@futurelastic/colab-handbook 1.13.0-rc.48 → 1.13.0-rc.49

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.48"
36
+ "version": "1.13.0-rc.49"
37
37
  }
package/tools/colab CHANGED
@@ -10537,7 +10537,9 @@ work as usual (json: \`direct: true\`, \`branch: null\`, \`mode: "evidence-close
10537
10537
 
10538
10538
  BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–3;
10539
10539
  absent or 1 declines every --batch call. It tests up to N green candidates as ONE combined head, then
10540
- fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle:
10540
+ fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle.
10541
+ A batch of ONE is valid (#562): a lone ready member lands the same way, so the combined run — the
10542
+ setups a repo runs only on ship-batch/** and trunk — gates it too, and it needs no sync + re-run:
10541
10543
  - each member must be green at its OWN head (or have no run that could ever arrive), pass every
10542
10544
  gate its own \`ship --dry --json\` reports, and be an ordinary squash into trunk through the
10543
10545
  auto-trunk grant — the docs-only door, a migration, a ci-grant/cure, a core-path review, an
@@ -10555,8 +10557,8 @@ It never waits: each call reads the remote, takes ONE step and exits —
10555
10557
  it, bounded (code-ship B1a), and run the SAME command again
10556
10558
  4 declined — nothing landed; the last line is "→ SERIAL: colab ship --branch <b1> · …". Causes:
10557
10559
  not enabled, no auto-trunk, no workflow fires on ship-batch/** (the run could never arrive),
10558
- trunk CI red (the cure/grant doors apply per member, never to a batch), fewer than two members
10559
- can join, or the combined run is red — classify it: red:infra → the printed \`gh run rerun\`,
10560
+ trunk CI red (the cure/grant doors apply per member, never to a batch), no member can join,
10561
+ or the combined run is red — classify it: red:infra → the printed \`gh run rerun\`,
10560
10562
  once; red:finding, or red again after that one re-run → serial
10561
10563
  1 refused (a broken checkout, an unreadable remote) — or the land push was refused while trunk did
10562
10564
  NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
@@ -10577,8 +10579,8 @@ PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in proj
10577
10579
  unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10578
10580
  ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10579
10581
  since the member became ready (its head CI's last update, else its head commit's date) — then the same
10580
- call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10581
- --batch with all of them. A single named branch is accepted only when the field is set.
10582
+ call builds it as a batch of one (#562). The caller waits, gathers every ready candidate again and
10583
+ calls --batch with all of them. Without the field, a lone member is built at once.
10582
10584
 
10583
10585
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10584
10586
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -14286,10 +14288,11 @@ function cmdShipBatch(opts) {
14286
14288
  if (String(doc.autonomy || '') !== 'auto-trunk') {
14287
14289
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
14288
14290
  }
14289
- // #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
14291
+ // #555: a declared ship-batch-wait makes a lone member wait for a partner below.
14292
+ // #562: one named member is a valid batch — it lands through the combined run, never serially.
14290
14293
  const waitCfg = shipBatch.parseShipBatchWait(doc);
14291
14294
  if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
14292
- if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
14295
+ if (members.length < 1) return serial('--batch names no branch — name every ready candidate');
14293
14296
  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`);
14294
14297
 
14295
14298
  const remote = git.remoteFor(repoAbs);
@@ -14355,7 +14358,7 @@ function cmdShipBatch(opts) {
14355
14358
  }
14356
14359
  if (!foreignStep) {
14357
14360
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
14358
- const matches = heads.length >= 2 && heads.every((m) => m.now && m.now.startsWith(m.sha));
14361
+ const matches = heads.length >= 1 && heads.every((m) => m.now && m.now.startsWith(m.sha));
14359
14362
  existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
14360
14363
  // #415: the command line and the staged batch can name different sets. A requested branch the
14361
14364
  // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
@@ -14368,7 +14371,7 @@ function cmdShipBatch(opts) {
14368
14371
  }
14369
14372
  }
14370
14373
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14371
- let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: 2, existing, trunkNow, verdict });
14374
+ let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict });
14372
14375
 
14373
14376
  if (step.step === 'rebuild') {
14374
14377
  print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
@@ -14428,7 +14431,7 @@ function cmdShipBatch(opts) {
14428
14431
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14429
14432
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14430
14433
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14431
- if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14434
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0) {
14432
14435
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14433
14436
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14434
14437
  const lone = selected[0];
@@ -14438,13 +14441,13 @@ function cmdShipBatch(opts) {
14438
14441
  if (pw.wait) {
14439
14442
  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.`);
14440
14443
  print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14441
- print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
14444
+ print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone, as a batch of one.');
14442
14445
  return 3;
14443
14446
  }
14444
14447
  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;
14445
- return serial(`1 member can join and no partner arrived — ${why}`);
14448
+ print(` no partner arrived for ${lone.branch} — ${why}; building a batch of one (the combined run still gates it, #562)`);
14446
14449
  }
14447
- if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
14450
+ if (step.step === 'serial') return serial('no member can join — each one above says why');
14448
14451
 
14449
14452
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14450
14453
  const ref = shipBatch.batchRefName(trunkNow);
@@ -14519,8 +14522,8 @@ function cmdShipBatch(opts) {
14519
14522
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
14520
14523
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14521
14524
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14522
- // Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
14523
- if (dropped.length && built.length >= 2) {
14525
+ // Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
14526
+ if (dropped.length && built.length >= 1) {
14524
14527
  const last = built[built.length - 1];
14525
14528
  const cur = git.git(['log', '-1', '--format=%B'], dir);
14526
14529
  const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
@@ -14532,9 +14535,9 @@ function cmdShipBatch(opts) {
14532
14535
  print(` ↻ ${b.branch}: combined despite a generated-file overlap — ${b.regenerated.join(', ')} regenerated by .colab/hooks/pre-ship on the combined head (the combined run is the gate)`);
14533
14536
  }
14534
14537
  const head = git.git(['rev-parse', 'HEAD'], dir).stdout;
14535
- if (built.length < 2) {
14538
+ if (built.length < 1) {
14536
14539
  cleanup();
14537
- return serial(`${built.length} member(s) survived the build — a batch needs at least two`, members);
14540
+ return serial('no member survived the build', members);
14538
14541
  }
14539
14542
  if (opts.dry) {
14540
14543
  cleanup();
@@ -51,7 +51,7 @@ const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
51
 
52
52
  /**
53
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
54
+ * before it lands alone (as a batch of one, #562). A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
55
55
  * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
56
  *
57
57
  * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
@@ -74,7 +74,8 @@ function parseShipBatchWait(doc) {
74
74
  }
75
75
 
76
76
  /**
77
- * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
77
+ * #555: does a batch call with ONE eligible member wait for a partner, or build now? (Past the window
78
+ * it lands alone — through the batch path, as a batch of one, #562 — never serially.)
78
79
  * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
80
  * already in flight — the lane is otherwise idle by then):
80
81
  * n parseShipBatch(doc).n
@@ -305,7 +306,8 @@ function combinedVerdict(rows) {
305
306
  /**
306
307
  * The one decision per `colab ship --batch` call. The command is RE-ENTRANT: it reads remote state,
307
308
  * takes one step, and exits — the caller waits (bounded, code-ship B1a) and calls again.
308
- * serial(reason) land nothing; hand the members back as a serial list (exit 4)
309
+ * serial(reason) land nothing; hand the members back as a serial list (exit 4) — never for
310
+ * a lone ready member: one member is a valid batch (#562)
309
311
  * wait-trunk trunk's own run is still in flight (exit 3)
310
312
  * rebuild a batch ref exists on a base trunk has moved past, or its members/heads are
311
313
  * no longer the ones asked for → delete it, then build afresh
@@ -328,7 +330,9 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
328
330
  if (verdict.state === 'red') return verdict.attempt >= 2 ? { step: 'red-serial' } : { step: 'red-rerun-or-serial' };
329
331
  return { step: 'land' };
330
332
  }
331
- if (eligibleCount < 2) return { step: 'serial', reason: 'too-few' };
333
+ // #562: a batch of ONE is a batch — a lone ready member still lands through the combined run, so
334
+ // the setups a repo runs only on ship-batch/** and trunk gate it before trunk moves.
335
+ if (eligibleCount < 1) return { step: 'serial', reason: 'none-ready' };
332
336
  return { step: 'build' };
333
337
  }
334
338