unitbob 0.1.8 → 0.1.9

package/README.md

@@ -3,6 +3,10 @@
 A living map of your app's business parts. Each important seam gets an automatic
 test — a "lamp" on the map. Green means fine, red means something broke.
 
+Works with Ruby on Rails (RSpec), JavaScript/TypeScript (Vitest), and Python
+(pytest) projects — the guardrail tests are generated in your project's own
+language and run with its native test runner.
+
 You work through Claude Code. You need: Node 18+, Python 3.10+.
 
 ---

package/dist/config.js

@@ -11,18 +11,29 @@ export const CONFIG_FILE = '.unitbob.json';
 // missing, unreadable, malformed JSON, or repo_id absent / 0 / non-integer
 // (the legacy init template wrote repo_id: 0). Callers re-link on null.
 export function readLocalRepoId(cwd) {
+    const repoId = readConfigField(cwd, 'repo_id');
+    return typeof repoId === 'number' && Number.isInteger(repoId) && repoId > 0 ? repoId : null;
+}
+// The server URL stored at `cwd`, or null when the file is missing, malformed,
+// or carries no usable http(s) URL. A local file naming a server must win over
+// the built-in default — otherwise a locally-linked project silently talks to
+// (and registers itself on) the public brain.
+export function readLocalServer(cwd) {
+    const server = readConfigField(cwd, 'server');
+    return typeof server === 'string' && /^https?:\/\//.test(server.trim()) ? server.trim() : null;
+}
+function readConfigField(cwd, field) {
     const path = join(cwd, CONFIG_FILE);
     if (!existsSync(path))
-        return null;
+        return undefined;
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(path, 'utf8'));
     }
     catch {
-        return null;
+        return undefined;
     }
-    const repoId = parsed && typeof parsed === 'object' ? parsed.repo_id : undefined;
-    return typeof repoId === 'number' && Number.isInteger(repoId) && repoId > 0 ? repoId : null;
+    return parsed && typeof parsed === 'object' ? parsed[field] : undefined;
 }
 export function writeConfigFile(cwd, config) {
     writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);

package/dist/files/guardrails.js

@@ -1,20 +1,29 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-export const GUARDRAILS_DIR = join('.unitbob', 'guardrails');
-export const SUITE_FILE = 'architecture_map_contracts_spec.rb';
+import { dirname, isAbsolute, join } from 'node:path';
+// A forward-slash literal, not path.join: suite paths always arrive over the
+// wire with '/', while path.join would render this '.unitbob\guardrails' on
+// Windows and make assertGuardrailPath reject every valid path there. node's
+// path.join still accepts a '/'-joined segment as input on every platform, so
+// filesystem builds below are unaffected.
+export const GUARDRAILS_DIR = '.unitbob/guardrails';
 export const HELPER_FILE = 'unitbob_helper.rb';
 // An always-empty custom options file: pointing rspec's --options here keeps
 // the project's own .rspec (stray --require lines, extra stdout formatters)
 // out of guardrail runs, whose JSON output must stay parseable.
 export const OPTIONS_FILE = 'rspec.opts';
-// RSpec writes its JSON report here via `--out`, not to stdout: the app under
-// test can print to stdout during a run (Rails logging, deprecation notices, a
-// stray `puts`), which corrupts a stdout-parsed JSON document. A dedicated file
-// isolates the report from anything else the process emits.
-export const RESULT_FILE = 'rspec_result.json';
-// The boot file the generated suite requires (spec 29). Connector-owned and
+// The one place that decides whether a host-provided suite path is safe to
+// write: relative, anchored under .unitbob/guardrails/, no traversal. Anything
+// else throws and nothing is written.
+export function assertGuardrailPath(path) {
+    const prefix = `${GUARDRAILS_DIR}/`;
+    const unsafe = !path || isAbsolute(path) || !path.startsWith(prefix) || path.split('/').some((segment) => segment === '..');
+    if (unsafe) {
+        throw new Error(`suite_file.path must be a relative path under ${prefix} with no traversal (got "${path}").`);
+    }
+}
+// The boot file the generated Ruby suite requires (spec 29). Connector-owned and
 // versioned with it — never scaffolded into the project, never part of the
-// suite digest (that covers `spec_rb` bytes only). Delegates to the project's
+// suite digest (that covers the suite_file only). Delegates to the project's
 // own RSpec setup when one exists; boots the Rails test environment directly
 // when none does. Both branches refuse a non-test environment — before boot
 // via ENV (nothing touched yet), after boot via Rails.env (config overrides).
@@ -39,16 +48,23 @@ else
 end
 abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
 `;
+// Write the suite blob's guardrail file at its own (validated) relative path.
+// The Ruby boot kit is materialized only for the rspec runner — Vitest and
+// pytest runs need no connector-written support files here (the runtime
+// pytest.ini lives outside this directory and is written by the pytest runner).
 export function materializeGuardrails(projectRoot, suite) {
+    assertGuardrailPath(suite.suite_file.path);
     const dir = join(projectRoot, GUARDRAILS_DIR);
     rmSync(dir, { recursive: true, force: true });
     mkdirSync(dir, { recursive: true });
-    const suitePath = join(dir, SUITE_FILE);
-    writeFileSync(suitePath, suite.spec_rb);
-    materializeHelper(projectRoot);
+    const suitePath = join(projectRoot, suite.suite_file.path);
+    mkdirSync(dirname(suitePath), { recursive: true });
+    writeFileSync(suitePath, suite.suite_file.content);
+    if (suite.runner_manifest.runner === 'rspec')
+        materializeHelper(projectRoot);
     return { suitePath };
 }
-// Both flows boot the same way: the check flow writes the boot kit next to
+// Both Ruby flows boot the same way: the check flow writes the boot kit next to
 // the suite here, the suite-build flow writes it right after the precheck.
 export function materializeHelper(projectRoot) {
     const dir = join(projectRoot, GUARDRAILS_DIR);

package/dist/files/suiteBuild.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { assertGuardrailPath } from "./guardrails.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
 }
@@ -30,34 +31,57 @@ export function readSuiteBuildRequest(projectRoot) {
     }
     return request;
 }
-// Read and parse the host's answer. The host wrote and ran the whole spec file;
-// the connector verifies it parses and carries `spec_rb` (inline or via
-// `spec_rb_path`) plus `test_metadata`, then relays it untouched. Anything
-// unparseable or incomplete means nothing is uploaded (all-or-nothing).
+// Read and parse the host's answer. The host wrote and ran the whole guardrail
+// file; the connector verifies the answer parses, carries `suite_file` (with a
+// safe path under .unitbob/guardrails/), `runner_manifest`, and
+// `test_metadata`, then relays it untouched. Anything unparseable or
+// incomplete means nothing is uploaded (all-or-nothing).
 export function readHostSuiteOutput(path, projectRoot) {
     if (!existsSync(path)) {
         throw new Error(`${path} not found — the host suite builder did not write its output.`);
     }
     const parsed = parseJson(readFileSync(path, 'utf8'), path);
     if (!parsed || typeof parsed !== 'object') {
-        throw new Error(`${path} is malformed: expected an object with spec_rb (or spec_rb_path) and test_metadata.`);
+        throw new Error(`${path} is malformed: expected an object with suite_file, runner_manifest, and test_metadata.`);
+    }
+    if ('spec_rb' in parsed || 'spec_rb_path' in parsed) {
+        throw new Error(`${path} uses the legacy spec_rb shape — emit suite_file { path, content } instead (spec 30).`);
     }
     if (!('test_metadata' in parsed)) {
         throw new Error(`${path} is malformed: missing test_metadata.`);
     }
-    const specRb = resolveSpecRb(parsed, projectRoot, path);
-    return { spec_rb: specRb, test_metadata: parsed.test_metadata };
+    const manifest = parsed.runner_manifest;
+    if (!manifest || typeof manifest !== 'object') {
+        throw new Error(`${path} is malformed: missing runner_manifest.`);
+    }
+    return {
+        suite_file: resolveSuiteFile(parsed, projectRoot, path),
+        runner_manifest: manifest,
+        test_metadata: parsed.test_metadata,
+    };
 }
-function resolveSpecRb(parsed, projectRoot, path) {
-    if (typeof parsed.spec_rb === 'string' && parsed.spec_rb.trim())
-        return parsed.spec_rb;
-    if (typeof parsed.spec_rb_path === 'string' && parsed.spec_rb_path.trim()) {
-        const specPath = isAbsolute(parsed.spec_rb_path) ? parsed.spec_rb_path : join(projectRoot, parsed.spec_rb_path);
-        if (!existsSync(specPath))
-            throw new Error(`${path}: spec_rb_path "${parsed.spec_rb_path}" does not exist.`);
-        return readFileSync(specPath, 'utf8');
+// The host may inline `content` or point at the file it already wrote at
+// `suite_file.path` — either way the path must be safe before anything is read.
+function resolveSuiteFile(parsed, projectRoot, path) {
+    const file = parsed.suite_file;
+    if (!file || typeof file !== 'object') {
+        throw new Error(`${path} is malformed: expected suite_file { path, content }.`);
+    }
+    const suiteFile = file;
+    const suitePath = typeof suiteFile.path === 'string' ? suiteFile.path : '';
+    assertGuardrailPath(suitePath);
+    if (typeof suiteFile.content === 'string' && suiteFile.content.trim()) {
+        return { path: suitePath, content: suiteFile.content };
+    }
+    const onDisk = join(projectRoot, suitePath);
+    if (!existsSync(onDisk)) {
+        throw new Error(`${path}: suite_file has no content and "${suitePath}" does not exist in the project.`);
+    }
+    const content = readFileSync(onDisk, 'utf8');
+    if (!content.trim()) {
+        throw new Error(`${path}: suite_file content at "${suitePath}" is empty.`);
     }
-    throw new Error(`${path} is malformed: expected a non-empty spec_rb or spec_rb_path.`);
+    return { path: suitePath, content };
 }
 function parseJson(raw, path) {
     try {

package/dist/link.js

@@ -5,35 +5,29 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
-import { CONFIG_FILE, readLocalRepoId, writeConfigFile } from "./config.js";
+import { CONFIG_FILE, readLocalRepoId, readLocalServer, writeConfigFile } from "./config.js";
 import { registerRepo, WireError } from "./wire.js";
-// Public Unitbob brain used by default. Local development can still pass an
-// explicit server URL or edit `.unitbob.json`.
+// Public Unitbob brain used by default. A `server` in `.unitbob.json` (or an
+// explicit argument) overrides it — see resolution order in ensureLinked.
 export const DEFAULT_SERVER = 'https://unitbob-73a4082838d3.herokuapp.com';
-// Make sure this project is linked, resolving the repo by name on every run
-// (cheap — the server find-or-creates) and reconciling with the local file:
-//   - no working link (file missing / repo_id 0 / non-int) → register, write
-//     the file, announce in one calm line;
-//   - the file's id matches the name's server id → proceed silently;
-//   - mismatch → fail here, before any expensive work — never silently re-link,
-//     the file may point at a real repo the user cares about.
-export async function ensureLinked(cwd = process.cwd(), server = DEFAULT_SERVER) {
+export async function ensureLinked(cwd = process.cwd(), server, out = process.stdout) {
+    const resolvedServer = server ?? readLocalServer(cwd) ?? DEFAULT_SERVER;
     const fileId = readLocalRepoId(cwd); // only cwd's own file — no walk-up
     const name = projectName(cwd);
     // Refuse before touching the server, so a stray run can't mint a junk repo.
     if (fileId === null)
         assertProjectRoot(cwd);
-    const authId = await registerRepo(server, name);
+    const authId = await registerRepo(resolvedServer, name);
     if (fileId === null) {
-        writeConfigFile(cwd, { server, repo_id: authId });
-        ensureGitignored(cwd);
-        process.stdout.write(`Linked this project to Unitbob as ${name}.\n`);
+        writeConfigFile(cwd, { server: resolvedServer, repo_id: authId });
+        ensureGitignored(cwd, out);
+        out.write(`Linked this project to Unitbob as ${name}.\n`);
     }
     else if (fileId !== authId) {
         throw new WireError(`${CONFIG_FILE} points at repo ${fileId}, but "${name}" is repo ${authId} on the server. ` +
             `Fix or remove ${CONFIG_FILE} before continuing.`);
     }
-    return { server, repoId: authId, projectRoot: cwd };
+    return { server: resolvedServer, repoId: authId, projectRoot: cwd };
 }
 // The linking name is the *project's* name, not the checkout's (spec 29). A
 // `.git` directory means cwd is the main checkout; a `.git` file is a worktree
@@ -113,7 +107,7 @@ function enclosingCheckout(cwd) {
 const ARTIFACT_DIR = '.unitbob/';
 const GITIGNORE = '.gitignore';
 // The config and the artifact dir are per-machine state, never committed.
-export function ensureGitignored(cwd) {
+export function ensureGitignored(cwd, out = process.stdout) {
     const gitignorePath = join(cwd, GITIGNORE);
     let current = '';
     if (existsSync(gitignorePath)) {
@@ -125,5 +119,5 @@ export function ensureGitignored(cwd) {
         return;
     const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
     writeFileSync(gitignorePath, `${current}${prefix}${additions.join('\n')}\n`);
-    process.stdout.write(`Added ${additions.join(', ')} to ${GITIGNORE}.\n`);
+    out.write(`Added ${additions.join(', ')} to ${GITIGNORE}.\n`);
 }

package/dist/runner/precheck.js

@@ -1,10 +1,44 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-const SUPPORTED = 'Unitbob guardrails support Ruby on Rails projects using RSpec only. ' +
-    'This project does not look like Rails + RSpec.';
-export function runtimePrecheck(projectRoot) {
+const defaultDeps = {
+    commandSucceeds: (command, args, cwd) => spawnSync(command, args, { cwd, timeout: 10_000 }).status === 0,
+};
+const STACKS = 'Ruby on Rails + RSpec, JavaScript/TypeScript + Vitest, or Python + pytest';
+// The generation-time gate: at least one supported stack must be present.
+export function anyStackPrecheck(projectRoot, deps = defaultDeps) {
+    const supported = ['rspec', 'vitest', 'pytest'].some((runner) => validateStack(projectRoot, runner, deps).ok);
+    if (supported)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `Unitbob guardrails support ${STACKS} only. This project matches none of those stacks.`,
+    };
+}
+// Confirm the host-selected runner against local markers. A mismatch fails
+// closed: the caller writes no files and uploads nothing.
+export function validateStack(projectRoot, runner, deps = defaultDeps) {
+    switch (runner) {
+        case 'rspec':
+            return rubyPrecheck(projectRoot);
+        case 'vitest':
+            return vitestPrecheck(projectRoot);
+        case 'pytest':
+            return pytestPrecheck(projectRoot, deps);
+        default:
+            return {
+                ok: false,
+                message: `Unsupported runner "${runner}" — Unitbob supports rspec, vitest, and pytest only.`,
+            };
+    }
+}
+function rubyPrecheck(projectRoot) {
     if (!hasGemfileWith(projectRoot, /\brails\b/)) {
-        return { ok: false, message: `${SUPPORTED} (no \`rails\` gem found in Gemfile.)` };
+        return {
+            ok: false,
+            message: 'The Ruby stack was selected, but this project does not look like Rails ' +
+                '(no `rails` gem found in Gemfile).',
+        };
     }
     // Specifically rspec-rails: the boot helper requires `rspec/rails`, so a
     // bare `rspec` gem passes nothing downstream — stop with the honest offer.
@@ -18,6 +52,53 @@ export function runtimePrecheck(projectRoot) {
     }
     return { ok: true };
 }
+function vitestPrecheck(projectRoot) {
+    const packageJson = join(projectRoot, 'package.json');
+    if (!existsSync(packageJson)) {
+        return {
+            ok: false,
+            message: 'The JavaScript/TypeScript stack was selected, but this project has no package.json.',
+        };
+    }
+    const hasVitest = /"vitest"/.test(readFileSync(packageJson, 'utf8')) ||
+        existsSync(join(projectRoot, 'node_modules', '.bin', 'vitest'));
+    if (!hasVitest) {
+        return {
+            ok: false,
+            message: 'JS/TS guardrails require Vitest (Jest is not supported in MVP v2), and vitest was not ' +
+                "found in this project's package.json or node_modules. Offer the user to add it " +
+                '(`npm i -D vitest`); change dependencies only with their consent, then retry.',
+        };
+    }
+    return { ok: true };
+}
+function pytestPrecheck(projectRoot, deps) {
+    const markers = ['pyproject.toml', 'requirements.txt', 'Pipfile'];
+    const found = markers.some((name) => existsSync(join(projectRoot, name)));
+    if (!found) {
+        return {
+            ok: false,
+            message: 'The Python stack was selected, but this project has none of ' +
+                `${markers.join(', ')} — it does not look like a Python project.`,
+        };
+    }
+    // Spec 30 fails closed on runner availability: unlike marker files, pytest
+    // must actually be importable in the current interpreter, or every run would
+    // end as a "No module named pytest" suite error after files were written. We
+    // probe the same interpreters the pytest runner tries, in the same order, so
+    // the precheck and the run agree on whether pytest is runnable.
+    const available = ['python3', 'python'].some((python) => deps.commandSucceeds(python, ['-m', 'pytest', '--version'], projectRoot));
+    if (!available) {
+        return {
+            ok: false,
+            message: 'The Python stack was selected, but pytest is not importable in the current Python ' +
+                'environment. If your dependencies live in a virtualenv, activate it (e.g. ' +
+                '`source .venv/bin/activate`) before running Unitbob; otherwise install pytest ' +
+                '(`pip install pytest`), then retry.',
+        };
+    }
+    return { ok: true };
+}
 function hasGemfileWith(projectRoot, pattern) {
     for (const name of ['Gemfile', 'gems.rb']) {
         const path = join(projectRoot, name);

package/dist/runner/pytest.js

@@ -0,0 +1,46 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { readReport } from "./types.js";
+export const PYTEST_TIMEOUT_MS = 10 * 60 * 1000;
+export const PYTEST_RESULT_FILE = join(GUARDRAILS_DIR, 'pytest_result.xml');
+// A minimal runtime config, created or overwritten before each run and passed
+// via `-c` so the project's own addopts (e.g. --cov, -n auto) cannot break the
+// guardrail run or its JUnit output. Connector-owned: never stored in Rails,
+// never part of the suite digest.
+export const PYTEST_INI_FILE = join('.unitbob', 'pytest.ini');
+export const PYTEST_INI = '[pytest]\naddopts =\n';
+// Run the materialised Unitbob guardrail suite with pytest in the current
+// Python environment (spec 30) — no guessing at Poetry/uv/virtualenv wrappers.
+// Only the guardrail file runs; the JUnit XML report goes to --junit-xml, not
+// stdout. The command is connector-owned: the suite artifact never carries a
+// command string.
+export async function runPytestSuite(projectRoot, suitePath) {
+    writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
+    const command = await pickPython(projectRoot);
+    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, suitePath, `--junit-xml=${PYTEST_RESULT_FILE}`];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: PYTEST_TIMEOUT_MS,
+        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return {
+        ...result,
+        command,
+        args,
+        resultPath: PYTEST_RESULT_FILE,
+        report: readReport(join(projectRoot, PYTEST_RESULT_FILE)),
+    };
+}
+// The interpreter that can actually run pytest: `python3` when pytest imports
+// there (macOS/Linux ship no bare `python`), else `python`. Probing `-m pytest`
+// rather than just `--version` keeps this in step with pytestPrecheck, so the
+// run uses the same interpreter the precheck confirmed.
+async function pickPython(projectRoot) {
+    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
+        cwd: projectRoot,
+        timeoutMs: 10_000,
+    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
+    return probe.code === 0 ? 'python3' : 'python';
+}

package/dist/runner/rspec.js

@@ -1,23 +1,23 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { runProcess } from "../proc.js";
-import { GUARDRAILS_DIR, OPTIONS_FILE, RESULT_FILE, SUITE_FILE } from "../files/guardrails.js";
+import { GUARDRAILS_DIR, OPTIONS_FILE } from "../files/guardrails.js";
+import { readReport } from "./types.js";
 export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 // Spec 26: the Unitbob file runs in a defined order with a fixed seed so a
 // green→red flip can never come from run-order nondeterminism. It does not inherit
 // the project's random ordering.
 export const RSPEC_SEED = '1';
+export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // Run the materialised Unitbob guardrail suite (spec 26). Only this file runs —
 // never the project's full suite — under RAILS_ENV=test with a fixed order/seed.
 // --options points at the materialized empty file so the project's own .rspec
 // (a --require of a helper we replaced, an extra stdout formatter) can neither
 // break the boot nor corrupt the JSON output. The JSON report goes to `--out`
 // (a file), not stdout, so the app's own stdout writes during the run can never
-// corrupt it.
-export async function runRspecSuite(projectRoot) {
-    const suitePath = join(GUARDRAILS_DIR, SUITE_FILE);
+// corrupt it. `suitePath` is the suite blob's own project-relative path.
+export async function runRspecSuite(projectRoot, suitePath) {
     const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
-    const resultPath = join(GUARDRAILS_DIR, RESULT_FILE);
     const { result, command, args } = await invokeRspec(projectRoot, [
         suitePath,
         '--options',
@@ -29,20 +29,15 @@ export async function runRspecSuite(projectRoot) {
         '--format',
         'json',
         '--out',
-        resultPath,
+        RSPEC_RESULT_FILE,
     ]);
-    return { ...result, command, args, jsonReport: readReport(join(projectRoot, resultPath)) };
-}
-// Read the `--out` report file back verbatim. A missing or unreadable file is a
-// clean empty string, not a throw: the caller falls back to stdout/stderr and
-// reports a suite error, exactly as it would for unparseable output.
-function readReport(path) {
-    try {
-        return existsSync(path) ? readFileSync(path, 'utf8') : '';
-    }
-    catch {
-        return '';
-    }
+    return {
+        ...result,
+        command,
+        args,
+        resultPath: RSPEC_RESULT_FILE,
+        report: readReport(join(projectRoot, RSPEC_RESULT_FILE)),
+    };
 }
 // Prefer the project's own `bin/rspec`; fall back to `bundle exec rspec`. Every
 // run sets RAILS_ENV=test so guardrails execute against the Rails test

package/dist/runner/types.js

@@ -0,0 +1,11 @@
+import { existsSync, readFileSync } from 'node:fs';
+// Read a report file back verbatim. A missing or unreadable file is a clean
+// empty string, not a throw: the caller reports a structured suite error.
+export function readReport(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, 'utf8') : '';
+    }
+    catch {
+        return '';
+    }
+}

package/dist/runner/vitest.js

@@ -0,0 +1,88 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { GUARDRAILS_DIR } from "../files/guardrails.js";
+import { readReport } from "./types.js";
+export const VITEST_TIMEOUT_MS = 10 * 60 * 1000;
+export const VITEST_RESULT_FILE = join(GUARDRAILS_DIR, 'vitest_result.json');
+// A connector-owned Vitest config, written next to .unitbob/ before a run when
+// the project has its own config. Connector-owned: never stored in Rails, never
+// part of the suite digest.
+export const VITEST_CONFIG_FILE = join('.unitbob', 'vitest.config.mjs');
+// 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
+// guardrail file needs all live there).
+const PROJECT_CONFIGS = [
+    'vitest.config.ts',
+    'vitest.config.mts',
+    'vitest.config.cts',
+    'vitest.config.js',
+    'vitest.config.mjs',
+    'vitest.config.cjs',
+    'vite.config.ts',
+    'vite.config.mts',
+    'vite.config.cts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.cjs',
+];
+// Run the materialised Unitbob guardrail suite with the project's own Vitest
+// (spec 30). Only the guardrail file runs — the path argument filters the run.
+//
+// A bare `vitest run <file>` treats the path as a filter that is intersected
+// with the project's `test.include`, so a project whose include does not cover
+// `.unitbob/` would collect no tests. When the project has its own config we
+// therefore write a tiny config that merges it and adds the guardrail file to
+// `include`; the positional filter still narrows the run to that one file. With
+// no project config, Vitest's default include already covers `.unitbob/`, so
+// the bare command is correct and we write nothing.
+//
+// The JSON report goes to --outputFile, not stdout, so app logging can never
+// corrupt it. The command is connector-owned: the suite artifact never carries
+// a command string.
+export async function runVitestSuite(projectRoot, suitePath) {
+    const configArgs = writeMergedConfig(projectRoot, suitePath);
+    const command = 'npx';
+    const args = ['vitest', 'run', suitePath, ...configArgs, '--reporter=json', `--outputFile=${VITEST_RESULT_FILE}`];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: VITEST_TIMEOUT_MS,
+        env: { ...process.env, UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return {
+        ...result,
+        command,
+        args,
+        resultPath: VITEST_RESULT_FILE,
+        report: readReport(join(projectRoot, VITEST_RESULT_FILE)),
+    };
+}
+// Returns the `--config` args to add, writing the merge config first. When the
+// project has no config of its own there is nothing to inherit and nothing to
+// override (defaults already cover .unitbob/), so we return no args.
+function writeMergedConfig(projectRoot, suitePath) {
+    const projectConfig = PROJECT_CONFIGS.find((name) => existsSync(join(projectRoot, name)));
+    if (!projectConfig)
+        return [];
+    writeFileSync(join(projectRoot, VITEST_CONFIG_FILE), mergedConfigSource(projectConfig, suitePath));
+    return ['--config', VITEST_CONFIG_FILE];
+}
+// The .unitbob/ config sits one level below the project root, so the project
+// config is a `../` import. `mergeConfig` concatenates `include`, so the
+// guardrail file joins the project's patterns instead of replacing them; the
+// positional filter then isolates it. A function-form config is resolved first.
+function mergedConfigSource(projectConfig, suitePath) {
+    return `// Written by the unitbob connector before each vitest run — do not edit.
+import { mergeConfig } from 'vitest/config';
+import projectConfig from ${JSON.stringify(`../${projectConfig}`)};
+
+const base = typeof projectConfig === 'function'
+  ? await projectConfig({ command: 'serve', mode: 'test' })
+  : projectConfig;
+
+export default mergeConfig(base, {
+  test: { include: [${JSON.stringify(suitePath)}] },
+});
+`;
+}

package/dist/verbs/putSuiteBuild.js

@@ -1,20 +1,30 @@
 import { readHostSuiteOutput, readSuiteBuildRequest } from "../files/suiteBuild.js";
+import { validateStack } from "../runner/precheck.js";
 import { Wire } from "../wire.js";
 // Read the task and the host's answer, verify the answer parses and carries the
-// whole spec file + test_metadata, then upload `{ map_digest, spec_rb,
-// test_metadata }`. `map_digest` comes from the task — never the host's answer —
-// so the host cannot claim a different map than it was given. If the answer is
-// unparseable or incomplete, nothing is uploaded and the previous suite stands.
+// whole suite artifact, confirm the host-selected stack against local project
+// markers (fail closed — a mismatch uploads nothing), then upload
+// `{ map_digest, suite_file, runner_manifest, test_metadata }`. `map_digest`
+// comes from the task — never the host's answer — so the host cannot claim a
+// different map than it was given. If the answer is unparseable or incomplete,
+// nothing is uploaded and the previous suite stands.
 export async function putSuiteBuild(config, _args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
     const output = readHostSuiteOutput(request.output_path, config.projectRoot);
     const actual = {
         putSuiteBuild: (payload) => new Wire(config).putSuiteBuild(payload),
+        validateStack,
         ...deps,
     };
+    const runner = String(output.runner_manifest.runner ?? '');
+    const check = actual.validateStack(config.projectRoot, runner);
+    if (!check.ok) {
+        throw new Error(check.message ?? `Local project does not match the selected runner "${runner}".`);
+    }
     const result = await actual.putSuiteBuild({
         map_digest: request.map_digest,
-        spec_rb: output.spec_rb,
+        suite_file: output.suite_file,
+        runner_manifest: output.runner_manifest,
         test_metadata: output.test_metadata,
     });
     const tallies = Object.entries(result.counts)

package/dist/verbs/run.js

@@ -1,60 +1,104 @@
 import { materializeGuardrails } from "../files/guardrails.js";
-import { runtimePrecheck } from "../runner/precheck.js";
+import { validateStack } from "../runner/precheck.js";
 import { runRspecSuite } from "../runner/rspec.js";
+import { runVitestSuite } from "../runner/vitest.js";
+import { runPytestSuite } from "../runner/pytest.js";
 import { Wire } from "../wire.js";
 // Bound failure text for transport/storage hygiene (spec 26). This is a size
 // limit only, not a privacy filter — application values in failure messages are
 // accepted, not scrubbed.
-const MAX_FAILURE_CHARS = 4000;
+const MAX_FAILURE_CHARS = 8000;
+const OUTPUT_TAIL_CHARS = 2000;
+// The check flow (spec 30): fetch the current suite blob, confirm the local
+// project matches its runner, materialize the guardrail file, execute the
+// connector-owned strategy named by `runner_manifest.runner`, and ship the raw
+// machine-readable report (or a structured runner error) to Rails.
 export async function run(config, _args, deps) {
     const wire = new Wire(config);
     const d = {
         getSuite: () => wire.getSuite(),
         postRun: (payload) => wire.postRun(payload),
         materializeGuardrails,
-        runRspecSuite,
-        precheck: runtimePrecheck,
+        runSuite: runSuiteByRunner,
+        validateStack,
         stdout: process.stdout,
         ...deps,
     };
-    const check = d.precheck(config.projectRoot);
-    if (!check.ok)
-        throw new Error(check.message ?? 'Unsupported runtime.');
     const suite = await d.getSuite();
     if (suite === null) {
         d.stdout.write('No Unitbob suite exists yet. Generate the test suite first, then run /unitbob check again.\n');
         return;
     }
+    // Fail closed before touching the working tree: a stack mismatch writes no files.
+    const runner = suite.runner_manifest.runner;
+    const check = d.validateStack(config.projectRoot, runner);
+    if (!check.ok)
+        throw new Error(check.message ?? `Local project does not match the suite runner "${runner}".`);
     d.materializeGuardrails(config.projectRoot, suite);
-    const result = await d.runRspecSuite(config.projectRoot).catch((err) => ({
+    const result = await d.runSuite(config.projectRoot, runner, suite.suite_file.path).catch((err) => ({
         stdout: '',
         stderr: err.message,
         code: null,
-        command: 'rspec',
+        command: runner,
         args: [],
-        jsonReport: '',
+        resultPath: '',
+        report: '',
     }));
-    const payload = rawRunPayload(suite.suite_digest, result);
+    const payload = rawRunPayload(suite.suite_digest, runner, result);
     const summary = await d.postRun(payload);
     d.stdout.write(`${summary.summary}\n`);
     if (summary.map_url)
         d.stdout.write(`${summary.map_url}\n`);
 }
-// The RSpec JSON report comes from the `--out` file (`jsonReport`), which the app
-// under test cannot pollute. Stdout is only a fallback for a runner double that
-// emits its report there; anything unparseable is a genuine suite error.
-function rawRunPayload(suiteDigest, result) {
-    const parsed = parseJsonObject(result.jsonReport) ?? parseJsonObject(result.stdout);
-    if (parsed)
-        return { suite_digest: suiteDigest, rspec_json: boundFailures(parsed) };
+// The connector-owned strategy table: `runner_manifest.runner` names one of
+// these; only suite and result paths vary. Host-provided command strings are
+// never executed.
+function runSuiteByRunner(projectRoot, runner, suitePath) {
+    switch (runner) {
+        case 'rspec':
+            return runRspecSuite(projectRoot, suitePath);
+        case 'vitest':
+            return runVitestSuite(projectRoot, suitePath);
+        case 'pytest':
+            return runPytestSuite(projectRoot, suitePath);
+        default:
+            return Promise.reject(new Error(`Unsupported runner "${runner}" — rebuild the suite with /unitbob suite.`));
+    }
+}
+// The machine-readable report comes from the runner's own output file, which
+// the app under test cannot pollute. A run that produced no report is a
+// structured suite error — command, exit code, expected result path, output
+// tail — which Rails records without repainting capabilities.
+function rawRunPayload(suiteDigest, runner, result) {
+    const report = boundedReport(runner, result);
+    if (report !== null)
+        return { suite_digest: suiteDigest, run_result: report };
     return {
         suite_digest: suiteDigest,
-        suite_error: suiteErrorMessage(result),
+        suite_error: {
+            command: [result.command, ...result.args].join(' '),
+            exit_code: result.code,
+            result_path: result.resultPath,
+            output_tail: outputTail(result),
+        },
     };
 }
+// JSON reports (rspec, vitest) are parsed only to size-bound failure text, then
+// re-serialized; the XML report is bounded per failure element the same way.
+// `null` means "no usable report" — the suite-error path. Stdout is only a
+// fallback for an rspec double that emits its report there.
+function boundedReport(runner, result) {
+    if (runner === 'pytest')
+        return result.report.trim() ? boundJunitXml(result.report) : null;
+    const parsed = parseJsonObject(result.report) ?? (runner === 'rspec' ? parseJsonObject(result.stdout) : null);
+    if (!parsed)
+        return null;
+    const bounded = runner === 'rspec' ? boundRspecFailures(parsed) : boundVitestFailures(parsed);
+    return JSON.stringify(bounded);
+}
 // Truncate long per-example failure message/backtrace before transport. Other
 // fields pass through untouched; Rails owns the capability join and status mapping.
-function boundFailures(rspecJson) {
+function boundRspecFailures(rspecJson) {
     const examples = rspecJson.examples;
     if (!Array.isArray(examples))
         return rspecJson;
@@ -75,9 +119,53 @@ function boundFailures(rspecJson) {
     });
     return { ...rspecJson, examples: bounded };
 }
+function boundVitestFailures(vitestJson) {
+    const testResults = vitestJson.testResults;
+    if (!Array.isArray(testResults))
+        return vitestJson;
+    const bounded = testResults.map((fileResult) => {
+        if (!fileResult || typeof fileResult !== 'object')
+            return fileResult;
+        const file = fileResult;
+        const assertions = file.assertionResults;
+        if (!Array.isArray(assertions))
+            return file;
+        const next = assertions.map((assertion) => {
+            if (!assertion || typeof assertion !== 'object')
+                return assertion;
+            const a = assertion;
+            if (!Array.isArray(a.failureMessages))
+                return a;
+            return { ...a, failureMessages: a.failureMessages.map((m) => (typeof m === 'string' ? truncate(m) : m)) };
+        });
+        return { ...file, assertionResults: next };
+    });
+    return { ...vitestJson, testResults: bounded };
+}
 function truncate(text) {
     return text.length > MAX_FAILURE_CHARS ? `${text.slice(0, MAX_FAILURE_CHARS)}… (truncated)` : text;
 }
+// pytest's JUnit XML has no size bound of its own: one failing assertion can
+// carry a multi-megabyte diff plus captured stdout/stderr. Bound the two things
+// Rails reads (the failure/error/skipped `message` attribute and the element
+// body) plus the captured-output blocks, keeping the document well-formed so
+// Rails' strict XML parse still succeeds.
+function boundJunitXml(xml) {
+    const boundedBodies = xml.replace(/(<(failure|error|skipped|system-out|system-err)\b[^>]*>)([\s\S]*?)(<\/\2>)/g, (_match, open, _tag, body, close) => `${boundXmlMessageAttr(open)}${boundXmlText(body)}${close}`);
+    // Self-closing forms (e.g. <failure message="…"/>) carry everything in the attr.
+    return boundedBodies.replace(/<(failure|error|skipped)\b[^>]*\/>/g, (tag) => boundXmlMessageAttr(tag));
+}
+function boundXmlMessageAttr(tag) {
+    // Attribute values escape their own quotes, so matching to the next `"` is safe.
+    return tag.replace(/(\bmessage=")([\s\S]*?)(")/, (_m, pre, value, post) => value.length > MAX_FAILURE_CHARS ? `${pre}${boundXmlText(value)}… (truncated)${post}` : `${pre}${value}${post}`);
+}
+function boundXmlText(text) {
+    return text.length > MAX_FAILURE_CHARS ? `${truncateXml(text)}… (truncated)` : text;
+}
+// Slice without cutting inside an XML entity, which would break a strict parse.
+function truncateXml(text) {
+    return text.slice(0, MAX_FAILURE_CHARS).replace(/&[^;]*$/, '');
+}
 function parseJsonObject(text) {
     try {
         const parsed = JSON.parse(text);
@@ -87,13 +175,12 @@ function parseJsonObject(text) {
         return null;
     }
 }
-function suiteErrorMessage(result) {
+function outputTail(result) {
     const bits = [];
-    if (result.code !== 0 && result.code !== null)
-        bits.push(`exit ${result.code}`);
     if (result.stderr.trim())
-        bits.push(`stderr: ${truncate(result.stderr.trim())}`);
+        bits.push(result.stderr.trim());
     if (result.stdout.trim())
-        bits.push(`stdout: ${result.stdout.trim().slice(0, 1000)}`);
-    return bits.length > 0 ? bits.join(' | ') : 'RSpec output was not parseable JSON';
+        bits.push(result.stdout.trim());
+    const joined = bits.join('\n');
+    return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
 }

package/dist/verbs/suitePrepare.js

@@ -1,21 +1,22 @@
 import { materializeHelper } from "../files/guardrails.js";
 import { writeSuiteBuildRequest } from "../files/suiteBuild.js";
-import { runtimePrecheck } from "../runner/precheck.js";
+import { anyStackPrecheck } from "../runner/precheck.js";
 import { Wire } from "../wire.js";
-// Confirm the runtime is supported (Rails + RSpec), materialize the boot helper
-// the generated suite will require, then fetch the generate recipe and the
-// per-block capability assignment and write the host's task to
-// `.unitbob/suite-build/request.json`. No model is called and no source is
-// read here — that is the host's job, framed by ai/agents/suite_builder.md. An
-// unsupported runtime stops with one actionable message and writes nothing; a
-// no-current-map error from the server surfaces (via WireError) with guidance to
-// run `/unitbob map` first.
+// Confirm at least one supported stack is present (Rails+RSpec, Vitest, or
+// pytest — the host LLM picks the primary one during generation), materialize
+// the Ruby boot helper a generated RSpec suite would require, then fetch the
+// generate recipe and the per-block capability assignment and write the host's
+// task to `.unitbob/suite-build/request.json`. No model is called and no
+// source is read here — that is the host's job, framed by
+// ai/agents/suite_builder.md. An unsupported project stops with one actionable
+// message and writes nothing; a no-current-map error from the server surfaces
+// (via WireError) with guidance to run `/unitbob map` first.
 export async function suitePrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePackets: () => wire.getSuitePackets(),
-        precheck: runtimePrecheck,
+        precheck: anyStackPrecheck,
         ...deps,
     };
     const check = actual.precheck(config.projectRoot);

package/dist/wire.js

@@ -56,9 +56,9 @@ export class Wire {
         return (await res.json());
     }
     // PUT /repos/:id/suite_build — upload the host's complete, locally-validated
-    // suite: the verbatim spec file plus the capability-keyed test_metadata. The
-    // server validates the classification, stores the bytes verbatim, versions, and
-    // returns the new suite's identity.
+    // suite artifact: the verbatim suite_file, the suite-level runner_manifest,
+    // and the capability-keyed test_metadata. The server validates the artifact,
+    // stores it verbatim, versions, and returns the new suite's identity.
     async putSuiteBuild(payload) {
         const res = await this.send('PUT', this.repoPath('suite_build'), payload);
         await this.ensureOk(res, `PUT ${this.repoPath('suite_build')}`);
@@ -118,9 +118,16 @@ export class Wire {
             throw new WireError(`GET ${this.repoPath('suite')} returned a malformed suite payload.`);
         }
         const suite = payload;
-        if (typeof suite.suite_digest !== 'string' || typeof suite.spec_rb !== 'string') {
+        const file = suite.suite_file;
+        const manifest = suite.runner_manifest;
+        const wellFormed = typeof suite.suite_digest === 'string' &&
+            file != null && typeof file === 'object' &&
+            typeof file.path === 'string' && typeof file.content === 'string' &&
+            manifest != null && typeof manifest === 'object' &&
+            typeof manifest.runner === 'string';
+        if (!wellFormed) {
             throw new WireError(`GET ${this.repoPath('suite')} returned a malformed suite payload: ` +
-                'expected suite_digest and spec_rb.');
+                'expected suite_digest, suite_file { path, content }, and runner_manifest.runner.');
         }
         return suite;
     }

package/package.json

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