@futurelastic/colab-handbook 1.14.0-rc.13 → 1.14.0-rc.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -157,7 +157,7 @@ const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
157
157
  const identity = require("../tools/lib/identity.js");
158
158
  const {
159
159
  handbookInfo, templateNames, templateChangedSince, cmpParts, cmpSemver,
160
- parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, looksLikeHandbookClaude,
160
+ parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, isCiProvenance, looksLikeHandbookClaude,
161
161
  } = stamp;
162
162
 
163
163
  const HERE = dirname(fileURLToPath(import.meta.url));
@@ -417,23 +417,29 @@ function satisfiesConstraint(version, constraint) {
417
417
 
418
418
  // Run all stamp/reconciliation checks for one repo, pushing findings via fail/warn.
419
419
  // Silent when there is nothing to say (the common, healthy case).
420
- function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", missingAxes = [], predatesAxes = [], writesRaw = null } = {}) {
420
+ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", missingAxes = [], predatesAxes = [], writesRaw = null, suggest = () => {} } = {}) {
421
421
  const cur = hb.version;
422
422
 
423
423
  const compareStamp = (kind, name, stampVersion, files, { isCi = false } = {}) => {
424
424
  // Deactivated while the handbook is untagged — a global note already says so.
425
425
  if (hb.untagged || !hb.hasGit) return;
426
+ // #607: a CI template is GUIDANCE. How an adopter's CI produces its verdict is the adopter's
427
+ // business; the handbook enforces only what `colab ship` reads (checked elsewhere in this file:
428
+ // trunk CI-gated, the branch trigger under gate: ci, ship-batch, the round-trip job name). So
429
+ // every stamp observation on a `ci-*` copy is information — never a fail, never a warn.
430
+ const warn_ = isCi ? suggest : warn;
431
+ const fail_ = isCi ? suggest : fail;
426
432
  if (name !== null && !tmplNames.has(name)) {
427
- warn(`${kind} stamped @ ${stampVersion} names unknown template "${name}" — not in handbook templates/`);
433
+ warn_(`${kind} stamped @ ${stampVersion} names unknown template "${name}" — not in handbook templates/`);
428
434
  return;
429
435
  }
430
436
  if (cmpSemver(stampVersion, cur) > 0) {
431
- warn(`${kind} stamped @ ${stampVersion} is NEWER than handbook current ${cur} — clock skew or a hand-edited stamp`);
437
+ warn_(`${kind} stamped @ ${stampVersion} is NEWER than handbook current ${cur} — clock skew or a hand-edited stamp`);
432
438
  return;
433
439
  }
434
440
  const { verifiable, changed, ruleNeutral } = templateChangedSince(HANDBOOK_ROOT, files, stampVersion);
435
441
  if (!verifiable) {
436
- warn(`${kind} stamped @ ${stampVersion}, a version not in this handbook checkout — cannot verify drift (fetch tags, or re-copy)`);
442
+ warn_(`${kind} stamped @ ${stampVersion}, a version not in this handbook checkout — cannot verify drift (fetch tags, or re-copy)`);
437
443
  return;
438
444
  }
439
445
  if (changed) {
@@ -452,8 +458,9 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
452
458
  // template stays a hard fail regardless of the declaration, for the identical reason
453
459
  // `isCi` already overrides ceremony above. Declaring nothing (the default) is unaffected
454
460
  // — that repo gets exactly today's fail.
455
- if (ruleNeutral && !isCi) warn(`${msg} (declared rule-neutral at commit time — see CONVENTIONS.md §8)`);
456
- else if (ceremony === "light" && !isCi) warn(`${msg} (ceremony: light — advisory, not a build/secret-scan template)`);
461
+ if (isCi) fail_(`${kind} copied @ ${stampVersion} — template has a newer suggestion (${cur}); adopt it if it helps: \`colab update\` shows the diff`);
462
+ else if (ruleNeutral) warn(`${msg} (declared rule-neutral at commit time — see CONVENTIONS.md §8)`);
463
+ else if (ceremony === "light") warn(`${msg} (ceremony: light — advisory)`);
457
464
  else fail(msg);
458
465
  }
459
466
  };
@@ -473,8 +480,11 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
473
480
  // that name exists). `unstampedFinding` is shared with `colab update` so the two tools
474
481
  // cannot drift on this. The `unrelated` finding is deliberately NOT raised here: it has no
475
482
  // action, and the audit reports drift, not reassurance.
476
- const finding = unstampedFinding(workflowProvenance(text, stem, tmplNames));
477
- if (finding && finding.state === 'unstamped') warn(`${wf} unstamped — ${finding.reason}`);
483
+ const prov = workflowProvenance(text, stem, tmplNames);
484
+ const finding = unstampedFinding(prov);
485
+ // #607: an unstamped CI copy is the adopter's own CI — information, like any CI-template drift.
486
+ const isCiCopy = isCiProvenance(prov); // the bare import: `stamp` is shadowed in this loop
487
+ if (finding && finding.state === 'unstamped') (isCiCopy ? suggest : warn)(`${wf} unstamped — ${finding.reason}`);
478
488
  }
479
489
  }
480
490
 
@@ -2096,7 +2106,9 @@ function auditRepoInner(target, ctx) {
2096
2106
  // was ever asked.
2097
2107
  const missingAxes = cfg ? stamp.AXES.filter((a) => !(a in cfg)) : [];
2098
2108
  info.predatesAxes = [];
2099
- if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw });
2109
+ info.suggestions = [];
2110
+ const suggest = (t) => info.suggestions.push(t);
2111
+ if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
2100
2112
 
2101
2113
  // ---- repository metadata identity scan (#228 part 4) ----------------------
2102
2114
  // Explicitly NOT gated on isSelf: the handbook is public, its description and topics are
@@ -3348,6 +3360,8 @@ function report(results, opts, ctx) {
3348
3360
  else if (r.adoption === "local") lines.push(`⌂ adopted locally, not committed — descriptor hidden by .git/info/exclude; a repo the fleet does not own (CONVENTIONS.md §9)${r.clean ? " ✓" : ""}`);
3349
3361
  else if (r.clean) lines.push("✓");
3350
3362
  r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
3363
+ // #607: CI-template drift — information, not a finding, so it never changes clean/ok.
3364
+ (r.suggestions || []).forEach((s) => lines.push(`▸ ${s}`));
3351
3365
  // #556: the measured picture — information, not a finding, so it never changes clean/ok.
3352
3366
  if (r.batchHistory?.status === "read") {
3353
3367
  r.batchHistory.picture.forEach((l) => lines.push(`▸ ${l}`));
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.13"
36
+ "version": "1.14.0-rc.15"
37
37
  }
@@ -12,12 +12,56 @@ Starting points you **copy into your own repo**. That is the entire model.
12
12
  > workflow that silently changes under a hundred repos is the failure mode we are
13
13
  > avoiding.
14
14
 
15
+ **The CI templates are guidance, not enforcement (#607).** Change your copy in any way you
16
+ like. The audit reports a difference from a CI template as a `▸` suggestion only, never a fail
17
+ or warn. The handbook enforces only what `colab ship` reads from your CI
18
+ ([CONVENTIONS §7, *What ship reads*](../CONVENTIONS.md#what-ship-reads--the-ci-contract-607)):
19
+ - a run on every push to trunk;
20
+ - a run on a branch push where `gate: authoritative: ci`;
21
+ - a run on `ship-batch/**` where `ship-batch` is above 1;
22
+ - a `Migration round-trip…` job where `migration-grant: reviewer`.
23
+
24
+ ### Two lanes — light on every merge, heavy on official builds and nightly
25
+
26
+ | Lane | Template → copy | Runs | What |
27
+ |---|---|---|---|
28
+ | **light** | `ci-<stack>.yml` → `ci.yml` | every push (branch and trunk); the lane `colab ship` reads | secret scan, build, typecheck/lint, the fast tests — aim for under 5 minutes at p50 |
29
+ | **heavy** | `ci-<stack>-heavy.yml` → `ci-heavy.yml` | nightly on trunk's tip (skipped when trunk has not moved since the last green nightly), at every release candidate and tag, and by hand — **never per merge** | the whole suite including heavy-marked tests, integration, browser/e2e, load |
30
+
31
+ - **The adopter marks which tests are heavy; an unmarked test is light**, so nothing stops
32
+ running per merge until someone decides it should.
33
+ - Node: a `test:heavy` script, for example over `*.heavy.test.*` files that `test` does not run.
34
+ - Python: the pytest marker `heavy`.
35
+ - Laravel: the Pest/PHPUnit group `heavy`.
36
+ - **The heavy lane gates official builds.** `release-tag.yml` calls it (`workflow_call`) at the
37
+ tag and publishes only on green. `release-auto.yml` dispatches it at every new candidate and
38
+ finalizes only on its green run at that candidate's exact sha. With no `ci-heavy.yml`, both
39
+ skip the gate.
40
+ - **A red nightly is a trunk finding, not a merge block.** It files one `trunk-red` issue per
41
+ lane, naming the commit range since the last green nightly. An open issue for the lane
42
+ suppresses a new one. If the issue list cannot be read, it files nothing and fails the job.
43
+ - **Exposure sets the bar.** `live`/`released` repos run the heavy lane before every official
44
+ build. `none`/`self` repos may run it nightly only.
45
+ - **The trade-off:** a defect the light lane misses can sit on trunk for up to a day. Where a
46
+ merge queue and spare runners exist, a full run per batch is an optional third trigger.
47
+ - **Traps the heavy template already handles:**
48
+ - It has no push or `pull_request` trigger, so ship never counts its run.
49
+ - The `plan` job, not an all-skipped run, is what concludes `success` on a skipped nightly.
50
+ - It has no `concurrency` group, so no heavy run is ever cancelled.
51
+ - The nightly never commits.
52
+ - The tested sha is in the job name, `Full suite @ <sha>`, which is how the next nightly knows
53
+ whether trunk moved.
54
+ - **A docs-only change needs no CI wait:** `colab ship` decides that from the diff (#606). The
55
+ light templates show a commented `paths-ignore` for docs as an option; the old in-workflow
56
+ docs-only guard is gone.
57
+
15
58
  ## What each template is for
16
59
 
17
60
  | File | Copy to | For | Notes |
18
61
  |---|---|---|---|
19
62
  | `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. |
20
63
  | `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
64
+ | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
21
65
  | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
22
66
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
23
67
  | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
@@ -87,6 +131,8 @@ schema *before* the change — once more, the way a deploy lands new migrations
87
131
  that predates them. The schema after both passes must match. Two things to know before
88
132
  trusting a green run:
89
133
 
134
+ - **A `down()` that sqlite cannot run, or one that does not undo its `up()`**, turns a leg red —
135
+ and nothing else in CI ever runs `down()`.
90
136
  - **Both legs matter.** The engines disagree: a `NOT NULL` column added without a default
91
137
  fails on sqlite when rows exist, while MariaDB accepts it and silently writes `''` into
92
138
  every existing row. A deploy-engine leg at a version production does not run proves
@@ -144,6 +190,7 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
144
190
  ```sh
145
191
  colab template # list templates + handbook version
146
192
  colab template ci-node --dest .github/workflows/ci.yml
193
+ colab template ci-node-heavy --dest .github/workflows/ci-heavy.yml # the heavy lane, optional
147
194
  colab template release-tag --dest .github/workflows/release.yml
148
195
  colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
149
196
  colab template deploy-container --dest .github/workflows/deploy-container.yml
@@ -270,8 +317,8 @@ silent updates, just an honest report that you are behind.
270
317
  If you're the one editing a template *in this repo* and the change touches no rule at
271
318
  all — a typo, a broken hyperlink, a comment — write `Rule-Neutral: yes` as a trailer on
272
319
  that commit. Every adopter's drift finding for it then downgrades to a warn instead of a
273
- hard fail, but only if **every** commit since their stamp declared it; a `ci-*` template
274
- is never eligible, trailer or not. Full contract: [CONVENTIONS.md §8](../CONVENTIONS.md#8-conformance-and-reconciliation).
320
+ hard fail, but only if **every** commit since their stamp declared it. A `ci-*` template's
321
+ drift is only ever a suggestion (#607), so the trailer is moot there. Full contract: [CONVENTIONS.md §8](../CONVENTIONS.md#8-conformance-and-reconciliation).
275
322
 
276
323
  ## Keeping honest
277
324
 
@@ -0,0 +1,366 @@
1
+ # CI heavy lane (Laravel) — TEMPLATE. Copy me into your repo at .github/workflows/ci-heavy.yml,
2
+ # beside ci.yml (copied from ci-laravel.yml). Guidance, not a dependency:
3
+ # you own the copy (CONVENTIONS.md §7).
4
+ #
5
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
6
+ #
7
+ # HEAVY LANE (#607): the whole suite, including tests marked heavy, plus anything too slow for
8
+ # every merge (integration, browser/e2e, load). The light lane (ci.yml) runs on every push and
9
+ # is the only lane `colab ship` reads. This one runs:
10
+ # - NIGHTLY, on trunk's tip. Skipped when trunk has not moved since the last green nightly.
11
+ # A red nightly opens one `trunk-red` issue naming the commit range that could have caused
12
+ # it. It never blocks a merge.
13
+ # - On every OFFICIAL BUILD: release-tag.yml calls this file and publishes only when it is
14
+ # green; release-auto.yml dispatches it at each candidate and finalizes only when it is
15
+ # green at that exact sha.
16
+ # - BY HAND: Actions → "CI (heavy)" → Run workflow, with a ref.
17
+ # Heavy is opt-in per test; an unmarked test is light. The marker:
18
+ # the Pest/PHPUnit group `heavy` (`->group('heavy')`, `#[Group('heavy')]`). The light
19
+ # lane excludes it; this lane runs the whole suite.
20
+ #
21
+ # Deliberately NOT triggered by push or pull_request: a run of this workflow must never count as
22
+ # a merge verdict (tools/lib/verify-runs.js sets schedule and dispatch runs aside).
23
+ # No concurrency block: a heavy run is never cancelled — a release may be waiting on it.
24
+
25
+ name: CI (heavy)
26
+
27
+ on:
28
+ schedule:
29
+ - cron: "23 2 * * *" # EDIT: nightly, UTC. Keep the cron in this one place.
30
+ workflow_dispatch:
31
+ inputs:
32
+ ref:
33
+ description: "Branch, tag or sha to test (empty = trunk's tip)"
34
+ required: false
35
+ default: ""
36
+ workflow_call:
37
+ inputs:
38
+ ref:
39
+ description: "Branch, tag or sha to test"
40
+ type: string
41
+ required: true
42
+
43
+ permissions: {}
44
+
45
+ env:
46
+ # EDIT: this repo's trunk (`trunk:` in .github/project.yml). A schedule always starts on the
47
+ # default branch; the nightly tests THIS branch's tip.
48
+ TRUNK: main
49
+ # EDIT: the same values as ci.yml.
50
+ VITE_APP_NAME: ""
51
+ WAYFINDER_ARGS: "--with-form"
52
+
53
+ jobs:
54
+ # Resolves the one commit this run tests, and decides whether to test it. This job is the one
55
+ # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
56
+ plan:
57
+ name: What to test
58
+ runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
59
+ timeout-minutes: 5
60
+ permissions:
61
+ actions: read
62
+ contents: read
63
+ outputs:
64
+ sha: ${{ steps.plan.outputs.sha }}
65
+ run: ${{ steps.plan.outputs.run }}
66
+ since: ${{ steps.plan.outputs.since }}
67
+ steps:
68
+ - name: Resolve the commit; skip a nightly on an unmoved trunk
69
+ id: plan
70
+ env:
71
+ GH_TOKEN: ${{ github.token }}
72
+ EVENT: ${{ github.event_name }}
73
+ REF: ${{ inputs.ref }}
74
+ REPO: ${{ github.repository }}
75
+ WORKFLOW_REF: ${{ github.workflow_ref }}
76
+ run: |
77
+ set -uo pipefail
78
+ target="${REF:-$TRUNK}"
79
+ if ! sha="$(gh api "repos/$REPO/commits/$target" --jq .sha)" || [ -z "$sha" ]; then
80
+ echo "::error::cannot resolve '$target' to a commit"
81
+ exit 1
82
+ fi
83
+ echo "sha=$sha" >> "$GITHUB_OUTPUT"
84
+ run=true; since=""
85
+ if [ "$EVENT" = "schedule" ]; then
86
+ # The last green nightly's tested commit, read from its `Full suite @ <sha>` job.
87
+ # Any read error leaves `since` empty, and the suite runs.
88
+ wf="${WORKFLOW_REF%@*}"; wf="${wf##*/}"
89
+ for id in $(gh api "repos/$REPO/actions/workflows/$wf/runs?event=schedule&status=success&per_page=10" \
90
+ --jq '.workflow_runs[].id' 2>/dev/null); do
91
+ since="$(gh api "repos/$REPO/actions/runs/$id/jobs" \
92
+ --jq '[.jobs[] | select(.conclusion == "success" and (.name | startswith("Full suite @ "))) | .name | ltrimstr("Full suite @ ")][0] // ""' 2>/dev/null || true)"
93
+ [ -z "$since" ] || break
94
+ done
95
+ if [ "$since" = "$sha" ]; then
96
+ run=false
97
+ echo "::notice title=heavy-skipped::$TRUNK has not moved since the last green nightly ($sha)"
98
+ fi
99
+ fi
100
+ echo "run=$run" >> "$GITHUB_OUTPUT"
101
+ echo "since=$since" >> "$GITHUB_OUTPUT"
102
+ echo "Heavy lane: ${run} at \`$sha\`${since:+ (last green nightly: \`$since\`)}" >> "$GITHUB_STEP_SUMMARY"
103
+
104
+ heavy:
105
+ # The tested sha is in the job name: the next nightly reads it back to decide whether trunk moved.
106
+ name: Full suite @ ${{ needs.plan.outputs.sha }}
107
+ needs: plan
108
+ if: ${{ needs.plan.outputs.run == 'true' }}
109
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
+ timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
111
+ permissions:
112
+ contents: read
113
+ defaults:
114
+ run:
115
+ # EDIT: the same directory as ci.yml's build job.
116
+ working-directory: .
117
+ steps:
118
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
119
+ with:
120
+ ref: ${{ needs.plan.outputs.sha }}
121
+ persist-credentials: false
122
+
123
+ # Toolchain and install: the same steps as ci.yml's build job, so both lanes resolve the
124
+ # same versions. Keep them in step when you edit either.
125
+ # ---------------------------------------------------------------------------
126
+ # Toolchain resolution. Precedence, highest first:
127
+ # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
128
+ # Node: 1. .github/project.yml -> node: 2. .nvmrc, else package.json engines.node
129
+ # ...and if neither declares it, FAIL.
130
+ #
131
+ # There is deliberately NO fallback default. A silent default is exactly how a
132
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
133
+ # CI was green and proved nothing about what actually shipped. Keep these equal
134
+ # to what the deploy target runs, or CI proves nothing.
135
+ # ---------------------------------------------------------------------------
136
+ - name: Resolve toolchain versions
137
+ id: toolchain
138
+ run: |
139
+ set -euo pipefail
140
+
141
+ # "^8.3" / ">=22.1" / "v22" / "8.4.*" -> "8.3" / "22.1" / "22" / "8.4"
142
+ normalise() {
143
+ printf '%s' "$1" \
144
+ | tr -d '"' \
145
+ | sed -E 's/^[^0-9]*//' \
146
+ | sed -E 's/[[:space:]].*$//' \
147
+ | sed -E 's/\.(x|\*)$//' \
148
+ | sed -E 's/[^0-9.].*$//' \
149
+ | sed -E 's/\.$//'
150
+ }
151
+
152
+ # Read a flat `key: value` out of .github/project.yml. That file is a
153
+ # handful of top-level keys by design, so this is sufficient.
154
+ from_project_yml() {
155
+ [ -f .github/project.yml ] || return 0
156
+ sed -nE "s/^[[:space:]]*$1:[[:space:]]*\"?([^\"#[:space:]]+)\"?.*/\1/p" .github/project.yml | head -1
157
+ }
158
+
159
+ # --- PHP ---------------------------------------------------------------
160
+ PHP_VERSION=""; PHP_SOURCE=""
161
+ V="$(from_project_yml php || true)"
162
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
163
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE=".github/project.yml (php:)"
164
+ fi
165
+ if [ -z "$PHP_VERSION" ] && [ -f composer.json ]; then
166
+ V=""
167
+ if command -v php >/dev/null 2>&1; then
168
+ V="$(php -r '$c=json_decode(file_get_contents("composer.json"),true); echo $c["require"]["php"] ?? "";' || true)"
169
+ elif command -v python3 >/dev/null 2>&1; then
170
+ V="$(python3 -c "import json;print((json.load(open('composer.json')).get('require') or {}).get('php') or '')" || true)"
171
+ elif command -v node >/dev/null 2>&1; then
172
+ V="$(node -e "try{const r=require('./composer.json').require||{};process.stdout.write(String(r.php||''))}catch(_){}" || true)"
173
+ fi
174
+ if [ -n "$V" ]; then
175
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE="composer.json (require.php)"
176
+ fi
177
+ fi
178
+ if [ -z "$PHP_VERSION" ]; then
179
+ echo "::error::No PHP version is declared in this repository, and this workflow refuses to guess one."
180
+ {
181
+ echo "Declare it in ONE of:"
182
+ echo " 1. .github/project.yml -> php: \"8.4\" (preferred)"
183
+ echo " 2. composer.json -> \"require\": { \"php\": \"^8.4\" }"
184
+ echo "Use the version the DEPLOY target runs."
185
+ } >&2
186
+ exit 1
187
+ fi
188
+
189
+ # --- Node --------------------------------------------------------------
190
+ NODE_VERSION=""; NODE_SOURCE=""
191
+ V="$(from_project_yml node || true)"
192
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
193
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".github/project.yml (node:)"
194
+ fi
195
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
196
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
197
+ if [ -n "$V" ]; then
198
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".nvmrc"
199
+ fi
200
+ fi
201
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
202
+ V=""
203
+ if command -v node >/dev/null 2>&1; then
204
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
205
+ elif command -v python3 >/dev/null 2>&1; then
206
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
207
+ fi
208
+ if [ -n "$V" ]; then
209
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE="package.json (engines.node)"
210
+ fi
211
+ fi
212
+ if [ -z "$NODE_VERSION" ]; then
213
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
214
+ {
215
+ echo "Declare it in ONE of:"
216
+ echo " 1. .github/project.yml -> node: \"22\" (preferred)"
217
+ echo " 2. .nvmrc -> 22 or package.json -> \"engines\": { \"node\": \">=22\" }"
218
+ echo "Use the version the DEPLOY target runs."
219
+ } >&2
220
+ exit 1
221
+ fi
222
+
223
+ echo "php-version=$PHP_VERSION" >> "$GITHUB_OUTPUT"
224
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
225
+ echo "PHP $PHP_VERSION (from: $PHP_SOURCE) / Node $NODE_VERSION (from: $NODE_SOURCE)"
226
+ {
227
+ echo "PHP **$PHP_VERSION** — resolved from \`$PHP_SOURCE\`"
228
+ echo ""
229
+ echo "Node **$NODE_VERSION** — resolved from \`$NODE_SOURCE\`"
230
+ } >> "$GITHUB_STEP_SUMMARY"
231
+
232
+ - name: Setup PHP
233
+ uses: shivammathur/setup-php@v2
234
+ with:
235
+ php-version: ${{ steps.toolchain.outputs.php-version }}
236
+ # sqlite3 + pdo_sqlite are what the throwaway bootstrap below runs on.
237
+ extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
238
+ coverage: none
239
+
240
+ # Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
241
+ # with composer.lock present. Both halves are load-bearing:
242
+ # - No composer.lock → nothing stable to key on; every run would save a fresh entry.
243
+ # - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
244
+ # jobs; a remote cache on top was measured as a loss, not a saving (#512).
245
+ # Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
246
+ # and its body: `colab ship`'s cure rule matches steps by exact name.
247
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
248
+ # two steps.
249
+ - name: Locate Composer cache
250
+ id: composer-cache
251
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
252
+ run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
253
+
254
+ - name: Restore Composer cache
255
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
256
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
257
+ with:
258
+ path: ${{ steps.composer-cache.outputs.dir }}
259
+ key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
260
+ restore-keys: composer-${{ runner.os }}-
261
+
262
+ - name: Composer install
263
+ env:
264
+ RUN_TESTS: 'true' # the heavy lane always runs the suite
265
+ run: |
266
+ # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
267
+ # boots the app — and the app cannot boot until the .env below exists.
268
+ # Dev dependencies are installed only when the Pest suite will run; a build-
269
+ # only job does not need them (wayfinder lives in require, not require-dev).
270
+ if [ "$RUN_TESTS" = "true" ]; then
271
+ composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
272
+ else
273
+ composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader --no-scripts
274
+ fi
275
+
276
+ - name: Prepare throwaway env for build-time codegen (wayfinder)
277
+ run: |
278
+ # See the header: .env.example ships DB_CONNECTION=mysql, but there is no
279
+ # MySQL on the runner. Rewrite to sqlite against an empty file so artisan
280
+ # boots. This .env is disposable — deploy workflows rsync with --exclude
281
+ # '.env', so it can never reach a server.
282
+ cp .env.example .env
283
+ sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
284
+ touch database/database.sqlite
285
+ php artisan key:generate --force
286
+ php artisan package:discover --ansi
287
+
288
+ echo "=== PHP version on runner ==="
289
+ php -v
290
+
291
+ echo "=== wayfinder:generate (stderr visible) ==="
292
+ # Run it here rather than letting the Vite plugin invoke it: the plugin hides
293
+ # stderr and reports only "Command failed".
294
+ php artisan wayfinder:generate $WAYFINDER_ARGS
295
+
296
+ # npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
297
+ # package-lock.json present (`cache: npm` fails the step without one). The automatic
298
+ # `packageManager` cache is pinned to the same condition so it cannot override it.
299
+ # EDIT: to turn it off everywhere, replace both expressions with '' and false.
300
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
301
+ with:
302
+ node-version: ${{ steps.toolchain.outputs.node-version }}
303
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
304
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
305
+
306
+ - name: Build frontend assets (Vite)
307
+ run: |
308
+ npm ci
309
+ npm run build
310
+
311
+ - name: Run migrations against sqlite
312
+ run: php artisan migrate --force
313
+
314
+ - name: Test (the whole suite)
315
+ run: |
316
+ if [ -f vendor/bin/pest ]; then
317
+ vendor/bin/pest --ci
318
+ elif [ -f vendor/bin/phpunit ]; then
319
+ vendor/bin/phpunit
320
+ else
321
+ echo "::error::neither vendor/bin/pest nor vendor/bin/phpunit exists."
322
+ exit 1
323
+ fi
324
+ # EDIT: integration, browser/e2e (Dusk) or load jobs go here, or as jobs of their own with
325
+ # `needs: plan` and the same `if:` and checkout ref as this one.
326
+
327
+ # A red NIGHTLY is a trunk finding, never a merge block: one open issue per lane. An open issue
328
+ # with the same title suppresses a new one; an issue list that cannot be read files nothing and
329
+ # fails this job, so a silent miss is never mistaken for "already reported".
330
+ report:
331
+ name: Report a red nightly
332
+ needs: [plan, heavy]
333
+ if: ${{ always() && github.event_name == 'schedule' && needs.heavy.result == 'failure' }}
334
+ runs-on: ubuntu-latest # EDIT: needs `gh`.
335
+ timeout-minutes: 5
336
+ permissions:
337
+ issues: write
338
+ steps:
339
+ - name: File one trunk-red issue
340
+ env:
341
+ GH_TOKEN: ${{ github.token }}
342
+ REPO: ${{ github.repository }}
343
+ SHA: ${{ needs.plan.outputs.sha }}
344
+ SINCE: ${{ needs.plan.outputs.since }}
345
+ WORKFLOW: ${{ github.workflow }}
346
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
347
+ run: |
348
+ set -uo pipefail
349
+ title="Nightly heavy lane red: $WORKFLOW"
350
+ if ! open="$(gh issue list -R "$REPO" --state open --search "\"$title\" in:title" --json number,title \
351
+ --jq "[.[] | select(.title == \"$title\")][0].number // \"\"")"; then
352
+ echo "::error::cannot read this repo's issues — nothing filed; the red run is the only report"
353
+ exit 1
354
+ fi
355
+ if [ -n "$open" ]; then
356
+ echo "::notice::#$open already reports this lane red — not filing another."
357
+ exit 0
358
+ fi
359
+ if [ -n "$SINCE" ]; then
360
+ range="[\`${SINCE:0:12}..${SHA:0:12}\`]($GITHUB_SERVER_URL/$REPO/compare/$SINCE...$SHA) — the commits since the last green nightly"
361
+ else
362
+ range="up to \`${SHA:0:12}\` — no green nightly on record to bound it"
363
+ fi
364
+ gh label create trunk-red -R "$REPO" --color B60205 --description "Trunk fails a check" 2>/dev/null || true
365
+ body="$(printf 'The heavy lane failed on trunk at `%s`: %s\n\nCould have caused it: %s.\n\nA nightly never blocks a merge. Close this issue once a nightly is green again.\n' "$SHA" "$RUN_URL" "$range")"
366
+ gh issue create -R "$REPO" --title "$title" --label trunk-red --body "$body"