@futurelastic/colab-handbook 1.14.0-rc.14 → 1.14.0-rc.16

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
@@ -122,6 +122,7 @@ const installRoute = require("../tools/lib/install-route.js");
122
122
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
123
123
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
124
124
  const shipBatch = require("../tools/lib/ship-batch.js");
125
+ const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
125
126
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
126
127
  const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
127
128
  const batchHistory = require("../tools/lib/batch-history.js"); // #556
@@ -157,7 +158,7 @@ const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
157
158
  const identity = require("../tools/lib/identity.js");
158
159
  const {
159
160
  handbookInfo, templateNames, templateChangedSince, cmpParts, cmpSemver,
160
- parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, looksLikeHandbookClaude,
161
+ parseWorkflowStamp, parseClaudeStamp, workflowProvenance, unstampedFinding, isCiProvenance, looksLikeHandbookClaude,
161
162
  } = stamp;
162
163
 
163
164
  const HERE = dirname(fileURLToPath(import.meta.url));
@@ -417,23 +418,29 @@ function satisfiesConstraint(version, constraint) {
417
418
 
418
419
  // Run all stamp/reconciliation checks for one repo, pushing findings via fail/warn.
419
420
  // 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 } = {}) {
421
+ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", missingAxes = [], predatesAxes = [], writesRaw = null, suggest = () => {} } = {}) {
421
422
  const cur = hb.version;
422
423
 
423
424
  const compareStamp = (kind, name, stampVersion, files, { isCi = false } = {}) => {
424
425
  // Deactivated while the handbook is untagged — a global note already says so.
425
426
  if (hb.untagged || !hb.hasGit) return;
427
+ // #607: a CI template is GUIDANCE. How an adopter's CI produces its verdict is the adopter's
428
+ // business; the handbook enforces only what `colab ship` reads (checked elsewhere in this file:
429
+ // trunk CI-gated, the branch trigger under gate: ci, ship-batch, the round-trip job name). So
430
+ // every stamp observation on a `ci-*` copy is information — never a fail, never a warn.
431
+ const warn_ = isCi ? suggest : warn;
432
+ const fail_ = isCi ? suggest : fail;
426
433
  if (name !== null && !tmplNames.has(name)) {
427
- warn(`${kind} stamped @ ${stampVersion} names unknown template "${name}" — not in handbook templates/`);
434
+ warn_(`${kind} stamped @ ${stampVersion} names unknown template "${name}" — not in handbook templates/`);
428
435
  return;
429
436
  }
430
437
  if (cmpSemver(stampVersion, cur) > 0) {
431
- warn(`${kind} stamped @ ${stampVersion} is NEWER than handbook current ${cur} — clock skew or a hand-edited stamp`);
438
+ warn_(`${kind} stamped @ ${stampVersion} is NEWER than handbook current ${cur} — clock skew or a hand-edited stamp`);
432
439
  return;
433
440
  }
434
441
  const { verifiable, changed, ruleNeutral } = templateChangedSince(HANDBOOK_ROOT, files, stampVersion);
435
442
  if (!verifiable) {
436
- warn(`${kind} stamped @ ${stampVersion}, a version not in this handbook checkout — cannot verify drift (fetch tags, or re-copy)`);
443
+ warn_(`${kind} stamped @ ${stampVersion}, a version not in this handbook checkout — cannot verify drift (fetch tags, or re-copy)`);
437
444
  return;
438
445
  }
439
446
  if (changed) {
@@ -452,8 +459,9 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
452
459
  // template stays a hard fail regardless of the declaration, for the identical reason
453
460
  // `isCi` already overrides ceremony above. Declaring nothing (the default) is unaffected
454
461
  // — 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)`);
462
+ if (isCi) fail_(`${kind} copied @ ${stampVersion} — template has a newer suggestion (${cur}); adopt it if it helps: \`colab update\` shows the diff`);
463
+ else if (ruleNeutral) warn(`${msg} (declared rule-neutral at commit time — see CONVENTIONS.md §8)`);
464
+ else if (ceremony === "light") warn(`${msg} (ceremony: light — advisory)`);
457
465
  else fail(msg);
458
466
  }
459
467
  };
@@ -473,8 +481,11 @@ function checkStamps(src, hb, tmplNames, fail, warn, { ceremony = "standard", mi
473
481
  // that name exists). `unstampedFinding` is shared with `colab update` so the two tools
474
482
  // cannot drift on this. The `unrelated` finding is deliberately NOT raised here: it has no
475
483
  // 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}`);
484
+ const prov = workflowProvenance(text, stem, tmplNames);
485
+ const finding = unstampedFinding(prov);
486
+ // #607: an unstamped CI copy is the adopter's own CI — information, like any CI-template drift.
487
+ const isCiCopy = isCiProvenance(prov); // the bare import: `stamp` is shadowed in this loop
488
+ if (finding && finding.state === 'unstamped') (isCiCopy ? suggest : warn)(`${wf} unstamped — ${finding.reason}`);
478
489
  }
479
490
  }
480
491
 
@@ -1761,6 +1772,31 @@ function auditRepoInner(target, ctx) {
1761
1772
  }
1762
1773
  }
1763
1774
 
1775
+ // ---- integration-profile / heavy-workflow (#610) ---------------------------
1776
+ // Read through tools/lib/integration-profile.js — the module `colab ship` and `colab release` use,
1777
+ // so the audit and the gates cannot disagree about a value. A malformed value makes the gates fail
1778
+ // closed to release-heavy (ship unchanged), which is safe but silent, so it fails here. The `live`
1779
+ // restriction fails only a DECLARED qualify/release-heavy; a repo that never declared gets a
1780
+ // suggestion, never a new failure.
1781
+ let integrationSuggestion = null;
1782
+ if (cfg) {
1783
+ const ipCfg = integrationProfile.parseProfile(cfg);
1784
+ const hwCfg = integrationProfile.parseHeavyWorkflow(cfg);
1785
+ if (!ipCfg.valid) fail(`${ipCfg.reason} — see project.schema.md, integration-profile`);
1786
+ if (!hwCfg.valid) fail(`${hwCfg.reason} — see project.schema.md, heavy-workflow`);
1787
+ if (ipCfg.valid) {
1788
+ const lr = integrationProfile.liveRestriction({ profile: ipCfg.profile, declared: ipCfg.declared, exposure: authority ? authority.exposure : null, deploy });
1789
+ if (lr && lr.level === "fail") fail(lr.message);
1790
+ else if (lr) integrationSuggestion = lr.message;
1791
+ if (ipCfg.profile === "promote" && (!trunk || trunk === "main")) {
1792
+ fail(`integration-profile: promote gates the promotion into main with the heavy lane, but trunk is ${JSON.stringify(trunk)} — there is no promotion to gate. Choose gated, qualify or release-heavy (CONVENTIONS.md §7, Integration profiles)`);
1793
+ }
1794
+ if (ipCfg.profile === "gated" && hwCfg.valid && !workflows.includes(hwCfg.file)) {
1795
+ warn(`integration-profile: gated but no .github/workflows/${hwCfg.file} — colab ship refuses every code landing until a heavy lane exists (templates/ci-<stack>-heavy.yml), or name it with heavy-workflow:`);
1796
+ }
1797
+ }
1798
+ }
1799
+
1764
1800
  // Additive `--json` keys only (#144's oracle: "`tier` continues to report the DECLARED
1765
1801
  // letter... New keys are additive"). `axisOfRecord` names which key governs
1766
1802
  // ('exposure' | 'tier-legacy' | 'none' | null when project.yml itself did not parse);
@@ -2096,7 +2132,10 @@ function auditRepoInner(target, ctx) {
2096
2132
  // was ever asked.
2097
2133
  const missingAxes = cfg ? stamp.AXES.filter((a) => !(a in cfg)) : [];
2098
2134
  info.predatesAxes = [];
2099
- if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw });
2135
+ info.suggestions = [];
2136
+ const suggest = (t) => info.suggestions.push(t);
2137
+ if (integrationSuggestion) suggest(integrationSuggestion); // #610
2138
+ if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
2100
2139
 
2101
2140
  // ---- repository metadata identity scan (#228 part 4) ----------------------
2102
2141
  // Explicitly NOT gated on isSelf: the handbook is public, its description and topics are
@@ -3348,6 +3387,8 @@ function report(results, opts, ctx) {
3348
3387
  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
3388
  else if (r.clean) lines.push("✓");
3350
3389
  r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
3390
+ // #607: CI-template drift — information, not a finding, so it never changes clean/ok.
3391
+ (r.suggestions || []).forEach((s) => lines.push(`▸ ${s}`));
3351
3392
  // #556: the measured picture — information, not a finding, so it never changes clean/ok.
3352
3393
  if (r.batchHistory?.status === "read") {
3353
3394
  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.14"
36
+ "version": "1.14.0-rc.16"
37
37
  }
@@ -12,12 +12,71 @@ 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. A repo that
46
+ cannot accept that picks another `integration-profile:` (below).
47
+
48
+ ### Where each integration profile wires the heavy lane (#610)
49
+
50
+ `integration-profile:` in `project.yml` ([CONVENTIONS §7](../CONVENTIONS.md#integration-profiles--where-the-heavy-lane-runs-and-what-a-green-trunk-promises-610))
51
+ decides when the heavy lane runs. The light `ci.yml` is the same under every profile; only the heavy
52
+ file's triggers change:
53
+
54
+ | Profile | What to change in `ci-heavy.yml` |
55
+ |---|---|
56
+ | `release-heavy` (absent) | nothing — the template as copied: nightly, plus every official build |
57
+ | `gated` | nothing — `colab ship` dispatches it (`workflow_dispatch`, input `ref` = the sha) at each landing's branch or batch head, and lands only on its green. Keep `workflow_dispatch` and its `ref` input. |
58
+ | `qualify` | the `schedule` cron becomes the clock: every few hours on trunk's tip (e.g. `"23 */4 * * *"`), still skipped when trunk has not moved |
59
+ | `promote` | dispatch it on the trunk tip before `colab promote` (`gh workflow run ci-heavy.yml --ref dev -f ref=<sha>`) — promote refuses until it is green |
60
+
61
+ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `project.yml`.
62
+ - **Traps the heavy template already handles:**
63
+ - It has no push or `pull_request` trigger, so ship never counts its run.
64
+ - The `plan` job, not an all-skipped run, is what concludes `success` on a skipped nightly.
65
+ - It has no `concurrency` group, so no heavy run is ever cancelled.
66
+ - The nightly never commits.
67
+ - The tested sha is in the job name, `Full suite @ <sha>`, which is how the next nightly knows
68
+ whether trunk moved.
69
+ - **A docs-only change needs no CI wait:** `colab ship` decides that from the diff (#606). The
70
+ light templates show a commented `paths-ignore` for docs as an option; the old in-workflow
71
+ docs-only guard is gone.
72
+
15
73
  ## What each template is for
16
74
 
17
75
  | File | Copy to | For | Notes |
18
76
  |---|---|---|---|
19
77
  | `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
78
  | `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. |
79
+ | `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
80
  | `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
81
  | `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
82
  | `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 +146,8 @@ schema *before* the change — once more, the way a deploy lands new migrations
87
146
  that predates them. The schema after both passes must match. Two things to know before
88
147
  trusting a green run:
89
148
 
149
+ - **A `down()` that sqlite cannot run, or one that does not undo its `up()`**, turns a leg red —
150
+ and nothing else in CI ever runs `down()`.
90
151
  - **Both legs matter.** The engines disagree: a `NOT NULL` column added without a default
91
152
  fails on sqlite when rows exist, while MariaDB accepts it and silently writes `''` into
92
153
  every existing row. A deploy-engine leg at a version production does not run proves
@@ -144,6 +205,7 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
144
205
  ```sh
145
206
  colab template # list templates + handbook version
146
207
  colab template ci-node --dest .github/workflows/ci.yml
208
+ colab template ci-node-heavy --dest .github/workflows/ci-heavy.yml # the heavy lane, optional
147
209
  colab template release-tag --dest .github/workflows/release.yml
148
210
  colab template deploy-xserver --dest .github/workflows/deploy-xserver.yml
149
211
  colab template deploy-container --dest .github/workflows/deploy-container.yml
@@ -270,8 +332,8 @@ silent updates, just an honest report that you are behind.
270
332
  If you're the one editing a template *in this repo* and the change touches no rule at
271
333
  all — a typo, a broken hyperlink, a comment — write `Rule-Neutral: yes` as a trailer on
272
334
  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).
335
+ hard fail, but only if **every** commit since their stamp declared it. A `ci-*` template's
336
+ 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
337
 
276
338
  ## Keeping honest
277
339
 
@@ -0,0 +1,370 @@
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
+ # - Per INTEGRATION PROFILE (project.yml `integration-profile:`, #610): `gated` — colab ship
18
+ # dispatches this file at each landing and lands only on its green (keep workflow_dispatch and
19
+ # its `ref` input); `qualify` — make the cron below a clock, every few hours; `promote` —
20
+ # dispatch it on trunk's tip before colab promote. Absent = release-heavy: as copied.
21
+ # Heavy is opt-in per test; an unmarked test is light. The marker:
22
+ # the Pest/PHPUnit group `heavy` (`->group('heavy')`, `#[Group('heavy')]`). The light
23
+ # lane excludes it; this lane runs the whole suite.
24
+ #
25
+ # Deliberately NOT triggered by push or pull_request: a run of this workflow must never count as
26
+ # a merge verdict (tools/lib/verify-runs.js sets schedule and dispatch runs aside).
27
+ # No concurrency block: a heavy run is never cancelled — a release may be waiting on it.
28
+
29
+ name: CI (heavy)
30
+
31
+ on:
32
+ schedule:
33
+ - cron: "23 2 * * *" # EDIT: nightly, UTC. Keep the cron in this one place.
34
+ workflow_dispatch:
35
+ inputs:
36
+ ref:
37
+ description: "Branch, tag or sha to test (empty = trunk's tip)"
38
+ required: false
39
+ default: ""
40
+ workflow_call:
41
+ inputs:
42
+ ref:
43
+ description: "Branch, tag or sha to test"
44
+ type: string
45
+ required: true
46
+
47
+ permissions: {}
48
+
49
+ env:
50
+ # EDIT: this repo's trunk (`trunk:` in .github/project.yml). A schedule always starts on the
51
+ # default branch; the nightly tests THIS branch's tip.
52
+ TRUNK: main
53
+ # EDIT: the same values as ci.yml.
54
+ VITE_APP_NAME: ""
55
+ WAYFINDER_ARGS: "--with-form"
56
+
57
+ jobs:
58
+ # Resolves the one commit this run tests, and decides whether to test it. This job is the one
59
+ # that concludes `success` when the nightly skips: a run whose jobs all skip reads as not-green.
60
+ plan:
61
+ name: What to test
62
+ runs-on: ubuntu-latest # EDIT: needs `gh` (GitHub-hosted images have it).
63
+ timeout-minutes: 5
64
+ permissions:
65
+ actions: read
66
+ contents: read
67
+ outputs:
68
+ sha: ${{ steps.plan.outputs.sha }}
69
+ run: ${{ steps.plan.outputs.run }}
70
+ since: ${{ steps.plan.outputs.since }}
71
+ steps:
72
+ - name: Resolve the commit; skip a nightly on an unmoved trunk
73
+ id: plan
74
+ env:
75
+ GH_TOKEN: ${{ github.token }}
76
+ EVENT: ${{ github.event_name }}
77
+ REF: ${{ inputs.ref }}
78
+ REPO: ${{ github.repository }}
79
+ WORKFLOW_REF: ${{ github.workflow_ref }}
80
+ run: |
81
+ set -uo pipefail
82
+ target="${REF:-$TRUNK}"
83
+ if ! sha="$(gh api "repos/$REPO/commits/$target" --jq .sha)" || [ -z "$sha" ]; then
84
+ echo "::error::cannot resolve '$target' to a commit"
85
+ exit 1
86
+ fi
87
+ echo "sha=$sha" >> "$GITHUB_OUTPUT"
88
+ run=true; since=""
89
+ if [ "$EVENT" = "schedule" ]; then
90
+ # The last green nightly's tested commit, read from its `Full suite @ <sha>` job.
91
+ # Any read error leaves `since` empty, and the suite runs.
92
+ wf="${WORKFLOW_REF%@*}"; wf="${wf##*/}"
93
+ for id in $(gh api "repos/$REPO/actions/workflows/$wf/runs?event=schedule&status=success&per_page=10" \
94
+ --jq '.workflow_runs[].id' 2>/dev/null); do
95
+ since="$(gh api "repos/$REPO/actions/runs/$id/jobs" \
96
+ --jq '[.jobs[] | select(.conclusion == "success" and (.name | startswith("Full suite @ "))) | .name | ltrimstr("Full suite @ ")][0] // ""' 2>/dev/null || true)"
97
+ [ -z "$since" ] || break
98
+ done
99
+ if [ "$since" = "$sha" ]; then
100
+ run=false
101
+ echo "::notice title=heavy-skipped::$TRUNK has not moved since the last green nightly ($sha)"
102
+ fi
103
+ fi
104
+ echo "run=$run" >> "$GITHUB_OUTPUT"
105
+ echo "since=$since" >> "$GITHUB_OUTPUT"
106
+ echo "Heavy lane: ${run} at \`$sha\`${since:+ (last green nightly: \`$since\`)}" >> "$GITHUB_STEP_SUMMARY"
107
+
108
+ heavy:
109
+ # The tested sha is in the job name: the next nightly reads it back to decide whether trunk moved.
110
+ name: Full suite @ ${{ needs.plan.outputs.sha }}
111
+ needs: plan
112
+ if: ${{ needs.plan.outputs.run == 'true' }}
113
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
114
+ timeout-minutes: 120 # EDIT: well above YOUR heavy p99; the default is 360.
115
+ permissions:
116
+ contents: read
117
+ defaults:
118
+ run:
119
+ # EDIT: the same directory as ci.yml's build job.
120
+ working-directory: .
121
+ steps:
122
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
123
+ with:
124
+ ref: ${{ needs.plan.outputs.sha }}
125
+ persist-credentials: false
126
+
127
+ # Toolchain and install: the same steps as ci.yml's build job, so both lanes resolve the
128
+ # same versions. Keep them in step when you edit either.
129
+ # ---------------------------------------------------------------------------
130
+ # Toolchain resolution. Precedence, highest first:
131
+ # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
132
+ # Node: 1. .github/project.yml -> node: 2. .nvmrc, else package.json engines.node
133
+ # ...and if neither declares it, FAIL.
134
+ #
135
+ # There is deliberately NO fallback default. A silent default is exactly how a
136
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
137
+ # CI was green and proved nothing about what actually shipped. Keep these equal
138
+ # to what the deploy target runs, or CI proves nothing.
139
+ # ---------------------------------------------------------------------------
140
+ - name: Resolve toolchain versions
141
+ id: toolchain
142
+ run: |
143
+ set -euo pipefail
144
+
145
+ # "^8.3" / ">=22.1" / "v22" / "8.4.*" -> "8.3" / "22.1" / "22" / "8.4"
146
+ normalise() {
147
+ printf '%s' "$1" \
148
+ | tr -d '"' \
149
+ | sed -E 's/^[^0-9]*//' \
150
+ | sed -E 's/[[:space:]].*$//' \
151
+ | sed -E 's/\.(x|\*)$//' \
152
+ | sed -E 's/[^0-9.].*$//' \
153
+ | sed -E 's/\.$//'
154
+ }
155
+
156
+ # Read a flat `key: value` out of .github/project.yml. That file is a
157
+ # handful of top-level keys by design, so this is sufficient.
158
+ from_project_yml() {
159
+ [ -f .github/project.yml ] || return 0
160
+ sed -nE "s/^[[:space:]]*$1:[[:space:]]*\"?([^\"#[:space:]]+)\"?.*/\1/p" .github/project.yml | head -1
161
+ }
162
+
163
+ # --- PHP ---------------------------------------------------------------
164
+ PHP_VERSION=""; PHP_SOURCE=""
165
+ V="$(from_project_yml php || true)"
166
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
167
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE=".github/project.yml (php:)"
168
+ fi
169
+ if [ -z "$PHP_VERSION" ] && [ -f composer.json ]; then
170
+ V=""
171
+ if command -v php >/dev/null 2>&1; then
172
+ V="$(php -r '$c=json_decode(file_get_contents("composer.json"),true); echo $c["require"]["php"] ?? "";' || true)"
173
+ elif command -v python3 >/dev/null 2>&1; then
174
+ V="$(python3 -c "import json;print((json.load(open('composer.json')).get('require') or {}).get('php') or '')" || true)"
175
+ elif command -v node >/dev/null 2>&1; then
176
+ V="$(node -e "try{const r=require('./composer.json').require||{};process.stdout.write(String(r.php||''))}catch(_){}" || true)"
177
+ fi
178
+ if [ -n "$V" ]; then
179
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE="composer.json (require.php)"
180
+ fi
181
+ fi
182
+ if [ -z "$PHP_VERSION" ]; then
183
+ echo "::error::No PHP version is declared in this repository, and this workflow refuses to guess one."
184
+ {
185
+ echo "Declare it in ONE of:"
186
+ echo " 1. .github/project.yml -> php: \"8.4\" (preferred)"
187
+ echo " 2. composer.json -> \"require\": { \"php\": \"^8.4\" }"
188
+ echo "Use the version the DEPLOY target runs."
189
+ } >&2
190
+ exit 1
191
+ fi
192
+
193
+ # --- Node --------------------------------------------------------------
194
+ NODE_VERSION=""; NODE_SOURCE=""
195
+ V="$(from_project_yml node || true)"
196
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
197
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".github/project.yml (node:)"
198
+ fi
199
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
200
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
201
+ if [ -n "$V" ]; then
202
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".nvmrc"
203
+ fi
204
+ fi
205
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
206
+ V=""
207
+ if command -v node >/dev/null 2>&1; then
208
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
209
+ elif command -v python3 >/dev/null 2>&1; then
210
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
211
+ fi
212
+ if [ -n "$V" ]; then
213
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE="package.json (engines.node)"
214
+ fi
215
+ fi
216
+ if [ -z "$NODE_VERSION" ]; then
217
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
218
+ {
219
+ echo "Declare it in ONE of:"
220
+ echo " 1. .github/project.yml -> node: \"22\" (preferred)"
221
+ echo " 2. .nvmrc -> 22 or package.json -> \"engines\": { \"node\": \">=22\" }"
222
+ echo "Use the version the DEPLOY target runs."
223
+ } >&2
224
+ exit 1
225
+ fi
226
+
227
+ echo "php-version=$PHP_VERSION" >> "$GITHUB_OUTPUT"
228
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
229
+ echo "PHP $PHP_VERSION (from: $PHP_SOURCE) / Node $NODE_VERSION (from: $NODE_SOURCE)"
230
+ {
231
+ echo "PHP **$PHP_VERSION** — resolved from \`$PHP_SOURCE\`"
232
+ echo ""
233
+ echo "Node **$NODE_VERSION** — resolved from \`$NODE_SOURCE\`"
234
+ } >> "$GITHUB_STEP_SUMMARY"
235
+
236
+ - name: Setup PHP
237
+ uses: shivammathur/setup-php@v2
238
+ with:
239
+ php-version: ${{ steps.toolchain.outputs.php-version }}
240
+ # sqlite3 + pdo_sqlite are what the throwaway bootstrap below runs on.
241
+ extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
242
+ coverage: none
243
+
244
+ # Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
245
+ # with composer.lock present. Both halves are load-bearing:
246
+ # - No composer.lock → nothing stable to key on; every run would save a fresh entry.
247
+ # - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
248
+ # jobs; a remote cache on top was measured as a loss, not a saving (#512).
249
+ # Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
250
+ # and its body: `colab ship`'s cure rule matches steps by exact name.
251
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
252
+ # two steps.
253
+ - name: Locate Composer cache
254
+ id: composer-cache
255
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
256
+ run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
257
+
258
+ - name: Restore Composer cache
259
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
260
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
261
+ with:
262
+ path: ${{ steps.composer-cache.outputs.dir }}
263
+ key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
264
+ restore-keys: composer-${{ runner.os }}-
265
+
266
+ - name: Composer install
267
+ env:
268
+ RUN_TESTS: 'true' # the heavy lane always runs the suite
269
+ run: |
270
+ # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
271
+ # boots the app — and the app cannot boot until the .env below exists.
272
+ # Dev dependencies are installed only when the Pest suite will run; a build-
273
+ # only job does not need them (wayfinder lives in require, not require-dev).
274
+ if [ "$RUN_TESTS" = "true" ]; then
275
+ composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
276
+ else
277
+ composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader --no-scripts
278
+ fi
279
+
280
+ - name: Prepare throwaway env for build-time codegen (wayfinder)
281
+ run: |
282
+ # See the header: .env.example ships DB_CONNECTION=mysql, but there is no
283
+ # MySQL on the runner. Rewrite to sqlite against an empty file so artisan
284
+ # boots. This .env is disposable — deploy workflows rsync with --exclude
285
+ # '.env', so it can never reach a server.
286
+ cp .env.example .env
287
+ sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
288
+ touch database/database.sqlite
289
+ php artisan key:generate --force
290
+ php artisan package:discover --ansi
291
+
292
+ echo "=== PHP version on runner ==="
293
+ php -v
294
+
295
+ echo "=== wayfinder:generate (stderr visible) ==="
296
+ # Run it here rather than letting the Vite plugin invoke it: the plugin hides
297
+ # stderr and reports only "Command failed".
298
+ php artisan wayfinder:generate $WAYFINDER_ARGS
299
+
300
+ # npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
301
+ # package-lock.json present (`cache: npm` fails the step without one). The automatic
302
+ # `packageManager` cache is pinned to the same condition so it cannot override it.
303
+ # EDIT: to turn it off everywhere, replace both expressions with '' and false.
304
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
305
+ with:
306
+ node-version: ${{ steps.toolchain.outputs.node-version }}
307
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
308
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
309
+
310
+ - name: Build frontend assets (Vite)
311
+ run: |
312
+ npm ci
313
+ npm run build
314
+
315
+ - name: Run migrations against sqlite
316
+ run: php artisan migrate --force
317
+
318
+ - name: Test (the whole suite)
319
+ run: |
320
+ if [ -f vendor/bin/pest ]; then
321
+ vendor/bin/pest --ci
322
+ elif [ -f vendor/bin/phpunit ]; then
323
+ vendor/bin/phpunit
324
+ else
325
+ echo "::error::neither vendor/bin/pest nor vendor/bin/phpunit exists."
326
+ exit 1
327
+ fi
328
+ # EDIT: integration, browser/e2e (Dusk) or load jobs go here, or as jobs of their own with
329
+ # `needs: plan` and the same `if:` and checkout ref as this one.
330
+
331
+ # A red NIGHTLY is a trunk finding, never a merge block: one open issue per lane. An open issue
332
+ # with the same title suppresses a new one; an issue list that cannot be read files nothing and
333
+ # fails this job, so a silent miss is never mistaken for "already reported".
334
+ report:
335
+ name: Report a red nightly
336
+ needs: [plan, heavy]
337
+ if: ${{ always() && github.event_name == 'schedule' && needs.heavy.result == 'failure' }}
338
+ runs-on: ubuntu-latest # EDIT: needs `gh`.
339
+ timeout-minutes: 5
340
+ permissions:
341
+ issues: write
342
+ steps:
343
+ - name: File one trunk-red issue
344
+ env:
345
+ GH_TOKEN: ${{ github.token }}
346
+ REPO: ${{ github.repository }}
347
+ SHA: ${{ needs.plan.outputs.sha }}
348
+ SINCE: ${{ needs.plan.outputs.since }}
349
+ WORKFLOW: ${{ github.workflow }}
350
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
351
+ run: |
352
+ set -uo pipefail
353
+ title="Nightly heavy lane red: $WORKFLOW"
354
+ if ! open="$(gh issue list -R "$REPO" --state open --search "\"$title\" in:title" --json number,title \
355
+ --jq "[.[] | select(.title == \"$title\")][0].number // \"\"")"; then
356
+ echo "::error::cannot read this repo's issues — nothing filed; the red run is the only report"
357
+ exit 1
358
+ fi
359
+ if [ -n "$open" ]; then
360
+ echo "::notice::#$open already reports this lane red — not filing another."
361
+ exit 0
362
+ fi
363
+ if [ -n "$SINCE" ]; then
364
+ range="[\`${SINCE:0:12}..${SHA:0:12}\`]($GITHUB_SERVER_URL/$REPO/compare/$SINCE...$SHA) — the commits since the last green nightly"
365
+ else
366
+ range="up to \`${SHA:0:12}\` — no green nightly on record to bound it"
367
+ fi
368
+ gh label create trunk-red -R "$REPO" --color B60205 --description "Trunk fails a check" 2>/dev/null || true
369
+ 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")"
370
+ gh issue create -R "$REPO" --title "$title" --label trunk-red --body "$body"