@futurelastic/colab-handbook 1.14.0-rc.6 → 1.14.0-rc.7

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.14.0-rc.6"
36
+ "version": "1.14.0-rc.7"
37
37
  }
package/tools/colab CHANGED
@@ -10582,7 +10582,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
10582
10582
  }
10583
10583
 
10584
10584
  const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
10585
- colab ship --batch <b1,b2[,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10585
+ colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
10586
10586
 
10587
10587
  The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
10588
10588
  CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
@@ -10687,8 +10687,15 @@ live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author be
10687
10687
  claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
10688
10688
  the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
10689
10689
  🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
10690
- the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
10691
- --batch or --direct, and not when this machine already holds a claim on the branch.
10690
+ the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt
10691
+ or --direct, and not when this machine already holds a claim on the branch.
10692
+
10693
+ IN A BATCH (#591) the hand-off rides its member: \`--batch b1,b2@<url>\` (split on the first @).
10694
+ That member is verified by this SAME door — same checks, same refusal text, which drops it from
10695
+ the batch while the rest build — then joins the combined run with no sync of its own; its squash
10696
+ carries the Colab-Handoff trailer, and the land reads the door back from that commit. Repeat the
10697
+ same list, @ included, on every call: a rebuild re-verifies its members from the command line.
10698
+ A bare --handoff beside --batch names no member and refuses.
10692
10699
 
10693
10700
  A remote-built branch that fell BEHIND its base (#579) is synced by the lander as usual (B0: merge
10694
10701
  the base in, push) — and the hand-off still verifies, because the commits between the handed-off
@@ -12306,6 +12313,11 @@ function cmdShipDryJson(opts) {
12306
12313
  baseCi: baseCiPayloadVal, dirtyOwners: dirtyOwnersPayloadVal, autonomyGate: autonomyGatePayloadVal,
12307
12314
  coreReview: coreReviewPayloadVal,
12308
12315
  ...machineTrailerPayload(mode === 'squash' || mode === 'pr-pending'),
12316
+ // #591: the verified hand-off (or its refusal), so `ship --batch` puts this member's
12317
+ // Colab-Handoff trailer on its squash and words a refusal exactly as the single door does.
12318
+ ...(handoff ? { handoff: handoff.ok
12319
+ ? { ok: true, url: handoff.url, sha: handoff.sha, handedOff: handoff.handedOff, syncMerges: handoff.syncMerges || 0 }
12320
+ : { ok: false, reason: handoff.reason, detail: handoff.detail } } : {}),
12309
12321
  };
12310
12322
  // #373: `ship --batch` reads each member through this SAME function — handed the body, not stdout.
12311
12323
  if (opts._report) opts._report.body = body;
@@ -12467,11 +12479,14 @@ function cmdShipDryJson(opts) {
12467
12479
  // ---- (c) no hand-merge conflict — NEW: the plain --dry prose path never checks this today ----
12468
12480
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
12469
12481
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
12470
- const mc = shipMergeConflictCheck(repoAbs, target, sess.branch, generated, hasPreShip);
12482
+ // #591: read the branch through the ref it actually resolves to — a hand-off branch is remote-only
12483
+ // here, and its bare name resolves to nothing (the same gap #589 closed for the cure rule).
12484
+ const dryShipRef = shipRefFor(repoAbs, sess.branch);
12485
+ const mc = shipMergeConflictCheck(repoAbs, target, dryShipRef, generated, hasPreShip);
12471
12486
  checks.push({ name: 'no hand-merge conflict', ok: mc.ok, class: mc.ok ? null : (mc.unknown ? SELF_CLEARING : HUMAN_GATED), detail: mc.detail });
12472
12487
 
12473
12488
  // ---- (d) the two checks the machine-facing path was missing entirely ----
12474
- const dryCommits = branchCommits(repoAbs, target, sess.branch);
12489
+ const dryCommits = branchCommits(repoAbs, target, dryShipRef);
12475
12490
 
12476
12491
  // #87: B1b's cross-check, same rule as the prose path — only over the issues that would CLOSE.
12477
12492
  const dryCorr = shipguard.corroborateIssues(closeIssues, sess.branch, dryCommits);
@@ -12514,7 +12529,7 @@ function cmdShipDryJson(opts) {
12514
12529
  // #90: "branch has commits" — the precondition whose absence told an unattended caller `ok: true`
12515
12530
  // about a branch that could not ship. It is NOT a failure when the branch qualifies for
12516
12531
  // evidence-close; it is a different mode, and saying so is the whole point.
12517
- const dryMode = shipMode(repoAbs, target, sess.branch, dryCommits);
12532
+ const dryMode = shipMode(repoAbs, target, dryShipRef, dryCommits);
12518
12533
  if (dryMode.evidenceClose) {
12519
12534
  mode = 'evidence-close';
12520
12535
  checks.push({ name: 'branch has commits', ok: true, class: null,
@@ -13422,8 +13437,10 @@ function cmdShip(argv) {
13422
13437
  // — refuse the combination rather than silently ignore --json on a real ship.
13423
13438
  if (opts.json && !opts.dry) throw new UserError('--json currently only applies together with --dry — see `colab ship --help`');
13424
13439
  if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
13425
- // #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
13426
- if (opts.handoff && (opts.batch || opts.direct)) throw new UserError(`--handoff applies to one --branch ship — not to ${opts.batch ? '--batch' : '--direct'} (see \`colab ship --help\`)`);
13440
+ // #578: a hand-off names ONE branch; trunk-direct has no branch for it to name. #591: in a batch the
13441
+ // hand-off rides its member (`--batch b1,b2@<url>`), so a bare --handoff beside --batch names no one.
13442
+ if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-url> (#591, see `colab ship --help`)');
13443
+ if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
13427
13444
  if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
13428
13445
  if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
13429
13446
  // A fully separate code path, deliberately: the prose/table path below is unchanged by this
@@ -14694,7 +14711,11 @@ function cmdShipBatch(opts) {
14694
14711
  const doc = projectDoc(repoAbs);
14695
14712
  const trunk = resolveTrunk(repoAbs, doc);
14696
14713
  if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
14697
- const members = [...new Set(String(opts.batch === true ? '' : opts.batch).split(',').map((s) => s.trim()).filter(Boolean))];
14714
+ // #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-url>`.
14715
+ const entries = shipHandoff.parseBatchEntries(opts.batch === true ? '' : opts.batch);
14716
+ if (entries.errors.length) throw new UserError(`--batch: ${entries.errors.join('; ')}`);
14717
+ const members = entries.members;
14718
+ const handoffs = entries.handoffs;
14698
14719
  if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
14699
14720
  const serial = (why, list = members) => {
14700
14721
  print(`✗ ship-batch: ${why}`);
@@ -14865,13 +14886,19 @@ function cmdShipBatch(opts) {
14865
14886
  if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
14866
14887
  else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
14867
14888
  if (!why) {
14868
- const rep = shipDryJsonReport({ repo: repoAbs, branch: b, dry: true, json: true, session: opts.session, sessionName: opts.sessionName });
14889
+ // #591: a hand-off member is read through the SAME door a single --handoff ship uses
14890
+ // (applyShipHandoff inside cmdShipDryJson) — one verification, never a batch-local copy.
14891
+ const rep = shipDryJsonReport({ repo: repoAbs, branch: b, dry: true, json: true, session: opts.session, sessionName: opts.sessionName,
14892
+ ...(handoffs[b] ? { handoff: handoffs[b] } : {}) });
14869
14893
  report = rep.body;
14870
14894
  files = branchChangedFiles(repoAbs, trunkRef, refs.remoteSha);
14871
14895
  ciClass = shipBatch.branchCiClass(git.ghRunForSha(repoAbs, b), workflowsFiringAt(repoAbs, refs.remoteSha, b).length > 0);
14872
- const el = rep.error ? { ok: false, why: rep.error } : shipBatch.memberEligibility(report, ciClass, {
14873
- trunk, touchesWorkflows: files.some((f) => f.startsWith('.github/workflows/')),
14874
- });
14896
+ const el = rep.error ? { ok: false, why: rep.error }
14897
+ // #591: a refused hand-off is worded as the single door words it — the same reason, the same detail.
14898
+ : (report && report.handoff && !report.handoff.ok) ? { ok: false, why: `Refusing --handoff: ${report.handoff.detail}` }
14899
+ : shipBatch.memberEligibility(report, ciClass, {
14900
+ trunk, touchesWorkflows: files.some((f) => f.startsWith('.github/workflows/')),
14901
+ });
14875
14902
  if (!el.ok) why = el.why;
14876
14903
  }
14877
14904
  evaluated.push({ branch: b, sha: refs.remoteSha, report, ciClass, files, ok: !why, why: why || `own head CI: ${ciClass}` });
@@ -14969,8 +14996,9 @@ function cmdShipBatch(opts) {
14969
14996
  const closeIssues = m.report.closeIssues || [];
14970
14997
  const refsIssues = m.report.refsIssues || [];
14971
14998
  const conflicts = [];
14999
+ // #591: a hand-off member's squash records the door its issue set came through, as a single ship's does.
14972
15000
  const msg = buildSquashMessage(repoAbs, trunkRef, m.sha, closeIssues, refsIssues, conflicts,
14973
- [machineLine, shipBatch.memberTrailer({ ref, branch: m.branch, sha: m.sha })].filter(Boolean));
15001
+ [shipHandoff.handoffTrailer(m.report.handoff), machineLine, shipBatch.memberTrailer({ ref, branch: m.branch, sha: m.sha })].filter(Boolean));
14974
15002
  const coverage = msg ? shipguard.closesCoverage({ message: msg, closeIssues, refsIssues, commits: branchCommits(repoAbs, trunkRef, m.sha) }) : { ok: false, missing: [] };
14975
15003
  const inherited = msg && refsIssues.length ? squash.inheritedClosingKeywordConflicts(msg, refsIssues) : [];
14976
15004
  if (!msg || !coverage.ok || inherited.length) {
@@ -15117,10 +15145,26 @@ function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opt
15117
15145
  // The post-ship hook runs ONCE, over the whole batch — it is a trunk-checkout event, not a member one.
15118
15146
  const changed = git.git(['diff', '--name-only', `${base}..${head}`], repoAbs);
15119
15147
  const hits = changed.ok ? lockfileDrift.changedLockfiles(changed.stdout.split('\n').filter(Boolean)) : [];
15148
+ // Which commit is whose — read from the trailers, never from position alone.
15149
+ const log = git.git(['log', '--format=%H%x01%B%x00', `${base}..${head}`], repoAbs);
15150
+ const commitOf = new Map();
15151
+ for (const rec of (log.ok ? log.stdout.split('\0') : [])) {
15152
+ const [sha, body] = rec.replace(/^\n+/, '').split('\x01');
15153
+ const tr = shipBatch.parseMemberTrailers([body || ''])[0];
15154
+ if (sha && tr) commitOf.set(tr.branch, { sha: sha.trim(), body: body || '' });
15155
+ }
15120
15156
  const allIssues = [];
15121
15157
  const st0 = state.loadState();
15122
15158
  const sessions = existing.members.map((m) => {
15123
15159
  const sess = resolveShipSession(st0, repoAbs, { branch: m.branch, session: opts.session, sessionName: opts.sessionName });
15160
+ // #591: a hand-off member holds no claim here. Its squash carries the Colab-Handoff trailer the
15161
+ // build verified, and the issue set is the branch name's trailing run — handoffVerdict's own rule —
15162
+ // so its tail is the single hand-off land's: Closes from git, the executor's claim and branch kept.
15163
+ const ho = sess.issues.length ? null : shipHandoff.parseHandoffTrailer((commitOf.get(m.branch) || {}).body);
15164
+ if (ho) {
15165
+ sess.issues = shipguard.branchIssueNumbers(m.branch);
15166
+ sess.handoff = { ok: true, url: ho.url, sha: m.sha, handedOff: ho.handedOff };
15167
+ }
15124
15168
  allIssues.push(...sess.issues);
15125
15169
  return sess;
15126
15170
  });
@@ -15132,14 +15176,6 @@ function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opt
15132
15176
  if (hits.length && !hook.ran) warnDeferred(lockfileDrift.driftWarning(hits));
15133
15177
  release();
15134
15178
 
15135
- // Which commit is whose — read from the trailers, never from position alone.
15136
- const log = git.git(['log', '--format=%H%x01%B%x00', `${base}..${head}`], repoAbs);
15137
- const commitOf = new Map();
15138
- for (const rec of (log.ok ? log.stdout.split('\0') : [])) {
15139
- const [sha, body] = rec.replace(/^\n+/, '').split('\x01');
15140
- const tr = shipBatch.parseMemberTrailers([body || ''])[0];
15141
- if (sha && tr) commitOf.set(tr.branch, { sha: sha.trim(), body: body || '' });
15142
- }
15143
15179
  const gh = isGhUsable(repoAbs);
15144
15180
  const suffix = shipBatch.evidenceSuffix({ n: existing.members.length, ref: existing.ref, headSha: head, runIds: verdict.runIds });
15145
15181
  existing.members.forEach((m, i) => {
@@ -15171,14 +15207,16 @@ function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refs
15171
15207
  pushEvent('ship', {
15172
15208
  repo: repoAbs, worktree: sess.name, session: sess.session,
15173
15209
  issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
15174
- payload: { state: 'merged', branch: sess.branch, target: trunk, sha, issues: sess.issues, batch: true },
15210
+ payload: { state: 'merged', branch: sess.branch, target: trunk, sha, issues: sess.issues, batch: true,
15211
+ ...(sess.handoff ? { handoff: { url: sess.handoff.url, sha: sess.handoff.sha } } : {}) },
15175
15212
  });
15176
15213
  for (const num of closeIssues) pushEvent('issue-merged', { repo: repoAbs, issue: num, payload: { sha } });
15177
15214
  shipLandedTail({
15178
15215
  repoAbs, sess, target: trunk, trunk, gh, sha, closeIssues, refsIssues, refsSet: new Set(refsIssues),
15179
- integration: resolveIntegration(repoAbs, doc, trunk), opts, evidenceExtra: suffix,
15216
+ integration: resolveIntegration(repoAbs, doc, trunk), opts, evidenceExtra: suffix + handoffEvidence(sess.handoff), // #591
15180
15217
  });
15181
15218
  print(` ✓ ${sess.branch} → ${trunk} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
15219
+ if (sess.handoff) print(` landed from the hand-off ${sess.handoff.url} — the executor's claim and worktree stay until it confirms the land (#578)`);
15182
15220
  }
15183
15221
 
15184
15222
  // ---------------------------------------------------------------------------
@@ -171,4 +171,42 @@ function syncMergeChain(run, head, baseRef, maxDepth = 50) {
171
171
  return chain;
172
172
  }
173
173
 
174
- module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain };
174
+ /**
175
+ * #591 — `--batch b1,b2@<handoff-url>`: split the batch list into member branch names and, for the
176
+ * members built on another machine, the hand-off each one names. One list, one source: the `@` rides
177
+ * the member it belongs to, so the hand-off cannot drift from the member list the way a second
178
+ * `--handoffs` map could. Each entry splits on its FIRST `@` — a §4 branch name never holds one, and
179
+ * a hand-off URL never holds a `,`. The URL itself is judged later by handoffVerdict, exactly as a
180
+ * single `--handoff` is, so a malformed one is refused with today's message, not a new one.
181
+ * Returns { members: [branch…] (deduped, in order), handoffs: { [branch]: url }, errors: [msg…] }.
182
+ */
183
+ function parseBatchEntries(list) {
184
+ const members = [];
185
+ const handoffs = {};
186
+ const errors = [];
187
+ for (const raw of String(list || '').split(',').map((x) => x.trim()).filter(Boolean)) {
188
+ const at = raw.indexOf('@');
189
+ const branch = (at < 0 ? raw : raw.slice(0, at)).trim();
190
+ const url = at < 0 ? '' : raw.slice(at + 1).trim();
191
+ if (!branch) { errors.push(`"${raw}" names a hand-off but no branch — write <branch>@<hand-off-url>`); continue; }
192
+ if (at >= 0 && !url) { errors.push(`"${raw}" has an @ but no hand-off URL after it`); continue; }
193
+ if (url) {
194
+ if (handoffs[branch] && handoffs[branch] !== url) { errors.push(`${branch} is named with two different hand-offs (${handoffs[branch]}, ${url})`); continue; }
195
+ handoffs[branch] = url;
196
+ }
197
+ if (!members.includes(branch)) members.push(branch);
198
+ }
199
+ return { members, handoffs, errors };
200
+ }
201
+
202
+ /**
203
+ * #591 — read a `Colab-Handoff:` trailer back off a squash commit body (handoffTrailer's inverse):
204
+ * `{ url, handedOff }` or null. A batch lands in a second call, so the member's door is read from
205
+ * the commit the combined run graded, never re-supplied on the command line.
206
+ */
207
+ function parseHandoffTrailer(body) {
208
+ const m = String(body || '').match(/^Colab-Handoff: (\S+) @ ([0-9a-f]{7,40})\b/m);
209
+ return m ? { url: m[1], handedOff: m[2] } : null;
210
+ }
211
+
212
+ module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };