JS Deps

Arguments

Specific package names (e.g. jest @types/jest), . for all packages, or glob patterns (e.g. @testing-library/*).

If $ARGUMENTS is help, --help, -h, or ?, skip the workflow and read references/options.md.

Workflow Selection

Based on user request:

• Security audit (audit, CVE, vulnerabilities, security): Read references/audit-workflow.md
• Dependency updates (update, upgrade, latest, modernize): Read references/update-workflow.md

Shared Process

1. Create Branch

Stash uncommitted changes and create a dedicated branch:

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BRANCH_NAME="js-deps-$TIMESTAMP"
git stash --include-untracked
git checkout -b "$BRANCH_NAME"

2. Detect Package Manager

Detect from lock files and package.json packageManager field (which takes precedence). See references/package-managers.md for detection logic and command mappings.

3. Verify Registry Access

Verify the package manager CLI is available and, for npm, that it can reach the registry. See references/package-managers.md for manager-specific verification commands.

If verification fails, prompt user: "Cannot reach package registry. Sandbox may be blocking network access. To allow package manager commands in sandbox mode, update settings.json."

Do not proceed until verification passes.

4. Discover Package Locations

Find all package.json files excluding node_modules. Store results as an array of directories to process.

5. Install Dependencies

Install dependencies in each discovered package directory so that npm outdated (and similar commands) can accurately compare installed versions against the registry. Without node_modules, exact-pinned packages (no ^ or ~) won't appear in outdated reports.

6. Identify Packages

• Parse $ARGUMENTS to determine packages
• For globs, expand against package.json dependencies
• For ., process all packages

7. Validate Changes

Check package.json scripts for available validation commands. Run available scripts using $PM run <script> in order (build, lint, test), continuing on failure to collect all errors. Skip any that don't exist.

If validation fails, revert the failing package to its previous version before continuing with remaining packages:

git checkout -- package.json package-lock.json  # or the equivalent lock file
$PM install

8. Update Documentation for Major Version Changes

For major version upgrades (e.g., 18.x to 19.x):

1. Search for version references in markdown files
2. Update in: CLAUDE.md, README.md, docs/*.md
3. Include changes in report/PR description

9. Cleanup

If a PR was created, do not delete the branch — it's needed for the open PR.

git checkout -
git stash list | grep -q . && git stash pop
# Only delete branch if no PR was created
if ! gh pr view "$BRANCH_NAME" --json url > /dev/null 2>&1; then
  git branch -d "$BRANCH_NAME"
fi

Edge Cases

• Glob matches nothing: Warn and list available packages
• Unsupported package manager: Prompt user for guidance
• Peer dep conflicts after major upgrades: When a plugin doesn't declare support for the new major version of its host (e.g., eslint-plugin-react-hooks not supporting eslint 10), add "overrides" to package.json rather than using --legacy-peer-deps. Example: "overrides": { "eslint-plugin-react-hooks": { "eslint": "$eslint" } }. The $eslint syntax references the version already declared in the package's own dependencies
• Lockfile sync: After all package.json changes, run $PM install in every modified directory and commit lockfiles — CI tools like npm ci require exact sync between package.json and the lockfile
• Verify devDependencies placement: After bulk installs across directories, verify that linting/testing/build packages (eslint, typescript, vite, etc.) ended up in devDependencies, not dependencies — easy to misplace when running install commands across many directories