@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.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 CHANGED
@@ -187,6 +187,7 @@ you want.
187
187
  | `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
188
188
  | `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
189
189
  | `--all` | `--tools --hooks --fleet`. |
190
+ | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json` with a local observer's events URL, only when the key is absent — an existing value is never overwritten. Without the flag, `--tools` seeds it from `~/.colab/notify-endpoint` when a local observer declared its URL there, and otherwise prints that `notifyUrl` is unset and which events that drops. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
190
191
  | `--dry` | Print what would happen, change nothing. Combines with all of the above. |
191
192
  | `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
192
193
 
@@ -216,14 +217,15 @@ window between a CLI commit and the next tag, and the advertised remedy copies
216
217
  *from* that same working tree — so on a machine developing the handbook it
217
218
  advised services to adopt untagged code.) It never rewrites the copy, not even
218
219
  with `--apply`: that is the toolchain your running services are executing.
219
- `colab --version` says which of the two you are talking to. The frozen copy carries
220
+ `colab --version` says which of the two you are talking to (or `npm package` for an
221
+ `npx`/`npm i` install), and prints that install's version. The frozen copy carries
220
222
  `tools/` only, so `colab template` refuses there — run it from the working tree.
221
223
 
222
224
  **3. Verify, and register your repos.**
223
225
 
224
226
  ```sh
225
227
  colab --help # not found? fix your PATH — step 2 prints the exact line
226
- colab --version # which colab is this: the working tree, or the frozen copy?
228
+ colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
227
229
  colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
228
230
  node audit/audit.mjs # a conformance report across the whole fleet
229
231
  colab update # stamped copies that fell behind — the frozen CLI included
@@ -245,8 +247,9 @@ A frozen copy never breaks — it gets **old**, and an old complete copy answers
245
247
  normally for every command it knows until something asks for one added after it
246
248
  was frozen. `--check` is the report nothing else gives: whether the frozen copy is
247
249
  behind the latest release, **which commands it does not dispatch**, whether the
248
- state file exists, whether anything is registered, and whether both pre-commit
249
- hooklets can actually run (gitleaks, and the identity vocabulary). ✗ means
250
+ state file exists, whether anything is registered, whether both pre-commit
251
+ hooklets can actually run (gitleaks, and the identity vocabulary), and whether
252
+ `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
250
253
  something installed here is stale or unusable; ⚠ means something was never set
251
254
  up, which may be deliberate. It never refreshes anything — re-freezing stays your
252
255
  call: `./install.sh --tools`.
package/README.vi.md CHANGED
@@ -185,6 +185,7 @@ nếu bạn thật sự chỉ cần bấy nhiêu.
185
185
  | `--hooks` | Trỏ git của clone này vào `.githooks/`, ở đó `pre-commit` chạy lần lượt mọi check trong `pre-commit.d/` — quét secret bằng gitleaks, và quét danh tính (identity) vốn cần một danh sách từ khoá do bạn cấp bằng đường dẫn và giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). `core.hooksPath` nằm trong `.git/config` nên là cấu hình per-clone, per-máy, không đi theo repo. |
186
186
  | `--fleet` | Tạo `~/.colab/repos.txt` từ `audit/repos.txt`, chỉ khi file chưa tồn tại. Danh sách đó cố tình nằm ngoài repo: nó ghi tên các repo private của bạn, còn repo này thì public. |
187
187
  | `--all` | `--tools --hooks --fleet`. |
188
+ | `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json` bằng URL nhận event của một observer chạy trên máy, chỉ khi khoá đó chưa có — giá trị đang có không bao giờ bị ghi đè. Không truyền flag thì `--tools` lấy URL từ `~/.colab/notify-endpoint` nếu observer trên máy đã khai ở đó; không có thì in rõ `notifyUrl` đang trống và sẽ mất những event nào. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
188
189
  | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với mọi flag trên. |
189
190
 
190
191
  **Service luôn-bật phải gọi `~/.colab/bin/colab`.** Bản CLI symlink chạy theo
@@ -208,13 +209,14 @@ mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag k
208
209
  phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
209
210
  triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
210
211
  ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
211
- của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào.
212
+ của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
213
+ cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
212
214
 
213
215
  **3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
214
216
 
215
217
  ```sh
216
218
  colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
217
- colab --version # colab nào đây: bản working tree hay bản đóng băng?
219
+ colab --version # colab nào đây — working tree, bản đóng băng hay npm package — và phiên bản của nó
218
220
  $EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
219
221
  node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
220
222
  colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
package/audit/audit.mjs CHANGED
@@ -1270,12 +1270,14 @@ function auditRepo(target, ctx) {
1270
1270
  // ---- ship-batch (#373) ------------------------------------------------------
1271
1271
  // Batch landing's opt-in: an integer 1–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
1272
1272
  // `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
1273
- // to serial, which is safe but silent, so it fails here. Two further shapes are inert rather than
1273
+ // to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
1274
+ // the CI templates' descriptor check too (#416, held to this same parser by
1275
+ // tools/lib/ci-template-descriptor-check.test.js). Two further shapes are inert rather than
1274
1276
  // wrong, so they warn: no workflow fires on a `ship-batch/**` push (the combined run can never
1275
1277
  // arrive), and no `autonomy: auto-trunk` (a batch lands in one unattended push, which needs it).
1276
1278
  if ("ship-batch" in (cfg || {}) && cfg["ship-batch"] !== null) {
1277
1279
  const sbCfg = shipBatch.parseShipBatch(cfg);
1278
- if (!sbCfg.valid) fail(sbCfg.reason);
1280
+ if (!sbCfg.valid) fail(`${sbCfg.reason} — the cap is deliberate, see project.schema.md, ship-batch`);
1279
1281
  else if (sbCfg.n > 1) {
1280
1282
  const firing = workflowsFiringOnBranchPush({ readFile: (p) => src.readFile(p), workflows, branch: shipBatch.PROBE_REF });
1281
1283
  if (!firing.length) warn(`ship-batch: ${sbCfg.n} but no workflow in .github/workflows fires on a push to ship-batch/** — colab ship --batch will always fall back to serial; add 'ship-batch/**' to a CI workflow's push: branches:`);
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.8"
30
+ "version": "1.12.0"
31
31
  }
@@ -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 pinned handbook ref (`HANDBOOK_REF`) — 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; 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, 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 for a service's `init`. `*.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
  | `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
@@ -31,6 +31,25 @@ Starting points you **copy into your own repo**. That is the entire model.
31
31
  | `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
32
32
  | `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
33
33
 
34
+ ### The `dedupe` job — why a claimed branch's first run skips the suite (#418)
35
+
36
+ All three CI templates open with a `dedupe` job. It runs only on the push that **creates** a
37
+ ref, which is what a session claim does: it pushes the new branch at trunk's head. It checks
38
+ nothing out, needs `permissions: actions: read`, and asks whether this same workflow already
39
+ has a green, non-pull-request run at this exact sha. If one exists, every other job is
40
+ skipped and the run still concludes `success`. If not, or if the check cannot run, the suite
41
+ runs as before. Every later push skips the guard, so real commits always get the full suite.
42
+ Two things to keep in a copy:
43
+
44
+ - **The guard calls `gh`.** GitHub-hosted images have it. On a self-hosted image without
45
+ `gh`, the guard prints a notice and the suite runs, so nothing breaks, but nothing is saved
46
+ either.
47
+ - **Every other job needs `!cancelled()` in its `if:`.** Without it, a job inherits the
48
+ implicit `success()`, which reads every ancestor, `dedupe` included. A job that only needs
49
+ `dedupe` indirectly would then be skipped on every ordinary push. That is why the Laravel
50
+ `migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
51
+ conditions to any job you add.
52
+
34
53
  ### Migration round-trip — what the Laravel job proves, and what it cannot
35
54
 
36
55
  `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
@@ -69,7 +88,7 @@ a workflow.
69
88
 
70
89
  | File | Copy to | For | Notes |
71
90
  |---|---|---|---|
72
- | `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes. Reads `project.yml`; missing descriptor → allows, with a warning. |
91
+ | `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
73
92
  | `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
74
93
  | `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
75
94
  | `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
@@ -104,8 +104,59 @@ env:
104
104
  # jobs from different runs interleave, and trunk can wait behind branch runs.
105
105
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
106
106
  jobs:
107
+ # Already tested at this sha? (#418) — the claim push.
108
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
109
+ # claim record), so the branch's first push sits on a sha trunk has usually already
110
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
111
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
112
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
113
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
114
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
115
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
116
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
117
+ # before (fail-open: this job never fails the run). Every later push has
118
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
119
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
120
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
121
+ # §4, "Branch CI"). This job is the one that ends green.
122
+ dedupe:
123
+ name: Already tested at this sha?
124
+ if: github.event_name == 'push' && github.event.created
125
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
126
+ permissions:
127
+ actions: read
128
+ outputs:
129
+ tested: ${{ steps.check.outputs.tested }}
130
+ steps:
131
+ - name: Look for a green run of this workflow at this sha
132
+ id: check
133
+ env:
134
+ GH_TOKEN: ${{ github.token }}
135
+ REPO: ${{ github.repository }}
136
+ RUN_ID: ${{ github.run_id }}
137
+ SHA: ${{ github.sha }}
138
+ run: |
139
+ tested=false
140
+ if ! command -v gh >/dev/null 2>&1; then
141
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
142
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
143
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
144
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
145
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
146
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
147
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
148
+ tested=true
149
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
150
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
151
+ else
152
+ echo "No green run of this workflow at $SHA yet — running the full suite."
153
+ fi
154
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
155
+
107
156
  gitleaks:
108
157
  name: Secret scan (gitleaks)
158
+ needs: dedupe
159
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
109
160
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
161
  steps:
111
162
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -145,6 +196,8 @@ jobs:
145
196
 
146
197
  build:
147
198
  name: Build (Laravel + Vite)
199
+ needs: dedupe
200
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
148
201
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
149
202
  # Re-exported so the migrations job below resolves PHP exactly once, here.
150
203
  outputs:
@@ -154,6 +207,31 @@ jobs:
154
207
  with:
155
208
  persist-credentials: false
156
209
 
210
+ # ---------------------------------------------------------------------------
211
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
212
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
213
+ # once turned every landing in a busy repo back to serial while this CI stayed
214
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
215
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
216
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
217
+ # cap is 3: project.schema.md, `ship-batch`.
218
+ # ---------------------------------------------------------------------------
219
+ - name: Descriptor check (.github/project.yml)
220
+ working-directory: ${{ github.workspace }}
221
+ run: |
222
+ [ -f .github/project.yml ] || exit 0
223
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
224
+ [ -n "$line" ] || exit 0
225
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
226
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
227
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
228
+ case "$v" in
229
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
230
+ *)
231
+ 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."
232
+ exit 1 ;;
233
+ esac
234
+
157
235
  # ---------------------------------------------------------------------------
158
236
  # Toolchain resolution. Precedence, highest first:
159
237
  # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
@@ -351,6 +429,10 @@ jobs:
351
429
  migrations:
352
430
  name: Migration round-trip (${{ matrix.engine }})
353
431
  needs: build
432
+ # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
433
+ # including `dedupe`, which is skipped on every ordinary push — so the implicit
434
+ # form would skip this job on exactly the runs it exists for (#418).
435
+ if: ${{ !cancelled() && needs.build.result == 'success' }}
354
436
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
355
437
  strategy:
356
438
  fail-fast: false
@@ -13,6 +13,7 @@
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
17
  # 1. Resolve the Node version from declared sources — never a hardcoded default.
17
18
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
18
19
  # 3. Install dependencies with the package manager the lockfile implies.
@@ -68,8 +69,59 @@ env:
68
69
  # jobs from different runs interleave, and trunk can wait behind branch runs.
69
70
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
70
71
  jobs:
72
+ # Already tested at this sha? (#418) — the claim push.
73
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
74
+ # claim record), so the branch's first push sits on a sha trunk has usually already
75
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
76
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
77
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
78
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
79
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
80
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
81
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
82
+ # before (fail-open: this job never fails the run). Every later push has
83
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
84
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
85
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
86
+ # §4, "Branch CI"). This job is the one that ends green.
87
+ dedupe:
88
+ name: Already tested at this sha?
89
+ if: github.event_name == 'push' && github.event.created
90
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
91
+ permissions:
92
+ actions: read
93
+ outputs:
94
+ tested: ${{ steps.check.outputs.tested }}
95
+ steps:
96
+ - name: Look for a green run of this workflow at this sha
97
+ id: check
98
+ env:
99
+ GH_TOKEN: ${{ github.token }}
100
+ REPO: ${{ github.repository }}
101
+ RUN_ID: ${{ github.run_id }}
102
+ SHA: ${{ github.sha }}
103
+ run: |
104
+ tested=false
105
+ if ! command -v gh >/dev/null 2>&1; then
106
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
107
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
108
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
109
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
110
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
111
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
112
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
113
+ tested=true
114
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
115
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
116
+ else
117
+ echo "No green run of this workflow at $SHA yet — running the full suite."
118
+ fi
119
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
120
+
71
121
  gitleaks:
72
122
  name: Secret scan (gitleaks)
123
+ needs: dedupe
124
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
73
125
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
74
126
  steps:
75
127
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -114,6 +166,8 @@ jobs:
114
166
 
115
167
  build:
116
168
  name: Build
169
+ needs: dedupe
170
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
117
171
  # A repo can adopt this template before it has any application code at all —
118
172
  # a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
119
173
  # else. Unguarded, every step below still runs: "Install dependencies" warns
@@ -147,6 +201,31 @@ jobs:
147
201
  with:
148
202
  persist-credentials: false
149
203
 
204
+ # ---------------------------------------------------------------------------
205
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
206
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
207
+ # once turned every landing in a busy repo back to serial while this CI stayed
208
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
209
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
210
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
211
+ # cap is 3: project.schema.md, `ship-batch`.
212
+ # ---------------------------------------------------------------------------
213
+ - name: Descriptor check (.github/project.yml)
214
+ working-directory: ${{ github.workspace }}
215
+ run: |
216
+ [ -f .github/project.yml ] || exit 0
217
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
218
+ [ -n "$line" ] || exit 0
219
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
220
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
221
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
222
+ case "$v" in
223
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
224
+ *)
225
+ 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."
226
+ exit 1 ;;
227
+ esac
228
+
150
229
  # ---------------------------------------------------------------------------
151
230
  # Toolchain resolution. Precedence, highest first:
152
231
  # 1. .github/project.yml -> node: <version>
@@ -27,6 +27,7 @@
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
31
  # 1. Resolve the Python version from declared sources — never a hardcoded default.
31
32
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
32
33
  # 3. Install dependencies from whichever manifest the repo actually has.
@@ -82,8 +83,59 @@ env:
82
83
  # jobs from different runs interleave, and trunk can wait behind branch runs.
83
84
  # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
84
85
  jobs:
86
+ # Already tested at this sha? (#418) — the claim push.
87
+ # A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
88
+ # claim record), so the branch's first push sits on a sha trunk has usually already
89
+ # run. Without this job that push re-runs the whole suite on a tested commit (~19% of
90
+ # all runs, measured across five adopting repos). This job runs ONLY on a ref's first
91
+ # push (`github.event.created`), checks nothing out, and asks one question: does THIS
92
+ # workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
93
+ # other job is skipped and the run concludes `success` — a branch-CI `green` that is
94
+ # true, because the same workflow passed at the same sha. Anything else — trunk still
95
+ # running, red, never run, `gh` missing, the API failing — and the suite runs as
96
+ # before (fail-open: this job never fails the run). Every later push has
97
+ # `created == false`, so a real commit always gets the full suite, with no extra hop.
98
+ # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
99
+ # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
100
+ # §4, "Branch CI"). This job is the one that ends green.
101
+ dedupe:
102
+ name: Already tested at this sha?
103
+ if: github.event_name == 'push' && github.event.created
104
+ runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
105
+ permissions:
106
+ actions: read
107
+ outputs:
108
+ tested: ${{ steps.check.outputs.tested }}
109
+ steps:
110
+ - name: Look for a green run of this workflow at this sha
111
+ id: check
112
+ env:
113
+ GH_TOKEN: ${{ github.token }}
114
+ REPO: ${{ github.repository }}
115
+ RUN_ID: ${{ github.run_id }}
116
+ SHA: ${{ github.sha }}
117
+ run: |
118
+ tested=false
119
+ if ! command -v gh >/dev/null 2>&1; then
120
+ echo "::notice::gh is not installed on this runner — running the full suite (#418)."
121
+ elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
122
+ echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
123
+ elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
124
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
125
+ echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
126
+ elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
127
+ tested=true
128
+ echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
129
+ echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
130
+ else
131
+ echo "No green run of this workflow at $SHA yet — running the full suite."
132
+ fi
133
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
134
+
85
135
  gitleaks:
86
136
  name: Secret scan (gitleaks)
137
+ needs: dedupe
138
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
87
139
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
88
140
  steps:
89
141
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -128,6 +180,8 @@ jobs:
128
180
 
129
181
  build:
130
182
  name: Build (Python)
183
+ needs: dedupe
184
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
131
185
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
132
186
  defaults:
133
187
  run:
@@ -138,6 +192,31 @@ jobs:
138
192
  with:
139
193
  persist-credentials: false
140
194
 
195
+ # ---------------------------------------------------------------------------
196
+ # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
197
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
198
+ # once turned every landing in a busy repo back to serial while this CI stayed
199
+ # green; only a ship dry run noticed. So the value fails HERE, where the person
200
+ # who changed project.yml is looking. Same rule as `colab ship` and the audit
201
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
202
+ # cap is 3: project.schema.md, `ship-batch`.
203
+ # ---------------------------------------------------------------------------
204
+ - name: Descriptor check (.github/project.yml)
205
+ working-directory: ${{ github.workspace }}
206
+ run: |
207
+ [ -f .github/project.yml ] || exit 0
208
+ line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
209
+ [ -n "$line" ] || exit 0
210
+ v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
211
+ -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
212
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
213
+ case "$v" in
214
+ ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
215
+ *)
216
+ 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."
217
+ exit 1 ;;
218
+ esac
219
+
141
220
  # ---------------------------------------------------------------------------
142
221
  # Toolchain resolution. Precedence, highest first:
143
222
  # 1. .github/project.yml -> python: <version>
@@ -9,10 +9,14 @@
9
9
  # COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
10
10
  # The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
11
11
  # automatically — main there is what promotion deploys, so it needs the gate most.
12
+ # RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
13
+ # `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
14
+ # they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
15
+ # uses a branch of either name for something else edits its copy of this hook (copy-and-own).
12
16
  # On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
13
17
  # Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
14
18
  #
15
- # The two variables named above are set BY A TOOL (`colab ship`, `colab promote`) or BY A PERSON at
19
+ # The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
16
20
  # the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
17
21
  # process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
18
22
  # The refusal messages below therefore name the remedy and not the variable (#322) — this header is
@@ -51,10 +55,13 @@ integration=$(awk '
51
55
  pushing_trunk=0
52
56
  pushing_main=0
53
57
  pushing_line=""
58
+ pushing_channel=""
54
59
  while read -r _localref _localsha remoteref _remotesha; do
55
60
  case "${remoteref:-}" in
56
61
  refs/heads/"$trunk") pushing_trunk=1 ;;
57
62
  refs/heads/main) pushing_main=1 ;;
63
+ refs/heads/next) pushing_channel=next ;;
64
+ refs/heads/stable) pushing_channel=stable ;;
58
65
  esac
59
66
  for line in $integration; do
60
67
  if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
@@ -105,6 +112,19 @@ if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}
105
112
  exit 1
106
113
  fi
107
114
 
115
+ # RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
116
+ if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
117
+ echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
118
+ echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
119
+ if [ "$pushing_channel" = next ]; then
120
+ echo " colab release cut # a new candidate fast-forwards 'next'" >&2
121
+ else
122
+ echo " colab release finalize # a new final fast-forwards 'stable'" >&2
123
+ fi
124
+ echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
125
+ exit 1
126
+ fi
127
+
108
128
  # MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
109
129
  if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
110
130
  echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
@@ -124,16 +124,24 @@ concurrency:
124
124
  permissions: {}
125
125
 
126
126
  env:
127
- # EDIT: the handbook version whose colab CLI makes the release decisions. Pin a tag;
128
- # moving it is a deliberate act, like re-copying a template.
129
- HANDBOOK_REF: "v1.11.0"
127
+ # EDIT: the handbook ref whose colab CLI makes the release decisions — a CHANNEL or a
128
+ # version tag (CONVENTIONS.md §6, *Release channels*, #445):
129
+ # stable the newest final release — the default; it moves forward as finals are cut,
130
+ # and that release's notes say what changed
131
+ # next the newest candidate (vX.Y.Z-rc.N) — the fast channel
132
+ # vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
133
+ # a template
134
+ HANDBOOK_REF: "stable"
130
135
  HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
131
136
 
132
137
  jobs:
133
138
  release:
134
139
  name: Cut, finalize, publish
135
- # A red CI run on main is not a candidate; skip rather than refuse.
136
- if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
140
+ # No job-level `if:` here, on purpose (#435): a red CI run is gated in the first step below,
141
+ # so this run concludes success. A job-level `if:` would skip every job, GitHub would record
142
+ # the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
143
+ # neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
144
+ # Release (auto) row would still sit beside it, refusing every ship until main moves.
137
145
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
138
146
  permissions:
139
147
  contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
@@ -160,6 +168,23 @@ jobs:
160
168
  # checkout's origin. The token is this job's, scoped by `permissions:` above.
161
169
  persist-credentials: true
162
170
 
171
+ # A red CI run on main is not a candidate. Gated here rather than by a job-level `if:` so
172
+ # this run concludes success, never `skipped` (#435; the comment on the job above).
173
+ - name: Gate on the triggering CI run
174
+ id: gate
175
+ env:
176
+ EVENT: ${{ github.event_name }}
177
+ CONCLUSION: ${{ github.event.workflow_run.conclusion }}
178
+ HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
179
+ run: |
180
+ set -euo pipefail
181
+ if [ "$EVENT" = "workflow_run" ] && [ "$CONCLUSION" != "success" ]; then
182
+ echo "cut=false" >> "$GITHUB_OUTPUT"
183
+ echo "CI concluded \`$CONCLUSION\` at $HEAD_SHA — nothing to cut." | tee -a "$GITHUB_STEP_SUMMARY"
184
+ else
185
+ echo "cut=true" >> "$GITHUB_OUTPUT"
186
+ fi
187
+
163
188
  - name: Fetch the colab CLI
164
189
  run: |
165
190
  set -euo pipefail
@@ -214,7 +239,7 @@ jobs:
214
239
  # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
215
240
  - name: Cut a candidate (colab release cut --auto)
216
241
  id: cut
217
- if: (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
242
+ 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'
218
243
  run: |
219
244
  set -uo pipefail
220
245
  OUT="$RUNNER_TEMP/cut.json"