@futurelastic/colab-handbook 1.13.0-rc.11 → 1.13.0-rc.12
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 +36 -6
- package/README.vi.md +37 -7
- package/package.json +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/install-check.js +72 -1
package/README.md
CHANGED
|
@@ -13,14 +13,15 @@ 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, from the newest release; --dry shows it first
|
|
16
|
+
cd ~/code/colab-handbook && ./install.sh --all # asks which coding agent gets the 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
|
|
20
20
|
colab register # adds the repo to this machine's fleet list
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
Then, in an agent session in that repo, run `/code-start <issue-number
|
|
23
|
+
Then, in an agent session in that repo, run `/code-start <issue-number>` (Claude
|
|
24
|
+
Code; in Codex, `$code-start` — see [*Choose your engine*](#choose-your-engine)). With an
|
|
24
25
|
agent at hand, `/handbook-sync` replaces the last three commands and also does
|
|
25
26
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
26
27
|
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
@@ -244,7 +245,8 @@ migration hold with or without it.
|
|
|
244
245
|
| [`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. Nothing is called remotely — copy it, edit it, own it. |
|
|
245
246
|
| [`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). |
|
|
246
247
|
| [`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. What each check means: [`audit/README.md`](audit/README.md). |
|
|
247
|
-
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session).
|
|
248
|
+
| [`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. |
|
|
249
|
+
| [`engines/`](engines/) | One small data file per coding agent: where its user-level skills go, how a skill is invoked, what it supports. Adding an engine is adding a file — [`engines/README.md`](engines/README.md). |
|
|
248
250
|
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
|
|
249
251
|
|
|
250
252
|
## Setting up a machine
|
|
@@ -268,9 +270,36 @@ Later moves are explicit:
|
|
|
268
270
|
A clone with uncommitted changes is never moved, and a re-run without either
|
|
269
271
|
flag keeps whatever is checked out.
|
|
270
272
|
|
|
273
|
+
### Choose your engine
|
|
274
|
+
|
|
275
|
+
The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
|
|
276
|
+
coding agent that reads skills can run them. What differs is **where each
|
|
277
|
+
agent looks for them**, so the install asks. At a terminal, `./install.sh`
|
|
278
|
+
lists the engines it knows and lets you pick one or more, with *other: give a
|
|
279
|
+
path* last. Unattended, say it with a flag:
|
|
280
|
+
|
|
281
|
+
```sh
|
|
282
|
+
./install.sh --engine claude # Claude Code → ~/.claude/skills
|
|
283
|
+
./install.sh --engine claude,codex # both
|
|
284
|
+
./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
| Engine | Skills folder | Invoke | Before the skills work there |
|
|
288
|
+
|---|---|---|---|
|
|
289
|
+
| 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. |
|
|
290
|
+
| 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. |
|
|
291
|
+
| 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`. |
|
|
292
|
+
|
|
293
|
+
A re-run with no flag and no terminal keeps every engine it finds already
|
|
294
|
+
linked, so an existing machine changes nothing. Finding none, it installs for
|
|
295
|
+
Claude Code and says so. The per-engine facts live in [`engines/`](engines/),
|
|
296
|
+
one file each — that folder is the source for the table above.
|
|
297
|
+
|
|
271
298
|
| Flag | What it does |
|
|
272
299
|
|---|---|
|
|
273
|
-
| *(none)* | Symlink `skills/` into
|
|
300
|
+
| *(none)* | Symlink `skills/` into each chosen engine'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 engine*](#choose-your-engine)). |
|
|
301
|
+
| `--engine <id>[,<id>]` | Install for these engines (`claude`, `codex` — the files in `engines/`), no question asked. |
|
|
302
|
+
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
274
303
|
| `--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. |
|
|
275
304
|
| `--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)). |
|
|
276
305
|
| `--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. |
|
|
@@ -294,7 +323,7 @@ yet, so the default `latest` tag holds only a placeholder; install from
|
|
|
294
323
|
**`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
|
|
295
324
|
<command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
|
|
296
325
|
still `colab`. The skills are not in the package; they install from a
|
|
297
|
-
clone, because they
|
|
326
|
+
clone, because they are symlinks into its working tree.
|
|
298
327
|
|
|
299
328
|
### Checking an install
|
|
300
329
|
|
|
@@ -305,7 +334,8 @@ node audit/audit.mjs # a conformance report across every registered repo
|
|
|
305
334
|
colab update # stamped copies that fell behind, the frozen CLI included
|
|
306
335
|
```
|
|
307
336
|
|
|
308
|
-
`--check` reports
|
|
337
|
+
`--check` reports, per engine, how many skills are linked, missing or broken,
|
|
338
|
+
plus that engine's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
|
|
309
339
|
which commands it does not dispatch, whether the state file exists, whether
|
|
310
340
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
311
341
|
`notifyUrl` is unset while a local observer declared an endpoint. ✗ means
|
package/README.vi.md
CHANGED
|
@@ -12,14 +12,15 @@ 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 #
|
|
15
|
+
cd ~/code/colab-handbook && ./install.sh --all # hỏi agent nào nhận skill; + 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
|
|
19
19
|
colab register # đưa repo vào danh sách fleet của máy này
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue
|
|
22
|
+
Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>` (Claude
|
|
23
|
+
Code; trong Codex là `$code-start` — xem [*Chọn engine*](#chọn-engine)). Có agent
|
|
23
24
|
trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
24
25
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
25
26
|
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
@@ -243,7 +244,8 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
243
244
|
| [`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. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
|
|
244
245
|
| [`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). |
|
|
245
246
|
| [`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. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
246
|
-
| [`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). `install.sh`
|
|
247
|
+
| [`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. |
|
|
248
|
+
| [`engines/`](engines/) | Mỗi coding agent 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 engine là thêm một file — [`engines/README.md`](engines/README.md). |
|
|
247
249
|
| [`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ứ. |
|
|
248
250
|
|
|
249
251
|
## Cài đặt máy
|
|
@@ -267,9 +269,36 @@ sau đều phải chủ động:
|
|
|
267
269
|
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
268
270
|
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
269
271
|
|
|
272
|
+
### Chọn engine
|
|
273
|
+
|
|
274
|
+
Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
|
|
275
|
+
agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
|
|
276
|
+
skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
|
|
277
|
+
engine 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
|
|
278
|
+
path*. Chạy không người trông thì nói bằng flag:
|
|
279
|
+
|
|
280
|
+
```sh
|
|
281
|
+
./install.sh --engine claude # Claude Code → ~/.claude/skills
|
|
282
|
+
./install.sh --engine claude,codex # cả hai
|
|
283
|
+
./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
| Engine | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
|
|
287
|
+
|---|---|---|---|
|
|
288
|
+
| 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ó. |
|
|
289
|
+
| 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. |
|
|
290
|
+
| 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`. |
|
|
291
|
+
|
|
292
|
+
Chạy lại không flag và không có terminal thì giữ mọi engine đã thấy được link
|
|
293
|
+
sẵn, nên máy đã cài không thay đổi gì. Không thấy engine nào thì cài cho Claude
|
|
294
|
+
Code và nói rõ điều đó. Thông tin từng engine nằm trong [`engines/`](engines/),
|
|
295
|
+
mỗi engine một file — thư mục đó là nguồn của bảng trên.
|
|
296
|
+
|
|
270
297
|
| Flag | Làm gì |
|
|
271
298
|
|---|---|
|
|
272
|
-
| *(không có)* | Symlink `skills/` vào
|
|
299
|
+
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng engine đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn engine*](#chọn-engine)). |
|
|
300
|
+
| `--engine <id>[,<id>]` | Cài cho các engine này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
|
|
301
|
+
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
273
302
|
| `--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ó. |
|
|
274
303
|
| `--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)). |
|
|
275
304
|
| `--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. |
|
|
@@ -291,8 +320,8 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
|
|
|
291
320
|
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à
|
|
292
321
|
bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
|
|
293
322
|
@futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
|
|
294
|
-
@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ì
|
|
295
|
-
symlink vào
|
|
323
|
+
@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ì chúng là
|
|
324
|
+
symlink trỏ vào working tree của bản clone đó.
|
|
296
325
|
|
|
297
326
|
### Kiểm tra bản cài
|
|
298
327
|
|
|
@@ -303,7 +332,8 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
|
303
332
|
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
304
333
|
```
|
|
305
334
|
|
|
306
|
-
`--check` báo
|
|
335
|
+
`--check` báo theo từng engine: bao nhiêu skill đã link, thiếu hay hỏng, kèm
|
|
336
|
+
các lưu ý riêng của engine đó (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
|
|
307
337
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
308
338
|
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
|
|
309
339
|
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
package/package.json
CHANGED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* engines/<id>.conf — one data file per coding agent the skills can be installed for (#530).
|
|
4
|
+
*
|
|
5
|
+
* The format is deliberately trivial (`key: value` lines, `#` comments, `note:`/`caveat:`
|
|
6
|
+
* repeatable) so install.sh can read it with sed, without node — a skills-only install must not
|
|
7
|
+
* need the CLI's runtime. This module is the JS reader for `install.sh --check`; the two readers
|
|
8
|
+
* must agree, and install-sh.test.js holds them to it. engines/README.md is the format's doc.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
const fs = require('fs');
|
|
12
|
+
const path = require('path');
|
|
13
|
+
|
|
14
|
+
const REPEATABLE = new Set(['note', 'caveat']);
|
|
15
|
+
|
|
16
|
+
/** Parse one conf file's text. First occurrence of a single-valued key wins, as `sed …;q` does. */
|
|
17
|
+
function parseConf(text) {
|
|
18
|
+
const out = { note: [], caveat: [] };
|
|
19
|
+
for (const raw of String(text).split(/\r?\n/)) {
|
|
20
|
+
if (/^\s*#/.test(raw)) continue;
|
|
21
|
+
const m = /^([a-z_]+):[ \t]*(.*)$/.exec(raw);
|
|
22
|
+
if (!m) continue;
|
|
23
|
+
const [, key, value] = m;
|
|
24
|
+
if (REPEATABLE.has(key)) out[key].push(value);
|
|
25
|
+
else if (!(key in out)) out[key] = value;
|
|
26
|
+
}
|
|
27
|
+
return out;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** `~/x` → <home>/x. Same rule as install.sh's expand_home for the values a conf file can hold. */
|
|
31
|
+
function expandHome(p, home) {
|
|
32
|
+
if (p === '~') return home;
|
|
33
|
+
if (p.startsWith('~/')) return path.join(home, p.slice(2));
|
|
34
|
+
return p;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Every engine in <root>/engines, in file order (the order install.sh's prompt numbers them). */
|
|
38
|
+
function listEngines(root) {
|
|
39
|
+
const dir = path.join(root, 'engines');
|
|
40
|
+
let files = [];
|
|
41
|
+
try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.conf')).sort(); } catch (_) { return []; }
|
|
42
|
+
return files.map((f) => ({ id: f.slice(0, -'.conf'.length), ...parseConf(fs.readFileSync(path.join(dir, f), 'utf8')) }));
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Folders given with --skills-dir on an earlier install, one per line in <COLAB_HOME>/skills-dirs. */
|
|
46
|
+
function rememberedDirs(colabHome) {
|
|
47
|
+
let text = '';
|
|
48
|
+
try { text = fs.readFileSync(path.join(colabHome, 'skills-dirs'), 'utf8'); } catch (_) { return []; }
|
|
49
|
+
return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
module.exports = { parseConf, expandHome, listEngines, rememberedDirs };
|
|
@@ -27,6 +27,7 @@ const path = require('path');
|
|
|
27
27
|
const { execFileSync } = require('child_process');
|
|
28
28
|
const stamp = require('./stamp');
|
|
29
29
|
const notifyEndpoint = require('./notify-endpoint');
|
|
30
|
+
const engines = require('./engines');
|
|
30
31
|
|
|
31
32
|
const OK = 'ok';
|
|
32
33
|
const WARN = 'warn';
|
|
@@ -141,6 +142,75 @@ function checkFrozen({ root, colabHome }) {
|
|
|
141
142
|
return rows;
|
|
142
143
|
}
|
|
143
144
|
|
|
145
|
+
/**
|
|
146
|
+
* The skills, per engine (#530). For every engine in engines/ with a folder of its own, plus every
|
|
147
|
+
* folder an earlier --skills-dir remembered: how many of this clone's skills are linked there, which
|
|
148
|
+
* are missing (a skill added since the install — re-run it), which links are broken (they point into
|
|
149
|
+
* this clone's skills/ at a folder that no longer exists — ✗, installed and now unusable), and which
|
|
150
|
+
* names something else holds (⚠, possibly a deliberate local variant; install.sh never clobbers it).
|
|
151
|
+
*
|
|
152
|
+
* An engine with nothing linked is "not installed for it" — one ✓ line naming them, because a
|
|
153
|
+
* Claude-only machine is a correct machine. Only when NO engine has the skills is that a ⚠.
|
|
154
|
+
* The engine's own `caveat:` lines become ⚠ rows while it is installed: they are what the user must
|
|
155
|
+
* do there for the skills to work (a sandbox with no network, say), and they stay true until done.
|
|
156
|
+
*/
|
|
157
|
+
function checkSkills({ root, home, colabHome }) {
|
|
158
|
+
const src = path.join(root, 'skills');
|
|
159
|
+
let skills = [];
|
|
160
|
+
try { skills = fs.readdirSync(src, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort(); } catch (_) { /* none */ }
|
|
161
|
+
const all = engines.listEngines(root);
|
|
162
|
+
const byId = Object.fromEntries(all.map((e) => [e.id, e]));
|
|
163
|
+
const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
|
|
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 engine', note: [], caveat: [] }, dir });
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
const rows = [];
|
|
169
|
+
const notInstalled = [];
|
|
170
|
+
for (const { e, dir } of targets) {
|
|
171
|
+
const linked = []; const missing = []; const broken = []; const foreign = [];
|
|
172
|
+
for (const name of skills) {
|
|
173
|
+
const dest = path.join(dir, name);
|
|
174
|
+
let st;
|
|
175
|
+
try { st = fs.lstatSync(dest); } catch (_) { missing.push(name); continue; }
|
|
176
|
+
if (!st.isSymbolicLink()) { foreign.push(name); continue; }
|
|
177
|
+
const to = path.resolve(dir, fs.readlinkSync(dest));
|
|
178
|
+
if (to === path.join(src, name)) linked.push(name);
|
|
179
|
+
else foreign.push(name);
|
|
180
|
+
}
|
|
181
|
+
// Links into this clone's skills/ whose target is gone: a skill removed or renamed upstream.
|
|
182
|
+
let entries = [];
|
|
183
|
+
try { entries = fs.readdirSync(dir); } catch (_) { /* folder absent */ }
|
|
184
|
+
for (const n of entries) {
|
|
185
|
+
const p = path.join(dir, n);
|
|
186
|
+
try {
|
|
187
|
+
if (!fs.lstatSync(p).isSymbolicLink()) continue;
|
|
188
|
+
const to = path.resolve(dir, fs.readlinkSync(p));
|
|
189
|
+
if (to.startsWith(src + path.sep) && !fs.existsSync(to)) broken.push(n);
|
|
190
|
+
} catch (_) { /* unreadable entry — not ours to judge */ }
|
|
191
|
+
}
|
|
192
|
+
const who = `${e.id} (${e.label || e.id}) ${dir}`;
|
|
193
|
+
if (!linked.length && !broken.length) { notInstalled.push(e.id === 'generic' ? dir : `${e.id} (${e.label || e.id})`); continue; }
|
|
194
|
+
const parts = [`${linked.length}/${skills.length} linked`];
|
|
195
|
+
if (missing.length) parts.push(`missing ${missing.join(', ')} — re-run ./install.sh${e.id === 'generic' ? '' : ` --engine ${e.id}`}`);
|
|
196
|
+
if (foreign.length) parts.push(`held by something else (left as is): ${foreign.join(', ')}`);
|
|
197
|
+
if (broken.length) parts.push(`BROKEN links to skills that no longer exist: ${broken.join(', ')} — remove them: ${broken.map((b) => `rm '${path.join(dir, b)}'`).join('; ')}`);
|
|
198
|
+
rows.push({
|
|
199
|
+
area: 'skills',
|
|
200
|
+
severity: broken.length ? FAIL : (missing.length || foreign.length) ? WARN : OK,
|
|
201
|
+
text: `${who}: ${parts.join('; ')}`,
|
|
202
|
+
});
|
|
203
|
+
for (const c of e.caveat || []) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: ${c}` });
|
|
204
|
+
if (e.verified && /^no\b/.test(e.verified)) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: engine file not verified by a run yet — ${e.verified.replace(/^no\s*[—-]?\s*/, '')}` });
|
|
205
|
+
}
|
|
206
|
+
if (!rows.length) {
|
|
207
|
+
rows.push({ area: 'skills', severity: WARN, text: `not linked for any engine — ./install.sh asks which (or --engine <id> / --skills-dir <path>)` });
|
|
208
|
+
} else if (notInstalled.length) {
|
|
209
|
+
rows.push({ area: 'skills', severity: OK, text: `not installed for: ${notInstalled.join(', ')} — fine if deliberate; ./install.sh --engine <id> adds one` });
|
|
210
|
+
}
|
|
211
|
+
return rows;
|
|
212
|
+
}
|
|
213
|
+
|
|
144
214
|
/** The state file. The CLI creates it lazily, so a consumer reading it early saw an error, not an empty fleet. */
|
|
145
215
|
function checkState({ root, colabHome, home }) {
|
|
146
216
|
const file = path.join(colabHome, 'state.json');
|
|
@@ -245,6 +315,7 @@ function checkNotify({ colabHome }) {
|
|
|
245
315
|
function runChecks(opts) {
|
|
246
316
|
const o = { env: process.env, ...opts };
|
|
247
317
|
return [
|
|
318
|
+
...checkSkills(o),
|
|
248
319
|
checkLink(o),
|
|
249
320
|
...checkFrozen(o),
|
|
250
321
|
checkState(o),
|
|
@@ -280,5 +351,5 @@ if (require.main === module) {
|
|
|
280
351
|
|
|
281
352
|
module.exports = {
|
|
282
353
|
OK, WARN, FAIL,
|
|
283
|
-
dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
|
|
354
|
+
dispatchedCommands, checkSkills, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
|
|
284
355
|
};
|