@moku-labs/ci 1.2.6 → 1.4.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) ·
@@ -40,14 +41,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 +63,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 +109,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
 
@@ -152,11 +158,45 @@ 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, 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

@@ -1109,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.
@@ -1163,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.
@@ -2290,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.
 *
@@ -2510,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`.
@@ -2537,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") {
@@ -2546,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/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

@@ -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.6",
+  "version": "1.4.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.3",
     "@types/bun": "1.3.14",
     "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.3",