@entro314labs/release-kit 2.3.1 → 2.3.3

package/README.md

@@ -55,6 +55,7 @@ Released v2.5.0
 | [📦 Install](#-install)                                                 | package, `npx`, or vendored file        |
 | [⚡ Usage](#-usage)                                                     | targets, bumps, flags                   |
 | [🧩 Steps](#-steps)                                                     | the seven steps and how to select them  |
+| [📚 Libraries versus apps](#-libraries-versus-apps)                     | which steps you want, and why           |
 | [🤖 Assistant](#-assistant-optional)                                    | optional AI drafting                    |
 | [🌍 Any language](#-any-language)                                       | Rust, Python, tag-only, anything        |
 | [✅ Preflight](#-preflight)                                             | what is checked before anything mutates |
@@ -231,8 +232,11 @@ Notes resolve in this order:
 2. The `## [Unreleased]` section, if the version has no section of its own — this is the
    same content that step 2 above is about to promote.
 3. The commits grouped by Conventional Commit type — Features, Bug Fixes, Performance
-   Improvements, Reverts, with breaking changes first and chores, CI and docs hidden. This
-   is deterministic and needs nothing installed, so decent notes are the default rather
+   Improvements, Reverts, with breaking changes first and chores, CI and docs hidden. Each
+   bullet links to its commit, and `closes #12` / `fixes #34` in a message becomes a link to
+   the issue. A `BREAKING CHANGE:` footer is used in place of the subject, since it explains
+   the break. A commit reverted within the same release drops out along with its revert.
+   All deterministic and needing nothing installed, so decent notes are the default rather
    than something that requires an assistant.
 4. Otherwise GitHub generates them from the commits since the previous tag.
 
@@ -323,6 +327,11 @@ Anything else runs as written with no preflight. The project name comes from the
 `name` in `package.json`, `Cargo.toml` or `pyproject.toml`, `module` in `go.mod` — falling
 back to the repository directory.
 
+`publish` is detected too, but only where one ecosystem obviously owns it: `package.json`
+gets `npm publish`, `Cargo.toml` gets `cargo publish`. Python has several publishers (uv,
+twine, poetry, flit) and Go has none, so those get nothing rather than a guess — publishing
+to the wrong registry is a far worse failure than being asked to configure it.
+
 With no `versionFile` configured it is detected from the repository — `package.json`,
 `pyproject.toml`, `Cargo.toml`, then `VERSION` — so most projects need no config for it at
 all. Set it explicitly to override, or to `null` for a repository that versions by tag.
@@ -528,6 +537,80 @@ One row in `ASSISTANTS` in `release.mjs`: the command, the args that make it rea
 stdin, and how it spells model and effort. Tools whose stdout carries session scaffolding
 declare `outputFile` and the answer is read from there instead.
 
+## 📚 Libraries versus apps
+
+Publishing splits in two, and which one you are decides the `steps` you want.
+
+**A library, package or tool publishes its source.** The registry receives what is already
+in the repository — `npm publish`, `cargo publish`, `uv publish` — and there is nothing to
+build first. release-kit does the whole thing:
+
+```json
+{}
+```
+
+Defaults are already correct: version → changelog → tag → push → publish → release.
+
+**An app has to be built before anything can be published.** Binaries, installers, bundles,
+container images: the artifact does not exist until something makes it. That build belongs
+to a build tool, and it changes where release-kit stops.
+
+### Apps with a simple build
+
+If the build runs before the release and leaves files on disk, release-kit can attach them
+itself. Nothing else is needed:
+
+```json
+{ "assets": ["dist/app-macos.zip", "dist/app-linux.tar.gz"], "publish": null }
+```
+
+Preflight fails if a listed asset is missing, so a release cannot quietly ship without its
+binaries.
+
+### Apps with a real build pipeline
+
+goreleaser, cargo-dist and electron-builder build for many targets and create the GitHub
+release themselves, with the artifacts attached. That is their job. release-kit's work ends
+at the pushed tag:
+
+```json
+{ "steps": ["version", "changelog", "tag", "push"], "notesFile": "dist-notes.md" }
+```
+
+Nothing after `push` — no `publish`, no `release`. The tag push is the handoff, and it is
+what triggers the build workflow:
+
+```yaml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    steps:
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0 }
+      - run: goreleaser release --clean --release-notes dist-notes.md
+```
+
+**Do not leave `release` in `steps` here.** goreleaser creates the GitHub release itself; if
+release-kit has already created one for that tag, goreleaser fails. Exactly one of them
+should own it, and it should be the one attaching the binaries.
+
+`notesFile` exists for this handoff: goreleaser's `--release-notes` takes a file and skips
+its own changelog generation. The notes are also in the annotated tag, but reading them back
+with `git tag --format='%(contents)'` embeds the signature when tags are signed, which then
+appears in your published release notes. `notesFile` writes the text itself.
+
+### Both at once
+
+A project can be both — a Rust crate that also ships binaries, say. Publish the library from
+release-kit and let the build tool handle the binaries and the release:
+
+```json
+{ "publish": "cargo publish", "steps": ["version", "changelog", "tag", "push", "publish"] }
+```
+
 ## 🔄 Keeping vendored copies in sync
 
 Installed as a dependency, updates come from your package manager and there is nothing to
@@ -552,6 +635,11 @@ including a directory that is not a repository.
 - Whatever the `publish` command needs — for the default, a live `npm login` session
   (two hours) or an OIDC trusted-publishing environment
 
+## 🗺 Roadmap
+
+Known defects, missing infrastructure, and the ideas that were considered and declined —
+with the reasoning — are in [ROADMAP.md](ROADMAP.md).
+
 ## 🤝 Contributing
 
 The tool releases itself, so a change ships the same way it would in any consuming project:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",

package/release.mjs

@@ -62,10 +62,13 @@ import { createInterface } from 'node:readline/promises'
  *                            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; null to skip publishing entirely
+ *   publish         string   publish command. Detected from the version source when unset,
+ *                            and only where it is unambiguous; null to publish nothing
  *   commitMessage   string   release commit subject
  *   releaseTitle    string   GitHub release title
  *   assets          string[] files attached to the GitHub release
+ *   notesFile       string   write the resolved release notes here, for a build tool that
+ *                            takes them as a file (goreleaser --release-notes, and similar)
  *   versioning      string   how `auto` derives a bump: "conventional", or
  *                            always-patch / always-minor / always-major to never infer
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
@@ -102,11 +105,12 @@ const DEFAULTS = {
   changelog: 'CHANGELOG.md',
   versionFile: undefined,
   versionFiles: [],
-  publish: 'npm publish --tag %d',
+  publish: undefined,
   commitMessage: 'chore(release): %t',
   releaseTitle: '%t',
   assets: [],
   assistant: null,
+  notesFile: null,
   versioning: 'conventional',
 }
 
@@ -148,6 +152,7 @@ Flags:
   --dist-tag <name>    override the npm dist-tag (default: derived from the version)
   --dry-run            print every step and execute nothing
   --yes, -y            skip the confirmation prompt
+  --notes-file <path>  write the resolved release notes to a file for the next tool
   --assistant <name>   drafting CLI to use: auto, none, claude, codex
   --assistant-model <name>
                        model the assistant runs with (e.g. sonnet, opus)
@@ -381,14 +386,16 @@ function commitsSinceLastTag() {
   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.
-  const raw = tryRead('git', ['log', `--format=%B%x1e`, range]) ?? ''
+  // %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]) ?? ''
   const commits = raw
-    .split('\u001e')
+    .split('\u001E')
     .map((entry) => entry.trim())
     .filter(Boolean)
     .map((entry) => {
-      const [subject, ...rest] = entry.split('\n')
-      return { subject: subject.trim(), body: rest.join('\n').trim() }
+      const [hash, message = ''] = entry.split('\u001F')
+      const [subject, ...rest] = message.split('\n')
+      return { hash: hash.trim(), subject: subject.trim(), body: rest.join('\n').trim() }
     })
     .filter(
       ({ subject }) =>
@@ -398,7 +405,8 @@ function commitsSinceLastTag() {
         !/^wip\b/i.test(subject) &&
         !/^(fixup|squash)!/.test(subject),
     )
-  return { lastTag, commits, subjects: commits.map((c) => c.subject) }
+  const kept = withoutRevertedCommits(commits)
+  return { lastTag, commits: kept, subjects: kept.map((c) => c.subject) }
 }
 
 /**
@@ -426,16 +434,31 @@ const CHANGELOG_SECTIONS = [
  * @returns {{type: string, scope: string|null, breaking: boolean, subject: string,
  *   releaseAs: string|null} | null} null when the subject is not Conventional Commits
  */
-function parseCommit(subject, body = '') {
+function parseCommit(subject, body = '', hash = '') {
   const match = /^([a-z]+)(?:\(([^)]+)\))?(!)?: (.+)$/i.exec(subject)
   if (!match) return null
   const [, type, scope, bang, text] = match
+  const shortHash = hash.slice(0, 7)
   // A breaking change is marked either by `!` in the header or a BREAKING CHANGE footer.
   const breaking = !!bang || /^BREAKING[ -]CHANGE:/m.test(body)
   // `Release-As: 1.2.3` in a commit body pins the next version, so the decision can live
   // in git history rather than on the command line.
   const releaseAs = /^Release-As:\s*v?(\S+)/im.exec(body)?.[1] ?? null
-  return { type: type.toLowerCase(), scope: scope ?? null, breaking, subject: text, releaseAs }
+  // Issues this commit closes, so the notes can link them the way a reader expects.
+  const closes = [...`${subject}\n${body}`.matchAll(CLOSES)].map((m) => m[1])
+  // 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
+  return {
+    type: type.toLowerCase(),
+    scope: scope ?? null,
+    breaking,
+    subject: text,
+    hash: shortHash,
+    releaseAs,
+    closes: [...new Set(closes)],
+    breakingNote,
+  }
 }
 
 /**
@@ -448,7 +471,7 @@ function parseCommit(subject, body = '') {
  * @returns {{bump: string, breaking: string[], features: string[], releaseAs: string|null}}
  */
 function inferBump(commits, currentVersion, strategy = 'conventional') {
-  const parsed = commits.map((c) => parseCommit(c.subject, c.body)).filter(Boolean)
+  const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
   const releaseAs = parsed.find((c) => c.releaseAs)?.releaseAs ?? null
   const breaking = parsed.filter((c) => c.breaking).map((c) => c.subject)
   const features = parsed
@@ -472,14 +495,27 @@ function inferBump(commits, currentVersion, strategy = 'conventional') {
  *
  * @returns {string | null} markdown body, or null when nothing visible changed
  */
-function changelogFromCommits(commits) {
-  const parsed = commits.map((c) => parseCommit(c.subject, c.body)).filter(Boolean)
+function changelogFromCommits(commits, links = null) {
+  const parsed = commits.map((c) => parseCommit(c.subject, c.body, c.hash)).filter(Boolean)
   const lines = []
 
+  /** One bullet: scope, text, a link to the commit, and any issues it closes. */
+  const bullet = (commit, text) => {
+    const scope = commit.scope ? `**${commit.scope}:** ` : ''
+    const parts = []
+    if (links && commit.hash) parts.push(`([${commit.hash}](${links.commit}/${commit.hash}))`)
+    if (commit.closes.length) {
+      const issues = commit.closes.map((n) => (links ? `[#${n}](${links.issue}/${n})` : `#${n}`))
+      parts.push(`closes ${issues.join(', ')}`)
+    }
+    return `- ${scope}${text}${parts.length ? ` ${parts.join(', ')}` : ''}`
+  }
+
   const breaking = parsed.filter((c) => c.breaking)
   if (breaking.length) {
     lines.push('### ⚠ BREAKING CHANGES', '')
-    for (const c of breaking) lines.push(`- ${c.scope ? `**${c.scope}:** ` : ''}${c.subject}`)
+    // The footer explains the break; the subject only says what changed.
+    for (const c of breaking) lines.push(bullet(c, c.breakingNote ?? c.subject))
     lines.push('')
   }
 
@@ -490,13 +526,68 @@ function changelogFromCommits(commits) {
     )
     if (!inSection.length) continue
     lines.push(`### ${section}`, '')
-    for (const c of inSection) lines.push(`- ${c.scope ? `**${c.scope}:** ` : ''}${c.subject}`)
+    for (const c of inSection) lines.push(bullet(c, c.subject))
     lines.push('')
   }
 
   return lines.length ? lines.join('\n').trim() : null
 }
 
+/**
+ * Per-forge URL shapes and the words that close an issue, following
+ * @semantic-release/release-notes-generator's hosts-config. The path segments genuinely
+ * 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' },
+}
+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
+
+/**
+ * The repository behind `origin`, for building links.
+ *
+ * Handles both URL forms git uses: `https://host/owner/repo.git` and the SCP-like
+ * `git@host:owner/repo.git`, which is not a URL and does not parse as one.
+ *
+ * @returns {{base: string, issue: string, commit: string} | null}
+ */
+function remoteLinks(remote) {
+  const url = tryRead('git', ['remote', 'get-url', remote])
+  if (!url) return null
+  const scp = /^(?:[^@]+@)?([^:/]+):(.+?)(?:\.git)?$/.exec(url.replace(/^ssh:\/\//, ''))
+  const web = /^[a-z+]+:\/\/(?:[^@]+@)?([^/]+)\/(.+?)(?:\.git)?$/i.exec(url)
+  const [, host, path] = web ?? scp ?? []
+  if (!host || !path) return null
+  const shape = HOSTS[host.toLowerCase()] ?? DEFAULT_HOST
+  return {
+    base: `https://${host}/${path}`,
+    issue: `https://${host}/${path}/${shape.issue}`,
+    commit: `https://${host}/${path}/${shape.commit}`,
+  }
+}
+
+/**
+ * Drop commits that were reverted within the same release, and the reverts themselves —
+ * neither belongs in notes describing what changed. A `git revert` records the reverted
+ * hash in its body, which is what pairs them up.
+ */
+function withoutRevertedCommits(commits) {
+  const reverted = new Set()
+  for (const { body } of commits) {
+    const match = /This reverts commit ([0-9a-f]{7,40})/i.exec(body ?? '')
+    if (match) reverted.add(match[1].slice(0, 7))
+  }
+  if (!reverted.size) return commits
+  return commits.filter(
+    (c) => !reverted.has((c.hash ?? '').slice(0, 7)) && !/This reverts commit/i.test(c.body ?? ''),
+  )
+}
+
 const CONVENTIONAL_TYPES = 'build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
 const CONVENTIONAL_RE = new RegExp(`^(${CONVENTIONAL_TYPES})(\\([^)]+\\))?!?: .+`)
 
@@ -756,9 +847,19 @@ function changelogSection(text, version) {
  * @returns {string | null} the updated document, or null when there is nothing to roll
  */
 function rollUnreleased(text, version, date) {
+  // A heading for this version already exists — possibly with an empty body, which
+  // `changelogSection` reports as absent. Rolling again would duplicate the heading.
+  if (new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)) return null
+
   const heading = /^##\s+\[?Unreleased\]?[^\n]*$/im
   const match = heading.exec(text)
   if (!match) return null
+
+  // An empty [Unreleased] has nothing to promote; rolling it produces an empty section.
+  const rest = text.slice(match.index + match[0].length)
+  const next = /^## /m.exec(rest)
+  const body = (next ? rest.slice(0, next.index) : rest).trim()
+  if (!body) return null
   const released = `## [Unreleased]\n\n## [${version}] - ${date}`
   return text.slice(0, match.index) + released + text.slice(match.index + match[0].length)
 }
@@ -891,6 +992,7 @@ const skippedSteps = option('--skip')
 const explicitDistTag = option('--dist-tag')
 const requestedPreid = option('--preid')
 const autoCommit = flag('--commit')
+const requestedNotesFile = option('--notes-file')
 const requestedAssistant = option('--assistant')
 const requestedModel = option('--assistant-model')
 const requestedEffort = option('--assistant-effort')
@@ -920,8 +1022,10 @@ if (flag('--sync')) {
     const projectRoot = resolve(target)
     const destination = join(projectRoot, 'scripts', basename(self))
     if (destination === self) continue
-    if (!existsSync(join(projectRoot, 'package.json'))) {
-      warn(`${target}: no package.json — skipped`)
+    // Any directory can hold a vendored copy: a manifest is only needed to wire up a
+    // script, which Rust, Python and Go projects do not have and do not need.
+    if (!existsSync(projectRoot)) {
+      warn(`${target}: no such directory — skipped`)
       continue
     }
     const current = existsSync(destination) ? readFileSync(destination, 'utf8') : null
@@ -934,9 +1038,15 @@ if (flag('--sync')) {
       writeFileSync(destination, source)
     }
     ok(`${target}: ${current === null ? 'installed' : 'updated'}${dryRun ? ' (dry run)' : ''}`)
-    const scripts = readJson(join(projectRoot, 'package.json')).scripts ?? {}
-    if (!scripts.release) {
-      warn(`${target}: add "release": "node scripts/${basename(self)}" to package.json`)
+
+    const manifestPath = join(projectRoot, 'package.json')
+    if (existsSync(manifestPath)) {
+      const scripts = readJson(manifestPath).scripts ?? {}
+      if (!scripts.release) {
+        warn(`${target}: add "release": "node scripts/${basename(self)}" to package.json`)
+      }
+    } else {
+      note(`${target}: run it with \`node scripts/${basename(self)}\``)
     }
   }
   process.exit(0)
@@ -951,6 +1061,7 @@ const VALUE_OPTIONS = new Set([
   '--skip',
   '--preid',
   '--dist-tag',
+  '--notes-file',
   '--assistant',
   '--assistant-model',
   '--assistant-effort',
@@ -1026,6 +1137,17 @@ function detectVersionFile() {
   return null
 }
 
+/**
+ * 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
+ * none, so those get nothing rather than a guess — publishing to the wrong registry is a
+ * far worse failure than being asked to configure it.
+ */
+const PUBLISH_BY_MANIFEST = {
+  'package.json': 'npm publish --tag %d',
+  'Cargo.toml': 'cargo publish',
+}
+
 // 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')
@@ -1060,6 +1182,15 @@ const goModule = existsSync('go.mod')
 const projectName =
   manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
 
+// 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
+}
+
 // Validate every name that was asked for, not just the ones that survive: a typo in
 // --skip would otherwise delete nothing and silently run the step you meant to drop.
 const requestedStepNames = [
@@ -1285,8 +1416,24 @@ if (bumping && compareVersions(version, currentVersion) <= 0) {
 const dirty = tryRead('git', ['status', '--porcelain'])
 if (dirty === null) fail('could not read git status')
 else if (dirty && runs('commit')) {
-  ok(`working tree has ${dirty.split('\n').length} change(s) — will be committed first`)
+  const entries = dirty.split('\n')
+  ok(`working tree has ${entries.length} change(s) — will be committed first`)
   console.log(dim(indent(formatStatus(dirty))))
+  // One commit gets one subject. A change set spanning several top-level directories is
+  // usually several pieces of work, and no honest Conventional Commits subject covers it.
+  const areas = new Set(
+    entries.map(
+      (entry) => entry.trim().split(/\s+/).slice(1).join(' ').replaceAll('"', '').split('/')[0],
+    ),
+  )
+  if (areas.size > 2) {
+    warn(
+      `these span ${areas.size} top-level paths (${[...areas].slice(0, 4).join(', ')}${areas.size > 4 ? ', …' : ''}), ` +
+        'which is usually more than one piece of work.\n' +
+        '       One commit gets one subject: consider committing them yourself, then ' +
+        'releasing with --skip commit.',
+    )
+  }
 } else if (dirty) {
   fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
 } else ok('working tree clean')
@@ -1467,7 +1614,7 @@ const notesDeferred = !!(dirty && runs('commit') && assistant)
 function draftNotesFor(v) {
   const { lastTag, subjects, commits } = commitsSinceLastTag()
   if (!commits.length) return null
-  if (!assistant) return changelogFromCommits(commits)
+  if (!assistant) return changelogFromCommits(commits, remoteLinks(config.remote))
   if (shallow) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
@@ -1475,7 +1622,10 @@ function draftNotesFor(v) {
     )
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
-  return draftReleaseNotes(v, subjects, lastTag) ?? changelogFromCommits(commits)
+  return (
+    draftReleaseNotes(v, subjects, lastTag) ??
+    changelogFromCommits(commits, remoteLinks(config.remote))
+  )
 }
 if (config.changelog && existsSync(config.changelog)) {
   const text = readFileSync(config.changelog, 'utf8')
@@ -1515,6 +1665,18 @@ for (const asset of config.assets) {
   else fail(`asset ${asset} does not exist`)
 }
 
+// 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)) {
+  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.',
+  )
+}
+
 if (problems.length) {
   const summary = `${problems.length} preflight check(s) failed:\n  - ${problems.join('\n  - ')}`
   if (!dryRun) abort(summary)
@@ -1527,6 +1689,29 @@ if (problems.length) {
 // CONFIRM
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Stage the working tree and draft its commit message before the confirmation prompt, so
+ * what gets approved is the message that will actually be written. Staging is the first
+ * mutation, and it is undone if the release is declined — `git add` touches only the index,
+ * never the working tree, so restoring it is exact.
+ */
+let commitMessage = null
+let didStage = false
+if (dirty && runs('commit') && !dryRun) {
+  step('Stage the working tree')
+  mutate('git', ['add', '--all'])
+  didStage = true
+  commitMessage = draftCommitMessage()
+  if (!commitMessage) {
+    mutate('git', ['reset', '--quiet'])
+    abort(
+      `${assistantName} could not draft a Conventional Commits message for these changes.\n\n` +
+        '  Commit them yourself and re-run, or run without --commit.',
+    )
+  }
+  console.log(indent(commitMessage))
+}
+
 if (!assumeYes && !dryRun && process.stdin.isTTY) {
   if (notes) console.log(`\n${bold('Release notes')}\n${indent(notes)}`)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
@@ -1539,7 +1724,11 @@ if (!assumeYes && !dryRun && process.stdin.isTTY) {
   } finally {
     rl.close()
   }
-  if (!/^y(es)?$/i.test(answer.trim())) abort('cancelled')
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    // Leave the index exactly as it was found.
+    if (didStage) mutate('git', ['reset', '--quiet'])
+    abort('cancelled')
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1550,18 +1739,8 @@ const staged = []
 
 if (dirty && runs('commit')) {
   step('Commit the working tree')
-  mutate('git', ['add', '--all'])
-  // Draft after staging: the message describes what is staged, not what happens to be
-  // in the tree. Under --dry-run nothing was staged, so there is nothing to describe.
-  const message = dryRun ? null : draftCommitMessage()
-  if (!message && !dryRun) {
-    abort(
-      `${assistantName} could not draft a Conventional Commits message for the staged changes.\n\n` +
-        '  Commit them yourself and re-run, or run without --commit.',
-    )
-  }
-  console.log(indent(message ?? '<drafted at run time>'))
-  mutate('git', ['commit', '-m', message ?? 'chore: working tree'])
+  if (dryRun) console.log(`  ${yellow('would run:')} git commit -m <drafted at run time>`)
+  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) {
@@ -1615,6 +1794,20 @@ if (staged.length) {
   mutate('git', ['commit', '-m', expand(config.commitMessage)])
 }
 
+/**
+ * Hand the notes to whatever builds and publishes next. goreleaser, cargo-dist and similar
+ * take release notes as a file and then own the GitHub release themselves.
+ *
+ * The notes are also in the annotated tag, but reading them back with `%(contents)` embeds
+ * the signature when tags are signed — this writes the text itself, with no such trap.
+ */
+const notesFile = requestedNotesFile ?? config.notesFile
+if (notesFile) {
+  step(`Write release notes to ${notesFile}`)
+  if (dryRun) console.log(`  ${yellow('would write')} ${notesFile}`)
+  else writeFileSync(notesFile, `${notes ?? `${projectName} ${tag}`}\n`)
+}
+
 if (runs('tag') && !taggedCommit) {
   step(`Annotated tag ${tag}`)
   // The notes become the tag annotation too, so a CI release workflow can read them