@futurelastic/colab-handbook 1.12.0 → 1.13.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.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -479,6 +479,7 @@ const WORKFLOW_FINGERPRINTS = [
479
479
  { marker: 'Release (auto) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'release-auto' },
480
480
  { marker: 'Deploy (SSH/rsync to shared hosting) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-xserver' },
481
481
  { marker: 'Branch name — TEMPLATE. Copy me into your repo', kind: 'text', template: 'branch-name' },
482
+ { marker: 'Deploy (container, platform adapter) — TEMPLATE. Copy me into your repo', kind: 'text', template: 'deploy-container' },
482
483
  // The header convention itself, unattributed: this catches a copy of any template ADDED LATER
483
484
  // without anyone remembering to extend this list — provided the new template keeps the house
484
485
  // header. A template that omits it is invisible here, which is worth knowing when writing one.
@@ -503,6 +504,12 @@ const WORKFLOW_FINGERPRINTS = [
503
504
  // overwrite. Verified against all three before being added here.
504
505
  { marker: 'Resolve deploy toolchain', kind: 'step', template: 'deploy-xserver' },
505
506
  { marker: 'Verify the deployed site answers', kind: 'step', template: 'deploy-xserver' },
507
+ // deploy-container (#452, split into publish + deploy jobs by #460): its two coined steps.
508
+ // "Resolve the tag to deploy" is deliberately not a marker — a phrase a hand-written deploy
509
+ // workflow could carry, and an over-eager marker invites an overwrite. A copy taken before #460
510
+ // (one step, "Build once, run exactly this tag, verify …") still matches on the header text marker.
511
+ { marker: 'Build once and push (deploy-container-run --publish-only)', kind: 'step', template: 'deploy-container' },
512
+ { marker: 'Run exactly this tag, verify (deploy-container-run --deploy-only)', kind: 'step', template: 'deploy-container' },
506
513
  // branch-name (#348): its one step.
507
514
  { marker: 'Check branch name (CONVENTIONS §4)', kind: 'step', template: 'branch-name' },
508
515
  // Shared by all three ci-* templates: proves derivation, cannot say from which. Note the exact
@@ -0,0 +1,195 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/tracker-fake.js — an in-memory implementation of the tracker contract (#501).
4
+ *
5
+ * It exists for two readers:
6
+ * - tools/lib/tracker-contract.test.js runs every scenario in tools/lib/tracker-scenarios.json
7
+ * against it, next to the GitHub adapter. When both pass the same scenarios, the scenarios
8
+ * describe the contract rather than one implementation's habits.
9
+ * - a consumer of this package that wants a tracker in a test without a network.
10
+ *
11
+ * `create(repoAbs, given)` seeds it from a scenario's `given` block (the shape is documented in
12
+ * tracker-scenarios.json's `given` key). Semantics follow tools/lib/tracker.js: synchronous,
13
+ * bound to one repo, never throws on an "environment" failure — `given.offline: true` makes every
14
+ * read come back as "could not read" (null, or `data: null`) and every write as `ok: false`.
15
+ *
16
+ * Fidelity points that a scenario pins, because GitHub behaves this way and a caller relies on it:
17
+ * - issues and pull requests share one number sequence;
18
+ * - a closed issue carries `stateReason` COMPLETED or NOT_PLANNED;
19
+ * - the claimer of an issue is the actor of the LATEST `labeled in-progress` event (tools/lib/git.js
20
+ * ghClaimHolder), and release unassigns the caller plus that claimer unless `selfOnly`;
21
+ * - list reads come back newest first.
22
+ */
23
+
24
+ function result(ok, extra = {}) {
25
+ return { ok, code: ok ? 0 : 1, stdout: '', stderr: ok ? '' : 'tracker unavailable (fake: offline)',
26
+ error: null, timedOut: false, ...extra };
27
+ }
28
+
29
+ function fail(stderr) {
30
+ return { ok: false, code: 1, stdout: '', stderr, error: null, timedOut: false };
31
+ }
32
+
33
+ const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
34
+ const pick = (obj, fields) => Object.fromEntries(fields.filter((f) => f in obj).map((f) => [f, obj[f]]));
35
+
36
+ function create(repoAbs, given = {}) {
37
+ const login = given.login === undefined ? 'fake-user' : given.login;
38
+ const offline = Boolean(given.offline);
39
+ const labels = clone(given.labels || []);
40
+ const issues = new Map();
41
+ const prs = new Map();
42
+ const runs = clone(given.runs || []);
43
+ const releases = new Map((given.releases || []).map((r) => [r.tag, clone(r)]));
44
+ const base = `https://tracker.invalid/${String(repoAbs).replace(/^\/+/, '')}`;
45
+
46
+ for (const i of given.issues || []) {
47
+ issues.set(i.number, {
48
+ number: i.number, title: i.title || '', body: i.body || '', state: i.state || 'OPEN',
49
+ stateReason: i.stateReason || (i.state === 'CLOSED' ? 'COMPLETED' : ''),
50
+ createdAt: i.createdAt || null, closedAt: i.closedAt || null,
51
+ labels: clone(i.labels || []), assignees: clone(i.assignees || []),
52
+ comments: (i.comments || []).map((c) => ({ author: c.author, body: c.body })),
53
+ events: clone(i.events || []),
54
+ });
55
+ }
56
+ for (const p of given.prs || []) {
57
+ prs.set(p.number, { reviews: [], body: '', state: 'OPEN', headRefOid: null, mergedAt: null, ...clone(p) });
58
+ }
59
+ const nextNumber = () => Math.max(0, ...issues.keys(), ...prs.keys()) + 1;
60
+
61
+ /** The issue as `gh issue view --json` shapes it: label/assignee/comment objects, not strings. */
62
+ function issueShape(i) {
63
+ return {
64
+ number: i.number, title: i.title, body: i.body, state: i.state, stateReason: i.stateReason,
65
+ createdAt: i.createdAt, closedAt: i.closedAt, url: `${base}/issues/${i.number}`,
66
+ labels: i.labels.map((name) => ({ name })),
67
+ assignees: i.assignees.map((l) => ({ login: l })),
68
+ comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body })),
69
+ };
70
+ }
71
+ function prShape(p) {
72
+ return {
73
+ number: p.number, title: p.title, body: p.body, state: p.state, headRefName: p.head,
74
+ baseRefName: p.base, headRefOid: p.headRefOid, mergedAt: p.mergedAt, reviews: clone(p.reviews),
75
+ author: { login: p.author }, url: `${base}/pull/${p.number}`,
76
+ };
77
+ }
78
+ function claimHolder(num) {
79
+ const i = issues.get(num);
80
+ if (offline || !i) return { assignees: null, claimer: null };
81
+ const actors = i.events.filter((e) => e.event === 'labeled' && e.label === 'in-progress').map((e) => e.actor);
82
+ return { assignees: [...i.assignees], claimer: actors.length ? actors[actors.length - 1] : null };
83
+ }
84
+ const withList = (data) => (offline ? result(false, { data: null }) : result(true, { stdout: JSON.stringify(data), data }));
85
+
86
+ return {
87
+ kind: 'fake',
88
+ repo: repoAbs,
89
+
90
+ state: () => (offline ? { ok: false, reason: 'missing' } : { ok: true, reason: null }),
91
+ currentLogin: () => (offline ? null : login),
92
+
93
+ issueView: (num, fields) => {
94
+ const i = issues.get(Number(num));
95
+ return offline || !i ? null : pick(issueShape(i), fields);
96
+ },
97
+ issueListAll: ({ limit, fields } = {}) => withList([...issues.values()]
98
+ .sort((a, b) => b.number - a.number).slice(0, limit).map((i) => pick(issueShape(i), fields))),
99
+ issueCreate: ({ title, body }) => {
100
+ if (offline) return { ...result(false), number: null, url: null };
101
+ const number = nextNumber();
102
+ issues.set(number, { number, title, body, state: 'OPEN', stateReason: '', createdAt: null, closedAt: null,
103
+ labels: [], assignees: [], comments: [], events: [] });
104
+ const url = `${base}/issues/${number}`;
105
+ return { ...result(true, { stdout: url }), number, url };
106
+ },
107
+ issueComment: (num, body) => {
108
+ const i = issues.get(Number(num));
109
+ if (offline) return result(false);
110
+ if (!i) return fail(`issue #${num} not found`);
111
+ i.comments.push({ author: login, body });
112
+ return result(true, { stdout: `${base}/issues/${num}#issuecomment-${i.comments.length}` });
113
+ },
114
+ issueClose: (num, { reason } = {}) => {
115
+ const i = issues.get(Number(num));
116
+ if (offline) return result(false);
117
+ if (!i) return fail(`issue #${num} not found`);
118
+ i.state = 'CLOSED';
119
+ i.stateReason = reason === 'not planned' ? 'NOT_PLANNED' : 'COMPLETED';
120
+ return result(true);
121
+ },
122
+ issueRelease: (num, opts = {}) => {
123
+ const caller = offline ? null : login;
124
+ if (offline) return { ...result(false), others: [], caller, note: '' };
125
+ const i = issues.get(Number(num));
126
+ if (!i) return { ...fail(`issue #${num} not found`), others: [], caller, note: '' };
127
+ let others = [];
128
+ let note = '';
129
+ if (!opts.selfOnly) {
130
+ const h = claimHolder(Number(num));
131
+ if (h.claimer && h.claimer !== caller && (h.assignees === null || h.assignees.includes(h.claimer))) others = [h.claimer];
132
+ else if (!h.claimer && h.assignees === null) note = 'could not read who holds the claim — unassigned @me only';
133
+ }
134
+ const drop = new Set([caller, ...others]);
135
+ i.assignees = i.assignees.filter((l) => !drop.has(l));
136
+ i.labels = i.labels.filter((l) => l !== 'in-progress');
137
+ return { ...result(true), others, caller, note };
138
+ },
139
+ claimHolder: (num) => claimHolder(Number(num)),
140
+
141
+ labelList: () => (offline ? null : [...labels]),
142
+
143
+ prForBranch: (branch) => {
144
+ if (offline) return { error: 'tracker unavailable (fake: offline)' };
145
+ const open = [...prs.values()].filter((p) => p.head === branch && p.state === 'OPEN').sort((a, b) => b.number - a.number);
146
+ if (!open.length) return { pr: null };
147
+ return { pr: pick(prShape(open[0]), ['number', 'url', 'state', 'author', 'headRefOid', 'reviews']) };
148
+ },
149
+ prCreate: ({ base: into, head, title, body }) => {
150
+ if (offline) return { ok: false, url: null, stderr: 'tracker unavailable (fake: offline)' };
151
+ if ([...prs.values()].some((p) => p.head === head && p.base === into && p.state === 'OPEN')) {
152
+ return { ok: false, url: null, stderr: `a pull request for branch "${head}" into branch "${into}" already exists` };
153
+ }
154
+ const number = nextNumber();
155
+ prs.set(number, { number, base: into, head, title, body, state: 'OPEN', author: login, headRefOid: null, mergedAt: null, reviews: [] });
156
+ return { ok: true, url: `${base}/pull/${number}`, stderr: '' };
157
+ },
158
+ prClose: (num, comment) => {
159
+ const p = prs.get(Number(num));
160
+ if (offline) return result(false);
161
+ if (!p) return fail(`pull request #${num} not found`);
162
+ p.state = 'CLOSED';
163
+ if (comment) (p.comments = p.comments || []).push({ author: login, body: comment });
164
+ return result(true);
165
+ },
166
+ prList: ({ base: into, head, state, limit, fields }) => withList([...prs.values()]
167
+ .filter((p) => p.base === into && p.head === head && (state === 'all' || p.state === String(state).toUpperCase()))
168
+ .sort((a, b) => b.number - a.number).slice(0, limit).map((p) => pick(prShape(p), fields))),
169
+ prEdit: (num, { title, body }) => {
170
+ const p = prs.get(Number(num));
171
+ if (offline) return result(false);
172
+ if (!p) return fail(`pull request #${num} not found`);
173
+ Object.assign(p, { title, body });
174
+ return result(true);
175
+ },
176
+
177
+ runList: ({ branch, commit, limit, fields }) => withList(runs
178
+ .filter((r) => r.headBranch === branch && (!commit || r.headSha === commit))
179
+ .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
180
+ .slice(0, limit).map((r) => pick(r, fields))),
181
+
182
+ releaseView: (tag) => {
183
+ if (offline) return result(false);
184
+ return releases.has(tag) ? result(true, { stdout: JSON.stringify({ tagName: tag }) }) : fail('release not found');
185
+ },
186
+ releaseCreate: (tag, { final = false } = {}) => {
187
+ if (offline) return result(false);
188
+ if (releases.has(tag)) return fail(`a release with tag ${tag} already exists`);
189
+ releases.set(tag, { tag, prerelease: !final });
190
+ return result(true, { stdout: `${base}/releases/tag/${tag}` });
191
+ },
192
+ };
193
+ }
194
+
195
+ module.exports = { create };
@@ -0,0 +1,106 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/tracker-github.js — the GitHub implementation of the tracker contract (#500), and the
4
+ * ONLY place in the CLI that spawns `gh`. Every `gh` call in tools/colab and tools/lib/git.js
5
+ * reaches the binary through `exec` below; the contract it implements is tools/lib/tracker.js.
6
+ *
7
+ * Two layers, on purpose:
8
+ * - `exec(args, opts)` — the raw spawn. git.js's `gh*` helpers call it (through their own lazy
9
+ * `gh()`), so their bodies, exports and callers stay exactly as they were.
10
+ * - `create(repoAbs)` — a repo-bound object carrying the contract's methods (tracker.METHODS).
11
+ * Methods are synchronous, never throw on an environment failure (no gh, no remote, offline —
12
+ * all come back as data), and keep the existing helpers' return shapes: a write returns
13
+ * git.run's `{ ok, code, stdout, stderr, error, timedOut }`; a list read adds `data` (parsed
14
+ * JSON, or `null` when the call failed, printed nothing, or printed something unparseable —
15
+ * `null` is "could not read", never "none").
16
+ *
17
+ * Behaviour-preserving by construction: every method spawns the exact argv and options the call
18
+ * site it replaced spawned (pinned by tools/lib/tracker-github.test.js's argv table).
19
+ *
20
+ * This module must NOT require ./tracker (tracker requires this one), and git.js must never require
21
+ * this module at its top level: git.js ends in `module.exports = {…}`, which REPLACES the exports
22
+ * object, so a load-time cycle would hand this module a stale empty `{}`. `git.run` is therefore
23
+ * looked up at call time, never captured — tests also swap PATH between calls, so the binary is
24
+ * resolved per call, never cached.
25
+ */
26
+
27
+ let _runner = null; // test seam only — see withRunner
28
+
29
+ /** Spawn `gh <args>` with `opts` (git.run's options: cwd, timeoutMs, maxBuffer, …). */
30
+ function exec(args, opts = {}) {
31
+ return _runner ? _runner(args, opts) : require('./git').run('gh', args, opts);
32
+ }
33
+
34
+ /**
35
+ * Run `fn` with every `gh` spawn — including the ones git.js's helpers make — routed to
36
+ * `runner(args, opts)` instead of the binary. Synchronous only; the previous runner is restored
37
+ * even when `fn` throws.
38
+ */
39
+ function withRunner(runner, fn) {
40
+ const prev = _runner;
41
+ _runner = runner;
42
+ try { return fn(); } finally { _runner = prev; }
43
+ }
44
+
45
+ /** Parsed stdout as `data`, or null on failure / empty / unparseable output. */
46
+ function withData(r) {
47
+ let data = null;
48
+ if (r.ok && r.stdout) { try { data = JSON.parse(r.stdout); } catch (_) { data = null; } }
49
+ return { ...r, data };
50
+ }
51
+
52
+ function create(repoAbs) {
53
+ const git = () => require('./git');
54
+ const at = { cwd: repoAbs };
55
+ return {
56
+ kind: 'github',
57
+ repo: repoAbs,
58
+
59
+ // --- identity / availability -------------------------------------------------------------
60
+ state: () => git().ghState(),
61
+ currentLogin: () => git().ghCurrentLogin(),
62
+
63
+ // --- issues ------------------------------------------------------------------------------
64
+ issueView: (num, fields) => git().ghIssueView(repoAbs, num, fields),
65
+ issueListAll: ({ limit, fields, maxBuffer } = {}) => withData(exec(
66
+ ['issue', 'list', '--state', 'all', '--limit', String(limit), '--json', fields.join(',')],
67
+ { ...at, ...(maxBuffer ? { maxBuffer } : {}) })),
68
+ issueCreate: ({ title, body }) => {
69
+ const r = exec(['issue', 'create', '--title', title, '--body', body], at);
70
+ const m = r.ok ? /\/issues\/([0-9]+)/.exec(r.stdout || '') : null;
71
+ return { ...r, number: m ? Number(m[1]) : null, url: m ? (r.stdout || '').trim() : null };
72
+ },
73
+ issueComment: (num, body) => git().ghIssueComment(repoAbs, num, body),
74
+ issueClose: (num, { reason } = {}) =>
75
+ exec(['issue', 'close', String(num), ...(reason ? ['--reason', reason] : [])], at),
76
+ issueRelease: (num, opts) => git().ghIssueRelease(repoAbs, num, opts),
77
+ claimHolder: (num) => git().ghClaimHolder(repoAbs, num),
78
+
79
+ // --- labels ------------------------------------------------------------------------------
80
+ labelList: () => git().ghListLabels(repoAbs),
81
+
82
+ // --- pull requests -----------------------------------------------------------------------
83
+ prForBranch: (branch) => git().ghPrForBranch(repoAbs, branch),
84
+ prCreate: (spec) => git().ghPrCreate(repoAbs, spec),
85
+ prClose: (num, comment) => git().ghPrClose(repoAbs, num, comment),
86
+ prList: ({ base, head, state, limit, fields }) => withData(exec(
87
+ ['pr', 'list', '--base', base, '--head', head, '--state', state, '--limit', String(limit),
88
+ '--json', fields.join(',')], at)),
89
+ prEdit: (num, { title, body }) =>
90
+ exec(['pr', 'edit', String(num), '--title', title, '--body', body], at),
91
+
92
+ // --- CI runs -----------------------------------------------------------------------------
93
+ runList: ({ branch, commit, limit, fields }) => withData(exec(
94
+ ['run', 'list', '--branch', branch, ...(commit ? ['--commit', commit] : []), '-L', String(limit),
95
+ '--json', fields.join(',')], at)),
96
+
97
+ // --- releases ----------------------------------------------------------------------------
98
+ releaseView: (tag) => exec(['release', 'view', tag, '--json', 'tagName'], at),
99
+ releaseCreate: (tag, { notesFile, final = false }) => {
100
+ const releaseCut = require('./release-cut'); // owns the argv (release-cut.test.js pins it)
101
+ return exec(final ? releaseCut.finalReleaseArgs(tag, notesFile) : releaseCut.prereleaseArgs(tag, notesFile), at);
102
+ },
103
+ };
104
+ }
105
+
106
+ module.exports = { exec, withRunner, create };
@@ -0,0 +1,206 @@
1
+ {
2
+ "$comment": "Tracker contract scenarios (#501) — the language-neutral spec of what an implementation of the tracker contract (tools/lib/tracker.js METHODS) must do. Each scenario: seed a tracker from `given`, run `steps` in order against that ONE tracker (state carries from step to step), and compare each step's return value to `expect`. This repo runs every scenario against its in-memory fake (tools/lib/tracker-fake.js) and against its GitHub adapter (tools/lib/tracker-github.js, gh replies replayed from recorded transcripts) — tools/lib/tracker-contract.test.js. A consumer with its own adapter, in any language, runs the same file with its own runner; see `match` for the comparison rules and `given` for the seed shape.",
3
+ "version": 1,
4
+ "match": {
5
+ "$comment": "How `expect` is compared with a step's actual return value. Partial by design: an implementation may return MORE than a scenario pins, never less or different.",
6
+ "null": "`expect: null` requires the value to be exactly null.",
7
+ "scalar": "a string, number or boolean must be strictly equal.",
8
+ "object": "every key in `expect` must be present in the actual object and match recursively; extra actual keys are ignored.",
9
+ "array": "the actual array must have the same length, and element i must match expect[i] recursively (order matters).",
10
+ "$re": "an object {\"$re\": \"<pattern>\"} matches a string the regular expression (ECMAScript syntax, unanchored) finds a match in.",
11
+ "$type": "an object {\"$type\": \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\"} matches any value of that type (array is not object)."
12
+ },
13
+ "given": {
14
+ "$comment": "The seed. Every key is optional. Logins and label names are plain strings here; how an implementation stores them is its own business.",
15
+ "login": "the account the tracker is authenticated as (what currentLogin returns, and the author of anything this tracker writes).",
16
+ "offline": "true = the tracker cannot be reached: reads return their `could not read` value (null, or `data: null`), writes return ok:false. Never a throw.",
17
+ "labels": "the label names defined on the repo, in the order labelList returns them.",
18
+ "issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{author, body}], events: [{event: \"labeled\", label, actor}]}] — `events` is the label timeline claimHolder reads; the claimer is the actor of the LATEST labeled in-progress event.",
19
+ "prs": "[{number, head, base, title, body, state: OPEN|CLOSED|MERGED, author}] — issues and pull requests share ONE number sequence, as on GitHub.",
20
+ "runs": "[{headBranch, headSha, status, conclusion, event, workflowName, createdAt}] — CI runs; runList returns them newest first by createdAt.",
21
+ "releases": "[{tag, prerelease}]"
22
+ },
23
+ "scenarios": [
24
+ {
25
+ "id": "identity",
26
+ "description": "An available tracker reports itself available and names the account it acts as.",
27
+ "given": { "login": "alice" },
28
+ "steps": [
29
+ { "call": "state", "args": [], "expect": { "ok": true, "reason": null } },
30
+ { "call": "currentLogin", "args": [], "expect": "alice" }
31
+ ]
32
+ },
33
+ {
34
+ "id": "issue-view",
35
+ "description": "issueView returns the requested fields of an issue, labels and assignees as objects; an issue that does not exist reads as null, never as an empty object.",
36
+ "given": {
37
+ "login": "alice",
38
+ "issues": [{ "number": 7, "title": "fix: the importer drops rows", "body": "Repro attached.", "state": "OPEN", "labels": ["bug", "in-progress"], "assignees": ["bob"] }]
39
+ },
40
+ "steps": [
41
+ { "call": "issueView", "args": [7, ["number", "title", "state", "labels", "assignees"]],
42
+ "expect": { "number": 7, "title": "fix: the importer drops rows", "state": "OPEN", "labels": [{ "name": "bug" }, { "name": "in-progress" }], "assignees": [{ "login": "bob" }] } },
43
+ { "call": "issueView", "args": [99, ["number"]], "expect": null }
44
+ ]
45
+ },
46
+ {
47
+ "id": "issue-create",
48
+ "description": "issueCreate takes the next number in the sequence issues and pull requests share, returns it with the issue's URL, and the new issue is open with nothing on it.",
49
+ "given": {
50
+ "login": "alice",
51
+ "issues": [{ "number": 7, "title": "an older issue", "state": "OPEN" }],
52
+ "prs": [{ "number": 8, "head": "fix/older-7", "base": "main", "title": "fix: older", "state": "MERGED", "author": "bob" }]
53
+ },
54
+ "steps": [
55
+ { "call": "issueCreate", "args": [{ "title": "feat: export as CSV", "body": "## Goal\nExport." }],
56
+ "expect": { "ok": true, "number": 9, "url": { "$re": "/issues/9$" } } },
57
+ { "call": "issueView", "args": [9, ["title", "body", "state", "labels", "assignees", "comments"]],
58
+ "expect": { "title": "feat: export as CSV", "body": "## Goal\nExport.", "state": "OPEN", "labels": [], "assignees": [], "comments": [] } }
59
+ ]
60
+ },
61
+ {
62
+ "id": "issue-comment",
63
+ "description": "A comment lands on the issue, authored by the tracker's account; commenting on an issue that does not exist fails as data.",
64
+ "given": { "login": "alice", "issues": [{ "number": 3, "title": "t", "state": "OPEN" }] },
65
+ "steps": [
66
+ { "call": "issueComment", "args": [3, "Progress: the parser is done."], "expect": { "ok": true } },
67
+ { "call": "issueView", "args": [3, ["comments"]],
68
+ "expect": { "comments": [{ "author": { "login": "alice" }, "body": "Progress: the parser is done." }] } },
69
+ { "call": "issueComment", "args": [404, "nobody home"], "expect": { "ok": false } }
70
+ ]
71
+ },
72
+ {
73
+ "id": "issue-close-reasons",
74
+ "description": "Closing with no reason records COMPLETED; closing with reason `not planned` records NOT_PLANNED.",
75
+ "given": { "login": "alice", "issues": [{ "number": 4, "title": "done", "state": "OPEN" }, { "number": 5, "title": "dropped", "state": "OPEN" }] },
76
+ "steps": [
77
+ { "call": "issueClose", "args": [4], "expect": { "ok": true } },
78
+ { "call": "issueClose", "args": [5, { "reason": "not planned" }], "expect": { "ok": true } },
79
+ { "call": "issueView", "args": [4, ["state", "stateReason"]], "expect": { "state": "CLOSED", "stateReason": "COMPLETED" } },
80
+ { "call": "issueView", "args": [5, ["state", "stateReason"]], "expect": { "state": "CLOSED", "stateReason": "NOT_PLANNED" } }
81
+ ]
82
+ },
83
+ {
84
+ "id": "claim-holder",
85
+ "description": "The claimer is the actor of the LATEST labeled-in-progress event, not the first; no event means no claimer; an issue that cannot be read gives null for both, never `nobody`.",
86
+ "given": {
87
+ "login": "alice",
88
+ "issues": [
89
+ { "number": 11, "title": "re-claimed", "state": "OPEN", "labels": ["in-progress"], "assignees": ["bob"],
90
+ "events": [{ "event": "labeled", "label": "in-progress", "actor": "carol" }, { "event": "labeled", "label": "in-progress", "actor": "bob" }] },
91
+ { "number": 12, "title": "never claimed", "state": "OPEN" }
92
+ ]
93
+ },
94
+ "steps": [
95
+ { "call": "claimHolder", "args": [11], "expect": { "assignees": ["bob"], "claimer": "bob" } },
96
+ { "call": "claimHolder", "args": [12], "expect": { "assignees": [], "claimer": null } },
97
+ { "call": "claimHolder", "args": [404], "expect": { "assignees": null, "claimer": null } }
98
+ ]
99
+ },
100
+ {
101
+ "id": "release-another-accounts-claim",
102
+ "description": "A claim taken under one account and released under another drops BOTH halves: the in-progress label and the claimer's assignee, and says whose assignee it removed.",
103
+ "given": {
104
+ "login": "alice",
105
+ "issues": [{ "number": 20, "title": "claimed by bob", "state": "OPEN", "labels": ["in-progress", "bug"], "assignees": ["bob"],
106
+ "events": [{ "event": "labeled", "label": "in-progress", "actor": "bob" }] }]
107
+ },
108
+ "steps": [
109
+ { "call": "issueRelease", "args": [20], "expect": { "ok": true, "caller": "alice", "others": ["bob"], "note": "" } },
110
+ { "call": "issueView", "args": [20, ["labels", "assignees"]], "expect": { "labels": [{ "name": "bug" }], "assignees": [] } }
111
+ ]
112
+ },
113
+ {
114
+ "id": "release-self-only",
115
+ "description": "selfOnly releases only the caller's half: the label goes, the latest labeler keeps its assignee (the yield path, where that labeler may be the winner of a race).",
116
+ "given": {
117
+ "login": "alice",
118
+ "issues": [{ "number": 21, "title": "raced", "state": "OPEN", "labels": ["in-progress"], "assignees": ["alice", "bob"],
119
+ "events": [{ "event": "labeled", "label": "in-progress", "actor": "bob" }] }]
120
+ },
121
+ "steps": [
122
+ { "call": "issueRelease", "args": [21, { "selfOnly": true }], "expect": { "ok": true, "caller": "alice", "others": [] } },
123
+ { "call": "issueView", "args": [21, ["labels", "assignees"]], "expect": { "labels": [], "assignees": [{ "login": "bob" }] } }
124
+ ]
125
+ },
126
+ {
127
+ "id": "labels-and-issue-list",
128
+ "description": "labelList returns the repo's label names; issueListAll returns every issue, open and closed, newest first, with the requested fields.",
129
+ "given": {
130
+ "login": "alice",
131
+ "labels": ["bug", "in-progress", "needs-plan"],
132
+ "issues": [{ "number": 1, "title": "open one", "state": "OPEN", "labels": ["bug"] }, { "number": 2, "title": "closed one", "state": "CLOSED", "stateReason": "COMPLETED" }]
133
+ },
134
+ "steps": [
135
+ { "call": "labelList", "args": [], "expect": ["bug", "in-progress", "needs-plan"] },
136
+ { "call": "issueListAll", "args": [{ "limit": 100, "fields": ["number", "state", "labels"] }],
137
+ "expect": { "ok": true, "data": [{ "number": 2, "state": "CLOSED", "labels": [] }, { "number": 1, "state": "OPEN", "labels": [{ "name": "bug" }] }] } }
138
+ ]
139
+ },
140
+ {
141
+ "id": "pull-request-lifecycle",
142
+ "description": "No open PR for a branch reads as {pr: null}; a created PR takes the shared next number, is found by its branch, can be retitled, and once closed is no longer the branch's open PR while prList with state all still lists it.",
143
+ "given": { "login": "alice", "issues": [{ "number": 30, "title": "feat: x", "state": "OPEN" }] },
144
+ "steps": [
145
+ { "call": "prForBranch", "args": ["feat/x-30"], "expect": { "pr": null } },
146
+ { "call": "prCreate", "args": [{ "base": "main", "head": "feat/x-30", "title": "feat: x", "body": "Closes #30" }],
147
+ "expect": { "ok": true, "url": { "$re": "/pull/31$" } } },
148
+ { "call": "prForBranch", "args": ["feat/x-30"],
149
+ "expect": { "pr": { "number": 31, "state": "OPEN", "author": { "login": "alice" }, "reviews": [] } } },
150
+ { "call": "prEdit", "args": [31, { "title": "feat: x, retitled", "body": "Closes #30" }], "expect": { "ok": true } },
151
+ { "call": "prList", "args": [{ "base": "main", "head": "feat/x-30", "state": "all", "limit": 50, "fields": ["number", "state", "title"] }],
152
+ "expect": { "ok": true, "data": [{ "number": 31, "state": "OPEN", "title": "feat: x, retitled" }] } },
153
+ { "call": "prClose", "args": [31, "Landed by squash on main."], "expect": { "ok": true } },
154
+ { "call": "prForBranch", "args": ["feat/x-30"], "expect": { "pr": null } },
155
+ { "call": "prList", "args": [{ "base": "main", "head": "feat/x-30", "state": "all", "limit": 50, "fields": ["number", "state"] }],
156
+ "expect": { "ok": true, "data": [{ "number": 31, "state": "CLOSED" }] } }
157
+ ]
158
+ },
159
+ {
160
+ "id": "ci-runs",
161
+ "description": "runList returns one branch's runs newest first, honours the limit, and narrows to one commit when asked.",
162
+ "given": {
163
+ "login": "alice",
164
+ "runs": [
165
+ { "headBranch": "main", "headSha": "aaa1111", "status": "completed", "conclusion": "success", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T10:00:00Z" },
166
+ { "headBranch": "main", "headSha": "bbb2222", "status": "in_progress", "conclusion": "", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T11:00:00Z" },
167
+ { "headBranch": "feat/y-40", "headSha": "ccc3333", "status": "completed", "conclusion": "failure", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T12:00:00Z" }
168
+ ]
169
+ },
170
+ "steps": [
171
+ { "call": "runList", "args": [{ "branch": "main", "limit": 10, "fields": ["headSha", "status", "conclusion"] }],
172
+ "expect": { "ok": true, "data": [{ "headSha": "bbb2222", "status": "in_progress", "conclusion": "" }, { "headSha": "aaa1111", "status": "completed", "conclusion": "success" }] } },
173
+ { "call": "runList", "args": [{ "branch": "main", "limit": 1, "fields": ["headSha"] }],
174
+ "expect": { "ok": true, "data": [{ "headSha": "bbb2222" }] } },
175
+ { "call": "runList", "args": [{ "branch": "main", "commit": "aaa1111", "limit": 10, "fields": ["headSha", "conclusion"] }],
176
+ "expect": { "ok": true, "data": [{ "headSha": "aaa1111", "conclusion": "success" }] } }
177
+ ]
178
+ },
179
+ {
180
+ "id": "releases",
181
+ "description": "A release that does not exist reads as a failed view; once created it reads back; creating the same tag twice fails as data.",
182
+ "given": { "login": "alice", "releases": [{ "tag": "v1.0.0", "prerelease": false }] },
183
+ "steps": [
184
+ { "call": "releaseView", "args": ["v1.1.0-rc.1"], "expect": { "ok": false } },
185
+ { "call": "releaseCreate", "args": ["v1.1.0-rc.1", { "notesFile": "notes.md" }], "expect": { "ok": true } },
186
+ { "call": "releaseView", "args": ["v1.1.0-rc.1"], "expect": { "ok": true } },
187
+ { "call": "releaseView", "args": ["v1.0.0"], "expect": { "ok": true } },
188
+ { "call": "releaseCreate", "args": ["v1.1.0-rc.1", { "notesFile": "notes.md" }], "expect": { "ok": false } }
189
+ ]
190
+ },
191
+ {
192
+ "id": "offline",
193
+ "description": "An unreachable tracker never throws: every read is `could not read` (null, data: null, or an error), every write is ok:false — and none of them is mistaken for `none`.",
194
+ "given": { "login": "alice", "offline": true, "issues": [{ "number": 1, "title": "exists, unreachable", "state": "OPEN", "labels": ["bug"] }] },
195
+ "steps": [
196
+ { "call": "issueView", "args": [1, ["number"]], "expect": null },
197
+ { "call": "issueListAll", "args": [{ "limit": 10, "fields": ["number"] }], "expect": { "ok": false, "data": null } },
198
+ { "call": "labelList", "args": [], "expect": null },
199
+ { "call": "claimHolder", "args": [1], "expect": { "assignees": null, "claimer": null } },
200
+ { "call": "issueComment", "args": [1, "lost"], "expect": { "ok": false } },
201
+ { "call": "runList", "args": [{ "branch": "main", "limit": 5, "fields": ["headSha"] }], "expect": { "ok": false, "data": null } },
202
+ { "call": "prForBranch", "args": ["feat/x-1"], "expect": { "error": { "$type": "string" } } }
203
+ ]
204
+ }
205
+ ]
206
+ }
@@ -0,0 +1,64 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/tracker.js — the tracker contract (#500): what the CLI asks of an issue tracker, named
4
+ * once, so an implementation other than GitHub (and #501's in-memory fake) has a method set to
5
+ * satisfy instead of a scatter of `gh` argv to imitate.
6
+ *
7
+ * The only real implementation today is tools/lib/tracker-github.js; tools/lib/tracker-fake.js is an
8
+ * in-memory one (#501). What every implementation must do is specified as data, in
9
+ * tools/lib/tracker-scenarios.json, and tools/lib/tracker-contract.test.js runs those scenarios
10
+ * against both. Semantics every implementation keeps:
11
+ * - synchronous — the CLI is spawnSync throughout;
12
+ * - bound to one repo — `forRepo(repoAbs)` fixes it, so no method takes a repo argument;
13
+ * - never throws on an environment failure (no tracker binary, no remote, offline): results are
14
+ * data. Writes return `{ ok, code, stdout, stderr, … }`; list reads add `data`, `null` meaning
15
+ * "could not read" and never "none"; the read helpers keep their existing null-on-failure
16
+ * contract.
17
+ *
18
+ * Deliberately NOT in the contract yet (#501 left it so: no scenario needs them, and each would
19
+ * pin a GitHub-only shape into a spec other trackers must satisfy): the CI-run
20
+ * summarisers and REST probes, label create/delete/edit, raw `issue edit` flags and raw `api`
21
+ * access. They still reach `gh` only through the adapter's `exec`.
22
+ */
23
+
24
+ const METHODS = Object.freeze([
25
+ { name: 'state', kind: 'read', returns: '{ ok, reason }' },
26
+ { name: 'currentLogin', kind: 'read', returns: 'login | null' },
27
+ { name: 'issueView', kind: 'read', returns: 'object | null' },
28
+ { name: 'issueListAll', kind: 'read', returns: 'result + data: issue[] | null' },
29
+ { name: 'issueCreate', kind: 'write', returns: 'result + number, url' },
30
+ { name: 'issueComment', kind: 'write', returns: 'result' },
31
+ { name: 'issueClose', kind: 'write', returns: 'result' },
32
+ { name: 'issueRelease', kind: 'write', returns: '{ ok, stderr, code, others, caller, note }' },
33
+ { name: 'claimHolder', kind: 'read', returns: '{ assignees, claimer }' },
34
+ { name: 'labelList', kind: 'read', returns: 'name[] | null' },
35
+ { name: 'prForBranch', kind: 'read', returns: '{ pr } | { error }' },
36
+ { name: 'prCreate', kind: 'write', returns: '{ ok, url, stderr }' },
37
+ { name: 'prClose', kind: 'write', returns: 'result' },
38
+ { name: 'prList', kind: 'read', returns: 'result + data: pr[] | null' },
39
+ { name: 'prEdit', kind: 'write', returns: 'result' },
40
+ { name: 'runList', kind: 'read', returns: 'result + data: run[] | null' },
41
+ { name: 'releaseView', kind: 'read', returns: 'result' },
42
+ { name: 'releaseCreate', kind: 'write', returns: 'result' },
43
+ ].map(Object.freeze));
44
+
45
+ /** Throw, naming every contract method `impl` lacks. Returns `impl` when it is complete. */
46
+ function assertImplements(impl, label = 'tracker') {
47
+ const missing = METHODS.filter((m) => !impl || typeof impl[m.name] !== 'function').map((m) => m.name);
48
+ if (missing.length) throw new Error(`${label} does not implement the tracker contract: missing ${missing.join(', ')}`);
49
+ return impl;
50
+ }
51
+
52
+ const KINDS = { github: () => require('./tracker-github'), fake: () => require('./tracker-fake') };
53
+ const _checked = new Set();
54
+
55
+ /** The tracker for one repo. `kind` defaults to the one implementation, `github`. */
56
+ function forRepo(repoAbs, { kind = 'github' } = {}) {
57
+ const load = KINDS[kind];
58
+ if (!load) throw new Error(`unknown tracker kind "${kind}" (known: ${Object.keys(KINDS).join(', ')})`);
59
+ const impl = load().create(repoAbs);
60
+ if (!_checked.has(kind)) { assertImplements(impl, `tracker "${kind}"`); _checked.add(kind); }
61
+ return impl;
62
+ }
63
+
64
+ module.exports = { METHODS, assertImplements, forRepo };