pnpm-upgrade-package

PNPM Upgrade Package

Use this skill for interactive dependency bumps in Langfuse.

Read Order

• Use this SKILL.md for the end-to-end workflow.
• Run the main helper once at the start of the upgrade:

node .agents/skills/pnpm-upgrade-package/scripts/check-release-age-window.mjs <package> [targetVersion]

Apply This Skill

• Ask for the package name if the user did not provide one.
• Ask for the target version if the user did not provide one.
• Run the main helper once as the first analysis step and use that single

output for scope, exclusion decisions, and the final bump.

• If the target package is not directly declared anywhere, run

pnpm why -r <package> to find which direct dependency brings it in, then inspect whether the current top-level parent already allows the requested transitive version via its dependency range.

• If the current parent range already covers the requested transitive version,

prefer a lockfile refresh / reinstall path over bumping the parent manifest.

• If the current parent range does not cover the requested transitive version,

upgrade that parent dependency instead of adding the target package directly unless the user explicitly wants that.

• Probe the parent once at @latest:

npm view <parent>@latest dependencies peerDependencies optionalDependencies --json. If that range resolves to any non-vulnerable version of the target, even one newer than the lowest fix, upgrade the parent instead of pinning the exact lowest fix. If the latest parent still pins a vulnerable range, do not walk intermediate parent versions: add a scoped overrides entry in pnpm-workspace.yaml only when the fixed version stays within the major the parent declares, otherwise treat it as a major migration and stop. In the final response, state that the parent pins the vulnerable range so the reviewer knows the override is a workaround.

• If pnpm will not move an already-allowed transitive version, a scoped

overrides entry in pnpm-workspace.yaml may be used as a temporary resolution tool. Before finishing, prove whether the override is still required: remove it, run pnpm install, then run pnpm dedupe. Inspect the diff after each generated change. If the target version remains without the override, do not keep the override; keep or restore it only when pnpm reverts or drifts from the requested version without it.

• Never manually edit pnpm-lock.yaml; regenerate lockfile changes with

pnpm commands only. If a lockfile-only refresh causes unrelated churn, adjust the pnpm command and rerun instead of patching the lockfile by hand.

• After fixing or upgrading a package, run pnpm dedupe. Always inspect the

diff after dedupe and revert that generated attempt if it introduces unrelated churn.

• Resolve the registry latest version, but do not silently upgrade to latest

unless the user asked for latest.

• Compare the target version with the latest version installable under the

current minimumReleaseAge window.

• Before generating lockfile changes, run

pnpm install --dry-run --ignore-scripts to catch resolver and policy failures without writing pnpm-lock.yaml or node_modules.

• Inspect any dry-run "would make changes" output as baseline resolver drift

before deciding which write command is safe.

• Ask before adding minimumReleaseAgeExclude entries for the target package,

exact dependency companions from dependencies or optionalDependencies, or locally installed exact peer dependencies.

• Finish with pnpm why -r <package> to confirm that only the intended version

remains in the workspace.

• In the final response, include a copy-pasteable human commit command using

the resolved package name and target version. Use a branch-safe package slug for scoped packages, but keep the exact package name in the commit message: git switch -C deps/bump-<package-slug>-to-<version> && git commit -m "chore(deps): bump <package> to <version>" --no-verify

Quick Commands

• Analysis pass:

node .agents/skills/pnpm-upgrade-package/scripts/check-release-age-window.mjs <package> <targetVersion>

• Transitive provenance / final graph verification:

pnpm why -r <package>

• Inspect a current parent manifest on the registry:

npm view <parent>@<installedVersion> dependencies peerDependencies optionalDependencies --json

• Preflight resolver/policy check:

pnpm install --dry-run --ignore-scripts

• Optional lockfile cleanup:

pnpm dedupe

• Bump in the root workspace:

pnpm -w up <package>@<version>

• Bump in one workspace:

pnpm --filter web up <package>@<version>

• Bump everywhere that should move together:

pnpm -r up <package>@<version>

• Verify temporary override removal:

remove the override, then run pnpm install and pnpm dedupe

• Human commit helper:

git switch -C deps/bump-<package-slug>-to-<version> && git commit -m "chore(deps): bump <package> to <version>" --no-verify