distribe

What this skill does

# Distribe — Tomitribe Release Distribution CLI

Internal Tomitribe CLI used across the release / CVE / customer-notification pipeline. Built from the `tomitribe/distribe` Maven multi-module project; the fat-jar entry point is `distribe-cli/target/distribe`.

## Discovering commands

Distribe is built on Crest, so the CLI is self-documenting. **Always prefer the built-in help over guessing**:

```bash
distribe help --all                 # flat list of every command + one-line description
distribe help <group>               # subcommands in a group (e.g. distribe help jenkins)
distribe help <group> <subcommand>  # full usage, flags, semantics, examples for one command
```

`distribe help <group> <subcommand>` is the source of truth — it ships with the build and reflects the exact flags compiled in. When unsure of an option or its default, read it from `help` rather than assuming.

## Locating the binary

Distribe ships as two executables in a `distribe` checkout:

- `distribe-cli/target/distribe` — the full CLI used by the release pipeline; this is the one referenced everywhere below as `distribe`.
- `distribe-lite-cli/target/distribe-lite` — a smaller variant for restricted environments.

If the binary is missing, the user has not built distribe yet. Ask before silently running `mvn install` — it's a long build.

## The `--config` flag

Almost every command takes `--config=<name>`. Profiles live under `~/.tribe/distribe/` and are managed via `distribe config`:

```bash
distribe config list                       # show all profiles
distribe config add <name>  --<key>=<val>  # create a new profile
distribe config set <name>  --<key>=<val>  # update a key on a profile
distribe config export <name>              # encrypted dump of a profile
distribe config import <file>              # restore from an exported profile
distribe config remove <name>
```

Profiles carry credentials for AWS, Nexus, Salesforce, Zendesk, Jenkins, GitHub. The CLI default is `--config=default`; teams typically maintain version-suffixed variants (e.g. `default-<distribe-version>`) so the right environment is paired with the right CLI build. **Ask the user which profile to use** rather than assuming. Never paste credentials into chat — refer them to `config set`.

---

## Top-level command groups

| Group         | Purpose                                                                 |
|---------------|-------------------------------------------------------------------------|
| `activity`    | Track / record release activity for reporting                           |
| `apigateway`  | AWS API Gateway helpers                                                 |
| `config`      | Manage local distribe profiles                                          |
| `customer`    | Customer / subscription operations (list, releases, mappings, extend)   |
| `cve`         | CVE customer fan-out, notifications, ticket bookkeeping                 |
| `github`      | GitHub helpers (onboard / sync forks)                                   |
| `jenkins`     | Trigger / inspect / configure Tomitribe CI jobs                         |
| `job`         | Cron-like scheduling of distribe commands                               |
| `jwt`         | Subscription JWT operations                                             |
| `lambda`      | Deploy / promote AWS Lambdas                                            |
| `license`     | License management                                                      |
| `nexus`       | Nexus repository queries + CVE template generation                      |
| `param`       | SSM Parameter Store helpers                                             |
| `patch`       | Patch utilities (e.g. stale-ref detection across poms)                  |
| `reporting`   | GA4 / BigQuery analytics & rollups                                      |
| `s3`          | Release distribution: archive, distribute, changelog, hashes, batch     |
| `sns`         | SNS notification helpers                                                |
| `stripe`      | Stripe billing helpers (coupons, codes, price/product verification)     |
| `token`       | Token generation                                                        |
| `weaver`      | Bytecode weaving runner                                                 |
| `zendesk`     | Download-page articles, tickets, orgs, segments, admin contacts         |

`distribe help <group>` lists the subcommands; `distribe help <group> <subcommand>` shows full options.

---

## `jenkins` — CI orchestration

```bash
# Trigger a PR build (manual-pr-trigger job)
distribe jenkins trigger <product> <branch> --pr=<PR_NUMBER>

# Trigger a stable branch build (post-merge smoke)
distribe jenkins trigger <product> <branch> --stable

# Snapshot a build's status (named flags, NOT positional)
distribe jenkins status --product=<product> --branch=<branch> --pr=<PR>
distribe jenkins status --product=<product> --branch=<branch> --pr=<PR> --build=<N>
distribe jenkins status --url=<full-build-url>
distribe jenkins status --product=<product> --branch=<branch> --pr=<PR> --watch  # poll until done

# Console output for a specific build
distribe jenkins console --url=<BUILD_URL>

# Read / write a job's config.xml
distribe jenkins get-config <job-path>
distribe jenkins set-config <job-path> < new.xml

# Create the standard pair of jobs (stable + manual-pr-trigger) for a new branch
distribe jenkins create-jobs <product> <branch>

# Run stable + manual-PR-trigger in parallel and apply the flaky-comparison matrix
distribe jenkins flaky-compare <product> <branch> --pr=<PR_NUMBER>
```

**Key semantics from `help`**:

- `jenkins trigger` polls the queue until the build URL appears, then returns *synchronously* with both queue and build URLs.
- With `--pr=<N>`, the Jenkins build displayName is also set to `PR #<N> - <PR title>` (fetched via `gh pr view`).
- `jenkins status` defaults to a terse snapshot (result + build-id + queued-at). Add `--watch` to poll up to ~90 minutes for completion plus a test-failure digest with an environmental-vs-test-specific heuristic.
- `jenkins flaky-compare` triggers both jobs in parallel, watches both, and applies the 4-cell decision matrix (stable green / red × PR green / red) automatically — replaces the two-window Jenkins-UI dance.

**Product / branch naming**: `<product>` is the Jenkins folder (e.g. `tomcat`, `tomee`, `activemq`). `<branch>` is the **Jenkins job basename**, which for Tomcat is prefixed `tomcat-` even when the git branch is not:

| Product | Git branch          | Jenkins branch name (what `--branch` wants) |
|---------|---------------------|---------------------------------------------|
| Tomcat  | `8.5.x-TT.x`        | `tomcat-8.5.x-TT.x`                         |
| Tomcat  | `9.0.x-TT.x`        | `tomcat-9.0.x-TT.x`                         |
| Tomcat  | `tomcat-10.0.x-TT.x`| `tomcat-10.0.x-TT.x`                        |
| Tomcat  | `tomcat-10.1.x-TT.x`| `tomcat-10.1.x-TT.x`                        |
| Tomcat  | `11.0.x-TT.x`       | `tomcat-11.0.x-TT.x`                        |

`trigger` is **positional** (`trigger <product> <branch>`); `status` and `console` are **named flags** (`--product`, `--branch`, `--pr`, `--url`). Mixing them up returns `Excess arguments: ...`.

---

## `cve` — CVE customer fan-out

The CVE flow is staged. Stage numbers below mirror the internal CVE process doc.

```bash
# Stage 3 (preparation): read a GitHub issue and build the per-CVE working directory.
# Issue-driven: product, branches, and CVE-IDs are inferred from the issue body.
distribe cve customers <ISSUE_NUMBER>

# Override the inferred branches (subset re-run, or force a branch not yet in the issue)
distribe cve customers <ISSUE_NUMBER> --branches=8.0,9.0,10.0

# Override CVE IDs / versions when the issue body doesn't carry them canonically
distribe cve customers <ISSUE_NUMBER> --cve-ids-override=CVE-2026-42402,CVE-2026-42403 --versions=8.0.17-TT.19

# Override th