chore: add release prepare command

[jrusso1020]

What

• Add bun run release:prepare <version> as the maintainer-facing stable release entrypoint.
• Make the first run draft missing changelog artifacts and intentionally exit before tagging; rerunning after manual review delegates to set-version.
• Tighten the direct set-version guard so stable releases also fail when generated TODO changelog copy is still present.
• Update maintainer docs to recommend release:prepare while keeping changelog:draft as the lower-level regeneration tool.

Why

Stable releases should be hard to run without reviewed GitHub release notes and Mintlify changelog copy. This keeps the existing manual rewrite step, but makes the expected path one command that engineers can rerun after review.

How

• Added scripts/release-prepare.ts with parsing, draft/review/set-version action selection, and command forwarding.
• Added focused script tests for parser behavior, action selection, command forwarding, and TODO detection.
• Extracted shared script CLI parsing helpers so changelog:draft and release:prepare use the same option handling.
• Adjusted changelog:draft --write so an existing release file is left unchanged unless --force is passed, while still allowing a missing docs entry to be added.

Test plan

• Unit tests added/updated: bun run test:scripts
• Format check: bun run format:check
• Lint: bun run lint
• Typecheck: bun run --filter '*' typecheck
• Fallow audit: bunx fallow audit --base origin/main --fail-on-issues
• Manual CLI checks: bun run release:prepare --help; bun run set-version 9.9.9 fails before mutation when changelog artifacts are missing
• Documentation updated

[jrusso1020]

• chore: add release prepare command #1165 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jun 2, 2026, 11:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[miguel-heygen]

LGTM. Clean follow-up to #1164.

The two-run model (first run drafts + exits non-zero, second run validates reviewed artifacts + delegates to set-version) is the right UX pattern — the enforced pause is the whole point, and exiting non-zero stops any chained commands without needing a flag.

Solid:

• TODO marker check in both release:prepare AND set-version closes the 'engineer skips prepare and uses set-version directly' gap.
• cli-options.ts extraction means argument parsing is in one place — draft-changelog and release-prepare won't drift.
• 22 focused script tests covering parser, action selection, command forwarding, and TODO detection.
• Docs updated consistently across CONTRIBUTING.md, changelog-process.mdx, and release-channels.mdx.

No issues.

[vanceingalls]

Additive review — the two-run UX model, TODO-marker check at both layers, cli-options extraction, and test coverage are all solid. Below are gaps not yet in the review.

Strengths

• readNextArg guarding --flag as the next arg value is a subtle footgun that was correctly ported during the refactor. ✓
• docsChangelogEntryHasGeneratedTodo scopes the TODO check to the matching <Update> entry, not the whole file — a reviewed entry and an unreviewed sibling don't cross-contaminate. ✓
• prependDocsUpdate idempotency (label= guard) makes the writeReleaseNotes early-return on EEXIST safe — rerunning changelog:draft --write doesn't produce duplicate docs entries. The behavior change (exit-1 → log+return) is correct. ✓

Important nit

draft-changelog.ts:433, release-prepare.ts:744, and the pre-existing set-version.ts all call validateCliVersion with their own regex, and they diverge:

• draft-changelog.ts: [0-9A-Za-z.-] — explicit charset, no underscore
• release-prepare.ts: [\w.] — \w includes underscore
• set-version.ts: [\w.] — same as release-prepare

A version like 1.2.3-my_build passes release-prepare and set-version but fails draft-changelog. Unlikely to bite in practice (semver prereleases don't use underscores), but the extraction was the natural moment to align them. Worth a one-liner fix on release-prepare.ts:744 to use [0-9A-Za-z.-], or better, export a shared SEMVER_PRERELEASE_PATTERN from cli-options.ts.

Nit

The --force flag on release:prepare is only consumed in the "draft" action path, which fires only when the release file is missing — and a missing file never needs --force. The flag is reachable in the rare split-state (release file exists, docs entry absent), but that's non-obvious. A short comment would help the next maintainer.

---

CI: baseRefName is main — not stacked. All required checks green. ✓

LGTM.

— Vai

[jrusso1020]

Addressed the semver regex nit in the latest push: draft-changelog, release:prepare, and set-version now all use the shared CLI_SEMVER_PATTERN from scripts/cli-options.ts, and scripts/cli-options.test.ts covers rejecting underscores in prerelease versions.

[vanceingalls]

Nit addressed — CLI_SEMVER_PATTERN exported from cli-options.ts and used by all three scripts (draft-changelog, release-prepare, set-version). Test confirms 1.2.3-alpha_1 (underscore) is correctly rejected by the shared pattern. LGTM.

— Vai

[jrusso1020]

Merge activity

• Jun 3, 12:34 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 3, 12:34 AM UTC: @jrusso1020 merged this pull request with Graphite.