unitbob 0.4.5 → 0.5.0

package/dist/runner/provision.js

@@ -1,13 +1,23 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
+import { defaultToolDeps, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
 // How long a local setup step may take before we stop waiting. Provisioning a
 // runner and loading a cold Rails test environment sit in the same ballpark —
 // tens of seconds on a large app — so `runner/bootcheck.ts` waits on this same
 // number rather than inventing a second one to keep in sync.
 export const PROVISION_TIMEOUT_MS = 120_000;
+// Installing an application's own dependency tree is a different order of work
+// from adding one runner gem: hundreds of packages, compiled extensions, a cold
+// package index. Two minutes is a normal figure for it, so it gets its own
+// budget instead of borrowing one sized for a single install.
+export const DEPENDENCY_INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, { cwd: options.cwd, timeoutMs: PROVISION_TIMEOUT_MS, env: { ...process.env, ...options.env } }),
+    runCmd: (command, args, options) => runProcess(command, args, {
+        cwd: options.cwd,
+        timeoutMs: options.timeoutMs ?? PROVISION_TIMEOUT_MS,
+        env: { ...process.env, ...options.env },
+    }),
 };
 export async function ensureRunner(projectRoot, runner, deps = defaultDeps) {
     const behavioralDir = join(projectRoot, '.unitbob', 'behavioral');
@@ -23,6 +33,297 @@ export async function ensureRunner(projectRoot, runner, deps = defaultDeps) {
             return { status: 'fixable', message: `Unsupported BDD runner "${runner}".` };
     }
 }
+// Make the structural runner runnable without touching the project.
+//
+// Nothing is built when the project already supplies the runner itself: a
+// developer with a working setup should not find a second copy of their
+// toolchain appear under `.unitbob/` because they tried Unitbob once.
+//
+// When the project does not supply it, everything the runner needs is installed
+// under `.unitbob/runners/` instead — the runner and, on the two stacks where it
+// is possible, the application's own dependencies with it. The project's
+// Gemfile, requirements.txt and package.json are read and never written.
+//
+// Python and Ruby get a complete environment this way. JavaScript deliberately
+// does not: node resolves an import by walking up from the importing file, so a
+// suite sitting in `.unitbob/structural/` finds the project's `node_modules` and
+// can never be made to find a sidecar copy instead. Vitest itself is installed
+// here because we spawn that binary by path; the project's dependencies stay the
+// project's, and a missing `node_modules` comes back as a fixable notice naming
+// the one command that fixes it.
+export async function ensureStructuralRunner(projectRoot, runner, deps = defaultDeps) {
+    const tools = deps.tools ?? defaultToolDeps;
+    if (projectProvidesRunner(projectRoot, runner, tools))
+        return { status: 'provisioned' };
+    const dir = join(projectRoot, SIDECAR_DIR);
+    mkdirSync(dir, { recursive: true });
+    switch (runner) {
+        case 'pytest':
+            return provisionPytest(projectRoot, deps);
+        case 'vitest':
+            return provisionVitest(projectRoot, deps);
+        case 'rspec':
+            return provisionRspec(projectRoot, deps);
+        default:
+            return { status: 'fixable', message: `Unsupported structural runner "${runner}".` };
+    }
+}
+// The builders we can make an environment with, in the order we try them.
+//
+// `python3 -m venv` before `uv` even though uv is faster: the standard-library
+// builder always puts pip in the environment it makes, and `uv venv`
+// deliberately does not. An environment with no pip is one nothing can be
+// installed into afterwards.
+//
+// And no `--system-site-packages`. Borrowing the machine's own packages looks
+// like a saving — the application's dependencies may already be installed
+// globally — but it makes the environment a different one on every machine,
+// which is the one thing a sidecar exists to prevent. It also lets pytest pick
+// up plugins nobody asked for: measured on a Flask app where an unrelated
+// globally-installed langsmith plugin was loaded into the run and died on a
+// pydantic/typing_extensions mismatch, so a project that imports perfectly well
+// could not be collected. This environment holds the requirements file and
+// pytest, and nothing else. Found 2026-08-12.
+const VENV_BUILDERS = [
+    { command: 'python3', args: (venvDir) => ['-m', 'venv', venvDir] },
+    { command: 'python', args: (venvDir) => ['-m', 'venv', venvDir] },
+    { command: 'uv', args: (venvDir) => ['venv', venvDir] },
+];
+// A virtual environment under `.unitbob/runners/.venv` holding pytest and, when
+// the project declares them in a requirements file, the application's own
+// packages — and deliberately nothing else. See `VENV_BUILDERS`.
+async function provisionPytest(projectRoot, deps) {
+    const venvDir = sidecarPath(projectRoot, '.venv');
+    const venvPython = join(venvDir, 'bin', 'python');
+    const built = await buildPythonEnvironment(projectRoot, venvDir, deps);
+    if (!built.created) {
+        return {
+            status: 'fixable',
+            message: `Failed to create a virtual environment under ${SIDECAR_DIR}/.venv.`,
+            checklist: ['Install python3-venv or uv: `python3 -m venv --help`, or `pip install uv`.'],
+        };
+    }
+    const pytest = await pipInstall(deps, projectRoot, venvPython, ['pytest']);
+    const notes = built.requirementsNote ? [built.requirementsNote] : [];
+    if (pytest.ok || runnerAvailable(projectRoot, 'pytest', deps.tools ?? defaultToolDeps)) {
+        return notes.length > 0 ? { status: 'provisioned', checklist: notes } : { status: 'provisioned' };
+    }
+    return {
+        status: 'fixable',
+        message: `Failed to install pytest into ${SIDECAR_DIR}/.venv.`,
+        checklist: [`Run \`${venvPython} -m pip install pytest\` manually to provision the runner.`, ...notes],
+    };
+}
+// Build a Python environment holding the application's declared dependencies,
+// and say so honestly when they would not go in. Both branches call it: the
+// structural suite imports the application and the behavioral suite drives it,
+// so neither is any use in an environment the application is not installed in.
+//
+// An interpreter that is merely present is not one the project can run on. A
+// machine can easily carry a Python newer than everything the project pins —
+// measured on a Flask app whose psycopg2, greenlet and multidict have no wheels
+// for 3.14 and do not compile against it, while the 3.11 standing beside it
+// installs all three from wheels in seconds. So when the requirements will not
+// go in, the environment is rebuilt with the next builder rather than handed
+// over half-empty. Found 2026-08-12.
+async function buildPythonEnvironment(projectRoot, venvDir, deps) {
+    const venvPython = join(venvDir, 'bin', 'python');
+    // The project's own statement of what it needs. It is also the only test of
+    // whether an environment is any use: one the application's packages will not
+    // install into is the wrong environment, however well it was built.
+    const requirements = ['requirements.txt', 'requirements/base.txt', 'requirements-dev.txt']
+        .find((name) => existsSync(join(projectRoot, name)));
+    let created = existsSync(venvPython);
+    let requirementsOk = requirements === undefined;
+    let failure;
+    for (const [index, builder] of VENV_BUILDERS.entries()) {
+        if (!created) {
+            const result = await deps
+                .runCmd(builder.command, builder.args(venvDir), { cwd: projectRoot })
+                .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+            if (result.code !== 0)
+                continue;
+            created = true;
+        }
+        if (requirements === undefined)
+            break;
+        const installed = await pipInstall(deps, projectRoot, venvPython, ['-r', requirements]);
+        if (installed.ok) {
+            requirementsOk = true;
+            break;
+        }
+        // Keep the first complaint: it comes from the interpreter the project would
+        // have been given by default, and it is the one worth reporting if no
+        // interpreter here works.
+        failure ??= installed.detail ?? '';
+        // Discard the environment only while there is another builder to try. The
+        // last one is kept even though the requirements did not go in: the runner
+        // still installs into it, and a suite that runs and cannot import the
+        // application says far more than no suite at all.
+        if (index === VENV_BUILDERS.length - 1)
+            break;
+        rmSync(venvDir, { recursive: true, force: true });
+        created = false;
+    }
+    if (!created)
+        return { created };
+    if (requirements === undefined) {
+        return { created, requirementsNote: noDependencySourceNote(projectRoot, venvDir) };
+    }
+    if (requirementsOk)
+        return { created };
+    // The reason travels with the notice. Without it the reader is told that
+    // something did not install and has to re-run the install by hand to find out
+    // what — and the answer is usually one line ("no wheel for this Python",
+    // "pg_config not found") that decides what they do next.
+    return {
+        created,
+        requirementsNote: `installing ${requirements} into ${relativeVenv(projectRoot, venvDir)} did not finish on any Python ` +
+            `available here — the suite may not be able to import the application.` +
+            (failure ? ` The install said: ${failure}` : ''),
+    };
+}
+// A Python project that states its dependencies somewhere other than a
+// requirements file was the quietest failure in here: nothing found to install
+// was read as nothing to install, the environment was declared a success, and
+// the suite then met the application it could not import. Detection accepts
+// `pyproject.toml` and `Pipfile` (see `precheck.ts`) while this function only
+// ever read `requirements*.txt`, so the two disagreed about what a Python
+// project is.
+//
+// Installing from those two sources is not attempted here yet. Saying so is not
+// optional: "we did not install your application's packages, and here is why"
+// is a sentence the reader can act on, and an empty environment reported as
+// built is not.
+function noDependencySourceNote(projectRoot, venvDir) {
+    const declared = ['pyproject.toml', 'Pipfile'].filter((name) => existsSync(join(projectRoot, name)));
+    const where = declared.length
+        ? `this project declares its dependencies in ${declared.join(' and ')}, which Unitbob does not install from yet`
+        : 'no requirements.txt, pyproject.toml or Pipfile was found';
+    return (`the application's own packages are not installed into ${relativeVenv(projectRoot, venvDir)} — ${where}. ` +
+        'The suite can start, but it may not be able to import the application.');
+}
+// Install into the sidecar environment, whichever tool built it.
+//
+// `python -m pip` rather than the `bin/pip` script: the script is missing from a
+// uv-built environment, and calling a path that is not there throws ENOENT,
+// which reads as "the install failed" when nothing was ever attempted. `uv pip`
+// is the second attempt for exactly that environment.
+async function pipInstall(deps, projectRoot, venvPython, packages) {
+    let last;
+    for (const candidate of [
+        { command: venvPython, args: ['-m', 'pip', 'install', ...packages] },
+        { command: 'uv', args: ['pip', 'install', '--python', venvPython, ...packages] },
+    ]) {
+        last = await deps
+            .runCmd(candidate.command, candidate.args, { cwd: projectRoot, timeoutMs: DEPENDENCY_INSTALL_TIMEOUT_MS })
+            .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+        if (last.code === 0)
+            return { ok: true };
+    }
+    return { ok: false, detail: last ? installerComplaint(last) : undefined };
+}
+// The one line of an installer's output that says what went wrong. pip prints
+// hundreds of lines of compiler noise and, among the lines that do look like
+// errors, one is a verbatim dump of the compiler command — three hundred
+// characters of flags whose only readable part is the word "clang". That line
+// is dropped along with anything else too long to be a summary, which leaves
+// pip's own verdict ("Failed building wheel for psycopg2-binary").
+function installerComplaint(result) {
+    const complaints = `${result.stdout}\n${result.stderr}`
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => /^(error|ERROR|×|note: This error|Failed to build)/.test(line))
+        .filter((line) => line.length <= 160 && !line.includes("Command '["));
+    return complaints[complaints.length - 1];
+}
+// Vitest under `.unitbob/runners/node_modules`, spawned by path. See the note on
+// `ensureStructuralRunner` for why the application's own packages are not
+// installed here.
+async function provisionVitest(projectRoot, deps) {
+    writeIfChanged(sidecarPath(projectRoot, 'package.json'), JSON.stringify({ name: 'unitbob-structural-sidecar', private: true, devDependencies: { vitest: '^3.0.0' } }, null, 2) + '\n');
+    if (!runnerAvailable(projectRoot, 'vitest')) {
+        const installed = await firstSuccess(deps, projectRoot, [
+            { command: 'npm', args: ['install', '--prefix', SIDECAR_DIR] },
+            { command: 'pnpm', args: ['install', '--prefix', SIDECAR_DIR] },
+            { command: 'yarn', args: ['install', '--cwd', SIDECAR_DIR] },
+        ], DEPENDENCY_INSTALL_TIMEOUT_MS);
+        if (!installed && !runnerAvailable(projectRoot, 'vitest')) {
+            return {
+                status: 'fixable',
+                message: `Failed to install vitest into ${SIDECAR_DIR}.`,
+                checklist: [`Install it manually: \`npm install --prefix ${SIDECAR_DIR}\`.`],
+            };
+        }
+    }
+    // The suite imports the application, and on this stack that resolves through
+    // the project's own node_modules — the one thing a sidecar cannot stand in for.
+    if (existsSync(join(projectRoot, 'package.json')) && !existsSync(join(projectRoot, 'node_modules'))) {
+        return {
+            status: 'provisioned',
+            checklist: [
+                "This project's own dependencies are not installed (`node_modules` is missing), and on this stack " +
+                    'they cannot be installed under `.unitbob/` — node resolves imports from the project itself. ' +
+                    'Run `npm install` in the project before generating, or the suite will not be able to import it.',
+            ],
+        };
+    }
+    return { status: 'provisioned' };
+}
+// A sidecar Gemfile that inherits the project's own, plus rspec-rails. Bundler
+// resolves the two together, so the application's gems come with it — the same
+// arrangement the Cucumber sidecar has used since spec 32-1, and the reason the
+// project's Gemfile is read rather than edited.
+async function provisionRspec(projectRoot, deps) {
+    const sidecarGemfile = sidecarPath(projectRoot, 'Gemfile');
+    writeIfChanged(sidecarGemfile, '# Sidecar Gemfile written by the unitbob connector — do not edit.\n' +
+        'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
+        'gem "rspec-rails", require: false\n');
+    // Start from the project's own resolution for the reason spelled out on the
+    // Cucumber sidecar below: without it bundler re-resolves the whole graph and
+    // hands the sidecar versions the project does not run.
+    copyLockIfPresent(projectRoot, sidecarPath(projectRoot, 'Gemfile.lock'));
+    const localBundle = join(projectRoot, 'bin', 'bundle');
+    const command = existsSync(localBundle) ? localBundle : 'bundle';
+    const result = await deps
+        .runCmd(command, ['install'], {
+        cwd: projectRoot,
+        env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile` },
+        timeoutMs: DEPENDENCY_INSTALL_TIMEOUT_MS,
+    })
+        .catch((err) => ({ code: 1, stdout: '', stderr: String(err) }));
+    if (result.code === 0)
+        return { status: 'provisioned' };
+    return {
+        status: 'fixable',
+        message: `Bundler failed to provision rspec-rails under ${SIDECAR_DIR}.`,
+        checklist: [
+            'Ensure bundler is installed (`gem install bundler`), then run ' +
+                `\`BUNDLE_GEMFILE=${SIDECAR_DIR}/Gemfile bundle install\` from the project root.`,
+        ],
+    };
+}
+// Run each candidate until one exits zero. Used for the "uv, else venv" and
+// "npm, else pnpm, else yarn" ladders, which are the same shape.
+async function firstSuccess(deps, cwd, candidates, timeoutMs) {
+    for (const candidate of candidates) {
+        const result = await deps
+            .runCmd(candidate.command, candidate.args, { cwd, timeoutMs })
+            .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+        if (result.code === 0)
+            return true;
+    }
+    return false;
+}
+function writeIfChanged(path, content) {
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== content)
+        writeFileSync(path, content);
+}
+function copyLockIfPresent(projectRoot, destination) {
+    const projectLock = join(projectRoot, 'Gemfile.lock');
+    if (existsSync(projectLock))
+        writeFileSync(destination, readFileSync(projectLock, 'utf8'));
+}
 async function provisionRuby(projectRoot, behavioralDir, deps) {
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
@@ -71,37 +372,36 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
 }
 async function provisionPython(projectRoot, behavioralDir, deps) {
     const venvDir = join(behavioralDir, '.venv');
-    const venvPip = join(venvDir, 'bin', 'pip');
+    const venvPython = join(venvDir, 'bin', 'python');
     const venvPytest = join(venvDir, 'bin', 'pytest');
-    if (existsSync(venvPytest)) {
-        return { status: 'provisioned' };
-    }
-    // Ladder: uv -> python3 -m venv --system-site-packages
-    const uvResult = await deps.runCmd('uv', ['venv', venvDir, '--system-site-packages'], { cwd: projectRoot }).catch(() => ({ code: 1 }));
-    let venvCreated = uvResult.code === 0;
-    if (!venvCreated) {
-        const venvResult = await deps
-            .runCmd('python3', ['-m', 'venv', '--system-site-packages', venvDir], { cwd: projectRoot })
-            .catch(() => ({ code: 1 }));
-        venvCreated = venvResult.code === 0;
-    }
-    if (!venvCreated) {
+    // The behavioral suite drives the application, so its environment needs the
+    // application in it — the same requirement, and now the same treatment, as the
+    // structural peer. It used to be built with `--system-site-packages` and given
+    // nothing but pytest-bdd, on the assumption that the machine already had the
+    // project's packages. On a machine that did not, every scenario failed on
+    // `No module named flask` in an environment Unitbob had just built for it.
+    const built = await buildPythonEnvironment(projectRoot, venvDir, deps);
+    if (!built.created) {
         return {
             status: 'fixable',
-            message: 'Failed to create virtual environment under .unitbob/behavioral/.venv.',
+            message: `Failed to create virtual environment under ${relativeVenv(projectRoot, venvDir)}.`,
             checklist: ['Install python3-venv or uv: `python3 -m venv --help` or `pip install uv`.'],
         };
     }
-    // Install pytest-bdd into the sidecar venv
-    const pipResult = await deps.runCmd(venvPip, ['install', 'pytest-bdd'], { cwd: projectRoot }).catch(() => ({ code: 1 }));
-    if (pipResult.code === 0 || existsSync(venvPytest)) {
-        return { status: 'provisioned' };
+    const installed = existsSync(venvPytest) || (await pipInstall(deps, projectRoot, venvPython, ['pytest-bdd'])).ok;
+    if (!installed && !existsSync(venvPytest)) {
+        return {
+            status: 'fixable',
+            message: `Failed to install pytest-bdd into ${relativeVenv(projectRoot, venvDir)}.`,
+            checklist: [`Run \`${venvPython} -m pip install pytest-bdd\` manually to provision the runner.`],
+        };
     }
-    return {
-        status: 'fixable',
-        message: 'Failed to install pytest-bdd into .unitbob/behavioral/.venv.',
-        checklist: [`Run \`${venvPip} install pytest-bdd\` manually to provision the runner.`],
-    };
+    return built.requirementsNote
+        ? { status: 'provisioned', checklist: [built.requirementsNote] }
+        : { status: 'provisioned' };
+}
+function relativeVenv(projectRoot, venvDir) {
+    return venvDir.startsWith(projectRoot) ? venvDir.slice(projectRoot.length + 1) : venvDir;
 }
 async function provisionJs(projectRoot, behavioralDir, deps) {
     const sidecarPkg = join(behavioralDir, 'package.json');

package/dist/runner/pytest.js

@@ -2,6 +2,7 @@ import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const PYTEST_TIMEOUT_MS = 10 * 60 * 1000;
 export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
@@ -11,19 +12,34 @@ export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
 // never part of the suite digest.
 export const PYTEST_INI_FILE = join('.unitbob', 'pytest.ini');
 export const PYTEST_INI = '[pytest]\naddopts =\n';
-// Run the materialised Unitbob guardrail suite with pytest in the current
-// Python environment (spec 30) — no guessing at Poetry/uv/virtualenv wrappers.
-// Only the guardrail file runs; the JUnit XML report goes to --junit-xml, not
-// stdout. The command is connector-owned: the suite artifact never carries a
-// command string.
-export async function runPytestSuite(projectRoot, suitePath) {
+// Run the materialised Unitbob guardrail suite with pytest (spec 30) — no
+// guessing at Poetry/uv/virtualenv wrappers. Only the guardrail files run; the
+// JUnit XML report goes to --junit-xml, not stdout. The command is
+// connector-owned: the suite artifact never carries a command string.
+//
+// Every file of the branch is named positionally (spec 42, §6.5) — a branch is
+// one file per assignment now, and pytest takes as many paths as it is given.
+//
+// Which pytest is a single question answered in one place (`locateRunner`), so
+// the precheck, the boot check and this run can never end up talking about
+// different interpreters. `python` is the last resort when nothing was found:
+// spawning it produces the honest "No module named pytest" rather than a silent
+// no-op, and the checks upstream have already had their chance to say so first.
+export async function runPytestSuite(projectRoot, suitePaths) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
-    const command = await pickPython(projectRoot);
-    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, suitePath, `--junit-xml=${PYTEST_RESULT_FILE}`];
+    const located = locateRunner(projectRoot, 'pytest');
+    const command = located?.command ?? 'python';
+    const args = [
+        ...(located?.args ?? ['-m', 'pytest']),
+        '-c',
+        PYTEST_INI_FILE,
+        ...suitePaths,
+        `--junit-xml=${PYTEST_RESULT_FILE}`,
+    ];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: PYTEST_TIMEOUT_MS,
-        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, UNITBOB_REPO_ROOT: projectRoot },
     });
     return {
         ...result,
@@ -33,14 +49,3 @@ export async function runPytestSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, PYTEST_RESULT_FILE)),
     };
 }
-// The interpreter that can actually run pytest: `python3` when pytest imports
-// there (macOS/Linux ship no bare `python`), else `python`. Probing `-m pytest`
-// rather than just `--version` keeps this in step with pytestPrecheck, so the
-// run uses the same interpreter the precheck confirmed.
-async function pickPython(projectRoot) {
-    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
-        cwd: projectRoot,
-        timeoutMs: 10_000,
-    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
-    return probe.code === 0 ? 'python3' : 'python';
-}

package/dist/runner/rspec.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
-import { executable, runProcess } from "../proc.js";
+import { runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
+import { locateRunner } from "./toolchain.js";
 import { readReport } from "./types.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
@@ -8,17 +9,23 @@ export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // the project's random ordering.
 export const RSPEC_SEED = '1';
 export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
-// Run the materialised Unitbob guardrail suite (spec 26). Only this file runs —
+// Run the materialised Unitbob guardrail suite (spec 26). Only these files run —
 // never the project's full suite — under RAILS_ENV=test with a fixed order/seed.
 // --options points at the materialized empty file so the project's own .rspec
 // (a --require of a helper we replaced, an extra stdout formatter) can neither
 // break the boot nor corrupt the JSON output. The JSON report goes to `--out`
 // (a file), not stdout, so the app's own stdout writes during the run can never
-// corrupt it. `suitePath` is the suite blob's own project-relative path.
-export async function runRspecSuite(projectRoot, suitePath) {
+// corrupt it.
+//
+// `suitePaths` is every file of the branch in the suite blob's own
+// project-relative form (spec 42, §6.5). Named one by one rather than as a
+// directory: the artifact already says exactly which files it is, while a
+// directory would also collect whatever else happens to be sitting under the
+// root.
+export async function runRspecSuite(projectRoot, suitePaths) {
     const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
     const { result, command, args } = await invokeRspec(projectRoot, [
-        suitePath,
+        ...suitePaths,
         '--options',
         optionsPath,
         '--order',
@@ -38,18 +45,19 @@ export async function runRspecSuite(projectRoot, suitePath) {
         report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
     };
 }
-// Prefer the project's own `bin/rspec`; fall back to `bundle exec rspec`. Every
+// Which rspec — the sidecar Unitbob installed, the project's own `bin/rspec`
+// binstub, or `bundle exec rspec` — is decided once, in `locateRunner`, so this
+// run and the checks that predicted it always mean the same installation. Every
 // run sets RAILS_ENV=test so guardrails execute against the Rails test
 // environment the project's `rails_helper` configures.
 async function invokeRspec(projectRoot, rspecArgs) {
-    const localRspec = join(projectRoot, 'bin', 'rspec');
-    const hasLocalRspec = executable(localRspec);
-    const command = hasLocalRspec ? localRspec : 'bundle';
-    const args = hasLocalRspec ? rspecArgs : ['exec', 'rspec', ...rspecArgs];
+    const located = locateRunner(projectRoot, 'rspec');
+    const command = located?.command ?? 'bundle';
+    const args = [...(located?.args ?? ['exec', 'rspec']), ...rspecArgs];
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: RSPEC_TIMEOUT_MS,
-        env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+        env: { ...process.env, ...located?.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
     });
     return { result, command, args };
 }

package/dist/runner/toolchain.js

@@ -0,0 +1,122 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { executable } from "../proc.js";
+// Where Unitbob keeps a test runner it had to install for itself, together with
+// whatever that runner needs to load the project.
+//
+// Deliberately not `.unitbob/structural/`: `materializeGuardrails` deletes that
+// directory before every suite write, so an environment installed there would be
+// rebuilt on every single run. Deliberately not the project's own dependency
+// files either — the whole point is that a vibecoder's repository looks exactly
+// the same after Unitbob has run as it did before. `.unitbob/` is already in
+// their .gitignore (see `ensureUnitbobIgnored`).
+export const SIDECAR_DIR = '.unitbob/runners';
+export function sidecarPath(projectRoot, ...segments) {
+    return join(projectRoot, SIDECAR_DIR, ...segments);
+}
+export const defaultToolDeps = {
+    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+};
+// How to invoke `runner` in this project, or null when nothing here can.
+//
+// The sidecar wins when it exists, and that order is deliberate. A sidecar is
+// only ever built because the project could not supply the runner itself, so
+// preferring it keeps every later run on the same environment the build was
+// prepared against. The alternative — asking the project first, every time —
+// lets a stray `pip install pytest` between two runs move the suite to a
+// different interpreter without anybody choosing that, and a guardrail suite
+// whose meaning is "green means fine" cannot afford a silent environment flip.
+export function locateRunner(projectRoot, runner, deps = defaultToolDeps) {
+    switch (runner) {
+        case 'pytest':
+            return locatePytest(projectRoot, deps);
+        case 'vitest':
+            return locateVitest(projectRoot);
+        case 'rspec':
+            return locateRspec(projectRoot);
+        default:
+            return null;
+    }
+}
+// Is a runner available at all — from the project or from a sidecar?
+export function runnerAvailable(projectRoot, runner, deps = defaultToolDeps) {
+    return locateRunner(projectRoot, runner, deps) !== null;
+}
+// Does the project supply this runner on its own, with no help from us? This is
+// the question provisioning asks before it builds anything: a project that is
+// already set up is left completely alone.
+//
+// Ruby answers from the Gemfile rather than from `locateRspec`, which always has
+// a `bundle exec rspec` to offer whether or not the gem behind it exists.
+export function projectProvidesRunner(projectRoot, runner, deps = defaultToolDeps) {
+    if (runner === 'rspec') {
+        return hasGemfileWith(projectRoot, /\brails\b/) && hasGemfileWith(projectRoot, /\brspec-rails\b/);
+    }
+    return locateRunner(projectRoot, runner, deps)?.source === 'project';
+}
+// Does one of the project's Gemfiles mention this? Shared by the Ruby precheck
+// and by the question above, so "is this a Rails project" is answered the same
+// way wherever it is asked.
+export function hasGemfileWith(projectRoot, pattern) {
+    for (const name of ['Gemfile', 'gems.rb']) {
+        const path = join(projectRoot, name);
+        if (existsSync(path) && pattern.test(readFileSync(path, 'utf8')))
+            return true;
+    }
+    return false;
+}
+// Python: an interpreter that can actually import pytest. The sidecar venv is
+// checked by file, the project's interpreters by asking them — `python3 -m
+// pytest --version` is the same question the run itself asks, so the two can
+// never disagree about which interpreter is usable.
+function locatePytest(projectRoot, deps) {
+    // The sidecar interpreter is asked the same question as any other, rather
+    // than trusted because the file is there. A virtualenv can exist and still
+    // have no pytest in it — `uv venv` creates one with no pip at all, so an
+    // install into it can fail while leaving a perfectly good `bin/python`
+    // behind. Trusting the file made provisioning report success and the boot
+    // check then say "No module named pytest" about an environment we had just
+    // built. Found on a Flask project, 2026-08-12.
+    const venvPython = sidecarPath(projectRoot, '.venv', 'bin', 'python');
+    if (executable(venvPython) && deps.commandSucceeds(venvPython, ['-m', 'pytest', '--version'], projectRoot)) {
+        return { command: venvPython, args: ['-m', 'pytest'], source: 'sidecar' };
+    }
+    for (const python of ['python3', 'python']) {
+        if (deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot)) {
+            return { command: python, args: ['-m', 'pytest'], source: 'project' };
+        }
+    }
+    return null;
+}
+// JS/TS: a vitest binary we can spawn. `npx` is not offered here — it would
+// install a package to answer a question, and this function's callers include
+// checks that must not install anything. The vitest runner keeps `npx` as its
+// own last resort, which is the behaviour it has always had.
+function locateVitest(projectRoot) {
+    const sidecar = sidecarPath(projectRoot, 'node_modules', '.bin', 'vitest');
+    if (executable(sidecar))
+        return { command: sidecar, args: [], source: 'sidecar' };
+    const project = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    if (executable(project))
+        return { command: project, args: [], source: 'project' };
+    return null;
+}
+// Ruby: bundler decides what "rspec" means, so the sidecar is selected by
+// pointing BUNDLE_GEMFILE at the sidecar Gemfile rather than by a different
+// binary. The project's own `bin/rspec` binstub is preferred over `bundle exec`
+// when it is there, exactly as the rspec runner has always preferred it.
+function locateRspec(projectRoot) {
+    if (existsSync(sidecarPath(projectRoot, 'Gemfile'))) {
+        return {
+            command: 'bundle',
+            args: ['exec', 'rspec'],
+            env: { BUNDLE_GEMFILE: `${SIDECAR_DIR}/Gemfile` },
+            source: 'sidecar',
+        };
+    }
+    const binstub = join(projectRoot, 'bin', 'rspec');
+    if (executable(binstub))
+        return { command: binstub, args: [], source: 'project' };
+    return { command: 'bundle', args: ['exec', 'rspec'], source: 'project' };
+}