chore(release): add a Claude Code skill that prepares the version-bump PR - #541

…p PR

Adds /bump-package-versions, a manual-only project skill for maintainers.
Per package it finds the last stable release tag, cross-checks it against
package.json on main and npm, lists the PRs merged since, diffs the public
surface (exported names, package.json fields, packed files) against the
published tarball, and picks major/minor/patch from semver plus this
repo's conventions: 0.x breaking changes and features take a minor, a new
block type is a minor for blocks and a patch for dependents, and
workspace:* pins force a release of every dependent. It pauses for
approval, bumps with `pnpm version --no-git-tag-version`, and opens a PR
shaped like #444.

CONTRIBUTING.md points to it from "Publishing packages".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hEPMFUL7nnce55y9RVztu

Addresses the two findings from the Codex review of this PR. Both were
verified and rated P3.

- Step 4 now also diffs the third-party packages inlined into each bundle
  against the published tarball, reading them from tsdown's //#region
  markers. Step 3's path filter can't see a change that touches only the
  root pnpm.overrides and pnpm-lock.yaml, yet such a change moves the
  yaml or zod copied into local-runner's snapshot reader. Step 3 now
  points to that check instead of keeping its own, already stale, list of
  bundled packages.
- Step 2 prints npm=none only when npm answers E404. Any other lookup
  failure prints npm=ERROR. A new table row says to re-run the loop in
  that case, instead of reading the failure as "never released".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hEPMFUL7nnce55y9RVztu

… closed

Addresses the four follow-up issues (A to D) from the review of this PR:

- A: manifest_of sorts dependencies and peerDependencies before diffing.
  pnpm pack writes them in a nondeterministic order: 6 packs of
  @deepnote/mcp gave 6 different outputs before, and 1 after.
- B: step 7 requires npm to answer E404 for the new version. The old
  check printed nothing, and so read as "available", whenever the lookup
  failed.
- C: step 2 prints tag-on-remote=- and tag-on-main=- when a package has
  no tag, so an untagged package no longer matches the local-only-tag and
  other-branch Stop rows.
- D: every npm view and npm pack pins --@deepnote:registry to
  registry.npmjs.org, where cd.yml publishes. A plain --registry, the
  first suggestion, does not override a scoped registry in a user's
  .npmrc: npm still sent the lookup to the scoped registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hEPMFUL7nnce55y9RVztu

…pm versions

Addresses the two open CodeRabbit comments on this PR.

- Step 3's "Ships" list now names all ten package.json fields that step
  4's manifest_of() diffs; it named six and left out main, module, types
  and peerDependencies. It also counts the install hooks npm runs on
  consumers' machines (preinstall, install, postinstall) and the build
  script as shipped, and "Doesn't ship" keeps only the other scripts.
  #483 added --no-fixed-extension to the build scripts of blocks and
  database-integrations, unreleased in both, which the old rule filed
  under "Doesn't ship".
- Step 2's table gets a row for tag=none with a version on npm: the
  package was published outside the release flow, so stop. No row
  covered it, and reading it as "never released" skips step 7's check
  that the version isn't on npm yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MDLLybntQm7AD7nUQAWZX

The skill's inline shell moves into one Node script with four commands
(baselines, changes, surface, set-version) that exit 1 when a run should
stop. SKILL.md drops from 267 to 183 lines, and the facts specific to one
package move into a single "Package notes" section.

- set-version refuses a target that isn't above the last release, and checks
  npm and origin before accepting a package as already at its target.
- baselines prints npm's error code with npm-error, so an auth failure is
  distinguishable from a dropped connection.
- surface also reports the third-party packages the public types import,
  flagging a changed range, and whether the built files changed byte for byte.
- Steps 1 to 6 stay on origin/main. An open release PR is compared at step 6
  and updated at step 7, after approval.
- SKILL.md says root pnpm.overrides don't ship, and how to rate a raised
  floor on a dependency the public types expose.
- CONTRIBUTING.md no longer limits the skill to multi-package releases.

Tested with dry runs to the step 6 checkpoint: on main at b331a3f the skill
matched #552 on 8 of 9 packages and raised the ninth as an open question; on
a242a4c it produced the proposal released as #562. Every baseline status was
exercised against a simulated remote, along with set-version's refusals and
surface's fail-closed path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BYyMrxsMPw3Yu9zmWuusYP

cd.yml publishes only when package.json matches the tag, so a prerelease cut
from main leaves main's package.json at the prerelease version. baselines
reported that as unreleased-bump. And because cd.yml publishes without --tag,
which npm 10 turns into latest, it could also stop earlier as
published-outside-flow.

checkBaseline now reports prerelease when package.json matches a prerelease
tag that is on origin and on main, and npm's latest is either the stable tag
or that prerelease. A local-only or off-main prerelease tag, or a package.json
past the last released prerelease, still stops the run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BYyMrxsMPw3Yu9zmWuusYP