opencode-readseek 0.8.21 → 0.8.22

package/index.ts

@@ -27,15 +27,15 @@ const PREFERRED_TOOL_DESCRIPTIONS: Record<string, string> = {
   readseek_read: "Preferred file reader; returns LINE:HASH anchors for durable references.",
   readseek_edit: "Preferred tool for editing existing text files with fresh LINE:HASH anchors.",
   readseek_write: "Preferred tool for creating or replacing a complete text file; returns LINE:HASH anchors.",
-  readseek_rename: "Preferred tool for renaming a symbol while preserving same-named bindings.",
+  readseek_rename: "Use to rename a symbol with binding-aware, verified edits.",
   readseek_grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
-  readseek_search: "Preferred AST search for code shapes and call sites.",
-  readseek_map: "Preferred symbol outline for a source file.",
-  readseek_def: "Preferred symbol definition lookup.",
-  readseek_refs: "Preferred identifier usage finder; use before rename or delete.",
-  readseek_hover: "Preferred cursor token and enclosing-symbol inspector.",
-  readseek_view: "Preferred PDF structure and content viewer.",
-  readseek_check: "Preferred quick syntax check after source edits.",
+  readseek_search: "Use for AST or structural code search with ast-grep-style patterns.",
+  readseek_map: "Use to inspect a source file's symbol outline without reading the whole file.",
+  readseek_def: "Use for go-to-definition or declaration lookup by name.",
+  readseek_refs: "Use to find identifier-name matches or binding-specific references before rename or delete.",
+  readseek_hover: "Use to inspect symbol identity at a source location.",
+  readseek_view: "Use to inspect PDF structure or selected content.",
+  readseek_check: "Use for a quick parser syntax check after source edits; unsupported languages are not validated.",
 };
 const FALLBACK_TOOL_DESCRIPTIONS: Record<string, string> = {
   read: "Fallback only. Prefer readseek_read so edits can use LINE:HASH anchors.",
@@ -316,6 +316,39 @@ function readSeekBinaryPath(): string {
   return path.join(path.dirname(packageJson), "bin", process.platform === "win32" ? "readseek.exe" : "readseek");
 }
 
+async function readBoundedText(
+  stream: ReadableStream<Uint8Array>,
+  streamName: "stdout" | "stderr",
+  onOverflow: () => void,
+): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > MAX_OUTPUT_BYTES) {
+        onOverflow();
+        void reader.cancel().catch(() => undefined);
+        throw new Error(`readseek ${streamName} exceeded the ${MAX_OUTPUT_BYTES}-byte output limit`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
 async function runReadSeekRaw(
   context: ToolContext,
   args: string[],
@@ -325,7 +358,6 @@ async function runReadSeekRaw(
   const cancelable = options.cancelable !== false;
   const spawnOptions = {
     cwd: context.directory,
-    maxBuffer: MAX_OUTPUT_BYTES,
     stderr: "pipe" as const,
     stdout: "pipe" as const,
   };
@@ -335,9 +367,19 @@ async function runReadSeekRaw(
       ? { ...spawnOptions, killSignal: "SIGKILL" as const, signal: context.abort }
       : spawnOptions,
   );
+  let killedForOverflow = false;
+  const killForOverflow = () => {
+    if (killedForOverflow) return;
+    killedForOverflow = true;
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Preserve the output-limit error if the process exited concurrently.
+    }
+  };
   const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
+    readBoundedText(child.stdout, "stdout", killForOverflow),
+    readBoundedText(child.stderr, "stderr", killForOverflow),
     child.exited,
   ]);
   if (cancelable) context.abort.throwIfAborted();
@@ -358,6 +400,25 @@ async function runReadSeek(
   }
 }
 
+async function postMutationPreview(
+  context: ToolContext,
+  args: string[],
+  filePath: string,
+  changed: boolean,
+): Promise<unknown> {
+  try {
+    return await runReadSeek(context, args, { cancelable: false });
+  } catch (error) {
+    const previewError = error instanceof Error ? error.message : String(error);
+    return {
+      file: filePath,
+      changed,
+      preview_error: previewError,
+      warning: "File mutation completed, but the post-write preview failed. Do not retry the mutation; read the file to verify content and refresh anchors.",
+    };
+  }
+}
+
 let readSeekCacheInit: Promise<string> | undefined;
 
 function readSeekCacheDir(): string {
@@ -954,8 +1015,10 @@ function resultPresentation(kind: PresentationKind, args: any, value: unknown):
       return { title, metadata: { edits, conflicts, others } };
     }
     case "edit":
-    case "write":
-      return { title: `${kind === "edit" ? "Edited" : "Wrote"} ${args.path}`, metadata: {} };
+    case "write": {
+      const preview = typeof output.preview_error === "string" ? " (preview unavailable)" : "";
+      return { title: `${kind === "edit" ? "Edited" : "Wrote"} ${args.path}${preview}`, metadata: {} };
+    }
     case "check": {
       const errors = typeof output.error_count === "number" ? output.error_count : 0;
       const missing = typeof output.missing_count === "number" ? output.missing_count : 0;
@@ -1064,7 +1127,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         formatReadResult,
       ),
       readseek_view: readseekTool(
-        "View PDF structure or selected content. Start with the overview, then narrow by page or node.",
+        "Inspect a PDF's structure or selected content. Start with the overview, then narrow by page, node, kind, or depth instead of reading the whole document.",
         {
           path: tool.schema.string().describe("PDF path relative to the project directory"),
           node: tool.schema.string().min(1).optional().describe("Node ID to use as the view root"),
@@ -1089,7 +1152,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         (result) => ({ output: boundDocumentOutput(String(result)) }),
       ),
       readseek_map: readseekTool(
-        "Show a source file's symbol outline without reading the full file.",
+        "Inspect a source file's symbol outline. Use this instead of reading the whole file when only declarations, names, kinds, and ranges are needed.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
@@ -1141,32 +1204,55 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
           const contextLines = (input.context as number | undefined) ?? 0;
           const results: { file: string; matches: unknown[]; hashlines: unknown[] }[] = [];
           let totalMatches = 0;
+          let truncated = false;
           for (const filePath of files.sort()) {
             context.abort.throwIfAborted();
-            if (totalMatches >= maxMatches) break;
+            if (truncated) break;
             const buffer = await readFile(filePath);
             if (buffer.includes(0)) continue;
             const lines = buffer.toString("utf8").replace(/\r\n/g, "\n").split("\n");
+            const matchLines = new Set<number>();
             const ranges: [number, number][] = [];
-            for (let index = 0; index < lines.length && totalMatches < maxMatches; index++) {
+            for (let index = 0; index < lines.length; index++) {
               expression.lastIndex = 0;
               if (!expression.test(lines[index] ?? "")) continue;
-              ranges.push([Math.max(1, index + 1 - contextLines), Math.min(lines.length, index + 1 + contextLines)]);
+              if (totalMatches === maxMatches) {
+                truncated = true;
+                break;
+              }
+              const line = index + 1;
+              matchLines.add(line);
+              ranges.push([Math.max(1, line - contextLines), Math.min(lines.length, line + contextLines)]);
               totalMatches++;
             }
             if (ranges.length === 0) continue;
-            const matches: unknown[] = [];
+
+            const mergedRanges: [number, number][] = [];
             for (const [start, end] of ranges) {
+              const previous = mergedRanges.at(-1);
+              if (previous && start <= previous[1] + 1) previous[1] = Math.max(previous[1], end);
+              else mergedRanges.push([start, end]);
+            }
+            const linesByNumber = new Map<number, unknown>();
+            for (const [start, end] of mergedRanges) {
               const output = record(await runReadSeek(context, ["read", `${filePath}:${start}`, "--end", String(end)]));
-              matches.push(...items(output.hashlines));
+              for (const hashline of items(output.hashlines)) {
+                const line = record(hashline).line;
+                if (typeof line === "number" && !linesByNumber.has(line)) linesByNumber.set(line, hashline);
+              }
             }
-            results.push({ file: filePath, matches, hashlines: matches });
+            const hashlines = [...linesByNumber.values()];
+            const matches = hashlines.filter((hashline) => {
+              const line = record(hashline).line;
+              return typeof line === "number" && matchLines.has(line);
+            });
+            results.push({ file: filePath, matches, hashlines });
           }
-          return { results, truncated: totalMatches >= maxMatches };
+          return { results, truncated };
         },
       ),
       readseek_search: readseekTool(
-        "Search AST patterns (ast-grep style) and return LINE:HASH anchors. Use for code structure; use readseek_grep for plain text.",
+        "Search code by AST structure using ast-grep-style patterns. Results include edit-ready LINE:HASH anchors. Use readseek_grep for identifiers, strings, comments, configuration, documentation, or other plain text and regex.",
         {
           pattern: tool.schema.string().describe("AST pattern (ast-grep style), such as console.log($$$ARGS)"),
           path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
@@ -1187,7 +1273,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_def: readseekTool(
-        "Find symbol declarations by name and return LINE:HASH anchors. Prefer this to text search for definitions.",
+        "Go to a symbol definition or declaration by name. Accepts qualified or unqualified names and returns LINE:HASH anchors; use this instead of text search for functions, methods, classes, types, and other declarations.",
         {
           name: tool.schema.string().describe("Symbol name"),
           path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
@@ -1207,7 +1293,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_refs: readseekTool(
-        "Find identifier usages with enclosing symbols. Use before renaming or deleting a symbol; add cursor scope to exclude same-named bindings.",
+        "Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and edit-ready LINE:HASH anchors. Without cursor scope, results are identifier-name matches; with scope, they follow one binding and exclude shadows. Use text search for literal occurrences in strings or comments, and use this tool before renaming or deleting a symbol.",
         {
           name: tool.schema.string().describe("Identifier name"),
           path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
@@ -1237,7 +1323,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_hover: readseekTool(
-        "Identify the token and enclosing symbol at a cursor. Use before definition lookup or rename.",
+        "Inspect the symbol at a source location. This identifies the token and enclosing symbol; use it before definition lookup or binding-specific references.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           line: tool.schema.number().int().positive().describe("One-based cursor line"),
@@ -1255,14 +1341,14 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_rename: readseekTool(
-        "Rename the symbol at a cursor while preserving same-named bindings. Applies verified edits atomically by default; set apply to false for a dry-run plan.",
+        "Rename a symbol at a source location. Resolvable same-named bindings are preserved; verified edits apply by default. Set `apply` to false to preview the plan before changing files.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           line: tool.schema.number().int().positive().describe("One-based cursor line of the symbol to rename"),
           column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column for disambiguation"),
           to: tool.schema.string().min(1).describe("New symbol name"),
           workspace: tool.schema.boolean().optional().describe("Include project-wide occurrences"),
-          apply: tool.schema.boolean().optional().describe("Apply verified edits atomically; defaults to true"),
+          apply: tool.schema.boolean().optional().describe("Apply verified edits; defaults to true"),
         },
         "rename",
         async (input, context) => {
@@ -1326,10 +1412,11 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
             if (before !== after) await writeText(filePath, { exists: true, content: before }, after);
             const firstEditedLine = Math.min(...edits.flatMap((edit) => anchorRefs(edit).map((ref) => ref.line)));
             const previewStart = Math.max(1, firstEditedLine - 3);
-            return runReadSeek(
+            return postMutationPreview(
               context,
               ["read", `${filePath}:${previewStart}`, "--end", String(previewStart + EDIT_RESULT_READ_LIMIT - 1)],
-              { cancelable: false },
+              filePath,
+              before !== after,
             );
           });
         },
@@ -1353,12 +1440,17 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
             await authorizeEdit(context, [filePath], simpleDiff(filePath, before.content, content), false);
             context.abort.throwIfAborted();
             await writeText(filePath, before, content);
-            return runReadSeek(context, ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)], { cancelable: false });
+            return postMutationPreview(
+              context,
+              ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)],
+              filePath,
+              !before.exists || before.content !== content,
+            );
           });
         },
       ),
       readseek_check: readseekTool(
-        "Run a quick syntax check on a source file. Reports parser errors and missing syntax; not a compiler or linter.",
+        "Check a source file for parser errors or missing syntax after edits. Validation requires a supported tree-sitter language; files without a supported parser are not checked. This is not a compiler, type checker, test runner, or linter.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-readseek",
-  "version": "0.8.21",
+  "version": "0.8.22",
   "description": "OpenCode plugin for anchored file operations and structural code navigation",
   "type": "module",
   "main": "./index.ts",
@@ -31,7 +31,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.8.21",
+    "@jarkkojs/readseek": "^0.8.22",
     "@opencode-ai/plugin": "^1.17.20"
   },
   "devDependencies": {