akm-cli 0.4.1 → 0.5.0-rc2

package/dist/setup.js

@@ -14,6 +14,7 @@ import { detectAgentPlatforms, detectOllama, detectOpenViking } from "./detect";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedder";
 import { akmIndex } from "./indexer";
 import { akmInit } from "./init";
+import { probeLlmCapabilities } from "./llm";
 import { getDefaultStashDir } from "./paths";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./semantic-status";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -236,8 +237,8 @@ async function stepOllama(current) {
         spin.stop("Ollama not detected");
         p.log.info("Ollama is not running. Embeddings will use the built-in local model.\n" +
             "To use Ollama later, install it from https://ollama.com and re-run `akm setup`.");
-        // Preserve existing embedding/LLM config when Ollama is not available
-        return { embedding: current.embedding, llm: current.llm };
+        // Preserve existing embedding config when Ollama is not available
+        return { embedding: current.embedding };
     }
     spin.stop(`Ollama detected at ${ollama.endpoint}`);
     if (ollama.models.length > 0) {
@@ -300,44 +301,162 @@ async function stepOllama(current) {
         };
     }
     // else: undefined → use built-in local
-    // LLM model selection
-    const chatModels = ollama.models.filter((m) => !embeddingModels.includes(m));
-    const allLlmCandidates = chatModels.length > 0 ? chatModels : ollama.models;
-    let llm;
-    const llmOptions = [];
-    for (const m of allLlmCandidates) {
-        llmOptions.push({ value: m, label: m, hint: "Ollama" });
-    }
-    llmOptions.push({
-        value: "none",
-        label: "Skip LLM enhancement",
-        hint: "use heuristic metadata",
-    });
+    // Surface Ollama details to the LLM step so it can offer Ollama as a preset.
+    const ollamaChatModels = ollama.models.filter((m) => !embeddingModels.includes(m));
+    return { embedding, ollamaEndpoint: ollama.endpoint, ollamaChatModels };
+}
+const LLM_PRESETS = [
+    {
+        value: "anthropic",
+        label: "Anthropic Claude (OpenAI SDK compat beta)",
+        endpoint: "https://api.anthropic.com/v1/chat/completions",
+        defaultModel: "claude-sonnet-4-5",
+        hint: "beta OpenAI-compat layer; set AKM_LLM_API_KEY; override the model if the default is unavailable",
+        contextWindow: 200_000,
+    },
+    {
+        value: "openai",
+        label: "OpenAI",
+        endpoint: "https://api.openai.com/v1/chat/completions",
+        defaultModel: "gpt-4o-mini",
+        hint: "AKM_LLM_API_KEY required",
+        contextWindow: 128_000,
+    },
+    {
+        value: "google",
+        label: "Google Gemini (OpenAI-compat)",
+        endpoint: "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
+        defaultModel: "gemini-2.0-flash",
+        hint: "OpenAI-compat endpoint, AKM_LLM_API_KEY required",
+        contextWindow: 1_000_000,
+    },
+];
+/**
+ * Step 3a: pick an LLM provider. Used for indexing-time metadata enhancement.
+ *
+ * @internal Exported for testing only.
+ */
+export async function stepLlm(current, ollamaEndpoint, ollamaChatModels) {
+    const options = LLM_PRESETS.map((preset) => ({
+        value: preset.value,
+        label: preset.label,
+        hint: preset.hint,
+    }));
+    const ollamaAvailable = Boolean(ollamaEndpoint && ollamaChatModels && ollamaChatModels.length > 0);
+    if (ollamaAvailable) {
+        options.push({
+            value: "ollama",
+            label: "Ollama (local)",
+            hint: ollamaChatModels?.[0] ?? "local",
+        });
+    }
+    options.push({ value: "custom", label: "Custom OpenAI-compatible endpoint" });
+    options.push({ value: "none", label: "Skip LLM", hint: "no metadata enhancement during indexing" });
     if (current.llm) {
-        llmOptions.push({
+        options.push({
             value: "keep",
             label: `Keep current: ${current.llm.provider ?? current.llm.endpoint}`,
             hint: current.llm.model,
         });
     }
-    const llmChoice = await prompt(() => p.select({
-        message: "Use an LLM for richer metadata during indexing?",
-        options: llmOptions,
-        initialValue: allLlmCandidates.length > 0 ? allLlmCandidates[0] : "none",
+    const initialValue = current.llm ? "keep" : ollamaAvailable ? "ollama" : (LLM_PRESETS[0]?.value ?? "none");
+    const choice = await prompt(() => p.select({
+        message: "Configure an LLM for richer metadata during indexing:",
+        options,
+        initialValue,
     }));
-    if (llmChoice === "keep") {
-        llm = current.llm;
-    }
-    else if (llmChoice !== "none") {
+    if (choice === "keep")
+        return current.llm;
+    if (choice === "none")
+        return undefined;
+    let llm;
+    if (choice === "ollama") {
+        const modelChoice = await prompt(() => p.select({
+            message: "Which Ollama model?",
+            options: (ollamaChatModels ?? []).map((m) => ({ value: m, label: m })),
+            initialValue: ollamaChatModels?.[0],
+        }));
         llm = {
             provider: "ollama",
-            endpoint: `${ollama.endpoint}/v1/chat/completions`,
-            model: llmChoice,
+            endpoint: `${ollamaEndpoint}/v1/chat/completions`,
+            model: modelChoice,
+            temperature: 0.3,
+            maxTokens: 1024,
+        };
+    }
+    else if (choice === "custom") {
+        const endpoint = await prompt(() => p.text({
+            message: "OpenAI-compatible chat completions endpoint:",
+            placeholder: "https://your-host/v1/chat/completions",
+            validate: (v) => {
+                if (!v?.trim())
+                    return "Endpoint cannot be empty";
+                if (!v.startsWith("http://") && !v.startsWith("https://"))
+                    return "Endpoint must start with http:// or https://";
+            },
+        }));
+        const model = await prompt(() => p.text({
+            message: "Model name:",
+            placeholder: "gpt-4o-mini",
+            validate: (v) => {
+                if (!v?.trim())
+                    return "Model name cannot be empty";
+            },
+        }));
+        llm = {
+            provider: "custom",
+            endpoint: endpoint.trim(),
+            model: model.trim(),
+            temperature: 0.3,
+            maxTokens: 1024,
+        };
+    }
+    else {
+        const preset = LLM_PRESETS.find((p) => p.value === choice);
+        if (!preset)
+            return undefined;
+        const model = await prompt(() => p.text({
+            message: `Model for ${preset.label}:`,
+            placeholder: preset.defaultModel,
+            defaultValue: preset.defaultModel,
+            validate: (v) => {
+                if (!v?.trim())
+                    return "Model name cannot be empty";
+            },
+        }));
+        llm = {
+            provider: preset.value,
+            endpoint: preset.endpoint,
+            model: model.trim() || preset.defaultModel,
             temperature: 0.3,
-            maxTokens: 512,
+            maxTokens: 1024,
+            contextWindow: preset.contextWindow,
         };
     }
-    return { embedding, llm };
+    // Remind the user about API key placement. We do not offer a "store in config"
+    // option because saveConfig() strips apiKey fields before writing — persisting
+    // secrets would need an encrypted/secure store that we don't ship.
+    const needsKey = llm.provider !== "ollama" && !llm.endpoint.includes("localhost");
+    if (needsKey && !process.env.AKM_LLM_API_KEY) {
+        p.log.info("This provider requires an API key. Set AKM_LLM_API_KEY in your shell (e.g. `export AKM_LLM_API_KEY=...`) before running `akm index`.");
+    }
+    // Capability probe — best-effort, never blocks setup.
+    const probeSpin = p.spinner();
+    probeSpin.start("Probing LLM (structured-output round-trip)...");
+    const probe = await probeLlmCapabilities(llm);
+    if (probe.reachable && probe.structuredOutput) {
+        probeSpin.stop("LLM reachable; structured output verified.");
+        llm.capabilities = { ...(llm.capabilities ?? {}), structuredOutput: true };
+    }
+    else if (probe.reachable) {
+        probeSpin.stop("LLM reachable but structured-output probe failed.");
+        llm.capabilities = { ...(llm.capabilities ?? {}), structuredOutput: false };
+    }
+    else {
+        probeSpin.stop("LLM not reachable.");
+        p.log.warn(`Could not reach the LLM endpoint${probe.error ? ` (${probe.error})` : ""}. Configuration was saved; verify your endpoint and API key, then retry.`);
+    }
+    return llm;
 }
 async function stepRegistries(current) {
     const defaults = DEFAULT_CONFIG.registries ?? [];
@@ -402,7 +521,7 @@ export async function stepStashSources(current) {
     for (const url of selectedRepos) {
         if (!existingUrls.has(url)) {
             const rec = RECOMMENDED_GITHUB_REPOS.find((r) => r.url === url);
-            stashes.push({ type: "github", url, name: rec?.name });
+            stashes.push({ type: "git", url, name: rec?.name });
             existingUrls.add(url);
         }
     }
@@ -489,7 +608,7 @@ export async function stepStashSources(current) {
             }));
             if (name === null)
                 continue;
-            const entry = { type: "github", url: url.trim() };
+            const entry = { type: "git", url: url.trim() };
             if (name.trim())
                 entry.name = name.trim();
             if (!stashes.some((s) => s.url === entry.url)) {
@@ -579,9 +698,15 @@ export async function runSetupWizard() {
         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 } = online ? await stepOllama(current) : { embedding: current.embedding, llm: current.llm };
+    // Step 2: Embedding (Ollama detection drives the embedding choice + surfaces
+    // the Ollama endpoint to the LLM step that follows).
+    p.log.step("Step 2: Embedding");
+    const { embedding, ollamaEndpoint, ollamaChatModels } = online
+        ? await stepOllama(current)
+        : { embedding: current.embedding };
+    // Step 2b: LLM provider — Anthropic / OpenAI / Gemini / Ollama / custom.
+    p.log.step("Step 2b: LLM Provider");
+    const llm = online ? await stepLlm(current, ollamaEndpoint, ollamaChatModels) : current.llm;
     // Step 3: Semantic search assets
     p.log.step("Step 3: Semantic Search");
     const semanticSearchMode = await stepSemanticSearch(current, embedding);

package/dist/stash-add.js

@@ -8,32 +8,50 @@ import { upsertLockEntry } from "./lockfile";
 import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
 import { ensureWebsiteMirror, validateWebsiteInputUrl } from "./stash-providers/website";
+import { warn } from "./warn";
+import { validateWikiName } from "./wiki";
+const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
         throw new UsageError("Install ref or local directory is required. " +
             "Examples: `akm add @scope/kit`, `akm add github:owner/repo`, `akm add ./local/path`");
+    // Validate and resolve wiki name when --type wiki is used
+    let wikiName;
+    if (input.overrideType) {
+        if (!VALID_OVERRIDE_TYPES.has(input.overrideType)) {
+            throw new UsageError(`Invalid --type value: "${input.overrideType}". Supported types: ${[...VALID_OVERRIDE_TYPES].join(", ")}`);
+        }
+        if (input.overrideType === "wiki") {
+            const derived = input.name ?? deriveWikiNameFromRef(ref);
+            validateWikiName(derived);
+            wikiName = derived;
+        }
+    }
     const stashDir = resolveStashDir();
     if (shouldAddAsWebsiteUrl(ref)) {
-        return addWebsiteStashSource(ref, stashDir, input.name, input.options);
+        return addWebsiteStashSource(ref, stashDir, input.name ?? wikiName, input.options, wikiName);
     }
     // Detect local directory refs and route them to stashes[] instead of installed[]
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
-            return addLocalStashSource(ref, parsed.sourcePath, stashDir);
+            if (input.trustThisInstall) {
+                warn("--trust has no effect on local directory sources; the install audit is not run for local paths.");
+            }
+            return addLocalStashSource(ref, parsed.sourcePath, stashDir, wikiName);
         }
     }
     catch {
         // Not a local ref — fall through to registry install
     }
-    return addRegistryKit(ref, stashDir);
+    return addRegistryKit(ref, stashDir, input.trustThisInstall, input.writable, wikiName);
 }
 /**
  * Add a local directory as a filesystem stash source.
  * Creates a stashes[] entry instead of an installed[] entry.
  */
-async function addLocalStashSource(ref, sourcePath, stashDir) {
+async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
     const config = loadUserConfig();
@@ -44,11 +62,16 @@ async function addLocalStashSource(ref, sourcePath, stashDir) {
         const entry = {
             type: "filesystem",
             path: resolvedPath,
-            name: toReadableId(resolvedPath),
+            name: wikiName ?? toReadableId(resolvedPath),
+            ...(wikiName ? { wikiName } : {}),
         };
         stashes.push(entry);
         saveConfig({ ...config, stashes });
     }
+    else if (wikiName && existing.wikiName !== wikiName) {
+        existing.wikiName = wikiName;
+        saveConfig({ ...config, stashes });
+    }
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
@@ -73,7 +96,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir) {
         },
     };
 }
-async function addWebsiteStashSource(ref, stashDir, name, options) {
+async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
     const normalizedUrl = validateWebsiteInputUrl(ref);
     const config = loadUserConfig();
     const stashes = [...(config.stashes ?? [])];
@@ -84,13 +107,23 @@ async function addWebsiteStashSource(ref, stashDir, name, options) {
             url: normalizedUrl,
             name: name ?? toWebsiteName(normalizedUrl),
             ...(options && Object.keys(options).length > 0 ? { options } : {}),
+            ...(wikiName ? { wikiName } : {}),
         };
         stashes.push(entry);
         saveConfig({ ...config, stashes });
     }
-    else if (options && Object.keys(options).length > 0) {
-        entry.options = { ...entry.options, ...options };
-        saveConfig({ ...config, stashes });
+    else {
+        let changed = false;
+        if (options && Object.keys(options).length > 0) {
+            entry.options = { ...entry.options, ...options };
+            changed = true;
+        }
+        if (wikiName && entry.wikiName !== wikiName) {
+            entry.wikiName = wikiName;
+            changed = true;
+        }
+        if (changed)
+            saveConfig({ ...config, stashes });
     }
     const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
     const index = await akmIndex({ stashDir });
@@ -120,8 +153,8 @@ async function addWebsiteStashSource(ref, stashDir, name, options) {
 /**
  * Install a kit from a registry (npm, github, git).
  */
-async function addRegistryKit(ref, stashDir) {
-    const installed = await installRegistryRef(ref);
+async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiName) {
+    const installed = await installRegistryRef(ref, { trustThisInstall, writable });
     const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === installed.id);
     const config = upsertInstalledRegistryEntry({
         id: installed.id,
@@ -133,6 +166,8 @@ async function addRegistryKit(ref, stashDir) {
         stashRoot: installed.stashRoot,
         cacheDir: installed.cacheDir,
         installedAt: installed.installedAt,
+        writable: installed.writable,
+        ...(wikiName ? { wikiName } : {}),
     });
     await upsertLockEntry({
         id: installed.id,
@@ -211,3 +246,41 @@ function toWebsiteName(siteUrl) {
         return siteUrl;
     }
 }
+/**
+ * Derive a wiki name from a ref string when --name is not provided.
+ * Lowercases and slugifies the most meaningful identifier segment.
+ */
+export function deriveWikiNameFromRef(ref) {
+    let candidate = ref;
+    // github:owner/repo or github:owner/repo@ref
+    if (/^github:/i.test(ref)) {
+        const repoPath = ref.replace(/^github:/i, "").split("@")[0];
+        candidate = repoPath.split("/").pop() ?? repoPath;
+    }
+    // npm:pkg or @scope/pkg
+    else if (/^npm:/i.test(ref) || ref.startsWith("@")) {
+        candidate = ref
+            .replace(/^npm:/i, "")
+            .replace(/^@[^/]+\//, "")
+            .split("@")[0];
+    }
+    // git URLs or HTTPS git URLs
+    else if (/^(git:|https?:\/\/)/.test(ref)) {
+        try {
+            candidate = new URL(ref).pathname.split("/").pop() ?? candidate;
+        }
+        catch {
+            candidate = ref.split("/").pop() ?? ref;
+        }
+        candidate = candidate.replace(/\.git$/, "");
+    }
+    // Local paths
+    else {
+        candidate = path.basename(ref.replace(/\/+$/, ""));
+    }
+    return candidate
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+}