akm-cli 0.5.0 → 0.6.0-rc1

package/dist/renderers.js

@@ -411,6 +411,58 @@ const memoryMdRenderer = {
             content: ctx.content(),
         };
     },
+    extractMetadata(entry, ctx) {
+        try {
+            const parsed = parseFrontmatter(ctx.content());
+            const fm = parsed.data;
+            // Description from frontmatter
+            const desc = toStringOrUndefined(fm.description);
+            if (desc && !entry.description) {
+                entry.description = desc;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+            // Tags from frontmatter
+            if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+                const fmTags = fm.tags.filter((t) => typeof t === "string" && t.trim().length > 0);
+                if (fmTags.length > 0) {
+                    entry.tags = Array.from(new Set([...(entry.tags ?? []), ...fmTags]));
+                }
+            }
+            // Build searchHints from structured memory metadata fields
+            const hints = new Set(entry.searchHints ?? []);
+            const source = toStringOrUndefined(fm.source);
+            if (source)
+                hints.add(source);
+            // observed_at: prefer frontmatter value, fall back to file mtime
+            const fmObservedAt = toStringOrUndefined(fm.observed_at);
+            if (fmObservedAt) {
+                hints.add(`observed_at:${fmObservedAt}`);
+            }
+            else {
+                // mtime fallback: format as ISO date (YYYY-MM-DD)
+                try {
+                    const mtime = ctx.stat().mtime;
+                    const isoDate = mtime.toISOString().slice(0, 10);
+                    hints.add(`observed_at:${isoDate}`);
+                }
+                catch {
+                    // Non-fatal: skip mtime fallback on stat error
+                }
+            }
+            const expires = toStringOrUndefined(fm.expires);
+            if (expires)
+                hints.add(`expires:${expires}`);
+            if (fm.subjective === true)
+                hints.add("subjective");
+            if (hints.size > 0) {
+                entry.searchHints = Array.from(hints).filter(Boolean);
+            }
+        }
+        catch {
+            // Non-fatal: skip metadata extraction on error
+        }
+    },
 };
 // ── 6. workflow-md ───────────────────────────────────────────────────────────
 const workflowMdRenderer = {

package/dist/search-source.js

@@ -5,15 +5,25 @@ import { loadConfig } from "./config";
 import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "./stash-providers/git";
 import { ensureWebsiteMirror, getCachePaths as getWebsiteCachePaths } from "./stash-providers/website";
 import { warn } from "./warn";
+// Legacy "context-hub" / "github" type aliases are normalized to "git" at
+// config-load time (see src/config.ts), so this set only contains the canonical
+// type.
+const GIT_STASH_TYPES = new Set(["git"]);
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
- * Build the ordered list of stash sources:
- *   1. Primary stash dir (user's own, destination for clone)
- *   2. Additional stashes (filesystem and remote providers)
- *   3. Installed kit paths (cache-managed, from registry)
+ * Build the ordered list of stash sources, walking every configured stash
+ * once. Iteration order:
  *
- * The first entry is always the primary stash. Additional entries come
- * from `stashes` config and `installed` kit entries.
+ *   1. The primary stash directory (the entry marked `primary: true`, or the
+ *      legacy top-level `stashDir`). Always emitted, even when the directory
+ *      does not yet exist on disk, so callers can use it as the clone target.
+ *   2. Each entry in `config.stashes[]` (in declared order), excluding the
+ *      one already emitted as the primary.
+ *   3. Each entry in `config.installed[]` (registry-managed stashes).
+ *
+ * Replaces the previous four-pass loop that walked `stashes[]` separately
+ * for each provider kind. Disabled entries (`enabled: false`) and entries
+ * whose disk path doesn't exist are filtered after deduplication.
  */
 export function resolveStashSources(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
@@ -36,48 +46,70 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             });
         }
     };
-    // Filesystem entries from stashes[]
-    for (const entry of config.stashes ?? []) {
-        if (entry.type === "filesystem" && entry.path && entry.enabled !== false) {
-            addSource(entry.path, entry.name, entry.wikiName);
-        }
+    // (1) + (2) Single pass over declared stashes — primary first if present,
+    // then the rest in declared order. The primary's directory is already
+    // injected as `sources[0]` above, so we only need to dedupe the source set.
+    const stashes = config.stashes ?? [];
+    const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
+    const ordered = [];
+    if (primaryIdx >= 0) {
+        ordered.push(stashes[primaryIdx]);
+        stashes.forEach((entry, i) => {
+            if (i !== primaryIdx)
+                ordered.push(entry);
+        });
     }
-    // Git stash entries: resolve cache directory so the indexer can walk it.
-    // "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 {
-                const repo = parseGitRepoUrl(entry.url);
-                const cachePaths = getCachePaths(repo.canonicalUrl);
-                // 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, entry.wikiName);
-            }
-            catch (err) {
-                warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
+    else {
+        ordered.push(...stashes);
     }
-    // Website stash entries: resolve cache directory so the indexer can walk
-    // the scraped markdown snapshots.
-    for (const entry of config.stashes ?? []) {
-        if (entry.type === "website" && entry.url && entry.enabled !== false) {
-            try {
-                const cachePaths = getWebsiteCachePaths(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)}`);
-            }
-        }
+    for (const entry of ordered) {
+        if (entry.enabled === false)
+            continue;
+        const dir = resolveEntryContentDir(entry);
+        if (dir == null)
+            continue;
+        addSource(dir, entry.name, entry.wikiName);
     }
-    // Installed kits (registry and local)
+    // (3) Installed stashes (registry-managed). Always last.
     for (const entry of config.installed ?? []) {
         addSource(entry.stashRoot, entry.id, entry.wikiName);
     }
     return sources;
 }
+/**
+ * Resolve the content directory the indexer should walk for a given config
+ * entry. Returns `undefined` if the entry has no walkable content (e.g. an
+ * `openviking` remote stash) so the caller can skip it.
+ */
+function resolveEntryContentDir(entry) {
+    if (entry.type === "filesystem" && entry.path) {
+        return entry.path;
+    }
+    if (GIT_STASH_TYPES.has(entry.type) && entry.url) {
+        try {
+            const repo = parseGitRepoUrl(entry.url);
+            const cachePaths = getCachePaths(repo.canonicalUrl);
+            // The content/ subdirectory inside the extracted repo is the actual
+            // stash root containing DOC.md / SKILL.md files that the walker indexes.
+            return path.join(cachePaths.repoDir, "content");
+        }
+        catch (err) {
+            warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
+    if (entry.type === "website" && entry.url) {
+        try {
+            return getWebsiteCachePaths(entry.url).stashDir;
+        }
+        catch (err) {
+            warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
+    // Remote-only providers (openviking) have no walkable directory.
+    return undefined;
+}
 /**
  * Convenience: returns just the directory paths, preserving priority order.
  */
@@ -168,8 +200,7 @@ function isValidDirectory(dir) {
         return false;
     }
 }
-// ── Git stash cache integration ──────────────────────────────────────────────
-const GIT_STASH_TYPES = new Set(["context-hub", "github", "git"]);
+// ── Stash cache integration ─────────────────────────────────────────────────
 /**
  * Ensure all cache-backed stash providers are refreshed so their cache
  * directories exist on disk. Must be called (async) before

package/dist/setup-steps.js

@@ -0,0 +1,45 @@
+/**
+ * Composable runner abstraction for `akm setup`.
+ *
+ * The interactive wizard in `setup.ts` historically ran a fixed series of
+ * step functions (`stepStashDir`, `stepOllama`, `stepLlm`, ...) inline.
+ * This module formalizes that pattern so steps can be:
+ *   - reused by `akm init` (non-interactive preset, see Finding 31),
+ *   - tested in isolation by passing a stub `SetupContext`, and
+ *   - extended by plugins without touching the wizard call site.
+ *
+ * Steps mutate state through `SetupContext.apply()`, which accumulates a
+ * delta on top of the original config. `stepLlm` reading the embedding
+ * endpoint that `stepSemanticSearch` produced is the canonical example of
+ * why mutable accumulation is preferred over immutable returns.
+ */
+/**
+ * Build a fresh `SetupContext` over a starting config. The returned context
+ * applies deltas in-place onto an internal accumulator and exposes the
+ * latest snapshot via `ctx.config`.
+ */
+export function createSetupContext(initial, options) {
+    let acc = { ...initial };
+    return {
+        get config() {
+            return acc;
+        },
+        nonInteractive: options.nonInteractive,
+        apply(delta) {
+            acc = { ...acc, ...delta };
+        },
+    };
+}
+/**
+ * Run a list of steps against a context. Steps marked interactive-only are
+ * skipped when `ctx.nonInteractive` is true. Returns the final accumulated
+ * config so callers can persist it without re-reading the context.
+ */
+export async function runSetupSteps(steps, ctx) {
+    for (const step of steps) {
+        if (ctx.nonInteractive && !step.nonInteractive)
+            continue;
+        await step.run(ctx);
+    }
+    return ctx.config;
+}

package/dist/setup.js

@@ -17,15 +17,16 @@ import { akmInit } from "./init";
 import { probeLlmCapabilities } from "./llm";
 import { getDefaultStashDir } from "./paths";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./semantic-status";
+import { createSetupContext, runSetupSteps } from "./setup-steps";
 // ── Constants ───────────────────────────────────────────────────────────────
-/** Recommended GitHub repositories shown during setup. */
-const RECOMMENDED_GITHUB_REPOS = [
-    {
-        url: "https://github.com/andrewyng/context-hub",
-        name: "context-hub",
-        hint: "community knowledge",
-    },
-];
+/**
+ * Recommended GitHub repositories shown during setup.
+ *
+ * Currently empty — populating from the akm-registry at runtime is a
+ * separate feature. The wizard prompt infrastructure is retained for that
+ * future use.
+ */
+const RECOMMENDED_GITHUB_REPOS = [];
 // Approximate first-download sizes used in the setup note.
 // LOCAL_MODEL_APPROX_SIZE_MB tracks the default local model (DEFAULT_LOCAL_MODEL).
 const LOCAL_MODEL_APPROX_SIZE_MB = 130;
@@ -136,7 +137,7 @@ async function prepareSemanticSearchAssets(config) {
     const remote = isRemoteEmbeddingConfig(config.embedding);
     // For local embeddings, ensure the required package is installed first.
     if (!remote) {
-        if (!(await isTransformersAvailable())) {
+        if (!isTransformersAvailable()) {
             const spin = p.spinner();
             spin.start("Installing @huggingface/transformers...");
             try {
@@ -505,34 +506,38 @@ export async function stepStashSources(current) {
         p.log.info(`You have ${stashes.length} existing stash source(s).`);
     }
     // ── Recommended GitHub repos ───────────────────────────────────────────
-    const existingUrls = new Set(stashes.map((s) => s.url));
-    const repoOptions = RECOMMENDED_GITHUB_REPOS.map((r) => ({
-        value: r.url,
-        label: r.name,
-        hint: existingUrls.has(r.url) ? `${r.hint} (already added)` : r.hint,
-    }));
-    const selectedRepos = await prompt(() => p.multiselect({
-        message: "Recommended GitHub repositories — toggle to add or remove:",
-        options: repoOptions,
-        initialValues: repoOptions.filter((o) => existingUrls.has(o.value)).map((o) => o.value),
-        required: false,
-    }));
-    // Add newly selected repos
-    for (const url of selectedRepos) {
-        if (!existingUrls.has(url)) {
-            const rec = RECOMMENDED_GITHUB_REPOS.find((r) => r.url === url);
-            stashes.push({ type: "git", url, name: rec?.name });
-            existingUrls.add(url);
+    // Skip the prompt entirely when there are no recommendations to show.
+    // The infrastructure is retained for a future registry-driven version.
+    if (RECOMMENDED_GITHUB_REPOS.length > 0) {
+        const existingUrls = new Set(stashes.map((s) => s.url));
+        const repoOptions = RECOMMENDED_GITHUB_REPOS.map((r) => ({
+            value: r.url,
+            label: r.name,
+            hint: existingUrls.has(r.url) ? `${r.hint} (already added)` : r.hint,
+        }));
+        const selectedRepos = await prompt(() => p.multiselect({
+            message: "Recommended GitHub repositories — toggle to add or remove:",
+            options: repoOptions,
+            initialValues: repoOptions.filter((o) => existingUrls.has(o.value)).map((o) => o.value),
+            required: false,
+        }));
+        // Add newly selected repos
+        for (const url of selectedRepos) {
+            if (!existingUrls.has(url)) {
+                const rec = RECOMMENDED_GITHUB_REPOS.find((r) => r.url === url);
+                stashes.push({ type: "git", url, name: rec?.name });
+                existingUrls.add(url);
+            }
         }
-    }
-    // Remove deselected repos that were previously configured
-    for (const rec of RECOMMENDED_GITHUB_REPOS) {
-        if (existingUrls.has(rec.url) && !selectedRepos.includes(rec.url)) {
-            const idx = stashes.findIndex((s) => s.url === rec.url);
-            if (idx !== -1) {
-                stashes.splice(idx, 1);
-                existingUrls.delete(rec.url);
-                p.log.info(`Removed ${rec.name}.`);
+        // Remove deselected repos that were previously configured
+        for (const rec of RECOMMENDED_GITHUB_REPOS) {
+            if (existingUrls.has(rec.url) && !selectedRepos.includes(rec.url)) {
+                const idx = stashes.findIndex((s) => s.url === rec.url);
+                if (idx !== -1) {
+                    stashes.splice(idx, 1);
+                    existingUrls.delete(rec.url);
+                    p.log.info(`Removed ${rec.name}.`);
+                }
             }
         }
     }
@@ -685,60 +690,128 @@ async function stepAgentPlatforms(current) {
     return entries;
 }
 // ── Main Wizard ─────────────────────────────────────────────────────────────
+/**
+ * Build the canonical list of `SetupStep`s for the interactive wizard.
+ * Exposed (and exported) so tests and `akm init` can compose subsets.
+ *
+ * Each step wraps the existing `step*` functions, accumulating its result
+ * into the shared `SetupContext`. The `nonInteractive` flag controls
+ * inclusion in `akm init` (a non-interactive preset of `akm setup`).
+ */
+export function buildSetupSteps(options) {
+    const outcome = { semantic: options.semanticSearchOutcome };
+    // Local cache of Ollama-detected fields surfaced from the embedding step
+    // to the LLM step. Mutable by design — `stepLlm` needs them.
+    let ollamaEndpoint;
+    let ollamaChatModels;
+    const steps = [
+        {
+            id: "stash-dir",
+            label: "Stash Directory",
+            nonInteractive: true,
+            async run(ctx) {
+                const stashDir = await stepStashDir(ctx.config);
+                ctx.apply({ stashDir });
+            },
+        },
+        {
+            id: "embedding",
+            label: "Embedding",
+            async run(ctx) {
+                if (!options.online) {
+                    ctx.apply({ embedding: ctx.config.embedding });
+                    return;
+                }
+                const result = await stepOllama(ctx.config);
+                ollamaEndpoint = result.ollamaEndpoint;
+                ollamaChatModels = result.ollamaChatModels;
+                ctx.apply({ embedding: result.embedding });
+            },
+        },
+        {
+            id: "llm",
+            label: "LLM Provider",
+            async run(ctx) {
+                if (!options.online) {
+                    ctx.apply({ llm: ctx.config.llm });
+                    return;
+                }
+                const llm = await stepLlm(ctx.config, ollamaEndpoint, ollamaChatModels);
+                ctx.apply({ llm });
+            },
+        },
+        {
+            id: "semantic-search",
+            label: "Semantic Search",
+            async run(ctx) {
+                const semantic = await stepSemanticSearch(ctx.config, ctx.config.embedding);
+                outcome.semantic = semantic;
+                ctx.apply({ semanticSearchMode: semantic.mode });
+            },
+        },
+        {
+            id: "registries",
+            label: "Registries",
+            async run(ctx) {
+                const registries = await stepRegistries(ctx.config);
+                ctx.apply({ registries });
+            },
+        },
+        {
+            id: "stash-sources",
+            label: "Stash Sources",
+            async run(ctx) {
+                const stashes = await stepStashSources(ctx.config);
+                const platforms = await stepAgentPlatforms(ctx.config);
+                const merged = [...stashes];
+                for (const ps of platforms) {
+                    if (!merged.some((s) => s.path === ps.path))
+                        merged.push(ps);
+                }
+                ctx.apply({ stashes: merged.length > 0 ? merged : undefined });
+            },
+        },
+    ];
+    return { steps, outcome };
+}
 export async function runSetupWizard() {
     p.intro("akm setup");
     const current = loadUserConfig();
     const configPath = getConfigPath();
-    // 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: 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);
-    // Step 4: Registries
-    p.log.step("Step 4: Registries");
-    const registries = await stepRegistries(current);
-    // Step 5: Stash sources
-    p.log.step("Step 5: Stash Sources");
-    const stashes = await stepStashSources(current);
-    // Step 6: Agent platform detection
-    p.log.step("Step 6: Agent Platform Detection");
-    const platformStashes = await stepAgentPlatforms(current);
-    // Merge platform stashes into main stashes list
-    const allStashes = [...stashes];
-    for (const ps of platformStashes) {
-        if (!allStashes.some((s) => s.path === ps.path)) {
-            allStashes.push(ps);
-        }
-    }
-    // Build final config
+    const ctx = createSetupContext(current, { nonInteractive: false });
+    const { steps, outcome } = buildSetupSteps({
+        online,
+        semanticSearchOutcome: { mode: current.semanticSearchMode, prepareAssets: false },
+    });
+    // Wrap each step with a `p.log.step()` header so the wizard UI is
+    // unchanged. The canonical `runSetupSteps()` runner is used directly by
+    // `akm init` (non-interactive) and by tests.
+    const labeledSteps = steps.map((step) => ({
+        ...step,
+        async run(stepCtx) {
+            p.log.step(step.label);
+            await step.run(stepCtx);
+        },
+    }));
+    await runSetupSteps(labeledSteps, ctx);
     const newConfig = {
-        ...current,
-        stashDir,
-        embedding,
-        llm,
-        registries,
-        stashes: allStashes.length > 0 ? allStashes : undefined,
-        // Preserve existing fields
-        semanticSearchMode: semanticSearchMode.mode,
+        ...ctx.config,
+        // Preserve fields the steps don't manage explicitly.
         installed: current.installed,
         output: current.output,
     };
+    const semanticSearchMode = outcome.semantic;
+    const stashDir = newConfig.stashDir ?? current.stashDir ?? getDefaultStashDir();
+    const embedding = newConfig.embedding;
+    const llm = newConfig.llm;
+    const registries = newConfig.registries;
+    const allStashes = newConfig.stashes ?? [];
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([