unitbob 0.7.3 → 0.7.4

package/dist/runner/vitest.js

@@ -16,6 +16,56 @@ export const VITEST_CONFIG_FILE = join('.unitbob', 'vitest.config.mjs');
 // and is rewritten immediately before every run, so a boot check that reused it
 // would either be overwritten or leave the run pointing at a probe.
 export const VITEST_BOOT_CONFIG_FILE = join('.unitbob', 'vitest.boot.config.mjs');
+// The structural branch's one shared setup file (spec 39). The coordinator
+// writes it before fan-out and owns it afterwards: it holds whatever has to
+// happen before the first import of any file of the branch — environment
+// variables, a TypeScript loader registration, at the very last resort an entry
+// through the project's root module.
+//
+// A fixed name rather than a new protocol field, because the file has to survive
+// the round trip: `materializeGuardrails` wipes this directory and lays the
+// artifact out again, so the file must travel as an ordinary `support_files`
+// entry — and every such entry is otherwise handed to the runner as a test path.
+// One constant here, read by the config builder, by both collectors of test
+// paths, and by `suite-prepare`, is the whole of the agreement. A field would
+// have had to be agreed with the server and both of its version models.
+//
+// One name, one extension. A second one buys nothing: vitest puts every setup
+// file through vite, so `require` is undefined in a `.js` setup file just as it
+// is in a `.ts` one.
+export const STRUCTURAL_SETUP_FILE = '.unitbob/structural/_setup.ts';
+// The project-relative path of that file, or `undefined` when it has not been
+// written yet. Two callers, one question: the config builder asks it to decide
+// whether to name the file in `setupFiles`, and `suite-prepare` asks it to
+// decide whether the boot probe is a scout or a sentry (spec 39, criterion 4).
+// Deliberately the same observable fact for both, rather than a flag — 32-6
+// forbids a mode, and a mode would let the two sides disagree about which run
+// they are in.
+export function setupFileOf(projectRoot) {
+    return existsSync(join(projectRoot, STRUCTURAL_SETUP_FILE)) ? STRUCTURAL_SETUP_FILE : undefined;
+}
+// Whether anything of ours can run before this stack's branch imports its first
+// module. Only vitest, because `setupFiles` is a vitest notion and the builder
+// below is the single place that inserts our file. Kept here, beside the
+// insertion it describes, rather than in the verb that asks: the verb would be
+// stating a fact about a module it does not own, and the two could then drift.
+export function canPrepareBeforeImports(runner) {
+    return runner === 'vitest';
+}
+// The files of an artifact that a runner may be pointed at, which is all of them
+// except the shared setup file. It travels as an ordinary `support_files` entry
+// so that materialization writes it back rather than wiping it, and it holds no
+// cases at all: a runner given it as a test path opens it, finds nothing, and
+// reports that nothing as a suite.
+//
+// One filter for both collectors — the check flow's and run-local's — because
+// the two must never disagree about which file this is. A leading `./` is
+// tolerated: the answer that names the file is hand-written, and two characters
+// must not be what decides whether the branch's preparation is executed or
+// collected.
+export function testPathsOf(paths) {
+    return paths.filter((path) => path.replace(/^\.\//, '') !== STRUCTURAL_SETUP_FILE);
+}
 // The project configs we inherit from, most specific first. Vitest reads a
 // project's own config even when we pass `--config`, so we must merge ours with
 // it rather than replace it (plugins, path aliases and resolve settings the
@@ -87,7 +137,7 @@ export async function runVitestSuite(projectRoot, suitePaths) {
 function writeMergedConfig(projectRoot, suitePaths) {
     const path = join(projectRoot, VITEST_CONFIG_FILE);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run'));
+    writeFileSync(path, configSource(projectConfigOf(projectRoot), suitePaths, 'run', setupFileOf(projectRoot)));
     return ['--config', VITEST_CONFIG_FILE];
 }
 // The same config, shaped for the boot check's probe (spec 38). Returned as text
@@ -95,7 +145,12 @@ function writeMergedConfig(projectRoot, suitePaths) {
 // puts in the project: it writes them together and removes them together, and a
 // writer here would take half of that away from the one place that can see it.
 export function vitestBootConfigSource(projectRoot, probePath) {
-    return configSource(projectConfigOf(projectRoot), [probePath], 'boot');
+    // The same preparation the run will get, which is the point of asking twice
+    // (spec 39, criterion 4). On the first `suite-prepare` there is no setup file
+    // and the probe answers "these files do not load on their own"; on the second,
+    // after the coordinator wrote one, it answers the question the run will
+    // actually put — and only then is a red answer worth a branch.
+    return configSource(projectConfigOf(projectRoot), [probePath], 'boot', setupFileOf(projectRoot));
 }
 function projectConfigOf(projectRoot) {
     return PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
@@ -118,13 +173,25 @@ function projectConfigOf(projectRoot) {
 // and `defineConfig` is a typing helper that buys a generated file nothing.
 // `mode` is the boot check's two differences from the run, and they go together:
 // globals on, and a workspace refused. See `vitestBootConfigSource`.
-function configSource(projectConfig, suitePaths, mode) {
+//
+// `setupFiles` is the one field that is added to rather than replaced (spec 39,
+// criterion 2). The project's own entry is what raises its test database and
+// reads its environment — epic-stack's `tests/setup/setup-test-env.ts` is why
+// its 50 structural checks have a database to read — and replacing it would
+// take that away from the only structural suite on the bench that works. Ours
+// goes first: it exists to set things up before the first import of anything,
+// and the project's own setup file opens with imports of the application.
+function configSource(projectConfig, suitePaths, mode, setupFile) {
     // After the project's own `test`, never before it: ours has to win.
-    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}include: ${JSON.stringify(suitePaths)}`;
+    const settings = `${mode === 'boot' ? 'globals: true, ' : ''}${setupFile ? 'setupFiles, ' : ''}include: ${JSON.stringify(suitePaths)}`;
     const header = '// Written by the unitbob connector before each vitest run — do not edit.';
     if (!projectConfig) {
+        // Nothing to inherit, so nothing to concatenate — but the shared file is
+        // still the branch's, and a project with no config of its own is exactly
+        // the kind that needs it.
+        const alone = setupFile ? `const setupFiles = ${JSON.stringify([setupFile])};\n` : '';
         return `${header}
-export default { test: { ${settings} } };
+${alone}export default { test: { ${settings} } };
 `;
     }
     // Globals, because the probe lives in `.unitbob/structural/`: an
@@ -144,13 +211,20 @@ const { projects, workspace, ...test } = base.test ?? {};
         : `
 const test = base.test ?? {};
 `;
+    // `[].concat(x)` on purpose: vitest accepts `setupFiles` as an array or as a
+    // bare string, and most projects set neither. All three forms arrive here and
+    // all three have to come out an array, because a config that throws while it
+    // is being read takes the whole run with it.
+    const merge = setupFile
+        ? `const setupFiles = ${JSON.stringify([setupFile])}.concat(test.setupFiles ?? []);\n`
+        : '';
     return `${header}
 import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
 
 const base = typeof projectConfig === 'function'
   ? await projectConfig({ command: 'serve', mode: 'test' })
   : projectConfig;
-${narrow}
+${narrow}${merge}
 export default { ...base, test: { ...test, ${settings} } };
 `;
 }

package/dist/verbs/run.js

@@ -4,7 +4,7 @@ import { placeProblem } from "../runner/place.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
-import { runVitestSuite } from "../runner/vitest.js";
+import { runVitestSuite, testPathsOf } from "../runner/vitest.js";
 import { runPytestSuite } from "../runner/pytest.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { enterUrl } from "../links.js";
@@ -147,8 +147,11 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
 // Every file of the branch, in the order the envelope carries them. A structural
 // branch is one file per assignment since spec one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
+//
+// Every file except the branch's shared setup file, which `testPathsOf` drops
+// (spec 39): it is named in `setupFiles` instead of being collected from.
 function artifactPaths(file) {
-    return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];
+    return testPathsOf([file.path, ...(file.support_files ?? []).map((entry) => entry.path)]);
 }
 function suiteError(suiteDigest, message) {
     return {

package/dist/verbs/runLocal.js

@@ -5,6 +5,7 @@ import { placeAdvice } from "../runner/placeAdvice.js";
 import { runnerEnvironmentPlaceProblem } from "../runner/placeEnvironment.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
+import { testPathsOf } from "../runner/vitest.js";
 import { runStructuralByRunner } from "./run.js";
 const OUTPUT_TAIL_CHARS = 4000;
 export async function runLocal(config, args = [], deps) {
@@ -259,7 +260,11 @@ function artifactPathsOf(output) {
     const rest = support
         .map((entry) => entry?.path)
         .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
-    return [path, ...rest];
+    // Everything but the branch's shared setup file (spec 39): it is a support
+    // file so that it survives materialization, and it is named in `setupFiles`
+    // rather than handed over as a path to collect tests from. Literally the same
+    // filter the check flow uses, because both sides have to mean the one file.
+    return testPathsOf([path, ...rest]);
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -11,6 +11,7 @@ import { placeProblem } from "../runner/place.js";
 import { alignRunnerEnvironmentWithPlace } from "../runner/placeEnvironment.js";
 import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { ToolchainUnavailableError } from "../runner/toolchain.js";
+import { canPrepareBeforeImports, setupFileOf, STRUCTURAL_SETUP_FILE } from "../runner/vitest.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -225,13 +226,52 @@ export async function suitePrepare(config, args = [], deps) {
     // and boots the application for itself, so asking with no structural branch in
     // the run would start Rails to answer a question nobody put — and a `broken`
     // answer would then report a branch this build never had.
+    //
+    // Spec 39 kept the sentry and moved the sentence. The probe asks its question
+    // twice: once before anything has been prepared for these files, and once
+    // after the coordinator has written the branch's shared setup file. Only the
+    // second answer costs a branch, because only the second one asks what the run
+    // will ask. Before the setup file exists the probe's question — "do these
+    // files load with nothing in front of them" — is stricter than the condition
+    // it stands in for, and `docs/adr/0001` forbids exactly that: the condition
+    // tested must equal the condition that makes a run impossible, never exceed
+    // it. Two bench projects were refused on that excess while their behavioral
+    // peers built and stayed green.
+    //
+    // The switch is the file on disk and nothing else. No flag and no mode: 32-6
+    // forbade them, and the connector has to ask this same question anyway to
+    // decide whether to name the file in `setupFiles`, so a second signal could
+    // only ever disagree with the first.
+    //
+    // And only on the stack where a preparation can actually be put in front of
+    // the imports — `canPrepareBeforeImports`, which is vitest and only vitest. On
+    // rspec and pytest nothing of ours runs before the branch's imports, so there
+    // the probe's question already *is* the run's question: no excess to correct,
+    // and a red answer costs the branch on the first run exactly as it has since
+    // 32-6. Waiting for a file those stacks will never have would have quietly
+    // reopened the funnel that spec closed.
+    //
+    // One thing this sign cannot see: a setup file left over from an earlier
+    // build. It comes back with the artifact and is materialized like any other
+    // file of the branch, so on a re-generation the probe sentences on its first
+    // ask instead of scouting. That is the honest reading — a preparation does
+    // exist and the probe went through it — and the way out is the same one the
+    // verdict already names: fix that file, run `suite-prepare` again. Telling the
+    // two apart would need a memory of which build wrote it, which is a mode by
+    // another name, and 32-6 forbade those.
     const bootNotices = [];
+    const bootAdvisories = [];
     const structuralIndex = branches.findIndex((branch) => branch.suite_kind === 'structural');
     if (structuralIndex !== -1) {
         const boot = await actual.bootCheck(config.projectRoot, structuralRunner, structuralSourceFiles(config.projectRoot, { branches }));
         if (boot.status === 'broken') {
-            branches.splice(structuralIndex, 1);
-            bootNotices.push(bootStop(boot, structuralRunner));
+            if (!canPrepareBeforeImports(structuralRunner) || setupFileOf(config.projectRoot)) {
+                branches.splice(structuralIndex, 1);
+                bootNotices.push(bootStop(boot, structuralRunner));
+            }
+            else {
+                bootAdvisories.push(bootAdvisory(boot, structuralRunner));
+            }
         }
         else {
             actual.stdout.write(bootFinding(boot, structuralRunner));
@@ -330,6 +370,18 @@ export async function suitePrepare(config, args = [], deps) {
             bootNotices.join('\n') +
             '\n');
     }
+    // The other half of the probe's answer (spec 39), and it needs a heading of
+    // its own: "was left out of this run" is true only of the verdict, and this
+    // branch was not left out of anything. It is being built, and what follows is
+    // the opening fact for whoever writes its preparation.
+    if (bootAdvisories.length > 0) {
+        actual.stdout.write('\nThe code-structure suite is still being built, and here is what its source files did on their own: ' +
+            `they did not load. Nothing has been put in front of them yet — that is what ${STRUCTURAL_SETUP_FILE} ` +
+            'is for, and writing it comes before the fan-out. None of your own tests were opened; only the files ' +
+            'the map named:\n' +
+            bootAdvisories.join('\n') +
+            '\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) {
@@ -434,16 +486,42 @@ function bootFinding(boot, runner) {
 // its peer carries on, `request.json` is written, and the vibecoder comes away
 // with the guardrails that branch can still give rather than with nothing.
 //
+// Reached only once the branch's shared setup file exists (spec 39). By then the
+// probe has been asked through that preparation, so a red answer is the run's
+// own answer and taking the branch is honest.
+function bootStop(boot, runner) {
+    return bootReport(boot, runner, true);
+}
+// The same red answer, read before anything was prepared for these files (spec
+// 39). Same facts, same words from the runner, same caveat — what differs is
+// the step that follows, and that is the whole difference between a scout and a
+// sentry. Nothing here is worded as a verdict on somebody's code, because on
+// this run it is not one: the files were asked to load with nothing in front of
+// them, and putting something in front of them is Unitbob's own work.
+function bootAdvisory(boot, runner) {
+    return bootReport(boot, runner, false);
+}
 // The two causes keep their separate next steps. An un-run `pip install` is not
 // somebody's bug and must not be worded as one; a module of theirs that raises
-// on import is theirs to fix and pointing at an install would waste their time.
-function bootStop(boot, runner) {
-    const next = boot.cause === 'defect_in_code'
-        ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
-        : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+// on import, asked with the preparation already in place, is theirs to fix and
+// pointing at an install would waste their time.
+//
+// The environment cause keeps the same next step in both reports: a missing gem
+// is not something a setup file can prepare its way around, and sending someone
+// to write one would waste the round it costs.
+function bootReport(boot, runner, prepared) {
+    const next = boot.cause !== 'defect_in_code'
+        ? '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.';
+            'then run `unitbob suite-prepare` again.'
+        : prepared
+            ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
+            : `This is what these files do with nothing in front of them, and the run will have ` +
+                `${STRUCTURAL_SETUP_FILE} in front of them. Put into that file whatever has to happen before the ` +
+                'first import — the environment variables the modules read, a loader registration, and only as a ' +
+                'last resort an entry through the project\'s root module — then run `unitbob suite-prepare` again ' +
+                'and this same question will be asked through it.';
     // `boot.message` is the runner's own words, indented but never paraphrased:
     // this is the line the vibecoder can paste into a search.
     return `  ${boot.message}\n\n${boot.detail}\n\n  ${next}${caveatFor(runner, '  ')}\n`;

package/package.json

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