Package.json Maintenance

Manages JavaScript package maintenance tasks in an isolated worktree, including security audits and dependency updates. Automatically detects and uses the project’s package manager (npm, yarn, pnpm, or bun).

Arguments

• Specific packages: jest @types/jest
• All packages: .
• Glob patterns: @testing-library/* jest*

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 Isolated Environment

Preferred: Worktree (isolated, non-disruptive)

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BRANCH_NAME="pkg-maintenance-$TIMESTAMP"
WORKTREE_PATH="../$BRANCH_NAME"
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"
cd "$WORKTREE_PATH"
USE_WORKTREE=true

Fallback: Branch (if worktree fails due to sandbox directory restrictions)

Prompt user: “Worktree creation failed (sandbox may restrict creating directories outside the working directory). Run in current directory on a new branch instead? This will stash any uncommitted changes.”

If user accepts:

git stash --include-untracked
git checkout -b "$BRANCH_NAME"
USE_WORKTREE=false

2. Detect Package Manager

Check for lock files to determine the package manager. See references/package-managers.md for detection logic and command mappings.

if [ -f "bun.lockb" ]; then PM="bun"
elif [ -f "pnpm-lock.yaml" ]; then PM="pnpm"
elif [ -f "yarn.lock" ]; then PM="yarn"
else PM="npm"
fi

Also check package.json for packageManager field which takes precedence.

3. Verify Registry Access

Verify the package manager can reach its registry. See references/package-managers.md for manager-specific commands.

If this 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 connectivity is confirmed.

4. Discover Package Locations

Find all package.json files excluding node_modules:

find . -name "package.json" -not -path "*/node_modules/*" -type f

Store results as an array of directories to process.

5. Identify Packages

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

6. 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 to previous version before continuing.

7. Update Documentation for Major Version Changes

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

1. Search for version references: grep -r "React 18\|Express 4" --include="*.md" .
2. Update in: CLAUDE.md, README.md, docs/*.md
3. Skip: specs/*/research.md, specs/*/tasks.md, archived files
4. Include changes in report/PR description

8. Cleanup

If using worktree:

cd -
git worktree remove "$WORKTREE_PATH"
# Delete branch only if no PR was created
git branch -d "$BRANCH_NAME"

If using branch fallback:

git checkout -
git stash pop
# Delete branch only if no PR was created
git branch -d "$BRANCH_NAME"

Edge Cases

• No package.json: Error with clear message
• Not a git repo: Error – git required for branch/worktree isolation
• Package not found: Suggest checking package name
• Glob matches nothing: Warn and list available packages
• Network restricted: Package manager commands require internet access; will fail in offline sandbox environments
• Unsupported package manager: If using an unrecognized package manager, prompt user for guidance