akm-cli 0.2.2 → 0.3.0

package/dist/semantic-status.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_LOCAL_MODEL } from "./embedder";
+import { getCacheDir, getSemanticStatusPath } from "./paths";
+export function deriveSemanticProviderFingerprint(embedding) {
+    if (embedding?.endpoint) {
+        return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;
+    }
+    return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}`;
+}
+export function readSemanticStatus() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(getSemanticStatusPath(), "utf8"));
+        if ((raw.status === "pending" ||
+            raw.status === "ready-js" ||
+            raw.status === "ready-vec" ||
+            raw.status === "blocked") &&
+            typeof raw.providerFingerprint === "string" &&
+            typeof raw.lastCheckedAt === "string") {
+            const status = {
+                status: raw.status,
+                providerFingerprint: raw.providerFingerprint,
+                lastCheckedAt: raw.lastCheckedAt,
+            };
+            if (typeof raw.reason === "string")
+                status.reason = raw.reason;
+            if (typeof raw.message === "string")
+                status.message = raw.message;
+            if (typeof raw.entryCount === "number")
+                status.entryCount = raw.entryCount;
+            if (typeof raw.embeddingCount === "number")
+                status.embeddingCount = raw.embeddingCount;
+            return status;
+        }
+    }
+    catch {
+        // ignore corrupt or missing semantic status
+    }
+    return undefined;
+}
+export function writeSemanticStatus(status) {
+    const dir = getCacheDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = getSemanticStatusPath();
+    const tmpPath = path.join(dir, `semantic-status.json.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`);
+    fs.writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
+    try {
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+export function clearSemanticStatus() {
+    try {
+        fs.unlinkSync(getSemanticStatusPath());
+    }
+    catch {
+        // ignore missing file
+    }
+}
+/** How long a "blocked" status is retained before the system retries. 24 hours. */
+export const BLOCKED_TTL_MS = 24 * 60 * 60 * 1000;
+export function getEffectiveSemanticStatus(config, status = readSemanticStatus()) {
+    if (config.semanticSearchMode === "off")
+        return "disabled";
+    if (!status)
+        return "pending";
+    const fingerprint = deriveSemanticProviderFingerprint(config.embedding);
+    if (status.providerFingerprint !== fingerprint)
+        return "pending";
+    // Auto-recovery: if blocked status is older than BLOCKED_TTL_MS, treat as pending
+    // so the next index run will re-attempt semantic setup.
+    if (status.status === "blocked") {
+        const checkedAt = new Date(status.lastCheckedAt).getTime();
+        if (Number.isNaN(checkedAt) || Date.now() - checkedAt > BLOCKED_TTL_MS) {
+            return "pending";
+        }
+    }
+    return status.status;
+}
+export function isSemanticRuntimeReady(status) {
+    return status === "ready-js" || status === "ready-vec";
+}
+export function classifySemanticFailure(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes("401") || lower.includes("403") || lower.includes("auth") || lower.includes("unauthorized")) {
+        return "remote-auth";
+    }
+    if (lower.includes("429") || lower.includes("rate limit") || lower.includes("quota")) {
+        return "remote-rate-limit";
+    }
+    if (lower.includes("eacces") || lower.includes("permission denied")) {
+        return "permission-denied";
+    }
+    // Native library / linker errors must be checked before the generic ONNX
+    // match because Alpine/musl linker errors often contain "onnxruntime" in
+    // the library path (e.g. onnxruntime_binding.node).
+    if (lower.includes("shared library") ||
+        lower.includes("glibc") ||
+        lower.includes("musl") ||
+        lower.includes("libc.so")) {
+        return "native-lib-missing";
+    }
+    if (lower.includes("onnx") || lower.includes("onnxruntime")) {
+        return "onnx-runtime-failed";
+    }
+    if (lower.includes("404") || lower.includes("model not found") || lower.includes("bad request")) {
+        return "remote-model";
+    }
+    if (lower.includes("transformers") || lower.includes("missing-package")) {
+        return "missing-package";
+    }
+    if (lower.includes("download")) {
+        return "local-model-download";
+    }
+    if (lower.includes("dimension mismatch")) {
+        return "dimension-mismatch";
+    }
+    if (lower.includes("db") || lower.includes("sqlite") || lower.includes("cache dir")) {
+        return "db-open";
+    }
+    if (lower.includes("timeout") ||
+        lower.includes("unreachable") ||
+        lower.includes("refused") ||
+        lower.includes("network") ||
+        lower.includes("fetch")) {
+        return "remote-network";
+    }
+    return "unknown";
+}

package/dist/setup.js

@@ -5,6 +5,7 @@
  * registry selection, stash sources, and agent platform discovery.
  * Collects all choices and writes config once at the end.
  */
+import path from "node:path";
 import * as p from "@clack/prompts";
 import { isHttpUrl } from "./common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
@@ -14,6 +15,7 @@ import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailabl
 import { akmIndex } from "./indexer";
 import { akmInit } from "./init";
 import { getDefaultStashDir } from "./paths";
+import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./semantic-status";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Recommended GitHub repositories shown during setup. */
 const RECOMMENDED_GITHUB_REPOS = [
@@ -78,6 +80,22 @@ async function promptOrBack(fn) {
         return null;
     return result;
 }
+/**
+ * Quick connectivity check. Returns true if we can reach a public
+ * endpoint within 3 seconds, false otherwise. Used to skip network-
+ * dependent setup steps gracefully when offline.
+ *
+ * @internal Exported for testing only.
+ */
+export async function isOnline() {
+    try {
+        await fetch("https://dns.google", { signal: AbortSignal.timeout(3000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isRemoteEmbeddingConfig(embedding) {
     return isHttpUrl(embedding?.endpoint);
 }
@@ -99,10 +117,10 @@ export function describeSemanticSearchAssets(embedding) {
 export async function stepSemanticSearch(current, embedding) {
     const enabled = await prompt(() => p.confirm({
         message: "Enable semantic search?",
-        initialValue: current.semanticSearch,
+        initialValue: current.semanticSearchMode !== "off",
     }));
     if (!enabled) {
-        return { enabled: false, prepareAssets: false };
+        return { mode: "off", prepareAssets: false };
     }
     p.note(describeSemanticSearchAssets(embedding).join("\n"), "Semantic Search Assets");
     const prepareAssets = await prompt(() => p.confirm({
@@ -111,7 +129,7 @@ export async function stepSemanticSearch(current, embedding) {
             : "Download and verify semantic-search assets now?",
         initialValue: true,
     }));
-    return { enabled: true, prepareAssets };
+    return { mode: "auto", prepareAssets };
 }
 async function prepareSemanticSearchAssets(config) {
     const remote = isRemoteEmbeddingConfig(config.embedding);
@@ -121,7 +139,9 @@ async function prepareSemanticSearchAssets(config) {
             const spin = p.spinner();
             spin.start("Installing @huggingface/transformers...");
             try {
+                const pkgRoot = path.resolve(import.meta.dir, "..");
                 const proc = Bun.spawn(["bun", "add", "@huggingface/transformers"], {
+                    cwd: pkgRoot,
                     stdout: "pipe",
                     stderr: "pipe",
                 });
@@ -138,7 +158,7 @@ async function prepareSemanticSearchAssets(config) {
                 p.log.warn(`Automatic install failed: ${msg}\n` +
                     "Install it manually with: bun add @huggingface/transformers\n" +
                     "Then re-run `akm setup` or `akm index --full --verbose`.");
-                return false;
+                return { ok: false, reason: "missing-package", message: `Automatic install failed: ${msg}` };
             }
         }
     }
@@ -151,16 +171,18 @@ async function prepareSemanticSearchAssets(config) {
         spin.stop("Semantic-search assets could not be prepared.");
         if (result.reason === "remote-unreachable") {
             p.log.warn("The remote embedding endpoint is not reachable. Check your endpoint and credentials, then retry `akm index --full --verbose`.");
+            return { ok: false, reason: "remote-network", message: "The remote embedding endpoint is not reachable." };
         }
         else if (result.reason === "missing-package") {
             p.log.warn("@huggingface/transformers is not installed. Install it with: bun add @huggingface/transformers\n" +
                 "Then re-run `akm setup` or `akm index --full --verbose`.");
+            return { ok: false, reason: "missing-package", message: "@huggingface/transformers is not installed." };
         }
         else {
             p.log.warn(`The local embedding model could not be downloaded: ${result.message}\n` +
                 "Retry `akm index --full --verbose` after confirming local model downloads are permitted.");
+            return { ok: false, reason: "local-model-download", message: result.message };
         }
-        return false;
     }
     spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
     let db;
@@ -182,7 +204,7 @@ async function prepareSemanticSearchAssets(config) {
         if (db)
             closeDatabase(db);
     }
-    return true;
+    return { ok: true };
 }
 // ── Steps ───────────────────────────────────────────────────────────────────
 async function stepStashDir(current) {
@@ -250,11 +272,20 @@ async function stepOllama(current) {
         embedding = current.embedding;
     }
     else if (embChoice !== "local") {
-        // Ask for dimension — different models produce different sizes
+        // Ask for dimension — different models produce different sizes.
+        // Common dimensions: nomic-embed-text=768, mxbai-embed-large=1024,
+        // all-minilm/bge-small=384. Default based on selected model.
+        const knownDims = {
+            nomic: 768,
+            mxbai: 1024,
+            minilm: 384,
+            bge: 384,
+        };
+        const guessedDim = Object.entries(knownDims).find(([k]) => embChoice.includes(k))?.[1] ?? 384;
         const dimChoice = await prompt(() => p.text({
-            message: "Embedding dimension (must match your index; 384 is common for MiniLM/nomic):",
-            placeholder: "384",
-            defaultValue: "384",
+            message: `Embedding dimension for ${embChoice}:`,
+            placeholder: String(guessedDim),
+            defaultValue: String(guessedDim),
             validate: (v) => {
                 const n = Number(v);
                 if (!Number.isInteger(n) || n <= 0)
@@ -542,12 +573,18 @@ export async function runSetupWizard() {
     // Step 1: Stash directory
     p.log.step("Step 1: Stash Directory");
     const stashDir = await stepStashDir(current);
+    // Quick connectivity check — skip network-dependent steps when offline
+    const online = await isOnline();
+    if (!online) {
+        p.log.warn("No network connectivity detected. Skipping Ollama detection and remote embedding checks.\n" +
+            "Local-only setup will continue. Re-run `akm setup` when online for full configuration.");
+    }
     // Step 2: Ollama / Embedding / LLM
     p.log.step("Step 2: Embedding & LLM");
-    const { embedding, llm } = await stepOllama(current);
+    const { embedding, llm } = online ? await stepOllama(current) : { embedding: current.embedding, llm: current.llm };
     // Step 3: Semantic search assets
     p.log.step("Step 3: Semantic Search");
-    const semanticSearch = await stepSemanticSearch(current, embedding);
+    const semanticSearchMode = await stepSemanticSearch(current, embedding);
     // Step 4: Registries
     p.log.step("Step 4: Registries");
     const registries = await stepRegistries(current);
@@ -573,7 +610,7 @@ export async function runSetupWizard() {
         registries,
         stashes: allStashes.length > 0 ? allStashes : undefined,
         // Preserve existing fields
-        semanticSearch: semanticSearch.enabled,
+        semanticSearchMode: semanticSearchMode.mode,
         installed: current.installed,
         output: current.output,
     };
@@ -583,7 +620,7 @@ export async function runSetupWizard() {
         `Stash directory:  ${stashDir}`,
         `Embedding:        ${embedding ? `${embedding.provider ?? "remote"} / ${embedding.model}` : "built-in local"}`,
         `LLM:              ${llm ? `${llm.provider ?? "remote"} / ${llm.model}` : "disabled"}`,
-        `Semantic search:  ${semanticSearch.enabled ? "enabled" : "disabled"}`,
+        `Semantic search:  ${semanticSearchMode.mode}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
         `Stash sources:    ${allStashes.length}`,
     ].join("\n"), "Configuration Summary");
@@ -597,18 +634,39 @@ export async function runSetupWizard() {
     saveConfig(newConfig);
     // Initialize stash directory
     await akmInit({ dir: stashDir });
-    if (semanticSearch.enabled) {
-        if (semanticSearch.prepareAssets) {
+    if (semanticSearchMode.mode === "off") {
+        clearSemanticStatus();
+    }
+    if (semanticSearchMode.mode === "auto") {
+        if (semanticSearchMode.prepareAssets) {
             const ready = await prepareSemanticSearchAssets(newConfig);
-            if (!ready) {
-                // Asset preparation failed: disable semantic search and persist the update.
-                newConfig.semanticSearch = false;
-                saveConfig(newConfig);
-                p.log.warn("Semantic search has been disabled in the saved configuration. Re-run `akm setup` or `akm index --full --verbose` once the issue is resolved.");
+            if (!ready.ok) {
+                writeSemanticStatus({
+                    status: "blocked",
+                    reason: ready.reason,
+                    message: ready.message,
+                    providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                    lastCheckedAt: new Date().toISOString(),
+                });
+                p.log.warn("Semantic search remains set to auto, but is currently blocked. Re-run `akm index --full --verbose` once the issue is resolved.");
+            }
+            else {
+                writeSemanticStatus({
+                    status: "pending",
+                    message: "Semantic prerequisites verified. Building the index to finish activation.",
+                    providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                    lastCheckedAt: new Date().toISOString(),
+                });
             }
         }
         else {
-            p.log.info("Semantic search will be enabled, but asset preparation was skipped. Run `akm index --full --verbose` later to verify it.");
+            writeSemanticStatus({
+                status: "pending",
+                message: "Semantic search is enabled, but asset preparation was skipped.",
+                providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                lastCheckedAt: new Date().toISOString(),
+            });
+            p.log.info("Semantic search is set to auto, but asset preparation was skipped. Run `akm index --full --verbose` later to verify it.");
         }
     }
     // Build search index
@@ -618,7 +676,7 @@ export async function runSetupWizard() {
     try {
         const indexResult = await akmIndex({ stashDir });
         spin.stop(`Indexed ${indexResult.totalEntries} assets.`);
-        if (newConfig.semanticSearch) {
+        if (newConfig.semanticSearchMode === "auto") {
             if (indexResult.verification.ok) {
                 p.log.success(indexResult.verification.message);
             }
@@ -633,6 +691,15 @@ export async function runSetupWizard() {
     catch (err) {
         spin.stop("Indexing failed — you can run `akm index` manually later.");
         p.log.warn(String(err));
+        if (newConfig.semanticSearchMode === "auto") {
+            writeSemanticStatus({
+                status: "blocked",
+                reason: "index-failed",
+                message: String(err),
+                providerFingerprint: deriveSemanticProviderFingerprint(newConfig.embedding),
+                lastCheckedAt: new Date().toISOString(),
+            });
+        }
     }
     // API key reminder
     if (embedding?.apiKey === undefined && embedding?.provider !== "ollama") {

package/dist/stash-add.js

@@ -7,24 +7,6 @@ import { akmIndex } from "./indexer";
 import { upsertLockEntry } from "./lockfile";
 import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
-export async function akmKitAdd(input) {
-    const ref = input.ref.trim();
-    if (!ref)
-        throw new UsageError("Registry ref is required. " + "Examples: `akm kit add @scope/kit`, `akm kit add github:owner/repo`");
-    const stashDir = resolveStashDir();
-    try {
-        const parsed = parseRegistryRef(ref);
-        if (parsed.source === "local") {
-            throw new UsageError(`Local directories should be added as stashes, not kits. Use \`akm stash add ${ref}\` instead.`);
-        }
-    }
-    catch (err) {
-        if (err instanceof UsageError)
-            throw err;
-        // Not a local ref — fall through to registry install
-    }
-    return addRegistryKit(ref, stashDir);
-}
 export async function akmAdd(input) {
     const ref = input.ref.trim();
     if (!ref)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -44,6 +44,7 @@
     "check": "bun run lint && bunx tsc --noEmit && bun test ./tests",
     "check:changed": "bun test tests/output-baseline.test.ts tests/e2e.test.ts tests/stash-search.test.ts && bun run lint && bunx tsc --noEmit",
     "test": "bun test ./tests",
+    "release:check": "./tests/release-check.sh",
     "lint": "bunx biome check src/ tests/",
     "lint:fix": "bunx biome check --write src/ tests/",
     "format": "bunx biome format --write src/ tests/",
@@ -60,6 +61,7 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "sqlite-vec": "0.1.7-alpha.2"
   },
   "engines": {
@@ -68,7 +70,6 @@
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "citty": "^0.2.1",
-    "@huggingface/transformers": "^3.8.1",
     "yaml": "^2.8.2"
   }
 }