publishorder

publishorder

你即将发布一个 monorepo 版本，而各个包必须按正确顺序发布：依赖项尚未发布的包不能先发布。publishorder 接收包依赖图——每个包的名称，以及必须先于它发布的包的名称——并计算发布计划：

• 发布顺序 — 对纳入计划的包进行拓扑排序，使用 Kahn 算法计算。每当有多个包可以发布时，优先选择名称按字母顺序排列最靠前的包，因此相同的依赖图始终会得到完全相同的顺序。
• 层级 — 按深度对包分组。第 0 层包含没有纳入计划的依赖项的包；其他包位于比其最深的纳入计划依赖项高一层的位置。同一层的所有包可以一起发布，只要它们下方的各层已发布。
• 变更集计划 — 传入已变更包的名称后，计划将恰好涵盖这些包以及所有直接或传递依赖于它们的包。其余包会列为 excluded，指向这些包的依赖项不会限制顺序——它们已发布。
• 循环检测 — 如果纳入计划的包无法排序，publishorder 不会报错或猜测，而是返回 ok: false，并给出确切的循环：按照名称和依赖项升序进行深度优先搜索，返回找到的第一个循环，并将组成该循环的包列出（依赖自身的包会报告为仅包含一个名称的循环）。完全位于排除包之间的循环不会阻止变更集计划。

依赖图必须完整：依赖项或变更条目中引用了未提供的包，会导致验证错误；包名称缺失或重复，以及字段类型错误也会导致验证错误。错误会指出出错路径（例如 packages[1].dependencies[0] references unknown package "core"），并且不会生成部分计划。计算是纯本地的：不使用网络、不读取配置，也不会读取你传入的输入以外的任何文件。

CLI

npx @reneturcios/publishorder plan --input args.json
npx @reneturcios/publishorder --version

args.json 包含完整的参数对象：

{
  "packages": [
    { "name": "core", "version": "1.4.1" },
    { "name": "lib", "dependencies": ["core"] },
    { "name": "app", "dependencies": ["lib"] }
  ],
  "changed": ["core"]
}

每个包的 dependencies 默认为 []，version 为可选项，且不会影响顺序；changed 整体为可选项。计划以 JSON 格式输出：

{
  "ok": true,
  "order": ["core", "lib", "app"],
  "levels": [["core"], ["lib"], ["app"]],
  "cycle": [],
  "included": ["app", "core", "lib"],
  "excluded": []
}

退出代码：成功时为 0，运行时错误时为 1（包括无法读取或无效的输入文件，或无效输入），用法错误时为 2。

MCP 服务

npx -y @reneturcios/publishorder mcp

MCP 客户端配置：

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

工具

• plan_publish_order — 根据依赖图规划 monorepo 发布顺序。

  • packages（数组，必填，至少一个元素）— 包对象，格式为 {name, dependencies?, version?}；name 在集合中必须唯一，每个 dependencies 条目都必须指向另一个已提供的包
  • changed（字符串数组，可选）— 提供此项时，计划将涵盖这些包以及所有传递依赖于它们的包

  返回 {ok, order, levels, cycle, included, excluded}。

Docker

docker run -i ghcr.io/cloudcorprecords/publishorder
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/publishorder plan --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios