@futurelastic/colab-handbook 1.13.0-rc.2 → 1.13.0-rc.21
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 +54 -19
- package/README.vi.md +58 -22
- package/package.json +2 -1
- package/templates/release-auto.yml +68 -4
- package/tools/colab +251 -45
- package/tools/lib/claim-identity.js +38 -0
- package/tools/lib/codec/claim.js +8 -3
- package/tools/lib/codec/labels.js +7 -0
- package/tools/lib/codec/samples.json +16 -0
- package/tools/lib/engines.js +52 -0
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +9 -3
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/scratch-dirs.js +13 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/shipguard.js +12 -1
package/README.md
CHANGED
|
@@ -13,15 +13,16 @@ 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
|
|
24
|
-
|
|
23
|
+
Then, in an agent session in that repo, run the `code-start` skill with an issue
|
|
24
|
+
number — each engine has its own way to invoke a skill, see [*Choose your engine*](#choose-your-engine).
|
|
25
|
+
With an agent at hand, the `handbook-sync` skill 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
|
|
27
28
|
packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
|
|
@@ -94,25 +95,30 @@ with no agent and no other tool.
|
|
|
94
95
|
|
|
95
96
|
## Your first session
|
|
96
97
|
|
|
97
|
-
A unit of work goes round one loop. Each step is a skill, invoked in an
|
|
98
|
-
session
|
|
99
|
-
[`skills/`](skills/).
|
|
98
|
+
A unit of work goes round one loop. Each step is a skill, invoked by name in an
|
|
99
|
+
agent session (the syntax is the engine's — [*Choose your engine*](#choose-your-engine)),
|
|
100
|
+
or followed by hand from [`skills/`](skills/).
|
|
100
101
|
|
|
101
102
|
| Step | Skill | Who runs it | What it leaves behind |
|
|
102
103
|
|---|---|---|---|
|
|
103
|
-
| 1. Pick |
|
|
104
|
-
| 2. Open |
|
|
104
|
+
| 1. Pick | `code-triage` | coordinator | the ready work in order, `group:` labels on issues that must share a branch, `needs-plan` on hard ones, the start commands |
|
|
105
|
+
| 2. Open | `code-start <N>` | implementer | the issue claimed, a branch cut from trunk and pushed, a worktree, a short plan file |
|
|
105
106
|
| 3. Work | — | implementer | commits on the branch |
|
|
106
|
-
| 4. Hand off |
|
|
107
|
-
| 5. Merge |
|
|
108
|
-
| 6. Clean up |
|
|
109
|
-
| 7. Release | release workflow, or
|
|
107
|
+
| 4. Hand off | `code-wrap` | implementer | what was learned written onto the Issue, the repo's gate run, the branch pushed — then it **stops** |
|
|
108
|
+
| 5. Merge | `code-ship` | coordinator, after a human go | one squash commit on trunk with `Closes #N`, evidence on each issue, claims released, the worktree removed |
|
|
109
|
+
| 6. Clean up | `code-sweep` | coordinator | finished work shipped, stale claims and worktrees cleared |
|
|
110
|
+
| 7. Release | release workflow, or `release-rung` | automatic, or a human where a tag deploys | a candidate tag, then the final after a test period — only where the repo's `exposure` has releases |
|
|
110
111
|
|
|
111
112
|
Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
|
|
112
113
|
`code-start` when flagged), `handbook-sync` (bring one repo up to the current
|
|
113
114
|
handbook), and `migration-review` (review a branch's migrations, for whoever a
|
|
114
115
|
repo binds to that role).
|
|
115
116
|
|
|
117
|
+
**Running the loop by hand at a terminal?** With no `--session`, `colab` names
|
|
118
|
+
you `person:<git user.email>/<host token>`, so claims and ship evidence say who
|
|
119
|
+
you are. If you work on several units at once from separate shells, give each
|
|
120
|
+
shell its own `COLAB_SESSION=<any stable id>` so their holds stay apart.
|
|
121
|
+
|
|
116
122
|
**Words you will meet:**
|
|
117
123
|
|
|
118
124
|
- **Trunk** — the branch sessions merge into (`trunk:` in `project.yml`).
|
|
@@ -160,7 +166,7 @@ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
|
|
|
160
166
|
|
|
161
167
|
## Adopting it into a repo
|
|
162
168
|
|
|
163
|
-
**The default route: run
|
|
169
|
+
**The default route: run the `handbook-sync` skill in an agent session inside the repo.**
|
|
164
170
|
It sees that nothing is adopted yet and drives adoption to the end — the
|
|
165
171
|
descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
|
|
166
172
|
the templates, and registration on this machine. Run later, the same skill
|
|
@@ -239,7 +245,8 @@ migration hold with or without it.
|
|
|
239
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. |
|
|
240
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). |
|
|
241
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). |
|
|
242
|
-
| [`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). |
|
|
243
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. |
|
|
244
251
|
|
|
245
252
|
## Setting up a machine
|
|
@@ -263,14 +270,41 @@ Later moves are explicit:
|
|
|
263
270
|
A clone with uncommitted changes is never moved, and a re-run without either
|
|
264
271
|
flag keeps whatever is checked out.
|
|
265
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
|
+
|
|
266
298
|
| Flag | What it does |
|
|
267
299
|
|---|---|
|
|
268
|
-
| *(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. |
|
|
269
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. |
|
|
270
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)). |
|
|
271
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. |
|
|
272
306
|
| `--all` | `--tools --hooks --fleet`. |
|
|
273
|
-
| `--notify-url <url>` |
|
|
307
|
+
| `--notify-url <url>` | Add `<url>` to `notifyUrl` in `~/.colab/config.json` if the key lacks it; an existing entry is never removed or rewritten. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
274
308
|
| `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
|
|
275
309
|
| `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
|
|
276
310
|
| `--dry` | Print what would happen, change nothing. Combines with the flags above. |
|
|
@@ -289,7 +323,7 @@ yet, so the default `latest` tag holds only a placeholder; install from
|
|
|
289
323
|
**`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
|
|
290
324
|
<command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
|
|
291
325
|
still `colab`. The skills are not in the package; they install from a
|
|
292
|
-
clone, because they
|
|
326
|
+
clone, because they are symlinks into its working tree.
|
|
293
327
|
|
|
294
328
|
### Checking an install
|
|
295
329
|
|
|
@@ -300,10 +334,11 @@ node audit/audit.mjs # a conformance report across every registered repo
|
|
|
300
334
|
colab update # stamped copies that fell behind, the frozen CLI included
|
|
301
335
|
```
|
|
302
336
|
|
|
303
|
-
`--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
|
|
304
339
|
which commands it does not dispatch, whether the state file exists, whether
|
|
305
340
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
306
|
-
`notifyUrl` is unset while a local observer declared
|
|
341
|
+
`notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
|
|
307
342
|
something installed is stale or unusable; ⚠ means something was never set up,
|
|
308
343
|
which may be deliberate or just not done yet — so a correct fresh install, with
|
|
309
344
|
no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
|
package/README.vi.md
CHANGED
|
@@ -12,15 +12,16 @@ 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
|
|
23
|
-
|
|
22
|
+
Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
|
|
23
|
+
mỗi engine có cách gọi skill riêng, xem [*Chọn engine*](#chọn-engine). Có agent
|
|
24
|
+
trong tay thì skill `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ũ
|
|
26
27
|
hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
|
|
@@ -93,25 +94,31 @@ khác.
|
|
|
93
94
|
|
|
94
95
|
## Phiên làm việc đầu tiên
|
|
95
96
|
|
|
96
|
-
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên
|
|
97
|
-
|
|
98
|
-
[`skills/`](skills/).
|
|
97
|
+
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
|
|
98
|
+
agent (cú pháp gọi là của engine — [*Chọn engine*](#chọn-engine)), hoặc tự làm
|
|
99
|
+
theo bằng tay từ [`skills/`](skills/).
|
|
99
100
|
|
|
100
101
|
| Bước | Skill | Ai chạy | Để lại gì |
|
|
101
102
|
|---|---|---|---|
|
|
102
|
-
| 1. Chọn |
|
|
103
|
-
| 2. Mở |
|
|
103
|
+
| 1. Chọn | `code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
|
|
104
|
+
| 2. Mở | `code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
|
|
104
105
|
| 3. Làm | — | thợ | commit trên nhánh |
|
|
105
|
-
| 4. Bàn giao |
|
|
106
|
-
| 5. Merge |
|
|
107
|
-
| 6. Dọn |
|
|
108
|
-
| 7. Release | release workflow, hoặc
|
|
106
|
+
| 4. Bàn giao | `code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
|
|
107
|
+
| 5. Merge | `code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
|
|
108
|
+
| 6. Dọn | `code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
|
|
109
|
+
| 7. Release | release workflow, hoặc `release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
|
|
109
110
|
|
|
110
111
|
Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
|
|
111
112
|
`code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
|
|
112
113
|
nhất), và `migration-review` (review migration của một nhánh, cho người/agent
|
|
113
114
|
được repo gán vai đó).
|
|
114
115
|
|
|
116
|
+
**Tự chạy vòng này bằng tay ở terminal?** Không có `--session` thì `colab` đặt
|
|
117
|
+
tên bạn là `person:<git user.email>/<host token>`, nên claim và bằng chứng ship
|
|
118
|
+
đều ghi rõ ai làm. Nếu làm nhiều đơn vị việc cùng lúc ở các shell khác nhau,
|
|
119
|
+
đặt cho mỗi shell một `COLAB_SESSION=<id ổn định bất kỳ>` để các hold không lẫn
|
|
120
|
+
vào nhau.
|
|
121
|
+
|
|
115
122
|
**Mấy từ sẽ gặp:**
|
|
116
123
|
|
|
117
124
|
- **Trunk** — nhánh các phiên merge vào (`trunk:` trong `project.yml`).
|
|
@@ -159,8 +166,8 @@ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
|
159
166
|
|
|
160
167
|
## Adopt vào một repo
|
|
161
168
|
|
|
162
|
-
**Đường mặc định: chạy
|
|
163
|
-
đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
|
|
169
|
+
**Đường mặc định: chạy skill `handbook-sync` trong một phiên agent ngay trong
|
|
170
|
+
repo đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
|
|
164
171
|
`colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
|
|
165
172
|
này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên bản handbook mới
|
|
166
173
|
nhất mà không làm mất phần bạn đã sửa.
|
|
@@ -237,7 +244,8 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
237
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. |
|
|
238
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). |
|
|
239
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). |
|
|
240
|
-
| [`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). |
|
|
241
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ứ. |
|
|
242
250
|
|
|
243
251
|
## Cài đặt máy
|
|
@@ -261,14 +269,41 @@ sau đều phải chủ động:
|
|
|
261
269
|
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
262
270
|
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
263
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
|
+
|
|
264
297
|
| Flag | Làm gì |
|
|
265
298
|
|---|---|
|
|
266
|
-
| *(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. |
|
|
267
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ó. |
|
|
268
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)). |
|
|
269
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. |
|
|
270
305
|
| `--all` | `--tools --hooks --fleet`. |
|
|
271
|
-
| `--notify-url <url>` |
|
|
306
|
+
| `--notify-url <url>` | Thêm `<url>` vào `notifyUrl` trong `~/.colab/config.json` nếu khoá đó chưa có URL này; không bao giờ xoá hay ghi đè mục đã có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
272
307
|
| `--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
308
|
| `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
|
|
274
309
|
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
|
|
@@ -285,8 +320,8 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
|
|
|
285
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à
|
|
286
321
|
bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
|
|
287
322
|
@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ì
|
|
289
|
-
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 đó.
|
|
290
325
|
|
|
291
326
|
### Kiểm tra bản cài
|
|
292
327
|
|
|
@@ -297,10 +332,11 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
|
297
332
|
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
298
333
|
```
|
|
299
334
|
|
|
300
|
-
`--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
|
|
301
337
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
302
|
-
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống
|
|
303
|
-
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
338
|
+
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
|
|
339
|
+
thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
304
340
|
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
341
|
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
342
|
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
|
package/package.json
CHANGED
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"tools/colab",
|
|
18
18
|
"tools/lib/*.js",
|
|
19
19
|
"!tools/lib/*.test.js",
|
|
20
|
+
"!tools/lib/refusal-sites.js",
|
|
20
21
|
"tools/lib/tracker-scenarios.json",
|
|
21
22
|
"tools/lib/codec/*.js",
|
|
22
23
|
"tools/lib/codec/*.d.ts",
|
|
@@ -32,5 +33,5 @@
|
|
|
32
33
|
"engines": {
|
|
33
34
|
"node": ">=18"
|
|
34
35
|
},
|
|
35
|
-
"version": "1.13.0-rc.
|
|
36
|
+
"version": "1.13.0-rc.21"
|
|
36
37
|
}
|
|
@@ -20,6 +20,9 @@
|
|
|
20
20
|
# hand-off where
|
|
21
21
|
# the final is a
|
|
22
22
|
# human's)
|
|
23
|
+
# an hourly schedule (#547) — the cut colab release cut --auto, only when main's head
|
|
24
|
+
# only, never promote or finalize has no tag AND the fetched CLI moved in the last
|
|
25
|
+
# RETRY_WINDOW_MINUTES (or a run here was displaced)
|
|
23
26
|
# workflow_dispatch all three, in that order
|
|
24
27
|
# any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
|
|
25
28
|
# project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
|
|
@@ -115,6 +118,23 @@
|
|
|
115
118
|
# pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
|
|
116
119
|
# applies to your deploy workflows exactly as before.
|
|
117
120
|
#
|
|
121
|
+
# A REFUSAL THE HANDBOOK FIXES IS RETRIED WITHIN THE HOUR (#547). A cut can be refused by a defect in
|
|
122
|
+
# the colab CLI rather than in your repo — a false positive in one of its checks. The fix reaches you
|
|
123
|
+
# when HANDBOOK_REF's channel moves, and nothing in your repo changes, so neither trigger above fires:
|
|
124
|
+
# the candidate would wait for your next merge or the next daily run (measured: ~2.5 h until a person
|
|
125
|
+
# dispatched it by hand, ~22 h otherwise). So an hourly run re-tries the CUT, and only the cut, when:
|
|
126
|
+
# - main's head carries no release tag yet (a head that has one has nothing to retry), and
|
|
127
|
+
# - the CLI this run fetched reached HANDBOOK_REF within RETRY_WINDOW_MINUTES — read from the date of
|
|
128
|
+
# the release tag at that commit (when the channel moved onto it), else the commit's own date; or
|
|
129
|
+
# - the newest other run of this workflow at main's head was cancelled. An hourly run shares the
|
|
130
|
+
# `release-auto` concurrency group, and GitHub cancels a PENDING run in a group when a newer one
|
|
131
|
+
# queues — so an hourly run can displace the very run a merge started. It then does that run's cut.
|
|
132
|
+
# Every other hourly run checks those and stops: no cut, no promotion, no finalize, so a held head is
|
|
133
|
+
# not tagged sooner than the daily run would tag it, and a standing refusal is not re-announced every
|
|
134
|
+
# hour. Nothing is stored between runs; the facts are re-read each time. EDIT: the cron string inside
|
|
135
|
+
# RETRY_RUN (release job env) must stay byte-identical to the hourly `cron:` line, or no run is
|
|
136
|
+
# recognised as a retry run — and the hourly run would then promote and finalize every hour.
|
|
137
|
+
#
|
|
118
138
|
# A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
|
|
119
139
|
# failed) is the ordinary output of most runs; it is printed to the run summary as a
|
|
120
140
|
# warning and the job stays green, so a refusal never paints main red for `colab ship`.
|
|
@@ -170,6 +190,9 @@ on:
|
|
|
170
190
|
# EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
|
|
171
191
|
# hour is when scheduled runs queue longest.
|
|
172
192
|
- cron: "17 3 * * *"
|
|
193
|
+
# #547: the hourly RETRY run — cut only, only when the CLI moved or a run was displaced (header,
|
|
194
|
+
# "A REFUSAL THE HANDBOOK FIXES"). Keep it byte-identical to the string in RETRY_RUN (release job env).
|
|
195
|
+
- cron: "47 * * * *"
|
|
173
196
|
workflow_dispatch:
|
|
174
197
|
# #474: a DRY RUN for a fix branch — see "DRY RUN ON A FIX BRANCH" in the header. A dispatch on
|
|
175
198
|
# any ref other than main is dry whether or not this is set; on main it is opt-in.
|
|
@@ -263,6 +286,12 @@ jobs:
|
|
|
263
286
|
# Never on workflow_run or schedule. Every write below is off when it is.
|
|
264
287
|
# EDIT: if your trunk is not `main`, name it here too (the same branch as `ref:` below).
|
|
265
288
|
DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref_name != 'main') }}
|
|
289
|
+
# #547: 'true' on the hourly retry run. EDIT: the cron string here is byte-identical to the hourly
|
|
290
|
+
# `cron:` under `on.schedule`.
|
|
291
|
+
RETRY_RUN: ${{ github.event_name == 'schedule' && github.event.schedule == '47 * * * *' }}
|
|
292
|
+
# EDIT: how recent a move of the CLI still earns a retry. Two hourly runs plus slack, so one
|
|
293
|
+
# scheduled run GitHub drops under load does not lose the retry; a second retry is a no-op.
|
|
294
|
+
RETRY_WINDOW_MINUTES: "130"
|
|
266
295
|
steps:
|
|
267
296
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
268
297
|
with:
|
|
@@ -334,13 +363,46 @@ jobs:
|
|
|
334
363
|
git config user.name "github-actions[bot]"
|
|
335
364
|
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
|
336
365
|
|
|
366
|
+
# #547: on the hourly retry run only — decide whether a cut is worth re-trying (header, "A REFUSAL
|
|
367
|
+
# THE HANDBOOK FIXES"). Ends green either way; retry=true lets the cut step below run.
|
|
368
|
+
- name: Retry a refused cut once the CLI moved (#547)
|
|
369
|
+
id: retry
|
|
370
|
+
if: env.RETRY_RUN == 'true'
|
|
371
|
+
run: |
|
|
372
|
+
set -uo pipefail
|
|
373
|
+
eval "$RETRY_TRANSIENT"
|
|
374
|
+
decide() { echo "retry=$1" >> "$GITHUB_OUTPUT"; echo "Retry run (#547): $2" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0; }
|
|
375
|
+
HEAD="$(git rev-parse HEAD)"
|
|
376
|
+
TAGGED="$(git tag --points-at "$HEAD" --list 'v*' | head -n 1)"
|
|
377
|
+
[ -z "$TAGGED" ] || decide false "main's head ${HEAD:0:7} already carries $TAGGED — nothing to retry."
|
|
378
|
+
# When the CLI reached HANDBOOK_REF: a channel moves onto a release tag's commit, so that
|
|
379
|
+
# tag's date is the move; a plain branch or an untagged commit falls back to the commit date.
|
|
380
|
+
CLI_DIR="${COLAB%/tools/colab}"
|
|
381
|
+
CLI_SHA="$(git -C "$CLI_DIR" rev-parse --short HEAD 2> /dev/null || echo unknown)"
|
|
382
|
+
MOVED="$(git -C "$CLI_DIR" for-each-ref --points-at HEAD --format='%(taggerdate:unix)' refs/tags 2> /dev/null | grep -E '^[0-9]+$' | sort -n | tail -n 1)"
|
|
383
|
+
[ -n "$MOVED" ] || MOVED="$(git -C "$CLI_DIR" log -1 --format=%ct HEAD 2> /dev/null || true)"
|
|
384
|
+
AGE=""; [ -n "$MOVED" ] && AGE=$(( $(date +%s) - MOVED ))
|
|
385
|
+
if [ -n "$AGE" ] && [ "$AGE" -le $(( ${RETRY_WINDOW_MINUTES:-130} * 60 )) ]; then
|
|
386
|
+
decide true "the colab CLI ($CLI_SHA) reached HANDBOOK_REF $(( AGE / 60 )) min ago and main's head ${HEAD:0:7} has no tag — re-trying the cut with it."
|
|
387
|
+
fi
|
|
388
|
+
# A run this one displaced: the newest OTHER run of this workflow at main's head, cancelled.
|
|
389
|
+
# An unreadable list re-tries rather than guessing — a cut with nothing owed is a no-op.
|
|
390
|
+
RUNS="$(retry_transient gh run list --workflow "$GITHUB_WORKFLOW" --commit "$HEAD" --limit 20 --json databaseId,conclusion,createdAt)" \
|
|
391
|
+
|| decide true "could not list this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut."
|
|
392
|
+
LAST="$(jq -r --arg me "${GITHUB_RUN_ID:-0}" '[.[] | select((.databaseId | tostring) != $me)] | sort_by(.createdAt) | last | .conclusion // ""' <<< "$RUNS" 2> /dev/null || echo unreadable)"
|
|
393
|
+
case "$LAST" in
|
|
394
|
+
cancelled) decide true "the last run at main's head ${HEAD:0:7} was cancelled (displaced from the shared concurrency group) — doing its cut." ;;
|
|
395
|
+
unreadable) decide true "could not read this workflow's runs at ${HEAD:0:7}, so a displaced run cannot be ruled out — re-trying the cut." ;;
|
|
396
|
+
esac
|
|
397
|
+
decide false "the colab CLI ($CLI_SHA) has not moved in the last ${RETRY_WINDOW_MINUTES:-130} min and no run at ${HEAD:0:7} was displaced — nothing to retry; the daily run cuts as usual."
|
|
398
|
+
|
|
337
399
|
# #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
|
|
338
400
|
# into main, then dispatch CI there — its green run fires this workflow again to cut the
|
|
339
401
|
# candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
|
|
340
402
|
# rejected) is a warning; the job stays green.
|
|
341
403
|
- name: Promote unattended (colab promote --auto)
|
|
342
404
|
id: promote
|
|
343
|
-
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
405
|
+
if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
|
|
344
406
|
env:
|
|
345
407
|
# EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
|
|
346
408
|
CI_WORKFLOW: "CI"
|
|
@@ -384,7 +446,7 @@ jobs:
|
|
|
384
446
|
# right after this run promoted: that head has no CI yet — the dispatched run cuts it.
|
|
385
447
|
- name: Cut a candidate (colab release cut --auto)
|
|
386
448
|
id: cut
|
|
387
|
-
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
|
|
449
|
+
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
|
|
388
450
|
run: |
|
|
389
451
|
set -uo pipefail
|
|
390
452
|
eval "$RETRY_TRANSIENT"
|
|
@@ -436,13 +498,15 @@ jobs:
|
|
|
436
498
|
echo
|
|
437
499
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
438
500
|
else
|
|
439
|
-
|
|
501
|
+
# #545: condition AND detail — the name alone hid which file and statement refused, so a
|
|
502
|
+
# false refusal could not be told from a real one without re-running the cut by hand.
|
|
503
|
+
echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | "\(.condition) — \(.detail)"] | join("; ")' "$OUT")"
|
|
440
504
|
fi
|
|
441
505
|
fi
|
|
442
506
|
|
|
443
507
|
- name: Finalize the newest clean candidate (colab release finalize --auto)
|
|
444
508
|
id: finalize
|
|
445
|
-
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
509
|
+
if: (github.event_name == 'schedule' && env.RETRY_RUN != 'true') || github.event_name == 'workflow_dispatch'
|
|
446
510
|
run: |
|
|
447
511
|
set -uo pipefail
|
|
448
512
|
eval "$RETRY_TRANSIENT"
|