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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13785 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +481 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
@@ -0,0 +1,540 @@
1
+ # CI (Laravel) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
5
+ # calls this file remotely and nothing will update it for you — divergence between
6
+ # your copy and the handbook is expected and fine. If you find an improvement worth
7
+ # sharing, change the handbook template too, but that is a manual, deliberate act.
8
+ #
9
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
10
+ #
11
+ # For: Laravel + Inertia + React + Vite fullstack apps with a route/type codegen step.
12
+ #
13
+ # Two things here are NOT optional, and are the whole reason this is separate from
14
+ # ci-node.yml:
15
+ #
16
+ # 1. THE SQLITE BOOTSTRAP. The Vite build runs the Laravel wayfinder plugin, which
17
+ # shells out to `php artisan wayfinder:generate`. That means the application must
18
+ # actually BOOT on the runner. Our .env.example files ship DB_CONNECTION=mysql,
19
+ # so without an override artisan tries to reach a MySQL server that does not
20
+ # exist on the runner and the build dies. We copy .env.example, rewrite the
21
+ # connection to sqlite, touch an empty database file, and generate a throwaway
22
+ # APP_KEY. This .env is disposable and never leaves the runner.
23
+ #
24
+ # 2. RUNNING WAYFINDER EXPLICITLY, before Vite. The Vite plugin swallows stderr and
25
+ # reports only "Command failed", which is unusable for debugging. Running the
26
+ # artisan command ourselves first means a codegen failure shows its real error.
27
+ #
28
+ # A third job, `migrations`, round-trips the schema (migrate -> rollback -> migrate)
29
+ # on the TEST engine (sqlite) AND the DEPLOY engine (a MariaDB/MySQL service
30
+ # container). Every case below was measured, and the engines disagree on several of
31
+ # them — so either engine alone passes a migration the other refuses:
32
+ #
33
+ # - A down() whose statements sqlite cannot run: only the sqlite leg goes red —
34
+ # and only if down() is ever executed, which nothing else in CI does.
35
+ # - A down() that does not undo its up(): the schema after the second migrate
36
+ # differs from the first, on either leg.
37
+ # - NOT NULL without a default: sqlite refuses the ALTER when the table holds
38
+ # rows; MariaDB accepts it and silently fills '' into every existing row. Only
39
+ # the sqlite leg goes red.
40
+ # - A foreign key added over orphan rows, ->change() silently dropping a modifier
41
+ # it did not restate (nullable, default, unsigned), lossy numeric conversion:
42
+ # the deploy engine's strict mode refuses these. sqlite catches some of them
43
+ # too, through its table rebuild — never count on it for the rest.
44
+ #
45
+ # The last two bullets fire ONLY when rows exist — on an empty table every one of
46
+ # them passes on both engines. Set ROUNDTRIP_SEEDER below, or they go unchecked.
47
+ #
48
+ # Not gated on RUN_TESTS: a bad migration is cheapest to fix on the branch that adds
49
+ # it, so this runs on every push, not only on main.
50
+
51
+ name: CI
52
+
53
+ on:
54
+ push:
55
+ # Every branch, not only trunk (#384). Sessions push branches without opening a
56
+ # PR, so a trunk-only trigger leaves a candidate with no run of its own before the
57
+ # merge: its first run is the post-merge trunk run, and a red there is everyone's
58
+ # TRUNK RED instead of one implementer's hand-back (CONVENTIONS.md §4, "Branch
59
+ # CI"). '**' also covers `ship-batch/**`, the batch-landing opt-in.
60
+ #
61
+ # EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
62
+ # trunk has its own lane — branch runs queue ahead of the one trunk run a merge
63
+ # waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
64
+ # runners, a runner pool, or a trunk-only label picked in `runs-on` on
65
+ # github.ref all have that capacity; keep '**' there. Trunk-only means the
66
+ # branches this repo actually has — and never drop `dev` on a Tier A or C repo:
67
+ # dev is the trunk, so a main-only trigger runs zero checks on the branch you
68
+ # merge into, and nothing looks broken (CONVENTIONS.md §7).
69
+ branches: ['**']
70
+ pull_request:
71
+ # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
72
+ # trunk, main the release; Tier B: main only).
73
+ branches: [main, dev]
74
+ # A promotion pushed by the release workflow's token triggers no push run, so that workflow
75
+ # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
76
+ workflow_dispatch:
77
+
78
+ # One live run per branch: a new push cancels the superseded run on the same ref.
79
+ # Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
80
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
81
+ # group under refs/pull/<n>/merge, apart from the branch's push runs.
82
+ # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
83
+ # may carry any name; one left off this list gets its trunk runs cancelled.
84
+ concurrency:
85
+ group: ci-${{ github.ref }}
86
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
87
+
88
+ env:
89
+ # Light CI on the dev trunk (does it build at all, ~2 min); heavy CI on main, where
90
+ # the Pest suite gates a release. On Tier C main IS production — promotion is the
91
+ # deploy — so this suite is the last gate before users, not a release formality.
92
+ # EDIT: set to a literal 'true' if this repo is Tier B (main is trunk) and you
93
+ # always want the suite.
94
+ RUN_TESTS: ${{ github.ref == 'refs/heads/main' || github.base_ref == 'main' }}
95
+ # EDIT: bump deliberately, not automatically.
96
+ GITLEAKS_VERSION: "8.30.1"
97
+ # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
98
+ VITE_APP_NAME: ""
99
+ # EDIT: arguments passed to `php artisan wayfinder:generate`.
100
+ WAYFINDER_ARGS: "--with-form"
101
+
102
+ # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
103
+ # fresh machine per job. With few self-hosted agents every job is a queue slot,
104
+ # jobs from different runs interleave, and trunk can wait behind branch runs.
105
+ # Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
106
+ jobs:
107
+ gitleaks:
108
+ name: Secret scan (gitleaks)
109
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
110
+ steps:
111
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
112
+ with:
113
+ # Full history: scan the commit log, not only the current tree.
114
+ fetch-depth: 0
115
+ persist-credentials: false
116
+
117
+ - name: Install gitleaks (pinned release binary)
118
+ run: |
119
+ # NOT gitleaks/gitleaks-action@v2 — it demands a paid GITLEAKS_LICENSE for
120
+ # organization-owned repositories. The plain release binary is MIT.
121
+ # Resolve OS/arch from uname — a hardcoded linux_x64 binary on a macOS
122
+ # self-hosted runner cannot exec, and fails as a bare exit 126.
123
+ case "$(uname -s)" in
124
+ Darwin) os=darwin ;;
125
+ Linux) os=linux ;;
126
+ *) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
127
+ esac
128
+ case "$(uname -m)" in
129
+ arm64|aarch64) arch=arm64 ;;
130
+ x86_64|amd64) arch=x64 ;;
131
+ *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
132
+ esac
133
+ curl -sSL -o gitleaks.tar.gz \
134
+ "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
135
+ # Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
136
+ # step then works on BOTH GitHub-hosted and shared self-hosted runners
137
+ # (a shared runner is infrastructure; jobs must not mutate it).
138
+ tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
139
+ chmod +x "$RUNNER_TEMP/gitleaks"
140
+ echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
141
+ rm -f gitleaks.tar.gz
142
+
143
+ - name: gitleaks detect
144
+ run: gitleaks detect --source . --no-banner
145
+
146
+ build:
147
+ name: Build (Laravel + Vite)
148
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
149
+ # Re-exported so the migrations job below resolves PHP exactly once, here.
150
+ outputs:
151
+ php-version: ${{ steps.toolchain.outputs.php-version }}
152
+ steps:
153
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
154
+ with:
155
+ persist-credentials: false
156
+
157
+ # ---------------------------------------------------------------------------
158
+ # Toolchain resolution. Precedence, highest first:
159
+ # PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
160
+ # Node: 1. .github/project.yml -> node: 2. .nvmrc, else package.json engines.node
161
+ # ...and if neither declares it, FAIL.
162
+ #
163
+ # There is deliberately NO fallback default. A silent default is exactly how a
164
+ # repo here ended up building on Node 20 in CI while deploying on Node 22 —
165
+ # CI was green and proved nothing about what actually shipped. Keep these equal
166
+ # to what the deploy target runs, or CI proves nothing.
167
+ # ---------------------------------------------------------------------------
168
+ - name: Resolve toolchain versions
169
+ id: toolchain
170
+ run: |
171
+ set -euo pipefail
172
+
173
+ # "^8.3" / ">=22.1" / "v22" / "8.4.*" -> "8.3" / "22.1" / "22" / "8.4"
174
+ normalise() {
175
+ printf '%s' "$1" \
176
+ | tr -d '"' \
177
+ | sed -E 's/^[^0-9]*//' \
178
+ | sed -E 's/[[:space:]].*$//' \
179
+ | sed -E 's/\.(x|\*)$//' \
180
+ | sed -E 's/[^0-9.].*$//' \
181
+ | sed -E 's/\.$//'
182
+ }
183
+
184
+ # Read a flat `key: value` out of .github/project.yml. That file is a
185
+ # handful of top-level keys by design, so this is sufficient.
186
+ from_project_yml() {
187
+ [ -f .github/project.yml ] || return 0
188
+ sed -nE "s/^[[:space:]]*$1:[[:space:]]*\"?([^\"#[:space:]]+)\"?.*/\1/p" .github/project.yml | head -1
189
+ }
190
+
191
+ # --- PHP ---------------------------------------------------------------
192
+ PHP_VERSION=""; PHP_SOURCE=""
193
+ V="$(from_project_yml php || true)"
194
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
195
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE=".github/project.yml (php:)"
196
+ fi
197
+ if [ -z "$PHP_VERSION" ] && [ -f composer.json ]; then
198
+ V=""
199
+ if command -v php >/dev/null 2>&1; then
200
+ V="$(php -r '$c=json_decode(file_get_contents("composer.json"),true); echo $c["require"]["php"] ?? "";' || true)"
201
+ elif command -v python3 >/dev/null 2>&1; then
202
+ V="$(python3 -c "import json;print((json.load(open('composer.json')).get('require') or {}).get('php') or '')" || true)"
203
+ elif command -v node >/dev/null 2>&1; then
204
+ V="$(node -e "try{const r=require('./composer.json').require||{};process.stdout.write(String(r.php||''))}catch(_){}" || true)"
205
+ fi
206
+ if [ -n "$V" ]; then
207
+ PHP_VERSION="$(normalise "$V")"; PHP_SOURCE="composer.json (require.php)"
208
+ fi
209
+ fi
210
+ if [ -z "$PHP_VERSION" ]; then
211
+ echo "::error::No PHP version is declared in this repository, and this workflow refuses to guess one."
212
+ {
213
+ echo "Declare it in ONE of:"
214
+ echo " 1. .github/project.yml -> php: \"8.4\" (preferred)"
215
+ echo " 2. composer.json -> \"require\": { \"php\": \"^8.4\" }"
216
+ echo "Use the version the DEPLOY target runs."
217
+ } >&2
218
+ exit 1
219
+ fi
220
+
221
+ # --- Node --------------------------------------------------------------
222
+ NODE_VERSION=""; NODE_SOURCE=""
223
+ V="$(from_project_yml node || true)"
224
+ if [ -n "$V" ] && [ "$V" != "null" ]; then
225
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".github/project.yml (node:)"
226
+ fi
227
+ if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
228
+ V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
229
+ if [ -n "$V" ]; then
230
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE=".nvmrc"
231
+ fi
232
+ fi
233
+ if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
234
+ V=""
235
+ if command -v node >/dev/null 2>&1; then
236
+ V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
237
+ elif command -v python3 >/dev/null 2>&1; then
238
+ V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
239
+ fi
240
+ if [ -n "$V" ]; then
241
+ NODE_VERSION="$(normalise "$V")"; NODE_SOURCE="package.json (engines.node)"
242
+ fi
243
+ fi
244
+ if [ -z "$NODE_VERSION" ]; then
245
+ echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
246
+ {
247
+ echo "Declare it in ONE of:"
248
+ echo " 1. .github/project.yml -> node: \"22\" (preferred)"
249
+ echo " 2. .nvmrc -> 22 or package.json -> \"engines\": { \"node\": \">=22\" }"
250
+ echo "Use the version the DEPLOY target runs."
251
+ } >&2
252
+ exit 1
253
+ fi
254
+
255
+ echo "php-version=$PHP_VERSION" >> "$GITHUB_OUTPUT"
256
+ echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
257
+ echo "PHP $PHP_VERSION (from: $PHP_SOURCE) / Node $NODE_VERSION (from: $NODE_SOURCE)"
258
+ {
259
+ echo "PHP **$PHP_VERSION** — resolved from \`$PHP_SOURCE\`"
260
+ echo ""
261
+ echo "Node **$NODE_VERSION** — resolved from \`$NODE_SOURCE\`"
262
+ } >> "$GITHUB_STEP_SUMMARY"
263
+
264
+ - name: Setup PHP
265
+ uses: shivammathur/setup-php@v2
266
+ with:
267
+ php-version: ${{ steps.toolchain.outputs.php-version }}
268
+ # sqlite3 + pdo_sqlite are what the throwaway bootstrap below runs on.
269
+ extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
270
+ coverage: none
271
+
272
+ - name: Composer install
273
+ run: |
274
+ # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
275
+ # boots the app — and the app cannot boot until the .env below exists.
276
+ # Dev dependencies are installed only when the Pest suite will run; a build-
277
+ # only job does not need them (wayfinder lives in require, not require-dev).
278
+ if [ "$RUN_TESTS" = "true" ]; then
279
+ composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
280
+ else
281
+ composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader --no-scripts
282
+ fi
283
+
284
+ - name: Prepare throwaway env for build-time codegen (wayfinder)
285
+ run: |
286
+ # See the header: .env.example ships DB_CONNECTION=mysql, but there is no
287
+ # MySQL on the runner. Rewrite to sqlite against an empty file so artisan
288
+ # boots. This .env is disposable — deploy workflows rsync with --exclude
289
+ # '.env', so it can never reach a server.
290
+ cp .env.example .env
291
+ sed -i 's/^DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
292
+ touch database/database.sqlite
293
+ php artisan key:generate --force
294
+ php artisan package:discover --ansi
295
+
296
+ echo "=== PHP version on runner ==="
297
+ php -v
298
+
299
+ echo "=== wayfinder:generate (stderr visible) ==="
300
+ # Run it here rather than letting the Vite plugin invoke it: the plugin hides
301
+ # stderr and reports only "Command failed".
302
+ php artisan wayfinder:generate $WAYFINDER_ARGS
303
+
304
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
305
+ with:
306
+ node-version: ${{ steps.toolchain.outputs.node-version }}
307
+
308
+ - name: Build frontend assets (Vite)
309
+ run: |
310
+ npm ci
311
+ npm run build
312
+
313
+ - name: Run migrations against sqlite
314
+ if: env.RUN_TESTS == 'true'
315
+ run: |
316
+ # Migrations must apply cleanly from zero. This is the cheapest way to catch
317
+ # a migration that only works against an already-populated database.
318
+ php artisan migrate --force
319
+
320
+ - name: Test (Pest)
321
+ if: env.RUN_TESTS == 'true'
322
+ run: |
323
+ if [ -f vendor/bin/pest ]; then
324
+ vendor/bin/pest --ci
325
+ elif [ -f vendor/bin/phpunit ]; then
326
+ echo "::notice::No Pest binary — falling back to PHPUnit."
327
+ vendor/bin/phpunit
328
+ else
329
+ echo "::error::RUN_TESTS is true but neither vendor/bin/pest nor vendor/bin/phpunit exists. Add a test runner, or set RUN_TESTS: false."
330
+ exit 1
331
+ fi
332
+
333
+ # ---------------------------------------------------------------------------
334
+ # Migration round-trip — see the header for what each engine catches.
335
+ #
336
+ # 1. migrate from zero (schema snapshot A)
337
+ # 2. migrate:rollback the migrations THIS change adds — every down() among them
338
+ # runs (all migrations when the change adds none)
339
+ # 3. seed only if ROUNDTRIP_SEEDER is set, and only when the change
340
+ # adds migrations: rows land at the PRE-change schema
341
+ # 4. migrate again — the new migrations land on those rows (snapshot B)
342
+ # 5. compare B must equal A — a down() that does not exactly undo its
343
+ # up() leaves a schema that differs on the second pass
344
+ #
345
+ # Steps 2-4 are the shape of a real deploy: new migrations landing on tables that
346
+ # already hold rows written before they existed. That is why the seed sits BETWEEN
347
+ # the rollback and the second migrate — rows seeded after the new migrations would
348
+ # already satisfy them (a NOT NULL column filled, a narrowed number in range) and
349
+ # every data-dependent trap would pass.
350
+ # ---------------------------------------------------------------------------
351
+ migrations:
352
+ name: Migration round-trip (${{ matrix.engine }})
353
+ needs: build
354
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
355
+ strategy:
356
+ fail-fast: false
357
+ matrix:
358
+ # EDIT: one row for the engine the tests run on, one for the engine PRODUCTION
359
+ # runs on, at production's exact version. Deploy engine is sqlite too? Delete
360
+ # the server row. MySQL, not MariaDB? Swap in the commented row. A server row
361
+ # whose version differs from production proves nothing about production.
362
+ include:
363
+ - engine: sqlite
364
+ connection: sqlite
365
+ image: '' # empty image = no service container for this row
366
+ health: 'true'
367
+ - engine: mariadb
368
+ connection: mariadb # Laravel 11+; use `mysql` on older frameworks
369
+ image: mariadb:11.4 # EDIT: the version the deploy target runs
370
+ health: healthcheck.sh --connect --innodb_initialized
371
+ # - engine: mysql
372
+ # connection: mysql
373
+ # image: mysql:8.4 # EDIT: the version the deploy target runs
374
+ # health: mysqladmin ping -h 127.0.0.1 -proot
375
+ services:
376
+ db:
377
+ image: ${{ matrix.image }}
378
+ env:
379
+ # A disposable server inside one job; this password never leaves the runner.
380
+ MYSQL_ROOT_PASSWORD: root
381
+ MYSQL_DATABASE: roundtrip
382
+ # Container port only, no fixed host port: a shared self-hosted runner may
383
+ # already listen on 3306 (README, "Self-hosted patterns"). The host port is
384
+ # read back from job.services below.
385
+ ports:
386
+ - 3306
387
+ options: >-
388
+ --health-cmd "${{ matrix.health }}"
389
+ --health-interval 5s
390
+ --health-timeout 5s
391
+ --health-retries 30
392
+ env:
393
+ # EDIT: a seeder class that leaves REPRESENTATIVE rows — NULLs where a column
394
+ # allows them, rows a new foreign key would orphan, numbers near a column's
395
+ # limits. Empty = no seeding, and the data-dependent traps in the header pass.
396
+ # It runs against the schema BEFORE this change, so it writes the way old data
397
+ # looks: raw DB::table() inserts into long-lived columns, not factories that
398
+ # fill whatever columns the models know about today.
399
+ ROUNDTRIP_SEEDER: ""
400
+ # EDIT: where this repo keeps migrations.
401
+ MIGRATIONS_PATH: database/migrations
402
+ steps:
403
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
404
+ with:
405
+ # Full history: step 3 counts the migrations this change adds against trunk.
406
+ fetch-depth: 0
407
+ persist-credentials: false
408
+
409
+ - name: Setup PHP
410
+ uses: shivammathur/setup-php@v2
411
+ with:
412
+ php-version: ${{ needs.build.outputs.php-version }}
413
+ extensions: mbstring, sqlite3, pdo_sqlite, pdo_mysql, bcmath, intl # EDIT: add what this app needs.
414
+ coverage: none
415
+
416
+ - name: Composer install
417
+ # Dev dependencies included: seeders usually build rows through factories.
418
+ run: composer install --no-interaction --prefer-dist --no-scripts
419
+
420
+ - name: Point the app at this row's engine
421
+ env:
422
+ ENGINE: ${{ matrix.engine }}
423
+ CONNECTION: ${{ matrix.connection }}
424
+ DB_SERVICE_PORT: ${{ job.services.db.ports['3306'] }}
425
+ run: |
426
+ set -euo pipefail
427
+ cp .env.example .env
428
+ php artisan key:generate --force
429
+ # Real environment variables win over .env (Laravel loads it immutably), so
430
+ # the connection is set here rather than by rewriting .env.example's lines.
431
+ # DB_URL is blanked: when set, it overrides every DB_* below.
432
+ {
433
+ echo "DB_CONNECTION=$CONNECTION"
434
+ echo "DB_URL="
435
+ } >> "$GITHUB_ENV"
436
+ if [ "$ENGINE" = sqlite ]; then
437
+ : > database/roundtrip.sqlite # truncate: a reused workspace must still start from zero
438
+ echo "DB_DATABASE=$PWD/database/roundtrip.sqlite" >> "$GITHUB_ENV"
439
+ else
440
+ {
441
+ echo "DB_HOST=127.0.0.1"
442
+ echo "DB_PORT=$DB_SERVICE_PORT"
443
+ echo "DB_DATABASE=roundtrip"
444
+ echo "DB_USERNAME=root"
445
+ echo "DB_PASSWORD=root"
446
+ } >> "$GITHUB_ENV"
447
+ fi
448
+
449
+ - name: Discover packages
450
+ run: php artisan package:discover --ansi
451
+
452
+ - name: Count the migrations this change adds
453
+ env:
454
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
455
+ run: |
456
+ set -euo pipefail
457
+ # Trunk from .github/project.yml, else the repo's default branch. A pull
458
+ # request compares against its own base instead.
459
+ trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
460
+ base_ref="origin/${GITHUB_BASE_REF:-${trunk:-$DEFAULT_BRANCH}}"
461
+ base=""
462
+ if git rev-parse -q --verify "$base_ref" >/dev/null; then
463
+ base="$(git merge-base HEAD "$base_ref")"
464
+ # On trunk itself the merge-base is HEAD: judge the commit that just landed.
465
+ if [ "$base" = "$(git rev-parse HEAD)" ]; then
466
+ base="$(git rev-parse -q --verify 'HEAD^' || true)"
467
+ fi
468
+ fi
469
+ steps=0
470
+ if [ -n "$base" ]; then
471
+ steps="$(git diff --name-only --diff-filter=A "$base" HEAD -- "$MIGRATIONS_PATH" | grep -c '\.php$' || true)"
472
+ fi
473
+ echo "ROLLBACK_STEPS=$steps" >> "$GITHUB_ENV"
474
+ if [ "$steps" -gt 0 ]; then
475
+ echo "This change adds $steps migration(s) (vs ${base_ref}); step 3 rolls back exactly those."
476
+ else
477
+ echo "This change adds no migrations (vs ${base_ref:-nothing}); step 3 rolls back all of them."
478
+ fi
479
+
480
+ - name: Write the schema snapshot script
481
+ run: |
482
+ # Tables, columns, indexes and foreign keys through the framework's own schema
483
+ # builder (Laravel 11+), so the same script reads sqlite and MariaDB/MySQL and
484
+ # needs no mysqldump/sqlite3 client on the runner. The migrations table is
485
+ # left out: its batch numbers differ between passes by design.
486
+ cat > "$RUNNER_TEMP/schema-snapshot.php" <<'PHP'
487
+ <?php
488
+ require getcwd() . '/vendor/autoload.php';
489
+ $app = require getcwd() . '/bootstrap/app.php';
490
+ $app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
491
+ $schema = Illuminate\Support\Facades\Schema::connection(null);
492
+ $m = config('database.migrations');
493
+ $skip = is_array($m) ? ($m['table'] ?? 'migrations') : ($m ?: 'migrations');
494
+ $current = method_exists($schema, 'getCurrentSchemaName') ? $schema->getCurrentSchemaName() : null;
495
+ $out = [];
496
+ foreach ($schema->getTables() as $t) {
497
+ $name = $t['name'];
498
+ if ($name === $skip || str_starts_with($name, 'sqlite_')) continue;
499
+ if ($current !== null && isset($t['schema']) && $t['schema'] !== $current) continue;
500
+ $idx = $schema->getIndexes($name);
501
+ usort($idx, fn ($a, $b) => strcmp($a['name'], $b['name']));
502
+ $fks = $schema->getForeignKeys($name);
503
+ usort($fks, fn ($a, $b) => strcmp(json_encode($a), json_encode($b)));
504
+ $out[$name] = ['columns' => $schema->getColumns($name), 'indexes' => $idx, 'foreign_keys' => $fks];
505
+ }
506
+ ksort($out);
507
+ echo json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";
508
+ PHP
509
+
510
+ - name: 1. migrate from zero
511
+ run: |
512
+ php artisan migrate --force
513
+ php "$RUNNER_TEMP/schema-snapshot.php" > "$RUNNER_TEMP/schema-a.json"
514
+
515
+ - name: 2. roll back
516
+ run: |
517
+ if [ "$ROLLBACK_STEPS" -gt 0 ]; then
518
+ php artisan migrate:rollback --step="$ROLLBACK_STEPS" --force
519
+ else
520
+ # Everything ran in one batch at step 1, so this rolls all of it back.
521
+ php artisan migrate:rollback --force
522
+ fi
523
+
524
+ - name: 3. seed rows at the pre-change schema
525
+ # No new migrations = nothing lands on the rows, and the schema is empty anyway.
526
+ if: env.ROUNDTRIP_SEEDER != '' && env.ROLLBACK_STEPS != '0'
527
+ run: php artisan db:seed --class="$ROUNDTRIP_SEEDER" --force
528
+
529
+ - name: 4. migrate again
530
+ run: |
531
+ php artisan migrate --force
532
+ php "$RUNNER_TEMP/schema-snapshot.php" > "$RUNNER_TEMP/schema-b.json"
533
+
534
+ - name: 5. the second pass must leave the same schema as the first
535
+ run: |
536
+ if ! diff -u "$RUNNER_TEMP/schema-a.json" "$RUNNER_TEMP/schema-b.json"; then
537
+ echo "::error::Schema after rollback + re-migrate differs from the first migrate (${{ matrix.engine }}). A down() does not exactly undo its up(); the diff above shows what the second pass left different."
538
+ exit 1
539
+ fi
540
+ echo "Round-trip clean on ${{ matrix.engine }}."