@futurelastic/colab-handbook 1.13.0-rc.45 → 1.13.0-rc.46
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 +23 -6
- package/tools/lib/ship-handoff.js +67 -9
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -10377,7 +10377,7 @@ A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHE
|
|
|
10377
10377
|
(…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
|
|
10378
10378
|
name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
|
|
10379
10379
|
one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
|
|
10380
|
-
branch that moved after its hand-off needs a new one); and every issue the branch carries has a
|
|
10380
|
+
branch that moved after its hand-off needs a new one — except by base-sync merges, #579, below); and every issue the branch carries has a
|
|
10381
10381
|
live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
|
|
10382
10382
|
claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
|
|
10383
10383
|
the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
|
|
@@ -10385,6 +10385,13 @@ the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url>
|
|
|
10385
10385
|
the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
|
|
10386
10386
|
--batch or --direct, and not when this machine already holds a claim on the branch.
|
|
10387
10387
|
|
|
10388
|
+
A remote-built branch that fell BEHIND its base (#579) is synced by the lander as usual (B0: merge
|
|
10389
|
+
the base in, push) — and the hand-off still verifies, because the commits between the handed-off
|
|
10390
|
+
sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
|
|
10391
|
+
and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
|
|
10392
|
+
conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
|
|
10393
|
+
trailer then reads \`Colab-Handoff: <url> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
|
|
10394
|
+
|
|
10388
10395
|
UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
|
|
10389
10396
|
--session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
|
|
10390
10397
|
(--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
|
|
@@ -11911,7 +11918,7 @@ function cmdShipDryJson(opts) {
|
|
|
11911
11918
|
const trunk = resolveTrunk(repoAbs, doc);
|
|
11912
11919
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
11913
11920
|
if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
|
|
11914
|
-
const handoff = applyShipHandoff(repoAbs, sess, opts); // #578 — same resolution as the prose path
|
|
11921
|
+
const handoff = applyShipHandoff(repoAbs, sess, opts, trunk); // #578 — same resolution as the prose path
|
|
11915
11922
|
|
|
11916
11923
|
const checks = [];
|
|
11917
11924
|
if (handoff) {
|
|
@@ -12995,7 +13002,7 @@ function autonomyGatePayload(gate) {
|
|
|
12995
13002
|
* Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
|
|
12996
13003
|
* this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
|
|
12997
13004
|
*/
|
|
12998
|
-
function applyShipHandoff(repoAbs, sess, opts) {
|
|
13005
|
+
function applyShipHandoff(repoAbs, sess, opts, trunk) {
|
|
12999
13006
|
if (!opts.handoff) return null;
|
|
13000
13007
|
if (opts.adopt) throw new UserError('--handoff and --adopt contradict each other: --adopt is for a branch with NO issue, --handoff for one whose claim lives on another machine — drop --adopt');
|
|
13001
13008
|
if (sess.issues.length) {
|
|
@@ -13017,6 +13024,13 @@ function applyShipHandoff(repoAbs, sess, opts) {
|
|
|
13017
13024
|
const remote = git.remoteFor(repoAbs);
|
|
13018
13025
|
if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
|
|
13019
13026
|
const refs = git.branchRefs(repoAbs, sess.branch, remote);
|
|
13027
|
+
// #579: base-sync merges the lander (B0) stacked on the handed-off head do not void the hand-off.
|
|
13028
|
+
// Read against the base as it is NOW — the merges' second parents must already be on it.
|
|
13029
|
+
let syncChain = [];
|
|
13030
|
+
if (u && comment && refs && refs.remoteSha && trunk) {
|
|
13031
|
+
git.git(['fetch', '--quiet', remote, `+refs/heads/${trunk}:refs/remotes/${remote}/${trunk}`], repoAbs);
|
|
13032
|
+
syncChain = shipHandoff.syncMergeChain((a) => git.git(a, repoAbs), refs.remoteSha, `refs/remotes/${remote}/${trunk}`);
|
|
13033
|
+
}
|
|
13020
13034
|
const claimsByIssue = {};
|
|
13021
13035
|
if (u && comment) {
|
|
13022
13036
|
for (const n of shipguard.branchIssueNumbers(sess.branch)) {
|
|
@@ -13024,7 +13038,7 @@ function applyShipHandoff(repoAbs, sess, opts) {
|
|
|
13024
13038
|
claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
|
|
13025
13039
|
}
|
|
13026
13040
|
}
|
|
13027
|
-
const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue });
|
|
13041
|
+
const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain });
|
|
13028
13042
|
if (!v.ok) return v;
|
|
13029
13043
|
sess.issues = v.issues;
|
|
13030
13044
|
sess.handoff = v;
|
|
@@ -13035,7 +13049,10 @@ function applyShipHandoff(repoAbs, sess, opts) {
|
|
|
13035
13049
|
}
|
|
13036
13050
|
|
|
13037
13051
|
function handoffDetail(v) {
|
|
13038
|
-
|
|
13052
|
+
const head = v.syncMerges
|
|
13053
|
+
? `${shortSha(v.handedOff)}, under ${v.syncMerges} clean base-sync merge${v.syncMerges === 1 ? '' : 's'} to the remote head ${shortSha(v.sha)} (#579)`
|
|
13054
|
+
: `${shortSha(v.sha)} = the remote head`;
|
|
13055
|
+
return `${v.url} hands off ${head}; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
|
|
13039
13056
|
}
|
|
13040
13057
|
|
|
13041
13058
|
/** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
|
|
@@ -13087,7 +13104,7 @@ function cmdShip(argv) {
|
|
|
13087
13104
|
// #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
|
|
13088
13105
|
// branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
|
|
13089
13106
|
// remote-only branch resolve here at all.
|
|
13090
|
-
const handoff = applyShipHandoff(repoAbs, sess, opts);
|
|
13107
|
+
const handoff = applyShipHandoff(repoAbs, sess, opts, trunk);
|
|
13091
13108
|
if (handoff && !handoff.ok) {
|
|
13092
13109
|
process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
|
|
13093
13110
|
`ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
|
|
@@ -24,7 +24,14 @@
|
|
|
24
24
|
* 4. the body names the branch, as a whole token;
|
|
25
25
|
* 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
|
|
26
26
|
* 6. the body names a sha that is a prefix of the remote branch's CURRENT head — a branch that
|
|
27
|
-
* moved after its hand-off was not handed off at that head, and lands only after a new one
|
|
27
|
+
* moved after its hand-off was not handed off at that head, and lands only after a new one.
|
|
28
|
+
* ONE movement is not "moved" (#579): base-sync merges stacked on the handed-off head. The
|
|
29
|
+
* stale-base gate (#395) sends every behind-trunk branch through B0's sync, and the sync moves
|
|
30
|
+
* the head; without this a remote-built branch that fell behind could land only after its
|
|
31
|
+
* executor — whose session has usually ended — posted again. A sync merge is accepted only
|
|
32
|
+
* when it adds nothing of its own (syncMergeChain, below): two parents, the second already on
|
|
33
|
+
* the base, and a tree equal to git's own clean merge of the two. Any other commit after the
|
|
34
|
+
* handed-off sha — a fix-up, a rebase, a hand-resolved conflict — is still `head-moved`;
|
|
28
35
|
* 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
|
|
29
36
|
* the hand-off's author before the hand-off — the claim really does live elsewhere, and the
|
|
30
37
|
* party handing off is the party holding it.
|
|
@@ -63,9 +70,13 @@ function namedShas(body) {
|
|
|
63
70
|
* refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
|
|
64
71
|
* claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
|
|
65
72
|
* or null for an issue whose comments could not be read
|
|
66
|
-
*
|
|
73
|
+
* syncChain — (#579) the first-parent ancestors of the remote head reached through pure
|
|
74
|
+
* base-sync merges only, nearest first (syncMergeChain's output); [] or absent = none
|
|
75
|
+
* Returns { ok: true, issues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
|
|
76
|
+
* `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
|
|
77
|
+
* unless the head was synced, in which case `syncMerges` counts the merges between them.
|
|
67
78
|
*/
|
|
68
|
-
function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
|
|
79
|
+
function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }) {
|
|
69
80
|
const no = (reason, detail) => ({ ok: false, reason, detail });
|
|
70
81
|
const u = parseHandoffUrl(url);
|
|
71
82
|
if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
|
|
@@ -89,9 +100,13 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
|
|
|
89
100
|
}
|
|
90
101
|
const head = String(refs.remoteSha).toLowerCase();
|
|
91
102
|
const shas = namedShas(comment.body);
|
|
92
|
-
|
|
103
|
+
// #579: the head itself first, then each sha a pure base-sync merge sits on, nearest first.
|
|
104
|
+
const lineage = [head, ...(Array.isArray(syncChain) ? syncChain : []).map((x) => String(x).toLowerCase())];
|
|
105
|
+
const at = lineage.findIndex((l) => shas.some((s) => l.startsWith(s)));
|
|
106
|
+
if (at < 0) {
|
|
107
|
+
const synced = lineage.length > 1 ? ` (nor ${lineage.length - 1 === 1 ? 'the sha' : 'any of the ' + (lineage.length - 1) + ' shas'} its base-sync merges sit on)` : '';
|
|
93
108
|
return no('head-moved', shas.length
|
|
94
|
-
? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)} — the branch moved after it was handed off; ask its executor for a new hand-off`
|
|
109
|
+
? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)}${synced} — the branch moved after it was handed off by more than a clean merge of its base; ask its executor for a new hand-off`
|
|
95
110
|
: `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
|
|
96
111
|
}
|
|
97
112
|
let executor = null;
|
|
@@ -105,12 +120,55 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
|
|
|
105
120
|
}
|
|
106
121
|
if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
|
|
107
122
|
}
|
|
108
|
-
return { ok: true, issues, sha: refs.remoteSha, executor, url: String(url).trim() };
|
|
123
|
+
return { ok: true, issues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
|
|
109
124
|
}
|
|
110
125
|
|
|
111
|
-
/**
|
|
126
|
+
/**
|
|
127
|
+
* The squash trailer recording the door the issue set came through. It names the HANDED-OFF sha —
|
|
128
|
+
* the one the executor vouched for — and, after a sync (#579), the head that actually landed.
|
|
129
|
+
*/
|
|
112
130
|
function handoffTrailer(v) {
|
|
113
|
-
|
|
131
|
+
if (!v || !v.ok) return '';
|
|
132
|
+
const handed = String(v.handedOff || v.sha).slice(0, 12);
|
|
133
|
+
const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
|
|
134
|
+
return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* #579 — walk the remote head's first-parent line while each commit is a PURE base-sync merge, and
|
|
139
|
+
* return the shas it sits on, nearest first. A commit qualifies only when all three hold:
|
|
140
|
+
* - exactly two parents (a squash, a rebase, a cherry-pick or a fix-up has one);
|
|
141
|
+
* - its second parent is already on the base (`merge-base --is-ancestor p2 <baseRef>`) — it
|
|
142
|
+
* brought in landed base content, not a side branch;
|
|
143
|
+
* - its tree equals `git merge-tree --write-tree p1 p2`'s — git's own conflict-free merge of the
|
|
144
|
+
* two. A conflict (exit 1) or a hand-edited result (a different tree) is NOT pure: someone wrote
|
|
145
|
+
* content into it, and only the executor can vouch for content.
|
|
146
|
+
* The walk stops at the first commit that fails, so a sync merge stacked on a fix-up yields only
|
|
147
|
+
* the fix-up's sha — which a hand-off naming the commit before the fix-up does not match.
|
|
148
|
+
*
|
|
149
|
+
* `run(args)` is git in the repo, returning { ok, code, stdout } (tools/lib/git.js `git`). A git
|
|
150
|
+
* too old for `merge-tree --write-tree` (< 2.38) proves nothing, so the chain is just empty there:
|
|
151
|
+
* the hand-off then needs the exact head, exactly as before #579.
|
|
152
|
+
*/
|
|
153
|
+
function syncMergeChain(run, head, baseRef, maxDepth = 50) {
|
|
154
|
+
const chain = [];
|
|
155
|
+
let cur = String(head || '');
|
|
156
|
+
for (let i = 0; cur && i < maxDepth; i++) {
|
|
157
|
+
const p = run(['rev-list', '--parents', '-n', '1', cur]);
|
|
158
|
+
if (!p.ok) break;
|
|
159
|
+
const parts = String(p.stdout).trim().split(/\s+/);
|
|
160
|
+
if (parts.length !== 3) break;
|
|
161
|
+
const [, p1, p2] = parts;
|
|
162
|
+
if (run(['merge-base', '--is-ancestor', p2, baseRef]).code !== 0) break;
|
|
163
|
+
const mt = run(['merge-tree', '--write-tree', p1, p2]);
|
|
164
|
+
if (mt.code !== 0) break;
|
|
165
|
+
const merged = String(mt.stdout).split('\n')[0].trim();
|
|
166
|
+
const tree = run(['rev-parse', `${cur}^{tree}`]);
|
|
167
|
+
if (!tree.ok || !/^[0-9a-f]{40,64}$/.test(merged) || merged !== String(tree.stdout).trim()) break;
|
|
168
|
+
chain.push(p1.toLowerCase());
|
|
169
|
+
cur = p1;
|
|
170
|
+
}
|
|
171
|
+
return chain;
|
|
114
172
|
}
|
|
115
173
|
|
|
116
|
-
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer };
|
|
174
|
+
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain };
|