Ln 821 NPM Upgrader

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-821-npm-upgrader

Type: L3 Worker Category: 8XX Optimization

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

Overview

Workflow

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

Phase 0: Pre-flight Checks

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-820. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

Phase 1: Analyze Dependencies

Read package.json and categorize dependencies for upgrade priority.

Phase 2: Security Audit

Actions:

Phase 3: Check Outdated

Phase 4: Identify Breaking Changes

MANDATORY READ: Load breaking_changes_patterns.md for full patterns.

Detection flow:

1. Compare current vs latest major versions.
2. Check shared breaking-change patterns.
3. Query Context7 or Ref for migration guides before changing code.

Common breaking examples:

Phase 5: Apply Upgrades

Upgrade order:

1. peer dependencies
2. framework packages
3. build tools
4. UI libraries
5. utilities
6. dev dependencies

Peer dependency conflicts:

MCP Tools for Migration Search

Use MCP tools to fetch migration guides before applying non-trivial changes.

Phase 6: Apply Migrations

1. Use MCP tools to find the current migration guide.
2. Apply automated code transforms only when the guide supports them.
3. Log manual follow-up steps for the final report.

Do not hardcode migrations without checking current documentation.

Phase 7: Verify Build

On failure:

1. Identify the failing package.
2. Search Context7 or Ref for the fix.
3. If unresolved, rollback that package and continue with the remaining candidates.

Phase 8: Report Results

Configuration

Options:
  upgradeType: major          # major | minor | patch
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true
  auditLevel: high
  minimumReleaseAge: 14
  legacyPeerDeps: false
  force: false
  runBuild: true
  runTests: false
  runTypeCheck: true
  rollbackOnFailure: true

Error Handling

Rollback: Restore package.json and the lock file, then run a clean install to restore the previous state.

References

• breaking_changes_patterns.md
• npm_peer_resolution.md

Runtime Summary Artifact

MANDATORY READ: Load references/coordinator_summary_contract.md

Emit a dependency-worker summary envelope.

Managed mode:

• ln-820 passes deterministic runId and exact summaryArtifactPath
• write the summary to the provided summaryArtifactPath

Standalone mode:

• omit runId and summaryArtifactPath
• write .hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-821--{identifier}.json

Monitor (2.1.98+): For install/audit/build/test commands expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

• Package manifest analyzed and dependencies prioritized
• Security audit completed for the selected package manager
• Outdated packages identified
• Breaking changes checked via patterns plus current docs
• Upgrades applied with rollback on failure
• Build and relevant verification commands pass after upgrades
• dependency-worker summary artifact written to the managed or standalone path

Version: 1.1.0 Last Updated: 2026-01-10