@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 +1 -1
- package/tools/colab +62 -24
- package/tools/lib/ship-handoff.js +39 -1
package/package.json
CHANGED
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
|
-
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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;
|
|
13426
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 }
|
|
14873
|
-
|
|
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
|
-
|
|
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 };
|