Shipcheck

shipcheck

Did that release actually ship? One command, every surface, one verdict.

A modern release touches many public surfaces: the git tag, the GitHub release, the package metadata in the repo, npm or PyPI, the MCP Registry, and the container image on GHCR. Each one can fail silently while the others look fine. The publish workflow goes green, and then: npm has the version stuck in a staged hold, the registry still points at the last release, the container tag never got pushed, or, the worst one, the git tag points at a commit that does not exist.

shipcheck checks every surface against one expected version and prints a single verdict: GO, or NO-GO with the exact surfaces that disagree and the evidence for each one. It speaks both ecosystems: Node repos are read from package.json and npm, Python repos from pyproject.toml / setup.cfg / setup.py and PyPI, and hybrid repos (a Python core with an npm wrapper, like wallcheck) are checked on every carrier they actually have.

Why this exists

shipcheck was not designed in the abstract. It is the manual verification gauntlet from shipping Greenlight and its sibling tools, turned into a tool. That gauntlet caught real failures:

• A release where the git tag pointed at a nonexistent commit object. npm, the registry, and the sources were all real; only checking that the tag resolves to a real commit exposed it. That is why tag-commit is a hard check.
• npm staged publishing holds, where a brand new package version sits in review and the registry shows only a placeholder. To a user, the release simply does not exist. That is why npm-version and npm-latest are separate checks.
• Registry publishes dispatched before npm verified, leaving the MCP Registry pointing at a version npm did not have yet. That ordering lesson is why shipcheck treats "listed" and "latest" as different facts on every surface.

What it checks

Verdict rules:

• GO: every hard check passes. Exit code 0.
• NO-GO: any hard check fails or errors. Exit code 1, ready for CI.
• SKIP: a surface that does not apply is skipped, never failed. A repo with no MCP Registry entry skips the registry checks; a repo with no public container image skips GHCR; a Python project that is not on PyPI skips the PyPI checks; a Python project with no package.json skips npm instead of failing it. GHCR checks are soft by default and become hard with --require ghcr.
• Every check reports expected vs actual and the source URL. A failed fetch is reported as an error with its HTTP status, never guessed.
• The report names the detected ecosystem (node, python, hybrid, unknown). A Python app with no metadata carriers at all (requirements files and sources only) is still detected from its tag tree, and reports its missing version carrier as a SKIP with the evidence, not as a silent pass.

Usage

CLI

# Full check. Version is read from package.json or the Python metadata# (pyproject.toml, setup.cfg, setup.py) on the default branch.npx @reneturcios/shipcheck check CloudCorpRecords/greenlight
# Python and hybrid repos work the same waynpx @reneturcios/shipcheck check CloudCorpRecords/wallcheck 0.5.0
# Check a specific versionnpx @reneturcios/shipcheck check CloudCorpRecords/greenlight 0.15.1
# Machine readable output, custom surface names, force GHCR to be requirednpx @reneturcios/shipcheck check owner/repo 1.2.0 --json \  --npm @scope/pkg --pypi pkg --server io.github.Owner/repo --require ghcr
# Single surfacesnpx @reneturcios/shipcheck npm @reneturcios/greenlight 0.15.1npx @reneturcios/shipcheck pypi wallcheck 0.5.0npx @reneturcios/shipcheck registry io.github.CloudCorpRecords/greenlight 0.15.1

Example output:

shipcheck CloudCorpRecords/greenlight v0.15.1: GO  [PASS] git-tag: Tag v0.15.1 exists (object type commit)  [PASS] tag-commit: Tag resolves to real commit f52939005a0f  [PASS] tag-version: package.json at v0.15.1 is version 0.15.1  [PASS] github-release: GitHub release v0.15.1 is published  [PASS] npm-version: @reneturcios/[email protected] is published on npm  [PASS] npm-latest: npm latest points at 0.15.1  [PASS] registry-version: MCP Registry lists io.github.CloudCorpRecords/greenlight 0.15.1 (status active)  [PASS] registry-latest: MCP Registry latest is 0.15.1 and active  [PASS] ghcr-tag: GHCR image has tag 0.15.1  [PASS] ghcr-latest: GHCR image has a latest tagGO: every hard surface agrees on this version.

Inference, so the common case needs one argument: the npm package name is read from package.json at the tag or on the default branch, the PyPI package name from the Python metadata, the registry server name from server.json when present (else io.github.<Owner>/<repo>), and the GHCR image defaults to ghcr.io/<owner>/<repo> lowercased. Override any of them with --npm, --pypi, --server, or --ghcr. Skip whole groups with --skip npm,pypi,python,server,registry,ghcr,release,github.

Set GITHUB_TOKEN for the higher authenticated GitHub API rate limit. Public surfaces need no other credentials; GHCR uses the standard anonymous token flow for public images.

MCP server

Add to your MCP client config:

{  "mcpServers": {    "shipcheck": {      "command": "npx",      "args": ["-y", "@reneturcios/shipcheck", "mcp"]    }  }}

Tools:

• check_release: the full check: repo, optional version, optional npm/PyPI/server overrides, require and skip lists.
• check_npm: one npm package and version: published, and latest points at it.
• check_pypi: one PyPI package and version: published with files, and it is the latest release. Absent from PyPI reports as skipped.
• check_registry: one MCP Registry server and version: listed, and marked latest.

Docker

docker run -i ghcr.io/cloudcorprecords/shipcheck mcpdocker run --rm ghcr.io/cloudcorprecords/shipcheck check CloudCorpRecords/greenlight 0.15.1

The toolkit

shipcheck is Wave 1, package 1 of a planned family of small, single-purpose developer tools by the same author, all built the same way: one bin that serves a CLI and an MCP server, deterministic checks with evidence, no invented answers.

• greenlight: pre-flight checks for open-source contributions: is this issue actually landable?
• prwatch: attention report for your open PRs: what needs you right now.
• claimcheck: stale-claim states and parked fixes on forks.
• gatefile: extract hidden contribution gates into machine-readable contribution-gates.json.
• pkgverdict: pre-install verdicts for npm packages: GO, RISKY, FAKE, or MISSING.

Development

npm installnpm run buildnpm test   # 40 tests, all surface logic runs on injected fixtures, no network

License

MIT