@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1

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 (73) hide show
  1. package/README.md +243 -213
  2. package/README.vi.md +246 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +6 -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 +1691 -254
  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 +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -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 +716 -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 +762 -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 +303 -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 +106 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/stamp.js +7 -0
  65. package/tools/lib/tracker-fake.js +195 -0
  66. package/tools/lib/tracker-github.js +106 -0
  67. package/tools/lib/tracker-scenarios.json +206 -0
  68. package/tools/lib/tracker.js +64 -0
  69. package/tools/lib/tree-green.js +88 -0
  70. package/tools/lib/util.js +17 -1
  71. package/tools/lib/verify-runs.js +104 -0
  72. package/tools/lib/wake.js +8 -90
  73. package/tools/lib/workflow-triggers.js +48 -0
@@ -115,6 +115,71 @@ function reportableLabels(verdicts) {
115
115
  return (verdicts || []).filter((v) => v && v.verdict !== 'mid-flight');
116
116
  }
117
117
 
118
+ /**
119
+ * #448: the second read before a destructive delete. Measured in an adopting repo: ship's (i)
120
+ * teardown deleted `group:<key>` while a fourth, deliberately-unshipped member still carried it
121
+ * OPEN — the open-member listing had come back empty 29 s after the squash closed the other three.
122
+ * That listing is `gh issue list --label`, which `gh` serves through GraphQL `search(...)`
123
+ * (verified with GH_DEBUG=api), and the search index lags the issues table: a burst of closes and
124
+ * label writes can leave it answering "0 open" for a label still on an open issue.
125
+ *
126
+ * `gh label delete` is repo-wide and cannot be undone per issue, so "0 open" from search alone is
127
+ * not enough to act on. The confirming read is the REST issues list (`ghOpenIssueNumbersByLabel`),
128
+ * which reads the issues table, not the index. The two failures are asymmetric exactly as
129
+ * isOpenMember's note says — keeping a spent label costs one stale picker entry until the next
130
+ * ship or `doctor --sync --prune`; deleting a live one strips a grouping from work in flight — so
131
+ * every case but "both reads agree on zero" keeps the label.
132
+ *
133
+ * @param {Array|null} searchOpen open members per the search-backed listing; null = could not read
134
+ * @param {Array|null} confirmOpen open member NUMBERS per the non-search read; null = could not read
135
+ * @returns {{action:'delete'|'keep', reason:string, open:number[]}}
136
+ * reason ∈ unread · open · unconfirmed · disagree · spent
137
+ */
138
+ function spentLabelDecision(searchOpen, confirmOpen) {
139
+ if (searchOpen === null || searchOpen === undefined) return { action: 'keep', reason: 'unread', open: [] };
140
+ if (Array.isArray(searchOpen) && searchOpen.length > 0) return { action: 'keep', reason: 'open', open: [] };
141
+ if (confirmOpen === null || confirmOpen === undefined || !Array.isArray(confirmOpen)) {
142
+ return { action: 'keep', reason: 'unconfirmed', open: [] };
143
+ }
144
+ if (confirmOpen.length > 0) {
145
+ const nums = confirmOpen.map((m) => (m && typeof m === 'object' ? m.number : m))
146
+ .filter((n) => n !== undefined && n !== null);
147
+ return { action: 'keep', reason: 'disagree', open: nums };
148
+ }
149
+ return { action: 'delete', reason: 'spent', open: [] };
150
+ }
151
+
152
+ /**
153
+ * The I/O shell around spentLabelDecision, with every call injected so the delete path is pinned by
154
+ * a test with no network (#448). `searchOpen` may be passed pre-read (doctor already has the
155
+ * membership from its classify pass) or as a function; `confirmOpen` and `deleteLabel` are always
156
+ * functions and are only CALLED when needed — the confirm read only when search said zero, the
157
+ * delete only when both reads agree.
158
+ *
159
+ * @returns {{action:'delete'|'keep', reason:string, open:number[], deleted:boolean, error:string|null}}
160
+ */
161
+ function teardownSpentGroupLabel(name, { searchOpen, confirmOpen, deleteLabel }) {
162
+ if (!isGroupLabel(name)) return { action: 'keep', reason: 'unread', open: [], deleted: false, error: null };
163
+ const s = typeof searchOpen === 'function' ? searchOpen(name) : searchOpen;
164
+ const needConfirm = Array.isArray(s) && s.length === 0;
165
+ const c = needConfirm ? confirmOpen(name) : null;
166
+ const d = spentLabelDecision(s, needConfirm ? c : null);
167
+ if (d.action !== 'delete') return { ...d, deleted: false, error: null };
168
+ const r = deleteLabel(name) || {};
169
+ return { ...d, deleted: !!r.ok, error: r.ok ? null : (r.stderr || 'gh label delete failed') };
170
+ }
171
+
172
+ /** One human line for a kept label — the CLI and its test read the same words. */
173
+ function keptReason(name, d) {
174
+ switch (d.reason) {
175
+ case 'unread': return `could not check membership of ${name} — left in place`;
176
+ case 'unconfirmed': return `${name} reads 0 open members by search but the confirming (non-search) read failed — left in place`;
177
+ case 'disagree': return `${name} reads 0 open members by search, but #${d.open.join(', #')} still carr${d.open.length === 1 ? 'ies' : 'y'} it open (non-search read) — left in place; the search index is lagging (#448)`;
178
+ default: return '';
179
+ }
180
+ }
181
+
118
182
  module.exports = {
119
183
  isOpenMember, classifyGroupLabel, classifyGroupLabels, deletableLabels, reportableLabels,
184
+ spentLabelDecision, teardownSpentGroupLabel, keptReason,
120
185
  };
@@ -13,8 +13,9 @@
13
13
  *
14
14
  * Row severities, and the one rule behind them: ✗ (fail, exit 1) means something was INSTALLED and
15
15
  * is now stale or unusable; ⚠ means something was simply never set up, which may be a deliberate
16
- * choice (a machine that only wants the skills needs no fleet list). A report that failed every
17
- * skills-only machine would teach people to ignore its exit code.
16
+ * choice (a machine that only wants the skills needs no fleet list) or just not done YET (no repo
17
+ * registered, no identity vocabulary). A report that failed every skills-only machine — or every
18
+ * correct fresh `--all` install, as it did until #521 — would teach people to ignore its exit code.
18
19
  *
19
20
  * CommonJS, zero dependencies, runnable as a script: install.sh calls
20
21
  * node tools/lib/install-check.js --root <handbook> --colab-home <dir> --home <dir>
@@ -163,9 +164,9 @@ function checkState({ root, colabHome, home }) {
163
164
  }
164
165
 
165
166
  /**
166
- * The fleet: both machine-local registries `colab register` writes. A repos.txt that exists with no
167
- * live entry is the `--fleet` dead end — seeded from placeholders, and the next command refuses with
168
- * "No repos registered". That one is a ✗; never having asked for a fleet is a ⚠.
167
+ * The fleet: both machine-local registries `colab register` writes. Nothing registered is ⚠ whether or
168
+ * not `--fleet` seeded the placeholder list: both are "not set up yet", the state every correct fresh
169
+ * install is in until its first `colab register` (#521). The ⚠ text still names the dead end.
169
170
  */
170
171
  function checkFleet({ colabHome }) {
171
172
  const rows = [];
@@ -179,7 +180,9 @@ function checkFleet({ colabHome }) {
179
180
  if (entries === null && !cfgRepos.length) {
180
181
  rows.push({ area: 'fleet', severity: WARN, text: `nothing registered — add each repo: colab register <path>` });
181
182
  } else if (entries !== null && !entries.length) {
182
- rows.push({ area: 'fleet', severity: FAIL, text: `${txtFile} exists with no live entry (placeholders only) — \`colab update\`/\`colab release-status\` refuse "No repos registered". Fix: colab register <path>` });
183
+ // #521: this is exactly what `--fleet` leaves on a new machine, and the install's own "next" list
184
+ // says to register a repo. Not yet set up, not broken — a ✗ here failed every correct fresh install.
185
+ rows.push({ area: 'fleet', severity: WARN, text: `nothing registered yet — ${txtFile} holds placeholders only, so \`colab update\`/\`colab release-status\` refuse "No repos registered". Next: colab register <path>` });
183
186
  } else {
184
187
  const locals = (entries || []).filter((e) => e.startsWith('/') || e.startsWith('~'));
185
188
  const unmirrored = locals.filter((e) => !cfgRepos.includes(e));
@@ -196,6 +199,9 @@ function checkFleet({ colabHome }) {
196
199
  * first hooklet's dependency) and said nothing about the identity vocabulary the second needs — and
197
200
  * the second guards publication to a public repo. With no vocabulary it warns and passes every commit.
198
201
  * Resolution order mirrors templates/pre-commit-identity exactly.
202
+ *
203
+ * Both dependencies are ⚠, never ✗ (#521): the preflight calls them optional, and a missing one is
204
+ * something not set up yet, not an install gone stale. Symmetric still — neither row is quieter.
199
205
  */
200
206
  function checkHooks({ root, colabHome, home, env }) {
201
207
  const hp = gitConfig(root, 'core.hooksPath', env);
@@ -206,7 +212,7 @@ function checkHooks({ root, colabHome, home, env }) {
206
212
  const rows = [];
207
213
  rows.push(isExecutable('gitleaks', env)
208
214
  ? { area: 'hooks', severity: OK, text: 'gitleaks on PATH — the secret scan runs' }
209
- : { area: 'hooks', severity: FAIL, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
215
+ : { area: 'hooks', severity: WARN, text: 'gitleaks not on PATH — the secret-scan hooklet skips every commit (macOS: brew install gitleaks)' });
210
216
 
211
217
  let vocab; let src;
212
218
  if (env.COLAB_IDENTITY_VOCAB) { vocab = env.COLAB_IDENTITY_VOCAB; src = 'COLAB_IDENTITY_VOCAB'; }
@@ -215,7 +221,7 @@ function checkHooks({ root, colabHome, home, env }) {
215
221
  if (vocab.startsWith('~/')) vocab = path.join(home, vocab.slice(2));
216
222
  rows.push(readText(vocab) !== null
217
223
  ? { area: 'hooks', severity: OK, text: `identity vocabulary ${vocab} (${src}) — the identity scan runs` }
218
- : { area: 'hooks', severity: FAIL, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
224
+ : { area: 'hooks', severity: WARN, text: `no identity vocabulary at ${vocab} (${src}) — the identity hooklet warns and lets every commit through. Example: templates/identity-vocabulary.example` });
219
225
  return rows;
220
226
  }
221
227
 
@@ -0,0 +1,139 @@
1
+ 'use strict';
2
+ /**
3
+ * A declared distributed tool has an install route §6 recognises (#469).
4
+ *
5
+ * CONVENTIONS.md §6, *Distribution*: every distributed tool installs with `npx`, by one of four
6
+ * rows (public/private × JS/compiled). What the audit cannot measure is whether a repository
7
+ * ships a tool at all — a root `bin`, a build matrix or a release workflow is just as true of a
8
+ * library or an app nobody installs. So the signal is DECLARED, never inferred: a repository
9
+ * says `distribution: js | compiled` in `.github/project.yml`, and only then is its row's route
10
+ * checked. Undeclared → no finding and no IO, by construction (the admission test: markers
11
+ * identify our text, not a stack).
12
+ *
13
+ * Pure: takes a reader plus the repository's visibility (read from the GitHub API at the
14
+ * caller, never guessed) and returns findings.
15
+ *
16
+ * VALID_DISTRIBUTION -> Set of the declared values
17
+ * rootBin(readFile) -> true when the root package.json has a non-empty bin
18
+ * distRefsCallers(workflows, read) -> [{ wf, line, target }] in-repo routes to dist refs
19
+ * evidence(reader) -> per-row route evidence (what is present, what is missing)
20
+ * findings({ distribution, … }) -> [{ level, text }]
21
+ */
22
+
23
+ const npmGuard = require('./npm-publish-guard.js');
24
+
25
+ const VALID_DISTRIBUTION = new Set(['js', 'compiled']);
26
+
27
+ // The one string the dist-refs template writes that no other workflow has a reason to: the ref
28
+ // namespace its orphan commits are pushed to. Content, not file name — a renamed copy counts.
29
+ const DIST_REF = /refs\/tags\/dist\//;
30
+ const LOCAL_USES = /^\s*-?\s*uses:\s*['"]?\.\/\.github\/workflows\/([\w.-]+\.ya?ml)['"]?\s*$/;
31
+
32
+ function stripComment(line) {
33
+ return line.replace(/(^|\s)#.*$/, '');
34
+ }
35
+
36
+ function parseJson(text) {
37
+ try { return JSON.parse(text); } catch (_) { return undefined; }
38
+ }
39
+
40
+ function hasBin(pkg) {
41
+ if (!pkg || typeof pkg !== 'object') return false;
42
+ const b = pkg.bin;
43
+ if (typeof b === 'string') return b.trim() !== '';
44
+ return !!b && typeof b === 'object' && Object.keys(b).length > 0;
45
+ }
46
+
47
+ function rootBin(readFile) {
48
+ const text = readFile('package.json');
49
+ return text != null && hasBin(parseJson(text));
50
+ }
51
+
52
+ function codeLines(text) {
53
+ return String(text || '').split('\n').map(stripComment);
54
+ }
55
+
56
+ function mentionsDistRef(text) {
57
+ return codeLines(text).some((l) => DIST_REF.test(l));
58
+ }
59
+
60
+ function isReusable(text) {
61
+ return codeLines(text).some((l) => /^\s*workflow_call\s*:/.test(l) || /\bworkflow_call\b/.test(l) && /^\s*on\s*:/.test(l));
62
+ }
63
+
64
+ /**
65
+ * In-repo routes to dist refs: a workflow line `uses: ./.github/workflows/<f>` whose target
66
+ * pushes to refs/tags/dist/, or a non-reusable workflow that does so itself (inlined).
67
+ * A dist-refs copy that nothing calls is not a route.
68
+ */
69
+ function distRefsCallers(workflows, readFile) {
70
+ const out = [];
71
+ for (const wf of workflows || []) {
72
+ const text = readFile(`.github/workflows/${wf}`);
73
+ if (!text) continue;
74
+ codeLines(text).forEach((line, i) => {
75
+ const m = line.match(LOCAL_USES);
76
+ if (!m) return;
77
+ if (mentionsDistRef(readFile(`.github/workflows/${m[1]}`))) out.push({ wf, line: i + 1, target: m[1] });
78
+ });
79
+ if (!isReusable(text) && mentionsDistRef(text)) out.push({ wf, line: null, target: wf });
80
+ }
81
+ return out;
82
+ }
83
+
84
+ /** What each §6 row's route needs, and whether this repository has it. */
85
+ function evidence({ readFile, listDir, workflows }) {
86
+ const publishes = npmGuard.workflowPublishes(workflows, readFile).length > 0;
87
+ const ms = npmGuard.manifests(readFile, listDir).filter((m) => !m.unparsed && m.pkg && typeof m.pkg === 'object');
88
+ const publicBin = ms.some((m) => m.pkg.private !== true && hasBin(m.pkg));
89
+ const publicBinOptDeps = ms.some((m) => m.pkg.private !== true && hasBin(m.pkg)
90
+ && m.pkg.optionalDependencies && typeof m.pkg.optionalDependencies === 'object'
91
+ && Object.keys(m.pkg.optionalDependencies).length > 0);
92
+ const bin = rootBin(readFile);
93
+ const callers = distRefsCallers(workflows, readFile);
94
+ const missing = {
95
+ 'js/public': [
96
+ ...(publishes ? [] : ['no workflow step publishes to npm']),
97
+ ...(publicBin ? [] : ['no non-private package.json has a bin']),
98
+ ],
99
+ 'js/private': bin ? [] : ['root package.json has no bin (the npx github: entry point)'],
100
+ 'compiled/public': [
101
+ ...(publishes ? [] : ['no workflow step publishes to npm']),
102
+ ...(publicBinOptDeps ? [] : ['no non-private package.json has a bin and per-platform optionalDependencies']),
103
+ ],
104
+ 'compiled/private': [
105
+ ...(bin ? [] : ['root package.json has no bin (the launcher, templates/npx-launcher.mjs)']),
106
+ ...(callers.length ? [] : ['no workflow calls a dist-refs workflow (uses: ./.github/workflows/dist-refs.yml, templates/dist-refs.yml)']),
107
+ ],
108
+ };
109
+ return { missing };
110
+ }
111
+
112
+ const RULE = 'every distributed tool installs with npx — public: an npm package; private: `npx github:<org>/<repo>#vX.Y.Z`, compiled binaries as dist refs (CONVENTIONS.md §6, Distribution, #469). A publish in a workflow outside this repository is not visible here';
113
+
114
+ /**
115
+ * @param distribution the raw declared value (undefined/null → not declared → [])
116
+ * @param visibility 'public' | 'private' | 'internal' | null (unknown)
117
+ * An invalid value is the caller's enum check, not reported here.
118
+ */
119
+ function findings({ distribution, readFile, listDir, workflows, visibility }) {
120
+ if (distribution == null || !VALID_DISTRIBUTION.has(distribution)) return [];
121
+ const { missing } = evidence({ readFile, listDir, workflows });
122
+ const pub = missing[`${distribution}/public`];
123
+ const priv = missing[`${distribution}/private`];
124
+ if (visibility === 'public') {
125
+ if (!pub.length) return [];
126
+ return [{ level: 'warn', text: `distribution: ${distribution}, but no install route §6 recognises — public repository: ${pub.join('; ')} — ${RULE}` }];
127
+ }
128
+ if (visibility === 'private' || visibility === 'internal') {
129
+ if (!priv.length) return [];
130
+ return [{ level: 'warn', text: `distribution: ${distribution}, but no install route §6 recognises — ${visibility} repository: ${priv.join('; ')} — ${RULE}` }];
131
+ }
132
+ if (!pub.length || !priv.length) return [];
133
+ return [{
134
+ level: 'warn',
135
+ text: `distribution: ${distribution}, but no install route §6 recognises — repository visibility could not be read, and neither row's route was found (public: ${pub.join('; ')}; private: ${priv.join('; ')}) — ${RULE}`,
136
+ }];
137
+ }
138
+
139
+ module.exports = { VALID_DISTRIBUTION, rootBin, distRefsCallers, evidence, findings };
@@ -283,6 +283,7 @@ function lineRanges(nums, text = null) {
283
283
  }
284
284
 
285
285
  module.exports = {
286
+ stripCode,
286
287
  IMPORT_MAX_DEPTH,
287
288
  SHELL_IMPORT,
288
289
  ENTRY,