@takara-ai/miru-code 0.4.5 → 0.4.9

package/src/installer/hooks/search-guard.ts

@@ -0,0 +1,215 @@
+const REDIRECT_MESSAGE =
+  "Use Miru MCP `search` (pass project root as `repo`) instead of built-in search tools. " +
+  "Grep/Glob/Shell are only for exact literal confirmation or non-code tasks.";
+
+const MIRU_TOOL_RE = /miru/i;
+
+const GREP_TOOL_RE = /^(grep|grep_search|Grep)$/i;
+const GLOB_TOOL_RE = /^(glob|glob_file_search|Glob)$/i;
+const SEMANTIC_TOOL_RE = /^(SemanticSearch|codebase_search)$/i;
+const SHELL_TOOL_RE = /^(Shell|Bash|execute_bash|shell)$/i;
+
+/** Returns true when a grep pattern looks like an exact literal lookup. */
+export function isLiteralGrepPattern(pattern: string): boolean {
+  const trimmed = pattern.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (/^[`'"][^`'"]+[`'"]$/.test(trimmed)) {
+    return true;
+  }
+  if (/^[A-Z][A-Z0-9_]{2,}$/.test(trimmed)) {
+    return true;
+  }
+  if (/^[a-f0-9-]{36}$/i.test(trimmed)) {
+    return true;
+  }
+  if (/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed) && trimmed.length <= 48) {
+    return true;
+  }
+  return false;
+}
+
+/** Shell commands that look like codebase exploration rather than builds/tests. */
+export function isExplorationShell(command: string): boolean {
+  const cmd = command.trim();
+  if (!cmd) {
+    return false;
+  }
+  if (
+    /\b(git|npm|bun|pnpm|yarn|cargo|go|make|cmake|docker|kubectl|pytest|jest|vitest)\b/.test(cmd)
+  ) {
+    return false;
+  }
+  return /\b(rg|ripgrep|grep|find|ag|ack|fd|locate)\b/.test(cmd);
+}
+
+export type HookPayload = {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  hook_event_name?: string;
+  agent_action_name?: string;
+  tool_info?: Record<string, unknown>;
+};
+
+export type GuardDecision = {
+  block: boolean;
+  reason: string;
+};
+
+export type HookResponseFormat = "claude" | "gemini" | "cursor" | "stderr";
+
+function grepPatternFromInput(toolInput: Record<string, unknown>): string {
+  return String(
+    toolInput.pattern ??
+      toolInput.query ??
+      toolInput.regex ??
+      toolInput.needle ??
+      toolInput.search_term ??
+      "",
+  );
+}
+
+/** Map host-specific stdin JSON into a common evaluation shape. */
+export function normalizeHookPayload(raw: Record<string, unknown>): HookPayload {
+  const agentAction = raw.agent_action_name;
+  if (typeof agentAction === "string") {
+    const toolInfo =
+      raw.tool_info && typeof raw.tool_info === "object" && !Array.isArray(raw.tool_info)
+        ? (raw.tool_info as Record<string, unknown>)
+        : {};
+    if (agentAction === "pre_run_command") {
+      return {
+        hook_event_name: "windsurf_pre_run_command",
+        tool_name: "Shell",
+        tool_input: { command: toolInfo.command_line ?? "" },
+      };
+    }
+  }
+
+  return {
+    tool_name: typeof raw.tool_name === "string" ? raw.tool_name : undefined,
+    tool_input:
+      raw.tool_input && typeof raw.tool_input === "object" && !Array.isArray(raw.tool_input)
+        ? (raw.tool_input as Record<string, unknown>)
+        : {},
+    hook_event_name: typeof raw.hook_event_name === "string" ? raw.hook_event_name : undefined,
+    agent_action_name:
+      typeof raw.agent_action_name === "string" ? raw.agent_action_name : undefined,
+    tool_info:
+      raw.tool_info && typeof raw.tool_info === "object" && !Array.isArray(raw.tool_info)
+        ? (raw.tool_info as Record<string, unknown>)
+        : undefined,
+  };
+}
+
+export function evaluateSearchGuard(payload: HookPayload): GuardDecision {
+  const toolName = String(payload.tool_name ?? "");
+  const toolInput = payload.tool_input ?? {};
+
+  if (!toolName || MIRU_TOOL_RE.test(toolName)) {
+    return { block: false, reason: "" };
+  }
+
+  if (GREP_TOOL_RE.test(toolName)) {
+    const pattern = grepPatternFromInput(toolInput);
+    if (isLiteralGrepPattern(pattern)) {
+      return { block: false, reason: "" };
+    }
+    return { block: true, reason: REDIRECT_MESSAGE };
+  }
+
+  if (GLOB_TOOL_RE.test(toolName)) {
+    return { block: true, reason: REDIRECT_MESSAGE };
+  }
+
+  if (SEMANTIC_TOOL_RE.test(toolName)) {
+    return { block: true, reason: REDIRECT_MESSAGE };
+  }
+
+  if (SHELL_TOOL_RE.test(toolName)) {
+    const command = String(toolInput.command ?? toolInput.cmd ?? "");
+    if (isExplorationShell(command)) {
+      return { block: true, reason: REDIRECT_MESSAGE };
+    }
+    return { block: false, reason: "" };
+  }
+
+  return { block: false, reason: "" };
+}
+
+export function hookResponseFormat(payload: HookPayload): HookResponseFormat {
+  const event = payload.hook_event_name ?? "";
+  if (event === "PreToolUse") {
+    return "claude";
+  }
+  if (event === "BeforeTool") {
+    return "gemini";
+  }
+  if (event === "preToolUse" || event === "windsurf_pre_run_command") {
+    return "stderr";
+  }
+  return "cursor";
+}
+
+export function claudeHookResponse(reason: string): string {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
+export function geminiHookResponse(reason: string): string {
+  return JSON.stringify({
+    decision: "deny",
+    reason,
+  });
+}
+
+export function cursorHookResponse(reason: string): string {
+  return JSON.stringify({
+    permission: "deny",
+    agent_message: reason,
+    user_message: "Miru: use MCP search instead of built-in grep/glob.",
+  });
+}
+
+export async function runSearchGuardFromStdin(): Promise<number> {
+  const text = await Bun.stdin.text();
+  if (!text.trim()) {
+    return 0;
+  }
+
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return 0;
+  }
+
+  const payload = normalizeHookPayload(raw);
+  const decision = evaluateSearchGuard(payload);
+  if (!decision.block) {
+    return 0;
+  }
+
+  const format = hookResponseFormat(payload);
+  if (format === "claude") {
+    process.stdout.write(claudeHookResponse(decision.reason));
+    return 0;
+  }
+  if (format === "gemini") {
+    process.stdout.write(geminiHookResponse(decision.reason));
+    return 0;
+  }
+  if (format === "stderr") {
+    process.stderr.write(decision.reason);
+    return 2;
+  }
+
+  process.stdout.write(cursorHookResponse(decision.reason));
+  return 2;
+}

package/src/installer/installer.ts

@@ -19,14 +19,16 @@ import {
   removeTomlBlock,
   replaceOrAppendMarked,
 } from "./config.ts";
+import { mergeHooks, removeHooks } from "./hooks/install.ts";
 import { promptConfirm, promptMultiSelect, requireInteractiveTerminal } from "./prompt.ts";
+import { CURSOR_RULES_MDC } from "./search-policy.ts";
 
 export interface WriteResult {
   path: string;
   action: InstallAction;
 }
 
-export type IntegrationId = "mcp" | "instructions" | "subagent";
+export type IntegrationId = "mcp" | "instructions" | "subagent" | "hooks" | "rules";
 
 interface Integration {
   id: IntegrationId;
@@ -84,6 +86,42 @@ async function applyInstructions(
   return { path, action };
 }
 
+async function applyHooks(agent: AgentTarget, mode: InstallMode): Promise<WriteResult | null> {
+  const path = agent.hooksPath;
+  const format = agent.hooksFormat;
+  if (!path || !format) {
+    return null;
+  }
+
+  const action =
+    mode === "install" ? await mergeHooks(format, path) : await removeHooks(format, path);
+
+  return { path, action };
+}
+
+async function applyCursorRules(
+  agent: AgentTarget,
+  mode: InstallMode,
+): Promise<WriteResult | null> {
+  const path = agent.cursorRulesPath;
+  if (!path) {
+    return null;
+  }
+
+  if (mode === "uninstall") {
+    if (!(await Bun.file(path).exists())) {
+      return { path, action: "not-found" };
+    }
+    await unlink(path);
+    return { path, action: "removed" };
+  }
+
+  const existed = await Bun.file(path).exists();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${CURSOR_RULES_MDC.trim()}\n`, "utf-8");
+  return { path, action: existed ? "updated" : "created" };
+}
+
 async function applySubagent(agent: AgentTarget, mode: InstallMode): Promise<WriteResult | null> {
   const dest = agent.subagentPath;
   const templateId = agent.subagentId;
@@ -132,6 +170,20 @@ const INTEGRATIONS: Integration[] = [
     planPath: (agent) => agent.subagentPath,
     apply: applySubagent,
   },
+  {
+    id: "rules",
+    label: "Cursor rules",
+    description: "always-on .cursor/rules policy for code search",
+    planPath: (agent) => agent.cursorRulesPath,
+    apply: applyCursorRules,
+  },
+  {
+    id: "hooks",
+    label: "Search hooks",
+    description: "blocks Grep/Glob and redirects agents to Miru MCP",
+    planPath: (agent) => agent.hooksPath,
+    apply: applyHooks,
+  },
 ];
 
 function formatActionLine(integration: Integration, result: WriteResult): string {
@@ -191,7 +243,7 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
   writeStdout("");
   writeStdout(`${brandTitle()}${install ? " installer" : " uninstaller"}`);
   divider();
-  hint("Select agents and integrations to configure.");
+  hint("↑↓ move  space select  enter confirm");
 
   const detected = await Promise.all(
     AGENT_TARGETS.map(async (agent) => ({
@@ -246,12 +298,13 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
     install ? "Done! Restart your agents to pick up changes." : "Done! Configuration removed.",
   );
   if (install) {
-    hint("Run miru setup — MCP loads the key from credentials.json automatically.");
+    hint("Restart agents after install. Hooks block built-in search in favor of Miru MCP.");
   }
   writeStdout("");
 }
 
 export {
+  applyHooks,
   applyInstructions,
   applyMcp,
   applySubagent,

package/src/installer/prompt.ts

@@ -1,6 +1,6 @@
 import { stdin as input, stdout as output } from "node:process";
 import * as readline from "node:readline/promises";
-import { bold, cyan, dim, divider, hint, warn } from "../cli-ui.ts";
+import { bold, cyan, dim, divider, green, hint, warn } from "../cli-ui.ts";
 
 export function requireInteractiveTerminal(command: string): void {
   if (!input.isTTY) {
@@ -11,27 +11,208 @@ export function requireInteractiveTerminal(command: string): void {
   }
 }
 
-async function readLine(prompt: string): Promise<string> {
-  const rl = readline.createInterface({ input, output });
+const ESC = "\x1b";
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+const CLEAR_LINE = `${ESC}[2K`;
+
+function writeRaw(text: string): void {
+  output.write(text);
+}
+
+function readKey(): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const onData = (chunk: Buffer) => {
+      cleanup();
+      resolve(chunk);
+    };
+    const onError = (err: Error) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      input.off("data", onData);
+      input.off("error", onError);
+    };
+    input.once("data", onData);
+    input.once("error", onError);
+  });
+}
+
+function parseKey(chunk: Buffer): string {
+  const text = chunk.toString("utf8");
+  if (chunk.length >= 3 && chunk[0] === 0x1b && chunk[1] === 0x5b) {
+    const code = chunk[2];
+    if (code === 0x41) {
+      return "up";
+    }
+    if (code === 0x42) {
+      return "down";
+    }
+    if (code === 0x43) {
+      return "right";
+    }
+    if (code === 0x44) {
+      return "left";
+    }
+  }
+  if (text === "\r" || text === "\n") {
+    return "enter";
+  }
+  if (text === " ") {
+    return "space";
+  }
+  if (text === "\x03") {
+    return "ctrl-c";
+  }
+  if (text === "a" || text === "A") {
+    return "all";
+  }
+  if (text === "y" || text === "Y") {
+    return "yes";
+  }
+  if (text === "n" || text === "N") {
+    return "no";
+  }
+  return text;
+}
+
+async function withRawMode<T>(fn: () => Promise<T>): Promise<T> {
+  input.setRawMode(true);
+  input.resume();
+  writeRaw(HIDE_CURSOR);
   try {
-    return (await rl.question(prompt)).trim();
+    return await fn();
   } finally {
-    rl.close();
+    writeRaw(SHOW_CURSOR);
+    input.setRawMode(false);
+    input.pause();
   }
 }
 
-export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
-  const hintText = defaultYes ? dim("[Y/n]") : dim("[y/N]");
-  const answer = (await readLine(`${question} ${hintText} `)).toLowerCase();
-  if (!answer) {
-    return defaultYes;
+function renderMultiSelect<T>(
+  title: string,
+  items: Array<{ label: string; value: T; checked: boolean }>,
+  cursor: number,
+  footer: string,
+): void {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(bold(title));
+  lines.push(dim("─".repeat(48)));
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    if (!item) {
+      continue;
+    }
+    const selected = i === cursor;
+    const pointer = selected ? cyan("›") : " ";
+    const mark = item.checked ? cyan("[x]") : dim("[ ]");
+    const label = selected ? bold(item.label) : item.label;
+    lines.push(`  ${pointer} ${mark} ${label}`);
   }
-  return answer === "y" || answer === "yes";
+  lines.push("");
+  lines.push(dim(footer));
+  writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
 }
 
 export async function promptMultiSelect<T>(
   title: string,
   items: Array<{ label: string; value: T; checked: boolean }>,
+): Promise<T[] | null> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  if (!input.isTTY) {
+    return items.filter((item) => item.checked).map((item) => item.value);
+  }
+
+  const footer = "↑↓ move  space toggle  a all  enter confirm  ctrl-c cancel";
+  let cursor = 0;
+
+  return withRawMode(async () => {
+    while (true) {
+      renderMultiSelect(title, items, cursor, footer);
+      const key = parseKey(await readKey());
+
+      if (key === "ctrl-c") {
+        writeRaw("\n");
+        return null;
+      }
+      if (key === "enter") {
+        writeRaw("\n");
+        return items.filter((item) => item.checked).map((item) => item.value);
+      }
+      if (key === "up") {
+        cursor = Math.max(0, cursor - 1);
+      } else if (key === "down") {
+        cursor = Math.min(items.length - 1, cursor + 1);
+      } else if (key === "space") {
+        const item = items[cursor];
+        if (item) {
+          item.checked = !item.checked;
+        }
+      } else if (key === "all") {
+        const allChecked = items.every((item) => item.checked);
+        for (const item of items) {
+          item.checked = !allChecked;
+        }
+      }
+    }
+  });
+}
+
+function renderConfirm(question: string, yesSelected: boolean): void {
+  const yes = yesSelected ? green(bold(" Yes ")) : dim(" Yes ");
+  const no = yesSelected ? dim(" No ") : green(bold(" No "));
+  writeRaw(`${CLEAR_LINE}${question}  ${yes} / ${no}\n`);
+  writeRaw(`${CLEAR_LINE}${dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel")}\n`);
+}
+
+export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
+  if (!input.isTTY) {
+    const rl = readline.createInterface({ input, output });
+    try {
+      const hintText = defaultYes ? dim("[Y/n]") : dim("[y/N]");
+      const answer = (await rl.question(`${question} ${hintText} `)).trim().toLowerCase();
+      if (!answer) {
+        return defaultYes;
+      }
+      return answer === "y" || answer === "yes";
+    } finally {
+      rl.close();
+    }
+  }
+
+  let yesSelected = defaultYes;
+
+  return withRawMode(async () => {
+    while (true) {
+      renderConfirm(question, yesSelected);
+      const key = parseKey(await readKey());
+
+      if (key === "ctrl-c") {
+        writeRaw("\n");
+        return false;
+      }
+      if (key === "enter") {
+        writeRaw("\n");
+        return yesSelected;
+      }
+      if (key === "left" || key === "no") {
+        yesSelected = false;
+      } else if (key === "right" || key === "yes") {
+        yesSelected = true;
+      }
+    }
+  });
+}
+
+/** Legacy numbered prompt kept for non-TTY fallback in tests. */
+export async function promptMultiSelectLegacy<T>(
+  title: string,
+  items: Array<{ label: string; value: T; checked: boolean }>,
 ): Promise<T[] | null> {
   output.write("\n");
   output.write(`${bold(title)}\n`);
@@ -49,29 +230,34 @@ export async function promptMultiSelect<T>(
   output.write("\n");
   hint("Enter numbers (1,3), 'all', or press Enter for defaults", output);
 
-  const answer = (await readLine(`${dim("> ")}`)).toLowerCase();
-  if (!answer) {
-    return items.filter((item) => item.checked).map((item) => item.value);
-  }
-  if (answer === "all" || answer === "a") {
-    return items.map((item) => item.value);
-  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${dim("> ")}`)).toLowerCase();
+    if (!answer) {
+      return items.filter((item) => item.checked).map((item) => item.value);
+    }
+    if (answer === "all" || answer === "a") {
+      return items.map((item) => item.value);
+    }
 
-  const indices = new Set<number>();
-  for (const part of answer.split(/[,\s]+/)) {
-    const n = Number(part);
-    if (Number.isInteger(n) && n >= 1 && n <= items.length) {
-      indices.add(n - 1);
+    const indices = new Set<number>();
+    for (const part of answer.split(/[,\s]+/)) {
+      const n = Number(part);
+      if (Number.isInteger(n) && n >= 1 && n <= items.length) {
+        indices.add(n - 1);
+      }
     }
-  }
 
-  if (indices.size === 0) {
-    warn("No valid selection.", output);
-    return null;
-  }
+    if (indices.size === 0) {
+      warn("No valid selection.", output);
+      return null;
+    }
 
-  return [...indices]
-    .sort((a, b) => a - b)
-    .map((i) => items[i]?.value)
-    .filter((value): value is T => value !== undefined);
+    return [...indices]
+      .sort((a, b) => a - b)
+      .map((i) => items[i]?.value)
+      .filter((value): value is T => value !== undefined);
+  } finally {
+    rl.close();
+  }
 }

package/src/installer/search-policy.ts

@@ -0,0 +1,68 @@
+/** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
+
+export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
+|------|-----|-----|
+| How/where/what handles X? | Miru MCP \`search\` | Grep, Glob, SemanticSearch, Read |
+| Similar code elsewhere | Miru MCP \`find_related\` | Read whole files |
+| Search docs or config | Miru \`search\` with \`content\` | Grep README paths |
+| Exact literal exists? | Grep | Miru |
+| Edit a known file:line | Read (after Miru found it) | Read-before-search |`;
+
+export const SEARCH_POLICY_BODY = `DO NOT use Grep, Glob, SemanticSearch, or Read to explore how code works when Miru MCP is available.
+
+Use Miru MCP tools first:
+- \`search\` — natural-language or code query; pass project root as \`repo\`
+- \`find_related\` — similar chunks after a \`search\` hit (\`file_path\` + \`line\`)
+
+Native tools are allowed ONLY when:
+- confirming an exact literal string (env var name, error code, quoted text)
+- reading a file you already located via Miru, to edit it
+- searching outside the indexed repo
+
+${SEARCH_POLICY_TABLE}`;
+
+export const INSTRUCTIONS_MARKDOWN = `## Miru Code Search
+
+${SEARCH_POLICY_BODY}
+
+Run \`miru setup\` once — the MCP server loads your API key from \`credentials.json\`.
+
+CLI fallback when MCP is unavailable:
+
+\`\`\`bash
+miru search "authentication flow" .
+miru find-related src/auth.ts 42 .
+\`\`\`
+
+After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+
+export const CURSOR_RULES_MDC = `---
+description: Miru MCP is the default for all code exploration
+alwaysApply: true
+---
+
+# Code search policy (Miru)
+
+${SEARCH_POLICY_BODY}
+
+When Miru MCP is connected, call \`search\` before any built-in search tool. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+
+export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\` and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
+
+${SEARCH_POLICY_BODY}
+
+### MCP workflow
+
+1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
+2. Use returned \`file_path\` and \`line\` from hits; call \`find_related\` to explore neighbors.
+3. Read files only when a chunk lacks context or you are about to edit.
+
+### CLI fallback (no MCP in this session)
+
+\`\`\`bash
+miru search "authentication flow" .
+miru find-related src/auth.ts 42 .
+\`\`\`
+
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;