opencode-readseek 0.8.18 → 0.8.20

package/README.md

@@ -1,13 +1,13 @@
 # opencode-readseek
 
-<img alt="Screenshot of OpenCode running opencode-readseek" src="screenshot.png" width="800">
+<img alt="OpenCode running opencode-readseek" src="screenshot.png" width="800">
 
-`opencode-readseek` adds ReadSeek's anchored file tools, structural search, and
-symbol navigation to OpenCode.
+`opencode-readseek` adds anchored file operations, structural search, symbol
+navigation, and PDF tools to OpenCode.
 
-## Installation
+## Install
 
-Add the plugin to `opencode.json`:
+Add the package to `opencode.json`:
 
 ```json
 {
@@ -15,29 +15,34 @@ Add the plugin to `opencode.json`:
 }
 ```
 
-OpenCode installs the package and its platform-specific `@jarkkojs/readseek`
-binary dependency with Bun.
+OpenCode installs the package and its platform-specific
+`@jarkkojs/readseek` dependency with Bun.
 
 ## Tools
 
-- `readseek_read`: reads anchored text; PDFs select one page by default.
-- `readseek_edit`: applies hash-verified edits to existing text files.
-- `readseek_write`: creates or replaces complete files.
-- `readseek_grep`: searches text or regular expressions and returns anchors.
-- `readseek_map`, `readseek_search`: map symbols and search AST patterns.
-- `readseek_def`, `readseek_refs`, `readseek_hover`: navigate symbols.
-- `readseek_rename`: applies verified renames by default. Set `apply: false` for a
-  dry run.
-- `readseek_check`: reports parse diagnostics.
-- `readseek_view`: indexes a PDF or narrows an existing index by page, node, kind,
-  or depth.
-
-The plugin requests read, grep, external-directory, and edit permissions as needed.
-File changes invalidate remembered anchors. Compaction state retains fresh paths
-and pending rename plans. Text reads return at most 2,000 lines by default.
-
-OpenCode is instructed to prefer ReadSeek tools over built-in read/edit/write/grep
-and symbol navigation; built-ins remain available as fallbacks.
+| Tool | Purpose |
+| --- | --- |
+| `readseek_read` | Read text with `LINE:HASH` anchors; read images or one PDF page |
+| `readseek_edit` | Apply hash-verified edits to an existing text file |
+| `readseek_write` | Create or replace a complete text file |
+| `readseek_grep` | Search text or regex and return anchors |
+| `readseek_map` | Show a source file's symbol outline |
+| `readseek_search` | Search AST patterns |
+| `readseek_def` | Find symbol definitions |
+| `readseek_refs` | Find identifier usages, optionally scoped to a cursor binding |
+| `readseek_hover` | Identify the token and enclosing symbol at a cursor |
+| `readseek_rename` | Apply a binding-aware rename; set `apply: false` for a dry run |
+| `readseek_check` | Report parser errors and missing syntax |
+| `readseek_view` | View or narrow a structural PDF index |
+
+The plugin requests read, grep, external-directory, and edit permissions as
+needed. Mutations invalidate remembered anchors; compaction preserves fresh
+paths and pending rename plans. Text reads return at most 2,000 lines by
+default.
+
+OpenCode is instructed to prefer ReadSeek over the built-in `read`, `edit`,
+`write`, `grep`, and `apply_patch` tools when ReadSeek can do the job. Built-ins
+remain available as fallbacks.
 
 ## Configuration
 
@@ -49,13 +54,24 @@ Pass options with OpenCode's plugin tuple syntax:
 }
 ```
 
-`imageMode` defaults to `"auto"`, exposing `none`, `all`, `ocr`, `caption`, and
-`objects`. `"on"` omits `none`; `"off"` skips images and PDFs. Omitting `image`
-also skips visual files.
+`imageMode` accepts:
 
-## Licensing
+- `"auto"` (default): expose `none`, `all`, `ocr`, `caption`, and `objects`.
+- `"on"`: expose local analysis modes and omit `none`.
+- `"off"`: skip image and PDF reads.
 
-`opencode-readseek` is licensed under
-[Apache-2.0](https://github.com/jarkkojs/readseek/blob/main/LICENSE-APACHE-2.0).
+Omitting `image` from a read also skips visual files.
+
+## Development
+
+```sh
+bun install
+bun test
+bun run typecheck
+```
+
+## License
+
+`opencode-readseek` is Apache-2.0; see [LICENSE](LICENSE).
 `@jarkkojs/readseek` is licensed separately under
-`Apache-2.0 AND LGPL-2.1-or-later`.
+Apache-2.0 AND LGPL-2.1-or-later.

package/index.ts

@@ -16,33 +16,32 @@ const MAX_DOCUMENT_OUTPUT_BYTES = 256 * 1024;
 const MAX_DOCUMENT_OUTPUT_LINES = 2000;
 const TOOL_POLICY = [
   "ReadSeek tool policy:",
-  "- Prefer readseek_* tools over OpenCode built-ins whenever they can do the job.",
-  "- Prefer readseek_read for text file reads; its LINE:HASH anchors are required by readseek_edit.",
-  "- Prefer readseek_grep for text/regex search and readseek_search for syntax-aware code shapes.",
-  "- Prefer readseek_map, readseek_def, readseek_refs, and readseek_hover for symbol navigation.",
-  "- Prefer readseek_edit for existing text files, readseek_write for whole-file creation or replacement, and readseek_rename for symbol renames.",
-  "- Do not use built-in read, edit, write, grep, or apply_patch when the corresponding ReadSeek tool can perform the change.",
-  "- Use readseek_check after source edits for a quick syntax check.",
+  "- Prefer readseek_* tools over built-ins when they can do the job.",
+  "- Read with readseek_read first; readseek_edit needs fresh LINE:HASH anchors.",
+  "- Use readseek_grep for text/regex, readseek_search for AST patterns, and readseek_map/def/refs/hover for symbol navigation.",
+  "- Use readseek_edit for existing files, readseek_write for whole-file creation or replacement, and readseek_rename for symbol renames.",
+  "- Do not use built-in read, edit, write, grep, or apply_patch when a ReadSeek tool can do the job.",
+  "- Run readseek_check after source edits for a quick syntax check.",
 ].join("\n");
 const PREFERRED_TOOL_DESCRIPTIONS: Record<string, string> = {
-  readseek_read: "Preferred file reader; returns LINE:HASH anchors required by readseek_edit.",
-  readseek_edit: "Preferred tool for editing existing text files with verified LINE:HASH anchors.",
-  readseek_write: "Preferred tool for creating or replacing a complete text file.",
-  readseek_rename: "Preferred tool for renaming code symbols safely across their resolved bindings.",
+  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_grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
-  readseek_search: "Preferred syntax-aware code search for AST shapes and call sites.",
-  readseek_map: "Preferred structural outline of symbols in a source file.",
+  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 before rename or delete.",
+  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.",
 };
 const FALLBACK_TOOL_DESCRIPTIONS: Record<string, string> = {
-  read: "Fallback only. Prefer readseek_read for text files so edits can use LINE:HASH anchors.",
-  edit: "Fallback only. Prefer readseek_edit with anchors from readseek_read/readseek_grep/readseek_search.",
+  read: "Fallback only. Prefer readseek_read so edits can use LINE:HASH anchors.",
+  edit: "Fallback only. Prefer readseek_edit with fresh LINE:HASH anchors.",
   write: "Fallback only. Prefer readseek_write so the result returns LINE:HASH anchors.",
-  grep: "Fallback only. Prefer readseek_grep for project text search with edit-ready anchors.",
+  grep: "Fallback only. Prefer readseek_grep for text/regex search with edit-ready anchors.",
   apply_patch: "Fallback only. Prefer readseek_edit for existing text files.",
 };
 const READSEEK_PLATFORM_PACKAGES: Record<string, string> = {
@@ -1017,8 +1016,8 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
     tool: {
       readseek_read: readseekTool(
         imagePolicy === "off"
-          ? "Read text with LINE:HASH anchors for durable references. Images and PDFs are skipped."
-          : `Read text with LINE:HASH anchors for durable references. For images or PDFs, select a mode (${imageModes.join(", ")}) or omit image to skip.`,
+          ? "Read text with LINE:HASH anchors. Image and PDF reads are disabled."
+          : `Read text with LINE:HASH anchors. For an image or PDF, select image (${imageModes.join(", ")}); omit it to skip visual files.`,
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           offset: tool.schema.number().int().positive().optional().describe("One-based starting line"),
@@ -1029,7 +1028,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
             ? {}
             : {
                 image: tool.schema.enum(imageModes as [ImageMode, ...ImageMode[]]).optional()
-                  .describe("Image or PDF processing mode"),
+                  .describe("Image/PDF processing mode")
               }),
         },
         "read",
@@ -1065,7 +1064,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         formatReadResult,
       ),
       readseek_view: readseekTool(
-        "View the structure or selected content of an indexed PDF. Start with the overview, then narrow by page or node.",
+        "View PDF structure or selected content. Start with the overview, then narrow by page or node.",
         {
           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"),
@@ -1090,7 +1089,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         (result) => ({ output: boundDocumentOutput(String(result)) }),
       ),
       readseek_map: readseekTool(
-        "List symbols and ranges in a source file. Use to inspect structure without reading the full file.",
+        "Show a source file's symbol outline without reading the full file.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
@@ -1105,7 +1104,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_grep: readseekTool(
-        "Search text or regular expressions and return matching LINE:HASH anchors. Use literal for exact text.",
+        "Search text or regex and return matching LINE:HASH anchors. Set literal for exact text.",
         {
           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"),
@@ -1167,9 +1166,9 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_search: readseekTool(
-        "Search syntax-aware code shapes with an ast-grep pattern and return LINE:HASH anchors. Use for calls, imports, declarations, JSX, or control flow; use text search for plain text.",
+        "Search AST patterns (ast-grep style) and return LINE:HASH anchors. Use for code structure; use readseek_grep for plain text.",
         {
-          pattern: tool.schema.string().describe("ast-grep pattern, such as console.log($$$ARGS)"),
+          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"),
           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"),
@@ -1188,7 +1187,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_def: readseekTool(
-        "Find symbol declarations by name and return LINE:HASH anchors. Use instead of text search to locate where a function, class, type, or other symbol is defined.",
+        "Find symbol declarations by name and return LINE:HASH anchors. Prefer this to text search for definitions.",
         {
           name: tool.schema.string().describe("Symbol name"),
           path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
@@ -1208,7 +1207,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_refs: readseekTool(
-        "Find identifier usages with enclosing symbols. Use before changing or deleting a symbol; add a cursor scope to exclude same-named bindings.",
+        "Find identifier usages with enclosing symbols. Use before renaming or deleting a symbol; add cursor scope to exclude same-named bindings.",
         {
           name: tool.schema.string().describe("Identifier name"),
           path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
@@ -1238,7 +1237,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, or to identify a line's enclosing symbol.",
+        "Identify the token and enclosing symbol at a cursor. Use before definition lookup or rename.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           line: tool.schema.number().int().positive().describe("One-based cursor line"),
@@ -1256,11 +1255,11 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_rename: readseekTool(
-        "Rename a symbol without changing same-named bindings. Applies verified edits atomically by default; set apply false for a dry-run plan.",
+        "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.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
-          line: tool.schema.number().int().positive().describe("One-based line of the symbol to rename"),
-          column: tool.schema.number().int().positive().optional().describe("One-based byte column for disambiguation"),
+          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"),
@@ -1291,7 +1290,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_edit: readseekTool(
-        "Edit an existing text file using LINE:HASH anchors. Stale hashes are rejected before writing.",
+        "Edit an existing text file with fresh LINE:HASH anchors. Stale hashes are rejected before writing.",
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           edits: tool.schema.array(tool.schema.union([
@@ -1308,7 +1307,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
             tool.schema.object({
               insert_after: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }).strict(),
             }).strict(),
-          ])).min(1).describe("Anchored edits to apply"),
+          ])).min(1).describe("LINE:HASH-anchored edits to apply"),
         },
         "edit",
         async (input, context) => {
@@ -1359,7 +1358,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
       readseek_check: readseekTool(
-        "Check a source file for parser errors and missing syntax. Use after edits for quick syntax validation, not as a compiler or linter.",
+        "Run a quick syntax check on a source file. Reports parser errors and missing syntax; not a compiler 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,7 +1,7 @@
 {
   "name": "opencode-readseek",
-  "version": "0.8.18",
-  "description": "OpenCode plugin for readseek-backed structural code navigation",
+  "version": "0.8.20",
+  "description": "OpenCode plugin for anchored file operations and structural code navigation",
   "type": "module",
   "main": "./index.ts",
   "exports": {
@@ -31,7 +31,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.8.18",
+    "@jarkkojs/readseek": "^0.8.20",
     "@opencode-ai/plugin": "^1.17.20"
   },
   "devDependencies": {