pi-readseek 0.8.19 → 0.8.20

package/README.md

@@ -26,13 +26,12 @@ supported platforms.
 | `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_rename` | Rename a cursor symbol; set `apply: false` to preview the plan |
 | `readSeek_check` | Report parser errors and missing syntax |
 | `readSeek_view` | View or narrow a structural PDF index |
 
-Workspace renames use name matching where binding resolution is unavailable.
-The extension also adds a short editing policy to Pi's system prompt so models
-prefer fresh `LINE:HASH` anchors and run a quick syntax check after source edits.
+The extension also tells Pi to get fresh anchors before editing and to run a
+syntax check after source edits.
 
 ## Settings
 
@@ -62,13 +61,12 @@ Defaults:
 ```
 
 - `replacedTools`: any of `"read"`, `"edit"`, `"write"`, and `"grep"`.
-- `imageMode`:
-  - `"auto"` exposes `none`, `all`, `ocr`, `caption`, and `objects`. If the
-    active model accepts images, prepared images go directly to the model.
-  - `"on"` always runs the selected local analysis and omits `none`.
-  - `"off"` skips standalone and PDF-embedded images; PDF text is still read.
-  Omitting `image` skips standalone images and, unless native vision is active
-  in `"auto"` mode, embedded PDF images.
+- `imageMode`: `"auto"` uses Pi's native image input when available, `"on"`
+  always runs local analysis, and `"off"` skips images while still reading PDF
+  text. Standalone images require `image`; values are `all`, `ocr`, `caption`, and
+  `objects`. In `"auto"`, `none` returns a prepared standalone image without local
+  analysis. Local analysis uses
+  [Qwen3-VL-2B-Instruct](../../docs/models/qwen3-vl-2b-instruct.md).
 - `syntaxValidation`: `"warn"` (write and warn), `"block"` (abort), or `"off"`.
   Validation triggers only when an edit increases parser error or missing-node
   counts.

package/dist/index.ts

@@ -50,8 +50,7 @@ var COMPACT_GUIDELINES = {
     "Use readSeek_search for AST patterns; use readSeek_grep for plain text."
   ],
   "refs.md": [
-    "Use readSeek_refs before renaming or deleting an identifier.",
-    "Use readSeek_refs with scope plus line/column to follow one binding and exclude same-named bindings."
+    "Use readSeek_refs before changing a symbol; add scope plus line/column to follow one binding."
   ]
 };
 function loadPrompt(promptUrl) {
@@ -3661,17 +3660,17 @@ function registerReadTool(pi, options = {}) {
   const imageModes = imageMode === "auto" ? ["none", "all", "ocr", "caption", "objects"] : ["all", "ocr", "caption", "objects"];
   const promptMetadata = defineToolPromptMetadata({
     promptUrl: new URL("../prompts/read.md", import.meta.url),
-    promptSnippet: "Read anchored text, symbols, maps, images, or PDFs",
+    promptSnippet: imageMode === "off" ? "Read anchored text, symbols, maps, or PDF text" : "Read anchored text, symbols, maps, images, or PDFs",
     registeredName: name
   });
   const tool = registerReadSeekTool(pi, {
     name,
     label: "Read",
-    description: imageMode === "off" ? "Read anchored text by range, map, or symbol. Standalone and PDF-embedded images are skipped; PDFs are read as text." : promptMetadata.description,
+    description: imageMode === "off" ? "Read anchored text by range, symbol, or map. Images are disabled; PDFs still return text." : promptMetadata.description,
     promptSnippet: promptMetadata.promptSnippet,
     promptGuidelines: [
       ...promptMetadata.promptGuidelines,
-      imageMode === "off" ? "The image parameter is unavailable; standalone and PDF-embedded images are skipped, while PDFs are read as text." : `Select image explicitly for standalone images: ${imageModes.join(", ")}. Omitting it skips standalone images. PDF text is always returned; image controls embedded images.${imageMode === "auto" ? " Native image-capable models receive prepared standalone and PDF-embedded images directly instead of using local analysis." : ""}`
+      ...imageMode === "auto" ? ["Image-capable Pi models receive prepared images directly. For standalone images, image=none skips local analysis; other modes use ReadSeek when native vision is unavailable."] : []
     ],
     parameters: Type2.Object({
       path: filePathParam(),
@@ -3685,7 +3684,7 @@ function registerReadTool(pi, options = {}) {
       })),
       ...imageMode === "off" ? {} : {
         image: Type2.Optional(Type2.Union(imageModes.map((mode) => Type2.Literal(mode)), {
-          description: `Standalone/PDF-embedded image mode: ${imageModes.join(", ")}. Required for standalone images.`
+          description: `Standalone/PDF-embedded image mode: ${imageModes.join(", ")}. Required for standalone images.${imageMode === "auto" ? " For standalone images, none skips local analysis." : ""}`
         }))
       }
     }),
@@ -4793,13 +4792,36 @@ function pendingPreviewLines(summary, preview, expanded) {
   const headerLine = summaryLine(preview.data.headerLabel, { hidden: !expanded });
   return { lines: [summary, headerLine], diffData: expanded ? diffData : undefined, headerLabel: preview.data.headerLabel };
 }
-var hashlineEditItemSchema = Type3.Union([
-  Type3.Object({ set_line: Type3.Object({ anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ replace_lines: Type3.Object({ start_anchor: Type3.String(), end_anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ insert_after: Type3.Object({ anchor: Type3.String(), new_text: Type3.String() }) }, { additionalProperties: false }),
-  Type3.Object({ replace: Type3.Object({ old_text: Type3.String(), new_text: Type3.String(), all: Type3.Optional(Type3.Boolean()), fuzzy: Type3.Optional(Type3.Boolean()) }) }, { additionalProperties: false }),
-  Type3.Object({ replace_symbol: Type3.Object({ symbol: Type3.String(), new_body: Type3.String() }) }, { additionalProperties: false })
-]);
+var hashlineEditItemSchema = Type3.Object({
+  set_line: Type3.Optional(Type3.Object({
+    anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the line to replace" }),
+    new_text: Type3.String({ description: "Replacement text; use an empty string to delete the line" })
+  }, { description: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+  replace_lines: Type3.Optional(Type3.Object({
+    start_anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the first line in the range" }),
+    end_anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the last line in the range" }),
+    new_text: Type3.String({ description: "Replacement text; use an empty string to delete the range" })
+  }, { description: 'Replace a range: {"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}' })),
+  insert_after: Type3.Optional(Type3.Object({
+    anchor: Type3.String({ description: "Fresh LINE:HASH anchor for the line after which to insert" }),
+    new_text: Type3.String({ description: "Text to insert after the anchored line" })
+  }, { description: 'Insert text: {"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+  replace: Type3.Optional(Type3.Object({
+    old_text: Type3.String({ description: "Exact text to find" }),
+    new_text: Type3.String({ description: "Replacement text" }),
+    all: Type3.Optional(Type3.Boolean({ description: "Replace every exact match" })),
+    fuzzy: Type3.Optional(Type3.Boolean({ description: "Allow unverified fuzzy matching when exact text is absent" }))
+  }, { description: 'Replace text: {"replace":{"old_text":"...","new_text":"..."}}' })),
+  replace_symbol: Type3.Optional(Type3.Object({
+    symbol: Type3.String({ description: "Mapped symbol name" }),
+    new_body: Type3.String({ description: "Complete replacement body for the symbol" })
+  }, { description: 'Replace a symbol: {"replace_symbol":{"symbol":"name","new_body":"..."}}' }))
+}, {
+  additionalProperties: false,
+  minProperties: 1,
+  maxProperties: 1,
+  description: "Exactly one nested edit variant"
+});
 var hashlineEditSchema = Type3.Object({
   path: filePathParam(),
   edits: Type3.Optional(Type3.Array(hashlineEditItemSchema, {
@@ -4860,7 +4882,12 @@ async function executeEdit(opts) {
       }
       for (let i = 0;i < edits.length; i++) {
         throwIfAborted(signal);
-        const e = edits[i];
+        const edit = edits[i];
+        if (!edit || typeof edit !== "object" || Array.isArray(edit)) {
+          const message = `edits[${i}] must be an object containing exactly one edit variant.`;
+          return buildEditError(absolutePath, "invalid-edit-variant", message);
+        }
+        const e = edit;
         if ((("old_text" in e) || ("new_text" in e)) && !("replace" in e)) {
           const message = `edits[${i}] has top-level 'old_text'/'new_text'. Use {replace: {old_text, new_text}} or {set_line}, {replace_lines}, {insert_after}.`;
           return buildEditError(absolutePath, "invalid-edit-variant", message);
@@ -4870,7 +4897,7 @@ async function executeEdit(opts) {
           return buildEditError(absolutePath, "invalid-edit-variant", message);
         }
         const variantCount = Number("set_line" in e) + Number("replace_lines" in e) + Number("insert_after" in e) + Number("replace" in e) + Number("replace_symbol" in e);
-        if (variantCount !== 1) {
+        if (variantCount !== 1 || Object.keys(e).length !== 1) {
           const message = `edits[${i}] must contain exactly one of: 'set_line', 'replace_lines', 'insert_after', 'replace', 'replace_symbol'. Got: [${Object.keys(e).join(", ")}].`;
           return buildEditError(absolutePath, "invalid-edit-variant", message);
         }
@@ -6463,7 +6490,7 @@ import path5 from "node:path";
 import { Text as Text6 } from "@earendil-works/pi-tui";
 var RENAME_PROMPT_METADATA = defineToolPromptMetadata({
   promptUrl: new URL("../prompts/rename.md", import.meta.url),
-  promptSnippet: "Rename the symbol at a cursor while preserving same-named bindings"
+  promptSnippet: "Rename a cursor symbol with verified edits"
 });
 var renameSchema = Type8.Object({
   path: filePathParam(),
@@ -7262,7 +7289,7 @@ function registerViewTool(pi) {
     parameters: Type13.Object({
       path: filePathParam(),
       node: Type13.Optional(Type13.String({ description: "Node ID to use as the view root" })),
-      page: optionalIntOrString("One-based source page"),
+      page: optionalIntOrString("One-based PDF page"),
       kind: Type13.Optional(Type13.Union(NODE_KINDS.map((kind) => Type13.Literal(kind)), {
         description: "Node kind filter"
       })),
@@ -7343,7 +7370,6 @@ function editingPolicy(readName, editName, writeName) {
     "ReadSeek editing policy:",
     `- Read first with ${readName} when preparing to edit; ${editName} needs fresh LINE:HASH anchors.`,
     `- Use ${editName} for existing files, ${writeName} for whole-file creation or replacement, and readSeek_rename for symbol renames.`,
-    "- Do not use Pi's built-in read, edit, write, or grep when the corresponding ReadSeek tool is available.",
     "- Run readSeek_check after source edits for a quick syntax check."
   ].join(`
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.8.19",
+  "version": "0.8.20",
   "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.8.19",
+    "@jarkkojs/readseek": "^0.8.20",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/edit.md

@@ -1,4 +1,4 @@
-Edit existing text files with fresh `LINE:HASH` anchors. Read or search the file first when no fresh anchors are available.
+Edit existing text files with fresh `LINE:HASH` anchors. Read or search the file first when no fresh anchors are available. Each `edits[]` item must use exactly one nested object: `{"set_line":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}`, `{"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_symbol":{"symbol":"name","new_body":"..."}}`, or `{"replace":{"old_text":"...","new_text":"..."}}`.
 
 Anchors come from `readSeek_read`, `readSeek_grep`, `readSeek_search`, or
 `readSeek_write`.

package/prompts/read.md

@@ -1,4 +1,4 @@
-Read anchored text by range, map, or symbol; process images only with an explicit mode. PDF text is always returned.
+Read anchored text by range, symbol, or map. Standalone images require an explicit mode; PDF text is always returned.
 
 ## Choose a read
 
@@ -23,10 +23,10 @@ Text output is capped at {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
 A truncated full-file read appends a map when available; use its ranges for
 follow-up reads.
 
-Standalone images require an explicit `image` mode. PDF text is always read;
-omitting `image` skips embedded images unless native vision is active in
-`"auto"` mode. With native vision, prepared standalone and PDF-embedded images
-go directly to the model instead of local analysis.
+Standalone images require `image`. In `"auto"`, `image: "none"` returns a
+prepared standalone image without local analysis. PDF text is always read;
+without `image`, embedded images are skipped unless an image-capable Pi model is
+active in `"auto"` mode. That model receives prepared images directly.
 
 ## Symbol lookup
 

package/prompts/refs.md

@@ -1,4 +1,4 @@
-Find identifier usages with enclosing symbols and edit-ready `LINE:HASH` anchors. Use before renaming, deleting, or changing a symbol; add cursor scope to exclude same-named bindings.
+Find identifier usages with enclosing symbols and edit-ready `LINE:HASH` anchors. Add cursor scope to follow one binding and exclude shadows.
 
 ## Parameters
 

package/prompts/rename.md

@@ -1,4 +1,4 @@
-Rename the symbol at a cursor while preserving resolvable same-named bindings. Use search and anchored edits for broader refactors.
+Rename the symbol at a cursor while preserving resolvable same-named bindings. Set `apply: false` to preview the verified plan.
 
 ## Parameters
 

package/prompts/view.md

@@ -4,7 +4,7 @@ View the structure or selected content of a PDF. Start with the overview, then n
 
 - `path` — PDF file.
 - `node` — node ID to use as the view root.
-- `page` — one-based source page.
+- `page` — one-based PDF page.
 - `kind` — node kind filter.
 - `depth` — maximum depth below selected roots.
 - `outline` — return outline nodes only.

package/prompts/write.md

@@ -13,4 +13,4 @@ rejected before writing.
 
 Text output uses `LINE:HASH|content` and is capped at {{DEFAULT_MAX_LINES}} lines
 or {{DEFAULT_MAX_BYTES}}. Complete anchors remain in `readSeekValue`. Results
-also include a compact diff, unified patch, and structured `details.diffData`.
+also include a compact diff and structured `details.diffData`.