akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/commands/{show.js → read/show.js}

@@ -18,31 +18,33 @@
  */
 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, rethrowIfTestIsolationError, UsageError } from "../core/errors";
-import { appendEvent, readEvents } from "../core/events";
-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";
+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 { 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 { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
+import { lookup } from "../../indexer/indexer.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 { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
-import "../sources/providers/index";
-import { getActiveWorkflowRun } from "../workflows/runs";
-import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
+import "../../sources/providers/index.js";
+import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
+import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
  */
 async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki } = await import("../wiki/wiki.js");
+    const { showWiki } = await import("../../wiki/wiki.js");
     const result = showWiki(stashDir, wikiName);
     return {
         type: "wiki",
@@ -58,7 +60,7 @@ async function showWikiRoot(stashDir, wikiName) {
     };
 }
 async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("../wiki/wiki.js");
+    const { showWikiAtPath } = await import("../../wiki/wiki.js");
     if (source.wikiName === wikiName) {
         const result = showWikiAtPath(wikiName, source.path);
         return {
@@ -105,6 +107,16 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
+    // 0a. Stash `.meta/` convention: `[origin//]meta[:name]` direct-reads a
+    //     human-authored orientation doc from the stash's `.meta/` directory.
+    //     These files are not indexed (the walker skips dot-dirs), so they are
+    //     resolved here before the index lookup and the `type:name` parser,
+    //     which would otherwise reject the non-asset-type `meta`.
+    {
+        const metaRef = parseMetaRef(ref);
+        if (metaRef)
+            return showStashMeta(metaRef);
+    }
     // 0. Wiki-root shortcut: `wiki:<name>` with no page path routes to the
     //    wiki summary (same payload as `akm wiki show <name>`). Honour
     //    `parsed.origin` by resolving against the matching stash source(s),
@@ -145,13 +157,49 @@ export async function akmShowUnified(input) {
     }
     // Count prior shows of this ref before logging the current one.
     const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref, undefined, input.eventSource);
+    logShowEvent(ref, input.eventSource);
     if (priorShowCount >= 2) {
         // Agent has shown this same asset 3+ times — inject a loop-break hint.
         result.showLoopWarning = priorShowCount + 1;
     }
     return result;
 }
+/**
+ * Resolve a stash `.meta/` doc and return it as a lightweight ShowResponse.
+ *
+ * With no origin the working stash (and other configured sources, in order)
+ * is searched and the first hit wins. With an origin the lookup is narrowed
+ * to that stash; an uninstalled origin yields an actionable "not installed"
+ * error. The file is read directly from disk — `.meta/` is never indexed.
+ */
+async function showStashMeta(metaRef) {
+    const allSources = resolveSourceEntries();
+    const sources = resolveSourcesForOrigin(metaRef.origin, allSources);
+    if (metaRef.origin && sources.length === 0) {
+        throw new NotFoundError(`Stash "${metaRef.origin}" is not installed, so its ${META_DIR}/ docs are unavailable. ` +
+            `Run: akm add ${metaRef.origin}`);
+    }
+    const config = loadConfig();
+    for (const source of sources) {
+        const filePath = resolveMetaFilePath(source.path, metaRef.name);
+        if (!filePath)
+            continue;
+        const content = fs.readFileSync(filePath, "utf8");
+        const editable = isEditable(filePath, config);
+        appendEvent({ eventType: "show", ref: `meta:${metaRef.name}`, metadata: { type: "meta", name: metaRef.name } });
+        return {
+            type: "meta",
+            name: metaRef.name,
+            path: filePath,
+            content,
+            origin: source.registryId ?? null,
+            editable,
+        };
+    }
+    throw new NotFoundError(`No ${META_DIR}/${metaRef.name} doc found${metaRef.origin ? ` in "${metaRef.origin}"` : ""}. ` +
+        `Stash maintainers can create ${META_DIR}/${metaRef.name}.md to describe this stash ` +
+        `(purpose, key assets, conventions, maintainer).`);
+}
 function hasAnyScopeKey(scope) {
     return Boolean(scope.user || scope.agent || scope.run || scope.channel);
 }
@@ -206,7 +254,7 @@ function recentShowCount(ref) {
         return 0;
     }
 }
-function logShowEvent(ref, existingDb, eventSource = "user") {
+function logShowEvent(ref, 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);
@@ -241,19 +289,14 @@ function logShowEvent(ref, existingDb, eventSource = "user") {
         /* fire-and-forget — select is best-effort */
     }
     try {
-        const db = existingDb ?? openExistingDatabase();
-        try {
+        withIndexDb((db) => {
             insertUsageEvent(db, {
                 event_type: "show",
                 entry_ref: ref,
                 entry_id: findEntryIdByRef(db, ref),
                 source: eventSource,
             });
-        }
-        finally {
-            if (!existingDb)
-                closeDatabase(db);
-        }
+        });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -324,20 +367,16 @@ export async function showLocal(input) {
         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 };
+                return withIndexDb((db) => {
+                    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 = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
@@ -435,8 +474,6 @@ 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"`.');
     }
@@ -447,11 +484,7 @@ export function normalizeShowArgv(argv) {
     const showArgs = [];
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
-        if (arg === "--quiet" ||
-            arg === "-q" ||
-            arg === "--verbose" ||
-            arg === "--for-agent" ||
-            arg === "--for-agent=true") {
+        if (arg === "--quiet" || arg === "-q" || arg === "--verbose") {
             globalFlags.push(arg);
             continue;
         }

package/dist/commands/registry-cli.js

@@ -2,14 +2,14 @@
 // 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 { defineCommand } from "citty";
-import { parsePositiveIntFlag } from "../cli/parse-args";
-import { output, runWithJsonErrors } from "../cli/shared";
-import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config";
-import { UsageError } from "../core/errors";
-import { warn } from "../core/warn";
-import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context";
-import { buildRegistryIndex, writeRegistryIndex } from "../registry/build-index";
-import { searchRegistry } from "./registry-search";
+import { parsePositiveIntFlag } from "../cli/parse-args.js";
+import { output, runWithJsonErrors } 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: {

package/dist/commands/remember.js

@@ -8,13 +8,13 @@
  * heuristic derivation, LLM enrichment) is testable in isolation and the
  * CLI entry point stays focused on argument parsing + output routing.
  */
-import { serializeFrontmatter } from "../core/asset-serialize";
-import { toErrorMessage, tryReadStdinText } from "../core/common";
-import { getDefaultLlmConfig, loadConfig } from "../core/config";
-import { UsageError } from "../core/errors";
-import { warn } from "../core/warn";
-import { SCOPE_KEYS } from "../indexer/metadata";
-import { parseFlagValue } from "../output/context";
+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 { 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).
@@ -148,7 +148,7 @@ export async function runLlmEnrich(body) {
         warn("Warning: --enrich requires an LLM to be configured. Run `akm setup` to configure one.");
         return { tags: [] };
     }
-    const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
+    const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client.js");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
 - "tags": array of 1-5 short lowercase keyword tags

package/dist/commands/sources/add-cli.js

@@ -0,0 +1,293 @@
+// 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 * as p from "@clack/prompts";
+import { defineCommand } from "citty";
+import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { warn } from "../../core/warn.js";
+import { getHyphenatedBoolean } from "../../output/context.js";
+import { akmRemove } from "./installed-stashes.js";
+import { akmAdd } from "./source-add.js";
+import { addStash } from "./source-manage.js";
+// ── Shared website-options helper (also used by wikiRegisterCommand) ──────────
+export function buildWebsiteOptions(args) {
+    const websiteOptions = {};
+    if (typeof args["max-pages"] === "string" && args["max-pages"].length > 0)
+        websiteOptions.maxPages = args["max-pages"];
+    if (typeof args["max-depth"] === "string" && args["max-depth"].length > 0)
+        websiteOptions.maxDepth = args["max-depth"];
+    return websiteOptions;
+}
+// ── HTTP safety check ─────────────────────────────────────────────────────────
+export function shouldWarnOnPlainHttp(ref) {
+    if (!ref.startsWith("http://"))
+        return false;
+    try {
+        const hostname = new URL(ref).hostname.toLowerCase();
+        return (hostname !== "localhost" &&
+            hostname !== "127.0.0.1" &&
+            hostname !== "0.0.0.0" &&
+            hostname !== "::1" &&
+            hostname !== "[::1]" &&
+            !hostname.endsWith(".localhost"));
+    }
+    catch {
+        return true;
+    }
+}
+/** Scan every env file in the freshly-installed stash for dangerous env keys. */
+function collectDangerousKeyFindings(installedStashRoot, checkEnvForDangerousKeys) {
+    const allFindings = [];
+    const subdir = "env";
+    const prefix = "env";
+    const dir = path.join(installedStashRoot, subdir);
+    const envFiles = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".env")) : [];
+    for (const envFile of envFiles) {
+        const envPath = path.join(dir, envFile);
+        const baseName = path.basename(envFile, ".env");
+        const vaultRef = baseName === "" ? `${prefix}:default` : `${prefix}:${baseName}`;
+        const relPath = path.join(subdir, envFile);
+        const findings = checkEnvForDangerousKeys(envPath, relPath, vaultRef);
+        for (const finding of findings) {
+            // Extract the key name from the detail string for the summary line.
+            const keyMatch = finding.detail.match(/Env key `([^`]+)`/);
+            const keyName = keyMatch ? keyMatch[1] : finding.file;
+            allFindings.push({ vaultRef, keyName, relPath });
+        }
+    }
+    return allFindings;
+}
+/**
+ * Audit a freshly-installed stash for dangerous env keys and decide whether the
+ * install must be blocked. Returns a typed decision instead of calling
+ * `process.exit`, so the abort cannot be lost to a swallowed exception. See the
+ * block comment above for the security rationale.
+ */
+export async function auditInstalledStashForDangerousKeys(opts) {
+    const { installedStashRoot, ref, allowDangerousKeys, rollbackTarget, isTTY } = opts;
+    // Best-effort scan: if collecting findings itself throws (corrupt env file,
+    // fs error) there is nothing concrete to block on, so fail soft. Crucially,
+    // this soft path runs BEFORE any findings exist — it can never re-open an
+    // already-detected dangerous install.
+    let allFindings;
+    try {
+        const { checkEnvForDangerousKeys } = await import("../lint/env-key-rules.js");
+        allFindings = collectDangerousKeyFindings(installedStashRoot, checkEnvForDangerousKeys);
+    }
+    catch {
+        return { blocked: false };
+    }
+    if (allFindings.length === 0)
+        return { blocked: false };
+    if (allowDangerousKeys) {
+        // Operator has explicitly accepted the risk — warn and continue.
+        for (const f of allFindings) {
+            warn(`[dangerous-vault-key] ${f.relPath}: key \`${f.keyName}\` in ${f.vaultRef} can hijack process execution via \`akm env run\`. Proceeding because --allow-insecure was set.`);
+        }
+        return { blocked: false };
+    }
+    // Helper: roll the install back before aborting. Rollback is best-effort; a
+    // failed rollback never UN-blocks the install — we still abort, just with a
+    // warning telling the operator to remove the stash manually.
+    async function rollback() {
+        try {
+            await akmRemove({ target: rollbackTarget });
+            return undefined;
+        }
+        catch (_rollbackErr) {
+            return (`Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                `Remove it manually with: akm remove ${rollbackTarget}`);
+        }
+    }
+    if (isTTY) {
+        // Interactive path: show findings and ask the user to confirm.
+        // Guard on stdin (not stdout) because p.confirm() reads from stdin;
+        // stdout may be a TTY while stdin is piped, which would cause a hang.
+        const stashLabel = ref;
+        const groupedByVault = new Map();
+        for (const f of allFindings) {
+            const existing = groupedByVault.get(f.vaultRef) ?? [];
+            existing.push(f.keyName);
+            groupedByVault.set(f.vaultRef, existing);
+        }
+        for (const [vaultRef, keys] of groupedByVault) {
+            warn(`[warn] Env "${vaultRef}" in stash "${stashLabel}" contains potentially dangerous keys:`);
+            for (const key of keys) {
+                warn(`  - ${key}: can hijack process execution via \`akm env run\``);
+            }
+        }
+        const confirmed = await p.confirm({
+            message: "Install anyway?",
+            initialValue: false,
+        });
+        if (p.isCancel(confirmed) || confirmed !== true) {
+            const rollbackWarning = await rollback();
+            console.error(JSON.stringify({
+                ok: false,
+                error: "Install aborted: stash contains dangerous env keys. Remove the keys or re-run with --allow-insecure to bypass.",
+                code: "DANGEROUS_VAULT_KEY",
+                ...(rollbackWarning ? { rollbackWarning } : {}),
+            }, null, 2));
+            return { blocked: true, exitCode: 1 };
+        }
+        // Operator confirmed at the prompt — allow the install to proceed.
+        return { blocked: false };
+    }
+    // Non-interactive path without bypass flag: fail hard.
+    const rollbackWarning = await rollback();
+    const keyList = allFindings.map((f) => `  - ${f.keyName} (${f.vaultRef})`).join("\n");
+    console.error(JSON.stringify({
+        ok: false,
+        error: `Install blocked: stash "${ref}" contains dangerous env keys that can hijack process execution via \`akm env run\`:\n${keyList}\nRe-run with --allow-insecure to bypass this check after reviewing the env file.`,
+        code: "DANGEROUS_VAULT_KEY",
+        ...(rollbackWarning ? { rollbackWarning } : {}),
+    }, null, 2));
+    return { blocked: true, exitCode: 1 };
+}
+// ── Command definition ────────────────────────────────────────────────────────
+export const addCommand = defineCommand({
+    meta: {
+        name: "add",
+        description: "Add a source (local directory, website, npm package, GitHub repo, git URL, or remote provider)",
+    },
+    args: {
+        ref: {
+            type: "positional",
+            description: "Path, URL, or registry ref (website URL, npm package, owner/repo, git URL, or local directory)",
+            required: true,
+        },
+        provider: { type: "string", description: "Provider type (e.g. website, npm). Required for URL sources." },
+        options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
+        name: { type: "string", description: "Human-friendly name for the source" },
+        writable: {
+            type: "boolean",
+            description: "Mark a git stash as writable so changes can be pushed back",
+            default: false,
+        },
+        type: {
+            type: "string",
+            description: "Override asset type for all files in this stash (currently supports: wiki)",
+        },
+        "max-pages": { type: "string", description: "Maximum pages to crawl for website sources (default: 50)" },
+        "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
+        "allow-insecure": {
+            type: "boolean",
+            description: "Allow a plain HTTP source URL and skip confirmation for dangerous env keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the stash.",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const ref = args.ref.trim();
+            const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
+            const allowDangerousKeys = allowInsecure;
+            // URL with --provider → stash source (remote or git provider)
+            if (args.provider) {
+                if (shouldWarnOnPlainHttp(ref)) {
+                    if (!allowInsecure) {
+                        throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+                    }
+                    warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
+                }
+                let parsedOptions;
+                if (args.options) {
+                    try {
+                        const parsed = JSON.parse(args.options);
+                        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                            throw new UsageError("--options must be a JSON object");
+                        }
+                        parsedOptions = parsed;
+                    }
+                    catch (err) {
+                        if (err instanceof UsageError)
+                            throw err;
+                        throw new UsageError("--options must be valid JSON");
+                    }
+                }
+                const result = addStash({
+                    target: ref,
+                    name: args.name,
+                    providerType: args.provider,
+                    options: parsedOptions,
+                    writable: args.writable,
+                });
+                appendEvent({
+                    eventType: "add",
+                    metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
+                });
+                output("add", result);
+                return;
+            }
+            if (shouldWarnOnPlainHttp(ref)) {
+                if (!allowInsecure) {
+                    throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                        "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+                }
+                warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
+            }
+            const websiteOptions = buildWebsiteOptions(args);
+            if (args.type === "wiki") {
+                const { registerWikiSource } = await import("./source-add.js");
+                const result = await registerWikiSource({
+                    ref,
+                    name: args.name,
+                    options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+                    writable: args.writable,
+                });
+                appendEvent({
+                    eventType: "add",
+                    metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
+                });
+                output("add", result);
+                return;
+            }
+            const result = await akmAdd({
+                ref,
+                name: args.name,
+                overrideType: args.type,
+                options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+                writable: args.writable,
+            });
+            appendEvent({
+                eventType: "add",
+                metadata: {
+                    target: ref,
+                    name: args.name ?? null,
+                    overrideType: args.type ?? null,
+                    writable: args.writable === true,
+                },
+            });
+            // ── Post-install env key audit ──────────────────────────────────────────
+            // Resolve the stash root from the install result and scan any env files
+            // for dangerous env var keys.  When findings are present the install is
+            // gated: TTY → interactive confirmation prompt; non-TTY without
+            // --allow-insecure → hard failure (exit 1).  Pass
+            // --allow-insecure to skip the prompt non-interactively.
+            const installedStashRoot = result.installed?.stashRoot ??
+                (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+            if (installedStashRoot) {
+                // Use the canonical installed id (most reliably resolved by akmRemove) rather
+                // than the raw user-supplied ref which may not match after URL normalisation.
+                const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+                // The audit RETURNS its decision; we decide `process.exit` here, OUTSIDE
+                // any catch, so the abort cannot be lost to a swallowed exception (C3).
+                const decision = await auditInstalledStashForDangerousKeys({
+                    installedStashRoot,
+                    ref,
+                    allowDangerousKeys,
+                    rollbackTarget,
+                    isTTY: process.stdin.isTTY === true,
+                });
+                if (decision.blocked) {
+                    process.exit(decision.exitCode);
+                }
+            }
+            output("add", result);
+        });
+    },
+});

package/dist/commands/{history.js → sources/history.js}

@@ -1,12 +1,28 @@
 // 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 { parseAssetRef } from "../core/asset-ref";
-import { UsageError } from "../core/errors";
-import { readEvents } from "../core/events";
-import { listProposals } from "../core/proposals";
-import { isoToSqlite, parseSinceToIso } from "../core/time";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
+/**
+ * `akm history` — surfaces internal mutation/usage events for a single asset
+ * (`--ref`) or stash-wide.
+ *
+ * Event sources:
+ *   - `usage_events` SQLite table: search, show, and feedback events recorded
+ *     by the local indexer during normal CLI use.
+ *   - `events.jsonl` append-only stream (opt-in via `--include-proposals`):
+ *     proposal lifecycle events (`promoted`, `rejected`) emitted by
+ *     `akm proposal accept` / `akm proposal reject`. Use this flag to see
+ *     the full proposal review trail alongside usage events.
+ *
+ * The two sources are merged and sorted chronologically (oldest first) so
+ * consumers see a coherent lifecycle trail in a single output.
+ */
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { UsageError } from "../../core/errors.js";
+import { readEvents } from "../../core/events.js";
+import { isoToSqlite, parseSinceToIso } from "../../core/time.js";
+import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { getUsageEvents } from "../../indexer/usage/usage-events.js";
+import { listProposals } from "../proposal/validators/proposals.js";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -71,25 +87,11 @@ export async function akmHistory(options = {}) {
     const db = options.db ?? openExistingDatabase();
     const ownsDb = options.db === undefined;
     try {
-        const conditions = [];
-        const params = [];
-        if (normalizedRef !== undefined) {
-            conditions.push("entry_ref = ?");
-            params.push(normalizedRef);
-        }
-        if (sinceNormalized !== undefined) {
-            conditions.push("created_at >= ?");
-            params.push(sinceNormalized);
-        }
-        if (options.source !== undefined) {
-            conditions.push("source = ?");
-            params.push(options.source);
-        }
-        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
-                 FROM usage_events ${where}
-                 ORDER BY id ASC`;
-        const rows = db.prepare(sql).all(...params);
+        const rows = getUsageEvents(db, {
+            entry_ref: normalizedRef,
+            since: sinceNormalized,
+            source: options.source,
+        });
         const usageEntries = rows.map(toEntry);
         // ── Proposal lifecycle events (opt-in) ────────────────────────────────
         const sources = ["usage_events"];

package/dist/commands/{info.js → sources/info.js}

@@ -2,12 +2,12 @@
 // 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 { getAssetTypes } from "../core/asset-spec";
-import { getSources, loadConfig } from "../core/config";
-import { getDbPath } from "../core/paths";
-import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../indexer/db";
-import { getEffectiveSemanticStatus, readSemanticStatus } from "../indexer/semantic-status";
-import { pkgVersion } from "../version";
+import { getAssetTypes } from "../../core/asset/asset-spec.js";
+import { getSources, loadConfig } from "../../core/config/config.js";
+import { getDbPath } from "../../core/paths.js";
+import { closeDatabase, getEntryCount, getMeta, isVecAvailable, openExistingDatabase } from "../../indexer/db/db.js";
+import { getEffectiveSemanticStatus, readSemanticStatus } from "../../indexer/search/semantic-status.js";
+import { pkgVersion } from "../../version.js";
 /**
  * Assemble system info describing the current capabilities, configuration,
  * and index state. Used by `akm info`.