@moku-labs/ci 1.0.0

package/dist/release.mjs

@@ -0,0 +1,2497 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile, spawn } from "node:child_process";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+//#region node_modules/@moku-labs/common/dist/cli.mjs
+/**
+* @file `@moku-labs/common/cli` — TTY/`NO_COLOR`-aware ANSI color + box-drawing
+* primitives: the shared "brand DNA" every Moku CLI renders through (the brand pink,
+* the palette, the box/spinner/progress glyphs). Color and Unicode glyphs are emitted
+* only on a real TTY with `NO_COLOR` unset; otherwise plain ASCII so CI logs and pipes
+* stay readable. Pure: depends on nothing but `process.stdout`/`process.env` defaults,
+* so a consuming framework can build its own panels on top without pulling in any UI lib.
+*/
+/** The ANSI escape byte (ESC, `0x1b`), built so no literal control char is in source. */
+const ESC = String.fromCodePoint(27);
+/** ANSI SGR codes used by the brand renderer (each prefixed with the ESC byte). */
+const ANSI = {
+	reset: `${ESC}[0m`,
+	bold: `${ESC}[1m`,
+	dim: `${ESC}[2m`,
+	red: `${ESC}[31m`,
+	green: `${ESC}[32m`,
+	yellow: `${ESC}[33m`,
+	blue: `${ESC}[34m`,
+	magenta: `${ESC}[35m`,
+	cyan: `${ESC}[36m`,
+	gray: `${ESC}[90m`
+};
+/**
+* The Moku brand pink (`#FF1E6F`) as an RGB triple, used for 24-bit truecolor output.
+* Degrades to {@link ANSI.magenta} on a 16-color TTY and to plain text off a TTY.
+*/
+const BRAND_PINK = {
+	r: 255,
+	g: 30,
+	b: 111
+};
+/**
+* Build a 24-bit (truecolor) SGR foreground escape for the given RGB triple.
+*
+* @param r - Red channel (0–255).
+* @param g - Green channel (0–255).
+* @param b - Blue channel (0–255).
+* @returns The `ESC[38;2;r;g;bm` foreground sequence.
+* @example
+* fg24(255, 30, 111); // "\x1b[38;2;255;30;111m"
+*/
+function fg24(r, g, b) {
+	return `${ESC}[38;2;${r};${g};${b}m`;
+}
+`${ESC}`;
+`${ESC}`;
+/** Unicode rounded box glyphs used when output is a color-capable TTY. */
+const UNICODE_BOX = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│"
+};
+/** ASCII box glyphs used when output is piped/CI (plain mode). */
+const ASCII_BOX = {
+	topLeft: "+",
+	topRight: "+",
+	bottomLeft: "+",
+	bottomRight: "+",
+	horizontal: "-",
+	vertical: "|"
+};
+/**
+* Matches every ANSI SGR escape sequence (used to measure visible width). Built from
+* the {@link ESC} byte so no literal control character appears in the source regex.
+*/
+const ANSI_PATTERN = new RegExp(String.raw`${ESC}\[[0-9;]*m`, "g");
+/**
+* Whether ANSI color/box glyphs should be emitted: a TTY stream with `NO_COLOR`
+* unset. Reads `process.stdout.isTTY` and `process.env.NO_COLOR` by default so the
+* renderer auto-degrades in CI and pipes.
+*
+* @param stream - Stream to probe for `isTTY` (defaults to `process.stdout`).
+* @param noColor - The `NO_COLOR` value (defaults to `process.env.NO_COLOR`).
+* @returns `true` when color should be used.
+* @example
+* supportsColor(); // true in an interactive terminal
+*/
+function supportsColor(stream = process.stdout, noColor = process.env.NO_COLOR) {
+	return stream.isTTY === true && noColor === void 0;
+}
+/**
+* Whether the terminal advertises 24-bit (truecolor) support via `COLORTERM`, so the
+* renderer may emit the exact brand pink ({@link BRAND_PINK}) instead of the 16-color
+* `magenta` approximation. Always layered on top of {@link supportsColor} — truecolor
+* is never used when color itself is disabled.
+*
+* @param colorTerm - The `COLORTERM` value (defaults to `process.env.COLORTERM`).
+* @returns `true` when `COLORTERM` is `truecolor` or `24bit`.
+* @example
+* supportsTruecolor("truecolor"); // true
+*/
+function supportsTruecolor(colorTerm = process.env.COLORTERM) {
+	return colorTerm === "truecolor" || colorTerm === "24bit";
+}
+/**
+* Select the box glyph set for the given color mode (Unicode on a TTY, ASCII off it).
+*
+* @param color - Whether color/Unicode output is enabled.
+* @returns The matching {@link BoxGlyphs} set.
+* @example
+* const glyphs = boxGlyphs(supportsColor());
+*/
+function boxGlyphs(color) {
+	return color ? UNICODE_BOX : ASCII_BOX;
+}
+/**
+* The visible width of a string, ignoring any ANSI escape sequences it contains.
+*
+* @param text - The (possibly colorized) text to measure.
+* @returns The number of visible characters.
+* @example
+* visibleWidth(`${ANSI.red}hi${ANSI.reset}`); // 2
+*/
+function visibleWidth(text) {
+	return text.replaceAll(ANSI_PATTERN, "").length;
+}
+/**
+* Build a {@link Palette} bound to a fixed color mode. When `color` is `false` every
+* helper returns its input unchanged, so the same render code path produces plain
+* output in CI/pipes.
+*
+* @param color - Whether color is enabled (typically `supportsColor()`).
+* @param truecolor - Whether 24-bit output is enabled (typically `supportsTruecolor()`);
+*   only consulted by {@link Palette.pink}. Defaults to `false` (16-color magenta).
+* @returns The bound color palette.
+* @example
+* const palette = makePalette(supportsColor(), supportsTruecolor());
+* const line = palette.green("done");
+*/
+function makePalette(color, truecolor = false) {
+	return {
+		enabled: color,
+		/**
+		* Wrap text in the given ANSI code (returns it unchanged when color is off).
+		*
+		* @param code - The ANSI SGR code to apply.
+		* @param text - The text to colorize.
+		* @returns The colorized (or unchanged) text.
+		* @example
+		* palette.paint(ANSI.green, "ok");
+		*/
+		paint(code, text) {
+			return color ? `${code}${text}${ANSI.reset}` : text;
+		},
+		/**
+		* Bold the given text (no-op in plain mode).
+		*
+		* @param text - The text to embolden.
+		* @returns The bold (or unchanged) text.
+		* @example
+		* palette.bold("title");
+		*/
+		bold(text) {
+			return this.paint(ANSI.bold, text);
+		},
+		/**
+		* Dim the given text (no-op in plain mode).
+		*
+		* @param text - The text to dim.
+		* @returns The dim (or unchanged) text.
+		* @example
+		* palette.dim("· 84ms");
+		*/
+		dim(text) {
+			return this.paint(ANSI.dim, text);
+		},
+		/**
+		* Color the given text green (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The green (or unchanged) text.
+		* @example
+		* palette.green("✓");
+		*/
+		green(text) {
+			return this.paint(ANSI.green, text);
+		},
+		/**
+		* Color the given text yellow (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The yellow (or unchanged) text.
+		* @example
+		* palette.yellow("~");
+		*/
+		yellow(text) {
+			return this.paint(ANSI.yellow, text);
+		},
+		/**
+		* Color the given text red (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The red (or unchanged) text.
+		* @example
+		* palette.red("✗");
+		*/
+		red(text) {
+			return this.paint(ANSI.red, text);
+		},
+		/**
+		* Color the given text cyan (no-op in plain mode).
+		*
+		* @param text - The text to colorize.
+		* @returns The cyan (or unchanged) text.
+		* @example
+		* palette.cyan("http://localhost:4173");
+		*/
+		cyan(text) {
+			return this.paint(ANSI.cyan, text);
+		},
+		/**
+		* Color the given text the Moku brand pink: exact `#FF1E6F` (24-bit) when truecolor
+		* is enabled, the 16-color `magenta` approximation otherwise, unchanged in plain mode.
+		*
+		* @param text - The text to colorize.
+		* @returns The pink (or unchanged) text.
+		* @example
+		* palette.pink("▟▙ moku web");
+		*/
+		pink(text) {
+			if (!color) return text;
+			if (truecolor) return `${fg24(BRAND_PINK.r, BRAND_PINK.g, BRAND_PINK.b)}${text}${ANSI.reset}`;
+			return this.paint(ANSI.magenta, text);
+		}
+	};
+}
+/**
+* Frame a list of already-rendered content lines in a box, padding each line to the
+* widest visible line (or `minInnerWidth`, whichever is larger — so several boxes can be
+* forced to a shared width). Uses Unicode borders when `color` is enabled and ASCII
+* otherwise. Visible width ignores embedded ANSI so colored lines align.
+*
+* @param lines - The content lines (may contain ANSI color codes).
+* @param color - Whether to use Unicode borders (and assume color-capable output).
+* @param minInnerWidth - Minimum inner (content) width to pad every row to. Defaults to `0`.
+* @returns The boxed lines (top border, content rows, bottom border).
+* @example
+* box(["Local:   http://localhost:4173"], true, 62);
+*/
+function box(lines, color, minInnerWidth = 0) {
+	const glyphs = boxGlyphs(color);
+	const inner = Math.max(0, minInnerWidth, ...lines.map((line) => visibleWidth(line)));
+	const horizontal = glyphs.horizontal.repeat(inner + 2);
+	const top = `${glyphs.topLeft}${horizontal}${glyphs.topRight}`;
+	const bottom = `${glyphs.bottomLeft}${horizontal}${glyphs.bottomRight}`;
+	return [
+		top,
+		...lines.map((line) => {
+			const pad = " ".repeat(inner - visibleWidth(line));
+			return `${glyphs.vertical} ${line}${pad} ${glyphs.vertical}`;
+		}),
+		bottom
+	];
+}
+/**
+* @file `@moku-labs/common/cli` — the branded console: the shared, **stateless** line
+* vocabulary every Moku CLI prints through so the look never drifts between projects.
+* It is the generic counterpart to a framework's own (stateful) panels: the `▟▙` lockup
+* banner, section `heading`s, `info`/`warn`/`error` lines, `✓/✗ check` rows, plus the
+* `railLine`/`box` builders a project composes its own panels from. Built entirely on the
+* {@link makePalette} primitives, TTY/`NO_COLOR`-aware, every line routed through an
+* injectable sink so tests capture output (and a non-CLI consumer can redirect it).
+*/
+/** Default total visible width the lockup rule spans and `railLine` right-aligns to. */
+const DEFAULT_WIDTH$1 = 66;
+/**
+* Create a {@link BrandConsole}. Output flows through the injected sink (default
+* `console.log`/`console.error`) and is colorized only when color is enabled, so the
+* identical render path yields branded color/Unicode on a TTY and plain ASCII in CI/pipes.
+*
+* @param options - Optional sinks, color/truecolor overrides, and width (see
+*   {@link BrandConsoleOptions}).
+* @returns The branded console.
+* @example
+* const ui = createBrandConsole();
+* ui.lockup({ wordmark: "moku tool", version: "v1.0.0" });
+* ui.check(true, "config loaded");
+*/
+function createBrandConsole(options = {}) {
+	const write = options.write ?? ((line) => console.log(line));
+	const writeError = options.writeError ?? ((line) => console.error(line));
+	const color = options.color ?? supportsColor();
+	const palette = makePalette(color, options.truecolor ?? (color && supportsTruecolor()));
+	const width = options.width ?? DEFAULT_WIDTH$1;
+	const cube = color ? "▟▙" : "*";
+	const rule = color ? "─" : "-";
+	/**
+	* Right-align `right` against `left` within `lineWidth`, measuring visible width so
+	* embedded ANSI never throws the alignment off.
+	*
+	* @param left - The left segment (may contain ANSI).
+	* @param right - The right segment (may contain ANSI).
+	* @param lineWidth - Total visible width to fill (defaults to the console width).
+	* @returns The padded line.
+	* @example
+	* railLine("left", "right", 20);
+	*/
+	const railLine = (left, right, lineWidth = width) => {
+		const gap = Math.max(1, lineWidth - visibleWidth(left) - visibleWidth(right));
+		return `${left}${" ".repeat(gap)}${right}`;
+	};
+	return {
+		palette,
+		color,
+		width,
+		/**
+		* Write a pre-rendered line verbatim through the stdout sink.
+		*
+		* @param text - The line to write (defaults to an empty line).
+		* @example
+		* ui.line("  custom row");
+		*/
+		line(text = "") {
+			write(text);
+		},
+		/**
+		* Render the `▟▙ <wordmark>` lockup (cube + bold-pink wordmark + optional label,
+		* version right-aligned), a dim hairline rule, and an optional dim facts line.
+		*
+		* @param opts - The lockup fields (see {@link LockupOptions}).
+		* @example
+		* ui.lockup({ wordmark: "moku web", label: "build", version: "v1.2.0" });
+		*/
+		lockup(opts) {
+			const wordmark = palette.pink(palette.bold(opts.wordmark));
+			const label = opts.label ? `  ${palette.dim(opts.label)}` : "";
+			write(railLine(` ${palette.pink(cube)} ${wordmark}${label}`, opts.version ? palette.dim(opts.version) : ""));
+			write(` ${palette.dim(rule.repeat(width - 1))}`);
+			if (opts.facts !== void 0) write(` ${palette.dim(opts.facts)}`);
+		},
+		/**
+		* Render a section heading: a blank line followed by a bold brand-pink label.
+		*
+		* @param text - The heading label.
+		* @example
+		* ui.heading("Diagnostics");
+		*/
+		heading(text) {
+			write("");
+			write(`  ${palette.bold(palette.pink(text))}`);
+		},
+		/**
+		* Render a neutral informational line (`› message`), indenting continuation lines.
+		*
+		* @param message - The line to print.
+		* @example
+		* ui.info("watching for changes…");
+		*/
+		info(message) {
+			const [first = "", ...rest] = message.split("\n");
+			write(`  ${palette.cyan("›")} ${first}`);
+			for (const lineText of rest) write(`    ${lineText}`);
+		},
+		/**
+		* Render a warning line (`⚠ message`, to stderr).
+		*
+		* @param message - The warning to print.
+		* @example
+		* ui.warn("deploy skipped");
+		*/
+		warn(message) {
+			writeError(`  ${palette.yellow("⚠")} ${message}`);
+		},
+		/**
+		* Render an error line (`✗ message`, to stderr), optionally with a cause beneath.
+		*
+		* @param message - The error summary to print.
+		* @param cause - Optional underlying error/value printed beneath the summary.
+		* @example
+		* ui.error("build failed", err);
+		*/
+		error(message, cause) {
+			writeError(`  ${palette.red("✗")} ${message}`);
+			if (cause !== void 0) writeError(String(cause));
+		},
+		/**
+		* Render a diagnostic line — green `✓` / red `✗` + label, with optional dim,
+		* indented detail beneath.
+		*
+		* @param ok - Whether the check passed.
+		* @param label - The check label.
+		* @param detail - Optional multi-line guidance shown indented under the line.
+		* @example
+		* ui.check(true, "config loaded");
+		*/
+		check(ok, label, detail) {
+			write(`  ${ok ? palette.green("✓") : palette.red("✗")} ${label}`);
+			if (detail !== void 0) for (const lineText of detail.split("\n")) write(`      ${palette.dim(lineText)}`);
+		},
+		railLine,
+		/**
+		* Frame the given content lines in a brand box and write the result.
+		*
+		* @param lines - The content lines (may contain ANSI).
+		* @param minInnerWidth - Minimum inner width to pad every row to. Defaults to `0`.
+		* @example
+		* ui.box(["Local    http://localhost:4173"]);
+		*/
+		box(lines, minInnerWidth = 0) {
+			for (const lineText of box(lines, color, minInnerWidth)) write(lineText);
+		}
+	};
+}
+/**
+* @file `@moku-labs/common/cli` — branded interactive prompts (`confirm` y/N and
+* `select` one-of-N) styled with the brand `◆` marker, the dim hint, and the cyan `›`
+* caret, so a guided flow in any Moku CLI looks the same. Built on `node:readline`; the
+* input/output streams and the choices-block sink are injectable so tests drive prompts
+* without a real TTY. Off a color TTY (CI/pipes) every prompt degrades to a plain form.
+*/
+/** Default prompt rail width — matches the brand console so hints align with other rows. */
+const DEFAULT_WIDTH = 66;
+/** Matches an explicit affirmative answer (`y`/`yes`, case-insensitive). */
+const YES_PATTERN = /^y(es)?$/i;
+/**
+* Create {@link BrandPrompts} bound to a color mode + streams. Styling matches the brand
+* console (the `◆` marker, dim hints, cyan caret); off a color TTY every prompt uses the
+* plain `question [y/N]` / `question [1-N]` form.
+*
+* @param options - Optional color/width overrides and injectable streams/sink (see
+*   {@link BrandPromptsOptions}).
+* @returns The branded prompts.
+* @example
+* const prompts = createBrandPrompts();
+* const i = await prompts.select("Workflow?", ["Auto", "Manual"]);
+*/
+function createBrandPrompts(options = {}) {
+	const color = options.color ?? supportsColor();
+	const palette = makePalette(color, options.truecolor ?? (color && supportsTruecolor()));
+	const width = options.width ?? DEFAULT_WIDTH;
+	const input = options.input ?? process.stdin;
+	const output = options.output ?? process.stdout;
+	const write = options.write ?? ((block) => console.log(block));
+	/**
+	* Build the y/N prompt string: the styled `◆ question … y / N ›` rail on a color TTY,
+	* else the plain `question [y/N] ` form.
+	*
+	* @param question - The yes/no question to display.
+	* @returns The readline prompt string.
+	* @example
+	* confirmPrompt("Deploy?");
+	*/
+	const confirmPrompt = (question) => {
+		if (!color) return `${question} [y/N] `;
+		const left = `  ${palette.pink("◆")} ${question}`;
+		const right = `${palette.dim("y / N")} ${palette.cyan("›")} `;
+		const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+		return `${left}${" ".repeat(gap)}${right}`;
+	};
+	/**
+	* Build the select choices block: the styled `◆ question` head + dim-numbered rows on a
+	* color TTY, else the plain `  N) label` list.
+	*
+	* @param question - The prompt shown above the choices (styled mode only).
+	* @param choices - The selectable option labels.
+	* @returns The multi-line choices block.
+	* @example
+	* choicesBlock("Pick", ["a", "b"]);
+	*/
+	const choicesBlock = (question, choices) => {
+		if (!color) return choices.map((choice, index) => `  ${index + 1}) ${choice}`).join("\n");
+		return [`  ${palette.pink("◆")} ${question}`, ...choices.map((choice, index) => `      ${palette.dim(String(index + 1))}  ${choice}`)].join("\n");
+	};
+	/**
+	* Build the select input prompt: the dim `pick 1–N ›` hint on a color TTY, else the
+	* plain `question [1-N] ` form.
+	*
+	* @param question - The prompt (used only by the plain fallback).
+	* @param count - The number of choices.
+	* @returns The readline prompt string.
+	* @example
+	* selectPrompt("Pick", 3);
+	*/
+	const selectPrompt = (question, count) => {
+		if (!color) return `${question} [1-${count}] `;
+		return `    ${palette.dim(`pick 1–${count}`)} ${palette.cyan("›")} `;
+	};
+	return {
+		/**
+		* Ask a yes/no question; resolves `true` only on an explicit `y`/`yes`.
+		*
+		* @param question - The yes/no question to display.
+		* @returns Resolves `true` when the user answered yes.
+		* @example
+		* await prompts.confirm("Deploy?");
+		*/
+		confirm(question) {
+			return new Promise((resolve) => {
+				const readline = createInterface({
+					input,
+					output
+				});
+				readline.question(confirmPrompt(question), (answer) => {
+					readline.close();
+					resolve(YES_PATTERN.test(answer.trim()));
+				});
+			});
+		},
+		/**
+		* Present `choices` numbered from 1 and resolve the chosen zero-based index.
+		*
+		* @param question - The prompt to display.
+		* @param choices - The selectable option labels.
+		* @returns Resolves the chosen zero-based index (`0` for empty/out-of-range).
+		* @example
+		* await prompts.select("Pick", ["a", "b"]);
+		*/
+		select(question, choices) {
+			return new Promise((resolve) => {
+				const readline = createInterface({
+					input,
+					output
+				});
+				write(choicesBlock(question, choices));
+				readline.question(selectPrompt(question, choices.length), (answer) => {
+					readline.close();
+					const picked = Number.parseInt(answer.trim(), 10);
+					resolve(Number.isInteger(picked) && picked >= 1 && picked <= choices.length ? picked - 1 : 0);
+				});
+			});
+		}
+	};
+}
+//#endregion
+//#region src/lib/git.ts
+/**
+* @file `moku-release` — git vocabulary as pure functions: remote-URL normalization, the
+* `owner/repo` slug, and the latest `v*` tag.
+*
+* The one piece of git *invocation* that lives here is {@link LATEST_TAG_ARGS}: the tag
+* listing must run with `versionsort.suffix=-` so `v1.0.0-rc.1` sorts BELOW `v1.0.0`
+* instead of above it. Keeping the argv next to the parser stops the two drifting apart.
+*/
+/** Argv for listing release tags newest-first with prereleases ordered correctly. */
+const LATEST_TAG_ARGS = [
+	"-c",
+	"versionsort.suffix=-",
+	"tag",
+	"--list",
+	"v*",
+	"--sort=-v:refname"
+];
+/** Matches the `owner/repo` pair in any GitHub remote form (ssh, https, with or without `.git`). */
+const OWNER_REPO_PATTERN = /github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/;
+/**
+* Reduce any remote form to a comparable canonical one: `git+` prefix dropped, `.git`
+* suffix dropped, `git@host:owner/repo` rewritten as `https://host/owner/repo`, trailing
+* slash and surrounding whitespace removed.
+*
+* @param url - A remote URL from `package.json` or `git remote get-url`.
+* @returns The canonical `https://host/owner/repo` form.
+* @example
+* normalizeRemoteUrl("git+https://github.com/moku-labs/common.git");
+* // "https://github.com/moku-labs/common"
+*/
+function normalizeRemoteUrl(url) {
+	return url.trim().replace(/^git\+/, "").replace(/\/$/, "").replace(/\.git$/, "").replace(/^(?:ssh:\/\/)?git@([^:/]+)[:/]/, "https://$1/");
+}
+/**
+* Extract the `owner/repo` slug a remote points at.
+*
+* @param url - A GitHub remote URL in any form.
+* @returns The `owner/repo` slug, or `undefined` when the URL is not a GitHub remote.
+* @example
+* ownerRepoFrom("git@github.com:moku-labs/common.git"); // "moku-labs/common"
+*/
+function ownerRepoFrom(url) {
+	const match = OWNER_REPO_PATTERN.exec(normalizeRemoteUrl(url));
+	if (!match) return void 0;
+	return `${match[1]}/${match[2]}`;
+}
+/**
+* Whether two remote URLs point at the same repository, comparing canonical forms so
+* `git+https://…​.git` and `git@github.com:…` match.
+*
+* @param left - The first remote URL.
+* @param right - The second remote URL.
+* @returns `true` when both resolve to the same canonical URL.
+* @example
+* sameRemote("git@github.com:o/r.git", "https://github.com/o/r"); // true
+*/
+function sameRemote(left, right) {
+	return normalizeRemoteUrl(left) === normalizeRemoteUrl(right);
+}
+/**
+* The newest release tag from `git tag` output produced with {@link LATEST_TAG_ARGS}.
+*
+* @param stdout - The raw tag listing.
+* @returns The first (newest) tag, or `undefined` when the repo has no release tags.
+* @example
+* latestVersionTag("v1.2.3\nv1.2.2\n"); // "v1.2.3"
+*/
+function latestVersionTag(stdout) {
+	return stdout.split("\n").map((line) => line.trim()).find((line) => line !== "");
+}
+//#endregion
+//#region src/lib/github.ts
+/**
+* @file `moku-release` — parsers for the `gh` JSON surfaces the CLI reads: branch
+* rulesets, workflow runs, and the release permalink printed in the final summary.
+*
+* `gh` is invoked by the checks and commands; everything that *interprets* its output
+* lives here so the interpretation is unit-testable against captured fixtures.
+*/
+/** Ruleset target value GitHub uses for branch (as opposed to tag) rulesets. */
+const BRANCH_TARGET = "branch";
+/**
+* Parse a JSON array `gh api` printed, tolerating error text and non-array payloads.
+*
+* @param stdout - The raw `gh api` output.
+* @returns The parsed array, or an empty array when the payload is not one.
+* @example
+* parseJsonArray('[{"target":"branch"}]');
+*/
+function parseJsonArray(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+/**
+* Whether an active BRANCH ruleset protects the default branch. Tag rulesets are ignored
+* on purpose — `moku-release` pushes tags, so restricting them would block every release.
+*
+* @param stdout - Output of `gh api repos/{owner}/{repo}/rulesets`.
+* @returns `true` when at least one active branch ruleset is present.
+* @example
+* hasMainBranchRuleset('[{"target":"branch","enforcement":"active"}]'); // true
+*/
+function hasMainBranchRuleset(stdout) {
+	return parseJsonArray(stdout).some((ruleset) => ruleset.target === BRANCH_TARGET && ruleset.enforcement !== "disabled");
+}
+/**
+* The id of the newest workflow run from `gh run list --json databaseId`.
+*
+* @param stdout - The raw `gh run list` JSON.
+* @returns The run id as a string, or `undefined` when no run was listed.
+* @example
+* latestRunId('[{"databaseId":42}]'); // "42"
+*/
+function latestRunId(stdout) {
+	const [first] = parseJsonArray(stdout);
+	if (first?.databaseId === void 0) return void 0;
+	return String(first.databaseId);
+}
+/**
+* The permalink of a GitHub release, for the final summary.
+*
+* @param ownerRepo - The `owner/repo` slug.
+* @param tag - The release tag (`v1.2.3`).
+* @returns The canonical release URL.
+* @example
+* releaseUrl("moku-labs/common", "v1.2.3");
+*/
+function releaseUrl(ownerRepo, tag) {
+	return `https://github.com/${ownerRepo}/releases/tag/${tag}`;
+}
+//#endregion
+//#region src/lib/package-json.ts
+/** Repo-relative path of the manifest every command reads. */
+const MANIFEST_PATH = "package.json";
+/** Lowest Node major a releasable package may declare — the npm Trusted Publishing floor. */
+const MINIMUM_NODE_MAJOR = 24;
+/** Value `engines.node` is set to when the field is missing or too low. */
+const NODE_ENGINE_RANGE = ">=24.0.0";
+/** Default `files` entry when a package declares none — the build output. */
+const DEFAULT_FILES = ["dist"];
+/** The scripts a releasable package must expose, mapped to the value `setup` fills in. */
+const REQUIRED_SCRIPTS = {
+	lint: "biome check . && eslint .",
+	typecheck: "tsc --noEmit",
+	test: "vitest run",
+	build: "tsdown",
+	validate: "publint && attw --pack . --profile node16",
+	"release:setup": "moku-release setup",
+	"release:doctor": "moku-release doctor",
+	release: "moku-release"
+};
+/**
+* Parse `package.json` text, treating malformed or non-object content as absent.
+*
+* @param text - The raw file contents, or `undefined` when the file is missing.
+* @returns The manifest, or `undefined` when it cannot be read as an object.
+* @example
+* parseManifest('{"name":"x"}');
+*/
+function parseManifest(text) {
+	if (text === void 0) return void 0;
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
+}
+/**
+* Read and parse the package manifest from a file store.
+*
+* @param files - The file port to read through.
+* @returns The manifest, or `undefined` when it is missing or malformed.
+* @example
+* const manifest = await readManifest(ctx.files);
+*/
+async function readManifest(files) {
+	return parseManifest(await files.read(MANIFEST_PATH));
+}
+/**
+* Render a manifest the way npm itself writes one: two-space JSON with a trailing newline.
+*
+* @param manifest - The manifest to serialize.
+* @returns The file contents to write.
+* @example
+* await files.write("package.json", formatManifest(manifest));
+*/
+function formatManifest(manifest) {
+	return `${JSON.stringify(manifest, void 0, 2)}\n`;
+}
+/**
+* The repository URL a manifest declares, in either the object or shorthand string form.
+*
+* @param manifest - The manifest to read.
+* @returns The declared URL, or `undefined` when the field is absent.
+* @example
+* repositoryUrlOf({ repository: { url: "git+https://github.com/o/r.git" } });
+*/
+function repositoryUrlOf(manifest) {
+	const { repository } = manifest;
+	if (typeof repository === "string") return repository;
+	return repository?.url;
+}
+/**
+* Whether an `engines.node` range admits Node 24 or newer. Only the first number in the
+* range is read — enough to separate `>=24`/`^24` from `>=20`, and it never mistakes a
+* richer range for a violation.
+*
+* @param range - The declared range, or `undefined`.
+* @returns `true` when the range's floor is Node 24 or newer.
+* @example
+* satisfiesNodeFloor(">=24.0.0"); // true
+*/
+function satisfiesNodeFloor(range) {
+	if (range === void 0) return false;
+	const match = /(\d+)/.exec(range);
+	if (!match?.[1]) return false;
+	return Number.parseInt(match[1], 10) >= MINIMUM_NODE_MAJOR;
+}
+/**
+* Every way a manifest falls short of the release contract, one line per gap, each naming
+* the exact script or field. An empty array means the manifest is on contract.
+*
+* @param manifest - The manifest to audit.
+* @returns The list of gaps, in reporting order.
+* @example
+* contractIssues({ name: "x" }); // ["missing script `lint`", …]
+*/
+function contractIssues(manifest) {
+	const issues = [];
+	const scripts = manifest.scripts ?? {};
+	for (const name of Object.keys(REQUIRED_SCRIPTS)) if (!scripts[name]) issues.push(`missing script \`${name}\``);
+	if (manifest.publishConfig?.access !== "public") issues.push("`publishConfig.access` is not `public`");
+	if (repositoryUrlOf(manifest) === void 0) issues.push("missing `repository.url`");
+	if (!manifest.files || manifest.files.length === 0) issues.push("missing `files`");
+	if (!satisfiesNodeFloor(manifest.engines?.node)) issues.push("`engines.node` is below `>=24`");
+	return issues;
+}
+/**
+* Bring a manifest onto the contract without overwriting anything it already chose: fill
+* missing scripts, force `publishConfig.access`, adopt the git remote as `repository.url`
+* when absent, add a default `files` allowlist, and raise `engines.node` to the floor.
+*
+* Running it twice produces no further changes — `setup` relies on that to stay idempotent.
+*
+* @param manifest - The manifest to normalize (never mutated).
+* @param remoteUrl - The `git remote get-url origin` value, when one is known.
+* @returns The normalized copy and the list of applied changes.
+* @example
+* const { manifest: next, changes } = normalizeManifest(current, "git@github.com:o/r.git");
+*/
+function normalizeManifest(manifest, remoteUrl) {
+	const next = structuredClone(manifest);
+	const changes = [];
+	const scripts = { ...next.scripts };
+	for (const [name, command] of Object.entries(REQUIRED_SCRIPTS)) {
+		if (scripts[name]) continue;
+		scripts[name] = command;
+		changes.push(`+ scripts.${name} = "${command}"`);
+	}
+	next.scripts = scripts;
+	if (next.publishConfig?.access !== "public") {
+		next.publishConfig = {
+			...next.publishConfig,
+			access: "public"
+		};
+		changes.push("+ publishConfig.access = \"public\"");
+	}
+	if (repositoryUrlOf(next) === void 0 && remoteUrl !== void 0) {
+		next.repository = {
+			type: "git",
+			url: remoteUrl
+		};
+		changes.push(`+ repository.url = "${remoteUrl}"`);
+	}
+	if (!next.files || next.files.length === 0) {
+		next.files = [...DEFAULT_FILES];
+		changes.push(`+ files = ${JSON.stringify(DEFAULT_FILES)}`);
+	}
+	if (!satisfiesNodeFloor(next.engines?.node)) {
+		next.engines = {
+			...next.engines,
+			node: NODE_ENGINE_RANGE
+		};
+		changes.push(`+ engines.node = "${NODE_ENGINE_RANGE}"`);
+	}
+	return {
+		manifest: next,
+		changes
+	};
+}
+//#endregion
+//#region src/lib/result.ts
+/**
+* A passing result. A pass never carries a fix — there is nothing to fix.
+*
+* @param detail - What was observed, in one line.
+* @returns The passing result.
+* @example
+* pass("npm 11.6.0");
+*/
+function pass(detail) {
+	return {
+		status: "pass",
+		detail
+	};
+}
+/**
+* A blocking result: the release cannot proceed until `fix` is applied.
+*
+* @param detail - What was observed, in one line.
+* @param fix - The concrete command or edit that resolves it.
+* @returns The failing result.
+* @example
+* fail("npm is not logged in", "npm login");
+*/
+function fail(detail, fix) {
+	return {
+		status: "fail",
+		detail,
+		fix
+	};
+}
+/**
+* An advisory result: worth knowing, not blocking.
+*
+* @param detail - What was observed, in one line.
+* @param fix - The concrete command or edit that resolves it.
+* @returns The warning result.
+* @example
+* warn("no branch ruleset on main", "moku-release setup");
+*/
+function warn(detail, fix) {
+	return {
+		status: "warn",
+		detail,
+		fix
+	};
+}
+/**
+* A skipped result: the check could not run because a prerequisite is missing.
+*
+* @param detail - Why the check was skipped.
+* @returns The skipped result.
+* @example
+* skip("package.json is unreadable");
+*/
+function skip(detail) {
+	return {
+		status: "skip",
+		detail
+	};
+}
+//#endregion
+//#region src/checks/branch-ruleset.ts
+/**
+* @file `moku-release` — check: a branch ruleset protects the default branch.
+*
+* Advisory. The release pipeline works without it; what it buys is that main can only
+* move through a PR, so a release always describes a reviewed state.
+*/
+/** Verifies `gh api repos/{owner}/{repo}/rulesets` lists an active branch ruleset. */
+const branchRulesetCheck = {
+	id: "branch-ruleset",
+	title: "branch ruleset on main",
+	/**
+	* List the repository's rulesets and look for an active branch-targeting one.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when one exists, warn when none does.
+	* @example
+	* await branchRulesetCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		const declared = manifest === void 0 ? void 0 : repositoryUrlOf(manifest);
+		const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
+		if (ownerRepo === void 0) return skip("cannot derive owner/repo from repository.url");
+		const rulesets = await ctx.exec.capture("gh", ["api", `repos/${ownerRepo}/rulesets`]);
+		if (rulesets.code !== 0) return skip("`gh api` could not read the rulesets");
+		if (!hasMainBranchRuleset(rulesets.stdout)) return warn("main has no branch ruleset", "moku-release setup");
+		return pass("active branch ruleset present");
+	}
+};
+//#endregion
+//#region src/checks/gh-auth.ts
+/**
+* @file `moku-release` — check: the GitHub CLI is installed and authenticated.
+*
+* A human-only prerequisite. The CLI never logs anyone in and never handles a token: it
+* reports the exact command the operator must run and stops there.
+*/
+/** Verifies `gh` exists and holds a live session. */
+const ghAuthCheck = {
+	id: "gh-auth",
+	title: "gh installed and authenticated",
+	/**
+	* Probe `gh --version`, then `gh auth status`.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when both succeed, otherwise the command the human must run.
+	* @example
+	* await ghAuthCheck.run(ctx);
+	*/
+	async run(ctx) {
+		if ((await ctx.exec.capture("gh", ["--version"])).code !== 0) return fail("`gh` is not installed", "brew install gh");
+		if ((await ctx.exec.capture("gh", ["auth", "status"])).code !== 0) return fail("`gh` is not authenticated", "gh auth login");
+		return pass("authenticated");
+	}
+};
+//#endregion
+//#region src/checks/npm-auth.ts
+/**
+* @file `moku-release` — check: npm holds a logged-in session.
+*
+* The second human-only prerequisite. Publishing itself runs through OIDC in CI, but the
+* one-time `setup` (first publish, `npm trust`) needs a local session — and only the human
+* can create one.
+*/
+/** Verifies `npm whoami` resolves to a user. */
+const npmAuthCheck = {
+	id: "npm-auth",
+	title: "npm is logged in",
+	/**
+	* Probe `npm whoami`.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass with the username, otherwise the login command.
+	* @example
+	* await npmAuthCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const session = await ctx.exec.capture("npm", ["whoami"]);
+		if (session.code !== 0) return fail("npm is not logged in", "npm login");
+		return pass(`logged in as ${session.stdout.trim()}`);
+	}
+};
+//#endregion
+//#region src/checks/npm-package.ts
+/**
+* @file `moku-release` — check: the package exists on the registry.
+*
+* Advisory, not blocking: a brand-new package legitimately has no npm presence yet, and
+* `setup` is what performs that first publish.
+*/
+/** Verifies `npm view <name> version` resolves. */
+const npmPackageCheck = {
+	id: "npm-package",
+	title: "package published on npm",
+	/**
+	* Ask the registry for the package's current version.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass with the published version, or a warning that the first publish is due.
+	* @example
+	* await npmPackageCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest?.name) return skip("package.json declares no `name`");
+		const view = await ctx.exec.capture("npm", [
+			"view",
+			manifest.name,
+			"version"
+		]);
+		if (view.code !== 0) return warn("first publish not done yet", "moku-release setup");
+		return pass(`${manifest.name}@${view.stdout.trim()}`);
+	}
+};
+//#endregion
+//#region src/lib/npm.ts
+/**
+* @file `moku-release` — npm semantics as pure functions: semver comparison (including
+* prerelease ordering), the minimum-version gate, the dist-tag a version belongs under,
+* and the parsers for `npm view … --json` output.
+*
+* Nothing here runs a command. Checks capture npm's output and hand the text to these
+* functions, which is what makes version and tag logic testable without a registry.
+*/
+/** Registry front-end the final summary links a published version to. */
+const NPM_BASE_URL = "https://www.npmjs.com/package";
+/** Dist-tag stable releases move. */
+const LATEST_TAG = "latest";
+/** Dist-tag prerelease versions are published under so they never clobber `latest`. */
+const NEXT_TAG = "next";
+/**
+* Split a version string into comparable parts. A leading `v` and any build metadata
+* (`+…`) are dropped — neither participates in precedence.
+*
+* @param version - The version or tag to parse (`v1.2.3-rc.1`).
+* @returns The numeric core and the prerelease identifiers.
+* @example
+* parseSemver("v1.2.3-rc.1"); // { core: [1, 2, 3], prerelease: ["rc", "1"] }
+*/
+function parseSemver(version) {
+	const [withoutBuild = ""] = version.replace(/^v/, "").split("+");
+	const dash = withoutBuild.indexOf("-");
+	const core = dash === -1 ? withoutBuild : withoutBuild.slice(0, dash);
+	const prerelease = dash === -1 ? "" : withoutBuild.slice(dash + 1);
+	return {
+		core: core.split(".").map((part) => Number.parseInt(part, 10) || 0),
+		prerelease: prerelease === "" ? [] : prerelease.split(".")
+	};
+}
+/**
+* Compare two prerelease identifiers by semver rules: numeric identifiers compare
+* numerically and always sort below alphanumeric ones, which compare lexically.
+*
+* @param left - The left identifier.
+* @param right - The right identifier.
+* @returns Negative, zero or positive.
+* @example
+* compareIdentifier("2", "10"); // negative — numeric, not lexical
+*/
+function compareIdentifier(left, right) {
+	const leftNumeric = /^\d+$/.test(left);
+	const rightNumeric = /^\d+$/.test(right);
+	if (leftNumeric && !rightNumeric) return -1;
+	if (!leftNumeric && rightNumeric) return 1;
+	if (leftNumeric && rightNumeric) return Number(left) - Number(right);
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+/**
+* Compare the prerelease segments of two versions. A stable release outranks any
+* prerelease; otherwise identifiers compare left to right and a shorter run loses.
+*
+* @param left - The left version's prerelease identifiers.
+* @param right - The right version's prerelease identifiers.
+* @returns Negative, zero or positive.
+* @example
+* comparePrerelease(["rc", "1"], []); // negative — 1.0.0-rc.1 < 1.0.0
+*/
+function comparePrerelease(left, right) {
+	if (left.length === 0 && right.length === 0) return 0;
+	if (left.length === 0) return 1;
+	if (right.length === 0) return -1;
+	for (const [index, leftPart] of left.entries()) {
+		const rightPart = right[index];
+		if (rightPart === void 0) return 1;
+		const verdict = compareIdentifier(leftPart, rightPart);
+		if (verdict !== 0) return verdict;
+	}
+	return left.length === right.length ? 0 : -1;
+}
+/**
+* Compare two semver versions, prerelease ordering included.
+*
+* @param left - The left version or `v`-prefixed tag.
+* @param right - The right version or `v`-prefixed tag.
+* @returns Negative when `left` is older, `0` when equal, positive when newer.
+* @example
+* compareSemver("1.0.0-rc.2", "1.0.0"); // negative
+*/
+function compareSemver(left, right) {
+	const a = parseSemver(left);
+	const b = parseSemver(right);
+	for (let index = 0; index < 3; index += 1) {
+		const verdict = (a.core[index] ?? 0) - (b.core[index] ?? 0);
+		if (verdict !== 0) return verdict;
+	}
+	return comparePrerelease(a.prerelease, b.prerelease);
+}
+/**
+* Whether `version` satisfies a minimum floor (used for the npm Trusted Publishing gate).
+*
+* @param version - The observed version.
+* @param minimum - The lowest acceptable version.
+* @returns `true` when `version >= minimum`.
+* @example
+* isAtLeast("11.6.0", "11.5.1"); // true
+*/
+function isAtLeast(version, minimum) {
+	return compareSemver(version, minimum) >= 0;
+}
+/**
+* The dist-tag a version is published under: prereleases go to `next` so they never move
+* `latest`.
+*
+* @param version - The version being published.
+* @returns `"next"` for a prerelease, `"latest"` otherwise.
+* @example
+* distTagFor("1.0.0-rc.1"); // "next"
+*/
+function distTagFor(version) {
+	return parseSemver(version).prerelease.length > 0 ? NEXT_TAG : LATEST_TAG;
+}
+/**
+* Parse `npm view <pkg> dist-tags --json` output into a plain tag → version map.
+*
+* @param stdout - The raw JSON npm printed.
+* @returns The dist-tag map, or `undefined` when the output is not a JSON object.
+* @example
+* parseDistTags('{"latest":"1.2.3"}'); // { latest: "1.2.3" }
+*/
+function parseDistTags(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
+}
+/**
+* The npm front-end URL for a package version, used in the final release summary.
+*
+* @param name - The package name.
+* @param version - The published version.
+* @returns The canonical npmjs.com URL.
+* @example
+* npmPackageUrl("@moku-labs/common", "1.2.3");
+*/
+function npmPackageUrl(name, version) {
+	return `${NPM_BASE_URL}/${name}/v/${version}`;
+}
+//#endregion
+//#region src/checks/npm-version.ts
+/**
+* @file `moku-release` — check: the local npm is new enough for Trusted Publishing.
+*
+* OIDC trusted publishing (and the `npm trust` command `setup` registers the publisher
+* with) landed in npm 11.5.1. Below that floor the whole token-free pipeline is
+* unavailable, so this is a hard fail rather than an advisory.
+*/
+/** The npm version that introduced OIDC trusted publishing. */
+const NPM_TRUSTED_PUBLISHING_FLOOR = "11.5.1";
+/** Verifies `npm --version` is at or above the Trusted Publishing floor. */
+const npmVersionCheck = {
+	id: "npm-version",
+	title: `npm >= ${NPM_TRUSTED_PUBLISHING_FLOOR}`,
+	/**
+	* Read `npm --version` and compare it to the floor.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass with the version, otherwise the upgrade command.
+	* @example
+	* await npmVersionCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const probe = await ctx.exec.capture("npm", ["--version"]);
+		if (probe.code !== 0) return fail("`npm` is not installed", "install Node 24 (bundles npm 11)");
+		const version = probe.stdout.trim();
+		if (!isAtLeast(version, "11.5.1")) return fail(`npm ${version} < ${NPM_TRUSTED_PUBLISHING_FLOOR}`, "npm install -g npm@latest");
+		return pass(`npm ${version}`);
+	}
+};
+//#endregion
+//#region src/checks/package-contract.ts
+/**
+* @file `moku-release` — check: package.json declares the release contract.
+*
+* Reports every gap by name (`missing script \`typecheck\``, not "scripts incomplete") so
+* the fix is mechanical, and points at the one command that closes all of them.
+*/
+/** Verifies the required scripts and publish fields are present. */
+const packageContractCheck = {
+	id: "package-contract",
+	title: "package.json on contract",
+	/**
+	* Audit the manifest against the contract table.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when nothing is missing, otherwise every gap by name.
+	* @example
+	* await packageContractCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest) return skip("package.json is missing or malformed");
+		const issues = contractIssues(manifest);
+		if (issues.length > 0) return fail(issues.join(", "), "moku-release setup");
+		return pass("all scripts and publish fields present");
+	}
+};
+//#endregion
+//#region src/checks/repository-url.ts
+/**
+* @file `moku-release` — check: `repository.url` points at the real origin.
+*
+* A manifest that names the wrong repository publishes provenance for the wrong
+* repository, and npm Trusted Publishing matches on that repository — so a mismatch here
+* surfaces later as an opaque OIDC rejection.
+*/
+/** Verifies the declared repository URL matches `git remote get-url origin`. */
+const repositoryUrlCheck = {
+	id: "repository-url",
+	title: "repository.url matches origin",
+	/**
+	* Compare the manifest's repository URL with the git remote, in canonical form.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when both name the same repository.
+	* @example
+	* await repositoryUrlCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest) return skip("package.json is missing or malformed");
+		const origin = await ctx.exec.capture("git", [
+			"remote",
+			"get-url",
+			"origin"
+		]);
+		if (origin.code !== 0) return skip("no `origin` remote configured");
+		const declared = repositoryUrlOf(manifest);
+		if (declared === void 0) return fail("package.json declares no `repository.url`", "moku-release setup");
+		if (!sameRemote(declared, origin.stdout)) return fail(`repository.url (${declared.trim()}) != origin (${origin.stdout.trim()})`, `set repository.url to "${origin.stdout.trim()}"`);
+		return pass(declared.trim());
+	}
+};
+//#endregion
+//#region src/checks/tag-sync.ts
+/**
+* @file `moku-release` — check: the newest git tag and npm's `latest` agree.
+*
+* The two drift in exactly two ways, and they mean opposite things: npm AHEAD of the tag
+* means a publish happened without its tag being pushed (history has lost the provenance
+* of a released version); npm BEHIND means a tag was cut whose publish never completed.
+* Both are advisory — neither blocks the next release, both want a human to look.
+*/
+/** Fix line shared by both drift directions — the resolution is the same investigation. */
+const DRIFT_FIX = "reconcile: push the missing tag, or re-run the release that never published";
+/** Verifies the latest `v*` tag equals npm's `latest` dist-tag. */
+const tagSyncCheck = {
+	id: "tag-sync",
+	title: "latest git tag matches npm latest",
+	/**
+	* Compare the newest release tag with the registry's `latest` dist-tag.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when both name the same version, warn (with the direction) otherwise.
+	* @example
+	* await tagSyncCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest?.name) return skip("package.json declares no `name`");
+		const tags = await ctx.exec.capture("git", LATEST_TAG_ARGS);
+		const tag = tags.code === 0 ? latestVersionTag(tags.stdout) : void 0;
+		if (tag === void 0) return skip("no `v*` tags yet");
+		const view = await ctx.exec.capture("npm", [
+			"view",
+			manifest.name,
+			"dist-tags",
+			"--json"
+		]);
+		const published = view.code === 0 ? parseDistTags(view.stdout)?.latest : void 0;
+		if (published === void 0) return skip("npm has no `latest` dist-tag yet");
+		const drift = compareSemver(published, tag);
+		if (drift > 0) return warn(`npm ${published} is AHEAD of tag ${tag}`, DRIFT_FIX);
+		if (drift < 0) return warn(`npm ${published} is BEHIND tag ${tag}`, DRIFT_FIX);
+		return pass(`${tag} == npm latest`);
+	}
+};
+//#endregion
+//#region src/templates/central.ts
+/**
+* @file `moku-release` — read a central definition from this package's own files.
+*
+* The CLI ships in the same package as `examples/` and `rulesets/`, so a template is read
+* from disk instead of being copied into a string. One file, one version, nothing to drift.
+*/
+/** A file that only exists at the package root, used to find it from `src/` and from `dist/`. */
+const ROOT_MARKER = path.join("rulesets", "main.json");
+/**
+* The package root: the closest parent directory that holds `rulesets/main.json`.
+*
+* @returns The absolute path of the package root.
+* @throws {Error} When no parent directory holds the marker, which means a broken install.
+* @example
+* path.join(packageRoot(), "examples");
+*/
+function packageRoot() {
+	let directory = path.dirname(fileURLToPath(import.meta.url));
+	while (!existsSync(path.join(directory, ROOT_MARKER))) {
+		const parent = path.dirname(directory);
+		if (parent === directory) throw new Error(`moku-release: ${ROOT_MARKER} not found above ${import.meta.url}`);
+		directory = parent;
+	}
+	return directory;
+}
+/**
+* Read one central definition, for example `examples/package/ci.yml`.
+*
+* @param relativePath - The path inside the package.
+* @returns The file contents.
+* @example
+* readCentral("rulesets/main.json");
+*/
+function readCentral(relativePath) {
+	return readFileSync(path.join(packageRoot(), relativePath), "utf8");
+}
+//#endregion
+//#region src/templates/publish.ts
+/**
+* @file `moku-release` — the `.github/workflows/publish.yml` template.
+*
+* Read from this package's own `examples/package/publish.yml`. The FILE NAME is the
+* contract: npm Trusted Publishing validates the CALLING workflow's filename, so this file
+* must stay `publish.yml` even though the publish itself happens inside the central
+* reusable workflow. There is no `NPM_TOKEN` anywhere — `id-token: write` is the whole
+* credential.
+*/
+/** Repo-relative path this template is written to. Registered with npm — never rename it. */
+const PUBLISH_WORKFLOW_PATH = ".github/workflows/publish.yml";
+/**
+* The reusable workflow ref `doctor` recognizes a migrated `publish.yml` by. The
+* `publish.local-publish.yml` fallback variant calls the same ref, so it is recognized too.
+*/
+const PUBLISH_WORKFLOW_REF = "moku-labs/ci/.github/workflows/package-release.yml@v1";
+/** The `publish.yml` body, read from `examples/package/publish.yml`. */
+const PUBLISH_WORKFLOW = readCentral("examples/package/publish.yml");
+//#endregion
+//#region src/checks/trusted-publisher.ts
+/**
+* @file `moku-release` — check: npm knows this repo's `publish.yml` as a trusted publisher.
+*
+* Without the registration the release workflow's OIDC token is rejected and the publish
+* step fails at the very end of a run, so this is fail-level. An npm too old to even have
+* `npm trust` warns instead — the answer there is an upgrade, not a registration.
+*/
+/** Basename npm registers the publisher against — the workflow file's name, not its path. */
+const PUBLISH_WORKFLOW_FILE$1 = ".github/workflows/publish.yml".split("/").pop() ?? "publish.yml";
+/**
+* Whether npm's output says the `trust` command itself does not exist.
+*
+* @param output - The combined stdout/stderr npm produced.
+* @returns `true` when the installed npm has no `trust` command.
+* @example
+* isUnknownCommand("Unknown command: \"trust\"");
+*/
+function isUnknownCommand(output) {
+	return /unknown command|did you mean|not a recognized/i.test(output);
+}
+/**
+* Whether npm refused the listing because nobody is logged in.
+*
+* @param output - The combined stdout/stderr npm produced.
+* @returns `true` when the failure is an authentication failure, not a missing registration.
+* @example
+* isUnauthorized("npm error code E401");
+*/
+function isUnauthorized(output) {
+	return /E401|ENEEDAUTH|401 Unauthorized/i.test(output);
+}
+/**
+* The exact registration command for this package and repository.
+*
+* @param name - The package name.
+* @param ownerRepo - The `owner/repo` slug.
+* @returns The `npm trust github …` command line.
+* @example
+* trustCommand("@moku-labs/common", "moku-labs/common");
+*/
+function trustCommand(name, ownerRepo) {
+	return `npm trust github ${name} --file ${PUBLISH_WORKFLOW_FILE$1} --repo ${ownerRepo} --yes`;
+}
+/** Verifies a trusted publisher is registered for the package. */
+const trustedPublisherCheck = {
+	id: "trusted-publisher",
+	title: "npm trusted publisher registered",
+	/**
+	* List the package's trusted publishers and look for this repo's `publish.yml`.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when registered, warn when npm is too old, skip when logged out, otherwise the exact command.
+	* @example
+	* await trustedPublisherCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest?.name) return skip("package.json declares no `name`");
+		const declared = repositoryUrlOf(manifest);
+		const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
+		if (ownerRepo === void 0) return skip("cannot derive owner/repo from repository.url");
+		const listing = await ctx.exec.capture("npm", [
+			"trust",
+			"list",
+			manifest.name
+		]);
+		if (isUnknownCommand(`${listing.stdout}${listing.stderr}`)) return warn("this npm has no `trust` command", "upgrade npm");
+		if (isUnauthorized(`${listing.stdout}${listing.stderr}`)) return skip("cannot list trusted publishers without `npm login`");
+		if (listing.code !== 0 || !listing.stdout.includes(PUBLISH_WORKFLOW_FILE$1)) return fail("no trusted publisher registered", trustCommand(manifest.name, ownerRepo));
+		return pass(`${ownerRepo} · ${PUBLISH_WORKFLOW_FILE$1}`);
+	}
+};
+//#endregion
+//#region src/templates/ci.ts
+/**
+* @file `moku-release` — the `.github/workflows/ci.yml` template.
+*
+* Read from this package's own `examples/package/ci.yml`. It is a thin caller: the
+* whole check matrix lives once in the central reusable workflow, so a pipeline change is
+* one PR there instead of one per repository. Two details are load-bearing and must not be
+* "tidied": the caller job id is `ci` (GitHub prefixes the reused jobs with it, so the
+* required checks are `ci / lint`, `ci / types`, `ci / test`, `ci / build`), and there is
+* deliberately NO concurrency block — the called workflow already groups by
+* `github.workflow`, and a caller group with the same value deadlocks against its own child.
+*/
+/** Repo-relative path this template is written to. */
+const CI_WORKFLOW_PATH = ".github/workflows/ci.yml";
+/** The reusable workflow ref `doctor` recognizes a migrated `ci.yml` by. */
+const CI_WORKFLOW_REF = "moku-labs/ci/.github/workflows/package-ci.yml@v1";
+/** The `ci.yml` body, read from `examples/package/ci.yml`. */
+const CI_WORKFLOW = readCentral("examples/package/ci.yml");
+//#endregion
+//#region src/templates/ruleset.ts
+/**
+* @file `moku-release` — the branch ruleset `setup` applies to `main`.
+*
+* Read from this package's own `rulesets/main.json`: PR-only main, no deletion, no
+* force-push, and the four required checks the thin `ci.yml` produces (`ci / lint`,
+* `ci / types`, `ci / test`, `ci / build`). Tags are deliberately NOT restricted — the
+* release workflow pushes `v*` tags, and a tag ruleset would block every release.
+*/
+/** The ruleset payload for `gh api repos/{owner}/{repo}/rulesets --input -`, read from `rulesets/main.json`. */
+const MAIN_RULESET_JSON = readCentral("rulesets/main.json");
+//#endregion
+//#region src/lib/templates.ts
+/**
+* @file `moku-release` — the workflow template surface: what to write, where, and how to
+* tell a migrated workflow from a hand-written legacy one.
+*
+* `setup` writes what {@link workflowTemplates} lists; `doctor` reads the same list back
+* and asks {@link isThinWorkflow} whether the file on disk still calls the pinned central
+* workflow. One list, both directions — a template can never drift from its check.
+*
+* The bodies are read from this package's own `examples/package/*.yml` and
+* `rulesets/main.json`: this CLI distributes the central definitions, it does not copy them.
+*/
+/** Both generated workflows, in the order `setup` writes and `doctor` reports them. */
+const workflowTemplates = [{
+	path: CI_WORKFLOW_PATH,
+	content: CI_WORKFLOW,
+	ref: CI_WORKFLOW_REF
+}, {
+	path: PUBLISH_WORKFLOW_PATH,
+	content: PUBLISH_WORKFLOW,
+	ref: PUBLISH_WORKFLOW_REF
+}];
+/**
+* Whether a workflow file on disk is the thin caller — i.e. it delegates to the pinned
+* central reusable workflow. A file that does not is a legacy hand-written pipeline.
+* Matching on the `@v1` ref rather than on the whole body is deliberate: the
+* `publish.local-publish.yml` fallback variant calls the same ref and must also pass.
+*
+* @param content - The file contents read from disk.
+* @param template - The template the file is expected to match.
+* @returns `true` when the file calls the pinned reusable workflow.
+* @example
+* isThinWorkflow(onDisk, workflowTemplates[0]);
+*/
+function isThinWorkflow(content, template) {
+	return content.includes(template.ref);
+}
+/**
+* The branch-ruleset payload `gh api … --input -` reads — the central definition verbatim.
+*
+* @returns The ruleset JSON.
+* @example
+* const body = renderMainRuleset();
+*/
+function renderMainRuleset() {
+	return MAIN_RULESET_JSON;
+}
+//#endregion
+//#region src/checks/workflows.ts
+/**
+* @file `moku-release` — check: both workflows exist and are the thin callers.
+*
+* Three outcomes, and the middle one matters most: a MISSING workflow fails, a
+* hand-written one warns ("legacy workflow, run release:setup to migrate") because the
+* repo still releases — just not through the shared pipeline — and a pinned thin caller
+* passes.
+*/
+/** Advisory shown for a workflow that exists but does not call the central pipeline. */
+const LEGACY_FIX = "legacy workflow, run release:setup to migrate";
+/** Verifies `ci.yml` and `publish.yml` are the `@v1`-pinned thin callers. */
+const workflowsCheck = {
+	id: "workflows",
+	title: "workflows are thin callers pinned to @v1",
+	/**
+	* Read both workflow files and classify each as missing, legacy or thin.
+	*
+	* @param ctx - The injected ports.
+	* @returns Fail for a missing file, warn for a legacy one, pass when both are thin.
+	* @example
+	* await workflowsCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const missing = [];
+		const legacy = [];
+		for (const template of workflowTemplates) {
+			const content = await ctx.files.read(template.path);
+			if (content === void 0) missing.push(template.path);
+			else if (!isThinWorkflow(content, template)) legacy.push(template.path);
+		}
+		if (missing.length > 0) return fail(`missing ${missing.join(", ")}`, "moku-release setup");
+		if (legacy.length > 0) return warn(`${legacy.join(", ")} not pinned to @v1`, LEGACY_FIX);
+		return pass("ci.yml + publish.yml pinned to @v1");
+	}
+};
+//#endregion
+//#region src/checks/working-tree.ts
+/**
+* @file `moku-release` — check: the working tree is clean and HEAD is `origin/main`.
+*
+* The only check whose severity depends on the caller: in `doctor` a dirty tree is
+* information (`warn`), in the `release` preflight it is a stop condition (`fail`) —
+* releasing from a state the remote has never seen produces a tag nobody can reproduce.
+* `ctx.strict` is the switch.
+*/
+/** Ref the release is always cut from. */
+const RELEASE_REF = "origin/main";
+/**
+* Report a problem at the severity the calling command asked for.
+*
+* @param ctx - The injected ports, carrying the `strict` flag.
+* @param detail - What was observed.
+* @param fixLine - The command that resolves it.
+* @returns A failing result under `strict`, otherwise a warning.
+* @example
+* atSeverity(ctx, "working tree is dirty", "git status");
+*/
+function atSeverity(ctx, detail, fixLine) {
+	return ctx.strict ? fail(detail, fixLine) : warn(detail, fixLine);
+}
+//#endregion
+//#region src/checks/index.ts
+/** Every diagnostic `doctor` runs, in report order. */
+const allChecks = [
+	ghAuthCheck,
+	npmAuthCheck,
+	npmVersionCheck,
+	packageContractCheck,
+	repositoryUrlCheck,
+	workflowsCheck,
+	npmPackageCheck,
+	trustedPublisherCheck,
+	tagSyncCheck,
+	branchRulesetCheck,
+	{
+		id: "working-tree",
+		title: "clean tree on origin/main",
+		/**
+		* Compare the porcelain status and the HEAD / `origin/main` revisions.
+		*
+		* @param ctx - The injected ports.
+		* @returns Pass when both agree; severity follows `ctx.strict` otherwise.
+		* @example
+		* await workingTreeCheck.run({ ...ctx, strict: true });
+		*/
+		async run(ctx) {
+			const status = await ctx.exec.capture("git", ["status", "--porcelain"]);
+			if (status.code !== 0) return skip("not a git repository");
+			if (status.stdout.trim() !== "") return atSeverity(ctx, "working tree has uncommitted changes", "commit or stash them");
+			const head = await ctx.exec.capture("git", ["rev-parse", "HEAD"]);
+			const remote = await ctx.exec.capture("git", ["rev-parse", RELEASE_REF]);
+			if (head.code !== 0 || remote.code !== 0) return skip(`cannot resolve ${RELEASE_REF}`);
+			if (head.stdout.trim() !== remote.stdout.trim()) return atSeverity(ctx, `HEAD is not ${RELEASE_REF}`, `git pull --ff-only origin main`);
+			return pass(`clean, in sync with ${RELEASE_REF}`);
+		}
+	}
+];
+//#endregion
+//#region src/commands/doctor.ts
+/** Glyphs for the two statuses the branded `check` row cannot express on its own. */
+const STATUS_GLYPH = {
+	warn: "⚠",
+	skip: "–"
+};
+/**
+* Print one entry: pass/fail through the branded check row, warn/skip as their own glyph
+* so a warning never reads as a failure.
+*
+* @param ui - The branded console.
+* @param entry - The check outcome to render.
+* @example
+* renderEntry(ui, { id: "npm-auth", title: "npm is logged in", status: "pass", detail: "ok" });
+*/
+function renderEntry(ui, entry) {
+	const label = `${entry.title} — ${entry.detail}`;
+	const hint = entry.fix === void 0 ? void 0 : `fix: ${entry.fix}`;
+	if (entry.status === "pass" || entry.status === "fail") {
+		ui.check(entry.status === "pass", label, hint);
+		return;
+	}
+	const glyph = STATUS_GLYPH[entry.status];
+	ui.line(`  ${ui.palette.yellow(glyph)} ${label}`);
+	if (hint !== void 0) ui.line(`      ${ui.palette.dim(hint)}`);
+}
+/**
+* Run one check, turning an unexpected throw into a failing entry rather than a crash —
+* a broken diagnostic must never hide the other ten.
+*
+* @param check - The check to run.
+* @param ctx - The ports and flags.
+* @returns The flattened entry.
+* @example
+* await evaluate(npmAuthCheck, ctx);
+*/
+async function evaluate(check, ctx) {
+	try {
+		return {
+			id: check.id,
+			title: check.title,
+			...await check.run(ctx)
+		};
+	} catch (error) {
+		return {
+			id: check.id,
+			title: check.title,
+			status: "fail",
+			detail: `check threw: ${String(error)}`,
+			fix: "report this as a moku-release bug"
+		};
+	}
+}
+/**
+* Run every check in order and report. Checks run sequentially on purpose: the report is
+* read top to bottom, and the tools they shell out to are not all concurrency-safe.
+*
+* @param options - The ports, console, and output mode.
+* @returns The entries and whether anything failed.
+* @example
+* const report = await runDoctor({ ctx, ui });
+*/
+async function runDoctor(options) {
+	const { ctx, ui, json = false, checks = allChecks } = options;
+	const entries = [];
+	for (const check of checks) entries.push(await evaluate(check, ctx));
+	const failed = entries.some((entry) => entry.status === "fail");
+	if (json) {
+		ui.line(JSON.stringify({
+			failed,
+			checks: entries
+		}, void 0, 2));
+		return {
+			entries,
+			failed
+		};
+	}
+	for (const entry of entries) renderEntry(ui, entry);
+	return {
+		entries,
+		failed
+	};
+}
+//#endregion
+//#region src/commands/release.ts
+/** Workflow file dispatched by name — the same name npm's trusted publisher is bound to. */
+const PUBLISH_WORKFLOW_FILE = ".github/workflows/publish.yml".split("/").pop() ?? "publish.yml";
+/** How long to keep asking the registry for the new version before giving up. */
+const REGISTRY_POLL_ATTEMPTS = 24;
+/** Gap between registry polls — 24 × 5s ≈ two minutes of registry lag tolerated. */
+const REGISTRY_POLL_INTERVAL_MS = 5e3;
+/** How many times to look for the dispatched run before concluding it never started. */
+const RUN_LOOKUP_ATTEMPTS = 10;
+/** Gap between run lookups — GitHub takes a moment to materialize a dispatched run. */
+const RUN_LOOKUP_INTERVAL_MS = 3e3;
+/**
+* The default delay helper.
+*
+* @param ms - Milliseconds to wait.
+* @returns Resolves after the delay.
+* @example
+* await defaultSleep(500);
+*/
+const defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/**
+* Run the strict preflight and print it. Strict mode is what turns the advisory
+* working-tree check into a stop condition.
+*
+* @param ctx - The ports and flags.
+* @param ui - The branded console.
+* @returns `true` when nothing blocks the release.
+* @example
+* if (!(await preflight(ctx, ui))) return 1;
+*/
+async function preflight(ctx, ui) {
+	ui.heading("Preflight");
+	const report = await runDoctor({
+		ctx: {
+			...ctx,
+			strict: true
+		},
+		ui,
+		checks: allChecks
+	});
+	if (report.failed) ui.error("preflight failed — nothing was dispatched");
+	return !report.failed;
+}
+/**
+* Find the run the dispatch just created, retrying while GitHub materializes it.
+*
+* @param ctx - The ports and flags.
+* @param sleep - The delay helper.
+* @returns The run id, or `undefined` when no run appeared.
+* @example
+* const runId = await findDispatchedRun(ctx, defaultSleep);
+*/
+async function findDispatchedRun(ctx, sleep) {
+	const args = [
+		"run",
+		"list",
+		"--workflow",
+		PUBLISH_WORKFLOW_FILE,
+		"--branch",
+		"main",
+		"--limit",
+		"1",
+		"--json",
+		"databaseId"
+	];
+	for (let attempt = 0; attempt < RUN_LOOKUP_ATTEMPTS; attempt += 1) {
+		const listing = await ctx.exec.capture("gh", args);
+		const runId = listing.code === 0 ? latestRunId(listing.stdout) : void 0;
+		if (runId !== void 0) return runId;
+		await sleep(RUN_LOOKUP_INTERVAL_MS);
+	}
+}
+/**
+* Poll the registry until the expected dist-tag moves off `before`. The registry lags
+* behind a successful publish, so "not there yet" is expected for a while and only a
+* timeout is an error.
+*
+* @param ctx - The ports and flags.
+* @param name - The package name.
+* @param tag - The dist-tag the new version lands under.
+* @param before - The version that tag pointed at before the release.
+* @param sleep - The delay helper.
+* @returns The new version, or `undefined` when the registry never moved.
+* @example
+* await awaitPublishedVersion(ctx, "@moku-labs/common", "latest", "1.2.2", defaultSleep);
+*/
+async function awaitPublishedVersion(ctx, name, tag, before, sleep) {
+	for (let attempt = 0; attempt < REGISTRY_POLL_ATTEMPTS; attempt += 1) {
+		const view = await ctx.exec.capture("npm", [
+			"view",
+			name,
+			"dist-tags",
+			"--json"
+		]);
+		const current = view.code === 0 ? parseDistTags(view.stdout)?.[tag] : void 0;
+		if (current !== void 0 && current !== before) return current;
+		await sleep(REGISTRY_POLL_INTERVAL_MS);
+	}
+}
+/**
+* Print the closing summary: what shipped, where its tag is, and the two links a human
+* actually clicks.
+*
+* @param ui - The branded console.
+* @param name - The package name.
+* @param version - The published version.
+* @param ownerRepo - The `owner/repo` slug, when one is known.
+* @example
+* renderSummary(ui, "@moku-labs/common", "1.2.3", "moku-labs/common");
+*/
+function renderSummary(ui, name, version, ownerRepo) {
+	const tag = `v${version}`;
+	const lines = [
+		ui.railLine(`${name}`, version, 48),
+		ui.railLine("tag", tag, 48),
+		ui.railLine("npm", npmPackageUrl(name, version), 48)
+	];
+	if (ownerRepo !== void 0) lines.push(ui.railLine("release", releaseUrl(ownerRepo, tag), 48));
+	ui.heading("Released");
+	ui.box(lines);
+}
+/**
+* Cut a release: preflight, dispatch `publish.yml`, watch the run, verify the artifact.
+*
+* @param options - The ports, console, bump type and flags.
+* @returns The process exit code.
+* @example
+* const code = await runRelease({ ctx, ui, releaseType: "patch" });
+*/
+async function runRelease(options) {
+	const { ctx, ui, releaseType, dryRun = false, sleep = defaultSleep } = options;
+	ui.lockup({
+		wordmark: "moku release",
+		label: dryRun ? `${releaseType} · dry-run` : releaseType
+	});
+	const manifest = await readManifest(ctx.files);
+	if (!manifest?.name) {
+		ui.error("package.json is missing, malformed, or has no `name`");
+		return 1;
+	}
+	await ctx.exec.capture("git", [
+		"fetch",
+		"--tags",
+		"--prune"
+	]);
+	if (!await preflight(ctx, ui)) return 1;
+	const declared = repositoryUrlOf(manifest);
+	const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
+	const tag = distTagFor(releaseType === "prerelease" ? "0.0.0-rc.0" : "0.0.0");
+	const before = parseDistTags((await ctx.exec.capture("npm", [
+		"view",
+		manifest.name,
+		"dist-tags",
+		"--json"
+	])).stdout)?.[tag];
+	if (dryRun) {
+		ui.heading("Plan");
+		ui.info(`gh workflow run ${PUBLISH_WORKFLOW_FILE} -f release_type=${releaseType} --ref main`);
+		ui.info(`watch the run, then wait for npm dist-tag \`${tag}\` to move from ${before ?? "—"}`);
+		return 0;
+	}
+	ui.heading("Dispatch");
+	const dispatched = await ctx.exec.capture("gh", [
+		"workflow",
+		"run",
+		PUBLISH_WORKFLOW_FILE,
+		"-f",
+		`release_type=${releaseType}`,
+		"--ref",
+		"main"
+	]);
+	if (dispatched.code !== 0) {
+		ui.error("could not dispatch the workflow", dispatched.stderr.trim());
+		return 1;
+	}
+	ui.check(true, `${PUBLISH_WORKFLOW_FILE} dispatched (${releaseType})`);
+	const runId = await findDispatchedRun(ctx, sleep);
+	if (runId === void 0) {
+		ui.error("the dispatched run never appeared — check GitHub Actions");
+		return 1;
+	}
+	ui.heading("Run");
+	if (await ctx.exec.inherit("gh", [
+		"run",
+		"watch",
+		runId,
+		"--exit-status"
+	]) !== 0) {
+		ui.error(`run ${runId} did not succeed`);
+		return 1;
+	}
+	ui.heading("Registry");
+	const version = await awaitPublishedVersion(ctx, manifest.name, tag, before, sleep);
+	if (version === void 0) {
+		ui.error(`npm dist-tag \`${tag}\` did not move — the run passed but nothing was published`);
+		return 1;
+	}
+	renderSummary(ui, manifest.name, version, ownerRepo);
+	return 0;
+}
+//#endregion
+//#region src/commands/setup.ts
+/**
+* Announce a mutation under `--dry-run`. Every step calls this before acting; a `true`
+* answer means "already reported, do nothing".
+*
+* @param setup - The wizard state.
+* @param description - The mutation, phrased as an infinitive ("write .github/…").
+* @returns `true` when the run is a dry run and the caller must not act.
+* @example
+* if (deferred(setup, "write .github/workflows/ci.yml")) return;
+*/
+function deferred(setup, description) {
+	if (!setup.dryRun) return false;
+	setup.ui.info(`would ${description}`);
+	return true;
+}
+/**
+* Verify the two human-only prerequisites. Nothing else in the wizard can run without
+* them, and neither can be automated — the wizard prints the command and stops.
+*
+* @param setup - The wizard state.
+* @returns `true` when both `gh` and npm are authenticated.
+* @example
+* if (!(await ensurePrerequisites(setup))) return 1;
+*/
+async function ensurePrerequisites(setup) {
+	setup.ui.heading("Prerequisites");
+	for (const check of [ghAuthCheck, npmAuthCheck]) {
+		const result = await check.run(setup.ctx);
+		setup.ui.check(result.status === "pass", `${check.title} — ${result.detail}`, result.fix);
+		if (result.status === "fail") {
+			setup.ui.error(`run this yourself, then re-run setup: ${result.fix}`);
+			return false;
+		}
+	}
+	return true;
+}
+/**
+* Write the two thin workflows. A file that already calls the pinned central workflow is
+* left alone; a differing file is only replaced after an explicit confirm, and a `.bak`
+* copy is kept.
+*
+* @param setup - The wizard state.
+* @returns Nothing.
+* @example
+* await writeWorkflows(setup);
+*/
+async function writeWorkflows(setup) {
+	setup.ui.heading("Workflows");
+	for (const template of workflowTemplates) {
+		const existing = await setup.ctx.files.read(template.path);
+		if (existing === template.content) {
+			setup.ui.check(true, `${template.path} up to date`);
+			continue;
+		}
+		if (existing !== void 0) {
+			const kind = isThinWorkflow(existing, template) ? "differs" : "is a legacy workflow";
+			if (!await setup.prompts.confirm(`${template.path} ${kind}. Replace it (a .bak copy is kept)?`)) {
+				setup.ui.check(false, `${template.path} left unchanged`);
+				continue;
+			}
+			if (deferred(setup, `back up and replace ${template.path}`)) continue;
+			await setup.ctx.files.backup(template.path);
+		} else if (deferred(setup, `write ${template.path}`)) continue;
+		await setup.ctx.files.write(template.path, template.content);
+		setup.ui.check(true, `${template.path} written`);
+	}
+}
+/**
+* Bring `package.json` onto the release contract. The change summary is printed first and
+* applied only after a confirm; an already-compliant manifest is a checkmark.
+*
+* @param setup - The wizard state.
+* @param manifest - The manifest read at the start of the run.
+* @returns Nothing.
+* @example
+* await normalizeContract(setup, manifest);
+*/
+async function normalizeContract(setup, manifest) {
+	setup.ui.heading("package.json");
+	const origin = await setup.ctx.exec.capture("git", [
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	const { manifest: next, changes } = normalizeManifest(manifest, origin.code === 0 ? origin.stdout.trim() : void 0);
+	if (changes.length === 0) {
+		setup.ui.check(true, "already on contract");
+		return;
+	}
+	for (const change of changes) setup.ui.line(`      ${setup.ui.palette.dim(change)}`);
+	if (!await setup.prompts.confirm(`Apply ${changes.length} change(s) to package.json?`)) {
+		setup.ui.check(false, "package.json left unchanged");
+		return;
+	}
+	if (deferred(setup, `write package.json`)) return;
+	await setup.ctx.files.write(MANIFEST_PATH, formatManifest(next));
+	setup.ui.check(true, `${MANIFEST_PATH} normalized`);
+}
+/**
+* Perform the very first publish, if the package has no registry presence yet. Stdio is
+* inherited so npm — not this CLI — prompts for an OTP.
+*
+* @param setup - The wizard state.
+* @param name - The package name.
+* @param version - The version about to be published.
+* @returns `true` when the package exists on npm after this step.
+* @example
+* await firstPublish(setup, "@moku-labs/common", "0.2.0");
+*/
+async function firstPublish(setup, name, version) {
+	setup.ui.heading("First publish");
+	const view = await setup.ctx.exec.capture("npm", [
+		"view",
+		name,
+		"version"
+	]);
+	if (view.code === 0) {
+		setup.ui.check(true, `${name}@${view.stdout.trim()} already on npm`);
+		return true;
+	}
+	if (!await setup.prompts.confirm(`Publish ${name}@${version} to npm now?`)) {
+		setup.ui.check(false, "first publish skipped");
+		return false;
+	}
+	if (deferred(setup, `run bun run build && npm publish --access public`)) return false;
+	if (await setup.ctx.exec.inherit("bun", ["run", "build"]) !== 0) {
+		setup.ui.error("build failed — not publishing");
+		return false;
+	}
+	const published = await setup.ctx.exec.inherit("npm", [
+		"publish",
+		"--access",
+		"public"
+	]);
+	setup.ui.check(published === 0, `npm publish ${name}@${version}`);
+	return published === 0;
+}
+/**
+* Tag the published version and push ONLY that tag — the branch is never written from
+* here.
+*
+* @param setup - The wizard state.
+* @param version - The version that was published.
+* @returns Nothing.
+* @example
+* await pushVersionTag(setup, "0.2.0");
+*/
+async function pushVersionTag(setup, version) {
+	setup.ui.heading("Tag");
+	const tag = `v${version}`;
+	if ((await setup.ctx.exec.capture("git", [
+		"tag",
+		"--list",
+		tag
+	])).stdout.trim() !== "") {
+		setup.ui.check(true, `${tag} already exists`);
+		return;
+	}
+	if (deferred(setup, `tag ${tag} and push it`)) return;
+	await setup.ctx.exec.capture("git", [
+		"tag",
+		"-a",
+		tag,
+		"-m",
+		tag
+	]);
+	const pushed = await setup.ctx.exec.capture("git", [
+		"push",
+		"origin",
+		`refs/tags/${tag}`
+	]);
+	setup.ui.check(pushed.code === 0, `${tag} pushed`, pushed.code === 0 ? void 0 : pushed.stderr);
+}
+/**
+* Register this repository's `publish.yml` as npm's trusted publisher, so the release
+* workflow publishes over OIDC and no `NPM_TOKEN` ever exists.
+*
+* @param setup - The wizard state.
+* @returns Nothing.
+* @example
+* await registerTrustedPublisher(setup);
+*/
+async function registerTrustedPublisher(setup) {
+	setup.ui.heading("Trusted publisher");
+	const result = await trustedPublisherCheck.run(setup.ctx);
+	if (result.status !== "fail" || result.fix === void 0) {
+		setup.ui.check(result.status === "pass", `${result.detail}`, result.fix);
+		return;
+	}
+	if (deferred(setup, result.fix)) return;
+	const [command = "npm", ...args] = result.fix.split(" ");
+	const code = await setup.ctx.exec.inherit(command, args);
+	setup.ui.check(code === 0, "trusted publisher registered");
+}
+/**
+* Apply the PR-only branch ruleset to the default branch. Tags stay unrestricted — the
+* release workflow pushes them.
+*
+* @param setup - The wizard state.
+* @param ownerRepo - The `owner/repo` slug.
+* @returns Nothing.
+* @example
+* await applyBranchRuleset(setup, "moku-labs/common");
+*/
+async function applyBranchRuleset(setup, ownerRepo) {
+	setup.ui.heading("Branch ruleset");
+	const result = await branchRulesetCheck.run(setup.ctx);
+	if (result.status === "pass") {
+		setup.ui.check(true, result.detail);
+		return;
+	}
+	if (deferred(setup, `create the PR-only branch ruleset on ${ownerRepo}`)) return;
+	const created = await setup.ctx.exec.capture("gh", [
+		"api",
+		`repos/${ownerRepo}/rulesets`,
+		"--method",
+		"POST",
+		"--input",
+		"-"
+	], { input: renderMainRuleset() });
+	setup.ui.check(created.code === 0, "branch ruleset applied", created.stderr.trim() || void 0);
+}
+/**
+* Run the whole wizard. Every step is skippable, idempotent, and re-runnable; the last one
+* is always `doctor`, so the wizard's own verdict is the same report the operator gets
+* from `release:doctor`.
+*
+* @param options - The ports, console, prompts and dry-run flag.
+* @returns The process exit code (`0` when the final doctor run is clean).
+* @example
+* const code = await runSetup({ ctx, ui, prompts });
+*/
+async function runSetup(options) {
+	const setup = {
+		dryRun: false,
+		...options
+	};
+	const { ui } = setup;
+	ui.lockup({
+		wordmark: "moku release",
+		label: setup.dryRun ? "setup · dry-run" : "setup"
+	});
+	if (!await ensurePrerequisites(setup)) return 1;
+	const manifest = await readManifest(setup.ctx.files);
+	if (!manifest?.name || !manifest.version) {
+		ui.error(`${MANIFEST_PATH} is missing, malformed, or has no name/version`);
+		return 1;
+	}
+	await writeWorkflows(setup);
+	await normalizeContract(setup, manifest);
+	await firstPublish(setup, manifest.name, manifest.version);
+	await pushVersionTag(setup, manifest.version);
+	await registerTrustedPublisher(setup);
+	const declared = repositoryUrlOf(manifest);
+	const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
+	if (ownerRepo === void 0) ui.warn("no GitHub owner/repo — skipping the branch ruleset");
+	else await applyBranchRuleset(setup, ownerRepo);
+	ui.heading("Doctor");
+	return (await runDoctor({
+		ctx: setup.ctx,
+		ui
+	})).failed ? 1 : 0;
+}
+//#endregion
+//#region src/lib/argv.ts
+/**
+* @file `moku-release` — argv parsing, kept out of the entry so the entry stays a
+* dispatcher.
+*
+* The grammar is deliberately tiny: one positional (a command name, or a semver bump that
+* implies the `release` command) plus three flags. Anything unrecognized resolves to
+* `help` with an `error` set — the CLI never guesses what an operator meant.
+*/
+/** The semver bumps `moku-release <type>` accepts, in menu order. */
+const RELEASE_TYPES = [
+	"patch",
+	"minor",
+	"major",
+	"prerelease"
+];
+/**
+* Whether a positional argument is one of the semver bumps.
+*
+* @param value - The positional to test.
+* @returns `true` when it names a release type.
+* @example
+* isReleaseType("patch"); // true
+*/
+function isReleaseType(value) {
+	return RELEASE_TYPES.includes(value);
+}
+/**
+* Build a `help` result carrying the reason the invocation was rejected.
+*
+* @param error - The message shown above the usage block.
+* @returns The rejecting parse result.
+* @example
+* rejected("unknown flag `--force`");
+*/
+function rejected(error) {
+	return {
+		command: "help",
+		json: false,
+		dryRun: false,
+		error
+	};
+}
+/**
+* Parse the argument vector (without `node` and the script path).
+*
+* @param argv - The raw arguments, e.g. `process.argv.slice(2)`.
+* @returns What to run, and with which flags.
+* @example
+* parseArgv(["patch", "--dry-run"]);
+* // { command: "release", releaseType: "patch", json: false, dryRun: true }
+*/
+function parseArgv(argv) {
+	const flags = argv.filter((argument) => argument.startsWith("-"));
+	const positionals = argv.filter((argument) => !argument.startsWith("-"));
+	if (flags.includes("--help") || flags.includes("-h")) return {
+		command: "help",
+		json: false,
+		dryRun: false
+	};
+	const unknownFlag = flags.find((flag) => flag !== "--json" && flag !== "--dry-run");
+	if (unknownFlag) return rejected(`unknown flag \`${unknownFlag}\``);
+	if (positionals.length > 1) return rejected(`unexpected argument \`${positionals[1]}\``);
+	const json = flags.includes("--json");
+	const dryRun = flags.includes("--dry-run");
+	const [first] = positionals;
+	if (first === void 0) return {
+		command: "help",
+		json,
+		dryRun
+	};
+	if (first === "doctor" || first === "setup") return {
+		command: first,
+		json,
+		dryRun
+	};
+	if (first === "help") return {
+		command: "help",
+		json,
+		dryRun
+	};
+	if (isReleaseType(first)) return {
+		command: "release",
+		releaseType: first,
+		json,
+		dryRun
+	};
+	return rejected(`unknown command \`${first}\``);
+}
+//#endregion
+//#region src/lib/exec.ts
+/**
+* @file `moku-release` — the injectable command runner, the CLI's only door to the shell.
+*
+* Two shapes, because release work needs both: `capture` reads a command's output (every
+* check), `inherit` hands the terminal to the child so `npm publish` can prompt for an OTP
+* and `gh run watch` can redraw. Arguments are always passed as an argv array through
+* `execFile`/`spawn` — never a shell string, so nothing interpolated can be re-parsed by a
+* shell. Tests inject a stub {@link Executor} and therefore never touch git, gh or npm.
+*/
+/** Exit code POSIX shells use for "command not found" — what a missing binary reports. */
+const COMMAND_NOT_FOUND = 127;
+/**
+* Normalize whatever `execFile` rejected with into a {@link CommandOutput}. A non-zero exit
+* carries `code` plus both streams; a missing binary carries an `ENOENT`-style string code
+* and no exit status at all.
+*
+* @param error - The rejection value from `execFile`.
+* @returns The equivalent captured output.
+* @example
+* fromExecError({ code: 1, stdout: "", stderr: "not logged in" });
+*/
+function fromExecError(error) {
+	const shape = error;
+	return {
+		code: typeof shape.code === "number" ? shape.code : COMMAND_NOT_FOUND,
+		stdout: shape.stdout ?? "",
+		stderr: shape.stderr ?? String(error)
+	};
+}
+/**
+* Create the real {@link Executor}, rooted at `cwd`.
+*
+* @param cwd - Default working directory for every child process.
+* @returns An executor bound to that directory.
+* @example
+* const exec = createExecutor(process.cwd());
+* const { stdout } = await exec.capture("git", ["rev-parse", "HEAD"]);
+*/
+function createExecutor(cwd) {
+	/**
+	* Run a command and capture both streams, turning failures into data.
+	*
+	* @param command - The binary to run.
+	* @param args - The argument vector.
+	* @param options - Optional per-call overrides.
+	* @returns The exit code and captured streams.
+	* @example
+	* await capture("npm", ["--version"]);
+	*/
+	const capture = (command, args, options = {}) => new Promise((resolve) => {
+		const child = execFile(command, [...args], { cwd: options.cwd ?? cwd }, (error, stdout, stderr) => {
+			if (error) return resolve(fromExecError(error));
+			resolve({
+				code: 0,
+				stdout,
+				stderr
+			});
+		});
+		if (options.input !== void 0) child.stdin?.end(options.input);
+	});
+	/**
+	* Run a command attached to the parent's stdio so it can prompt and redraw.
+	*
+	* @param command - The binary to run.
+	* @param args - The argument vector.
+	* @param options - Optional per-call overrides.
+	* @returns The exit code (`127` when the binary is missing).
+	* @example
+	* await inherit("npm", ["login"]);
+	*/
+	const inherit = (command, args, options = {}) => new Promise((resolve) => {
+		const child = spawn(command, [...args], {
+			cwd: options.cwd ?? cwd,
+			stdio: "inherit"
+		});
+		child.on("error", () => resolve(COMMAND_NOT_FOUND));
+		child.on("close", (code) => resolve(code ?? 1));
+	});
+	return {
+		capture,
+		inherit
+	};
+}
+//#endregion
+//#region src/lib/files.ts
+/**
+* @file `moku-release` — the injectable file port, rooted at the package directory.
+*
+* The second (and last) door to the outside world. Checks only ever `read`; `setup` also
+* `write`s and takes a `.bak` before it replaces anything it did not author. Paths are
+* always repo-relative POSIX paths, so a test can back the whole CLI with a plain object.
+*/
+/** Suffix given to the copy `setup` keeps before overwriting a file it did not author. */
+const BACKUP_SUFFIX = ".bak";
+/**
+* Create the real {@link FileStore}, rooted at `root`.
+*
+* @param root - Absolute path every relative path resolves against.
+* @returns A file store bound to that directory.
+* @example
+* const files = createFileStore(process.cwd());
+* const manifest = await files.read("package.json");
+*/
+function createFileStore(root) {
+	/**
+	* Resolve a repo-relative path against the store root.
+	*
+	* @param relative - Repo-relative path.
+	* @returns The absolute path.
+	* @example
+	* absolute("package.json");
+	*/
+	const absolute = (relative) => path.resolve(root, relative);
+	/**
+	* Read a repo-relative file, mapping "missing" to `undefined`.
+	*
+	* @param path - Repo-relative path.
+	* @returns The contents, or `undefined`.
+	* @example
+	* await read("package.json");
+	*/
+	const read = async (path) => {
+		try {
+			return await readFile(absolute(path), "utf8");
+		} catch {
+			return;
+		}
+	};
+	/**
+	* Write a repo-relative file, creating parent directories first.
+	*
+	* @param path - Repo-relative path.
+	* @param content - The text to write.
+	* @returns Nothing.
+	* @example
+	* await write("README.md", "# hi");
+	*/
+	const write = async (path$1, content) => {
+		const target = absolute(path$1);
+		await mkdir(path.dirname(target), { recursive: true });
+		await writeFile(target, content, "utf8");
+	};
+	/**
+	* Copy a repo-relative file next to itself with a `.bak` suffix.
+	*
+	* @param path - Repo-relative path of the file to preserve.
+	* @returns The repo-relative path of the backup.
+	* @example
+	* await backup(".github/workflows/ci.yml");
+	*/
+	const backup = async (path) => {
+		const target = `${path}${BACKUP_SUFFIX}`;
+		await copyFile(absolute(path), absolute(target));
+		return target;
+	};
+	return {
+		read,
+		write,
+		backup
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @file `moku-release` — the CLI entry: build the ports, parse argv, dispatch, exit.
+*
+* Deliberately thin. It owns exactly three things — the branded console, the two injected
+* ports ({@link createExecutor} / {@link createFileStore}), and the exit code — so that
+* every decision worth testing lives in a command, a check, or a pure lib function, none
+* of which know that a process exists.
+*/
+/** The usage block, printed for `help`, for a bare invocation, and for a rejected one. */
+const USAGE = [
+	"  moku-release setup              one-time wizard: workflows, contract, first publish",
+	"  moku-release doctor [--json]    read-only diagnosis of the release setup",
+	`  moku-release <${RELEASE_TYPES.join("|")}>`,
+	"",
+	"  --dry-run                       print every action, mutate nothing",
+	"",
+	"  Two steps are yours alone — this CLI never handles a credential:",
+	"    gh auth login",
+	"    npm login"
+].join("\n");
+/**
+* Dispatch a parsed invocation to its command.
+*
+* @param parsed - The parsed argument vector.
+* @param ctx - The ports and flags every command runs against.
+* @param ui - The branded console.
+* @returns The process exit code.
+* @example
+* await dispatch(parseArgv(["doctor"]), ctx, ui);
+*/
+async function dispatch(parsed, ctx, ui) {
+	if (parsed.command === "doctor") {
+		if (!parsed.json) ui.lockup({
+			wordmark: "moku release",
+			label: "doctor"
+		});
+		return (await runDoctor({
+			ctx,
+			ui,
+			json: parsed.json
+		})).failed ? 1 : 0;
+	}
+	if (parsed.command === "setup") return runSetup({
+		ctx,
+		ui,
+		prompts: createBrandPrompts(),
+		dryRun: parsed.dryRun
+	});
+	if (parsed.command === "release" && parsed.releaseType !== void 0) return runRelease({
+		ctx,
+		ui,
+		releaseType: parsed.releaseType,
+		dryRun: parsed.dryRun
+	});
+	if (parsed.error !== void 0) ui.error(parsed.error);
+	ui.lockup({
+		wordmark: "moku release",
+		label: "usage"
+	});
+	ui.line(USAGE);
+	return parsed.error === void 0 ? 0 : 1;
+}
+/**
+* Build the ports from the current working directory and run the requested command.
+*
+* @returns The process exit code.
+* @example
+* process.exitCode = await main();
+*/
+async function main() {
+	const cwd = process.cwd();
+	const ui = createBrandConsole();
+	const ctx = {
+		cwd,
+		exec: createExecutor(cwd),
+		files: createFileStore(cwd),
+		strict: false
+	};
+	return dispatch(parseArgv(process.argv.slice(2)), ctx, ui);
+}
+process.exitCode = await main();
+//#endregion
+export {};