opencode-readseek 0.8.22 → 0.8.24

package/index.ts

@@ -1152,7 +1152,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         (result) => ({ output: boundDocumentOutput(String(result)) }),
       ),
       readseek_map: readseekTool(
-        "Inspect a source file's symbol outline. Use this instead of reading the whole file when only declarations, names, kinds, and ranges are needed.",
+        "Inspect a source file's symbol outline. Use this instead of reading the whole file when only declarations, names, kinds, ranges, and line hashes 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"),
@@ -1167,14 +1167,14 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_grep: readseekTool(
-        "Search text or regex and return matching LINE:HASH anchors. Set literal for exact text.",
+        "Search text or regex in files and return matching LINE:HASH anchors. Set literal for exact text. Use for identifiers, strings, configuration, errors, comments, and documentation.",
         {
-          pattern: tool.schema.string().describe("Text or regular expression to search for"),
-          path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
+          pattern: tool.schema.string().describe("Text or regular expression to search for; set literal for exact text"),
+          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
           glob: tool.schema.string().optional().describe("File-name glob, such as **/*.ts"),
           literal: tool.schema.boolean().optional().describe("Treat pattern as literal text"),
           ignoreCase: tool.schema.boolean().optional().describe("Ignore case"),
-          context: tool.schema.number().int().nonnegative().optional().describe("Surrounding lines to return"),
+          context: tool.schema.number().int().nonnegative().optional().describe("Surrounding lines for each match"),
           limit: tool.schema.number().int().positive().optional().describe("Maximum matching lines; defaults to 100"),
         },
         "grep",
@@ -1252,14 +1252,14 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_search: readseekTool(
-        "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.",
+        "Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as 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"),
+          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          cached: tool.schema.boolean().optional().describe("Search tracked or indexed files in a Git repository"),
-          others: tool.schema.boolean().optional().describe("Search untracked files in a Git repository"),
-          ignored: tool.schema.boolean().optional().describe("Include ignored untracked files; requires others"),
+          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
+          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
+          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
         },
         "search",
         async (input, context) => {
@@ -1273,14 +1273,14 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_def: readseekTool(
-        "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.",
+        "Go to a symbol definition or declaration by name. Accepts qualified or unqualified names; 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"),
+          name: tool.schema.string().describe("Qualified or unqualified symbol name"),
+          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
-          cached: tool.schema.boolean().optional().describe("Search tracked or indexed files in a Git repository"),
-          others: tool.schema.boolean().optional().describe("Search untracked files in a Git repository"),
-          ignored: tool.schema.boolean().optional().describe("Include ignored untracked files; requires others"),
+          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
+          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
+          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
         },
         "def",
         async (input, context) => {
@@ -1293,17 +1293,17 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_refs: readseekTool(
-        "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.",
+        "Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and line hashes usable as 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"),
+          name: tool.schema.string().describe("Identifier to find references for"),
+          path: tool.schema.string().optional().describe("File or directory to search; defaults to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
           scope: tool.schema.boolean().optional().describe("Restrict results to the binding at the cursor"),
-          line: tool.schema.number().int().positive().optional().describe("Cursor line, required with scope"),
-          column: tool.schema.number().int().positive().optional().describe("Cursor byte column for disambiguation"),
-          cached: tool.schema.boolean().optional().describe("Search tracked or indexed files in a Git repository"),
-          others: tool.schema.boolean().optional().describe("Search untracked files in a Git repository"),
-          ignored: tool.schema.boolean().optional().describe("Include ignored untracked files; requires others"),
+          line: tool.schema.number().int().positive().optional().describe("One-based cursor line; required with scope"),
+          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column for disambiguation"),
+          cached: tool.schema.boolean().optional().describe("In a Git repository, search tracked/indexed files"),
+          others: tool.schema.boolean().optional().describe("In a Git repository, search untracked files"),
+          ignored: tool.schema.boolean().optional().describe("With others=true, include ignored untracked files"),
         },
         "refs",
         async (input, context) => {
@@ -1327,7 +1327,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           line: tool.schema.number().int().positive().describe("One-based cursor line"),
-          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column"),
+          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column for disambiguation"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
         },
         "hover",
@@ -1341,14 +1341,14 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_rename: readseekTool(
-        "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.",
+        "Rename a symbol at a source location. Resolvable same-named bindings are preserved; verified edits apply by default. Set `apply: 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; defaults to true"),
+          workspace: tool.schema.boolean().optional().describe("Rename across the project"),
+          apply: tool.schema.boolean().optional().describe("Apply the verified edits; defaults to true"),
         },
         "rename",
         async (input, context) => {
@@ -1376,24 +1376,30 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_edit: readseekTool(
-        "Edit an existing text file with fresh LINE:HASH anchors. Stale hashes are rejected before writing.",
+        "Edit an existing text file with fresh LINE:HASH anchors. Supports set_line, replace_lines, and insert_after only. Stale hashes are rejected before writing.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           edits: tool.schema.array(tool.schema.union([
             tool.schema.object({
-              set_line: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }).strict(),
+              set_line: tool.schema.object({
+                anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the line to replace"),
+                new_text: tool.schema.string().describe("Replacement text; use an empty string to delete the line"),
+              }).strict(),
             }).strict(),
             tool.schema.object({
               replace_lines: tool.schema.object({
-                start_anchor: tool.schema.string(),
-                end_anchor: tool.schema.string(),
-                new_text: tool.schema.string(),
+                start_anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the first line in the range"),
+                end_anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the last line in the range"),
+                new_text: tool.schema.string().describe("Replacement text; use an empty string to delete the range"),
               }).strict(),
             }).strict(),
             tool.schema.object({
-              insert_after: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }).strict(),
+              insert_after: tool.schema.object({
+                anchor: tool.schema.string().describe("Fresh LINE:HASH anchor for the line after which to insert"),
+                new_text: tool.schema.string().describe("Text to insert after the anchored line"),
+              }).strict(),
             }).strict(),
-          ])).min(1).describe("LINE:HASH-anchored edits to apply"),
+          ])).min(1).describe("Anchored edits: set_line, replace_lines, or insert_after"),
         },
         "edit",
         async (input, context) => {
@@ -1422,7 +1428,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_write: readseekTool(
-        "Create or replace a whole text file and return LINE:HASH anchors.",
+        "Create or replace a complete text file and return LINE:HASH anchors. Use anchored edits for small changes to an existing file. Binary-looking content is rejected before writing.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           content: tool.schema.string().describe("Complete text file content"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-readseek",
-  "version": "0.8.22",
+  "version": "0.8.24",
   "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.22",
+    "@jarkkojs/readseek": "^0.8.24",
     "@opencode-ai/plugin": "^1.17.20"
   },
   "devDependencies": {