ln-711-npm-upgrader

| Aspect | Details |

|--------|---------|

| Input | Project path, package manager type |

| Output | Updated package.json, lock file, migration report |

| Supports | npm, yarn (classic & berry), pnpm |

---

See [diagram.html](diagram.html) for visual workflow.

Phases: Pre-flight → Analyze → Security Audit → Check Outdated → Identify Breaking → Apply Upgrades → Apply Migrations → Verify Build → Report

---

| Check | Required | Action if Missing |

|-------|----------|-------------------|

| Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml) | Yes | Warn and run npm install first |

| package.json | Yes | Block upgrade |

> Workers assume coordinator (ln-710) already verified git state and created backup.

---

Read package.json and categorize dependencies for upgrade priority.

Dependency Categories

| Category | Examples | Priority |

|----------|----------|----------|

| framework | react, vue, angular | 2 (after peer deps) |

| build | vite, webpack, esbuild | 3 |

| ui | @radix-ui/*, tailwindcss | 4 |

| state | @tanstack/react-query, zustand | 5 |

| utils | lodash, date-fns | 6 |

| dev | eslint, prettier, typescript | 7 |

| peer | @types/*, typescript | 1 (first) |

---

Commands

| Manager | Command |

|---------|---------|

| npm | npm audit --audit-level=high |

| yarn | yarn audit --level high |

| pnpm | pnpm audit --audit-level high |

Actions

| Severity | Action |

|----------|--------|

| Critical | Block upgrade, report |

| High | Warn, continue |

| Moderate/Low | Log only |

---

Commands

| Manager | Command |

|---------|---------|

| npm | npm outdated --json |

| yarn | yarn outdated --json |

| pnpm | pnpm outdated --json |

---

Detection

1. Compare current vs latest major versions
2. Check [breaking_changes_patterns.md](../ln-710-dependency-upgrader/references/breaking_changes_patterns.md)
3. Query Context7/Ref for migration guides

Common Breaking Changes

> See [breaking_changes_patterns.md](../ln-710-dependency-upgrader/references/breaking_changes_patterns.md) for full patterns.

| Package | Breaking Version | Key Changes |

|---------|------------------|-------------|

| react | 18 → 19 | JSX Transform, ref as prop |

| vite | 5 → 6 | ESM only, Node 18+ |

| eslint | 8 → 9 | Flat config required |

| tailwindcss | 3 → 4 | CSS-based config |

| typescript | 5.4 → 5.5+ | Stricter inference |

---

Upgrade Order

1. Peer dependencies (TypeScript, @types/*)
2. Framework packages (React, Vue core)
3. Build tools (Vite, webpack)
4. UI libraries (after framework)
5. Utilities (lodash, date-fns)
6. Dev dependencies (testing, linting)

Commands

| Manager | Command |

|---------|---------|

| npm | npm install @latest --save |

| yarn | yarn add @latest |

| pnpm | pnpm add @latest |

Peer Dependency Conflicts

| Situation | Solution |

|-----------|----------|

| ERESOLVE error | npm install --legacy-peer-deps |

| Still fails | npm install --force (last resort) |

---

Priority Order (Fallback Strategy)

| Priority | Tool | When to Use |

|----------|------|-------------|

| 1 | mcp__context7__query-docs | First choice for library docs |

| 2 | mcp__Ref__ref_search_documentation | Official docs and GitHub |

| 3 | WebSearch | Latest info, community solutions |

Context7 Usage

| Step | Tool | Parameters |

|------|------|------------|

| 1. Find library | mcp__context7__resolve-library-id | libraryName: "react", query: "migration guide" |

| 2. Query docs | mcp__context7__query-docs | libraryId: "/facebook/react", query: "react 18 to 19 migration" |

MCP Ref Usage

| Action | Tool | Query Example |

|--------|------|---------------|

| Search | mcp__Ref__ref_search_documentation | "react 19 migration guide breaking changes" |

| Read | mcp__Ref__ref_read_url | URL from search results |

WebSearch Fallback

Use when Context7/Ref return no results:

• " breaking changes migration 2025"
• " fix stackoverflow"

---

Process

1. Use MCP tools (see section above) to find migration guide
2. Apply automated code transforms via Edit tool
3. Log manual migration steps for user

> Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.

---

Commands

| Check | Command |

|-------|---------|

| TypeScript | npm run check or npx tsc --noEmit |

| Build | npm run build |

| Tests | npm test (if available) |

On Failure

1. Identify failing package from error
2. Search Context7/Ref for fix
3. If unresolved: rollback package, continue with others

---

Report Schema

| Field | Description |

|-------|-------------|

| project | Project path |

| packageManager | npm, yarn, or pnpm |

| duration | Total time |

| upgrades.major[] | Breaking changes applied |

| upgrades.minor[] | Feature updates |

| upgrades.patch[] | Bug fixes |

| migrations[] | Applied migrations |

| skipped[] | Already latest |

| buildVerification | PASSED or FAILED |

| warnings[] | Non-blocking issues |

---

```yaml

Options:

# Upgrade scope

upgradeType: major # major | minor | patch

# Breaking changes

allowBreaking: true

autoMigrate: true

queryMigrationGuides: true # Use Context7/Ref

# Security

auditLevel: high # none | low | moderate | high | critical

minimumReleaseAge: 14 # days

# Peer dependencies

legacyPeerDeps: false

force: false

# Verification

runBuild: true

runTests: false

runTypeCheck: true

# Rollback

createBackup: true

rollbackOnFailure: true

```

---

| Error | Cause | Solution |

|-------|-------|----------|

| ERESOLVE | Peer dep conflict | --legacy-peer-deps |

| ENOENT | Missing lock file | npm install first |

| Build fail | Breaking change | Apply migration via Context7 |

| Type errors | Version mismatch | Update @types/* |

Rollback

Restore package.json and lock file from git, then run clean install to restore previous state.

---

• [breaking_changes_patterns.md](../ln-710-dependency-upgrader/references/breaking_changes_patterns.md)
• [npm_peer_resolution.md](references/npm_peer_resolution.md)

---

Version: 1.1.0

Last Updated: 2026-01-10