unitbob 0.2.8 → 0.3.0

package/dist/runner/bootcheck.js

@@ -0,0 +1,389 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { executable, runProcess } from "../proc.js";
+import { GUARDRAILS_DIR, HELPER_FILE } from "../files/guardrails.js";
+import { PYTEST_INI, PYTEST_INI_FILE } from "./pytest.js";
+import { PROVISION_TIMEOUT_MS } from "./provision.js";
+const defaultDeps = {
+    runCmd: (command, args, options) => runProcess(command, args, {
+        cwd: options.cwd,
+        timeoutMs: PROVISION_TIMEOUT_MS,
+        env: { ...process.env, ...options.env },
+    }),
+};
+// How much of a runner's output rides along in `detail`. Enough to see the
+// stack that mattered, short enough that a stop message stays readable.
+const DETAIL_LIMIT = 4_000;
+// What each stack can and cannot tell us. Printed with the finding rather than
+// kept quiet: promising all three stacks the same guarantee is exactly the kind
+// of claim spec 32-5 had to go back and delete.
+export const SIGNAL_STRENGTH = {
+    rspec: 'Full signal on this stack: the check loads the very file the suite starts from, ' +
+        'so whatever stops one stops the other.',
+    pytest: 'Partial signal on this stack: collection only imports what the tests import, so code no ' +
+        'test reaches was not checked — and it imports the whole test tree, so a failure may belong ' +
+        "to one of the project's own tests rather than to the suite that was about to be written.",
+    vitest: 'Weak signal on this stack: only test files are parsed and imported, and all of them — so a ' +
+        "failure may belong to one of the project's own tests. Type errors are not checked at all " +
+        '(vite and esbuild strip types without checking them), and a project with no tests yields ' +
+        'no signal.',
+};
+// Does the suite for this stack get off the ground? One attempt, one answer.
+export async function bootCheck(projectRoot, runner, deps = defaultDeps) {
+    switch (runner) {
+        case 'rspec':
+            return rubyBootCheck(projectRoot, deps);
+        case 'pytest':
+            return pytestBootCheck(projectRoot, deps);
+        case 'vitest':
+            return vitestBootCheck(projectRoot, deps);
+        default:
+            return { status: 'not_checked', reason: 'no_runner' };
+    }
+}
+// Ruby: load `.unitbob/structural/unitbob_helper.rb` under RAILS_ENV=test. That
+// is not a stand-in for the suite's boot — it *is* the suite's boot. The
+// generated spec's first line requires this exact file, and the helper hands off
+// to the project's own `spec/rails_helper.rb` when there is one, so factories,
+// `spec/support` and the project's own configuration all come along for free,
+// without this module knowing anything about them.
+async function rubyBootCheck(projectRoot, deps) {
+    const helper = join(projectRoot, GUARDRAILS_DIR, HELPER_FILE);
+    if (!existsSync(helper))
+        return { status: 'not_checked', reason: 'nothing_to_load' };
+    const first = await loadRubyHelper(projectRoot, helper, deps);
+    if (first.status !== 'broken')
+        return first;
+    // Repair what we are allowed to repair, then ask once more. A vibecoder has
+    // no test database — demanding one would turn away nearly every user we have.
+    // Never in a loop: one attempt, one retry, then the answer stands.
+    //
+    // Only when the failure is about the database, though. Preparing it is not
+    // free — it drops and reloads the schema, tens of seconds on a large app —
+    // and doing that in response to a syntax error is a side effect nobody asked
+    // for and a wait that buys nothing.
+    if (!looksLikeDatabase(first.detail))
+        return first;
+    if (!(await prepareTestDatabase(projectRoot, deps)))
+        return first;
+    return loadRubyHelper(projectRoot, helper, deps);
+}
+// Is this failure about the database at all? Kept as one broad signal rather
+// than a list of adapter error classes — the same reason the cause heuristics
+// stay generic. Being wrong here is cheap in one direction (a preparation we
+// did not need) and cheap in the other (we return the failure we already have,
+// which is honest either way).
+function looksLikeDatabase(detail) {
+    return /database|migration|schema|ActiveRecord::(NoDatabase|StatementInvalid|PendingMigration)/i.test(detail);
+}
+async function loadRubyHelper(projectRoot, helper, deps) {
+    // `executable`, not `existsSync` — the same test `runRspecSuite` makes of
+    // `bin/rspec`, and for the same reason. A binstub that is present but not
+    // executable makes `spawn` throw, `attempt` return null, and the answer come
+    // back `no_runner`: "no runner available to load your suite with", said to
+    // someone whose bundler is installed and working. That is the mistake
+    // `runner_too_old` and `runner_could_not_answer` were added to stop making,
+    // and the global `bundle` was standing right there the whole time.
+    const localBundle = join(projectRoot, 'bin', 'bundle');
+    const command = executable(localBundle) ? localBundle : 'bundle';
+    return classify(projectRoot, 'rspec', await attempt(deps, command, ['exec', 'ruby', '-e', `require ${JSON.stringify(helper)}`], {
+        cwd: projectRoot,
+        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+    }), 
+    // A clean load says nothing on stdout and exits 0. Anything else is the
+    // suite failing to start.
+    (result) => (result.code === 0 ? 'ok' : 'broken'));
+}
+// Python: `pytest --collect-only` imports every test module, which is what the
+// run would do first. It sees import errors in code the tests reach, and only
+// there — recorded as a limitation rather than dressed up as completeness.
+//
+// `-c` with an empty-addopts config, exactly as `runPytestSuite` does and for
+// exactly its reason: the project's own `addopts` (`--cov`, `-n auto`) must not
+// decide the answer. Without it a project whose `pytest.ini` asks for a plugin
+// that is not installed came back `broken` — a healthy application refused over
+// a `--cov` flag. The run path had already solved this; the check had not
+// inherited the solution, which also made it *stricter* than the thing it
+// predicts, the one rule this whole check is built on.
+async function pytestBootCheck(projectRoot, deps) {
+    // Its own directory, rather than relying on `materializeHelper` having run
+    // first: this check must not fail because a different step was skipped.
+    mkdirSync(join(projectRoot, dirname(PYTEST_INI_FILE)), { recursive: true });
+    writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
+    for (const python of ['python3', 'python']) {
+        const result = await attempt(deps, python, ['-m', 'pytest', '-c', PYTEST_INI_FILE, '--collect-only', '-q'], {
+            cwd: projectRoot,
+        });
+        if (result === null)
+            continue; // this interpreter is not on the machine
+        return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
+    }
+    return { status: 'not_checked', reason: 'no_runner' };
+}
+// pytest's own exit vocabulary, used rather than "zero or not". The distinction
+// that matters is between "your code did not load" and "pytest itself could not
+// be asked", and only the first is an answer about the project.
+function pytestVerdict(code) {
+    // `classify` turns a timeout into `timed_out` before asking, so this is
+    // unreachable — but "no exit code" can only ever mean "we learned nothing".
+    if (code === null)
+        return 'runner_could_not_answer';
+    // 5 — collected nothing. A project that came to Unitbob *for* tests is the
+    // typical customer, not a defect.
+    if (code === 5)
+        return 'nothing_to_load';
+    // 3 — internal error, 4 — bad usage. Both are about the invocation, not the
+    // project, so neither may read as "your suite cannot start".
+    if (code === 3 || code === 4)
+        return 'runner_could_not_answer';
+    return code === 0 ? 'ok' : 'broken';
+}
+// JS/TS: `vitest list` parses and imports the test files, which is the closest
+// thing this stack has to a boot.
+//
+// `tsc --noEmit` is deliberately not used. It answers a different question —
+// are the types sound — and a project with a hundred type errors runs perfectly
+// well, because vite, esbuild and tsx strip types without checking them. Type
+// errors accumulate for years in healthy codebases; calling that "broken" would
+// turn away the majority. A file that is genuinely unparseable is caught here
+// anyway, since `vitest list` has to parse it.
+async function vitestBootCheck(projectRoot, deps) {
+    const local = join(projectRoot, 'node_modules', '.bin', 'vitest');
+    // Only a vitest already installed in the project is used. Reaching for `npx`
+    // would install a package to answer a question, and installing into the
+    // user's project is not this check's business.
+    //
+    // `executable`, not `existsSync`, and there is no fallback to go to: an
+    // unrunnable binary sends `spawn` into EACCES, `supportsList` reads that as
+    // "cannot be asked", and the answer came back `runner_too_old` — a positive
+    // falsehood about a version nobody looked at. `no_runner` is the honest one
+    // here: there is no vitest this check can invoke.
+    if (!executable(local))
+        return { status: 'not_checked', reason: 'no_runner' };
+    // `list` is a subcommand only from Vitest 2.1. Older versions read it as a
+    // *filename filter* and go on to run whatever it matches, which was measured
+    // doing two unhelpful things: reporting "No test files found" on a project
+    // that plainly has tests, and — when a file happened to match — starting watch
+    // mode and hanging until the timeout killed it, two minutes for nothing.
+    //
+    // Neither is `broken`, so no healthy project was ever refused. But a check
+    // that quietly answers about the wrong thing is worse than one that says it
+    // did not run, so ask the version first and decline outright when the
+    // subcommand does not exist.
+    // Not `no_runner`: vitest is installed and works, it simply cannot be asked
+    // this question. Telling someone "no runner available" while it sits in their
+    // node_modules sends them to fix the wrong thing.
+    if (!(await supportsList(projectRoot, local, deps))) {
+        return { status: 'not_checked', reason: 'runner_too_old' };
+    }
+    const result = await attempt(deps, local, ['list'], { cwd: projectRoot });
+    return classify(projectRoot, 'vitest', result, (proc) => {
+        if (proc.code === 0)
+            return 'ok';
+        if (/no test files found/i.test(`${proc.stdout}\n${proc.stderr}`))
+            return 'nothing_to_load';
+        return 'broken';
+    });
+}
+// The first Vitest that has a `list` subcommand. Below this it is a filter.
+const VITEST_LIST_FROM = { major: 2, minor: 1 };
+// `vitest --version` prints e.g. `vitest/1.6.0 darwin-arm64 node-v25.2.1`. A
+// version we cannot read is treated as unsupported: guessing wrong here costs
+// either a silent non-answer or a two-minute hang, and both are worse than
+// saying plainly that the check did not run.
+async function supportsList(projectRoot, binary, deps) {
+    const result = await attempt(deps, binary, ['--version'], { cwd: projectRoot });
+    if (!result || result.code !== 0)
+        return false;
+    const found = /vitest\/(\d+)\.(\d+)/i.exec(`${result.stdout}\n${result.stderr}`);
+    if (!found)
+        return false;
+    const [major, minor] = [Number(found[1]), Number(found[2])];
+    return major > VITEST_LIST_FROM.major || (major === VITEST_LIST_FROM.major && minor >= VITEST_LIST_FROM.minor);
+}
+// Runs one command, turning "this binary is not on the machine" into null (the
+// caller decides whether that means `no_runner` or "try the next interpreter")
+// and a timeout into a ProcResult with a null code, as runProcess already does.
+async function attempt(deps, command, args, options) {
+    try {
+        return await deps.runCmd(command, args, options);
+    }
+    catch {
+        return null;
+    }
+}
+function classify(projectRoot, runner, result, verdict) {
+    if (result === null)
+        return { status: 'not_checked', reason: 'no_runner' };
+    // runProcess reports a timeout as a null exit code. Waiting too long tells us
+    // nothing about the code, so it must not read as a defect.
+    if (result.code === null)
+        return { status: 'not_checked', reason: 'timed_out' };
+    const outcome = verdict(result);
+    if (outcome === 'ok')
+        return { status: 'ok' };
+    if (outcome === 'nothing_to_load')
+        return { status: 'not_checked', reason: 'nothing_to_load' };
+    // Nothing was learned about the project, and saying otherwise would be the
+    // lie this check exists to remove.
+    if (outcome === 'runner_could_not_answer')
+        return { status: 'not_checked', reason: 'runner_could_not_answer' };
+    const output = `${result.stdout}\n${result.stderr}`.trim();
+    return {
+        status: 'broken',
+        cause: causeOf(output, projectRoot, runner),
+        message: firstErrorLine(output),
+        detail: output.length > DETAIL_LIMIT ? `${output.slice(0, DETAIL_LIMIT)}\n…` : output,
+    };
+}
+// One concept, not a catalogue of known errors — the lesson spec 32-2 drew from
+// the over-fitted regex scanner of 32-3. "A name that does not resolve to a file
+// inside this project" is the single class of failure that, in all three
+// languages, reaches project code while still being a setup step rather than a
+// defect.
+const DEPENDENCY_MISSING = [
+    /\bLoadError\b/,
+    /Bundler::GemNotFound/,
+    /\bModuleNotFoundError\b/,
+    /Cannot find module\b/,
+    /Failed to resolve import\b/,
+];
+// Which of the two sentences the vibecoder reads. It changes wording only —
+// both outcomes stop the run, because in both cases every test would die before
+// asserting anything. That is why getting this wrong is cheap: the first draft
+// of this spec let the same distinction decide whether to stop at all, and
+// there a misclassification would have refused a healthy project.
+function causeOf(output, projectRoot, runner) {
+    if (DEPENDENCY_MISSING.some((pattern) => pattern.test(output)))
+        return 'environment_not_ready';
+    return hasProjectFrame(output, projectRoot, runner) ? 'defect_in_code' : 'environment_not_ready';
+}
+// Both halves are needed, and reasoning from Rails alone hides that. Ruby
+// resolves gems through `bundler/setup` before the first application file, so a
+// missing gem there reliably produces a trace with no project frame in it.
+// Python and JS have no such gate — the import is resolved from inside a project
+// file:
+//
+//   tests/test_foo.py:3: in <module>
+//       import requests
+//   E   ModuleNotFoundError: No module named 'requests'
+//
+// There is a project frame, and it is an un-run `pip install`. Hence the second
+// condition above.
+function hasProjectFrame(output, projectRoot, runner) {
+    // Line by line, because a stack frame names one file and the question is
+    // asked of that file. Judging the whole output at once let `.venv/lib/...`
+    // answer yes on the strength of its `lib/`, which is how a `TypeError` deep
+    // inside a dependency came back as a defect in the user's code.
+    const ownDirs = runner === 'vitest' ? ['src'] : ['app', 'lib'];
+    const conventional = new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`);
+    for (const line of output.split('\n')) {
+        // Wherever a dependency is installed, it is not this project's code — and
+        // that has to be decided before anything below gets a chance to say yes.
+        if (INSTALLED_DEPENDENCY.test(line))
+            continue;
+        // The conventional homes of business code, relative or absolute.
+        if (conventional.test(line))
+            return true;
+        if (line.includes(projectRoot))
+            return true;
+        // Python names no fixed layout the way Rails does, and pytest prints frames
+        // relative to the working directory — `mypackage/billing.py:12`, matching
+        // neither of the two rules above. So fall back to the only thing that
+        // generalises: the file in this frame is a file this repository has.
+        //
+        // Data-driven, so it needs no list of package names and holds for
+        // src-layout, flat-layout and anything else. Without it a genuine
+        // `NameError` in the user's own module was reported as "your environment is
+        // not ready", sending them to run `pip install` over a typo.
+        for (const [, candidate] of line.matchAll(SOURCE_FRAME)) {
+            if (existsSync(join(projectRoot, candidate)))
+                return true;
+        }
+    }
+    return false;
+}
+// Where a dependency lives once installed — never the project's own code, in
+// any of the three languages. The last two are the languages' own installed
+// libraries: `…/lib/ruby/3.3.0/psych.rb` is a frame the `lib/` rule below would
+// otherwise read as this project's business code.
+const INSTALLED_DEPENDENCY = /site-packages|dist-packages|node_modules|[/.]venv[/\\]|\/gems\/|[/\\]lib[/\\]ruby[/\\]|[/\\]lib[/\\]python\d/;
+// A `path/to/file.ext:LINE` frame, as every one of these runners prints them.
+const SOURCE_FRAME = /([\w.\-/\\]+\.(?:py|rb|ts|tsx|js|jsx|mjs|cjs)):\d+/g;
+// The runner's own words, never a paraphrase. A vibecoder can search for this
+// string; a summary of it they cannot. File and line come along when the runner
+// put them on the same line, and are not manufactured when it did not.
+//
+// Exported because spec 32-7 asks a second tool to load the application (the
+// router), and one rule for quoting a failed load is better than two.
+export function firstErrorLine(output) {
+    const lines = output.split('\n').map((line) => line.trim()).filter(Boolean);
+    const looksLikeError = /(^|[^A-Za-z])(error|exception|traceback)|:\d+:in |^E\s|\(.*Error\)/i;
+    return lines.find((line) => looksLikeError.test(line)) ?? lines[0] ?? 'the runner exited without output';
+}
+// The one repair this check performs. A test database is not a repository file
+// and is disposable by nature, which puts it under the same rule that already
+// lets `provision.ts` write its own Gemfile and venv: everything inside our own
+// sandbox, nothing of the project's touched.
+//
+// The project's own dependencies (`bundle install`, `npm install`,
+// `pip install`) stay off-limits for exactly that reason — they rewrite
+// `Gemfile.lock` and `package-lock.json`, which are the user's files. Those are
+// named to the human instead.
+//
+// Returns whether the repair ran, so the caller knows whether a retry is worth
+// anything.
+async function prepareTestDatabase(projectRoot, deps) {
+    if (!testDatabaseIsSeparate(projectRoot))
+        return false;
+    const rails = join(projectRoot, 'bin', 'rails');
+    const useBinstub = executable(rails);
+    const command = useBinstub ? rails : 'bundle';
+    const args = useBinstub ? ['db:test:prepare'] : ['exec', 'rails', 'db:test:prepare'];
+    const result = await attempt(deps, command, args, {
+        cwd: projectRoot,
+        env: { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return result !== null && result.code === 0;
+}
+// Refuse to prepare unless we can positively read two different database names.
+// Getting this wrong destroys a person's working data, which is not recoverable
+// by re-running anything, so every uncertainty resolves to "don't": no
+// database.yml, no `test:` block, a name we cannot read through ERB, or two
+// names that match — all of them stop the step.
+export function testDatabaseIsSeparate(projectRoot) {
+    const path = join(projectRoot, 'config', 'database.yml');
+    if (!existsSync(path))
+        return false;
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const test = databaseNameIn(text, 'test');
+    const development = databaseNameIn(text, 'development');
+    if (!test || !development)
+        return false;
+    return test !== development;
+}
+// The `database:` of one top-level environment block. Deliberately textual: the
+// connector carries no YAML parser, database.yml is routinely full of ERB, and
+// a name inherited through a `<<: *default` anchor is one we cannot resolve —
+// all of which come back as undefined and stop the step, which is the safe
+// direction to be wrong in.
+function databaseNameIn(text, environment) {
+    const lines = text.split('\n');
+    const start = lines.findIndex((line) => new RegExp(`^${environment}:\\s*(#.*)?$`).test(line));
+    if (start === -1)
+        return null;
+    for (const line of lines.slice(start + 1)) {
+        if (/^\S/.test(line))
+            break; // the next top-level block began
+        const match = /^\s+database:\s*(.+?)\s*$/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return null;
+}

package/dist/runner/manifest.js

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function selectRunnerEnvelope(candidates, runner) {
+    if (!runner || !Array.isArray(candidates))
+        return null;
+    const match = candidates.find((entry) => entry && typeof entry === 'object' && entry.runner === runner);
+    return match ? { ...match } : null;
+}
+// The behavioral envelope also carries the pinned dependency actually installed
+// into the isolated runner environment. Only the machine that provisioned the
+// sidecar can know it, so it is read back from that environment rather than
+// guessed.
+//
+// Unreadable means no envelope at all — never a partial one, and never an
+// invented version. The server requires this field on every behavioral upload,
+// so an envelope missing it is rejected at the last step, after the suite has
+// been written, run, and reviewed: precisely the failure this whole path exists
+// to remove. An envelope is either complete and copied verbatim, or absent and
+// the branch does not get built.
+export function withInstalledRunnerVersion(envelope, runner, projectRoot) {
+    const version = installedRunnerVersion(runner, projectRoot);
+    return version ? { ...envelope, runner_version: version } : null;
+}
+const BEHAVIORAL_DIR = '.unitbob/behavioral';
+// Matches the server's own PINNED_VERSION: a digit, then version characters.
+const PINNED_VERSION = /^[0-9][0-9A-Za-z.\-+]*$/;
+function installedRunnerVersion(runner, projectRoot) {
+    const root = join(projectRoot, BEHAVIORAL_DIR);
+    const found = readInstalledVersion(runner, root);
+    return found && PINNED_VERSION.test(found) ? found : null;
+}
+function readInstalledVersion(runner, root) {
+    switch (runner) {
+        case 'cucumber':
+            return gemfileLockVersion(join(root, 'Gemfile.lock'), 'cucumber');
+        case 'cucumber-js':
+            return packageJsonVersion(join(root, 'node_modules', '@cucumber', 'cucumber', 'package.json'));
+        case 'pytest-bdd':
+            return sitePackagesVersion(join(root, '.venv'), 'pytest_bdd');
+        default:
+            return null;
+    }
+}
+// `    cucumber (9.2.0)` under GEM/specs. The indented, parenthesised form is
+// the resolved version; the Gemfile's own `~> 9.0` constraint is not.
+function gemfileLockVersion(path, gem) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const match = readFileSync(path, 'utf8').match(new RegExp(`^\\s{4}${gem} \\(([^)]+)\\)$`, 'm'));
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function packageJsonVersion(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Installed distributions record their version in the `<name>-<version>.dist-info`
+// directory name, which needs no interpreter to read.
+function sitePackagesVersion(venv, distribution) {
+    try {
+        for (const lib of readdirSync(join(venv, 'lib'))) {
+            const packages = join(venv, 'lib', lib, 'site-packages');
+            if (!existsSync(packages))
+                continue;
+            for (const entry of readdirSync(packages)) {
+                const match = entry.match(new RegExp(`^${distribution}-(.+)\\.dist-info$`));
+                if (match)
+                    return match[1];
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}

package/dist/runner/precheck.js

@@ -5,11 +5,39 @@ const defaultDeps = {
     commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
 };
 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'];
+// 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;
+}
+// The BDD runner for a structural stack. One project, one language: the
+// behavioral peer follows the stack already detected instead of probing the
+// filesystem a second time.
+//
+// A second probe used to answer first on `package.json` alone, so a Rails app
+// with any front-end build — the common case — got an rspec structural branch
+// and a cucumber-js behavioral one. Step definitions in JavaScript cannot boot
+// Rails, use its test helpers, or reach its test database, so that branch was
+// dead before it was written, and the generation recipe allows exactly one stack
+// per project anyway.
+const BDD_RUNNER_FOR_STACK = {
+    rspec: 'cucumber',
+    vitest: 'cucumber-js',
+    pytest: 'pytest-bdd',
+};
+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.
 export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
-    const supported = ['rspec', 'vitest', 'pytest'].some((runner) => validateStack(projectRoot, runner, deps).ok);
-    if (supported)
-        return { ok: true };
+    const runner = detectStructuralRunner(projectRoot, deps);
+    if (runner !== null)
+        return { ok: true, runner };
     return {
         ok: false,
         message: `Unitbob guardrails support ${STACKS} only. This project matches none of those stacks.`,

package/dist/runner/provision.js

@@ -1,8 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.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;
 const defaultDeps = {
-    runCmd: (command, args, options) => runProcess(command, args, { cwd: options.cwd, timeoutMs: 120_000, env: { ...process.env, ...options.env } }),
+    runCmd: (command, args, options) => runProcess(command, args, { cwd: options.cwd, timeoutMs: PROVISION_TIMEOUT_MS, env: { ...process.env, ...options.env } }),
 };
 export async function ensureRunner(projectRoot, runner, deps = defaultDeps) {
     const behavioralDir = join(projectRoot, '.unitbob', 'behavioral');

package/dist/runner/rspec.js

@@ -1,6 +1,5 @@
-import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { runProcess } from "../proc.js";
+import { executable, runProcess } from "../proc.js";
 import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
 import { readReport } from "./types.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
@@ -54,11 +53,3 @@ async function invokeRspec(projectRoot, rspecArgs) {
     });
     return { result, command, args };
 }
-function executable(path) {
-    try {
-        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
-    }
-    catch {
-        return false;
-    }
-}