@futurelastic/colab-handbook 1.12.0-rc.69 → 1.12.0-rc.71
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 +49 -22
- package/README.vi.md +50 -24
- package/audit/audit.mjs +13 -4
- package/package.json +1 -1
- package/tools/colab +116 -19
- package/tools/lib/adopt.js +61 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/install-check.js +14 -8
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ This file is for humans.
|
|
|
13
13
|
|
|
14
14
|
```sh
|
|
15
15
|
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
16
|
-
cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks; --dry shows it first
|
|
16
|
+
cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks, from the newest release; --dry shows it first
|
|
17
17
|
cd /path/to/your-repo
|
|
18
18
|
colab adopt # asks only what it cannot detect, writes .github/project.yml
|
|
19
19
|
colab labels --ensure # creates the convention labels
|
|
@@ -23,7 +23,8 @@ colab register # adds the repo to this machine's fleet list
|
|
|
23
23
|
Then, in an agent session in that repo, run `/code-start <issue-number>`. With an
|
|
24
24
|
agent at hand, `/handbook-sync` replaces the last three commands and also does
|
|
25
25
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
26
|
-
You need `git`, `node` ≥ 18 and `gh` logged in (`gh auth login`)
|
|
26
|
+
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
27
|
+
packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
|
|
27
28
|
|
|
28
29
|
*([`CONVENTIONS.md`](CONVENTIONS.md) is the normative document, written in
|
|
29
30
|
English so agents and tooling can read it. This file and the Vietnamese
|
|
@@ -133,18 +134,24 @@ it end to end.
|
|
|
133
134
|
|
|
134
135
|
## The five questions
|
|
135
136
|
|
|
136
|
-
Adopting means answering these about your repo
|
|
137
|
-
|
|
137
|
+
Adopting means answering these about your repo into `.github/project.yml`.
|
|
138
|
+
`colab adopt` asks only the two that change a gate (1 and 3), as numbered menus;
|
|
139
|
+
the other three are optional and can be answered any time later:
|
|
138
140
|
|
|
139
|
-
| # | Question | Writes |
|
|
140
|
-
|
|
141
|
-
| 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` |
|
|
142
|
-
| 2 | Who else works here — just you, a team, or the public? | `room` |
|
|
143
|
-
| 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` |
|
|
144
|
-
| 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` |
|
|
145
|
-
| 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` |
|
|
146
|
-
|
|
147
|
-
|
|
141
|
+
| # | Question | Writes | At adoption |
|
|
142
|
+
|---|---|---|---|
|
|
143
|
+
| 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` | asked |
|
|
144
|
+
| 2 | Who else works here — just you, a team, or the public? | `room` | optional — `colab adopt --axis room` |
|
|
145
|
+
| 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` | asked — a human's answer |
|
|
146
|
+
| 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` | optional — `colab adopt --axis writes` |
|
|
147
|
+
| 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` | optional — `colab adopt --axis channels` |
|
|
148
|
+
|
|
149
|
+
**Answering question 3 is a human's act** when the answer is "nothing" or "only
|
|
150
|
+
people already in the room". An agent can drive everything else; when it gets
|
|
151
|
+
there, `colab adopt` prints, as its first line, the one command the human runs.
|
|
152
|
+
|
|
153
|
+
Nothing is asked that the repo already states — its default branch (`trunk`,
|
|
154
|
+
kept as it is: a `master` default is fine, nothing needs renaming),
|
|
148
155
|
its toolchain, its ports are detected. Gate count, release ritual and whether a
|
|
149
156
|
branch is mandatory are derived from the answers. What each answer resolves to,
|
|
150
157
|
and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
|
|
@@ -163,7 +170,7 @@ edits.
|
|
|
163
170
|
By hand, the same steps (full checklist:
|
|
164
171
|
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
165
172
|
|
|
166
|
-
1. `colab adopt` — answers the
|
|
173
|
+
1. `colab adopt` — answers the two gating questions and writes
|
|
167
174
|
`.github/project.yml`. It stops there and prints the remaining steps.
|
|
168
175
|
2. `colab labels --ensure` — the convention labels do not exist by default. A
|
|
169
176
|
check whose label was never created can never fire.
|
|
@@ -238,10 +245,23 @@ migration hold with or without it.
|
|
|
238
245
|
## Setting up a machine
|
|
239
246
|
|
|
240
247
|
Once per machine. Clone somewhere permanent — the skills are symlinks *into
|
|
241
|
-
this working tree*, so
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
248
|
+
this working tree*, so whatever it has checked out is the version every session
|
|
249
|
+
gets. `install.sh` checks its prerequisites before it changes anything, never
|
|
250
|
+
overwrites what it did not create, and `--dry` prints the plan first.
|
|
251
|
+
|
|
252
|
+
**Which version you get.** `main` runs ahead of the last final release, so the
|
|
253
|
+
first install from a fresh clone checks out the **newest final release tag**
|
|
254
|
+
(`vX.Y.Z`, never a release candidate) and installs from that — the same
|
|
255
|
+
default npm gives you. To follow `main` instead, unreleased work included, run
|
|
256
|
+
the first install with `--trunk`. Every run prints which one you are on.
|
|
257
|
+
Later moves are explicit:
|
|
258
|
+
|
|
259
|
+
- to a newer release: `./install.sh --release`;
|
|
260
|
+
- from a release back to `main`: `git checkout main && ./install.sh --trunk` (an
|
|
261
|
+
older release's installer does not know `--trunk`, so check out `main` first).
|
|
262
|
+
|
|
263
|
+
A clone with uncommitted changes is never moved, and a re-run without either
|
|
264
|
+
flag keeps whatever is checked out.
|
|
245
265
|
|
|
246
266
|
| Flag | What it does |
|
|
247
267
|
|---|---|
|
|
@@ -251,6 +271,8 @@ the plan first.
|
|
|
251
271
|
| `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
|
|
252
272
|
| `--all` | `--tools --hooks --fleet`. |
|
|
253
273
|
| `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json`, only if the key is absent. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
274
|
+
| `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
|
|
275
|
+
| `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
|
|
254
276
|
| `--dry` | Print what would happen, change nothing. Combines with the flags above. |
|
|
255
277
|
| `--check` | **Read-only** health report on an earlier install — see below. Takes no other flag; exit 1 on any ✗ row. |
|
|
256
278
|
|
|
@@ -262,9 +284,11 @@ branch this clone has checked out. The frozen copy never moves on its own:
|
|
|
262
284
|
[`tools/README.md`](tools/README.md#install).
|
|
263
285
|
|
|
264
286
|
**The CLI alone, without the skills,** is on npm as
|
|
265
|
-
**`@futurelastic/colab-handbook
|
|
266
|
-
|
|
267
|
-
|
|
287
|
+
**`@futurelastic/colab-handbook`**. No final release has been published to npm
|
|
288
|
+
yet, so the default `latest` tag holds only a placeholder; install from
|
|
289
|
+
**`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
|
|
290
|
+
<command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
|
|
291
|
+
still `colab`. The skills are not in the package; they install from a
|
|
268
292
|
clone, because they must symlink into `~/.claude/skills/`.
|
|
269
293
|
|
|
270
294
|
### Checking an install
|
|
@@ -281,7 +305,10 @@ which commands it does not dispatch, whether the state file exists, whether
|
|
|
281
305
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
282
306
|
`notifyUrl` is unset while a local observer declared an endpoint. ✗ means
|
|
283
307
|
something installed is stale or unusable; ⚠ means something was never set up,
|
|
284
|
-
which may be deliberate
|
|
308
|
+
which may be deliberate or just not done yet — so a correct fresh install, with
|
|
309
|
+
no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
|
|
310
|
+
never refreshes anything. `--check` is not in v1.11.0 or earlier; on such a
|
|
311
|
+
release, follow `main` to get it.
|
|
285
312
|
|
|
286
313
|
## Why so little enforcement
|
|
287
314
|
|
package/README.vi.md
CHANGED
|
@@ -12,7 +12,7 @@ File này dành cho con người.
|
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
15
|
-
cd ~/code/colab-handbook && ./install.sh --all # skills + CLI colab + hook; --dry để xem trước
|
|
15
|
+
cd ~/code/colab-handbook && ./install.sh --all # skills + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
|
|
16
16
|
cd /duong-dan/toi/repo-cua-ban
|
|
17
17
|
colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
|
|
18
18
|
colab labels --ensure # tạo các label quy ước
|
|
@@ -22,7 +22,8 @@ colab register # đưa repo vào danh sách fleet của máy này
|
|
|
22
22
|
Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>`. Có agent
|
|
23
23
|
trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
24
24
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
25
|
-
và `gh` đã đăng nhập (`gh auth login`)
|
|
25
|
+
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
26
|
+
hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
|
|
26
27
|
|
|
27
28
|
*([`CONVENTIONS.md`](CONVENTIONS.md) là tài liệu chuẩn tắc, viết bằng tiếng Anh
|
|
28
29
|
để agent và tool đọc được. File này và bản tiếng Anh [`README.md`](README.md)
|
|
@@ -132,18 +133,24 @@ còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra n
|
|
|
132
133
|
|
|
133
134
|
## Năm câu hỏi
|
|
134
135
|
|
|
135
|
-
Adopt nghĩa là trả lời mấy câu này về repo của bạn
|
|
136
|
-
|
|
136
|
+
Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
|
|
137
|
+
`colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
|
|
138
|
+
số; ba câu còn lại là tuỳ chọn, trả lời lúc nào sau này cũng được:
|
|
137
139
|
|
|
138
|
-
| # | Câu hỏi | Ghi vào |
|
|
139
|
-
|
|
140
|
-
| 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` |
|
|
141
|
-
| 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` |
|
|
142
|
-
| 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` |
|
|
143
|
-
| 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` |
|
|
144
|
-
| 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` |
|
|
145
|
-
|
|
146
|
-
|
|
140
|
+
| # | Câu hỏi | Ghi vào | Lúc adopt |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` | có hỏi |
|
|
143
|
+
| 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` | tuỳ chọn — `colab adopt --axis room` |
|
|
144
|
+
| 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` | có hỏi — người thật trả lời |
|
|
145
|
+
| 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` | tuỳ chọn — `colab adopt --axis writes` |
|
|
146
|
+
| 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` | tuỳ chọn — `colab adopt --axis channels` |
|
|
147
|
+
|
|
148
|
+
**Trả lời câu 3 là việc của người thật** khi câu trả lời là "không gì cả" hoặc
|
|
149
|
+
"chỉ những người đang có mặt". Agent làm được mọi phần còn lại; tới bước đó,
|
|
150
|
+
`colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
|
|
151
|
+
|
|
152
|
+
Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`, giữ nguyên
|
|
153
|
+
như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
|
|
147
154
|
port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
|
|
148
155
|
nhánh hay không đều suy ra từ câu trả lời. Mỗi câu trả lời quy về đâu, và vì
|
|
149
156
|
sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
@@ -161,7 +168,7 @@ nhất mà không làm mất phần bạn đã sửa.
|
|
|
161
168
|
Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
|
|
162
169
|
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
163
170
|
|
|
164
|
-
1. `colab adopt` — trả lời
|
|
171
|
+
1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
|
|
165
172
|
đó và in ra các bước còn lại.
|
|
166
173
|
2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
|
|
167
174
|
của nó chưa từng được tạo thì không bao giờ chạy được.
|
|
@@ -236,10 +243,23 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
236
243
|
## Cài đặt máy
|
|
237
244
|
|
|
238
245
|
Làm một lần cho mỗi máy. Clone vào chỗ ở lâu dài — các skill là symlink trỏ
|
|
239
|
-
*thẳng vào working tree này*, nên repo đang checkout
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
246
|
+
*thẳng vào working tree này*, nên repo đang checkout cái gì thì mọi phiên dùng
|
|
247
|
+
đúng bản skill đó. `install.sh` kiểm tra đủ điều kiện trước khi đụng vào gì,
|
|
248
|
+
không bao giờ ghi đè thứ nó không tạo ra, và `--dry` in kế hoạch ra trước.
|
|
249
|
+
|
|
250
|
+
**Bạn nhận phiên bản nào.** `main` chạy trước bản phát hành chính thức cuối
|
|
251
|
+
cùng, nên lần cài đầu tiên từ một bản clone mới sẽ checkout **tag phát hành
|
|
252
|
+
chính thức mới nhất** (`vX.Y.Z`, không bao giờ là bản ứng viên) rồi cài từ đó —
|
|
253
|
+
giống mặc định của npm. Muốn theo `main`, kể cả phần chưa phát hành, thì chạy
|
|
254
|
+
lần cài đầu với `--trunk`. Lần chạy nào cũng in ra bạn đang ở bản nào. Đổi về
|
|
255
|
+
sau đều phải chủ động:
|
|
256
|
+
|
|
257
|
+
- lên bản phát hành mới hơn: `./install.sh --release`;
|
|
258
|
+
- từ một bản phát hành quay về `main`: `git checkout main && ./install.sh --trunk`
|
|
259
|
+
(installer của bản phát hành cũ không biết `--trunk`, nên checkout `main` trước).
|
|
260
|
+
|
|
261
|
+
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
262
|
+
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
243
263
|
|
|
244
264
|
| Flag | Làm gì |
|
|
245
265
|
|---|---|
|
|
@@ -249,6 +269,8 @@ dùng đúng bản skill của nhánh đó; hãy để nó ở `main`. `install.
|
|
|
249
269
|
| `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
|
|
250
270
|
| `--all` | `--tools --hooks --fleet`. |
|
|
251
271
|
| `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json`, chỉ khi khoá đó chưa có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
272
|
+
| `--release` | Checkout clone này về tag phát hành chính thức mới nhất, rồi cài. Là mặc định cho lần cài đầu từ một bản clone mới. |
|
|
273
|
+
| `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
|
|
252
274
|
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
|
|
253
275
|
| `--check` | Báo cáo sức khoẻ **chỉ đọc** cho một lần cài trước đó — xem bên dưới. Không nhận flag nào khác; exit 1 nếu có dòng ✗. |
|
|
254
276
|
|
|
@@ -259,10 +281,11 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
|
|
|
259
281
|
--tools` để làm mới. Vì sao lại làm vậy:
|
|
260
282
|
[`tools/README.md`](tools/README.md#install).
|
|
261
283
|
|
|
262
|
-
**Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
284
|
+
**Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**.
|
|
285
|
+
Chưa có bản phát hành chính thức nào lên npm, nên tag mặc định `latest` chỉ là
|
|
286
|
+
bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
|
|
287
|
+
@futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
|
|
288
|
+
@futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
|
|
266
289
|
symlink vào `~/.claude/skills/`.
|
|
267
290
|
|
|
268
291
|
### Kiểm tra bản cài
|
|
@@ -278,8 +301,11 @@ colab update # các bản copy có đóng dấu đã tụt lại, k
|
|
|
278
301
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
279
302
|
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
|
|
280
303
|
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
281
|
-
hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố
|
|
282
|
-
|
|
304
|
+
hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý hoặc
|
|
305
|
+
chỉ là chưa làm tới — nên một bản cài mới đúng, chưa đăng ký repo nào và chưa có
|
|
306
|
+
danh sách từ khoá danh tính, sẽ ra các dòng ⚠ và exit 0. Nó không bao giờ tự làm
|
|
307
|
+
mới gì cả. `--check` không có trong v1.11.0 trở về trước; ở những bản đó, hãy theo
|
|
308
|
+
`main` để có nó.
|
|
283
309
|
|
|
284
310
|
## Vì sao ép buộc ít vậy
|
|
285
311
|
|
package/audit/audit.mjs
CHANGED
|
@@ -82,7 +82,7 @@ const {
|
|
|
82
82
|
// encode the VALIDATOR half (report every violation) separately from `colab adopt`'s CONSTRUCTOR
|
|
83
83
|
// half (does declaring this exposure value stay possible at all?). Same install.sh-freezes-
|
|
84
84
|
// tools/lib/ reasoning as the other requires on this page.
|
|
85
|
-
const { evaluateExposure } = require("../tools/lib/exposure-shape.js");
|
|
85
|
+
const { evaluateExposure, singleTrunkViolation } = require("../tools/lib/exposure-shape.js");
|
|
86
86
|
// #208's `writes` split precedence ladder — same shared-module reasoning as axisAuthority
|
|
87
87
|
// above, reused for a second axis rather than a bespoke second mechanism.
|
|
88
88
|
const writesAuthority = require("../tools/lib/writes-authority.js");
|
|
@@ -1100,6 +1100,10 @@ function renderDuration(age) {
|
|
|
1100
1100
|
|
|
1101
1101
|
function auditRepo(target, ctx) {
|
|
1102
1102
|
const src = makeSource(target);
|
|
1103
|
+
// #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
|
|
1104
|
+
// trunk-exists check below — one read, so a remote target costs one API listing, not three.
|
|
1105
|
+
let branchesMemo;
|
|
1106
|
+
const branchList = () => (branchesMemo === undefined ? (branchesMemo = src.branches()) : branchesMemo);
|
|
1103
1107
|
const findings = []; // { level: 'fail'|'warn', text }
|
|
1104
1108
|
// `self` = this target IS the handbook, not one of its consumers. Surfaced in the
|
|
1105
1109
|
// report (and in --json) so the row reads as source-of-truth rather than clean-by-luck:
|
|
@@ -1608,7 +1612,12 @@ function auditRepo(target, ctx) {
|
|
|
1608
1612
|
? `tier A with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(trunk)}`
|
|
1609
1613
|
: `tier A requires trunk "dev", found ${JSON.stringify(trunk)} — only a tag-gated A (deploy: tag) may run a single trunk "main"`);
|
|
1610
1614
|
}
|
|
1611
|
-
|
|
1615
|
+
// #522: B is the single-trunk shape — one long-lived branch, any spelling. `master` (or
|
|
1616
|
+
// whatever an existing repo's default is) conforms; a "main" beside a non-main trunk does not.
|
|
1617
|
+
if (tier === "B") {
|
|
1618
|
+
const single = singleTrunkViolation(trunk, branchList());
|
|
1619
|
+
if (single) fail(`tier B requires a single trunk — ${single}`);
|
|
1620
|
+
}
|
|
1612
1621
|
// C uses A's two-branch split: main = what is live, trunk = where sessions land. #205:
|
|
1613
1622
|
// this validates the SPLIT, not the spelling — trunk is a declared setting (default
|
|
1614
1623
|
// "dev", proposed by colab adopt and the templates), never required to literally be
|
|
@@ -1817,7 +1826,7 @@ function auditRepo(target, ctx) {
|
|
|
1817
1826
|
// construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
|
|
1818
1827
|
// A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
|
|
1819
1828
|
// "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
|
|
1820
|
-
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers] };
|
|
1829
|
+
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers], branches: branchList() };
|
|
1821
1830
|
for (const entry of evaluateExposure(exp, shapeCtx)) {
|
|
1822
1831
|
if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
|
|
1823
1832
|
else fail(entry.message);
|
|
@@ -1825,7 +1834,7 @@ function auditRepo(target, ctx) {
|
|
|
1825
1834
|
}
|
|
1826
1835
|
|
|
1827
1836
|
// ---- declared trunk actually exists -------------------------------------
|
|
1828
|
-
const branches =
|
|
1837
|
+
const branches = branchList();
|
|
1829
1838
|
if (trunk && branches === null) {
|
|
1830
1839
|
warn(`cannot list branches (not a git checkout, or gh unavailable) — trunk "${trunk}" unverified`);
|
|
1831
1840
|
} else if (trunk && branches && !branches.includes(trunk)) {
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -7718,6 +7718,18 @@ answered by its number OR its literal value), DERIVES the rest, and WRITES the d
|
|
|
7718
7718
|
act — append-only, never touching a byte already there. A complete descriptor just reports
|
|
7719
7719
|
(write nothing, exit 0); re-answer one row on purpose with --axis.
|
|
7720
7720
|
|
|
7721
|
+
ONLY THE GATING ROWS ARE ASKED (#533): deploy/production and exposure. room, writes and channels
|
|
7722
|
+
are optional and legal absent — never prompted for; the report names them in one line with the
|
|
7723
|
+
\`--axis\` command that answers each later, and their own flag still answers one in the same run.
|
|
7724
|
+
After deploy: none, production is not asked again (null follows; --deploy none alone implies it).
|
|
7725
|
+
|
|
7726
|
+
A SINGLE TRUNK, ANY SPELLING (#522): exposure none (and released with production null, and the
|
|
7727
|
+
legacy tier B) need ONE long-lived branch, not one named "main" — an existing master default
|
|
7728
|
+
adopts as-is. A "main" beside a non-main trunk is the two-branch shape and is refused (exit 5).
|
|
7729
|
+
At a terminal the exposure answer is checked against that shape when given, and re-asked with
|
|
7730
|
+
the reason. When a human must finish (the gate below), the FIRST line printed is the one
|
|
7731
|
+
command to run, every answer this run had already filled in.
|
|
7732
|
+
|
|
7721
7733
|
--writes accepts free (coexistence, the default), direct (an attended human may commit straight
|
|
7722
7734
|
to trunk; DECLARED today, its runtime is DEFERRED — see CONVENTIONS.md §2, "writes: direct —
|
|
7723
7735
|
declared today, runtime deferred"), or isolated (vetoes trunk-direct outright, human or not).
|
|
@@ -7914,7 +7926,26 @@ function adoptGitExtras(repoAbs, opts = {}) {
|
|
|
7914
7926
|
// #483: the fork's own owner, from origin's URL — what an inherited CODEOWNERS team is compared to.
|
|
7915
7927
|
const originUrl = git.git(['remote', 'get-url', 'origin'], repoAbs);
|
|
7916
7928
|
const ownOrg = originUrl.ok ? codeowners.remoteOwner(originUrl.stdout) : null;
|
|
7917
|
-
return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg };
|
|
7929
|
+
return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg, branches: adoptBranchList(repoAbs) };
|
|
7930
|
+
}
|
|
7931
|
+
|
|
7932
|
+
/** #522: every branch name visible here — refs/heads ∪ refs/remotes/<any>/<name> — the same union
|
|
7933
|
+
* audit/audit.mjs's `branches()` reads, so the single-trunk rule (tools/lib/exposure-shape.js
|
|
7934
|
+
* `singleTrunkViolation`) answers identically on both sides: adopt never writes what the audit
|
|
7935
|
+
* then fails. null when git cannot list refs (the rule then fails closed to trunk "main"). */
|
|
7936
|
+
function adoptBranchList(repoAbs) {
|
|
7937
|
+
const r = git.git(['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes'], repoAbs);
|
|
7938
|
+
if (!r.ok) return null;
|
|
7939
|
+
const names = new Set();
|
|
7940
|
+
for (const ref of r.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
|
|
7941
|
+
if (ref.startsWith('refs/heads/')) names.add(ref.slice('refs/heads/'.length));
|
|
7942
|
+
else if (ref.startsWith('refs/remotes/')) {
|
|
7943
|
+
const rest = ref.slice('refs/remotes/'.length);
|
|
7944
|
+
const name = rest.slice(rest.indexOf('/') + 1);
|
|
7945
|
+
if (rest.includes('/') && name && name !== 'HEAD') names.add(name);
|
|
7946
|
+
}
|
|
7947
|
+
}
|
|
7948
|
+
return [...names];
|
|
7918
7949
|
}
|
|
7919
7950
|
|
|
7920
7951
|
/**
|
|
@@ -8187,6 +8218,8 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
|
|
|
8187
8218
|
print(`detected trunk: ${t.detected || '(unknown)'}${trunkSourceNote}${t.declared !== null ? ` (declared: ${t.declared}${t.agree === false ? ' ⚠ disagrees with detected' : ''})` : ''}`);
|
|
8188
8219
|
print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
|
|
8189
8220
|
print(`declared ports: ${fmtVal(report.detected.ports)}`);
|
|
8221
|
+
const optLine = adopt.optionalRowsLine(report.optionalUnanswered); // #533
|
|
8222
|
+
if (optLine) print(optLine);
|
|
8190
8223
|
if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
|
|
8191
8224
|
if (report.inheritedCodeowners) {
|
|
8192
8225
|
const ic = report.inheritedCodeowners;
|
|
@@ -8262,6 +8295,8 @@ function adoptAnswersFromFlags(opts, cfg, axesToAsk, forcedAxes) {
|
|
|
8262
8295
|
if (!adopt.VALID_DEPLOY.has(opts.deploy)) throw new UserError(`--deploy must be one of: ${[...adopt.VALID_DEPLOY].join(', ')}`);
|
|
8263
8296
|
values.deploy = opts.deploy;
|
|
8264
8297
|
flags.push('--deploy');
|
|
8298
|
+
// #533: deploy: none already says nothing is live — production: null follows, never re-asked.
|
|
8299
|
+
if (opts.deploy === 'none' && opts.production === undefined && eligible('production', 'tier')) values.production = null;
|
|
8265
8300
|
}
|
|
8266
8301
|
if (flags.length) answers.tier = { values, mode: 'flag', flags };
|
|
8267
8302
|
}
|
|
@@ -8325,7 +8360,7 @@ async function askMenu(rl, axis, promptFn) {
|
|
|
8325
8360
|
* URL itself asked only on "yes" — this keeps every axis forced-choice-shaped without pretending
|
|
8326
8361
|
* a URL belongs to an enum.
|
|
8327
8362
|
*/
|
|
8328
|
-
async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
8363
|
+
async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
|
|
8329
8364
|
const answers = {};
|
|
8330
8365
|
for (const axis of axesToAsk) {
|
|
8331
8366
|
const q = adopt.QUESTIONS.find((x) => x.axis === axis);
|
|
@@ -8336,13 +8371,16 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8336
8371
|
process.stdout.write(`${adopt.renderMenu('tier')}\n`);
|
|
8337
8372
|
return rlAsk(rl, ' deploy: ');
|
|
8338
8373
|
});
|
|
8339
|
-
process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
|
|
8340
|
-
const existsRaw = (await rlAsk(rl, ' production: ')).trim();
|
|
8341
8374
|
let prod = null;
|
|
8342
|
-
|
|
8343
|
-
|
|
8344
|
-
|
|
8345
|
-
|
|
8375
|
+
// #533: deploy: none already answered "nothing is live" — asking production again is noise.
|
|
8376
|
+
if (depChoice.value !== 'none') {
|
|
8377
|
+
process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
|
|
8378
|
+
const existsRaw = (await rlAsk(rl, ' production: ')).trim();
|
|
8379
|
+
if (existsRaw === '2' || existsRaw === 'yes') {
|
|
8380
|
+
prod = (await rlAsk(rl, ' URL: ')).trim() || null;
|
|
8381
|
+
} else if (existsRaw !== '1' && existsRaw !== 'no') {
|
|
8382
|
+
throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
|
|
8383
|
+
}
|
|
8346
8384
|
}
|
|
8347
8385
|
answers.tier = { values: { production: prod, deploy: depChoice.value }, mode: 'interactive' };
|
|
8348
8386
|
} else if (axis === 'channels') {
|
|
@@ -8352,12 +8390,22 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8352
8390
|
});
|
|
8353
8391
|
answers.channels = { values: { channels: resolved.value }, mode: 'interactive' };
|
|
8354
8392
|
} else if (axis === 'exposure') {
|
|
8355
|
-
|
|
8356
|
-
|
|
8357
|
-
|
|
8358
|
-
|
|
8359
|
-
|
|
8360
|
-
|
|
8393
|
+
// #522: the repo-shape check runs HERE, at answer time — a refusal re-asks with its reason,
|
|
8394
|
+
// instead of surfacing after every other question with nothing written.
|
|
8395
|
+
let chosen = null;
|
|
8396
|
+
for (let attempt = 0; attempt < 2 && !chosen; attempt++) {
|
|
8397
|
+
const resolved = await askMenu(rl, 'exposure', () => {
|
|
8398
|
+
process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
|
|
8399
|
+
return rlAsk(rl, ' choice: ');
|
|
8400
|
+
});
|
|
8401
|
+
if (resolved.skip) { chosen = resolved; break; }
|
|
8402
|
+
const problem = checkExposure ? checkExposure(resolved.value, answers) : null;
|
|
8403
|
+
if (!problem) { chosen = resolved; break; }
|
|
8404
|
+
process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
|
|
8405
|
+
}
|
|
8406
|
+
if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
|
|
8407
|
+
if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
|
|
8408
|
+
answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
|
|
8361
8409
|
} else {
|
|
8362
8410
|
// room, writes — plain single-choice menus, no skip.
|
|
8363
8411
|
const resolved = await askMenu(rl, axis, () => {
|
|
@@ -8370,11 +8418,41 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8370
8418
|
return answers;
|
|
8371
8419
|
}
|
|
8372
8420
|
|
|
8421
|
+
/** #522: this run's answers as the ordered flag list `adopt.humanAdoptCommand` prints — what the
|
|
8422
|
+
* human pastes to finish the same adoption with the gate satisfied. */
|
|
8423
|
+
function adoptReplayFlags(opts, answers) {
|
|
8424
|
+
const flags = [];
|
|
8425
|
+
if (opts.repo !== undefined) flags.push(['--repo', opts.repo]);
|
|
8426
|
+
const t = answers.tier && answers.tier.values;
|
|
8427
|
+
if (t && 'production' in t) flags.push(['--production', t.production === null ? 'none' : t.production]);
|
|
8428
|
+
if (t && 'deploy' in t) flags.push(['--deploy', t.deploy]);
|
|
8429
|
+
if (answers.exposure) flags.push(['--exposure', answers.exposure.values.exposure]);
|
|
8430
|
+
if (answers.room) flags.push(['--room', answers.room.values.room]);
|
|
8431
|
+
if (answers.writes) flags.push(['--writes', answers.writes.values.writes]);
|
|
8432
|
+
if (answers.channels) flags.push(['--channels', answers.channels.values.channels.join(',')]);
|
|
8433
|
+
if (opts.stack !== undefined) flags.push(['--stack', opts.stack]);
|
|
8434
|
+
if (opts.autonomy !== undefined) flags.push(['--autonomy', opts.autonomy]);
|
|
8435
|
+
if (opts.reason !== undefined) flags.push(['--reason', opts.reason]);
|
|
8436
|
+
if (opts.answeredBy) flags.push(['--answered-by', opts.answeredBy]);
|
|
8437
|
+
if (opts.land) flags.push(['--land', true]);
|
|
8438
|
+
return flags;
|
|
8439
|
+
}
|
|
8440
|
+
|
|
8441
|
+
/** #522: the same command shape for a run that had no answers at all — placeholders per asked row. */
|
|
8442
|
+
function adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable) {
|
|
8443
|
+
const flags = [];
|
|
8444
|
+
if (axesToAsk.includes('tier')) flags.push(['--production', '<url>|none'], ['--deploy', '<none|tag|manual|push-main>']);
|
|
8445
|
+
if (axesToAsk.includes('exposure')) flags.push(['--exposure', '<none|self|live|released>']);
|
|
8446
|
+
for (const a of ['room', 'writes', 'channels']) if (axesToAsk.includes(a)) flags.push([`--${a}`, `<${a}>`]);
|
|
8447
|
+
if (stackUnresolvable) flags.push(['--stack', '<text>']);
|
|
8448
|
+
return flags;
|
|
8449
|
+
}
|
|
8450
|
+
|
|
8373
8451
|
/** The `EXPOSURE_SHAPE`/falsifier context, built from EFFECTIVE production/deploy — accounting
|
|
8374
8452
|
* for a `tier`-axis answer resolved in THIS SAME run, not only what was already on record, so
|
|
8375
8453
|
* declaring production+deploy and exposure together in one invocation validates against each
|
|
8376
8454
|
* other rather than the pre-write snapshot. */
|
|
8377
|
-
function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
|
|
8455
|
+
function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io, branches) {
|
|
8378
8456
|
const effProduction = tierAnswer ? tierAnswer.values.production : (Object.prototype.hasOwnProperty.call(cfg, 'production') ? cfg.production : null);
|
|
8379
8457
|
const effDeploy = tierAnswer ? tierAnswer.values.deploy : (Object.prototype.hasOwnProperty.call(cfg, 'deploy') ? cfg.deploy : null);
|
|
8380
8458
|
const evidence = consumerEvidence.consumerEvidence(io, workflows);
|
|
@@ -8382,7 +8460,7 @@ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
|
|
|
8382
8460
|
const hasProduction = effProduction !== null && effProduction !== undefined && effProduction !== '';
|
|
8383
8461
|
const runbook = Object.prototype.hasOwnProperty.call(cfg, 'runbook') ? cfg.runbook : null;
|
|
8384
8462
|
const hasRunbook = !!(runbook && io.readFile(String(runbook).trim().replace(/^\.\//, '')) !== null);
|
|
8385
|
-
return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy };
|
|
8463
|
+
return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy, branches: branches === undefined ? null : branches };
|
|
8386
8464
|
}
|
|
8387
8465
|
|
|
8388
8466
|
async function cmdAdopt(argv) {
|
|
@@ -8428,7 +8506,12 @@ async function cmdAdopt(argv) {
|
|
|
8428
8506
|
if (!adopt.ROW_NAMES.includes(a)) throw new UserError(`Unknown --axis "${a}" — expected one of: ${adopt.ROW_NAMES.join(', ')}`);
|
|
8429
8507
|
}
|
|
8430
8508
|
const forcedAxes = new Set(requestedAxes);
|
|
8431
|
-
|
|
8509
|
+
// #533: a fresh adoption asks only the rows that change a gate (production/deploy, exposure);
|
|
8510
|
+
// room/writes/channels are asked only when forced (--axis) or answered by their flag.
|
|
8511
|
+
const flagAxes = new Set();
|
|
8512
|
+
if (opts.production !== undefined || opts.deploy !== undefined) flagAxes.add('tier');
|
|
8513
|
+
for (const a of ['room', 'exposure', 'writes', 'channels']) if (opts[a] !== undefined) flagAxes.add(a);
|
|
8514
|
+
let axesToAsk = adopt.axesToAsk(cfg, forcedAxes, flagAxes);
|
|
8432
8515
|
// --local re-run (#393): once exposure is on record, a bare `adopt --local` (no answer flags, no
|
|
8433
8516
|
// --axis) is the idempotent re-apply — exclude lines, stub, labels, checkout — never a prompt for
|
|
8434
8517
|
// the optional rows (room/writes/channels), which --local leaves to the operator by design.
|
|
@@ -8522,7 +8605,11 @@ async function cmdAdopt(argv) {
|
|
|
8522
8605
|
} else if (isTTY) {
|
|
8523
8606
|
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
|
|
8524
8607
|
try {
|
|
8525
|
-
|
|
8608
|
+
const shapeWorkflows = io.listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f));
|
|
8609
|
+
answers = await adoptAskInteractive(rl, axesToAsk, cfg, (exposure, sofar) => {
|
|
8610
|
+
const v = adopt.exposureShapeVerdict(exposure, adoptShapeCtx(cfg, sofar.tier, extra.trunk, shapeWorkflows, io, extra.branches));
|
|
8611
|
+
return v.ok ? null : v.reason;
|
|
8612
|
+
});
|
|
8526
8613
|
if (needsStack && opts.stack === undefined) {
|
|
8527
8614
|
process.stdout.write('\nNo manifest recognised (package.json/composer.json/pyproject.toml/'
|
|
8528
8615
|
+ '.python-version) — the audit requires stack: as a literal key.\n');
|
|
@@ -8537,6 +8624,12 @@ async function cmdAdopt(argv) {
|
|
|
8537
8624
|
} else {
|
|
8538
8625
|
const hints = axesToAsk.map(adoptAxisFlagHint).join(' ');
|
|
8539
8626
|
const stackHint = stackUnresolvable ? ' --stack "<text>"' : '';
|
|
8627
|
+
// #522: the human step goes FIRST — answering exposure none/self is a human's act, so the one
|
|
8628
|
+
// command that finishes the adoption leads, and the explanation follows it.
|
|
8629
|
+
if (axesToAsk.includes('exposure')) {
|
|
8630
|
+
warn('a human finishes this adoption — run at an interactive terminal: colab adopt (or, non-interactively:)');
|
|
8631
|
+
warn(` ${adopt.humanAdoptCommand(adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable))}`);
|
|
8632
|
+
}
|
|
8540
8633
|
warn(`${axesToAsk.length} unanswered §9 row(s) (${axesToAsk.join(', ')}) — no TTY and no answer flags, so there is no way to ask. Re-run with: ${hints}${stackHint}`);
|
|
8541
8634
|
return 1;
|
|
8542
8635
|
}
|
|
@@ -8561,7 +8654,7 @@ async function cmdAdopt(argv) {
|
|
|
8561
8654
|
// written, per "nothing partially written on refusal".
|
|
8562
8655
|
if (answers.exposure) {
|
|
8563
8656
|
const proposedExposure = answers.exposure.values.exposure;
|
|
8564
|
-
const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io);
|
|
8657
|
+
const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io, extra.branches);
|
|
8565
8658
|
const evidence = consumerEvidence.consumerEvidence(io, workflows);
|
|
8566
8659
|
const currentExposure = axisAuthority.axisOfRecord(cfg).exposure;
|
|
8567
8660
|
const verdict = adopt.gateVerdict({
|
|
@@ -8575,6 +8668,10 @@ async function cmdAdopt(argv) {
|
|
|
8575
8668
|
reason: opts.reason || null,
|
|
8576
8669
|
});
|
|
8577
8670
|
if (!verdict.ok) {
|
|
8671
|
+
if (verdict.class === adopt.GATE_CLASS.HUMAN_GATED) {
|
|
8672
|
+
// #522: lead with the one command a human runs, every answer this run had filled in.
|
|
8673
|
+
warn(`a human finishes this adoption — run: ${adopt.humanAdoptCommand(adoptReplayFlags(opts, answers))}`);
|
|
8674
|
+
}
|
|
8578
8675
|
warn(verdict.message);
|
|
8579
8676
|
return verdict.exitCode;
|
|
8580
8677
|
}
|
package/tools/lib/adopt.js
CHANGED
|
@@ -37,6 +37,13 @@ const { UserError } = require('./util.js');
|
|
|
37
37
|
|
|
38
38
|
const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
|
|
39
39
|
|
|
40
|
+
/** #533: the rows that change a gate — the only ones a fresh adoption ASKS. `tier` here is the
|
|
41
|
+
* production/deploy pair; `exposure` sets the gate count. The other three are optional in the
|
|
42
|
+
* schema and legal absent (room → trail verbosity, writes → `free` is the default, channels →
|
|
43
|
+
* descriptive), so adoption leaves them unanswered and names the `--axis` command instead. */
|
|
44
|
+
const GATING_ROWS = Object.freeze(['tier', 'exposure']);
|
|
45
|
+
const OPTIONAL_ROWS = Object.freeze(['room', 'writes', 'channels']);
|
|
46
|
+
|
|
40
47
|
// ---------------------------------------------------------------------- descriptor read
|
|
41
48
|
|
|
42
49
|
/** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
|
|
@@ -387,7 +394,7 @@ function remainingSteps(ctx = {}) {
|
|
|
387
394
|
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
388
395
|
steps.push(
|
|
389
396
|
{ n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
|
|
390
|
-
{ n: 4, text: '
|
|
397
|
+
{ n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
|
|
391
398
|
);
|
|
392
399
|
if (ctx.fork) {
|
|
393
400
|
steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
|
|
@@ -538,6 +545,7 @@ function detect(io, extra = {}) {
|
|
|
538
545
|
inheritedCodeowners,
|
|
539
546
|
migrations,
|
|
540
547
|
remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
|
|
548
|
+
optionalUnanswered: optionalUnanswered(cfg), // #533
|
|
541
549
|
};
|
|
542
550
|
}
|
|
543
551
|
|
|
@@ -780,6 +788,52 @@ function axisMissing(cfg, axis) {
|
|
|
780
788
|
}
|
|
781
789
|
}
|
|
782
790
|
|
|
791
|
+
/**
|
|
792
|
+
* #533: which rows this run asks. A gating row is asked when it is still missing; an optional row
|
|
793
|
+
* (room/writes/channels) only when the caller forced it (`--axis`) or supplied its answer flag —
|
|
794
|
+
* a fresh adoption never prompts for it. `flagAxes` — the rows an answer flag was given for.
|
|
795
|
+
*/
|
|
796
|
+
function axesToAsk(cfg, forcedAxes, flagAxes) {
|
|
797
|
+
const forced = forcedAxes instanceof Set ? forcedAxes : new Set(forcedAxes || []);
|
|
798
|
+
const flagged = flagAxes instanceof Set ? flagAxes : new Set(flagAxes || []);
|
|
799
|
+
return ROW_NAMES.filter((a) => forced.has(a)
|
|
800
|
+
|| (axisMissing(cfg, a) && (GATING_ROWS.includes(a) || flagged.has(a))));
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
/** #533: the optional rows still unanswered after a run — reported in one line, never asked. */
|
|
804
|
+
function optionalUnanswered(cfg) {
|
|
805
|
+
return OPTIONAL_ROWS.filter((a) => axisMissing(cfg, a));
|
|
806
|
+
}
|
|
807
|
+
|
|
808
|
+
/** The one line naming them and the command that answers each later (#533). null when none. */
|
|
809
|
+
function optionalRowsLine(rows) {
|
|
810
|
+
if (!rows || !rows.length) return null;
|
|
811
|
+
return `not asked (optional, legal absent): ${rows.join(', ')} — answer later with \`colab adopt --axis ${rows.join(',')}\``;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/** Shell-quote one argument only when it needs it — the printed command must paste and run. */
|
|
815
|
+
function shellArg(v) {
|
|
816
|
+
const t = String(v);
|
|
817
|
+
return /^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `"${t.replace(/(["\\$`])/g, '\\$1')}"`;
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
/**
|
|
821
|
+
* #522: the ONE command a human runs to finish an adoption an agent could not — printed as the
|
|
822
|
+
* first line of a human-gated refusal, answers already filled in. `flags` is an ordered list of
|
|
823
|
+
* `[flag, value]` pairs (value undefined/null for a bare flag); `--answered-by` is appended as a
|
|
824
|
+
* placeholder when absent, because the human bar needs it alongside COLAB_HUMAN=1.
|
|
825
|
+
*/
|
|
826
|
+
function humanAdoptCommand(flags) {
|
|
827
|
+
const parts = ['COLAB_HUMAN=1', 'colab', 'adopt'];
|
|
828
|
+
let hasAnsweredBy = false;
|
|
829
|
+
for (const [flag, value] of flags || []) {
|
|
830
|
+
if (flag === '--answered-by') hasAnsweredBy = true;
|
|
831
|
+
parts.push(value === undefined || value === null || value === true ? flag : `${flag} ${shellArg(value)}`);
|
|
832
|
+
}
|
|
833
|
+
if (!hasAnsweredBy) parts.push('--answered-by "<your name>"');
|
|
834
|
+
return parts.join(' ');
|
|
835
|
+
}
|
|
836
|
+
|
|
783
837
|
// ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
|
|
784
838
|
|
|
785
839
|
/**
|
|
@@ -1166,6 +1220,12 @@ module.exports = {
|
|
|
1166
1220
|
renderMenu,
|
|
1167
1221
|
resolveChoice,
|
|
1168
1222
|
axisMissing,
|
|
1223
|
+
GATING_ROWS,
|
|
1224
|
+
OPTIONAL_ROWS,
|
|
1225
|
+
axesToAsk,
|
|
1226
|
+
optionalUnanswered,
|
|
1227
|
+
optionalRowsLine,
|
|
1228
|
+
humanAdoptCommand,
|
|
1169
1229
|
EXPOSURE_RANK,
|
|
1170
1230
|
GATE_CLASS,
|
|
1171
1231
|
EXIT_CODE,
|
|
@@ -53,7 +53,8 @@
|
|
|
53
53
|
* Context shape both sides build (identically named, audit.mjs and adopt.js each computing the
|
|
54
54
|
* booleans from their own sources — a real git checkout for one, a `git status`-aware `io` for
|
|
55
55
|
* the other):
|
|
56
|
-
* { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames? }
|
|
56
|
+
* { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames?, branches? }
|
|
57
|
+
* `branches` (#522) is what `singleTrunkViolation` reads — omitting it fails closed to trunk "main".
|
|
57
58
|
* `deployWorkflowNames` is OPTIONAL and cosmetic only (the `none` violation names which
|
|
58
59
|
* workflow(s) contradict it) — omitting it (as adopt.js's ctx does) only drops the parenthetical
|
|
59
60
|
* from the message, never changes which entries fire.
|
|
@@ -74,13 +75,45 @@ function evaluateExposure(exposure, ctx) {
|
|
|
74
75
|
}
|
|
75
76
|
}
|
|
76
77
|
|
|
78
|
+
/**
|
|
79
|
+
* #522: the single-trunk invariant shared by every shape with no release branch — `exposure: none`,
|
|
80
|
+
* `exposure: released` with `production: null`, and the legacy `tier: B` (audit/audit.mjs). It is
|
|
81
|
+
* about HOW MANY long-lived branches exist, never how the one branch is spelled: an existing repo
|
|
82
|
+
* whose default branch is `master` (or anything else) adopts as-is, with nothing renamed.
|
|
83
|
+
*
|
|
84
|
+
* What it refuses is the two-branch shape wearing a single-trunk label: a `main` branch sitting
|
|
85
|
+
* beside a trunk that is not `main` is the live/released split (main = what ships, trunk = where
|
|
86
|
+
* sessions land), and declaring "nothing consumes this" over it would hide the release branch.
|
|
87
|
+
*
|
|
88
|
+
* `branches` — every branch name the caller can see (local ∪ remote-tracking), or null/undefined
|
|
89
|
+
* when it cannot list them. Unknown FAILS CLOSED to the old spelling rule (trunk "main"): a
|
|
90
|
+
* non-main trunk is accepted only when a readable branch list proves no `main` sits beside it.
|
|
91
|
+
*
|
|
92
|
+
* Returns null when the invariant holds, else the reason text (no prefix — each caller names its
|
|
93
|
+
* own shape in front of it).
|
|
94
|
+
*/
|
|
95
|
+
function singleTrunkViolation(trunk, branches) {
|
|
96
|
+
if (!trunk) return `no trunk declared, found ${JSON.stringify(trunk)}`;
|
|
97
|
+
if (trunk === 'main') return null;
|
|
98
|
+
if (!Array.isArray(branches)) {
|
|
99
|
+
return `trunk ${JSON.stringify(trunk)} can stand in for "main" only when the branch list is readable `
|
|
100
|
+
+ 'and shows no "main" beside it, and the branch list could not be read';
|
|
101
|
+
}
|
|
102
|
+
if (branches.includes('main')) {
|
|
103
|
+
return `trunk is ${JSON.stringify(trunk)} and a "main" branch exists beside it — that is the `
|
|
104
|
+
+ 'two-branch (live/released) shape, not a single trunk';
|
|
105
|
+
}
|
|
106
|
+
return null;
|
|
107
|
+
}
|
|
108
|
+
|
|
77
109
|
function evaluateNone(ctx) {
|
|
78
110
|
const out = [];
|
|
79
|
-
|
|
111
|
+
const single = singleTrunkViolation(ctx.trunk, ctx.branches);
|
|
112
|
+
if (single) {
|
|
80
113
|
out.push({
|
|
81
114
|
kind: 'fail',
|
|
82
|
-
message: `exposure: none requires trunk
|
|
83
|
-
+ '
|
|
115
|
+
message: `exposure: none requires a single trunk — ${single} — nothing consumes this repo, `
|
|
116
|
+
+ 'so there is no release branch to speak of',
|
|
84
117
|
});
|
|
85
118
|
}
|
|
86
119
|
if (ctx.hasDeployWorkflow) {
|
|
@@ -131,11 +164,12 @@ function evaluateLive(ctx) {
|
|
|
131
164
|
|
|
132
165
|
function evaluateReleasedNoProduction(ctx) {
|
|
133
166
|
const out = [];
|
|
134
|
-
|
|
167
|
+
const single = singleTrunkViolation(ctx.trunk, ctx.branches);
|
|
168
|
+
if (single) {
|
|
135
169
|
out.push({
|
|
136
170
|
kind: 'fail',
|
|
137
|
-
message: `exposure: released with production: null requires trunk
|
|
138
|
-
+
|
|
171
|
+
message: `exposure: released with production: null requires a single trunk — ${single} — `
|
|
172
|
+
+ 'nothing is live, so there is no release branch to speak of',
|
|
139
173
|
});
|
|
140
174
|
}
|
|
141
175
|
if (ctx.deploy !== null && ctx.deploy !== undefined && ctx.deploy !== 'none') {
|
|
@@ -204,4 +238,4 @@ function evaluateReleasedWithProduction(ctx) {
|
|
|
204
238
|
return out;
|
|
205
239
|
}
|
|
206
240
|
|
|
207
|
-
module.exports = { evaluateExposure };
|
|
241
|
+
module.exports = { evaluateExposure, singleTrunkViolation };
|
|
@@ -13,8 +13,9 @@
|
|
|
13
13
|
*
|
|
14
14
|
* Row severities, and the one rule behind them: ✗ (fail, exit 1) means something was INSTALLED and
|
|
15
15
|
* is now stale or unusable; ⚠ means something was simply never set up, which may be a deliberate
|
|
16
|
-
* choice (a machine that only wants the skills needs no fleet list)
|
|
17
|
-
*
|
|
16
|
+
* choice (a machine that only wants the skills needs no fleet list) or just not done YET (no repo
|
|
17
|
+
* registered, no identity vocabulary). A report that failed every skills-only machine — or every
|
|
18
|
+
* correct fresh `--all` install, as it did until #521 — would teach people to ignore its exit code.
|
|
18
19
|
*
|
|
19
20
|
* CommonJS, zero dependencies, runnable as a script: install.sh calls
|
|
20
21
|
* node tools/lib/install-check.js --root <handbook> --colab-home <dir> --home <dir>
|
|
@@ -163,9 +164,9 @@ function checkState({ root, colabHome, home }) {
|
|
|
163
164
|
}
|
|
164
165
|
|
|
165
166
|
/**
|
|
166
|
-
* The fleet: both machine-local registries `colab register` writes.
|
|
167
|
-
*
|
|
168
|
-
*
|
|
167
|
+
* The fleet: both machine-local registries `colab register` writes. Nothing registered is ⚠ whether or
|
|
168
|
+
* not `--fleet` seeded the placeholder list: both are "not set up yet", the state every correct fresh
|
|
169
|
+
* install is in until its first `colab register` (#521). The ⚠ text still names the dead end.
|
|
169
170
|
*/
|
|
170
171
|
function checkFleet({ colabHome }) {
|
|
171
172
|
const rows = [];
|
|
@@ -179,7 +180,9 @@ function checkFleet({ colabHome }) {
|
|
|
179
180
|
if (entries === null && !cfgRepos.length) {
|
|
180
181
|
rows.push({ area: 'fleet', severity: WARN, text: `nothing registered — add each repo: colab register <path>` });
|
|
181
182
|
} else if (entries !== null && !entries.length) {
|
|
182
|
-
|
|
183
|
+
// #521: this is exactly what `--fleet` leaves on a new machine, and the install's own "next" list
|
|
184
|
+
// says to register a repo. Not yet set up, not broken — a ✗ here failed every correct fresh install.
|
|
185
|
+
rows.push({ area: 'fleet', severity: WARN, text: `nothing registered yet — ${txtFile} holds placeholders only, so \`colab update\`/\`colab release-status\` refuse "No repos registered". Next: colab register <path>` });
|
|
183
186
|
} else {
|
|
184
187
|
const locals = (entries || []).filter((e) => e.startsWith('/') || e.startsWith('~'));
|
|
185
188
|
const unmirrored = locals.filter((e) => !cfgRepos.includes(e));
|
|
@@ -196,6 +199,9 @@ function checkFleet({ colabHome }) {
|
|
|
196
199
|
* first hooklet's dependency) and said nothing about the identity vocabulary the second needs — and
|
|
197
200
|
* the second guards publication to a public repo. With no vocabulary it warns and passes every commit.
|
|
198
201
|
* Resolution order mirrors templates/pre-commit-identity exactly.
|
|
202
|
+
*
|
|
203
|
+
* Both dependencies are ⚠, never ✗ (#521): the preflight calls them optional, and a missing one is
|
|
204
|
+
* something not set up yet, not an install gone stale. Symmetric still — neither row is quieter.
|
|
199
205
|
*/
|
|
200
206
|
function checkHooks({ root, colabHome, home, env }) {
|
|
201
207
|
const hp = gitConfig(root, 'core.hooksPath', env);
|
|
@@ -206,7 +212,7 @@ function checkHooks({ root, colabHome, home, env }) {
|
|
|
206
212
|
const rows = [];
|
|
207
213
|
rows.push(isExecutable('gitleaks', env)
|
|
208
214
|
? { area: 'hooks', severity: OK, text: 'gitleaks on PATH — the secret scan runs' }
|
|
209
|
-
: { area: 'hooks', severity:
|
|
215
|
+
: { area: 'hooks', severity: WARN, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
|
|
210
216
|
|
|
211
217
|
let vocab; let src;
|
|
212
218
|
if (env.COLAB_IDENTITY_VOCAB) { vocab = env.COLAB_IDENTITY_VOCAB; src = 'COLAB_IDENTITY_VOCAB'; }
|
|
@@ -215,7 +221,7 @@ function checkHooks({ root, colabHome, home, env }) {
|
|
|
215
221
|
if (vocab.startsWith('~/')) vocab = path.join(home, vocab.slice(2));
|
|
216
222
|
rows.push(readText(vocab) !== null
|
|
217
223
|
? { area: 'hooks', severity: OK, text: `identity vocabulary ${vocab} (${src}) — the identity scan runs` }
|
|
218
|
-
: { area: 'hooks', severity:
|
|
224
|
+
: { area: 'hooks', severity: WARN, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
|
|
219
225
|
return rows;
|
|
220
226
|
}
|
|
221
227
|
|