pi-hashline-edit-pro 0.16.3 → 0.16.5

package/README.md

@@ -56,7 +56,7 @@ Optional parameters:
 - `offset` -- start reading from this line number (1-indexed).
 - `limit` -- maximum number of lines to return.
 
-Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not participate in the hashline protocol. Binary and directory paths are rejected with a descriptive error. Empty files return an advisory suggesting using replace to insert content.
+Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not participate in the hashline protocol. Binary and directory paths are rejected with a descriptive error. Empty files are returned as a single empty-line hash (`HASH│`). Use replace on that hash to insert content.
 
 ### `replace` -- hash-anchored modifications
 
@@ -66,9 +66,10 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ```json
 {
-  "path": "src/main.ts",
   "changes": [
     { "content_lines": ["  console.log('hashline');"], "hash_range_inclusive": ["ve7", "ve7"] }
+  ],
+  "path": "src/main.ts"
 }
 ```
 
@@ -93,7 +94,7 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 
 ### Stable hashing across edits
 
-Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro/hash-store.json`) that preserves hashes for unchanged lines across edits. When you replace lines in a file, the runtime diffs the old content against the new content and copies hashes for unchanged lines to their new positions. This means editing one part of a file does not change the hashes of unrelated lines elsewhere — the model can keep using previously seen anchors for untouched regions.
+Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro/hash-store.json`) that preserves hashes for unchanged lines across edits. When you replace lines in a file, the runtime maps the old content against the new content and copies hashes for unchanged lines to their new positions. This means editing one part of a file does not change the hashes of unrelated lines elsewhere — the model can keep using previously seen anchors for untouched regions.
 
 The store contains per-file snapshots: the last known content and hashes for each file. On read, if the file content matches the snapshot, the saved hashes are returned immediately. Stale snapshots (for files that no longer exist) are pruned on session start.
 
@@ -144,7 +145,7 @@ The file is created automatically when any setting is toggled. Both fields are i
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 - **Boundary duplication warnings.** When the last line of a replacement matches the next surviving line (or the first line matches the preceding one), a warning is emitted. This catches a common LLM pattern where closing delimiters like `}`, `});`, or `} else {` are accidentally duplicated. The warning is a short header followed by a hashline-anchored window: the duplicated pair plus 2 lines of context before and after, shown as plain `HASH│content` rows with post-edit hashes. Seeing the duplication in context (rather than just being told a hash) is what prompts the model to act on it — and since the hashes are current and staleness is per-line, the model can remove the duplicate in one follow-up `replace` without re-reading. No autocorrection is applied — the duplicate stays in the file and the model decides whether to remove it. Raw line comparison (not trimmed) avoids false positives when indentation differs.
 - **Flat mode normalization.** When flat mode is active, the tool's `execute` function wraps the top-level `hash_range_inclusive` and `content_lines` into a single-element `changes` array internally, then runs the same pipeline as bulk mode. The `normReq` function in `replace-normalize.ts` also handles flat format directly, so any code path that normalizes input (e.g. `compPreview`) works with both formats.
-- **Persistent hash store.** `lineHashes` is async and uses a persistent store to preserve hashes for unchanged lines across edits. The store is at `~/.config/pi-hashline-edit-pro/hash-store.json` and is auto-created on first use. It contains per-file snapshots (last known content+hashes). When called from the replace pipeline, it diffs old vs new content and copies hashes for unchanged lines. When called from read, it returns saved hashes if the content matches, otherwise computes fresh hashes via `_lineHashesPure`. Stale snapshots are pruned on session start. This ensures that editing one part of a file does not cascade to change hashes of unrelated lines.
+- **Persistent hash store.** `lineHashes` is async and uses a persistent store to preserve hashes for unchanged lines across edits. The store is at `~/.config/pi-hashline-edit-pro/hash-store.json` and is auto-created on first use. It contains per-file snapshots (last known content+hashes). When called from the replace pipeline, it maps old vs new content and copies hashes for unchanged lines. When called from read, it returns saved hashes if the content matches, otherwise computes fresh hashes via `_lineHashesPure`. Stale snapshots are pruned on session start. This ensures that editing one part of a file does not cascade to change hashes of unrelated lines.
 ## Hashing
 
 Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32 via WebAssembly), then mapped to a 3-character string from the URL-safe base64 alphabet `A-Za-z0-9-_`. That's 64 distinct characters, 6 bits per position, 18 bits of entropy per anchor.
@@ -157,7 +158,7 @@ The runtime always precomputes the full per-line hash array for a file via `line
 
 ### Bare-prefix detector
 
-With the `│` delimiter format, the bare-prefix detector regex `^\s*[A-Za-z0-9_\-]{3}│` is highly specific. It only matches lines starting with a hash-like prefix. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
+With the `│` delimiter format, the bare-prefix detector regex `^\s*([A-Za-z0-9_\-]{3})│` is highly specific. It only matches lines starting with a hash-like prefix. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-bulk-guidelines.md

@@ -3,4 +3,5 @@
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
 - **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- **`content_lines` must be a native JSON array of strings**, not a JSON string. Do NOT serialize it: `"content_lines": "[\"line1\", \"line2\"]"` is WRONG. Use `"content_lines": ["line1", "line2"]` instead.
 - If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace-bulk.md

@@ -80,6 +80,18 @@ Right:
 ```json
 { "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
+⚠️ Common mistake: do not serialize `content_lines` as a JSON string.
+
+Wrong:
+```json
+{ "changes": [{ "content_lines": "[\"line1\", \"line2\"]", "hash_range_inclusive": ["F4T", "F4T"] }], "path": "src/main.ts" }
+
+Right:
+```json
+{ "changes": [{ "content_lines": ["line1", "line2"], "hash_range_inclusive": ["F4T", "F4T"] }], "path": "src/main.ts" }
+
+`content_lines` must be a native JSON array of strings, not a string that looks like an array. Pass it as a proper JSON array value.
+
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
 - To delete a range, use `content_lines: []`.

package/prompts/replace-flat-guidelines.md

@@ -3,4 +3,5 @@
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
 - **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- **`content_lines` must be a native JSON array of strings**, not a JSON string. Do NOT serialize it: `"content_lines": "[\"line1\", \"line2\"]"` is WRONG. Use `"content_lines": ["line1", "line2"]` instead.
 - If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace-flat.md

@@ -65,6 +65,18 @@ Right:
 ```json
 { "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
+⚠️ Common mistake: do not serialize `content_lines` as a JSON string.
+
+Wrong:
+```json
+{ "content_lines": "[\"line1\", \"line2\"]", "hash_range_inclusive": ["F4T", "F4T"], "path": "src/main.ts" }
+
+Right:
+```json
+{ "content_lines": ["line1", "line2"], "hash_range_inclusive": ["F4T", "F4T"], "path": "src/main.ts" }
+
+`content_lines` must be a native JSON array of strings, not a string that looks like an array. Pass it as a proper JSON array value.
+
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
 - To delete a range, use `content_lines: []`.

package/prompts/replace-guidelines.md

@@ -3,5 +3,6 @@
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
 - **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- **`content_lines` must be a native JSON array of strings**, not a JSON string. Do NOT serialize it: `"content_lines": "[\"line1\", \"line2\"]"` is WRONG. Use `"content_lines": ["line1", "line2"]` instead.
 - Two modes are available: bulk (default, uses `changes` array) and flat (top-level `hash_range_inclusive`/`content_lines`). Toggle with `/toggle-replace-mode`.
 - If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace.md

@@ -127,6 +127,18 @@ Right:
 ```json
 { "content_lines": [...], "hash_range_inclusive": ["F4T", "F4T"] }
 
+⚠️ Common mistake: do not serialize `content_lines` as a JSON string.
+
+Wrong:
+```json
+{ "content_lines": "[\"line1\", \"line2\"]", "hash_range_inclusive": ["F4T", "F4T"] }
+
+Right:
+```json
+{ "content_lines": ["line1", "line2"], "hash_range_inclusive": ["F4T", "F4T"] }
+
+`content_lines` must be a native JSON array of strings, not a string that looks like an array. Pass it as a proper JSON array value.
+
 Rules:
 - `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
 - To delete a range, use `content_lines: []`.

package/src/hashline/parse.ts

@@ -56,13 +56,13 @@ function assertNoPrefixes(lines: string[]): void {
 }
 
 export function parseText(edit: string[] | string | null): string[] {
-	if (edit === null) return [];
-	const lines =
-		typeof edit === "string"
-			? (edit.endsWith("\n") ? edit.slice(0, -1) : edit)
-					.replaceAll("\r", "")
-					.split("\n")
-			: edit;
-	assertNoPrefixes(lines);
-	return lines;
+  if (edit === null) return [];
+  if (typeof edit === "string") {
+    throw new Error(
+      `[E_BAD_SHAPE] "content_lines" must be a native JSON array of strings, not a JSON string.`
+      + ` Do not serialize the array (e.g. '["line1", "line2"]') — pass it as a proper JSON array: ["line1", "line2"].`
+    );
+  }
+  assertNoPrefixes(edit);
+  return edit;
 }

package/src/hashline/resolve.ts

@@ -148,6 +148,13 @@ function assertItem(edit: Record<string, unknown>, index: number): void {
     throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "content_lines" field. Provide the replacement lines (use [] to delete).`);
   }
   if ("content_lines" in edit && !isStrArr(edit.content_lines)) {
+    const val = edit.content_lines;
+    if (typeof val === "string") {
+      throw new Error(
+        `[E_BAD_SHAPE] Edit ${index} field "content_lines" must be a native JSON array of strings, not a JSON string.`
+        + ` Do not serialize the array (e.g. '["line1", "line2"]') — pass it as a proper JSON array: ["line1", "line2"].`
+      );
+    }
     throw new Error(`[E_BAD_SHAPE] Edit ${index} field "content_lines" must be a string array.`);
   }
   if (!isStrPair(edit.hash_range_inclusive)) {

package/src/replace-normalize.ts

@@ -1,5 +1,17 @@
 import { isRec, has } from "./utils";
 
+function assertContentLinesNotString(
+  value: unknown,
+  label: string,
+): void {
+  if (typeof value === "string") {
+    throw new Error(
+      `[E_BAD_SHAPE] ${label}: "content_lines" must be a native JSON array of strings, not a JSON string.`
+      + ` Do not serialize the array (e.g. '["line1", "line2"]') — pass it as a proper JSON array: ["line1", "line2"].`
+    );
+  }
+}
+
 export function normalizeFilePath(record: Record<string, unknown>): void {
   if (typeof record.path !== "string" && typeof record.file_path === "string") {
     record.path = record.file_path;
@@ -31,9 +43,24 @@ export function normReq(input: unknown): unknown {
 
   normalizeFilePath(record);
 
+  // Early validation: reject string-typed content_lines at the top level
+  if (has(record, "content_lines") && typeof record.content_lines === "string") {
+    assertContentLinesNotString(record.content_lines, "Top-level");
+  }
+
   normalizeField(record, "changes", "changes");
   normalizeField(record, "edits", "changes");
 
+  // Validate items in the changes array before wrapping flat format
+  if (Array.isArray(record.changes)) {
+    for (let i = 0; i < record.changes.length; i++) {
+      const item = record.changes[i];
+      if (isRec(item) && has(item, "content_lines") && typeof item.content_lines === "string") {
+        assertContentLinesNotString(item.content_lines, `changes[${i}]`);
+      }
+    }
+  }
+
   if (!Array.isArray(record.changes) && has(record, "hash_range_inclusive") && has(record, "content_lines")) {
     const hri = record.hash_range_inclusive;
     const cl = record.content_lines;