@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 +1 -1
- package/tools/colab +20 -17
- package/tools/lib/ship-batch.js +8 -4
package/package.json
CHANGED
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),
|
|
10559
|
-
|
|
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
|
|
10581
|
-
--batch with all of them.
|
|
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
|
|
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 <
|
|
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 >=
|
|
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:
|
|
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 === '
|
|
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
|
|
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
|
-
|
|
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(
|
|
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 (≥
|
|
14523
|
-
if (dropped.length && built.length >=
|
|
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 <
|
|
14538
|
+
if (built.length < 1) {
|
|
14536
14539
|
cleanup();
|
|
14537
|
-
return serial(
|
|
14540
|
+
return serial('no member survived the build', members);
|
|
14538
14541
|
}
|
|
14539
14542
|
if (opts.dry) {
|
|
14540
14543
|
cleanup();
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
|