@futurelastic/colab-handbook 1.18.0-rc.6 → 1.18.0-rc.8
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 +16 -0
- package/README.vi.md +15 -0
- package/package.json +1 -1
- package/tools/colab +24 -3
- package/tools/lib/engines.js +53 -1
- package/tools/lib/install-check.js +63 -4
- package/tools/lib/migration-paths.js +44 -14
- package/tools/lib/release-cut.js +58 -8
- package/tools/lib/release-finalize.js +5 -2
package/README.md
CHANGED
|
@@ -317,11 +317,27 @@ linked, so an existing machine changes nothing. Finding none, it installs for
|
|
|
317
317
|
Claude Code and says so. The per-runtime facts live in [`engines/`](engines/),
|
|
318
318
|
one file each — that folder is the source for the table above.
|
|
319
319
|
|
|
320
|
+
**Sessions that run in a private home** never see a user-level folder. For
|
|
321
|
+
those, copy the skills into the repo itself:
|
|
322
|
+
|
|
323
|
+
```sh
|
|
324
|
+
./install.sh --repo ~/code/app --engine opencode # → ~/code/app/.opencode/skills
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Every skill is copied as plain files (a linked folder or file is
|
|
328
|
+
dereferenced, never linked), with a manifest of what was copied. The command
|
|
329
|
+
prints each file it wrote, so you can commit them. A re-run refreshes the
|
|
330
|
+
copies the repo has not edited and leaves edited ones alone. `--check` reports
|
|
331
|
+
the copy and its version, and marks it ✗ behind once a skill changes in the
|
|
332
|
+
clone. Only agent runtimes whose `engines/` file names a `project_skills_dir`
|
|
333
|
+
have this route; today that is opencode.
|
|
334
|
+
|
|
320
335
|
| Flag | What it does |
|
|
321
336
|
|---|---|
|
|
322
337
|
| *(none)* | Symlink `skills/` into each chosen agent runtime'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 agent runtime*](#choose-your-agent-runtime)). |
|
|
323
338
|
| `--engine <id>[,<id>]` | Install for these agent runtimes (`claude`, `codex`, `opencode` — the files in `engines/`), no question asked. |
|
|
324
339
|
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
340
|
+
| `--repo <path> --engine <id>` | Instead of a user-level install, **copy** the skills into that repo's project skills folder, for sessions that run in a private home. Prints the files to commit. |
|
|
325
341
|
| `--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. |
|
|
326
342
|
| `--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)). |
|
|
327
343
|
| `--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. |
|
package/README.vi.md
CHANGED
|
@@ -316,11 +316,26 @@ sẵn, nên máy đã cài không thay đổi gì. Không thấy agent runtime n
|
|
|
316
316
|
Code và nói rõ điều đó. Thông tin từng agent runtime nằm trong [`engines/`](engines/),
|
|
317
317
|
mỗi agent runtime một file — thư mục đó là nguồn của bảng trên.
|
|
318
318
|
|
|
319
|
+
**Phiên chạy trong một home riêng** không bao giờ thấy thư mục cấp user. Với
|
|
320
|
+
những phiên đó, hãy chép skill vào chính repo:
|
|
321
|
+
|
|
322
|
+
```sh
|
|
323
|
+
./install.sh --repo ~/code/app --engine opencode # → ~/code/app/.opencode/skills
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Mỗi skill được chép thành file thường (thư mục hay file là link thì được chép
|
|
327
|
+
nội dung, không bao giờ để link), kèm một manifest ghi những gì đã chép. Lệnh in
|
|
328
|
+
ra từng file nó đã ghi để bạn commit. Chạy lại thì làm mới các bản chép mà repo
|
|
329
|
+
chưa sửa, và để nguyên bản đã sửa. `--check` báo bản chép cùng phiên bản của nó,
|
|
330
|
+
và đánh ✗ (đã cũ) khi một skill trong clone thay đổi. Chỉ agent runtime nào có
|
|
331
|
+
file `engines/` khai `project_skills_dir` mới có đường này; hiện nay là opencode.
|
|
332
|
+
|
|
319
333
|
| Flag | Làm gì |
|
|
320
334
|
|---|---|
|
|
321
335
|
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng agent runtime đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn agent runtime*](#chọn-agent-runtime)). |
|
|
322
336
|
| `--engine <id>[,<id>]` | Cài cho các agent runtime này (`claude`, `codex`, `opencode` — các file trong `engines/`), không hỏi. |
|
|
323
337
|
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
338
|
+
| `--repo <path> --engine <id>` | Thay cho cài cấp user: **chép** skill vào thư mục skill của project trong repo đó, cho phiên chạy trong một home riêng. In ra các file cần commit. |
|
|
324
339
|
| `--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ó. |
|
|
325
340
|
| `--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)). |
|
|
326
341
|
| `--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. |
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -1414,7 +1414,12 @@ function readAllIssuesForSwitches(repoAbs) {
|
|
|
1414
1414
|
return Array.isArray(list) && list.length < LIMIT ? list : null;
|
|
1415
1415
|
}
|
|
1416
1416
|
|
|
1417
|
-
/**
|
|
1417
|
+
/**
|
|
1418
|
+
* [{status, path, content, added?}] for every path changed between `from` (null = the empty tree) and
|
|
1419
|
+
* `sha`; null on a git failure. #673: a declared schema FILE (migration-paths.js isDeclaredFile) also
|
|
1420
|
+
* carries `added` — the lines the change added, with their line numbers — which is what schema-additive
|
|
1421
|
+
* reads for it. A failed read leaves `added` null, which that check refuses (an unread change).
|
|
1422
|
+
*/
|
|
1418
1423
|
function releaseCutChanges(repoAbs, from, sha, declared) {
|
|
1419
1424
|
let base = from;
|
|
1420
1425
|
if (!base) {
|
|
@@ -1433,6 +1438,11 @@ function releaseCutChanges(repoAbs, from, sha, declared) {
|
|
|
1433
1438
|
const show = git.git(['show', `${sha}:${file}`], repoAbs);
|
|
1434
1439
|
content = show.ok ? show.stdout : '';
|
|
1435
1440
|
}
|
|
1441
|
+
if (!status.startsWith('D') && migrationPaths.isDeclaredFile(file, declared)) {
|
|
1442
|
+
// -U0: only the added lines and their hunk headers; --no-renames keeps one path per side.
|
|
1443
|
+
const d = git.git(['diff', '-U0', '--no-renames', '--no-color', base, sha, '--', file], repoAbs);
|
|
1444
|
+
return { status, path: file, content, added: d.ok ? releaseCut.addedLinesFromDiff(d.stdout) : null };
|
|
1445
|
+
}
|
|
1436
1446
|
return { status, path: file, content };
|
|
1437
1447
|
});
|
|
1438
1448
|
}
|
|
@@ -1801,7 +1811,7 @@ function cmdReleaseCut(argv) {
|
|
|
1801
1811
|
let created = false;
|
|
1802
1812
|
let published = null; // #443: { ok, detail } once a tag was created — null when nothing was cut
|
|
1803
1813
|
if (verdict.ok && !opts.dry) {
|
|
1804
|
-
const message = releaseCut.tagMessage(verdict, { sha, lastFinal });
|
|
1814
|
+
const message = releaseCut.tagMessage(verdict, { sha, lastFinal, checkedBy: checkedByLine() });
|
|
1805
1815
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', verdict.tag, sha, '-m', message], repoAbs);
|
|
1806
1816
|
if (!t.ok) throw new UserError(`git tag ${verdict.tag} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
1807
1817
|
const push = git.git(['push', remote, `refs/tags/${verdict.tag}`], repoAbs);
|
|
@@ -2312,7 +2322,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2312
2322
|
if (!opts.dry) {
|
|
2313
2323
|
if (verdict.state === 'finalized') {
|
|
2314
2324
|
const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1${verdict.early ? ', --early' : ''})` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
|
|
2315
|
-
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
|
|
2325
|
+
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor, checkedBy: checkedByLine() });
|
|
2316
2326
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
|
|
2317
2327
|
if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
2318
2328
|
const push = git.git(['push', remote, `refs/tags/${cand.version}`], repoAbs);
|
|
@@ -9674,6 +9684,17 @@ function versionLine(self) {
|
|
|
9674
9684
|
return `colab ${self.version} (${where})`;
|
|
9675
9685
|
}
|
|
9676
9686
|
|
|
9687
|
+
/**
|
|
9688
|
+
* #673: the colab that decided, for a release tag's message — the version plus, for a working tree, the
|
|
9689
|
+
* commit it runs at (its "version" is only the nearest release tag, so two dev checkouts would read
|
|
9690
|
+
* alike). No filesystem path: a tag message is published with the repo it lands in.
|
|
9691
|
+
*/
|
|
9692
|
+
function checkedByLine(self = selfProvenance()) {
|
|
9693
|
+
if (self.kind !== 'working-tree') return `colab ${self.version} (${self.kind === 'npm' ? 'npm package' : 'frozen copy'})`;
|
|
9694
|
+
const head = stamp.gitIn(self.source, ['rev-parse', '--short=12', 'HEAD']);
|
|
9695
|
+
return `colab ${self.version} (working tree${head.ok && head.out ? ` @ ${head.out}` : ''}${self.branch ? `, branch ${self.branch}` : ''})`;
|
|
9696
|
+
}
|
|
9697
|
+
|
|
9677
9698
|
function cmdVersion() {
|
|
9678
9699
|
return print(versionLine(selfProvenance()));
|
|
9679
9700
|
}
|
package/tools/lib/engines.js
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
const fs = require('fs');
|
|
12
12
|
const path = require('path');
|
|
13
|
+
const crypto = require('crypto');
|
|
13
14
|
|
|
14
15
|
const REPEATABLE = new Set(['note', 'caveat']);
|
|
15
16
|
|
|
@@ -49,4 +50,55 @@ function rememberedDirs(colabHome) {
|
|
|
49
50
|
return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
|
|
50
51
|
}
|
|
51
52
|
|
|
52
|
-
|
|
53
|
+
/**
|
|
54
|
+
* Per-repo copies (#664): `install.sh --repo <path> --engine <id>` copies the skills into the agent
|
|
55
|
+
* runtime's PROJECT skills folder (`project_skills_dir:`), for a runtime whose sessions run in a
|
|
56
|
+
* private home and never see a user-level install. Each copy is remembered in
|
|
57
|
+
* <COLAB_HOME>/skills-copies as one `<engine id>|<repo path>` line, so `--check` finds it.
|
|
58
|
+
*/
|
|
59
|
+
function rememberedCopies(colabHome) {
|
|
60
|
+
let text = '';
|
|
61
|
+
try { text = fs.readFileSync(path.join(colabHome, 'skills-copies'), 'utf8'); } catch (_) { return []; }
|
|
62
|
+
return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#') && l.includes('|'))
|
|
63
|
+
.map((l) => { const i = l.indexOf('|'); return { engine: l.slice(0, i), repo: l.slice(i + 1) }; });
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The manifest install.sh writes beside the copies: what it copied, at which version, with what content. */
|
|
67
|
+
const COPY_MANIFEST = '.colab-handbook-skills';
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* A skill folder's content digest — the same algorithm as install.sh's tree_digest, and
|
|
71
|
+
* install-sh.test.js holds the two to it: sha256 over one `<sha256 of file> <relative path>\n`
|
|
72
|
+
* line per regular file, links followed, paths sorted bytewise (LC_ALL=C sort). Null when absent.
|
|
73
|
+
*/
|
|
74
|
+
function treeDigest(dir) {
|
|
75
|
+
const files = [];
|
|
76
|
+
const walk = (rel) => {
|
|
77
|
+
for (const n of fs.readdirSync(path.join(dir, rel))) {
|
|
78
|
+
const r = rel ? `${rel}/${n}` : n;
|
|
79
|
+
const st = fs.statSync(path.join(dir, r)); // stat, not lstat: links are followed, as cp -RL does
|
|
80
|
+
if (st.isDirectory()) walk(r);
|
|
81
|
+
else if (st.isFile()) files.push(r);
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
try { if (!fs.statSync(dir).isDirectory()) return null; walk(''); } catch (_) { return null; }
|
|
85
|
+
files.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
|
|
86
|
+
const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
|
|
87
|
+
return sha(files.map((f) => `${sha(fs.readFileSync(path.join(dir, f)))} ${f}\n`).join(''));
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Parse a COPY_MANIFEST: its stamp version, engine, and `{ <skill>: <digest> }`. Null when absent. */
|
|
91
|
+
function readCopyManifest(dir) {
|
|
92
|
+
let text;
|
|
93
|
+
try { text = fs.readFileSync(path.join(dir, COPY_MANIFEST), 'utf8'); } catch (_) { return null; }
|
|
94
|
+
const out = { version: null, engine: null, skills: {} };
|
|
95
|
+
for (const l of text.split(/\r?\n/)) {
|
|
96
|
+
let m;
|
|
97
|
+
if ((m = /^#\s*colab-handbook:\s*skills\s*@\s*(\S+)/.exec(l))) out.version = m[1];
|
|
98
|
+
else if ((m = /^#\s*engine:\s*(\S+)/.exec(l))) out.engine = m[1];
|
|
99
|
+
else if ((m = /^([0-9a-f]{64}) (.+)$/.exec(l))) out.skills[m[2]] = m[1];
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { parseConf, expandHome, listEngines, rememberedDirs, rememberedCopies, COPY_MANIFEST, treeDigest, readCopyManifest };
|
|
@@ -157,7 +157,9 @@ function checkFrozen({ root, colabHome }) {
|
|
|
157
157
|
function checkSkills({ root, home, colabHome }) {
|
|
158
158
|
const src = path.join(root, 'skills');
|
|
159
159
|
let skills = [];
|
|
160
|
-
|
|
160
|
+
// stat, not the Dirent: a skill folder that is itself a link is a skill too, as install.sh's `*/` glob says (#664).
|
|
161
|
+
const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch (_) { return false; } };
|
|
162
|
+
try { skills = fs.readdirSync(src).filter((n) => isDir(path.join(src, n))).sort(); } catch (_) { /* none */ }
|
|
161
163
|
const all = engines.listEngines(root);
|
|
162
164
|
const byId = Object.fromEntries(all.map((e) => [e.id, e]));
|
|
163
165
|
const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
|
|
@@ -203,11 +205,68 @@ function checkSkills({ root, home, colabHome }) {
|
|
|
203
205
|
for (const c of e.caveat || []) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: ${c}` });
|
|
204
206
|
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
207
|
}
|
|
206
|
-
|
|
208
|
+
const copies = checkCopies({ root, colabHome, skills, byId });
|
|
209
|
+
if (!rows.length && !copies.length) {
|
|
207
210
|
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) {
|
|
211
|
+
} else if (rows.length && notInstalled.length) {
|
|
209
212
|
rows.push({ area: 'skills', severity: OK, text: `not installed for: ${notInstalled.join(', ')} — fine if deliberate; ./install.sh --engine <id> adds one` });
|
|
210
213
|
}
|
|
214
|
+
// An engine installed both ways states its caveats once.
|
|
215
|
+
const seen = new Set();
|
|
216
|
+
return [...rows, ...copies].filter((r) => (seen.has(r.text) ? false : (seen.add(r.text), true)));
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Per-repo copies (#664), every one remembered in <COLAB_HOME>/skills-copies: the same row as a
|
|
221
|
+
* user-level install, plus the version the copy was stamped with. Per skill, three digests decide —
|
|
222
|
+
* the manifest's (what install.sh wrote), the copy's now, and this clone's skill now:
|
|
223
|
+
* copy ≠ manifest → edited in the repo (⚠: the repo owns its copy; a re-run leaves it alone)
|
|
224
|
+
* clone ≠ manifest = copy → behind (✗: installed, and the handbook has moved on — re-run)
|
|
225
|
+
* in the clone, not copied → missing (⚠, a skill added since — re-run), as for a link
|
|
226
|
+
* copied, gone from clone → behind too (✗, removed upstream — a re-run deletes it)
|
|
227
|
+
*/
|
|
228
|
+
function checkCopies({ root, colabHome, skills, byId }) {
|
|
229
|
+
const src = path.join(root, 'skills');
|
|
230
|
+
const rows = [];
|
|
231
|
+
for (const { engine, repo } of engines.rememberedCopies(colabHome)) {
|
|
232
|
+
const e = byId[engine] || { id: engine, caveat: [] };
|
|
233
|
+
const rel = e.project_skills_dir;
|
|
234
|
+
const rerun = `./install.sh --repo '${repo}' --engine ${engine}`;
|
|
235
|
+
if (!rel) {
|
|
236
|
+
rows.push({ area: 'skills', severity: WARN, text: `${engine} copy in ${repo}: engines/${engine}.conf names no project_skills_dir any more — remove the line from ${path.join(colabHome, 'skills-copies')} if the copy is gone` });
|
|
237
|
+
continue;
|
|
238
|
+
}
|
|
239
|
+
const dir = path.join(repo, rel);
|
|
240
|
+
const man = engines.readCopyManifest(dir);
|
|
241
|
+
if (!man) {
|
|
242
|
+
rows.push({ area: 'skills', severity: WARN, text: `${engine} (${e.label || engine}) ${dir}: no ${engines.COPY_MANIFEST} — the copy is gone, or was not written by install.sh. Re-copy: ${rerun}, or drop the line from ${path.join(colabHome, 'skills-copies')}` });
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
const current = []; const behind = []; const edited = []; const missing = []; const removed = [];
|
|
246
|
+
for (const name of skills) {
|
|
247
|
+
const want = man.skills[name];
|
|
248
|
+
if (!want) { missing.push(name); continue; }
|
|
249
|
+
const now = engines.treeDigest(path.join(dir, name));
|
|
250
|
+
if (now !== want) { edited.push(name); continue; }
|
|
251
|
+
if (engines.treeDigest(path.join(src, name)) !== want) behind.push(name);
|
|
252
|
+
else current.push(name);
|
|
253
|
+
}
|
|
254
|
+
for (const name of Object.keys(man.skills)) {
|
|
255
|
+
if (skills.includes(name)) continue;
|
|
256
|
+
if (engines.treeDigest(path.join(dir, name)) === man.skills[name]) removed.push(name);
|
|
257
|
+
}
|
|
258
|
+
const parts = [`${current.length}/${skills.length} current`];
|
|
259
|
+
if (behind.length) parts.push(`BEHIND the handbook: ${behind.join(', ')} — re-run ${rerun}, then commit`);
|
|
260
|
+
if (removed.length) parts.push(`copies of skills the handbook no longer has: ${removed.join(', ')} — re-run ${rerun} to remove them`);
|
|
261
|
+
if (missing.length) parts.push(`missing ${missing.join(', ')} — re-run ${rerun}`);
|
|
262
|
+
if (edited.length) parts.push(`edited in the repo (left as is; a re-run will not refresh them): ${edited.join(', ')}`);
|
|
263
|
+
rows.push({
|
|
264
|
+
area: 'skills',
|
|
265
|
+
severity: (behind.length || removed.length) ? FAIL : (missing.length || edited.length) ? WARN : OK,
|
|
266
|
+
text: `${engine} (${e.label || engine}) ${dir} — copy @ ${man.version || 'unknown'}: ${parts.join('; ')}`,
|
|
267
|
+
});
|
|
268
|
+
for (const c of e.caveat || []) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: ${c}` });
|
|
269
|
+
}
|
|
211
270
|
return rows;
|
|
212
271
|
}
|
|
213
272
|
|
|
@@ -352,5 +411,5 @@ if (require.main === module) {
|
|
|
352
411
|
|
|
353
412
|
module.exports = {
|
|
354
413
|
OK, WARN, FAIL,
|
|
355
|
-
dispatchedCommands, checkSkills, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
|
|
414
|
+
dispatchedCommands, checkSkills, checkCopies, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
|
|
356
415
|
};
|
|
@@ -9,9 +9,16 @@
|
|
|
9
9
|
* `migrations/` — was invisible to both: `colab ship --dry` reported `no new migrations ✓` on a
|
|
10
10
|
* branch adding a production data backfill, so the human-only grant (#98) never engaged.
|
|
11
11
|
*
|
|
12
|
-
* `migrations:` in `.github/project.yml` names the extra places, as repo-relative
|
|
12
|
+
* `migrations:` in `.github/project.yml` names the extra places, as repo-relative paths:
|
|
13
13
|
*
|
|
14
|
-
* migrations: [backend/migrations/]
|
|
14
|
+
* migrations: [backend/migrations/, server/db.ts]
|
|
15
|
+
*
|
|
16
|
+
* #673: an entry is a DIRECTORY when it ends in `/` (matched by prefix, as before), and otherwise a
|
|
17
|
+
* path that may be a FILE: that exact path, or anything under it. So `backend/migrations` still covers
|
|
18
|
+
* `backend/migrations/x.sql`, and `server/db.ts` covers a schema the server applies inline at start-up
|
|
19
|
+
* (`CREATE TABLE`/`ALTER TABLE` in its own code, no migrations directory) — before this, that layout
|
|
20
|
+
* could not be declared at all, and #671's fail-closed grant gate left such a repo no tooled release.
|
|
21
|
+
* A change to a declared file IS a migration; release-cut's schema-additive reads the lines it added.
|
|
15
22
|
*
|
|
16
23
|
* The declared list is ADDED to the two defaults, never a replacement for them: a declaration can
|
|
17
24
|
* only make the gate see more. There is deliberately no opt-out of the defaults — an opt-out can
|
|
@@ -30,23 +37,34 @@ const DEFAULT_MIGRATION_PATHS = Object.freeze(['database/migrations/', 'prisma/m
|
|
|
30
37
|
const FOREIGN_TREE_SEGMENTS = new Set(['node_modules', 'vendor']);
|
|
31
38
|
|
|
32
39
|
/**
|
|
33
|
-
* One declared entry → its normalised
|
|
34
|
-
*
|
|
35
|
-
*
|
|
40
|
+
* One declared entry → its normalised path, or `{ problem }`. `./` and doubled `/` are removed; a
|
|
41
|
+
* trailing `/` is KEPT when written (a directory) and never added (#673: without one, the entry may
|
|
42
|
+
* name a file). Rejected, not guessed: absolute paths and `..` (not repo-relative), globs (a path
|
|
43
|
+
* match would silently match nothing for `*`), and empties.
|
|
36
44
|
*/
|
|
37
45
|
function normalizeEntry(raw) {
|
|
38
46
|
if (typeof raw !== 'string') return { problem: `${JSON.stringify(raw)} is not a path` };
|
|
39
47
|
let p = raw.trim();
|
|
40
48
|
if (p === '') return { problem: 'an empty entry is not a path' };
|
|
41
49
|
if (p.startsWith('/')) return { problem: `"${p}" is absolute — declare a repo-relative prefix (e.g. "backend/migrations/")` };
|
|
42
|
-
if (/[*?[\]{}]/.test(p)) return { problem: `"${p}" is a glob — declare a plain directory prefix; entries are matched by
|
|
43
|
-
p = p.replace(/^(\.\/)+/, '').replace(/\/{2,}/g, '/');
|
|
44
|
-
if (p === '' || p === '.') return { problem: `"${raw}" names the repo root — every file would be a migration` };
|
|
50
|
+
if (/[*?[\]{}]/.test(p)) return { problem: `"${p}" is a glob — declare a plain directory prefix ("backend/migrations/") or a file ("server/db.ts"); entries are matched by path, not by pattern` };
|
|
51
|
+
p = p.replace(/^(\.\/)+/, '').replace(/\/{2,}/g, '/').replace(/(\/\.)+\/?$/, '/');
|
|
52
|
+
if (p === '' || p === '.' || p === '/' || p === './') return { problem: `"${raw}" names the repo root — every file would be a migration` };
|
|
45
53
|
if (p.split('/').includes('..')) return { problem: `"${p}" climbs out of the repo — declare a repo-relative prefix` };
|
|
46
|
-
if (!p.endsWith('/')) p += '/';
|
|
47
54
|
return { path: p };
|
|
48
55
|
}
|
|
49
56
|
|
|
57
|
+
/** The directory form of an entry (`a/b` → `a/b/`) — what duplicates and defaults compare by. */
|
|
58
|
+
function dirForm(p) {
|
|
59
|
+
return p.endsWith('/') ? p : `${p}/`;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Does declared entry `p` cover repo-relative `f`? A directory by prefix; a no-slash entry exactly or below it. */
|
|
63
|
+
function entryCovers(p, f) {
|
|
64
|
+
if (p.endsWith('/')) return f.startsWith(p);
|
|
65
|
+
return f === p || f.startsWith(`${p}/`);
|
|
66
|
+
}
|
|
67
|
+
|
|
50
68
|
/**
|
|
51
69
|
* `migrations:` from a parsed project.yml → `{ declared, paths, problems, notes, reason }`.
|
|
52
70
|
* `problems` are invalid shapes/entries (the audit fails them); `notes` are harmless redundancy — an
|
|
@@ -58,7 +76,8 @@ function normalizeEntry(raw) {
|
|
|
58
76
|
* lenient in the direction that makes the gate STRICTER (it still sees
|
|
59
77
|
* the path the author obviously meant); the audit fails the shape.
|
|
60
78
|
*
|
|
61
|
-
* `paths` never includes the defaults — `isMigrationPath` always applies those itself.
|
|
79
|
+
* `paths` never includes the defaults — `isMigrationPath` always applies those itself. An entry
|
|
80
|
+
* keeps its trailing `/` as written (#673): `a/b/` is a directory, `a/b` a file or a directory.
|
|
62
81
|
*/
|
|
63
82
|
function parseMigrationPaths(doc) {
|
|
64
83
|
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'migrations');
|
|
@@ -83,11 +102,11 @@ function parseMigrationPaths(doc) {
|
|
|
83
102
|
for (const raw of entries) {
|
|
84
103
|
const r = normalizeEntry(raw);
|
|
85
104
|
if (r.problem) { problems.push(`migrations: ${r.problem}`); continue; }
|
|
86
|
-
if (DEFAULT_MIGRATION_PATHS.includes(r.path)) {
|
|
105
|
+
if (DEFAULT_MIGRATION_PATHS.includes(dirForm(r.path))) {
|
|
87
106
|
notes.push(`migrations: "${r.path}" is already a default — it need not be declared`);
|
|
88
107
|
continue;
|
|
89
108
|
}
|
|
90
|
-
if (paths.
|
|
109
|
+
if (paths.some((q) => dirForm(q) === dirForm(r.path))) { notes.push(`migrations: "${r.path}" is declared twice`); continue; }
|
|
91
110
|
paths.push(r.path);
|
|
92
111
|
}
|
|
93
112
|
return { declared: true, paths, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
|
|
@@ -106,10 +125,21 @@ function isMigrationPath(file, declared) {
|
|
|
106
125
|
for (const d of DEFAULT_MIGRATION_PATHS) {
|
|
107
126
|
if (f.startsWith(d) || f.includes(`/${d}`)) return true;
|
|
108
127
|
}
|
|
109
|
-
for (const p of declared || []) if (
|
|
128
|
+
for (const p of declared || []) if (entryCovers(p, f)) return true;
|
|
110
129
|
return false;
|
|
111
130
|
}
|
|
112
131
|
|
|
132
|
+
/**
|
|
133
|
+
* #673: is `file` exactly a declared no-slash entry — a schema FILE, edited in place by nature (one
|
|
134
|
+
* `db.ts` that runs its `CREATE`/`ALTER` at start-up)? Such a file is not a migration *history*: an
|
|
135
|
+
* edit is how it grows, never "an existing migration was rewritten", so schema-additive reads the
|
|
136
|
+
* lines the edit ADDED instead. A file under a declared directory is not one (that is a history).
|
|
137
|
+
*/
|
|
138
|
+
function isDeclaredFile(file, declared) {
|
|
139
|
+
const f = String(file || '');
|
|
140
|
+
return (declared || []).some((p) => !p.endsWith('/') && f === p);
|
|
141
|
+
}
|
|
142
|
+
|
|
113
143
|
/**
|
|
114
144
|
* Directories named `migrations` in a tracked-file list that NO rule covers — the likely
|
|
115
145
|
* undeclared layout the audit reports. `files` is `git ls-files` output (repo-relative). Returns the
|
|
@@ -131,5 +161,5 @@ function undeclaredMigrationDirs(files, declared) {
|
|
|
131
161
|
}
|
|
132
162
|
|
|
133
163
|
module.exports = {
|
|
134
|
-
DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, undeclaredMigrationDirs,
|
|
164
|
+
DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, isDeclaredFile, undeclaredMigrationDirs,
|
|
135
165
|
};
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -870,21 +870,25 @@ function laravelUpBody(text) {
|
|
|
870
870
|
*/
|
|
871
871
|
function schemaVerdict(changes, since, declared, layout) {
|
|
872
872
|
const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
|
|
873
|
-
|
|
873
|
+
// #673: a declared schema FILE (an inline schema the server applies itself) is read by the lines
|
|
874
|
+
// its change added — never "unread", and an edit is never "an existing migration was rewritten".
|
|
875
|
+
const schemaFiles = inPaths.filter((c) => migrationPaths.isDeclaredFile(c.path, declared));
|
|
876
|
+
const history = inPaths.filter((c) => !migrationPaths.isDeclaredFile(c.path, declared));
|
|
877
|
+
const migrations = history.filter((c) => /\.(php|sql)$/.test(c.path));
|
|
874
878
|
// #383: a declared path widens what COUNTS as a migration, not what this heuristic can READ. A
|
|
875
879
|
// declared migration in any other format (a Node boot migration, a Go file) is named in the
|
|
876
880
|
// detail, so the §6 judgement the release notes owe knows exactly which files it still has to
|
|
877
881
|
// read by hand — never silently folded into "none destructive". Only for DECLARED paths: under
|
|
878
882
|
// the defaults a non-php/sql file is Prisma's migration_lock.toml and the like, as it always was.
|
|
879
883
|
const unread = (declared && declared.length)
|
|
880
|
-
?
|
|
884
|
+
? history.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
|
|
881
885
|
: [];
|
|
882
|
-
const scope = `Laravel database/migrations + Prisma prisma/migrations${declared && declared.length ? ` + declared ${declared.join(', ')} (php/sql only)` : ''} — other layouts are not read`;
|
|
886
|
+
const scope = `Laravel database/migrations + Prisma prisma/migrations${declared && declared.length ? ` + declared ${declared.join(', ')} (php/sql only; a declared file: the SQL it added)` : ''} — other layouts are not read`;
|
|
883
887
|
const hasDeclared = !!(declared && declared.length);
|
|
884
888
|
const notChecked = (why) => ({ ok: true, checked: false, detail: `not checked — ${why}` });
|
|
885
889
|
const unreadWhy = () => `${unread.length} declared migration file(s) changed since ${since} in a format this check does not read (php/sql only) — a human reads them before the final: ${unread.map((c) => c.path).join(', ')}`;
|
|
886
890
|
const howToDeclare = 'a repo whose migrations live elsewhere declares their directory as `migrations:` in .github/project.yml (project.schema.md `migrations`); a repo with no database has nothing to declare';
|
|
887
|
-
if (!migrations.length) {
|
|
891
|
+
if (!migrations.length && !schemaFiles.length) {
|
|
888
892
|
if (unread.length) return notChecked(unreadWhy());
|
|
889
893
|
if (!hasDeclared && layout === false) return notChecked(`no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate and no \`migrations:\` declared, so no migration was read — ${howToDeclare}`);
|
|
890
894
|
if (!hasDeclared && layout === null) return notChecked(`the tree at the candidate could not be read for a migration layout, so no migration was read — ${howToDeclare}`);
|
|
@@ -904,11 +908,55 @@ function schemaVerdict(changes, since, declared, layout) {
|
|
|
904
908
|
if (m) findings.push(`${c.path}:${m.line}: \`${m.statement}\`${m.inUp ? ' in the Up section' : ''}`);
|
|
905
909
|
}
|
|
906
910
|
}
|
|
911
|
+
for (const c of schemaFiles) {
|
|
912
|
+
const f = schemaFileFinding(c);
|
|
913
|
+
if (f) findings.push(f);
|
|
914
|
+
}
|
|
907
915
|
if (findings.length) {
|
|
908
916
|
return { ok: false, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
|
|
909
917
|
}
|
|
910
|
-
|
|
911
|
-
|
|
918
|
+
const read = [
|
|
919
|
+
...(migrations.length ? [`${migrations.length} migration file(s) added`] : []),
|
|
920
|
+
...(schemaFiles.length ? [`declared schema file(s) changed (${schemaFiles.map((c) => c.path).join(', ')}), the SQL they added read`] : []),
|
|
921
|
+
].join(' and ');
|
|
922
|
+
if (unread.length) return notChecked(`${read} since ${since}, none destructive — but ${unreadWhy()}`);
|
|
923
|
+
return { ok: true, detail: `${read} since ${since}, none destructive (${scope})` };
|
|
924
|
+
}
|
|
925
|
+
|
|
926
|
+
/**
|
|
927
|
+
* #673: one declared schema file's change → a destructive finding, or null. Reads ONLY what the change
|
|
928
|
+
* added (`c.added` = [{ line, text }], new-side line numbers; for an added file, its whole content):
|
|
929
|
+
* a `CREATE TABLE` the file has always held is not this release's, a `DROP COLUMN` it just gained is.
|
|
930
|
+
* Fails CLOSED — a deleted file, or added lines that could not be read, is a finding. Lines removed
|
|
931
|
+
* from the file are not read: a schema that stops creating a table drops nothing that exists.
|
|
932
|
+
*/
|
|
933
|
+
function schemaFileFinding(c) {
|
|
934
|
+
const st = String(c.status || '').charAt(0);
|
|
935
|
+
if (st === 'D') return `${c.path}: deleted — the declared schema file is gone`;
|
|
936
|
+
let lines = Array.isArray(c.added) ? c.added : null;
|
|
937
|
+
if (!lines && st === 'A' && typeof c.content === 'string') lines = c.content.split('\n').map((text, i) => ({ line: i + 1, text }));
|
|
938
|
+
if (!lines) return `${c.path}: the lines this change added could not be read — an unread schema change is not an additive one`;
|
|
939
|
+
const m = sqlDestructive(lines.map((l) => l.text).join('\n'));
|
|
940
|
+
if (!m) return null;
|
|
941
|
+
const at = lines[m.line - 1];
|
|
942
|
+
return `${c.path}:${at ? at.line : '?'}: \`${m.statement}\` added`;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
/**
|
|
946
|
+
* #673: `git diff -U0` output for ONE file → the lines it added, [{ line, text }] with new-side line
|
|
947
|
+
* numbers read from each hunk header. Pure, so the shape is tested without git.
|
|
948
|
+
*/
|
|
949
|
+
function addedLinesFromDiff(diffText) {
|
|
950
|
+
const out = [];
|
|
951
|
+
let next = null;
|
|
952
|
+
for (const l of String(diffText || '').split('\n')) {
|
|
953
|
+
const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l);
|
|
954
|
+
if (h) { next = Number(h[1]); continue; }
|
|
955
|
+
if (next === null) continue; // the file header, before the first hunk
|
|
956
|
+
if (l.startsWith('+')) { out.push({ line: next, text: l.slice(1) }); next += 1; }
|
|
957
|
+
else if (l.startsWith(' ')) next += 1; // context (none at -U0, kept for safety)
|
|
958
|
+
}
|
|
959
|
+
return out;
|
|
912
960
|
}
|
|
913
961
|
|
|
914
962
|
// ---- §6 condition 4: switch dependencies -------------------------------------------------------
|
|
@@ -1243,7 +1291,7 @@ function versionSourceOf(policy) {
|
|
|
1243
1291
|
}
|
|
1244
1292
|
|
|
1245
1293
|
/** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
|
|
1246
|
-
function tagMessage(verdict, { sha, lastFinal }) {
|
|
1294
|
+
function tagMessage(verdict, { sha, lastFinal, checkedBy }) {
|
|
1247
1295
|
// #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
|
|
1248
1296
|
// reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
|
|
1249
1297
|
const fast = !!verdict.final;
|
|
@@ -1253,6 +1301,8 @@ function tagMessage(verdict, { sha, lastFinal }) {
|
|
|
1253
1301
|
'',
|
|
1254
1302
|
`Commit: ${sha}`,
|
|
1255
1303
|
`Since: ${lastFinal}`,
|
|
1304
|
+
// #673: which colab decided — two channels reading one commit differently is then visible here.
|
|
1305
|
+
...(checkedBy ? [`Checked by: ${checkedBy}`] : []),
|
|
1256
1306
|
`Bump: ${verdict.bump}${verdict.overridden ? ` (overridden from ${verdict.overridden.from || 'no bump'} — reason: ${verdict.overridden.reason})` : ''}${verdict.signals ? ' (computed by --auto)' : ''}`,
|
|
1257
1307
|
'',
|
|
1258
1308
|
...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
|
|
@@ -1281,7 +1331,7 @@ module.exports = {
|
|
|
1281
1331
|
isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1282
1332
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
1283
1333
|
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
|
|
1284
|
-
fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, verifyingRunsForCut, verifyingNote, isMigrationPath, schemaVerdict,
|
|
1334
|
+
fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, verifyingRunsForCut, verifyingNote, isMigrationPath, schemaVerdict, addedLinesFromDiff,
|
|
1285
1335
|
parseSwitchMarkers, switchVerdict,
|
|
1286
1336
|
promotionVerdict, decide, tagMessage, versionSourceOf,
|
|
1287
1337
|
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
|
|
@@ -572,7 +572,9 @@ function migrationGrantVerdict({ paths, grant, since, layout }) {
|
|
|
572
572
|
// #671: fail closed where nothing could have been seen — an automatically deployed final never
|
|
573
573
|
// reads "nothing read" as "nothing changed". The way out is named in the detail, never implied —
|
|
574
574
|
// route-neutral: release finalize prints its own human command, and route deploy-tag-fast has none.
|
|
575
|
-
|
|
575
|
+
// #673: a schema applied inline by the server's own code is declarable too — as the FILE — and the
|
|
576
|
+
// detail names the grant command that clears its next change, so no one reaches for a raw tag.
|
|
577
|
+
const wayOut = 'declare where the schema lives as `migrations:` in .github/project.yml (project.schema.md `migrations`) — a migration directory (`migrations: [backend/migrations/]`) or, for a schema the server applies inline, the file itself (`migrations: [server/db.ts]`); a change under it then clears the usual way (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>). Until then the final is a human act, not the grant\'s — and a repo with no database has no layout to declare, so its final stays one';
|
|
576
578
|
if (layout === false) return { ok: false, detail: `no migration was read since ${since || 'the first commit'}: no \`migrations:\` declared and no Laravel database/migrations/ or Prisma prisma/migrations/ directory at the candidate, so a migration elsewhere would be invisible — ${wayOut}` };
|
|
577
579
|
if (layout !== true) return { ok: false, unread: true, detail: `the tree at the candidate could not be read for a migration layout, so an empty migration list since ${since || 'the first commit'} is not evidence that none changed — ${wayOut}` };
|
|
578
580
|
return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|
|
@@ -803,7 +805,7 @@ function earlyLine(early) {
|
|
|
803
805
|
}
|
|
804
806
|
|
|
805
807
|
/** The final tag's annotated message: which candidate, which period, every condition, who. */
|
|
806
|
-
function tagMessage(verdict, { candidate, period, actor }) {
|
|
808
|
+
function tagMessage(verdict, { candidate, period, actor, checkedBy }) {
|
|
807
809
|
return [
|
|
808
810
|
`${candidate.version} — release (colab release finalize)`,
|
|
809
811
|
'',
|
|
@@ -812,6 +814,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
|
|
|
812
814
|
period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
|
|
813
815
|
verdict.early ? `Early final: ${earlyLine(verdict.early)}` : null,
|
|
814
816
|
`Finalized by: ${actor}`,
|
|
817
|
+
checkedBy ? `Checked by: ${checkedBy}` : null, // #673: which colab decided
|
|
815
818
|
verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
|
|
816
819
|
'',
|
|
817
820
|
'Conditions (CONVENTIONS.md §6):',
|