@jacebenson/jsn 4.3.10-dev.67 → 4.3.11-dev.68

package/src/commands/docs/ingest.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { openDocsDb, closeDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function ingestDocs(opts = {}) {
@@ -14,69 +14,69 @@ export function ingestDocs(opts = {}) {
   // Fresh build each run.
   if (fs.existsSync(dbPath)) fs.rmSync(dbPath);
 
-  const db = openDocsDb({ dbPath });
-  initDocsSchema(db);
+  return withDocsDb({ dbPath }, (db) => {
+    initDocsSchema(db);
 
-  const insert = db.prepare(`
-    INSERT INTO docs (path, title, release, bundle, doc_type, locale, frontmatter, body, size, mtime, hash, hrr_vector)
-    VALUES (@path, @title, @release, @bundle, @doc_type, @locale, @frontmatter, @body, @size, @mtime, @hash, @hrr_vector)
-  `);
+    const insert = db.prepare(`
+      INSERT INTO docs (path, title, release, bundle, doc_type, locale, frontmatter, body, size, mtime, hash, hrr_vector)
+      VALUES (@path, @title, @release, @bundle, @doc_type, @locale, @frontmatter, @body, @size, @mtime, @hash, @hrr_vector)
+    `);
 
-  let count = 0;
-  let errors = 0;
-  const startedAt = Date.now();
+    let count = 0;
+    let errors = 0;
+    const startedAt = Date.now();
 
-  db.exec('BEGIN');
-  for (const { file, rel } of walkDocs(roots)) {
-    try {
-      const stat = fs.statSync(file);
-      const raw = fs.readFileSync(file, 'utf8');
-      const hash = createHash('sha256').update(raw).digest('hex');
-      let data = {};
-      let body = raw;
+    db.exec('BEGIN');
+    for (const { file, rel } of walkDocs(roots)) {
       try {
-        const parsed = parseFrontmatter(raw);
-        data = parsed.data || {};
-        body = parsed.content || '';
-      } catch {
-        // Malformed frontmatter: keep raw body, empty metadata.
+        const stat = fs.statSync(file);
+        const raw = fs.readFileSync(file, 'utf8');
+        const hash = createHash('sha256').update(raw).digest('hex');
+        let data = {};
+        let body = raw;
+        try {
+          const parsed = parseFrontmatter(raw);
+          data = parsed.data || {};
+          body = parsed.content || '';
+        } catch {
+          // Malformed frontmatter: keep raw body, empty metadata.
+        }
+        const hrr = embed
+          ? phasesToBytes(encodeText(docSurface(data.title ?? null, body), DEFAULT_DIM))
+          : null;
+        insert.run({
+          path: rel,
+          title: data.title ?? null,
+          release: data.release ?? null,
+          bundle: data.bundle ?? null,
+          doc_type: data.doc_type ?? null,
+          locale: data.locale ?? null,
+          frontmatter: JSON.stringify(data),
+          body,
+          size: stat.size,
+          mtime: Math.floor(stat.mtimeMs),
+          hash,
+          hrr_vector: hrr,
+        });
+        count++;
+        if (count % 5000 === 0) {
+          process.stderr.write(`  ...${count} files\n`);
+        }
+      } catch (err) {
+        errors++;
+        if (errors <= 10) process.stderr.write(`Skipped ${file}: ${err.message}\n`);
       }
-      const hrr = embed
-        ? phasesToBytes(encodeText(docSurface(data.title ?? null, body), DEFAULT_DIM))
-        : null;
-      insert.run({
-        path: rel,
-        title: data.title ?? null,
-        release: data.release ?? null,
-        bundle: data.bundle ?? null,
-        doc_type: data.doc_type ?? null,
-        locale: data.locale ?? null,
-        frontmatter: JSON.stringify(data),
-        body,
-        size: stat.size,
-        mtime: Math.floor(stat.mtimeMs),
-        hash,
-        hrr_vector: hrr,
-      });
-      count++;
-      if (count % 5000 === 0) {
-        process.stderr.write(`  ...${count} files\n`);
-      }
-    } catch (err) {
-      errors++;
-      if (errors <= 10) process.stderr.write(`Skipped ${file}: ${err.message}\n`);
     }
-  }
-  db.exec('COMMIT');
+    db.exec('COMMIT');
 
-  db.exec("INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
-  db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-  db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('hrr_dim', ?)").run(String(DEFAULT_DIM));
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('embeddings', ?)").run(String(embed));
-  closeDocsDb(db);
+    db.exec("INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('hrr_dim', ?)").run(String(DEFAULT_DIM));
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('embeddings', ?)").run(String(embed));
 
-  const secs = ((Date.now() - startedAt) / 1000).toFixed(1);
-  return { count, errors, secs, dbPath, embedded: embed };
+    const secs = ((Date.now() - startedAt) / 1000).toFixed(1);
+    return { count, errors, secs, dbPath, embedded: embed };
+  });
 }

package/src/commands/docs/refresh.js

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { openDocsDb, closeDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function refreshDocs(opts = {}) {
@@ -15,108 +15,108 @@ export function refreshDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first for the initial build.`);
   }
 
-  const db = openDocsDb({ dbPath });
-  db.exec('PRAGMA journal_mode = WAL');
+  return withDocsDb({ dbPath }, (db) => {
+    db.exec('PRAGMA journal_mode = WAL');
 
-  const cols = db.prepare('PRAGMA table_info(docs)').all().map((c) => c.name);
-  if (!cols.includes('hash')) db.exec('ALTER TABLE docs ADD COLUMN hash TEXT');
-  if (!cols.includes('hrr_vector')) db.exec('ALTER TABLE docs ADD COLUMN hrr_vector BLOB');
+    const cols = db.prepare('PRAGMA table_info(docs)').all().map((c) => c.name);
+    if (!cols.includes('hash')) db.exec('ALTER TABLE docs ADD COLUMN hash TEXT');
+    if (!cols.includes('hrr_vector')) db.exec('ALTER TABLE docs ADD COLUMN hrr_vector BLOB');
 
-  const embeddingsEnabled =
-    db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n > 0 ||
-    !cols.includes('hrr_vector');
+    const embeddingsEnabled =
+      db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n > 0 ||
+      !cols.includes('hrr_vector');
 
-  const isBackfill = db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hash IS NOT NULL').get().n === 0
-    && db.prepare('SELECT COUNT(*) AS n FROM docs').get().n > 0;
-  const setHash = db.prepare('UPDATE docs SET hash = ? WHERE id = ?');
+    const isBackfill = db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hash IS NOT NULL').get().n === 0
+      && db.prepare('SELECT COUNT(*) AS n FROM docs').get().n > 0;
+    const setHash = db.prepare('UPDATE docs SET hash = ? WHERE id = ?');
 
-  const existing = new Map();
-  for (const row of db.prepare('SELECT id, path, hash FROM docs').all()) {
-    existing.set(row.path, { id: row.id, hash: row.hash });
-  }
+    const existing = new Map();
+    for (const row of db.prepare('SELECT id, path, hash FROM docs').all()) {
+      existing.set(row.path, { id: row.id, hash: row.hash });
+    }
 
-  const upsert = db.prepare(`
-    INSERT INTO docs (path, title, release, bundle, doc_type, locale, frontmatter, body, size, mtime, hash, hrr_vector)
-    VALUES (@path, @title, @release, @bundle, @doc_type, @locale, @frontmatter, @body, @size, @mtime, @hash, @hrr_vector)
-    ON CONFLICT(path) DO UPDATE SET
-      title=@title, release=@release, bundle=@bundle, doc_type=@doc_type, locale=@locale,
-      frontmatter=@frontmatter, body=@body, size=@size, mtime=@mtime, hash=@hash, hrr_vector=@hrr_vector
-  `);
-  const del = db.prepare('DELETE FROM docs WHERE id = ?');
-
-  let added = 0, updated = 0, removed = 0, unchanged = 0, errors = 0;
-  const seen = new Set();
-  const started = Date.now();
-
-  const files = [...walkDocs(roots)];
-
-  db.exec('BEGIN');
-  for (const { file, rel } of files) {
-    try {
-      seen.add(rel);
-      const raw = fs.readFileSync(file, 'utf8');
-      const hash = createHash('sha256').update(raw).digest('hex');
-
-      const prev = existing.get(rel);
-      if (prev && prev.hash === hash) {
-        unchanged++;
-        continue;
-      }
+    const upsert = db.prepare(`
+      INSERT INTO docs (path, title, release, bundle, doc_type, locale, frontmatter, body, size, mtime, hash, hrr_vector)
+      VALUES (@path, @title, @release, @bundle, @doc_type, @locale, @frontmatter, @body, @size, @mtime, @hash, @hrr_vector)
+      ON CONFLICT(path) DO UPDATE SET
+        title=@title, release=@release, bundle=@bundle, doc_type=@doc_type, locale=@locale,
+        frontmatter=@frontmatter, body=@body, size=@size, mtime=@mtime, hash=@hash, hrr_vector=@hrr_vector
+    `);
+    const del = db.prepare('DELETE FROM docs WHERE id = ?');
 
-      if (isBackfill && prev) {
-        setHash.run(hash, prev.id);
-        unchanged++;
-        continue;
-      }
+    let added = 0, updated = 0, removed = 0, unchanged = 0, errors = 0;
+    const seen = new Set();
+    const started = Date.now();
+
+    const files = [...walkDocs(roots)];
 
-      const stat = fs.statSync(file);
-      let data = {}, body = raw;
+    db.exec('BEGIN');
+    for (const { file, rel } of files) {
       try {
-        const parsed = parseFrontmatter(raw);
-        data = parsed.data || {};
-        body = parsed.content || '';
-      } catch {
-        // keep raw body on malformed frontmatter
+        seen.add(rel);
+        const raw = fs.readFileSync(file, 'utf8');
+        const hash = createHash('sha256').update(raw).digest('hex');
+
+        const prev = existing.get(rel);
+        if (prev && prev.hash === hash) {
+          unchanged++;
+          continue;
+        }
+
+        if (isBackfill && prev) {
+          setHash.run(hash, prev.id);
+          unchanged++;
+          continue;
+        }
+
+        const stat = fs.statSync(file);
+        let data = {}, body = raw;
+        try {
+          const parsed = parseFrontmatter(raw);
+          data = parsed.data || {};
+          body = parsed.content || '';
+        } catch {
+          // keep raw body on malformed frontmatter
+        }
+
+        const hrr = embeddingsEnabled
+          ? phasesToBytes(encodeText(docSurface(data.title ?? null, body), DEFAULT_DIM))
+          : null;
+
+        upsert.run({
+          path: rel,
+          title: data.title ?? null,
+          release: data.release ?? null,
+          bundle: data.bundle ?? null,
+          doc_type: data.doc_type ?? null,
+          locale: data.locale ?? null,
+          frontmatter: JSON.stringify(data),
+          body,
+          size: stat.size,
+          mtime: Math.floor(stat.mtimeMs),
+          hash,
+          hrr_vector: hrr,
+        });
+        if (prev) updated++; else added++;
+      } catch (err) {
+        errors++;
+        if (errors <= 10) process.stderr.write(`Skipped ${file}: ${err.message}\n`);
       }
-
-      const hrr = embeddingsEnabled
-        ? phasesToBytes(encodeText(docSurface(data.title ?? null, body), DEFAULT_DIM))
-        : null;
-
-      upsert.run({
-        path: rel,
-        title: data.title ?? null,
-        release: data.release ?? null,
-        bundle: data.bundle ?? null,
-        doc_type: data.doc_type ?? null,
-        locale: data.locale ?? null,
-        frontmatter: JSON.stringify(data),
-        body,
-        size: stat.size,
-        mtime: Math.floor(stat.mtimeMs),
-        hash,
-        hrr_vector: hrr,
-      });
-      if (prev) updated++; else added++;
-    } catch (err) {
-      errors++;
-      if (errors <= 10) process.stderr.write(`Skipped ${file}: ${err.message}\n`);
     }
-  }
 
-  for (const [rel, row] of existing) {
-    if (!seen.has(rel)) {
-      del.run(row.id);
-      removed++;
+    for (const [rel, row] of existing) {
+      if (!seen.has(rel)) {
+        del.run(row.id);
+        removed++;
+      }
     }
-  }
-  db.exec('COMMIT');
+    db.exec('COMMIT');
 
-  db.exec("INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
-  db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
-  closeDocsDb(db);
+    db.exec("INSERT INTO docs_fts(docs_fts) VALUES('optimize');");
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
 
-  const secs = ((Date.now() - started) / 1000).toFixed(1);
-  return { added, updated, removed, unchanged, errors, secs, dbPath, embeddingsEnabled };
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    return { added, updated, removed, unchanged, errors, secs, dbPath, embeddingsEnabled };
+  });
 }

package/src/commands/docs/search.js

@@ -1,7 +1,7 @@
 // CLI search against the docs SQLite database.
 
 import fs from 'node:fs';
-import { getDocsDbPath, hasEmbeddings, openDocsDb, closeDocsDb, getMeta } from './db.js';
+import { getDocsDbPath, hasEmbeddings, openDocsDb, closeDocsDb, withDocsDb, getMeta } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
 function safeParse(s) {
@@ -50,119 +50,119 @@ export function searchDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = openDocsDb({ dbPath });
-  const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
-  const offset = parseInt(opts.offset, 10) || 0;
-  const bundle = opts.bundle ? String(opts.bundle) : null;
-  const docType = opts.docType ? String(opts.docType) : null;
-  const mode = opts.mode === 'keyword' ? 'keyword' : 'hybrid';
-  const useHybrid = mode === 'hybrid' && hasEmbeddings(db);
-
-  const filters = [];
-  const params = { q, limit, offset };
-  if (bundle) {
-    filters.push('d.bundle = @bundle');
-    params.bundle = bundle;
-  }
-  if (docType) {
-    filters.push('d.doc_type = @docType');
-    params.docType = docType;
-  }
-  const where = filters.length ? ' AND ' + filters.join(' AND ') : '';
-
-  // Total matching docs (for pagination)
-  const total = db
-    .prepare(`SELECT COUNT(*) AS n FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH @q${where}`)
-    .get({ q, ...(bundle && { bundle }), ...(docType && { docType }) }).n;
-
-  let rows;
-  if (!useHybrid) {
-    rows = db
-      .prepare(
-        `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release,
-                json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
-                snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
-                bm25(docs_fts) AS score
-         FROM docs_fts
-         JOIN docs d ON d.id = docs_fts.rowid
-         WHERE docs_fts MATCH @q${where}
-         ORDER BY score
-         LIMIT @limit OFFSET @offset`
-      )
-      .all(params);
-  } else {
-    const candParams = { q, cand: (limit + offset) * 4 + 20 };
-    if (bundle) candParams.bundle = bundle;
-    if (docType) candParams.docType = docType;
-    const candidates = db
-      .prepare(
-        `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release, d.hrr_vector,
-                json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
-                snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
-                bm25(docs_fts) AS bm25
-         FROM docs_fts
-         JOIN docs d ON d.id = docs_fts.rowid
-         WHERE docs_fts MATCH @q${where}
-         ORDER BY bm25
-         LIMIT @cand`
-      )
-      .all(candParams);
-
-    if (candidates.length === 0) {
-      rows = [];
+  return withDocsDb({ dbPath }, (db) => {
+    const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
+    const offset = parseInt(opts.offset, 10) || 0;
+    const bundle = opts.bundle ? String(opts.bundle) : null;
+    const docType = opts.docType ? String(opts.docType) : null;
+    const mode = opts.mode === 'keyword' ? 'keyword' : 'hybrid';
+    const useHybrid = mode === 'hybrid' && hasEmbeddings(db);
+
+    const filters = [];
+    const params = { q, limit, offset };
+    if (bundle) {
+      filters.push('d.bundle = @bundle');
+      params.bundle = bundle;
+    }
+    if (docType) {
+      filters.push('d.doc_type = @docType');
+      params.docType = docType;
+    }
+    const where = filters.length ? ' AND ' + filters.join(' AND ') : '';
+
+    // Total matching docs (for pagination)
+    const total = db
+      .prepare(`SELECT COUNT(*) AS n FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH @q${where}`)
+      .get({ q, ...(bundle && { bundle }), ...(docType && { docType }) }).n;
+
+    let rows;
+    if (!useHybrid) {
+      rows = db
+        .prepare(
+          `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release,
+                  json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
+                  snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
+                  bm25(docs_fts) AS score
+           FROM docs_fts
+           JOIN docs d ON d.id = docs_fts.rowid
+           WHERE docs_fts MATCH @q${where}
+           ORDER BY score
+           LIMIT @limit OFFSET @offset`
+        )
+        .all(params);
     } else {
-      const hrrDim = (() => {
-        const value = getMeta(db, 'hrr_dim');
-        const n = parseInt(value, 10);
-        return Number.isInteger(n) ? n : DEFAULT_DIM;
-      })();
-      const queryVec = encodeText(q, hrrDim);
-      const queryTokens = new Set(q.toLowerCase().split(/\s+/).filter(Boolean));
-
-      const bmVals = candidates.map((c) => c.bm25);
-      const bmMin = Math.min(...bmVals);
-      const bmMax = Math.max(...bmVals);
-      const bmRange = bmMax - bmMin || 1;
-
-      const FTS_W = 0.4, JACCARD_W = 0.3, HRR_W = 0.3;
-
-      for (const c of candidates) {
-        const ftsScore = 1 - (c.bm25 - bmMin) / bmRange;
-        const contentTokens = new Set(
-          `${c.title || ''} ${c.path || ''}`.toLowerCase().split(/\s+/).filter(Boolean)
-        );
-        let inter = 0;
-        for (const t of queryTokens) if (contentTokens.has(t)) inter++;
-        const union = queryTokens.size + contentTokens.size - inter;
-        const jaccard = union ? inter / union : 0;
-
-        let hrrSim = 0.5;
-        if (c.hrr_vector) {
-          hrrSim = (similarity(queryVec, bytesToPhases(c.hrr_vector)) + 1) / 2;
+      const candParams = { q, cand: (limit + offset) * 4 + 20 };
+      if (bundle) candParams.bundle = bundle;
+      if (docType) candParams.docType = docType;
+      const candidates = db
+        .prepare(
+          `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release, d.hrr_vector,
+                  json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
+                  snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
+                  bm25(docs_fts) AS bm25
+           FROM docs_fts
+           JOIN docs d ON d.id = docs_fts.rowid
+           WHERE docs_fts MATCH @q${where}
+           ORDER BY bm25
+           LIMIT @cand`
+        )
+        .all(candParams);
+
+      if (candidates.length === 0) {
+        rows = [];
+      } else {
+        const hrrDim = (() => {
+          const value = getMeta(db, 'hrr_dim');
+          const n = parseInt(value, 10);
+          return Number.isInteger(n) ? n : DEFAULT_DIM;
+        })();
+        const queryVec = encodeText(q, hrrDim);
+        const queryTokens = new Set(q.toLowerCase().split(/\s+/).filter(Boolean));
+
+        const bmVals = candidates.map((c) => c.bm25);
+        const bmMin = Math.min(...bmVals);
+        const bmMax = Math.max(...bmVals);
+        const bmRange = bmMax - bmMin || 1;
+
+        const FTS_W = 0.4, JACCARD_W = 0.3, HRR_W = 0.3;
+
+        for (const c of candidates) {
+          const ftsScore = 1 - (c.bm25 - bmMin) / bmRange;
+          const contentTokens = new Set(
+            `${c.title || ''} ${c.path || ''}`.toLowerCase().split(/\s+/).filter(Boolean)
+          );
+          let inter = 0;
+          for (const t of queryTokens) if (contentTokens.has(t)) inter++;
+          const union = queryTokens.size + contentTokens.size - inter;
+          const jaccard = union ? inter / union : 0;
+
+          let hrrSim = 0.5;
+          if (c.hrr_vector) {
+            hrrSim = (similarity(queryVec, bytesToPhases(c.hrr_vector)) + 1) / 2;
+          }
+
+          c.score = FTS_W * ftsScore + JACCARD_W * jaccard + HRR_W * hrrSim;
+          delete c.hrr_vector;
+          delete c.bm25;
         }
 
-        c.score = FTS_W * ftsScore + JACCARD_W * jaccard + HRR_W * hrrSim;
-        delete c.hrr_vector;
-        delete c.bm25;
+        candidates.sort((a, b) => b.score - a.score);
+        rows = candidates.slice(offset, offset + limit);
       }
-
-      candidates.sort((a, b) => b.score - a.score);
-      rows = candidates.slice(offset, offset + limit);
     }
-  }
 
-  closeDocsDb(db);
 
-  // Post-process canonical_url JSON strings that may contain escaped content.
-  for (const row of rows) {
-    if (row.canonical_url) row.canonical_url = safeParse(row.canonical_url) || row.canonical_url;
-  }
+    // Post-process canonical_url JSON strings that may contain escaped content.
+    for (const row of rows) {
+      if (row.canonical_url) row.canonical_url = safeParse(row.canonical_url) || row.canonical_url;
+    }
 
-  return {
-    query: q,
-    mode: useHybrid ? 'hybrid' : 'keyword',
-    total,
-    count: rows.length,
-    results: rows,
-  };
+    return {
+      query: q,
+      mode: useHybrid ? 'hybrid' : 'keyword',
+      total,
+      count: rows.length,
+      results: rows,
+    };
+  });
 }

package/src/commands/docs/serve.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import http from 'node:http';
 import { URL } from 'node:url';
 import Database from 'better-sqlite3';
-import { getDocsDbPath, hasEmbeddings } from './db.js';
+import { getDocsDbPath, hasEmbeddings, closeDocsDb } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
 const PUBLIC_DIR = path.join(import.meta.dirname, 'public');
@@ -236,6 +236,8 @@ export function serveDocs(opts = {}) {
     }
   });
 
+  server.once('close', () => closeDocsDb(db));
+
   return new Promise((resolve, reject) => {
     let currentPort = parseInt(port, 10);
     const maxAttempts = 10;
@@ -263,6 +265,7 @@ export function serveDocs(opts = {}) {
         err.message = `Could not find an open port between ${port} and ${currentPort}. Try specifying one with --port.`;
       }
       resolved = true;
+      closeDocsDb(db);
       reject(err);
     }