---

name: ln-711-npm-upgrader description: Upgrades npm/yarn/pnpm dependencies with breaking change handling

ln-711-npm-upgrader

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader

Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.

---

Overview

---

Workflow

See diagram.html for visual workflow.

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

---

Phase 0: Pre-flight Checks

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

---

Phase 1: Analyze Dependencies

Read package.json and categorize dependencies for upgrade priority.

Dependency Categories

---

Phase 2: Security Audit

Commands

Actions

---

Phase 3: Check Outdated

Commands

---

Phase 4: Identify Breaking Changes

Detection

1. Compare current vs latest major versions
2. Check breaking_changes_patterns.md
3. Query Context7/Ref for migration guides

Common Breaking Changes

See breaking_changes_patterns.md for full patterns.

---

Phase 5: Apply Upgrades

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

Peer Dependency Conflicts

---

MCP Tools for Migration Search

Priority Order (Fallback Strategy)

Context7 Usage

MCP Ref Usage

WebSearch Fallback

Use when Context7/Ref return no results:

• "<package> <version> breaking changes migration 2025"
• "<package> <error message> fix stackoverflow"

---

Phase 6: Apply Migrations

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.

---

Phase 7: Verify Build

Commands

On Failure

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

---

Phase 8: Report Results

Report Schema

---

Configuration

CopyOptions:
  # 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 Handling

Rollback

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

---

References

• breaking_changes_patterns.md
• npm_peer_resolution.md

---

Version: 1.1.0 Last Updated: 2026-01-10