@trim21/personal-pi-extensions 0.1.643 → 0.1.644

package/package.json

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

package/src/claude-code/files.ts

@@ -17,7 +17,8 @@ import {
   createReadsState,
   type FileSnapshot,
   type ReadsState,
-  readStateKey,
+  recordRead,
+  recordReads,
   requireCurrentRead,
   restoreReads,
   snapshotOf,
@@ -247,13 +248,11 @@ export function registerFileTools(
           { type: "text", text: `Read image file [${imageMime}]` },
           { type: "image", data, mimeType: imageMime },
         ];
-        const snapshot = snapshotOf(image, false);
-        const key = await readStateKey(filePath);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, filePath, snapshotOf(image, false));
         return {
           content,
           details: {
-            reads: { [key]: snapshot },
+            reads,
             pendant: {
               subtitle: formatSubtitlePath(ctx.cwd, filePath),
               title: "Read",
@@ -264,7 +263,6 @@ export function registerFileTools(
 
       const offset = params.offset ?? 1;
       const limit = params.limit;
-      const key = await readStateKey(filePath);
       const buffer = await readFile(filePath);
 
       if (isBinary(buffer.subarray(0, SAMPLE_BYTES))) {
@@ -285,8 +283,7 @@ export function registerFileTools(
           `File content (${estimatedTokens} tokens) exceeds maximum allowed tokens (${MAX_READ_TOKENS}). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file.`,
         );
       }
-      const snapshot = snapshotOf(buffer);
-      state.reads.set(key, snapshot);
+      const reads = await recordRead(state, filePath, snapshotOf(buffer));
       // 与 Edit / Write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
         notify: (message, level) => ctx.ui.notify(message, level),
@@ -300,7 +297,7 @@ export function registerFileTools(
           },
         ],
         details: {
-          reads: { [key]: snapshot },
+          reads,
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -384,9 +381,7 @@ export function registerFileTools(
             await mkdir(dirname(filePath), { recursive: true });
           }
           await writeFile(filePath, newString, "utf8");
-          const snapshot = snapshotOf(newString);
-          const key = await readStateKey(filePath);
-          state.reads.set(key, snapshot);
+          const reads = await recordRead(state, filePath, snapshotOf(newString));
           const diff = generateDiffString("", convertLeadingTabsToSpaces(newString));
           signal?.throwIfAborted();
           const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
@@ -399,7 +394,7 @@ export function registerFileTools(
               diff: diff.diff,
               patch: generateUnifiedPatch(filePath, "", convertLeadingTabsToSpaces(newString)),
               firstChangedLine: diff.firstChangedLine,
-              reads: { [key]: snapshot },
+              reads,
             },
             diagnostics,
           ];
@@ -436,8 +431,7 @@ export function registerFileTools(
             "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
           );
         }
-        const key = await readStateKey(filePath);
-        requireCurrentRead(state, key, filePath, content);
+        await requireCurrentRead(state, filePath, content);
         await access(filePath, constants.R_OK | constants.W_OK);
         signal?.throwIfAborted();
         const original = content.toString("utf8");
@@ -450,8 +444,7 @@ export function registerFileTools(
           signal,
         });
         await writeFile(filePath, restored, "utf8");
-        const snapshot = snapshotOf(restored);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, filePath, snapshotOf(restored));
         // patch/diff 仅供显示：前导 tab 转空格，避免 UI 渲染错位（对齐 Claude Code）
         const diff = generateDiffString(
           convertLeadingTabsToSpaces(original),
@@ -475,7 +468,7 @@ export function registerFileTools(
               convertLeadingTabsToSpaces(restored),
             ),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [key]: snapshot },
+            reads,
           },
           diagnostics,
         ];
@@ -527,13 +520,11 @@ export function registerFileTools(
         [string, FileToolDetails, DiagnosticReport]
       >(filePath, async () => {
         let original: string | undefined;
-        let key: string | undefined;
         try {
           const value = await stat(filePath);
           if (value.isFile()) {
             const content = await readFile(filePath);
-            key = await readStateKey(filePath);
-            requireCurrentRead(state, key, filePath, content);
+            await requireCurrentRead(state, filePath, content);
             original = content.toString("utf8");
           }
         } catch (error) {
@@ -552,10 +543,7 @@ export function registerFileTools(
         });
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, params.content, "utf8");
-        const snapshot = snapshotOf(params.content);
-        // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
-        const resolvedKey = key ?? (await readStateKey(filePath));
-        state.reads.set(resolvedKey, snapshot);
+        const reads = await recordRead(state, filePath, snapshotOf(params.content));
         const diff = generateDiffString(original ?? "", params.content);
         const text =
           original === undefined
@@ -572,7 +560,7 @@ export function registerFileTools(
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original ?? "", params.content),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [resolvedKey]: snapshot },
+            reads,
           },
           diagnostics,
         ];
@@ -639,16 +627,14 @@ export default function claudeCodeFileTools(
       onEnabled: (pi, service) => {
         registerLspRenameTool(pi, service, {
           policy,
-          recordReads: async (applied) => {
-            const reads: Record<string, FileSnapshot> = {};
-            for (const fileEdit of applied) {
-              const key = await readStateKey(fileEdit.path);
-              const snapshot = snapshotOf(fileEdit.newText);
-              state.reads.set(key, snapshot);
-              reads[key] = snapshot;
-            }
-            return reads;
-          },
+          recordReads: (applied) =>
+            recordReads(
+              state,
+              applied.map((fileEdit) => ({
+                path: fileEdit.path,
+                snapshot: snapshotOf(fileEdit.newText),
+              })),
+            ),
         });
         registerLspInspectTools(pi, service);
       },

package/src/lib/file-reads.ts

@@ -6,11 +6,15 @@
  * - 工具名集合：claude-code 是大写 Read/Edit/Write，opencode 是小写；
  * - 指纹来源：claude-code 手里已有内容，直接 snapshotOf(content)；opencode 的
  *   read 是流式分页读取，整文件指纹用 fileDigest(path)。
+ *
+ * 记账 key 的解析与读写由本模块独占（readStateKey / recordRead / require*），
+ * 调用点只给路径与快照，不自己拼 details 里的 map。
  */
 
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
@@ -72,32 +76,73 @@ export async function digestIfExists(filePath: string): Promise<string | undefin
 }
 
 /**
- * 记账 key：解析 symlink 后的真实路径。文件尚不存在（Write 新建 / Edit 空
- * old_string 创建）时 realpath 抛 ENOENT，回退到调用方给出的路径。
+ * 记账 key：解析 symlink 后的真实路径。文件尚未落盘（Write 新建 / Edit 空
+ * old_string 创建）时向上找到最深的已存在祖先、解析它再把剩余路径段拼回去——
+ * 结果与文件落盘后 realpath(filePath) 相同，因此调用点不必关心算 key 的时机
+ * （写入路径尤其容易在创建分支上算早）。
  */
 export async function readStateKey(filePath: string): Promise<string> {
-  try {
-    return await realpath(filePath);
-  } catch (error) {
-    if (isMissingPath(error)) {
+  const pending: string[] = [];
+  let current = filePath;
+  for (;;) {
+    try {
+      return join(await realpath(current), ...pending.toReversed());
+    } catch (error) {
+      if (!isMissingPath(error)) {
+        throw error;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      // 一路到文件系统根仍不存在：无法解析，回退调用方给出的路径
       return filePath;
     }
-    throw error;
+    pending.push(basename(current));
+    current = parent;
   }
 }
 
+/**
+ * 记账「这些文件的内容即各自的 snapshot」：解析 key 写入 state，返回可直接放进
+ * 工具 details 的 reads 片段。
+ *
+ * 这一侧是对象而不是 Map：details 是 JSON（宿主按 `JsonValue` 写进 session
+ * JSONL），Map 序列化过去会变成 `{}`，记账就丢了；读取方向与之相对（
+ * `deserializeReads` 从同一个对象形状还原成 Map）。
+ */
+export async function recordReads(
+  state: ReadsState,
+  entries: readonly { path: string; snapshot: FileSnapshot }[],
+): Promise<Record<string, FileSnapshot>> {
+  const reads: Record<string, FileSnapshot> = {};
+  for (const entry of entries) {
+    const key = await readStateKey(entry.path);
+    state.reads.set(key, entry.snapshot);
+    reads[key] = entry.snapshot;
+  }
+  return reads;
+}
+
+/** 单文件记账：`recordReads` 的单项形式。 */
+export async function recordRead(
+  state: ReadsState,
+  filePath: string,
+  snapshot: FileSnapshot,
+): Promise<Record<string, FileSnapshot>> {
+  return await recordReads(state, [{ path: filePath, snapshot }]);
+}
+
 function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
   return left.digest === right.digest;
 }
 
 /** 校验「已读且未变」：未读过、非文本、指纹不符都拒绝写入。 */
-export function requireCurrentRead(
+export async function requireCurrentRead(
   state: ReadsState,
-  key: string,
   filePath: string,
   currentContent: Uint8Array | string,
-): void {
-  const readSnapshot = state.reads.get(key);
+): Promise<void> {
+  const readSnapshot = state.reads.get(await readStateKey(filePath));
   if (!readSnapshot) {
     throw new Error("File has not been read yet. Read it first before writing to it.");
   }
@@ -113,21 +158,17 @@ export function requireCurrentRead(
 
 /**
  * 过期校验：该文件已有读取记录时，要求磁盘上的当前指纹与记录一致，否则拒绝
- * 写入；从未读过（没有记录）时直接放行。
+ * 写入；从未读过（没有记录）时直接放行，且不做整文件指纹计算。
  *
  * opencode 的 write 用这个：没读过的文件允许直接写，读过之后再被外部改动就必须
- * 重新 read。`currentDigest` 为 undefined（文件已不存在）同样算过期。
+ * 重新 read。文件已不存在（指纹 undefined）同样算过期。
  */
-export function requireUnchangedRead(
-  state: ReadsState,
-  key: string,
-  currentDigest: string | undefined,
-): void {
-  const readSnapshot = state.reads.get(key);
+export async function requireUnchangedRead(state: ReadsState, filePath: string): Promise<void> {
+  const readSnapshot = state.reads.get(await readStateKey(filePath));
   if (!readSnapshot) {
     return;
   }
-  if (currentDigest === undefined || readSnapshot.digest !== currentDigest) {
+  if (readSnapshot.digest !== (await digestIfExists(filePath))) {
     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.",
     );

package/src/opencode/files.ts

@@ -38,11 +38,11 @@ import { Type } from "typebox";
 
 import {
   createReadsState,
-  digestIfExists,
   fileDigest,
   type FileSnapshot,
   type ReadsState,
-  readStateKey,
+  recordRead,
+  recordReads,
   requireCurrentRead,
   requireUnchangedRead,
   restoreReads,
@@ -500,13 +500,11 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
           { type: "text", text: "Image read successfully" },
           { type: "image", data: base64, mimeType },
         ];
-        const key = await readStateKey(absolutePath);
-        const snapshot = snapshotOf(buffer, false);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, absolutePath, snapshotOf(buffer, false));
         return {
           content,
           details: {
-            reads: { [key]: snapshot },
+            reads,
             pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) },
           },
         };
@@ -521,7 +519,6 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
 
       // 记账指纹先于分页读取：文件若在读取期间被改动，指纹对应的是改动前的
       // 内容，后续 edit 会要求重新 read（失败方向安全）。
-      const key = await readStateKey(absolutePath);
       const snapshot: FileSnapshot = { digest: await fileDigest(absolutePath), textEditable: true };
 
       const effectiveOffset = offset || 1;
@@ -555,7 +552,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
         outputText = `${header}${numbered}\n\n(End of file - total ${page.count} lines)${footer}`;
       }
 
-      state.reads.set(key, snapshot);
+      const reads = await recordRead(state, absolutePath, snapshot);
 
       // opencode: 与 edit / write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
@@ -572,7 +569,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
         content,
         details: {
           ...details,
-          reads: { [key]: snapshot },
+          reads,
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -667,16 +664,14 @@ function registerEditTool(
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
-            // 新建文件无需先 read（无处可读），写后记账；realpath 要等文件落盘
-            const key = await readStateKey(absolutePath);
-            const snapshot = snapshotOf(newString);
-            state.reads.set(key, snapshot);
+            // 新建文件无需先 read（无处可读），写后记账
+            const reads = await recordRead(state, absolutePath, snapshotOf(newString));
             const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
               signal,
             });
             return [
               "Edit applied successfully.",
-              { diff: "", patch: "", firstChangedLine: 0, reads: { [key]: snapshot } },
+              { diff: "", patch: "", firstChangedLine: 0, reads },
               diagnostics,
             ] as const;
           }
@@ -702,8 +697,7 @@ function registerEditTool(
 
           // 指纹校验必须发生在写入之前：未 read 或外部已改动都拒绝编辑
           const rawContent = await readFile(absolutePath, "utf8");
-          const key = await readStateKey(absolutePath);
-          requireCurrentRead(state, key, absolutePath, rawContent);
+          await requireCurrentRead(state, absolutePath, rawContent);
 
           const applied = applyEdit(rawContent, oldString, newString, replaceAll);
           signal?.throwIfAborted();
@@ -715,8 +709,7 @@ function registerEditTool(
             signal,
           });
           await writeFile(absolutePath, applied.finalContent, "utf8");
-          const snapshot = snapshotOf(applied.finalContent);
-          state.reads.set(key, snapshot);
+          const reads = await recordRead(state, absolutePath, snapshotOf(applied.finalContent));
 
           const diffOld = normalizeToLF(applied.contentOld);
           const diffNew = normalizeToLF(applied.contentNew);
@@ -731,7 +724,7 @@ function registerEditTool(
               diff: diffResult.diff,
               patch,
               firstChangedLine: diffResult.firstChangedLine,
-              reads: { [key]: snapshot },
+              reads,
             },
             diagnostics,
           ] as const;
@@ -811,12 +804,9 @@ function registerWriteTool(
         async () => {
           signal?.throwIfAborted();
 
-          const key = await readStateKey(absolutePath);
           // write 不要求先读过；但若已有读取记录，磁盘内容必须仍是读取时的样子，
           // 否则先重新 read（外部改动过的文件不让盲写覆盖）
-          if (state.reads.has(key)) {
-            requireUnchangedRead(state, key, await digestIfExists(absolutePath));
-          }
+          await requireUnchangedRead(state, absolutePath);
 
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
           // 否则用新内容自带的 BOM。旧内容整读一次，既是 BOM 的来源，也是审批预览
@@ -842,14 +832,13 @@ function registerWriteTool(
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
           await writeFile(absolutePath, finalContent, "utf8");
-          // 写后记账（key 在写入前已算过）：紧接着的 edit 不该再要求重新 read
-          const snapshot = snapshotOf(finalContent);
-          state.reads.set(key, snapshot);
+          // 写后记账：紧接着的 edit 不该再要求重新 read
+          const reads = await recordRead(state, absolutePath, snapshotOf(finalContent));
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
             signal,
           });
 
-          return ["Wrote file successfully.", { reads: { [key]: snapshot } }, diagnostics] as const;
+          return ["Wrote file successfully.", { reads }, diagnostics] as const;
         },
       );
 
@@ -906,16 +895,14 @@ export default function opencodeFileTools(
       onEnabled: (pi, service) => {
         registerLspRenameTool(pi, service, {
           policy,
-          recordReads: async (applied) => {
-            const reads: Record<string, FileSnapshot> = {};
-            for (const fileEdit of applied) {
-              const key = await readStateKey(fileEdit.path);
-              const snapshot = snapshotOf(fileEdit.newText);
-              state.reads.set(key, snapshot);
-              reads[key] = snapshot;
-            }
-            return reads;
-          },
+          recordReads: (applied) =>
+            recordReads(
+              state,
+              applied.map((fileEdit) => ({
+                path: fileEdit.path,
+                snapshot: snapshotOf(fileEdit.newText),
+              })),
+            ),
         });
         registerLspInspectTools(pi, service);
       },