pnpm-audit-fix

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

Severity	Report	Default fix (after confirm)	Optional fix
critical	Yes	Yes	—
high	Yes	Yes	—
moderate	Yes	Yes	User may exclude (e.g. only high/critical)
low	Yes (summary + detail)	No	Yes, if user explicitly requests

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, github_advisory_id, 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.

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:

The above is the remediation plan for moderate and above vulnerabilities (default scope). Please confirm whether to proceed?

• Reply "confirm" → fix all moderate / high / critical
• Reply "high/critical only" → skip moderate
• Reply "include low" → also fix low in addition to the default scope
• Reply "cancel" → do not modify any files
• Or specify item numbers (e.g. "only fix 1, 3")

Resolve the approved scope before Step 5:

User says	Approved scope
confirm / all / yes	moderate + high + critical
high/critical only	high + critical only
include low / with low	moderate + high + critical + low
item numbers	Only listed items
cancel / no	Stop — no changes

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

Situation	Plan
actions[].action === "update" with target	Bump to target via direct update or override
Direct dep, semver-compatible patch	pnpm update <pkg>@<version>
Transitive only	pnpm.overrides
action === "review"	Manual review — document risk, do not auto-fix
Override conflicts with existing pin	Propose new version; note conflict in report
Major version jump required	Flag as breaking-change risk; require explicit user approval

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