@takara-ai/miru-code 0.2.0 → 0.4.0

package/src/cli-ui.ts

@@ -0,0 +1,189 @@
+import type { SearchResult } from "./types.ts";
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  magenta: "\x1b[35m",
+} as const;
+
+function colorEnabled(stream: NodeJS.WriteStream = process.stdout): boolean {
+  return stream.isTTY && process.env.NO_COLOR === undefined;
+}
+
+function paint(text: string, code: string, stream?: NodeJS.WriteStream): string {
+  if (!colorEnabled(stream)) {
+    return text;
+  }
+  return `${code}${text}${ANSI.reset}`;
+}
+
+export function bold(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.bold, stream);
+}
+
+export function dim(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.dim, stream);
+}
+
+export function cyan(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.cyan, stream);
+}
+
+export function green(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.green, stream);
+}
+
+export function red(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.red, stream);
+}
+
+export function yellow(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.yellow, stream);
+}
+
+export function magenta(text: string, stream?: NodeJS.WriteStream): string {
+  return paint(text, ANSI.magenta, stream);
+}
+
+export function isInteractiveStdout(): boolean {
+  return process.stdout.isTTY && process.env.NO_COLOR === undefined;
+}
+
+export function prefersJsonOutput(jsonFlag: boolean): boolean {
+  return jsonFlag || !process.stdout.isTTY;
+}
+
+export function brandTitle(): string {
+  return bold("Miru", process.stderr) + dim(" (見る)", process.stderr);
+}
+
+export function writeStdout(line = ""): void {
+  process.stdout.write(`${line}\n`);
+}
+
+export function writeStderr(line = ""): void {
+  process.stderr.write(`${line}\n`);
+}
+
+export function divider(char = "─", width = 52, stream: NodeJS.WriteStream = process.stdout): void {
+  const line = char.repeat(width);
+  stream.write(`${dim(line, stream)}\n`);
+}
+
+export function header(title: string, subtitle?: string): void {
+  writeStdout("");
+  writeStdout(brandTitle() + (title ? dim(` · ${title}`) : ""));
+  if (subtitle) {
+    writeStdout(dim(subtitle));
+  }
+  divider();
+}
+
+export function section(title: string): void {
+  writeStdout("");
+  writeStdout(bold(title));
+}
+
+export function commandRow(name: string, description: string, indent = 2): void {
+  const pad = " ".repeat(indent);
+  const nameCol = name.padEnd(16);
+  writeStdout(`${pad}${cyan(nameCol)} ${dim(description)}`);
+}
+
+function writeLine(message: string, stream: NodeJS.WriteStream = process.stderr): void {
+  stream.write(`${message}\n`);
+}
+
+export function success(message: string, stream?: NodeJS.WriteStream): void {
+  writeLine(green("✓ ") + message, stream);
+}
+
+export function info(message: string, stream?: NodeJS.WriteStream): void {
+  writeLine(dim("· ") + message, stream);
+}
+
+export function warn(message: string, stream?: NodeJS.WriteStream): void {
+  writeLine(yellow("! ") + message, stream);
+}
+
+export function fail(message: string, stream?: NodeJS.WriteStream): void {
+  writeLine(red("✗ ") + message, stream);
+}
+
+export function hint(message: string, stream?: NodeJS.WriteStream): void {
+  writeLine(dim(`  ${message}`), stream);
+}
+
+const PREVIEW_LINES = 12;
+const PREVIEW_WIDTH = 72;
+
+function truncateLine(line: string, width: number): string {
+  if (line.length <= width) {
+    return line;
+  }
+  return `${line.slice(0, width - 1)}…`;
+}
+
+function previewContent(content: string): string[] {
+  return content
+    .split("\n")
+    .slice(0, PREVIEW_LINES)
+    .map((line) => truncateLine(line.replace(/\t/g, "  "), PREVIEW_WIDTH));
+}
+
+export function formatSearchResultsPretty(query: string, results: SearchResult[]): string {
+  const lines: string[] = [];
+  const count = results.length;
+  const label = count === 1 ? "1 result" : `${count} results`;
+
+  lines.push("");
+  lines.push(bold(label) + dim(` for `) + cyan(`"${query}"`));
+  lines.push("");
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (!result) {
+      continue;
+    }
+    const { chunk, score } = result;
+    const location = `${chunk.file_path}:${chunk.start_line}-${chunk.end_line}`;
+    const lang = chunk.language ? dim(`  ${chunk.language}`) : "";
+    const rank = dim(`[${i + 1}]`);
+    const scoreText = magenta(score.toFixed(3));
+
+    lines.push(`${rank} ${scoreText}  ${bold(location)}${lang}`);
+    lines.push(dim("─".repeat(Math.min(PREVIEW_WIDTH, 52))));
+
+    for (const line of previewContent(chunk.content)) {
+      lines.push(dim("  ") + line);
+    }
+
+    const totalLines = chunk.content.split("\n").length;
+    if (totalLines > PREVIEW_LINES) {
+      lines.push(dim(`  … ${totalLines - PREVIEW_LINES} more lines`));
+    }
+
+    if (i < results.length - 1) {
+      lines.push("");
+    }
+  }
+
+  if (isInteractiveStdout()) {
+    lines.push("");
+    lines.push(dim("Tip: add --json for machine-readable output"));
+  }
+  return lines.join("\n");
+}
+
+export function formatSearchErrorPretty(message: string): string {
+  return `\n${yellow("No results")} ${dim("—")} ${message}\n`;
+}
+
+export function formatRelatedHeader(filePath: string, line: number): string {
+  return `related to ${filePath}:${line}`;
+}

package/src/cli.ts

@@ -2,20 +2,62 @@
 import { resolve } from "node:path";
 import { type AgentId, writeAgentFile } from "./agents.ts";
 import { clearCache } from "./cache.ts";
+import {
+  fail,
+  formatRelatedHeader,
+  formatSearchErrorPretty,
+  formatSearchResultsPretty,
+  hint,
+  prefersJsonOutput,
+  success,
+} from "./cli-ui.ts";
 import { loadStoredCredentials } from "./credentials.ts";
 import { loadEnvFiles } from "./env-files.ts";
+import {
+  AGENT_IDS,
+  formatUnknownAgent,
+  printCommandHelp,
+  printFullHelp,
+  printMainHelp,
+} from "./help.ts";
+import { runInstaller } from "./installer/installer.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
 import { ensureCredentials, runClearCredentials, runSetup } from "./setup.ts";
-import type { ContentType } from "./types.ts";
+import { withSpinner } from "./spinner.ts";
+import type { ContentType, SearchResult } from "./types.ts";
 import { formatResults, resolveChunk, resolveContent } from "./utils.ts";
 
 loadEnvFiles();
 await loadStoredCredentials();
 
-const CLI_COMMANDS = new Set(["search", "find-related", "init", "setup", "clear", "-h", "--help"]);
+const CLI_COMMANDS = new Set([
+  "search",
+  "find-related",
+  "init",
+  "install",
+  "uninstall",
+  "setup",
+  "clear",
+  "help",
+  "-h",
+  "--help",
+]);
 
-const AGENTS = new Set<AgentId>(["claude", "copilot", "cursor", "gemini", "kiro", "opencode"]);
+const AGENTS = new Set<AgentId>(AGENT_IDS);
+
+function parseFlagArgv(argv: string[], flag: string): { present: boolean; rest: string[] } {
+  const rest: string[] = [];
+  let present = false;
+  for (const arg of argv) {
+    if (arg === flag) {
+      present = true;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { present, rest };
+}
 
 function parseContentArgv(argv: string[]): { content: ContentType[]; rest: string[] } {
   const rest: string[] = [];
@@ -61,19 +103,46 @@ function parseTopK(argv: string[]): { topK: number; rest: string[] } {
   return { topK: Number.isFinite(topK) && topK >= 1 ? Math.floor(topK) : 5, rest };
 }
 
+function emitSearchOutput(
+  query: string,
+  results: SearchResult[],
+  jsonFlag: boolean,
+  emptyMessage = "No results found.",
+): void {
+  if (results.length === 0) {
+    if (prefersJsonOutput(jsonFlag)) {
+      console.log(JSON.stringify({ error: emptyMessage }));
+      return;
+    }
+    process.stdout.write(formatSearchErrorPretty(emptyMessage));
+    return;
+  }
+
+  if (prefersJsonOutput(jsonFlag)) {
+    console.log(JSON.stringify(formatResults(query, results)));
+    return;
+  }
+
+  process.stdout.write(formatSearchResultsPretty(query, results));
+}
+
 async function runSearch(
   path: string,
   query: string,
   topK: number,
   content: ContentType[],
+  jsonFlag: boolean,
 ): Promise<void> {
   await ensureCredentials();
-  const index = await MiruIndex.fromSource(path, content);
-  await index.saveToDefaultCache(path);
-  const results = await index.search({ query, topK });
-  const out =
-    results.length > 0 ? formatResults(query, results) : { error: "No results found." as const };
-  console.log(JSON.stringify(out));
+
+  const index = await withSpinner("Indexing and searching", async () => {
+    const built = await MiruIndex.fromSource(path, content);
+    await built.saveToDefaultCache(path);
+    const results = await built.search({ query, topK });
+    return { index: built, results };
+  });
+
+  emitSearchOutput(query, index.results, jsonFlag);
 }
 
 async function runFindRelated(
@@ -82,81 +151,105 @@ async function runFindRelated(
   line: number,
   topK: number,
   content: ContentType[],
+  jsonFlag: boolean,
 ): Promise<void> {
   await ensureCredentials();
-  const index = await MiruIndex.fromSource(path, content);
-  const chunk = resolveChunk(index.chunks, filePath, line);
-  if (!chunk) {
-    console.error(`No chunk found at ${filePath}:${line}.`);
-    process.exit(1);
+
+  const { results, label } = await withSpinner("Finding related chunks", async () => {
+    const built = await MiruIndex.fromSource(path, content);
+    const chunk = resolveChunk(built.chunks, filePath, line);
+    if (!chunk) {
+      throw new RelatedChunkNotFoundError(filePath, line);
+    }
+    const hits = await built.findRelated(chunk, topK);
+    await built.saveToDefaultCache(path);
+    return {
+      results: hits,
+      label: formatRelatedHeader(filePath, line),
+    };
+  });
+
+  emitSearchOutput(label, results, jsonFlag, `No related chunks found for ${filePath}:${line}.`);
+}
+
+class RelatedChunkNotFoundError extends Error {
+  constructor(filePath: string, line: number) {
+    super(`No chunk found at ${filePath}:${line}.`);
+    this.name = "RelatedChunkNotFoundError";
   }
-  const results = await index.findRelated(chunk, topK);
-  const label = `Chunks related to ${filePath}:${line}`;
-  const out =
-    results.length > 0
-      ? formatResults(label, results)
-      : { error: `No related chunks found for ${filePath}:${line}.` };
-  console.log(JSON.stringify(out));
-  await index.saveToDefaultCache(path);
 }
 
 async function runInit(agent: AgentId, force: boolean): Promise<void> {
-  const dest = await writeAgentFile(agent, { force });
-  console.log(`Created ${dest}`);
+  try {
+    const dest = await writeAgentFile(agent, { force });
+    success(`Wrote sub-agent: ${dest}`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail(message);
+    hint("Use --force to overwrite an existing file.");
+    process.exit(1);
+  }
 }
 
 async function runClear(path: string): Promise<void> {
   await clearCache(path);
-  console.log(`Cleared cached index for: ${path}`);
+  success(`Cleared cached index for ${path}`);
 }
 
-function printHelp(): void {
-  console.log(`Miru (見る) — hybrid code search (Bun + TypeScript + Takara)
-
-CLI:
-  miru search <query> [path] [-k N] [--content code|docs|config|all]
-  miru find-related <file_path> <line> [path] [-k N] [--content ...]
-  miru setup [--key KEY] [--force] [--clear]
-  miru init [--agent cursor] [--force]
-  miru clear [path]
-
-MCP server (default when no CLI subcommand):
-  miru [--ref BRANCH] [--content code ...]
-
-  Indexes a repo on the first search/find_related call via the tool repo argument.
+async function runCli(argv: string[]): Promise<void> {
+  const [command, ...rest] = argv;
 
-Examples:
-  miru search "auth middleware" ./src
-  miru find-related src/auth.ts 42 .
+  if (command === undefined) {
+    printMainHelp();
+    return;
+  }
 
-Environment:
-  TAKARA_API_KEY / OPENAI_API_KEY / MIRU_OPENAI_API_KEY   Takara bearer token
-  MIRU_OPENAI_BASE_URL                                    Default: infer.dev.takara.ai
-`);
-}
+  if (command === "-h" || command === "--help") {
+    printFullHelp();
+    return;
+  }
 
-async function runCli(argv: string[]): Promise<void> {
-  const [command, ...rest] = argv;
+  if (command === "help") {
+    const topic = rest[0];
+    if (!topic) {
+      printMainHelp();
+      return;
+    }
+    printCommandHelp(topic);
+    return;
+  }
 
-  if (command === "-h" || command === "--help" || command === undefined) {
-    printHelp();
+  if (command === "install" || command === "uninstall") {
+    await runInstaller(command);
     return;
   }
 
   if (command === "init") {
-    let agent: AgentId = "claude";
+    let agent: AgentId | undefined;
     let force = false;
     for (let i = 0; i < rest.length; i++) {
       const arg = rest[i];
       if (arg === "--force") {
         force = true;
-      } else if ((arg === "--agent" || arg === "-a") && rest[i + 1]) {
-        const value = rest[++i] as AgentId;
-        if (AGENTS.has(value)) {
-          agent = value;
+      } else if (arg === "--agent" || arg === "-a") {
+        const value = rest[++i];
+        if (!value) {
+          fail("Missing value for --agent.");
+          printCommandHelp("init");
+          process.exit(1);
         }
+        if (!AGENTS.has(value as AgentId)) {
+          fail(formatUnknownAgent(value));
+          process.exit(1);
+        }
+        agent = value as AgentId;
       }
     }
+    if (!agent) {
+      fail("miru init requires --agent.");
+      printCommandHelp("init");
+      process.exit(1);
+    }
     await runInit(agent, force);
     return;
   }
@@ -177,7 +270,7 @@ async function runCli(argv: string[]): Promise<void> {
     }
     if (clear) {
       if (apiKey) {
-        console.error("Usage: miru setup --clear cannot be combined with --key.");
+        fail("miru setup --clear cannot be combined with --key.");
         process.exit(1);
       }
       await runClearCredentials();
@@ -193,17 +286,18 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
-  const { content, rest: contentRest } = parseContentArgv(rest);
+  const { present: jsonFlag, rest: jsonRest } = parseFlagArgv(rest, "--json");
+  const { content, rest: contentRest } = parseContentArgv(jsonRest);
   const { topK, rest: sizedRest } = parseTopK(contentRest);
 
   if (command === "search") {
     const query = sizedRest[0];
     if (!query) {
-      console.error("Usage: miru search <query> [path] [-k N] [--content ...]");
+      printCommandHelp("search");
       process.exit(1);
     }
     const path = resolve(sizedRest[1] ?? process.cwd());
-    await runSearch(path, query, topK, content);
+    await runSearch(path, query, topK, content, jsonFlag);
     return;
   }
 
@@ -211,16 +305,25 @@ async function runCli(argv: string[]): Promise<void> {
     const filePath = sizedRest[0];
     const lineRaw = sizedRest[1];
     if (!filePath || !lineRaw) {
-      console.error("Usage: miru find-related <file_path> <line> [path] [-k N] [--content ...]");
+      printCommandHelp("find-related");
       process.exit(1);
     }
     const line = Number(lineRaw);
     const path = resolve(sizedRest[2] ?? process.cwd());
-    await runFindRelated(path, filePath, line, topK, content);
+    try {
+      await runFindRelated(path, filePath, line, topK, content, jsonFlag);
+    } catch (err) {
+      if (err instanceof RelatedChunkNotFoundError) {
+        fail(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
     return;
   }
 
-  printHelp();
+  fail(`Unknown command: ${command}`);
+  printMainHelp();
   process.exit(1);
 }
 
@@ -270,6 +373,6 @@ async function main(): Promise<void> {
 }
 
 main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err);
+  fail(err instanceof Error ? err.message : String(err));
   process.exit(1);
 });

package/src/credentials.ts

@@ -1,6 +1,6 @@
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { EMBEDDING_API_KEY_NAMES, envFirstString } from "./env.ts";
+import { hasTakaraApiKeyInEnv } from "./env.ts";
 
 const CREDENTIALS_FILENAME = "credentials.json";
 const CREDENTIALS_VERSION = 1;
@@ -31,10 +31,6 @@ export function resolveCredentialsPath(): string {
   return join(resolveCredentialsDir(), CREDENTIALS_FILENAME);
 }
 
-export function hasEmbeddingApiKeyInEnv(): boolean {
-  return Boolean(envFirstString([...EMBEDDING_API_KEY_NAMES], ""));
-}
-
 export async function readStoredCredentials(): Promise<StoredCredentials | null> {
   const path = resolveCredentialsPath();
   if (!(await Bun.file(path).exists())) {
@@ -53,7 +49,7 @@ export async function readStoredCredentials(): Promise<StoredCredentials | null>
 
 /** Set TAKARA_API_KEY from the user credentials file when env is unset. */
 export async function loadStoredCredentials(): Promise<boolean> {
-  if (hasEmbeddingApiKeyInEnv()) {
+  if (hasTakaraApiKeyInEnv()) {
     return false;
   }
   const stored = await readStoredCredentials();

package/src/env.ts

@@ -31,21 +31,17 @@ export function envOptionalInt(names: string[], min = 1): number | undefined {
   return undefined;
 }
 
-const EMBEDDING_API_KEY_NAMES = [
-  "TAKARA_API_KEY",
-  "OPENAI_API_KEY",
-  "MIRU_OPENAI_API_KEY",
-  "SEMBLE_OPENAI_API_KEY",
-] as const;
+export const TAKARA_API_KEY_ENV = "TAKARA_API_KEY";
 
-export { EMBEDDING_API_KEY_NAMES };
+export function hasTakaraApiKeyInEnv(): boolean {
+  return Boolean(process.env[TAKARA_API_KEY_ENV]?.trim());
+}
 
 export function resolveEmbeddingApiKey(): string {
-  const key = envFirstString([...EMBEDDING_API_KEY_NAMES], "");
+  const key = process.env[TAKARA_API_KEY_ENV]?.trim() ?? "";
   if (!key) {
     throw new Error(
-      "Embedding API key required. Run `miru setup`, set TAKARA_API_KEY, OPENAI_API_KEY, " +
-        "MIRU_OPENAI_API_KEY, or SEMBLE_OPENAI_API_KEY in your MCP server env or .env.local.",
+      "Takara API key required. Run `miru setup`, or set TAKARA_API_KEY in your MCP server env or .env.local.",
     );
   }
   return key;