@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +312 -3
- package/README.vi.md +281 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +278 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- 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 }}."
|