@futurelastic/colab-handbook 1.13.0-rc.8 → 1.13.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.
@@ -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. |
@@ -263,23 +263,90 @@ jobs:
263
263
  # green; only a ship dry run noticed. So the value fails HERE, where the person
264
264
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
265
265
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
266
- # cap is 3: project.schema.md, `ship-batch`.
266
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
267
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
268
+ # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
267
269
  # ---------------------------------------------------------------------------
268
270
  - name: Descriptor check (.github/project.yml)
269
271
  working-directory: ${{ github.workspace }}
270
272
  run: |
271
273
  [ -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:]]*//' \
274
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
275
+ field() {
276
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
277
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
275
278
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
276
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
279
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
280
+ }
281
+ v="$(field ship-batch)"
277
282
  case "$v" in
278
283
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
279
284
  *)
280
285
  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
286
  exit 1 ;;
282
287
  esac
288
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
289
+ w="$(field ship-batch-wait)"
290
+ case "$w" in
291
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
292
+ *)
293
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
294
+ echo "ship-batch-wait: $w — ok"
295
+ else
296
+ 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."
297
+ exit 1
298
+ fi ;;
299
+ esac
300
+ # ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
301
+ # Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
302
+ f="$(field ci-wait-factor)"
303
+ case "$f" in
304
+ ''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
305
+ *)
306
+ if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
307
+ echo "ci-wait-factor: $f — ok"
308
+ else
309
+ 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."
310
+ exit 1
311
+ fi ;;
312
+ esac
313
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
314
+ # floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
315
+ # which a test holds this list to.
316
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
317
+ bad=0
318
+ while IFS= read -r t; do
319
+ case "$t" in =*)
320
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
321
+ bad=1; continue ;;
322
+ esac
323
+ k="${t%%:*}"
324
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
325
+ max=999999999
326
+ case "$k" in
327
+ hot-file-count|claude-md-line-multiple) min=2 ;;
328
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
329
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
330
+ batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
331
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
332
+ bad=1; continue ;;
333
+ esac
334
+ case "$n" in ''|'~'|null) continue ;; esac
335
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
336
+ echo "thresholds.$k: $n — ok"
337
+ else
338
+ 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."
339
+ bad=1
340
+ fi
341
+ done < <(awk '
342
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
343
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
344
+ if (v != "" && v != "~" && v != "null") print "=" v
345
+ next }
346
+ b && /^[[:space:]]*(#|$)/ { next }
347
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
348
+ { b = 0 }' .github/project.yml)
349
+ [ "$bad" = 0 ] || exit 1
283
350
 
284
351
  # ---------------------------------------------------------------------------
285
352
  # Toolchain resolution. Precedence, highest first:
@@ -13,7 +13,8 @@
13
13
  # `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
14
14
  #
15
15
  # What it does:
16
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
16
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
17
+ # ship-batch-wait, #555; ci-wait-factor, #564).
17
18
  # 1. Resolve the Node version from declared sources — never a hardcoded default.
18
19
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
19
20
  # 3. Install dependencies with the package manager the lockfile implies.
@@ -257,23 +258,90 @@ jobs:
257
258
  # green; only a ship dry run noticed. So the value fails HERE, where the person
258
259
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
259
260
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
260
- # cap is 3: project.schema.md, `ship-batch`.
261
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
262
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
263
+ # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
261
264
  # ---------------------------------------------------------------------------
262
265
  - name: Descriptor check (.github/project.yml)
263
266
  working-directory: ${{ github.workspace }}
264
267
  run: |
265
268
  [ -f .github/project.yml ] || exit 0
266
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
267
- [ -n "$line" ] || exit 0
268
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
269
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
270
+ field() {
271
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
272
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
269
273
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
270
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
274
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
275
+ }
276
+ v="$(field ship-batch)"
271
277
  case "$v" in
272
278
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
273
279
  *)
274
280
  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."
275
281
  exit 1 ;;
276
282
  esac
283
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
284
+ w="$(field ship-batch-wait)"
285
+ case "$w" in
286
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
287
+ *)
288
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
289
+ echo "ship-batch-wait: $w — ok"
290
+ else
291
+ 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."
292
+ exit 1
293
+ fi ;;
294
+ esac
295
+ # ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
296
+ # Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
297
+ f="$(field ci-wait-factor)"
298
+ case "$f" in
299
+ ''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
300
+ *)
301
+ if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
302
+ echo "ci-wait-factor: $f — ok"
303
+ else
304
+ 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."
305
+ exit 1
306
+ fi ;;
307
+ esac
308
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
309
+ # floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
310
+ # which a test holds this list to.
311
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
312
+ bad=0
313
+ while IFS= read -r t; do
314
+ case "$t" in =*)
315
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
316
+ bad=1; continue ;;
317
+ esac
318
+ k="${t%%:*}"
319
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
320
+ max=999999999
321
+ case "$k" in
322
+ hot-file-count|claude-md-line-multiple) min=2 ;;
323
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
324
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
325
+ batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
326
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
327
+ bad=1; continue ;;
328
+ esac
329
+ case "$n" in ''|'~'|null) continue ;; esac
330
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
331
+ echo "thresholds.$k: $n — ok"
332
+ else
333
+ 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."
334
+ bad=1
335
+ fi
336
+ done < <(awk '
337
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
338
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
339
+ if (v != "" && v != "~" && v != "null") print "=" v
340
+ next }
341
+ b && /^[[:space:]]*(#|$)/ { next }
342
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
343
+ { b = 0 }' .github/project.yml)
344
+ [ "$bad" = 0 ] || exit 1
277
345
 
278
346
  # ---------------------------------------------------------------------------
279
347
  # Toolchain resolution. Precedence, highest first:
@@ -27,7 +27,8 @@
27
27
  # NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
28
28
  #
29
29
  # What it does:
30
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
30
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
31
+ # ship-batch-wait, #555; ci-wait-factor, #564).
31
32
  # 1. Resolve the Python version from declared sources — never a hardcoded default.
32
33
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
33
34
  # 3. Install dependencies from whichever manifest the repo actually has.
@@ -248,23 +249,90 @@ jobs:
248
249
  # green; only a ship dry run noticed. So the value fails HERE, where the person
249
250
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
250
251
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
251
- # cap is 3: project.schema.md, `ship-batch`.
252
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
253
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
254
+ # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
252
255
  # ---------------------------------------------------------------------------
253
256
  - name: Descriptor check (.github/project.yml)
254
257
  working-directory: ${{ github.workspace }}
255
258
  run: |
256
259
  [ -f .github/project.yml ] || exit 0
257
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
258
- [ -n "$line" ] || exit 0
259
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
260
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
261
+ field() {
262
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
263
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
260
264
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
261
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
265
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
266
+ }
267
+ v="$(field ship-batch)"
262
268
  case "$v" in
263
269
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
264
270
  *)
265
271
  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."
266
272
  exit 1 ;;
267
273
  esac
274
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
275
+ w="$(field ship-batch-wait)"
276
+ case "$w" in
277
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
278
+ *)
279
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
280
+ echo "ship-batch-wait: $w — ok"
281
+ else
282
+ 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."
283
+ exit 1
284
+ fi ;;
285
+ esac
286
+ # ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
287
+ # Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
288
+ f="$(field ci-wait-factor)"
289
+ case "$f" in
290
+ ''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
291
+ *)
292
+ if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
293
+ echo "ci-wait-factor: $f — ok"
294
+ else
295
+ 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."
296
+ exit 1
297
+ fi ;;
298
+ esac
299
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
300
+ # floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
301
+ # which a test holds this list to.
302
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
303
+ bad=0
304
+ while IFS= read -r t; do
305
+ case "$t" in =*)
306
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
307
+ bad=1; continue ;;
308
+ esac
309
+ k="${t%%:*}"
310
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
311
+ max=999999999
312
+ case "$k" in
313
+ hot-file-count|claude-md-line-multiple) min=2 ;;
314
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
315
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
316
+ batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
317
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
318
+ bad=1; continue ;;
319
+ esac
320
+ case "$n" in ''|'~'|null) continue ;; esac
321
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
322
+ echo "thresholds.$k: $n — ok"
323
+ else
324
+ 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."
325
+ bad=1
326
+ fi
327
+ done < <(awk '
328
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
329
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
330
+ if (v != "" && v != "~" && v != "null") print "=" v
331
+ next }
332
+ b && /^[[:space:]]*(#|$)/ { next }
333
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
334
+ { b = 0 }' .github/project.yml)
335
+ [ "$bad" = 0 ] || exit 1
268
336
 
269
337
  # ---------------------------------------------------------------------------
270
338
  # Toolchain resolution. Precedence, highest first:
@@ -20,6 +20,9 @@
20
20
  # hand-off where
21
21
  # the final is a
22
22
  # human's)
23
+ # an hourly schedule (#547) — the cut colab release cut --auto, only when main's head
24
+ # only, never promote or finalize has no tag AND the fetched CLI moved in the last
25
+ # RETRY_WINDOW_MINUTES (or a run here was displaced)
23
26
  # workflow_dispatch all three, in that order
24
27
  # any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
25
28
  # project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
@@ -115,6 +118,23 @@
115
118
  # pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
116
119
  # applies to your deploy workflows exactly as before.
117
120
  #
121
+ # A REFUSAL THE HANDBOOK FIXES IS RETRIED WITHIN THE HOUR (#547). A cut can be refused by a defect in
122
+ # the colab CLI rather than in your repo — a false positive in one of its checks. The fix reaches you
123
+ # when HANDBOOK_REF's channel moves, and nothing in your repo changes, so neither trigger above fires:
124
+ # the candidate would wait for your next merge or the next daily run (measured: ~2.5 h until a person
125
+ # dispatched it by hand, ~22 h otherwise). So an hourly run re-tries the CUT, and only the cut, when:
126
+ # - main's head carries no release tag yet (a head that has one has nothing to retry), and
127
+ # - the CLI this run fetched reached HANDBOOK_REF within RETRY_WINDOW_MINUTES — read from the date of
128
+ # the release tag at that commit (when the channel moved onto it), else the commit's own date; or
129
+ # - the newest other run of this workflow at main's head was cancelled. An hourly run shares the
130
+ # `release-auto` concurrency group, and GitHub cancels a PENDING run in a group when a newer one
131
+ # queues — so an hourly run can displace the very run a merge started. It then does that run's cut.
132
+ # Every other hourly run checks those and stops: no cut, no promotion, no finalize, so a held head is
133
+ # not tagged sooner than the daily run would tag it, and a standing refusal is not re-announced every
134
+ # hour. Nothing is stored between runs; the facts are re-read each time. EDIT: the cron string inside
135
+ # RETRY_RUN (release job env) must stay byte-identical to the hourly `cron:` line, or no run is
136
+ # recognised as a retry run — and the hourly run would then promote and finalize every hour.
137
+ #
118
138
  # A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
119
139
  # failed) is the ordinary output of most runs; it is printed to the run summary as a
120
140
  # warning and the job stays green, so a refusal never paints main red for `colab ship`.
@@ -170,6 +190,9 @@ on:
170
190
  # EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
171
191
  # hour is when scheduled runs queue longest.
172
192
  - cron: "17 3 * * *"
193
+ # #547: the hourly RETRY run — cut only, only when the CLI moved or a run was displaced (header,
194
+ # "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (release job env).
195
+ - cron: "47 * * * *"
173
196
  workflow_dispatch:
174
197
  # #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
175
198
  # any ref other than main is dry whether or not this is set; on main it is opt-in.
@@ -263,6 +286,12 @@ jobs:
263
286
  # Never on workflow_run or schedule. Every write below is off when it is.
264
287
  # EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
265
288
  DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
289
+ # #547: 'true' on the hourly retry run. EDIT: the cron string here is byte-identical to the hourly
290
+ # `cron:` under `on.schedule`.
291
+ RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
292
+ # EDIT: how recent a move of the CLI still earns a retry. Two hourly runs plus slack, so one
293
+ # scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
294
+ RETRY_WINDOW_MINUTES: "130"
266
295
  steps:
267
296
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
268
297
  with:
@@ -334,13 +363,46 @@ jobs:
334
363
  git config user.name "github-actions[bot]"
335
364
  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
336
365
 
366
+ # #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
367
+ # THE HANDBOOK FIXES"). Ends green either way; retry=true lets the cut step below run.
368
+ - name: Retry a refused cut once the CLI moved (#547)
369
+ id: retry
370
+ if: env.RETRY_RUN == 'true'
371
+ run: |
372
+ set -uo pipefail
373
+ eval "$RETRY_TRANSIENT"
374
+ decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
375
+ HEAD="$(git rev-parse HEAD)"
376
+ TAGGED="$(git tag --points-at "$HEAD" --list 'v*' | head -n 1)"
377
+ [ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
378
+ # When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
379
+ # tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
380
+ CLI_DIR="${COLAB%/tools/colab}"
381
+ CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
382
+ MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
383
+ [ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
384
+ AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
385
+ if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
386
+ decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
387
+ fi
388
+ # A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
389
+ # An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
390
+ RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
391
+ || decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
392
+ LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
393
+ case "$LAST" in
394
+ cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
395
+ unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
396
+ esac
397
+ decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
398
+
337
399
  # #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
338
400
  # into main, then dispatch CI there — its green run fires this workflow again to cut the
339
401
  # candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
340
402
  # rejected) is a warning; the job stays green.
341
403
  - name: Promote unattended (colab promote --auto)
342
404
  id: promote
343
- if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
405
+ if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
344
406
  env:
345
407
  # EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
346
408
  CI_WORKFLOW: "CI"
@@ -384,7 +446,7 @@ jobs:
384
446
  # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
385
447
  - name: Cut a candidate (colab release cut --auto)
386
448
  id: cut
387
- if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
449
+ if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
388
450
  run: |
389
451
  set -uo pipefail
390
452
  eval "$RETRY_TRANSIENT"
@@ -436,13 +498,15 @@ jobs:
436
498
  echo
437
499
  } >> "$GITHUB_STEP_SUMMARY"
438
500
  else
439
- echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
501
+ # #545: condition AND detail — the name alone hid which file and statement refused, so a
502
+ # false refusal could not be told from a real one without re-running the cut by hand.
503
+ echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | "\(.condition) — \(.detail)"] | join("; ")' "$OUT")"
440
504
  fi
441
505
  fi
442
506
 
443
507
  - name: Finalize the newest clean candidate (colab release finalize --auto)
444
508
  id: finalize
445
- if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
509
+ if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
446
510
  run: |
447
511
  set -uo pipefail
448
512
  eval "$RETRY_TRANSIENT"