akm-cli 0.9.0-beta.54 → 0.9.0-beta.56

package/dist/indexer/indexer.js

@@ -143,6 +143,7 @@ async function runEmbeddingPhase(ctx) {
  */
 async function runFinalizePhase(ctx) {
     const { db, config, sources, sourceDirs, isIncremental, stashDir, signal, onProgress } = ctx;
+    ctx.timing.tFinalizeStart = Date.now();
     // Rebuild FTS after all inserts. Use incremental mode when this whole
     // index run is incremental — only entries touched by `upsertEntry`
     // since the last rebuild are re-indexed.
@@ -153,10 +154,13 @@ async function runFinalizePhase(ctx) {
     });
     ctx.timing.tFtsEnd = Date.now();
     // Re-link detached usage_events and recompute utility scores.
+    onProgress({ phase: "finalize", message: "Relinking usage events." });
     relinkUsageEvents(db);
+    onProgress({ phase: "finalize", message: "Recomputing utility scores." });
     recomputeUtilityScores(db);
     // Purge LLM cache entries for assets that no longer exist in the index.
     try {
+        onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
         clearStaleCacheEntries(db);
     }
     catch {
@@ -164,6 +168,7 @@ async function runFinalizePhase(ctx) {
     }
     // Regenerate each wiki's index.md from its pages' frontmatter. Best-effort.
     try {
+        onProgress({ phase: "finalize", message: "Regenerating wiki indexes." });
         const { regenerateAllWikiIndexes } = await import("../wiki/wiki.js");
         regenerateAllWikiIndexes(stashDir);
     }
@@ -180,6 +185,7 @@ async function runFinalizePhase(ctx) {
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
     const semanticEntryCount = getEmbeddableEntryCount(db);
+    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
     const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
     if (config.semanticSearchMode === "off") {
         clearSemanticStatus();
@@ -199,6 +205,7 @@ async function runFinalizePhase(ctx) {
     // Store verification result and totalEntries on ctx for the caller to use
     ctx.verification = verification;
     ctx.totalEntries = totalEntries;
+    ctx.timing.tFinalizeEnd = Date.now();
     // suppress unused warning — sources was previously used inline
     void sources;
 }
@@ -239,7 +246,21 @@ export async function akmIndex(options) {
     return akmIndexReal(options);
 }
 async function akmIndexReal(options) {
-    return withIndexWriterLease({ purpose: "akm-index", signal: options?.signal }, async () => {
+    const requestedAt = Date.now();
+    let acquiredAt = requestedAt;
+    return withIndexWriterLease({
+        purpose: "akm-index",
+        signal: options?.signal,
+        onWait: ({ waitedMs }) => {
+            options?.onProgress?.({
+                phase: "preflight",
+                message: `Waiting for index writer lease (${Math.round(waitedMs / 1000)}s elapsed).`,
+            });
+        },
+        onAcquired: ({ waitedMs }) => {
+            acquiredAt = requestedAt + waitedMs;
+        },
+    }, async () => {
         const stashDir = options?.stashDir || resolveStashDir();
         const onProgress = options?.onProgress ?? (() => { });
         const signal = options?.signal;
@@ -258,10 +279,17 @@ async function akmIndexReal(options) {
         warnOnUnmigratedVaults(stashDir);
         // Ensure git stash caches are extracted before resolving stash dirs,
         // so their content directories exist on disk for the walker to discover.
+        const sourceCacheStart = Date.now();
+        onProgress({ phase: "preflight", message: "Hydrating source caches." });
         const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
         await ensureSourceCaches(config, { force: full });
+        const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
         const allSourceDirs = allSourceEntries.map((s) => s.path);
+        onProgress({
+            phase: "preflight",
+            message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
+        });
         const t0 = Date.now();
         // Open database — pass embedding dimension from config if available
         const dbPath = getDbPath();
@@ -291,6 +319,8 @@ async function akmIndexReal(options) {
                     tLlmEnd: t0,
                     tFtsEnd: t0,
                     tEmbedEnd: t0,
+                    tFinalizeStart: t0,
+                    tFinalizeEnd: t0,
                 },
                 isIncremental,
                 builtAtMs,
@@ -328,9 +358,15 @@ async function akmIndexReal(options) {
             // After the normal index completes, remove entries whose source files no
             // longer exist on disk. Remote entries (empty file_path) are skipped.
             let cleanResult;
+            const cleanStart = Date.now();
             if (clean) {
+                onProgress({
+                    phase: "finalize",
+                    message: dryRun ? "Scanning for stale index entries (dry run)." : "Removing stale index entries.",
+                });
                 cleanResult = runCleanPass(db, dryRun);
             }
+            const cleanEnd = Date.now();
             // ────────────────────────────────────────────────────────────────────────
             return {
                 stashDir,
@@ -348,6 +384,12 @@ async function akmIndexReal(options) {
                     llmMs: timing.tLlmEnd - timing.tWalkEnd,
                     embedMs: timing.tEmbedEnd - timing.tLlmEnd,
                     ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
+                    finalizeMs: timing.tFinalizeEnd - timing.tFinalizeStart,
+                    cleanMs: clean ? cleanEnd - cleanStart : 0,
+                    preflightMs: timing.t0 - requestedAt,
+                    leaseWaitMs: acquiredAt - requestedAt,
+                    sourceCacheMs: sourceCacheEnd - sourceCacheStart,
+                    endToEndMs: Date.now() - requestedAt,
                 },
                 ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
             };
@@ -854,31 +896,44 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
                 warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
             }
         }
-        const embeddings = await embedBatch(texts, config.embedding, signal);
-        throwIfAborted(signal);
-        // Wrap all embedding upserts in a single transaction so partial
-        // state is rolled back on failure rather than leaving the table half-filled.
-        let storedCount = 0;
-        let skippedCount = 0;
-        db.transaction(() => {
-            for (let i = 0; i < allEntries.length; i++) {
-                if (upsertEmbedding(db, allEntries[i].id, embeddings[i])) {
-                    storedCount++;
-                }
-                else {
-                    skippedCount++;
+        let heartbeatTimer;
+        try {
+            heartbeatTimer = setInterval(() => {
+                onProgress({
+                    phase: "embeddings",
+                    message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
+                });
+            }, 15000);
+            const embeddings = await embedBatch(texts, config.embedding, signal);
+            throwIfAborted(signal);
+            // Wrap all embedding upserts in a single transaction so partial
+            // state is rolled back on failure rather than leaving the table half-filled.
+            let storedCount = 0;
+            let skippedCount = 0;
+            db.transaction(() => {
+                for (let i = 0; i < allEntries.length; i++) {
+                    if (upsertEmbedding(db, allEntries[i].id, embeddings[i])) {
+                        storedCount++;
+                    }
+                    else {
+                        skippedCount++;
+                    }
                 }
+            })();
+            if (skippedCount > 0) {
+                warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
-        })();
-        if (skippedCount > 0) {
-            warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
+            onProgress({
+                phase: "embeddings",
+                message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
+            });
+            setMeta(db, "embeddingFingerprint", currentFingerprint);
+            return { success: true };
+        }
+        finally {
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
         }
-        onProgress({
-            phase: "embeddings",
-            message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
-        });
-        setMeta(db, "embeddingFingerprint", currentFingerprint);
-        return { success: true };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/indexer/search/fts-query.js

@@ -0,0 +1,51 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Pure FTS5 query-string helpers, extracted from indexer/db/db.ts.
+ *
+ * These transform a raw user query into an FTS5-safe MATCH expression. They
+ * touch no database state, so they are unit-testable with zero DB setup.
+ */
+/**
+ * Sanitize a raw user query into an FTS5-safe implicit-AND expression.
+ *
+ * Allows only characters safe in FTS5 queries: letters, digits, underscores,
+ * and whitespace. Everything else (hyphens, dots, quotes, parens, asterisks,
+ * colons, carets, @, !, etc.) is replaced with a space so that compound
+ * identifiers like "code-review" or "k8s.setup" become AND-joined tokens
+ * ("code review", "k8s setup") rather than triggering FTS5 syntax errors.
+ */
+export function sanitizeFtsQuery(query) {
+    let sanitized = query.replace(/[^a-zA-Z0-9_\s]/g, " ");
+    // Neutralize the NEAR operator (FTS5 proximity syntax)
+    sanitized = sanitized.replace(/\bNEAR\b/g, " ");
+    const tokens = sanitized.split(/\s+/).filter((t) => t.length >= 1);
+    if (tokens.length === 0)
+        return "";
+    // Use implicit AND (space-separated tokens) for precision. FTS5 treats
+    // space-separated tokens as an implicit AND, matching only rows that
+    // contain ALL terms.
+    return tokens.join(" ");
+}
+/**
+ * Build a prefix query from an FTS5 query string by appending `*` to each
+ * token that is 3+ characters long. Tokens shorter than 3 characters are
+ * kept as-is (no prefix expansion) to avoid overly broad matches.
+ *
+ * Returns null if no tokens qualify for prefix expansion.
+ */
+export function buildPrefixQuery(ftsQuery) {
+    const tokens = ftsQuery.split(/\s+/).filter(Boolean);
+    let hasPrefix = false;
+    const prefixTokens = tokens.map((t) => {
+        if (t.length >= 3) {
+            hasPrefix = true;
+            return `${t}*`;
+        }
+        return t;
+    });
+    if (!hasPrefix)
+        return null;
+    return prefixTokens.join(" ");
+}

package/dist/integrations/agent/spawn.js

@@ -17,6 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { spawn as runtimeSpawn } from "../../runtime.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
@@ -346,72 +347,20 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     if (parseOutput === "json" && stdioMode === "captured") {
-        // Strip <think> blocks and code fences, then try direct parse with
-        // embedded-JSON fallback for local LLMs that emit prose around the payload.
-        const cleaned = stdout
-            .trim()
-            .replace(/<think>[\s\S]*?<\/think>/gi, "")
-            .trim()
-            .replace(/^```(?:json)?\s*\n?/, "")
-            .replace(/\n?```\s*$/, "")
-            .trim();
-        let parsed;
-        try {
-            parsed = JSON.parse(cleaned);
-        }
-        catch {
-            // Fallback: extract the first balanced {…} from prose output.
-            let found;
-            for (let s = 0; s < cleaned.length; s++) {
-                if (cleaned[s] !== "{")
-                    continue;
-                let depth = 0, inStr = false, esc = false;
-                for (let i = s; i < cleaned.length; i++) {
-                    const c = cleaned[i];
-                    if (inStr) {
-                        if (esc) {
-                            esc = false;
-                        }
-                        else if (c === "\\") {
-                            esc = true;
-                        }
-                        else if (c === '"') {
-                            inStr = false;
-                        }
-                        continue;
-                    }
-                    if (c === '"') {
-                        inStr = true;
-                        continue;
-                    }
-                    if (c === "{")
-                        depth++;
-                    if (c === "}") {
-                        depth--;
-                        if (depth === 0) {
-                            try {
-                                found = JSON.parse(cleaned.slice(s, i + 1));
-                            }
-                            catch { }
-                            break;
-                        }
-                    }
-                }
-                if (found !== undefined)
-                    break;
-            }
-            if (found === undefined) {
-                return {
-                    ok: false,
-                    exitCode,
-                    stdout,
-                    stderr,
-                    durationMs,
-                    reason: "parse_error",
-                    error: "no JSON object found in agent output",
-                };
-            }
-            parsed = found;
+        // Strip <think> blocks and code fences, then parse with embedded-JSON
+        // fallback for local LLMs that emit prose around the payload. Handles
+        // both top-level `{…}` and `[…]` structures.
+        const parsed = parseEmbeddedJsonResponse(stdout);
+        if (parsed === undefined) {
+            return {
+                ok: false,
+                exitCode,
+                stdout,
+                stderr,
+                durationMs,
+                reason: "parse_error",
+                error: "no JSON structure found in agent output",
+            };
         }
         return { ok: true, exitCode, stdout, stderr, durationMs, parsed };
     }

package/dist/llm/embedders/cache.js

@@ -25,7 +25,9 @@ export function getCachedEmbedding(key) {
     return cached;
 }
 export function setCachedEmbedding(key, value) {
-    // Evict oldest entry if at capacity
+    // Delete first so an overwrite refreshes LRU recency AND is not counted as a
+    // new insert: only a genuinely new key at capacity should evict the oldest.
+    embedCache.delete(key);
     if (embedCache.size >= EMBED_CACHE_MAX) {
         const oldest = embedCache.keys().next().value;
         if (oldest !== undefined) {

package/dist/output/text/helpers.js

@@ -1058,6 +1058,19 @@ export function formatIndexPlain(r) {
     if (verification?.ok === false && verification.message) {
         out += `\nVerification: ${String(verification.message)}`;
     }
+    const timing = indexResult.timing;
+    if (timing) {
+        out +=
+            `\nTiming: total ${timing.totalMs}ms` +
+                `, preflight ${timing.preflightMs}ms` +
+                `, walk ${timing.walkMs}ms` +
+                `, llm ${timing.llmMs}ms` +
+                `, embeddings ${timing.embedMs}ms` +
+                `, fts ${timing.ftsMs}ms` +
+                `, finalize ${timing.finalizeMs}ms` +
+                `, clean ${timing.cleanMs}ms` +
+                `, end-to-end ${timing.endToEndMs}ms`;
+    }
     return out;
 }
 export function formatListPlain(r) {

package/dist/registry/resolve.js

@@ -238,6 +238,11 @@ function tryParseLocalRef(rawRef, explicitPath) {
     };
 }
 function isPathLikeRef(ref) {
+    // A leading `@` marks an npm scope (`@scope/pkg`), never a filesystem path —
+    // treat it as non-path so it falls through to the npm branch instead of
+    // being resolved (and rejected) as an explicit local path.
+    if (ref.startsWith("@"))
+        return false;
     if (ref === "." || ref === "..")
         return true;
     if (path.isAbsolute(ref))