@moku-labs/ci 1.2.3 → 1.2.5

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

@@ -2152,6 +2152,22 @@ function deferred(setup, description) {
 	return true;
 }
 /**
+* Hand a step that needs the owner's OTP back to the owner. npm asks for the OTP in a
+* browser; with nobody at the keyboard (`--yes`) that would hang, so the command is printed.
+*
+* @param setup - The wizard state.
+* @param step - What the step does, as a noun phrase ("first publish").
+* @param command - The command the owner runs themselves.
+* @returns `true` when the run is unattended and the caller must not act.
+* @example
+* if (needsOwner(setup, "first publish", "npm publish --access public")) return false;
+*/
+function needsOwner(setup, step, command) {
+	if (!setup.unattended) return false;
+	setup.ui.check(false, `${step} needs your OTP, run it yourself`, command);
+	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.
 *
@@ -2201,16 +2217,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;
 	}
@@ -2236,7 +2251,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`);
 	}
@@ -2279,10 +2298,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");
@@ -2293,16 +2312,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 (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",
@@ -2310,7 +2334,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
@@ -2329,6 +2353,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",
@@ -2375,6 +2403,7 @@ async function registerTrustedPublisher(setup) {
 		return;
 	}
 	if (deferred(setup, registration)) return;
+	if (needsOwner(setup, "trusted publisher registration", registration)) return;
 	const [command = "npm", ...args] = registration.split(" ");
 	const code = await setup.ctx.exec.inherit(command, args);
 	const hint = code === 0 ? void 0 : `verify: ${result.fix}`;
@@ -2464,6 +2493,7 @@ async function applyBranchRuleset(setup, ownerRepo) {
 async function runSetup(options) {
 	const setup = {
 		dryRun: false,
+		unattended: false,
 		...options
 	};
 	const { ui } = setup;
@@ -2473,14 +2503,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);
@@ -2491,7 +2524,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
@@ -2831,7 +2864,8 @@ async function dispatch(parsed, ctx, ui) {
 		ctx,
 		ui,
 		prompts: parsed.yes || parsed.dryRun ? ASSENTING_PROMPTS : createBrandPrompts(),
-		dryRun: parsed.dryRun
+		dryRun: parsed.dryRun,
+		unattended: parsed.yes
 	});
 	if (parsed.command === "release" && parsed.releaseType !== void 0) return runRelease({
 		ctx,

package/package.json

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