cursedbelt-server 1.0.0

package/src/server/sqlite/fts5.spec.ts

@@ -0,0 +1,175 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { applyFtsSchema, buildFtsSchema, createFts5Search, sanitizeFtsQuery } from './fts5';
+
+/** A representative content table + its FTS index, the way an app migration would. */
+function makeNotesDb(): Database {
+  const db = new Database(':memory:');
+  db.run('CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)');
+  applyFtsSchema(db, { table: 'notes_fts', contentTable: 'notes', columns: ['body'] });
+  return db;
+}
+
+describe('sanitizeFtsQuery', () => {
+  test('wraps each word as an AND-of-prefix token', () => {
+    expect(sanitizeFtsQuery('hello')).toBe('"hello"*');
+    expect(sanitizeFtsQuery('hello world')).toBe('"hello"* "world"*');
+  });
+
+  test('strips FTS5 operators so input cannot inject syntax or error out', () => {
+    expect(sanitizeFtsQuery('"; DROP--')).toBe('"DROP"*');
+    expect(sanitizeFtsQuery('foo:bar^2 (baz)')).toBe('"foo"* "bar"* "2"* "baz"*');
+    expect(sanitizeFtsQuery('a AND b')).toBe('"a"* "AND"* "b"*'); // AND is just a literal term
+  });
+
+  test('returns empty string when nothing searchable remains', () => {
+    expect(sanitizeFtsQuery('')).toBe('');
+    expect(sanitizeFtsQuery('   ')).toBe('');
+    expect(sanitizeFtsQuery('***')).toBe('');
+  });
+
+  test('keeps unicode letters/digits', () => {
+    expect(sanitizeFtsQuery('café 2024')).toBe('"café"* "2024"*');
+  });
+});
+
+describe('buildFtsSchema', () => {
+  test('emits an external-content table + three sync triggers', () => {
+    const sql = buildFtsSchema({ table: 'notes_fts', contentTable: 'notes', columns: ['body'] });
+    expect(sql).toContain('USING fts5(\n  "body",\n  content="notes"');
+    expect(sql).toContain('content_rowid="id"');
+    expect(sql).toContain('AFTER INSERT ON "notes"');
+    expect(sql).toContain('AFTER DELETE ON "notes"');
+    expect(sql).toContain('AFTER UPDATE ON "notes"');
+  });
+
+  test('rejects non-identifier names and empty column lists', () => {
+    expect(() =>
+      buildFtsSchema({ table: 'a"; DROP', contentTable: 'n', columns: ['c'] }),
+    ).toThrow();
+    expect(() => buildFtsSchema({ table: 'a_fts', contentTable: 'n', columns: [] })).toThrow();
+  });
+
+  test('supports a custom rowid and multiple columns', () => {
+    const db = new Database(':memory:');
+    db.run('CREATE TABLE c (pk INTEGER PRIMARY KEY, first TEXT, last TEXT)');
+    applyFtsSchema(db, {
+      table: 'c_fts',
+      contentTable: 'c',
+      contentRowid: 'pk',
+      columns: ['first', 'last'],
+    });
+    db.run("INSERT INTO c (pk, first, last) VALUES (5, 'Ada', 'Lovelace')");
+    const hits = createFts5Search(db).search({ table: 'c_fts', query: 'lovelace' });
+    expect(hits).toHaveLength(1);
+    expect(hits[0].rowid).toBe(5);
+  });
+});
+
+describe('createFts5Search.search', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = makeNotesDb();
+    db.run("INSERT INTO notes (id, body) VALUES (1, 'Hello world')");
+    db.run("INSERT INTO notes (id, body) VALUES (2, 'Goodbye moon')");
+  });
+
+  test('finds a single match and ranks it (bm25, negative)', () => {
+    const results = createFts5Search(db).search({ table: 'notes_fts', query: 'hello' });
+    expect(results).toHaveLength(1);
+    expect(results[0].rowid).toBe(1);
+    expect(results[0].rank).toBeLessThan(0);
+  });
+
+  test('multi-word query ANDs the terms', () => {
+    const fts = createFts5Search(db);
+    expect(fts.search({ table: 'notes_fts', query: 'hello world' })).toHaveLength(1);
+    expect(fts.search({ table: 'notes_fts', query: 'hello moon' })).toHaveLength(0);
+  });
+
+  test('no-match and prefix-match behave as expected', () => {
+    const fts = createFts5Search(db);
+    expect(fts.search({ table: 'notes_fts', query: 'xyz123xyz' })).toHaveLength(0);
+    expect(fts.search({ table: 'notes_fts', query: 'hel' })).toHaveLength(1);
+  });
+
+  test('empty/operator-only query returns [] without touching the DB', () => {
+    expect(createFts5Search(db).search({ table: 'notes_fts', query: '   ' })).toEqual([]);
+  });
+
+  test('orders results by relevance (rank ascending)', () => {
+    db.run("INSERT INTO notes (id, body) VALUES (3, 'hello hello hello')");
+    const results = createFts5Search(db).search({ table: 'notes_fts', query: 'hello' });
+    expect(results.map((r) => r.rowid)).toEqual([3, 1]); // denser match ranks first
+    expect(results[0].rank).toBeLessThanOrEqual(results[1].rank);
+  });
+
+  test('snippet + highlight columns are returned only when requested', () => {
+    const plain = createFts5Search(db).search({ table: 'notes_fts', query: 'hello' })[0];
+    expect(plain.snippet).toBeUndefined();
+    expect(plain.highlight).toBeUndefined();
+
+    const rich = createFts5Search(db).search({
+      table: 'notes_fts',
+      query: 'hello',
+      snippet: { startMatch: '[', endMatch: ']' },
+      highlight: { column: 0, startMatch: '<', endMatch: '>' },
+    })[0];
+    expect(rich.snippet).toBe('[Hello] world');
+    expect(rich.highlight).toBe('<Hello> world');
+  });
+
+  test('limit + offset paginate', () => {
+    db.run("INSERT INTO notes (id, body) VALUES (3, 'hello there')");
+    const fts = createFts5Search(db);
+    const page1 = fts.search({ table: 'notes_fts', query: 'hello', limit: 1, offset: 0 });
+    const page2 = fts.search({ table: 'notes_fts', query: 'hello', limit: 1, offset: 1 });
+    expect(page1).toHaveLength(1);
+    expect(page2).toHaveLength(1);
+    expect(page1[0].rowid).not.toBe(page2[0].rowid);
+  });
+
+  test('rejects a non-identifier table name', () => {
+    expect(() => createFts5Search(db).search({ table: 'notes_fts; DROP', query: 'x' })).toThrow();
+  });
+});
+
+describe('createFts5Search triggers + maintenance', () => {
+  test('triggers keep the index in sync on insert / update / delete', () => {
+    const db = makeNotesDb();
+    const fts = createFts5Search(db);
+    db.run("INSERT INTO notes (id, body) VALUES (1, 'alpha')");
+    expect(fts.search({ table: 'notes_fts', query: 'alpha' })).toHaveLength(1);
+
+    db.run("UPDATE notes SET body = 'beta' WHERE id = 1");
+    expect(fts.search({ table: 'notes_fts', query: 'alpha' })).toHaveLength(0);
+    expect(fts.search({ table: 'notes_fts', query: 'beta' })).toHaveLength(1);
+
+    db.run('DELETE FROM notes WHERE id = 1');
+    expect(fts.search({ table: 'notes_fts', query: 'beta' })).toHaveLength(0);
+  });
+
+  test('clear empties the index; rebuild repopulates it from content', () => {
+    const db = makeNotesDb();
+    db.run("INSERT INTO notes (id, body) VALUES (1, 'searchable text')");
+    const fts = createFts5Search(db, { tables: ['notes_fts'] });
+    expect(fts.search({ table: 'notes_fts', query: 'searchable' })).toHaveLength(1);
+
+    fts.clear('notes_fts');
+    expect(fts.search({ table: 'notes_fts', query: 'searchable' })).toHaveLength(0);
+
+    fts.rebuildAll();
+    expect(fts.search({ table: 'notes_fts', query: 'searchable' })).toHaveLength(1);
+
+    // optimize is a maintenance no-op for correctness — it must not throw or lose rows.
+    fts.optimize('notes_fts');
+    expect(fts.search({ table: 'notes_fts', query: 'searchable' })).toHaveLength(1);
+  });
+
+  test('rebuildAll iterates only the configured tables', () => {
+    const db = makeNotesDb();
+    db.run("INSERT INTO notes (id, body) VALUES (1, 'x')");
+    // No tables configured → rebuildAll is a no-op (does not throw).
+    expect(() => createFts5Search(db).rebuildAll()).not.toThrow();
+  });
+});

package/src/server/sqlite/fts5.ts

@@ -0,0 +1,255 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * FTS5 full-text search for `bun:sqlite` — the from-scratch replacement for the apps'
+ * hand-rolled `LIKE '%' || ? || '%'` search. Three pieces:
+ *
+ *  1. {@link buildFtsSchema} — generates the `CREATE VIRTUAL TABLE` + the three
+ *     external-content sync triggers for one indexed table. Apps call it from a
+ *     migration instead of hand-writing the (highly repetitive) trigger SQL 4×.
+ *  2. {@link createFts5Search} — a ranked query builder (bm25 `rank`, `snippet`,
+ *     `highlight`) over those tables, plus the FTS5 maintenance commands
+ *     (`rebuild`/`clear`/`optimize`) the ETL and bulk importers need.
+ *  3. {@link sanitizeFtsQuery} — turns arbitrary user input into a safe AND-of-prefix
+ *     FTS5 MATCH expression (no operator injection, no parse errors).
+ *
+ * FTS5 is compiled into `bun:sqlite` (NOT `node:sqlite`, which omits it). Everything
+ * here is app-agnostic: the indexed table names are a *constructor option*, never
+ * hard-coded — ca and ru index different tables.
+ */
+
+/** A safe, unquoted SQL identifier (table/column name). */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function assertIdent(name: string, what: string): string {
+  if (!IDENT.test(name)) {
+    throw new Error(`Invalid ${what}: ${JSON.stringify(name)} (expected a plain SQL identifier)`);
+  }
+  return name;
+}
+
+/** Double-quote an identifier (validated first, so the quoting can't be escaped out of). */
+const q = (name: string): string => `"${name}"`;
+
+/** Single-quote a string literal for inlining (doubles embedded quotes). */
+const lit = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+
+/** Coerce to a bounded non-negative integer for inlining (snippet token counts, etc.). */
+const int = (n: number, fallback: number): number =>
+  Number.isFinite(n) ? Math.trunc(n) : fallback;
+
+// ── Schema generation ────────────────────────────────────────────────────────
+
+export interface FtsTableSpec {
+  /** The FTS5 virtual table to create, e.g. `'notes_fts'`. */
+  table: string;
+  /** The source ("content") table whose text it indexes, e.g. `'notes'`. */
+  contentTable: string;
+  /** The content table's rowid/primary-key column. Default: `'id'`. */
+  contentRowid?: string;
+  /** Indexed columns — must exist on the content table, in this order. */
+  columns: string[];
+  /**
+   * FTS5 tokenizer directive. Default: `unicode61 remove_diacritics 2` (case- and
+   * accent-folding, the right default for human text). Pass e.g. `'porter unicode61'`
+   * for stemming, or `'trigram'` for substring search.
+   */
+  tokenize?: string;
+}
+
+/**
+ * Build the DDL for one external-content FTS5 table and its three sync triggers
+ * (insert/update/delete), as a single multi-statement string ready for `db.run()`.
+ *
+ * External content (`content=<table>, content_rowid=<pk>`) means the FTS index stores
+ * only the inverted index, never a second copy of the text — the triggers mirror every
+ * write into the index. This is the canonical pattern from the SQLite FTS5 docs,
+ * generated once so apps don't repeat it per table.
+ */
+export function buildFtsSchema(spec: FtsTableSpec): string {
+  const table = assertIdent(spec.table, 'fts table name');
+  const content = assertIdent(spec.contentTable, 'content table name');
+  const rowid = assertIdent(spec.contentRowid ?? 'id', 'content rowid column');
+  if (spec.columns.length === 0) {
+    throw new Error(`buildFtsSchema(${table}): at least one indexed column is required`);
+  }
+  const cols = spec.columns.map((c) => assertIdent(c, 'indexed column'));
+  const tokenize = spec.tokenize ?? 'unicode61 remove_diacritics 2';
+
+  const colList = cols.map(q).join(', ');
+  const newVals = cols.map((c) => `new.${q(c)}`).join(', ');
+  const oldVals = cols.map((c) => `old.${q(c)}`).join(', ');
+
+  // `INSERT INTO <fts>(<fts>, rowid, …) VALUES('delete', …)` is FTS5's documented way
+  // to remove the prior term rows for a content row before re-indexing it.
+  return `
+CREATE VIRTUAL TABLE IF NOT EXISTS ${q(table)} USING fts5(
+  ${colList},
+  content=${q(content)},
+  content_rowid=${q(rowid)},
+  tokenize=${lit(tokenize)}
+);
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_ai`)} AFTER INSERT ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(rowid, ${colList}) VALUES (new.${q(rowid)}, ${newVals});
+END;
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_ad`)} AFTER DELETE ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(${q(table)}, rowid, ${colList}) VALUES ('delete', old.${q(rowid)}, ${oldVals});
+END;
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_au`)} AFTER UPDATE ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(${q(table)}, rowid, ${colList}) VALUES ('delete', old.${q(rowid)}, ${oldVals});
+  INSERT INTO ${q(table)}(rowid, ${colList}) VALUES (new.${q(rowid)}, ${newVals});
+END;`.trim();
+}
+
+/** Create every table in `specs` and its triggers on `db` (one `db.run` per spec). */
+export function applyFtsSchema(db: Database, ...specs: FtsTableSpec[]): void {
+  for (const spec of specs) db.run(buildFtsSchema(spec));
+}
+
+// ── Search ───────────────────────────────────────────────────────────────────
+
+export interface FtsResult {
+  /** The content row's rowid (its `content_rowid` value). */
+  rowid: number;
+  /** FTS5 bm25 relevance — lower (more negative) is more relevant. */
+  rank: number;
+  /** Present only when `snippet` was requested: a truncated, match-marked excerpt. */
+  snippet?: string;
+  /** Present only when `highlight` was requested: the full column with matches marked. */
+  highlight?: string;
+}
+
+export interface FtsSnippetOpts {
+  /** FTS column index to excerpt; `-1` (default) auto-picks the best-matching column. */
+  column?: number;
+  /** Wraps each match, default `'<b>'`. */
+  startMatch?: string;
+  /** Closes each match, default `'</b>'`. */
+  endMatch?: string;
+  /** Inserted where text is trimmed, default `'…'`. */
+  ellipsis?: string;
+  /** Max tokens in the excerpt (1–64), default `16`. */
+  maxTokens?: number;
+}
+
+export interface FtsHighlightOpts {
+  /** FTS column index to return (required — `highlight()` has no auto column). */
+  column: number;
+  /** Wraps each match, default `'<b>'`. */
+  startMatch?: string;
+  /** Closes each match, default `'</b>'`. */
+  endMatch?: string;
+}
+
+export interface FtsSearchOpts {
+  /** The FTS5 table to query, e.g. `'notes_fts'`. */
+  table: string;
+  /** Raw user query — sanitized into a prefix-match expression before MATCH. */
+  query: string;
+  /** Page size, default `20`. */
+  limit?: number;
+  /** Row offset, default `0`. */
+  offset?: number;
+  /** Request a `snippet(...)` excerpt column. */
+  snippet?: FtsSnippetOpts;
+  /** Request a `highlight(...)` column. */
+  highlight?: FtsHighlightOpts;
+}
+
+export interface Fts5Search {
+  /** Ranked search; returns `[]` for an empty/operator-only query (never throws on it). */
+  search(opts: FtsSearchOpts): FtsResult[];
+  /** Rebuild one FTS index from its content table (post-ETL / after `clear`). */
+  rebuild(table: string): void;
+  /** Rebuild every table passed to {@link createFts5Search} (`tables` option). */
+  rebuildAll(): void;
+  /** Empty an FTS index (the `'delete-all'` command) — pair with `rebuild` for bulk loads. */
+  clear(table: string): void;
+  /** Merge the index's b-tree segments (the `'optimize'` command) for faster queries. */
+  optimize(table: string): void;
+}
+
+function snippetExpr(table: string, o: FtsSnippetOpts): string {
+  const col = int(o.column ?? -1, -1);
+  const start = lit(o.startMatch ?? '<b>');
+  const end = lit(o.endMatch ?? '</b>');
+  const ell = lit(o.ellipsis ?? '…');
+  const tokens = Math.min(64, Math.max(1, int(o.maxTokens ?? 16, 16)));
+  return `snippet(${q(table)}, ${col}, ${start}, ${end}, ${ell}, ${tokens}) AS snippet`;
+}
+
+function highlightExpr(table: string, o: FtsHighlightOpts): string {
+  const col = Math.max(0, int(o.column, 0));
+  const start = lit(o.startMatch ?? '<b>');
+  const end = lit(o.endMatch ?? '</b>');
+  return `highlight(${q(table)}, ${col}, ${start}, ${end}) AS highlight`;
+}
+
+/**
+ * Build a ranked-search facade over the FTS5 tables named in `opts.tables` (the set
+ * `rebuildAll()` iterates). The `db` handle is the same one the app uses — one
+ * connection, one WAL.
+ */
+export function createFts5Search(db: Database, opts: { tables?: string[] } = {}): Fts5Search {
+  const tables = (opts.tables ?? []).map((t) => assertIdent(t, 'fts table name'));
+
+  const facade: Fts5Search = {
+    search(o) {
+      const match = sanitizeFtsQuery(o.query);
+      if (!match) return [];
+      const table = assertIdent(o.table, 'fts table name');
+
+      const projection = ['rowid', 'rank'];
+      if (o.snippet) projection.push(snippetExpr(table, o.snippet));
+      if (o.highlight) projection.push(highlightExpr(table, o.highlight));
+
+      const sql = `SELECT ${projection.join(', ')} FROM ${q(table)} WHERE ${q(table)} MATCH ? ORDER BY rank LIMIT ? OFFSET ?`;
+      return db
+        .query<FtsResult, [string, number, number]>(sql)
+        .all(match, Math.max(0, int(o.limit ?? 20, 20)), Math.max(0, int(o.offset ?? 0, 0)));
+    },
+
+    rebuild(table) {
+      const t = assertIdent(table, 'fts table name');
+      db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('rebuild')`);
+    },
+
+    rebuildAll() {
+      for (const t of tables) facade.rebuild(t);
+    },
+
+    clear(table) {
+      const t = assertIdent(table, 'fts table name');
+      db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('delete-all')`);
+    },
+
+    optimize(table) {
+      const t = assertIdent(table, 'fts table name');
+      db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('optimize')`);
+    },
+  };
+
+  return facade;
+}
+
+// ── Query sanitization ─────────────────────────────────────────────────────────
+
+/**
+ * Convert arbitrary user input into a safe FTS5 MATCH expression: every run of
+ * letters/digits/underscore becomes a quoted prefix token (`"term"*`), joined by
+ * spaces (FTS5's implicit AND). All FTS5 operators (`" * : ^ ( ) - + NEAR …`) are
+ * dropped with the surrounding punctuation, so the query can neither inject syntax
+ * nor raise a parse error. Returns `''` when nothing searchable remains.
+ *
+ * Examples: `hello` → `"hello"*`; `hello world` → `"hello"* "world"*` (both must
+ * match); `DROP TABLE` → `"DROP"* "TABLE"*` (a literal search, harmless).
+ */
+export function sanitizeFtsQuery(raw: string, opts: { mode?: 'all' | 'any' } = {}): string {
+  const tokens = raw.match(/[\p{L}\p{N}_]+/gu);
+  if (!tokens || tokens.length === 0) return '';
+  // 'all' (default) = AND-of-prefix — precision, right for search-as-you-type.
+  // 'any' = OR-of-prefix — recall, right for retrieval from a natural-language
+  // question where requiring every word ("what do I have about…") matches nothing;
+  // bm25 still ranks docs hitting more/rarer terms first.
+  return tokens.map((t) => `"${t}"*`).join(opts.mode === 'any' ? ' OR ' : ' ');
+}

package/src/server/sqlite/health.spec.ts

@@ -0,0 +1,79 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSqliteHealthChecks } from './health';
+
+const find = (db: Database, opts: Parameters<typeof createSqliteHealthChecks>[1], name: string) =>
+  createSqliteHealthChecks(db, opts).find((c) => c.name === name);
+
+describe('createSqliteHealthChecks', () => {
+  const dirs: string[] = [];
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+  const tmp = () => {
+    const d = mkdtempSync(join(tmpdir(), 'cb-health-'));
+    dirs.push(d);
+    return d;
+  };
+
+  test('exposes the three named probes', () => {
+    expect(createSqliteHealthChecks(new Database(':memory:'), {}).map((c) => c.name)).toEqual([
+      'sqlite:integrity',
+      'sqlite:size',
+      'sqlite:wal',
+    ]);
+  });
+
+  test('integrity is ok on a healthy DB', async () => {
+    const db = new Database(':memory:');
+    db.run('CREATE TABLE t (id INTEGER PRIMARY KEY)');
+    const result = await find(db, {}, 'sqlite:integrity')!.check();
+    expect(result.status).toBe('ok');
+    expect(result.message).toBe('ok');
+  });
+
+  test('size reports ok below the threshold and warn above it', async () => {
+    const db = new Database(':memory:');
+    db.run('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)');
+
+    const ok = await find(db, {}, 'sqlite:size')!.check();
+    expect(ok.status).toBe('ok');
+    expect(ok.message).toMatch(/MB$/);
+
+    const warn = await find(db, { maxSizeBytes: 0 }, 'sqlite:size')!.check();
+    expect(warn.status).toBe('warn');
+    expect(warn.message).toContain('threshold');
+  });
+
+  test('wal is ok on a non-WAL (:memory:) DB', async () => {
+    const result = await find(new Database(':memory:'), {}, 'sqlite:wal')!.check();
+    expect(result.status).toBe('ok');
+    expect(result.message).toBe('0 WAL pages');
+  });
+
+  test('wal warns when uncheckpointed pages exceed the threshold', async () => {
+    const db = new Database(join(tmp(), 'wal.sqlite'), { create: true });
+    db.run('PRAGMA journal_mode = WAL');
+    db.run('PRAGMA wal_autocheckpoint = 100000'); // keep frames in the WAL
+    db.run('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)');
+    for (let i = 0; i < 300; i++) db.run('INSERT INTO t (v) VALUES (?)', [`row-${i}`]);
+
+    const result = await find(db, { maxWalPages: 0 }, 'sqlite:wal')!.check();
+    expect(result.status).toBe('warn');
+    expect(result.message).toMatch(/WAL has \d+ pages/);
+    db.close();
+  });
+
+  test('a check never throws — corrupt-page detail surfaces as an error status', async () => {
+    // quick_check on a valid DB returns 'ok'; this asserts the contract shape: status
+    // is always one of ok/warn/error and check() resolves rather than rejecting.
+    const checks = createSqliteHealthChecks(new Database(':memory:'), {});
+    for (const c of checks) {
+      const r = await c.check();
+      expect(['ok', 'warn', 'error']).toContain(r.status);
+    }
+  });
+});

package/src/server/sqlite/health.ts

@@ -0,0 +1,105 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * DB-layer health probes for `bun:sqlite`. Each is a small, self-describing descriptor
+ * — `name` + `description` + an async `check()` returning a status — so it can be
+ * rendered in an operator console and drive readiness from one source.
+ *
+ * The shape is intentionally dependency-free (it does NOT import cwip's health types):
+ * apps adapt a descriptor into cwip's `HealthCheck` registry with a trivial map, e.g.
+ *
+ * ```ts
+ * registry.register(...createSqliteHealthChecks(db, {}).map((p) => async () => {
+ *   const r = await p.check();
+ *   return { id: p.name, title: p.description, category: 'Database',
+ *            severity: 'warn', status: r.status, detail: r.message ?? '', remediation: [] };
+ * }));
+ * ```
+ *
+ * `status` values (`ok`/`warn`/`error`) already line up with cwip's `HealthStatus`.
+ */
+
+export type SqliteHealthStatus = 'ok' | 'warn' | 'error';
+
+export interface SqliteHealthResult {
+  status: SqliteHealthStatus;
+  /** Human-readable detail for the current status. */
+  message?: string;
+}
+
+export interface SqliteHealthCheck {
+  /** Stable id, e.g. `'sqlite:integrity'`. */
+  name: string;
+  /** Short human description. */
+  description: string;
+  check(): Promise<SqliteHealthResult>;
+}
+
+export interface SqliteHealthOpts {
+  /** Warn when the DB file exceeds this many bytes. Default: 500 MB. */
+  maxSizeBytes?: number;
+  /** Warn when the WAL holds more than this many pages. Default: 1000. */
+  maxWalPages?: number;
+}
+
+const BYTES_PER_MB = 1_048_576;
+const mb = (bytes: number): string => `${(bytes / BYTES_PER_MB).toFixed(1)}MB`;
+
+/**
+ * Build the SQLite health probes for `db`. Use `quick_check` (fast, still catches
+ * corruption) in the loop; expose the exhaustive `integrity_check` as an
+ * admin-triggered action elsewhere.
+ */
+export function createSqliteHealthChecks(
+  db: Database,
+  opts: SqliteHealthOpts = {},
+): SqliteHealthCheck[] {
+  const maxSizeBytes = opts.maxSizeBytes ?? 500 * BYTES_PER_MB;
+  const maxWalPages = opts.maxWalPages ?? 1000;
+
+  return [
+    {
+      name: 'sqlite:integrity',
+      description: 'SQLite quick_check integrity',
+      async check() {
+        const row = db.query<Record<string, string>, []>('PRAGMA quick_check').get();
+        const outcome = row ? Object.values(row)[0] : undefined;
+        return outcome === 'ok'
+          ? { status: 'ok', message: 'ok' }
+          : { status: 'error', message: outcome ?? 'unknown' };
+      },
+    },
+    {
+      name: 'sqlite:size',
+      description: 'DB file size within threshold',
+      async check() {
+        const info = db
+          .query<{ page_count: number; page_size: number }, []>(
+            'SELECT page_count, page_size FROM pragma_page_count(), pragma_page_size()',
+          )
+          .get();
+        const bytes = (info?.page_count ?? 0) * (info?.page_size ?? 4096);
+        return bytes > maxSizeBytes
+          ? { status: 'warn', message: `DB is ${mb(bytes)} (threshold: ${mb(maxSizeBytes)})` }
+          : { status: 'ok', message: mb(bytes) };
+      },
+    },
+    {
+      name: 'sqlite:wal',
+      description: 'WAL checkpoint lag',
+      async check() {
+        // PRAGMA wal_checkpoint returns one row {busy, log, checkpointed}; `log` is the
+        // total WAL pages, or -1 when the DB is not in WAL mode (treat as 0).
+        const row = db
+          .query<{ busy: number; log: number; checkpointed: number }, []>(
+            'PRAGMA wal_checkpoint(PASSIVE)',
+          )
+          .get();
+        const pages = row && row.log > 0 ? row.log : 0;
+        return pages > maxWalPages
+          ? { status: 'warn', message: `WAL has ${pages} pages (threshold: ${maxWalPages})` }
+          : { status: 'ok', message: `${pages} WAL pages` };
+      },
+    },
+  ];
+}