rvlib-shipkit 0.14.0 → 0.17.0

package/src/release/git-facts.ts

@@ -0,0 +1,133 @@
+// the git questions a release asks, in one place: which remote to push to,
+// what the worktree is hiding, which tags exist here but nowhere else.
+// Deliberately dependency-free (no config load, no ci) so a check script can
+// import it without dragging the gate in.
+import type { RepoConfig } from '../repo-config.ts'
+
+export function git(root: string, args: string[]): { code: number; out: string } {
+    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
+}
+
+/** the push remote: the current branch's upstream when it has one, else the
+ *  repo's single remote, else refuse. Never prefers a name: a repo whose
+ *  remote is not called `origin` is normal, and guessing strands the tag
+ *  somewhere nobody looks. */
+export function deriveRemote(root: string): { remote: string } | { error: string } {
+    const branch = git(root, ['branch', '--show-current']).out
+    if (branch !== '') {
+        const r = git(root, ['config', '--get', `branch.${branch}.remote`])
+        if (r.code === 0 && r.out !== '') return { remote: r.out }
+    }
+    const r = git(root, ['remote'])
+    if (r.code !== 0) return { error: 'git remote failed (not a repo?)' }
+    const remotes = r.out.split('\n').map((l) => l.trim()).filter((l) => l !== '')
+    if (remotes.length === 0) return { error: 'no git remote configured' }
+    if (remotes.length === 1) return { remote: remotes[0]! }
+    return { error: `branch '${branch === '' ? '(detached)' : branch}' has no upstream and ${remotes.length} remotes exist (${remotes.join(', ')}) — set one with git push -u <remote> <branch>` }
+}
+
+/** the worktree's dirty paths, minus the runner's own log dir. running the
+ *  gate creates that dir, so counting it would make every gated release refuse
+ *  in any repo that does not gitignore it. */
+export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string): string {
+    const logRoot = (config.logDir ?? 'tmp/shipkit-ci').replace(/^\.\//, '').split('/')[0]!
+    const args = pathspec != null && pathspec !== '' ? ['status', '--porcelain', '--', pathspec] : ['status', '--porcelain']
+    return git(root, args).out
+        .split('\n')
+        .filter((l) => l.trim() !== '' && !l.slice(3).trim().replace(/^"|"$/g, '').startsWith(`${logRoot}/`) && l.slice(3).trim() !== `${logRoot}/`)
+        .join('\n')
+}
+
+export const tagExistsLocally = (root: string, tag: string): boolean =>
+    git(root, ['rev-parse', '--quiet', '--verify', `refs/tags/${tag}`]).code === 0
+
+export type RemoteTags = { tags: Set<string> } | { error: string }
+/** tag name → the COMMIT it names on the remote (the peeled oid when the tag
+ *  is annotated), so two tags of the same name can be compared by what they
+ *  describe rather than by their spelling */
+export type RemoteTagRefs = { refs: Map<string, string> } | { error: string }
+
+/** every tag the remote carries, with its commit. One `ls-remote` per repo,
+ *  never one per tag: the caller compares locally. Deliberately unpatterned,
+ *  because `ls-remote <pattern>` drops the peeled `^{}` line and leaves only
+ *  the tag OBJECT id, which differs between two tags of the same commit. */
+export function remoteTagRefs(root: string, remote: string): RemoteTagRefs {
+    const p = Bun.spawnSync(['git', 'ls-remote', '--tags', remote], { cwd: root, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
+    if (p.exitCode !== 0) return { error: `${p.stderr.toString()}${p.stdout.toString()}`.trim().split('\n').at(-1) ?? 'ls-remote failed' }
+    const refs = new Map<string, string>()
+    for (const line of p.stdout.toString().split('\n')) {
+        const [oid, ref] = line.split('\t')
+        const name = ref?.split('refs/tags/')[1]
+        if (oid == null || name == null || name === '') continue
+        const peeled = name.endsWith('^{}')
+        const key = peeled ? name.slice(0, -3) : name
+        // the peeled line always wins, whichever order it arrives in
+        if (peeled || !refs.has(key)) refs.set(key, oid)
+    }
+    return { refs }
+}
+
+export function remoteTags(root: string, remote: string): RemoteTags {
+    const r = remoteTagRefs(root, remote)
+    return 'error' in r ? r : { tags: new Set(r.refs.keys()) }
+}
+
+export type RemoteTagState =
+    | { state: 'absent' }
+    | { state: 'same'; oid: string }
+    /** the name is taken on the remote by another commit — the version is burnt */
+    | { state: 'different'; remoteOid: string; localOid: string | null }
+    | { state: 'unreadable'; error: string }
+
+/** what the remote says about ONE tag. Comparing NAMES is what let a burnt
+ *  version read as "fully released": the tag was there, describing a tree
+ *  nobody released. */
+export function remoteTagState(root: string, remote: string, tag: string): RemoteTagState {
+    const r = remoteTagRefs(root, remote)
+    if ('error' in r) return { state: 'unreadable', error: r.error }
+    const remoteOid = r.refs.get(tag)
+    if (remoteOid == null) return { state: 'absent' }
+    const local = git(root, ['rev-parse', `${tag}^{}`])
+    const localOid = local.code === 0 ? local.out : null
+    return localOid === remoteOid ? { state: 'same', oid: remoteOid } : { state: 'different', remoteOid, localOid }
+}
+
+export type MergeProbe =
+    | { state: 'clean' }
+    | { state: 'conflicts'; paths: string[] }
+    /** this git could not answer, so the caller must not claim either way */
+    | { state: 'unknown'; reason: string }
+
+/** would `from` merge into `tip` cleanly? Answered from the object database:
+ *  `git merge-tree --write-tree` (git 2.38+) writes nothing but objects, so no
+ *  ref moves and no file is checked out. That is what lets a REHEARSAL answer
+ *  the merge question without touching the branch a human treats as a gate.
+ *
+ *  exit 1 covers both conflicts and a ref git could not resolve, so the tree
+ *  oid on stdout is what separates them: no oid means no merge was attempted. */
+export function mergeProbe(root: string, tip: string, from: string): MergeProbe {
+    // env is passed explicitly: Bun resolves argv[0] against the PATH it
+    // captured at startup unless it is, so an older git ahead on PATH would
+    // never be reached, here or in a test that stages one
+    const p = Bun.spawnSync(['git', 'merge-tree', '--write-tree', '--name-only', tip, from], { cwd: root, env: process.env })
+    const out = p.stdout.toString()
+    const [head, ...rest] = out.split('\n')
+    const wroteTree = head != null && /^[0-9a-f]{40}$/.test(head.trim())
+    if (p.exitCode === 0 && wroteTree) return { state: 'clean' }
+    if (p.exitCode === 1 && wroteTree)
+        return { state: 'conflicts', paths: (rest.join('\n').split('\n\n')[0] ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '') }
+    const reason = `${p.stderr.toString()}${out}`.trim().split('\n').filter((l) => l !== '').at(-1) ?? `git merge-tree exited ${p.exitCode}`
+    return { state: 'unknown', reason: `${reason} (needs git 2.38+)` }
+}
+
+/** local tags matching any of the release units' tag shapes that the remote
+ *  does not have. A stranded tag is invisible where he looks (GitHub), so it
+ *  is a failure, not a note. */
+export function strandedTags(p: { root: string; globs: string[]; remote: string }): { stranded: string[]; local: string[] } | { error: string } {
+    const local = p.globs.flatMap((g) => git(p.root, ['tag', '-l', g]).out.split('\n').map((l) => l.trim()).filter((l) => l !== ''))
+    const uniq = [...new Set(local)].sort()
+    const r = remoteTags(p.root, p.remote)
+    if ('error' in r) return r
+    return { stranded: uniq.filter((t) => !r.tags.has(t)), local: uniq }
+}

package/src/release/run-bump.ts

@@ -0,0 +1,436 @@
+// the whole release from one word. each step is trivial, the sequence is
+// what costs time and produces half-released states, so the sequence is the
+// command.
+//
+// order is load-bearing. The MERGE happens first, because every fact a bump
+// writes (the next version, the tag, the per-unit gate) must describe the
+// merged tree, never the branch it was computed on. Nothing is pushed until
+// the very end, so any refusal rolls the merge back and returns you to your
+// branch. The gate then runs before anything is written, so a red repo never
+// gets a version bump commit, and the prepublish scripts run before the
+// commit, so a failing build cannot be tagged. publishing is delegated to
+// run-release.
+//
+// --dry-run is the ONE exception, and deliberately so: it is the command you
+// run BECAUSE you do not want to touch anything, so a rehearsal that merges
+// and rolls back is wrong even when the rollback works. It probes the merge
+// in the object database instead (git-facts mergeProbe) and gates the
+// UNMERGED tree, saying so. That is strictly less proof than a real bump,
+// which is why the report states what it did NOT cover.
+//
+// every window where the release branch carries an unagreed merge is closed
+// on the way out: the rollback reads both git exit codes, and an interrupt
+// during the gate or the prepublish scripts runs it too.
+//
+// with several units the ATOMIC part is the version commit: one commit holds
+// every selected unit's package.json and changelog. The publish part is
+// RESUMABLE instead, because an npm publish cannot be undone and a rollback
+// that cannot roll back is a lie.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { relative } from 'path'
+import { declaredKind, hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
+import { deriveRemote, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
+import { unitBlockers } from './unit-gate.ts'
+import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
+import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type BumpKind = 'major' | 'minor' | 'patch'
+
+/** next version, X.Y.Z only. A prerelease or build suffix is refused rather
+ *  than silently mangled: guessing what `1.2.3-beta.1` plus "minor" means is
+ *  exactly the kind of doubt this tool exists to remove. */
+export function nextVersion(current: string, kind: BumpKind): string {
+    const m = current.match(/^(\d+)\.(\d+)\.(\d+)$/)
+    if (m == null) throw new Error(`version '${current}' is not plain X.Y.Z — bump it by hand, then release`)
+    const [maj, min, pat] = [Number(m[1]), Number(m[2]), Number(m[3])]
+    if (kind === 'major') return `${maj + 1}.0.0`
+    if (kind === 'minor') return `${maj}.${min + 1}.0`
+    return `${maj}.${min}.${pat + 1}`
+}
+
+export type BumpOpts = {
+    /** rehearse: gate and prepublish scripts run, nothing is written, and no
+     *  merge is made — the merge is probed in the object database instead */
+    dryRun?: boolean
+    /** stop after committing the bump, do not tag or publish */
+    noRelease?: boolean
+    /** refuse on a feature branch instead of merging it into the release branch */
+    noMerge?: boolean
+    /** which unit to bump (default 'root') */
+    unit?: string
+    /** bump every unit whose changelog carries non-empty Unreleased notes */
+    all?: boolean
+    print?: (line: string) => void
+}
+
+type Git = (args: string[]) => { code: number; out: string }
+
+/** bring a feature branch onto the release branch with a merge commit, and
+ *  hand back a rollback. nothing here is pushed, so a later failure can undo
+ *  the merge completely and put the caller back where it started. */
+function mergeIntoReleaseBranch(
+    git: Git,
+    p: { from: string; to: string; remote: string; print: (l: string) => void },
+): { ok: true; rollback: () => void } | { ok: false } {
+    const { from, to, remote, print } = p
+    git(['fetch', remote, '--quiet'])
+    // every return-to-the-branch is checked: a silent checkout failure leaves
+    // HEAD on the release branch while the line above says otherwise, and the
+    // operator's next commit lands there
+    const restore = (): boolean => {
+        const r = git(['checkout', '--quiet', from])
+        if (r.code === 0) return true
+        print(`FAIL: could not return to '${from}' (git checkout exited ${r.code}) — HEAD is STILL on '${to}', your next commit would land there`)
+        for (const l of r.out.split('\n').slice(0, 4)) print(`      ${l}`)
+        print(`      fix: git checkout ${from}`)
+        return false
+    }
+
+    const co = git(['checkout', '--quiet', to])
+    if (co.code !== 0) { print(`FAIL: cannot switch to '${to}' — ${co.out}`); return { ok: false } }
+
+    // fast-forward only: a release branch that diverged from its remote is a
+    // human decision, never something a release command resolves
+    const remoteHead = git(['rev-parse', '--quiet', '--verify', `${remote}/${to}`])
+    if (remoteHead.code === 0) {
+        const ff = git(['merge', '--ff-only', `${remote}/${to}`])
+        if (ff.code !== 0) {
+            print(`FAIL: '${to}' has diverged from ${remote}/${to} — reconcile it by hand`)
+            restore()
+            return { ok: false }
+        }
+    }
+    const before = git(['rev-parse', 'HEAD']).out
+    const merge = git(['merge', '--no-ff', from, '-m', `merge ${from}`])
+    if (merge.code !== 0) {
+        print(`FAIL: merging '${from}' into '${to}' hit conflicts, nothing was changed`)
+        for (const l of merge.out.split('\n').slice(0, 8)) print(`      ${l}`)
+        git(['merge', '--abort'])
+        restore()
+        return { ok: false }
+    }
+    print(`ok: merged '${from}' into '${to}' (merge commit, not pushed yet)`)
+    return {
+        ok: true,
+        rollback: () => {
+            // the merge was never pushed, so this drops only local work. Both
+            // calls are READ: an index.lock from a concurrent run makes the
+            // reset fail, and announcing a rollback that did not happen is how
+            // a merge nobody agreed to gets pushed by the next command.
+            const reset = git(['reset', '--hard', before])
+            if (reset.code !== 0) {
+                print(`FAIL: rollback FAILED — '${to}' STILL carries the merge (git reset --hard exited ${reset.code})`)
+                for (const l of reset.out.split('\n').slice(0, 4)) print(`      ${l}`)
+                print(`      fix: git reset --hard ${before} && git checkout ${from}`)
+                return
+            }
+            if (restore()) print(`ok: rolled '${to}' back and returned to '${from}' — nothing was pushed`)
+        },
+    }
+}
+
+/** the rehearsal's answer to the same two questions, from the object database:
+ *  has the release branch diverged from its remote, and would the merge
+ *  conflict. Nothing is checked out and no ref moves, which is the whole point
+ *  of a dry run. It must answer for the tree the REAL path would build, so a
+ *  release branch that exists only on the remote resolves to the remote ref:
+ *  that is exactly what `git checkout <to>` creates. `refuse` stops the run,
+ *  and `inconclusive` forbids the closing "dry run clean" claim. */
+type MergeRehearsal = { refuse: true } | { refuse: false; inconclusive: boolean }
+
+function probeMergeIntoReleaseBranch(
+    root: string,
+    git: Git,
+    p: { from: string; to: string; remote: string; print: (l: string) => void },
+): MergeRehearsal {
+    const { from, to, remote, print } = p
+    // a rehearsal's ONLY product is this answer, so it must not be computed
+    // from a remote ref that never refreshed. Offline, an expired credential
+    // or a declined prompt all land here.
+    const fetched = git(['fetch', remote, '--quiet'])
+    const stale = fetched.code !== 0
+    if (stale) print(`WARN could not fetch '${remote}' (git fetch exited ${fetched.code}) — the remote refs below may be stale`)
+    const remoteRef = `${remote}/${to}`
+    const localExists = git(['rev-parse', '--quiet', '--verify', to]).code === 0
+    const remoteExists = git(['rev-parse', '--quiet', '--verify', remoteRef]).code === 0
+    if (!localExists && !remoteExists) {
+        print(`FAIL: no branch '${to}' here or on '${remote}' — a release needs a branch to ship from`)
+        return { refuse: true }
+    }
+    let tip = localExists ? to : remoteRef
+    if (localExists && remoteExists) {
+        // the real path fast-forwards, which succeeds when either side is an
+        // ancestor of the other and refuses only on a genuine divergence
+        const behind = git(['merge-base', '--is-ancestor', to, remoteRef]).code === 0
+        const ahead = git(['merge-base', '--is-ancestor', remoteRef, to]).code === 0
+        if (!behind && !ahead) { print(`FAIL: '${to}' has diverged from ${remoteRef} — reconcile it by hand`); return { refuse: true } }
+        if (behind) tip = remoteRef
+    }
+    const probe = mergeProbe(root, tip, from)
+    if (probe.state === 'conflicts') {
+        print(`FAIL: '${from}' would conflict with '${to}' — nothing was merged, nothing was changed`)
+        for (const path of probe.paths.slice(0, 8)) print(`      ${path}`)
+        return { refuse: true }
+    }
+    if (probe.state === 'unknown') {
+        print(`WARN cannot check the merge without touching the worktree (${probe.reason}) — the rehearsal does not know whether '${from}' merges into '${to}'`)
+        return { refuse: false, inconclusive: true }
+    }
+    print(`note: '${from}' merges cleanly into '${to}' (checked in the object database, no ref moved)`)
+    // a clean answer computed from refs that never refreshed proves less than
+    // it says, so the rehearsal declines to close clean
+    return { refuse: false, inconclusive: stale }
+}
+
+type Selected = { unit: ReleaseUnit; version: string; changelogRel: string; kind: BumpKind }
+
+export async function runBump(root: string, config: RepoConfig, kind: BumpKind | null, o: BumpOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    if (o.all === true && o.unit != null) { print('FAIL: pass a unit or --all, never both'); return 1 }
+
+    const git: Git = (args) => gitAt(root, args)
+    const cur = git(['rev-parse', '--abbrev-ref', 'HEAD']).out
+    const branch = config.release?.branch ?? 'main'
+
+    // pre-merge, ONLY what a merge cannot change: a typo'd unit id, a dirty
+    // tree, the branch decision, the remote. Everything the bump WRITES is
+    // computed after the merge, off the tree that actually ships.
+    const onDisk = resolveUnits(root, config)
+    if (onDisk.errors.length > 0) { for (const e of onDisk.errors) print(`FAIL: ${formatUnitError(e)}`); return 1 }
+    if (o.all !== true) {
+        const id = o.unit ?? 'root'
+        if (unitById(onDisk.units, id) == null) {
+            print(`FAIL: no release unit '${id}' — known units: ${onDisk.units.map((x) => x.id).join(', ')}`)
+            print('      fix: shipkit releases')
+            return 1
+        }
+    }
+    // the tree must be clean BEFORE any branch move, or a checkout carries
+    // uncommitted work across branches
+    const dirty = dirtyPaths(root, config)
+    if (dirty !== '') { print(`FAIL: working tree not clean, commit your work first:\n${dirty.split('\n').slice(0, 10).join('\n')}`); return 1 }
+
+    const wantMerge = cur !== branch && o.noMerge !== true && (config.release?.mergeFromBranch ?? true)
+    if (cur !== branch && !wantMerge) { print(`FAIL: releases ship from '${branch}', HEAD is on '${cur}'`); return 1 }
+    const remote = deriveRemote(root)
+    if ('error' in remote) { print(`FAIL: ${remote.error}`); return 1 }
+    if (wantMerge) print(`note: on '${cur}', so '${cur}' merges into '${branch}' first`)
+
+    // the merge happens FIRST among the writes, so every fact below describes
+    // the tree that ships. Nothing here is pushed, so every refusal rolls it
+    // back whole. A rehearsal merges NOTHING and says what it therefore did
+    // not prove (the file header owns the reasoning).
+    const rehearsal = o.dryRun === true
+    let rollback: (() => void) | null = null
+    let onInterrupt: (() => void) | null = null
+    let mergeUnknown = false
+    if (wantMerge && rehearsal) {
+        const probe = probeMergeIntoReleaseBranch(root, git, { from: cur, to: branch, remote: remote.remote, print })
+        if (probe.refuse) return 1
+        mergeUnknown = probe.inconclusive
+    } else if (wantMerge) {
+        const m = mergeIntoReleaseBranch(git, { from: cur, to: branch, remote: remote.remote, print })
+        if (!m.ok) return 1
+        rollback = m.rollback
+        // the merge window spans the gate and the prepublish scripts, and
+        // nothing there handles an interrupt: Ctrl-C used to leave the merge
+        // on the release branch with not a line printed about it
+        onInterrupt = () => { print(`FAIL: interrupted — rolling '${branch}' back`); rollback?.(); process.exit(130) }
+        process.on('SIGINT', onInterrupt)
+        process.on('SIGTERM', onInterrupt)
+    }
+    // shut the window: after this the merge is either undone or permanent, and
+    // an interrupt must never reset --hard over files the operator has to keep
+    const closeMergeWindow = (): void => {
+        if (onInterrupt != null) { process.off('SIGINT', onInterrupt); process.off('SIGTERM', onInterrupt); onInterrupt = null }
+        rollback = null
+    }
+    const rollBack = (): void => { rollback?.(); closeMergeWindow() }
+    const fail = (msg: string, fixLine?: string): number => {
+        print(`FAIL: ${msg}`)
+        if (fixLine != null) print(`      fix: ${fixLine}`)
+        rollBack()
+        return 1
+    }
+
+    // phase 1, on the MERGED tree (on the FEATURE tree in a rehearsal): the
+    // resolution, the selection, the next versions, the tag refusals and the
+    // per-unit gate all describe what ships
+    const resolved = resolveUnits(root, config)
+    // bump can touch several units at once, so ANY unresolved unit is fatal:
+    // a selection built from a partial model is a selection nobody can trust
+    if (resolved.errors.length > 0) { for (const e of resolved.errors) print(`FAIL: ${formatUnitError(e)}`); rollBack(); return 1 }
+    const all = releaseOrder(resolved.units)
+
+    // selection. `--all` reads the changelogs: a unit with nothing to say is
+    // skipped, not failed, so `--all` means "ship everything that has news".
+    let picked: ReleaseUnit[]
+    if (o.all === true) {
+        picked = []
+        for (const u of all) {
+            if (!existsSync(u.changelog)) { print(`skip: ${u.id} — no changelog at ${relative(root, u.changelog)}`); continue }
+            if (hasUnreleasedNotes(readFileSync(u.changelog, 'utf8'))) picked.push(u)
+            else print(`skip: ${u.id} — no Unreleased notes`)
+        }
+        if (picked.length === 0) return fail('no unit has non-empty Unreleased notes — write what changed, then bump')
+    } else {
+        const id = o.unit ?? 'root'
+        const u = unitById(all, id)
+        if (u == null) return fail(`no release unit '${id}' after the merge — known units: ${all.map((x) => x.id).join(', ')}`, 'shipkit releases')
+        picked = [u]
+    }
+
+    // one ls-remote for the whole run: a tag name the remote already carries
+    // is a burnt version, and finding that out AFTER the version commit leaves
+    // a number nobody can ship
+    const onRemote = remoteTags(root, remote.remote)
+    if ('error' in onRemote) return fail(`cannot read tags on '${remote.remote}' (${onRemote.error}) — a bump that cannot see the remote's tags can burn a version`)
+
+    const blockers: string[] = []
+    const selected: Selected[] = []
+    for (const unit of picked) {
+        const changelogRel = relative(root, unit.changelog)
+        if (!existsSync(unit.changelog)) { blockers.push(`unit '${unit.id}': ${changelogRel} not found — a release states what changed`); continue }
+        const source = readFileSync(unit.changelog, 'utf8')
+        // an explicit kind on the command line wins for the whole selection.
+        // Without one, each unit answers for itself from its own heading, and
+        // a unit that never said is a refusal: guessing a version number
+        // publishes it, and a published number cannot be recalled.
+        const unitKind = kind ?? declaredKind(source)
+        if (unitKind == null) {
+            blockers.push(`unit '${unit.id}': ${changelogRel} does not say what kind of release this is — write "## Unreleased (minor)", or pass a kind that applies to every selected unit`)
+            continue
+        }
+        let version: string
+        try { version = nextVersion(unit.version, unitKind) }
+        catch (e) { blockers.push(`unit '${unit.id}': ${e instanceof Error ? e.message : String(e)}`); continue }
+        const promoted = promoteUnreleased(source, version)
+        if ('error' in promoted) { blockers.push(`unit '${unit.id}': ${promoted.error}`); continue }
+        const tag = renderTag(unit, version)
+        if (tagExistsLocally(root, tag)) {
+            blockers.push(`unit '${unit.id}': tag ${tag} already exists here — finish that release with \`shipkit release ${unit.id}\`, or pick another bump`)
+            continue
+        }
+        if (onRemote.tags.has(tag)) {
+            blockers.push(`unit '${unit.id}': tag ${tag} already exists on '${remote.remote}' — that version number is taken, pick another bump`)
+            continue
+        }
+        blockers.push(...unitBlockers(root, config, unit))
+        selected.push({ unit, version, changelogRel, kind: unitKind })
+    }
+    // everything the release needs that does not depend on the new version.
+    // HEAD is the release branch by now, so the branch check applies — except
+    // in a rehearsal that deliberately stayed on the feature branch, where the
+    // branch decision was already made and refused above
+    blockers.push(...environmentBlockers(root, config, {
+        wantGh: picked.some((u) => u.targets.githubRelease),
+        skipBranch: rehearsal && wantMerge,
+    }))
+    if (blockers.length > 0) { for (const b of blockers) print(`FAIL: ${b}`); rollBack(); return 1 }
+
+    for (const s of selected) print(`note: ${s.unit.id} ${s.unit.version} → ${s.version} (${s.kind})`)
+
+    // phase 2: ONE gate for the whole repo. The repo is one worktree, so N
+    // gates cost N times as much and prove the same thing. Frozen, and fatal
+    // on non-blocking failures when the repo declared requireHealthy.
+    // releaseUnit then skips it, because bump already proved this exact tree.
+    if ((await runReleaseGate(root, config, print, { fix: true })) !== 0) return fail('ci gate is red on the merged result — fix it, then bump')
+    // the gate's fix pass can rewrite files. writing a version on top of that
+    // produces a version commit that excludes the rewrite and a release that
+    // then refuses on a dirty tree, which is a half-released repo.
+    const afterGate = dirtyPaths(root, config)
+    if (afterGate !== '')
+        return fail(
+            `the gate rewrote files, so the tree is no longer clean:\n${afterGate.split('\n').slice(0, 10).join('\n')}`,
+            rollback != null
+                ? 'the rollback below discards them. run `shipkit ci` on your branch, commit what it rewrites, then bump again'
+                : 'run `shipkit ci`, commit what it rewrites, then bump again',
+        )
+    print('ok: ci gate green')
+
+    for (const s of selected) {
+        for (const script of unitPrepublishScripts(s.unit)) {
+            const r = Bun.spawnSync(['bun', 'run', script], { cwd: s.unit.dir, stdout: 'inherit', stderr: 'inherit' })
+            if (r.exitCode !== 0) return fail(`${s.unit.id}: ${script} failed (exit ${r.exitCode}) — nothing was written`)
+            print(`ok: ${s.unit.id} ${script}`)
+        }
+    }
+    if (selected.every((s) => unitPrepublishScripts(s.unit).length === 0)) print('note: no prepublish scripts')
+
+    if (rehearsal) {
+        const what = selected.map((s) => `${s.unit.id} ${s.version}`).join(', ')
+        // a rehearsal that could not answer the merge question must not close
+        // with the word "clean": that green is what sends an operator into a
+        // real bump that aborts mid-merge
+        if (mergeUnknown) print(`WARN dry run inconclusive — would write ${what}, but the merge into '${branch}' could not be checked (git 2.38+ answers it)`)
+        else print(`ok: dry run clean — would write ${what}, commit, then ${o.noRelease === true ? 'stop' : 'release'}`)
+        // what the rehearsal did NOT cover, said out loud: a merge that never
+        // happened cannot have been gated, and a number computed on the
+        // feature branch can differ from the one the real bump writes
+        if (wantMerge)
+            print(`      it did NOT merge: '${branch}' never moved, and everything above (versions, tags, gate) describes '${cur}' UNMERGED`)
+        rollBack()
+        return 0
+    }
+
+    // phase 3: ONE version commit holding every selected unit's two files.
+    // Partial writes are the half-released state this whole command exists to
+    // prevent, so the write and the commit are one step for the whole selection.
+    //
+    // from the first write on, a failure NEVER rolls back: `git reset --hard`
+    // would delete the very files the fix line tells the operator to commit.
+    // What is on disk is reported as it is, interrupts included.
+    closeMergeWindow()
+    const failKeep = (msg: string, fixLine: string): number => { print(`FAIL: ${msg}`); print(`      fix: ${fixLine}`); return 1 }
+    const files: string[] = []
+    for (const s of selected) {
+        const pkgRel = s.unit.rel === '' ? 'package.json' : `${s.unit.rel}/package.json`
+        // re-read: a merge can have changed both files under us
+        const pkgNow = readFileSync(`${root}/${pkgRel}`, 'utf8')
+        const promoted = promoteUnreleased(readFileSync(s.unit.changelog, 'utf8'), s.version)
+        if ('error' in promoted) return failKeep(`${s.unit.id}: ${promoted.error}`, `check ${s.changelogRel}, then run bump again`)
+        // indentation is preserved by rewriting only the version VALUE, so a bump
+        // never reformats a file the repo cares about
+        const bumped = pkgNow.replace(/("version"\s*:\s*")[^"]*(")/, `$1${s.version}$2`)
+        if (bumped === pkgNow) return failKeep(`${s.unit.id}: could not rewrite the version field in ${pkgRel}`, `git status, then set the version by hand`)
+        writeFileSync(`${root}/${pkgRel}`, bumped)
+        writeFileSync(s.unit.changelog, promoted.text)
+        files.push(pkgRel, s.changelogRel)
+        print(`ok: ${pkgRel} ${s.version}, ${s.changelogRel} section promoted`)
+    }
+
+    const add = git(['add', ...files])
+    if (add.code !== 0) return failKeep('git add failed', 'the version files are written but unstaged. git status, then commit them')
+    const label = selected.map((s) => (s.unit.id === 'root' ? s.version : `${s.unit.id}@${s.version}`)).join(', ')
+    // the hooks already ran through the gate above; --no-verify is NOT used,
+    // so the repo's own commit gates still apply to this commit
+    const commit = git(['commit', '-m', `release ${label}`])
+    if (commit.code !== 0)
+        return failKeep(`commit failed — ${commit.out}`, 'the version files are written but uncommitted. fix the gate, commit, then `shipkit release`')
+    print(`ok: committed release ${label}`)
+
+    if (o.noRelease === true) { print(`ok: bumped ${label}, not released (--no-release)`); return 0 }
+
+    // phase 4: publish per unit, sequentially. A failure STOPS and never rolls
+    // back: the version commit already landed for every unit, so each one
+    // resumes with `shipkit release <id>` and no re-bump.
+    const fresh = resolveUnits(root, config)
+    if (fresh.errors.length > 0) { for (const e of fresh.errors) print(`FAIL: ${formatUnitError(e)}`); return 1 }
+    const order = selected.map((s) => unitById(fresh.units, s.unit.id)).filter((u): u is ReleaseUnit => u != null)
+    for (let i = 0; i < order.length; i++) {
+        const u = order[i]!
+        const code = await releaseUnit(root, config, u, {
+            skipGate: true,
+            skipGateReason: 'already green on this tree (bump ran it)',
+            skipUnitGate: true,
+            print,
+        })
+        if (code !== 0) {
+            print(`FAIL: ${u.id} did not finish — the version commit is already in, so nothing needs re-bumping`)
+            for (const rest of order.slice(i)) print(`      fix: shipkit release ${rest.id}`)
+            return 1
+        }
+    }
+    return 0
+}