@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11

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 (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. package/bin/cli.js +0 -3
@@ -0,0 +1,291 @@
1
+ # CI (Node) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
5
+ # calls this file remotely and nothing will update it for you — divergence between
6
+ # your copy and the handbook is expected and fine. If you find an improvement worth
7
+ # sharing, change the handbook template too, but that is a manual, deliberate act.
8
+ #
9
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
+ #
11
+ # For: pure Node projects (Vite SPA, node libs, Astro static sites, Capacitor apps).
12
+ # NOT for: Laravel + Inertia fullstack apps — their Vite build shells out to
13
+ # `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
14
+ #
15
+ # What it does:
16
+ # 1. Resolve the Node version from declared sources — never a hardcoded default.
17
+ # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
18
+ # 3. Install dependencies with the package manager the lockfile implies.
19
+ # 4. Run typecheck / lint / test only if package.json declares those scripts, so a
20
+ # repo without them is not forced to add placeholders to keep CI green.
21
+ # 5. Build.
22
+
23
+ name: CI
24
+
25
+ on:
26
+ push:
27
+ # Every branch, not only trunk (#384). Sessions push branches without opening a
28
+ # PR, so a trunk-only trigger leaves a candidate with no run of its own before the
29
+ # merge: its first run is the post-merge trunk run, and a red there is everyone's
30
+ # TRUNK RED instead of one implementer's hand-back (CONVENTIONS.md §4, "Branch
31
+ # CI"). '**' also covers `ship-batch/**`, the batch-landing opt-in.
32
+ #
33
+ # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
34
+ # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
35
+ # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
36
+ # runners, a runner pool, or a trunk-only label picked in `runs-on` on
37
+ # github.ref all have that capacity; keep '**' there. Trunk-only means the
38
+ # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
39
+ # dev is the trunk, so a main-only trigger runs zero checks on the branch you
40
+ # merge into, and nothing looks broken (CONVENTIONS.md §7).
41
+ branches: ['**']
42
+ pull_request:
43
+ # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
44
+ # trunk, main the release; Tier B: main only).
45
+ branches: [main, dev]
46
+ # A promotion pushed by the release workflow's token triggers no push run, so that workflow
47
+ # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
48
+ workflow_dispatch:
49
+
50
+ # One live run per branch: a new push cancels the superseded run on the same ref.
51
+ # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
52
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
53
+ # group under refs/pull/<n>/merge, apart from the branch's push runs.
54
+ # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
55
+ # may carry any name; one left off this list gets its trunk runs cancelled.
56
+ concurrency:
57
+ group: ci-${{ github.ref }}
58
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
59
+
60
+ env:
61
+ # EDIT: bump deliberately, not automatically.
62
+ GITLEAKS_VERSION: "8.30.1"
63
+ # EDIT: npm script to build. Change for monorepos or non-standard scripts.
64
+ BUILD_COMMAND: "build"
65
+
66
+ # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
67
+ # fresh machine per job. With few self-hosted agents every job is a queue slot,
68
+ # jobs from different runs interleave, and trunk can wait behind branch runs.
69
+ # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
70
+ jobs:
71
+ gitleaks:
72
+ name: Secret scan (gitleaks)
73
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
74
+ steps:
75
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
76
+ with:
77
+ # Full history: gitleaks scans commits, not just the working tree, so a
78
+ # secret that was committed and later removed is still caught.
79
+ fetch-depth: 0
80
+ persist-credentials: false
81
+
82
+ - name: Install gitleaks (pinned release binary)
83
+ run: |
84
+ # Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
85
+ # GITLEAKS_LICENSE for repositories owned by an organization (free only for
86
+ # personal repos). The release binary itself is MIT and has no such gate.
87
+ # Repos also carry a local pre-commit gitleaks hook; this is the second layer.
88
+ # The asset is OS/arch-specific, so resolve both from uname instead of
89
+ # assuming the GitHub-hosted default: a hardcoded linux_x64 binary on a
90
+ # macOS self-hosted runner is an ELF the kernel cannot exec, and the step
91
+ # fails with exit 126 rather than anything mentioning the platform.
92
+ case "$(uname -s)" in
93
+ Darwin) os=darwin ;;
94
+ Linux) os=linux ;;
95
+ *) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
96
+ esac
97
+ case "$(uname -m)" in
98
+ arm64|aarch64) arch=arm64 ;;
99
+ x86_64|amd64) arch=x64 ;;
100
+ *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
101
+ esac
102
+ curl -sSL -o gitleaks.tar.gz \
103
+ "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
104
+ # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
105
+ # step then works on BOTH GitHub-hosted and shared self-hosted runners
106
+ # (a shared runner is infrastructure; jobs must not mutate it).
107
+ tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
108
+ chmod +x "$RUNNER_TEMP/gitleaks"
109
+ echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
110
+ rm -f gitleaks.tar.gz
111
+
112
+ - name: gitleaks detect
113
+ run: gitleaks detect --source . --no-banner
114
+
115
+ build:
116
+ name: Build
117
+ # A repo can adopt this template before it has any application code at all —
118
+ # a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
119
+ # else. Unguarded, every step below still runs: "Install dependencies" warns
120
+ # and falls through to `npm install` with no package.json to install, then
121
+ # "Build" fails outright trying to read it — turning trunk CI red as the
122
+ # first consequence of adopting, not of anything about the repo changing.
123
+ # Skip the package.json-dependent steps instead, the same way the generic
124
+ # scaffold workflow guards it (`if [ -f package.json ]; then node=true; else
125
+ # node=false; fi`). gitleaks above stays unconditional — a repo with no code
126
+ # can still commit a secret.
127
+ #
128
+ # NOTE (#245): this guard used to sit here, at job level — `if:
129
+ # hashFiles('package.json') != ''`. `hashFiles()` is NOT among the functions
130
+ # GitHub allows in `jobs.<job_id>.if` (only `github` / `needs` / `vars` /
131
+ # `inputs` plus always()/cancelled()/success()/failure()); a job-level `if:`
132
+ # using it is rejected at workflow-VALIDATION time, before any job runs — the
133
+ # whole workflow file fails with "0 jobs created" and a message that names
134
+ # neither the key nor the expression. It is valid in a step-level `if:`,
135
+ # which is why it looked right when written (a042cea, fixing #73). Moved the
136
+ # guard onto every step below that assumes package.json exists instead — the
137
+ # workspace isn't even checked out yet at job level, so a job-level
138
+ # hashFiles() would have been testing an empty directory even if it were
139
+ # allowed.
140
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
141
+ defaults:
142
+ run:
143
+ # EDIT: set to the directory holding package.json if the app is not at the root.
144
+ working-directory: .
145
+ steps:
146
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
147
+ with:
148
+ persist-credentials: false
149
+
150
+ # ---------------------------------------------------------------------------
151
+ # Toolchain resolution. Precedence, highest first:
152
+ # 1. .github/project.yml -> node: <version>
153
+ # 2. .nvmrc, else package.json -> engines.node
154
+ # 3. FAIL.
155
+ #
156
+ # There is deliberately NO fallback default. A silent default is exactly how a
157
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
158
+ # CI was green and proved nothing about what actually shipped. If the version
159
+ # is not declared anywhere, that is a bug in the repo, and the build says so.
160
+ # ---------------------------------------------------------------------------
161
+ - name: Resolve Node version
162
+ id: toolchain
163
+ if: hashFiles('package.json') != ''
164
+ run: |
165
+ set -euo pipefail
166
+
167
+ # Normalise "^22", ">=22.1", "v22", "22.x" -> "22.1" / "22". setup-node
168
+ # accepts a partial version and picks the newest matching release.
169
+ normalise() {
170
+ printf '%s' "$1" \
171
+ | tr -d '"' \
172
+ | sed -E 's/^[^0-9]*//' \
173
+ | sed -E 's/[[:space:]].*$//' \
174
+ | sed -E 's/\.x$//' \
175
+ | sed -E 's/[^0-9.].*$//' \
176
+ | sed -E 's/\.$//'
177
+ }
178
+
179
+ NODE_VERSION=""
180
+ SOURCE=""
181
+
182
+ # 1. project.yml wins. Flat `node: 22` mapping; good enough, this file is
183
+ # a handful of keys by design.
184
+ if [ -f .github/project.yml ]; then
185
+ V="$(sed -nE 's/^[[:space:]]*node:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
186
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
187
+ NODE_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (node:)"
188
+ fi
189
+ fi
190
+
191
+ # 2a. .nvmrc
192
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
193
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
194
+ if [ -n "$V" ]; then
195
+ NODE_VERSION="$(normalise "$V")"; SOURCE=".nvmrc"
196
+ fi
197
+ fi
198
+
199
+ # 2b. package.json -> engines.node
200
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
201
+ V=""
202
+ if command -v node >/dev/null 2>&1; then
203
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
204
+ elif command -v python3 >/dev/null 2>&1; then
205
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
206
+ fi
207
+ if [ -n "$V" ]; then
208
+ NODE_VERSION="$(normalise "$V")"; SOURCE="package.json (engines.node)"
209
+ fi
210
+ fi
211
+
212
+ # 3. No declared source -> stop. Do not guess.
213
+ if [ -z "$NODE_VERSION" ]; then
214
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
215
+ {
216
+ echo ""
217
+ echo "Declare it in ONE of these places (checked in this order):"
218
+ echo " 1. .github/project.yml -> node: \"22\" (preferred: one descriptor for the whole repo)"
219
+ echo " 2. .nvmrc -> 22 (also drives local dev via nvm/fnm)"
220
+ echo " or package.json -> \"engines\": { \"node\": \">=22\" }"
221
+ echo ""
222
+ echo "Pick the version your DEPLOY target runs. CI on a different major than"
223
+ echo "production proves nothing."
224
+ } >&2
225
+ exit 1
226
+ fi
227
+
228
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
229
+ echo "Node $NODE_VERSION (resolved from: $SOURCE)"
230
+ echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
231
+
232
+ - name: Setup Node
233
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
234
+ if: hashFiles('package.json') != ''
235
+ with:
236
+ node-version: ${{ steps.toolchain.outputs.node-version }}
237
+
238
+ - name: Install dependencies
239
+ if: hashFiles('package.json') != ''
240
+ run: |
241
+ # Lockfile decides the package manager. `npm ci` / `--frozen-lockfile` are
242
+ # intentional: CI must fail on a stale lockfile rather than silently resolve
243
+ # a different dependency tree than the developer had.
244
+ if [ -f pnpm-lock.yaml ]; then
245
+ corepack enable
246
+ pnpm install --frozen-lockfile
247
+ elif [ -f package-lock.json ]; then
248
+ npm ci
249
+ else
250
+ echo "::warning::No lockfile found — falling back to 'npm install'. Commit a lockfile so CI is reproducible."
251
+ npm install
252
+ fi
253
+
254
+ - name: Detect optional scripts
255
+ id: scripts
256
+ if: hashFiles('package.json') != ''
257
+ run: |
258
+ # package.json's `scripts` decides what this job MEASURES: a missing script
259
+ # skips its step and the job still concludes success. So `colab ship`'s cure
260
+ # rule treats a scripts change as an instrument change and never lets such a
261
+ # branch cure a red trunk by itself (CONVENTIONS.md, Cure rule, condition 5).
262
+ #
263
+ # node -e over grep: package.json is JSON, and a "typecheck" substring can
264
+ # appear inside a dependency name or another script's body.
265
+ has() {
266
+ node -e "const s=(require('./package.json').scripts)||{};process.exit(s['$1']?0:1)" 2>/dev/null
267
+ }
268
+ for s in typecheck lint test; do
269
+ if has "$s"; then
270
+ echo "$s=true" >> "$GITHUB_OUTPUT"
271
+ else
272
+ echo "$s=false" >> "$GITHUB_OUTPUT"
273
+ echo "::notice::No '$s' script in package.json — skipping."
274
+ fi
275
+ done
276
+
277
+ - name: Typecheck
278
+ if: steps.scripts.outputs.typecheck == 'true'
279
+ run: npm run typecheck
280
+
281
+ - name: Lint
282
+ if: steps.scripts.outputs.lint == 'true'
283
+ run: npm run lint
284
+
285
+ - name: Test
286
+ if: steps.scripts.outputs.test == 'true'
287
+ run: npm test
288
+
289
+ - name: Build
290
+ if: hashFiles('package.json') != ''
291
+ run: npm run "$BUILD_COMMAND"
@@ -0,0 +1,281 @@
1
+ # CI (Python) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
5
+ # calls this file remotely and nothing will update it for you — divergence between
6
+ # your copy and the handbook is expected and fine. If you find an improvement worth
7
+ # sharing, change the handbook template too, but that is a manual, deliberate act.
8
+ #
9
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
+ #
11
+ # For: Python projects — FastAPI/Flask services, CLI tools, libraries.
12
+ #
13
+ # HYBRID REPOS (a Python backend plus a Node/Vite frontend in one repo) are a real
14
+ # and common shape here, and this template covers HALF of one. Do not copy the Node
15
+ # template and graft a Python job into it: the header then lies about what the file
16
+ # is, and that is exactly how a repo ended up with `python-version: "3.13"` hardcoded
17
+ # — the Node template's own rule 1 forbids hardcoding, but there was nowhere to
18
+ # declare a Python version, so the repo had no honest alternative. Instead:
19
+ #
20
+ # 1. copy THIS file to .github/workflows/ci.yml,
21
+ # 2. copy the `build:` job out of ci-node.yml and paste it in alongside,
22
+ # 3. keep BOTH "Resolve … version" steps — each ecosystem resolves independently,
23
+ # and neither may be hardcoded,
24
+ # 4. stamp the file with whichever template you copied first, and say in a comment
25
+ # that the other job came from the other template.
26
+ #
27
+ # NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
28
+ #
29
+ # What it does:
30
+ # 1. Resolve the Python version from declared sources — never a hardcoded default.
31
+ # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
32
+ # 3. Install dependencies from whichever manifest the repo actually has.
33
+ # 4. Byte-compile — the cheapest possible "does it even parse" gate.
34
+ # 5. Run lint / tests only if the repo has them, so a repo without a suite is not
35
+ # forced to add placeholders to keep CI green.
36
+
37
+ name: CI
38
+
39
+ on:
40
+ push:
41
+ # Every branch, not only trunk (#384). Sessions push branches without opening a
42
+ # PR, so a trunk-only trigger leaves a candidate with no run of its own before the
43
+ # merge: its first run is the post-merge trunk run, and a red there is everyone's
44
+ # TRUNK RED instead of one implementer's hand-back (CONVENTIONS.md §4, "Branch
45
+ # CI"). '**' also covers `ship-batch/**`, the batch-landing opt-in.
46
+ #
47
+ # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
48
+ # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
49
+ # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
50
+ # runners, a runner pool, or a trunk-only label picked in `runs-on` on
51
+ # github.ref all have that capacity; keep '**' there. Trunk-only means the
52
+ # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
53
+ # dev is the trunk, so a main-only trigger runs zero checks on the branch you
54
+ # merge into, and nothing looks broken (CONVENTIONS.md §7).
55
+ branches: ['**']
56
+ pull_request:
57
+ # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
58
+ # trunk, main the release; Tier B: main only).
59
+ branches: [main, dev]
60
+ # A promotion pushed by the release workflow's token triggers no push run, so that workflow
61
+ # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
62
+ workflow_dispatch:
63
+
64
+ # One live run per branch: a new push cancels the superseded run on the same ref.
65
+ # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
66
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
67
+ # group under refs/pull/<n>/merge, apart from the branch's push runs.
68
+ # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
69
+ # may carry any name; one left off this list gets its trunk runs cancelled.
70
+ concurrency:
71
+ group: ci-${{ github.ref }}
72
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
73
+
74
+ env:
75
+ # EDIT: bump deliberately, not automatically.
76
+ GITLEAKS_VERSION: "8.30.1"
77
+ # EDIT: the importable package/directory to byte-compile. Often `src` or the app name.
78
+ PACKAGE_DIR: "."
79
+
80
+ # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
81
+ # fresh machine per job. With few self-hosted agents every job is a queue slot,
82
+ # jobs from different runs interleave, and trunk can wait behind branch runs.
83
+ # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
84
+ jobs:
85
+ gitleaks:
86
+ name: Secret scan (gitleaks)
87
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
88
+ steps:
89
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
90
+ with:
91
+ # Full history: gitleaks scans commits, not just the working tree, so a
92
+ # secret that was committed and later removed is still caught.
93
+ fetch-depth: 0
94
+ persist-credentials: false
95
+
96
+ - name: Install gitleaks (pinned release binary)
97
+ run: |
98
+ # Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
99
+ # GITLEAKS_LICENSE for repositories owned by an organization (free only for
100
+ # personal repos). The release binary itself is MIT and has no such gate.
101
+ # Repos also carry a local pre-commit gitleaks hook; this is the second layer.
102
+ # The asset is OS/arch-specific, so resolve both from uname instead of
103
+ # assuming the GitHub-hosted default: a hardcoded linux_x64 binary on a
104
+ # macOS self-hosted runner is an ELF the kernel cannot exec, and the step
105
+ # fails with exit 126 rather than anything mentioning the platform.
106
+ case "$(uname -s)" in
107
+ Darwin) os=darwin ;;
108
+ Linux) os=linux ;;
109
+ *) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
110
+ esac
111
+ case "$(uname -m)" in
112
+ arm64|aarch64) arch=arm64 ;;
113
+ x86_64|amd64) arch=x64 ;;
114
+ *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
115
+ esac
116
+ curl -sSL -o gitleaks.tar.gz \
117
+ "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
118
+ # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
119
+ # step then works on BOTH GitHub-hosted and shared self-hosted runners
120
+ # (a shared runner is infrastructure; jobs must not mutate it).
121
+ tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
122
+ chmod +x "$RUNNER_TEMP/gitleaks"
123
+ echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
124
+ rm -f gitleaks.tar.gz
125
+
126
+ - name: gitleaks detect
127
+ run: gitleaks detect --source . --no-banner
128
+
129
+ build:
130
+ name: Build (Python)
131
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
132
+ defaults:
133
+ run:
134
+ # EDIT: set to the directory holding the Python project if it is not at the root.
135
+ working-directory: .
136
+ steps:
137
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
138
+ with:
139
+ persist-credentials: false
140
+
141
+ # ---------------------------------------------------------------------------
142
+ # Toolchain resolution. Precedence, highest first:
143
+ # 1. .github/project.yml -> python: <version>
144
+ # 2. .python-version (pyenv; also what most local tooling reads)
145
+ # 3. pyproject.toml -> [project] requires-python
146
+ # 4. FAIL.
147
+ #
148
+ # NOTE what is NOT on that list: requirements.txt. It pins DEPENDENCIES, never
149
+ # the interpreter — a repo with only a requirements.txt has declared nothing
150
+ # about which Python it runs on, and this workflow will (correctly) stop and
151
+ # say so. Add `python:` to project.yml or a `.python-version`; do not paper
152
+ # over it with a hardcoded version here.
153
+ #
154
+ # There is deliberately NO fallback default. A silent default is exactly how a
155
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
156
+ # CI was green and proved nothing about what actually shipped. Python has the
157
+ # same failure with sharper edges: a minor is a real feature release, so 3.12
158
+ # vs 3.13 is not a cosmetic difference.
159
+ # ---------------------------------------------------------------------------
160
+ - name: Resolve Python version
161
+ id: toolchain
162
+ run: |
163
+ set -euo pipefail
164
+
165
+ # ">=3.13" / "~=3.12" / "3.13.1" / "3.13" -> "3.13" / "3.12" / "3.13.1"
166
+ normalise() {
167
+ printf '%s' "$1" \
168
+ | tr -d '"' \
169
+ | sed -E 's/^[^0-9]*//' \
170
+ | sed -E 's/[[:space:],].*$//' \
171
+ | sed -E 's/\.(x|\*)$//' \
172
+ | sed -E 's/[^0-9.].*$//' \
173
+ | sed -E 's/\.$//'
174
+ }
175
+
176
+ PY_VERSION=""
177
+ SOURCE=""
178
+
179
+ # 1. project.yml wins. Flat `python: 3.13` mapping; good enough, this file
180
+ # is a handful of keys by design.
181
+ if [ -f .github/project.yml ]; then
182
+ V="$(sed -nE 's/^[[:space:]]*python:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
183
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
184
+ PY_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (python:)"
185
+ fi
186
+ fi
187
+
188
+ # 2. .python-version
189
+ if [ -z "$PY_VERSION" ] && [ -f .python-version ]; then
190
+ V="$(grep -vE '^[[:space:]]*(#|$)' .python-version | head -1 | tr -d '[:space:]' || true)"
191
+ if [ -n "$V" ]; then
192
+ PY_VERSION="$(normalise "$V")"; SOURCE=".python-version"
193
+ fi
194
+ fi
195
+
196
+ # 3. pyproject.toml -> [project] requires-python. Read with a line match, not
197
+ # a TOML parser: the field is a single top-level string and the runner is
198
+ # not guaranteed to have tomllib available before setup-python has run.
199
+ if [ -z "$PY_VERSION" ] && [ -f pyproject.toml ]; then
200
+ V="$(sed -nE 's/^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' pyproject.toml | head -1 || true)"
201
+ if [ -n "$V" ]; then
202
+ PY_VERSION="$(normalise "$V")"; SOURCE="pyproject.toml (requires-python)"
203
+ fi
204
+ fi
205
+
206
+ # 4. No declared source -> stop. Do not guess.
207
+ if [ -z "$PY_VERSION" ]; then
208
+ echo "::error::No Python version is declared in this repository, and this workflow refuses to guess one."
209
+ {
210
+ echo ""
211
+ echo "Declare it in ONE of these places (checked in this order):"
212
+ echo " 1. .github/project.yml -> python: \"3.13\" (preferred: one descriptor for the whole repo)"
213
+ echo " 2. .python-version -> 3.13 (also drives local dev via pyenv)"
214
+ echo " 3. pyproject.toml -> [project] requires-python = \">=3.13\""
215
+ echo ""
216
+ echo "requirements.txt does NOT count — it pins dependencies, not the interpreter."
217
+ echo "Pick the version your DEPLOY target runs. CI on a different minor than"
218
+ echo "production proves less than you think."
219
+ } >&2
220
+ exit 1
221
+ fi
222
+
223
+ echo "python-version=$PY_VERSION" >> "$GITHUB_OUTPUT"
224
+ echo "Python $PY_VERSION (resolved from: $SOURCE)"
225
+ echo "Python **$PY_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
226
+
227
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
228
+ with:
229
+ python-version: ${{ steps.toolchain.outputs.python-version }}
230
+
231
+ - name: Install dependencies
232
+ run: |
233
+ python -m pip install --upgrade pip
234
+ # Whichever manifest the repo actually has. A packaged project (pyproject)
235
+ # installs itself so imports resolve the way they will in production;
236
+ # a plain requirements.txt service just installs its pins.
237
+ if [ -f pyproject.toml ]; then
238
+ pip install -e .
239
+ elif [ -f requirements.txt ]; then
240
+ pip install -r requirements.txt
241
+ else
242
+ echo "::warning::No pyproject.toml or requirements.txt — nothing to install."
243
+ fi
244
+
245
+ - name: Byte-compile
246
+ # The cheapest gate there is: every module parses. Catches the syntax error
247
+ # that only ever runs on a code path nobody tests.
248
+ run: python -m compileall -q "$PACKAGE_DIR"
249
+
250
+ - name: Detect optional tooling
251
+ id: tools
252
+ run: |
253
+ # EDIT: add the tools this repo uses. Each is optional so a repo without it
254
+ # is not forced to adopt one to keep CI green.
255
+ # Because a tool missing here SKIPS its step and the job still concludes
256
+ # `success`, the files installed from above and here are part of the
257
+ # instrument: `colab ship`'s cure rule refuses a branch that changes them
258
+ # while trunk is red (CONVENTIONS.md §5, cure rule condition 6, #377). Installing
259
+ # from a file this template does not name (a lockfile, a new include)?
260
+ # Extend that rule's list, or accept that the cure rule cannot see it.
261
+ if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
262
+ for t in ruff mypy pytest; do
263
+ if python -m "$t" --version >/dev/null 2>&1; then
264
+ echo "$t=true" >> "$GITHUB_OUTPUT"
265
+ else
266
+ echo "$t=false" >> "$GITHUB_OUTPUT"
267
+ echo "::notice::$t not installed — skipping."
268
+ fi
269
+ done
270
+
271
+ - name: Lint (ruff)
272
+ if: steps.tools.outputs.ruff == 'true'
273
+ run: python -m ruff check .
274
+
275
+ - name: Typecheck (mypy)
276
+ if: steps.tools.outputs.mypy == 'true'
277
+ run: python -m mypy "$PACKAGE_DIR"
278
+
279
+ - name: Test (pytest)
280
+ if: steps.tools.outputs.pytest == 'true'
281
+ run: python -m pytest -q