@moku-labs/ci 1.2.5 → 1.3.0

package/README.md

@@ -40,14 +40,16 @@ bun add -d @moku-labs/ci
 bun run release:setup
 ```
 
-`setup` writes the two workflow files, adds the missing scripts, does the first publish,
-registers the trusted publisher and applies the branch ruleset. Run it again any time — it
-only does what is still missing.
+`setup` writes the two workflow files and the Dependabot files, adds the missing scripts,
+does the first publish, registers the trusted publisher, applies the branch ruleset and
+allows auto-merge. Run it again any time — it only does what is still missing.
 
 > [!NOTE]
-> **Status: `1.x`, early.** `package-ci.yml`, `package-release.yml` and `moku-release release`
-> ship this package itself: `1.1.1` was the first live release, tokenless and with provenance.
-> `moku-release setup` has passed dry-run and unit tests only.
+> **Status: `1.x`, in use.** All eight moku packages — `core`, `common`, `web`, `worker`, `room`,
+> `system`, `ai`, `native` — run `package-ci.yml` and `package-release.yml` from `@v1`, and each
+> has shipped a tokenless release with provenance through them. `moku-release setup` did every
+> one of those migrations live, including two first publishes behind 2FA.
+> `app-deploy.yml` has no live user yet.
 
 > [!IMPORTANT]
 > Two steps are yours alone. The CLI never handles a credential, and there is no `NPM_TOKEN`
@@ -60,7 +62,7 @@ only does what is still missing.
 
 ## Why @moku-labs/ci
 
-- **One copy of the pipeline.** Seven repos had seven different `ci.yml` and six different
+- **One copy of the pipeline.** Eight packages had eight different `ci.yml` and eight different
   `publish.yml`. A fix now lands here and reaches every project through the `@v1` tag.
 - **Scripts are the interface, not tools.** The workflows call `bun run lint`, never `biome`.
   A project with special needs changes its own script, not the central YAML.
@@ -106,10 +108,13 @@ 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. |
 
 > [!TIP]
-> A Layer-3 app copies `examples/app/ci.yml` by hand and needs a `deploy` script. The CLI
-> sets up packages only.
+> A Layer-3 app copies `examples/app/ci.yml` and `examples/dependabot.yml` by hand and needs
+> a `deploy` script. An app merges Dependabot PRs by hand, because the merge runs the deploy.
+> The CLI sets up packages only.
 
 ## Project checks
 
@@ -156,7 +161,7 @@ bun add https://pkg.pr.new/@moku-labs/core@42   # 42 = PR number, a commit sha w
 
 | 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: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. |
 

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`.
@@ -1080,6 +1109,25 @@ 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/dependabot.ts
+/**
+* @file `moku-release` — the Dependabot templates.
+*
+* Read from this package's own `examples/dependabot.yml` and
+* `examples/package/dependabot-automerge.yml`. Dependabot opens one grouped PR a day when a
+* new `@moku-labs/*` version is out; the automerge workflow merges it once the required
+* `ci / …` checks pass. The config sits outside `examples/package/` on purpose: it is not a
+* workflow, and the self-test runs actionlint on every `.yml` one folder below `examples/`.
+*/
+/** Repo-relative path the Dependabot config is written to. */
+const DEPENDABOT_CONFIG_PATH = ".github/dependabot.yml";
+/** The Dependabot config body, read from `examples/dependabot.yml`. */
+const DEPENDABOT_CONFIG = readCentral("examples/dependabot.yml");
+/** Repo-relative path the automerge workflow is written to. */
+const DEPENDABOT_AUTOMERGE_PATH = ".github/workflows/dependabot-automerge.yml";
+/** The automerge workflow body, read from `examples/package/dependabot-automerge.yml`. */
+const DEPENDABOT_AUTOMERGE = readCentral("examples/package/dependabot-automerge.yml");
+//#endregion
 //#region src/templates/publish.ts
 /**
 * @file `moku-release` — the `.github/workflows/publish.yml` template.
@@ -1134,6 +1182,14 @@ const workflowTemplates = [{
 	content: PUBLISH_WORKFLOW,
 	ref: PUBLISH_WORKFLOW_REF
 }];
+/** The Dependabot config and its automerge workflow, in the order `setup` writes them. */
+const dependabotTemplates = [{
+	path: DEPENDABOT_CONFIG_PATH,
+	content: DEPENDABOT_CONFIG
+}, {
+	path: DEPENDABOT_AUTOMERGE_PATH,
+	content: DEPENDABOT_AUTOMERGE
+}];
 /**
 * 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.
@@ -1179,11 +1235,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,
@@ -2261,6 +2317,32 @@ async function writeWorkflows(setup) {
 	}
 }
 /**
+* Write the Dependabot config and its automerge workflow. A missing file is written; a
+* file that differs is the project's own config and is left alone, without asking.
+*
+* @param setup - The wizard state.
+* @returns Nothing.
+* @example
+* await writeDependabot(setup);
+*/
+async function writeDependabot(setup) {
+	setup.ui.heading("Dependabot");
+	for (const template of dependabotTemplates) {
+		const existing = await setup.ctx.files.read(template.path);
+		if (existing === template.content) {
+			setup.ui.check(true, `${template.path} up to date`);
+			continue;
+		}
+		if (existing !== void 0) {
+			setup.ui.check(true, `${template.path} is the project's own, left as is`);
+			continue;
+		}
+		if (deferred(setup, `write ${template.path}`)) continue;
+		await setup.ctx.files.write(template.path, template.content);
+		setup.ui.check(true, `${template.path} written`);
+	}
+}
+/**
 * Bring `package.json` onto the release contract. The change summary is printed first and
 * applied only after a confirm; an already-compliant manifest is a checkmark.
 *
@@ -2481,6 +2563,39 @@ async function applyBranchRuleset(setup, ownerRepo) {
 	setup.ui.check(created.code === 0, "branch ruleset applied", created.stderr.trim() || void 0);
 }
 /**
+* Turn on the repo setting the automerge workflow needs. Without it `gh pr merge --auto`
+* fails and every Dependabot PR waits for a manual merge.
+*
+* @param setup - The wizard state.
+* @param ownerRepo - The `owner/repo` slug.
+* @returns Nothing.
+* @example
+* await enableAutoMerge(setup, "moku-labs/common");
+*/
+async function enableAutoMerge(setup, ownerRepo) {
+	setup.ui.heading("Auto-merge");
+	const current = await setup.ctx.exec.capture("gh", [
+		"api",
+		`repos/${ownerRepo}`,
+		"--jq",
+		".allow_auto_merge"
+	]);
+	if (current.code === 0 && current.stdout.trim() === "true") {
+		setup.ui.check(true, "auto-merge already allowed");
+		return;
+	}
+	if (deferred(setup, `allow auto-merge on ${ownerRepo}`)) return;
+	const updated = await setup.ctx.exec.capture("gh", [
+		"api",
+		`repos/${ownerRepo}`,
+		"--method",
+		"PATCH",
+		"-F",
+		"allow_auto_merge=true"
+	]);
+	setup.ui.check(updated.code === 0, "auto-merge allowed", updated.stderr.trim() || void 0);
+}
+/**
 * Run the whole wizard. Every step is skippable, idempotent, and re-runnable; the last one
 * is always `doctor`, so the wizard's own verdict is the same report the operator gets
 * from `release:doctor`.
@@ -2508,6 +2623,7 @@ async function runSetup(options) {
 		return 1;
 	}
 	await writeWorkflows(setup);
+	await writeDependabot(setup);
 	await normalizeContract(setup, manifest);
 	const published = await firstPublish(setup, manifest.name, manifest.version);
 	if (published === "absent") {
@@ -2517,8 +2633,11 @@ async function runSetup(options) {
 	await registerTrustedPublisher(setup);
 	const declared = repositoryUrlOf(manifest);
 	const ownerRepo = declared === void 0 ? void 0 : ownerRepoFrom(declared);
-	if (ownerRepo === void 0) ui.warn("no GitHub owner/repo — skipping the branch ruleset");
-	else await applyBranchRuleset(setup, ownerRepo);
+	if (ownerRepo === void 0) ui.warn("no GitHub owner/repo — skipping the branch ruleset and auto-merge");
+	else {
+		await applyBranchRuleset(setup, ownerRepo);
+		await enableAutoMerge(setup, ownerRepo);
+	}
 	ui.heading("Doctor");
 	const report = await runDoctor({
 		ctx: setup.ctx,

package/examples/dependabot.yml

@@ -0,0 +1,15 @@
+# Dependabot for a moku-family repo. Only @moku-labs/* is watched, grouped into one PR a day.
+# A package also gets examples/package/dependabot-automerge.yml, so the PR merges itself
+# once the required ci / … checks pass. An app merges it by hand: that merge runs the deploy.
+version: 2
+updates:
+  - package-ecosystem: "bun"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-name: "@moku-labs/*"
+    groups:
+      moku:
+        patterns:
+          - "@moku-labs/*"

package/examples/package/dependabot-automerge.yml

@@ -0,0 +1,21 @@
+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.
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    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 }}

package/package.json

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