@cleocode/core 2026.10.4 → 2026.10.5-rc.ci.672

package/dist/tasks/tool-runner-guard.js

@@ -0,0 +1,141 @@
+/**
+ * Test-runner guard for the evidence tool runner (T13203).
+ *
+ * `runToolCached` starts a project's own toolchain (`pnpm run test`, the build,
+ * lint, typecheck). Called from inside a test runner, the most likely cause is a
+ * mock that no longer intercepts. A stale barrel mock once let a vitest worker
+ * run `pnpm run test`, and every worker of that suite did the same: whole-suite
+ * runs multiplied across the machine (the T13121 saturation class).
+ *
+ * Inside a test runner the runner therefore refuses to spawn a tool, with
+ * {@link ToolSpawnInTestRunnerError}, unless the test injected a process
+ * runner through {@link injectToolProcessRunner}. A test that really wants a
+ * child process (the tool-cache suites run tiny `node -e` commands) opts in by
+ * injecting the real runner on purpose; nothing reaches it by accident.
+ *
+ * @module
+ * @task T13203
+ */
+import { ExitCode } from '@cleocode/contracts/exit-codes.js';
+import { CleoError } from '../errors.js';
+/** Environment variables that mean "this process is a test runner or its worker". */
+export const TEST_RUNNER_ENV_MARKERS = ['VITEST', 'VITEST_WORKER_ID', 'JEST_WORKER_ID'];
+/**
+ * Name the test-runner marker present in `env`, if any.
+ *
+ * @param env - Environment to inspect (injectable for tests).
+ * `NODE_ENV=test` is deliberately not a marker: developer shells and tools set
+ * it, and refusing a human's `cleo verify` would be a regression. Every vitest
+ * and jest worker sets one of the markers above.
+ *
+ * @returns The marker (`VITEST`, `VITEST_WORKER_ID` or `JEST_WORKER_ID`), or
+ *   `null` outside a test runner.
+ */
+export function detectTestRunner(env = process.env) {
+    for (const name of TEST_RUNNER_ENV_MARKERS) {
+        if (env[name] !== undefined && env[name] !== '')
+            return name;
+    }
+    return null;
+}
+/**
+ * The evidence tool runner refused to start a tool inside a test runner.
+ *
+ * @example
+ * ```ts
+ * try { await runToolCached(cmd, root); }
+ * catch (e) { if (e instanceof ToolSpawnInTestRunnerError) console.error(e.codeName); }
+ * ```
+ */
+export class ToolSpawnInTestRunnerError extends CleoError {
+    /** Stable machine-readable error code. */
+    codeName = 'E_TOOL_SPAWN_IN_TEST_RUNNER';
+    /**
+     * @param tool - Canonical tool name (`test`, `build`, …).
+     * @param command - The command line that was refused.
+     * @param marker - The test-runner marker that was detected.
+     */
+    constructor(tool, command, marker) {
+        super(ExitCode.CONFIG_ERROR, `Refused to run tool '${tool}' (${command}) inside a test runner (${marker}): ` +
+            'a test reached the real evidence tool runner, usually through a mock that no longer intercepts.', {
+            fix: 'Mock the module that calls runToolCached, or inject a runner with ' +
+                'injectToolProcessRunner() in the test that means to spawn a process.',
+            details: {
+                field: 'tool',
+                expected: 'an injected ToolProcessRunner inside a test runner',
+                actual: marker,
+                tool,
+                command,
+            },
+        });
+        this.name = 'ToolSpawnInTestRunnerError';
+    }
+}
+/**
+ * `cleo run` (`runGoverned`) refused to start a command inside a test runner
+ * (T13236): the same recursion class as {@link ToolSpawnInTestRunnerError},
+ * reached through the CLI's front door instead of the evidence runner — a
+ * test that spawns `cleo run`, or calls `runGoverned` with the real spawner,
+ * would start the suite again from inside one of its own workers.
+ *
+ * @example
+ * ```ts
+ * try { await runGoverned(opts); }
+ * catch (e) { if (e instanceof GovernedRunInTestRunnerError) console.error(e.codeName); }
+ * ```
+ */
+export class GovernedRunInTestRunnerError extends CleoError {
+    /** Stable machine-readable error code. */
+    codeName = 'E_RUN_SPAWN_IN_TEST_RUNNER';
+    /**
+     * @param command - The command line that was refused (redacted).
+     * @param marker - The test-runner marker that was detected.
+     */
+    constructor(command, marker) {
+        super(ExitCode.CONFIG_ERROR, `cleo run refused to start '${command}' inside a test runner (${marker}): ` +
+            'a test reached the real governed runner, usually through a mock that no longer intercepts.', {
+            fix: 'Mock @cleocode/core/resources/run-governed.js, or pass deps.spawn to runGoverned ' +
+                'in the test that means to start a process (spawnGovernedChild is the real one).',
+            details: {
+                field: 'command',
+                expected: 'an injected spawn inside a test runner',
+                actual: marker,
+                command,
+            },
+        });
+        this.name = 'GovernedRunInTestRunnerError';
+    }
+}
+let _injected = null;
+/**
+ * Inject the process runner the evidence tool runner uses (tests only).
+ *
+ * Passing the real runner (`spawnToolProcess` from `tool-cache.ts`) is the
+ * explicit opt-in for a test that means to start a child process. Pass `null`
+ * to restore the default.
+ *
+ * @param runner - Runner to use, or `null` for the default.
+ */
+export function injectToolProcessRunner(runner) {
+    _injected = runner;
+}
+/**
+ * Pick the process runner for one tool run.
+ *
+ * @param tool - Canonical tool name, for the refusal message.
+ * @param command - The command line, for the refusal message.
+ * @param fallback - The real runner, used outside a test runner.
+ * @param env - Environment to inspect (injectable for tests).
+ * @returns The injected runner, else `fallback` outside a test runner.
+ * @throws ToolSpawnInTestRunnerError inside a test runner with no injected runner.
+ */
+export function resolveToolProcessRunner(tool, command, fallback, env = process.env) {
+    if (_injected !== null)
+        return _injected;
+    const marker = detectTestRunner(env);
+    // @sync-invariant none:local-only refuses a local child process from a test runner; no row is written
+    if (marker !== null)
+        throw new ToolSpawnInTestRunnerError(tool, command, marker);
+    return fallback;
+}
+//# sourceMappingURL=tool-runner-guard.js.map

package/dist/tasks/tool-runner-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-runner-guard.js","sourceRoot":"","sources":["../../src/tasks/tool-runner-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA6CzC,qFAAqF;AACrF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,CAAU,CAAC;AAEjG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnE,KAAK,MAAM,IAAI,IAAI,uBAAuB,EAAE,CAAC;QAC3C,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IACvD,0CAA0C;IACjC,QAAQ,GAAG,6BAA6B,CAAC;IAElD;;;;OAIG;IACH,YAAY,IAAY,EAAE,OAAe,EAAE,MAAc;QACvD,KAAK,CACH,QAAQ,CAAC,YAAY,EACrB,wBAAwB,IAAI,MAAM,OAAO,2BAA2B,MAAM,KAAK;YAC7E,iGAAiG,EACnG;YACE,GAAG,EACD,oEAAoE;gBACpE,sEAAsE;YACxE,OAAO,EAAE;gBACP,KAAK,EAAE,MAAM;gBACb,QAAQ,EAAE,oDAAoD;gBAC9D,MAAM,EAAE,MAAM;gBACd,IAAI;gBACJ,OAAO;aACR;SACF,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,4BAA6B,SAAQ,SAAS;IACzD,0CAA0C;IACjC,QAAQ,GAAG,4BAA4B,CAAC;IAEjD;;;OAGG;IACH,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CACH,QAAQ,CAAC,YAAY,EACrB,8BAA8B,OAAO,2BAA2B,MAAM,KAAK;YACzE,4FAA4F,EAC9F;YACE,GAAG,EACD,mFAAmF;gBACnF,iFAAiF;YACnF,OAAO,EAAE;gBACP,KAAK,EAAE,SAAS;gBAChB,QAAQ,EAAE,wCAAwC;gBAClD,MAAM,EAAE,MAAM;gBACd,OAAO;aACR;SACF,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED,IAAI,SAAS,GAA6B,IAAI,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAgC;IACtE,SAAS,GAAG,MAAM,CAAC;AACrB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAY,EACZ,OAAe,EACf,QAA2B,EAC3B,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACrC,sGAAsG;IACtG,IAAI,MAAM,KAAK,IAAI;QAAE,MAAM,IAAI,0BAA0B,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjF,OAAO,QAAQ,CAAC;AAClB,CAAC"}