pnpm-upgrade

name	pnpm-upgrade
description	Keep pnpm current: preflight the published package and pnpm/action-setup self-installer, update pnpm locally, align packageManager in package.json, and refresh CI pins. Use this when refreshing the pnpm toolchain manually or in automation.

pnpm Upgrade

Use these steps to update pnpm and CI pins without blunt search/replace.

Steps (run from repo root)

1. Resolve the target pnpm release

   • Query the npm registry before changing the local toolchain: PNPM_VERSION=$(curl -fsSL https://registry.npmjs.org/pnpm/latest | jq -r .version).
   • Abort if the version is missing.
   • Resolve the exact package integrity: curl -fsSL "https://registry.npmjs.org/pnpm/${PNPM_VERSION}" | jq -r .dist.integrity.
   • Store the result as PNPM_INTEGRITY.
   • Abort if the integrity is missing or does not start with sha512-.
   • Convert the base64 digest after sha512- to lowercase hex, for example:

     printf '%s' "${PNPM_INTEGRITY#sha512-}" | base64 -d | xxd -p -c 256
     

   • Store the result as PNPM_SHA512_HEX.

2. Find the target pnpm/action-setup release

   • Query GitHub API: curl -fsSL https://api.github.com/repos/pnpm/action-setup/releases/latest | jq -r .tag_name.
   • Use GITHUB_TOKEN/GH_TOKEN if available for higher rate limits.
   • Store as ACTION_TAG (e.g., v4.2.0). Abort if missing.

3. Resolve the action tag to an immutable commit SHA

   • Run git ls-remote https://github.com/pnpm/action-setup "refs/tags/${ACTION_TAG}^{}" and capture the SHA as ACTION_SHA.
   • If the dereferenced tag is missing, fall back to git ls-remote https://github.com/pnpm/action-setup "refs/tags/${ACTION_TAG}".
   • Abort if ACTION_SHA is empty.

4. Preflight the release and CI installation path

   • Run node .agents/skills/pnpm-upgrade/scripts/preflight.mjs --version "${PNPM_VERSION}" --action-ref "${ACTION_SHA}".
   • The script first rejects published pnpm manifests with non-empty dependencies or devDependencies. pnpm bundles its runtime dependencies, so these fields indicate a broken publication such as pnpm@11.12.0.
   • It then reproduces both pnpm/action-setup installation paths in separate temporary directories: install the regular pnpm bootstrap from pnpm-lock.json and the standalone @pnpm/exe bootstrap from exe-lock.json, set isolated PNPM_HOME directories, and self-update each bootstrap to PNPM_VERSION.
   • Abort the upgrade on any failure. Do not bypass this check with a direct local install; the preflight exists to exercise the CI-only bootstrap path.

5. Update pnpm locally

   • Run pnpm self-update "${PNPM_VERSION}".
   • If pnpm is missing or self-update fails only because the current installation cannot update itself, run corepack prepare "pnpm@${PNPM_VERSION}" --activate. Do not use this fallback to bypass a failed preflight.
   • Confirm pnpm -v exactly matches PNPM_VERSION.

6. Align package.json

   • Open package.json and set packageManager to pnpm@${PNPM_VERSION}+sha512.${PNPM_SHA512_HEX} (preserve trailing newline and formatting).

7. Update workflows carefully (no broad regex)

   • Files: everything under .github/workflows/ that uses pnpm/action-setup.
   • For each file, edit by hand:
     • Set uses: pnpm/action-setup@${ACTION_SHA}.
     • If a with: version: field exists, set it to ${PNPM_VERSION} (keep quoting style/indent).
   • Do not touch unrelated steps. Avoid multiline sed/perl one-liners.

8. Verify

   • Run pnpm -v and confirm it matches the version portion of packageManager.
   • Confirm packageManager keeps the exact +sha512.${PNPM_SHA512_HEX} suffix.
   • git diff to ensure only intended workflow/package.json changes.

9. Follow-up

   • If runtime code/build/test config was changed (not typical here), run $code-change-verification; otherwise, a light check is enough.
   • Commit with chore: upgrade pnpm toolchain and open a PR (automation may do this).

Notes

• Tools needed: curl, jq, base64, xxd, node, npm, and pnpm/corepack. Install if missing.
• Keep edits minimal and readable—prefer explicit file edits over global replacements.
• GitHub Actions must stay pinned to commit SHAs, not tags. Use the latest release tag only to discover the commit SHA to pin.
• If GitHub API is rate-limited, retry with a token or bail out rather than guessing the tag.