@moku-labs/ci 1.1.3 → 1.2.2

package/README.md

@@ -22,6 +22,7 @@ everything else lives here, once. Not a build tool and not a framework — it ca
 [Install](#install) ·
 [How it works](#how-it-works) ·
 [Workflows](#workflows) ·
+[PR previews](#pr-previews) ·
 [CLI](#cli) ·
 [The contract](#the-contract) ·
 [Versioning](#versioning) ·
@@ -93,7 +94,7 @@ flowchart LR
 
 | Workflow | Called from | Jobs | Inputs (all optional) |
 |---|---|---|---|
-| [`package-ci.yml`](.github/workflows/package-ci.yml) | [`examples/package/ci.yml`](examples/package/ci.yml) | `lint` · `types` · `test` · `build` | `runs_on`, `bun_version`, `validate` |
+| [`package-ci.yml`](.github/workflows/package-ci.yml) | [`examples/package/ci.yml`](examples/package/ci.yml) | `lint` · `types` · `test` · `build` · `preview` | `runs_on`, `bun_version`, `validate`, `preview` |
 | [`package-release.yml`](.github/workflows/package-release.yml) | [`examples/package/publish.yml`](examples/package/publish.yml) | `check` → `release` → `package` → `publish` | `release_type`, `publish`, `runs_on`, `bun_version`, `node_version`, `artifact_name`, `validate` |
 | [`app-deploy.yml`](.github/workflows/app-deploy.yml) | [`examples/app/ci.yml`](examples/app/ci.yml) | `validate` → `deploy` to Cloudflare | script names (`lint_script`, `build_script`, `deploy_script`, …) and two required secrets |
 | [`self-test.yml`](.github/workflows/self-test.yml) | this repo only | `actionlint` over workflows and examples | — |
@@ -109,12 +110,29 @@ flowchart LR
 > A Layer-3 app copies `examples/app/ci.yml` by hand and needs a `deploy` script. The CLI
 > sets up packages only.
 
+## PR previews
+
+Every pull request commit is published to [pkg.pr.new](https://pkg.pr.new) by the `preview`
+job. Nothing reaches npm and no token is in scope. The bot comments the install command on
+the PR.
+
+```sh
+bun add https://pkg.pr.new/@moku-labs/core@42   # 42 = PR number, a commit sha works too
+```
+
+| Rule | Where |
+|---|---|
+| The [pkg.pr.new GitHub App](https://github.com/apps/pkg-pr-new) must be installed on the repo. | once per org |
+| The package repo must be public. The consuming project may be private. | pkg.pr.new |
+| 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` |
+
 ## CLI
 
 | Command | When | What it does |
 |---|---|---|
 | `bun run release:setup` | once per project | Idempotent wizard: workflows, script contract, first publish, first tag, trusted publisher, branch ruleset, then `doctor`. `--dry-run` prints every action and changes nothing. |
-| `bun run release:doctor` | any time | Changes nothing in the project; it only runs `git fetch --tags` first. Eleven checks, one line each, and the exact `fix:` command for every red line. `--json` for machines. |
+| `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. |
 
 The scripts are plain aliases of the `moku-release` bin. Internals and the list of checks:

package/dist/release.mjs

@@ -644,6 +644,61 @@ function parseJsonArray(stdout) {
 function hasMainBranchRuleset(stdout) {
 	return parseJsonArray(stdout).some((ruleset) => ruleset.target === BRANCH_TARGET && ruleset.enforcement !== "disabled");
 }
+/** Rule type GitHub uses for the required status checks of a ruleset. */
+const REQUIRED_CHECKS_RULE = "required_status_checks";
+/**
+* Parse the `rules` of one full ruleset, tolerating error text and non-object payloads.
+*
+* @param stdout - Output of `gh api repos/{owner}/{repo}/rulesets/{id}`, or a ruleset template.
+* @returns The rules, or an empty array when the payload has none.
+* @example
+* parseRules('{"rules":[{"type":"deletion"}]}');
+*/
+function parseRules(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		return Array.isArray(parsed?.rules) ? parsed.rules : [];
+	} catch {
+		return [];
+	}
+}
+/**
+* The ids of every active BRANCH ruleset, in listing order.
+*
+* @param stdout - Output of `gh api repos/{owner}/{repo}/rulesets`.
+* @returns The ruleset ids; a ruleset without an id is left out.
+* @example
+* activeBranchRulesetIds('[{"id":7,"target":"branch","enforcement":"active"}]'); // [7]
+*/
+function activeBranchRulesetIds(stdout) {
+	return parseJsonArray(stdout).filter((ruleset) => ruleset.target === BRANCH_TARGET && ruleset.enforcement !== "disabled").flatMap((ruleset) => ruleset.id === void 0 ? [] : [ruleset.id]);
+}
+/**
+* The status check contexts one full ruleset requires.
+*
+* @param stdout - One full ruleset as JSON.
+* @returns The required contexts, e.g. `["ci / lint"]`.
+* @example
+* requiredCheckContexts(renderMainRuleset()); // ["ci / lint", "ci / types", …]
+*/
+function requiredCheckContexts(stdout) {
+	return parseRules(stdout).filter((rule) => rule.type === REQUIRED_CHECKS_RULE).flatMap((rule) => rule.parameters?.required_status_checks ?? []).flatMap((check) => check.context === void 0 ? [] : [check.context]);
+}
+/**
+* The body that moves an existing ruleset onto the central required checks. Every other
+* rule of the existing ruleset is kept as it is.
+*
+* @param existing - The full existing ruleset as JSON.
+* @param template - The central ruleset template as JSON.
+* @returns The `PUT` body: the existing rules with the template's required checks.
+* @example
+* const body = withCentralRequiredChecks(existingJson, renderMainRuleset());
+*/
+function withCentralRequiredChecks(existing, template) {
+	const kept = parseRules(existing).filter((rule) => rule.type !== REQUIRED_CHECKS_RULE);
+	const central = parseRules(template).filter((rule) => rule.type === REQUIRED_CHECKS_RULE);
+	return JSON.stringify({ rules: [...kept, ...central] });
+}
 /**
 * The id of the newest workflow run from `gh run list --json databaseId`.
 *
@@ -719,16 +774,34 @@ function parseManifest(text) {
 async function readManifest(files) {
 	return parseManifest(await files.read(MANIFEST_PATH));
 }
+/** Any character outside printable ASCII and the JSON whitespace. */
+const NON_ASCII = /[^\t\n\r -~]/;
+/**
+* Whether a text holds only ASCII characters, i.e. every other character is `\uXXXX`-escaped.
+*
+* @param text - The file contents to test.
+* @returns `true` when no raw non-ASCII character is present.
+* @example
+* isAsciiOnly('{"description":"a \\u2014 b"}'); // true
+*/
+function isAsciiOnly(text) {
+	return !NON_ASCII.test(text);
+}
 /**
 * Render a manifest the way npm itself writes one: two-space JSON with a trailing newline.
+* A source file that was ASCII-only stays ASCII-only, so an escaped dash the package chose
+* does not show up as a changed line in the diff.
 *
 * @param manifest - The manifest to serialize.
+* @param source - The file contents the manifest was read from, when there were any.
 * @returns The file contents to write.
 * @example
-* await files.write("package.json", formatManifest(manifest));
+* await files.write("package.json", formatManifest(manifest, source));
 */
-function formatManifest(manifest) {
-	return `${JSON.stringify(manifest, void 0, 2)}\n`;
+function formatManifest(manifest, source) {
+	const text = `${JSON.stringify(manifest, void 0, 2)}\n`;
+	if (source === void 0 || !isAsciiOnly(source)) return text;
+	return text.replaceAll(new RegExp(NON_ASCII, "g"), (character) => String.raw`\u${character.codePointAt(0)?.toString(16).padStart(4, "0")}`);
 }
 /**
 * The repository URL a manifest declares, in either the object or shorthand string form.
@@ -894,6 +967,143 @@ function skip(detail) {
 	};
 }
 //#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/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/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/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/branch-ruleset.ts
 /**
 * @file `moku-release` — check: a branch ruleset protects the default branch.
@@ -901,15 +1111,40 @@ function skip(detail) {
 * 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. */
+/**
+* Find the first active branch ruleset whose required checks are not the central ones. A
+* legacy ruleset requires `lint`; the thin caller reports `ci / lint`, so no PR can merge.
+*
+* @param ctx - The injected ports.
+* @param ownerRepo - The `owner/repo` slug.
+* @param listing - Output of `gh api repos/{owner}/{repo}/rulesets`.
+* @returns The stale ruleset, or `undefined` when every ruleset is on the central checks.
+* @example
+* const stale = await findStaleRuleset(ctx, "moku-labs/system", listing.stdout);
+*/
+async function findStaleRuleset(ctx, ownerRepo, listing) {
+	const central = new Set(requiredCheckContexts(renderMainRuleset()));
+	for (const id of activeBranchRulesetIds(listing)) {
+		const detail = await ctx.exec.capture("gh", ["api", `repos/${ownerRepo}/rulesets/${id}`]);
+		if (detail.code !== 0) continue;
+		const legacy = requiredCheckContexts(detail.stdout).filter((context) => !central.has(context));
+		if (legacy.length > 0) return {
+			id,
+			body: detail.stdout,
+			legacy
+		};
+	}
+}
+/** Verifies `gh api repos/{owner}/{repo}/rulesets` lists an active, up-to-date 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.
+	* List the repository's rulesets, look for an active branch-targeting one, and make sure
+	* it does not require legacy check names.
 	*
 	* @param ctx - The injected ports.
-	* @returns Pass when one exists, warn when none does.
+	* @returns Pass when one exists on the central checks, warn otherwise.
 	* @example
 	* await branchRulesetCheck.run(ctx);
 	*/
@@ -921,6 +1156,8 @@ const branchRulesetCheck = {
 		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");
+		const stale = await findStaleRuleset(ctx, ownerRepo, rulesets.stdout);
+		if (stale !== void 0) return warn(`ruleset requires legacy checks: ${stale.legacy.join(", ")}`, "moku-release setup");
 		return pass("active branch ruleset present");
 	}
 };
@@ -1216,6 +1453,59 @@ const packageContractCheck = {
 	}
 };
 //#endregion
+//#region src/checks/preview-deps.ts
+/**
+* @file `moku-release` — check: no dependency points at a pkg.pr.new preview build.
+*
+* A preview URL is for testing an unreleased upstream change. It has no provenance and dies
+* with its pull request, so a release must never be cut with one in the manifest. The `lint`
+* job of package-ci.yml refuses the same thing on every PR; this is the local view of it.
+*/
+/** Host every pkg.pr.new install URL contains. */
+const PREVIEW_HOST = "pkg.pr.new";
+/** The manifest tables a preview URL can sit in. */
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+/**
+* Names of every dependency whose range is a pkg.pr.new URL.
+*
+* @param manifest - The manifest to scan.
+* @returns The dependency names, in manifest order.
+* @example
+* previewDependencies({ dependencies: { "@moku-labs/core": "https://pkg.pr.new/@moku-labs/core@42" } });
+*/
+function previewDependencies(manifest) {
+	return DEPENDENCY_FIELDS.flatMap((field) => {
+		const table = manifest[field];
+		if (typeof table !== "object" || table === null) return [];
+		return Object.entries(table).filter(([, range]) => typeof range === "string" && range.includes(PREVIEW_HOST)).map(([name]) => name);
+	});
+}
+/** Verifies no dependency is installed from a pkg.pr.new preview. */
+const previewDepsCheck = {
+	id: "preview-deps",
+	title: "no pkg.pr.new preview dependencies",
+	/**
+	* Scan the dependency tables for preview URLs.
+	*
+	* @param ctx - The injected ports.
+	* @returns Pass when none is found, otherwise every preview dependency by name.
+	* @example
+	* await previewDepsCheck.run(ctx);
+	*/
+	async run(ctx) {
+		const manifest = await readManifest(ctx.files);
+		if (!manifest) return skip("package.json is missing or malformed");
+		const names = previewDependencies(manifest);
+		if (names.length > 0) return fail(`preview build of ${names.join(", ")}`, `release upstream, then: bun add ${names.join(" ")}`);
+		return pass("every dependency comes from the registry");
+	}
+};
+//#endregion
 //#region src/checks/repository-url.ts
 /**
 * @file `moku-release` — check: `repository.url` points at the real origin.
@@ -1296,64 +1586,6 @@ const tagSyncCheck = {
 	}
 };
 //#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.
@@ -1387,6 +1619,18 @@ function isUnauthorized(output) {
 	return /E401|ENEEDAUTH|401 Unauthorized/i.test(output);
 }
 /**
+* Whether npm refused the listing because the account needs a one-time password. Output is
+* captured here, so npm cannot prompt: the answer is unknown, not "missing".
+*
+* @param output - The combined stdout/stderr npm produced.
+* @returns `true` when npm asked for an OTP.
+* @example
+* isOtpRequired("npm error code EOTP");
+*/
+function isOtpRequired(output) {
+	return /EOTP|one-time password/i.test(output);
+}
+/**
 * The exact registration command for this package and repository.
 *
 * @param name - The package name.
@@ -1396,7 +1640,7 @@ function isUnauthorized(output) {
 * trustCommand("@moku-labs/common", "moku-labs/common");
 */
 function trustCommand(name, ownerRepo) {
-	return `npm trust github ${name} --file ${PUBLISH_WORKFLOW_FILE$1} --repo ${ownerRepo} --yes`;
+	return `npm trust github ${name} --file ${PUBLISH_WORKFLOW_FILE$1} --repo ${ownerRepo} --allow-publish --yes`;
 }
 /** Verifies a trusted publisher is registered for the package. */
 const trustedPublisherCheck = {
@@ -1423,90 +1667,12 @@ 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("npm asks for an OTP, cannot verify from here", `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}`);
 	}
 };
 //#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.
@@ -1576,6 +1742,7 @@ const allChecks = [
 	npmAuthCheck,
 	npmVersionCheck,
 	packageContractCheck,
+	previewDepsCheck,
 	repositoryUrlCheck,
 	workflowsCheck,
 	npmPackageCheck,
@@ -1948,9 +2115,55 @@ async function ensurePrerequisites(setup) {
 	return true;
 }
 /**
+* Whether git already holds this exact file: tracked, and with no uncommitted change.
+*
+* @param setup - The wizard state.
+* @param path - Repo-relative path of the file.
+* @returns `true` when `git checkout -- <path>` would bring the current content back.
+* @example
+* await isCommittedUnchanged(setup, ".github/workflows/ci.yml");
+*/
+async function isCommittedUnchanged(setup, path) {
+	if ((await setup.ctx.exec.capture("git", [
+		"ls-files",
+		"--error-unmatch",
+		path
+	])).code !== 0) return false;
+	const status = await setup.ctx.exec.capture("git", [
+		"status",
+		"--porcelain",
+		"--",
+		path
+	]);
+	return status.code === 0 && status.stdout.trim() === "";
+}
+/**
+* Ask before replacing an existing workflow, and keep the original: in git when it is
+* committed and unmodified, in a `.bak` copy otherwise.
+*
+* @param setup - The wizard state.
+* @param template - The central workflow about to be written.
+* @param existing - The current contents of the file.
+* @returns `true` when the caller may write the template now.
+* @example
+* if (!(await clearExistingWorkflow(setup, template, existing))) continue;
+*/
+async function clearExistingWorkflow(setup, template, existing) {
+	const kind = isThinWorkflow(existing, template) ? "differs" : "is a legacy workflow";
+	const committed = await isCommittedUnchanged(setup, template.path);
+	const safety = committed ? "git keeps the original" : "a .bak copy is kept";
+	if (!await setup.prompts.confirm(`${template.path} ${kind}. Replace it (${safety})?`)) {
+		setup.ui.check(false, `${template.path} left unchanged`);
+		return false;
+	}
+	if (deferred(setup, `${committed ? "replace" : "back up and replace"} ${template.path}`)) return false;
+	if (!committed) await setup.ctx.files.backup(template.path);
+	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.
+* copy is kept unless git already holds the original.
 *
 * @param setup - The wizard state.
 * @returns Nothing.
@@ -1965,15 +2178,7 @@ async function writeWorkflows(setup) {
 			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;
+		if (!(existing === void 0 ? !deferred(setup, `write ${template.path}`) : await clearExistingWorkflow(setup, template, existing))) continue;
 		await setup.ctx.files.write(template.path, template.content);
 		setup.ui.check(true, `${template.path} written`);
 	}
@@ -2006,7 +2211,8 @@ async function normalizeContract(setup, manifest) {
 		return;
 	}
 	if (deferred(setup, `write package.json`)) return;
-	await setup.ctx.files.write(MANIFEST_PATH, formatManifest(next));
+	const source = await setup.ctx.files.read(MANIFEST_PATH);
+	await setup.ctx.files.write(MANIFEST_PATH, formatManifest(next, source));
 	setup.ui.check(true, `${MANIFEST_PATH} normalized`);
 }
 /**
@@ -2060,6 +2266,11 @@ async function firstPublish(setup, name, version) {
 */
 async function pushVersionTag(setup, version) {
 	setup.ui.heading("Tag");
+	const latest = latestVersionTag((await setup.ctx.exec.capture("git", [...LATEST_TAG_ARGS])).stdout);
+	if (latest !== void 0) {
+		setup.ui.check(true, `release tags exist, latest is ${latest}`);
+		return;
+	}
 	const tag = `v${version}`;
 	if ((await setup.ctx.exec.capture("git", [
 		"tag",
@@ -2122,6 +2333,21 @@ async function applyBranchRuleset(setup, ownerRepo) {
 		setup.ui.check(true, result.detail);
 		return;
 	}
+	const listing = await setup.ctx.exec.capture("gh", ["api", `repos/${ownerRepo}/rulesets`]);
+	const stale = await findStaleRuleset(setup.ctx, ownerRepo, listing.stdout);
+	if (stale !== void 0) {
+		if (deferred(setup, `move ruleset ${stale.id} on ${ownerRepo} to the ci / … checks`)) return;
+		const updated = await setup.ctx.exec.capture("gh", [
+			"api",
+			`repos/${ownerRepo}/rulesets/${stale.id}`,
+			"--method",
+			"PUT",
+			"--input",
+			"-"
+		], { input: withCentralRequiredChecks(stale.body, renderMainRuleset()) });
+		setup.ui.check(updated.code === 0, "branch ruleset updated", updated.stderr.trim() || void 0);
+		return;
+	}
 	if (deferred(setup, `create the PR-only branch ruleset on ${ownerRepo}`)) return;
 	const created = await setup.ctx.exec.capture("gh", [
 		"api",
@@ -2181,7 +2407,7 @@ async function runSetup(options) {
 * 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
+* implies the `release` command) plus four 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. */
@@ -2191,6 +2417,13 @@ const RELEASE_TYPES = [
 	"major",
 	"prerelease"
 ];
+/** Every flag the CLI accepts, besides `--help`. */
+const KNOWN_FLAGS = /* @__PURE__ */ new Set([
+	"--json",
+	"--dry-run",
+	"--yes",
+	"-y"
+]);
 /**
 * Whether a positional argument is one of the semver bumps.
 *
@@ -2215,6 +2448,7 @@ function rejected(error) {
 		command: "help",
 		json: false,
 		dryRun: false,
+		yes: false,
 		error
 	};
 }
@@ -2225,7 +2459,7 @@ function rejected(error) {
 * @returns What to run, and with which flags.
 * @example
 * parseArgv(["patch", "--dry-run"]);
-* // { command: "release", releaseType: "patch", json: false, dryRun: true }
+* // { command: "release", releaseType: "patch", json: false, dryRun: true, yes: false }
 */
 function parseArgv(argv) {
 	const flags = argv.filter((argument) => argument.startsWith("-"));
@@ -2233,34 +2467,40 @@ function parseArgv(argv) {
 	if (flags.includes("--help") || flags.includes("-h")) return {
 		command: "help",
 		json: false,
-		dryRun: false
+		dryRun: false,
+		yes: false
 	};
-	const unknownFlag = flags.find((flag) => flag !== "--json" && flag !== "--dry-run");
+	const unknownFlag = flags.find((flag) => !KNOWN_FLAGS.has(flag));
 	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 yes = flags.includes("--yes") || flags.includes("-y");
 	const [first] = positionals;
 	if (first === void 0) return {
 		command: "help",
 		json,
-		dryRun
+		dryRun,
+		yes
 	};
 	if (first === "doctor" || first === "setup") return {
 		command: first,
 		json,
-		dryRun
+		dryRun,
+		yes
 	};
 	if (first === "help") return {
 		command: "help",
 		json,
-		dryRun
+		dryRun,
+		yes
 	};
 	if (isReleaseType(first)) return {
 		command: "release",
 		releaseType: first,
 		json,
-		dryRun
+		dryRun,
+		yes
 	};
 	return rejected(`unknown command \`${first}\``);
 }
@@ -2445,12 +2685,32 @@ const USAGE = [
 	"  moku-release doctor [--json]    read-only diagnosis of the release setup",
 	`  moku-release <${RELEASE_TYPES.join("|")}>`,
 	"",
-	"  --dry-run                       print every action, mutate nothing",
+	"  --dry-run                       print every action, mutate nothing, ask nothing",
+	"  --yes, -y                       answer every setup confirmation with yes",
 	"",
 	"  Two steps are yours alone — this CLI never handles a credential:",
 	"    gh auth login",
 	"    npm login"
 ].join("\n");
+/** Prompts that never read stdin: every confirmation is a yes, every menu its first entry. */
+const ASSENTING_PROMPTS = {
+	/**
+	* Answer a confirmation with yes.
+	*
+	* @returns Always `true`.
+	* @example
+	* await ASSENTING_PROMPTS.confirm("Replace ci.yml?"); // true
+	*/
+	confirm: async () => true,
+	/**
+	* Pick the first entry of a menu.
+	*
+	* @returns Always `0`.
+	* @example
+	* await ASSENTING_PROMPTS.select("Bump?", ["patch", "minor"]); // 0
+	*/
+	select: async () => 0
+};
 /**
 * Dispatch a parsed invocation to its command.
 *
@@ -2476,7 +2736,7 @@ async function dispatch(parsed, ctx, ui) {
 	if (parsed.command === "setup") return runSetup({
 		ctx,
 		ui,
-		prompts: createBrandPrompts(),
+		prompts: parsed.yes || parsed.dryRun ? ASSENTING_PROMPTS : createBrandPrompts(),
 		dryRun: parsed.dryRun
 	});
 	if (parsed.command === "release" && parsed.releaseType !== void 0) return runRelease({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/ci",
-  "version": "1.1.3",
+  "version": "1.2.2",
   "description": "Central CI and release for the moku family: reusable workflows, caller examples and the moku-release CLI.",
   "type": "module",
   "sideEffects": [
@@ -56,8 +56,8 @@
     "lint:fix": "biome check --write . && eslint --fix .",
     "format": "biome format --write .",
     "test": "vitest run",
-    "release:setup": "moku-release setup",
-    "release:doctor": "moku-release doctor",
-    "release": "moku-release"
+    "release:setup": "bun run build && node dist/release.mjs setup",
+    "release:doctor": "bun run build && node dist/release.mjs doctor",
+    "release": "bun run build && node dist/release.mjs"
   }
 }