@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 +31 -10
- package/README.vi.md +32 -12
- package/package.json +1 -1
- 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
|
|
@@ -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
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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
|
|
272
|
-
|
|
273
|
-
|
|
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
|
|
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
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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
|
-
|
|
270
|
-
|
|
271
|
-
|
|
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ố
|
|
288
|
-
|
|
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
|
@@ -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
|
|