@futurelastic/colab-handbook 1.13.0-rc.9 → 1.13.0
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 +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +116 -15
- package/package.json +1 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +72 -5
- package/templates/ci-node.yml +74 -6
- package/templates/ci-python.yml +74 -6
- package/templates/release-auto.yml +68 -4
- package/tools/colab +784 -91
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +70 -15
- 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 +110 -15
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
package/tools/lib/codec/claim.js
CHANGED
|
@@ -35,15 +35,18 @@ const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
|
|
|
35
35
|
const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
|
|
36
36
|
|
|
37
37
|
/**
|
|
38
|
-
* Does `v` look like a session URL
|
|
39
|
-
* (#306), not a gate — claim-identity.js re-exports this one copy of it.
|
|
38
|
+
* Does `v` look like a session id — a URL, a `session_…` token, a bare uuid — rather than a display
|
|
39
|
+
* name? A SHAPE heuristic (#306), not a gate — claim-identity.js re-exports this one copy of it.
|
|
40
|
+
* The uuid shape is #531: `--session` takes any stable id, and an engine whose session id is a bare
|
|
41
|
+
* uuid must not have it read back from a claim comment as a session NAME.
|
|
40
42
|
*/
|
|
41
43
|
function looksLikeSessionId(v) {
|
|
42
44
|
const s = String(v == null ? '' : v).trim();
|
|
43
45
|
if (!s) return false;
|
|
44
46
|
// #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
|
|
45
47
|
// too — a stable join key, not a display name — so it reads back as one from a claim comment.
|
|
46
|
-
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s)
|
|
48
|
+
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s)
|
|
49
|
+
|| /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
|
|
47
50
|
}
|
|
48
51
|
|
|
49
52
|
/**
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/config-set.js — a TUNING change to `.github/project.yml`, made and shipped cheaply (#561).
|
|
4
|
+
*
|
|
5
|
+
* Before this module, changing one repo-owned value (`ship-batch: 2`, a threshold) cost an issue, a
|
|
6
|
+
* code session, a wrap and a ship — the same ceremony as a feature. Repos that pay that much per
|
|
7
|
+
* tuning step do not tune. The descriptor stays committed (CI templates read it from the commit,
|
|
8
|
+
* worktrees are cut from git, and authority-granting fields need their review trail), so the cost is
|
|
9
|
+
* cut on two sides instead:
|
|
10
|
+
*
|
|
11
|
+
* 1. `colab config set <key> <value>` writes ONE tuning key, validated by the same parser every
|
|
12
|
+
* reader of that key uses, and commits it on a short branch — no checkout is touched.
|
|
13
|
+
* 2. `colab ship` computes a TUNING-ONLY class from the diff, modelled on the docs-only door
|
|
14
|
+
* (tools/lib/docs-only.js): no issue, no `Closes #N`, the evidence in the commit body, every
|
|
15
|
+
* other precondition unchanged.
|
|
16
|
+
*
|
|
17
|
+
* The allowlist and the authority list below are constants, so widening either is a handbook change
|
|
18
|
+
* reviewed in a commit — never a project.yml field, a flag or an env var. Every doubt resolves to
|
|
19
|
+
* "not tuning": a second file, a comment line, an authority key, a malformed value, a git read that
|
|
20
|
+
* failed. A false "no" costs a human click; a false "yes" lands an unreviewed change.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const yaml = require('./yaml');
|
|
24
|
+
const shipBatch = require('./ship-batch');
|
|
25
|
+
const ciProfile = require('./ci-profile');
|
|
26
|
+
const thresholds = require('./thresholds');
|
|
27
|
+
|
|
28
|
+
const DESCRIPTOR = '.github/project.yml';
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The tuning allowlist: key → the one validator every reader of that key already uses. Each returns
|
|
32
|
+
* a problem sentence, or null when the parsed descriptor's value is valid (absent counts as valid —
|
|
33
|
+
* removing a tuning key restores the documented default).
|
|
34
|
+
*/
|
|
35
|
+
const TUNING = Object.freeze({
|
|
36
|
+
'ship-batch': (doc) => { const r = shipBatch.parseShipBatch(doc); return r.valid ? null : r.reason; },
|
|
37
|
+
'ship-batch-wait': (doc) => { const r = shipBatch.parseShipBatchWait(doc); return r.valid ? null : r.reason; },
|
|
38
|
+
'ci-wait-factor': (doc) => { const r = ciProfile.parseFactor(doc); return r.valid ? null : r.reason; },
|
|
39
|
+
[thresholds.KEY]: (doc) => { const r = thresholds.parseThresholds(doc); return r.problems.length ? r.problems.join('; ') : null; },
|
|
40
|
+
});
|
|
41
|
+
const TUNING_KEYS = Object.freeze(Object.keys(TUNING));
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Never on this path: these grant authority or change what deploys (#561 §4). Listed so `config set`
|
|
45
|
+
* can say WHY it refuses them; any key outside TUNING is refused all the same.
|
|
46
|
+
*/
|
|
47
|
+
const AUTHORITY_KEYS = Object.freeze([
|
|
48
|
+
'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'trust-humans',
|
|
49
|
+
'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
|
|
50
|
+
]);
|
|
51
|
+
|
|
52
|
+
/** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`). */
|
|
53
|
+
const VALUE_RE = /^[A-Za-z0-9._-]+$/;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* `ship-batch` → `{ top: 'ship-batch', sub: null }`; `thresholds.hot-file-count` → `{ top:
|
|
57
|
+
* 'thresholds', sub: 'hot-file-count' }`. Returns `{ problem }` for anything outside the allowlist.
|
|
58
|
+
*/
|
|
59
|
+
function parseKeyPath(arg) {
|
|
60
|
+
const s = String(arg || '').trim();
|
|
61
|
+
const dot = s.indexOf('.');
|
|
62
|
+
const top = dot < 0 ? s : s.slice(0, dot);
|
|
63
|
+
const sub = dot < 0 ? null : s.slice(dot + 1);
|
|
64
|
+
if (AUTHORITY_KEYS.includes(top)) {
|
|
65
|
+
return { problem: `${top} grants authority or changes what deploys — it is never a tuning change; edit it on a branch with an issue and ship it the full way (#561)` };
|
|
66
|
+
}
|
|
67
|
+
if (!TUNING[top]) return { problem: `${s} is not a tuning key (tuning keys: ${TUNING_KEYS.join(', ')}, thresholds.<name>)` };
|
|
68
|
+
if (top === thresholds.KEY) {
|
|
69
|
+
if (!sub) return { problem: `${top} is a map — set one entry: ${top}.<name> (names: ${Object.keys(thresholds.SPEC).join(', ')})` };
|
|
70
|
+
if (!thresholds.SPEC[sub]) return { problem: `${top}.${sub} is not a known threshold (known: ${Object.keys(thresholds.SPEC).join(', ')})` };
|
|
71
|
+
} else if (sub !== null) {
|
|
72
|
+
return { problem: `${top} is a scalar — set it as ${top}, not ${s}` };
|
|
73
|
+
}
|
|
74
|
+
return { top, sub };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const isTopKeyLine = (line) => /^[^\s#][^:]*:/.test(line);
|
|
78
|
+
const topKeyOf = (line) => (isTopKeyLine(line) ? line.slice(0, line.indexOf(':')).trim() : null);
|
|
79
|
+
|
|
80
|
+
/** Replace a `key: value # comment` line's value, keeping the indent and the trailing comment. */
|
|
81
|
+
function replaceValue(line, value) {
|
|
82
|
+
const m = /^(\s*[^:#]+:)([ \t]*)([^#]*?)([ \t]*#.*)?$/.exec(line);
|
|
83
|
+
if (!m) return null;
|
|
84
|
+
return `${m[1]} ${value}${m[4] || ''}`;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Edit ONE tuning key in the descriptor's text, leaving every other byte alone. Returns `{ text,
|
|
89
|
+
* old }` (`old` is the previous raw value, or null when the key was absent), or `{ problem }`.
|
|
90
|
+
*/
|
|
91
|
+
function editText(text, keyPath, value) {
|
|
92
|
+
if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ -)` };
|
|
93
|
+
const src = String(text);
|
|
94
|
+
const eol = src.endsWith('\n') ? '' : '\n';
|
|
95
|
+
const lines = src.split('\n');
|
|
96
|
+
if (lines[lines.length - 1] === '') lines.pop();
|
|
97
|
+
const topIdx = lines.findIndex((l) => topKeyOf(l) === keyPath.top);
|
|
98
|
+
const blockEnd = (start) => { let j = start + 1; while (j < lines.length && !isTopKeyLine(lines[j]) && !/^#/.test(lines[j])) j++; return j; };
|
|
99
|
+
const restOf = (l) => l.slice(l.indexOf(':') + 1).replace(/[ \t]#.*$/, '').trim();
|
|
100
|
+
|
|
101
|
+
if (!keyPath.sub) {
|
|
102
|
+
if (topIdx < 0) return { text: `${src}${eol}${keyPath.top}: ${value}\n`, old: null };
|
|
103
|
+
const rest = restOf(lines[topIdx]);
|
|
104
|
+
if (rest === '' && blockEnd(topIdx) > topIdx + 1 && lines.slice(topIdx + 1, blockEnd(topIdx)).some((l) => l.trim() && !l.trim().startsWith('#'))) {
|
|
105
|
+
return { problem: `${keyPath.top} is written as a block in ${DESCRIPTOR} — edit it by hand` };
|
|
106
|
+
}
|
|
107
|
+
lines[topIdx] = replaceValue(lines[topIdx], value);
|
|
108
|
+
return { text: lines.join('\n') + '\n', old: rest === '' ? null : rest };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
if (topIdx < 0) return { text: `${src}${eol}${keyPath.top}:\n ${keyPath.sub}: ${value}\n`, old: null };
|
|
112
|
+
if (restOf(lines[topIdx]) !== '') return { problem: `${keyPath.top} is written inline in ${DESCRIPTOR} — edit it by hand` };
|
|
113
|
+
const end = blockEnd(topIdx);
|
|
114
|
+
let lastChild = topIdx, indent = ' ';
|
|
115
|
+
for (let j = topIdx + 1; j < end; j++) {
|
|
116
|
+
const l = lines[j];
|
|
117
|
+
if (!l.trim() || l.trim().startsWith('#')) continue;
|
|
118
|
+
const m = /^(\s+)([^:#]+):/.exec(l);
|
|
119
|
+
if (!m) return { problem: `${keyPath.top} has a line this command cannot read (${JSON.stringify(l)}) — edit it by hand` };
|
|
120
|
+
lastChild = j; indent = m[1];
|
|
121
|
+
if (m[2].trim() === keyPath.sub) {
|
|
122
|
+
const old = restOf(l);
|
|
123
|
+
lines[j] = replaceValue(l, value);
|
|
124
|
+
return { text: lines.join('\n') + '\n', old: old === '' ? null : old };
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
lines.splice(lastChild + 1, 0, `${indent}${keyPath.sub}: ${value}`);
|
|
128
|
+
return { text: lines.join('\n') + '\n', old: null };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** The value a key path resolves to in a parsed doc (undefined when absent). */
|
|
132
|
+
function valueAt(doc, keyPath) {
|
|
133
|
+
const top = doc ? doc[keyPath.top] : undefined;
|
|
134
|
+
if (!keyPath.sub) return top;
|
|
135
|
+
return top && typeof top === 'object' ? top[keyPath.sub] : undefined;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Line diff → the 0-based indices of changed lines on each side. A plain LCS: a descriptor is a few
|
|
140
|
+
* hundred lines at most, and a dependency-free diff keeps this module pure and testable.
|
|
141
|
+
*/
|
|
142
|
+
function changedLines(aText, bText) {
|
|
143
|
+
const a = String(aText).split('\n'), b = String(bText).split('\n');
|
|
144
|
+
const n = a.length, m = b.length;
|
|
145
|
+
const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
|
|
146
|
+
for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) {
|
|
147
|
+
dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
|
|
148
|
+
}
|
|
149
|
+
const del = [], add = [];
|
|
150
|
+
let i = 0, j = 0;
|
|
151
|
+
while (i < n && j < m) {
|
|
152
|
+
if (a[i] === b[j]) { i++; j++; } else if (dp[i + 1][j] >= dp[i][j + 1]) del.push(i++); else add.push(j++);
|
|
153
|
+
}
|
|
154
|
+
while (i < n) del.push(i++);
|
|
155
|
+
while (j < m) add.push(j++);
|
|
156
|
+
return { a, b, del, add };
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* The top-level key whose block holds line `idx`, or null for a top-level comment / a line before
|
|
161
|
+
* any key. A blank line is reported as `''` (harmless wherever it sits).
|
|
162
|
+
*/
|
|
163
|
+
function ownerOf(lines, idx) {
|
|
164
|
+
const l = lines[idx];
|
|
165
|
+
if (!l.trim()) return '';
|
|
166
|
+
if (/^#/.test(l)) return null;
|
|
167
|
+
for (let k = idx; k >= 0; k--) {
|
|
168
|
+
if (/^#/.test(lines[k])) return null; // a top-level comment ends the block above it
|
|
169
|
+
const key = topKeyOf(lines[k]);
|
|
170
|
+
if (key !== null) return key;
|
|
171
|
+
}
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Is the change from `baseText` to `headText` (both the descriptor's full text) TUNING ONLY?
|
|
177
|
+
* `paths` are the changed entries for the whole diff — `[{ path, oldMode, newMode, binary }]`, the
|
|
178
|
+
* shape docs-only.js reads — so a second file anywhere refuses the class.
|
|
179
|
+
*
|
|
180
|
+
* Tuning only means: exactly one file changed, the descriptor, as a regular text file; every changed
|
|
181
|
+
* non-blank line sits inside a tuning key's block; every other key parses identical on both sides;
|
|
182
|
+
* and every tuning key that moved holds a valid value (or is absent) at head.
|
|
183
|
+
*
|
|
184
|
+
* Returns `{ tuning, keys, reason }` — `reason` is one line for a human, set on both outcomes.
|
|
185
|
+
*/
|
|
186
|
+
function classify({ entries, baseText, headText }) {
|
|
187
|
+
const no = (reason, keys = []) => ({ tuning: false, keys, reason });
|
|
188
|
+
const files = [...new Set((entries || []).map((e) => e.path))];
|
|
189
|
+
if (!files.length) return no('empty diff — nothing to call tuning');
|
|
190
|
+
if (files.length !== 1 || files[0] !== DESCRIPTOR) {
|
|
191
|
+
const other = files.filter((f) => f !== DESCRIPTOR);
|
|
192
|
+
return no(`changes ${other.length ? other.slice(0, 3).join(', ') + (other.length > 3 ? ` +${other.length - 3} more` : '') : files.join(', ')} — a tuning change touches ${DESCRIPTOR} alone`);
|
|
193
|
+
}
|
|
194
|
+
for (const e of entries) {
|
|
195
|
+
if (e.binary) return no(`${DESCRIPTOR} reads as binary`);
|
|
196
|
+
if ((e.oldMode && e.oldMode !== '100644' && e.oldMode !== '000000') || (e.newMode && e.newMode !== '100644')) {
|
|
197
|
+
return no(`${DESCRIPTOR} mode change (${e.oldMode} → ${e.newMode})`);
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
if (typeof baseText !== 'string' || typeof headText !== 'string') return no(`could not read ${DESCRIPTOR} on both sides`);
|
|
201
|
+
|
|
202
|
+
const d = changedLines(baseText, headText);
|
|
203
|
+
const owners = new Set();
|
|
204
|
+
for (const [lines, idxs] of [[d.a, d.del], [d.b, d.add]]) {
|
|
205
|
+
for (const idx of idxs) {
|
|
206
|
+
const o = ownerOf(lines, idx);
|
|
207
|
+
if (o === '') continue;
|
|
208
|
+
if (o === null) return no(`line ${JSON.stringify(lines[idx].slice(0, 60))} is a top-level comment or sits outside any key`);
|
|
209
|
+
owners.add(o);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
if (!owners.size) return no('only blank lines changed — nothing to call tuning');
|
|
213
|
+
const offending = [...owners].filter((k) => !TUNING[k]);
|
|
214
|
+
if (offending.length) {
|
|
215
|
+
const auth = offending.filter((k) => AUTHORITY_KEYS.includes(k));
|
|
216
|
+
return no(`${offending.join(', ')} ${offending.length > 1 ? 'are' : 'is'} not a tuning key${auth.length ? ` (${auth.join(', ')} grant${auth.length > 1 ? '' : 's'} authority)` : ''}`, [...owners]);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
let base, head;
|
|
220
|
+
try { base = yaml.parse(baseText) || {}; head = yaml.parse(headText) || {}; } catch (e) { return no(`${DESCRIPTOR} does not parse: ${e.message}`); }
|
|
221
|
+
const keys = [...new Set([...Object.keys(base), ...Object.keys(head)])];
|
|
222
|
+
const moved = keys.filter((k) => JSON.stringify(base[k]) !== JSON.stringify(head[k]));
|
|
223
|
+
const nonTuning = moved.filter((k) => !TUNING[k]);
|
|
224
|
+
if (nonTuning.length) return no(`${nonTuning.join(', ')} changed value — not a tuning key`, moved);
|
|
225
|
+
if (!moved.length) return no('no value changed — formatting alone is not a tuning change');
|
|
226
|
+
const bad = moved.map((k) => TUNING[k](head)).filter(Boolean);
|
|
227
|
+
if (bad.length) return no(`malformed tuning value: ${bad.join('; ')}`, moved);
|
|
228
|
+
return { tuning: true, keys: moved, reason: `tuning-only (${moved.join(', ')})` };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* The branch shape, with I/O: what `branch` changes relative to its merge base with `base` — the
|
|
233
|
+
* same three-dot diff the squash would land, read through docs-only.js's entry reader so both doors
|
|
234
|
+
* judge one diff. `git` is tools/lib/git.js (or a fake with its `git()` shape).
|
|
235
|
+
*/
|
|
236
|
+
function branchTuning(git, repo, base, branch) {
|
|
237
|
+
const docsOnly = require('./docs-only');
|
|
238
|
+
const entries = docsOnly.readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
|
|
239
|
+
if (!entries) return { tuning: false, keys: [], reason: `could not read the diff ${base}...${branch}` };
|
|
240
|
+
const mb = git.git(['merge-base', base, branch], repo);
|
|
241
|
+
if (!mb.ok) return { tuning: false, keys: [], reason: `no merge base between ${base} and ${branch}` };
|
|
242
|
+
const show = (ref) => { const r = git.git(['show', `${ref}:${DESCRIPTOR}`], repo); return r.ok ? r.stdout : (/does not exist|exists on disk, but not in/.test(r.stderr || '') ? '' : null); };
|
|
243
|
+
return classify({ entries, baseText: show(mb.stdout.trim()), headText: show(branch) });
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Commit `text` as the descriptor on top of `baseSha`, as branch `branch`, WITHOUT touching any
|
|
248
|
+
* working tree or the repo's own index: a scratch index (GIT_INDEX_FILE) holds the tree. The main
|
|
249
|
+
* checkout stays on trunk at rest, which a `git checkout -b` here would break (CONVENTIONS.md §4).
|
|
250
|
+
* The ref is created only if absent (`update-ref <ref> <sha> ""`), so a concurrent run cannot
|
|
251
|
+
* overwrite a branch someone else just made. Returns `{ ok, sha, error }`.
|
|
252
|
+
*/
|
|
253
|
+
function commitOnBranch(repo, { baseSha, text, message, branch }) {
|
|
254
|
+
const { spawnSync } = require('child_process');
|
|
255
|
+
const fs = require('fs');
|
|
256
|
+
const os = require('os');
|
|
257
|
+
const path = require('path');
|
|
258
|
+
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-config-set-'));
|
|
259
|
+
const env = { ...process.env, GIT_INDEX_FILE: path.join(tmp, 'index') };
|
|
260
|
+
const run = (args, input) => {
|
|
261
|
+
const r = spawnSync('git', args, { cwd: repo, env, encoding: 'utf8', ...(input !== undefined ? { input } : {}) });
|
|
262
|
+
return { ok: r.status === 0, out: String(r.stdout || '').trim(), err: String(r.stderr || '').trim() };
|
|
263
|
+
};
|
|
264
|
+
try {
|
|
265
|
+
const rt = run(['read-tree', baseSha]);
|
|
266
|
+
if (!rt.ok) return { ok: false, error: `read-tree ${baseSha}: ${rt.err}` };
|
|
267
|
+
const blob = run(['hash-object', '-w', '--stdin'], text);
|
|
268
|
+
if (!blob.ok) return { ok: false, error: `hash-object: ${blob.err}` };
|
|
269
|
+
const up = run(['update-index', '--add', '--cacheinfo', `100644,${blob.out},${DESCRIPTOR}`]);
|
|
270
|
+
if (!up.ok) return { ok: false, error: `update-index: ${up.err}` };
|
|
271
|
+
const tree = run(['write-tree']);
|
|
272
|
+
if (!tree.ok) return { ok: false, error: `write-tree: ${tree.err}` };
|
|
273
|
+
const commit = run(['commit-tree', tree.out, '-p', baseSha, '-F', '-'], message);
|
|
274
|
+
if (!commit.ok) return { ok: false, error: `commit-tree: ${commit.err}` };
|
|
275
|
+
const ref = run(['update-ref', `refs/heads/${branch}`, commit.out, '']);
|
|
276
|
+
if (!ref.ok) return { ok: false, error: `update-ref refs/heads/${branch}: ${ref.err}` };
|
|
277
|
+
return { ok: true, sha: commit.out };
|
|
278
|
+
} finally {
|
|
279
|
+
fs.rmSync(tmp, { recursive: true, force: true });
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/** The descriptor's exact text at `ref` (no trimming — it becomes a blob), '' when absent, null on a git error. */
|
|
284
|
+
function descriptorAt(repo, ref) {
|
|
285
|
+
const { spawnSync } = require('child_process');
|
|
286
|
+
const r = spawnSync('git', ['show', `${ref}:${DESCRIPTOR}`], { cwd: repo, encoding: 'utf8' });
|
|
287
|
+
if (r.status === 0) return String(r.stdout);
|
|
288
|
+
return /does not exist|exists on disk, but not in/.test(String(r.stderr || '')) ? '' : null;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Does `colab config set <key>` mean THIS repo's descriptor (#561) rather than the machine-local
|
|
293
|
+
* config? Machine keys are camelCase (`claimTTLHours`); descriptor keys are kebab-case. An authority
|
|
294
|
+
* key routes here too, so its refusal names the reason instead of "unknown config key".
|
|
295
|
+
*/
|
|
296
|
+
function isDescriptorKey(arg) {
|
|
297
|
+
const s = String(arg || '');
|
|
298
|
+
const top = s.split('.')[0];
|
|
299
|
+
return !!TUNING[top] || AUTHORITY_KEYS.includes(top) || /[-.]/.test(s);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/** `chore/tune-<key>` — never ending in a digit group, which `colab ship` would read as an issue number. */
|
|
303
|
+
function branchName(keyPath) {
|
|
304
|
+
const slug = [keyPath.top, keyPath.sub].filter(Boolean).join('-').toLowerCase().replace(/[^a-z0-9-]+/g, '-');
|
|
305
|
+
return `chore/tune-${slug}`;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** The commit message: a conventional subject, the evidence in the body (#561). */
|
|
309
|
+
function commitMessage(keyPath, oldValue, value, evidence) {
|
|
310
|
+
const name = [keyPath.top, keyPath.sub].filter(Boolean).join('.');
|
|
311
|
+
return `chore(project): ${name} ${oldValue === null || oldValue === undefined ? '(unset)' : oldValue} → ${value}\n\n` +
|
|
312
|
+
`Tuning-only change to ${DESCRIPTOR}, written by \`colab config set\` (#561).\n\n` +
|
|
313
|
+
`Evidence: ${String(evidence).trim()}\n`;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
module.exports = {
|
|
317
|
+
DESCRIPTOR, TUNING, TUNING_KEYS, AUTHORITY_KEYS,
|
|
318
|
+
parseKeyPath, editText, valueAt, changedLines, ownerOf, classify, branchTuning, commitOnBranch, descriptorAt, isDescriptorKey, branchName, commitMessage,
|
|
319
|
+
};
|
package/tools/lib/disposition.js
CHANGED
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
|
|
56
56
|
const { axisOfRecord } = require('./axis-authority');
|
|
57
57
|
const { parseWakeLine } = require('./wake');
|
|
58
|
+
const { thresholdValue, parseThresholds } = require('./thresholds');
|
|
58
59
|
|
|
59
60
|
// ---------------------------------------------------------------------------------------------
|
|
60
61
|
// Vocabulary
|
|
@@ -115,10 +116,10 @@ const EVIDENCE_FIELDS = Object.freeze(['what', 'command', 'result', 'remains']);
|
|
|
115
116
|
/**
|
|
116
117
|
* PROPOSAL, not a measured threshold (CONVENTIONS.md §5 says so in the same words). A hold whose
|
|
117
118
|
* wake condition has sat this long without movement wants a human to confirm it is still wanted.
|
|
118
|
-
*
|
|
119
|
-
*
|
|
119
|
+
* This is the DEFAULT: a repo may declare its own as `thresholds.hold-stale-days` (#560), read
|
|
120
|
+
* from the `project` fact through tools/lib/thresholds.js. Exported for consumers and tests.
|
|
120
121
|
*/
|
|
121
|
-
const HOLD_STALE_DAYS =
|
|
122
|
+
const HOLD_STALE_DAYS = thresholdValue({}, 'hold-stale-days');
|
|
122
123
|
|
|
123
124
|
/**
|
|
124
125
|
* One marker per line, `proposed=<token>`, the shape `colab:grade verdict=<token>` already uses.
|
|
@@ -320,11 +321,13 @@ function classify(facts) {
|
|
|
320
321
|
'a park with no wake condition is not a hold — it is a silent wontfix, and should be said plainly',
|
|
321
322
|
['no review-by:<date>, no blockedBy edge, and no wake: condition from the closed vocabulary']);
|
|
322
323
|
}
|
|
323
|
-
const
|
|
324
|
+
const declared = parseThresholds(f.project); // #560: the repo's value, else the default 30
|
|
325
|
+
const staleDays = declared.values['hold-stale-days'];
|
|
326
|
+
const stale = Number.isFinite(w.ageDays) && w.ageDays > staleDays && w.movedSince !== true;
|
|
324
327
|
return stale
|
|
325
328
|
? verdict(kind, HUMAN, true,
|
|
326
|
-
`the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${
|
|
327
|
-
[`wake older than ${
|
|
329
|
+
`the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${staleDays} d is ${declared.declared['hold-stale-days'] ? 'this repo\'s thresholds.hold-stale-days' : 'a PROPOSAL, unmeasured'})`,
|
|
330
|
+
[`wake older than ${staleDays} days with no movement`])
|
|
328
331
|
: verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
|
|
329
332
|
}
|
|
330
333
|
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -166,5 +166,5 @@ function directChanges(git, repo, trunk, since) {
|
|
|
166
166
|
|
|
167
167
|
module.exports = {
|
|
168
168
|
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
169
|
-
pathReason, classify, parseRaw, parseBinary, branchChanges, directChanges,
|
|
169
|
+
pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
|
|
170
170
|
};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* engines/<id>.conf — one data file per coding agent the skills can be installed for (#530).
|
|
4
|
+
*
|
|
5
|
+
* The format is deliberately trivial (`key: value` lines, `#` comments, `note:`/`caveat:`
|
|
6
|
+
* repeatable) so install.sh can read it with sed, without node — a skills-only install must not
|
|
7
|
+
* need the CLI's runtime. This module is the JS reader for `install.sh --check`; the two readers
|
|
8
|
+
* must agree, and install-sh.test.js holds them to it. engines/README.md is the format's doc.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
const fs = require('fs');
|
|
12
|
+
const path = require('path');
|
|
13
|
+
|
|
14
|
+
const REPEATABLE = new Set(['note', 'caveat']);
|
|
15
|
+
|
|
16
|
+
/** Parse one conf file's text. First occurrence of a single-valued key wins, as `sed …;q` does. */
|
|
17
|
+
function parseConf(text) {
|
|
18
|
+
const out = { note: [], caveat: [] };
|
|
19
|
+
for (const raw of String(text).split(/\r?\n/)) {
|
|
20
|
+
if (/^\s*#/.test(raw)) continue;
|
|
21
|
+
const m = /^([a-z_]+):[ \t]*(.*)$/.exec(raw);
|
|
22
|
+
if (!m) continue;
|
|
23
|
+
const [, key, value] = m;
|
|
24
|
+
if (REPEATABLE.has(key)) out[key].push(value);
|
|
25
|
+
else if (!(key in out)) out[key] = value;
|
|
26
|
+
}
|
|
27
|
+
return out;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** `~/x` → <home>/x. Same rule as install.sh's expand_home for the values a conf file can hold. */
|
|
31
|
+
function expandHome(p, home) {
|
|
32
|
+
if (p === '~') return home;
|
|
33
|
+
if (p.startsWith('~/')) return path.join(home, p.slice(2));
|
|
34
|
+
return p;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Every engine in <root>/engines, in file order (the order install.sh's prompt numbers them). */
|
|
38
|
+
function listEngines(root) {
|
|
39
|
+
const dir = path.join(root, 'engines');
|
|
40
|
+
let files = [];
|
|
41
|
+
try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.conf')).sort(); } catch (_) { return []; }
|
|
42
|
+
return files.map((f) => ({ id: f.slice(0, -'.conf'.length), ...parseConf(fs.readFileSync(path.join(dir, f), 'utf8')) }));
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Folders given with --skills-dir on an earlier install, one per line in <COLAB_HOME>/skills-dirs. */
|
|
46
|
+
function rememberedDirs(colabHome) {
|
|
47
|
+
let text = '';
|
|
48
|
+
try { text = fs.readFileSync(path.join(colabHome, 'skills-dirs'), 'utf8'); } catch (_) { return []; }
|
|
49
|
+
return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
module.exports = { parseConf, expandHome, listEngines, rememberedDirs };
|
package/tools/lib/git.js
CHANGED
|
@@ -297,21 +297,70 @@ function claimRemote(repo) {
|
|
|
297
297
|
}
|
|
298
298
|
|
|
299
299
|
/**
|
|
300
|
-
* Every branch head on `remoteName
|
|
301
|
-
* local cache)
|
|
302
|
-
* failed ask is NOT "no branches": it returns
|
|
303
|
-
* (fail closed) instead of reading an unreachable
|
|
304
|
-
* `{ ok: true, heads: [{ branch, sha }] }` otherwise, `sha` short
|
|
300
|
+
* Every branch head on `remoteName` — plus every claim ref (`refs/claims/<branch>`, #550) — asked
|
|
301
|
+
* of the remote directly (`ls-remote`, no fetch, no local cache): the claim record another machine
|
|
302
|
+
* can read (#325). Unlike `existingBranchRef`, a failed ask is NOT "no branches": it returns
|
|
303
|
+
* `{ ok: false, stderr }` so the caller can refuse (fail closed) instead of reading an unreachable
|
|
304
|
+
* remote as clear ground. `{ ok: true, heads: [{ branch, sha, claimRef? }] }` otherwise, `sha` short
|
|
305
|
+
* (7) — `parseRemoteHeads`.
|
|
305
306
|
*/
|
|
306
307
|
function remoteHeads(repo, remoteName) {
|
|
307
|
-
const r = git(['ls-remote', '
|
|
308
|
+
const r = git(['ls-remote', remoteName, 'refs/heads/*', `${CLAIM_REF_PREFIX}*`], repo, { timeoutMs: 60_000 });
|
|
308
309
|
if (!r.ok) return { ok: false, stderr: r.stderr || (r.timedOut ? 'ls-remote timed out' : `exit ${r.code}`) };
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
310
|
+
return { ok: true, heads: parseRemoteHeads(r.stdout) };
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* #550 — where `colab worktree new` records a claim at cut: `refs/claims/<branch>`, NOT the branch.
|
|
315
|
+
* A push to `refs/heads/<branch>` fires every CI `push` trigger, and at cut the branch is identical
|
|
316
|
+
* to trunk, so each claim re-ran the full suite on a commit trunk had already tested (measured: ~209
|
|
317
|
+
* of 230 duplicate runs in one org over 3 days, one sha run 8 times). GitHub fires `push` workflows
|
|
318
|
+
* for branches and tags only, so a ref outside both namespaces is a claim record every machine can
|
|
319
|
+
* still `ls-remote`, at zero CI cost (probed live 2026-10-07: a refs/claims push started no run).
|
|
320
|
+
* The branch itself reaches the remote at its first real push (code-wrap), where CI is wanted.
|
|
321
|
+
*/
|
|
322
|
+
const CLAIM_REF_PREFIX = 'refs/claims/';
|
|
323
|
+
function claimRef(branch) { return `${CLAIM_REF_PREFIX}${branch}`; }
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* `ls-remote` output → `[{ branch, sha, claimRef? }]`, short sha. A `refs/claims/<b>` entry reads as
|
|
327
|
+
* branch `<b>` with `claimRef: true`; when the same name is ALSO a real branch, only the branch row is
|
|
328
|
+
* kept (it is the stronger record — it carries commits). Pure, for tests.
|
|
329
|
+
*/
|
|
330
|
+
function parseRemoteHeads(stdout) {
|
|
331
|
+
const heads = new Map();
|
|
332
|
+
const claims = new Map();
|
|
333
|
+
for (const line of String(stdout || '').split('\n')) {
|
|
334
|
+
const m = line.match(/^([0-9a-f]{7,})\s+refs\/(heads|claims)\/(.+)$/);
|
|
335
|
+
if (!m) continue;
|
|
336
|
+
if (m[2] === 'heads') heads.set(m[3], { branch: m[3], sha: m[1].slice(0, 7) });
|
|
337
|
+
else claims.set(m[3], { branch: m[3], sha: m[1].slice(0, 7), claimRef: true });
|
|
313
338
|
}
|
|
314
|
-
|
|
339
|
+
for (const [b, c] of claims) if (!heads.has(b)) heads.set(b, c);
|
|
340
|
+
return [...heads.values()];
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Push the claim record for `branch` (#550): `<branch>:refs/claims/<branch>`, CREATE-ONLY
|
|
345
|
+
* (`--force-with-lease=<ref>:` with an empty expect), so two machines cutting one name still race on
|
|
346
|
+
* a real compare-and-swap and the loser is rejected. No `-u`: there is no remote branch to track yet.
|
|
347
|
+
*/
|
|
348
|
+
function pushClaimRef(repo, remote, branch) {
|
|
349
|
+
const ref = claimRef(branch);
|
|
350
|
+
return git(['push', remote, `--force-with-lease=${ref}:`, `refs/heads/${branch}:${ref}`], repo, { timeoutMs: 120_000 });
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* Delete the claim record for `branch` from `remote` (#550). Idempotent: an absent ref is success
|
|
355
|
+
* (nothing to release), so teardown never fails on a claim that was never pushed or already gone.
|
|
356
|
+
*/
|
|
357
|
+
function deleteClaimRef(repo, remote, branch) {
|
|
358
|
+
const ref = claimRef(branch);
|
|
359
|
+
const ls = git(['ls-remote', remote, ref], repo, { timeoutMs: 60_000 });
|
|
360
|
+
if (!ls.ok) return { ok: false, stderr: ls.stderr || `exit ${ls.code}` };
|
|
361
|
+
if (!String(ls.stdout || '').trim()) return { ok: true, absent: true };
|
|
362
|
+
const r = git(['push', remote, '--delete', ref], repo, { timeoutMs: 120_000 });
|
|
363
|
+
return { ok: r.ok, stderr: r.stderr };
|
|
315
364
|
}
|
|
316
365
|
|
|
317
366
|
/** List worktree paths registered in a repo (porcelain). */
|
|
@@ -911,7 +960,8 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
911
960
|
// does not own) before it computes a verdict, and can only do that if the row says so.
|
|
912
961
|
// workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
|
|
913
962
|
// id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
|
|
914
|
-
'
|
|
963
|
+
// updatedAt is additive (#555): a finished run's completion time, the lone-member wait's anchor.
|
|
964
|
+
'--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
|
|
915
965
|
if (!r.ok) return null;
|
|
916
966
|
let runs;
|
|
917
967
|
try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
@@ -1011,8 +1061,9 @@ function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
|
|
|
1011
1061
|
*/
|
|
1012
1062
|
function ghRunsAtCommit(repo, sha, limit = 100) {
|
|
1013
1063
|
if (!sha) return null;
|
|
1064
|
+
// updatedAt is additive (#566): release finalize places a run around the candidate's cut instant.
|
|
1014
1065
|
const r = gh(['run', 'list', '--commit', sha, '-L', String(limit),
|
|
1015
|
-
'--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
|
|
1066
|
+
'--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,event'], { cwd: repo });
|
|
1016
1067
|
if (!r.ok) return null;
|
|
1017
1068
|
let runs;
|
|
1018
1069
|
try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
@@ -1093,7 +1144,8 @@ function excludedRunSummary(rows) {
|
|
|
1093
1144
|
* #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
|
|
1094
1145
|
* to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
|
|
1095
1146
|
* per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
|
|
1096
|
-
* along as `setAside`, each with its reason.
|
|
1147
|
+
* along as `setAside`, each with its reason. #567: a `workflow_dispatch` run the policy's
|
|
1148
|
+
* `dispatchVerifies` resolver rescues (lost push event) is counted and named in `dispatchCounted`. Opt-in: without `opts.verifying` nothing changes, so
|
|
1097
1149
|
* readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
|
|
1098
1150
|
*/
|
|
1099
1151
|
function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
@@ -1101,16 +1153,19 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1101
1153
|
const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
|
|
1102
1154
|
let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
|
|
1103
1155
|
let setAside = [];
|
|
1156
|
+
let dispatchCounted = [];
|
|
1104
1157
|
if (opts && opts.verifying) {
|
|
1105
1158
|
const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
|
|
1106
1159
|
owned = split.counted;
|
|
1107
1160
|
setAside = split.setAside;
|
|
1161
|
+
dispatchCounted = split.dispatchCounted || [];
|
|
1108
1162
|
}
|
|
1109
1163
|
const { heads, superseded } = newestRunPerWorkflow(owned);
|
|
1110
1164
|
const extra = {
|
|
1111
1165
|
...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
|
|
1112
1166
|
...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
|
|
1113
1167
|
...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
|
|
1168
|
+
...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
|
|
1114
1169
|
};
|
|
1115
1170
|
const r = summarizeRepoOwnedRuns(heads, sha);
|
|
1116
1171
|
return { ...r, ...extra };
|
|
@@ -1329,7 +1384,7 @@ module.exports = {
|
|
|
1329
1384
|
ghCommitCheckRuns, ghCheckRunAnnotations,
|
|
1330
1385
|
run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
|
|
1331
1386
|
detectTrunk, branchExists, branchRefs, existingBranchRef,
|
|
1332
|
-
claimRemote, remoteHeads,
|
|
1387
|
+
claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
|
|
1333
1388
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1334
1389
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1335
1390
|
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|