brainbank 0.1.3 → 0.1.4

package/src/cli/commands/mcp-export.ts

@@ -0,0 +1,273 @@
+/**
+ * brainbank mcp:export [target] — Export MCP server config for AI IDEs.
+ *
+ * Generates the MCP server config block for brainbank and merges it into
+ * the target IDE's config file. Currently supports: antigravity.
+ *
+ * Detects: node path, cli.js path, API keys from config or env vars.
+ */
+
+import type { ProjectConfig } from '@/cli/factory/config-loader.ts';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c, args, getFlag } from '@/cli/utils.ts';
+import { getConfig } from '@/cli/factory/index.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Supported export targets and their config file paths. */
+const TARGETS: Record<string, { configPath: string; label: string }> = {
+    antigravity: {
+        configPath: path.join(process.env.HOME ?? '~', '.gemini', 'antigravity', 'mcp_config.json'),
+        label: 'Gemini Antigravity',
+    },
+};
+
+interface McpServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+
+interface McpConfig {
+    mcpServers: Record<string, McpServerConfig>;
+}
+
+/**
+ * Build the brainbank MCP server config block.
+ * Resolves node binary, dist/cli.js path, and API keys.
+ */
+function buildBrainbankMcpBlock(config: ProjectConfig | null): McpServerConfig {
+    const nodeBin = process.execPath;
+
+    // Resolve dist/cli.js from the global install location (node_prefix/lib/node_modules/brainbank/dist/cli.js)
+    const globalCliJs = path.join(path.dirname(nodeBin), '..', 'lib', 'node_modules', 'brainbank', 'dist', 'cli.js');
+    // Fallback: relative to this file (dev / npm link)
+    const localCliJs = path.resolve(__dirname, '..', '..', 'dist', 'cli.js');
+    const resolvedCliJs = fs.existsSync(globalCliJs) ? globalCliJs : localCliJs;
+
+    const env: Record<string, string> = {};
+
+    // Resolve API keys: config.keys > env vars
+    const keys = config?.keys;
+    const perplexityKey = keys?.perplexity ?? process.env.PERPLEXITY_API_KEY;
+    const anthropicKey = keys?.anthropic ?? process.env.ANTHROPIC_API_KEY;
+    const openaiKey = keys?.openai ?? process.env.OPENAI_API_KEY;
+
+    if (perplexityKey) env.PERPLEXITY_API_KEY = perplexityKey;
+    if (anthropicKey) env.ANTHROPIC_API_KEY = anthropicKey;
+    if (openaiKey) env.OPENAI_API_KEY = openaiKey;
+
+    const block: McpServerConfig = {
+        command: nodeBin,
+        args: ['--disable-warning=ExperimentalWarning', resolvedCliJs, 'mcp'],
+    };
+
+    if (Object.keys(env).length > 0) {
+        block.env = env;
+    }
+
+    return block;
+}
+
+/**
+ * Load existing MCP config, merge brainbank entry, and write back.
+ * Preserves all other server entries.
+ */
+function mergeAndWrite(targetPath: string, block: McpServerConfig): { created: boolean } {
+    let existing: McpConfig = { mcpServers: {} };
+    const created = !fs.existsSync(targetPath);
+
+    if (!created) {
+        try {
+            const raw = fs.readFileSync(targetPath, 'utf-8');
+            existing = JSON.parse(raw) as McpConfig;
+            if (!existing.mcpServers) existing.mcpServers = {};
+        } catch {
+            // Corrupt or empty file — start fresh
+            existing = { mcpServers: {} };
+        }
+    }
+
+    existing.mcpServers.brainbank = block;
+
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, JSON.stringify(existing, null, 2) + '\n');
+
+    return { created };
+}
+
+/** Check if an MCP config already has a brainbank entry. */
+export function hasBrainbankMcpEntry(targetPath: string): boolean {
+    if (!fs.existsSync(targetPath)) return false;
+    try {
+        const raw = fs.readFileSync(targetPath, 'utf-8');
+        const config = JSON.parse(raw) as McpConfig;
+        return !!config.mcpServers?.brainbank;
+    } catch {
+        return false;
+    }
+}
+
+/** Auto-export: called after index when Antigravity is detected. */
+export async function autoExportMcp(repoPath: string): Promise<void> {
+    const target = TARGETS.antigravity;
+    if (!target) return;
+
+    // Only auto-export if Antigravity dir exists
+    const antigravityDir = path.dirname(target.configPath);
+    if (!fs.existsSync(antigravityDir)) return;
+
+    // Only auto-export if brainbank isn't already configured
+    if (hasBrainbankMcpEntry(target.configPath)) return;
+
+    const config = await getConfig(repoPath);
+    const block = buildBrainbankMcpBlock(config);
+    mergeAndWrite(target.configPath, block);
+    console.log(`  ${c.green('✓')} Exported MCP config to ${c.dim(path.relative(process.env.HOME ?? '', target.configPath))}`);
+}
+
+// ── GEMINI.md BrainBank Section ──────────────────────────────
+
+const BRAINBANK_SECTION_MARKER = '<!-- brainbank:start -->';
+const BRAINBANK_SECTION_END = '<!-- brainbank:end -->';
+
+/** Global GEMINI.md path — ~/.gemini/GEMINI.md (shared across all projects). */
+const GLOBAL_GEMINI = path.join(process.env.HOME ?? '~', '.gemini', 'GEMINI.md');
+
+function buildGeminiSection(): string {
+    return `${BRAINBANK_SECTION_MARKER}
+
+## BrainBank — Code Intelligence
+
+**\`brainbank_context\`** — semantic code discovery. Use it **only** when you need to understand functionality that spans multiple files (e.g. "how does auth work", "notification pipeline"). \`repo\` is **required**.
+
+**Do NOT use it for:** finding a specific string, variable, function name, or exact match — use \`grep_search\` for that. BrainBank is for *understanding context*, not for *locating text*.
+
+**Params:** \`compact: false\`, \`sources: { code: 25, docs: 0, git: 0 }\`. Only add \`docs\` when the user explicitly asks about documentation.
+
+### Output handling — MANDATORY
+
+BrainBank may return results **inline** or save them to an **output file**:
+
+- **Inline:** read and proceed normally.
+- **File result** (saved to \`output.txt\`): you **MUST STOP IMMEDIATELY**. Show the path as a clickable link, ask the user to paste, then **DO NOT PROCEED**:
+
+  📋 Output: [output.txt](file:///path/to/output.txt) — _"Could you paste the context output here?"_
+
+  **NEVER** read the file yourself. **NEVER** continue working. Wait for the user to paste the content. This is not optional.
+
+${BRAINBANK_SECTION_END}
+`;
+}
+
+/** Check if GEMINI.md already has the brainbank section. */
+function hasGeminiSection(geminiPath: string): boolean {
+    if (!fs.existsSync(geminiPath)) return false;
+    const content = fs.readFileSync(geminiPath, 'utf-8');
+    return content.includes(BRAINBANK_SECTION_MARKER);
+}
+
+/** Append BrainBank section to GEMINI.md (creates if doesn't exist). */
+function appendGeminiSection(geminiPath: string): void {
+    const section = buildGeminiSection();
+    if (fs.existsSync(geminiPath)) {
+        fs.appendFileSync(geminiPath, section);
+    } else {
+        fs.writeFileSync(geminiPath, `# GEMINI.md\n${section}`);
+    }
+}
+
+/** Replace BrainBank section between markers in GEMINI.md. */
+function replaceGeminiSection(geminiPath: string): void {
+    const content = fs.readFileSync(geminiPath, 'utf-8');
+    const startIdx = content.indexOf(BRAINBANK_SECTION_MARKER);
+    const endIdx = content.indexOf(BRAINBANK_SECTION_END);
+    if (startIdx === -1 || endIdx === -1) return;
+
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + BRAINBANK_SECTION_END.length);
+    const section = buildGeminiSection();
+    fs.writeFileSync(geminiPath, before + section + after);
+}
+
+/** CLI command: brainbank mcp:export [target] [--force] */
+export async function cmdMcpExport(): Promise<void> {
+    const targetName = args[1] || getFlag('target') || 'antigravity';
+    const repoPath = getFlag('repo') || '.';
+    const force = args.includes('--force') || args.includes('-f');
+
+    const target = TARGETS[targetName];
+    if (!target) {
+        console.error(c.red(`Unknown export target: ${targetName}`));
+        console.error(c.dim(`  Available: ${Object.keys(TARGETS).join(', ')}`));
+        process.exit(1);
+    }
+
+    const config = await getConfig(repoPath);
+    const block = buildBrainbankMcpBlock(config);
+
+    console.log(c.bold(`\n━━━ MCP Export: ${target.label} ━━━\n`));
+
+    // ── MCP Config ────────────────────────────────────────────
+    const mcpExists = hasBrainbankMcpEntry(target.configPath);
+    let writeMcp = true;
+
+    if (mcpExists && !force) {
+        console.log(`  ${c.yellow('●')} MCP config already has brainbank entry`);
+        const cliPath = block.args.find(a => !a.startsWith('--')) ?? block.args[0];
+        console.log(`  ${c.dim('  New:')} ${block.command} ${cliPath}`);
+        const envKeys = block.env ? Object.keys(block.env) : [];
+        if (envKeys.length > 0) console.log(`  ${c.dim('  Keys:')} ${envKeys.join(', ')}`);
+        const { confirm } = await import('@inquirer/prompts');
+        writeMcp = await confirm({ message: 'Override existing brainbank MCP entry?', default: true });
+    }
+
+    if (writeMcp) {
+        const { created } = mergeAndWrite(target.configPath, block);
+        console.log(`  ${c.green('✓')} ${created ? 'Created' : 'Updated'} ${c.dim(target.configPath)}`);
+    } else {
+        console.log(`  ${c.dim('MCP config — skipped')}`);
+    }
+
+    // ── Global GEMINI.md (~/.gemini/GEMINI.md) ────────────────
+    const geminiHasSection = hasGeminiSection(GLOBAL_GEMINI);
+
+    if (geminiHasSection) {
+        if (force) {
+            replaceGeminiSection(GLOBAL_GEMINI);
+            console.log(`  ${c.green('✓')} Replaced BrainBank section in ${c.dim('~/.gemini/GEMINI.md')}`);
+        } else {
+            console.log(`  ${c.yellow('●')} ~/.gemini/GEMINI.md already has BrainBank section`);
+            const { confirm } = await import('@inquirer/prompts');
+            const override = await confirm({ message: 'Override existing BrainBank section?', default: false });
+            if (override) {
+                replaceGeminiSection(GLOBAL_GEMINI);
+                console.log(`  ${c.green('✓')} Replaced BrainBank section in ${c.dim('~/.gemini/GEMINI.md')}`);
+            } else {
+                console.log(`  ${c.dim('GEMINI.md — skipped')}`);
+            }
+        }
+    } else {
+        if (force) {
+            appendGeminiSection(GLOBAL_GEMINI);
+            console.log(`  ${c.green('✓')} Added BrainBank section to ${c.dim('~/.gemini/GEMINI.md')}`);
+        } else {
+            const { confirm } = await import('@inquirer/prompts');
+            const addGemini = await confirm({
+                message: 'Add BrainBank instructions to ~/.gemini/GEMINI.md? (teaches AI tools how to use BrainBank)',
+                default: true,
+            });
+            if (addGemini) {
+                appendGeminiSection(GLOBAL_GEMINI);
+                console.log(`  ${c.green('✓')} Added BrainBank section to ${c.dim('~/.gemini/GEMINI.md')}`);
+            }
+        }
+    }
+
+    console.log(`\n  ${c.dim('Restart your IDE to apply changes.')}\n`);
+}

package/src/cli/commands/mcp.ts

@@ -0,0 +1,6 @@
+/** brainbank mcp — Start MCP server (stdio). */
+
+export async function cmdMcp(): Promise<void> {
+    // Import and run the MCP server directly from core
+    await import('@/mcp/mcp-server.ts');
+}

package/src/cli/commands/query.ts

@@ -0,0 +1,167 @@
+/**
+ * brainbank query <task> — Get formatted context for a task
+ *
+ * Primary command for semantic code search + LLM-pruned context.
+ *
+ * Flags:
+ *   --context <desc>   General task context for the pruner (inline or @file)
+ *   --pruner <desc>    Specific pruning instructions for the pruner
+ *   --code 20          Max code results (default: 20)
+ *   --git 5            Max git results
+ *   --no-git           Skip git results
+ *   --no-code          Skip code results
+ *   --path <dir>       Filter results to files under path prefix(es)
+ *   --ignore <paths>   Exclude paths (comma-separated or repeated)
+ */
+
+import * as fs from 'node:fs';
+import { c, args, stripFlags, getFlag, getFlagAll } from '@/cli/utils.ts';
+import { createBrain } from '@/cli/factory/index.ts';
+import { tryServerContext } from '@/cli/server-client.ts';
+
+/** Parse --code N, --git N, --no-git, --no-code flags into sources map. */
+function parseSourceFlags(): Record<string, number> {
+    const NON_SOURCE = new Set([
+        'repo', 'depth', 'collection', 'pattern', 'context', 'pruner', 'name',
+        'keep', 'only', 'docs-path', 'mode', 'limit',
+        'ignore', 'meta', 'k', 'yes', 'y', 'force', 'verbose', 'path',
+    ]);
+    const sources: Record<string, number> = {};
+    for (let i = 0; i < args.length; i++) {
+        if (!args[i].startsWith('--')) continue;
+        const name = args[i].slice(2);
+        // --no-git, --no-code → set to 0
+        if (name.startsWith('no-')) {
+            sources[name.slice(3)] = 0;
+            continue;
+        }
+        // --code 20, --git 5
+        const next = args[i + 1];
+        if (next !== undefined && /^\d+$/.test(next) && !NON_SOURCE.has(name)) {
+            sources[name] = parseInt(next, 10);
+            i++;
+        }
+    }
+    return sources;
+}
+
+/** Read a flag value that supports inline string or @file references. */
+function readFlagValue(flagName: string): string | undefined {
+    const raw = getFlag(flagName);
+    if (!raw) return undefined;
+
+    if (raw.startsWith('@')) {
+        const filePath = raw.slice(1);
+        try {
+            return fs.readFileSync(filePath, 'utf-8').trim();
+        } catch {
+            console.error(c.red(`Cannot read ${flagName} file: ${filePath}`));
+            process.exit(1);
+        }
+    }
+    return raw;
+}
+
+export async function cmdQuery(): Promise<void> {
+    const task = stripFlags(args).slice(1).join(' ');
+    if (!task) {
+        console.log(c.red('Usage: brainbank query <task description>'));
+        console.log(c.dim('  Options:'));
+        console.log(c.dim('    --context <desc|@file>   General task context for the pruner'));
+        console.log(c.dim('    --pruner <desc>          Specific pruning focus'));
+        console.log(c.dim('    --path <dir>             Filter to files under path'));
+        console.log(c.dim('    --code N --git N         Source limits'));
+        process.exit(1);
+    }
+
+    const sources = parseSourceFlags();
+    const rawPath = getFlag('path');
+    const pathPrefix = rawPath
+        ? rawPath.split(',').map(p => p.trim()).filter(Boolean)
+        : undefined;
+    const normalizedPath = pathPrefix && pathPrefix.length === 1 ? pathPrefix[0] : pathPrefix;
+    const ignorePaths = getFlagAll('ignore');
+    const repo = getFlag('repo');
+
+    // Parse --context and --pruner flags (both support inline or @file)
+    const contextDesc = readFlagValue('context');
+    const prunerDesc = readFlagValue('pruner');
+
+    // Parse BrainBankQL field flags
+    const fields = parseFieldFlags();
+
+    // Try HTTP server delegation first
+    const serverResult = await tryServerContext({
+        task,
+        repo: repo ?? process.cwd(),
+        sources: Object.keys(sources).length > 0 ? sources : undefined,
+        pathPrefix: normalizedPath,
+        ignorePaths: ignorePaths.length > 0 ? ignorePaths : undefined,
+        fields: Object.keys(fields).length > 0 ? fields : undefined,
+        context: contextDesc,
+        prunerContext: prunerDesc,
+    });
+
+    if (serverResult !== null) {
+        console.log(serverResult);
+        return;
+    }
+
+    // Fall back to local
+    const brain = await createBrain();
+    const result = await brain.getContext(task, {
+        sources: Object.keys(sources).length > 0 ? sources : undefined,
+        pathPrefix: normalizedPath,
+        ignorePaths: ignorePaths.length > 0 ? ignorePaths : undefined,
+        source: 'cli',
+        fields: Object.keys(fields).length > 0 ? fields : undefined,
+        context: contextDesc,
+        prunerContext: prunerDesc,
+    });
+    console.log(result);
+    brain.close();
+}
+
+/** Parse BrainBankQL field flags: --lines, --symbols, --compact, --no-callTree, --callTree.depth=N, etc. */
+function parseFieldFlags(): Record<string, unknown> {
+    const FIELD_BOOLEANS = new Set(['lines', 'symbols', 'compact']);
+    const FIELD_NEGATABLE = new Set(['callTree', 'imports']);
+    const fields: Record<string, unknown> = {};
+
+    for (let i = 0; i < args.length; i++) {
+        if (!args[i].startsWith('--')) continue;
+        const raw = args[i].slice(2);
+
+        // --no-callTree, --no-imports → set to false
+        if (raw.startsWith('no-')) {
+            const name = raw.slice(3);
+            if (FIELD_NEGATABLE.has(name)) {
+                fields[name] = false;
+            }
+            continue;
+        }
+
+        // --callTree.depth=4 → { depth: 4 }
+        const dotIdx = raw.indexOf('.');
+        if (dotIdx > 0) {
+            const fieldName = raw.slice(0, dotIdx);
+            const rest = raw.slice(dotIdx + 1);
+            const eqIdx = rest.indexOf('=');
+            if (eqIdx > 0) {
+                const key = rest.slice(0, eqIdx);
+                const val = parseInt(rest.slice(eqIdx + 1), 10);
+                if (!isNaN(val)) {
+                    fields[fieldName] = { [key]: val };
+                }
+            }
+            continue;
+        }
+
+        // --lines, --symbols, --compact → true
+        if (FIELD_BOOLEANS.has(raw)) {
+            fields[raw] = true;
+        }
+    }
+
+    return fields;
+}

package/src/cli/commands/reembed.ts

@@ -0,0 +1,30 @@
+/** brainbank reembed — Re-embed all vectors. */
+
+import { c } from '@/cli/utils.ts';
+import { createBrain } from '@/cli/factory/index.ts';
+
+export async function cmdReembed(): Promise<void> {
+    const brain = await createBrain();
+    await brain.initialize();
+
+    console.log(c.bold('\n━━━ BrainBank Re-embed ━━━\n'));
+    console.log(c.dim('  Regenerating vectors with current embedding provider...'));
+    console.log(c.dim('  Text, FTS, and metadata remain unchanged.\n'));
+
+    const result = await brain.reembed({
+        onProgress: (table: string, current: number, total: number) => {
+            process.stdout.write(`\r  ${c.cyan(table.padEnd(8))} ${current}/${total}`);
+        },
+    });
+
+    console.log('\n');
+    for (const [name, count] of Object.entries(result.counts)) {
+        if (count > 0) {
+            const label = name.charAt(0).toUpperCase() + name.slice(1);
+            console.log(`  ${c.green('✓')} ${label.padEnd(8)} ${count} vectors`);
+        }
+    }
+    console.log(`\n  ${c.bold('Total')}: ${result.total} vectors regenerated\n`);
+
+    brain.close();
+}

package/src/cli/commands/reindex.ts

@@ -0,0 +1,40 @@
+/**
+ * brainbank reindex [path] — Nuke data and re-index from scratch.
+ *
+ * Deletes the .brainbank/data/ directory (SQLite DB + HNSW index)
+ * then runs a headless `index --yes` to rebuild everything.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { c, args, stripFlags } from '@/cli/utils.ts';
+import { cmdIndex } from './index.ts';
+
+export async function cmdReindex(): Promise<void> {
+    const positional = stripFlags(args);
+    const repoPath = path.resolve(positional[1] || '.');
+    const dataDir = path.join(repoPath, '.brainbank', 'data');
+
+    if (fs.existsSync(dataDir)) {
+        const entries = fs.readdirSync(dataDir);
+        console.log(c.bold('\n━━━ Reindex ━━━\n'));
+        console.log(`  ${c.yellow('✗')} Deleting ${path.relative(process.cwd(), dataDir)}/ (${entries.length} files)`);
+        fs.rmSync(dataDir, { recursive: true, force: true });
+        console.log(`  ${c.green('✓')} Data cleared\n`);
+    } else {
+        console.log(c.bold('\n━━━ Reindex ━━━\n'));
+        console.log(c.dim('  No existing data — fresh index\n'));
+    }
+
+    // Inject --yes into args so index runs headless (no TUI)
+    if (!args.includes('--yes') && !args.includes('-y')) {
+        args.push('--yes');
+    }
+
+    // Force re-index all files
+    if (!args.includes('--force')) {
+        args.push('--force');
+    }
+
+    return cmdIndex();
+}