@ophan/cli 0.0.2 → 0.0.4

package/README.md

@@ -35,7 +35,7 @@ npx @ophan/cli gc               # Clean up old analysis entries
 
 ```bash
 npm install --save-dev @ophan/cli
-npx ophan analyze
+npx @ophan/cli analyze
 ```
 
 Add to your team's repo so everyone gets the CLI on `npm install`. Analysis is cached by content hash — unchanged functions are never re-analyzed.

package/dist/auth.js

@@ -113,7 +113,7 @@ async function login(webappUrl, timeoutMs = 120000) {
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             server.close();
-            reject(new Error("Login timed out. Please try again with `ophan login`."));
+            reject(new Error("Login timed out. Please try again with `npx @ophan/cli login`."));
         }, timeoutMs);
         const server = http.createServer(async (req, res) => {
             const url = new URL(req.url || "/", `http://localhost:${port}`);
@@ -196,7 +196,7 @@ async function login(webappUrl, timeoutMs = 120000) {
 async function getAuthenticatedClient() {
     const creds = readCredentials();
     if (!creds) {
-        throw new Error("Not logged in. Run `ophan login` first.");
+        throw new Error("Not logged in. Run `npx @ophan/cli login` first.");
     }
     const supabase = (0, supabase_js_1.createClient)(creds.api_url, creds.api_key, {
         auth: {
@@ -224,7 +224,7 @@ async function getAuthenticatedClient() {
         refresh_token: creds.refresh_token,
     });
     if (error || !data.session) {
-        throw new Error(`Session expired or invalid. Run \`ophan login\` again.\n  ${error?.message || "No session returned"}`);
+        throw new Error(`Session expired or invalid. Run \`npx @ophan/cli login\` again.\n  ${error?.message || "No session returned"}`);
     }
     // Persist the new tokens so next invocation can use the fresh access_token
     // without consuming the refresh token again

package/dist/index.js

@@ -46,11 +46,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 require("dotenv/config");
 const commander_1 = require("commander");
 const core_1 = require("@ophan/core");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
 const auth_1 = require("./auth");
 const sync_1 = require("./sync");
 const watch_1 = require("./watch");
@@ -64,7 +69,7 @@ program
  * Returns undefined if user isn't logged in or repo doesn't exist in Supabase.
  * Silent — never fails the analyze command.
  */
-async function createPullFn(rootPath) {
+async function createPullFn(rootPath, onProgress) {
     const creds = (0, auth_1.readCredentials)();
     if (!creds)
         return undefined;
@@ -79,8 +84,14 @@ async function createPullFn(rootPath) {
             .single();
         if (!repo)
             return undefined;
+        const log = onProgress ?? ((step) => console.log(`  ${step}`));
         return async (hashes) => {
-            await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, hashes, (step) => console.log(`  ${step}`));
+            try {
+                await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, hashes, log);
+            }
+            catch {
+                // Pull is a non-critical optimization — silently degrade
+            }
         };
     }
     catch {
@@ -96,7 +107,13 @@ async function runAnalyze(rootPath) {
             process.stdout.cursorTo(0);
         }
         process.stdout.write(`  [${current}/${total}] ${file}\n`);
-    }, pullFn);
+    }, pullFn, (analyzed, total) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  Analyzing: ${analyzed}/${total} functions`);
+    });
     console.log(`\n✅ Done! ${result.analyzed} analyzed, ${result.skipped} cached` +
         (result.pulled ? ` (${result.pulled} from cloud)` : "") +
         ` across ${result.files} files` +
@@ -115,10 +132,29 @@ program
     .description("Remove orphaned analysis entries (manual, safe for branch switching)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .option("-d, --days <days>", "Grace period in days", "30")
+    .option("-f, --force", "Run GC even when not on default branch")
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
     const maxAgeDays = parseInt(options.days, 10);
     const dbPath = path.join(rootPath, ".ophan", "index.db");
+    // Branch safety check — GC on a feature branch can orphan
+    // hashes that only exist on the default branch
+    const currentBranch = (0, sync_1.getGitBranch)(rootPath);
+    if (currentBranch !== null) {
+        const defaultBranch = (0, sync_1.getDefaultBranch)(rootPath);
+        if (currentBranch !== defaultBranch && !options.force) {
+            console.error(`⚠️  You're on branch '${currentBranch}', not '${defaultBranch}'.\n` +
+                `   Running GC on a feature branch can delete analysis for functions\n` +
+                `   that only exist on '${defaultBranch}'. If synced, these deletions\n` +
+                `   propagate to the cloud.\n\n` +
+                `   Switch to '${defaultBranch}' first, or use --force to proceed.`);
+            process.exit(1);
+        }
+        if (currentBranch !== defaultBranch && options.force) {
+            console.warn(`⚠️  Running GC on branch '${currentBranch}' (default: '${defaultBranch}').\n` +
+                `   Proceeding with --force.\n`);
+        }
+    }
     console.log("🧹 Refreshing file index...\n");
     await (0, core_1.refreshFileIndex)(rootPath, (current, total, file) => {
         if (process.stdout.isTTY) {
@@ -144,7 +180,7 @@ program
         try {
             await (0, auth_1.getAuthenticatedClient)();
             console.log(`  Already logged in as ${existing.email}`);
-            console.log(`  Run \`ophan logout\` first to switch accounts.`);
+            console.log(`  Run \`npx @ophan/cli logout\` first to switch accounts.`);
             return;
         }
         catch {
@@ -172,21 +208,51 @@ program
 // ========== SYNC ==========
 program
     .command("sync")
-    .description("Sync analysis to ophan.dev")
+    .description("Sync analysis with ophan.dev (pull + push)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
     try {
         const { supabase, userId } = await (0, auth_1.getAuthenticatedClient)();
-        console.log("☁️  Syncing to ophan.dev...\n");
-        const result = await (0, sync_1.syncToSupabase)(rootPath, supabase, userId, (step) => {
-            console.log(`  ${step}`);
-        });
-        console.log(`\n✅ Sync complete: ${result.pushed} analysis entries pushed, ` +
-            `${result.locations} file locations synced` +
-            (result.gcProcessed > 0
-                ? `, ${result.gcProcessed} GC deletions applied`
-                : ""));
+        console.log("☁️  Syncing with ophan.dev...\n");
+        // Pull first: fetch missing analysis from cloud
+        let pulled = 0;
+        const repoName = path.basename(rootPath);
+        const { data: repo } = await supabase
+            .from("repos")
+            .select("id")
+            .eq("user_id", userId)
+            .eq("name", repoName)
+            .single();
+        if (repo) {
+            const missingHashes = (0, core_1.findMissingHashes)(dbPath);
+            if (missingHashes.length > 0) {
+                const pullResult = await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, missingHashes, (step) => console.log(`  ${step}`));
+                pulled = pullResult.pulled;
+            }
+            else {
+                console.log("  No missing analyses to pull.");
+            }
+        }
+        // Then push local analysis to cloud
+        const result = await (0, sync_1.syncToSupabase)(rootPath, supabase, userId, (step) => console.log(`  ${step}`));
+        const parts = [
+            `${pulled} pulled`,
+            `${result.pushed} pushed`,
+            `${result.locations} file locations synced`,
+        ];
+        if (result.practices > 0)
+            parts.push(`${result.practices} practices synced`);
+        if (result.communities > 0)
+            parts.push(`${result.communities} community memberships`);
+        if (result.communityEdges > 0)
+            parts.push(`${result.communityEdges} community edges`);
+        if (result.summaries > 0)
+            parts.push(`${result.summaries} summaries`);
+        if (result.gcProcessed > 0)
+            parts.push(`${result.gcProcessed} GC deletions applied`);
+        console.log(`\n✅ Sync complete: ${parts.join(", ")}`);
     }
     catch (err) {
         console.error(`\n❌ Sync failed: ${err.message}`);
@@ -202,7 +268,21 @@ program
     .option("--sync", "Auto-sync to cloud after each analysis batch")
     .action(async (options) => {
     const rootPath = path.resolve(options.path);
-    const pullFn = await createPullFn(rootPath);
+    // Watch is long-running (used by extension host) — never crash on stray rejections.
+    // Common cause: Supabase server unreachable during pull/sync operations.
+    process.on("unhandledRejection", (reason) => {
+        const msg = reason?.message ?? String(reason);
+        if (options.json) {
+            process.stdout.write(JSON.stringify({ event: "error", message: `Unhandled rejection: ${msg}` }) + "\n");
+        }
+        else {
+            console.error(`  ❌ Unexpected error: ${msg}`);
+        }
+    });
+    const pullProgress = options.json
+        ? (step) => process.stdout.write(JSON.stringify({ event: "pull_progress", message: step }) + "\n")
+        : undefined;
+    const pullFn = await createPullFn(rootPath, pullProgress);
     let syncFn;
     if (options.sync) {
         const creds = (0, auth_1.readCredentials)();
@@ -213,18 +293,18 @@ program
             }
             catch {
                 if (options.json) {
-                    process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Session expired — sync disabled. Run ophan login." }) + "\n");
+                    process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Session expired — sync disabled. Run npx @ophan/cli login." }) + "\n");
                 }
                 else {
-                    console.warn("  ⚠️  Session expired — sync disabled. Run `ophan login` to re-authenticate.");
+                    console.warn("  ⚠️  Session expired — sync disabled. Run `npx @ophan/cli login` to re-authenticate.");
                 }
             }
         }
         else if (options.json) {
-            process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Not logged in — sync disabled. Run ophan login." }) + "\n");
+            process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Not logged in — sync disabled. Run npx @ophan/cli login." }) + "\n");
         }
         else {
-            console.warn("  ⚠️  Not logged in — sync disabled. Run `ophan login` to enable cloud sync.");
+            console.warn("  ⚠️  Not logged in — sync disabled. Run `npx @ophan/cli login` to enable cloud sync.");
         }
     }
     await (0, watch_1.startWatch)({
@@ -234,12 +314,291 @@ program
         json: options.json,
     });
 });
-// Keep "init" as alias for "analyze" for backwards compat
+// ========== INIT ==========
 program
     .command("init")
-    .description("Alias for analyze")
+    .description("Initialize Ophan for this repository (fast, no network calls)")
     .option("-p, --path <path>", "Path to repository", process.cwd())
     .action(async (options) => {
-    await runAnalyze(path.resolve(options.path));
+    const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    console.log("Initializing Ophan...\n");
+    // Create .ophan dir + DB tables + gitignore
+    fs.mkdirSync(path.join(rootPath, ".ophan"), { recursive: true });
+    (0, core_1.ensureGitignore)(rootPath);
+    (0, core_1.initDb)(dbPath).close();
+    // Scan files and index all functions
+    let fileCount = 0;
+    await (0, core_1.refreshFileIndex)(rootPath, (current, total, file) => {
+        fileCount = total;
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}\n`);
+    });
+    // Count indexed functions
+    const db = new better_sqlite3_1.default(dbPath, { readonly: true });
+    const row = db.prepare("SELECT COUNT(*) as count FROM file_functions").get();
+    db.close();
+    console.log(`\n✅ Initialized! Found ${row.count} functions across ${fileCount} files.`);
+    console.log(`   Database: .ophan/index.db\n`);
+    console.log(`   Next: run \`npx @ophan/cli watch\` to start analysis.`);
+});
+// ========== GRAPH ==========
+program
+    .command("graph")
+    .description("Build function relationship graph and detect communities")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .option("-a, --algorithm <algorithm>", "Community detection algorithm (louvain, leiden, label-propagation)", core_1.DEFAULT_GRAPH_CONFIG.algorithm)
+    .option("-r, --resolution <number>", "Louvain resolution parameter (higher = more communities)", String(core_1.DEFAULT_GRAPH_CONFIG.resolution))
+    .option("--min-size <number>", "Minimum community size (smaller clusters are dissolved)", String(core_1.DEFAULT_GRAPH_CONFIG.minCommunitySize))
+    .option("--max-size <number>", "Maximum community size (informational)", String(core_1.DEFAULT_GRAPH_CONFIG.maxCommunitySize))
+    .option("--json", "Output results as JSON")
+    .option("--summarize", "Generate documentation for detected communities using Claude")
+    .option("--raw-source", "Use raw function source code for documentation (requires --summarize)")
+    .option("--directory-decay <number>", "Directory distance decay factor (0=off, higher=stronger)", String(core_1.DEFAULT_GRAPH_CONFIG.directoryDecay))
+    .option("--compare", "Compare multiple algorithm configurations side by side")
+    .action(async (options) => {
+    const rootPath = path.resolve(options.path);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    if (!fs.existsSync(dbPath)) {
+        console.error("No .ophan/index.db found. Run `npx @ophan/cli init` first.");
+        process.exit(1);
+    }
+    if (options.rawSource && !options.summarize) {
+        console.error("--raw-source requires --summarize");
+        process.exit(1);
+    }
+    const config = {
+        algorithm: options.algorithm,
+        edgeWeights: core_1.DEFAULT_GRAPH_CONFIG.edgeWeights,
+        resolution: parseFloat(options.resolution),
+        minCommunitySize: parseInt(options.minSize, 10),
+        maxCommunitySize: parseInt(options.maxSize, 10),
+        directoryDecay: parseFloat(options.directoryDecay),
+    };
+    if (!options.json) {
+        console.log(`\nBuilding function graph (${config.algorithm}, resolution=${config.resolution})...\n`);
+    }
+    // Extract functions with relationship data
+    const functions = await (0, core_1.extractAllFunctions)(rootPath, !options.json ? (current, total, file) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}`);
+    } : undefined);
+    if (!options.json) {
+        console.log(`\n\n  ${functions.length} functions extracted, resolving edges...\n`);
+    }
+    // Populate file_functions index from extracted functions (needed for edge resolution)
+    const db = (0, core_1.initDb)(dbPath);
+    // Snapshot old hashes before populateFileIndex overwrites file_functions
+    // This enables incremental edge resolution (only recompute changed + neighbor edges)
+    const oldHashes = new Set(db.prepare("SELECT DISTINCT content_hash FROM file_functions").all()
+        .map((r) => r.content_hash));
+    (0, core_1.populateFileIndex)(db, functions);
+    if (!options.json) {
+        console.log(`  Indexed ${functions.length} functions, detecting communities...\n`);
+    }
+    // --compare mode: resolve edges once, run multiple algorithm configs, print table
+    if (options.compare) {
+        const resolver = rootPath ? (0, core_1.buildModuleResolver)(rootPath, functions) : undefined;
+        const edges = (0, core_1.resolveEdges)(db, functions, config, undefined, resolver);
+        (0, core_1.storeEdges)(db, edges);
+        const edgesWithTransitive = (0, core_1.addTransitiveEdges)(edges, config);
+        // Build hash→filePath map for directory distance decay
+        let hashToFilePath;
+        if (rootPath && (config.directoryDecay ?? 0) > 0) {
+            hashToFilePath = new Map();
+            for (const fn of functions)
+                hashToFilePath.set(fn.contentHash, fn.filePath);
+        }
+        const allHashes = new Set(functions.map((f) => f.contentHash));
+        const metrics = (0, core_1.runComparison)(edgesWithTransitive, config, core_1.DEFAULT_COMPARISONS, hashToFilePath, rootPath, allHashes);
+        if (options.json) {
+            console.log(JSON.stringify({ nodes: allHashes.size, edges: edgesWithTransitive.length, comparisons: metrics }));
+        }
+        else {
+            console.log(`  Algorithm Comparison (${allHashes.size} nodes, ${edgesWithTransitive.length} edges)\n`);
+            // Table header
+            const header = [
+                "Configuration".padEnd(25),
+                "Communities".padStart(12),
+                "Dissolved".padStart(14),
+                "Coverage".padStart(9),
+                "Min".padStart(5),
+                "Med".padStart(5),
+                "Max".padStart(5),
+                "Modularity".padStart(11),
+            ].join("");
+            console.log(`  ${header}`);
+            console.log(`  ${"─".repeat(header.length)}`);
+            for (const m of metrics) {
+                const dissolved = `${m.dissolvedCount} (${m.dissolvedPct.toFixed(0)}%)`;
+                const modularity = m.modularity !== null ? m.modularity.toFixed(4) : "---";
+                const row = [
+                    m.label.padEnd(25),
+                    String(m.communityCount).padStart(12),
+                    dissolved.padStart(14),
+                    `${m.coverage.toFixed(0)}%`.padStart(9),
+                    String(m.minSize).padStart(5),
+                    String(m.medianSize).padStart(5),
+                    String(m.maxSize).padStart(5),
+                    modularity.padStart(11),
+                ].join("");
+                console.log(`  ${row}`);
+            }
+            console.log();
+        }
+        db.close();
+        return;
+    }
+    // Run full graph pipeline with hierarchical detection
+    const hierResult = (0, core_1.detectHierarchicalCommunities)(db, functions, config, oldHashes, rootPath);
+    const result = hierResult.l0;
+    // Build source map for raw-source summarization mode
+    let sourceMap;
+    if (options.rawSource) {
+        sourceMap = new Map();
+        for (const fn of functions)
+            sourceMap.set(fn.contentHash, fn.sourceCode);
+    }
+    if (options.json) {
+        const output = {
+            algorithm: config.algorithm,
+            resolution: config.resolution,
+            nodes: result.nodesInGraph,
+            edges: result.edgesInGraph,
+            communities: result.communityCount,
+            dissolved: result.dissolvedCount,
+            modularity: result.modularity,
+            assignments: result.assignments,
+            communityEdges: hierResult.communityEdges,
+            l1Groups: hierResult.l1GroupCount,
+            l1Assignments: hierResult.l1Assignments,
+        };
+        // Summarize if requested
+        if (options.summarize) {
+            const sumResult = await (0, core_1.summarizeCommunities)(db, {
+                config: { algorithm: config.algorithm },
+                sourceMap,
+                rootPath,
+            });
+            const l1 = (0, core_1.loadAllSummaries)(db, config.algorithm, 1);
+            const l2 = (0, core_1.loadAllSummaries)(db, config.algorithm, 2);
+            const l3 = (0, core_1.loadAllSummaries)(db, config.algorithm, 3);
+            const cc = (0, core_1.loadAllSummaries)(db, config.algorithm, 10);
+            output.summaries = {
+                l1: l1.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                l2: l2.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                l3: l3.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                crossCutting: cc.map((s) => ({ communityId: s.communityId, ...s.summary })),
+                stats: sumResult,
+            };
+        }
+        console.log(JSON.stringify(output));
+    }
+    else {
+        console.log(`  Nodes:       ${result.nodesInGraph}`);
+        console.log(`  Edges:       ${result.edgesInGraph}`);
+        console.log(`  Communities: ${result.communityCount}`);
+        if (result.dissolvedCount > 0) {
+            console.log(`  Dissolved:   ${result.dissolvedCount} (below min size ${config.minCommunitySize})`);
+        }
+        if (result.modularity !== null) {
+            console.log(`  Modularity:  ${result.modularity.toFixed(4)}`);
+        }
+        if (result.effectiveResolution && result.effectiveResolution !== config.resolution) {
+            console.log(`  Resolution:  ${result.effectiveResolution} (auto-scaled from ${config.resolution})`);
+        }
+        if (hierResult.l1GroupCount > 0) {
+            console.log(`  Groups:      ${hierResult.l1GroupCount} (hierarchical)`);
+        }
+        if (hierResult.communityEdges.length > 0) {
+            console.log(`  Cross-edges: ${hierResult.communityEdges.length} (between communities)`);
+        }
+        // Show community breakdown
+        if (result.communityCount > 0) {
+            const communityMap = new Map();
+            for (const a of result.assignments) {
+                if (a.communityId === "__dissolved")
+                    continue;
+                const members = communityMap.get(a.communityId) || [];
+                members.push(a.contentHash);
+                communityMap.set(a.communityId, members);
+            }
+            console.log(`\n  Community breakdown:`);
+            // Look up function names from DB for display
+            const readDb = new better_sqlite3_1.default(dbPath, { readonly: true });
+            const lookupName = readDb.prepare("SELECT function_name, file_path FROM file_functions WHERE content_hash = ? LIMIT 1");
+            const sorted = [...communityMap.entries()].sort((a, b) => b[1].length - a[1].length);
+            for (const [communityId, hashes] of sorted) {
+                const overMax = hashes.length > config.maxCommunitySize;
+                const flag = overMax ? " (large)" : "";
+                console.log(`\n    Community ${communityId}${flag} (${hashes.length} functions):`);
+                for (const hash of hashes.slice(0, 15)) {
+                    const row = lookupName.get(hash);
+                    if (row) {
+                        const relPath = path.relative(rootPath, row.file_path);
+                        console.log(`      ${row.function_name}  (${relPath})`);
+                    }
+                    else {
+                        console.log(`      ${hash.slice(0, 12)}...`);
+                    }
+                }
+                if (hashes.length > 15) {
+                    console.log(`      ... and ${hashes.length - 15} more`);
+                }
+            }
+            readDb.close();
+        }
+        // Summarize if requested
+        if (options.summarize) {
+            // Check if any function analysis exists (for a useful warning in non-raw mode)
+            const analysisCount = db.prepare("SELECT COUNT(*) as count FROM function_analysis").get().count;
+            if (!options.rawSource && analysisCount === 0) {
+                console.log("  ⚠️  No function analysis found. Run `ophan analyze` first for best results.\n");
+            }
+            else if (result.communityCount > 0) {
+                console.log(options.rawSource
+                    ? "\n📝 Generating documentation from source code...\n"
+                    : "\n📝 Generating documentation...\n");
+                const sumResult = await (0, core_1.summarizeCommunities)(db, {
+                    config: { algorithm: config.algorithm },
+                    onProgress: (step) => console.log(`  ${step}`),
+                    sourceMap,
+                    rootPath,
+                });
+                const generated = sumResult.l1Summarized + sumResult.l2Summarized + sumResult.l3Summarized;
+                const cached = sumResult.l1Cached + sumResult.l2Cached + sumResult.l3Cached;
+                const driftSkipped = sumResult.l1DriftSkipped;
+                const failed = sumResult.l1Failed ?? 0;
+                const parts = [`${generated} generated`, `${cached} cached`];
+                if (driftSkipped > 0)
+                    parts.push(`${driftSkipped} drift-skipped`);
+                if (failed > 0)
+                    parts.push(`${failed} failed`);
+                console.log(`\n✅ Documentation: ${parts.join(", ")}`);
+                if (sumResult.ccDetected > 0) {
+                    console.log(`  Cross-cutting: ${sumResult.ccDetected} detected, ${sumResult.ccSummarized} documented, ${sumResult.ccCached} cached`);
+                    const ccSummaries = (0, core_1.loadAllSummaries)(db, config.algorithm, 10);
+                    if (ccSummaries.length > 0) {
+                        console.log(`\n  Cross-Cutting Concerns:`);
+                        for (const s of ccSummaries) {
+                            const sum = s.summary;
+                            const badge = sum.concernType === "security" ? "SEC" : "DATA";
+                            const communities = (sum.affectedCommunities || [])
+                                .map((c) => c.communityTitle).join(", ");
+                            console.log(`    [${badge}] ${sum.title} (${communities})`);
+                        }
+                    }
+                }
+            }
+        }
+        console.log();
+    }
+    db.close();
 });
 program.parse();

package/dist/sync.js

@@ -36,13 +36,67 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitBranch = getGitBranch;
+exports.getGitCommitHash = getGitCommitHash;
+exports.getDefaultBranch = getDefaultBranch;
 exports.syncToSupabase = syncToSupabase;
 exports.pullFromSupabase = pullFromSupabase;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
+const p_limit_1 = __importDefault(require("p-limit"));
 const core_1 = require("@ophan/core");
+const supabaseLimit = (0, p_limit_1.default)(3);
+/** Run chunked Supabase operations in parallel with bounded concurrency. */
+async function parallelChunks(rows, chunkSize, fn) {
+    const chunks = [];
+    for (let i = 0; i < rows.length; i += chunkSize) {
+        chunks.push(rows.slice(i, i + chunkSize));
+    }
+    await Promise.all(chunks.map((chunk) => supabaseLimit(() => fn(chunk))));
+}
+function getGitBranch(rootPath) {
+    try {
+        return ((0, child_process_1.execSync)("git rev-parse --abbrev-ref HEAD", {
+            cwd: rootPath,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim() || null);
+    }
+    catch {
+        return null;
+    }
+}
+function getGitCommitHash(rootPath) {
+    try {
+        return ((0, child_process_1.execSync)("git rev-parse HEAD", {
+            cwd: rootPath,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim() || null);
+    }
+    catch {
+        return null;
+    }
+}
+function getDefaultBranch(rootPath) {
+    try {
+        const ref = (0, child_process_1.execSync)("git symbolic-ref refs/remotes/origin/HEAD", {
+            cwd: rootPath,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        // ref = "refs/remotes/origin/main" → extract "main"
+        const match = ref.match(/refs\/remotes\/origin\/(.+)/);
+        if (match)
+            return match[1];
+    }
+    catch {
+        // No remote, shallow clone, or not a git repo
+    }
+    return "main";
+}
 function getGitRemoteUrl(rootPath) {
     try {
         return ((0, child_process_1.execSync)("git remote get-url origin", {
@@ -58,7 +112,7 @@ function getGitRemoteUrl(rootPath) {
 async function syncToSupabase(rootPath, supabase, userId, onProgress) {
     const dbPath = path.join(rootPath, ".ophan", "index.db");
     if (!fs.existsSync(dbPath)) {
-        throw new Error(`No analysis database found at ${dbPath}\n  Run \`ophan analyze\` first.`);
+        throw new Error(`No analysis database found at ${dbPath}\n  Run \`npx @ophan/cli init\` first.`);
     }
     const db = new better_sqlite3_1.default(dbPath);
     // Ensure sync_meta table exists (may not if DB was created by older version)
@@ -86,12 +140,42 @@ async function syncToSupabase(rootPath, supabase, userId, onProgress) {
             name: repoName,
             remote_url: remoteUrl,
         }, { onConflict: "user_id,name" })
-            .select("id")
+            .select("id, docs_branch")
             .single();
         if (repoError) {
             throw new Error(`Failed to register repo: ${repoError.message}`);
         }
         const repoId = repo.id;
+        const docsBranch = repo.docs_branch ?? "main";
+        // Determine whether to sync architecture data (communities, edges, summaries).
+        // Gate: only sync when on the configured docs branch.
+        // Non-git repos (branch = null) bypass the gate — always sync.
+        const currentBranch = getGitBranch(rootPath);
+        const syncArchitecture = currentBranch === null || currentBranch === docsBranch;
+        if (!syncArchitecture) {
+            onProgress?.(`Skipping architecture sync (on '${currentBranch}', docs branch is '${docsBranch}')`);
+        }
+        // 1.5. Pull practices from Supabase → local SQLite
+        onProgress?.("Syncing practices...");
+        const { data: practiceRows } = await supabase
+            .from("repo_practices")
+            .select("practice_id, rule, severity")
+            .eq("repo_id", repoId);
+        const practicesSynced = practiceRows?.length ?? 0;
+        if (practiceRows && practiceRows.length > 0) {
+            (0, core_1.importPractices)(db, practiceRows.map((r) => ({
+                id: r.practice_id,
+                rule: r.rule,
+                severity: r.severity,
+            })));
+        }
+        else {
+            // No practices defined — clear local table
+            try {
+                db.prepare("DELETE FROM practices").run();
+            }
+            catch { }
+        }
         // 2. Push unsynced analysis (now includes analysis_type + schema_version)
         onProgress?.("Pushing analysis...");
         const unsynced = db
@@ -110,16 +194,15 @@ async function syncToSupabase(rootPath, supabase, userId, onProgress) {
                 language: row.language,
                 entity_type: row.entity_type,
             }));
-            // Batch upsert in chunks of 500 (Supabase limit)
-            for (let i = 0; i < rows.length; i += 500) {
-                const chunk = rows.slice(i, i + 500);
+            // Batch upsert in chunks of 500 with bounded concurrency
+            await parallelChunks(rows, 500, async (chunk) => {
                 const { error } = await supabase
                     .from("function_analysis")
                     .upsert(chunk, { onConflict: "content_hash,repo_id,analysis_type" });
                 if (error) {
                     throw new Error(`Failed to push analysis: ${error.message}`);
                 }
-            }
+            });
             // Mark as synced locally
             const now = Math.floor(Date.now() / 1000);
             const markSynced = db.prepare("UPDATE function_analysis SET synced_at = ? WHERE content_hash = ? AND analysis_type = ?");
@@ -140,28 +223,37 @@ async function syncToSupabase(rootPath, supabase, userId, onProgress) {
             throw new Error(`Failed to clear locations: ${delError.message}`);
         }
         const locations = db
-            .prepare(`SELECT file_path, function_name, content_hash, language, entity_type
-         FROM file_functions`)
+            .prepare(`SELECT file_path, function_name, content_hash, language, entity_type, start_line
+         FROM file_functions
+         GROUP BY file_path, function_name`)
             .all();
         if (locations.length > 0) {
+            // Convert absolute paths to repo-relative for cloud storage
+            // (local DB stores absolute paths for file I/O, but cloud paths
+            // must be portable across machines)
+            const rootPrefix = rootPath.endsWith(path.sep)
+                ? rootPath
+                : rootPath + path.sep;
             const locationRows = locations.map((row) => ({
                 repo_id: repoId,
                 user_id: userId,
-                file_path: row.file_path,
+                file_path: row.file_path.startsWith(rootPrefix)
+                    ? row.file_path.slice(rootPrefix.length)
+                    : row.file_path,
                 function_name: row.function_name,
                 content_hash: row.content_hash,
                 language: row.language,
                 entity_type: row.entity_type,
+                start_line: row.start_line,
             }));
-            for (let i = 0; i < locationRows.length; i += 500) {
-                const chunk = locationRows.slice(i, i + 500);
+            await parallelChunks(locationRows, 500, async (chunk) => {
                 const { error } = await supabase
                     .from("function_locations")
                     .insert(chunk);
                 if (error) {
                     throw new Error(`Failed to push locations: ${error.message}`);
                 }
-            }
+            });
         }
         // 4. Process GC tombstones
         onProgress?.("Processing garbage collection...");
@@ -169,30 +261,36 @@ async function syncToSupabase(rootPath, supabase, userId, onProgress) {
             .prepare("SELECT content_hash, analysis_type FROM function_gc WHERE synced_at IS NULL")
             .all();
         if (gcRows.length > 0) {
-            for (const row of gcRows) {
-                if (row.analysis_type) {
-                    // Delete specific analysis type
-                    await supabase
-                        .from("function_analysis")
-                        .delete()
-                        .eq("content_hash", row.content_hash)
-                        .eq("repo_id", repoId)
-                        .eq("analysis_type", row.analysis_type);
+            // Batch GC deletes using .in() for efficiency
+            const withType = gcRows.filter((r) => r.analysis_type);
+            const withoutType = gcRows.filter((r) => !r.analysis_type);
+            // Delete analysis rows with specific type (group by type)
+            if (withType.length > 0) {
+                const byType = new Map();
+                for (const row of withType) {
+                    const hashes = byType.get(row.analysis_type) || [];
+                    hashes.push(row.content_hash);
+                    byType.set(row.analysis_type, hashes);
                 }
-                else {
-                    // NULL analysis_type means delete all types (legacy GC entry)
-                    await supabase
-                        .from("function_analysis")
-                        .delete()
-                        .eq("content_hash", row.content_hash)
-                        .eq("repo_id", repoId);
-                }
-                await supabase
-                    .from("function_locations")
-                    .delete()
-                    .eq("content_hash", row.content_hash)
-                    .eq("repo_id", repoId);
+                await Promise.all([...byType.entries()].map(([type, hashes]) => parallelChunks(hashes, 50, async (chunk) => {
+                    await supabase.from("function_analysis").delete()
+                        .eq("repo_id", repoId).eq("analysis_type", type).in("content_hash", chunk);
+                })));
             }
+            // Delete analysis rows without type (legacy GC entries)
+            if (withoutType.length > 0) {
+                const legacyHashes = withoutType.map((r) => r.content_hash);
+                await parallelChunks(legacyHashes, 50, async (chunk) => {
+                    await supabase.from("function_analysis").delete()
+                        .eq("repo_id", repoId).in("content_hash", chunk);
+                });
+            }
+            // Delete location rows for all GC'd hashes
+            const allGcHashes = gcRows.map((r) => r.content_hash);
+            await parallelChunks(allGcHashes, 50, async (chunk) => {
+                await supabase.from("function_locations").delete()
+                    .eq("repo_id", repoId).in("content_hash", chunk);
+            });
             // Mark GC rows as synced locally, then delete them
             const now = Math.floor(Date.now() / 1000);
             db.transaction(() => {
@@ -200,10 +298,145 @@ async function syncToSupabase(rootPath, supabase, userId, onProgress) {
                 db.prepare("DELETE FROM function_gc WHERE synced_at IS NOT NULL").run();
             })();
         }
+        // 5. Replace communities (full sync, like function_locations)
+        // Steps 5-7 are gated by syncArchitecture (only sync on docs branch)
+        let communitiesSynced = 0;
+        if (!syncArchitecture) {
+            return {
+                pushed: unsynced.length,
+                locations: locations.length,
+                gcProcessed: gcRows.length,
+                practices: practicesSynced,
+                communities: 0,
+                communityEdges: 0,
+                summaries: 0,
+                skippedArchitecture: true,
+                commitHash: null,
+            };
+        }
+        const hasCommunities = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='communities'").get();
+        if (hasCommunities) {
+            onProgress?.("Syncing community memberships...");
+            const { error: commDelError } = await supabase
+                .from("communities")
+                .delete()
+                .eq("repo_id", repoId);
+            if (commDelError) {
+                throw new Error(`Failed to clear communities: ${commDelError.message}`);
+            }
+            const communityRows = db.prepare("SELECT content_hash, level, community_id, algorithm FROM communities").all();
+            if (communityRows.length > 0) {
+                const rows = communityRows.map((row) => ({
+                    content_hash: row.content_hash,
+                    level: row.level,
+                    community_id: row.community_id,
+                    algorithm: row.algorithm,
+                    repo_id: repoId,
+                    user_id: userId,
+                }));
+                await parallelChunks(rows, 500, async (chunk) => {
+                    const { error } = await supabase.from("communities").insert(chunk);
+                    if (error) {
+                        throw new Error(`Failed to push communities: ${error.message}`);
+                    }
+                });
+                communitiesSynced = communityRows.length;
+            }
+        }
+        // 6. Replace community_edges (full sync, like communities)
+        let communityEdgesSynced = 0;
+        const hasCommunityEdges = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='community_edges'").get();
+        if (hasCommunityEdges) {
+            onProgress?.("Syncing community edges...");
+            const { error: ceDelError } = await supabase
+                .from("community_edges")
+                .delete()
+                .eq("repo_id", repoId);
+            if (ceDelError) {
+                throw new Error(`Failed to clear community edges: ${ceDelError.message}`);
+            }
+            const ceRows = db.prepare("SELECT source_community, target_community, algorithm, weight, edge_count FROM community_edges").all();
+            if (ceRows.length > 0) {
+                const rows = ceRows.map((row) => ({
+                    source_community: row.source_community,
+                    target_community: row.target_community,
+                    algorithm: row.algorithm,
+                    repo_id: repoId,
+                    user_id: userId,
+                    weight: row.weight,
+                    edge_count: row.edge_count,
+                }));
+                await parallelChunks(rows, 500, async (chunk) => {
+                    const { error } = await supabase.from("community_edges").insert(chunk);
+                    if (error) {
+                        throw new Error(`Failed to push community edges: ${error.message}`);
+                    }
+                });
+                communityEdgesSynced = ceRows.length;
+            }
+        }
+        // 7. Replace community summaries (full sync, like communities)
+        let summariesSynced = 0;
+        const hasSummaries = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='community_summaries'").get();
+        if (hasSummaries) {
+            onProgress?.("Syncing community summaries...");
+            const { error: sumDelError } = await supabase
+                .from("community_summaries")
+                .delete()
+                .eq("repo_id", repoId);
+            if (sumDelError) {
+                throw new Error(`Failed to clear summaries: ${sumDelError.message}`);
+            }
+            const summaryRows = db.prepare("SELECT community_id, level, algorithm, input_hash, summary, model_version, created_at FROM community_summaries").all();
+            if (summaryRows.length > 0) {
+                const rows = summaryRows.map((row) => ({
+                    community_id: row.community_id,
+                    level: row.level,
+                    algorithm: row.algorithm,
+                    repo_id: repoId,
+                    user_id: userId,
+                    input_hash: row.input_hash,
+                    summary: JSON.parse(row.summary),
+                    model_version: row.model_version,
+                }));
+                await parallelChunks(rows, 500, async (chunk) => {
+                    const { error } = await supabase
+                        .from("community_summaries")
+                        .insert(chunk);
+                    if (error) {
+                        throw new Error(`Failed to push summaries: ${error.message}`);
+                    }
+                });
+                summariesSynced = summaryRows.length;
+            }
+        }
+        // 8. Record docs sync commit hash (git repos only)
+        const commitHash = getGitCommitHash(rootPath);
+        if (commitHash && currentBranch) {
+            await supabase.from("docs_sync_history").insert({
+                repo_id: repoId,
+                user_id: userId,
+                commit_hash: commitHash,
+                branch: currentBranch,
+            });
+            await supabase
+                .from("repos")
+                .update({
+                last_docs_sync_commit: commitHash,
+                last_docs_sync_at: new Date().toISOString(),
+            })
+                .eq("id", repoId);
+        }
         return {
             pushed: unsynced.length,
             locations: locations.length,
             gcProcessed: gcRows.length,
+            practices: practicesSynced,
+            communities: communitiesSynced,
+            communityEdges: communityEdgesSynced,
+            summaries: summariesSynced,
+            skippedArchitecture: false,
+            commitHash,
         };
     }
     finally {
@@ -221,32 +454,41 @@ async function pullFromSupabase(rootPath, supabase, userId, repoId, missingHashe
     const dbPath = path.join(rootPath, ".ophan", "index.db");
     onProgress?.(`Pulling ${missingHashes.length} cached analyses from cloud...`);
     const allRows = [];
-    // Batch queries in chunks of 200 to avoid URL length limits
-    for (let i = 0; i < missingHashes.length; i += 200) {
-        const chunk = missingHashes.slice(i, i + 200);
-        const { data, error } = await supabase
-            .from("function_analysis")
-            .select("content_hash, analysis_type, analysis, model_version, schema_version, language, entity_type")
-            .eq("repo_id", repoId)
-            .in("content_hash", chunk);
-        if (error) {
-            onProgress?.(`Warning: pull failed: ${error.message}`);
-            continue;
-        }
-        if (data) {
-            for (const row of data) {
-                allRows.push({
-                    content_hash: row.content_hash,
-                    analysis_type: row.analysis_type,
-                    analysis: typeof row.analysis === "string" ? row.analysis : JSON.stringify(row.analysis),
-                    model_version: row.model_version,
-                    schema_version: row.schema_version ?? 1,
-                    language: row.language ?? "typescript",
-                    entity_type: row.entity_type ?? "function",
-                });
+    // Batch queries in chunks of 50 with bounded concurrency
+    // (SHA256 hashes are 64 chars each; 50 × 64 ≈ 3.2KB fits within URI limits)
+    const pullChunks = [];
+    for (let i = 0; i < missingHashes.length; i += 50) {
+        pullChunks.push(missingHashes.slice(i, i + 50));
+    }
+    await Promise.all(pullChunks.map((chunk) => supabaseLimit(async () => {
+        try {
+            const { data, error } = await supabase
+                .from("function_analysis")
+                .select("content_hash, analysis_type, analysis, model_version, schema_version, language, entity_type")
+                .eq("repo_id", repoId)
+                .in("content_hash", chunk);
+            if (error) {
+                onProgress?.(`Warning: pull failed: ${error.message}`);
+                return;
+            }
+            if (data) {
+                for (const row of data) {
+                    allRows.push({
+                        content_hash: row.content_hash,
+                        analysis_type: row.analysis_type,
+                        analysis: typeof row.analysis === "string" ? row.analysis : JSON.stringify(row.analysis),
+                        model_version: row.model_version,
+                        schema_version: row.schema_version ?? 1,
+                        language: row.language ?? "typescript",
+                        entity_type: row.entity_type ?? "function",
+                    });
+                }
             }
         }
-    }
+        catch (err) {
+            onProgress?.(`Warning: pull request failed: ${err?.message ?? String(err)}`);
+        }
+    })));
     if (allRows.length === 0)
         return { pulled: 0 };
     const imported = (0, core_1.importAnalysis)(dbPath, allRows);

package/dist/watch.js

@@ -33,27 +33,90 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatError = formatError;
+exports.isGitIgnored = isGitIgnored;
+exports.withTimeout = withTimeout;
 exports.startWatch = startWatch;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
 const core_1 = require("@ophan/core");
 function emit(event) {
     process.stdout.write(JSON.stringify(event) + "\n");
 }
+function formatError(err) {
+    if (err instanceof Error)
+        return err.message || err.constructor.name;
+    if (typeof err === "string")
+        return err || "Empty error string";
+    // Handle non-Error objects (e.g. Supabase/Anthropic SDK errors with circular refs)
+    if (err && typeof err === "object") {
+        const obj = err;
+        if (typeof obj.message === "string" && obj.message)
+            return obj.message;
+        if (typeof obj.error === "string" && obj.error)
+            return obj.error;
+        try {
+            const json = JSON.stringify(err);
+            if (json && json !== "{}")
+                return json;
+        }
+        catch { /* circular — fall through */ }
+        // Last resort for objects: try toString, check it's not the useless default
+        const str = String(err);
+        if (str !== "[object Object]")
+            return str;
+        return "Unknown error (non-serializable object)";
+    }
+    if (err === undefined)
+        return "Unknown error (undefined)";
+    if (err === null)
+        return "Unknown error (null)";
+    return String(err);
+}
+/**
+ * Check if a file is ignored by git (respects all .gitignore files, global gitignore,
+ * and .git/info/exclude). Returns false if not in a git repo or git is unavailable.
+ */
+function isGitIgnored(filePath, cwd) {
+    try {
+        (0, child_process_1.execSync)(`git check-ignore -q "${filePath}"`, {
+            cwd,
+            stdio: "pipe",
+        });
+        return true; // exit code 0 = ignored
+    }
+    catch {
+        return false; // exit code 1 = not ignored, or git not available
+    }
+}
+/** Wraps a promise with a timeout. Rejects with a timeout error if not resolved within `ms`. */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Analysis timeout after ${ms / 1000}s for ${label}`)), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
 async function startWatch(options) {
     const { rootPath, pullFn, syncFn, json } = options;
     const dbPath = path.join(rootPath, ".ophan", "index.db");
     const lockPath = path.join(rootPath, ".ophan", "watch.lock");
-    // Check for existing watcher
+    // Check for existing watcher — kill it so only one instance runs at a time
     if (fs.existsSync(lockPath)) {
         try {
             const pid = parseInt(fs.readFileSync(lockPath, "utf-8").trim());
             process.kill(pid, 0); // Check if process is alive (signal 0 = no-op)
+            // Kill the existing watcher and take over
             if (json)
-                emit({ event: "error", message: `Another watcher is running (PID ${pid})` });
+                emit({ event: "replacing_watcher", oldPid: pid });
             else
-                console.error(`Another watcher is already running (PID ${pid}). Kill it or remove .ophan/watch.lock`);
-            process.exit(1);
+                console.log(`  Stopping previous watcher (PID ${pid})...`);
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { /* already dying */ }
+            // Brief wait for process to exit and release resources
+            await new Promise((resolve) => setTimeout(resolve, 500));
         }
         catch {
             // Process is dead — stale lock file, continue
@@ -74,33 +137,78 @@ async function startWatch(options) {
         console.log("🔮 Ophan watching...\n");
     if (!json)
         console.log("  Running initial scan...");
-    const scanResult = await (0, core_1.analyzeRepository)(rootPath, (current, total, file) => {
-        if (!json && process.stdout.isTTY) {
-            process.stdout.clearLine(0);
-            process.stdout.cursorTo(0);
-            process.stdout.write(`  [${current}/${total}] ${file}`);
+    const INITIAL_SCAN_RETRIES = 2;
+    const PROGRESS_THROTTLE_MS = 500;
+    let scanSucceeded = false;
+    for (let attempt = 0; attempt <= INITIAL_SCAN_RETRIES; attempt++) {
+        try {
+            let lastProgressEmit = 0;
+            const scanResult = await (0, core_1.analyzeRepository)(rootPath, (current, total, file) => {
+                if (json) {
+                    const now = Date.now();
+                    if (now - lastProgressEmit > PROGRESS_THROTTLE_MS || current === total) {
+                        emit({ event: "scan_progress", current, total, file });
+                        lastProgressEmit = now;
+                    }
+                }
+                else if (process.stdout.isTTY) {
+                    process.stdout.clearLine(0);
+                    process.stdout.cursorTo(0);
+                    process.stdout.write(`  [${current}/${total}] ${file}`);
+                }
+            }, pullFn);
+            if (json) {
+                emit({
+                    event: "scan_complete",
+                    files: scanResult.files,
+                    analyzed: scanResult.analyzed,
+                    cached: scanResult.skipped,
+                    pulled: scanResult.pulled,
+                });
+            }
+            else {
+                console.log(`\n  Initial scan: ${scanResult.analyzed} analyzed, ${scanResult.skipped} cached` +
+                    (scanResult.pulled ? ` (${scanResult.pulled} from cloud)` : "") +
+                    ` across ${scanResult.files} files`);
+            }
+            // Sync after initial scan if anything was analyzed
+            if (syncFn && scanResult.analyzed > 0) {
+                await runSync(syncFn, json);
+            }
+            scanSucceeded = true;
+            break;
+        }
+        catch (err) {
+            const msg = formatError(err);
+            if (attempt < INITIAL_SCAN_RETRIES) {
+                const delay = (attempt + 1) * 3000;
+                if (json) {
+                    emit({ event: "retry", attempt: attempt + 1, maxAttempts: INITIAL_SCAN_RETRIES + 1, message: msg, delayMs: delay });
+                }
+                else {
+                    console.error(`\n  ❌ Initial scan failed: ${msg}. Retrying in ${delay / 1000}s...`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            else {
+                if (json) {
+                    emit({ event: "error", message: `Initial scan failed after ${INITIAL_SCAN_RETRIES + 1} attempts: ${msg}` });
+                }
+                else {
+                    console.error(`\n  ❌ Initial scan failed after ${INITIAL_SCAN_RETRIES + 1} attempts: ${msg}`);
+                }
+            }
         }
-    }, pullFn);
-    if (json) {
-        emit({
-            event: "scan_complete",
-            files: scanResult.files,
-            analyzed: scanResult.analyzed,
-            cached: scanResult.skipped,
-            pulled: scanResult.pulled,
-        });
-    }
-    else {
-        console.log(`\n  Initial scan: ${scanResult.analyzed} analyzed, ${scanResult.skipped} cached` +
-            (scanResult.pulled ? ` (${scanResult.pulled} from cloud)` : "") +
-            ` across ${scanResult.files} files`);
     }
-    // Sync after initial scan if anything was analyzed
-    if (syncFn && scanResult.analyzed > 0) {
-        await runSync(syncFn, json);
+    if (!scanSucceeded) {
+        // Continue to file watching — incremental analysis can still work.
+        // Individual file changes will trigger re-analysis.
+        if (json)
+            emit({ event: "error", message: "Continuing in watch-only mode. File changes will trigger analysis." });
     }
     // Phase 2: Open DB for incremental watching
     const db = (0, core_1.initDb)(dbPath);
+    const practices = (0, core_1.loadPracticesFromDb)(db);
     const extSet = new Set((0, core_1.getSupportedExtensions)().map((e) => e.toLowerCase()));
     const DEBOUNCE_MS = 5000;
     const SYNC_DEBOUNCE_MS = 10000;
@@ -123,12 +231,20 @@ async function startWatch(options) {
             }
         }, SYNC_DEBOUNCE_MS);
     }
-    // FIFO analysis queue
+    // FIFO analysis queue with circuit breaker
     let analyzing = false;
     const queue = [];
+    const MAX_CONSECUTIVE_ERRORS = 3;
+    const CIRCUIT_BREAKER_COOLDOWN_MS = 30000;
+    const ANALYSIS_TIMEOUT_MS = 120000;
+    let consecutiveErrors = 0;
+    let circuitBrokenUntil = 0;
     async function processQueue() {
         if (analyzing || queue.length === 0)
             return;
+        // Circuit breaker: stop processing if too many consecutive errors
+        if (Date.now() < circuitBrokenUntil)
+            return;
         analyzing = true;
         while (queue.length > 0) {
             const file = queue.shift();
@@ -139,7 +255,8 @@ async function startWatch(options) {
                 console.log(`  Analyzing ${relPath}...`);
             const start = Date.now();
             try {
-                const result = await (0, core_1.analyzeFiles)(db, rootPath, [file], { pullFn });
+                const result = await withTimeout((0, core_1.analyzeFiles)(db, rootPath, [file], { pullFn, practices }), ANALYSIS_TIMEOUT_MS, relPath);
+                consecutiveErrors = 0; // Reset on success
                 const duration = Date.now() - start;
                 if (json) {
                     emit({
@@ -160,17 +277,38 @@ async function startWatch(options) {
                 }
             }
             catch (err) {
+                consecutiveErrors++;
+                const msg = formatError(err);
                 if (json) {
-                    emit({ event: "error", file: relPath, message: err.message });
+                    emit({ event: "error", file: relPath, message: msg });
                 }
                 else {
-                    console.error(`  ❌ ${relPath}: ${err.message}`);
+                    console.error(`  ❌ ${relPath}: ${msg}`);
+                }
+                // Circuit breaker: pause after repeated failures
+                if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                    circuitBrokenUntil = Date.now() + CIRCUIT_BREAKER_COOLDOWN_MS;
+                    const remaining = queue.length;
+                    if (json) {
+                        emit({
+                            event: "error",
+                            message: `${MAX_CONSECUTIVE_ERRORS} consecutive failures — pausing analysis for ${CIRCUIT_BREAKER_COOLDOWN_MS / 1000}s. ${remaining} file(s) queued for retry.`,
+                        });
+                    }
+                    else {
+                        console.error(`  ⏸ ${MAX_CONSECUTIVE_ERRORS} consecutive failures — pausing for ${CIRCUIT_BREAKER_COOLDOWN_MS / 1000}s`);
+                    }
+                    break; // Leave remaining files in queue for retry after cooldown
                 }
             }
         }
         analyzing = false;
     }
-    const IGNORE_SEGMENTS = ["node_modules", ".ophan", "__pycache__", ".venv", "venv", ".tox", ".eggs", "dist"];
+    // Fast-path segments that are always ignored (avoids git subprocess for common cases)
+    const ALWAYS_IGNORE = ["node_modules", ".ophan"];
+    // Cache of directory prefixes known to be gitignored — avoids repeated git check-ignore calls
+    // for files in the same ignored directory (e.g. .output/public/assets/a.js, .output/public/assets/b.js)
+    const ignoredDirCache = new Set();
     function onFileChange(filename) {
         const ext = path.extname(filename).toLowerCase();
         if (!extSet.has(ext))
@@ -178,9 +316,21 @@ async function startWatch(options) {
         const absPath = path.isAbsolute(filename)
             ? filename
             : path.resolve(rootPath, filename);
-        // Skip ignored directories
-        if (IGNORE_SEGMENTS.some((seg) => absPath.includes(`/${seg}/`) || absPath.includes(`\\${seg}\\`)))
+        // Fast-path: skip universally-ignored directories without shelling out to git
+        if (ALWAYS_IGNORE.some((seg) => absPath.includes(`/${seg}/`) || absPath.includes(`\\${seg}\\`)))
             return;
+        // Check directory-level cache before calling git
+        const dir = path.dirname(absPath);
+        for (const cached of ignoredDirCache) {
+            if (dir.startsWith(cached))
+                return;
+        }
+        // Ask git whether this file is ignored (respects all .gitignore files + global)
+        if (isGitIgnored(absPath, rootPath)) {
+            // Cache the directory so sibling files skip the git call
+            ignoredDirCache.add(dir);
+            return;
+        }
         // Skip if file was deleted
         if (!fs.existsSync(absPath))
             return;
@@ -193,7 +343,13 @@ async function startWatch(options) {
             if (!queue.includes(absPath)) {
                 queue.push(absPath);
             }
-            processQueue();
+            processQueue().catch((err) => {
+                const msg = formatError(err);
+                if (json)
+                    emit({ event: "error", message: msg });
+                else
+                    console.error(`  ❌ Analysis error: ${msg}`);
+            });
         }, DEBOUNCE_MS));
     }
     // Start recursive file watcher (macOS + Windows native, Linux may need chokidar)

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@ophan/cli",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "files": [
-    "dist"
+    "dist",
+    "ophan_logo.png"
   ],
   "bin": {
     "ophan": "./dist/index.js"
@@ -15,9 +16,10 @@
   "dependencies": {
     "@ophan/core": "workspace:*",
     "@supabase/supabase-js": "^2.49.4",
-    "better-sqlite3": "^11.9.1",
+    "better-sqlite3": "^12.6.2",
     "commander": "^14.0.2",
     "dotenv": "^16.4.7",
+    "p-limit": "^6.2.0",
     "open": "^10.1.0"
   },
   "devDependencies": {