unitbob 0.4.4 → 0.5.0

package/dist/runner/precheck.js

@@ -1,18 +1,36 @@
-import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-const defaultDeps = {
-    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
-};
+import { defaultToolDeps, hasGemfileWith, locateRunner, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, } from "./toolchain.js";
+const defaultDeps = defaultToolDeps;
 const STACKS = 'Ruby on Rails + RSpec, JavaScript/TypeScript + Vitest, or Python + pytest';
 // Tried in this order, so a project carrying markers for more than one stack
 // resolves to the same runner on every run.
 const STRUCTURAL_RUNNERS = ['rspec', 'vitest', 'pytest'];
+// The file that says "this project is written in this language". Nothing here
+// asks whether the runner is installed — that is a separate question with a
+// separate answer, and merging the two is what made this gate lie.
+//
+// A project whose language is obvious but whose runner is missing used to fail
+// detection, and the caller then reported the only thing it had left: "this
+// project matches none of those stacks". That sentence was false — the project
+// was Python, it simply had no pytest — and it sent people to look for a problem
+// with their project instead of at the one command that fixes it. The runner is
+// now provisioned under `.unitbob/` (see `ensureStructuralRunner`), so the
+// question this gate answers is the one it can answer honestly: which language.
+const PYTHON_MARKERS = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
+function looksLikePython(projectRoot) {
+    return PYTHON_MARKERS.some((name) => existsSync(join(projectRoot, name)));
+}
+const STACK_MARKERS = {
+    rspec: (projectRoot) => hasGemfileWith(projectRoot, /\brails\b/),
+    vitest: (projectRoot) => existsSync(join(projectRoot, 'package.json')),
+    pytest: looksLikePython,
+};
 // Which structural runner this project's markers select, or null when none do.
 // The gate below walks the same list: "is any stack present" and "which one is
 // it" must never be able to disagree.
-export function detectStructuralRunner(projectRoot, deps = defaultDeps) {
-    return STRUCTURAL_RUNNERS.find((runner) => validateStack(projectRoot, runner, deps).ok) ?? null;
+export function detectStructuralRunner(projectRoot, _deps = defaultDeps) {
+    return STRUCTURAL_RUNNERS.find((runner) => STACK_MARKERS[runner]?.(projectRoot)) ?? null;
 }
 // The BDD runner for a structural stack. One project, one language: the
 // behavioral peer follows the stack already detected instead of probing the
@@ -33,7 +51,10 @@ export function detectBddRunner(projectRoot, deps = defaultDeps) {
     const structural = detectStructuralRunner(projectRoot, deps);
     return structural ? BDD_RUNNER_FOR_STACK[structural] ?? null : null;
 }
-// The generation-time gate: at least one supported stack must be present.
+// The generation-time gate: at least one supported stack must be present. It
+// says nothing about whether the runner is installed, because by the time that
+// matters the runner has been provisioned; `runnerReadyPrecheck` is the check
+// for that, and it runs straight after provisioning.
 export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
     const runner = detectStructuralRunner(projectRoot, deps);
     if (runner !== null)
@@ -43,6 +64,54 @@ export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
         message: `Unitbob guardrails support ${STACKS} only. This project matches none of those stacks.`,
     };
 }
+// Is the runner startable now, after provisioning has had its turn?
+//
+// Not the same question as `validateStack`, and the difference is the sidecar.
+// `validateStack` asks whether the *project* is set up for a stack — the right
+// question when a host has chosen one and nothing has been installed yet. This
+// asks whether anything on this machine can start the runner, which includes
+// the environment Unitbob just built under `.unitbob/`.
+//
+// Asking the first question in the second's place refuses a project we have
+// only just finished preparing: a JS project with no vitest of its own was
+// told to `npm i -D vitest` seconds after a working vitest was installed for
+// it. Found on the connector's own repository, 2026-08-12.
+export function runnerReadyPrecheck(projectRoot, runner, deps = defaultDeps) {
+    // Ruby is the one stack whose lookup can never come back empty — `bundle exec
+    // rspec` is always a command one could type — so readiness is the gem being
+    // resolvable, from the sidecar Gemfile or from the project's own.
+    const ready = runner === 'rspec'
+        ? locateRunner(projectRoot, 'rspec')?.source === 'sidecar' || projectProvidesRunner(projectRoot, 'rspec', deps)
+        : runnerAvailable(projectRoot, runner, deps);
+    if (ready)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `The ${runner} runner is not available: it is not installed in this project, and Unitbob could ` +
+            `not install one for itself under ${SIDECAR_DIR}/. Nothing was written and nothing was uploaded.`,
+    };
+}
+// Has Unitbob built this runner for this project already? One question, asked
+// the same way by every precheck that would otherwise advise the user to install
+// something they now have.
+//
+// Ruby needs the second half. Its sidecar is a Gemfile, and `provisionRspec`
+// writes that file *before* it runs bundler and leaves it in place when bundler
+// fails — so its mere existence says "we tried", not "it is there", and taking
+// it as proof would silence the rspec-rails advice exactly when the install
+// failed and the advice is what the user needs. Bundler rewrites the sidecar
+// lock on success, and the project's own lock cannot name a gem its Gemfile
+// lacks, so the gem appearing there is the first artefact that means it
+// resolves. The vitest side needs nothing extra: `locateVitest` tests the actual
+// `.bin/vitest` executable.
+function sidecarProvides(projectRoot, runner, deps = defaultDeps) {
+    if (locateRunner(projectRoot, runner, deps)?.source !== 'sidecar')
+        return false;
+    if (runner !== 'rspec')
+        return true;
+    const lock = join(projectRoot, SIDECAR_DIR, 'Gemfile.lock');
+    return existsSync(lock) && /\brspec-rails\s+\(/.test(readFileSync(lock, 'utf8'));
+}
 // Confirm the host-selected runner against local markers. A mismatch fails
 // closed: the caller writes no files and uploads nothing.
 //
@@ -56,9 +125,9 @@ export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
 export function validateStack(projectRoot, runner, deps = defaultDeps) {
     switch (runner) {
         case 'rspec':
-            return rubyPrecheck(projectRoot);
+            return rubyPrecheck(projectRoot, deps);
         case 'vitest':
-            return vitestPrecheck(projectRoot);
+            return vitestPrecheck(projectRoot, deps);
         case 'pytest':
             return pytestPrecheck(projectRoot, deps);
         case 'cucumber':
@@ -100,16 +169,14 @@ function jsBehavioralPrecheck(projectRoot) {
 // and message shape as the structural pytest precheck; pytest-bdd itself, if
 // missing, surfaces as a suite error from the run.
 function pythonBehavioralPrecheck(projectRoot, deps) {
-    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
-    if (!markers.some((name) => existsSync(join(projectRoot, name)))) {
+    if (!looksLikePython(projectRoot)) {
         return {
             ok: false,
             message: 'The behavioral (Gherkin) suite selected the Python stack, but this project has none of ' +
-                `${markers.join(', ')} — it does not look like a Python project.`,
+                `${PYTHON_MARKERS.join(', ')} — it does not look like a Python project.`,
         };
     }
-    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
-    if (!available) {
+    if (!runnerAvailable(projectRoot, 'pytest', deps)) {
         return {
             ok: false,
             message: 'The behavioral (Gherkin) suite selected the Python stack, but pytest is not importable in ' +
@@ -119,7 +186,7 @@ function pythonBehavioralPrecheck(projectRoot, deps) {
     }
     return { ok: true };
 }
-function rubyPrecheck(projectRoot) {
+function rubyPrecheck(projectRoot, deps) {
     if (!hasGemfileWith(projectRoot, /\brails\b/)) {
         return {
             ok: false,
@@ -129,7 +196,13 @@ function rubyPrecheck(projectRoot) {
     }
     // Specifically rspec-rails: the boot helper requires `rspec/rails`, so a
     // bare `rspec` gem passes nothing downstream — stop with the honest offer.
-    if (!hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
+    //
+    // Unless Unitbob already installed one for itself. The advice below asks the
+    // user to change their Gemfile, and that is the wrong sentence seconds after a
+    // working runner was provisioned under `.unitbob/`. `runnerReadyPrecheck`
+    // already knows this; this function used to send the reader back to the old
+    // answer regardless.
+    if (!sidecarProvides(projectRoot, 'rspec', deps) && !hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
         return {
             ok: false,
             message: "Unitbob guardrails need the rspec-rails gem, which is not in this project's " +
@@ -139,7 +212,7 @@ function rubyPrecheck(projectRoot) {
     }
     return { ok: true };
 }
-function vitestPrecheck(projectRoot) {
+function vitestPrecheck(projectRoot, deps) {
     const packageJson = join(projectRoot, 'package.json');
     if (!existsSync(packageJson)) {
         return {
@@ -147,7 +220,12 @@ function vitestPrecheck(projectRoot) {
             message: 'The JavaScript/TypeScript stack was selected, but this project has no package.json.',
         };
     }
-    const hasVitest = /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
+    // Same rule as the Ruby precheck above: a runner Unitbob installed for this
+    // project is a runner this project has. Without this the connector's own
+    // repository was told to `npm i -D vitest` seconds after a working vitest had
+    // been put under `.unitbob/` for it.
+    const hasVitest = sidecarProvides(projectRoot, 'vitest', deps) ||
+        /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
         existsSync(join(projectRoot, 'node_modules', '.bin', 'vitest'));
     if (!hasVitest) {
         return {
@@ -160,22 +238,20 @@ function vitestPrecheck(projectRoot) {
     return { ok: true };
 }
 function pytestPrecheck(projectRoot, deps) {
-    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
-    const found = markers.some((name) => existsSync(join(projectRoot, name)));
-    if (!found) {
+    if (!looksLikePython(projectRoot)) {
         return {
             ok: false,
             message: 'The Python stack was selected, but this project has none of ' +
-                `${markers.join(', ')} — it does not look like a Python project.`,
+                `${PYTHON_MARKERS.join(', ')} — it does not look like a Python project.`,
         };
     }
     // Spec 30 fails closed on runner availability: unlike marker files, pytest
-    // must actually be importable in the current interpreter, or every run would
-    // end as a "No module named pytest" suite error after files were written. We
-    // probe the same interpreters the pytest runner tries, in the same order, so
-    // the precheck and the run agree on whether pytest is runnable.
-    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
-    if (!available) {
+    // must actually be importable, or every run would end as a "No module named
+    // pytest" suite error after files were written. `runnerAvailable` asks the
+    // same question the run asks, of the same environments in the same order —
+    // the sidecar under `.unitbob/` first, then the machine's own interpreters —
+    // so the check and the run can never disagree about what is runnable.
+    if (!runnerAvailable(projectRoot, 'pytest', deps)) {
         return {
             ok: false,
             message: 'The Python stack was selected, but pytest is not importable in the current Python ' +
@@ -186,11 +262,3 @@ function pytestPrecheck(projectRoot, deps) {
     }
     return { ok: true };
 }
-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;
-}

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');