update-deps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Dependencies

更新依赖项

Audit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.
This process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.
审计过时包、验证供应链完整性、升级安全的包、暂存需要审核的包,并记录所有操作。
此流程分为三个阶段:发现、完整性审计和执行。其中完整性审计是最重要的环节——每个包在修改锁文件前都会经过检查。

Phase 1: Discovery

阶段1:发现

Run
bun outdated
to get the full list of packages with available updates.
bash
bun outdated
Parse the output into a structured list. For each package, note:
  • Package name
  • Current version
  • Available update version
  • Whether it's age-gated (indicated by
    *
    in the output — the footnote "The * indicates that version isn't true latest due to minimum release age" confirms this)
  • Whether it's a runtime dep, dev dep, or peer dep
Also check whether any packages are blocked entirely by the age gate (like
@pierre/diffs
was when its minimum semver range couldn't resolve). Flag these separately — they may need
minimumReleaseAgeExcludes
in
bunfig.toml
.
运行
bun outdated
获取所有可更新包的完整列表。
bash
bun outdated
将输出解析为结构化列表。针对每个包,记录:
  • 包名称
  • 当前版本
  • 可用更新版本
  • 是否受发布时长限制(输出中的
    *
    标识——脚注“*表示该版本因最低发布时长要求并非真正的最新版本”可确认这一点)
  • 它是运行时依赖、开发依赖还是对等依赖
同时检查是否有包完全被发布时长限制阻挡(比如
@pierre/diffs
在其最小语义化版本范围无法解析时的情况)。单独标记这些包——它们可能需要在
bunfig.toml
中配置
minimumReleaseAgeExcludes

Phase 2: Integrity Audit

阶段2:完整性审计

This is the core of the process. Spawn one Sonnet sub-agent per package to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.
Each sub-agent receives the package name, current version, and target version, and performs the following checks:
这是流程的核心。为每个包启动一个Sonnet子代理来并行执行完整性检查。此处使用Sonnet是因为这些是独立的结构化验证任务,不需要复杂的推理能力。
每个子代理会收到包名称、当前版本和目标版本,并执行以下检查:

Sub-agent prompt template

子代理提示模板

For each outdated package, spawn a Sonnet agent with this task:
You are auditing the npm package "{package}" for a version bump from {current} to {target}.

Run these checks and report back with a JSON object:

1. **Maintainer verification**: Check if maintainers changed between versions.
   npm view {package}@{current} maintainers --json
   npm view {package}@{target} maintainers --json
   Compare the two lists. Flag any additions or removals.

2. **Publish date and age**: Get the publish timestamp.
   npm view {package} time --json
   Extract the date for version {target}. Calculate days since publication.
   Flag if younger than 7 days.

3. **Provenance**: Check if the package has registry signatures or attestations.
   npm audit signatures (if not already run this session)
   Note whether the package has provenance attestations.

4. **Tarball diff**: Show what actually changed in the published package.
   npm diff --diff={package}@{current} --diff={package}@{target}
   Summarize the changes:
   - How many files changed
   - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?
   - Any new runtime dependencies added?
   - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)

5. **Release notes**: Try to find what changed.
   Check the package's repository for release notes or changelog:
   npm view {package}@{target} repository.url
   gh release view v{target} --repo <owner/repo> (try with and without v prefix)
   Summarize the changelog if found.

Report your findings as JSON:

{{
  "package": "{package}",
  "from": "{current}",
  "to": "{target}",
  "age_days": <number>,
  "maintainers_changed": <boolean>,
  "maintainers_added": [],
  "maintainers_removed": [],
  "provenance": <boolean>,
  "new_runtime_deps": [],
  "files_changed": <number>,
  "has_source_changes": <boolean>,
  "changelog_summary": "<brief summary>",
  "suspicious_patterns": [],
  "verdict": "safe" | "review" | "defer",
  "verdict_reason": "<one sentence explanation>"
}}

Verdict guidelines:
- "safe": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns
- "review": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)
- "defer": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing
针对每个过时包,启动一个Sonnet代理并分配以下任务:
You are auditing the npm package "{package}" for a version bump from {current} to {target}.

Run these checks and report back with a JSON object:

1. **Maintainer verification**: Check if maintainers changed between versions.
   npm view {package}@{current} maintainers --json
   npm view {package}@{target} maintainers --json
   Compare the two lists. Flag any additions or removals.

2. **Publish date and age**: Get the publish timestamp.
   npm view {package} time --json
   Extract the date for version {target}. Calculate days since publication.
   Flag if younger than 7 days.

3. **Provenance**: Check if the package has registry signatures or attestations.
   npm audit signatures (if not already run this session)
   Note whether the package has provenance attestations.

4. **Tarball diff**: Show what actually changed in the published package.
   npm diff --diff={package}@{current} --diff={package}@{target}
   Summarize the changes:
   - How many files changed
   - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?
   - Any new runtime dependencies added?
   - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)

5. **Release notes**: Try to find what changed.
   Check the package's repository for release notes or changelog:
   npm view {package}@{target} repository.url
   gh release view v{target} --repo <owner/repo> (try with and without v prefix)
   Summarize the changelog if found.

Report your findings as JSON:

{{
  "package": "{package}",
  "from": "{current}",
  "to": "{target}",
  "age_days": <number>,
  "maintainers_changed": <boolean>,
  "maintainers_added": [],
  "maintainers_removed": [],
  "provenance": <boolean>,
  "new_runtime_deps": [],
  "files_changed": <number>,
  "has_source_changes": <boolean>,
  "changelog_summary": "<brief summary>",
  "suspicious_patterns": [],
  "verdict": "safe" | "review" | "defer",
  "verdict_reason": "<one sentence explanation>"
}}

Verdict guidelines:
- "safe": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns
- "review": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)
- "defer": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing

Collecting results

收集结果

As sub-agents complete, collect their JSON reports. If a sub-agent fails or times out, mark that package as "defer" with reason "audit failed".
子代理完成任务后,收集它们的JSON报告。如果子代理失败或超时,将该包标记为“defer”,原因是“审计失败”。

Tier classification

层级分类

After collecting all results, classify packages into tiers. This helps the user understand the risk profile at a glance:
TierDescriptionTypical action
Runtime, high surfaceLibraries your code calls directly (parsers, diff engines, UI libs)Check provenance, review diff, run tests
SDK/API depsThird-party service SDKs (agent SDKs, platform integrations)Read changelog for API changes, test integration
Dev-onlyType definitions, build tools, test frameworksUpdate freely — these don't ship
Build toolchainBun itself, compilers, bundlersMost caution — breakage affects all outputs
收集所有结果后,将包分为不同层级。这有助于用户快速了解风险概况:
层级描述典型操作
运行时,高暴露面代码直接调用的库(解析器、差异引擎、UI库)查看来源信息、审核差异、运行测试
SDK/API依赖第三方服务SDK(Agent SDK、平台集成)查看变更日志中的API改动、测试集成
仅开发环境类型定义、构建工具、测试框架自由更新——这些不会随产品发布
构建工具链Bun本身、编译器、打包器需格外谨慎——故障会影响所有输出

Phase 3: Execution

阶段3:执行

Bump safe packages

升级安全包

For all packages with verdict "safe":
bash
bun update pkg1@version1 pkg2@version2 ...
If the update fails due to age gate conflicts (a package's minimum semver can't resolve), add it to
minimumReleaseAgeExcludes
in
bunfig.toml
and document why.
针对所有判定为“safe”的包:
bash
bun update pkg1@version1 pkg2@version2 ...
如果因发布时长限制冲突导致更新失败(包的最小语义化版本无法解析),将其添加到
bunfig.toml
minimumReleaseAgeExcludes
中并记录原因。

Log to supply chain notes

记录到供应链笔记

Write the full audit results to
~/.supply-chain/notes/<YYYY-MM-DD>.json
:
json
{
  "date": "YYYY-MM-DD",
  "project": "plannotator",
  "bumped": [
    {
      "package": "...",
      "from": "...",
      "to": "...",
      "age_days": 0,
      "maintainers_changed": false,
      "provenance": false,
      "notes": "..."
    }
  ],
  "deferred": [
    {
      "package": "...",
      "current": "...",
      "available": "...",
      "age_days": 0,
      "maintainers_changed": false,
      "reason": "...",
      "review_by": "YYYY-MM-DD"
    }
  ],
  "excluded_from_age_gate": [
    {
      "package": "...",
      "reason": "..."
    }
  ]
}
Set
review_by
to 7 days from today for deferred packages.
将完整的审计结果写入
~/.supply-chain/notes/<YYYY-MM-DD>.json
json
{
  "date": "YYYY-MM-DD",
  "project": "plannotator",
  "bumped": [
    {
      "package": "...",
      "from": "...",
      "to": "...",
      "age_days": 0,
      "maintainers_changed": false,
      "provenance": false,
      "notes": "..."
    }
  ],
  "deferred": [
    {
      "package": "...",
      "current": "...",
      "available": "...",
      "age_days": 0,
      "maintainers_changed": false,
      "reason": "...",
      "review_by": "YYYY-MM-DD"
    }
  ],
  "excluded_from_age_gate": [
    {
      "package": "...",
      "reason": "..."
    }
  ]
}
为暂存的包设置
review_by
为当前日期起7天后。

Check previously deferred packages

检查之前暂存的包

Read all files in
~/.supply-chain/notes/
and collect any deferred packages from previous audits that are still at the same version in the current lockfile. These are packages that were deferred before and still haven't been updated.
To check: for each previously deferred entry, see if the current installed version matches the
current
field from the deferral note. If it does, the package is still deferred.
读取
~/.supply-chain/notes/
中的所有文件,收集之前审计中暂存且当前锁文件中版本仍未更新的包。这些是之前被暂存但尚未升级的包。
检查方式:对于每个之前的暂存条目,查看当前安装版本是否与暂存记录中的
current
字段匹配。如果匹配,则该包仍处于暂存状态。

Phase 4: Recap

阶段4:总结

Present a clear summary to the user:
向用户呈现清晰的总结:

Updated

已更新

List each bumped package with version change and one-line reason it was safe.
列出每个升级的包、版本变更以及判定为安全的一行理由。

Deferred

已暂存

List each deferred package with version change and reason for deferral.
列出每个暂存的包、版本变更以及暂存原因。

Still Deferred (from previous audits)

仍暂存(来自之前的审计)

List any packages that were deferred in previous audit sessions and still haven't been bumped. Include the original deferral date and reason. This is the "you've been putting this off" section — it keeps deferred packages from being forgotten.
If the still-deferred list is empty, say so — that's a good sign.
列出所有在之前审计中被暂存且尚未升级的包。包含最初的暂存日期和原因。这是“你一直拖延的任务”部分——避免暂存的包被遗忘。
如果仍暂存的列表为空,说明情况良好。

Age Gate Exclusions

发布时长限制例外

If any packages were added to
minimumReleaseAgeExcludes
, note them and why.
如果有包被添加到
minimumReleaseAgeExcludes
,记录它们及其原因。