@futurelastic/colab-handbook 1.13.0-rc.52 → 1.13.0-rc.53

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.52"
36
+ "version": "1.13.0-rc.53"
37
37
  }
package/tools/colab CHANGED
@@ -77,6 +77,7 @@ const releaseCut = require('./lib/release-cut');
77
77
  const releaseFinalize = require('./lib/release-finalize');
78
78
  const releaseChannel = require('./lib/release-channel');
79
79
  const shippedBranch = require('./lib/shipped-branch');
80
+ const landedPrs = require('./lib/landed-prs');
80
81
  const shipRoles = require('./lib/ship-roles'); // #372
81
82
  const shipHandoff = require('./lib/ship-handoff'); // #578
82
83
  const refsBrake = require('./lib/refs-brake'); // #385
@@ -4513,7 +4514,8 @@ CI grant merges into a repo whose own test suite is known-failing:
4513
4514
  for the BRANCH's own current head (the same "ask by sha" check \`ship\` itself uses) — a human's
4514
4515
  say-so alone is never enough. \`--evidence-run\` is a RECORDING-ONLY pointer for the audit trail;
4515
4516
  it can never substitute for the measured run. If the branch has no run yet, open a PR for it
4516
- (\`gh pr create\`) and let CI finish, then re-run this command.
4517
+ (\`gh pr create\`) and let CI finish, then re-run this command. You do not need to close that
4518
+ PR afterwards: \`colab ship\` closes it once the branch lands (#584).
4517
4519
  2. NEVER STACKS. Creating a grant refuses outright if trunk is not currently red (nothing to
4518
4520
  exempt), and refuses again if a PRIOR ci-grant already merged something and trunk has been red
4519
4521
  continuously since — a second exemption on a still-broken repo is exactly the failure this gate
@@ -4862,7 +4864,7 @@ function cmdCiGrantCreate(repoAbs, num, opts) {
4862
4864
  throw new UserError(
4863
4865
  `"${opts.branch}" has no completed, successful CI run for its current head (${shortSha(evRun.sha)}) — ` +
4864
4866
  `a CI grant requires MEASURED evidence, never a human's say-so alone. Open a PR for it ` +
4865
- `(\`gh pr create\`) and let CI finish, then re-run this command.`);
4867
+ `(\`gh pr create\`) and let CI finish, then re-run this command — \`colab ship\` closes that PR once the branch lands (#584).`);
4866
4868
  }
4867
4869
  const evidenceSha = evRun.sha;
4868
4870
 
@@ -6329,6 +6331,9 @@ in a cleanup cron.
6329
6331
  reported but never deleted (a label a triage session just created and has not
6330
6332
  applied yet is indistinguishable from one whose members were all transferred
6331
6333
  away — the labels API exposes no creation time, so a human decides).
6334
+ Also lists open PRs whose head commit already landed in trunk (#584) — CI-trigger
6335
+ PRs a squash ship left open. Report-only, --prune included: doctor never closes
6336
+ a PR. A PR whose head is not in the local clone is not judged.
6332
6337
  `;
6333
6338
 
6334
6339
  const EMPTY_SET = new Set();
@@ -6413,7 +6418,7 @@ function cmdDoctor(argv) {
6413
6418
  const report = { deadWorktrees: [], orphanClaims: [], staleClaims: [], stalePlaces: [], unprovablePlaces: [], releasedPlaces: [], orphanPorts: [], brokenRecords: [], prunedPorts: [],
6414
6419
  renamedHostRecords: [], unprovenHostRecords: [],
6415
6420
  mergedFlips: [], mergedSweep: [], mergedDirty: [], mergedHookFail: [], mergedRemoveFail: [], shippedBranches: [], ghostPorts: [],
6416
- spentGroupLabels: [], groupLabelsChecked: !!opts.sync, pruned: !!opts.prune };
6421
+ spentGroupLabels: [], groupLabelsChecked: !!opts.sync, landedPrs: [], landedPrsUnread: [], pruned: !!opts.prune };
6417
6422
 
6418
6423
  // One answer per (repo, branch) — pass 5b asks about the same branch from a worktree and from each
6419
6424
  // of its claims, and every miss costs two `git rev-parse` calls.
@@ -6804,6 +6809,28 @@ function cmdDoctor(argv) {
6804
6809
  }
6805
6810
  }
6806
6811
 
6812
+ // 9b. open PRs whose head already landed (#584) — the CI-trigger PRs a squash ship left open before
6813
+ // ship learned to close them, or that a ship on another machine could not close. Report-only,
6814
+ // --prune included: closing a PR is a write on a shared forge, and a human may still want it.
6815
+ // Behind --sync for the same reason as pass 9 (network). A PR whose head commit is not in this
6816
+ // clone is not judged — the answer would be a guess — so the list is honest, not exhaustive.
6817
+ if (opts.sync && git.ghAvailable()) {
6818
+ const repos = [...new Set([...(config.repos || []), ...knownRepos(config)].map((r) => path.resolve(r)))]
6819
+ .filter((r) => repoLive(r) && git.remoteUrl(r));
6820
+ for (const repo of repos) {
6821
+ const trunk = resolveTrunk(repo, projectDoc(repo));
6822
+ if (!trunk) continue;
6823
+ const listed = git.ghOpenPrs(repo);
6824
+ if (listed.error) { report.landedPrsUnread.push({ repo: shortRepo(repo), error: listed.error }); continue; }
6825
+ for (const pr of listed.prs) {
6826
+ if (!pr.headRefOid || pr.headRefName === trunk) continue;
6827
+ if (!git.git(['cat-file', '-e', `${pr.headRefOid}^{commit}`], repo).ok) continue;
6828
+ if (landed.landedState(repo, trunk, pr.headRefOid).state !== 'landed') continue;
6829
+ report.landedPrs.push({ repo: shortRepo(repo), number: pr.number, url: pr.url || '', branch: pr.headRefName || '', trunk });
6830
+ }
6831
+ }
6832
+ }
6833
+
6807
6834
  // 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
6808
6835
  // the verdict — it is configuration, not state drift. Silent on a machine with no
6809
6836
  // <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
@@ -6953,6 +6980,17 @@ function cmdDoctor(argv) {
6953
6980
  print(' NOT exhaustive: a branch whose work trunk later rewrote can conflict against trunk');
6954
6981
  print(' instead of matching it, and is omitted here rather than risk calling unmerged work spent.');
6955
6982
  }
6983
+ // #584 — after the verdict, not counted: an open PR on a landed branch breaks nothing, it reads as
6984
+ // unmerged work on a tracker. Printed only under --sync.
6985
+ if (report.landedPrs.length) {
6986
+ print('');
6987
+ print(`Open PRs whose branch already landed (${report.landedPrs.length}) — the squash left them open:`);
6988
+ for (const p of report.landedPrs) print(` #${p.number} ${p.branch} [${p.repo}] → in ${p.trunk}${p.url ? ` ${p.url}` : ''}`);
6989
+ print(' `colab ship` closes these itself since #584; these predate that, or a ship could not close them.');
6990
+ print(' doctor never closes a PR, --prune included. To close one:');
6991
+ print(` gh pr close ${report.landedPrs[0].number} --comment "Landed on ${report.landedPrs[0].trunk} by squash." # in ${report.landedPrs[0].repo}`);
6992
+ }
6993
+ for (const u of report.landedPrsUnread) warn(`could not list open PRs in ${u.repo} (${u.error}) — landed-PR check skipped there`);
6956
6994
  // Also after the verdict, and also not drift: a spent group label breaks nothing, it is picker
6957
6995
  // noise on a tracker. Printed only under --sync, so silence here NEVER means "checked, clean" —
6958
6996
  // which is why a --sync run that finds nothing says so explicitly below.
@@ -14085,11 +14123,13 @@ function cmdShip(argv) {
14085
14123
  // a long ship these lines would otherwise scroll off above the `✓ Shipped` line — which is
14086
14124
  // exactly how #304's failure went unnoticed in the first place.
14087
14125
  deferredCollector = [];
14126
+ let reviewPrHandled = null; // #584: the #350 review PR, already closed (or warned about) above
14088
14127
  // #350: the approved PR is spent — its work landed by squash, which the forge cannot see as a merge.
14089
14128
  if (coreReview.verdict === 'approved' && coreReview.pr && gh) {
14090
14129
  const closed = git.ghPrClose(repoAbs, coreReview.pr.number, `Landed on \`${target}\` as ${sha} by \`colab ship\` (#350), approved by ${coreReview.approval.by}.`);
14091
14130
  if (closed.ok) print(` closed PR #${coreReview.pr.number} (landed as ${sha})`);
14092
14131
  else warnDeferred(`could not close PR #${coreReview.pr.number} (${(closed.stderr || '').split('\n')[0]}) — it landed as ${sha}; close it by hand`);
14132
+ reviewPrHandled = coreReview.pr.number; // #584: either way the tail's landed-PR close must not touch it again
14093
14133
  }
14094
14134
  // Only when the target IS the shared checkout. `ephemeralTarget === false` means
14095
14135
  // `targetDir === repoAbs` (see #234's note above); a declared integration line merged in a
@@ -14155,6 +14195,7 @@ function cmdShip(argv) {
14155
14195
  // window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
14156
14196
  // same block, and re-assigning the collector here would silently discard them.
14157
14197
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
14198
+ skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
14158
14199
  evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
14159
14200
 
14160
14201
  print('');
@@ -14174,6 +14215,38 @@ function cmdShip(argv) {
14174
14215
  }
14175
14216
 
14176
14217
 
14218
+ /**
14219
+ * #584: close every open PR whose head is the branch this ship just landed — the PR a person or an
14220
+ * automation opened only to obtain branch CI. The forge never sees a squash as a merge of that PR, so
14221
+ * without this it stays open forever, reading as unmerged work. Only a PR whose head commit is the
14222
+ * landed tip (or an ancestor of it) is closed; one carrying commits that did not land is kept and
14223
+ * reported. Best-effort throughout: every failure defers a warning, none fails the ship.
14224
+ */
14225
+ function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
14226
+ const remoteName = git.remoteInfo(repoAbs).name || 'origin';
14227
+ const tipOf = (ref) => { const r = git.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoAbs); return r.ok ? r.stdout.trim() : null; };
14228
+ const tip = tipOf(`refs/heads/${sess.branch}`) || tipOf(`refs/remotes/${remoteName}/${sess.branch}`);
14229
+ const headLanded = (oid) => {
14230
+ if (!tip) return false;
14231
+ if (oid === tip) return true;
14232
+ return git.git(['merge-base', '--is-ancestor', oid, tip], repoAbs).ok;
14233
+ };
14234
+ const res = landedPrs.closeLandedPrs({
14235
+ prs: git.ghOpenPrsForBranch(repoAbs, sess.branch),
14236
+ headLanded,
14237
+ close: (n, comment) => git.ghPrClose(repoAbs, n, comment),
14238
+ comment: landedPrs.landedPrComment({ target, sha, issues }),
14239
+ skip,
14240
+ });
14241
+ if (res.listError) {
14242
+ warnDeferred(`could not list open PRs for ${sess.branch} (${res.listError}) — any PR opened for its CI is still open; close it by hand (it landed as ${sha})`);
14243
+ return;
14244
+ }
14245
+ for (const n of res.closed) print(` closed PR #${n} — its branch ${sess.branch} landed as ${sha} (#584)`);
14246
+ for (const f of res.failed) warnDeferred(`could not close PR #${f.number} (${f.error}) — ${sess.branch} landed as ${sha}; close it by hand`);
14247
+ for (const k of res.kept) warnDeferred(`kept PR #${k.number} open: ${k.reason} (${sess.branch} landed as ${sha}) — it carries work that did not ship`);
14248
+ }
14249
+
14177
14250
  /**
14178
14251
  * The post-merge tail every landed branch gets — cmdShip's B3 through i2, moved here unchanged (#373)
14179
14252
  * so a batch member gets exactly the same steps in the same order: worktree teardown (B3), the claims
@@ -14182,7 +14255,13 @@ function cmdShip(argv) {
14182
14255
  * addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
14183
14256
  * batch member.
14184
14257
  */
14185
- function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '' }) {
14258
+ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
14259
+ // #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
14260
+ // B3 below may delete it, and "did the PR's head land?" is answered against that tip.
14261
+ if (gh && sess.branch) {
14262
+ try { shipCloseLandedPrs(repoAbs, sess, { target, sha, issues: closeIssues, skip: skipPrs }); }
14263
+ catch (e) { warnDeferred(`landed-PR close for ${sess.branch} failed (${e.message}) — the ship landed as ${sha}; close any PR for it by hand`); }
14264
+ }
14186
14265
  const worktreeKept = !!(sess.name && opts.keepWorktree);
14187
14266
  if (sess.name && !opts.keepWorktree) {
14188
14267
  print(`B3: removing worktree ${sess.name} …`);
package/tools/lib/git.js CHANGED
@@ -691,6 +691,30 @@ function ghPrForBranch(repo, branch) {
691
691
  } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
692
692
  }
693
693
 
694
+ /**
695
+ * #584: EVERY open pull request whose head is `branch` — not just the first, as ghPrForBranch
696
+ * returns — so `colab ship` can close each CI-trigger PR its squash left behind. `{ prs }` on
697
+ * success (possibly empty), `{ error }` when the read failed; never conflate the two.
698
+ */
699
+ function ghOpenPrsForBranch(repo, branch) {
700
+ const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
701
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
702
+ try {
703
+ const list = JSON.parse(r.stdout || '[]');
704
+ return { prs: Array.isArray(list) ? list : [] };
705
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
706
+ }
707
+
708
+ /** #584: every open pull request in the repo, for `colab doctor --sync`'s landed-PR listing. */
709
+ function ghOpenPrs(repo) {
710
+ const r = gh(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
711
+ if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
712
+ try {
713
+ const list = JSON.parse(r.stdout || '[]');
714
+ return { prs: Array.isArray(list) ? list : [] };
715
+ } catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
716
+ }
717
+
694
718
  /**
695
719
  * #367: the forge's visibility for this repo — "PUBLIC" | "PRIVATE" | "INTERNAL" — or null when it
696
720
  * could not be read (no gh, no GitHub remote, offline). Null is "could not read", never "private":
@@ -1401,5 +1425,5 @@ module.exports = {
1401
1425
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1402
1426
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1403
1427
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1404
- ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,
1428
+ ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
1405
1429
  };
@@ -0,0 +1,58 @@
1
+ 'use strict';
2
+ /**
3
+ * #584: a pull request opened only to obtain branch CI stays open forever once `colab ship`
4
+ * squash-lands its branch — the squash is a NEW commit, so the forge never sees the PR's head land,
5
+ * and nothing else closes it. Measured 2026-10-10: five such PRs open on two repos, all landed, the
6
+ * oldest 15 days old, each reading as unmerged work waiting for review.
7
+ *
8
+ * Pure rules only — tools/colab owns the gh calls. Two rules:
9
+ *
10
+ * 1. Close a PR only when its head commit LANDED: the PR head is the landed branch tip, or an
11
+ * ancestor of it. A PR head carrying commits the ship did NOT include (pushed to the remote
12
+ * branch after the local tip was cut, or from another machine) is KEPT, with a warning — closing
13
+ * it would hide work that is not on trunk.
14
+ * 2. Best-effort. A failed list or close is a warning, never a failed ship: the merge already landed
15
+ * and is pushed, so a non-zero exit here would read as "ship failed" and invite a re-merge.
16
+ */
17
+
18
+ /** The comment a closed PR carries — the same shape as #350's close: where it landed, and why. */
19
+ function landedPrComment({ target, sha, issues }) {
20
+ const nums = (issues || []).map((n) => `#${n}`).join(' ');
21
+ return `Landed on \`${target}\` as ${sha} by \`colab ship\`${nums ? ` (${nums})` : ''}. ` +
22
+ 'The branch was squash-merged, which the forge cannot see as a merge of this PR, so ship closes it (#584).';
23
+ }
24
+
25
+ /**
26
+ * Decide and act on every open PR whose head is the landed branch.
27
+ *
28
+ * prs — the open PRs listed for the branch, as git.ghOpenPrsForBranch returns them:
29
+ * { prs: [{ number, headRefOid, url }] } or { error }
30
+ * headLanded — (oid) => true when that commit is in what landed (tip or ancestor); false otherwise
31
+ * close — (number, comment) => { ok, stderr }
32
+ * comment — the closing comment (landedPrComment)
33
+ * skip — PR numbers already handled by another path (#350's approved review PR)
34
+ *
35
+ * Returns { closed: [n], kept: [{ number, reason }], failed: [{ number, error }], listError }.
36
+ */
37
+ function closeLandedPrs({ prs, headLanded, close, comment, skip = [] }) {
38
+ const out = { closed: [], kept: [], failed: [], listError: null };
39
+ if (!prs || prs.error || !Array.isArray(prs.prs)) { out.listError = (prs && prs.error) || 'could not list open PRs'; return out; }
40
+ const skipSet = new Set(skip.map(Number));
41
+ for (const pr of prs.prs) {
42
+ const number = Number(pr.number);
43
+ if (!Number.isFinite(number) || skipSet.has(number)) continue;
44
+ let landed = false;
45
+ try { landed = !!(pr.headRefOid && headLanded(pr.headRefOid)); } catch (_) { landed = false; }
46
+ if (!landed) {
47
+ out.kept.push({ number, reason: `its head ${String(pr.headRefOid || '?').slice(0, 12)} is not in what landed` });
48
+ continue;
49
+ }
50
+ let r;
51
+ try { r = close(number, comment); } catch (e) { r = { ok: false, stderr: e.message }; }
52
+ if (r && r.ok) out.closed.push(number);
53
+ else out.failed.push({ number, error: ((r && r.stderr) || 'gh pr close failed').split('\n')[0] });
54
+ }
55
+ return out;
56
+ }
57
+
58
+ module.exports = { landedPrComment, closeLandedPrs };