@futurelastic/colab-handbook 1.13.0-rc.36 → 1.13.0-rc.38

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/audit/audit.mjs CHANGED
@@ -1374,11 +1374,22 @@ function auditRepo(target, ctx) {
1374
1374
  // read by three consumers). tools/lib/migration-grant.js parseGrantPolicy is the one reading, so
1375
1375
  // `colab migration-grant` and the audit cannot disagree. The value is always reported
1376
1376
  // (info.migrationGrant). An invalid value fails: the reader falls back to `human`, which is safe
1377
- // but silent. `reviewer` is clean: colab ship honours it under P+M+HEAD+R (#401).
1377
+ // but silent. `reviewer` is clean when a round-trip job exists: colab ship honours it under
1378
+ // P+M+HEAD+R (#401), and R needs that job (#494).
1378
1379
  {
1379
1380
  const pol = migrationGrant.parseGrantPolicy(cfg);
1380
1381
  info.migrationGrant = pol.policy;
1381
1382
  if (!pol.valid) fail(pol.reason);
1383
+ // #494: R needs a live `Migration round-trip…` job. Without one every reviewer grant fails R
1384
+ // (the mint and ship both refuse) and the declared policy does nothing — say so here, not at
1385
+ // ship time. A warning: the policy fails safe, back to a human grant.
1386
+ if (pol.valid && pol.policy === "reviewer") {
1387
+ const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
1388
+ info.migrationRoundtrip = rt;
1389
+ if (!rt.length) {
1390
+ warn(`migration-grant: reviewer, but no workflow in .github/workflows has a "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job — every reviewer grant fails R (the mint and colab ship refuse); adopt the job from templates/ci-laravel.yml or the opt-in block in templates/ci-node.yml, or declare migration-grant: human`);
1391
+ }
1392
+ }
1382
1393
  }
1383
1394
 
1384
1395
  // ---- ci-grant (#504) -------------------------------------------------------
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.36"
36
+ "version": "1.13.0-rc.38"
37
37
  }
@@ -73,7 +73,16 @@ on:
73
73
  # the newest run per workflow at a sha, so that second run also decided the verdict.
74
74
  # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
75
75
  # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
76
- # only branch run (CONVENTIONS.md §4, "Branch CI").
76
+ # only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
77
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
78
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
79
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
80
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
81
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
82
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
83
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
84
+ # pull_request:
85
+ # branches: ['**']
77
86
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
78
87
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
79
88
  workflow_dispatch:
@@ -86,7 +95,8 @@ on:
86
95
  # drop the second one's run before it ever started (#512).
87
96
  # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
88
97
  # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
89
- # name; one left off this list gets its trunk runs cancelled.
98
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
99
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
90
100
  concurrency:
91
101
  group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
92
102
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
@@ -142,7 +152,11 @@ jobs:
142
152
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
143
153
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
144
154
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
145
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
155
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
156
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
157
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
158
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
159
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
146
160
  dedupe:
147
161
  name: Already tested at this sha or tree?
148
162
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -165,9 +179,34 @@ jobs:
165
179
  SHA: ${{ github.sha }}
166
180
  CREATED: ${{ github.event.created }}
167
181
  REF_NAME: ${{ github.ref_name }}
182
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
168
183
  run: |
169
184
  tested=false
170
185
  cited=
186
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
187
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
188
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
189
+ reusable() {
190
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
191
+ --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
192
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
193
+ return 1
194
+ elif [ -n "$SK" ]; then
195
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
196
+ return 1
197
+ fi
198
+ }
199
+ # The cited run, as "<id> <head sha> <url> <branch>": a green push run of this workflow on
200
+ # another ref of this repo. #552: one at THIS sha first (a `ship-batch/*` run trunk
201
+ # fast-forwarded to), an exact query; else one whose commit has THIS tree (#493).
202
+ same_sha() {
203
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
204
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null | grep .
205
+ }
206
+ same_tree() {
207
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
208
+ --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\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null
209
+ }
171
210
  if ! command -v gh >/dev/null 2>&1; then
172
211
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
173
212
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -182,16 +221,15 @@ jobs:
182
221
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
183
222
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
184
223
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
185
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
186
- --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
224
+ elif ! CAND="$(same_sha || same_tree)"; then
187
225
  echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
188
226
  elif [ -z "$CAND" ]; then
189
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
227
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
190
228
  else
191
- read -r CSHA URL BR <<< "$CAND"
229
+ read -r CID CSHA URL BR <<< "$CAND"
192
230
  if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
193
231
  echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
194
- else
232
+ elif reusable "$CID"; then
195
233
  tested=true
196
234
  cited="$URL"
197
235
  echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
@@ -215,7 +253,7 @@ jobs:
215
253
  gitleaks:
216
254
  name: Secret scan (gitleaks)
217
255
  needs: dedupe
218
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
256
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
219
257
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
220
258
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
221
259
  steps:
@@ -257,7 +295,7 @@ jobs:
257
295
  build:
258
296
  name: Build (Laravel + Vite)
259
297
  needs: dedupe
260
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
298
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
261
299
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
262
300
  # Re-exported so the migrations job below resolves PHP exactly once, here.
263
301
  outputs:
@@ -20,7 +20,8 @@
20
20
  # 3. Install dependencies with the package manager the lockfile implies.
21
21
  # 4. Run typecheck / lint / test only if package.json declares those scripts, so a
22
22
  # repo without them is not forced to add placeholders to keep CI green.
23
- # 5. Build.
23
+ # 5. Build, if package.json declares the BUILD_COMMAND script.
24
+ # 6. Opt-in, commented: a Migration round-trip for `migration-grant: reviewer` (#494).
24
25
 
25
26
  name: CI
26
27
 
@@ -47,7 +48,16 @@ on:
47
48
  # the newest run per workflow at a sha, so that second run also decided the verdict.
48
49
  # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
49
50
  # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
50
- # only branch run (CONVENTIONS.md §4, "Branch CI").
51
+ # only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
52
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
53
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
54
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
55
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
56
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
57
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
58
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
59
+ # pull_request:
60
+ # branches: ['**']
51
61
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
52
62
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
53
63
  workflow_dispatch:
@@ -60,7 +70,8 @@ on:
60
70
  # drop the second one's run before it ever started (#512).
61
71
  # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
62
72
  # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
63
- # name; one left off this list gets its trunk runs cancelled.
73
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
74
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
64
75
  concurrency:
65
76
  group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
66
77
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
@@ -68,7 +79,8 @@ concurrency:
68
79
  env:
69
80
  # EDIT: bump deliberately, not automatically.
70
81
  GITLEAKS_VERSION: "8.30.1"
71
- # EDIT: npm script to build. Change for monorepos or non-standard scripts.
82
+ # EDIT: npm script to build. Change for monorepos or non-standard scripts. Empty, or a
83
+ # script package.json does not declare, skips the build with a notice (#526).
72
84
  BUILD_COMMAND: "build"
73
85
 
74
86
  # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
@@ -105,7 +117,11 @@ jobs:
105
117
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
106
118
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
107
119
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
108
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
120
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
121
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
122
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
123
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
124
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
109
125
  dedupe:
110
126
  name: Already tested at this sha or tree?
111
127
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -128,9 +144,34 @@ jobs:
128
144
  SHA: ${{ github.sha }}
129
145
  CREATED: ${{ github.event.created }}
130
146
  REF_NAME: ${{ github.ref_name }}
147
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
131
148
  run: |
132
149
  tested=false
133
150
  cited=
151
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
152
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
153
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
154
+ reusable() {
155
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
156
+ --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
157
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
158
+ return 1
159
+ elif [ -n "$SK" ]; then
160
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
161
+ return 1
162
+ fi
163
+ }
164
+ # The cited run, as "<id> <head sha> <url> <branch>": a green push run of this workflow on
165
+ # another ref of this repo. #552: one at THIS sha first (a `ship-batch/*` run trunk
166
+ # fast-forwarded to), an exact query; else one whose commit has THIS tree (#493).
167
+ same_sha() {
168
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
169
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null | grep .
170
+ }
171
+ same_tree() {
172
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
173
+ --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\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null
174
+ }
134
175
  if ! command -v gh >/dev/null 2>&1; then
135
176
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
136
177
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -145,16 +186,15 @@ jobs:
145
186
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
146
187
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
147
188
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
148
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
149
- --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
189
+ elif ! CAND="$(same_sha || same_tree)"; then
150
190
  echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
151
191
  elif [ -z "$CAND" ]; then
152
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
192
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
153
193
  else
154
- read -r CSHA URL BR <<< "$CAND"
194
+ read -r CID CSHA URL BR <<< "$CAND"
155
195
  if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
156
196
  echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
157
- else
197
+ elif reusable "$CID"; then
158
198
  tested=true
159
199
  cited="$URL"
160
200
  echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
@@ -178,7 +218,7 @@ jobs:
178
218
  gitleaks:
179
219
  name: Secret scan (gitleaks)
180
220
  needs: dedupe
181
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
221
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
182
222
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
183
223
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
184
224
  steps:
@@ -225,7 +265,7 @@ jobs:
225
265
  build:
226
266
  name: Build
227
267
  needs: dedupe
228
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
268
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
229
269
  # A repo can adopt this template before it has any application code at all —
230
270
  # a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
231
271
  # else. Unguarded, every step below still runs: "Install dependencies" warns
@@ -250,6 +290,9 @@ jobs:
250
290
  # hashFiles() would have been testing an empty directory even if it were
251
291
  # allowed.
252
292
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
293
+ # Re-exported so the opt-in round-trip job below resolves Node exactly once, here.
294
+ outputs:
295
+ node-version: ${{ steps.toolchain.outputs.node-version }}
253
296
  defaults:
254
297
  run:
255
298
  # EDIT: set to the directory holding package.json if the app is not at the root.
@@ -499,6 +542,183 @@ jobs:
499
542
  if: steps.scripts.outputs.test == 'true'
500
543
  run: npm test
501
544
 
545
+ # Optional, like the scripts above (#526): a library or a test-only repo has no `build`
546
+ # script, and a template that fails on that turns a new adopter's first trunk run red.
502
547
  - name: Build
503
548
  if: hashFiles('package.json') != ''
504
- run: npm run "$BUILD_COMMAND"
549
+ run: |
550
+ if [ -z "$BUILD_COMMAND" ]; then
551
+ echo "::notice::BUILD_COMMAND is empty — no build."
552
+ elif ! node -e "const s=(require('./package.json').scripts)||{};process.exit(s[process.env.BUILD_COMMAND]?0:1)" 2>/dev/null; then
553
+ echo "::notice::No '$BUILD_COMMAND' script in package.json — skipping the build."
554
+ else
555
+ npm run "$BUILD_COMMAND"
556
+ fi
557
+
558
+ # ---------------------------------------------------------------------------
559
+ # Migration round-trip — OPT-IN (#494). Needed for `migration-grant: reviewer`: condition R
560
+ # reads a passing job named "Migration round-trip…" at the shipped head (CONVENTIONS.md §5),
561
+ # and the audit warns when a repo declares `reviewer` without one. Node has no canonical
562
+ # migration runner, so the job runs YOURS, forward-only, three times — each pass's schema
563
+ # must equal the first:
564
+ #
565
+ # 1. fresh apply every migration to an empty database (schema A)
566
+ # 2. re-apply apply again on the same database — nothing changes (must equal A)
567
+ # 3. on base empty database, apply the BASE's migrations (+ ROUNDTRIP_SEED rows),
568
+ # then this change's on top (must equal A)
569
+ #
570
+ # Pass 3 is the shape of a real deploy: an edit to a migration that is already applied is
571
+ # skipped by the runner there, so its schema differs from pass 1. Pass 3 runs the base's
572
+ # migrations with THIS checkout's code and node_modules — a runner whose migrations import
573
+ # app code may need its own ROUNDTRIP_APPLY for that pass.
574
+ #
575
+ # To adopt: remove the leading `# ` from every line between the two fences, e.g.
576
+ # sed -i '/^ ##>>>/,/^ ##<<</ s/^ # \{0,1\}/ /' .github/workflows/ci.yml
577
+ # then walk its EDIT points. Kept commented, not behind an `if:`: a job skipped on every run
578
+ # would cost every repo trunk tree reuse (#511), and a no-op job that ends green would pass
579
+ # R without testing anything. The branch that uncomments it edits .github/workflows/, so that
580
+ # one branch fails R and ships on a human grant (a branch never grades itself).
581
+ # ---------------------------------------------------------------------------
582
+ ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
583
+ # migrations:
584
+ # name: Migration round-trip (${{ matrix.engine }})
585
+ # needs: build
586
+ # # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
587
+ # # including `dedupe`, which is skipped on every ordinary push (#418).
588
+ # if: ${{ !cancelled() && needs.build.result == 'success' }}
589
+ # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
590
+ # strategy:
591
+ # fail-fast: false
592
+ # matrix:
593
+ # include:
594
+ # - engine: postgres
595
+ # image: postgres:17 # EDIT: the version production runs. A different one proves nothing about it.
596
+ # services:
597
+ # db:
598
+ # image: ${{ matrix.image }}
599
+ # env:
600
+ # # A disposable server inside one job; this password never leaves the runner.
601
+ # POSTGRES_PASSWORD: postgres
602
+ # # Container port only: a shared self-hosted runner may already listen on 5432.
603
+ # ports:
604
+ # - 5432
605
+ # options: >-
606
+ # --health-cmd "pg_isready -U postgres"
607
+ # --health-interval 5s
608
+ # --health-timeout 5s
609
+ # --health-retries 30
610
+ # env:
611
+ # # EDIT: the command that applies every pending migration to $DATABASE_URL — e.g.
612
+ # # `npx knex migrate:latest`, `npx dbmate --no-dump-schema up`, `node scripts/migrate.mjs`.
613
+ # # Required: an enabled round-trip that applies nothing must not pass R.
614
+ # ROUNDTRIP_APPLY: ""
615
+ # # EDIT: the prefixes under `migrations:` in .github/project.yml, space-separated.
616
+ # MIGRATIONS_PATHS: "migrations/"
617
+ # # EDIT: rows that look like OLD data (NULLs, rows a new foreign key would orphan),
618
+ # # written between pass 3's two applies. Empty = no seeding.
619
+ # ROUNDTRIP_SEED: ""
620
+ # # Leave an empty database, and print its schema. The defaults run INSIDE the
621
+ # # service container, so the client always matches the server's version.
622
+ # ROUNDTRIP_RESET: >-
623
+ # docker exec "$DB_CONTAINER" psql -q -U postgres -v ON_ERROR_STOP=1
624
+ # -c 'DROP DATABASE IF EXISTS roundtrip WITH (FORCE)' -c 'CREATE DATABASE roundtrip'
625
+ # ROUNDTRIP_DUMP: >-
626
+ # docker exec "$DB_CONTAINER" pg_dump -U postgres --schema-only --no-owner --no-privileges roundtrip
627
+ # steps:
628
+ # - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
629
+ # with:
630
+ # # Full history: pass 3 reads the migrations as they were at the base.
631
+ # fetch-depth: 0
632
+ # persist-credentials: false
633
+ #
634
+ # - name: Setup Node
635
+ # uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
636
+ # with:
637
+ # node-version: ${{ needs.build.outputs.node-version }}
638
+ #
639
+ # - name: Install dependencies
640
+ # run: |
641
+ # if [ -f pnpm-lock.yaml ]; then corepack enable; pnpm install --frozen-lockfile
642
+ # elif [ -f package-lock.json ]; then npm ci
643
+ # else npm install
644
+ # fi
645
+ #
646
+ # - name: Round-trip
647
+ # env:
648
+ # DB_CONTAINER: ${{ job.services.db.id }}
649
+ # DATABASE_URL: postgres://postgres:postgres@127.0.0.1:${{ job.services.db.ports['5432'] }}/roundtrip
650
+ # DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
651
+ # run: |
652
+ # set -euo pipefail
653
+ # if [ -z "${ROUNDTRIP_APPLY:-}" ]; then
654
+ # echo "::error::ROUNDTRIP_APPLY is empty — set the command that applies every pending migration (#494)."
655
+ # exit 1
656
+ # fi
657
+ # if [ -z "${MIGRATIONS_PATHS:-}" ]; then
658
+ # echo "::error::MIGRATIONS_PATHS is empty — copy the migrations: prefixes from .github/project.yml."
659
+ # exit 1
660
+ # fi
661
+ # # pg_dump 17.6+ writes a random key on its \restrict lines; drop them before comparing.
662
+ # dump() { eval "$ROUNDTRIP_DUMP" | { grep -vE '^\\(un)?restrict ' || true; }; }
663
+ # T="$RUNNER_TEMP"
664
+ #
665
+ # # The base: trunk from .github/project.yml (else the default branch); on trunk itself,
666
+ # # the commit before the one that just landed. A pull request compares against its base.
667
+ # trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
668
+ # base_ref="origin/${GITHUB_BASE_REF:-${trunk:-$DEFAULT_BRANCH}}"
669
+ # base=""
670
+ # if git rev-parse -q --verify "$base_ref" >/dev/null; then
671
+ # base="$(git merge-base HEAD "$base_ref")"
672
+ # [ "$base" != "$(git rev-parse HEAD)" ] || base="$(git rev-parse -q --verify 'HEAD^' || true)"
673
+ # fi
674
+ # if [ -n "$base" ]; then
675
+ # # Added, modified AND renamed (#507): an edit to an applied migration is the trap pass 3 exists for.
676
+ # # shellcheck disable=SC2086
677
+ # touched="$(git diff --name-status --diff-filter=AMR "$base" HEAD -- $MIGRATIONS_PATHS)"
678
+ # if [ -n "$touched" ]; then
679
+ # echo "This change touches migrations (vs $base_ref):"
680
+ # printf '%s\n' "$touched" | awk -F'\t' '{ print " " (substr($1,1,1) == "A" ? "added " : "modified") " " $NF }'
681
+ # else
682
+ # echo "This change adds or modifies no migrations (vs $base_ref)."
683
+ # fi
684
+ # fi
685
+ #
686
+ # # 1. Fresh: every migration applied to an empty database.
687
+ # eval "$ROUNDTRIP_RESET"
688
+ # eval "$ROUNDTRIP_APPLY"
689
+ # dump > "$T/schema-a.sql"
690
+ #
691
+ # # 2. Idempotent: applying again on the same database changes nothing.
692
+ # eval "$ROUNDTRIP_APPLY"
693
+ # dump > "$T/schema-a2.sql"
694
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-a2.sql"; then
695
+ # echo "::error::Pass 2 (re-apply): a second apply changed the schema. The runner re-ran a migration it had already applied."
696
+ # exit 1
697
+ # fi
698
+ #
699
+ # # 3. Deploy-shaped: the base's migrations first (plus old-looking rows), then this change's
700
+ # # on top. A migration that was edited after it was applied is skipped by the runner here,
701
+ # # exactly as on a real database, so the schema differs from pass 1.
702
+ # eval "$ROUNDTRIP_RESET"
703
+ # if [ -n "$base" ]; then
704
+ # for p in $MIGRATIONS_PATHS; do
705
+ # p="${p%/}"; rm -rf "$p"
706
+ # if git cat-file -e "$base:$p" 2>/dev/null; then git archive "$base" "$p" | tar -x; fi
707
+ # done
708
+ # eval "$ROUNDTRIP_APPLY"
709
+ # [ -z "${ROUNDTRIP_SEED:-}" ] || eval "$ROUNDTRIP_SEED"
710
+ # for p in $MIGRATIONS_PATHS; do
711
+ # p="${p%/}"; rm -rf "$p"
712
+ # git checkout -q HEAD -- "$p" 2>/dev/null || true
713
+ # done
714
+ # else
715
+ # echo "::notice::No base to compare against ($base_ref not found) — pass 3 applies from empty."
716
+ # fi
717
+ # eval "$ROUNDTRIP_APPLY"
718
+ # dump > "$T/schema-b.sql"
719
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-b.sql"; then
720
+ # echo "::error::Pass 3 (base, then this change): the schema differs from a fresh apply. A migration already on the base was edited, or the order only works on an empty database."
721
+ # exit 1
722
+ # fi
723
+ # echo "Round-trip passed: fresh, re-applied, and on top of the base all give one schema."
724
+ ##<<< migration round-trip
@@ -61,7 +61,16 @@ on:
61
61
  # the newest run per workflow at a sha, so that second run also decided the verdict.
62
62
  # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
63
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").
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: ['**']
65
74
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
66
75
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
67
76
  workflow_dispatch:
@@ -74,7 +83,8 @@ on:
74
83
  # drop the second one's run before it ever started (#512).
75
84
  # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
76
85
  # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
77
- # name; one left off this list gets its trunk runs cancelled.
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).
78
88
  concurrency:
79
89
  group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
80
90
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
@@ -119,7 +129,11 @@ jobs:
119
129
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
120
130
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
121
131
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
122
- # 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.
123
137
  dedupe:
124
138
  name: Already tested at this sha or tree?
125
139
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -142,9 +156,34 @@ jobs:
142
156
  SHA: ${{ github.sha }}
143
157
  CREATED: ${{ github.event.created }}
144
158
  REF_NAME: ${{ github.ref_name }}
159
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
145
160
  run: |
146
161
  tested=false
147
162
  cited=
163
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
164
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
165
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
166
+ reusable() {
167
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
168
+ --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
169
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
170
+ return 1
171
+ elif [ -n "$SK" ]; then
172
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
173
+ return 1
174
+ fi
175
+ }
176
+ # The cited run, as "<id> <head sha> <url> <branch>": a green push run of this workflow on
177
+ # another ref of this repo. #552: one at THIS sha first (a `ship-batch/*` run trunk
178
+ # fast-forwarded to), an exact query; else one whose commit has THIS tree (#493).
179
+ same_sha() {
180
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
181
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null | grep .
182
+ }
183
+ same_tree() {
184
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
185
+ --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\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null
186
+ }
148
187
  if ! command -v gh >/dev/null 2>&1; then
149
188
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
150
189
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -159,16 +198,15 @@ jobs:
159
198
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
160
199
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
161
200
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
162
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
163
- --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
201
+ elif ! CAND="$(same_sha || same_tree)"; then
164
202
  echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
165
203
  elif [ -z "$CAND" ]; then
166
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
204
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
167
205
  else
168
- read -r CSHA URL BR <<< "$CAND"
206
+ read -r CID CSHA URL BR <<< "$CAND"
169
207
  if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
170
208
  echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
171
- else
209
+ elif reusable "$CID"; then
172
210
  tested=true
173
211
  cited="$URL"
174
212
  echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
@@ -192,7 +230,7 @@ jobs:
192
230
  gitleaks:
193
231
  name: Secret scan (gitleaks)
194
232
  needs: dedupe
195
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
233
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
196
234
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
197
235
  timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
198
236
  steps:
@@ -239,7 +277,7 @@ jobs:
239
277
  build:
240
278
  name: Build (Python)
241
279
  needs: dedupe
242
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
280
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
243
281
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
244
282
  defaults:
245
283
  run:
@@ -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:
package/tools/colab CHANGED
@@ -9302,6 +9302,10 @@ prepended at the top for a *.yml/*.yaml copy, since there is no shebang to prote
9302
9302
  opens with a \`#!\` shebang (a *.mjs template) gets the same stamp on its SECOND line instead —
9303
9303
  using \`//\` there, since a bare \`#\` on any other line is a JS syntax error — so the shebang
9304
9304
  still has to be line 1 for the file to run.
9305
+ A ci-* template is also written with this repo's protected refs (#526): the template names
9306
+ \`main\`/\`dev\` in concurrency and the dedupe guard; the copy names the \`trunk:\` declared in
9307
+ .github/project.yml (plus \`main\` where a promotion into main releases), and says what it wrote.
9308
+ It then lists the repo's other workflows that also run on push, for you to keep, merge or delete.
9305
9309
  These templates are NEVER called remotely — copy, edit, own. When the audit flags your
9306
9310
  copy as behind a changed template, review the diff and re-copy to re-stamp.
9307
9311
  `;
@@ -9391,7 +9395,30 @@ function cmdTemplate(argv) {
9391
9395
  warn('handbook has no tags yet — stamping @ v0. Tag the handbook, then re-copy to stamp a real version.');
9392
9396
  }
9393
9397
 
9394
- const body = fs.readFileSync(srcFile, 'utf8');
9398
+ let body = fs.readFileSync(srcFile, 'utf8');
9399
+ // #526: a CI template names its protected refs `main`/`dev` — defaults, not this repo's facts.
9400
+ // Write the repo's declared trunk (and release branch) instead, and say what changed.
9401
+ const trunkNotes = [];
9402
+ let repoForCopy = null;
9403
+ if (ext === 'yml') {
9404
+ try { repoForCopy = git.repoRoot(path.dirname(destFile)) || resolveWorkingRepo(opts); } catch (_) { repoForCopy = null; }
9405
+ }
9406
+ if (ext === 'yml' && /^ci-/.test(stem)) {
9407
+ const tt = require('./lib/template-trunk');
9408
+ let doc = null;
9409
+ if (repoForCopy) doc = repoDescriptorDoc(repoForCopy);
9410
+ const p = tt.protectedRefs(doc);
9411
+ if (!p) {
9412
+ trunkNotes.push(' trunk: no `trunk:` in .github/project.yml — the template\'s main/dev refs are left as is; walk its # EDIT: markers.');
9413
+ } else {
9414
+ const r = tt.substituteTrunk(body, p);
9415
+ body = r.text;
9416
+ trunkNotes.push(r.changes.length
9417
+ ? ` trunk: wrote ${p.refs.join(', ')} (from .github/project.yml) into: ${r.changes.join(', ')}.`
9418
+ : ` trunk: ${p.refs.join(', ')} — the template's refs already match .github/project.yml.`);
9419
+ if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
9420
+ }
9421
+ }
9395
9422
  // A *.yml copy has no shebang to protect, so this is still a plain prepend at line 1 — unchanged
9396
9423
  // from before. A *.mjs copy opens with `#!/usr/bin/env node`; insertStamp puts the stamp on line
9397
9424
  // 2 instead so the shebang stays first and the file keeps running as a script (#252).
@@ -9405,6 +9432,23 @@ function cmdTemplate(argv) {
9405
9432
  // extension) is exactly how a stem collision reads back as a false confirmation (#252).
9406
9433
  print(`✓ ${stem}.${ext} @ ${version} → ${destFile}`);
9407
9434
  print(' stamped. Walk its # EDIT: markers, declare your toolchain, then commit. You own this file now.');
9435
+ for (const l of trunkNotes) print(l);
9436
+ // #526: a repo adopting a CI template usually has CI already. Both then run on every push —
9437
+ // name them and leave the choice to the person, never decide it here.
9438
+ if (ext === 'yml' && /^ci-/.test(stem) && repoForCopy) {
9439
+ const wfDir = path.join(repoForCopy, '.github', 'workflows');
9440
+ let others = [];
9441
+ try {
9442
+ const wt = require('./lib/workflow-triggers');
9443
+ others = fs.readdirSync(wfDir)
9444
+ .filter((f) => /\.ya?ml$/.test(f) && path.join(wfDir, f) !== destFile)
9445
+ .filter((f) => { const on = wt.parseWorkflowOn(fs.readFileSync(path.join(wfDir, f), 'utf8')); return on.found && on.events.has('push'); });
9446
+ } catch (_) { others = []; }
9447
+ if (others.length) {
9448
+ print(' Other workflows here also run on push — keep each, merge it into this one, or delete it (your call):');
9449
+ for (const f of others) print(` .github/workflows/${f}`);
9450
+ }
9451
+ }
9408
9452
  return 0;
9409
9453
  }
9410
9454
 
@@ -9475,6 +9519,8 @@ function inspectRepo(entry, ctx) {
9475
9519
  try { wfs = fs.existsSync(wfDir) ? fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f)).sort() : []; }
9476
9520
  catch (_) { wfs = []; }
9477
9521
 
9522
+ // #526: a CI copy is written with this repo's refs, so pristine means "as colab template renders it here".
9523
+ const descDoc = repoDescriptorDoc(abs);
9478
9524
  for (const wf of wfs) {
9479
9525
  const rel = `.github/workflows/${wf}`;
9480
9526
  const text = read(rel);
@@ -9483,6 +9529,7 @@ function inspectRepo(entry, ctx) {
9483
9529
  const c = stamp.classifyStamped({
9484
9530
  root: ctx.handbookRoot, hb: ctx.hb, tmplNames: ctx.tmplNames,
9485
9531
  templateName: st.name, stampVersion: st.version, localText: text, comparable: true,
9532
+ render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc),
9486
9533
  });
9487
9534
  artifacts.push({ file: rel, template: st.name, applicable: c.state === 'behind', ...c });
9488
9535
  } else {
@@ -9566,10 +9613,17 @@ function entryLabel(entry) {
9566
9613
  }
9567
9614
 
9568
9615
  /** Rewrite a behind-but-pristine workflow copy as the current template, freshly stamped. */
9616
+ /** A repo's parsed .github/project.yml, or null when absent or unreadable. */
9617
+ function repoDescriptorDoc(repoAbs) {
9618
+ try { return require('./lib/yaml').parse(fs.readFileSync(path.join(repoAbs, '.github', 'project.yml'), 'utf8')) || {}; }
9619
+ catch (_) { return null; }
9620
+ }
9621
+
9569
9622
  function refreshArtifact(repo, art, ctx) {
9570
9623
  const src = path.join(ctx.templatesDir, `${art.template}.yml`);
9571
9624
  if (!fs.existsSync(src)) return { ok: false, err: `template ${art.template}.yml is not in the handbook` };
9572
- const body = fs.readFileSync(src, 'utf8');
9625
+ // Rendered exactly as `colab template <name> --force` would write it here (#526).
9626
+ const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path));
9573
9627
  const dest = path.join(repo.path, art.file);
9574
9628
  try {
9575
9629
  fs.mkdirSync(path.dirname(dest), { recursive: true });
package/tools/lib/git.js CHANGED
@@ -1203,6 +1203,12 @@ function isNewerRun(a, b) {
1203
1203
  * sha — otherwise a cancel-in-progress straggler created after the passing run would turn #92's
1204
1204
  * green back into "every run was cancelled". It still counts when it is all a workflow has.
1205
1205
  *
1206
+ * #514: `skipped` is neutral in exactly the same way. A run whose every job was skipped executed
1207
+ * nothing (a same-repo `pull_request` run gated off by a fork-PR `if:`, a `workflow_run` that
1208
+ * declined), so a newer `skipped` row never stands for a workflow that has a run that ran: push
1209
+ * `failure` + newer `skipped` reads red, push `success` + newer `skipped` reads green. A workflow
1210
+ * whose runs are ALL skipped still reads not-green, as before.
1211
+ *
1206
1212
  * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1207
1213
  * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
1208
1214
  * green (#307): it is the head, so the all-finished quantifier sees it.
@@ -1210,6 +1216,9 @@ function isNewerRun(a, b) {
1210
1216
  * Returns the heads in their original order (callers' newest-first `forSha[0]` pick relies on it)
1211
1217
  * plus the rows they superseded.
1212
1218
  */
1219
+ /** Conclusions of a run that executed nothing — never chosen over a run that did (#92, #514). */
1220
+ const NEUTRAL_RUN = new Set(['cancelled', 'skipped']);
1221
+
1213
1222
  function newestRunPerWorkflow(rows) {
1214
1223
  const best = new Map();
1215
1224
  rows.forEach((x, i) => {
@@ -1218,9 +1227,9 @@ function newestRunPerWorkflow(rows) {
1218
1227
  const cur = best.get(name);
1219
1228
  if (cur === undefined) { best.set(name, i); return; }
1220
1229
  const c = rows[cur];
1221
- const xCancelled = x.conclusion === 'cancelled';
1222
- const cCancelled = c.conclusion === 'cancelled';
1223
- if (xCancelled !== cCancelled) { if (cCancelled) best.set(name, i); return; }
1230
+ const xNeutral = NEUTRAL_RUN.has(x.conclusion);
1231
+ const cNeutral = NEUTRAL_RUN.has(c.conclusion);
1232
+ if (xNeutral !== cNeutral) { if (cNeutral) best.set(name, i); return; }
1224
1233
  if (isNewerRun(x, c)) best.set(name, i);
1225
1234
  });
1226
1235
  const heads = []; const superseded = [];
@@ -290,13 +290,28 @@ function labelNamesOf(record) {
290
290
  const SHIP_CONDITION_TAG = Object.freeze({ policy: 'P policy', marker: 'M record', head: 'HEAD', roundtrip: 'R round-trip' });
291
291
 
292
292
  /**
293
- * The CI round-trip job (#399's `templates/ci-laravel.yml`) is found by NAME PREFIX: its matrix
294
- * legs are named `Migration round-trip (<engine>)`. Nothing in project.yml names it today (#401
293
+ * The CI round-trip job (#399's `templates/ci-laravel.yml`, and #494's opt-in block in
294
+ * `templates/ci-node.yml`) is found by NAME PREFIX: its matrix legs are named
295
+ * `Migration round-trip (<engine>)`. Nothing in project.yml names it today (#401
295
296
  * risk 1) — a repo that renames the job, or has no such job, cannot pass R, and ships a migration
296
297
  * on a human grant exactly as before. STABLE: renaming the template's job breaks this reader.
297
298
  */
298
299
  const ROUNDTRIP_JOB_PREFIX = 'Migration round-trip';
299
300
 
301
+ /**
302
+ * #494 — which workflows carry a live job whose `name:` starts with ROUNDTRIP_JOB_PREFIX. A
303
+ * commented line never counts (ci-node ships its job as a commented opt-in block). `readFile(rel)`
304
+ * returns the text or null; `workflows` are file names under .github/workflows. Text-level on
305
+ * purpose — the same reading R does by job name at ship time, without a YAML parser.
306
+ */
307
+ function roundtripJobWorkflows({ readFile, workflows }) {
308
+ const re = new RegExp(`^\\s+name:\\s*['"]?${ROUNDTRIP_JOB_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
309
+ return (workflows || []).filter((wf) => {
310
+ const text = readFile(`.github/workflows/${wf}`);
311
+ return typeof text === 'string' && re.test(text);
312
+ });
313
+ }
314
+
300
315
  /**
301
316
  * R — did the live CI round-trip pass on the shipped HEAD? Pure: `jobs` is every job of every run
302
317
  * at that sha (git.ghRunJobs rows, flattened), or null when any read failed. Passes only when:
@@ -738,6 +753,8 @@ module.exports = {
738
753
  GRANT_POLICIES, parseGrantPolicy,
739
754
  // #401 — ship honours a reviewer grant
740
755
  ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
756
+ // #494 — the audit's check that R is reachable at all
757
+ roundtripJobWorkflows,
741
758
  // #457 — the mint-time checks
742
759
  REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
743
760
  };
@@ -642,7 +642,7 @@ function sameContent(a, b) {
642
642
  * so divergence is undecidable and the classification stops at current/behind.
643
643
  */
644
644
  function classifyStamped(opts) {
645
- const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames } = opts;
645
+ const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames, render = null } = opts;
646
646
 
647
647
  if (hb.untagged || !hb.hasGit) {
648
648
  return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion, to: hb.version };
@@ -675,7 +675,11 @@ function classifyStamped(opts) {
675
675
  return { state: 'n-a', reason: `cannot read templates/${templateName} at ${stampVersion} — cannot tell pristine from edited`, from: stampVersion, to: hb.version };
676
676
  }
677
677
  const expected = stampLine(templateName, stampVersion) + pristine;
678
- if (sameContent(localText, expected)) {
678
+ // #526: `colab template` writes a CI copy with the repo's own refs. `render` (when given) is
679
+ // that rendering, so such a copy still reads as pristine; the raw body still counts too (a copy
680
+ // made before #526, or in a repo whose descriptor changed since).
681
+ const rendered = typeof render === 'function' ? stampLine(templateName, stampVersion) + render(pristine) : null;
682
+ if (sameContent(localText, expected) || (rendered !== null && sameContent(localText, rendered))) {
679
683
  return { state: 'behind', reason: 'pristine copy, template changed since this stamp', from: stampVersion, to: hb.version };
680
684
  }
681
685
  return { state: 'diverged', reason: `hand-edited since it was copied @ ${stampVersion} — copy-and-own, review by hand`, from: stampVersion, to: hb.version };
@@ -0,0 +1,80 @@
1
+ 'use strict';
2
+ /**
3
+ * Trunk substitution for a copied CI template (#526). Pure: text in, text out, no I/O.
4
+ *
5
+ * The CI templates protect two refs by name — `main` and `dev` — in three places: the concurrency
6
+ * `group`, `cancel-in-progress`, and the `dedupe` guard's `if:`. Those names are the defaults of the
7
+ * two shapes a repo can have, not facts about any one repo. Copied verbatim into a repo whose trunk
8
+ * is `master`, the trunk runs become cancellable (the deadlock CONVENTIONS §4 warns about) and the
9
+ * tree-reuse guard never fires there. `colab template` knows the trunk — it is in
10
+ * `.github/project.yml` — so it writes the right refs instead of leaving an EDIT point.
11
+ *
12
+ * Which refs a repo protects:
13
+ * - one branch (trunk `main`, or any trunk on a repo with no release branch) → `[trunk]`;
14
+ * - two branches (trunk ≠ `main` where the promotion into `main` releases — exposure live or
15
+ * released, or legacy tier A/C) → `['main', trunk]`.
16
+ *
17
+ * The Laravel template's test tier also names `main` as the branch whose suite gates a release;
18
+ * on a one-branch repo that branch is the trunk, so it is rewritten too.
19
+ *
20
+ * Only the exact expression shapes the templates ship are rewritten. A copy whose shape was
21
+ * already edited is left alone and reported as `missed`, never guessed at.
22
+ */
23
+
24
+ const TEMPLATE_REFS = ['main', 'dev'];
25
+
26
+ /** The refs a repo's CI protects, from its parsed descriptor. null when no `trunk:` is declared. */
27
+ function protectedRefs(doc) {
28
+ const trunk = doc && typeof doc.trunk === 'string' && doc.trunk.trim() ? doc.trunk.trim() : null;
29
+ if (!trunk) return null;
30
+ const exposure = doc.exposure == null ? null : String(doc.exposure);
31
+ const tier = doc.tier == null ? null : String(doc.tier).toUpperCase();
32
+ const promotes = exposure === 'live' || exposure === 'released' || (exposure == null && (tier === 'A' || tier === 'C'));
33
+ const twoBranch = trunk !== 'main' && promotes;
34
+ return { trunk, twoBranch, refs: twoBranch ? ['main', trunk] : [trunk] };
35
+ }
36
+
37
+ const eq = (r) => `github.ref == 'refs/heads/${r}'`;
38
+ const ne = (r) => `github.ref != 'refs/heads/${r}'`;
39
+
40
+ /**
41
+ * Rewrite the template's `main`/`dev` refs to `p` (protectedRefs' result).
42
+ * Returns { text, changes: [what], missed: [what] }. `changes` is empty when the template's own
43
+ * refs are already right (a `dev` trunk with a `main` release branch).
44
+ */
45
+ function substituteTrunk(text, p) {
46
+ const changes = [];
47
+ const missed = [];
48
+ let out = text;
49
+ const swap = (label, from, to) => {
50
+ if (!out.includes(from)) { missed.push(label); return; }
51
+ if (from !== to) { out = out.split(from).join(to); changes.push(label); }
52
+ };
53
+ const tplEq = TEMPLATE_REFS.map(eq);
54
+ swap('concurrency group', `(${tplEq.join(' || ')}) && format(`, `(${p.refs.map(eq).join(' || ')}) && format(`);
55
+ swap('cancel-in-progress', `cancel-in-progress: \${{ ${TEMPLATE_REFS.map(ne).join(' && ')} }}`,
56
+ `cancel-in-progress: \${{ ${p.refs.map(ne).join(' && ')} }}`);
57
+ swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
58
+ // ci-laravel's test tier (only present there): the release-gating branch is the trunk on a one-branch repo.
59
+ if (!p.twoBranch && p.trunk !== 'main' && out.includes('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')) {
60
+ out = out.split('[ "$BASE_REF" = "main" ]').join(`[ "$BASE_REF" = "${p.trunk}" ]`);
61
+ out = out.split('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')
62
+ .join(`[ "$REF" = "refs/heads/${p.trunk}" ] || [ "$trunk" = "${p.trunk}" ]`);
63
+ changes.push('test tier');
64
+ }
65
+ return { text: out, changes, missed };
66
+ }
67
+
68
+ /**
69
+ * What `colab template <name>` writes for a repo whose descriptor is `doc`: the body with this
70
+ * repo's refs when `name` is a CI template and a trunk is declared, else the body unchanged.
71
+ * `colab update` uses the same rendering both to recognise a pristine copy and to refresh one, so
72
+ * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
73
+ */
74
+ function renderForRepo(name, body, doc) {
75
+ if (!/^ci-/.test(String(name || ''))) return body;
76
+ const p = protectedRefs(doc);
77
+ return p ? substituteTrunk(body, p).text : body;
78
+ }
79
+
80
+ module.exports = { TEMPLATE_REFS, protectedRefs, substituteTrunk, renderForRepo };