pi-hashline-edit-pro 0.11.2 → 0.11.4

package/README.md

@@ -66,19 +66,14 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 {
   "path": "src/main.ts",
   "edits": [
-    { "old_range": ["ve7", "ve7"], "new_lines": ["  console.log('hashline');"] }
+    { "hash_range_incl": ["ve7", "ve7"], "new_lines": ["  console.log('hashline');"] }
   ]
 }
 ```
-
-| Field | Purpose |
-|---|---|
-| `old_range` | Inclusive line range `[start_hash, end_hash]` (required). |
-| `new_lines` | Replacement content (one string per line). Use `[]` to delete. |
+| `hash_range_incl` | Inclusive line range `[start_hash, end_hash]` (required). |
 
 - **Request structure validation.** The request envelope (`path`, `edits`) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
-- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
-
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_incl: ["<START>", "<END>"], new_lines: [...]}`.
 All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
 
 ### Chained edits
@@ -105,7 +100,7 @@ The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details
 - **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error tells the model to call `read()` to get fresh anchors, then copy the 3-character HASH from each line into the next replace call.
 - **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
 - **Strict patch content.** If `new_lines` contains `+HASH│` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH│` content (the first 4 chars of a `new_lines` entry looking like 3 base64 chars + `│`) is also rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
-- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_incl: ["<START>", "<END>"], new_lines: [...]}`.
 - **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.
 - **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 includes the surviving line's post-edit hash so the model can reference it in a follow-up edit. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "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/read.md

@@ -12,6 +12,7 @@ File kinds:
 - Text files are returned as `HASH│content` lines.
 - Images (JPEG, PNG, GIF, WebP) are returned as visual attachments.
 - Binary files and directories 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.
 
 Non-UTF-8 bytes:
-- Non-UTF-8 bytes are decoded as U+FFFD. The output is flagged when this happens.
+- UTF-8 byte-order marks (BOM) are stripped. Editing a file with a BOM rewrites it without the BOM.

package/prompts/replace.md

@@ -7,10 +7,6 @@ How to use:
 1. Call `read` to get HASH anchors:
 ```
 read({ path: "src/main.ts" })
-// Returns:
-// MQX│const x = 1;
-// ZPM│const y = 2;
-// VRW│const z = 3;
 ```
 
 2. Copy the 3-character HASH (before `│`) into `hash_range_incl`:
@@ -48,6 +44,22 @@ Examples:
 ] }
 ```
 
+4. Append after the last line (include the old last line so the new line is added after it):
+
+```json
+{ "path": "src/main.ts", "edits": [
+  { "hash_range_incl": ["ZPM", "ZPM"], "new_lines": ["old last line", "new line"] }
+] }
+```
+
+5. Seed content into an empty file (replace the single empty-line hash returned by read):
+
+```json
+{ "path": "src/main.ts", "edits": [
+  { "hash_range_incl": ["aB3", "aB3"], "new_lines": ["first line", "second line"] }
+] }
+```
+
 ⚠️ Common mistake: do not copy the `HASH│` prefix into `new_lines`.
 
 Wrong:
@@ -92,7 +104,7 @@ Error recovery:
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
 - `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
 - `[E_BAD_SHAPE]` — malformed request or edit item (missing fields, wrong types, unknown fields).
-- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_range` format detected. Use `{hash_range_incl, new_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_incl, new_lines}` instead.
 - `[E_EDIT_CONFLICT]` — two edits overlap on the same line range. Make edits non-overlapping.
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
 - `[E_BARE_HASH_PREFIX]` — a `new_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_incl` uses hashes, `new_lines` does not.

package/src/fs-write.ts

@@ -5,6 +5,7 @@ import {
 	open,
 	readlink,
 	rename,
+	rm,
 	stat,
 	writeFile,
 } from "fs/promises";
@@ -102,5 +103,14 @@ export async function writeAtomic(
 		await tempHandle.close();
 	}
 
-	await rename(tempPath, targetPath);
+	try {
+		await rename(tempPath, targetPath);
+	} catch (error: unknown) {
+		try {
+			await rm(tempPath, { force: true });
+		} catch {
+			// best-effort cleanup
+		}
+		throw error;
+	}
 }

package/src/hashline/apply.ts

@@ -216,7 +216,8 @@ export function applyEdits(
 	edits: import("./resolve").HEdit[],
 	signal?: AbortSignal,
 	precomputedHashes?: string[],
-): {
+	filePath?: string,
+	): {
 	content: string;
 	firstChangedLine: number | undefined;
 	lastChangedLine: number | undefined;
@@ -252,12 +253,11 @@ export function applyEdits(
 	);
 	if (mismatches.length) {
 		throw new Error(
-			fmtMismatch(mismatches, lineIndex.fileLines, fileHashes),
+			fmtMismatch(mismatches, lineIndex.fileLines, fileHashes, filePath),
 		);
 	}
 
-	const barePrefixWarnings = assertNoBarePrefix(edits, lineIndex.fileLines, fileHashes);
-	warnings.push(...barePrefixWarnings);
+	assertNoBarePrefix(edits, lineIndex.fileLines, fileHashes);
 	warnUnicodeEsc(edits, warnings);
 
 	const orderedSpans = resSpans(

package/src/hashline/hash.ts

@@ -62,6 +62,17 @@ function canon(line: string): string {
 	return line.replace(/\r/g, "").trimEnd();
 }
 
+/**
+ * Compute a unique 3-character hash for every line of `content`.
+ *
+ * Each line is hashed with xxHash32 over its canonical form (trailing
+ * whitespace and CR characters stripped). If the base hash collides with a
+ * hash already assigned to an earlier line, a retry counter (`:R{retry}`)
+ * is appended to the canonical content and the hash is recomputed until a
+ * unique anchor is found. This perfect-hashing step guarantees every line
+ * in a file receives a distinct anchor, even when multiple lines contain
+ * identical text (e.g. repeated `}` or `import` statements).
+ */
 export function lineHashes(content: string): string[] {
 	const lines = content.split("\n");
 	const hashes = new Array<string>(lines.length);

package/src/hashline/resolve.ts

@@ -79,6 +79,7 @@ export function fmtMismatch(
 	mismatches: HMismatch[],
 	fileLines: string[],
 	fileHashes: string[],
+	filePath?: string,
 	): string {
 	assertAligned(fileLines, fileHashes, "fmtMismatch");
 
@@ -88,15 +89,15 @@ export function fmtMismatch(
 
 	const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
 	if (notFound.length > 0) {
-	out.push(
-		`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH from each line into your next replace call.`
-	);
+		out.push(
+			`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-char HASH from each line into your next replace call.`
+		);
 	}
 	if (ambiguous.length > 0) {
 		if (out.length > 0) out.push("");
-	out.push(
-		`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}. Call read() to get fresh anchors, then copy the 3-char HASH from each line into your next replace call.`
-	);
+		out.push(
+			`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH from each line into your next replace call.`
+		);
 		for (const m of ambiguous) {
 			const sample = (m.candidates ?? []).slice(0, 5);
 			const more =
@@ -187,8 +188,7 @@ export function assertNoBarePrefix(
 	edits: HEdit[],
 	fileLines: string[],
 	fileHashes: string[],
-): string[] {
-	assertAligned(fileLines, fileHashes, "assertNoBarePrefix");
+): void {
 	const suspects: { line: string; hash: string; editIndex: number; lineIndex: number }[] = [];
 	for (let editIndex = 0; editIndex < edits.length; editIndex++) {
 		const edit = edits[editIndex]!;
@@ -198,8 +198,7 @@ export function assertNoBarePrefix(
 			if (match) suspects.push({ line, hash: match[1]!, editIndex, lineIndex });
 		}
 	}
-	if (suspects.length === 0) return [];
-
+	if (suspects.length === 0) return;
 	const locations = suspects
 		.map((s) => `edit ${s.editIndex}, new_lines[${s.lineIndex}]`)
 		.join("; ");

package/src/read.ts

@@ -51,12 +51,14 @@ export function fmtReadPreview(
 	const startLine = normPosInt(options.offset, "offset") ?? 1;
 	if (totalLines === 0) {
 		if (startLine === 1) {
+			const allHashes = precomputedHashes ?? lineHashes(text);
+			const emptyLineHash = allHashes[0] ?? "";
 			return {
-				text: "File is empty. Use edit to insert content.",
+				text: `${emptyLineHash}│\n[File is empty. Use replace to insert content.]`,
 			};
 		}
 		return {
-			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit to insert content.`,
+			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use replace to insert content.`,
 		};
 
 	}

package/src/replace-normalize.ts

@@ -12,16 +12,6 @@ function coerceEditsArray(edits: unknown): unknown {
 	}
 }
 
-function normalizeEditItem(item: unknown): unknown {
-	if (!isRec(item)) return item;
-	const record: Record<string, unknown> = { ...item };
-	// Rename old_range to hash_range_incl for backward compatibility
-	if (has(record, "old_range") && !has(record, "hash_range_incl")) {
-		record.hash_range_incl = record.old_range;
-		delete record.old_range;
-	}
-	return record;
-}
 
 export function normReq(input: unknown): unknown {
 	if (!isRec(input)) {
@@ -41,10 +31,6 @@ export function normReq(input: unknown): unknown {
 		record.edits = coerceEditsArray(record.edits);
 	}
 
-	// Normalize each edit item: rename old_range to hash_range_incl
-	if (Array.isArray(record.edits)) {
-		record.edits = record.edits.map(normalizeEditItem);
-	}
 
 	return record;
 }

package/src/replace-render.ts

@@ -1,5 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { normReq } from "./replace-normalize";
+import type { HTEdit } from "./hashline";
 import type { ReqParams, ReplaceDetails } from "./replace";
 import { isRec } from "./utils";
 
@@ -31,12 +32,16 @@ export function getPreviewInput(
 		return null;
 	}
 
-	const request: ReqParams = { path: normalized.path };
-	if (Array.isArray(normalized.edits)) {
-		request.edits = normalized.edits as any;
+	if (!Array.isArray(normalized.edits)) {
+		return null;
 	}
 
-	return request.edits !== undefined ? request : null;
+	const request: ReqParams = {
+		path: normalized.path,
+		edits: normalized.edits as HTEdit[],
+	};
+
+	return request;
 }
 
 export function colorLines(lines: string[], theme: FgT): string[] {

package/src/replace-response.ts

@@ -1,3 +1,4 @@
+import type { ReplaceDetails } from "./replace";
 import { genDiff } from "./replace-diff";
 import {
 	affRange,
@@ -10,7 +11,7 @@ import { ANCHOR_BUDGET } from "./constants";
 type TResult = {
 	content: Array<{ type: "text"; text: string }>;
 	isError?: boolean;
-	details: any;
+	details: ReplaceDetails;
 };
 
 export type RMetrics = {
@@ -175,7 +176,7 @@ export function buildChanged(input: SuccessInput): TResult {
 					: "Anchors omitted; use read for subsequent edits.";
 			})()
 		: resultLines.length === 0
-			? "File is empty. Use edit to insert content."
+			? "File is empty. Use replace to insert content."
 			: "";
 	const text = [anchorsBlock, warningsBlock.trimStart()]
 		.filter((section) => section.length > 0)

package/src/replace.ts

@@ -66,16 +66,14 @@ const editItemSchema = Type.Object(
 export const editToolSchema = Type.Object(
 	{
 		path: Type.String({ description: "path" }),
-		edits: Type.Optional(
-			Type.Array(editItemSchema, { description: "edits over $path" }),
-		),
+		edits: Type.Array(editItemSchema, { description: "edits over $path" }),
 	},
 	{ additionalProperties: false },
 );
 
 export type ReqParams = {
 	path: string;
-	edits?: HTEdit[];
+	edits: HTEdit[];
 };
 
 export type ReplaceDetails = {
@@ -99,7 +97,7 @@ export function assertReq(
 		throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
 	}
 
-	for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "start", "end", "lines"]) {
+	for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines"]) {
 		if (has(request, legacyKey)) {
 			throw new Error(
 				`[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_incl: ["<START>", "<END>"], new_lines: [...]}.`
@@ -113,8 +111,8 @@ export function assertReq(
 		throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string.');
 	}
 
-	if (has(request, "edits") && !Array.isArray(request.edits)) {
-		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array when provided. Each edit is { hash_range_incl: ["<START>", "<END>"], new_lines: [...] }.');
+	if (!Array.isArray(request.edits)) {
+		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array. Each edit is { hash_range_incl: ["<START>", "<END>"], new_lines: [...] }.');
 	}
 }
 
@@ -157,6 +155,7 @@ async function execPipeline(
 		resolved,
 		signal,
 		originalHashes,
+		path,
 	);
 
 	return {