@arc-e-tect/api-only-publisher 0.11.0 → 0.12.0

package/README.adoc

@@ -6,10 +6,11 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.11.0
+:api-only-publisher-version: 0.12.0
 
 image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
 image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
+image:https://img.shields.io/docker/v/arcetect/api-only-publisher?sort=semver&label=Docker%20Hub[Docker Hub,link=https://hub.docker.com/r/arcetect/api-only-publisher]
 image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDoneRight-API?filter=api-only-publisher-v*[GitHub release,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/releases?q=api-only-publisher]
 image:https://img.shields.io/badge/Node-22.14%2B-339933?logo=node.js[Node 22.14+,link=https://nodejs.org]
 image:https://img.shields.io/badge/License-MIT-blue[MIT,link=LICENSE]
@@ -63,6 +64,8 @@ To set it up for your situation, start at link:../docs/README.adoc[the documenta
 Nothing else.
 The bundlers, https://redocly.com/docs/cli/[Redocly CLI ↗] and https://www.asyncapi.com/tools/cli[AsyncAPI CLI ↗], are fetched by `npx` at the versions `apionly.yaml` pins, so they need no installation, and the only runtime dependency is `yaml`.
 
+Or Docker instead of Node.js: the image holds the Publisher and its bundlers, and downloads nothing when it runs, as <<docker>> describes.
+
 [#installation]
 == Installation
 
@@ -131,6 +134,22 @@ A published contract should change only when its fragments or its version change
 The bundlers are a separate matter.
 However the Publisher itself is started, it fetches them with `npx`, at the versions `toolchain` in `apionly.yaml` pins.
 
+[#as-a-docker-image]
+=== As a Docker image
+
+The fit for a CI pipeline that may run only vetted, mirrored artefacts.
+
+[source,console,subs="attributes+"]
+----
+docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" arcetect/api-only-publisher:{api-only-publisher-version} build
+----
+
+* One artefact, with one digest, holds the Publisher *and* its bundlers, so a pipeline pins, verifies, scans and mirrors everything it runs at once.
+* It downloads nothing when it runs, so `apionly.yaml` must pin the bundler versions the image carries.
+* The pin is the image's digest, in each pipeline that runs it; nothing in the library records it.
+
+<<docker>> describes it in full.
+
 [#commands]
 == Commands
 
@@ -176,6 +195,7 @@ A target whose closure is untouched needs no new version, however much else in t
 `--target` and `--channel` may be repeated.
 `-C <dir>` runs as if started in `<dir>`; without it the configuration is found by walking up from the current directory.
 `-q` or `--quiet` reports only errors, which is what a script that reads the output wants.
+`--version`, on its own, prints the Publisher's version.
 `--pre-release <ids>` appends pre-release identifiers to each target's version, as <<versions,Versions §>> describes.
 
 [source,console]
@@ -651,6 +671,28 @@ What happens when the destination already has the version:
 A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
 |===
 
+[#handoff]
+=== The hand-off: what a `publish` run wrote
+
+Every `publish` run lists each file its channels wrote locally, with its SHA-256, in two files in the packages directory -- `build.packages`, `build/packages` by default, or `--out`:
+
+[cols="1,3", options="header"]
+|===
+| File | Content
+
+| `packages.json`
+| `schemaVersion`, and `files`: for each file, its `path`, `sha256`, `target`, `version` and `channel`.
+
+| `packages.sha256`
+| The same files in the format `sha256sum -c` checks.
+|===
+
+Paths are relative to the library root, with forward slashes, so `sha256sum -c build/packages/packages.sha256` checks them from there.
+A run replaces both files.
+A channel in a remote mode writes nothing locally, so it adds nothing.
+
+The hand-off is for a later step that publishes those files itself -- the second of <<docker-two-steps,the image's two steps §>> -- so that it ships exactly the bytes the Publisher produced, and nothing else.
+
 [#channel-text]
 === What a package says about itself
 
@@ -797,8 +839,8 @@ lint:
     openapi: warn       # a request body or response with no example: error, warn (the default) or off
 
 toolchain:
-  redocly: "@redocly/cli@2.52.0"
-  asyncapi: "@asyncapi/cli@6.0.2"
+  redocly: "@redocly/cli@2.55.0"
+  asyncapi: "@asyncapi/cli@6.2.0"
 
 channels:
   file:
@@ -863,6 +905,24 @@ A bundle root moved into or out of `bundles/` needs its relative `$ref`s adjuste
 Unpinned, the documents this tool produces could change because an upstream release happened, with nothing in the library having changed.
 An upgrade should be a deliberate commit that moves the pin, reviewed with whatever it changes in the published documents.
 
+Two environment variables decide where a pinned bundler comes from.
+Neither is set outside the Docker image, which is then exactly the `npx` behaviour above.
+
+[cols="1,3", options="header"]
+|===
+| Variable | Effect
+
+| `API_ONLY_PUBLISHER_TOOLCHAIN_DIR`
+| A directory holding installed bundlers, as `npm install --prefix <dir>` leaves it.
+A bundler installed there at exactly the pinned version runs from there, without `npx`.
+
+| `API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD`
+| `allow`, the default, fetches any other pin with `npx`.
+`never` refuses to: `build` and `lint` fail before doing anything, naming the versions the directory holds.
+|===
+
+The Docker image sets both, with `never`, <<docker-toolchain>>.
+
 [#behaviour]
 == Behaviour worth knowing about
 
@@ -988,13 +1048,13 @@ So there is nothing to hoist and nothing to select: every fragment is stamped, a
 ----
 channels:
   auditV1:
-    x-fragment-path: asyncapi/channels/iff/useraccount/AuditV1.yaml
-    address: iff.useraccount.audit.v1
+    x-fragment-path: asyncapi/channels/apionly/useraccount/AuditV1.yaml
+    address: apionly.useraccount.audit.v1
     messages:
       registrationInitiatedMessage:
-        x-fragment-path: asyncapi/messages/iff/useraccount/RegistrationInitiatedMessageV1.yaml
+        x-fragment-path: asyncapi/messages/apionly/useraccount/RegistrationInitiatedMessageV1.yaml
         payload:
-          x-fragment-path: asyncapi/components/iff/useraccount/schemas/RegistrationInitiatedEventV1.yaml
+          x-fragment-path: asyncapi/components/apionly/useraccount/schemas/RegistrationInitiatedEventV1.yaml
           properties:
             username:
               x-fragment-path: openapi/components/common/schemas/UsernameV1.yaml
@@ -1046,6 +1106,440 @@ A producer has no business knowing the directory layout of the projects that con
 The `distribution` block copies built documents into such a layout, so that a library can adopt this tool before its consumers adopt the API-Only Subscriber.
 Once they subscribe, each consuming project declares where its own copy lands, and the block goes away.
 
+[#docker]
+== The Docker image
+
+The Publisher is also a Docker image, for CI pipelines that may run only what has been vetted and mirrored into the organisation's own registry.
+
+[cols="1,3"]
+|===
+| Docker Hub | `docker.io/arcetect/api-only-publisher`
+| GHCR       | `ghcr.io/arc-e-tect/api-only-publisher`
+| Platforms  | `linux/amd64` and `linux/arm64`, as one multi-platform image
+|===
+
+Vetting the npm package does not vet what it runs: it fetches Redocly CLI and AsyncAPI CLI with `npx` when it runs.
+The image is one artefact, with one digest, holding one Publisher version *and* its toolchain, and it is *sealed*: it downloads nothing, and contacts nothing, when it runs.
+It can be pulled by digest, its signature verified, its SBOM and provenance read, scanned, and mirrored, and then a pipeline knows exactly what it runs.
+
+Both registries serve the same image, with the same digest: Docker Hub gets a copy of what GHCR was given, never a rebuild.
+
+link:../docs/guides/publishing-from-ci/overview.adoc[Publishing from CI with the image →] is the guide, with prompts that set up the pipeline in your own repository.
+
+[#docker-two-steps]
+=== Two steps: package in the image, publish with the platform's tools
+
+. *In the image*, the Publisher builds, lints and packages bundles into files, with the local modes of its channels: `file`, `maven` and `nuget` to a directory, and `npm` with `publish: false`.
+It needs no network and no credential.
+. *In the pipeline*, a following job publishes those files to the organisation's registry with that platform's own tools and credentials: `npm publish`, `mvn deploy:deploy-file`, `dotnet nuget push`, a release upload.
+
+Every `publish` run writes a hand-off, <<handoff,The hand-off §>>, listing each file it wrote with its SHA-256.
+The publishing job checks the files against it, and publishes exactly those bytes: the bytes in the registry are the bytes the vetted tool produced.
+
+Credentials never enter the image.
+
+[IMPORTANT]
+.What the image does not do yet
+====
+The image does not publish to a remote registry itself.
+The channels' remote modes -- `maven` or `nuget` to a URL, `npm` with publishing, `github-release` -- may work from inside it, but they are neither tested nor supported there.
+Publish in a second step, as <<docker-pipelines>> shows.
+====
+
+[#docker-tags]
+=== Tags, and why to pin by digest
+
+[cols="1,3", options="header"]
+|===
+| Tag | Points at
+
+| `{api-only-publisher-version}`
+| That version, and nothing else, for good.
+Once pushed, an exact-version tag never points at another digest: a re-publish of a version reuses the image it already has, and never rebuilds it.
+
+| `0.11`, `0`, `latest`
+| The highest released version.
+They move with each new highest release, never for a re-publish of an older version, and never for a pre-release.
+
+| `1.0.0-rc.1`, …
+| A pre-release gets only its exact tag.
+|===
+
+Pin by digest, as `arcetect/api-only-publisher@sha256:<digest>`.
+A digest names the bytes a vetting team approved, in any registry the image is mirrored to; a tag is only a name, and a mirror may be configured to let it move.
+
+Find a version's digest with:
+
+[source,console,subs="attributes+"]
+----
+docker buildx imagetools inspect arcetect/api-only-publisher:{api-only-publisher-version} --format '{{ .Manifest.Digest }}'
+----
+
+The GitHub Release of each version lists it too, with both references.
+
+[#docker-vetting]
+=== For a vetting team
+
+[#docker-contents]
+==== What is inside
+
+[cols="1,3", options="header"]
+|===
+| Part | Detail
+
+| Base
+| `node:24-trixie-slim`, the official Node.js 24 image on Debian 13, pinned by digest.
+
+| Added packages
+| `git` and `ca-certificates`; `tar` and `npm` come with the base.
+
+| The Publisher
+| The npm package `@arc-e-tect/api-only-publisher` at the image's version: the release workflow installs the tarball npm serves for that version.
+
+| The toolchain
+| Redocly CLI and AsyncAPI CLI, at the versions `init` pins, installed from a lockfile into `/opt/api-only-publisher/toolchain`.
+
+| User
+| UID `10001`, GID `0`: not root.
+Any other UID works too, <<docker-user>>.
+|===
+
+The labels say so without running anything:
+
+[source,console,subs="attributes+"]
+----
+docker pull arcetect/api-only-publisher:{api-only-publisher-version}
+docker image inspect arcetect/api-only-publisher:{api-only-publisher-version} --format '{{ json .Config.Labels }}'
+----
+
+Besides the OCI annotations -- `source`, `revision`, `version`, `created`, `licenses` and the rest -- two labels name the toolchain:
+
+[cols="2,1", options="header"]
+|===
+| Label | Example
+| `com.arc-e-tect.api-only-publisher.toolchain.redocly`  | `@redocly/cli@2.55.0`
+| `com.arc-e-tect.api-only-publisher.toolchain.asyncapi` | `@asyncapi/cli@6.2.0`
+|===
+
+[#docker-sbom]
+==== SBOM and provenance
+
+Each image carries an SPDX SBOM and SLSA provenance as attestations, per platform.
+The SBOM lists every package in the image: the Debian packages, and the npm packages of the Publisher and the toolchain with their whole dependency trees.
+The provenance names this repository, the release workflow and the commit.
+
+[source,console,subs="attributes+"]
+----
+docker buildx imagetools inspect arcetect/api-only-publisher:{api-only-publisher-version} --format '{{ json .SBOM }}'
+docker buildx imagetools inspect arcetect/api-only-publisher:{api-only-publisher-version} --format '{{ json .Provenance }}'
+----
+
+The GitHub Release of each version has both platforms' SBOMs attached, as `api-only-publisher-image-<version>-linux-<arch>.spdx.json`.
+
+[#docker-signature]
+==== Verifying the signature
+
+Each image is signed with https://docs.sigstore.dev/[Sigstore cosign ↗], keyless: the signing certificate is issued to the release workflow's GitHub OIDC identity, so no signing key exists to be stolen.
+Verify against exactly that identity:
+
+[source,console,subs="attributes+"]
+----
+cosign verify \
+  --certificate-identity https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/.github/workflows/api-only-publisher-image.yml@refs/heads/main \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  arcetect/api-only-publisher@sha256:<digest>
+----
+
+The same command, with `ghcr.io/arc-e-tect/api-only-publisher`, verifies GHCR's copy.
+The identity is the image workflow, at `main`, which the release workflow calls.
+
+[#docker-scanning]
+==== Scanning
+
+Each release is scanned with https://trivy.dev/[Trivy ↗], every platform, every severity, and the reports are attached to its GitHub Release as `api-only-publisher-image-<version>-linux-<arch>.trivy.json` and `.txt`.
+
+A *CRITICAL* finding that has a fix blocks the release from reaching Docker Hub.
+The exceptions are listed in link:.trivyignore.yaml[`.trivyignore.yaml` →], each with its reason, the path it applies to, and the date it expires.
+Findings without a fix, which every Debian base has, are reported and do not block.
+
+Scan it yourself as your policy requires, for example:
+
+[source,console]
+----
+trivy image --ignorefile .trivyignore.yaml arcetect/api-only-publisher@sha256:<digest>
+----
+
+[#docker-mirroring]
+==== Mirroring into an internal registry
+
+Copy the image with everything attached to it -- both platforms, their SBOM and provenance attestations, and the signature -- with https://oras.land/[the ORAS CLI ↗]:
+
+[source,console,subs="attributes+"]
+----
+oras cp -r \
+  docker.io/arcetect/api-only-publisher@sha256:<digest> \
+  registry.example.com/mirror/arcetect/api-only-publisher:{api-only-publisher-version}
+----
+
+`-r` copies the image's referrers too, which is where cosign stores the signature: an OCI referrer, a Sigstore bundle, not a `sha256-<digest>.sig` tag.
+`skopeo copy --all` and `crane copy` keep the platforms and the attestations, but not a referrer, so a copy made with them has no signature to verify.
+The mirror must support the OCI 1.1 referrers API, as Docker Hub, GHCR and the CNCF Distribution registry, version 3, do; check your registry's documentation for its own.
+
+The digest does not change in the copy.
+Verify the mirror's copy as the original, with the mirror's name:
+
+[source,console]
+----
+cosign verify \
+  --certificate-identity https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/.github/workflows/api-only-publisher-image.yml@refs/heads/main \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  registry.example.com/mirror/arcetect/api-only-publisher@sha256:<digest>
+----
+
+Pipelines then pin the same digest, with the mirror's name.
+
+[#docker-pipelines]
+=== For a pipeline author
+
+[#docker-run]
+==== Every command, as `docker run`
+
+Run from the library's root, which is mounted at `/work`, the image's working directory:
+
+[source,console,subs="attributes+"]
+----
+docker run --rm --network none --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher@sha256:<digest> init --yes --openapi --asyncapi .
+docker run --rm --network none --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher@sha256:<digest> build
+docker run --rm --network none --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher@sha256:<digest> publish --target orders --target payments
+----
+
+The image's arguments are the Publisher's: every command in <<commands>> works this way, and so do `--help` and `--version`.
+Anything else runs as given, `sh -c '…'` included.
+
+`--network none` is not needed, and costs nothing: nothing in the image uses the network.
+
+[#docker-user]
+==== The user, file ownership and git
+
+`--user "$(id -u):$(id -g)"` runs the Publisher as you, so the files it writes into `/work` are yours.
+Any UID works, with or without an entry in the image's `/etc/passwd`: `HOME` is `/tmp`, which any user can write.
+
+`git` trusts a mounted repository whoever owns it; without that, git would refuse a repository owned by another user as "dubious ownership".
+The library does not have to be a git repository, but `pack` and `publish` read the commit time and the `origin` remote from it when it is.
+
+[#docker-read-only]
+==== A read-only root filesystem
+
+The image runs with `--read-only`, as hardened platforms enforce, given a writable `/tmp`:
+
+[source,console]
+----
+docker run --rm --read-only --tmpfs /tmp --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher@sha256:<digest> build
+----
+
+[#docker-toolchain]
+==== The toolchain rule, and the opt-in
+
+The image runs its own toolchain, and only that: `apionly.yaml` must pin the versions the image carries, the ones its `com.arc-e-tect.api-only-publisher.toolchain.*` labels name, and `init` writes.
+A library pinning another version fails at once, before anything is built and without reaching for the network:
+
+----
+Error: apionly.yaml's toolchain.redocly pins @redocly/cli@2.51.0, and API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD=never forbids downloading it.
+This installation carries @asyncapi/cli@6.2.0 and @redocly/cli@2.55.0.
+Set toolchain.redocly to "@redocly/cli@2.55.0" in apionly.yaml, or use the api-only-publisher image whose com.arc-e-tect.api-only-publisher.toolchain.redocly label is @redocly/cli@2.51.0.
+To allow the download instead, run with API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD=allow.
+----
+
+Align `toolchain` in `apionly.yaml`, or use the image version that carries the pinned toolchain.
+
+`API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD=allow` lets the Publisher fetch a pin the image does not carry with `npx`, as it does outside Docker.
+It is off in the image, and exists for someone who knowingly accepts a download; the image is then no longer sealed.
+With a read-only root, `/tmp` must allow what `npx` fetches to run:
+
+[source,console]
+----
+docker run --rm --read-only --tmpfs /tmp:exec -e API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD=allow \
+  --user "$(id -u):$(id -g)" -v "$PWD:/work" arcetect/api-only-publisher@sha256:<digest> build
+----
+
+<<pinning-the-bundlers>> describes the variables.
+
+[#docker-network]
+==== Nothing phones home
+
+The image makes no outbound connection: it sets, in its environment, what switches off each tool's own:
+
+[cols="1,2", options="header"]
+|===
+| Tool | Switched off with
+| npm           | `NPM_CONFIG_UPDATE_NOTIFIER=false`, `NPM_CONFIG_FUND=false`, `NPM_CONFIG_AUDIT=false`
+| Redocly CLI   | `REDOCLY_TELEMETRY=off`, `REDOCLY_SUPPRESS_UPDATE_NOTICE=true`
+| AsyncAPI CLI  | `ASYNCAPI_METRICS_CONFIG_PATH`, naming a file with analytics disabled, and `ASYNCAPI_SKIP_NEW_VERSION_CHECK=true`
+|===
+
+This is tested, not assumed: the whole smoke test was run on a network whose every packet was captured, and the image sent none.
+
+[#docker-ci-job]
+==== As a CI job image
+
+The image is also a job image, for platforms that run a job's own shell commands inside it.
+Its entrypoint runs the Publisher when the first argument is one of its commands or a flag, and anything else as given, so a platform that starts the image with a shell needs no entrypoint override.
+
+GitHub Actions replaces the entrypoint of a `container:` job, and runs its steps as the image's user by default, which cannot write the workspace GitHub mounts; run the job as the runner's user, UID 1001:
+
+[source,yaml]
+----
+include::pipelines/github-actions-container-job.yml[]
+----
+
+A GitLab CI job uses it as it stands:
+
+[source,yaml]
+----
+package:
+  image: docker.io/arcetect/api-only-publisher@sha256:<digest>
+  script:
+    - api-only-publisher build
+----
+
+[#docker-github-actions]
+==== Reference pipeline: GitHub Actions
+
+Two jobs: `package` runs the image and hands the files on, `publish` checks them against the hand-off and publishes them to npm, Maven and NuGet on GitHub Packages, and to a GitHub Release, with the job's `GITHUB_TOKEN`.
+Copy it into `.github/workflows/`, then set the digest, the targets and the trigger.
+The container-job variant above replaces its `package` job.
+
+It is exercised end to end, both variants, by a workflow in this repository that publishes to scratch packages and resolves each one with its ecosystem's own client and with the API-Only Subscriber.
+
+[source,yaml]
+----
+include::pipelines/github-actions.yml[]
+----
+
+What the two steps lose, and how the pipeline makes up for it:
+
+* *Idempotence.* A channel's remote mode leaves a version the registry has alone when it is identical, and refuses it when it differs; `npm publish` or `dotnet nuget push` of an existing version fails instead.
+Each publishing step checks for the version first, compares the bytes, and publishes only what is missing, so a re-run is safe and a real conflict still fails.
+* *Maven checksums and metadata.* The local Maven layout holds the artifact, its POM and its manifest, and no `.md5`, `.sha1` or `maven-metadata.xml`.
+`mvn deploy:deploy-file` writes those when it uploads, so the repository ends up as a remote `maven` channel would leave it, and Gradle resolves it.
+
+[#docker-gitlab]
+==== Reference pipeline: GitLab CI
+
+[WARNING]
+====
+*Not exercised.*
+This pipeline is validated against GitLab's published CI schema only; no GitLab pipeline has run it yet.
+====
+
+The same two steps: `package` runs in the image, and one `publish:*` job per registry publishes to the project's package registry with `CI_JOB_TOKEN`: npm, Maven and NuGet, and the archives to the generic package registry.
+
+[source,yaml]
+----
+include::pipelines/gitlab-ci.yml[]
+----
+
+[#docker-mirror-in-pipelines]
+==== Using a mirrored image
+
+Replace the image reference with the mirror's, keeping the digest: `registry.example.com/mirror/arcetect/api-only-publisher@sha256:<digest>`.
+Both reference pipelines name the image in one place: `PUBLISHER_IMAGE`, and the container job's `image`.
+
+[#docker-maintainers]
+=== For maintainers
+
+[#docker-release]
+==== How an image is released
+
+The release workflow calls link:../.github/workflows/api-only-publisher-image.yml[`api-only-publisher-image.yml` →] after the npm upload:
+
+. *Plan.* The tag rules, link:docker/image-tags.js[`docker/image-tags.js` →]: whether GHCR already has the version, and which floating tags move.
+. *Build*, each platform on a native runner, from the tarball npm serves for the version, pushed to GHCR by digest with its SBOM and provenance.
+. *Tag and sign on GHCR*: the multi-platform image, its exact-version tag, and a keyless signature.
+. *Smoke test* on both platforms, from an anonymous pull by digest, which proves the package is public: link:docker/smoke-test.sh[`docker/smoke-test.sh` →].
+. *Scan*, reported in full, blocking on a fixable critical finding.
+. *Promote*: the same digest copied to Docker Hub, its floating tags moved on both registries, the digest checked on Docker Hub, and signed and verified there.
+. *Describe*: the Docker Hub short description and overview, from link:docker/DOCKERHUB.md[`docker/DOCKERHUB.md` →].
+. *Release assets*: the SBOMs and scan reports attached to the GitHub Release, and the image listed in its notes.
+
+A failure in any of these never undoes the npm release; the workflow summary shows it.
+A branch that changes what the image is built from builds it for `linux/amd64` and smoke-tests it, without pushing.
+
+[#docker-secrets]
+==== Secrets and variables
+
+[cols="1,1,3", options="header"]
+|===
+| Name | Kind | Scope and use
+
+| `GITHUB_TOKEN`
+| Automatic
+| `packages: write` to push to GHCR, `contents: write` to attach release assets, `id-token: write` for cosign's keyless signature. No stored secret.
+
+| `DOCKERHUB_NAMESPACE`
+| Variable
+| The Docker Hub namespace, `arcetect`: the image is `<namespace>/api-only-publisher`. A variable, so the image can move to an organisation without editing a workflow.
+
+| `DOCKERHUB_USERNAME`
+| Variable
+| The Docker Hub account the tokens belong to.
+
+| `DOCKERHUB_TOKEN`
+| Secret
+| A Docker Hub personal access token with *Read & Write* scope: pushes the image and its tags.
+
+| `DOCKERHUB_DESCRIPTION_TOKEN`
+| Secret
+| A Docker Hub personal access token with *Read, Write, Delete* scope, the scope Docker Hub requires to change a repository's description. Only the description job holds it.
+
+| `E2E_CLEANUP_TOKEN`
+| Secret, optional
+| A classic GitHub personal access token with `read:packages` and `delete:packages`, with which the end-to-end workflow deletes its scratch package versions. Without it, it lists them for deletion by hand.
+|===
+
+The repository's Actions policy allows only GitHub-owned actions, verified creators and listed ones, and requires every action pinned by SHA.
+`peter-evans/dockerhub-description`, which updates the description, is on that list; a workflow using an action that is not fails to start, with no message saying why.
+
+[#docker-visibility]
+==== GHCR visibility
+
+GitHub documents that a package starts private and does not inherit its repository's visibility, which can be changed only by hand.
+In practice, the scratch package the dry run pushed, linked to this public repository through the image's `source` annotation, was public from its first push.
+
+So the first release may need nothing; the smoke test finds out, since it pulls the image anonymously.
+If that pull fails, its message names this step: open the package's settings, https://github.com/users/Arc-E-Tect/packages/container/api-only-publisher/settings[api-only-publisher ↗], choose *Change visibility* under *Danger Zone*, make it *Public*, and re-run the failed jobs.
+
+[#docker-republish]
+==== Re-publishing
+
+Run the release workflow by hand with `republish_version` set to a released version, when its npm upload or its image failed.
+A version npm already has is not uploaded again.
+If GHCR has the image, it is reused, not rebuilt, and Docker Hub is given that same digest, or left alone if it has it; an exact-version tag is never pointed at another digest.
+The floating tags move only if the version is the highest released.
+
+[#docker-verifying]
+==== Running the smoke test and the end-to-end workflow
+
+The smoke test runs an image exactly as the release does, with nothing but Docker:
+
+[source,console]
+----
+cd api-only-publisher
+docker/build-context.sh 0.0.0-local
+docker build -t api-only-publisher:local --build-arg VERSION=0.0.0-local .
+docker/smoke-test.sh api-only-publisher:local 0.0.0-local
+----
+
+It runs every step with no network, a read-only root and your own user: the version, the help, the toolchain labels against what is installed and against `init`'s pins, a library with two targets built, linted and packaged to every local channel in one run, ownership, byte-identical packaging twice, the hand-off, a foreign toolchain pin failing at once, the shell mode, and a build as an arbitrary UID.
+
+link:../.github/workflows/api-only-publisher-image-e2e.yml[`api-only-publisher-image-e2e.yml` →] runs the GitHub Actions reference pipeline for real, by hand only.
+Give it an image by digest; it publishes version `0.<run>.<attempt>` of two scratch targets, `apionly-e2e-alpha` and `apionly-e2e-beta`, to npm, Maven and NuGet on GitHub Packages and to a scratch release, publishes again to prove a re-run is safe, resolves each package with its own client and with the Subscriber, and removes what it published.
+The image workflow, dispatched by hand, is the release's dry run: its defaults are the scratch names `ghcr.io/arc-e-tect/api-only-publisher-scratch` and `arcetect/api-only-publisher-scratch`, and it builds from the branch's source.
+
 [#adapting]
 == Adapting it to another project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/build-error.js

@@ -0,0 +1,7 @@
+"use strict";
+
+// The error a build throws, in a module of its own so that toolchain.js can throw it
+// without requiring pipeline.js back.
+class BuildError extends Error {}
+
+module.exports = { BuildError };

package/src/channels.js

@@ -49,7 +49,7 @@ function publishFile(archive, manifest, options, log) {
     fs.writeFileSync(path.join(targetDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
 
     log(`-- Published ${manifest.target} ${manifest.version} to ${archiveDest}`);
-    return { location: archiveDest };
+    return { location: archiveDest, files: [archiveDest, path.join(targetDir, "manifest.json")] };
 }
 
 function pom(groupId, artifactId, version, packaging, description = `API description documents for ${artifactId}.`) {
@@ -104,14 +104,20 @@ function publishMaven(archive, manifest, options, log) {
     const base = `${artifactId}-${version}`;
     const artifactDest = path.join(dir, `${base}.${extension}`);
     fs.copyFileSync(archive, artifactDest);
-    fs.writeFileSync(path.join(dir, `${base}.pom`), pom(groupId, artifactId, version, extension, pomDescription(options, manifest)));
+    const pomDest = path.join(dir, `${base}.pom`);
+    fs.writeFileSync(pomDest, pom(groupId, artifactId, version, extension, pomDescription(options, manifest)));
 
     // The manifest travels beside the artifact as well as inside it, so a
     // consumer can read provenance without unpacking anything.
-    fs.writeFileSync(path.join(dir, `${base}-manifest.json`), JSON.stringify(manifest, null, 2) + "\n");
+    const manifestDest = path.join(dir, `${base}-manifest.json`);
+    fs.writeFileSync(manifestDest, JSON.stringify(manifest, null, 2) + "\n");
 
     log(`-- Published ${groupId}:${artifactId}:${version} to ${repository}`);
-    return { location: artifactDest, coordinates: `${groupId}:${artifactId}:${version}@${extension}` };
+    return {
+        location: artifactDest,
+        coordinates: `${groupId}:${artifactId}:${version}@${extension}`,
+        files: [artifactDest, pomDest, manifestDest],
+    };
 }
 
 /**
@@ -161,7 +167,7 @@ function publishNpm(archive, manifest, options, log) {
                 { cwd: workDir, encoding: "utf8" }).trim().split("\n").pop();
             const location = path.join(outDir, packed);
             log(`-- Packed npm ${name}@${version} (${distTag}) to ${location}`);
-            return { location, distTag, name };
+            return { location, distTag, name, files: [location] };
         }
 
         // Idempotent: a version the registry already has is left alone when it is the

package/src/cli.js

@@ -20,6 +20,8 @@ const { publish, ChannelError } = require("./channels");
 const { VersionError: PolicyError, describe } = require("./version-policy");
 const { versionOf, BundleVersionError } = require("./bundle-version");
 const { unreferenced } = require("./unreferenced");
+const { requireTools } = require("./toolchain");
+const { writeHandoff } = require("./handoff");
 
 const USAGE = `api-only-publisher -- build and distribute API description documents
 
@@ -67,6 +69,7 @@ Options:
   -C <dir>          Run as if started in <dir>.
   -q, --quiet       Only report errors.
   -h, --help        Show this help.
+  --version         On its own: print the Publisher's version.
 
 What gets built, and where each document goes, is declared in apionly.yaml.
 A published target's version is read from its version file:
@@ -97,6 +100,11 @@ function parseArgs(argv) {
             case "--target": options.targets.push(next()); break;
             case "--pre-release": options.preRelease = next(); break;
             case "--version":
+                // Alone, it asks for the Publisher's own version, as any tool's does.
+                if (argv.length === 1) {
+                    options.version = true;
+                    break;
+                }
                 throw new ConfigError(
                     "--version is no longer accepted: each published target's version is read from its version " +
                     "file, <target>.bundle.properties beside its bundle root. Pass --pre-release <ids> to cut a " +
@@ -283,6 +291,10 @@ async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
 
+    if (options.version) {
+        process.stdout.write(`${require("../package.json").version}\n`);
+        return 0;
+    }
     if (options.help || !command) {
         process.stdout.write(USAGE);
         return 0;
@@ -334,6 +346,8 @@ async function main(argv, io = {}) {
             // in dist/. Every selected document is linted even when one fails, so
             // one run reports every failure rather than only the first.
             const { lint } = require("./pipeline");
+            requireTools(config, ["openapi", "asyncapi"].filter((kind) =>
+                config.targetsFor(kind).some((target) => !targets || targets.includes(target))));
             const failures = [];
             let linted = 0;
             for (const kind of ["openapi", "asyncapi"]) {
@@ -441,6 +455,7 @@ async function main(argv, io = {}) {
             const versions = versionsOf(config, shipped, options.preRelease);
             const closures = forTargets(config, undefined, shipped);
             let published = 0;
+            const handoff = [];
             for (const target of Object.keys(config.targets)) {
                 if (targets && !targets.includes(target)) continue;
                 if (!config.isPublished(target)) continue;
@@ -453,11 +468,17 @@ async function main(argv, io = {}) {
                 });
                 for (const name of names) {
                     // A remote channel returns a promise; a local one does not.
-                    await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
+                    const result = await publish(archive, manifest, name, { ...(configured[name] || {}), baseDir: config.root }, log);
+                    for (const file of result.files || []) {
+                        handoff.push({ file, target, version: manifest.version, channel: name });
+                    }
                     published += 1;
                 }
             }
+            // What a later step publishes byte for byte; README.adoc#handoff.
+            const { sha256: listing } = writeHandoff(config.root, outDir, handoff);
             log(`\nPublished ${published} artifact(s).`);
+            log(`Listed ${handoff.length} file(s) in ${path.relative(config.root, listing)}.`);
             return 0;
         }
         case "split": {

package/src/handoff.js

@@ -0,0 +1,43 @@
+"use strict";
+
+// The hand-off: what a publish run left on disk for a later step to ship.
+//
+// In the two-step model the Publisher -- typically in its Docker image -- packages
+// bundles into files, and a following pipeline job publishes those files with the
+// registry's own tools. That job must ship exactly the bytes the Publisher wrote,
+// and nothing else, so every publish run lists each file a local channel wrote,
+// with its SHA-256, in two forms: packages.json for a script to read, and
+// packages.sha256 for `sha256sum -c`. Paths are relative to the library root, so
+// the check runs from there.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const HANDOFF_JSON = "packages.json";
+const HANDOFF_SHA256 = "packages.sha256";
+const HANDOFF_SCHEMA_VERSION = 1;
+
+/**
+ * Writes packages.json and packages.sha256 into `outDir`, replacing any from an
+ * earlier run, listing `entries` -- `{ file, target, version, channel }`, `file`
+ * absolute -- sorted by path.
+ */
+function writeHandoff(root, outDir, entries) {
+    const files = entries
+        .map(({ file, target, version, channel }) => ({
+            path: path.relative(root, file).split(path.sep).join("/"),
+            sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"),
+            target, version, channel,
+        }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+    fs.mkdirSync(outDir, { recursive: true });
+    const json = path.join(outDir, HANDOFF_JSON);
+    const sha256 = path.join(outDir, HANDOFF_SHA256);
+    fs.writeFileSync(json, JSON.stringify({ schemaVersion: HANDOFF_SCHEMA_VERSION, files }, null, 2) + "\n");
+    fs.writeFileSync(sha256, files.map((f) => `${f.sha256}  ${f.path}\n`).join(""));
+    return { json, sha256 };
+}
+
+module.exports = { writeHandoff, HANDOFF_JSON, HANDOFF_SHA256, HANDOFF_SCHEMA_VERSION };

package/src/index.js

@@ -22,4 +22,5 @@ module.exports = {
     ...require("./changed"),
     ...require("./split"),
     ...require("./channels"),
+    ...require("./handoff"),
 };

package/src/init-config.js

@@ -17,7 +17,7 @@ const YAML = require("yaml");
 
 /** Where a kind's tool is pinned in `toolchain`; the two kinds do not share a key name. */
 const TOOLCHAIN_KEY = { openapi: "redocly", asyncapi: "asyncapi" };
-const TOOLCHAIN_PIN = { openapi: "@redocly/cli@2.52.0", asyncapi: "@asyncapi/cli@6.0.2" };
+const TOOLCHAIN_PIN = { openapi: "@redocly/cli@2.55.0", asyncapi: "@asyncapi/cli@6.2.0" };
 
 /**
  * The slots scaffold(v) would fill for one kind, in the order config(v) declares them,
@@ -132,4 +132,4 @@ function addMissingConfig(text, v, portfolio) {
     return added.length === 0 ? { text, added } : { text: doc.toString(), added };
 }
 
-module.exports = { addMissingConfig };
+module.exports = { addMissingConfig, TOOLCHAIN_PIN };

package/src/init.js

@@ -15,7 +15,7 @@
 const fs = require("fs");
 const path = require("path");
 const YAML = require("yaml");
-const { addMissingConfig } = require("./init-config");
+const { addMissingConfig, TOOLCHAIN_PIN } = require("./init-config");
 
 /** Every value the scaffold is written from, as it is when nobody chooses otherwise. */
 const DEFAULTS = Object.freeze({
@@ -66,8 +66,8 @@ function config(v) {
         "",
         "toolchain:",
     );
-    if (openapi) lines.push('  redocly: "@redocly/cli@2.52.0"');
-    if (asyncapi) lines.push('  asyncapi: "@asyncapi/cli@6.0.2"');
+    if (openapi) lines.push(`  redocly: "${TOOLCHAIN_PIN.openapi}"`);
+    if (asyncapi) lines.push(`  asyncapi: "${TOOLCHAIN_PIN.asyncapi}"`);
     lines.push("", "targets:", `  ${v.target}:`);
     if (openapi) lines.push("    openapi:", `      bundle: bundles/${v.target}_openapi_structure.yaml`);
     if (asyncapi) lines.push("    asyncapi:", `      bundle: bundles/${v.target}_asyncapi_structure.yaml`);

package/src/nuget.js

@@ -160,12 +160,13 @@ function publishLocal(archive, manifest, options, id, log) {
 
     const file = path.join(dir, `${lowerId}.${lowerVersion}.nupkg`);
     fs.writeFileSync(file, bytes);
-    fs.writeFileSync(`${file}.sha512`, crypto.createHash("sha512").update(bytes).digest("base64"));
-    fs.writeFileSync(path.join(dir, `${lowerId}.nuspec`), spec);
-    fs.writeFileSync(path.join(dir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    const written = [file, `${file}.sha512`, path.join(dir, `${lowerId}.nuspec`), path.join(dir, "manifest.json")];
+    fs.writeFileSync(written[1], crypto.createHash("sha512").update(bytes).digest("base64"));
+    fs.writeFileSync(written[2], spec);
+    fs.writeFileSync(written[3], JSON.stringify(manifest, null, 2) + "\n");
 
     log(`-- Published NuGet ${id} ${manifest.version} to ${feed}`);
-    return { location: file, id, version: manifest.version, prerelease: isPrerelease(manifest.version) };
+    return { location: file, id, version: manifest.version, prerelease: isPrerelease(manifest.version), files: written };
 }
 
 /** The resources a feed's service index lists. */

package/src/pipeline.js

@@ -14,8 +14,8 @@ const { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps
 const {
     asyncapiOperationsWithoutExamples, openapiOperationsWithoutExamples, asyncapiMessage, openapiMessage,
 } = require("./examples");
-
-class BuildError extends Error {}
+const { BuildError } = require("./build-error");
+const toolchain = require("./toolchain");
 
 function run(command, args, { quiet, reportFile = null } = {}) {
     try {
@@ -38,6 +38,23 @@ function run(command, args, { quiet, reportFile = null } = {}) {
     }
 }
 
+/**
+ * Copy a directory tree, symlinks as symlinks.
+ *
+ * Not fs.cpSync: its native implementation fails with EACCES on Docker Desktop's
+ * bind mounts, which is where the Publisher's image stages a mounted library.
+ */
+function copyTree(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const source = path.join(from, entry.name);
+        const dest = path.join(to, entry.name);
+        if (entry.isDirectory()) copyTree(source, dest);
+        else if (entry.isSymbolicLink()) fs.symlinkSync(fs.readlinkSync(source), dest);
+        else fs.copyFileSync(source, dest);
+    }
+}
+
 /**
  * Copy the whole source root to the staging directory for one specification
  * type.
@@ -52,8 +69,7 @@ function stage(config, kind, log) {
     const to = config.stagingRoot(kind);
     log(`-- Staging ${path.relative(config.root, from)} -> ${path.relative(config.root, to)}`);
     fs.rmSync(to, { recursive: true, force: true });
-    fs.mkdirSync(to, { recursive: true });
-    fs.cpSync(from, to, { recursive: true });
+    copyTree(from, to);
     return to;
 }
 
@@ -94,8 +110,9 @@ function bundle(config, target, kind, outFile, log, { stagingRoot } = {}) {
     }
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
     log(`-- Bundling ${path.basename(source)}`);
-    const tool = kind === "openapi" ? config.tool("redocly") : config.tool("asyncapi");
-    run("npx", ["--yes", tool, "bundle", source, "--output", outFile], { quiet: true });
+    const tool = config.tool(toolchain.TOOL_OF_KIND[kind]);
+    const runner = toolchain.resolve(toolchain.TOOL_OF_KIND[kind], tool);
+    run(runner.command, [...runner.args, "bundle", source, "--output", outFile], { quiet: true });
     if (!fs.existsSync(outFile)) {
         throw new BuildError(`target '${target}': ${tool} produced no output at ${outFile}`);
     }
@@ -121,7 +138,7 @@ function bundleWithFragmentPaths(config, target, kind, outFile, log) {
 
     const pass = (name, only) => {
         const root = path.join(scratch, name);
-        fs.cpSync(config.stagingRoot(kind), root, { recursive: true });
+        copyTree(config.stagingRoot(kind), root);
         try {
             stampFiles(root, { only });
         } catch (error) {
@@ -170,7 +187,7 @@ function bundleInlinedWithFragmentPaths(config, target, kind, outFile, log) {
     const scratch = config.fragmentPathStaging(target);
     fs.rmSync(scratch, { recursive: true, force: true });
     const root = path.join(scratch, "stamp");
-    fs.cpSync(config.stagingRoot(kind), root, { recursive: true });
+    copyTree(config.stagingRoot(kind), root);
 
     const bundleRoot = path.relative(root, config.bundleRootPath(target, kind, root)).split(path.sep).join("/");
     try {
@@ -199,12 +216,12 @@ function bundleInlinedWithFragmentPaths(config, target, kind, outFile, log) {
 }
 
 function lint(config, kind, file, log, { report = false, reportFile = null } = {}) {
-    const tool = kind === "openapi" ? config.tool("redocly") : config.tool("asyncapi");
+    const runner = toolchain.resolve(toolchain.TOOL_OF_KIND[kind], config.tool(toolchain.TOOL_OF_KIND[kind]));
     const args = kind === "openapi"
-        ? ["--yes", tool, "lint"].concat(config.lintConfig("openapi") ? ["--config", config.lintConfig("openapi")] : []).concat([file])
-        : ["--yes", tool, "validate", file];
+        ? ["lint"].concat(config.lintConfig("openapi") ? ["--config", config.lintConfig("openapi")] : []).concat([file])
+        : ["validate", file];
     log(`-- Validating ${path.basename(file)}`);
-    const output = run("npx", args, { quiet: true, reportFile });
+    const output = run(runner.command, [...runner.args, ...args], { quiet: true, reportFile });
     if (report && output.trim()) log(output.trimEnd());
 }
 
@@ -289,6 +306,11 @@ function prepare(config, { kinds = ["openapi", "asyncapi"], log = () => {} } = {
  * @returns {Array<{target, kind, file, distributed}>}
  */
 function build(config, { targets, versionOf = () => null, kinds = ["openapi", "asyncapi"], log = () => {} } = {}) {
+    // Every tool this build needs is found before anything is staged, so a toolchain
+    // the installation cannot run fails the build before it has done any work.
+    const needed = kinds.filter((kind) => config.targetsFor(kind).some((t) => !targets || targets.includes(t)));
+    toolchain.requireTools(config, needed);
+
     const results = [];
     for (const kind of kinds) {
         const all = config.targetsFor(kind).filter((t) => !targets || targets.includes(t));
@@ -349,5 +371,5 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
 }
 
 module.exports = {
-    build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, checkExamples, distribute, BuildError,
+    build, prepare, stage, copyTree, substituteTree, bundle, bundleWithFragmentPaths, lint, checkExamples, distribute, BuildError,
 };

package/src/toolchain.js

@@ -0,0 +1,123 @@
+"use strict";
+
+// Finding the bundler and validator a build runs.
+//
+// Out of the box each tool runs through `npx --yes <pin>`, which downloads the
+// pinned version when it is not cached. An installation that already carries the
+// tools -- the Docker image -- names where they are, and a tool installed there at
+// exactly the pinned version runs from its own bin instead. An installation that
+// must not download anything at all says so, and a pin it does not carry then
+// fails before anything runs, rather than reaching for the network.
+//
+// Both are environment variables, so the Publisher outside the image behaves as
+// it always has: neither is set there.
+
+const fs = require("fs");
+const path = require("path");
+
+const { BuildError } = require("./build-error");
+
+/** Where the installed toolchain is: a directory `npm install --prefix` filled. */
+const DIR_ENV = "API_ONLY_PUBLISHER_TOOLCHAIN_DIR";
+/** `allow`, the default, falls back to npx; `never` refuses to. */
+const DOWNLOAD_ENV = "API_ONLY_PUBLISHER_TOOLCHAIN_DOWNLOAD";
+/** The image label naming the pin each tool is installed at, per toolchain key. */
+const LABEL_PREFIX = "com.arc-e-tect.api-only-publisher.toolchain.";
+
+/** Which toolchain key each kind of document is built with. */
+const TOOL_OF_KIND = { openapi: "redocly", asyncapi: "asyncapi" };
+
+class ToolchainError extends BuildError {}
+
+/** A pin such as `@redocly/cli@2.52.0` as its package name and version; a bare name has none. */
+function parseSpec(spec) {
+    const at = spec.lastIndexOf("@");
+    if (at <= 0) return { name: spec, version: null };
+    return { name: spec.slice(0, at), version: spec.slice(at + 1) };
+}
+
+function readPackage(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+        return null;
+    }
+}
+
+function packageDir(dir, name) {
+    return path.join(dir, "node_modules", ...name.split("/"));
+}
+
+/** Every tool the toolchain directory declares, as `name@installed-version`, in declaration order. */
+function installed(dir) {
+    if (!dir) return [];
+    const manifest = readPackage(path.join(dir, "package.json"));
+    if (!manifest) return [];
+    return Object.keys(manifest.dependencies || {}).map((name) => {
+        const own = readPackage(path.join(packageDir(dir, name), "package.json"));
+        return `${name}@${own ? own.version : "(missing)"}`;
+    });
+}
+
+// The bin to run: the only one, or the one named after the package or its scope --
+// Redocly CLI declares `openapi` and `redocly`, and `redocly` is the tool.
+function binOf(own, spec) {
+    if (typeof own.bin === "string") return own.bin;
+    const bins = Object.keys(own.bin || {});
+    if (bins.length === 1) return own.bin[bins[0]];
+    const scope = own.name.startsWith("@") ? own.name.slice(1).split("/")[0] : null;
+    const unscoped = own.name.split("/").pop();
+    const named = [unscoped, scope].find((candidate) => candidate && own.bin[candidate]);
+    if (named) return own.bin[named];
+    throw new ToolchainError(`${spec} declares several bins (${bins.join(", ")}), and none is named after it`);
+}
+
+function downloadMode(env) {
+    const mode = env[DOWNLOAD_ENV] === undefined || env[DOWNLOAD_ENV] === "" ? "allow" : env[DOWNLOAD_ENV];
+    if (mode !== "allow" && mode !== "never") {
+        throw new ToolchainError(`${DOWNLOAD_ENV} must be allow or never, not ${JSON.stringify(mode)}`);
+    }
+    return mode;
+}
+
+function refusal(key, spec, dir, carried) {
+    const { name } = parseSpec(spec);
+    const same = carried.find((entry) => parseSpec(entry).name === name);
+    const lines = [`apionly.yaml's toolchain.${key} pins ${spec}, and ${DOWNLOAD_ENV}=never forbids downloading it.`];
+    if (carried.length === 0) {
+        lines.push(`This installation carries no toolchain${dir ? ` in ${dir}` : `: ${DIR_ENV} is not set`}.`);
+    } else {
+        const list = carried.length === 1 ? carried[0] : `${carried.slice(0, -1).join(", ")} and ${carried[carried.length - 1]}`;
+        lines.push(`This installation carries ${list}.`);
+    }
+    const align = same ? `Set toolchain.${key} to "${same}" in apionly.yaml, or use` : "Use";
+    lines.push(`${align} the api-only-publisher image whose ${LABEL_PREFIX}${key} label is ${spec}.`);
+    lines.push(`To allow the download instead, run with ${DOWNLOAD_ENV}=allow.`);
+    return new ToolchainError(lines.join("\n"));
+}
+
+/**
+ * How to run the tool pinned as `spec` under toolchain key `key`: a command and
+ * the arguments that precede the tool's own.
+ */
+function resolve(key, spec, env = process.env) {
+    const mode = downloadMode(env);
+    const dir = env[DIR_ENV] || null;
+    const { name, version } = parseSpec(spec);
+    if (dir && version) {
+        const root = packageDir(dir, name);
+        const own = readPackage(path.join(root, "package.json"));
+        if (own && own.version === version) return { command: path.join(root, binOf(own, spec)), args: [] };
+    }
+    if (mode === "never") throw refusal(key, spec, dir, installed(dir));
+    return { command: "npx", args: ["--yes", spec] };
+}
+
+/** Resolves the tool of every kind in `kinds`, so a run that cannot have them fails before it starts. */
+function requireTools(config, kinds, env = process.env) {
+    for (const kind of kinds) resolve(TOOL_OF_KIND[kind], config.tool(TOOL_OF_KIND[kind]), env);
+}
+
+module.exports = {
+    parseSpec, installed, resolve, requireTools, ToolchainError, DIR_ENV, DOWNLOAD_ENV, LABEL_PREFIX, TOOL_OF_KIND,
+};