imvanzen/maintenance

Dependency Maintenance

When to apply

• User asks to fix audit, resolve vulnerabilities, update packages, upgrade dependencies, or run maintenance.
• User wants to address Dependabot/audit findings or keep dependencies current without introducing breaking changes.

Goals

• Security first: Resolve high/critical vulnerabilities; prefer minimal version bumps that fix the issue.
• Value over churn: Apply updates that bring security fixes or useful features; avoid upgrades that mainly introduce breaking API changes.
• Minimize breakage: Prefer patch and minor updates; treat major upgrades as opt-in and document impact.

Procedure

Step 1: Detect package manager and run audit

1. Determine package manager from repo: packageManager in root package.json, or presence of pnpm-lock.yaml / package-lock.json / yarn.lock.
2. Run audit (from repo root):
   • pnpm: pnpm audit
   • npm: npm audit
3. Capture output: vulnerability count by severity (critical, high, moderate, low), and which packages are affected.
4. If audit returns 0 vulnerabilities, proceed to Step 2. Otherwise note findings for Step 4.

Step 2: List outdated packages

1. Run outdated (from repo root):
   • pnpm: pnpm outdated
   • npm: npm outdated
2. Parse output into: package name, current version, latest version.
3. Classify each outdated package by version bump type:
   • Patch (e.g. 20.3.1 → 20.4.1): safe, apply.
   • Minor (e.g. 2.7.6 → 2.8.9): generally safe; apply unless project rules say otherwise.
   • Major (e.g. 9.x → 10.x): breaking; do not apply by default—list and recommend separate PR or explicit user approval.

Step 3: Prioritization matrix

Order of operations:

| Priority | Category | Action | |----------|----------|--------| | 1 | Audit: critical/high | Fix via minimal version bump or pnpm.overrides (pnpm) / overrides (npm). Prefer pnpm update <pkg> or audit fix only when it doesn’t jump major. | | 2 | Audit: moderate/low | Same as above; can batch with non-breaking updates. | | 3 | Outdated: patch | Update (e.g. pnpm update --latest scoped to patch, or per-package update). | | 4 | Outdated: minor | Update if no known breaking changes for this project; skip if tightly coupled (e.g. eslint + eslint-config-*). | | 5 | Outdated: major | Do not update in this run. List in summary with “Major upgrade (deferred)” and note possible breaking changes; suggest separate task/PR. |

Step 4: Resolve audit findings

1. For each vulnerability, determine the minimal fix: patch or minor bump that satisfies the advisory (check pnpm audit --json or npm equivalent for “fix available”).
2. Prefer:
   • Updating only the affected package to the minimum version that fixes the issue.
   • Using pnpm.overrides (in root package.json) only when a direct update isn’t possible (transitive dep). Match existing override style in the repo.
3. Run pnpm install (or equivalent) and re-run audit to confirm vulnerabilities are gone.
4. If the only fix is a major upgrade, document it in the summary and do not apply unless the user explicitly asks to include major upgrades.

Step 5: Apply non-breaking package updates

1. Apply patch and minor updates only. For pnpm:
   • Per-package: pnpm update <pkg> (respects semver range) or pnpm update <pkg> --latest only when targeting a specific minor.
   • Prefer pnpm update (no args) to bump within current ranges, then re-run pnpm outdated to see remaining; for explicit latest patch/minor use pnpm update <pkg>@<version>.
2. Avoid pnpm update -r --latest (or npm equivalent that pulls majors) unless user explicitly requested “update everything including major.”
3. After updates: run pnpm install, then pnpm audit and pnpm outdated again; run lint and tests (e.g. pnpm lint, pnpm test) to confirm no regressions.

Step 6: Summary and deferred items

Produce a short summary:

## Maintenance Summary

### Audit
- Resolved: X vulnerabilities (critical/high/moderate/low).
- Remaining: (if any) list and reason (e.g. fix requires major upgrade).

### Updated (patch/minor)
- package@old → new
- ...

### Deferred (major upgrades)
- package@current → latest (major) – reason (e.g. breaking API changes; handle in separate PR).

Add any new overrides or lockfile changes to the same commit/PR as the rest of maintenance.

Decision rules

• Security vs breaking: A fix that requires a major upgrade is still applied only if the user explicitly opts in; otherwise resolve via override or document as deferred.
• Monorepo: Run audit and update from root; use filters (e.g. pnpm --filter) only when updating a specific workspace is required.
• Overrides: Prefer the same override style as in the repo (e.g. pnpm.overrides with >=X.Y.Z). Don’t remove existing overrides unless they’re obsolete and safe to drop.
• Lockfile: Always run install after changes and commit updated lockfile.

Constraints

• Do not upgrade to a major version unless the user explicitly requests it or approves after being shown the deferred list.
• Do not run destructive commands (e.g. pnpm store prune without user consent) or remove lockfiles.
• After any update, run the project’s lint and test commands and report failures.

Validation before finishing

• [ ] Audit re-run shows no new unresolved critical/high (or user accepted remaining).
• [ ] Only patch/minor updates applied (or explicit user approval for major).
• [ ] Lockfile and, if used, overrides are consistent and committed.
• [ ] Lint and tests passed (or failures documented for user).