@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0

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.
@@ -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"