@entro314labs/release-kit 2.9.3 → 2.9.4

package/README.md

@@ -185,20 +185,22 @@ Prerelease bumps need `--preid` unless the current version already carries one t
 
 ### Flags
 
-| Flag                         | Effect                                                                     |
-| ---------------------------- | -------------------------------------------------------------------------- |
-| `--only <steps>`             | Run only these steps, comma-separated.                                     |
-| `--skip <steps>`             | Run every step except these.                                               |
-| `--commit`                   | Force the `commit` step on when a `steps` config removed it.               |
-| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports. |
-| `--yes`, `-y`                | Skip the confirmation prompt.                                              |
-| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`. |
-| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.               |
-| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                           |
-| `--assistant-model <name>`   | Model the assistant runs with.                                             |
-| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                  |
-| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.       |
-| `--help`, `-h`               | Full flag list.                                                            |
+| Flag                         | Effect                                                                        |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `--only <steps>`             | Run only these steps, comma-separated.                                        |
+| `--skip <steps>`             | Run every step except these.                                                  |
+| `--commit`                   | Force the `commit` step on when a `steps` config removed it.                  |
+| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports.    |
+| `--yes`, `-y`                | Skip the confirmation prompt.                                                 |
+| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`.    |
+| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.                  |
+| `--notes <source>`           | Where notes come from: `auto`, `changelog`, `assistant`, `commits`, `github`. |
+| `--notes-file <path>`        | Write the resolved notes to a file for the next tool — see `notesFile`.       |
+| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                              |
+| `--assistant-model <name>`   | Model the assistant runs with.                                                |
+| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                     |
+| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.          |
+| `--help`, `-h`               | Full flag list.                                                               |
 
 ### Linting commits
 
@@ -350,6 +352,13 @@ rather than stopping at the first problem.
 
 - The target version is greater than the current one — and for `auto`, which bump the
   commits imply and why
+- The version step will write the target, when the target differs from what the files say
+  — a tag naming one version over a manifest carrying another is refused, since
+  `npm publish` sends the manifest
+- A relative bump is not counting from a version a dead run wrote and never committed
+  (the file says one thing on disk and another at `HEAD`), and not skipping past a release
+  tagged at `HEAD` that never reached the registry — both are refused with the command that
+  finishes the earlier release instead
 - Working tree is clean, or listed for commit when the `commit` step runs
 - On the configured branch, and not on a detached HEAD
 - The remote exists, is reachable, and the branch is not behind it
@@ -393,6 +402,13 @@ last tag, and after a failed publish there are none — the tag it would read fr
 the dead run made. Rather than aborting with "no releasable commits", it finishes that
 release: same version, same tag, the steps that remain.
 
+A relative bump is the one target that cannot be re-run as-is, because it counts from the
+version the dead run already wrote: `minor` after a dead `minor` would release `1.2.0`
+from the commit `v1.1.0` already tags. Preflight refuses both shapes of that — the bump
+written but never committed, and the tag at `HEAD` that never reached the registry — and
+names the command that finishes the earlier release: `release-kit 1.1.0`, or no target, or
+`auto`.
+
 ### A release that was never published
 
 A tag is not a release. The tag and the push happen before the publish, so a publish that
@@ -666,23 +682,27 @@ execution is not wired up yet.
 `release.config.json`, beside `package.json`. Every key is optional; unknown keys abort
 rather than being silently ignored.
 
-| Key             | Default                | Meaning                                                               |
-| --------------- | ---------------------- | --------------------------------------------------------------------- |
-| `steps`         | all but `commit`       | Which steps run; the order is fixed                                   |
-| `tagPrefix`     | `"v"`                  | Prepended to the version to form the tag                              |
-| `branch`        | `"main"`               | The only branch a release may run from; `null` allows any             |
-| `remote`        | `"origin"`             | Git remote to push to                                                 |
-| `changelog`     | `"CHANGELOG.md"`       | Changelog path; `null` for a project without one                      |
-| `versionFile`   | detected               | Where the version lives; `null` versions by tag alone                 |
-| `versionFiles`  | detected               | Further files kept in sync; a path or `{ path, pattern }`             |
-| `publish`       | detected               | Publish command, or an array of them; `null` publishes nothing        |
-| `versioning`    | `"conventional"`       | How `auto` infers; or `always-patch` / `-minor` / `-major`            |
-| `verify`        | `null`                 | Command run during preflight; non-zero aborts before anything mutates |
-| `hooks`         | `{}`                   | Commands run between the steps — see [Hooks](#-hooks)                 |
-| `assistant`     | `null`                 | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }`          |
-| `commitMessage` | `"chore(release): %t"` | Release commit subject                                                |
-| `releaseTitle`  | `"%t"`                 | GitHub release title                                                  |
-| `assets`        | `[]`                   | Files attached to the GitHub release                                  |
+| Key             | Default                | Meaning                                                                 |
+| --------------- | ---------------------- | ----------------------------------------------------------------------- |
+| `steps`         | all seven              | Which steps run; the order is fixed. `commit` no-ops on a clean tree    |
+| `tagPrefix`     | `"v"`                  | Prepended to the version to form the tag                                |
+| `branch`        | `"main"`               | The only branch a release may run from; `null` allows any               |
+| `remote`        | `"origin"`             | Git remote to push to                                                   |
+| `changelog`     | `"CHANGELOG.md"`       | Changelog path; `null` for a project without one                        |
+| `versionFile`   | detected               | Where the version lives; `null` versions by tag alone                   |
+| `versionFiles`  | detected               | Further files kept in sync; a path or `{ path, pattern }`               |
+| `publish`       | detected               | Publish command, or an array of them; `null` publishes nothing          |
+| `versioning`    | `"conventional"`       | How `auto` infers; or `always-patch` / `-minor` / `-major`              |
+| `verify`        | `null`                 | Command run during preflight; non-zero aborts before anything mutates   |
+| `hooks`         | `{}`                   | Commands run between the steps — see [Hooks](#-hooks)                   |
+| `assistant`     | `null`                 | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }`            |
+| `commitMessage` | `"chore(release): %t"` | Release commit subject                                                  |
+| `releaseTitle`  | `"%t"`                 | GitHub release title                                                    |
+| `assets`        | `[]`                   | Files attached to the GitHub release                                    |
+| `notes`         | `"auto"`               | Notes source; or force `changelog` / `assistant` / `commits` / `github` |
+| `notesFile`     | `null`                 | Write the resolved notes here for the tool that runs next               |
+| `hiddenTypes`   | `[]`                   | Commit types left out of commit-derived notes                           |
+| `ignoreCommits` | release, merge, wip…   | Regexes for commits that are bookkeeping rather than change             |
 
 Command and message strings expand four tokens: `%v` version, `%t` tag, `%n` package
 name, `%d` npm dist-tag. In the `publish` command line the substituted values are
@@ -774,7 +794,10 @@ Two npm behaviours are handled automatically:
   at all.** In GitHub Actions with
   `id-token: write`, or GitLab CI/CircleCI with `NPM_ID_TOKEN`, `whoami` fails while
   `publish` succeeds. That environment is detected and the auth check is skipped, so a
-  valid CI release is not aborted over a missing token it does not need.
+  valid CI release is not aborted over a missing token it does not need. That covers the
+  CLIs that exchange the OIDC token themselves — npm, pnpm, bun and `uv publish`. cargo is
+  not one of them: crates.io's trusted publishing goes through an action that turns the
+  token into `CARGO_REGISTRY_TOKEN`, so the cargo credential check still applies in CI.
 
 ### Examples
 
@@ -933,11 +956,13 @@ release themselves, with the artifacts attached. That is their job. release-kit'
 at the pushed tag:
 
 ```json
-{ "steps": ["commit", "version", "changelog", "tag", "push"], "notesFile": "dist-notes.md" }
+{ "steps": ["commit", "version", "changelog", "tag", "push"] }
 ```
 
 Nothing after `push` — no `publish`, no `release`. The tag push is the handoff, and it is
-what triggers the build workflow:
+what triggers the build workflow. The notes travel in the annotated tag, which is the one
+thing that reaches a fresh checkout on another machine; the signature block a signed tag
+appends is stripped before the file is handed over:
 
 ```yaml
 on:
@@ -949,6 +974,10 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with: { fetch-depth: 0 }
+      - name: Read the release notes off the tag
+        run: |
+          git tag -l --format='%(contents)' "$GITHUB_REF_NAME" \
+            | sed '/^-----BEGIN [A-Z ]*SIGNATURE-----$/,$d' > dist-notes.md
       - run: goreleaser release --clean --release-notes dist-notes.md
 ```
 
@@ -968,10 +997,11 @@ generated by different code from the same commits, and they drift.
 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.
+`notesFile` is the same handoff for a build tool that runs next **on the same machine**:
+`release-kit auto && goreleaser release --release-notes dist-notes.md`. It writes the text
+itself, with no signature to strip. It is written after the release commit and is not part
+of it, so a workflow on another machine never sees it — that is what the tag read above is
+for.
 
 ### Both at once
 

package/TRAIN.md

@@ -12,7 +12,11 @@ readable, vendorable, zero dependencies.
 **Status: prototype.** Discovery, graph derivation, registry-aware change detection,
 cascade, planning, whole-train preflight, `seed-tags`, and the train summary work.
 Execution (running release-kit per package) is not implemented yet — `train` without
-`--dry-run` says so and exits.
+`--dry-run` says so and exits. Three things the design below describes are not built
+either, and the plan does not claim them: taking `packages` from `pnpm-workspace.yaml` /
+`workspaces` when the config omits it (the config must list them today), and the two
+per-package authentication checks in the preflight table (publish CLI and `gh`), which
+each package's own release-kit run performs when execution lands.
 
 ```sh
 release-train graph                  # print the derived dependency graph and topo order

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.9.3",
+  "version": "2.9.4",
   "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",
@@ -49,11 +49,11 @@
     "release": "node release.mjs"
   },
   "devDependencies": {
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
     "semver": "^7.8.5"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }

package/release.mjs

@@ -47,6 +47,7 @@ import {
 import { homedir, tmpdir } from 'node:os'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // CONFIG
@@ -115,9 +116,10 @@ import { createInterface } from 'node:readline/promises'
 const STEPS = ['commit', 'version', 'changelog', 'tag', 'push', 'publish', 'release']
 
 /**
- * All seven. `commit` is a conditional default: it no-ops on a clean tree, and on a dirty
- * tree it proceeds only when a drafting assistant is configured — otherwise preflight
- * still refuses the unclean tree. Opt out with `--skip commit` or a `steps` config.
+ * All seven. `commit` no-ops on a clean tree; on a dirty tree it stages everything and
+ * commits it, with a drafted message when an assistant is configured and a generated
+ * `chore:` message naming the files otherwise. Opt out with `--skip commit` or a `steps`
+ * config, which restores the refusal on a dirty tree.
  */
 const DEFAULT_STEPS = [...STEPS]
 
@@ -185,11 +187,13 @@ release-kit — tag, publish, and release a JS/TS/Node project.
 
 Target (optional; defaults to the version already in package.json):
   <x.y.z>              release this exact version
+  auto                 infer the bump from the commits since the last tag
   patch minor major    bump from the current version
   prepatch preminor premajor prerelease
                        prerelease bump; needs --preid unless it can be inferred
 
-Steps, in the fixed order they run. All but "commit" run by default:
+Steps, in the fixed order they run. All seven run by default; "commit" no-ops on a
+clean tree:
   ${STEPS.join('  ')}
 
 Subcommands (they check, print or copy, and never start a release):
@@ -1352,7 +1356,7 @@ function distTagFor(version, explicitTag) {
   throw new Error(
     `prerelease identifier "${label}" maps to no known dist-tag ` +
       `(${[...KNOWN_CHANNELS].sort().join(', ')}). Publishing it as "latest" would ` +
-      `clobber the stable line — pass --tag <dist-tag> to choose one explicitly.`,
+      `clobber the stable line — pass --dist-tag <name> to choose one explicitly.`,
   )
 }
 
@@ -1672,7 +1676,18 @@ function patternFor({ path, pattern, all = false }) {
 /** @returns {string | null} the version recorded in a source file */
 function readVersionFrom(entry) {
   const source = versionSource(entry)
-  const text = readFileSync(source.path, 'utf8')
+  return versionInText(source, readFileSync(source.path, 'utf8'))
+}
+
+/**
+ * The version a source file's text carries, resolved the same way it will be written.
+ *
+ * Split from `readVersionFrom` so the text can come from somewhere other than the working
+ * tree — `git show HEAD:<path>` — and still be read by the resolver the write uses.
+ *
+ * @returns {string | null}
+ */
+function versionInText(source, text) {
   const { kind, shape } = versionMode(source, text)
   if (kind === 'bare') return text.trim() || null
   if (kind === 'markers') {
@@ -1895,7 +1910,11 @@ if (flag('--help') || flag('-h')) {
 
 // --sync copies this file into other projects and exits; it touches no git state.
 if (flag('--sync')) {
-  const self = new URL(import.meta.url).pathname
+  // A URL's pathname is percent-encoded and keeps the leading slash before a Windows
+  // drive letter, so a script installed under a directory with a space in its name — or
+  // anywhere on Windows — was reported as "piped from stdin". fileURLToPath is the
+  // inverse of what Node did to build import.meta.url.
+  const self = fileURLToPath(import.meta.url)
   // Piped from stdin (`curl … | node -`) there is no file to copy: import.meta.url points
   // at a synthetic [eval] path. Say so instead of failing on a missing file.
   if (!existsSync(self)) {
@@ -2022,6 +2041,9 @@ const VALUE_OPTIONS = new Set([
   '--assistant-effort',
 ])
 
+/** Flags that take no value. With VALUE_OPTIONS, the whole vocabulary this file accepts. */
+const BOOLEAN_FLAGS = new Set(['--dry-run', '--yes', '-y', '--commit', '--help', '-h', '--sync'])
+
 /** The version or bump target: the only argument that is neither a flag nor a flag's value. */
 const positionals = []
 for (let i = 0; i < argv.length; i += 1) {
@@ -2029,7 +2051,20 @@ for (let i = 0; i < argv.length; i += 1) {
     i += 1
     continue
   }
-  if (!argv[i].startsWith('-')) positionals.push(argv[i])
+  if (!argv[i].startsWith('-')) {
+    positionals.push(argv[i])
+    continue
+  }
+  // An unknown flag used to be dropped without a word, and `--auto` is the one people
+  // reach for: it released whatever version package.json already carried, which is a
+  // different release from the `auto` they asked for.
+  if (!BOOLEAN_FLAGS.has(argv[i])) {
+    const bare = argv[i].replace(/^-+/, '')
+    const hint = BUMPS.has(bare)
+      ? `\n  The target is positional: ${INVOCATION} ${bare}, not ${argv[i]}`
+      : ''
+    abort(`unknown flag: ${argv[i]}${hint}`)
+  }
 }
 const target = positionals[0]
 // A second positional is always a mistake, and silently ignoring it changes the release
@@ -2552,6 +2587,23 @@ let autoBump = null
 /** The tag of a previous release this run is finishing rather than starting. */
 let resuming = null
 
+/**
+ * A release tagged at HEAD that never reached the registry, found while resolving a
+ * relative bump. `auto` finishes such a release; a `patch`/`minor`/`major` cannot — it
+ * would bump past it, tag a second version on the same commit, and leave the first one
+ * unpublished for good. Preflight refuses it and names the command that finishes it.
+ */
+let unfinishedAtHead = null
+
+/**
+ * A release that died after the tag and before the publish is finished by re-running the
+ * same command — but only while nothing new has happened. A commit or a working tree that
+ * `--commit` is about to turn into one moves HEAD past the tag, and publishing then would
+ * ship a tree the tag does not describe; that work belongs in the next version, which is
+ * what the shipped-tag baseline makes sure it is released as.
+ */
+const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
+
 let version
 if (!target) {
   if (!currentVersion) {
@@ -2568,12 +2620,6 @@ if (!target) {
         'from.\n  Pass the first version explicitly: release-kit 0.1.0',
     )
   }
-  // A release that died after the tag and before the publish is finished by re-running the
-  // same command — but only while nothing new has happened. A commit or a working tree that
-  // `--commit` is about to turn into one moves HEAD past the tag, and publishing then would
-  // ship a tree the tag does not describe; that work belongs in the next version, which is
-  // what the baseline below makes sure it is released as.
-  const wouldCommitMore = !!tryRead('git', ['status', '--porcelain']) && runs('commit')
   const pending = wouldCommitMore ? null : unfinishedRelease()
   if (pending) {
     ;({ name: resuming, version } = pending)
@@ -2611,6 +2657,10 @@ if (!target) {
       `a ${target} bump from a stable version needs --preid <${[...KNOWN_CHANNELS].sort().join('|')}>`,
     )
   }
+  // The same question `auto` asks, with the opposite answer: `auto` finishes the release
+  // it finds at HEAD, a named bump would skip past it. Recorded here, refused in preflight
+  // with the rest.
+  unfinishedAtHead = wouldCommitMore ? null : unfinishedRelease()
   version = incrementVersion(currentVersion, target, preid)
 } else if (parseVersion(target)) {
   version = target
@@ -2749,6 +2799,33 @@ if (resuming) {
   ok(`finishing ${resuming}: it was tagged and pushed, but never reached the registry`)
 }
 
+if (unfinishedAtHead) {
+  fail(
+    `${unfinishedAtHead.name} is tagged at HEAD but never reached the registry, and a ` +
+      `${target} bump would release ${version} from the same commit and leave it that way.\n` +
+      `       Finish it instead: re-run with no target, or with auto.`,
+  )
+}
+
+// A run that wrote the version and died before its release commit — a failing lockfile
+// refresh, an afterVersion hook, a commit hook — leaves the bump on disk and nowhere
+// else. The current version is then read from that file, and a relative bump counts from
+// it: `minor` after a dead `minor` released 1.2.0 with 1.1.0 tagged nowhere, its changelog
+// section documenting a version that never existed. Only a bump is affected; an explicit
+// version, or none, releases what is on disk and the commit step carries it.
+if (target && BUMPS.has(target) && versionFile && currentVersion) {
+  const committed = tryRead('git', ['show', `HEAD:${versionFile.path}`])
+  const headVersion = committed === null ? null : versionInText(versionFile, committed)
+  if (headVersion && headVersion !== currentVersion) {
+    fail(
+      `${versionFile.path} says ${currentVersion} on disk but ${headVersion} at HEAD — an ` +
+        `uncommitted version bump, which a ${target} bump would count from and skip past.\n` +
+        `       Finish it with \`${INVOCATION} ${currentVersion}\`, or restore the file: ` +
+        `git restore ${versionFile.path}`,
+    )
+  }
+}
+
 // A previous release that never shipped is not history — its commits are still owed to
 // whoever installs this package, and they are in this release's range because of it. Say
 // so: the changelog keeps the section that was written for that version, and a section
@@ -2756,7 +2833,9 @@ if (resuming) {
 const absorbed = absorbedReleaseTags({ stable: !isPrerelease }).filter(
   (entry) => entry.version !== version,
 )
-if (absorbed.length) {
+// Not when the run is being refused for exactly this: saying the commits ship in a
+// version that will not be released contradicts the failure above it.
+if (absorbed.length && !unfinishedAtHead) {
   const names = absorbed.map((entry) => entry.name).join(', ')
   const many = absorbed.length > 1
   const existingChangelog =
@@ -2789,13 +2868,32 @@ if (bumping) {
     }
     if (source.optional) continue
     const text = readFileSync(source.path, 'utf8')
-    const { kind, shape } = versionMode(source, text)
+    // Resolving the mode can itself refuse — a Cargo.lock with nothing beside it to say
+    // which crate is yours — and the write step must not be where that is discovered.
+    let mode
+    try {
+      mode = versionMode(source, text)
+    } catch (err) {
+      fail(err.message)
+      continue
+    }
+    const { kind, shape } = mode
     if (kind === 'pattern' && !shape.test(text)) {
       fail(
         `${source.path} has no version for release-kit to replace.\n` +
           '       Remove it from versionFiles, mark the line with x-release-kit-version, ' +
           'or give the entry a "pattern".',
       )
+    } else if (kind === 'bare' && text.trim() && !parseVersion(text.trim())) {
+      // The whole-file mode is right for a VERSION file and catastrophic for anything
+      // else. `writeVersionInto` refuses it too, but by then the files before it in the
+      // list have already changed.
+      fail(
+        `${source.path} is not a file containing only a version, and carries no ` +
+          'x-release-kit-version marker.\n       Writing the version into it would replace ' +
+          'everything else in it. Mark the line that holds the version, or give the entry ' +
+          'a "pattern".',
+      )
     }
   }
 }
@@ -2807,6 +2905,17 @@ if (bumping && currentVersion && compareVersions(version, currentVersion) <= 0)
 } else if (bumping) {
   // No manifest and no tag to read a version from, but files to write one into.
   ok(`writing ${version} into ${versionTargets.map((source) => source.path).join(', ')}`)
+} else if (versionTargets.length && version !== currentVersion) {
+  // The version step is off and the target is not what the files say. The tag would name
+  // one version and the manifest — which is what `npm publish` sends and what the build
+  // compiles in — another. There is no release in which those two are allowed to differ.
+  const files = versionTargets.map((source) => source.path).join(', ')
+  fail(
+    `the version step is not selected, but ${version} is not the version in ${files}` +
+      `${currentVersion ? ` (${currentVersion})` : ''}.\n` +
+      '       The tag would say one version and the files another. Add "version" to the ' +
+      'steps, or release the version already there.',
+  )
 } else if (versionFile) {
   ok(`releasing the version already in ${versionFile.path} (${version})`)
 } else {
@@ -3010,9 +3119,17 @@ if (!runs('release')) {
   if (releaseExists) note(`a GitHub release for ${tag} already exists — will skip that step`)
 }
 
+/**
+ * CLIs that publish over OIDC with no token of their own once the CI job can mint one:
+ * npm, pnpm and bun exchange it with the registry themselves, and so does `uv publish`.
+ * cargo does not — crates.io's trusted publishing goes through an action that turns the
+ * OIDC token into a `CARGO_REGISTRY_TOKEN`, so for cargo the token check still stands.
+ */
+const OIDC_CLIS = new Set([...NPM_CLIS, 'uv'])
+
 /** Whether one publish CLI can publish at all: OIDC, a token, or a live session. */
 function checkCredentials({ cli, registry, command }) {
-  if (isTrustedPublishing) {
+  if (isTrustedPublishing && OIDC_CLIS.has(cli)) {
     ok(`${cli}: trusted publishing (OIDC) — no token needed`)
     // 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
@@ -3236,7 +3353,9 @@ for (const asset of config.assets) {
 const wouldCommit = [
   dirty && runs('commit') && 'the working tree',
   bumping && 'a version bump',
-  rolledChangelog && 'a changelog entry',
+  // The roll is computed whenever [Unreleased] is populated, because the notes come from
+  // it either way; it is only written — and only becomes a commit — when the step runs.
+  rolledChangelog && runs('changelog') && 'a changelog entry',
 ].filter(Boolean)
 if (taggedCommit && runs('tag') && wouldCommit.length) {
   fail(
@@ -3439,15 +3558,37 @@ for (const target of publishTargets) {
 // target published nothing, and telling downstream otherwise is a lie it may act on.
 if (publishedSomething) runHook('afterPublish')
 
+/**
+ * Whether a stable release above this version already exists, anywhere in the
+ * repository — not only in this branch's history, since a patch on an older line is
+ * cut from a branch the newer minor was never merged into.
+ *
+ * GitHub's "Latest" badge is what `releases/latest` resolves to, and `--latest`
+ * forces it. A backport patch that took it would point every "download the latest
+ * release" link at the older line.
+ */
+function supersededByExistingRelease() {
+  const listed = tryRead('git', ['tag', '--list', `${config.tagPrefix}*`]) ?? ''
+  return listed
+    .split('\n')
+    .map((name) => name.trim().slice(config.tagPrefix.length))
+    .filter((v) => parseVersion(v) && !parseVersion(v).pre.length)
+    .some((v) => compareVersions(v, version) > 0)
+}
+
 if (runs('release') && !releaseExists) {
   step(`GitHub release ${tag}`)
+  const latest = !isPrerelease && !supersededByExistingRelease()
+  if (!isPrerelease && !latest) {
+    note(`a newer stable release is already tagged — ${tag} will not be marked Latest`)
+  }
   const args = [
     'release',
     'create',
     tag,
     '--title',
     expand(config.releaseTitle),
-    isPrerelease ? '--prerelease' : '--latest',
+    isPrerelease ? '--prerelease' : `--latest=${latest}`,
     // Notes arrive on stdin, so there is no temp file and nothing to escape.
     ...(notes ? ['--notes-file', '-'] : ['--generate-notes']),
     ...config.assets,

package/train.mjs

@@ -78,6 +78,11 @@ export function parseSemver(version) {
   return { major: +match[1], minor: +match[2], patch: +match[3], prerelease: match[4] ?? null }
 }
 
+/**
+ * Precedence per semver §11, the same ordering release.mjs `compareVersions` applies. It
+ * has to be, because this decides which tag is a package's last release: ranking every
+ * prerelease equal left `rc.9` and `rc.10` in `git tag` order, which is alphabetical.
+ */
 export function compareSemver(a, b) {
   const pa = parseSemver(a)
   const pb = parseSemver(b)
@@ -85,18 +90,45 @@ export function compareSemver(a, b) {
   for (const key of ['major', 'minor', 'patch']) {
     if (pa[key] !== pb[key]) return pa[key] - pb[key]
   }
-  if (pa.prerelease && !pb.prerelease) return -1
-  if (!pa.prerelease && pb.prerelease) return 1
+  if (!pa.prerelease && !pb.prerelease) return 0
+  if (!pa.prerelease) return 1
+  if (!pb.prerelease) return -1
+  const x = pa.prerelease.split('.')
+  const y = pb.prerelease.split('.')
+  for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+    const left = x[i]
+    const right = y[i]
+    if (left === undefined) return -1
+    if (right === undefined) return 1
+    if (left === right) continue
+    const leftNumeric = /^\d+$/.test(left)
+    const rightNumeric = /^\d+$/.test(right)
+    if (leftNumeric && rightNumeric) return Number(left) - Number(right)
+    // Numeric identifiers always have lower precedence than alphanumeric ones.
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1
+    return left < right ? -1 : 1
+  }
   return 0
 }
 
+/**
+ * The bumps a train plans, with release.mjs `incrementVersion`'s arithmetic for them: a
+ * major/minor/patch off a prerelease releases that prerelease's base when the base already
+ * satisfies the bump, so `2.0.0-beta.1` + `patch` is `2.0.0` — not the `2.0.1` a naive
+ * increment gives, which release-kit would then never produce.
+ */
 export function bumpSemver(version, bump) {
   const v = parseSemver(version)
   if (!v) return null
   if (bump === 'as-is') return version
-  if (bump === 'major') return `${v.major + 1}.0.0`
-  if (bump === 'minor') return `${v.major}.${v.minor + 1}.0`
-  return `${v.major}.${v.minor}.${v.patch + 1}`
+  const pre = v.prerelease !== null
+  if (bump === 'major') {
+    return pre && v.minor === 0 && v.patch === 0 ? `${v.major}.0.0` : `${v.major + 1}.0.0`
+  }
+  if (bump === 'minor') {
+    return pre && v.patch === 0 ? `${v.major}.${v.minor}.0` : `${v.major}.${v.minor + 1}.0`
+  }
+  return pre ? `${v.major}.${v.minor}.${v.patch}` : `${v.major}.${v.minor}.${v.patch + 1}`
 }
 
 /**
@@ -339,6 +371,8 @@ export function discover(rootDir, config) {
       repoRelPath: repoDir ? relative(repoDir, dir) || '.' : null,
       publish: entry.publish !== false,
       branch: releaseConfig.branch === undefined ? 'main' : releaseConfig.branch,
+      // The prefix release-kit will tag with, and so the one its history is read under.
+      tagPrefix: releaseConfig.tagPrefix ?? 'v',
       ...manifest,
     })
   }
@@ -416,19 +450,24 @@ export function topoSort(orderEdges) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Tag scheme: `v<version>` when the repo owns exactly one member, `<name>@<version>` when
- * it owns several — which keeps single-package repos identical to standalone release-kit.
+ * Tag scheme: the package's own `tagPrefix` (`v` unless its release.config.json says
+ * otherwise) when the repo owns exactly one member, `<name>@<version>` when it owns
+ * several — which keeps single-package repos identical to standalone release-kit.
  */
 export function tagPatternFor(member, repoMemberCount) {
-  return repoMemberCount > 1
-    ? { prefix: `${member.name}@`, glob: `${member.name}@*` }
-    : { prefix: 'v', glob: 'v*' }
+  if (repoMemberCount > 1) return { prefix: `${member.name}@`, glob: `${member.name}@*` }
+  const prefix = member.tagPrefix ?? 'v'
+  return { prefix, glob: `${prefix}*` }
 }
 
 function lastReleaseTag(member, repoMemberCount) {
   if (!member.repoDir) return null
   const { prefix, glob } = tagPatternFor(member, repoMemberCount)
-  const tags = git(member.repoDir, ['tag', '--list', glob], { allowFailure: true })
+  // `--merged HEAD`, as release.mjs reads it: a tag made on another branch is not this
+  // branch's last release, and the commits it would hide are still unreleased here.
+  const tags = git(member.repoDir, ['tag', '--list', glob, '--merged', 'HEAD'], {
+    allowFailure: true,
+  })
   if (!tags) return null
   const versions = tags
     .split('\n')