@stealthscale/tool-cli 0.1.0

package/dist/command-wCHt33VW.mjs

@@ -0,0 +1,740 @@
+import { defineCommand } from "citty";
+import { dependencyClosure, workspaceManifests, workspaceRoot } from "@stealthscale/tool-workspace";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { looseObject, number, optional, parse, record, string, unknown } from "@stealthscale/core-schema";
+//#region src/release/changesets.ts
+/**
+* @fileoverview Tells changesets/action what a run published. The action hands the publish
+* script a file path and reads JSON lines back from it, one per tag, and creates the git tag
+* and the GitHub release from each. It reads nothing the script prints.
+*/
+/**
+* Builds the entry for one published package.
+*
+* @param {Manifest} manifest - The package that went out.
+* @returns {TagEvent} The entry, naming the package and its tag.
+*/
+function tagEvent(manifest) {
+	return {
+		packageName: manifest.name,
+		tag: `${manifest.name}@${manifest.version}`,
+		type: "git-tag"
+	};
+}
+/**
+* Writes the entries where changesets/action reads them, one JSON object per line.
+*
+* A run that published nothing still writes the file, empty. The action reports a file it
+* cannot read as a warning and then creates no tag for anything, so an empty file and a
+* missing one differ.
+*
+* @param {string} file - The path the action handed the run, from `CHANGESETS_OUTPUT`.
+* @param {readonly TagEvent[]} events - One entry per published package.
+*/
+function writeTagEvents(file, events) {
+	writeFileSync(file, events.map((event) => `${JSON.stringify(event)}\n`).join(""));
+}
+//#endregion
+//#region src/report/report.ts
+/**
+* Matches a stack frame, which says where a tool was when it failed rather than why.
+*/
+const STACK_FRAME = /^\s+at\s/u;
+/**
+* Builds a step that went as it should.
+*
+* @param {string} name - The stage and its subject.
+* @param {string} [detail] - Text worth reading even so, such as a checker's warnings.
+*     Default: nothing.
+* @returns {Step} The step.
+*/
+function passed(name, detail = "") {
+	return {
+		detail,
+		name,
+		ok: true
+	};
+}
+/**
+* Builds a step that did not go as it should.
+*
+* @param {string} name - The stage and its subject.
+* @param {string} detail - The reason: the command's last lines, or what was found wanting.
+* @returns {Step} The step.
+*/
+function failed(name, detail) {
+	return {
+		detail,
+		name,
+		ok: false
+	};
+}
+/**
+* Lists the steps of a run that failed.
+*
+* @param {Report} report - The run.
+* @returns {Step[]} The failed steps, in order.
+*/
+function failures(report) {
+	return report.steps.filter((step) => !step.ok);
+}
+/**
+* Keeps the end of what a command wrote, which is where the reason usually is. Stack frames
+* go first: a bundler's failure is one line of cause over thirty lines of frames.
+*
+* @param {string} output - Everything the command wrote, both streams together.
+* @param {number} [keep] - How many lines to keep at most. Default: 20.
+* @returns {string} The last lines, with blank lines at either end dropped.
+*/
+function lastLines(output, keep = 20) {
+	const lines = output.split("\n").filter((line) => !STACK_FRAME.test(line));
+	const first = lines.findIndex((line) => line.trim() !== "");
+	if (first === -1) return "";
+	const last = lines.findLastIndex((line) => line.trim() !== "") + 1;
+	return lines.slice(Math.max(first, last - keep), last).join("\n");
+}
+/**
+* Renders a report as text: one line per step, a step's detail indented under it, then the
+* count and, when something failed, where to look.
+*
+* @param {Report} report - The run.
+* @returns {string} The text, ending in a newline.
+*/
+function render(report) {
+	const lines = report.steps.flatMap((step) => [`${step.ok ? "ok  " : "FAIL"}  ${step.name}`, ...step.detail === "" ? [] : step.detail.split("\n").map((line) => `      ${line}`)]);
+	const count = failures(report).length;
+	const summary = count === 0 ? `${report.steps.length} steps, all passed` : `${report.steps.length} steps, ${count} failed; the run's files are in ${report.workdir}`;
+	return [
+		...lines,
+		"",
+		summary,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/shell/shell.ts
+/**
+* @fileoverview Runs the commands the `stealth` tool needs: bun, npm and a registry, as real
+* processes that the tool owns. A specification hands the tool a shell that records instead.
+*/
+/**
+* Describes what a listening server answers for its address, in the one field the tool reads.
+*/
+const BOUND_ADDRESS = looseObject({ port: number() });
+/**
+* Builds this process's environment with the command's own additions on top.
+*
+* @param {RunOptions} options - The options the command was given.
+* @returns {Readonly<Record<string, string | undefined>>} This process's variables, with the
+*     command's additions written over them.
+*/
+function environment(options) {
+	return {
+		...process.env,
+		...options.env
+	};
+}
+/**
+* Runs one command to completion.
+*
+* @param {string} file - The executable.
+* @param {readonly string[]} args - The arguments.
+* @param {RunOptions} options - The working directory and the environment.
+* @returns {Promise<CommandOutcome>} The exit code and both streams.
+*/
+function run(file, args, options) {
+	return new Promise((resolve) => {
+		const child = spawn(file, [...args], {
+			cwd: options.cwd,
+			env: environment(options),
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", (error) => {
+			resolve({
+				code: 1,
+				stderr: error.message,
+				stdout
+			});
+		});
+		child.on("close", (code) => {
+			resolve({
+				code: code ?? 1,
+				stderr,
+				stdout
+			});
+		});
+	});
+}
+/**
+* Sets how long a stopped process is given to leave on `SIGTERM` before it is killed.
+*/
+const GRACE_MS = 1e3;
+/**
+* Starts one long-lived process, owned by its pid.
+*
+* The log file is opened here and closed when the process exits, so a tool that starts and
+* stops several registries over a run does not run out of descriptors.
+*
+* @param {string} file - The executable.
+* @param {readonly string[]} args - The arguments.
+* @param {StartOptions} options - The working directory, the environment and the log file.
+* @returns {StartedProcess} The process.
+*/
+function start(file, args, options) {
+	const log = openSync(options.log, "a");
+	const child = spawn(file, [...args], {
+		cwd: options.cwd,
+		env: environment(options),
+		stdio: [
+			"ignore",
+			log,
+			log
+		]
+	});
+	/**
+	* Waits for the process to end, however it ends, and closes its log.
+	*
+	* A process that never spawned reports `error` and one that ran reports `exit`, so the
+	* wait settles on either; a promise settles once, so the log is closed once.
+	*
+	* @returns {Promise<void>} Resolves after the exit, with the log closed.
+	*/
+	async function untilClosed() {
+		await new Promise((resolve) => {
+			child.once("exit", () => {
+				resolve();
+			});
+			child.once("error", () => {
+				resolve();
+			});
+		});
+		closeSync(log);
+	}
+	const exited = untilClosed();
+	return {
+		pid: child.pid ?? 0,
+		/**
+		* Asks the process to leave, kills it if it will not, and waits for the exit.
+		*
+		* @returns {Promise<void>} Resolves after the exit.
+		*/
+		stop: async () => {
+			child.kill("SIGTERM");
+			const killer = setTimeout(() => {
+				child.kill("SIGKILL");
+			}, GRACE_MS);
+			try {
+				await exited;
+			} finally {
+				clearTimeout(killer);
+			}
+		}
+	};
+}
+/**
+* Asks the operating system for a port and gives it straight back.
+*
+* @returns {Promise<number>} A port that was free when asked.
+*/
+function freePort() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const { port } = parse(BOUND_ADDRESS, server.address());
+			server.close(() => {
+				resolve(port);
+			});
+		});
+	});
+}
+/**
+* Builds the shell the tool runs under: real processes and real ports. `start` returns the
+* very process it spawned, so `stop` never reaches a process somebody else owns.
+*
+* @returns {Shell} A shell backed by real processes and real ports.
+*/
+function shell() {
+	return {
+		freePort,
+		run,
+		start
+	};
+}
+//#endregion
+//#region src/release/ranges.ts
+/**
+* @fileoverview Writes the range a published manifest carries where the workspace wrote the
+* `workspace:` protocol.
+*
+* Bun rewrites the protocol itself, but it takes the version from the lockfile, and nothing
+* updates the version a lockfile records for a workspace package: `changeset version` writes
+* the manifests alone, and `bun install`, `--force` and `--lockfile-only` all answer "no
+* changes". So bun ships the version from before the bump. A theme released at 0.1.0 asked
+* for `core-theme@^0.0.0`, and a caret on a `0.0.x` version excludes every later one, so no
+* consumer could install it.
+*
+* The release knows every version it is publishing, because it read the manifests to decide
+* what to publish. It writes the ranges from those rather than trusting the lockfile.
+*/
+/**
+* Names the blocks a manifest declares dependencies in.
+*/
+const DEPENDENCY_BLOCKS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+/**
+* Reads the workspace protocol and the range written after it.
+*/
+const WORKSPACE = /^workspace:(?<written>.*)$/u;
+/**
+* Writes the range that stands in for one workspace protocol.
+*
+* `*` pins the version exactly, which is what a package asking for whatever the workspace
+* holds means once the workspace is not there. `^` and `~` take that operator. Anything else
+* is a range somebody wrote by hand, and it is published as written.
+*
+* @param {string} written - The text after `workspace:`: `*`, `^`, `~` or a range.
+* @param {string} version - The version the depended-on package is being published at.
+* @returns {string} The range to publish.
+*/
+function rangeFor(written, version) {
+	if (written === "*" || written === "") return version;
+	if (written === "^" || written === "~") return `${written}${version}`;
+	return written;
+}
+/**
+* Rewrites every workspace protocol in one manifest against the versions being published.
+*
+* A dependency the workspace does not hold is left as it was written, because inventing a
+* range for it would publish a manifest nobody can explain. Packing then fails on the
+* protocol, which is the loud answer.
+*
+* @param {Declared} declared - The manifest, as it is written on disk.
+* @param {ReadonlyMap<string, string>} versions - Each workspace package mapped to the
+*     version it is being published at.
+* @returns {Declared} The manifest, with every protocol it could resolve written as a range.
+*/
+function resolvedRanges(declared, versions) {
+	const rewritten = { ...declared };
+	for (const block of DEPENDENCY_BLOCKS) {
+		const entries = declared[block];
+		if (typeof entries !== "object" || entries === null) continue;
+		rewritten[block] = Object.fromEntries(Object.entries(entries).map(([name, range]) => {
+			const version = versions.get(name);
+			const protocol = typeof range === "string" ? WORKSPACE.exec(range) : null;
+			if (version === void 0 || protocol?.groups === void 0) return [name, range];
+			return [name, rangeFor(String(protocol.groups["written"]), version)];
+		}));
+	}
+	return rewritten;
+}
+//#endregion
+//#region src/release/packages.ts
+/**
+* @fileoverview Packs a built package into a tarball with bun and publishes the tarball
+* with npm. The tarball comes from bun, because bun rewrites `workspace:^` and `catalog:`
+* into ranges; the upload goes through npm, because npm can attest provenance and bun
+* cannot. The access comes from the manifest's `publishConfig`, which npm reads from the
+* tarball, and so does the registry when the manifest names one.
+*/
+/**
+* Matches a glob character in a `files` entry, which names more than one path.
+*/
+const GLOB = /[*?[{]/u;
+/**
+* Joins everything a command wrote on both streams.
+*
+* @param {CommandOutcome} outcome - The command's exit code and both streams.
+* @returns {string} Stdout, then stderr.
+*/
+function outputOf(outcome) {
+	return `${outcome.stdout}\n${outcome.stderr}`;
+}
+/**
+* Lists the paths a manifest's `files` names that are missing from the package. A glob
+* entry names no one path and is not checked; a manifest without `files` names nothing.
+*
+* @param {Manifest} manifest - The package to check.
+* @returns {string[]} The missing paths, relative to the package, in `files` order.
+*/
+function missingFiles(manifest) {
+	return (manifest.files ?? []).filter((file) => !GLOB.test(file) && !existsSync(join(manifest.directory, file)));
+}
+/**
+* Reads a manifest's text as the object the rewrite works on.
+*
+* It refuses anything that is not an object rather than answering an empty one, because the
+* answer is written back over the file: a manifest this could not read would be replaced by
+* `{}`. It throws before anything is written, so the package is left as it was found.
+*
+* @param {string} text - The manifest as it is written on disk.
+* @returns {Declared} The manifest.
+* @throws {Error} When the text parses to anything but an object.
+*/
+function declaredIn(text) {
+	const parsed = JSON.parse(text);
+	if (typeof parsed !== "object" || parsed === null) throw new Error(`a manifest is an object, and this one parsed to ${typeof parsed}`);
+	return Object.fromEntries(Object.entries({ ...parsed }));
+}
+/**
+* Runs one step with the package's manifest holding real ranges instead of the workspace
+* protocol, and writes back what was there however the step ended.
+*
+* The manifest is written rather than the tarball patched, because bun packs what is on
+* disk: with no protocol left there is nothing for it to rewrite out of a stale lockfile.
+* The original text goes back byte for byte, so a manifest a person formatted stays as they
+* wrote it. A caller naming no versions has nothing to write, and the file is left alone.
+*
+* @template Result - The value the step answers with.
+* @param {Manifest} manifest - The package being packed.
+* @param {ReadonlyMap<string, string>} versions - Each workspace package mapped to the
+*     version it is being published at.
+* @param {() => Promise<Result>} step - The work to run while the ranges are written.
+* @returns {Promise<Result>} The step's own answer, unchanged.
+*/
+async function written(manifest, versions, step) {
+	if (versions.size === 0) return step();
+	const path = join(manifest.directory, "package.json");
+	const before = readFileSync(path, "utf8");
+	const after = resolvedRanges(declaredIn(before), versions);
+	writeFileSync(path, `${JSON.stringify(after, void 0, 2)}\n`);
+	try {
+		return await step();
+	} finally {
+		writeFileSync(path, before);
+	}
+}
+/**
+* Packs one built package into the destination directory.
+*
+* @param {Manifest} manifest - The package to pack.
+* @param {string} destination - The directory the tarball goes into.
+* @param {Shell} shell - The shell that runs bun.
+* @param {ReadonlyMap<string, string>} [versions] - Each workspace package mapped to the
+*     version it is being published at. Default: none, leaving every range as written.
+* @returns {Promise<PackResult>} The step, and the tarball when there is one.
+*/
+async function pack(manifest, destination, shell, versions = /* @__PURE__ */ new Map()) {
+	const name = `pack ${manifest.name}`;
+	const outcome = await written(manifest, versions, () => shell.run("bun", [
+		"pm",
+		"pack",
+		"--destination",
+		destination,
+		"--quiet"
+	], { cwd: manifest.directory }));
+	const tarball = outcome.stdout.split("\n").map((line) => line.trim()).findLast((line) => line.endsWith(".tgz"));
+	if (outcome.code !== 0 || tarball === void 0) return { step: failed(name, lastLines(outputOf(outcome))) };
+	return {
+		packed: {
+			manifest,
+			tarball: resolve(destination, tarball)
+		},
+		step: passed(name, tarball)
+	};
+}
+/**
+* Publishes one tarball with npm. The token, when there is one, travels in a user config
+* file npm is pointed at, so nothing else npm reads is touched.
+*
+* The run's registry is passed on the command line rather than the manifest's. Npm reads
+* `publishConfig.registry` out of the tarball and lets it win over the flag, which is the
+* rule the asking side applies as well.
+*
+* @param {string} tarball - The tarball to publish, absolute.
+* @param {string} cwd - The directory npm runs in.
+* @param {PublishOptions} options - How to publish. `PublishOptions` documents every member.
+* @param {Shell} shell - The shell that runs npm.
+* @returns {Promise<CommandOutcome>} Npm's exit code and both streams.
+*/
+function publishTarball(tarball, cwd, options, shell) {
+	const args = ["publish", tarball];
+	if (options.dryRun) args.push("--dry-run");
+	if (options.provenance) args.push("--provenance");
+	if (options.registry !== void 0) args.push("--registry", options.registry);
+	return shell.run("npm", args, {
+		cwd,
+		env: options.userconfig === void 0 ? void 0 : { NPM_CONFIG_USERCONFIG: options.userconfig }
+	});
+}
+//#endregion
+//#region src/release/registry.ts
+/**
+* @fileoverview Asks a registry what it has: which registry npm is configured for, and
+* whether it already holds a version of a package.
+*/
+/**
+* Accepts the document a registry answers for a package, in the one field the tool reads.
+*/
+const PACKUMENT = looseObject({ versions: optional(record(string(), unknown())) });
+/**
+* Ends a registry URL with the slash bun and npm write.
+*
+* @param {string} url - The registry as npm or a manifest names it.
+* @returns {string} The URL with exactly one trailing slash.
+*/
+function withTrailingSlash(url) {
+	return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+* Asks npm for the registry it is configured to publish to.
+*
+* Ask this in the directory the publish will run in. Npm reads its configuration, and the
+* manifest beside it, from where it runs, so asking anywhere else can name a registry the
+* publish will not use, and asking in a workspace whose manifest names another package
+* manager makes npm refuse outright.
+*
+* @param {Shell} shell - The shell that runs npm.
+* @param {string} cwd - The directory the publish will run in.
+* @returns {Promise<string>} The registry, with its trailing slash.
+* @throws {Error} When npm names no registry.
+*/
+async function configuredRegistry(shell, cwd) {
+	const outcome = await shell.run("npm", [
+		"config",
+		"get",
+		"registry"
+	], { cwd });
+	const url = outcome.stdout.trim();
+	if (outcome.code !== 0 || url === "") throw new Error(`npm names no registry: ${lastLines(`${outcome.stdout}\n${outcome.stderr}`)}`);
+	return withTrailingSlash(url);
+}
+/**
+* Returns `true` when the registry already holds this version of the package.
+*
+* @param {string} registry - The registry, with its trailing slash.
+* @param {Manifest} manifest - The package to ask about.
+* @param {typeof fetch} fetchImpl - The fetch that asks the registry.
+* @returns {Promise<boolean>} `true` when that exact version is there.
+* @throws {Error} When the registry answers with anything but the package or a 404.
+*/
+async function registryHasVersion(registry, manifest, fetchImpl) {
+	const response = await fetchImpl(`${registry}${manifest.name.replace("/", "%2F")}`);
+	if (response.status === 404) return false;
+	if (!response.ok) throw new Error(`${registry} answered ${response.status} for ${manifest.name}`);
+	const { versions } = parse(PACKUMENT, await response.json());
+	return manifest.version in (versions ?? {});
+}
+//#endregion
+//#region src/release/release.ts
+/**
+* @fileoverview Publishes every public package of a workspace the registry does not have
+* yet, in dependency order, from a workspace that is already built.
+*/
+/**
+* Collects the release set: every public package of the workspace and every workspace
+* package it depends on, dependencies before dependents.
+*
+* @param {string} root - The workspace root.
+* @returns {ReleaseSet} The set, and the private packages it would need and cannot have.
+*/
+function releaseSet(root) {
+	const manifests = workspaceManifests(root);
+	const roots = manifests.filter((manifest) => !manifest.private).map((manifest) => manifest.name);
+	const { ordered } = dependencyClosure(roots, manifests);
+	return {
+		hidden: ordered.filter((manifest) => manifest.private).map((manifest) => manifest.name),
+		ordered: ordered.filter((manifest) => !manifest.private)
+	};
+}
+/**
+* Releases one package: skips it when the registry has the version, refuses it when a path
+* its `files` names is missing, and packs and publishes it otherwise.
+*
+* @param {Manifest} manifest - The package to release.
+* @param {Publishing} publishing - The registry to ask and the versions going out.
+*     `Publishing` documents every member.
+* @param {ReleaseOptions} options - How to publish, and where the tarballs go.
+* @param {Shell} shell - The shell that runs bun and npm.
+* @returns {Promise<Released>} The step, and the tag entry when the package went out.
+*/
+async function releaseOne(manifest, publishing, options, shell) {
+	const { registry, versions } = publishing;
+	const name = `publish ${manifest.name}@${manifest.version}`;
+	if (await registryHasVersion(manifest.registry === void 0 ? registry : withTrailingSlash(manifest.registry), manifest, options.fetch)) return { step: passed(name, "already on the registry") };
+	const missing = missingFiles(manifest);
+	if (missing.length > 0) return { step: failed(name, `not built: ${missing.join(", ")} missing`) };
+	const { packed, step } = await pack(manifest, options.tarballs, shell, versions);
+	if (packed === void 0) return { step };
+	const outcome = await publishTarball(packed.tarball, options.tarballs, options, shell);
+	if (outcome.code !== 0) return { step: failed(name, lastLines(`${outcome.stdout}\n${outcome.stderr}`)) };
+	if (options.dryRun) return { step: passed(name, "dry run") };
+	return {
+		step: passed(name, "published"),
+		tag: tagEvent(manifest)
+	};
+}
+/**
+* Releases the packages one after another, dependencies first, and stops at the first
+* failure: a dependent published without its dependency is a package nobody can install.
+*
+* @param {readonly Manifest[]} ordered - The packages, dependencies first.
+* @param {string} registry - The registry to ask, unless a manifest names its own.
+* @param {ReleaseOptions} options - How to publish, and where the tarballs go.
+* @param {Shell} shell - The shell that runs bun and npm.
+* @returns {Promise<Released[]>} One entry per package, in the order they were tried.
+*/
+function releaseAll(ordered, registry, options, shell) {
+	const versions = new Map(ordered.map((manifest) => [manifest.name, manifest.version]));
+	return ordered.reduce(async (before, manifest) => {
+		const done = await before;
+		if (done.some(({ step }) => !step.ok)) {
+			const name = `publish ${manifest.name}@${manifest.version}`;
+			return [...done, { step: failed(name, "not attempted: an earlier publish failed") }];
+		}
+		return [...done, await releaseOne(manifest, {
+			registry,
+			versions
+		}, options, shell)];
+	}, Promise.resolve([]));
+}
+/**
+* Releases every package of the set the registry does not have yet, packed and published in
+* dependency order. It refuses the whole set when the set depends on a private package.
+*
+* @param {ReleaseOptions} options - The registry, how to publish, the workspace and where
+*     the tarballs go.
+* @param {Shell} shell - The shell that runs bun and npm.
+* @returns {Promise<Report>} Every step, in order.
+*/
+async function release(options, shell) {
+	const { hidden, ordered } = releaseSet(options.root);
+	if (hidden.length > 0) return {
+		steps: [failed("release set", `private, so nothing that depends on them can be installed: ${hidden.join(", ")}`)],
+		workdir: options.tarballs
+	};
+	mkdirSync(options.tarballs, { recursive: true });
+	const registry = options.registry === void 0 ? await configuredRegistry(shell, options.tarballs) : withTrailingSlash(options.registry);
+	const released = await releaseAll(ordered, registry, options, shell);
+	if (options.changesetsOutput !== void 0) writeTagEvents(options.changesetsOutput, released.flatMap(({ tag }) => tag === void 0 ? [] : [tag]));
+	return {
+		steps: [passed("release set", `${ordered.length} packages to ${registry}`), ...released.map(({ step }) => step)],
+		workdir: options.tarballs
+	};
+}
+//#endregion
+//#region src/release/command.ts
+/**
+* @fileoverview The `stealth release` command: what it takes from the command line, and how
+* it turns that into a release run. Everything the run touches from outside arrives as a
+* dependency, so a specification drives the whole command without a registry or a process.
+*/
+/**
+* Prefixes the directory the tarballs are written to, so a leftover run is recognisable in
+* the temporary directory.
+*/
+const TARBALL_PREFIX = "stealth-release-";
+/**
+* What `stealth release` takes from the command line.
+*
+* The registry and the token are absent by default: npm reads its own configuration, and a
+* manifest's `publishConfig` overrides it per package. Naming either here is for a run that
+* publishes somewhere else, such as a local registry in a smoke test.
+*/
+const RELEASE_ARGS = {
+	"dry-run": {
+		default: false,
+		description: "Report what would be published, and publish nothing.",
+		type: "boolean"
+	},
+	provenance: {
+		default: false,
+		description: "Attest provenance through the CI job's token. Npm refuses it elsewhere.",
+		type: "boolean"
+	},
+	registry: {
+		description: "Publish to this registry instead of the one npm is configured for.",
+		type: "string",
+		valueHint: "url"
+	},
+	tarballs: {
+		description: "Write the tarballs here instead of a new temporary directory.",
+		type: "string",
+		valueHint: "dir"
+	},
+	userconfig: {
+		description: "Read npm's configuration, and so the token, from this file.",
+		type: "string",
+		valueHint: "file"
+	}
+};
+/**
+* Runs a release from the parsed command line and reports it.
+*
+* The exit code is set rather than thrown: a failed publish is an outcome the report already
+* explains, and throwing would print a stack trace over it.
+*
+* @param {ParsedArgs<typeof RELEASE_ARGS>} args - The command line, as citty parsed it.
+* @param {ReleaseDeps} deps - The workspace, the registry, the shell and where to write.
+* @returns {Promise<void>} Resolves once the report is written.
+*/
+async function runRelease(args, deps) {
+	const report = await release({
+		changesetsOutput: deps.changesetsOutput,
+		dryRun: args["dry-run"],
+		fetch: deps.fetch,
+		provenance: args.provenance,
+		registry: args.registry,
+		root: workspaceRoot(deps.cwd),
+		tarballs: args.tarballs ?? mkdtempSync(join(tmpdir(), TARBALL_PREFIX)),
+		userconfig: args.userconfig
+	}, deps.shell);
+	deps.log(render(report));
+	if (failures(report).length > 0) process.exitCode = 1;
+}
+/**
+* Builds the release command against the outside world it is given.
+*
+* @param {ReleaseDeps} deps - The workspace, the registry, the shell and where to write.
+* @returns {CommandDef} The command, ready to hand to citty.
+*/
+function releaseCommandWith(deps) {
+	return defineCommand({
+		args: RELEASE_ARGS,
+		meta: {
+			description: "Publish every public package the registry does not have yet.",
+			name: "release"
+		},
+		/**
+		* Runs the release the command line asks for.
+		*
+		* @param {CommandContext<typeof RELEASE_ARGS>} context - The command line, as citty
+		*     parsed it.
+		* @returns {Promise<void>} Resolves once the report is written.
+		*/
+		run: ({ args }) => runRelease(args, deps)
+	});
+}
+/**
+* The release command as the `stealth` bin runs it: this process, the real registry, a real
+* shell and the terminal.
+*/
+const releaseCommand = releaseCommandWith({
+	changesetsOutput: process.env["CHANGESETS_OUTPUT"],
+	cwd: process.cwd(),
+	fetch,
+	log: process.stdout.write.bind(process.stdout),
+	shell: shell()
+});
+//#endregion
+export { tagEvent as _, configuredRegistry as a, missingFiles as c, shell as d, failed as f, render as g, passed as h, releaseSet as i, pack as l, lastLines as m, releaseCommandWith as n, registryHasVersion as o, failures as p, release as r, withTrailingSlash as s, releaseCommand as t, publishTarball as u, writeTagEvents as v };