unitbob 0.2.8 → 0.3.1

package/dist/verbs/putSuiteBuild.js

@@ -1,52 +1,76 @@
-import { readBehavioralReview, readHostSuiteOutputs, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { readBehavioralReview, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { collectBuildProblems, formatBranchProblems } from "./validateBuild.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
 // (spec 32). `source_digest` comes from the task — never the host's answer — so
 // the host cannot claim a different map than each branch was given. A branch the
 // host could not build is uploaded as a `build_error`, which never rolls back the
-// peer branch. If a branch's answer is unparseable, nothing is uploaded.
+// peer branch. A branch whose local review will not bind is reported unpublished
+// and its peer still goes up — one branch's problem is never the other's.
+//
+// The line between "skip this branch" and "upload nothing" is whose problem it
+// is. The answer *file* is the whole answer: missing, unparseable, or carrying
+// no branches array, it stops everything, because there is no second problem to
+// find. Everything smaller belongs to one branch — a malformed entry, a review
+// that will not bind, a marker the local check could not account for — and its
+// peer still goes up.
 //
 // Returns the server's per-branch results so the caller can compose the first run
 // on top of them (spec 32-4) without parsing the lines printed here.
 export async function putSuiteBuild(config, _args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
-    const outputs = readHostSuiteOutputs(request.output_path, request);
+    // Spec 32-6: read branch by branch, so one unreadable entry neither hides the
+    // next branch's problems nor sinks a peer that is finished and correct.
+    const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const d = {
         putSuiteBuilds: (items) => new Wire(config).putSuiteBuilds(items),
         stdout: process.stdout,
         ...deps,
     };
     const digestFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.source_digest]));
-    const items = outputs.map((output) => {
+    const items = [];
+    const blocked = unreadable.map((entry) => ({
+        suite_kind: entry.suite_kind,
+        status: BLOCKED_STATUS,
+        error: entry.message,
+    }));
+    // The same check `unitbob validate-build` runs, run here too so it cannot be
+    // skipped by going straight to the upload — but reported the way every other
+    // local failure here is reported: against the branch it belongs to.
+    //
+    // 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)) {
+        problemsFor.set(problem.branch, [...(problemsFor.get(problem.branch) ?? []), problem.message]);
+    }
+    for (const output of outputs) {
+        const failed = problemsFor.get(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) {
-            return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
+            items.push({ suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error });
+            continue;
         }
         let testMetadata = output.test_metadata;
         if (output.suite_kind === 'behavioral') {
-            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.');
+            try {
+                testMetadata = withReview(config, request, output);
             }
-            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.');
+            catch (err) {
+                blocked.push({ suite_kind: output.suite_kind, status: BLOCKED_STATUS, error: err.message });
+                continue;
             }
-            testMetadata = {
-                ...output.test_metadata,
-                bdd_quality_review: {
-                    ...qualityReview,
-                    candidate_digest: review.candidate_digest,
-                },
-                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 } : {}),
-            };
         }
-        return {
+        items.push({
             suite_kind: output.suite_kind,
             source_digest: sourceDigest,
             artifacts: {
@@ -54,13 +78,53 @@ export async function putSuiteBuild(config, _args = [], deps) {
                 runner_manifest: output.runner_manifest,
                 test_metadata: testMetadata,
             },
-        };
-    });
-    const results = await d.putSuiteBuilds(items);
-    for (const result of results) {
+        });
+    }
+    // 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
+    // wire error with a worse message.
+    const results = items.length > 0 ? await d.putSuiteBuilds(items) : [];
+    const all = [...results, ...blocked];
+    for (const result of all) {
         d.stdout.write(`${printResult(result)}\n`);
     }
-    return results;
+    return all;
+}
+// A branch that cannot be assembled locally: its review is missing, stale, or
+// 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,
+        },
+        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
@@ -90,7 +154,11 @@ export function classifyPublication(results) {
 // above "no suite was published".
 function printResult(result) {
     if (!PUBLISHED.has(result.status)) {
-        return `${result.suite_kind}: not published — ${unpublishedReason(result)}.`;
+        // The reason often ends in a sentence of its own — a server message, or a
+        // list of this branch's problems — so the closing stop is added only when
+        // there is not one already.
+        const reason = unpublishedReason(result);
+        return `${result.suite_kind}: not published — ${reason}${/[.!?]$/.test(reason.trim()) ? '' : '.'}`;
     }
     const tallies = result.counts
         ? Object.entries(result.counts)

package/dist/verbs/run.js

@@ -5,6 +5,7 @@ import { runRspecSuite } from "../runner/rspec.js";
 import { runVitestSuite } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { enterUrl } from "../links.js";
 import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
 const OUTPUT_TAIL_CHARS = 2000;
@@ -54,8 +55,10 @@ async function execute(config, d, only) {
     const { results, map_url } = await d.postRunsBatch(runs);
     for (const result of results)
         d.stdout.write(`${result.summary}\n`);
+    // The token joins the address here rather than on the server, so it stays out
+    // of response bodies and out of the brain's logs (spec 33).
     if (map_url)
-        d.stdout.write(`${map_url}\n`);
+        d.stdout.write(`${enterUrl(config, map_url)}\n`);
 }
 // All-or-nothing. Publication and this fetch are two requests, so another client
 // can republish in between. Running whatever is current instead would file honest

package/dist/verbs/show.js

@@ -1,5 +1,6 @@
+import { consoleUrl } from "../links.js";
 export function repoUrl(config) {
-    return `${config.server}/repos/${config.repoId}#map`;
+    return consoleUrl(config);
 }
 export async function show(config) {
     process.stdout.write(`${repoUrl(config)}\n`);

package/dist/verbs/suitePrepare.js

@@ -1,10 +1,47 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import { materializeHelper } from "../files/guardrails.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { anyStackPrecheck } from "../runner/precheck.js";
+import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
+import { anyStackPrecheck, detectBddRunner, detectStructuralRunner } from "../runner/precheck.js";
+import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
 import { ensureRunner } from "../runner/provision.js";
 import { Wire } from "../wire.js";
+// The complete envelope for one branch, or null when this machine cannot
+// produce one: the server offered no combination this stack matches, or the
+// behavioral runner's installed version could not be read back.
+//
+// Null stops the branch rather than handing the host a shape to fill in. The
+// host's own composition is what this path replaced — a single wrong field is
+// rejected at upload, hours after the suite was written, run, and reviewed —
+// and a half-filled envelope fails the same way. Better to say so now, in one
+// line, than to be told by the server at the end.
+// Why a branch got no envelope, in the vibecoder's terms. The two causes sit on
+// opposite sides of the wire and have opposite fixes, so they are never merged
+// into one vague line.
+function envelopeBlockedReason(packet, runner) {
+    if (!Array.isArray(packet.runner_manifests) || packet.runner_manifests.length === 0) {
+        return 'the Unitbob server sent no runner combinations with this assignment — it is older than this connector. ' +
+            'Update the server (or the connector) so the two agree, then retry.';
+    }
+    if (!runner) {
+        return `this project matches none of the runners the server offered for the ${packet.suite_kind} suite.`;
+    }
+    return `the version of "${runner}" installed under .unitbob/behavioral/ could not be read, and the server requires it. ` +
+        'Re-run `unitbob suite-prepare` so the runner is provisioned again.';
+}
+function runnerEnvelopeFor(packet, runner, projectRoot) {
+    const selected = runner
+        ?? (packet.suite_kind === 'behavioral'
+            ? detectBddRunner(projectRoot) ?? undefined
+            : detectStructuralRunner(projectRoot) ?? undefined);
+    const envelope = selectRunnerEnvelope(packet.runner_manifests, selected);
+    if (!envelope || !selected)
+        return envelope;
+    // Only the behavioral runner is provisioned into an isolated environment, so
+    // it is the only one with an installed version to record.
+    return packet.suite_kind === 'behavioral'
+        ? withInstalledRunnerVersion(envelope, selected, 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
 // (spec 32) and each branch's recipe, and write the host's task to
@@ -20,7 +57,9 @@ export async function suitePrepare(config, args = [], deps) {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
         ...deps,
     };
@@ -28,6 +67,23 @@ export async function suitePrepare(config, args = [], deps) {
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
     materializeHelper(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
+    // and before the network, so a project whose suite cannot start costs one
+    // command instead of a full generation.
+    //
+    // There is no `--on-broken-boot` flag and no mode. The decision is not a
+    // policy we could reasonably let a user set — it follows from the fact: we
+    // tried to load the thing the suite starts with, it did not load, therefore
+    // not one test would reach its first assertion. Debugging generation against a
+    // knowingly dead project is our problem, not the vibecoder's.
+    // The stack the precheck just identified, rather than a second detection of
+    // 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));
+    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.
     // A `fixable` outcome (no package manager available to install the runner) is an infrastructure
@@ -38,7 +94,8 @@ export async function suitePrepare(config, args = [], deps) {
     const fixableNotices = [];
     const buildable = [];
     for (const packet of packets) {
-        const runner = packet.runner ?? (packet.suite_kind === 'behavioral' ? inferBddRunner(config.projectRoot) : undefined);
+        const runner = packet.runner
+            ?? (packet.suite_kind === 'behavioral' ? detectBddRunner(config.projectRoot) ?? undefined : undefined);
         if (runner && (packet.suite_kind === 'behavioral' || ['cucumber', 'cucumber-js', 'pytest-bdd'].includes(runner))) {
             const prov = await actual.ensureRunner(config.projectRoot, runner);
             if (prov.status === 'fixable') {
@@ -47,15 +104,42 @@ export async function suitePrepare(config, args = [], deps) {
                 continue;
             }
         }
-        buildable.push(packet);
+        buildable.push({ packet, runner });
+    }
+    const prepared = await Promise.all(buildable.map(async ({ packet, runner }) => {
+        // Read after provisioning, never before: the behavioral envelope carries
+        // the version that is now installed in the sidecar.
+        const manifest = actual.runnerEnvelope(packet, runner, config.projectRoot);
+        if (!manifest)
+            return { packet, runner, branch: null };
+        return {
+            packet,
+            runner,
+            branch: {
+                suite_kind: packet.suite_kind,
+                source_digest: packet.source_digest,
+                path_root: packet.path_root,
+                recipe: await actual.getRecipe(recipeNameFor(packet)),
+                assignment: packet.assignment,
+                runner_manifest: manifest,
+            },
+        };
+    }));
+    // A branch without a complete envelope is not handed to the host at all. The
+    // host has nothing to compose it from — that composition is what this replaced
+    // — so writing the branch anyway only moves the same rejection to the end of
+    // the run, hours later.
+    const branches = [];
+    const blockedNotices = [];
+    for (const { packet, runner, branch } of prepared) {
+        if (branch)
+            branches.push(branch);
+        else
+            blockedNotices.push(`  ${packet.suite_kind}: ${envelopeBlockedReason(packet, runner)}`);
+    }
+    if (branches.length === 0) {
+        throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\nNothing was written and nothing was uploaded.`);
     }
-    const branches = await Promise.all(buildable.map(async (packet) => ({
-        suite_kind: packet.suite_kind,
-        source_digest: packet.source_digest,
-        path_root: packet.path_root,
-        recipe: await actual.getRecipe(recipeNameFor(packet)),
-        assignment: packet.assignment,
-    })));
     const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
     const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
@@ -73,7 +157,102 @@ export async function suitePrepare(config, args = [], deps) {
             fixableNotices.join('\n') +
             '\nFix the above, then re-run `unitbob suite-prepare` to build the behavioral peer.\n');
     }
+    // Same shape, different cause: this branch has an assignment but no runner
+    // envelope to upload it with, so it is not offered to the host at all. Its
+    // peer above is unaffected.
+    if (blockedNotices.length > 0) {
+        actual.stdout.write('\nOne suite branch was left out of this run — it has no runner manifest, and the server ' +
+            'accepts an upload only with one:\n' +
+            blockedNotices.join('\n') +
+            '\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
+// trusts.
+//
+// A stop here is a finding, not a refusal, and the wording has to carry that.
+// "We found the defect that stops your suite from starting" and "we could not
+// build your suite" describe the same event and leave the reader in completely
+// different places.
+function bootFinding(boot, runner) {
+    // Both halves of "what this answer is worth" travel together, on every
+    // outcome. Splitting them is how the stack caveat came to be missing from
+    // `broken`, and pinning `STRUCTURAL_ONLY` to `ok` alone would have repeated
+    // that in the same breath as the fix: on Rails the stack caveat reads
+    // "whatever stops one stops the other", which is an unscoped claim about a
+    // branch nobody asked — loudest exactly where the run stops for both.
+    // Empties are dropped rather than joined blindly, so a runner with no caveat
+    // of its own does not leave a blank line behind.
+    const caveat = [runner ? SIGNAL_STRENGTH[runner] : '', runner ? STRUCTURAL_ONLY : '']
+        .filter(Boolean)
+        .map((line) => `\n${line}`)
+        .join('');
+    if (boot.status === 'ok') {
+        return `Checked that the suite can start: it does.${caveat}\n`;
+    }
+    if (boot.status === 'not_checked') {
+        // 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 headline = boot.cause === 'defect_in_code'
+        ? 'Found a defect that stops your test suite from starting.'
+        : 'Your test suite cannot start yet — its environment is not ready.';
+    // The runner's own words. Everything else on screen is ours; this line is
+    // 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.';
+    return (`${headline}\n\n` +
+        `  ${boot.message}\n\n` +
+        `${boot.detail}\n\n` +
+        'No suite was written and nothing was uploaded — every test would have died on that line ' +
+        // The caveat belongs here most of all, and this was the one branch it did
+        // not reach — found on the fifth implementation review, 2026-08-03. On
+        // pytest and vitest the check collects the project's whole test tree, so
+        // the line above may come from a test of the project's own that the Unitbob
+        // suite would never have imported. Printing "found a defect" and keeping
+        // that back sends someone to fix a file this product was never going to
+        // touch, which is the same over-claim the spec accepted the wide check only
+        // on condition of disclosing.
+        `before reaching its first assertion. ${next}${caveat}\n`);
+}
+// Spec 32-6 says the boot rule is one rule for both branches; this check asks
+// one of them. It is made against the *structural* runner, which is what
+// `precheck` identified and what the materialized helper belongs to. The
+// behavioral branch starts elsewhere — cucumber with its own `features/support`,
+// cucumber-js with its own — and there is nothing of ours to load there yet:
+// at this point in `suite-prepare` the behavioral suite has not been generated.
+// Asking the question anyway would mean booting the project's own feature
+// files, which is *wider* than the condition that stops the Unitbob run — the
+// one thing this module's governing rule forbids ("the condition we test must
+// equal the condition that makes a run impossible, never exceed it").
+//
+// So the boundary is stated instead of crossed. Recorded on the fifth
+// implementation review, 2026-08-03, and written into the spec beside it.
+const STRUCTURAL_ONLY = 'This says nothing about the product-behaviour branch: it starts with a runner of its own, ' +
+    'which has nothing of ours to load until its suite exists, so it was not asked.';
+const NOT_CHECKED_REASON = {
+    no_runner: 'Did not check whether the suite can start: no runner available to load it with.',
+    // Distinct from `no_runner` on purpose. The runner is installed and working;
+    // it is only too old to be asked this particular question, and "no runner
+    // available" would send someone to fix a thing that is not broken.
+    runner_too_old: 'Did not check whether the suite can start: the installed runner is too old to be asked. ' +
+        'Nothing is wrong with it — this check simply has no way to pose the question to that version.',
+    // Distinct for the same reason, one step further along: the runner is there
+    // and current, it was reached, and it declined to answer — pytest exiting on
+    // a usage or internal error of its own. That says nothing about the project,
+    // and "no runner available" would again send someone after the wrong thing.
+    runner_could_not_answer: 'Did not check whether the suite can start: the runner could not answer the question — it ' +
+        '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.',
+};
 function knownDefectContext(args) {
     const defect = option(args, '--known-defect=');
     const fixedRevision = option(args, '--fixed-revision=');
@@ -100,10 +279,3 @@ function option(args, prefix) {
         throw new Error(`${prefix.slice(0, -1)} requires a value.`);
     return value || undefined;
 }
-function inferBddRunner(projectRoot) {
-    if (existsSync(join(projectRoot, 'package.json')))
-        return 'cucumber-js';
-    if (['pyproject.toml', 'requirements.txt', 'Pipfile'].some((f) => existsSync(join(projectRoot, f))))
-        return 'pytest-bdd';
-    return 'cucumber';
-}