rename --mode to --expect-mode for clarity

The flag asserts the detected mode rather than setting it, so the
name should reflect that. Reads more naturally in YAML where there's
no surrounding context.

Internal `assertMode` field name unchanged.

Author: theoephraim

.bumpy/ci-expect-mode-flag.md

@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': minor
+---
+
+Add `--expect-mode` flag to `bumpy ci release` for asserting the detected release mode (`version-pr` or `publish`). Enables split-job release workflows where each job fails loudly if the runtime state doesn't match what the job expects. Refactored `ReleaseOptions` to rename the existing `mode` field to `autoPublish: boolean` and add `assertMode`. `--expect-mode` and `--auto-publish` cannot be combined.

.bumpy/ci-mode-flag.md

@@ -58,7 +58,7 @@ jobs:
       - run: bun install
       # -------------------------------
 
-      - run: bunx @varlock/bumpy ci release --mode version-pr
+      - run: bunx @varlock/bumpy ci release --expect-mode version-pr
         env:
           GH_TOKEN: ${{ github.token }}
           BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # <- PAT so that version PR triggers CI
@@ -92,7 +92,7 @@ jobs:
 
       - run: echo "📦 Publishing packages:" && echo "${{ needs.plan.outputs.packages }}"
 
-      - run: bunx @varlock/bumpy ci release --mode publish
+      - run: bunx @varlock/bumpy ci release --expect-mode publish
         env:
           GH_TOKEN: ${{ github.token }}
           # We dont use the default GH token so that further workflows can be triggred by GH release events

.github/workflows/release.yaml

@@ -231,12 +231,12 @@ bumpy ci release --auto-publish
 bumpy ci release --auto-publish --tag beta
 ```
 
-| Flag              | Description                                                                                                                                                             |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--mode <mode>`   | Assert detected mode: `version-pr` or `publish`. Errors if the detected mode differs. Use to gate split-job workflows so a job can't silently fall into the wrong path. |
-| `--auto-publish`  | Version + publish directly instead of creating a PR                                                                                                                     |
-| `--tag <tag>`     | npm dist-tag (for `--auto-publish`)                                                                                                                                     |
-| `--branch <name>` | Version PR branch name (default: `bumpy/version-packages`)                                                                                                              |
+| Flag                   | Description                                                                                                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--expect-mode <mode>` | Assert detected mode: `version-pr` or `publish`. Errors if the detected mode differs. Use to gate split-job workflows so a job can't silently fall into the wrong path. |
+| `--auto-publish`       | Version + publish directly instead of creating a PR                                                                                                                     |
+| `--tag <tag>`          | npm dist-tag (for `--auto-publish`)                                                                                                                                     |
+| `--branch <name>`      | Version PR branch name (default: `bumpy/version-packages`)                                                                                                              |
 
 Requires `GH_TOKEN`. When `BUMPY_GH_TOKEN` is set, it is automatically used to push the version branch and create/edit the PR so that PR workflows trigger (see [GitHub Actions setup](github-actions.md#token-setup)).
 

docs/cli.md

@@ -80,7 +80,7 @@ jobs:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
       - run: bun install
-      - run: bunx @varlock/bumpy ci release --mode version-pr
+      - run: bunx @varlock/bumpy ci release --expect-mode version-pr
         env:
           GH_TOKEN: ${{ github.token }}
           BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # so the version PR triggers CI
@@ -106,7 +106,7 @@ jobs:
       - run: bun install
       # Expensive build steps that only matter before publish go here:
       # - run: bun run build
-      - run: bunx @varlock/bumpy ci release --mode publish
+      - run: bunx @varlock/bumpy ci release --expect-mode publish
         env:
           GH_TOKEN: ${{ github.token }}
           BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # so `release: published` workflows trigger
@@ -116,14 +116,22 @@ jobs:
 
 - `plan` runs `bumpy ci plan` to determine whether the current push should update the Version Packages PR (`version-pr`), publish unpublished packages (`publish`), or do nothing.
 - Only one of `version-pr` or `publish` runs per push. The other is skipped via the `if:` condition.
-- The `--mode` flag on `ci release` asserts that the detected mode matches what each job expects — if the runtime state ever drifts, the job fails loudly instead of silently doing the wrong thing.
+- The `--expect-mode` flag on `ci release` asserts that the detected mode matches what each job expects — if the runtime state ever drifts, the job fails loudly instead of silently doing the wrong thing.
 - Expensive build steps (compilation, tests, bundling) only run inside the `publish` job, so PR merges that just maintain the version PR stay cheap.
 
-### One-time setup
+### Required setup
 
-1. **Create the `publish` environment** in repo Settings → Environments. GitHub auto-creates it on the first run, but creating it manually lets you add protection rules (required reviewers, branch restrictions to `main` only) before any release runs.
-2. **Pin the npm trusted publisher to environment `publish`** on each package's npmjs.com settings → Trusted Publishers → GitHub Actions. Set the environment field to `publish`. This binds the OIDC trust to that specific environment — even if someone adds a rogue workflow file, npm will reject any token request that doesn't carry the `publish` environment claim.
-3. **Set `BUMPY_GH_TOKEN`** — see [Token setup](#token-setup) below.
+1. **Pin the npm trusted publisher to environment `publish`** on each package's npmjs.com settings → Trusted Publishers → GitHub Actions. Set the environment field to `publish`. This binds the OIDC trust to that specific environment — even if someone adds a rogue workflow file, npm will reject any token request that doesn't carry the `publish` environment claim.
+2. **Set `BUMPY_GH_TOKEN`** — see [Token setup](#token-setup) below.
+
+That's it — the `publish` environment auto-creates on the first publish run, so no manual GitHub setup is required.
+
+### Optional hardening: protection rules on the `publish` environment
+
+If you create the environment manually in repo Settings → Environments _before_ the first publish, you can attach protection rules:
+
+- **Restrict deployment branches to `main`** — recommended. Cheap defense in depth: non-`main` refs can never request an OIDC token from this environment, even if a workflow trigger is accidentally widened later.
+- **Required reviewers** — optional. Adds a manual approval gate before each publish. Usually redundant if `npmStaged: true` is enabled (below), since you already have a 2FA approval gate on npmjs.com.
 
 **Recommended publish config** — enable provenance and staged publishing for maximum security:
 
@@ -152,7 +160,7 @@ publish:
     contents: write
   steps:
     # ... checkout/setup-bun/setup-node/install steps ...
-    - run: bunx @varlock/bumpy ci release --mode publish
+    - run: bunx @varlock/bumpy ci release --expect-mode publish
       env:
         GH_TOKEN: ${{ github.token }}
         NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

docs/github-actions.md

@@ -117,19 +117,19 @@ async function main() {
           await ciPlanCommand(rootDir);
         } else if (subcommand === 'release') {
           const { ciReleaseCommand } = await import('./commands/ci.ts');
-          const assertModeFlag = ciFlags.mode;
+          const expectModeFlag = ciFlags['expect-mode'];
           const autoPublishFlag = ciFlags['auto-publish'] === true;
-          if (assertModeFlag !== undefined && assertModeFlag !== 'version-pr' && assertModeFlag !== 'publish') {
-            log.error(`Invalid --mode value: "${assertModeFlag}". Must be "version-pr" or "publish".`);
+          if (expectModeFlag !== undefined && expectModeFlag !== 'version-pr' && expectModeFlag !== 'publish') {
+            log.error(`Invalid --expect-mode value: "${expectModeFlag}". Must be "version-pr" or "publish".`);
             process.exit(1);
           }
-          if (assertModeFlag !== undefined && autoPublishFlag) {
-            log.error('--mode and --auto-publish cannot be used together.');
+          if (expectModeFlag !== undefined && autoPublishFlag) {
+            log.error('--expect-mode and --auto-publish cannot be used together.');
             process.exit(1);
           }
           await ciReleaseCommand(rootDir, {
             autoPublish: autoPublishFlag,
-            assertMode: assertModeFlag as 'version-pr' | 'publish' | undefined,
+            assertMode: expectModeFlag as 'version-pr' | 'publish' | undefined,
             tag: ciFlags.tag as string | undefined,
             branch: ciFlags.branch as string | undefined,
           });
@@ -250,7 +250,7 @@ function printHelp() {
     --no-fail               Warn only, never exit 1
 
   CI release options:
-    --mode <mode>           Assert detected mode: "version-pr" or "publish" (errors if mismatched)
+    --expect-mode <mode>    Assert detected mode: "version-pr" or "publish" (errors if mismatched)
     --auto-publish          Version + publish directly (default: create version PR)
     --tag <tag>             npm dist-tag for auto-publish
     --branch <name>         Branch name for version PR (default: bumpy/version-packages)

packages/bumpy/src/cli.ts

@@ -409,7 +409,7 @@ export async function ciReleaseCommand(rootDir: string, opts: ReleaseOptions): P
   if (opts.assertMode && opts.assertMode !== detectedMode) {
     throw new Error(
       `Expected mode "${opts.assertMode}" but detected "${detectedMode}". ` +
-        `Either remove --mode, or gate this step on the output of "bumpy ci plan".`,
+        `Either remove --expect-mode, or gate this step on the output of "bumpy ci plan".`,
     );
   }