@aprimediet/codewalker 1.0.0 → 1.2.0

package/src/db.test.ts

@@ -0,0 +1,343 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import Database from 'better-sqlite3';
+import { openDb, bootstrapDb, upsertSymbol, searchSymbols, getMeta, setMeta, deleteFileSymbols, upsertLibrary, upsertLibSymbol, deleteLibrary, searchLibSymbols } from './db.ts';
+
+describe('db.ts', () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-db-'));
+    dbPath = path.join(tmpDir, 'test.db');
+  });
+
+  afterEach(() => {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  describe('bootstrapDb', () => {
+    it('creates files, symbols, symbols_fts, and meta tables', () => {
+      const db = new Database(dbPath);
+      bootstrapDb(db);
+      db.close();
+
+      // Re-open and check tables exist
+      const db2 = new Database(dbPath);
+      const tables = db2.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      const tableNames = tables.map(t => t.name);
+      expect(tableNames).toContain('files');
+      expect(tableNames).toContain('symbols');
+      expect(tableNames).toContain('meta');
+
+      // Check FTS virtual table (shows as 'table' type in sqlite_master)
+      const ftsTables = db2.prepare("SELECT name FROM sqlite_master WHERE name='symbols_fts'").all() as { name: string }[];
+      expect(ftsTables.length).toBe(1);
+      expect(ftsTables[0]!.name).toBe('symbols_fts');
+      db2.close();
+    });
+
+    it('is idempotent (can be called twice)', () => {
+      const db = new Database(dbPath);
+      bootstrapDb(db);
+      bootstrapDb(db);
+      db.close();
+      // No error = idempotent
+    });
+
+    it('sets user_version to 1', () => {
+      const db = new Database(dbPath);
+      bootstrapDb(db);
+      const version = db.pragma('user_version', { simple: true }) as number;
+      expect(version).toBe(2);
+      db.close();
+    });
+
+    it('creates libraries, lib_symbols, and lib_symbols_fts tables', () => {
+      const db = openDb(dbPath);
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      const tableNames = tables.map(t => t.name);
+      expect(tableNames).toContain('libraries');
+      expect(tableNames).toContain('lib_symbols');
+
+      const ftsTables = db.prepare("SELECT name FROM sqlite_master WHERE name='lib_symbols_fts'").all() as { name: string }[];
+      expect(ftsTables.length).toBe(1);
+      db.close();
+    });
+
+    it('does not destroy existing symbols tables (additive upgrade)', () => {
+      // Bootstrap v1 DB first, then re-bootstrap (simulate upgrade)
+      const db = new Database(dbPath);
+      bootstrapDb(db);
+      upsertSymbol(db, {
+        name: 'keep', kind: 'function', file_path: 'src/a.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      // Call bootstrapDb again (simulates upgrade to v2 adds lib tables)
+      bootstrapDb(db);
+
+      // Symbol still there
+      const symbols = searchSymbols(db, 'keep', undefined, 10);
+      expect(symbols).toHaveLength(1);
+
+      // Lib tables exist
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      expect(tables.map(t => t.name)).toContain('lib_symbols');
+      db.close();
+    });
+  });
+
+  describe('openDb', () => {
+    it('opens a DB and bootstraps it', () => {
+      const db = openDb(dbPath);
+      expect(db.open).toBe(true);
+      // Tables exist
+      const count = db.prepare("SELECT COUNT(*) as c FROM sqlite_master WHERE type='table'").get() as { c: number };
+      expect(count.c).toBeGreaterThan(0);
+      db.close();
+    });
+  });
+
+  describe('symbols CRUD', () => {
+    it('inserts a symbol and finds it via FTS MATCH', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'myFunc',
+        kind: 'function',
+        file_path: 'src/test.ts',
+        line_start: 10,
+        line_end: 20,
+        signature: '(x: number) => string',
+        doc: 'Does something useful',
+        summary: '',
+        card_path: '/cards/myFunc.md',
+      });
+
+      // FTS search
+      const results = searchSymbols(db, 'myFunc', undefined, 10);
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('myFunc');
+      expect(results[0]!.kind).toBe('function');
+
+      db.close();
+    });
+
+    it('bm25 ranks name hit above doc-only hit', () => {
+      const db = openDb(dbPath);
+
+      // Doc hit: "token" only appears in doc text, not in name
+      upsertSymbol(db, {
+        name: 'loadData',
+        kind: 'function',
+        file_path: 'src/a.ts',
+        line_start: 1,
+        line_end: 5,
+        signature: '() => void',
+        doc: 'Helper to refresh the auth token',
+        summary: '',
+        card_path: '',
+      });
+
+      // Name hit: "token" is in the name
+      upsertSymbol(db, {
+        name: 'refreshToken',
+        kind: 'function',
+        file_path: 'src/b.ts',
+        line_start: 10,
+        line_end: 15,
+        signature: '() => Promise<string>',
+        doc: 'Gets a new token',
+        summary: '',
+        card_path: '',
+      });
+
+      const results = searchSymbols(db, 'token', undefined, 10);
+      expect(results.length).toBeGreaterThanOrEqual(2);
+      // First result should be the name hit (name is weighted higher in bm25)
+      expect(results[0]!.name).toBe('refreshToken');
+
+      db.close();
+    });
+
+    it('re-indexing a file is idempotent (no duplicate rows)', () => {
+      const db = openDb(dbPath);
+
+      // First insert
+      upsertSymbol(db, {
+        name: 'foo', kind: 'function', file_path: 'src/test.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      // Re-insert same file (simulate reindex)
+      deleteFileSymbols(db, 'src/test.ts');
+      upsertSymbol(db, {
+        name: 'foo', kind: 'function', file_path: 'src/test.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      const results = searchSymbols(db, 'foo', undefined, 10);
+      expect(results).toHaveLength(1);
+
+      db.close();
+    });
+
+    it('deleting a file removes only its symbols', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'keep', kind: 'function', file_path: 'src/keep.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertSymbol(db, {
+        name: 'remove', kind: 'function', file_path: 'src/remove.ts',
+        line_start: 2, line_end: 2, signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      deleteFileSymbols(db, 'src/remove.ts');
+
+      const all = searchSymbols(db, '', undefined, 10);
+      expect(all).toHaveLength(1);
+      expect(all[0]!.name).toBe('keep');
+
+      db.close();
+    });
+  });
+
+  describe('library CRUD', () => {
+    it('upsertLibrary inserts or updates a library record', () => {
+      const db = openDb(dbPath);
+      upsertLibrary(db, { name: 'hono', version: '4.6.3', source: 'node_modules', dts_path: '/a.d.ts', readme: 'Hono web framework' });
+
+      const row = db.prepare("SELECT * FROM libraries WHERE name = ?").get('hono') as any;
+      expect(row).not.toBeUndefined();
+      expect(row.version).toBe('4.6.3');
+      expect(row.source).toBe('node_modules');
+      db.close();
+    });
+
+    it('upsertLibSymbol inserts a lib symbol and it is FTS-searchable', () => {
+      const db = openDb(dbPath);
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'export declare function createMiddleware(...)',
+        doc: 'Define a typed middleware handler.', summary: 'Define a typed middleware handler.',
+        card_path: '/cards/hono/createMiddleware.md',
+      });
+
+      const results = searchLibSymbols(db, 'createMiddleware', undefined, 10);
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('createMiddleware');
+      expect(results[0]!.lib).toBe('hono');
+      expect(results[0]!.version).toBe('4.6.3');
+      expect(results[0]!.source).toBe('lib');
+
+      db.close();
+    });
+
+    it('searchLibSymbols empty query returns all symbols ordered by name', () => {
+      const db = openDb(dbPath);
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'zMiddleware',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'aRouter',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      const results = searchLibSymbols(db, '', undefined, 10);
+      expect(results).toHaveLength(2);
+      expect(results[0]!.name).toBe('aRouter');
+      expect(results[1]!.name).toBe('zMiddleware');
+      db.close();
+    });
+
+    it('deleteLibrary removes symbols and FTS rows for all versions of a lib', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.5.0', name: 'oldFunc',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      deleteLibrary(db, 'hono');
+
+      const results = searchLibSymbols(db, '', undefined, 10);
+      expect(results).toHaveLength(0);
+
+      const libRow = db.prepare("SELECT * FROM libraries WHERE name = ?").get('hono') as any;
+      expect(libRow).toBeUndefined();
+
+      db.close();
+    });
+
+    it('re-inserting same (lib, name) does not create duplicates', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'v1', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'v2', doc: '', summary: '', card_path: '',
+      });
+
+      const results = searchLibSymbols(db, 'createMiddleware', undefined, 10);
+      expect(results).toHaveLength(1);
+      // Latest signature
+      expect(results[0]!.signature).toBe('v2');
+
+      db.close();
+    });
+
+    it('kind filter narrows lib symbol results', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'myFunc',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'MyType',
+        kind: 'type', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      const funcs = searchLibSymbols(db, '', 'function', 10);
+      expect(funcs).toHaveLength(1);
+      expect(funcs[0]!.name).toBe('myFunc');
+
+      db.close();
+    });
+  });
+
+  describe('meta', () => {
+    it('setMeta and getMeta round-trip values', () => {
+      const db = openDb(dbPath);
+      setMeta(db, 'last_indexed_commit', 'abc123');
+      setMeta(db, 'schema_version', '1');
+
+      expect(getMeta(db, 'last_indexed_commit')).toBe('abc123');
+      expect(getMeta(db, 'schema_version')).toBe('1');
+      expect(getMeta(db, 'nonexistent')).toBeNull();
+
+      db.close();
+    });
+
+    it('setMeta overwrites existing values', () => {
+      const db = openDb(dbPath);
+      setMeta(db, 'key', 'first');
+      setMeta(db, 'key', 'second');
+      expect(getMeta(db, 'key')).toBe('second');
+      db.close();
+    });
+  });
+});

package/src/db.ts

@@ -0,0 +1,363 @@
+/**
+ * SQLite database layer for codewalker.
+ *
+ * Uses better-sqlite3 with WAL mode. The schema follows the design in the build prompt:
+ * - `files`: tracks indexed files (path, lang, sha, indexed_at)
+ * - `symbols`: one row per extracted symbol
+ * - `symbols_fts`: FTS5 virtual table for full-text search
+ * - `meta`: key/value store for index metadata
+ *
+ * FTS5 uses external-content mode pointing at `symbols`. When re-indexing a file,
+ * delete its rows + matching FTS rows, then INSERT fresh.
+ */
+
+import Database, { type Database as DatabaseType } from "better-sqlite3";
+import type { LibSymbol } from "./types.ts";
+
+export { Database };
+export type { DatabaseType };
+
+/** Open a DB file path, enable WAL, and bootstrap schema. */
+export function openDb(dbPath: string): DatabaseType {
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  bootstrapDb(db);
+  return db;
+}
+
+/** Bootstrap DDL — idempotent (all CREATE use IF NOT EXISTS). */
+export function bootstrapDb(db: DatabaseType): void {
+  db.exec(`
+    PRAGMA user_version = 2;
+
+    CREATE TABLE IF NOT EXISTS files (
+      path        TEXT PRIMARY KEY,
+      lang        TEXT,
+      blob_sha    TEXT,
+      indexed_at  TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS symbols (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      name        TEXT NOT NULL,
+      kind        TEXT,
+      file_path   TEXT,
+      line_start  INTEGER,
+      line_end    INTEGER,
+      signature   TEXT,
+      doc         TEXT,
+      summary     TEXT,
+      card_path   TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
+      name, signature, doc, summary,
+      content='symbols', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TABLE IF NOT EXISTS libraries (
+      name        TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      source      TEXT,
+      dts_path    TEXT,
+      readme      TEXT,
+      indexed_at  TEXT,
+      PRIMARY KEY (name, version)
+    );
+
+    CREATE TABLE IF NOT EXISTS lib_symbols (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      lib         TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      kind        TEXT,
+      signature   TEXT,
+      doc         TEXT,
+      summary     TEXT,
+      card_path   TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS lib_symbols_fts USING fts5(
+      name, signature, doc, summary,
+      content='lib_symbols', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+
+    -- Keep the external-content FTS indexes in sync via triggers (the SQLite-documented
+    -- pattern). Code must do plain INSERT/UPDATE/DELETE on the base tables and NEVER touch
+    -- the *_fts tables directly: the 'delete' command needs the ORIGINAL column values, which
+    -- only the triggers (via old.*) have. Hand-rolled FTS maintenance with empty/placeholder
+    -- values corrupts the index ("database disk image is malformed").
+    CREATE TRIGGER IF NOT EXISTS symbols_ai AFTER INSERT ON symbols BEGIN
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_ad AFTER DELETE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_au AFTER UPDATE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ai AFTER INSERT ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ad AFTER DELETE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_au AFTER UPDATE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+  `);
+}
+
+/** Upsert a file record. */
+export function upsertFile(
+  db: DatabaseType,
+  path: string,
+  lang: string,
+  blobSha: string,
+): void {
+  db.prepare(
+    `INSERT INTO files (path, lang, blob_sha, indexed_at)
+     VALUES (?, ?, ?, datetime('now'))
+     ON CONFLICT(path) DO UPDATE SET lang=excluded.lang, blob_sha=excluded.blob_sha, indexed_at=excluded.indexed_at`,
+  ).run(path, lang, blobSha);
+}
+
+/** Delete file tracking row. */
+export function deleteFile(db: DatabaseType, filePath: string): void {
+  db.prepare("DELETE FROM files WHERE path = ?").run(filePath);
+}
+
+/** Insert or update a symbol. Replaces on (name, file_path) conflict. */
+export function upsertSymbol(
+  db: DatabaseType,
+  symbol: {
+    name: string;
+    kind: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+    signature: string;
+    doc: string;
+    summary: string;
+    card_path: string;
+  },
+): void {
+  // Plain INSERT — the symbols_ai trigger keeps symbols_fts in sync. Callers (scan/sync) always
+  // delete a file's symbols before re-inserting, so re-indexing is idempotent without an update path.
+  db.prepare(
+    `INSERT INTO symbols (name, kind, file_path, line_start, line_end, signature, doc, summary, card_path)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    symbol.name, symbol.kind, symbol.file_path, symbol.line_start, symbol.line_end,
+    symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
+  );
+}
+
+/** Delete all symbols for a given file. The symbols_ad trigger removes their FTS rows. */
+export function deleteFileSymbols(db: DatabaseType, filePath: string): void {
+  db.prepare("DELETE FROM symbols WHERE file_path = ?").run(filePath);
+}
+
+/** Search symbols via FTS5 MATCH, ranked by bm25. */
+export function searchSymbols(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: string,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  summary: string;
+  score: number;
+}> {
+  if (!query.trim()) {
+    // Return all symbols ordered by name
+    let sql = "SELECT s.id, s.name, s.kind, s.file_path, s.line_start, s.line_end, s.signature, s.summary, 0.0 as score FROM symbols s";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE s.kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY s.name LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params) as typeof results;
+  }
+
+  let sql = `
+    SELECT s.id, s.name, s.kind, s.file_path, s.line_start, s.line_end, s.signature, s.summary,
+           bm25(symbols_fts, 10.0, 5.0, 1.0, 8.0) as score
+    FROM symbols_fts
+    JOIN symbols s ON s.id = symbols_fts.rowid
+    WHERE symbols_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND s.kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  return db.prepare(sql).all(...params) as typeof results;
+}
+
+/** Upsert a library record. */
+export function upsertLibrary(
+  db: DatabaseType,
+  pkg: { name: string; version: string; source?: string; dts_path?: string | null; readme?: string | null },
+): void {
+  db.prepare(
+    `INSERT INTO libraries (name, version, source, dts_path, readme, indexed_at)
+     VALUES (?, ?, ?, ?, ?, datetime('now'))
+     ON CONFLICT(name, version) DO UPDATE SET
+       source=excluded.source, dts_path=excluded.dts_path, readme=excluded.readme, indexed_at=excluded.indexed_at`,
+  ).run(pkg.name, pkg.version, pkg.source ?? null, pkg.dts_path ?? null, pkg.readme ?? null);
+}
+
+/** Upsert a lib symbol. Replaces on (lib, name) duplicate. */
+export function upsertLibSymbol(
+  db: DatabaseType,
+  symbol: {
+    lib: string;
+    version: string;
+    name: string;
+    kind: string;
+    signature: string;
+    doc: string;
+    summary: string;
+    card_path: string;
+  },
+): void {
+  // The lib_symbols_ai / _au triggers keep lib_symbols_fts in sync — never touch the FTS table here.
+  const existing = db.prepare(
+    "SELECT id FROM lib_symbols WHERE lib = ? AND name = ?",
+  ).get(symbol.lib, symbol.name) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE lib_symbols SET version=?, kind=?, signature=?, doc=?, summary=?, card_path=?
+       WHERE id = ?`,
+    ).run(
+      symbol.version, symbol.kind, symbol.signature,
+      symbol.doc, symbol.summary, symbol.card_path,
+      existing.id,
+    );
+  } else {
+    db.prepare(
+      `INSERT INTO lib_symbols (lib, version, name, kind, signature, doc, summary, card_path)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      symbol.lib, symbol.version, symbol.name, symbol.kind,
+      symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
+    );
+  }
+}
+
+/** Delete all lib_symbols (all versions) for a library, then the libraries rows.
+ *  The lib_symbols_ad trigger removes the FTS rows. */
+export function deleteLibrary(db: DatabaseType, libName: string): void {
+  db.prepare("DELETE FROM lib_symbols WHERE lib = ?").run(libName);
+  db.prepare("DELETE FROM libraries WHERE name = ?").run(libName);
+}
+
+/**
+ * Search lib symbols via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all symbols ordered by name.
+ */
+export function searchLibSymbols(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: string,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  lib: string;
+  version: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  summary: string;
+  score: number;
+  source: "lib";
+}> {
+  if (!query.trim()) {
+    let sql = "SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary, 0.0 as score FROM lib_symbols s";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE s.kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY s.name LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params).map((r: any) => ({
+      ...r,
+      file_path: "",
+      line_start: 0,
+      line_end: 0,
+      source: "lib" as const,
+    }));
+  }
+
+  let sql = `
+    SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary,
+           bm25(lib_symbols_fts, 10.0, 5.0, 1.0, 8.0) as score
+    FROM lib_symbols_fts
+    JOIN lib_symbols s ON s.id = lib_symbols_fts.rowid
+    WHERE lib_symbols_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND s.kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  return db.prepare(sql).all(...params).map((r: any) => ({
+    ...r,
+    file_path: "",
+    line_start: 0,
+    line_end: 0,
+    source: "lib" as const,
+  }));
+}
+
+/** Get a meta value. */
+export function getMeta(db: DatabaseType, key: string): string | null {
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+/** Set a meta value. */
+export function setMeta(db: DatabaseType, key: string, value: string): void {
+  db.prepare(
+    "INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+  ).run(key, value);
+}