@futurelastic/colab-handbook 1.13.0-rc.47 → 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.47"
36
+ "version": "1.13.0-rc.49"
37
37
  }
package/tools/colab CHANGED
@@ -2049,10 +2049,25 @@ function cmdReleaseFinalize(argv) {
2049
2049
  });
2050
2050
  // #566: only the run that CUT the candidate vouches for what it published — read from the rows
2051
2051
  // BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
2052
- const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
2052
+ const cutRunOpts = {
2053
2053
  tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
2054
2054
  jobCount: (id) => git.ghRunJobCount(repoAbs, id),
2055
- });
2055
+ };
2056
+ const cutRun = releaseFinalize.cutRunVerdict(rawRows, cutRunOpts);
2057
+ // #565: a run that failed only in its deploy jobs (staging) — the three run-reading conditions
2058
+ // re-read with it counted as passed. decide() uses that reading on a human final only, and names
2059
+ // the failure either way. Jobs are read lazily: only when a condition already failed.
2060
+ let deployReport = null;
2061
+ if (Array.isArray(rawRows) && !(conditions.ci.ok && conditions.suite.ok && cutRun.ok)) {
2062
+ const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
2063
+ if (d.failures.length) {
2064
+ const at = `${cand.tag}@${shortSha(cand.sha)}`;
2065
+ const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
2066
+ const run = git.summarizeRunsForCommit(lenRows, cand.sha);
2067
+ const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
2068
+ deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
2069
+ }
2070
+ }
2056
2071
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
2057
2072
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
2058
2073
  // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
@@ -2076,7 +2091,7 @@ function cmdReleaseFinalize(argv) {
2076
2091
  }
2077
2092
  const verdict = releaseFinalize.decide({
2078
2093
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2079
- ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
2094
+ ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2080
2095
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2081
2096
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2082
2097
  });
@@ -10522,7 +10537,9 @@ work as usual (json: \`direct: true\`, \`branch: null\`, \`mode: "evidence-close
10522
10537
 
10523
10538
  BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–3;
10524
10539
  absent or 1 declines every --batch call. It tests up to N green candidates as ONE combined head, then
10525
- 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:
10526
10543
  - each member must be green at its OWN head (or have no run that could ever arrive), pass every
10527
10544
  gate its own \`ship --dry --json\` reports, and be an ordinary squash into trunk through the
10528
10545
  auto-trunk grant — the docs-only door, a migration, a ci-grant/cure, a core-path review, an
@@ -10540,8 +10557,8 @@ It never waits: each call reads the remote, takes ONE step and exits —
10540
10557
  it, bounded (code-ship B1a), and run the SAME command again
10541
10558
  4 declined — nothing landed; the last line is "→ SERIAL: colab ship --branch <b1> · …". Causes:
10542
10559
  not enabled, no auto-trunk, no workflow fires on ship-batch/** (the run could never arrive),
10543
- trunk CI red (the cure/grant doors apply per member, never to a batch), fewer than two members
10544
- 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\`,
10545
10562
  once; red:finding, or red again after that one re-run → serial
10546
10563
  1 refused (a broken checkout, an unreadable remote) — or the land push was refused while trunk did
10547
10564
  NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
@@ -10562,8 +10579,8 @@ PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in proj
10562
10579
  unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
10563
10580
  ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
10564
10581
  since the member became ready (its head CI's last update, else its head commit's date) — then the same
10565
- call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
10566
- --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.
10567
10584
 
10568
10585
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
10569
10586
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -14271,10 +14288,11 @@ function cmdShipBatch(opts) {
14271
14288
  if (String(doc.autonomy || '') !== 'auto-trunk') {
14272
14289
  return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
14273
14290
  }
14274
- // #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.
14275
14293
  const waitCfg = shipBatch.parseShipBatchWait(doc);
14276
14294
  if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
14277
- 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');
14278
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`);
14279
14297
 
14280
14298
  const remote = git.remoteFor(repoAbs);
@@ -14340,7 +14358,7 @@ function cmdShipBatch(opts) {
14340
14358
  }
14341
14359
  if (!foreignStep) {
14342
14360
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
14343
- 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));
14344
14362
  existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
14345
14363
  // #415: the command line and the staged batch can name different sets. A requested branch the
14346
14364
  // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
@@ -14353,7 +14371,7 @@ function cmdShipBatch(opts) {
14353
14371
  }
14354
14372
  }
14355
14373
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
14356
- 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 });
14357
14375
 
14358
14376
  if (step.step === 'rebuild') {
14359
14377
  print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
@@ -14413,7 +14431,7 @@ function cmdShipBatch(opts) {
14413
14431
  e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
14414
14432
  const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
14415
14433
  step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
14416
- if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
14434
+ if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0) {
14417
14435
  // #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
14418
14436
  // member is ready. Wait for a partner until the repo's window, counted from when it became ready.
14419
14437
  const lone = selected[0];
@@ -14423,13 +14441,13 @@ function cmdShipBatch(opts) {
14423
14441
  if (pw.wait) {
14424
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.`);
14425
14443
  print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
14426
- 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.');
14427
14445
  return 3;
14428
14446
  }
14429
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;
14430
- 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)`);
14431
14449
  }
14432
- 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');
14433
14451
 
14434
14452
  // ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
14435
14453
  const ref = shipBatch.batchRefName(trunkNow);
@@ -14504,8 +14522,8 @@ function cmdShipBatch(opts) {
14504
14522
  for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
14505
14523
  // #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
14506
14524
  // batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
14507
- // Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
14508
- 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) {
14509
14527
  const last = built[built.length - 1];
14510
14528
  const cur = git.git(['log', '-1', '--format=%B'], dir);
14511
14529
  const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
@@ -14517,9 +14535,9 @@ function cmdShipBatch(opts) {
14517
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)`);
14518
14536
  }
14519
14537
  const head = git.git(['rev-parse', 'HEAD'], dir).stdout;
14520
- if (built.length < 2) {
14538
+ if (built.length < 1) {
14521
14539
  cleanup();
14522
- 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);
14523
14541
  }
14524
14542
  if (opts.dry) {
14525
14543
  cleanup();
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
77
77
 
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
- 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -379,6 +379,56 @@ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } =
379
379
  };
380
380
  }
381
381
 
382
+ // ---- a failed deploy job: a report on a human final, a gate on an automatic one (#565) -------------
383
+
384
+ // A job whose name says it deploys. The release workflow deploys the candidate to staging after it has
385
+ // built, tested and published it; that job's failure is about the deploy target (a host the runner
386
+ // cannot reach, a registry permission, a sibling image that was never built), never about the code.
387
+ const DEPLOY_JOB_RE = /\bdeploy/i;
388
+
389
+ /** Does a job named `name` deploy? Read from the name: GitHub's job read carries no environment. */
390
+ function isDeployJob(name) {
391
+ return DEPLOY_JOB_RE.test(String(name || ''));
392
+ }
393
+
394
+ /**
395
+ * The runs at a candidate's commit that failed ONLY in deploy jobs (#565). `rows` are the run rows
396
+ * (null = unread); `jobsOf(databaseId)` returns that run's jobs (`git.ghRunJobs`, null = unread), asked
397
+ * lazily and only for a completed run that concluded `failure`.
398
+ *
399
+ * A run is deploy-only when its jobs were read, at least one did not pass, and every job that did not
400
+ * pass (anything but success/skipped/neutral — cancelled included) is a deploy job. A job that builds,
401
+ * tests or publishes failing keeps the run a failure; so does a run whose jobs could not be read.
402
+ *
403
+ * Returns { rows, failures } — `rows` a copy of `rows` where each deploy-only run reads `success` and
404
+ * carries `deployFailed` (its failed deploy jobs), `failures` [{ workflowName, databaseId, jobs }] for
405
+ * the report. Measuring this never decides anything: decide() uses the rewritten reading only on a
406
+ * human final, and names the failures either way.
407
+ */
408
+ function deployOnlyFailures(rows, jobsOf) {
409
+ if (!Array.isArray(rows) || typeof jobsOf !== 'function') return { rows, failures: [] };
410
+ const failures = [];
411
+ const out = rows.map((r) => {
412
+ if (!r || r.status !== 'completed' || r.conclusion !== 'failure' || r.databaseId == null) return r;
413
+ const jobs = jobsOf(r.databaseId);
414
+ if (!Array.isArray(jobs) || !jobs.length) return r;
415
+ const bad = jobs.filter((j) => j && !(j.status === 'completed' && NOT_RED.has(j.conclusion)));
416
+ if (!bad.length || !bad.every((j) => isDeployJob(j.name))) return r;
417
+ const named = bad.map((j) => `${j.name} (${j.status === 'completed' ? j.conclusion || 'no conclusion' : j.status || 'unknown'})`);
418
+ failures.push({ workflowName: r.workflowName || '(unnamed workflow)', databaseId: r.databaseId, jobs: named });
419
+ return { ...r, conclusion: 'success', deployFailed: named };
420
+ });
421
+ return { rows: out, failures };
422
+ }
423
+
424
+ /** The `deploy-report` check's detail — what failed, and what it means on this final. */
425
+ function deployReportDetail(failures, { blocking }) {
426
+ const what = failures.map((f) => `${f.workflowName} run ${f.databaseId}: ${f.jobs.join(', ')}`).join('; ');
427
+ return blocking
428
+ ? `a deploy job failed at this candidate (${what}); an automatic final treats it as blocking, so ci-green, full-suite and cut-run read the run as failed`
429
+ : `a deploy job failed at this candidate (${what}); its build, tests and publish passed, so on a human final this is a report, not a gate: ci-green, full-suite and cut-run read that run without its deploy jobs. Check the deploy target before you finalize`;
430
+ }
431
+
382
432
  // ---- the test period ----------------------------------------------------------------------------
383
433
 
384
434
  /**
@@ -617,7 +667,17 @@ function decide(facts) {
617
667
  add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
618
668
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
619
669
  add('trunk-green', tr.ok, tr.detail, ownClock);
620
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
670
+ // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
671
+ // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
672
+ // those runs counted as passed; it is absent when no such run exists.
673
+ const dr = f.deployReport && Array.isArray(f.deployReport.failures) && f.deployReport.failures.length ? f.deployReport : null;
674
+ const lenient = !!dr && !auto;
675
+ const pick = (strict, relaxed) => (lenient && relaxed ? relaxed : strict);
676
+ for (const [condition, v] of [['ci-green', pick(f.ci, dr && dr.ci)], ['full-suite', pick(f.suite, dr && dr.suite)], ['cut-run', pick(f.cutRun, dr && dr.cutRun)]]) {
677
+ add(condition, v && v.ok, v ? v.detail : 'not measured');
678
+ }
679
+ if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
680
+ for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
621
681
  add(condition, v && v.ok, v ? v.detail : 'not measured');
622
682
  }
623
683
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -699,7 +759,7 @@ module.exports = {
699
759
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
700
760
  parseVersion, compareVersions, parseCandidate,
701
761
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
702
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
762
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
703
763
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
704
764
  carriedIssues, previousFinal, releasedEvent, releasedComment,
705
765
  };
@@ -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