@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.
- package/README.md +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +116 -15
- package/package.json +2 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +72 -5
- package/templates/ci-node.yml +74 -6
- package/templates/ci-python.yml +74 -6
- package/templates/release-auto.yml +68 -4
- package/tools/colab +791 -93
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +70 -15
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +110 -15
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
package/templates/README.md
CHANGED
|
@@ -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. |
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -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
|
-
|
|
273
|
-
|
|
274
|
-
|
|
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:
|
package/templates/ci-node.yml
CHANGED
|
@@ -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
|
-
|
|
267
|
-
|
|
268
|
-
|
|
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:
|
package/templates/ci-python.yml
CHANGED
|
@@ -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
|
-
|
|
258
|
-
|
|
259
|
-
|
|
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
|
-
|
|
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"
|