enginedrift

enginedrift

Node 项目中有三个地方会悄悄声明 Node 版本： package.json 中的 engines.node、CI 中的 node-version 值， 以及 Dockerfile 中的 FROM node:... 标签。这些声明不一致时， 问题通常会很晚才出现——例如 CI 作业运行的主版本与容器不同， 或某项语法特性在一处可用、在另一处却不可用。enginedrift 会提取 每个来源实际声明的内容，并提前报告版本差异。

它会返回：

• drift — 当来源声明了相互冲突的主版本，或某个来源的版本 完全低于 package.json 声明的最低版本时为 true
• sources — 每个提供的来源对应一项，其中包含原始声明字符串、 找到的主版本（按升序排列且不重复），以及来源无法锁定主版本时 的说明（例如 CI 的 node-version-file 键）
• issues — 按固定顺序排列：MAJOR_MISMATCH（不同来源之间 存在不同主版本）、BELOW_MINIMUM（某个来源的版本完全低于 package.json 中的最低主版本）、UNPINNED_IMAGE（Dockerfile 中的 FROM node 没有数字标签，例如 lts-alpine 或 latest）， 以及 NO_ENGINES（package.json 未声明 engines.node）

提取说明：对于 engines 范围，声明的最低版本是其中提及的最小主版本 （>=20 表示 20，^18.2 表示 18，20.x 表示 20，而单独的 * 表示未声明版本）。CI 值可以是标量、内联矩阵列表（如 [20, 22]）， 也可以是键下方的 YAML 块列表。会扫描 Dockerfile 中的每个阶段，因此 多阶段构建会报告每一行 FROM node。CI 配置或 Dockerfile 缺失本身 不会被视为问题。纯本地计算：不联网、不需要配置，工具本身不会读取任何文件。

CLI

npx @reneturcios/enginedrift check --package-json package.json --ci .github/workflows/ci.yml --dockerfile Dockerfile
npx @reneturcios/enginedrift --version

--ci 和 --dockerfile 标志是可选的。结果以 JSON 格式输出。退出代码： 检查运行成功时为 0（版本差异是数据，不是错误）；发生运行时错误时为 1 （包括文件不可读或 package.json 无效）；发生用法错误时为 2。

MCP 服务

npx -y @reneturcios/enginedrift mcp

MCP 客户端配置：

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

工具

• check_engine_drift — 比较 package.json、CI 配置和 Dockerfile 中声明的 Node 主版本，并报告版本差异。
  • package_json（字符串，必填）— package.json 文本；其中的 engines.node 范围是基准来源
  • ci_yaml（字符串，可选）— CI 工作流 YAML 文本； 提取其中的 node-version 值
  • dockerfile（字符串，可选）— Dockerfile 文本；提取其中的 FROM node 镜像标签

Docker

docker run -i ghcr.io/cloudcorprecords/enginedrift
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/enginedrift check --package-json /w/package.json --dockerfile /w/Dockerfile

开发

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