unitbob 0.5.0 → 0.6.0

package/dist/verbs/runLocal.js

@@ -1,5 +1,8 @@
 import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { digestOf, failureSet, readRunState, rememberFailures } from "../runner/failureDigest.js";
+import { placeProblem } from "../runner/place.js";
+import { placeAdvice } from "../runner/placeAdvice.js";
+import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { runStructuralByRunner } from "./run.js";
@@ -12,6 +15,13 @@ export async function runLocal(config, args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
+    // Spec 36, criteria 7 and 6. A run that cannot reach the place its
+    // dependencies live in has nothing to report but noise — and neither has one
+    // whose runner was installed somewhere else, which looks ready because
+    // readiness here is a file existing.
+    const unusable = placeProblem(config.projectRoot) ?? runnerEnvironmentPlaceProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
     const request = readSuiteBuildRequest(config.projectRoot);
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const wanted = selectBranches(request, args);
@@ -124,7 +134,12 @@ async function runOneBranch(config, d, suiteKind, output) {
                 : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
-        d.stdout.write(`The runner could not start: ${err.message}\n`);
+        // The second and last dead end (spec 36, §7.1). This one does not throw —
+        // it prints and returns zero, so it never reaches the one `catch` that adds
+        // this advice everywhere else. And it is the case that matters most: the
+        // suite exists by now, and the person is trying to run it.
+        const advice = placeAdvice(config.projectRoot);
+        d.stdout.write(`The runner could not start: ${err.message}\n${advice ? `\n${advice}\n` : ''}`);
         return null;
     }
     d.stdout.write(report(result));
@@ -163,7 +178,7 @@ function outputTail(result) {
 }
 // The suite blob's own project-relative paths, exactly as the runners expect
 // them: the main file first, then every other file of the branch. The main file
-// stopped being the whole suite in spec 42, §6 — a branch is one file per
+// stopped being the whole suite in spec 43, §6 — a branch is one file per
 // assignment now — and running it alone would exercise a fraction of what the
 // answer claims to guard.
 //

package/dist/verbs/suitePrepare.js

@@ -2,10 +2,14 @@ import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { bddStepLoading } from "../runner/bdd.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
-import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
+import { anyStackPrecheck, behavioralHarnessNotice, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck, } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
+import { placeProblem } from "../runner/place.js";
+import { alignRunnerEnvironmentWithPlace } from "../runner/placeEnvironment.js";
 import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
+import { ToolchainUnavailableError } from "../runner/toolchain.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -70,9 +74,30 @@ export async function suitePrepare(config, args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
+    // Spec 36, criterion 7. Before the first byte is written and long before the
+    // first call to the server: a place that cannot be used is a fact we can learn
+    // now, and learning it after a suite has been generated and run means the
+    // evidence disappeared with the container.
+    //
+    // Not a `ToolchainUnavailableError`: the place is named in the config and the
+    // message below already says what to do about it. Suggesting a container to
+    // somebody whose container is the problem is noise.
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(`${unusable}\nNothing was written and nothing was uploaded.`);
     const check = actual.precheck(config.projectRoot);
+    // Deliberately a plain stop. This one says "none of the three stacks is here",
+    // which is read off files — a Gemfile, a package.json, a requirements.txt —
+    // and those are on this machine whatever place the run happens in. A container
+    // is never the answer to it.
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
+    // An environment installed somewhere else is not an environment (spec 36, §6).
+    // Here, where it can be built again, and before anything asks whether a runner
+    // is ready.
+    const replaced = alignRunnerEnvironmentWithPlace(config.projectRoot);
+    if (replaced)
+        actual.stdout.write(`${replaced}\n`);
     // Ruby only. This wrote `unitbob_helper.rb` and `rspec.opts` into every
     // project it touched, so a Flask app and a NestJS app each came away with a
     // Ruby file they never asked for and cannot run — the product leaving another
@@ -92,16 +117,17 @@ export async function suitePrepare(config, args = [], deps) {
         const provisioned = await actual.ensureStructuralRunner(config.projectRoot, check.runner);
         if (provisioned.status === 'fixable') {
             const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
-            throw new Error(`The ${check.runner} runner could not be installed under .unitbob/, and nothing can run without it: ` +
-                `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written and nothing was uploaded.`);
+            throw new ToolchainUnavailableError(`The ${check.runner} runner could not be installed under .unitbob/, and nothing can run without it: ` +
+                `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written and nothing was uploaded.`, config.projectRoot);
         }
         setupNotices.push(...(provisioned.checklist ?? []));
         // Confirm rather than assume. Provisioning reporting success and the runner
         // actually being startable are two different facts, and this is the cheap
         // one to check before a whole generation is built on it.
         const ready = actual.confirmRunner(config.projectRoot, check.runner);
-        if (!ready.ok)
-            throw new Error(ready.message ?? `The ${check.runner} runner is not available.`);
+        if (!ready.ok) {
+            throw new ToolchainUnavailableError(ready.message ?? `The ${check.runner} runner is not available.`, config.projectRoot);
+        }
     }
     // Spec 32-6. Before anything is fetched or written, find out whether the suite
     // would get off the ground at all. It runs here, after the boot helper exists
@@ -117,8 +143,15 @@ export async function suitePrepare(config, args = [], deps) {
     // the same thing: on Python that would shell out to pytest all over again.
     const structuralRunner = check.runner ?? null;
     const boot = await actual.bootCheck(config.projectRoot, structuralRunner);
-    if (boot.status === 'broken')
-        throw new Error(bootFinding(boot, structuralRunner));
+    if (boot.status === 'broken') {
+        // "Your environment is not ready" is the one of the two that a container can
+        // answer — the toolchain is missing here and may be sitting in one. A defect
+        // found in the code is a defect wherever it runs, and offering a container
+        // for it would be the noise this spec is trying to remove.
+        throw boot.cause === 'environment_not_ready'
+            ? new ToolchainUnavailableError(bootFinding(boot, structuralRunner), config.projectRoot)
+            : new Error(bootFinding(boot, structuralRunner));
+    }
     actual.stdout.write(bootFinding(boot, structuralRunner));
     const packets = await actual.getSuitePacketsBatch();
     // Spec 32-1: Zero-touch sidecar provision for behavioral BDD runners during build preflight.
@@ -139,8 +172,14 @@ export async function suitePrepare(config, args = [], deps) {
                 fixableNotices.push(`  Behavioral runner "${runner}" not installed: ${prov.message ?? ''}${steps}`);
                 continue;
             }
+            // Every BDD runner with a connector-owned harness gets it here, before its
+            // branch is offered to the host (spec 35-1). Only Ruby is probed by
+            // running it: the Ruby World integrates deeply with Rails, and the probe
+            // needs an application to integrate with. The JS and Python harnesses do
+            // one thing — refuse connections that leave the machine — and their
+            // guards are executed for real in the connector's own suite.
+            materializeBehavioralWorld(config.projectRoot, runner);
             if (runner === 'cucumber') {
-                materializeBehavioralWorld(config.projectRoot);
                 const probe = await actual.worldProbe(config.projectRoot);
                 if (probe.status === 'fixable') {
                     fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
@@ -156,6 +195,11 @@ export async function suitePrepare(config, args = [], deps) {
         const manifest = actual.runnerEnvelope(packet, runner, config.projectRoot);
         if (!manifest)
             return { packet, runner, branch: null };
+        // Spec 44, §3.2. The rule for which step files this runner loads travels
+        // with the branch that will be written against it, so nobody has to read
+        // the connector's own source to find it out — which is exactly what two
+        // coordinators did.
+        const stepLoading = packet.suite_kind === 'behavioral' && runner ? bddStepLoading(runner) : null;
         return {
             packet,
             runner,
@@ -166,6 +210,7 @@ export async function suitePrepare(config, args = [], deps) {
                 recipe: await actual.getRecipe(recipeNameFor(packet)),
                 assignment: packet.assignment,
                 runner_manifest: manifest,
+                ...(stepLoading ? { step_loading: stepLoading } : {}),
             },
         };
     }));
@@ -200,6 +245,28 @@ export async function suitePrepare(config, args = [], deps) {
         `finish says so in its own entry rather than being left out of the array. Run each locally with \`unitbob run-local\` (the same ` +
         `runner that runs after publishing, so you never have to guess the command), repair broken harness steps while application failures remain red, ` +
         `then run ${nextCommand}.\n`);
+    // Printed as well as written, because a rule nobody reads is a rule nobody
+    // follows — and this one is silent when broken: a step file the runner does
+    // not collect produces no error, only a green run over no scenarios.
+    for (const { packet, runner, branch } of prepared) {
+        if (!branch || packet.suite_kind !== 'behavioral' || !runner)
+            continue;
+        // Before the steps are written, not after they misbehave: what this runner
+        // does and does not load is the fact a worker needs while deciding what a
+        // step may assume (spec 35-1, criterion 2).
+        const harness = behavioralHarnessNotice(runner);
+        if (harness)
+            actual.stdout.write(harness);
+        actual.stdout.write(branch.step_loading
+            ? stepLoadingNotice(runner, branch.step_loading)
+            // Said rather than left blank. This connector has no strategy for that
+            // runner, so it does not know which files it loads — and silence here
+            // reads as "any name will do", which is the failure this whole notice
+            // exists to prevent.
+            : `\nBehavioral steps run under "${runner}", and this connector does not know how that runner ` +
+                'finds its step files — it has no strategy of that name. Nothing here tells you what to call ' +
+                'them, and this connector will not be able to run the branch either.\n');
+    }
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.
     if (setupNotices.length > 0) {
@@ -221,6 +288,24 @@ export async function suitePrepare(config, args = [], deps) {
             '\n');
     }
 }
+// The runner's own rule for which step files it will load, in the words of the
+// side that loads them (spec 44, §3.2). The same object is in `request.json`, on
+// the behavioral branch; this is the copy the coordinator sees without opening a
+// file.
+//
+// A null pattern is printed as a null pattern. A runner whose rule is not one
+// pattern says what it does know and admits the rest — inventing a pattern here
+// would recreate, in the connector this time, exactly the retelling this
+// replaced.
+function stepLoadingNotice(runner, loading) {
+    const rule = loading.step_files
+        ? `it loads \`${loading.step_files}\` from \`.unitbob/behavioral/step_definitions/\` — put the capability id ` +
+            'where the `*` is, and a file named anything else is not loaded at all'
+        : 'its rule for which files it loads is not one pattern, and this connector will not state one for it';
+    return (`\nBehavioral steps run under "${runner}", and ${rule}. What else has to be true of a step file there:\n  - ` +
+        loading.requirements.join('\n  - ') +
+        '\nThis is also in `request.json`, on the behavioral branch, as `step_loading`.\n');
+}
 // What the boot check found, in the vibecoder's terms. Printed on every run,
 // including the quiet ones: "we looked and it starts" and "we could not look"
 // are both worth a line, and a check nobody hears about is a check nobody
@@ -250,7 +335,8 @@ function bootFinding(boot, runner) {
         // Not checked is not broken, and nothing downstream may treat it as such.
         // Conflating the two would block honest projects — the whole reason this
         // state is named for what happened rather than for what we know.
-        return `${NOT_CHECKED_REASON[boot.reason]} Generation continues.${caveat}\n`;
+        const said = boot.detail ? `\n\n  ${boot.detail}\n` : '';
+        return `${NOT_CHECKED_REASON[boot.reason]}${said} Generation continues.${caveat}\n`;
     }
     const headline = boot.cause === 'defect_in_code'
         ? 'Found a defect that stops your test suite from starting.'
@@ -307,6 +393,12 @@ const NOT_CHECKED_REASON = {
         'stopped on an error of its own before loading anything. Nothing was learned about your code either way.',
     timed_out: 'Did not check whether the suite can start: loading it took too long and was stopped.',
     nothing_to_load: 'Did not check whether the suite can start: there was nothing to load yet.',
+    // Spec 36, criterion 8. Docker refused, or the container went away between the
+    // check and the spawn. Nothing here says anything about the project, and the
+    // one thing this must never turn into is "we found a defect in your code".
+    place_failed: 'Did not check whether the suite can start: the place this project runs in did not carry the command ' +
+        'out. That is a fault of the container or the docker daemon, not of your code, and nothing was learned ' +
+        'about your code either way.',
 };
 function knownDefectContext(args) {
     const defect = option(args, '--known-defect=');

package/dist/verbs/suiteReviewPrepare.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBehavioral, } from "../files/behavioral.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
+import { placeOf } from "../runner/place.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
@@ -54,6 +55,19 @@ async function runCandidateInProject(projectRoot, output, revision) {
     return { revision, run_result: report };
 }
 async function runCandidateAtRevision(projectRoot, output, revision) {
+    // Spec 36, Non-Goals. The worktree below is created under the system's
+    // temporary directory — outside anything a container has mounted, so in there
+    // it does not exist at all. Said plainly rather than run into. The obvious
+    // repair, moving the worktree under `.unitbob/`, puts a whole second copy of
+    // the application inside the tree graphify scans, and a copy left behind by a
+    // failure builds the next map out of two applications.
+    const place = placeOf(projectRoot);
+    if (place.kind === 'docker') {
+        throw new Error("Reviewing at a fixed revision is not supported while this project's tests run inside a container " +
+            `(\`${place.container}\`): the review needs a git worktree outside the project, which the container ` +
+            'cannot see. Review against the working tree instead (drop the fixed revision), or run this project ' +
+            'on this machine.');
+    }
     const resolved = execFileSync('git', ['rev-parse', '--verify', revision], {
         cwd: projectRoot,
         encoding: 'utf8',

package/dist/wire.js

@@ -86,7 +86,7 @@ export class Wire {
     // carries one result per suite_kind.
     //
     // `dryRun` is the same route, the same body and the same server-side
-    // validation, stopped before the first write (spec 42, §1). It answers
+    // validation, stopped before the first write (spec 43, §1). It answers
     // `would_publish` instead of `created`, and it is deliberately not a route of
     // its own: a second route would grow a second implementation, which is the
     // defect this whole spec removes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {

package/plugin/codex/agents/suite-repair-worker.toml

@@ -21,7 +21,7 @@ markers, or paths. Do not edit production code, host-owned shared files, the
 connector-owned harness, or another slice.
 
 After every owned edit, run
-`npx -y --loglevel=error unitbob@0.5.0 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.6.0 run-local <branch>` and inspect the machine
 report. Look only at examples or scenarios matching your owned paths or case
 markers. Do not require a green exit code from the whole branch: foreign failures
 and an already-confirmed product red do not widen your scope. Repeat the bounded