@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.0

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/tools/colab CHANGED
@@ -22,6 +22,7 @@ const squash = require('./lib/squash');
22
22
  const procs = require('./lib/procs');
23
23
  const landed = require('./lib/landed');
24
24
  const notify = require('./lib/notify');
25
+ const notifyEndpoint = require('./lib/notify-endpoint'); // #414
25
26
  const journal = require('./lib/journal');
26
27
  const labels = require('./lib/labels');
27
28
  const records = require('./lib/records');
@@ -56,6 +57,7 @@ const claimComments = require('./lib/claim-comments');
56
57
  const machine = require('./lib/machine');
57
58
  const targetSync = require('./lib/ship-target-sync');
58
59
  const shipBatch = require('./lib/ship-batch');
60
+ const conflictMarkers = require('./lib/conflict-markers');
59
61
  const docsOnly = require('./lib/docs-only');
60
62
  const cureDiff = require('./lib/cure-diff');
61
63
  const codeowners = require('./lib/codeowners');
@@ -63,6 +65,7 @@ const releasePolicy = require('./lib/release-policy');
63
65
  const workflowTriggers = require('./lib/workflow-triggers');
64
66
  const releaseCut = require('./lib/release-cut');
65
67
  const releaseFinalize = require('./lib/release-finalize');
68
+ const releaseChannel = require('./lib/release-channel');
66
69
  const shippedBranch = require('./lib/shipped-branch');
67
70
  const shipRoles = require('./lib/ship-roles'); // #372
68
71
  const refsBrake = require('./lib/refs-brake'); // #385
@@ -1244,6 +1247,11 @@ Every cut also publishes the candidate's GitHub pre-release (#443): notes = the
1244
1247
  since the last final plus the tag message. Best-effort — a failure warns (--json published.ok false)
1245
1248
  and never undoes the pushed tag.
1246
1249
 
1250
+ Every cut also fast-forwards the release channel \`next\` — a branch, always the newest candidate
1251
+ (#445) — to the candidate's commit, pushed with COLAB_RELEASE=1 (what pre-push-guard lets through).
1252
+ Forward only, never forced: a \`next\` that is not an ancestor of the candidate is reported and left
1253
+ alone. Best-effort like the pre-release (--json channel.ok false); the tag stands either way.
1254
+
1247
1255
  Needs origin reachable (the tag is recorded there) and gh usable (CI, suite and switch markers are
1248
1256
  read from GitHub). Exit code: 0 when a candidate was cut (or, with --dry, would be), or an --auto
1249
1257
  no-op; 1 when refused.
@@ -1508,11 +1516,16 @@ function cmdReleaseCut(argv) {
1508
1516
  created = true;
1509
1517
  published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message });
1510
1518
  }
1519
+ // #445: the `next` channel names the newest candidate — fast-forwarded in the run that pushed it.
1520
+ // Best-effort like the pre-release: the tag already stands, so a channel that cannot move is reported.
1521
+ const channel = verdict.ok && verdict.tag
1522
+ ? releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
1523
+ : null;
1511
1524
 
1512
1525
  if (opts.json) {
1513
1526
  print(JSON.stringify({
1514
1527
  repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1515
- ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, version: verdict.version, bump: verdict.bump,
1528
+ ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1516
1529
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1517
1530
  }, null, 2));
1518
1531
  return verdict.ok || verdict.noop ? 0 : 1;
@@ -1534,12 +1547,14 @@ function cmdReleaseCut(argv) {
1534
1547
  print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
1535
1548
  return 1;
1536
1549
  }
1537
- if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote} and publish its GitHub pre-release. Nothing created.`);
1550
+ if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
1538
1551
  else {
1539
1552
  print(`✓ cut ${verdict.tag} on ${at} and pushed it to ${remote} — a candidate, not a release; finalizing it is the release skill's.`);
1540
1553
  if (published && published.ok) print(`✓ ${published.detail}`);
1541
1554
  else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --prerelease --latest=false`);
1542
1555
  }
1556
+ if (channel && channel.ok) print(`${opts.dry ? '·' : '✓'} ${channel.detail}`);
1557
+ else if (channel) warn(`${channel.detail} — the tag stands`);
1543
1558
  return 0;
1544
1559
  }
1545
1560
 
@@ -1627,6 +1642,10 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1627
1642
  in a commit since the previous final) gets one comment: "Released in vX.Y.Z"
1628
1643
  (with --dry: every check passed, nothing written)
1629
1644
 
1645
+ A final also fast-forwards the release channel \`stable\` — a branch, always the newest final (#445)
1646
+ — to its commit; already-final repairs a \`stable\` a dead run left behind. Forward only, never
1647
+ forced, best-effort (--json channel); the final tag stands either way.
1648
+
1630
1649
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
1631
1650
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
1632
1651
  ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
@@ -1634,7 +1653,8 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1634
1653
  regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
1635
1654
  began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
1636
1655
  test-period from max(candidate tag date, tracking issue creation), release: test-period long
1637
- trunk-green every main run since the period began, of the workflows that ran at the candidate,
1656
+ trunk-green every run since the period began on main — and on project.yml's trunk: when that is
1657
+ another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
1638
1658
  none red — required only where the final is automatic
1639
1659
 
1640
1660
  manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
@@ -1664,6 +1684,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1664
1684
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
1665
1685
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
1666
1686
  skipped (--auto: [{tag, state, detail?}] — the other open candidates),
1687
+ channel (null, or {channel, ok, action, detail} — the stable move, #445),
1667
1688
  announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
1668
1689
  grant (null, or {issue, ruledBy} — the operator grant that made this final automatic) }
1669
1690
 
@@ -1703,6 +1724,7 @@ function cmdReleaseFinalize(argv) {
1703
1724
  if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — the tracking issue, runs and regression edges live on GitHub`);
1704
1725
  const doc = projectDoc(repoAbs);
1705
1726
  const policy = releasePolicy.evaluateRelease(doc);
1727
+ const windowBranches = releaseFinalize.windowBranches(doc && doc.trunk); // #437
1706
1728
  const now = new Date().toISOString();
1707
1729
  const remote = git.remoteFor(repoAbs); // #301
1708
1730
 
@@ -1782,10 +1804,13 @@ function cmdReleaseFinalize(argv) {
1782
1804
  });
1783
1805
  const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
1784
1806
  const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
1785
- const sinceRaw = git.ghRunsSince(repoAbs, 'main', period.start.slice(0, 10));
1786
- const since = sinceRaw ? { ...sinceRaw, runs: releaseCut.withoutOwnWorkflow(sinceRaw.runs) } : sinceRaw; // #425
1807
+ // #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
1808
+ const since = releaseFinalize.mergeWindowRuns(windowBranches.map((branch) => {
1809
+ const raw = git.ghRunsSince(repoAbs, branch, period.start.slice(0, 10));
1810
+ return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
1811
+ }));
1787
1812
  const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
1788
- periodStart: period.start, periodEnd: walk ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated),
1813
+ periodStart: period.start, periodEnd: walk ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
1789
1814
  });
1790
1815
  const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
1791
1816
  const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
@@ -1838,6 +1863,7 @@ function cmdReleaseFinalize(argv) {
1838
1863
 
1839
1864
  // ---- writes ----
1840
1865
  let tagged = false;
1866
+ let channel = null; // #445: { channel, ok, action, detail } once `stable` was (or could not be) moved
1841
1867
  const comment = (num, fields, text) => {
1842
1868
  const view = git.ghIssueView(repoAbs, num, ['comments']);
1843
1869
  if (view && releaseFinalize.hasEvent(view.comments, fields)) return;
@@ -1880,6 +1906,13 @@ function cmdReleaseFinalize(argv) {
1880
1906
  }
1881
1907
  tagged = true;
1882
1908
  }
1909
+ // #445: the `stable` channel names the newest final — moved by the run that tags it, and repaired
1910
+ // on the already-final resume (a run that died between the tag push and the move finishes it).
1911
+ if (tagged) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: cand.sha, label: cand.version });
1912
+ else if (verdict.state === 'already-final' && version0) {
1913
+ const finalTag = tags.find((t) => t.name === version0);
1914
+ if (finalTag) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: finalTag.sha, label: version0 });
1915
+ }
1883
1916
  // The newest candidate is announced on its version's issue — on --auto with its own clock.
1884
1917
  const tNew = version0 ? trackings.get(version0) : null;
1885
1918
  if (newest && tNew && tNew.number) {
@@ -1929,7 +1962,7 @@ function cmdReleaseFinalize(argv) {
1929
1962
  lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
1930
1963
  periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
1931
1964
  state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
1932
- skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null,
1965
+ skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null, channel,
1933
1966
  }, null, 2));
1934
1967
  } else {
1935
1968
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
@@ -1942,6 +1975,8 @@ function cmdReleaseFinalize(argv) {
1942
1975
  print('');
1943
1976
  print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
1944
1977
  if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
1978
+ if (channel && channel.ok) print(`✓ ${channel.detail}`);
1979
+ else if (channel) warn(`${channel.detail} — the final tag stands`);
1945
1980
  if (verdict.handoff) print(`\nThe final is a human act here. The one command, for a human to run:\n ${verdict.handoff}`);
1946
1981
  }
1947
1982
  // #423: on --auto, "nothing to do yet" (still testing, no candidate) is the workflow's ordinary output.
@@ -2363,7 +2398,7 @@ function cmdGateRecorded(argv) {
2363
2398
  // `live-env:`.
2364
2399
  // ---------------------------------------------------------------------------
2365
2400
 
2366
- const HELP_GATE_HERMETIC = `colab gate-hermetic [--net auto|on] [--keep VAR,...] [--json] [--verbose] [--repo <path>] -- <test command...>
2401
+ const HELP_GATE_HERMETIC = `colab gate-hermetic [--net auto|on] [--keep VAR,...] [--no-pin] [--json] [--verbose] [--repo <path>] -- <test command...>
2367
2402
 
2368
2403
  Runs the repo's TEST STEP twice and gives one verdict (#403, code-wrap A3):
2369
2404
 
@@ -2373,7 +2408,11 @@ Runs the repo's TEST STEP twice and gives one verdict (#403, code-wrap A3):
2373
2408
  daemon/fleet runtime unset (*_URL *_HOST *_PORT *_TOKEN *_KEY *_SECRET *_SOCK
2374
2409
  COLAB_* CLAUDE* GH_* …); network off where the platform allows it —
2375
2410
  macOS sandbox-exec, Linux unshare --net (loopback stays up in both) — and the
2376
- line saying which is always printed.
2411
+ line saying which is always printed. Toolchain-manager homes you have NOT set
2412
+ (RUSTUP_HOME CARGO_HOME PYENV_ROOT RBENV_ROOT ASDF_DATA_DIR NVM_DIR VOLTA_HOME
2413
+ MISE_DATA_DIR GOPATH) are pinned to their real directory first, when it exists,
2414
+ so a rustup/pyenv/asdf proxy still finds the installed toolchain instead of
2415
+ trying to download one (#447). Every pin is printed.
2377
2416
 
2378
2417
  Verdicts (exit 0 = may count as green, 1 = not):
2379
2418
  green both runs passed exit 0
@@ -2390,6 +2429,8 @@ pass \`-- sh -c '…'\` for pipes or &&.
2390
2429
  --net on do not cut the network (reported); default auto = best effort
2391
2430
  --keep A,B pass these variables through to the hermetic run anyway — printed in the
2392
2431
  verdict, so a pass-through is never silent
2432
+ --no-pin do not pin toolchain-manager homes: the strict run, for a suite suspected of
2433
+ reading a manager's own config or package cache (~/.cargo/config.toml, …)
2393
2434
  --json one JSON object instead of the text verdict
2394
2435
  --verbose print each run's full output (default: failing names + a short tail on red)
2395
2436
  --repo <path> working tree to run in (default: cwd)
@@ -2405,7 +2446,7 @@ function cmdGateHermetic(argv) {
2405
2446
  const cmd = dd === -1 ? [] : argv.slice(dd + 1);
2406
2447
  const opts = parseArgs(own, {
2407
2448
  values: { '--repo': 'repo', '--net': 'net', '--keep': 'keep' },
2408
- flags: { '--json': 'json', '--verbose': 'verbose', '-h': 'help', '--help': 'help' },
2449
+ flags: { '--json': 'json', '--verbose': 'verbose', '--no-pin': 'noPin', '-h': 'help', '--help': 'help' },
2409
2450
  });
2410
2451
  if (opts.help) return print(HELP_GATE_HERMETIC);
2411
2452
  if (opts._.length) throw new UserError(`unexpected argument "${opts._[0]}" — the test command goes after \`--\` (see --help)`);
@@ -2453,7 +2494,10 @@ function cmdGateHermetic(argv) {
2453
2494
  if (normal.ok && !skip) {
2454
2495
  homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-hermetic-home-'));
2455
2496
  try {
2456
- envInfo = hermetic.hermeticEnv(process.env, homeDir, keep);
2497
+ const pins = opts.noPin ? [] : hermetic.toolchainPins(process.env, (d) => {
2498
+ try { return fs.statSync(d).isDirectory(); } catch (_) { return false; }
2499
+ });
2500
+ envInfo = hermetic.hermeticEnv(process.env, homeDir, keep, { pins });
2457
2501
  net = hermetic.probeNetworkIsolation({
2458
2502
  platform: process.platform, mode: netMode,
2459
2503
  run: (c, a) => spawnSync(c, a, { stdio: 'ignore' }),
@@ -2473,7 +2517,7 @@ function cmdGateHermetic(argv) {
2473
2517
  verdict, ok: exitCode === 0, command: cmd,
2474
2518
  liveEnv: { skip, trunkSource, value: trunkLive.value },
2475
2519
  normal: { ok: normal.ok, exit: normal.exit },
2476
- hermetic: herm ? { ok: herm.ok, exit: herm.exit, stripped: envInfo.stripped, kept: envInfo.kept, network: net.note } : null,
2520
+ hermetic: herm ? { ok: herm.ok, exit: herm.exit, stripped: envInfo.stripped, kept: envInfo.kept, pinned: envInfo.pinned, network: net.note } : null,
2477
2521
  failing, notes,
2478
2522
  }, null, 2));
2479
2523
  return exitCode;
@@ -2487,6 +2531,8 @@ function cmdGateHermetic(argv) {
2487
2531
  lines.push(`hermetic run: ${herm.ok ? 'green' : 'RED'} (exit ${herm.exit === null ? 'none' : herm.exit}${herm.signal ? `, ${herm.signal}` : ''})`);
2488
2532
  lines.push(` HOME=<fresh empty dir>; unset ${envInfo.stripped.length} var(s)${envInfo.stripped.length ? `: ${envInfo.stripped.join(' ')}` : ''}`);
2489
2533
  if (envInfo.kept.length) lines.push(` --keep passed through: ${envInfo.kept.join(' ')}`);
2534
+ if (envInfo.pinned.length) lines.push(` toolchain homes pinned to their real dirs: ${envInfo.pinned.join(' ')}`);
2535
+ else if (opts.noPin) lines.push(' toolchain homes: NOT pinned (--no-pin)');
2490
2536
  lines.push(` ${net.note}`);
2491
2537
  } else {
2492
2538
  lines.push('hermetic run: not attempted (normal run is red)');
@@ -2506,6 +2552,13 @@ function cmdGateHermetic(argv) {
2506
2552
  for (const l of hermetic.tail(out)) lines.push(` | ${l}`);
2507
2553
  }
2508
2554
  }
2555
+ if (verdict === 'live-env' && hermetic.looksLikeToolchainMiss(herm.output)) {
2556
+ lines.push('', 'hint: the hermetic failure looks like a toolchain manager that could not find its install',
2557
+ ' (a proxy trying to download a toolchain with the network off) — not necessarily the tests. Its',
2558
+ ' default homes under $HOME are pinned already, so its install lives elsewhere (or --no-pin was given):',
2559
+ ' export the manager\'s home variable (e.g. RUSTUP_HOME, CARGO_HOME) so it passes through, and re-run.',
2560
+ ' Name it in the distill comment (#447).');
2561
+ }
2509
2562
  lines.push('', `VERDICT: ${verdict} — ${hermetic.VERDICT_TEXT[verdict]}`);
2510
2563
  print(lines.join('\n'));
2511
2564
  return exitCode;
@@ -4838,6 +4891,19 @@ function worktreeSubdir(config) { return config.worktreeSubdir || '.worktrees';
4838
4891
  // slow-but-working. Overridable per-machine/per-repo for a legitimately slow teardown.
4839
4892
  const TEARDOWN_TIMEOUT_MS = Number(process.env.COLAB_TEARDOWN_TIMEOUT_MS) || 5 * 60 * 1000;
4840
4893
 
4894
+ /**
4895
+ * #436: after a pre-ship hook exits 0, which of the paths it was handed still carry conflict markers
4896
+ * in the index — i.e. would be committed with `<<<<<<<` in them. Untrimmed git output, so the line
4897
+ * numbers in the message are the file's own.
4898
+ */
4899
+ function stagedConflictMarkers(dir, paths) {
4900
+ const rawGit = (args, cwd) => {
4901
+ const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
4902
+ return { ok: r.status === 0, stdout: r.stdout || '' };
4903
+ };
4904
+ return conflictMarkers.stagedMarkerPaths(rawGit, dir, paths);
4905
+ }
4906
+
4841
4907
  function runHook(repoAbs, name, ctx) {
4842
4908
  const hook = path.join(repoAbs, '.colab', 'hooks', name);
4843
4909
  try {
@@ -5680,6 +5746,11 @@ claims from.
5680
5746
  "contained in trunk" between releases BY CONSTRUCTION, which this heuristic would otherwise
5681
5747
  misread as spent and advise deleting, silently breaking GitOps deploys (#63).
5682
5748
 
5749
+ - \`notifyUrl: unset\` is reported (read-only, never pruned, not part of the verdict) when a
5750
+ local observer declared its events URL in <COLAB_HOME>/notify-endpoint and notifyUrl is not
5751
+ set — that observer then receives no issue.merged / issue.closed / readiness.marked /
5752
+ gate.recorded event (#414). No declared endpoint, no line: unset is the right default there.
5753
+
5683
5754
  This exists because claims made without a worktree were never auto-healed before, and a
5684
5755
  real repo accumulated 17 stale same-day claims. Run \`colab doctor\` regularly; \`--prune\`
5685
5756
  in a cleanup cron.
@@ -6170,6 +6241,11 @@ function cmdDoctor(argv) {
6170
6241
  }
6171
6242
  }
6172
6243
 
6244
+ // 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
6245
+ // the verdict — it is configuration, not state drift. Silent on a machine with no
6246
+ // <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
6247
+ report.notify = notifyEndpoint.status(config, state.COLAB_DIR);
6248
+
6173
6249
  if (opts.json) { print(JSON.stringify(report, null, 2)); return 0; }
6174
6250
 
6175
6251
  const verb = opts.prune ? 'Pruned' : 'Found';
@@ -6374,6 +6450,11 @@ function cmdDoctor(argv) {
6374
6450
  print(' which also stops colab handing it to a worktree. A "cwd DELETED" line above is the real');
6375
6451
  print(' orphan and wants killing, not reserving.');
6376
6452
  }
6453
+ const notifyLine = notifyEndpoint.healthLine(report.notify);
6454
+ if (notifyLine) {
6455
+ print('');
6456
+ print(notifyLine);
6457
+ }
6377
6458
  return 0;
6378
6459
  }
6379
6460
 
@@ -8187,20 +8268,31 @@ function readFrozenStamp(dir) {
8187
8268
  function selfProvenance() {
8188
8269
  const st = readFrozenStamp(__dirname);
8189
8270
  if (st && st.name === stamp.FROZEN_STAMP_NAME) {
8190
- return { frozen: true, version: st.version, source: __dirname, branch: null };
8271
+ return { kind: 'frozen', frozen: true, version: st.version, source: __dirname, branch: null };
8191
8272
  }
8192
8273
  const { root } = handbookPaths();
8274
+ // A registry install (npx, npm i) — before the git read below, which has no repo of its own to
8275
+ // answer from there and would walk up into whatever repo the npx cache happens to sit inside (#444).
8276
+ const pkg = stamp.npmPackageInfo(root);
8277
+ if (pkg) return { kind: 'npm', frozen: false, version: pkg.version, source: root, branch: null };
8193
8278
  const hb = stamp.handbookInfo(root);
8194
8279
  const br = stamp.gitIn(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
8195
- return { frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
8280
+ return { kind: 'working-tree', frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
8281
+ }
8282
+
8283
+ /**
8284
+ * One version, from whichever provenance applies — there used to be a second, hard-coded
8285
+ * `colab 1.0.0` in front of it that no release ever moved (#444).
8286
+ */
8287
+ function versionLine(self) {
8288
+ const where = self.kind === 'frozen' ? `frozen copy: ${self.source}`
8289
+ : self.kind === 'npm' ? `npm package: ${self.source}`
8290
+ : `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
8291
+ return `colab ${self.version} (${where})`;
8196
8292
  }
8197
8293
 
8198
8294
  function cmdVersion() {
8199
- const self = selfProvenance();
8200
- const where = self.frozen
8201
- ? `frozen copy: ${self.source}`
8202
- : `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
8203
- return print(`colab 1.0.0 — colab-handbook ${self.version} (${where})`);
8295
+ return print(versionLine(selfProvenance()));
8204
8296
  }
8205
8297
 
8206
8298
  /** Current handbook version = nearest RELEASE tag (pre-releases skipped, #334); 'v0' before the first one. */
@@ -9379,8 +9471,12 @@ for is built in its place, so the survivors of a decline can batch without landi
9379
9471
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
9380
9472
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
9381
9473
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
9382
- --dry builds the batch locally and prints it, pushing nothing. Consumer CI must opt in: add
9383
- 'ship-batch/**' to a CI workflow's push: branches:.
9474
+ A hook that exits 0 but leaves a <<<<<<< / >>>>>>> line staged in a path it was handed counts as failing (#436).
9475
+ Resuming a staged batch: a branch you name that the staged batch does not carry (over the cap, dropped
9476
+ at build, added since) is NOT landed with it — the command names both lists and says so (#415).
9477
+ --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
9478
+ locally and printed; a staged green batch prints what would land (members, combined run, target sha).
9479
+ Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
9384
9480
 
9385
9481
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
9386
9482
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -11789,6 +11885,14 @@ function cmdShip(argv) {
11789
11885
  }
11790
11886
  if (hasPreShip) {
11791
11887
  const hk = runHook(repoAbs, 'pre-ship', { wtPath: branchDir, name: sess.name || sess.branch, branch: sess.branch, ports: [], trunk, base: target, issues: sess.issues });
11888
+ // #436: exit 0 is the hook's claim; the index is the proof. Markers left in a path it was
11889
+ // handed make it a failing hook, checked BEFORE the commit so nothing carrying them is pushed.
11890
+ const markers = hk.ran && hk.ok ? stagedConflictMarkers(branchDir, uf) : [];
11891
+ if (markers.length) {
11892
+ git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
11893
+ process.stderr.write(`✗ B0: pre-ship hook exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} — treated as a failing hook. Nothing pushed.\n`);
11894
+ return 1;
11895
+ }
11792
11896
  const committed = hk.ran && hk.ok && git.git(['commit', '--no-edit'], branchDir).ok;
11793
11897
  if (!committed) {
11794
11898
  git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
@@ -12433,7 +12537,9 @@ function cmdShipBatch(opts) {
12433
12537
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
12434
12538
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
12435
12539
  .filter((x) => x.sha && x.parsed);
12540
+ // #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
12436
12541
  const deleteRef = (ref) => {
12542
+ if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
12437
12543
  const d = git.git(['push', remote, '--delete', ref], repoAbs);
12438
12544
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
12439
12545
  return d.ok;
@@ -12463,6 +12569,14 @@ function cmdShipBatch(opts) {
12463
12569
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
12464
12570
  const matches = heads.length >= 2 && heads.every((m) => m.now && m.now.startsWith(m.sha));
12465
12571
  existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
12572
+ // #415: the command line and the staged batch can name different sets. A requested branch the
12573
+ // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
12574
+ // along — say so, naming both lists, instead of resuming as if the two were the same.
12575
+ const notStaged = shipBatch.notStaged(members, inBatch);
12576
+ if (notStaged.length) {
12577
+ print(` ! ${atBase.parsed.ref} was staged with ${inBatch.map((m) => m.branch).join(', ')}; this command named ${members.join(', ')}.`);
12578
+ print(` NOT in the staged batch, so it does not land with it: ${notStaged.join(', ')} — ship it after this batch (next batch, or colab ship --branch <b>).`);
12579
+ }
12466
12580
  }
12467
12581
  }
12468
12582
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
@@ -12489,7 +12603,7 @@ function cmdShipBatch(opts) {
12489
12603
  return 4;
12490
12604
  }
12491
12605
  if (step.step === 'red-serial') {
12492
- print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} deleted.`);
12606
+ print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
12493
12607
  deleteRef(existing.ref);
12494
12608
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
12495
12609
  return 4;
@@ -12556,8 +12670,13 @@ function cmdShipBatch(opts) {
12556
12670
  issues: (m.report && m.report.closeIssues) || [],
12557
12671
  });
12558
12672
  const left = hk.ran ? unmergedIn() : unmerged;
12673
+ // #436: a hook that exits 0 and `git add`s a path still holding markers clears the unmerged
12674
+ // state, so `left` reads empty — read the staged content itself before trusting it.
12675
+ const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
12559
12676
  if (!hk.ran || !hk.ok || left.length) {
12560
12677
  why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
12678
+ } else if (markers.length) {
12679
+ why = `.colab/hooks/pre-ship exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} on the combined head — treated as a failing hook, next batch`;
12561
12680
  } else regenerated = unmerged;
12562
12681
  }
12563
12682
  if (why) {
@@ -12624,6 +12743,14 @@ function cmdShipBatch(opts) {
12624
12743
  */
12625
12744
  function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opts) {
12626
12745
  const head = existing.sha;
12746
+ // #415: a staged green batch reached under --dry is a read: what WOULD land, and nothing else —
12747
+ // no fast-forward, no push, no ref delete, no hook, no worktree teardown, no claim, no comment.
12748
+ if (opts.dry) {
12749
+ print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(base)} [DRY RUN]`);
12750
+ print(`→ READY: would fast-forward ${trunk} ${shortSha(base)} → ${shortSha(head)} — ${existing.ref}, combined run ${(verdict.runIds || []).join(', ') || '(id unread)'} ${verdict.why || verdict.state}`);
12751
+ print(` would land ${existing.members.length} member(s), one squash each: ${existing.members.map((m) => m.branch).join(', ')}`);
12752
+ return 0;
12753
+ }
12627
12754
  const headBranch = git.git(['rev-parse', '--abbrev-ref', 'HEAD'], repoAbs).stdout;
12628
12755
  if (headBranch !== trunk || git.dirtyTracked(repoAbs)) {
12629
12756
  throw new UserError(`the main checkout is not on a clean ${trunk} ("${headBranch}"${git.dirtyTracked(repoAbs) ? ', dirty' : ''}) — the batch is green and waiting; fix the checkout and run this command again`);
@@ -0,0 +1,47 @@
1
+ 'use strict';
2
+ /**
3
+ * #436: a pre-ship hook's exit code is a claim ("ZERO means every conflicted path was resolved"),
4
+ * not proof. A hook that regenerates a path's NEW layout and then `git add`s an OLD path still full
5
+ * of conflict markers exits 0 and stages the markers — git clears the unmerged state on `add`, so
6
+ * `git diff --diff-filter=U` reads clean. This reads what would actually be committed.
7
+ *
8
+ * Detection is deliberately `<<<<<<<` / `>>>>>>>` at column 0 (followed by a space or end of line).
9
+ * A bare `=======` line is NOT a marker on its own: it is also a legitimate Markdown setext-heading
10
+ * underline, and generated docs are exactly the files this check reads. Every real conflict block
11
+ * carries the two outer markers, so nothing is missed by not counting the middle one alone.
12
+ */
13
+
14
+ const MARKER = /^(<{7}|>{7})(?:[ \t]|$)/;
15
+
16
+ /** Pure: 1-based line numbers of conflict-marker lines in `text`. */
17
+ function markerLines(text) {
18
+ const out = [];
19
+ String(text == null ? '' : text).split('\n').forEach((line, i) => {
20
+ if (MARKER.test(line.replace(/\r$/, ''))) out.push(i + 1);
21
+ });
22
+ return out;
23
+ }
24
+
25
+ /**
26
+ * Which of `paths` still hold conflict markers in the INDEX (stage 0 — what `git commit` takes) at
27
+ * `cwd`. `gitFn(args, cwd)` → `{ ok, stdout }`. A path absent from the index (deleted, or still
28
+ * unmerged at stages 1-3) is skipped here: deletion is a resolution, and an unmerged path is the
29
+ * caller's existing `--diff-filter=U` check. Returns `[{ path, lines }]`.
30
+ */
31
+ function stagedMarkerPaths(gitFn, cwd, paths) {
32
+ const hits = [];
33
+ for (const p of [...new Set(paths || [])]) {
34
+ const r = gitFn(['show', `:0:${p}`], cwd);
35
+ if (!r || !r.ok) continue;
36
+ const lines = markerLines(r.stdout);
37
+ if (lines.length) hits.push({ path: p, lines });
38
+ }
39
+ return hits;
40
+ }
41
+
42
+ /** One line naming each path and its first marker lines. */
43
+ function describe(hits) {
44
+ return (hits || []).map((h) => `${h.path}:${h.lines.slice(0, 3).join(',')}${h.lines.length > 3 ? ',…' : ''}`).join(', ');
45
+ }
46
+
47
+ module.exports = { markerLines, stagedMarkerPaths, describe };
@@ -51,6 +51,70 @@ const TEST_RUNNER_LEAKS = ['NODE_TEST_CONTEXT', 'NODE_TEST_WORKER_ID'];
51
51
  // HOME-derived locations re-pointed INTO the fresh home, so nothing reaches the real one through them.
52
52
  const XDG_DIRS = { XDG_CONFIG_HOME: '.config', XDG_DATA_HOME: '.local/share', XDG_CACHE_HOME: '.cache', XDG_STATE_HOME: '.local/state' };
53
53
 
54
+ // Toolchain-manager homes (#447). A version manager's proxy (`cargo`/`rustc` from rustup, a pyenv
55
+ // or asdf shim, …) finds its installed toolchain through ONE variable whose default is under
56
+ // $HOME. With HOME swapped for an empty dir the proxy finds nothing, tries to install a toolchain,
57
+ // and — network off — fails; the verdict then read `live-env` and blamed the code for a machine
58
+ // dependency it does not have (measured: a rustup-managed Rust workspace, `live-env` locally,
59
+ // green on CI where the container brings its own toolchain). An installed toolchain is the
60
+ // compiler/interpreter the test step runs ON, not live state the tests READ, so the variable is
61
+ // pinned to the real directory BEFORE HOME moves — only when the caller has not set it already
62
+ // (a set value passes through untouched: none of these names match a strip rule) and only when
63
+ // that directory actually exists (nothing is invented). Every pin is printed in the verdict, the
64
+ // same visibility rule as --keep. The cost, stated: such a home also holds the manager's own
65
+ // config and package cache (~/.cargo/config.toml, ~/.cargo/registry, ~/go/pkg/mod), and a test
66
+ // reading THOSE is not caught — `--no-pin` restores the strict run for a suite suspected of it.
67
+ const TOOLCHAIN_HOMES = [
68
+ { name: 'RUSTUP_HOME', rel: '.rustup', manager: 'rustup' },
69
+ { name: 'CARGO_HOME', rel: '.cargo', manager: 'rustup/cargo' },
70
+ { name: 'PYENV_ROOT', rel: '.pyenv', manager: 'pyenv' },
71
+ { name: 'RBENV_ROOT', rel: '.rbenv', manager: 'rbenv' },
72
+ { name: 'ASDF_DATA_DIR', rel: '.asdf', manager: 'asdf' },
73
+ { name: 'NVM_DIR', rel: '.nvm', manager: 'nvm' },
74
+ { name: 'VOLTA_HOME', rel: '.volta', manager: 'volta' },
75
+ // mise follows XDG_DATA_HOME, which the hermetic run re-points — so its default must be resolved
76
+ // against the CALLER's XDG_DATA_HOME, not the fresh one.
77
+ { name: 'MISE_DATA_DIR', rel: '.local/share/mise', xdg: ['XDG_DATA_HOME', 'mise'], manager: 'mise' },
78
+ { name: 'GOPATH', rel: 'go', manager: 'go (GOTOOLCHAIN downloads + module cache)' },
79
+ ];
80
+
81
+ /**
82
+ * Which toolchain homes to pin → `[{ name, value, manager }]`. `exists(path)` is injected so this
83
+ * stays pure; the CLI passes a real directory check. A variable already set in `env` is never in
84
+ * the list — it reaches the hermetic run unchanged anyway.
85
+ */
86
+ function toolchainPins(env, exists) {
87
+ const home = env.HOME;
88
+ const pins = [];
89
+ for (const t of TOOLCHAIN_HOMES) {
90
+ if (env[t.name]) continue;
91
+ let dir = null;
92
+ if (t.xdg && env[t.xdg[0]]) dir = `${env[t.xdg[0]].replace(/\/+$/, '')}/${t.xdg[1]}`;
93
+ else if (home) dir = `${home.replace(/\/+$/, '')}/${t.rel}`;
94
+ if (dir && exists(dir)) pins.push({ name: t.name, value: dir, manager: t.manager });
95
+ }
96
+ return pins;
97
+ }
98
+
99
+ // The output shapes of a version manager that could not find its toolchain — what a missed pin
100
+ // looks like. Used only for a hint line under a `live-env` verdict; the verdict itself is unchanged.
101
+ const TOOLCHAIN_MISS_PATTERNS = [
102
+ /syncing channel updates for/i, // rustup proxy installing a toolchain
103
+ /static\.rust-lang\.org/i,
104
+ /rustup could not choose a version|no default toolchain/i,
105
+ /pyenv: version .* is not installed/i,
106
+ /rbenv: version .* is not installed/i,
107
+ /No version is set for command|No preset version installed/i, // asdf
108
+ /mise .*(is not installed|missing:)/i,
109
+ /go: downloading go\d|toolchain not available/i,
110
+ ];
111
+
112
+ /** True when a failed run's output looks like a toolchain manager missing its install. */
113
+ function looksLikeToolchainMiss(output) {
114
+ const s = String(output || '');
115
+ return TOOLCHAIN_MISS_PATTERNS.some((re) => re.test(s));
116
+ }
117
+
54
118
  function shouldStrip(name) {
55
119
  if (name === 'HOME' || name === 'PATH') return false;
56
120
  if (STRIP_EXACT.has(name) || STRIP_EXACT.has(name.toLowerCase())) return true;
@@ -65,15 +129,17 @@ function normalEnv(env) {
65
129
  }
66
130
 
67
131
  /**
68
- * The hermetic run's env → `{ env, stripped, kept }`. `home` is the fresh directory the caller
69
- * created. `keep` names variables the caller explicitly passes through anyway — every one is
70
- * echoed in the verdict, so a pass-through is visible, never silent.
132
+ * The hermetic run's env → `{ env, stripped, kept, pinned }`. `home` is the fresh directory the
133
+ * caller created. `keep` names variables the caller explicitly passes through anyway — every one is
134
+ * echoed in the verdict, so a pass-through is visible, never silent. `pins` (from `toolchainPins`)
135
+ * are toolchain-manager homes set to their real directories before HOME moves (#447) — echoed too.
71
136
  */
72
- function hermeticEnv(env, home, keep = []) {
137
+ function hermeticEnv(env, home, keep = [], { pins = [] } = {}) {
73
138
  const keepSet = new Set(keep);
74
139
  const out = {};
75
140
  const stripped = [];
76
141
  const kept = [];
142
+ for (const p of pins) out[p.name] = p.value;
77
143
  for (const [k, v] of Object.entries(env)) {
78
144
  if (TEST_RUNNER_LEAKS.includes(k)) continue;
79
145
  if (keepSet.has(k)) { out[k] = v; if (shouldStrip(k)) kept.push(k); continue; }
@@ -83,7 +149,7 @@ function hermeticEnv(env, home, keep = []) {
83
149
  }
84
150
  out.HOME = home;
85
151
  for (const [k, rel] of Object.entries(XDG_DIRS)) if (!keepSet.has(k)) out[k] = `${home}/${rel}`;
86
- return { env: out, stripped: stripped.sort(), kept: kept.sort() };
152
+ return { env: out, stripped: stripped.sort(), kept: kept.sort(), pinned: pins.map((p) => p.name) };
87
153
  }
88
154
 
89
155
  // ---- the network ----------------------------------------------------------------------------
@@ -188,6 +254,6 @@ const VERDICT_TEXT = {
188
254
  };
189
255
 
190
256
  module.exports = {
191
- parseLiveEnv, shouldStrip, normalEnv, hermeticEnv, probeNetworkIsolation, parseFailures, tail,
257
+ parseLiveEnv, shouldStrip, normalEnv, hermeticEnv, toolchainPins, looksLikeToolchainMiss, TOOLCHAIN_HOMES, probeNetworkIsolation, parseFailures, tail,
192
258
  classify, VERDICT_TEXT, DARWIN_PROFILE, LINUX_WRAPPER, TEST_RUNNER_LEAKS,
193
259
  };
@@ -25,6 +25,7 @@ const fs = require('fs');
25
25
  const path = require('path');
26
26
  const { execFileSync } = require('child_process');
27
27
  const stamp = require('./stamp');
28
+ const notifyEndpoint = require('./notify-endpoint');
28
29
 
29
30
  const OK = 'ok';
30
31
  const WARN = 'warn';
@@ -218,6 +219,23 @@ function checkHooks({ root, colabHome, home, env }) {
218
219
  return rows;
219
220
  }
220
221
 
222
+ /**
223
+ * notifyUrl against a DECLARED local observer (#414). Silent unless something says an observer runs
224
+ * here: a machine with no <COLAB_HOME>/notify-endpoint gets no row at all — unset is the right default
225
+ * there, and a ⚠ on every such machine would teach people to ignore the row. ⚠ rather than ✗: the
226
+ * key is something never set up, not something installed that went stale.
227
+ */
228
+ function checkNotify({ colabHome }) {
229
+ let cfg = {};
230
+ try { cfg = JSON.parse(readText(path.join(colabHome, 'config.json')) || '{}'); } catch (_) { /* reported by colab itself */ }
231
+ const st = notifyEndpoint.status(cfg, colabHome);
232
+ if (st.state === 'unset') return [];
233
+ if (st.state === 'set' && !st.declared) {
234
+ return [{ area: 'notify', severity: OK, text: `notifyUrl = ${st.url}` }];
235
+ }
236
+ return [{ area: 'notify', severity: WARN, text: notifyEndpoint.healthLine(st) }];
237
+ }
238
+
221
239
  function runChecks(opts) {
222
240
  const o = { env: process.env, ...opts };
223
241
  return [
@@ -226,6 +244,7 @@ function runChecks(opts) {
226
244
  checkState(o),
227
245
  ...checkFleet(o),
228
246
  ...checkHooks(o),
247
+ ...checkNotify(o),
229
248
  ];
230
249
  }
231
250
 
@@ -255,5 +274,5 @@ if (require.main === module) {
255
274
 
256
275
  module.exports = {
257
276
  OK, WARN, FAIL,
258
- dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, runChecks, render,
277
+ dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
259
278
  };