unitbob 0.1.9 → 0.1.11

package/README.md

@@ -31,13 +31,20 @@ Restart the session so the commands load.
 
 ## Full cycle
 
-| Step | With a prompt (just type in chat) | With a command |
-|------|-----------------------------------|----------------|
-| 1. Build the map | `Build my Unitbob map` | `/unitbob:map` |
-| 2. Generate tests | `Generate the guardrail tests` | `/unitbob:suite` |
-| 3. Run the checks | `Run the checks` | `/unitbob:check` |
-| 4. Fix a red lamp | `Fix guardrail <id>` | `/unitbob:fix <id>` |
-| 5. Open the map | `Open my Unitbob map` | `/unitbob:show` |
+Just type it in the chat. There is nothing to memorise and no command to get right.
+
+| Step | Say this |
+|------|----------|
+| 1. Build the map | `Build my Unitbob map` |
+| 2. Generate tests | `Generate the guardrail tests` |
+| 3. Run the checks | `Run the checks` |
+| 4. Fix a red lamp | `Fix guardrail <id>` |
+| 5. Open the map | `Open my Unitbob map` |
+
+There are also `/unitbob:map`, `/unitbob:suite` and friends, but they work only
+inside a Claude Code terminal, and only in a session started after the plugin was
+installed — in a browser or desktop window they are not recognised at all. The
+phrasings above work everywhere, so they are the ones documented here.
 
 ---
 

package/dist/files/mapBuild.js

@@ -11,6 +11,14 @@ export function requestPath(projectRoot) {
 export function outputPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'map-build', 'map_document.json');
 }
+// The surface inventory (spec 31, step 1) and the grouped surface document
+// (step 2) are the two extra local artifacts of one atomic map build.
+export function surfacesPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'map-build', 'surfaces.json');
+}
+export function surfaceOutputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'map-build', 'surface_document.json');
+}
 export function readFreshGraph(projectRoot) {
     const path = graphPath(projectRoot);
     if (!existsSync(path)) {
@@ -25,6 +33,8 @@ export function writeMapBuildRequest(projectRoot, recipes) {
         project_root: projectRoot,
         graph_path: graphPath(projectRoot),
         output_path: outputPath(projectRoot),
+        surfaces_path: surfacesPath(projectRoot),
+        surface_output_path: surfaceOutputPath(projectRoot),
         recipes,
     };
     const path = requestPath(projectRoot);
@@ -39,7 +49,8 @@ export function readMapBuildRequest(projectRoot) {
     }
     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.`);
+        throw new Error(`${path} is malformed: expected project_root, graph_path, output_path, surfaces_path, ` +
+            'surface_output_path, and recipes.');
     }
     return packet;
 }
@@ -49,6 +60,20 @@ export function readHostMapOutput(path) {
     }
     return parseJson(readFileSync(path, 'utf8'), path);
 }
+// The two surface artifacts are both required before upload: no partial bundle
+// carrying only one lens is ever sent (spec 31, atomic bundle).
+export function readSurfacesInventory(path) {
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — the extract_surfaces step did not write a surfaces inventory.`);
+    }
+    return parseJson(readFileSync(path, 'utf8'), path);
+}
+export function readSurfaceDocument(path) {
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — the decompose_surfaces step did not write a surface document.`);
+    }
+    return parseJson(readFileSync(path, 'utf8'), path);
+}
 function parseJson(raw, path) {
     try {
         return JSON.parse(raw);
@@ -65,9 +90,13 @@ function isMapBuildRequest(value) {
     return (typeof packet.project_root === 'string' &&
         typeof packet.graph_path === 'string' &&
         typeof packet.output_path === 'string' &&
+        typeof packet.surfaces_path === 'string' &&
+        typeof packet.surface_output_path === 'string' &&
         !!recipes &&
         isRecipe(recipes.decompose) &&
-        isRecipe(recipes.relate));
+        isRecipe(recipes.relate) &&
+        isRecipe(recipes.extract_surfaces) &&
+        isRecipe(recipes.decompose_surfaces));
 }
 function isRecipe(value) {
     if (!value || typeof value !== 'object')

package/dist/proc.js

@@ -56,20 +56,70 @@ export async function requireGraphify() {
             `"graphify", needs Python 3.10+), then retry (${err.message}).`);
     }
 }
+// Paths that hold no business logic in the stacks unitbob supports — Rails,
+// JS/TS, Python — and that graphify does not already skip (it drops
+// node_modules, venv, dist, build, target, out, __pycache__, and the framework
+// cache and report dirs on its own).
+//
+// Every entry earns its place, because an over-broad pattern fails silently: a
+// subsystem simply never appears on the map and nobody learns why. Measured on
+// one real Rails app (2943 nodes), vendor/ was 1337 of them, app/assets/ 414,
+// db/migrate/ 314 — 70% of the graph, and the busiest nodes in it were `_()`
+// and `$()`. Everything else in that project was already clean: bin/, tmp/,
+// log/ and storage/ produced zero nodes, so they are deliberately not listed.
+//
+// The list stays language-neutral: one project is often Rails and Python at
+// once. Gitignore syntax; graphify merges it with .gitignore, and it can only
+// ever exclude more, never re-include.
+export const GRAPH_NOISE_PATTERNS = [
+    '# unitbob: keep the graph about your own business code',
+    '.unitbob/',
+    // Third-party code committed into the repo. In Rails, `vendor/` is the
+    // convention for it, and `app/assets/javascripts/` is where sprockets-era
+    // apps dumped libraries — on the measured app that folder was moment.js,
+    // datatables.js and jquery.inputmask, against a single node of own code. A
+    // modern Rails app keeps its own JS in `app/javascript/`, which stays.
+    'vendor/',
+    'app/assets/javascripts/',
+    'app/assets/builds/',
+    'app/assets/config/',
+    'public/assets/',
+    'public/packs/',
+    '*.min.js',
+    '*.min.css',
+    '*.bundle.js',
+    // Generated code: schema history and codegen output. Describes the shape of
+    // data, never the behaviour a guardrail could protect.
+    'db/migrate/',
+    'db/schema.rb',
+    'db/structure.sql',
+    'migrations/',
+    '__generated__/',
+    '*_pb2.py',
+    '*_pb2_grpc.py',
+    '*_pb.js',
+    // Type declarations — a contract for a compiler, with no runtime behaviour.
+    '*.d.ts',
+    '*.pyi',
+];
 export function ensureUnitbobIgnored(projectRoot) {
-    ensureLine(join(projectRoot, '.gitignore'), '.unitbob/');
-    ensureLine(join(projectRoot, '.gitignore'), 'graphify-out/');
-    ensureLine(join(projectRoot, '.graphifyignore'), '.unitbob/');
+    // `.graphifyignore` is unitbob's own bookkeeping, like the other two entries —
+    // the user never edits it, so it stays out of their commits.
+    ensureLines(join(projectRoot, '.gitignore'), ['.unitbob/', 'graphify-out/', '.graphifyignore']);
+    ensureLines(join(projectRoot, '.graphifyignore'), GRAPH_NOISE_PATTERNS);
 }
-function ensureLine(path, line) {
+// Appends whichever lines are missing, in one write, leaving the user's own
+// entries (and their order) untouched. Idempotent: a second run adds nothing.
+function ensureLines(path, lines) {
     let current = '';
-    if (existsSync(path)) {
+    if (existsSync(path))
         current = readFileSync(path, 'utf8');
-        if (current.split('\n').some((existing) => existing.trim() === line))
-            return;
-    }
+    const present = new Set(current.split('\n').map((line) => line.trim()));
+    const missing = lines.filter((line) => !present.has(line));
+    if (missing.length === 0)
+        return;
     const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
-    writeFileSync(path, `${current}${prefix}${line}\n`);
+    writeFileSync(path, `${current}${prefix}${missing.join('\n')}\n`);
 }
 export async function runGraphifyExtractKeyless(projectRoot) {
     // Deterministic AST-only graph; no LLM, no API key. `update --force` re-extracts

package/dist/verbs/mapPrepare.js

@@ -20,9 +20,21 @@ export async function mapPrepare(config, _args = [], deps) {
         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 });
+    const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
+        actual.getRecipe('decompose'),
+        actual.getRecipe('relate'),
+        actual.getRecipe('extract_surfaces'),
+        actual.getRecipe('decompose_surfaces'),
+    ]);
+    const packet = writeMapBuildRequest(config.projectRoot, {
+        decompose,
+        relate,
+        extract_surfaces: extractSurfaces,
+        decompose_surfaces: decomposeSurfaces,
+    });
     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');
+    process.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
+        `${packet.output_path} (recipes.decompose, recipes.relate), and the surface map at ` +
+        `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
+        'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');
 }

package/dist/verbs/putMapBuild.js

@@ -1,16 +1,26 @@
 import { readFileSync } from 'node:fs';
-import { readHostMapOutput, readMapBuildRequest } from "../files/mapBuild.js";
+import { readHostMapOutput, readMapBuildRequest, readSurfaceDocument, readSurfacesInventory, } 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'));
+    // Both lenses must be present locally before anything is sent — the host stores
+    // the bundle atomically or not at all (spec 31). A missing artifact here throws
+    // and no partial upload happens.
     const mapDocument = readHostMapOutput(packet.output_path);
+    const surfaces = readSurfacesInventory(packet.surfaces_path);
+    const surfaceDocument = readSurfaceDocument(packet.surface_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}) ` +
+    const result = await actual.putMapBuild({
+        graph,
+        map_document: mapDocument,
+        surfaces,
+        surface_document: surfaceDocument,
+    });
+    process.stdout.write(`Map uploaded (map ${result.map_digest}, surface ${result.surface_digest}, graph ${result.graph_digest}) ` +
         `${result.reused ? 'reused' : 'created'} version ${result.map_version_id}.\n` +
         `${result.map_url}\n`);
 }

package/dist/wire.js

@@ -40,8 +40,10 @@ export class Wire {
     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.
+    // PUT /repos/:id/map_build — upload the fresh graph and both host-built lenses
+    // (decompose map_document + surfaces inventory + grouped surface_document) as
+    // one atomic bundle. Rails validates both documents, versions, and computes all
+    // digests; either lens failing rejects the whole bundle (spec 31).
     async putMapBuild(payload) {
         const res = await this.send('PUT', this.repoPath('map_build'), payload);
         await this.ensureOk(res, `PUT ${this.repoPath('map_build')}`);

package/package.json

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