@trim21/personal-pi-extensions 0.1.641 → 0.1.642

package/README.md

@@ -137,7 +137,7 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 写保护直接内置在各写工具（opencode 风格 `write`/`edit`、Claude Code 风格 `Write`/`Edit`）内部，通过 `src/lib/write-guard.ts` 的 `guardWriteAccess` 实现。读取工具（`read`、`ls`、`find`、`grep`）不受限制。
 
 - workspace 内或 `/tmp` 下的路径自动放行
-- 外部路径需通过确认对话框由用户审批（**Approve once** / **Block** / **Block with reason**），对话框内以 ```diff 代码块展示将要发生的变更预览（定位由各写工具注入自己的匹配实现，能定位时显示带行号的真实 patch，否则退化为参数 diff）
+- 外部路径需通过确认对话框由用户审批（**Approve once** / **Block** / **Block with reason**），对话框内以 ```diff 代码块展示将要发生的变更；预览由「将要写入的内容」直接算出，批准后写的就是这份内容（批准前若文件被外部改动则拒绝写入）
 - headless（无 UI）会话直接拒绝外部写入；Windows 上不提供审批路径，工作区外写入一律拒绝
 - `/bwrap-deny-request` 生效期间外部写入按无理由拒绝处理（`user deny <tool>: blocked`）
 - 无需配置，随各写工具自动生效
@@ -253,7 +253,7 @@ opencode 风格工具集，随 `src/opencode/index.ts` 一次加载：`read` / `
 
 ### edit
 
-`edit` 使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数复制自 opencode，匹配引擎位于 `src/opencode/edit-engine.ts`；写保护审批弹窗（`src/lib/write-guard.ts`）的 diff 预览由调用方注入这套引擎，因此预览与落盘同语义。唯一的有意差异是去掉了原版的转义规范化（EscapeNormalizedReplacer）：它会把源码里合法的 `\n`、`\t` 等转义序列当成模型多转义的产物做启发式反转义，可能改坏内容。
+`edit` 使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数复制自 opencode，匹配引擎位于 `src/opencode/edit-engine.ts`。唯一的有意差异是去掉了原版的转义规范化（EscapeNormalizedReplacer）：它会把源码里合法的 `\n`、`\t` 等转义序列当成模型多转义的产物做启发式反转义，可能改坏内容。
 
 支持的匹配策略：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.641",
+  "version": "0.1.642",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/claude-code/files.ts

@@ -345,31 +345,6 @@ export function registerFileTools(
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
       const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
-      await guardWriteAccess(ctx, {
-        toolName: "Edit",
-        absolutePath: filePath,
-        // 审批预览必须与落盘同语义：这里注入本工具自己的精确匹配（空 old_string
-        // 是创建/填充文件，按整文件写入预览）
-        change:
-          params.old_string === ""
-            ? { kind: "write", newText: params.new_string }
-            : {
-                kind: "edit",
-                oldText: params.old_string,
-                newText: params.new_string,
-                apply: (content) => ({
-                  contentOld: content,
-                  contentNew: applyExactEdit(
-                    content,
-                    params.old_string,
-                    params.new_string,
-                    params.replace_all ?? false,
-                  ),
-                }),
-              },
-        policy,
-        signal,
-      });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
       >(filePath, async () => {
@@ -381,11 +356,12 @@ export function registerFileTools(
         // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
         if (oldString === "") {
           let exists = true;
+          let contentOld = "";
           try {
             const value = await stat(filePath);
             if (value.isFile()) {
-              const content = await readFile(filePath, "utf8");
-              if (content.trim() !== "") {
+              contentOld = await readFile(filePath, "utf8");
+              if (contentOld.trim() !== "") {
                 throw new Error("Cannot create new file - file already exists.");
               }
             }
@@ -396,6 +372,14 @@ export function registerFileTools(
               throw error;
             }
           }
+          // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+          await guardWriteAccess(ctx, {
+            toolName: "Edit",
+            absolutePath: filePath,
+            mutation: { contentOld, contentNew: newString },
+            policy,
+            signal,
+          });
           if (!exists) {
             await mkdir(dirname(filePath), { recursive: true });
           }
@@ -458,6 +442,13 @@ export function registerFileTools(
         signal?.throwIfAborted();
         const original = content.toString("utf8");
         const restored = applyExactEdit(original, oldString, newString, replaceAll);
+        await guardWriteAccess(ctx, {
+          toolName: "Edit",
+          absolutePath: filePath,
+          mutation: { contentOld: original, contentNew: restored },
+          policy,
+          signal,
+        });
         await writeFile(filePath, restored, "utf8");
         const snapshot = snapshotOf(restored);
         state.reads.set(key, snapshot);
@@ -532,13 +523,6 @@ export function registerFileTools(
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
       const filePath = resolveToolFilePath(params.file_path, ctx.cwd);
-      await guardWriteAccess(ctx, {
-        toolName: "Write",
-        absolutePath: filePath,
-        change: { kind: "write", newText: params.content },
-        policy,
-        signal,
-      });
       const [message, details, diagnostics] = await withFileMutationQueue<
         [string, FileToolDetails, DiagnosticReport]
       >(filePath, async () => {
@@ -558,6 +542,14 @@ export function registerFileTools(
           }
         }
         signal?.throwIfAborted();
+        // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+        await guardWriteAccess(ctx, {
+          toolName: "Write",
+          absolutePath: filePath,
+          mutation: { contentOld: original ?? "", contentNew: params.content },
+          policy,
+          signal,
+        });
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, params.content, "utf8");
         const snapshot = snapshotOf(params.content);

package/src/lib/lsp/rename-tool.ts

@@ -194,18 +194,14 @@ export function registerLspRenameTool(
       if (applied.length === 0) {
         throw new Error("LSP rename returned no edits");
       }
+      // 先逐个文件审批、再逐个写盘：用户在第二个文件上拒绝时不该留下半个 rename。
+      // 变更前后内容已由 expandWorkspaceEdit 在内存里算好，审批框展示的就是要写入的
+      // 内容；对话框停留期间的外部改动由写保护的指纹校验兜住。
       for (const fileEdit of applied) {
         await guardWriteAccess(ctx, {
           toolName: "lsp-rename",
           absolutePath: fileEdit.path,
-          change: {
-            kind: "edit",
-            oldText: fileEdit.oldText,
-            newText: fileEdit.newText,
-            // LSP 编辑已在内存里展开成整文件的 old/new，落盘是覆盖写：预览直接用
-            // 这一对文本，不必再把整份旧内容交给匹配引擎去找
-            apply: () => ({ contentOld: fileEdit.oldText, contentNew: fileEdit.newText }),
-          },
+          mutation: { contentOld: fileEdit.oldText, contentNew: fileEdit.newText },
           policy: options.policy,
           signal,
         });

package/src/lib/write-guard.ts

@@ -11,17 +11,17 @@
  * - `/bwrap-deny-request` (non-sandbox request policy) refuses outside writes
  *   outright, with the same error as the user picking "Block".
  *
- * Callers have already parsed their tool arguments, so the guard only takes the
- * resolved pieces: the raw target path and the pending change. An edit carries
- * the caller's own matching implementation, so the previewed diff comes from the
- * same semantics that will write the file.
+ * Callers have already parsed their tool arguments and computed the result, so the
+ * guard takes the resolved pieces: the raw target path and the mutation (the file's
+ * content before and after). The preview is rendered from those two strings, so the
+ * approved diff is the change that gets written.
  */
 
-import { readFile } from "node:fs/promises";
 import { basename, isAbsolute, relative, sep } from "node:path";
 
 import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 
+import { digestIfExists, snapshotOf } from "./file-reads.js";
 import { fenceCodeBlock } from "./markdown.js";
 import type { RequestPolicy } from "./request-policy.js";
 
@@ -59,80 +59,52 @@ function wrapDiff(patch: string): string {
 }
 
 /**
- * 审批预览用的应用函数：把这次改动套到文件内容上，返回 diff 用的前后文本。
- * 必须是该工具落盘时使用的同一套匹配实现——否则对话框展示的 diff 与实际写入
- * 可能不一致。
+ * 待审批的写入：内容由调用方先读盘并算好，批准后按 `contentNew` 落盘。
+ *
+ * 两份内容都是文件原始内容（保留 BOM 与行尾），不是匹配引擎的中间产物——这样
+ * 预览就是磁盘前后的真实对照，批准后的指纹校验也能与磁盘字节逐字节对上。
  */
-export type PendingChangeApply = (fileContent: string) => {
+export interface FileMutation {
+  /** 变更前的完整文件内容（文件不存在时为 ""）。 */
   readonly contentOld: string;
+  /** 变更后的完整内容——即批准后写进磁盘的字节。 */
   readonly contentNew: string;
-};
-
-/** 整文件写入：预览是完整的增删 patch，不需要匹配实现。 */
-export interface FileWriteChange {
-  readonly kind: "write";
-  readonly newText: string;
 }
 
-/**
- * 替换：`apply` 是调用方自己的匹配实现（精确匹配、模糊匹配，或已展开好的整文件
- * 编辑）。匹配不上时抛错即可，写保护会退化为参数 diff。
- */
-export interface FileEditChange {
-  readonly kind: "edit";
-  readonly oldText: string;
-  readonly newText: string;
-  readonly apply: PendingChangeApply;
-}
-
-/** The pending file change, described by the caller from already-parsed args. */
-export type PendingChange = FileWriteChange | FileEditChange;
-
 /** 预览统一按 LF 渲染：CRLF 文件的 diff 每行都带 \r，在对话框里显示成乱码。 */
 function normalizeToLF(text: string): string {
   return text.replaceAll("\r\n", "\n");
 }
 
-/** 参数 diff：调用方的匹配实现报告不出结果时的兜底形式。 */
-function parameterDiff(oldText: string, newText: string): string {
-  const removed = oldText.split("\n").map((line) => `-${line}`);
-  const added = newText.split("\n").map((line) => `+${line}`);
-  return [...removed, ...added].join("\n");
+/** 待审批写入的 diff 代码块：由将落盘的内容直接算出，不做第二次匹配。 */
+export function renderMutationPreview(resolvedPath: string, mutation: FileMutation): string {
+  return wrapDiff(
+    generateUnifiedPatch(
+      basename(resolvedPath),
+      normalizeToLF(mutation.contentOld),
+      normalizeToLF(mutation.contentNew),
+      2,
+    ),
+  );
 }
 
+/** 空内容的指纹：文件不存在与空文件在审批视角下等价。 */
+const EMPTY_DIGEST = snapshotOf("").digest;
+
 /**
- * Build a `diff` code block preview of the pending change.
- * Returns undefined when the diff cannot be computed.
+ * 批准后重新取一次磁盘指纹：用户停留在对话框上的这段时间文件可能被外部改动，
+ * 此时按审批所用的旧内容算出的 `contentNew` 会覆盖别人的改动。
  */
-export async function buildDiffPreview(
-  resolvedPath: string,
-  change: PendingChange,
-): Promise<string | undefined> {
-  let fileContent = "";
-  try {
-    fileContent = await readFile(resolvedPath, "utf8");
-  } catch {
-    // Unreadable or missing file: treat as empty so writes show as full additions.
-  }
-
-  if (change.kind === "write") {
-    // Whole-file write: show the full addition/replacement patch.
-    return wrapDiff(generateUnifiedPatch(basename(resolvedPath), fileContent, change.newText, 2));
+async function requireApprovedContentStillCurrent(opts: WriteGuardOptions): Promise<void> {
+  const { mutation } = opts;
+  if (mutation === undefined) {
+    return;
   }
-
-  // 定位由调用方的匹配实现负责（与其落盘同语义）；匹配不上时退回参数 diff。
-  try {
-    const { contentOld, contentNew } = change.apply(fileContent);
-    return wrapDiff(
-      generateUnifiedPatch(
-        basename(resolvedPath),
-        normalizeToLF(contentOld),
-        normalizeToLF(contentNew),
-        2,
-      ),
+  const current = (await digestIfExists(opts.absolutePath)) ?? EMPTY_DIGEST;
+  if (current !== snapshotOf(mutation.contentOld).digest) {
+    throw new Error(
+      "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
     );
-  } catch {
-    return wrapDiff(parameterDiff(change.oldText, change.newText));
   }
 }
 
@@ -159,9 +131,10 @@ export interface WriteGuardOptions {
   /** The resolved absolute target path (caller has already parsed its args). */
   absolutePath: string;
   /**
-   * 待审批的变更内容；缺省时审批对话框不展示 diff 预览，仅按路径审批。
+   * 待审批的写入（变更前后的完整内容）；缺省时审批对话框不展示 diff 预览，
+   * 仅按路径审批（流式落盘的工具用不上它）。
    */
-  change?: PendingChange;
+  mutation?: FileMutation;
   /** 调用方所在扩展入口持有的非沙盒请求策略（跨入口一致时绑同一个 pi.events）。 */
   policy: RequestPolicy;
   /** 工具调用的中止信号：透传给审批对话框，工具被取消时对话框一起关掉。 */
@@ -204,7 +177,8 @@ export async function guardWriteAccess(
   }
 
   for (;;) {
-    const diffPreview = opts.change ? await buildDiffPreview(absolutePath, opts.change) : undefined;
+    const diffPreview =
+      opts.mutation === undefined ? undefined : renderMutationPreview(absolutePath, opts.mutation);
     const title =
       `Model requests write access outside workspace:\n\n` +
       `  Tool:  ${opts.toolName}\n` +
@@ -220,6 +194,7 @@ export async function guardWriteAccess(
       throw new Error(`user deny ${opts.toolName}: cancelled`);
     }
     if (choice === "Approve once") {
+      await requireApprovedContentStillCurrent(opts);
       return;
     }
     if (choice === "Block") {

package/src/opencode/files.ts

@@ -632,27 +632,6 @@ function registerEditTool(
 
       const absolutePath = isAbsolute(filePath) ? filePath : resolvePath(ctx.cwd, filePath);
 
-      await guardWriteAccess(ctx, {
-        toolName: "edit",
-        absolutePath,
-        // 审批预览必须与落盘同语义：注入本工具自己的模糊匹配引擎（空 oldString
-        // 是创建新文件，按整文件写入预览）
-        change:
-          oldString === ""
-            ? { kind: "write", newText: newString }
-            : {
-                kind: "edit",
-                oldText: oldString,
-                newText: newString,
-                apply: (content) => {
-                  const applied = applyEdit(content, oldString, newString, replaceAll);
-                  return { contentOld: applied.contentOld, contentNew: applied.contentNew };
-                },
-              },
-        policy,
-        signal,
-      });
-
       const [message, details, diagnostics] = await withFileMutationQueue(
         absolutePath,
         async () => {
@@ -677,6 +656,14 @@ function registerEditTool(
               );
             }
             // opencode: writeWithDirs 自动创建父目录；newString 开头的 BOM 原样保留
+            // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+            await guardWriteAccess(ctx, {
+              toolName: "edit",
+              absolutePath,
+              mutation: { contentOld: "", contentNew: newString },
+              policy,
+              signal,
+            });
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
@@ -720,6 +707,13 @@ function registerEditTool(
 
           const applied = applyEdit(rawContent, oldString, newString, replaceAll);
           signal?.throwIfAborted();
+          await guardWriteAccess(ctx, {
+            toolName: "edit",
+            absolutePath,
+            mutation: { contentOld: rawContent, contentNew: applied.finalContent },
+            policy,
+            signal,
+          });
           await writeFile(absolutePath, applied.finalContent, "utf8");
           const snapshot = snapshotOf(applied.finalContent);
           state.reads.set(key, snapshot);
@@ -810,13 +804,6 @@ function registerWriteTool(
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const { filePath: rawPath, content } = params;
       const absolutePath = resolvePath(ctx.cwd, rawPath);
-      await guardWriteAccess(ctx, {
-        toolName: "write",
-        absolutePath,
-        change: { kind: "write", newText: content },
-        policy,
-        signal,
-      });
       const dir = dirname(absolutePath);
 
       const [message, details, diagnostics] = await withFileMutationQueue(
@@ -832,29 +819,31 @@ function registerWriteTool(
           }
 
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
-          // 否则用新内容自带的 BOM
+          // 否则用新内容自带的 BOM。旧内容整读一次，既是 BOM 的来源，也是审批预览
+          // 的「变更前内容」。
           let existing: Buffer | undefined;
           try {
-            const fh = await open(absolutePath, "r");
-            try {
-              existing = Buffer.alloc(3);
-              const { bytesRead } = await fh.read(existing, 0, 3, 0);
-              if (bytesRead < 3) {
-                existing = undefined;
-              }
-            } finally {
-              await fh.close();
-            }
+            existing = await readFile(absolutePath);
           } catch {
-            // 文件不存在：无旧 BOM
+            // 文件不存在：无旧文件
           }
           const { bom: desiredBom, text: nextText } = resolveBom(existing, content);
+          const finalContent = desiredBom + nextText;
+
+          // 审批在算完内容之后、产生副作用（建目录 / 写盘）之前：预览就是将要写入的内容
+          await guardWriteAccess(ctx, {
+            toolName: "write",
+            absolutePath,
+            mutation: { contentOld: existing?.toString("utf8") ?? "", contentNew: finalContent },
+            policy,
+            signal,
+          });
 
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
-          await writeFile(absolutePath, desiredBom + nextText, "utf8");
+          await writeFile(absolutePath, finalContent, "utf8");
           // 写后记账（key 在写入前已算过）：紧接着的 edit 不该再要求重新 read
-          const snapshot = snapshotOf(desiredBom + nextText);
+          const snapshot = snapshotOf(finalContent);
           state.reads.set(key, snapshot);
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
             signal,