unitbob 0.7.8 → 0.7.13

package/dist/verbs/testsPrepare.js

@@ -0,0 +1,77 @@
+import { materializeBehavioralUnion, materializeBehavioralWorld } from "../files/behavioral.js";
+import { featureFeaturePath, featureStepsPath, knowledgePath, parseFeatureId, testsOutputPath, testsRequestPath, writeTestsRequest, } from "../files/features.js";
+import { installedRunnerVersion, selectRunnerEnvelope } from "../runner/manifest.js";
+import { placeProblem } from "../runner/place.js";
+import { detectBddRunner } from "../runner/precheck.js";
+import { ensureRunner } from "../runner/provision.js";
+import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { Wire } from "../wire.js";
+import { assertKnowledgeUnchanged } from "./putTests.js";
+// `tests-prepare <feature_id>` (spec 52-3, AC 3.4): the host's task for writing
+// a feature's checks. The packet (a 409 before the talk is the server's own
+// sentence, let through), then the knowledge file on disk held to the server's
+// digest — the checks are written from that file, and a file edited after the
+// talk would put text under seal the person never confirmed — then the recipe,
+// the union of the main suite and every red feature's checks on disk (the
+// shared steps to reuse, the base for rewriting the wiring at `red`), the
+// runner provisioned as `suite-prepare` provisions it, the World in place, and
+// `tests-request.json` beside the talk's request. No model is called, nothing
+// is uploaded.
+export async function testsPrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getTestsPacket: (id) => wire.getTestsPacket(id),
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuiteIndex: () => wire.getSuiteIndex(),
+        detectRunner: detectBddRunner,
+        ensureRunner,
+        installedVersion: installedRunnerVersion,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-prepare');
+    const unusable = placeProblem(config.projectRoot);
+    if (unusable)
+        throw new Error(unusable);
+    const packet = await d.getTestsPacket(featureId);
+    assertKnowledgeUnchanged(config.projectRoot, featureId, packet.knowledge_digest);
+    const [recipe, index] = await Promise.all([d.getRecipe('feature_tests'), d.getSuiteIndex()]);
+    // The main suite's runner when it is built — the checks share its directory
+    // and its steps, so they cannot run on another — else the one this stack
+    // selects, as `suite-prepare` does.
+    const runner = packet.main_suite === 'not_built' ? d.detectRunner(config.projectRoot) : packet.main_suite.runner;
+    if (!runner) {
+        throw new Error('This project matches no BDD runner the connector can run — the checks cannot be written on it.');
+    }
+    const provisioned = await d.ensureRunner(config.projectRoot, runner);
+    if (provisioned.status === 'fixable') {
+        const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
+        throw new ToolchainUnavailableError(`The "${runner}" runner could not be installed under .unitbob/, and the checks cannot run without it: ` +
+            `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written.`, config.projectRoot);
+    }
+    const selected = selectRunnerEnvelope(packet.runner_manifests, runner);
+    const version = d.installedVersion(runner, config.projectRoot);
+    if (!selected || !version) {
+        throw new Error(`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.');
+    }
+    materializeBehavioralUnion(config.projectRoot, index, runner);
+    materializeBehavioralWorld(config.projectRoot, runner);
+    writeTestsRequest(config.projectRoot, featureId, {
+        project_root: config.projectRoot,
+        recipe,
+        feature: packet.feature,
+        feature_tag: packet.feature_tag,
+        assignment: packet.assignment,
+        scenarios: packet.scenarios,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        knowledge_digest: packet.knowledge_digest,
+        runner,
+        runner_manifest: { ...selected, runner_version: version },
+        main_suite: packet.main_suite,
+        feature_path: featureFeaturePath(featureId),
+        steps_path: featureStepsPath(featureId, runner),
+        output_path: testsOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Tests request written to ${testsRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/testsReviewPrepare.js

@@ -0,0 +1,40 @@
+import { knowledgePath, parseFeatureId, readTestsOutput, readTestsRequest, testsReviewOutputPath, testsReviewRequestPath, writeTestsReviewRequest, } from "../files/features.js";
+import { suiteCandidateDigest } from "../files/suiteBuild.js";
+import { Wire } from "../wire.js";
+// `tests-review-prepare <feature_id>` (spec 52-4, AC 1.11): the independent
+// reviewer's task for a feature's checks, once they all pass. The packet
+// first — a 409 is the server's own sentence, at `intent` (nothing to review)
+// and at `done` (the checks are guardrails now), let through as it is — then
+// the files from disk exactly as `put-tests` will send them, bound by the same
+// candidate digest the upload carries, and the request written in the shape
+// of the main suite's `review-request.json` so the same role reads it: plus
+// where `knowledge.md` is, because the promise each scenario protects is
+// written there, and the scenarios as the server sealed them. No model is
+// called, nothing is uploaded; `put-tests` publishes the review.
+export async function testsReviewPrepare(config, args = [], deps) {
+    const d = {
+        getTestsPacket: (id) => new Wire(config).getTestsPacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'tests-review-prepare');
+    // An existence guard only: the request is what `put-tests` will read after
+    // the review, and its absence names the verb that writes it — better said
+    // here than as a missing answer two steps later.
+    readTestsRequest(config.projectRoot, featureId);
+    const packet = await d.getTestsPacket(featureId);
+    const output = readTestsOutput(config.projectRoot, featureId);
+    writeTestsReviewRequest(config.projectRoot, featureId, {
+        candidate_digest: suiteCandidateDigest({
+            suite_kind: 'behavioral', suite_file: output.suite_file, runner_manifest: output.runner_manifest,
+        }),
+        suite_file: output.suite_file,
+        capabilities: output.test_metadata.capabilities,
+        knowledge_path: knowledgePath(config.projectRoot, featureId),
+        scenarios: packet.scenarios,
+        output_path: testsReviewOutputPath(config.projectRoot, featureId),
+    });
+    d.stdout.write(`Feature review request written to ${testsReviewRequestPath(config.projectRoot, featureId)}\n`);
+    d.stdout.write(`Next: have the independent reviewer write bdd_quality_review to ${testsReviewOutputPath(config.projectRoot, featureId)}, ` +
+        `then run \`unitbob put-tests ${featureId}\`.\n`);
+}

package/dist/wire.js

@@ -7,11 +7,17 @@ import { proxyHint } from "./proxyHint.js";
 // that reads an absence as a verdict either invents a rejection or invents an
 // approval. `validate-build` is the caller that needs the difference: with no
 // server it succeeds, and says out loud which questions went unasked.
+//
+// `status` is the HTTP status the server answered with, when there was one:
+// for the one caller that treats a 404 — a server older than the route — as
+// an absence rather than a verdict (`map-prepare`, spec 52-4).
 export class WireError extends Error {
     unreachable;
+    status;
     constructor(message, options = {}) {
         super(message);
         this.unreachable = options.unreachable ?? false;
+        this.status = options.status ?? null;
     }
 }
 // POST /repos/register — the linking bootstrap (spec 28). A standalone function
@@ -102,15 +108,19 @@ export class Wire {
         return body.results;
     }
     // GET /repos/:id/suites — both current suites (spec 32), exactly two peer
-    // items. A `ready` item carries its blob; a `not_built` item is skipped.
-    async getSuites() {
+    // items, and since spec 52-3 the checks of every red feature beside them. A
+    // `ready` item carries its blob; a `not_built` item is skipped.
+    async getSuiteIndex() {
         const res = await this.send('GET', this.repoPath('suites'));
         await this.ensureOk(res, `GET ${this.repoPath('suites')}`);
         const body = (await res.json());
         if (!Array.isArray(body.suites)) {
             throw new WireError(`GET ${this.repoPath('suites')} returned no suites array.`);
         }
-        return body.suites;
+        return {
+            suites: body.suites,
+            feature_suites: Array.isArray(body.feature_suites) ? body.feature_suites : [],
+        };
     }
     // POST /repos/:id/runs/batch — ship each branch's raw report (or suite error)
     // in one batch; the server parses each against the exact stored version and
@@ -149,6 +159,15 @@ export class Wire {
         await this.ensureOk(res, `PUT ${this.repoPath('suite_build')}`);
         return (await res.json());
     }
+    // GET /repos/:id/red_lamps — the red list (spec 54-1). No parameters: the
+    // server names the current version of each map itself, which is the whole
+    // point — a fix no longer guesses a digest.
+    async getRedList() {
+        const url = this.repoPath('red_lamps');
+        const res = await this.send('GET', url);
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
     // GET /repos/:id/fix_packet?interface_id= — the per-capability repair packet.
     // Relayed down for the host to fix code or accept the change; 422 (non-failed /
     // stale / no suite) surfaces as a WireError carrying the server's business reason.
@@ -158,6 +177,69 @@ export class Wire {
         await this.ensureOk(res, `GET ${url}`);
         return (await res.json());
     }
+    // POST /repos/:id/features — record a feature (spec 52-1). A 409 (no current
+    // map) and a 422 (an id not on the map, with both sides named in the body)
+    // surface as a WireError carrying the server's text, so the host reads what
+    // the map knows and corrects its file.
+    async postFeature(payload) {
+        const res = await this.send('POST', this.repoPath('features'), payload);
+        if (res.status === 422)
+            throw new WireError(await unknownCapabilitiesRefusal(res));
+        await this.ensureOk(res, `POST ${this.repoPath('features')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features — every feature of the project, newest first, and
+    // the server's words for an empty list (spec 52-2, AC 1.2).
+    async listFeatures() {
+        const res = await this.send('GET', this.repoPath('features'));
+        await this.ensureOk(res, `GET ${this.repoPath('features')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features/:feature_id/knowledge_packet (spec 52-2, AC 1.3).
+    async getKnowledgePacket(featureId) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/knowledge_packet`);
+        const res = await this.send('GET', path);
+        await this.ensureOk(res, `GET ${path}`);
+        return (await res.json());
+    }
+    // PUT /repos/:id/features/:feature_id/knowledge (spec 52-2, AC 1.4). The
+    // server checks the file's shape; a 422 carries `problems`, and they are
+    // relaid whole, one line per problem with both sides — the host fixes the
+    // file from those lines, and cutting them at 500 characters would hide the
+    // ones at the end.
+    async putKnowledge(featureId, knowledge) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/knowledge`);
+        const res = await this.send('PUT', path, { knowledge });
+        if (res.status === 422)
+            throw new WireError(await problemsRefusal(res, 'PUT knowledge failed: 422'));
+        await this.ensureOk(res, `PUT ${path}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/features/:feature_id/tests_packet (spec 52-3, AC 2.1). A
+    // 409 is the server's own sentence (talk the feature through first) and is
+    // relaid as it is.
+    async getTestsPacket(featureId) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/tests_packet`);
+        const res = await this.send('GET', path);
+        if (res.status === 409)
+            throw new WireError(await wordedRefusal(res, `GET tests_packet failed: 409`));
+        await this.ensureOk(res, `GET ${path}`);
+        return (await res.json());
+    }
+    // PUT /repos/:id/features/:feature_id/suite (spec 52-3, AC 2.2). Every
+    // refusal is worded by the server: a 409 in one sentence, a 422 in one
+    // sentence or, for a broken seal, with one problem per difference — relaid
+    // whole, both sides per line, like the knowledge file's.
+    async putFeatureSuite(featureId, upload) {
+        const path = this.repoPath(`features/${encodeURIComponent(String(featureId))}/suite`);
+        const res = await this.send('PUT', path, upload);
+        if (res.status === 409)
+            throw new WireError(await wordedRefusal(res, 'PUT suite failed: 409'));
+        if (res.status === 422)
+            throw new WireError(await problemsRefusal(res, 'PUT suite failed: 422'));
+        await this.ensureOk(res, `PUT ${path}`);
+        return (await res.json());
+    }
     // GET /recipes/:name — fetch a recipe at call time. Recipes live on Rails so
     // the connector and Skill carry no recipe text (spec 15, acceptance criteria).
     async getRecipe(name) {
@@ -244,7 +326,7 @@ export class Wire {
         if (res.status === 404) {
             throw new WireError(`This project is linked to a repository the server at ${this.config.server} does not have, ` +
                 'or the token in .unitbob.json does not open it. Delete .unitbob.json to link again ' +
-                '(the old project, along with its map and checks, stays where it is).');
+                '(the old project, along with its map and checks, stays where it is).', { status: 404 });
         }
         let detail = '';
         try {
@@ -253,8 +335,55 @@ export class Wire {
         catch {
             // ignore — the status alone is actionable enough
         }
-        throw new WireError(statusRefusal(what, res, detail, this.config.server));
+        throw new WireError(statusRefusal(what, res, detail, this.config.server), { status: res.status });
+    }
+}
+// The 422 of POST /features carries two lists, and the host corrects its file by
+// reading both (spec 52-1, AC 1.3). `ensureOk` keeps 500 characters of a body,
+// which is a line of context for every other refusal and, on a map of twenty
+// capabilities or more, cuts `known_ids` in half — the list the correction is
+// made from, on exactly the projects that have the most ids to get wrong. So
+// the two lists are relaid whole, one per line; any other 422 body keeps the
+// ordinary shape.
+async function unknownCapabilitiesRefusal(res) {
+    const { text, body } = await readBody(res);
+    if (!Array.isArray(body.unknown_ids) || !Array.isArray(body.known_ids)) {
+        return `POST features failed: 422 — ${text.slice(0, 500)}`;
+    }
+    return (`POST features failed: 422 — ${String(body.error ?? 'These capabilities are not on the current map.')}\n` +
+        `unknown_ids: ${JSON.stringify(body.unknown_ids)}\n` +
+        `known_ids: ${JSON.stringify(body.known_ids)}`);
+}
+// A refusal the server worded in one sentence: that sentence, whole.
+async function wordedRefusal(res, prefix) {
+    const { text, body } = await readBody(res);
+    return `${prefix} — ${typeof body.error === 'string' ? body.error : text.slice(0, 500)}`;
+}
+// A refusal that may carry `problems` — the knowledge file's shape (spec 52-2,
+// AC 5.3) or a broken seal (spec 52-3): the sentence, then one problem per line
+// with both sides, relaid whole because the host fixes the file from all of
+// them; without problems, the sentence.
+async function problemsRefusal(res, prefix) {
+    const { text, body } = await readBody(res);
+    const head = `${prefix} — ${typeof body.error === 'string' ? body.error : text.slice(0, 500)}`;
+    if (!Array.isArray(body.problems))
+        return head;
+    const lines = body.problems.map((problem) => `expected: ${String(problem.expected)}\n     got: ${String(problem.got)}`);
+    return [head, ...lines].join('\n');
+}
+// A refusal body as text and, when it is JSON, as an object; when it is not,
+// the text itself is the detail.
+async function readBody(res) {
+    let text = '';
+    let body = {};
+    try {
+        text = await res.text();
+        body = JSON.parse(text);
+    }
+    catch {
+        // not JSON — the text itself is the detail
     }
+    return { text, body };
 }
 // The two statuses that prove somebody else answered.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.7.8",
+  "version": "0.7.13",
   "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.7.8 run-local <branch>` and inspect the machine
+`npx -y --loglevel=error unitbob@0.7.13 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

package/plugin/codex/agents/suite-reviewer.toml

@@ -160,6 +160,24 @@ genuinely holds a promise and holds less of it than its name suggests. Nothing
 mechanical can tell those two apart; what makes the difference is that your
 sentence is specific enough to act on.
 
+## A feature's checks
+
+The same review, for a smaller candidate: the checks of one feature being
+built (spec 52-4). Then the request is
+`.unitbob/features/<id>/tests-review-request.json`, with the same keys as the
+main suite's plus two — `knowledge_path` and `scenarios` — and the review goes
+to the `output_path` it names, in the same form: `candidate_digest` at the top
+level, `bdd_quality_review` with one entry per Scenario by `case_marker` and
+name. There is no `known_defect_probe` and no `selection_review` here; write
+neither.
+
+When the request carries `knowledge_path`, the promise each Scenario protects
+is written in that `knowledge.md`, in its `Scenarios` section — read it there,
+not from the capability description, which for a feature is one line. The
+Scenario text is the user's and sealed; the steps behind it are what you
+judge, exactly as above. Do not read the feature's implementation: whether the
+code is right is the run's question, and the run was made by the connector.
+
 ## What is not yours
 
 **Do not edit the suite.** Not the `.feature` files, not the step definitions,