node-deps-bumper

Node Dependency Bumper

使用 Taze 制定一份结构化更新计划，应用兼容的范围更新，并批量决定主版本更新。

添加依赖

添加新软件包或 CLI 时，请使用仓库的包管理器和现有的版本范围约定，而不是 Taze。允许安装 package@latest 并保留包管理器生成的 ^x.y.z 范围。不要仅仅因为插入符范围允许未来版本，就将其替换为精确版本。

如果存在有效的包管理器最短发布时间策略，该策略将决定候选版本的新鲜度边界。在这种情况下，请阅读 references/conditional-workflows.md。已提交的锁文件和冻结部署安装可保证可复现性。仅当用户或仓库要求、已知兼容性限制有充分理由，或软件包将在没有已提交锁文件和冻结安装的情况下运行时，才使用精确版本固定。

多个仓库

如果用户指定两个或更多仓库，或要求在多个仓库间同步或对齐依赖，请阅读 references/multi-repo-alignment.md。该流程会对每个仓库执行下方的工作流，并增加共享目标选择、一次跨仓库主版本批处理，以及每个仓库各自的提交。

工作流

1. 确定技能目录，并从目标仓库保存辅助计划：

   bash <skill-dir>/scripts/run-taze.sh --plan [--include package-a,package-b] > <taze-plan.json>
   

   JSON 计划会将每个发现的更新分类为 apply、review-major、review 或 skip-fixed。辅助工具会检测单体仓库，在扫描时纳入已锁定的版本，并镜像 Bun 的最短发布时间设置。如果仓库使用包管理器的发布时间门槛或 Bun catalogs，请仅针对当前生效的分支阅读 references/conditional-workflows.md。

2. 如果请求了 --dry-run，则展示计划和数量，然后停止，不更改清单或锁文件。

3. 选择所有标记为 apply 的范围内次版本/补丁版本更新。复用对软件包/版本变更的明确批准。绝不要仅凭软件包名称自动批准主版本更新。将尚未处理的 review-major 和未知更新合并为一批进行决策，并提供当前版本、目标版本、软件包用途以及相关迁移说明/发行说明。仅应用已获授权的主版本更新。

4. 如果没有选中的更新，则报告无操作并停止。如果根清单使用 Bun catalogs，请预览已接受计划中确切的已选 catalog 变更。仅传入 catalog 中存在的软件包。如果该子集为空，则跳过辅助工具：

   uv run <skill-dir>/scripts/update-bun-catalogs.py \
     --root <repo> --plan <taze-plan.json> --include package-a,package-b
   

   预览为只读操作。缺少 catalog 条目、计划行冲突、不支持的版本，或 catalog 值与计划不再匹配时，都会在写入前失败。辅助工具不会选择升级。

5. 首次写入清单或锁文件之前，选择并运行一个基线检查，以检测所选更新导致的回归。遵循仓库要求的检查。否则，根据更新软件包的实际使用方和风险，选择依赖解析、构建、测试、类型检查、代码检查、格式检查、代码生成或不变量检查。仅仅因为存在汇总套件，不要在共享工具链或运行时发生变更之外使用它。尽可能使用冻结或非写入模式，并记录更新后重跑所用的确切命令和覆盖范围。 在判断是否会阻止升级之前，先归因每项失败。如果与升级无关的既有失败可复现、可在升级后进行比较，且不会妨碍依赖解析或检测回归所需的检查，则继续升级。不要将该失败作为升级的一部分修复。依赖或 peer 解析冲突、可采取行动的不安全行为，或无法提供可靠前后对比信号的基线，都会阻止升级。遇到这种情况，请停止并输出 ### ⛔ Dependency bump blocked — baseline unusable，报告确切的前置条件和诊断信息，无需请求重复授权。无法避免的弃用等信息性通知不会阻止升级。

6. 对于 Bun catalogs，先应用预览的变更：使用相同的计划和 catalog include 子集，重新运行 update-bun-catalogs.py 并添加 --write。该操作会以原子方式更新每个匹配的默认/命名 catalog 条目，并保留现有的 ^、~ 或空前缀。请在 Taze 之前应用，因为 Taze 原生的 catalog 写入会使此计划过时。

   然后通过一条命令写入所有选定的 Taze 更新：

   bash <skill-dir>/scripts/run-taze.sh --write --include package-a,package-b
   

7. 运行 ni，让仓库的包管理器更新其锁文件。

8. 检查清单和锁文件的差异。重新运行精确的基线命令，以及能够覆盖已更新依赖项和任何必需迁移的最精简检查。除非有证据表明并非由升级导致，否则将每项新引入的错误、类型问题、检查失败（包括测试、构建、lint、格式化、代码生成和仓库不变量）、依赖或 peer 解析冲突，以及可采取行动的兼容性或安全警告，都视为由升级导致。

9. 修复升级导致的所有问题，包括必需的源代码或配置迁移，同时保持预期行为。不要仅为通过检查而抑制诊断、降低验证标准或改变预期行为。每次修复后，重新运行输入或行为发生变化的检查。完成时，要求针对最终状态，记录的整套检查均有有效结果，且相对于已接受的基线没有新增失败。输入未变的通过结果可以复用。只有符合第 5 步比较要求、且与升级无关的既有失败可以保留。

   如果在任务授权范围内没有明确安全的修复方案，请停止并输出 ### ⚠️ Dependency regression decision required。将所有此类问题及其证据、受影响位置、修复和回退选项、可能影响汇总到一个表格中。在用户作出选择、应用修复或回退有问题的更新、重新生成锁文件，并且整套检查满足相同的基线比较要求之前，不要报告完成。

面向用户的输出

使用 ### 📦 Dependency plan 展示计划，包含数量和简洁表格：

ID	Plan value	Decision	Package	Current → target	Type	Notes

将计划中的 apply、review-major、review 和 skip-fixed 原样列出，并附上通俗易懂的决策说明。为需要用户选择的行分配稳定 ID，以便用户一次性作答。预览时使用 ### 🔎 Dry run — no files written，无操作时使用 ### ✅ No selected updates。

已应用的更新完成后，使用 ### 🏁 Dependencies updated，列出已更改清单/锁文件的树状结构，并添加 ### 🧪 Verification。仅对不会阻止升级的信息性事项使用 ### ⚠️ Remaining review，绝不可用于尚未解决的升级导致的问题。辅助 JSON、包/版本字符串、命令和诊断信息必须保持原样，不得加装饰。

不变量

• 除非用户明确要求，否则固定版本和非 SemVer 协议保持不变。
• 对于新依赖和 CLI，插入符范围有效。如果提交的锁文件和冻结安装能够控制解析，则不要将其描述为不可复现。
• 包参数会限制扫描和写入阶段。
• 扫描和写入采用相同的成熟期策略。
• Bun catalog 的预览和写入使用相同的、已接受的 Taze 计划和所选包集。过时的计划绝不会执行写入。
• 如果仓库证据、对等依赖范围或发布说明表明情况并非如此，则不要仅凭 SemVer 推断兼容性。

完成工作需要具备带有归属信息且可安全比较的写入前基线、经过审查的计划、保留所选更新、重新生成的锁文件、记录的测试套件或依赖项专属检查中没有新增失败，并且不存在由升级导致的未解决问题。试运行完成则需要结构化计划且写入次数为零。