akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{paths.js → core/paths.js}

@@ -19,7 +19,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
             return path.join(appData, "akm");
         const userProfile = env.USERPROFILE?.trim();
         if (!userProfile) {
-            throw new ConfigError("Unable to determine config directory. Set APPDATA or USERPROFILE.");
+            throw new ConfigError("Unable to determine config directory. Set APPDATA or USERPROFILE.", "CONFIG_DIR_UNRESOLVABLE");
         }
         return path.join(userProfile, "AppData", "Roaming", "akm");
     }
@@ -28,7 +28,7 @@ export function getConfigDir(env = process.env, platform = process.platform) {
         return path.join(xdgConfigHome, "akm");
     const home = env.HOME?.trim();
     if (!home) {
-        throw new ConfigError("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
+        throw new ConfigError("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.", "CONFIG_DIR_UNRESOLVABLE");
     }
     return path.join(home, ".config", "akm");
 }
@@ -49,7 +49,7 @@ export function getCacheDir() {
             return path.join(userProfile, "AppData", "Local", "akm");
         const appData = process.env.APPDATA?.trim();
         if (!appData) {
-            throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
+            throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.", "CONFIG_DIR_UNRESOLVABLE");
         }
         // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so navigate
         // to the sibling "Local" directory. This is typically
@@ -96,7 +96,7 @@ export function getDefaultStashDir() {
     }
     const home = process.env.HOME?.trim();
     if (!home) {
-        throw new ConfigError("Unable to determine default stash directory. Set HOME.");
+        throw new ConfigError("Unable to determine default stash directory. Set HOME.", "STASH_DIR_NOT_FOUND");
     }
     return path.join(home, "akm");
 }

package/dist/core/write-source.js

@@ -0,0 +1,280 @@
+/**
+ * write-source — the only place in the codebase that branches on `source.kind`.
+ *
+ * v1 architecture spec §2.6 / §2.7 / §10 step 5: writing to a source is *not*
+ * a SourceProvider interface concern. It's a small command-layer helper that
+ * does a plain filesystem write, plus a git-specific commit (and optional
+ * push) when the source is backed by a git working tree.
+ *
+ * If a third kind ever needs special write handling, it gets added here. For
+ * v1 there are exactly two cases. Adding more parallel scoring systems for
+ * different provider kinds is explicitly disallowed by CLAUDE.md.
+ *
+ * This module is the **single dispatch point** for `kind`-branching write
+ * logic. Callers (remember, import, source-add, etc.) MUST go through
+ * `writeAssetToSource` / `deleteAssetFromSource` rather than re-inlining the
+ * filesystem-write + git-commit dance.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
+import { makeAssetRef } from "./asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { isWithin, resolveStashDir } from "./common";
+import { resolveConfiguredSources } from "./config";
+import { ConfigError, UsageError } from "./errors";
+/**
+ * Source kinds that the loader is allowed to mark `writable: true`. Anything
+ * else is rejected at config load (per locked decision 4) — see
+ * {@link assertWritableAllowedForKind}.
+ */
+const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
+// ── Public helpers ──────────────────────────────────────────────────────────
+/**
+ * Resolve the effective `writable` flag for a source config entry, applying
+ * the v1 default policy from spec §5.4:
+ *
+ *  - `filesystem` → `true` by default
+ *  - everything else → `false` by default
+ *
+ * Users can opt out for `filesystem` via `writable: false`. They cannot opt
+ * **in** for `website` / `npm` — that combination is rejected at config load
+ * (see {@link assertWritableAllowedForKind}).
+ */
+export function resolveWritable(entry) {
+    if (typeof entry.writable === "boolean")
+        return entry.writable;
+    return entry.type === "filesystem";
+}
+/**
+ * Reject `writable: true` on `website` / `npm` sources at config-load time.
+ * Per locked decision 4 (§6 of the v1 implementation plan): `sync()` would
+ * clobber writes on the next refresh, so allowing writes here is a footgun.
+ *
+ * Throws {@link ConfigError} when the combination is rejected.
+ */
+export function assertWritableAllowedForKind(entry) {
+    if (entry.writable !== true)
+        return;
+    if (REJECTED_WRITABLE_KINDS.has(entry.type)) {
+        const label = entry.name ? ` "${entry.name}"` : "";
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.type}" on source${label}).`, "INVALID_CONFIG_FILE", "To author into a checked-out package, add the same path as a separate filesystem source.");
+    }
+}
+/**
+ * Write a textual asset (`content`) into `source` at the path implied by
+ * `ref`. Always:
+ *
+ *   1. Refuses if `config.writable` is not truthy (per §5.4).
+ *   2. Performs a plain filesystem write to `path.join(source.path, …)`.
+ *
+ * For sources of `kind === "git"`, additionally:
+ *
+ *   3. `git -C <path> add <file>`
+ *   4. `git -C <path> commit -m "Update <ref>"`
+ *   5. `git -C <path> push` when `config.options.pushOnCommit` is truthy.
+ *
+ * Any other `kind` reaching this helper is a configuration bug — the loader
+ * rejects unsupported writable kinds — so we throw {@link ConfigError}.
+ */
+export async function writeAssetToSource(source, config, ref, content) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const normalized = content.endsWith("\n") ? content : `${content}\n`;
+    fs.writeFileSync(filePath, normalized, "utf8");
+    await runKindSpecificCommit(source, config, filePath, `Update ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Delete the asset at `ref` from `source`. Symmetric to
+ * {@link writeAssetToSource}: same writable check, same git-commit-and-push
+ * convenience for `kind === "git"`.
+ */
+export async function deleteAssetFromSource(source, config, ref) {
+    ensureWritable(source, config);
+    const filePath = resolveAssetFilePath(source, ref);
+    if (!fs.existsSync(filePath)) {
+        throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    fs.unlinkSync(filePath);
+    await runKindSpecificCommit(source, config, filePath, `Remove ${formatRefForMessage(ref)}`);
+    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+}
+/**
+ * Resolve the destination for a write per locked decision 3:
+ *
+ *   1. Explicit `--target <name>` (when supplied)
+ *   2. `config.defaultWriteTarget`
+ *   3. `config.stashDir` (the working stash created by `akm init`)
+ *   4. `ConfigError("no writable source configured; run `akm init`")`
+ *
+ * The legacy `first-writable-in-source-array-order` fallback is *not* used —
+ * see plan §6 decision 3 for the rationale.
+ */
+export function resolveWriteTarget(akmConfig, explicitTarget) {
+    const configuredSources = resolveConfiguredSources(akmConfig);
+    // 1. Explicit --target wins.
+    if (explicitTarget) {
+        const match = configuredSources.find((s) => s.name === explicitTarget);
+        if (!match) {
+            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        // Up-front writable check so an explicit --target fails fast with a
+        // ConfigError (rather than the generic UsageError ensureWritable would
+        // raise after we've already started building paths). Resolve the
+        // effective writable flag (filesystem defaults to true; everything else
+        // defaults to false) so unset values are interpreted correctly.
+        const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
+        if (!effectiveWritable) {
+            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
+        }
+        return adaptConfiguredSource(match);
+    }
+    // 2. config.defaultWriteTarget.
+    if (akmConfig.defaultWriteTarget) {
+        const match = configuredSources.find((s) => s.name === akmConfig.defaultWriteTarget);
+        if (match)
+            return adaptConfiguredSource(match);
+        // Fall through if the named target no longer exists — surface a clear error.
+        throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm list` to see configured sources.");
+    }
+    // 3. Working stash (config.stashDir / resolveStashDir()).
+    try {
+        const stashDir = resolveStashDir({ readOnly: true });
+        return {
+            source: { kind: "filesystem", name: "stash", path: stashDir },
+            config: { type: "filesystem", path: stashDir, name: "stash", writable: true },
+        };
+    }
+    catch {
+        // Fall through to the final ConfigError below.
+    }
+    // 4. Nothing usable.
+    throw new ConfigError("no writable source configured; run `akm init`", "STASH_DIR_NOT_FOUND", "Run `akm init` to create a working stash, or set `defaultWriteTarget` in your config.");
+}
+// ── Internals ───────────────────────────────────────────────────────────────
+function ensureWritable(source, config) {
+    // Apply the same default-resolution rule as resolveWritable so callers can
+    // pass through a SourceConfigEntry with an absent `writable` field.
+    const writable = resolveWritable(config);
+    if (!writable) {
+        throw new UsageError(`Source "${source.name}" is not writable. Set \`writable: true\` on the source config entry to enable writes.`, "INVALID_FLAG_VALUE");
+    }
+}
+function resolveAssetFilePath(source, ref) {
+    const typeDir = TYPE_DIRS[ref.type];
+    if (!typeDir) {
+        throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");
+    }
+    const typeRoot = path.join(source.path, typeDir);
+    const assetPath = resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved asset path escapes its source: "${ref.name}" in source "${source.name}".`, "PATH_ESCAPE_VIOLATION");
+    }
+    return assetPath;
+}
+async function runKindSpecificCommit(source, config, filePath, message) {
+    if (source.kind === "filesystem") {
+        return; // No commit step.
+    }
+    if (source.kind === "git") {
+        runGitCommit(source.path, filePath, message);
+        if (config.options?.pushOnCommit) {
+            runGitPush(source.path);
+        }
+        return;
+    }
+    // Reject any other kind reaching the helper. The config loader is the
+    // first line of defence (assertWritableAllowedForKind), but we throw here
+    // so external callers that bypass the loader still get a clear error.
+    throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
+        "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
+}
+function runGitCommit(repoDir, filePath, message) {
+    // Stage the specific file rather than `add -A` so unrelated working-tree
+    // changes don't get folded into the asset commit.
+    const relPath = path.relative(repoDir, filePath) || filePath;
+    const addResult = spawnSync("git", ["-C", repoDir, "add", "--", relPath], { encoding: "utf8" });
+    if (addResult.status !== 0) {
+        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
+    }
+    // Provide a fallback identity so fresh CI/test environments without
+    // user.name/user.email configured can always commit.
+    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", message], { encoding: "utf8" });
+    if (commitResult.status !== 0) {
+        // `nothing to commit` is a no-op success — the file may have matched the
+        // existing tree exactly. Surface other errors verbatim.
+        const stderr = commitResult.stderr ?? "";
+        if (/nothing to commit|no changes added/i.test(stderr) ||
+            /nothing to commit|no changes added/i.test(commitResult.stdout ?? "")) {
+            return;
+        }
+        throw new Error(`git commit failed: ${stderr.trim() || "unknown error"}`);
+    }
+}
+function runGitPush(repoDir) {
+    const pushResult = spawnSync("git", ["-C", repoDir, "push"], { encoding: "utf8", timeout: 120_000 });
+    if (pushResult.status !== 0) {
+        throw new Error(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`);
+    }
+}
+function formatRefForMessage(ref) {
+    return ref.origin ? `${ref.origin}//${ref.type}:${ref.name}` : `${ref.type}:${ref.name}`;
+}
+/**
+ * Derive a {@link WriteTargetSource} + persisted {@link SourceConfigEntry}
+ * from the runtime {@link ConfiguredSource} representation used elsewhere in
+ * the codebase. The mapping is:
+ *
+ *   ConfiguredSource.type     → WriteTargetSource.kind
+ *   ConfiguredSource.name     → WriteTargetSource.name
+ *   ConfiguredSource.source.* → WriteTargetSource.path  (via parseSourceSpec)
+ *
+ * Legacy aliases (`context-hub`, `github`) have already been normalised to
+ * `git` by the config loader, so this mapping is straightforward.
+ */
+function adaptConfiguredSource(runtime) {
+    const writePath = pathFromConfiguredSource(runtime);
+    if (!writePath) {
+        throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
+    }
+    // Map the runtime kind to the write helper's `kind` discriminator. Only
+    // filesystem and git produce writable sources at v1.
+    const kind = runtime.type === "filesystem" || runtime.type === "git" ? runtime.type : runtime.type;
+    const config = {
+        type: runtime.type,
+        name: runtime.name,
+        ...(writePath !== undefined ? { path: writePath } : {}),
+        ...(runtime.writable !== undefined ? { writable: runtime.writable } : {}),
+        ...(runtime.options ? { options: runtime.options } : {}),
+    };
+    return {
+        source: { kind, name: runtime.name, path: writePath },
+        config,
+    };
+}
+function pathFromConfiguredSource(runtime) {
+    // ConfiguredSource.source is the parsed SourceSpec (filesystem|git|website|npm).
+    // For writable kinds we only ever care about a local on-disk path: filesystem
+    // sources expose it directly; git sources resolve through the cache mirror
+    // (handled by the existing source provider). For v1 the helper trusts
+    // callers to materialise the cache path beforehand and does not re-clone.
+    const spec = runtime.source;
+    if (spec.type === "filesystem")
+        return spec.path;
+    // For git sources we fall back to the cached repo directory the provider
+    // already materialised. The lookup is intentionally lazy — we only import
+    // it when needed to keep the helper's import graph small.
+    if (spec.type === "git") {
+        try {
+            const repo = parseGitRepoUrl(spec.url);
+            return getCachePaths(repo.canonicalUrl).repoDir;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/{local-search.js → indexer/db-search.js}

@@ -1,32 +1,35 @@
 /**
- * Local (filesystem + SQLite) stash search implementation.
+ * Database-backed (SQLite + FTS5/vector) source search implementation.
  *
- * Extracted from stash-search.ts to break the circular import:
- *   stash-search.ts → stash-providers/filesystem.ts → local-search.ts (no cycle)
+ * Extracted from source-search.ts to break the circular import:
+ *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
  *
- * stash-search.ts imports this module for the `searchLocal` export.
- * stash-providers/filesystem.ts also imports `searchLocal` from here.
+ * source-search.ts imports this module for the `searchLocal` export.
+ * sources/providers/filesystem.ts also imports `searchLocal` from here.
+ *
+ * Renamed from `local-search.ts` to signal that this is the DB-layer search
+ * implementation, not a "local vs. remote" distinction.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ACTION_BUILDERS, TYPE_TO_RENDERER } from "./asset-registry";
-import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
+import { makeAssetRef } from "../core/asset-ref";
+import { defaultRendererRegistry } from "../core/asset-registry";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
-import { buildSearchText } from "./indexer";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
-import { getDbPath } from "./paths";
+import { buildSearchText } from "./search-fields";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
-import { makeAssetRef } from "./stash-ref";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
-export async function rendererForType(type) {
-    const name = TYPE_TO_RENDERER[type];
+export async function rendererForType(type, registry = defaultRendererRegistry) {
+    const name = registry.rendererNameFor(type);
     return name ? getRenderer(name) : undefined;
 }
-export function buildLocalAction(type, ref) {
-    const builder = ACTION_BUILDERS[type];
+export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
+    const builder = registry.actionBuilderFor(type);
     return builder ? builder(ref) : `akm show ${ref}`;
 }
 function resolveSearchHitRef(entry, refName, source) {
@@ -41,7 +44,8 @@ function resolveSearchHitOrigin(source) {
 // ── Main search entrypoint ───────────────────────────────────────────────────
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
-    const allStashDirs = sources.map((s) => s.path);
+    const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
+    const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
@@ -81,7 +85,7 @@ export async function searchLocal(input) {
                     }
                 }
                 if (entryCount > 0 && stashDirMatch) {
-                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources);
+                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry);
                     return {
                         hits,
                         tip: hits.length === 0
@@ -101,7 +105,7 @@ export async function searchLocal(input) {
     catch (error) {
         warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
-    const hitArrays = await Promise.all(allStashDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config)));
+    const hitArrays = await Promise.all(allSourceDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
     const hits = hitArrays.flat().slice(0, limit);
     return {
         hits,
@@ -110,7 +114,7 @@ export async function searchLocal(input) {
     };
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
     // Empty query: return all entries
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
@@ -131,9 +135,10 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             query,
             rankingMode: "fts",
             defaultStashDir: stashDir,
-            allStashDirs,
+            allSourceDirs,
             sources,
             config,
+            rendererRegistry,
         })));
         return { hits };
     }
@@ -350,13 +355,19 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             item.utilityBoosted = true;
         }
     }
+    // ── minScore floor ──────────────────────────────────────────────────────
+    // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
+    // below the configured floor. FTS hits and hybrid hits are always kept.
+    // Default floor: 0.2. Set search.minScore = 0 in config to disable.
+    const minScore = config.search?.minScore ?? 0.2;
+    const preFilter = minScore > 0 ? scored.filter((item) => item.rankingMode !== "semantic" || item.score >= minScore) : scored;
     // Deterministic tiebreaker on equal scores
-    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    preFilter.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
     // Deduplicate by file path — keep only the highest-scored entry per file.
     // Multiple .stash.json entries can map to the same file (e.g. entries without
     // a filename field all collapse to files[0]). Showing the same path/ref
     // multiple times clutters results.
-    const deduped = deduplicateByPath(scored);
+    const deduped = deduplicateByPath(preFilter);
     const rankMs = Date.now() - tRank0;
     const selected = deduped.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => buildDbHit({
@@ -367,10 +378,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         query,
         rankingMode,
         defaultStashDir: stashDir,
-        allStashDirs,
+        allSourceDirs,
         sources,
         config,
         utilityBoosted,
+        rendererRegistry,
     })));
     return { embedMs, rankMs, hits };
 }
@@ -383,7 +395,7 @@ async function tryVecScores(db, query, k, config) {
     if (hasEmbeddings !== "1")
         return null;
     try {
-        const { embed } = await import("./embedder.js");
+        const { embed } = await import("../llm/embedder.js");
         const queryEmbedding = await embed(query, config.embedding);
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();
@@ -401,20 +413,24 @@ async function tryVecScores(db, query, k, config) {
     }
 }
 // ── Substring fallback (no index) ───────────────────────────────────────────
-async function substringSearch(query, searchType, limit, stashDir, sources, config) {
+async function substringSearch(query, searchType, limit, stashDir, sources, config, rendererRegistry = defaultRendererRegistry) {
     const assets = await indexAssets(stashDir, searchType, sources);
     const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
     if (!query) {
         const sorted = matched.sort(compareAssets);
         const unique = deduplicateAssetsByPath(sorted);
-        return Promise.all(unique.slice(0, limit).map((asset) => assetToSearchHit(asset, stashDir, sources, config)));
+        return Promise.all(unique
+            .slice(0, limit)
+            .map((asset) => assetToSearchHit(asset, stashDir, sources, config, undefined, rendererRegistry)));
     }
     // Score and sort by relevance
     const scored = matched.map((asset) => ({ asset, score: scoreSubstringMatch(asset.entry, query) }));
     scored.sort((a, b) => b.score - a.score || compareAssets(a.asset, b.asset));
     // Deduplicate by path — keep highest-scored entry per file
     const dedupedScored = deduplicateByPath(scored.map((s) => ({ ...s, filePath: s.asset.path })));
-    return Promise.all(dedupedScored.slice(0, limit).map(({ asset, score }) => assetToSearchHit(asset, stashDir, sources, config, score)));
+    return Promise.all(dedupedScored
+        .slice(0, limit)
+        .map(({ asset, score }) => assetToSearchHit(asset, stashDir, sources, config, score, rendererRegistry)));
 }
 function scoreSubstringMatch(entry, query) {
     const tokens = query.split(/\s+/).filter(Boolean);
@@ -444,6 +460,7 @@ function scoreSubstringMatch(entry, query) {
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
+    const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
     const canonical = deriveCanonicalAssetNameFromStashRoot(input.entry.type, entryStashDir, input.path);
     const refName = canonical && !canonical.startsWith("../") && !canonical.startsWith("..\\") ? canonical : input.entry.name;
@@ -471,12 +488,12 @@ export async function buildDbHit(input) {
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
-        action: buildLocalAction(input.entry.type, ref),
+        action: buildLocalAction(input.entry.type, ref, rendererRegistry),
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
     };
-    const renderer = await rendererForType(input.entry.type);
+    const renderer = await rendererForType(input.entry.type, rendererRegistry);
     if (renderer?.enrichSearchHit) {
         renderer.enrichSearchHit(hit, entryStashDir);
     }
@@ -530,7 +547,7 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted) {
         reasons.push("usage history boost");
     return reasons;
 }
-async function assetToSearchHit(asset, stashDir, sources, config, score) {
+async function assetToSearchHit(asset, stashDir, sources, config, score, rendererRegistry = defaultRendererRegistry) {
     const source = findSourceForPath(asset.path, sources);
     const editable = isEditable(asset.path, config);
     const ref = resolveSearchHitRef(asset.entry, asset.entry.name, source);
@@ -550,11 +567,11 @@ async function assetToSearchHit(asset, stashDir, sources, config, score) {
         description: asset.entry.description,
         tags: asset.entry.tags,
         ...(size ? { size } : {}),
-        action: buildLocalAction(asset.entry.type, ref),
+        action: buildLocalAction(asset.entry.type, ref, rendererRegistry),
         ...(score !== undefined ? { score } : {}),
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
     };
-    const renderer = await rendererForType(asset.entry.type);
+    const renderer = await rendererForType(asset.entry.type, rendererRegistry);
     if (renderer?.enrichSearchHit) {
         renderer.enrichSearchHit(hit, stashDir);
     }