unitbob 0.7.15 → 0.7.16

package/README.md

@@ -35,7 +35,7 @@ Codex:
 ```
 codex plugin marketplace add sergeygershun/unitbob-connector
 codex plugin add unitbob@unitbob
-npx -y unitbob@0.7.15 codex-install
+npx -y unitbob@0.7.16 codex-install
 ```
 
 Then start a new chat. A chat opened before the install does not know about

package/dist/files/behavioral.js

@@ -217,6 +217,10 @@ net.Socket.prototype.connect = function unitbobGuardedConnect(...args) {
 // database. Those stay in host-owned shared steps, as on every other stack.
 // The one thing this file says about the database is "no": a `DATABASE_URL`
 // whose database is not named like a test one does not get a door.
+// How long the World gives Next to come up in `BeforeAll`: a cold `.next` on
+// a large application compiles for a while. One constant, read by the probe
+// too, so the probe's clock can never be the shorter one (ADR 0001).
+export const NEXT_WORLD_BOOT_TIMEOUT_MS = 180_000;
 const NEXT_DOOR_JS = `
 // ---------------------------------------------------------------------------
 // The door into this Next.js application (spec 56-1).
@@ -276,7 +280,7 @@ function unitbobDatabaseName(url) {
   }
 }
 
-BeforeAll({ timeout: 180000 }, async function () {
+BeforeAll({ timeout: ${NEXT_WORLD_BOOT_TIMEOUT_MS} }, async function () {
   // The runner already sets NODE_ENV=test; kept here so Next reads .env.test
   // even when this file is loaded some other way.
   process.env.NODE_ENV = process.env.NODE_ENV || 'test';

package/dist/files/workerPlan.js

@@ -73,9 +73,11 @@ export function assignedSurfaces(projectRoot) {
 }
 // Spec 55-1, §4. The marker the request minted for each capability and each
 // structural interface, by id — the `@ubc_…` tag a Scenario must carry and the
-// `[ubc_…]` a structural test names. This is the one reader of markers in
-// `src/`, and it answers one question: which markers were this slice's. What a
-// marker *means* on the map is the server's, and nothing here goes near it.
+// `[ubc_…]` a structural test names. This reads them off the request and
+// answers one question: which markers were this slice's (the verb then finds
+// them in the slice's files, `runner/failureDigest.ts` in a run report — both
+// by the same 12-hex shape). What a marker *means* on the map is the server's,
+// and nothing here goes near it.
 export function assignedMarkers(projectRoot) {
     const request = readRequest(projectRoot);
     const byId = new Map();

package/dist/runner/bootcheck.js

@@ -380,10 +380,12 @@ function classify(projectRoot, runner, result, verdict) {
     return { status: 'broken', cause: causeOf(output, projectRoot, runner), message, detail };
 }
 // Spec 55-1, §1. Vite's import-analysis stopped on a file this runner has no
-// reading of — a `.py` the map named, say. That file got to vite through our
-// list and nowhere else, so the answer is about the list. Only vite says this;
-// the other runners never see such a file (their probes skip it) and their
-// parse errors mean what they say.
+// reading of — a `.py` the map named, say. The probe imports only runner files
+// (`vitestProbeSource`), so such a file reaches vite either through the list
+// before that filter existed or through the project's own import of it; in
+// both cases the answer names the file, and the second is a defect the message
+// still points at. Only vite says this; the other runners never see such a
+// file (their probes skip it) and their parse errors mean what they say.
 const FOREIGN_PARSE = /vite:import-analysis|Failed to parse source for import analysis/;
 const REPORTED_FILE = /^\s*File:\s*(\S+?)(?::\d+)*\s*$/m;
 function foreignFileParsed(output, projectRoot, runner) {

package/dist/runner/worldProbe.js

@@ -1,6 +1,6 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { BEHAVIORAL_DIR, BEHAVIORAL_WORLD_JS_PATH, BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
+import { BEHAVIORAL_DIR, BEHAVIORAL_WORLD_JS_PATH, BEHAVIORAL_WORLD_PATH, NEXT_WORLD_BOOT_TIMEOUT_MS } from "../files/behavioral.js";
 import { BEHAVIORAL_GEMFILE } from "./bdd.js";
 import { firstErrorLine } from "./bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
@@ -8,8 +8,14 @@ import { PROVISION_TIMEOUT_MS } from "./provision.js";
 import { looksLikeNext } from "../surfaces/nextRoutes.js";
 const PROBE_ROOT = '.unitbob/suite-build/world-probe';
 const defaultDeps = {
-    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: PROVISION_TIMEOUT_MS }),
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: options.timeoutMs ?? PROVISION_TIMEOUT_MS }),
 };
+// What both probes leave to the run itself, said with every `ok`. The probe
+// loads the connector's World and its own two or three steps; the project's
+// `step_definitions/` — and any `Before` hook a coordinator writes there — are
+// first loaded by the suite. So a green probe means the door opens, not that
+// every hook behind it is sound.
+const LEFT_TO_THE_RUN = "It ran the connector's own steps only; your step_definitions/ and the hooks in them are first loaded by the suite itself.";
 // Which Worlds are probed by running them: the ones that open a door into the
 // application — Ruby's, which integrates with Rails, and Next's, which starts
 // the application (spec 56-1). A harness that only guards the network
@@ -49,7 +55,7 @@ export async function probeBehavioralWorld(projectRoot, deps = defaultDeps) {
             },
         });
         if (result.code === 0)
-            return { status: 'ok' };
+            return { status: 'ok', message: LEFT_TO_THE_RUN };
         const detail = [result.stdout, result.stderr].map((text) => text.trim()).filter(Boolean).join('\n') || `exit ${result.code}`;
         return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe failed: ${detail}` };
     }
@@ -90,9 +96,13 @@ export async function probeNextWorld(projectRoot, deps = defaultDeps) {
                 CUCUMBER_PUBLISH_QUIET: 'true',
                 UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
             },
+            // The run gives `BeforeAll` this long to start Next (ADR 0001: the probe
+            // may be looser than the run, never stricter), plus one request through
+            // the door once it is open.
+            timeoutMs: NEXT_WORLD_BOOT_TIMEOUT_MS + PROVISION_TIMEOUT_MS,
         });
         if (result.code === 0)
-            return { status: 'ok' };
+            return { status: 'ok', message: LEFT_TO_THE_RUN };
         // cucumber-js opens every run on a Node it has not been tested with by
         // saying so; that line is not the error and must not be quoted as one.
         const lines = [result.stdout, result.stderr]

package/dist/surfaces/nextRoutes.js

@@ -39,38 +39,40 @@ export function nextGate(projectRoot) {
 }
 const PAGE_FILE = /^page\.(tsx|jsx|js|ts)$/;
 const ROUTE_FILE = /^route\.(tsx|jsx|js|ts)$/;
-// Every address under the app directory, sorted by path so the inventory reads
-// like a route table rather than like a directory listing. Files are named
-// relative to the project root with forward slashes, which is how the graph
-// names them too.
 export function nextAppRoutes(projectRoot) {
     const appDir = nextAppDir(projectRoot);
+    const routing = { rows: [], unread: [] };
     if (!appDir)
-        return [];
-    const rows = [];
-    walk(join(projectRoot, appDir), appDir.split(/[\\/]/).join('/'), [], rows);
-    return rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        return routing;
+    walk(join(projectRoot, appDir), appDir.split(/[\\/]/).join('/'), [], routing);
+    routing.rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return routing;
 }
-function walk(dir, relative, segments, rows) {
+function walk(dir, relative, segments, routing) {
     const path = urlOfSegments(segments);
     // A subtree with no URL has no addresses anywhere below it.
     if (path === null)
         return;
     for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
         if (entry.isDirectory()) {
-            walk(join(dir, entry.name), `${relative}/${entry.name}`, [...segments, entry.name], rows);
+            walk(join(dir, entry.name), `${relative}/${entry.name}`, [...segments, entry.name], routing);
             continue;
         }
         if (!entry.isFile())
             continue;
         const file = `${relative}/${entry.name}`;
         if (PAGE_FILE.test(entry.name)) {
-            rows.push({ verb: 'GET', path, file, method: 'default' });
+            routing.rows.push({ verb: 'GET', path, file, method: 'default' });
         }
         else if (ROUTE_FILE.test(entry.name)) {
-            for (const verb of exportedHttpMethods(readFileSync(join(dir, entry.name), 'utf8'))) {
-                rows.push({ verb, path, file, method: verb });
-            }
+            const text = readFileSync(join(dir, entry.name), 'utf8');
+            const verbs = exportedHttpMethods(text);
+            for (const verb of verbs)
+                routing.rows.push({ verb, path, file, method: verb });
+            // Whatever it declares itself, a file that re-exports has addresses this
+            // reading cannot see; the model finds them in the graph.
+            if (REEXPORTS_ALL.test(text))
+                routing.unread.push(file);
         }
     }
 }
@@ -107,9 +109,11 @@ const METHOD = HTTP_METHODS.join('|');
 //   export const { GET, POST } = handlers   (the Auth.js shape)
 //
 // Not read: `export * from './handlers'` — the file names no method, and
-// following the import would be a second module resolver. Such an address is
-// simply not in the inventory; the recipe says the model may still find it in
-// the graph, as it finds everything on a stack with no inventory at all.
+// following the import would be a second module resolver. Such a file goes to
+// `NextRouting.unread` instead, and the recipe tells the model to find its
+// addresses in the graph and name that file as their `source_file`; that is
+// the one address the inventory check accepts beyond the inventory.
+const REEXPORTS_ALL = /^\s*export\s+\*/m;
 const DECLARED = [
     new RegExp(`^\\s*export\\s+(?:async\\s+)?function\\s+(${METHOD})\\b`, 'gm'),
     new RegExp(`^\\s*export\\s+(?:const|let|var)\\s+(${METHOD})\\s*[=:]`, 'gm'),

package/dist/surfaces/routeInventory.js

@@ -52,7 +52,7 @@ async function askRailsRouter(projectRoot, deps) {
 // declaration. `gate` names the `proxy.ts`/`middleware.ts` every address goes
 // through — not an address itself, and the recipe says so.
 function readNextFiles(projectRoot) {
-    const rows = nextAppRoutes(projectRoot);
+    const { rows, unread } = nextAppRoutes(projectRoot);
     // An `app/` with no `page.*` or `route.*` declares nothing. As on Rails, we do
     // not claim "no addresses" for a reading that may simply have missed them.
     if (rows.length === 0)
@@ -60,7 +60,15 @@ function readNextFiles(projectRoot) {
     const nodes = graphNodes(projectRoot);
     const surfaces = rows.map((row) => toNextSurface(row, nodes));
     const gate = nextGate(projectRoot);
-    return writeInventory(projectRoot, { declared_by: 'next app router', environment: 'default', ...(gate ? { gate } : {}), surfaces }, 'files');
+    return writeInventory(projectRoot, {
+        declared_by: 'next app router',
+        environment: 'default',
+        ...(gate ? { gate } : {}),
+        // The files this reading could not see into (ADR 0001): named here so
+        // the sentence below and `inventoryProblems` both know the gap.
+        ...(unread.length > 0 ? { unread } : {}),
+        surfaces,
+    }, 'files');
 }
 // The inventory, and only the inventory. `surfaces.json` is not written here,
 // however tempting: the recipe turns this file into that one with a single
@@ -88,6 +96,7 @@ function writeInventory(projectRoot, document, source) {
         linked: document.surfaces.filter((surface) => surface.handler_symbol).length,
         environment: document.environment,
         source,
+        ...(document.unread ? { unread: document.unread.length } : {}),
     };
 }
 // One question, up to two environments. Everything that can be decided from the
@@ -152,7 +161,9 @@ export function describeRouteInventory(result) {
         return (`Route inventory written to ${result.path}: ${result.routes} ${plural(result.routes, 'address', 'addresses')} ` +
             `from the ${result.source === 'files' ? 'file system' : 'router'}` +
             `${result.source === 'router' && result.environment === 'default' ? ' (read in the default environment — ' +
-                'the test one would not load)' : ''}, ${result.linked} tied to a graph node. The extract_surfaces recipe turns ` +
+                'the test one would not load)' : ''}, ${result.linked} tied to a graph node` +
+            `${result.unread ? `; ${result.unread} route ${plural(result.unread, 'file re-exports its handlers and is', 'files re-export their handlers and are')} ` +
+                'listed under `unread` — their addresses are not in the inventory' : ''}. The extract_surfaces recipe turns ` +
             'this file into surfaces.json with one command, then adds the job, table and external surfaces to it.');
     }
     return `No route inventory: ${becauseOf(result)}. The extract_surfaces recipe reads the source instead.`;
@@ -162,7 +173,7 @@ export function describeRouteInventory(result) {
 function becauseOf(result) {
     switch (result.reason) {
         case 'unsupported_stack':
-            return 'this project has no router Unitbob can ask yet (Rails and the Next.js app router so far)';
+            return 'this project has no router Unitbob can ask yet (Rails and Next.js (app router) so far)';
         case 'app_did_not_load':
             return `the router could not be asked — ${result.detail}`;
         case 'did_not_finish':
@@ -403,22 +414,29 @@ function findNode(nodes, file, action) {
 export function inventoryProblems(inventory, surfaces) {
     const declared = routeEntriesIn(inventory);
     if (declared === null) {
-        return ['the route inventory is not readable, so what the router declared cannot be confirmed'];
+        return ['the route inventory is not readable, so what the application declared cannot be confirmed'];
     }
     const written = routeEntriesIn(surfaces);
     if (written === null)
         return ['surfaces.json has no readable `surfaces` array'];
     const problems = [];
     const missing = [...declared.keys()].filter((id) => !written.has(id));
-    const invented = [...written.keys()].filter((id) => !declared.has(id));
+    // ADR 0001: the check is no stricter than the inventory's own claim. A file
+    // the inventory lists under `unread` is one it could not see into, so an
+    // address served by that file is the model's to add — and only that one.
+    const unread = unreadFilesIn(inventory);
+    const invented = [...written.keys()].filter((id) => !declared.has(id) && !unread.has(written.get(id)?.source_file));
     if (missing.length > 0) {
-        problems.push(`surfaces.json is missing ${missing.length} address the router declared: ${list(missing)}. ` +
+        problems.push(`surfaces.json is missing ${missing.length} address the inventory declared: ${list(missing)}. ` +
             'Copy every entry of the route inventory across unchanged.');
     }
     if (invented.length > 0) {
-        problems.push(`surfaces.json carries ${invented.length} route the router never declared: ${list(invented)}. ` +
-            'The router is the authority on what exists; an address it does not know is either a typo ' +
-            'in a copied id or invented.');
+        problems.push(`surfaces.json carries ${invented.length} route the inventory does not declare: ${list(invented)}. ` +
+            'The inventory is what the application declared about itself — its router\'s answer, or its route ' +
+            'files; an address it does not know is either a typo in a copied id or invented.' +
+            (unread.size > 0
+                ? ' The one exception is an address served by a route file listed under `unread`, with that file as its `source_file`.'
+                : ''));
     }
     // Two sentences rather than one, because the two kinds of rewrite are not the
     // same mistake and the person reading has to fix the right thing: one sends a
@@ -432,7 +450,7 @@ export function inventoryProblems(inventory, surfaces) {
     const relabelled = alteredFields(declared, written, LABEL_FIELDS);
     if (relabelled.length > 0) {
         problems.push(`surfaces.json reworded ${relabelled.length} handler_label: ${list(relabelled)}. ` +
-            'That name is what the router itself printed; the human names for the map are the ' +
+            'That name is what the inventory itself printed; the human names for the map are the ' +
             'capability titles in the next step, not this field.');
     }
     return problems;
@@ -462,6 +480,12 @@ function alteredFields(declared, written, fields) {
     }
     return altered;
 }
+// The `unread` list of a Next.js inventory, as a set; empty on a router's
+// inventory, which has no such list because a router declares all it serves.
+function unreadFilesIn(inventory) {
+    const unread = inventory?.unread;
+    return new Set(Array.isArray(unread) ? unread.filter((file) => typeof file === 'string') : []);
+}
 function routeEntriesIn(document) {
     const surfaces = document?.surfaces;
     if (!Array.isArray(surfaces))

package/dist/verbs/putMapBuild.js

@@ -59,7 +59,7 @@ function refuseAlteredAddresses(inventoryPath, surfaces) {
     const problems = inventoryProblems(inventory, surfaces);
     if (problems.length === 0)
         return;
-    throw new Error(`The routes in surfaces.json do not match the ones this project's router declared, so nothing ` +
+    throw new Error(`The routes in surfaces.json do not match the ones this project declared (its router's answer, or its route files), so nothing ` +
         `was uploaded and the previous map stays current:\n- ${problems.join('\n- ')}`);
 }
 // Spec 32-7, Task 1.11. The addresses are now a command's answer rather than the

package/dist/verbs/suitePrepare.js

@@ -199,6 +199,9 @@ export async function suitePrepare(config, args = [], deps) {
                     fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
                     continue;
                 }
+                // ADR 0001: the probe's account of what it did not cover is part of
+                // the answer, printed with the good news rather than kept in a comment.
+                actual.stdout.write(`Checked that the connector-owned World profile works on this project: it does.${probe.message ? ` ${probe.message}` : ''}\n`);
             }
         }
         buildable.push({ packet, runner });

package/package.json

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