pi-hashline-edit-pro 1.0.6 → 1.0.8

package/README.md

@@ -90,7 +90,7 @@ Exactly one edit per call, with `hash_range_inclusive` and `content_lines` at th
 | Field | Description |
 | --- | --- |
 | `hash_range_inclusive` | Pair of 3-char hashes from `read` output marking the first and last line of the range to replace (inclusive). |
-| `content_lines` | Replacement content, one string per line. Use `[]` to delete the range. |
+| `content_lines` | Replacement content, one string per line; entries must not contain line breaks. Use `[]` to delete the range. |
 
 Behavior:
 
@@ -132,6 +132,7 @@ Enabled by default. After a successful `write`, `replace`, or `undo_last_replace
 
 - History is per-file and single-level: only the most recent replace can be reverted.
 - History is persisted in the hash store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) and survives session restarts; a failed `write` does not clear it.
+- **Undo is a precondition, not a convenience.** The undo record is persisted *before* the edit is written; if it cannot be persisted, the `replace` is refused with `[E_UNDO_UNAVAILABLE]` and the file is not touched, so every applied edit is undoable. If the file write itself then fails, the previous undo record is restored, so a refused edit never destroys earlier undo history.
 - A successful `write` clears the history for that file.
 - Call `read` after an undo to get fresh anchors for follow-up edits.
 - **Safety guard.** If the file was modified or deleted since the last replace, `undo_last_replace` refuses with `[E_UNDO_STALE]` rather than overwriting those changes.
@@ -154,7 +155,7 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 
 | Code | Meaning |
 | --- | --- |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields. |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields, or a `content_lines` entry contains a line break. |
 | `[E_BAD_REF]` | An anchor in `hash_range_inclusive` is not a bare 3-char hash. |
 | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
@@ -167,6 +168,7 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 | `[E_ACCESS]` | The file is not readable or writable. |
 | `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
 | `[E_UNDO_STALE]` | `undo_last_replace` refused: the file was modified or deleted after the last replace. |
+| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `replace` was refused and the file was left unchanged. |
 | `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
 
 ## Hashing
@@ -181,10 +183,18 @@ The alphabet is sized for an LLM consumer: the model tokenizes rather than squin
 
 - **Stale anchors fail, per line.** A hash mismatch means that line's content changed since the last `read`. The error says so and, when only one anchor of a pair is stale, shows the current lines around the still-valid anchor so the range can be re-located without a full re-read. Mismatched anchors are never silently relocated to a "close enough" line — correctness over convenience.
 - **Autocorrection only when the intent is unambiguous**, and always visible: hash-prefix and diff-row stripping produce a warning; the boundary-duplication fix is silent because the duplicate never reaches the file. Literal content is never silently altered when the intent is ambiguous (numbered deletion rows and unified-diff lines are written verbatim).
-- **Byte-exact preservation.** UTF-8 BOMs, CRLF, LF, and CR-only line endings, file permissions, and trailing newlines survive edits and undo.
+- **Byte-exact preservation.** UTF-8 BOMs, CRLF, LF, and CR-only line endings, file permissions, and trailing newlines survive edits and undo; files with mixed line endings are normalized to a single line ending on edit.
 - **Atomic and ordered writes.** Files are written via temp-file-then-rename; symlink chains are resolved so the target is updated without replacing the symlink; hard-linked files are updated in place; concurrent edits to the same underlying file serialize through a per-target mutation queue.
 - **One edit per call.** The request shape stays `{path, hash_range_inclusive, content_lines}` from schema through validation to application; there is no batching dialect.
 
+## Troubleshooting
+
+- **Stale anchors.** `[E_STALE_ANCHOR]` / `[E_AMBIGUOUS_ANCHOR]` mean the file changed since the anchors were read, or an earlier `read` never happened. Call `read` for fresh anchors and retry.
+- **Reset the hash store.** Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars). Quit pi, delete those three files, and the store is rebuilt on the next session. Anchor history is lost, but no project files are touched.
+- **Corrupt store.** If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` (plus `-wal`/`-shm` variants) and rebuilt automatically; the quarantined files can be deleted once a healthy store exists.
+- **Legacy migration.** On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`, which can be deleted.
+- **`[E_UNDO_UNAVAILABLE]`.** The edit was refused because the undo record could not be written — check disk space and that the config directory is writable, then retry.
+
 ## Development
 
 Requires [Node.js](https://nodejs.org) ≥ 22.13 and npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 62-symbol, perfect hashing)",
   "main": "index.ts",

package/prompts/replace-guidelines.md

@@ -1,3 +1,4 @@
 - `replace`: hash_range_inclusive must use only anchors from the most recent read of the same file.
 - `replace`: content_lines is a native JSON array of strings — never a serialized JSON string. When copying a line from read output, remove its HASH│ prefix and keep the leading whitespace exactly as shown.
-- `replace`: minimize the replaced range — anchor only the lines that actually change; for insertions use a single-line range (e.g. the line after the insertion point) instead of a whole block, so fewer unchanged lines must be reproduced byte-exact.
+- `replace`: minimize the replaced range — anchor only the lines that actually change; for insertions use a single-line range (e.g. the line after the insertion point) instead of a whole block, so fewer unchanged lines must be reproduced byte-exact.
+- `replace`: content_lines entries are single lines — never embed a line break inside an entry; pass each line as its own array entry.

package/src/file-kind.ts

@@ -39,12 +39,6 @@ function isTextType(mimeType: string): boolean {
   return mimeType.startsWith("text/") || TEXT_TYPES.has(mimeType);
 }
 
-export type FKind =
-  | { kind: "directory" }
-  | { kind: "image"; mimeType: string }
-  | { kind: "text" }
-  | { kind: "binary"; description: string };
-
 export type LFile =
   | { kind: "directory" }
   | { kind: "image"; mimeType: string }
@@ -149,17 +143,3 @@ export async function loadFileKindAndText(
     await fileHandle.close();
   }
 }
-
-export async function classifyFileKind(filePath: string): Promise<FKind> {
-  const loaded = await loadFileKindAndText(filePath);
-  switch (loaded.kind) {
-    case "directory":
-      return loaded;
-    case "image":
-      return loaded;
-    case "binary":
-      return loaded;
-    case "text":
-      return { kind: "text" };
-  }
-}

package/src/fs-write.ts

@@ -9,8 +9,6 @@ import {
 	rm,
 	stat,
 	writeFile,
-	copyFile,
-	chmod,
 } from "fs/promises";
 import { dirname, join, parse, resolve, sep } from "path";
 import { errCode } from "./utils";
@@ -153,20 +151,6 @@ export async function writeAtomic(
     await rename(tempPath, targetPath);
     await syncDir(dir);
   } catch (error: unknown) {
-    if (errCode(error) === "EXDEV") {
-      try {
-        await copyFile(tempPath, targetPath);
-        if (existingStats) {
-          await chmod(targetPath, existingStats.mode & 0o7777);
-        }
-        await rm(tempPath, { force: true });
-        await syncDir(dir);
-        return;
-      } catch {
-        try { await rm(tempPath, { force: true }); } catch {}
-        throw error;
-      }
-    }
     if (process.platform === "win32" && errCode(error) === "EPERM") {
       try {
         await writeFile(targetPath, content, "utf-8");

package/src/hash-store.ts

@@ -324,10 +324,6 @@ export function upsertSnapshot(
   store.stmts.upsert(path, checksum, lineCount, JSON.stringify(hashes), Date.now());
 }
 
-export function deleteSnapshot(store: HashStore, path: string): void {
-  store.stmts.deleteOne(path);
-}
-
 export function upsertUndo(store: HashStore, path: string, entry: UndoRecord): void {
   store.stmts.undoUpsert(
     path,

package/src/hashline/hash.ts

@@ -234,6 +234,16 @@ function mapStableHashes(
     if (idx !== undefined) removedIndexes.add(idx);
   }
 
+  let spanStart = oldLines.length;
+  let spanEnd = -1;
+  for (const idx of removedIndexes) {
+    if (idx < spanStart) spanStart = idx;
+    if (idx > spanEnd) spanEnd = idx;
+  }
+  const spanLen = spanEnd >= spanStart ? spanEnd - spanStart + 1 : 0;
+  const replacementLen = newLines.length - oldLines.length + spanLen;
+  const shiftAfterSpan = spanEnd >= spanStart ? replacementLen - spanLen : 0;
+
   const survivors: { index: number; hash: string }[] = [];
   const removedEntries: { index: number; hash: string }[] = [];
   for (let i = 0; i < oldLines.length; i++) {
@@ -261,7 +271,8 @@ function mapStableHashes(
   for (const entry of survivors) {
     const candidates = newByContent.get(canon(oldLines[entry.index]!));
     if (!candidates || candidates.length === 0) continue;
-    const pos = nearestNew(candidates, entry.index);
+    const target = entry.index > spanEnd ? entry.index + shiftAfterSpan : entry.index;
+    const pos = nearestNew(candidates, target);
     if (pos < 0) continue;
     const newIdx = candidates.splice(pos, 1)[0]!;
     newHashes[newIdx] = entry.hash;

package/src/hashline/parse.ts

@@ -46,5 +46,11 @@ export function parseText(edit: string[] | string | null): string[] {
   if (typeof edit === "string") {
     throw new Error(CONTENT_LINES_NOT_STRING_MSG);
   }
+  const lineBreakIndex = edit.findIndex((line) => /[\r\n]/.test(line));
+  if (lineBreakIndex >= 0) {
+    throw new Error(
+      `[E_BAD_SHAPE] "content_lines" entry at index ${lineBreakIndex} contains a \\r or \\n line break. Pass each line as its own array entry.`,
+    );
+  }
   return edit;
 }

package/src/hashline/resolve.ts

@@ -225,7 +225,7 @@ export function stripBarePrefixes(
 			? "none of the stripped hashes match current file lines"
 			: `${matchedCount} of ${stripped.length} stripped hash(es) match current file lines`;
 	warnings.push(
-		`Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).`
+		`[E_BARE_HASH_PREFIX] Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -251,7 +251,7 @@ export function stripDiffPrefixes(
 	if (stripped.length === 0) return edit;
 	const locations = stripped.map((i) => `content_lines[${i}]`).join(", ");
 	warnings.push(
-		`Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
+		`[E_INVALID_PATCH] Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -276,7 +276,7 @@ export function swapReversedRanges(
 		return edit;
 	}
 	warnings.push(
-		`Autocorrected: hash_range_inclusive was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
+		`[E_BAD_OP] Autocorrected: hash_range_inclusive was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
 	);
 	return { ...edit, hash_range_inclusive: [endRef, startRef] as [Anchor, Anchor] };
 }

package/src/replace-render.ts

@@ -16,6 +16,7 @@ export type RRState = {
 	argsKey?: string;
 	preview?: RPreview;
 	previewGeneration?: number;
+	previewTimer?: ReturnType<typeof setTimeout>;
 };
 
 export function getPreviewInput(

package/src/replace-undo.ts

@@ -2,7 +2,7 @@ import { readFile } from "fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { loadHashStore, upsertSnapshot, upsertUndo, getUndoEntry, deleteUndo } from "./hash-store";
+import { loadHashStore, upsertSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
 import { contentChecksum } from "./hashline/hasher";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./paths";
@@ -19,9 +19,14 @@ export interface UndoEntry {
   resultContent: string;
 }
 
-export async function saveUndo(path: string, entry: UndoEntry): Promise<boolean> {
+export async function saveUndo(
+  path: string,
+  entry: UndoEntry,
+): Promise<{ persisted: boolean; restore: () => Promise<void> }> {
+  let previous: UndoRecord | undefined;
   try {
     const store = await loadHashStore();
+    previous = getUndoEntry(store, path);
     upsertUndo(store, path, {
       content: entry.content,
       bom: entry.bom,
@@ -29,11 +34,22 @@ export async function saveUndo(path: string, entry: UndoEntry): Promise<boolean>
       hashes: entry.hashes,
       resultContent: entry.resultContent,
     });
-    return true;
   } catch (error) {
     console.error("Failed to persist undo entry:", error);
-    return false;
+    return { persisted: false, restore: async () => undefined };
   }
+  return {
+    persisted: true,
+    restore: async () => {
+      try {
+        const store = await loadHashStore();
+        if (previous) upsertUndo(store, path, previous);
+        else deleteUndo(store, path);
+      } catch (error) {
+        console.error("Failed to restore previous undo entry:", error);
+      }
+    },
+  };
 }
 
 export async function getUndo(path: string): Promise<UndoEntry | undefined> {
@@ -109,6 +125,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
         }
 
         if (currentRaw === undefined) {
+          await clearUndo(mutationTargetPath);
           return {
             content: [
               {
@@ -121,6 +138,7 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
           };
         }
         if (currentRaw !== undo.bom + restoreEndings(undo.resultContent, undo.originalEnding)) {
+          await clearUndo(mutationTargetPath);
           return {
             content: [
               {

package/src/replace.ts

@@ -47,7 +47,7 @@ import { loadHashStore, type HashStore } from "./hash-store";
 
 const contentLinesSchema = Type.Array(Type.String(), {
   description:
-    "Replacement content, one string per line. Use [] to delete the range."
+    "Replacement content, one string per line; entries must not contain line breaks. Use [] to delete the range."
 });
 
 const hashRangeInclSchema = Type.Array(
@@ -78,7 +78,6 @@ export type ReplaceDetails = {
   firstChangedLine?: number;
   snapshotId?: string;
   classification?: "noop";
-  structureOutline?: string[];
   metrics?: RMetrics;
 };
 
@@ -99,6 +98,8 @@ interface PipelineResult {
   totalRemovedLines: number;
 }
 
+const PREVIEW_DEBOUNCE_MS = 150;
+
 const ROOT_KS = new Set(["path", "content_lines", "hash_range_inclusive"]);
 
 const LEGACY_KS = ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines", "changes"];
@@ -318,12 +319,20 @@ export function buildToolDef(): ToolDef {
     renderShell: "default",
     renderCall(args, theme, context) {
       const previewInput = getPreviewInput(args);
+      const cancelPendingPreview = () => {
+        if (context.state.previewTimer) {
+          clearTimeout(context.state.previewTimer);
+          context.state.previewTimer = undefined;
+        }
+      };
       if (context.executionStarted) {
+        cancelPendingPreview();
         context.state.argsKey = undefined;
         context.state.preview = undefined;
         context.state.previewGeneration =
           (context.state.previewGeneration ?? 0) + 1;
       } else if (!context.argsComplete || !previewInput) {
+        cancelPendingPreview();
         context.state.argsKey = undefined;
         context.state.preview = undefined;
         context.state.previewGeneration =
@@ -331,31 +340,35 @@ export function buildToolDef(): ToolDef {
       } else {
         const argsKey = JSON.stringify(previewInput);
         if (context.state.argsKey !== argsKey) {
+          cancelPendingPreview();
           context.state.argsKey = argsKey;
           context.state.preview = undefined;
           const previewGeneration = (context.state.previewGeneration ?? 0) + 1;
           context.state.previewGeneration = previewGeneration;
-          compPreview(args, context.cwd)
-            .then((preview) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = preview;
-                context.invalidate();
-              }
-            })
-            .catch((err: unknown) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = {
-                  error: err instanceof Error ? err.message : String(err),
-                };
-                context.invalidate();
-              }
-            });
+          context.state.previewTimer = setTimeout(() => {
+            context.state.previewTimer = undefined;
+            compPreview(args, context.cwd)
+              .then((preview) => {
+                if (
+                  context.state.argsKey === argsKey &&
+                  context.state.previewGeneration === previewGeneration
+                ) {
+                  context.state.preview = preview;
+                  context.invalidate();
+                }
+              })
+              .catch((err: unknown) => {
+                if (
+                  context.state.argsKey === argsKey &&
+                  context.state.previewGeneration === previewGeneration
+                ) {
+                  context.state.preview = {
+                    error: err instanceof Error ? err.message : String(err),
+                  };
+                  context.invalidate();
+                }
+              });
+          }, PREVIEW_DEBOUNCE_MS);
         }
       }
       const text =
@@ -384,6 +397,10 @@ export function buildToolDef(): ToolDef {
 
       const renderState = context.state as RRState | undefined;
       if (renderState) {
+        if (renderState.previewTimer) {
+          clearTimeout(renderState.previewTimer);
+          renderState.previewTimer = undefined;
+        }
         renderState.preview = undefined;
         renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
       }
@@ -458,21 +475,27 @@ export function buildToolDef(): ToolDef {
         }
 
         abortIf(signal);
-        await writeAtomic(
-          absolutePath,
-          bom + restoreEndings(result, originalEnding),
-        );
-        const undoPersisted = await saveUndo(mutationTargetPath, {
+        const undo = await saveUndo(mutationTargetPath, {
           content: originalNormalized,
           bom,
           originalEnding,
           hashes: originalHashes,
           resultContent: result,
         });
-        if (!undoPersisted) {
-          warnings.push(
-            "Undo history could not be persisted; undo_last_replace will not be available for this edit.",
+        if (!undo.persisted) {
+          throw new Error(
+            `[E_UNDO_UNAVAILABLE] Cannot persist undo history to the hash store; the edit was NOT applied and ${path} is unchanged. Retry the replace, or use write if the store cannot be recovered.`
+          );
+        }
+        try {
+          abortIf(signal);
+          await writeAtomic(
+            absolutePath,
+            bom + restoreEndings(result, originalEnding),
           );
+        } catch (error) {
+          await undo.restore();
+          throw error;
         }
         const updatedSnapshotId = (await fileSnap(absolutePath))
           .snapshotId;

package/src/validation.ts

@@ -35,8 +35,3 @@ export function valKind(file: LFile, path: string): asserts file is { kind: "tex
 	}
 }
 
-
-export function isText(file: LFile): file is { kind: "text"; text: string; hadUtf8DecodeErrors?: true } {
-	return file.kind === "text";
-}
-