@cairnvibe/indexer 0.2.8 → 0.2.10

package/dist/crawl.js

@@ -62,6 +62,8 @@ async function crawlSite(opts) {
                         file: finalUrl,
                         reachableFiles: [],
                         elements: extracted.elements,
+                        dataShapes: [], // no source file to read in crawl mode
+                        inAppCopy: [], // no source file to read in crawl mode
                         renderedText: extracted.bodyText,
                     });
                     if (depth >= maxDepth)
@@ -113,6 +115,8 @@ async function crawlSite(opts) {
         allScannedFiles: [],
         frameworkReachableFiles: [],
         frameworkElements: [],
+        apiRouteHandlers: [], // no source file to read in crawl mode
+        businessRules: [], // no source file to read in crawl mode
     };
 }
 function normalizeForDedup(url) {

package/dist/key-rotator.js

@@ -1,12 +1,24 @@
 "use strict";
-// Round-robins across a comma-separated list of API keys (e.g. `GROQ_API_KEYS`)
-// so a batch of L3 describe calls can spread across several free-tier rate
-// limits instead of hammering a single key.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyRotator = void 0;
+// Round-robins across a comma-separated list of API keys (e.g. `GROQ_API_KEYS`)
+// so a batch of L3 describe calls can spread across several free-tier rate
+// limits instead of hammering a single key. Mirrors packages/sdk/src/
+// key-rotator.ts — small enough that duplicating it beats adding a shared
+// package for it.
+//
+// Real, live-found gap this closes (same one the sdk copy fixes): a key
+// that's genuinely invalid/expired (a real 401 — see llm.ts's
+// isInvalidKeyError) used to just keep getting handed out by `take()` on
+// every pass through the rotation, forever, for the life of this `cairn
+// build` process — wasting a real API round trip and a real retry
+// attempt on a key already proven dead, over and over, on every page
+// that happened to land on it. `markDead` excludes a confirmed-invalid
+// key from rotation for the rest of THIS build.
 class KeyRotator {
     keys;
     next = 0;
+    deadKeys = new Set();
     constructor(keys) {
         if (keys.length === 0)
             throw new Error("KeyRotator: at least one key is required");
@@ -21,10 +33,33 @@ class KeyRotator {
             .filter(Boolean);
         return keys.length > 0 ? new KeyRotator(keys) : null;
     }
+    /** Round-robins across whichever keys haven't been confirmed dead yet.
+     * Falls back to the full original list if every key has been marked
+     * dead — a bounded retry loop still needs something real to try. */
     take() {
-        const key = this.keys[this.next % this.keys.length];
+        const liveKeys = this.keys.filter((k) => !this.deadKeys.has(k));
+        const pool = liveKeys.length > 0 ? liveKeys : this.keys;
+        const key = pool[this.next % pool.length];
         this.next += 1;
         return key;
     }
+    /** Marks a key as confirmed invalid (a real 401, not a rate limit) —
+     * excluded from `take()`'s rotation for the rest of this build. Logs
+     * once per key, naming only its last 4 characters. */
+    markDead(key) {
+        if (this.deadKeys.has(key))
+            return;
+        this.deadKeys.add(key);
+        const remaining = this.keys.length - this.deadKeys.size;
+        console.warn(`[cairn] API key ending in "${key.slice(-4)}" is invalid (confirmed via a real 401) — excluded from rotation for the rest of this build. ${remaining} of ${this.keys.length} configured key(s) remain.`);
+    }
+    /** How many distinct keys are configured. */
+    get size() {
+        return this.keys.length;
+    }
+    /** How many configured keys have NOT been marked dead. */
+    get liveSize() {
+        return this.keys.length - this.deadKeys.size;
+    }
 }
 exports.KeyRotator = KeyRotator;

package/dist/l1-api-routes.js

@@ -0,0 +1,101 @@
+"use strict";
+// L1 addendum — API route handlers (Phase 4, layer 6 of the deep-runtime-
+// context plan: "which pages/components call which APIs"). Still pure AST
+// facts, still deterministic: resolves an HTTP-method export
+// (`export async function POST() {}` or `export const POST = async () =>
+// {}`) in a Next.js App Router `app/api/**/route.ts` file to the real,
+// imported, project-local function names its body actually calls — e.g.
+// `app/api/invoices/route.ts`'s `POST` calling `createInvoice()` from
+// `lib/invoices.ts`. This is the second hop of a real dependency graph
+// whose first hop (a click's onClick -> a `fetch(url, {method})` call)
+// l1-scan.ts's findApiCallIn/resolveHandlerCall already trace — connecting
+// the two tells the agent not just THAT a button calls POST /api/invoices,
+// but WHAT REAL CODE actually runs when it does.
+//
+// Deliberately App Router only (`app/api/**/route.ts`) — Pages Router API
+// routes (`pages/api/*.ts`) export one default handler that dispatches on
+// `req.method` internally, a materially different (and less statically
+// clean) shape; skipped rather than guessed at, same "only claim what's
+// genuinely traceable" discipline as l1-data-shapes.ts's own explicit-
+// return-type-only boundary.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapApiRouteHandlers = mapApiRouteHandlers;
+exports.getCallableBody = getCallableBody;
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+function mapApiRouteHandlers(project, absRoot) {
+    const handlers = [];
+    for (const sf of project.getSourceFiles()) {
+        const url = deriveApiRoute(absRoot, sf.getFilePath());
+        if (!url)
+            continue;
+        const file = toPosix(node_path_1.default.relative(absRoot, sf.getFilePath()));
+        const exported = sf.getExportedDeclarations();
+        for (const method of HTTP_METHODS) {
+            const decls = exported.get(method);
+            if (!decls || decls.length === 0)
+                continue;
+            const calls = new Set();
+            for (const decl of decls) {
+                const body = getCallableBody(decl);
+                if (!body)
+                    continue;
+                for (const name of tracedCallsIn(sf, body))
+                    calls.add(name);
+            }
+            handlers.push({ method, url, file, calls: Array.from(calls).sort() });
+        }
+    }
+    return handlers.sort((a, b) => (a.url === b.url ? a.method.localeCompare(b.method) : a.url.localeCompare(b.url)));
+}
+/** App Router convention only: app/api/**\/route.ts -> /api/... . Null for anything else (Pages Router API, a non-route.ts file, a route.ts outside app/api/). */
+function deriveApiRoute(absRoot, filePath) {
+    const rel = toPosix(node_path_1.default.relative(absRoot, filePath));
+    if (!rel.startsWith("app/api/"))
+        return null;
+    if (!/\/route\.(ts|js)$/.test(rel))
+        return null;
+    return "/" + rel.slice("app/".length).replace(/\/route\.(ts|js)$/, "");
+}
+/** Exported for reuse by l1-business-rules.ts (Phase 4 layer 3) — the same "get the actual callable node, whichever of function-declaration/arrow/function-expression shape it is" resolution, not a second copy. */
+function getCallableBody(decl) {
+    if (ts_morph_1.Node.isFunctionDeclaration(decl) || ts_morph_1.Node.isArrowFunction(decl) || ts_morph_1.Node.isFunctionExpression(decl))
+        return decl;
+    if (ts_morph_1.Node.isVariableDeclaration(decl)) {
+        const init = decl.getInitializer();
+        if (init && (ts_morph_1.Node.isArrowFunction(init) || ts_morph_1.Node.isFunctionExpression(init)))
+            return init;
+    }
+    return null;
+}
+/** Real, imported, project-local function names called anywhere in `body` — same "identifier callee, resolves to a named import whose module isn't node_modules" filter l1-data-shapes.ts's resolveImportedFunction uses, so a library/global call (NextResponse.json, db.prepare) is never mistaken for app logic. */
+function tracedCallsIn(sf, body) {
+    const names = new Set();
+    for (const call of body.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        if (!ts_morph_1.Node.isIdentifier(callee))
+            continue;
+        if (resolvesToProjectFunction(sf, callee.getText()))
+            names.add(callee.getText());
+    }
+    return Array.from(names);
+}
+function resolvesToProjectFunction(sf, name) {
+    for (const imp of sf.getImportDeclarations()) {
+        const named = imp.getNamedImports().find((n) => (n.getAliasNode()?.getText() ?? n.getName()) === name);
+        if (!named)
+            continue;
+        const target = imp.getModuleSpecifierSourceFile();
+        if (!target || target.getFilePath().includes("node_modules"))
+            continue;
+        return true;
+    }
+    return false;
+}
+function toPosix(p) {
+    return p.split(node_path_1.default.sep).join("/");
+}

package/dist/l1-business-rules.js

@@ -0,0 +1,101 @@
+"use strict";
+// L1 addendum — business rules & validation constraints (Phase 4, layer 3
+// of the deep-runtime-context plan: "legal state transitions, validation
+// constraints, permission/role gating... without this the agent can
+// attempt actions that are structurally possible to click but
+// semantically invalid"). Still pure AST facts, still deterministic.
+//
+// Real research before writing this (an Explore-agent pass over
+// examples/demo-app's actual mutating functions) found the honest truth:
+// this app has almost NOTHING resembling a real domain rule — its
+// mutating functions (archiveInvoice, moveCard, updateCard) apply
+// unconditionally, no transition/permission logic anywhere. The one real
+// exception, `lib/shop.ts`'s `placeOrder`, gates on `isLoggedIn()`. What
+// IS genuinely common and real: every API route's own required-field/
+// not-found guards (`if (!body.email) return NextResponse.json(...)`).
+// This extractor reports BOTH kinds uniformly, as "a real guard this
+// function enforces" — it does not, and cannot, reliably tell a domain
+// permission check apart from an input-validation check by AST shape
+// alone; that distinction is left to whoever reads the result.
+//
+// Deliberately reuses l1-api-routes.ts's own already-proven traversal
+// (which route handler exports which HTTP method, which real functions
+// it calls) rather than re-deriving it — resolveImportedFunction is
+// l1-data-shapes.ts's own real declaration resolver, getCallableBody is
+// l1-api-routes.ts's own callable-node resolver; both exported for this,
+// not duplicated.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBusinessRules = extractBusinessRules;
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const l1_data_shapes_1 = require("./l1-data-shapes");
+const l1_api_routes_1 = require("./l1-api-routes");
+function extractBusinessRules(project, absRoot, handlers) {
+    const rules = [];
+    const seen = new Set(); // dedupe: the same guarded function can be called from several routes
+    for (const handler of handlers) {
+        const sf = project.getSourceFile(node_path_1.default.join(absRoot, handler.file));
+        if (!sf)
+            continue;
+        // Guards written directly in the route handler's own body — the
+        // common, real case in practice (required-field/not-found checks).
+        const handlerDecl = sf.getExportedDeclarations().get(handler.method)?.[0];
+        const handlerBody = handlerDecl ? (0, l1_api_routes_1.getCallableBody)(handlerDecl) : null;
+        if (handlerBody)
+            collect(`${handler.method} ${handler.url}`, handlerBody, handler.file, rules, seen);
+        // Guards inside a real function this handler calls — the rarer,
+        // more genuinely domain-flavored case (e.g. placeOrder's isLoggedIn check).
+        for (const callName of handler.calls) {
+            const decl = (0, l1_data_shapes_1.resolveImportedFunction)(sf, callName);
+            const body = decl ? (0, l1_api_routes_1.getCallableBody)(decl) : null;
+            if (!body)
+                continue;
+            const calleeSource = toPosixRel(absRoot, body.getSourceFile().getFilePath());
+            collect(callName, body, calleeSource, rules, seen);
+        }
+    }
+    return rules.sort((a, b) => (a.functionName === b.functionName ? a.condition.localeCompare(b.condition) : a.functionName.localeCompare(b.functionName)));
+}
+function collect(functionName, body, source, rules, seen) {
+    for (const guard of findGuardClauses(body)) {
+        const key = `${functionName}::${guard.condition}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        rules.push({ functionName, condition: guard.condition, consequence: guard.consequence, source });
+    }
+}
+/**
+ * A "guard" = an `if` whose THEN branch is a single return/throw
+ * statement (bare, or the sole statement in a `{ }` block) — the
+ * syntactic shape both a real domain check and a plain input-validation
+ * check share. A multi-statement then-branch is deliberately skipped —
+ * a guard with real side effects beyond returning is a more complex
+ * case this doesn't try to summarize as one simple condition/consequence
+ * pair.
+ */
+function findGuardClauses(body) {
+    const results = [];
+    for (const ifStmt of body.getDescendantsOfKind(ts_morph_1.SyntaxKind.IfStatement)) {
+        const consequenceNode = unwrapSingleStatementBlock(ifStmt.getThenStatement());
+        if (!consequenceNode)
+            continue;
+        if (ts_morph_1.Node.isReturnStatement(consequenceNode) || ts_morph_1.Node.isThrowStatement(consequenceNode)) {
+            results.push({ condition: ifStmt.getExpression().getText(), consequence: consequenceNode.getText() });
+        }
+    }
+    return results;
+}
+function unwrapSingleStatementBlock(stmt) {
+    if (ts_morph_1.Node.isBlock(stmt)) {
+        const statements = stmt.getStatements();
+        return statements.length === 1 ? statements[0] : null;
+    }
+    return stmt;
+}
+function toPosixRel(absRoot, absFile) {
+    return node_path_1.default.relative(absRoot, absFile).split(node_path_1.default.sep).join("/");
+}

package/dist/l1-data-shapes.js

@@ -0,0 +1,154 @@
+"use strict";
+// L1 addendum — data shapes (Phase 4, layer 2 of the deep-runtime-context
+// plan). Still pure AST facts, still deterministic: only EXPLICIT
+// return-type annotations are read, never the type checker's inferred type
+// (`getType()`), matching l1-scan.ts's own "read syntax, not semantics"
+// discipline — a function without an explicit return-type annotation
+// contributes nothing here rather than falling back to checker inference,
+// which is slower and less stable across ts-morph/TS versions.
+//
+// Concretely: for every file reachable from a page (already computed by
+// l1-scan.ts's walkImports), find calls to an imported function whose
+// return type names an interface or object-shaped type alias, and report
+// that type's real fields — e.g. `listInvoices(): Invoice[]` in
+// lib/invoices.ts surfaces Invoice's real `status: "Paid" | "Overdue" |
+// "Archived"` union onto the page that renders it, instead of the agent
+// only ever seeing button labels.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDataShapes = extractDataShapes;
+exports.resolveImportedFunction = resolveImportedFunction;
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+function extractDataShapes(project, absRoot, reachableAbsFiles) {
+    const shapes = new Map();
+    for (const absFile of reachableAbsFiles) {
+        const sf = project.getSourceFile(absFile);
+        if (!sf)
+            continue;
+        for (const call of sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callee = call.getExpression();
+            if (!ts_morph_1.Node.isIdentifier(callee))
+                continue;
+            const decl = resolveImportedFunction(sf, callee.getText());
+            if (!decl)
+                continue;
+            const shape = shapeFromReturnType(decl, absRoot);
+            if (shape && !shapes.has(shape.name))
+                shapes.set(shape.name, shape);
+        }
+    }
+    return Array.from(shapes.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Finds the declaration an imported identifier resolves to — a top-level function or a const-assigned arrow/function expression — in its own module. Exported for reuse by l1-business-rules.ts (Phase 4 layer 3), which needs the real declaration itself (to walk its body), not just its name. */
+function resolveImportedFunction(sf, name) {
+    for (const imp of sf.getImportDeclarations()) {
+        const named = imp.getNamedImports().find((n) => (n.getAliasNode()?.getText() ?? n.getName()) === name);
+        if (!named)
+            continue;
+        const target = imp.getModuleSpecifierSourceFile();
+        if (!target)
+            continue;
+        const realName = named.getName();
+        const fn = target.getFunctions().find((f) => f.getName() === realName);
+        if (fn)
+            return fn;
+        return target.getVariableDeclarations().find((d) => d.getName() === realName);
+    }
+    return undefined;
+}
+function shapeFromReturnType(decl, absRoot) {
+    let returnTypeNode;
+    if (ts_morph_1.Node.isFunctionDeclaration(decl)) {
+        returnTypeNode = decl.getReturnTypeNode();
+    }
+    else if (ts_morph_1.Node.isVariableDeclaration(decl)) {
+        const init = decl.getInitializer();
+        if (init && (ts_morph_1.Node.isArrowFunction(init) || ts_morph_1.Node.isFunctionExpression(init))) {
+            returnTypeNode = init.getReturnTypeNode();
+        }
+    }
+    if (!returnTypeNode)
+        return null;
+    const typeName = baseTypeName(returnTypeNode);
+    if (!typeName)
+        return null;
+    const found = findTypeDeclaration(returnTypeNode.getSourceFile(), typeName);
+    if (!found)
+        return null;
+    if (found.iface) {
+        const iface = found.iface;
+        const fields = iface
+            .getProperties()
+            .map((p) => ({ name: p.getName(), type: p.getTypeNode()?.getText() ?? "unknown", optional: p.hasQuestionToken() }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        return { name: iface.getName(), fields, source: toPosixRel(absRoot, iface.getSourceFile().getFilePath()) };
+    }
+    const alias = found.alias;
+    const aliasTypeNode = alias.getTypeNode();
+    if (!aliasTypeNode || !ts_morph_1.Node.isTypeLiteral(aliasTypeNode))
+        return null; // union/primitive aliases aren't a "shape" — no fields to report
+    const fields = aliasTypeNode
+        .getMembers()
+        .filter(ts_morph_1.Node.isPropertySignature)
+        .map((p) => ({ name: p.getName(), type: p.getTypeNode()?.getText() ?? "unknown", optional: p.hasQuestionToken() }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { name: alias.getName(), fields, source: toPosixRel(absRoot, alias.getSourceFile().getFilePath()) };
+}
+/**
+ * A return-type annotation (`BoardColumn[]`) very often names a type that's
+ * only IMPORTED into this file, not declared here — types split into their
+ * own `*-types.ts` module is a common real convention (this repo's own
+ * demo-app does it, for a real reason: keeping a server-only db import out
+ * of a "use client" component's bundle). Falls back to the file's own
+ * imports, one hop, before giving up — not a general module-resolution
+ * walk, just enough to cover the common "split types file" shape.
+ */
+function findTypeDeclaration(sf, typeName) {
+    const localIface = sf.getInterface(typeName);
+    if (localIface)
+        return { iface: localIface };
+    const localAlias = sf.getTypeAlias(typeName);
+    if (localAlias)
+        return { alias: localAlias };
+    for (const imp of sf.getImportDeclarations()) {
+        const named = imp.getNamedImports().find((n) => (n.getAliasNode()?.getText() ?? n.getName()) === typeName);
+        if (!named)
+            continue;
+        const target = imp.getModuleSpecifierSourceFile();
+        if (!target)
+            continue;
+        const realName = named.getName();
+        const iface = target.getInterface(realName);
+        if (iface)
+            return { iface };
+        const alias = target.getTypeAlias(realName);
+        if (alias)
+            return { alias };
+    }
+    return null;
+}
+/** Strips `[]` and a `| null` / `| undefined` union member, then requires a plain named type reference (no generics like `Promise<X>` — out of scope for v1). */
+function baseTypeName(typeNode) {
+    let node = typeNode;
+    if (ts_morph_1.Node.isArrayTypeNode(node)) {
+        node = node.getElementTypeNode();
+    }
+    if (ts_morph_1.Node.isUnionTypeNode(node)) {
+        const members = node.getTypeNodes().filter((n) => n.getText() !== "null" && n.getText() !== "undefined");
+        if (members.length !== 1)
+            return null;
+        node = members[0];
+        if (ts_morph_1.Node.isArrayTypeNode(node))
+            node = node.getElementTypeNode();
+    }
+    if (ts_morph_1.Node.isTypeReference(node)) {
+        return node.getTypeName().getText();
+    }
+    return null;
+}
+function toPosixRel(absRoot, absFile) {
+    return node_path_1.default.relative(absRoot, absFile).split(node_path_1.default.sep).join("/");
+}

package/dist/l1-in-app-copy.js

@@ -0,0 +1,52 @@
+"use strict";
+// L1 addendum — in-app copy (Phase 4, layer 4 of the deep-runtime-context
+// plan: "help text, tooltips, onboarding copy... real authored semantics
+// to mine instead of only LLM-guessed purpose"). Still pure AST facts,
+// still deterministic: walks a page's own reachable files (the same set
+// l1-scan.ts already computes) for heading/paragraph JSX elements and
+// extracts their real text content — the same JSX-text-reading logic
+// l1-scan.ts already uses for an interactive element's own label, just
+// applied to the NON-interactive elements around it.
+//
+// Confirmed real, not hypothetical, before writing this: examples/demo-app's
+// own pages each open with a real, human-authored <h1>/<p> pair
+// ("Invoices" / "Every invoice you've sent, with its status and amount.")
+// that today's L3 LLM-generated purpose/title can only ever GUESS at,
+// even though the real answer is sitting right there in the source.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractInAppCopy = extractInAppCopy;
+const ts_morph_1 = require("ts-morph");
+const l1_scan_1 = require("./l1-scan");
+const COPY_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6", "p"]);
+/**
+ * @param reachableAbsFiles Absolute paths, same set l1-scan.ts already
+ * computed for this page (its own file plus every file it imports).
+ * @param relPathOf Converts an absolute path back to the same repo-
+ * relative, posix-separated form every other L1 fact uses — passed in
+ * rather than reimplemented, so this module never has its own opinion
+ * about path formatting.
+ */
+function extractInAppCopy(project, reachableAbsFiles, relPathOf) {
+    const blocks = [];
+    for (const absFile of reachableAbsFiles) {
+        const sf = project.getSourceFile(absFile);
+        if (!sf)
+            continue;
+        const relFile = relPathOf(absFile);
+        const nodes = [...sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxOpeningElement), ...sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxSelfClosingElement)];
+        for (const node of nodes) {
+            const tag = node.getTagNameNode().getText().toLowerCase();
+            if (!COPY_TAGS.has(tag))
+                continue;
+            // Self-closing copy elements (<p />) never carry text — only
+            // getElementText's own JsxElement-children path can find any.
+            if (node.getKind() !== ts_morph_1.SyntaxKind.JsxOpeningElement)
+                continue;
+            const text = (0, l1_scan_1.getElementText)(node);
+            if (!text)
+                continue;
+            blocks.push({ tag: tag, text, file: relFile, line: node.getStartLineNumber() });
+        }
+    }
+    return blocks.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)));
+}

package/dist/l1-scan.js

@@ -8,9 +8,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanL1 = scanL1;
+exports.getElementText = getElementText;
 const node_path_1 = __importDefault(require("node:path"));
 const ts_morph_1 = require("ts-morph");
 const routes_1 = require("./routes");
+const l1_data_shapes_1 = require("./l1-data-shapes");
+const l1_api_routes_1 = require("./l1-api-routes");
+const l1_in_app_copy_1 = require("./l1-in-app-copy");
+const l1_business_rules_1 = require("./l1-business-rules");
 const INTERACTIVE_TAGS = new Set(["button", "a", "form", "input"]);
 const DEFAULT_ROOTS = ["app", "components", "lib", "pages"];
 // Files the framework invokes directly rather than a page importing them —
@@ -76,11 +81,14 @@ function scanL1(rootDir) {
         const reachable = new Set();
         const elements = [];
         walkImports(pageFile, absRoot, reachable, elements, new Set());
+        const reachableAbsFiles = Array.from(reachable).map((rel) => node_path_1.default.join(absRoot, rel));
         return {
             route: deriveRoute(absRoot, pageFile.getFilePath()),
             file: toPosix(node_path_1.default.relative(absRoot, pageFile.getFilePath())),
             reachableFiles: Array.from(reachable).sort(),
             elements: elements.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file))),
+            dataShapes: (0, l1_data_shapes_1.extractDataShapes)(project, absRoot, reachableAbsFiles),
+            inAppCopy: (0, l1_in_app_copy_1.extractInAppCopy)(project, reachableAbsFiles, (absPath) => toPosix(node_path_1.default.relative(absRoot, absPath))),
         };
     });
     pages.sort((a, b) => a.route.localeCompare(b.route));
@@ -97,12 +105,15 @@ function scanL1(rootDir) {
         // can describe them once and the manifest can attach them to every page.
         walkImports(sf, absRoot, frameworkReachable, frameworkElements, frameworkVisited);
     }
+    const apiRouteHandlers = (0, l1_api_routes_1.mapApiRouteHandlers)(project, absRoot);
     return {
         version: "1",
         pages,
         allScannedFiles,
         frameworkReachableFiles: Array.from(frameworkReachable).sort(),
         frameworkElements: frameworkElements.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file))),
+        apiRouteHandlers,
+        businessRules: (0, l1_business_rules_1.extractBusinessRules)(project, absRoot, apiRouteHandlers),
     };
 }
 function walkImports(sf, absRoot, reachableRel, elements, visitedAbs) {
@@ -211,20 +222,48 @@ function getAttrInitializerNode(attrs, name) {
     }
     return undefined;
 }
+/** Exported for reuse by l1-in-app-copy.ts (Phase 4 layer 4) — the exact
+ * same "read a JSX element's own text" logic, not a second copy.
+ *
+ * Real, live-found bug this fixes: only DIRECT JsxText children were ever
+ * read — an element whose label sits inside a wrapper (`<a><span><Icon/>
+ * Go to Invoices</span></a>`, an extremely common real-world icon+label
+ * pattern, confirmed live in examples/demo-app's own landing page) came
+ * back with NO text at all. With no text and no aria-label, manifest.ts's
+ * elementFallbackSelector had nothing to fall back to but the bare tag
+ * name ("a") — a selector matching every link on the page, useless for
+ * actually finding the ONE the manifest meant. That's the real, traced
+ * cause of "Could not find that element on the page" repeating for the
+ * landing page's own nav cards — not a runtime bug at all, a static-
+ * analysis gap in how a label gets extracted in the first place. Now
+ * recurses into nested JsxElement children (never into a JsxExpression's
+ * `{dynamic value}` or a JsxSelfClosingElement icon, which have no real
+ * static text to read) so any REAL, human-authored text anywhere inside
+ * the element is found, no matter how deeply it's wrapped. */
 function getElementText(opening) {
     const parent = opening.getParentIfKind(ts_morph_1.SyntaxKind.JsxElement);
     if (!parent)
         return null;
     const texts = [];
-    for (const child of parent.getJsxChildren()) {
+    collectJsxText(parent, texts);
+    const joined = texts.join(" ").trim().replace(/\s+/g, " ");
+    return joined.length > 0 ? joined : null;
+}
+function collectJsxText(element, texts) {
+    for (const child of element.getJsxChildren()) {
         if (ts_morph_1.Node.isJsxText(child)) {
             const t = child.getText().trim().replace(/\s+/g, " ");
             if (t)
                 texts.push(t);
         }
+        else if (ts_morph_1.Node.isJsxElement(child)) {
+            collectJsxText(child, texts);
+        }
+        // JsxSelfClosingElement (an icon like <FileText/>) and JsxExpression
+        // (a dynamic value like {count}) are deliberately skipped — neither
+        // has real static text to read, and a dynamic value must never be
+        // guessed at.
     }
-    const joined = texts.join(" ").trim();
-    return joined.length > 0 ? joined : null;
 }
 function resolveHandlerCall(sf, initializer) {
     if (!initializer)

package/dist/llm.js

@@ -114,10 +114,30 @@ exports.AnthropicDescribeClient = AnthropicDescribeClient;
 // Model list changes over time — verified live against GET /openai/v1/models
 // while building this; check that endpoint again if this starts 404ing.
 const GROQ_DEFAULT_MODEL = "openai/gpt-oss-120b";
+/**
+ * Same defensive-shape-checking approach as concurrency.ts's own
+ * error-inspection helpers — checked directly against the real Groq API
+ * before writing this (not guessed): a real 401 from an invalid/expired
+ * key throws with `.status === 401` and a doubly-nested
+ * `.error.error.code === "invalid_api_key"`.
+ */
+function isInvalidKeyError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.status === 401)
+        return true;
+    const code = e.code ?? e.error?.code ?? e.error?.error?.code;
+    if (code === "invalid_api_key")
+        return true;
+    const message = typeof e.message === "string" ? e.message : "";
+    return message.includes("invalid_api_key") || message.includes("Invalid API Key");
+}
 class GroqDescribeClient {
     keys;
     model;
-    constructor(options) {
+    clientFactory;
+    constructor(options, clientFactory = (apiKey) => new groq_sdk_1.default({ apiKey })) {
         const rotator = options?.apiKeys
             ? new key_rotator_1.KeyRotator(options.apiKeys)
             : key_rotator_1.KeyRotator.fromEnvList(process.env.GROQ_API_KEYS);
@@ -126,33 +146,58 @@ class GroqDescribeClient {
         }
         this.keys = rotator;
         this.model = options?.model ?? process.env.GROQ_MODEL ?? GROQ_DEFAULT_MODEL;
+        this.clientFactory = clientFactory;
     }
     async describePage(input) {
-        const client = new groq_sdk_1.default({ apiKey: this.keys.take() });
         const userContent = buildUserContent(input);
-        const completion = await client.chat.completions.create({
-            model: this.model,
-            messages: [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userContent },
-            ],
-            tools: [
-                {
-                    type: "function",
-                    function: {
-                        name: DESCRIBE_TOOL_NAME,
-                        description: DESCRIBE_TOOL.description,
-                        parameters: DESCRIBE_TOOL.input_schema,
-                    },
-                },
-            ],
-            tool_choice: { type: "function", function: { name: DESCRIBE_TOOL_NAME } },
-        });
-        const toolCall = completion.choices[0]?.message?.tool_calls?.[0];
-        if (!toolCall) {
-            throw new Error(`L3 describe (groq): no tool call in response for ${input.route}`);
+        // Real, live-found gap this closes: a genuinely dead/expired key used
+        // to just throw straight out of this method on every page that
+        // happened to land on it via round-robin, for the entire build —
+        // wasting a real API round trip on a key already proven dead, over
+        // and over. A bounded loop over the real configured key count,
+        // separate from (and orthogonal to) withRetry's own 429/5xx backoff
+        // retries at the caller — an invalid key isn't a transient condition
+        // that backing off helps with, it's a permanent fact about that one
+        // key, so this retries IMMEDIATELY on a different key instead of
+        // waiting. See KeyRotator.markDead's own doc comment.
+        const maxKeyAttempts = Math.max(this.keys.size, 1);
+        for (let attempt = 0;; attempt++) {
+            const key = this.keys.take();
+            try {
+                const client = this.clientFactory(key);
+                const completion = await client.chat.completions.create({
+                    model: this.model,
+                    messages: [
+                        { role: "system", content: SYSTEM_PROMPT },
+                        { role: "user", content: userContent },
+                    ],
+                    tools: [
+                        {
+                            type: "function",
+                            function: {
+                                name: DESCRIBE_TOOL_NAME,
+                                description: DESCRIBE_TOOL.description,
+                                parameters: DESCRIBE_TOOL.input_schema,
+                            },
+                        },
+                    ],
+                    tool_choice: { type: "function", function: { name: DESCRIBE_TOOL_NAME } },
+                });
+                const toolCall = completion.choices[0]?.message?.tool_calls?.[0];
+                if (!toolCall) {
+                    throw new Error(`L3 describe (groq): no tool call in response for ${input.route}`);
+                }
+                return toPageDescription(JSON.parse(toolCall.function.arguments));
+            }
+            catch (err) {
+                if (isInvalidKeyError(err)) {
+                    this.keys.markDead(key);
+                    if (attempt < maxKeyAttempts - 1)
+                        continue;
+                }
+                throw err;
+            }
         }
-        return toPageDescription(JSON.parse(toolCall.function.arguments));
     }
 }
 exports.GroqDescribeClient = GroqDescribeClient;

package/dist/manifest.js

@@ -4,10 +4,26 @@ exports.assembleManifest = assembleManifest;
 exports.parseApiCall = parseApiCall;
 const node_child_process_1 = require("node:child_process");
 function assembleManifest(rootDir, facts, l2, l3) {
-    const globalElements = facts.frameworkElements.map((el) => toManifestElement(el, l3.globalElements.find((e) => e.id === el.id), "present in the root layout"));
+    // Phase 4, layer 6 — keyed once per build, not per element, so
+    // enriching every element's apiCall stays a cheap map lookup.
+    const routeHandlersByKey = new Map(facts.apiRouteHandlers.map((h) => [`${h.method} ${h.url}`, h]));
+    // Phase 4, layer 3 — keyed by BusinessRule.functionName, which is
+    // EITHER a route key ("POST /api/shop/checkout", for a guard written
+    // directly in the handler) OR a real called function's own name (for
+    // a guard found inside it) — see enrichApiCall for how both get
+    // looked up together for one apiCall.
+    const businessRulesByKey = new Map();
+    for (const rule of facts.businessRules) {
+        const existing = businessRulesByKey.get(rule.functionName);
+        if (existing)
+            existing.push(rule);
+        else
+            businessRulesByKey.set(rule.functionName, [rule]);
+    }
+    const globalElements = facts.frameworkElements.map((el) => toManifestElement(el, l3.globalElements.find((e) => e.id === el.id), "present in the root layout", routeHandlersByKey, businessRulesByKey));
     const pages = facts.pages.map((rawPage) => {
         const desc = l3.descriptions.get(rawPage.route);
-        const ownElements = rawPage.elements.map((el) => toManifestElement(el, desc?.elements.find((e) => e.id === el.id), `reachable from route ${rawPage.route}`));
+        const ownElements = rawPage.elements.map((el) => toManifestElement(el, desc?.elements.find((e) => e.id === el.id), `reachable from route ${rawPage.route}`, routeHandlersByKey, businessRulesByKey));
         return {
             id: slugifyRoute(rawPage.route),
             route: rawPage.route,
@@ -17,6 +33,8 @@ function assembleManifest(rootDir, facts, l2, l3) {
             whenToUse: desc?.whenToUse ?? "Unknown — no description generated for this page.",
             confidence: desc?.confidence ?? 0,
             elements: [...ownElements, ...globalElements],
+            dataShapes: rawPage.dataShapes,
+            inAppCopy: rawPage.inAppCopy,
         };
     });
     return {
@@ -62,7 +80,7 @@ function parseApiCall(handlerCall) {
         return null;
     return { method: method, url };
 }
-function toManifestElement(el, elDesc, baseEvidence) {
+function toManifestElement(el, elDesc, baseEvidence, routeHandlersByKey, businessRulesByKey) {
     const evidence = [baseEvidence];
     if (el.handlerCall)
         evidence.push(`onClick calls ${el.handlerCall}`);
@@ -76,9 +94,35 @@ function toManifestElement(el, elDesc, baseEvidence) {
         does: elDesc?.does ?? "Unknown — no description generated for this element.",
         confidence: elDesc?.confidence ?? 0,
         evidence,
-        apiCall: parseApiCall(el.handlerCall),
+        apiCall: enrichApiCall(parseApiCall(el.handlerCall), routeHandlersByKey, businessRulesByKey),
     };
 }
+/** Phase 4, layer 6 — attaches the real backend function name(s) that
+ * actually run when this apiCall fires, when Cairn found and traced the
+ * matching route handler (l1-api-routes.ts). Absent when no handler
+ * matched — a route Cairn didn't scan, or one whose body called nothing
+ * traceable — never invented. Phase 4, layer 3 — ALSO attaches any real
+ * guard clauses found either in the route handler's own body or in a
+ * function it calls (l1-business-rules.ts), formatted as readable
+ * "condition → consequence" strings. Absent when none were found —
+ * most real mutating functions in a typical app have none (confirmed
+ * live against examples/demo-app before building this), which is a
+ * real, honest finding, not a bug in the extractor. */
+function enrichApiCall(apiCall, routeHandlersByKey, businessRulesByKey) {
+    if (!apiCall)
+        return null;
+    let enriched = apiCall;
+    const handler = routeHandlersByKey.get(`${apiCall.method} ${apiCall.url}`);
+    if (handler && handler.calls.length > 0)
+        enriched = { ...enriched, handledBy: handler.calls };
+    const relevantFunctionNames = [`${apiCall.method} ${apiCall.url}`, ...(enriched.handledBy ?? [])];
+    const constraints = relevantFunctionNames
+        .flatMap((name) => businessRulesByKey.get(name) ?? [])
+        .map((rule) => `${rule.condition} → ${rule.consequence}`);
+    if (constraints.length > 0)
+        enriched = { ...enriched, constraints };
+    return enriched;
+}
 function elementFallbackSelector(el) {
     if (el.ariaLabel)
         return `[aria-label='${el.ariaLabel}']`;

package/dist/setup.js

@@ -171,8 +171,21 @@ async function runSetup(dir) {
             (0, node_child_process_1.execSync)(`npm install ${PACKAGES.join(" ")}`, { cwd: absDir, stdio: "pipe" });
             spinner.stop((0, ui_1.green)(`✓ installed ${PACKAGES.join(", ")}`));
         }
-        catch {
+        catch (err) {
             spinner.stop((0, ui_1.red)("✗ npm install failed"));
+            // Real, live-found bug this closes: `catch {}` (no bound error) threw
+            // away npm's own stderr — the ONE thing that actually explains why it
+            // failed (a real registry error, an ERESOLVE conflict, a permissions
+            // problem, no network) — leaving a user with nothing but "failed, try
+            // again," which just fails the same way for the same unknown reason.
+            // execSync's thrown error carries the captured output on
+            // `.stderr`/`.stdout` (Buffers, from the `stdio: "pipe"` above) even
+            // though the command itself never printed anything to this process's
+            // own stderr — surface it instead of discarding it.
+            const e = err;
+            const detail = (e.stderr?.toString().trim() || e.stdout?.toString().trim() || "").trim();
+            if (detail)
+                console.error(`\n${detail}\n`);
             console.error(`Install these yourself and re-run \`cairn setup\`:\n  npm install ${PACKAGES.join(" ")}`);
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/indexer",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Cairn's analyzer and installer (the `cairn` CLI) — scans Next.js source or crawls any running app, and scaffolds the backend either way.",
   "license": "MIT",
   "publishConfig": { "access": "public" },