akm-cli 0.0.21 → 0.0.22

package/dist/local-search.js

@@ -0,0 +1,429 @@
+/**
+ * Local (filesystem + SQLite) 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 imports this module for the `searchLocal` export.
+ * stash-providers/filesystem.ts also imports `searchLocal` from here.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { _setAssetTypeHooks, deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, openDatabase, searchFts, searchVec, } from "./db";
+import { getRenderer } from "./file-context";
+import { buildSearchText } from "./indexer";
+import { generateMetadataFlat, loadStashFile } from "./metadata";
+import { getDbPath } from "./paths";
+import { makeAssetRef } from "./stash-ref";
+import { buildEditHint, findSourceForPath, isEditable } from "./stash-source";
+import { walkStashFlat } from "./walker";
+import { warn } from "./warn";
+// ── Type renderer/action maps (re-exported so stash-search.ts can register) ──
+/** Map asset types to their primary renderer names. */
+export const TYPE_TO_RENDERER = {
+    script: "script-source",
+    skill: "skill-md",
+    command: "command-md",
+    agent: "agent-md",
+    knowledge: "knowledge-md",
+    memory: "memory-md",
+};
+export const ACTION_BUILDERS = {
+    script: (ref) => `akm show ${ref} -> execute the run command`,
+    skill: (ref) => `akm show ${ref} -> follow the instructions`,
+    command: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
+    agent: (ref) => `akm show ${ref} -> dispatch with full prompt`,
+    knowledge: (ref) => `akm show ${ref} -> read reference material`,
+    memory: (ref) => `akm show ${ref} -> recall context`,
+};
+// Wire asset-spec's deferred hooks so that registerAssetType() automatically
+// populates TYPE_TO_RENDERER and ACTION_BUILDERS when the optional spec fields
+// rendererName / actionBuilder are provided.
+_setAssetTypeHooks((type, rendererName) => {
+    TYPE_TO_RENDERER[type] = rendererName;
+}, (type, builder) => {
+    ACTION_BUILDERS[type] = builder;
+});
+export async function rendererForType(type) {
+    const name = TYPE_TO_RENDERER[type];
+    return name ? getRenderer(name) : undefined;
+}
+export function buildLocalAction(type, ref) {
+    const builder = ACTION_BUILDERS[type];
+    return builder ? builder(ref) : `akm show ${ref}`;
+}
+// ── Main search entrypoint ───────────────────────────────────────────────────
+export async function searchLocal(input) {
+    const { query, searchType, limit, stashDir, sources, config } = input;
+    const allStashDirs = sources.map((s) => s.path);
+    // Try to open the database
+    const dbPath = getDbPath();
+    try {
+        if (fs.existsSync(dbPath)) {
+            const embeddingDim = config.embedding?.dimension;
+            const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+            try {
+                const entryCount = getEntryCount(db);
+                const storedStashDir = getMeta(db, "stashDir");
+                if (entryCount > 0 && storedStashDir === stashDir) {
+                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources);
+                    return {
+                        hits,
+                        tip: hits.length === 0
+                            ? "No matching stash assets were found. Try running 'akm index' to rebuild."
+                            : undefined,
+                        embedMs,
+                        rankMs,
+                    };
+                }
+            }
+            finally {
+                closeDatabase(db);
+            }
+        }
+    }
+    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 hits = hitArrays.flat().slice(0, limit);
+    return {
+        hits,
+        tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
+    };
+}
+// ── Database search ─────────────────────────────────────────────────────────
+async function searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources) {
+    // Empty query: return all entries
+    if (!query) {
+        const typeFilter = searchType === "any" ? undefined : searchType;
+        const allEntries = getAllEntries(db, typeFilter);
+        const selected = allEntries.slice(0, limit);
+        const hits = await Promise.all(selected.map((ie) => buildDbHit({
+            entry: ie.entry,
+            path: ie.filePath,
+            score: 1,
+            query,
+            rankingMode: "fts",
+            defaultStashDir: stashDir,
+            allStashDirs,
+            sources,
+            config,
+        })));
+        return { hits };
+    }
+    // Score using FTS5 (BM25) and optionally sqlite-vec
+    const tEmbed0 = Date.now();
+    const embeddingScores = await tryVecScores(db, query, limit * 3, config);
+    const embedMs = Date.now() - tEmbed0;
+    const tRank0 = Date.now();
+    const typeFilter = searchType === "any" ? undefined : searchType;
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    // Reciprocal Rank Fusion (RRF) constant
+    const RRF_K = 60;
+    // Build FTS rank map: rank 1 = best BM25, rank 2 = second best, etc.
+    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);
+        }
+    }
+    // Merge results using RRF
+    const scored = [];
+    const seenIds = new Set();
+    // Process FTS results
+    for (const [id, { rank, result }] of ftsRankMap) {
+        seenIds.add(id);
+        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] of embeddingScores) {
+            if (seenIds.has(id))
+                continue;
+            const embedRank = embedRankMap.get(id);
+            if (embedRank === undefined)
+                continue;
+            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: rrfScore,
+                    rankingMode: "semantic",
+                });
+            }
+        }
+    }
+    // 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)) {
+                    boostSum += 0.15;
+                }
+            }
+        }
+        // Search hint boost
+        if (entry.searchHints) {
+            for (const hint of entry.searchHints) {
+                const hintLower = hint.toLowerCase();
+                for (const token of queryTokens) {
+                    if (hintLower.includes(token)) {
+                        boostSum += 0.12;
+                        break;
+                    }
+                }
+            }
+        }
+        // Name boost
+        const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
+        if (queryTokens.some((t) => nameLower.includes(t))) {
+            boostSum += 0.1;
+        }
+        item.score = item.score * (1 + boostSum);
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const rankMs = Date.now() - tRank0;
+    const selected = scored.slice(0, limit);
+    const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode }) => buildDbHit({
+        entry,
+        path: filePath,
+        score: Math.round(score * 100) / 100,
+        query,
+        rankingMode,
+        defaultStashDir: stashDir,
+        allStashDirs,
+        sources,
+        config,
+    })));
+    return { embedMs, rankMs, hits };
+}
+// ── Vector scorer ───────────────────────────────────────────────────────────
+async function tryVecScores(db, query, k, config) {
+    if (!config.semanticSearch)
+        return null;
+    const hasEmbeddings = getMeta(db, "hasEmbeddings");
+    if (hasEmbeddings !== "1")
+        return null;
+    try {
+        const { embed } = await import("./embedder.js");
+        const queryEmbedding = await embed(query, config.embedding);
+        const vecResults = searchVec(db, queryEmbedding, k);
+        const scores = new Map();
+        for (const { id, distance } of vecResults) {
+            // Convert L2 distance to cosine similarity (vectors are normalized)
+            const cosineSim = 1 - (distance * distance) / 2;
+            scores.set(id, Math.max(0, cosineSim));
+        }
+        return scores;
+    }
+    catch (error) {
+        warn("Vector search failed, skipping:", error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+// ── Substring fallback (no index) ───────────────────────────────────────────
+async function substringSearch(query, searchType, limit, stashDir, sources, config) {
+    const assets = await indexAssets(stashDir, searchType);
+    const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
+    if (!query) {
+        return Promise.all(matched
+            .sort(compareAssets)
+            .slice(0, limit)
+            .map((asset) => assetToSearchHit(asset, query, stashDir, sources, config)));
+    }
+    // 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));
+    return Promise.all(scored.slice(0, limit).map(({ asset, score }) => assetToSearchHit(asset, query, stashDir, sources, config, score)));
+}
+function scoreSubstringMatch(entry, query) {
+    const tokens = query.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return 0.5;
+    let score = 0.3;
+    const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
+    const descLower = (entry.description ?? "").toLowerCase();
+    const tagsLower = (entry.tags ?? []).join(" ").toLowerCase();
+    if (nameLower === query) {
+        score += 0.5;
+    }
+    else if (nameLower.includes(query)) {
+        score += 0.35;
+    }
+    else if (tokens.some((t) => nameLower.includes(t))) {
+        score += 0.2;
+    }
+    if (tokens.some((t) => tagsLower.includes(t))) {
+        score += 0.1;
+    }
+    if (tokens.some((t) => descLower.includes(t))) {
+        score += 0.05;
+    }
+    return Math.round(Math.min(1, score) * 100) / 100;
+}
+// ── Hit building ────────────────────────────────────────────────────────────
+export async function buildDbHit(input) {
+    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;
+    const qualityBoost = input.entry.quality === "generated" ? 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.round(input.score * (1 + qualityBoost + confidenceBoost) * 100) / 100;
+    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 = {
+        type: input.entry.type,
+        name: input.entry.name,
+        path: input.path,
+        ref: makeAssetRef(input.entry.type, refName, source?.registryId),
+        origin: source?.registryId ?? null,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, refName, source?.registryId) } : {}),
+        description: input.entry.description,
+        tags: input.entry.tags,
+        size: deriveSize(input.entry.fileSize),
+        action: buildLocalAction(input.entry.type, makeAssetRef(input.entry.type, refName, source?.registryId)),
+        score,
+        whyMatched,
+    };
+    const renderer = await rendererForType(input.entry.type);
+    if (renderer?.enrichSearchHit) {
+        renderer.enrichSearchHit(hit, entryStashDir);
+    }
+    return hit;
+}
+export function buildWhyMatched(entry, query, rankingMode, qualityBoost, confidenceBoost) {
+    const reasons = [rankingMode === "semantic" ? "semantic similarity" : "fts bm25 relevance"];
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const name = entry.name.toLowerCase();
+    const tags = entry.tags?.join(" ").toLowerCase() ?? "";
+    const searchHints = entry.searchHints?.join(" ").toLowerCase() ?? "";
+    const aliases = entry.aliases?.join(" ").toLowerCase() ?? "";
+    if (tokens.some((t) => name.includes(t)))
+        reasons.push("matched name tokens");
+    if (tokens.some((t) => tags.includes(t)))
+        reasons.push("matched tags");
+    if (tokens.some((t) => searchHints.includes(t)))
+        reasons.push("matched searchHints");
+    if (tokens.some((t) => aliases.includes(t)))
+        reasons.push("matched aliases");
+    if (qualityBoost > 0)
+        reasons.push("curated metadata boost");
+    if (confidenceBoost > 0)
+        reasons.push("metadata confidence boost");
+    return reasons;
+}
+async function assetToSearchHit(asset, _query, stashDir, sources, config, score) {
+    const source = findSourceForPath(asset.path, sources);
+    const editable = isEditable(asset.path, config);
+    const ref = makeAssetRef(asset.entry.type, asset.entry.name, source?.registryId);
+    const fileSize = readFileSize(asset.path);
+    const size = deriveSize(fileSize);
+    const hit = {
+        type: asset.entry.type,
+        name: asset.entry.name,
+        path: asset.path,
+        ref,
+        origin: source?.registryId ?? null,
+        editable,
+        ...(!editable
+            ? { editHint: buildEditHint(asset.path, asset.entry.type, asset.entry.name, source?.registryId) }
+            : {}),
+        description: asset.entry.description,
+        tags: asset.entry.tags,
+        ...(size ? { size } : {}),
+        action: buildLocalAction(asset.entry.type, ref),
+        ...(score !== undefined ? { score } : {}),
+    };
+    const renderer = await rendererForType(asset.entry.type);
+    if (renderer?.enrichSearchHit) {
+        renderer.enrichSearchHit(hit, stashDir);
+    }
+    return hit;
+}
+// ── Utilities ────────────────────────────────────────────────────────────────
+export function deriveSize(bytes) {
+    if (bytes === undefined)
+        return undefined;
+    if (bytes < 1024)
+        return "small";
+    if (bytes < 10240)
+        return "medium";
+    return "large";
+}
+function readFileSize(filePath) {
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function indexAssets(stashDir, type) {
+    const assets = [];
+    const filterType = type === "any" ? undefined : type;
+    const fileContexts = walkStashFlat(stashDir);
+    const dirGroups = new Map();
+    for (const ctx of fileContexts) {
+        const group = dirGroups.get(ctx.parentDirAbs);
+        if (group)
+            group.push(ctx.absPath);
+        else
+            dirGroups.set(ctx.parentDirAbs, [ctx.absPath]);
+    }
+    for (const [dirPath, files] of dirGroups) {
+        let stash = loadStashFile(dirPath);
+        if (stash) {
+            const coveredFiles = new Set(stash.entries.map((entry) => entry.filename).filter((entry) => !!entry));
+            const uncoveredFiles = files.filter((file) => !coveredFiles.has(path.basename(file)));
+            if (uncoveredFiles.length > 0) {
+                const generated = await generateMetadataFlat(stashDir, uncoveredFiles);
+                if (generated.entries.length > 0) {
+                    stash = { entries: [...stash.entries, ...generated.entries] };
+                }
+            }
+        }
+        else {
+            const generated = await generateMetadataFlat(stashDir, files);
+            if (generated.entries.length === 0)
+                continue;
+            stash = generated;
+        }
+        for (const entry of stash.entries) {
+            if (filterType && entry.type !== filterType)
+                continue;
+            const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+            assets.push({ entry, path: entryPath });
+        }
+    }
+    return assets;
+}
+function compareAssets(a, b) {
+    if (a.entry.type !== b.entry.type)
+        return a.entry.type.localeCompare(b.entry.type);
+    return a.entry.name.localeCompare(b.entry.name);
+}

package/dist/lockfile.js

@@ -5,6 +5,41 @@ import { getConfigDir } from "./config";
 function getLockfilePath() {
     return path.join(getConfigDir(), "stash.lock");
 }
+// ── Lock sentinel ────────────────────────────────────────────────────────────
+const LOCK_MAX_RETRIES = 3;
+const LOCK_RETRY_DELAY_MS = 100;
+function getLockSentinelPath() {
+    return `${getLockfilePath()}.lck`;
+}
+async function acquireLockSentinel() {
+    const sentinelPath = getLockSentinelPath();
+    // Ensure the directory exists before attempting to create the sentinel
+    fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
+    for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
+        try {
+            fs.writeFileSync(sentinelPath, String(process.pid), { flag: "wx" });
+            return true; // Sentinel created — we own the lock
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // Another process holds the lock — wait briefly before retrying
+            if (attempt < LOCK_MAX_RETRIES - 1) {
+                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
+            }
+        }
+    }
+    // Best-effort: proceed without the lock rather than failing the install
+    return false;
+}
+function releaseLockSentinel() {
+    try {
+        fs.unlinkSync(getLockSentinelPath());
+    }
+    catch {
+        /* ignore — sentinel may already be gone */
+    }
+}
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
     const lockfilePath = getLockfilePath();
@@ -22,7 +57,7 @@ export function writeLockfile(entries) {
     const lockfilePath = getLockfilePath();
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
-    const tmpPath = `${lockfilePath}.tmp.${process.pid}`;
+    const tmpPath = `${lockfilePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
     try {
         fs.writeFileSync(tmpPath, `${JSON.stringify(entries, null, 2)}\n`, "utf8");
         fs.renameSync(tmpPath, lockfilePath);
@@ -37,10 +72,17 @@ export function writeLockfile(entries) {
         throw err;
     }
 }
-export function upsertLockEntry(entry) {
-    const entries = readLockfile();
-    const withoutExisting = entries.filter((e) => e.id !== entry.id);
-    writeLockfile([...withoutExisting, entry]);
+export async function upsertLockEntry(entry) {
+    const acquired = await acquireLockSentinel();
+    try {
+        const entries = readLockfile();
+        const withoutExisting = entries.filter((e) => e.id !== entry.id);
+        writeLockfile([...withoutExisting, entry]);
+    }
+    finally {
+        if (acquired)
+            releaseLockSentinel();
+    }
 }
 export function removeLockEntry(id) {
     const entries = readLockfile();

package/dist/matchers.js

@@ -66,6 +66,9 @@ export function directoryMatcher(ctx) {
     if (topDir === "knowledge" && ext === ".md") {
         return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
     }
+    if (topDir === "memories" && ext === ".md") {
+        return { type: "memory", specificity: 10, renderer: "memory-md" };
+    }
     return null;
 }
 // ── parentDirHintMatcher (specificity: 15) ──────────────────────────────────
@@ -92,6 +95,9 @@ export function parentDirHintMatcher(ctx) {
     if (parentDir === "knowledge" && ext === ".md") {
         return { type: "knowledge", specificity: 15, renderer: "knowledge-md" };
     }
+    if (parentDir === "memories" && ext === ".md") {
+        return { type: "memory", specificity: 15, renderer: "memory-md" };
+    }
     return null;
 }
 // ── smartMdMatcher (specificity: 20 / 18 / 8 / 5) ──────────────────────────

package/dist/metadata.js

@@ -39,7 +39,7 @@ export function loadStashFile(dirPath) {
 }
 export function writeStashFile(dirPath, stash) {
     const filePath = stashFilePath(dirPath);
-    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    const tmpPath = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
     try {
         fs.writeFileSync(tmpPath, `${JSON.stringify(stash, null, 2)}\n`, "utf8");
         fs.renameSync(tmpPath, filePath);
@@ -54,6 +54,14 @@ export function writeStashFile(dirPath, stash) {
         throw err;
     }
 }
+/**
+ * Validate and normalize a raw object into a `StashEntry`.
+ *
+ * **Ordering dependency:** Uses `isAssetType()` to check `entry.type`, which
+ * only recognizes custom types registered via `registerAssetType()`. If this
+ * function is called before custom types are registered, those entries will be
+ * rejected as invalid.
+ */
 export function validateStashEntry(entry) {
     if (typeof entry !== "object" || entry === null)
         return null;
@@ -115,6 +123,8 @@ export function validateStashEntry(entry) {
     const usage = normalizeNonEmptyStringList(e.usage);
     if (usage)
         result.usage = usage;
+    // SECURITY NOTE: run, setup, and cwd are advisory metadata fields for AI agent consumers.
+    // They are NOT executed by akm directly. Consumers should validate and sanitize before execution.
     if (typeof e.run === "string" && e.run.trim())
         result.run = e.run.trim();
     if (typeof e.setup === "string" && e.setup.trim())
@@ -139,7 +149,7 @@ function normalizeNonEmptyStringList(value) {
     return filtered.length > 0 ? filtered : undefined;
 }
 // ── Metadata Generation ─────────────────────────────────────────────────────
-export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
+export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
     const pkgMeta = extractPackageMetadata(dirPath);
     for (const file of files) {
@@ -178,9 +188,9 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
         }
         // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
         const fileCtx = buildFileContext(typeRoot, file);
-        const match = runMatchers(fileCtx);
+        const match = await runMatchers(fileCtx);
         if (match) {
-            const renderer = getRenderer(match.renderer);
+            const renderer = await getRenderer(match.renderer);
             if (renderer?.extractMetadata) {
                 const renderCtx = buildRenderContext(fileCtx, match, [typeRoot]);
                 renderer.extractMetadata(entry, renderCtx);
@@ -211,12 +221,12 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
  * file via `runMatchers()` and uses the matched type for canonical naming.
  * Files that no matcher claims are silently skipped.
  */
-export function generateMetadataFlat(stashRoot, files) {
+export async function generateMetadataFlat(stashRoot, files) {
     const entries = [];
     const pkgMetaCache = new Map();
     for (const file of files) {
         const ctx = buildFileContext(stashRoot, file);
-        const match = runMatchers(ctx);
+        const match = await runMatchers(ctx);
         if (!match)
             continue;
         const assetType = match.type;
@@ -260,7 +270,7 @@ export function generateMetadataFlat(stashRoot, files) {
             }
         }
         // Renderer metadata extraction
-        const renderer = getRenderer(match.renderer);
+        const renderer = await getRenderer(match.renderer);
         if (renderer?.extractMetadata) {
             const renderCtx = buildRenderContext(ctx, match, [stashRoot]);
             renderer.extractMetadata(entry, renderCtx);
@@ -288,9 +298,9 @@ function normalizeTerms(values) {
         if (!cleaned)
             continue;
         normalized.add(cleaned);
-        if (cleaned.endsWith("s") && cleaned.length > 3) {
-            normalized.add(cleaned.slice(0, -1));
-        }
+        // De-pluralization heuristic removed: the FTS5 porter stemmer (configured
+        // with `tokenize='porter unicode61'`) handles stemming correctly, including
+        // edge cases like "kubernetes" and "status" that the naive s-strip mangled.
     }
     return Array.from(normalized);
 }

package/dist/paths.js

@@ -51,6 +51,10 @@ export function getCacheDir() {
         if (!appData) {
             throw new ConfigError("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
         }
+        // Heuristic fallback: APPDATA points to %APPDATA% (Roaming), so navigate
+        // to the sibling "Local" directory. This is typically
+        // C:\Users\<name>\AppData\Roaming → C:\Users\<name>\AppData\Local\akm.
+        // Preferred: set LOCALAPPDATA to avoid this navigation.
         return path.join(appData, "..", "Local", "akm");
     }
     const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();

package/dist/providers/skills-sh.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry } from "../common";
 import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../provider-registry";
+import { registerProvider } from "../registry-factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -132,7 +132,8 @@ class SkillsShProvider {
             const dir = path.dirname(cachePath);
             fs.mkdirSync(dir, { recursive: true });
             const tmpPath = `${cachePath}.tmp.${process.pid}`;
-            fs.writeFileSync(tmpPath, JSON.stringify(entries), "utf8");
+            // 0o600: owner read/write only — cache may contain search terms tied to API keys
+            fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
             fs.renameSync(tmpPath, cachePath);
         }
         catch {

package/dist/providers/static-index.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry } from "../common";
+import { fetchWithRetry, toErrorMessage } from "../common";
+import { asString } from "../github";
 import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../provider-registry";
+import { registerProvider } from "../registry-factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
@@ -100,7 +101,7 @@ export function writeCachedIndex(cachePath, index) {
     try {
         const dir = path.dirname(cachePath);
         fs.mkdirSync(dir, { recursive: true });
-        const tmpPath = `${cachePath}.tmp.${process.pid}`;
+        const tmpPath = `${cachePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
         fs.writeFileSync(tmpPath, JSON.stringify(index), "utf8");
         fs.renameSync(tmpPath, cachePath);
     }
@@ -316,9 +317,6 @@ function scoreAsset(asset, tokens) {
     return tokens.length > 0 ? score / tokens.length : 0;
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
-function asString(value) {
-    return typeof value === "string" && value ? value : undefined;
-}
 function asSource(value) {
     if (value === "npm" || value === "github" || value === "git" || value === "local")
         return value;
@@ -342,6 +340,3 @@ function buildInstallRef(source, ref) {
             return `github:${ref}`;
     }
 }
-function toErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}