akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/read/show.js

@@ -18,23 +18,28 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { findCittyTopLevelCommandIndex } from "../../cli/parse-args.js";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
+import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { findEntryIdByRef } from "../../indexer/db/db.js";
-import { ensureIndex } from "../../indexer/ensure-index.js";
+import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
+import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
+import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookup } from "../../indexer/indexer.js";
+import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { resolveStorageLocations } from "../../storage/locations.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -142,10 +147,8 @@ export async function akmShowUnified(input) {
         }
     }
     // Auto-index when stale so the index is current before lookup.
-    const allSources = resolveSourceEntries();
-    if (allSources.length > 0) {
-        await ensureIndex(allSources[0].path);
-    }
+    const { primarySource } = resolveReadSources();
+    await ensurePrimaryIndexForRead(primarySource);
     // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if --scope was supplied, the asset's
@@ -296,7 +299,7 @@ function logShowEvent(ref, eventSource = "user") {
                 entry_id: findEntryIdByRef(db, ref),
                 source: eventSource,
             });
-        });
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -360,6 +363,21 @@ export async function showLocal(input) {
     }
     const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, source?.registryId);
     const response = renderer.buildShowResponse(renderCtx);
+    // 07 P1-D: provenance-aware toolPolicy CEILING. An agent's self-declared
+    // `tools` frontmatter is honoured ONLY for the operator's own PRIMARY stash —
+    // the assets they authored. Every other source is content pulled from
+    // elsewhere and must not name its own tool grant: registry-installed packs, a
+    // configured secondary source, and even a git source the operator marked
+    // `--writable` to contribute edits upstream (writability is "can I push", not
+    // "do I trust this content to grant itself tools"). Drop the policy so dispatch
+    // falls back to the parent/default grant. Keys off primary-stash identity —
+    // `allSources[0]` is always the primary (search-source.ts) — not a
+    // name-derived registryId or the orthogonal `writable` bit. `source` undefined
+    // (unresolved path) also fails closed.
+    const isPrimaryStash = source !== undefined && source.path === allSources[0]?.path;
+    if (response.toolPolicy !== undefined && !isPrimaryStash) {
+        delete response.toolPolicy;
+    }
     const editable = isEditable(assetPath, config);
     const fullResponse = {
         ...response,
@@ -383,6 +401,15 @@ export async function showLocal(input) {
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
+    // #624-P3: opt-in inline graph extraction. Default OFF — when the flag is
+    // unset this whole block is skipped (no hasGraphData check, no LLM call), so
+    // behavior is byte-identical to today. When ON, it extracts graph data for an
+    // ungraphed asset, but ONLY when a model is configured (model-available
+    // guard) and ALWAYS bounded by a 30s timeout so `show` can never hang. Any
+    // timeout/model-unavailable/error path returns the response unchanged.
+    if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction === true) {
+        await maybeExtractGraphInline(config, sourceStashDir, assetPath);
+    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }
@@ -391,6 +418,58 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/**
+ * #624-P3 — opt-in inline graph extraction for `akm show`. Best-effort and
+ * timeout-bounded: never throws, never hangs, never mutates the response.
+ *
+ * Preconditions (caller already checked the flag): a model must be configured
+ * (model-available guard via {@link resolveIndexPassLLM}) and the asset must be
+ * ungraphed ({@link hasGraphData}). Extraction races a 30s timeout so `show`
+ * cannot block on a slow provider; any timeout/error/missing-model path is
+ * swallowed and `show` returns its already-assembled response unchanged.
+ */
+async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
+    try {
+        // Model-available guard — no provider configured ⇒ silent skip, no LLM call.
+        if (!resolveIndexPassLLM("graph", config))
+            return;
+        let alreadyGraphed = false;
+        let bodyHash;
+        try {
+            const raw = fs.readFileSync(assetPath, "utf8");
+            bodyHash = computeBodyHash(parseFrontmatter(raw).content.trim());
+        }
+        catch {
+            return; // file gone/unreadable ⇒ nothing to extract
+        }
+        withIndexDb((db) => {
+            alreadyGraphed = hasGraphData(db, sourceStashDir, assetPath);
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+        if (alreadyGraphed)
+            return;
+        // Open the db for the async extraction ourselves: `withIndexDb` is
+        // synchronous and would close the connection the instant the async fn
+        // returns its Promise (before extraction completes). Close it explicitly
+        // after the race settles instead.
+        const db = openExistingDatabase(resolveStorageLocations().indexDb);
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, 30_000);
+        });
+        try {
+            await Promise.race([extractGraphForSingleFile(db, sourceStashDir, assetPath, bodyHash, { config }), timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            closeDatabase(db);
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // Any other failure: silently return the unchanged show response.
+    }
+}
 /**
  * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
  * just need the raw file (e.g. clone, write-source) and don't want the full
@@ -458,6 +537,14 @@ function buildSummaryResponse(full, assetPath) {
 }
 // ── argv normalisation ───────────────────────────────────────────────────────
 const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
+const SHOW_ARGV_TOP_LEVEL_ARGS = {
+    format: { type: "string" },
+    output: { type: "string" },
+    detail: { type: "string" },
+    shape: { type: "string" },
+    quiet: { type: "boolean", alias: "q" },
+    verbose: { type: "boolean" },
+};
 /**
  * Normalize argv so positional view-mode arguments after the asset ref
  * are rewritten into internal flags that citty can parse.
@@ -471,15 +558,20 @@ const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines
  * 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")
+    const rawArgs = argv.slice(2);
+    const commandIndex = findCittyTopLevelCommandIndex(rawArgs, SHOW_ARGV_TOP_LEVEL_ARGS);
+    if (commandIndex < 0 || rawArgs[commandIndex] !== "show")
         return argv;
-    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
+    const commandArgs = rawArgs.slice(commandIndex + 1);
+    if (commandArgs.includes("--view") ||
+        commandArgs.includes("--heading") ||
+        commandArgs.includes("--start") ||
+        commandArgs.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 prefix = [...argv.slice(0, 2), ...rawArgs.slice(0, commandIndex + 1)];
+    const rest = commandArgs;
     const globalFlags = [];
     const showArgs = [];
     for (let i = 0; i < rest.length; i++) {

package/dist/commands/registry-cli.js

@@ -3,27 +3,24 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineCommand } from "citty";
 import { parsePositiveIntFlag } from "../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../cli/shared.js";
+import { defineJsonCommand, output } from "../cli/shared.js";
 import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
-import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context.js";
 import { buildRegistryIndex, writeRegistryIndex } from "../registry/build-index.js";
 import { searchRegistry } from "./read/registry-search.js";
 export const registryCommand = defineCommand({
     meta: { name: "registry", description: "Manage stash registries" },
     subCommands: {
-        list: defineCommand({
+        list: defineJsonCommand({
             meta: { name: "list", description: "List configured registries" },
-            run() {
-                return runWithJsonErrors(() => {
-                    const config = loadUserConfig();
-                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
-                    output("registry-list", { registries });
-                });
+            async run() {
+                const config = loadUserConfig();
+                const registries = config.registries ?? DEFAULT_CONFIG.registries;
+                output("registry-list", { registries });
             },
         }),
-        add: defineCommand({
+        add: defineJsonCommand({
             meta: { name: "add", description: "Add a registry by URL" },
             args: {
                 url: { type: "positional", description: "Registry index URL", required: true },
@@ -36,75 +33,71 @@ export const registryCommand = defineCommand({
                     default: false,
                 },
             },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    if (!args.url.startsWith("http")) {
-                        throw new UsageError("Registry URL must start with http:// or https://");
-                    }
-                    if (args.url.startsWith("http://")) {
-                        const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
-                        if (!allowInsecure) {
-                            throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
-                                "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
-                        }
-                        warn("Warning: registry URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious index.");
+            async run({ args }) {
+                if (!args.url.startsWith("http")) {
+                    throw new UsageError("Registry URL must start with http:// or https://");
+                }
+                if (args.url.startsWith("http://")) {
+                    const allowInsecure = args["allow-insecure"];
+                    if (!allowInsecure) {
+                        throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
+                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
                     }
-                    const config = loadUserConfig();
-                    const registries = [...(config.registries ?? [])];
-                    // Deduplicate by URL
-                    if (registries.some((r) => r.url === args.url)) {
-                        output("registry-add", { registries, added: false, message: "Registry URL already configured" });
-                        return;
+                    warn("Warning: registry URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious index.");
+                }
+                const config = loadUserConfig();
+                const registries = [...(config.registries ?? [])];
+                // Deduplicate by URL
+                if (registries.some((r) => r.url === args.url)) {
+                    output("registry-add", { registries, added: false, message: "Registry URL already configured" });
+                    return;
+                }
+                const entry = { url: args.url };
+                if (args.name)
+                    entry.name = args.name;
+                if (args.provider)
+                    entry.provider = args.provider;
+                if (args.options) {
+                    try {
+                        entry.options = JSON.parse(args.options);
                     }
-                    const entry = { url: args.url };
-                    if (args.name)
-                        entry.name = args.name;
-                    if (args.provider)
-                        entry.provider = args.provider;
-                    if (args.options) {
-                        try {
-                            entry.options = JSON.parse(args.options);
-                        }
-                        catch {
-                            throw new UsageError("--options must be valid JSON");
-                        }
+                    catch {
+                        throw new UsageError("--options must be valid JSON");
                     }
-                    registries.push(entry);
-                    saveConfig({ ...config, registries });
-                    output("registry-add", { registries, added: true });
-                });
+                }
+                registries.push(entry);
+                saveConfig({ ...config, registries });
+                output("registry-add", { registries, added: true });
             },
         }),
-        remove: defineCommand({
+        remove: defineJsonCommand({
             meta: { name: "remove", description: "Remove a registry by URL or name" },
             args: {
                 target: { type: "positional", description: "Registry URL or name to remove", required: true },
                 yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
             },
-            run({ args }) {
-                return runWithJsonErrors(async () => {
-                    const config = loadUserConfig();
-                    const registries = [...(config.registries ?? [])];
-                    const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
-                    if (idx === -1) {
-                        output("registry-remove", { registries, removed: false, message: "No matching registry found" });
-                        return;
-                    }
-                    const { confirmDestructive } = await import("../cli/confirm.js");
-                    const confirmed = await confirmDestructive(`Remove registry "${args.target}"? This cannot be undone.`, {
-                        yes: args.yes === true,
-                    });
-                    if (!confirmed) {
-                        process.stderr.write("Aborted.\n");
-                        return;
-                    }
-                    const removed = registries.splice(idx, 1)[0];
-                    saveConfig({ ...config, registries });
-                    output("registry-remove", { registries, removed: true, entry: removed });
+            async run({ args }) {
+                const config = loadUserConfig();
+                const registries = [...(config.registries ?? [])];
+                const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
+                if (idx === -1) {
+                    output("registry-remove", { registries, removed: false, message: "No matching registry found" });
+                    return;
+                }
+                const { confirmDestructive } = await import("../cli/confirm.js");
+                const confirmed = await confirmDestructive(`Remove registry "${args.target}"? This cannot be undone.`, {
+                    yes: args.yes === true,
                 });
+                if (!confirmed) {
+                    process.stderr.write("Aborted.\n");
+                    return;
+                }
+                const removed = registries.splice(idx, 1)[0];
+                saveConfig({ ...config, registries });
+                output("registry-remove", { registries, removed: true, entry: removed });
             },
         }),
-        search: defineCommand({
+        search: defineJsonCommand({
             meta: { name: "search", description: "Search enabled registries for stashes" },
             args: {
                 query: { type: "positional", description: "Search query", required: true },
@@ -112,14 +105,12 @@ export const registryCommand = defineCommand({
                 assets: { type: "boolean", description: "Include asset-level search results", default: false },
             },
             async run({ args }) {
-                await runWithJsonErrors(async () => {
-                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
-                    const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
-                    output("registry-search", result);
-                });
+                const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+                const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
+                output("registry-search", result);
             },
         }),
-        "build-index": defineCommand({
+        "build-index": defineJsonCommand({
             meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
             args: {
                 out: { type: "string", description: "Output path for the generated index" },
@@ -128,21 +119,19 @@ export const registryCommand = defineCommand({
                 "github-api": { type: "string", description: "Override GitHub API base URL" },
             },
             async run({ args }) {
-                await runWithJsonErrors(async () => {
-                    const result = await buildRegistryIndex({
-                        manualEntriesPath: args.manual,
-                        npmRegistryBase: getHyphenatedArg(args, "npm-registry"),
-                        githubApiBase: getHyphenatedArg(args, "github-api"),
-                    });
-                    const outPath = writeRegistryIndex(result.index, args.out);
-                    output("registry-build-index", {
-                        outPath,
-                        version: result.index.version,
-                        updatedAt: result.index.updatedAt,
-                        totalKits: result.counts.total,
-                        counts: result.counts,
-                        manualEntriesPath: result.paths.manualEntriesPath,
-                    });
+                const result = await buildRegistryIndex({
+                    manualEntriesPath: args.manual,
+                    npmRegistryBase: args["npm-registry"],
+                    githubApiBase: args["github-api"],
+                });
+                const outPath = writeRegistryIndex(result.index, args.out);
+                output("registry-build-index", {
+                    outPath,
+                    version: result.index.version,
+                    updatedAt: result.index.updatedAt,
+                    totalKits: result.counts.total,
+                    counts: result.counts,
+                    manualEntriesPath: result.paths.manualEntriesPath,
                 });
             },
         }),

package/dist/commands/remember.js

@@ -12,25 +12,24 @@ import { serializeFrontmatter } from "../core/asset/asset-serialize.js";
 import { toErrorMessage, tryReadStdinText } from "../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
+import { DURATION_UNITS, parseDuration as parseDurationSpec } from "../core/time.js";
 import { warn } from "../core/warn.js";
 import { SCOPE_KEYS } from "../indexer/passes/metadata.js";
 import { parseFlagValue } from "../output/context.js";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
- * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
+ * Supports the CLI-wide canonical grammar: `30d` (days), `12h` (hours),
+ * `5m` (minutes), `3M` (months, approximated as 30d).
  */
 export function parseDuration(s) {
-    const match = s.trim().match(/^(\d+)([dhm])$/i);
-    if (!match)
-        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, or 6m.`, "INVALID_FLAG_VALUE");
-    const n = Number(match[1]);
-    const unit = match[2].toLowerCase();
-    if (unit === "d")
-        return n * 24 * 60 * 60 * 1000;
-    if (unit === "h")
-        return n * 60 * 60 * 1000;
-    // 'm' = months, approximated as 30 days
-    return n * 30 * 24 * 60 * 60 * 1000;
+    // Canonical CLI unit grammar: `m` = minutes, `M` = months. Not lower-cased,
+    // so case distinguishes the two (`5m` = 5 minutes, `5M` = 5 months). See
+    // core/time.ts DURATION_UNITS.
+    const ms = parseDurationSpec(s.trim(), DURATION_UNITS);
+    if (ms === null) {
+        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, 5m, or 3M.`, "INVALID_FLAG_VALUE");
+    }
+    return ms;
 }
 /**
  * Build a YAML frontmatter block from memory metadata.