@moku-labs/ci 1.3.0 → 1.5.0

package/README.md

@@ -24,6 +24,7 @@ everything else lives here, once. Not a build tool and not a framework — it ca
 [Workflows](#workflows) ·
 [Project checks](#project-checks) ·
 [PR previews](#pr-previews) ·
+[Demos](#demos) ·
 [CLI](#cli) ·
 [The contract](#the-contract) ·
 [Versioning](#versioning) ·
@@ -90,8 +91,17 @@ flowchart LR
 1. `release:setup` writes two thin callers into `.github/workflows/`.
 2. Every PR runs `package-ci.yml`: four jobs, reported as `ci / lint`, `ci / types`,
    `ci / test`, `ci / build`.
-3. `release patch` dispatches `publish.yml`, which calls `package-release.yml`:
-   check → tag → pack → publish. The CLI watches the run and verifies the version on npm.
+3. Every merge to `main` runs `publish.yml`, which calls `package-release.yml`:
+   check → tag → pack → publish. The version is always a patch. `release wait` waits for
+   it and verifies the version on npm.
+4. A person runs `release minor`, or `release major` for a milestone. It dispatches the same
+   `publish.yml`.
+
+| Who releases | Version |
+|---|---|
+| a merge to `main` | patch, always |
+| a person | minor |
+| a person, for a milestone | major |
 
 ## Workflows
 
@@ -109,7 +119,7 @@ flowchart LR
 | [`examples/package/publish.local-publish.yml`](examples/package/publish.local-publish.yml) | Fallback: publish from the project's own job. Use it only if the central publish fails npm auth. |
 | [`rulesets/main.json`](rulesets/main.json) | Branch ruleset for `main`: PR only, no force-push, the four `ci / …` checks required. |
 | [`examples/dependabot.yml`](examples/dependabot.yml) | Dependabot config: one grouped PR a day for `@moku-labs/*` only. `setup` writes it to `.github/dependabot.yml`. |
-| [`examples/package/dependabot-automerge.yml`](examples/package/dependabot-automerge.yml) | Turns on auto-merge for a Dependabot PR; the ruleset checks stay the gate. `setup` writes it and allows auto-merge on the repo. |
+| [`examples/package/dependabot-automerge.yml`](examples/package/dependabot-automerge.yml) | Turns on auto-merge for a Dependabot PR; the ruleset checks stay the gate. After the merge it dispatches `publish.yml` with `patch`, because a merge made by `GITHUB_TOKEN` starts no push run. `setup` writes it and allows auto-merge on the repo. |
 
 > [!TIP]
 > A Layer-3 app copies `examples/app/ci.yml` and `examples/dependabot.yml` by hand and needs
@@ -157,13 +167,48 @@ bun add https://pkg.pr.new/@moku-labs/core@42   # 42 = PR number, a commit sha w
 | A preview URL never reaches `main`: the `lint` job and `doctor` both refuse it. | `package-ci.yml`, `preview-deps` |
 | `preview` is not a required check. Turn it off with `with: { preview: false }`. | caller `ci.yml` |
 
+## Demos
+
+`demos.yml` runs the moku demos (`moku-labs/demos`) against what a pull request builds, so an
+engine or editor change that breaks a real game fails on its own PR.
+
+```yaml
+demos:
+  needs: ci
+  if: github.event_name == 'pull_request'
+  uses: moku-labs/ci/.github/workflows/demos.yml@v1
+  with:
+    game: https://pkg.pr.new/@moku-labs/game@${{ github.event.pull_request.head.sha }}
+    tier: ${{ contains(github.event.pull_request.labels.*.name, 'demos:full') && 'full' || 'fast' }}
+```
+
+| Input | Default | Meaning |
+|---|---|---|
+| `game`, `editor` | `""` | A version, a pkg.pr.new URL, or empty for each demo's own pin |
+| `tier` | `fast` | `fast`: `bun run test` on ubuntu. `full`: plus `test:visual` on macos-latest and `test:editor` |
+| `demos_ref` | `main` | demos branch when no paired branch exists |
+| `paired_ref` | PR branch | demos branch with this name wins, for an intended break |
+| `only` | `[]` | JSON array of demo folders; empty = all |
+
+| Rule | Where |
+|---|---|
+| A demo is a folder whose `package.json` has `"moku": { "demo": true }`. | demos repo |
+| The workflow only calls the demo's scripts with `--engine` / `--editor`; the demo's runner picks the package, as it does locally. | demo runner |
+| A tracked file with `/Users/`, `/home/…` or `?? "../` fails the run. Paths are parameters. | `discover` |
+| Checks to require: `demos / fast`; `demos / full` reports only on the full tier. | rulesets |
+| Pixels run on macOS: on Linux runners WebGPU loses its device. | `visual-run` |
+
+Examples: `examples/package/ci-with-demos.yml` (label `demos:full`) and
+`examples/package/demos-comment.yml` (PR comment `/demos full`).
+
 ## CLI
 
 | Command | When | What it does |
 |---|---|---|
 | `bun run release:setup` | once per project | Idempotent wizard: workflows, Dependabot, script contract, first publish, first tag, trusted publisher, branch ruleset, auto-merge, then `doctor`. `--dry-run` prints every action, changes nothing and asks nothing. `--yes` answers every confirmation for an agent or CI; a step that needs your npm OTP is then printed, not run. |
 | `bun run release:doctor` | any time | Changes nothing in the project; it only runs `git fetch --tags` first. Twelve checks, one line each, and the exact `fix:` command for every red line. `--json` for machines. |
-| `bun run release <patch\|minor\|major\|prerelease>` | each release | Refuses unless the tree is clean and `HEAD == origin/main`. Dispatches `publish.yml`, watches the run, verifies the version and dist-tag on npm. |
+| `bun run release wait` | after each merge to `main` | Refuses unless `origin/main` holds `HEAD`. Waits for the first release tag that holds the commit, then for npm to serve that version. Stops on a failed run and prints the log command. |
+| `bun run release <patch\|minor\|major\|prerelease>` | a release a person asks for | Refuses unless the tree is clean and `HEAD == origin/main`. Dispatches `publish.yml`, watches the run, verifies the version and dist-tag on npm. |
 
 The scripts are plain aliases of the `moku-release` bin. Internals and the list of checks:
 [src/README.md](src/README.md).

package/dist/release.mjs

@@ -487,6 +487,57 @@ function createBrandPrompts(options = {}) {
 		if (!color) return `${question} [1-${count}] `;
 		return `    ${palette.dim(`pick 1–${count}`)} ${palette.cyan("›")} `;
 	};
+	let readline;
+	let closed = false;
+	const lines = [];
+	const waiters = [];
+	/**
+	* Show `prompt` and resolve the next input line. Lines that arrive before a question are
+	* queued; once the input has ended, the question resolves `""` (the prompt's default).
+	*
+	* @param prompt - The readline prompt string.
+	* @returns Resolves the raw answer line.
+	* @example
+	* await ask("Deploy? [y/N] ");
+	*/
+	const ask = (prompt) => {
+		if (closed && lines.length === 0) {
+			output.write(prompt);
+			return Promise.resolve("");
+		}
+		readline ??= openReadline();
+		readline.setPrompt(prompt);
+		readline.prompt();
+		const queued = lines.shift();
+		if (queued !== void 0) return Promise.resolve(queued);
+		readline.resume();
+		return new Promise((resolve) => waiters.push(resolve));
+	};
+	/**
+	* Create the shared interface: route each line to the oldest waiting question or the
+	* queue, pause while idle so the process can exit, and settle waiters on close.
+	*
+	* @returns The shared readline interface.
+	* @example
+	* readline ??= openReadline();
+	*/
+	const openReadline = () => {
+		const created = createInterface({
+			input,
+			output
+		});
+		created.on("line", (line) => {
+			const waiter = waiters.shift();
+			if (waiter) waiter(line);
+			else lines.push(line);
+			if (waiters.length === 0) created.pause();
+		});
+		created.on("close", () => {
+			closed = true;
+			for (const waiter of waiters.splice(0)) waiter("");
+		});
+		return created;
+	};
 	return {
 		/**
 		* Ask a yes/no question; resolves `true` only on an explicit `y`/`yes`.
@@ -497,16 +548,7 @@ function createBrandPrompts(options = {}) {
 		* 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()));
-				});
-			});
+			return ask(confirmPrompt(question)).then((answer) => YES_PATTERN.test(answer.trim()));
 		},
 		/**
 		* Present `choices` numbered from 1 and resolve the chosen zero-based index.
@@ -518,17 +560,10 @@ function createBrandPrompts(options = {}) {
 		* 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);
-				});
+			write(choicesBlock(question, choices));
+			return ask(selectPrompt(question, choices.length)).then((answer) => {
+				const picked = Number.parseInt(answer.trim(), 10);
+				return Number.isInteger(picked) && picked >= 1 && picked <= choices.length ? picked - 1 : 0;
 			});
 		}
 	};
@@ -742,6 +777,22 @@ function latestRunId(stdout) {
 	return String(first.databaseId);
 }
 /**
+* The runs from `gh run list --json databaseId,headSha,status,conclusion`, newest first.
+*
+* @param stdout - The raw `gh run list` JSON.
+* @returns The runs that carry an id and a commit; anything else is left out.
+* @example
+* parseRuns('[{"databaseId":42,"headSha":"abc123","status":"queued","conclusion":""}]');
+*/
+function parseRuns(stdout) {
+	return parseJsonArray(stdout).flatMap((run) => run.databaseId === void 0 || run.headSha === void 0 ? [] : [{
+		databaseId: run.databaseId,
+		headSha: run.headSha,
+		status: run.status ?? "",
+		conclusion: run.conclusion ?? ""
+	}]);
+}
+/**
 * The permalink of a GitHub release, for the final summary.
 *
 * @param ownerRepo - The `owner/repo` slug.
@@ -1707,7 +1758,7 @@ const tagSyncCheck = {
 * `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";
+const PUBLISH_WORKFLOW_FILE$2 = ".github/workflows/publish.yml".split("/").pop() ?? "publish.yml";
 /** Detail of the result when the listing sits behind 2FA; `setup` offers to register anyway. */
 const TRUST_NEEDS_OTP = "npm asks for an OTP, cannot verify from here";
 /**
@@ -1754,7 +1805,7 @@ function isOtpRequired(output) {
 * trustCommand("@moku-labs/common", "moku-labs/common");
 */
 function trustCommand(name, ownerRepo) {
-	return `npm trust github ${name} --file ${PUBLISH_WORKFLOW_FILE$1} --repo ${ownerRepo} --allow-publish --yes`;
+	return `npm trust github ${name} --file ${PUBLISH_WORKFLOW_FILE$2} --repo ${ownerRepo} --allow-publish --yes`;
 }
 /** Verifies a trusted publisher is registered for the package. */
 const trustedPublisherCheck = {
@@ -1782,8 +1833,8 @@ const trustedPublisherCheck = {
 		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 (isOtpRequired(`${listing.stdout}${listing.stderr}`)) return warn(TRUST_NEEDS_OTP, `npm trust list ${manifest.name}`);
-		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}`);
+		if (listing.code !== 0 || !listing.stdout.includes(PUBLISH_WORKFLOW_FILE$2)) return fail("no trusted publisher registered", trustCommand(manifest.name, ownerRepo));
+		return pass(`${ownerRepo} · ${PUBLISH_WORKFLOW_FILE$2}`);
 	}
 };
 //#endregion
@@ -1794,10 +1845,15 @@ const trustedPublisherCheck = {
 * 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.
+* passes. A thin `publish.yml` without the `push` trigger warns too: it releases only by
+* hand, and the family rule is a patch on every merge to main.
 */
 /** Advisory shown for a workflow that exists but does not call the central pipeline. */
 const LEGACY_FIX = "legacy workflow, run release:setup to migrate";
+/** Advisory shown for a thin `publish.yml` that does not release on a merge to main. */
+const AUTO_RELEASE_FIX = "add `push: branches: [main]` under `on:` in publish.yml";
+/** Matches the `push:` trigger of a workflow, at the indent `on:` gives its events. */
+const PUSH_TRIGGER = /^ {2}push:/m;
 /** Verifies `ci.yml` and `publish.yml` are the `@v1`-pinned thin callers. */
 const workflowsCheck = {
 	id: "workflows",
@@ -1813,13 +1869,16 @@ const workflowsCheck = {
 	async run(ctx) {
 		const missing = [];
 		const legacy = [];
+		let autoRelease = true;
 		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);
+			else if (template.path === ".github/workflows/publish.yml") autoRelease = PUSH_TRIGGER.test(content);
 		}
 		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);
+		if (!autoRelease) return warn("publish.yml does not release on a merge to main", AUTO_RELEASE_FIX);
 		return pass("ci.yml + publish.yml pinned to @v1");
 	}
 };
@@ -1978,9 +2037,9 @@ async function runDoctor(options) {
 //#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";
+const PUBLISH_WORKFLOW_FILE$1 = ".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 = 60;
+const REGISTRY_POLL_ATTEMPTS$1 = 60;
 /** Gap between registry polls — 60 × 10s = ten minutes. The first live release needed three. */
 const REGISTRY_POLL_INTERVAL_MS = 1e4;
 /** How many times to look for the dispatched run before concluding it never started. */
@@ -1995,7 +2054,7 @@ const RUN_LOOKUP_INTERVAL_MS = 3e3;
 * @example
 * await defaultSleep(500);
 */
-const defaultSleep = (ms) => new Promise((resolve) => {
+const defaultSleep$1 = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 /**
@@ -2026,7 +2085,7 @@ const LATEST_RUN_ARGS = [
 	"run",
 	"list",
 	"--workflow",
-	PUBLISH_WORKFLOW_FILE,
+	PUBLISH_WORKFLOW_FILE$1,
 	"--branch",
 	"main",
 	"--limit",
@@ -2081,7 +2140,7 @@ async function findDispatchedRun(ctx, previous, sleep) {
 * 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) {
+	for (let attempt = 0; attempt < REGISTRY_POLL_ATTEMPTS$1; attempt += 1) {
 		const view = await ctx.exec.capture("npm", [
 			"view",
 			name,
@@ -2124,7 +2183,7 @@ function renderSummary(ui, name, version, ownerRepo) {
 * const code = await runRelease({ ctx, ui, releaseType: "patch" });
 */
 async function runRelease(options) {
-	const { ctx, ui, releaseType, dryRun = false, sleep = defaultSleep } = options;
+	const { ctx, ui, releaseType, dryRun = false, sleep = defaultSleep$1 } = options;
 	ui.lockup({
 		wordmark: "moku release",
 		label: dryRun ? `${releaseType} · dry-run` : releaseType
@@ -2146,7 +2205,7 @@ async function runRelease(options) {
 	])).stdout)?.[tag];
 	if (dryRun) {
 		ui.heading("Plan");
-		ui.info(`gh workflow run ${PUBLISH_WORKFLOW_FILE} -f release_type=${releaseType} --ref main`);
+		ui.info(`gh workflow run ${PUBLISH_WORKFLOW_FILE$1} -f release_type=${releaseType} --ref main`);
 		ui.info(`watch the run, then wait for npm dist-tag \`${tag}\` to move from ${before ?? "—"}`);
 		return 0;
 	}
@@ -2155,7 +2214,7 @@ async function runRelease(options) {
 	const dispatched = await ctx.exec.capture("gh", [
 		"workflow",
 		"run",
-		PUBLISH_WORKFLOW_FILE,
+		PUBLISH_WORKFLOW_FILE$1,
 		"-f",
 		`release_type=${releaseType}`,
 		"--ref",
@@ -2165,7 +2224,7 @@ async function runRelease(options) {
 		ui.error("could not dispatch the workflow", dispatched.stderr.trim());
 		return 1;
 	}
-	ui.check(true, `${PUBLISH_WORKFLOW_FILE} dispatched (${releaseType})`);
+	ui.check(true, `${PUBLISH_WORKFLOW_FILE$1} dispatched (${releaseType})`);
 	const runId = await findDispatchedRun(ctx, previousRun, sleep);
 	if (runId === void 0) {
 		ui.error("the dispatched run never appeared — check GitHub Actions");
@@ -2647,6 +2706,193 @@ async function runSetup(options) {
 	return report.failed ? 1 : 0;
 }
 //#endregion
+//#region src/commands/wait.ts
+/** Workflow file whose runs are read — the one that releases on a push to main. */
+const PUBLISH_WORKFLOW_FILE = ".github/workflows/publish.yml".split("/").pop() ?? "publish.yml";
+/** How long to wait for a tag that holds the commit — 120 × 10s = twenty minutes. */
+const TAG_POLL_ATTEMPTS = 120;
+/** How long to wait for a run to start before saying none will — 12 × 10s = two minutes. */
+const RUN_START_ATTEMPTS = 12;
+/** How long to keep asking the registry for the version — 60 × 10s = ten minutes. */
+const REGISTRY_POLL_ATTEMPTS = 60;
+/** Gap between polls of every loop here. */
+const POLL_INTERVAL_MS = 1e4;
+/** The `gh run list` call that reads the newest `publish.yml` runs on main. */
+const RECENT_RUNS_ARGS = [
+	"run",
+	"list",
+	"--workflow",
+	PUBLISH_WORKFLOW_FILE,
+	"--branch",
+	"main",
+	"--limit",
+	"5",
+	"--json",
+	"databaseId,headSha,status,conclusion"
+];
+/** Argv for the release tags that hold a commit, oldest first: the first one shipped it. */
+const TAGS_WITH_HEAD_ARGS = [
+	"-c",
+	"versionsort.suffix=-",
+	"tag",
+	"--list",
+	"v*",
+	"--contains",
+	"HEAD",
+	"--sort=v:refname"
+];
+/**
+* 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);
+});
+/**
+* Whether `HEAD` is an ancestor of a ref, i.e. the ref holds the commit.
+*
+* @param ctx - The ports and flags.
+* @param ref - A branch, tag or sha.
+* @returns `true` when the ref holds `HEAD`.
+* @example
+* await holdsHead(ctx, "origin/main");
+*/
+async function holdsHead(ctx, ref) {
+	return (await ctx.exec.capture("git", [
+		"merge-base",
+		"--is-ancestor",
+		"HEAD",
+		ref
+	])).code === 0;
+}
+/**
+* The newest `publish.yml` run whose commit holds `HEAD`. A run of a later merge counts:
+* its version carries the commit too.
+*
+* @param ctx - The ports and flags.
+* @returns The run, or `undefined` when no run covers the commit yet.
+* @example
+* const run = await coveringRun(ctx);
+*/
+async function coveringRun(ctx) {
+	const listing = await ctx.exec.capture("gh", RECENT_RUNS_ARGS);
+	if (listing.code !== 0) return void 0;
+	for (const run of parseRuns(listing.stdout)) if (await holdsHead(ctx, run.headSha)) return run;
+}
+/**
+* Wait until a release tag holds `HEAD`. Stops early when the covering run failed, or when
+* no run started at all.
+*
+* @param ctx - The ports and flags.
+* @param ui - The branded console.
+* @param sleep - The delay helper.
+* @returns The tag, or `undefined` after the reason was printed.
+* @example
+* const tag = await awaitTag(ctx, ui, defaultSleep);
+*/
+async function awaitTag(ctx, ui, sleep) {
+	for (let attempt = 0; attempt < TAG_POLL_ATTEMPTS; attempt += 1) {
+		await ctx.exec.capture("git", [
+			"fetch",
+			"--tags",
+			"--prune"
+		]);
+		const tags = await ctx.exec.capture("git", TAGS_WITH_HEAD_ARGS);
+		const tag = tags.code === 0 ? latestVersionTag(tags.stdout) : void 0;
+		if (tag !== void 0) return tag;
+		const run = await coveringRun(ctx);
+		if (run === void 0 && attempt >= RUN_START_ATTEMPTS) {
+			ui.error(`no ${PUBLISH_WORKFLOW_FILE} run started for this commit`, `${PUBLISH_WORKFLOW_FILE} needs \`push: branches: [main]\`; a Dependabot merge needs the dispatch step of dependabot-automerge.yml`);
+			return;
+		}
+		if (run?.status === "completed" && run.conclusion !== "success") {
+			ui.error(`run ${run.databaseId} ended as ${run.conclusion}`, `gh run view ${run.databaseId} --log-failed`);
+			return;
+		}
+		await sleep(POLL_INTERVAL_MS);
+	}
+	ui.error("no release tag holds this commit after twenty minutes");
+}
+/**
+* Poll the registry until it serves one exact version. The registry lags behind a
+* successful publish, so "not there yet" is expected for a while.
+*
+* @param ctx - The ports and flags.
+* @param name - The package name.
+* @param version - The version the tag names.
+* @param sleep - The delay helper.
+* @returns `true` when the registry serves the version.
+* @example
+* await awaitVersion(ctx, "@moku-labs/common", "1.2.4", defaultSleep);
+*/
+async function awaitVersion(ctx, name, version, sleep) {
+	for (let attempt = 0; attempt < REGISTRY_POLL_ATTEMPTS; attempt += 1) {
+		const view = await ctx.exec.capture("npm", [
+			"view",
+			`${name}@${version}`,
+			"version"
+		]);
+		if (view.code === 0 && view.stdout.trim() === version) return true;
+		await sleep(POLL_INTERVAL_MS);
+	}
+	return false;
+}
+/**
+* Wait for the auto-release of `HEAD`: the commit is on `origin/main`, a release tag holds
+* it, and npm serves that version.
+*
+* @param options - The ports, console and delay helper.
+* @returns The process exit code.
+* @example
+* const code = await runWait({ ctx, ui });
+*/
+async function runWait(options) {
+	const { ctx, ui, sleep = defaultSleep } = options;
+	ui.lockup({
+		wordmark: "moku release",
+		label: "wait"
+	});
+	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 holdsHead(ctx, "origin/main")) {
+		ui.error("HEAD is not on origin/main", "merge the PR, then: git checkout main && git pull");
+		return 1;
+	}
+	ui.heading("Tag");
+	const tag = await awaitTag(ctx, ui, sleep);
+	if (tag === void 0) return 1;
+	ui.check(true, `${tag} holds this commit`);
+	ui.heading("Registry");
+	const version = tag.replace(/^v/, "");
+	if (!await awaitVersion(ctx, manifest.name, version, sleep)) {
+		ui.error(`npm does not serve ${manifest.name}@${version} after ten minutes`);
+		return 1;
+	}
+	const declared = repositoryUrlOf(manifest);
+	const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
+	const lines = [
+		ui.railLine(manifest.name, version, 48),
+		ui.railLine("tag", tag, 48),
+		ui.railLine("npm", npmPackageUrl(manifest.name, version), 48)
+	];
+	if (ownerRepo !== void 0) lines.push(ui.railLine("release", releaseUrl(ownerRepo, tag), 48));
+	ui.heading("Released");
+	ui.box(lines);
+	return 0;
+}
+//#endregion
 //#region src/lib/argv.ts
 /**
 * @file `moku-release` — argv parsing, kept out of the entry so the entry stays a
@@ -2729,7 +2975,7 @@ function parseArgv(argv) {
 		dryRun,
 		yes
 	};
-	if (first === "doctor" || first === "setup") return {
+	if (first === "doctor" || first === "setup" || first === "wait") return {
 		command: first,
 		json,
 		dryRun,
@@ -2929,8 +3175,12 @@ function createFileStore(root) {
 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 wait               wait for the auto-release of HEAD, verify it on npm",
 	`  moku-release <${RELEASE_TYPES.join("|")}>`,
 	"",
+	"  A merge to main releases a patch by itself. A person releases minor,",
+	"  or major for a milestone.",
+	"",
 	"  --dry-run                       print every action, mutate nothing, ask nothing",
 	"  --yes, -y                       answer every setup confirmation with yes",
 	"",
@@ -2986,6 +3236,10 @@ async function dispatch(parsed, ctx, ui) {
 		dryRun: parsed.dryRun,
 		unattended: parsed.yes
 	});
+	if (parsed.command === "wait") return runWait({
+		ctx,
+		ui
+	});
 	if (parsed.command === "release" && parsed.releaseType !== void 0) return runRelease({
 		ctx,
 		ui,

package/examples/package/ci-with-demos.yml

@@ -0,0 +1,28 @@
+name: CI
+
+# ci.yml of a package whose PRs must run the moku demos (the engine, the editor).
+# Same thin caller as ci.yml, plus a `demos` job after the preview is published.
+# Required checks: "ci / lint", "ci / types", "ci / test", "ci / build" and "demos / fast".
+# The label `demos:full` on the PR adds pixels (macOS) and editor scenarios: "demos / full".
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: moku-labs/ci/.github/workflows/package-ci.yml@v1
+
+  demos:
+    needs: ci
+    if: github.event_name == 'pull_request'
+    uses: moku-labs/ci/.github/workflows/demos.yml@v1
+    with:
+      # The preview job of `ci` published this commit; a full sha resolves on pkg.pr.new.
+      # In the editor's repo, pass `editor:` instead of `game:`.
+      game: https://pkg.pr.new/@moku-labs/game@${{ github.event.pull_request.head.sha }}
+      tier: ${{ contains(github.event.pull_request.labels.*.name, 'demos:full') && 'full' || 'fast' }}

package/examples/package/demos-comment.yml

@@ -0,0 +1,41 @@
+name: Demos on comment
+
+# A PR comment `/demos full` runs the full demos tier against the PR's preview, without a label.
+# Only members and collaborators can trigger it.
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+
+jobs:
+  head:
+    if: >-
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/demos full') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      sha: ${{ steps.pr.outputs.sha }}
+      ref: ${{ steps.pr.outputs.ref }}
+    steps:
+      - id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          gh api "repos/$REPO/pulls/$PR" --jq '"sha=\(.head.sha)\nref=\(.head.ref)"' >> "$GITHUB_OUTPUT"
+
+  demos:
+    needs: head
+    uses: moku-labs/ci/.github/workflows/demos.yml@v1
+    with:
+      game: https://pkg.pr.new/@moku-labs/game@${{ needs.head.outputs.sha }}
+      # issue_comment has no head_ref: name the branch to pair with explicitly.
+      paired_ref: ${{ needs.head.outputs.ref }}
+      tier: full

package/examples/package/dependabot-automerge.yml

@@ -2,20 +2,47 @@ name: Dependabot automerge
 
 # Turns on auto-merge for a Dependabot PR. The branch ruleset stays the gate: the merge
 # waits for ci / lint, ci / types, ci / test and ci / build. Needs the repo setting
-# allow_auto_merge, which `moku-release setup` turns on.
+# allow_auto_merge, which `moku-release setup` turns on. After the merge it dispatches
+# publish.yml, so a Dependabot merge releases a patch like any other merge.
 on: pull_request
 
+# One waiter per PR: a rebase of the PR starts a new run and ends the old one.
+concurrency:
+  group: dependabot-automerge-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 permissions:
   contents: write
   pull-requests: write
+  actions: write # dispatch publish.yml after the merge
 
 jobs:
   automerge:
     if: github.event.pull_request.user.login == 'dependabot[bot]'
     runs-on: ubuntu-latest
+    env:
+      PR_URL: ${{ github.event.pull_request.html_url }}
+      REPO: ${{ github.repository }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Merge once required checks pass
         run: gh pr merge --auto --squash "$PR_URL"
-        env:
-          PR_URL: ${{ github.event.pull_request.html_url }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Release the merge as a patch
+        # A merge made by GITHUB_TOKEN starts no push run, so the auto-release of publish.yml
+        # never sees it. workflow_dispatch is the one event GITHUB_TOKEN may start: wait for
+        # the merge, then dispatch the same patch a push would have cut.
+        run: |
+          set -euo pipefail
+          for _ in $(seq 1 90); do
+            state="$(gh pr view "$PR_URL" --json state --jq .state)"
+            case "$state" in
+              MERGED)
+                gh workflow run publish.yml --repo "$REPO" --ref main -f release_type=patch
+                exit 0 ;;
+              CLOSED)
+                echo "closed without a merge, nothing to release"
+                exit 0 ;;
+            esac
+            sleep 20
+          done
+          echo "::warning::not merged after 30 minutes, no release was dispatched"

package/examples/package/publish.local-publish.yml

@@ -8,6 +8,11 @@ name: Release
 # `npm publish` runs HERE, in this repo's own publish.yml, so the OIDC claim's
 # job_workflow_ref points at <owner>/<repo>/.github/workflows/publish.yml.
 on:
+  # Auto-release: every merge to main ships a PATCH. A person dispatches minor, or major for
+  # a milestone. A PR merged by GITHUB_TOKEN starts no push run: dependabot-automerge.yml
+  # dispatches the patch for its own merges.
+  push:
+    branches: [main]
   workflow_dispatch:
     inputs:
       release_type:
@@ -39,7 +44,7 @@ jobs:
     if: |
       always() && needs.release.outputs.artifact_name != '' &&
       (
-        (github.event_name == 'workflow_dispatch' && needs.release.outputs.tag != '') ||
+        (github.event_name != 'release' && needs.release.outputs.tag != '') ||
         github.event_name == 'release'
       )
     runs-on: ubuntu-latest
@@ -49,7 +54,7 @@ jobs:
     steps:
       - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && needs.release.outputs.tag || github.ref }}
+          ref: ${{ github.event_name != 'release' && needs.release.outputs.tag || github.ref }}
           persist-credentials: false
       - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
@@ -75,7 +80,7 @@ jobs:
         run: |
           set -euo pipefail
           pkg="$(node -p "require('./package.json').version")"
-          if [ "$EVENT" = "workflow_dispatch" ]; then want="$DISPATCH_VERSION"; else want="${REF_NAME#v}"; fi
+          if [ "$EVENT" = "release" ]; then want="${REF_NAME#v}"; else want="$DISPATCH_VERSION"; fi
           [ -n "$want" ] || { echo "empty version/ref — refusing to publish"; exit 1; }
           [ "$pkg" = "$want" ] || { echo "package.json $pkg != ref $want"; exit 1; }
           # Prereleases go to dist-tag 'next' so they never clobber 'latest'.

package/examples/package/publish.yml

@@ -3,6 +3,11 @@ name: Release
 # Thin caller. The FILENAME is a contract: npm Trusted Publishing is registered against
 # "publish.yml" for this repo — renaming it breaks tokenless publishing.
 on:
+  # Auto-release: every merge to main ships a PATCH. A person dispatches minor, or major for
+  # a milestone. A PR merged by GITHUB_TOKEN starts no push run: dependabot-automerge.yml
+  # dispatches the patch for its own merges.
+  push:
+    branches: [main]
   workflow_dispatch:
     inputs:
       release_type:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/ci",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Central CI and release for the moku family: reusable workflows, caller examples and the moku-release CLI.",
   "type": "module",
   "sideEffects": [
@@ -32,7 +32,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@moku-labs/common": "0.3.0",
+    "@moku-labs/common": "0.3.4",
     "@types/bun": "1.3.14",
     "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.3",