akm-cli 0.7.5 → 0.8.0-rc.10

package/dist/commands/add-cli.js

@@ -0,0 +1,279 @@
+// 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";
+import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
+import { warn } from "../core/warn";
+import { getHyphenatedBoolean } from "../output/context";
+import { akmRemove } from "./installed-stashes";
+import { akmAdd } from "./source-add";
+import { addStash } from "./source-manage";
+// ── 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;
+    }
+}
+// ── 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 vault 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");
+                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 vault key audit ────────────────────────────────────────
+            // Resolve the stash root from the install result and scan any vault 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.
+            try {
+                const installedStashRoot = result.installed?.stashRoot ??
+                    (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+                if (installedStashRoot) {
+                    const { checkVaultForDangerousKeys } = await import("./lint/env-key-rules.js");
+                    // Collect all dangerous-key findings across every env file (env/, and
+                    // the deprecated vaults/) in the freshly-installed stash.
+                    const allFindings = [];
+                    for (const [subdir, prefix] of [
+                        ["env", "env"],
+                        ["vaults", "vault"],
+                    ]) {
+                        const dir = path.join(installedStashRoot, subdir);
+                        if (!fs.existsSync(dir))
+                            continue;
+                        const envFiles = 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 = checkVaultForDangerousKeys(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 });
+                            }
+                        }
+                    }
+                    if (allFindings.length > 0) {
+                        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 vault run\`. Proceeding because --allow-insecure was set.`);
+                            }
+                        }
+                        else if (process.stdin.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] Vault "${vaultRef}" in stash "${stashLabel}" contains potentially dangerous keys:`);
+                                for (const key of keys) {
+                                    warn(`  - ${key}: can hijack process execution via \`akm vault run\``);
+                                }
+                            }
+                            const confirmed = await p.confirm({
+                                message: "Install anyway?",
+                                initialValue: false,
+                            });
+                            if (p.isCancel(confirmed) || confirmed !== true) {
+                                // Roll back the install before aborting.
+                                // 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;
+                                let rollbackWarning;
+                                try {
+                                    await akmRemove({ target: rollbackTarget });
+                                }
+                                catch (_rollbackErr) {
+                                    rollbackWarning =
+                                        `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                            `Remove it manually with: akm remove ${rollbackTarget}`;
+                                }
+                                console.error(JSON.stringify({
+                                    ok: false,
+                                    error: "Install aborted: stash contains dangerous vault keys. Remove the keys or re-run with --allow-insecure to bypass.",
+                                    code: "DANGEROUS_VAULT_KEY",
+                                    ...(rollbackWarning ? { rollbackWarning } : {}),
+                                }, null, 2));
+                                process.exit(1);
+                            }
+                        }
+                        else {
+                            // Non-interactive path without bypass flag: fail hard.
+                            // Roll back the install before exiting.
+                            // 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;
+                            let rollbackWarning;
+                            try {
+                                await akmRemove({ target: rollbackTarget });
+                            }
+                            catch (_rollbackErr) {
+                                rollbackWarning =
+                                    `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                        `Remove it manually with: akm remove ${rollbackTarget}`;
+                            }
+                            const keyList = allFindings.map((f) => `  - ${f.keyName} (${f.vaultRef})`).join("\n");
+                            console.error(JSON.stringify({
+                                ok: false,
+                                error: `Install blocked: stash "${ref}" contains dangerous vault keys that can hijack process execution via \`akm vault run\`:\n${keyList}\nRe-run with --allow-insecure to bypass this check after reviewing the vault.`,
+                                code: "DANGEROUS_VAULT_KEY",
+                                ...(rollbackWarning ? { rollbackWarning } : {}),
+                            }, null, 2));
+                            process.exit(1);
+                        }
+                    }
+                }
+            }
+            catch (auditErr) {
+                // Only swallow errors that are NOT our intentional process.exit calls.
+                if (auditErr instanceof Error && auditErr.message === "process.exit called")
+                    throw auditErr;
+                // Vault key audit is best-effort; never fail the install on unexpected audit errors.
+            }
+            output("add", result);
+        });
+    },
+});

package/dist/commands/agent-dispatch.js

@@ -0,0 +1,110 @@
+// 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 agent <profile> [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]`
+ *
+ * Dispatch an agent by named profile, optionally injecting a prompt from
+ * inline text, a stash command: asset, or a stash workflow: asset.
+ *
+ * When none of --prompt, --command, or --workflow are given, the agent is
+ * launched interactively (no injected prompt).
+ *
+ * Template placeholders (`{{0}}`, `{{1}}`, ...) in the loaded asset body are
+ * filled from the extra positional args in order.
+ */
+import fs from "node:fs";
+import { parseAssetRef } from "../core/asset-ref";
+import { NotFoundError, UsageError } from "../core/errors";
+import { requireAgentProfile } from "../integrations/agent/config";
+import { runAgentSdk } from "../integrations/agent/sdk-runner";
+import { runAgent } from "../integrations/agent/spawn";
+/**
+ * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
+ * corresponding entries in `args`. Any placeholder index that exceeds the
+ * args array is left as-is.
+ */
+function fillPlaceholders(template, args) {
+    return template.replace(/\{\{(\d+)\}\}/g, (match, idx) => {
+        const i = Number.parseInt(idx, 10);
+        return i < args.length ? args[i] : match;
+    });
+}
+/**
+ * Resolve the body of an asset by ref string. The ref must parse as a
+ * valid asset ref (e.g. `command:my-cmd`, `workflow:my-flow`). The file
+ * must exist on disk (the index provides the file path).
+ *
+ * Throws `NotFoundError` when the ref cannot be resolved.
+ */
+async function resolveAssetBody(ref) {
+    let parsed;
+    try {
+        parsed = parseAssetRef(ref);
+    }
+    catch (err) {
+        throw new UsageError(`Invalid asset ref "${ref}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");
+    }
+    // Lazy import to avoid pulling the full indexer at startup.
+    const { lookup } = await import("../indexer/indexer.js");
+    const entry = await lookup(parsed);
+    if (!entry) {
+        throw new NotFoundError(`Asset "${ref}" not found in the index. Run \`akm index\` to rebuild the index.`);
+    }
+    try {
+        return fs.readFileSync(entry.filePath, "utf8");
+    }
+    catch (err) {
+        throw new NotFoundError(`Asset "${ref}" is indexed but the file could not be read (${entry.filePath}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function akmAgentDispatch(options) {
+    if (!options.profileName?.trim()) {
+        throw new UsageError("agent: <profile> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    // Resolve the profile — throws ConfigError with an actionable hint when
+    // agent config is absent or the profile is not found.
+    const profile = requireAgentProfile(options.agentConfig, options.profileName.trim());
+    // Resolve the prompt text from whichever source was provided.
+    let prompt;
+    if (options.commandRef) {
+        const body = await resolveAssetBody(options.commandRef);
+        prompt = options.args?.length ? fillPlaceholders(body, options.args) : body;
+    }
+    else if (options.workflowRef) {
+        const body = await resolveAssetBody(options.workflowRef);
+        prompt = options.args?.length ? fillPlaceholders(body, options.args) : body;
+    }
+    else if (options.prompt !== undefined) {
+        prompt = options.prompt;
+    }
+    // When prompt is undefined, the agent is launched interactively.
+    const stdio = prompt === undefined && profile.sdkMode !== true ? "interactive" : profile.stdio;
+    // Build the final dispatch request: merge the caller-supplied dispatch with
+    // the resolved prompt so the builder has all context in one place.
+    const dispatchRequest = options.dispatch
+        ? { ...options.dispatch, prompt: prompt ?? options.dispatch.prompt }
+        : undefined;
+    const runOptions = {
+        stdio,
+        parseOutput: "text",
+        ...(options.args?.length && !options.commandRef && !options.workflowRef ? { args: options.args } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
+    };
+    const result = profile.sdkMode
+        ? await runAgentSdk(profile, prompt ?? "", runOptions, options.llmConfig)
+        : await runAgent(profile, prompt, runOptions);
+    return {
+        schemaVersion: 1,
+        ok: result.ok,
+        shape: "agent-result",
+        profileName: profile.name,
+        exitCode: result.exitCode,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        durationMs: result.durationMs,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+        ...(result.reason !== undefined ? { reason: result.reason } : {}),
+    };
+}

package/dist/commands/agent-support.js

@@ -0,0 +1,68 @@
+// 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/.
+/**
+ * Shared helpers for agent-based commands (reflect, propose, etc.).
+ *
+ * Consolidates utility functions that were duplicated byte-for-byte across
+ * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
+ * profile can import from here rather than copy-pasting.
+ */
+import { loadConfig } from "../core/config";
+import { requireAgentProfile, } from "../integrations/agent";
+// ── Config helpers ───────────────────────────────────────────────────────────
+/**
+ * Load the loaded AkmConfig from disk.
+ *
+ * After 0.8.0, the legacy `agent` top-level block was removed — the agent
+ * profile data now lives on the unified `AkmConfig` (via `profiles.agent` and
+ * `defaults.agent`). This helper remains for source-compat with callers that
+ * still expect an "AgentConfig"; it now returns the loaded `AkmConfig`.
+ */
+export function loadAgentConfigFromDisk() {
+    return loadConfig();
+}
+/**
+ * Resolve the agent profile for a command's options.
+ * Prefers an injected `agentProfile` (test seam) over the on-disk config.
+ */
+export function resolveAgentProfile(options) {
+    if (options.agentProfile)
+        return options.agentProfile;
+    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+    return requireAgentProfile(agent, options.profile);
+}
+// ── Failure helpers ──────────────────────────────────────────────────────────
+/**
+ * Base failure envelope shared by all agent command failures.
+ * Each command returns its own typed failure shape — this helper builds the
+ * common fields so per-command wrappers only need to add their own fields.
+ */
+export function baseFailureFields(result, fallbackReason = "non_zero_exit") {
+    const reason = result.reason ?? fallbackReason;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        reason,
+        error: result.error ?? `agent failure (${reason})`,
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+// ── ENOENT hint ──────────────────────────────────────────────────────────────
+/**
+ * Return `true` when a failed agent result looks like the binary was not found
+ * on PATH. Used to surface a better error message pointing the user at
+ * `akm setup`.
+ */
+export function isEnoentFailure(result) {
+    return (result.reason === "spawn_failed" &&
+        (!!result.error?.includes("ENOENT") || !!result.error?.toLowerCase().includes("not found")));
+}
+/**
+ * Build an actionable error message for a spawn-ENOENT failure.
+ */
+export function enoentHintMessage(binName) {
+    return `The agent binary '${binName}' was not found on PATH. Run \`akm setup\` to configure an agent CLI, or install ${binName} and retry.`;
+}

package/dist/commands/completions.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 os from "node:os";
 import path from "node:path";