@wtf/release-docs 9.0.2 → 10.0.0

package/guides/ecosystems.md

@@ -14,15 +14,21 @@ An ecosystem is a module that reads one kind of manifest, such as npm's `package
   depends on.
 - `satisfies` says whether a version is within a range, by the ecosystem's own rules.
 
-Four ecosystems are built in. Each one has a semantic-release plugin of its own that publishes its
-packages:
-
-| Ecosystem | Package              | Plugin                        | Manifests it reads                                        |
-| --------- | -------------------- | ----------------------------- | --------------------------------------------------------- |
-| `npm`     | `@wtf/release-npm`   | `@wtf/semantic-release-npm`   | each `package.json` that git tracks                       |
-| `cargo`   | `@wtf/release-cargo` | `@wtf/semantic-release-cargo` | the Cargo workspace at the root, through `cargo metadata` |
-| `go`      | `@wtf/release-go`    | `@wtf/semantic-release-go`    | each `go.mod` that git tracks                             |
-| `maven`   | `@wtf/release-maven` | `@wtf/semantic-release-maven` | each `pom.xml` that git tracks                            |
+An ecosystem that releases implements the steps of the contract of `@wtf/release/contract` too:
+`verify`, `prepare`, `smoke`, `publish` and `move`, each optional but `publish`. Any driver runs
+them, a semantic-release plugin, a CLI or a test, over a plan of the packages to publish (see
+[Release the packages](#release-the-packages)).
+
+Five ecosystems are built in, each one releasing by the contract, and each with a semantic-release
+plugin of its own that drives it:
+
+| Ecosystem | Package              | Plugin                        | Manifests it reads                                                                      |
+| --------- | -------------------- | ----------------------------- | --------------------------------------------------------------------------------------- |
+| `npm`     | `@wtf/release-npm`   | `@wtf/semantic-release-npm`   | each `package.json` that git tracks                                                     |
+| `cargo`   | `@wtf/release-cargo` | `@wtf/semantic-release-cargo` | the Cargo workspace at the root, through `cargo metadata`                               |
+| `go`      | `@wtf/release-go`    | `@wtf/semantic-release-go`    | each `go.mod` that git tracks                                                           |
+| `maven`   | `@wtf/release-maven` | `@wtf/semantic-release-maven` | each `pom.xml` that git tracks                                                          |
+| `oci`     | `@wtf/release-oci`   | `@wtf/semantic-release-oci`   | each `Dockerfile`, `Containerfile` or `.devcontainer/devcontainer.json` that git tracks |
 
 ## Name the ecosystems in your config
 
@@ -69,8 +75,8 @@ ecosystem costs a repo nothing. For example, cargo's ecosystem gives no package
   a train (`EDEPENDENCYNOTRAIN`). That train must have released (`EDEPENDENCYNORELEASE`), and one
   of its releases must be within the range (`EDEPENDENCYUNSATISFIED`).
 - **Versions.** A release stamps each range on another train's package with that train's last
-  release, read from the train's tags that `HEAD` holds (`releasedVersions` of
-  `@wtf/release-trains/packages`).
+  release, read from the train's tags that `HEAD` holds. `planOf` of `@wtf/release-trains/plan`
+  gives them in the plan of the train, the version of each package of the repo.
 - **Cascade.** When another train's last release falls outside a range that this train's last
   release published, this train releases again. It releases a major when a major left a `peer`
   range behind, and a patch for any other kind.
@@ -106,8 +112,8 @@ See [Publish npm packages](publishing.md).
 
 `@wtf/release-cargo` reads the Cargo workspace at the root of the repo with
 `cargo metadata --no-deps --format-version 1`. For a commit, it exports the files with
-`git archive` into the system's temporary files, unpacks them with `tar`, reads them, and removes
-them.
+`git archive` into a temporary folder of the platform, unpacks them with `tar`, reads them, and
+removes them.
 
 - **Published:** every crate without `publish = false`.
 - **Kinds:** a normal dependency is `runtime`, a build dependency is `build`, and a dev-dependency
@@ -189,6 +195,24 @@ own.
 So a bare version never causes a cascade, and the release never rewrites a range of your own. See
 [Publish Maven modules](publishing-maven.md).
 
+### OCI images
+
+`@wtf/release-oci` reads each folder of a file an image is built of that git tracks: a
+`Dockerfile`, a `Containerfile`, or a `.devcontainer/devcontainer.json`, which the devcontainer CLI
+builds. A folder of more than one is one image. It reads a commit's files with `git ls-tree`.
+
+- **Name:** the image's repository in its registry: the registry image of the project,
+  `CI_REGISTRY_IMAGE` of a pipeline, for the image at the root, and that and its folder for another.
+  Where the environment names no registry image, the image is named by its folder.
+- **Published:** every image.
+- **Kinds:** none. An image does not depend on another image of the repo as the trains read it: a
+  `FROM` or a base pins a tag of a registry. Order such trains by `dependsOn`.
+- **`resolve`:** the version itself, the tag a release publishes.
+- **`satisfies`:** a tag of the one version it names.
+
+A release copies the image a pipeline tested, by its digest, to the tags of the version, and moves
+the minor and the major of a release. See [Publish OCI images](publishing-oci.md).
+
 ## Write your own ecosystem
 
 Write an ecosystem when your repo holds a kind of package that none of the built-in ecosystems
@@ -196,13 +220,13 @@ reads.
 
 ### The interface
 
-`@wtf/release-trains/ecosystem` declares the interface:
+`@wtf/release/ecosystem` declares the interface:
 
 ```ts fragment
 export interface Ecosystem {
   /** 'npm', 'cargo': as an error, the notes and a key of the trains say it. */
   readonly name: string
-  /** The packages of the repo, of the working tree, or at `context.ref`, by `context.system`. */
+  /** The packages of the repo, of the working tree, or at `context.ref`, of `context.root`. */
   packages(context: EcosystemContext): Promise<readonly Package[]>
   /** The range a release publishes of `range`, of `version`, the release of the package it names. */
   resolve(range: string, version: string): string
@@ -227,8 +251,8 @@ export interface Dependency {
 
 The trains call `packages` for the working tree, with no `ref`. They also call it for a commit, such
 as the tag of a train's last release, which a cascade reads. `packages` does everything through its
-context's `system`, as every library does: files, git, and the ecosystem's own tool. See
-[The system](system.md).
+context, as every library does: the files of the folder of the repo, `root`, and git and the
+ecosystem's own tool by the `platform`. See [The platform](platform.md).
 
 ### An example
 
@@ -237,9 +261,10 @@ of its own, a `release.json` in each folder. The manifest holds a name, a flag t
 package publishes, and dependencies at exact versions:
 
 ```ts
-import { git, gitOf, trackedFiles } from '@wtf/release-system/git'
-import { basenameOf, dirnameOf, joinPath } from '@wtf/release-system/posix'
-import type { Ecosystem, EcosystemContext, Package } from '@wtf/release-trains/ecosystem'
+import { readFile } from '@wtf/release/files'
+import { git, trackedFiles } from '@wtf/release/git'
+import { basenameOf, dirnameOf } from '@wtf/release/posix'
+import type { Ecosystem, EcosystemContext, Package } from '@wtf/release/ecosystem'
 
 /** What a release.json holds. */
 interface Manifest {
@@ -250,8 +275,7 @@ interface Manifest {
 
 /** Each release.json of the repo, of the working tree or of `context.ref`, by git. */
 async function manifestsOf(context: EcosystemContext): Promise<[string, Manifest][]> {
-  const { cwd, system } = gitOf(context)
-  const { ref } = context
+  const { root, ref } = context
   const files = (
     ref === undefined
       ? await trackedFiles(context)
@@ -261,7 +285,7 @@ async function manifestsOf(context: EcosystemContext): Promise<[string, Manifest
     files.map(async (file): Promise<[string, Manifest]> => {
       const text =
         ref === undefined
-          ? await system.fs.readFile(joinPath(cwd, file))
+          ? await readFile(root, file)
           : await git(['show', `${ref}:${file}`], context)
       return [file, JSON.parse(text) as Manifest]
     })
@@ -306,16 +330,29 @@ export default ecosystem
   such as `1.5.0-beta.1` for `^1.4.0`, because the trains release prereleases on their channels.
 - **No manifest means no package.** In a repo without any of the ecosystem's manifests, return `[]`
   rather than fail. A config can then name the ecosystem before the first manifest exists.
-- **Always use the system.** Do not use `node:*`, `process` or the global `fetch`. Everything the
-  module does outside itself goes through `context.system`. The trains can then run it on a CLI's
-  system, or on a test's system in memory.
+- **Always use the context.** Do not use `node:*`, `process` or the global `fetch`. Everything the
+  module does outside itself goes through `context.root` and `context.platform`. The trains can
+  then run it on a CLI's platform, or on a test's platform and folder in memory.
+
+### Release the packages
 
-### Publish the packages
+To release its packages too, the ecosystem implements `ReleasingEcosystem` of
+`@wtf/release/contract`, of options of its own: `publish`, and the steps of `verify`, `prepare`,
+`smoke` and `move` that fit it. Each step takes the `Release` (the version, the folder of the repo,
+the platform, whether it is a dry run, and where to log), the `Plan` of the ecosystem (its packages
+to publish, in order, and the version of each package of the repo), and its options. It knows no
+train: a driver gives it the plan, as `planOf` of `@wtf/release-trains/plan` works one out for a
+train, and runs a step of every ecosystem by `runStep` of `@wtf/release/driver`. The test ecosystem
+of `@wtf/release` (`packages/release/test/contract.test.ts`) implements every step, and each
+built-in library one, as the guide of each shows.
 
-The ecosystem does not publish. Write a semantic-release plugin for that, as
-`@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and
-`@wtf/semantic-release-maven` are. The plugin:
+A semantic-release plugin over it, as `@wtf/semantic-release-npm`, `-cargo`, `-go`, `-maven` and
+`-oci` are:
 
 - reads `trains`, `ecosystems` and `train` from the root of the config;
-- finds its train's packages with `ownersOf` from `@wtf/release-trains/packages`;
-- reads the other trains' versions with `releasedVersions`, which throws the trains' errors.
+- works out the plan of its train with `planOf`, which throws the trains' errors;
+- runs each step of the ecosystem in its step of semantic-release, on the platform and the folder of
+  the run that `runOf` of `@wtf/semantic-release` gives, marking the errors that leave it by
+  `markedStep`;
+- records what `publish` published for the links of the release, by `recordReleased` of
+  `@wtf/semantic-release/links`.

package/guides/getting-started.md

@@ -18,14 +18,15 @@ other train first.
 ## Which packages it releases
 
 An **ecosystem** tells the trains how to read one kind of package: where its manifests are, what it
-depends on, and what a version range means. Four ecosystems are built in, and one repo can mix them:
+depends on, and what a version range means. Five ecosystems are built in, and one repo can mix them:
 
-| Ecosystem | Manifests                       | Plugin                        | Guide                                          |
-| --------- | ------------------------------- | ----------------------------- | ---------------------------------------------- |
-| npm       | each `package.json`             | `@wtf/semantic-release-npm`   | [Publish npm packages](publishing.md)          |
-| Cargo     | the Cargo workspace at the root | `@wtf/semantic-release-cargo` | [Publish Cargo crates](publishing-crates.md)   |
-| Go        | each `go.mod`                   | `@wtf/semantic-release-go`    | [Publish Go modules](publishing-go-modules.md) |
-| Maven     | each `pom.xml`                  | `@wtf/semantic-release-maven` | [Publish Maven modules](publishing-maven.md)   |
+| Ecosystem | Manifests                                                               | Plugin                        | Guide                                          |
+| --------- | ----------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------- |
+| npm       | each `package.json`                                                     | `@wtf/semantic-release-npm`   | [Publish npm packages](publishing.md)          |
+| Cargo     | the Cargo workspace at the root                                         | `@wtf/semantic-release-cargo` | [Publish Cargo crates](publishing-crates.md)   |
+| Go        | each `go.mod`                                                           | `@wtf/semantic-release-go`    | [Publish Go modules](publishing-go-modules.md) |
+| Maven     | each `pom.xml`                                                          | `@wtf/semantic-release-maven` | [Publish Maven modules](publishing-maven.md)   |
+| OCI       | each `Dockerfile`, `Containerfile` or `.devcontainer/devcontainer.json` | `@wtf/semantic-release-oci`   | [Publish OCI images](publishing-oci.md)        |
 
 You can also write an ecosystem of your own for any other kind of package. See
 [How ecosystems work](ecosystems.md).
@@ -35,28 +36,33 @@ You can also write an ecosystem of your own for any other kind of package. See
 wtf release has two layers:
 
 - **Libraries** do the work. They do not depend on semantic-release or on any other release tool.
-  Each function takes the `system` it runs on from its caller, so you can also run the libraries
-  from a CLI or a script of your own. See [The system](system.md).
+  Each function takes the folder of the repo and the platform it runs on from its caller, so you
+  can also run the libraries from a CLI or a script of your own. See [The platform](platform.md).
 - **Plugins** let semantic-release run the libraries. Each plugin is a thin adapter over its
   library.
 
 The libraries:
 
-- `@wtf/release-system` is the base of the other libraries: the system, paths and globs, git,
-  option validators and `ReleaseError`. It knows nothing about trains.
+- `@wtf/release` is the base of the other libraries: the platform they run on, the files of the
+  repo, programs, paths and globs, git, option validators and `ReleaseError`. It knows nothing about
+  trains.
 - `@wtf/release-trains` handles the trains: their commits, their checks, and the folders a build
   generates.
-- `@wtf/release-npm`, `@wtf/release-cargo`, `@wtf/release-go` and `@wtf/release-maven` are the
-  four ecosystems. Each one also publishes the train's packages of its kind.
+- `@wtf/release-npm`, `@wtf/release-cargo`, `@wtf/release-go`, `@wtf/release-maven` and
+  `@wtf/release-oci` are the five ecosystems. Each one also publishes the train's packages of its
+  kind.
 - `@wtf/release-replace` replaces text in files, such as the version in a badge.
 - `@wtf/release-validate` validates a config with any Standard Schema.
 
 The plugins:
 
+- `@wtf/semantic-release` is what every plugin shares: it makes Node's platform and the folder of
+  the repo for a run, and marks the libraries' errors for semantic-release.
 - `@wtf/semantic-release-trains` checks the trains, gives a plugin it wraps only the train's
   commits, and stages the folders a build generates.
-- `@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and
-  `@wtf/semantic-release-maven` publish the train's packages of one ecosystem.
+- `@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go`,
+  `@wtf/semantic-release-maven` and `@wtf/semantic-release-oci` publish the train's packages of one
+  ecosystem.
 - `@wtf/semantic-release-replace` replaces text in files during a release.
 - `@wtf/semantic-release-validate` validates the config of a run with a schema of your own.
 
@@ -104,15 +110,14 @@ The examples in these guides use the trains that this repo releases its own pack
 
 | Train      | Folders                                                           |
 | ---------- | ----------------------------------------------------------------- |
-| `system`   | `packages/release-system`                                         |
+| `release`  | `packages/release`, `packages/semantic-release`                   |
 | `trains`   | `packages/release-trains`, `packages/semantic-release-trains`, …  |
 | `replace`  | `packages/release-replace`, `packages/semantic-release-replace`   |
 | `validate` | `packages/release-validate`, `packages/semantic-release-validate` |
 | `docs`     | `packages/docs`                                                   |
 
-`@wtf/release-trains` and `@wtf/release-replace` list `@wtf/release-system`, so `trains` and
-`replace` depend on `system`. `validate` depends on no other train. The docs package lists every
-package, so `docs` releases last.
+Each library lists `@wtf/release`, and each plugin `@wtf/semantic-release`, so `trains`, `replace`
+and `validate` depend on `release`. The docs package lists every package, so `docs` releases last.
 
 Each example shows only the trains it needs. The repo's own `release.config.mjs` declares them all,
 and tags each one `<train>-v<version>`. Here is a config with two trains:
@@ -189,7 +194,7 @@ releases nothing:
 RELEASE_TRAIN=trains npx semantic-release --dry-run --no-ci
 ```
 
-Release a train that another train depends on first, such as `system` before `trains`. The plugin
+Release a train that another train depends on first, such as `release` before `trains`. The plugin
 warns you when a dependency train has commits that it has not released. See
 [Trains that depend on other trains](dependency-rules.md).
 
@@ -211,7 +216,7 @@ copy of each package that it packs. See [Publish npm packages](publishing.md).
   train's tag on your host.
   Wrapped in the trains plugin, `@semantic-release/gitlab` links each package that the release
   published. See [The links of the release](publishing.md#the-links-of-the-release).
-- [The system](system.md): run the libraries on a system of your own.
+- [The platform](platform.md): run the libraries on a platform of your own.
 
 ## Make the first release
 

package/guides/platform.md

@@ -0,0 +1,179 @@
+# The platform
+
+Read this page when you want to run the libraries outside semantic-release, from a CLI of your own,
+or in tests. You can also use it to change how the plugins run programs.
+
+Every function of the libraries, such as `@wtf/release-trains`, `@wtf/release-npm` and
+`@wtf/release-replace`, reaches the outside world through two things its caller gives it:
+
+- `root`, the folder of the repo. It is a `FileSystemDirectoryHandle` of the File System standard,
+  so it can be a folder on disk, a folder in memory, or a browser's.
+- `platform`, what runs programs, fetches and makes temporary folders. It is a part of the platform
+  of [`@wtf/platform`](https://www.npmjs.com/package/@wtf/platform), picked to what the function
+  uses.
+
+The types come from `@wtf/release`, the base that the other libraries build on. A function requires
+them from its caller and never makes them itself. None of the library modules names Node. Each
+caller passes what fits it:
+
+- A semantic-release plugin passes Node's platform and the folder of the run.
+- A CLI passes Node's, or a platform of its own.
+- A test passes a platform and a folder in memory.
+
+Each function takes only what it uses:
+
+| It takes          | What it holds                                                                                               | Which functions take it                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `root` alone      | The folder of the repo.                                                                                     | A function that only reads or writes files of the repo.           |
+| `RepoPlatform`    | `spawn`, which starts a program, `env`, the environment a program gets, and `dirs.cwd`, the working folder. | A function that runs git, or another program of the repo.         |
+| `ReleasePlatform` | A `RepoPlatform`, with `fetch`, and `path`, `navigator`, `crypto` and `dirs.temp` for temporary folders.    | A release that fetches, or stages what it packs outside the repo. |
+
+`platform.dirs.cwd` is the path of the folder that `root` is the handle of, and programs run there.
+`RepoContext` holds the two together, `{ root, platform }`:
+
+```ts
+import type { RepoContext } from '@wtf/release'
+import { readFile } from '@wtf/release/files'
+import { run } from '@wtf/release/process'
+
+/** The name of the root package, and the commit of the working tree. */
+export async function describe({ root, platform }: RepoContext) {
+  const { name } = JSON.parse(await readFile(root, 'package.json')) as { name: string }
+  const { stdout } = await run(platform, 'git', ['rev-parse', 'HEAD'])
+  return `${name}@${stdout.trim()}`
+}
+```
+
+`@wtf/release/files` reads and writes the files of a folder by their paths from it, with `/`:
+`readFile`, `readBytes`, `writeFile`, `exists`, `readDir`, `makeDir`, `remove` and `copy`.
+`@wtf/release/posix` joins paths without a platform.
+
+`run` of `@wtf/release/process` runs a program in the folder of the repo, or in a folder of it, and
+returns `{ stdout, stderr, code }`. The program gets the platform's `env`, or the environment you
+give it whole; `envOf` makes one of the platform's with variables of your own. A non-zero exit code
+is not a failure of `run` itself, and the caller decides what it means. `run` rejects only when the
+program cannot start.
+
+## Use Node's platform
+
+A CLI or a script on Node makes Node's platform with `nodePlatform` of
+`@wtf/platform-node/platform`, and the folder of the repo with `nodeDirectory` of
+`@wtf/platform-fs-node/handles`. Node's platform works in `process.cwd()` and gives each program
+`process.env`:
+
+```ts
+import type { ReleasePlatform } from '@wtf/release'
+import { readWorkspace } from '@wtf/release-npm/workspace'
+import { nodeDirectory } from '@wtf/platform-fs-node/handles'
+import { nodeStorage } from '@wtf/platform-fs-node/storage'
+import { nodePlatform } from '@wtf/platform-node/platform'
+
+const platform: ReleasePlatform = nodePlatform({
+  fetch: (input, init) => fetch(input, init),
+  storage: nodeStorage()
+})
+const root = await nodeDirectory(platform.dirs.cwd)
+
+export const packages = await readWorkspace(root)
+```
+
+## Write a platform of your own
+
+A CLI gives each function the platform it runs on, so it can change any member of it. This example
+logs each program before it runs:
+
+```ts
+import type { ReleasePlatform, RepoContext } from '@wtf/release'
+import npm from '@wtf/release-npm'
+import { verifyTrain } from '@wtf/release-trains/verify'
+
+/** A platform whose programs are logged before they run, over the one a CLI has. */
+export const logged = (platform: ReleasePlatform): ReleasePlatform => ({
+  ...platform,
+  spawn: (command, args, options) => {
+    console.error(`$ ${command} ${args.join(' ')}`)
+    return platform.spawn(command, args, options)
+  }
+})
+
+export function check({ root, platform }: RepoContext<ReleasePlatform>) {
+  return verifyTrain({
+    trains: {
+      validate: { paths: ['packages/release-validate', 'packages/semantic-release-validate'] }
+    },
+    train: 'validate',
+    ecosystems: [npm],
+    root,
+    platform: logged(platform)
+  })
+}
+```
+
+## The platform of the plugins
+
+Each plugin makes Node's platform and the folder of the repo for the run, with `runOf` of
+`@wtf/semantic-release`. It makes them from the folder and the environment that semantic-release
+gives each step, `cwd` and `env`, which the plugin requires. It passes them to every call into its
+library, so each program runs in that folder and with that environment.
+
+A plugin knows it runs on Node, and a library does not: a library always takes the platform it is
+given and assumes none. So a plugin has no option of its platform, and lays nothing over Node's. To
+change what the programs of a release see, change the environment of the run, as the variables of
+its job: `GIT_TERMINAL_PROMPT=0` stops every program of the release from asking for a password.
+
+A test of a plugin that runs it on a platform in memory mocks `@wtf/platform-node/platform`, as
+Vitest's `vi.mock` does, so the plugin's Node's platform is the test's.
+
+## Errors
+
+The libraries throw plain errors: each is a `ReleaseError` of `@wtf/release/errors`, or of a class
+of its package that extends it, with a stable code, a message of what is wrong, and details of how
+to fix it. They know nothing of the tool that prints them.
+
+A plugin marks them as they leave each of its steps, with `markedStep` of
+`@wtf/semantic-release/errors`, so that semantic-release prints each by its code, its message and
+its details. A CLI of your own prints them its own way:
+
+```ts
+import { isReleaseError } from '@wtf/release/errors'
+
+/** An error as a CLI prints it: its code and how to fix it, of a release's. */
+export const printed = (error: unknown): string =>
+  isReleaseError(error) ? `${error.code}: ${error.message}\n${error.details}` : String(error)
+```
+
+## Use a platform in tests
+
+A platform with scripted programs and a folder in memory run the libraries with no disk and no git.
+`memoryPlatform` of `@wtf/platform-memory/platform` answers each program by a script, and records
+each it runs. `memoryDirectory` of `@wtf/platform-fs-memory/handles` is a disk in memory:
+
+```ts
+import { testDirs } from '@wtf/platform/dirs'
+import { memoryDirectory } from '@wtf/platform-fs-memory/handles'
+import { memoryPlatform } from '@wtf/platform-memory/platform'
+import { makeDir, writeFile } from '@wtf/release/files'
+import npm from '@wtf/release-npm'
+
+// A disk in memory, of the folder of the repo, /repo, and a temporary folder, /tmp.
+const disk = memoryDirectory()
+const root = await makeDir(disk, 'repo')
+await makeDir(disk, 'tmp')
+await writeFile(root, 'package.json', '{ "name": "repo", "private": true }')
+await writeFile(root, 'packages/core/package.json', '{ "name": "@acme/core" }')
+
+// git lists the files it tracks. Any other program is not there, as of a command not found.
+const platform = memoryPlatform({
+  dirs: testDirs({ cwd: '/repo', temp: '/tmp' }),
+  directory: () => disk,
+  spawn: (command, args) =>
+    command === 'git' && args[0] === 'ls-files'
+      ? { stdout: 'package.json\0packages/core/package.json\0' }
+      : undefined
+})
+
+export const names = async () => (await npm.packages({ root, platform })).map(({ name }) => name) // ['repo', '@acme/core']
+
+// Each program that ran: [{ command: 'git', args: ['ls-files', '-z'], … }]
+export const runs = () => platform.spawn.runs
+```

package/guides/publishing-crates.md

@@ -94,21 +94,57 @@ and at the commit of a train's last release. For that commit, they export the fi
 
 ## What a release does
 
-1. **`verifyConditions`** checks the options and reads the workspace with `cargo metadata`. It
-   selects the crates that the release publishes and puts them in dependency order. It reads each
-   other train's last release from its tags. It checks the credentials. A workspace that cannot be
+The plugin maps each step of semantic-release onto a step of the cargo ecosystem, the contract of
+[`@wtf/release`](../../release/README.md). It gives the ecosystem the release, of the next
+release's version, and the train's plan: the train's crates that publish, in dependency order, and
+the version of each crate of the workspace, the release's for the train's crates and each other
+train's last release for that train's crates.
+
+1. **`verifyConditions`** checks the options and works out the plan, which reads the workspace with
+   `cargo metadata` and each other train's last release from its tags. A workspace that cannot be
    published fails here, before the tag (see
    [When crates depend on other trains](#when-crates-depend-on-other-trains)).
-2. **`prepare`** writes the versions into the manifests: the release's version into the train's
-   crates, and each other train's last release into that train's crates and into each dependency on
-   them. It then reads the workspace again. A crate that is not at its train's version fails the run
-   (see [What the stamp does not read](#what-the-stamp-does-not-read)).
-3. **`publish`** asks the registry's sparse index which crates it already has, and skips them. It
-   publishes the rest in dependency order with `cargo publish`. cargo waits for each crate to appear
-   in the index before the next one, so the crates of a release can install each other.
-
-A dry run of semantic-release runs only `verifyConditions`. It writes no version and publishes
-nothing.
+2. **`verifyRelease`** runs the ecosystem's `verify` once semantic-release knows the version: it
+   checks the version, the crates that the release publishes, of `include` and `exclude`, their
+   order, and the credentials.
+3. **`prepare`** runs the ecosystem's `prepare`, which writes the plan's versions into the
+   manifests: the release's version into the train's crates, and each other train's last release
+   into that train's crates and into each dependency on them. It then reads the workspace again. A
+   crate that is not at its train's version fails the run (see
+   [What the stamp does not read](#what-the-stamp-does-not-read)).
+4. **`publish`** runs the ecosystem's `publish`. It asks the registry's sparse index which crates
+   it already has, and skips them. It publishes the rest in the plan's order with `cargo publish`.
+   cargo waits for each crate to appear in the index before the next one, so the crates of a
+   release can install each other.
+
+A dry run of semantic-release runs only `verifyConditions` and `verifyRelease`. It writes no
+version and publishes nothing.
+
+### Without semantic-release
+
+The ecosystem knows no train and no release tool, so any driver can release the crates: give it a
+release and a plan, and run its steps, as with `runStep` of `@wtf/release/driver`. A dry run
+(`dryRun: true`) writes and publishes nothing: `prepare` gives the manifests it would write, and
+`publish` only asks the registry.
+
+```ts
+import type { Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import { publishOrder } from '@wtf/release/order'
+import cargo from '@wtf/release-cargo'
+
+/** Every crate of the workspace that publishes, at the version of the release, but the docs. */
+export async function releaseCrates(release: Release) {
+  const packages = await cargo.packages(release)
+  const { order } = publishOrder(packages.filter(({ published }) => published))
+  const versions = new Map(order.map(({ name }) => [name, release.version]))
+  const plans = new Map([['cargo', { own: order, versions }]])
+  const ecosystems = [[cargo, { exclude: ['docs'] }]] as const
+  await runStep(release, plans, ecosystems, 'verify')
+  await runStep(release, plans, ecosystems, 'prepare')
+  return (await runStep(release, plans, ecosystems, 'publish')).released
+}
+```
 
 ## When crates depend on other trains
 
@@ -210,7 +246,10 @@ no release publishes it.
   before the tag with `EDEPENDENCYNORELEASE`.
 - **`publish = false` on what is not published.** Mark an example or a test crate of the workspace
   this way. Otherwise the train whose paths hold it publishes it. You can also leave a crate of the
-  train out with `exclude`, which names only crates of the train (`ECRATES`).
+  train out with `exclude`, which names only crates of the train, or crates that publish nowhere
+  (`ECRATES`). A crate with `publish = false` that a train's paths hold is stamped at the
+  train's version all the same, with its dependencies on published crates, so `cargo publish
+  --workspace` and the smoke, which build every member, resolve it.
 
 ## Authenticate to the registry
 
@@ -220,9 +259,9 @@ uses:
 - an ID token of the job, in `CRATES_IO_ID_TOKEN` by default (`idToken` names another variable);
 - a token, in `CARGO_REGISTRY_TOKEN`.
 
-With both, the plugin uses the ID token and the log says so. With neither, `verifyConditions` fails
-with `ECRATEAUTH` before the tag. A dry run only warns, because semantic-release runs only
-`verifyConditions` in a dry run.
+With both, the plugin uses the ID token and the log says so. With neither, `verifyRelease` fails
+with `ECRATEAUTH` before the tag. A dry run only warns so, because semantic-release runs neither
+`prepare` nor `publish` in a dry run.
 
 ### Trusted publishing
 
@@ -265,6 +304,8 @@ The plugin does the rest:
 - When the job ends, even when it fails, the plugin revokes the token (`DELETE` on the same URL). A
   failed revoke is logged and fails nothing, because the token expires by itself.
 - The tokens appear in no log and no error.
+- Each request to the registry names the library, `@wtf/release-cargo`, as its user agent, as
+  crates.io asks every client to name itself.
 
 A registry other than crates.io that offers the same exchange takes its API as `registryApi`, with
 its `registry` and its `index`: