akm-cli 0.6.1 → 0.7.0

package/dist/tests/agent/agent-spawn.test.js

@@ -0,0 +1,234 @@
+/**
+ * Tests for the agent CLI spawn wrapper (`runAgent`).
+ *
+ * Acceptance coverage:
+ *   • Captured stdio collects stdout/stderr.
+ *   • Hard timeout maps to `reason: "timeout"`.
+ *   • Non-zero exit maps to `reason: "non_zero_exit"`.
+ *   • Synchronous spawn failure maps to `reason: "spawn_failed"`.
+ *   • Malformed JSON output (when `parseOutput: "json"`) maps to
+ *     `reason: "parse_error"`.
+ *   • Successful run returns `ok: true`, captured `stdout`, parsed JSON.
+ *
+ * The wrapper takes a `spawn` injection point so we never touch real
+ * binaries here. Where we do touch a real subprocess (one fast `bun -e`
+ * timeout test) we keep the timeout small and deterministic.
+ */
+import { describe, expect, test } from "bun:test";
+import { runAgent } from "../../src/integrations/agent/spawn";
+function makeProfile(overrides = {}) {
+    return {
+        name: "test-agent",
+        bin: "test-agent",
+        args: [],
+        stdio: "captured",
+        envPassthrough: ["PATH"],
+        parseOutput: "text",
+        ...overrides,
+    };
+}
+function asReadableStream(text) {
+    const bytes = new TextEncoder().encode(text);
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+function fakeSpawnFn(config) {
+    const state = { kills: 0 };
+    const spawn = () => {
+        if (config.throwSync)
+            throw config.throwSync;
+        let resolveExit = () => { };
+        const exited = new Promise((resolve, reject) => {
+            resolveExit = resolve;
+            if (config.rejectExit) {
+                reject(config.rejectExit);
+            }
+            else if (!config.hangsUntilKilled) {
+                resolve(config.exitCode);
+            }
+        });
+        const proc = {
+            exitCode: config.hangsUntilKilled ? null : config.exitCode,
+            exited,
+            stdout: asReadableStream(config.stdout ?? ""),
+            stderr: asReadableStream(config.stderr ?? ""),
+            stdin: null,
+            kill() {
+                state.kills += 1;
+                // Simulate process exit on signal.
+                resolveExit(143);
+            },
+        };
+        return proc;
+    };
+    return { spawn, kills: 0 };
+}
+describe("runAgent — captured stdio", () => {
+    test("returns ok:true with stdout/stderr on exit 0", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 0, stdout: "hello\n", stderr: "" });
+        const result = await runAgent(makeProfile(), "go", { spawn });
+        expect(result.ok).toBe(true);
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toBe("hello\n");
+        expect(result.reason).toBeUndefined();
+        expect(typeof result.durationMs).toBe("number");
+    });
+    test("non-zero exit yields structured `non_zero_exit`", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 7, stderr: "boom" });
+        const result = await runAgent(makeProfile(), "go", { spawn });
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("non_zero_exit");
+        expect(result.exitCode).toBe(7);
+        expect(result.stderr).toBe("boom");
+        expect(result.error).toContain("exited with code 7");
+    });
+    test("synchronous spawn failure yields `spawn_failed`", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 0, throwSync: new Error("ENOENT: command not found") });
+        const result = await runAgent(makeProfile(), "go", { spawn });
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("spawn_failed");
+        expect(result.error).toContain("ENOENT");
+        expect(result.exitCode).toBeNull();
+    });
+    test("rejected proc.exited yields `spawn_failed`", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 0, rejectExit: new Error("kernel ate it") });
+        const result = await runAgent(makeProfile(), "go", { spawn });
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("spawn_failed");
+    });
+});
+describe("runAgent — timeout", () => {
+    test("kills the subprocess and reports `timeout`", async () => {
+        // Drive the timer manually so the assertion is deterministic.
+        let timerCallback;
+        const fakeSet = ((cb) => {
+            timerCallback = cb;
+            return 1;
+        });
+        const fakeClear = (() => { });
+        const { spawn } = fakeSpawnFn({ exitCode: 0, hangsUntilKilled: true });
+        const promise = runAgent(makeProfile(), "go", {
+            spawn,
+            setTimeoutFn: fakeSet,
+            clearTimeoutFn: fakeClear,
+            timeoutMs: 100,
+        });
+        // Kick the deadline.
+        expect(timerCallback).toBeDefined();
+        timerCallback?.();
+        const result = await promise;
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("timeout");
+        expect(result.error).toContain("100ms");
+    });
+    test("real timeout against `bun -e` sleeping past the deadline (deterministic & fast)", async () => {
+        const profile = makeProfile({ bin: "bun", args: ["-e", "await new Promise(r => setTimeout(r, 5000))"] });
+        const start = Date.now();
+        const result = await runAgent(profile, undefined, { timeoutMs: 250 });
+        const elapsed = Date.now() - start;
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("timeout");
+        // Should bail well before the 5-second sleep would complete.
+        expect(elapsed).toBeLessThan(2000);
+    });
+});
+describe("runAgent — JSON parse mode", () => {
+    test("parses JSON stdout and surfaces it via `parsed`", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 0, stdout: '{"role":"agent"}' });
+        const result = await runAgent(makeProfile({ parseOutput: "json" }), "go", { spawn });
+        expect(result.ok).toBe(true);
+        expect(result.parsed).toEqual({ role: "agent" });
+    });
+    test("malformed JSON yields `parse_error`", async () => {
+        const { spawn } = fakeSpawnFn({ exitCode: 0, stdout: "not json {" });
+        const result = await runAgent(makeProfile({ parseOutput: "json" }), "go", { spawn });
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("parse_error");
+        expect(result.error).toBeTruthy();
+    });
+    // ── #284 GAP-HIGH 10: parseOutput=json + non-zero exit + non-JSON stderr ──
+    test("parseOutput=json + non-zero exit: non_zero_exit precedence (parse_error suppressed)", async () => {
+        // Non-zero exit must surface as `non_zero_exit`, not `parse_error`, even
+        // when the stdout/stderr payload is malformed JSON. The exit code is the
+        // primary failure signal; parse failures are downstream of a successful run.
+        const { spawn } = fakeSpawnFn({
+            exitCode: 5,
+            stdout: "not json {",
+            stderr: "agent panic: kernel ate my JSON",
+        });
+        const result = await runAgent(makeProfile({ parseOutput: "json" }), "go", { spawn });
+        expect(result.ok).toBe(false);
+        expect(result.reason).toBe("non_zero_exit");
+        expect(result.exitCode).toBe(5);
+        expect(result.stderr).toBe("agent panic: kernel ate my JSON");
+        expect(result.parsed).toBeUndefined();
+    });
+});
+// ── #284 GAP-HIGH 11: timeoutMs precedence ────────────────────────────────
+describe("runAgent — timeoutMs precedence", () => {
+    test("options.timeoutMs overrides profile.timeoutMs", async () => {
+        // Both profile and options carry a timeoutMs. Options must win.
+        let timerCallback;
+        let observedDeadlineMs;
+        const fakeSet = ((cb, ms) => {
+            timerCallback = cb;
+            observedDeadlineMs = ms;
+            return 1;
+        });
+        const fakeClear = (() => { });
+        const { spawn } = fakeSpawnFn({ exitCode: 0, hangsUntilKilled: true });
+        const profile = makeProfile({ timeoutMs: 999_999 });
+        const promise = runAgent(profile, "go", {
+            spawn,
+            setTimeoutFn: fakeSet,
+            clearTimeoutFn: fakeClear,
+            timeoutMs: 250,
+        });
+        expect(observedDeadlineMs).toBe(250); // override won
+        timerCallback?.();
+        const result = await promise;
+        expect(result.reason).toBe("timeout");
+    });
+});
+describe("runAgent — argument and env construction", () => {
+    test("appends prompt after profile.args and options.args", async () => {
+        let capturedCmd;
+        const spawn = (cmd) => {
+            capturedCmd = cmd;
+            return {
+                exitCode: 0,
+                exited: Promise.resolve(0),
+                stdout: asReadableStream(""),
+                stderr: asReadableStream(""),
+                stdin: null,
+                kill() { },
+            };
+        };
+        await runAgent(makeProfile({ args: ["--profile-arg"] }), "the-prompt", { spawn, args: ["--call-arg"] });
+        expect(capturedCmd).toEqual(["test-agent", "--profile-arg", "--call-arg", "the-prompt"]);
+    });
+    test("env is filtered by envPassthrough plus profile/options env", async () => {
+        let capturedEnv;
+        const spawn = (_cmd, opts) => {
+            capturedEnv = opts.env;
+            return {
+                exitCode: 0,
+                exited: Promise.resolve(0),
+                stdout: asReadableStream(""),
+                stderr: asReadableStream(""),
+                stdin: null,
+                kill() { },
+            };
+        };
+        await runAgent(makeProfile({ envPassthrough: ["KEEP_ME"], env: { PROFILE_VAR: "1" } }), undefined, {
+            spawn,
+            env: { CALL_VAR: "2" },
+            envSource: { KEEP_ME: "yes", DROP_ME: "no" },
+        });
+        expect(capturedEnv).toEqual({ KEEP_ME: "yes", PROFILE_VAR: "1", CALL_VAR: "2" });
+    });
+});

package/dist/tests/agent-output.test.js

@@ -0,0 +1,186 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+function writeConfig(configDir, config) {
+    const configPath = path.join(configDir, "akm", "config.json");
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+function runCli(stashDir, args, config) {
+    const xdgCache = makeTempDir("akm-agent-cache-");
+    const xdgConfig = makeTempDir("akm-agent-config-");
+    if (config)
+        writeConfig(xdgConfig, config);
+    const result = spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        env: {
+            ...process.env,
+            AKM_STASH_DIR: stashDir,
+            XDG_CACHE_HOME: xdgCache,
+            XDG_CONFIG_HOME: xdgConfig,
+        },
+    });
+    if (result.status !== 0) {
+        throw new Error(`CLI exited ${result.status}:\n${result.stderr}`);
+    }
+    return result.stdout.trim();
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("--for-agent output mode", () => {
+    function makeStash() {
+        const stashDir = makeTempDir("akm-agent-stash-");
+        writeFile(path.join(stashDir, "agents", "architect.md"), "---\ndescription: System architecture agent\ntags: [arch, design]\n---\nYou are an architect.\n");
+        writeFile(path.join(stashDir, "scripts", "deploy.sh"), "#!/usr/bin/env bash\necho deploy\n");
+        writeFile(path.join(stashDir, "commands", "release.md"), "---\ndescription: Release process\n---\nRun release {{version}}\n");
+        return stashDir;
+    }
+    test("--for-agent search output has only: name, ref, type, description, action, score", () => {
+        const stashDir = makeStash();
+        const output = runCli(stashDir, ["search", "architect", "--format=json", "--for-agent"]);
+        const json = JSON.parse(output);
+        expect(json.hits.length).toBeGreaterThan(0);
+        const hit = json.hits[0];
+        const keys = Object.keys(hit);
+        // Must have these agent-essential fields (when present)
+        expect(keys).toContain("name");
+        expect(keys).toContain("type");
+        expect(keys).toContain("action");
+        // Only allowed keys (estimatedTokens is optional — present when fileSize is known)
+        const allowedKeys = new Set(["name", "ref", "type", "description", "action", "score", "estimatedTokens"]);
+        for (const key of keys) {
+            expect(allowedKeys.has(key)).toBe(true);
+        }
+    });
+    test("--for-agent search output does NOT have: schemaVersion, stashDir, path, whyMatched, origin, editable", () => {
+        const stashDir = makeStash();
+        const output = runCli(stashDir, ["search", "architect", "--format=json", "--for-agent"]);
+        const json = JSON.parse(output);
+        // Top-level envelope must not have these
+        expect(json).not.toHaveProperty("schemaVersion");
+        expect(json).not.toHaveProperty("stashDir");
+        expect(json).not.toHaveProperty("timing");
+        // Hits must not have these
+        const hits = json.hits;
+        for (const hit of hits) {
+            expect(hit).not.toHaveProperty("path");
+            expect(hit).not.toHaveProperty("whyMatched");
+            expect(hit).not.toHaveProperty("origin");
+            expect(hit).not.toHaveProperty("editable");
+            expect(hit).not.toHaveProperty("editHint");
+            expect(hit).not.toHaveProperty("tags");
+            expect(hit).not.toHaveProperty("size");
+        }
+    });
+    test("--for-agent show output strips non-essential fields", () => {
+        const stashDir = makeStash();
+        const output = runCli(stashDir, ["show", "command:release.md", "--format=json", "--for-agent"]);
+        const json = JSON.parse(output);
+        // Must have essential fields
+        expect(json).toHaveProperty("name");
+        expect(json).toHaveProperty("type");
+        // Must NOT have non-essential fields
+        expect(json).not.toHaveProperty("schemaVersion");
+        expect(json).not.toHaveProperty("path");
+        expect(json).not.toHaveProperty("origin");
+        expect(json).not.toHaveProperty("editable");
+        expect(json).not.toHaveProperty("editHint");
+    });
+    test("--for-agent show output keeps content/run/action", () => {
+        const stashDir = makeStash();
+        // Command has template content
+        const cmdOutput = runCli(stashDir, ["show", "command:release.md", "--format=json", "--for-agent"]);
+        const cmdJson = JSON.parse(cmdOutput);
+        expect(cmdJson).toHaveProperty("template");
+        expect(cmdJson).toHaveProperty("action");
+        // Script has run field
+        const scriptOutput = runCli(stashDir, ["show", "script:deploy.sh", "--format=json", "--for-agent"]);
+        const scriptJson = JSON.parse(scriptOutput);
+        expect(scriptJson).toHaveProperty("run");
+        expect(scriptJson).toHaveProperty("action");
+    });
+    test("standard output (without --for-agent) is unchanged", () => {
+        const stashDir = makeStash();
+        // Default brief search still has same shape
+        const searchOutput = runCli(stashDir, ["search", "architect", "--format=json"]);
+        const searchJson = JSON.parse(searchOutput);
+        // hits is always present; warnings may appear when semantic search is pending
+        expect(Object.keys(searchJson)).toContain("hits");
+        // Standard brief output includes at least name, type, action (may also include estimatedTokens etc.)
+        const hit = searchJson.hits[0] ?? {};
+        expect(hit).toHaveProperty("name");
+        expect(hit).toHaveProperty("type");
+        expect(hit).toHaveProperty("action");
+        // Default show still has origin
+        const showOutput = runCli(stashDir, ["show", "command:release.md", "--format=json"]);
+        const showJson = JSON.parse(showOutput);
+        expect(showJson).toHaveProperty("origin");
+    });
+});
+describe("--format jsonl", () => {
+    function makeStash() {
+        const stashDir = makeTempDir("akm-jsonl-stash-");
+        writeFile(path.join(stashDir, "agents", "architect.md"), "---\ndescription: System architecture agent\n---\nYou are an architect.\n");
+        writeFile(path.join(stashDir, "scripts", "deploy.sh"), "#!/usr/bin/env bash\necho deploy\n");
+        return stashDir;
+    }
+    test("JSONL format outputs one JSON object per line for search hits", () => {
+        const stashDir = makeStash();
+        // QA #14: empty query now rejects; use a real keyword that matches stash assets.
+        // Use "architect" since architect.md has that word in both name and content.
+        const output = runCli(stashDir, ["search", "architect", "--format=jsonl"]);
+        const lines = output.split("\n").filter((line) => line.trim().length > 0);
+        // Should have at least 1 hit
+        expect(lines.length).toBeGreaterThanOrEqual(1);
+        // Each line must be its own object, not wrapped in an envelope
+        for (const line of lines) {
+            const parsed = JSON.parse(line);
+            expect(typeof parsed).toBe("object");
+            expect(parsed).toHaveProperty("name");
+        }
+    });
+    test("each JSONL line is valid parseable JSON", () => {
+        const stashDir = makeStash();
+        const output = runCli(stashDir, ["search", "deploy", "--format=jsonl"]);
+        const lines = output.split("\n").filter((line) => line.trim().length > 0);
+        for (const line of lines) {
+            expect(() => JSON.parse(line)).not.toThrow();
+            const parsed = JSON.parse(line);
+            expect(typeof parsed).toBe("object");
+            expect(Array.isArray(parsed)).toBe(false);
+        }
+    });
+    test("JSONL combined with --for-agent uses agent shaping", () => {
+        const stashDir = makeStash();
+        const output = runCli(stashDir, ["search", "deploy", "--format=jsonl", "--for-agent"]);
+        const lines = output.split("\n").filter((line) => line.trim().length > 0);
+        for (const line of lines) {
+            const parsed = JSON.parse(line);
+            const allowedKeys = new Set(["name", "ref", "type", "description", "action", "score", "estimatedTokens"]);
+            for (const key of Object.keys(parsed)) {
+                expect(allowedKeys.has(key)).toBe(true);
+            }
+            // Must not have stripped fields
+            expect(parsed).not.toHaveProperty("path");
+            expect(parsed).not.toHaveProperty("origin");
+            expect(parsed).not.toHaveProperty("whyMatched");
+        }
+    });
+});

package/dist/tests/architecture/agent-no-llm-sdk-guard.test.js

@@ -0,0 +1,103 @@
+/**
+ * Regression guard — `src/integrations/agent/**` does not import LLM SDKs.
+ *
+ * Locks v1 spec §9.7 (LLM/agent boundary) and §12 (CLI shell-out only).
+ * Issue #222.
+ *
+ * **This test is defence-in-depth, not the primary enforcement.**
+ *
+ * The primary enforcement of the agent shell-out invariant is:
+ *   1. The seam test in `agent-spawn-seam.test.ts`, which locks the
+ *      `runAgent` interface.
+ *   2. The TypeScript module graph — vendor SDKs are not in
+ *      `package.json`, so an accidental import would fail to resolve at
+ *      build time.
+ *   3. Code review and the architectural boundary documented in
+ *      `docs/technical/architecture.md`.
+ *
+ * The guard below scans file contents under `src/integrations/agent/`
+ * for known LLM SDK package names. It exists to surface accidental
+ * regressions in PRs (e.g. someone copies an example that pulls in a
+ * vendor SDK before the type-check would catch it). The list is
+ * intentionally narrow — it names specific vendor packages, not broad
+ * patterns — so it does not flag legitimate code.
+ *
+ * Adding a new SDK package to the list (when a new vendor ships) is a
+ * one-line change. Removing the test entirely is a contract violation:
+ * agents are reachable only via the spawn wrapper.
+ */
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+const REPO_ROOT = path.resolve(import.meta.dir, "..", "..");
+const AGENT_DIR = path.join(REPO_ROOT, "src", "integrations", "agent");
+/**
+ * Specific vendor SDK package names whose presence in the agent
+ * integration tree would indicate the shell-out invariant has been
+ * crossed. The names are matched as quoted-import strings, not as
+ * arbitrary substrings, so unrelated mentions in comments do not
+ * trip the guard.
+ */
+const FORBIDDEN_LLM_SDK_PACKAGES = [
+    "@anthropic-ai/sdk",
+    "@anthropic-ai/bedrock-sdk",
+    "@anthropic-ai/vertex-sdk",
+    "openai",
+    "@google/generative-ai",
+    "@google/genai",
+    "@google-ai/generativelanguage",
+    "cohere-ai",
+    "@mistralai/mistralai",
+    "@huggingface/inference",
+    "groq-sdk",
+    "ollama",
+    "langchain",
+    "@langchain/core",
+    "@langchain/openai",
+    "@langchain/anthropic",
+    "ai",
+    "replicate",
+];
+function listAgentSourceFiles() {
+    const out = [];
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(abs);
+            else if (entry.isFile() && entry.name.endsWith(".ts"))
+                out.push(abs);
+        }
+    }
+    walk(AGENT_DIR);
+    return out.sort();
+}
+/**
+ * Match `from "<pkg>"` and `from '<pkg>'` and the equivalent
+ * `import("<pkg>")` / `require("<pkg>")` forms. This is deliberately
+ * a quoted-import match, not a free-text substring match, so writing
+ * about a vendor SDK in a comment ("never imports `openai`") does not
+ * trip the guard.
+ */
+function buildImportRegex(pkg) {
+    const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`${String.raw `(?:from|import\(|require\()\s*['"]` + escaped}(?:/[^'"]*)?['"]`);
+}
+describe("regression guard: src/integrations/agent/** never imports LLM SDKs", () => {
+    test("the agent integration tree exists", () => {
+        expect(fs.existsSync(AGENT_DIR)).toBe(true);
+        const files = listAgentSourceFiles();
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test.each([...FORBIDDEN_LLM_SDK_PACKAGES])("no file imports %s", (pkg) => {
+        const re = buildImportRegex(pkg);
+        const offenders = [];
+        for (const file of listAgentSourceFiles()) {
+            const text = fs.readFileSync(file, "utf8");
+            if (re.test(text)) {
+                offenders.push(path.relative(REPO_ROOT, file));
+            }
+        }
+        expect(offenders).toEqual([]);
+    });
+});