@takara-ai/miru-code 0.3.0 → 0.4.0

package/src/help.ts

@@ -1,4 +1,14 @@
 import type { AgentId } from "./agents.ts";
+import {
+  brandTitle,
+  commandRow,
+  divider,
+  fail,
+  header,
+  hint,
+  section,
+  writeStdout,
+} from "./cli-ui.ts";
 
 export const AGENT_IDS: readonly AgentId[] = [
   "claude",
@@ -12,44 +22,41 @@ export const AGENT_IDS: readonly AgentId[] = [
 const AGENT_LIST = AGENT_IDS.join(", ");
 
 export function printMainHelp(): void {
-  const lines = [
-    "",
-    "Miru (見る) — hybrid code search for agents",
-    "",
-    "Usage:",
-    "  miru                         Start MCP server (stdio)",
-    "  miru <command> [options]",
-    "",
-    "Commands:",
-    "  search        Hybrid search over a codebase",
-    "  find-related  Find chunks related to a file:line",
-    "  setup         Save your Takara API key locally",
-    "  init          Write a miru-code sub-agent for your IDE",
-    "  clear         Remove cached index for a path",
-    "",
-    "Quick start:",
-    "  miru setup",
-    "  miru init --agent cursor",
-    '  miru search "auth middleware" ./src',
-    "",
-    "Run miru help <command> for details.",
-    "Run miru -h for environment variables.",
-    "",
-  ];
-  process.stdout.write(`${lines.join("\n")}\n`);
+  header("hybrid code search for agents");
+
+  section("Usage");
+  writeStdout("  miru                         Start MCP server (stdio)");
+  writeStdout("  miru <command> [options]");
+  divider();
+
+  section("Commands");
+  commandRow("search", "Hybrid search over a codebase");
+  commandRow("find-related", "Find chunks related to a file:line");
+  commandRow("setup", "Save your Takara API key locally");
+  commandRow("install", "Configure miru across coding agents");
+  commandRow("uninstall", "Remove miru agent configuration");
+  commandRow("init", "Write a project-local sub-agent file");
+  commandRow("clear", "Remove cached index for a path");
+  commandRow("help", "Show help for a command");
+  divider();
+
+  section("Quick start");
+  writeStdout("  miru setup && miru install");
+  writeStdout('  miru search "auth middleware" ./src');
+  writeStdout("");
+  hint("miru help <command>  ·  miru -h for environment variables");
+  writeStdout("");
 }
 
 export function printEnvHelp(): void {
-  const lines = [
-    "",
-    "Environment:",
-    "  TAKARA_API_KEY",
-    "      Takara bearer token for embeddings",
-    "  MIRU_OPENAI_BASE_URL",
-    "      Default: infer.dev.takara.ai",
-    "",
-  ];
-  process.stdout.write(`${lines.join("\n")}\n`);
+  section("Environment");
+  writeStdout("  TAKARA_API_KEY");
+  writeStdout("      Takara bearer token for embeddings");
+  writeStdout("  MIRU_OPENAI_BASE_URL");
+  writeStdout("      Default: https://infer.dev.takara.ai/v1");
+  writeStdout("  MIRU_CONCURRENCY");
+  writeStdout("      Parallel workers (default: CPUs − 2)");
+  writeStdout("");
 }
 
 export function printFullHelp(): void {
@@ -57,117 +64,95 @@ export function printFullHelp(): void {
   printEnvHelp();
 }
 
+function printCommandHeader(name: string, summary: string): void {
+  writeStdout("");
+  writeStdout(`${brandTitle()} ${name}`);
+  writeStdout(summary);
+  divider();
+}
+
 export function printCommandHelp(command: string): void {
   switch (command) {
     case "search":
-      process.stdout.write(
-        [
-          "",
-          "miru search — hybrid search",
-          "",
-          "Usage:",
-          "  miru search <query> [path] [-k N] [--content TYPE ...]",
-          "",
-          "Options:",
-          "  -k, --top-k N       Number of results (default: 5)",
-          "  --content TYPE      code | docs | config | all (default: code)",
-          "",
-          "Example:",
-          '  miru search "where is auth" ./src -k 10 --content code docs',
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("search", "Hybrid semantic + keyword search.");
+      section("Usage");
+      writeStdout("  miru search <query> [path] [options]");
+      section("Options");
+      writeStdout("  -k, --top-k N       Number of results (default: 5)");
+      writeStdout("  --content TYPE      code | docs | config | all");
+      writeStdout("  --json              JSON output (default when piped)");
+      section("Example");
+      writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
+      writeStdout("");
       return;
     case "find-related":
-      process.stdout.write(
-        [
-          "",
-          "miru find-related — related chunks",
-          "",
-          "Usage:",
-          "  miru find-related <file> <line> [path] [-k N] [--content TYPE ...]",
-          "",
-          "Example:",
-          "  miru find-related src/auth.ts 42 . -k 8",
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("find-related", "Semantic neighbors of a file location.");
+      section("Usage");
+      writeStdout("  miru find-related <file> <line> [path] [options]");
+      section("Example");
+      writeStdout("  miru find-related src/auth.ts 42 . -k 8");
+      writeStdout("");
       return;
     case "setup":
-      process.stdout.write(
-        [
-          "",
-          "miru setup — store API key",
-          "",
-          "Usage:",
-          "  miru setup",
-          "  miru setup --key TOKEN",
-          "  miru setup --force",
-          "  miru setup --clear",
-          "",
-          "Options:",
-          "  --key, -k TOKEN     Provide key on the command line (non-interactive)",
-          "  --force             Replace an existing stored key",
-          "  --clear             Remove stored credentials",
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("setup", "Store and validate your Takara API key.");
+      section("Usage");
+      writeStdout("  miru setup [--key TOKEN] [--force] [--clear]");
+      section("Options");
+      writeStdout("  --key, -k TOKEN     Non-interactive key entry");
+      writeStdout("  --force             Replace an existing stored key");
+      writeStdout("  --clear             Remove stored credentials");
+      writeStdout("");
+      return;
+    case "install":
+      printCommandHeader("install", "Interactive global agent setup.");
+      writeStdout("Configures MCP server, instructions, and sub-agent files under");
+      writeStdout("your user config (~/.claude, ~/.cursor, etc.).");
+      writeStdout("");
+      writeStdout("Run miru setup first, or set TAKARA_API_KEY for MCP env expansion.");
+      writeStdout("");
+      return;
+    case "uninstall":
+      printCommandHeader("uninstall", "Remove miru configuration from agents.");
+      writeStdout("Removes MCP entries, marked instruction blocks, and global sub-agents.");
+      writeStdout("");
       return;
     case "init":
-      process.stdout.write(
-        [
-          "",
-          "miru init — IDE sub-agent file",
-          "",
-          "Usage:",
-          "  miru init --agent AGENT [--force]",
-          "",
-          "Agents:",
-          `  ${AGENT_LIST}`,
-          "",
-          "Examples:",
-          "  miru init --agent cursor",
-          "  miru init --agent claude --force",
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("init", "Project-local sub-agent file.");
+      writeStdout("Prefer miru install for global setup. Use init to commit into a repo.");
+      section("Usage");
+      writeStdout("  miru init --agent AGENT [--force]");
+      section("Agents");
+      writeStdout(`  ${AGENT_LIST}`);
+      section("Example");
+      writeStdout("  miru init --agent claude --force");
+      writeStdout("");
       return;
     case "clear":
-      process.stdout.write(
-        [
-          "",
-          "miru clear — drop cached index",
-          "",
-          "Usage:",
-          "  miru clear [path]",
-          "",
-          "Example:",
-          "  miru clear .",
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("clear", "Drop the on-disk index cache.");
+      section("Usage");
+      writeStdout("  miru clear [path]");
+      section("Example");
+      writeStdout("  miru clear .");
+      writeStdout("");
       return;
     case "mcp":
-      process.stdout.write(
-        [
-          "",
-          "miru — MCP server (default with no subcommand)",
-          "",
-          "Usage:",
-          "  miru [--ref BRANCH] [--content TYPE ...]",
-          "",
-          "Indexes a repo on the first search/find_related tool call (repo argument).",
-          "With no path, uses the process working directory.",
-          "",
-        ].join("\n"),
-      );
+      printCommandHeader("mcp", "Stdio MCP server (default with no subcommand).");
+      section("Usage");
+      writeStdout("  miru [--ref BRANCH] [--content TYPE ...]");
+      writeStdout("");
+      writeStdout("Indexes on the first search/find_related tool call (repo argument).");
+      writeStdout("");
       return;
     default:
-      process.stderr.write(`Unknown command: ${command}\n\n`);
-      printMainHelp();
-      process.exit(1);
+      failHelp(command);
   }
-  process.stdout.write("\n");
+}
+
+function failHelp(command: string): never {
+  fail(`Unknown command: ${command}`);
+  writeStdout("");
+  printMainHelp();
+  process.exit(1);
 }
 
 export function formatUnknownAgent(agent: string): string {

package/src/installer/agents.ts

@@ -0,0 +1,246 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentId } from "../agents.ts";
+
+export type InstallAction =
+  | "created"
+  | "updated"
+  | "unchanged"
+  | "not-found"
+  | "removed"
+  | "error"
+  | "skipped";
+
+export type InstallMode = "install" | "uninstall";
+
+export const MIRU_START = "<!-- miru:start -->";
+export const MIRU_END = "<!-- miru:end -->";
+
+const HOME = homedir();
+
+const TAKARA_KEY_PLACEHOLDER = "$" + "{TAKARA_API_KEY}";
+
+const MCP_ENV: Record<string, string> = {
+  TAKARA_API_KEY: TAKARA_KEY_PLACEHOLDER,
+};
+
+const STDIO_SERVER_CONFIG: Record<string, unknown> = {
+  command: "bunx",
+  args: ["@takara-ai/miru-code"],
+  type: "stdio",
+  env: MCP_ENV,
+};
+
+const BARE_STDIO_SERVER_CONFIG: Record<string, unknown> = {
+  command: "bunx",
+  args: ["@takara-ai/miru-code"],
+  env: MCP_ENV,
+};
+
+const OPENCODE_SERVER_CONFIG: Record<string, unknown> = {
+  command: ["bunx", "@takara-ai/miru-code"],
+  type: "local",
+  enabled: true,
+  environment: MCP_ENV,
+};
+
+export const INSTRUCTIONS = `${MIRU_START}
+## Miru Code Search
+
+A \`miru\` MCP server is available with two tools:
+- \`search\` — search the codebase with a natural-language or code query.
+- \`find_related\` — find code similar to a specific file and line.
+
+Always call \`search\` before using Grep, Glob, or Read to explore the codebase. Use Grep/Glob/Read only for exact path lookup, exhaustive literal matches, or when the returned chunk lacks enough context.
+
+Set \`TAKARA_API_KEY\` in your MCP config (or run \`miru setup\` for CLI use). MCP does not inherit shell env reliably.
+
+Pass \`--content docs\` to search documentation, \`--content config\` for config files, or \`--content all\` for everything.
+
+For CLI fallback or sub-agents without MCP access:
+
+\`\`\`bash
+miru search "authentication flow" ./my-project
+miru search "deployment guide" ./my-project --content docs
+miru find-related src/auth.ts 42 ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+\`\`\`
+
+First run builds a disk cache. The MCP server updates local indexes while it runs; after CLI-only use or large refactors, run \`miru clear <path>\`.
+
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\` in its place.
+
+### Workflow
+
+1. Start with \`search\` (MCP) or \`miru search\` (CLI) to find relevant chunks.
+2. Use \`--content docs\` / \`--content config\` / \`--content all\` when appropriate.
+3. Inspect full files only when the chunk is not enough.
+4. Optionally use \`find_related\` with a hit's \`file_path\` and \`line\`.
+5. Use Grep only for exhaustive literal matches.
+${MIRU_END}
+`;
+
+export type McpConfigFormat = "json" | "toml";
+
+export interface McpConfig {
+  path: string;
+  key: string;
+  memberKey: string;
+  entry: Record<string, unknown>;
+  format: McpConfigFormat;
+}
+
+export interface AgentTarget {
+  id: AgentId | "codex" | "vscode";
+  displayName: string;
+  binary: string | null;
+  configDir: string | null;
+  mcp: McpConfig | null;
+  instructionsPath: string | null;
+  subagentPath: string | null;
+  subagentId: AgentId | null;
+}
+
+export function opencodeMcpPath(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg ? join(xdg, "opencode") : join(HOME, ".config", "opencode");
+  const jsonc = join(base, "opencode.jsonc");
+  const json = join(base, "opencode.json");
+  if (existsSync(jsonc)) {
+    return jsonc;
+  }
+  if (existsSync(json)) {
+    return json;
+  }
+  return jsonc;
+}
+
+export function vscodeMcpPath(): string {
+  if (process.platform === "darwin") {
+    return join(HOME, "Library", "Application Support", "Code", "User", "mcp.json");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA ?? HOME;
+    return join(appData, "Code", "User", "mcp.json");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(HOME, ".config");
+  return join(xdg, "Code", "User", "mcp.json");
+}
+
+function jsonMcp(path: string, key: string, entry: Record<string, unknown>): McpConfig {
+  return { path, key, memberKey: "miru", entry, format: "json" };
+}
+
+export const AGENT_TARGETS: AgentTarget[] = [
+  {
+    id: "claude",
+    displayName: "Claude Code",
+    binary: "claude",
+    configDir: join(HOME, ".claude"),
+    mcp: jsonMcp(join(HOME, ".claude.json"), "mcpServers", STDIO_SERVER_CONFIG),
+    instructionsPath: join(HOME, ".claude", "CLAUDE.md"),
+    subagentPath: join(HOME, ".claude", "agents", "miru-code.md"),
+    subagentId: "claude",
+  },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    binary: "cursor",
+    configDir: join(HOME, ".cursor"),
+    mcp: jsonMcp(join(HOME, ".cursor", "mcp.json"), "mcpServers", STDIO_SERVER_CONFIG),
+    instructionsPath: null,
+    subagentPath: join(HOME, ".cursor", "agents", "miru-code.md"),
+    subagentId: "cursor",
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    binary: "gemini",
+    configDir: join(HOME, ".gemini"),
+    mcp: jsonMcp(join(HOME, ".gemini", "settings.json"), "mcpServers", STDIO_SERVER_CONFIG),
+    instructionsPath: join(HOME, ".gemini", "GEMINI.md"),
+    subagentPath: join(HOME, ".gemini", "agents", "miru-code.md"),
+    subagentId: "gemini",
+  },
+  {
+    id: "kiro",
+    displayName: "Kiro",
+    binary: "kiro",
+    configDir: join(HOME, ".kiro"),
+    mcp: jsonMcp(join(HOME, ".kiro", "settings", "mcp.json"), "mcpServers", {
+      ...STDIO_SERVER_CONFIG,
+      env: {
+        ...MCP_ENV,
+        PATH: "/usr/local/bin:/usr/bin:/bin",
+      },
+    }),
+    instructionsPath: join(HOME, ".kiro", "steering", "miru.md"),
+    subagentPath: join(HOME, ".kiro", "agents", "miru-code.md"),
+    subagentId: "kiro",
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    binary: "opencode",
+    configDir: join(HOME, ".config", "opencode"),
+    mcp: jsonMcp(opencodeMcpPath(), "mcp", OPENCODE_SERVER_CONFIG),
+    instructionsPath: join(HOME, ".config", "opencode", "AGENTS.md"),
+    subagentPath: join(HOME, ".config", "opencode", "agents", "miru-code.md"),
+    subagentId: "opencode",
+  },
+  {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    binary: null,
+    configDir: join(HOME, ".config", "github-copilot"),
+    mcp: jsonMcp(join(HOME, ".copilot", "mcp-config.json"), "mcpServers", BARE_STDIO_SERVER_CONFIG),
+    instructionsPath: null,
+    subagentPath: join(HOME, ".copilot", "agents", "miru-code.agent.md"),
+    subagentId: "copilot",
+  },
+  {
+    id: "codex",
+    displayName: "Codex",
+    binary: "codex",
+    configDir: join(HOME, ".codex"),
+    mcp: {
+      path: join(HOME, ".codex", "config.toml"),
+      key: "mcp_servers",
+      memberKey: "miru",
+      entry: {},
+      format: "toml",
+    },
+    instructionsPath: join(HOME, ".codex", "AGENTS.md"),
+    subagentPath: null,
+    subagentId: null,
+  },
+  {
+    id: "vscode",
+    displayName: "VS Code",
+    binary: "code",
+    configDir: null,
+    mcp: jsonMcp(vscodeMcpPath(), "servers", STDIO_SERVER_CONFIG),
+    instructionsPath: null,
+    subagentPath: null,
+    subagentId: null,
+  },
+];
+
+export async function isAgentDetected(agent: AgentTarget): Promise<boolean> {
+  if (agent.binary) {
+    try {
+      const proc = Bun.spawn(["which", agent.binary], { stdout: "pipe", stderr: "ignore" });
+      const code = await proc.exited;
+      if (code === 0) {
+        return true;
+      }
+    } catch {
+      // which unavailable
+    }
+  }
+  if (agent.configDir) {
+    return Bun.file(agent.configDir).exists();
+  }
+  return false;
+}