yarn-dependency-upgrades

name

yarn-dependency-upgrades

description

Upgrade dependencies and maintain CVE-focused resolution hygiene in a Yarn 4 Node.js project. Use when asked to upgrade one dependency, multiple dependencies, or all dependencies to latest versions, when asked to remediate CVEs from `yarn-audit-known-issues` produced by `yarn npm audit --recursive --environment production --json`, or when asked to check and remove unnecessary `package.json` `resolutions` after upstream dependency upgrades. Follow this precedence for CVE remediation: (1) upgrade the vulnerable package if it is in package.json `dependencies`, (2) otherwise upgrade a direct parent dependency that pulls in the vulnerable transitive package, (3) otherwise use a package-level CVE resolution for the vulnerable package, falling back to descriptor-level resolution only when a broad override is incompatible.

Yarn Dependency Upgrades

Overview

Use deterministic Yarn 4 commands that match yarn up -i outcomes while remaining scriptable and repeatable.

Top-level resolutions are a CVE-remediation mechanism in this skill. Do not add or keep a resolution just to force a newer transitive version. If removing a resolution does not cause the production audit command yarn npm audit --recursive --environment production --json to report a vulnerability, remove it. If a resolution is still required for a CVE after cleanup, check whether its target version is stale and upgrade the retained resolution to the latest compatible fixed npm version.

Preflight

• Run commands from the repository root.
• Confirm Yarn 4 is active: yarn --version.
• Confirm the repo manager: node -p "require('./package.json').packageManager".

Upgrade Scope

• Upgrade one dependency to latest: yarn up <package>@latest
• Upgrade multiple dependencies to latest: yarn up <package-a>@latest <package-b>@latest
• Preferred: upgrade all direct dependencies and devDependencies to latest using globs:
  • yarn up '*' '@*/*'
• Optional: refresh all matching transitive resolutions after the manifest upgrade:
  • yarn up -R '*' '@*/*'
• Keep glob patterns quoted (especially in zsh) to prevent shell expansion.
• Run interactive mode only when explicitly requested: yarn up -i <pattern>

CVE Workflow

1. Generate the production audit file:
   • yarn npm audit --recursive --environment production --json > yarn-audit-known-issues
2. Check for findings:
   • test -s yarn-audit-known-issues
3. Create an action plan (helper script in this skill):
   • node skills/yarn-dependency-upgrades/scripts/cve-upgrade-plan.js yarn-audit-known-issues
4. Apply fixes in strict precedence order for each vulnerable package:
   • If package exists in top-level dependencies: run yarn up <package>@latest
   • Else upgrade a direct parent dependency that introduces it: run yarn up <parent>@latest
   • Else apply a package-level override for the vulnerable package: yarn set resolution <package> npm:<version>
   • If the package-level override is incompatible with unrelated dependents, fall back to the narrow vulnerable descriptor from yarn why <package> --json: yarn set resolution <descriptor> npm:<version>
5. Re-run audit after each fix batch and continue until the file is empty.

Resolution Guidance

• Prefer one package-level CVE resolution for each vulnerable package, for example "uuid": "npm:14.0.0", when the intent is to prevent any vulnerable version from remaining in the dependency graph.
• Use descriptor-specific resolutions only when a package-level override is incompatible with unrelated dependents or when only one vulnerable descriptor can safely move.
• Derive fallback descriptors from yarn why <package> --json and use each affected descriptor with yarn set resolution.
• Use latest version lookup when creating resolution commands:
  • yarn npm info <package> --fields version --json
• Persist overrides in top-level resolutions only when the production audit shows they are required to prevent a CVE.
• Do not retain or upgrade resolutions for freshness, compatibility, or general policy reasons unless the user explicitly asks for a different policy than this skill's default.

Resolution Cleanup

1. Create a baseline audit snapshot:
   • yarn npm audit --recursive --environment production --json > yarn-audit-baseline
2. Work through package.json resolutions entries one at a time:
   • Identify current graph context for the resolved package: yarn why <package> --json
   • Temporarily remove one resolutions entry from package.json
   • Re-resolve without the override: yarn up -R '*' '@*/*'
   • Re-run audit: yarn npm audit --recursive --environment production --json > yarn-audit-after
3. Decide keep/remove for that entry:
   • Keep the entry removed when yarn-audit-after stays empty or otherwise does not introduce a vulnerability finding attributable to that package
   • Restore the entry only when removing it causes a production CVE to reappear
4. Repeat until each resolution entry has been tested, then run the CVE workflow again for any remaining findings.

Retained Resolution Upgrade

After cleanup, check every remaining package.json resolutions entry for newer target versions:

1. Generate the non-mutating retained-resolution report:
   • node skills/yarn-dependency-upgrades/scripts/resolution-upgrade-plan.js
2. For each report item where needsUpgrade is true:
   • Update that package.json resolution to the reported suggestedPackageJsonValue
   • Run yarn install
   • Re-run the production audit:
     • yarn npm audit --recursive --environment production --json > yarn-audit-known-issues
3. If install, audit, or tests fail after upgrading a retained resolution, revert that resolution or narrow it to the CVE-required descriptor and document the blocker.
4. Do not upgrade retained resolutions that are not required by the production audit after cleanup; remove them instead.

Verification

Run mandatory repository checks after dependency changes:

• yarn lint
• yarn test:coverage
• yarn test:routes
• yarn build

References

• Use references/yarn-upgrade-playbook.md for command variants and troubleshooting.