akm-cli 0.0.20 → 0.0.22

package/dist/db.js

@@ -46,7 +46,9 @@ export function isVecAvailable(db) {
 }
 const VEC_DOCS_URL = "https://github.com/itlackey/agentikit/blob/main/docs/configuration.md#sqlite-vec-extension";
 const VEC_FALLBACK_THRESHOLD = 10_000;
-let vecInitWarned = false;
+// Per-database warning state: tracks which databases have already emitted the
+// vec-missing warning so we don't spam on every openDatabase() call.
+const vecInitWarnedDbs = new WeakSet();
 /**
  * Warn if sqlite-vec is unavailable and embedding count exceeds threshold.
  * Called from openDatabase (once at init) and from indexer (each run).
@@ -54,7 +56,7 @@ let vecInitWarned = false;
 export function warnIfVecMissing(db, { once } = { once: false }) {
     if (isVecAvailable(db))
         return;
-    if (once && vecInitWarned)
+    if (once && vecInitWarnedDbs.has(db))
         return;
     try {
         const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
@@ -62,7 +64,7 @@ export function warnIfVecMissing(db, { once } = { once: false }) {
         if (count >= VEC_FALLBACK_THRESHOLD) {
             warn("Semantic search is using JS fallback for %d entries. Install sqlite-vec for faster performance.\n  See: %s", count, VEC_DOCS_URL);
             if (once)
-                vecInitWarned = true;
+                vecInitWarnedDbs.add(db);
         }
     }
     catch {
@@ -104,6 +106,12 @@ function ensureSchema(db, embeddingDim) {
     CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
     CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
   `);
+    // Set version immediately after table creation so a crash before the end of
+    // ensureSchema() does not leave the database in a versionless state on next open.
+    const versionAfterCreate = getMeta(db, "version");
+    if (!versionAfterCreate) {
+        setMeta(db, "version", String(DB_VERSION));
+    }
     // BLOB-based embedding storage (always available, no sqlite-vec needed)
     db.exec(`
     CREATE TABLE IF NOT EXISTS embeddings (
@@ -134,9 +142,20 @@ function ensureSchema(db, embeddingDim) {
             catch {
                 /* ignore */
             }
+            // CR-2: Delete stale BLOB embeddings so they don't produce silently wrong
+            // similarity scores against the new-dimension vec table.
+            try {
+                db.exec("DELETE FROM embeddings");
+            }
+            catch {
+                /* ignore */
+            }
         }
         const vecExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'").get();
         if (!vecExists) {
+            if (!Number.isInteger(embeddingDim) || embeddingDim <= 0 || embeddingDim > 4096) {
+                throw new Error(`Invalid embedding dimension: ${embeddingDim}`);
+            }
             db.exec(`
         CREATE VIRTUAL TABLE entries_vec USING vec0(
           id       INTEGER PRIMARY KEY,
@@ -146,11 +165,6 @@ function ensureSchema(db, embeddingDim) {
         }
         setMeta(db, "embeddingDim", String(embeddingDim));
     }
-    // Set version if not present
-    const version = getMeta(db, "version");
-    if (!version) {
-        setMeta(db, "version", String(DB_VERSION));
-    }
 }
 // ── Meta helpers ────────────────────────────────────────────────────────────
 export function getMeta(db, key) {
@@ -161,6 +175,13 @@ export function setMeta(db, key, value) {
     db.prepare("INSERT OR REPLACE INTO index_meta (key, value) VALUES (?, ?)").run(key, value);
 }
 // ── Entry operations ────────────────────────────────────────────────────────
+/**
+ * Insert or update an entry in the `entries` table. Returns the row id.
+ *
+ * **Important:** This does not update the FTS index. Callers must call
+ * `rebuildFts()` after all upserts are complete for full-text search to
+ * reflect the changes.
+ */
 export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, searchText) {
     const stmt = db.prepare(`
     INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
@@ -176,29 +197,50 @@ export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, se
     stmt.run(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type);
     // Fetch the row id explicitly since last_insert_rowid() is unreliable for ON CONFLICT DO UPDATE
     const row = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(entryKey);
+    if (!row)
+        throw new Error("upsertEntry: entry_key not found after upsert");
     return row.id;
 }
 export function deleteEntriesByDir(db, dirPath) {
-    const ids = db.prepare("SELECT id FROM entries WHERE dir_path = ?").all(dirPath);
-    deleteRelatedRows(db, ids);
-    db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
+    db.transaction(() => {
+        const ids = db.prepare("SELECT id FROM entries WHERE dir_path = ?").all(dirPath);
+        deleteRelatedRows(db, ids);
+        db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
+    })();
 }
 export function deleteEntriesByStashDir(db, stashDir) {
-    const ids = db.prepare("SELECT id FROM entries WHERE stash_dir = ?").all(stashDir);
-    deleteRelatedRows(db, ids);
-    db.prepare("DELETE FROM entries WHERE stash_dir = ?").run(stashDir);
+    db.transaction(() => {
+        const ids = db.prepare("SELECT id FROM entries WHERE stash_dir = ?").all(stashDir);
+        deleteRelatedRows(db, ids);
+        db.prepare("DELETE FROM entries WHERE stash_dir = ?").run(stashDir);
+    })();
 }
+const SQLITE_CHUNK_SIZE = 500;
 function deleteRelatedRows(db, ids) {
-    for (const { id } of ids) {
+    if (ids.length === 0)
+        return;
+    const numericIds = ids.map((r) => r.id);
+    const vecAvail = isVecAvailable(db);
+    // Process in chunks to stay within SQLITE_MAX_VARIABLE_NUMBER
+    for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
         try {
-            db.prepare("DELETE FROM embeddings WHERE id = ?").run(id);
+            db.prepare(`DELETE FROM embeddings WHERE id IN (${placeholders})`).run(...chunk);
         }
         catch {
             /* ignore */
         }
-        if (isVecAvailable(db)) {
+        // HI-1: Also delete from FTS table so orphaned FTS rows don't remain
+        try {
+            db.prepare(`DELETE FROM entries_fts WHERE entry_id IN (${placeholders})`).run(...chunk);
+        }
+        catch {
+            /* ignore */
+        }
+        if (vecAvail) {
             try {
-                db.prepare("DELETE FROM entries_vec WHERE id = ?").run(id);
+                db.prepare(`DELETE FROM entries_vec WHERE id IN (${placeholders})`).run(...chunk);
             }
             catch {
                 /* ignore */
@@ -207,8 +249,14 @@ function deleteRelatedRows(db, ids) {
     }
 }
 export function rebuildFts(db) {
-    db.exec("DELETE FROM entries_fts");
-    db.exec("INSERT INTO entries_fts (entry_id, search_text) SELECT CAST(id AS TEXT), search_text FROM entries");
+    // CR-1: Wrap DELETE + INSERT in a single transaction so the FTS table is
+    // never left empty between the two statements if a crash occurs.
+    // HI-14: Store the integer id directly (FTS5 stores all content as text
+    // internally; the join in searchFts compares numerically without CAST).
+    db.transaction(() => {
+        db.exec("DELETE FROM entries_fts");
+        db.exec("INSERT INTO entries_fts (entry_id, search_text) SELECT id, search_text FROM entries");
+    })();
 }
 // ── Vector operations ───────────────────────────────────────────────────────
 export function upsertEmbedding(db, entryId, embedding) {
@@ -235,7 +283,9 @@ export function searchVec(db, queryEmbedding, k) {
                 .prepare("SELECT id, distance FROM entries_vec WHERE embedding MATCH ? AND k = ?")
                 .all(buf, k);
         }
-        catch {
+        catch (err) {
+            // MD-5: Log the failure so it's visible in diagnostics
+            console.warn("[db] searchVec (sqlite-vec path) failed:", err instanceof Error ? err.message : String(err));
             return [];
         }
     }
@@ -269,7 +319,9 @@ function searchBlobVec(db, queryEmbedding, k) {
             distance: Math.sqrt(2 * Math.max(0, 1 - similarity)),
         }));
     }
-    catch {
+    catch (err) {
+        // MD-5: Log the failure so it's visible in diagnostics
+        console.warn("[db] searchBlobVec (JS fallback) failed:", err instanceof Error ? err.message : String(err));
         return [];
     }
 }
@@ -280,12 +332,13 @@ export function searchFts(db, query, limit, entryType) {
         return [];
     let sql;
     let params;
+    // HI-14: Join on integer entry_id directly (no CAST needed; we store integer)
     if (entryType && entryType !== "any") {
         sql = `
       SELECT e.id, e.file_path AS filePath, e.entry_json, e.search_text AS searchText,
              bm25(entries_fts) AS bm25Score
       FROM entries_fts f
-      JOIN entries e ON e.id = CAST(f.entry_id AS INTEGER)
+      JOIN entries e ON e.id = f.entry_id
       WHERE entries_fts MATCH ?
         AND e.entry_type = ?
       ORDER BY bm25Score
@@ -298,7 +351,7 @@ export function searchFts(db, query, limit, entryType) {
       SELECT e.id, e.file_path AS filePath, e.entry_json, e.search_text AS searchText,
              bm25(entries_fts) AS bm25Score
       FROM entries_fts f
-      JOIN entries e ON e.id = CAST(f.entry_id AS INTEGER)
+      JOIN entries e ON e.id = f.entry_id
       WHERE entries_fts MATCH ?
       ORDER BY bm25Score
       LIMIT ?
@@ -307,13 +360,26 @@ export function searchFts(db, query, limit, entryType) {
     }
     try {
         const rows = db.prepare(sql).all(...params);
-        return rows.map((row) => ({
-            id: row.id,
-            filePath: row.filePath,
-            entry: JSON.parse(row.entry_json),
-            searchText: row.searchText,
-            bm25Score: row.bm25Score,
-        }));
+        // CR-6: Guard against corrupt JSON — skip the row rather than crashing
+        const results = [];
+        for (const row of rows) {
+            let entry;
+            try {
+                entry = JSON.parse(row.entry_json);
+            }
+            catch {
+                console.warn(`[db] searchFts: skipping entry id=${row.id} — corrupt entry_json`);
+                continue;
+            }
+            results.push({
+                id: row.id,
+                filePath: row.filePath,
+                entry,
+                searchText: row.searchText,
+                bm25Score: row.bm25Score,
+            });
+        }
+        return results;
     }
     catch {
         return [];
@@ -323,11 +389,13 @@ function sanitizeFtsQuery(query) {
     const tokens = query
         .replace(/[^a-zA-Z0-9\s]/g, " ")
         .split(/\s+/)
-        .filter((t) => t.length >= 1);
+        .filter((t) => t.length >= 2);
     if (tokens.length === 0)
         return "";
-    // Use unquoted tokens so the porter stemmer can normalize word forms
-    return tokens.join(" ");
+    // MD-1: Use OR so that any matching token returns results (better recall for
+    // exploratory search). Use unquoted tokens so the porter stemmer can
+    // normalize word forms.
+    return tokens.join(" OR ");
 }
 // ── All entries ─────────────────────────────────────────────────────────────
 export function getAllEntries(db, entryType) {
@@ -343,15 +411,28 @@ export function getAllEntries(db, entryType) {
         params = [];
     }
     const rows = db.prepare(sql).all(...params);
-    return rows.map((row) => ({
-        id: row.id,
-        entryKey: row.entry_key,
-        dirPath: row.dir_path,
-        filePath: row.file_path,
-        stashDir: row.stash_dir,
-        entry: JSON.parse(row.entry_json),
-        searchText: row.search_text,
-    }));
+    // CR-6: Guard against corrupt JSON — skip the row rather than crashing
+    const entries = [];
+    for (const row of rows) {
+        let entry;
+        try {
+            entry = JSON.parse(row.entry_json);
+        }
+        catch {
+            console.warn(`[db] getAllEntries: skipping entry id=${row.id} — corrupt entry_json`);
+            continue;
+        }
+        entries.push({
+            id: row.id,
+            entryKey: row.entry_key,
+            dirPath: row.dir_path,
+            filePath: row.file_path,
+            stashDir: row.stash_dir,
+            entry,
+            searchText: row.search_text,
+        });
+    }
+    return entries;
 }
 export function getEntryCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
@@ -361,19 +442,41 @@ export function getEntryById(db, id) {
     const row = db.prepare("SELECT file_path, entry_json FROM entries WHERE id = ?").get(id);
     if (!row)
         return undefined;
-    return { filePath: row.file_path, entry: JSON.parse(row.entry_json) };
+    // CR-6: Guard against corrupt JSON
+    let entry;
+    try {
+        entry = JSON.parse(row.entry_json);
+    }
+    catch {
+        console.warn(`[db] getEntryById: skipping entry id=${id} — corrupt entry_json`);
+        return undefined;
+    }
+    return { filePath: row.file_path, entry };
 }
 export function getEntriesByDir(db, dirPath) {
     const rows = db
         .prepare("SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries WHERE dir_path = ?")
         .all(dirPath);
-    return rows.map((row) => ({
-        id: row.id,
-        entryKey: row.entry_key,
-        dirPath: row.dir_path,
-        filePath: row.file_path,
-        stashDir: row.stash_dir,
-        entry: JSON.parse(row.entry_json),
-        searchText: row.search_text,
-    }));
+    // CR-6: Guard against corrupt JSON — skip the row rather than crashing
+    const entries = [];
+    for (const row of rows) {
+        let entry;
+        try {
+            entry = JSON.parse(row.entry_json);
+        }
+        catch {
+            console.warn(`[db] getEntriesByDir: skipping entry id=${row.id} — corrupt entry_json`);
+            continue;
+        }
+        entries.push({
+            id: row.id,
+            entryKey: row.entry_key,
+            dirPath: row.dir_path,
+            filePath: row.file_path,
+            stashDir: row.stash_dir,
+            entry,
+            searchText: row.search_text,
+        });
+    }
+    return entries;
 }

package/dist/embedder.js

@@ -1,22 +1,29 @@
 import { fetchWithTimeout } from "./common";
-let localEmbedder;
+import { warn } from "./warn";
+// Cache the promise itself (not the resolved result) so concurrent calls share
+// the same initialisation work and never download the model twice.
+let localEmbedderPromise;
 async function getLocalEmbedder() {
-    if (!localEmbedder) {
-        let pipeline;
-        try {
-            const mod = await import("@xenova/transformers");
-            pipeline = mod.pipeline;
-        }
-        catch {
-            throw new Error("Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers");
-        }
-        const pipelineFn = pipeline;
-        localEmbedder = await pipelineFn("feature-extraction", "Xenova/all-MiniLM-L6-v2");
-    }
-    if (!localEmbedder) {
-        throw new Error("Failed to initialize local embedder.");
+    if (!localEmbedderPromise) {
+        localEmbedderPromise = (async () => {
+            let pipeline;
+            try {
+                const mod = await import("@xenova/transformers");
+                pipeline = mod.pipeline;
+            }
+            catch {
+                throw new Error("Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers");
+            }
+            const pipelineFn = pipeline;
+            return pipelineFn("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+        })();
+        // HI-13: Clear the cached promise on failure so the next call retries
+        // instead of permanently rejecting every subsequent call with the same error.
+        localEmbedderPromise.catch(() => {
+            localEmbedderPromise = undefined;
+        });
     }
-    return localEmbedder;
+    return localEmbedderPromise;
 }
 async function embedLocal(text) {
     const model = await getLocalEmbedder();
@@ -111,13 +118,24 @@ async function embedRemoteBatch(texts, config) {
         if (!json.data || json.data.length !== batch.length) {
             throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
         }
-        results.push(...json.data.map((d) => d.embedding));
+        for (const [idx, d] of json.data.entries()) {
+            if (!Array.isArray(d.embedding)) {
+                throw new Error(`Unexpected embedding at batch index ${idx}: missing or invalid`);
+            }
+            results.push(d.embedding);
+        }
     }
     return results;
 }
 // ── Similarity ──────────────────────────────────────────────────────────────
 export function cosineSimilarity(a, b) {
-    const len = Math.min(a.length, b.length);
+    if (a.length !== b.length) {
+        // MD-4: Return 0 on dimension mismatch rather than silently computing on a
+        // truncated view, which would produce meaningless similarity scores.
+        warn("cosineSimilarity: vector dimension mismatch (%d vs %d) — re-index recommended", a.length, b.length);
+        return 0;
+    }
+    const len = a.length;
     if (len === 0)
         return 0;
     let dot = 0, magA = 0, magB = 0;

package/dist/errors.js

@@ -10,6 +10,8 @@ export class ConfigError extends Error {
     constructor(msg) {
         super(msg);
         this.name = "ConfigError";
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 /** Raised when the user supplies invalid arguments or input. */
@@ -17,6 +19,8 @@ export class UsageError extends Error {
     constructor(msg) {
         super(msg);
         this.name = "UsageError";
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 /** Raised when a requested resource (asset, entry, file) is not found. */
@@ -24,5 +28,7 @@ export class NotFoundError extends Error {
     constructor(msg) {
         super(msg);
         this.name = "NotFoundError";
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
     }
 }

package/dist/file-context.js

@@ -68,23 +68,22 @@ export function buildFileContext(stashRoot, absPath) {
 const matchers = [];
 /** Renderer lookup by name. */
 const renderers = new Map();
-let builtinsInitialized = false;
+let builtinsPromise;
 /**
  * Ensure that built-in matchers and renderers are registered.
  * Called lazily on first use of runMatchers/getRenderer.
+ * Stores the in-progress promise so parallel callers don't double-register.
  */
-function ensureBuiltinsRegistered() {
-    if (builtinsInitialized)
-        return;
-    builtinsInitialized = true;
-    // Lazy inline require avoids a top-level static import cycle.
-    // These are only evaluated once.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { registerBuiltinMatchers } = require("./matchers");
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { registerBuiltinRenderers } = require("./renderers");
-    registerBuiltinMatchers();
-    registerBuiltinRenderers();
+async function ensureBuiltinsRegistered() {
+    if (!builtinsPromise) {
+        builtinsPromise = (async () => {
+            const { registerBuiltinMatchers } = await import("./matchers.js");
+            const { registerBuiltinRenderers } = await import("./renderers.js");
+            registerBuiltinMatchers();
+            registerBuiltinRenderers();
+        })();
+    }
+    return builtinsPromise;
 }
 /**
  * Register an AssetMatcher.
@@ -106,15 +105,15 @@ export function registerRenderer(renderer) {
 /**
  * Look up a renderer by name.
  */
-export function getRenderer(name) {
-    ensureBuiltinsRegistered();
+export async function getRenderer(name) {
+    await ensureBuiltinsRegistered();
     return renderers.get(name);
 }
 /**
  * Return all registered renderers (snapshot, safe to iterate).
  */
-export function getAllRenderers() {
-    ensureBuiltinsRegistered();
+export async function getAllRenderers() {
+    await ensureBuiltinsRegistered();
     return Array.from(renderers.values());
 }
 /**
@@ -128,8 +127,8 @@ export function getAllRenderers() {
  *    (this lets user-registered matchers override built-in ones).
  * 4. Returns null when no matcher claims the file.
  */
-export function runMatchers(ctx) {
-    ensureBuiltinsRegistered();
+export async function runMatchers(ctx) {
+    await ensureBuiltinsRegistered();
     // Collect (result, registrationIndex) pairs from all matchers.
     const hits = [];
     for (let i = 0; i < matchers.length; i++) {

package/dist/frontmatter.js

@@ -8,6 +8,16 @@
  * Parse YAML-subset frontmatter from a Markdown (or similar) string.
  *
  * Returns the parsed key-value data and the remaining body content.
+ *
+ * **Limitations**: This is a hand-rolled YAML-subset parser with intentional
+ * constraints for simplicity and safety:
+ * - **No list support**: YAML block sequences (`- item`) and flow arrays
+ *   (`[a, b, c]`) are silently ignored. List-valued frontmatter keys will
+ *   produce an empty string or be skipped. Callers must NOT rely on list-
+ *   valued frontmatter.
+ * - **No nested objects beyond one level**: Only a single level of indented
+ *   key-value pairs is supported.
+ * - **Scalar values only**: string, boolean, and number scalars are supported.
  */
 export function parseFrontmatter(raw) {
     const parsedBlock = parseFrontmatterBlock(raw);
@@ -46,12 +56,18 @@ export function parseFrontmatter(raw) {
     };
 }
 export function parseFrontmatterBlock(raw) {
-    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    // Handle both LF and CRLF line endings throughout.
+    // The closing --- may be preceded by \r\n; capture and strip trailing \r
+    // from the frontmatter block so key parsing sees clean LF-terminated lines.
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r\n|\r|\n|$)([\s\S]*)$/);
     if (!match)
         return null;
+    // Strip any \r characters from the frontmatter block to normalise CRLF → LF
+    const frontmatter = match[1].replace(/\r/g, "");
+    const content = match[2];
     return {
-        frontmatter: match[1],
-        content: match[2],
+        frontmatter,
+        content,
         bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
     };
 }