@futurelastic/colab-handbook 1.13.0-rc.23 → 1.13.0-rc.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -1304,6 +1304,17 @@ function auditRepo(target, ctx) {
1304
1304
  }
1305
1305
  }
1306
1306
 
1307
+ // ---- ship-batch-wait (#555) -------------------------------------------------
1308
+ // How long a lone ready candidate waits for a partner (tools/lib/ship-batch.js parseShipBatchWait,
1309
+ // the reading `colab ship --batch` uses). Malformed fails here and in the CI templates' descriptor
1310
+ // check, the #416 pattern — ship fails closed to no wait, silently. A window with no batch to fill
1311
+ // (ship-batch absent or 1) is inert, so it warns. No ceiling: the repo chooses the value.
1312
+ if ("ship-batch-wait" in (cfg || {}) && cfg["ship-batch-wait"] !== null) {
1313
+ const wCfg = shipBatch.parseShipBatchWait(cfg);
1314
+ if (!wCfg.valid) fail(`${wCfg.reason} — see project.schema.md, ship-batch-wait`);
1315
+ else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1316
+ }
1317
+
1307
1318
  // ---- migrations (#383) ----------------------------------------------------
1308
1319
  // Where the repo's migrations live, beyond the two defaults (database/migrations/,
1309
1320
  // prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.23"
36
+ "version": "1.13.0-rc.24"
37
37
  }
@@ -263,23 +263,39 @@ jobs:
263
263
  # green; only a ship dry run noticed. So the value fails HERE, where the person
264
264
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
265
265
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
266
- # cap is 3: project.schema.md, `ship-batch`.
266
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
267
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
267
268
  # ---------------------------------------------------------------------------
268
269
  - name: Descriptor check (.github/project.yml)
269
270
  working-directory: ${{ github.workspace }}
270
271
  run: |
271
272
  [ -f .github/project.yml ] || exit 0
272
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
273
- [ -n "$line" ] || exit 0
274
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
273
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
274
+ field() {
275
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
276
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
275
277
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
276
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
278
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
279
+ }
280
+ v="$(field ship-batch)"
277
281
  case "$v" in
278
282
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
279
283
  *)
280
284
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
281
285
  exit 1 ;;
282
286
  esac
287
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
288
+ w="$(field ship-batch-wait)"
289
+ case "$w" in
290
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
291
+ *)
292
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
293
+ echo "ship-batch-wait: $w — ok"
294
+ else
295
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
296
+ exit 1
297
+ fi ;;
298
+ esac
283
299
 
284
300
  # ---------------------------------------------------------------------------
285
301
  # Toolchain resolution. Precedence, highest first:
@@ -13,7 +13,8 @@
13
13
  # `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
14
14
  #
15
15
  # What it does:
16
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
16
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
17
+ # ship-batch-wait, #555).
17
18
  # 1. Resolve the Node version from declared sources — never a hardcoded default.
18
19
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
19
20
  # 3. Install dependencies with the package manager the lockfile implies.
@@ -257,23 +258,39 @@ jobs:
257
258
  # green; only a ship dry run noticed. So the value fails HERE, where the person
258
259
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
259
260
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
260
- # cap is 3: project.schema.md, `ship-batch`.
261
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
262
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
261
263
  # ---------------------------------------------------------------------------
262
264
  - name: Descriptor check (.github/project.yml)
263
265
  working-directory: ${{ github.workspace }}
264
266
  run: |
265
267
  [ -f .github/project.yml ] || exit 0
266
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
267
- [ -n "$line" ] || exit 0
268
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
268
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
269
+ field() {
270
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
271
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
269
272
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
270
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
273
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
274
+ }
275
+ v="$(field ship-batch)"
271
276
  case "$v" in
272
277
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
273
278
  *)
274
279
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
275
280
  exit 1 ;;
276
281
  esac
282
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
283
+ w="$(field ship-batch-wait)"
284
+ case "$w" in
285
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
286
+ *)
287
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
288
+ echo "ship-batch-wait: $w — ok"
289
+ else
290
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
291
+ exit 1
292
+ fi ;;
293
+ esac
277
294
 
278
295
  # ---------------------------------------------------------------------------
279
296
  # Toolchain resolution. Precedence, highest first:
@@ -27,7 +27,8 @@
27
27
  # NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
28
28
  #
29
29
  # What it does:
30
- # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
30
+ # 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
31
+ # ship-batch-wait, #555).
31
32
  # 1. Resolve the Python version from declared sources — never a hardcoded default.
32
33
  # 2. Secret scan with gitleaks (pinned release binary, see note at the step).
33
34
  # 3. Install dependencies from whichever manifest the repo actually has.
@@ -248,23 +249,39 @@ jobs:
248
249
  # green; only a ship dry run noticed. So the value fails HERE, where the person
249
250
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
250
251
  # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
251
- # cap is 3: project.schema.md, `ship-batch`.
252
+ # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
253
+ # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
252
254
  # ---------------------------------------------------------------------------
253
255
  - name: Descriptor check (.github/project.yml)
254
256
  working-directory: ${{ github.workspace }}
255
257
  run: |
256
258
  [ -f .github/project.yml ] || exit 0
257
- line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
258
- [ -n "$line" ] || exit 0
259
- v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
259
+ # The scalar after `<key>:` — comment, trailing blanks and one level of quotes stripped.
260
+ field() {
261
+ grep -E "^$1[[:space:]]*:" .github/project.yml | head -1 \
262
+ | sed -E -e "s/^$1[[:space:]]*:[[:space:]]*//" \
260
263
  -e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
261
- -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
264
+ -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/" || true
265
+ }
266
+ v="$(field ship-batch)"
262
267
  case "$v" in
263
268
  ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
264
269
  *)
265
270
  echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
266
271
  exit 1 ;;
267
272
  esac
273
+ # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
274
+ w="$(field ship-batch-wait)"
275
+ case "$w" in
276
+ ''|'~'|null) echo "ship-batch-wait: absent — ok" ;;
277
+ *)
278
+ if printf '%s\n' "$w" | grep -Eq '^[0-9]+[smh]$'; then
279
+ echo "ship-batch-wait: $w — ok"
280
+ else
281
+ echo "::error file=.github/project.yml::ship-batch-wait is '$w', expected a whole number with a unit: 90s, 6m, 1h (omit for no wait). colab ship ignores any other value and does not wait."
282
+ exit 1
283
+ fi ;;
284
+ esac
268
285
 
269
286
  # ---------------------------------------------------------------------------
270
287
  # Toolchain resolution. Precedence, highest first:
package/tools/colab CHANGED
@@ -10351,6 +10351,12 @@ at build, added since) is NOT landed with it — the command names both lists an
10351
10351
  --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
10352
10352
  locally and printed; a staged green batch prints what would land (members, combined run, target sha).
10353
10353
  Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
10354
+ PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
10355
+ unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10356
+ ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10357
+ since the member became ready (its head CI's last update, else its head commit's date) — then the same
10358
+ call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10359
+ --batch with all of them. A single named branch is accepted only when the field is set.
10354
10360
 
10355
10361
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10356
10362
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -13909,7 +13915,10 @@ function cmdShipBatch(opts) {
13909
13915
  if (String(doc.autonomy || '') !== 'auto-trunk') {
13910
13916
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
13911
13917
  }
13912
- if (members.length < 2) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
13918
+ // #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
13919
+ const waitCfg = shipBatch.parseShipBatchWait(doc);
13920
+ if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
13921
+ if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
13913
13922
  if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
13914
13923
 
13915
13924
  const remote = git.remoteFor(repoAbs);
@@ -14048,6 +14057,22 @@ function cmdShipBatch(opts) {
14048
14057
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14049
14058
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14050
14059
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14060
+ if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14061
+ // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14062
+ // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14063
+ const lone = selected[0];
14064
+ const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
14065
+ const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
14066
+ const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
14067
+ if (pw.wait) {
14068
+ print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
14069
+ print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14070
+ print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
14071
+ return 3;
14072
+ }
14073
+ const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
14074
+ return serial(`1 member can join and no partner arrived — ${why}`);
14075
+ }
14051
14076
  if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
14052
14077
 
14053
14078
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
@@ -94,6 +94,8 @@ function restRow(x) {
94
94
  return {
95
95
  headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
96
96
  createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
97
+ // #555: a finished run's last update is its completion — when a lone batch member became ready.
98
+ updatedAt: x.updated_at || null,
97
99
  event: x.event || null, url: x.html_url || null,
98
100
  // #510: the workflow FILE's id — the cure rule's same-workflow test, which a display name cannot answer.
99
101
  workflowId: x.workflow_id ?? null,
package/tools/lib/git.js CHANGED
@@ -960,7 +960,8 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
960
960
  // does not own) before it computes a verdict, and can only do that if the row says so.
961
961
  // workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
962
962
  // id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
963
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
963
+ // updatedAt is additive (#555): a finished run's completion time, the lone-member wait's anchor.
964
+ '--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
964
965
  if (!r.ok) return null;
965
966
  let runs;
966
967
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -46,6 +46,70 @@ function parseShipBatch(doc) {
46
46
  return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
47
47
  }
48
48
 
49
+ const WAIT_KEY = 'ship-batch-wait';
50
+ const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
+
52
+ /**
53
+ * #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
54
+ * before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
55
+ * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
+ *
57
+ * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
58
+ * (owner, 2026-10-07: "Should not set any hard code number") — the repo chooses, from its own
59
+ * history. Anything malformed FAILS CLOSED to no wait, with the reason: a bad value must never delay
60
+ * a landing. The audit and the CI templates' descriptor check fail the same values.
61
+ */
62
+ function parseShipBatchWait(doc) {
63
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, WAIT_KEY);
64
+ if (!has || doc[WAIT_KEY] === null || doc[WAIT_KEY] === undefined) {
65
+ return { sec: 0, declared: false, valid: true, reason: `${WAIT_KEY} absent` };
66
+ }
67
+ const v = doc[WAIT_KEY];
68
+ const m = typeof v === 'string' ? /^(\d+)([smh])$/.exec(v.trim()) : null;
69
+ if (m) {
70
+ const sec = Number(m[1]) * WAIT_UNITS[m[2]];
71
+ if (Number.isSafeInteger(sec)) return { sec, declared: true, valid: true, reason: `${WAIT_KEY}: ${v.trim()}` };
72
+ }
73
+ return { sec: 0, declared: true, valid: false, reason: `${WAIT_KEY} is ${JSON.stringify(v)}, expected a whole number with a unit — 90s, 6m, 1h (omit for no wait)` };
74
+ }
75
+
76
+ /**
77
+ * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
78
+ * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
+ * already in flight — the lane is otherwise idle by then):
80
+ * n parseShipBatch(doc).n
81
+ * waitSec parseShipBatchWait(doc).sec (0 = absent, zero, or malformed)
82
+ * eligibleCount members that passed their own gates
83
+ * readySinceMs when the lone member became ready — its head CI's last update, else its head
84
+ * commit's date; null = unreadable
85
+ * nowMs the clock
86
+ * Out: `{ wait: true, leftSec }` or `{ wait: false, reason }`. The window is counted from the member's
87
+ * own ready time, not from this call, so the command stays stateless and re-entrant: every call
88
+ * re-derives how much is left, on any machine, and the window can never restart.
89
+ */
90
+ function partnerWait({ n, waitSec, eligibleCount, readySinceMs, nowMs }) {
91
+ if (!(n > 1)) return { wait: false, reason: 'not-enabled' };
92
+ if (!(waitSec > 0)) return { wait: false, reason: 'no-window' };
93
+ if (eligibleCount !== 1) return { wait: false, reason: eligibleCount > 1 ? 'has-partner' : 'none-ready' };
94
+ if (!Number.isFinite(readySinceMs) || !Number.isFinite(nowMs)) return { wait: false, reason: 'ready-time-unread' };
95
+ const leftSec = Math.ceil(waitSec - Math.max(0, nowMs - readySinceMs) / 1000);
96
+ if (leftSec <= 0) return { wait: false, reason: 'window-elapsed' };
97
+ return { wait: true, leftSec };
98
+ }
99
+
100
+ /**
101
+ * When did a member become ready? The newest `updatedAt` among its finished head runs (a run's last
102
+ * update is its completion), else — no run, because none can arrive — its head commit's date.
103
+ * Null when neither reads; the caller then does not wait.
104
+ */
105
+ function readySince(rows, commitIso) {
106
+ const done = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
107
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
108
+ if (done.length) return Math.max(...done);
109
+ const c = Date.parse(commitIso || '');
110
+ return Number.isFinite(c) ? c : null;
111
+ }
112
+
49
113
  function batchRefName(baseSha) {
50
114
  return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
51
115
  }
@@ -315,8 +379,8 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
315
379
  }
316
380
 
317
381
  module.exports = {
318
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
319
- parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
382
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY,
383
+ parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
320
384
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
321
385
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
322
386
  };