@futurelastic/colab-handbook 1.12.0-rc.70 → 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 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
@@ -244,10 +245,23 @@ migration hold with or without it.
244
245
  ## Setting up a machine
245
246
 
246
247
  Once per machine. Clone somewhere permanent — the skills are symlinks *into
247
- this working tree*, so whichever branch it has checked out is the version every
248
- session gets; keep it on `main`. `install.sh` checks its prerequisites before it
249
- changes anything, never overwrites what it did not create, and `--dry` prints
250
- the plan first.
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.
251
265
 
252
266
  | Flag | What it does |
253
267
  |---|---|
@@ -257,6 +271,8 @@ the plan first.
257
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. |
258
272
  | `--all` | `--tools --hooks --fleet`. |
259
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`. |
260
276
  | `--dry` | Print what would happen, change nothing. Combines with the flags above. |
261
277
  | `--check` | **Read-only** health report on an earlier install — see below. Takes no other flag; exit 1 on any ✗ row. |
262
278
 
@@ -268,9 +284,11 @@ branch this clone has checked out. The frozen copy never moves on its own:
268
284
  [`tools/README.md`](tools/README.md#install).
269
285
 
270
286
  **The CLI alone, without the skills,** is on npm as
271
- **`@futurelastic/colab-handbook`** — `npx @futurelastic/colab-handbook <command>`,
272
- or `npm i -g @futurelastic/colab-handbook` (`@next` for release candidates). The
273
- command is still `colab`. The skills are not in the package; they install from a
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
274
292
  clone, because they must symlink into `~/.claude/skills/`.
275
293
 
276
294
  ### Checking an install
@@ -287,7 +305,10 @@ which commands it does not dispatch, whether the state file exists, whether
287
305
  anything is registered, whether both pre-commit hooklets can run, and whether
288
306
  `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
289
307
  something installed is stale or unusable; ⚠ means something was never set up,
290
- which may be deliberate. It never refreshes anything.
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.
291
312
 
292
313
  ## Why so little enforcement
293
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)
@@ -242,10 +243,23 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
242
243
  ## Cài đặt máy
243
244
 
244
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ỏ
245
- *thẳng vào working tree này*, nên repo đang checkout nhánh nào thì mọi phiên
246
- dùng đúng bản skill của nhánh đó; hãy để nó ở `main`. `install.sh` kiểm tra đủ
247
- điều kiện trước khi đụng vào gì, không bao giờ ghi đè thứ nó không tạo ra, và
248
- `--dry` in kế hoạch ra trước.
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.
249
263
 
250
264
  | Flag | Làm gì |
251
265
  |---|---|
@@ -255,6 +269,8 @@ dùng đúng bản skill của nhánh đó; hãy để nó ở `main`. `install.
255
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. |
256
270
  | `--all` | `--tools --hooks --fleet`. |
257
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. |
258
274
  | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
259
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 ✗. |
260
276
 
@@ -265,10 +281,11 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
265
281
  --tools` để làm mới. Vì sao lại làm vậy:
266
282
  [`tools/README.md`](tools/README.md#install).
267
283
 
268
- **Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**
269
- — `npx @futurelastic/colab-handbook <lệnh>`, hoặc `npm i -g
270
- @futurelastic/colab-handbook` (`@next` cho bản ứng viên). Lệnh gõ vẫn là
271
- `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
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
272
289
  symlink vào `~/.claude/skills/`.
273
290
 
274
291
  ### Kiểm tra bản cài
@@ -284,8 +301,11 @@ colab update # các bản copy có đóng dấu đã tụt lại, k
284
301
  nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
285
302
  hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
286
303
  khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
287
- hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý. Nó
288
- không bao giờ tự làm mới gì cả.
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ó.
289
309
 
290
310
  ## Vì sao ép buộc ít vậy
291
311
 
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.70"
35
+ "version": "1.12.0-rc.71"
36
36
  }
@@ -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). A report that failed every
17
- * skills-only machine would teach people to ignore its exit code.
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. A repos.txt that exists with no
167
- * live entry is the `--fleet` dead end — seeded from placeholders, and the next command refuses with
168
- * "No repos registered". That one is a ✗; never having asked for a fleet is a ⚠.
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
- rows.push({ area: 'fleet', severity: FAIL, text: `${txtFile} exists with no live entry (placeholders only) — \`colab update\`/\`colab release-status\` refuse "No repos registered". Fix: colab register <path>` });
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: FAIL, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
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: FAIL, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
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