@takara-ai/miru-code 1.0.5 → 1.1.0

package/src/mcp/server.ts

@@ -87,12 +87,10 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z
+        anchor_line: z
           .number()
           .int()
-          .describe(
-            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
-          ),
+          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         before: z
           .number()
@@ -108,7 +106,7 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
           .describe("Extra chunks after the anchor (default 1)."),
       },
     },
-    async ({ file_path: filePath, line, repo, before, after }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo, before, after }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
@@ -117,19 +115,19 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         const { anchor, chunks: expanded } = expandChunksAtLine(
           index.chunks,
           filePath,
-          line,
+          anchorLine,
           repoRoot,
           beforeCount,
           afterCount,
         );
         if (!anchor) {
           return toolText(
-            `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
+            `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
         return toolText(
           JSON.stringify(
-            formatExpandResults(filePath, line, anchor, expanded, {
+            formatExpandResults(filePath, anchorLine, anchor, expanded, {
               repoRoot,
               before: beforeCount,
               after: afterCount,
@@ -150,12 +148,10 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z
+        anchor_line: z
           .number()
           .int()
-          .describe(
-            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
-          ),
+          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z
           .number()
@@ -168,25 +164,25 @@ export function createMcpServer(cache: IndexCache): MiruMcpServer {
           ),
       },
     },
-    async ({ file_path: filePath, line, repo, top_k: topK }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo, top_k: topK }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
-        const chunk = resolveChunk(index.chunks, filePath, line, repoRoot);
+        const chunk = resolveChunk(index.chunks, filePath, anchorLine, repoRoot);
         if (!chunk) {
           return toolText(
-            `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
+            `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
         const results = await index.findRelated(chunk, clampMcpTopK(topK));
         if (results.length === 0) {
           return toolText(
-            JSON.stringify({ error: `No related chunks found for ${filePath}:${line}.` }),
+            JSON.stringify({ error: `No related chunks found for ${filePath}:${anchorLine}.` }),
           );
         }
         return toolText(
           JSON.stringify(
-            formatResults(`Chunks related to ${filePath}:${line}`, results, {
+            formatResults(`Chunks related to ${filePath}:${anchorLine}`, results, {
               repoRoot,
               snippet: true,
             }),

package/src/miru-index.ts

@@ -9,6 +9,7 @@ import {
 } from "./embeddings/openai.ts";
 import { cloneGitRepository } from "./git.ts";
 import type { BM25Index } from "./index/bm25.ts";
+import { buildChunkSelector } from "./index/chunk-selector.ts";
 import { createIndexFromPath } from "./index/create.ts";
 import { applyIncrementalFileChanges } from "./index/incremental.ts";
 import { persistencePaths, saveIndexBundle } from "./index/persistence.ts";
@@ -19,27 +20,71 @@ import { chunkKey, chunkToDict } from "./types.ts";
 import { computeSourceCacheKey, isGitUrl } from "./utils.ts";
 import { indexCacheEpoch } from "./version.ts";
 
+/**
+ * In-memory search index over a codebase: BM25 keyword scores plus semantic
+ * embeddings, with optional disk cache for reuse across runs.
+ *
+ * Construct via `fromPath`, `fromGit`, or `fromSource`; load a saved bundle
+ * with `loadFromDisk`. Search combines both signals; `findRelated` is
+ * semantic-only similarity from an existing chunk or hit.
+ *
+ * Lifecycle:
+ * - **Build** — parse files, chunk, embed, score with BM25
+ * - **Cache** — `save` writes a bundle keyed by source path or git URL + ref
+ * - **Query** — `search` blends BM25 and vectors; filters use prebuilt mappings
+ * - **Update** — `applyFileChanges` re-indexes only touched paths (local roots)
+ */
 export class MiruIndex {
+  /** OpenAI (or configured) client used for query embeddings and reranking. */
   readonly embeddings: EmbeddingBackend;
+
+  /** Flat list of all chunks; index position is the stable chunk id. */
   private chunksInternal: Chunk[];
+
+  /** Inverted index for lexical (BM25) retrieval. */
   private bm25Index: BM25Index;
+
+  /** Vector store for semantic nearest-neighbor search. */
   private semanticIndex: SemanticIndex;
+
+  /**
+   * True when hydrated from disk via `loadFromDisk`.
+   * Affects `saveToCache`, which skips re-saving already-cached indexes unless forced.
+   */
   private loadedFromDiskFlag: boolean;
 
+  /** Model id stored in cache metadata and used for new embeddings. */
   readonly embeddingModel: string;
+
+  /**
+   * Absolute path to the indexed tree on disk, or `null` for git-only indexes
+   * (clone is deleted after indexing; incremental updates need a local root).
+   */
   private readonly root: string | null;
+
+  /** Content kinds indexed at build time (e.g. `code`, `markdown`). */
   private readonly content: ContentType[];
+
+  /** Repo-relative file path → chunk indices in `chunksInternal`. */
   private fileMapping: Map<string, number[]>;
+
+  /** Language tag → chunk indices, for `filterLanguages` in search. */
   private languageMapping: Map<string, number[]>;
 
+  /** Read-only view of indexed chunks. */
   get chunks(): Chunk[] {
     return this.chunksInternal;
   }
 
+  /** Whether this instance was loaded from a cache bundle rather than freshly built. */
   get loadedFromDisk(): boolean {
     return this.loadedFromDiskFlag;
   }
 
+  /**
+   * Prefer static factories (`fromPath`, `fromGit`, `loadFromDisk`) over calling
+   * directly; the constructor is public for tests and advanced composition.
+   */
   constructor(options: {
     embeddings: EmbeddingBackend;
     bm25Index: BM25Index;
@@ -63,6 +108,10 @@ export class MiruIndex {
     this.rebuildMappings();
   }
 
+  /**
+   * Rebuild file/language → chunk-index maps after chunks change.
+   * Called from the constructor and after incremental updates.
+   */
   private rebuildMappings(): void {
     this.fileMapping = new Map();
     this.languageMapping = new Map();
@@ -85,6 +134,12 @@ export class MiruIndex {
     }
   }
 
+  /**
+   * Clone a remote repo, index it, persist to cache, and return the in-memory index.
+   *
+   * Cache key is derived from URL + ref. On hit, skips clone and embedding work.
+   * The temporary clone directory is always removed in `finally`.
+   */
   static async fromGit(
     url: string,
     content: ContentType[] = ["code"],
@@ -113,6 +168,7 @@ export class MiruIndex {
         semanticIndex: semantic,
         chunks,
         embeddingModel: model,
+        // No durable local root — clone is deleted; incremental updates unavailable.
         root: null,
         content,
       });
@@ -123,6 +179,7 @@ export class MiruIndex {
     }
   }
 
+  /** Resolve a local path or git URL and delegate to `fromPath` or `fromGit`. */
   static async fromSource(
     source: string,
     content: ContentType[] = ["code"],
@@ -135,6 +192,13 @@ export class MiruIndex {
     return MiruIndex.fromPath(source, content, embeddingModel);
   }
 
+  /**
+   * Index a directory on disk, reusing a validated cache hit when available.
+   *
+   * `root` is set to the resolved path so `applyFileChanges` can re-chunk files
+   * later. Unlike `fromGit`, this does not auto-save to cache; callers use
+   * `saveToCache` when they want persistence.
+   */
   static async fromPath(
     path: string,
     content: ContentType[] = ["code"],
@@ -178,6 +242,12 @@ export class MiruIndex {
     });
   }
 
+  /**
+   * Hydrate BM25, semantic vectors, and chunks from a saved index bundle.
+   *
+   * Validates embedding model compatibility via cache metadata. Sets
+   * `loadedFromDisk` so callers can avoid redundant cache writes.
+   */
   static async loadFromDisk(path: string, embeddingModel?: string): Promise<MiruIndex> {
     const model = embeddingModel ?? resolveEmbeddingModel();
     const { bm25, semantic, chunks, metadata } = await loadCachedIndex(path);
@@ -196,6 +266,12 @@ export class MiruIndex {
     });
   }
 
+  /**
+   * Write BM25, semantic vectors, chunk metadata, and index metadata to `path`.
+   *
+   * Metadata includes `index_epoch` for invalidation when Miru's on-disk format
+   * changes, plus embedding model/dimensions for cache validation on reload.
+   */
   async save(path: string): Promise<void> {
     const paths = persistencePaths(path);
     await mkdir(paths.root, { recursive: true });
@@ -218,17 +294,24 @@ export class MiruIndex {
     });
   }
 
-  async saveToDefaultCache(sourcePath: string): Promise<void> {
-    if (!this.loadedFromDiskFlag) {
+  /**
+   * Persist to the default cache location for `sourcePath`.
+   *
+   * By default this is a no-op for unchanged indexes loaded from disk, avoiding
+   * redundant cache writes. Pass `force: true` after mutating a cached index.
+   */
+  async saveToCache(sourcePath: string, options: { force?: boolean } = {}): Promise<void> {
+    if (!this.loadedFromDiskFlag || options.force) {
       await this.save(findIndexCachePath(sourcePath));
     }
   }
 
-  async persistToCache(sourcePath: string): Promise<void> {
-    await this.save(findIndexCachePath(sourcePath));
-  }
-
-  /** Re-chunk and re-embed only the given repo-relative paths; drop their old chunks. */
+  /**
+   * Re-chunk and re-embed only the given repo-relative paths; drop their old chunks.
+   *
+   * Requires `root` (local `fromPath` indexes only). Updates BM25, semantic
+   * index, and mappings in place; clears `loadedFromDisk` since data changed.
+   */
   async applyFileChanges(relativePaths: readonly string[]): Promise<void> {
     if (!this.root) {
       throw new Error("Incremental update requires a local index with root_path set.");
@@ -253,20 +336,27 @@ export class MiruIndex {
     this.rebuildMappings();
   }
 
-  private getSelector(filterLanguages?: string[], filterPaths?: string[]): number[] | undefined {
-    const selector: number[] = [];
-    for (const lang of filterLanguages ?? []) {
-      selector.push(...(this.languageMapping.get(lang) ?? []));
-    }
-    for (const fp of filterPaths ?? []) {
-      selector.push(...(this.fileMapping.get(fp) ?? []));
-    }
-    if (selector.length === 0) {
-      return undefined;
-    }
-    return [...new Set(selector)];
+  private getSelector(
+    filterLanguages?: string[],
+    filterPaths?: string[],
+  ): readonly number[] | undefined {
+    return buildChunkSelector(
+      {
+        fileMapping: this.fileMapping,
+        languageMapping: this.languageMapping,
+      },
+      filterLanguages,
+      filterPaths,
+    );
   }
 
+  /**
+   * Hybrid BM25 + semantic search over indexed chunks.
+   *
+   * `alpha` blends keyword vs vector scores (default depends on content type).
+   * `filterLanguages` / `filterPaths` restrict candidates before ranking.
+   * `rerank` defaults to on for code indexes (cross-encoder style reranking).
+   */
   async search(options: {
     query: string;
     topK?: number;
@@ -296,6 +386,13 @@ export class MiruIndex {
     });
   }
 
+  /**
+   * Semantic neighbors of a chunk or search hit, excluding the source itself.
+   *
+   * Uses the chunk's text as the query embedding. When the source has a
+   * language, search is scoped to same-language chunks. Requests `topK + 1`
+   * hits so filtering out the source still yields `topK` results.
+   */
   async findRelated(source: Chunk | SearchResult, topK = 5): Promise<SearchResult[]> {
     const target = "chunk" in source ? source.chunk : source;
     const selector = target.language ? this.getSelector([target.language]) : undefined;

package/src/search.ts

@@ -35,7 +35,7 @@ function semanticFromQueryVector(
   semanticIndex: SemanticIndex,
   chunks: Chunk[],
   topK: number,
-  selector?: number[],
+  selector?: readonly number[],
 ): SearchResult[] {
   const { indices, distances } = semanticIndex.query(queryVec, topK, selector);
   return indices.flatMap((index, i) => {
@@ -52,7 +52,7 @@ async function searchBm25(
   bm25Index: BM25Index,
   chunks: Chunk[],
   topK: number,
-  selector?: number[],
+  selector?: readonly number[],
 ): Promise<SearchResult[]> {
   const tokens = tokenize(query);
   if (tokens.length === 0) {
@@ -79,7 +79,7 @@ export async function hybridSearch(options: {
   chunks: Chunk[];
   topK: number;
   alpha?: number | null;
-  selector?: number[];
+  selector?: readonly number[];
   rerank?: boolean;
 }): Promise<SearchResult[]> {
   const {
@@ -170,7 +170,7 @@ export async function searchSemanticOnly(options: {
   semanticIndex: SemanticIndex;
   chunks: Chunk[];
   topK: number;
-  selector?: number[];
+  selector?: readonly number[];
 }): Promise<SearchResult[]> {
   const queryVec = await options.embeddings.embedQuery(options.query);
   return semanticFromQueryVector(

package/src/setup.ts

@@ -1,4 +1,4 @@
-import { brandTitle, divider, fail, hint, info, success, writeStderr } from "./cli-ui.ts";
+import { divider, fail, hint, info, printBrandBanner, success, writeStderr } from "./cli-ui.ts";
 import {
   clearStoredCredentials,
   loadStoredCredentials,
@@ -55,7 +55,8 @@ export async function runSetup(options: RunSetupOptions = {}): Promise<RunSetupR
   }
 
   writeStderr("");
-  writeStderr(`${brandTitle()} setup`);
+  // stderr banner: setup runs before stdout may be a TTY (e.g. piped miru search).
+  printBrandBanner(process.stderr);
   divider("─", 48, process.stderr);
   writeStderr("Miru needs a Takara API key for code embeddings.");
   hint("Get a bearer token from Takara, then enter it below.");
@@ -129,6 +130,11 @@ export async function ensureCredentials(options?: { interactive?: boolean }): Pr
     return;
   }
 
+  writeStderr("");
+  // Brand on stderr when credentials are missing in non-interactive mode (stdout may not be a TTY).
+  printBrandBanner(process.stderr);
+  writeStderr("");
+
   throw new Error(
     "Takara API key required. Run `miru setup` in a terminal, or set TAKARA_API_KEY " +
       "in your MCP server env (Cursor mcp.json) or .env.local.",

package/src/terminal.ts

@@ -0,0 +1,171 @@
+/**
+ * Terminal helpers: ANSI styling, display-width layout, and brand RGB colors.
+ * Brand colors use truecolor when COLORTERM says so; otherwise 256-color palette
+ * (Terminal.app often omits COLORTERM but still renders 38;5 correctly).
+ */
+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;
+
+export function colorEnabled(stream: NodeJS.WriteStream = process.stdout): boolean {
+  // https://no-color.org — any NO_COLOR value disables styling.
+  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}`;
+}
+
+const style =
+  (code: string) =>
+  (text: string, stream?: NodeJS.WriteStream): string =>
+    paint(text, code, stream);
+
+export const bold = style(ANSI.bold);
+export const dim = style(ANSI.dim);
+export const cyan = style(ANSI.cyan);
+export const green = style(ANSI.green);
+export const red = style(ANSI.red);
+export const yellow = style(ANSI.yellow);
+export const magenta = style(ANSI.magenta);
+
+function charWidth(codePoint: number): number {
+  // East Asian and emoji runes count as two columns in most terminals.
+  if (codePoint === 0) {
+    return 0;
+  }
+  if (
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) ||
+    codePoint === 0xfeff
+  ) {
+    return 0;
+  }
+  if (
+    (codePoint >= 0x1100 && codePoint <= 0x115f) ||
+    (codePoint >= 0x2e80 && codePoint <= 0x303e) ||
+    (codePoint >= 0x3041 && codePoint <= 0x33ff) ||
+    (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+    (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+    (codePoint >= 0xa000 && codePoint <= 0xa4cf) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe4f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+export function displayWidth(text: string): number {
+  // Ignore ANSI SGR sequences when measuring layout width.
+  let width = 0;
+  let inEscape = false;
+  for (const char of text) {
+    if (inEscape) {
+      if (char === "m") {
+        inEscape = false;
+      }
+      continue;
+    }
+    if (char === "\x1b") {
+      inEscape = true;
+      continue;
+    }
+    width += charWidth(char.codePointAt(0) ?? 0);
+  }
+  return width;
+}
+
+export function padLineToWidth(text: string, width: number): string {
+  const pad = Math.max(0, width - displayWidth(text));
+  return `${text}${" ".repeat(pad)}`;
+}
+
+/** Parse `#rrggbb` into `[r, g, b]` for terminal truecolor/256-color SGR. */
+export function hexToRgb(hex: string): readonly [number, number, number] {
+  const normalized = hex.trim().replace(/^#/, "");
+  if (!/^[0-9a-fA-F]{6}$/.test(normalized)) {
+    throw new Error(`Invalid hex color: ${hex}`);
+  }
+  return [
+    Number.parseInt(normalized.slice(0, 2), 16),
+    Number.parseInt(normalized.slice(2, 4), 16),
+    Number.parseInt(normalized.slice(4, 6), 16),
+  ];
+}
+
+export function cropCommonLeading(rows: readonly string[]): string[] {
+  // Trim shared left margin from sampled art without shifting rows relative to each other.
+  const trimmed = rows.map((row) => row.trimEnd());
+  let minLead = trimmed[0]?.length ?? 0;
+  let hasContent = false;
+
+  for (const row of trimmed) {
+    if (!row.trim()) {
+      continue;
+    }
+    hasContent = true;
+    minLead = Math.min(minLead, row.length - row.trimStart().length);
+  }
+
+  if (!hasContent) {
+    return [...trimmed];
+  }
+  return trimmed.map((row) => row.slice(minLead));
+}
+
+function rgbToAnsi256(r: number, g: number, b: number): number {
+  const avg = Math.round((r + g + b) / 3);
+  if (Math.abs(r - g) <= 3 && Math.abs(g - b) <= 3) {
+    if (avg < 8) {
+      return 16;
+    }
+    if (avg > 248) {
+      return 231;
+    }
+    return Math.round(((avg - 8) / 247) * 24) + 232;
+  }
+  return (
+    16 + 36 * Math.round((r / 255) * 5) + 6 * Math.round((g / 255) * 5) + Math.round((b / 255) * 5)
+  );
+}
+
+function brandSgr(rgb: readonly [number, number, number]): string {
+  const [r, g, b] = rgb;
+  const colorTerm = process.env.COLORTERM?.toLowerCase() ?? "";
+  // termstandard/colors: COLORTERM=truecolor|24bit → 24-bit SGR; else 256-color cube.
+  const truecolor =
+    process.env.FORCE_COLOR === "3" ||
+    colorTerm.includes("truecolor") ||
+    colorTerm.includes("24bit");
+  if (truecolor) {
+    return `\x1b[1;38;2;${r};${g};${b}m`;
+  }
+  return `\x1b[1;38;5;${rgbToAnsi256(r, g, b)}m`;
+}
+
+export function brandColor(
+  text: string,
+  rgb: readonly [number, number, number],
+  stream: NodeJS.WriteStream = process.stdout,
+): string {
+  if (!colorEnabled(stream)) {
+    return text;
+  }
+  return `${brandSgr(rgb)}${text}${ANSI.reset}`;
+}

package/src/version.ts

@@ -1,4 +1,3 @@
-import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import packageJson from "../package.json";
 import { resolveCacheFolder } from "./cache.ts";
@@ -49,13 +48,25 @@ export function isVersionNewer(latest: string, current: string): boolean {
     return latest !== current;
   }
 
-  for (let i = 0; i < 3; i++) {
-    if (a[i]! > b[i]!) {
-      return true;
-    }
-    if (a[i]! < b[i]!) {
-      return false;
-    }
+  const [a0, a1, a2] = a;
+  const [b0, b1, b2] = b;
+  if (a0 > b0) {
+    return true;
+  }
+  if (a0 < b0) {
+    return false;
+  }
+  if (a1 > b1) {
+    return true;
+  }
+  if (a1 < b1) {
+    return false;
+  }
+  if (a2 > b2) {
+    return true;
+  }
+  if (a2 < b2) {
+    return false;
   }
   return false;
 }
@@ -66,7 +77,7 @@ function updateCheckPath(): string {
 
 async function readUpdateCheckCache(): Promise<UpdateCheckCache | null> {
   try {
-    const raw = await readFile(updateCheckPath(), "utf-8");
+    const raw = await Bun.file(updateCheckPath()).text();
     const parsed = JSON.parse(raw) as UpdateCheckCache;
     if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string") {
       return null;
@@ -79,7 +90,7 @@ async function readUpdateCheckCache(): Promise<UpdateCheckCache | null> {
 
 async function writeUpdateCheckCache(latest: string): Promise<void> {
   const payload: UpdateCheckCache = { checkedAt: Date.now(), latest };
-  await writeFile(updateCheckPath(), `${JSON.stringify(payload)}\n`, "utf-8");
+  await Bun.write(updateCheckPath(), `${JSON.stringify(payload)}\n`);
 }
 
 export async function fetchLatestPublishedVersion(): Promise<string> {