Recover npm publication with typed registry state

[karlwaldman]

Summary

• replace the release job's fail-open npm view ... || true recovery branch with a built-in typed npm Registry resolver
• treat only an exact HTTP 404 as unpublished; require exact package/version/integrity for an existing version; fail on malformed, conflicting, unavailable, or unexpected responses
• bump every governed release surface to immutable recovery version 3.2.2

Why

The immutable v3.2.1 release run stopped before publication because npm's E404 JSON body was coerced into a nonempty integrity string. npm and the MCP Registry remain unpublished at 3.2.1. The tag/release is retained and marked publication-halted.

TDD proof

RED:

• node scripts/verify-npm-release-smoke.mjs failed because resolveNpmPublicationState did not exist
• workflow contract rejected the existing npm view ... || true branch

GREEN at exact head 804961c181aa29ef0a0f90761a44f7c1d73f2569:

• npm test: 193 passed
• npm audit --audit-level=low: 0 vulnerabilities
• npm, MCP Registry, and protected-main provenance verifier smokes: green
• release metadata 3.2.2: green
• public-claims: 46 source/packed surfaces
• product-facts source + live v1 bridge: green, reviewed 50/day
• packed CLI/capabilities/scopes/protocol: green
• deterministic non-root Docker smoke: green, exact source 804961c1
• live exact npm publication-state request for absent oilpriceapi-mcp@3.2.2: absent, exit 0
• git diff --check: clean

Release gates

• no npm or MCP Registry publication occurs from this PR
• after merge, require exact-main CI and credentialed production synthetic
• publish immutable v3.2.2, then verify npm latest/integrity/SLSA provenance, MCP Registry exact readback, and cold-installed keyless customer paths
• downstream API v2/docs/Sheets rollout remains held until those public artifact checks pass

Summary by CodeRabbit

• Release

  • Updated the MCP server and package version to 3.2.2 across the published configuration and metadata.

• Bug Fixes

  • Improved npm publishing validation to distinguish already-published, unpublished, and invalid package states.
  • Prevented releases from proceeding when registry responses are ambiguous, malformed, or inconsistent.

• Tests

  • Added coverage for successful, missing, invalid, and server-error registry responses.
  • Strengthened checks for secure publication workflow behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The release updates package metadata to version 3.2.2 and adds npm publication-state verification. The publish workflow publishes absent packages, accepts matching packages, and fails on unexpected registry responses.

Changes

NPM release flow

Layer / File(s)	Summary
Version alignment .mcp.json, manifest.json, package.json, server.json, src/index.ts	Release metadata and MCP_VERSION now report version 3.2.2.
Publication-state verification scripts/verify-npm-release.mjs, scripts/verify-npm-release-smoke.mjs	The verifier resolves absent and present states, rejects invalid responses, supports NPM_RELEASE_MODE=publication-state, and includes smoke coverage.
Publish workflow integration .github/workflows/publish.yml, src/__tests__/directorySource.test.ts	The OIDC job uses publication-state mode and publishes only when the expected package is absent. Tests reject direct npm lookups and `

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PublishWorkflow
  participant VerifyNpmRelease
  participant NpmRegistry
  PublishWorkflow->>VerifyNpmRelease: resolve publication state
  VerifyNpmRelease->>NpmRegistry: fetch package version metadata
  NpmRegistry-->>VerifyNpmRelease: return registry response
  VerifyNpmRelease-->>PublishWorkflow: return absent, present, or failure
  PublishWorkflow->>NpmRegistry: publish when state is absent

Loading

Possibly related PRs

• OilpriceAPI/mcp-server#55: Introduced the release-verification and publication workflow extended here.
• OilpriceAPI/mcp-server#67: Introduced the npm release verification extended by the publication-state resolver.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: typed npm registry-state handling for publication recovery.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/release-3-2-2-recovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[karlwaldman]

Exact-head release-recovery clearance for 804961c181aa29ef0a0f90761a44f7c1d73f2569 on base 10e78b26343376c369ad9c5c15db831141bf88a0:

• local: 193/193 tests, audit 0, exact build/package/Docker, 46 public surfaces, product-facts and release verifiers green
• adversarial resolver matrix: 15 discriminating cases; only HTTP 404 resolves absent and only exact name/version/integrity resolves present
• 401/429/503, malformed/conflicting 200, invalid JSON, fetch failure, bad SRI, missing inputs, unsupported mode, and invalid timeout all fail closed
• shell assignment preserves resolver nonzero status under set -euo pipefail
• hosted run 31509904700: every applicable job green; CodeRabbit green; PR CLEAN

No npm or MCP Registry publication occurred from the PR. Next gates are squash merge, exact-main credentialed smoke, then immutable v3.2.2 publication and public artifact readback.

[karlwaldman]

Production release receipt:

• squash merge: d8c83bd020d3dfe7e264b21acdb7b0ad64edcdfe
• protected-main exact run: https://github.com/OilpriceAPI/mcp-server/actions/runs/31511245226, all jobs green including credentialed latest/curve smoke
• release: https://github.com/OilpriceAPI/mcp-server/releases/tag/v3.2.2
• publish run: https://github.com/OilpriceAPI/mcp-server/actions/runs/31511364030, attempt 2 fully green
• npm latest: oilpriceapi-mcp@3.2.2, integrity sha512-n+mWDGB/XKmH7E8xZw3nD89MebmQlFiTOl83381GKqtDUi62VpKUvbeGA07wR4mPYbyygyoCV29T8ck5cpk1kA==, shasum d5c68d36f8bb91c8e37e4f2db4c2f9d777486dce
• exact npm latest/integrity/source-repo/workflow/tag/commit/SLSA/transparency verifier: green
• official MCP Registry io.github.OilpriceAPI/mcp-server version 3.2.2: active, latest, exact metadata readback green
• cold public npm install: Node 18.20.8 and Node 24 both green; exact source d8c83bd0, 32/36 read tools, live reviewed 50/day product-facts tool/resource parity, and keyless Brent with source timestamp

The first publish attempt successfully created npm 3.2.2 but the npm attestation endpoint propagated just after the bounded readback expired; Registry publication did not run. The idempotent failed-job retry verified the now-public exact tarball and source-bound attestation, then published and read back the MCP Registry entry. No duplicate or divergent artifact was created.