@futurelastic/colab-handbook 1.13.0-rc.44 → 1.13.0-rc.45
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 +98 -7
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/ship-handoff.js +116 -0
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -78,6 +78,7 @@ const releaseFinalize = require('./lib/release-finalize');
|
|
|
78
78
|
const releaseChannel = require('./lib/release-channel');
|
|
79
79
|
const shippedBranch = require('./lib/shipped-branch');
|
|
80
80
|
const shipRoles = require('./lib/ship-roles'); // #372
|
|
81
|
+
const shipHandoff = require('./lib/ship-handoff'); // #578
|
|
81
82
|
const refsBrake = require('./lib/refs-brake'); // #385
|
|
82
83
|
const localAdopt = require('./lib/local-adopt'); // #393
|
|
83
84
|
const ownerBranch = require('./lib/owner-branch'); // #394
|
|
@@ -10275,7 +10276,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
10275
10276
|
return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
|
|
10276
10277
|
}
|
|
10277
10278
|
|
|
10278
|
-
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
10279
|
+
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]
|
|
10279
10280
|
colab ship --batch <b1,b2[,b3]> [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
|
|
10280
10281
|
|
|
10281
10282
|
The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
|
|
@@ -10371,6 +10372,19 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
|
|
|
10371
10372
|
\`Colab-Adopted: origin/<br> @ <sha> on <host> (machine <id>)\` trailer. A LOCAL no-digit branch is
|
|
10372
10373
|
still a legitimate zero. --adopt never bypasses a branch that names issues.
|
|
10373
10374
|
|
|
10375
|
+
A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
|
|
10376
|
+
\`colab ship --branch <br> --handoff <url>\`, where <url> is the executor's hand-off comment
|
|
10377
|
+
(…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
|
|
10378
|
+
name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
|
|
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
|
|
10381
|
+
live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
|
|
10382
|
+
claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
|
|
10383
|
+
the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
|
|
10384
|
+
🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
|
|
10385
|
+
the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
|
|
10386
|
+
--batch or --direct, and not when this machine already holds a claim on the branch.
|
|
10387
|
+
|
|
10374
10388
|
UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
|
|
10375
10389
|
--session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
|
|
10376
10390
|
(--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
|
|
@@ -11897,8 +11911,13 @@ function cmdShipDryJson(opts) {
|
|
|
11897
11911
|
const trunk = resolveTrunk(repoAbs, doc);
|
|
11898
11912
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
11899
11913
|
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
|
|
11900
11915
|
|
|
11901
11916
|
const checks = [];
|
|
11917
|
+
if (handoff) {
|
|
11918
|
+
checks.push({ name: 'hand-off verified (#578)', ok: handoff.ok, class: handoff.ok ? null : HUMAN_GATED,
|
|
11919
|
+
detail: handoff.ok ? handoffDetail(handoff) : `${handoff.reason}: ${handoff.detail}` });
|
|
11920
|
+
}
|
|
11902
11921
|
let target = null;
|
|
11903
11922
|
// #74/#263: the close-gate split (closeIssues/refsIssues/checklistFindings) is reported
|
|
11904
11923
|
// ALONGSIDE `checks` AS WELL AS folded into it — `closeIssues`/`refsIssues`/`checklistFindings`
|
|
@@ -12968,6 +12987,62 @@ function autonomyGatePayload(gate) {
|
|
|
12968
12987
|
}
|
|
12969
12988
|
|
|
12970
12989
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
12990
|
+
/**
|
|
12991
|
+
* #578 — `--handoff <comment-url>`: verify the executor's recorded hand-off and, when it holds, take
|
|
12992
|
+
* the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
|
|
12993
|
+
* without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
|
|
12994
|
+
*
|
|
12995
|
+
* Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
|
|
12996
|
+
* this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
|
|
12997
|
+
*/
|
|
12998
|
+
function applyShipHandoff(repoAbs, sess, opts) {
|
|
12999
|
+
if (!opts.handoff) return null;
|
|
13000
|
+
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
|
+
if (sess.issues.length) {
|
|
13002
|
+
throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
|
|
13003
|
+
`for ${sess.branch} — ship it without --handoff`);
|
|
13004
|
+
}
|
|
13005
|
+
const u = shipHandoff.parseHandoffUrl(opts.handoff);
|
|
13006
|
+
let comment = null;
|
|
13007
|
+
if (u) {
|
|
13008
|
+
const r = git.ghApi(repoAbs, [`repos/{owner}/{repo}/issues/comments/${u.commentId}`]);
|
|
13009
|
+
if (r.ok) {
|
|
13010
|
+
try {
|
|
13011
|
+
const j = JSON.parse(r.stdout);
|
|
13012
|
+
comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
|
|
13013
|
+
} catch (_) { comment = null; }
|
|
13014
|
+
}
|
|
13015
|
+
}
|
|
13016
|
+
// The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
|
|
13017
|
+
const remote = git.remoteFor(repoAbs);
|
|
13018
|
+
if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
|
|
13019
|
+
const refs = git.branchRefs(repoAbs, sess.branch, remote);
|
|
13020
|
+
const claimsByIssue = {};
|
|
13021
|
+
if (u && comment) {
|
|
13022
|
+
for (const n of shipguard.branchIssueNumbers(sess.branch)) {
|
|
13023
|
+
const info = git.ghIssueView(repoAbs, n, ['comments']);
|
|
13024
|
+
claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
|
|
13025
|
+
}
|
|
13026
|
+
}
|
|
13027
|
+
const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue });
|
|
13028
|
+
if (!v.ok) return v;
|
|
13029
|
+
sess.issues = v.issues;
|
|
13030
|
+
sess.handoff = v;
|
|
13031
|
+
// #372: the implementer is the executor that handed off — name it, never leave it reading as the shipper.
|
|
13032
|
+
const ex = (claimsByIssue[v.issues[0]] || []).find((c) => c.branch === sess.branch && c.login === v.executor.login);
|
|
13033
|
+
if (ex && (ex.session || ex.sessionName)) sess.holder = { session: ex.session || '', sessionName: ex.sessionName || '' };
|
|
13034
|
+
return v;
|
|
13035
|
+
}
|
|
13036
|
+
|
|
13037
|
+
function handoffDetail(v) {
|
|
13038
|
+
return `${v.url} hands off ${shortSha(v.sha)} = the remote head; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
|
|
13039
|
+
}
|
|
13040
|
+
|
|
13041
|
+
/** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
|
|
13042
|
+
function handoffEvidence(v) {
|
|
13043
|
+
return v ? ` · landed from the executor's hand-off ${v.url} — its claim and worktree stay until it confirms the land` : '';
|
|
13044
|
+
}
|
|
13045
|
+
|
|
12971
13046
|
function shipRefFor(repoAbs, branch) {
|
|
12972
13047
|
const r = git.branchRefs(repoAbs, branch);
|
|
12973
13048
|
return r.localSha || r.remoteSha || branch;
|
|
@@ -12975,7 +13050,7 @@ function shipRefFor(repoAbs, branch) {
|
|
|
12975
13050
|
|
|
12976
13051
|
function cmdShip(argv) {
|
|
12977
13052
|
const opts = parseArgs(argv, {
|
|
12978
|
-
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
|
|
13053
|
+
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
|
|
12979
13054
|
// #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
|
|
12980
13055
|
// `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
|
|
12981
13056
|
// accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
|
|
@@ -12990,6 +13065,8 @@ function cmdShip(argv) {
|
|
|
12990
13065
|
// — refuse the combination rather than silently ignore --json on a real ship.
|
|
12991
13066
|
if (opts.json && !opts.dry) throw new UserError('--json currently only applies together with --dry — see `colab ship --help`');
|
|
12992
13067
|
if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
|
|
13068
|
+
// #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
|
|
13069
|
+
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\`)`);
|
|
12993
13070
|
if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
|
|
12994
13071
|
// A fully separate code path, deliberately: the prose/table path below is unchanged by this
|
|
12995
13072
|
// feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
|
|
@@ -13007,6 +13084,17 @@ function cmdShip(argv) {
|
|
|
13007
13084
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
13008
13085
|
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)`);
|
|
13009
13086
|
|
|
13087
|
+
// #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
|
|
13088
|
+
// branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
|
|
13089
|
+
// remote-only branch resolve here at all.
|
|
13090
|
+
const handoff = applyShipHandoff(repoAbs, sess, opts);
|
|
13091
|
+
if (handoff && !handoff.ok) {
|
|
13092
|
+
process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
|
|
13093
|
+
`ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
|
|
13094
|
+
process.stderr.write(' Nothing was claimed or taken over here — the executor\'s claim still stands.\n');
|
|
13095
|
+
return 1;
|
|
13096
|
+
}
|
|
13097
|
+
|
|
13010
13098
|
// ---- the recorded branch must RESOLVE, before anything else is computed ----
|
|
13011
13099
|
// Everything downstream is keyed to this name: the claim lookup above, the migration diff, the
|
|
13012
13100
|
// squash. A worktree record holding a role word or a deleted branch fails all three quietly —
|
|
@@ -13066,6 +13154,7 @@ function cmdShip(argv) {
|
|
|
13066
13154
|
const gh = isGhUsable(repoAbs);
|
|
13067
13155
|
// #345: the gate that passed is the table's first row, so a reader sees WHICH door opened it.
|
|
13068
13156
|
const checks = [['✓', 'autonomy granted', autonomyGate.detail]];
|
|
13157
|
+
if (handoff) checks.push(['✓', 'hand-off verified (#578)', handoffDetail(handoff)]);
|
|
13069
13158
|
|
|
13070
13159
|
// Which claimed issues are REFERENCED (Refs #N), not closed — three sources unioned by
|
|
13071
13160
|
// resolveCloseRefsSplit (#48, #74): --refs, the tracking label, and #74's close gate (an
|
|
@@ -13738,7 +13827,7 @@ function cmdShip(argv) {
|
|
|
13738
13827
|
(publicOmit ? (m) => print(` ${m}`) : warn)(`Machine trailer ${machineTrailerSummary(trailerDecision)}`);
|
|
13739
13828
|
}
|
|
13740
13829
|
const machineLine = trailerDecision.line;
|
|
13741
|
-
const ciTrailerLines = [ciTrailer, adoptTrailer, machineLine].filter(Boolean);
|
|
13830
|
+
const ciTrailerLines = [ciTrailer, adoptTrailer, shipHandoff.handoffTrailer(sess.handoff), machineLine].filter(Boolean);
|
|
13742
13831
|
if (opts.message) {
|
|
13743
13832
|
// --message overrides the subject/body, but Closes is spliced in as its own paragraph — never
|
|
13744
13833
|
// concatenated. Appending it welded ` — Closes #N` onto whatever the message ended with, which
|
|
@@ -13747,7 +13836,7 @@ function cmdShip(argv) {
|
|
|
13747
13836
|
for (const tl of ciTrailerLines) {
|
|
13748
13837
|
if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
|
|
13749
13838
|
const lastLine = commitMsg.split('\n').pop().trim();
|
|
13750
|
-
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
13839
|
+
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
13751
13840
|
}
|
|
13752
13841
|
} else {
|
|
13753
13842
|
// Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
|
|
@@ -13957,7 +14046,7 @@ function cmdShip(argv) {
|
|
|
13957
14046
|
pushEvent('ship', {
|
|
13958
14047
|
repo: repoAbs, worktree: sess.name, session: sess.session,
|
|
13959
14048
|
issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
|
|
13960
|
-
payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}) },
|
|
14049
|
+
payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}), ...(sess.handoff ? { handoff: { url: sess.handoff.url, sha: sess.handoff.sha } } : {}) },
|
|
13961
14050
|
});
|
|
13962
14051
|
|
|
13963
14052
|
// Then, PER ISSUE, a merge-completion event (#46 §2, following #45 §2). The ship event above is
|
|
@@ -13979,11 +14068,12 @@ function cmdShip(argv) {
|
|
|
13979
14068
|
// window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
|
|
13980
14069
|
// same block, and re-assigning the collector here would silently discard them.
|
|
13981
14070
|
shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
|
|
13982
|
-
evidenceExtra: opts.humanDoorEvidence || '' }); // #525
|
|
14071
|
+
evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
|
|
13983
14072
|
|
|
13984
14073
|
print('');
|
|
13985
14074
|
print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
|
|
13986
14075
|
if (adoptInfo) print(` adopted from ${adoptInfo.remote || 'origin'}/${adoptInfo.branch} @ ${shortSha(adoptInfo.remoteSha)} — recorded in the Colab-Adopted: trailer (#324)`);
|
|
14076
|
+
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)`);
|
|
13987
14077
|
if (target !== trunk) print(` "${target}" is a declared line: this work is NOT in ${trunk} until a human merges the line.`);
|
|
13988
14078
|
// #114: everything deferred since the push (e2, #304) lands here, AFTER the success line — not scattered above it
|
|
13989
14079
|
// where a long ship scrolls it out of view. The merge itself already landed either way; this is
|
|
@@ -14025,7 +14115,8 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
|
|
|
14025
14115
|
// B3 (cont.) — the shipped branch. Kept by default; --delete-branch opts in. MUST come after the
|
|
14026
14116
|
// worktree removal above: git refuses to delete a branch checked out in a worktree.
|
|
14027
14117
|
// #368: a Refs-only ship deletes unless --keep-branch — see tools/lib/shipped-branch.js.
|
|
14028
|
-
|
|
14118
|
+
// #578: a handed-off branch is the executor's until it confirms the land — never deleted for it.
|
|
14119
|
+
const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch || (!!sess.handoff && !opts.deleteBranch) });
|
|
14029
14120
|
handleShippedBranch(repoAbs, target, sess.branch, { disposition, worktreeKept, integration });
|
|
14030
14121
|
|
|
14031
14122
|
// ---- (g/h) B4 verify + post summary per issue ----
|
|
@@ -55,7 +55,7 @@ function releaseComments(sorted) {
|
|
|
55
55
|
|
|
56
56
|
/**
|
|
57
57
|
* Live claim comments on an issue. Returns [{login, host, machine, session, sessionName, at,
|
|
58
|
-
* identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
|
|
58
|
+
* branch, worktree, identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
|
|
59
59
|
* is built from `comps` (claim-identity.js `components()`, #267); the raw fields are returned too
|
|
60
60
|
* for callers that need `sameClaimant`'s degrade-on-missing comparison.
|
|
61
61
|
*
|
|
@@ -91,7 +91,8 @@ function liveClaimComments(comments, comps) {
|
|
|
91
91
|
const { host, session, sessionName } = claim;
|
|
92
92
|
const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
|
|
93
93
|
const at = c.createdAt;
|
|
94
|
-
|
|
94
|
+
// #578: branch/worktree ride along so a reader can ask WHICH branch a live claim holds.
|
|
95
|
+
const entry = { login, host, machine: machineTok, session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
|
|
95
96
|
const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
|
|
96
97
|
|| (r.login === login && !isNamedWinner(entry, r.winner))));
|
|
97
98
|
if (!cancelled) live.push({ ...entry, identity: claimIdentity.identityString({ login, host, session }, comps) });
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #578 — `colab ship --branch <br> --handoff <comment-url>`: land a branch whose claim lives on
|
|
4
|
+
* ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
|
|
5
|
+
*
|
|
6
|
+
* The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
|
|
7
|
+
* A branch built and wrapped on machine A and landed from machine B has its claim in A's registry,
|
|
8
|
+
* so on B ship reads zero claims and refuses (#153 / #324). The only way to write a record on B was
|
|
9
|
+
* `colab claim --force` — a human-only takeover — so an agent lander had no sanctioned path, and
|
|
10
|
+
* every remote-built branch waited for a person even when it had passed review and merged clean.
|
|
11
|
+
*
|
|
12
|
+
* The door. The executor has already said, on the tracker, which branch it handed off and at which
|
|
13
|
+
* head. That comment, checked against git and against the executor's own live claim, is the
|
|
14
|
+
* evidence ship would otherwise get from a local claim. Nothing on B's registry is written and
|
|
15
|
+
* nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
|
|
16
|
+
* (its own `colab worktree rm`, which releases the claim as usual).
|
|
17
|
+
*
|
|
18
|
+
* What a hand-off must prove, in order — the first failure is the verdict:
|
|
19
|
+
* 1. the URL is an issue-comment URL (`…/issues/<N>#issuecomment-<id>`);
|
|
20
|
+
* 2. the comment was read from THIS repo (fetched through `{owner}/{repo}`, so an off-repo id is a
|
|
21
|
+
* 404) and its own html_url names the same issue the URL does;
|
|
22
|
+
* 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
|
|
23
|
+
* issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
|
|
24
|
+
* 4. the body names the branch, as a whole token;
|
|
25
|
+
* 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
|
|
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;
|
|
28
|
+
* 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
|
|
29
|
+
* the hand-off's author before the hand-off — the claim really does live elsewhere, and the
|
|
30
|
+
* party handing off is the party holding it.
|
|
31
|
+
*
|
|
32
|
+
* Pure: every input is already read. tools/colab does the IO (`gh api`, `git fetch`, issue views).
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
const { branchIssueNumbers } = require('./branch-name');
|
|
36
|
+
|
|
37
|
+
/** `https://github.com/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE). */
|
|
38
|
+
function parseHandoffUrl(url) {
|
|
39
|
+
const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
|
|
40
|
+
if (!m) return null;
|
|
41
|
+
return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
|
|
45
|
+
|
|
46
|
+
/** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
|
|
47
|
+
function namesBranch(body, branch) {
|
|
48
|
+
if (!branch) return false;
|
|
49
|
+
return new RegExp(`(^|[^A-Za-z0-9._/-])${escapeRe(branch)}(?![A-Za-z0-9._/-])`).test(String(body || ''));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Every 7–40 hex token in `body`, lower-cased — the candidate head shas a hand-off names. */
|
|
53
|
+
function namedShas(body) {
|
|
54
|
+
return [...String(body || '').matchAll(/(?<![0-9A-Za-z])([0-9a-fA-F]{7,40})(?![0-9A-Za-z])/g)]
|
|
55
|
+
.map((m) => m[1].toLowerCase());
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The verdict. Inputs:
|
|
60
|
+
* url — the --handoff value
|
|
61
|
+
* comment — { body, login, createdAt, htmlUrl } as read from THIS repo, or null (unreadable)
|
|
62
|
+
* branch — the branch being shipped
|
|
63
|
+
* refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
|
|
64
|
+
* claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
|
|
65
|
+
* or null for an issue whose comments could not be read
|
|
66
|
+
* Returns { ok: true, issues, sha, executor, url } or { ok: false, reason, detail }.
|
|
67
|
+
*/
|
|
68
|
+
function handoffVerdict({ url, comment, branch, refs, claimsByIssue }) {
|
|
69
|
+
const no = (reason, detail) => ({ ok: false, reason, detail });
|
|
70
|
+
const u = parseHandoffUrl(url);
|
|
71
|
+
if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
|
|
72
|
+
if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
|
|
73
|
+
const got = parseHandoffUrl(comment.htmlUrl);
|
|
74
|
+
if (!got || got.commentId !== u.commentId || got.issue !== u.issue ||
|
|
75
|
+
got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
|
|
76
|
+
return no('mismatch', `the URL says ${u.owner}/${u.repo}#${u.issue}, but comment ${u.commentId} is ${comment.htmlUrl || 'somewhere else'}`);
|
|
77
|
+
}
|
|
78
|
+
const issues = branchIssueNumbers(branch);
|
|
79
|
+
if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
|
|
80
|
+
if (!issues.includes(u.issue)) return no('not-this-branch', `the hand-off is on #${u.issue}, which ${branch} does not carry (${issues.map((n) => '#' + n).join(' ')})`);
|
|
81
|
+
if (!namesBranch(comment.body, branch)) return no('branch-not-named', `the hand-off comment does not name the branch ${branch}`);
|
|
82
|
+
if (!refs || !refs.remoteSha) return no('no-remote-branch', `${branch} is not on the remote — a hand-off lands a pushed branch only`);
|
|
83
|
+
// Ship merges the local ref when one exists (shipRefFor), so it must BE the remote head: a stale
|
|
84
|
+
// copy a DWIM checkout made earlier would land a sha the hand-off never named.
|
|
85
|
+
if (refs.localSha && refs.localSha !== refs.remoteSha) {
|
|
86
|
+
return no('local-diverges', refs.localFromRemote
|
|
87
|
+
? `this machine's ${branch} (${refs.localSha.slice(0, 8)}, created from the remote by an earlier checkout) is behind or apart from the remote's (${refs.remoteSha.slice(0, 8)}) — reset it to the remote's (git branch -f ${branch} <remote>/${branch}, from a checkout not on it) and re-run`
|
|
88
|
+
: `this machine has its own ${branch} (${refs.localSha.slice(0, 8)}) that differs from the remote's (${refs.remoteSha.slice(0, 8)}) — not a remote-built branch here`);
|
|
89
|
+
}
|
|
90
|
+
const head = String(refs.remoteSha).toLowerCase();
|
|
91
|
+
const shas = namedShas(comment.body);
|
|
92
|
+
if (!shas.some((s) => head.startsWith(s))) {
|
|
93
|
+
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`
|
|
95
|
+
: `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
|
|
96
|
+
}
|
|
97
|
+
let executor = null;
|
|
98
|
+
for (const n of issues) {
|
|
99
|
+
const live = claimsByIssue ? claimsByIssue[n] : null;
|
|
100
|
+
if (!live) return no('claims-unreadable', `#${n}'s comments could not be read — the executor's claim cannot be checked`);
|
|
101
|
+
const match = live.find((c) => c.branch === branch && c.login === comment.login && c.at < comment.createdAt);
|
|
102
|
+
if (!match) {
|
|
103
|
+
return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off — ` +
|
|
104
|
+
'the hand-off must come from the party holding the claim');
|
|
105
|
+
}
|
|
106
|
+
if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
|
|
107
|
+
}
|
|
108
|
+
return { ok: true, issues, sha: refs.remoteSha, executor, url: String(url).trim() };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** The squash trailer recording the door the issue set came through. */
|
|
112
|
+
function handoffTrailer(v) {
|
|
113
|
+
return v && v.ok ? `Colab-Handoff: ${v.url} @ ${String(v.sha).slice(0, 12)}` : '';
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer };
|