unitbob 0.4.5 → 0.5.1

package/dist/verbs/putSuiteBuild.js

@@ -1,5 +1,6 @@
-import { readBehavioralReview, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { collectBuildProblems, formatBranchProblems } from "./validateBuild.js";
+import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { collectBuildProblems } from "./validateBuild.js";
+import { PUBLISHED, uploadItem, withReview } from "../files/suiteBuildUpload.js";
 import { Wire } from "../wire.js";
 // Read the task and the host's answers, verify each branch parses and carries a
 // safe-path artifact envelope, then upload both peer branches in one batch
@@ -28,7 +29,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
         stdout: process.stdout,
         ...deps,
     };
-    const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
     const items = [];
     const blocked = unreadable.map((entry) => ({
         suite_kind: entry.suite_kind,
@@ -39,26 +39,19 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
+    // Since spec 42 that check is exactly one question, and it is about a branch
+    // the answer has *no* entry for: everything else it used to ask is now asked
+    // of the server, by a dry run, before this command runs at all. So its
+    // problems can never land on a branch this loop visits, and they are reported
+    // below rather than inside it.
+    //
     // An earlier draft threw and stopped the command, which quietly undid spec
-    // 32-5 Phase 4: one missing marker in the behavioral answer would have left a
-    // finished structural suite unpublished. Every problem this check raises is
-    // already named against a branch, so it blocks that branch and never the
-    // batch. That also bounds what a false positive in a local check can cost —
-    // one branch, with the peer still going up and the server still the authority.
-    const problemsFor = new Map();
-    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
-        problemsFor.set(problem.branch, [...(problemsFor.get(problem.branch) ?? []), problem.message]);
-    }
+    // 32-5 Phase 4: one behavioral problem would have left a finished structural
+    // suite unpublished. Every problem here is named against a branch, so it
+    // blocks that branch and never the batch.
     for (const output of outputs) {
-        const failed = problemsFor.get(output.suite_kind);
-        problemsFor.delete(output.suite_kind);
-        if (failed) {
-            blocked.push({ suite_kind: output.suite_kind, status: BLOCKED_STATUS, error: formatBranchProblems(failed) });
-            continue;
-        }
-        const sourceDigest = digestFor.get(output.suite_kind) ?? '';
         if (output.build_error) {
-            items.push({ suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error });
+            items.push(uploadItem(request, output, undefined));
             continue;
         }
         let testMetadata = output.test_metadata;
@@ -71,23 +64,14 @@ export async function putSuiteBuild(config, _args = [], deps) {
                 continue;
             }
         }
-        items.push({
-            suite_kind: output.suite_kind,
-            source_digest: sourceDigest,
-            artifacts: {
-                suite_file: output.suite_file,
-                runner_manifest: output.runner_manifest,
-                test_metadata: testMetadata,
-            },
-        });
+        items.push(uploadItem(request, output, testMetadata));
     }
-    // What is left in `problemsFor` belongs to a branch the loop above never
-    // reached, because the answer has no entry for it at all. It has nothing to
-    // upload and nothing to roll back, so it costs its peer nothing — but it is
+    // A branch the request asked for and the answer never mentions. It has nothing
+    // to upload and nothing to roll back, so it costs its peer nothing — but it is
     // exactly the branch that used to leave no trace anywhere, and the one line it
     // prints here is the whole point of noticing it (spec 32-6, a2time 2026-08-04).
-    for (const [suiteKind, messages] of problemsFor) {
-        blocked.push({ suite_kind: suiteKind, status: BLOCKED_STATUS, error: formatBranchProblems(messages) });
+    for (const problem of collectBuildProblems(request, outputs, unreadable)) {
+        blocked.push({ suite_kind: problem.branch, status: BLOCKED_STATUS, error: problem.message });
     }
     // Every branch is blocked, so there is nothing to upload. Asking the server to
     // publish an empty batch would turn a local, already-explained problem into a
@@ -103,46 +87,6 @@ export async function putSuiteBuild(config, _args = [], deps) {
 // malformed. Not a server status — it never reaches the server — but it travels
 // as one so a single rule decides what counts as published (see `PUBLISHED`).
 const BLOCKED_STATUS = 'not_ready';
-// 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.
-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 } : {}),
-    };
-}
-// 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.
-const PUBLISHED = new Set(['created', 'unchanged', 'restored']);
 export function classifyPublication(results) {
     const split = { digests: [], unpublished: [] };
     for (const result of results) {
@@ -176,7 +120,20 @@ function printResult(result) {
             .join(', ')
         : '';
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
-    return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
+    return (`${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.` + printDowngrades(result));
+}
+// Spec 42, §7. A capability every one of whose Scenarios the review objected to
+// is stored `unguarded` by the publish. The run is standing right here when that
+// is decided, so it is told here, in the server's own words — finding it on the
+// map afterwards is how a run finishes believing it published a guarantee it did
+// not.
+function printDowngrades(result) {
+    const downgraded = result.unguarded_by_review ?? [];
+    if (downgraded.length === 0)
+        return '';
+    return (`\n  ${downgraded.length} capability(ies) published unguarded, because the review objected to every ` +
+        'Scenario guarding them:\n' +
+        downgraded.map((entry) => `    - ${entry.capability_id}: ${entry.reason}`).join('\n'));
 }
 // The server's own words when it sent any; otherwise the best true thing that can
 // be said. A status this connector does not know is quoted rather than guessed

package/dist/verbs/run.js

@@ -27,9 +27,12 @@ function resolve(config, deps) {
     return {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
+        // The whole envelope, support files and all: a branch is a set of files
+        // since spec 42, §6, and picking `path` and `content` out of it here was
+        // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
-            suite_file: { path: item.suite_file.path, content: item.suite_file.content },
+            suite_file: item.suite_file,
             runner_manifest: item.runner_manifest,
         }),
         materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
@@ -98,7 +101,7 @@ async function buildRunPayload(config, d, item) {
         }
         else {
             d.materializeStructural(config.projectRoot, item);
-            result = await d.runStructural(config.projectRoot, runner, item.suite_file.path);
+            result = await d.runStructural(config.projectRoot, runner, artifactPaths(item.suite_file));
         }
     }
     catch (err) {
@@ -121,18 +124,24 @@ async function buildRunPayload(config, d, item) {
 // Exported for `run-local`, which runs these same strategies against the files
 // the host just wrote rather than against a published suite. One dispatch table,
 // so the command the loop iterates on is the command that runs after publishing.
-export function runStructuralByRunner(projectRoot, runner, suitePath) {
+export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     switch (runner) {
         case 'rspec':
-            return runRspecSuite(projectRoot, suitePath);
+            return runRspecSuite(projectRoot, suitePaths);
         case 'vitest':
-            return runVitestSuite(projectRoot, suitePath);
+            return runVitestSuite(projectRoot, suitePaths);
         case 'pytest':
-            return runPytestSuite(projectRoot, suitePath);
+            return runPytestSuite(projectRoot, suitePaths);
         default:
             return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite.`));
     }
 }
+// Every file of the branch, in the order the envelope carries them. A structural
+// branch is one file per assignment since spec 42, §6, and running only the main
+// one would execute a fraction of what the map says is guarded.
+function artifactPaths(file) {
+    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+}
 function suiteError(suiteDigest, message) {
     return {
         suite_digest: suiteDigest,

package/dist/verbs/runLocal.js

@@ -102,10 +102,10 @@ async function runOneBranch(config, d, suiteKind, output) {
         return null;
     }
     let runner;
-    let suitePath;
+    let suitePaths;
     try {
         runner = branchRunner(output);
-        suitePath = mainPathOf(output);
+        suitePaths = artifactPathsOf(output);
     }
     catch (err) {
         d.stdout.write(`Cannot run this branch: ${err.message}\n`);
@@ -120,8 +120,8 @@ async function runOneBranch(config, d, suiteKind, output) {
     try {
         result =
             suiteKind === 'behavioral'
-                ? await d.runBehavioral(config.projectRoot, runner, suitePath)
-                : await d.runStructural(config.projectRoot, runner, suitePath);
+                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0])
+                : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
         d.stdout.write(`The runner could not start: ${err.message}\n`);
@@ -161,14 +161,26 @@ function outputTail(result) {
     const joined = bits.join('\n');
     return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
 }
-// The suite blob's own project-relative path, exactly as the runners expect it.
-function mainPathOf(output) {
+// 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
+// assignment now — and running it alone would exercise a fraction of what the
+// answer claims to guard.
+//
+// The behavioral runners are given the main `.feature` and find the rest
+// themselves: all three are pointed at the directory (`bdd.ts`), which is why a
+// multi-file behavioral branch already worked before this spec.
+function artifactPathsOf(output) {
     const file = output.suite_file;
     const path = file?.path;
     if (typeof path !== 'string' || !path) {
         throw new Error('this branch names no suite file to run.');
     }
-    return path;
+    const support = Array.isArray(file?.support_files) ? file.support_files : [];
+    const rest = support
+        .map((entry) => entry?.path)
+        .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
+    return [path, ...rest];
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -2,10 +2,11 @@ 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 } from "../runner/precheck.js";
+import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
-import { ensureRunner } from "../runner/provision.js";
+import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -46,7 +47,8 @@ function runnerEnvelopeFor(packet, runner, projectRoot) {
         : envelope;
 }
 // Confirm at least one supported stack is present, materialize the Ruby boot
-// helper a generated RSpec suite would require, then fetch both peer assignments
+// helper an RSpec suite would need — only in a Ruby project — then fetch both
+// peer assignments
 // (spec 32) and each branch's recipe, and write the host's task to
 // `.unitbob/suite-build/request.json`. No model is called and no source is read
 // here — that is the host's job, framed by the two generation recipes. An
@@ -60,8 +62,10 @@ export async function suitePrepare(config, args = [], deps) {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
         bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
         worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
@@ -70,7 +74,36 @@ export async function suitePrepare(config, args = [], deps) {
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
-    materializeHelper(config.projectRoot);
+    // 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
+    // stack's litter in someone's repository.
+    if (detectStructuralRunner(config.projectRoot) === 'rspec')
+        materializeHelper(config.projectRoot);
+    // The stack is known; now make it runnable. A vibecoder who has never
+    // installed a test runner is the ordinary customer, not an edge case, so the
+    // runner (and, where the language allows it, the application's own
+    // dependencies) is installed under `.unitbob/` rather than reported as a
+    // reason they cannot use the product. Nothing in their project is written to.
+    //
+    // A project that already has its runner is left completely alone — see
+    // `ensureStructuralRunner` — so this costs nothing on a set-up machine.
+    const setupNotices = [];
+    if (check.runner) {
+        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.`);
+        }
+        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.`);
+    }
     // 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
     // and before the network, so a project whose suite cannot start costs one
@@ -124,6 +157,11 @@ export async function suitePrepare(config, args = [], deps) {
         const manifest = actual.runnerEnvelope(packet, runner, config.projectRoot);
         if (!manifest)
             return { packet, runner, branch: null };
+        // Spec 43, §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,
@@ -134,6 +172,7 @@ export async function suitePrepare(config, args = [], deps) {
                 recipe: await actual.getRecipe(recipeNameFor(packet)),
                 assignment: packet.assignment,
                 runner_manifest: manifest,
+                ...(stepLoading ? { step_loading: stepLoading } : {}),
             },
         };
     }));
@@ -168,8 +207,27 @@ 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;
+        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) {
+        actual.stdout.write('\nOne setup step is worth knowing about before you generate:\n  - ' + setupNotices.join('\n  - ') + '\n');
+    }
     if (fixableNotices.length > 0) {
         actual.stdout.write('\nBehavioral suite skipped this run — its runner or connector-owned World profile is not ready. ' +
             'This is a fixable setup step, not a build failure, and it does not affect the structural suite:\n' +
@@ -186,6 +244,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 43, §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
@@ -224,9 +300,10 @@ function bootFinding(boot, runner) {
     // the one the vibecoder can paste into a search.
     const next = boot.cause === 'defect_in_code'
         ? 'Fix that, then run `unitbob suite-prepare` again.'
-        : "Unitbob does not install your project's own dependencies — that would rewrite your Gemfile.lock " +
-            'or package-lock.json. Run the install your project needs (`bundle install`, `npm install`, ' +
-            '`pip install -r requirements.txt`), then run `unitbob suite-prepare` again.';
+        : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+            'it never writes to your project. Something outside that file is still missing here. Run the ' +
+            'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
+            'then run `unitbob suite-prepare` again.';
     return (`${headline}\n\n` +
         `  ${boot.message}\n\n` +
         `${boot.detail}\n\n` +