@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
@@ -55,22 +55,38 @@ on:
55
55
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
56
56
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
57
57
  branches: ['**']
58
- pull_request:
59
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
60
- # trunk, main the release; Tier B: main only).
61
- branches: [main, dev]
58
+ # No `pull_request:` here (#512). A branch with an open PR in this repository already
59
+ # has a push run at the same head, and a `pull_request` run beside it doubled the CI
60
+ # per commit while testing a merge ref instead of the sha that lands. Readers keep only
61
+ # the newest run per workflow at a sha, so that second run also decided the verdict.
62
+ # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
63
+ # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
64
+ # only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
65
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
66
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
67
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
68
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
69
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
70
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
71
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
72
+ # pull_request:
73
+ # branches: ['**']
62
74
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
63
75
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
64
76
  workflow_dispatch:
65
77
 
66
78
  # One live run per branch: a new push cancels the superseded run on the same ref.
67
79
  # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
68
- # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
69
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
70
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
71
- # may carry any name; one left off this list gets its trunk runs cancelled.
80
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
81
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
82
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
83
+ # drop the second one's run before it ever started (#512).
84
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
85
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
86
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
87
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
72
88
  concurrency:
73
- group: ci-${{ github.ref }}
89
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
74
90
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
75
91
 
76
92
  env:
@@ -113,17 +129,35 @@ jobs:
113
129
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
114
130
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
115
131
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
116
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
132
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
133
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
134
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
135
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
136
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
137
+ #
138
+ # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
139
+ # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
140
+ # asks a third question: is every path changed since the base documentation, by the rule
141
+ # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
142
+ # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
143
+ # submodule or a binary), and does the base
144
+ # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
145
+ # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
146
+ # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
147
+ # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
148
+ # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
149
+ # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
117
150
  dedupe:
118
151
  name: Already tested at this sha or tree?
119
152
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
120
153
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
121
154
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
155
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
122
156
  permissions:
123
157
  actions: read
124
158
  contents: read
125
159
  outputs:
126
- tested: ${{ steps.check.outputs.tested }}
160
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
127
161
  cited: ${{ steps.check.outputs.cited }}
128
162
  steps:
129
163
  - name: Look for a green run of this workflow at this sha or tree
@@ -135,9 +169,58 @@ jobs:
135
169
  SHA: ${{ github.sha }}
136
170
  CREATED: ${{ github.event.created }}
137
171
  REF_NAME: ${{ github.ref_name }}
172
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
138
173
  run: |
139
174
  tested=false
140
175
  cited=
176
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
177
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
178
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
179
+ reusable() {
180
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
181
+ --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name] | join(", ") end' 2>/dev/null)"; then
182
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
183
+ return 1
184
+ elif [ -n "$SK" ]; then
185
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
186
+ return 1
187
+ fi
188
+ }
189
+ # The candidate runs, one per line as "<id> <head sha> <url> <branch>", newest first: green
190
+ # push runs of this workflow on another ref of this repo. #552: those at THIS sha first (a
191
+ # `ship-batch/*` run trunk fast-forwarded to), an exact query; then those whose commit has
192
+ # THIS tree (#493). The query's own per_page bounds the walk (#592).
193
+ same_sha() {
194
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
195
+ --jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
196
+ }
197
+ same_tree() {
198
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
199
+ --jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
200
+ }
201
+ # #592: cite the newest candidate on stdin that passes every check. One that fails a check
202
+ # is passed over, not the end of the search: the newest green run can be a skip-chained one
203
+ # (#511) while an older run at the same sha or tree ran every job. A run already tried (the
204
+ # sha query's runs reappear in the tree listing) is not tried twice.
205
+ cite() {
206
+ local CID CSHA URL BR CTREE
207
+ while read -r CID CSHA URL BR; do
208
+ [ -n "$CID" ] || continue
209
+ case " $TRIED " in *" $CID "*) continue ;; esac
210
+ TRIED="$TRIED $CID"
211
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
212
+ echo "::notice::Could not confirm the tree of $CSHA — passing over run $CID (#493)."
213
+ elif reusable "$CID"; then
214
+ tested=true
215
+ cited="$URL"
216
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
217
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
218
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
219
+ return 0
220
+ fi
221
+ done
222
+ return 1
223
+ }
141
224
  if ! command -v gh >/dev/null 2>&1; then
142
225
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
143
226
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -152,21 +235,17 @@ jobs:
152
235
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
153
236
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
154
237
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
155
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
156
- --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
157
- echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
158
- elif [ -z "$CAND" ]; then
159
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
160
238
  else
161
- read -r CSHA URL BR <<< "$CAND"
162
- if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
163
- echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
164
- else
165
- tested=true
166
- cited="$URL"
167
- echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
168
- echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
169
- echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
239
+ TRIED=
240
+ SC="$(same_sha)" || SC= # the sha query failing falls through to the tree listing (#552)
241
+ if [ -n "$SC" ] && cite <<< "$SC"; then
242
+ :
243
+ elif ! TC="$(same_tree)"; then
244
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
245
+ elif [ -z "$SC$TC" ]; then
246
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
247
+ elif ! cite <<< "$TC"; then
248
+ echo "No green run of this workflow at sha $SHA or tree $OURS can be cited — running the full suite (#592)."
170
249
  fi
171
250
  fi
172
251
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
@@ -181,12 +260,167 @@ jobs:
181
260
  fi
182
261
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
183
262
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
263
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
264
+ - name: Find the base a docs-only change would rely on
265
+ id: docs_base
266
+ if: steps.check.outputs.tested != 'true'
267
+ env:
268
+ GH_TOKEN: ${{ github.token }}
269
+ REPO: ${{ github.repository }}
270
+ RUN_ID: ${{ github.run_id }}
271
+ SHA: ${{ github.sha }}
272
+ BEFORE: ${{ github.event.before }}
273
+ CREATED: ${{ github.event.created }}
274
+ REF: ${{ github.ref }}
275
+ REF_NAME: ${{ github.ref_name }}
276
+ run: |
277
+ base=
278
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
279
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
280
+ optin() {
281
+ local v items
282
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
283
+ if [ -z "$v" ]; then
284
+ items="$(printf '%s\n' "$DESC" | awk '/^ci-docs-skip[[:space:]]*:/{f=1;next} f&&/^[[:space:]]+-/{sub(/^[[:space:]]+-[[:space:]]*/,"");sub(/[[:space:]]+#.*$/,"");print;next} f&&/^[[:space:]]*(#.*)?$/{next} {f=0}')"
285
+ [ -n "$items" ] || return 1
286
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
287
+ v="${v#[}"; v="${v%]}"
288
+ items="$(printf '%s' "$v" | tr ',' '\n')"
289
+ else
290
+ return 1
291
+ fi
292
+ EXCLUDE=
293
+ while IFS= read -r it; do
294
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
295
+ [ -n "$it" ] || continue
296
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
297
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
298
+ EXCLUDE="$EXCLUDE ${it%/}"
299
+ done <<< "$items"
300
+ }
301
+ if ! command -v gh >/dev/null 2>&1; then
302
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
303
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
304
+ echo "$REF is not a branch — docs-only mode is off (#570)."
305
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
306
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
307
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
308
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
309
+ elif ! optin; then
310
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
311
+ else
312
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
313
+ if [ -z "$TRUNK" ]; then
314
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
315
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
316
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
317
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
318
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
319
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
320
+ base="$BEFORE" # a push to trunk: the change is what this push added
321
+ else
322
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
323
+ fi
324
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
325
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
326
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
327
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
328
+ if [ -n "$base" ]; then
329
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
330
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
331
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .head_branch == \"$TRUNK\" and .head_repository.full_name == \"$REPO\")] | sort_by(.created_at) | last | if . != null and .status == \"completed\" and .conclusion == \"success\" then .html_url else empty end" 2>/dev/null)"; then
332
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
333
+ base=
334
+ elif [ -z "$URL" ]; then
335
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
336
+ base=
337
+ fi
338
+ fi
339
+ fi
340
+ if [ -n "$base" ]; then
341
+ echo "base=$base" >> "$GITHUB_OUTPUT"
342
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
343
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
344
+ fi
345
+ - name: Is every changed path documentation?
346
+ id: docs
347
+ if: steps.docs_base.outputs.base != ''
348
+ env:
349
+ GH_TOKEN: ${{ github.token }}
350
+ SERVER_URL: ${{ github.server_url }}
351
+ REPO: ${{ github.repository }}
352
+ SHA: ${{ github.sha }}
353
+ BASE: ${{ steps.docs_base.outputs.base }}
354
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
355
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
356
+ run: |
357
+ tested=false
358
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
359
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
360
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
361
+ reason() {
362
+ local p="$1" base dir x
363
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
364
+ case "$p" in \"*) echo "quoted path"; return ;; esac
365
+ for x in $EXCLUDE; do
366
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
367
+ done
368
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
369
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
370
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
371
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
372
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
373
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
374
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
375
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
376
+ case "$p" in docs/*) return ;; esac
377
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
378
+ echo "not .md/.mdx/.txt and not under docs/"
379
+ }
380
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
381
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
382
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
383
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
384
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
385
+ && git -C "$G" config http.extraheader "$AUTH" \
386
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
387
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
388
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
389
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
390
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
391
+ elif [ -z "$RAW" ]; then
392
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
393
+ else
394
+ bad=; n=0
395
+ while IFS= read -r line; do
396
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
397
+ why="$(reason "$p")"
398
+ set -- $meta
399
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
400
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
401
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
402
+ done <<< "$RAW"
403
+ while IFS=$'\t' read -r a d p; do
404
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
405
+ done <<< "$NUM"
406
+ if [ -n "$bad" ]; then
407
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
408
+ else
409
+ tested=true
410
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
411
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
412
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
413
+ fi
414
+ fi
415
+ rm -rf "$G"
416
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
184
417
 
185
418
  gitleaks:
186
419
  name: Secret scan (gitleaks)
187
420
  needs: dedupe
188
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
421
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
189
422
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
423
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
190
424
  steps:
191
425
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
192
426
  with:
@@ -231,8 +465,11 @@ jobs:
231
465
  build:
232
466
  name: Build (Python)
233
467
  needs: dedupe
234
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
468
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
235
469
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
470
+ timeout-minutes: 30 # a hung build must not hold the runner for the 360-minute default (#572).
471
+ # EDIT: NOT a measured fit (#572) — one Python adopter, whose build is a byte-compile (p99
472
+ # under 1 min). Set it well above YOUR p99 — below it a slow but healthy suite goes red.
236
473
  defaults:
237
474
  run:
238
475
  # EDIT: set to the directory holding the Python project if it is not at the root.
@@ -244,13 +481,15 @@ jobs:
244
481
 
245
482
  # ---------------------------------------------------------------------------
246
483
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
247
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
484
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
248
485
  # once turned every landing in a busy repo back to serial while this CI stayed
249
486
  # green; only a ship dry run noticed. So the value fails HERE, where the person
250
487
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
251
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
252
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
488
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
489
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
253
490
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
491
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
492
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
254
493
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
255
494
  # ---------------------------------------------------------------------------
256
495
  - name: Descriptor check (.github/project.yml)
@@ -266,11 +505,26 @@ jobs:
266
505
  }
267
506
  v="$(field ship-batch)"
268
507
  case "$v" in
269
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
508
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
270
509
  *)
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."
510
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
272
511
  exit 1 ;;
273
512
  esac
513
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
514
+ s="$(field ship-batch-steps)"
515
+ case "$s" in
516
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
517
+ *)
518
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
519
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
520
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
521
+ && printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
522
+ echo "ship-batch-steps: $list — ok"
523
+ else
524
+ echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
525
+ exit 1
526
+ fi ;;
527
+ esac
274
528
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
275
529
  w="$(field ship-batch-wait)"
276
530
  case "$w" in
@@ -420,9 +674,24 @@ jobs:
420
674
  echo "Python $PY_VERSION (resolved from: $SOURCE)"
421
675
  echo "Python **$PY_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
422
676
 
677
+ # Package cache (#571): pip's wheel cache, on only on a GitHub-hosted runner AND with a
678
+ # dependency manifest present. Both halves are load-bearing:
679
+ # - No requirements*.txt / pyproject.toml → setup-python's `cache: pip` fails the step
680
+ # ("No file ... matched"), and this template allows a repo with neither.
681
+ # - Self-hosted → off. A persistent runner already keeps ~/.cache/pip between jobs; a
682
+ # remote cache on top was measured as a loss, not a saving (#512).
683
+ # The cache holds downloaded wheels, never a resolution: it cannot change which versions
684
+ # install, so a repo without a pinned lockfile is no less reproducible with it on.
685
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, replace the
686
+ # `cache:` expression with ''. Manifests outside the root → widen cache-dependency-path
687
+ # and the hashFiles() to match.
423
688
  - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
424
689
  with:
425
690
  python-version: ${{ steps.toolchain.outputs.python-version }}
691
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('requirements*.txt', 'pyproject.toml') != '' && 'pip' || '' }}
692
+ cache-dependency-path: |
693
+ requirements*.txt
694
+ pyproject.toml
426
695
 
427
696
  - name: Install dependencies
428
697
  run: |
@@ -14,7 +14,8 @@
14
14
  // previous final), verifies that, and still fails the run. A manual rollback is a re-run
15
15
  // with the previous tag.
16
16
  // The outcome — "running vX.Y.Z at <time>" or the failure — goes to the run summary and, when one
17
- // exists, to the release issue (the issue carrying `<!-- colab:release version=vX.Y.Z -->`).
17
+ // exists, to the release issue (the issue whose body STARTS with `<!-- colab:release version=vX.Y.Z -->`;
18
+ // one that only mentions it is not the record — #576).
18
19
  //
19
20
  // CONFIGURATION (env; the workflow's one env block):
20
21
  // DEPLOY_ADAPTER portainer (default) — loads ./deploy-adapter-<name>.mjs beside this file
@@ -187,12 +188,25 @@ async function waitForVersion(url, version, io, timeoutS, auth = {}) {
187
188
  }
188
189
  }
189
190
 
191
+ // The release issue is the one whose body STARTS with the marker (leading whitespace tolerated) —
192
+ // never one that merely mentions it, which the search above also returns, in an order GitHub's
193
+ // ranking decides (#576). The same anchored rule as the handbook's release codec
194
+ // (`decodeTrackingMarker`, #575), restated here because this copy never calls back to the handbook.
195
+ export function releaseIssue(json, tag) {
196
+ let list;
197
+ try { list = JSON.parse(json || '[]'); } catch { return ''; }
198
+ if (!Array.isArray(list)) return '';
199
+ const re = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
200
+ const hit = list.find((i) => { const m = re.exec(String((i && i.body) || '')); return m && m[1] === tag; });
201
+ return hit ? String(hit.number) : '';
202
+ }
203
+
190
204
  function record(io, tag, line) {
191
205
  io.summary(line);
192
206
  const repo = io.env.GITHUB_REPOSITORY;
193
207
  if (!repo) return;
194
- const found = io.sh('gh', ['issue', 'list', '--repo', repo, '--state', 'all', '--search', `"colab:release version=${tag}" in:body`, '--json', 'number', '--jq', '.[0].number // ""']);
195
- const n = found.status === 0 ? found.stdout.trim() : '';
208
+ const found = io.sh('gh', ['issue', 'list', '--repo', repo, '--state', 'all', '--search', `"colab:release version=${tag}" in:body`, '--json', 'number,body']);
209
+ const n = found.status === 0 ? releaseIssue(found.stdout, tag) : '';
196
210
  if (!n) { io.log(`no release issue for ${tag} — recorded in the run summary only`); return; }
197
211
  const c = io.sh('gh', ['issue', 'comment', n, '--repo', repo, '--body', line]);
198
212
  if (c.status !== 0) io.log(`could not comment on release issue #${n}: ${c.stderr.trim()}`);
@@ -103,6 +103,11 @@ on:
103
103
  # EDIT: only if your tag convention differs. This trigger is what makes
104
104
  # `deploy: tag` true — a tag is the deploy, a branch push is not.
105
105
  - "v*.*.*"
106
+ # A pre-release (v1.2.3-rc.1, -beta.2) never deploys: `v*.*.*` matches it, and the
107
+ # release workflow cuts a candidate tag automatically. The final tag is the deploy.
108
+ # This line MUST come right after the positive pattern it excludes — GitHub applies
109
+ # the patterns in order, so a negative pattern placed before it excludes nothing.
110
+ - "!v*.*.*-*"
106
111
  workflow_dispatch:
107
112
  inputs:
108
113
  ref:
@@ -154,6 +159,13 @@ jobs:
154
159
  # EDIT: your runner label. See the SELF-HOSTED RUNNER note in the header —
155
160
  # this file assumes PHP and Composer already exist on the box.
156
161
  runs-on: [self-hosted, Linux, X64]
162
+ # EDIT: size this above your slowest healthy deploy (build + rsync + migrate +
163
+ # smoke), with headroom for a large migration. Without it a hung step — an SSH
164
+ # session waiting on a prompt, a migration blocked on a lock — holds this
165
+ # self-hosted runner for GitHub's default 360 minutes, and every later deploy
166
+ # queues behind it. A deploy that legitimately needs longer should raise this,
167
+ # not delete it.
168
+ timeout-minutes: 30
157
169
  steps:
158
170
  - name: Checkout
159
171
  uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -0,0 +1,16 @@
1
+ # Copy to .github/workflows/instruction-files.yml — CLAUDE.md must be @AGENTS.md + tool blocks (#588).
2
+ name: instruction-files
3
+ on:
4
+ # Keep `push:` UNFILTERED (#599). The ratchet is meant to fail on the session branch that breaks
5
+ # it, before trunk; narrowed to `branches: [main]`, it first fails ON trunk, and the cure branch's
6
+ # push run cannot prove the job (#297). The audit reports a narrowed copy.
7
+ push:
8
+ pull_request:
9
+ # Lets `colab ship` prove a red job on a cure branch by dispatch (#510), with no human ci-grant.
10
+ workflow_dispatch:
11
+ jobs:
12
+ instruction-files:
13
+ uses: futurelastic/colab-handbook/.github/workflows/instruction-files.yml@main
14
+ # No GitHub-hosted minutes (self-hosted-only org)? Pass your runner (#594) — a label or a JSON list:
15
+ # with:
16
+ # runs-on: '["self-hosted","linux"]'
@@ -0,0 +1,55 @@
1
+ #!/bin/sh
2
+ # pre-commit-instruction-files — refuse a commit that leaves repo prose in a CLAUDE.md (#588).
3
+ #
4
+ # THE RULE (CONVENTIONS.md §9 step 5). Repo prose lives in AGENTS.md; CLAUDE.md is only the
5
+ # `@AGENTS.md` import plus the blocks tools look up in CLAUDE.md by name (the Conventions block
6
+ # with its stamp, any paired tool-managed block). An editor-side hook only sees edits made through
7
+ # one agent's file tools — a shell write, another agent, a person or a generator that rewrites
8
+ # CLAUDE.md all pass it. This runs on every commit, whoever made it.
9
+ #
10
+ # THE JUDGEMENT IS NOT HERE. It is `colab instruction-files --staged` — the same code the audit
11
+ # and the reusable CI workflow (.github/workflows/instruction-files.yml in the handbook) run, so
12
+ # the three cannot disagree. Same ratchet too: staging a CLAUDE.md or AGENTS.md is touching the
13
+ # rule's files, so every CLAUDE.md must then conform; a commit that leaves both alone is never
14
+ # judged, so an unmigrated repo is not blocked by adding this hook.
15
+ #
16
+ # COST. With no CLAUDE.md/AGENTS.md staged this is one `git diff --cached --name-only` and exits —
17
+ # a few milliseconds. Only a commit that stages one of them starts node.
18
+ #
19
+ # WHERE `colab` COMES FROM: $COLAB_BIN if set (the handbook's own hooklet points it at its
20
+ # checkout), else `colab` on PATH. Neither present → warn and pass: an unconfigured machine is a
21
+ # different statement from a failed check, and CI still runs the same judgement on the push.
22
+ #
23
+ # INSTALL — beside the dispatcher (templates/pre-commit-dispatch, see its header):
24
+ # cp templates/pre-commit-instruction-files <hooks>/pre-commit.d/30-instruction-files
25
+ # chmod +x <hooks>/pre-commit.d/30-instruction-files
26
+ #
27
+ # EXIT: 0 pass (or nothing to judge, or no colab), 1 refused — the message names the fix.
28
+
29
+ set -u
30
+
31
+ staged=$(git diff --cached --name-only --diff-filter=ACMRT 2>/dev/null | grep -E '(^|/)(CLAUDE|AGENTS)\.md$' || true)
32
+ [ -n "$staged" ] || exit 0
33
+
34
+ bin="${COLAB_BIN:-colab}"
35
+ if [ -n "${COLAB_BIN:-}" ]; then
36
+ [ -f "$bin" ] || { printf '%s\n' "⚠ pre-commit-instruction-files: COLAB_BIN=$bin does not exist — not judged; CI will judge on push." >&2; exit 0; }
37
+ set -- node "$bin"
38
+ elif command -v colab >/dev/null 2>&1; then
39
+ set -- colab
40
+ else
41
+ printf '%s\n' "⚠ pre-commit-instruction-files: \`colab\` is not installed — CLAUDE.md not judged here; CI will judge it on push (npm i -g @futurelastic/colab-handbook)." >&2
42
+ exit 0
43
+ fi
44
+
45
+ "$@" instruction-files --staged
46
+ status=$?
47
+ if [ "$status" -eq 1 ]; then
48
+ printf '%s\n' "❌ commit BLOCKED: move the prose above into AGENTS.md and keep CLAUDE.md to \`@AGENTS.md\` + tool blocks." >&2
49
+ exit 1
50
+ fi
51
+ if [ "$status" -ne 0 ]; then
52
+ printf '%s\n' "❌ commit BLOCKED: the instruction-file check could not run (exit $status) — see above." >&2
53
+ exit 1
54
+ fi
55
+ exit 0