shipcheck

shipcheck

这个版本真的发布了吗？一个命令，检查所有渠道，给出一个结论。

现代版本会发布到许多公开渠道：Git 标签、GitHub Release、仓库中的包元数据、npm 或 PyPI、MCP Registry，以及 GHCR 上的容器镜像。每个渠道都可能悄无声息地失败，而其他渠道看起来一切正常。发布工作流显示成功，结果却是：npm 中的版本卡在暂存审核状态，Registry 仍指向上一个版本，容器标签从未推送，或者更糟——Git 标签指向一个并不存在的提交。

shipcheck 会根据预期版本检查每个渠道，并给出一个结论：GO，或者 NO-GO，同时列出不一致的具体渠道及每项检查的证据。它支持两种生态：从 package.json 和 npm 检查 Node 仓库；从 pyproject.toml / setup.cfg / setup.py 和 PyPI 检查 Python 仓库；对于混合仓库（例如 wallcheck 这样的 Python 核心加 npm 包装器），则会检查它们实际拥有的每种发布载体。

为什么要做这个工具

shipcheck 并非凭空设计而来。它是将发布 Greenlight 及其配套工具时的手动验证流程做成了工具。那套流程曾发现过真实故障：

• 一次发布中，Git 标签指向了一个不存在的提交对象。npm、Registry 和源代码都真实存在；只有检查标签是否能解析到真实提交，才能发现问题。这就是 tag-commit 属于强制检查的原因。
• npm 暂存发布会让新版本的包卡在审核中，而 Registry 只显示占位内容。对用户来说，这个版本根本不存在。这就是 npm-version 和 npm-latest 分开检查的原因。
• Registry 发布在 npm 验证完成前就已启动，导致 MCP Registry 指向了一个 npm 尚未提供的版本。这个顺序问题让 shipcheck 在每个发布渠道上都将“已列出”和“最新”视为不同的事实。

检查内容

检查项	验证内容
git-tag	仓库中存在 v<version> 标签
tag-commit	标签解析为真实的提交对象
tag-version	标签中的 package.json 携带预期版本
pyproject-version	标签中的所有 Python 版本载体一致：pyproject.toml（[project] 或 [tool.poetry]）、setup.cfg、setup.py，以及从其指向的文件中解析出的动态版本（hatch、setuptools attr: / file:、__version__）
server-version	标签中的 server.json、其软件包版本及其 OCI 标签全部一致
github-release	存在该标签对应的已发布（非草稿）GitHub Release
npm-version	npm 软件包已发布此版本（仅当仓库中有 npm 软件包时）
npm-latest	npm dist-tags.latest 指向此版本
pypi-version	PyPI 软件包已发布此版本及其文件（Python 项目）
pypi-latest	PyPI 上最新发布的版本为此版本
registry-version	MCP Registry 中列出了此服务的此版本
registry-latest	MCP Registry 将此版本标记为最新且处于活跃状态
ghcr-tag	GHCR 镜像拥有此版本标签
ghcr-latest	GHCR 镜像也拥有 latest 标签
python-tests	软性检查：标签中存在 Python 测试文件，并符合运行器结构（pytest 配置或 unittest 结构）
dockerfile	软性检查：标签树中存在 Dockerfile
readme	软性检查：仓库根目录中存在 README
mcp-entry	软性检查：存在 MCP 服务入口点（*-mcp 或服务控制台脚本，或 server.json）

判定规则：

• GO：所有硬性检查均通过。退出代码为 0。
• NO-GO：任一硬性检查失败或出错。退出代码为 1，可用于 CI。
• SKIP：不适用的检查项会跳过，而不会判定为失败。没有 MCP Registry 条目的仓库会跳过 Registry 检查；没有公开容器镜像的仓库会跳过 GHCR 检查；不在 PyPI 上发布的 Python 项目会跳过 PyPI 检查；没有 package.json 的 Python 项目会跳过 npm 检查，而不会因此失败。GHCR 检查默认是软性检查，使用 --require ghcr 后会变为硬性检查。
• 每项检查都会报告预期值与实际值，以及来源 URL。获取失败会作为错误报告并附上 HTTP 状态码，不会猜测结果。
• 报告会列出检测到的生态系统（node、python、hybrid、unknown）。即使 Python 应用完全没有元数据载体（只有 requirements 文件和源文件），仍会根据其标签树检测出来；对于缺失的版本载体，会根据证据报告为 SKIP，而非静默通过。

用法

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 way
npx @reneturcios/shipcheck check CloudCorpRecords/wallcheck 0.5.0

# Check a specific version
npx @reneturcios/shipcheck check CloudCorpRecords/greenlight 0.15.1

# Machine readable output, custom surface names, force GHCR to be required
npx @reneturcios/shipcheck check owner/repo 1.2.0 --json \
  --npm @scope/pkg --pypi pkg --server io.github.Owner/repo --require ghcr

# Single surfaces
npx @reneturcios/shipcheck npm @reneturcios/greenlight 0.15.1
npx @reneturcios/shipcheck pypi wallcheck 0.5.0
npx @reneturcios/shipcheck registry io.github.CloudCorpRecords/greenlight 0.15.1

输出示例：

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 tag
GO: every hard surface agrees on this version.

自动推断，因此常见情况下只需一个参数：npm 软件包名称从标签或默认分支上的 package.json 中读取，PyPI 软件包名称从 Python 元数据中读取；如果存在 server.json，则从中读取 Registry 服务名称，否则使用 io.github.<Owner>/<repo>；GHCR 镜像默认为转为小写的 ghcr.io/<owner>/<repo>。使用 --npm、--pypi、--server 或 --ghcr 可覆盖这些值。使用 --skip npm,pypi,python,server,registry,ghcr,release,github 可跳过整组检查。

设置 GITHUB_TOKEN 可提高经过身份验证的 GitHub API 速率限制。公开检查项无需其他凭据；GHCR 公开镜像使用标准匿名令牌流程。

MCP 服务

将以下内容添加到 MCP 客户端配置中：

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

工具：

• check_release：完整检查：仓库、可选版本、可选 npm/PyPI/服务覆盖项、必需项和跳过项列表。
• check_npm：单个 npm 软件包和版本：已发布，且 latest 指向该版本。
• check_pypi：单个 PyPI 软件包和版本：已发布且包含文件，并且是最新发布版本。若 PyPI 上不存在，则报告为跳过。
• check_registry：单个 MCP Registry 服务和版本：已列出，且标记为最新。

Docker

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

工具包

shipcheck 是该作者计划推出的一系列小型单一用途开发者工具中的 Wave 1、package 1。它们采用相同的构建方式：一个 bin 同时提供 CLI 和 MCP 服务，通过确定性检查提供证据，不编造答案。

• greenlight：开源贡献的预检：这个问题真的可以合并吗？
• prwatch：关于你已开启的 PR 的关注事项报告：现在有哪些事需要你处理？
• claimcheck：fork 上过时声明的状态和搁置的修复。
• gatefile：提取隐藏的贡献门槛，生成机器可读的 contribution-gates.json。
• pkgverdict：npm 包的安装前判定：GO、RISKY、FAKE 或 MISSING。

开发

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

许可证

MIT