brainbank 0.1.0-beta.1

package/src/cli/utils.ts

@@ -0,0 +1,137 @@
+/**
+ * BrainBank CLI — Shared Utilities
+ *
+ * Colors, argument parsing, result formatting, and plugin discovery.
+ */
+
+import type { BrainBank } from '@/brainbank.ts';
+import type { DocsPlugin } from '@/plugin.ts';
+import type { SearchResult } from '@/types.ts';
+
+import { isDocsPlugin } from '@/plugin.ts';
+
+export const c = {
+    green:   (s: string) => `\x1b[32m${s}\x1b[0m`,
+    red:     (s: string) => `\x1b[31m${s}\x1b[0m`,
+    yellow:  (s: string) => `\x1b[33m${s}\x1b[0m`,
+    cyan:    (s: string) => `\x1b[36m${s}\x1b[0m`,
+    dim:     (s: string) => `\x1b[2m${s}\x1b[0m`,
+    bold:    (s: string) => `\x1b[1m${s}\x1b[0m`,
+    magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
+
+/** Raw argv, sliced past the Node binary and script path. */
+export const args = process.argv.slice(2);
+
+export function getFlag(name: string): string | undefined {
+    const idx = args.indexOf(`--${name}`);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+
+/** Collect all values for a repeated flag (--ignore a --ignore b) or comma-separated (--ignore a,b). */
+export function getFlagAll(name: string): string[] {
+    const values: string[] = [];
+    const flag = `--${name}`;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === flag && args[i + 1] && !args[i + 1].startsWith('--')) {
+            for (const v of args[i + 1].split(',')) {
+                const trimmed = v.trim();
+                if (trimmed) values.push(trimmed);
+            }
+            i++;
+        }
+    }
+    return values;
+}
+
+export function hasFlag(name: string): boolean {
+    return args.includes(`--${name}`);
+}
+
+/** Known flags that take a value (--flag <value>). */
+const VALUE_FLAGS = new Set([
+    'repo', 'depth', 'collection', 'pattern', 'context', 'name',
+    'keep', 'pruner', 'only', 'docs', 'path',
+    'ignore', 'include', 'meta', 'k', 'mode', 'limit',
+]);
+
+/**
+ * Strip all --flags AND their values from an argv slice.
+ * Returns only positional arguments.
+ *
+ * Handles:
+ *   - Known VALUE_FLAGS: --repo /path → skip both
+ *   - Dynamic source flags: --code 10 → skip both (any --name <number>)
+ *   - Boolean flags: --force, --yes → skip flag only
+ *
+ *   stripFlags(['ksearch', 'auth', '--repo', '/path', '--code', '10'])
+ *   → ['ksearch', 'auth']
+ */
+export function stripFlags(argv: string[]): string[] {
+    const result: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--')) {
+            const name = argv[i].slice(2);
+            const next = argv[i + 1];
+            // Known value flag or dynamic numeric value → skip both
+            if (next !== undefined && !next.startsWith('--')) {
+                if (VALUE_FLAGS.has(name) || /^\d+$/.test(next)) {
+                    i++; // skip the value
+                }
+            }
+            continue;
+        }
+        result.push(argv[i]);
+    }
+    return result;
+}
+
+
+export function printResults(results: SearchResult[], minScore = 0.70): void {
+    const filtered = results.filter(r => r.score >= minScore).slice(0, 20);
+
+    if (filtered.length === 0) {
+        console.log(c.yellow(`  No results above ${Math.round(minScore * 100)}% score.`));
+        return;
+    }
+
+    for (const r of filtered) {
+        const score = Math.round(r.score * 100);
+
+        if (r.type === 'code') {
+            const m = r.metadata;
+            console.log(
+                `${c.green(`[CODE ${score}%]`)} ${c.bold(r.filePath!)} — ` +
+                `${m.name || m.chunkType} ${c.dim(`L${m.startLine}-${m.endLine}`)}`,
+            );
+            console.log(c.dim(r.content.split('\n').slice(0, 5).join('\n')));
+            console.log('');
+        } else if (r.type === 'commit') {
+            const m = r.metadata;
+            console.log(
+                `${c.cyan(`[COMMIT ${score}%]`)} ${c.bold(m.shortHash)} ` +
+                `${r.content} ${c.dim(`(${m.author})`)}`,
+            );
+            if (m.files?.length) console.log(c.dim(`  Files: ${m.files.slice(0, 4).join(', ')}`));
+            console.log('');
+        } else if (r.type === 'document') {
+            const ctx = r.context ? ` — ${c.dim(r.context)}` : '';
+            console.log(
+                `${c.magenta(`[DOC ${score}%]`)} ${c.bold(r.filePath!)} ` +
+                `[${r.metadata.collection}]${ctx}`,
+            );
+            console.log(c.dim(r.content.split('\n').slice(0, 4).join('\n')));
+            console.log('');
+        }
+    }
+}
+
+/** Discover the first plugin that implements DocsPlugin by capability. */
+export function findDocsPlugin(brain: BrainBank): DocsPlugin | undefined {
+    for (const name of brain.plugins) {
+        const p = brain.plugin(name);
+        if (p && isDocsPlugin(p)) return p;
+    }
+    return undefined;
+}

package/src/config.ts

@@ -0,0 +1,49 @@
+import type { BrainBankConfig, ResolvedConfig } from './types.ts';
+
+import * as path from 'node:path';
+
+
+export const DEFAULTS: ResolvedConfig = {
+    repoPath: '.',
+    dbPath: '.brainbank/data/brainbank.db',
+    gitDepth: 500,
+    maxFileSize: 512_000,      // 500KB
+    maxDiffBytes: 8192,
+    hnswM: 16,
+    hnswEfConstruction: 200,
+    hnswEfSearch: 50,
+    embeddingDims: 384,
+    maxElements: 2_000_000,
+};
+
+
+/**
+ * Merge partial config with defaults.
+ * All fields become required.
+ * Relative dbPath is resolved against repoPath.
+ */
+export function resolveConfig(partial: BrainBankConfig = {}): ResolvedConfig {
+    const repoPath = path.resolve(partial.repoPath ?? DEFAULTS.repoPath);
+    const rawDbPath = partial.dbPath ?? DEFAULTS.dbPath;
+    // Resolve relative dbPath against repoPath so DB lives alongside the repo
+    const dbPath = path.isAbsolute(rawDbPath) ? rawDbPath : path.join(repoPath, rawDbPath);
+
+    return {
+        repoPath,
+        dbPath,
+        gitDepth:          partial.gitDepth          ?? DEFAULTS.gitDepth,
+        maxFileSize:       partial.maxFileSize       ?? DEFAULTS.maxFileSize,
+        maxDiffBytes:      partial.maxDiffBytes      ?? DEFAULTS.maxDiffBytes,
+        hnswM:             partial.hnswM             ?? DEFAULTS.hnswM,
+        hnswEfConstruction: partial.hnswEfConstruction ?? DEFAULTS.hnswEfConstruction,
+        hnswEfSearch:      partial.hnswEfSearch      ?? DEFAULTS.hnswEfSearch,
+        embeddingDims:     partial.embeddingDims     ?? DEFAULTS.embeddingDims,
+        maxElements:       partial.maxElements       ?? DEFAULTS.maxElements,
+        embeddingProvider: partial.embeddingProvider,
+        pruner: partial.pruner,
+        expander: partial.expander,
+        webhookPort: partial.webhookPort,
+        contextFields: partial.contextFields,
+    };
+}
+

package/src/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * BrainBank — Constants
+ *
+ * Core-only constants. Plugin names are NOT defined here — they belong
+ * to their respective packages. Only keys owned by the core live here.
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json') as { version: string };
+
+/** Package version from package.json. */
+export const VERSION: string = pkg.version;
+
+/** HNSW index key for KV collections (core-owned). */
+export const HNSW = {
+    KV: 'kv',
+} as const;
+
+export type HnswKey = typeof HNSW[keyof typeof HNSW];

package/src/db/adapter.ts

@@ -0,0 +1,112 @@
+/**
+ * BrainBank — Database Adapter Interface
+ *
+ * Abstract contract for database operations. All consumers depend on
+ * this interface — never on a concrete driver. The `SQLiteAdapter`
+ * is the built-in implementation; future adapters (LibSQL, Turso,
+ * PostgreSQL) implement the same contract.
+ *
+ * Phase 1: sync-first API matching the existing synchronous SQLite usage.
+ * Async variants will be added when needed by async-native adapters.
+ */
+
+
+/** Result from mutating queries (INSERT / UPDATE / DELETE). */
+export interface ExecuteResult {
+    /** Row ID of the last inserted row. */
+    lastInsertRowid: number | bigint;
+    /** Number of rows changed by the statement. */
+    changes: number;
+}
+
+/** A prepared statement with typed query methods. */
+export interface PreparedStatement<T = unknown> {
+    /** Execute a query and return the first matching row, or `undefined`. */
+    get(...params: unknown[]): T | undefined;
+    /** Execute a query and return all matching rows. */
+    all(...params: unknown[]): T[];
+    /** Execute a mutating statement and return the result. */
+    run(...params: unknown[]): ExecuteResult;
+    /** Iterate over matching rows without loading them all into memory. */
+    iterate(...params: unknown[]): IterableIterator<T>;
+}
+
+/** Adapter capability flags — describes what the underlying engine supports. */
+export interface AdapterCapabilities {
+    /** Full-text search engine. */
+    fts: 'fts5' | 'tsvector' | 'none';
+    /** Upsert syntax dialect. */
+    upsert: 'or-replace' | 'on-conflict';
+    /** Native JSON column support. */
+    json: boolean;
+    /** Native vector column support (e.g. pgvector). */
+    vectors: boolean;
+}
+
+/**
+ * Database adapter interface.
+ *
+ * All BrainBank components depend on this contract instead of a
+ * concrete database driver. Keeps the door open for LibSQL, Turso,
+ * PostgreSQL, etc. without touching consumer code.
+ */
+export interface DatabaseAdapter {
+    /** Prepare a reusable statement. */
+    prepare<T = unknown>(sql: string): PreparedStatement<T>;
+
+    /** Execute raw DDL / multi-statement SQL (no results). */
+    exec(sql: string): void;
+
+    /** Run `fn` inside a transaction. Auto-commits on success, auto-rollbacks on error. */
+    transaction<T>(fn: () => T): T;
+
+    /** Run a prepared statement on multiple rows inside a single transaction. */
+    batch<T extends unknown[]>(sql: string, rows: T[]): void;
+
+    /** Close the database and release resources. */
+    close(): void;
+
+    /** Engine capabilities (FTS, upsert dialect, etc.). */
+    readonly capabilities: AdapterCapabilities;
+
+    /**
+     * Escape hatch: access the underlying raw driver.
+     * Returns `undefined` for adapters that don't support raw access.
+     *
+     * @deprecated Use `DatabaseAdapter` methods instead. This exists
+     * only for gradual migration of plugins that depend on driver internals.
+     */
+    raw<T = unknown>(): T | undefined;
+}
+
+// ── Row Types ────────────────────────────────────────────────────────
+// Typed interfaces for rows returned by core SQLite queries.
+// Domain-specific row types live in their respective packages.
+
+export interface KvDataRow {
+    id: number;
+    collection: string;
+    content: string;
+    meta_json: string;
+    tags_json: string;
+    expires_at: number | null;
+    created_at: number;
+}
+
+export interface KvVectorRow {
+    data_id: number;
+    embedding: Uint8Array;
+}
+
+export interface EmbeddingMetaRow {
+    value: string;
+}
+
+export interface VectorRow {
+    id: number;
+    embedding: Uint8Array;
+}
+
+export interface CountRow {
+    c: number;
+}

package/src/db/metadata.ts

@@ -0,0 +1,130 @@
+/**
+ * BrainBank — Database Metadata
+ *
+ * Helpers for reading/writing metadata stored in core SQLite tables:
+ *
+ * - **Index State** — cross-process HNSW version tracking.
+ *   Processes compare in-memory versions with DB to detect staleness
+ *   and trigger hot-reload via `ensureFresh()`.
+ *
+ * - **Embedding Meta** — tracks which embedding provider is stored in
+ *   the database. Detects dimension mismatches at startup and updates
+ *   metadata after `reembed()`.
+ */
+
+import type { EmbeddingProvider } from '@/types.ts';
+import type { DatabaseAdapter, EmbeddingMetaRow } from './adapter.ts';
+
+import { providerKey } from '@/lib/provider-key.ts';
+
+
+// ── Index State ─────────────────────────────────────────────────────
+
+/** Row shape returned from index_state queries. */
+interface IndexStateRow {
+    name: string;
+    version: number;
+    writer_pid: number;
+    updated_at: number;
+}
+
+/**
+ * Increment the version for a given index name.
+ * Sets writer_pid to current process PID.
+ * Uses UPSERT so the row is created on first call.
+ */
+export function bumpVersion(db: DatabaseAdapter, name: string): number {
+    const row = db.prepare(`
+        INSERT INTO index_state (name, version, writer_pid, updated_at)
+        VALUES (?, 1, ?, unixepoch())
+        ON CONFLICT(name) DO UPDATE SET
+            version    = version + 1,
+            writer_pid = excluded.writer_pid,
+            updated_at = excluded.updated_at
+        RETURNING version
+    `).get(name, process.pid) as { version: number };
+    return row.version;
+}
+
+/**
+ * Get all index versions as a Map.
+ * Used by `ensureFresh()` to compare against in-memory versions.
+ */
+export function getVersions(db: DatabaseAdapter): Map<string, number> {
+    const rows = db.prepare('SELECT name, version FROM index_state').all() as IndexStateRow[];
+    const map = new Map<string, number>();
+    for (const row of rows) {
+        map.set(row.name, row.version);
+    }
+    return map;
+}
+
+/** Get the version of a single index. Returns 0 if not found. */
+export function getVersion(db: DatabaseAdapter, name: string): number {
+    const row = db.prepare('SELECT version FROM index_state WHERE name = ?').get(name) as { version: number } | undefined;
+    return row?.version ?? 0;
+}
+
+
+// ── Embedding Meta ──────────────────────────────────────────────────
+
+/** Stored embedding metadata shape. */
+export interface EmbeddingMeta {
+    provider: string;
+    dims: number;
+    /** Stable key for auto-resolving provider on startup (e.g. 'openai', 'local'). */
+    providerKey: string;
+}
+
+/** Get stored embedding metadata. Returns null if not set. */
+export function getEmbeddingMeta(db: DatabaseAdapter): EmbeddingMeta | null {
+    try {
+        const provider = db.prepare(
+            "SELECT value FROM embedding_meta WHERE key = 'provider'"
+        ).get() as EmbeddingMetaRow | undefined;
+        const dims = db.prepare(
+            "SELECT value FROM embedding_meta WHERE key = 'dims'"
+        ).get() as EmbeddingMetaRow | undefined;
+        const key = db.prepare(
+            "SELECT value FROM embedding_meta WHERE key = 'provider_key'"
+        ).get() as EmbeddingMetaRow | undefined;
+
+        if (!provider || !dims) return null;
+        return {
+            provider: provider.value,
+            dims: Number(dims.value),
+            providerKey: key?.value ?? 'local',
+        };
+    } catch {
+        return null;
+    }
+}
+
+/** Store current provider info. */
+export function setEmbeddingMeta(db: DatabaseAdapter, embedding: EmbeddingProvider): void {
+    const upsert = db.prepare(
+        'INSERT OR REPLACE INTO embedding_meta (key, value) VALUES (?, ?)'
+    );
+    upsert.run('provider', embedding.constructor?.name ?? 'unknown');
+    upsert.run('dims', String(embedding.dims));
+    upsert.run('provider_key', providerKey(embedding));
+    upsert.run('indexed_at', new Date().toISOString());
+}
+
+/** Check if the configured provider differs from what's stored. */
+export function detectProviderMismatch(
+    db: DatabaseAdapter,
+    embedding: EmbeddingProvider,
+): { mismatch: boolean; stored: string; current: string } | null {
+    const meta = getEmbeddingMeta(db);
+    if (!meta) return null; // First time, no mismatch
+
+    const currentName = embedding.constructor?.name ?? 'unknown';
+    const mismatch = meta.dims !== embedding.dims || meta.provider !== currentName;
+
+    return {
+        mismatch,
+        stored: `${meta.provider}/${meta.dims}`,
+        current: `${currentName}/${embedding.dims}`,
+    };
+}

package/src/db/migrations.ts

@@ -0,0 +1,66 @@
+/**
+ * BrainBank — Plugin Migration System
+ *
+ * Per-plugin versioned schema migrations.
+ * Each plugin declares a schemaVersion + ordered migrations array.
+ * Core stores applied versions in `plugin_versions` table.
+ *
+ * Plugins call `runPluginMigrations()` at the top of their `initialize()`.
+ * Migrations use `IF NOT EXISTS` so first run on an existing DB is a no-op.
+ */
+
+import type { DatabaseAdapter } from './adapter.ts';
+
+/** A single migration step. */
+export interface Migration {
+    /** Version this migration brings the schema to. */
+    version: number;
+    /** Apply the migration. Must be idempotent (use IF NOT EXISTS). */
+    up(adapter: DatabaseAdapter): void;
+}
+
+/** Get the currently stored schema version for a plugin. Returns 0 if no record. */
+export function getPluginVersion(adapter: DatabaseAdapter, pluginName: string): number {
+    try {
+        const row = adapter.prepare(
+            'SELECT version FROM plugin_versions WHERE plugin_name = ?'
+        ).get(pluginName) as { version: number } | undefined;
+        return row?.version ?? 0;
+    } catch {
+        return 0;
+    }
+}
+
+/** Set the schema version for a plugin. */
+export function setPluginVersion(adapter: DatabaseAdapter, pluginName: string, version: number): void {
+    adapter.prepare(`
+        INSERT OR REPLACE INTO plugin_versions (plugin_name, version, applied_at)
+        VALUES (?, ?, unixepoch())
+    `).run(pluginName, version);
+}
+
+/**
+ * Run pending migrations for a plugin.
+ * Skips migrations whose version <= stored version.
+ * Each migration runs in its own transaction.
+ */
+export function runPluginMigrations(
+    adapter: DatabaseAdapter,
+    pluginName: string,
+    schemaVersion: number,
+    migrations: Migration[],
+): void {
+    const current = getPluginVersion(adapter, pluginName);
+    if (current >= schemaVersion) return;
+
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+
+    for (const m of sorted) {
+        if (m.version <= current) continue;
+
+        adapter.transaction(() => {
+            m.up(adapter);
+            setPluginVersion(adapter, pluginName, m.version);
+        });
+    }
+}