@futurelastic/colab-handbook 1.15.1-rc.1 → 1.16.0-rc.10
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/README.md +17 -16
- package/README.vi.md +19 -18
- package/audit/audit.mjs +6 -54
- package/package.json +1 -1
- package/templates/README.md +70 -6
- package/templates/ci-node.yml +39 -12
- package/templates/ci-python.yml +207 -0
- package/tools/colab +60 -2
- package/tools/lib/install-check.js +1 -1
- package/tools/lib/md-anchors.js +60 -0
- package/tools/lib/template-roundtrip.js +90 -0
package/README.md
CHANGED
|
@@ -21,7 +21,7 @@ colab register # adds the repo to this machine's fleet list
|
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
Then, in an agent session in that repo, run the `code-start` skill with an issue
|
|
24
|
-
number — each
|
|
24
|
+
number — each agent runtime has its own way to invoke a skill, see [*Choose your agent runtime*](#choose-your-agent-runtime).
|
|
25
25
|
With an agent at hand, the `handbook-sync` skill replaces the last three commands and also does
|
|
26
26
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
27
27
|
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
@@ -115,7 +115,7 @@ with a pointer to [#604](https://github.com/futurelastic/colab-handbook/issues/6
|
|
|
115
115
|
## Your first session
|
|
116
116
|
|
|
117
117
|
A unit of work goes round one loop. Each step is a skill, invoked by name in an
|
|
118
|
-
agent session (the syntax is the
|
|
118
|
+
agent session (the syntax is the agent runtime's — [*Choose your agent runtime*](#choose-your-agent-runtime)),
|
|
119
119
|
or followed by hand from [`skills/`](skills/).
|
|
120
120
|
|
|
121
121
|
| Step | Skill | Who runs it | What it leaves behind |
|
|
@@ -235,9 +235,9 @@ the step you are refining by its number (`code-ship` B1c, `code-sweep` §3): a
|
|
|
235
235
|
large skill is a short core plus reference files, and the core keeps every
|
|
236
236
|
step's number.
|
|
237
237
|
|
|
238
|
-
Claude Code loads the file into the skill automatically. Other
|
|
238
|
+
Claude Code loads the file into the skill automatically. Other agent runtimes get a
|
|
239
239
|
plain sentence in each skill telling the agent to read the file, which works
|
|
240
|
-
without any
|
|
240
|
+
without any runtime support. Because the file instructs agents, a change to it
|
|
241
241
|
is never treated as docs-only: it merges on `auto-trunk` or a human's go, like a
|
|
242
242
|
`CLAUDE.md` change. Rule:
|
|
243
243
|
[`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
|
|
@@ -261,11 +261,12 @@ migration hold with or without it.
|
|
|
261
261
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
|
|
262
262
|
| [`AGENTS.md`](AGENTS.md) | The entry point for AI agents — the operational distillation (EN). |
|
|
263
263
|
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
264
|
-
| [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos.
|
|
264
|
+
| [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. Optional — the handbook ships no enforcement; each file's home is the tool that runs it ([`templates/README.md`](templates/README.md#where-each-file-lives--the-handbook-ships-no-enforcement-643)). Copy it, edit it, own it; one caller, `instruction-files.yml`, is kept for compatibility. |
|
|
265
265
|
| [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Command reference: [`tools/README.md`](tools/README.md). |
|
|
266
|
-
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. What each check means: [`audit/README.md`](audit/README.md). |
|
|
266
|
+
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. The text checks stay here; the multi-repo sweep is adopter tooling and leaves once its replacement ships. What each check means: [`audit/README.md`](audit/README.md). |
|
|
267
267
|
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Plain `SKILL.md` folders; `install.sh` links them into each coding agent you choose. |
|
|
268
|
-
| [`
|
|
268
|
+
| [`guides/`](guides/) | The role guides — author, reviewer, coordinator, cure, by hand — each written as the files that role leaves for the next. The judgement only; the skills keep their names and point to their guide. |
|
|
269
|
+
| [`engines/`](engines/) | One small data file per agent runtime: where its user-level skills go, how a skill is invoked, what it supports. Adding an agent runtime is adding a file — [`engines/README.md`](engines/README.md). |
|
|
269
270
|
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
|
|
270
271
|
|
|
271
272
|
## Setting up a machine
|
|
@@ -289,12 +290,12 @@ Later moves are explicit:
|
|
|
289
290
|
A clone with uncommitted changes is never moved, and a re-run without either
|
|
290
291
|
flag keeps whatever is checked out.
|
|
291
292
|
|
|
292
|
-
### Choose your
|
|
293
|
+
### Choose your agent runtime
|
|
293
294
|
|
|
294
295
|
The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
|
|
295
296
|
coding agent that reads skills can run them. What differs is **where each
|
|
296
297
|
agent looks for them**, so the install asks. At a terminal, `./install.sh`
|
|
297
|
-
lists the
|
|
298
|
+
lists the agent runtimes it knows and lets you pick one or more, with *other: give a
|
|
298
299
|
path* last. Unattended, say it with a flag:
|
|
299
300
|
|
|
300
301
|
```sh
|
|
@@ -303,21 +304,21 @@ path* last. Unattended, say it with a flag:
|
|
|
303
304
|
./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
|
|
304
305
|
```
|
|
305
306
|
|
|
306
|
-
|
|
|
307
|
+
| Agent runtime | Skills folder | Invoke | Before the skills work there |
|
|
307
308
|
|---|---|---|---|
|
|
308
309
|
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Nothing. This user-level install **wins** over a repo's own `.claude/skills/<name>` of the same name (precedence is enterprise > personal > project), so rename a repo variant you want used. |
|
|
309
310
|
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Its default sandbox has no network, so `gh` fails: set `[sandbox_workspace_write] network_access = true` in `~/.codex/config.toml`. Values from Codex's docs; not yet verified by a clean-machine run. |
|
|
310
311
|
| anything else | `--skills-dir <path>` | the agent's own way | The agent's shell needs network access for `gh`. The folder is remembered in `~/.colab/skills-dirs`. |
|
|
311
312
|
|
|
312
|
-
A re-run with no flag and no terminal keeps every
|
|
313
|
+
A re-run with no flag and no terminal keeps every agent runtime it finds already
|
|
313
314
|
linked, so an existing machine changes nothing. Finding none, it installs for
|
|
314
|
-
Claude Code and says so. The per-
|
|
315
|
+
Claude Code and says so. The per-runtime facts live in [`engines/`](engines/),
|
|
315
316
|
one file each — that folder is the source for the table above.
|
|
316
317
|
|
|
317
318
|
| Flag | What it does |
|
|
318
319
|
|---|---|
|
|
319
|
-
| *(none)* | Symlink `skills/` into each chosen
|
|
320
|
-
| `--engine <id>[,<id>]` | Install for these
|
|
320
|
+
| *(none)* | Symlink `skills/` into each chosen agent runtime's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your agent runtime*](#choose-your-agent-runtime)). |
|
|
321
|
+
| `--engine <id>[,<id>]` | Install for these agent runtimes (`claude`, `codex` — the files in `engines/`), no question asked. |
|
|
321
322
|
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
322
323
|
| `--tools` | The `colab` CLI twice: a **symlink** at `~/.local/bin/colab` for your sessions (it prints the `PATH` line if needed), and a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services. Also creates an empty `~/.colab/state.json` if there is none. |
|
|
323
324
|
| `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
|
|
@@ -353,8 +354,8 @@ node audit/audit.mjs # a conformance report across every registered repo
|
|
|
353
354
|
colab update # stamped copies that fell behind, the frozen CLI included
|
|
354
355
|
```
|
|
355
356
|
|
|
356
|
-
`--check` reports, per
|
|
357
|
-
plus that
|
|
357
|
+
`--check` reports, per agent runtime, how many skills are linked, missing or broken,
|
|
358
|
+
plus that runtime's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
|
|
358
359
|
which commands it does not dispatch, whether the state file exists, whether
|
|
359
360
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
360
361
|
`notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
|
package/README.vi.md
CHANGED
|
@@ -20,7 +20,7 @@ colab register # đưa repo vào danh sách fleet của máy này
|
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
|
|
23
|
-
mỗi
|
|
23
|
+
mỗi agent runtime có cách gọi skill riêng, xem [*Chọn agent runtime*](#chọn-agent-runtime). Có agent
|
|
24
24
|
trong tay thì skill `handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
25
25
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
26
26
|
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
@@ -114,7 +114,7 @@ production đủ 7 ngày. Thông báo nằm ở đầu
|
|
|
114
114
|
## Phiên làm việc đầu tiên
|
|
115
115
|
|
|
116
116
|
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
|
|
117
|
-
agent (cú pháp gọi là của
|
|
117
|
+
agent (cú pháp gọi là của agent runtime — [*Chọn agent runtime*](#chọn-agent-runtime)), hoặc tự làm
|
|
118
118
|
theo bằng tay từ [`skills/`](skills/).
|
|
119
119
|
|
|
120
120
|
| Bước | Skill | Ai chạy | Để lại gì |
|
|
@@ -234,8 +234,8 @@ chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo
|
|
|
234
234
|
B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
|
|
235
235
|
chiếu, và phần lõi giữ số của mọi bước.
|
|
236
236
|
|
|
237
|
-
Claude Code tự nạp file vào skill. Các
|
|
238
|
-
skill bảo agent đọc file, cách này chạy được mà không cần
|
|
237
|
+
Claude Code tự nạp file vào skill. Các agent runtime khác có một câu thường trong mỗi
|
|
238
|
+
skill bảo agent đọc file, cách này chạy được mà không cần runtime hỗ trợ gì.
|
|
239
239
|
Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
|
|
240
240
|
docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
|
|
241
241
|
`CLAUDE.md`. Quy tắc:
|
|
@@ -260,11 +260,12 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
260
260
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
|
|
261
261
|
| [`AGENTS.md`](AGENTS.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
|
|
262
262
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
263
|
-
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt.
|
|
263
|
+
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Tuỳ chọn — handbook không kèm cơ chế cưỡng chế nào; nhà của mỗi file là công cụ chạy nó ([`templates/README.md`](templates/README.md#where-each-file-lives--the-handbook-ships-no-enforcement-643)). Copy, sửa, sở hữu; riêng một caller, `instruction-files.yml`, được giữ để tương thích. |
|
|
264
264
|
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
|
|
265
|
-
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
265
|
+
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Các check văn bản ở lại đây; phần quét nhiều repo là công cụ của bên adopt và sẽ rời đi khi bản thay thế ra mắt. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
266
266
|
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). Là các thư mục `SKILL.md` thuần; `install.sh` link chúng vào từng coding agent bạn chọn. |
|
|
267
|
-
| [`
|
|
267
|
+
| [`guides/`](guides/) | Các hướng dẫn theo vai trò — author, reviewer, coordinator, cure, by hand — mỗi bản viết dưới dạng các file vai trò đó để lại cho bước sau. Chỉ phần phán đoán; các skill giữ nguyên tên và trỏ tới hướng dẫn của mình. |
|
|
268
|
+
| [`engines/`](engines/) | Mỗi agent runtime một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm agent runtime là thêm một file — [`engines/README.md`](engines/README.md). |
|
|
268
269
|
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
|
|
269
270
|
|
|
270
271
|
## Cài đặt máy
|
|
@@ -288,12 +289,12 @@ sau đều phải chủ động:
|
|
|
288
289
|
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
289
290
|
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
290
291
|
|
|
291
|
-
### Chọn
|
|
292
|
+
### Chọn agent runtime
|
|
292
293
|
|
|
293
294
|
Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
|
|
294
295
|
agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
|
|
295
296
|
skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
|
|
296
|
-
|
|
297
|
+
agent runtime nó biết và cho bạn chọn một hoặc nhiều, lựa chọn cuối là *other: give a
|
|
297
298
|
path*. Chạy không người trông thì nói bằng flag:
|
|
298
299
|
|
|
299
300
|
```sh
|
|
@@ -302,21 +303,21 @@ path*. Chạy không người trông thì nói bằng flag:
|
|
|
302
303
|
./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
|
|
303
304
|
```
|
|
304
305
|
|
|
305
|
-
|
|
|
306
|
+
| Agent runtime | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
|
|
306
307
|
|---|---|---|---|
|
|
307
308
|
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Không cần gì. Bản cài cấp user này **thắng** `.claude/skills/<name>` cùng tên của repo (thứ tự ưu tiên là enterprise > personal > project), nên muốn dùng bản của repo thì đổi tên nó. |
|
|
308
309
|
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Sandbox mặc định không có mạng nên `gh` lỗi: đặt `[sandbox_workspace_write] network_access = true` trong `~/.codex/config.toml`. Số liệu lấy từ tài liệu của Codex; chưa được xác minh bằng một lần chạy trên máy sạch. |
|
|
309
310
|
| agent khác | `--skills-dir <path>` | theo cách của agent | Shell của agent cần có mạng cho `gh`. Thư mục được ghi nhớ trong `~/.colab/skills-dirs`. |
|
|
310
311
|
|
|
311
|
-
Chạy lại không flag và không có terminal thì giữ mọi
|
|
312
|
-
sẵn, nên máy đã cài không thay đổi gì. Không thấy
|
|
313
|
-
Code và nói rõ điều đó. Thông tin từng
|
|
314
|
-
mỗi
|
|
312
|
+
Chạy lại không flag và không có terminal thì giữ mọi agent runtime đã thấy được link
|
|
313
|
+
sẵn, nên máy đã cài không thay đổi gì. Không thấy agent runtime nào thì cài cho Claude
|
|
314
|
+
Code và nói rõ điều đó. Thông tin từng agent runtime nằm trong [`engines/`](engines/),
|
|
315
|
+
mỗi agent runtime một file — thư mục đó là nguồn của bảng trên.
|
|
315
316
|
|
|
316
317
|
| Flag | Làm gì |
|
|
317
318
|
|---|---|
|
|
318
|
-
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng
|
|
319
|
-
| `--engine <id>[,<id>]` | Cài cho các
|
|
319
|
+
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng agent runtime đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn agent runtime*](#chọn-agent-runtime)). |
|
|
320
|
+
| `--engine <id>[,<id>]` | Cài cho các agent runtime này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
|
|
320
321
|
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
321
322
|
| `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
|
|
322
323
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
@@ -351,8 +352,8 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
|
351
352
|
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
352
353
|
```
|
|
353
354
|
|
|
354
|
-
`--check` báo theo từng
|
|
355
|
-
các lưu ý riêng của
|
|
355
|
+
`--check` báo theo từng agent runtime: bao nhiêu skill đã link, thiếu hay hỏng, kèm
|
|
356
|
+
các lưu ý riêng của runtime đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
|
|
356
357
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
357
358
|
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
|
|
358
359
|
thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
package/audit/audit.mjs
CHANGED
|
@@ -91,6 +91,8 @@ const stamp = require("../tools/lib/stamp.js");
|
|
|
91
91
|
const { missingConventionLabels, staleConventionDescriptions, MINIMAL_LABEL_NAMES } = require("../tools/lib/labels.js");
|
|
92
92
|
// #393: "adopted locally, not committed" — one classifier, shared with `colab adopt --local`.
|
|
93
93
|
const { localAdoptionState } = require("../tools/lib/local-adopt.js");
|
|
94
|
+
// #158 heading slugs, shared with the rule-inventory check (#632).
|
|
95
|
+
const { collectHeadingSlugs } = require("../tools/lib/md-anchors.js");
|
|
94
96
|
// #144's authority-flip precedence ladder — shared with `tools/colab` for the same reason
|
|
95
97
|
// every other cross-tool reading in this file is: two implementations of "which key governs"
|
|
96
98
|
// is exactly the two-places-drift disease this handbook exists to kill.
|
|
@@ -1456,7 +1458,7 @@ function auditRepoInner(target, ctx) {
|
|
|
1456
1458
|
const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
|
|
1457
1459
|
info.migrationRoundtrip = rt;
|
|
1458
1460
|
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`);
|
|
1461
|
+
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
1462
|
}
|
|
1461
1463
|
}
|
|
1462
1464
|
}
|
|
@@ -2505,59 +2507,9 @@ function splitDerivedSpans(text) {
|
|
|
2505
2507
|
return { authoredLines, malformed };
|
|
2506
2508
|
}
|
|
2507
2509
|
|
|
2508
|
-
//
|
|
2509
|
-
//
|
|
2510
|
-
//
|
|
2511
|
-
// project.schema.md, skills/handbook-sync/SKILL.md, tools/README.md) — every one of
|
|
2512
|
-
// them resolves under it. Not a general markdown-heading parser: it does not need to be,
|
|
2513
|
-
// because the only headings it is ever asked to slugify are the ones already governing
|
|
2514
|
-
// the links this check exists to validate.
|
|
2515
|
-
function slugifyHeading(text) {
|
|
2516
|
-
return text
|
|
2517
|
-
.replace(/`([^`]*)`/g, "$1") // code spans contribute their literal text, not backticks
|
|
2518
|
-
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) contributes only the text
|
|
2519
|
-
.trim()
|
|
2520
|
-
.replace(/#+$/, "") // a trailing "##" some repos use to mark a self-anchor
|
|
2521
|
-
.toLowerCase()
|
|
2522
|
-
// strip punctuation, keep Unicode letters/digits, underscore, hyphens/spaces -- NOT
|
|
2523
|
-
// collapsed. `\w` is ASCII-only ([A-Za-z0-9_]); GitHub's real slugifier keeps Unicode
|
|
2524
|
-
// letters (Vietnamese, Japanese, accented Latin, ...), so `\w` alone silently deleted
|
|
2525
|
-
// them and produced a slug GitHub never renders (#280). `\p{L}`/`\p{N}` (with the `/u`
|
|
2526
|
-
// flag) widen letter/digit matching to Unicode while `_` stays its own explicit member
|
|
2527
|
-
// of the class -- it must NOT be folded into `\p{L}`/`\p{N}`, because the very next
|
|
2528
|
-
// step below (`.replace(/[ _]/g, "-")`) turns underscores into hyphens and needs them
|
|
2529
|
-
// to survive this line to do it; the issue's own one-line suggestion dropped `_` from
|
|
2530
|
-
// the class and would have silently broken every underscored heading slug.
|
|
2531
|
-
.replace(/[^\p{L}\p{N}_\- ]+/gu, "")
|
|
2532
|
-
.trim()
|
|
2533
|
-
// Each space/underscore becomes its OWN hyphen -- never collapsed. GitHub does not
|
|
2534
|
-
// merge runs: a heading like "tier -- required" strips the em-dash but keeps both
|
|
2535
|
-
// spaces around where it was, producing "tier--required" (double hyphen), and every
|
|
2536
|
-
// link already written against a real heading in this repo is punctuated that way.
|
|
2537
|
-
// Collapsing here silently breaks every one of them.
|
|
2538
|
-
.replace(/[ _]/g, "-");
|
|
2539
|
-
}
|
|
2540
|
-
|
|
2541
|
-
// Every heading in `text`, in document order, mapped to its resolved slug — including
|
|
2542
|
-
// GitHub's duplicate-slug suffixing (`-1`, `-2`, … in heading order, not alphabetical).
|
|
2543
|
-
// Fenced code blocks are skipped so a `#` inside a code sample is never read as a heading.
|
|
2544
|
-
function collectHeadingSlugs(text) {
|
|
2545
|
-
const slugs = new Set();
|
|
2546
|
-
const seen = new Map(); // base slug -> next suffix to try
|
|
2547
|
-
let inFence = false;
|
|
2548
|
-
for (const line of text.split("\n")) {
|
|
2549
|
-
if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
|
|
2550
|
-
if (inFence) continue;
|
|
2551
|
-
const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
|
|
2552
|
-
if (!m) continue;
|
|
2553
|
-
const base = slugifyHeading(m[1]);
|
|
2554
|
-
if (!base) continue;
|
|
2555
|
-
const n = seen.get(base) ?? 0;
|
|
2556
|
-
seen.set(base, n + 1);
|
|
2557
|
-
slugs.add(n === 0 ? base : `${base}-${n}`);
|
|
2558
|
-
}
|
|
2559
|
-
return slugs;
|
|
2560
|
-
}
|
|
2510
|
+
// slugifyHeading + collectHeadingSlugs live in tools/lib/md-anchors.js (#632) — one slugifier,
|
|
2511
|
+
// shared with scripts/check-rule-inventory.mjs, so an inventory `dest#anchor` and a doc link
|
|
2512
|
+
// cannot disagree about what a heading's anchor is.
|
|
2561
2513
|
|
|
2562
2514
|
// Every `](target#fragment)` markdown link, repo-relative to the file that carries it.
|
|
2563
2515
|
// `target` is `""` for a same-file link (`[…](#slug)`); anything already resolved by the
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -2,11 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
Starting points you **copy into your own repo**. That is the entire model.
|
|
4
4
|
|
|
5
|
-
> **These are NOT called remotely.**
|
|
6
|
-
>
|
|
5
|
+
> **These are NOT called remotely — with one exception.** `instruction-files.yml` is a caller:
|
|
6
|
+
> its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
|
|
7
|
+
> kept for compatibility — see *Where each file lives* below). Every other file here is copied,
|
|
8
|
+
> not called. (`dist-refs.yml` is a
|
|
7
9
|
> `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
|
|
8
10
|
> `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
|
|
9
|
-
> handbook told repos to call shared workflows; that was reversed. Every workflow now
|
|
11
|
+
> handbook told repos to call shared workflows; that was reversed. Every other workflow now
|
|
10
12
|
> lives, in full, inside the repo that runs it. You copy the file, you edit it, **you
|
|
11
13
|
> own it.** Divergence between your copy and this template is expected — a shared
|
|
12
14
|
> workflow that silently changes under a hundred repos is the failure mode we are
|
|
@@ -70,14 +72,38 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
|
|
|
70
72
|
light templates show a commented `paths-ignore` for docs as an option; the old in-workflow
|
|
71
73
|
docs-only guard is gone.
|
|
72
74
|
|
|
75
|
+
## Where each file lives — the handbook ships no enforcement (#643)
|
|
76
|
+
|
|
77
|
+
Every file in this folder is an **optional starting file**: copy it if it helps, change it as
|
|
78
|
+
you like, or write your own. The handbook states rules; the tool that runs a file is what
|
|
79
|
+
enforces anything, and that tool is the file's home. Where the runner is still a `colab`
|
|
80
|
+
command in this repo, the file stays here until that command's replacement ships — code moves
|
|
81
|
+
only after its replacement exists (epic #631), and a file that moves keeps its path here with a
|
|
82
|
+
header naming its new home ([`docs/compat-surfaces.md`](../docs/compat-surfaces.md)).
|
|
83
|
+
|
|
84
|
+
| File | Runs it today | Home |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `ci-node.yml`, `ci-python.yml`, `ci-laravel.yml` (with the #625 `Migration round-trip` job), `ci-*-heavy.yml` | your forge's CI; `colab ship` / `promote` read or dispatch the runs; `colab template --roundtrip` writes the round-trip job | the adopter's CI layer; until it ships (#608), an optional starting file here |
|
|
87
|
+
| `release-tag.yml`, `release-auto.yml` | your forge's CI; `release-auto.yml` runs `colab release cut` / `finalize --auto` | the release commands' new home (#608); an optional starting file here until then |
|
|
88
|
+
| `dist-refs.yml`, `npx-launcher.mjs`, `npx-service.mjs` | your own release workflow and package `bin` | stays here, as an optional starting file |
|
|
89
|
+
| `deploy-xserver.yml`, `deploy-container.yml`, `deploy-container-run.mjs`, `deploy-adapter-portainer.mjs` | your repo's deploy workflow | the adopter's deploy tooling; here as an optional starting file |
|
|
90
|
+
| `pre-push-guard` | git, honouring `COLAB_SHIP=1` from `colab ship` | the tool that lands branches (#608); an optional starting file here until then |
|
|
91
|
+
| `pre-commit-dispatch`, `pre-commit-identity`, `identity-vocabulary.example` | git (this repo's own `.githooks/` run them in place) | stays here, as an optional starting file |
|
|
92
|
+
| `pre-commit-instruction-files`, `instruction-files.yml` | `colab instruction-files`; the reusable workflow in this repo | the `colab instruction-files` command; the reusable workflow is the one remote call this folder keeps, for compatibility |
|
|
93
|
+
| `docs-lint.mjs`, `docs-lint.yml`, `branch-name.yml` | your CI (advisory or opt-in); `code-wrap`'s docs step | stays here, as an optional starting file |
|
|
94
|
+
| `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
|
|
95
|
+
|
|
96
|
+
Nothing in this table changes what a copied file does. A stamp, a drift report or a `colab`
|
|
97
|
+
check that reads one of these files is that tool's behaviour, documented with the tool.
|
|
98
|
+
|
|
73
99
|
## What each template is for
|
|
74
100
|
|
|
75
101
|
| File | Copy to | For | Notes |
|
|
76
102
|
|---|---|---|---|
|
|
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. |
|
|
103
|
+
| `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
104
|
| `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
105
|
| `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. |
|
|
106
|
+
| `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
107
|
| `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
108
|
| `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
109
|
| `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,9 +164,44 @@ notice back and print the run they relied on. Three things to keep in a copy:
|
|
|
138
164
|
Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
|
|
139
165
|
run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
|
|
140
166
|
|
|
167
|
+
### Migration round-trip — have it from the first copy
|
|
168
|
+
|
|
169
|
+
`migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
|
|
170
|
+
shipped head (condition R, [CONVENTIONS §5](../CONVENTIONS.md#migration-exemption--a-narrow-door-through-no-new-migrations-opened-by-a-role-98-402)).
|
|
171
|
+
`ci-laravel.yml` always carries it. `ci-node.yml` and `ci-python.yml` carry it as an opt-in
|
|
172
|
+
block, and **the time to opt in is the copy** (#625):
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
colab template ci-node --dest .github/workflows/ci.yml --roundtrip --roundtrip-apply 'npx knex migrate:latest'
|
|
176
|
+
colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip-apply 'alembic upgrade head'
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
- **Why at copy.** A later branch that adds the job edits `.github/workflows/`, and a branch
|
|
180
|
+
that can rewrite the job grading it never passes R — so that one branch, and its migration,
|
|
181
|
+
ships on a human grant. In the commit that creates the workflows, there is no such branch.
|
|
182
|
+
- **No migrations yet?** Leave out `--roundtrip-apply`. The job is written but **skipped**
|
|
183
|
+
until `ROUNDTRIP_APPLY` (workflow `env`, top of the file) is set: a skipped leg never passes
|
|
184
|
+
R, so migrations ship on a human grant, and CI stays green — a fresh repo is not held red.
|
|
185
|
+
The build job prints a warning saying so. The cost while skipped: trunk does not reuse a
|
|
186
|
+
branch's identical-tree run (#511). A green no-op job would pass R without testing
|
|
187
|
+
anything; the job never becomes one.
|
|
188
|
+
- **What `--roundtrip` writes:** every `##>>> migration round-trip` fence uncommented (four:
|
|
189
|
+
the workflow env, the build job's `roundtrip` output and its warning step, the job),
|
|
190
|
+
`ROUNDTRIP_APPLY` from `--roundtrip-apply`, and `MIGRATIONS_PATHS` from `.github/project.yml`
|
|
191
|
+
`migrations:` when declared. The other edit points (Postgres image, `ROUNDTRIP_SEED`, reset
|
|
192
|
+
and dump commands) are still yours to walk. By hand, the template header's `sed` does the
|
|
193
|
+
same uncommenting.
|
|
194
|
+
- **Not in the heavy lane.** `--roundtrip` refuses `ci-*-heavy`: that lane never runs at a
|
|
195
|
+
branch's head, and R reads the shipped head.
|
|
196
|
+
- **`colab template` names the gap.** Copying a `ci-*` template into a repo whose policy
|
|
197
|
+
resolves to `reviewer` (the repo key, else this machine's value) without any round-trip job
|
|
198
|
+
prints a warning with the re-copy command. The audit warns the same for a declared `reviewer`.
|
|
199
|
+
- A copy made with `--roundtrip` differs from the template text, so `colab update` reads it as
|
|
200
|
+
locally edited and leaves it to you — copy-and-own, as for any edit.
|
|
201
|
+
|
|
141
202
|
### Migration round-trip — what the Laravel job proves, and what it cannot
|
|
142
203
|
|
|
143
|
-
`ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
|
|
204
|
+
`ci-laravel.yml`'s `migrations` job runs every migration **twice per database engine**: once from
|
|
144
205
|
zero, then — after rolling back the migrations the change adds and seeding rows at the
|
|
145
206
|
schema *before* the change — once more, the way a deploy lands new migrations on data
|
|
146
207
|
that predates them. The schema after both passes must match. Two things to know before
|
|
@@ -341,6 +402,9 @@ drift is only ever a suggestion (#607), so the trailer is moot there. Full contr
|
|
|
341
402
|
is missing or incoherent, when a declared toolchain disagrees with what CI actually
|
|
342
403
|
pins, when branch names drift, and when a stamped copy has fallen behind its template.
|
|
343
404
|
It is advisory — run it locally or on a schedule. It is **not** wired into any repo's CI.
|
|
405
|
+
That multi-repo sweep is adopter tooling: it runs from here, unchanged, until its replacement
|
|
406
|
+
ships, and then leaves; only the text checks stay
|
|
407
|
+
([`audit/README.md`, *What stays and what leaves*](../audit/README.md#what-stays-and-what-leaves-643)).
|
|
344
408
|
|
|
345
409
|
## Runner policy
|
|
346
410
|
|
package/templates/ci-node.yml
CHANGED
|
@@ -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
|
|
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
|
|
622
|
-
#
|
|
623
|
-
#
|
|
624
|
-
#
|
|
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
|
-
#
|
|
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
|
-
# #
|
|
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),
|
package/templates/ci-python.yml
CHANGED
|
@@ -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) {
|
|
@@ -162,7 +162,7 @@ function checkSkills({ root, home, colabHome }) {
|
|
|
162
162
|
const byId = Object.fromEntries(all.map((e) => [e.id, e]));
|
|
163
163
|
const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
|
|
164
164
|
for (const dir of engines.rememberedDirs(colabHome)) {
|
|
165
|
-
if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another
|
|
165
|
+
if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another agent runtime', note: [], caveat: [] }, dir });
|
|
166
166
|
}
|
|
167
167
|
|
|
168
168
|
const rows = [];
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
// md-anchors — the heading-to-anchor slugs a markdown link or an inventory `dest#anchor` resolves
|
|
3
|
+
// against. Moved out of audit/audit.mjs (#158) by #632 so the audit and
|
|
4
|
+
// scripts/check-rule-inventory.mjs share one slugifier.
|
|
5
|
+
|
|
6
|
+
// Minimal GitHub-compatible heading→anchor slugifier (#158). GitHub's real algorithm is
|
|
7
|
+
// unpublished; this is deliberately the common-case subset, calibrated against the 47
|
|
8
|
+
// anchor links already live in this repo (CLAUDE.md, CONVENTIONS.md, README*.md,
|
|
9
|
+
// project.schema.md, skills/handbook-sync/SKILL.md, tools/README.md) — every one of
|
|
10
|
+
// them resolves under it. Not a general markdown-heading parser: it does not need to be,
|
|
11
|
+
// because the only headings it is ever asked to slugify are the ones already governing
|
|
12
|
+
// the links this check exists to validate.
|
|
13
|
+
function slugifyHeading(text) {
|
|
14
|
+
return text
|
|
15
|
+
.replace(/`([^`]*)`/g, "$1") // code spans contribute their literal text, not backticks
|
|
16
|
+
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) contributes only the text
|
|
17
|
+
.trim()
|
|
18
|
+
.replace(/#+$/, "") // a trailing "##" some repos use to mark a self-anchor
|
|
19
|
+
.toLowerCase()
|
|
20
|
+
// strip punctuation, keep Unicode letters/digits, underscore, hyphens/spaces -- NOT
|
|
21
|
+
// collapsed. `\w` is ASCII-only ([A-Za-z0-9_]); GitHub's real slugifier keeps Unicode
|
|
22
|
+
// letters (Vietnamese, Japanese, accented Latin, ...), so `\w` alone silently deleted
|
|
23
|
+
// them and produced a slug GitHub never renders (#280). `\p{L}`/`\p{N}` (with the `/u`
|
|
24
|
+
// flag) widen letter/digit matching to Unicode while `_` stays its own explicit member
|
|
25
|
+
// of the class -- it must NOT be folded into `\p{L}`/`\p{N}`, because the very next
|
|
26
|
+
// step below (`.replace(/[ _]/g, "-")`) turns underscores into hyphens and needs them
|
|
27
|
+
// to survive this line to do it; the issue's own one-line suggestion dropped `_` from
|
|
28
|
+
// the class and would have silently broken every underscored heading slug.
|
|
29
|
+
.replace(/[^\p{L}\p{N}_\- ]+/gu, "")
|
|
30
|
+
.trim()
|
|
31
|
+
// Each space/underscore becomes its OWN hyphen -- never collapsed. GitHub does not
|
|
32
|
+
// merge runs: a heading like "tier -- required" strips the em-dash but keeps both
|
|
33
|
+
// spaces around where it was, producing "tier--required" (double hyphen), and every
|
|
34
|
+
// link already written against a real heading in this repo is punctuated that way.
|
|
35
|
+
// Collapsing here silently breaks every one of them.
|
|
36
|
+
.replace(/[ _]/g, "-");
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// Every heading in `text`, in document order, mapped to its resolved slug — including
|
|
40
|
+
// GitHub's duplicate-slug suffixing (`-1`, `-2`, … in heading order, not alphabetical).
|
|
41
|
+
// Fenced code blocks are skipped so a `#` inside a code sample is never read as a heading.
|
|
42
|
+
function collectHeadingSlugs(text) {
|
|
43
|
+
const slugs = new Set();
|
|
44
|
+
const seen = new Map(); // base slug -> next suffix to try
|
|
45
|
+
let inFence = false;
|
|
46
|
+
for (const line of text.split("\n")) {
|
|
47
|
+
if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
|
|
48
|
+
if (inFence) continue;
|
|
49
|
+
const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
|
|
50
|
+
if (!m) continue;
|
|
51
|
+
const base = slugifyHeading(m[1]);
|
|
52
|
+
if (!base) continue;
|
|
53
|
+
const n = seen.get(base) ?? 0;
|
|
54
|
+
seen.set(base, n + 1);
|
|
55
|
+
slugs.add(n === 0 ? base : `${base}-${n}`);
|
|
56
|
+
}
|
|
57
|
+
return slugs;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
module.exports = { slugifyHeading, collectHeadingSlugs };
|
|
@@ -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 };
|