akm-cli 0.1.3 → 0.2.1

package/dist/stash-search.js

@@ -1,11 +1,13 @@
 import { loadConfig } from "./config";
-import { ACTION_BUILDERS, buildLocalAction, rendererForType, searchLocal, TYPE_TO_RENDERER } from "./local-search";
+import { closeDatabase, openDatabase } from "./db";
+import { searchLocal } from "./local-search";
 import { resolveStashProviders } from "./stash-provider-factory";
 // Eagerly import stash providers to trigger self-registration
 import "./stash-providers/index";
 import { UsageError } from "./errors";
 import { searchRegistry } from "./registry-search";
 import { resolveStashSources } from "./search-source";
+import { insertUsageEvent } from "./usage-events";
 const DEFAULT_LIMIT = 20;
 export async function akmSearch(input) {
     const t0 = Date.now();
@@ -19,7 +21,7 @@ export async function akmSearch(input) {
     if (sources.length === 0) {
         // stashDir: "" is a safe sentinel here — the response carries zero hits
         // and a warning, so no downstream code will try to use the empty path.
-        return {
+        const response = {
             schemaVersion: 1,
             stashDir: "",
             source,
@@ -27,12 +29,16 @@ export async function akmSearch(input) {
             warnings: ["No stashes configured. Run `akm init` to create your working stash."],
             timing: { totalMs: Date.now() - t0 },
         };
+        logSearchEvent(query, response);
+        return response;
     }
     // Primary stash directory — used for DB path lookups and as the default
     // stash root. Safe because the empty-sources case is handled above.
     const stashDir = sources[0].path;
-    // Resolve additional stash providers (e.g. OpenViking) from config
-    const additionalStashProviders = resolveStashProviders(config);
+    // Resolve additional stash providers (e.g. OpenViking) from config.
+    // Exclude filesystem (handled by resolveStashSources) and context-hub/github
+    // (content now indexed through the unified FTS5 pipeline).
+    const additionalStashProviders = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.type !== "context-hub" && p.type !== "git");
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -43,8 +49,8 @@ export async function akmSearch(input) {
             sources,
             config,
         });
-    // Query additional stash providers (e.g. OpenViking)
-    const additionalStashResults = source === "registry" || additionalStashProviders.length === 0 || !query
+    // Pass original case to providers — FTS5 requires lowercase but remote providers handle case themselves
+    const additionalStashResults = source === "registry" || additionalStashProviders.length === 0
         ? []
         : await Promise.all(additionalStashProviders.map(async (provider) => {
             try {
@@ -65,7 +71,7 @@ export async function akmSearch(input) {
         const allStashHits = mergeStashHits(localResult?.hits ?? [], additionalHits, limit);
         const localWarnings = [...(localResult?.warnings ?? []), ...additionalWarnings];
         const hasResults = allStashHits.length > 0;
-        return {
+        const response = {
             schemaVersion: 1,
             stashDir,
             source,
@@ -74,9 +80,14 @@ export async function akmSearch(input) {
             warnings: localWarnings.length > 0 ? localWarnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
+        logSearchEvent(query, response);
+        return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
-        const installRef = hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`;
+        // Use the provider-supplied installRef when available (already correctly
+        // prefixed), otherwise derive it from source + ref for backward compat.
+        const installRef = hit.installRef ??
+            (hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`);
         return {
             type: "registry",
             name: hit.title,
@@ -89,76 +100,118 @@ export async function akmSearch(input) {
         };
     });
     if (source === "registry") {
-        const hits = registryHits.slice(0, limit);
-        const hasResults = hits.length > 0;
-        return {
+        const slicedRegistryHits = registryHits.slice(0, limit);
+        const hasResults = slicedRegistryHits.length > 0;
+        const response = {
             schemaVersion: 1,
             stashDir,
             source,
-            hits,
+            hits: [],
+            registryHits: slicedRegistryHits,
             tip: hasResults ? undefined : "No matching registry entries were found.",
             warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0 },
         };
+        logSearchEvent(query, response);
+        return response;
     }
     // source === "both"
     const allStashHits = mergeStashHits(localResult?.hits ?? [], additionalHits, limit * 2);
-    const mergedHits = mergeSearchHits(allStashHits, registryHits, limit);
     const warnings = [...(localResult?.warnings ?? []), ...additionalWarnings, ...(registryResult?.warnings ?? [])];
-    const hasResults = mergedHits.length > 0;
-    return {
+    const hasResults = allStashHits.length > 0 || registryHits.length > 0;
+    const response = {
         schemaVersion: 1,
         stashDir,
         source,
-        hits: mergedHits,
+        hits: allStashHits.slice(0, limit),
+        registryHits,
         tip: hasResults ? undefined : "No matching stash assets or registry entries were found.",
         warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
+    logSearchEvent(query, response);
+    return response;
 }
-// Re-export searchLocal so existing callers (filesystem.ts) still work via this module
-export { searchLocal };
-// ── Type renderer and action builder registration ────────────────────────────
-export function registerTypeRenderer(type, rendererName) {
-    TYPE_TO_RENDERER[type] = rendererName;
+/**
+ * Resolve entry IDs by file_path lookup (exact match, not LIKE).
+ */
+function resolveEntryIds(db, hits) {
+    const results = [];
+    const stmt = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1");
+    for (const hit of hits) {
+        try {
+            const row = stmt.get(hit.path);
+            if (row)
+                results.push({ entryId: row.id, ref: hit.ref });
+        }
+        catch {
+            /* skip unresolvable */
+        }
+    }
+    return results;
 }
-export function registerActionBuilder(type, builder) {
-    ACTION_BUILDERS[type] = builder;
+/**
+ * Fire-and-forget: log a search event to the usage_events table.
+ * Never blocks the caller; errors are silently ignored.
+ */
+function logSearchEvent(query, response, existingDb) {
+    try {
+        const db = existingDb ?? openDatabase();
+        try {
+            const stashHits = response.hits.filter((h) => h.type !== "registry").slice(0, 50);
+            const resolved = resolveEntryIds(db, stashHits);
+            for (const { entryId, ref } of resolved) {
+                insertUsageEvent(db, {
+                    event_type: "search",
+                    query,
+                    entry_id: entryId,
+                    entry_ref: ref,
+                });
+            }
+            insertUsageEvent(db, {
+                event_type: "search",
+                query,
+                metadata: JSON.stringify({ resultCount: response.hits.length, resolvedCount: resolved.length }),
+            });
+        }
+        finally {
+            if (!existingDb)
+                closeDatabase(db);
+        }
+    }
+    catch {
+        /* fire-and-forget */
+    }
 }
-// Re-export for consumers that were already importing from stash-search
-export { buildLocalAction, rendererForType };
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
- * Merge hits from local stash and additional providers using Reciprocal Rank
- * Fusion (RRF). Each list is already internally sorted by relevance. RRF
- * assigns scores based on rank position rather than raw score values, so
- * sources with incompatible score scales (e.g. RRF ~0.01-0.03 vs 0-1 or
- * 0-100) are merged fairly.
+ * Merge local and additional stash hits into a single ranked list.
+ *
+ * Provider hits (e.g. OpenViking) keep their original scores and compete
+ * fairly alongside local hits. Duplicates are resolved in favour of the
+ * local version.
+ *
+ * 1. Build set of local hit keys for dedup.
+ * 2. Filter provider hits that aren't duplicates.
+ * 3. Combine local + non-duplicate provider hits.
+ * 4. Sort by score descending.
+ * 5. Slice to limit.
  */
 export function mergeStashHits(localHits, additionalHits, limit) {
     if (additionalHits.length === 0)
         return localHits.slice(0, limit);
-    const RRF_K = 60;
-    const scoreMap = new Map();
-    const applyRankedList = (hits) => {
-        for (let i = 0; i < hits.length; i++) {
-            const key = hits[i].path ?? hits[i].ref ?? hits[i].name;
-            const rrf = 1 / (RRF_K + i + 1);
-            const existing = scoreMap.get(key);
-            if (existing) {
-                existing.score += rrf;
-            }
-            else {
-                scoreMap.set(key, { hit: hits[i], score: rrf });
-            }
-        }
-    };
-    applyRankedList(localHits);
-    applyRankedList(additionalHits);
-    return [...scoreMap.values()]
-        .sort((a, b) => b.score - a.score)
-        .slice(0, limit)
-        .map((v) => ({ ...v.hit, score: Math.round(v.score * 10000) / 10000 }));
+    // Track local hits by a dedup key (path > ref > name)
+    const localKeys = new Set();
+    for (const h of localHits) {
+        localKeys.add(h.path ?? h.ref ?? h.name);
+    }
+    // Keep non-duplicate provider hits with their original scores
+    const providerOnly = additionalHits.filter((h) => {
+        const key = h.path ?? h.ref ?? h.name;
+        return !localKeys.has(key);
+    });
+    // Combine and sort by score descending
+    return [...localHits, ...providerOnly].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, limit);
 }
 function normalizeLimit(limit) {
     if (typeof limit !== "number" || Number.isNaN(limit) || limit <= 0) {
@@ -177,45 +230,8 @@ export function parseSearchSource(source) {
     throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`);
 }
 /**
- * Merge stash hits and registry hits using RRF, same rationale as mergeStashHits.
+ * Merge stash hits and registry hits via simple concatenation.
  */
 export function mergeSearchHits(localHits, registryHits, limit) {
-    if (registryHits.length === 0)
-        return localHits.slice(0, limit);
-    if (localHits.length === 0)
-        return registryHits.slice(0, limit);
-    const RRF_K = 60;
-    const scoreMap = new Map();
-    const applyStashList = (hits) => {
-        for (let i = 0; i < hits.length; i++) {
-            const key = hits[i].path ?? hits[i].ref ?? hits[i].name;
-            const rrf = 1 / (RRF_K + i + 1);
-            const existing = scoreMap.get(key);
-            if (existing) {
-                existing.score += rrf;
-            }
-            else {
-                scoreMap.set(key, { hit: hits[i], score: rrf });
-            }
-        }
-    };
-    const applyRegistryList = (hits) => {
-        for (let i = 0; i < hits.length; i++) {
-            const key = `registry:${hits[i].id ?? hits[i].name}`;
-            const rrf = 1 / (RRF_K + i + 1);
-            const existing = scoreMap.get(key);
-            if (existing) {
-                existing.score += rrf;
-            }
-            else {
-                scoreMap.set(key, { hit: hits[i], score: rrf });
-            }
-        }
-    };
-    applyStashList(localHits);
-    applyRegistryList(registryHits);
-    return [...scoreMap.values()]
-        .sort((a, b) => b.score - a.score)
-        .slice(0, limit)
-        .map((v) => ({ ...v.hit, score: Math.round(v.score * 10000) / 10000 }));
+    return [...localHits, ...registryHits].slice(0, limit);
 }

package/dist/stash-show.js

@@ -1,27 +1,86 @@
+import path from "node:path";
 import { loadConfig } from "./config";
+import { closeDatabase, openDatabase } from "./db";
 import { NotFoundError, UsageError } from "./errors";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { loadStashFile } from "./metadata";
 import { resolveSourcesForOrigin } from "./origin-resolve";
 import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./search-source";
 import { resolveStashProviders } from "./stash-provider-factory";
 import { parseAssetRef } from "./stash-ref";
 import { resolveAssetPath } from "./stash-resolve";
+import { insertUsageEvent } from "./usage-events";
 // Eagerly import stash providers to trigger self-registration
 import "./stash-providers/index";
 /**
- * Unified show: routes to the first stash provider that can handle the ref.
- * viking:// refs are handled by OpenViking provider; everything else by filesystem show.
+ * Unified show: tries local FTS5 index first, then remote providers.
+ *
+ * When `detail` is `"summary"`, the response omits content/template/prompt and
+ * returns only compact metadata (name, type, description, tags, parameters).
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
-    // Try stash providers first (e.g. OpenViking for viking:// URIs)
+    // 1. Try local filesystem first (FTS5 index lookup)
+    let localError;
+    try {
+        const result = await showLocal(input);
+        logShowEvent(ref);
+        return result;
+    }
+    catch (err) {
+        // Only fall through to remote providers on NotFoundError
+        if (!(err instanceof NotFoundError))
+            throw err;
+        localError = err;
+    }
+    // 2. Try remote providers (e.g. OpenViking)
     const config = loadConfig();
-    const provider = resolveStashProviders(config).find((p) => p.canShow(ref));
-    if (provider) {
-        return provider.show(ref, input.view);
+    const providers = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.canShow(ref));
+    for (const provider of providers) {
+        try {
+            const response = await provider.show(ref, input.view);
+            logShowEvent(ref);
+            if (input.detail === "summary") {
+                return buildSummaryResponse(response);
+            }
+            return response;
+        }
+        catch (err) {
+            if (!(err instanceof NotFoundError))
+                throw err;
+        }
+    }
+    // Nothing found anywhere — rethrow the original local error with its specific message
+    throw localError;
+}
+/**
+ * Fire-and-forget: log a show event to the usage_events table.
+ * Never blocks the caller; errors are silently ignored.
+ */
+function logShowEvent(ref, existingDb) {
+    try {
+        const db = existingDb ?? openDatabase();
+        try {
+            const parsed = parseAssetRef(ref);
+            const safeName = parsed.name.replace(/%/g, "\\%").replace(/_/g, "\\_");
+            const row = db
+                .prepare("SELECT id FROM entries WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
+                .get(`%:${parsed.type}:${safeName}`, parsed.type);
+            insertUsageEvent(db, {
+                event_type: "show",
+                entry_ref: ref,
+                entry_id: row?.id,
+            });
+        }
+        finally {
+            if (!existingDb)
+                closeDatabase(db);
+        }
+    }
+    catch {
+        /* fire-and-forget */
     }
-    // Default: local filesystem show
-    return showLocal(input);
 }
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
@@ -71,10 +130,67 @@ export async function showLocal(input) {
     const renderCtx = buildRenderContext(fileCtx, match, allStashDirs);
     const response = renderer.buildShowResponse(renderCtx);
     const editable = isEditable(assetPath, config);
-    return {
+    const fullResponse = {
         ...response,
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
+    if (input.detail === "summary") {
+        return buildSummaryResponse(fullResponse, assetPath);
+    }
+    return fullResponse;
+}
+/**
+ * Build a compact summary response from a full ShowResponse.
+ *
+ * Strips content/template/prompt and returns only metadata fields:
+ * type, name, path, description, tags, parameters, action.
+ * Enriches description and tags from frontmatter or .stash.json when available.
+ *
+ * Enrichment via frontmatter and .stash.json is only performed when `assetPath`
+ * is supplied (local assets). Remote provider responses (e.g. OpenViking) rely
+ * on the provider having already populated description and tags.
+ *
+ * The resulting JSON should be under 200 tokens.
+ */
+function buildSummaryResponse(full, assetPath) {
+    // Try to enrich metadata from .stash.json if description or tags are missing
+    let description = full.description;
+    let tags = full.tags;
+    if (assetPath) {
+        // Try frontmatter extraction from content fields
+        const textContent = full.content ?? full.template ?? full.prompt;
+        if (textContent && !description) {
+            const parsed = parseFrontmatter(textContent);
+            description = toStringOrUndefined(parsed.data.description);
+        }
+        // Try .stash.json for richer metadata (tags especially)
+        const dir = path.dirname(assetPath);
+        const stashFile = loadStashFile(dir);
+        if (stashFile) {
+            const fileName = path.basename(assetPath);
+            const entry = stashFile.entries.find((e) => e.filename === fileName);
+            if (entry) {
+                if (!description && entry.description) {
+                    description = entry.description;
+                }
+                if (!tags && entry.tags) {
+                    tags = entry.tags;
+                }
+            }
+        }
+    }
+    const summary = {
+        type: full.type,
+        name: full.name,
+        path: full.path,
+        ...(description ? { description } : {}),
+        ...(tags && tags.length > 0 ? { tags } : {}),
+        ...(full.parameters ? { parameters: full.parameters } : {}),
+        ...(full.action ? { action: full.action } : {}),
+        ...(full.run ? { run: full.run } : {}),
+        ...(full.origin !== undefined ? { origin: full.origin } : {}),
+    };
+    return summary;
 }

package/dist/usage-events.js

@@ -0,0 +1,73 @@
+/**
+ * Usage event helpers for telemetry and utility-based re-ranking.
+ *
+ * Schema (created by ensureUsageEventsSchema):
+ *   id, event_type, query, entry_id (nullable), entry_ref, signal, metadata, created_at
+ */
+// ── Schema ──────────────────────────────────────────────────────────────────
+export function ensureUsageEventsSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_type TEXT NOT NULL,
+      query      TEXT,
+      entry_id   INTEGER,
+      entry_ref  TEXT,
+      signal     TEXT,
+      metadata   TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_usage_events_entry ON usage_events(entry_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_type ON usage_events(event_type);
+    CREATE INDEX IF NOT EXISTS idx_usage_events_ref ON usage_events(entry_ref);
+  `);
+}
+// ── Insert ───────────────────────────────────────────────────────────────────
+/**
+ * Insert a usage event into the database. Fire-and-forget: errors are
+ * silently caught so callers are never blocked or disrupted.
+ */
+export function insertUsageEvent(db, event) {
+    try {
+        db.prepare(`INSERT INTO usage_events (event_type, query, entry_id, entry_ref, signal, metadata)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(event.event_type, event.query ?? null, event.entry_id ?? null, event.entry_ref ?? null, event.signal ?? null, event.metadata ?? null);
+    }
+    catch {
+        /* fire-and-forget: silently ignore errors */
+    }
+}
+// ── Query ────────────────────────────────────────────────────────────────────
+/**
+ * Retrieve usage events, optionally filtered by event_type and/or entry_ref.
+ */
+export function getUsageEvents(db, filters) {
+    const conditions = [];
+    const params = [];
+    if (filters?.event_type) {
+        conditions.push("event_type = ?");
+        params.push(filters.event_type);
+    }
+    if (filters?.entry_ref) {
+        conditions.push("entry_ref = ?");
+        params.push(filters.entry_ref);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+               FROM usage_events ${where}
+               ORDER BY id ASC`;
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Delete usage events older than the given number of days.
+ */
+export function purgeOldUsageEvents(db, retentionDays) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return;
+    try {
+        const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
+    }
+    catch {
+        /* Table may not exist yet */
+    }
+}

package/dist/version.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+// Version: prefer compile-time define, then package.json, then fallback
+export const pkgVersion = (() => {
+    // Injected at compile time via `bun build --define`
+    if (typeof AKM_VERSION !== "undefined")
+        return AKM_VERSION;
+    try {
+        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+    }
+    catch {
+        // swallow — running as compiled binary without package.json
+    }
+    return "0.0.0-dev";
+})();

package/dist/walker.js

@@ -9,6 +9,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isRelevantAssetFile } from "./asset-spec";
 import { buildFileContext } from "./file-context";
+const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
 /**
  * Walk a type root directory and return files grouped by their parent directory.
  *
@@ -82,7 +83,6 @@ function walkStashGit(stashRoot) {
     // result.success is false if the process exited non-zero OR git was not found
     if (!result.success)
         return null;
-    const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
     const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
     const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : String(result.stdout ?? "");
     const files = stdout
@@ -139,7 +139,6 @@ function isInsideGitRepo(dir) {
 /** Manual walk for non-git directories. */
 function walkStashManual(stashRoot) {
     const results = [];
-    const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
     const stack = [stashRoot];
     while (stack.length > 0) {
         const current = stack.pop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [
@@ -51,7 +51,6 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0",
     "sqlite-vec": "0.1.7-alpha.2"
   },
   "engines": {
@@ -59,6 +58,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "citty": "^0.2.1"
+    "@huggingface/transformers": "^3.8.1",
+    "citty": "^0.2.1",
+    "yaml": "^2.8.2"
   }
 }