@futurelastic/colab-handbook 1.12.0-rc.16 → 1.12.0-rc.17

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
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.16"
30
+ "version": "1.12.0-rc.17"
31
31
  }
package/tools/colab CHANGED
@@ -2398,7 +2398,7 @@ function cmdGateRecorded(argv) {
2398
2398
  // `live-env:`.
2399
2399
  // ---------------------------------------------------------------------------
2400
2400
 
2401
- 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...>
2402
2402
 
2403
2403
  Runs the repo's TEST STEP twice and gives one verdict (#403, code-wrap A3):
2404
2404
 
@@ -2408,7 +2408,11 @@ Runs the repo's TEST STEP twice and gives one verdict (#403, code-wrap A3):
2408
2408
  daemon/fleet runtime unset (*_URL *_HOST *_PORT *_TOKEN *_KEY *_SECRET *_SOCK
2409
2409
  COLAB_* CLAUDE* GH_* …); network off where the platform allows it —
2410
2410
  macOS sandbox-exec, Linux unshare --net (loopback stays up in both) — and the
2411
- 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.
2412
2416
 
2413
2417
  Verdicts (exit 0 = may count as green, 1 = not):
2414
2418
  green both runs passed exit 0
@@ -2425,6 +2429,8 @@ pass \`-- sh -c '…'\` for pipes or &&.
2425
2429
  --net on do not cut the network (reported); default auto = best effort
2426
2430
  --keep A,B pass these variables through to the hermetic run anyway — printed in the
2427
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, …)
2428
2434
  --json one JSON object instead of the text verdict
2429
2435
  --verbose print each run's full output (default: failing names + a short tail on red)
2430
2436
  --repo <path> working tree to run in (default: cwd)
@@ -2440,7 +2446,7 @@ function cmdGateHermetic(argv) {
2440
2446
  const cmd = dd === -1 ? [] : argv.slice(dd + 1);
2441
2447
  const opts = parseArgs(own, {
2442
2448
  values: { '--repo': 'repo', '--net': 'net', '--keep': 'keep' },
2443
- flags: { '--json': 'json', '--verbose': 'verbose', '-h': 'help', '--help': 'help' },
2449
+ flags: { '--json': 'json', '--verbose': 'verbose', '--no-pin': 'noPin', '-h': 'help', '--help': 'help' },
2444
2450
  });
2445
2451
  if (opts.help) return print(HELP_GATE_HERMETIC);
2446
2452
  if (opts._.length) throw new UserError(`unexpected argument "${opts._[0]}" — the test command goes after \`--\` (see --help)`);
@@ -2488,7 +2494,10 @@ function cmdGateHermetic(argv) {
2488
2494
  if (normal.ok && !skip) {
2489
2495
  homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-hermetic-home-'));
2490
2496
  try {
2491
- 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 });
2492
2501
  net = hermetic.probeNetworkIsolation({
2493
2502
  platform: process.platform, mode: netMode,
2494
2503
  run: (c, a) => spawnSync(c, a, { stdio: 'ignore' }),
@@ -2508,7 +2517,7 @@ function cmdGateHermetic(argv) {
2508
2517
  verdict, ok: exitCode === 0, command: cmd,
2509
2518
  liveEnv: { skip, trunkSource, value: trunkLive.value },
2510
2519
  normal: { ok: normal.ok, exit: normal.exit },
2511
- 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,
2512
2521
  failing, notes,
2513
2522
  }, null, 2));
2514
2523
  return exitCode;
@@ -2522,6 +2531,8 @@ function cmdGateHermetic(argv) {
2522
2531
  lines.push(`hermetic run: ${herm.ok ? 'green' : 'RED'} (exit ${herm.exit === null ? 'none' : herm.exit}${herm.signal ? `, ${herm.signal}` : ''})`);
2523
2532
  lines.push(` HOME=<fresh empty dir>; unset ${envInfo.stripped.length} var(s)${envInfo.stripped.length ? `: ${envInfo.stripped.join(' ')}` : ''}`);
2524
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)');
2525
2536
  lines.push(` ${net.note}`);
2526
2537
  } else {
2527
2538
  lines.push('hermetic run: not attempted (normal run is red)');
@@ -2541,6 +2552,13 @@ function cmdGateHermetic(argv) {
2541
2552
  for (const l of hermetic.tail(out)) lines.push(` | ${l}`);
2542
2553
  }
2543
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
+ }
2544
2562
  lines.push('', `VERDICT: ${verdict} — ${hermetic.VERDICT_TEXT[verdict]}`);
2545
2563
  print(lines.join('\n'));
2546
2564
  return exitCode;
@@ -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
  };