brainbank 0.7.0 → 0.8.0

package/src/cli/factory/builtin-registration.ts

@@ -0,0 +1,123 @@
+/**
+ * BrainBank CLI — Plugin Registration
+ *
+ * Generic plugin registration with multi-repo detection
+ * and per-plugin config resolution. No hardcoded plugin names.
+ */
+
+import type { BrainBank } from '@/brainbank.ts';
+import type { DocumentCollection } from '@/types.ts';
+import type { ProjectConfig } from './config-loader.ts';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { c } from '../utils.ts';
+import { loadPlugin, isMultiRepoCapable, resolveEmbeddingKey } from './plugin-loader.ts';
+
+/** Read a nested property from a generic config section. */
+function pluginCfg(config: ProjectConfig | null, pluginName: string): Record<string, unknown> {
+    const section = config?.[pluginName];
+    if (section && typeof section === 'object' && !Array.isArray(section)) {
+        return section as Record<string, unknown>;
+    }
+    return {};
+}
+
+/** Detect subdirectories that have their own .git repo. Respects optional `repos` whitelist. */
+function detectGitSubdirs(parentPath: string, repos?: string[]): { name: string; path: string }[] {
+    try {
+        const entries = fs.readdirSync(parentPath, { withFileTypes: true });
+        let subdirs = entries
+            .filter(e => {
+                if (e.name.startsWith('.') || e.name.startsWith('node_modules')) return false;
+                // Follow symlinks: isDirectory() is false for symlinks, so check via statSync
+                const isDir = e.isDirectory() || (e.isSymbolicLink() && fs.statSync(path.join(parentPath, e.name)).isDirectory());
+                return isDir && fs.existsSync(path.join(parentPath, e.name, '.git'));
+            })
+            .map(e => ({ name: e.name, path: path.join(parentPath, e.name) }));
+
+        if (repos && repos.length > 0) {
+            const allowed = new Set(repos);
+            subdirs = subdirs.filter(s => allowed.has(s.name));
+        }
+
+        return subdirs;
+    } catch { return []; }
+}
+
+/** Register plugins with multi-repo detection and per-plugin config. */
+export async function registerBuiltins(
+    brain: BrainBank, rp: string, pluginNames: string[],
+    config: ProjectConfig | null, ignorePatterns: string[] = [],
+): Promise<void> {
+    const resolvedRp = path.resolve(rp);
+    const hasRootGit = fs.existsSync(path.join(resolvedRp, '.git'));
+    const configRepos = config?.repos as string[] | undefined;
+    const gitSubdirs = !hasRootGit ? detectGitSubdirs(resolvedRp, configRepos) : [];
+
+    for (const name of pluginNames) {
+        const factory = await loadPlugin(name);
+        if (!factory) {
+            console.error(c.yellow(`  ⚠ @brainbank/${name} not installed — skipping ${name} indexing`));
+            console.error(c.dim(`    Install: npm i -g @brainbank/${name}`));
+            continue;
+        }
+
+        const cfg = pluginCfg(config, name);
+
+        // Resolve per-plugin embedding if configured
+        const embKey = cfg.embedding as string | undefined;
+        const embeddingProvider = embKey ? await resolveEmbeddingKey(embKey) : undefined;
+
+        // Multi-repo: create one plugin instance per git subdir
+        if (gitSubdirs.length > 0 && isMultiRepoCapable(name)) {
+            console.error(c.cyan(`  Multi-repo: found ${gitSubdirs.length} git repos: ${gitSubdirs.map(d => d.name).join(', ')}`));
+            for (const sub of gitSubdirs) {
+                const mergedIgnore = [...(cfg.ignore as string[] ?? []), ...ignorePatterns];
+                brain.use(factory({
+                    ...cfg,
+                    repoPath: sub.path,
+                    name: `${name}:${sub.name}`,
+                    embeddingProvider,
+                    ignore: mergedIgnore.length > 0 ? mergedIgnore : undefined,
+                }));
+            }
+        } else {
+            // Single repo: merge ignore patterns for plugins that support them
+            const configIgnore = cfg.ignore as string[] | undefined ?? [];
+            const mergedIgnore = [...configIgnore, ...ignorePatterns];
+
+            brain.use(factory({
+                ...cfg,
+                repoPath: rp,
+                embeddingProvider,
+                ignore: mergedIgnore.length > 0 ? mergedIgnore : undefined,
+            }));
+        }
+    }
+}
+
+/** Register doc collections from config. Call after brain.initialize(). */
+export async function registerConfigCollections(brain: BrainBank, rp: string, config: ProjectConfig | null): Promise<void> {
+    const docsCfg = pluginCfg(config, 'docs');
+    const collections = docsCfg.collections as DocumentCollection[] | undefined;
+    if (!collections?.length) return;
+
+    const { isDocsPlugin } = await import('@/plugin.ts');
+    const rawPlugin = brain.plugin('docs');
+    if (!rawPlugin || !isDocsPlugin(rawPlugin)) return;
+
+    const repoPath = path.resolve(rp);
+    for (const coll of collections) {
+        const absPath = path.resolve(repoPath, coll.path);
+        try {
+            await rawPlugin.addCollection({
+                name: coll.name, path: absPath,
+                pattern: coll.pattern ?? '**/*.md', ignore: coll.ignore, context: coll.context,
+            });
+        } catch (e: unknown) {
+            if (!(e instanceof Error && e.message.includes('already'))) throw e;
+            // Collection already registered — skip
+        }
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * BrainBank CLI — Config Loader
+ *
+ * Loads .brainbank/config.json (or .ts/.js/.mjs fallback).
+ * Config priority: CLI flags > config file > defaults.
+ */
+
+import type { Plugin } from '@/plugin.ts';
+import type { BrainBankConfig, DocumentCollection } from '@/types.ts';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { c } from '../utils.ts';
+
+/** Full .brainbank/config.json schema. */
+export interface ProjectConfig {
+    plugins?: string[];
+    embedding?: string;
+    reranker?: string;
+    pruner?: string;
+    maxFileSize?: number;
+    indexers?: Plugin[];
+    brainbank?: Partial<BrainBankConfig>;
+    /** Context field defaults (e.g. { lines: true, callTree: true, symbols: false }). */
+    context?: Record<string, unknown>;
+    /** Per-plugin config sections (e.g. code, git, docs). */
+    [pluginName: string]: unknown;
+}
+
+const CONFIG_NAMES = ['config.json', 'config.ts', 'config.js', 'config.mjs'];
+const NOT_LOADED = Symbol('not-loaded');
+let _configCache: ProjectConfig | null | typeof NOT_LOADED = NOT_LOADED;
+
+/** Load .brainbank/config.json (or .ts fallback) if present. */
+export async function loadConfig(repoPath: string): Promise<ProjectConfig | null> {
+    if (_configCache !== NOT_LOADED) return _configCache;
+
+    const brainbankDir = path.resolve(repoPath, '.brainbank');
+
+    for (const name of CONFIG_NAMES) {
+        const configPath = path.join(brainbankDir, name);
+        if (!fs.existsSync(configPath)) continue;
+
+        try {
+            if (name === 'config.json') {
+                const raw = fs.readFileSync(configPath, 'utf-8');
+                _configCache = JSON.parse(raw) as ProjectConfig;
+            } else {
+                const mod = await import(configPath);
+                _configCache = (mod.default ?? mod) as ProjectConfig;
+            }
+            return _configCache;
+        } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(c.red(`Error loading .brainbank/${name}: ${message}`));
+            process.exit(1);
+        }
+    }
+
+    _configCache = null;
+    return null;
+}
+
+/** Get the loaded config (for use by commands). */
+export async function getConfig(repoPath?: string): Promise<ProjectConfig | null> {
+    return loadConfig(repoPath ?? '.');
+}
+
+/** Reset config cache. Useful for tests. */
+export function resetConfigCache(): void {
+    _configCache = NOT_LOADED;
+}

package/src/cli/factory/index.ts

@@ -0,0 +1,65 @@
+/**
+ * BrainBank CLI — Brain Factory
+ *
+ * Creates a configured BrainBank instance with dynamically loaded plugins,
+ * auto-discovered indexers, and config file support.
+ * Delegates to focused modules in factory/.
+ */
+
+import type { Plugin } from '@/plugin.ts';
+import type { BrainBankConfig } from '@/types.ts';
+import type { BrainContext } from './brain-context.ts';
+
+import { BrainBank } from '@/brainbank.ts';
+import { contextFromCLI, ctxFlag, ctxEnv } from './brain-context.ts';
+import { registerBuiltins, registerConfigCollections } from './builtin-registration.ts';
+import { loadConfig, getConfig, resetConfigCache } from './config-loader.ts';
+import { discoverFolderPlugins, resetPluginCache, setupProviders } from './plugin-loader.ts';
+
+export type { ProjectConfig } from './config-loader.ts';
+export type { BrainContext } from './brain-context.ts';
+export { contextFromCLI } from './brain-context.ts';
+export { getConfig, registerConfigCollections };
+
+/** Reset factory caches. Useful for tests. */
+export function resetFactoryCache(): void {
+    resetConfigCache();
+    resetPluginCache();
+}
+
+/**
+ * Create a BrainBank with built-in + discovered + config plugins.
+ *
+ * Accepts either a `BrainContext` (for programmatic use) or an optional
+ * `repoPath` string (for CLI backward compat — builds context from argv).
+ */
+export async function createBrain(contextOrRepo?: BrainContext | string): Promise<BrainBank> {
+    const ctx: BrainContext = typeof contextOrRepo === 'string'
+        ? contextFromCLI(contextOrRepo)
+        : contextOrRepo ?? contextFromCLI();
+
+    const rp = ctx.repoPath;
+    const config = await loadConfig(rp);
+    const folderPlugins = await discoverFolderPlugins(rp);
+
+    const brainOpts: Partial<BrainBankConfig> & Record<string, unknown> = { repoPath: rp, ...(config?.brainbank ?? {}) };
+    if (config?.maxFileSize) brainOpts.maxFileSize = config.maxFileSize as number;
+    await setupProviders(brainOpts, config, ctx.flags, ctx.env);
+
+    const brain = new BrainBank(brainOpts);
+    const builtins = config?.plugins ?? ['code', 'git', 'docs'];
+
+    // Merge ignore patterns from context flags
+    const ignoreFlag = ctxFlag(ctx, 'ignore');
+    const ignorePatterns = ignoreFlag ? ignoreFlag.split(',').map(s => s.trim()) : [];
+
+    await registerBuiltins(brain, rp, builtins, config, ignorePatterns);
+
+    for (const plugin of folderPlugins) brain.use(plugin);
+
+    if (config?.indexers) {
+        for (const plugin of config.indexers as Plugin[]) brain.use(plugin);
+    }
+
+    return brain;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * BrainBank CLI — Plugin Loader
+ *
+ * Generic plugin loader registry with dynamic @brainbank/* package loading
+ * and auto-discovery of user plugins from .brainbank/plugins/.
+ */
+
+import type { Plugin } from '@/plugin.ts';
+import type { EmbeddingProvider } from '@/types.ts';
+import type { ProjectConfig } from './config-loader.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; } }],
+]);
+
+/** Plugins that support multi-repo mode (one instance per git subdir). */
+const MULTI_REPO_PLUGINS = new Set(['code', 'git']);
+
+/** Load a plugin factory by name. Returns null if not installed. */
+export async function loadPlugin(name: string): Promise<PluginFactory | null> {
+    const loader = PLUGIN_LOADERS.get(name);
+    if (!loader) return null;
+    return loader();
+}
+
+/** Register a custom plugin loader. */
+export function registerPluginLoader(name: string, loader: PluginLoaderFn): void {
+    PLUGIN_LOADERS.set(name, loader);
+}
+
+/** Check if a plugin supports multi-repo mode. */
+export function isMultiRepoCapable(name: string): boolean {
+    return MULTI_REPO_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;
+}
+
+/** 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 reranker 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> {
+    const rerankerFlag = flags?.reranker ?? (config?.reranker as string | undefined);
+    if (rerankerFlag === 'qwen3') {
+        const { Qwen3Reranker } = await import('@/providers/rerankers/qwen3-reranker.ts');
+        brainOpts.reranker = new Qwen3Reranker();
+    }
+
+    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();
+    }
+
+    // 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();
+        } 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,63 @@
+#!/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 { cmdDaemon } from './commands/daemon.ts';
+import { cmdStatus } from './commands/status.ts';
+import { showHelp } from './commands/help.ts';
+
+const command = args[0];
+
+async function main(): Promise<void> {
+    switch (command) {
+        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 '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,135 @@
+/**
+ * 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 * as http from 'node:http';
+
+import { isServerRunning } from '@/services/daemon.ts';
+
+interface ContextOptions {
+    task: string;
+    repo?: string;
+    sources?: Record<string, number>;
+    pathPrefix?: 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;
+    }
+}
+
+/**
+ * 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();
+    });
+}