@cairnvibe/indexer 0.1.0 → 0.2.0

package/dist/cli.js

@@ -17,6 +17,7 @@ const manifest_1 = require("./manifest");
 const diff_1 = require("./diff");
 const docs_1 = require("./docs");
 const init_1 = require("./init");
+const setup_1 = require("./setup");
 function parseArgs(rest) {
     const positional = [];
     const flags = {};
@@ -43,11 +44,20 @@ async function main() {
     }
     if (command === "build") {
         const provider = flags.provider === "groq" ? "groq" : "anthropic";
-        if (provider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
+        const keyMissing = provider === "anthropic" ? !process.env.ANTHROPIC_API_KEY : !process.env.GROQ_API_KEYS;
+        if (keyMissing && "if-configured" in flags) {
+            // Used by the prebuild hook `cairn setup` wires in: a deploy with no key
+            // set yet (e.g. the very first one, before env vars are configured on the
+            // hosting platform) skips this step instead of failing the whole build —
+            // the app still builds and runs, just without an updated manifest.
+            console.error(`cairn build --if-configured: no key set for ${provider} — skipping, leaving any existing ui-manifest.json as-is.`);
+            return;
+        }
+        if (provider === "anthropic" && keyMissing) {
             console.error("cairn build: ANTHROPIC_API_KEY is not set. Export it, or pass --provider groq, and re-run.");
             process.exit(1);
         }
-        if (provider === "groq" && !process.env.GROQ_API_KEYS) {
+        if (provider === "groq" && keyMissing) {
             console.error("cairn build --provider groq: GROQ_API_KEYS is not set (comma-separated). Export it and re-run.");
             process.exit(1);
         }
@@ -92,6 +102,10 @@ async function main() {
         console.error(`wrote ${outPath}`);
         return;
     }
+    if (command === "setup") {
+        await (0, setup_1.runSetup)(dir);
+        return;
+    }
     if (command === "init") {
         const result = (0, init_1.runInit)(dir);
         console.error(`cairn init: detected ${result.framework}.`);
@@ -129,7 +143,8 @@ async function main() {
         return;
     }
     console.error("usage:");
-    console.error("  cairn init <dir>   (scaffolds the API route/server + .env.example, detects your framework)");
+    console.error("  cairn setup [dir]   (the one-command path: installs deps, asks for keys — skippable, wires the widget in, builds once, auto-rebuilds on future `npm run build`)");
+    console.error("  cairn init <dir>   (scaffolds the API route/server + .env.example, detects your framework — no prompts, no installs)");
     console.error("  cairn scan <dir>");
     console.error("  cairn build <dir> [--provider anthropic|groq]   (Next.js source scan)");
     console.error("  cairn build <url> [--provider anthropic|groq] [--out <dir>] [--storage-state <file>]   (any framework — crawls a running app; --storage-state replays a saved logged-in session for auth-gated apps)");

package/dist/init.js

@@ -67,7 +67,7 @@ function runInit(dir) {
     }
     else {
         writeIfAbsent(node_path_1.default.join(absDir, "cairn-server.cjs"), STANDALONE_SERVER, result);
-        result.nextSteps.push("1. cp .env.example .env and fill in your key(s).", "2. npm install express @cairnvibe/sdk @cairnvibe/core   (@cairnvibe/sdk isn't on npm yet — see README.md's Quick start for the file: install path)", "3. Start your app, then: npx cairn build http://localhost:PORT   (crawls the running app — works for any framework)", "4. node cairn-server.cjs   (the copilot backend, separate from your app's own server)", "5. Add this to your HTML, pointed at wherever cairn-server.cjs is running:", '   <script src="/cairn-widget.js"></script>', '   <cairn-widget endpoint="http://localhost:4000/api/copilot"></cairn-widget>', "   (copy node_modules/@cairnvibe/sdk/dist/cairn-widget.js into your app's static assets as cairn-widget.js)");
+        result.nextSteps.push("1. cp .env.example .env and fill in your key(s).", "2. npm install express @cairnvibe/sdk @cairnvibe/core", "3. Start your app, then: npx cairn build http://localhost:PORT   (crawls the running app — works for any framework)", "4. node cairn-server.cjs   (the copilot backend, separate from your app's own server)", "5. Add this to your HTML, pointed at wherever cairn-server.cjs is running:", '   <script src="/cairn-widget.js"></script>', '   <cairn-widget endpoint="http://localhost:4000/api/copilot"></cairn-widget>', "   (copy node_modules/@cairnvibe/sdk/dist/cairn-widget.js into your app's static assets as cairn-widget.js)");
     }
     return result;
 }

package/dist/inject-widget.js

@@ -0,0 +1,108 @@
+"use strict";
+// `cairn setup`'s one departure from `init`'s "never touch an existing
+// file" rule — but only for this one, narrow, reversible edit (adding an
+// import + one JSX tag), and only ever via a real AST parse, never blind
+// string splicing. Any structure this doesn't recognize falls back to
+// printing the two-line manual instruction instead of guessing — the
+// same "don't corrupt what you don't understand" discipline `init` uses
+// for whole files, applied here at the node level.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectWidget = injectWidget;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const WIDGET_JSX = `<Copilot registeredActions={[]} onDo={(action, target) => { /* run it through your own auth */ }} />`;
+function findLayoutFile(absDir, framework) {
+    const candidates = framework === "next-app-router"
+        ? ["app/layout.tsx", "app/layout.jsx"]
+        : ["pages/_app.tsx", "pages/_app.jsx"];
+    for (const c of candidates) {
+        const p = node_path_1.default.join(absDir, c);
+        if (node_fs_1.default.existsSync(p))
+            return p;
+    }
+    return null;
+}
+function injectWidget(dir, framework) {
+    const absDir = node_path_1.default.resolve(dir);
+    const target = findLayoutFile(absDir, framework);
+    if (!target) {
+        return { injected: false, reason: "no app/layout.tsx or pages/_app.tsx found — add <Copilot/> manually" };
+    }
+    const relTarget = node_path_1.default.relative(absDir, target) || target;
+    const original = node_fs_1.default.readFileSync(target, "utf8");
+    if (original.includes("@cairnvibe/sdk") || original.includes("<Copilot")) {
+        return { injected: false, reason: `${relTarget} already references Copilot — leaving it alone` };
+    }
+    try {
+        const project = new ts_morph_1.Project({
+            useInMemoryFileSystem: false,
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: { jsx: ts_morph_1.ts.JsxEmit.ReactJSX, allowJs: true, esModuleInterop: true, target: ts_morph_1.ts.ScriptTarget.ES2022 },
+        });
+        const sf = project.addSourceFileAtPath(target);
+        const hasImport = sf.getImportDeclarations().some((d) => d.getModuleSpecifierValue() === "@cairnvibe/sdk");
+        if (!hasImport) {
+            sf.addImportDeclaration({ moduleSpecifier: "@cairnvibe/sdk", namedImports: ["Copilot"] });
+        }
+        // `insertText` at a position, not `replaceWithText` on a node — the latter
+        // asks ts-morph to structurally reconcile old vs. new trees, which fails
+        // ("children of the old and new trees were expected to have the same
+        // count") the moment the replacement text contains a whole new element
+        // rather than equivalent-shaped content. Plain positional insertion has
+        // no tree to reconcile, so it can't hit that class of error.
+        let inserted = false;
+        // App Router: insert right before </body>, wherever it is in the tree.
+        const bodyOpening = sf
+            .getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxOpeningElement)
+            .find((el) => el.getTagNameNode().getText() === "body");
+        if (bodyOpening) {
+            const closing = bodyOpening.getParentIfKind(ts_morph_1.SyntaxKind.JsxElement)?.getClosingElement();
+            if (closing) {
+                sf.insertText(closing.getStart(), `${WIDGET_JSX}\n      `);
+                inserted = true;
+            }
+        }
+        // App Router fallback: a custom layout with no literal <body> — drop it right after {children}.
+        if (!inserted) {
+            const childrenExpr = sf
+                .getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxExpression)
+                .find((e) => e.getExpression()?.getText() === "children");
+            if (childrenExpr) {
+                sf.insertText(childrenExpr.getEnd(), `\n      ${WIDGET_JSX}`);
+                inserted = true;
+            }
+        }
+        // Pages Router: wrap the returned <Component .../> as a sibling inside a fragment,
+        // wherever it sits (works whether or not it's already inside other providers).
+        // Insert the closing half first so the earlier (opening-half) position isn't shifted yet.
+        if (!inserted) {
+            const componentTag = sf
+                .getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxSelfClosingElement)
+                .find((el) => el.getTagNameNode().getText() === "Component");
+            if (componentTag) {
+                // Capture both positions before either insertText call — the node
+                // reference goes stale ("removed or forgotten") the instant the
+                // first insertion changes the source text underneath it.
+                const start = componentTag.getStart();
+                const end = componentTag.getEnd();
+                sf.insertText(end, `\n      ${WIDGET_JSX}\n    </>`);
+                sf.insertText(start, `<>\n      `);
+                inserted = true;
+            }
+        }
+        if (!inserted) {
+            return { injected: false, reason: `couldn't find a safe spot in ${relTarget} — add <Copilot/> manually` };
+        }
+        sf.saveSync();
+        return { injected: true, filePath: target };
+    }
+    catch (err) {
+        // Never leave a half-written file — ts-morph only writes on saveSync(),
+        // so a thrown error here means the original file on disk is untouched.
+        return { injected: false, reason: `couldn't safely modify ${relTarget} (${err.message}) — add <Copilot/> manually` };
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,42 @@
+"use strict";
+// A tiny prompt helper for `cairn setup` — built on Node's own `readline`
+// deliberately, not a new dependency, for something this small. Every
+// prompt this module offers is skippable: an empty answer means "skip,"
+// never a forced choice, matching setup's whole "ask, don't require"
+// design.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closePrompts = closePrompts;
+exports.ask = ask;
+exports.askYesNo = askYesNo;
+exports.askOptional = askOptional;
+const node_readline_1 = __importDefault(require("node:readline"));
+let sharedInterface = null;
+function rl() {
+    if (!sharedInterface) {
+        sharedInterface = node_readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    }
+    return sharedInterface;
+}
+function closePrompts() {
+    sharedInterface?.close();
+    sharedInterface = null;
+}
+function ask(question) {
+    return new Promise((resolve) => rl().question(question, (answer) => resolve(answer.trim())));
+}
+/** A yes/no prompt. Empty answer (just pressing enter) takes `fallback`. */
+async function askYesNo(question, fallback) {
+    const suffix = fallback ? " [Y/n] " : " [y/N] ";
+    const answer = (await ask(question + suffix)).toLowerCase();
+    if (!answer)
+        return fallback;
+    return answer.startsWith("y");
+}
+/** A free-text prompt where an empty answer means "skip this." Returns null when skipped. */
+async function askOptional(question) {
+    const answer = await ask(question);
+    return answer.length > 0 ? answer : null;
+}

package/dist/setup.js

@@ -0,0 +1,175 @@
+"use strict";
+// `cairn setup` — the one-command onboarding path: install what's
+// needed, ask only for what's actually optional (skippable), scaffold
+// the backend, wire the widget into the real layout file, build the
+// manifest once now, and leave a `prebuild` hook so it rebuilds itself
+// on every future `npm run build` without another manual step.
+//
+// Deliberately layered on top of `runInit` rather than replacing it —
+// `init` stays the safe, deterministic, non-interactive primitive
+// (never touches an existing file, never installs anything, never
+// prompts); `setup` is the opinionated wizard built from those same
+// primitives plus the two things `init` intentionally doesn't do:
+// install dependencies and edit an existing layout file.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetup = runSetup;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const init_1 = require("./init");
+const inject_widget_1 = require("./inject-widget");
+const prompt_1 = require("./prompt");
+const l1_scan_1 = require("./l1-scan");
+const l2_reachability_1 = require("./l2-reachability");
+const l3_describe_1 = require("./l3-describe");
+const llm_1 = require("./llm");
+const manifest_1 = require("./manifest");
+const core_1 = require("@cairnvibe/core");
+const PACKAGES = ["@cairnvibe/core", "@cairnvibe/sdk", "@cairnvibe/indexer"];
+function readPackageJson(absDir) {
+    const p = node_path_1.default.join(absDir, "package.json");
+    if (!node_fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function alreadyInstalled(pkg) {
+    if (!pkg)
+        return false;
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return PACKAGES.every((p) => !!deps[p]);
+}
+async function runSetup(dir) {
+    const absDir = node_path_1.default.resolve(dir);
+    console.log(`cairn setup: looking at ${absDir}\n`);
+    // 1. Scaffold what init already safely can — framework detection, the
+    // backend route, .env.example. Never overwrites anything that exists.
+    const init = (0, init_1.runInit)(dir);
+    console.log(`Detected: ${init.framework}`);
+    for (const f of init.filesWritten)
+        console.log(`  wrote   ${node_path_1.default.relative(absDir, f) || f}`);
+    for (const f of init.filesSkipped)
+        console.log(`  skipped ${node_path_1.default.relative(absDir, f) || f} (already exists)`);
+    console.log("");
+    if (init.framework === "other") {
+        // A generic backend needs a real framework decision (Express? Fastify? something
+        // else?) this wizard shouldn't guess at — print init's own manual steps instead
+        // of half-automating something it can't verify is right.
+        console.log("Not a detected Next.js project — falling back to the manual steps:\n");
+        for (const step of init.nextSteps)
+            console.log(`  ${step}`);
+        return;
+    }
+    // 2. Install what's needed — the actual "one command" part. Skips
+    // cleanly if already present (e.g. re-running setup after a partial run).
+    const pkg = readPackageJson(absDir);
+    if (!alreadyInstalled(pkg)) {
+        console.log(`Installing ${PACKAGES.join(", ")} ...`);
+        try {
+            (0, node_child_process_1.execSync)(`npm install ${PACKAGES.join(" ")}`, { cwd: absDir, stdio: "inherit" });
+        }
+        catch {
+            console.error("\nnpm install failed — install these yourself and re-run `cairn setup`:");
+            console.error(`  npm install ${PACKAGES.join(" ")}`);
+            return;
+        }
+    }
+    else {
+        console.log("Dependencies already installed — skipping.\n");
+    }
+    // 3. Ask only what's actually needed, everything skippable.
+    console.log("\nA couple of quick questions — press enter to skip anything you'll add later.\n");
+    let provider = null;
+    let providerKey = null;
+    const wantsLLM = await (0, prompt_1.askYesNo)("Set up an LLM provider now? (needed for the agent to actually answer anything)", true);
+    if (wantsLLM) {
+        const choice = (await (0, prompt_1.ask)("Anthropic or Groq? [anthropic] ")).toLowerCase();
+        provider = choice.startsWith("g") ? "groq" : "anthropic";
+        providerKey = await (0, prompt_1.askOptional)(provider === "anthropic" ? "Paste your ANTHROPIC_API_KEY: " : "Paste your GROQ_API_KEYS: ");
+    }
+    const wantsVoice = await (0, prompt_1.askYesNo)("Set up voice (Deepgram — speech in/out) now?", false);
+    const deepgramKey = wantsVoice ? await (0, prompt_1.askOptional)("Paste your DEEPGRAM_API_KEY: ") : null;
+    (0, prompt_1.closePrompts)();
+    // 4. Write a real .env (not just .env.example) with whatever was actually given.
+    const envLines = [];
+    if (provider === "anthropic")
+        envLines.push(`ANTHROPIC_API_KEY=${providerKey ?? ""}`);
+    if (provider === "groq")
+        envLines.push(`GROQ_API_KEYS=${providerKey ?? ""}`);
+    if (deepgramKey)
+        envLines.push(`DEEPGRAM_API_KEY=${deepgramKey}`);
+    envLines.push("CAIRN_REGISTERED_ACTIONS=");
+    const envPath = node_path_1.default.join(absDir, ".env");
+    if (!node_fs_1.default.existsSync(envPath)) {
+        node_fs_1.default.writeFileSync(envPath, envLines.join("\n") + "\n");
+        console.log(`\nwrote ${node_path_1.default.relative(absDir, envPath)}`);
+    }
+    else {
+        console.log(`\n${node_path_1.default.relative(absDir, envPath)} already exists — not overwriting; add keys there yourself if you skipped any above.`);
+    }
+    // 5. Wire the widget into the real layout file — the one thing `init`
+    // deliberately doesn't do. Falls back to printing instructions on
+    // anything it can't confidently parse.
+    const framework = init.framework;
+    const inject = (0, inject_widget_1.injectWidget)(dir, framework);
+    if (inject.injected) {
+        console.log(`wired <Copilot/> into ${node_path_1.default.relative(absDir, inject.filePath)}`);
+    }
+    else {
+        console.log(`\n<Copilot/> not auto-wired (${inject.reason}). Add it yourself:`);
+        console.log('  import { Copilot } from "@cairnvibe/sdk";');
+        console.log("  <Copilot registeredActions={[]} onDo={(action, target) => { /* run it */ }} />");
+    }
+    // 6. Build the manifest once now, if we actually have a usable key —
+    // no point trying (and failing loudly) with nothing to call.
+    const haveUsableKey = (provider === "anthropic" && providerKey) || (provider === "groq" && providerKey);
+    if (haveUsableKey) {
+        console.log(`\nBuilding the manifest (${provider}) ...`);
+        try {
+            // Reuse the same env-var-driven construction `cairn build` uses, rather
+            // than duplicating each client's options shape here — the .env written
+            // above already has this exact value, this just makes it live for the
+            // rest of this process too.
+            if (provider === "anthropic")
+                process.env.ANTHROPIC_API_KEY = providerKey;
+            if (provider === "groq")
+                process.env.GROQ_API_KEYS = providerKey;
+            const client = provider === "anthropic" ? new llm_1.AnthropicDescribeClient() : new llm_1.GroqDescribeClient();
+            const facts = (0, l1_scan_1.scanL1)(dir);
+            const l2 = (0, l2_reachability_1.computeL2)(dir, facts);
+            const l3 = await (0, l3_describe_1.describeAll)(dir, facts, client);
+            const manifest = core_1.ManifestSchema.parse((0, manifest_1.assembleManifest)(dir, facts, l2, l3));
+            node_fs_1.default.writeFileSync(node_path_1.default.join(absDir, "ui-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+            console.log(`wrote ui-manifest.json (${manifest.pages.length} page(s))`);
+        }
+        catch (err) {
+            console.error(`manifest build failed (${err.message}) — run \`npx cairn build .\` yourself once your key is confirmed working.`);
+        }
+    }
+    else {
+        console.log("\nNo key given yet — skipping the first build. Run `npx cairn build .` once you've added one to .env.");
+    }
+    // 7. Wire a prebuild hook so this stays current on every future build/deploy —
+    // "just build and redeploy" only works if the manifest regenerates itself.
+    if (pkg && !pkg.scripts?.prebuild?.includes("cairn build")) {
+        const pkgPath = node_path_1.default.join(absDir, "package.json");
+        const fresh = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf8"));
+        fresh.scripts = fresh.scripts ?? {};
+        const providerFlag = provider === "groq" ? "groq" : "anthropic";
+        fresh.scripts.prebuild = fresh.scripts.prebuild
+            ? `${fresh.scripts.prebuild} && cairn build . --provider ${providerFlag} --if-configured`
+            : `cairn build . --provider ${providerFlag} --if-configured`;
+        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(fresh, null, 2) + "\n");
+        console.log('added a "prebuild" script — the manifest regenerates automatically on every `npm run build`.');
+        console.log("(--if-configured means a build with no key set yet skips this step instead of failing the whole build —");
+        console.log(" set the same key as an environment variable on whatever platform you deploy to.)");
+    }
+    console.log("\nDone. `npm run dev` and ask it something.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/indexer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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" },