@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
package/tools/lib/git.js CHANGED
@@ -19,16 +19,32 @@ function run(cmd, args, opts = {}) {
19
19
  const { timeoutMs, ...spawnOpts } = opts;
20
20
  const res = spawnSync(cmd, args, { encoding: 'utf8', ...(timeoutMs ? { timeout: timeoutMs } : {}), ...spawnOpts });
21
21
  const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
22
+ const stderr = (res.stderr || '').trim();
22
23
  return {
23
- ok: res.status === 0 && !timedOut,
24
+ ok: res.status === 0 && !timedOut && !res.error,
24
25
  code: res.status,
25
26
  stdout: (res.stdout || '').trim(),
26
- stderr: timedOut ? `timed out after ${timeoutMs}ms with no output` : (res.stderr || '').trim(),
27
+ // A spawn error (#585) leaves stderr empty: ENOBUFS kills the child once stdout passes
28
+ // `maxBuffer` (1 MiB by default), ENOENT means the binary is missing. An empty detail then
29
+ // reads as "git said nothing" and a caller's remedy guesses at the wrong cause, so the error
30
+ // itself becomes the detail whenever the child wrote none.
31
+ stderr: timedOut ? `timed out after ${timeoutMs}ms with no output` : (stderr || spawnErrorLine(res.error, spawnOpts)),
27
32
  error: res.error || null,
28
33
  timedOut,
29
34
  };
30
35
  }
31
36
 
37
+ /** One line naming a spawn error, or '' for none. ENOBUFS names the buffer it overran (#585). */
38
+ function spawnErrorLine(error, spawnOpts = {}) {
39
+ if (!error) return '';
40
+ const code = error.code || 'error';
41
+ if (code === 'ENOBUFS') {
42
+ const max = spawnOpts.maxBuffer || 1024 * 1024;
43
+ return `ENOBUFS: output passed the ${Math.round(max / 1024)} KiB read buffer and the child was killed`;
44
+ }
45
+ return `${code}: ${error.message || 'spawn failed'}`;
46
+ }
47
+
32
48
  /**
33
49
  * Every `gh` spawn in this module goes through the tracker adapter (#500) — the one place the CLI
34
50
  * talks to GitHub. Lazy require, deliberately: `module.exports = {…}` below REPLACES the exports
@@ -691,6 +707,30 @@ function ghPrForBranch(repo, branch) {
691
707
  } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
692
708
  }
693
709
 
710
+ /**
711
+ * #584: EVERY open pull request whose head is `branch` — not just the first, as ghPrForBranch
712
+ * returns — so `colab ship` can close each CI-trigger PR its squash left behind. `{ prs }` on
713
+ * success (possibly empty), `{ error }` when the read failed; never conflate the two.
714
+ */
715
+ function ghOpenPrsForBranch(repo, branch) {
716
+ const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
717
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
718
+ try {
719
+ const list = JSON.parse(r.stdout || '[]');
720
+ return { prs: Array.isArray(list) ? list : [] };
721
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
722
+ }
723
+
724
+ /** #584: every open pull request in the repo, for `colab doctor --sync`'s landed-PR listing. */
725
+ function ghOpenPrs(repo) {
726
+ const r = gh(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
727
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
728
+ try {
729
+ const list = JSON.parse(r.stdout || '[]');
730
+ return { prs: Array.isArray(list) ? list : [] };
731
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
732
+ }
733
+
694
734
  /**
695
735
  * #367: the forge's visibility for this repo — "PUBLIC" | "PRIVATE" | "INTERNAL" — or null when it
696
736
  * could not be read (no gh, no GitHub remote, offline). Null is "could not read", never "private":
@@ -1042,7 +1082,7 @@ function ghInstalled() {
1042
1082
  function ghRunsForRef(repo, ref, sha, limit = 20) {
1043
1083
  if (!sha) return null;
1044
1084
  const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
1045
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
1085
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,attempt'], { cwd: repo });
1046
1086
  if (!r.ok) return null;
1047
1087
  let runs;
1048
1088
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -1203,6 +1243,12 @@ function isNewerRun(a, b) {
1203
1243
  * sha — otherwise a cancel-in-progress straggler created after the passing run would turn #92's
1204
1244
  * green back into "every run was cancelled". It still counts when it is all a workflow has.
1205
1245
  *
1246
+ * #514: `skipped` is neutral in exactly the same way. A run whose every job was skipped executed
1247
+ * nothing (a same-repo `pull_request` run gated off by a fork-PR `if:`, a `workflow_run` that
1248
+ * declined), so a newer `skipped` row never stands for a workflow that has a run that ran: push
1249
+ * `failure` + newer `skipped` reads red, push `success` + newer `skipped` reads green. A workflow
1250
+ * whose runs are ALL skipped still reads not-green, as before.
1251
+ *
1206
1252
  * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1207
1253
  * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
1208
1254
  * green (#307): it is the head, so the all-finished quantifier sees it.
@@ -1210,6 +1256,9 @@ function isNewerRun(a, b) {
1210
1256
  * Returns the heads in their original order (callers' newest-first `forSha[0]` pick relies on it)
1211
1257
  * plus the rows they superseded.
1212
1258
  */
1259
+ /** Conclusions of a run that executed nothing — never chosen over a run that did (#92, #514). */
1260
+ const NEUTRAL_RUN = new Set(['cancelled', 'skipped']);
1261
+
1213
1262
  function newestRunPerWorkflow(rows) {
1214
1263
  const best = new Map();
1215
1264
  rows.forEach((x, i) => {
@@ -1218,9 +1267,9 @@ function newestRunPerWorkflow(rows) {
1218
1267
  const cur = best.get(name);
1219
1268
  if (cur === undefined) { best.set(name, i); return; }
1220
1269
  const c = rows[cur];
1221
- const xCancelled = x.conclusion === 'cancelled';
1222
- const cCancelled = c.conclusion === 'cancelled';
1223
- if (xCancelled !== cCancelled) { if (cCancelled) best.set(name, i); return; }
1270
+ const xNeutral = NEUTRAL_RUN.has(x.conclusion);
1271
+ const cNeutral = NEUTRAL_RUN.has(c.conclusion);
1272
+ if (xNeutral !== cNeutral) { if (cNeutral) best.set(name, i); return; }
1224
1273
  if (isNewerRun(x, c)) best.set(name, i);
1225
1274
  });
1226
1275
  const heads = []; const superseded = [];
@@ -1382,7 +1431,7 @@ function ghAssignedIssues(repo) {
1382
1431
 
1383
1432
  module.exports = {
1384
1433
  ghCommitCheckRuns, ghCheckRunAnnotations,
1385
- run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1434
+ run, spawnErrorLine, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1386
1435
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1387
1436
  claimRemote, remoteHeads, parseRemoteHeads, CLAIM_REF_PREFIX, claimRef, pushClaimRef, deleteClaimRef,
1388
1437
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
@@ -1392,5 +1441,5 @@ module.exports = {
1392
1441
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1393
1442
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1394
1443
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1395
- ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,
1444
+ ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
1396
1445
  };
@@ -282,6 +282,52 @@ function lineRanges(nums, text = null) {
282
282
  return parts.join(', ');
283
283
  }
284
284
 
285
+ /**
286
+ * Is one CLAUDE.md the thin-shell shape (#588)? The single judgement every enforcement point uses —
287
+ * the audit, the pre-commit hook and the reusable CI workflow all reach it through
288
+ * `instruction-gate.js`, never a second copy.
289
+ *
290
+ * `{ conforming, residue, legacy, message }`. `agents` is the sibling AGENTS.md text, or null.
291
+ * Conforming: no residue (`shellResidue`), or CLAUDE.md byte-identical to its AGENTS.md (a
292
+ * symlinked or copied pair is one file — nothing to move). A missing AGENTS.md on its own is not a
293
+ * failure: a CLAUDE.md that is only tool blocks breaks no rule; the audit still advises on it.
294
+ * `message` (null when conforming) names the fix, because a refusal that does not is a dead end.
295
+ */
296
+ function judgeClaudeMd(claude, agents = null, rel = ENTRY) {
297
+ if (claude === null || claude === undefined) return { conforming: true, residue: [], legacy: false, message: null };
298
+ if (agents !== null && agents !== undefined && agents === claude) return { conforming: true, residue: [], legacy: false, message: null };
299
+ const residue = shellResidue(claude);
300
+ if (!residue.length) return { conforming: true, residue, legacy: false, message: null };
301
+ const legacy = !isThinShell(claude);
302
+ const shape = legacy ? 'and it has no @AGENTS.md import (a legacy prose-only file)' : 'next to its @AGENTS.md import';
303
+ const sibling = path.posix.join(path.posix.dirname(rel), AUTHORED).replace(/^\.\//, '');
304
+ return {
305
+ conforming: false,
306
+ residue,
307
+ legacy,
308
+ message: `${rel} line${residue.length === 1 ? '' : 's'} ${lineRanges(residue, claude)} carry repo prose ${shape} — move them to ${sibling} ` +
309
+ `and keep ${rel} to the \`@AGENTS.md\` import, blank lines and tool blocks such as the Conventions block`,
310
+ };
311
+ }
312
+
313
+ /**
314
+ * The ratchet (#588), pure. `changed` = repo-relative paths that differ between the base and the
315
+ * head; `head` / `base` = `[{ path, conforming }]` for every CLAUDE.md at each side (`base` null
316
+ * when there is no base to compare against). Fails iff some head CLAUDE.md does not conform AND
317
+ * (a) a CLAUDE.md or AGENTS.md changed — the branch touched the rule's files, so it owns them; or
318
+ * (b) every CLAUDE.md conformed at the base — the repo had migrated, and this would regress it.
319
+ * An unmigrated repo whose branch leaves both files alone stays green, so adding the check never
320
+ * turns a trunk red on its own. `{ fail, reason, bad }`; `reason` is 'touched' | 'regressed' | null.
321
+ */
322
+ const RULE_FILE_RE = /(^|\/)(CLAUDE|AGENTS)\.md$/;
323
+ function ratchetVerdict({ changed = [], head = [], base = null }) {
324
+ const bad = head.filter((f) => !f.conforming);
325
+ if (!bad.length) return { fail: false, reason: null, bad };
326
+ if (changed.some((p) => RULE_FILE_RE.test(p))) return { fail: true, reason: 'touched', bad };
327
+ if (base && base.every((f) => f.conforming)) return { fail: true, reason: 'regressed', bad };
328
+ return { fail: false, reason: null, bad };
329
+ }
330
+
285
331
  module.exports = {
286
332
  stripCode,
287
333
  IMPORT_MAX_DEPTH,
@@ -300,4 +346,7 @@ module.exports = {
300
346
  conventionsBlock,
301
347
  shellResidue,
302
348
  lineRanges,
349
+ judgeClaudeMd,
350
+ RULE_FILE_RE,
351
+ ratchetVerdict,
303
352
  };
@@ -0,0 +1,150 @@
1
+ 'use strict';
2
+ /**
3
+ * The instruction-file gate (#588) — the ONE git-aware entry point the three enforcement points
4
+ * share: the audit (`checkInstructionFileShape`, warn → fail), the pre-commit hook
5
+ * (`colab instruction-files --staged`) and the reusable CI workflow
6
+ * (`colab instruction-files --base <ref>`). The shape judgement itself is
7
+ * `instruction-file.js` `judgeClaudeMd`, and the ratchet is its `ratchetVerdict`; this module only
8
+ * reads trees out of git and feeds them in. Nothing else re-implements either.
9
+ *
10
+ * Sides a tree can be read from:
11
+ * { ref: '<rev>' } a commit (CI's head, the merge base)
12
+ * 'index' the staged content (the pre-commit hook)
13
+ * 'worktree' the files on disk, tracked paths only (the audit, which reads the working tree)
14
+ *
15
+ * "Every tracked CLAUDE.md" means every path whose basename is `CLAUDE.md`, at any depth, judged
16
+ * against the `AGENTS.md` beside it. A symlinked CLAUDE.md is read through its link target, so the
17
+ * common `CLAUDE.md -> AGENTS.md` pair reads as one file (conforming), as the audit already treats
18
+ * a byte-identical pair.
19
+ */
20
+
21
+ const fs = require('fs');
22
+ const path = require('path');
23
+ const { execFileSync } = require('child_process');
24
+ const inst = require('./instruction-file.js');
25
+
26
+ const CLAUDE_RE = /(^|\/)CLAUDE\.md$/;
27
+
28
+ function git(cwd, args) {
29
+ try {
30
+ return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
31
+ } catch (_) {
32
+ return null;
33
+ }
34
+ }
35
+
36
+ /** `[{ path, mode }]` for every CLAUDE.md on `side`; null when the side cannot be read. */
37
+ function listClaude(cwd, side) {
38
+ let out;
39
+ if (side === 'index' || side === 'worktree') out = git(cwd, ['ls-files', '-s', '-z']);
40
+ else out = git(cwd, ['ls-tree', '-r', '-z', '--full-tree', side.ref]);
41
+ if (out === null) return null;
42
+ const found = [];
43
+ for (const rec of out.split('\0')) {
44
+ if (!rec) continue;
45
+ const tab = rec.indexOf('\t');
46
+ const p = rec.slice(tab + 1);
47
+ if (!CLAUDE_RE.test(p)) continue;
48
+ found.push({ path: p, mode: rec.split(' ')[0] });
49
+ }
50
+ return found;
51
+ }
52
+
53
+ /** `readFile(rel) -> string|null` on `side`. */
54
+ function reader(cwd, side) {
55
+ if (side === 'worktree') {
56
+ return (rel) => {
57
+ try { return fs.readFileSync(path.join(cwd, rel), 'utf8'); } catch (_) { return null; }
58
+ };
59
+ }
60
+ const prefix = side === 'index' ? ':' : `${side.ref}:`;
61
+ return (rel) => git(cwd, ['show', `${prefix}${rel}`]);
62
+ }
63
+
64
+ /**
65
+ * `[{ path, conforming, message }]` — every CLAUDE.md on `side`, judged. null when the side
66
+ * cannot be read (an unknown ref). Symlinks (mode 120000) are followed one hop, in-repo only.
67
+ */
68
+ function judgeSide(cwd, side) {
69
+ const list = listClaude(cwd, side);
70
+ if (list === null) return null;
71
+ const read = reader(cwd, side);
72
+ return list.map(({ path: rel, mode }) => {
73
+ let text;
74
+ if (mode === '120000' && side !== 'worktree') {
75
+ const target = (read(rel) || '').trim();
76
+ const r = inst.resolveImport(rel, target);
77
+ text = r.path ? read(r.path) : null;
78
+ } else {
79
+ text = read(rel);
80
+ }
81
+ const agentsRel = path.posix.join(path.posix.dirname(rel), inst.AUTHORED).replace(/^\.\//, '');
82
+ const j = inst.judgeClaudeMd(text, read(agentsRel), rel);
83
+ return { path: rel, conforming: j.conforming, message: j.message };
84
+ });
85
+ }
86
+
87
+ /**
88
+ * Run the gate. Options:
89
+ * cwd repo (default process.cwd())
90
+ * staged true → judge the index against HEAD (the pre-commit hook)
91
+ * base a rev → judge `head` against merge-base(base, HEAD) (CI, the audit)
92
+ * head 'worktree' to judge the working tree instead of HEAD (the audit); default HEAD
93
+ * With neither `staged` nor `base`, every CLAUDE.md at the head is judged with no ratchet:
94
+ * any non-conforming file fails (`reason: 'strict'`).
95
+ *
96
+ * Returns `{ ok, error?, fail, reason, mode, base, files, bad, changed }`. `ok: false` means the
97
+ * gate could not answer (not a repo, base unknown, merge base not reachable in a shallow clone)
98
+ * — callers must refuse rather than read that as a pass.
99
+ */
100
+ function gate({ cwd = process.cwd(), staged = false, base = null, head = null } = {}) {
101
+ if (git(cwd, ['rev-parse', '--git-dir']) === null) return { ok: false, error: `${cwd} is not a git repo` };
102
+ const hasHead = git(cwd, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']) !== null;
103
+
104
+ if (staged) {
105
+ const files = judgeSide(cwd, 'index');
106
+ const changed = (git(cwd, ['diff', '--cached', '--name-only', '-z']) || '').split('\0').filter(Boolean);
107
+ const baseFiles = hasHead ? judgeSide(cwd, { ref: 'HEAD' }) : [];
108
+ const v = inst.ratchetVerdict({ changed, head: files, base: baseFiles });
109
+ return { ok: true, mode: 'staged', base: hasHead ? 'HEAD' : null, files, changed, ...v };
110
+ }
111
+
112
+ const headSide = head === 'worktree' ? 'worktree' : { ref: head || 'HEAD' };
113
+ if (headSide !== 'worktree' && !hasHead && !head) return { ok: false, error: 'HEAD has no commit yet' };
114
+ const files = judgeSide(cwd, headSide);
115
+ if (files === null) return { ok: false, error: `cannot read ${head || 'HEAD'}` };
116
+
117
+ if (!base) {
118
+ const bad = files.filter((f) => !f.conforming);
119
+ return { ok: true, mode: 'strict', base: null, files, changed: [], fail: bad.length > 0, reason: bad.length ? 'strict' : null, bad };
120
+ }
121
+
122
+ if (git(cwd, ['rev-parse', '--verify', '-q', `${base}^{commit}`]) === null) {
123
+ return { ok: false, error: `base ${base} is not a commit here — fetch it (a CI checkout needs fetch-depth: 0)` };
124
+ }
125
+ const headRev = headSide === 'worktree' ? 'HEAD' : headSide.ref;
126
+ const mb = (git(cwd, ['merge-base', base, headRev]) || '').trim();
127
+ if (!mb) return { ok: false, error: `no merge base between ${base} and ${headRev} — a shallow clone? (fetch-depth: 0)` };
128
+ const diffArgs = headSide === 'worktree' ? ['diff', '--name-only', '-z', mb] : ['diff', '--name-only', '-z', mb, headRev];
129
+ const changed = (git(cwd, diffArgs) || '').split('\0').filter(Boolean);
130
+ const baseFiles = judgeSide(cwd, { ref: mb });
131
+ const v = inst.ratchetVerdict({ changed, head: files, base: baseFiles });
132
+ return { ok: true, mode: 'ratchet', base: mb, files, changed, ...v };
133
+ }
134
+
135
+ /** One human line per verdict, naming the fix. */
136
+ function describe(r) {
137
+ if (!r.ok) return [`cannot judge: ${r.error}`];
138
+ if (!r.bad.length) return [`instruction files conform (${r.files.length} CLAUDE.md judged)`];
139
+ const why = {
140
+ touched: 'this change touches CLAUDE.md/AGENTS.md, so every CLAUDE.md must conform',
141
+ regressed: 'every CLAUDE.md conformed at the merge base, so this would regress the repo',
142
+ strict: 'judged with no base (no ratchet)',
143
+ }[r.reason];
144
+ const lines = r.bad.map((f) => f.message);
145
+ if (r.fail) lines.push(`(${why} — CONVENTIONS.md §9 step 5, #588)`);
146
+ else lines.push('(not failing: unmigrated repo and this change leaves CLAUDE.md/AGENTS.md alone — the ratchet, #588)');
147
+ return lines;
148
+ }
149
+
150
+ module.exports = { CLAUDE_RE, listClaude, reader, judgeSide, gate, describe };
@@ -0,0 +1,58 @@
1
+ 'use strict';
2
+ /**
3
+ * #584: a pull request opened only to obtain branch CI stays open forever once `colab ship`
4
+ * squash-lands its branch — the squash is a NEW commit, so the forge never sees the PR's head land,
5
+ * and nothing else closes it. Measured 2026-10-10: five such PRs open on two repos, all landed, the
6
+ * oldest 15 days old, each reading as unmerged work waiting for review.
7
+ *
8
+ * Pure rules only — tools/colab owns the gh calls. Two rules:
9
+ *
10
+ * 1. Close a PR only when its head commit LANDED: the PR head is the landed branch tip, or an
11
+ * ancestor of it. A PR head carrying commits the ship did NOT include (pushed to the remote
12
+ * branch after the local tip was cut, or from another machine) is KEPT, with a warning — closing
13
+ * it would hide work that is not on trunk.
14
+ * 2. Best-effort. A failed list or close is a warning, never a failed ship: the merge already landed
15
+ * and is pushed, so a non-zero exit here would read as "ship failed" and invite a re-merge.
16
+ */
17
+
18
+ /** The comment a closed PR carries — the same shape as #350's close: where it landed, and why. */
19
+ function landedPrComment({ target, sha, issues }) {
20
+ const nums = (issues || []).map((n) => `#${n}`).join(' ');
21
+ return `Landed on \`${target}\` as ${sha} by \`colab ship\`${nums ? ` (${nums})` : ''}. ` +
22
+ 'The branch was squash-merged, which the forge cannot see as a merge of this PR, so ship closes it (#584).';
23
+ }
24
+
25
+ /**
26
+ * Decide and act on every open PR whose head is the landed branch.
27
+ *
28
+ * prs — the open PRs listed for the branch, as git.ghOpenPrsForBranch returns them:
29
+ * { prs: [{ number, headRefOid, url }] } or { error }
30
+ * headLanded — (oid) => true when that commit is in what landed (tip or ancestor); false otherwise
31
+ * close — (number, comment) => { ok, stderr }
32
+ * comment — the closing comment (landedPrComment)
33
+ * skip — PR numbers already handled by another path (#350's approved review PR)
34
+ *
35
+ * Returns { closed: [n], kept: [{ number, reason }], failed: [{ number, error }], listError }.
36
+ */
37
+ function closeLandedPrs({ prs, headLanded, close, comment, skip = [] }) {
38
+ const out = { closed: [], kept: [], failed: [], listError: null };
39
+ if (!prs || prs.error || !Array.isArray(prs.prs)) { out.listError = (prs && prs.error) || 'could not list open PRs'; return out; }
40
+ const skipSet = new Set(skip.map(Number));
41
+ for (const pr of prs.prs) {
42
+ const number = Number(pr.number);
43
+ if (!Number.isFinite(number) || skipSet.has(number)) continue;
44
+ let landed = false;
45
+ try { landed = !!(pr.headRefOid && headLanded(pr.headRefOid)); } catch (_) { landed = false; }
46
+ if (!landed) {
47
+ out.kept.push({ number, reason: `its head ${String(pr.headRefOid || '?').slice(0, 12)} is not in what landed` });
48
+ continue;
49
+ }
50
+ let r;
51
+ try { r = close(number, comment); } catch (e) { r = { ok: false, stderr: e.message }; }
52
+ if (r && r.ok) out.closed.push(number);
53
+ else out.failed.push({ number, error: ((r && r.stderr) || 'gh pr close failed').split('\n')[0] });
54
+ }
55
+ return out;
56
+ }
57
+
58
+ module.exports = { landedPrComment, closeLandedPrs };
@@ -241,7 +241,7 @@ function evaluateShipSet(issues, records, branch, labelName, ctx) {
241
241
  reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
242
242
  continue;
243
243
  }
244
- const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, contentId: ctx.contentId, issueNum: n, labelName, policy });
244
+ const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, contentId: ctx.contentId, issueNum: n, labelName, policy, policyReason: ctx.policyReason || null });
245
245
  if (!r.ok) {
246
246
  const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
247
247
  missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
@@ -290,13 +290,28 @@ function labelNamesOf(record) {
290
290
  const SHIP_CONDITION_TAG = Object.freeze({ policy: 'P policy', marker: 'M record', head: 'HEAD', roundtrip: 'R round-trip' });
291
291
 
292
292
  /**
293
- * The CI round-trip job (#399's `templates/ci-laravel.yml`) is found by NAME PREFIX: its matrix
294
- * legs are named `Migration round-trip (<engine>)`. Nothing in project.yml names it today (#401
293
+ * The CI round-trip job (#399's `templates/ci-laravel.yml`, and #494's opt-in block in
294
+ * `templates/ci-node.yml`) is found by NAME PREFIX: its matrix legs are named
295
+ * `Migration round-trip (<engine>)`. Nothing in project.yml names it today (#401
295
296
  * risk 1) — a repo that renames the job, or has no such job, cannot pass R, and ships a migration
296
297
  * on a human grant exactly as before. STABLE: renaming the template's job breaks this reader.
297
298
  */
298
299
  const ROUNDTRIP_JOB_PREFIX = 'Migration round-trip';
299
300
 
301
+ /**
302
+ * #494 — which workflows carry a live job whose `name:` starts with ROUNDTRIP_JOB_PREFIX. A
303
+ * commented line never counts (ci-node ships its job as a commented opt-in block). `readFile(rel)`
304
+ * returns the text or null; `workflows` are file names under .github/workflows. Text-level on
305
+ * purpose — the same reading R does by job name at ship time, without a YAML parser.
306
+ */
307
+ function roundtripJobWorkflows({ readFile, workflows }) {
308
+ const re = new RegExp(`^\\s+name:\\s*['"]?${ROUNDTRIP_JOB_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
309
+ return (workflows || []).filter((wf) => {
310
+ const text = readFile(`.github/workflows/${wf}`);
311
+ return typeof text === 'string' && re.test(text);
312
+ });
313
+ }
314
+
300
315
  /**
301
316
  * R — did the live CI round-trip pass on the shipped HEAD? Pure: `jobs` is every job of every run
302
317
  * at that sha (git.ghRunJobs rows, flattened), or null when any read failed. Passes only when:
@@ -689,7 +704,8 @@ function parseGrantPolicy(doc) {
689
704
  * The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
690
705
  * (#401) calls it and adds R. `ctx` = { branch, headSha, contentId, issueNum, labelName, policy } where
691
706
  * `contentId` (#508) is migrationContentId at `headSha` (grantHeadBinding), and
692
- * `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
707
+ * `policy` is the resolved policy (repo key > owner-level > human, #596) and `policyReason` its
708
+ * source sentence when the owner level is in play. Checks, cheapest/most-fundamental first, each with its
693
709
  * own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
694
710
  * branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
695
711
  * The CI round-trip is checked here only as RECORDED; re-verifying it against live CI for `head`
@@ -704,7 +720,13 @@ function evaluateReviewerGrant(record, ctx) {
704
720
  if (record.state !== 'OPEN') return no(`#${issue} is ${record.state || 'not open'} — a grant expires when its issue closes`);
705
721
  const labelNames = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
706
722
  if (!labelNames.includes(c.labelName)) return no(`#${issue} does not carry the \`${c.labelName}\` label`);
707
- if (c.policy !== 'reviewer') return no(`this repo's migration-grant policy is "${c.policy || 'human'}" — a reviewer grant is honoured only under migration-grant: reviewer`);
723
+ // #596: `policyReason` is set only where the owner level is in play (an owner value, a repo opt-out,
724
+ // an unreadable owner record) — it names the source. Otherwise the text is the pre-#596 one.
725
+ if (c.policy !== 'reviewer') {
726
+ return no(c.policyReason
727
+ ? `${c.policyReason} — a reviewer grant is honoured only where the policy resolves to reviewer`
728
+ : `this repo's migration-grant policy is "${c.policy || 'human'}" — a reviewer grant is honoured only under migration-grant: reviewer`);
729
+ }
708
730
  checks.policy = true;
709
731
  const reviewer = liveGrantRecords(record.comments).filter((g) => g.role !== 'human');
710
732
  if (reviewer.length === 0) return no(`#${issue} has no live reviewer grant (revoked, or never posted)`);
@@ -738,6 +760,8 @@ module.exports = {
738
760
  GRANT_POLICIES, parseGrantPolicy,
739
761
  // #401 — ship honours a reviewer grant
740
762
  ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
763
+ // #494 — the audit's check that R is reachable at all
764
+ roundtripJobWorkflows,
741
765
  // #457 — the mint-time checks
742
766
  REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
743
767
  };
@@ -0,0 +1,133 @@
1
+ 'use strict';
2
+ /**
3
+ * Owner-level grant policy (#596): one `migration-grant` value set once, by a human, for every repo
4
+ * an owner runs. Precedence: the repo's explicit `migration-grant:` > the owner value > `human`.
5
+ *
6
+ * WHERE IT LIVES. Not in a file. A committed file (in the repo, or in the owner's `.github` repo)
7
+ * is edited by any session that can commit, and nothing in it names who set it. So the value is a
8
+ * tracker record, the same class as a migration grant itself:
9
+ * - repo = `<owner>/.github` (GitHub's own owner-wide-defaults repo; `<owner>` is the GitHub
10
+ * owner of the repo being judged, resolved by `gh` from its remote);
11
+ * - issue = the lowest-numbered OPEN issue there labelled `colab-owner-policy`;
12
+ * - value = marker comments `<!-- colab:owner-policy key=<key> value=<value> -->`. The LATEST
13
+ * marker for a key whose author counts as human wins. `value=unset` withdraws it.
14
+ *
15
+ * HOW A READER PROVES A HUMAN SET IT. The same two halves a human grant has, no weaker and no
16
+ * stronger: the write is refused without `COLAB_HUMAN=1` (tools/colab `owner-policy set`), and
17
+ * the read counts a marker only when its author is the `.github` repo's OWNER or a MEMBER and, where
18
+ * the repo being judged declares `trust-humans:` (read from its trunk / merge target, never from a
19
+ * branch), only when that login is listed (trust-humans.js authorIsHuman). A marker from anyone
20
+ * else is ignored and reported, never honoured. COLLABORATOR is deliberately not enough here: an
21
+ * outside collaborator on the owner's defaults repo does not answer for every repo the owner runs.
22
+ *
23
+ * PURE: parsed records in, verdicts out. No git, no network — tools/colab does the I/O.
24
+ */
25
+ const trustHumans = require('./trust-humans');
26
+
27
+ const LABEL = 'colab-owner-policy';
28
+ const RECORD_REPO = '.github';
29
+ const ISSUE_TITLE = 'colab owner policy';
30
+ /** Keys the owner record may carry. `ci-grant` could take the same shape later (#596, out of scope). */
31
+ const KEYS = ['migration-grant'];
32
+ const VALUES = { 'migration-grant': ['human', 'reviewer'] };
33
+ const UNSET = 'unset';
34
+ /** Owner-level record authors: the owner account, or an org member. Not COLLABORATOR — see above. */
35
+ const OWNER_ASSOCIATIONS = new Set(['OWNER', 'MEMBER']);
36
+
37
+ const MARK_RE = /<!--\s*colab:owner-policy\s+key=([a-z][a-z-]*)\s+value=([a-z]+)\s*-->/;
38
+
39
+ function isValidValue(key, value) {
40
+ return KEYS.includes(key) && (value === UNSET || (VALUES[key] || []).includes(value));
41
+ }
42
+
43
+ /** The comment body `owner-policy set` posts. Marker first, so a reader never parses prose. */
44
+ function markerBody(key, value, host, iso) {
45
+ if (!isValidValue(key, value)) throw new Error(`owner-policy: ${key}=${value} is not settable`);
46
+ const what = value === UNSET
47
+ ? `withdraws the owner-level \`${key}\` value — repos without their own key fall back to the default`
48
+ : `sets the owner-level \`${key}\` to \`${value}\` for every repo this owner runs that does not declare its own \`${key}:\``;
49
+ return `<!-- colab:owner-policy key=${key} value=${value} -->\n` +
50
+ `**colab owner policy** — ${what}. Host \`${host}\` · ${iso}. A repo's own \`${key}:\` still wins; ` +
51
+ `\`${key}: human\` in a repo's project.yml opts that repo out.`;
52
+ }
53
+
54
+ /**
55
+ * Normalise one comment from either shape colab reads: REST (`user.login`, `author_association`,
56
+ * `created_at`) or gh's GraphQL JSON (`author.login`, `authorAssociation`, `createdAt`).
57
+ */
58
+ function normComment(c) {
59
+ const o = c || {};
60
+ return {
61
+ login: (o.user && o.user.login) || (o.author && o.author.login) || '',
62
+ authorAssociation: o.author_association || o.authorAssociation || '',
63
+ at: o.created_at || o.createdAt || '',
64
+ body: String(o.body || ''),
65
+ };
66
+ }
67
+
68
+ /**
69
+ * The owner value for `key` from the record issue's comments. `trust` = the JUDGED repo's
70
+ * parseTrustHumans(...) at its trunk/target (or null = undeclared).
71
+ * Returns { set, value, by, at, ignored: [{ login, at, value, reason }] } — `set` false when no
72
+ * trusted marker exists or the latest trusted one is `unset`.
73
+ */
74
+ function ownerValue(comments, key, trust) {
75
+ const list = (Array.isArray(comments) ? comments : []).map(normComment)
76
+ .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
77
+ let cur = null;
78
+ const ignored = [];
79
+ for (const c of list) {
80
+ const m = c.body.trim().match(MARK_RE);
81
+ if (!m || m[1] !== key) continue;
82
+ const value = m[2];
83
+ if (!isValidValue(key, value)) { ignored.push({ login: c.login, at: c.at, value, reason: `"${value}" is not a ${key} value` }); continue; }
84
+ if (!OWNER_ASSOCIATIONS.has(c.authorAssociation)) {
85
+ ignored.push({ login: c.login, at: c.at, value, reason: `${c.login || '(unknown)'} (${c.authorAssociation || 'unknown association'}) is not the owner or an org member` });
86
+ continue;
87
+ }
88
+ const h = trustHumans.authorIsHuman(c, trust);
89
+ if (!h.ok) { ignored.push({ login: c.login, at: c.at, value, reason: h.reason }); continue; }
90
+ cur = { value, by: c.login, at: c.at };
91
+ }
92
+ if (!cur || cur.value === UNSET) return { set: false, value: null, by: cur ? cur.by : null, at: cur ? cur.at : null, ignored };
93
+ return { set: true, value: cur.value, by: cur.by, at: cur.at, ignored };
94
+ }
95
+
96
+ /**
97
+ * Three-level precedence for `migration-grant`. `repoPol` = migration-grant.js parseGrantPolicy(doc);
98
+ * `owner` = { read: 'ok'|'none'|'unread', owner, set, value, by, at, why } from tools/colab's reader,
99
+ * or null when the owner record was not consulted (the repo declares its own key, so it is not needed).
100
+ * Returns repoPol's shape plus { source: 'repo'|'owner'|'default', optedOut, owner, ownerBy, ownerAt,
101
+ * ownerNote }. `reason` is a sentence naming the source — the caller prints it on refusal.
102
+ */
103
+ function resolveGrantPolicy(repoPol, owner) {
104
+ const o = owner || null;
105
+ const ownerSet = !!(o && o.read === 'ok' && o.set);
106
+ const ownerBits = ownerSet ? { owner: o.owner || null, ownerBy: o.by || null, ownerAt: o.at || null } : { owner: null, ownerBy: null, ownerAt: null };
107
+ if (repoPol.declared) {
108
+ const optedOut = repoPol.valid && repoPol.policy === 'human' && ownerSet && o.value === 'reviewer';
109
+ return { ...repoPol, source: 'repo', optedOut, ...ownerBits, ownerNote: '',
110
+ reason: optedOut
111
+ ? `this repo opted out: project.yml declares migration-grant: human, which wins over the owner-level reviewer value (set by ${o.by} at ${o.at})`
112
+ : repoPol.reason };
113
+ }
114
+ if (ownerSet) {
115
+ return { policy: o.value, declared: false, valid: true, source: 'owner', optedOut: false, ...ownerBits, ownerNote: '',
116
+ reason: `owner-level migration-grant: ${o.value} (set on ${o.owner || 'the owner'}/${RECORD_REPO} by ${o.by} at ${o.at}; this repo declares no key of its own)` };
117
+ }
118
+ const ownerNote = o && o.read === 'unread' ? `the owner-level record could not be read (${o.why || 'unknown error'}) — read as unset` : '';
119
+ return { ...repoPol, source: 'default', optedOut: false, ...ownerBits, ownerNote,
120
+ reason: ownerNote ? `${repoPol.reason}; ${ownerNote}` : repoPol.reason };
121
+ }
122
+
123
+ /** One-line source label for a printed policy: `repo`, `owner (<by> at <at>)`, or `default`. */
124
+ function sourceLabel(res) {
125
+ if (!res) return 'default';
126
+ if (res.source === 'owner') return `owner (${res.ownerBy || '?'} at ${res.ownerAt || '?'})`;
127
+ return res.source;
128
+ }
129
+
130
+ module.exports = {
131
+ LABEL, RECORD_REPO, ISSUE_TITLE, KEYS, VALUES, UNSET, OWNER_ASSOCIATIONS, MARK_RE,
132
+ isValidValue, markerBody, normComment, ownerValue, resolveGrantPolicy, sourceLabel,
133
+ };