@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13790 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* `install.sh --check` — a READ-ONLY report on what an earlier install left behind (#341).
|
|
4
|
+
*
|
|
5
|
+
* Why it exists: the frozen CLI copy at <COLAB_HOME>/bin/colab is pinned on purpose, so it never
|
|
6
|
+
* breaks — it gets OLD. An old complete copy answers normally for every command it knows and fails
|
|
7
|
+
* only when something finally asks for a command added after it was frozen. Measured across three
|
|
8
|
+
* machines of one fleet: three different stamps, none matching the tree, the oldest not dispatching
|
|
9
|
+
* a dozen commands the current CLI does. Nothing reported any of it. This module is that report.
|
|
10
|
+
*
|
|
11
|
+
* It never writes and never refreshes. Auto-refreshing a frozen copy is a non-goal: consumers rely
|
|
12
|
+
* on it not moving underneath them, so detection is the whole job and re-freezing stays a human act.
|
|
13
|
+
*
|
|
14
|
+
* Row severities, and the one rule behind them: ✗ (fail, exit 1) means something was INSTALLED and
|
|
15
|
+
* is now stale or unusable; ⚠ means something was simply never set up, which may be a deliberate
|
|
16
|
+
* choice (a machine that only wants the skills needs no fleet list). A report that failed every
|
|
17
|
+
* skills-only machine would teach people to ignore its exit code.
|
|
18
|
+
*
|
|
19
|
+
* CommonJS, zero dependencies, runnable as a script: install.sh calls
|
|
20
|
+
* node tools/lib/install-check.js --root <handbook> --colab-home <dir> --home <dir>
|
|
21
|
+
* and exits with its code. lib/ is also copied into the frozen copy, where it is inert.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
const fs = require('fs');
|
|
25
|
+
const path = require('path');
|
|
26
|
+
const { execFileSync } = require('child_process');
|
|
27
|
+
const stamp = require('./stamp');
|
|
28
|
+
|
|
29
|
+
const OK = 'ok';
|
|
30
|
+
const WARN = 'warn';
|
|
31
|
+
const FAIL = 'fail';
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The top-level commands a `tools/colab` source dispatches, sorted. Read from the `switch` inside
|
|
35
|
+
* `function main(argv)` — the only place a command becomes reachable — so a helper elsewhere that
|
|
36
|
+
* happens to `case 'room':` is never mistaken for one. Same shape on every tag back to v1.9.0.
|
|
37
|
+
*/
|
|
38
|
+
function dispatchedCommands(src) {
|
|
39
|
+
const start = src.search(/^function main\(argv\)/m);
|
|
40
|
+
if (start < 0) return [];
|
|
41
|
+
const body = src.slice(start);
|
|
42
|
+
const end = body.search(/^\s*default:/m);
|
|
43
|
+
const sw = end < 0 ? body : body.slice(0, end);
|
|
44
|
+
const out = new Set();
|
|
45
|
+
for (const m of sw.matchAll(/case '([a-z][a-z-]*)'/g)) out.add(m[1]);
|
|
46
|
+
return [...out].sort();
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function readText(p) {
|
|
50
|
+
try { return fs.readFileSync(p, 'utf8'); } catch (_) { return null; }
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function isExecutable(cmd, env) {
|
|
54
|
+
for (const dir of String(env.PATH || '').split(path.delimiter)) {
|
|
55
|
+
if (!dir) continue;
|
|
56
|
+
try { fs.accessSync(path.join(dir, cmd), fs.constants.X_OK); return true; } catch (_) { /* next */ }
|
|
57
|
+
}
|
|
58
|
+
return false;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function gitConfig(root, key, env) {
|
|
62
|
+
try {
|
|
63
|
+
return execFileSync('git', ['-C', root, 'config', '--get', key],
|
|
64
|
+
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
|
|
65
|
+
// git itself is found on the REAL PATH: the injected env may narrow PATH to decide what
|
|
66
|
+
// gitleaks lookup sees, and must not also hide git (whose config it is reading).
|
|
67
|
+
env: { ...env, PATH: process.env.PATH } }).trim();
|
|
68
|
+
} catch (_) {
|
|
69
|
+
return '';
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The symlinked CLI (~/.local/bin/colab): does it follow THIS clone, with templates/ reachable? */
|
|
74
|
+
function checkLink({ root, home }) {
|
|
75
|
+
const link = path.join(home, '.local', 'bin', 'colab');
|
|
76
|
+
let target;
|
|
77
|
+
try { target = fs.readlinkSync(link); } catch (e) {
|
|
78
|
+
if (e.code === 'ENOENT') return { area: 'cli', severity: WARN, text: `no symlink at ${link} — sessions have no colab on PATH; install: ./install.sh --tools` };
|
|
79
|
+
return { area: 'cli', severity: WARN, text: `${link} is not a symlink — not installed by install.sh, left as is` };
|
|
80
|
+
}
|
|
81
|
+
const ours = path.resolve(path.dirname(link), target) === path.join(root, 'tools', 'colab');
|
|
82
|
+
if (!ours) return { area: 'cli', severity: WARN, text: `${link} points at ${target}, not this clone — another checkout owns your PATH colab` };
|
|
83
|
+
if (!fs.existsSync(path.join(root, 'templates'))) {
|
|
84
|
+
return { area: 'cli', severity: FAIL, text: `${link} follows this clone, but ${path.join(root, 'templates')} is missing — \`colab template\` cannot run` };
|
|
85
|
+
}
|
|
86
|
+
return { area: 'cli', severity: OK, text: `${link} → this clone (templates/ present)` };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* The frozen copy. Two independent questions, both needed:
|
|
91
|
+
* - classifyFrozen: has a RELEASED CLI change happened since the stamp? (bounded by the latest tag)
|
|
92
|
+
* - the command diff: which commands does the tree dispatch that the copy does not? This is the
|
|
93
|
+
* concrete failure a service hits, and it names them instead of saying "behind".
|
|
94
|
+
* The diff alone is not a verdict: on a machine developing the handbook the tree legitimately
|
|
95
|
+
* dispatches unreleased commands, which is a ⚠ (re-freeze after the next tag), not a ✗.
|
|
96
|
+
*/
|
|
97
|
+
function checkFrozen({ root, colabHome }) {
|
|
98
|
+
const dir = path.join(colabHome, 'bin');
|
|
99
|
+
const bin = path.join(dir, 'colab');
|
|
100
|
+
const rows = [];
|
|
101
|
+
if (!fs.existsSync(bin)) {
|
|
102
|
+
return [{ area: 'frozen', severity: WARN, text: `no frozen copy at ${bin} — fine unless an always-on service calls colab; install: ./install.sh --tools` }];
|
|
103
|
+
}
|
|
104
|
+
const stampText = readText(path.join(dir, stamp.FROZEN_STAMP_FILE));
|
|
105
|
+
const parsed = stampText ? stamp.parseWorkflowStamp(stampText) : null;
|
|
106
|
+
if (!parsed || parsed.name !== stamp.FROZEN_STAMP_NAME) {
|
|
107
|
+
return [{ area: 'frozen', severity: FAIL, text: `${bin} has no ${stamp.FROZEN_STAMP_FILE} beside it — not written by install.sh, lineage unknown. Re-freeze: rm -rf '${dir}' && ./install.sh --tools` }];
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
const partial = ['lib', 'package.json'].filter((p) => !fs.existsSync(path.join(dir, p)));
|
|
111
|
+
if (partial.length) {
|
|
112
|
+
rows.push({ area: 'frozen', severity: FAIL, text: `partial copy — missing ${partial.join(', ')} beside ${bin}. Re-freeze: ./install.sh --tools` });
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
const hb = stamp.handbookInfo(root);
|
|
116
|
+
const c = stamp.classifyFrozen({ root, hb, stampVersion: parsed.version });
|
|
117
|
+
const tree = stamp.freezeVersion(root).version;
|
|
118
|
+
const treeCmds = dispatchedCommands(readText(path.join(root, 'tools', 'colab')) || '');
|
|
119
|
+
const frozenCmds = new Set(dispatchedCommands(readText(bin) || ''));
|
|
120
|
+
const missing = treeCmds.filter((x) => !frozenCmds.has(x));
|
|
121
|
+
const versions = `stamped ${parsed.version}, tree ${tree}`;
|
|
122
|
+
|
|
123
|
+
if (c.state === 'behind') {
|
|
124
|
+
rows.push({ area: 'frozen', severity: FAIL, text: `behind — ${versions}. ${c.reason}` });
|
|
125
|
+
} else if (c.state === 'n-a') {
|
|
126
|
+
rows.push({ area: 'frozen', severity: WARN, text: `cannot compare — ${versions}. ${c.reason}` });
|
|
127
|
+
} else if (missing.length) {
|
|
128
|
+
rows.push({ area: 'frozen', severity: WARN, text: `current as released (${c.reason}) — ${versions}; the tree's unreleased work adds commands, re-freeze after the next tag` });
|
|
129
|
+
} else {
|
|
130
|
+
rows.push({ area: 'frozen', severity: OK, text: `current — ${versions} (${c.reason})` });
|
|
131
|
+
}
|
|
132
|
+
if (missing.length) {
|
|
133
|
+
rows.push({
|
|
134
|
+
area: 'frozen',
|
|
135
|
+
severity: c.state === 'behind' ? FAIL : WARN,
|
|
136
|
+
text: `does not dispatch ${missing.length} command(s) the tree does: ${missing.join(', ')} — a service calling one gets "Unknown command"`,
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
return rows;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** The state file. The CLI creates it lazily, so a consumer reading it early saw an error, not an empty fleet. */
|
|
143
|
+
function checkState({ root, colabHome, home }) {
|
|
144
|
+
const file = path.join(colabHome, 'state.json');
|
|
145
|
+
const cliInstalled = fs.existsSync(path.join(colabHome, 'bin', 'colab'))
|
|
146
|
+
|| fs.existsSync(path.join(home, '.local', 'bin', 'colab'));
|
|
147
|
+
const text = readText(file);
|
|
148
|
+
if (text === null) {
|
|
149
|
+
return {
|
|
150
|
+
area: 'state',
|
|
151
|
+
severity: cliInstalled ? FAIL : WARN,
|
|
152
|
+
text: `no ${file} — ${cliInstalled ? 'the CLI is installed, so anything reading state now errors instead of seeing an empty fleet; ./install.sh --tools creates an empty one' : 'created by ./install.sh --tools (or the first state-changing colab command)'}`,
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
try {
|
|
156
|
+
const st = JSON.parse(text);
|
|
157
|
+
const n = (o) => (o && typeof o === 'object' ? Object.keys(o).length : 0);
|
|
158
|
+
return { area: 'state', severity: OK, text: `${file} — ${n(st.claims)} claim(s), ${n(st.worktrees)} worktree(s)` };
|
|
159
|
+
} catch (e) {
|
|
160
|
+
return { area: 'state', severity: FAIL, text: `${file} is not valid JSON (${e.message}) — every colab command will refuse; run \`colab doctor\` from the working tree` };
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* The fleet: both machine-local registries `colab register` writes. A repos.txt that exists with no
|
|
166
|
+
* live entry is the `--fleet` dead end — seeded from placeholders, and the next command refuses with
|
|
167
|
+
* "No repos registered". That one is a ✗; never having asked for a fleet is a ⚠.
|
|
168
|
+
*/
|
|
169
|
+
function checkFleet({ colabHome }) {
|
|
170
|
+
const rows = [];
|
|
171
|
+
const txtFile = path.join(colabHome, 'repos.txt');
|
|
172
|
+
const txt = readText(txtFile);
|
|
173
|
+
const entries = txt === null ? null
|
|
174
|
+
: txt.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).filter(Boolean);
|
|
175
|
+
let cfgRepos = [];
|
|
176
|
+
try { cfgRepos = JSON.parse(readText(path.join(colabHome, 'config.json')) || '{}').repos || []; } catch (_) { /* reported by colab itself */ }
|
|
177
|
+
|
|
178
|
+
if (entries === null && !cfgRepos.length) {
|
|
179
|
+
rows.push({ area: 'fleet', severity: WARN, text: `nothing registered — add each repo: colab register <path>` });
|
|
180
|
+
} else if (entries !== null && !entries.length) {
|
|
181
|
+
rows.push({ area: 'fleet', severity: FAIL, text: `${txtFile} exists with no live entry (placeholders only) — \`colab update\`/\`colab release-status\` refuse "No repos registered". Fix: colab register <path>` });
|
|
182
|
+
} else {
|
|
183
|
+
const locals = (entries || []).filter((e) => e.startsWith('/') || e.startsWith('~'));
|
|
184
|
+
const unmirrored = locals.filter((e) => !cfgRepos.includes(e));
|
|
185
|
+
rows.push({ area: 'fleet', severity: OK, text: `${(entries || []).length} entr${(entries || []).length === 1 ? 'y' : 'ies'} in repos.txt, ${cfgRepos.length} repo(s) in config.json` });
|
|
186
|
+
if (unmirrored.length) {
|
|
187
|
+
rows.push({ area: 'fleet', severity: WARN, text: `${unmirrored.length} local path(s) in repos.txt missing from config.json (hand-edited?) — their ports are not reserved. \`colab register <path>\` writes both` });
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
return rows;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* The hooklets in THIS clone. Symmetric on purpose: the preflight once warned about gitleaks (the
|
|
195
|
+
* first hooklet's dependency) and said nothing about the identity vocabulary the second needs — and
|
|
196
|
+
* the second guards publication to a public repo. With no vocabulary it warns and passes every commit.
|
|
197
|
+
* Resolution order mirrors templates/pre-commit-identity exactly.
|
|
198
|
+
*/
|
|
199
|
+
function checkHooks({ root, colabHome, home, env }) {
|
|
200
|
+
const hp = gitConfig(root, 'core.hooksPath', env);
|
|
201
|
+
const enabled = hp === '.githooks' || (hp && path.resolve(root, hp) === path.join(root, '.githooks'));
|
|
202
|
+
if (!enabled) {
|
|
203
|
+
return [{ area: 'hooks', severity: WARN, text: `not enabled in this clone (core.hooksPath=${hp || 'unset'}) — ./install.sh --hooks` }];
|
|
204
|
+
}
|
|
205
|
+
const rows = [];
|
|
206
|
+
rows.push(isExecutable('gitleaks', env)
|
|
207
|
+
? { area: 'hooks', severity: OK, text: 'gitleaks on PATH — the secret scan runs' }
|
|
208
|
+
: { area: 'hooks', severity: FAIL, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
|
|
209
|
+
|
|
210
|
+
let vocab; let src;
|
|
211
|
+
if (env.COLAB_IDENTITY_VOCAB) { vocab = env.COLAB_IDENTITY_VOCAB; src = 'COLAB_IDENTITY_VOCAB'; }
|
|
212
|
+
else if ((vocab = gitConfig(root, 'colab.identityVocabulary', env))) { src = 'git config colab.identityVocabulary'; }
|
|
213
|
+
else { vocab = path.join(colabHome, 'identity-vocabulary'); src = 'default'; }
|
|
214
|
+
if (vocab.startsWith('~/')) vocab = path.join(home, vocab.slice(2));
|
|
215
|
+
rows.push(readText(vocab) !== null
|
|
216
|
+
? { area: 'hooks', severity: OK, text: `identity vocabulary ${vocab} (${src}) — the identity scan runs` }
|
|
217
|
+
: { area: 'hooks', severity: FAIL, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
|
|
218
|
+
return rows;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
function runChecks(opts) {
|
|
222
|
+
const o = { env: process.env, ...opts };
|
|
223
|
+
return [
|
|
224
|
+
checkLink(o),
|
|
225
|
+
...checkFrozen(o),
|
|
226
|
+
checkState(o),
|
|
227
|
+
...checkFleet(o),
|
|
228
|
+
...checkHooks(o),
|
|
229
|
+
];
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
const MARK = { [OK]: '✓', [WARN]: '⚠', [FAIL]: '✗' };
|
|
233
|
+
|
|
234
|
+
function render(rows) {
|
|
235
|
+
const lines = rows.map((r) => ` ${MARK[r.severity]} ${r.area.padEnd(7)} ${r.text}`);
|
|
236
|
+
const fails = rows.filter((r) => r.severity === FAIL).length;
|
|
237
|
+
const warns = rows.filter((r) => r.severity === WARN).length;
|
|
238
|
+
lines.push('');
|
|
239
|
+
lines.push(fails
|
|
240
|
+
? ` ${fails} ✗ row(s) — something installed here is stale or unusable (exit 1)`
|
|
241
|
+
: ` no ✗ rows${warns ? ` — ${warns} ⚠ row(s) are things not set up, which may be deliberate` : ''} (exit 0)`);
|
|
242
|
+
return { text: lines.join('\n'), code: fails ? 1 : 0 };
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
if (require.main === module) {
|
|
246
|
+
const argv = process.argv.slice(2);
|
|
247
|
+
const val = (flag, dflt) => { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : dflt; };
|
|
248
|
+
const home = val('--home', require('os').homedir());
|
|
249
|
+
const root = path.resolve(val('--root', path.resolve(__dirname, '..', '..')));
|
|
250
|
+
const colabHome = val('--colab-home', process.env.COLAB_HOME || path.join(home, '.colab'));
|
|
251
|
+
const { text, code } = render(runChecks({ root, colabHome, home }));
|
|
252
|
+
process.stdout.write(text + '\n');
|
|
253
|
+
process.exitCode = code;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
module.exports = {
|
|
257
|
+
OK, WARN, FAIL,
|
|
258
|
+
dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, runChecks, render,
|
|
259
|
+
};
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The repo's instruction file, and what an agent actually loads from it (#417).
|
|
4
|
+
*
|
|
5
|
+
* Two files can carry a repo's agent instructions: `AGENTS.md`, which most agent tools read,
|
|
6
|
+
* and `CLAUDE.md`, which one tool reads by name. The shape this handbook documents
|
|
7
|
+
* (CONVENTIONS.md §9 step 5) is:
|
|
8
|
+
*
|
|
9
|
+
* - repo prose lives in `AGENTS.md`;
|
|
10
|
+
* - `CLAUDE.md` is a thin shell: an `@AGENTS.md` import plus the blocks tools look up
|
|
11
|
+
* in `CLAUDE.md` BY NAME (this handbook's Conventions block with its stamp, and any
|
|
12
|
+
* other tool-managed block);
|
|
13
|
+
* - no block lives in both files.
|
|
14
|
+
*
|
|
15
|
+
* So three questions get three different answers, and every consumer has to ask the right one:
|
|
16
|
+
*
|
|
17
|
+
* | question | answer |
|
|
18
|
+
* |--------------------------------------------|------------------------------------------|
|
|
19
|
+
* | where are the repo's rules written? | `authoredRouter()` — AGENTS.md, else CLAUDE.md |
|
|
20
|
+
* | what is loaded into every session (cost)? | `collectLoaded()` — CLAUDE.md + every in-repo @-import |
|
|
21
|
+
* | where do by-name tool blocks live? | always `CLAUDE.md` (stamp.js, `colab update`) |
|
|
22
|
+
*
|
|
23
|
+
* Import resolution mirrors the loader's own rules, narrowed to what a repo is accountable for:
|
|
24
|
+
*
|
|
25
|
+
* - an import is an `@<path>` token at the start of a line or after whitespace (so
|
|
26
|
+
* `user@example.md` is not one); trailing `),;:!?` and one trailing `.` are stripped;
|
|
27
|
+
* - tokens inside fenced code blocks and inline code spans are ignored (a `@me` in a
|
|
28
|
+
* `gh issue edit --add-assignee @me` example is not an import);
|
|
29
|
+
* - paths are relative to the IMPORTING file;
|
|
30
|
+
* - in-repo only: an absolute path, a `~` path, a drive letter, or anything that normalizes
|
|
31
|
+
* outside the repo is rejected and recorded, never followed — a per-user import is that
|
|
32
|
+
* user's cost, not the repo's;
|
|
33
|
+
* - recursive to depth IMPORT_MAX_DEPTH (the entry file is depth 0); deeper is `truncated`;
|
|
34
|
+
* - cycle-safe: each file is read and counted once;
|
|
35
|
+
* - a missing target is recorded, not an error — prose like `@types/node` is common.
|
|
36
|
+
*
|
|
37
|
+
* Pure: every read goes through the caller's `readFile(relPath) -> string|null`, so the
|
|
38
|
+
* audit's local and remote sources both work. No dependencies.
|
|
39
|
+
*
|
|
40
|
+
* `templates/docs-lint.mjs` is copy-and-own and cannot require this module; it carries a
|
|
41
|
+
* one-level inline copy of `parseImports` that must stay in step with this one (both have
|
|
42
|
+
* tests on the same cases).
|
|
43
|
+
*/
|
|
44
|
+
|
|
45
|
+
const path = require('path');
|
|
46
|
+
|
|
47
|
+
const IMPORT_MAX_DEPTH = 5;
|
|
48
|
+
const SHELL_IMPORT = '@AGENTS.md';
|
|
49
|
+
const ENTRY = 'CLAUDE.md';
|
|
50
|
+
const AUTHORED = 'AGENTS.md';
|
|
51
|
+
|
|
52
|
+
const escapeRe = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
53
|
+
|
|
54
|
+
const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
|
|
55
|
+
|
|
56
|
+
/** Every line with fenced-block content and inline code spans blanked (line numbers kept). */
|
|
57
|
+
function stripCode(text) {
|
|
58
|
+
const out = [];
|
|
59
|
+
let fence = null;
|
|
60
|
+
for (const line of String(text).split(/\r?\n/)) {
|
|
61
|
+
const m = line.match(FENCE_RE);
|
|
62
|
+
if (fence) {
|
|
63
|
+
if (m && m[1][0] === fence[0] && m[1].length >= fence.length) fence = null;
|
|
64
|
+
out.push('');
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
67
|
+
if (m) { fence = m[1]; out.push(''); continue; }
|
|
68
|
+
// Inline code spans: a run of N backticks closes at the next run of exactly N.
|
|
69
|
+
out.push(line.replace(/(`+)[\s\S]*?\1/g, (s) => ' '.repeat(s.length)));
|
|
70
|
+
}
|
|
71
|
+
return out;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const TOKEN_RE = /(^|\s)@([^\s]+)/g;
|
|
75
|
+
|
|
76
|
+
/** `[{ raw, line }]` — every import token, in order. `line` is 1-based. */
|
|
77
|
+
function parseImports(text) {
|
|
78
|
+
const found = [];
|
|
79
|
+
stripCode(text).forEach((line, i) => {
|
|
80
|
+
TOKEN_RE.lastIndex = 0;
|
|
81
|
+
let m;
|
|
82
|
+
while ((m = TOKEN_RE.exec(line)) !== null) {
|
|
83
|
+
let raw = m[2].replace(/[),;:!?]+$/, '').replace(/\.$/, '');
|
|
84
|
+
if (raw) found.push({ raw, line: i + 1 });
|
|
85
|
+
}
|
|
86
|
+
});
|
|
87
|
+
return found;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** `{ path }` (repo-relative, posix) or `{ rejected: 'absolute'|'home'|'escapes' }`. */
|
|
91
|
+
function resolveImport(fromRel, raw) {
|
|
92
|
+
if (raw.startsWith('~')) return { rejected: 'home' };
|
|
93
|
+
if (raw.startsWith('/') || raw.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(raw)) return { rejected: 'absolute' };
|
|
94
|
+
const joined = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), raw.replace(/\\/g, '/')));
|
|
95
|
+
if (joined === '..' || joined.startsWith('../') || joined === '.') return { rejected: 'escapes' };
|
|
96
|
+
return { path: joined };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* What the loader pulls in when it reads `entry`: `{ files, rejected, missing, truncated }`.
|
|
101
|
+
* `files` is depth-first in import order, entry first: `[{ path, text, depth, from }]`.
|
|
102
|
+
* A missing entry yields `files: []`.
|
|
103
|
+
*/
|
|
104
|
+
function collectLoaded(readFile, entry = ENTRY, { maxDepth = IMPORT_MAX_DEPTH } = {}) {
|
|
105
|
+
const files = [];
|
|
106
|
+
const rejected = [];
|
|
107
|
+
const missing = [];
|
|
108
|
+
const truncated = [];
|
|
109
|
+
const seen = new Set();
|
|
110
|
+
const visit = (rel, depth, from) => {
|
|
111
|
+
if (seen.has(rel)) return;
|
|
112
|
+
seen.add(rel);
|
|
113
|
+
const text = readFile(rel);
|
|
114
|
+
if (text === null || text === undefined) {
|
|
115
|
+
if (from !== null) missing.push({ path: rel, from });
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
118
|
+
files.push({ path: rel, text, depth, from });
|
|
119
|
+
for (const { raw } of parseImports(text)) {
|
|
120
|
+
const r = resolveImport(rel, raw);
|
|
121
|
+
if (r.rejected) { rejected.push({ raw, from: rel, reason: r.rejected }); continue; }
|
|
122
|
+
if (depth + 1 > maxDepth) { if (!seen.has(r.path)) truncated.push({ path: r.path, from: rel }); continue; }
|
|
123
|
+
visit(r.path, depth + 1, rel);
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
visit(entry, 0, null);
|
|
127
|
+
return { files, rejected, missing, truncated };
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** In-repo imports of `CLAUDE.md` that exist, in order (one level). */
|
|
131
|
+
function existingImports(readFile, entry = ENTRY) {
|
|
132
|
+
const text = readFile(entry);
|
|
133
|
+
if (text === null || text === undefined) return [];
|
|
134
|
+
const out = [];
|
|
135
|
+
for (const { raw } of parseImports(text)) {
|
|
136
|
+
const r = resolveImport(entry, raw);
|
|
137
|
+
if (r.path && !out.includes(r.path) && readFile(r.path) !== null && readFile(r.path) !== undefined) out.push(r.path);
|
|
138
|
+
}
|
|
139
|
+
return out;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Where the repo's rules are WRITTEN: the first existing in-repo import of `CLAUDE.md` (the
|
|
144
|
+
* shell case), else `CLAUDE.md`, else `AGENTS.md`, else null.
|
|
145
|
+
*/
|
|
146
|
+
function authoredRouter(readFile) {
|
|
147
|
+
const imports = existingImports(readFile);
|
|
148
|
+
if (imports.length) return imports[0];
|
|
149
|
+
if (readFile(ENTRY) !== null && readFile(ENTRY) !== undefined) return ENTRY;
|
|
150
|
+
if (readFile(AUTHORED) !== null && readFile(AUTHORED) !== undefined) return AUTHORED;
|
|
151
|
+
return null;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Tool-written blocks, detected by their open/close tags. Only a properly paired block
|
|
156
|
+
* counts. Kept deliberately small: the generic BEGIN/END row covers any generator using that
|
|
157
|
+
* convention (one framework writes `<!-- BEGIN:nextjs-agent-rules -->` … `<!-- END:… -->`),
|
|
158
|
+
* so a new row is only for a tool with a different syntax, and only with a real sample.
|
|
159
|
+
*/
|
|
160
|
+
const TOOL_BLOCKS = [
|
|
161
|
+
{ id: 'laravel-boost', open: /^\s*<laravel-boost-guidelines>\s*$/, close: /^\s*<\/laravel-boost-guidelines>\s*$/ },
|
|
162
|
+
{ id: 'begin-end', open: /^\s*<!--\s*BEGIN:(\S+)\s*-->\s*$/, close: (name) => new RegExp(`^\\s*<!--\\s*END:${escapeRe(name)}\\s*-->\\s*$`) },
|
|
163
|
+
// #419: `<!-- <name>:start … -->` … `<!-- <name>:end -->` — a UI package writes its workflow block
|
|
164
|
+
// this way, with a trailing note on the open line (`(managed by … — edit … instead)`); the
|
|
165
|
+
// colab:derived span (#117) has the same shape. The name is everything before the LAST `:start`.
|
|
166
|
+
{ id: 'start-end', open: /^\s*<!--\s*(\S+?):start(?:\s.*)?-->\s*$/, close: (name) => new RegExp(`^\\s*<!--\\s*${escapeRe(name)}:end(?:\\s.*)?-->\\s*$`) },
|
|
167
|
+
];
|
|
168
|
+
|
|
169
|
+
/** `[{ id, startLine, endLine }]` for every paired tool block in `text`. */
|
|
170
|
+
function findToolBlocks(text) {
|
|
171
|
+
const lines = String(text).split(/\r?\n/);
|
|
172
|
+
const found = [];
|
|
173
|
+
for (let i = 0; i < lines.length; i++) {
|
|
174
|
+
for (const row of TOOL_BLOCKS) {
|
|
175
|
+
const m = lines[i].match(row.open);
|
|
176
|
+
if (!m) continue;
|
|
177
|
+
const id = row.id === 'laravel-boost' ? row.id : m[1];
|
|
178
|
+
const close = typeof row.close === 'function' ? row.close(m[1]) : row.close;
|
|
179
|
+
for (let j = i + 1; j < lines.length; j++) {
|
|
180
|
+
if (close.test(lines[j])) { found.push({ id, startLine: i + 1, endLine: j + 1 }); i = j; break; }
|
|
181
|
+
}
|
|
182
|
+
break;
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
return found;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** `[{ id, paths }]` — every tool block id present in more than one of `files` (`[{ path, text }]`). */
|
|
189
|
+
function duplicateToolBlocks(files) {
|
|
190
|
+
const where = new Map();
|
|
191
|
+
for (const f of files) {
|
|
192
|
+
for (const b of findToolBlocks(f.text)) {
|
|
193
|
+
if (!where.has(b.id)) where.set(b.id, []);
|
|
194
|
+
const list = where.get(b.id);
|
|
195
|
+
if (!list.includes(f.path)) list.push(f.path);
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
return [...where].filter(([, paths]) => paths.length > 1).map(([id, paths]) => ({ id, paths }));
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Does `text` (a CLAUDE.md) import AGENTS.md — i.e. is it the thin-shell shape? */
|
|
202
|
+
function isThinShell(text) {
|
|
203
|
+
return parseImports(text).some((i) => i.raw === AUTHORED || i.raw === './' + AUTHORED);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* The handbook's Conventions block in a CLAUDE.md: `{ startLine, endLine }` (1-based, inclusive)
|
|
208
|
+
* or null. It has no close tag, so its extent is structural: it opens at the `## Conventions`-style
|
|
209
|
+
* level-2+ heading directly above its stamp (or at the stamp — or, unstamped, the template's
|
|
210
|
+
* "This repo follows the [colab-handbook]" sentence — when there is no such heading) and runs
|
|
211
|
+
* to the line before the next heading of the same or a higher level, else to EOF. A repo that appended its own bullets to the block keeps them inside it — those are
|
|
212
|
+
* the block's to carry.
|
|
213
|
+
*/
|
|
214
|
+
const STAMP_RE = /<!--\s*colab-handbook\s*@/;
|
|
215
|
+
const FOLLOWS_RE = /^\s*This repo follows the \[colab-handbook\]/; // the template's own sentence, not any mention
|
|
216
|
+
const HEADING_RE = /^(#{1,6})\s/;
|
|
217
|
+
function conventionsBlock(text) {
|
|
218
|
+
const lines = String(text).split(/\r?\n/);
|
|
219
|
+
const code = stripCode(text);
|
|
220
|
+
let anchor = lines.findIndex((l) => STAMP_RE.test(l));
|
|
221
|
+
if (anchor < 0) anchor = code.findIndex((l) => FOLLOWS_RE.test(l));
|
|
222
|
+
if (anchor < 0) return null;
|
|
223
|
+
let start = anchor;
|
|
224
|
+
let level = 7; // no heading: the block ends at the next heading of any level
|
|
225
|
+
for (let i = anchor - 1; i >= 0; i--) {
|
|
226
|
+
if (!lines[i].trim()) continue;
|
|
227
|
+
const h = code[i].match(HEADING_RE);
|
|
228
|
+
if (h && h[1].length >= 2) { start = i; level = h[1].length; } // a level-1 heading is the file's title
|
|
229
|
+
break; // only the nearest non-blank line above may be the block's heading
|
|
230
|
+
}
|
|
231
|
+
let end = lines.length - 1;
|
|
232
|
+
for (let i = anchor + 1; i < lines.length; i++) {
|
|
233
|
+
const h = code[i].match(HEADING_RE);
|
|
234
|
+
if (h && h[1].length <= level) { end = i - 1; break; }
|
|
235
|
+
}
|
|
236
|
+
while (end > anchor && !lines[end].trim()) end--;
|
|
237
|
+
return { startLine: start + 1, endLine: end + 1 };
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Lines of a CLAUDE.md that the thin-shell shape does not allow (#419): `[lineNo]`, 1-based.
|
|
242
|
+
* Allowed: blank lines, lines made only of @-import tokens, paired tool blocks (TOOL_BLOCKS), and
|
|
243
|
+
* the Conventions block. Everything else is repo prose, which belongs in AGENTS.md.
|
|
244
|
+
*/
|
|
245
|
+
function shellResidue(text) {
|
|
246
|
+
const lines = String(text).split(/\r?\n/);
|
|
247
|
+
if (lines.length && lines[lines.length - 1] === '') lines.pop();
|
|
248
|
+
const allowed = new Set();
|
|
249
|
+
const cover = (a, b) => { for (let n = a; n <= b; n++) allowed.add(n); };
|
|
250
|
+
for (const b of findToolBlocks(text)) cover(b.startLine, b.endLine);
|
|
251
|
+
const conv = conventionsBlock(text);
|
|
252
|
+
if (conv) cover(conv.startLine, conv.endLine);
|
|
253
|
+
const out = [];
|
|
254
|
+
lines.forEach((line, i) => {
|
|
255
|
+
const n = i + 1;
|
|
256
|
+
if (allowed.has(n) || !line.trim()) return;
|
|
257
|
+
if (line.trim().split(/\s+/).every((tok) => /^@\S+$/.test(tok))) return;
|
|
258
|
+
out.push(n);
|
|
259
|
+
});
|
|
260
|
+
return out;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* `[3,4,5,9]` → `"3-5, 9"`. With `text`, a run also spans lines that are blank in it, so prose
|
|
265
|
+
* paragraphs separated by empty lines read as one range (`1-249`, not forty fragments).
|
|
266
|
+
*/
|
|
267
|
+
function lineRanges(nums, text = null) {
|
|
268
|
+
const lines = text === null ? null : String(text).split(/\r?\n/);
|
|
269
|
+
const bridges = (a, b) => {
|
|
270
|
+
if (b === a + 1) return true;
|
|
271
|
+
if (!lines) return false;
|
|
272
|
+
for (let n = a + 1; n < b; n++) if ((lines[n - 1] || '').trim()) return false;
|
|
273
|
+
return true;
|
|
274
|
+
};
|
|
275
|
+
const parts = [];
|
|
276
|
+
for (let i = 0; i < nums.length; i++) {
|
|
277
|
+
let j = i;
|
|
278
|
+
while (j + 1 < nums.length && bridges(nums[j], nums[j + 1])) j++;
|
|
279
|
+
parts.push(j > i ? `${nums[i]}-${nums[j]}` : `${nums[i]}`);
|
|
280
|
+
i = j;
|
|
281
|
+
}
|
|
282
|
+
return parts.join(', ');
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
module.exports = {
|
|
286
|
+
IMPORT_MAX_DEPTH,
|
|
287
|
+
SHELL_IMPORT,
|
|
288
|
+
ENTRY,
|
|
289
|
+
AUTHORED,
|
|
290
|
+
parseImports,
|
|
291
|
+
resolveImport,
|
|
292
|
+
collectLoaded,
|
|
293
|
+
existingImports,
|
|
294
|
+
authoredRouter,
|
|
295
|
+
TOOL_BLOCKS,
|
|
296
|
+
findToolBlocks,
|
|
297
|
+
duplicateToolBlocks,
|
|
298
|
+
isThinShell,
|
|
299
|
+
conventionsBlock,
|
|
300
|
+
shellResidue,
|
|
301
|
+
lineRanges,
|
|
302
|
+
};
|