@ophan/cli 0.0.1

package/README.md

@@ -0,0 +1,82 @@
+# @ophan/cli
+
+Command-line interface for analyzing codebases and managing Ophan databases.
+
+## Usage
+
+### Repository Analysis
+```bash
+# Analyze a repo (creates .ophan/index.db)
+npx ophan analyze --path /path/to/repo
+
+# Or as dev dependency
+npm install --save-dev ophan
+npx ophan analyze
+```
+
+### Commands
+- `ophan analyze` — Scan repo, extract functions, analyze with Claude, store by content hash
+- `ophan sync` — Push/pull analysis to/from Supabase (requires auth)
+- `ophan gc` — Garbage collect orphaned analysis entries (manual only, never automatic, 30-day grace period)
+
+## How Analysis Works
+
+### Initial Run
+1. Discovers all TypeScript/JavaScript source files
+2. Extracts functions, computes SHA256 content hash for each
+3. Checks local DB — skips functions with existing analysis for that hash
+4. Sends new functions to Claude for analysis
+5. Stores results in `function_analysis` (keyed by content_hash)
+6. Updates `file_functions` with file path, function name, content_hash, mtime
+
+### Incremental Updates
+1. Checks `file_mtime` in `file_functions` — skips entirely unchanged files (no parsing needed)
+2. Re-parses changed files, re-hashes functions
+3. Only analyzes functions with new/unknown hashes
+4. Updates `file_functions` mappings
+
+### Garbage Collection
+`ophan gc` is manual only — never runs automatically. This protects against branch switching scenarios (e.g. function deleted on feature branch but still exists on main).
+
+How it works:
+1. Scans codebase, computes all current hashes
+2. Compares to stored `function_analysis` entries
+3. Only deletes entries not seen in grace period (default 30 days, configurable)
+4. Updates `last_referenced_at` in Supabase for synced entries
+5. If synced, GC'd entries can be re-downloaded on next sync instead of re-analyzed
+
+`file_functions` is ephemeral — rebuilt on every scan. `function_analysis` is persistent until explicit GC.
+
+### Sync
+`ophan sync` pushes/pulls `function_analysis` rows to/from Supabase:
+- Insert-only (content-addressed = immutable, no conflicts)
+- Free users: scoped to `user_id`
+- Team users: scoped to `team_id` (new members pull existing analysis)
+
+## Design Principles
+
+### Local-First
+All analysis stored in per-repo `.ophan/index.db` (gitignored). No cloud required for core functionality. Supabase sync is optional.
+
+### Dev Dependency Model
+Add to `devDependencies` — one engineer installs, whole team gets CLI on `npm install`. Bottom-up adoption path.
+
+### Non-Invasive
+Database in hidden `.ophan/` directory, gitignored. Does not modify source code or project configuration.
+
+### Content-Addressed
+Analysis keyed by function content hash, not file path. Branch-agnostic, merge-friendly, deduplication built in.
+
+## Output
+
+Creates `.ophan/index.db` containing:
+- `function_analysis` — content_hash, analysis JSON, model version, timestamp
+- `file_functions` — file path, function name, content_hash, file mtime
+
+## CI/CD Integration
+
+### GitHub Action (Planned)
+Run `ophan analyze` on PRs:
+- Comment with new function documentation
+- Fail if new security warnings introduced
+- Show data flow changes in PR review

package/dist/auth.js

@@ -0,0 +1,239 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCredentials = readCredentials;
+exports.saveCredentials = saveCredentials;
+exports.deleteCredentials = deleteCredentials;
+exports.login = login;
+exports.getAuthenticatedClient = getAuthenticatedClient;
+const supabase_js_1 = require("@supabase/supabase-js");
+const http = __importStar(require("http"));
+const net = __importStar(require("net"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const CREDENTIALS_DIR = path.join(os.homedir(), ".ophan");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+function readCredentials() {
+    try {
+        const data = fs.readFileSync(CREDENTIALS_FILE, "utf8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+function saveCredentials(creds) {
+    fs.mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), "utf8");
+}
+function deleteCredentials() {
+    try {
+        fs.unlinkSync(CREDENTIALS_FILE);
+    }
+    catch {
+        // Already gone
+    }
+}
+function findAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                server.close();
+                return reject(new Error("Could not find available port"));
+            }
+            const port = addr.port;
+            server.close(() => resolve(port));
+        });
+        server.on("error", reject);
+    });
+}
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html>
+<head><title>Ophan CLI</title>
+<style>
+  body { font-family: -apple-system, system-ui, sans-serif; display: flex;
+    justify-content: center; align-items: center; min-height: 100vh;
+    margin: 0; background: #0a0a0a; color: #fafafa; }
+  .card { text-align: center; padding: 3rem; }
+  h1 { color: #2dd4bf; margin-bottom: 0.5rem; }
+  p { color: #a3a3a3; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1>Logged in!</h1>
+    <p>You can close this tab and return to your terminal.</p>
+  </div>
+</body>
+</html>`;
+/**
+ * Browser-based login flow.
+ * 1. Start local HTTP server
+ * 2. Open browser to webapp /auth/cli?port=PORT
+ * 3. Wait for callback with tokens
+ * 4. Store credentials and return
+ */
+async function login(webappUrl, timeoutMs = 120000) {
+    const port = await findAvailablePort();
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("Login timed out. Please try again with `ophan login`."));
+        }, timeoutMs);
+        const server = http.createServer(async (req, res) => {
+            const url = new URL(req.url || "/", `http://localhost:${port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404, { Connection: "close" });
+                res.end("Not found");
+                return;
+            }
+            const tokenHash = url.searchParams.get("token_hash");
+            const supabaseUrl = url.searchParams.get("supabase_url");
+            const supabaseAnonKey = url.searchParams.get("supabase_anon_key");
+            if (!tokenHash || !supabaseUrl || !supabaseAnonKey) {
+                res.writeHead(400, { Connection: "close" });
+                res.end("Missing required parameters");
+                return;
+            }
+            // Exchange token_hash for an independent session via verifyOtp
+            const supabase = (0, supabase_js_1.createClient)(supabaseUrl, supabaseAnonKey, {
+                auth: {
+                    autoRefreshToken: false,
+                    persistSession: false,
+                },
+            });
+            const { data, error: otpError } = await supabase.auth.verifyOtp({
+                token_hash: tokenHash,
+                type: "magiclink",
+            });
+            if (otpError || !data.session) {
+                const msg = otpError?.message || "No session returned";
+                res.writeHead(400, {
+                    "Content-Type": "text/html",
+                    Connection: "close",
+                });
+                res.end(`<html><body style="font-family:system-ui;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#0a0a0a;color:#fafafa"><div style="text-align:center"><h1 style="color:#ef4444">Login failed</h1><p style="color:#a3a3a3">${msg}</p></div></body></html>`);
+                clearTimeout(timeout);
+                server.closeAllConnections();
+                server.close(() => reject(new Error(msg)));
+                return;
+            }
+            const creds = {
+                api_url: supabaseUrl,
+                api_key: supabaseAnonKey,
+                access_token: data.session.access_token,
+                refresh_token: data.session.refresh_token,
+                user_id: data.session.user.id,
+                email: data.session.user.email || "",
+                expires_at: data.session.expires_at || 0,
+            };
+            saveCredentials(creds);
+            // Connection: close tells browser to not keep-alive, so server.close() resolves immediately
+            res.writeHead(200, { "Content-Type": "text/html", Connection: "close" });
+            res.end(SUCCESS_HTML);
+            clearTimeout(timeout);
+            server.closeAllConnections();
+            server.close(() => resolve(creds));
+        });
+        server.listen(port, async () => {
+            const authUrl = `${webappUrl}/auth/cli?port=${port}`;
+            console.log(`\n  Opening browser to sign in...`);
+            console.log(`  If it doesn't open, visit: ${authUrl}\n`);
+            try {
+                const open = (await Promise.resolve().then(() => __importStar(require("open")))).default;
+                await open(authUrl);
+            }
+            catch {
+                // Browser open failed — user can still visit the URL manually
+            }
+        });
+        server.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+/**
+ * Get an authenticated Supabase client from stored credentials.
+ * Only refreshes tokens when they're actually expired — avoids consuming
+ * the refresh token unnecessarily (which would invalidate it via rotation).
+ */
+async function getAuthenticatedClient() {
+    const creds = readCredentials();
+    if (!creds) {
+        throw new Error("Not logged in. Run `ophan login` first.");
+    }
+    const supabase = (0, supabase_js_1.createClient)(creds.api_url, creds.api_key, {
+        auth: {
+            autoRefreshToken: false,
+            persistSession: false,
+        },
+    });
+    const now = Math.floor(Date.now() / 1000);
+    const BUFFER_SECONDS = 60;
+    if (creds.expires_at && creds.expires_at > now + BUFFER_SECONDS) {
+        // Access token still valid — set session without triggering refresh.
+        // This does NOT consume the refresh token.
+        const { error } = await supabase.auth.setSession({
+            access_token: creds.access_token,
+            refresh_token: creds.refresh_token,
+        });
+        if (!error) {
+            return { supabase, userId: creds.user_id };
+        }
+        // If setSession failed despite token appearing valid (e.g., revoked server-side),
+        // fall through to refresh attempt below.
+    }
+    // Access token expired (or missing expires_at) — explicitly refresh
+    const { data, error } = await supabase.auth.refreshSession({
+        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"}`);
+    }
+    // Persist the new tokens so next invocation can use the fresh access_token
+    // without consuming the refresh token again
+    const updated = {
+        ...creds,
+        access_token: data.session.access_token,
+        refresh_token: data.session.refresh_token,
+        expires_at: data.session.expires_at || 0,
+    };
+    saveCredentials(updated);
+    return { supabase, userId: creds.user_id };
+}

package/dist/index.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+"use strict";
+// @ophan/cli — Command-line orchestration layer
+//
+// Architecture:
+//   The CLI is a thin orchestration layer over @ophan/core. It owns the user-facing
+//   commands (analyze, gc, sync) and progress reporting, but delegates all analysis,
+//   parsing, hashing, and DB operations to the core package.
+//
+//   The CLI is IDE-agnostic — it works the same whether the user has VS Code, JetBrains,
+//   or no IDE at all. It creates .ophan/index.db which any IDE extension can read.
+//
+//   Language support is driven by core's extractFunctions() — when core gains Python/Go/Java
+//   parsers, the CLI automatically supports those languages with no changes needed here.
+//   The file glob pattern and language detection live in core, not in the CLI.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const commander_1 = require("commander");
+const core_1 = require("@ophan/core");
+const path = __importStar(require("path"));
+const auth_1 = require("./auth");
+const sync_1 = require("./sync");
+const watch_1 = require("./watch");
+const program = new commander_1.Command();
+program
+    .name("ophan")
+    .description("AI-powered code security analysis")
+    .version("0.0.1");
+/**
+ * Try to create a pull function for cloud sync.
+ * 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) {
+    const creds = (0, auth_1.readCredentials)();
+    if (!creds)
+        return undefined;
+    try {
+        const { supabase, userId } = await (0, auth_1.getAuthenticatedClient)();
+        const repoName = path.basename(rootPath);
+        const { data: repo } = await supabase
+            .from("repos")
+            .select("id")
+            .eq("user_id", userId)
+            .eq("name", repoName)
+            .single();
+        if (!repo)
+            return undefined;
+        return async (hashes) => {
+            await (0, sync_1.pullFromSupabase)(rootPath, supabase, userId, repo.id, hashes, (step) => console.log(`  ${step}`));
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runAnalyze(rootPath) {
+    console.log("🔮 Ophan analyzing...\n");
+    const pullFn = await createPullFn(rootPath);
+    const result = await (0, core_1.analyzeRepository)(rootPath, (current, total, file) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}\n`);
+    }, pullFn);
+    console.log(`\n✅ Done! ${result.analyzed} analyzed, ${result.skipped} cached` +
+        (result.pulled ? ` (${result.pulled} from cloud)` : "") +
+        ` across ${result.files} files` +
+        (result.skippedSize ? ` (${result.skippedSize} files skipped — too large)` : ""));
+    console.log(`   Database: .ophan/index.db`);
+}
+program
+    .command("analyze")
+    .description("Analyze repository for security issues and documentation")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .action(async (options) => {
+    await runAnalyze(path.resolve(options.path));
+});
+program
+    .command("gc")
+    .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")
+    .action(async (options) => {
+    const rootPath = path.resolve(options.path);
+    const maxAgeDays = parseInt(options.days, 10);
+    const dbPath = path.join(rootPath, ".ophan", "index.db");
+    console.log("🧹 Refreshing file index...\n");
+    await (0, core_1.refreshFileIndex)(rootPath, (current, total, file) => {
+        if (process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        process.stdout.write(`  [${current}/${total}] ${file}\n`);
+    });
+    console.log("\n\n🗑️  Cleaning orphaned entries...");
+    const result = (0, core_1.gcAnalysis)(dbPath, maxAgeDays);
+    console.log(`\n✅ Removed ${result.deleted} orphaned entries (grace period: ${maxAgeDays} days)`);
+});
+// ========== AUTH ==========
+const DEFAULT_WEBAPP_URL = "https://app.ophan.dev";
+program
+    .command("login")
+    .description("Sign in to ophan.dev via browser")
+    .option("--webapp-url <url>", "Webapp URL (default: https://app.ophan.dev)", process.env.OPHAN_WEBAPP_URL || DEFAULT_WEBAPP_URL)
+    .action(async (options) => {
+    const existing = (0, auth_1.readCredentials)();
+    if (existing) {
+        // Validate the stored session is still good
+        try {
+            await (0, auth_1.getAuthenticatedClient)();
+            console.log(`  Already logged in as ${existing.email}`);
+            console.log(`  Run \`ophan logout\` first to switch accounts.`);
+            return;
+        }
+        catch {
+            // Session expired/invalid — delete stale credentials and re-login
+            console.log("  Previous session expired. Re-authenticating...");
+            (0, auth_1.deleteCredentials)();
+        }
+    }
+    try {
+        const creds = await (0, auth_1.login)(options.webappUrl);
+        console.log(`\n✅ Logged in as ${creds.email}`);
+    }
+    catch (err) {
+        console.error(`\n❌ Login failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command("logout")
+    .description("Sign out and remove stored credentials")
+    .action(() => {
+    (0, auth_1.deleteCredentials)();
+    console.log("✅ Logged out. Credentials removed.");
+});
+// ========== SYNC ==========
+program
+    .command("sync")
+    .description("Sync analysis to ophan.dev")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .action(async (options) => {
+    const rootPath = path.resolve(options.path);
+    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`
+                : ""));
+    }
+    catch (err) {
+        console.error(`\n❌ Sync failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ========== WATCH ==========
+program
+    .command("watch")
+    .description("Watch for file changes and auto-analyze")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .option("--json", "Output structured JSON events (for IDE integration)")
+    .option("--sync", "Auto-sync to cloud after each analysis batch")
+    .action(async (options) => {
+    const rootPath = path.resolve(options.path);
+    const pullFn = await createPullFn(rootPath);
+    let syncFn;
+    if (options.sync) {
+        const creds = (0, auth_1.readCredentials)();
+        if (creds) {
+            try {
+                const { supabase, userId } = await (0, auth_1.getAuthenticatedClient)();
+                syncFn = () => (0, sync_1.syncToSupabase)(rootPath, supabase, userId);
+            }
+            catch {
+                if (options.json) {
+                    process.stdout.write(JSON.stringify({ event: "sync_warning", message: "Session expired — sync disabled. Run ophan login." }) + "\n");
+                }
+                else {
+                    console.warn("  ⚠️  Session expired — sync disabled. Run `ophan 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");
+        }
+        else {
+            console.warn("  ⚠️  Not logged in — sync disabled. Run `ophan login` to enable cloud sync.");
+        }
+    }
+    await (0, watch_1.startWatch)({
+        rootPath,
+        pullFn,
+        syncFn,
+        json: options.json,
+    });
+});
+// Keep "init" as alias for "analyze" for backwards compat
+program
+    .command("init")
+    .description("Alias for analyze")
+    .option("-p, --path <path>", "Path to repository", process.cwd())
+    .action(async (options) => {
+    await runAnalyze(path.resolve(options.path));
+});
+program.parse();