[goosewobbler]

Description

version --json and publish --json now print the same JSON envelope as every other command, and both accept --output <path>. notes and publish unwrap an envelope on input, so the stages still chain. This finishes the envelope work in #544: notes has no JSON output, so every --json command now prints an envelope.

--output resolves against the directory releasekit runs in, not --project-dir, the same as release --output.

Chaining the stages

• Unwrapping. unwrapEnvelope (core) runs inside notes' parseVersionOutput and publish's parseInput, so string, file and stdin input are all covered.

• Bare input still works. A plain VersionOutput, such as a hand-written file or output from an older releasekit, passes through unchanged.

• Failed upstream stages. Feeding a failed stage's envelope forward now fails as an input error (exit 3) that names that stage's code and message, instead of a schema error about missing fields:

  code: INPUT_PARSE_ERROR
  message: Failed to parse version output: Upstream releasekit stage failed (GENERAL_ERROR): …
  

• Chain through a file. notes reads the VersionOutput but doesn't print it, so it can't sit in a pipe. The three-stage stdin pipe the docs showed never worked; version --json | publish does. publish commits only the files version changed plus whatever is staged, so stage the changelog first:

  releasekit version --output version.json
  releasekit notes --input version.json
  git add CHANGELOG.md
  releasekit publish --input version.json

Other changes

• errorEnvelope takes optional data and changed.
  • Without them, publish's failure envelope would drop partialOutput (what was published before the failure), and would report changed: false after a partial publish.
  • The envelope has no field for the failed stage, so the error message names it.
  • schemaVersion stays 1, because readers that ignore data on an error are unaffected.
• publishDidChange moved to @releasekit/publish, so the publish CLI and standing-pr publish decide changed the same way.
  • Only a registry publish or a release commit made by this run counts. Tags, pushes and GitHub releases that already existed all report success without changing anything.
  • standing-pr publish never commits, so for it only registry publishes count.
• One envelope writer. writeEnvelope and writeErrorEnvelope in core's cli.ts are shared by version, publish and release.
  • Printing for --json needs a one-line noConsole suppression (chore(biome): flag console in package source #668's rule).
  • A warning about an unwritable error-envelope path goes through the logger.

Breaking changes

• --json output shape. Scripts that read version --json or publish --json must now read .data, e.g. jq '.data.updates[]'. An older standalone @releasekit/notes or @releasekit/publish rejects the envelope, so keep all the packages on one version. Worth a callout in the release notes.
• Exit codes follow the documented table (via exitCodeForError).
  • Before: version exited 1 for every failure, and publish exited 9 for any publish-package error and 1 for anything else.
  • Now: a publish config error exits 2, bad or failed-upstream input exits 3, and pipeline failures still exit 9.
• release and standing-pr exit codes. These already report a stage's own error code (fix(core): recognise ReleaseKitError across bundled copies of core #651). With the expanded table their exit codes follow its family too; for example, a publish-stage PIPELINE_STAGE_ERROR now exits 9. docs/cli.md says so.

The repo's workflows and the Action only check for a non-zero exit. On 0.x a ! bumps the minor version, so this ships as 0.42.0.

Not in this PR

• The version README keeps only this PR's flag changes: the --json envelope wording and the new --output row. Unrelated fixes to its flag table moved to docs(version): match the README flag table to the CLI #677.
• Found in review and filed separately:
  • release --json drops a publish failure's partial output and failed stage that publish --json reports #700: release --json drops a publish failure's partial output and stage.
  • Envelope errors[].category isn't the coarse category the docs promise #699: the envelope's category isn't coarse enough.
  • version --project-dir <relative path> loads the config from the wrong directory and silently uses defaults #698: a relative version --project-dir loads the wrong config.
  • Standalone publish can’t resume after a partial failure #707: re-running a partially failed publish stops at the commit, so it can't resume; docs/cli.md now says so.
• publish --input dropping updates[].tag and baselineTags (publish --input drops per-package tags and baseline tags from the version output #675) was fixed on main by fix(publish): keep per-package and baseline tags in --input #684.

Related Issue(s)

Part of #544.

Type of Change

• feat — New feature
• fix — Bug fix
• docs — Documentation change
• refactor — Code refactoring
• test — Adding or updating tests
• chore — Maintenance, dependencies, tooling
• Breaking change — Requires major version bump

Scope

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/release
• @releasekit/config
• @releasekit/core
• CI / workflows
• Root / monorepo

Checklist

• Lint passes (pnpm lint)
• Tests pass (pnpm test)
• Typecheck passes (pnpm typecheck)
• Documentation updated (if applicable)
• Breaking changes noted in description

Testing Notes

• Built CLIs, run by hand:
  • publish reading an enveloped file, a bare file, a failed upstream envelope, and a schemaVersion: 2 envelope.
  • notes reading an enveloped payload and a failed one.
  • version --json | publish, and an unwritable --output.
  • The documented file-based chain, end to end. The release commit holds the bumped manifest and the staged changelog. Re-running on the same tree stops at the git-commit stage, as the docs now say.
• Unit tests drive the real commands:
  • A version --json failure exits by its code's family; for example, --stable --prerelease gives an INPUT_ERROR envelope.
  • publish --output on a pipeline failure writes the partial output to the file.
  • publish --input holding a failed upstream envelope exits 3.
  • changed is checked for publish.
  • version --output works on its own and with --project-dir.
  • Each package checks that every one of its error codes maps to an exit-code family.
• Suites: typecheck and lint are clean. The core, publish, version, notes and release unit suites pass, and so do version's integration suite (in CI since test(version): run the integration suite in CI and fix its stale sync-tags fixture #685) and the root integration suite.
• Merge with main: it merges cleanly with main after fix(version)!: sync every committed Cargo.lock that records a bumped crate #674. The merged exit-code table keeps fix(version)!: sync every committed Cargo.lock that records a bumped crate #674's CARGO_LOCK_SYNC_ERROR in the version-error family.

🤖 Generated with Claude Code

[github-actions]

Standing release PR: #614 · v0.42.0 queued (4 packages) · open 82d 19h 53m · ✅ ready to merge

Release Preview — v0.41.2 → v0.42.0

Note: Labels on this PR are advisory in standing-pr mode. Bumps come from conventional commits in the standing PR; override by editing labels on the standing PR itself. Add release:immediate to bypass the standing PR and release this PR directly.

These changes will be added to the release PR (#614) when merged:

Changelog

monorepo 0.41.2 → 0.42.0

Added

• envelope the version and publish commands, unwrap on the pipe (cli)

Changed

• link to the chaining section from architecture, simplify envelope comments
• tighten the envelope docs and comments
• trim the envelope doc comments; drop a stale e2e helper note (core)
• write --output through the real JSON writer (version)
• add braces to every single-statement body
• point --json stability at schemaVersion; keep the version README to this PR's flags
• cover the version and publish failure paths through the commands (cli)
• share one error-envelope writer and trim review leftovers (cli)
• release and standing-pr now report a stage's own error code (cli)
• drop the duplicate publish exit test and the notes exit clause
• drop low-value review additions
• describe notes' parse check precisely; name a lost --output result (cli)
• scope the exit-code contract to the commands it holds for (cli)

Fixed

• commit a hybrid package's Cargo.toml in a direct release (release) (PR #691 · closes #678)
• suppress per line instead of exempting cli.ts; test --output alone (cli)
• don't crash the error path on an unwritable --output; scope the notes exit claim (cli)
• correct the chaining, retry and exit-code docs; move the --output test into CI (cli)
• report publish commits as changes and exit publish by code family (cli)
• complete the exit-code table and validate envelopes on unwrap (cli)

All packages → 0.42.0 (sync versioning)

• @releasekit/version
• @releasekit/notes
• @releasekit/publish
• @releasekit/release

After merge — predicted release

No version escalation — this PR's changes will be included in the queued release without affecting the projected versions.

Package	Standing PR	This PR	After merge
monorepo	0.42.0	0.42.0	0.42.0

---

Updated automatically by ReleaseKit