@takara-ai/miru-code 0.2.0 → 0.4.0

package/src/help.ts

@@ -0,0 +1,160 @@
+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",
+  "copilot",
+  "cursor",
+  "gemini",
+  "kiro",
+  "opencode",
+] as const;
+
+const AGENT_LIST = AGENT_IDS.join(", ");
+
+export function printMainHelp(): void {
+  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 {
+  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 {
+  printMainHelp();
+  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":
+      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":
+      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":
+      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":
+      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":
+      printCommandHeader("clear", "Drop the on-disk index cache.");
+      section("Usage");
+      writeStdout("  miru clear [path]");
+      section("Example");
+      writeStdout("  miru clear .");
+      writeStdout("");
+      return;
+    case "mcp":
+      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:
+      failHelp(command);
+  }
+}
+
+function failHelp(command: string): never {
+  fail(`Unknown command: ${command}`);
+  writeStdout("");
+  printMainHelp();
+  process.exit(1);
+}
+
+export function formatUnknownAgent(agent: string): string {
+  return `Unknown agent "${agent}". Choose one of: ${AGENT_LIST}`;
+}

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;
+}

package/src/installer/config.ts

@@ -0,0 +1,273 @@
+import { mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { type InstallAction, MIRU_END, MIRU_START } from "./agents.ts";
+
+const CODEX_MCP_HEADER = "[mcp_servers.miru]";
+const CODEX_MCP_BLOCK = `[mcp_servers.miru]
+command = "bunx"
+args = ["@takara-ai/miru-code"]
+env = { TAKARA_API_KEY = "\${TAKARA_API_KEY}" }
+`;
+
+/** Strip line and block comments so JSONC configs can be parsed. */
+export function stripJsonComments(text: string): string {
+  let out = "";
+  let i = 0;
+  let inString = false;
+  let stringQuote = '"';
+  while (i < text.length) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (ch === "\\" && next !== undefined) {
+        out += next;
+        i += 2;
+        continue;
+      }
+      if (ch === stringQuote) {
+        inString = false;
+      }
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringQuote = ch;
+      out += ch;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") {
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) {
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | "error" {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(stripJsonComments(trimmed));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return "error";
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return "error";
+  }
+}
+
+function sectionObject(
+  root: Record<string, unknown>,
+  sectionKey: string,
+): Record<string, unknown> | "error" {
+  const section = root[sectionKey];
+  if (section === undefined) {
+    return {};
+  }
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    return "error";
+  }
+  return section as Record<string, unknown>;
+}
+
+export async function mergeJsonMember(
+  path: string,
+  sectionKey: string,
+  memberKey: string,
+  value: Record<string, unknown>,
+): Promise<InstallAction> {
+  const existed = await Bun.file(path).exists();
+  const text = existed ? await Bun.file(path).text() : "";
+  const parsed = parseJsonObject(text);
+  if (parsed === "error") {
+    return "error";
+  }
+
+  const section = sectionObject(parsed, sectionKey);
+  if (section === "error") {
+    return "error";
+  }
+
+  if (JSON.stringify(section[memberKey]) === JSON.stringify(value)) {
+    return "unchanged";
+  }
+
+  section[memberKey] = value;
+  parsed[sectionKey] = section;
+
+  const next = `${JSON.stringify(parsed, null, 2)}\n`;
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, next, "utf-8");
+  return existed ? "updated" : "created";
+}
+
+export async function removeJsonMember(
+  path: string,
+  sectionKey: string,
+  memberKey: string,
+): Promise<InstallAction> {
+  if (!(await Bun.file(path).exists())) {
+    return "not-found";
+  }
+
+  const text = await Bun.file(path).text();
+  const parsed = parseJsonObject(text);
+  if (parsed === "error") {
+    return "error";
+  }
+
+  const section = sectionObject(parsed, sectionKey);
+  if (section === "error" || !(memberKey in section)) {
+    return "not-found";
+  }
+
+  delete section[memberKey];
+  if (Object.keys(section).length === 0) {
+    delete parsed[sectionKey];
+  } else {
+    parsed[sectionKey] = section;
+  }
+
+  const next = `${JSON.stringify(parsed, null, 2)}\n`;
+  if (next === `${text.endsWith("\n") ? text : `${text}\n`}`) {
+    return "not-found";
+  }
+
+  if (Object.keys(parsed).length === 0) {
+    await unlink(path);
+    return "removed";
+  }
+
+  await writeFile(path, next, "utf-8");
+  return "removed";
+}
+
+export async function replaceOrAppendMarked(path: string, content: string): Promise<InstallAction> {
+  await mkdir(dirname(path), { recursive: true });
+  const existed = await Bun.file(path).exists();
+  const existing = existed ? await Bun.file(path).text() : "";
+
+  const startIdx = existing.indexOf(MIRU_START);
+  const endIdx = existing.indexOf(MIRU_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + MIRU_END.length);
+    const updated = `${before}${content.trim()}\n${after.replace(/^\n+/, "")}`;
+    if (updated === existing) {
+      return "unchanged";
+    }
+    await writeFile(path, updated, "utf-8");
+    return "updated";
+  }
+
+  const separator =
+    existing && !existing.endsWith("\n\n") ? (existing.endsWith("\n") ? "\n" : "\n\n") : "";
+  await writeFile(path, `${existing}${separator}${content}`, "utf-8");
+  return existed ? "updated" : "created";
+}
+
+export async function removeMarked(path: string): Promise<InstallAction> {
+  if (!(await Bun.file(path).exists())) {
+    return "not-found";
+  }
+
+  const existing = await Bun.file(path).text();
+  const startIdx = existing.indexOf(MIRU_START);
+  const endIdx = existing.indexOf(MIRU_END);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return "not-found";
+  }
+
+  const before = existing.slice(0, startIdx).replace(/\n+$/, "");
+  const after = existing.slice(endIdx + MIRU_END.length).replace(/^\n+/, "");
+  const updated = [before, after].filter((part) => part.length > 0).join("\n");
+  const withNewline = updated.length > 0 ? `${updated}\n` : "";
+
+  if (withNewline.trim().length === 0) {
+    await unlink(path);
+    return "removed";
+  }
+
+  await writeFile(path, withNewline, "utf-8");
+  return "removed";
+}
+
+function stripTomlSection(text: string, header: string): string {
+  const prefix = header.trim().slice(1, -1);
+  const lines = text.split("\n");
+  const result: string[] = [];
+  let skipping = false;
+
+  for (const line of lines) {
+    const tableKey = line.split("#")[0]?.trim() ?? "";
+    if (tableKey.startsWith("[") && tableKey.endsWith("]")) {
+      const tableName = tableKey.slice(1, -1);
+      if (tableName === prefix || tableName.startsWith(`${prefix}.`)) {
+        skipping = true;
+        continue;
+      }
+      skipping = false;
+    }
+    if (!skipping) {
+      result.push(line);
+    }
+  }
+
+  return result.join("\n");
+}
+
+export async function mergeTomlBlock(path: string): Promise<InstallAction> {
+  await mkdir(dirname(path), { recursive: true });
+  const existed = await Bun.file(path).exists();
+  const existing = existed ? await Bun.file(path).text() : "";
+
+  if (existing.includes(CODEX_MCP_BLOCK.trim())) {
+    return "unchanged";
+  }
+
+  const base = stripTomlSection(existing, CODEX_MCP_HEADER).replace(/\n+$/, "");
+  const next = base.length > 0 ? `${base}\n\n${CODEX_MCP_BLOCK}` : CODEX_MCP_BLOCK;
+  await writeFile(path, next.endsWith("\n") ? next : `${next}\n`, "utf-8");
+  return existed ? "updated" : "created";
+}
+
+export async function removeTomlBlock(path: string): Promise<InstallAction> {
+  if (!(await Bun.file(path).exists())) {
+    return "not-found";
+  }
+
+  const existing = await Bun.file(path).text();
+  if (!existing.includes(CODEX_MCP_HEADER)) {
+    return "not-found";
+  }
+
+  const remaining = stripTomlSection(existing, CODEX_MCP_HEADER).trim();
+  if (remaining.length === 0) {
+    await unlink(path);
+    return "removed";
+  }
+
+  await writeFile(path, `${remaining}\n`, "utf-8");
+  return "removed";
+}