@futurelastic/colab-handbook 1.14.0-rc.14 → 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 +24 -10
- package/package.json +1 -1
- package/templates/README.md +49 -2
- package/templates/ci-laravel-heavy.yml +366 -0
- package/templates/ci-laravel.yml +27 -218
- package/templates/ci-node-heavy.yml +289 -0
- package/templates/ci-node.yml +23 -202
- package/templates/ci-python-heavy.yml +298 -0
- package/templates/ci-python.yml +26 -207
- package/templates/release-auto.yml +70 -1
- package/templates/release-tag.yml +20 -3
- package/tools/colab +12 -3
- package/tools/lib/stamp.js +16 -1
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
456
|
-
else if (
|
|
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
|
|
477
|
-
|
|
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
|
-
|
|
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
package/templates/README.md
CHANGED
|
@@ -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
|
|
274
|
-
is
|
|
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"
|