akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/commands/show.js

@@ -9,33 +9,31 @@
  * edit-hints, summary-detail truncation) lives below in this file. The flow:
  *
  *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
- *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
- *   3. Fall back to the on-disk type-dir resolver only when the index has
- *      no matching row — covers the "indexed yet?" gap when the user has
- *      just added a file and not run `akm index`.
+ *   2. Auto-index when stale so the index is current.
+ *   3. Ask `indexer.lookup(ref)` for the row in the FTS index.
  *   4. Render the file via the matcher/renderer pipeline.
- *
- * Step (2) is the v1 spec change: reading is the indexer's job. Step (3) is a
- * pragmatic safety net (NOT remote provider fallback, which the spec
- * forbids — "Show: Local FTS5 index only. No remote provider fallback.").
  */
 import fs from "node:fs";
 import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
+import { asNonEmptyString } from "../core/common";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
-import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
+import { parseFrontmatter } from "../core/frontmatter";
 import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
+import { ensureIndex } from "../indexer/ensure-index";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
+import { listRelatedPathsForFile } from "../indexer/graph-boost";
 import { lookup } from "../indexer/indexer";
+import { resolveAssetPath } from "../indexer/path-resolver";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
 import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 // Eagerly import source providers to trigger self-registration.
 import "../sources/providers/index";
-import { resolveAssetPath } from "../sources/resolve";
 import { getActiveWorkflowRun } from "../workflows/runs";
+import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
@@ -128,7 +126,12 @@ export async function akmShowUnified(input) {
                 new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
         }
     }
-    // Try local filesystem (FTS5 index lookup, then on-disk fallback)
+    // Auto-index when stale so the index is current before lookup.
+    const allSources = resolveSourceEntries();
+    if (allSources.length > 0) {
+        await ensureIndex(allSources[0].path);
+    }
+    // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if --scope was supplied, the asset's
     // frontmatter scope must satisfy every supplied key. We re-read the file
@@ -177,7 +180,7 @@ function enforceScopeOrThrow(filePath, ref, scope) {
     for (const [key, expectedValue] of expected) {
         if (expectedValue === undefined)
             continue;
-        const actual = toStringOrUndefined(fm[`scope_${key}`]);
+        const actual = asNonEmptyString(fm[`scope_${key}`]);
         if (actual !== expectedValue) {
             throw new NotFoundError(`Asset "${ref}" exists but is out of scope (expected scope_${key}="${expectedValue}").`);
         }
@@ -201,6 +204,31 @@ function logShowEvent(ref, existingDb) {
     // detect akm show invocations without relying on stdout scraping.
     const parsed = parseAssetRef(ref);
     appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
+    // Detect if this show is a selection from a recent search result.
+    try {
+        const { events: recentSearches } = readEvents({ type: "search" });
+        const cutoffMs = Date.now() - 60_000;
+        const matchingSearch = [...recentSearches].reverse().find((e) => {
+            if (!e.ts || new Date(e.ts).getTime() < cutoffMs)
+                return false;
+            const refs = e.metadata?.resultRefs ?? [];
+            return refs.includes(ref);
+        });
+        if (matchingSearch) {
+            appendEvent({
+                eventType: "select",
+                ref,
+                metadata: {
+                    query: matchingSearch.metadata?.query,
+                    searchTs: matchingSearch.ts,
+                    rankPosition: (matchingSearch.metadata?.resultRefs ?? []).indexOf(ref),
+                },
+            });
+        }
+    }
+    catch {
+        /* fire-and-forget — select is best-effort */
+    }
     try {
         const db = existingDb ?? openExistingDatabase();
         try {
@@ -219,40 +247,6 @@ function logShowEvent(ref, existingDb) {
         /* fire-and-forget */
     }
 }
-/**
- * Resolve an asset path to a file via:
- *   1. `indexer.lookup(ref)` — the spec's primary path (§6.2).
- *   2. On-disk type-dir traversal — fallback for files not yet indexed.
- *
- * Returns `undefined` if neither path finds a match.
- */
-async function resolvePathViaIndexThenDisk(parsed, searchSourceDirs) {
-    // Step 1: indexer
-    try {
-        const entry = await lookup(parsed);
-        if (entry) {
-            return { assetPath: entry.filePath };
-        }
-    }
-    catch (err) {
-        // Index unavailable (e.g. DB doesn't exist yet) — fall back to disk walk.
-        if (!(err instanceof NotFoundError)) {
-            // continue to disk fallback
-        }
-    }
-    // Step 2: on-disk type-dir traversal
-    let lastError;
-    for (const dir of searchSourceDirs) {
-        try {
-            const assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
-            return { assetPath, lastError };
-        }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-        }
-    }
-    return lastError ? { assetPath: "", lastError } : undefined;
-}
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseAssetRef(input.ref);
@@ -273,13 +267,11 @@ export async function showLocal(input) {
         }
     }
     if (!assetPath) {
-        const resolved = await resolvePathViaIndexThenDisk(parsed, allSourceDirs);
-        if (resolved?.assetPath) {
-            assetPath = resolved.assetPath;
-        }
-        else if (resolved?.lastError) {
-            lastError = resolved.lastError;
-        }
+        const resolvedAssetPath = await resolveAssetPath(parsed, {
+            stashDir: input.stashDir,
+            mode: "index-first",
+        });
+        assetPath = resolvedAssetPath ?? undefined;
     }
     if (!assetPath && parsed.origin && searchSources.length === 0) {
         const installCmd = `akm add ${parsed.origin}`;
@@ -318,8 +310,23 @@ export async function showLocal(input) {
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
+        related: (() => {
+            let db;
+            try {
+                db = openExistingDatabase();
+                const related = listRelatedPathsForFile(sourceStashDir, assetPath, 5, db);
+                return { total: related.length, hits: related };
+            }
+            catch {
+                return { total: 0, hits: [] };
+            }
+            finally {
+                if (db)
+                    closeDatabase(db);
+            }
+        })(),
     };
-    const activeRun = getActiveWorkflowRun();
+    const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
@@ -379,7 +386,7 @@ function buildSummaryResponse(full, assetPath) {
         const textContent = full.content ?? full.template ?? full.prompt;
         if (textContent && !description) {
             const parsed = parseFrontmatter(textContent);
-            description = toStringOrUndefined(parsed.data.description);
+            description = asNonEmptyString(parsed.data.description);
         }
     }
     const summary = {
@@ -396,3 +403,76 @@ function buildSummaryResponse(full, assetPath) {
     };
     return summary;
 }
+// ── argv normalisation ───────────────────────────────────────────────────────
+const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
+/**
+ * Normalize argv so positional view-mode arguments after the asset ref
+ * are rewritten into internal flags that citty can parse.
+ *
+ * Converts:
+ *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --akmView toc
+ *   akm show knowledge:guide.md section Auth → akm show knowledge:guide.md --akmView section --akmHeading Auth
+ *   akm show knowledge:guide.md lines 1 50   → akm show knowledge:guide.md --akmView lines --akmStart 1 --akmEnd 50
+ *
+ * Legacy `--view` is intentionally unsupported.
+ * Returns a new array; the input is never modified.
+ */
+export function normalizeShowArgv(argv) {
+    // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
+    if (argv[2] !== "show")
+        return argv;
+    if (argv[3] === "proposal")
+        return argv;
+    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
+        throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
+    }
+    // Separate global flags from positional/show-specific args
+    const prefix = argv.slice(0, 3); // [bun, script, show]
+    const rest = argv.slice(3);
+    const globalFlags = [];
+    const showArgs = [];
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--quiet" || arg === "-q" || arg === "--for-agent" || arg === "--for-agent=true") {
+            globalFlags.push(arg);
+            continue;
+        }
+        if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
+            globalFlags.push(arg);
+            continue;
+        }
+        if (arg === "--format" || arg === "--detail") {
+            globalFlags.push(arg);
+            if (rest[i + 1] !== undefined) {
+                globalFlags.push(rest[i + 1]);
+                i++;
+            }
+            continue;
+        }
+        showArgs.push(arg);
+    }
+    // showArgs[0] = ref, showArgs[1] = potential view mode, showArgs[2..] = view params
+    const ref = showArgs[0];
+    const viewMode = showArgs[1];
+    if (!ref || !viewMode || !SHOW_VIEW_MODES.has(viewMode)) {
+        return argv;
+    }
+    const result = [...prefix, ref, "--akmView", viewMode];
+    if (viewMode === "section") {
+        // Next arg is the heading name; pass empty string when missing so the
+        // show handler can produce a clear "section not found" error.
+        const heading = showArgs[2] ?? "";
+        result.push("--akmHeading", heading);
+    }
+    else if (viewMode === "lines") {
+        // Next two args are start and end
+        const start = showArgs[2];
+        const end = showArgs[3];
+        if (start)
+            result.push("--akmStart", start);
+        if (end)
+            result.push("--akmEnd", end);
+    }
+    result.push(...globalFlags);
+    return result;
+}

package/dist/commands/source-add.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir } from "../core/common";
-import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
+import { getSources, loadConfig, loadUserConfig, saveConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { akmIndex } from "../indexer/indexer";
@@ -74,7 +74,7 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
     // Derive the canonical name: explicit --name wins, then wiki name, then readable path.
     const derivedName = explicitName ?? wikiName ?? toReadableId(resolvedPath);
     // Check for duplicates in sources[]
-    const sources = [...(config.sources ?? config.stashes ?? [])];
+    const sources = [...getSources(config)];
     const existing = sources.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
     let persistedEntry;
     if (!existing) {
@@ -85,7 +85,7 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
             ...(wikiName ? { wikiName } : {}),
         };
         sources.push(persistedEntry);
-        saveConfig({ ...config, sources, stashes: undefined });
+        saveConfig({ ...config, sources });
     }
     else {
         let changed = false;
@@ -99,7 +99,7 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
             changed = true;
         }
         if (changed)
-            saveConfig({ ...config, sources, stashes: undefined });
+            saveConfig({ ...config, sources });
         persistedEntry = existing;
     }
     const index = await akmIndex({ stashDir });
@@ -116,7 +116,7 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
             ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
-            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            sourceCount: getSources(updatedConfig).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -131,7 +131,7 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
 async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
     const normalizedUrl = validateWebsiteInputUrl(ref);
     const config = loadUserConfig();
-    const sources = [...(config.sources ?? config.stashes ?? [])];
+    const sources = [...getSources(config)];
     let entry = sources.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
     if (!entry) {
         entry = {
@@ -142,7 +142,7 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
             ...(wikiName ? { wikiName } : {}),
         };
         sources.push(entry);
-        saveConfig({ ...config, sources, stashes: undefined });
+        saveConfig({ ...config, sources });
     }
     else {
         let changed = false;
@@ -155,7 +155,7 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
             changed = true;
         }
         if (changed)
-            saveConfig({ ...config, sources, stashes: undefined });
+            saveConfig({ ...config, sources });
     }
     const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
     const index = await akmIndex({ stashDir });
@@ -172,7 +172,7 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
             ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
-            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            sourceCount: getSources(updatedConfig).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -268,7 +268,7 @@ async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiN
             audit,
         },
         config: {
-            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            sourceCount: getSources(updatedConfig).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {

package/dist/commands/source-manage.js

@@ -1,5 +1,6 @@
 import path from "node:path";
-import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
+import { isRemoteUrl } from "../core/common";
+import { getSources, loadConfig, loadUserConfig, saveConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { resolveSourceEntries } from "../indexer/search-source";
 // ── Operations ──────────────────────────────────────────────────────────────
@@ -19,14 +20,9 @@ export function addStash(opts) {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
     const config = loadUserConfig();
-    const sources = [...(config.sources ?? config.stashes ?? [])];
-    const isRemoteUrl = target.startsWith("http://") ||
-        target.startsWith("https://") ||
-        target.startsWith("git@") ||
-        target.startsWith("ssh://") ||
-        target.startsWith("git://");
+    const sources = [...getSources(config)];
     let entry;
-    if (isRemoteUrl) {
+    if (isRemoteUrl(target)) {
         if (!providerType) {
             throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
         }
@@ -53,7 +49,7 @@ export function addStash(opts) {
             entry.name = name;
     }
     sources.push(entry);
-    saveConfig({ ...config, sources, stashes: undefined });
+    saveConfig({ ...config, sources });
     return { sources, added: true, entry };
 }
 /**
@@ -62,16 +58,12 @@ export function addStash(opts) {
  */
 export function removeStash(target) {
     const config = loadUserConfig();
-    const sources = [...(config.sources ?? config.stashes ?? [])];
-    const isUrl = target.startsWith("http://") ||
-        target.startsWith("https://") ||
-        target.startsWith("git@") ||
-        target.startsWith("ssh://") ||
-        target.startsWith("git://");
-    const resolvedPath = !isUrl ? path.resolve(target) : undefined;
+    const sources = [...getSources(config)];
+    const isUrlTarget = isRemoteUrl(target);
+    const resolvedPath = !isUrlTarget ? path.resolve(target) : undefined;
     // Try URL match first, then path, then name (most specific → least specific)
     let idx = -1;
-    if (isUrl) {
+    if (isUrlTarget) {
         idx = sources.findIndex((s) => s.url === target);
     }
     if (idx === -1 && resolvedPath) {
@@ -84,7 +76,7 @@ export function removeStash(target) {
         return { sources, removed: false, message: "No matching source found" };
     }
     const removed = sources.splice(idx, 1)[0];
-    saveConfig({ ...config, sources, stashes: undefined });
+    saveConfig({ ...config, sources });
     return { sources, removed: true, entry: removed };
 }
 /**
@@ -93,6 +85,6 @@ export function removeStash(target) {
 export function listStashes() {
     const config = loadConfig();
     const localSources = resolveSourceEntries();
-    const sources = config.sources ?? config.stashes ?? [];
+    const sources = getSources(config);
     return { localSources, sources };
 }