NPM Updater

Structured workflow for updating all dependencies in a single package.json.

Step 0: Detect Package Manager

Determine package manager from lockfiles and package.json config:

Use Glob to check for lockfiles in the project root. If ambiguous, ask the user.

Install commands: npm=npm install, yarn=yarn install, pnpm=pnpm install, bun=bun install

Step 1: Discover Verification Commands

Read package.json scripts. Identify which exist:

• Type check: type-check, typecheck, tsc
• Lint: lint
• Build: build
• Test: test

Store for use in Step 7.

Step 2: Snapshot Current State

Read package.json. Record all devDependencies and dependencies with current version ranges. Group into:

1. devDependencies (update first)
2. dependencies (update second)

Step 3: Check Latest Versions

For each dependency, fetch latest version from the npm registry:

WebFetch: https://registry.npmjs.org/{exact-package-name}/latest
Prompt: "Return the version number and the repository URL (from repository.url or homepage)"

SECURITY — Package identity verification:

• Use the exact package name from package.json. Never guess or autocomplete names.
• Only use https://registry.npmjs.org/ — no other registries.
• Extract repository.url from the registry response for GitHub lookups. Never construct GitHub URLs by guessing org/repo names.
• If package name looks suspicious or metadata is unexpected, alert the user immediately.

Classify each dependency:

• Patch/minor: e.g., 2.1.0 → 2.3.1
• Major: e.g., 2.x → 3.x
• Already latest: skip

Step 4: Batch Minor/Patch Updates

4a: devDependencies (minor/patch)

Update all devDependency version ranges with minor/patch bumps in package.json. Run install. Run verification (Step 7).

If verification fails, bisect: revert and update half at a time to isolate the breaking dep.

4b: dependencies (minor/patch)

Same process for production dependencies.

Step 5: Major Updates — Changelog Analysis

For each major version bump, before updating:

5a: Fetch Changelog

Try these sources in order, using the repository.url obtained in Step 3:

1. GitHub releases: WebFetch the releases page from the verified repo URL. Prompt: "List breaking changes between v{current} and v{latest}".

2. CHANGELOG.md: WebFetch the raw CHANGELOG.md from the verified repo. Prompt: "List breaking changes between v{current} and v{latest}".

3. Context7 MCP: resolve-library-id then query-docs with "migration breaking changes version {latest}".

5b: Assess Impact

For each major bump determine:

• Breaking API changes that affect this project?
• Code migration needed?
• Is this a "big upgrade" needing a migration guide? (→ Step 6)

If breaking changes are trivial (renamed export, dropped old Node support, etc.), update directly. Apply necessary code changes, run verification.

Step 6: Major Updates — Migration Guide (User Approval Required)

Applies when:

• Package is a framework or core tool (Next.js, React, Prisma, TypeScript, ESLint, Emotion, Tailwind, etc.)
• Changelog references a migration guide
• Breaking changes are substantial

6a: Find Migration Guide

1. Repo docs: Check verified repository.url for migration/upgrade docs.

2. Official docs: WebSearch for "{package-name} migration guide v{current} to v{latest}".

3. Context7 MCP: Query "{package-name} migration guide version {latest}".

4. Codemods/CLI tools: Search for automated migration tools (e.g., npx @next/codemod, npx prisma migrate). Mention these explicitly.

5. Agent-based migration prompts: Many migration guides now include dedicated prompts or instructions for AI coding agents (e.g., LLM prompts, .cursor rules, agent migration scripts). When a migration guide is found, search within it and the surrounding repo/docs for:

   • Agent-specific migration prompts (often in markdown files, .cursor/, or labeled "AI prompt", "LLM prompt", "agent instructions")
   • Automated agent-driven migration workflows or CLI flags (e.g., --agent, --ai)
   • WebSearch for "{package-name} v{latest} migration AI agent prompt" or "{package-name} v{latest} cursor migration"

   If any agent-based migration prompt or tool is found, always surface it to the user in Step 6b — these are the highest-quality migration paths and should be preferred over manual guide-following.

6b: Present to User for Approval

MANDATORY — before following any migration guide:

AskUserQuestion:
"Found migration guide for {package} v{current} → v{latest}:
{link-to-guide}

Key breaking changes:
- {change 1}
- {change 2}

Approach: {describe how you'll follow the guide, mention codemods if available}

Proceed with this migration?"
Options: ["Yes, follow the guide", "Skip this upgrade", "Let me review first"]

6c: Execute Migration

Only after user approval:

1. Follow migration guide step by step
2. Run codemods if available
3. Update package.json, run install
4. Run verification (Step 7)

Step 7: Verification

Run discovered commands from Step 1 sequentially, stop on first failure:

1. {manager} install
2. Type check (if available): {manager} run {type-check-script}
3. Lint (if available): {manager} run lint
4. Build (if available): {manager} run build

On failure:

• Read error output, attempt fix (type errors, renamed imports, etc.)
• Re-run verification
• If stuck after 2 attempts, report failure with error details to user

Step 8: Summary

Present completion table:

| Package        | From    | To      | Type  | Source Changes | Notes           |
|----------------|---------|---------|-------|----------------|-----------------|
| typescript     | 5.3.0   | 5.7.0   | minor | none           | batched         |
| next           | 15.1.0  | 16.0.0  | major | 12 files       | migration guide |
| eslint         | 8.x     | 9.x     | major | 3 files        | flat config     |
| @types/node    | 20.x    | 22.x    | major | none           | types only      |

• Source Changes: List count of files modified due to the upgrade (excluding package.json/lockfile). If files were changed, briefly list the key files affected.
• Include skipped packages with reasons.

Security Reminders

• Never install packages by guessing names. Use exact name from existing package.json.
• Verify GitHub URLs from npm registry repository.url, not manual construction.
• Never run {manager} add {pkg}@latest without confirming package name and version from registry first. Prevents typosquatting.
• If anything looks suspicious, alert the user immediately.