@futurelastic/colab-handbook 1.13.0-rc.50 → 1.13.0-rc.51
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 +70 -0
- package/tools/lib/git.js +1 -1
- package/tools/lib/ship-batch.js +61 -0
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -10566,6 +10566,11 @@ It never waits: each call reads the remote, takes ONE step and exits —
|
|
|
10566
10566
|
One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
|
|
10567
10567
|
is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
|
|
10568
10568
|
for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
|
|
10569
|
+
The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref at trunk's tip has its
|
|
10570
|
+
combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
|
|
10571
|
+
\`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
|
|
10572
|
+
'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
|
|
10573
|
+
A red batch, or one with no run / not landed past that grace, holds nothing.
|
|
10569
10574
|
A member that conflicts with the members already in is dropped to the next batch; the rest go on —
|
|
10570
10575
|
unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
|
|
10571
10576
|
regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
|
|
@@ -12216,6 +12221,17 @@ function cmdShipDryJson(opts) {
|
|
|
12216
12221
|
if (coreReviewJson.verdict === 'pending') mode = 'pr-pending';
|
|
12217
12222
|
}
|
|
12218
12223
|
|
|
12224
|
+
// #581: the same lane read as the prose path's table — a squash into trunk while a batch holds the
|
|
12225
|
+
// lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
|
|
12226
|
+
// Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
|
|
12227
|
+
if (!dryMode.evidenceClose && !opts._batchMember) {
|
|
12228
|
+
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
12229
|
+
if (laneJson) {
|
|
12230
|
+
checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
|
|
12231
|
+
detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
|
|
12232
|
+
}
|
|
12233
|
+
}
|
|
12234
|
+
|
|
12219
12235
|
// #149: the same inherited-closing-keyword scan the prose --dry path runs, mirrored here —
|
|
12220
12236
|
// following #153's own precedent for this function (its comment above: "a caller reading only
|
|
12221
12237
|
// checks[]/ok … used to see NO check at all here"). Without this, the ONE caller class this path
|
|
@@ -13300,6 +13316,11 @@ function cmdShip(argv) {
|
|
|
13300
13316
|
const coreReview = shipCoreReview(repoAbs, gh, target, sess.branch);
|
|
13301
13317
|
const coreOk = coreReview.verdict !== 'refuse';
|
|
13302
13318
|
checks.push([coreOk ? (coreReview.verdict === 'pending' ? '⏸' : '✓') : '✗', 'core-path review (#350)', coreReview.detail]);
|
|
13319
|
+
|
|
13320
|
+
// #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
|
|
13321
|
+
// hold is not a failed precondition — it is a pause, taken below once every real one has passed.
|
|
13322
|
+
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
13323
|
+
if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
|
|
13303
13324
|
for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
|
|
13304
13325
|
|
|
13305
13326
|
// #389: the record this ship will write after the push must be writable NOW.
|
|
@@ -13534,6 +13555,8 @@ function cmdShip(argv) {
|
|
|
13534
13555
|
print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · ' +
|
|
13535
13556
|
(opts.keepWorktree ? 'keep worktree' : 'worktree rm') + ' (releases claims)');
|
|
13536
13557
|
print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
|
|
13558
|
+
} else if (lane && lane.held && coreReview.verdict !== 'pending') {
|
|
13559
|
+
print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
|
|
13537
13560
|
} else if (coreReview.verdict === 'pending') {
|
|
13538
13561
|
print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
|
|
13539
13562
|
'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
|
|
@@ -13599,6 +13622,9 @@ function cmdShip(argv) {
|
|
|
13599
13622
|
return shipOpenCorePr(repoAbs, coreReview, { target, branch: sess.branch, title, body });
|
|
13600
13623
|
}
|
|
13601
13624
|
|
|
13625
|
+
// ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
|
|
13626
|
+
if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
|
|
13627
|
+
|
|
13602
13628
|
// ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
|
|
13603
13629
|
const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
|
|
13604
13630
|
const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
|
|
@@ -13744,6 +13770,10 @@ function cmdShip(argv) {
|
|
|
13744
13770
|
ciGrantForTrailer = ciResultB1.grantVerdict;
|
|
13745
13771
|
}
|
|
13746
13772
|
}
|
|
13773
|
+
// #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
|
|
13774
|
+
// built in that window is exactly as live as one the table saw.
|
|
13775
|
+
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
|
|
13776
|
+
if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
|
|
13747
13777
|
// WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
|
|
13748
13778
|
// (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
|
|
13749
13779
|
// out onto a long-lived line is the very state that made this axis necessary — everything reading
|
|
@@ -14266,6 +14296,46 @@ function shipDryJsonReport(opts) {
|
|
|
14266
14296
|
return { ok: code === 0, body: holder.body || null, error: null };
|
|
14267
14297
|
}
|
|
14268
14298
|
|
|
14299
|
+
/**
|
|
14300
|
+
* #581: is a batch in flight at trunk's current tip? Read by every serial door that moves trunk (the
|
|
14301
|
+
* prose ship's table and B1, `--dry --json`), so a lander told about it waits instead of moving trunk
|
|
14302
|
+
* under the batch — which would throw the batch's green combined run away. The rule is
|
|
14303
|
+
* lib/ship-batch.js laneHold; this only reads the remote.
|
|
14304
|
+
*
|
|
14305
|
+
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
14306
|
+
* trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
|
|
14307
|
+
*/
|
|
14308
|
+
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
|
|
14309
|
+
if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
|
|
14310
|
+
const remote = git.remoteFor(repoAbs);
|
|
14311
|
+
const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14312
|
+
if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
|
|
14313
|
+
const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
|
|
14314
|
+
const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
|
|
14315
|
+
const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
|
|
14316
|
+
.filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
|
|
14317
|
+
const batches = atTip.map((x) => {
|
|
14318
|
+
const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
|
|
14319
|
+
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
14320
|
+
if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
|
|
14321
|
+
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
14322
|
+
return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
|
|
14323
|
+
builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
|
|
14324
|
+
});
|
|
14325
|
+
const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
|
|
14326
|
+
const detail = r.held
|
|
14327
|
+
? `${r.ref} holds the ${trunk} lane — ${r.why}; landing now would move ${trunk} under it and discard its run`
|
|
14328
|
+
: (r.released.length ? `no batch holds the lane (${r.released.map((x) => `${x.ref}: ${x.why}`).join('; ')})` : `no batch in flight at ${trunk}@${shortSha(trunkNow)}`);
|
|
14329
|
+
return { ...r, trunkNow, detail };
|
|
14330
|
+
}
|
|
14331
|
+
|
|
14332
|
+
/** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
|
|
14333
|
+
function printBatchLanePause(lane, trunk) {
|
|
14334
|
+
print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
|
|
14335
|
+
print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
|
|
14336
|
+
print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
|
|
14337
|
+
}
|
|
14338
|
+
|
|
14269
14339
|
function cmdShipBatch(opts) {
|
|
14270
14340
|
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
|
|
14271
14341
|
if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
|
package/tools/lib/git.js
CHANGED
|
@@ -1042,7 +1042,7 @@ function ghInstalled() {
|
|
|
1042
1042
|
function ghRunsForRef(repo, ref, sha, limit = 20) {
|
|
1043
1043
|
if (!sha) return null;
|
|
1044
1044
|
const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
|
|
1045
|
-
'--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
|
|
1045
|
+
'--json', 'headSha,status,conclusion,createdAt,updatedAt,databaseId,workflowName,attempt'], { cwd: repo });
|
|
1046
1046
|
if (!r.ok) return null;
|
|
1047
1047
|
let runs;
|
|
1048
1048
|
try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -370,6 +370,66 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
|
|
|
370
370
|
return (batchRows || []).length >= a.length;
|
|
371
371
|
}
|
|
372
372
|
|
|
373
|
+
/**
|
|
374
|
+
* #581: the lane reservation. A batch ref at trunk's CURRENT tip whose combined run is in flight (or
|
|
375
|
+
* green and not yet landed) holds the trunk lane: a serial `colab ship` into trunk that landed now
|
|
376
|
+
* would move trunk under it, and the batch's next call would throw the green run away and rebuild —
|
|
377
|
+
* measured five builds in two hours on one repo, every member ready the whole time. The ref itself
|
|
378
|
+
* is the reservation: it already sits on the remote every lander reads, it names its base, and its
|
|
379
|
+
* runs say whether it is alive. No second record to write, expire or keep in sync.
|
|
380
|
+
*
|
|
381
|
+
* Facts in, per batch ref on the remote (`batches`):
|
|
382
|
+
* ref, base7 parseBatchRef
|
|
383
|
+
* verdict combinedVerdict of the runs at its head
|
|
384
|
+
* builtAtMs the batch head's commit time (the build commits it), null = unread
|
|
385
|
+
* settledAtMs the newest `updatedAt` of its runs once green, null = unread
|
|
386
|
+
* plus `trunkNow` (the remote trunk sha), `nowMs`, and `graceSec`.
|
|
387
|
+
*
|
|
388
|
+
* Out: `{ held: true, ref, why }` for the first batch that holds the lane, else `{ held: false,
|
|
389
|
+
* released: [{ ref, why }] }` naming each batch at this base that does NOT hold it, and why.
|
|
390
|
+
* - a batch on an older base holds nothing: trunk already moved past it, it rebuilds anyway;
|
|
391
|
+
* - red (first attempt or after its re-run) → declined, holds nothing;
|
|
392
|
+
* - pending, or a run list that could not be read → held (fail closed: a pause clears itself);
|
|
393
|
+
* - no run yet → held for `graceSec` after it was built, then released (its run never came);
|
|
394
|
+
* - green → held for `graceSec` after it went green — its lander lands it on its next call —
|
|
395
|
+
* then released: a green batch nobody lands is abandoned, and must not hold the lane forever.
|
|
396
|
+
* An unread time (built/settled) is released, never held: a hold has to be provably alive.
|
|
397
|
+
*/
|
|
398
|
+
const LANE_GRACE_SEC = 900;
|
|
399
|
+
|
|
400
|
+
function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {}) {
|
|
401
|
+
const now = String(trunkNow || '');
|
|
402
|
+
const released = [];
|
|
403
|
+
if (!now) return { held: false, released };
|
|
404
|
+
const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
|
|
405
|
+
const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
|
|
406
|
+
for (const b of (Array.isArray(batches) ? batches : [])) {
|
|
407
|
+
if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
|
|
408
|
+
const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
|
|
409
|
+
if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
|
|
410
|
+
if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
|
|
411
|
+
if (v.state === 'none') {
|
|
412
|
+
if (fresh(b.builtAtMs)) return { held: true, ref: b.ref, why: `built ${mins(b.builtAtMs)}, its combined run has not appeared yet` };
|
|
413
|
+
released.push({ ref: b.ref, why: Number.isFinite(b.builtAtMs)
|
|
414
|
+
? `no combined run ${mins(b.builtAtMs)} after it was built (grace ${graceSec}s) — treated as abandoned`
|
|
415
|
+
: 'no combined run, and its build time could not be read — not provably alive' });
|
|
416
|
+
continue;
|
|
417
|
+
}
|
|
418
|
+
if (fresh(b.settledAtMs)) return { held: true, ref: b.ref, why: `combined run green ${mins(b.settledAtMs)} — its lander lands it on its next call` };
|
|
419
|
+
released.push({ ref: b.ref, why: Number.isFinite(b.settledAtMs)
|
|
420
|
+
? `combined run green ${mins(b.settledAtMs)} and still not landed (grace ${graceSec}s) — treated as abandoned`
|
|
421
|
+
: 'combined run green, but when it went green could not be read — not provably alive' });
|
|
422
|
+
}
|
|
423
|
+
return { held: false, released };
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
|
|
427
|
+
function settledAt(rows) {
|
|
428
|
+
const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
|
|
429
|
+
.map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
|
|
430
|
+
return t.length ? Math.max(...t) : null;
|
|
431
|
+
}
|
|
432
|
+
|
|
373
433
|
/**
|
|
374
434
|
* #415: branches the command line names that a staged batch does not carry, in command-line order.
|
|
375
435
|
* `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
|
|
@@ -430,4 +490,5 @@ module.exports = {
|
|
|
430
490
|
droppedTrailer, parseDroppedTrailers, appendTrailers,
|
|
431
491
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
432
492
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
493
|
+
LANE_GRACE_SEC, laneHold, settledAt,
|
|
433
494
|
};
|