@d3ara1n/pi-hashline-edit 0.1.0 → 0.1.1

package/src/core/parse.ts

@@ -1,11 +1,12 @@
 /**
- * 严格解析器：patch 字符串 → {@link ParsedPatch}。
+ * Strict parser: patch string → {@link ParsedPatch}.
  *
- * 核心零猜测：只接受规范格式（正确 verb + 正确锚 + `+` body 行），
- * 任何变体（裸行、旧 `oldText`/`newText`、`SWAP`/`DEL` 等）一律拒绝，
- * 交给 `transforms/normalize-legacy` 中间件归一化后再进入解析。
+ * Core principle — zero guessing: only the canonical format is accepted (correct
+ * verb + correct anchor + `+` body rows). Any variant (bare lines, legacy
+ * `oldText`/`newText`, `SWAP`/`DEL`, etc.) is rejected and left to the
+ * `transforms/normalize-legacy` middleware to normalize before parsing.
  *
- * 格式：
+ * Format:
  *
  * ```
  * file: <path>
@@ -62,7 +63,7 @@ type ParsedHeader =
 			readonly build: (body: string[]) => Edit;
 	  };
 
-/** 解析单个操作头（已 trim）。末尾冒号可选（有 body 的 verb）。 */
+/** Parse a single operation header (already trimmed). Trailing colon is optional (for body-bearing verbs). */
 function parseOpHeader(s: string): ParsedHeader {
 	let core = s;
 	if (core.endsWith(":")) core = core.slice(0, -1).trimEnd();
@@ -101,10 +102,10 @@ function parseOpHeader(s: string): ParsedHeader {
 }
 
 /**
- * 严格解析 patch。
+ * Strictly parse a patch.
  *
- * @param input patch 字符串（CRLF 自动归一为 LF）
- * @returns 解析结果；非法格式返回 `ok: false` + PatchError（含输入行号）
+ * @param input patch string (CRLF is normalized to LF automatically)
+ * @returns parse result; malformed input returns `ok: false` + PatchError (with the input line number)
  */
 export function parsePatch(input: string): ParseResult {
 	const normalized = input.replace(/\r\n/g, "\n");

package/src/core/snapshot.test.ts

@@ -2,7 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { splitLines, joinLines, createSnapshot, verifyAnchor } from "./snapshot.ts";
 
-test("splitLines 边界", () => {
+test("splitLines edge cases", () => {
 	assert.deepEqual(splitLines(""), []);
 	assert.deepEqual(splitLines("a"), ["a"]);
 	assert.deepEqual(splitLines("a\nb"), ["a", "b"]);
@@ -11,19 +11,19 @@ test("splitLines 边界", () => {
 	assert.deepEqual(splitLines("\n"), [""]);
 });
 
-test("splitLines 去掉 CRLF 的 \\r", () => {
+test("splitLines strips CRLF \\r", () => {
 	assert.deepEqual(splitLines("a\r\nb\r\n"), ["a", "b"]);
 	assert.deepEqual(splitLines("a\r\nb"), ["a", "b"]);
 });
 
-test("joinLines 行尾恢复", () => {
+test("joinLines restores line endings", () => {
 	assert.equal(joinLines(["a", "b"]), "a\nb\n");
 	assert.equal(joinLines([]), "");
 	assert.equal(joinLines(["a", "b"], "crlf"), "a\r\nb\r\n");
 	assert.equal(joinLines(["a", "b"], "lf"), "a\nb\n");
 });
 
-test("createSnapshot 记录 path/text/hashLen", () => {
+test("createSnapshot records path/text/hashLen", () => {
 	const s = createSnapshot("f.ts", "a\nb\nc\n");
 	assert.equal(s.path, "f.ts");
 	assert.equal(s.text, "a\nb\nc\n");
@@ -31,16 +31,16 @@ test("createSnapshot 记录 path/text/hashLen", () => {
 	assert.equal(s.hashLen, 4);
 });
 
-test("createSnapshot 自定义 hashLen", () => {
+test("createSnapshot custom hashLen", () => {
 	assert.equal(createSnapshot("f", "a\n", 6).hashLen, 6);
 });
 
-test("createSnapshot 记录 lineEnding", () => {
+test("createSnapshot records lineEnding", () => {
 	assert.equal(createSnapshot("f", "a\nb\n").lineEnding, "lf");
 	assert.equal(createSnapshot("f", "a\r\nb\r\n").lineEnding, "crlf");
 });
 
-test("verifyAnchor 匹配", () => {
+test("verifyAnchor match", () => {
 	const s = createSnapshot("f", "a\nb\n");
 	assert.deepEqual(verifyAnchor(s, { line: 2, hash: s.lineHashes[1] }), { ok: true, line: 2 });
 });
@@ -52,7 +52,7 @@ test("verifyAnchor hash_not_found", () => {
 	if (!r.ok) assert.equal(r.error, "hash_not_found");
 });
 
-test("verifyAnchor line_mismatch（漂移）", () => {
+test("verifyAnchor line_mismatch (drift)", () => {
 	const s = createSnapshot("f", "a\nb\n");
 	const r = verifyAnchor(s, { line: 1, hash: s.lineHashes[1] });
 	assert.equal(r.ok, false);

package/src/core/snapshot.ts

@@ -1,12 +1,16 @@
 /**
- * 文件快照与锚校验。
+ * File snapshot and anchor verification.
  *
- * 快照在 read 时记录原文 + 每行 hash；apply 时校验「当前文件 == 快照」
- * （stale 检查）以及每个锚的 hash 与行号对得上（防模型记错）。
+ * A snapshot records the original text + per-line hash at read time; at apply
+ * time it verifies "current file == snapshot" (stale check) and that each
+ * anchor's hash matches its line number (guards against the model
+ * misremembering).
  *
- * CRLF：splitLines 归一化去掉每行尾的 \r（hash 基于干净行，与模型从显示中
- * 复制的无 \r 内容一致），createSnapshot 记录原行尾，joinLines 按记录的
- * 行尾恢复——保证 CRLF 文件 edit 后行尾不变。
+ * CRLF: splitLines normalizes by stripping the trailing `\r` from each line
+ * (hashes are based on clean lines, matching the `\r`-free content the model
+ * copies from the display); createSnapshot records the original line ending,
+ * and joinLines restores it per the recorded ending — guaranteeing a CRLF file
+ * keeps its line endings after edit.
  *
  * @module pi-hashline-edit/core
  */
@@ -15,11 +19,13 @@ import { hashFileLines } from "./hash.ts";
 import type { Anchor, FileSnapshot, LineEnding } from "./types.ts";
 
 /**
- * 按行分割文本，去掉每行尾的 \r（CRLF 归一化，hash 基于干净行）。
+ * Split text into lines, stripping the trailing `\r` of each line (CRLF
+ * normalization, so hashes are based on clean lines).
  *
- * 约定：末尾换行视为最后一行的终止符，不产生多余空尾行。
+ * Convention: a trailing newline is treated as the terminator of the last line,
+ * not as producing an extra empty trailing line.
  * - `"a\nb\n"` → `["a", "b"]`
- * - `"a\r\nb\r\n"` → `["a", "b"]`（\r 去掉）
+ * - `"a\r\nb\r\n"` → `["a", "b"]` (`\r` stripped)
  * - `"a\n\n"` → `["a", ""]`
  * - `""` → `[]`
  */
@@ -29,42 +35,42 @@ export function splitLines(text: string): string[] {
 	return normalized.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
 }
 
-/** 检测文本的主导行尾（含 \r\n 即视为 CRLF）。 */
+/** Detect the dominant line ending of the text (any `\r\n` counts as CRLF). */
 export function detectLineEnding(text: string): LineEnding {
 	return text.includes("\r\n") ? "crlf" : "lf";
 }
 
-/** 把行数组 join 成文本，按指定行尾恢复（默认 LF）。非空文件末尾带换行。 */
+/** Join a line array back into text, restoring the given line ending (default LF). Non-empty files end with a newline. */
 export function joinLines(lines: readonly string[], ending: LineEnding = "lf"): string {
 	if (lines.length === 0) return "";
 	const sep = ending === "crlf" ? "\r\n" : "\n";
 	return lines.join(sep) + sep;
 }
 
-/** 为文件创建快照：记录原文 + 行尾 + 每行 context-aware hash。 */
+/** Create a snapshot for a file: record original text + line ending + per-line context-aware hash. */
 export function createSnapshot(path: string, text: string, len = 4): FileSnapshot {
 	const lines = splitLines(text);
 	const lineHashes = hashFileLines(lines, len);
 	return { path, lineHashes, text, hashLen: len, lineEnding: detectLineEnding(text) };
 }
 
-/** 锚校验结果。 */
+/** Anchor verification result. */
 export type AnchorVerifyResult =
 	| { readonly ok: true; readonly line: number }
 	| {
 			readonly ok: false;
 			readonly error: "hash_not_found" | "line_mismatch" | "collision";
-			/** hash 实际出现的行号（1-based）。 */
+			/** Line number(s) where the hash actually appears (1-based). */
 			readonly found?: readonly number[];
 	  };
 
 /**
- * 在快照中校验锚。
+ * Verify an anchor against the snapshot.
  *
- * - hash 唯一存在且行号匹配 → `ok`
- * - hash 唯一存在但行号不符 → `line_mismatch`（`found` 给真实行号；漂移，可由 relocate 中间件处理）
- * - hash 多处出现 → `collision`（`found` 给所有位置）
- * - hash 不存在 → `hash_not_found`（文件已变，需重读）
+ * - hash is unique and the line number matches → `ok`
+ * - hash is unique but the line number differs → `line_mismatch` (`found` gives the real line number; drift, handled by the relocate middleware)
+ * - hash appears at multiple lines → `collision` (`found` gives all positions)
+ * - hash does not exist → `hash_not_found` (file changed, needs re-read)
  */
 export function verifyAnchor(snapshot: FileSnapshot, anchor: Anchor): AnchorVerifyResult {
 	const found: number[] = [];

package/src/core/types.ts

@@ -1,18 +1,19 @@
 /**
- * Hashline 核心类型定义。
+ * Hashline core type definitions.
  *
  * @module pi-hashline-edit/core
  */
 
-/** 行锚：行号（1-based）+ 内容 hash 双重引用。 */
+/** Line anchor: dual reference of line number (1-based) + content hash. */
 export interface Anchor {
 	readonly line: number;
 	readonly hash: string;
 }
 
 /**
- * 编辑操作。所有带行号的操作都通过 {@link Anchor} 引用——
- * 行号给人读，hash 给机器校验，二者必须同时匹配快照。
+ * Edit operation. Every line-numbered op references a line via {@link Anchor} —
+ * the line number is for humans, the hash for machine verification; both must
+ * match the snapshot at once.
  */
 export type Edit =
 	| { readonly op: "replace"; readonly start: Anchor; readonly end?: Anchor; readonly body: string[] }
@@ -24,41 +25,41 @@ export type Edit =
 
 export type LineEnding = "lf" | "crlf";
 
-/** 文件快照：read 时记录的原文 + 每行 context-aware hash。 */
+/** File snapshot: original text recorded at read time + per-line context-aware hash. */
 export interface FileSnapshot {
 	readonly path: string;
-	/** `lineHashes[i]` = 第 (i+1) 行的 hash，长度恒等于文件行数。 */
+	/** `lineHashes[i]` = hash of line (i+1); length always equals the file's line count. */
 	readonly lineHashes: readonly string[];
 	readonly text: string;
-	/** 生成 lineHashes 时用的 hash 长度；apply 生成新快照时须沿用，避免长度不一致导致下次校验失败。 */
+	/** Hash length used when generating lineHashes; apply must reuse it for the new snapshot to avoid length drift on the next verification. */
 	readonly hashLen: number;
-	/** 原文件行尾（lf/crlf）；apply 据此恢复，保证 CRLF 文件 edit 后行尾不变。 */
+	/** Original file line ending (lf/crlf); apply restores it so a CRLF file keeps its line endings after edit. */
 	readonly lineEnding: LineEnding;
 }
 
-/** 解析出的单个文件 patch。 */
+/** A single parsed file patch. */
 export interface ParsedPatch {
 	readonly path: string;
 	readonly edits: Edit[];
 }
 
-/** 错误种类。 */
+/** Error kinds. */
 export type PatchErrorKind =
-	| "parse" // 输入格式错误
-	| "stale" // 文件已变（当前 text !== snapshot.text）
-	| "anchor" // 锚 hash 不匹配快照（模型记错）或行号越界
-	| "collision" // hash 在文件中多处出现，无法唯一定位
-	| "range" // 操作范围非法（重叠、逆序、跨空等）
-	| "noop"; // 编辑未产生变化（body 与目标行字节相同）
+	| "parse" // malformed input
+	| "stale" // file changed (current text !== snapshot.text)
+	| "anchor" // anchor hash does not match the snapshot (model misremembered) or line out of range
+	| "collision" // hash appears at multiple lines, cannot locate uniquely
+	| "range" // illegal operation range (overlap, reverse order, spanning a gap, etc.)
+	| "noop"; // edit produced no change (body byte-identical to the target)
 
 export interface PatchError {
 	readonly kind: PatchErrorKind;
 	readonly message: string;
-	/** 输入 patch 中的行号（1-based），用于错误定位。 */
+	/** Line number (1-based) in the input patch, for error localization. */
 	readonly line?: number;
 }
 
-/** 应用结果。 */
+/** Apply result. */
 export type ApplyResult =
 	| {
 			readonly ok: true;

package/src/index.ts

@@ -1,9 +1,10 @@
 /**
- * pi-hashline-edit 扩展入口。
+ * pi-hashline-edit extension entry.
  *
- * override 内置 read/edit：read 输出「行号#hash│内容」并记录快照，
- * edit 只接受 hashline patch（LINE#HASH 锚），旧 oldText/newText 明确拒绝
- * （不静默降级）。renderer 自动继承内置渲染。
+ * Overrides the built-in read/edit: read outputs "lineNo#hash│content" and
+ * records a snapshot; edit accepts only a hashline patch (LINE#HASH anchors),
+ * and legacy oldText/newText is rejected explicitly (no silent degradation).
+ * The renderer is inherited from the built-in automatically.
  *
  * @module pi-hashline-edit
  */
@@ -17,7 +18,7 @@ import { makeReadOverride } from "./pi/read-tool.ts";
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();
 
-	// session 启动/重载时刷新配置与快照
+	// refresh config and snapshots on session start / reload
 	pi.on("session_start", async () => {
 		const config = loadConfig(cwd);
 		const state = getState();

package/src/pi/config.ts

@@ -1,6 +1,7 @@
 /**
- * 配置加载：项目 `.pi/settings.json` 替换全局，per-field `??` DEFAULT 兜底。
- * 配置字段 `hashlineEdit`（去 `pi-` 前缀转 camelCase）。
+ * Config loading: project `.pi/settings.json` replaces global, per-field `??`
+ * falls back to DEFAULT. Config field `hashlineEdit` (drop the `pi-` prefix,
+ * camelCase).
  *
  * @module pi-hashline-edit/pi
  */
@@ -10,9 +11,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 export interface HashlineEditConfig {
-	/** 是否启用 hashline（false 时透传内置 read/edit）。 */
+	/** Whether hashline is enabled (when false, delegate to the built-in read/edit). */
 	enabled: boolean;
-	/** 行 hash 长度（默认 4）。 */
+	/** Line hash length (default 4). */
 	hashLen: number;
 }
 
@@ -24,7 +25,7 @@ function getAgentDir(): string {
 	return path.join(os.homedir(), ".pi", "agent");
 }
 
-/** 直接 JSON.parse，不剥注释（标准 JSON 禁止注释，出错降级默认）。 */
+/** Parse JSON directly without stripping comments (standard JSON forbids comments; on error fall back to default). */
 function readSettings(filePath: string): Record<string, unknown> {
 	try {
 		if (!fs.existsSync(filePath)) return {};
@@ -35,8 +36,8 @@ function readSettings(filePath: string): Record<string, unknown> {
 }
 
 /**
- * 加载配置。项目 `cwd/.pi/settings.json` 的 `hashlineEdit` 整块替换全局，
- * 缺失字段由 DEFAULT_CONFIG 兜底。
+ * Load config. The `hashlineEdit` in project `cwd/.pi/settings.json` replaces
+ * the global one wholesale; missing fields fall back to DEFAULT_CONFIG.
  */
 export function loadConfig(cwd?: string): HashlineEditConfig {
 	const globalSettings = readSettings(path.join(getAgentDir(), "settings.json"));

package/src/pi/edit-tool.ts

@@ -1,13 +1,16 @@
 /**
- * Override edit：只接受 hashline patch（`input`）。
+ * Override edit: accepts only a hashline patch (`input`).
  *
- * 不兼容旧 oldText/newText——发现旧格式输入时明确报错，让开发者知道
- * 模型没用新方案，而非静默降级。容错仅限不影响结果的格式归一化
- * （parse 层的可选冒号、CRLF 等）；范式级兼容一概拒绝。
+ * Not backward-compatible with legacy oldText/newText — when legacy input is
+ * detected it errors explicitly so the developer knows the model didn't use the
+ * new approach, rather than silently degrading. Tolerance is limited to
+ * format-only normalizations that don't affect the result (optional colon, CRLF
+ * at the parse layer); paradigm-level compatibility is refused outright.
  *
- * 并发安全：read-modify-write 包在 withFileMutationQueue 里，串行化同文件
- * 的多次 edit，防止 pi 默认并行执行下丢数据。响应 AbortSignal——读后/写前
- * 检查，用户取消时不落盘。
+ * Concurrency safety: the read-modify-write is wrapped in
+ * withFileMutationQueue, serializing multiple edits to the same file to prevent
+ * data loss under pi's default parallel execution. AbortSignal is honored —
+ * checked after read / before write, so a user cancel never touches the disk.
  *
  * @module pi-hashline-edit/pi
  */
@@ -19,10 +22,13 @@ import { applyEdits, parsePatch } from "../core/index.ts";
 import type { Edit, FileSnapshot, PatchError } from "../core/types.ts";
 import { canonicalPath } from "./read-tool.ts";
 import { getState, getSnapshot, putSnapshot, recordSnapshot } from "./state.ts";
+import { Text } from "@earendil-works/pi-tui";
 
-// schema 不声明 additionalProperties:false：模型误发旧 edits/oldText/newText
-// 时，这些额外字段原样到达 execute，由 missingInputError 检测并明确拒绝。
-// 依赖 typebox 默认允许额外属性 + pi validation 不 strip —— 勿改这两点。
+// The schema deliberately omits additionalProperties:false: when the model
+// mistakenly sends legacy edits/oldText/newText, those extra fields reach
+// execute as-is and are caught and rejected explicitly by missingInputError.
+// This relies on typebox allowing extra properties by default + pi validation
+// not stripping them — do not change either of these.
 
 const editSchema = Type.Object({
 	path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
@@ -34,7 +40,7 @@ const editSchema = Type.Object({
 	),
 });
 
-/** 把 PatchError 转成对模型有用的提示文本。 */
+/** Turn a PatchError into helpful hint text for the model. */
 function errorText(e: PatchError, path: string): string {
 	switch (e.kind) {
 		case "stale":
@@ -52,7 +58,7 @@ function errorText(e: PatchError, path: string): string {
 	}
 }
 
-/** 取应用后首个变更行（用于 firstChangedLine / TUI 跳转）。insert_after 取锚 +1。 */
+/** Get the first changed line after applying (for firstChangedLine / TUI jump). insert_after uses anchor + 1. */
 function minAnchorLine(edits: readonly Edit[]): number | undefined {
 	let min: number | undefined;
 	for (const e of edits) {
@@ -61,15 +67,16 @@ function minAnchorLine(edits: readonly Edit[]): number | undefined {
 		else if (e.op === "insert_after") line = e.anchor.line + 1;
 		else if (e.op === "insert_before") line = e.anchor.line;
 		else if (e.op === "prepend") line = 1;
-		// append 无锚，跳过（末尾追加）
+		// append has no anchor, skip (trailing append)
 		if (line !== undefined && (min === undefined || line < min)) min = line;
 	}
 	return min;
 }
 
 /**
- * 模型未用 hashline（发了旧 oldText/newText 或缺 input）→ 明确告知，不静默降级。
- * 导出以便测试。params 用 any 以便检测 schema 外的旧格式字段。
+ * The model didn't use hashline (sent legacy oldText/newText or is missing
+ * input) → tell it explicitly, don't silently degrade. Exported for testing.
+ * params is `any` so it can detect legacy fields outside the schema.
  */
 export function missingInputError(path: string, params: any): string {
 	const legacy =
@@ -82,7 +89,7 @@ export function missingInputError(path: string, params: any): string {
 	return `Edit ${path}: missing \`input\` (hashline patch). Read ${path} first, then send \`input\` referencing LINE#HASH anchors.`;
 }
 
-/** 构造错误 result（带 isError: true，让 TUI/agent loop 识别失败而非当成功）。 */
+/** Build an error result (with isError: true so the TUI/agent loop treats it as a failure, not a success). */
 function errResult(text: string) {
 	return {
 		isError: true as const,
@@ -110,20 +117,56 @@ export function makeEditOverride(cwd: string) {
 		parameters: editSchema,
 		renderShell: "self" as const,
 
+		renderCall(args: Static<typeof editSchema>, theme: any) {
+			let text = theme.fg("toolTitle", theme.bold("edit "));
+			text += theme.fg("accent", args.path);
+			if (args.input) {
+				const firstOp = args.input.split("\n").find((l) => l.trim() && !l.startsWith("+"));
+				if (firstOp) text += theme.fg("dim", ` — ${firstOp.trim()}`);
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result: any, { isPartial, expanded }: any, theme: any) {
+			if (isPartial) return new Text(theme.fg("warning", "Editing…"), 0, 0);
+			const content = result.content?.[0];
+			if (result.isError) {
+				const t = content?.type === "text" ? content.text.split("\n")[0] : "Error";
+				return new Text(theme.fg("error", t), 0, 0);
+			}
+			const diff: string | undefined = result.details?.diff;
+			if (!diff) {
+				const t = content?.type === "text" ? content.text : "Edited";
+				return new Text(theme.fg("success", t), 0, 0);
+			}
+			// details.diff is pi-format (+N/-N/<space>N content); color by leading char
+			const allLines = diff.split("\n");
+			const shown = expanded ? allLines : allLines.slice(0, 24);
+			const body = shown
+				.map((line: string) => {
+					if (line.startsWith("+")) return theme.fg("success", line);
+					if (line.startsWith("-")) return theme.fg("error", line);
+					return theme.fg("dim", line);
+				})
+				.join("\n");
+			const more = !expanded && allLines.length > 24 ? `\n${theme.fg("dim", `… (${allLines.length - 24} more)`)}` : "";
+			return new Text(body + more, 0, 0);
+		},
+
 		async execute(toolCallId: string, params: Static<typeof editSchema>, signal: AbortSignal | undefined, onUpdate: any) {
 			const state = getState();
-			// 用户主动关闭 hashline（config.enabled=false）→ 透传内置
+			// hashline disabled by the user (config.enabled=false) → delegate to the built-in
 			if (!state.config.enabled) return builtin.execute(toolCallId, params as any, signal, onUpdate);
 
 			const path = params.path;
 			const absPath = canonicalPath(cwd, path);
 			const input = params.input;
 
-			// 无 input → 明确告知（区分旧格式 vs 缺失），不静默降级
+			// No input → tell explicitly (distinguish legacy vs missing), don't silently degrade
 			if (typeof input !== "string" || input.trim() === "") {
 				return errResult(missingInputError(path, params as any));
 			}
-			// withFileMutationQueue 串行化同文件的 read-modify-write，防并行 edit 丢数据
+			// withFileMutationQueue serializes read-modify-write for the same file, preventing parallel-edit data loss
 			return await withFileMutationQueue(absPath, () => runHashline(absPath, path, input, signal));
 		},
 	};
@@ -137,14 +180,15 @@ async function runHashline(absPath: string, displayPath: string, input: string,
 		const msg = e instanceof Error ? e.message : String(e);
 		return errResult(`Error reading ${displayPath}: ${msg}`);
 	}
-	// 读后检查取消：用户 abort 则不继续 parse/apply，文件不变
+	// Check for cancel after read: if the user aborted, don't proceed to parse/apply; the file stays untouched
 	if (signal?.aborted) return errResult(`Edit ${displayPath} aborted before apply.`);
 
-	// 取已记录快照；若无（模型未 read）则用当前文件建立——anchor 校验仍会强制
-	// 模型用真实 hash（没读过就猜不对），自然引导它先 read。
+	// Use the recorded snapshot, or if there is none (the model didn't read) build one from the
+	// current file — anchor verification still forces the model to use a real hash (it can't guess
+	// correctly without reading), naturally steering it to read first.
 	const snap: FileSnapshot = getSnapshot(absPath) ?? recordSnapshot(absPath, currentText);
 
-	// input 不含 file 头，prepend 一个让 parsePatch 通过（path 仅作标签）
+	// input has no file header; prepend one so parsePatch passes (path is just a label)
 	const parsed = parsePatch(`file: ${absPath}\n\n${input}`);
 	if (!parsed.ok) {
 		return errResult(errorText(parsed.error, displayPath));
@@ -155,7 +199,7 @@ async function runHashline(absPath: string, displayPath: string, input: string,
 		return errResult(errorText(result.error, displayPath));
 	}
 
-	// 写前检查取消：abort 则不落盘，文件不变
+	// Check for cancel before write: if aborted, don't touch the disk; the file stays untouched
 	if (signal?.aborted) return errResult(`Edit ${displayPath} aborted before write.`);
 
 	try {
@@ -165,7 +209,7 @@ async function runHashline(absPath: string, displayPath: string, input: string,
 		return errResult(`Error writing ${displayPath}: ${msg}`);
 	}
 
-	// 更新快照：连续 edit 无需重读（result.newSnapshot 基于新文本），走 LRU
+	// Update the snapshot: consecutive edits need no re-read (result.newSnapshot is based on the new text), via LRU
 	putSnapshot(absPath, result.newSnapshot);
 
 	return {
@@ -173,8 +217,9 @@ async function runHashline(absPath: string, displayPath: string, input: string,
 			{ type: "text" as const, text: `Edited ${displayPath} (${parsed.patch.edits.length} op(s)).` },
 		],
 		details: {
-			// details.diff 必须用 pi 的 generateDiffString（+N content 格式），
-			// 内置 renderer 的 parseDiffLine 只认这个格式；core 的标准 unified diff 会被当纯文本灰显
+			// details.diff must use pi's generateDiffString (+N content format); the built-in
+			// renderer's parseDiffLine only recognizes this format — core's standard unified diff
+			// would be grayed out as plain text
 			diff: generateDiffString(currentText, result.text),
 			patch: generateUnifiedPatch(displayPath, currentText, result.text),
 			firstChangedLine: minAnchorLine(parsed.patch.edits),

package/src/pi/execute.test.ts

@@ -1,6 +1,7 @@
 /**
- * pi 接入层 execute 集成测试：驱动真实的 makeReadOverride/makeEditOverride
- * execute，覆盖文本 read 带锚、hashline edit 闭环、错误返回 isError。
+ * Integration tests for the pi integration layer's execute: drives the real
+ * makeReadOverride/makeEditOverride execute, covering text read with anchors,
+ * the hashline edit closed loop, and error returns with isError.
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -24,7 +25,7 @@ async function withDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
 
 const call = (tool: any, params: any) => tool.execute("0", params, undefined, undefined);
 
-test("read execute：文本输出 LINE#HASH│content", async () => {
+test("read execute: text outputs LINE#HASH│content", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "line1\nline2\n");
 		const read = makeReadOverride(dir);
@@ -37,18 +38,18 @@ test("read execute：文本输出 LINE#HASH│content", async () => {
 	});
 });
 
-test("read execute：记录 snapshot 供 edit 用", async () => {
+test("read execute: records a snapshot for edit", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\nb\n");
 		const read = makeReadOverride(dir);
 		await call(read, { path: "f.txt" });
 		const snap = getSnapshot(join(dir, "f.txt"));
-		assert.ok(snap, "snapshot 未记录");
+		assert.ok(snap, "snapshot not recorded");
 		assert.equal(snap!.lineHashes.length, 2);
 	});
 });
 
-test("edit execute：hashline 闭环（read → edit → 文件改）", async () => {
+test("edit execute: hashline closed loop (read → edit → file changed)", async () => {
 	await withDir(async (dir) => {
 		const f = join(dir, "f.txt");
 		await writeFile(f, "a\nb\nc\n");
@@ -59,12 +60,12 @@ test("edit execute：hashline 闭环（read → edit → 文件改）", async ()
 			path: "f.txt",
 			input: `replace 2#${snap.lineHashes[1]}:\n+B`,
 		});
-		assert.equal(r.isError, undefined, "不应是错误");
+		assert.equal(r.isError, undefined, "should not be an error");
 		assert.equal(await readFile(f, "utf-8"), "a\nB\nc\n");
 	});
 });
 
-test("edit execute：连续 edit 复用更新后的 snapshot", async () => {
+test("edit execute: consecutive edits reuse the updated snapshot", async () => {
 	await withDir(async (dir) => {
 		const f = join(dir, "f.txt");
 		await writeFile(f, "a\nb\n");
@@ -73,7 +74,7 @@ test("edit execute：连续 edit 复用更新后的 snapshot", async () => {
 		await call(read, { path: "f.txt" });
 		let snap = getSnapshot(f)!;
 		await call(edit, { path: "f.txt", input: `replace 1#${snap.lineHashes[0]}:\n+A` });
-		// 第二次 edit：snapshot 已被 edit 更新，用新 hash
+		// second edit: the snapshot was updated by the edit, use the new hash
 		snap = getSnapshot(f)!;
 		const r: any = await call(edit, { path: "f.txt", input: `replace 2#${snap.lineHashes[1]}:\n+B` });
 		assert.equal(r.isError, undefined);
@@ -81,17 +82,17 @@ test("edit execute：连续 edit 复用更新后的 snapshot", async () => {
 	});
 });
 
-test("edit execute：无 read 直接 edit → anchor 校验失败", async () => {
+test("edit execute: edit without a prior read → anchor verification fails", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\nb\n");
 		const edit = makeEditOverride(dir);
-		// 没 read 过，hash 是瞎写的
+		// never read, so the hash is made up
 		const r: any = await call(edit, { path: "f.txt", input: "replace 1#XXXX:\n+A" });
 		assert.equal(r.isError, true);
 	});
 });
 
-test("edit execute：缺 input → isError + missing 提示", async () => {
+test("edit execute: missing input → isError + missing hint", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		const r: any = await call(makeEditOverride(dir), { path: "f.txt" });
@@ -100,7 +101,7 @@ test("edit execute：缺 input → isError + missing 提示", async () => {
 	});
 });
 
-test("edit execute：旧 oldText/newText → isError + legacy 提示", async () => {
+test("edit execute: legacy oldText/newText → isError + legacy hint", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		const r: any = await call(makeEditOverride(dir), {
@@ -113,7 +114,7 @@ test("edit execute：旧 oldText/newText → isError + legacy 提示", async ()
 	});
 });
 
-test("edit execute：parse 错误 → isError", async () => {
+test("edit execute: parse error → isError", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		await call(makeReadOverride(dir), { path: "f.txt" });