@d3ara1n/pi-hashline-edit 0.1.0

package/src/pi/edit-tool.ts

@@ -0,0 +1,183 @@
+/**
+ * Override edit：只接受 hashline patch（`input`）。
+ *
+ * 不兼容旧 oldText/newText——发现旧格式输入时明确报错，让开发者知道
+ * 模型没用新方案，而非静默降级。容错仅限不影响结果的格式归一化
+ * （parse 层的可选冒号、CRLF 等）；范式级兼容一概拒绝。
+ *
+ * 并发安全：read-modify-write 包在 withFileMutationQueue 里，串行化同文件
+ * 的多次 edit，防止 pi 默认并行执行下丢数据。响应 AbortSignal——读后/写前
+ * 检查，用户取消时不落盘。
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import { createEditTool, generateDiffString, generateUnifiedPatch, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { readFile, writeFile } from "node:fs/promises";
+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";
+
+// schema 不声明 additionalProperties:false：模型误发旧 edits/oldText/newText
+// 时，这些额外字段原样到达 execute，由 missingInputError 检测并明确拒绝。
+// 依赖 typebox 默认允许额外属性 + pi validation 不 strip —— 勿改这两点。
+
+const editSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+	input: Type.Optional(
+		Type.String({
+			description:
+				"Hashline patch referencing LINE#HASH anchors from your latest read. Ops: replace / delete / insert_after / insert_before / append / prepend. Body rows start with `+`. This tool does NOT accept legacy oldText/newText.",
+		}),
+	),
+});
+
+/** 把 PatchError 转成对模型有用的提示文本。 */
+function errorText(e: PatchError, path: string): string {
+	switch (e.kind) {
+		case "stale":
+			return `File ${path} changed since your last read. Re-read it before editing.`;
+		case "anchor":
+			return `Anchor mismatch: ${e.message}. Re-read ${path} to get current line hashes (LINE#HASH).`;
+		case "collision":
+			return `Hash collision: ${e.message}. Re-read ${path}.`;
+		case "range":
+			return `Bad range: ${e.message}`;
+		case "noop":
+			return `Edit produced no change: ${e.message}`;
+		case "parse":
+			return `Parse error${e.line ? ` at line ${e.line}` : ""}: ${e.message}`;
+	}
+}
+
+/** 取应用后首个变更行（用于 firstChangedLine / TUI 跳转）。insert_after 取锚 +1。 */
+function minAnchorLine(edits: readonly Edit[]): number | undefined {
+	let min: number | undefined;
+	for (const e of edits) {
+		let line: number | undefined;
+		if (e.op === "replace" || e.op === "delete") line = e.start.line;
+		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 无锚，跳过（末尾追加）
+		if (line !== undefined && (min === undefined || line < min)) min = line;
+	}
+	return min;
+}
+
+/**
+ * 模型未用 hashline（发了旧 oldText/newText 或缺 input）→ 明确告知，不静默降级。
+ * 导出以便测试。params 用 any 以便检测 schema 外的旧格式字段。
+ */
+export function missingInputError(path: string, params: any): string {
+	const legacy =
+		Array.isArray(params?.edits) ||
+		typeof params?.oldText === "string" ||
+		typeof params?.newText === "string";
+	if (legacy) {
+		return `⚠ ${path}: you sent the legacy oldText/newText format, but this edit tool ONLY accepts hashline \`input\`. The legacy path was intentionally removed so this is surfaced, not silently degraded. Re-read ${path} to get LINE#HASH anchors, then send \`input\` (e.g. \`replace 4#aF3:\` followed by \`+\` body rows).`;
+	}
+	return `Edit ${path}: missing \`input\` (hashline patch). Read ${path} first, then send \`input\` referencing LINE#HASH anchors.`;
+}
+
+/** 构造错误 result（带 isError: true，让 TUI/agent loop 识别失败而非当成功）。 */
+function errResult(text: string) {
+	return {
+		isError: true as const,
+		content: [{ type: "text" as const, text }],
+		details: undefined,
+	};
+}
+
+export function makeEditOverride(cwd: string) {
+	const builtin = createEditTool(cwd);
+
+	return {
+		name: "edit" as const,
+		label: "edit",
+		description:
+			"Edit a file via hashline patch (LINE#HASH anchors, content-verified). Does NOT accept legacy oldText/newText.",
+		promptSnippet: "Edit files via hashline LINE#HASH anchors (input patch); legacy oldText/newText not accepted",
+		promptGuidelines: [
+			"Pass `input`: a hashline patch referencing `LINE#HASH` anchors copied from your latest read output (e.g. `replace 12#aF3:`).",
+			"Ops: `replace LINE#HASH[..LINE#HASH]:` · `delete LINE#HASH` · `insert_after LINE#HASH:` · `insert_before LINE#HASH:` · `append:` · `prepend:`.",
+			"Body rows start with `+` followed by the literal line. `+` alone = blank line. Literal `+`/`-` lines become `++`/`+-`.",
+			"After each successful edit, re-ground: line numbers shift, so take the next edit's anchors from a fresh read.",
+			"This tool does NOT accept legacy oldText/newText — sending those returns an error (intentional, so it's visible).",
+		],
+		parameters: editSchema,
+		renderShell: "self" as const,
+
+		async execute(toolCallId: string, params: Static<typeof editSchema>, signal: AbortSignal | undefined, onUpdate: any) {
+			const state = getState();
+			// 用户主动关闭 hashline（config.enabled=false）→ 透传内置
+			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 缺失），不静默降级
+			if (typeof input !== "string" || input.trim() === "") {
+				return errResult(missingInputError(path, params as any));
+			}
+			// withFileMutationQueue 串行化同文件的 read-modify-write，防并行 edit 丢数据
+			return await withFileMutationQueue(absPath, () => runHashline(absPath, path, input, signal));
+		},
+	};
+}
+
+async function runHashline(absPath: string, displayPath: string, input: string, signal: AbortSignal | undefined) {
+	let currentText: string;
+	try {
+		currentText = (await readFile(absPath)).toString("utf-8");
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		return errResult(`Error reading ${displayPath}: ${msg}`);
+	}
+	// 读后检查取消：用户 abort 则不继续 parse/apply，文件不变
+	if (signal?.aborted) return errResult(`Edit ${displayPath} aborted before apply.`);
+
+	// 取已记录快照；若无（模型未 read）则用当前文件建立——anchor 校验仍会强制
+	// 模型用真实 hash（没读过就猜不对），自然引导它先 read。
+	const snap: FileSnapshot = getSnapshot(absPath) ?? recordSnapshot(absPath, currentText);
+
+	// input 不含 file 头，prepend 一个让 parsePatch 通过（path 仅作标签）
+	const parsed = parsePatch(`file: ${absPath}\n\n${input}`);
+	if (!parsed.ok) {
+		return errResult(errorText(parsed.error, displayPath));
+	}
+
+	const result = applyEdits(currentText, parsed.patch.edits, snap);
+	if (!result.ok) {
+		return errResult(errorText(result.error, displayPath));
+	}
+
+	// 写前检查取消：abort 则不落盘，文件不变
+	if (signal?.aborted) return errResult(`Edit ${displayPath} aborted before write.`);
+
+	try {
+		await writeFile(absPath, result.text);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		return errResult(`Error writing ${displayPath}: ${msg}`);
+	}
+
+	// 更新快照：连续 edit 无需重读（result.newSnapshot 基于新文本），走 LRU
+	putSnapshot(absPath, result.newSnapshot);
+
+	return {
+		content: [
+			{ 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 会被当纯文本灰显
+			diff: generateDiffString(currentText, result.text),
+			patch: generateUnifiedPatch(displayPath, currentText, result.text),
+			firstChangedLine: minAnchorLine(parsed.patch.edits),
+		},
+	};
+}

package/src/pi/execute.test.ts

@@ -0,0 +1,124 @@
+/**
+ * pi 接入层 execute 集成测试：驱动真实的 makeReadOverride/makeEditOverride
+ * execute，覆盖文本 read 带锚、hashline edit 闭环、错误返回 isError。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { makeEditOverride } from "./edit-tool.ts";
+import { makeReadOverride } from "./read-tool.ts";
+import { clearSnapshots, getSnapshot } from "./state.ts";
+
+async function withDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+	const dir = await mkdtemp(join(tmpdir(), "hl-"));
+	clearSnapshots();
+	try {
+		return await fn(dir);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+		clearSnapshots();
+	}
+}
+
+const call = (tool: any, params: any) => tool.execute("0", params, undefined, undefined);
+
+test("read execute：文本输出 LINE#HASH│content", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "line1\nline2\n");
+		const read = makeReadOverride(dir);
+		const r: any = await call(read, { path: "f.txt" });
+		const text = r.content[0];
+		assert.equal(text.type, "text");
+		assert.match(text.text, /1#[0-9A-Z]+│line1/);
+		assert.match(text.text, /2#[0-9A-Z]+│line2/);
+		assert.match(text.text, /f\.txt · 2 lines/);
+	});
+});
+
+test("read execute：记录 snapshot 供 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.equal(snap!.lineHashes.length, 2);
+	});
+});
+
+test("edit execute：hashline 闭环（read → edit → 文件改）", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		await call(makeReadOverride(dir), { path: "f.txt" });
+		const snap = getSnapshot(f)!;
+		const edit = makeEditOverride(dir);
+		const r: any = await call(edit, {
+			path: "f.txt",
+			input: `replace 2#${snap.lineHashes[1]}:\n+B`,
+		});
+		assert.equal(r.isError, undefined, "不应是错误");
+		assert.equal(await readFile(f, "utf-8"), "a\nB\nc\n");
+	});
+});
+
+test("edit execute：连续 edit 复用更新后的 snapshot", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\n");
+		const read = makeReadOverride(dir);
+		const edit = makeEditOverride(dir);
+		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
+		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);
+		assert.equal(await readFile(f, "utf-8"), "A\nB\n");
+	});
+});
+
+test("edit execute：无 read 直接 edit → anchor 校验失败", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\nb\n");
+		const edit = makeEditOverride(dir);
+		// 没 read 过，hash 是瞎写的
+		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 () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		const r: any = await call(makeEditOverride(dir), { path: "f.txt" });
+		assert.equal(r.isError, true);
+		assert.match(r.content[0].text, /missing/);
+	});
+});
+
+test("edit execute：旧 oldText/newText → isError + legacy 提示", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ oldText: "a", newText: "b" }],
+		});
+		assert.equal(r.isError, true);
+		assert.match(r.content[0].text, /legacy/);
+		assert.match(r.content[0].text, /ONLY/);
+	});
+});
+
+test("edit execute：parse 错误 → isError", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		await call(makeReadOverride(dir), { path: "f.txt" });
+		const r: any = await call(makeEditOverride(dir), { path: "f.txt", input: "SWAP 1#X:\n+a" });
+		assert.equal(r.isError, true);
+		assert.match(r.content[0].text, /Parse error|unknown verb/);
+	});
+});

package/src/pi/pi.test.ts

@@ -0,0 +1,28 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { canonicalPath } from "./read-tool.ts";
+import { missingInputError } from "./edit-tool.ts";
+
+test("canonicalPath resolve 相对/绝对", () => {
+	assert.equal(canonicalPath("/cwd", "foo.ts"), "/cwd/foo.ts");
+	assert.equal(canonicalPath("/cwd", "./foo.ts"), "/cwd/foo.ts");
+	assert.equal(canonicalPath("/cwd", "/abs/x.ts"), "/abs/x.ts");
+});
+
+test("missingInputError: edits 数组 → 明确告知不降级", () => {
+	const msg = missingInputError("f.ts", { edits: [{ oldText: "a", newText: "b" }] });
+	assert.ok(msg.includes("legacy"), msg);
+	assert.ok(msg.includes("ONLY"), msg);
+	assert.ok(msg.includes("f.ts"), msg);
+});
+
+test("missingInputError: 顶层 oldText/newText 也识别为旧格式", () => {
+	const msg = missingInputError("f.ts", { oldText: "a", newText: "b" });
+	assert.ok(msg.includes("legacy"));
+});
+
+test("missingInputError: 仅缺 input（非旧格式）", () => {
+	const msg = missingInputError("f.ts", {});
+	assert.ok(msg.includes("missing"));
+	assert.ok(!msg.includes("legacy"));
+});

package/src/pi/read-tool.ts

@@ -0,0 +1,98 @@
+/**
+ * Override read：文本文件输出「行号#hash│内容」并记录快照；
+ * 非文本（图片/二进制）与读取错误透传内置 read，renderer 自动继承。
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import { createReadTool } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { splitLines } from "../core/snapshot.ts";
+import { getState, getSnapshot, recordSnapshot } from "./state.ts";
+
+const MAX_LINES = 2000;
+const MAX_BYTES = 256 * 1024;
+
+/** canonical path：read/edit 共用，保证 snapshot key 一致。 */
+export function canonicalPath(cwd: string, p: string): string {
+	return resolve(cwd, p);
+}
+
+/** 构造 read override（registerTool 的 ToolDefinition 片段）。 */
+export function makeReadOverride(cwd: string) {
+	const builtin = createReadTool(cwd);
+
+	return {
+		name: "read" as const,
+		label: "read",
+		description:
+			"Read file contents. Text files display per-line content hashes (LINE#HASH│content) for hashline-verified editing.",
+		promptSnippet: "Read files; each text line shows a content hash (LINE#HASH│content) anchoring it for edits",
+		promptGuidelines: [
+			'Text files display as `LINE#HASH│content` (e.g. `12#aF3│  return x`). The `#HASH` anchors each line for precise editing.',
+			"Pass `path`; optionally `offset` (1-indexed start line) and `limit` (max lines). Prefer read over cat/sed for files you intend to edit.",
+		],
+		parameters: builtin.parameters,
+
+		async execute(toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any) {
+			// 未启用 → 完全透传内置
+			// 未启用 或 用户已取消 → 透传内置（builtin 自行处理 abort）
+			if (!getState().config.enabled || signal?.aborted) return builtin.execute(toolCallId, params, signal, onUpdate);
+
+			const absPath = canonicalPath(cwd, params.path as string);
+			let buf: Buffer;
+			try {
+				buf = await readFile(absPath);
+			} catch {
+				// 读取错误 → 透传内置（它有完善的错误信息）
+				return builtin.execute(toolCallId, params, signal, onUpdate);
+			}
+
+			// 二进制/图片检测（null 字节）→ 透传内置（内置用 file-type 处理图片）
+			if (buf.includes(0)) return builtin.execute(toolCallId, params, signal, onUpdate);
+
+			const text = buf.toString("utf-8");
+			const allLines = splitLines(text);
+			const totalLines = allLines.length;
+
+			// 记录全文快照（edit 锚基于全文行号）
+			const snap = recordSnapshot(absPath, text);
+
+			// offset/limit
+			const offset = (params.offset as number | undefined) ?? 1;
+			const limit = (params.limit as number | undefined) ?? MAX_LINES;
+			const startIdx = Math.max(0, offset - 1);
+			const endIdx = Math.min(totalLines, startIdx + limit);
+
+			const rows: string[] = [];
+			let bytes = 0;
+			let truncated = false;
+			for (let i = startIdx; i < endIdx; i++) {
+				const lineNo = i + 1;
+				const row = `${lineNo}#${snap.lineHashes[i]}│${allLines[i]}`;
+				bytes += Buffer.byteLength(row, "utf-8");
+				if (bytes > MAX_BYTES) {
+					truncated = true;
+					break;
+				}
+				rows.push(row);
+			}
+
+			const shownFrom = offset > 1 ? ` (from line ${offset})` : "";
+			const tail = truncated ? `\n… (truncated at ${MAX_BYTES >> 10}KB; use offset/limit to read more)` : "";
+			const header = `${params.path} · ${totalLines} lines${shownFrom}\n`;
+			const body = rows.join("\n");
+
+			return {
+				content: [{ type: "text" as const, text: header + body + tail }],
+				details: undefined,
+			};
+		},
+	};
+}
+
+/** 供 edit override 复用：取某 path 的已记录快照（按 canonical path）。 */
+export function lookupSnapshot(cwd: string, p: string) {
+	return getSnapshot(canonicalPath(cwd, p));
+}

package/src/pi/state.ts

@@ -0,0 +1,79 @@
+/**
+ * Session 级状态：文件快照存储（LRU）+ 配置。
+ *
+ * globalThis 单例（规避 Bun module identity 问题，见仓库 AGENTS）。
+ * 快照 LRU 驱逐（默认 64 个文件），防长会话内存无限增长——冷文件被新文件挤出。
+ * read 记录、edit 校验；key 为 canonical 绝对路径。
+ * config 放 state，session_start 重载。
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import { createSnapshot } from "../core/snapshot.ts";
+import type { FileSnapshot } from "../core/types.ts";
+import type { HashlineEditConfig } from "./config.ts";
+
+const GLOBAL_KEY = "__piHashlineEdit";
+const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4 };
+/** 最多缓存的文件快照数；超出按 LRU 驱逐最久未访问的。 */
+const MAX_SNAPSHOTS = 64;
+
+export interface HashlineEditState {
+	/** canonical path → 快照。LRU 顺序：Map 插入序，最近访问的在末尾。 */
+	readonly snapshots: Map<string, FileSnapshot>;
+	hashLen: number;
+	config: HashlineEditConfig;
+}
+
+export function getState(): HashlineEditState {
+	const g = globalThis as Record<string, unknown>;
+	const existing = g[GLOBAL_KEY];
+	if (existing) return existing as HashlineEditState;
+	const state: HashlineEditState = {
+		snapshots: new Map(),
+		hashLen: DEFAULT_CONFIG.hashLen,
+		config: DEFAULT_CONFIG,
+	};
+	g[GLOBAL_KEY] = state;
+	return state;
+}
+
+/** 写入快照并维持 LRU：移到末尾（最近使用），超限驱逐最旧（Map 首项）。 */
+function touchAndEvict(map: Map<string, FileSnapshot>, path: string, snap: FileSnapshot): void {
+	if (map.has(path)) map.delete(path);
+	map.set(path, snap);
+	while (map.size > MAX_SNAPSHOTS) {
+		const oldest = map.keys().next().value;
+		if (oldest === undefined) break;
+		map.delete(oldest);
+	}
+}
+
+/** 记录文件快照（read 时调用）：算行 hash + LRU。 */
+export function recordSnapshot(canonicalPath: string, text: string): FileSnapshot {
+	const state = getState();
+	const snap = createSnapshot(canonicalPath, text, state.hashLen);
+	touchAndEvict(state.snapshots, canonicalPath, snap);
+	return snap;
+}
+
+/** 存入已算好的快照（edit 成功后更新），走 LRU。 */
+export function putSnapshot(canonicalPath: string, snap: FileSnapshot): void {
+	touchAndEvict(getState().snapshots, canonicalPath, snap);
+}
+
+/** 取文件快照（edit 校验用）；命中时移到末尾（LRU touch）。 */
+export function getSnapshot(canonicalPath: string): FileSnapshot | undefined {
+	const map = getState().snapshots;
+	const snap = map.get(canonicalPath);
+	if (snap) {
+		map.delete(canonicalPath);
+		map.set(canonicalPath, snap);
+	}
+	return snap;
+}
+
+/** 清空快照（session 重启时）。 */
+export function clearSnapshots(): void {
+	getState().snapshots.clear();
+}