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: PNPMVERSION=$(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/${PNPMVERSION}" | jq -r .dist.integrity. - Store the result as PNPMINTEGRITY. - Abort if the integrity is missing or does not start with sha512-. - Convert the base64 digest after sha512- to lowercase hex, for example: ``bash printf '%s' "${PNPMINTEGRITY#sha512-}" | base64 -d | xxd -p -c 256 ` - Store the result as PNPMSHA512HEX`.

1. Find the target pnpm/action-setup release

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

1. Resolve the action tag to an immutable commit SHA

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

1. Preflight the release and CI installation path

- Run node .agents/skills/pnpm-upgrade/scripts/preflight.mjs --version "${PNPMVERSION}" --action-ref "${ACTIONSHA}". - 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 [email protected]. - 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 PNPMHOME directories, and self-update each bootstrap to PNPMVERSION. - 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.

1. Update pnpm locally

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

1. Align package.json

- Open package.json and set packageManager to pnpm@${PNPMVERSION}+sha512.${PNPMSHA512_HEX} (preserve trailing newline and formatting).

1. 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@${ACTIONSHA}. - If a with: version: field exists, set it to ${PNPMVERSION} (keep quoting style/indent). - Do not touch unrelated steps. Avoid multiline sed/perl one-liners.

1. Verify

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

1. 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.