pi-hashline-edit-pro 0.11.3 → 0.11.5

package/package.json

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

@@ -44,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:

package/src/file-kind.ts

@@ -3,158 +3,158 @@ import { fileTypeFromBuffer } from "file-type";
 import { SNIFF_BYTES, MAX_BYTES } from "./constants";
 
 const IMG_TYPES = new Set<string>([
-	"image/jpeg",
-	"image/png",
-	"image/gif",
-	"image/webp",
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
 ]);
 
 const TEXT_TYPES = new Set<string>([
-	"application/rtf",
-	"application/xml",
-	"application/x-ms-regedit",
+  "application/rtf",
+  "application/xml",
+  "application/x-ms-regedit",
 ]);
 
 function isTextType(mimeType: string): boolean {
-	return mimeType.startsWith("text/") || TEXT_TYPES.has(mimeType);
+  return mimeType.startsWith("text/") || TEXT_TYPES.has(mimeType);
 }
 
 export type FKind =
-	| { kind: "directory" }
-	| { kind: "image"; mimeType: string }
-	| { kind: "text" }
-	| { kind: "binary"; description: string };
+  | { kind: "directory" }
+  | { kind: "image"; mimeType: string }
+  | { kind: "text" }
+  | { kind: "binary"; description: string };
 
 export type LFile =
-	| { kind: "directory" }
-	| { kind: "image"; mimeType: string }
-	| { kind: "text"; text: string; hadUtf8DecodeErrors?: true }
-	| { kind: "binary"; description: string };
+  | { kind: "directory" }
+  | { kind: "image"; mimeType: string }
+  | { kind: "text"; text: string; hadUtf8DecodeErrors?: true }
+  | { kind: "binary"; description: string };
 
 function hasNull(buffer: Uint8Array): boolean {
-	return buffer.includes(0);
+  return buffer.includes(0);
 }
 
 export async function loadFileKindAndText(
-	filePath: string,
+  filePath: string,
 ): Promise<LFile> {
-	const pathStat = await fsStat(filePath);
-	if (pathStat.isDirectory()) {
-		return { kind: "directory" };
-	}
-	if (!pathStat.isFile()) {
-		return {
-			kind: "binary",
-			description: "unsupported file type",
-		};
-	}
-	if (pathStat.size > MAX_BYTES) {
-		return {
-			kind: "binary",
-			description: `file exceeds ${MAX_BYTES} byte limit`
-		};
-	}
-
-	const fileHandle = await fsOpen(filePath, "r");
-	try {
-		const buffer = Buffer.alloc(SNIFF_BYTES);
-		const { bytesRead } = await fileHandle.read(
-			buffer,
-			0,
-			SNIFF_BYTES,
-			0,
-		);
-		if (bytesRead === 0) {
-			return { kind: "text", text: "" };
-		}
-
-		const sample = buffer.subarray(0, bytesRead);
-		const detectedMimeType = (await fileTypeFromBuffer(sample))?.mime;
-		if (
-			detectedMimeType !== undefined &&
-			!isTextType(detectedMimeType)
-		) {
-			if (IMG_TYPES.has(detectedMimeType)) {
-				return { kind: "image", mimeType: detectedMimeType };
-			}
-			return {
-				kind: "binary",
-				description: detectedMimeType,
-			};
-		}
-		if (hasNull(sample)) {
-			return {
-				kind: "binary",
-				description: "null bytes detected",
-			};
-		}
-
-		const decoder = new TextDecoder("utf-8");
-		const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
-		let hadUtf8DecodeErrors = false;
-		const noteUtf8Err = (chunk?: Uint8Array): void => {
-			if (hadUtf8DecodeErrors) return;
-			try {
-				fatalDecoder.decode(chunk, { stream: chunk !== undefined });
-			} catch (error: unknown) {
-				if (error instanceof TypeError) {
-					hadUtf8DecodeErrors = true;
-					return;
-				}
-				throw error;
-			}
-		};
-
-		noteUtf8Err(sample);
-		const parts: string[] = [decoder.decode(sample, { stream: true })];
-
-		let position = bytesRead;
-		while (true) {
-			const { bytesRead: chunkBytesRead } = await fileHandle.read(
-				buffer,
-				0,
-				SNIFF_BYTES,
-				position,
-			);
-			if (chunkBytesRead === 0) {
-				break;
-			}
-
-			const chunk = buffer.subarray(0, chunkBytesRead);
-			if (hasNull(chunk)) {
-				return {
-					kind: "binary",
-					description: "null bytes detected",
-				};
-			}
-			noteUtf8Err(chunk);
-			parts.push(decoder.decode(chunk, { stream: true }));
-			position += chunkBytesRead;
-		}
-
-		noteUtf8Err();
-		parts.push(decoder.decode());
-
-		return {
-			kind: "text",
-			text: parts.join(""),
-			...(hadUtf8DecodeErrors ? { hadUtf8DecodeErrors: true as const } : {}),
-		};
-	} finally {
-		await fileHandle.close();
-	}
+  const pathStat = await fsStat(filePath);
+  if (pathStat.isDirectory()) {
+    return { kind: "directory" };
+  }
+  if (!pathStat.isFile()) {
+    return {
+      kind: "binary",
+      description: "unsupported file type",
+    };
+  }
+  if (pathStat.size > MAX_BYTES) {
+    return {
+      kind: "binary",
+      description: `file exceeds ${MAX_BYTES} byte limit`
+    };
+  }
+
+  const fileHandle = await fsOpen(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(SNIFF_BYTES);
+    const { bytesRead } = await fileHandle.read(
+      buffer,
+      0,
+      SNIFF_BYTES,
+      0,
+    );
+    if (bytesRead === 0) {
+      return { kind: "text", text: "" };
+    }
+
+    const sample = buffer.subarray(0, bytesRead);
+    const detectedMimeType = (await fileTypeFromBuffer(sample))?.mime;
+    if (
+      detectedMimeType !== undefined &&
+      !isTextType(detectedMimeType)
+    ) {
+      if (IMG_TYPES.has(detectedMimeType)) {
+        return { kind: "image", mimeType: detectedMimeType };
+      }
+      return {
+        kind: "binary",
+        description: detectedMimeType,
+      };
+    }
+    if (hasNull(sample)) {
+      return {
+        kind: "binary",
+        description: "null bytes detected",
+      };
+    }
+
+    const decoder = new TextDecoder("utf-8");
+    const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
+    let hadUtf8DecodeErrors = false;
+    const noteUtf8Err = (chunk?: Uint8Array): void => {
+      if (hadUtf8DecodeErrors) return;
+      try {
+        fatalDecoder.decode(chunk, { stream: chunk !== undefined });
+      } catch (error: unknown) {
+        if (error instanceof TypeError) {
+          hadUtf8DecodeErrors = true;
+          return;
+        }
+        throw error;
+      }
+    };
+
+    noteUtf8Err(sample);
+    const parts: string[] = [decoder.decode(sample, { stream: true })];
+
+    let position = bytesRead;
+    while (true) {
+      const { bytesRead: chunkBytesRead } = await fileHandle.read(
+        buffer,
+        0,
+        SNIFF_BYTES,
+        position,
+      );
+      if (chunkBytesRead === 0) {
+        break;
+      }
+
+      const chunk = buffer.subarray(0, chunkBytesRead);
+      if (hasNull(chunk)) {
+        return {
+          kind: "binary",
+          description: "null bytes detected",
+        };
+      }
+      noteUtf8Err(chunk);
+      parts.push(decoder.decode(chunk, { stream: true }));
+      position += chunkBytesRead;
+    }
+
+    noteUtf8Err();
+    parts.push(decoder.decode());
+
+    return {
+      kind: "text",
+      text: parts.join(""),
+      ...(hadUtf8DecodeErrors ? { hadUtf8DecodeErrors: true as const } : {}),
+    };
+  } finally {
+    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" };
-	}
+  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

@@ -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,7 +253,7 @@ export function applyEdits(
 	);
 	if (mismatches.length) {
 		throw new Error(
-			fmtMismatch(mismatches, lineIndex.fileLines, fileHashes),
+			fmtMismatch(mismatches, lineIndex.fileLines, fileHashes, filePath),
 		);
 	}
 

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 =

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,6 +12,22 @@ function coerceEditsArray(edits: unknown): unknown {
 	}
 }
 
+function coerceNewLines(edits: unknown): unknown {
+  if (!Array.isArray(edits)) return edits;
+  return edits.map((edit: unknown) => {
+    if (!isRec(edit)) return edit;
+    if (typeof edit.new_lines !== "string") return edit;
+    try {
+      const parsed: unknown = JSON.parse(edit.new_lines);
+      if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+        return { ...edit, new_lines: parsed };
+      }
+    } catch {
+      // not valid JSON, leave as-is for downstream validation
+    }
+    return edit;
+  });
+}
 
 export function normReq(input: unknown): unknown {
 	if (!isRec(input)) {
@@ -29,8 +45,8 @@ export function normReq(input: unknown): unknown {
 
 	if (hasEditsField) {
 		record.edits = coerceEditsArray(record.edits);
+		record.edits = coerceNewLines(record.edits);
 	}
 
-
 	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 = {
@@ -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 {