brainbank 0.1.0-beta.1

package/src/cli/factory/plugin-loader.ts

@@ -0,0 +1,325 @@
+/**
+ * BrainBank CLI — Plugin Loader
+ *
+ * Generic plugin loader registry with dynamic @brainbank/* package loading,
+ * npm package fallback for third-party plugins, and auto-discovery of
+ * user plugins from .brainbank/plugins/.
+ */
+
+import type { Plugin, PluginScanInfo, PluginPreviewLine } from '@/plugin.ts';
+import type { EmbeddingProvider } from '@/types.ts';
+import type { ProjectConfig } from './config-loader.ts';
+import type { ScanModule } from '@/cli/commands/scan.ts';
+import type { PreviewLine } from '@/cli/tui/tree-scanner.ts';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { c } from '../utils.ts';
+
+/** Plugin factory — accepts config, returns Plugin. */
+type PluginFactory = (opts: Record<string, unknown>) => Plugin;
+
+/** Loader function: dynamically imports a package and returns its factory. */
+type PluginLoaderFn = () => Promise<PluginFactory | null>;
+
+/** Built-in plugin loader registry. Extensible at runtime. */
+const PLUGIN_LOADERS = new Map<string, PluginLoaderFn>([
+    ['code', async () => { try { return (await import('@brainbank/code')).code as PluginFactory; } catch { return null; } }],
+    ['git', async () => { try { return (await import('@brainbank/git')).git as PluginFactory; } catch { return null; } }],
+    ['docs', async () => { try { return (await import('@brainbank/docs')).docs as PluginFactory; } catch { return null; } }],
+]);
+
+/** Built-in plugin names — used to skip npm fallback. */
+const BUILTIN_PLUGINS = new Set(['code', 'git', 'docs']);
+
+
+
+/**
+ * Load a plugin factory by name.
+ * 1. Check the built-in loader registry.
+ * 2. Fallback: try `import(name)` for npm packages (third-party plugins).
+ * Returns null if not installed.
+ */
+export async function loadPlugin(name: string): Promise<PluginFactory | null> {
+    // Built-in loader
+    const loader = PLUGIN_LOADERS.get(name);
+    if (loader) return loader();
+
+    // npm package fallback — try importing the package directly
+    try {
+        const mod = await import(name) as Record<string, unknown>;
+        // Convention: export default factory, or named export matching short name
+        // e.g. 'brainbank-csv' exports `csv()`, '@myorg/brainbank-csv' exports `csv()`
+        const shortName = name.replace(/^@[^/]+\//, '').replace(/^brainbank-/, '');
+        const factory = mod.default ?? mod[shortName];
+        if (typeof factory === 'function') return factory as PluginFactory;
+
+        // Fallback: check all exports for a function that returns a Plugin-like object
+        for (const val of Object.values(mod)) {
+            if (typeof val === 'function') return val as PluginFactory;
+        }
+    } catch {
+        // Not installed — will be reported by registerBuiltins
+    }
+
+    return null;
+}
+
+/** Register a custom plugin loader. */
+export function registerPluginLoader(name: string, loader: PluginLoaderFn): void {
+    PLUGIN_LOADERS.set(name, loader);
+}
+
+
+
+/** Check if a plugin name is a built-in. */
+export function isBuiltinPlugin(name: string): boolean {
+    return BUILTIN_PLUGINS.has(name);
+}
+
+const INDEXER_EXTENSIONS = ['.ts', '.js', '.mjs'];
+const NOT_LOADED = Symbol('not-loaded');
+let _folderPluginsCache: Plugin[] | typeof NOT_LOADED = NOT_LOADED;
+
+/** Auto-discover plugins from .brainbank/plugins/ folder. */
+export async function discoverFolderPlugins(repoPath: string): Promise<Plugin[]> {
+    if (_folderPluginsCache !== NOT_LOADED) return _folderPluginsCache;
+
+    const pluginsDir = path.resolve(repoPath, '.brainbank', 'plugins');
+
+    if (!fs.existsSync(pluginsDir)) {
+        _folderPluginsCache = [];
+        return [];
+    }
+
+    const files = fs.readdirSync(pluginsDir)
+        .filter(f => INDEXER_EXTENSIONS.some(ext => f.endsWith(ext)))
+        .sort();
+
+    const plugins: Plugin[] = [];
+
+    for (const file of files) {
+        const filePath = path.join(pluginsDir, file);
+        try {
+            const mod = await import(filePath);
+            const plugin = mod.default ?? mod;
+
+            if (plugin && typeof plugin === 'object' && plugin.name) {
+                plugins.push(plugin as Plugin);
+            } else {
+                console.error(c.yellow(`⚠ ${file}: must export a default Plugin with a 'name' property, skipping`));
+            }
+        } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(c.red(`Error loading plugin ${file}: ${message}`));
+        }
+    }
+
+    _folderPluginsCache = plugins;
+    return plugins;
+}
+
+/** Reset folder plugins cache. Useful for tests. */
+export function resetPluginCache(): void {
+    _folderPluginsCache = NOT_LOADED;
+}
+
+
+// ── External Plugin Discovery (TUI integration) ──────────────────
+
+/** Result of discovering external (non-built-in) plugins. */
+export interface ExternalPluginDiscovery {
+    /** ScanModule entries to merge into the TUI sidebar. */
+    modules: ScanModule[];
+    /** Preview lines keyed by plugin name, for the TUI explorer panel. */
+    previews: Map<string, PreviewLine[]>;
+}
+
+/**
+ * Discover external plugins from config and produce scan/preview data for the TUI.
+ *
+ * For each non-built-in plugin in the list:
+ *   1. Try `import(name)` to load the package.
+ *   2. If it exports `scan(repoPath)`, use it for the sidebar.
+ *   3. If it exports `preview(repoPath)`, use it for the explorer panel.
+ *   4. If not installed, show as unavailable with install hint.
+ *
+ * Also scans `.brainbank/plugins/` folder plugins for scan/preview exports.
+ */
+export async function discoverExternalPlugins(
+    repoPath: string,
+    pluginNames: string[],
+): Promise<ExternalPluginDiscovery> {
+    const modules: ScanModule[] = [];
+    const previews = new Map<string, PreviewLine[]>();
+    const resolvedRp = path.resolve(repoPath);
+
+    // 1. Discover npm plugins listed in config
+    for (const name of pluginNames) {
+        if (BUILTIN_PLUGINS.has(name)) continue;
+
+        try {
+            const mod = await import(name) as Record<string, unknown>;
+
+            // scan() → ScanModule for sidebar
+            if (typeof mod.scan === 'function') {
+                const info = mod.scan(resolvedRp) as PluginScanInfo;
+                modules.push(scanInfoToModule(info));
+            } else {
+                // No scan export — generic entry
+                modules.push({
+                    name,
+                    available: true,
+                    checked: true,
+                    icon: '🔌',
+                    summary: `${name} plugin`,
+                });
+            }
+
+            // preview() → PreviewLine[] for explorer
+            if (typeof mod.preview === 'function') {
+                const lines = mod.preview(resolvedRp) as PluginPreviewLine[];
+                previews.set(name, lines.map(previewLineToInternal));
+            }
+        } catch {
+            // Package not installed
+            modules.push({
+                name,
+                available: false,
+                checked: false,
+                icon: '🔌',
+                summary: 'not installed',
+                disabled: `npm i ${name}`,
+            });
+        }
+    }
+
+    // 2. Discover folder plugins that export scan/preview
+    const pluginsDir = path.resolve(repoPath, '.brainbank', 'plugins');
+    if (fs.existsSync(pluginsDir)) {
+        const files = fs.readdirSync(pluginsDir)
+            .filter(f => INDEXER_EXTENSIONS.some(ext => f.endsWith(ext)))
+            .sort();
+
+        for (const file of files) {
+            const filePath = path.join(pluginsDir, file);
+            try {
+                const mod = await import(filePath) as Record<string, unknown>;
+                const plugin = mod.default ?? mod;
+                const pluginName = (plugin && typeof plugin === 'object' && 'name' in plugin)
+                    ? (plugin as { name: string }).name
+                    : file.replace(/\.[^.]+$/, '');
+
+                // Skip if already added from config
+                if (modules.some(m => m.name === pluginName)) continue;
+
+                if (typeof mod.scan === 'function') {
+                    const info = mod.scan(resolvedRp) as PluginScanInfo;
+                    modules.push(scanInfoToModule(info));
+                } else {
+                    modules.push({
+                        name: pluginName,
+                        available: true,
+                        checked: true,
+                        icon: '🔌',
+                        summary: `local plugin (${file})`,
+                    });
+                }
+
+                if (typeof mod.preview === 'function') {
+                    const lines = mod.preview(resolvedRp) as PluginPreviewLine[];
+                    previews.set(pluginName, lines.map(previewLineToInternal));
+                }
+            } catch {
+                // Failed to load folder plugin — skip for discovery
+            }
+        }
+    }
+
+    return { modules, previews };
+}
+
+/** Convert PluginScanInfo (public type) to ScanModule (internal type). */
+function scanInfoToModule(info: PluginScanInfo): ScanModule {
+    return {
+        name: info.name,
+        available: info.available,
+        summary: info.summary,
+        icon: info.icon,
+        checked: info.checked,
+        disabled: info.disabled,
+        details: info.details,
+    };
+}
+
+/** Convert PluginPreviewLine (public type) to PreviewLine (internal type). */
+function previewLineToInternal(line: PluginPreviewLine): PreviewLine {
+    return {
+        text: line.text,
+        color: line.color,
+        bold: line.bold,
+        dim: line.dim,
+    };
+}
+
+
+// ── Provider Setup ───────────────────────────────────────────────
+
+/** Resolve an embedding key string to an EmbeddingProvider instance. */
+export async function resolveEmbeddingKey(key: string): Promise<EmbeddingProvider> {
+    const { resolveEmbedding } = await import('@/providers/embeddings/resolve.ts');
+    return resolveEmbedding(key);
+}
+
+/** Configure pruner, expander, and global embedding provider on brainOpts. */
+export async function setupProviders(
+    brainOpts: Record<string, unknown>,
+    config: ProjectConfig | null,
+    flags?: Record<string, string | undefined>,
+    env?: Record<string, string | undefined>,
+): Promise<void> {
+    // Resolve API keys: config.keys > env vars
+    const keys = config?.keys ?? {};
+    const anthropicKey = keys.anthropic || process.env.ANTHROPIC_API_KEY;
+    const perplexityKey = keys.perplexity || process.env.PERPLEXITY_API_KEY;
+    const openaiKey = keys.openai || process.env.OPENAI_API_KEY;
+
+    // Inject resolved keys into process.env so downstream providers auto-detect them
+    if (anthropicKey) process.env.ANTHROPIC_API_KEY = anthropicKey;
+    if (perplexityKey) process.env.PERPLEXITY_API_KEY = perplexityKey;
+    if (openaiKey) process.env.OPENAI_API_KEY = openaiKey;
+
+
+
+    const prunerFlag = flags?.pruner ?? (config?.pruner as string | undefined);
+    if (prunerFlag === 'haiku') {
+        const { HaikuPruner } = await import('@/providers/pruners/haiku-pruner.ts');
+        brainOpts.pruner = new HaikuPruner({ apiKey: anthropicKey });
+    }
+
+    // Expander: explicit opt-in only (config.json `expander: "haiku"` or --expander flag)
+    const expanderFlag = flags?.expander ?? (config?.expander as string | undefined);
+    if (expanderFlag === 'haiku') {
+        try {
+            const { HaikuExpander } = await import('@/providers/pruners/haiku-expander.ts');
+            brainOpts.expander = new HaikuExpander({ apiKey: anthropicKey });
+        } catch {
+            // Fail-open: if API key missing, skip expander silently
+        }
+    }
+
+    const embFlag = flags?.embedding
+        ?? (config?.embedding as string | undefined)
+        ?? env?.BRAINBANK_EMBEDDING
+        ?? process.env.BRAINBANK_EMBEDDING;
+    if (embFlag) {
+        const provider = await resolveEmbeddingKey(embFlag);
+        brainOpts.embeddingProvider = provider;
+        brainOpts.embeddingDims = provider.dims;
+    }
+
+    // Context field defaults from config.json "context" section
+    if (config?.context) {
+        brainOpts.contextFields = config.context;
+    }
+}

package/src/cli/index.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+
+/**
+ * BrainBank — CLI Entry Point
+ *
+ * Dispatcher that routes commands to their handler modules.
+ */
+
+import { args, c } from './utils.ts';
+import { cmdIndex } from './commands/index.ts';
+import { cmdCollection } from './commands/collection.ts';
+import { cmdKv } from './commands/kv.ts';
+import { cmdDocs, cmdDocSearch } from './commands/docs.ts';
+import { cmdSearch, cmdHybridSearch, cmdKeywordSearch } from './commands/search.ts';
+import { cmdContext } from './commands/context.ts';
+import { cmdFiles } from './commands/files.ts';
+import { cmdStats } from './commands/stats.ts';
+import { cmdReembed } from './commands/reembed.ts';
+import { cmdWatch } from './commands/watch.ts';
+import { cmdMcp } from './commands/mcp.ts';
+import { cmdMcpExport } from './commands/mcp-export.ts';
+import { cmdDaemon } from './commands/daemon.ts';
+import { cmdStatus } from './commands/status.ts';
+import { showHelp } from './commands/help.ts';
+import { VERSION } from '@/constants.ts';
+
+const command = args[0];
+
+async function main(): Promise<void> {
+    switch (command) {
+        case '--version':
+        case '-v':
+            console.log(`brainbank v${VERSION}`);
+            break;
+        case 'i':
+        case 'index':       return cmdIndex();
+        case 'collection':  return cmdCollection();
+        case 'kv':          return cmdKv();
+        case 'docs':        return cmdDocs();
+        case 'dsearch':     return cmdDocSearch();
+        case 'search':      return cmdSearch();
+        case 'hsearch':     return cmdHybridSearch();
+        case 'ksearch':     return cmdKeywordSearch();
+        case 'context':     return cmdContext();
+        case 'files':       return cmdFiles();
+        case 'stats':       return cmdStats();
+        case 'reembed':     return cmdReembed();
+        case 'watch':       return cmdWatch();
+        case 'mcp':         return cmdMcp();
+        case 'mcp:export':  return cmdMcpExport();
+        case 'serve':        return cmdMcp(); // backward compat
+        case 'daemon':      return cmdDaemon();
+        case 'status':      return cmdStatus();
+        case 'help':
+        case '--help':
+        case '-h':
+            showHelp();
+            break;
+        default:
+            if (command) console.log(c.red(`Unknown command: ${command}\n`));
+            showHelp();
+            process.exit(command ? 1 : 0);
+    }
+}
+
+main().catch(err => {
+    console.error(c.red(`Error: ${err.message}`));
+    if (process.env.BRAINBANK_DEBUG) console.error(err.stack);
+    process.exit(1);
+});

package/src/cli/server-client.ts

@@ -0,0 +1,178 @@
+/**
+ * ServerClient — Lightweight HTTP client for the BrainBank daemon.
+ *
+ * Used by CLI commands to delegate to a running HTTP server
+ * instead of loading models locally. Falls back gracefully
+ * (returns null) if the server is unreachable.
+ */
+
+import type { SearchResult } from '@/types.ts';
+
+import * as http from 'node:http';
+
+import { isServerRunning } from '@/services/daemon.ts';
+
+interface ContextOptions {
+    task: string;
+    repo?: string;
+    sources?: Record<string, number>;
+    pathPrefix?: string | string[];
+    affectedFiles?: string[];
+}
+
+/**
+ * Try to get context from the running HTTP server.
+ * Returns the context string if successful, null if server is unreachable.
+ */
+export async function tryServerContext(options: ContextOptions): Promise<string | null> {
+    const info = isServerRunning();
+    if (!info) return null;
+
+    try {
+        const body = JSON.stringify({
+            task: options.task,
+            repo: options.repo,
+            sources: options.sources,
+            pathPrefix: options.pathPrefix,
+            affectedFiles: options.affectedFiles,
+        });
+
+        const response = await httpPost(info.port, '/context', body);
+        const data = JSON.parse(response) as { context?: string; error?: string };
+
+        if (data.error) return null;
+        return data.context ?? null;
+    } catch {
+        // Server unreachable or error — fall back to local
+        return null;
+    }
+}
+
+interface SearchDelegateOptions {
+    query: string;
+    repo?: string;
+    sources?: Record<string, number>;
+    pathPrefix?: string | string[];
+    maxResults?: number;
+}
+
+/**
+ * Try to delegate a search to the running HTTP server.
+ * Mode: 'search' (vector), 'hybrid' (hsearch), 'keyword' (ksearch).
+ * Returns SearchResult[] if successful, null if server is unreachable.
+ */
+export async function tryServerSearch(
+    mode: 'search' | 'hybrid' | 'keyword',
+    options: SearchDelegateOptions,
+): Promise<SearchResult[] | null> {
+    const info = isServerRunning();
+    if (!info) return null;
+
+    const endpoint = mode === 'search' ? '/search' : mode === 'hybrid' ? '/hsearch' : '/ksearch';
+
+    try {
+        const body = JSON.stringify({
+            query: options.query,
+            repo: options.repo,
+            sources: options.sources,
+            pathPrefix: options.pathPrefix,
+            maxResults: options.maxResults,
+        });
+
+        const response = await httpPost(info.port, endpoint, body);
+        const data = JSON.parse(response) as { results?: SearchResult[]; error?: string };
+
+        if (data.error) return null;
+        return data.results ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Try to trigger indexing on the running HTTP server.
+ * Returns the result if successful, null if server is unreachable.
+ */
+export async function tryServerIndex(repo?: string, forceReindex?: boolean): Promise<Record<string, unknown> | null> {
+    const info = isServerRunning();
+    if (!info) return null;
+
+    try {
+        const body = JSON.stringify({ repo, forceReindex });
+        const response = await httpPost(info.port, '/index', body);
+        const data = JSON.parse(response) as { result?: Record<string, unknown>; error?: string };
+
+        if (data.error) return null;
+        return data.result ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Check server health. Returns health info or null.
+ */
+export async function serverHealth(): Promise<{
+    ok: boolean;
+    pid: number;
+    port: number;
+    uptime: number;
+    workspaces: number;
+} | null> {
+    const info = isServerRunning();
+    if (!info) return null;
+
+    try {
+        const response = await httpGet(info.port, '/health');
+        return JSON.parse(response) as { ok: boolean; pid: number; port: number; uptime: number; workspaces: number };
+    } catch {
+        return null;
+    }
+}
+
+// ── HTTP helpers ────────────────────────────────────
+
+function httpPost(port: number, path: string, body: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const req = http.request({
+            hostname: '127.0.0.1',
+            port,
+            path,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+            },
+            timeout: 120_000, // 2 minutes — context queries can be slow on first load
+        }, (res) => {
+            const chunks: Buffer[] = [];
+            res.on('data', (chunk: Buffer) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+        req.write(body);
+        req.end();
+    });
+}
+
+function httpGet(port: number, path: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const req = http.request({
+            hostname: '127.0.0.1',
+            port,
+            path,
+            method: 'GET',
+            timeout: 5_000,
+        }, (res) => {
+            const chunks: Buffer[] = [];
+            res.on('data', (chunk: Buffer) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+        req.end();
+    });
+}