pi-hashline-edit-pro 0.10.0 → 0.11.1

package/index.ts

@@ -1,37 +1,37 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readFile } from "fs/promises";
 import { join, isAbsolute } from "path";
-import { computeLineHashes, ensureHasherReady, formatHashlineRegion } from "./src/hashline";
-import { registerReplaceTool } from "./src/replace";
-import { registerReadTool } from "./src/read";
-import { normalizeToLF } from "./src/replace-diff";
-import { getVisibleLines } from "./src/utils";
-import { AUTO_READ_MAX_LINES } from "./src/constants";
+import { lineHashes, initHasher, fmtRegion } from "./src/hashline";
+import { regReplace } from "./src/replace";
+import { regRead } from "./src/read";
+import { toLF } from "./src/replace-diff";
+import { visLines } from "./src/utils";
+import { AUTO_READ_MAX } from "./src/constants";
 
 export default function (pi: ExtensionAPI): void {
-  registerReadTool(pi);
-  registerReplaceTool(pi);
+  regRead(pi);
+  regReplace(pi);
 
   pi.on("session_start", async (_event, ctx) => {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
-    await ensureHasherReady();
+    await initHasher();
   });
 
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
-  let autoReadEnabled = autoReadValue === "1" || autoReadValue === "true";
+  let autoRead = autoReadValue === "1" || autoReadValue === "true";
 
   pi.registerCommand("toggle-auto-read", {
     description: "Toggle automatic hashline anchors after write operations",
     handler: async (_args, ctx) => {
-      autoReadEnabled = !autoReadEnabled;
-      const state = autoReadEnabled ? "enabled" : "disabled";
+      autoRead = !autoRead;
+      const state = autoRead ? "enabled" : "disabled";
       ctx.ui.notify(`Auto-read after write: ${state}`, "info");
     },
   });
 
   pi.on("tool_result", async (event, ctx) => {
-    if (!autoReadEnabled) return;
+    if (!autoRead) return;
     if (event.toolName !== "write" || event.isError) return;
 
     const filePath = (event.input as Record<string, unknown>)?.path;
@@ -41,20 +41,20 @@ export default function (pi: ExtensionAPI): void {
       const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
       const content = await readFile(absolutePath, "utf-8");
 
-      const normalized = normalizeToLF(content);
-      const visibleLines = getVisibleLines(normalized);
+      const normalized = toLF(content);
+      const visibleLines = visLines(normalized);
 
       if (visibleLines.length === 0) return;
 
-      const truncated = visibleLines.length > AUTO_READ_MAX_LINES;
-      const displayLines = truncated ? visibleLines.slice(0, AUTO_READ_MAX_LINES) : visibleLines;
+      const truncated = visibleLines.length > AUTO_READ_MAX;
+      const displayLines = truncated ? visibleLines.slice(0, AUTO_READ_MAX) : visibleLines;
 
-      const hashes = computeLineHashes(normalized);
+      const hashes = lineHashes(normalized);
       const selectedHashes = hashes.slice(0, displayLines.length);
-      const hashlineOutput = formatHashlineRegion(selectedHashes, displayLines);
+      const hashlineOutput = fmtRegion(selectedHashes, displayLines);
 
       const paginationHint = truncated
-        ? `\n\n[Showing lines 1-${AUTO_READ_MAX_LINES} of ${visibleLines.length}. Use offset=${AUTO_READ_MAX_LINES + 1} to continue.]`
+        ? `\n\n[Showing lines 1-${AUTO_READ_MAX} of ${visibleLines.length}. Use offset=${AUTO_READ_MAX + 1} to continue.]`
         : "";
 
       if (hashlineOutput) {
@@ -75,4 +75,4 @@ export default function (pi: ExtensionAPI): void {
       ctx.ui.notify("Hashline Edit mode active", "info");
     });
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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-guidelines.md

@@ -1,3 +1,3 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
 - After a successful `replace`, the response text is empty (warnings only). Call `read` to get fresh anchors for follow-up edits.
-- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH from each line into `old_range`, and retry.
+- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH from each line into `hash_range_incl`, and retry.

package/prompts/replace.md

@@ -13,10 +13,10 @@ read({ path: "src/main.ts" })
 // VRW│const z = 3;
 ```
 
-2. Copy the 3-character HASH (before `│`) into `old_range`:
+2. Copy the 3-character HASH (before `│`) into `hash_range_incl`:
 ```json
 { "path": "src/main.ts", "edits": [
-  { "old_range": ["MQX", "MQX"], "new_lines": ["const x = 99;"] }
+  { "hash_range_incl": ["MQX", "MQX"], "new_lines": ["const x = 99;"] }
 ] }
 ```
 
@@ -25,14 +25,14 @@ Examples:
 1. Single line replace:
 ```json
 { "path": "src/main.ts", "edits": [
-  { "old_range": ["MQX", "MQX"], "new_lines": ["const x = 1;"] }
+  { "hash_range_incl": ["MQX", "MQX"], "new_lines": ["const x = 1;"] }
 ] }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
 { "path": "src/main.ts", "edits": [
-  { "old_range": ["ZPM", "VRW"], "new_lines": [
+  { "hash_range_incl": ["ZPM", "VRW"], "new_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
@@ -43,8 +43,8 @@ Examples:
 3. Multiple regions in one call (delete two non-adjacent ranges):
 ```json
 { "path": "src/server.ts", "edits": [
-  { "old_range": ["aB3", "xY7"], "new_lines": [] },
-  { "old_range": ["MQX", "ZPM"], "new_lines": [] }
+  { "hash_range_incl": ["aB3", "xY7"], "new_lines": [] },
+  { "hash_range_incl": ["MQX", "ZPM"], "new_lines": [] }
 ] }
 ```
 
@@ -52,38 +52,38 @@ Examples:
 
 Wrong:
 ```json
-{ "old_range": ["F4T", "F4T"], "new_lines": ["F4T│import { x } from \"./x\";"] }
+{ "hash_range_incl": ["F4T", "F4T"], "new_lines": ["F4T│import { x } from \"./x\";"] }
 ```
 
 Right:
 ```json
-{ "old_range": ["F4T", "F4T"], "new_lines": ["import { x } from \"./x\";"] }
+{ "hash_range_incl": ["F4T", "F4T"], "new_lines": ["import { x } from \"./x\";"] }
 ```
 
-`old_range` uses the hash anchor. `new_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
+`hash_range_incl` uses the hash anchor. `new_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
 
-⚠️ Common mistake: `old_range` is only the 3-character HASH, not the full `HASH│content` line.
+⚠️ Common mistake: `hash_range_incl` is only the 3-character HASH, not the full `HASH│content` line.
 
 Wrong:
 ```json
-{ "old_range": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "new_lines": [...] }
+{ "hash_range_incl": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "new_lines": [...] }
 ```
 
 Right:
 ```json
-{ "old_range": ["F4T", "F4T"], "new_lines": [...] }
+{ "hash_range_incl": ["F4T", "F4T"], "new_lines": [...] }
 ```
 
 Rules:
-- `old_range` is a pair `[start, end]`. A single-line replace is `old_range: ["X", "X"]`.
+- `hash_range_incl` is a pair `[start, end]`. A single-line replace is `hash_range_incl: ["X", "X"]`.
 - To delete a range, use `new_lines: []`.
-- `old_range` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
+- `hash_range_incl` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
 - `new_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix, no `+`/`-` diff markers.
 - Don't add `""` for spacing unless you actually want a new blank line.
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `new_lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `old_range` is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
+- The `hash_range_incl` is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
 
 On success, the response text is empty (or contains only warnings if present). Call `read` to get fresh anchors for follow-up edits.
 
@@ -92,9 +92,9 @@ 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` format detected. Use `{old_range, new_lines}` instead.
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_range` 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. `old_range` uses hashes, `new_lines` does not.
+- `[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.
 - `[E_INVALID_PATCH]` — diff prefixes (`+`/`-`) in `new_lines`. Use literal content only.
-- `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+- `[E_WOULD_EMPTY]` — edit would empty a non-empty file.

package/src/constants.ts

@@ -1,6 +1,6 @@
-export const AUTO_READ_MAX_LINES = 2000;
-export const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
-export const ANCHOR_CONTEXT_LINES = 0;
-export const ANCHOR_MAX_OUTPUT_LINES = 12;
-export const FILE_TYPE_SNIFF_BYTES = 8192;
-export const MAX_FILE_BYTES = 100 * 1024 * 1024;
+export const AUTO_READ_MAX = 2000;
+export const ANCHOR_BUDGET = 50 * 1024;
+export const CTX_LINES = 0;
+export const MAX_OUT = 12;
+export const SNIFF_BYTES = 8192;
+export const MAX_BYTES = 100 * 1024 * 1024;

package/src/file-kind.ts

@@ -1,43 +1,43 @@
 import { open as fsOpen, stat as fsStat } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
-import { FILE_TYPE_SNIFF_BYTES, MAX_FILE_BYTES } from "./constants";
+import { SNIFF_BYTES, MAX_BYTES } from "./constants";
 
-const IMAGE_MIME_TYPES = new Set<string>([
+const IMG_TYPES = new Set<string>([
 	"image/jpeg",
 	"image/png",
 	"image/gif",
 	"image/webp",
 ]);
 
-const TEXT_LIKE_MIME_TYPES = new Set<string>([
+const TEXT_TYPES = new Set<string>([
 	"application/rtf",
 	"application/xml",
 	"application/x-ms-regedit",
 ]);
 
-function isTextLikeMimeType(mimeType: string): boolean {
-	return mimeType.startsWith("text/") || TEXT_LIKE_MIME_TYPES.has(mimeType);
+function isTextType(mimeType: string): boolean {
+	return mimeType.startsWith("text/") || TEXT_TYPES.has(mimeType);
 }
 
-export type FileKind =
+export type FKind =
 	| { kind: "directory" }
 	| { kind: "image"; mimeType: string }
 	| { kind: "text" }
 	| { kind: "binary"; description: string };
 
-export type LoadedFile =
+export type LFile =
 	| { kind: "directory" }
 	| { kind: "image"; mimeType: string }
 	| { kind: "text"; text: string; hadUtf8DecodeErrors?: true }
 	| { kind: "binary"; description: string };
 
-function hasNullByte(buffer: Uint8Array): boolean {
+function hasNull(buffer: Uint8Array): boolean {
 	return buffer.includes(0);
 }
 
 export async function loadFileKindAndText(
 	filePath: string,
-): Promise<LoadedFile> {
+): Promise<LFile> {
 	const pathStat = await fsStat(filePath);
 	if (pathStat.isDirectory()) {
 		return { kind: "directory" };
@@ -48,20 +48,20 @@ export async function loadFileKindAndText(
 			description: "unsupported file type",
 		};
 	}
-	if (pathStat.size > MAX_FILE_BYTES) {
+	if (pathStat.size > MAX_BYTES) {
 		return {
 			kind: "binary",
-			description: `file exceeds ${MAX_FILE_BYTES} byte limit`
+			description: `file exceeds ${MAX_BYTES} byte limit`
 		};
 	}
 
 	const fileHandle = await fsOpen(filePath, "r");
 	try {
-		const buffer = Buffer.alloc(FILE_TYPE_SNIFF_BYTES);
+		const buffer = Buffer.alloc(SNIFF_BYTES);
 		const { bytesRead } = await fileHandle.read(
 			buffer,
 			0,
-			FILE_TYPE_SNIFF_BYTES,
+			SNIFF_BYTES,
 			0,
 		);
 		if (bytesRead === 0) {
@@ -72,9 +72,9 @@ export async function loadFileKindAndText(
 		const detectedMimeType = (await fileTypeFromBuffer(sample))?.mime;
 		if (
 			detectedMimeType !== undefined &&
-			!isTextLikeMimeType(detectedMimeType)
+			!isTextType(detectedMimeType)
 		) {
-			if (IMAGE_MIME_TYPES.has(detectedMimeType)) {
+			if (IMG_TYPES.has(detectedMimeType)) {
 				return { kind: "image", mimeType: detectedMimeType };
 			}
 			return {
@@ -82,7 +82,7 @@ export async function loadFileKindAndText(
 				description: detectedMimeType,
 			};
 		}
-		if (hasNullByte(sample)) {
+		if (hasNull(sample)) {
 			return {
 				kind: "binary",
 				description: "null bytes detected",
@@ -92,7 +92,7 @@ export async function loadFileKindAndText(
 		const decoder = new TextDecoder("utf-8");
 		const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
 		let hadUtf8DecodeErrors = false;
-		const noteUtf8DecodeErrors = (chunk?: Uint8Array): void => {
+		const noteUtf8Err = (chunk?: Uint8Array): void => {
 			if (hadUtf8DecodeErrors) return;
 			try {
 				fatalDecoder.decode(chunk, { stream: chunk !== undefined });
@@ -105,7 +105,7 @@ export async function loadFileKindAndText(
 			}
 		};
 
-		noteUtf8DecodeErrors(sample);
+		noteUtf8Err(sample);
 		const parts: string[] = [decoder.decode(sample, { stream: true })];
 
 		let position = bytesRead;
@@ -113,7 +113,7 @@ export async function loadFileKindAndText(
 			const { bytesRead: chunkBytesRead } = await fileHandle.read(
 				buffer,
 				0,
-				FILE_TYPE_SNIFF_BYTES,
+				SNIFF_BYTES,
 				position,
 			);
 			if (chunkBytesRead === 0) {
@@ -121,18 +121,18 @@ export async function loadFileKindAndText(
 			}
 
 			const chunk = buffer.subarray(0, chunkBytesRead);
-			if (hasNullByte(chunk)) {
+			if (hasNull(chunk)) {
 				return {
 					kind: "binary",
 					description: "null bytes detected",
 				};
 			}
-			noteUtf8DecodeErrors(chunk);
+			noteUtf8Err(chunk);
 			parts.push(decoder.decode(chunk, { stream: true }));
 			position += chunkBytesRead;
 		}
 
-		noteUtf8DecodeErrors();
+		noteUtf8Err();
 		parts.push(decoder.decode());
 
 		return {
@@ -145,7 +145,7 @@ export async function loadFileKindAndText(
 	}
 }
 
-export async function classifyFileKind(filePath: string): Promise<FileKind> {
+export async function classifyFileKind(filePath: string): Promise<FKind> {
 	const loaded = await loadFileKindAndText(filePath);
 	switch (loaded.kind) {
 		case "directory":
@@ -157,4 +157,4 @@ export async function classifyFileKind(filePath: string): Promise<FileKind> {
 		case "text":
 			return { kind: "text" };
 	}
-}
+}

package/src/file-reader.ts

@@ -0,0 +1,48 @@
+import { constants } from "fs";
+import { lineHashes } from "./hashline";
+import { loadFileKindAndText, type LFile } from "./file-kind";
+import { toCwd } from "./path-utils";
+import { detectEnding, toLF, stripBOM } from "./replace-diff";
+import { abortIf } from "./runtime";
+import { assertText, valAccess } from "./validation";
+
+export interface NormFile {
+	absolutePath: string;
+	normalized: string;
+	bom: string;
+	originalEnding: "\r\n" | "\n";
+	fileHashes: string[];
+	hadUtf8DecodeErrors: boolean;
+}
+
+export async function readNormFile(
+	path: string,
+	cwd: string,
+	signal: AbortSignal | undefined,
+	accessMode: number = constants.R_OK,
+	preloadedFile?: LFile,
+): Promise<NormFile> {
+	const absolutePath = toCwd(path, cwd);
+
+	abortIf(signal);
+	await valAccess(absolutePath, path, accessMode);
+
+	abortIf(signal);
+	const file = preloadedFile ?? (await loadFileKindAndText(absolutePath));
+	assertText(file, path);
+
+	abortIf(signal);
+	const { bom, text: rawContent } = stripBOM(file.text);
+	const originalEnding = detectEnding(rawContent);
+	const normalized = toLF(rawContent);
+	const fileHashes = lineHashes(normalized);
+
+	return {
+		absolutePath,
+		normalized,
+		bom,
+		originalEnding,
+		fileHashes,
+		hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
+	};
+}

package/src/fs-write.ts

@@ -9,8 +9,9 @@ import {
 	writeFile,
 } from "fs/promises";
 import { dirname, join, parse, resolve, sep } from "path";
+import { errCode } from "./validation";
 
-export async function resolveMutationTargetPath(path: string): Promise<string> {
+export async function resolveTarget(path: string): Promise<string> {
 	const absolutePath = resolve(path);
 	const { root } = parse(absolutePath);
 	const parts = absolutePath
@@ -19,7 +20,7 @@ export async function resolveMutationTargetPath(path: string): Promise<string> {
 		.filter((part) => part.length > 0);
 	const visitedSymlinks = new Set<string>();
 
-	async function resolveFromParts(
+	async function resParts(
 		currentPath: string,
 		remainingParts: string[],
 	): Promise<string> {
@@ -33,7 +34,7 @@ export async function resolveMutationTargetPath(path: string): Promise<string> {
 		try {
 			const candidateStats = await lstat(candidatePath);
 			if (!candidateStats.isSymbolicLink()) {
-				return resolveFromParts(candidatePath, tail);
+				return resParts(candidatePath, tail);
 			}
 
 			if (visitedSymlinks.has(candidatePath)) {
@@ -53,32 +54,32 @@ export async function resolveMutationTargetPath(path: string): Promise<string> {
 				.slice(parse(linkTargetPath).root.length)
 				.split(sep)
 				.filter((part) => part.length > 0);
-			return resolveFromParts(parse(linkTargetPath).root, [
+			return resParts(parse(linkTargetPath).root, [
 				...targetParts,
 				...tail,
 			]);
-		} catch (error: unknown) {
-			if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
-				return join(candidatePath, ...tail);
-			}
-			throw error;
+	} catch (error: unknown) {
+		if (errCode(error) === "ENOENT") {
+			return join(candidatePath, ...tail);
 		}
+		throw error;
+	}
 	}
 
-	return resolveFromParts(root, parts);
+	return resParts(root, parts);
 }
 
-export async function writeFileAtomically(
+export async function writeAtomic(
 	path: string,
 	content: string,
 ): Promise<void> {
-	const targetPath = await resolveMutationTargetPath(path);
+	const targetPath = await resolveTarget(path);
 
 	let existingStats: Awaited<ReturnType<typeof stat>> | null = null;
 	try {
 		existingStats = await stat(targetPath);
 	} catch (error: unknown) {
-		if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+		if (errCode(error) !== "ENOENT") {
 			throw error;
 		}
 	}