@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
@@ -8,7 +8,7 @@
8
8
  * declare to CHOOSE a route its row permits and to NARROW it:
9
9
  *
10
10
  * release:
11
- * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | live
11
+ * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
12
12
  * candidates: auto # auto | off
13
13
  * candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
14
14
  * test-period: 3d # <N>d, never below the route's 3 days
@@ -18,8 +18,11 @@
18
18
  * exports: <path> # #422 — a committed list of public symbols, one per line
19
19
  * npm: <dir> # #433 — publish this package directory to npm from release-auto.yml
20
20
  * npm-gate: <command> # #433 — the pack-allowlist gate, run before every npm publish
21
- * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable?
21
+ * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable? (#484: default per route)
22
22
  * final-grant: 123 # #441 — an operator's recorded decision letting deploy-tag's final be automatic
23
+ * health-url: https://… # #446/#452 — deploy-tag or deploy-tag-fast (required there): the public endpoint reporting the running version
24
+ * rollback: auto # #446 — deploy-tag-fast only: the deploy rolls itself back when that check fails
25
+ * final-spacing: 1h # #446 — deploy-tag-fast only: minimum time between finals (<N>h | <N>d, ≥ 1h)
23
26
  *
24
27
  * Two layers. The descriptor's ROW (exposure + deploy + production) is a fact about the repo; the
25
28
  * ROUTE is how releases run on it. A row permits a fixed set of routes (ROW_ROUTES) and derives one
@@ -44,18 +47,38 @@
44
47
 
45
48
  const axisAuthority = require('./axis-authority.js');
46
49
 
47
- const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant']);
48
- // #438: where the version a tag names comes from. `manifest` (the default) — every declared manifest
49
- // (VERSION, package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it
50
- // on trunk first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check
51
- // skips them, and the repo's own release/deploy step stamps the number from the tag (on a deploy-only
52
- // ref or at build time — never a commit on trunk). Neither widens nor narrows a route: it decides
53
- // which file is the source of a number, never whether a tag is cut.
50
+ const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant', 'health-url', 'rollback', 'final-spacing']);
51
+ // #438: where the version a tag names comes from. `manifest` — every declared manifest (VERSION,
52
+ // package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it on trunk
53
+ // first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check skips
54
+ // them, and the repo's own release/deploy step stamps the number from the tag (on a deploy-only ref
55
+ // or at build time — never a commit on trunk). Neither widens nor narrows a route: it decides which
56
+ // file is the source of a number, never whether a tag is cut.
57
+ // #484: the DEFAULT is per route (defaultVersionSource below) — `tag` wherever the machine cuts the
58
+ // tag, `manifest` wherever a person does. A declared value always wins, in either direction.
54
59
  const VERSION_SOURCES = Object.freeze(['manifest', 'tag']);
55
60
  // #441: the one route whose final may become automatic by an operator's grant, and the row it must
56
61
  // sit on — `deploy: tag` only. `deploy: manual` stays human: a person runs that deploy anyway.
57
62
  const GRANTABLE_ROUTE = 'deploy-tag';
58
63
  const GRANTABLE_ROW = 'released-tag';
64
+ // #446: the route that cuts a FINAL on every green trunk head — no candidate, no test period — and
65
+ // deploys it in the same run. It exists only on deploy: tag, only with the operator's recorded grant
66
+ // (the #441 reader, unchanged), and only where the repo declares a health-gated deploy that rolls
67
+ // itself back: those two declarations stand in for the test period it does not have. Its own keys —
68
+ // `health-url`, `rollback`, `final-spacing` — fit this route alone.
69
+ const FAST_ROUTE = 'deploy-tag-fast';
70
+ const GRANTABLE_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
71
+ const FAST_KEYS = Object.freeze(['health-url', 'rollback', 'final-spacing']);
72
+ // #452: `health-url` is the one verify key every deploy shares — #446's health gate and the container
73
+ // deploy template's verify step (templates/deploy-container.yml) read the same line. It is legal on
74
+ // both deploying-tag routes and required only on the fast one; `rollback` and `final-spacing` stay
75
+ // the fast route's alone.
76
+ const FAST_ONLY_KEYS = Object.freeze(['rollback', 'final-spacing']);
77
+ const HEALTH_URL_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
78
+ const ROLLBACK = Object.freeze(['auto']);
79
+ // The minimum spacing between two finals on deploy-tag-fast: both the default and the floor. A burst
80
+ // of merges then deploys at most once an hour; a repo may lengthen it, never shorten it.
81
+ const FINAL_SPACING_HOURS = 1;
59
82
  // #433: the npm opt-in. `npm` names the package directory release-auto.yml publishes (`.` for the
60
83
  // root); `npm-gate` the command that proves the tarball holds only what was meant to ship. They are
61
84
  // a pair — a publish with no gate is the stray-local-file leak the gate exists to stop — and they
@@ -84,7 +107,8 @@ const TEST_PERIOD_DAYS = 3;
84
107
  * finalize how a final is reached: 'none' (no tags), 'after-test-period' (each clean
85
108
  * candidate on its own clock), 'newest-clean' (the newest candidate clean for
86
109
  * the period; a newer candidate does not restart an older one's clock),
87
- * 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click'.
110
+ * 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click',
111
+ * 'on-green-head' (#446: `release cut --auto` tags the final itself; no candidate).
88
112
  */
89
113
  const ROUTE_POLICY = Object.freeze({
90
114
  'none': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'nothing consumes a tag here, so no tags are cut' }),
@@ -92,6 +116,7 @@ const ROUTE_POLICY = Object.freeze({
92
116
  'public-tool': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'auto', finalize: 'after-test-period', why: 'adopters install it and nothing deploys: every green trunk head gets a candidate, and the final tag is automatic after a clean test period' }),
93
117
  'library-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-tag', why: 'a library released per merge and pinned by its consumers: no candidates, the tag triggers the publish and the route\'s checks still apply' }),
94
118
  'deploy-tag': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'human-click', why: 'the tag deploys production, so the final tag is a human act' }),
119
+ 'deploy-tag-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-green-head', why: 'the operator granted a final on every green trunk head, deployed in the same run behind a health-gated deploy that rolls itself back' }),
95
120
  'live': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'the promotion is the deploy and stays human; no automatic tags' }),
96
121
  });
97
122
  const ROUTES = Object.freeze(Object.keys(ROUTE_POLICY));
@@ -105,7 +130,7 @@ const ROW_ROUTES = Object.freeze({
105
130
  'no-tags': Object.freeze(['none']),
106
131
  'live': Object.freeze(['live', 'none']),
107
132
  'released-no-production': Object.freeze(['public-tool', 'rapid-app', 'library-fast', 'none']),
108
- 'released-tag': Object.freeze(['deploy-tag', 'none']),
133
+ 'released-tag': Object.freeze(['deploy-tag', 'deploy-tag-fast', 'none']),
109
134
  'released-manual': Object.freeze(['deploy-tag', 'none']),
110
135
  'unmatched': Object.freeze(['none']),
111
136
  });
@@ -148,10 +173,51 @@ function deriveDefault(cfg) {
148
173
  };
149
174
  }
150
175
 
176
+ /**
177
+ * #484: the version-source a policy defaults to when `release.version-source` is not declared.
178
+ * `tag` wherever the machine cuts the tag — automatic candidates (rapid-app, public-tool,
179
+ * deploy-tag) or a final tagged by `release cut --auto` itself (deploy-tag-fast's on-green-head):
180
+ * the release workflow never pushes to trunk, so nobody is there to bump a manifest before each
181
+ * cut, and a `manifest` default refuses the first candidate after a final and every one after it.
182
+ * `manifest` everywhere a person cuts the tag (and can bump the file first). Read from the
183
+ * EFFECTIVE policy, so a `candidates: off` narrowing moves the default back to `manifest`.
184
+ */
185
+ function defaultVersionSource(p) {
186
+ return p && (p.candidates === 'auto' || p.finalize === 'on-green-head') ? 'tag' : 'manifest';
187
+ }
188
+
151
189
  /** A route's policy as an effective-shaped object (no `why`). */
152
190
  function routePolicy(route) {
153
191
  const p = ROUTE_POLICY[route];
154
- return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null } : null;
192
+ return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: defaultVersionSource(p), versionSourceDeclared: false, finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null } : null;
193
+ }
194
+
195
+ /** `6h` -> 6, `2d` -> 48; anything else (including `30m`, `0h`) -> null. */
196
+ function parseSpacing(v) {
197
+ const m = typeof v === 'string' ? /^([0-9]+)([hd])$/.exec(v.trim()) : null;
198
+ if (!m) return null;
199
+ const n = parseInt(m[1], 10) * (m[2] === 'd' ? 24 : 1);
200
+ return n > 0 ? n : null;
201
+ }
202
+
203
+ /** A health URL is an absolute https:// URL with a host. */
204
+ function validHealthUrl(v) {
205
+ if (typeof v !== 'string' || !/^https:\/\/[^\s/]+/.test(v.trim())) return false;
206
+ try { return new URL(v.trim()).protocol === 'https:'; } catch { return false; }
207
+ }
208
+
209
+ /**
210
+ * #446: what a declared `deploy-tag-fast` still lacks — the operator's grant, the health URL, the
211
+ * rollback declaration. Empty array = all three present (shape only; the grant's tracker state is
212
+ * finalGrantVerdict's).
213
+ */
214
+ function fastRoutePrerequisites(raw) {
215
+ const r = raw || {};
216
+ const missing = [];
217
+ if (parseGrantIssue(r['final-grant']) === null) missing.push("release.final-grant: <N> — the operator's recorded decision (colab decision <N> --record --ruled-by <human>)");
218
+ if (!validHealthUrl(r['health-url'])) missing.push('release.health-url: https://… — the public endpoint that reports the running version');
219
+ if (!ROLLBACK.includes(r.rollback)) missing.push('release.rollback: auto — the deploy rolls itself back when the health check fails');
220
+ return missing;
155
221
  }
156
222
 
157
223
  function parseTestPeriod(v) {
@@ -176,7 +242,8 @@ function evaluateRelease(cfg) {
176
242
  const fromDerived = () => ({
177
243
  route: derived.route, candidates: derived.candidates, candidatesPerDay: derived.candidatesPerDay,
178
244
  testPeriodDays: derived.testPeriodDays, final: derived.final, finalize: derived.finalize, npm: null,
179
- versionSource: 'manifest', finalGrant: null,
245
+ versionSource: defaultVersionSource(derived), versionSourceDeclared: false,
246
+ finalGrant: null, healthGate: null, healthUrl: null, finalSpacingHours: null,
180
247
  });
181
248
  let effective = fromDerived();
182
249
  const findings = [];
@@ -222,6 +289,11 @@ function evaluateRelease(cfg) {
222
289
  else if (!allowed.includes(v)) {
223
290
  fail(`release.route: ${v} does not fit ${derived.axis} — that descriptor permits ${allowed.join(' or ')} (${routes}). ` +
224
291
  'A route is chosen among the ones exposure + deploy permit; change those first if the repo really changed');
292
+ } else if (v === FAST_ROUTE && fastRoutePrerequisites(raw).length) {
293
+ // Fail closed: without its grant and its health gate the fast route would be an automatic,
294
+ // untested deploy nobody chose. The derived route (deploy-tag, human final) stays in effect.
295
+ fail(`release.route: ${FAST_ROUTE} needs the operator's grant and a declared health-gated deploy before it may stand — missing: ` +
296
+ `${fastRoutePrerequisites(raw).join('; ')} (${routes}). Until then the final stays a human act on route ${derived.route}`);
225
297
  } else {
226
298
  effective = routePolicy(v);
227
299
  why = ROUTE_POLICY[v].why;
@@ -259,8 +331,14 @@ function evaluateRelease(cfg) {
259
331
  if ('final-grant' in raw) {
260
332
  const n = parseGrantIssue(raw['final-grant']);
261
333
  if (n === null) fail(`release.final-grant is ${JSON.stringify(raw['final-grant'])}, expected the number of the decision issue that records the operator's ruling (e.g. 123 or "#123")`);
262
- else if (effective.route !== GRANTABLE_ROUTE || derived.row !== GRANTABLE_ROW) {
263
- fail(`release.final-grant fits only route ${GRANTABLE_ROUTE} on deploy: tag — ${route} on ${derived.axis} is not that (${routes}). ` +
334
+ else if (effective.route === FAST_ROUTE) {
335
+ // #446: the route itself is the automatic final, so the grant takes effect from this line alone.
336
+ grant = { issue: n };
337
+ effective.finalGrant = grant;
338
+ } else if (raw.route === FAST_ROUTE) {
339
+ // The route was refused above; its grant line is not a second finding.
340
+ } else if (effective.route !== GRANTABLE_ROUTE || derived.row !== GRANTABLE_ROW) {
341
+ fail(`release.final-grant fits only route ${GRANTABLE_ROUTE} on deploy: tag (or ${FAST_ROUTE}) — ${route} on ${derived.axis} is not that (${routes}). ` +
264
342
  (derived.row === 'released-manual' ? 'On deploy: manual a person runs the deploy anyway, so its final stays human' : 'Its final is not a deploying human act, so there is nothing to grant'));
265
343
  } else grant = { issue: n };
266
344
  }
@@ -268,7 +346,9 @@ function evaluateRelease(cfg) {
268
346
  if ('final' in raw) {
269
347
  const v = raw.final;
270
348
  if (!FINAL.includes(v)) fail(`release.final is ${JSON.stringify(v)}, expected "auto" or "human"`);
271
- else if (v === 'auto' && effective.final === 'human' && grant) {
349
+ else if (effective.route === FAST_ROUTE) {
350
+ if (v === 'human') fail(`release.final: human on route ${FAST_ROUTE} — that route has no candidate for a human to finalize; use route deploy-tag for a human final`);
351
+ } else if (v === 'auto' && effective.final === 'human' && grant) {
272
352
  // #441: an automatic final that deploys production — permitted only by the recorded grant.
273
353
  effective.final = 'auto';
274
354
  effective.finalize = 'after-test-period';
@@ -288,17 +368,44 @@ function evaluateRelease(cfg) {
288
368
  const v = raw['test-period'];
289
369
  const days = parseTestPeriod(v);
290
370
  if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
291
- else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} finalizes on the tag itself, with no candidate. Remove the key`);
371
+ else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
292
372
  else if (days < effective.testPeriodDays) {
293
373
  widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer`);
294
374
  } else effective.testPeriodDays = days;
295
375
  }
296
376
 
297
- // #438: where the tag's version comes from.
377
+ // #438: where the tag's version comes from. #484: the default follows the route as narrowed so
378
+ // far (a `candidates: off` narrowing hands the cut back to a person, and with it `manifest`);
379
+ // a valid declared value wins either way, an invalid one is a finding and leaves the default.
380
+ effective.versionSource = defaultVersionSource(effective);
298
381
  if ('version-source' in raw) {
299
382
  const v = raw['version-source'];
300
383
  if (!VERSION_SOURCES.includes(v)) fail(`release.version-source is ${JSON.stringify(v)}, expected "tag" or "manifest"`);
301
- else effective.versionSource = v;
384
+ else { effective.versionSource = v; effective.versionSourceDeclared = true; }
385
+ }
386
+
387
+ // #446: the fast route's own keys — only there, and the floor on spacing. #452: `health-url` is
388
+ // shared with deploy-tag, where it is optional and only names the version a deploy waits for.
389
+ const fastKeys = FAST_ONLY_KEYS.filter((k) => k in raw);
390
+ if ('health-url' in raw && effective.route === GRANTABLE_ROUTE) {
391
+ if (!validHealthUrl(raw['health-url'])) fail(`release.health-url is ${JSON.stringify(raw['health-url'])}, expected an absolute https:// URL that reports the running version`);
392
+ else effective.healthUrl = raw['health-url'].trim();
393
+ } else if ('health-url' in raw && effective.route !== FAST_ROUTE && raw.route !== FAST_ROUTE) {
394
+ fail(`release.health-url fits only route ${HEALTH_URL_ROUTES.join(' or ')} — ${route} on ${derived.axis} is not that (${routes}). ` +
395
+ 'Nothing deploys from a tag here, so there is no running version to check. Remove the key');
396
+ }
397
+ if (effective.route === FAST_ROUTE) {
398
+ effective.healthGate = { url: raw['health-url'].trim(), rollback: raw.rollback };
399
+ effective.healthUrl = raw['health-url'].trim();
400
+ effective.finalSpacingHours = FINAL_SPACING_HOURS;
401
+ if ('final-spacing' in raw) {
402
+ const h = parseSpacing(raw['final-spacing']);
403
+ if (h === null) fail(`release.final-spacing is ${JSON.stringify(raw['final-spacing'])}, expected hours or days like "${FINAL_SPACING_HOURS}h" or "1d"`);
404
+ else if (h < FINAL_SPACING_HOURS) widen('final-spacing', raw['final-spacing'], `finals are at least ${FINAL_SPACING_HOURS}h apart. Set ${FINAL_SPACING_HOURS}h or longer`);
405
+ else effective.finalSpacingHours = h;
406
+ }
407
+ } else if (fastKeys.length && raw.route !== FAST_ROUTE) {
408
+ fail(`release.${fastKeys.join(' / release.')} fits only route ${FAST_ROUTE} — ${route} on ${derived.axis} is not that (${routes}). Remove the key${fastKeys.length > 1 ? 's' : ''}`);
302
409
  }
303
410
 
304
411
  // 3. npm (#433) — only on a route where a tag publishes to adopters and deploys nothing.
@@ -333,7 +440,7 @@ function parseGrantIssue(v) {
333
440
  function finalGrantVerdict(record, { issue, trust } = {}) {
334
441
  const decisionRecord = require('./decision-record.js');
335
442
  const ref = `release.final-grant #${issue}`;
336
- if (!record) return { ok: false, ruledBy: null, detail: `${ref} could not be read from the tracker — an unread grant is not a grant` };
443
+ if (!record) return { ok: false, unread: true, ruledBy: null, detail: `${ref} could not be read from the tracker — an unread grant is not a grant` };
337
444
  const labels = (record.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
338
445
  const all = decisionRecord.liveDecisions(record.comments);
339
446
  const live = decisionRecord.trustedDecisions(record.comments, trust);
@@ -352,7 +459,8 @@ function finalGrantVerdict(record, { issue, trust } = {}) {
352
459
  }
353
460
 
354
461
  module.exports = {
355
- VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, parseGrantIssue, finalGrantVerdict,
462
+ VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, FAST_ONLY_KEYS, HEALTH_URL_ROUTES, ROLLBACK, FINAL_SPACING_HOURS,
463
+ parseGrantIssue, finalGrantVerdict, parseSpacing, validHealthUrl, fastRoutePrerequisites,
356
464
  KEYS, INPUT_KEYS, NPM_KEYS, NPM_ROUTES, CANDIDATES, FINAL, TEST_PERIOD_DAYS, ROUTES, ROUTE_POLICY, ROW_ROUTES,
357
- deriveDefault, evaluateRelease, parseTestPeriod, routePolicy,
465
+ deriveDefault, evaluateRelease, parseTestPeriod, routePolicy, defaultVersionSource,
358
466
  };
@@ -0,0 +1,125 @@
1
+ 'use strict';
2
+ /**
3
+ * The release workflow on a private repo runs on the repo's own runners (#453).
4
+ *
5
+ * On a PRIVATE (or internal) repository GitHub-hosted minutes are billed, and when the
6
+ * owner's billing fails GitHub refuses a hosted job before it starts. The release workflow
7
+ * (templates/release-auto.yml, or anything running `colab release cut|finalize --auto`) fires
8
+ * on every green trunk run, so a refused hosted job is a failed run at trunk's head — and
9
+ * `colab ship` reads that as "trunk not green" and refuses every landing until a human
10
+ * intervenes. Measured: two consecutive trunk-red events on one adopting repo, the release
11
+ * workflow being the only one on trunk still on hosted runners.
12
+ *
13
+ * The one job exempt is the one that publishes to npm: npm trusted publishing does not support
14
+ * self-hosted runners, and a private repo never publishes to public npm anyway (#432).
15
+ *
16
+ * Pure: takes a reader, the workflow list and the visibility the caller read from the forge
17
+ * (never a local guess). Unknown visibility → no finding (under-report, never invent).
18
+ *
19
+ * jobRunners(text) -> [{ job, runsOn, line, hosted, publishesNpm }]
20
+ * findings(...) -> string[] advisories, one per offending job
21
+ */
22
+
23
+ const RELEASE_AUTO_RUN = /\brelease\s+(cut|finalize)\s+--auto\b/;
24
+ const HOSTED_LABEL = /^(ubuntu|windows|macos)-[\w.-]+$/i;
25
+ const NPM_PUBLISH = /(^|[\s;&|(])(npm|pnpm|bun|yarn(\s+npm)?)\s+publish\b/;
26
+
27
+ function stripComment(line) {
28
+ return line.replace(/(^|\s)#.*$/, '');
29
+ }
30
+
31
+ function unquote(s) {
32
+ return s.trim().replace(/^['"]|['"]$/g, '');
33
+ }
34
+
35
+ /**
36
+ * The labels a `runs-on:` value names, or null when it cannot be read statically
37
+ * (an expression, a `group:` mapping, nothing at all).
38
+ */
39
+ function labelsOf(value, following) {
40
+ const v = stripComment(value).trim();
41
+ if (v.includes('${{')) return null;
42
+ if (v.startsWith('[')) {
43
+ return v.replace(/^\[|\]$/g, '').split(',').map(unquote).filter(Boolean);
44
+ }
45
+ if (v) return [unquote(v)];
46
+ // Block list on the following lines: `- label`.
47
+ const out = [];
48
+ for (const raw of following) {
49
+ const l = stripComment(raw);
50
+ if (!l.trim()) continue;
51
+ const m = l.match(/^\s+-\s+(.+)$/);
52
+ if (!m) break;
53
+ if (m[1].includes('${{')) return null;
54
+ out.push(unquote(m[1]));
55
+ }
56
+ return out.length ? out : null;
57
+ }
58
+
59
+ /** Every job's `runs-on`, by a line scan of the `jobs:` mapping (2-space job keys). */
60
+ function jobRunners(text) {
61
+ const lines = String(text || '').split('\n');
62
+ const out = [];
63
+ let inJobs = false;
64
+ let current = null;
65
+ const flush = () => { if (current) out.push(current); current = null; };
66
+ lines.forEach((raw, i) => {
67
+ if (/^jobs:\s*(#.*)?$/.test(raw)) { inJobs = true; return; }
68
+ if (!inJobs) return;
69
+ if (/^\S/.test(raw) && !/^#/.test(raw)) { flush(); inJobs = false; return; }
70
+ const key = raw.match(/^ {2}([A-Za-z0-9_-]+):\s*(#.*)?$/);
71
+ if (key) { flush(); current = { job: key[1], runsOn: null, line: null, hosted: false, publishesNpm: false }; return; }
72
+ if (!current) return;
73
+ if (NPM_PUBLISH.test(stripComment(raw))) current.publishesNpm = true;
74
+ const ro = raw.match(/^ {4}runs-on:(.*)$/);
75
+ if (ro) {
76
+ const labels = labelsOf(ro[1], lines.slice(i + 1));
77
+ current.runsOn = labels;
78
+ current.line = i + 1;
79
+ current.hosted = !!(labels && labels.length && labels.every((l) => HOSTED_LABEL.test(l)));
80
+ }
81
+ });
82
+ flush();
83
+ return out;
84
+ }
85
+
86
+ /** The first statically-readable self-hosted `runs-on` in the repo's other workflows, as written. */
87
+ function selfHostedLabel(workflows, readFile, except) {
88
+ for (const wf of workflows || []) {
89
+ if (wf === except) continue;
90
+ const text = readFile(`.github/workflows/${wf}`);
91
+ if (!text) continue;
92
+ for (const j of jobRunners(text)) {
93
+ if (j.runsOn && j.runsOn.some((l) => l === 'self-hosted')) {
94
+ return { wf, labels: j.runsOn };
95
+ }
96
+ }
97
+ }
98
+ return null;
99
+ }
100
+
101
+ function isPrivate(visibility) {
102
+ const v = visibility ? String(visibility).toLowerCase() : null;
103
+ return v === 'private' || v === 'internal';
104
+ }
105
+
106
+ function findings({ readFile, workflows, visibility }) {
107
+ if (!isPrivate(visibility)) return [];
108
+ const out = [];
109
+ for (const wf of workflows || []) {
110
+ const text = readFile(`.github/workflows/${wf}`);
111
+ if (!text || !RELEASE_AUTO_RUN.test(text)) continue;
112
+ const hosted = jobRunners(text).filter((j) => j.hosted && !j.publishesNpm);
113
+ if (!hosted.length) continue;
114
+ const own = selfHostedLabel(workflows, readFile, wf);
115
+ const hint = own
116
+ ? `use the label your ${own.wf} already runs on: runs-on: [${own.labels.join(', ')}]`
117
+ : 'use your self-hosted trunk runner label';
118
+ for (const j of hosted) {
119
+ out.push(`${wf} job \`${j.job}\` runs on GitHub-hosted (${j.runsOn.join(', ')}, line ${j.line}) on a ${String(visibility).toLowerCase()} repo — hosted minutes are billed here, and a billing refusal fails this run at trunk's head, which turns trunk red for \`colab ship\`; ${hint} (templates/release-auto.yml, RUNNERS)`);
120
+ }
121
+ }
122
+ return out;
123
+ }
124
+
125
+ module.exports = { jobRunners, selfHostedLabel, findings, isPrivate, RELEASE_AUTO_RUN };
@@ -156,7 +156,9 @@ function manifestVersions(readFile) {
156
156
  * checkout cannot answer (null = not measured)
157
157
  * tags every tag name in the repo — the finals among them are what the version must outrank
158
158
  * trunk the trunk name, for the detail text
159
- * versionSource #438 — 'manifest' (default): every declared manifest must equal the tag. 'tag'
159
+ * versionSource #438 — 'manifest' (this function's default; the policy's own default is per
160
+ * route since #484 — release-policy.js defaultVersionSource): every declared manifest
161
+ * must equal the tag. 'tag'
160
162
  * (`release.version-source: tag`): the manifests are DERIVABLE — the repo's own
161
163
  * release/deploy step stamps them from the tag, never on trunk — so a manifest that
162
164
  * differs is skipped and named, not refused. A manifest that cannot be read at all
@@ -0,0 +1,106 @@
1
+ 'use strict';
2
+ /**
3
+ * #488: where a session's scratch lives — the plan file (`code-start` / `code-plan` write it,
4
+ * `code-wrap` / `code-ship` read and delete it) and dispatch briefs.
5
+ *
6
+ * Both used to be literals under `.claude/` (`.claude/plans/`, `.claude/briefs/`). The agent CLI
7
+ * guards `.claude/` as configuration, so every scratch write there could cost the operator a
8
+ * permission prompt — for a file that is disposable by definition. Defaults now sit outside it:
9
+ *
10
+ * plans `<main checkout>/.plans/` overridable by COLAB_PLANS_DIR
11
+ * briefs `<main checkout>/.briefs/` overridable by COLAB_BRIEFS_DIR
12
+ *
13
+ * A configured value is relative to the repo root, or absolute. Writers use ONLY the configured
14
+ * dir. Readers use the configured dir first, then the legacy `.claude/plans/` — one transition,
15
+ * so a plan written before the switch is still graded, journalled and deleted. Old files are never
16
+ * moved.
17
+ *
18
+ * Everything here is pure (env + strings in, strings out); tools/colab does the IO.
19
+ */
20
+
21
+ const path = require('path');
22
+
23
+ const DEFAULT_PLANS_DIR = '.plans';
24
+ const DEFAULT_BRIEFS_DIR = '.briefs';
25
+ /** Read-only fallbacks for the transition (#488). Never written to by anything that follows #488. */
26
+ const LEGACY_PLANS_DIR = '.claude/plans';
27
+ const LEGACY_BRIEFS_DIR = '.claude/briefs';
28
+
29
+ /** A configured dir, normalised: trimmed, forward slashes, no trailing slash; blank → the default. */
30
+ function normalise(value, dflt) {
31
+ const v = String(value === undefined || value === null ? '' : value).trim().replace(/\\/g, '/');
32
+ if (!v) return dflt;
33
+ if (v === '/') return dflt; // the filesystem root is never a scratch dir — treat as unset
34
+ return v.replace(/\/+$/, '') || dflt;
35
+ }
36
+
37
+ /** The plans dir as configured — relative to the repo root unless absolute. */
38
+ function plansDirSetting(env = process.env) { return normalise(env.COLAB_PLANS_DIR, DEFAULT_PLANS_DIR); }
39
+ /** The briefs dir as configured — relative to the repo root unless absolute. */
40
+ function briefsDirSetting(env = process.env) { return normalise(env.COLAB_BRIEFS_DIR, DEFAULT_BRIEFS_DIR); }
41
+
42
+ function resolveIn(repoRoot, rel) { return path.isAbsolute(rel) ? rel : path.join(repoRoot, rel); }
43
+
44
+ /** Absolute dir a writer puts a plan file in. Never the legacy dir (unless configured to it). */
45
+ function planWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, plansDirSetting(env)); }
46
+
47
+ /** Absolute dir a writer puts a brief in. */
48
+ function briefsWriteDir(repoRoot, env = process.env) { return resolveIn(repoRoot, briefsDirSetting(env)); }
49
+
50
+ /** Absolute dirs a reader looks in, in order: configured first, then legacy. Deduplicated. */
51
+ function planReadDirs(repoRoot, env = process.env) {
52
+ const out = [];
53
+ for (const d of [planWriteDir(repoRoot, env), resolveIn(repoRoot, LEGACY_PLANS_DIR)]) {
54
+ if (!out.includes(d)) out.push(d);
55
+ }
56
+ return out;
57
+ }
58
+
59
+ /**
60
+ * A configured dir that is relative and stays inside the repo, as a root-anchored exclude line
61
+ * (`/.plans/`) — or null for an absolute dir or one that climbs out (`../x`), which no repo-local
62
+ * ignore file can or needs to hide.
63
+ */
64
+ function anchoredLine(rel) {
65
+ if (path.isAbsolute(rel)) return null;
66
+ const n = path.posix.normalize(rel);
67
+ if (n === '.' || n.startsWith('../') || n === '..') return null;
68
+ return `/${n.replace(/^\.\//, '')}/`;
69
+ }
70
+
71
+ /**
72
+ * Root-anchored `.git/info/exclude` lines for every scratch dir — configured plans, configured
73
+ * briefs, and the legacy `.claude/plans/` (kept: a clone may still hold pre-#488 files).
74
+ */
75
+ function excludeLines(env = process.env) {
76
+ const out = [];
77
+ for (const rel of [plansDirSetting(env), briefsDirSetting(env), LEGACY_PLANS_DIR]) {
78
+ const line = anchoredLine(rel);
79
+ if (line && !out.includes(line)) out.push(line);
80
+ }
81
+ return out;
82
+ }
83
+
84
+ /**
85
+ * Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
86
+ * keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
87
+ * by definition, and must never be what makes a teardown refuse (#488).
88
+ */
89
+ function isScratchPath(relPath, env = process.env) {
90
+ const p = String(relPath || '').replace(/^"|"$/g, '').replace(/\\/g, '/').replace(/^\.\//, '');
91
+ return excludeLines(env).some((line) => p.startsWith(line.slice(1)));
92
+ }
93
+
94
+ /** Drop porcelain lines (`?? path`, ` M path`) whose path is scratch. Text in, text out. */
95
+ function withoutScratch(porcelainText, env = process.env) {
96
+ if (!porcelainText) return porcelainText;
97
+ return String(porcelainText).split('\n')
98
+ .filter((l) => l && !isScratchPath(l.slice(3), env))
99
+ .join('\n');
100
+ }
101
+
102
+ module.exports = {
103
+ DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
104
+ plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
105
+ excludeLines, isScratchPath, withoutScratch,
106
+ };
@@ -179,6 +179,9 @@ function wiring(fires) {
179
179
  * databaseId}`). Same all-runs rule as summarizeRunsForCommit: any finished not-green row (cancelled
180
180
  * aside) makes it red; any unfinished row keeps it pending; green needs every row finished and at
181
181
  * least one success. `attempt` is the highest run attempt seen — how many times it was re-run.
182
+ * Unlike summarizeRunsForCommit it does NOT reduce to the newest run per workflow (#461): a batch
183
+ * ref is built fresh and re-run in place (same run, higher `attempt`), so it carries no superseded
184
+ * attempts of a workflow for that reduction to set aside.
182
185
  */
183
186
  function combinedVerdict(rows) {
184
187
  const list = Array.isArray(rows) ? rows : null;
@@ -279,9 +282,41 @@ function serialLine(branches) {
279
282
  return `→ SERIAL: ${list.map((b) => `colab ship --branch ${b}`).join(' · ') || '(no members)'}`;
280
283
  }
281
284
 
285
+ /**
286
+ * #509: WHY the land step's fast-forward push failed — asked before anything is reported. The push
287
+ * is the atomic "trunk has not moved" check, but a failed push is not proof trunk moved: a local
288
+ * `pre-push` hook can refuse it, and a remote can reject it for reasons of its own (protection, a
289
+ * pre-receive hook). Reporting those as "trunk moved — run again" sent an unattended caller into a
290
+ * retry loop against a deterministic refusal, under the exit code a scheduler reads as a pause.
291
+ *
292
+ * Facts in: the push's stderr, the remote trunk sha re-read AFTER the failure (null = could not
293
+ * read), and `base` — the trunk sha the batch was built on. Decision out:
294
+ *
295
+ * trunk-moved the remote trunk is no longer `base` — the existing pause-and-rebuild (exit 3)
296
+ * unreachable the remote could not be re-read — nothing is provable; a pause (exit 3), with
297
+ * the push's own output, never the "trunk moved" claim
298
+ * remote-rejected trunk did not move and the remote refused the update ("[remote rejected]") —
299
+ * deterministic until a human acts: exit 1, no "run again"
300
+ * push-refused trunk did not move and the remote said nothing — the push never reached it,
301
+ * which is what a refusing local `pre-push` hook looks like: exit 1, no "run again"
302
+ *
303
+ * `lines` is the push's stderr trimmed to its first `max` non-empty lines, minus git's generic
304
+ * "failed to push some refs" trailer — the hook's or the remote's own words are the diagnosis.
305
+ */
306
+ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
307
+ const all = String(stderr || '').split('\n').map((l) => l.replace(/\s+$/, '')).filter((l) => l.trim());
308
+ const telling = all.filter((l) => !/^error: failed to push some refs to /.test(l));
309
+ const lines = (telling.length ? telling : all).slice(0, max);
310
+ const now = remoteNow ? String(remoteNow).trim() : '';
311
+ if (!now) return { kind: 'unreachable', exit: 3, lines };
312
+ if (!base || now !== String(base).trim()) return { kind: 'trunk-moved', exit: 3, lines };
313
+ if (all.some((l) => /\[remote rejected\]/.test(l))) return { kind: 'remote-rejected', exit: 1, lines };
314
+ return { kind: 'push-refused', exit: 1, lines };
315
+ }
316
+
282
317
  module.exports = {
283
318
  MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
284
319
  parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
285
320
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
286
- batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged,
321
+ batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
287
322
  };
@@ -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