akm-cli 0.6.1 → 0.7.0-rc1

package/dist/{setup → src/setup}/setup.js

@@ -14,6 +14,7 @@ import { getDefaultStashDir } from "../core/paths";
 import { closeDatabase, isVecAvailable, openDatabase } from "../indexer/db";
 import { akmIndex } from "../indexer/indexer";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/semantic-status";
+import { detectAgentCliProfiles, pickDefaultAgentProfile, } from "../integrations/agent";
 import { probeLlmCapabilities } from "../llm/client";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder";
 import { detectAgentPlatforms, detectOllama } from "./detect";
@@ -284,6 +285,7 @@ async function stepOllama(current) {
             bge: 384,
         };
         const guessedDim = Object.entries(knownDims).find(([k]) => embChoice.includes(k))?.[1] ?? 384;
+        p.note("Embedding dimension must match the model. Common values: 384 (BGE small), 768 (BGE base), 1024 (BGE large). Press Enter to accept the detected default.", "Embedding dimension");
         const dimChoice = await prompt(() => p.text({
             message: `Embedding dimension for ${embChoice}:`,
             placeholder: String(guessedDim),
@@ -313,7 +315,6 @@ const LLM_PRESETS = [
         endpoint: "https://api.anthropic.com/v1/chat/completions",
         defaultModel: "claude-sonnet-4-5",
         hint: "beta OpenAI-compat layer; set AKM_LLM_API_KEY; override the model if the default is unavailable",
-        contextWindow: 200_000,
     },
     {
         value: "openai",
@@ -321,7 +322,6 @@ const LLM_PRESETS = [
         endpoint: "https://api.openai.com/v1/chat/completions",
         defaultModel: "gpt-4o-mini",
         hint: "AKM_LLM_API_KEY required",
-        contextWindow: 128_000,
     },
     {
         value: "google",
@@ -329,7 +329,6 @@ const LLM_PRESETS = [
         endpoint: "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
         defaultModel: "gemini-2.0-flash",
         hint: "OpenAI-compat endpoint, AKM_LLM_API_KEY required",
-        contextWindow: 1_000_000,
     },
 ];
 /**
@@ -431,7 +430,6 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels) {
             model: model.trim() || preset.defaultModel,
             temperature: 0.3,
             maxTokens: 1024,
-            contextWindow: preset.contextWindow,
         };
     }
     // Remind the user about API key placement. We do not offer a "store in config"
@@ -649,6 +647,29 @@ async function stepAgentPlatforms(current) {
     }
     return entries;
 }
+/**
+ * Detect installed agent CLIs and produce an updated `agent` config block
+ * with a sensible `default` (the first detected profile that the user has
+ * not already overridden).
+ *
+ * Pure-ish: file system / PATH probes are routed through `detectFn` so
+ * tests can drive the branches without touching the real PATH.
+ *
+ * @internal Exported for testing only.
+ */
+export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
+    const detections = detectFn(current.agent);
+    const defaultName = pickDefaultAgentProfile(detections, current.agent?.default);
+    // No installed agents found and no existing config → leave block absent.
+    if (!defaultName && !current.agent) {
+        return { detections };
+    }
+    const agent = {
+        ...(current.agent ?? {}),
+        ...(defaultName ? { default: defaultName } : {}),
+    };
+    return { agent, detections };
+}
 // ── Main Wizard ─────────────────────────────────────────────────────────────
 /**
  * Build the canonical list of `SetupStep`s for the interactive wizard.
@@ -731,6 +752,23 @@ export function buildSetupSteps(options) {
                 ctx.apply({ sources: merged.length > 0 ? merged : undefined });
             },
         },
+        {
+            id: "agent-cli",
+            label: "Agent CLI",
+            nonInteractive: true,
+            async run(ctx) {
+                const result = stepAgentCliDetection(ctx.config);
+                const detected = result.detections.filter((d) => d.available);
+                if (detected.length > 0) {
+                    p.log.info(`Detected agent CLIs: ${detected.map((d) => d.name).join(", ")}.` +
+                        (result.agent?.default ? ` Default profile: ${result.agent.default}.` : ""));
+                }
+                else {
+                    p.log.info("No agent CLIs detected on PATH. Agent commands will be disabled until one is installed and `akm setup` is re-run.");
+                }
+                ctx.apply({ agent: result.agent });
+            },
+        },
     ];
     return { steps, outcome };
 }
@@ -771,7 +809,7 @@ export async function runSetupWizard() {
     const embedding = newConfig.embedding;
     const llm = newConfig.llm;
     const registries = newConfig.registries;
-    const allStashes = newConfig.stashes ?? [];
+    const allStashes = newConfig.sources ?? newConfig.stashes ?? [];
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([

package/dist/{sources → src/sources}/providers/git.js

@@ -6,6 +6,7 @@ import { resolveStashDir } from "../../core/common";
 import { loadConfig } from "../../core/config";
 import { ConfigError, UsageError } from "../../core/errors";
 import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths";
+import { sanitizeCommitMessage } from "../../core/write-source";
 import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve";
 import { registerSourceProvider } from "../provider-factory";
 import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
@@ -77,20 +78,6 @@ function getCachePaths(repoUrl) {
     const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
     const cacheRoot = getRegistryIndexCacheDir();
     const rootDir = path.join(cacheRoot, `git-${key}`);
-    // One-time silent migration: legacy `context-hub-${key}` directories were
-    // created for ALL git stashes (not just the andrewyng/context-hub repo). If
-    // the new path doesn't yet exist but the legacy one does, rename it in place
-    // so existing clones aren't silently invalidated. Failures are non-fatal —
-    // worst case the repo is re-cloned on the next refresh.
-    try {
-        const legacyRootDir = path.join(cacheRoot, `context-hub-${key}`);
-        if (!fs.existsSync(rootDir) && fs.existsSync(legacyRootDir)) {
-            fs.renameSync(legacyRootDir, rootDir);
-        }
-    }
-    catch {
-        /* migration is best-effort */
-    }
     return {
         rootDir,
         repoDir: path.join(rootDir, "repo"),
@@ -398,7 +385,12 @@ function parseGitRepoUrl(rawUrl) {
  */
 export function saveGitStash(name, message, writableOverride) {
     const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
-    const commitMessage = message?.trim() || `akm save ${timestamp}`;
+    // Sanitize the user-supplied message: strip CR/LF/NUL, collapse whitespace,
+    // clamp length. An attacker can otherwise pass `--message "subject\n\n\
+    // Co-Authored-By: someone-else"` and forge trailers in the commit log.
+    // Empty result falls back to the timestamped default.
+    const sanitized = message ? sanitizeCommitMessage(message) : "";
+    const commitMessage = sanitized || `akm save ${timestamp}`;
     let repoDir;
     let writable = false;
     if (name) {

package/dist/tests/add-website-source.test.js

@@ -0,0 +1,119 @@
+import { afterAll, afterEach, describe, expect, test } from "bun:test";
+import { spawn } 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 = [];
+const servers = [];
+const CLI_TIMEOUT_MS = 30_000;
+const TEST_TIMEOUT_MS = 60_000;
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function createWorkingStash() {
+    const dir = makeTempDir("akm-add-website-stash-");
+    for (const sub of ["skills", "commands", "agents", "knowledge", "scripts"]) {
+        fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+    return dir;
+}
+function serveWebsite() {
+    const server = Bun.serve({
+        port: 0,
+        fetch(request) {
+            const url = new URL(request.url);
+            if (url.pathname === "/") {
+                return new Response("<html><head><title>Example Docs</title></head><body><h1>Example Docs</h1><p>Welcome to the docs.</p><a href='/getting-started'>Getting started</a></body></html>", {
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+            if (url.pathname === "/getting-started") {
+                return new Response("<html><body><h1>Getting started</h1><p>Run setup first.</p></body></html>", {
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+            return new Response("not found", { status: 404 });
+        },
+    });
+    servers.push(server);
+    return `http://127.0.0.1:${server.port}`;
+}
+afterEach(() => {
+    for (const server of servers.splice(0)) {
+        server.stop(true);
+    }
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+afterAll(() => {
+    for (const server of servers.splice(0)) {
+        server.stop(true);
+    }
+});
+describe("akm add website", () => {
+    test("adds a website stash source, caches markdown, and indexes it", async () => {
+        const stashDir = createWorkingStash();
+        const xdgCache = makeTempDir("akm-add-website-cache-");
+        const xdgConfig = makeTempDir("akm-add-website-config-");
+        const websiteUrl = serveWebsite();
+        const configDir = path.join(xdgConfig, "akm");
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(path.join(configDir, "config.json"), `${JSON.stringify({ semanticSearchMode: "off" }, null, 2)}\n`);
+        const child = spawn("bun", [CLI, "add", websiteUrl, "--name", "docs-site", "--format=json"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                AKM_STASH_DIR: stashDir,
+                XDG_CACHE_HOME: xdgCache,
+                XDG_CONFIG_HOME: xdgConfig,
+            },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        const exitCode = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error("CLI website add timed out"));
+            }, CLI_TIMEOUT_MS);
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                resolve(code ?? 1);
+            });
+        });
+        expect(exitCode).toBe(0);
+        expect(stderr.trim()).toBe("");
+        const parsed = JSON.parse(stdout.trim());
+        const normalizedWebsiteUrl = `${websiteUrl}/`;
+        expect(parsed.sourceAdded).toBeDefined();
+        expect(parsed.sourceAdded?.type).toBe("website");
+        expect(parsed.sourceAdded?.url).toBe(normalizedWebsiteUrl);
+        expect(parsed.sourceAdded?.name).toBe("docs-site");
+        expect(parsed.index?.totalEntries).toBeGreaterThanOrEqual(2);
+        const configPath = path.join(xdgConfig, "akm", "config.json");
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        expect(config.sources).toContainEqual({
+            type: "website",
+            url: normalizedWebsiteUrl,
+            name: "docs-site",
+        });
+        expect(parsed.sourceAdded?.stashRoot).toBeDefined();
+        const knowledgeFiles = fs.readdirSync(path.join(parsed.sourceAdded?.stashRoot, "knowledge")).sort();
+        expect(knowledgeFiles).toEqual(["getting-started.md", "index.md"]);
+        const homeDoc = fs.readFileSync(path.join(parsed.sourceAdded?.stashRoot, "knowledge", "index.md"), "utf8");
+        expect(homeDoc).toContain("Example Docs");
+    }, { timeout: TEST_TIMEOUT_MS });
+});

package/dist/tests/agent/agent-config-loader.test.js

@@ -0,0 +1,70 @@
+/**
+ * Integration test: the AkmConfig loader propagates the `agent` block
+ * through `loadConfig()` (and through the on-disk JSONC parser, exercising
+ * the `pickKnownKeys` path).
+ *
+ * The acceptance criterion "config schema accepts an optional agent block"
+ * lives at the loader boundary, not just the parser; this test pins the
+ * end-to-end shape.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+let tmpHome;
+let originalHome;
+let originalXdg;
+beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "akm-agent-cfg-"));
+    originalHome = process.env.HOME;
+    originalXdg = process.env.XDG_CONFIG_HOME;
+    process.env.HOME = tmpHome;
+    process.env.XDG_CONFIG_HOME = path.join(tmpHome, ".config");
+});
+afterEach(() => {
+    if (originalHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = originalHome;
+    if (originalXdg === undefined)
+        delete process.env.XDG_CONFIG_HOME;
+    else
+        process.env.XDG_CONFIG_HOME = originalXdg;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+describe("AkmConfig loader — agent block", () => {
+    test("loads agent.default + agent.profiles from disk", async () => {
+        const { getConfigPath, loadUserConfig, resetConfigCache } = await import("../../src/core/config");
+        const cfgPath = getConfigPath();
+        fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+        fs.writeFileSync(cfgPath, JSON.stringify({
+            semanticSearchMode: "auto",
+            agent: {
+                default: "claude",
+                timeoutMs: 45000,
+                profiles: {
+                    claude: { args: ["--print"] },
+                    rover: { bin: "rover-cli", parseOutput: "json" },
+                },
+                // Unknown key — must not throw at load.
+                mystery: 1,
+            },
+        }, null, 2));
+        resetConfigCache();
+        const cfg = loadUserConfig();
+        expect(cfg.agent?.default).toBe("claude");
+        expect(cfg.agent?.timeoutMs).toBe(45000);
+        expect(cfg.agent?.profiles?.claude?.args).toEqual(["--print"]);
+        expect(cfg.agent?.profiles?.rover?.bin).toBe("rover-cli");
+        expect(cfg.agent?.profiles?.rover?.parseOutput).toBe("json");
+    });
+    test("agent block absent → cfg.agent is undefined → requireAgentProfile throws", async () => {
+        const { loadUserConfig, resetConfigCache } = await import("../../src/core/config");
+        const { requireAgentProfile } = await import("../../src/integrations/agent/config");
+        const { ConfigError } = await import("../../src/core/errors");
+        resetConfigCache();
+        const cfg = loadUserConfig();
+        expect(cfg.agent).toBeUndefined();
+        expect(() => requireAgentProfile(cfg.agent)).toThrow(ConfigError);
+    });
+});

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

@@ -0,0 +1,221 @@
+/**
+ * Tests for the `agent.*` config block parser and profile resolver.
+ *
+ * Acceptance coverage:
+ *   • Parser accepts the documented shape.
+ *   • Unknown keys are warn-and-ignored (no throw).
+ *   • Built-in profiles resolve for opencode, claude, codex, gemini, aider.
+ *   • Missing block surfaces a stable ConfigError via requireAgentProfile.
+ */
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+const warnings = [];
+// NOTE: `mock.module` in Bun is process-global — once installed it persists
+// across test files run in the same `bun test` invocation. So this mock has
+// to remain a faithful drop-in for the real `src/core/warn` module:
+//
+//   1. Every export that the real module ships must be represented here,
+//      otherwise tests in other files that import a missing export get
+//      `undefined` and silently break (issue #273).
+//   2. `warn()` must also forward to `console.warn` so other test files that
+//      capture stderr (e.g. the noise-gate tests in
+//      tests/workflows/indexer-rejection.test.ts) continue to see the calls.
+//      We push to the local `warnings[]` so this file's own assertions still
+//      work, AND forward to `console.warn` so callers that intercept it
+//      still observe what was emitted.
+let mockedQuiet = false;
+let mockedVerbose = false;
+mock.module("../../src/core/warn", () => ({
+    warn: (...args) => {
+        warnings.push(args.join(" "));
+        if (!mockedQuiet)
+            console.warn(...args);
+    },
+    warnVerbose: (...args) => {
+        if (!mockedVerbose)
+            return;
+        warnings.push(args.join(" "));
+        if (!mockedQuiet)
+            console.warn(...args);
+    },
+    setQuiet: (value) => {
+        mockedQuiet = value;
+    },
+    resetQuiet: () => {
+        mockedQuiet = false;
+    },
+    isQuiet: () => mockedQuiet,
+    setVerbose: (value) => {
+        mockedVerbose = value;
+    },
+    resetVerbose: () => {
+        mockedVerbose = false;
+    },
+    isVerbose: () => {
+        const env = process.env.AKM_VERBOSE?.trim().toLowerCase();
+        if (env === "1" || env === "true" || env === "yes" || env === "on")
+            return true;
+        if (env === "0" || env === "false" || env === "no" || env === "off")
+            return false;
+        return mockedVerbose;
+    },
+}));
+beforeEach(() => {
+    warnings.length = 0;
+});
+afterEach(() => {
+    warnings.length = 0;
+});
+describe("parseAgentConfig", () => {
+    test("returns undefined when block is absent", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        expect(parseAgentConfig(undefined)).toBeUndefined();
+        expect(warnings).toHaveLength(0);
+    });
+    test("warns and returns undefined for non-object root", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        expect(parseAgentConfig("oops")).toBeUndefined();
+        expect(warnings.some((w) => w.includes('"agent"'))).toBe(true);
+    });
+    test("accepts the documented shape", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({
+            default: "opencode",
+            timeoutMs: 30000,
+            profiles: {
+                opencode: { bin: "opencode", args: ["--non-interactive"], stdio: "captured" },
+            },
+        });
+        expect(parsed?.default).toBe("opencode");
+        expect(parsed?.timeoutMs).toBe(30000);
+        expect(parsed?.profiles?.opencode).toEqual({
+            bin: "opencode",
+            args: ["--non-interactive"],
+            stdio: "captured",
+        });
+    });
+    test("warn-and-ignore unknown top-level keys (no throw)", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({
+            default: "claude",
+            moonRoutingTable: { foo: "bar" }, // unknown
+        });
+        expect(parsed?.default).toBe("claude");
+        expect(warnings.some((w) => w.includes("moonRoutingTable"))).toBe(true);
+    });
+    test("warn-and-ignore unknown per-profile keys", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({
+            profiles: {
+                custom: { bin: "ok", quirks: "nope" },
+            },
+        });
+        expect(parsed?.profiles?.custom?.bin).toBe("ok");
+        expect(warnings.some((w) => w.includes("quirks"))).toBe(true);
+    });
+    test("warn-and-ignore malformed timeoutMs", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({ timeoutMs: "60s" });
+        expect(parsed?.timeoutMs).toBeUndefined();
+        expect(warnings.some((w) => w.includes("timeoutMs"))).toBe(true);
+    });
+    test("rejects non-string args entries", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({
+            profiles: { opencode: { args: ["--ok", 5, "--also-ok"] } },
+        });
+        expect(parsed?.profiles?.opencode?.args).toEqual(["--ok", "--also-ok"]);
+        expect(warnings.some((w) => w.includes("args"))).toBe(true);
+    });
+    test("rejects bad stdio mode", async () => {
+        const { parseAgentConfig } = await import("../../src/integrations/agent/config");
+        const parsed = parseAgentConfig({
+            profiles: { opencode: { stdio: "weird" } },
+        });
+        expect(parsed?.profiles?.opencode?.stdio).toBeUndefined();
+        expect(warnings.some((w) => w.includes("stdio"))).toBe(true);
+    });
+});
+describe("built-in profile resolution", () => {
+    test("resolves opencode, claude, codex, gemini, aider out of the box", async () => {
+        const { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile } = await import("../../src/integrations/agent/profiles");
+        expect(BUILTIN_AGENT_PROFILE_NAMES).toEqual(["aider", "claude", "codex", "gemini", "opencode"]);
+        for (const name of ["opencode", "claude", "codex", "gemini", "aider"]) {
+            const profile = getBuiltinAgentProfile(name);
+            expect(profile).toBeDefined();
+            expect(profile?.bin).toBeTruthy();
+            expect(profile?.envPassthrough).toContain("PATH");
+        }
+    });
+    test("user override merges on top of built-in", async () => {
+        const { resolveAgentProfile } = await import("../../src/integrations/agent/config");
+        const merged = resolveAgentProfile("opencode", { args: ["--scripted"], stdio: "captured" });
+        expect(merged?.bin).toBe("opencode"); // built-in default
+        expect(merged?.args).toEqual(["--scripted"]); // override
+        expect(merged?.stdio).toBe("captured"); // override
+        expect(merged?.envPassthrough).toContain("PATH"); // built-in retained
+    });
+    test("user-defined profile (no built-in) requires bin", async () => {
+        const { resolveAgentProfile } = await import("../../src/integrations/agent/config");
+        expect(resolveAgentProfile("rover", undefined)).toBeUndefined();
+        expect(resolveAgentProfile("rover", {})).toBeUndefined();
+        const ok = resolveAgentProfile("rover", { bin: "rover-cli", args: ["--silent"] });
+        expect(ok?.bin).toBe("rover-cli");
+        expect(ok?.args).toEqual(["--silent"]);
+        expect(ok?.stdio).toBe("captured");
+    });
+    test("envPassthrough merges base + override", async () => {
+        const { resolveAgentProfile } = await import("../../src/integrations/agent/config");
+        const merged = resolveAgentProfile("opencode", { envPassthrough: ["MY_TOKEN"] });
+        expect(merged?.envPassthrough).toContain("PATH"); // from built-in
+        expect(merged?.envPassthrough).toContain("MY_TOKEN"); // from override
+    });
+    test("listAgentProfileNames includes built-ins plus user-defined", async () => {
+        const { listAgentProfileNames } = await import("../../src/integrations/agent/config");
+        const names = listAgentProfileNames({ profiles: { rover: { bin: "rover" } } });
+        expect(names).toContain("rover");
+        expect(names).toContain("opencode");
+        expect(names).toContain("claude");
+    });
+});
+describe("requireAgentProfile", () => {
+    test("throws ConfigError when the agent block is missing", async () => {
+        const { requireAgentProfile } = await import("../../src/integrations/agent/config");
+        const { ConfigError } = await import("../../src/core/errors");
+        let caught;
+        try {
+            requireAgentProfile(undefined);
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(ConfigError);
+        expect(caught.message).toContain("agent commands are disabled");
+        const hint = caught.hint();
+        expect(hint).toBeTruthy();
+        expect(hint).toContain("akm setup");
+    });
+    test("throws when no default and no requested name", async () => {
+        const { requireAgentProfile } = await import("../../src/integrations/agent/config");
+        const { ConfigError } = await import("../../src/core/errors");
+        let caught;
+        try {
+            requireAgentProfile({});
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(ConfigError);
+        expect(caught.message).toContain("require a profile");
+    });
+    test("resolves the requested profile when valid", async () => {
+        const { requireAgentProfile } = await import("../../src/integrations/agent/config");
+        const profile = requireAgentProfile({ default: "claude" });
+        expect(profile.name).toBe("claude");
+        expect(profile.bin).toBe("claude");
+    });
+    test("explicit requested name beats config default", async () => {
+        const { requireAgentProfile } = await import("../../src/integrations/agent/config");
+        const profile = requireAgentProfile({ default: "claude" }, "codex");
+        expect(profile.name).toBe("codex");
+    });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * Tests for setup-time agent CLI detection.
+ *
+ * Acceptance coverage:
+ *   • Detects every built-in profile bin via the injected `which` probe.
+ *   • Picks the first available profile as the default.
+ *   • Honours an existing `agent.default` when that profile is still
+ *     available (round-trip stability).
+ *   • Returns `undefined` when nothing is installed.
+ *   • `stepAgentCliDetection` produces a config-shaped result the wizard
+ *     can `apply()`.
+ */
+import { describe, expect, test } from "bun:test";
+import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../src/integrations/agent/detect";
+function whichOnly(installed) {
+    const set = new Set(installed);
+    return (bin) => (set.has(bin) ? `/usr/local/bin/${bin}` : undefined);
+}
+describe("detectAgentCliProfiles", () => {
+    test("reports every built-in profile, available iff bin found", () => {
+        const results = detectAgentCliProfiles(undefined, whichOnly(["claude", "codex"]));
+        const names = results.map((r) => r.name).sort();
+        expect(names).toEqual(["aider", "claude", "codex", "gemini", "opencode"]);
+        expect(results.find((r) => r.name === "claude")?.available).toBe(true);
+        expect(results.find((r) => r.name === "codex")?.available).toBe(true);
+        expect(results.find((r) => r.name === "gemini")?.available).toBe(false);
+    });
+    test("includes user-defined profiles via the resolver", () => {
+        const results = detectAgentCliProfiles({ profiles: { rover: { bin: "rover-cli" } } }, whichOnly(["rover-cli"]));
+        const rover = results.find((r) => r.name === "rover");
+        expect(rover?.available).toBe(true);
+        expect(rover?.resolvedPath).toContain("rover-cli");
+    });
+    test("returns nothing-installed when the probe always says no", () => {
+        const results = detectAgentCliProfiles(undefined, whichOnly([]));
+        expect(results.every((r) => !r.available)).toBe(true);
+    });
+});
+describe("pickDefaultAgentProfile", () => {
+    test("picks the first available result when no existing default", () => {
+        const picked = pickDefaultAgentProfile([
+            { name: "aider", bin: "aider", available: false },
+            { name: "claude", bin: "claude", available: true },
+            { name: "codex", bin: "codex", available: true },
+        ]);
+        expect(picked).toBe("claude");
+    });
+    test("keeps an existing available default", () => {
+        const picked = pickDefaultAgentProfile([
+            { name: "claude", bin: "claude", available: true },
+            { name: "codex", bin: "codex", available: true },
+        ], "codex");
+        expect(picked).toBe("codex");
+    });
+    test("falls back when the existing default is no longer available", () => {
+        const picked = pickDefaultAgentProfile([
+            { name: "claude", bin: "claude", available: true },
+            { name: "codex", bin: "codex", available: false },
+        ], "codex");
+        expect(picked).toBe("claude");
+    });
+    test("returns undefined when nothing is available", () => {
+        const picked = pickDefaultAgentProfile([
+            { name: "claude", bin: "claude", available: false },
+            { name: "codex", bin: "codex", available: false },
+        ]);
+        expect(picked).toBeUndefined();
+    });
+});
+describe("stepAgentCliDetection (setup wizard)", () => {
+    test("persists default + leaves block absent when nothing detected & no prior config", async () => {
+        const { stepAgentCliDetection } = await import("../../src/setup/setup");
+        const result = stepAgentCliDetection({ semanticSearchMode: "auto" }, () => [
+            { name: "claude", bin: "claude", available: false },
+            { name: "codex", bin: "codex", available: false },
+        ]);
+        expect(result.agent).toBeUndefined();
+        expect(result.detections).toHaveLength(2);
+    });
+    test("writes agent.default to the first detected profile", async () => {
+        const { stepAgentCliDetection } = await import("../../src/setup/setup");
+        const result = stepAgentCliDetection({ semanticSearchMode: "auto" }, () => [
+            { name: "claude", bin: "claude", available: false },
+            { name: "codex", bin: "codex", available: true },
+        ]);
+        expect(result.agent?.default).toBe("codex");
+    });
+    test("preserves user-overridden default when still available", async () => {
+        const { stepAgentCliDetection } = await import("../../src/setup/setup");
+        const result = stepAgentCliDetection({
+            semanticSearchMode: "auto",
+            agent: { default: "aider", profiles: { aider: { args: ["--no-auto-commits"] } } },
+        }, () => [
+            { name: "claude", bin: "claude", available: true },
+            { name: "aider", bin: "aider", available: true },
+        ]);
+        expect(result.agent?.default).toBe("aider");
+        expect(result.agent?.profiles?.aider?.args).toEqual(["--no-auto-commits"]);
+    });
+});