l-make-release
Release @takazudo/mdx-formatter — bump the version, sync platform packages, write the changelog, integrate on main, wait for CI, run the release coordinator (dry run, then the real start) so Actions t...
/l-make-release
One-call orchestrator for releasing @takazudo/mdx-formatter and its four lockstep platform packages. Bumps the version, syncs the platform packages, writes a changelog doc, integrates the bump on main, waits for CI on that exact commit, then dispatches .: a read-only dry run first, then the real start. The coordinator creates the v* tag at the frozen SHA with Actions' own token and explicitly dispatches release.yml, which builds the napi binaries, packs once, publishes all five npm packages through OIDC trusted publishing, moves both latest and next, verifies the registry and creates the GitHub Release. Full reference: scripts/.
Invocation & autonomy
This skill is model-invocable: a rough natural-language request like "bump version", "cut a release", or "release it" may trigger it.
Default: fully autonomous end-to-end — NEVER ask for confirmation, NEVER stop and wait. Steps 1–3 are read-only; print the Step 3 proposal (current → new version + categorized changelog) for visibility only and proceed straight into Step 4. The coordinator start with dry_run=false at Step 9 IS the publish trigger — do not pause to ask "tag?", "publish?", or any equivalent. The invocation itself is the authorization. A request that only asks to prepare or check a release is not an invocation of this skill's publish steps.
--confirm option (opt-in interactive mode). When the invocation includes --confirm (e.g. /, /), restore interactive behavior: present the Step 3 proposal and wait for explicit user confirmation before the first mutation (Step 4), and stop after Step 8 (coordinator dry run green) — report the version, the frozen SHA and the coordinator inputs for dry_run=false, and let the user start it. Use this when the version strategy or release notes need vetting.
Architecture (why this works)
The four platform packages (
npm/darwin-arm64,npm/darwin-x64,npm/linux-x64-gnu,npm/win32-x64-msvc) are pnpm workspace members, declared on the root as pinnedworkspace:X.Y.ZoptionalDependencies. They resolve locally at bump time — before the new versions exist on the registry — so the lockfile stays consistent and bump-commit CI is green. (The pre-workspace flow could never have green CI on the bump commit:ERR_PNPM_OUTDATED_LOCKFILE, see v1.2.1 history.)scripts/keeps all fivesync- napi- versions. mjs package.jsonversions + theworkspace:specifiers lockstep with the root version.release.ymlpacks once — the platform packages withnpm pack, the root withpnpm pack(which rewritesworkspace:X.Y.Z→ exactX.Y.Z) — verifies the tarballs and the shipped Linux binary, then publishes those exact files withnpm publish <tgz>through OIDC, natives first. An existing version must have identical bytes; a version is never republished.Stable releases only — no prereleases. The
-next.Nline was retired after1.3.0-next.5. Every release publishes underlatest, thenrelease.ymlmovesnextto the same version, sonextis just an alias oflatestand anyone still installing@nextlands on the stable release. Don't delete thenexttag:@nextinstalls would fail.No npm token. npm authenticates the
publishjob through GitHub OIDC (trusted publisher: ownerTakazudo, repomdx-formatter, workflowrelease.yml, no environment, allowednpm publish+npm dist-tag, on each of the five packages). The job refusesNPM_TOKEN/NODE_AUTH_TOKEN/ npmrc tokens rather than falling back to them.Why a coordinator. Claude Code Cloud's
ghis not authenticated and its git proxy can refuse tag pushes.release-coordinator.yml(dispatched onmain) creates the tag with Actions' ownGITHUB_TOKENand dispatchesrelease.ymlexplicitly, because a tag created withGITHUB_TOKENdoes not trigger push workflows.
Boundaries
This skill never runs
npm publish/pnpm publish/npm dist-taglocally and never adds an npm token, PAT or other credential. Publishing happens only inrelease.yml.The GitHub Release is created by
release.yml'sfinalizejob after all five packages and both dist-tags are verified.Never move or delete a
v*tag. The coordinator refuses a tag at another commit and keeps an identical one.Never create a prerelease (
X.Y.Z-next.Nor any other suffix), even if asked for "next". Ship a stable version instead.
Step 1: Preconditions
Verify ALL of the following. If any check fails, stop with a clear message.
Current branch is
main(git branch --show-current), or, in Claude Code Cloud, the session branch freshly created from the latestorigin/mainWorking tree is clean (
git status --porcelainreturns empty)Know which GitHub capabilities exist: an authenticated
gh(gh auth status), or the GitHub MCP tools (actions_run_trigger,actions_list,create_pull_request,merge_pull_request). In Claude Code Cloudghis usually unauthenticated; use the MCP tools. If neither can dispatch a workflow, stop after Step 7 and hand the user the coordinator inputs (Actions UI fallback).First OIDC release only (until one release has shown
_npmUser.trustedPublisheron all five): ask the user to confirm on npmjs.com that each of the five packages has an active (not expired) trusted publisher forrelease.ymlallowingnpm publishandnpm dist-tag. npm expires a new configuration that sees no successful publish within two days; registration alone does not prove OIDC publishing works. You cannot read these settings without the owner's login.Tags are fresh and at least one
v*tag exists:git fetch --tags origin git tag -l 'v*' --sort=-v:refname | head -1
Step 2: Determine Next Version
Read the current version from the root package.json.
No argument
Current is a leftover prerelease
X.Y.Z-next.N: finalize it →X.Y.Z(analyze commits since the last stable tag, skipping-next.*tags).Current is stable
X.Y.Z: analyze commits since the last tag (Step 3) and pick autonomously:breaking changes → major
new features → minor
otherwise → patch
major / minor / patch argument
Stable release with that bump from the current stable version (e.g. patch: 1.2.1 → 1.2.2). If the current version is a leftover prerelease, bump from its base (1.3.0-next.5 + patch → 1.3.0, + minor → 1.3.0, + major → 2.0.0).
Guard: version must not already exist on npm
A partially recovered prior run may have published the computed version even though the local state suggests otherwise. Always check, and bump past any hit:
node -e "fetch('https://registry.npmjs.org/@takazudo%2fmdx-formatter',{headers:{'Cache-Control':'no-cache'}}).then(async r=>{if(r.status!==200)throw new Error('HTTP '+r.status);const d=await r.json();console.log(d.versions['<version>']?'TAKEN':'FREE')}).catch(e=>{console.error('UNKNOWN',e.message);process.exit(3)})"TAKEN → recompute (next patch) and re-check. UNKNOWN (network, 4xx/5xx) is not "free": retry later or stop.
Step 3: Analyze Changes and Propose
git log <last-tag>..HEAD --onelineCategorize each commit by judgment (this repo uses [formatter] / [doc] / [misc] / [claude] scope prefixes, not conventional commits — read the subjects and classify):
Breaking Changes: API/CLI behavior changes consumers must adapt to
Features: new capabilities
Bug Fixes: fixes to formatting behavior, CLI, or shipped binaries
Other Changes: docs, CI, deps, internal refactors
Present the proposal:
Proposed bump: {current} → {new} ({type})
Breaking Changes:
- description (hash)
Features:
- description (hash)
Bug Fixes:
- description (hash)
Other Changes:
- description (hash)Only show sections that have entries.
Default (autonomous): the printout is for visibility only — proceed straight to Step 4.
With
--confirm: wait for explicit user confirmation before proceeding.
Step 4: Bump + Sync + Changelog
4a. Bump the root version
Update the version field in the root package.json to the new version (no v prefix).
4b. Propagate to platform packages
pnpm sync:napi-versionsThis rewrites the four npm/ versions and the root's workspace:X.Y.Z optionalDependencies.
4c. Regenerate the lockfile
pnpm install --lockfile-only --no-frozen-lockfile--lockfile-only updates pnpm-lock.yaml without touching node_modules (avoids the non-TTY purge abort). The platform entries are workspace links, so the new version always resolves. The expected diff is exactly the four specifier: workspace:<old> → workspace:<new> lines — if anything structural appears, stop and surface it.
4d. Write the changelog doc
Create doc/:
---
title: 'v{VERSION}'
sidebar_position: { MAJOR * 1000 + MINOR * 100 + PATCH }
---
# v{VERSION}
Released: {YYYY-MM-DD}
## Breaking Changes
- Description (commit-hash)
## Features
- Description (commit-hash)
## Bug Fixes
- Description (commit-hash)
## Other Changes
- Description (commit-hash)Rules:
Only include sections that have entries
Use today's date
Each entry: commit subject with the short hash in parentheses
The changelog category sorts
desc, so the position formula puts newer versions on top
When finalizing a leftover prerelease, analyze ALL commits since the last stable tag (skipping -next.* tags) so the changelog covers the whole prerelease line.
Step 5: Build and Test
pnpm build:rust && pnpm build && pnpm testpnpm build:rust refreshes crates/ so the tests exercise the current Rust code, not a stale local binary. If anything fails, stop — nothing has been committed yet, so a full reset is:
git checkout -- . && git clean -f doc/src/content/docs/changelog/(git clean removes the untracked changelog mdx written in Step 4d.)
Step 6: Atomic Commit, Integrate on main
ONE commit containing everything (single revert = full rollback):
git add package.json npm/*/package.json pnpm-lock.yaml
git add doc/src/content/docs/changelog/v{VERSION}.mdx
git commit -m "chore(release): Bump to v{VERSION}"Local with push rights to
main:git push origin main.Claude Code Cloud (or no direct push): push the session branch, open a PR to
main, wait for its CI, and merge it with a regular merge.
Then read main's HEAD and keep it as SHA (full 40 characters). That is the frozen candidate; never replace it with a later main commit during this release.
Step 7: Wait for CI on the exact candidate
ci.yml's push run on main for exactly SHA must be green (a PR run does not count). Delegate to / when gh works (Skill(skill="watch-ci", args="--branch main --commit <SHA>")), otherwise poll actions_list → list_workflow_runs for ci.yml filtered by branch main and match head_sha. If it was cancelled by a later push, re-run it; do not freeze another commit.
Step 8: Coordinator dry run
Dispatch release-coordinator.yml on main with version={VERSION}, sha=<SHA>, dry_run=true:
Cloud:
actions_run_trigger(method: run_workflow,workflow_id: release-coordinator.yml,ref: main,inputs: {version, sha, dry_run: true}).With
gh:gh workflow run release-coordinator.yml --ref main -f version={VERSION} -f sha=<SHA> -f dry_run=true.
Find the run titled Release coordinator v{VERSION} @ <SHA> (dry run) and wait for it. It must be green; read its summary (CI run, npm state, warnings). A failure here changes nothing — fix the cause and repeat. Exit-3 style messages ("unknown", "pending") mean "check again later", never "not published".
With --confirm: STOP HERE and report version, SHA and the dry_run=false inputs.
Step 9: Start the release
Send the same inputs with dry_run=false. The tag job creates v{VERSION} at SHA (or keeps an identical one), and the dispatch job starts release.yml at the tag and prints the run id and attempt. A green coordinator is not a finished release. If the tag job reports HTTP 403, do not work around it with another credential; report GitHub's message and the candidate/control/workflow SHAs it printed and let the user decide (push the tag with their credentials, or freeze a new candidate).
Step 10: Watch the Release run
Follow the release.yml run the coordinator reported (match run id, tag v{VERSION} and SHA). Poll in the background (actions_get → get_workflow_run, or gh run view <id> --json status,conclusion) — never a foreground sleep.
Success:
finalizeprinted the five-package evidence table and the GitHub Release URL.Failure: read the failed job log. Re-send the coordinator with the same inputs: it reuses an active run, re-runs the failed jobs of the original run after a partial publish (same packed tarballs), or starts a new run when nothing was published. Never move the tag, never republish.
Step 11: Verify + Final Report
for PKG in @takazudo/mdx-formatter @takazudo/mdx-formatter-darwin-arm64 @takazudo/mdx-formatter-darwin-x64 @takazudo/mdx-formatter-linux-x64-gnu @takazudo/mdx-formatter-win32-x64-msvc; do
npm view "${PKG}@${VERSION}" version _npmUser.trustedPublisher dist.attestations.url
npm view "${PKG}" dist-tags --json
doneReport separately: npm publication (five exact versions, trusted publisher, provenance run id), dist-tags (latest and next = {VERSION} on all five), the tag (v{VERSION} → SHA), and the GitHub Release URL, plus the coordinator and release.yml run URLs.
Failure Recovery
Build or test failure (Step 5)
Nothing is committed yet. Reset the working tree, fix the issue, re-run the skill.
CI fails on the bump commit (Step 7)
Fix, commit, push, re-invoke /. Do not tag until green.
release.yml fails (Step 10)
Re-send the coordinator with the same
versionandSHA. It decides from observed state: an active run is reused, a partial publish re-runs the failed jobs of the original run (its packed tarballs are reused), nothing published → a new run. In the Actions UI, "Re-run failed jobs" on the original run is equivalent.different bytesin the publish log means npm already holds that version from another build. Do not force it; resume the original run instead, or leave the version and release the next patch.registry ... unknown/ exit 3: the registry could not be read. Wait and re-run; it is never treated as "not published".All five published but dist-tags or the GitHub Release missing → re-send the coordinator;
release.ymlthen skips uploads, checks provenance, synchronizes the tags and finalizes.
OIDC authentication failures
ENEEDAUTH, E404 Not Found - PUT or E403 from npm publish / npm dist-tag in the publish job mean npm did not accept the OIDC identity. Check, on npmjs.com for the failing package, that a trusted publisher exists with owner Takazudo, repository mdx-formatter, workflow release.yml (exact, with .yml), environment empty, and allowed actions npm publish and npm dist-tag; that the job still has id-token: write; and that npm is ≥ 11.21.0. Read the registry before retrying: a failed command does not prove nothing was published. Re-issuing an old npm token is not a fix; the workflows refuse tokens. If the owner decides to fall back temporarily, that is a separate, explicit change.
Historical stable-only latest repair
The repair-tags.yml workflow remains for the September 2026 stable-only recovery. It does not implement the current both-tag policy. For a partial current release, re-send the coordinator (or "Re-run failed jobs" on the original release.yml run) so its byte-checked publish and both-tag synchronization complete. Use the stable-only repair workflow only when deliberately restoring stable latest; follow scripts/ and verify that this is the intended policy for that incident.
Rolling back before the coordinator created the tag
The Step 6 commit is atomic — one revert undoes the bump, the lockfile, and the changelog doc:
git revert --no-edit <BUMP_SHA>
git push origin mainIf later commits already sit on top of the bump, do NOT revert; the stale version number is harmless — the next release bumps past it.
Never delete published things
Never delete a pushed v* tag, a published GitHub Release, or unpublish an npm version. Abandoned/broken versions are superseded by the next bump.