feat(release): release from CI with one command

[Moltenship]

One command releases the nine @moltenship packages, and nobody confirms anything: asking for the release is the approval.

vp run release [<version>] [--dry-run]     # or /release [version] [--dry-run] in Claude Code

The laptop only triggers and watches. CI does the release, publishing through npm trusted publishing (OIDC) with provenance; no npm token exists, and there's no 2FA prompt, environment reviewer, npm login or version prompt.

A release, from the owner's side

1. vp run release (or /release).
2. The command checks the laptop side:
   • the checkout is main, clean and in sync with origin;
   • CI is green on HEAD (it waits while CI runs);
   • main's rules would let the workflow push.
3. It picks the version: the argument, or the suggestion from the Conventional Commits since the last tag. It never prompts.
4. It starts .github/workflows/release.yml on main and watches it (gh run watch). Then it prints the GitHub release's link, or the failed jobs and the end of their logs.
5. /release then rewrites the generated notes with gh release edit.

The workflow

One release at a time (concurrency: release, nothing cancelled).

Job	Permissions	What it does
check	id-token: write	Fails fast: - the version is above the packages'; - v<version> isn't on GitHub and npm doesn't have it; - the run is on main, on the commit the command checked; - no release landed on main while the run waited; - every package trusts this workflow: it trades the OIDC token for a publish token, as npm publish does, and throws the token away.
gate	read	In the runner only: bumps the nine manifests, commits chore(release): v<version> and tags it. Then runs release:gate on that commit: the full tier, Firefox included, with a strict dry run. Writes the notes with changelogithub and bundles the commit and tag for the next jobs.
publish	id-token: write, no install scripts	npm publish --provenance on the tarballs the gate checked, through trusted publishing, skipping any npm already serves.
finish	contents: write, the only writer	Waits for npm to serve every package (integrity, dist-tag, trusted publisher and provenance). Then pushes the tag first, then main, merging like a PR if main moved, and writes the GitHub release, marked as a pre-release for an RC.
install	read	Installs from npm into clean Vite and Next.js apps (registry:e2e).

Dry runs and hardening:

• A dry run skips publish and finish. It runs publish-dry-run and finish-dry-run instead, which have no OIDC token and no write access, and queues apart from real releases.
• The jobs that hold credentials pin their actions to commits, use no cache, install without scripts, and run tools/release/src/ci.ts with node rather than through Vite Task.

Why workflow_dispatch and not antfu's tag push: with a tag push, the laptop pushes the bump and the tag before anything checks them, so a red gate leaves both behind. Here nothing leaves the runners until the gate has passed, and main gets the version only once npm serves it. That matters because the docs site's registry follows main.

Resuming:

• Rerunning vp run release <version> after a run failed after publishing started runs that run's failed jobs again (gh run rerun --failed). That reuses the same commit and tarballs, kept 30 days, so npm never gets two builds of one version. This needs no checkout.
• A run that failed before publishing is left alone, and a new run starts from main.
• A running release is watched; a finished one is just reported.
• A bare vp run release finishes the packages' own version while its release isn't done. When the only commits since the last tag are the release's own, it stops with "Nothing to release" instead of publishing an empty version.
• It won't start a release while another one is running.

Trust and the zero-confirmation trade-off

• What's given up: no person looks at a release before it ships.
• What stands in:
  • only the owner can push to or dispatch on main;
  • each package's trusted publisher is pinned to Moltenship/time and release.yml;
  • optionally, "Require two-factor authentication and disallow tokens" means no token can publish at all. Trusted publishing isn't a token, so it keeps working.
• No downgrade from rc.1: rc.1 went out with a token plus --provenance (no trusted publisher). pnpm's trustPolicy: no-downgrade ranks trusted publisher + provenance above provenance alone (trustChecks.ts), so releases from this workflow aren't a downgrade. npm has no such check.

Details and sources: docs/internal/research/release-flow.md, which has a new section on this decision.

The owner's one-time setup (also in docs/internal/releasing.md)

Do it within 48 hours before the first release. Since 2 Oct 2026, npm drops a trusted publisher that hasn't published within 48 hours of being created.

1. A trusted publisher on each of the nine packages. Two ways:
   • Run vp run release:trust. It runs npm trust github <pkg> --file release.yml --repo Moltenship/time --allow-publish --yes for each package; it needs npm 11.15 or later. The first call asks for 2FA; tick "skip 2FA for the next 5 minutes" and the other eight go through.
   • Or, on npmjs.com, open each package's Settings, then Trusted publishing, then GitHub Actions, and enter:
     • organization or user: Moltenship;
     • repository: time;
     • workflow filename: release.yml;
     • environment: blank.
2. Remove the token. Delete the repository's npm environment and its NPM_TOKEN secret, and revoke the token on npmjs.com.
3. Optional: set each package to "Require two-factor authentication and disallow tokens". vp run release:trust --disallow-tokens does it with npm access set mfa=publish.

Removed from the first version of this PR

• staging and approval;
• the npm login, terminal and version-prompt preflight;
• the local gate's state file, undo and signal handling;
• the macOS 27 Firefox wait, now unneeded because the gate runs Firefox on a fresh runner;
• terminal.sh;
• the CI concurrency change;
• the release:version, release:publish, release:published and release:github tasks, plus the old release.yml's token-based jobs.

Kept

• changelogithub notes and the frozen CHANGELOG;
• the /release skill in the repo with disable-model-invocation: true (rewritten for the CI flow);
• the research note;
• CI's on-demand release-gate job.

Tests

• Unit tests: 150 pass, covering:
  • nextStep, publishStarted and the version choice's rules;
  • the check job's problems;
  • npm's exchange answers;
  • the trusted-publisher setup;
  • the workflow contract: jobs, permissions, pins, the dry-run jobs and CI parity;
  • the publish guard and the npm check.
• vp run ready:full passed locally at e90d41c1. vp run ready passed at the final commit, 5354a5bb.
• CI's release-gate is green on e90d41c1 (job) and on the final commit, 5354a5bb (job).
• Dry runs of the release workflow, each started by vp run release --dry-run from this branch:
  • 38705122632 on 974733f9, the first design;
  • 38708797626 on c147cee0, with the jobs that have no credentials;
  • 38718528054 on the final commit, 5354a5bb, with the version picked by the command (1.0.0-rc.2).
• What the dry runs did:
  • check: npm answered 404 OIDC token exchange error - package not found for all nine, as expected before the setup, and the run reported it.
  • gate: committed and tagged in the runner, and the gate passed.
  • publish dry run: npm 11.20.0 and the nine tarballs, with provenance.
  • finish dry run: the fast-forward plan and the notes.

Review

Claude Opus 5.5 (xhigh) reviewed this redesign in rounds 5 to 7, after four rounds on the first one. It found 1 blocker, 5 should-fix and 11 nits, all fixed. The final round confirmed nothing open. One nit is left by choice: a dry run with no version, started while a real release is unfinished, picks that version and stops at check with a clear message.

Untested live

• A real publish through trusted publishing: no trusted publisher exists yet, and the dry run doesn't publish. The check job's exchange did reach npm, which answered 404 OIDC token exchange error - package not found for all nine packages, as expected before the setup.
• A real push to main and a GitHub release from the workflow: the dry run only proves the job can push the tag (git push --dry-run).
• A rerun of failed jobs after a partial publish.

Refs #207, #146, #47

🤖 Generated with Claude Code