unitbob 0.2.7 → 0.2.8

package/dist/cli.js

@@ -3,15 +3,20 @@
 // trace. This module decides exit codes but never acts on them: importing it must
 // stay free of side effects so tests can drive `main` directly. `bin.ts` is the
 // executable that owns process startup and exit.
+//
+// One verb is more than a dispatch: `put-suite-build` composes two hands-verbs
+// into a single user operation, so `publishAndRun` at the bottom of this file
+// holds that sequence and the exit code it implies (spec 32-4). Every other verb
+// keeps its whole flow in its own module under `verbs/`.
 import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
-import { run } from "./verbs/run.js";
+import { run, runOnly } from "./verbs/run.js";
 import { init } from "./verbs/init.js";
 import { mapPrepare } from "./verbs/mapPrepare.js";
 import { putMapBuild } from "./verbs/putMapBuild.js";
 import { suitePrepare } from "./verbs/suitePrepare.js";
-import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
+import { classifyPublication, putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
 import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
@@ -27,7 +32,8 @@ Verbs:
   put-map-build        Internal: upload the host-built map and graph.
   suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
   suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
-  put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata).
+  put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata),
+                       then run every branch it published and report the server's results.
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
   contract-prompt <digest> <test_id> [fix|accept]
                        Internal: fetch the fix/accept brief for one red check on either map.
@@ -37,7 +43,8 @@ Verbs:
 Pipeline: map and suite are built on your machine. \`*-prepare\` writes a request
 packet (with the recipe and paths); you build the artifact at the packet's
 output_path from your local source; \`put-*\` uploads only the structured result.
-\`check\` runs the guardrails locally and reports results to the server.
+\`put-suite-build\` then runs what it published, so a suite never sits with nothing
+to show. \`check\` re-runs the guardrails locally and reports results to the server.
 Graph extraction is keyless: the connector needs no LLM API key. Inference is the
 host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify skill).
 
@@ -73,8 +80,7 @@ export async function main(argv, deps = { ensureLinked }) {
                 await suiteReviewPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-suite-build':
-                await putSuiteBuild(await deps.ensureLinked(), args);
-                return 0;
+                return await publishAndRun(await deps.ensureLinked(), args);
             case 'fix-prepare':
                 await fixPrepare(await deps.ensureLinked(), args);
                 return 0;
@@ -95,3 +101,48 @@ export async function main(argv, deps = { ensureLinked }) {
         return 1;
     }
 }
+// Publishing a suite and running it the first time are one user operation
+// (spec 32-4). They used to be two commands, and the second one was a step the
+// host LLM could simply not take: the suite was stored, nothing had ever run it,
+// and the user was told about results that did not exist. Now the connector owns
+// the sequence, so no instruction-following can drop half of it.
+//
+// This is a composition, not a transaction. The two server requests stay separate:
+// if the run cannot finish, the published suite and any earlier results for the
+// same identity survive untouched, and a standalone `unitbob check` completes the
+// loop. The two outputs also keep separate authorities — which branch published
+// comes from the build response, and what the results are comes only from the
+// server's answer to the run.
+export async function publishAndRun(config, args, deps) {
+    const d = {
+        putSuiteBuild: (cfg, a) => putSuiteBuild(cfg, a),
+        runOnly: (cfg, digests) => runOnly(cfg, digests),
+        stdout: process.stdout,
+        stderr: process.stderr,
+        ...deps,
+    };
+    const { digests, unpublished } = classifyPublication(await d.putSuiteBuild(config, args));
+    // Nothing is current, so there is nothing honest to run. A branch that failed
+    // to publish must never fall back to the suite it was meant to replace.
+    if (digests.length === 0) {
+        d.stderr.write('No suite was published, so nothing was run. Fix the problems reported above and generate the Unitbob guardrails again.\n');
+        return 1;
+    }
+    // Said between the two halves, because it is a fact about publication and the
+    // run summaries have not been printed yet. Reading a peer's results onto a
+    // branch that was never published is the exact mistake this whole spec exists
+    // to stop, so the output names the gap instead of leaving it to be inferred.
+    if (unpublished.length > 0) {
+        d.stdout.write(`Partial success. No run summary below covers: ${unpublished.join(', ')}.\n`);
+    }
+    try {
+        await d.runOnly(config, digests);
+    }
+    catch (err) {
+        // The upload never happened, so no results were stored — partially or
+        // otherwise. Everything published above is still valid and still current.
+        d.stderr.write(`${err.message}\nThe suite is published. Run the Unitbob checks to finish.\n`);
+        return 1;
+    }
+    return 0;
+}

package/dist/verbs/putSuiteBuild.js

@@ -6,6 +6,9 @@ import { Wire } from "../wire.js";
 // 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.
+//
+// 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);
@@ -57,10 +60,37 @@ export async function putSuiteBuild(config, _args = [], deps) {
     for (const result of results) {
         d.stdout.write(`${printResult(result)}\n`);
     }
+    return results;
 }
+// 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) {
+        if (!PUBLISHED.has(result.status)) {
+            split.unpublished.push(result.suite_kind);
+            continue;
+        }
+        if (!result.suite_digest) {
+            throw new Error(`The server accepted the ${result.suite_kind} suite as "${result.status}" but returned no identity ` +
+                'to run it by. The suite is published; run the Unitbob checks to finish.');
+        }
+        split.digests.push(result.suite_digest);
+    }
+    return split;
+}
+// Asks `PUBLISHED` rather than naming the failing statuses again: this line and
+// the run that follows it must agree about what "published" means, or a branch the
+// command skipped gets a line that reads like a success — digest and all — right
+// above "no suite was published".
 function printResult(result) {
-    if (result.status === 'error' || result.status === 'build_error') {
-        return `${result.suite_kind}: not published — ${result.error ?? 'the host could not build this suite'}.`;
+    if (!PUBLISHED.has(result.status)) {
+        return `${result.suite_kind}: not published — ${unpublishedReason(result)}.`;
     }
     const tallies = result.counts
         ? Object.entries(result.counts)
@@ -70,3 +100,13 @@ function printResult(result) {
     const digest = result.suite_digest ? ` (${result.suite_digest})` : '';
     return `${result.suite_kind}: ${result.status}${digest}${tallies ? ` — ${tallies}` : ''}.`;
 }
+// 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
+// at — claiming the host could not build it would invent a cause.
+function unpublishedReason(result) {
+    if (result.error)
+        return result.error;
+    if (result.status === 'build_error')
+        return 'the host could not build this suite';
+    return `the server answered "${result.status}"`;
+}

package/dist/verbs/run.js

@@ -8,9 +8,22 @@ import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { Wire } from "../wire.js";
 const OUTPUT_TAIL_CHARS = 2000;
+// `check`/`run`: execute every ready peer. This is the standalone flow the user
+// asks for by name, and the recovery path after an interrupted first run.
 export async function run(config, _args, deps) {
+    return execute(config, resolve(config, deps), null);
+}
+// The first run that `put-suite-build` performs itself (spec 32-4): execute
+// exactly the suite identities publication just returned, or none of them. Every
+// requested identity must still be the current one — see `select`. Callers pass a
+// non-empty list; "nothing was published" is decided and reported one level up,
+// where the publication results that explain it are still in hand.
+export async function runOnly(config, digests, deps) {
+    return execute(config, resolve(config, deps), digests);
+}
+function resolve(config, deps) {
     const wire = new Wire(config);
-    const d = {
+    return {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
@@ -25,14 +38,17 @@ export async function run(config, _args, deps) {
         stdout: process.stdout,
         ...deps,
     };
+}
+async function execute(config, d, only) {
     const suites = await d.getSuites();
     const ready = suites.filter((item) => item.status === 'ready');
-    if (ready.length === 0) {
+    const selected = only === null ? ready : select(ready, only);
+    if (selected.length === 0) {
         d.stdout.write('No Unitbob suites exist yet. Generate them first, then run the Unitbob checks again.\n');
         return;
     }
     const runs = [];
-    for (const item of ready) {
+    for (const item of selected) {
         runs.push(await buildRunPayload(config, d, item));
     }
     const { results, map_url } = await d.postRunsBatch(runs);
@@ -41,6 +57,21 @@ export async function run(config, _args, deps) {
     if (map_url)
         d.stdout.write(`${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
+// results against a version the user never asked about, and silently substituting
+// an older suite for a branch that failed to publish would be worse still. So a
+// requested identity that is no longer current stops the whole run.
+function select(ready, wanted) {
+    const byDigest = new Map(ready.map((item) => [item.suite_digest ?? '', item]));
+    const missing = wanted.filter((digest) => !byDigest.has(digest));
+    if (missing.length > 0) {
+        throw new Error(`The suite this project just published (${missing.join(', ')}) is no longer the current one — ` +
+            'something else replaced it while this command was running. Nothing was run, so no results were ' +
+            'filed against the wrong version.');
+    }
+    return wanted.map((digest) => byDigest.get(digest));
+}
 // One branch's run payload. A stack mismatch, a materialize failure, or a runner
 // that produced no report all become this branch's structured suite error — the
 // peer branch is unaffected. This connector never installs anything: a missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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": {