@entro314labs/release-kit 2.3.2 → 2.4.0

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.
@@ -333,6 +342,11 @@ the version. Only the version itself is rewritten, so comments and formatting su
 because the TOML match is anchored to the start of a line, a dependency's
 `serde = { version = "1.0" }` is left alone.
 
+**Lockfiles are scoped automatically.** A `Cargo.lock` records a version for every
+dependency — hundreds of them — so matching the first `version = "…"` would rewrite an
+unrelated crate. Listing one rewrites only the `[[package]]` block whose name matches the
+crate in the sibling `Cargo.toml`; with no sibling to read, it refuses rather than guesses.
+
 For anything else, give a pattern with one capture group around the version. `versionFiles`
 takes the same entries, so several files stay in sync across formats:
 
@@ -343,6 +357,29 @@ takes the same entries, so several files stay in sync across formats:
 }
 ```
 
+A desktop app usually carries the same version in a lot of places at once — a workspace
+manifest, per-platform bundle configs, a crate manifest and its lockfile. They stay in step
+in one release, across three formats, with no scripting:
+
+```json
+{
+  "versionFiles": [
+    "apps/desktop/package.json",
+    "apps/desktop/src-tauri/tauri.conf.json",
+    "apps/desktop/src-tauri/tauri.macos.conf.json",
+    "apps/desktop/src-tauri/tauri.windows.conf.json",
+    "apps/desktop/src-tauri/tauri.linux.conf.json",
+    "apps/desktop/src-tauri/Cargo.toml",
+    "apps/desktop/src-tauri/Cargo.lock"
+  ],
+  "publish": null,
+  "steps": ["version", "changelog", "tag", "push"]
+}
+```
+
+Stopping at `push` because the tag is what triggers the build pipeline — see
+[Libraries versus apps](#-libraries-versus-apps).
+
 The project name comes from the manifest when there is one (`name` in `package.json`,
 `Cargo.toml` or `pyproject.toml`), and falls back to the repository directory.
 
@@ -528,6 +565,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,8 +663,24 @@ 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
 
+```sh
+pnpm install
+pnpm test     # 63 tests, node --test, no framework
+pnpm check    # format + lint + tests, the same gate CI runs
+```
+
+`test/` holds unit suites for the pure functions and an integration suite that builds real
+throwaway repositories with a real bare remote and stubbed `gh`/`npm`. The integration tests
+pin defects found in use, so a name like "refuses to reuse a tag while still producing a
+commit" is describing something that actually happened.
+
 The tool releases itself, so a change ships the same way it would in any consuming project:
 add a `## [Unreleased]` entry to `CHANGELOG.md`, then run `pnpm release <bump>` from a clone.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "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",
@@ -41,12 +41,14 @@
     "format:check": "oxfmt --check .",
     "lint": "oxlint .",
     "lint:ci": "oxlint --deny-warnings .",
-    "check": "pnpm run format:check && pnpm run lint:ci",
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "check": "pnpm run format:check && pnpm run lint:ci && pnpm run test",
     "release": "node release.mjs"
   },
   "devDependencies": {
     "oxfmt": "^0.63.0",
-    "oxlint": "^1.78.0"
+    "oxlint": "^1.78.0",
+    "semver": "^7.8.5"
   },
   "engines": {
     "node": ">=22"

package/release.mjs

@@ -41,7 +41,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
-import { basename, join, relative, resolve, sep } from 'node:path'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -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})(\\([^)]+\\))?!?: .+`)
 
@@ -766,7 +857,8 @@ function rollUnreleased(text, version, date) {
 
   // An empty [Unreleased] has nothing to promote; rolling it produces an empty section.
   const rest = text.slice(match.index + match[0].length)
-  const body = (/^## /m.exec(rest) ? rest.slice(0, /^## /m.exec(rest).index) : rest).trim()
+  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)
@@ -827,9 +919,29 @@ function readNameFrom(entry) {
 /** Normalise a versionFile / versionFiles entry to { path, pattern }. */
 const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } : entry)
 
+/**
+ * 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.
+ * Rewriting it corrupts an unrelated dependency, silently. Scope to the named package block.
+ */
+function cargoLockPattern(lockPath) {
+  const sibling = join(dirname(lockPath), 'Cargo.toml')
+  const crate = existsSync(sibling) ? readNameFrom({ path: sibling }) : null
+  if (!crate) {
+    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 = ` +
+        `\\"(.+)\\"" }`,
+    )
+  }
+  return new RegExp(`\\[\\[package\\]\\]\\nname = "${escapeRe(crate)}"\\nversion = "([^"]*)"`)
+}
+
 /** 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')
+  if (basename(path) === 'Cargo.lock') return cargoLockPattern(path)
   if (path.endsWith('.json')) return VERSION_PATTERNS.json
   if (path.endsWith('.toml')) return VERSION_PATTERNS.toml
   return null
@@ -849,9 +961,10 @@ function readVersionFrom(entry) {
  * 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
  * @returns {boolean} whether the file needed changing
  */
-function writeVersionInto(entry, version) {
+function writeVersionInto(entry, version, { dryRun = false } = {}) {
   const source = versionSource(entry)
   const text = readFileSync(source.path, 'utf8')
   const pattern = patternFor(source)
@@ -900,6 +1013,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')
@@ -929,8 +1043,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
@@ -943,9 +1059,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)
@@ -960,6 +1082,7 @@ const VALUE_OPTIONS = new Set([
   '--skip',
   '--preid',
   '--dist-tag',
+  '--notes-file',
   '--assistant',
   '--assistant-model',
   '--assistant-effort',
@@ -1035,6 +1158,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')
@@ -1069,6 +1203,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 = [
@@ -1294,8 +1437,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')
@@ -1476,7 +1635,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 ` +
@@ -1484,7 +1643,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')
@@ -1548,6 +1710,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 })
@@ -1560,7 +1745,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')
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1571,18 +1760,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) {
@@ -1596,7 +1775,7 @@ if (bumping) {
   for (const entry of [versionFile, ...config.versionFiles]) {
     const source = versionSource(entry)
     if (!existsSync(source.path)) abort(`versionFiles entry ${source.path} does not exist`)
-    if (writeVersionInto(source, version)) {
+    if (writeVersionInto(source, version, { dryRun })) {
       staged.push(source.path)
       console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${source.path}`)
     }
@@ -1636,6 +1815,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