akm-cli 0.7.0 → 0.7.1

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

@@ -1,234 +0,0 @@
-/**
- * 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

@@ -1,186 +0,0 @@
-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

@@ -1,103 +0,0 @@
-/**
- * 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([]);
-    });
-});