akm-cli 0.2.2 → 0.3.0-rc2

package/dist/indexer.js

@@ -5,6 +5,7 @@ import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddin
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
+import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
 import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
 import { walkStashFlat } from "./walker";
 import { warn } from "./warn";
@@ -36,7 +37,7 @@ export async function akmIndex(options) {
             message: buildIndexSummaryMessage({
                 mode: isIncremental ? "incremental" : "full",
                 stashSources: allStashDirs.length,
-                semanticSearch: config.semanticSearch,
+                semanticSearchMode: config.semanticSearchMode,
                 embeddingProvider: getEmbeddingProvider(config.embedding),
                 llmEnabled: !!config.llm,
                 vecAvailable: isVecAvailable(db),
@@ -97,21 +98,52 @@ export async function akmIndex(options) {
         rebuildFts(db);
         onProgress({ phase: "fts", message: "Rebuilt full-text search index." });
         const tFtsEnd = Date.now();
+        // Re-link detached usage_events to their new entry_ids via entry_ref.
+        // entry_ref is "type:name" (e.g., "skill:code-review"), entry_key is "stashDir:type:name".
+        // Use substr to extract the "type:name" suffix from entry_key for exact comparison
+        // (avoids LIKE which would require escaping % and _ in user-facing names).
+        try {
+            db.exec(`
+        UPDATE usage_events SET entry_id = (
+          SELECT e.id FROM entries e
+          WHERE substr(e.entry_key, length(e.entry_key) - length(usage_events.entry_ref)) = ':' || usage_events.entry_ref
+          LIMIT 1
+        )
+        WHERE entry_id IS NULL AND entry_ref IS NOT NULL
+      `);
+        }
+        catch {
+            /* ignore if table doesn't exist yet */
+        }
         // Recompute utility scores from usage_events after FTS rebuild
         recomputeUtilityScores(db);
         // Generate embeddings if semantic search is enabled
-        const hasEmbeddings = await generateEmbeddingsForDb(db, config, onProgress);
+        const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress);
         const tEmbedEnd = Date.now();
         // Update metadata
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
         setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
-        setMeta(db, "hasEmbeddings", hasEmbeddings ? "1" : "0");
+        setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
         const totalEntries = getEntryCount(db);
         // Warn on every index run if using JS fallback with many entries
         warnIfVecMissing(db);
         const tEnd = Date.now();
-        const verification = verifyIndexState(db, config, totalEntries);
+        const verification = verifyIndexState(db, config, totalEntries, embeddingResult);
+        if (config.semanticSearchMode === "off") {
+            clearSemanticStatus();
+        }
+        else {
+            writeSemanticStatus({
+                status: verification.semanticStatus === "disabled" ? "pending" : verification.semanticStatus,
+                ...(embeddingResult.reason ? { reason: embeddingResult.reason } : {}),
+                ...(embeddingResult.message ? { message: embeddingResult.message } : {}),
+                providerFingerprint: deriveSemanticProviderFingerprint(config.embedding),
+                lastCheckedAt: new Date().toISOString(),
+                entryCount: verification.entryCount,
+                embeddingCount: verification.embeddingCount,
+            });
+        }
         onProgress({ phase: "verify", message: verification.message });
         return {
             stashDir,
@@ -222,7 +254,14 @@ async function indexEntries(db, allStashDirs, isIncremental, builtAtMs, doFullDe
             }
             db.exec("DELETE FROM entries_fts");
             db.exec("DELETE FROM utility_scores");
-            db.exec("DELETE FROM usage_events");
+            // Detach usage_events from entries about to be deleted — null out entry_id
+            // but keep entry_ref so events can be re-linked after entries are rebuilt.
+            try {
+                db.exec("UPDATE usage_events SET entry_id = NULL WHERE entry_id IS NOT NULL");
+            }
+            catch {
+                /* ignore if table doesn't exist */
+            }
             db.exec("DELETE FROM entries");
         }
         for (const { dirPath, currentStashDir, files, stash, skip } of dirRecords) {
@@ -283,16 +322,38 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     }
 }
 async function generateEmbeddingsForDb(db, config, onProgress) {
-    if (!config.semanticSearch) {
+    if (config.semanticSearchMode === "off") {
         onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
-        return false;
+        return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
+    }
+    // Detect embedding model/provider changes and purge stale embeddings
+    // so that incremental reindex regenerates all vectors with the new model.
+    const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
+    const storedFingerprint = getMeta(db, "embeddingFingerprint");
+    if (storedFingerprint && storedFingerprint !== currentFingerprint) {
+        try {
+            db.exec("DELETE FROM embeddings");
+        }
+        catch {
+            /* ignore */
+        }
+        if (isVecAvailable(db)) {
+            try {
+                db.exec("DELETE FROM entries_vec");
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        setMeta(db, "hasEmbeddings", "0");
     }
     try {
         const { embedBatch } = await import("./embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
         if (allEntries.length === 0) {
             onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
-            return true;
+            setMeta(db, "embeddingFingerprint", currentFingerprint);
+            return { success: true };
         }
         onProgress({
             phase: "embeddings",
@@ -311,15 +372,21 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
             phase: "embeddings",
             message: `Stored ${embeddings.length} embedding${embeddings.length === 1 ? "" : "s"}.`,
         });
-        return true;
+        setMeta(db, "embeddingFingerprint", currentFingerprint);
+        return { success: true };
     }
     catch (error) {
-        warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
+        const message = error instanceof Error ? error.message : String(error);
+        warn("Embedding generation failed, continuing without:", message);
         onProgress({
             phase: "embeddings",
-            message: `Embedding generation failed: ${error instanceof Error ? error.message : String(error)}`,
+            message: `Embedding generation failed: ${message}`,
         });
-        return false;
+        return {
+            success: false,
+            reason: classifySemanticFailure(message),
+            message: `Semantic search verification failed: ${message}`,
+        };
     }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -341,18 +408,18 @@ function attachFileSize(entry, entryPath) {
 }
 function buildIndexSummaryMessage(options) {
     const stashSourceLabel = options.stashSources === 1 ? "stash source" : "stash sources";
-    const semanticDetail = getSemanticSearchLabel(options.semanticSearch, options.embeddingProvider, options.vecAvailable);
+    const semanticDetail = getSemanticSearchLabel(options.semanticSearchMode, options.embeddingProvider, options.vecAvailable);
     return `Starting ${options.mode} index (${options.stashSources} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
 }
 function getEmbeddingProvider(embedding) {
     return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
 }
-function getSemanticSearchLabel(semanticSearch, embeddingProvider, vecAvailable) {
-    if (!semanticSearch)
+function getSemanticSearchLabel(semanticSearchMode, embeddingProvider, vecAvailable) {
+    if (semanticSearchMode === "off")
         return "disabled";
     return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
 }
-function verifyIndexState(db, config, totalEntries) {
+function verifyIndexState(db, config, totalEntries, embeddingResult) {
     const embeddingCount = getEmbeddingCount(db);
     const vecAvailable = isVecAvailable(db);
     const embeddingProvider = getEmbeddingProvider(config.embedding);
@@ -360,18 +427,22 @@ function verifyIndexState(db, config, totalEntries) {
         return {
             ok: true,
             message: "Index ready. No assets were found yet.",
-            semanticSearchEnabled: config.semanticSearch,
+            semanticSearchEnabled: config.semanticSearchMode === "auto",
+            semanticSearchMode: config.semanticSearchMode,
+            semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
             embeddingProvider,
             entryCount: totalEntries,
             embeddingCount,
             vecAvailable,
         };
     }
-    if (!config.semanticSearch) {
+    if (config.semanticSearchMode === "off") {
         return {
             ok: true,
             message: "Keyword index ready. Semantic search is disabled.",
             semanticSearchEnabled: false,
+            semanticSearchMode: config.semanticSearchMode,
+            semanticStatus: "disabled",
             embeddingProvider,
             entryCount: totalEntries,
             embeddingCount,
@@ -383,6 +454,8 @@ function verifyIndexState(db, config, totalEntries) {
             ok: true,
             message: `Semantic search ready (${embeddingCount}/${totalEntries} embeddings, ${vecAvailable ? "sqlite-vec active" : "JS fallback active"}).`,
             semanticSearchEnabled: true,
+            semanticSearchMode: config.semanticSearchMode,
+            semanticStatus: vecAvailable ? "ready-vec" : "ready-js",
             embeddingProvider,
             entryCount: totalEntries,
             embeddingCount,
@@ -391,11 +464,14 @@ function verifyIndexState(db, config, totalEntries) {
     }
     return {
         ok: false,
-        message: `Semantic search verification failed (${embeddingCount}/${totalEntries} embeddings available).`,
+        message: embeddingResult.message ??
+            `Semantic search verification failed (${embeddingCount}/${totalEntries} embeddings available).`,
         guidance: embeddingProvider === "remote"
             ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
             : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/configuration.md for local embedding dependency setup.",
         semanticSearchEnabled: true,
+        semanticSearchMode: config.semanticSearchMode,
+        semanticStatus: "blocked",
         embeddingProvider,
         entryCount: totalEntries,
         embeddingCount,

package/dist/info.js

@@ -3,6 +3,7 @@ import { getAssetTypes } from "./asset-spec";
 import { loadConfig } from "./config";
 import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openDatabase } from "./db";
 import { getDbPath } from "./paths";
+import { getEffectiveSemanticStatus, readSemanticStatus } from "./semantic-status";
 import { pkgVersion } from "./version";
 /**
  * Assemble system info describing the current capabilities, configuration,
@@ -14,9 +15,11 @@ export function assembleInfo(options) {
     const config = loadConfig();
     // Asset types
     const assetTypes = getAssetTypes();
+    const semanticRuntime = readSemanticStatus();
+    const semanticStatus = getEffectiveSemanticStatus(config, semanticRuntime);
     // Search modes
     const searchModes = ["fts"];
-    if (config.semanticSearch) {
+    if (semanticStatus === "ready-js" || semanticStatus === "ready-vec") {
         searchModes.push("semantic", "hybrid");
     }
     // Registries (strip sensitive fields like apiKey from options)
@@ -41,6 +44,12 @@ export function assembleInfo(options) {
         version: pkgVersion,
         assetTypes,
         searchModes,
+        semanticSearch: {
+            mode: config.semanticSearchMode,
+            status: semanticStatus,
+            ...(semanticRuntime?.reason ? { reason: semanticRuntime.reason } : {}),
+            ...(semanticRuntime?.message ? { message: semanticRuntime.message } : {}),
+        },
         registries,
         stashProviders,
         indexStats,

package/dist/installed-kits.js

@@ -1,15 +1,11 @@
 /**
- * Installed-kit operations: list, remove, update.
+ * Source operations: list, remove, update.
  *
- * Manages the set of kits that have been added to the local stash via
- * `akm add`. Each installed kit has a cache directory and a stash root that
- * is added to the search path.
- *
- * Not to be confused with:
- *   - registry-factory.ts   — factory map for kit-discovery registry providers
- *   - stash-provider-factory.ts — factory map for runtime stash data sources
+ * Provides unified operations across all source kinds (local, managed, remote).
+ * The CLI's `akm list`, `akm remove`, and `akm update` commands are wired here.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 import { NotFoundError, UsageError } from "./errors";
@@ -17,49 +13,107 @@ import { akmIndex } from "./indexer";
 import { removeLockEntry, upsertLockEntry } from "./lockfile";
 import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
-export async function akmList(input) {
+import { removeStash } from "./stash-source-manage";
+export async function akmListSources(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const config = loadConfig();
-    const installed = config.installed ?? [];
+    const kindFilter = input?.kind;
+    const sources = [];
+    // Stash entries → local or remote sources
+    for (const stash of config.stashes ?? []) {
+        const isRemote = stash.url != null;
+        const kind = isRemote ? "remote" : "local";
+        if (kindFilter && !kindFilter.includes(kind))
+            continue;
+        const name = stash.name ?? stash.path ?? stash.url ?? "unknown";
+        sources.push({
+            name,
+            kind,
+            path: stash.path,
+            provider: isRemote ? stash.type : undefined,
+            updatable: false,
+            status: { exists: stash.path ? directoryExists(stash.path) : true },
+        });
+    }
+    // Installed entries → managed sources
+    for (const entry of config.installed ?? []) {
+        const kind = "managed";
+        if (kindFilter && !kindFilter.includes(kind))
+            continue;
+        sources.push({
+            name: entry.id,
+            kind,
+            path: entry.stashRoot,
+            ref: entry.ref,
+            version: entry.resolvedVersion,
+            updatable: true,
+            status: { exists: directoryExists(entry.stashRoot) },
+        });
+    }
     return {
         schemaVersion: 1,
         stashDir,
-        installed: installed.map((entry) => ({
-            ...entry,
-            status: {
-                cacheDirExists: directoryExists(entry.cacheDir),
-                stashRootExists: directoryExists(entry.stashRoot),
-            },
-        })),
-        totalInstalled: installed.length,
+        sources,
+        totalSources: sources.length,
     };
 }
 export async function akmRemove(input) {
     const target = input.target.trim();
     if (!target)
-        throw new UsageError("Target is required. Provide the kit id or ref (e.g. `akm remove npm:@scope/kit` or `akm remove owner/repo`).");
+        throw new UsageError("Target is required. Provide the source id, ref, path, URL, or name (e.g. `akm remove npm:@scope/kit` or `akm remove ~/my-stash`).");
     const stashDir = input.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const installed = config.installed ?? [];
-    const entry = resolveInstalledTarget(installed, target);
-    const updatedConfig = removeInstalledRegistryEntry(entry.id);
-    await removeLockEntry(entry.id);
-    // Only clean up cache for non-local sources — local sources point to the
-    // user's real directory on disk and must never be deleted.
-    if (entry.source !== "local") {
-        cleanupDirectoryBestEffort(entry.cacheDir);
+    // Try installed[] first (managed sources)
+    const entry = tryResolveInstalledTarget(installed, target);
+    if (entry) {
+        const updatedConfig = removeInstalledRegistryEntry(entry.id);
+        await removeLockEntry(entry.id);
+        if (entry.source !== "local") {
+            cleanupDirectoryBestEffort(entry.cacheDir);
+        }
+        const index = await akmIndex({ stashDir });
+        return {
+            schemaVersion: 1,
+            stashDir,
+            target,
+            removed: {
+                id: entry.id,
+                source: entry.source,
+                ref: entry.ref,
+                cacheDir: entry.cacheDir,
+                stashRoot: entry.stashRoot,
+            },
+            config: {
+                stashCount: updatedConfig.stashes?.length ?? 0,
+                installedKitCount: updatedConfig.installed?.length ?? 0,
+            },
+            index: {
+                mode: index.mode,
+                totalEntries: index.totalEntries,
+                directoriesScanned: index.directoriesScanned,
+                directoriesSkipped: index.directoriesSkipped,
+            },
+        };
     }
+    // Fall through to stashes[] (local/remote sources)
+    const stashResult = removeStash(target);
+    if (!stashResult.removed || !stashResult.entry) {
+        throw new NotFoundError(`No matching source for target: ${target}`);
+    }
+    const removedEntry = stashResult.entry;
     const index = await akmIndex({ stashDir });
+    const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
         stashDir,
         target,
         removed: {
-            id: entry.id,
-            source: entry.source,
-            ref: entry.ref,
-            cacheDir: entry.cacheDir,
-            stashRoot: entry.stashRoot,
+            id: removedEntry.name ?? removedEntry.path ?? removedEntry.url ?? target,
+            source: removedEntry.type,
+            ref: removedEntry.path ?? removedEntry.url ?? target,
+            cacheDir: "",
+            stashRoot: removedEntry.path ?? "",
         },
         config: {
             stashCount: updatedConfig.stashes?.length ?? 0,
@@ -146,9 +200,32 @@ function selectTargets(installed, target, all) {
     if (!target) {
         throw new UsageError("Either <target> or --all is required.");
     }
-    return [resolveInstalledTarget(installed, target)];
+    const found = tryResolveInstalledTarget(installed, target);
+    if (found)
+        return [found];
+    // Check if target matches a stash source and give a helpful message
+    const config = loadConfig();
+    const stashes = config.stashes ?? [];
+    const isUrl = target.startsWith("http://") || target.startsWith("https://");
+    const resolvedPath = !isUrl ? path.resolve(target) : undefined;
+    const stashMatch = stashes.find((s) => {
+        if (isUrl && s.url === target)
+            return true;
+        if (resolvedPath && s.path && path.resolve(s.path) === resolvedPath)
+            return true;
+        if (s.name === target)
+            return true;
+        return false;
+    });
+    if (stashMatch) {
+        if (stashMatch.url) {
+            throw new UsageError(`"${target}" is a remote provider — it queries live data and has nothing to update.`);
+        }
+        throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`);
+    }
+    throw new NotFoundError(`No matching source for target: ${target}`);
 }
-function resolveInstalledTarget(installed, target) {
+function tryResolveInstalledTarget(installed, target) {
     const byId = installed.find((entry) => entry.id === target);
     if (byId)
         return byId;
@@ -167,7 +244,7 @@ function resolveInstalledTarget(installed, target) {
         if (byParsedId)
             return byParsedId;
     }
-    throw new NotFoundError(`No installed kit matched target: ${target}`);
+    return undefined;
 }
 function toInstalledEntry(status) {
     // KitInstallStatus extends InstalledKitEntry; omit the extra extractedDir field.

package/dist/local-search.js

@@ -17,6 +17,7 @@ import { buildSearchText } from "./indexer";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 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";
@@ -32,6 +33,22 @@ export function buildLocalAction(type, ref) {
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const allStashDirs = sources.map((s) => s.path);
+    const rawStatus = readSemanticStatus();
+    const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
+    const warnings = [];
+    if (config.semanticSearchMode === "auto" && semanticStatus === "pending") {
+        // Distinguish between fingerprint mismatch (config changed) and never-set-up.
+        const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
+        if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
+            warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
+        }
+        else {
+            warnings.push("Semantic search is pending verification. Run 'akm setup' or 'akm index --full' to enable semantic search.");
+        }
+    }
+    if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
+        warnings.push("Semantic search is currently blocked. Using keyword search until the semantic backend is healthy again.");
+    }
     // Try to open the database
     const dbPath = getDbPath();
     try {
@@ -41,13 +58,27 @@ export async function searchLocal(input) {
             try {
                 const entryCount = getEntryCount(db);
                 const storedStashDir = getMeta(db, "stashDir");
-                if (entryCount > 0 && storedStashDir === stashDir) {
+                // Accept the index if the incoming stashDir matches the primary OR
+                // appears anywhere in the stored stashDirs array. This prevents
+                // unnecessary substring fallback when only the primary dir changes.
+                let stashDirMatch = storedStashDir === stashDir;
+                if (!stashDirMatch) {
+                    try {
+                        const storedDirs = JSON.parse(getMeta(db, "stashDirs") ?? "[]");
+                        stashDirMatch = storedDirs.includes(stashDir);
+                    }
+                    catch {
+                        /* ignore malformed stashDirs */
+                    }
+                }
+                if (entryCount > 0 && stashDirMatch) {
                     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,
+                        warnings: warnings.length > 0 ? warnings : undefined,
                         embedMs,
                         rankMs,
                     };
@@ -66,6 +97,7 @@ export async function searchLocal(input) {
     return {
         hits,
         tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
+        warnings: warnings.length > 0 ? warnings : undefined,
     };
 }
 // ── Database search ─────────────────────────────────────────────────────────
@@ -335,7 +367,8 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
-    if (!config.semanticSearch)
+    const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
+    if (!isSemanticRuntimeReady(semanticStatus))
         return null;
     const hasEmbeddings = getMeta(db, "hasEmbeddings");
     if (hasEmbeddings !== "1")

package/dist/paths.js

@@ -68,6 +68,9 @@ export function getCacheDir() {
 export function getDbPath() {
     return path.join(getCacheDir(), "index.db");
 }
+export function getSemanticStatusPath() {
+    return path.join(getCacheDir(), "semantic-status.json");
+}
 export function getRegistryCacheDir() {
     return path.join(getCacheDir(), "registry");
 }