@entro314labs/release-kit 2.9.3 → 2.10.0

package/release.mjs

@@ -42,11 +42,13 @@ import {
   mkdtempSync,
   readdirSync,
   readFileSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // CONFIG
@@ -91,6 +93,9 @@ import { createInterface } from 'node:readline/promises'
  *   verify          string   command run during preflight — a project's own gate (tests,
  *                            build). Non-zero aborts before anything mutates, instead of a
  *                            prepublishOnly hook failing after the commit, tag and push
+ *   requireGreen    boolean  refuse to release a HEAD that GitHub does not report green:
+ *                            pushed, every check run and commit status finished, none of
+ *                            them failed. See `checkHeadIsGreen`
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
  *                            ASSISTANTS, "auto" for the first available, or null. The
  *                            object form { tool, model, effort } also pins which model and
@@ -115,9 +120,10 @@ import { createInterface } from 'node:readline/promises'
 const STEPS = ['commit', 'version', 'changelog', 'tag', 'push', 'publish', 'release']
 
 /**
- * All seven. `commit` is a conditional default: it no-ops on a clean tree, and on a dirty
- * tree it proceeds only when a drafting assistant is configured — otherwise preflight
- * still refuses the unclean tree. Opt out with `--skip commit` or a `steps` config.
+ * All seven. `commit` no-ops on a clean tree; on a dirty tree it stages everything and
+ * commits it, with a drafted message when an assistant is configured and a generated
+ * `chore:` message naming the files otherwise. Opt out with `--skip commit` or a `steps`
+ * config, which restores the refusal on a dirty tree.
  */
 const DEFAULT_STEPS = [...STEPS]
 
@@ -145,6 +151,7 @@ const DEFAULTS = {
     '^(fixup|squash)!',
   ],
   verify: null,
+  requireGreen: false,
   hooks: {},
 }
 
@@ -185,11 +192,13 @@ release-kit — tag, publish, and release a JS/TS/Node project.
 
 Target (optional; defaults to the version already in package.json):
   <x.y.z>              release this exact version
+  auto                 infer the bump from the commits since the last tag
   patch minor major    bump from the current version
   prepatch preminor premajor prerelease
                        prerelease bump; needs --preid unless it can be inferred
 
-Steps, in the fixed order they run. All but "commit" run by default:
+Steps, in the fixed order they run. All seven run by default; "commit" no-ops on a
+clean tree:
   ${STEPS.join('  ')}
 
 Subcommands (they check, print or copy, and never start a release):
@@ -653,11 +662,29 @@ const CHANGELOG_SECTIONS = [
   { type: 'chore', section: 'Miscellaneous Chores' },
 ]
 
+/**
+ * The `Notes:` trailer in a commit body: the author's own wording for the release-notes
+ * entry, which beats anything derived from the subject. `Notes: no-notes` keeps the commit
+ * out of the notes altogether — a refactor that has to be a `fix:` for the version bump but
+ * that no reader upgrading needs to hear about. GitHub Desktop runs its notes this way.
+ *
+ * The version bump is not affected either way: the trailer decides what is said about a
+ * change, not whether it happened.
+ *
+ * @returns {{text: string|null, excluded: boolean}}
+ */
+function notesTrailer(body = '') {
+  const text = /^Notes:[ \t]*(\S.*)$/im.exec(body)?.[1]?.trim() ?? null
+  const excluded = !!text && /^no-notes$/i.test(text)
+  return { text: excluded ? null : text, excluded }
+}
+
 /**
  * Parse a commit into the parts a release cares about.
  *
  * @returns {{type: string, scope: string|null, breaking: boolean, subject: string,
- *   releaseAs: string|null} | null} null when the subject is not Conventional Commits
+ *   releaseAs: string|null, notes: string|null, noNotes: boolean} | null} null when the
+ *   subject is not Conventional Commits
  */
 function parseCommit(subject, body = '', hash = '') {
   // Conventional Commits does not restrict the type to letters — `i18n:` and `a11y:` are
@@ -676,6 +703,7 @@ function parseCommit(subject, body = '', hash = '') {
   // A BREAKING CHANGE footer usually explains the break far better than the subject does.
   const breakingNote =
     /^BREAKING[ -]CHANGE:\s*([\s\S]+?)(?=\n\n|$)/m.exec(body)?.[1]?.trim() ?? null
+  const trailer = notesTrailer(body)
   return {
     type: type.toLowerCase(),
     scope: scope ?? null,
@@ -685,6 +713,8 @@ function parseCommit(subject, body = '', hash = '') {
     releaseAs,
     closes: [...new Set(closes)],
     breakingNote,
+    notes: trailer.text,
+    noNotes: trailer.excluded,
   }
 }
 
@@ -723,7 +753,9 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
 function changelogFromCommits(commits, links = null, hidden = [], contributors = []) {
-  const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
+  const parsed = commits
+    .map((c) => parseCommit(c.subject, c.body, c.hash))
+    .filter((c) => c && !c.noNotes)
   const lines = []
 
   /** One bullet: scope, text, a link to the commit, and any issues it closes. */
@@ -741,8 +773,9 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
   const breaking = parsed.filter((c) => c.breaking)
   if (breaking.length) {
     lines.push('### ⚠ BREAKING CHANGES', '')
-    // The footer explains the break; the subject only says what changed.
-    for (const c of breaking) lines.push(bullet(c, c.breakingNote ?? c.subject))
+    // The footer explains the break; the subject only says what changed. A `Notes:`
+    // trailer beats both: it is the author's wording written for exactly this list.
+    for (const c of breaking) lines.push(bullet(c, c.notes ?? c.breakingNote ?? c.subject))
     lines.push('')
   }
 
@@ -764,7 +797,7 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
     )
     if (!inSection.length) continue
     lines.push(`### ${section}`, '')
-    for (const c of inSection) lines.push(bullet(c, c.subject))
+    for (const c of inSection) lines.push(bullet(c, c.notes ?? c.subject))
     lines.push('')
   }
 
@@ -776,7 +809,7 @@ function changelogFromCommits(commits, links = null, hidden = [], contributors =
   )
   if (other.length) {
     lines.push('### Other Changes', '')
-    for (const c of other) lines.push(bullet(c, c.subject))
+    for (const c of other) lines.push(bullet(c, c.notes ?? c.subject))
     lines.push('')
   }
 
@@ -1062,13 +1095,41 @@ function linkCitedCommits(notes, commits, links) {
   })
 }
 
+/**
+ * The marker a drafting model puts on an entry it is not sure of — whether the change is
+ * user-facing, or what it means for someone upgrading. The alternative is a confident guess
+ * published as fact; a flagged entry is a question for the human cutting the release.
+ */
+const UNSURE = '[???]'
+
+/**
+ * Drafted entries the model flagged as unsure, as the lines it wrote them on. Drafts are
+ * validated, not trusted: like an invented commit hash, a flagged entry must not reach a
+ * tag, a changelog or a release page without someone having looked at it.
+ *
+ * @returns {string[]}
+ */
+function uncertainEntries(notes) {
+  return (notes ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.includes(UNSURE))
+}
+
+/** The notes with the marker removed, once a human has reviewed the flagged entries. */
+const withoutUnsureMarkers = (notes) => notes.replaceAll(`${UNSURE} `, '').replaceAll(UNSURE, '')
+
 /**
  * Draft release notes from the commit log.
  *
  * @returns {string | null} markdown body (no version heading), or null
  */
 function draftReleaseNotes(version, commits, lastTag, links) {
-  if (!commits.length) return null
+  // `Notes: no-notes` is the author saying this commit is not news; the model never sees it.
+  const listed = commits
+    .map((c) => ({ ...c, trailer: notesTrailer(c.body) }))
+    .filter((c) => !c.trailer.excluded)
+  if (!listed.length) return null
 
   const prompt = [
     `Write release notes for version ${version}.`,
@@ -1080,20 +1141,31 @@ function draftReleaseNotes(version, commits, lastTag, links) {
     '- End every bullet with the short hashes it covers, in parentheses: `(abc1234)` or',
     '  `(abc1234, def5678)` when merged. Copy them exactly from the list below and invent',
     '  nothing — a hash that is not in the list will be removed.',
-    '- Omit internal chores: CI, linting, formatting, dependency bumps, version bumps.',
+    '- Omit internal chores: CI, linting, formatting, version bumps and dependency bumps —',
+    '  except a component that ships inside the product (a bundled runtime, a sidecar',
+    '  binary, an embedded engine or database). Users run that code, so its update is a',
+    '  user-visible change: name the component and the version it moved to.',
+    '- For bug fixes, describe what works now, not what was broken.',
+    '- If you cannot tell whether a change is user-facing, or what it means for someone',
+    `  upgrading, start that bullet with ${UNSURE} — a person will resolve it. Do not guess.`,
+    "- A commit with a `Notes:` line carries its author's wording for the entry: use that",
+    '  text as written, changing it only to fit the heading or to merge it with related work.',
     '- Write for someone upgrading: say what changed for them, not which files moved.',
     '- Plain, factual language. No hype, no emoji, no concluding summary.',
     '- Output only the markdown body: no version heading, no code fences, no attribution.',
     '- Do NOT explain your reasoning or add any commentary before or after the notes.',
     '',
     `Commits since ${lastTag ?? 'the start of the project'}:`,
-    ...commits.map((c) => `- ${(c.hash ?? '').slice(0, 7)} ${c.subject}`),
+    ...listed.flatMap((c) => [
+      `- ${(c.hash ?? '').slice(0, 7)} ${c.subject}`,
+      ...(c.trailer.text ? [`  Notes: ${c.trailer.text}`] : []),
+    ]),
   ].join('\n')
 
   const drafted = runAssistant(prompt)
   if (!drafted) return null
   const cleaned = cleanNotes(drafted)
-  return cleaned ? linkCitedCommits(cleaned, commits, links) : null
+  return cleaned ? linkCitedCommits(cleaned, listed, links) : null
 }
 
 /** One-line rendering of an argv, so a multi-line arg (release notes) stays readable. */
@@ -1352,7 +1424,7 @@ function distTagFor(version, explicitTag) {
   throw new Error(
     `prerelease identifier "${label}" maps to no known dist-tag ` +
       `(${[...KNOWN_CHANNELS].sort().join(', ')}). Publishing it as "latest" would ` +
-      `clobber the stable line — pass --tag <dist-tag> to choose one explicitly.`,
+      `clobber the stable line — pass --dist-tag <name> to choose one explicitly.`,
   )
 }
 
@@ -1392,6 +1464,32 @@ function changelogOutOfOrder(text) {
   return versions.filter((v, i) => i > 0 && compareVersions(versions[i - 1], v) < 0)
 }
 
+/**
+ * The release candidates of a stable version that the changelog has sections for: for
+ * `2.0.0`, the `2.0.0-rc.1` and `2.0.0-beta.3` headings.
+ *
+ * A stable release reads history from the last stable tag and generates its notes from
+ * those commits, so wording someone edited into a candidate's section does not carry over.
+ * The sections stay in the file; this is how the release notices they exist.
+ *
+ * @returns {string[]} the candidate versions, in file order
+ */
+function candidateSections(text, version) {
+  const base = parseVersion(version)
+  if (!base || base.pre.length) return []
+  return [...text.matchAll(/^## \[?v?(\d+\.\d+\.\d+-[\w.]+)\]?/gm)]
+    .map((m) => m[1])
+    .filter((v) => {
+      const parsed = parseVersion(v)
+      return (
+        parsed &&
+        parsed.major === base.major &&
+        parsed.minor === base.minor &&
+        parsed.patch === base.patch
+      )
+    })
+}
+
 /** The `## ` heading offsets in a changelog, in file order. */
 const sectionOffsets = (text) => [...text.matchAll(/^## .*$/gm)].map((m) => m.index)
 
@@ -1421,9 +1519,13 @@ function insertChangelogSection(text, version, date, body) {
   }
   // Falling out of the loop means every version section is newer, so the release belongs
   // at the foot. With nothing to compare against it belongs at the head instead: appending
-  // to a date-headed changelog would file the release below its oldest entry.
-  if (!comparable && offsets.length) {
-    return `${text.slice(0, offsets[0])}${entry}\n${text.slice(offsets[0])}`
+  // to a date-headed changelog would file the release below its oldest entry. The head is
+  // below [Unreleased], though, which stays the first section — a first release drafted into
+  // a changelog holding only an empty [Unreleased] used to land above it.
+  if (!comparable) {
+    const unreleased = /^## \[?Unreleased\]?/i
+    const first = offsets.find((offset) => !unreleased.test(text.slice(offset)))
+    if (first !== undefined) return `${text.slice(0, first)}${entry}\n${text.slice(first)}`
   }
   const trimmed = text.trimEnd()
   return `${trimmed}\n\n${entry}`
@@ -1607,6 +1709,53 @@ function expandPaths(pattern) {
   return current
 }
 
+/**
+ * crates.io's default ceiling on an uploaded `.crate`, in bytes: `10 * 1024 * 1024` in
+ * crates.io's src/config/publish_limits.rs. The registry can raise it for one crate on
+ * request, but a crate over it is otherwise refused at upload — after the tag and the push.
+ */
+const CRATES_IO_MAX_BYTES = 10 * 1024 * 1024
+
+/**
+ * The `cargo package` argv that builds exactly what a `cargo publish` command would upload,
+ * so preflight can find a missing file or an oversized archive before anything is tagged.
+ *
+ * Deriving it from the publish command rather than guessing keeps the selection the same:
+ * `-p`, `--workspace`, `--manifest-path`, `--features` and `--no-verify` mean the same thing
+ * to both subcommands, so a workspace packages each crate it will publish. Only the flags
+ * `cargo package` does not take are dropped (`--dry-run`, `--token`).
+ *
+ * `--locked` is added when the repository has a `Cargo.lock`: publishing verifies against
+ * it, and a stale one is a failure better found now. Without a lockfile it would refuse
+ * outright, and plenty of libraries do not commit one. `--allow-dirty` is added only when
+ * the tree is dirty — preflight reports that on its own, or the commit step is about to
+ * make it clean — so the package check still says something useful.
+ *
+ * A command that is not a plain `cargo publish …` (a pipeline, quoting, an env prefix) is
+ * not taken apart: there is no reliable way to know what it uploads.
+ *
+ * @returns {string[] | null} args for `cargo`, or null when it cannot be derived
+ */
+function cargoPackageArgs(command, { dirty = false, lockfile = false } = {}) {
+  if (!/^cargo\s+publish(?:\s|$)/.test(command.trim()) || /[;&|<>`$()'"\\]/.test(command)) {
+    return null
+  }
+  const words = command.trim().split(/\s+/).slice(2)
+  const args = ['package']
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i]
+    if (word === '--dry-run' || word === '-n' || word.startsWith('--token=')) continue
+    if (word === '--token') {
+      i += 1
+      continue
+    }
+    args.push(word)
+  }
+  if (lockfile && !args.includes('--locked')) args.push('--locked')
+  if (dirty && !args.includes('--allow-dirty')) args.push('--allow-dirty')
+  return args
+}
+
 /**
  * The crates in a Cargo workspace whose version this bump owns: the members that inherit
  * it with `version.workspace = true`, which is how a workspace keeps its crates in step.
@@ -1672,7 +1821,18 @@ function patternFor({ path, pattern, all = false }) {
 /** @returns {string | null} the version recorded in a source file */
 function readVersionFrom(entry) {
   const source = versionSource(entry)
-  const text = readFileSync(source.path, 'utf8')
+  return versionInText(source, readFileSync(source.path, 'utf8'))
+}
+
+/**
+ * The version a source file's text carries, resolved the same way it will be written.
+ *
+ * Split from `readVersionFrom` so the text can come from somewhere other than the working
+ * tree — `git show HEAD:<path>` — and still be read by the resolver the write uses.
+ *
+ * @returns {string | null}
+ */
+function versionInText(source, text) {
   const { kind, shape } = versionMode(source, text)
   if (kind === 'bare') return text.trim() || null
   if (kind === 'markers') {
@@ -1895,7 +2055,11 @@ if (flag('--help') || flag('-h')) {
 
 // --sync copies this file into other projects and exits; it touches no git state.
 if (flag('--sync')) {
-  const self = new URL(import.meta.url).pathname
+  // A URL's pathname is percent-encoded and keeps the leading slash before a Windows
+  // drive letter, so a script installed under a directory with a space in its name — or
+  // anywhere on Windows — was reported as "piped from stdin". fileURLToPath is the
+  // inverse of what Node did to build import.meta.url.
+  const self = fileURLToPath(import.meta.url)
   // Piped from stdin (`curl … | node -`) there is no file to copy: import.meta.url points
   // at a synthetic [eval] path. Say so instead of failing on a missing file.
   if (!existsSync(self)) {
@@ -2022,6 +2186,9 @@ const VALUE_OPTIONS = new Set([
   '--assistant-effort',
 ])
 
+/** Flags that take no value. With VALUE_OPTIONS, the whole vocabulary this file accepts. */
+const BOOLEAN_FLAGS = new Set(['--dry-run', '--yes', '-y', '--commit', '--help', '-h', '--sync'])
+
 /** The version or bump target: the only argument that is neither a flag nor a flag's value. */
 const positionals = []
 for (let i = 0; i < argv.length; i += 1) {
@@ -2029,7 +2196,20 @@ for (let i = 0; i < argv.length; i += 1) {
     i += 1
     continue
   }
-  if (!argv[i].startsWith('-')) positionals.push(argv[i])
+  if (!argv[i].startsWith('-')) {
+    positionals.push(argv[i])
+    continue
+  }
+  // An unknown flag used to be dropped without a word, and `--auto` is the one people
+  // reach for: it released whatever version package.json already carried, which is a
+  // different release from the `auto` they asked for.
+  if (!BOOLEAN_FLAGS.has(argv[i])) {
+    const bare = argv[i].replace(/^-+/, '')
+    const hint = BUMPS.has(bare)
+      ? `\n  The target is positional: ${INVOCATION} ${bare}, not ${argv[i]}`
+      : ''
+    abort(`unknown flag: ${argv[i]}${hint}`)
+  }
 }
 const target = positionals[0]
 // A second positional is always a mistake, and silently ignoring it changes the release
@@ -2131,6 +2311,10 @@ const ECOSYSTEM_MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml']
  */
 function detectCompanionFiles(primaryPath, primaryVersion) {
   const companions = []
+  // The lockfile pins the crate's own version, so a bump leaves it stale — whether
+  // Cargo.toml is the version source or a manifest kept in step with one. A plain crate was
+  // the case missed: `cargo publish` then refused the dirty lockfile, after the push.
+  if (primaryPath === 'Cargo.toml' && existsSync('Cargo.lock')) companions.push('Cargo.lock')
   for (const candidate of ECOSYSTEM_MANIFESTS) {
     if (candidate === primaryPath || !existsSync(candidate)) continue
     const found = readVersionFrom({ path: candidate })
@@ -2552,6 +2736,23 @@ let autoBump = null
 /** The tag of a previous release this run is finishing rather than starting. */
 let resuming = null
 
+/**
+ * A release tagged at HEAD that never reached the registry, found while resolving a
+ * relative bump. `auto` finishes such a release; a `patch`/`minor`/`major` cannot — it
+ * would bump past it, tag a second version on the same commit, and leave the first one
+ * unpublished for good. Preflight refuses it and names the command that finishes it.
+ */
+let unfinishedAtHead = null
+
+/**
+ * A release that died after the tag and before the publish is finished by re-running the
+ * same command — but only while nothing new has happened. A commit or a working tree that
+ * `--commit` is about to turn into one moves HEAD past the tag, and publishing then would
+ * ship a tree the tag does not describe; that work belongs in the next version, which is
+ * what the shipped-tag baseline makes sure it is released as.
+ */
+const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
+
 let version
 if (!target) {
   if (!currentVersion) {
@@ -2568,12 +2769,6 @@ if (!target) {
         'from.\n  Pass the first version explicitly: release-kit 0.1.0',
     )
   }
-  // A release that died after the tag and before the publish is finished by re-running the
-  // same command — but only while nothing new has happened. A commit or a working tree that
-  // `--commit` is about to turn into one moves HEAD past the tag, and publishing then would
-  // ship a tree the tag does not describe; that work belongs in the next version, which is
-  // what the baseline below makes sure it is released as.
-  const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
   const pending = wouldCommitMore ? null : unfinishedRelease()
   if (pending) {
     ;({ name: resuming, version } = pending)
@@ -2611,6 +2806,10 @@ if (!target) {
       `a ${target} bump from a stable version needs --preid <${[...KNOWN_CHANNELS].sort().join('|')}>`,
     )
   }
+  // The same question `auto` asks, with the opposite answer: `auto` finishes the release
+  // it finds at HEAD, a named bump would skip past it. Recorded here, refused in preflight
+  // with the rest.
+  unfinishedAtHead = wouldCommitMore ? null : unfinishedRelease()
   version = incrementVersion(currentVersion, target, preid)
 } else if (parseVersion(target)) {
   version = target
@@ -2749,6 +2948,33 @@ if (resuming) {
   ok(`finishing ${resuming}: it was tagged and pushed, but never reached the registry`)
 }
 
+if (unfinishedAtHead) {
+  fail(
+    `${unfinishedAtHead.name} is tagged at HEAD but never reached the registry, and a ` +
+      `${target} bump would release ${version} from the same commit and leave it that way.\n` +
+      `       Finish it instead: re-run with no target, or with auto.`,
+  )
+}
+
+// A run that wrote the version and died before its release commit — a failing lockfile
+// refresh, an afterVersion hook, a commit hook — leaves the bump on disk and nowhere
+// else. The current version is then read from that file, and a relative bump counts from
+// it: `minor` after a dead `minor` released 1.2.0 with 1.1.0 tagged nowhere, its changelog
+// section documenting a version that never existed. Only a bump is affected; an explicit
+// version, or none, releases what is on disk and the commit step carries it.
+if (target && BUMPS.has(target) && versionFile && currentVersion) {
+  const committed = tryRead('git', ['show', `HEAD:${versionFile.path}`])
+  const headVersion = committed === null ? null : versionInText(versionFile, committed)
+  if (headVersion && headVersion !== currentVersion) {
+    fail(
+      `${versionFile.path} says ${currentVersion} on disk but ${headVersion} at HEAD — an ` +
+        `uncommitted version bump, which a ${target} bump would count from and skip past.\n` +
+        `       Finish it with \`${INVOCATION} ${currentVersion}\`, or restore the file: ` +
+        `git restore ${versionFile.path}`,
+    )
+  }
+}
+
 // A previous release that never shipped is not history — its commits are still owed to
 // whoever installs this package, and they are in this release's range because of it. Say
 // so: the changelog keeps the section that was written for that version, and a section
@@ -2756,7 +2982,9 @@ if (resuming) {
 const absorbed = absorbedReleaseTags({ stable: !isPrerelease }).filter(
   (entry) => entry.version !== version,
 )
-if (absorbed.length) {
+// Not when the run is being refused for exactly this: saying the commits ship in a
+// version that will not be released contradicts the failure above it.
+if (absorbed.length && !unfinishedAtHead) {
   const names = absorbed.map((entry) => entry.name).join(', ')
   const many = absorbed.length > 1
   const existingChangelog =
@@ -2789,13 +3017,57 @@ if (bumping) {
     }
     if (source.optional) continue
     const text = readFileSync(source.path, 'utf8')
-    const { kind, shape } = versionMode(source, text)
+    // Resolving the mode can itself refuse — a Cargo.lock with nothing beside it to say
+    // which crate is yours — and the write step must not be where that is discovered.
+    let mode
+    try {
+      mode = versionMode(source, text)
+    } catch (err) {
+      fail(err.message)
+      continue
+    }
+    const { kind, shape } = mode
     if (kind === 'pattern' && !shape.test(text)) {
       fail(
         `${source.path} has no version for release-kit to replace.\n` +
           '       Remove it from versionFiles, mark the line with x-release-kit-version, ' +
           'or give the entry a "pattern".',
       )
+    } else if (kind === 'bare' && text.trim() && !parseVersion(text.trim())) {
+      // The whole-file mode is right for a VERSION file and catastrophic for anything
+      // else. `writeVersionInto` refuses it too, but by then the files before it in the
+      // list have already changed.
+      fail(
+        `${source.path} is not a file containing only a version, and carries no ` +
+          'x-release-kit-version marker.\n       Writing the version into it would replace ' +
+          'everything else in it. Mark the line that holds the version, or give the entry ' +
+          'a "pattern".',
+      )
+    }
+  }
+}
+
+// A configured list is never extended, so a Cargo.toml written without the Cargo.lock beside
+// it leaves the lockfile on the old version. Publishing is where that breaks: `cargo publish`
+// refuses a dirty tree, after the tag and the push. Say so before either.
+if (bumping && publishTargets.some((target) => target.cli === 'cargo')) {
+  const written = new Set(versionTargets.map((source) => source.path))
+  for (const source of versionTargets) {
+    if (basename(source.path) !== 'Cargo.toml') continue
+    const lockPath = join(dirname(source.path), 'Cargo.lock')
+    if (written.has(lockPath) || !existsSync(lockPath)) continue
+    let recorded = null
+    try {
+      recorded = readVersionFrom({ path: lockPath })
+    } catch {
+      // A lockfile with nothing beside it to scope by: not this check's question.
+    }
+    if (recorded && recorded !== version) {
+      fail(
+        `${lockPath} records ${readNameFrom(source) ?? 'the crate'} ${recorded}, and nothing ` +
+          `will bump it — \`cargo publish\` would refuse the stale lockfile after the push.\n` +
+          `       Add "${lockPath}" to versionFiles in release.config.json.`,
+      )
     }
   }
 }
@@ -2807,6 +3079,17 @@ if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0)
 } else if (bumping) {
   // No manifest and no tag to read a version from, but files to write one into.
   ok(`writing ${version} into ${versionTargets.map((source) => source.path).join(', ')}`)
+} else if (versionTargets.length && version !== currentVersion) {
+  // The version step is off and the target is not what the files say. The tag would name
+  // one version and the manifest — which is what `npm publish` sends and what the build
+  // compiles in — another. There is no release in which those two are allowed to differ.
+  const files = versionTargets.map((source) => source.path).join(', ')
+  fail(
+    `the version step is not selected, but ${version} is not the version in ${files}` +
+      `${currentVersion ? ` (${currentVersion})` : ''}.\n` +
+      '       The tag would say one version and the files another. Add "version" to the ' +
+      'steps, or release the version already there.',
+  )
 } else if (versionFile) {
   ok(`releasing the version already in ${versionFile.path} (${version})`)
 } else {
@@ -2899,6 +3182,123 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   }
 }
 
+/**
+ * Check run conclusions that mean the commit is not fit to release. `stale` is GitHub giving
+ * up on a run that never finished, which is not a pass either.
+ */
+const RED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'action_required', 'stale'])
+
+/**
+ * Whether GitHub reports the commit being released as green — the gate `requireGreen` opts
+ * into, so a release cannot be cut from a commit CI failed on or has not finished with.
+ *
+ * Both of GitHub's check systems are read. Check runs are what Actions and GitHub Apps
+ * report; commit statuses are the older API that external CI (Buildkite, Jenkins, older
+ * integrations) still posts to. Reading only one would call a commit green while the other
+ * system has it red. The combined status's own `state` is not used: it says `pending` for a
+ * commit with no statuses at all, so the individual statuses are what count.
+ *
+ * Only `success` counts as a pass. `neutral` and `skipped` are not failures, but a commit
+ * whose every check was skipped has not been verified by anything, and zero checks is the
+ * same answer — both are refused rather than read as green.
+ *
+ * When this runs inside GitHub Actions, the job running it is itself an unfinished check run
+ * on the same commit — the `workflow_run` recipe in the README releases exactly the commit
+ * it runs on — and waiting for it would wait forever. Check runs belonging to the current
+ * workflow run are therefore skipped; jobs in the same workflow are what `needs:` orders.
+ *
+ * `{owner}/{repo}` is filled in by gh from the checkout, the same way `gh release create`
+ * resolves the repository the release step publishes to.
+ */
+function checkHeadIsGreen(sha) {
+  const api = (path, jq) => tryRead('gh', ['api', '--paginate', path, '--jq', jq])
+  const checkRuns = api(
+    `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
+    '.check_runs[] | [.name, .status, (.conclusion // ""), (.details_url // "")] | @tsv',
+  )
+  const statuses = api(
+    `repos/{owner}/{repo}/commits/${sha}/status?per_page=100`,
+    '.statuses[] | [.context, .state] | @tsv',
+  )
+  if (checkRuns === null || statuses === null) {
+    fail(`requireGreen: could not read the checks on ${sha.slice(0, 8)} from GitHub (gh api)`)
+    return
+  }
+  const ownRun =
+    process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_RUN_ID
+      ? `/actions/runs/${process.env.GITHUB_RUN_ID}/`
+      : null
+  const rows = (text) =>
+    text
+      .split('\n')
+      .filter((line) => line.trim())
+      .map((line) => line.split('\t'))
+
+  const red = []
+  const waiting = []
+  let passed = 0
+  for (const [name, status, conclusion, url = ''] of rows(checkRuns)) {
+    if (ownRun && url.includes(ownRun)) continue
+    if (status !== 'completed') waiting.push(`${name} (${status})`)
+    else if (RED_CONCLUSIONS.has(conclusion)) red.push(`${name} (${conclusion})`)
+    else if (conclusion === 'success') passed += 1
+  }
+  for (const [context, state] of rows(statuses)) {
+    if (state === 'failure' || state === 'error') red.push(`${context} (${state})`)
+    else if (state === 'pending') waiting.push(`${context} (pending)`)
+    else if (state === 'success') passed += 1
+  }
+
+  const at = `HEAD (${sha.slice(0, 8)})`
+  if (red.length) {
+    fail(`requireGreen: ${at} is not green — ${red.join(', ')}`)
+  } else if (waiting.length) {
+    fail(
+      `requireGreen: checks on ${at} have not finished — ${waiting.join(', ')}.\n` +
+        '       Wait for them to complete, then re-run.',
+    )
+  } else if (!passed) {
+    fail(
+      `requireGreen: no check has passed on ${at} — nothing has verified it.\n` +
+        '       Push it and wait for CI, or turn requireGreen off for a repository without CI.',
+    )
+  } else {
+    ok(`${at} is green (${passed} check${passed === 1 ? '' : 's'} passed)`)
+  }
+}
+
+// Opt-in: the commit being released has to be one CI has seen and passed. That means it is
+// on the remote — a local commit has no checks to read — and that what the commit step is
+// about to add is not part of the release, since CI never saw that either.
+if (config.requireGreen) {
+  const upstream = branch && !detached ? `${config.remote}/${branch}` : null
+  const sha = tryRead('git', ['rev-parse', 'HEAD'])
+  const onRemote =
+    upstream && succeeds('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`])
+  const ahead = onRemote ? tryRead('git', ['rev-list', '--count', `${upstream}..HEAD`]) : null
+  if (dirty && runs('commit')) {
+    fail(
+      'requireGreen: the working tree would be committed and released without CI having ' +
+        'run on it.\n       Commit and push it, wait for the checks, then release.',
+    )
+  }
+  if (!succeeds('gh', ['--version']) || !succeeds('gh', ['auth', 'status'])) {
+    fail('requireGreen reads the checks with `gh`, which is not installed or not authenticated')
+  } else if (!onRemote) {
+    fail(
+      `requireGreen: ${upstream ?? 'this branch'} does not exist on ${config.remote}, so no ` +
+        'check has run on HEAD. Push it and wait for CI.',
+    )
+  } else if (ahead !== '0') {
+    fail(
+      `requireGreen: HEAD is ${ahead ?? 'an unknown number of'} commit(s) ahead of ` +
+        `${upstream}, so CI has not seen it. Push it and wait for the checks.`,
+    )
+  } else if (sha) {
+    checkHeadIsGreen(sha)
+  }
+}
+
 // If the previous release tag is reachable from HEAD, a shallow clone hides nothing the
 // release reads — notes and `auto` see the whole span. No reachable tag means the history
 // is provably truncated: `auto` would infer the bump from a fraction of the commits, so
@@ -3010,10 +3410,40 @@ if (!runs('release')) {
   if (releaseExists) note(`a GitHub release for ${tag} already exists — will skip that step`)
 }
 
+/**
+ * CLIs that publish over OIDC with no token of their own once the CI job can mint one:
+ * npm, pnpm and bun exchange it with the registry themselves, and so does `uv publish`.
+ * cargo does not — crates.io's trusted publishing goes through an action that turns the
+ * OIDC token into a `CARGO_REGISTRY_TOKEN`, so for cargo the token check still stands.
+ */
+const OIDC_CLIS = new Set([...NPM_CLIS, 'uv'])
+
+/**
+ * The oldest npm CLI that publishes over OIDC. An older one finds no token and fails the
+ * publish — after the tag and the push, since nothing before that step asks it anything.
+ * https://docs.npmjs.com/trusted-publishers states the minimum; pnpm and bun implement the
+ * exchange themselves and document no equivalent, so only npm is checked.
+ */
+const NPM_OIDC_MIN = '11.5.1'
+
 /** Whether one publish CLI can publish at all: OIDC, a token, or a live session. */
 function checkCredentials({ cli, registry, command }) {
-  if (isTrustedPublishing) {
+  if (isTrustedPublishing && OIDC_CLIS.has(cli)) {
     ok(`${cli}: trusted publishing (OIDC) — no token needed`)
+    if (cli === 'npm') {
+      const npmVersion = tryRead('npm', ['--version'])
+      if (!npmVersion || !parseVersion(npmVersion)) {
+        warn(
+          `npm: could not read its version — trusted publishing needs npm ${NPM_OIDC_MIN} or later`,
+        )
+      } else if (compareVersions(npmVersion, NPM_OIDC_MIN) < 0) {
+        fail(
+          `npm ${npmVersion} cannot publish with trusted publishing, which needs npm ` +
+            `${NPM_OIDC_MIN} or later — the publish would fail after the tag and push.\n` +
+            '       Update it before releasing: npm install -g npm@latest',
+        )
+      }
+    }
     // Provenance is the other half of what OIDC makes possible: a signed attestation
     // tying the published artefact to the workflow and commit that produced it. It is
     // not added to the command here — npm generates it for a trusted publish on its own,
@@ -3052,6 +3482,75 @@ function checkCredentials({ cli, registry, command }) {
   }
 }
 
+/**
+ * Package what `cargo publish` will upload, before the tag and the push rather than after.
+ *
+ * `cargo publish` packages and verifies as its first act, so a file left out by `include`
+ * or `exclude`, a manifest crates.io rejects, a crate that does not build from its own
+ * archive, or one over the upload limit is discovered only once the release is tagged and
+ * pushed. This runs the same packaging now. It builds the crate, as publishing does, so it
+ * costs a compile.
+ *
+ * It packages the tree as it is — the version is not bumped yet. The version number is the
+ * one thing that differs from what will be uploaded, and it changes neither the file list,
+ * the metadata, nor the size.
+ */
+function checkCratePackage(target) {
+  const args = cargoPackageArgs(target.command, {
+    dirty: !!dirty,
+    lockfile: existsSync('Cargo.lock'),
+  })
+  if (!args) {
+    note(`cargo: \`${target.command}\` is not a plain cargo publish — not packaging it first`)
+    return
+  }
+  const started = Date.now()
+  try {
+    // A verify build prints every crate it compiles; Node's 1 MiB default would overflow.
+    execFileSync('cargo', args, { stdio: 'pipe', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  } catch (err) {
+    const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
+    fail(`\`cargo ${args.join(' ')}\` failed — \`${target.command}\` would too:\n${indent(tail)}`)
+    return
+  }
+  const metadata = tryRead('cargo', ['metadata', '--no-deps', '--format-version', '1'])
+  let targetDir = null
+  try {
+    targetDir = metadata ? JSON.parse(metadata).target_directory : null
+  } catch {
+    targetDir = null
+  }
+  const packageDir = targetDir ? join(targetDir, 'package') : null
+  // Only archives this run wrote: target/package keeps every earlier version too.
+  const crates =
+    packageDir && existsSync(packageDir)
+      ? readdirSync(packageDir)
+          .filter((name) => name.endsWith('.crate'))
+          .map((name) => {
+            const { size, mtimeMs } = statSync(join(packageDir, name))
+            return { name, size, mtimeMs }
+          })
+          .filter(({ mtimeMs }) => mtimeMs >= started - 1000)
+      : []
+  if (!crates.length) {
+    warn('cargo package passed, but no .crate it wrote was found to check against the size limit')
+    return
+  }
+  const limitMb = (CRATES_IO_MAX_BYTES / 1024 / 1024).toFixed(0)
+  for (const { name, size } of crates) {
+    const mb = (size / 1024 / 1024).toFixed(1)
+    if (size > CRATES_IO_MAX_BYTES) {
+      fail(
+        `${name} is ${mb} MiB, over crates.io's ${limitMb} MiB upload limit.\n` +
+          '       Trim it with `include`/`exclude` in Cargo.toml (`cargo package --list` shows ' +
+          'what goes in), or ask crates.io to raise the limit for this crate.',
+      )
+    } else {
+      ok(`cargo package: ${name} (${mb} MiB)`)
+    }
+  }
+}
+
 /** Commands whose version is already on the registry, so the publish step skips them. */
 const alreadyPublished = new Set()
 if (!publishTargets.length) {
@@ -3075,6 +3574,7 @@ if (!publishTargets.length) {
       alreadyPublished.add(target.command)
       note(`${target.name}@${version} is already published — will skip \`${target.command}\``)
     }
+    if (target.cli === 'cargo' && !alreadyPublished.has(target.command)) checkCratePackage(target)
   }
 }
 
@@ -3127,6 +3627,18 @@ const notesDeferred = !!(dirty && runs('commit'))
  */
 let notesPending = false
 
+/**
+ * Entries the assistant flagged as unsure in the notes it drafted — see `uncertainEntries`.
+ * Only a draft can carry them: hand-written and commit-derived notes are someone's words.
+ */
+let unsure = []
+
+/**
+ * Whether a person answers the confirmation prompt. Under --yes, or with no terminal to ask
+ * on, nobody reviews anything before it is tagged and published.
+ */
+const confirming = !assumeYes && !dryRun && !!process.stdin.isTTY
+
 /**
  * Notes for a version, in descending order of how much they can be trusted:
  * an assistant's prose when one is configured, otherwise the commits grouped by
@@ -3167,11 +3679,30 @@ function draftNotesFor(v) {
     )
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
+  const drafted = draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote))
+  unsure = uncertainEntries(drafted)
   return (
-    draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
+    drafted ??
     changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes, contributors)
   )
 }
+
+/**
+ * The flagged entries, listed for whoever has to resolve them. Non-interactively nobody can,
+ * so preflight refuses; at the prompt the person answering is the review.
+ */
+const listUnsure = () => {
+  const one = unsure.length === 1
+  const what = `${unsure.length} drafted entr${one ? 'y' : 'ies'} ${UNSURE}`
+  return `${assistantName} marked ${what} — it could not tell what ${one ? 'it means' : 'they mean'} for users:\n${indent(unsure.join('\n'))}`
+}
+
+/** What to do about flagged entries when nobody is at the prompt to review them. */
+const handWritten = config.changelog
+  ? `, or write the notes into [Unreleased] in ${config.changelog} with them resolved — a hand-written section wins over a draft`
+  : ''
+const UNSURE_FIX = `       Re-run without --yes in a terminal to review them at the prompt${handWritten}.`
+
 const changelogText =
   config.changelog && existsSync(config.changelog) ? readFileSync(config.changelog, 'utf8') : null
 if (changelogText) reportChangelogOrder(changelogText)
@@ -3201,18 +3732,37 @@ if (notesSource === 'github') {
 
   // Generate, either because nothing was written or because a source was named.
   if (!notes) {
+    // Candidates' sections are not a source for the stable release: its notes come from all
+    // the commits since the last stable tag. Say so while there is still time to write the
+    // wording that should survive into [Unreleased] — nothing else would.
+    const candidates =
+      notesSource === 'auto' && changelogText ? candidateSections(changelogText, version) : []
+    if (candidates.length) {
+      warn(
+        `${config.changelog} has sections for ${candidates.join(', ')}, but ${version} ` +
+          'has none of its own, so its notes are generated from every commit since the last ' +
+          'stable release.\n       Anything edited into those sections is not carried over. ' +
+          `To release with it, write the ${version} notes into [Unreleased] and re-run.`,
+      )
+    }
     if (notesDeferred) {
       notesPending = true
       ok(`release notes will be ${assistant ? 'drafted' : 'generated'} after the commit`)
     } else {
       draftedNotes = draftNotesFor(version)
+      if (unsure.length) {
+        if (confirming) warn(`${listUnsure()}\n       They are shown again at the prompt.`)
+        else fail(`${listUnsure()}\n${UNSURE_FIX}`)
+      }
       if (draftedNotes) {
         notes = draftedNotes
-        ok(
-          notesSource === 'commits' || !assistant
-            ? 'release notes built from the commit log'
-            : `release notes drafted by ${assistantName}`,
-        )
+        // An "ok" under the failure above would contradict it: these notes are refused.
+        if (!unsure.length || confirming)
+          ok(
+            notesSource === 'commits' || !assistant
+              ? 'release notes built from the commit log'
+              : `release notes drafted by ${assistantName}`,
+          )
       } else if (notesSource === 'auto') {
         warn(
           `no ${config.changelog ?? 'changelog'} section and nothing to draft from — GitHub will generate the notes`,
@@ -3236,7 +3786,9 @@ for (const asset of config.assets) {
 const wouldCommit = [
   dirty && runs('commit') && 'the working tree',
   bumping && 'a version bump',
-  rolledChangelog && 'a changelog entry',
+  // The roll is computed whenever [Unreleased] is populated, because the notes come from
+  // it either way; it is only written — and only becomes a commit — when the step runs.
+  rolledChangelog && runs('changelog') && 'a changelog entry',
 ].filter(Boolean)
 if (taggedCommit && runs('tag') && wouldCommit.length) {
   fail(
@@ -3252,7 +3804,8 @@ if (taggedCommit && runs('tag') && wouldCommit.length) {
 if (config.verify) {
   note(`running verify: ${config.verify}`)
   try {
-    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8' })
+    // A test suite or a build can print far more than Node's 1 MiB default capture.
+    execSync(config.verify, { stdio: 'pipe', encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
     ok(`verify passed: ${config.verify}`)
   } catch (err) {
     const tail = `${err.stdout ?? ''}${err.stderr ?? ''}`.trim().split('\n').slice(-12).join('\n')
@@ -3298,19 +3851,43 @@ if (dirty && runs('commit') && !dryRun) {
   console.log(indent(commitMessage))
 }
 
-if (!assumeYes && !dryRun && process.stdin.isTTY) {
-  if (notes) console.log(`\n${bold('Release notes')}\n${indent(notes)}`)
+/** Ask a yes/no question on the terminal; anything but yes is no. */
+async function ask(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   let answer = ''
   try {
-    answer = await rl.question(`\nRelease ${bold(tag)} of ${projectName}? [y/N] `)
+    answer = await rl.question(question)
   } catch {
     // Ctrl+C or Ctrl+D at the prompt rejects the question. That is a decline, not a
     // crash — without this it exits on an unhandled AbortError and a stack trace.
   } finally {
     rl.close()
   }
-  if (!/^y(es)?$/i.test(answer.trim())) {
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+/**
+ * Show the notes, with the entries the assistant was unsure of called out, and ask. A yes is
+ * the review those entries were waiting for, so the marker comes off before anything is
+ * written: `[???]` in a tag or on a release page helps nobody.
+ */
+async function confirmRelease(question) {
+  if (notes) console.log(`\n${bold('Release notes')}\n${indent(notes)}`)
+  if (unsure.length) {
+    console.log(`\n${yellow(bold('Review these'))} — ${listUnsure()}`)
+    console.log(dim('  Answering y releases them as shown, without the marker.'))
+  }
+  const yes = await ask(question)
+  if (yes && unsure.length) {
+    notes = withoutUnsureMarkers(notes)
+    if (draftedNotes) draftedNotes = withoutUnsureMarkers(draftedNotes)
+    unsure = []
+  }
+  return yes
+}
+
+if (confirming) {
+  if (!(await confirmRelease(`\nRelease ${bold(tag)} of ${projectName}? [y/N] `))) {
     // Leave the index exactly as it was found.
     if (didStage) mutate('git', ['reset', '--quiet'])
     abort('cancelled')
@@ -3332,6 +3909,18 @@ if (dirty && runs('commit')) {
   if (notesPending && !dryRun) {
     draftedNotes = draftNotesFor(version)
     if (draftedNotes) notes = draftedNotes
+    // These notes were drafted after the prompt, so nobody has seen them. Flagged entries
+    // get the review preflight would have given them; the commit just made stays, and a
+    // re-run drafts from a clean tree — before the prompt, where they can be reviewed.
+    if (unsure.length) {
+      const committed =
+        '       The working tree is committed; nothing else has changed. Re-running drafts the ' +
+        'notes during preflight, before anything else happens.'
+      if (!confirming) abort(`${listUnsure()}\n${UNSURE_FIX}\n${committed}`)
+      if (!(await confirmRelease(`\nRelease ${bold(tag)} with these notes? [y/N] `))) {
+        abort(`cancelled\n${committed}`)
+      }
+    }
   }
 }
 
@@ -3439,15 +4028,37 @@ for (const target of publishTargets) {
 // target published nothing, and telling downstream otherwise is a lie it may act on.
 if (publishedSomething) runHook('afterPublish')
 
+/**
+ * Whether a stable release above this version already exists, anywhere in the
+ * repository — not only in this branch's history, since a patch on an older line is
+ * cut from a branch the newer minor was never merged into.
+ *
+ * GitHub's "Latest" badge is what `releases/latest` resolves to, and `--latest`
+ * forces it. A backport patch that took it would point every "download the latest
+ * release" link at the older line.
+ */
+function supersededByExistingRelease() {
+  const listed = tryRead('git', ['tag', '--list', `${config.tagPrefix}*`]) ?? ''
+  return listed
+    .split('\n')
+    .map((name) => name.trim().slice(config.tagPrefix.length))
+    .filter((v) => parseVersion(v) && !parseVersion(v).pre.length)
+    .some((v) => compareVersions(v, version) > 0)
+}
+
 if (runs('release') && !releaseExists) {
   step(`GitHub release ${tag}`)
+  const latest = !isPrerelease && !supersededByExistingRelease()
+  if (!isPrerelease && !latest) {
+    note(`a newer stable release is already tagged — ${tag} will not be marked Latest`)
+  }
   const args = [
     'release',
     'create',
     tag,
     '--title',
     expand(config.releaseTitle),
-    isPrerelease ? '--prerelease' : '--latest',
+    isPrerelease ? '--prerelease' : `--latest=${latest}`,
     // Notes arrive on stdin, so there is no temp file and nothing to escape.
     ...(notes ? ['--notes-file', '-'] : ['--generate-notes']),
     ...config.assets,