@moku-labs/ci 1.3.0 → 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) ·
@@ -157,6 +158,40 @@ 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 |

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/ci",
-  "version": "1.3.0",
+  "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",