@entro314labs/release-kit 2.8.0 → 2.9.0

package/README.md

@@ -10,7 +10,7 @@
 [![downloads](https://img.shields.io/npm/dm/@entro314labs/release-kit?color=cb3837)](https://www.npmjs.com/package/@entro314labs/release-kit)
 [![unpacked size](https://img.shields.io/npm/unpacked-size/@entro314labs/release-kit?color=blueviolet)](https://www.npmjs.com/package/@entro314labs/release-kit?activeTab=code)
 [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#-requirements)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2018-339933?logo=node.js&logoColor=white)](#-requirements)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022-339933?logo=node.js&logoColor=white)](#-requirements)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
@@ -56,6 +56,7 @@ Released v2.5.0
 | [⚡ 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           |
+| [🪝 Hooks](#-hooks)                                                     | commands between the steps              |
 | [🤖 Assistant](#-assistant-optional)                                    | optional AI drafting                    |
 | [🌍 Any language](#-any-language)                                       | Rust, Python, tag-only, anything        |
 | [🚂 Release trains](#-release-trains)                                   | monorepos and multi-repo workspaces     |
@@ -126,7 +127,7 @@ Pin the URL to a tag, never `main`: piping an unpinned remote script into an int
 means whatever is at that URL runs against your repository and your credentials. `--sync` is
 the one thing that does not work this way — copying itself needs a file on disk.
 
-> **All five paths run the same file and need Node 18+.** That includes the Rust, Python and
+> **All five paths run the same file and need Node 22+.** That includes the Rust, Python and
 > Go projects: `release-kit` is a Node program regardless of what it is releasing.
 
 Zero-config works on the conventions below; add a [`release.config.json`](#️-configuration)
@@ -143,6 +144,16 @@ pnpm release -- --dry-run         # print every step, execute nothing
 pnpm release -- --help
 ```
 
+`next` answers "what version would this release?" and stops. Only the version reaches
+stdout, so it substitutes into a command; everything it would otherwise narrate goes to
+stderr, where a human still reads it.
+
+```sh
+release-kit next            # the version already in the manifest
+release-kit next minor      # what a minor bump would release
+release-kit next auto       # what the commits imply — the same inference the release uses
+```
+
 The target is optional. With no target it releases whatever version `package.json`
 already says — which is the mode to use when a version bump landed in an earlier commit.
 
@@ -231,7 +242,7 @@ them execute, it never reorders them.
 | `version`   | on      | Write the version into `package.json` and `versionFiles`                                           |
 | `changelog` | on      | Roll `[Unreleased]` into the version, or add drafted notes                                         |
 | `tag`       | on      | Annotated git tag carrying the release notes                                                       |
-| `push`      | on      | Push the branch and tag together (`--follow-tags`)                                                 |
+| `push`      | on      | Push the branch and tag as one transaction (`--follow-tags --atomic`)                              |
 | `publish`   | on      | Run the configured `publish` command                                                               |
 | `release`   | on      | Create the GitHub release                                                                          |
 
@@ -275,10 +286,24 @@ Notes resolve in this order:
    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.
+   A **New Contributors** section names anyone whose first commit to the repository is in
+   this release — derived from the git history rather than a forge API, so it needs no
+   token and works offline, and it is skipped on a first release where everyone would be
+   new. 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.
 
+**Which tag the history is read from** is the highest version tag carrying the configured
+prefix that is reachable from `HEAD` — not the nearest tag. A repository carrying tags that
+are not releases (a rolling `latest-beta` marker, a `nightly`) is unaffected by them, and a
+patch tagged on top of a later minor does not drag the baseline backwards.
+
+**A stable release absorbs the candidates that led to it.** Releasing `2.0.0` after
+`2.0.0-rc.1` and `-rc.2` reads history from the last _stable_ tag, so the notes describe
+everything the release ships rather than the gap between the last two candidates — which
+is usually just the release commit. Releasing a candidate is unchanged: each one's notes
+say what changed in that candidate.
+
 `--notes <source>` forces one instead of walking that list: `changelog`, `assistant`,
 `commits`, or `github`. A named source that produces nothing is an error rather than a
 quiet fall-through — asking for one thing and being given another is worse than being told
@@ -290,6 +315,14 @@ does not make it preferred, because a hand-written changelog entry should still
 The same text becomes the tag annotation, the GitHub release body, and (when rolled) the
 changelog entry. It is written once and lands in three places.
 
+**Keep a Changelog link definitions are maintained.** `## [1.2.3]` is a markdown link
+_reference_, and renders as literal bracketed text without a matching definition at the
+foot of the file. Every bracketed heading in the document gets one — not just the version
+being released — so a changelog that never had them is repaired in one release: each
+version compares against the version below it, the oldest links to its own tag, and
+`[Unreleased]` compares the newest version against `HEAD`. Definitions for labels that are
+not headings are left alone, since those are yours.
+
 ### npm dist-tags
 
 The [dist-tag](https://docs.npmjs.com/cli/commands/npm-dist-tag) is derived from the
@@ -358,24 +391,26 @@ Only one step is Node-specific: `publish`. Committing, changelog rolling, taggin
 and GitHub releases are the same everywhere, so `versionFile` points at wherever a project
 keeps its version and the rest works unchanged.
 
-| Project                        | Config                                                                          |
-| ------------------------------ | ------------------------------------------------------------------------------- |
-| Node (npm)                     | nothing — `package.json` and `npm publish` are the defaults                     |
-| Node (pnpm / bun)              | `{"publish": "pnpm publish --tag %d"}` or `{"publish": "bun publish --tag %d"}` |
-| Rust                           | `{"versionFile": "Cargo.toml", "publish": "cargo publish"}`                     |
-| Python                         | `{"versionFile": "pyproject.toml", "publish": "uv publish"}`                    |
-| Go                             | `{"versionFile": null, "publish": "go list -m %n@%t"}` — the tag is the release |
-| Anything with a `VERSION` file | `{"versionFile": "VERSION", "publish": null}`                                   |
-| Versioned only by tag          | `{"versionFile": null}`, then `release-kit 1.2.3`                               |
+| Project                        | Config                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------- |
+| Node (npm)                     | nothing — `package.json` and `npm publish` are the defaults                            |
+| Node (pnpm / bun)              | `{"publish": "pnpm publish --tag %d"}` or `{"publish": "bun publish --tag %d"}`        |
+| Rust                           | nothing — `Cargo.toml` and `cargo publish` are detected                                |
+| Rust + npm (a Tauri plugin)    | nothing — both manifests bump, both registries publish                                 |
+| Python                         | `{"versionFile": "pyproject.toml", "publish": "uv publish"}`                           |
+| Go                             | `{"publish": "go list -m %n@%t"}` — the tag is the release; a `version.go` is detected |
+| Anything with a `VERSION` file | `{"versionFile": "VERSION", "publish": null}`                                          |
+| Versioned only by tag          | `{"versionFile": null}`, then `release-kit 1.2.3`                                      |
 
 The publish step also gets a preflight when the command is one it recognises:
 
-| Publish command | Authentication                        | Already published?                  |
-| --------------- | ------------------------------------- | ----------------------------------- |
-| `npm` / `pnpm`  | `whoami`                              | `view <name>@<version>`             |
-| `bun`           | `bun pm whoami`                       | `bun pm view <name>@<version>`      |
-| `uv`            | `UV_PUBLISH_TOKEN` in the environment | none — `uv` skips duplicates itself |
-| `go`            | none needed                           | `go list -m <module>@<tag>`         |
+| Publish command | Authentication                                              | Already published?                  |
+| --------------- | ----------------------------------------------------------- | ----------------------------------- |
+| `npm` / `pnpm`  | `whoami`                                                    | `view <name>@<version>`             |
+| `bun`           | `bun pm whoami`                                             | `bun pm view <name>@<version>`      |
+| `uv`            | `UV_PUBLISH_TOKEN` in the environment                       | none — `uv` skips duplicates itself |
+| `cargo`         | `CARGO_REGISTRY_TOKEN`, or `cargo login`'s credentials file | `cargo info <crate>@<version>`      |
+| `go`            | none needed                                                 | `go list -m <module>@<tag>`         |
 
 Anything else runs as written with no preflight. The project name comes from the manifest —
 `name` in `package.json`, `Cargo.toml` or `pyproject.toml`, `module` in `go.mod` — falling
@@ -384,7 +419,95 @@ 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.
+to the wrong registry is a far worse failure than being asked to configure it. A manifest
+that forbids publishing is honoured: a `"private": true` package.json, a crate with
+`publish = false`, and a crate built only as a `cdylib` — a native extension module rather
+than a library — get no command at all.
+
+### One repository, two registries
+
+A Tauri plugin is a crate and its npm bindings built from one source tree; a maturin
+project is a crate and a wheel. Both manifests sit at the repository root and carry the
+same version, and both publish on the same release. That needs no config:
+
+```
+tauri-plugin-demo/
+  package.json     @tauri-apps/plugin-demo   1.4.0
+  Cargo.toml       tauri-plugin-demo         1.4.0
+  Cargo.lock
+```
+
+```sh
+release-kit minor --yes
+#   also versioned in Cargo.toml, Cargo.lock (detected)
+#   publish: npm publish --tag latest
+#   publish: cargo publish
+```
+
+The second manifest is detected only when it **already carries the same version**. Two
+manifests on different numbers are two independent release lines, and dragging one to the
+other's number is a silent, wrong release — that case says so and leaves the file alone,
+pointing at `versionFiles` for a project that really does want them joined. A project that
+wrote its own `versionFile` or `versionFiles` is never extended behind its back.
+
+`publish` therefore takes an array as well as a string, for any project releasing to more
+than one registry:
+
+```json
+{ "publish": ["npm publish --tag %d", "cargo publish"] }
+```
+
+They run in order, each with its own authentication check and its own already-published
+check, so a re-run after a half-finished publish completes the other half instead of
+failing. The detected order puts npm before cargo deliberately: npm allows an unpublish for
+72 hours and crates.io never does, so a publish that fails part-way through has not already
+made the permanent half.
+
+Names are resolved per registry rather than once: the crate is looked up under the `name`
+in `Cargo.toml`, not the npm package name, since `@tauri-apps/plugin-demo` and
+`tauri-plugin-demo` are the same release under two names.
+
+### Languages that have no version of their own
+
+A Go module has only `go.mod`, and `go.mod` carries no version — `go get` resolves a tag.
+The same is true of a Swift package or a plain C library. There is nothing to bump, so the
+tag is the version and `versionFile` resolves to `null` on its own.
+
+Those projects still usually keep a number in source, so `mytool --version` prints
+something:
+
+```go
+package main
+
+const Version = "1.2.0"
+```
+
+`version.go`, `internal/version/version.go` and `pkg/version/version.go` are detected and
+rewritten on release, with no config — `const Version`, `var Version` and
+`var Version string` are all read. The tag stays the source of truth; the constant is a
+mirror kept in step with it.
+
+Detection adopts a file only when it **already carries the current version**. That rules
+out the placeholder a build replaces at link time:
+
+```go
+var Version = "dev"   // -ldflags "-X main.Version=$(git describe)" — left alone
+```
+
+A mismatch here is skipped silently rather than warned about, because a placeholder is a
+normal thing to find rather than a mistake — unlike two manifests on different versions.
+
+For a constant somewhere else, or in a language whose convention is not in that list, name
+it with a `pattern`:
+
+```json
+{
+  "versionFiles": [{ "path": "src/version.h", "pattern": "^#define VERSION \"(.+)\"" }]
+}
+```
+
+`versionFiles` is written whether or not the project has a `versionFile`, so this works for
+a repository that versions by tag alone.
 
 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
@@ -398,8 +521,60 @@ because the TOML match is anchored to the start of a line, a dependency's
 
 **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.
+unrelated crate. Listing one rewrites only the `[[package]]` blocks this project owns: the
+crate named in the sibling `Cargo.toml`, or — for a workspace root, which has no
+`[package]` of its own — every member that inherits the version with
+`version.workspace = true`. A member pinned to its own number is versioned separately and
+is left alone. With nothing beside it to read, it refuses rather than guesses.
+
+`package-lock.json`, `npm-shrinkwrap.json` and `uv.lock` record the project's own version
+too, and are refreshed by the tool that owns them rather than rewritten by pattern — the
+version sits in more than one place and the formats change shape between tool versions.
+Each is scoped to its manifest, so a `uv.lock` for a component this release is not
+versioning stays out of the release commit, and a missing tool warns rather than aborting.
+`pnpm-lock.yaml` records no root version, so it never goes stale.
+
+### Marking the line instead of writing a pattern
+
+The files that most want keeping in step — a README install line, a badge URL, a
+Dockerfile tag — are the ones where a regex is fiddliest to get right. A comment on the
+line says which of a file's numbers is the version, so nothing outside the file has to
+describe where it sits:
+
+````md
+Install with `npm i acme@1.2.3` <!-- x-release-kit-version -->
+
+```dockerfile
+FROM acme:1.2   # x-release-kit-minor
+```
+````
+
+`-major`, `-minor`, `-patch`, `-date` and `-version-date` write a piece of the release
+instead of the whole version — `-version-date` covers both on one line, which is the shape
+of an AppStream `<release version="…" date="…"/>` tag — and `x-release-kit-start-<scope>` … `x-release-kit-end` covers a run of lines
+rather than commenting each one. Just list the file:
+
+```json
+{ "versionFiles": ["README.md", "Dockerfile"] }
+```
+
+A file listed with no marker, no `pattern` and no recognised extension is treated as
+containing nothing but the version — right for a `VERSION` file, and refused for anything
+else rather than replacing its contents with the number.
+
+**Paths may contain `*`**, matching within one path segment, so the per-platform configs a
+desktop app carries do not have to be written out one by one:
+
+```json
+{ "versionFiles": ["src-tauri/tauri.*.conf.json"] }
+```
+
+A pattern matching no files aborts: it was written to keep files in step, and silently
+keeping none of them in step is the failure it was meant to prevent. A file the glob
+matched that carries no version is skipped, though — a glob says "every file of this
+shape", and some of them legitimately have none, as a Tauri per-OS overlay does. A file
+you named on purpose is different: being unable to write it fails preflight, before
+anything mutates.
 
 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:
@@ -419,10 +594,7 @@ in one release, across three formats, with no scripting:
 {
   "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/tauri.*conf.json",
     "apps/desktop/src-tauri/Cargo.toml",
     "apps/desktop/src-tauri/Cargo.lock"
   ],
@@ -431,6 +603,10 @@ in one release, across three formats, with no scripting:
 }
 ```
 
+The glob covers `tauri.conf.json` and every per-OS overlay beside it, including ones added
+later — and the overlays that carry no `version` of their own are skipped rather than
+failing the release.
+
 Stopping at `push` because the tag is what triggers the build pipeline — see
 [Libraries versus apps](#-libraries-versus-apps).
 
@@ -459,22 +635,23 @@ 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`  | `[]`                     | Further files kept in sync; a path or `{ path, pattern }`             |
-| `publish`       | `"npm publish --tag %d"` | Publish command; `null` means none is configured                      |
-| `versioning`    | `"conventional"`         | How `auto` infers; or `always-patch` / `-minor` / `-major`            |
-| `verify`        | `null`                   | Command run during preflight; non-zero aborts before anything mutates |
-| `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 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                                  |
 
 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
@@ -599,6 +776,40 @@ A project releasing off a non-default branch with a different tag scheme:
 }
 ```
 
+## 🪝 Hooks
+
+`verify` covers the gate that matters most — the project's own tests, run during preflight
+before anything mutates. What it cannot express is work that has to happen _between_ the
+release's own steps.
+
+```json
+{
+  "hooks": {
+    "afterVersion": "cargo build --release",
+    "beforePublish": "pnpm build",
+    "afterRelease": "curl -X POST -d 'shipped %t' https://hooks.example/deploy"
+  }
+}
+```
+
+| Hook            | Runs                                                    |
+| --------------- | ------------------------------------------------------- |
+| `beforeVersion` | After preflight, before any file is written             |
+| `afterVersion`  | After the version is on disk, before the release commit |
+| `beforePublish` | After the tag is pushed, before anything is published   |
+| `afterPublish`  | After a publish actually ran                            |
+| `afterRelease`  | After the GitHub release is created                     |
+
+Each takes a command line or an array of them, expanding the same `%v` `%t` `%n` `%d`
+tokens `publish` does, shell-quoted on substitution. A non-zero exit aborts the release
+where it happened. An unknown hook name aborts rather than silently never running.
+
+`afterVersion` sits where it does for a reason: **anything it changes is staged for the
+release commit**, so a file regenerated from the version rides in that commit instead of
+being left behind in the working tree. `afterPublish` runs only when a publish actually
+happened, so a re-run that skipped an already-published target does not tell something
+downstream a lie it may act on.
+
 ## 🤖 Assistant (optional)
 
 An assistant is an AI CLI already installed on your machine. When one is configured,
@@ -757,7 +968,7 @@ including a directory that is not a repository.
 
 ## 📋 Requirements
 
-- **Node 18+ — including for Rust, Python and Go projects.** `release-kit` is a Node
+- **Node 22+ — including for Rust, Python and Go projects.** `release-kit` is a Node
   program whatever it releases; there is no standalone binary.
 - `git`
 - `gh`, authenticated — only when creating GitHub releases
@@ -773,7 +984,7 @@ with the reasoning — are in [ROADMAP.md](ROADMAP.md).
 
 ```sh
 pnpm install
-pnpm test     # 63 tests, node --test, no framework
+pnpm test     # 188 tests, node --test, no framework
 pnpm check    # format + lint + tests, the same gate CI runs
 ```
 

package/TRAIN.md

@@ -269,6 +269,19 @@ Seeding refuses, per member and without touching it, when:
 The orchestrator's graph is built from npm-style manifests today. Non-npm members still
 participate:
 
+- **Rust**: `Cargo.toml` versions and `cargo publish`, both already handled per package.
+  What the orchestrator would additionally need is the range rewrite: a crate depending on
+  a sibling by `path` also carries a `version` for it, and crates.io rejects a publish
+  whose path dependency has no version — so the dependent's manifest must move to the
+  dependency's new number before it publishes. release-please's `cargo-toml.ts` is the
+  worked reference: it rewrites `version` under `dependencies`, `dev-dependencies`,
+  `build-dependencies` and every `target.<cfg>` table, skipping entries with no `path`
+  (a real crates.io dependency, not a sibling) and no `version` (a path-only dependency,
+  which needs nothing). Workspace inheritance moves the problem rather than removing it:
+  `version.workspace = true` in a member points at `[workspace.package]`, which is one
+  place to rewrite instead of many. Not built in `release.mjs`, where a single package has
+  no internal ranges to rewrite and the code would have no caller.
+
 - **Go**: no manifest version; the tag is the release. release-kit already handles it
   (`versionFile: null`). It has no npm-visible dependents, so no registry wait.
 - **Python / PHP**: `pyproject.toml` / `composer.json` versions, publish via the package's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.8.0",
+  "version": "2.9.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",