@futurelastic/colab-handbook 1.17.0-rc.1 → 1.17.0-rc.3

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.17.0-rc.1"
36
+ "version": "1.17.0-rc.3"
37
37
  }
package/tools/colab CHANGED
@@ -11106,6 +11106,9 @@ It never waits: each call reads the remote, takes ONE step and exits —
11106
11106
  One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
11107
11107
  is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
11108
11108
  for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
11109
+ A call that goes serial on trunk CI not green gives up on its members, so it deletes every batch at
11110
+ trunk's tip whose members it ALL names (its run cancelled if still going) — nobody would ever land
11111
+ it, and it would hold this base for every later call; a batch also carrying another member stays (#656).
11109
11112
  The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref at trunk's tip has its
11110
11113
  combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
11111
11114
  \`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
@@ -13440,13 +13443,19 @@ function readTargetCodeowners(repoAbs, target) {
13440
13443
 
13441
13444
  /**
13442
13445
  * #483: is this repo a fork, and which org owns it? The fork test is adopt's own (#449: a remote named
13443
- * `upstream` whose URL differs from origin's), so adopt and ship never disagree about the shape; the
13444
- * owner is read from this repo's remote URL. Either unknown → `{ fork: false }`, nothing is dropped.
13446
+ * `upstream` whose URL differs from origin's), so adopt and ship never disagree about the shape — or,
13447
+ * with no such remote on this checkout, the committed record of that same test (#658): the descriptor's
13448
+ * `instruction-files: upstream` (#602), which adopt writes on a detected fork. A checkout that never
13449
+ * added the remote then still reads as the fork its descriptor says it is. The owner is read from
13450
+ * this repo's remote URL. Either unknown → `{ fork: false }`, nothing is dropped.
13445
13451
  */
13446
13452
  function codeownersForkContext(repoAbs) {
13447
- if (!adoptDetectFork(repoAbs)) return { fork: false, ownOrg: null };
13453
+ const declared = instructionFile.parseInstructionFiles(projectDoc(repoAbs)).exempt;
13454
+ if (!adoptDetectFork(repoAbs) && !declared) return { fork: false, ownOrg: null };
13448
13455
  const name = git.remoteInfo(repoAbs).name || 'origin';
13449
- const u = git.git(['remote', 'get-url', name], repoAbs);
13456
+ // The configured url, as the gh pin reads it (#658): `get-url` expands `url.<x>.insteadOf`, which
13457
+ // changes how git reaches the remote, never which org owns it.
13458
+ const u = git.git(['config', '--get', `remote.${name}.url`], repoAbs);
13450
13459
  const ownOrg = u.ok ? codeowners.remoteOwner(u.stdout) : null;
13451
13460
  return { fork: !!ownOrg, ownOrg };
13452
13461
  }
@@ -15316,12 +15325,55 @@ function cmdShipBatch(opts) {
15316
15325
  const gh = isGhUsable(repoAbs);
15317
15326
  if (!gh) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — a batch cannot read its combined run`);
15318
15327
 
15328
+ // #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
15329
+ const deleteRef = (ref) => {
15330
+ if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
15331
+ const d = git.git(['push', remote, '--delete', ref], repoAbs);
15332
+ if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
15333
+ return d.ok;
15334
+ };
15335
+ // A ref nothing can land any more may still have its run going: cancel it rather than let it finish.
15336
+ const cancelRuns = (ref, sha) => {
15337
+ for (const r of (git.ghRunsForRef(repoAbs, ref, sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
15338
+ if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${ref}`); continue; }
15339
+ const cx = git.ghRunCancel(repoAbs, r.databaseId);
15340
+ if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${ref} — it will finish on a ref that is gone`);
15341
+ }
15342
+ };
15343
+
15319
15344
  // ---- (b) trunk CI, read with NO doors: the cure/grant doors apply per member, never to a batch ----
15320
15345
  const tci = shipCiCheck(repoAbs, gh, trunk, trunk, null, null);
15321
15346
  const trunkCi = tci.ok ? 'green' : (tci.class === SELF_CLEARING ? 'pending' : 'red');
15322
15347
  if (trunkCi === 'red') {
15348
+ // #656: going serial here gives up on these members, so a ref this command staged for them on an
15349
+ // earlier call is landed by nobody — and it would read "in flight" to the next --batch at this base
15350
+ // and to every serial door, until trunk moved (which the lock itself was preventing). Delete each
15351
+ // ref rooted at trunk's tip whose members are ALL named here; one that also carries another
15352
+ // caller's member stays (#581). Still fails closed: nothing lands, the members go serial.
15353
+ releaseGivenUpBatches();
15323
15354
  return serial(`trunk CI not green (${tci.detail}) — a batch never passes the cure/grant doors; each member meets them on its own`);
15324
15355
  }
15356
+ function releaseGivenUpBatches() {
15357
+ const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
15358
+ if (!ls.ok) { warn(`could not read ${remote}'s ship-batch refs — a batch staged for ${members.join(', ')} (if any) stays; delete it by hand`); return; }
15359
+ const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref).map(([sha, ref]) => [sha.trim(), ref.trim()]);
15360
+ const tip = ((rows.find(([, ref]) => ref === `refs/heads/${trunk}`) || [])[0]) || '';
15361
+ const refs = rows.map(([sha, ref]) => ({ sha, parsed: shipBatch.parseBatchRef(ref) })).filter((x) => x.parsed);
15362
+ if (!tip || !refs.length) return;
15363
+ const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow: tip });
15364
+ const rooted = refs.filter((x) => chains.get(x.parsed.ref).rooted).map((x) => {
15365
+ // Each ref's OWN members: its trailers name it (a chain child's commits sit above its parent's).
15366
+ const lg = git.git(['log', '--format=%B%x00', `${tip}..${x.sha}`], repoAbs);
15367
+ const own = shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === x.parsed.ref).reverse();
15368
+ return { ref: x.parsed.ref, sha: x.sha, members: own.map((m) => m.branch) };
15369
+ });
15370
+ for (const ref of shipBatch.givenUpRefs({ refs: rooted, members })) {
15371
+ const b = rooted.find((x) => x.ref === ref);
15372
+ print(` ${ref} carries ${b.members.join(', ')} — every one going serial now, so nothing would ever land it; ${opts.dry ? 'would delete it [DRY RUN]' : 'deleting it'} (#656)`);
15373
+ cancelRuns(ref, b.sha);
15374
+ deleteRef(ref);
15375
+ }
15376
+ }
15325
15377
  if (trunkCi === 'pending') {
15326
15378
  print(`⏸ ship-batch: trunk CI is still running (${tci.detail}) — wait on it (bounded, B1a), then run this command again.`);
15327
15379
  return 3;
@@ -15336,13 +15388,6 @@ function cmdShipBatch(opts) {
15336
15388
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
15337
15389
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
15338
15390
  .filter((x) => x.sha && x.parsed);
15339
- // #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
15340
- const deleteRef = (ref) => {
15341
- if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
15342
- const d = git.git(['push', remote, '--delete', ref], repoAbs);
15343
- if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
15344
- return d.ok;
15345
- };
15346
15391
  // #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
15347
15392
  // ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
15348
15393
  // whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
@@ -15361,11 +15406,7 @@ function cmdShipBatch(opts) {
15361
15406
  const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
15362
15407
  if (offTrunk) {
15363
15408
  print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
15364
- for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
15365
- if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
15366
- const cx = git.ghRunCancel(repoAbs, r.databaseId);
15367
- if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
15368
- }
15409
+ cancelRuns(b.parsed.ref, b.sha);
15369
15410
  } else {
15370
15411
  print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
15371
15412
  }
@@ -470,6 +470,29 @@ function foreignBatchStep(verdict) {
470
470
  return verdict && verdict.state === 'red' ? { step: 'clear', why: verdict.why } : { step: 'wait' };
471
471
  }
472
472
 
473
+ /**
474
+ * #656: a `--batch` call that goes SERIAL before it reaches the existing-batch step (trunk CI not
475
+ * green) is giving up on its members — they go to `colab ship --branch`, one at a time. A ref it
476
+ * staged on an earlier call is then landed by nobody: no caller names that set again, and the ref
477
+ * still reads "in flight" to the next `--batch` at the same base (foreignBatchStep waits on a green
478
+ * ref forever) and to the serial doors (laneHold). Measured: one repo paused 14 h on such a ref.
479
+ *
480
+ * Which refs this call abandons: those whose carried members are ALL named by this call. A ref that
481
+ * also carries a member this call does not name belongs, at least in part, to another caller — it
482
+ * stays, exactly as #581 keeps it. A ref whose members could not be read (empty list) stays too:
483
+ * never deleted on a guess.
484
+ *
485
+ * In: refs `[{ ref, members: [branch…] }]` (the batch refs rooted at trunk's tip, each with the
486
+ * members its own Ship-Batch: trailers carry), members (the branches this call names).
487
+ * Out: the refs to delete, in input order.
488
+ */
489
+ function givenUpRefs({ refs, members } = {}) {
490
+ const named = new Set(Array.isArray(members) ? members : []);
491
+ return (Array.isArray(refs) ? refs : [])
492
+ .filter((r) => r && r.ref && Array.isArray(r.members) && r.members.length && r.members.every((b) => named.has(b)))
493
+ .map((r) => r.ref);
494
+ }
495
+
473
496
  /**
474
497
  * Does a green run on the batch ref count as trunk-green for the SAME sha (trunk fast-forwarded to
475
498
  * the batch head, so the sha is identical)? Only when the same workflows ran there — a workflow that
@@ -678,7 +701,7 @@ module.exports = {
678
701
  MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, STEPS_KEY, SIZE_TRAILER_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
679
702
  parseShipBatch, parseShipBatchWait, parseShipBatchSteps, sizeTrailer, parseSizeTrailer, adaptiveSize, splitHalves, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
680
703
  droppedTrailer, parseDroppedTrailers, appendTrailers,
681
- branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
704
+ branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep, givenUpRefs,
682
705
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
683
706
  LANE_GRACE_SEC, laneHold, settledAt, MAX_CHAIN_DEPTH, batchChains, chainedLandStep,
684
707
  };
@@ -15,7 +15,9 @@
15
15
  * `null` is "could not read", never "none").
16
16
  *
17
17
  * Behaviour-preserving by construction: every method spawns the exact argv and options the call
18
- * site it replaced spawned (pinned by tools/lib/tracker-github.test.js's argv table).
18
+ * site it replaced spawned (pinned by tools/lib/tracker-github.test.js's argv table). The one
19
+ * addition is the environment: `exec` pins `GH_REPO` to the resolved remote's repo (#658,
20
+ * `pinnedOpts`), so no call depends on gh's default repo or on which other remotes exist.
19
21
  *
20
22
  * This module must NOT require ./tracker (tracker requires this one), and git.js must never require
21
23
  * this module at its top level: git.js ends in `module.exports = {…}`, which REPLACES the exports
@@ -26,9 +28,68 @@
26
28
 
27
29
  let _runner = null; // test seam only — see withRunner
28
30
 
29
- /** Spawn `gh <args>` with `opts` (git.run's options: cwd, timeoutMs, maxBuffer, …). */
31
+ /**
32
+ * #658 — `[HOST/]OWNER/REPO` for a remote URL, in the form `GH_REPO` takes, or null.
33
+ *
34
+ * Only a host gh is known to serve is pinned: `github.com`, or the `GH_HOST` the environment names.
35
+ * Any other host — an SSH alias, a self-hosted forge gh was never pointed at — reads as null, and
36
+ * the call keeps gh's own resolution exactly as before, rather than pinning a name gh cannot reach.
37
+ */
38
+ function ghRepoFromUrl(url, env = process.env) {
39
+ const s = String(url || '').trim();
40
+ let m = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/([^/]+)\/([^/]+?)(?:\.git)?\/*$/i.exec(s);
41
+ if (!m) m = /^(?:[^@/\s]+@)?([^:/\s]+):([^/]+)\/([^/]+?)(?:\.git)?\/*$/.exec(s);
42
+ if (!m) return null;
43
+ const host = m[1].toLowerCase();
44
+ const ghHost = String(env.GH_HOST || '').toLowerCase();
45
+ if (host === 'github.com') return `${m[2]}/${m[3]}`;
46
+ if (ghHost && host === ghHost) return `${host}/${m[2]}/${m[3]}`;
47
+ return null;
48
+ }
49
+
50
+ const _pinCache = new Map(); // resolved cwd → GH_REPO value or null; one repo's remote does not move mid-run
51
+ function _resetPinCache() { _pinCache.clear(); }
52
+
53
+ /**
54
+ * #658 — the repo every `gh` call is pinned to: the one colab's own resolved remote points at
55
+ * (`origin`, or `colab.remote` / the single remote — tools/lib/git.js `remoteInfo`, #301), read
56
+ * for the call's `cwd`. Without it a bare `gh issue|pr|run …` follows gh's own default, which on
57
+ * a fork checkout with an `upstream` remote and no `gh repo set-default` is the UPSTREAM — a ship
58
+ * then read the carried issues as CLOSED and trunk CI as "no run" from the wrong repo.
59
+ * null when nothing resolves (no remote, ambiguous remotes, a host gh does not serve): unpinned.
60
+ */
61
+ function pinnedRepo(cwd) {
62
+ const key = require('path').resolve(cwd || process.cwd());
63
+ if (_pinCache.has(key)) return _pinCache.get(key);
64
+ let slug = null;
65
+ try {
66
+ // The CONFIGURED url, not `git remote get-url`: get-url expands `url.<x>.insteadOf`, which
67
+ // rewrites how git reaches the remote (a mirror, a local path), never which forge repo it is.
68
+ const g = require('./git');
69
+ const { name } = g.remoteInfo(key);
70
+ const u = name ? g.git(['config', '--get', `remote.${name}.url`], key) : null;
71
+ slug = u && u.ok ? ghRepoFromUrl(u.stdout) : null;
72
+ } catch (_) { slug = null; }
73
+ _pinCache.set(key, slug);
74
+ return slug;
75
+ }
76
+
77
+ /**
78
+ * `opts` with `GH_REPO` set to `pinnedRepo(opts.cwd)` — unless the call already names its repo
79
+ * (`--repo`/`-R`), the caller passed its own `GH_REPO`, or the environment sets one (an explicit
80
+ * choice, honoured as gh honours it). Every other option passes through untouched.
81
+ */
82
+ function pinnedOpts(args, opts = {}) {
83
+ if ((args || []).some((a) => a === '--repo' || a === '-R' || /^--repo=/.test(String(a)))) return opts;
84
+ const base = opts.env || process.env;
85
+ if (base.GH_REPO) return opts;
86
+ const slug = pinnedRepo(opts.cwd);
87
+ return slug ? { ...opts, env: { ...base, GH_REPO: slug } } : opts;
88
+ }
89
+
90
+ /** Spawn `gh <args>` with `opts` (git.run's options: cwd, timeoutMs, maxBuffer, …), pinned to origin's repo (#658). */
30
91
  function exec(args, opts = {}) {
31
- return _runner ? _runner(args, opts) : require('./git').run('gh', args, opts);
92
+ return _runner ? _runner(args, opts) : require('./git').run('gh', args, pinnedOpts(args, opts));
32
93
  }
33
94
 
34
95
  /**
@@ -103,4 +164,4 @@ function create(repoAbs) {
103
164
  };
104
165
  }
105
166
 
106
- module.exports = { exec, withRunner, create };
167
+ module.exports = { exec, withRunner, create, ghRepoFromUrl, pinnedRepo, pinnedOpts, _resetPinCache };