unitbob 0.1.0

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// The single entry point. Parse `unitbob <verb> [args]`, dispatch to a hands-verb,
+// and map any thrown error to a non-zero exit with an actionable message — never
+// a raw stack trace. This is the only place that decides process exit codes.
+import { loadConfig } from "./config.js";
+import { recipe } from "./verbs/recipe.js";
+import { show } from "./verbs/show.js";
+import { run } from "./verbs/run.js";
+import { init } from "./verbs/init.js";
+import { mapPrepare } from "./verbs/mapPrepare.js";
+import { putMapBuild } from "./verbs/putMapBuild.js";
+import { suitePrepare } from "./verbs/suitePrepare.js";
+import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
+import { fixPrepare } from "./verbs/fixPrepare.js";
+const USAGE = `unitbob — thin local hands for the Unitbob server.
+
+Usage: unitbob <verb> [args]
+
+Verbs:
+  init                 Write a .unitbob.json template and git-ignore it.
+  recipe <name>        Fetch and print a recipe from the server.
+  show                 Print the link to this project's map.
+  map-prepare          Internal: keylessly update the graph (no API key) and write the host map-build request.
+  put-map-build        Internal: upload the host-built map and graph.
+  suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
+  put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata).
+  fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
+  check                Run the guardrail suite locally and report.
+  run                  Alias for check.
+
+Pipeline: map and suite are built on your machine. \`*-prepare\` writes a request
+packet (with the recipe and paths); you build the artifact at the packet's
+output_path from your local source; \`put-*\` uploads only the structured result.
+\`check\` runs the guardrails locally and reports results to the server.
+Graph extraction is keyless: the connector needs no LLM API key. Inference is the
+host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify skill).
+
+Config: .unitbob.json at your project root — { "server": "...", "repo_id": <number> }.`;
+async function main(argv) {
+    const [verb, ...args] = argv;
+    if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
+        process.stdout.write(`${USAGE}\n`);
+        return verb ? 0 : 1;
+    }
+    try {
+        switch (verb) {
+            case 'init':
+                await init(args);
+                return 0;
+            case 'recipe':
+                await recipe(loadConfig(), args);
+                return 0;
+            case 'show':
+                await show(loadConfig());
+                return 0;
+            case 'map-prepare':
+                await mapPrepare(loadConfig(), args);
+                return 0;
+            case 'put-map-build':
+                await putMapBuild(loadConfig(), args);
+                return 0;
+            case 'suite-prepare':
+                await suitePrepare(loadConfig(), args);
+                return 0;
+            case 'put-suite-build':
+                await putSuiteBuild(loadConfig(), args);
+                return 0;
+            case 'fix-prepare':
+                await fixPrepare(loadConfig(), args);
+                return 0;
+            case 'run':
+            case 'check':
+                await run(loadConfig(), args);
+                return 0;
+            default:
+                process.stderr.write(`Unknown verb "${verb}".\n\n${USAGE}\n`);
+                return 1;
+        }
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 1;
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,53 @@
+// Per-project config for the connector. Lives in `.unitbob.json` at the project
+// root: { "server": "https://…", "repo_id": 3 }. No secret — auth is deferred
+// (spec 15, decision #3). Every verb reads it. A missing or malformed file must
+// fail with an actionable setup message, never a raw stack trace.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const CONFIG_FILE = '.unitbob.json';
+const SETUP_HINT = 'run `unitbob init`, or create a `.unitbob.json` at your project root with ' +
+    '{ "server": "https://your-unitbob-host", "repo_id": <number> }';
+// Walk up from `startDir` to the filesystem root looking for `.unitbob.json`.
+export function findConfigPath(startDir = process.cwd()) {
+    let dir = startDir;
+    for (;;) {
+        const candidate = join(dir, CONFIG_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function loadConfig(startDir = process.cwd()) {
+    const path = findConfigPath(startDir);
+    if (!path) {
+        throw new Error(`No ${CONFIG_FILE} found — ${SETUP_HINT}`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Could not read ${path} (${err.message}) — ${SETUP_HINT}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${path} is not valid JSON — ${SETUP_HINT}`);
+    }
+    const obj = (parsed && typeof parsed === 'object' ? parsed : {});
+    const server = obj.server;
+    const repoId = obj.repo_id;
+    if (typeof server !== 'string' || server.trim() === '') {
+        throw new Error(`${path} is missing a "server" string — ${SETUP_HINT}`);
+    }
+    if (typeof repoId !== 'number' || !Number.isInteger(repoId)) {
+        throw new Error(`${path} is missing an integer "repo_id" — ${SETUP_HINT}`);
+    }
+    // Trim a trailing slash so callers can join paths without doubling up.
+    return { server: server.trim().replace(/\/+$/, ''), repoId, projectRoot: dirname(path) };
+}

package/dist/files/fix.js

@@ -0,0 +1,20 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'fix', 'request.json');
+}
+export function writeFixRequest(projectRoot, interfaceId, packet) {
+    const request = {
+        project_root: projectRoot,
+        interface_id: interfaceId,
+        headline: packet.headline,
+        failure_message: packet.failure_message,
+        anchor: packet.anchor,
+        prompt: packet.prompt,
+    };
+    const path = requestPath(projectRoot);
+    if (!existsSync(dirname(path)))
+        mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}

package/dist/files/guardrails.js

@@ -0,0 +1,12 @@
+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';
+export function materializeGuardrails(projectRoot, suite) {
+    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);
+    return { suitePath };
+}

package/dist/files/mapBuild.js

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function graphPath(projectRoot) {
+    // The one canonical local graph, shared with Graphify and any host-LLM
+    // enrichment. The connector keeps no second `.unitbob` copy.
+    return join(projectRoot, 'graphify-out', 'graph.json');
+}
+export function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'map-build', 'request.json');
+}
+export function outputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'map-build', 'map_document.json');
+}
+export function readFreshGraph(projectRoot) {
+    const path = graphPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`graphify update did not write ${path}`);
+    }
+    const rawGraphJson = readFileSync(path, 'utf8');
+    parseJson(rawGraphJson, path);
+    return rawGraphJson;
+}
+export function writeMapBuildRequest(projectRoot, recipes) {
+    const packet = {
+        project_root: projectRoot,
+        graph_path: graphPath(projectRoot),
+        output_path: outputPath(projectRoot),
+        recipes,
+    };
+    const path = requestPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(packet, null, 2)}\n`);
+    return packet;
+}
+export function readMapBuildRequest(projectRoot) {
+    const path = requestPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`npx unitbob map-prepare\` first.`);
+    }
+    const packet = parseJson(readFileSync(path, 'utf8'), path);
+    if (!isMapBuildRequest(packet)) {
+        throw new Error(`${path} is malformed: expected project_root, graph_path, output_path, and recipes.`);
+    }
+    return packet;
+}
+export function readHostMapOutput(path) {
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — the host map builder did not write a map document.`);
+    }
+    return parseJson(readFileSync(path, 'utf8'), path);
+}
+function parseJson(raw, path) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err.message})`);
+    }
+}
+function isMapBuildRequest(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const packet = value;
+    const recipes = packet.recipes;
+    return (typeof packet.project_root === 'string' &&
+        typeof packet.graph_path === 'string' &&
+        typeof packet.output_path === 'string' &&
+        !!recipes &&
+        isRecipe(recipes.decompose) &&
+        isRecipe(recipes.relate));
+}
+function isRecipe(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const recipe = value;
+    return typeof recipe.name === 'string' && typeof recipe.version === 'string' && typeof recipe.text === 'string';
+}

package/dist/files/suiteBuild.js

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+export function requestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
+}
+export function outputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'suite_output.json');
+}
+export function writeSuiteBuildRequest(projectRoot, task) {
+    const request = {
+        project_root: projectRoot,
+        map_digest: task.map_digest,
+        output_path: outputPath(projectRoot),
+        recipe: task.recipe,
+        blocks: task.blocks,
+    };
+    const path = requestPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+export function readSuiteBuildRequest(projectRoot) {
+    const path = requestPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`npx unitbob suite-prepare\` first.`);
+    }
+    const request = parseJson(readFileSync(path, 'utf8'), path);
+    if (!isSuiteBuildRequest(request)) {
+        throw new Error(`${path} is malformed: expected project_root, map_digest, output_path, recipe, and blocks.`);
+    }
+    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).
+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.`);
+    }
+    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 };
+}
+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');
+    }
+    throw new Error(`${path} is malformed: expected a non-empty spec_rb or spec_rb_path.`);
+}
+function parseJson(raw, path) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err.message})`);
+    }
+}
+function isSuiteBuildRequest(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const request = value;
+    return (typeof request.project_root === 'string' &&
+        typeof request.map_digest === 'string' &&
+        typeof request.output_path === 'string' &&
+        isRecipe(request.recipe) &&
+        Array.isArray(request.blocks));
+}
+function isRecipe(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const recipe = value;
+    return typeof recipe.name === 'string' && typeof recipe.version === 'string' && typeof recipe.text === 'string';
+}

package/dist/proc.js

@@ -0,0 +1,79 @@
+// Spawn helper for the local tools the connector drives (graphify, rspec). It
+// captures stdout/stderr/exit code and hands them back untouched — shaping or
+// interpreting that output is the caller's (and ultimately Rails') job.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const GRAPHIFY_TIMEOUT_MS = 10 * 60 * 1000;
+export function runProcess(command, args = [], options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd: options.cwd, env: options.env });
+        let stdout = '';
+        let stderr = '';
+        let finished = false;
+        let timedOut = false;
+        let forceKillTimer = null;
+        const finish = (result) => {
+            if (finished)
+                return;
+            finished = true;
+            if (timer)
+                clearTimeout(timer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            resolve(result);
+        };
+        const timer = options.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                stderr += `${stderr.endsWith('\n') || stderr.length === 0 ? '' : '\n'}${command} timed out after ${options.timeoutMs}ms`;
+                child.kill('SIGTERM');
+                forceKillTimer = setTimeout(() => child.kill('SIGKILL'), 2000);
+            }, options.timeoutMs)
+            : null;
+        child.stdout.on('data', (chunk) => (stdout += chunk.toString()));
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            reject(err);
+        });
+        child.on('close', (code) => finish({ stdout, stderr, code: timedOut ? null : code }));
+    });
+}
+export async function requireGraphify() {
+    try {
+        const result = await runProcess('graphify', ['--help']);
+        if (result.code === 0)
+            return;
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `graphify --help exited ${result.code}`);
+    }
+    catch (err) {
+        throw new Error(`graphify is required but was not found or did not run. Install graphify and make sure ` +
+            `it is available in PATH (${err.message}).`);
+    }
+}
+export function ensureUnitbobIgnored(projectRoot) {
+    ensureLine(join(projectRoot, '.gitignore'), '.unitbob/');
+    ensureLine(join(projectRoot, '.gitignore'), 'graphify-out/');
+    ensureLine(join(projectRoot, '.graphifyignore'), '.unitbob/');
+}
+function ensureLine(path, line) {
+    let current = '';
+    if (existsSync(path)) {
+        current = readFileSync(path, 'utf8');
+        if (current.split('\n').some((existing) => existing.trim() === line))
+            return;
+    }
+    const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+    writeFileSync(path, `${current}${prefix}${line}\n`);
+}
+export async function runGraphifyExtractKeyless(projectRoot) {
+    // Deterministic AST-only graph; no LLM, no API key. `update --force` re-extracts
+    // the code and refreshes <root>/graphify-out/graph.json in place, replacing
+    // removed nodes. Semantic enrichment, if wanted, is host-LLM work (the
+    // /graphify skill on the client), never a keyed LLM here.
+    return await runProcess('graphify', ['update', projectRoot, '--force'], { cwd: projectRoot, timeoutMs: GRAPHIFY_TIMEOUT_MS });
+}

package/dist/runner/precheck.js

@@ -0,0 +1,28 @@
+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) {
+    if (!hasGemfileWith(projectRoot, /\brails\b/)) {
+        return { ok: false, message: `${SUPPORTED} (no \`rails\` gem found in Gemfile.)` };
+    }
+    if (!hasGemfileWith(projectRoot, /\brspec(-rails)?\b/)) {
+        return { ok: false, message: `${SUPPORTED} (no \`rspec\`/\`rspec-rails\` gem found in Gemfile.)` };
+    }
+    if (!existsSync(join(projectRoot, 'spec', 'rails_helper.rb'))) {
+        return {
+            ok: false,
+            message: 'Unitbob needs spec/rails_helper.rb to run Rails guardrails, but it was not found. ' +
+                'Set up RSpec for this Rails project first, then try again.',
+        };
+    }
+    return { ok: true };
+}
+function hasGemfileWith(projectRoot, pattern) {
+    for (const name of ['Gemfile', 'gems.rb']) {
+        const path = join(projectRoot, name);
+        if (existsSync(path) && pattern.test(readFileSync(path, 'utf8')))
+            return true;
+    }
+    return false;
+}

package/dist/runner/rspec.js

@@ -0,0 +1,38 @@
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { GUARDRAILS_DIR, SUITE_FILE } from "../files/guardrails.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';
+// 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.
+export async function runRspecSuite(projectRoot) {
+    const suitePath = join(GUARDRAILS_DIR, SUITE_FILE);
+    return invokeRspec(projectRoot, [suitePath, '--order', 'defined', '--seed', RSPEC_SEED, '--format', 'json']);
+}
+// 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
+// environment the project's `rails_helper` configures.
+async function invokeRspec(projectRoot, rspecArgs) {
+    const localRspec = join(projectRoot, 'bin', 'rspec');
+    const hasLocalRspec = executable(localRspec);
+    const command = hasLocalRspec ? localRspec : 'bundle';
+    const args = hasLocalRspec ? rspecArgs : ['exec', 'rspec', ...rspecArgs];
+    const result = await runProcess(command, args, {
+        cwd: projectRoot,
+        timeoutMs: RSPEC_TIMEOUT_MS,
+        env: { ...process.env, RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot },
+    });
+    return { ...result, command, args };
+}
+function executable(path) {
+    try {
+        return existsSync(path) && (statSync(path).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/verbs/fixPrepare.js

@@ -0,0 +1,21 @@
+import { writeFixRequest } from "../files/fix.js";
+import { Wire } from "../wire.js";
+// Fetch the per-capability repair packet and write the host's task to
+// `.unitbob/fix/request.json`. No recipe fetch, no upload — the host reads its own
+// source and the local spec file, then either fixes code (next `/unitbob check`
+// shows the result) or accepts the change and republishes the suite (spec 26). A
+// 422 from the server (non-failed / stale / no suite) surfaces via WireError;
+// nothing is written.
+export async function fixPrepare(config, args = [], deps) {
+    const interfaceId = (args[0] ?? '').trim();
+    if (!interfaceId)
+        throw new Error('Usage: unitbob fix-prepare <interface_id>');
+    const d = {
+        getFixPacket: (id) => new Wire(config).getFixPacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const packet = await d.getFixPacket(interfaceId);
+    writeFixRequest(config.projectRoot, interfaceId, packet);
+    d.stdout.write(`${packet.message}\n`);
+}

package/dist/verbs/init.js

@@ -0,0 +1,35 @@
+// `unitbob init` — write a `.unitbob.json` template at the current directory and
+// make sure it is git-ignored. This is the one verb that does not require an
+// existing config, since its job is to create one.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const CONFIG_FILE = '.unitbob.json';
+const ARTIFACT_DIR = '.unitbob/';
+const GITIGNORE = '.gitignore';
+export async function init(_args) {
+    const cwd = process.cwd();
+    const configPath = join(cwd, CONFIG_FILE);
+    if (existsSync(configPath)) {
+        process.stdout.write(`${CONFIG_FILE} already exists at ${configPath} — leaving it untouched.\n`);
+    }
+    else {
+        const template = { server: 'http://localhost:3000', repo_id: 0 };
+        writeFileSync(configPath, `${JSON.stringify(template, null, 2)}\n`);
+        process.stdout.write(`Wrote ${configPath}. Edit "server" and "repo_id" to point at your Unitbob host.\n`);
+    }
+    ensureGitignored(cwd);
+}
+function ensureGitignored(cwd) {
+    const gitignorePath = join(cwd, GITIGNORE);
+    let current = '';
+    if (existsSync(gitignorePath)) {
+        current = readFileSync(gitignorePath, 'utf8');
+    }
+    const lines = current.split('\n').map((line) => line.trim());
+    const additions = [CONFIG_FILE, ARTIFACT_DIR].filter((line) => !lines.includes(line));
+    if (additions.length === 0)
+        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`);
+}

package/dist/verbs/mapPrepare.js

@@ -0,0 +1,28 @@
+import { ensureUnitbobIgnored, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
+import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
+import { Wire } from "../wire.js";
+export async function mapPrepare(config, _args = [], deps) {
+    const wire = new Wire(config);
+    const actual = {
+        requireGraphify,
+        ensureUnitbobIgnored,
+        runGraphifyExtractKeyless,
+        getRecipe: (name) => wire.getRecipe(name),
+        ...deps,
+    };
+    actual.ensureUnitbobIgnored(config.projectRoot);
+    await actual.requireGraphify();
+    // Keyless: refresh the one canonical graph in place. No inference secret and no
+    // graph flags — semantic enrichment is host-LLM work, not a keyed LLM here.
+    const result = await actual.runGraphifyExtractKeyless(config.projectRoot);
+    if (result.code !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `graphify exited ${result.code}`;
+        throw new Error(`graphify update failed: ${detail}`);
+    }
+    readFreshGraph(config.projectRoot);
+    const [decompose, relate] = await Promise.all([actual.getRecipe('decompose'), actual.getRecipe('relate')]);
+    const packet = writeMapBuildRequest(config.projectRoot, { decompose, relate });
+    process.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
+    process.stdout.write(`Next: build the Map Document at ${packet.output_path} following recipes.decompose and ` +
+        'recipes.relate inside that request, then run `unitbob put-map-build`.\n');
+}

package/dist/verbs/putMapBuild.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { readHostMapOutput, readMapBuildRequest } from "../files/mapBuild.js";
+import { Wire } from "../wire.js";
+export async function putMapBuild(config, _args = [], deps) {
+    const packet = readMapBuildRequest(config.projectRoot);
+    const graph = JSON.parse(readFileSync(packet.graph_path, 'utf8'));
+    const mapDocument = readHostMapOutput(packet.output_path);
+    const actual = {
+        putMapBuild: (payload) => new Wire(config).putMapBuild(payload),
+        ...deps,
+    };
+    const result = await actual.putMapBuild({ graph, map_document: mapDocument });
+    process.stdout.write(`Map uploaded (${result.map_digest}, graph ${result.graph_digest}) ` +
+        `${result.reused ? 'reused' : 'created'} version ${result.map_version_id}.\n` +
+        `${result.map_url}\n`);
+}

package/dist/verbs/putSuiteBuild.js

@@ -0,0 +1,25 @@
+import { readHostSuiteOutput, readSuiteBuildRequest } from "../files/suiteBuild.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.
+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),
+        ...deps,
+    };
+    const result = await actual.putSuiteBuild({
+        map_digest: request.map_digest,
+        spec_rb: output.spec_rb,
+        test_metadata: output.test_metadata,
+    });
+    const tallies = Object.entries(result.counts)
+        .map(([name, value]) => `${value} ${name}`)
+        .join(', ');
+    process.stdout.write(`Suite uploaded (${result.suite_digest}) as version ${result.suite_version_id}` +
+        `${tallies ? ` — ${tallies}` : ''}.\n${result.map_url}\n`);
+}

package/dist/verbs/recipe.js

@@ -0,0 +1,9 @@
+import { Wire } from "../wire.js";
+export async function recipe(config, args) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('usage: unitbob recipe <name>  (e.g. decompose, relate, generate)');
+    }
+    const { text } = await new Wire(config).getRecipe(name);
+    process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+}

package/dist/verbs/run.js

@@ -0,0 +1,95 @@
+import { materializeGuardrails } from "../files/guardrails.js";
+import { runtimePrecheck } from "../runner/precheck.js";
+import { runRspecSuite } from "../runner/rspec.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;
+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,
+        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;
+    }
+    d.materializeGuardrails(config.projectRoot, suite);
+    const result = await d.runRspecSuite(config.projectRoot).catch((err) => ({
+        stdout: '',
+        stderr: err.message,
+        code: null,
+        command: 'rspec',
+        args: [],
+    }));
+    const payload = rawRunPayload(suite.suite_digest, result);
+    const summary = await d.postRun(payload);
+    d.stdout.write(`${summary.summary}\n`);
+    if (summary.map_url)
+        d.stdout.write(`${summary.map_url}\n`);
+}
+function rawRunPayload(suiteDigest, result) {
+    const parsed = parseJsonObject(result.stdout);
+    if (parsed)
+        return { suite_digest: suiteDigest, rspec_json: boundFailures(parsed) };
+    return {
+        suite_digest: suiteDigest,
+        suite_error: suiteErrorMessage(result),
+    };
+}
+// 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) {
+    const examples = rspecJson.examples;
+    if (!Array.isArray(examples))
+        return rspecJson;
+    const bounded = examples.map((example) => {
+        if (!example || typeof example !== 'object')
+            return example;
+        const ex = example;
+        const exception = ex.exception;
+        if (!exception || typeof exception !== 'object')
+            return ex;
+        const exc = exception;
+        const next = { ...exc };
+        if (typeof exc.message === 'string')
+            next.message = truncate(exc.message);
+        if (Array.isArray(exc.backtrace))
+            next.backtrace = exc.backtrace.slice(0, 20);
+        return { ...ex, exception: next };
+    });
+    return { ...rspecJson, examples: bounded };
+}
+function truncate(text) {
+    return text.length > MAX_FAILURE_CHARS ? `${text.slice(0, MAX_FAILURE_CHARS)}… (truncated)` : text;
+}
+function parseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function suiteErrorMessage(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())}`);
+    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';
+}

package/dist/verbs/show.js

@@ -0,0 +1,6 @@
+export function repoUrl(config) {
+    return `${config.server}/repos/${config.repoId}`;
+}
+export async function show(config) {
+    process.stdout.write(`${repoUrl(config)}\n`);
+}

package/dist/verbs/suitePrepare.js

@@ -0,0 +1,31 @@
+import { writeSuiteBuildRequest } from "../files/suiteBuild.js";
+import { runtimePrecheck } from "../runner/precheck.js";
+import { Wire } from "../wire.js";
+// Confirm the runtime is supported (Rails + RSpec + rails_helper), 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.
+export async function suitePrepare(config, _args = [], deps) {
+    const wire = new Wire(config);
+    const actual = {
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuitePackets: () => wire.getSuitePackets(),
+        precheck: runtimePrecheck,
+        ...deps,
+    };
+    const check = actual.precheck(config.projectRoot);
+    if (!check.ok)
+        throw new Error(check.message ?? 'Unsupported runtime.');
+    const [recipe, packets] = await Promise.all([actual.getRecipe('generate'), actual.getSuitePackets()]);
+    const request = writeSuiteBuildRequest(config.projectRoot, {
+        map_digest: packets.map_digest,
+        recipe,
+        blocks: packets.blocks,
+    });
+    process.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
+    process.stdout.write(`Next: write the complete guardrail spec and ${request.output_path} following \`recipe\` and the ` +
+        'per-block capability `blocks` inside that request, run it locally to green, then run `unitbob put-suite-build`.\n');
+}

package/dist/wire.js

@@ -0,0 +1,120 @@
+// Raised when the server cannot be reached or answers with an error status.
+// Verbs surface its message and exit non-zero; they never fabricate a result.
+export class WireError extends Error {
+}
+export class Wire {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // PUT /repos/:id/map_build — upload the fresh graph and host-built map as one
+    // atomic blob. Rails validates, versions, and computes all digests.
+    async putMapBuild(payload) {
+        const res = await this.send('PUT', this.repoPath('map_build'), payload);
+        await this.ensureOk(res, `PUT ${this.repoPath('map_build')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/suite_packets — the host's assignment (the capabilities to
+    // guard). Relayed opaque; 409 (no current map) surfaces as a WireError carrying
+    // the server's "run /unitbob map first" guidance.
+    async getSuitePackets() {
+        const res = await this.send('GET', this.repoPath('suite_packets'));
+        await this.ensureOk(res, `GET ${this.repoPath('suite_packets')}`);
+        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.
+    async putSuiteBuild(payload) {
+        const res = await this.send('PUT', this.repoPath('suite_build'), payload);
+        await this.ensureOk(res, `PUT ${this.repoPath('suite_build')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/fix_packet?interface_id= — the per-capability repair packet.
+    // Relayed down for the host to fix code or accept the change; 422 (non-failed /
+    // stale / no suite) surfaces as a WireError carrying the server's business reason.
+    async getFixPacket(interfaceId) {
+        const url = this.repoQueryPath('fix_packet', 'interface_id', interfaceId);
+        const res = await this.send('GET', url);
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
+    // GET /recipes/:name — fetch a recipe at call time. Recipes live on Rails so
+    // the connector and Skill carry no recipe text (spec 15, acceptance criteria).
+    async getRecipe(name) {
+        const url = `${this.config.server}/recipes/${encodeURIComponent(name)}`;
+        const res = await this.send('GET', url);
+        if (res.status === 404) {
+            throw new WireError(`Unknown recipe "${name}" (server returned 404).`);
+        }
+        await this.ensureOk(res, `GET ${url}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/suite — the current suite blob, or null when none exists yet
+    // (the server answers 204). Returned opaque; materializing it is spec 18.
+    async getSuite() {
+        const res = await this.send('GET', this.repoPath('suite'));
+        if (res.status === 204)
+            return null;
+        await this.ensureOk(res, `GET ${this.repoPath('suite')}`);
+        return this.decodeSuiteBlob(await res.json());
+    }
+    // POST /repos/:id/runs — ship the raw runner output; the server parses it and
+    // returns the run summary. The connector neither builds nor reads the payload
+    // body beyond passing it along.
+    async postRun(payload) {
+        const res = await this.send('POST', this.repoPath('runs'), payload);
+        await this.ensureOk(res, `POST ${this.repoPath('runs')}`);
+        return (await res.json());
+    }
+    // GET /repos/:id/lamps — the server's current run summary, printed verbatim.
+    async getLamps() {
+        const res = await this.send('GET', this.repoPath('lamps'));
+        await this.ensureOk(res, `GET ${this.repoPath('lamps')}`);
+        return await res.json();
+    }
+    repoPath(suffix) {
+        return `${this.config.server}/repos/${this.config.repoId}/${suffix}`;
+    }
+    repoQueryPath(suffix, key, value) {
+        return `${this.repoPath(suffix)}?${key}=${encodeURIComponent(value)}`;
+    }
+    decodeSuiteBlob(payload) {
+        if (!payload || typeof payload !== 'object') {
+            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') {
+            throw new WireError(`GET ${this.repoPath('suite')} returned a malformed suite payload: ` +
+                'expected suite_digest and spec_rb.');
+        }
+        return suite;
+    }
+    async send(method, url, body) {
+        try {
+            return await fetch(url, {
+                method,
+                headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new WireError(`Cannot reach the Unitbob server at ${this.config.server} ` +
+                `(${err.message}). Check that the server is running and that ` +
+                `"server" in .unitbob.json is correct.`);
+        }
+    }
+    async ensureOk(res, what) {
+        if (res.ok)
+            return;
+        let detail = '';
+        try {
+            detail = (await res.text()).slice(0, 500);
+        }
+        catch {
+            // ignore — the status alone is actionable enough
+        }
+        throw new WireError(`${what} failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "unitbob",
+  "version": "0.1.0",
+  "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": {
+    "unitbob": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "node --test test/*.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}