Releases and recovery

Preparing the repository, merging a PR and publishing packages are separate operations. The current published train is toolkit 0.1.0-alpha.2 and Hey API integration 3.0.0-alpha.2, available on npm's next channel. It includes all nineteen packages, with direct named setters, local diagnostics and native Zod/ArkType adapters. The GitHub prerelease records its source commit and original package artifacts. The first seventeen-package alpha.0 release remains unchanged. For later trains, version fields and green tests alone do not prove registry publication.

Release train

The root is private. All scoped toolkit packages share a fixed Changesets version group; the unscoped hey-api-builders keeps its own major version. Internal runtime dependencies are exact. Root development links may use workspace:*, but published manifests must contain the matching actual versions. check-workspace.mjs rejects missing internal packages, version drift, dependency cycles, unexpected exports, core vendor dependencies and incorrect release channels before installation.

Add a changeset for subsequent changes. The repository is in Changesets prerelease mode (.changeset/pre.json), so run pnpm version-packages for the next alpha. Only use pnpm changeset pre enter alpha when starting a new prerelease cycle. Review the version plan, generated changelogs, exact internal dependency versions and package publishConfig.tag fields. They must be next for prereleases and latest only for an explicitly reviewed stable train. Refresh pnpm-lock.yaml after versioning and run pnpm check:workspace. The guard intentionally fails rather than concealing an incomplete version transition. Leaving prerelease mode is a deliberate operation.

Prepare without publishing

From the reviewed commit with the pinned Node/pnpm toolchain:

pnpm install --frozen-lockfile
pnpm validate
pnpm pack:check
pnpm test:examples
node scripts/test-browser.mjs --install
pnpm release:prepare

pack:check verifies packages in a disposable location and does not require a clean worktree. release:prepare requires a clean committed tree, refuses to overwrite an existing release directory, and prepares that directory with all tarballs, manifest.json and SHA256SUMS. The manifest records the source commit, complete inventory, versions, distribution tag and SHA-256/SHA-512 digests. Package export and ESM declaration diagnostics run against each actual tarball. Internal dependency metadata is checked again after all packages have been packed. No publication occurs during these commands.

Inspect the complete artifact set. Consumer tests install actual tarballs in fresh projects; a successful workspace import is not equivalent evidence. Portable core, browser, minimum-compiler and recipe jobs are separate acceptance gates. Performance reports are correctness-checked measurements, not hardware-independent speed promises.

Publish through the reviewed release workflow

First publication of the new npm names

npm requires a package to exist before it can receive a trusted-publisher configuration. Releases introducing new package names use a separate bootstrap:

1. On the renamed repository's reviewed main, dispatch Prepare provenance-backed first publication. It runs the full acceptance gates, packs the entire train, and signs the verified archives in a separate credential-isolated GitHub job. It does not publish to npm and needs no npm token.

2. Download the mimlet-first-publication artifact from that exact workflow run. It contains release/ and provenance/. Install npm@11.19.0 into a temporary directory with lifecycle scripts disabled.

3. Run the verifier, then the publisher in an interactive terminal:

   node scripts/bootstrap-release.mjs verify /path/to/npm-runtime/node_modules/npm /path/to/artifact/release /path/to/artifact/provenance
   node scripts/bootstrap-release.mjs publish /path/to/npm-runtime/node_modules/npm /path/to/artifact/release /path/to/artifact/provenance

   Every archive, internal dependency, provenance signature, GitHub certificate identity, source commit and registry collision is checked before the first write. npm handles interactive security-key/2FA verification. Existing identical versions are skipped, so an interrupted batch can resume from the same artifact.

4. Configure each package's trusted publisher for JeffreyNijs/mimlet, workflow npm-publish.yml, environment npm-publish, allowing publication. Future releases use the normal workflow below.

The bootstrap pins npm's own configuration, 2FA, publishing and Sigstore modules. It selects the pre-signed bundle instead of local automatic signing; it does not strip provenance or change packed bytes. This avoids the npm CLI's conflicting publishConfig.provenance and --provenance-file options. Updating the pinned npm runtime requires reviewing those interfaces. Keep credentials out of artifacts.

Subsequent releases

The publishing trigger is a GitHub release with tag toolkit-v<core version>, for example toolkit-v0.1.0-alpha.0. The workflow checks that the release commit belongs to main, runs acceptance, audits dependencies, prepares the verified artifacts and compares the tag/prerelease flag to the manifest. The scoped train and Hey API integration must use the same prerelease/stable channel.

Before each publication, confirm ownership of each npm name, the matching trusted publisher, the intended npm-publish environment policy and the release source. These external account controls can drift independently of the repository. Keep long-lived npm credentials out of source and generated artifacts.

The publish job receives the verified artifact inventory rather than rebuilding source with publishing credentials. It verifies archive/file identities, sizes, digests, package metadata and the complete internal dependency graph before any publish. The configured npm CLI publishes the tarballs with lifecycle scripts disabled and provenance enabled. Prereleases use next; stable releases use latest. A non-matching tag or channel fails closed.

Failure, partial release and rollback

Publication across multiple npm packages is not transactional. The job checks all existing package versions first. An identical already-published integrity is a completed item; a different integrity or a failed registry request stops the job. A retry can resume the remaining packages from the same verified artifact set. Do not rebuild arbitrary different bytes and claim they are the same release.

Preserve the original release artifacts while investigating a partial publish. Do not publish a replacement under a conflicting immutable version. Prepare a new patch/prerelease train when a source or artifact correction is necessary, with updated internal versions and new acceptance evidence. Registry errors are not converted into permission to publish blindly.

For a bad release, consumers should pin a previous coherent train (including the matching core and Hey API integration), or move to a corrected train. Maintainers may deprecate a bad version and adjust distribution tags through their normal reviewed npm process. Do not automatically unpublish packages or rewrite Git history as a rollback. Never mix a generated v3 client with an incompatible core.

This guide describes the release process; the linked release and registry metadata provide publication evidence. A published alpha does not authorize releasing unreviewed future artifacts. See acceptance and security.