@wtf/release-docs 9.0.2 → 10.0.0

package/guides/publishing-go-modules.md

@@ -10,7 +10,9 @@ or `v<version>` for a module at the root. The Go proxy reads the module from tha
 publishes a module by pushing its tag.
 
 The plugin runs on the library [`@wtf/release-go`](../../release-go/README.md). The library's
-default export is the Go ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+default export is the Go ecosystem, which reads the modules of a repo and releases them in the steps
+of [`@wtf/release`](../../release/README.md)'s contract, and the plugin exports the same ecosystem
+at `./ecosystem`. Add
 `'@wtf/semantic-release-go/ecosystem'` to `ecosystems` in your config. The trains then treat modules
 the same way as npm packages: they decide which train holds each module, the order of the trains,
 the checks of a release, and the releases a train owes the trains it depends on. See
@@ -102,18 +104,24 @@ workflow:
 
 ## What a release does
 
-1. **`verifyConditions`** checks the options and reads the go.mod files that git tracks. It selects
-   the modules that the release tags, and reads each other train's last release from its tags. A
-   repo that cannot be released fails here, before the tag (see
+Each step of semantic-release runs a step of the Go ecosystem over the plan of the train: the
+modules of the train that Go can fetch, and the version of each module of the repo.
+
+1. **`verifyConditions`** checks the options and reads the go.mod files that git tracks. It works
+   out the plan of the train, which reads each other train's last release from its tags, and selects
+   the modules that the release tags. A repo that cannot be released fails here, before the tag (see
    [When modules depend on other trains](#when-modules-depend-on-other-trains)).
-2. **`verifyRelease`** checks each module's path against the major of the release's version
-   (`EGOMAJOR`; see [Release a new major](#release-a-new-major)).
-3. **`prepare`** checks the majors again and writes the versions into the go.mod files. It writes
+2. **`verifyRelease`** runs the ecosystem's `verify`. It checks that the version is one Go tags a
+   module of (`EGOSEMVER`), and each module's path against the major of the version (`EGOMAJOR`;
+   see [Release a new major](#release-a-new-major)).
+3. **`prepare`** runs the ecosystem's `prepare`, which writes the versions into the go.mod
+   files. It writes
    the release's version into each require of a module of the train, and each other train's last
    release into each require of that train's modules, in every go.mod of the repo. Then it reads the
    files again, and a require that is not at its train's version fails the run (`EGOVERSION`; see
    [What the release changes in go.mod](#what-the-release-changes-in-gomod)).
-4. **`publish`** commits the changed go.mod files and tags that commit with each module's tag (see
+4. **`publish`** runs `publish`, which commits the changed go.mod files and tags that commit with
+   each module's tag (see
    [Tag a commit that holds the versions](#tag-a-commit-that-holds-the-versions)). It skips each tag
    the remote already has. With `proxy`, it then asks the Go proxy for each module.
 
@@ -132,7 +140,8 @@ tag. The branch, the index and the working tree stay as they are; only the tags
 
 - The commit message is `chore(release): Go modules of <train> <version>`.
 - The author comes from `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL`, and the committer from
-  `GIT_COMMITTER_*`. Without them, both are `semantic-release-bot`.
+  `GIT_COMMITTER_*`. Without them, both are `semantic-release-bot`. The plugin gives the library
+  this author: the library itself has none, and a caller of its own names one.
 - When no go.mod changed, as for modules that require no other module of the repo, the plugin tags
   the release commit itself.
 
@@ -190,8 +199,8 @@ From v2 on, Go holds the major in the module path: `example.com/repo/core/v2`. A
 `/vN` needs a release of major N. A release of major 2 or higher needs a path that ends in its
 major.
 
-The plugin checks this in `verifyRelease`, once semantic-release knows the version, and again in
-`prepare`. So a breaking change to a module whose path has no `/v2` fails before anything is tagged
+The plugin checks this in `verifyRelease`, once semantic-release knows the version. So a breaking
+change to a module whose path has no `/v2` fails before anything is tagged
 (`EGOMAJOR`). The error names the go.mod to change. In the commit of the breaking change:
 
 1. Write `module example.com/repo/core/v2` in that go.mod.
@@ -276,3 +285,38 @@ Before it creates anything, the plugin asks the remote for every tag. It skips e
 has, and pushes the rest in one atomic push: all of them or none. So retry the tag's job to create
 the missing tags. A remote that cannot be asked stops the run before anything is created
 (`EGOTAG`).
+
+## Release Go modules without semantic-release
+
+The Go ecosystem knows no train and no release tool. Any caller can release modules with it: give
+it a release, a plan, and its options, and run its steps, one by one or through `runStep` of
+`@wtf/release/driver`. The plan says which modules the release tags (`own`) and the version that
+each module of the repo is required at (`versions`). `@wtf/release-trains/plan` works out the plan
+of a train, or you can write one by hand.
+
+```ts
+import type { Plan, Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import go from '@wtf/release-go'
+
+declare const release: Release
+declare const plan: Plan
+
+const plans = new Map([['go', plan]])
+const ecosystems = [
+  [
+    go,
+    {
+      remote: 'origin',
+      author: { name: 'Release Bot', email: 'release-bot@example.com' },
+      proxy: true
+    }
+  ]
+] as const
+await runStep(release, plans, ecosystems, 'verify')
+await runStep(release, plans, ecosystems, 'prepare')
+export const { released } = await runStep(release, plans, ecosystems, 'publish')
+```
+
+`publish` needs `remote` and `author`, unless the release is a dry run (`EGOTAG`). A dry run writes
+no go.mod, creates no commit and no tag, and asks the proxy nothing: it says the tags it would push.

package/guides/publishing-maven.md

@@ -110,20 +110,26 @@ nor a JDK, because the trains read the poms with git.
 
 ## What a release does
 
+The plugin works out the plan of the train: the modules it deploys, and the version of each module
+of the repo. Then each step of semantic-release runs a step of the Maven ecosystem, `verify`,
+`prepare` or `publish`, over that plan, and what it says and throws names the train (see [Without semantic-release](#without-semantic-release)).
+
 1. **`verifyConditions`** checks the options and reads the poms. It selects the modules that the
    release deploys and puts them in dependency order. It reads each other train's last release from
-   its tags, and finds each module's repository. A repo that cannot be deployed fails here, before
-   the tag (see [When modules depend on other trains](#when-modules-depend-on-other-trains)).
-2. **`prepare`** writes the versions into the poms: the release's version into the train's poms,
-   and each other train's last release into that train's poms. It also writes them into the
-   parents, dependencies and plugins that name those modules. Then it reads the poms again, and a
-   module that is not at its train's version fails the run (see
-   [What the stamp writes](#what-the-stamp-writes)).
-3. **`publish`** asks each module's repository whether it has the module's pom, and skips each one
+   its tags (see [When modules depend on other trains](#when-modules-depend-on-other-trains)).
+2. **`verifyRelease`** checks the release's version by Maven's rules once semantic-release knows
+   it: a version that ends in `SNAPSHOT`, or holds a space or a character Maven bans, fails with
+   `EMAVENVERSION`. It finds each module's repository. A repo that cannot be deployed fails here,
+   before the tag.
+3. **`prepare`** checks the version again, and writes the versions into the poms: the release's
+   version into the train's poms, and each other train's last release into that train's poms. It also writes them into the parents, dependencies and plugins
+   that name those modules. Then it reads the poms again, and a module that is not at its train's
+   version fails the run (see [What the stamp writes](#what-the-stamp-writes)).
+4. **`publish`** asks each module's repository whether it has the module's pom, and skips each one
    it has. It deploys the rest in dependency order.
 
-A dry run of semantic-release runs only `verifyConditions`. It writes no version and deploys
-nothing.
+A dry run of semantic-release runs only `verifyConditions` and `verifyRelease`. It writes no
+version and deploys nothing.
 
 ### How a module is deployed
 
@@ -136,6 +142,36 @@ from the root of the repo, after the modules it depends on.
   as a test kit with `maven.deploy.skip`. The plugin installs such a module into the local
   repository first.
 
+### Without semantic-release
+
+The library releases the modules of any plan, with no train and no release tool. Its default export
+is a `ReleasingEcosystem` of `@wtf/release/contract`, so `runStep` of `@wtf/release/driver` runs its
+steps. A plan names the modules to deploy, in order, and the version each module of the repo takes:
+
+```ts
+import type { Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import maven from '@wtf/release-maven'
+import { publishOrder, readModules, selectArtifacts } from '@wtf/release-maven/artifacts'
+
+/** Every module of the repo that deploys, at the version of the release. */
+export async function releaseAll(release: Release) {
+  const modules = await readModules(release)
+  const names = new Set(modules.map(({ name }) => name))
+  const own = publishOrder(selectArtifacts(modules, { train: names }))
+  const versions = new Map(modules.map(({ name }) => [name, release.version]))
+  const plans = new Map([['maven', { own, versions }]])
+  const ecosystems = [[maven, { args: ['-s', 'ci_settings.xml'] }]] as const
+  await runStep(release, plans, ecosystems, 'verify')
+  await runStep(release, plans, ecosystems, 'prepare')
+  return (await runStep(release, plans, ecosystems, 'publish')).released
+}
+```
+
+The options are the plugin's `repository`, `lookup`, `lookupAuth`, `command` and `args`, and
+`installs`, the modules to install before the ones that need them. A dry run of the release writes
+and deploys nothing.
+
 ## When modules depend on other trains
 
 A repo can be released in several trains. Each train has its own modules, version and tags, and its
@@ -174,6 +210,8 @@ The trains run the same checks for every ecosystem. They run in `verifyCondition
 - A module of the release that depends on a module of a train with no release fails with
   `EDEPENDENCYNORELEASE`.
 - A module that the paths of two trains hold fails with `ETRAINOVERLAP`.
+- A module of the release whose range no release of the other train satisfies fails with
+  `EDEPENDENCYUNSATISFIED` (see [Versions and ranges](#versions-and-ranges)).
 
 In the first two cases there is no version that a repository could serve, so the release never
 deploys the placeholder. A dependency in the `test` scope is not a fault, because no consumer

package/guides/publishing-oci.md

@@ -0,0 +1,134 @@
+# Publish OCI images
+
+[`@wtf/semantic-release-oci`](../../semantic-release-oci/README.md) releases the OCI images of a repo
+that belong to a train: container images, built by Docker, buildah or the devcontainer CLI. Use it
+when a train holds images, alone or beside npm packages and crates in the same release. They share
+one version and one train tag, and a retry finishes a release that stopped.
+
+A release never rebuilds an image. The pipeline of the tag builds and tests each image, as it does
+on every branch; the release then copies that tested image, by its digest, to the tags of its
+version. The bytes released are the bytes tested, and a consumer pins a version, or a major that
+moves, instead of a commit.
+
+The plugin runs on the library [`@wtf/release-oci`](../../release-oci/README.md). The library's
+default export is the OCI ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+`'@wtf/semantic-release-oci/ecosystem'` to `ecosystems` in your config. The trains then treat images
+the same way as npm packages: they decide which train holds each image, the order of the trains,
+and the checks of a release. See [How ecosystems work](ecosystems.md).
+
+## Turn it on
+
+### Build and test each image in the pipeline of the tag
+
+An image is each folder that holds a `Dockerfile`, a `Containerfile` or a
+`.devcontainer/devcontainer.json` that git tracks. The pipeline of the tag builds it, tests it, and
+pushes it as a snapshot before the release publishes: the plugin copies that snapshot. By default it
+is `<image>/snapshot:<CI_COMMIT_REF_SLUG>`, as the devcontainer component of
+[wetryfun/devops/components](https://gitlab.com/wetryfun/devops/components) pushes it. Another
+pipeline names its own with `sourceRepository` and `sourceTag`.
+
+### Add the OCI ecosystem and the plugin
+
+An image belongs to the train whose `paths` hold its folder. Its repository in the registry is the
+registry image of the project, `CI_REGISTRY_IMAGE` of a pipeline, for an image at the root, and
+that and its folder for another, as `registry.gitlab.com/acme/images/base` of a folder `base`.
+
+```js norun
+// release.config.mjs
+export default {
+  trains: { base: { paths: ['base'] }, release: { paths: ['release'] } },
+  ecosystems: ['@wtf/semantic-release-oci/ecosystem'],
+  train: process.env.RELEASE_TRAIN,
+  tagFormat: `${process.env.RELEASE_TRAIN}-v\${version}`,
+  plugins: [
+    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/commit-analyzer' }],
+    ['@wtf/semantic-release-oci', { platforms: ['linux/amd64'] }],
+    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/gitlab' }]
+  ]
+}
+```
+
+### Log crane in
+
+The plugin runs [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md),
+which copies a digest from one repository to another by mounting its blobs, with no docker and no
+pull. Put crane on the path of the release job and log it in to the registry, as in a pipeline of
+GitLab:
+
+```sh
+echo "$CI_REGISTRY_PASSWORD" | crane auth login --username "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+```
+
+## What a release does
+
+In the run of the tag, `verifyRelease` and `publish` run the steps of the OCI ecosystem of
+`@wtf/release-oci` over the images of the train:
+
+1. `verifyRelease` checks the version and the tags that move, each a tag an image can have, once
+   semantic-release knows the version;
+2. finds the snapshot of each image of the train by its digest, `crane digest`, and the platforms of
+   its index, `crane manifest`. A snapshot the registry has not, or of fewer platforms than
+   `platforms` names, fails the release (`EOCISMOKE`) before anything is copied;
+3. checks the tag of the version: a registry that has it at the same digest skips it, and at another
+   digest refuses the release (`EOCIRETAG`). A released version never moves;
+4. copies the snapshot to the version, and then points the minor and the major, which move, at the
+   digest of the version:
+
+| Version        | Tags                |
+| -------------- | ------------------- |
+| `1.4.2`        | `1.4.2`, `1.4`, `1` |
+| `0.3.1`        | `0.3.1`, `0.3`      |
+| `8.0.0-next.1` | `8.0.0-next.1`      |
+
+5. links each image from the GitLab release of the tag to its page in the container registry of the
+   project, which the Container Registry API names (`EOCILINK`). An image is linked where it lives,
+   never uploaded.
+
+A release that stopped part way is finished by a retry of its job: the version the registry has at
+the same digest is skipped, and the moving tags are copied again.
+
+## Release images without semantic-release
+
+The OCI ecosystem is a `ReleasingEcosystem` of `@wtf/release/contract`, so any driver releases
+images by it, as a CLI that releases an image of Debian 12.12 as `12.12-wtf.1`, `12.12` and
+`latest`. It takes the version and the tags that move as they are given, and derives none:
+
+```ts
+import type { Plan, Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import oci from '@wtf/release-oci'
+
+export async function releaseImages(release: Release, plan: Plan, snapshot: string) {
+  const plans = new Map([['oci', plan]])
+  const options = {
+    moving: ['12.12', 'latest'],
+    source: { repository: '{image}/snapshot', tag: snapshot }
+  }
+  for (const step of ['verify', 'publish', 'move'] as const)
+    // oxlint-disable-next-line no-await-in-loop -- one step after another
+    await runStep(release, plans, [[oci, options]], step)
+}
+```
+
+See [the library's README](../../release-oci/README.md) for each step and its options.
+
+## Label an image of its version
+
+A release stamps nothing into an image: what was tested ships. A pipeline that labels an image of
+the version it will be, as `org.opencontainers.image.version`, reads the next version of its train
+of the dotenv that `semantic-release-info` writes, and passes it to its build as an argument of its
+own.
+
+## Errors
+
+| Code            | What to do                                                                     |
+| --------------- | ------------------------------------------------------------------------------ |
+| `EOCIECOSYSTEM` | Add `'@wtf/semantic-release-oci/ecosystem'` to `ecosystems`                    |
+| `EOCIIMAGE`     | Run the release in a pipeline of GitLab, or give the plugin `image`            |
+| `EOCISOURCE`    | Run the release in the pipeline of its tag, or give the plugin `sourceTag`     |
+| `EOCIVERSION`   | Release a version that is a tag of an image, as `1.4.2`                        |
+| `EOCISMOKE`     | Build and push the snapshot before the release, and log crane in               |
+| `EOCIRETAG`     | Release a new version: the registry has this one at another digest             |
+| `EOCITAG`       | Give crane a token that may write the repository, and retry the job            |
+| `EOCIMOVE`      | Publish the version first: the tags that move point at it                      |
+| `EOCILINK`      | Give the run a token that may read the registry of the project, `GITLAB_TOKEN` |

package/guides/publishing.md

@@ -45,21 +45,21 @@ The plugin does not create the release on GitLab or GitHub. List `@semantic-rele
 `@semantic-release/github` after it. Wrapped in the trains plugin, `@semantic-release/gitlab` links each
 package that the release published: see [The links of the release](#the-links-of-the-release).
 
-| Option       | Default                                  | What it does                                                                                                                                                                                                         |
-| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `publisher`  | `npm`                                    | The tool that publishes: `npm`, `pnpm`, the path of a module, or a package name. See [Publishers](#publishers).                                                                                                      |
-| `access`     | each package's `publishConfig.access`    | `public` or `restricted`.                                                                                                                                                                                            |
-| `provenance` | `auto`                                   | Whether to publish with provenance: `auto` (when the CI provides an ID token), `true` or `false`.                                                                                                                    |
-| `registry`   | each package's `publishConfig.registry`  | The registry to publish to.                                                                                                                                                                                          |
-| `first`      | none                                     | The folder of the package to publish first.                                                                                                                                                                          |
-| `last`       | none                                     | The folder of the package to publish last.                                                                                                                                                                           |
-| `conditions` | `['source']`                             | The export conditions that point at source files. No tarball ships them.                                                                                                                                             |
-| `check`      | `true`                                   | Check the packages before the first publish. See [What the check catches](#what-the-check-catches).                                                                                                                  |
-| `aside`      | none                                     | Package names to publish under their major's line when their dist-tag points above the release: `release-<major>.x` in place of `latest`, `<dist-tag>-<major>.x` in place of another.                                |
-| `tarballDir` | a folder in the system's temporary files | Where to keep the tarballs after the release, for the links of a package in `pack` or on a registry with no page. Add a folder in the repo to `.gitignore`. A CI job starts with it empty.                           |
-| `pack`       | none                                     | Folders or globs of private packages in the train. The plugin packs them into `tarballDir` beside the others and never publishes them. The GitLab release links each one's tarball. Use it for a demo.               |
-| `distTag`    | the channel's                            | One dist-tag for every package, in place of the channel's, for a one-off release. An empty string means no override.                                                                                                 |
-| `smoke`      | `false`                                  | `true`, or `{ forbid }` with globs that no tarball may hold. Installs each packed package as a consumer would, in `prepare`, before the tag. See [Smoke-test the packages](#smoke-test-the-packages-before-the-tag). |
+| Option       | Default                                 | What it does                                                                                                                                                                                                         |
+| ------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `publisher`  | `npm`                                   | The tool that publishes: `npm`, `pnpm`, the path of a module, or a package name. See [Publishers](#publishers).                                                                                                      |
+| `access`     | each package's `publishConfig.access`   | `public` or `restricted`.                                                                                                                                                                                            |
+| `provenance` | `auto`                                  | Whether to publish with provenance: `auto` (when the CI provides an ID token), `true` or `false`.                                                                                                                    |
+| `registry`   | each package's `publishConfig.registry` | The registry to publish to.                                                                                                                                                                                          |
+| `first`      | none                                    | The folder of the package to publish first.                                                                                                                                                                          |
+| `last`       | none                                    | The folder of the package to publish last.                                                                                                                                                                           |
+| `conditions` | `['source']`                            | The export conditions that point at source files. No tarball ships them.                                                                                                                                             |
+| `check`      | `true`                                  | Check the packages before the first publish. See [What the check catches](#what-the-check-catches).                                                                                                                  |
+| `aside`      | none                                    | Package names to publish under their major's line when their dist-tag points above the release: `release-<major>.x` in place of `latest`, `<dist-tag>-<major>.x` in place of another.                                |
+| `tarballDir` | a temporary folder of the platform      | Where to keep the tarballs after the release, for the links of a package in `pack` or on a registry with no page. Add a folder in the repo to `.gitignore`. A CI job starts with it empty.                           |
+| `pack`       | none                                    | Folders or globs of private packages in the train. The plugin packs them into `tarballDir` beside the others and never publishes them. The GitLab release links each one's tarball. Use it for a demo.               |
+| `distTag`    | the channel's                           | One dist-tag for every package, in place of the channel's, for a one-off release. An empty string means no override.                                                                                                 |
+| `smoke`      | `false`                                 | `true`, or `{ forbid }` with globs that no tarball may hold. Installs each packed package as a consumer would, in `prepare`, before the tag. See [Smoke-test the packages](#smoke-test-the-packages-before-the-tag). |
 
 ### Provenance
 
@@ -87,39 +87,45 @@ JSON leaves out, and the channel's dist-tag applies.
 
 ## What a release does
 
-A release runs three steps. Each step is a function of `@wtf/release-npm/release`.
+The plugin runs on the steps of the npm ecosystem of `@wtf/release-npm`, each over the plan of the
+train. The plan is the train's packages that publish, in order, and the version of each package of
+the repo that a range resolves to. `planOf` from `@wtf/release-trains/plan` works it out:
 
-1. **Resolve the manifests** (`resolveManifests`). The plugin finds the train's packages that
-   publish: every package under the train's `paths` that is not private. It finds them the way the
-   package manager does, by the globs in `pnpm-workspace.yaml` or in the `workspaces` field of
-   `package.json`. It orders them so that each package comes after the packages it runs with
-   (`dependencies`, `peerDependencies` and `optionalDependencies`). `first` and `last` pin a package
-   to either end. Then it builds each manifest as it will publish:
+- It finds the train's packages that publish: every package under the train's `paths` that is not
+  private. It finds them the way the package manager does, by the globs in `pnpm-workspace.yaml`
+  or in the `workspaces` field of `package.json`.
+- It orders them so that each package comes after the packages it runs with (`dependencies`,
+  `peerDependencies` and `optionalDependencies`). `first` and `last` pin a package to either end.
+- Each package in the same train gets the release's version. Each package in another train gets
+  that train's last release, which `planOf` reads from the tags. A train's cascade reads the same
+  tags.
+
+Then the steps of the library, each a function of `@wtf/release-npm/release`, release the plan:
+
+1. **Resolve the manifests** (`resolvePlan`). The library builds each manifest as it will publish:
    - The version is the release's version.
-   - Each `workspace:` range on a package in the same train resolves to that version, the way pnpm
-     resolves `workspace:*`, `workspace:^` and `workspace:~`.
-   - Each `workspace:` range on a package in another train resolves to that train's last release,
-     which the plugin reads from the tags. `releasedVersions` from `@wtf/release-trains/packages`
-     and `resolveSpecifier` from `@wtf/release-npm/manifests` do this, and a train's cascade reads
-     the same functions.
-   - The plugin drops a devDependency whose `workspace:` range points at a package that no train
-     releases, such as a private package of shared configs, or at a train with no release yet. No
-     consumer installs a devDependency.
-   - The plugin strips each export that points at source: the `source` condition, or a `.ts`
+   - Each `workspace:` range resolves to the version of the plan of the package it names, the way
+     pnpm resolves `workspace:*`, `workspace:^` and `workspace:~` (`resolveSpecifier` from
+     `@wtf/release-npm/manifests`).
+   - The library drops a devDependency whose `workspace:` range points at a package of no version
+     in the plan, such as a private package of shared configs, or of a train with no release yet.
+     No consumer installs a devDependency.
+   - The library strips each export that points at source: the `source` condition, or a `.ts`
      target.
 
    Then it checks each manifest. This step writes nothing.
 
-2. **Pack the tarballs** (`packTrain`). The plugin copies each package, without its `node_modules`,
-   into a folder in the system's temporary files. It writes the resolved manifest into the copy and
-   packs the copy there. It packs every package before the first publish, so a fault stops the run
-   before anything reaches the registry.
+2. **Pack the tarballs** (`packRelease`). The library copies each package, without its
+   `node_modules`, into a temporary folder of the platform. It writes the resolved manifest into the
+   copy and packs the copy there. It packs every package before the first publish, so a fault stops
+   the run before anything reaches the registry.
 
-3. **Publish** (`publishTrain`). The plugin publishes each package under the dist-tag of the
-   release's channel. That is `latest`, or `beta` for `2.1.0-beta.3`, or `prerelease` for
-   `2.1.0-0`. A channel that npm would read as a range, such as `1.x` on a maintenance branch,
-   becomes `release-1.x`. The plugin adds provenance where the CI provides an ID token, and skips
-   each version that the registry already has.
+3. **Publish** (`publishPacked`). The library publishes each package under the first dist-tag the
+   plugin gives it, `moving`, which the plugin derives from the release's channel. That is
+   `latest`, or `beta` for `2.1.0-beta.3`, or `prerelease` for `2.1.0-0`. A channel that npm would
+   read as a range, such as `1.x` on a maintenance branch, becomes `release-1.x`. The library adds
+   provenance where the CI provides an ID token, and skips each version that the registry already
+   has.
 
 ### When a dist-tag would move back
 
@@ -137,25 +143,29 @@ release, the run fails too. A release whose channel is a line already, such as `
 
 ### Which semantic-release step does what
 
-The plugin implements the same steps as `@semantic-release/npm`:
+The plugin implements the same steps as `@semantic-release/npm`. Each maps onto a step of the
+library:
 
-- `verifyConditions` checks the publisher and the packages as they are in the repo.
-- `prepare` runs steps 1 and 2 and asks the registry, all before the tag. These faults fail the run
-  here:
+- `verifyConditions` checks its options and the publisher, and the packages as they are in the repo
+  (`checkPlan`, the library's `verify` but of the version, which semantic-release has not yet).
+- `verifyRelease` runs the library's `verify`, which checks the version once semantic-release knows
+  it, and the packages of the train.
+- `prepare` runs the library's `prepare`, steps 1 and 2, which asks the registry too, and, with
+  `smoke`, its `smoke`, all before the tag. These faults fail the run here:
   - a range that no release satisfies (`EDEPENDENCYUNSATISFIED`);
   - a dependency on a train with no release (`EDEPENDENCYNORELEASE`);
   - a dependency on a package of no train (`EDEPENDENCYNOTRAIN`);
   - a package that cannot be packed;
   - a release that would move a dist-tag back (`EPUBLISHBEHIND`).
-- `publish` runs step 3 with what `prepare` packed, after the tag is pushed. It returns the release
-  to semantic-release as the stock plugin does: the publisher's name and its packages, the page of
-  the first package, and the channel. Then it removes the copies and the tarballs. With
-  `tarballDir`, it keeps the tarballs. If `publish` finds nothing packed for its train and version
-  in the same process, it resolves and packs again.
-- `addChannel` moves a published release to the dist-tag of its new channel, by `tagTrain`.
-  semantic-release asks for this when you merge a branch of one channel into the branch of another.
-  The plugin runs `npm dist-tag add` for each package of the train that the registry has at the
-  version, with either built-in publisher.
+- `publish` runs the library's `publish`, step 3, with what `prepare` packed, after the tag is
+  pushed. It returns the release to semantic-release as the stock plugin does: the publisher's name
+  and its packages, the page of the first package, and the channel. Then it removes the copies and
+  the tarballs. With `tarballDir`, it keeps the tarballs. If `publish` finds nothing packed for its
+  train and version in the same process, it resolves and packs again.
+- `addChannel` moves a published release to the dist-tag of its new channel, by the library's
+  `move` (`moveRelease`). semantic-release asks for this when you merge a branch of one channel into
+  the branch of another. The plugin runs `npm dist-tag add` for each package of the train that the
+  registry has at the version, with either built-in publisher.
 
 npm moves a dist-tag only with the token in its config. Its trusted publishing covers
 `npm publish` and no other command, so a release from a channel branch needs `NPM_TOKEN` too. A
@@ -182,8 +192,8 @@ tries the private packages of `pack` too. It does this with `smokePacked` from
 - **In the tarball:** an entry of `files` that the tarball does not hold, as when a package was
   packed without a build; an export with a source condition; a file that matches `forbid`, such as
   `**/*.tsbuildinfo`.
-- **In the install:** npm installs the package in a project of its own in the system's temporary
-  files. Every other packed package installs from its tarball through npm's `overrides`, so npm does
+- **In the install:** npm installs the package in a project of its own in a temporary folder of
+  the platform. Every other packed package installs from its tarball through npm's `overrides`, so npm does
   not ask the registry for any of them.
 - **In the imports:** the plugin imports each entry of `exports`, except `./package.json` and
   patterns. It reports a `SyntaxError`, a module not found that is neither an optional peer in the
@@ -302,31 +312,38 @@ commits on top. See [Run releases in CI](ci-recipes.md#gitlab-ci).
 
 ## Use the steps as a library
 
-The three steps are functions of `@wtf/release-npm/release` and need no release tool. Each step runs
-on the `system` that its caller passes, as a CLI passes its own system adapted to the interface:
+The steps are those of the npm ecosystem, the default export of `@wtf/release-npm`, and need no
+release tool and no train. Each step takes the release, the plan and the options of the library.
+The release carries the folder of the repo and the platform that its caller passes, as a CLI passes
+its own (see [The platform](platform.md)). The plan is the packages that publish, in order, and the
+version of each package of the repo. The options name `moving`, the dist-tags a publish puts the
+version under, which npm always publishes under one of. `runStep` from `@wtf/release/driver` runs a
+step of each ecosystem of a release:
 
 ```ts
-import type { System } from '@wtf/release-system/system'
-import { packTrain, publishTrain, resolveManifests } from '@wtf/release-npm/release'
-
-export async function release(system: System, version: string) {
-  const resolved = await resolveManifests({
-    trains: { trains: { paths: ['packages/release-trains', 'packages/release-trains-*'] } },
-    train: 'trains',
-    version,
-    system
-  })
-  const packed = await packTrain(resolved, { system })
-  try {
-    return await publishTrain(packed, { system, dryRun: true })
-  } finally {
-    await packed.cleanup()
-  }
+import type { Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import npm from '@wtf/release-npm'
+
+export async function release(at: Release) {
+  const own = (await npm.packages(at)).filter(
+    ({ dir, published }) => published && dir.startsWith('packages/')
+  )
+  const versions = new Map(own.map(({ name }) => [name, at.version]))
+  const plans = new Map([['npm', { own, versions }]])
+  const ecosystems = [[npm, { moving: ['next'] }]] as const
+  await runStep(at, plans, ecosystems, 'verify')
+  await runStep(at, plans, ecosystems, 'prepare')
+  const { released } = await runStep(at, plans, ecosystems, 'publish')
+  return released
 }
 ```
 
-`releaseTrain` runs all three in one call, the way a job in the tag's pipeline publishes its
-release. See [Publish from the tag pipeline](ci-recipes.md#publish-from-the-tag-pipeline).
+The plan here is every package of the repo under `packages/` that publishes, in the order the
+ecosystem reads them. A driver that publishes in order of the dependencies works the order out by `publishOrder`
+from `@wtf/release/order`, as `planOf` does. See [Publish from the tag
+pipeline](ci-recipes.md#publish-from-the-tag-pipeline) for the run of a release in the tag's
+pipeline.
 
 ## Publishers
 
@@ -356,7 +373,8 @@ A publisher can also have these optional members:
   as `options.tarball`.
 - `page`: it returns a package's page, which the plugin passes to semantic-release as the release's
   URL.
-- `tag`: it points a dist-tag at a version the registry has, for `addChannel` and `tagTrain`.
+- `tag`: it points a dist-tag at a version the registry has, for `addChannel` and the library's
+  `move`.
   Without it, a release cannot move to another channel.
 
 The plugin does not check whether a `lookup` without `tagged` would move a dist-tag back.
@@ -385,13 +403,14 @@ registry:
 
 ```js train=trains
 // release/yarn-publisher.mjs
+import { run } from '@wtf/release/process'
 import { npmPublisher } from '@wtf/release-npm/publishers'
 
 /** @type {import('@wtf/release-npm').Publisher} */
 export default {
   name: 'yarn',
   lookup: npmPublisher.lookup,
-  async publish(pkg, options, { system, env, dryRun, memo }) {
+  async publish(pkg, options, { platform, dryRun, memo }) {
     // The npm lookup keeps what it asked in the step's store: a publisher forgets what it changes.
     memo?.clear()
     if (dryRun) return
@@ -402,7 +421,7 @@ export default {
       options.tag,
       ...(options.access ? ['--access', options.access] : [])
     ]
-    const { code, stderr } = await system.exec('yarn', args, { cwd: pkg.dir, env })
+    const { code, stderr } = await run(platform, 'yarn', args, { cwd: pkg.dir })
     if (code !== 0) throw new Error(stderr)
   }
 }
@@ -446,18 +465,20 @@ echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authTo
 
 ```js train=trains
 // release/jsr-publisher.mjs
+import { run } from '@wtf/release/process'
+
 /** @type {import('@wtf/release-npm').Publisher} */
 export default {
   name: 'jsr',
-  async lookup(pkg, version, _tag, { system, env }) {
+  async lookup(pkg, version, _tag, { platform }) {
     const meta = `https://jsr.io/${pkg.name}/${version}_meta.json`
-    const { code } = await system.exec('curl', ['--fail', '--silent', '--head', meta], { env })
+    const response = await platform.fetch(meta, { method: 'HEAD' })
     // JSR has no dist-tags: no `tagged`.
-    return { published: code === 0 }
+    return { published: response.ok }
   },
-  async publish(pkg, _options, { system, env, dryRun }) {
+  async publish(pkg, _options, { platform, dryRun }) {
     const args = ['jsr', 'publish', '--allow-dirty', ...(dryRun ? ['--dry-run'] : [])]
-    const { code, stderr } = await system.exec('npx', args, { cwd: pkg.dir, env })
+    const { code, stderr } = await run(platform, 'npx', args, { cwd: pkg.dir })
     if (code !== 0) throw new Error(stderr)
   }
 }