brainbank 0.1.0-beta.1

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/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/scan.ts

@@ -0,0 +1,336 @@
+/**
+ * brainbank scan — Lightweight repo scanner for the interactive index flow.
+ *
+ * Scans the filesystem WITHOUT initializing BrainBank. Returns a ScanResult
+ * describing what's available to index via dynamic ScanModule descriptors.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import picomatch from 'picomatch';
+import { SUPPORTED_EXTENSIONS, isIgnoredDir, isIgnoredFile } from '@/lib/languages.ts';
+
+
+/** A single scannable module (plugin). */
+export interface ScanModule {
+    /** Plugin name (e.g. 'code', 'git', 'docs'). */
+    name: string;
+    /** Whether there's content available to index. */
+    available: boolean;
+    /** Human-readable summary (e.g. '1243 files (5 languages)'). */
+    summary: string;
+    /** Emoji icon for display. */
+    icon: string;
+    /** Whether checked by default in the prompt. */
+    checked: boolean;
+    /** Reason this module is disabled (shown in prompt). */
+    disabled?: string;
+    /** Detail lines for the scan tree (e.g. per-language breakdown). */
+    details?: string[];
+}
+
+export interface ScanResult {
+    repoPath: string;
+    modules: ScanModule[];
+    config: { exists: boolean; ignore?: string[]; include?: string[]; plugins?: string[] };
+    db: { exists: boolean; sizeMB: number; lastModified?: Date } | null;
+}
+
+
+/** Scan a repo path and return what's available to index. */
+export function scanRepo(repoPath: string): ScanResult {
+    const resolved = path.resolve(repoPath);
+    const config = scanConfig(resolved);
+
+    return {
+        repoPath: resolved,
+        modules: scanModules(resolved, config),
+        config,
+        db: scanDb(resolved),
+    };
+}
+
+/** Produce ScanModule descriptors for known plugin types. */
+function scanModules(repoPath: string, config: ScanResult['config']): ScanModule[] {
+    return [
+        scanCodeModule(repoPath, config.include, config.ignore),
+        scanGitModule(repoPath),
+        scanDocsModule(repoPath),
+    ];
+}
+
+
+/** Scan for indexable code files. Respects include/ignore from config. */
+function scanCodeModule(repoPath: string, include?: string[], ignore?: string[]): ScanModule {
+    const byLanguage = new Map<string, number>();
+    let total = 0;
+
+    // Build matchers from config patterns
+    let isIncluded: ((p: string) => boolean) | null = null;
+    let isIgnoredPat: ((p: string) => boolean) | null = null;
+    let includeBases: string[] | null = null;
+    if (include?.length) {
+        isIncluded = picomatch(include, { dot: true });
+        includeBases = include.map(p => picomatch.scan(p).base).filter(b => b && b !== '.');
+    }
+    if (ignore?.length) isIgnoredPat = picomatch(ignore, { dot: true });
+
+    function walk(dir: string): void {
+        let entries: fs.Dirent[];
+        try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+        catch { return; }
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const isDir = entry.isDirectory() || (entry.isSymbolicLink() && (() => { try { return fs.statSync(fullPath).isDirectory(); } catch { return false; } })());
+            if (isDir) {
+                if (isIgnoredDir(entry.name)) continue;
+                // Early prune: if include bases are set, skip dirs that can't match
+                if (includeBases && includeBases.length > 0) {
+                    const relDir = path.relative(repoPath, fullPath);
+                    const canMatch = includeBases.some(base =>
+                        relDir.startsWith(base) || base.startsWith(relDir),
+                    );
+                    if (!canMatch) continue;
+                }
+                walk(fullPath);
+            } else if (entry.isFile()) {
+                if (isIgnoredFile(entry.name)) continue;
+                const ext = path.extname(entry.name).toLowerCase();
+                const lang = SUPPORTED_EXTENSIONS[ext];
+                if (!lang) continue;
+
+                // Apply include/ignore filters using relative path
+                const rel = path.relative(repoPath, fullPath);
+                if (isIncluded && !isIncluded(rel)) continue;
+                if (isIgnoredPat && isIgnoredPat(rel)) continue;
+
+                byLanguage.set(lang, (byLanguage.get(lang) ?? 0) + 1);
+                total++;
+            }
+        }
+    }
+
+    walk(repoPath);
+
+    if (total === 0) {
+        return { name: 'code', available: false, summary: 'no supported source files found', icon: '📁', checked: false, disabled: 'nothing to index' };
+    }
+
+    const langCount = byLanguage.size;
+    const sorted = [...byLanguage.entries()].sort((a, b) => b[1] - a[1]);
+    const maxShow = 7;
+    const shown = sorted.slice(0, maxShow);
+    const remaining = sorted.length - maxShow;
+
+    const details: string[] = [];
+    for (let i = 0; i < shown.length; i++) {
+        const [lang, count] = shown[i];
+        const isLast = i === shown.length - 1 && remaining <= 0;
+        const prefix = isLast ? '└──' : '├──';
+        details.push(`${prefix} ${lang.padEnd(14)} ${count} files`);
+    }
+    if (remaining > 0) {
+        details.push(`└── ...and ${remaining} more`);
+    }
+
+    return {
+        name: 'code',
+        available: true,
+        summary: `${total} files (${langCount} language${langCount > 1 ? 's' : ''})`,
+        icon: '📁',
+        checked: true,
+        details,
+    };
+}
+
+/** Scan for git history. */
+function scanGitModule(repoPath: string): ScanModule {
+    const stats = scanGitStats(repoPath);
+
+    if (!stats) {
+        return { name: 'git', available: false, summary: 'no .git directory found', icon: '📜', checked: false, disabled: 'not a git repo' };
+    }
+
+    const details: string[] = [];
+    if (stats.lastMessage) {
+        details.push(`Last: ${stats.lastMessage} (${stats.lastDate})`);
+    }
+
+    return {
+        name: 'git',
+        available: true,
+        summary: `${stats.commitCount.toLocaleString()} commits`,
+        icon: '📜',
+        checked: true,
+        details,
+    };
+}
+
+/** Scan for document collections. */
+function scanDocsModule(repoPath: string): ScanModule {
+    const collections = scanDocsCollections(repoPath);
+
+    if (collections.length === 0) {
+        return { name: 'docs', available: false, summary: 'no documents found', icon: '📄', checked: false, disabled: 'no .md/.mdx files' };
+    }
+
+    const totalFiles = collections.reduce((s, d) => s + d.fileCount, 0);
+    const details = collections.map((d, i) => {
+        const isLast = i === collections.length - 1;
+        const prefix = isLast ? '└──' : '├──';
+        return `${prefix} ${d.name.padEnd(10)} → ${d.path} (${d.fileCount} files)`;
+    });
+
+    return {
+        name: 'docs',
+        available: true,
+        summary: `${collections.length} collection${collections.length > 1 ? 's' : ''} (${totalFiles} files)`,
+        icon: '📄',
+        checked: true,
+        details,
+    };
+}
+
+
+/** Get git stats for this repo. */
+function scanGitStats(repoPath: string): { commitCount: number; lastMessage: string; lastDate: string } | null {
+    if (!fs.existsSync(path.join(repoPath, '.git'))) return null;
+    return gitStats(repoPath);
+}
+
+/** Get git stats for a single directory. */
+function gitStats(dir: string): { commitCount: number; lastMessage: string; lastDate: string } | null {
+    try {
+        const count = parseInt(execSync('git rev-list --count HEAD', { cwd: dir, encoding: 'utf-8' }).trim(), 10);
+        const log = execSync('git log -1 --format="%s|%ar"', { cwd: dir, encoding: 'utf-8' }).trim();
+        const [lastMessage, lastDate] = log.split('|');
+        return { commitCount: count, lastMessage: lastMessage ?? '', lastDate: lastDate ?? '' };
+    } catch {
+        return null;
+    }
+}
+
+/** Scan for document collections (config + auto-detect). */
+function scanDocsCollections(repoPath: string): { name: string; path: string; fileCount: number }[] {
+    const results: { name: string; path: string; fileCount: number }[] = [];
+    const seen = new Set<string>();
+
+    // 1. Read explicit collections from config.json
+    const configPath = path.join(repoPath, '.brainbank', 'config.json');
+    try {
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
+            const docsCfg = config?.docs as Record<string, unknown> | undefined;
+            const collections = docsCfg?.collections as { name: string; path: string }[] | undefined;
+            if (collections) {
+                for (const coll of collections) {
+                    const absPath = path.resolve(repoPath, coll.path);
+                    results.push({ name: coll.name, path: coll.path, fileCount: countDocs(absPath) });
+                    seen.add(absPath);
+                }
+            }
+        }
+    } catch {}
+
+    // 2. Auto-detect .md/.mdx in the repo root and top-level dirs
+    const rootDocs = countDocsShallow(repoPath);
+    if (rootDocs > 0) {
+        results.push({ name: '(root)', path: '.', fileCount: rootDocs });
+    }
+
+    try {
+        for (const entry of fs.readdirSync(repoPath, { withFileTypes: true })) {
+            if (!entry.isDirectory()) continue;
+            if (isIgnoredDir(entry.name)) continue;
+            if (entry.name.startsWith('.')) continue;
+
+            const dirPath = path.join(repoPath, entry.name);
+            if (seen.has(dirPath)) continue;
+
+            const count = countDocs(dirPath);
+            if (count > 0) {
+                results.push({ name: entry.name, path: `./${entry.name}`, fileCount: count });
+            }
+        }
+    } catch {}
+
+    return results;
+}
+
+/** Count .md/.mdx files recursively in a directory. */
+function countDocs(dir: string): number {
+    let count = 0;
+    try {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const ePath = path.join(dir, e.name);
+            const isDir = e.isDirectory() || (e.isSymbolicLink() && (() => { try { return fs.statSync(ePath).isDirectory(); } catch { return false; } })());
+            if (isDir) {
+                if (isIgnoredDir(e.name)) continue;
+                count += countDocs(ePath);
+            } else if ((e.isFile() || e.isSymbolicLink()) && /\.mdx?$/i.test(e.name)) {
+                count++;
+            }
+        }
+    } catch {}
+    return count;
+}
+
+/** Count .md/.mdx files in a directory (non-recursive, root level only). */
+function countDocsShallow(dir: string): number {
+    let count = 0;
+    try {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (e.isFile() && /\.mdx?$/i.test(e.name)) count++;
+        }
+    } catch {}
+    return count;
+}
+
+/** Check if config.json exists and read key fields. */
+function scanConfig(repoPath: string): ScanResult['config'] {
+    const configPath = path.join(repoPath, '.brainbank', 'config.json');
+    if (!fs.existsSync(configPath)) return { exists: false };
+
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
+        const codeCfg = config?.code as Record<string, unknown> | undefined;
+
+        // Merge root-level and per-plugin include/ignore
+        const rootInclude = config?.include as string[] | undefined;
+        const rootIgnore = config?.ignore as string[] | undefined;
+        const pluginInclude = codeCfg?.include as string[] | undefined;
+        const pluginIgnore = codeCfg?.ignore as string[] | undefined;
+
+        const include = [...(rootInclude ?? []), ...(pluginInclude ?? [])];
+        const ignore = [...(rootIgnore ?? []), ...(pluginIgnore ?? [])];
+
+        return {
+            exists: true,
+            ignore: ignore.length > 0 ? ignore : undefined,
+            include: include.length > 0 ? include : undefined,
+            plugins: config?.plugins as string[] | undefined,
+        };
+    } catch {
+        return { exists: false };
+    }
+}
+
+/** Check DB existence and size. */
+function scanDb(repoPath: string): ScanResult['db'] {
+    const dbPath = path.join(repoPath, '.brainbank', 'data', 'brainbank.db');
+    if (!fs.existsSync(dbPath)) return { exists: false, sizeMB: 0 };
+
+    try {
+        const stat = fs.statSync(dbPath);
+        return {
+            exists: true,
+            sizeMB: Math.round(stat.size / 1024 / 1024 * 10) / 10,
+            lastModified: stat.mtime,
+        };
+    } catch {
+        return { exists: false, sizeMB: 0 };
+    }
+}
+