@entro314labs/release-kit 2.8.0 → 2.9.1

package/release.mjs

@@ -24,7 +24,10 @@
  *  - Every step is idempotent. A run interrupted partway through (a publish timeout, a
  *    network failure) can be re-run: an already-written version, an existing tag at HEAD,
  *    an already-published version and an existing release are each detected and skipped.
- *    There is no cleanup step and no --resume flag.
+ *    There is no cleanup step and no --resume flag. `auto` re-run that way finishes the
+ *    unpublished release rather than reporting nothing to do, and once history has moved
+ *    on past it, the version that does ship carries its commits — a tag is not a release,
+ *    and work that never reached a registry is still unreleased.
  *
  * Configuration is optional. Defaults are the conventions (package.json version,
  * CHANGELOG.md, main branch, `v` tag prefix, npm publish); a release.config.json beside
@@ -37,6 +40,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   writeFileSync,
 } from 'node:fs'
@@ -61,9 +65,16 @@ import { createInterface } from 'node:readline/promises'
  *   versionFile     string|object|null  where the project's version lives. Detected from
  *                            the repository when unset; null when it versions by tag alone
  *   versionFiles    array    further files whose version is kept in sync; each is a path
- *                            or { path, pattern }
- *   publish         string   publish command. Detected from the version source when unset,
- *                            and only where it is unambiguous; null to publish nothing
+ *                            or { path, pattern }. Written even where versionFile is null,
+ *                            which is how a language with no version of its own — a Go
+ *                            module — keeps one in source. When neither this nor
+ *                            versionFile is configured, a second root manifest and a
+ *                            conventional version constant already on the same version are
+ *                            detected and kept in step
+ *   publish         string|string[]  publish command, or several for a project that
+ *                            releases to more than one registry. Detected from the version
+ *                            sources when unset, and only where unambiguous; null to
+ *                            publish nothing
  *   commitMessage   string   release commit subject
  *   releaseTitle    string   GitHub release title
  *   assets          string[] files attached to the GitHub release
@@ -91,11 +102,11 @@ import { createInterface } from 'node:readline/promises'
  * committing, is a mistake the tool should not let you express.
  *
  *   commit     commit a dirty working tree (opt-in; touches work that predates the release)
- *   version    write the version into package.json and versionFiles
+ *   version    write the version into the version source and versionFiles
  *   changelog  roll [Unreleased] into the version, or add drafted notes
  *   tag        annotated git tag carrying the release notes
  *   push       push the branch and the tag together
- *   publish    run the configured publish command
+ *   publish    run the configured publish command(s), in order
  *   release    create the GitHub release
  *
  * `version` and `changelog` write files; those writes are persisted by a release commit
@@ -134,8 +145,24 @@ const DEFAULTS = {
     '^(fixup|squash)!',
   ],
   verify: null,
+  hooks: {},
 }
 
+/**
+ * The points a project can hang its own commands on, in the order they run.
+ *
+ * `verify` already covers the one gate that matters most — the project's own tests, run
+ * during preflight before anything mutates. What it cannot express is work that has to
+ * happen *between* the release's own steps: regenerating a file derived from the version,
+ * building an artefact the publish command expects to find, telling something downstream
+ * that a release landed.
+ *
+ * They are command lines rather than callbacks because the config is JSON, and they take
+ * the same `%v` `%t` `%n` `%d` tokens the publish command does. A non-zero exit aborts the
+ * release exactly where it happened, which is the point of running them there.
+ */
+const HOOKS = ['beforeVersion', 'afterVersion', 'beforePublish', 'afterPublish', 'afterRelease']
+
 /**
  * Prerelease identifiers that map to their own npm dist-tag. An identifier outside this
  * set has no safe home, so `distTagFor` refuses rather than letting a prerelease fall
@@ -165,7 +192,11 @@ Target (optional; defaults to the version already in package.json):
 Steps, in the fixed order they run. All but "commit" run by default:
   ${STEPS.join('  ')}
 
-Subcommands (they check or copy, and never start a release):
+Subcommands (they check, print or copy, and never start a release):
+  next [<version>|<bump>]
+                       print the version that target would release, and stop.
+                       Only the version reaches stdout, so it substitutes:
+                       VERSION=$(release-kit next auto)
   lint-commits [<range>]
                        check commit subjects against Conventional Commits
                        (default range: since the last tag)
@@ -210,9 +241,20 @@ const yellow = (s) => paint('33', s)
 
 let stepNumber = 0
 const step = (title) => console.log(`\n${bold(`[${++stepNumber}] ${title}`)}`)
-const ok = (message) => console.log(`  ${green('ok')}   ${message}`)
-const warn = (message) => console.log(`  ${yellow('warn')} ${message}`)
-const note = (message) => console.log(`  ${dim(message)}`)
+/**
+ * `next` exists to be substituted into a shell command, so its stdout must carry the
+ * version and nothing else. Everything the release would narrate still gets said — on
+ * stderr, where a human reads it and `$(...)` does not.
+ */
+const PRINT_ONLY = process.argv[2] === 'next'
+const say = (line) => {
+  if (PRINT_ONLY) process.stderr.write(`${line}\n`)
+  else console.log(line)
+}
+
+const ok = (message) => say(`  ${green('ok')}   ${message}`)
+const warn = (message) => say(`  ${yellow('warn')} ${message}`)
+const note = (message) => say(`  ${dim(message)}`)
 const indent = (text) =>
   text
     .split('\n')
@@ -315,7 +357,28 @@ const ASSISTANTS = {
   },
   codex: {
     command: 'codex',
-    args: ['exec', '--skip-git-repo-check', '--sandbox', 'read-only'],
+    // A draft needs a bare model, but `codex exec` boots the user's whole session by
+    // default — plugins (with their MCP servers, hooks and skills), memories, apps and a
+    // notify program — several thousand tokens of context and seconds of startup that a
+    // one-shot prose prompt never uses. All four features are stable flags; an unknown
+    // flag on some future codex makes the draft fail closed into the deterministic
+    // fallback, which is this tool's contract for every assistant failure.
+    args: [
+      'exec',
+      '--skip-git-repo-check',
+      '--sandbox',
+      'read-only',
+      '--disable',
+      'plugins',
+      '--disable',
+      'hooks',
+      '--disable',
+      'memories',
+      '--disable',
+      'apps',
+      '-c',
+      'notify=[]',
+    ],
     probe: ['--version'],
     model: (m) => ['-m', m],
     effort: (e) => ['-c', `model_reasoning_effort="${e}"`],
@@ -411,29 +474,160 @@ function runAssistant(prompt) {
   }
 }
 
-/** Commit subjects since the last tag, with release and merge commits filtered out. */
-function commitsSinceLastTag() {
+/**
+ * The repository's release tags that are reachable from HEAD, highest version first.
+ *
+ * `git describe --tags --abbrev=0` answers a different question — "the nearest tag of any
+ * kind" — and it is wrong in two ways that were both observed. A repository carrying tags
+ * that are not releases gets one of those as its baseline: a single rolling `latest-beta`
+ * marker, which tauri-release-kit maintains for its update channels, made a release abort
+ * with "no releasable commits since latest-beta". And "nearest ancestor" is not "latest
+ * release": a patch tagged on top of a later minor drags the baseline backwards.
+ *
+ * Only tags carrying the configured prefix and a parseable version count, and they are
+ * ordered by semver precedence rather than by position in the history. `--merged HEAD`
+ * keeps a tag made on another branch out of this branch's history, and degrades correctly
+ * in a shallow clone: a tag whose commit was not fetched is simply not listed.
+ *
+ * @returns {{name: string, version: string}[]}
+ */
+function releaseTags(prefix = config.tagPrefix ?? '') {
+  const listed = tryRead('git', ['tag', '--list', `${prefix}*`, '--merged', 'HEAD']) ?? ''
+  return listed
+    .split('\n')
+    .map((name) => name.trim())
+    .filter(Boolean)
+    .map((name) => ({ name, version: name.slice(prefix.length) }))
+    .filter(({ version }) => parseVersion(version))
+    .sort((a, b) => compareVersions(b.version, a.version))
+}
+
+/**
+ * The tag a release reads its history from.
+ *
+ * @param {{stable?: boolean, shipped?: boolean}} [options] `stable` when the version being
+ *   released has no prerelease identifier, which rolls the release candidates leading to it
+ *   up into it: their work is what is shipping now, and reading from the last candidate
+ *   describes only the gap between the last two candidates. Promoting `2.0.0-rc.2` to
+ *   `2.0.0` that way produced empty notes, because the one commit in range was the release
+ *   chore. Releasing a candidate keeps the full ordering, so each candidate's notes say what
+ *   changed in that candidate rather than repeating the whole cycle.
+ *
+ *   `shipped` skips tags whose version never reached the registry — see
+ *   `absorbedReleaseTags` for why, and `versionShipped` for how that is established.
+ * @returns {string | null}
+ */
+function lastReleaseTag({ stable = false, prefix, shipped = false } = {}) {
+  const tags = releaseTags(prefix)
+  const eligible = stable ? tags.filter(({ version }) => !parseVersion(version).pre.length) : tags
+  if (!shipped) return eligible[0]?.name ?? null
+  for (const tag of eligible) {
+    const state = versionShipped(tag.version)
+    if (state === true) return tag.name
+    // Nothing could answer. Walking further asks the same unanswerable question about older
+    // versions, and treating silence as "never published" would reach back to the first
+    // commit in the repository — so this reads history exactly as it did before.
+    if (state === null) break
+  }
+  // Either the registry went quiet, or no tag this project ever made is on it — a project
+  // that tags and publishes by hand looks exactly like that. Neither is evidence that the
+  // last release failed, so the newest tag stays the baseline.
+  return eligible[0]?.name ?? null
+}
+
+/**
+ * The tags this release is about to absorb: versions that were tagged, pushed and written
+ * into the changelog, and then never published.
+ *
+ * Their commits are still unreleased work — the tag says otherwise, and that is what made
+ * them disappear. `2.0.1` failed to publish, `2.0.2` read its history from the `v2.0.1` tag
+ * and shipped notes covering one commit, and the ten commits `2.0.1` was made of are named
+ * in no release anyone can install. Reading from the last *shipped* tag puts them back in
+ * range, both for the notes and for the bump `auto` infers from them.
+ *
+ * @returns {{name: string, version: string}[]} newest first, empty in the ordinary case
+ */
+function absorbedReleaseTags({ stable = false } = {}) {
+  const tags = releaseTags()
+  const eligible = stable ? tags.filter(({ version }) => !parseVersion(version).pre.length) : tags
+  const baseline = lastReleaseTag({ stable, shipped: true })
+  const absorbed = []
+  for (const tag of eligible) {
+    if (tag.name === baseline) break
+    if (versionShipped(tag.version) !== false) break
+    absorbed.push(tag)
+  }
+  return absorbed
+}
+
+/** Commit subjects since the last release tag, with release and merge commits filtered out. */
+function commitsSinceLastTag(options) {
   const ignored = (config.ignoreCommits ?? []).map((pattern) => new RegExp(pattern, 'i'))
-  const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+  const lastTag = lastReleaseTag(options)
   const range = lastTag ? `${lastTag}..HEAD` : 'HEAD'
   // %B is the whole message: bodies carry BREAKING CHANGE and Release-As footers. A record
   // separator keeps multi-line messages parseable when splitting the log back apart.
-  // %h first, then the message: the hash is what links each bullet back to its commit.
-  const raw = tryRead('git', ['log', `--format=%h%x1f%B%x1e`, range]) ?? ''
+  // %h first, then the author, then the message: the hash is what links each bullet back
+  // to its commit, and the author is what says who is new here.
+  const raw = tryRead('git', ['log', `--format=%h%x1f%an%x1f%ae%x1f%B%x1e`, range]) ?? ''
   const commits = raw
     .split('\u001E')
     .map((entry) => entry.trim())
     .filter(Boolean)
     .map((entry) => {
-      const [hash, message = ''] = entry.split('\u001F')
+      const [hash, author = '', email = '', message = ''] = entry.split('\u001F')
       const [subject, ...rest] = message.split('\n')
-      return { hash: hash.trim(), subject: subject.trim(), body: rest.join('\n').trim() }
+      return {
+        hash: hash.trim(),
+        author: author.trim(),
+        email: email.trim().toLowerCase(),
+        subject: subject.trim(),
+        body: rest.join('\n').trim(),
+      }
     })
     // Bookkeeping rather than change: the previous release's own commit, merges that
     // duplicate the branch they bring in, and markers meant to be autosquashed away.
     .filter(({ subject }) => subject && !ignored.some((re) => re.test(subject)))
   const kept = withoutRevertedCommits(commits)
-  return { lastTag, commits: kept, subjects: kept.map((c) => c.subject) }
+  return {
+    lastTag,
+    commits: kept,
+    subjects: kept.map((c) => c.subject),
+    contributors: newContributors(lastTag, kept),
+  }
+}
+
+/**
+ * The people whose first commit to this repository is in this release.
+ *
+ * git-cliff derives this from the forge's API, which needs a token, a network and a
+ * forge. The repository already knows: an author absent from every commit before the
+ * previous tag has not contributed before. That answer is exact, offline, and the same on
+ * GitHub, GitLab and a bare remote — and it degrades with a shallow clone exactly as the
+ * rest of the notes do, which is already warned about.
+ *
+ * The first release has no "before", so everyone would be new and the section would say
+ * nothing; it is skipped there.
+ *
+ * @returns {string[]} display names, GitHub handles where the email carries one
+ */
+function newContributors(lastTag, commits) {
+  if (!lastTag || !commits.length) return []
+  const before = new Set(
+    (tryRead('git', ['log', '--format=%ae', lastTag]) ?? '')
+      .split('\n')
+      .map((email) => email.trim().toLowerCase())
+      .filter(Boolean),
+  )
+  const seen = new Map()
+  for (const { author, email } of commits) {
+    if (!email || before.has(email) || seen.has(email)) continue
+    // A GitHub noreply address carries the account handle, which is what a reader can
+    // actually follow; anything else falls back to the name on the commit.
+    const handle = /^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$/.exec(email)?.[1]
+    seen.set(email, handle ? `@${handle}` : author)
+  }
+  return [...seen.values()].filter(Boolean)
 }
 
 /**
@@ -528,7 +722,7 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  *
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
-function changelogFromCommits(commits, links = null, hidden = []) {
+function changelogFromCommits(commits, links = null, hidden = [], contributors = []) {
   const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
   const lines = []
 
@@ -577,6 +771,14 @@ function changelogFromCommits(commits, links = null, hidden = []) {
     lines.push('')
   }
 
+  // Last, and only when there is something above it: a list of names is not release notes
+  // on its own, and a release with no described changes should still say so.
+  if (lines.length && contributors.length) {
+    lines.push('### New Contributors', '')
+    for (const name of contributors) lines.push(`- ${name} made their first contribution`)
+    lines.push('')
+  }
+
   return lines.length ? lines.join('\n').trim() : null
 }
 
@@ -586,11 +788,28 @@ function changelogFromCommits(commits, links = null, hidden = []) {
  * differ: Bitbucket uses /issue/ and /commits/ where GitHub uses /issues/ and /commit/.
  */
 const HOSTS = {
-  'github.com': { issue: 'issues', commit: 'commit' },
-  'gitlab.com': { issue: 'issues', commit: 'commit' },
-  'bitbucket.org': { issue: 'issue', commit: 'commits' },
+  'github.com': {
+    issue: 'issues',
+    commit: 'commit',
+    compare: 'compare/%f...%t',
+    tag: 'releases/tag/%t',
+  },
+  'gitlab.com': { issue: 'issues', commit: 'commit', compare: 'compare/%f...%t', tag: '-/tags/%t' },
+  // Bitbucket reverses the operands and separates them with two dots, and keeps tags under
+  // /commits/tag/ rather than a releases page it does not have.
+  'bitbucket.org': {
+    issue: 'issue',
+    commit: 'commits',
+    compare: 'branches/compare/%t..%f',
+    tag: 'commits/tag/%t',
+  },
+}
+const DEFAULT_HOST = {
+  issue: 'issues',
+  commit: 'commit',
+  compare: 'compare/%f...%t',
+  tag: 'releases/tag/%t',
 }
-const DEFAULT_HOST = { issue: 'issues', commit: 'commit' }
 
 /** Words that mark an issue reference as closed by the commit. */
 const CLOSES = /\b(?:close[sd]?|closing|fix(?:e[sd])?|fixing|resolve[sd]?|resolving)\s+#(\d+)/gi
@@ -611,10 +830,13 @@ function remoteLinks(remote) {
   const [, host, path] = web ?? scp ?? []
   if (!host || !path) return null
   const shape = HOSTS[host.toLowerCase()] ?? DEFAULT_HOST
+  const base = `https://${host}/${path}`
   return {
-    base: `https://${host}/${path}`,
-    issue: `https://${host}/${path}/${shape.issue}`,
-    commit: `https://${host}/${path}/${shape.commit}`,
+    base,
+    issue: `${base}/${shape.issue}`,
+    commit: `${base}/${shape.commit}`,
+    compare: (from, to) => `${base}/${shape.compare.replace('%f', from).replace('%t', to)}`,
+    tag: (name) => `${base}/${shape.tag.replace('%t', name)}`,
   }
 }
 
@@ -871,6 +1093,103 @@ function mutate(command, args, options = {}) {
   }
 }
 
+/**
+ * Lockfiles that record the releasing project's own version, and the command that brings
+ * each back into step.
+ *
+ * A lockfile is not rewritten by pattern like a manifest is: `package-lock.json` carries
+ * the version in two places, `uv.lock` carries it inside the `[[package]]` block for the
+ * project among all its dependencies, and both formats change shape between tool versions.
+ * The tool that owns the file is the only thing that can be trusted to edit it, so each
+ * one is refreshed by running that tool.
+ *
+ * `manifest` scopes the refresh: a polyglot repository can hold a `uv.lock` for a Python
+ * component that this release is not versioning, and regenerating it would put an
+ * unrelated change in the release commit.
+ *
+ * pnpm and Cargo are deliberately absent. `pnpm-lock.yaml` records no root version, so it
+ * never goes stale; `Cargo.lock` does, and is already kept in step as a version file with
+ * a pattern scoped to the crate.
+ */
+const LOCKFILES = [
+  {
+    path: 'package-lock.json',
+    manifest: 'package.json',
+    command: ['npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent']],
+  },
+  {
+    path: 'npm-shrinkwrap.json',
+    manifest: 'package.json',
+    command: ['npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent']],
+  },
+  { path: 'uv.lock', manifest: 'pyproject.toml', command: ['uv', ['lock', '--quiet']] },
+]
+
+/**
+ * Bring every lockfile belonging to a manifest this release wrote back into step.
+ *
+ * A missing tool is a warning rather than an abort: the lockfile is left exactly as stale
+ * as it already was, which is the behaviour without this step at all, and no release
+ * should die because a lock tool is not installed on the machine cutting it.
+ *
+ * @param {string[]} written paths the version step wrote
+ */
+function refreshLockfiles(written) {
+  const done = new Set()
+  for (const { path, manifest, command } of LOCKFILES) {
+    if (!existsSync(path) || !written.includes(manifest)) continue
+    const [tool, args] = command
+    // npm writes whichever of the two lockfiles the project has; running it twice is one
+    // pointless install, not two different edits.
+    if (!done.has(tool)) {
+      if (!dryRun && !succeeds(tool, ['--version'])) {
+        warn(`${path} records the version and ${tool} is not installed — leaving it stale`)
+        continue
+      }
+      mutate(tool, args)
+      done.add(tool)
+    }
+    staged.push(path)
+  }
+}
+
+/**
+ * Push the release commit and its tag as one transaction.
+ *
+ * `--follow-tags` and `--atomic` answer different questions: the first decides *which*
+ * refs are sent, the second decides whether they land together. With only the first, a
+ * server is free to accept the branch and reject the tag — which is precisely the split
+ * this step exists to prevent, leaving a release commit on the remote with no tag, or a
+ * tag with no commit behind it.
+ *
+ * Not every server implements the atomic capability, so a refusal on those grounds falls
+ * back to the plain push. Nothing else does: a rejected non-fast-forward retried without
+ * `--atomic` would push one ref and not the other, which is worse than failing.
+ */
+function pushBranchAndTag(branchRef) {
+  const args = ['push', '--follow-tags', config.remote, branchRef]
+  const atomic = ['push', '--follow-tags', '--atomic', config.remote, branchRef]
+  const line = formatCommand('git', atomic)
+  if (dryRun) {
+    console.log(`  ${yellow('would run:')} ${line}`)
+    return
+  }
+  console.log(`  ${dim(`$ ${line}`)}`)
+  try {
+    execFileSync('git', atomic, { stdio: ['pipe', 'inherit', 'pipe'] })
+    return
+  } catch (err) {
+    const stderr = `${err.stderr ?? ''}`
+    process.stderr.write(stderr)
+    if (!/atomic/i.test(stderr)) abortMidRelease(line)
+  }
+  warn(
+    `${config.remote} does not support atomic pushes — sending the branch and tag in one ` +
+      'call, but not as one transaction',
+  )
+  mutate('git', args)
+}
+
 /**
  * Mutating shell command, for configured strings like `publish` that are written as a
  * whole command line rather than an argv. Shell metacharacters are the author's to own.
@@ -1072,6 +1391,65 @@ function insertChangelogSection(text, version, date, body) {
   return `${trimmed}\n\n${entry}`
 }
 
+/**
+ * Write the link reference definitions a Keep a Changelog document's headings depend on.
+ *
+ * `## [1.2.3]` is a markdown link *reference*: without a matching `[1.2.3]: <url>` at the
+ * foot of the file it renders as literal bracketed text. Sections were being written in
+ * that shape and the definitions were never written at all, so every heading in every
+ * changelog this tool has ever rolled is a dead reference.
+ *
+ * Every bracketed heading in the document gets one, not only the version being released,
+ * so a changelog that never had them is repaired in one release rather than from here on.
+ * Each version links to the diff since the version below it; the oldest links to its own
+ * tag, having no predecessor to compare against. `[Unreleased]` compares the newest
+ * version against `HEAD`.
+ *
+ * Definitions for labels that are not headings are left exactly where they are — those are
+ * the author's own links, and this owns only what it can derive.
+ *
+ * @param {ReturnType<typeof remoteLinks>} links
+ * @returns {string} the document with its definitions rewritten
+ */
+function withChangelogLinks(text, links, tagPrefix = '') {
+  if (!links) return text
+  const labels = [...text.matchAll(/^## \[([^\]]+)\]/gm)].map((m) => m[1])
+  if (!labels.length) return text
+
+  const versions = labels
+    .filter((label) => parseVersion(label.replace(/^v/, '')))
+    .sort((a, b) => compareVersions(b.replace(/^v/, ''), a.replace(/^v/, '')))
+  const unreleased = labels.find((label) => /^unreleased$/i.test(label))
+
+  const tagged = (label) => `${tagPrefix}${label.replace(/^v/, '')}`
+  const definitions = []
+  if (unreleased && versions.length) {
+    definitions.push(`[${unreleased}]: ${links.compare(tagged(versions[0]), 'HEAD')}`)
+  }
+  versions.forEach((version, index) => {
+    const previous = versions[index + 1]
+    definitions.push(
+      `[${version}]: ${
+        previous ? links.compare(tagged(previous), tagged(version)) : links.tag(tagged(version))
+      }`,
+    )
+  })
+  if (!definitions.length) return text
+
+  // Drop the existing definitions for the labels being rewritten, wherever they sit, so
+  // running this twice produces the same document rather than a second copy.
+  const managed = new Set([...(unreleased ? [unreleased] : []), ...versions])
+  const body = text
+    .split('\n')
+    .filter((line) => {
+      const label = /^\[([^\]]+)\]:\s/.exec(line)?.[1]
+      return !(label && managed.has(label))
+    })
+    .join('\n')
+
+  return `${body.trimEnd()}\n\n${definitions.join('\n')}\n`
+}
+
 /**
  * Promote `## [Unreleased]` to a released version and reopen an empty one above it.
  *
@@ -1152,6 +1530,73 @@ function readNameFrom(entry) {
 /** Normalise a versionFile / versionFiles entry to { path, pattern }. */
 const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } : entry)
 
+/**
+ * Expand a path that may contain `*` segments into the paths that exist, in sorted order.
+ *
+ * A desktop app carries the same version in a per-platform config for every platform it
+ * ships, and a Cargo workspace lists its members as `crates/*`. Writing those out one by
+ * one is the config the glob replaces. `*` matches within a single path segment, which is
+ * what both of those shapes need and is all Go's `filepath.Glob` — the shape changie's
+ * `replacements` use — offers either.
+ *
+ * @returns {string[]} matching paths; a pattern with no `*` yields itself when it exists
+ */
+function expandPaths(pattern) {
+  if (!pattern.includes('*')) return existsSync(pattern) ? [pattern] : []
+  const absolute = pattern.startsWith('/')
+  let current = [absolute ? '/' : '.']
+  for (const segment of pattern.split('/').filter(Boolean)) {
+    const next = []
+    if (segment.includes('*')) {
+      const shape = new RegExp(`^${segment.split('*').map(escapeRe).join('[^/]*')}$`)
+      for (const dir of current) {
+        let entries
+        try {
+          entries = readdirSync(dir).sort()
+        } catch {
+          continue
+        }
+        for (const entry of entries) if (shape.test(entry)) next.push(join(dir, entry))
+      }
+    } else {
+      for (const dir of current) {
+        const joined = join(dir, segment)
+        if (existsSync(joined)) next.push(joined)
+      }
+    }
+    current = next
+  }
+  return current
+}
+
+/**
+ * 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.
+ *
+ * A member pinning its own number is versioned separately and is left out, the same rule
+ * the companion-manifest detection uses.
+ *
+ * @returns {string[]} crate names
+ */
+function workspaceCrates(manifestPath) {
+  const text = readFileSync(manifestPath, 'utf8')
+  const members = /^members\s*=\s*\[([\s\S]*?)\]/m.exec(text)?.[1]
+  if (!members) return []
+  const root = dirname(manifestPath)
+  const names = []
+  for (const entry of members.matchAll(/"([^"]+)"/g)) {
+    for (const dir of expandPaths(join(root, entry[1]))) {
+      const memberManifest = join(dir, 'Cargo.toml')
+      if (!existsSync(memberManifest)) continue
+      const member = readFileSync(memberManifest, 'utf8')
+      if (!/^version(?:\.workspace)?\s*=\s*\{?\s*workspace\s*=\s*true/m.test(member)) continue
+      const name = NAME_PATTERNS.toml.exec(member)?.[1]
+      if (name) names.push(name)
+    }
+  }
+  return names
+}
+
 /**
  * A lockfile records a version for every dependency — hundreds of them — so the first
  * `version = "…"` in the file belongs to whichever crate sorts first, not to this project.
@@ -1159,21 +1604,27 @@ const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } :
  */
 function cargoLockPattern(lockPath) {
   const sibling = join(dirname(lockPath), 'Cargo.toml')
-  const crate = existsSync(sibling) ? readNameFrom({ path: sibling }) : null
-  if (!crate) {
+  // A workspace root carries no `[package]` of its own; what it owns is every member that
+  // inherits the version with `version.workspace = true`, and the lockfile records a
+  // block for each of them.
+  const crates = existsSync(sibling)
+    ? [...new Set([readNameFrom({ path: sibling }), ...workspaceCrates(sibling)].filter(Boolean))]
+    : []
+  if (!crates.length) {
     throw new Error(
       `${lockPath} lists every dependency's version, so it needs to know which package is ` +
-        `yours.\n  No Cargo.toml beside it to read the name from — give an explicit ` +
-        `pattern:\n  { "path": "${lockPath}", "pattern": "name = \\"<crate>\\"\\nversion = ` +
-        `\\"(.+)\\"" }`,
+        `yours.\n  No Cargo.toml beside it naming a crate or a workspace member that ` +
+        `inherits the version — give an explicit pattern:\n  { "path": "${lockPath}", ` +
+        `"pattern": "name = \\"<crate>\\"\\nversion = \\"(.+)\\"" }`,
     )
   }
-  return new RegExp(`\\[\\[package\\]\\]\\nname = "${escapeRe(crate)}"\\nversion = "([^"]*)"`)
+  const names = crates.map(escapeRe).join('|')
+  return new RegExp(`\\[\\[package\\]\\]\\nname = "(?:${names})"\\nversion = "([^"]*)"`, 'g')
 }
 
 /** The regex for a source, or null when the whole file is the version. */
-function patternFor({ path, pattern }) {
-  if (pattern) return new RegExp(pattern, 'm')
+function patternFor({ path, pattern, all = false }) {
+  if (pattern) return new RegExp(pattern, all ? 'mg' : 'm')
   if (basename(path) === 'Cargo.lock') return cargoLockPattern(path)
   if (path.endsWith('.json')) return VERSION_PATTERNS.json
   if (path.endsWith('.toml')) return VERSION_PATTERNS.toml
@@ -1184,31 +1635,176 @@ function patternFor({ path, pattern }) {
 function readVersionFrom(entry) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
-  const pattern = patternFor(source)
-  if (!pattern) return text.trim() || null
-  const match = pattern.exec(text)
+  const { kind, shape } = versionMode(source, text)
+  if (kind === 'bare') return text.trim() || null
+  if (kind === 'markers') {
+    // The first line under a `version` marker is the one that carries the whole version;
+    // a `major` or `date` marker carries only a piece of it.
+    let scope = null
+    for (const line of text.split('\n')) {
+      const starting = MARKER_START.exec(line)?.[1]
+      if (starting) {
+        scope = starting
+        continue
+      }
+      if (scope && MARKER_END.test(line)) {
+        scope = null
+        continue
+      }
+      const active = MARKER_INLINE.exec(line)?.[1] ?? scope
+      if (active === 'version') {
+        const found = MARKER_VERSION.exec(line)?.[0]
+        if (found) return found
+      }
+    }
+    return null
+  }
+  const match = shape.exec(text)
   return match ? match[1] : null
 }
 
+/**
+ * Version markers: a comment naming the version, put on the line that carries it.
+ *
+ * A `pattern` can already reach any file, but writing one is a regex per file, and the
+ * files that most want keeping in step — a README install line, a badge URL, a Dockerfile
+ * tag, a Helm chart — are exactly the ones where a regex is fiddliest to get right and
+ * easiest to get subtly wrong. release-please solved this with a marker comment on the
+ * line instead, and the convention travels: the file says which of its numbers is the
+ * version, so nothing outside it has to describe where that number sits.
+ *
+ *   npm i acme@1.2.3            <!-- x-release-kit-version -->
+ *   FROM acme:1.2               # x-release-kit-minor
+ *   Released 2026-08-20         <!-- x-release-kit-date -->
+ *
+ * A block form covers a run of lines, for a fenced example that should not carry a comment
+ * on every line:
+ *
+ *   <!-- x-release-kit-start-version -->
+ *   ```sh
+ *   npm i acme@1.2.3
+ *   ```
+ *   <!-- x-release-kit-end -->
+ */
+// `version-date` comes first: the alternation is ordered, and `version` would otherwise
+// match its prefix and leave the date alone.
+const SCOPES = 'version-date|major|minor|patch|version|date'
+const MARKER_INLINE = new RegExp(`x-release-kit-(${SCOPES})\\b`)
+const MARKER_START = new RegExp(`x-release-kit-start-(${SCOPES})\\b`)
+const MARKER_END = /x-release-kit-end\b/
+const MARKER_VERSION = /\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?/i
+const MARKER_NUMBER = /\b\d+\b/
+const MARKER_DATE = /\d{4}-\d{2}-\d{2}/
+
+/** Whether a file opts into marker rewriting at all. */
+const hasVersionMarkers = (text) => MARKER_INLINE.test(text) || MARKER_START.test(text)
+
+/**
+ * Rewrite the marked numbers in a file.
+ *
+ * A marker whose line carries nothing to replace is left alone rather than guessed at: a
+ * heading above a block, or a comment on its own line, is a normal thing to find.
+ *
+ * @returns {string} the rewritten text
+ */
+function applyVersionMarkers(text, version, date) {
+  const { major, minor, patch } = parseVersion(version)
+  const replacements = {
+    version: [MARKER_VERSION, version],
+    major: [MARKER_NUMBER, String(major)],
+    minor: [MARKER_NUMBER, String(minor)],
+    patch: [MARKER_NUMBER, String(patch)],
+    date: [MARKER_DATE, date],
+  }
+  // One line carrying both, which is the shape of an AppStream <release> tag.
+  const versionAndDate = (line) => line.replace(MARKER_VERSION, version).replace(MARKER_DATE, date)
+  let scope = null
+  return text
+    .split('\n')
+    .map((line) => {
+      const inline = MARKER_INLINE.exec(line)?.[1]
+      const starting = MARKER_START.exec(line)?.[1]
+      // A start marker opens a block; its own line is not rewritten, since the marker
+      // comment is the whole content of it.
+      if (starting) {
+        scope = starting
+        return line
+      }
+      if (scope && MARKER_END.test(line)) {
+        scope = null
+        return line
+      }
+      const active = inline ?? scope
+      if (!active) return line
+      if (active === 'version-date') return versionAndDate(line)
+      const [shape, value] = replacements[active]
+      return line.replace(shape, value)
+    })
+    .join('\n')
+}
+
+/**
+ * Where a file keeps its version, most specific first: the `pattern` the entry was
+ * configured with, the markers the file carries, the shape its extension implies, and —
+ * for a plain `VERSION` file — being nothing but the version.
+ *
+ * Reading and writing both go through this, so they can never disagree about which of a
+ * file's numbers is the version.
+ *
+ * @returns {{kind: 'pattern'|'markers'|'bare', shape: RegExp|null}}
+ */
+function versionMode(source, text) {
+  if (source.pattern) return { kind: 'pattern', shape: patternFor(source) }
+  if (hasVersionMarkers(text)) return { kind: 'markers', shape: null }
+  const inferred = patternFor(source)
+  return inferred ? { kind: 'pattern', shape: inferred } : { kind: 'bare', shape: null }
+}
+
 /**
  * Replace the version in a source file, touching nothing else: only the captured range is
  * rewritten, so formatting, key order and comments all survive.
  *
- * @param {{dryRun?: boolean}} [options] report the change without making it
+ * Four ways a file says where its version is, most specific first: the `pattern` it was
+ * configured with, the markers it carries, the shape its extension implies, and — for a
+ * plain `VERSION` file — being nothing but the version.
+ *
+ * @param {{dryRun?: boolean, date?: string}} [options] report the change without making
+ *   it; the date written for a `x-release-kit-date` marker
  * @returns {boolean} whether the file needed changing
  */
-function writeVersionInto(entry, version, { dryRun = false } = {}) {
+function writeVersionInto(entry, version, { dryRun = false, date } = {}) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
-  const pattern = patternFor(source)
+  const { kind, shape } = versionMode(source, text)
 
   let updated
-  if (pattern) {
-    const match = pattern.exec(text)
-    if (!match) throw new Error(`${source.path} has no version matching ${pattern}`)
-    const start = match.index + match[0].indexOf(match[1])
-    updated = text.slice(0, start) + version + text.slice(start + match[1].length)
+  if (kind === 'pattern') {
+    if (!shape.test(text)) {
+      if (source.optional) return false
+      throw new Error(`${source.path} has no version matching ${shape}`)
+    }
+    shape.lastIndex = 0
+    // A global pattern rewrites every match rather than the first: a Cargo.lock records
+    // one block per crate, and a workspace bump owns all the members inheriting from it.
+    updated = text.replace(shape, (match, captured) => {
+      const at = match.indexOf(captured)
+      return match.slice(0, at) + version + match.slice(at + captured.length)
+    })
+  } else if (kind === 'markers') {
+    updated = applyVersionMarkers(text, version, date ?? new Date().toISOString().slice(0, 10))
   } else {
+    // The last resort overwrites the file with the version, which is right for a VERSION
+    // file and catastrophic for anything else. A file that is not already just a version
+    // was listed by mistake, or wants a marker or a pattern — say so rather than shred it.
+    const existing = text.trim()
+    if (existing && !parseVersion(existing)) {
+      throw new Error(
+        `${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".',
+      )
+    }
     updated = `${version}\n`
   }
 
@@ -1221,7 +1817,9 @@ function writeVersionInto(entry, version, { dryRun = false } = {}) {
 // ARGUMENTS
 // ─────────────────────────────────────────────────────────────────────────────
 
-const argv = process.argv.slice(2)
+// `next` is a modifier on the ordinary target resolution, not a mode of its own: it takes
+// the same target argument and stops once the version is known.
+const argv = process.argv.slice(PRINT_ONLY ? 3 : 2)
 const BUMPS = new Set([
   'auto',
   'major',
@@ -1313,9 +1911,9 @@ if (flag('--sync')) {
 if (argv[0] === 'lint-commits') {
   const rest = argv.slice(1)
   const subjectAt = rest.indexOf('--subject')
-  const ignored = { ...DEFAULTS, ...readUserConfig() }.ignoreCommits.map(
-    (pattern) => new RegExp(pattern, 'i'),
-  )
+  // This subcommand runs before `config` is bound, so it resolves its own.
+  const lintConfig = { ...DEFAULTS, ...readUserConfig() }
+  const ignored = lintConfig.ignoreCommits.map((pattern) => new RegExp(pattern, 'i'))
 
   let subjects
   let scope
@@ -1328,7 +1926,7 @@ if (argv[0] === 'lint-commits') {
     scope = null
   } else {
     if (!tryRead('git', ['rev-parse', '--show-toplevel'])) abort('not inside a git repository')
-    const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+    const lastTag = lastReleaseTag({ prefix: lintConfig.tagPrefix ?? '' })
     const range =
       rest.find((arg) => !arg.startsWith('-')) ?? (lastTag ? `${lastTag}..HEAD` : 'HEAD')
     // Merges carry no prose of their own, and %s is enough: nothing here reads the body.
@@ -1434,6 +2032,14 @@ const userConfig = readUserConfig()
 const config = { ...DEFAULTS, ...userConfig }
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
+// A misspelled hook name is a hook that silently never runs, which is the failure mode
+// this file refuses everywhere else it takes a name.
+const unknownHooks = Object.keys(config.hooks ?? {}).filter((key) => !HOOKS.includes(key))
+if (unknownHooks.length) {
+  abort(
+    `release.config.json has unknown hooks: ${unknownHooks.join(', ')}\n  Known: ${HOOKS.join(', ')}`,
+  )
+}
 
 /**
  * Which steps run: config provides the baseline, --only replaces it, --skip subtracts, and
@@ -1455,17 +2061,94 @@ const parseStepList = (value) =>
 const manifest = existsSync('package.json') ? readJson('package.json') : null
 
 /**
- * Where this project keeps its version, when the config does not say. Checked in order of
- * how definitively each file identifies a repository. `go.mod` resolves to null because Go
- * modules carry no version — the tag is the version.
+ * Files that identify a repository, most definitive first. The first one present is where
+ * the version is read from and written to. `go.mod` is absent because Go modules carry no
+ * version — the tag is the version.
  */
+const MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml', 'VERSION']
+
+/** Where this project keeps its version, when the config does not say. */
 function detectVersionFile() {
-  for (const candidate of ['package.json', 'pyproject.toml', 'Cargo.toml', 'VERSION']) {
-    if (existsSync(candidate)) return candidate
-  }
+  for (const candidate of MANIFESTS) if (existsSync(candidate)) return candidate
   return null
 }
 
+/**
+ * Manifests that name an ecosystem, so a second one present means a second registry. A
+ * bare VERSION file is deliberately not one: it names nothing, and a repository keeping an
+ * unrelated VERSION beside its manifest should not be told the two disagree.
+ */
+const ECOSYSTEM_MANIFESTS = ['package.json', 'pyproject.toml', 'Cargo.toml']
+
+/**
+ * Some repositories release one source tree to two ecosystems at once — a Tauri plugin is
+ * a crate and an npm package, a maturin project is a crate and a wheel — and carry the
+ * version in both manifests. Those bump together with no config.
+ *
+ * The safety rule is that they must already agree. Two manifests on different versions are
+ * two independent version lines, and dragging one to the other's number is a silent, wrong
+ * release; say so and touch nothing instead.
+ *
+ * @returns {string[]} further files to keep in step with the primary version source
+ */
+function detectCompanionFiles(primaryPath, primaryVersion) {
+  const companions = []
+  for (const candidate of ECOSYSTEM_MANIFESTS) {
+    if (candidate === primaryPath || !existsSync(candidate)) continue
+    const found = readVersionFrom({ path: candidate })
+    if (found !== primaryVersion) {
+      warn(
+        `${candidate} is at ${found ?? 'no readable version'} while ${primaryPath} is at ` +
+          `${primaryVersion}, so they are versioned separately — leaving ${candidate} alone.\n` +
+          '       Add it to "versionFiles" in release.config.json to bump them together.',
+      )
+      continue
+    }
+    companions.push(candidate)
+    // The lockfile pins the crate's own version too, so a bump leaves it stale.
+    if (candidate === 'Cargo.toml' && existsSync('Cargo.lock')) companions.push('Cargo.lock')
+  }
+  return companions
+}
+
+/**
+ * Where a language records no version of its own, a project that wants `--version` to work
+ * keeps one in source instead: a Go module has only `go.mod`, which carries no version at
+ * all, so the number lives in a `version.go` the tag is supposed to match.
+ *
+ * These mirror the tag rather than define it — `go get` resolves a tag, not a constant —
+ * so they are detected as files to keep in step, never as the source of truth.
+ *
+ * A candidate is adopted only when it already carries the current version, the same rule
+ * the companion manifests use. Here it does a second job: it rules out the `var Version =
+ * "dev"` placeholder that a build replaces with -ldflags, which is not a version to bump
+ * and is common enough that warning about it every release would be pure noise. Mismatches
+ * are therefore skipped silently, unlike a manifest on its own version line.
+ *
+ * Anything outside this table is three lines of `versionFiles` config with a `pattern`;
+ * this covers the convention that comes up without one.
+ */
+const VERSION_MIRRORS = [
+  {
+    // `const Version = "1.2.0"`, `var Version = "1.2.0"`, and the same inside a const
+    // block or with an explicit `string` type.
+    pattern: '^\\s*(?:const\\s+|var\\s+)?[Vv]ersion\\s*(?:string\\s*)?=\\s*"(.+)"',
+    paths: ['version.go', 'internal/version/version.go', 'pkg/version/version.go'],
+  },
+]
+
+/** @returns {{path: string, pattern: string}[]} source files already carrying `version` */
+function detectVersionMirrors(version) {
+  const found = []
+  for (const { paths, pattern } of VERSION_MIRRORS) {
+    for (const path of paths) {
+      if (!existsSync(path)) continue
+      if (readVersionFrom({ path, pattern }) === version) found.push({ path, pattern })
+    }
+  }
+  return found
+}
+
 /**
  * The publish command implied by a project's manifest, but only where one ecosystem
  * obviously owns it. Python has several publishers (uv, twine, poetry, flit) and Go has
@@ -1477,6 +2160,26 @@ const PUBLISH_BY_MANIFEST = {
   'Cargo.toml': 'cargo publish',
 }
 
+/**
+ * A manifest that must not be published says so in itself. Detection honours that: a
+ * private package or an unpublishable crate is one this repository releases by tag alone,
+ * and detecting a command for it would attempt the one thing the manifest forbids.
+ */
+function detectablePublish(path) {
+  if (basename(path) === 'package.json') return !readJson(path).private
+  if (basename(path) === 'Cargo.toml') {
+    const text = readFileSync(path, 'utf8')
+    if (/^publish\s*=\s*false/m.test(text)) return false
+    // A crate built only as a cdylib is a native extension module — what maturin and
+    // napi-rs compile into a wheel or a .node — not a library anyone depends on from
+    // crates.io. Its version travels with the package it is built into, which is why the
+    // two match; publishing it to crates.io is the one thing nobody asked for.
+    const crateTypes = /^crate-type\s*=\s*\[([^\]]*)\]/m.exec(text)?.[1]
+    if (crateTypes?.includes('cdylib') && !crateTypes.includes('rlib')) return false
+  }
+  return true
+}
+
 // An explicit `versionFile: null` means "versions by tag" and must not be re-detected, so
 // the distinction is between the key being absent and the key being set to null.
 const configuredVersionFile = Object.hasOwn(userConfig, 'versionFile')
@@ -1502,11 +2205,7 @@ if (versionFile && !existsSync(versionFile.path)) {
  * the version has to be typed out in full every time.
  */
 function versionFromLastTag() {
-  const tag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
-  if (!tag) return null
-  const bare =
-    config.tagPrefix && tag.startsWith(config.tagPrefix) ? tag.slice(config.tagPrefix.length) : tag
-  return parseVersion(bare) ? bare : null
+  return releaseTags()[0]?.version ?? null
 }
 
 const currentVersion = versionFile ? readVersionFrom(versionFile) : versionFromLastTag()
@@ -1524,13 +2223,73 @@ const goModule = existsSync('go.mod')
 const projectName =
   manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
 
+/**
+ * Manifests found beside the primary one that carry the same version. Detected only when
+ * the project has said nothing about either key: a project that listed its own
+ * `versionFiles` has already answered this question, and quietly appending to that answer
+ * would release files it deliberately left out.
+ */
+const detecting =
+  !!currentVersion &&
+  !Object.hasOwn(userConfig, 'versionFile') &&
+  !Object.hasOwn(userConfig, 'versionFiles')
+const companionFiles = detecting
+  ? [
+      ...(versionFile ? detectCompanionFiles(versionFile.path, currentVersion) : []),
+      ...detectVersionMirrors(currentVersion),
+    ]
+  : []
+if (companionFiles.length) {
+  config.versionFiles = companionFiles
+  note(
+    `also versioned in ${companionFiles.map((entry) => versionSource(entry).path).join(', ')} ` +
+      '(detected)',
+  )
+}
+
+/**
+ * Every file the version is written into: the source of truth first, then the files kept
+ * in step with it. A repository that versions by tag alone has no source of truth here and
+ * may still have mirrors to write — a Go module's `version.go` is exactly that — so this
+ * is what the version step works from, rather than `versionFile` being required.
+ */
+/**
+ * Every file the version is written into, with `*` in a `versionFiles` path expanded to
+ * the files it matches.
+ *
+ * A pattern matching nothing is an error rather than a quiet skip: it was written to keep
+ * files in step, and silently keeping none of them in step is the failure it was meant to
+ * prevent. `versionFile` is never globbed — the source of truth is one file, and a glob
+ * that resolved to two would make which one wins an accident of directory order.
+ */
+const versionTargets = [
+  ...(versionFile ? [versionSource(versionFile)] : []),
+  ...config.versionFiles.map(versionSource).flatMap((source) => {
+    if (!source.path.includes('*')) return [source]
+    const matched = expandPaths(source.path)
+    if (!matched.length) abort(`versionFiles pattern ${source.path} matched no files`)
+    // A glob says "every file of this shape", and some of them legitimately carry no
+    // version — a Tauri per-OS overlay holds only the keys it overrides. Being unable to
+    // write one is expected here, unlike a path someone named on purpose.
+    return matched.map((path) => Object.assign({}, source, { path, optional: true }))
+  }),
+]
+
 // Same rule as versionFile: an explicit `publish: null` means "publish nothing" and is
 // never re-detected. Unset means "work it out", and working it out can yield nothing.
 if (!Object.hasOwn(userConfig, 'publish')) {
   // Preflight already reports "no publish command configured" when the step runs, so
   // there is nothing to say here — and `runs` is not resolved this early.
-  config.publish =
-    (versionFile ? PUBLISH_BY_MANIFEST[basename(versionFile.path)] : undefined) ?? null
+  //
+  // Two manifests releasing in step means two registries: the npm command comes first
+  // because it is the recoverable one — npm allows an unpublish for 72 hours, crates.io
+  // never does — so a half-finished publish leaves the undoable half undone.
+  const detected = [versionFile, ...companionFiles]
+    .filter(Boolean)
+    .map((entry) => versionSource(entry).path)
+    .filter((path) => PUBLISH_BY_MANIFEST[basename(path)] && detectablePublish(path))
+    .map((path) => PUBLISH_BY_MANIFEST[basename(path)])
+  config.publish = detected.length ? detected : null
 }
 
 // Validate every name that was asked for, not just the ones that survive: a typo in
@@ -1550,6 +2309,20 @@ if (skippedSteps) for (const name of parseStepList(skippedSteps)) steps.delete(n
 if (autoCommit) steps.add('commit')
 const runs = (name) => steps.has(name)
 
+/**
+ * True when the commit step is off because a config `steps` list omits it — as opposed to
+ * being switched off for this run with --skip or --only. Configs written before `commit`
+ * became a default step omit it without ever having chosen to, so a dirty-tree refusal
+ * caused by one deserves a hint that the flag-driven refusal does not: the flag user just
+ * asked for exactly this.
+ */
+const commitExcludedByConfig =
+  !runs('commit') &&
+  !onlySteps &&
+  !(skippedSteps && parseStepList(skippedSteps).includes('commit')) &&
+  Array.isArray(config.steps) &&
+  !config.steps.includes('commit')
+
 /**
  * The drafting tool, resolved from --assistant then config. "auto" picks the first one
  * present on PATH; a named tool must be known and installed, otherwise it is an error
@@ -1585,11 +2358,152 @@ if (assistantChoice !== 'none' && assistantChoice !== null) {
 }
 const assistant = assistantName ? ASSISTANTS[assistantName] : null
 
+/**
+ * Registries whose preflight can be run, keyed by the first word of the publish command.
+ * Each declares how that CLI answers "who am I", "does this version already exist" and
+ * "is this package there at all"; any may be null when the tool has no such notion. A
+ * publish command outside this table (vsce, a shell pipeline) is run as written with no
+ * preflight — it cannot be introspected, and guessing would invent failures.
+ *
+ * `exists` is what separates "that version was never published" from "the registry did not
+ * answer". Both make the version lookup exit non-zero, and only the first one means the
+ * release is unfinished — see `versionShipped`.
+ */
+const REGISTRIES = {
+  npm: {
+    whoami: ['whoami'],
+    published: (name, v) => ['view', `${name}@${v}`, 'version'],
+    exists: (name) => ['view', name, 'version'],
+  },
+  pnpm: {
+    whoami: ['whoami'],
+    published: (name, v) => ['view', `${name}@${v}`, 'version'],
+    exists: (name) => ['view', name, 'version'],
+  },
+  bun: {
+    whoami: ['pm', 'whoami'],
+    published: (name, v) => ['pm', 'view', `${name}@${v}`, 'version'],
+    exists: (name) => ['pm', 'view', name, 'version'],
+  },
+  // uv authenticates with a token from the environment rather than a logged-in session,
+  // and skips duplicate uploads itself via --check-url, so there is no version lookup.
+  uv: { env: ['UV_PUBLISH_TOKEN', 'UV_PUBLISH_PASSWORD'], login: 'set UV_PUBLISH_TOKEN' },
+  // cargo has no "who am I": crates.io auth is a token, either in the environment or in
+  // the credentials file `cargo login` writes. `cargo info` is the version lookup, and
+  // exits non-zero for a version the index does not carry (cargo 1.82+).
+  cargo: {
+    env: ['CARGO_REGISTRY_TOKEN', 'CARGO_REGISTRIES_CRATES_IO_TOKEN'],
+    credentials: [
+      join(homedir(), '.cargo', 'credentials.toml'),
+      join(homedir(), '.cargo', 'credentials'),
+    ],
+    login: 'run `cargo login`, or set CARGO_REGISTRY_TOKEN',
+    published: (name, v) => ['info', `${name}@${v}`],
+    exists: (name) => ['info', name],
+  },
+  // For Go the tag is the release; `go list` warms the module proxy and doubles as the
+  // check for whether this version is already resolvable.
+  go: {
+    published: (name, v) => ['list', '-m', `${name}@${v}`],
+    exists: (name) => ['list', '-m', `${name}@latest`],
+  },
+}
+
+/**
+ * Which manifest records the name a registry knows this project by, when it is not the one
+ * `projectName` came from. They are not always the same string: a Tauri plugin publishes as
+ * `@tauri-apps/plugin-x` on npm and `tauri-plugin-x` on crates.io, so looking the crate up
+ * under its npm name would report every version as unpublished.
+ */
+const NAME_MANIFEST_BY_CLI = { cargo: 'Cargo.toml' }
+
+function registryName(cli) {
+  const manifest = NAME_MANIFEST_BY_CLI[cli]
+  if (!manifest) return projectName
+  const source = versionTargets.find((entry) => basename(entry.path) === manifest)
+  return (source && readNameFrom(source)) ?? projectName
+}
+
+/**
+ * `publish` is one command or several, because one source tree can own a package in more
+ * than one ecosystem. They run in the configured order.
+ */
+const publishList = config.publish == null ? [] : [config.publish].flat()
+if (publishList.some((entry) => typeof entry !== 'string')) {
+  abort('publish must be a command string, an array of command strings, or null')
+}
+
+/**
+ * One answer per version, per run: the lookups are network calls, and the same version is
+ * asked about by the baseline walk and again by preflight.
+ */
+const shippedCache = new Map()
+
+/**
+ * Whether a version actually reached every registry this project publishes to.
+ *
+ * A tag is not a release. The tag and the push happen before the publish, so a publish that
+ * fails — a failing prepublish gate, an expired npm session, a network drop — leaves the
+ * version tagged, pushed and changelogged but absent from the registry. Nothing downstream
+ * has it, and until this could be asked, nothing upstream knew.
+ *
+ * "Not there" and "could not ask" are the same exit code from every one of these CLIs, and
+ * conflating them is dangerous in one direction only: reading an unreachable registry as
+ * "nothing was ever published" would drag the notes baseline back through the whole
+ * history. The bare-name lookup separates them — a package whose own name resolves is a
+ * registry that answered.
+ *
+ * @param {string} v
+ * @returns {boolean | null} null when nothing here can answer
+ */
+function versionShipped(v) {
+  if (shippedCache.has(v)) return shippedCache.get(v)
+  let answer = null
+  for (const template of publishList) {
+    const cli = template.trim().split(/\s+/)[0]
+    const registry = REGISTRIES[cli]
+    if (!registry?.published || !registry.exists) continue
+    const name = registryName(cli)
+    if (succeeds(cli, registry.published(name, v))) {
+      answer ??= true
+      continue
+    }
+    // One registry missing the version is enough: the release did not finish everywhere,
+    // and the half that is missing is the half still owed to its consumers.
+    if (succeeds(cli, registry.exists(name))) {
+      answer = false
+      break
+    }
+    answer = null
+    break
+  }
+  shippedCache.set(v, answer)
+  return answer
+}
+
+/**
+ * The release that was started and never finished: the newest tag, sitting at HEAD, whose
+ * version never reached the registry.
+ *
+ * Re-running the same command is the documented way to recover from a release that died
+ * partway through, and `auto` was the one target that could not: it resolves a version from
+ * the commits since the last tag, finds none, and aborts with "nothing to release" — while
+ * the thing left to do is the publish the previous run never got to.
+ *
+ * @returns {{name: string, version: string} | null}
+ */
+function unfinishedRelease() {
+  const [newest] = releaseTags()
+  if (!newest || versionShipped(newest.version) !== false) return null
+  const at = tryRead('git', ['rev-list', '-n', '1', newest.name])
+  return at && at === tryRead('git', ['rev-parse', 'HEAD']) ? newest : null
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // RESOLVE THE TARGET VERSION
 // ─────────────────────────────────────────────────────────────────────────────
 
-console.log(
+say(
   bold(`${projectName} release`) +
     (dryRun ? `  ${yellow('(dry run — nothing will execute)')}` : ''),
 )
@@ -1597,6 +2511,9 @@ console.log(
 /** What `auto` inferred, kept so preflight can show the reasoning. */
 let autoBump = null
 
+/** The tag of a previous release this run is finishing rather than starting. */
+let resuming = null
+
 let version
 if (!target) {
   if (!currentVersion) {
@@ -1613,24 +2530,35 @@ if (!target) {
         'from.\n  Pass the first version explicitly: release-kit 0.1.0',
     )
   }
-  const { commits, lastTag } = commitsSinceLastTag()
-  if (!commits.length) {
-    abort(
-      `no releasable commits since ${lastTag ?? 'the start of the project'} — nothing to release`,
-    )
-  }
-  autoBump = inferBump(commits, currentVersion, config.versioning)
-  if (autoBump.releaseAs) {
-    if (!parseVersion(autoBump.releaseAs)) {
-      abort(`Release-As: ${autoBump.releaseAs} in a commit is not a semver version`)
-    }
-    version = autoBump.releaseAs
+  // 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)
   } else {
-    version = incrementVersion(
-      currentVersion,
-      autoBump.bump,
-      requestedPreid ?? preidOf(currentVersion),
-    )
+    const { commits, lastTag } = commitsSinceLastTag({ shipped: true })
+    if (!commits.length) {
+      abort(
+        `no releasable commits since ${lastTag ?? 'the start of the project'} — nothing to release`,
+      )
+    }
+    autoBump = inferBump(commits, currentVersion, config.versioning)
+    if (autoBump.releaseAs) {
+      if (!parseVersion(autoBump.releaseAs)) {
+        abort(`Release-As: ${autoBump.releaseAs} in a commit is not a semver version`)
+      }
+      version = autoBump.releaseAs
+    } else {
+      version = incrementVersion(
+        currentVersion,
+        autoBump.bump,
+        requestedPreid ?? preidOf(currentVersion),
+      )
+    }
   }
 } else if (BUMPS.has(target)) {
   if (!currentVersion) {
@@ -1653,8 +2581,13 @@ if (!target) {
 }
 
 const tag = `${config.tagPrefix}${version}`
+if (PRINT_ONLY) {
+  console.log(version)
+  process.exit(0)
+}
+
 const isPrerelease = parseVersion(version).pre.length > 0
-const bumping = !!versionFile && version !== currentVersion && runs('version')
+const bumping = versionTargets.length > 0 && version !== currentVersion && runs('version')
 
 let distTag
 try {
@@ -1681,32 +2614,55 @@ const expand = (template) => expandWith(template, (value) => value)
 const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`
 const expandShell = (template) => expandWith(template, shellQuote)
 
-const publishCommand = runs('publish') && config.publish ? expandShell(config.publish) : null
+/**
+ * Run a lifecycle hook, if the project configured one.
+ *
+ * Anything a hook leaves modified is staged for the release commit. Preflight has already
+ * established that the tree was clean (or that the `commit` step is committing all of it),
+ * so a file that is dirty now was produced by this release and belongs in it — which is
+ * what makes `afterVersion` useful for regenerating a file derived from the version.
+ *
+ * @param {string} name one of HOOKS
+ */
+function runHook(name) {
+  const configured = config.hooks?.[name]
+  if (!configured) return
+  const commands = Array.isArray(configured) ? configured : [configured]
+  step(`Hook ${name}`)
+  for (const command of commands) mutateShell(expandShell(command))
+  if (dryRun) return
+  for (const path of dirtyPaths()) if (!staged.includes(path)) staged.push(path)
+}
 
 /**
- * Registries whose preflight can be run, keyed by the first word of the publish command.
- * Each declares how that CLI answers "who am I" and "does this version already exist";
- * either may be null when the tool has no such notion. A publish command outside this
- * table (vsce, a shell pipeline) is run as written with no preflight — it cannot be
- * introspected, and guessing would invent failures.
+ * Paths git reports as changed, whatever the change is.
+ *
+ * The status column cannot be sliced at a fixed offset: the capture is trimmed, which
+ * strips the leading space off the first entry only, so ` M file` arrives as `M file`
+ * while the rest keep theirs. Split on the gap after the code instead.
  */
-const REGISTRIES = {
-  npm: { whoami: ['whoami'], published: (name, v) => ['view', `${name}@${v}`, 'version'] },
-  pnpm: { whoami: ['whoami'], published: (name, v) => ['view', `${name}@${v}`, 'version'] },
-  bun: {
-    whoami: ['pm', 'whoami'],
-    published: (name, v) => ['pm', 'view', `${name}@${v}`, 'version'],
-  },
-  // uv authenticates with a token from the environment rather than a logged-in session,
-  // and skips duplicate uploads itself via --check-url, so there is no version lookup.
-  uv: { env: ['UV_PUBLISH_TOKEN', 'UV_PUBLISH_PASSWORD'], login: 'set UV_PUBLISH_TOKEN' },
-  // For Go the tag is the release; `go list` warms the module proxy and doubles as the
-  // check for whether this version is already resolvable.
-  go: { published: (name, v) => ['list', '-m', `${name}@${v}`] },
+function dirtyPaths() {
+  return (
+    (tryRead('git', ['status', '--porcelain']) ?? '')
+      .split('\n')
+      .map((line) => /^\s*\S{1,2}\s+(.+)$/.exec(line)?.[1]?.trim())
+      .filter(Boolean)
+      // A rename reads as "old -> new"; the new path is the one to stage.
+      .map((path) => path.split(' -> ').at(-1))
+  )
 }
 
-const publishCli = publishCommand?.trim().split(/\s+/)[0]
-const registry = publishCli ? REGISTRIES[publishCli] : null
+/** Each publish command with the CLI it drives, that CLI's preflight row, and its name. */
+const publishTargets = runs('publish')
+  ? publishList.map((template) => {
+      const command = expandShell(template)
+      const cli = command.trim().split(/\s+/)[0]
+      return { command, cli, registry: REGISTRIES[cli] ?? null, name: registryName(cli) }
+    })
+  : []
+
+/** npm-family commands are the ones a `"private": true` package.json forbids. */
+const NPM_CLIS = new Set(['npm', 'pnpm', 'bun'])
 
 /**
  * CI publishing over OIDC ("trusted publishing") carries no token at all: `whoami` fails
@@ -1751,10 +2707,68 @@ if (autoBump) {
   }
 }
 
-if (bumping && compareVersions(version, currentVersion) <= 0) {
+if (resuming) {
+  ok(`finishing ${resuming}: it was tagged and pushed, but never reached the registry`)
+}
+
+// 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
+// naming a version no registry carries is worth a human deciding about.
+const absorbed = absorbedReleaseTags({ stable: !isPrerelease }).filter(
+  (entry) => entry.version !== version,
+)
+if (absorbed.length) {
+  const names = absorbed.map((entry) => entry.name).join(', ')
+  const many = absorbed.length > 1
+  const existingChangelog =
+    config.changelog && existsSync(config.changelog) ? readFileSync(config.changelog, 'utf8') : null
+  const documented = absorbed
+    .filter((entry) => existingChangelog && changelogSection(existingChangelog, entry.version))
+    .map((entry) => entry.version)
+  const stale = documented.length
+    ? `\n       ${config.changelog} still documents ${documented.join(', ')} — ${
+        documented.length > 1 ? 'versions' : 'a version'
+      } no registry carries. Fold ${
+        documented.length > 1 ? 'those sections' : 'that section'
+      } into ${version} by hand.`
+    : ''
+  warn(
+    `${names} ${many ? 'were' : 'was'} tagged but never published, so ${version} ships ${
+      many ? 'their' : 'its'
+    } commits as well as its own.${stale}`,
+  )
+}
+
+// Writing the version is the first mutating step, and it used to discover a file it
+// could not write *while writing the others* — aborting with a raw stack trace after
+// some of them had already changed. Every target is checked here instead.
+if (bumping) {
+  for (const source of versionTargets) {
+    if (!existsSync(source.path)) {
+      fail(`versionFiles entry ${source.path} does not exist`)
+      continue
+    }
+    if (source.optional) continue
+    const text = readFileSync(source.path, 'utf8')
+    const { kind, shape } = versionMode(source, text)
+    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".',
+      )
+    }
+  }
+}
+
+if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0) {
   fail(`${version} is not greater than the current version ${currentVersion}`)
-} else if (bumping) {
+} else if (bumping && currentVersion) {
   ok(`version ${currentVersion} → ${version}`)
+} 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 (versionFile) {
   ok(`releasing the version already in ${versionFile.path} (${version})`)
 } else {
@@ -1789,7 +2803,12 @@ else if (dirty && runs('commit')) {
     )
   }
 } else if (dirty) {
-  fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
+  const hint = commitExcludedByConfig
+    ? '\n       The steps list in release.config.json omits `commit` (it may predate ' +
+      'commit becoming\n       a default step). Add "commit" to it, or pass --commit ' +
+      'to commit these now.'
+    : ''
+  fail(`working tree is not clean:\n${indent(formatStatus(dirty))}${hint}`)
 } else ok('working tree clean')
 
 if (assistant) {
@@ -1848,7 +2867,7 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
 // that is a failure; commit-derived notes merely come out partial, so that is a warning.
 let shallowHidesHistory = false
 if (shallow) {
-  const reachableTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
+  const reachableTag = lastReleaseTag()
   shallowHidesHistory = !reachableTag
   if (reachableTag) {
     ok(
@@ -1953,37 +2972,70 @@ if (!runs('release')) {
   if (releaseExists) note(`a GitHub release for ${tag} already exists — will skip that step`)
 }
 
-let alreadyPublished = false
-if (!publishCommand) {
-  note(runs('publish') ? 'no publish command configured' : 'publish step not selected')
-} else if (manifest?.private) {
-  fail('package.json is private but a publish command is configured')
-} else if (!registry) {
-  ok(`publish: ${publishCommand}`)
-} else {
+/** Whether one publish CLI can publish at all: OIDC, a token, or a live session. */
+function checkCredentials({ cli, registry, command }) {
   if (isTrustedPublishing) {
-    ok('trusted publishing (OIDC) — no token needed')
-  } else if (registry.env) {
-    // Token-in-the-environment auth: there is no session to interrogate, only credentials.
+    ok(`${cli}: trusted publishing (OIDC) — no token needed`)
+    // 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,
+    // and forcing the flag fails outright for a private package or a registry that
+    // cannot receive one. Saying so is what turns "available" into "used".
+    if (NPM_CLIS.has(cli) && !/--provenance\b/.test(command ?? '')) {
+      note(
+        `${cli}: OIDC also allows a signed provenance attestation — add --provenance to ` +
+          'the publish command if the registry accepts one and the package is public',
+      )
+    }
+    return
+  }
+  if (registry.env) {
+    // Token auth: there is no session to interrogate, only credentials to find.
     const found = registry.env.find((name) => process.env[name])
-    if (found) ok(`${publishCli} credentials found (${found})`)
-    else fail(`${publishCli} has no publish credentials — ${registry.login}`)
-  } else if (registry.whoami) {
-    const user = tryRead(publishCli, registry.whoami)
+    if (found) {
+      ok(`${cli} credentials found (${found})`)
+      return
+    }
+    const file = registry.credentials?.find((path) => existsSync(path))
+    if (file) ok(`${cli} credentials found (${file})`)
+    else fail(`${cli} has no publish credentials — ${registry.login}`)
+    return
+  }
+  if (registry.whoami) {
+    const user = tryRead(cli, registry.whoami)
     if (user === null) {
       // npm replaced long-lived tokens with two-hour sessions in December 2025, so the
       // usual cause is an expired session rather than a missing login.
       fail(
-        `${publishCli} is not authenticated — run \`${publishCli} login\`. ` +
+        `${cli} is not authenticated — run \`${cli} login\`. ` +
           'npm logins are two-hour sessions, so an earlier one may have expired.',
       )
-    } else ok(`${publishCli} authenticated (${user || 'unknown user'})`)
+    } else ok(`${cli} authenticated (${user || 'unknown user'})`)
   }
+}
 
-  if (registry.published) {
-    alreadyPublished = succeeds(publishCli, registry.published(projectName, version))
-    if (alreadyPublished) {
-      note(`${projectName}@${version} is already published — will skip the publish step`)
+/** Commands whose version is already on the registry, so the publish step skips them. */
+const alreadyPublished = new Set()
+if (!publishTargets.length) {
+  note(runs('publish') ? 'no publish command configured' : 'publish step not selected')
+} else if (manifest?.private && publishTargets.some((target) => NPM_CLIS.has(target.cli))) {
+  fail('package.json is private but an npm publish command is configured')
+} else {
+  // One CLI can appear more than once; interrogating it twice says the same thing twice.
+  const authenticated = new Set()
+  for (const target of publishTargets) {
+    ok(`publish: ${target.command}`)
+    if (!target.registry) continue
+    if (!authenticated.has(target.cli)) {
+      authenticated.add(target.cli)
+      checkCredentials(target)
+    }
+    if (
+      target.registry.published &&
+      succeeds(target.cli, target.registry.published(target.name, version))
+    ) {
+      alreadyPublished.add(target.command)
+      note(`${target.name}@${version} is already published — will skip \`${target.command}\``)
     }
   }
 }
@@ -2027,13 +3079,29 @@ let draftedNotes = null
  */
 const notesDeferred = !!(dirty && runs('commit'))
 
+/**
+ * Set only when preflight found nothing to release with and left the drafting to the
+ * post-commit step. Deferral has to be recorded rather than re-derived from `notesDeferred`
+ * there: a dirty tree is what makes drafting possible to defer, not what makes it necessary.
+ * A hand-written changelog section has already answered the question, and re-drafting over
+ * it would discard the notes the confirmation prompt showed and append a second section for
+ * the same version.
+ */
+let notesPending = false
+
 /**
  * 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
  * Conventional Commit type. Only when neither yields anything does GitHub generate them.
  */
 function draftNotesFor(v) {
-  const { lastTag, subjects, commits } = commitsSinceLastTag()
+  // A stable release absorbs the candidates that led to it: their commits are what it
+  // ships, and reading from the last candidate leaves the notes describing the gap
+  // between two candidates rather than the release.
+  const { lastTag, subjects, commits, contributors } = commitsSinceLastTag({
+    stable: !isPrerelease,
+    shipped: true,
+  })
   if (!commits.length) return null
 
   // Notes are built from Conventional Commits, so anything not written that way is simply
@@ -2048,7 +3116,12 @@ function draftNotesFor(v) {
   }
   // An explicitly named source wins over the assistant being merely available.
   if (!assistant || notesSource === 'commits')
-    return changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
+    return changelogFromCommits(
+      commits,
+      remoteLinks(config.remote),
+      config.hiddenTypes,
+      contributors,
+    )
   if (shallowHidesHistory) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
@@ -2058,7 +3131,7 @@ function draftNotesFor(v) {
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return (
     draftReleaseNotes(v, commits, lastTag, remoteLinks(config.remote)) ??
-    changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes)
+    changelogFromCommits(commits, remoteLinks(config.remote), config.hiddenTypes, contributors)
   )
 }
 const changelogText =
@@ -2091,6 +3164,7 @@ if (notesSource === 'github') {
   // Generate, either because nothing was written or because a source was named.
   if (!notes) {
     if (notesDeferred) {
+      notesPending = true
       ok(`release notes will be ${assistant ? 'drafted' : 'generated'} after the commit`)
     } else {
       draftedNotes = draftNotesFor(version)
@@ -2119,13 +3193,19 @@ for (const asset of config.assets) {
 
 // Reusing a tag is the resume path, and a resume writes nothing. If this run would still
 // produce a commit, that commit moves HEAD past the tag and the release ends up tagged at
-// the wrong revision — which is silent until someone checks out the tag.
-if (taggedCommit && runs('tag') && (bumping || rolledChangelog)) {
+// the wrong revision — which is silent until someone checks out the tag, and worse for the
+// working tree: `publish` sends what is on disk now, not what the tag describes.
+const wouldCommit = [
+  dirty && runs('commit') && 'the working tree',
+  bumping && 'a version bump',
+  rolledChangelog && 'a changelog entry',
+].filter(Boolean)
+if (taggedCommit && runs('tag') && wouldCommit.length) {
   fail(
     `tag ${tag} already exists at HEAD, but this run would still commit ` +
-      `${[bumping && 'a version bump', rolledChangelog && 'a changelog entry'].filter(Boolean).join(' and ')}.\n` +
-      '       That commit would leave the tag behind HEAD. Release a new version, or use ' +
-      '--only with the steps that remain.',
+      `${wouldCommit.join(' and ')}.\n` +
+      '       That commit would leave the tag behind HEAD, and publish a tree it does not ' +
+      'describe.\n       Release a new version, or use --only with the steps that remain.',
   )
 }
 
@@ -2211,33 +3291,38 @@ if (dirty && runs('commit')) {
   else mutate('git', ['commit', '-m', commitMessage])
 
   // Now that the commit exists it is part of the release, so the notes can describe it.
-  if (notesDeferred && !dryRun) {
+  if (notesPending && !dryRun) {
     draftedNotes = draftNotesFor(version)
     if (draftedNotes) notes = draftedNotes
   }
 }
 
+runHook('beforeVersion')
+
 if (bumping) {
   step(`Write version ${version}`)
-  for (const entry of [versionFile, ...config.versionFiles]) {
-    const source = versionSource(entry)
+  const releaseDate = new Date().toISOString().slice(0, 10)
+  for (const source of versionTargets) {
     if (!existsSync(source.path)) abort(`versionFiles entry ${source.path} does not exist`)
-    if (writeVersionInto(source, version, { dryRun })) {
+    if (writeVersionInto(source, version, { dryRun, date: releaseDate })) {
       staged.push(source.path)
       console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${source.path}`)
     }
   }
-  // A package-lock.json embeds the root version twice, so it goes stale on a bump.
-  if (existsSync('package-lock.json')) {
-    mutate('npm', ['install', '--package-lock-only', '--ignore-scripts', '--silent'])
-    staged.push('package-lock.json')
-  }
+  refreshLockfiles(versionTargets.map((source) => source.path))
 }
 
+// After the version is on disk and before the release commit, so a file the hook
+// regenerates from the version rides in that commit rather than being left behind.
+runHook('afterVersion')
+
+/** The version headings a changelog carries are dead link references without these. */
+const linked = (text) => withChangelogLinks(text, remoteLinks(config.remote), config.tagPrefix)
+
 if (rolledChangelog && runs('changelog')) {
   step(`Roll ${config.changelog} to ${version}`)
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
-  else writeFileSync(config.changelog, rolledChangelog)
+  else writeFileSync(config.changelog, linked(rolledChangelog))
   staged.push(config.changelog)
 } else if (runs('changelog') && draftedNotes && config.changelog && existsSync(config.changelog)) {
   step(`Add the drafted ${version} section to ${config.changelog}`)
@@ -2245,11 +3330,13 @@ if (rolledChangelog && runs('changelog')) {
   else {
     writeFileSync(
       config.changelog,
-      insertChangelogSection(
-        readFileSync(config.changelog, 'utf8'),
-        version,
-        new Date().toISOString().slice(0, 10),
-        draftedNotes,
+      linked(
+        insertChangelogSection(
+          readFileSync(config.changelog, 'utf8'),
+          version,
+          new Date().toISOString().slice(0, 10),
+          draftedNotes,
+        ),
       ),
     )
   }
@@ -2294,15 +3381,25 @@ if (runs('tag') && !taggedCommit) {
 
 if (runs('push')) {
   step(`Push branch and tag to ${config.remote}`)
-  // --follow-tags sends the commit and the tag in one call; pushing them separately is how
-  // a tag ends up on the remote without its commit, or a release without its tag.
-  mutate('git', ['push', '--follow-tags', config.remote, branch ?? 'HEAD'])
+  pushBranchAndTag(branch ?? 'HEAD')
 }
 
-if (publishCommand && !alreadyPublished) {
-  step(`Publish to the registry (dist-tag ${distTag})`)
-  mutateShell(publishCommand)
+// After the tag is pushed and before anything is published: the point where an artefact
+// the publish command expects to find has to exist.
+if (publishTargets.length) runHook('beforePublish')
+
+let publishedSomething = false
+for (const target of publishTargets) {
+  if (alreadyPublished.has(target.command)) continue
+  step(
+    `Publish ${target.name} (${target.cli}${NPM_CLIS.has(target.cli) ? `, dist-tag ${distTag}` : ''})`,
+  )
+  mutateShell(target.command)
+  publishedSomething = true
 }
+// Only when something was actually published: a re-run that skipped every already-published
+// target published nothing, and telling downstream otherwise is a lie it may act on.
+if (publishedSomething) runHook('afterPublish')
 
 if (runs('release') && !releaseExists) {
   step(`GitHub release ${tag}`)
@@ -2318,6 +3415,7 @@ if (runs('release') && !releaseExists) {
     ...config.assets,
   ]
   mutate('gh', args, notes ? { input: `${notes}\n` } : {})
+  runHook('afterRelease')
 }
 
 /**
@@ -2337,7 +3435,7 @@ function emitOutputs() {
     name: projectName,
     'dist-tag': distTag,
     steps: STEPS.filter(runs).join(','),
-    published: String(!!publishCommand && !alreadyPublished),
+    published: String(publishTargets.some((target) => !alreadyPublished.has(target.command))),
     'release-url': releaseUrl,
   }
   try {