unitbob 0.4.5 → 0.5.1

package/dist/files/guardrails.js

@@ -62,21 +62,31 @@ else
 end
 abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
 `;
-// Write the suite blob's guardrail file at its own (validated) relative path.
-// The Ruby boot kit is materialized only for the rspec runner — Vitest and
-// pytest runs need no connector-written support files here (the runtime
-// pytest.ini lives outside this directory and is written by the pytest runner).
+// Write every file of the suite blob at its own (validated) relative path. The
+// Ruby boot kit is materialized only for the rspec runner — Vitest and pytest
+// runs need no connector-written support files here (the runtime pytest.ini
+// lives outside this directory and is written by the pytest runner).
+//
+// Every file, not just the main one (spec 42, §6.4). The directory is wiped
+// first and only the main file was written back, so a published suite of four
+// files came back as one and the run that followed it silently protected a
+// quarter of what the map claimed.
 export function materializeGuardrails(projectRoot, suite) {
-    assertGuardrailPath(suite.suite_file.path);
+    const files = [suite.suite_file, ...(suite.suite_file.support_files ?? [])];
+    for (const file of files)
+        assertGuardrailPath(file.path);
     const dir = join(projectRoot, GUARDRAILS_DIR);
     rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir, { recursive: true });
-    const suitePath = join(projectRoot, suite.suite_file.path);
-    mkdirSync(dirname(suitePath), { recursive: true });
-    writeFileSync(suitePath, suite.suite_file.content);
+    const written = files.map((file) => {
+        const path = join(projectRoot, file.path);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, file.content);
+        return path;
+    });
     if (suite.runner_manifest.runner === 'rspec')
         materializeHelper(projectRoot);
-    return { suitePath };
+    return { suitePath: written[0], supportPaths: written.slice(1) };
 }
 // Both Ruby flows boot the same way: the check flow writes the boot kit next to
 // the suite here, the suite-build flow writes it right after the precheck.

package/dist/files/suiteBuild.js

@@ -82,12 +82,27 @@ export function branchRunner(output) {
     }
     return runner;
 }
+// What the reviewer actually read: the suite files, and the manifest that runs
+// them. Nothing else (spec 42, §4).
+//
+// `test_metadata` used to be in here, and the server's copy of this formula
+// stripped the review's own keys back out to match — two lists that had to stay
+// identical for ever or every upload would break. The real cost was elsewhere,
+// though: editing metadata declared the review stale. On noahsat-web,
+// 2026-08-12 the reviewer was right that the steps drive only `PATCH`, the fix
+// moved three `PUT` aliases into a deferred list, not one byte of the suite
+// moved — and the run still paid for re-binding the candidate and a second
+// reviewer pass, the most expensive step of the whole recipe, to satisfy the
+// reviewer's own finding.
+//
+// `stableJson` sorts object keys and does nothing else. The server's
+// `canonical_json` does the same, which is the only reason the two sides agree;
+// a normalization added on one side alone would break every upload.
 export function suiteCandidateDigest(output) {
     return createHash('sha256')
         .update(stableJson({
         suite_file: output.suite_file,
         runner_manifest: output.runner_manifest,
-        test_metadata: output.test_metadata,
     }))
         .digest('hex');
 }

package/dist/files/suiteBuildUpload.js

@@ -0,0 +1,71 @@
+import { readBehavioralReview } from "./suiteBuild.js";
+// What travels to the server, and what "published" means when it answers. One
+// module, because two commands ask those questions: `put-suite-build` sends the
+// batch, and `validate-build` sends the same batch as a dry run so the server's
+// verdict is about the exact bytes the publish will carry (spec 42, §3).
+//
+// A second assembly would be a second answer to "what are we uploading", and the
+// dry run would then be checking something the publish does not send — which is
+// worth less than not checking at all, because it reads as a verdict.
+// The three outcomes that leave a branch published and current: a new version, an
+// identical version already stored, or a reactivated one. Each returns the
+// identity to run. Everything else — a rejected branch, a branch the host could
+// not build, or a status this connector has never seen — fails closed and is
+// never run, so a newer server can never trick an older connector into running
+// something it does not understand.
+export const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
+// The answer a dry run gives to a branch it would accept. A server that does not
+// know `dry_run` answers one of `PUBLISHED` instead — which means it published —
+// and `validate-build` says so rather than reporting a check that passed.
+export const WOULD_PUBLISH = 'would_publish';
+// One branch, as the upload sends it. `source_digest` comes from the request,
+// never from the host's answer, so the host cannot claim a different map than
+// the branch was given.
+export function uploadItem(request, output, testMetadata) {
+    const sourceDigest = request.branches.find((branch) => branch.suite_kind === output.suite_kind)?.source_digest ?? '';
+    if (output.build_error) {
+        return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+    }
+    return {
+        suite_kind: output.suite_kind,
+        source_digest: sourceDigest,
+        artifacts: {
+            suite_file: output.suite_file,
+            runner_manifest: output.runner_manifest,
+            test_metadata: testMetadata,
+        },
+    };
+}
+// The behavioral branch's uploaded metadata, with the independent review and the
+// connector's own run evidence folded in.
+//
+// Throws for anything that leaves this branch unpublishable — a missing review,
+// one bound to a different candidate, a defect the review called not_supplied.
+// The caller turns that into one unpublished branch rather than a failed
+// command: a blocked review is a fact about the behavioral suite, and the
+// structural peer next to it is finished and correct. Sinking the whole upload
+// with it forced the one workaround this contract exists to prevent — hand-editing
+// the answer down to a single branch, which loses the peer candidate for real.
+export function withReview(config, request, output) {
+    const review = readBehavioralReview(config.projectRoot, output);
+    const probe = review.known_defect_probe;
+    const qualityReview = review.bdd_quality_review;
+    if (!qualityReview || typeof qualityReview !== 'object') {
+        throw new Error('The separate behavioral review must contain a bdd_quality_review object.');
+    }
+    if (request.known_defect_context.status === 'supplied' && probe?.status === 'not_supplied') {
+        throw new Error('A known defect was supplied to suite-prepare, but the behavioral review marked it not_supplied.');
+    }
+    return {
+        ...output.test_metadata,
+        bdd_quality_review: {
+            ...qualityReview,
+            candidate_digest: review.candidate_digest,
+        },
+        ...(review.selection_review ? { selection_review: review.selection_review } : {}),
+        known_defect_probe: review.known_defect_probe,
+        known_defect_context: request.known_defect_context,
+        candidate_run: review.candidate_run,
+        ...(review.fixed_candidate_run ? { fixed_candidate_run: review.fixed_candidate_run } : {}),
+    };
+}

package/dist/files/workerPlan.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { detectStructuralRunner } from "../runner/precheck.js";
 import { assertUnitbobPath } from "./artifactPath.js";
 export function workerPlanPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'worker-plan.json');
@@ -33,8 +34,13 @@ export function readWorkerPlan(projectRoot) {
     }
     return parsed;
 }
+const RUBY_HARNESS = {
+    behavioral: '.unitbob/behavioral/step_definitions/00_unitbob_world.rb',
+    structural: '.unitbob/structural/unitbob_helper.rb',
+};
 export function validateWorkerPlanFiles(projectRoot) {
     const errors = [];
+    const rubyProject = detectStructuralRunner(projectRoot) === 'rspec';
     const plan = readWorkerPlan(projectRoot);
     let request;
     try {
@@ -86,12 +92,23 @@ export function validateWorkerPlanFiles(projectRoot) {
             errors.push(`${label}: done_when must be non-empty`);
         if (!isNonEmptyString(item?.harness_path))
             errors.push(`${label}: harness_path must be non-empty`);
-        const expectedHarness = item?.branch === 'behavioral'
-            ? '.unitbob/behavioral/step_definitions/00_unitbob_world.rb'
-            : item?.branch === 'structural' ? '.unitbob/structural/unitbob_helper.rb' : null;
+        // Both connector-owned harness files are Ruby, and only a Ruby project has
+        // them: `unitbob_helper.rb` boots Rails for RSpec, and the behavioral World
+        // is materialized for cucumber alone. Demanding them everywhere refused
+        // every Python and JS plan over a file that does not exist and would mean
+        // nothing if it did — the same mistake as the stack gate that reported a
+        // Python project as no stack at all. Found 2026-08-12.
+        //
+        // What is required of the other stacks is what the rule was ever about: the
+        // harness is connector territory, under `.unitbob/`, not a file in the
+        // project.
+        const expectedHarness = rubyProject ? RUBY_HARNESS[item?.branch] ?? null : null;
         if (expectedHarness && item.harness_path !== expectedHarness) {
             errors.push(`${label}: harness_path must name the connector-owned ${expectedHarness}`);
         }
+        if (!expectedHarness && isNonEmptyString(item?.harness_path) && !item.harness_path.startsWith('.unitbob/')) {
+            errors.push(`${label}: harness_path must be a connector-owned path under .unitbob/ (got "${item.harness_path}")`);
+        }
         if (!item?.limits || item.limits.planned_cases !== item.planned_cases?.length) {
             errors.push(`${label}: limits.planned_cases must equal planned_cases.length`);
         }

package/dist/runner/bdd.js

@@ -22,33 +22,96 @@ export const BDD_RUN_ARTIFACTS = [
     PYTEST_BDD_PLUGIN_NAME,
     PYTEST_INI_NAME,
 ];
+// One name for the directory every strategy points its loader at, so the
+// descriptors below and the commands below them cannot come to mean different
+// directories.
+const STEP_DEFINITIONS = 'step_definitions';
 const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, CUCUMBER_REPORT_NAME);
 const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, PYTEST_BDD_REPORT_NAME);
 const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, PYTEST_BDD_PLUGIN_NAME);
 const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, PYTEST_INI_NAME);
 const PYTEST_INI = '[pytest]\naddopts =\n';
+// Load order is a fact about both Cucumbers and about neither pytest — pytest
+// picks `conftest.py` up itself, so there is no trap to work around there.
+const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file is not special to the runner — `account_access` ' +
+    'loads before `shared`. Open each capability file with an explicit require of the shared one rather ' +
+    'than trusting the alphabet.';
 // The connector-owned BDD strategy table (spec 32): the `runner` enum names one
 // of these; the connector never executes a host-provided command string. Each
 // strategy runs the whole behavioral bundle and returns the raw machine-readable
 // report verbatim — the connector does no marker join and no aggregation.
+//
+// A strategy is its command *and* its loading rule. They are one entry so that a
+// fourth runner cannot be added with only half of itself stated.
+const BDD_STRATEGIES = {
+    cucumber: {
+        run: (projectRoot) => runCucumberRuby(projectRoot),
+        loading: {
+            step_files: '*.rb',
+            requirements: [
+                'The connector points `--require` at `step_definitions/`, so every `.rb` file there is loaded. ' +
+                    'That explicit `--require` also switches off Cucumber\'s automatic loading of `features/support/`: ' +
+                    'a World or helper parked there is never evaluated, and every step then fails on a bare object.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'cucumber-js': {
+        run: (projectRoot) => runCucumberJs(projectRoot),
+        loading: {
+            step_files: '*.js',
+            requirements: [
+                'Keep `step_definitions/` to CommonJS JavaScript and nothing else. The connector passes the whole ' +
+                    'directory to `--require`, and cucumber-js `require()`s every file it matches whatever the ' +
+                    'extension — a stray `.ts`, `.json` or `.md` left there is executed as JavaScript and aborts the ' +
+                    'entire run with a parse error, before a single scenario.',
+                'The connector registers no TypeScript loader, so a `.ts` file cannot compile itself. If you want ' +
+                    'one, register the compiler from the file that sorts first — and remember the file registering it ' +
+                    'is itself loaded as plain JavaScript.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'pytest-bdd': {
+        run: (projectRoot, mainPath) => runPytestBdd(projectRoot, mainPath),
+        loading: {
+            step_files: 'test_*.py',
+            requirements: [
+                'pytest collects `step_definitions/` under its own default, which is `test_*.py` and `*_test.py`. ' +
+                    'The connector writes no `python_files` setting and will not: a file named outside those two — ' +
+                    '`<capability>_steps.py`, say — is simply not collected. No error, no scenarios, a green run ' +
+                    'over nothing.',
+                '`conftest.py` is picked up by pytest itself whatever else sits beside it, so shared fixtures ' +
+                    'belong there and there is no load-order trap to work around.',
+            ],
+        },
+    },
+};
 export function runBddSuite(projectRoot, runner, mainPath) {
-    switch (runner) {
-        case 'cucumber':
-            return runCucumberRuby(projectRoot);
-        case 'cucumber-js':
-            return runCucumberJs(projectRoot);
-        case 'pytest-bdd':
-            return runPytestBdd(projectRoot, mainPath);
-        default:
-            return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
+    const strategy = strategyFor(runner);
+    if (!strategy) {
+        return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
     }
+    return strategy.run(projectRoot, mainPath);
+}
+// How this runner loads step files, for whoever has to write one. Null for a
+// runner this connector does not run, which is the same answer `runBddSuite`
+// gives it.
+export function bddStepLoading(runner) {
+    return strategyFor(runner)?.loading ?? null;
+}
+// `Object.hasOwn` rather than a bare index: the runner name arrives over the
+// wire, and `constructor` would otherwise come back as a truthy strategy with no
+// `run` on it.
+function strategyFor(runner) {
+    return Object.hasOwn(BDD_STRATEGIES, runner) ? BDD_STRATEGIES[runner] : null;
 }
 // Ruby: `cucumber` with the built-in message formatter. The features and step
 // definitions both live under the behavioral root; --require points at the step
 // definitions so only the Unitbob bundle loads.
 async function runCucumberRuby(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
     if (!existsSync(sidecarGemfile)) {
         throw missingRunner('Cucumber');
@@ -75,7 +138,7 @@ function missingRunner(name) {
 // to a file.
 async function runCucumberJs(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions', '**', '*');
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
     const sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
     if (!executable(sidecarBin)) {
         throw missingRunner('Cucumber JS');
@@ -103,7 +166,7 @@ async function runPytestBdd(projectRoot, mainPath) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
     writeFileSync(join(projectRoot, PYTEST_BDD_PLUGIN_FILE), PYTEST_BDD_PLUGIN);
     const command = await pickPython(projectRoot);
-    const stepsDir = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const stepsDir = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const isVenvPytest = command.endsWith('/pytest');
     const args = isVenvPytest
         ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot]

package/dist/runner/bootcheck.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable, runProcess } from "../proc.js";
+import { locateRunner } from "./toolchain.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";
@@ -86,9 +87,14 @@ async function loadRubyHelper(projectRoot, helper, deps) {
     // and the global `bundle` was standing right there the whole time.
     const localBundle = join(projectRoot, 'bin', 'bundle');
     const command = executable(localBundle) ? localBundle : 'bundle';
+    // When Unitbob installed rspec-rails for itself, the gems this helper needs
+    // are resolved by the sidecar Gemfile, not the project's. Asking bundler
+    // without that variable would load a different set of gems than the run does,
+    // which is exactly the way a check ends up predicting the wrong thing.
+    const located = locateRunner(projectRoot, 'rspec');
     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 },
+        env: { ...located?.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.
@@ -110,10 +116,25 @@ async function pytestBootCheck(projectRoot, deps) {
     // 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,
-        });
+    // The same pytest the run will use, resolved once in `locateRunner` — the
+    // sidecar under `.unitbob/` when Unitbob installed one, else the machine's own
+    // interpreter. Asking a different interpreter than the run uses is how a check
+    // ends up answering about something nobody is going to execute.
+    //
+    // When it resolves nothing we still try the two interpreters by name rather
+    // than reporting `no_runner` from a lookup. The lookup is a prediction; the
+    // spawn is the fact, and a check that stops at its own prediction can be
+    // wrong in the one direction that costs the most — refusing a project that
+    // would have answered perfectly well.
+    const located = locateRunner(projectRoot, 'pytest');
+    const candidates = located
+        ? [located]
+        : [
+            { command: 'python3', args: ['-m', 'pytest'], env: undefined },
+            { command: 'python', args: ['-m', 'pytest'], env: undefined },
+        ];
+    for (const candidate of candidates) {
+        const result = await attempt(deps, candidate.command, [...candidate.args, '-c', PYTEST_INI_FILE, '--collect-only', '-q'], { cwd: projectRoot, env: candidate.env });
         if (result === null)
             continue; // this interpreter is not on the machine
         return classify(projectRoot, 'pytest', result, (proc) => pytestVerdict(proc.code));
@@ -148,7 +169,10 @@ function pytestVerdict(code) {
 // 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');
+    // A sidecar vitest counts as installed: it is ours, it is on disk, and it is
+    // the one the run will spawn. What stays out is `npx`, for the reason below.
+    const local = locateRunner(projectRoot, 'vitest')?.command
+        ?? 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.
@@ -275,15 +299,17 @@ function hasProjectFrame(output, projectRoot, runner) {
     // 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('|')})/`);
+    const ownDirs = CONVENTIONAL_SOURCE_DIRS[runner] ?? [];
+    const conventional = ownDirs.length
+        ? new RegExp(`(^|[\\s"'(\\[/])(${ownDirs.join('|')})/`)
+        : null;
     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))
+        if (conventional?.test(line))
             return true;
         if (line.includes(projectRoot))
             return true;
@@ -303,6 +329,18 @@ function hasProjectFrame(output, projectRoot, runner) {
     }
     return false;
 }
+// Where each stack conventionally keeps its business code. Only a stack that
+// really has such a convention gets an entry: `app/` and `lib/` are Rails, and
+// they used to be the fallback for everything that was not vitest, which meant a
+// Python project got Rails's layout applied to its stack traces. Python names no
+// fixed layout at all, so it is deliberately absent — the repository-file test
+// below is the answer there, and it is the more reliable one anyway.
+const CONVENTIONAL_SOURCE_DIRS = {
+    rspec: ['app', 'lib'],
+    cucumber: ['app', 'lib'],
+    vitest: ['src'],
+    'cucumber-js': ['src'],
+};
 // 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