unitbob 0.5.0 → 0.5.1

package/dist/runner/bdd.js

@@ -22,33 +22,96 @@ export const BDD_RUN_ARTIFACTS = [
     PYTEST_BDD_PLUGIN_NAME,
     PYTEST_INI_NAME,
 ];
+// One name for the directory every strategy points its loader at, so the
+// descriptors below and the commands below them cannot come to mean different
+// directories.
+const STEP_DEFINITIONS = 'step_definitions';
 const CUCUMBER_REPORT = join(BEHAVIORAL_ROOT, CUCUMBER_REPORT_NAME);
 const PYTEST_BDD_REPORT = join(BEHAVIORAL_ROOT, PYTEST_BDD_REPORT_NAME);
 const PYTEST_BDD_PLUGIN_FILE = join(BEHAVIORAL_ROOT, PYTEST_BDD_PLUGIN_NAME);
 const PYTEST_INI_FILE = join(BEHAVIORAL_ROOT, PYTEST_INI_NAME);
 const PYTEST_INI = '[pytest]\naddopts =\n';
+// Load order is a fact about both Cucumbers and about neither pytest — pytest
+// picks `conftest.py` up itself, so there is no trap to work around there.
+const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file is not special to the runner — `account_access` ' +
+    'loads before `shared`. Open each capability file with an explicit require of the shared one rather ' +
+    'than trusting the alphabet.';
 // The connector-owned BDD strategy table (spec 32): the `runner` enum names one
 // of these; the connector never executes a host-provided command string. Each
 // strategy runs the whole behavioral bundle and returns the raw machine-readable
 // report verbatim — the connector does no marker join and no aggregation.
+//
+// A strategy is its command *and* its loading rule. They are one entry so that a
+// fourth runner cannot be added with only half of itself stated.
+const BDD_STRATEGIES = {
+    cucumber: {
+        run: (projectRoot) => runCucumberRuby(projectRoot),
+        loading: {
+            step_files: '*.rb',
+            requirements: [
+                'The connector points `--require` at `step_definitions/`, so every `.rb` file there is loaded. ' +
+                    'That explicit `--require` also switches off Cucumber\'s automatic loading of `features/support/`: ' +
+                    'a World or helper parked there is never evaluated, and every step then fails on a bare object.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'cucumber-js': {
+        run: (projectRoot) => runCucumberJs(projectRoot),
+        loading: {
+            step_files: '*.js',
+            requirements: [
+                'Keep `step_definitions/` to CommonJS JavaScript and nothing else. The connector passes the whole ' +
+                    'directory to `--require`, and cucumber-js `require()`s every file it matches whatever the ' +
+                    'extension — a stray `.ts`, `.json` or `.md` left there is executed as JavaScript and aborts the ' +
+                    'entire run with a parse error, before a single scenario.',
+                'The connector registers no TypeScript loader, so a `.ts` file cannot compile itself. If you want ' +
+                    'one, register the compiler from the file that sorts first — and remember the file registering it ' +
+                    'is itself loaded as plain JavaScript.',
+                CUCUMBER_LOAD_ORDER,
+            ],
+        },
+    },
+    'pytest-bdd': {
+        run: (projectRoot, mainPath) => runPytestBdd(projectRoot, mainPath),
+        loading: {
+            step_files: 'test_*.py',
+            requirements: [
+                'pytest collects `step_definitions/` under its own default, which is `test_*.py` and `*_test.py`. ' +
+                    'The connector writes no `python_files` setting and will not: a file named outside those two — ' +
+                    '`<capability>_steps.py`, say — is simply not collected. No error, no scenarios, a green run ' +
+                    'over nothing.',
+                '`conftest.py` is picked up by pytest itself whatever else sits beside it, so shared fixtures ' +
+                    'belong there and there is no load-order trap to work around.',
+            ],
+        },
+    },
+};
 export function runBddSuite(projectRoot, runner, mainPath) {
-    switch (runner) {
-        case 'cucumber':
-            return runCucumberRuby(projectRoot);
-        case 'cucumber-js':
-            return runCucumberJs(projectRoot);
-        case 'pytest-bdd':
-            return runPytestBdd(projectRoot, mainPath);
-        default:
-            return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
+    const strategy = strategyFor(runner);
+    if (!strategy) {
+        return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
     }
+    return strategy.run(projectRoot, mainPath);
+}
+// How this runner loads step files, for whoever has to write one. Null for a
+// runner this connector does not run, which is the same answer `runBddSuite`
+// gives it.
+export function bddStepLoading(runner) {
+    return strategyFor(runner)?.loading ?? null;
+}
+// `Object.hasOwn` rather than a bare index: the runner name arrives over the
+// wire, and `constructor` would otherwise come back as a truthy strategy with no
+// `run` on it.
+function strategyFor(runner) {
+    return Object.hasOwn(BDD_STRATEGIES, runner) ? BDD_STRATEGIES[runner] : null;
 }
 // Ruby: `cucumber` with the built-in message formatter. The features and step
 // definitions both live under the behavioral root; --require points at the step
 // definitions so only the Unitbob bundle loads.
 async function runCucumberRuby(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
     if (!existsSync(sidecarGemfile)) {
         throw missingRunner('Cucumber');
@@ -75,7 +138,7 @@ function missingRunner(name) {
 // to a file.
 async function runCucumberJs(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
-    const steps = join(BEHAVIORAL_ROOT, 'step_definitions', '**', '*');
+    const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
     const sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
     if (!executable(sidecarBin)) {
         throw missingRunner('Cucumber JS');
@@ -103,7 +166,7 @@ async function runPytestBdd(projectRoot, mainPath) {
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
     writeFileSync(join(projectRoot, PYTEST_BDD_PLUGIN_FILE), PYTEST_BDD_PLUGIN);
     const command = await pickPython(projectRoot);
-    const stepsDir = join(BEHAVIORAL_ROOT, 'step_definitions');
+    const stepsDir = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const isVenvPytest = command.endsWith('/pytest');
     const args = isVenvPytest
         ? ['-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', projectRoot]

package/dist/verbs/codexInstall.js

@@ -2,27 +2,62 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
+// The four named roles, in one place. Everything that counts them counts this
+// list — see the message at the bottom, which used to carry the number as a
+// literal and spent a release saying "Installed 3" beside four names.
+export const AGENT_NAMES = ['suite-worker', 'suite-repair-worker', 'fact-finder', 'suite-reviewer'];
 const bundledAgentsDir = fileURLToPath(new URL('../../plugin/codex/agents/', import.meta.url));
+const LABEL = {
+    created: 'created:        ',
+    updated: 'updated:        ',
+    current: 'already current:',
+};
+// Install (or refresh) the bounded Codex role definitions in the user's agent
+// directory.
+//
+// This used to refuse when an installed file differed from the bundled one, to
+// protect a definition the user had edited by hand. The case it actually met was
+// the ordinary one: an upgrade from an older release, where every file differs
+// and every install therefore failed. Spec 43, §1.6.
+//
+// The refusal became actively harmful once the workflows started asking a role
+// whether this session can see it. A stale role answers that question exactly
+// like a current one, so an update nobody could apply reads as "fully equipped"
+// — the check would pass and the run would proceed on last release's
+// instructions. So the file is overwritten, and what changed is said out loud
+// rather than left for the user to discover.
 export function installCodexAgents(args, deps = { home: homedir(), stdout: process.stdout }) {
     if (args.length > 0)
         throw new Error('codex-install accepts no arguments.');
     const targetDir = join(deps.home, '.codex', 'agents');
-    const files = AGENT_NAMES.map((name) => ({
-        source: join(bundledAgentsDir, `${name}.toml`),
-        target: join(targetDir, `${name}.toml`),
-    }));
-    for (const file of files) {
-        if (!existsSync(file.target))
-            continue;
-        if (readFileSync(file.target, 'utf8') === readFileSync(file.source, 'utf8'))
-            continue;
-        throw new Error(`Refusing to overwrite existing Codex agent definition: ${file.target}`);
-    }
     mkdirSync(targetDir, { recursive: true });
-    for (const file of files) {
-        if (!existsSync(file.target))
-            copyFileSync(file.source, file.target);
+    const byOutcome = { created: [], updated: [], current: [] };
+    for (const name of AGENT_NAMES) {
+        const source = join(bundledAgentsDir, `${name}.toml`);
+        const target = join(targetDir, `${name}.toml`);
+        const outcome = outcomeFor(source, target);
+        if (outcome !== 'current')
+            copyFileSync(source, target);
+        byOutcome[outcome].push(`${name}.toml`);
     }
-    deps.stdout.write(`Installed 3 Unitbob Codex agent definitions in ${targetDir}. Start a new Codex thread before running Unitbob.\n`);
+    const changes = ['created', 'updated', 'current']
+        .filter((outcome) => byOutcome[outcome].length > 0)
+        .map((outcome) => `  ${LABEL[outcome]} ${byOutcome[outcome].join(', ')}`);
+    // The reason is attached only when something actually changed, and it is
+    // worded to be true of both ways it can change. "A thread open before these
+    // files existed" is true of a first install and false of an upgrade, where the
+    // files did exist — and the upgrade is the case that matters most, because a
+    // thread holding last release's definition answers a readiness check exactly
+    // like a current one.
+    const changed = byOutcome.created.length + byOutcome.updated.length > 0;
+    const why = changed
+        ? ' — a thread already open is running the definitions it read when it started, not these'
+        : '';
+    deps.stdout.write(`${AGENT_NAMES.length} Unitbob Codex agent definitions in ${targetDir}:\n${changes.join('\n')}\n` +
+        `Start a new Codex thread before running Unitbob${why}.\n`);
+}
+function outcomeFor(source, target) {
+    if (!existsSync(target))
+        return 'created';
+    return readFileSync(target, 'utf8') === readFileSync(source, 'utf8') ? 'current' : 'updated';
 }

package/dist/verbs/suitePrepare.js

@@ -2,6 +2,7 @@ import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
+import { bddStepLoading } from "../runner/bdd.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
 import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
@@ -156,6 +157,11 @@ export async function suitePrepare(config, args = [], deps) {
         const manifest = actual.runnerEnvelope(packet, runner, config.projectRoot);
         if (!manifest)
             return { packet, runner, branch: null };
+        // Spec 43, §3.2. The rule for which step files this runner loads travels
+        // with the branch that will be written against it, so nobody has to read
+        // the connector's own source to find it out — which is exactly what two
+        // coordinators did.
+        const stepLoading = packet.suite_kind === 'behavioral' && runner ? bddStepLoading(runner) : null;
         return {
             packet,
             runner,
@@ -166,6 +172,7 @@ export async function suitePrepare(config, args = [], deps) {
                 recipe: await actual.getRecipe(recipeNameFor(packet)),
                 assignment: packet.assignment,
                 runner_manifest: manifest,
+                ...(stepLoading ? { step_loading: stepLoading } : {}),
             },
         };
     }));
@@ -200,6 +207,22 @@ export async function suitePrepare(config, args = [], deps) {
         `finish says so in its own entry rather than being left out of the array. Run each locally with \`unitbob run-local\` (the same ` +
         `runner that runs after publishing, so you never have to guess the command), repair broken harness steps while application failures remain red, ` +
         `then run ${nextCommand}.\n`);
+    // Printed as well as written, because a rule nobody reads is a rule nobody
+    // follows — and this one is silent when broken: a step file the runner does
+    // not collect produces no error, only a green run over no scenarios.
+    for (const { packet, runner, branch } of prepared) {
+        if (!branch || packet.suite_kind !== 'behavioral' || !runner)
+            continue;
+        actual.stdout.write(branch.step_loading
+            ? stepLoadingNotice(runner, branch.step_loading)
+            // Said rather than left blank. This connector has no strategy for that
+            // runner, so it does not know which files it loads — and silence here
+            // reads as "any name will do", which is the failure this whole notice
+            // exists to prevent.
+            : `\nBehavioral steps run under "${runner}", and this connector does not know how that runner ` +
+                'finds its step files — it has no strategy of that name. Nothing here tells you what to call ' +
+                'them, and this connector will not be able to run the branch either.\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) {
@@ -221,6 +244,24 @@ export async function suitePrepare(config, args = [], deps) {
             '\n');
     }
 }
+// The runner's own rule for which step files it will load, in the words of the
+// side that loads them (spec 43, §3.2). The same object is in `request.json`, on
+// the behavioral branch; this is the copy the coordinator sees without opening a
+// file.
+//
+// A null pattern is printed as a null pattern. A runner whose rule is not one
+// pattern says what it does know and admits the rest — inventing a pattern here
+// would recreate, in the connector this time, exactly the retelling this
+// replaced.
+function stepLoadingNotice(runner, loading) {
+    const rule = loading.step_files
+        ? `it loads \`${loading.step_files}\` from \`.unitbob/behavioral/step_definitions/\` — put the capability id ` +
+            'where the `*` is, and a file named anything else is not loaded at all'
+        : 'its rule for which files it loads is not one pattern, and this connector will not state one for it';
+    return (`\nBehavioral steps run under "${runner}", and ${rule}. What else has to be true of a step file there:\n  - ` +
+        loading.requirements.join('\n  - ') +
+        '\nThis is also in `request.json`, on the behavioral branch, as `step_loading`.\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

package/package.json

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