akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/indexer/search-hit-enrichers.js

@@ -0,0 +1,111 @@
+// 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 { makeAssetRef } from "../core/asset-ref";
+import { getDerivedForParent } from "./db";
+import { getRenderer } from "./file-context";
+const rendererSearchHitEnricher = {
+    name: "renderer-search-hit-enricher",
+    appliesTo(ctx) {
+        return ctx.rendererRegistry.rendererNameFor(ctx.type) !== undefined;
+    },
+    async enrich(hit, ctx) {
+        const rendererName = ctx.rendererRegistry.rendererNameFor(ctx.type);
+        if (!rendererName)
+            return;
+        const renderer = await getRenderer(rendererName);
+        renderer?.enrichSearchHit?.(hit, ctx.stashDir);
+    },
+};
+/**
+ * Phase 5A / Advantage D5 — derived-memory enricher.
+ *
+ * When a parent memory has a `.derived` child indexed (the LLM-distilled
+ * lesson surface), this enricher rewrites the parent hit to surface the
+ * derived child's description / searchHints / tags AND sets `expandTo` to
+ * the derived child's ref so callers can fetch it via `akm show <ref>`.
+ *
+ * The parent ref is preserved on the hit — only the surface text is
+ * swapped, so links and provenance still point at the canonical parent.
+ *
+ * Skipped for:
+ *  - non-memory hits
+ *  - memory hits that are themselves derived children (name ends with
+ *    `.derived`) — we never recurse parent→child→grandchild
+ *  - contexts without an open DB connection
+ */
+export const derivedMemoryEnricher = {
+    name: "derived-memory-enricher",
+    appliesTo(ctx) {
+        return ctx.type === "memory" && ctx.db !== undefined;
+    },
+    enrich(hit, ctx) {
+        if (!ctx.db)
+            return;
+        // Never recurse: a `.derived` hit is itself the child surface; leaving
+        // it untouched also avoids `<parent>.derived.derived` chains.
+        if (hit.name.toLowerCase().endsWith(".derived"))
+            return;
+        // Parent ref shape: `memory:<name>`. Re-build from the entry's name
+        // so we don't depend on whatever wiki/registry prefix `hit.ref` carries.
+        const parentRef = makeAssetRef("memory", hit.name);
+        const derived = getDerivedForParent(ctx.db, parentRef);
+        if (!derived)
+            return;
+        // Swap description / searchHints / tags from the derived child.
+        // The parent ref itself is preserved — only the surface text is swapped.
+        if (typeof derived.entry.description === "string" && derived.entry.description.length > 0) {
+            hit.description = derived.entry.description;
+        }
+        if (Array.isArray(derived.entry.searchHints) && derived.entry.searchHints.length > 0) {
+            // We don't have a `searchHints` field on SourceSearchHit today — it's
+            // only used inside ranking. The plan says to swap when present; we
+            // record it onto the hit only if a future renderer surfaces it. For
+            // now, treat as advisory (no-op when SearchHit lacks the field).
+        }
+        if (Array.isArray(derived.entry.tags) && derived.entry.tags.length > 0) {
+            hit.tags = derived.entry.tags;
+        }
+        hit.expandTo = makeAssetRef("memory", derived.entry.name);
+    },
+};
+/**
+ * Registry of additional enrichers — populated by
+ * {@link registerSearchHitEnricher} and consumed in addition to
+ * {@link defaultSearchHitEnrichers} when `enrichSearchHit` is invoked
+ * without an explicit enricher list.
+ *
+ * Kept module-local so callers must use `registerSearchHitEnricher` rather
+ * than mutating the array directly.
+ */
+const additionalEnrichers = [];
+export const defaultSearchHitEnrichers = [rendererSearchHitEnricher, derivedMemoryEnricher];
+/**
+ * Register an additional enricher to be applied alongside the defaults.
+ *
+ * Idempotent on `name`: subsequent calls with the same name replace the
+ * previously-registered enricher (so tests can re-register cleanly without
+ * stacking duplicates).
+ */
+export function registerSearchHitEnricher(enricher) {
+    const existingIndex = additionalEnrichers.findIndex((e) => e.name === enricher.name);
+    if (existingIndex >= 0) {
+        additionalEnrichers[existingIndex] = enricher;
+    }
+    else {
+        additionalEnrichers.push(enricher);
+    }
+}
+/**
+ * Test-only: clear the registered-enrichers list. Not part of the public API.
+ */
+export function _resetRegisteredSearchHitEnrichers() {
+    additionalEnrichers.length = 0;
+}
+export async function enrichSearchHit(hit, ctx, enrichers = [...defaultSearchHitEnrichers, ...additionalEnrichers]) {
+    for (const enricher of enrichers) {
+        if (!enricher.appliesTo(ctx))
+            continue;
+        await enricher.enrich(hit, ctx);
+    }
+}

package/dist/indexer/search-source.js

@@ -1,7 +1,10 @@
+// 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 fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getSources, loadConfig } from "../core/config";
 import { resolveSourceProviderFactory } from "../sources/provider-factory";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
@@ -21,7 +24,7 @@ const GIT_STASH_TYPES = new Set(["git"]);
  *   1. The primary stash directory (the entry marked `primary: true`, or the
  *      legacy top-level `stashDir`). Always emitted, even when the directory
  *      does not yet exist on disk, so callers can use it as the clone target.
- *   2. Each entry in `config.sources ?? config.stashes[]` (in declared order), excluding the
+ *   2. Each entry in `config.sources[]` (in declared order), excluding the
  *      one already emitted as the primary.
  *   3. Each entry in `config.installed[]` (registry-managed stashes).
  *
@@ -32,12 +35,29 @@ const GIT_STASH_TYPES = new Set(["git"]);
 export function resolveSourceEntries(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
     const config = existingConfig ?? loadConfig();
-    const sources = [{ path: stashDir }];
+    // Primary stash is always writable.
+    const sources = [{ path: stashDir, writable: true }];
     const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId, wikiName) => {
+    const addSource = (dir, registryId, wikiName, writable) => {
         const resolved = path.resolve(dir);
-        if (seen.has(resolved))
+        if (seen.has(resolved)) {
+            // Already in the source list — typically the primary stash injected at
+            // sources[0] before this loop. Enrich that entry with whatever metadata
+            // the matching config source carries so `--source <config-name>` can
+            // find it via registryId. Without this, the primary stash entry stays
+            // identity-less and a user-named primary source ("name": "my-stash")
+            // would validate but match zero entries when filtering.
+            const existing = sources.find((s) => s.path === resolved);
+            if (existing) {
+                if (registryId && !existing.registryId)
+                    existing.registryId = registryId;
+                if (wikiName && !existing.wikiName)
+                    existing.wikiName = wikiName;
+                if (writable && !existing.writable)
+                    existing.writable = true;
+            }
             return;
+        }
         seen.add(resolved);
         if (isSuspiciousStashRoot(dir)) {
             warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
@@ -47,13 +67,14 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
                 path: resolved,
                 ...(registryId ? { registryId } : {}),
                 ...(wikiName ? { wikiName } : {}),
+                ...(writable ? { writable: true } : {}),
             });
         }
     };
     // (1) + (2) Single pass over declared stashes — primary first if present,
     // then the rest in declared order. The primary's directory is already
     // injected as `sources[0]` above, so we only need to dedupe the source set.
-    const stashes = config.sources ?? config.stashes ?? [];
+    const stashes = getSources(config);
     const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
     const ordered = [];
     if (primaryIdx >= 0) {
@@ -72,11 +93,12 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
         const dir = resolveEntryContentDir(entry);
         if (dir == null)
             continue;
-        addSource(dir, entry.name, entry.wikiName);
+        addSource(dir, entry.name, entry.wikiName, entry.writable === true);
     }
     // (3) Installed stashes (registry-managed). Always last.
+    // Only installed entries explicitly marked writable: true are considered writable.
     for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id, entry.wikiName);
+        addSource(entry.stashRoot, entry.id, entry.wikiName, entry.writable === true);
     }
     return sources;
 }
@@ -132,6 +154,19 @@ function resolveEntryContentDir(entry) {
 export function resolveAllStashDirs(overrideStashDir) {
     return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
+/**
+ * Return the resolved absolute paths of all writable stash sources.
+ *
+ * The primary stash is always writable. Filesystem/git sources that have
+ * `writable: true` in config are also included. Registry-cached sources
+ * (installed without `writable: true`) are excluded because they are
+ * overwritten on `akm update` and must never be mutated.
+ */
+export function getWritableStashDirs(overrideStashDir, existingConfig) {
+    return resolveSourceEntries(overrideStashDir, existingConfig)
+        .filter((s) => s.writable === true)
+        .map((s) => s.path);
+}
 /**
  * Find which source a file path belongs to.
  */
@@ -226,8 +261,7 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    // Use sources[] (current key) with fallback to stashes[] (deprecated, one-release compat).
-    const entries = cfg.sources ?? cfg.stashes ?? [];
+    const entries = getSources(cfg);
     for (const entry of entries) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
             continue;

package/dist/indexer/semantic-status.js

@@ -1,7 +1,10 @@
+// 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 fs from "node:fs";
-import path from "node:path";
+import { writeFileAtomic } from "../core/common";
 import { getCacheDir, getSemanticStatusPath } from "../core/paths";
-import { DEFAULT_LOCAL_MODEL } from "../llm/embedder";
+import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local";
 export function deriveSemanticProviderFingerprint(embedding) {
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
@@ -41,21 +44,7 @@ export function readSemanticStatus() {
 export function writeSemanticStatus(status) {
     const dir = getCacheDir();
     fs.mkdirSync(dir, { recursive: true });
-    const filePath = getSemanticStatusPath();
-    const tmpPath = path.join(dir, `semantic-status.json.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`);
-    fs.writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
-    try {
-        fs.renameSync(tmpPath, filePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeFileAtomic(getSemanticStatusPath(), `${JSON.stringify(status, null, 2)}\n`);
 }
 export function clearSemanticStatus() {
     try {