akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/commands/registry-search.js

@@ -1,5 +1,8 @@
+// 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/.
 import { toErrorMessage } from "../core/common";
-import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { DEFAULT_CONFIG } from "../core/config";
 import { warn } from "../core/warn";
 import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
@@ -133,7 +136,7 @@ export function resolveRegistries(configRegistries) {
         }
         return entries;
     }
-    const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
+    const registries = configRegistries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
 }
 // ── Provider resolution ─────────────────────────────────────────────────────

package/dist/commands/remember.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Memory-specific helpers for `akm remember`.
  *
@@ -5,12 +8,13 @@
  * heuristic derivation, LLM enrichment) is testable in isolation and the
  * CLI entry point stays focused on argument parsing + output routing.
  */
-import { stringify as yamlStringify } from "yaml";
+import { serializeFrontmatter } from "../core/asset-serialize";
 import { toErrorMessage, tryReadStdinText } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getDefaultLlmConfig, loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { SCOPE_KEYS } from "../indexer/metadata";
+import { parseFlagValue } from "../output/context";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
  * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
@@ -53,6 +57,12 @@ export function buildMemoryFrontmatter(fields) {
         obj.expires = fields.expires;
     if (fields.subjective)
         obj.subjective = true;
+    if (fields.captureMode === "hot" || fields.captureMode === "background") {
+        obj.captureMode = fields.captureMode;
+    }
+    if (typeof fields.beliefState === "string" && fields.beliefState.trim()) {
+        obj.beliefState = fields.beliefState.trim();
+    }
     // Scope keys are emitted as flat top-level keys (`scope_user`, …) so the
     // existing one-level frontmatter parser can read them without nesting.
     // A scope object with no populated values is dropped.
@@ -68,7 +78,7 @@ export function buildMemoryFrontmatter(fields) {
     // produce `---\n{}\n---` (the YAML serializer's empty-object form).
     if (Object.keys(obj).length === 0)
         return "---\n---";
-    const serialized = yamlStringify(obj).trimEnd();
+    const serialized = serializeFrontmatter(obj);
     return `---\n${serialized}\n---`;
 }
 /**
@@ -133,11 +143,11 @@ const LLM_ENRICH_TIMEOUT_MS = 10_000;
  */
 export async function runLlmEnrich(body) {
     const config = loadConfig();
-    if (!config.llm) {
-        warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
+    const llmConfig = getDefaultLlmConfig(config);
+    if (!llmConfig) {
+        warn("Warning: --enrich requires an LLM to be configured. Run `akm setup` to configure one.");
         return { tags: [] };
     }
-    const llmConfig = config.llm;
     const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
@@ -188,3 +198,56 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
         return { tags: [] };
     }
 }
+// ── Content-arg disambiguation ───────────────────────────────────────────────
+/**
+ * Guard against citty consuming a global flag value as the `content` positional.
+ *
+ * When the user runs `akm remember --format json` without a content argument,
+ * citty may assign `"json"` to the `content` positional because of how it
+ * handles flag order. This helper detects that case and returns `undefined`
+ * so `readMemoryContent` falls through to stdin.
+ */
+export function resolveRememberContentArg(content) {
+    if (content === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        content === parsedFormat &&
+        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        content === parsedDetail &&
+        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return content;
+}
+function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const rememberIndex = argv.indexOf("remember");
+    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
+    let flagIndex = -1;
+    let flagConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === flagName) {
+            flagIndex = i;
+            flagConsumesNextToken = true;
+            break;
+        }
+        if (token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (tokens.slice(0, flagIndex).includes(content))
+        return false;
+    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFlag).includes(content))
+        return false;
+    return true;
+}

package/dist/commands/schema-repair.js

@@ -0,0 +1,203 @@
+// 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/.
+/**
+ * Schema-repair pass for `akm improve`.
+ *
+ * Attempts to patch missing frontmatter fields (`description`, `when_to_use`)
+ * on assets that failed schema validation, using a single bounded in-tree LLM
+ * call per asset. Results are recorded as `schema_repair_invoked` events.
+ *
+ * This module is extracted from `improve.ts` to make the repair logic
+ * independently testable and to use the `tryLlmFeature` seam rather than raw
+ * `chatCompletion`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { assembleAsset } from "../core/asset-serialize";
+import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { createProposal, isProposalSkipped } from "../core/proposals";
+import { info, warn } from "../core/warn";
+import { resolveAssetPath } from "../indexer/path-resolver";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Minimum gap between schema-repair attempts on the same asset. */
+const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/**
+ * Per-ref attempt cap (O-6 / #379): maximum number of schema-repair attempts
+ * allowed within SCHEMA_REPAIR_WINDOW_MS. Prevents indefinite nightly re-repair
+ * of assets whose source content is genuinely ambiguous or inconsistently
+ * structured. After cap, the asset is skipped until the window rolls over.
+ * Self-Refine arXiv:2303.17651 — iteration must be bounded.
+ */
+const SCHEMA_REPAIR_MAX_ATTEMPTS = 3;
+const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Run the schema-repair loop for a batch of validation failures.
+ * Returns a list of per-asset outcome records and the set of refs that were
+ * successfully repaired (so the caller can exclude them from skip logic).
+ */
+export async function runSchemaRepairPass(failures, options) {
+    const repairs = [];
+    const repairedRefs = new Set();
+    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn = chatCompletion, } = options;
+    for (const failure of failures) {
+        if (Date.now() - startMs >= budgetMs)
+            break;
+        // Cooldown: skip repair if we ran it successfully recently.
+        const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
+        const lastRepair = recentRepairs.events
+            .filter((e) => e.metadata?.outcome === "written")
+            .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
+        if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        // O-6 / #379: Cap total attempts at SCHEMA_REPAIR_MAX_ATTEMPTS per SCHEMA_REPAIR_WINDOW_MS.
+        // Prevents indefinite nightly re-repair of assets whose source is genuinely ambiguous.
+        // After the cap is reached, the asset is skipped until the window rolls over.
+        const windowStart = Date.now() - SCHEMA_REPAIR_WINDOW_MS;
+        const attemptsInWindow = recentRepairs.events.filter((e) => e.ts !== undefined && new Date(e.ts).getTime() >= windowStart).length;
+        if (attemptsInWindow >= SCHEMA_REPAIR_MAX_ATTEMPTS) {
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "skipped",
+                error: `schema-repair attempt cap reached (${attemptsInWindow}/${SCHEMA_REPAIR_MAX_ATTEMPTS} in 30d window)`,
+            });
+            continue;
+        }
+        const filePath = await findFilePath(failure.ref, stashDir);
+        if (!filePath) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        if (path.extname(filePath).toLowerCase() !== ".md") {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        try {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const fm = parseFrontmatter(raw);
+            const missingFields = [];
+            if (!fm.data.description)
+                missingFields.push("description");
+            if (isLessonCandidateFn(failure.ref) && !fm.data.when_to_use)
+                missingFields.push("when_to_use");
+            if (missingFields.length === 0) {
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                continue;
+            }
+            const fieldList = missingFields.join(" and ");
+            info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
+            const bodyPreview = (fm.content ?? raw).slice(0, 2000);
+            const llmResponse = await chatFn(llmConfig, [
+                {
+                    role: "system",
+                    content: `You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.`,
+                },
+                {
+                    role: "user",
+                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${parseAssetRef(failure.ref).type} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}\n\n${bodyPreview}`,
+                },
+            ]);
+            const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
+            if (!parsed) {
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "error",
+                    error: "LLM returned unparseable JSON for schema repair",
+                });
+                continue;
+            }
+            const newFm = { ...fm.data };
+            if (parsed.description)
+                newFm.description = parsed.description;
+            if (parsed.when_to_use)
+                newFm.when_to_use = parsed.when_to_use;
+            const newContent = assembleAsset(newFm, fm.content);
+            // M-3 / #387: Route through proposal queue instead of writing directly to
+            // disk. This restores akm's safety invariant — the proposal queue is the
+            // only path to a committed asset write. LLM-generated `description` /
+            // `when_to_use` fields can be incorrect; routing through the queue makes
+            // them human-reviewable before they affect search ranking and curate hints.
+            // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
+            // should be human-reviewable.
+            if (stashDir) {
+                const proposalResult = createProposal(stashDir, {
+                    ref: failure.ref,
+                    source: "schema-repair",
+                    payload: {
+                        content: newContent,
+                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                    },
+                });
+                if (isProposalSkipped(proposalResult)) {
+                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
+                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                    continue;
+                }
+                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
+                });
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "queued",
+                    proposalId: proposalResult.id,
+                });
+                // Mark as repaired so the caller removes it from the validation-failure set.
+                repairedRefs.add(failure.ref);
+            }
+            else {
+                // Fallback: no stash dir available — write directly (legacy path).
+                // This should not occur in production; stashDir is always provided by
+                // `runSchemaRepairPass` callers in improve.ts.
+                warn(`[improve] schema-repair: no stashDir available for ${failure.ref}, falling back to direct write`);
+                fs.writeFileSync(filePath, newContent, "utf8");
+                info(`[improve] schema-repair written: ${failure.ref}`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "written", reason: failure.reason },
+                });
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
+                repairedRefs.add(failure.ref);
+            }
+        }
+        catch (e) {
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "error", reason: failure.reason, error: String(e) },
+            });
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "error", error: String(e) });
+        }
+    }
+    return { repairs, repairedRefs };
+}
+// ── Default seam implementations ─────────────────────────────────────────────
+function defaultIsLessonCandidate(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        return parsed.type === "lesson";
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultFindFilePath(ref, stashDir) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "index-first",
+        directoryIndexNames: ["SKILL.md", "index.md", "README.md"],
+        preserveDirectNameFallback: true,
+    });
+}

package/dist/commands/search.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * `akm search` — entry point.
  *
@@ -9,11 +12,13 @@
  * Provider `search()` methods do not exist.
  */
 import { loadConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { rethrowIfTestIsolationError, UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
+import { isTransientStashPath } from "../core/paths";
+import { bumpUtilityScoresBatch, closeDatabase, openExistingDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
+import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../sources/providers/index";
@@ -26,10 +31,42 @@ export async function akmSearch(input) {
     const normalizedQuery = query.toLowerCase();
     const searchType = input.type ?? "any";
     const limit = normalizeLimit(input.limit);
-    const source = parseSearchSource(input.source ?? "stash");
+    const parsedSource = parseSearchSource(input.source ?? "stash");
     const config = loadConfig();
-    const sources = resolveSourceEntries(undefined, config);
-    if (sources.length === 0) {
+    // Named-source filter: when --source is not a standard enum value, treat it
+    // as a named source from config.sources[].name. Validate early (before
+    // resolveSourceEntries, which can throw STASH_DIR_NOT_FOUND) so that a bad
+    // --source name always produces INVALID_SOURCE_VALUE regardless of stash state.
+    let namedSourceName;
+    let source;
+    if (parsedSource !== "stash" && parsedSource !== "registry" && parsedSource !== "both") {
+        namedSourceName = parsedSource;
+        // Check that the named source exists in the config before touching the stash.
+        const configSources = config.sources ?? [];
+        const foundInConfig = configSources.some((s) => s.name === namedSourceName) || configSources.some((s) => s.path === namedSourceName);
+        if (!foundInConfig) {
+            const validNames = configSources.map((s) => s.name).filter((n) => Boolean(n));
+            const hint = validNames.length > 0
+                ? `Known source names: ${validNames.join(", ")}`
+                : "No named sources are configured. Run `akm list` to see installed stashes.";
+            throw new UsageError(`Unknown source name: "${namedSourceName}". ${hint}`, "INVALID_SOURCE_VALUE");
+        }
+        source = "stash";
+    }
+    else {
+        source = parsedSource;
+    }
+    let allSources = resolveSourceEntries(undefined, config);
+    // When a named source was requested, narrow the sources list to just that entry.
+    // `resolveSourceEntries` sets `registryId` to `entry.name` for each config source.
+    if (namedSourceName !== undefined) {
+        const ns = namedSourceName;
+        allSources = allSources.filter((s) => s.registryId === ns || s.path === ns);
+        // allSources may still be empty if the configured source dir doesn't exist on
+        // disk (resolveSourceEntries skips non-existent dirs). Fall through to the
+        // zero-sources guard below which emits a friendly warning.
+    }
+    if (allSources.length === 0) {
         // stashDir: "" is a safe sentinel here — the response carries zero hits
         // and a warning, so no downstream code will try to use the empty path.
         const response = {
@@ -40,14 +77,18 @@ export async function akmSearch(input) {
             warnings: ["No stashes configured. Run `akm init` to create your working stash."],
             timing: { totalMs: Date.now() - t0 },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, undefined, input.eventSource);
         return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
     // stash root. Safe because the empty-sources case is handled above.
-    const stashDir = sources[0].path;
+    const stashDir = allSources[0].path;
+    // Expose the filtered source list to downstream search calls.
+    const sources = allSources;
     const filters = normalizeScopeFilters(input.filters);
     const includeProposed = input.includeProposed === true;
+    const belief = input.belief ?? "all";
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -59,6 +100,13 @@ export async function akmSearch(input) {
             config,
             filters,
             includeProposed,
+            beliefFilter: belief,
+            // When `--source <name>` narrowed the source list above, propagate
+            // that intent down to the database layer so FTS/vector hits from
+            // sources outside the narrowed set are filtered out post-ranking.
+            // Without this, the index (which spans every configured source)
+            // would leak hits from sources the caller did not request.
+            restrictToSources: namedSourceName !== undefined,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
@@ -73,7 +121,8 @@ export async function akmSearch(input) {
             warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, localResult?.mode ?? "keyword", input.eventSource);
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -107,7 +156,8 @@ export async function akmSearch(input) {
             warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0 },
         };
-        logSearchEvent(query, response);
+        if (!input.skipLogging)
+            logSearchEvent(query, response, undefined, undefined, input.eventSource);
         return response;
     }
     // source === "both"
@@ -124,7 +174,8 @@ export async function akmSearch(input) {
         warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
-    logSearchEvent(query, response);
+    if (!input.skipLogging)
+        logSearchEvent(query, response, undefined, undefined, input.eventSource);
     return response;
 }
 /**
@@ -160,13 +211,16 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, existingDb) {
+function logSearchEvent(query, response, existingDb, mode = "keyword", eventSource = "user") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
+    // D8: include registry hit refs so a show following a registry-only search generates a select event
+    const registryHitRefs = (response.registryHits ?? []).map((h) => `registry:${h.id}`);
+    const allResultRefs = [...stashHits.map((h) => h.ref), ...registryHitRefs];
     appendEvent({
         eventType: "search",
-        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
+        metadata: { query, hitCount: stashHits.length, resultRefs: allResultRefs, mode },
     });
     try {
         const db = existingDb ?? openExistingDatabase();
@@ -178,8 +232,24 @@ function logSearchEvent(query, response, existingDb) {
                     query,
                     entry_id: entryId,
                     entry_ref: ref,
+                    source: eventSource,
                 });
             }
+            // Bump utility scores for all resolved entries (MemRL retrieval signal).
+            // The indexer overwrites these at next reindex; bumps are temporary hints.
+            const resolvedIds = resolved.map((r) => r.entryId).filter((id) => id !== undefined);
+            if (resolvedIds.length > 0) {
+                let scopeKey;
+                try {
+                    const stashPath = response.stashDir;
+                    const disabled = process.env.AKM_DISABLE_SCOPED_UTILITY === "1" || (stashPath && isTransientStashPath(stashPath));
+                    scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
+                }
+                catch {
+                    // Non-fatal — fall back to global-only bumps on any error.
+                }
+                bumpUtilityScoresBatch(db, resolvedIds, 1.0, 0.1, scopeKey);
+            }
             // Count registry hits separately so registry-only searches record a
             // non-zero resultCount. response.hits is always [] when source="registry".
             const stashHitCount = response.hits.length;
@@ -192,7 +262,9 @@ function logSearchEvent(query, response, existingDb) {
                     stashHitCount,
                     registryHitCount,
                     resolvedCount: resolved.length,
+                    mode,
                 }),
+                source: eventSource,
             });
         }
         finally {
@@ -200,7 +272,8 @@ function logSearchEvent(query, response, existingDb) {
                 closeDatabase(db);
         }
     }
-    catch {
+    catch (err) {
+        rethrowIfTestIsolationError(err);
         /* fire-and-forget */
     }
 }
@@ -211,6 +284,24 @@ function normalizeLimit(limit) {
     }
     return Math.min(Math.floor(limit), 200);
 }
+/**
+ * Parse the `--source` flag value.
+ *
+ * Accepts:
+ *   - `stash` (default) — search the local stash index only
+ *   - `registry`        — search remote registries only
+ *   - `both`            — search stash and registries
+ *   - `local`           — alias for `stash`
+ *   - Any named source from `config.sources[].name` — filters stash results to
+ *     that single source only. The named-source path is detected and resolved
+ *     inside `akmSearch`; this function returns the raw name so the caller can
+ *     pass it through to `akmSearch` which accepts `SearchSource | string`.
+ *
+ * Unknown values that are not a known enum AND not a named source will still
+ * produce an error inside `akmSearch` when the config lookup finds nothing.
+ * This allows the CLI to accept named sources without requiring config access
+ * at parse time.
+ */
 export function parseSearchSource(source) {
     if (source === "stash" || source === "registry" || source === "both")
         return source;
@@ -219,7 +310,17 @@ export function parseSearchSource(source) {
         return "stash";
     if (typeof source === "undefined")
         return "stash";
-    throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`, "INVALID_SOURCE_VALUE");
+    // Pass through unknown strings — they may be valid named sources.
+    // `akmSearch` will validate against config.sources and throw a UsageError
+    // with a helpful message if the name isn't found.
+    return source;
+}
+export function parseBeliefFilterMode(value) {
+    if (value === undefined || value === "all")
+        return "all";
+    if (value === "current" || value === "historical")
+        return value;
+    throw new UsageError(`Invalid value for --belief: ${String(value)}. Expected one of: all|current|historical`, "INVALID_FLAG_VALUE");
 }
 /**
  * Strip empty / non-string values from a scope filter object. Returns

package/dist/commands/self-update.js

@@ -1,3 +1,6 @@
+// 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/.
 import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";