agentikit 0.0.13 → 0.0.15

package/dist/{src/stash-search.js → stash-search.js}

@@ -1,13 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
-import { ASSET_TYPES, TYPE_DIRS, deriveCanonicalAssetName } from "./asset-spec";
-import { walkStash } from "./walker";
-import { makeAssetRef } from "./stash-ref";
+import { ASSET_TYPES, deriveCanonicalAssetName, TYPE_DIRS } from "./asset-spec";
+import { tryGetHandler } from "./asset-type-handler";
 import { loadConfig } from "./config";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, openDatabase, searchFts, searchVec, } from "./db";
+import { UsageError } from "./errors";
+import { getDbPath } from "./paths";
 import { searchRegistry } from "./registry-search";
-import { openDatabase, closeDatabase, getDbPath, getMeta, searchFts, searchVec, getAllEntries, getEntryCount, getEntryById, isVecAvailable, } from "./db";
-import { tryGetHandler } from "./asset-type-handler";
-import { resolveStashSources, findSourceForPath } from "./stash-source";
+import { makeAssetRef } from "./stash-ref";
+import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./stash-source";
+import { walkStash } from "./walker";
+import { warn } from "./warn";
 const DEFAULT_LIMIT = 20;
 export async function agentikitSearch(input) {
     const t0 = Date.now();
@@ -17,7 +20,17 @@ export async function agentikitSearch(input) {
     const limit = normalizeLimit(input.limit);
     const usageMode = parseSearchUsageMode(input.usage);
     const source = parseSearchSource(input.source);
-    const sources = resolveStashSources();
+    const config = loadConfig();
+    const sources = resolveStashSources(undefined, config);
+    if (sources.length === 0) {
+        return {
+            stashDir: "",
+            source: source ?? "all",
+            hits: [],
+            warnings: ["No stash sources configured. Run `akm init` first."],
+            timing: { totalMs: Date.now() - t0 },
+        };
+    }
     const stashDir = sources[0].path;
     const localResult = source === "registry"
         ? undefined
@@ -28,11 +41,9 @@ export async function agentikitSearch(input) {
             usageMode,
             stashDir,
             sources,
+            config,
         });
-    const config = loadConfig();
-    const registryResult = source === "local"
-        ? undefined
-        : await searchRegistry(query, { limit, registryUrls: config.registryUrls });
+    const registryResult = source === "local" ? undefined : await searchRegistry(query, { limit, registryUrls: config.registryUrls });
     if (source === "local") {
         return {
             stashDir,
@@ -40,11 +51,12 @@ export async function agentikitSearch(input) {
             hits: localResult?.hits ?? [],
             usageGuide: localResult?.usageGuide,
             tip: localResult?.tip,
+            warnings: localResult?.warnings,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
-        const installRef = hit.source === "npm" ? `npm:${hit.ref}` : `github:${hit.ref}`;
+        const installRef = hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`;
         return {
             hitSource: "registry",
             type: "registry",
@@ -73,19 +85,19 @@ export async function agentikitSearch(input) {
         };
     }
     const mergedHits = mergeSearchHits(localResult?.hits ?? [], registryHits, limit);
+    const warnings = [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])];
     return {
         stashDir,
         source,
         hits: mergedHits,
         usageGuide: localResult?.usageGuide,
         tip: mergedHits.length === 0 ? "No matching stash assets or registry entries were found." : undefined,
-        warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
+        warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
 }
 async function searchLocal(input) {
-    const { query, searchType, limit, usageMode, stashDir, sources } = input;
-    const config = loadConfig();
+    const { query, searchType, limit, usageMode, stashDir, sources, config } = input;
     const allStashDirs = sources.map((s) => s.path);
     // Try to open the database
     const dbPath = getDbPath();
@@ -101,7 +113,9 @@ async function searchLocal(input) {
                     return {
                         hits,
                         usageGuide,
-                        tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
+                        tip: hits.length === 0
+                            ? "No matching stash assets were found. Try running 'akm index' to rebuild."
+                            : undefined,
                         embedMs,
                         rankMs,
                     };
@@ -113,12 +127,14 @@ async function searchLocal(input) {
         }
     }
     catch (error) {
-        console.warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
+        warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
     const hits = allStashDirs
-        .flatMap((dir) => substringSearch(query, searchType, limit, dir, sources))
+        .flatMap((dir) => substringSearch(query, searchType, limit, dir, sources, config))
         .slice(0, limit);
-    const usageGuide = shouldIncludeUsageGuide(usageMode) ? buildUsageGuide(hits.map((hit) => hit.type), searchType) : undefined;
+    const usageGuide = shouldIncludeUsageGuide(usageMode)
+        ? buildUsageGuide(hits.map((hit) => hit.type), searchType)
+        : undefined;
     return {
         hits,
         usageGuide,
@@ -142,6 +158,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             allStashDirs,
             sources,
             includeItemUsage: shouldIncludeItemUsage(usageMode),
+            config,
         }));
         return {
             hits,
@@ -157,58 +174,67 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
     const tRank0 = Date.now();
     const typeFilter = searchType === "any" ? undefined : searchType;
     const ftsResults = searchFts(db, query, limit * 3, typeFilter);
-    // Build score map from FTS results (normalize BM25 scores)
-    const ftsScoreMap = new Map();
-    for (const r of ftsResults) {
-        // BM25 returns negative scores (more negative = better match), normalize to 0-1
-        const absScore = Math.abs(r.bm25Score);
-        const normalized = absScore / (1 + absScore);
-        ftsScoreMap.set(r.id, { score: normalized, result: r });
+    // Reciprocal Rank Fusion (RRF) constant
+    const RRF_K = 60;
+    // Build FTS rank map: rank 1 = best BM25, rank 2 = second best, etc.
+    // FTS results are already sorted by bm25Score (ascending, more negative = better)
+    const ftsRankMap = new Map();
+    for (let i = 0; i < ftsResults.length; i++) {
+        const r = ftsResults[i];
+        ftsRankMap.set(r.id, { rank: i + 1, result: r });
+    }
+    // Build embedding rank map: sort by cosine similarity descending
+    const embedRankMap = new Map();
+    if (embeddingScores) {
+        const sortedEmbeddings = [...embeddingScores.entries()].sort((a, b) => b[1] - a[1]);
+        for (let i = 0; i < sortedEmbeddings.length; i++) {
+            embedRankMap.set(sortedEmbeddings[i][0], i + 1);
+        }
     }
-    // Blend scores
+    // Merge results using RRF
     const scored = [];
     const seenIds = new Set();
     // Process FTS results
-    for (const [id, { score: ftsScore, result }] of ftsScoreMap) {
+    for (const [id, { rank, result }] of ftsRankMap) {
         seenIds.add(id);
-        const embScore = embeddingScores?.get(id);
-        if (embScore !== undefined) {
-            const blended = embScore * 0.7 + ftsScore * 0.3;
-            if (blended > 0)
-                scored.push({ id, entry: result.entry, filePath: result.filePath, score: blended, rankingMode: "semantic" });
-        }
-        else if (ftsScore > 0) {
-            scored.push({ id, entry: result.entry, filePath: result.filePath, score: ftsScore, rankingMode: "fts" });
-        }
+        const ftsRrf = 1 / (RRF_K + rank);
+        const embedRank = embedRankMap.get(id);
+        const embedRrf = embedRank !== undefined ? 1 / (RRF_K + embedRank) : 0;
+        const rrfScore = ftsRrf + embedRrf;
+        const rankingMode = embedRrf > 0 ? "semantic" : "fts";
+        scored.push({ id, entry: result.entry, filePath: result.filePath, score: rrfScore, rankingMode });
     }
     // Add vec-only results not already in FTS results
     if (embeddingScores) {
-        for (const [id, embScore] of embeddingScores) {
+        for (const [id] of embeddingScores) {
             if (seenIds.has(id))
                 continue;
+            const embedRank = embedRankMap.get(id);
             const found = getEntryById(db, id);
             if (found) {
                 if (typeFilter && found.entry.type !== typeFilter)
                     continue;
+                const rrfScore = 1 / (RRF_K + embedRank);
                 scored.push({
                     id,
                     entry: found.entry,
                     filePath: found.filePath,
-                    score: embScore,
+                    score: rrfScore,
                     rankingMode: "semantic",
                 });
             }
         }
     }
-    // Apply boosts (tag, intent, name matches)
+    // Apply boosts as multiplicative factors
     const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     for (const item of scored) {
         const entry = item.entry;
+        let boostSum = 0;
         // Tag boost
         if (entry.tags) {
             for (const tag of entry.tags) {
                 if (queryTokens.some((t) => tag.toLowerCase() === t)) {
-                    item.score += 0.15;
+                    boostSum += 0.15;
                 }
             }
         }
@@ -218,7 +244,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
                 const intentLower = intent.toLowerCase();
                 for (const token of queryTokens) {
                     if (intentLower.includes(token)) {
-                        item.score += 0.12;
+                        boostSum += 0.12;
                         break;
                     }
                 }
@@ -227,11 +253,9 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         // Name boost
         const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
         if (queryTokens.some((t) => nameLower.includes(t))) {
-            item.score += 0.1;
+            boostSum += 0.1;
         }
-    }
-    for (const item of scored) {
-        item.score = Math.min(item.score, 1.0);
+        item.score = item.score * (1 + boostSum);
     }
     scored.sort((a, b) => b.score - a.score);
     const rankMs = Date.now() - tRank0;
@@ -246,6 +270,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         allStashDirs,
         sources,
         includeItemUsage: shouldIncludeItemUsage(usageMode),
+        config,
     }));
     return {
         embedMs,
@@ -258,7 +283,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
-    if (!config.semanticSearch || !isVecAvailable())
+    if (!config.semanticSearch)
         return null;
     const hasEmbeddings = getMeta(db, "hasEmbeddings");
     if (hasEmbeddings !== "1")
@@ -276,30 +301,30 @@ async function tryVecScores(db, query, k, config) {
         return scores;
     }
     catch (error) {
-        console.warn("Vector search failed, skipping:", error instanceof Error ? error.message : String(error));
+        warn("Vector search failed, skipping:", error instanceof Error ? error.message : String(error));
         return null;
     }
 }
 // ── Substring fallback (no index) ───────────────────────────────────────────
-function substringSearch(query, searchType, limit, stashDir, sources) {
+function substringSearch(query, searchType, limit, stashDir, sources, config) {
     const assets = indexAssets(stashDir, searchType);
     return assets
         .filter((asset) => asset.name.toLowerCase().includes(query))
         .sort(compareAssets)
         .slice(0, limit)
-        .map((asset) => assetToSearchHit(asset, stashDir, sources));
+        .map((asset) => assetToSearchHit(asset, stashDir, sources, config));
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 function buildDbHit(input) {
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
     const typeRoot = path.join(entryStashDir, TYPE_DIRS[input.entry.type]);
-    const openRefName = deriveCanonicalAssetName(input.entry.type, typeRoot, input.path)
-        ?? input.entry.name;
+    const openRefName = deriveCanonicalAssetName(input.entry.type, typeRoot, input.path) ?? input.entry.name;
     const qualityBoost = input.entry.generated === true ? 0 : 0.05;
     const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
-    const score = Math.min(Math.round((input.score + qualityBoost + confidenceBoost) * 1000) / 1000, 1.0);
+    const score = Math.round(input.score * (1 + qualityBoost + confidenceBoost) * 1000) / 1000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost);
     const source = findSourceForPath(input.path, input.sources);
+    const editable = isEditable(input.path, input.config);
     const hit = {
         hitSource: "local",
         type: input.entry.type,
@@ -307,7 +332,8 @@ function buildDbHit(input) {
         path: input.path,
         openRef: makeAssetRef(input.entry.type, openRefName, source?.registryId),
         registryId: source?.registryId,
-        editable: source?.writable ?? false,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, openRefName, source?.registryId) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         score,
@@ -344,8 +370,9 @@ function buildWhyMatched(entry, query, rankingMode, qualityBoost, confidenceBoos
     return reasons;
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function assetToSearchHit(asset, stashDir, sources) {
+function assetToSearchHit(asset, stashDir, sources, config) {
     const source = findSourceForPath(asset.path, sources);
+    const editable = isEditable(asset.path, config);
     const hit = {
         hitSource: "local",
         type: asset.type,
@@ -353,7 +380,8 @@ function assetToSearchHit(asset, stashDir, sources) {
         path: asset.path,
         openRef: makeAssetRef(asset.type, asset.name, source?.registryId),
         registryId: source?.registryId,
-        editable: source?.writable ?? false,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(asset.path, asset.type, asset.name, source?.registryId) } : {}),
     };
     const handler = tryGetHandler(asset.type);
     if (handler?.enrichSearchHit) {
@@ -373,32 +401,19 @@ function parseSearchUsageMode(mode) {
     }
     if (typeof mode === "undefined")
         return "both";
-    throw new Error(`Invalid usage mode: ${String(mode)}. Expected one of: none|both|item|guide`);
+    throw new UsageError(`Invalid usage mode: ${String(mode)}. Expected one of: none|both|item|guide`);
 }
 function parseSearchSource(source) {
     if (source === "local" || source === "registry" || source === "both")
         return source;
     if (typeof source === "undefined")
         return "local";
-    throw new Error(`Invalid search source: ${String(source)}. Expected one of: local|registry|both`);
+    throw new UsageError(`Invalid search source: ${String(source)}. Expected one of: local|registry|both`);
 }
 function mergeSearchHits(localHits, registryHits, limit) {
-    const merged = [];
-    let localIndex = 0;
-    let registryIndex = 0;
-    while (merged.length < limit && (localIndex < localHits.length || registryIndex < registryHits.length)) {
-        if (localIndex < localHits.length) {
-            merged.push(localHits[localIndex]);
-            localIndex += 1;
-            if (merged.length >= limit)
-                break;
-        }
-        if (registryIndex < registryHits.length) {
-            merged.push(registryHits[registryIndex]);
-            registryIndex += 1;
-        }
-    }
-    return merged;
+    const all = [...localHits, ...registryHits];
+    all.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    return all.slice(0, limit);
 }
 function shouldIncludeUsageGuide(mode) {
     return mode === "both" || mode === "guide";

package/dist/stash-show.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import { getHandler } from "./asset-type-handler";
+import { loadConfig } from "./config";
+import { NotFoundError } from "./errors";
+import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
+import { resolveSourcesForOrigin } from "./origin-resolve";
+import { parseAssetRef } from "./stash-ref";
+import { resolveAssetPath } from "./stash-resolve";
+import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./stash-source";
+export async function agentikitShow(input) {
+    const parsed = parseAssetRef(input.ref);
+    const config = loadConfig();
+    const allSources = resolveStashSources();
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    const allStashDirs = searchSources.map((s) => s.path);
+    let assetPath;
+    let lastError;
+    for (const dir of allStashDirs) {
+        try {
+            assetPath = resolveAssetPath(dir, parsed.type, parsed.name);
+            break;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    if (!assetPath && parsed.origin && searchSources.length === 0) {
+        const installCmd = `akm add ${parsed.origin}`;
+        throw new NotFoundError(`Stash asset not found for ref: ${parsed.type}:${parsed.name}. ` +
+            `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`);
+    }
+    if (!assetPath) {
+        throw lastError ?? new NotFoundError(`Stash asset not found for ref: ${parsed.type}:${parsed.name}`);
+    }
+    const source = findSourceForPath(assetPath, allSources);
+    const sourceStashDir = source?.path ?? allStashDirs[0];
+    // Try new renderer pipeline first
+    if (sourceStashDir) {
+        const fileCtx = buildFileContext(sourceStashDir, assetPath);
+        const match = runMatchers(fileCtx);
+        if (match) {
+            match.meta = { ...match.meta, name: parsed.name, view: input.view };
+            const renderer = getRenderer(match.renderer);
+            if (renderer) {
+                const renderCtx = buildRenderContext(fileCtx, match, allStashDirs);
+                const response = renderer.buildShowResponse(renderCtx);
+                const editable = isEditable(assetPath, config);
+                return {
+                    ...response,
+                    registryId: source?.registryId,
+                    editable,
+                    ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
+                };
+            }
+        }
+    }
+    // Fallback to legacy handler
+    const content = fs.readFileSync(assetPath, "utf8");
+    const handler = getHandler(parsed.type);
+    const response = handler.buildShowResponse({
+        name: parsed.name,
+        path: assetPath,
+        content,
+        view: input.view,
+        stashDirs: allStashDirs,
+    });
+    const editable = isEditable(assetPath, config);
+    return {
+        ...response,
+        registryId: source?.registryId,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
+    };
+}

package/dist/stash-source.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "./common";
+import { loadConfig } from "./config";
+import { warn } from "./warn";
+// ── Resolution ──────────────────────────────────────────────────────────────
+/**
+ * Build the ordered list of stash sources (search paths):
+ *   1. Primary stash dir (user's own, destination for clone)
+ *   2. Additional search paths (user-configured)
+ *   3. Installed kit paths (cache-managed, from registry)
+ *
+ * The first entry is always the primary stash. Additional entries come
+ * from `searchPaths` config and `registry.installed` entries.
+ */
+export function resolveStashSources(overrideStashDir, existingConfig) {
+    const stashDir = overrideStashDir ?? resolveStashDir();
+    const config = existingConfig ?? loadConfig();
+    const sources = [{ path: stashDir }];
+    for (const dir of config.searchPaths) {
+        if (isSuspiciousStashRoot(dir)) {
+            warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(dir)) {
+            sources.push({ path: dir });
+        }
+    }
+    for (const entry of config.registry?.installed ?? []) {
+        if (isSuspiciousStashRoot(entry.stashRoot)) {
+            warn(`Warning: stash root "${entry.stashRoot}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(entry.stashRoot)) {
+            sources.push({
+                path: entry.stashRoot,
+                registryId: entry.id,
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export function resolveAllStashDirs(overrideStashDir) {
+    return resolveStashSources(overrideStashDir).map((s) => s.path);
+}
+/**
+ * Find which source a file path belongs to.
+ */
+export function findSourceForPath(filePath, sources) {
+    const resolved = path.resolve(filePath);
+    for (const source of sources) {
+        if (resolved.startsWith(path.resolve(source.path) + path.sep))
+            return source;
+    }
+    return undefined;
+}
+/**
+ * Return the primary stash source (first entry in the list).
+ * This is the user's working stash and the default destination for clone.
+ */
+export function getPrimarySource(sources) {
+    return sources[0];
+}
+// ── Editability ─────────────────────────────────────────────────────────────
+/**
+ * Determine whether a file is safe to edit in place.
+ *
+ * The only files that are NOT editable are those inside a cache directory
+ * managed by the package manager (`registry.installed[].cacheDir`). These
+ * will be overwritten by `akm update` without warning.
+ *
+ * Everything else — working stash, search paths, local project dirs — is
+ * the user's domain to manage.
+ */
+export function isEditable(filePath, config) {
+    const cfg = config ?? loadConfig();
+    const resolved = path.resolve(filePath);
+    const cacheManaged = cfg.registry?.installed ?? [];
+    const isWin = process.platform === "win32";
+    for (const entry of cacheManaged) {
+        const cacheRoot = path.resolve(entry.cacheDir);
+        if (isWin) {
+            // Windows paths are case-insensitive — normalize both sides
+            if (resolved.toLowerCase().startsWith(cacheRoot.toLowerCase() + path.sep))
+                return false;
+        }
+        else {
+            if (resolved.startsWith(cacheRoot + path.sep))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Build an actionable hint for the agent when a file is not editable.
+ * Callers must check `isEditable()` before calling — this function
+ * unconditionally returns the hint string.
+ */
+export function buildEditHint(filePath, assetType, assetName, origin) {
+    const ref = origin ? `${origin}//${assetType}:${assetName}` : `${assetType}:${assetName}`;
+    return `This asset is managed by akm and may be overwritten on update. To edit, run: akm clone ${ref}`;
+}
+// ── Validation ──────────────────────────────────────────────────────────────
+const SUSPICIOUS_ROOTS = new Set(["/", "/etc", "/bin", "/sbin", "/usr", "/var", "/tmp", "/dev", "/proc", "/sys"]);
+function isSuspiciousStashRoot(dir) {
+    const resolved = path.resolve(dir);
+    const normalized = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    if (SUSPICIOUS_ROOTS.has(normalized))
+        return true;
+    if (process.platform === "win32") {
+        // Check for Windows system directories
+        const winDir = (process.env.SystemRoot || "C:\\Windows").toLowerCase();
+        if (normalized === winDir || normalized.startsWith(winDir + path.sep))
+            return true;
+    }
+    return false;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}