home / skills / openai / openai-agents-js / pnpm-upgrade

pnpm-upgrade skill

safe

/.codex/skills/pnpm-upgrade

This skill helps you upgrade pnpm and align CI manifests by updating pnpm versions, packageManager, and workflow pins across your repo.

npx playbooks add skill openai/openai-agents-js --skill pnpm-upgrade

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: pnpm-upgrade
description: 'Keep pnpm current: run pnpm self-update/corepack prepare, align packageManager in package.json, and bump pnpm/action-setup + pinned pnpm versions in .github/workflows to the latest release. 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. Update pnpm locally
   - Try `pnpm self-update`; if pnpm is missing or self-update fails, run `corepack prepare pnpm@latest --activate`.
   - Capture the resulting version as `PNPM_VERSION=$(pnpm -v)`.

2. Align package.json
   - Open `package.json` and set `packageManager` to `pnpm@${PNPM_VERSION}` (preserve trailing newline and formatting).

3. Find latest pnpm/action-setup tag
   - 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.

4. 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_TAG}`.
     - 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.

5. Verify
   - Run `pnpm -v` and confirm it matches `packageManager`.
   - `git diff` to ensure only intended workflow/package.json changes.

6. 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`, `node`, `pnpm`/`corepack`. Install if missing.
- Keep edits minimal and readable—prefer explicit file edits over global replacements.
- If GitHub API is rate-limited, retry with a token or bail out rather than guessing the tag.

Overview

This skill automates a careful pnpm toolchain refresh across a repository. It runs pnpm self-update or corepack prepare, aligns packageManager in package.json, and updates pnpm/action-setup and pinned pnpm versions in .github/workflows to the latest release. The goal is a minimal, verifiable update suitable for manual or automated PRs.

How this skill works

The skill updates pnpm locally (preferring pnpm self-update, falling back to corepack), captures the active pnpm version, and writes packageManager in package.json to that exact version. It queries the GitHub API for the latest pnpm/action-setup release tag and updates workflow files under .github/workflows that use that action, setting the uses: tag and any with: version: values to the captured pnpm version. It emphasizes manual, file-scoped edits and confirms changes with git diff.

When to use it

When refreshing the repository pnpm runtime to the latest stable release
Before opening a toolchain PR that must keep changes minimal and auditable
When CI workflows use pnpm/action-setup and need a pinned action tag and pnpm version
If pnpm is missing or self-update fails and corepack must be used
When automation should avoid broad regex replacements in workflows

Best practices

Prefer pnpm self-update; use corepack prepare pnpm@latest --activate only if necessary
Capture PNPM_VERSION=$(pnpm -v) and use it verbatim in package.json and workflows
Query GitHub API for the latest pnpm/action-setup release tag and use authenticated requests if rate-limited
Edit each workflow file by hand or with targeted edits; avoid repository-wide regex replacements
Run pnpm -v and git diff to verify only intended files changed before committing

Example use cases

Manually refresh the pnpm toolchain before a large dependency upgrade
Build automation that opens a chore PR to keep CI and local pnpm aligned
Small repositories where you want predictable, pinned pnpm/action-setup versions
Projects using corepack where pnpm may not be preinstalled on developer machines

FAQ

What if GitHub API rate limits the release lookup?

Retry the query with GITHUB_TOKEN or GH_TOKEN for higher rate limits; if still blocked, abort rather than guessing the tag.

Should I change any other workflow steps?

No. Keep edits minimal: only update pnpm/action-setup uses and any with: version fields. Avoid touching unrelated steps.