@takara-ai/miru-code 0.1.4 → 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`.
@@ -93,14 +89,14 @@ Run `miru init --agent <id> --force` to overwrite an existing sub-agent file.
 
 ### MCP server
 
-Run with **no arguments** to start the stdio MCP server. It indexes the **current working directory** (most IDEs set this to your workspace). Optional path/ref flags pre-index a different repo.
+Run with **no arguments** to start the stdio MCP server. Indexing begins on the first `search` or `find_related` call, using the `repo` path you pass. Optional `--ref` sets the default git ref for remote repos.
 
 ```bash
 bunx @takara-ai/miru-code
 # or after bun add -g @takara-ai/miru-code:  miru
 ```
 
-**Tools:** `search`, `find_related` — pass `repo` only when querying a different path or git URL.
+**Tools:** `search`, `find_related` — `repo` is required (project root or https:// git URL).
 
 For MCP configs, use `bunx` as the command (`bun` with `x` in `args` works too — they're equivalent).
 
@@ -352,12 +348,14 @@ bun run typecheck
 
 Releases use **Bun** for install, test, and `bun pm pack`. The registry upload uses **`npm publish`** on that tarball because [Bun does not yet support npm OIDC trusted publishing](https://github.com/oven-sh/bun/issues/22423) — no long-lived npm tokens in GitHub secrets.
 
-**Local first publish** (creates the package on npm):
+**Local publish** (logged in to npm; `publishConfig.access` is already `public`):
 
 ```bash
-bun publish --access public
+bun publish
 ```
 
+Runs `prepublishOnly` (typecheck + tests), then a single registry upload. Do not add a `publish` script that calls `npm publish` — Bun runs lifecycle scripts after its own upload and would publish twice.
+
 **CI** (after Trusted Publisher is configured on npm):
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,6 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "bun run typecheck && bun test",
-    "publish": "npm publish --access public",
     "benchmark:quality": "bun run scripts/benchmark-quality.ts",
     "benchmark:quantization": "bun run scripts/benchmark-quantization.ts"
   },

package/src/cli.ts

@@ -4,18 +4,34 @@ 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";
 import type { ContentType } from "./types.ts";
-import { formatResults, isGitUrl, resolveChunk, resolveContent } from "./utils.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",
+  "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,54 +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
-  miru [path] [--ref BRANCH] [--content code ...]
-
-  With no path, indexes the process working directory (Cursor sets this to your workspace).
-
-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;
   }
@@ -200,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());
@@ -212,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);
@@ -221,12 +245,12 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
-  printHelp();
+  process.stderr.write(`Unknown command: ${command}\n`);
+  printMainHelp();
   process.exit(1);
 }
 
 async function runMcp(argv: string[]): Promise<void> {
-  let path: string | null = null;
   let ref: string | null = null;
   const contentTokens: string[] = [];
 
@@ -247,15 +271,10 @@ async function runMcp(argv: string[]): Promise<void> {
         contentTokens.push(value);
         i++;
       }
-      continue;
-    }
-    if (arg && !arg.startsWith("-") && path === null) {
-      path = isGitUrl(arg) ? arg : resolve(arg);
     }
   }
 
   await serveMcp({
-    path,
     ref,
     content: resolveContent(contentTokens.length > 0 ? contentTokens : ["code"]),
   });

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/mcp/index-cache.ts

@@ -57,11 +57,14 @@ export function shouldIgnoreWatchPath(relativePath: string | null | undefined):
 
 export class IndexCache {
   private readonly content: ContentType[];
+  private readonly defaultRef: string | null;
   private readonly entries = new Map<string, CacheEntry>();
   private watcher: ReturnType<typeof watch> | null = null;
+  private watchedSource: string | null = null;
 
-  constructor(content: ContentType[] = ["code"]) {
+  constructor(content: ContentType[] = ["code"], defaultRef: string | null = null) {
     this.content = content;
+    this.defaultRef = defaultRef;
   }
 
   private ensureEntry(cacheKey: string): CacheEntry {
@@ -107,6 +110,7 @@ export class IndexCache {
     void task
       .then((index) => {
         entry.index = index;
+        this.maybeStartWatcher(source);
         void this.flushFileUpdates(cacheKey, source);
         return index;
       })
@@ -120,11 +124,12 @@ export class IndexCache {
   }
 
   async get(source: string, ref?: string | null): Promise<MiruIndex> {
-    const cacheKey = computeSourceCacheKey(source, ref);
+    const resolvedRef = ref ?? this.defaultRef;
+    const cacheKey = computeSourceCacheKey(source, resolvedRef);
     const entry = this.ensureEntry(cacheKey);
 
     if (!entry.task) {
-      this.startBuild(source, ref, cacheKey);
+      this.startBuild(source, resolvedRef, cacheKey);
     }
 
     const index = await entry.task;
@@ -237,6 +242,18 @@ export class IndexCache {
     entry.updateChain = entry.updateChain.then(run, run);
   }
 
+  private maybeStartWatcher(source: string): void {
+    if (!mcpWatchEnabled() || isGitUrl(source)) {
+      return;
+    }
+    const resolved = resolve(source);
+    if (this.watchedSource === resolved) {
+      return;
+    }
+    this.watchedSource = resolved;
+    this.startWatcher(resolved);
+  }
+
   startWatcher(path: string): void {
     const resolved = resolve(path);
     if (this.watcher) {
@@ -251,34 +268,33 @@ export class IndexCache {
   close(): void {
     this.watcher?.close();
     this.watcher = null;
+    this.watchedSource = null;
     this.entries.clear();
   }
 }
 
 export async function getIndexForRepo(
   repo: string | null | undefined,
-  defaultSource: string | null,
   cache: IndexCache,
   ref?: string | null,
 ): Promise<MiruIndex> {
-  if (repo && isGitUrl(repo) && !repo.startsWith("https://") && !repo.startsWith("http://")) {
+  if (!repo) {
     throw new Error(
-      `Only https://, http://, or local directory paths are accepted as \`repo\`. Got: ${repo}`,
+      "Pass an https:// or http:// git URL or local directory path as `repo` (project root for local workspaces).",
     );
   }
 
-  const source = repo ?? defaultSource;
-  if (!source) {
+  if (isGitUrl(repo) && !repo.startsWith("https://") && !repo.startsWith("http://")) {
     throw new Error(
-      "No repo specified and no default index. Pass an https:// or http:// git URL or local directory path as `repo`.",
+      `Only https://, http://, or local directory paths are accepted as \`repo\`. Got: ${repo}`,
     );
   }
 
   try {
-    return await cache.get(source, ref);
+    return await cache.get(repo, ref);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to index ${source}: ${message}`);
+    throw new Error(`Failed to index ${repo}: ${message}`);
   }
 }
 

package/src/mcp/serve.ts

@@ -1,24 +1,14 @@
-import { resolve } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import type { ContentType } from "../types.ts";
-import { isGitUrl } from "../utils.ts";
-import { IndexCache, mcpWatchEnabled } from "./index-cache.ts";
+import { IndexCache } from "./index-cache.ts";
 import { createMcpServer } from "./server.ts";
 
 export async function serveMcp(options: {
-  path?: string | null;
   ref?: string | null;
   content?: ContentType[];
 }): Promise<void> {
-  const cache = new IndexCache(options.content ?? ["code"]);
-  const defaultSource = options.path ?? resolve(process.cwd());
-
-  void cache.get(defaultSource, options.ref).catch(() => undefined);
-  if (!isGitUrl(defaultSource) && mcpWatchEnabled()) {
-    cache.startWatcher(defaultSource);
-  }
-
-  const server = createMcpServer(cache, defaultSource);
+  const cache = new IndexCache(options.content ?? ["code"], options.ref ?? null);
+  const server = createMcpServer(cache);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/mcp/server.ts

@@ -6,17 +6,17 @@ import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 
 const REPO_DESCRIPTION =
   "https:// or http:// git URL (e.g. https://github.com/org/repo) or local directory path to index and search. " +
-  "Required when no default index was configured at startup. " +
-  "The index is cached after the first call, so repeat queries are fast.";
+  "Pass the project root for local workspaces. " +
+  "The index is built on the first tool call and cached for the session.";
 
 const SERVER_INSTRUCTIONS =
   "Instant code search for any local or remote git repository. " +
   "Call `search` to find relevant code; call `find_related` on a result to discover similar code elsewhere. " +
-  "When working in a local project, pass the project root as `repo`. " +
-  "For remote repos, pass an explicit https:// URL. Never guess or infer URLs. " +
+  "Always pass the project root as `repo` on the first call (local path or https:// git URL). " +
+  "Never guess or infer URLs. " +
   "Prefer these tools over Grep, Glob, or Read for any question about how code works.";
 
-export function createMcpServer(cache: IndexCache, defaultSource: string | null = null): McpServer {
+export function createMcpServer(cache: IndexCache): McpServer {
   const server = new McpServer(
     {
       name: "miru",
@@ -32,16 +32,16 @@ export function createMcpServer(cache: IndexCache, defaultSource: string | null
     {
       description:
         "Search a codebase with a natural-language or code query. " +
-        "Pass a git URL or local path as `repo` to index it on demand; indexes are cached for the session.",
+        "Indexes `repo` on the first call; later calls reuse the session cache.",
       inputSchema: {
         query: z.string().describe("Natural language or code query."),
-        repo: z.string().nullable().optional().describe(REPO_DESCRIPTION),
+        repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z.number().int().min(1).optional().describe("Number of results to return."),
       },
     },
     async ({ query, repo, top_k: topK }) => {
       try {
-        const index = await getIndexForRepo(repo ?? null, defaultSource, cache);
+        const index = await getIndexForRepo(repo, cache);
         const results = await index.search({ query, topK: topK ?? 5 });
         if (results.length === 0) {
           return toolText(JSON.stringify({ error: "No results found." }));
@@ -66,13 +66,13 @@ export function createMcpServer(cache: IndexCache, defaultSource: string | null
             "Path to the file as stored in the index (use file_path from a search result).",
           ),
         line: z.number().int().describe("Line number (1-indexed)."),
-        repo: z.string().nullable().optional().describe(REPO_DESCRIPTION),
+        repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z.number().int().min(1).optional().describe("Number of similar chunks to return."),
       },
     },
     async ({ file_path: filePath, line, repo, top_k: topK }) => {
       try {
-        const index = await getIndexForRepo(repo ?? null, defaultSource, cache);
+        const index = await getIndexForRepo(repo, cache);
         const chunk = resolveChunk(index.chunks, filePath, line);
         if (!chunk) {
           return toolText(

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) {