fix-audit - SKILL.md Agent Skill

name: fix-audit description: Fix pnpm audit vulnerabilities. Upgrades packages, adds overrides, handles minimumReleaseAge restrictions, and cleans up stale overrides. user-invocable: true allowed-tools: Bash, Read, Edit, Write, Grep, Glob

Fix pnpm Audit Vulnerabilities

Fix all vulnerabilities reported by pnpm audit. Follow each phase in order.

Phase 1: Audit and Identify

Run pnpm audit --json and capture the output.
Parse the JSON to build a list of vulnerabilities with: package name, current version, patched/fixed version, severity, and the path (which top-level dependency pulls it in).
If there are no vulnerabilities, report that and stop.
Present a summary table of all findings to the user before proceeding.

Phase 2: Upgrade Packages Directly

For each vulnerability, attempt a direct upgrade first:

If the vulnerable package is a direct dependency (in root or workspace package.json), run:
```
pnpm update <package>@<fixed-version> --filter <workspace>
```
If it's a transitive dependency, run:
```
pnpm update <package> --recursive
```
After all upgrades, run pnpm audit --json again to check which vulnerabilities remain.
Report what was fixed and what remains.

Phase 3: Add Overrides for Remaining Issues

For vulnerabilities not fixed by direct upgrades:

Read the current pnpm.overrides from the root package.json.
Add override entries for the vulnerable packages pinning them to the fixed versions:
```
"pnpm": {
  "overrides": {
    "<package>": "<fixed-version>"
  }
}
```
Scoped overrides: When a package has multiple major versions (e.g., brace-expansion 1.x, 2.x, 4.x), use pnpm's version selector syntax to avoid breaking incompatible consumers:
```
"brace-expansion@>=4": ">=5.0.5"
```
An unscoped override like "brace-expansion": ">=5.0.5" would force ALL consumers to 5.x, breaking packages that depend on 1.x or 2.x APIs.
Run pnpm install to apply the overrides.

Phase 4: Handle minimumReleaseAge Failures

If pnpm install fails because a package version cannot be found (error messages like ERR_PNPM_FETCH_404, No matching version found, or package not found), this is likely because the fixed version was published recently and is blocked by minimumReleaseAge: 2880 in pnpm-workspace.yaml.

To work around this:

Read pnpm-workspace.yaml and note the current minimumReleaseAge value.
Temporarily comment out the minimumReleaseAge line (and its preceding comment lines):
```
# minimumReleaseAge: 2880
```
Run pnpm install to update the lockfile.
Immediately restore the minimumReleaseAge line to its original value:
```
minimumReleaseAge: 2880
```
Verify with pnpm install that the lockfile is now consistent with the age restriction re-enabled. If this second install fails, the package truly cannot be resolved — remove that override and report the issue to the user.

CRITICAL: Never leave minimumReleaseAge commented out. Always restore it, even if subsequent steps fail.

Alternative: Use minimumReleaseAgeExclude in pnpm-workspace.yaml instead of commenting out the age restriction:

minimumReleaseAgeExclude:
  - path-to-regexp

This is safer but should still be removed after the lockfile is updated.

Phase 5: Clean Up Stale Overrides

After the lockfile is updated, check whether any existing overrides in pnpm.overrides are now unnecessary:

Read the current pnpm.overrides from root package.json.
Remove ALL overrides, run pnpm install to regenerate the lockfile, then run pnpm audit --json.
Check which vulnerabilities reappear — only those overrides are still needed.
Add back only the needed overrides, run pnpm install to apply.

Important: You must run pnpm install after changing overrides because pnpm audit checks the lockfile, and the lockfile retains previously resolved versions until regenerated. Simply removing an override and running audit without install will show the old (safe) versions and give a false "stale" result.

Phase 6: Fix Version Mismatches

Run pnpm manypkg fix to ensure any upgraded packages have consistent version ranges across all workspace package.json files.

Phase 7: Final Verification

Run pnpm audit one final time and report the results.
Run pnpm install --frozen-lockfile to verify the lockfile is consistent.
Summarize all changes made:
- Packages upgraded directly
- Overrides added
- Overrides removed (stale)
- Any vulnerabilities that could not be fixed (and why)