tomevault-io 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
$ARGUMENTSto determine packages - For globs, expand against package.json dependencies
- For
., process all packages
6. Validate Changes
Check package.json scripts for available validation commands:
| Purpose | Common names |
|---|---|
| Build | build, compile, tsc |
| Lint | lint, check, eslint |
| Test | test, jest, vitest |
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):
- Search for version references:
grep -r "React 18\|Express 4" --include="*.md" . - Update in:
CLAUDE.md,README.md,docs/*.md - Skip:
specs/*/research.md,specs/*/tasks.md, archived files - 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.