| name | bump-packages |
| description | Bump every external npm dependency in this pnpm workspace to its latest version, then open a `chore: bump packages` PR. Use this whenever the user runs `/bump-packages`, asks to "bump/update/upgrade the (dev)dependencies", "update packages to latest", "do a dependency bump", or otherwise wants the monorepo's deps refreshed. Patch and (>=1.x) minor bumps apply automatically; major bumps — and 0.x minors, which are breaking under SemVer — are NEVER applied without first showing the user a breaking-changes report and getting an explicit go/no-go per package. The skill validates the result (build, types, lint, tests), adds a `fix:` changeset for any runtime-dependency bump on a publishable package, and finishes with an overview of what changed. |
Bumping packages
This repo is a pnpm-workspace monorepo (@lifi/sdk + five providers). Keeping its
external dependencies current is routine maintenance, but three things make a blind
pnpm update --latest && git push a bad idea, and they're the reason this skill exists:
- Major bumps break things. A
2.x → 3.x jump (or, under SemVer, a 0.22 → 0.23)
can change APIs the SDK relies on. Those need a human looking at the changelog before
they land — so this skill researches the breaking changes and asks you per package,
while applying the safe patch/minor bumps without ceremony.
- Runtime bumps ship to users; dev bumps don't. Bumping
viem changes what
@lifi/sdk-provider-ethereum resolves for consumers, so it needs a Changesets entry
(CI/releases depend on it). Bumping biome or vitest doesn't affect the published
tarball, so it must NOT get a changeset (a noisy, meaningless release entry).
- Brand-new releases are a supply-chain risk. A version published in the last 24h is
"too fresh" to trust. The target is never automatically the registry's
latest — it's
the newest version that has already aged past 24h. pnpm 11 enforces this floor by
default (minimumReleaseAge: 1440), so pnpm up --latest, run under the repo's pinned
pnpm, holds a too-fresh release back to the newest aged version on its own — and preserves
each dependency's existing prefix (^, ~, or a deliberate exact pin) — verified for all
three. So you don't hand-write versions; you let pnpm resolve, and report what it held
back. Packages matched by minimumReleaseAgeExclude in pnpm-workspace.yaml (our
trusted first-party scopes — @bigmi/*, @lifi/*) bypass the floor; the analysis script
reads that list and won't predict holding them back, matching pnpm.
The deterministic parts — discovering outdated deps, predicting the aged target pnpm will
land on, classifying each by SemVer risk, and working out which publishable packages need a
changeset — are done by scripts/analyze-outdated.mjs so they come out the same way every
run. The script tells you what will happen (and what's held back, and why) before any
mutation; pnpm then does the bump. Your job is the judgement: reviewing the majors,
validating the result, writing a good PR.
Why not pnpm up -r -i --latest? The interactive -i picker is a keyboard-driven TUI
this tool can't drive, so we use the non-interactive --latest form.
Workflow
1. Start clean, on a fresh branch, using the repo's pnpm
Bumps land as a PR, and you can't commit to main. Make sure the working tree is clean
(git status), sync, and cut the branch:
git fetch origin main
git switch main && git pull --ff-only
git switch -c chore/bump-packages
If the tree has unrelated uncommitted changes, stop and ask the user — don't sweep their
work into a dependency PR.
Run pnpm from the repo root so you get the pinned version. Corepack serves the
packageManager-pinned pnpm (11.x) inside the repo, and that's what enforces the 24h floor
(see the intro). A stray pnpm 10.x on PATH would not — if a resolution looks too fresh,
confirm pnpm --version says 11.x. Nothing to configure.
Bump the package manager itself, too. Check the pinned pnpm against the latest:
npm view pnpm version
node -p "require('./package.json').packageManager"
Bump it to latest now — this rewrites the packageManager hash and the diff rides along in
the PR:
COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack use pnpm@latest
Do this first — before any dependency bump. The dependency steps and the final
pnpm regen (step 6) rewrite pnpm-lock.yaml, and you want that lockfile written by the
new pnpm so its format and resolution match what CI and everyone else uses post-merge.
pnpm goes to latest unconditionally — even a major (11.x → 12.x); pnpm regen would force
it regardless, and step-6 validation plus your PR review are the safety net if a toolchain
major misbehaves. (The major-approval gate is for the workspace's dependencies, not the
package manager.)
CI derives pnpm from packageManager (.github/actions/pnpm-install runs
pnpm/action-setup with no explicit version:), so this one field bump keeps CI in sync —
nothing else to change. If that ever stops being true (a hardcoded pnpm version: in a
workflow, a .tool-versions/.nvmrc, or an engines.pnpm), bump it in lockstep, or the PR
goes red. A quick git grep for the old version catches strays.
2. Capture the type-check baseline (before touching anything)
pnpm check:types can carry a pre-existing failure (see the repo's CLAUDE.md "Known
Issues"). If you only look at the post-bump result you'll wrongly blame the bump. So
record the baseline now, on the clean branch:
pnpm check:types > /tmp/bump-typecheck-before.txt 2>&1; echo "baseline exit: $?"
Keep this file. After bumping you'll re-run and diff — only new errors are the bump's
fault.
3. Analyze what's outdated
node .claude/skills/bump-packages/scripts/analyze-outdated.mjs > /tmp/bump-plan.json
The script fetches npm publish timestamps, picks the newest aged target per dep (≥24h
old), preserves each prefix, and prints a readable summary to stderr plus a JSON plan to
stdout (/tmp/bump-plan.json). Read both. The plan's parts:
safe — patch bumps and minor bumps on >=1.x packages. Apply these automatically.needsApproval — major bumps, plus 0.x minor bumps (reason: "zerox-minor"),
which SemVer treats as breaking. Never apply these without the user's OK (step 5).tooFresh — deps with updates whose newest version is younger than 24h, so there's
nothing aged enough to install yet. Don't bump these. Mention them in the summary
(with hoursUntilEligible) so the user knows they're waiting, not forgotten. An
ageUnknown entry means npm view couldn't return timestamps — treat as not-yet-eligible
rather than guessing.changeset — a map of publishable package → the runtime-dep bumps affecting it.
This is what needs a fix: changeset (step 7).deprecated — packages npm flags as deprecated. Call these out; a deprecated package
usually wants replacing, not just bumping.
Per entry, note target (the aged version pnpm should land on), registryLatest, and
heldBack: true when registryLatest is newer than target but too fresh. The target
is what the script predicts pnpm will install under the 24h floor — use it for
classification and the summary; pnpm produces the actual resolution in step 4.
If everything is up to date (summary.total === 0 and no tooFresh), tell the user and stop.
4. Apply the safe bumps
Let pnpm rewrite the ranges across the whole workspace — under pnpm 11's default age floor
it lands the aged target and keeps each prefix (caret, tilde, or exact) intact:
pnpm up -r --latest <name1> <name2> ...
Then sanity-check that pnpm's resolution matches the plan — versions should equal each
entry's target, never a heldBack registryLatest:
git diff -- '**/package.json' package.json
grep -E '<one-bumped-name>@' pnpm-lock.yaml
If a resolved version is newer than the plan's target, the age floor isn't taking effect
(likely a non-pinned pnpm 10.x on PATH — see step 1); stop and fix that before continuing,
rather than shipping a too-fresh dependency.
5. Research and approve the majors / 0.x minors
For each entry in needsApproval, build a breaking-changes report before asking.
Follow references/breaking-changes.md for where to look (GitHub releases between the two
versions, the package CHANGELOG, migration guides) and how to summarize. Present one block
per package — current → target (use the entry's aged target, not registryLatest), the
breaking changes that actually touch how this repo uses the dep, the migration steps, and a
link — then collect a per-package decision with an AskUserQuestion (multi-select: "Which
major upgrades should I apply?"). List every candidate so the user can pick a subset;
default is to skip the ones they don't pick.
Apply only the approved ones with pnpm up -r --latest <approved-names> (same as step 4).
If a major needs code changes to compile, make the minimal migration edits the changelog
calls for — or, if they're large, report back and let the user decide to defer that one.
Leave declined/deferred majors exactly as they were; they'll show as "deferred" in the
final summary so they're not silently dropped.
6. Regenerate the lockfile, then validate
First regenerate everything from scratch so you validate the exact, fresh state that
ships — not an incrementally-patched lockfile. pnpm regen deletes pnpm-lock.yaml, wipes
every node_modules, and runs corepack use pnpm@latest, then reinstalls cleanly:
pnpm regen
This re-resolves the whole tree from the bumped package.json ranges under pnpm 11's age
floor — so the committed lockfile is fully fresh and deduped, and reaffirms pnpm@latest. It's
a full reinstall, so it takes a bit. (It also re-runs corepack use pnpm@latest; if a newer
pnpm landed mid-run, the packageManager hash updates again — that's fine.)
Then run the checks proactively, against the fresh tree — the pre-commit hook will run
check + check:types + circular-deps + knip and pre-push runs test:unit anyway, so doing
them now lets you attribute and fix failures cleanly:
pnpm build
pnpm check
pnpm check:circular-deps
pnpm knip:check
pnpm test:unit
pnpm check:types > /tmp/bump-typecheck-after.txt 2>&1; echo "after exit: $?"
diff /tmp/bump-typecheck-before.txt /tmp/bump-typecheck-after.txt || true
Interpreting results:
check:types — judge it by the diff against the baseline, not pass/fail. Errors
present in both files are pre-existing (not yours). Errors only in the "after" file are
regressions the bump caused — investigate them.- A runtime bump that breaks the build/tests is the high-stakes case: either make the
small migration fix, or drop that single dep from the batch (revert its range, re-install)
and note it as "reverted — needs follow-up" rather than shipping a broken provider.
- If
biome check reports formatting changes, run pnpm check:write to apply them.
pnpm build rewrites the generated packages/*/src/version.ts files (it inlines each
package's current version). Those are build artifacts, unrelated to a dependency bump — and
a build can surface a pre-existing version drift in them. Don't let them into the PR; you'll
discard them at staging time (step 8).
7. Add a changeset for runtime bumps
Every publishable package in plan.changeset had a runtime dependency change, so it ships
to users and needs a Changesets entry — CI nudges (and releases depend) on it. Author one
changeset declaring those packages at patch (a dependency refresh is a fix:-level change
unless the bump changed the package's own public API). Use the changeset skill's format
(references/format.md there) — write .changeset/bump-packages.md:
---
"@lifi/sdk-provider-ethereum": patch
"@lifi/sdk-provider-sui": patch
---
Bump runtime dependencies: viem to 2.51.3, @mysten/sui to 2.17.0.
Only list the packages from plan.changeset. Dev-only bumps (biome, vitest, knip, tsdown,
@types/node, @lifi/data-types as a devDep, …) get no changeset. If plan.changeset is
empty, skip this step entirely. Confirm with pnpm changeset status.
8. Commit, push, open the PR
Stage deliberately. git add -A is wrong here — it would sweep this skill (untracked on
the branch) and any scratch files into the PR. But a narrow package.json/lockfile glob is
also wrong: a major bump may have required migration edits in packages/*/src/, and the
pnpm bump changes the packageManager field — all of which must ship. Stage tracked
modifications (which covers src/ edits, every package.json, the lockfile, and
packageManager) plus the new changeset, then eyeball exactly what's staged before
committing:
git add -u
git restore --staged --worktree -- $(git ls-files '**/version.ts')
git add .changeset/*.md
git status
git diff --cached --stat
git commit -m "chore: bump packages"
git push -u origin HEAD
gh pr create --title "chore: bump packages" --body "<summary>" --base main
Write the PR body as the overview from step 9 (the bump table, plus any deferred majors and
the changeset note). Open it ready for review (no --draft).
Hook escape hatch — use only with proof: if the pre-commit hook blocks the commit on a
check:types error that your step-6 baseline diff shows is pre-existing (identical in
both files), it's not your bump's fault and you may commit with --no-verify. Never reach
for --no-verify to bypass a failure the bump actually introduced — fix or drop that bump
instead.
9. Give the user the overview
End with a compact table so the user sees exactly what happened:
## Bumped packages
| Package | Type | From | To | Bump | Changeset |
|----------------------|---------|----------|---------|-------|-----------|
| viem | runtime | 2.48.11 | 2.51.3 | minor | ✅ patch |
| @mysten/sui | runtime | 2.16.2 | 2.17.0 | minor | ✅ patch |
| @biomejs/biome | dev | 2.4.15 | 2.4.16 | patch | — |
| vitest | dev | 4.1.6 | 4.1.7 | patch | — |
| … | | | | | |
**Package manager**: pnpm 11.1.2 → 11.5.0 (or "already latest").
**Held back** (newest too fresh, <24h): <name → registryLatest, eligible in ~Nh> — or "none".
**Deferred majors** (declined/needs work): <name current→target, one line why> — or "none".
**Validation**: lockfile regenerated (`pnpm regen`) ✅ · build ✅ · types ✅ (no new errors) · lint ✅ · unit tests ✅
**PR**: <link>
The To column is always the aged target that was actually installed. If a dep was
held back, the held-back line names the newer registry version still waiting out the 24h —
so nothing looks silently skipped.
Include any deprecated-package warnings and anything you reverted. If a major was deferred,
say what the user needs to do to revisit it.
