@futurelastic/colab-handbook 1.15.1-rc.1 → 1.16.0-rc.1

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
@@ -1456,7 +1456,7 @@ function auditRepoInner(target, ctx) {
1456
1456
  const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
1457
1457
  info.migrationRoundtrip = rt;
1458
1458
  if (!rt.length) {
1459
- 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`);
1459
+ 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 / ci-python.yml (\`colab template ci-node --roundtrip\` writes it live, #625), or declare migration-grant: human`);
1460
1460
  }
1461
1461
  }
1462
1462
  }
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.15.1-rc.1"
36
+ "version": "1.16.0-rc.1"
37
37
  }
@@ -74,10 +74,10 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
74
74
 
75
75
  | File | Copy to | For | Notes |
76
76
  |---|---|---|---|
77
- | `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. |
77
+ | `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | Resolves Node version from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. Opt-in `Migration round-trip` job — `--roundtrip` writes it live, see *Migration round-trip* below. |
78
78
  | `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
79
79
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
80
- | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
80
+ | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. Opt-in `Migration round-trip` job, as in `ci-node.yml`. |
81
81
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
82
82
  | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
83
83
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
@@ -138,6 +138,41 @@ notice back and print the run they relied on. Three things to keep in a copy:
138
138
  Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
139
139
  run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
140
140
 
141
+ ### Migration round-trip — have it from the first copy
142
+
143
+ `migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
144
+ shipped head (condition R, [CONVENTIONS §5](../CONVENTIONS.md#migration-exemption--a-narrow-door-through-no-new-migrations-opened-by-a-role-98-402)).
145
+ `ci-laravel.yml` always carries it. `ci-node.yml` and `ci-python.yml` carry it as an opt-in
146
+ block, and **the time to opt in is the copy** (#625):
147
+
148
+ ```sh
149
+ colab template ci-node --dest .github/workflows/ci.yml --roundtrip --roundtrip-apply 'npx knex migrate:latest'
150
+ colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip-apply 'alembic upgrade head'
151
+ ```
152
+
153
+ - **Why at copy.** A later branch that adds the job edits `.github/workflows/`, and a branch
154
+ that can rewrite the job grading it never passes R — so that one branch, and its migration,
155
+ ships on a human grant. In the commit that creates the workflows, there is no such branch.
156
+ - **No migrations yet?** Leave out `--roundtrip-apply`. The job is written but **skipped**
157
+ until `ROUNDTRIP_APPLY` (workflow `env`, top of the file) is set: a skipped leg never passes
158
+ R, so migrations ship on a human grant, and CI stays green — a fresh repo is not held red.
159
+ The build job prints a warning saying so. The cost while skipped: trunk does not reuse a
160
+ branch's identical-tree run (#511). A green no-op job would pass R without testing
161
+ anything; the job never becomes one.
162
+ - **What `--roundtrip` writes:** every `##>>> migration round-trip` fence uncommented (four:
163
+ the workflow env, the build job's `roundtrip` output and its warning step, the job),
164
+ `ROUNDTRIP_APPLY` from `--roundtrip-apply`, and `MIGRATIONS_PATHS` from `.github/project.yml`
165
+ `migrations:` when declared. The other edit points (Postgres image, `ROUNDTRIP_SEED`, reset
166
+ and dump commands) are still yours to walk. By hand, the template header's `sed` does the
167
+ same uncommenting.
168
+ - **Not in the heavy lane.** `--roundtrip` refuses `ci-*-heavy`: that lane never runs at a
169
+ branch's head, and R reads the shipped head.
170
+ - **`colab template` names the gap.** Copying a `ci-*` template into a repo whose policy
171
+ resolves to `reviewer` (the repo key, else this machine's value) without any round-trip job
172
+ prints a warning with the re-copy command. The audit warns the same for a declared `reviewer`.
173
+ - A copy made with `--roundtrip` differs from the template text, so `colab update` reads it as
174
+ locally edited and leaves it to you — copy-and-own, as for any edit.
175
+
141
176
  ### Migration round-trip — what the Laravel job proves, and what it cannot
142
177
 
143
178
  `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
@@ -21,7 +21,8 @@
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
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
+ # 6. Opt-in, commented: a Migration round-trip for `migration-grant: reviewer` (#494) —
25
+ # `colab template ci-node --roundtrip` writes it live at copy (#625).
25
26
  #
26
27
  # LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
27
28
  # fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
@@ -93,6 +94,14 @@ env:
93
94
  # EDIT: npm script to build. Change for monorepos or non-standard scripts. Empty, or a
94
95
  # script package.json does not declare, skips the build with a notice (#526).
95
96
  BUILD_COMMAND: "build"
97
+ ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
98
+ # # EDIT: the command that applies every pending migration to $DATABASE_URL — e.g.
99
+ # # `npx knex migrate:latest`, `npx dbmate --no-dump-schema up`, `node scripts/migrate.mjs`.
100
+ # # Empty = the round-trip job is SKIPPED, and a skipped job never passes R: migrations ship
101
+ # # on a human grant until this is set (#625). Here, not in the job, because a job-level
102
+ # # `if:` cannot read `env` — the build job hands it on as an output.
103
+ # ROUNDTRIP_APPLY: ""
104
+ ##<<< migration round-trip
96
105
 
97
106
  # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
98
107
  # fresh machine per job. With few self-hosted agents every job is a queue slot,
@@ -304,6 +313,10 @@ jobs:
304
313
  # Re-exported so the opt-in round-trip job below resolves Node exactly once, here.
305
314
  outputs:
306
315
  node-version: ${{ steps.toolchain.outputs.node-version }}
316
+ ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
317
+ # # `on` once ROUNDTRIP_APPLY is set; the round-trip job runs only then (#625).
318
+ # roundtrip: ${{ env.ROUNDTRIP_APPLY != '' && 'on' || 'off' }}
319
+ ##<<< migration round-trip
307
320
  defaults:
308
321
  run:
309
322
  # EDIT: set to the directory holding package.json if the app is not at the root.
@@ -598,6 +611,17 @@ jobs:
598
611
  else
599
612
  npm run "$BUILD_COMMAND"
600
613
  fi
614
+ ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
615
+ #
616
+ # # A skipped job prints nothing, so the reason it is skipped is said here (#625).
617
+ # - name: Migration round-trip configured?
618
+ # run: |
619
+ # if [ -z "${ROUNDTRIP_APPLY:-}" ]; then
620
+ # echo "::warning::Migration round-trip is skipped: ROUNDTRIP_APPLY is empty in .github/workflows/ci.yml. Until it is set, condition R never passes and every migration ships on a human grant (#625)."
621
+ # else
622
+ # echo "Migration round-trip: on (ROUNDTRIP_APPLY is set)."
623
+ # fi
624
+ ##<<< migration round-trip
601
625
 
602
626
  # ---------------------------------------------------------------------------
603
627
  # Migration round-trip — OPT-IN (#494). Needed for `migration-grant: reviewer`: condition R
@@ -616,20 +640,26 @@ jobs:
616
640
  # migrations with THIS checkout's code and node_modules — a runner whose migrations import
617
641
  # app code may need its own ROUNDTRIP_APPLY for that pass.
618
642
  #
619
- # To adopt: remove the leading `# ` from every line between the two fences, e.g.
643
+ # To adopt AT COPY (#625) — the same commit that creates the workflows, so no later branch has
644
+ # to edit .github/workflows/ (such a branch fails R and ships on a human grant):
645
+ # colab template ci-node --dest .github/workflows/ci.yml --roundtrip [--roundtrip-apply '<cmd>']
646
+ # By hand: remove the leading `# ` from every line between EACH pair of fences (four pairs:
647
+ # the workflow env, the build job's outputs and its last step, this job), e.g.
620
648
  # sed -i '/^ ##>>>/,/^ ##<<</ s/^ # \{0,1\}/ /' .github/workflows/ci.yml
621
- # then walk its EDIT points. Kept commented, not behind an `if:`: a job skipped on every run
622
- # would cost every repo trunk tree reuse (#511), and a no-op job that ends green would pass
623
- # R without testing anything. The branch that uncomments it edits .github/workflows/, so that
624
- # one branch fails R and ships on a human grant (a branch never grades itself).
649
+ # then walk its EDIT points. Kept commented, not merely gated: an adopted job that is skipped
650
+ # costs the repo trunk tree reuse (#511), so a repo that never runs migrations should not pay it.
651
+ # Adopted with ROUNDTRIP_APPLY still empty, the job is SKIPPED (fails closed): a skipped leg
652
+ # never passes R, and CI stays green, so a fresh repo with no migrations yet is not held red.
653
+ # A no-op job that ended green would pass R without testing anything — never make it one.
625
654
  # ---------------------------------------------------------------------------
626
655
  ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
627
656
  # migrations:
628
657
  # name: Migration round-trip (${{ matrix.engine }})
629
658
  # needs: build
630
659
  # # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
631
- # # including `dedupe`, which is skipped on every ordinary push (#418).
632
- # if: ${{ !cancelled() && needs.build.result == 'success' }}
660
+ # # including `dedupe`, which is skipped on every ordinary push (#418). `roundtrip` is `on`
661
+ # # only once ROUNDTRIP_APPLY (the workflow env, above) is set — skipped until then (#625).
662
+ # if: ${{ !cancelled() && needs.build.result == 'success' && needs.build.outputs.roundtrip == 'on' }}
633
663
  # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
634
664
  # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
635
665
  # # EDIT: measured (#572): p99 under 4 min on every adopter. Keep it well above your own p99.
@@ -654,10 +684,7 @@ jobs:
654
684
  # --health-timeout 5s
655
685
  # --health-retries 30
656
686
  # env:
657
- # # EDIT: the command that applies every pending migration to $DATABASE_URL — e.g.
658
- # # `npx knex migrate:latest`, `npx dbmate --no-dump-schema up`, `node scripts/migrate.mjs`.
659
- # # Required: an enabled round-trip that applies nothing must not pass R.
660
- # ROUNDTRIP_APPLY: ""
687
+ # # ROUNDTRIP_APPLY is in the workflow env at the top of this file (#625).
661
688
  # # EDIT: the prefixes under `migrations:` in .github/project.yml, space-separated.
662
689
  # MIGRATIONS_PATHS: "migrations/"
663
690
  # # EDIT: rows that look like OLD data (NULLs, rows a new foreign key would orphan),
@@ -33,6 +33,8 @@
33
33
  # 4. Byte-compile — the cheapest possible "does it even parse" gate.
34
34
  # 5. Run lint / tests only if the repo has them, so a repo without a suite is not
35
35
  # forced to add placeholders to keep CI green.
36
+ # 6. Opt-in, commented: a Migration round-trip for `migration-grant: reviewer` (#625) —
37
+ # `colab template ci-python --roundtrip` writes it live at copy.
36
38
  #
37
39
  # LIGHT LANE (#607): this file runs on every push and is what `colab ship` reads. Keep it
38
40
  # fast — secret scan, build, typecheck/lint, the fast tests (target: under 5 minutes).
@@ -103,6 +105,14 @@ env:
103
105
  GITLEAKS_VERSION: "8.30.1"
104
106
  # EDIT: the importable package/directory to byte-compile. Often `src` or the app name.
105
107
  PACKAGE_DIR: "."
108
+ ##>>> migration round-trip (opt-in, #625) — uncomment to the closing fence
109
+ # # EDIT: the command that applies every pending migration to $DATABASE_URL — e.g.
110
+ # # `alembic upgrade head`, `python manage.py migrate --noinput`, `yoyo apply --batch -d "$DATABASE_URL" migrations`.
111
+ # # Empty = the round-trip job is SKIPPED, and a skipped job never passes R: migrations ship
112
+ # # on a human grant until this is set (#625). Here, not in the job, because a job-level
113
+ # # `if:` cannot read `env` — the build job hands it on as an output.
114
+ # ROUNDTRIP_APPLY: ""
115
+ ##<<< migration round-trip
106
116
 
107
117
  # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
108
118
  # fresh machine per job. With few self-hosted agents every job is a queue slot,
@@ -288,6 +298,13 @@ jobs:
288
298
  timeout-minutes: 30 # a hung build must not hold the runner for the 360-minute default (#572).
289
299
  # EDIT: NOT a measured fit (#572) — one Python adopter, whose build is a byte-compile (p99
290
300
  # under 1 min). Set it well above YOUR p99 — below it a slow but healthy suite goes red.
301
+ # Re-exported so the opt-in round-trip job below resolves Python exactly once, here.
302
+ outputs:
303
+ python-version: ${{ steps.toolchain.outputs.python-version }}
304
+ ##>>> migration round-trip (opt-in, #625) — uncomment to the closing fence
305
+ # # `on` once ROUNDTRIP_APPLY is set; the round-trip job runs only then (#625).
306
+ # roundtrip: ${{ env.ROUNDTRIP_APPLY != '' && 'on' || 'off' }}
307
+ ##<<< migration round-trip
291
308
  defaults:
292
309
  run:
293
310
  # EDIT: set to the directory holding the Python project if it is not at the root.
@@ -563,3 +580,193 @@ jobs:
563
580
  if: steps.tools.outputs.pytest == 'true'
564
581
  # Everything not marked heavy; ci-heavy.yml runs the rest. Exit 5 = no test selected.
565
582
  run: python -m pytest -q -m "not heavy" || [ $? -eq 5 ]
583
+ ##>>> migration round-trip (opt-in, #625) — uncomment to the closing fence
584
+ #
585
+ # # A skipped job prints nothing, so the reason it is skipped is said here (#625).
586
+ # - name: Migration round-trip configured?
587
+ # run: |
588
+ # if [ -z "${ROUNDTRIP_APPLY:-}" ]; then
589
+ # echo "::warning::Migration round-trip is skipped: ROUNDTRIP_APPLY is empty in .github/workflows/ci.yml. Until it is set, condition R never passes and every migration ships on a human grant (#625)."
590
+ # else
591
+ # echo "Migration round-trip: on (ROUNDTRIP_APPLY is set)."
592
+ # fi
593
+ ##<<< migration round-trip
594
+
595
+ # ---------------------------------------------------------------------------
596
+ # Migration round-trip — OPT-IN (#625; ci-node's job, #494). For `migration-grant: reviewer`:
597
+ # condition R reads a passing job named "Migration round-trip…" at the shipped head (CONVENTIONS.md §5),
598
+ # and the audit warns when a repo declares `reviewer` without one. Python has no canonical
599
+ # migration runner, so the job runs YOURS, forward-only, three times — each pass's schema
600
+ # must equal the first:
601
+ #
602
+ # 1. fresh apply every migration to an empty database (schema A)
603
+ # 2. re-apply apply again on the same database — nothing changes (must equal A)
604
+ # 3. on base empty database, apply the BASE's migrations (+ ROUNDTRIP_SEED rows),
605
+ # then this change's on top (must equal A)
606
+ #
607
+ # Pass 3 is the shape of a real deploy: an edit to a migration that is already applied is
608
+ # skipped by the runner there, so its schema differs from pass 1. Pass 3 runs the base's
609
+ # migrations with THIS checkout's code and installed packages — a runner whose migrations
610
+ # import app code (Django, Alembic env.py) may need its own ROUNDTRIP_APPLY for that pass.
611
+ #
612
+ # To adopt AT COPY (#625) — the same commit that creates the workflows, so no later branch has
613
+ # to edit .github/workflows/ (such a branch fails R and ships on a human grant):
614
+ # colab template ci-python --dest .github/workflows/ci.yml --roundtrip [--roundtrip-apply '<cmd>']
615
+ # By hand: remove the leading `# ` from every line between EACH pair of fences (four pairs:
616
+ # the workflow env, the build job's outputs and its last step, this job), e.g.
617
+ # sed -i '/^ ##>>>/,/^ ##<<</ s/^ # \{0,1\}/ /' .github/workflows/ci.yml
618
+ # then walk its EDIT points. Kept commented, not merely gated: an adopted job that is skipped
619
+ # costs the repo trunk tree reuse (#511), so a repo that never runs migrations should not pay it.
620
+ # Adopted with ROUNDTRIP_APPLY still empty, the job is SKIPPED (fails closed): a skipped leg
621
+ # never passes R, and CI stays green, so a fresh repo with no migrations yet is not held red.
622
+ # A no-op job that ended green would pass R without testing anything — never make it one.
623
+ # ---------------------------------------------------------------------------
624
+ ##>>> migration round-trip (opt-in, #625) — uncomment to the closing fence
625
+ # migrations:
626
+ # name: Migration round-trip (${{ matrix.engine }})
627
+ # needs: build
628
+ # # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
629
+ # # including `dedupe`, which is skipped on every ordinary push (#418). `roundtrip` is `on`
630
+ # # only once ROUNDTRIP_APPLY (the workflow env, above) is set — skipped until then (#625).
631
+ # if: ${{ !cancelled() && needs.build.result == 'success' && needs.build.outputs.roundtrip == 'on' }}
632
+ # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
633
+ # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
634
+ # # EDIT: NOT measured for Python (#572) — ci-node's adopters ran p99 under 4 min. Keep it well above your own p99.
635
+ # strategy:
636
+ # fail-fast: false
637
+ # matrix:
638
+ # include:
639
+ # - engine: postgres
640
+ # image: postgres:17 # EDIT: the version production runs. A different one proves nothing about it.
641
+ # services:
642
+ # db:
643
+ # image: ${{ matrix.image }}
644
+ # env:
645
+ # # A disposable server inside one job; this password never leaves the runner.
646
+ # POSTGRES_PASSWORD: postgres
647
+ # # Container port only: a shared self-hosted runner may already listen on 5432.
648
+ # ports:
649
+ # - 5432
650
+ # options: >-
651
+ # --health-cmd "pg_isready -U postgres"
652
+ # --health-interval 5s
653
+ # --health-timeout 5s
654
+ # --health-retries 30
655
+ # env:
656
+ # # ROUNDTRIP_APPLY is in the workflow env at the top of this file (#625).
657
+ # # EDIT: the prefixes under `migrations:` in .github/project.yml, space-separated.
658
+ # MIGRATIONS_PATHS: "migrations/"
659
+ # # EDIT: rows that look like OLD data (NULLs, rows a new foreign key would orphan),
660
+ # # written between pass 3's two applies. Empty = no seeding.
661
+ # ROUNDTRIP_SEED: ""
662
+ # # Leave an empty database, and print its schema. The defaults run INSIDE the
663
+ # # service container, so the client always matches the server's version.
664
+ # ROUNDTRIP_RESET: >-
665
+ # docker exec "$DB_CONTAINER" psql -q -U postgres -v ON_ERROR_STOP=1
666
+ # -c 'DROP DATABASE IF EXISTS roundtrip WITH (FORCE)' -c 'CREATE DATABASE roundtrip'
667
+ # ROUNDTRIP_DUMP: >-
668
+ # docker exec "$DB_CONTAINER" pg_dump -U postgres --schema-only --no-owner --no-privileges roundtrip
669
+ # steps:
670
+ # - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
671
+ # with:
672
+ # # Full history: pass 3 reads the migrations as they were at the base.
673
+ # fetch-depth: 0
674
+ # persist-credentials: false
675
+ #
676
+ # - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
677
+ # with:
678
+ # python-version: ${{ needs.build.outputs.python-version }}
679
+ # # Same cache gate as the build job's setup-python (#571): hosted + a manifest only.
680
+ # cache: ${{ runner.environment == 'github-hosted' && hashFiles('requirements*.txt', 'pyproject.toml') != '' && 'pip' || '' }}
681
+ # cache-dependency-path: |
682
+ # requirements*.txt
683
+ # pyproject.toml
684
+ #
685
+ # - name: Install dependencies
686
+ # run: |
687
+ # python -m pip install --upgrade pip
688
+ # if [ -f pyproject.toml ]; then pip install -e .
689
+ # elif [ -f requirements.txt ]; then pip install -r requirements.txt
690
+ # fi
691
+ # # EDIT: the migration runner and the database driver, if neither manifest above installs them.
692
+ # if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
693
+ #
694
+ # - name: Round-trip
695
+ # env:
696
+ # DB_CONTAINER: ${{ job.services.db.id }}
697
+ # DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.db.ports['5432'] }}/roundtrip
698
+ # DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
699
+ # run: |
700
+ # set -euo pipefail
701
+ # if [ -z "${ROUNDTRIP_APPLY:-}" ]; then
702
+ # echo "::error::ROUNDTRIP_APPLY is empty — set the command that applies every pending migration (#494)."
703
+ # exit 1
704
+ # fi
705
+ # if [ -z "${MIGRATIONS_PATHS:-}" ]; then
706
+ # echo "::error::MIGRATIONS_PATHS is empty — copy the migrations: prefixes from .github/project.yml."
707
+ # exit 1
708
+ # fi
709
+ # # pg_dump 17.6+ writes a random key on its \restrict lines; drop them before comparing.
710
+ # dump() { eval "$ROUNDTRIP_DUMP" | { grep -vE '^\\(un)?restrict ' || true; }; }
711
+ # T="$RUNNER_TEMP"
712
+ #
713
+ # # The base: trunk from .github/project.yml (else the default branch); on trunk itself,
714
+ # # the commit before the one that just landed. A pull request compares against its base.
715
+ # trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
716
+ # base_ref="origin/${GITHUB_BASE_REF:-${trunk:-$DEFAULT_BRANCH}}"
717
+ # base=""
718
+ # if git rev-parse -q --verify "$base_ref" >/dev/null; then
719
+ # base="$(git merge-base HEAD "$base_ref")"
720
+ # [ "$base" != "$(git rev-parse HEAD)" ] || base="$(git rev-parse -q --verify 'HEAD^' || true)"
721
+ # fi
722
+ # if [ -n "$base" ]; then
723
+ # # Added, modified AND renamed (#507): an edit to an applied migration is the trap pass 3 exists for.
724
+ # # shellcheck disable=SC2086
725
+ # touched="$(git diff --name-status --diff-filter=AMR "$base" HEAD -- $MIGRATIONS_PATHS)"
726
+ # if [ -n "$touched" ]; then
727
+ # echo "This change touches migrations (vs $base_ref):"
728
+ # printf '%s\n' "$touched" | awk -F'\t' '{ print " " (substr($1,1,1) == "A" ? "added " : "modified") " " $NF }'
729
+ # else
730
+ # echo "This change adds or modifies no migrations (vs $base_ref)."
731
+ # fi
732
+ # fi
733
+ #
734
+ # # 1. Fresh: every migration applied to an empty database.
735
+ # eval "$ROUNDTRIP_RESET"
736
+ # eval "$ROUNDTRIP_APPLY"
737
+ # dump > "$T/schema-a.sql"
738
+ #
739
+ # # 2. Idempotent: applying again on the same database changes nothing.
740
+ # eval "$ROUNDTRIP_APPLY"
741
+ # dump > "$T/schema-a2.sql"
742
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-a2.sql"; then
743
+ # echo "::error::Pass 2 (re-apply): a second apply changed the schema. The runner re-ran a migration it had already applied."
744
+ # exit 1
745
+ # fi
746
+ #
747
+ # # 3. Deploy-shaped: the base's migrations first (plus old-looking rows), then this change's
748
+ # # on top. A migration that was edited after it was applied is skipped by the runner here,
749
+ # # exactly as on a real database, so the schema differs from pass 1.
750
+ # eval "$ROUNDTRIP_RESET"
751
+ # if [ -n "$base" ]; then
752
+ # for p in $MIGRATIONS_PATHS; do
753
+ # p="${p%/}"; rm -rf "$p"
754
+ # if git cat-file -e "$base:$p" 2>/dev/null; then git archive "$base" "$p" | tar -x; fi
755
+ # done
756
+ # eval "$ROUNDTRIP_APPLY"
757
+ # [ -z "${ROUNDTRIP_SEED:-}" ] || eval "$ROUNDTRIP_SEED"
758
+ # for p in $MIGRATIONS_PATHS; do
759
+ # p="${p%/}"; rm -rf "$p"
760
+ # git checkout -q HEAD -- "$p" 2>/dev/null || true
761
+ # done
762
+ # else
763
+ # echo "::notice::No base to compare against ($base_ref not found) — pass 3 applies from empty."
764
+ # fi
765
+ # eval "$ROUNDTRIP_APPLY"
766
+ # dump > "$T/schema-b.sql"
767
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-b.sql"; then
768
+ # 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."
769
+ # exit 1
770
+ # fi
771
+ # echo "Round-trip passed: fresh, re-applied, and on top of the base all give one schema."
772
+ ##<<< migration round-trip
package/tools/colab CHANGED
@@ -9681,6 +9681,7 @@ function listTemplates(templatesDir) {
9681
9681
  }
9682
9682
 
9683
9683
  const HELP_TEMPLATE = `colab template [<name>] [--dest <path>] [--repo <path>] [--force]
9684
+ [--roundtrip [--roundtrip-apply <cmd>]]
9684
9685
 
9685
9686
  Copy a colab-handbook template into a repo, STAMPED with the handbook's current version. The
9686
9687
  stamp lets the audit tell you later when the source template has moved on.
@@ -9697,6 +9698,17 @@ Options:
9697
9698
  --repo <path> target repo root for the default destination (default: git root of cwd) —
9698
9699
  *.yml templates only; a non-YAML template always requires --dest.
9699
9700
  --force overwrite an existing destination. You OWN the copy — local edits are lost.
9701
+ --roundtrip (ci-node, ci-python) write the opt-in "Migration round-trip" job LIVE, so a
9702
+ repo under migration-grant: reviewer has it from the commit that creates its
9703
+ CI (#625) — a later branch adding it edits .github/workflows/ and fails R.
9704
+ MIGRATIONS_PATHS is filled from .github/project.yml migrations: when declared.
9705
+ Until ROUNDTRIP_APPLY is set the job is SKIPPED: R never passes (migrations
9706
+ ship on a human grant) and CI stays green. Refused for a *-heavy template —
9707
+ the heavy lane never runs at the shipped head R reads. ci-laravel's job is
9708
+ always on.
9709
+ --roundtrip-apply <cmd>
9710
+ the command that applies every pending migration (implies --roundtrip), e.g.
9711
+ 'npx knex migrate:latest' or 'alembic upgrade head'.
9700
9712
 
9701
9713
  The copied file gets one stamp line:
9702
9714
  # colab-handbook: <name> @ <version>
@@ -9714,10 +9726,11 @@ copy as behind a changed template, review the diff and re-copy to re-stamp.
9714
9726
 
9715
9727
  function cmdTemplate(argv) {
9716
9728
  const opts = parseArgs(argv, {
9717
- values: { '--dest': 'dest', '--repo': 'repo' },
9718
- flags: { '--force': 'force', '-h': 'help', '--help': 'help' },
9729
+ values: { '--dest': 'dest', '--repo': 'repo', '--roundtrip-apply': 'roundtripApply' },
9730
+ flags: { '--force': 'force', '--roundtrip': 'roundtrip', '-h': 'help', '--help': 'help' },
9719
9731
  });
9720
9732
  if (opts.help) return print(HELP_TEMPLATE);
9733
+ if (opts.roundtripApply != null) opts.roundtrip = true;
9721
9734
 
9722
9735
  // The frozen copy carries tools/ only — no templates/ to copy from, and no git history to stamp
9723
9736
  // with: handbookVersion() from <COLAB_HOME> would answer 'v0', so even a copy that found its
@@ -9785,6 +9798,13 @@ function cmdTemplate(argv) {
9785
9798
  throw new UserError(`"${stem}.${ext}" has no formulaic destination — pass --dest <path> (e.g. --dest tools/${stem}.${ext}).`);
9786
9799
  }
9787
9800
 
9801
+ // #625: refused before anything is written — a heavy lane never runs at the head R reads.
9802
+ const roundtrip = require('./lib/template-roundtrip');
9803
+ if (opts.roundtrip) {
9804
+ const why = ext === 'yml' ? roundtrip.refusal(stem, fs.readFileSync(srcFile, 'utf8')) : `${stem}.${ext} is not a CI template`;
9805
+ if (why) throw new UserError(`--roundtrip: ${why}`);
9806
+ }
9807
+
9788
9808
  if (fs.existsSync(destFile) && !opts.force) {
9789
9809
  warn(`${destFile} already exists — not overwriting.`);
9790
9810
  print('Compare your copy against the current template:');
@@ -9821,6 +9841,23 @@ function cmdTemplate(argv) {
9821
9841
  if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
9822
9842
  }
9823
9843
  }
9844
+ // #625: the round-trip job written live, at copy — the commit that creates the workflows.
9845
+ const roundtripNotes = [];
9846
+ if (opts.roundtrip && roundtrip.ALWAYS_ON.has(stem)) {
9847
+ roundtripNotes.push(` round-trip: ${stem}'s "Migration round-trip" job is always on — nothing to enable.`);
9848
+ } else if (opts.roundtrip) {
9849
+ const doc = repoForCopy ? repoDescriptorDoc(repoForCopy) : null;
9850
+ const declared = migrationPaths.parseMigrationPaths(doc).paths;
9851
+ let r;
9852
+ try { r = roundtrip.enableRoundtrip(body, { apply: opts.roundtripApply, paths: declared }); } catch (e) { throw new UserError(`--roundtrip-apply: ${e.message}`); }
9853
+ body = r.text;
9854
+ roundtripNotes.push(` round-trip: wrote the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job live (${r.changes.join(', ')}).`);
9855
+ if (r.missed.length) roundtripNotes.push(` ⚠ round-trip: not found in this template, set by hand: ${r.missed.join(', ')}.`);
9856
+ if (!declared.length) roundtripNotes.push(' round-trip: no migrations: in .github/project.yml — check MIGRATIONS_PATHS (an EDIT point) names your migrations directory.');
9857
+ if (!String(opts.roundtripApply || '').trim()) {
9858
+ roundtripNotes.push(' round-trip: ROUNDTRIP_APPLY is empty, so the job is SKIPPED — R never passes and migrations ship on a human grant until you set it (workflow env, top of the file).');
9859
+ }
9860
+ }
9824
9861
  // A *.yml copy has no shebang to protect, so this is still a plain prepend at line 1 — unchanged
9825
9862
  // from before. A *.mjs copy opens with `#!/usr/bin/env node`; insertStamp puts the stamp on line
9826
9863
  // 2 instead so the shebang stays first and the file keeps running as a script (#252).
@@ -9835,6 +9872,27 @@ function cmdTemplate(argv) {
9835
9872
  print(`✓ ${stem}.${ext} @ ${version} → ${destFile}`);
9836
9873
  print(' stamped. Walk its # EDIT: markers, declare your toolchain, then commit. You own this file now.');
9837
9874
  for (const l of trunkNotes) print(l);
9875
+ for (const l of roundtripNotes) print(l);
9876
+ // #625: a repo whose policy resolves to reviewer needs the job — say which, at the copy, not at
9877
+ // the first migration's ship. Any workflow carrying it counts (the dest itself included).
9878
+ if (ext === 'yml' && /^ci-/.test(stem) && repoForCopy && !opts.roundtrip) {
9879
+ const pol = migrationGrantPolicyFor(repoDescriptorDoc(repoForCopy));
9880
+ if (pol && pol.policy === 'reviewer') {
9881
+ const wfDir = path.join(repoForCopy, '.github', 'workflows');
9882
+ let wfs = [];
9883
+ try { wfs = fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f)); } catch (_) { wfs = []; }
9884
+ const readFile = (rel) => { try { return fs.readFileSync(path.join(repoForCopy, rel), 'utf8'); } catch (_) { return null; } };
9885
+ const destText = fs.readFileSync(destFile, 'utf8');
9886
+ const live = migrationGrant.roundtripJobWorkflows({ readFile, workflows: wfs }).length
9887
+ || migrationGrant.roundtripJobWorkflows({ readFile: () => destText, workflows: ['dest'] }).length;
9888
+ if (!live) {
9889
+ const fix = roundtrip.hasRoundtripFence(fs.readFileSync(srcFile, 'utf8'))
9890
+ ? `re-copy with --force --roundtrip [--roundtrip-apply '<cmd>'] in this same commit`
9891
+ : 'add one to this repo\'s CI (templates/ci-laravel.yml, ci-node.yml and ci-python.yml carry it)';
9892
+ print(` ⚠ migration-grant resolves to reviewer here (${pol.source || 'repo'}), but no workflow has a "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job — every reviewer grant fails R. ${fix}.`);
9893
+ }
9894
+ }
9895
+ }
9838
9896
  // #526: a repo adopting a CI template usually has CI already. Both then run on every push —
9839
9897
  // name them and leave the choice to the person, never decide it here.
9840
9898
  if (ext === 'yml' && /^ci-/.test(stem) && repoForCopy) {
@@ -0,0 +1,90 @@
1
+ 'use strict';
2
+ /**
3
+ * The Migration round-trip, written live at copy (#625). Pure: text in, text out, no I/O.
4
+ *
5
+ * `migration-grant: reviewer` grants only where a job named "Migration round-trip…" passed at the
6
+ * shipped head (condition R, CONVENTIONS.md §5). ci-node and ci-python carry that job as an opt-in
7
+ * block between `##>>> migration round-trip` / `##<<< migration round-trip` fences — several pairs
8
+ * per file, since the job also needs a workflow env value and a build-job output. Adopting it on a
9
+ * LATER branch edits .github/workflows/, and such a branch fails R by construction, so the one
10
+ * branch that adopts the job ships on a human grant. Writing it at copy — the commit that creates
11
+ * the workflows — removes that branch.
12
+ *
13
+ * Fail closed: with ROUNDTRIP_APPLY empty, the build job's `roundtrip` output is `off` and the job
14
+ * is skipped. A skipped leg never passes R, and CI stays green — a repo with no migrations yet is
15
+ * not held red. A no-op job that ended green would pass R; this module never produces one.
16
+ *
17
+ * Uncommenting is the template's own recipe, `sed '/^ ##>>>/,/^ ##<<</ s/^ # \{0,1\}/ /'`,
18
+ * applied to the round-trip fences only.
19
+ */
20
+
21
+ const FENCE_OPEN = /^ ##>>> migration round-trip/;
22
+ const FENCE_CLOSE = /^ ##<<< migration round-trip/;
23
+
24
+ /** Templates whose job is always on (nothing to enable). */
25
+ const ALWAYS_ON = new Set(['ci-laravel']);
26
+
27
+ /** Is there an opt-in round-trip block in this template text? */
28
+ function hasRoundtripFence(text) {
29
+ return String(text).split('\n').some((l) => FENCE_OPEN.test(l));
30
+ }
31
+
32
+ /** A YAML single-quoted scalar: `'` doubles, nothing else escapes. */
33
+ function yamlSingleQuoted(s) {
34
+ return `'${String(s).replace(/'/g, "''")}'`;
35
+ }
36
+
37
+ /**
38
+ * Why `--roundtrip` cannot apply to template `stem`, or null when it can. `text` is the template.
39
+ * A heavy lane runs nightly and on release candidates, never on a branch head — R reads the
40
+ * shipped head, so a round-trip there could never pass it.
41
+ */
42
+ function refusal(stem, text) {
43
+ if (/-heavy$/.test(stem)) {
44
+ return `${stem} is the heavy lane: it never runs at a branch's head, and R reads the round-trip at the shipped head — so a round-trip there could never pass R. Put it in the light lane: colab template ${stem.replace(/-heavy$/, '')} --roundtrip`;
45
+ }
46
+ if (ALWAYS_ON.has(stem)) return null;
47
+ if (!hasRoundtripFence(text)) return `${stem} has no Migration round-trip block to enable`;
48
+ return null;
49
+ }
50
+
51
+ /**
52
+ * Uncomment every round-trip fence and fill the values the copy can know.
53
+ * opts: { apply?: string, paths?: string[] }. Returns { text, changes: [what], missed: [what] }.
54
+ * `apply` with a newline is refused (throws): ROUNDTRIP_APPLY is one shell line.
55
+ */
56
+ function enableRoundtrip(text, opts) {
57
+ const o = opts || {};
58
+ if (o.apply != null && /[\r\n]/.test(o.apply)) throw new Error('--roundtrip-apply must be one line');
59
+ const changes = [];
60
+ const missed = [];
61
+ let inside = false;
62
+ let fences = 0;
63
+ let out = String(text).split('\n').map((l) => {
64
+ if (FENCE_OPEN.test(l)) { inside = true; fences += 1; return l; }
65
+ if (FENCE_CLOSE.test(l)) { inside = false; return l; }
66
+ return inside ? l.replace(/^ # ?/, ' ') : l;
67
+ }).join('\n');
68
+ if (!fences) return { text: String(text), changes, missed: ['round-trip block'] };
69
+ changes.push(`uncommented ${fences} fenced block${fences === 1 ? '' : 's'}`);
70
+
71
+ const apply = o.apply == null ? '' : String(o.apply).trim();
72
+ if (apply) {
73
+ const re = /^ ROUNDTRIP_APPLY: ""$/m;
74
+ if (re.test(out)) {
75
+ out = out.replace(re, ` ROUNDTRIP_APPLY: ${yamlSingleQuoted(apply)}`);
76
+ changes.push('ROUNDTRIP_APPLY');
77
+ } else missed.push('ROUNDTRIP_APPLY');
78
+ }
79
+ const paths = (o.paths || []).filter(Boolean);
80
+ if (paths.length) {
81
+ const re = /^ MIGRATIONS_PATHS: "[^"\n]*"$/m;
82
+ if (re.test(out)) {
83
+ out = out.replace(re, ` MIGRATIONS_PATHS: ${yamlSingleQuoted(paths.join(' '))}`);
84
+ changes.push('MIGRATIONS_PATHS (from .github/project.yml migrations:)');
85
+ } else missed.push('MIGRATIONS_PATHS');
86
+ }
87
+ return { text: out, changes, missed };
88
+ }
89
+
90
+ module.exports = { FENCE_OPEN, FENCE_CLOSE, ALWAYS_ON, hasRoundtripFence, refusal, enableRoundtrip, yamlSingleQuoted };