@takara-ai/miru-code 1.8.2 → 1.10.0

package/src/index/chunk-selector.ts

@@ -4,14 +4,16 @@ export type ChunkIndexMappings = {
 };
 
 /**
- * Union of chunk indices matching language and/or path filters.
+ * Union of chunk indices matching language and/or path filters. Path filters
+ * match an exact indexed file path or every file below a directory prefix.
  *
  * Filters combine with OR semantics: a chunk is included if it matches any
  * requested language or path. Returns `undefined` when no filters are given
- * (search all chunks) or when no chunks match.
+ * (search all chunks), and an empty array when filters match no chunks.
  *
- * Single-filter queries return the prebuilt map array directly (read-only for
- * callers). Multi-filter queries allocate a deduped index list.
+ * Exact-file and single-language queries return the prebuilt map array
+ * directly (read-only for callers). Directory and multi-filter queries
+ * allocate an index list.
  */
 export function buildChunkSelector(
   mappings: ChunkIndexMappings,
@@ -28,19 +30,28 @@ export function buildChunkSelector(
   if (langCount === 1 && pathCount === 0) {
     const lang = filterLanguages?.[0];
     if (!lang) {
-      return undefined;
+      return [];
     }
     const indices = mappings.languageMapping.get(lang);
-    return indices && indices.length > 0 ? indices : undefined;
+    return indices && indices.length > 0 ? indices : [];
   }
 
   if (pathCount === 1 && langCount === 0) {
     const fp = filterPaths?.[0];
     if (!fp) {
-      return undefined;
+      return [];
     }
-    const indices = mappings.fileMapping.get(fp);
-    return indices && indices.length > 0 ? indices : undefined;
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      return exact;
+    }
+    const prefix = `${normalized}/`;
+    return [...mappings.fileMapping.entries()]
+      .filter(([filePath]) => filePath.replace(/\\/g, "/").startsWith(prefix))
+      .flatMap(([, indices]) => indices);
   }
 
   const selector: number[] = [];
@@ -48,10 +59,27 @@ export function buildChunkSelector(
     selector.push(...(mappings.languageMapping.get(lang) ?? []));
   }
   for (const fp of filterPaths ?? []) {
-    selector.push(...(mappings.fileMapping.get(fp) ?? []));
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      selector.push(...exact);
+      continue;
+    }
+    const prefix = `${normalized}/`;
+    for (const [filePath, indices] of mappings.fileMapping) {
+      if (filePath.replace(/\\/g, "/").startsWith(prefix)) {
+        selector.push(...indices);
+      }
+    }
   }
   if (selector.length === 0) {
-    return undefined;
+    return [];
   }
   return [...new Set(selector)];
 }
+
+function normalizePathFilter(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}

package/src/index/create.ts

@@ -136,9 +136,6 @@ export async function createIndexFromPath(
       }
 
       const take = Math.min(embedBatchSize, pendingWindows.length);
-      if (!force && take < embedBatchSize) {
-        break;
-      }
 
       const batch = pendingWindows.splice(0, take);
       emittedApiBatches++;
@@ -158,9 +155,10 @@ export async function createIndexFromPath(
       })();
       embedPromises.push(promise);
       embedInFlight.add(promise);
-      promise.finally(() => {
-        embedInFlight.delete(promise);
-      });
+      promise.then(
+        () => embedInFlight.delete(promise),
+        () => embedInFlight.delete(promise),
+      );
     }
   };
 
@@ -209,9 +207,7 @@ export async function createIndexFromPath(
   await maybeScheduleEmbed(true);
   await Promise.all(embedPromises);
   // Finish any BM25 docs not yet processed during idle gaps.
-  while (bm25Cursor < emittedChunks.length) {
-    progressBm25(50);
-  }
+  progressBm25(Number.POSITIVE_INFINITY);
   const embedsDoneAt = performance.now();
 
   const chunks = emittedChunks;

package/src/index/files.ts

@@ -52,6 +52,9 @@ const EXTENSION_TO_LANGUAGE: Record<string, string> = {
   ".zig": "zig",
   ".vue": "vue",
   ".svelte": "svelte",
+  ".astro": "astro",
+  ".erb": "embeddedtemplate",
+  ".ejs": "embeddedtemplate",
   ".md": "markdown",
   ".mdx": "markdown",
   ".rst": "rst",
@@ -64,6 +67,7 @@ const EXTENSION_TO_LANGUAGE: Record<string, string> = {
   ".cfg": "ini",
   ".xml": "xml",
   ".html": "html",
+  ".htm": "html",
   ".css": "css",
   ".scss": "scss",
   ".less": "less",
@@ -74,7 +78,7 @@ const CODE_EXTENSIONS = new Set(
   Object.entries(EXTENSION_TO_LANGUAGE)
     .filter(
       ([, lang]) =>
-        !["markdown", "rst", "text", "json", "yaml", "toml", "ini", "xml", "html"].includes(lang),
+        !["markdown", "rst", "text", "json", "yaml", "toml", "ini", "xml"].includes(lang),
     )
     .map(([ext]) => ext),
 );

package/src/index/incremental.ts

@@ -5,7 +5,7 @@ import type { Chunk, ContentType } from "../types.ts";
 import type { BM25Index } from "./bm25.ts";
 import { detectLanguage, getExtensions, getFileStatus, readFileText } from "./files.ts";
 import type { SemanticIndex } from "./semantic-index.ts";
-import { buildBm25FromChunks } from "./sparse.ts";
+import { buildBm25FromChunks, patchBm25 } from "./sparse.ts";
 import { buildSemanticIndex } from "./vector-storage.ts";
 import { vectorAt } from "./vectors.ts";
 
@@ -40,9 +40,34 @@ function isIndexableRelativePath(relativePath: string, extensions: Set<string>):
   return extensions.has(ext);
 }
 
+/** Vector for every text: reused from `known`, otherwise embedded once (duplicates share a call). */
+async function vectorsByText(
+  embeddings: EmbeddingBackend,
+  texts: readonly string[],
+  known: ReadonlyMap<string, Float32Array>,
+): Promise<Map<string, Float32Array>> {
+  const result = new Map(known);
+  const missing = [...new Set(texts)].filter((text) => !result.has(text));
+  if (missing.length === 0) {
+    return result;
+  }
+  const embedded = await embeddings.embedDocuments(missing);
+  if (embedded.length !== missing.length) {
+    throw new Error(
+      `Vector count ${embedded.length} does not match chunk count ${missing.length}.`,
+    );
+  }
+  for (const [i, text] of missing.entries()) {
+    result.set(text, embedded[i] as Float32Array);
+  }
+  return result;
+}
+
 /**
  * Replace chunks for the given repo-relative paths only: remove old chunks,
- * embed new ones, rebuild BM25 + semantic indexes from the merged vector set.
+ * embed new ones, rebuild the semantic index from the merged vector set, and update
+ * BM25 by dropping the old docs and indexing only the new chunks. Pass `bm25` (the
+ * index matching `chunks`) to enable that; without it BM25 is rebuilt from scratch.
  */
 export async function applyIncrementalFileChanges(options: {
   root: string;
@@ -50,6 +75,7 @@ export async function applyIncrementalFileChanges(options: {
   embeddings: EmbeddingBackend;
   chunks: Chunk[];
   semanticIndex: SemanticIndex;
+  bm25?: BM25Index;
   relativePaths: readonly string[];
 }): Promise<{ chunks: Chunk[]; bm25: BM25Index; semantic: SemanticIndex }> {
   const root = resolve(options.root);
@@ -60,16 +86,24 @@ export async function applyIncrementalFileChanges(options: {
       .filter((p) => p.length > 0 && isIndexableRelativePath(p, extensions)),
   );
 
+  // BM25 doc i is chunk i; an index of another size can't be patched safely.
+  const baseBm25 = options.bm25?.size === options.chunks.length ? options.bm25 : undefined;
+
   if (targets.size === 0) {
     return {
       chunks: options.chunks,
-      bm25: buildBm25FromChunks(options.chunks),
+      bm25: baseBm25 ?? buildBm25FromChunks(options.chunks),
       semantic: options.semanticIndex,
     };
   }
 
   const keptChunks: Chunk[] = [];
   const keptVectors: Float32Array[] = [];
+  const removedDocs = new Set<number>();
+  // An embedding is a pure function of chunk text, so a re-chunked file can reuse
+  // the vector of any old chunk with byte-identical content (keyed on the exact
+  // string, never a hash, so a collision can't leave a stale vector).
+  const reusableVectors = new Map<string, Float32Array>();
 
   for (let i = 0; i < options.chunks.length; i++) {
     const chunk = options.chunks[i];
@@ -78,6 +112,10 @@ export async function applyIncrementalFileChanges(options: {
     }
     const rel = normalizeRelativePath(chunk.file_path);
     if (targets.has(rel)) {
+      removedDocs.add(i);
+      if (!reusableVectors.has(chunk.content)) {
+        reusableVectors.set(chunk.content, vectorAt(options.semanticIndex, i));
+      }
       continue;
     }
     keptChunks.push(chunk);
@@ -89,10 +127,12 @@ export async function applyIncrementalFileChanges(options: {
     addedChunks.push(...(await chunksForFile(root, rel)));
   }
 
-  let addedVectors: Float32Array[] = [];
-  if (addedChunks.length > 0) {
-    addedVectors = await options.embeddings.embedDocuments(addedChunks.map((c) => c.content));
-  }
+  const vectorFor = await vectorsByText(
+    options.embeddings,
+    addedChunks.map((c) => c.content),
+    reusableVectors,
+  );
+  const addedVectors = addedChunks.map((c) => vectorFor.get(c.content) as Float32Array);
 
   const chunks = [...keptChunks, ...addedChunks];
   const vectors = [...keptVectors, ...addedVectors];
@@ -107,7 +147,7 @@ export async function applyIncrementalFileChanges(options: {
 
   return {
     chunks,
-    bm25: buildBm25FromChunks(chunks),
+    bm25: baseBm25 ? patchBm25(baseBm25, removedDocs, addedChunks) : buildBm25FromChunks(chunks),
     semantic: buildSemanticIndex(vectors),
   };
 }

package/src/index/sparse.ts

@@ -30,10 +30,22 @@ export function addChunkToBm25(bm25: BM25Index, chunk: Chunk): void {
   bm25.addDocument(tokenize(enrichForBm25(chunk)));
 }
 
-export function buildBm25FromChunks(chunks: readonly Chunk[]): BM25Index {
-  const bm25 = new BM25Index();
+function appendChunksToBm25(bm25: BM25Index, chunks: readonly Chunk[]): BM25Index {
   for (const chunk of chunks) {
     addChunkToBm25(bm25, chunk);
   }
   return bm25;
 }
+
+export function buildBm25FromChunks(chunks: readonly Chunk[]): BM25Index {
+  return appendChunksToBm25(new BM25Index(), chunks);
+}
+
+/** Drop docs `removedDocs` from `base` and append `added`; `base` is left untouched. */
+export function patchBm25(
+  base: BM25Index,
+  removedDocs: ReadonlySet<number>,
+  added: readonly Chunk[],
+): BM25Index {
+  return appendChunksToBm25(base.withoutDocuments(removedDocs), added);
+}

package/src/installer/agents.ts

@@ -5,11 +5,7 @@ import { join } from "node:path";
 import type { AgentId } from "../agents.ts";
 import { INSTRUCTIONS_MARKDOWN } from "./search-policy.ts";
 
-function copilotHooksPath(home: string): string {
-  return join(home, ".copilot", "hooks", "miru-search.json");
-}
-
-/** Shared Copilot / VS Code / Visual Studio config root (MCP, hooks, agents). */
+/** Shared Copilot / VS Code / Visual Studio config root (MCP, agents). */
 export function copilotHomeDir(home: string): string {
   return join(home, ".copilot");
 }
@@ -55,22 +51,15 @@ export function nativeSteSkillDir(home: string, vendor: NativeSkillVendor): stri
   return skillDir(home, `.${vendor}`, "ste");
 }
 
-function kiroHooksPath(home: string): string {
-  return join(home, ".kiro", "settings", "hooks.json");
-}
-
-function windsurfHooksPath(home: string): string {
-  return join(home, ".codeium", "windsurf", "hooks.json");
-}
-
 /** OpenCode config root (`$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`). */
 export function opencodeConfigDir(home: string): string {
   const xdg = process.env.XDG_CONFIG_HOME;
   return xdg ? join(xdg, "opencode") : join(home, ".config", "opencode");
 }
 
-function opencodePluginPath(home: string): string {
-  return join(opencodeConfigDir(home), "plugins", "miru-search-guard.ts");
+/** OpenCode's first-class global skill location for Miru code-search routing. */
+export function opencodeMiruSkillPath(home: string): string {
+  return join(opencodeConfigDir(home), "skills", "miru-code-search", "SKILL.md");
 }
 
 export type InstallAction =
@@ -86,24 +75,24 @@ export type InstallMode = "install" | "uninstall";
 
 export const MIRU_START = "<!-- miru:start -->";
 export const MIRU_END = "<!-- miru:end -->";
+export const MIRU_BUNX_PACKAGE = "@takara-ai/miru-code@latest";
 
 const HOME = homedir();
 
 const STDIO_SERVER_CONFIG: Record<string, unknown> = {
   command: "bunx",
-  args: ["@takara-ai/miru-code"],
+  args: [MIRU_BUNX_PACKAGE, "mcp"],
   type: "stdio",
 };
 
 const BARE_STDIO_SERVER_CONFIG: Record<string, unknown> = {
   command: "bunx",
-  args: ["@takara-ai/miru-code"],
+  args: [MIRU_BUNX_PACKAGE, "mcp"],
 };
 
 const OPENCODE_SERVER_CONFIG: Record<string, unknown> = {
-  command: ["bunx", "@takara-ai/miru-code"],
+  command: ["bunx", MIRU_BUNX_PACKAGE, "mcp"],
   type: "local",
-  enabled: true,
 };
 
 export const INSTRUCTIONS = `${MIRU_START}
@@ -121,7 +110,7 @@ export interface McpConfig {
   format: McpConfigFormat;
 }
 
-export type HooksFormat =
+export type LegacyHooksFormat =
   | "claude"
   | "cursor"
   | "gemini"
@@ -138,8 +127,9 @@ export interface AgentTarget {
   mcp: McpConfig | null;
   instructionsPath: string | null;
   cursorRulesPath: string | null;
-  hooksPath: string | null;
-  hooksFormat: HooksFormat | null;
+  /** Search-hook paths are retained for uninstalling hooks created by older releases. */
+  legacyHooksPath: string | null;
+  legacyHooksFormat: LegacyHooksFormat | null;
   subagentPath: string | null;
   subagentId: AgentId | null;
   /**
@@ -151,6 +141,8 @@ export interface AgentTarget {
    * On-demand STE skill directory (`…/skills/ste/`), or null if unsupported.
    */
   steSkillDir: string | null;
+  /** OpenCode's global Miru code-search skill, advertised on each model step. */
+  miruSkillPath?: string | null;
 }
 
 export function opencodeMcpPath(): string {
@@ -166,11 +158,11 @@ export function opencodeMcpPath(): string {
   return jsonc;
 }
 
-export function vscodeMcpPath(): string {
-  if (process.platform === "darwin") {
+export function vscodeMcpPath(platform: NodeJS.Platform = process.platform): string {
+  if (platform === "darwin") {
     return join(HOME, "Library", "Application Support", "Code", "User", "mcp.json");
   }
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     const appData = process.env.APPDATA ?? HOME;
     return join(appData, "Code", "User", "mcp.json");
   }
@@ -184,23 +176,27 @@ export function visualStudioMcpPath(): string {
   return join(profile, ".mcp.json");
 }
 
-export function visualStudioInstallDir(): string | null {
-  if (process.platform !== "win32") {
+export function visualStudioInstallDir(
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (platform !== "win32") {
     return null;
   }
   const programFiles = process.env.ProgramFiles ?? join("C:", "Program Files");
   return join(programFiles, "Microsoft Visual Studio");
 }
 
-async function detectVisualStudio(): Promise<boolean> {
-  if (process.platform !== "win32") {
+async function detectVisualStudio(dependencies: AgentDetectionDependencies = {}): Promise<boolean> {
+  const platform = dependencies.platform ?? process.platform;
+  if (platform !== "win32") {
     return false;
   }
 
-  const installDir = visualStudioInstallDir();
-  if (installDir && existsSync(installDir)) {
+  const installDir = visualStudioInstallDir(platform);
+  const pathExists = dependencies.existsSync ?? existsSync;
+  if (installDir && pathExists(installDir)) {
     try {
-      const entries = await readdir(installDir);
+      const entries = await (dependencies.readdir ?? ((path: string) => readdir(path)))(installDir);
       if (entries.length > 0) {
         return true;
       }
@@ -210,8 +206,9 @@ async function detectVisualStudio(): Promise<boolean> {
   }
 
   try {
-    const proc = Bun.spawn(["where", "devenv"], { stdout: "pipe", stderr: "ignore" });
-    return (await proc.exited) === 0;
+    return await (dependencies.commandOnPath
+      ? dependencies.commandOnPath("devenv")
+      : commandOnPath("devenv", platform, dependencies.spawn));
   } catch {
     return false;
   }
@@ -233,8 +230,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(join(HOME, ".claude.json"), "mcpServers", STDIO_SERVER_CONFIG),
     instructionsPath: join(HOME, ".claude", "CLAUDE.md"),
     cursorRulesPath: null,
-    hooksPath: join(HOME, ".claude", "settings.json"),
-    hooksFormat: "claude",
+    legacyHooksPath: join(HOME, ".claude", "settings.json"),
+    legacyHooksFormat: "claude",
     subagentPath: join(HOME, ".claude", "agents", "miru-code.md"),
     subagentId: "claude",
     cavemanSkillPath: nativeCavemanSkillPath(HOME, "claude"),
@@ -248,12 +245,13 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(join(HOME, ".cursor", "mcp.json"), "mcpServers", STDIO_SERVER_CONFIG),
     instructionsPath: null,
     cursorRulesPath: join(HOME, ".cursor", "rules", "miru-code.mdc"),
-    hooksPath: join(HOME, ".cursor", "hooks.json"),
-    hooksFormat: "cursor",
+    legacyHooksPath: join(HOME, ".cursor", "hooks.json"),
+    legacyHooksFormat: "cursor",
     subagentPath: join(HOME, ".cursor", "agents", "miru-code.md"),
     subagentId: "cursor",
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
     steSkillDir: SHARED_STE_SKILL_DIR,
+    miruSkillPath: opencodeMiruSkillPath(HOME),
   },
   {
     id: "gemini",
@@ -263,8 +261,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(join(HOME, ".gemini", "settings.json"), "mcpServers", STDIO_SERVER_CONFIG),
     instructionsPath: join(HOME, ".gemini", "GEMINI.md"),
     cursorRulesPath: null,
-    hooksPath: join(HOME, ".gemini", "settings.json"),
-    hooksFormat: "gemini",
+    legacyHooksPath: join(HOME, ".gemini", "settings.json"),
+    legacyHooksFormat: "gemini",
     subagentPath: join(HOME, ".gemini", "agents", "miru-code.md"),
     subagentId: "gemini",
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -278,8 +276,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(join(HOME, ".kiro", "settings", "mcp.json"), "mcpServers", STDIO_SERVER_CONFIG),
     instructionsPath: join(HOME, ".kiro", "steering", "miru.md"),
     cursorRulesPath: null,
-    hooksPath: kiroHooksPath(HOME),
-    hooksFormat: "kiro",
+    legacyHooksPath: join(HOME, ".kiro", "settings", "hooks.json"),
+    legacyHooksFormat: "kiro",
     subagentPath: join(HOME, ".kiro", "agents", "miru-code.md"),
     subagentId: "kiro",
     cavemanSkillPath: nativeCavemanSkillPath(HOME, "kiro"),
@@ -290,11 +288,11 @@ export const AGENT_TARGETS: AgentTarget[] = [
     displayName: "OpenCode",
     binary: "opencode",
     configDir: opencodeConfigDir(HOME),
-    mcp: jsonMcp(opencodeMcpPath(), "mcp", OPENCODE_SERVER_CONFIG),
+    mcp: jsonMcp(opencodeMcpPath(), "mcp.servers", OPENCODE_SERVER_CONFIG),
     instructionsPath: join(opencodeConfigDir(HOME), "AGENTS.md"),
     cursorRulesPath: null,
-    hooksPath: opencodePluginPath(HOME),
-    hooksFormat: "opencode",
+    legacyHooksPath: join(opencodeConfigDir(HOME), "plugins", "miru-search-guard.ts"),
+    legacyHooksFormat: "opencode",
     subagentPath: join(opencodeConfigDir(HOME), "agents", "miru-code.md"),
     subagentId: "opencode",
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -312,8 +310,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     ),
     instructionsPath: null,
     cursorRulesPath: null,
-    hooksPath: copilotHooksPath(HOME),
-    hooksFormat: "vscode",
+    legacyHooksPath: join(copilotHomeDir(HOME), "hooks", "miru-search.json"),
+    legacyHooksFormat: "vscode",
     subagentPath: join(copilotHomeDir(HOME), "agents", "miru-code.agent.md"),
     subagentId: "copilot",
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -333,8 +331,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     },
     instructionsPath: join(HOME, ".codex", "AGENTS.md"),
     cursorRulesPath: null,
-    hooksPath: join(HOME, ".codex", "hooks.json"),
-    hooksFormat: "claude",
+    legacyHooksPath: join(HOME, ".codex", "hooks.json"),
+    legacyHooksFormat: "claude",
     subagentPath: null,
     subagentId: null,
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -348,8 +346,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(vscodeMcpPath(), "servers", STDIO_SERVER_CONFIG),
     instructionsPath: null,
     cursorRulesPath: null,
-    hooksPath: copilotHooksPath(HOME),
-    hooksFormat: "vscode",
+    legacyHooksPath: join(copilotHomeDir(HOME), "hooks", "miru-search.json"),
+    legacyHooksFormat: "vscode",
     subagentPath: null,
     subagentId: null,
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -363,8 +361,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: null,
     instructionsPath: null,
     cursorRulesPath: null,
-    hooksPath: windsurfHooksPath(HOME),
-    hooksFormat: "windsurf",
+    legacyHooksPath: join(HOME, ".codeium", "windsurf", "hooks.json"),
+    legacyHooksFormat: "windsurf",
     subagentPath: null,
     subagentId: null,
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -378,8 +376,8 @@ export const AGENT_TARGETS: AgentTarget[] = [
     mcp: jsonMcp(visualStudioMcpPath(), "servers", STDIO_SERVER_CONFIG),
     instructionsPath: null,
     cursorRulesPath: null,
-    hooksPath: copilotHooksPath(HOME),
-    hooksFormat: "vscode",
+    legacyHooksPath: join(copilotHomeDir(HOME), "hooks", "miru-search.json"),
+    legacyHooksFormat: "vscode",
     subagentPath: null,
     subagentId: null,
     cavemanSkillPath: SHARED_CAVEMAN_SKILL,
@@ -387,38 +385,60 @@ export const AGENT_TARGETS: AgentTarget[] = [
   },
 ];
 
-async function commandOnPath(command: string): Promise<boolean> {
-  const lookup = process.platform === "win32" ? ["where", command] : ["which", command];
+async function commandOnPath(
+  command: string,
+  platform: NodeJS.Platform = process.platform,
+  spawn: typeof Bun.spawn = Bun.spawn,
+): Promise<boolean> {
+  const lookup = platform === "win32" ? ["where", command] : ["which", command];
   try {
-    const proc = Bun.spawn(lookup, { stdout: "pipe", stderr: "ignore" });
+    const proc = spawn(lookup, { stdout: "pipe", stderr: "ignore" });
     return (await proc.exited) === 0;
   } catch {
     return false;
   }
 }
 
-export async function isAgentDetected(agent: AgentTarget): Promise<boolean> {
+export interface AgentDetectionDependencies {
+  platform?: NodeJS.Platform;
+  existsSync?: typeof existsSync;
+  readdir?: (path: string) => Promise<string[]>;
+  commandOnPath?: (command: string) => Promise<boolean>;
+  spawn?: typeof Bun.spawn;
+  home?: string;
+}
+
+export async function isAgentDetected(
+  agent: AgentTarget,
+  dependencies: AgentDetectionDependencies = {},
+): Promise<boolean> {
   if (agent.id === "visualstudio") {
-    return detectVisualStudio();
+    return detectVisualStudio(dependencies);
   }
   if (agent.id === "windsurf") {
-    if (agent.configDir && existsSync(agent.configDir)) {
+    if (agent.configDir && (dependencies.existsSync ?? existsSync)(agent.configDir)) {
       return true;
     }
-    if (agent.binary && (await commandOnPath(agent.binary))) {
+    const commandExists = dependencies.commandOnPath
+      ? dependencies.commandOnPath
+      : (command: string) => commandOnPath(command, dependencies.platform, dependencies.spawn);
+    if (agent.binary && (await commandExists(agent.binary))) {
       return true;
     }
     return false;
   }
   // Copilot-specific artifacts only — ~/.copilot alone is shared with VS Code / VS.
   if (agent.id === "copilot") {
-    return isCopilotInstalled(HOME);
+    return isCopilotInstalled(dependencies.home ?? HOME);
   }
-  if (agent.binary && (await commandOnPath(agent.binary))) {
+  const commandExists = dependencies.commandOnPath
+    ? dependencies.commandOnPath
+    : (command: string) => commandOnPath(command, dependencies.platform, dependencies.spawn);
+  if (agent.binary && (await commandExists(agent.binary))) {
     return true;
   }
   if (agent.configDir) {
-    return Bun.file(agent.configDir).exists();
+    return (dependencies.existsSync ?? existsSync)(agent.configDir);
   }
   return false;
 }