@moku-labs/ci 1.2.4 → 1.2.6

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) ·
+[Project checks](#project-checks) ·
 [PR previews](#pr-previews) ·
 [CLI](#cli) ·
 [The contract](#the-contract) ·
@@ -94,8 +95,8 @@ 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` · `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` |
+| [`package-ci.yml`](.github/workflows/package-ci.yml) | [`examples/package/ci.yml`](examples/package/ci.yml) | `lint` · `types` · `test` · `build` · `extra` · `preview` | `runs_on`, `bun_version`, `validate`, `preview`, `extra` |
+| [`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`, `extra` |
 | [`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 | — |
 
@@ -110,6 +111,30 @@ flowchart LR
 > A Layer-3 app copies `examples/app/ci.yml` by hand and needs a `deploy` script. The CLI
 > sets up packages only.
 
+## Project checks
+
+A check the five contract scripts do not cover goes in `extra`: a JSON array of script names.
+Each one is its own job, run after a build, and reported as `ci / extra (check:bundle)`.
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  ci:
+    uses: moku-labs/ci/.github/workflows/package-ci.yml@v1
+    with:
+      extra: '["check:bundle", "test:cli-e2e"]'
+```
+
+| Rule | Where |
+|---|---|
+| Give `publish.yml` the same `extra`, so a release waits for the same checks. | caller `publish.yml` |
+| `setup` never replaces a thin caller that differs from the template. | `moku-release setup` |
+| An `extra` job is not a required check until the ruleset of that repo names it. | repo ruleset |
+| A check that needs its own matrix or a cron stays a separate workflow file. `doctor` and `setup` only look at `ci.yml` and `publish.yml`. | the project |
+
+A package may keep its version in git tags only. `build` and `preview` then seed
+`package.json` from the latest `v*` tag before they pack. Nothing is committed.
+
 ## PR previews
 
 Every pull request commit is published to [pkg.pr.new](https://pkg.pr.new) by the `preview`

package/dist/release.mjs

@@ -685,19 +685,48 @@ 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]);
 }
 /**
+* What is wrong with a ruleset's required checks, measured against the central ones. A
+* legacy check is a central one without the caller prefix (`lint` for `ci / lint`): the thin
+* caller never reports it. Any other context is the project's own (`ci-pass` of a matrix
+* workflow) and is none of our business.
+*
+* @param required - The contexts the ruleset requires.
+* @param central - The central contexts (`ci / lint`, …).
+* @returns The legacy contexts to drop and the central ones still missing.
+* @example
+* requiredChecksDrift(["lint", "ci-pass"], ["ci / lint"]); // { legacy: ["lint"], missing: ["ci / lint"] }
+*/
+function requiredChecksDrift(required, central) {
+	const bare = new Set(central.map((context) => context.slice(5)));
+	return {
+		legacy: required.filter((context) => bare.has(context)),
+		missing: central.filter((context) => !required.includes(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.
+* rule is kept as it is, and so is every required check the project added itself.
 *
 * @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.
+* @returns The `PUT` body: the existing rules with the central required checks merged in.
 * @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] });
+	const centralContexts = requiredCheckContexts(template);
+	const { legacy } = requiredChecksDrift(requiredCheckContexts(existing), centralContexts);
+	const own = requiredCheckContexts(existing).filter((context) => !legacy.includes(context) && !centralContexts.includes(context));
+	const merged = central.map((rule) => ({
+		...rule,
+		parameters: {
+			...rule.parameters,
+			required_status_checks: [...rule.parameters?.required_status_checks ?? [], ...own.map((context) => ({ context }))]
+		}
+	}));
+	return JSON.stringify({ rules: [...kept, ...merged] });
 }
 /**
 * The id of the newest workflow run from `gh run list --json databaseId`.
@@ -1179,11 +1208,11 @@ function renderMainRuleset() {
 * const stale = await findStaleRuleset(ctx, "moku-labs/system", listing.stdout);
 */
 async function findStaleRuleset(ctx, ownerRepo, listing) {
-	const central = new Set(requiredCheckContexts(renderMainRuleset()));
+	const central = 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));
+		const { legacy } = requiredChecksDrift(requiredCheckContexts(detail.stdout), central);
 		if (legacy.length > 0) return {
 			id,
 			body: detail.stdout,
@@ -2217,16 +2246,15 @@ async function isCommittedUnchanged(setup, path) {
 *
 * @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;
+* if (!(await clearExistingWorkflow(setup, template))) continue;
 */
-async function clearExistingWorkflow(setup, template, existing) {
-	const kind = isThinWorkflow(existing, template) ? "differs" : "is a legacy workflow";
+async function clearExistingWorkflow(setup, template) {
 	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})?`)) {
+	const question = `${template.path} is a legacy workflow. Replace it (${safety})?`;
+	if (!await setup.prompts.confirm(question)) {
 		setup.ui.check(false, `${template.path} left unchanged`);
 		return false;
 	}
@@ -2252,7 +2280,11 @@ async function writeWorkflows(setup) {
 			setup.ui.check(true, `${template.path} up to date`);
 			continue;
 		}
-		if (!(existing === void 0 ? !deferred(setup, `write ${template.path}`) : await clearExistingWorkflow(setup, template, existing))) continue;
+		if (existing !== void 0 && isThinWorkflow(existing, template)) {
+			setup.ui.check(true, `${template.path} is a thin caller with its own inputs, left as is`);
+			continue;
+		}
+		if (!(existing === void 0 ? !deferred(setup, `write ${template.path}`) : await clearExistingWorkflow(setup, template))) continue;
 		await setup.ctx.files.write(template.path, template.content);
 		setup.ui.check(true, `${template.path} written`);
 	}
@@ -2295,10 +2327,10 @@ async function normalizeContract(setup, manifest) {
 *
 * @param setup - The wizard state.
 * @param name - The package name.
-* @param version - The version about to be published.
-* @returns `true` when this run performed the first publish.
+* @param version - The version about to be published; a released package may keep none.
+* @returns Where the package stands on npm after this step.
 * @example
-* await firstPublish(setup, "@moku-labs/common", "0.2.0");
+* const state = await firstPublish(setup, "@moku-labs/common", "0.2.0");
 */
 async function firstPublish(setup, name, version) {
 	setup.ui.heading("First publish");
@@ -2309,17 +2341,21 @@ async function firstPublish(setup, name, version) {
 	]);
 	if (view.code === 0) {
 		setup.ui.check(true, `${name}@${view.stdout.trim()} already on npm`);
-		return false;
+		return "present";
+	}
+	if (version === void 0) {
+		setup.ui.check(false, `${MANIFEST_PATH} has no \`version\`, a first publish needs one`);
+		return "absent";
 	}
 	if (!await setup.prompts.confirm(`Publish ${name}@${version} to npm now?`)) {
 		setup.ui.check(false, "first publish skipped");
-		return false;
+		return "absent";
 	}
-	if (deferred(setup, `run bun run build && npm publish --access public`)) return false;
-	if (needsOwner(setup, "first publish", "bun run build && npm publish --access public")) return false;
+	if (deferred(setup, `run bun run build && npm publish --access public`)) return "published";
+	if (needsOwner(setup, "first publish", "bun run build && npm publish --access public")) return "absent";
 	if (await setup.ctx.exec.inherit("bun", ["run", "build"]) !== 0) {
 		setup.ui.error("build failed — not publishing");
-		return false;
+		return "absent";
 	}
 	const published = await setup.ctx.exec.inherit("npm", [
 		"publish",
@@ -2327,7 +2363,7 @@ async function firstPublish(setup, name, version) {
 		"public"
 	]);
 	setup.ui.check(published === 0, `npm publish ${name}@${version}`);
-	return published === 0;
+	return published === 0 ? "published" : "absent";
 }
 /**
 * Tag the published version and push ONLY that tag — the branch is never written from
@@ -2346,6 +2382,10 @@ async function pushVersionTag(setup, version) {
 		setup.ui.check(true, `release tags exist, latest is ${latest}`);
 		return;
 	}
+	if (version === void 0) {
+		setup.ui.check(false, `${MANIFEST_PATH} has no \`version\` and the repo has no release tag`);
+		return;
+	}
 	const tag = `v${version}`;
 	if ((await setup.ctx.exec.capture("git", [
 		"tag",
@@ -2492,14 +2532,17 @@ async function runSetup(options) {
 	});
 	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`);
+	if (!manifest?.name) {
+		ui.error(`${MANIFEST_PATH} is missing, malformed, or has no name`);
 		return 1;
 	}
 	await writeWorkflows(setup);
 	await normalizeContract(setup, manifest);
-	const justPublished = await firstPublish(setup, manifest.name, manifest.version);
-	await pushVersionTag(setup, manifest.version);
+	const published = await firstPublish(setup, manifest.name, manifest.version);
+	if (published === "absent") {
+		ui.heading("Tag");
+		ui.check(false, "no version tag pushed, the package is not on npm yet");
+	} else await pushVersionTag(setup, manifest.version);
 	await registerTrustedPublisher(setup);
 	const declared = repositoryUrlOf(manifest);
 	const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
@@ -2510,7 +2553,7 @@ async function runSetup(options) {
 		ctx: setup.ctx,
 		ui
 	});
-	if (justPublished) ui.info("published just now: npm can answer 404 for a few minutes, re-run release:doctor then");
+	if (published === "published" && !setup.dryRun) ui.info("published just now: npm can answer 404 for a few minutes, re-run release:doctor then");
 	return report.failed ? 1 : 0;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/ci",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Central CI and release for the moku family: reusable workflows, caller examples and the moku-release CLI.",
   "type": "module",
   "sideEffects": [