pnpm Audit Fix

Works in any pnpm project. Applies fixes only after user confirmation.

Default fix scope: moderate, high, critical. Never auto-fix without user confirmation.

Scope

Workflow

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Verify pnpm project
- [ ] Step 2: Collect audit data
- [ ] Step 3: Build and present report
- [ ] Step 4: Wait for user confirmation
- [ ] Step 5: Apply fixes (only if confirmed)
- [ ] Step 6: Verify and summarize

Step 1: Verify pnpm project

Confirm package.json exists and the project uses pnpm (pnpm-lock.yaml or packageManager field).

Run from the project root:

pnpm --version

If pnpm is missing, report it and stop (install via corepack enable or npm i -g pnpm).

Step 2: Collect audit data

pnpm audit --json > /tmp/pnpm-audit.json 2>/dev/null || true

Validate the output before parsing: if /tmp/pnpm-audit.json is empty or not valid JSON (the || true masks command failure, e.g. registry/network error), stop and report the error — do not parse or guess versions.

To extract the structured summary, run node scripts/collect-audit.mjs (parses /tmp/pnpm-audit.json by default, or re-runs the audit itself when the file is missing). The script groups advisories by severity and marks the default scope (moderate+). Use the script output as the data source for the report; refer to the field mapping below for details.

Parse the JSON:

• advisories — vulnerability details (severity, module, versions, paths, CVE, advisory URL)
• actions — suggested fixes (update with target, or review with no auto-fix)

Default fix set: filter advisories where severity is moderate, high, or critical.

Optional fix set: filter advisories where severity is low (include in report; fix only if user requests).

For each advisory in the report, gather:

• Package name (module_name)
• Installed version (findings[0].version)
• Severity
• CVE / advisory ID (cves, githubadvisoryid, url)
• Dependency path (findings[0].paths or paths in actions)
• Patched version (patched_versions / recommendation)
• Matching actions entry (if any)

Supplement with pnpm why <package> when the dependency path is unclear.

Step 3: Build and present report

Use the template in [report-template.md](report-template.md).

Rules:

• Every default-scope item (moderate+) must have an explicit fix plan before asking for confirmation.
• Low items appear in a separate section with fix plans prepared, but marked as not included by default.
• If no moderate+ issues exist, say so clearly. If low issues exist, note them. Stop if nothing is in scope — do not modify files.
• If an issue has action: "review" only (no target), mark fix plan as manual review required and explain why.
• Prefer the smallest safe fix: direct dependency bump > pnpm.overrides > pnpm audit --fix (last resort — may add broad overrides).

Stop here. Do not edit package.json, lockfile, or overrides until the user confirms.

Step 4: Wait for user confirmation

Ask explicitly:

以上为 moderate 及以上漏洞修复计划（默认范围）。请确认是否执行？

- 回复「确认」→ 修复全部 moderate / high / critical
- 回复「仅 high/critical」→ 跳过 moderate
- 回复「包含 low」→ 在默认范围基础上一并修复 low
- 回复「取消」→ 不修改任何文件
- 或指定条目编号（如「只修 1、3」）

Resolve the approved scope before Step 5:

If the user cancels or does not confirm — stop without changes.

Step 5: Apply fixes (confirmed scope only)

Apply fixes in this order of preference:

A. Direct dependency — package is in dependencies or devDependencies:

pnpm update <package>@<patched-version>
# or edit package.json version range, then:
pnpm install

B. Transitive dependency — add or update pnpm.overrides in package.json:

"pnpm": {
  "overrides": {
    "<vulnerable-package>": "<patched-version>"
  }
}

Merge with existing overrides; do not remove unrelated entries. Then run pnpm install.

C. Bulk override — only when multiple transitive issues share the same override strategy and the user approved it:

pnpm audit --fix

Review the diff carefully — --fix may add overrides beyond the approved scope. Trim or revert any changes outside the approved scope.

After each fix batch, re-run pnpm audit --json and confirm the targeted advisories are resolved.

Step 6: Verify and summarize

pnpm audit --audit-level moderate

Deliver a post-fix summary:

• Approved scope vs. what was actually fixed
• What was changed (package.json, pnpm.overrides, lockfile)
• Which advisories are resolved
• Any remaining items in the approved scope and why (manual review, upstream blocker)
• Skipped severities (e.g. moderate excluded, or low not requested)

Run project tests or build only if the user requests or the repo has a standard check script.

Fix plan decision guide

Hard rules

• Default scope is moderate + high + critical; low only when the user explicitly includes it in Step 4.
• Never fix severities outside the approved scope.
• Never modify files before Step 4 confirmation.
• Never remove existing pnpm.overrides entries unrelated to the fix.
• Never commit unless the user asks.
• If pnpm audit --json fails (registry/network) or the saved JSON is empty/invalid, report the error and stop — do not guess versions.

Additional resources

• Report output format: [report-template.md](report-template.md)