fix(release): make publish recovery idempotent

[flyingrobots]

Summary

• skip immutable npm versions that are already published before attempting npm publish
• skip immutable JSR versions that are already published before attempting JSR publish
• add explicit SKIP_NPM_PUBLISH / SKIP_JSR_PUBLISH recovery switches
• add a manual recovery workflow for an existing tag such as v0.10.4

Why

The v0.10.4 tag published npm successfully, then JSR returned 429 Too Many Requests. A naive rerun would likely fail on already-published npm versions before it can retry JSR.

Validation

• node --check scripts/release/publish.mjs
• SKIP_NPM_PUBLISH=1 SKIP_JSR_PUBLISH=1 node scripts/release/publish.mjs
• node scripts/release/preflight.mjs
• pnpm -r run lint
• git diff --check
• pre-push hook reran pnpm -r run lint and pnpm -r test

Summary by CodeRabbit

• New Features

  • Added a manual “Recover Release” workflow to restore a release tag and ensure the matching release page exists.
  • Release publishing now avoids republishing versions that are already available, helping reduce duplicate publish attempts.

• Bug Fixes

  • Added safeguards to skip package publishing when artifacts already exist, and to optionally bypass npm/JSR publishing when needed.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

A new manual workflow validates a release tag, installs dependencies, runs the release publish script with npm publishing skipped, and creates a GitHub Release if needed. The publish script now skips npm or JSR publishes when versions already exist or skip flags are set.

Changes

Recover Release flow

Layer / File(s)	Summary
Publish script checks scripts/release/publish.mjs	Adds command and environment helpers, then skips npm and JSR publish steps when a version already exists or a skip flag is set.
Manual recovery workflow .github/workflows/recover-release.yml	Adds a manual workflow that validates the tag against package.json, installs dependencies, runs the publish script with SKIP_NPM_PUBLISH=1, and creates a GitHub Release with gh release view / gh release create when missing.

Sequence Diagram(s)

sequenceDiagram
  participant PublishScript as scripts/release/publish.mjs
  participant NpmRegistry as npm registry
  participant JsrRegistry as JSR registry

  PublishScript->>NpmRegistry: npm view name@version --json
  NpmRegistry-->>PublishScript: published version or 404
  PublishScript->>JsrRegistry: GET /@scope/name/meta.json
  JsrRegistry-->>PublishScript: package version metadata or 404

Loading

sequenceDiagram
  participant Runner as GitHub Actions runner
  participant ReleaseScript as scripts/release/publish.mjs
  participant GhCli as gh release
  participant GitHubReleases as GitHub Releases

  Runner->>ReleaseScript: pnpm release:publish with SKIP_NPM_PUBLISH=1
  ReleaseScript-->>Runner: publish complete
  Runner->>GhCli: gh release view TAG
  alt release missing
    Runner->>GhCli: gh release create --verify-tag --generate-notes TAG
    GhCli->>GitHubReleases: create release for TAG
  else release exists
    GhCli-->>Runner: existing release
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

A bunny hopped through tags so bright,
And tucked the release back into light.
With carrots cached and checks complete,
The registry dance was neat and sweet. 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: making release publish recovery idempotent.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/idempotent-release-publish

---

_{Comment @coderabbitai help to get the list of available commands.}