Release guide

Maintainer HQ treats the local release gate as authoritative. CI calls the same underlying scripts and adds parallelism, caching, summaries, and failure artifacts.

Before versioning

Add user-visible changes under a category in the Unreleased section of CHANGELOG.md. From a clean main checkout, install exact dependencies and the browser runtime, then run:

npm ci
npx playwright install chromium
npm run check:release

The gate validates source and syntax, audits dependencies before the longer local suites, enforces coverage thresholds, runs browser flows, scans publication content, dry-runs the package manifest, creates the tarball and checksum, and installs that tarball under a clean temporary home for an onboarding probe. The dependency-audit wrapper disables npm's nested retries, gives every registry attempt a fixed timeout, and retries only recognized transient failures within a fixed attempt limit. If npm exhausts those transient attempts, the wrapper projects every exact package and version from the bounded lockfile into OSV's batch API only after confirming that OSV's public npm feed is fresh. Any npm finding, OSV finding at any severity, stale or unavailable OSV data, malformed response, unsupported lockfile entry, or unrecognized provider failure stops the release.

Cut a version

Use the guarded version command instead of editing version fields or tags manually:

npm run release:version -- patch

major, minor, patch, and an exact x.y.z version are accepted. The command refuses a non-main branch, a dirty tree, an existing tag, a non-advancing version, or empty release notes. It runs the full release gate before editing, synchronizes package.json, package-lock.json, src/constants.mjs, and CHANGELOG.md, reruns unit and integration tests against the new version, rechecks publication state, commits only the version files, and creates an annotated vX.Y.Z tag. It does not push.

Publish through GitHub

Push the release commit only when branch CI should run. Wait for all required jobs to pass, then push the annotated tag. Tag CI verifies the tag against the package, source constant, changelog, and checked-out commit; reruns the release gate; builds the tarball and SHA256SUMS; and creates the GitHub release from the exact changelog section.

The tag workflow is the normal deployment path. It provisions its own Chromium runtime before repeating the full release gate. If a remote release must be recovered manually, use the same npm run verify:release-tag, npm run check:release, npm run package, and npm run release:notes -- vX.Y.Z commands before invoking GitHub CLI. Never upload a workspace document, provider projection, environment file, browser trace containing private state, or ad hoc artifact outside dist/.

Verify a release

Download the tarball and checksum from the GitHub release, verify SHA-256, install into a temporary prefix, and run maintctl --version, maintctl init, and maintctl doctor. The automated clean-install probe performs the same product checks on every release candidate.