@takara-ai/miru-code 0.2.0 → 0.3.0

package/README.md

@@ -60,7 +60,7 @@ Add credentials to `.env.local` (loaded automatically when you run from this rep
 
 | Variable | Default |
 |----------|---------|
-| `TAKARA_API_KEY` / `OPENAI_API_KEY` / `MIRU_OPENAI_API_KEY` | (required) Bearer token for Takara |
+| `TAKARA_API_KEY` | (required) Takara bearer token for embeddings |
 | `MIRU_OPENAI_BASE_URL` | `https://infer.dev.takara.ai/v1` |
 | `MIRU_OPENAI_EMBEDDING_MODEL` | `ds1-potion-code-16m` |
 | `MIRU_EMBEDDING_DIMENSIONS` | `256` (auto for potion) |
@@ -68,12 +68,8 @@ Add credentials to `.env.local` (loaded automatically when you run from this rep
 | `MIRU_EMBEDDING_BATCH_SIZE` | `32` (max for this model) |
 | `MIRU_CONCURRENCY` | logical CPUs **minus 2** (min 1) |
 
-`SEMBLE_*` env names are still accepted as aliases for migration.
-
 Parallelism: file reads/chunking, embedding batches (up to concurrency in flight), query embed overlapping BM25, and **BM25 scoring in Bun workers** (shards by doc range when index has 256+ chunks). BM25 uses an inverted postings list for fast single-threaded search on small indexes. Override with `MIRU_CONCURRENCY`.
 
-`OPENAI_*` env aliases are also accepted where noted in the CLI help.
-
 ## IDE integration
 
 Miru supports six agent platforms. For each, you can wire the **MCP server** (recommended) and/or install a **CLI sub-agent** with `miru init`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -4,6 +4,13 @@ import { type AgentId, writeAgentFile } from "./agents.ts";
 import { clearCache } from "./cache.ts";
 import { loadStoredCredentials } from "./credentials.ts";
 import { loadEnvFiles } from "./env-files.ts";
+import {
+  AGENT_IDS,
+  formatUnknownAgent,
+  printCommandHelp,
+  printFullHelp,
+  printMainHelp,
+} from "./help.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
 import { ensureCredentials, runClearCredentials, runSetup } from "./setup.ts";
@@ -13,9 +20,18 @@ 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",
+  "setup",
+  "clear",
+  "help",
+  "-h",
+  "--help",
+]);
 
-const AGENTS = new Set<AgentId>(["claude", "copilot", "cursor", "gemini", "kiro", "opencode"]);
+const AGENTS = new Set<AgentId>(AGENT_IDS);
 
 function parseContentArgv(argv: string[]): { content: ContentType[]; rest: string[] } {
   const rest: string[] = [];
@@ -101,8 +117,15 @@ async function runFindRelated(
 }
 
 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 });
+    process.stdout.write(`Wrote sub-agent: ${dest}\n`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${message}\n`);
+    process.stderr.write("Use --force to overwrite an existing file.\n");
+    process.exit(1);
+  }
 }
 
 async function runClear(path: string): Promise<void> {
@@ -110,53 +133,55 @@ async function runClear(path: string): Promise<void> {
   console.log(`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.
-
-Examples:
-  miru search "auth middleware" ./src
-  miru find-related src/auth.ts 42 .
-
-Environment:
-  TAKARA_API_KEY / OPENAI_API_KEY / MIRU_OPENAI_API_KEY   Takara bearer token
-  MIRU_OPENAI_BASE_URL                                    Default: infer.dev.takara.ai
-`);
-}
-
 async function runCli(argv: string[]): Promise<void> {
   const [command, ...rest] = argv;
 
-  if (command === "-h" || command === "--help" || command === undefined) {
-    printHelp();
+  if (command === undefined) {
+    printMainHelp();
+    return;
+  }
+
+  if (command === "-h" || command === "--help") {
+    printFullHelp();
+    return;
+  }
+
+  if (command === "help") {
+    const topic = rest[0];
+    if (!topic) {
+      printMainHelp();
+      return;
+    }
+    printCommandHelp(topic);
     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) {
+          process.stderr.write("Missing value for --agent.\n");
+          printCommandHelp("init");
+          process.exit(1);
+        }
+        if (!AGENTS.has(value as AgentId)) {
+          process.stderr.write(`${formatUnknownAgent(value)}\n`);
+          process.exit(1);
         }
+        agent = value as AgentId;
       }
     }
+    if (!agent) {
+      process.stderr.write("miru init requires --agent.\n");
+      printCommandHelp("init");
+      process.exit(1);
+    }
     await runInit(agent, force);
     return;
   }
@@ -199,7 +224,7 @@ async function runCli(argv: string[]): Promise<void> {
   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());
@@ -211,7 +236,7 @@ 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);
@@ -220,7 +245,8 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
-  printHelp();
+  process.stderr.write(`Unknown command: ${command}\n`);
+  printMainHelp();
   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;

package/src/help.ts

@@ -0,0 +1,175 @@
+import type { AgentId } from "./agents.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 {
+  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`);
+}
+
+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`);
+}
+
+export function printFullHelp(): void {
+  printMainHelp();
+  printEnvHelp();
+}
+
+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"),
+      );
+      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"),
+      );
+      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"),
+      );
+      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"),
+      );
+      return;
+    case "clear":
+      process.stdout.write(
+        [
+          "",
+          "miru clear — drop cached index",
+          "",
+          "Usage:",
+          "  miru clear [path]",
+          "",
+          "Example:",
+          "  miru clear .",
+          "",
+        ].join("\n"),
+      );
+      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"),
+      );
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${command}\n\n`);
+      printMainHelp();
+      process.exit(1);
+  }
+  process.stdout.write("\n");
+}
+
+export function formatUnknownAgent(agent: string): string {
+  return `Unknown agent "${agent}". Choose one of: ${AGENT_LIST}`;
+}

package/src/prompt.ts

@@ -0,0 +1,111 @@
+import { stdin as input, stdout as output } from "node:process";
+
+export interface HiddenPromptState {
+  value: string;
+  escapeBuffer: string;
+}
+
+export function createHiddenPromptState(): HiddenPromptState {
+  return { value: "", escapeBuffer: "" };
+}
+
+/** Apply one UTF-16 code unit from raw stdin; returns terminal echo bytes (may be empty). */
+export function applyHiddenPromptChar(
+  state: HiddenPromptState,
+  char: string,
+): { state: HiddenPromptState; echo: string; submit?: boolean; cancel?: boolean } {
+  if (char === "\x1b") {
+    return { state: { ...state, escapeBuffer: "\x1b" }, echo: "" };
+  }
+
+  if (state.escapeBuffer.length > 0) {
+    const escapeBuffer = state.escapeBuffer + char;
+    let done = false;
+    if (escapeBuffer.startsWith("\x1b[")) {
+      done = escapeBuffer.length > 2 && char >= "@" && char <= "~";
+    } else if (escapeBuffer.startsWith("\x1b")) {
+      done = escapeBuffer.length >= 2;
+    }
+    return {
+      state: { ...state, escapeBuffer: done ? "" : escapeBuffer },
+      echo: "",
+    };
+  }
+
+  if (char === "\n" || char === "\r" || char === "\u0004") {
+    return { state, echo: "", submit: true };
+  }
+
+  if (char === "\u0003") {
+    return { state, echo: "", cancel: true };
+  }
+
+  if (char === "\u007f" || char === "\b") {
+    if (state.value.length === 0) {
+      return { state, echo: "" };
+    }
+    return {
+      state: { ...state, value: state.value.slice(0, -1) },
+      echo: "\b \b",
+    };
+  }
+
+  if (char < " " || char === "\x7f") {
+    return { state, echo: "" };
+  }
+
+  return {
+    state: { ...state, value: state.value + char },
+    echo: "*",
+  };
+}
+
+export async function promptHidden(message: string): Promise<string> {
+  if (!input.isTTY) {
+    throw new Error(
+      "Cannot prompt for API key: stdin is not a TTY. Run `miru setup --key YOUR_KEY` or set TAKARA_API_KEY.",
+    );
+  }
+
+  return new Promise((resolve, reject) => {
+    output.write(message);
+    input.setRawMode?.(true);
+    input.resume();
+    input.setEncoding("utf8");
+
+    let state = createHiddenPromptState();
+
+    const onData = (chunk: string) => {
+      for (const char of chunk) {
+        const result = applyHiddenPromptChar(state, char);
+        state = result.state;
+
+        if (result.cancel) {
+          cleanup();
+          output.write("\n");
+          reject(new Error("Setup cancelled."));
+          process.exit(130);
+        }
+
+        if (result.submit) {
+          cleanup();
+          output.write("\n");
+          resolve(state.value.trim());
+          return;
+        }
+
+        if (result.echo) {
+          output.write(result.echo);
+        }
+      }
+    };
+
+    const cleanup = () => {
+      input.setRawMode?.(false);
+      input.pause();
+      input.removeListener("data", onData);
+    };
+
+    input.on("data", onData);
+  });
+}

package/src/setup.ts

@@ -1,65 +1,16 @@
-import { stdin as input, stdout as output } from "node:process";
+import { stdout as output } from "node:process";
 import {
   clearStoredCredentials,
-  hasEmbeddingApiKeyInEnv,
   loadStoredCredentials,
   readStoredCredentials,
   resolveCredentialsPath,
   saveStoredCredentials,
 } from "./credentials.ts";
 import { validateEmbeddingApiKey } from "./embeddings/validate.ts";
-import { resolveEmbeddingApiKey } from "./env.ts";
+import { hasTakaraApiKeyInEnv, resolveEmbeddingApiKey } from "./env.ts";
+import { promptHidden } from "./prompt.ts";
 import { Spinner } from "./spinner.ts";
 
-async function promptHidden(message: string): Promise<string> {
-  if (!input.isTTY) {
-    throw new Error(
-      "Cannot prompt for API key: stdin is not a TTY. Run `miru setup --key YOUR_KEY` or set TAKARA_API_KEY.",
-    );
-  }
-
-  return new Promise((resolve, reject) => {
-    output.write(message);
-    input.setRawMode?.(true);
-    input.resume();
-    input.setEncoding("utf8");
-
-    let value = "";
-    const onData = (chunk: string) => {
-      const char = chunk[0];
-      if (char === "\n" || char === "\r" || char === "\u0004") {
-        cleanup();
-        output.write("\n");
-        resolve(value.trim());
-        return;
-      }
-      if (char === "\u0003") {
-        cleanup();
-        output.write("\n");
-        reject(new Error("Setup cancelled."));
-        process.exit(130);
-      }
-      if (char === "\u007f" || char === "\b") {
-        if (value.length > 0) {
-          value = value.slice(0, -1);
-          output.write("\b \b");
-        }
-        return;
-      }
-      value += chunk;
-      output.write("*");
-    };
-
-    const cleanup = () => {
-      input.setRawMode?.(false);
-      input.pause();
-      input.removeListener("data", onData);
-    };
-
-    input.on("data", onData);
-  });
-}
-
 async function promptApiKey(): Promise<string> {
   let key = "";
   while (!key) {
@@ -78,7 +29,7 @@ export interface RunSetupOptions {
 }
 
 export async function runSetup(options: RunSetupOptions = {}): Promise<string> {
-  if (!options.force && hasEmbeddingApiKeyInEnv()) {
+  if (!options.force && hasTakaraApiKeyInEnv()) {
     const path = resolveCredentialsPath();
     const stored = await readStoredCredentials();
     if (stored) {