Maintainer release procedure

Internal checklist for release validation, bootstrap publication, provenance, and post-release verification.

Maintainer release procedure

This is the release runbook for the public invariantcad npm package and its matching GitHub release. It intentionally keeps publishing separate from the ordinary CI workflow.

Release acceptance

Before creating a tag:

1. move shipped changes from Unreleased into a dated changelog section;
2. set the same version in package.json and the release notes;
3. review the committed etc/api/ diff against the previous release;
4. run pnpm release:check;
5. review the checked coverage report and all six kernel/model reference benchmark results emitted by that command;
6. inspect pnpm pack --dry-run for secrets, local artifacts, and omissions;
7. push the release commit and wait for every required GitHub check to pass; and
8. create the annotated v<package-version> tag from that exact commit.

The release workflow serializes publication attempts and independently installs from the frozen lockfile after a full-history checkout. Before acceptance or publication, it proves that the dispatch ref is the exact annotated v<package-version> tag, that the tag points at the checked-out commit, and that the commit is contained in origin/main. It then reruns the full acceptance suite and publishes from a GitHub-hosted runner with provenance. The suite includes strict TypeScript, source correctness and format hygiene, public-entrypoint and API-report consistency, package metadata/types, clean-consumer installation, checked coverage, the complete six-case reference benchmark, dependency audit, Mintlify validation and links, and the production browser bundle.

The publication job uses Node.js 24 because the pinned Mint CLI accepts Node 20.17 through 24 and rejects Node 25 and newer. Independent CI continues to gate InvariantCAD on Node 26, so this tooling ceiling is not a package runtime ceiling.

One-time npm bootstrap

The one-time bootstrap completed with invariantcad@0.1.0 on 2026-07-22. The public registry artifact, provenance, owner, files, CLI, entry points, geometry kernels, and latest tag were independently verified. The release workflow does not read or require a registry token.

Never commit an npm token or copy it into a workflow file, shell history, issue, release note, or CI log. The npm-side bootstrap token must also be revoked.

The package’s npm trusted publisher is configured with these case-sensitive values:

• provider: GitHub Actions;
• organization or user: shlokjain42;
• repository: invariantCAD;
• workflow filename: release.yml;
• environment: npm; and
• allowed action: npm publish.

Publishing access requires 2FA and disallows traditional tokens. Future releases use the workflow’s short-lived OIDC identity; no npm secret is needed. npm automatically emits provenance for a public package published from this public repository through trusted publishing.

InvariantCAD 0.1.1 is the first post-bootstrap, end-to-end confirmation of this tokenless path. If npm returns ENEEDAUTH, verify every trusted-publisher field exactly; do not restore a long-lived publish secret.

Publishing and verification

Dispatch the workflow on the tag, never on a branch:

VERSION="$(node -p 'require("./package.json").version')" gh workflow run release.yml --ref "v$"

After it succeeds, verify independently:

npm view “invariantcad@${VERSION}" version dist-tags repository --json npm pack "invariantcad@$” —dry-run

Install the registry artifact into an empty temporary project and exercise its ESM entry points and CLI. Only then publish the GitHub release using the body of docs/releases/<version>.md as the release notes; omit that Mintlify page’s YAML frontmatter delimiters and fields.

Published npm versions are immutable. If verification uncovers a defect, do not attempt to replace the version; fix it and publish a new patch version.