akm-cli 0.4.0 → 0.5.0-rc1

package/dist/renderers.js

@@ -9,10 +9,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { hasErrnoCode } from "./common";
+import { UsageError } from "./errors";
 import { registerRenderer } from "./file-context";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
 import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "./markdown";
 import { extractDescriptionFromComments, loadStashFile } from "./metadata";
+import { makeAssetRef } from "./stash-ref";
+import { listKeys as listVaultKeys } from "./vault";
+import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
 // ── Interpreter auto-detection map ───────────────────────────────────────────
 const INTERPRETER_MAP = {
     ".sh": "bash",
@@ -149,6 +153,12 @@ function deriveName(ctx) {
     const ext = path.extname(ctx.relPath);
     return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
 }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function buildWorkflowAction(ref) {
+    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+}
 /**
  * Load the matching StashEntry for a file path from the directory's .stash.json.
  */
@@ -309,6 +319,85 @@ const knowledgeMdRenderer = {
         }
     },
 };
+// ── 4b. wiki-md ──────────────────────────────────────────────────────────────
+const WIKI_PAGE_ACTION = "Wiki page — read below. Use 'toc' to scan, 'section <heading>' for depth.";
+const wikiMdRenderer = {
+    name: "wiki-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const v = ctx.matchResult.meta?.view ?? { mode: "full" };
+        const content = ctx.content();
+        switch (v.mode) {
+            case "toc": {
+                const toc = parseMarkdownToc(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: formatToc(toc),
+                };
+            }
+            case "frontmatter": {
+                const fm = extractFrontmatterOnly(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: fm ?? "(no frontmatter)",
+                };
+            }
+            case "section": {
+                const section = extractSection(content, v.heading);
+                if (!section) {
+                    return {
+                        type: "wiki",
+                        name,
+                        path: ctx.absPath,
+                        action: WIKI_PAGE_ACTION,
+                        content: `Section "${v.heading}" not found in ${name}. Try \`akm show wiki:${name} toc\` to discover available headings.`,
+                    };
+                }
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: section.content,
+                };
+            }
+            case "lines": {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: extractLineRange(content, v.start, v.end),
+                };
+            }
+            default: {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content,
+                };
+            }
+        }
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const toc = parseMarkdownToc(ctx.content());
+            if (toc.headings.length > 0)
+                entry.toc = toc.headings;
+        }
+        catch {
+            // Non-fatal: skip TOC if file can't be read
+        }
+    },
+};
 // ── 5. memory-md ─────────────────────────────────────────────────────────────
 const memoryMdRenderer = {
     name: "memory-md",
@@ -323,7 +412,58 @@ const memoryMdRenderer = {
         };
     },
 };
-// ── 6. script-source ─────────────────────────────────────────────────────────
+// ── 6. workflow-md ───────────────────────────────────────────────────────────
+const workflowMdRenderer = {
+    name: "workflow-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: workflow.description,
+            workflowTitle: workflow.title,
+            parameters: workflow.parameters?.map((parameter) => parameter.name),
+            workflowParameters: workflow.parameters,
+            steps: workflow.steps,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(workflow.title);
+        for (const step of workflow.steps) {
+            hints.add(step.title);
+            hints.add(step.id);
+            hints.add(step.instructions);
+            for (const criterion of step.completionCriteria ?? []) {
+                hints.add(criterion);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (workflow.parameters?.length) {
+            entry.parameters = workflow.parameters.map((parameter) => ({
+                name: parameter.name,
+                ...(parameter.description ? { description: parameter.description } : {}),
+            }));
+        }
+    },
+};
+function parseWorkflowForRendering(content) {
+    try {
+        return parseWorkflowMarkdown(content);
+    }
+    catch (error) {
+        if (error instanceof WorkflowValidationError) {
+            throw new UsageError(error.message);
+        }
+        throw error;
+    }
+}
+// ── 7. script-source ─────────────────────────────────────────────────────────
 const scriptSourceRenderer = {
     name: "script-source",
     buildShowResponse(ctx) {
@@ -379,6 +519,43 @@ const scriptSourceRenderer = {
         }
     },
 };
+// ── 8. vault-env ─────────────────────────────────────────────────────────────
+/**
+ * Vault renderer. Returns ONLY key names and start-of-line comments — never
+ * values. Deliberately omits content/template/prompt so vault values cannot
+ * leak through `akm show`.
+ */
+const vaultEnvRenderer = {
+    name: "vault-env",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        return {
+            type: "vault",
+            name,
+            path: ctx.absPath,
+            action: 'Vault — keys + comments only. Use `eval "$(akm vault load <ref>)"` to load values into the current shell. Values stay on disk and are never written to akm\'s stdout.',
+            description: comments.length > 0 ? comments.join("\n") : undefined,
+            keys,
+            comments,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        // Re-derive from the file directly to guarantee no value ever transits
+        // through any other code path. Caller already short-circuits in
+        // generateMetadata{,Flat}, but this is defense in depth.
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        if (comments.length > 0 && !entry.description) {
+            entry.description = comments.join(" ").slice(0, 500);
+            entry.source = "comments";
+            entry.confidence = 0.7;
+        }
+        if (keys.length > 0) {
+            entry.searchHints = keys;
+        }
+        entry.tags = Array.from(new Set([...(entry.tags ?? []), "vault", "secrets"]));
+    },
+};
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -386,8 +563,11 @@ const builtinRenderers = [
     commandMdRenderer,
     agentMdRenderer,
     knowledgeMdRenderer,
+    wikiMdRenderer,
     memoryMdRenderer,
+    workflowMdRenderer,
     scriptSourceRenderer,
+    vaultEnvRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -399,4 +579,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/search-fields.js

@@ -41,6 +41,10 @@ export function buildSearchFields(entry) {
         if (entry.intent.output)
             hintParts.push(entry.intent.output);
     }
+    if (entry.xrefs)
+        hintParts.push(entry.xrefs.join(" "));
+    if (entry.pageKind)
+        hintParts.push(entry.pageKind);
     const hints = hintParts.join(" ").toLowerCase();
     const contentParts = [];
     if (entry.toc) {

package/dist/search-source.js

@@ -20,7 +20,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
     const config = existingConfig ?? loadConfig();
     const sources = [{ path: stashDir }];
     const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId) => {
+    const addSource = (dir, registryId, wikiName) => {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
@@ -29,17 +29,21 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
         }
         if (isValidDirectory(dir)) {
-            sources.push({ path: resolved, ...(registryId ? { registryId } : {}) });
+            sources.push({
+                path: resolved,
+                ...(registryId ? { registryId } : {}),
+                ...(wikiName ? { wikiName } : {}),
+            });
         }
     };
     // Filesystem entries from stashes[]
     for (const entry of config.stashes ?? []) {
         if (entry.type === "filesystem" && entry.path && entry.enabled !== false) {
-            addSource(entry.path, entry.name);
+            addSource(entry.path, entry.name, entry.wikiName);
         }
     }
     // Git stash entries: resolve cache directory so the indexer can walk it.
-    // "context-hub", "github", and "git" provider types are handled.
+    // "git" provider type (and its legacy aliases "context-hub", "github") are handled.
     for (const entry of config.stashes ?? []) {
         if (GIT_STASH_TYPES.has(entry.type) && entry.url && entry.enabled !== false) {
             try {
@@ -48,7 +52,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
                 // The content/ subdirectory inside the extracted repo is the actual
                 // stash root containing DOC.md / SKILL.md files that the walker indexes.
                 const contentDir = path.join(cachePaths.repoDir, "content");
-                addSource(contentDir, entry.name);
+                addSource(contentDir, entry.name, entry.wikiName);
             }
             catch (err) {
                 warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
@@ -61,7 +65,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
         if (entry.type === "website" && entry.url && entry.enabled !== false) {
             try {
                 const cachePaths = getWebsiteCachePaths(entry.url);
-                addSource(cachePaths.stashDir, entry.name ?? entry.url);
+                addSource(cachePaths.stashDir, entry.name ?? entry.url, entry.wikiName);
             }
             catch (err) {
                 warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
@@ -70,7 +74,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
     }
     // Installed kits (registry and local)
     for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id);
+        addSource(entry.stashRoot, entry.id, entry.wikiName);
     }
     return sources;
 }
@@ -180,7 +184,7 @@ export async function ensureStashCaches(config) {
         try {
             const repo = parseGitRepoUrl(entry.url);
             const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true });
+            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true, writable: entry.writable === true });
         }
         catch (err) {
             warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);

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);