@jacebenson/jsn 3.2.0 → 3.3.0

package/src/commands/docs/refresh.js

@@ -0,0 +1,135 @@
+// Incremental refresh: sync docs.db to the current state of the markdown folder
+// after a ServiceNow docs update (e.g. `git pull` in the docs repo).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import matter from 'gray-matter';
+import { openDocsDb, closeDocsDb, getDocsDbPath } from './db.js';
+import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
+
+export function refreshDocs(opts = {}) {
+  const docsDir = opts.docsDir;
+  const dbPath = opts.dbPath || getDocsDbPath();
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first for the initial build.`);
+  }
+  if (!fs.existsSync(docsDir)) {
+    throw new Error(`Docs directory not found: ${docsDir}`);
+  }
+
+  const db = openDocsDb({ dbPath });
+  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 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 = ?');
+
+  function* walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) yield* walk(full);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) yield full;
+    }
+  }
+
+  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 = [...walk(docsDir)];
+
+  db.exec('BEGIN');
+  for (const file of files) {
+    try {
+      const rel = path.relative(docsDir, file).split(path.sep).join('/');
+      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 = matter(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`);
+    }
+  }
+
+  for (const [rel, row] of existing) {
+    if (!seen.has(rel)) {
+      del.run(row.id);
+      removed++;
+    }
+  }
+  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);
+
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+  return { added, updated, removed, unchanged, errors, secs, dbPath, embeddingsEnabled };
+}

package/src/commands/docs/search.js

@@ -0,0 +1,139 @@
+// CLI search against the docs SQLite database.
+
+import fs from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { getDocsDbPath, hasEmbeddings } from './db.js';
+import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
+
+function safeParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+export function searchDocs(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  const q = (opts.query || '').toString().trim();
+  if (!q) {
+    throw new Error('Query is required.');
+  }
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
+  }
+
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  const limit = Math.min(parseInt(opts.limit, 10) || 20, 100);
+  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 ') : '';
+
+  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 = [];
+    } else {
+      const hrrDim = (() => {
+        try {
+          const row = db.prepare("SELECT value FROM meta WHERE key='hrr_dim'").get();
+          return row ? parseInt(row.value, 10) : DEFAULT_DIM;
+        } catch {
+          return 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;
+      }
+
+      candidates.sort((a, b) => b.score - a.score);
+      rows = candidates.slice(offset, offset + limit);
+    }
+  }
+
+  db.close();
+
+  // 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',
+    count: rows.length,
+    results: rows,
+  };
+}

package/src/commands/docs/serve.js

@@ -0,0 +1,278 @@
+// Built-in HTTP server for docs search (node:http only, no Express).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { URL } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import { getDocsDbPath, hasEmbeddings } from './db.js';
+import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
+
+const PUBLIC_DIR = path.join(import.meta.dirname, 'public');
+
+function safeParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+function sendJSON(res, status, obj) {
+  const body = JSON.stringify(obj, null, 2);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function sendText(res, status, text, type = 'text/plain') {
+  res.writeHead(status, {
+    'Content-Type': type,
+    'Content-Length': Buffer.byteLength(text),
+  });
+  res.end(text);
+}
+
+function serveStatic(req, res, filePath) {
+  if (!fs.existsSync(filePath)) {
+    sendText(res, 404, 'Not found');
+    return;
+  }
+  const stat = fs.statSync(filePath);
+  if (stat.isDirectory()) {
+    sendText(res, 403, 'Forbidden');
+    return;
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  const mime = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+  }[ext] || 'application/octet-stream';
+
+  res.writeHead(200, {
+    'Content-Type': mime,
+    'Content-Length': stat.size,
+  });
+  fs.createReadStream(filePath).pipe(res);
+}
+
+export function serveDocs(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  const port = parseInt(opts.port, 10) || 3000;
+  const host = opts.host || '127.0.0.1';
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
+  }
+
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  const hasEmb = hasEmbeddings(db);
+  const hrrDim = (() => {
+    try {
+      const row = db.prepare("SELECT value FROM meta WHERE key='hrr_dim'").get();
+      return row ? parseInt(row.value, 10) : DEFAULT_DIM;
+    } catch {
+      return DEFAULT_DIM;
+    }
+  })();
+
+  const server = http.createServer((req, res) => {
+    try {
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+      const pathname = decodeURIComponent(url.pathname);
+
+      if (pathname === '/health') {
+        return sendJSON(res, 200, { ok: true });
+      }
+
+      if (pathname === '/stats') {
+        const total = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
+        return sendJSON(res, 200, { documents: total, db: path.resolve(dbPath), embeddings: hasEmb, hrr_dim: hrrDim });
+      }
+
+      if (pathname === '/bundles') {
+        const rows = db
+          .prepare('SELECT bundle, COUNT(*) AS count FROM docs WHERE bundle IS NOT NULL GROUP BY bundle ORDER BY count DESC')
+          .all();
+        return sendJSON(res, 200, rows);
+      }
+
+      if (pathname === '/search') {
+        const q = (url.searchParams.get('q') || '').trim();
+        if (!q) return sendJSON(res, 400, { error: "Missing query parameter 'q'." });
+
+        const limit = Math.min(parseInt(url.searchParams.get('limit'), 10) || 20, 100);
+        const offset = parseInt(url.searchParams.get('offset'), 10) || 0;
+        const bundle = url.searchParams.get('bundle') || null;
+        const docType = url.searchParams.get('doc_type') || null;
+        let mode = (url.searchParams.get('mode') || (hasEmb ? 'hybrid' : 'keyword')).toString();
+        if (mode === 'hybrid' && !hasEmb) mode = 'keyword';
+
+        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 ') : '';
+
+        try {
+          if (mode === 'keyword') {
+            const 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);
+            return sendJSON(res, 200, { query: q, mode, count: rows.length, results: rows });
+          }
+
+          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) {
+            return sendJSON(res, 200, { query: q, mode, count: 0, results: [] });
+          }
+
+          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;
+          }
+
+          candidates.sort((a, b) => b.score - a.score);
+          const results = candidates.slice(offset, offset + limit);
+          return sendJSON(res, 200, { query: q, mode, count: results.length, results });
+        } catch (err) {
+          return sendJSON(res, 400, { error: `Invalid FTS query: ${err.message}` });
+        }
+      }
+
+      if (pathname.startsWith('/doc/')) {
+        const id = pathname.slice(5);
+        if (!id) return sendJSON(res, 400, { error: "Missing 'id'." });
+        const row = db.prepare('SELECT * FROM docs WHERE id = ?').get(id);
+        if (!row) return sendJSON(res, 404, { error: 'Not found' });
+        row.frontmatter = safeParse(row.frontmatter);
+        return sendJSON(res, 200, row);
+      }
+
+      if (pathname === '/doc') {
+        const p = url.searchParams.get('path') || '';
+        if (!p) return sendJSON(res, 400, { error: "Missing 'path'." });
+        const row = db.prepare('SELECT * FROM docs WHERE path = ?').get(p);
+        if (!row) return sendJSON(res, 404, { error: 'Not found' });
+        row.frontmatter = safeParse(row.frontmatter);
+        return sendJSON(res, 200, row);
+      }
+
+      // Static files.
+      let filePath = path.join(PUBLIC_DIR, pathname === '/' ? 'index.html' : pathname);
+      // Security: prevent escaping public dir.
+      filePath = path.resolve(filePath);
+      const publicResolved = path.resolve(PUBLIC_DIR);
+      if (!filePath.startsWith(publicResolved + path.sep) && filePath !== publicResolved) {
+        return sendText(res, 403, 'Forbidden');
+      }
+      return serveStatic(req, res, filePath);
+    } catch (err) {
+      sendJSON(res, 500, { error: err.message });
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    let currentPort = parseInt(port, 10);
+    const maxAttempts = 10;
+    let attempts = 0;
+    let resolved = false;
+
+    function onListening() {
+      if (resolved) return;
+      resolved = true;
+      server.removeListener('error', onError);
+      process.stderr.write(`ServiceNow docs search listening on http://${host}:${currentPort}\n`);
+      resolve({ server, port: currentPort, host, dbPath });
+    }
+
+    function onError(err) {
+      if (resolved) return;
+      server.removeListener('listening', onListening);
+      if (err.code === 'EADDRINUSE' && attempts < maxAttempts) {
+        process.stderr.write(`Port ${currentPort} in use, trying ${currentPort + 1}...\n`);
+        currentPort++;
+        tryListen();
+        return;
+      }
+      if (err.code === 'EADDRINUSE') {
+        err.message = `Could not find an open port between ${port} and ${currentPort}. Try specifying one with --port.`;
+      }
+      resolved = true;
+      reject(err);
+    }
+
+    function tryListen() {
+      attempts++;
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(currentPort, host);
+    }
+
+    tryListen();
+  });
+}

package/src/commands/docs/sync.js

@@ -0,0 +1,75 @@
+// Clone or update the ServiceNow docs repo locally.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getDocsSourceDir, getDocsSourceMarkdownDir, getDocsDbPath, docsDbExists } from './db.js';
+import { ingestDocs } from './ingest.js';
+import { refreshDocs } from './refresh.js';
+
+const REPO_URL = 'https://github.com/ServiceNow/ServiceNowDocs';
+const BRANCH = 'australia';
+
+function git(args, cwd, stdio = 'inherit') {
+  const r = spawnSync('git', args, { cwd, stdio });
+  if (r.status !== 0) {
+    throw new Error(`git ${args[0]} failed (exit ${r.status}).`);
+  }
+}
+
+export function syncDocs(opts = {}) {
+  const repoDir = opts.repoDir || getDocsSourceDir();
+  const markdownDir = opts.markdownDir || getDocsSourceMarkdownDir();
+  const dbPath = opts.dbPath || getDocsDbPath();
+  const embed = opts.embed !== false;
+  const noIngest = opts.noIngest === true;
+
+  const initialStatus = {
+    clone: !fs.existsSync(path.join(repoDir, '.git')),
+    docsApprox: 45000,
+    willEmbed: embed && noIngest === false,
+    minutesHint: embed ? 3 : 1,
+  };
+
+  process.stderr.write('Note: docs sync downloads ~45k markdown files and builds an FTS5 + HRR index. ');
+  process.stderr.write(`This normally takes ${initialStatus.minutesHint}-${initialStatus.minutesHint + 2} minutes.\n`);
+  if (initialStatus.willEmbed) {
+    process.stderr.write('Pass --no-embed to skip semantic embeddings and finish faster.\n');
+  }
+  process.stderr.write('\n');
+
+  if (!initialStatus.clone) {
+    process.stderr.write(`Updating existing clone at ${repoDir} ...\n`);
+    git(['-C', repoDir, 'pull', '--ff-only'], repoDir, 'inherit');
+  } else {
+    fs.mkdirSync(path.dirname(repoDir), { recursive: true });
+    process.stderr.write(`Cloning ${REPO_URL} (branch ${BRANCH}) into ${repoDir} ...\n`);
+    git([
+      'clone',
+      '--depth', '1',
+      '--branch', BRANCH,
+      '--config', 'core.longpaths=true',
+      REPO_URL,
+      repoDir,
+    ], undefined, 'inherit');
+  }
+
+  if (!fs.existsSync(markdownDir)) {
+    throw new Error(`Expected markdown folder not found at ${markdownDir}.`);
+  }
+
+  if (noIngest) {
+    return { repoDir, markdownDir, dbPath, ingested: false, note: 'Run without --no-ingest to build the index.' };
+  }
+
+  // If the DB already exists, use incremental refresh. Otherwise, full ingest.
+  if (docsDbExists()) {
+    process.stderr.write(`Docs DB found — running incremental refresh...\n`);
+    const result = refreshDocs({ docsDir: markdownDir, dbPath });
+    return { repoDir, markdownDir, dbPath, ingested: true, incremental: true, ...result };
+  }
+
+  process.stderr.write('No existing DB — running full ingest...\n');
+  const result = ingestDocs({ docsDir: markdownDir, dbPath, embed });
+  return { repoDir, markdownDir, dbPath, ingested: true, incremental: false, ...result };
+}

package/suppress-warnings.cjs

@@ -0,0 +1,13 @@
+// Suppresses the node:sqlite ExperimentalWarning on Node 22.x.
+// Loaded via NODE_OPTIONS=--require before the main ESM entry point.
+
+const original = process.emitWarning;
+process.emitWarning = function emitWarning(warning, ...args) {
+  const message = typeof warning === 'string'
+    ? warning
+    : (warning?.message || '');
+  if (message.includes('SQLite')) {
+    return;
+  }
+  return original.apply(this, [warning, ...args]);
+};