npm publish refuses to run outside the release workflow

[las7]

Closes the hole that burnt v0.4.0.

A release here is two publishes: npm, then the MCP registry. npm publish by hand does only the first, and does it without running the tests — so the registry never sees the version, and the number is spent against the workflow that would have caught whatever is wrong with it.

It already happened

$ npm view @reachpad/mcp@0.3.0 _npmUser.name  →  GitHub Actions
$ npm view @reachpad/mcp@0.3.1 _npmUser.name  →  (a person)
$ npm view @reachpad/mcp@0.4.0 _npmUser.name  →  GitHub Actions
$ npm view @reachpad/mcp@0.4.1 _npmUser.name  →  GitHub Actions

0.3.1 went out by hand on 2026-08-24 carrying a 153-character description, against the registry's 100-character cap. Nothing tried to publish 0.3.1 to the registry, so the cap went unnoticed for three days — until v0.4.0 hit it, after npm had already taken 0.4.0. The listing sat on 0.3.0 the whole time, and 0.4.0 is on npm and absent from the registry permanently.

The gate

prepublishOnly refuses unless CI is set. It costs nothing, needs no credential to check, and fails toward a refused publish rather than a bad one. The message says what to do instead:

publish-guard: REFUSING to publish from outside CI.

  Release by pushing a tag instead:

      git tag -a v<version> <sha> -m "<what changed>"
      git push origin v<version>

  That runs the tests, publishes to npm, and publishes to the registry.

  If you really mean to do it by hand: ALLOW_MANUAL_PUBLISH=1 npm publish

The escape hatch is deliberate, explicit and greppable, and warns that the registry half will not run.

Verified by running it, not by reading it

case	result
no CI	refused, exit 1
CI=true	packs, exit 0 — the workflow is unaffected
ALLOW_MANUAL_PUBLISH=1	allowed with the warning, exit 0
npm pack	the guard does not ship in the tarball

48 tests pass, 1 skipped (live, needs credentials).

Still worth doing separately

This is a client-side gate — it stops the accident, not a determined publish. The registry-side version is npm trusted publishing (require a provenance-signed CI publish, reject token publishes). That needs npm account access I don't have from this box.

🤖 Generated with Claude Code

https://claude.ai/code/session_01STcKsJb8PNq3xbYsCuiiHs