akm-cli 0.5.0 → 0.6.0-rc1

package/dist/curate.js

@@ -0,0 +1,258 @@
+/**
+ * Curate logic for `akm curate`.
+ *
+ * Given a query (and optional type filter / source / limit), pick a small,
+ * high-signal set of stash + registry hits and enrich each with the data
+ * needed to act (ref, run, parameters, follow-up command).
+ *
+ * The exported `akmCurate()` API is the single entry point. Internal
+ * helpers stay private. Tests can drive the public API or call the smaller
+ * pure helpers (`curateSearchResults`, `orderCuratedTypes`,
+ * `deriveCurateFallbackQueries`) by importing them directly.
+ */
+import { truncateDescription } from "./output-shapes";
+import { akmSearch, parseSearchSource } from "./stash-search";
+import { akmShowUnified } from "./stash-show";
+const CURATE_FALLBACK_FILTER_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "for",
+    "how",
+    "i",
+    "in",
+    "of",
+    "or",
+    "the",
+    "to",
+    "with",
+]);
+const CURATED_TYPE_FALLBACK_ORDER = ["skill", "command", "script", "knowledge", "agent", "memory"];
+const CURATED_TYPE_FALLBACK_INDEX = new Map(CURATED_TYPE_FALLBACK_ORDER.map((type, index) => [type, index]));
+const MIN_CURATE_FALLBACK_TOKEN_LENGTH = 3;
+const MAX_CURATE_FALLBACK_KEYWORDS = 6;
+export const CURATE_SEARCH_LIMIT_MULTIPLIER = 4;
+export const MIN_CURATE_SEARCH_LIMIT = 12;
+const DEFAULT_CURATE_LIMIT = 4;
+/**
+ * Public curate entry point. Performs the search itself when
+ * `options.searchResponse` is not supplied.
+ */
+export async function akmCurate(options) {
+    const limit = options.limit && options.limit > 0 ? options.limit : DEFAULT_CURATE_LIMIT;
+    const source = options.source ?? parseSearchSource("stash");
+    const searchResponse = options.searchResponse ??
+        (await searchForCuration({
+            query: options.query,
+            type: options.type,
+            // Search deeper than the final curated count so we can pick one strong
+            // match per type and still have room for fallback retries.
+            limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
+            source,
+        }));
+    return curateSearchResults(options.query, searchResponse, limit, options.type);
+}
+export async function curateSearchResults(query, result, limit, selectedType) {
+    const stashHits = result.hits.filter((hit) => hit.type !== "registry");
+    const registryHits = result.registryHits ?? [];
+    let selectedStashHits;
+    if (selectedType && selectedType !== "any") {
+        selectedStashHits = stashHits.slice(0, limit);
+    }
+    else {
+        const bestByType = new Map();
+        for (const hit of stashHits) {
+            if (!bestByType.has(hit.type))
+                bestByType.set(hit.type, hit);
+        }
+        const orderedTypes = orderCuratedTypes(query, Array.from(bestByType.keys()));
+        selectedStashHits = orderedTypes
+            .map((type) => bestByType.get(type))
+            .filter((hit) => Boolean(hit));
+    }
+    const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, Math.min(2, limit - selectedStashHits.length));
+    const items = [
+        ...(await Promise.all(selectedStashHits.slice(0, limit).map((hit) => enrichCuratedStashHit(query, hit)))),
+        ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
+    ].slice(0, limit);
+    return {
+        query,
+        summary: buildCurateSummary(query, items),
+        items,
+        ...(result.warnings?.length ? { warnings: result.warnings } : {}),
+        ...(result.tip ? { tip: result.tip } : {}),
+    };
+}
+export function orderCuratedTypes(query, types) {
+    const lower = query.toLowerCase();
+    const boosts = new Map();
+    const addBoost = (type, amount) => boosts.set(type, (boosts.get(type) ?? 0) + amount);
+    if (/(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower)) {
+        addBoost("script", 6);
+        addBoost("command", 4);
+    }
+    if (/(guide|docs?|readme|reference|how|explain|learn|why)/.test(lower)) {
+        addBoost("knowledge", 6);
+        addBoost("skill", 4);
+    }
+    if (/(agent|assistant|planner|review|analy[sz]e|architect|prompt)/.test(lower)) {
+        addBoost("agent", 6);
+        addBoost("skill", 3);
+    }
+    if (/(config|template|release|generate|command)/.test(lower)) {
+        addBoost("command", 5);
+    }
+    if (/(memory|context|recall|remember)/.test(lower)) {
+        addBoost("memory", 6);
+    }
+    return [...types].sort((a, b) => {
+        const boostDiff = (boosts.get(b) ?? 0) - (boosts.get(a) ?? 0);
+        if (boostDiff !== 0)
+            return boostDiff;
+        return ((CURATED_TYPE_FALLBACK_INDEX.get(a) ?? Number.MAX_SAFE_INTEGER) -
+            (CURATED_TYPE_FALLBACK_INDEX.get(b) ?? Number.MAX_SAFE_INTEGER));
+    });
+}
+async function enrichCuratedStashHit(query, hit) {
+    let shown;
+    try {
+        shown = await akmShowUnified({ ref: hit.ref });
+    }
+    catch {
+        shown = undefined;
+    }
+    const description = shown?.description ?? hit.description;
+    const preview = buildCuratedPreview(shown, hit);
+    return {
+        source: "stash",
+        type: shown?.type ?? hit.type,
+        name: shown?.name ?? hit.name,
+        ref: hit.ref,
+        ...(description ? { description } : {}),
+        ...(preview ? { preview } : {}),
+        ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
+        ...(shown?.run ? { run: shown.run } : {}),
+        followUp: `akm show ${hit.ref}`,
+        reason: buildCuratedReason(query, shown?.type ?? hit.type),
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+    };
+}
+function buildCuratedRegistryItem(query, hit) {
+    return {
+        source: "registry",
+        type: "registry",
+        name: hit.name,
+        id: hit.id,
+        ...(hit.description ? { description: hit.description } : {}),
+        followUp: hit.action ?? `akm add ${hit.id}`,
+        reason: `Useful external source to explore for ${query}.`,
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+    };
+}
+function firstNonEmpty(values) {
+    return values.find((value) => typeof value === "string" && value.trim().length > 0);
+}
+function buildCuratedPreview(shown, hit) {
+    if (shown?.run)
+        return truncateDescription(`run ${shown.run}`, 160);
+    const payload = firstNonEmpty([shown?.template, shown?.prompt, shown?.content, hit.description])
+        ?.replace(/\s+/g, " ")
+        .trim();
+    return payload ? truncateDescription(payload, 160) : undefined;
+}
+function buildCuratedReason(query, type) {
+    switch (type) {
+        case "script":
+            return `Best runnable script match for "${query}".`;
+        case "command":
+            return `Best reusable command/template match for "${query}".`;
+        case "knowledge":
+            return `Best reference document match for "${query}".`;
+        case "skill":
+            return `Best instructions/workflow match for "${query}".`;
+        case "agent":
+            return `Best specialized agent prompt match for "${query}".`;
+        case "memory":
+            return `Best saved context match for "${query}".`;
+        default:
+            return `Best ${type} match for "${query}".`;
+    }
+}
+function buildCurateSummary(query, items) {
+    if (items.length === 0) {
+        return `No curated assets were selected for "${query}".`;
+    }
+    const labels = items.map((item) => `${item.type}:${item.name}`);
+    return `Selected ${items.length} high-signal result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
+}
+function hasSearchResults(result) {
+    return result.hits.length > 0 || (result.registryHits?.length ?? 0) > 0;
+}
+/**
+ * Extract a small set of fallback keywords when a prompt-style curate query
+ * returns no hits as a whole phrase.
+ *
+ * We keep up to MAX_CURATE_FALLBACK_KEYWORDS distinct keywords and drop short
+ * or common filler words so follow-up searches stay inexpensive while focusing
+ * on higher-signal terms.
+ */
+export function deriveCurateFallbackQueries(query) {
+    return Array.from(new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        // Keep longer tokens so fallback stays focused on higher-signal terms
+        // and avoids broad one- and two-letter matches that overwhelm curation.
+        .filter((token) => token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH && !CURATE_FALLBACK_FILTER_WORDS.has(token)))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+}
+export function mergeCurateSearchResponses(base, extras) {
+    const hitsByRef = new Map();
+    for (const hit of base.hits.filter((entry) => entry.type !== "registry")) {
+        hitsByRef.set(hit.ref, hit);
+    }
+    for (const result of extras) {
+        for (const hit of result.hits.filter((entry) => entry.type !== "registry")) {
+            const existing = hitsByRef.get(hit.ref);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
+                hitsByRef.set(hit.ref, hit);
+            }
+        }
+    }
+    const registryById = new Map();
+    for (const hit of base.registryHits ?? []) {
+        registryById.set(hit.id, hit);
+    }
+    for (const result of extras) {
+        for (const hit of result.registryHits ?? []) {
+            const existing = registryById.get(hit.id);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
+                registryById.set(hit.id, hit);
+            }
+        }
+    }
+    const warnings = Array.from(new Set([...(base.warnings ?? []), ...extras.flatMap((result) => result.warnings ?? [])]));
+    const mergedHits = [...hitsByRef.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const mergedRegistryHits = [...registryById.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    return {
+        ...base,
+        hits: mergedHits,
+        ...(mergedRegistryHits.length > 0 ? { registryHits: mergedRegistryHits } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+        ...(mergedHits.length > 0 || mergedRegistryHits.length > 0 ? { tip: undefined } : {}),
+    };
+}
+export async function searchForCuration(input) {
+    const initial = await akmSearch(input);
+    if (hasSearchResults(initial))
+        return initial;
+    const fallbackQueries = deriveCurateFallbackQueries(input.query);
+    if (fallbackQueries.length <= 1)
+        return initial;
+    const fallbackResults = await Promise.all(fallbackQueries.map((token) => akmSearch({
+        query: token,
+        type: input.type,
+        limit: input.limit,
+        source: input.source,
+    })));
+    return mergeCurateSearchResponses(initial, fallbackResults);
+}

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

@@ -1,32 +1,35 @@
 /**
- * Local (filesystem + SQLite) stash search implementation.
+ * Database-backed (SQLite + FTS5/vector) stash search implementation.
  *
  * Extracted from stash-search.ts to break the circular import:
- *   stash-search.ts → stash-providers/filesystem.ts → local-search.ts (no cycle)
+ *   stash-search.ts → stash-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.
+ *
+ * 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 { defaultRendererRegistry } from "./asset-registry";
 import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
 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,6 +44,7 @@ function resolveSearchHitOrigin(source) {
 // ── Main search entrypoint ───────────────────────────────────────────────────
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
+    const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allStashDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
@@ -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, allStashDirs, 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(allStashDirs.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, allStashDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
     // Empty query: return all entries
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
@@ -134,6 +138,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             allStashDirs,
             sources,
             config,
+            rendererRegistry,
         })));
         return { hits };
     }
@@ -371,6 +376,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         sources,
         config,
         utilityBoosted,
+        rendererRegistry,
     })));
     return { embedMs, rankMs, hits };
 }
@@ -401,20 +407,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 +454,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 +482,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 +541,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 +561,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);
     }