pi-readseek 0.6.11 → 0.6.13

package/README.md

@@ -1,50 +1,43 @@
 # pi-readseek
 
-`pi-readseek` is a pi extension for readseek-backed file reading, hash-anchored
-editing, anchored grep, structural maps, symbol lookup, and structural search.
-It exposes readseek tools under the `readSeek_` prefix. Built-in pi tools stay
-active unless excluded in settings.
+`pi-readseek` is a Pi extension for ReadSeek-backed file reading, hash-anchored
+editing, anchored grep, structural maps, symbol navigation, and structural search.
+Pi's built-in tools remain unchanged by default. `replacedTools` can register the
+corresponding ReadSeek implementations under built-in names.
 
 ## Installation
 
-```bash
+```sh
 pi install npm:pi-readseek
 ```
 
-The structural search and map features require the `@jarkkojs/readseek` native
-binary. The extension auto-installs the correct platform package, or you can
-install it manually:
-
-```bash
-# Auto-installed by the extension on supported platforms.
-# Manual install (if needed):
-npm install --save-dev @jarkkojs/readseek
-```
+`pi-readseek` depends on `@jarkkojs/readseek`; installation includes the native
+binary automatically on supported platforms.
 
 ## Tools
 
-- **readSeek_read:** reads text with `LINE:HASH` anchors; when image modes are
+- `readSeek_read`: reads text with `LINE:HASH` anchors; when image modes are
   enabled, images and PDFs can be returned as base64 or analyzed locally.
-- **readSeek_edit:** edits existing text files using fresh `LINE:HASH` anchors.
-- **readSeek_grep:** searches text and returns edit-ready anchors.
-- **readSeek_search:** searches code by structural AST pattern.
-- **readSeek_refs:** finds identifier references with enclosing symbols.
-- **readSeek_rename:** plans or applies binding-aware renames.
-- **readSeek_hover:** identifies the cursor token and enclosing symbol.
-- **readSeek_def:** finds structural symbol definitions.
-- **readSeek_check:** checks a source file for parser errors and missing syntax.
-- **readSeek_write:** creates or overwrites whole files and returns anchors.
+- `readSeek_edit`: edits existing text files using fresh `LINE:HASH` anchors.
+- `readSeek_grep`: searches text and returns edit-ready anchors.
+- `readSeek_search`: searches code by structural AST pattern.
+- `readSeek_refs`: finds identifier references with enclosing symbols.
+- `readSeek_rename`: plans or applies binding-aware renames; workspace matches are
+  name-based where binding support is unavailable.
+- `readSeek_hover`: identifies the cursor token and enclosing symbol.
+- `readSeek_def`: finds structural symbol definitions.
+- `readSeek_check`: checks a source file for parser errors and missing syntax.
+- `readSeek_write`: creates or overwrites whole files and returns anchors.
 
 ## Settings
 
 `pi-readseek` reads optional JSON settings from:
 
-- `~/.pi/agent/settings.json` — Global
-- `.pi/settings.json` — Project
+- `~/.pi/agent/settings.json` — global settings.
+- `.pi/settings.json` — project settings.
 
-Project settings override global settings. The `readseek` section lives inside pi's
-shared `settings.json`, alongside other extensions' sections. All settings are
-optional (defaults shown):
+Project settings override global settings. The `readseek` section lives in Pi's
+shared `settings.json`. All settings are optional; defaults are shown below.
 
 ```json
 {
@@ -61,18 +54,18 @@ optional (defaults shown):
 }
 ```
 
-- **replacedTools:** built-in tool names to replace with their `readSeek_*` equivalents.
+- `replacedTools`: built-in tool names to replace with ReadSeek implementations.
   Valid values are `"read"`, `"edit"`, `"write"`, and `"grep"`. For a
-  readseek-only file surface, use `["read", "edit", "write", "grep"]`.
-- **imageMode:** `"auto"` exposes `none`, `all`, `ocr`, `caption`, and `objects`;
+  ReadSeek-only file surface, use `["read", "edit", "write", "grep"]`.
+- `imageMode`: `"auto"` exposes `none`, `all`, `ocr`, `caption`, and `objects`;
   `"on"` omits `none`; `"off"` removes the `image` parameter and always skips
   image/PDF files. Omitting `image` also skips visual files.
-- **syntaxValidation:** pre-write syntax-regression check in `readSeek_edit`:
-  `"warn"` writes with a warning, `"block"` aborts without writing, `"off"`
+- `syntaxValidation`: pre-write syntax-regression check in `readSeek_edit`:
+  `"warn"` writes with a warning, `"block"` aborts without writing, and `"off"`
   skips the check.
-- **timeoutMs:** readseek invocation timeout in milliseconds.
-- **grep.maxLines** / **grep.maxBytes:** visible `readSeek_grep` output
-  budget; values above the defaults are clamped.
+- `timeoutMs`: ReadSeek invocation timeout in milliseconds.
+- `grep.maxLines` / `grep.maxBytes`: visible `readSeek_grep` output budget; values
+  above the defaults are clamped.
 
 ## Licensing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.6.11",
+    "@jarkkojs/readseek": "^0.6.13",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },
@@ -59,7 +59,6 @@
     "vitest": "^4.1.0"
   },
   "directories": {
-    "doc": "docs",
     "test": "tests"
   },
   "bugs": {

package/prompts/check.md

@@ -2,7 +2,7 @@ Check a source file for parser errors and missing syntax. Use after edits for qu
 
 ## Parameters
 
-- `path` - source file to check.
+- `path` — source file to check.
 
 ## Output
 

package/prompts/edit.md

@@ -42,9 +42,9 @@ matches before continuing.
 ## `replace_symbol`
 
 Use `replace_symbol` for one whole mapped `Name`, `Class.method`, or
-`Name@<line>` in TypeScript, JavaScript, Rust, or Java. `new_body` must be
-non-empty and unindented. Confirm fuzzy symbol matches first; do not overlap it
-with anchored edits.
+`Name@<line>` in any mappable source file. `new_body` must be non-empty and
+unindented. Confirm fuzzy symbol matches first; do not overlap them with anchored
+edits.
 
 ## Stale anchors
 
@@ -59,9 +59,10 @@ Retry with those anchors, or read/search again. Verify any auto-relocation warni
 ## Validation and warnings
 
 All edits validate before writing; hard failures write nothing. Anchored edits run
-bottom-up. `no-op` means no change. Syntax validation for Rust, C++, C headers,
-and Java follows `readseek.syntaxValidation`: `warn` (default), `block`, or `off`.
-It reports only newly introduced parser errors.
+bottom-up. `no-op` means no change. Syntax validation for every language with a
+tree-sitter parser follows `readseek.syntaxValidation`: `warn` (default), `block`,
+or `off`. It triggers when error or missing-node counts increase and reports the
+post-edit diagnostic ranges.
 
 ## Optional post-edit verification
 

package/prompts/grep.md

@@ -19,4 +19,6 @@ Search plain text or regex in files and return edit-ready `LINE:HASH` anchors. U
 - `scope` — only `"symbol"` is supported.
 - `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
 
-If output says results were truncated at `limit` or by display budget, narrow before editing. Good narrowing order: `summary` → `path`/`glob` → stricter pattern → `scope: "symbol"` or `context`.
+If output is truncated at `limit` or by the display budget, narrow with `summary`,
+then `path`/`glob`, then a stricter pattern. Request context or symbol blocks only
+after narrowing.

package/prompts/read.md

@@ -24,7 +24,7 @@ Truncated full-file reads append a map when available. Use its ranges for follow
 
 | Query | Reads |
 |---|---|
-| `{ "symbol": "processEvent" }` | function or top-level symbol |
+| `{ "symbol": "processEvent" }` | function or unqualified symbol |
 | `{ "symbol": "EventEmitter" }` | class/interface/type/enum/etc. |
 | `{ "symbol": "EventEmitter.emit" }` | child method/member |
 | `{ "symbol": "Foo.bar@42" }` | overload/definition near line 42 |

package/prompts/refs.md

@@ -20,5 +20,6 @@ shadows.
 
 ## Git selection
 
-In Git repositories, directory search includes tracked/indexed and untracked
-non-ignored files. `ignored` requires `others`.
+In Git repositories, directory search includes tracked/indexed and untracked,
+non-ignored files by default. `cached` or `others` restricts the search to that
+group; `ignored` requires `others`.

package/prompts/rename.md

@@ -1,8 +1,9 @@
-Rename the symbol at a cursor without changing same-named bindings. Use for symbol renames; use search and edit for broader refactors.
+Rename the symbol at a cursor without changing resolvable same-named bindings. Use for symbol renames; use search and edit for broader refactors.
 
 ## Parameters
 
 - `path`, `line`, `to` — required file, one-based cursor line, and plain new name.
 - `column` — optional one-based cursor byte column.
-- `workspace` — expand across the project; local shadows in other files are excluded.
+- `workspace` — expand across the project; local shadows are excluded where binding
+  support is available, and other files are otherwise matched by name.
 - `apply` — default `true`; set `false` to return only the verified plan.

package/prompts/search.md

@@ -30,6 +30,6 @@ punctuation must be valid for the selected language.
 
 ## Git selection
 
-In Git repositories, directory search includes tracked/indexed and untracked
-non-ignored files. Use `cached`, `others`, and `ignored` to choose; `ignored`
-requires `others`.
+In Git repositories, directory search includes tracked/indexed and untracked,
+non-ignored files by default. `cached` or `others` restricts the search to that
+group; `ignored` requires `others`.

package/prompts/write.md

@@ -1,6 +1,6 @@
 Create or replace a complete file and return `LINE:HASH` anchors. Use for new or fully generated files; use anchored edits for small changes.
 
-## Use / avoid
+## Usage
 
 Existing files are overwritten without confirmation. Binary-looking content is
 rejected without writing.

package/src/readseek-client.ts

@@ -358,6 +358,7 @@ function defaultReadSeekDir(): string | null {
 }
 
 const DEFAULT_READSEEK_TIMEOUT_MS = 120_000;
+const DEFAULT_READSEEK_VISION_TIMEOUT_MS = 30 * 60_000;
 
 function readSeekTimeoutMs(): number {
 	return resolveReadSeekTimeoutMs() ?? DEFAULT_READSEEK_TIMEOUT_MS;
@@ -493,11 +494,36 @@ async function runReadSeekVision(args: string[], options: RunReadSeekOptions = {
 	});
 	const predecessor = visionInvocationTail;
 	visionInvocationTail = predecessor.then(() => gate);
+	const signal = options.signal;
 
-	await predecessor;
 	try {
-		options.signal?.throwIfAborted();
-		return await runReadSeek(args, options);
+		if (signal) {
+			signal.throwIfAborted();
+			await new Promise<void>((resolve, reject) => {
+				const onAbort = (): void => {
+					signal.removeEventListener("abort", onAbort);
+					reject(signal.reason);
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+				predecessor.then(
+					() => {
+						signal.removeEventListener("abort", onAbort);
+						resolve();
+					},
+					(error) => {
+						signal.removeEventListener("abort", onAbort);
+						reject(error);
+					},
+				);
+			});
+		} else {
+			await predecessor;
+		}
+		signal?.throwIfAborted();
+		return await runReadSeek(args, {
+			...options,
+			timeoutMs: options.timeoutMs ?? resolveReadSeekTimeoutMs() ?? DEFAULT_READSEEK_VISION_TIMEOUT_MS,
+		});
 	} finally {
 		release();
 	}