@tduyng/pi-edit-path 0.0.2 → 0.0.3

package/README.md

@@ -1,34 +1,44 @@
 # @tduyng/pi-edit-path
 
-Two halves of one edit path. `then_run` fuses the validation command into the edit that needs it, and the edit hint names the region on disk a failed edit meant, so the retry lands without a re-read.
+Fix the edit path instead of walking it twice. Fuse the check into the edit that needs it, and name the region on disk a failed edit meant, so the retry lands without a re-read.
+
+## What it costs
+
+`then_run` adds two guideline bullets to the `edit` and `write` prompts, and the edit hint adds nothing at all: no tool, no schema, no prompt text. It reads the file pi already named in its own error.
+
+What it saves is a round trip per check and a read per failed edit. A rejected edit that comes back with the closest region on disk costs one retry instead of a re-read plus a retry.
 
 ## then_run
 
-`then_run` is an optional parameter on `edit` and `write`: an object with `command` and `timeout` (seconds), or the command as a plain string. It runs after the mutation succeeds and is skipped if the mutation fails.
+`then_run` is an optional parameter on `edit` and `write`: an object with `command` and `timeout` in seconds, or the command as a plain string. It runs after the mutation succeeds and is skipped when the mutation fails.
 
-A string carrying an object literal, `then_run: '{command: "npm test"}'`, is read for its `command` and `timeout` rather than handed to bash, which used to run the braces and answer `command not found`. A string with no key in it stays the command. A literal naming no command is reported as a `then_run` failure after the mutation has landed, so the model is told the file changed and what the argument should have been.
+```text
+edit(path: "src/retry.ts", edits: [...], then_run: {command: "bun test src/retry", timeout: 120})
+```
+
+The tool definitions are extended, not replaced. The built-in `edit` and `write` schemas keep their properties and gain an optional `then_run`, and each working directory gets its own cached definition.
 
-Success and failure use sentinel markers. On success the command output is appended to the mutation result preceded by `[then_run:succeeded]`. On failure the mutation output is reported first, followed by `[then_run:failed]` and the error message, all wrapped in a single thrown error so the mutation result is not lost.
+Result markers are sentinels. On success the command output is appended after `[then_run:succeeded]`. On failure the mutation output is reported first, then `[then_run:failed]` and the error, all inside one thrown error, so the mutation result is never lost.
 
-The tool definitions are extended, not replaced: the built-in `edit` and `write` schemas keep their properties and gain an optional `then_run`. Each working directory gets its own cached tool definition.
+A string carrying an object literal, `then_run: '{command: "npm test"}'`, is read for its `command` and `timeout` instead of being handed to bash, which used to run the braces and answer `command not found`. A literal naming no command is reported as a `then_run` failure after the mutation has landed, so the model is told the file changed and what the argument should have been.
 
-Two guidelines ride on the tool prompts. Pass `then_run` when the check follows from the same file the edit or write just changed. Use a separate `bash` call when the check does not follow from the edit, spans files not yet written, or when the model needs to read the edit result before deciding what to run.
+Pass `then_run` when the check follows from the file the edit just changed. Use a separate `bash` call when the check spans files not yet written, or when you need to read the edit result before deciding what to run.
 
 ## The edit hint
 
-On a `tool_result` where pi's own edit could not find the old text or matched it more than once, the hint appends what the read was for: the closest region as it reads on disk now, with line numbers and current text, or the line of every match when the old text matches more than once. The retry copies old text from those lines.
+When pi's own edit cannot find the old text, or finds it more than once, the hint appends what the read was for: the closest region as it reads on disk now, with line numbers and current text, or the line of every match when the old text matched more than once. The retry copies old text out of those lines.
 
-The hint reports, it never repairs. A miss that survives pi's fuzzy matching is a real mismatch, and silently applying a guess there would write code nobody asked for.
+The hint reports and never repairs. A miss that survives pi's fuzzy matching is a real mismatch, and silently applying a guess would write code nobody asked for.
 
-A region is found by line agreement, not by character count. Every distinctive line of old text (at least four characters, so a lone `}` never votes) is looked up in the file as pi's own matcher would read it, and the window of oldText's height holding the most of them wins. Under half agreeing means no region is shown, because a weak guess invites an edit against the wrong lines.
+A region is found by line agreement, not by character count. Every distinctive line of the old text (at least four characters, so a lone `}` never votes) is looked up in the file as pi's own matcher would read it, and the window of oldText's height holding the most of them wins. Under half agreeing means no region is shown, because a weak guess invites an edit against the wrong lines.
 
-Agreement alone hides the commonest cause. On a miss where every distinctive line of a doc comment was present in the file, the model had re-wrapped a paragraph at a different column and written one word from memory. A line-for-line search cannot see a re-wrap, so the lines that are in no way on disk are listed by name next to the region.
+Agreement alone hides the commonest cause. On a miss where every distinctive line of a doc comment was present, the model had re-wrapped a paragraph at a different column and written one word from memory. A line-for-line search cannot see a re-wrap, so the lines that are in no way on disk are listed by name next to the region.
 
 ## Cost
 
-The hint adds no tool, no schema and no prompt text. It reads the file pi already named in the error. A file over 2MB is not read. `then_run` costs two guideline bullets on the `edit` and `write` prompts and saves one provider round trip per fused check.
-
-`PI_HINT_EDIT_HINT=0` disables the hint. It accepts `false`, `no`, and `off` too.
+- The hint reads one file that pi already named, and refuses anything over 2 MB.
+- `then_run` costs two guideline bullets on the `edit` and `write` prompts and saves one provider round trip per fused check.
+- `PI_HINT_EDIT_HINT=0` disables the hint, and accepts `false`, `no`, and `off`.
 
 ## Install
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-edit-path",
-  "version": "0.0.2",
-  "description": "Two halves of one edit path: fuse the validation command into the edit that needs it, and name the region on disk a failed edit meant so the retry lands without a re-read.",
+  "version": "0.0.3",
+  "description": "Fuse the validation command into the edit that needs it, and name the region on disk a failed edit meant.",
   "keywords": [
     "pi",
     "pi-package",