@futurelastic/colab-handbook 1.13.0-rc.4 → 1.13.0-rc.41

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.
Files changed (42) hide show
  1. package/README.md +50 -20
  2. package/README.vi.md +53 -23
  3. package/audit/audit.mjs +128 -16
  4. package/package.json +2 -1
  5. package/templates/README.md +15 -3
  6. package/templates/ci-laravel.yml +184 -30
  7. package/templates/ci-node.yml +327 -26
  8. package/templates/ci-python.yml +140 -23
  9. package/templates/deploy-xserver.yml +12 -0
  10. package/templates/release-auto.yml +68 -4
  11. package/tools/colab +990 -107
  12. package/tools/lib/batch-history.js +104 -0
  13. package/tools/lib/batch-stats.js +277 -0
  14. package/tools/lib/ci-profile.js +195 -0
  15. package/tools/lib/ci-verdict.js +13 -5
  16. package/tools/lib/ci-wait.js +6 -1
  17. package/tools/lib/codec/claim.js +6 -3
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/labels.js +7 -0
  21. package/tools/lib/codec/release.js +6 -3
  22. package/tools/lib/codec/samples.json +61 -0
  23. package/tools/lib/config-set.js +319 -0
  24. package/tools/lib/disposition.js +9 -6
  25. package/tools/lib/docs-only.js +1 -1
  26. package/tools/lib/engines.js +52 -0
  27. package/tools/lib/git.js +82 -18
  28. package/tools/lib/install-check.js +77 -5
  29. package/tools/lib/journal.js +3 -0
  30. package/tools/lib/migration-grant.js +19 -2
  31. package/tools/lib/notify-endpoint.js +114 -59
  32. package/tools/lib/notify.js +68 -22
  33. package/tools/lib/release-cut.js +39 -3
  34. package/tools/lib/release-finalize.js +113 -17
  35. package/tools/lib/release-policy.js +11 -3
  36. package/tools/lib/ship-batch.js +109 -2
  37. package/tools/lib/ship-human-door.js +76 -0
  38. package/tools/lib/shipguard.js +12 -1
  39. package/tools/lib/stamp.js +6 -2
  40. package/tools/lib/template-trunk.js +80 -0
  41. package/tools/lib/thresholds.js +110 -0
  42. package/tools/lib/verify-runs.js +117 -4
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
20
20
  | `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. |
21
21
  | `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
22
  | `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
- | `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, 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. |
23
+ | `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. |
24
24
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
25
25
  | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
26
26
  | `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
@@ -67,8 +67,11 @@ notice back and print the run they relied on. Three things to keep in a copy:
67
67
 
68
68
  - **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
69
69
  commit objects.
70
- - **The trunk refs in its `if:` mirror `concurrency`'s list.** On a repo whose trunk has another
71
- name, edit both. Until you do, the guard simply never fires on trunk — nothing breaks.
70
+ - **The trunk refs in its `if:` mirror `concurrency`'s list.** The list appears three times in a
71
+ copy: the `group:`, `cancel-in-progress:`, and this `if:` (#512 gave the trunk its own
72
+ per-run group, so a pending trunk run is never replaced). On a repo whose trunk has another
73
+ name, edit all three. Until you do, the guard simply never fires on trunk — nothing breaks;
74
+ but a trunk left out of `group:` and `cancel-in-progress:` has its runs cancelled.
72
75
  - **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
73
76
  the guard says. Give them their own `if:` that does not read `needs.dedupe`.
74
77
 
@@ -302,3 +305,12 @@ runner is infrastructure, not a throwaway VM.
302
305
  service context (`job.services.mysql.ports['3306']`), threading it through your
303
306
  env. A fixed `3306:3306` works exactly until the first job lands on a runner
304
307
  that already listens there.
308
+
309
+ ### One run per commit — why the CI templates have no `pull_request` trigger (#512)
310
+
311
+ The three `ci-*` templates trigger on `push: ['**']` and `workflow_dispatch`. A same-repo PR
312
+ commit gets the push run and nothing else; a `pull_request` trigger beside it ran the suite twice
313
+ and let the later run, which tests the merge ref, decide the verdict. Two edits belong to a copy:
314
+ a repo that goes back to trunk-only push restores `pull_request: branches: [<trunk>]`, and a repo
315
+ that accepts fork PRs keeps one (a fork's push never runs a workflow here). Detail:
316
+ `CONVENTIONS.md` §4, *Branch CI*.
@@ -67,31 +67,50 @@ on:
67
67
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
68
68
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
69
69
  branches: ['**']
70
- pull_request:
71
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
72
- # trunk, main the release; Tier B: main only).
73
- branches: [main, dev]
70
+ # No `pull_request:` here (#512). A branch with an open PR in this repository already
71
+ # has a push run at the same head, and a `pull_request` run beside it doubled the CI
72
+ # per commit while testing a merge ref instead of the sha that lands. Readers keep only
73
+ # the newest run per workflow at a sha, so that second run also decided the verdict.
74
+ # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
75
+ # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
76
+ # only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
77
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
78
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
79
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
80
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
81
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
82
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
83
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
84
+ # pull_request:
85
+ # branches: ['**']
74
86
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
75
87
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
76
88
  workflow_dispatch:
77
89
 
78
90
  # One live run per branch: a new push cancels the superseded run on the same ref.
79
91
  # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
80
- # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
81
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
82
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
83
- # may carry any name; one left off this list gets its trunk runs cancelled.
92
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
93
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
94
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
95
+ # drop the second one's run before it ever started (#512).
96
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
97
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
98
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
99
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
84
100
  concurrency:
85
- group: ci-${{ github.ref }}
101
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
86
102
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
87
103
 
88
104
  env:
89
- # Light CI on the dev trunk (does it build at all, ~2 min); heavy CI on main, where
90
- # the Pest suite gates a release. On Tier C main IS production — promotion is the
91
- # deploy — so this suite is the last gate before users, not a release formality.
92
- # EDIT: set to a literal 'true' if this repo is Tier B (main is trunk) and you
93
- # always want the suite.
94
- RUN_TESTS: ${{ github.ref == 'refs/heads/main' || github.base_ref == 'main' }}
105
+ # Whether the Pest suite runs. 'auto' is decided by the "Decide the test tier" step in
106
+ # `build` (#512). Light CI on a dev trunk and its branches (does it build at all,
107
+ # ~2 min); heavy CI on main, where the Pest suite gates a release. On Tier C main IS
108
+ # production — promotion is the deploy — so this suite is the last gate before users,
109
+ # not a release formality. When main is the trunk (Tier B) every branch push runs the
110
+ # suite too: this workflow has no `pull_request` run any more, and that run used to be
111
+ # the only place a Tier B branch got its tests.
112
+ # EDIT: set to a literal 'true' to always run the suite, 'false' to never run it.
113
+ RUN_TESTS: auto
95
114
  # EDIT: bump deliberately, not automatically.
96
115
  GITLEAKS_VERSION: "8.30.1"
97
116
  # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
@@ -133,12 +152,17 @@ jobs:
133
152
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
134
153
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
135
154
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
136
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
155
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
156
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
157
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
158
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
159
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
137
160
  dedupe:
138
161
  name: Already tested at this sha or tree?
139
162
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
140
163
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
141
164
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
165
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
142
166
  permissions:
143
167
  actions: read
144
168
  contents: read
@@ -155,9 +179,34 @@ jobs:
155
179
  SHA: ${{ github.sha }}
156
180
  CREATED: ${{ github.event.created }}
157
181
  REF_NAME: ${{ github.ref_name }}
182
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
158
183
  run: |
159
184
  tested=false
160
185
  cited=
186
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
187
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
188
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
189
+ reusable() {
190
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
191
+ --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name] | join(", ") end' 2>/dev/null)"; then
192
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
193
+ return 1
194
+ elif [ -n "$SK" ]; then
195
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
196
+ return 1
197
+ fi
198
+ }
199
+ # The cited run, as "<id> <head sha> <url> <branch>": a green push run of this workflow on
200
+ # another ref of this repo. #552: one at THIS sha first (a `ship-batch/*` run trunk
201
+ # fast-forwarded to), an exact query; else one whose commit has THIS tree (#493).
202
+ same_sha() {
203
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
204
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null | grep .
205
+ }
206
+ same_tree() {
207
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
208
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null
209
+ }
161
210
  if ! command -v gh >/dev/null 2>&1; then
162
211
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
163
212
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -172,16 +221,15 @@ jobs:
172
221
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
173
222
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
174
223
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
175
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
176
- --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
224
+ elif ! CAND="$(same_sha || same_tree)"; then
177
225
  echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
178
226
  elif [ -z "$CAND" ]; then
179
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
227
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
180
228
  else
181
- read -r CSHA URL BR <<< "$CAND"
229
+ read -r CID CSHA URL BR <<< "$CAND"
182
230
  if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
183
231
  echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
184
- else
232
+ elif reusable "$CID"; then
185
233
  tested=true
186
234
  cited="$URL"
187
235
  echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
@@ -205,8 +253,9 @@ jobs:
205
253
  gitleaks:
206
254
  name: Secret scan (gitleaks)
207
255
  needs: dedupe
208
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
256
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
209
257
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
258
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
210
259
  steps:
211
260
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
212
261
  with:
@@ -246,8 +295,11 @@ jobs:
246
295
  build:
247
296
  name: Build (Laravel + Vite)
248
297
  needs: dedupe
249
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
298
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
250
299
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
300
+ timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
301
+ # EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
302
+ # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
251
303
  # Re-exported so the migrations job below resolves PHP exactly once, here.
252
304
  outputs:
253
305
  php-version: ${{ steps.toolchain.outputs.php-version }}
@@ -256,6 +308,37 @@ jobs:
256
308
  with:
257
309
  persist-credentials: false
258
310
 
311
+ # Decide the test tier (#512). Not an `env:` expression, because the answer depends on
312
+ # the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
313
+ # RUN_TESTS 'true' / 'false' → used as written.
314
+ # 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
315
+ # 'auto', push or dispatch → on for main, and for every branch when trunk is main
316
+ # (Tier B); off for a dev trunk and its branches (Tier C).
317
+ - name: Decide the test tier
318
+ id: tier
319
+ env:
320
+ DECLARED: ${{ env.RUN_TESTS }}
321
+ EVENT: ${{ github.event_name }}
322
+ REF: ${{ github.ref }}
323
+ BASE_REF: ${{ github.base_ref }}
324
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
325
+ run: |
326
+ case "$DECLARED" in
327
+ true|false) run="$DECLARED" ;;
328
+ *)
329
+ trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
330
+ [ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
331
+ if [ "$EVENT" = "pull_request" ]; then
332
+ [ "$BASE_REF" = "main" ] && run=true || run=false
333
+ elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
334
+ run=true
335
+ else
336
+ run=false
337
+ fi ;;
338
+ esac
339
+ echo "run_tests=$run" >> "$GITHUB_OUTPUT"
340
+ echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
341
+
259
342
  # ---------------------------------------------------------------------------
260
343
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
261
344
  # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
@@ -263,23 +346,90 @@ jobs:
263
346
  # green; only a ship dry run noticed. So the value fails HERE, where the person
264
347
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
265
348
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
266
- # cap is 3: project.schema.md, `ship-batch`.
349
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
350
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
351
+ # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
267
352
  # ---------------------------------------------------------------------------
268
353
  - name: Descriptor check (.github/project.yml)
269
354
  working-directory: ${{ github.workspace }}
270
355
  run: |
271
356
  [ -f .github/project.yml ] || exit 0
272
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
273
- [ -n "$line" ] || exit 0
274
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
357
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
358
+ field() {
359
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
360
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
275
361
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
276
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
362
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
363
+ }
364
+ v="$(field ship-batch)"
277
365
  case "$v" in
278
366
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
279
367
  *)
280
368
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
281
369
  exit 1 ;;
282
370
  esac
371
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
372
+ w="$(field ship-batch-wait)"
373
+ case "$w" in
374
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
375
+ *)
376
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
377
+ echo "ship-batch-wait: $w — ok"
378
+ else
379
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
380
+ exit 1
381
+ fi ;;
382
+ esac
383
+ # ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
384
+ # Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
385
+ f="$(field ci-wait-factor)"
386
+ case "$f" in
387
+ ''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
388
+ *)
389
+ if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
390
+ echo "ci-wait-factor: $f — ok"
391
+ else
392
+ echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
393
+ exit 1
394
+ fi ;;
395
+ esac
396
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
397
+ # floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
398
+ # which a test holds this list to.
399
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
400
+ bad=0
401
+ while IFS= read -r t; do
402
+ case "$t" in =*)
403
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
404
+ bad=1; continue ;;
405
+ esac
406
+ k="${t%%:*}"
407
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
408
+ max=999999999
409
+ case "$k" in
410
+ hot-file-count|claude-md-line-multiple) min=2 ;;
411
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
412
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
413
+ batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
414
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
415
+ bad=1; continue ;;
416
+ esac
417
+ case "$n" in ''|'~'|null) continue ;; esac
418
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
419
+ echo "thresholds.$k: $n — ok"
420
+ else
421
+ echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number from $min to $max. Every reader ignores it (a batch-* key is then not judged; any other uses its default). See project.schema.md, thresholds."
422
+ bad=1
423
+ fi
424
+ done < <(awk '
425
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
426
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
427
+ if (v != "" && v != "~" && v != "null") print "=" v
428
+ next }
429
+ b && /^[[:space:]]*(#|$)/ { next }
430
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
431
+ { b = 0 }' .github/project.yml)
432
+ [ "$bad" = 0 ] || exit 1
283
433
 
284
434
  # ---------------------------------------------------------------------------
285
435
  # Toolchain resolution. Precedence, highest first:
@@ -397,6 +547,8 @@ jobs:
397
547
  coverage: none
398
548
 
399
549
  - name: Composer install
550
+ env:
551
+ RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
400
552
  run: |
401
553
  # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
402
554
  # boots the app — and the app cannot boot until the .env below exists.
@@ -438,14 +590,14 @@ jobs:
438
590
  npm run build
439
591
 
440
592
  - name: Run migrations against sqlite
441
- if: env.RUN_TESTS == 'true'
593
+ if: steps.tier.outputs.run_tests == 'true'
442
594
  run: |
443
595
  # Migrations must apply cleanly from zero. This is the cheapest way to catch
444
596
  # a migration that only works against an already-populated database.
445
597
  php artisan migrate --force
446
598
 
447
599
  - name: Test (Pest)
448
- if: env.RUN_TESTS == 'true'
600
+ if: steps.tier.outputs.run_tests == 'true'
449
601
  run: |
450
602
  if [ -f vendor/bin/pest ]; then
451
603
  vendor/bin/pest --ci
@@ -488,6 +640,8 @@ jobs:
488
640
  # form would skip this job on exactly the runs it exists for (#418).
489
641
  if: ${{ !cancelled() && needs.build.result == 'success' }}
490
642
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
643
+ timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
644
+ # EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
491
645
  strategy:
492
646
  fail-fast: false
493
647
  matrix: