unitbob 0.1.4 → 0.1.6

package/dist/files/guardrails.js

@@ -2,11 +2,54 @@ 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 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';
+// The boot file the generated 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
+// 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).
+export const UNITBOB_HELPER_RB = `# frozen_string_literal: true
+# Written by the unitbob connector on every materialization — do not edit.
+ENV['RAILS_ENV'] ||= 'test'
+abort 'unitbob_helper: refusing to run against a non-test environment' unless ENV['RAILS_ENV'] == 'test'
+root = File.expand_path('../..', __dir__)
+if File.exist?(File.join(root, 'spec', 'rails_helper.rb'))
+  # The project has its own RSpec setup — respect it (factories, cleaners…).
+  $LOAD_PATH.unshift File.join(root, 'spec')
+  require 'rails_helper'
+else
+  # No RSpec scaffolding — boot the Rails test environment directly.
+  require File.join(root, 'config', 'environment')
+  require 'rspec/rails'
+  ActiveRecord::Migration.maintain_test_schema!
+  RSpec.configure do |config|
+    config.use_transactional_fixtures = true
+    config.infer_spec_type_from_file_location!
+  end
+end
+abort 'unitbob_helper: refusing to run against a non-test environment' unless Rails.env.test?
+`;
 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);
+    materializeHelper(projectRoot);
     return { suitePath };
 }
+// Both 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);
+    mkdirSync(dir, { recursive: true });
+    const helperPath = join(dir, HELPER_FILE);
+    writeFileSync(helperPath, UNITBOB_HELPER_RB);
+    writeFileSync(join(dir, OPTIONS_FILE), '');
+    return helperPath;
+}

package/dist/link.js

@@ -1,10 +1,10 @@
 // Zero-touch linking (spec 28): every verb starts here. A project is identified
-// by its folder name — basename(cwd), nothing else — and resolved on the server
+// by its main checkout's folder name (spec 29) and resolved on the server
 // idempotently each run. The user never supplies a repo_id; it is an internal
 // server key nobody is expected to know.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { CONFIG_FILE, readLocalRepoId, writeConfigFile } from "./config.js";
 import { registerRepo, WireError } from "./wire.js";
 // Grill decision #1: hosted deployment is deferred; the local brain is the only
@@ -19,7 +19,7 @@ export const DEFAULT_SERVER = 'http://localhost:3000';
 //     the file may point at a real repo the user cares about.
 export async function ensureLinked(cwd = process.cwd(), server = DEFAULT_SERVER) {
     const fileId = readLocalRepoId(cwd); // only cwd's own file — no walk-up
-    const name = basename(cwd);
+    const name = projectName(cwd);
     // Refuse before touching the server, so a stray run can't mint a junk repo.
     if (fileId === null)
         assertProjectRoot(cwd);
@@ -35,14 +35,80 @@ export async function ensureLinked(cwd = process.cwd(), server = DEFAULT_SERVER)
     }
     return { server, 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
+// pointer whose `gitdir:` leads back to the main checkout
+// (`<root>/.git/worktrees/<slug>`). No subprocess — the file is parsed
+// directly, and anything unexpected (no `.git`, submodules, exotic layouts)
+// falls back to basename(cwd): name resolution never fails linking.
+export function projectName(cwd) {
+    const gitPath = join(cwd, '.git');
+    try {
+        if (!statSync(gitPath).isFile())
+            return basename(cwd); // .git directory — main checkout
+        const pointer = readFileSync(gitPath, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
+        if (!pointer)
+            return basename(cwd);
+        const gitdir = isAbsolute(pointer[1]) ? pointer[1] : resolve(cwd, pointer[1]);
+        const commonGit = commonGitDir(gitdir);
+        if (commonGit === null)
+            return basename(cwd); // submodule (`.git/modules/…`) or exotic layout
+        if (basename(commonGit) === '.git')
+            return basename(dirname(commonGit));
+        return basename(commonGit).replace(/\.git$/, '') || basename(cwd); // bare / separate git dir
+    }
+    catch {
+        return basename(cwd); // no .git at all — git-less project
+    }
+}
+// The main checkout's git dir for a worktree: git's own `commondir` pointer
+// inside the worktree admin dir works for every layout (bare main repo,
+// --separate-git-dir); the literal `<root>/.git/worktrees/<slug>` shape is
+// the fallback. null means "not a worktree we understand" — the caller falls
+// back to basename(cwd), so name resolution never fails linking.
+function commonGitDir(gitdir) {
+    const commondir = join(gitdir, 'commondir');
+    if (existsSync(commondir))
+        return resolve(gitdir, readFileSync(commondir, 'utf8').trim());
+    const worktrees = dirname(gitdir);
+    if (basename(worktrees) === 'worktrees' && basename(dirname(worktrees)) === '.git') {
+        return dirname(worktrees);
+    }
+    return null;
+}
+const PROJECT_MARKERS = ['Gemfile', 'gems.rb', 'package.json'];
 // Linking writes a file and creates a server row — only do that at a real
-// project root: a `.git` present, and never at $HOME or the filesystem root.
+// project root: never $HOME or the filesystem root, and the folder must be
+// anchored by `.git` or a recognizable project marker (a vibecoder may not use
+// version control at all; the marker still keeps junk folders off the brain).
 export function assertProjectRoot(cwd) {
     const isFsRoot = dirname(cwd) === cwd;
-    if (isFsRoot || cwd === homedir() || !existsSync(join(cwd, '.git'))) {
-        throw new WireError(`${cwd} does not look like a project root (no .git here) — ` +
-            "run this from your project's root folder.");
+    const hasGit = existsSync(join(cwd, '.git'));
+    const anchored = hasGit || PROJECT_MARKERS.some((marker) => existsSync(join(cwd, marker)));
+    if (isFsRoot || cwd === homedir() || !anchored) {
+        throw new WireError(`${cwd} does not look like a project root (no .git and no project files ` +
+            "(Gemfile/package.json) here) — run this from your project's root folder.");
+    }
+    // A marker without .git can also mean a folder *inside* a bigger project —
+    // a monorepo sub-package, a Rails app's frontend/, node_modules. Those must
+    // never mint a brain repo: inside a checkout, the root is where .git is.
+    if (!hasGit) {
+        const enclosing = enclosingCheckout(cwd);
+        if (enclosing !== null || cwd.split(sep).includes('node_modules')) {
+            const hint = enclosing === null ? 'a dependency folder' : `the project at ${enclosing}`;
+            throw new WireError(`${cwd} looks like a folder inside ${hint} — run this from your project's root folder.`);
+        }
+    }
+}
+// Nearest ancestor carrying a .git, walking up to (but not including) $HOME —
+// a dotfiles repo in $HOME must not swallow every git-less project under it.
+function enclosingCheckout(cwd) {
+    const home = homedir();
+    for (let dir = dirname(cwd); dir !== home && dirname(dir) !== dir; dir = dirname(dir)) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
     }
+    return null;
 }
 const ARTIFACT_DIR = '.unitbob/';
 const GITIGNORE = '.gitignore';

package/dist/runner/precheck.js

@@ -6,14 +6,14 @@ 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'))) {
+    // Specifically rspec-rails: the boot helper requires `rspec/rails`, so a
+    // bare `rspec` gem passes nothing downstream — stop with the honest offer.
+    if (!hasGemfileWith(projectRoot, /\brspec-rails\b/)) {
         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.',
+            message: "Unitbob guardrails need the rspec-rails gem, which is not in this project's " +
+                'Gemfile. Offer the user to add it and run `bundle install`; change the Gemfile ' +
+                'only with their consent, then retry.',
         };
     }
     return { ok: true };

package/dist/runner/rspec.js

@@ -1,7 +1,7 @@
 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";
+import { GUARDRAILS_DIR, OPTIONS_FILE, 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
@@ -9,9 +9,23 @@ export const RSPEC_TIMEOUT_MS = 10 * 60 * 1000;
 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.
+// --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.
 export async function runRspecSuite(projectRoot) {
     const suitePath = join(GUARDRAILS_DIR, SUITE_FILE);
-    return invokeRspec(projectRoot, [suitePath, '--order', 'defined', '--seed', RSPEC_SEED, '--format', 'json']);
+    const optionsPath = join(GUARDRAILS_DIR, OPTIONS_FILE);
+    return invokeRspec(projectRoot, [
+        suitePath,
+        '--options',
+        optionsPath,
+        '--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

package/dist/verbs/suitePrepare.js

@@ -1,9 +1,11 @@
+import { materializeHelper } from "../files/guardrails.js";
 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
+// 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
@@ -19,6 +21,7 @@ export async function suitePrepare(config, _args = [], deps) {
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
+    materializeHelper(config.projectRoot);
     const [recipe, packets] = await Promise.all([actual.getRecipe('generate'), actual.getSuitePackets()]);
     const request = writeSuiteBuildRequest(config.projectRoot, {
         map_digest: packets.map_digest,

package/package.json

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