gh-byborgai-prompt-collection-aitt/commands/update-npm-packages.md

allowed-tools, argument-hint, description

allowed-tools	argument-hint	description
Read, Grep, Glob, Bash, TodoWrite, Bash(npx), Bash(npm), Bash(git add .), Bash(git status), Bash(git commit), AskUserQuestion, WebSearch, WebFetch	[--target <patch|minor|major>] [--package <name>] [--safe] [--skip <pkg1,pkg2,...>]	Continuously updates NPM packages one at a time, verifies each update, and commits them until no more updates are available or user stops the process.

/update-npm-packages — Continuously update NPM packages one by one

Purpose

Automate your "one-package-at-a-time" update flow with minimal risk. Continuously selects and applies eligible updates (preferring PATCH, then MINOR, optionally MAJOR), records changelog summaries, runs basic checks, and commits each update automatically. The process continues until no more updates are available or the user interrupts it.

Usage

/update-npm-packages /update-npm-packages --target patch /update-npm-packages --target minor /update-npm-packages --target major /update-npm-packages --package /update-npm-packages --safe /update-npm-packages --skip react,eslint,chalk /update-npm-packages --audit-level high /update-npm-packages --safe --audit-level critical

Flags

--target <patch|minor|major> Specify update level: PATCH (default), MINOR, or MAJOR. Default behavior: patch→minor fallback (no major unless explicitly specified) --package Update ONLY this specific package and exit (no loop, no other packages) --safe Enable interactive mode - pause before each update for user approval after showing changelog research --skip <pkg1,pkg2,...> Comma-separated list of package names to skip (e.g., "react,eslint,chalk"). Packages in this list will be excluded from updates --audit-level <low|moderate|high|critical> Set the audit severity threshold for blocking updates (default: moderate). Updates introducing vulnerabilities at or above this level will require user approval

What This Command Does

This command runs in a LOOP until no more updates are available or the user stops it.

Initial Setup (Once per run)

1. Check git working directory

   • Run git status --porcelain to check for uncommitted changes
   • If working directory is NOT clean (has uncommitted changes):
     • Display the current status to the user
     • Use AskUserQuestion to ask: "Your working directory has uncommitted changes. Would you like to: (1) stash changes and continue, (2) commit changes first, or (3) abort?"
     • Responses:
       • stash or 1 - Run git stash push -m "Auto-stash before package updates" and continue
       • commit or 2 - Stop and ask user to commit manually first
       • abort or 3 - Exit the command immediately
   • If working directory is clean: Proceed to next step

2. Confirm auto-update mode (only if --safe flag is NOT present)

   • If --safe flag is NOT present: Use AskUserQuestion tool to confirm automatic updates
   • Question: "This will automatically update packages without manual approval. Continue?"
   • Options: ["yes", "no"]
   • Responses:
     • yes - Proceed with automatic updates
     • no - Exit the command immediately
   • If --safe flag is present: Skip this confirmation (user will approve each update individually)

3. Determine ticket

   • Try .claude/scripts/find-ticket-from-branch.sh to get ticket ID from branch

For Each Package (Repeats automatically)

4. Select ONE eligible update (STEP 1)

   • If --package is provided: Use ONLY that specific package, ignore skip list, ignore target preference
     • After processing this package, exit immediately (do not continue loop)
     • If the package is not available for update, report this and exit
   • Otherwise (no --package flag):
     • Apply skip list: If --skip flag is provided, use that comma-separated list (e.g., react,eslint,chalk). Use npx ncu --reject with the skip list to exclude these packages
     • If no --skip flag is provided: No packages are skipped (no default skip list)
     • If --target major is specified: Run npx ncu -t major (with --reject if skip list exists). If none found, exit loop: "All updates completed"
     • If --target minor is specified: Run npx ncu -t minor (with --reject if skip list exists). If none found, exit loop: "All updates completed"
     • If --target patch is specified or no target: Run npx ncu -t patch (with --reject if skip list exists). If none found, run npx ncu -t minor. If none, exit loop: "All updates completed"
     • Choose exactly ONE package per iteration

5. Quick research (STEP 2, ≤2 minutes)

   • Look up the package changelog on npm/GitHub
   • Always display a short summary of key changes to the user (breaking changes, new features, bug fixes)
   • Always append the summary to package-updates-changelog.md at repo root (create if missing)
   • If info is hard to find within ~2 minutes, write/display a brief general note and proceed

6. User approval (STEP 2a, only with --safe flag)

• If --safe flag is present: Display the research findings to the user
• Show: package name, current version, target version, and changelog summary
• Use AskUserQuestion tool to ask: "Proceed with this update? (yes/no/skip-all)"
• Responses:
  • yes - Continue with this update
  • no - Skip this package and move to next one
  • skip-all - Stop the loop entirely
• If --safe flag is NOT present: Skip this step and proceed automatically

7. Apply the update (STEP 3)

   • Always run: npm install <pkg>@<targetVersion> (e.g., npm install inquirer@12.6.3)
   • No dry-run mode - this command actually applies updates

8. Verify basics + Security audit (STEP 4)

   • Security audit check:
     • Run npm audit --audit-level=moderate --json to check for vulnerabilities
     • Parse the JSON output to count vulnerabilities by severity (critical, high, moderate, low)
     • If new critical or high vulnerabilities are introduced (compare with pre-update baseline if available):
       • Display the vulnerability details to the user (package name, severity, description)
       • Use AskUserQuestion to ask: "This update introduces critical/high security vulnerabilities. Would you like to: (1) revert this update, (2) continue anyway, (3) try npm audit fix, or (4) view detailed audit report?"
       • Responses:
         • revert or 1 - Revert the update (git reset --hard HEAD~1 && npm install) and stop the loop
         • continue or 2 - Proceed with the update despite vulnerabilities (log warning in changelog)
         • fix or 3 - Run npm audit fix and re-verify, then ask for confirmation again if issues remain
         • report or 4 - Run npm audit (human-readable format) and display full report, then ask again
     • If moderate or low vulnerabilities: Log them in the changelog but continue (non-blocking)
   • Unless --no-verify, run:
     • npm install && npx tsc --noEmit (always, if TypeScript is present)
     • Conditionally run: npm run storybook / npm run eslint / npm run test / npm run build (only if relevant scripts exist in package.json)
   • If verification scripts are not available or fail to run: Use AskUserQuestion to ask the user:
     • "Verification script(s) not available or failed. Would you like to: (1) skip verification and continue, (2) suggest alternative verification steps, or (3) stop the update process?"
   • On errors: attempt quick fixes or revert (git reset --hard HEAD~1 && npm install) and stop the loop

9. Commit the update (STEP 5)

   • Stage: git add package.json package-lock.json
   • Auto-commit with conventional format: <TICKET> chore: update <package> from <oldVersion> to <newVersion>
   • Keep first line ≤72 chars; imperative mood; accurate, concise

10. Continue to next package

• If --package was specified: Exit immediately after committing (single package mode)
• Otherwise: Automatically return to STEP 1 and process the next package
• Loop continues until no more updates or user interrupts

Important Notes

• Continuous operation: Processes ALL available updates automatically, one package at a time (unless --package is specified)
• Single package mode: Use --package <name> to update only one specific package and exit immediately
• Prefer PATCH over MINOR: Default behavior checks patch updates first; only moves to minor if no patches available (unless specific --target is used)
• MAJOR version updates: Use --target major to explicitly enable MAJOR version updates. By default, MAJOR updates are NOT processed due to potential breaking changes
• Custom skip list: Use --skip pkg1,pkg2,pkg3 to exclude specific packages from updates. No default skip list (unless --package is used - then skip list is ignored)
• Security audit: Each update is automatically checked for security vulnerabilities using npm audit. Critical/high vulnerabilities require user approval before proceeding
• Audit level control: Use --audit-level <low|moderate|high|critical> to set the severity threshold for blocking updates (default: moderate)
• Auto-commit each update: Every successful update gets its own commit immediately
• Follow conventional commits: Format is TICKET chore: update <package> from <old> to <new>
• Stop on errors: If verification fails, revert the update and stop the loop (don't continue to next package)
• User can interrupt: Press Ctrl+C or stop the command at any time to halt the process
• Automatic changelog tracking: All update summaries are automatically written to package-updates-changelog.md, including any security vulnerability notes
• Safe mode: Use --safe flag for interactive approval before each update - ideal for teams that want manual review