akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/commands/show.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * `akm show` — entry point.
  *
@@ -16,14 +19,17 @@
 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 { NotFoundError, rethrowIfTestIsolationError, 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";
@@ -139,7 +145,7 @@ export async function akmShowUnified(input) {
     }
     // Count prior shows of this ref before logging the current one.
     const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref);
+    logShowEvent(ref, undefined, input.eventSource);
     if (priorShowCount >= 2) {
         // Agent has shown this same asset 3+ times — inject a loop-break hint.
         result.showLoopWarning = priorShowCount + 1;
@@ -177,7 +183,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}").`);
         }
@@ -189,18 +195,51 @@ function enforceScopeOrThrow(filePath, ref, scope) {
  */
 function recentShowCount(ref) {
     try {
-        const { events } = readEvents({ type: "show", ref });
+        const { events } = readEvents({
+            type: "show",
+            ref,
+            since: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+        });
         return events.length;
     }
     catch {
         return 0;
     }
 }
-function logShowEvent(ref, existingDb) {
+function logShowEvent(ref, existingDb, eventSource = "user") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // 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 {
+        // D7: bound the query to the last 60 s so we never scan unbounded history
+        const { events: recentSearches } = readEvents({
+            type: "search",
+            since: new Date(Date.now() - 60_000).toISOString(),
+        });
+        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 {
@@ -208,6 +247,7 @@ function logShowEvent(ref, existingDb) {
                 event_type: "show",
                 entry_ref: ref,
                 entry_id: findEntryIdByRef(db, ref),
+                source: eventSource,
             });
         }
         finally {
@@ -215,22 +255,11 @@ function logShowEvent(ref, existingDb) {
                 closeDatabase(db);
         }
     }
-    catch {
+    catch (err) {
+        rethrowIfTestIsolationError(err);
         /* fire-and-forget */
     }
 }
-/**
- * Resolve an asset path via the FTS5 index only. Spec §6.2's primary path.
- *
- * Returns `undefined` if the index has no matching row.
- */
-async function resolvePathViaIndex(parsed) {
-    const entry = await lookup(parsed);
-    if (entry) {
-        return { assetPath: entry.filePath };
-    }
-    return undefined;
-}
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseAssetRef(input.ref);
@@ -251,10 +280,11 @@ export async function showLocal(input) {
         }
     }
     if (!assetPath) {
-        const resolved = await resolvePathViaIndex(parsed);
-        if (resolved?.assetPath) {
-            assetPath = resolved.assetPath;
-        }
+        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}`;
@@ -293,8 +323,24 @@ 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 (err) {
+                rethrowIfTestIsolationError(err);
+                return { total: 0, hits: [] };
+            }
+            finally {
+                if (db)
+                    closeDatabase(db);
+            }
+        })(),
     };
-    const activeRun = getActiveWorkflowRun(getCurrentWorkflowScopeKey());
+    const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
@@ -354,7 +400,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 = {
@@ -371,3 +417,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,9 +1,11 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 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";
 import { upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
@@ -11,7 +13,6 @@ import { detectStashRoot } from "../sources/providers/provider-utils";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../sources/website-ingest";
 import { ensureWikiNameAvailable, validateWikiName } from "../wiki/wiki";
-import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
     const ref = input.ref.trim();
@@ -38,16 +39,13 @@ export async function akmAdd(input) {
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
-            if (input.trustThisInstall) {
-                warn("--trust has no effect on local directory sources; the install audit is not run for local paths.");
-            }
             return addLocalSource(ref, parsed.sourcePath, stashDir, wikiName, input.name);
         }
     }
     catch {
         // Not a local ref — fall through to registry install
     }
-    return addRegistryStash(ref, stashDir, input.trustThisInstall, input.writable, wikiName);
+    return addRegistryStash(ref, stashDir, input.writable, wikiName);
 }
 export async function registerWikiSource(input) {
     const stashDir = resolveStashDir();
@@ -59,7 +57,6 @@ export async function registerWikiSource(input) {
         name,
         overrideType: "wiki",
         options: input.options,
-        trustThisInstall: input.trustThisInstall,
         writable: input.writable,
     });
 }
@@ -74,7 +71,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 +82,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 +96,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 +113,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 +128,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 +139,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 +152,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 +169,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: {
@@ -186,38 +183,14 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
 }
 /**
  * Install a stash from a registry (npm, github, git) by dispatching to the
- * matching syncable provider, then running the post-sync install audit and
- * persisting the lock entry.
+ * matching syncable provider and persisting the lock entry.
  */
-async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiName) {
+async function addRegistryStash(ref, stashDir, writable, wikiName) {
     const parsedRef = parseRegistryRef(ref);
     if (writable === true && parsedRef.source !== "git") {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
-    // Pre-sync registry-policy enforcement uses just the parsed ref (no fetch needed),
-    // so we keep parity with the historical behavior where `enforceRegistryInstallPolicy`
-    // ran before `extractTarGzSecure` etc.
-    const config = loadConfig();
-    const synced = await syncFromRef(ref, { trustThisInstall, writable });
-    const registryLabels = deriveRegistryLabels({
-        source: synced.source,
-        ref: synced.ref,
-        artifactUrl: synced.artifactUrl,
-    });
-    enforceRegistryInstallPolicy(registryLabels, config, ref);
-    // Post-sync hook: install audit. Throws when blocked unless `--trust` is set
-    // (in which case the audit report still surfaces in the response).
-    const audit = auditInstallCandidate({
-        rootDir: synced.extractedDir,
-        source: synced.source,
-        ref: synced.ref,
-        registryLabels,
-        config,
-        trustThisInstall,
-    });
-    if (audit.blocked) {
-        throw new Error(formatInstallAuditFailure(synced.ref, audit));
-    }
+    const synced = await syncFromRef(ref, { writable });
     const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === synced.id);
     const updatedConfig = upsertInstalledRegistryEntry({
         id: synced.id,
@@ -265,10 +238,9 @@ async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiN
             cacheDir: synced.cacheDir,
             extractedDir: synced.extractedDir,
             installedAt: synced.syncedAt,
-            audit,
         },
         config: {
-            sourceCount: (updatedConfig.sources ?? updatedConfig.stashes ?? []).length,
+            sourceCount: getSources(updatedConfig).length,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {

package/dist/commands/source-clone.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
 import { makeAssetRef, parseAssetRef } from "../core/asset-ref";

package/dist/commands/source-manage.js

@@ -1,5 +1,9 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 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 +23,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 +52,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 +61,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 +79,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 +88,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 };
 }