Add semantic npm release automation

[calvin-archastro]

Review on ArchCode

Problem and author intent

Intern MCP still used the one-time bootstrap release workflow created before the package existed on npm. It offered no semantic-version choice, tried to publish the version already committed in package.json, and relied on NPM_TOKEN. The package is now public, so maintainers need the same bump-and-tag release flow used by archastro-js and a separate OIDC publication boundary.

What changed

• Added a required patch, minor, or major input to the manual release workflow.
• The release job runs the complete package gate, updates package.json plus package-lock.json, and pushes a version-only release branch.
• The workflow opens and rebase-merges that PR, matching Intern MCP’s active main-branch ruleset.
• It resolves the PR’s immutable mergeCommit.oid, verifies that exact commit is on main and contains the selected version, then creates the vX.Y.Z tag. This prevents a concurrent main merge from entering the published package.
• Added publish.yml, explicitly dispatched at the immutable tag because GITHUB_TOKEN tag pushes do not start another workflow.
• The publish job checks tag/package agreement and duplicate versions, publishes through npm Trusted Publishing in the protected npm-release environment, and creates the GitHub Release.
• Updated release documentation and added an executable workflow contract test.

Scope indicator

CI/release automation only. No runtime MCP behavior changes.

Risk assessment

Medium. This changes npm publication authority and tag creation. Risk is constrained by the protected environment, GitHub-hosted OIDC publisher, immutable merged-commit tagging, complete package checks before release, exact version checks before publish, and refusal to overwrite an existing npm version.

User impact

Maintainers can select patch, minor, or major from the Actions UI. Package consumers see no change until a release is intentionally run.

Testing

• Workflow contract: src/release-workflows.test.ts, test “a manual semantic version bump reaches the tag-bound OIDC publisher” (passed). It pins semantic inputs, rebase-only merge behavior, immutable merge-SHA ordering, explicit publish dispatch, protected OIDC authority, private-repository provenance behavior, and removal of NPM_TOKEN.
• npm run check — passed: formatting, lint, TypeScript build, 9 test files / 33 tests, and clean-consumer package smoke.
• Both workflow YAML files parse successfully with Ruby Psych.
• A temporary package fixture proved npm version patch --no-git-tag-version updates package.json, package-lock.json, and the root lockfile package entry from 0.1.0 to 0.1.1.
• Independent adversarial review found and verified fixes for the repository’s rebase-only merge rule, merge-before-tag ordering, immutable merge-commit selection, and shell heredoc escaping; final review reported no remaining actionable findings.
• No honest end-to-end publish was run: the real boundary creates a protected tag, publishes an immutable npm version, and creates a GitHub Release. The first release after merge is the canonical live proof.

Follow-ups and known issues

• Before the first run, npm’s trusted publisher for @archastro/intern-mcp must point to workflow filename publish.yml and environment npm-release. npm permits one trusted publisher per package.
• Provenance is intentionally omitted while the source repository is private; npm Trusted Publishing supports the publish, but npm provenance does not support private source repositories.