feat: add bumpy publish reopen for rejected staged publishes

npm exposes no public 'rejected' signal (a rejected stage is indistinguishable
from a pending one via npm info), and the finalize job is credential-free, so
bumpy can't auto-detect a rejection. After `npm stage reject`, run
`bumpy publish reopen <name@version>`: it flips the staged target back to failed,
which rejoins the fix-forward path — the tag un-freezes and the next publish
re-stages. Abandon instead by not reopening (the next version supersedes the draft).

Adds the command + CLI wiring, tests, and docs (cli.md, configuration.md,
github-actions.md rejection subsection).

Author: theoephraim

docs/cli.md

@@ -128,7 +128,23 @@ bumpy publish finalize --dry-run       # show what would be finalized
 | `[name@version]` | Finalize only this release; omit to reconcile all staged releases |
 | `--dry-run`      | Report what would be finalized without editing any releases       |
 
-Idempotent — a version that's still staged is left untouched — so it's safe to run on a schedule, manually, or from an approval webhook. See [the finalize workflow](github-actions.md#staged-publishing-finalize-workflow) for wiring it into CI.
+Idempotent — a version that's still staged is left untouched — so it's safe to run on a schedule, manually, or from an approval webhook. See [Staged publishing (finalizing a release)](github-actions.md#staged-publishing-finalizing-a-release) for wiring it into CI.
+
+## `bumpy publish reopen`
+
+Reopen a [staged](configuration.md#staged-publishing) release whose staged publish was **rejected** on npm. Rejection isn't publicly observable (a rejected stage looks the same as a pending one to the registry), so bumpy can't detect it — run this after `npm stage reject <stage-id>` to tell it.
+
+```bash
+npm stage reject <stage-id>          # reject on npm
+bumpy publish reopen @myorg/pkg@1.2.3 # then reopen the release
+```
+
+| Argument / Flag | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `name@version`  | The rejected release to reopen (required)            |
+| `--dry-run`     | Report what would change without editing the release |
+
+It flips the staged target back to **failed**, which rejoins the fix-forward path: the 🟡 marker clears, the version tag un-freezes, and the next `bumpy publish` re-stages the same version. To _abandon_ the version instead, don't reopen — ship a different version and the draft is superseded.
 
 ## `bumpy check`
 

docs/configuration.md

@@ -121,6 +121,8 @@ Staging is an **npm-registry feature** — it only applies to packages published
 
 Because a staged package isn't live yet, bumpy does **not** mark the release as published: the publish target shows as **🟡 staged, awaiting approval** and the GitHub release stays a **draft** (so the `release: published` event doesn't fire prematurely). Going live is a two-step handoff: you **approve on npm** (`npm stage approve <stage-id>` — the 2FA gate), then run **`bumpy publish finalize`** to update the GitHub release (flip it to ✅ published, link the live package). You can run finalize by hand or on a schedule — see [Staged publishing (finalizing a release)](github-actions.md#staged-publishing-finalizing-a-release) for the full lifecycle and both setups.
 
+If you instead **reject** a stage on npm (`npm stage reject <stage-id>`), run **`bumpy publish reopen <name@version>`** — bumpy can't detect a rejection on its own, and this reopens the release so the next publish re-stages the fixed build. To abandon the version entirely, don't reopen; the next version bump supersedes the draft.
+
 ### Version PR config
 
 The `versionPr` object customizes the PR that `bumpy ci release` creates:

docs/github-actions.md

@@ -411,6 +411,19 @@ Because finalize decides what to publish by probing the registry (not from the p
 >
 > For most repos you won't need this — the no-payload nudge above is the norm.
 
+### If a staged publish is rejected
+
+Approval is publicly observable (the package goes live, and finalize notices), but **rejection is not** — a rejected stage looks identical to a still-pending one to `npm info` (both are simply "not live"). So bumpy can't auto-detect a rejection, and the release would otherwise sit at 🟡 forever. When you reject a stage, tell bumpy:
+
+```bash
+npm stage reject <stage-id>              # reject on npm
+bumpy publish reopen my-pkg@1.2.3        # tell bumpy — reopens the release for re-publish
+```
+
+`publish reopen` flips the staged target back to **failed**, which rejoins the normal fix-forward path: the 🟡 marker clears, the version tag un-freezes, and the **next `bumpy publish` re-stages the same version** — so push your fix and let CI re-stage it. (If you're rejecting to _abandon_ the version rather than redo it, don't reopen — just ship a different version and the draft gets superseded automatically.)
+
+If you approve/reject through tooling, have it run `bumpy publish reopen <tag>` (e.g. via a `repository_dispatch`) at rejection time, the mirror of the finalize nudge.
+
 ## Advanced: per-package conditional builds
 
 If you have one expensive package whose build you only want to run when that package itself is being released, use `ci plan`'s `packages` output to gate per-package steps:

packages/bumpy/src/cli.ts

@@ -222,6 +222,21 @@ async function main() {
           break;
         }
 
+        // `bumpy publish reopen <name@version>` — after `npm stage reject`, flip a rejected
+        // staged release back to failed so the next publish re-stages it.
+        if (args[1] === 'reopen') {
+          const reopenFlags = parseFlags(args.slice(2));
+          const tagArg = args[2] && !args[2].startsWith('--') ? args[2] : undefined;
+          const tag = (reopenFlags.tag as string | undefined) ?? tagArg;
+          if (!tag) {
+            log.error('`bumpy publish reopen` requires a release: `bumpy publish reopen <name@version>`');
+            process.exit(1);
+          }
+          const { reopenCommand } = await import('./commands/reopen.ts');
+          await reopenCommand(rootDir, { tag, dryRun: reopenFlags['dry-run'] === true });
+          break;
+        }
+
         const { publishCommand } = await import('./commands/publish.ts');
         if (flags.snapshot === true) {
           log.error('--snapshot requires a name, e.g. `bumpy publish --snapshot pr-123`.');
@@ -292,6 +307,8 @@ function printHelp() {
                             (--snapshot <name>: transient preview publish to a throwaway dist-tag)
     publish finalize        Finalize staged releases that have been approved and gone live
                             ([name@version]: finalize one release; otherwise reconcile all staged)
+    publish reopen          Reopen a staged release rejected on npm so it re-stages on next publish
+                            (name@version required; run after "npm stage reject")
     ci check                PR check — report pending releases, comment on PR
     ci comment              Post a pre-rendered comment (workflow_run half of the fork-comment split)
     ci plan                 Report what ci release would do (JSON + GitHub Actions outputs)

packages/bumpy/src/commands/reopen.ts

@@ -0,0 +1,63 @@
+import { log, colorize } from '../utils/logger.ts';
+import { isGhAvailable, findReleaseByTag, updateReleaseBody, updateReleaseBodyStatus } from '../core/github-release.ts';
+
+export interface ReopenCommandOptions {
+  /** The rejected release to reopen (`name@version`). */
+  tag: string;
+  dryRun?: boolean;
+}
+
+/**
+ * Reopen a staged release whose staged publish was rejected on npm.
+ *
+ * npm exposes no public "rejected" signal (a rejected stage looks identical to a still-pending
+ * one — both are simply not live), and the finalize job is intentionally credential-free, so
+ * bumpy can't auto-detect a rejection. Instead the maintainer (or their approval tooling) runs
+ * this after `npm stage reject <stage-id>`.
+ *
+ * It flips the staged target(s) back to `failed`, which reuses bumpy's existing fix-forward
+ * path: the stale 🟡 clears, the version tag un-freezes (a `failed` target isn't "shipped"),
+ * and the next `bumpy publish` re-stages the same version. To abandon the version instead, just
+ * don't reopen — the next version bump supersedes the draft.
+ */
+export async function reopenCommand(rootDir: string, opts: ReopenCommandOptions): Promise<void> {
+  if (!isGhAvailable()) {
+    log.error('gh CLI not found — cannot reopen a staged release.');
+    process.exit(1);
+  }
+
+  const info = await findReleaseByTag(opts.tag, rootDir);
+  if (!info) {
+    log.error(`No GitHub release found for ${opts.tag}.`);
+    process.exit(1);
+  }
+  const meta = info.metadata;
+  if (!meta) {
+    log.error(`${opts.tag} has no bumpy metadata — nothing to reopen.`);
+    process.exit(1);
+  }
+
+  const stagedTargets = Object.entries(meta.targets).filter(([, s]) => s.status === 'staged');
+  if (stagedTargets.length === 0) {
+    log.info(`${opts.tag} has no staged targets — nothing to reopen.`);
+    return;
+  }
+
+  for (const [targetName, state] of stagedTargets) {
+    meta.targets[targetName] = {
+      status: 'failed',
+      error: 'staged publish was rejected — will re-stage on next publish',
+      lastAttempt: new Date().toISOString(),
+      ...(state.label ? { label: state.label } : {}),
+    };
+  }
+
+  if (opts.dryRun) {
+    log.dim(`  Would reopen ${opts.tag} — ${stagedTargets.length} staged target(s) → failed`);
+    return;
+  }
+
+  const updatedBody = updateReleaseBodyStatus(info.body, meta);
+  await updateReleaseBody(opts.tag, updatedBody, rootDir);
+  log.success(`  Reopened ${colorize(opts.tag, 'cyan')} — will re-stage on the next publish run`);
+}

packages/bumpy/test/core/reopen.test.ts

@@ -0,0 +1,63 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { installShellMock, uninstallShellMock, getCallsMatching, addMockRule } from '../helpers-shell-mock.ts';
+import { composeReleaseBody, parseReleaseMetadata, type ReleaseMetadata } from '../../src/core/github-release.ts';
+import { reopenCommand } from '../../src/commands/reopen.ts';
+
+/** Mock `gh release view <tag> --json ...` to return a release with the given body. */
+function mockReleaseView(body: string, isDraft = true) {
+  addMockRule({
+    match: /^gh release view/,
+    response: JSON.stringify({ tagName: 'pkg-a@1.2.3', name: 'pkg-a v1.2.3', body, isDraft }),
+  });
+}
+
+describe('reopenCommand', () => {
+  beforeEach(() => installShellMock());
+  afterEach(() => uninstallShellMock());
+
+  const stagedMeta: ReleaseMetadata = {
+    version: '1.2.3',
+    targets: { npm: { status: 'staged', stageId: 'uuid-1', stagedAt: '2026-01-01T00:00:00Z' } },
+  };
+
+  test('flips a staged target to failed and edits the release body', async () => {
+    mockReleaseView(composeReleaseBody('- A change', stagedMeta));
+    addMockRule({ match: /^gh release edit/, response: '' });
+
+    await reopenCommand('/tmp/x', { tag: 'pkg-a@1.2.3' });
+
+    const editCalls = getCallsMatching('gh release edit');
+    expect(editCalls.length).toBe(1);
+
+    // The edited body's metadata should now show the target as failed (rejected).
+    const notesIdx = editCalls[0]!.args.indexOf('--notes');
+    const newBody = editCalls[0]!.args[notesIdx + 1]!;
+    const meta = parseReleaseMetadata(newBody)!;
+    expect(meta.targets.npm!.status).toBe('failed');
+    expect(meta.targets.npm!.error).toContain('rejected');
+    // No longer staged — the stale 🟡 marker is gone.
+    expect(newBody).not.toContain('🟡');
+  });
+
+  test('dry-run does not edit the release', async () => {
+    mockReleaseView(composeReleaseBody('- A change', stagedMeta));
+    addMockRule({ match: /^gh release edit/, response: '' });
+
+    await reopenCommand('/tmp/x', { tag: 'pkg-a@1.2.3', dryRun: true });
+
+    expect(getCallsMatching('gh release edit')).toHaveLength(0);
+  });
+
+  test('no-ops when the release has no staged targets', async () => {
+    const liveMeta: ReleaseMetadata = {
+      version: '1.2.3',
+      targets: { npm: { status: 'success', url: 'https://npmjs.com/package/pkg-a/v/1.2.3' } },
+    };
+    mockReleaseView(composeReleaseBody('- A change', liveMeta));
+    addMockRule({ match: /^gh release edit/, response: '' });
+
+    await reopenCommand('/tmp/x', { tag: 'pkg-a@1.2.3' });
+
+    expect(getCallsMatching('gh release edit')).toHaveLength(0);
+  });
+});