@trim21/personal-pi-extensions 0.0.137 → 0.0.140

package/README.md

@@ -85,7 +85,7 @@ pi -e ./src/bwrap/index.ts
 阻止 `write` 和 `edit` 工具写入 workspace 外部的路径。读取工具（`read`、`ls`、`find`、`grep`）不受限制。
 
 - workspace 内或 `/tmp` 下的路径自动放行
-- 外部路径需通过确认对话框由用户审批
+- 外部路径需通过确认对话框由用户审批,对话框内以 ```diff 代码块展示将要发生的变更预览(与 opencode-edit 共享匹配引擎,能定位时显示带行号的真实 patch,否则退化为参数 diff)
 - 无需配置
 
 ### 使用
@@ -98,7 +98,7 @@ pi -e ./src/workspace-guard.ts
 
 ## opencode-edit
 
-替换内置 `edit` 工具，使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数直接复制自 opencode，行为与原版完全一致。
+替换内置 `edit` 工具，使用 [opencode](https://github.com/anomalyco/opencode) 的 schema 和模糊匹配引擎。核心 replacer 和 `replace()` 函数直接复制自 opencode，行为与原版完全一致。匹配引擎位于 `src/opencode-edit-engine.ts`，与 workspace-guard 的审批弹窗 diff 预览共享。
 
 支持的匹配策略：
 

package/package.json

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

package/src/gh-readonly.ts

@@ -171,60 +171,6 @@ export class GhError extends Error {
   }
 }
 
-/** How long `read-github-pr-status` waits for pending checks to resolve. */
-const POLL_INTERVAL_MS = 30_000;
-const POLL_TIMEOUT_MS = 30 * 60_000;
-
-/** Sleep for `ms`, resolving early if `signal` is aborted. */
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
-    if (signal?.aborted) {
-      resolve();
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      resolve();
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-/**
- * Poll a `gh pr checks` query until it reaches a final state.
- *
- * `gh pr checks` exit codes: 0 = all passed, 1 = some failed, 8 = some pending.
- * Pending (8) is polled every `intervalMs` until `timeoutMs` elapses, at which
- * point the current result is returned as-is. Any other code is returned
- * immediately; the caller decides whether it is an error.
- */
-export async function pollChecksResult<R extends { code: number; stdout: string }>(
-  query: () => Promise<R>,
-  opts: { signal?: AbortSignal; intervalMs?: number; timeoutMs?: number } = {},
-): Promise<R> {
-  const { signal, intervalMs = POLL_INTERVAL_MS, timeoutMs = POLL_TIMEOUT_MS } = opts;
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    if (signal?.aborted) {
-      throw new Error("read-github-pr-status aborted");
-    }
-    const result = await query();
-    if (result.code !== 8) {
-      // 0 = all passed, 1 = some failed, anything else is a real error
-      return result;
-    }
-    // Still pending — keep waiting unless the overall timeout expired
-    if (Date.now() >= deadline) {
-      return result;
-    }
-    await sleep(intervalMs, signal);
-  }
-}
-
 /** Run `gh` and return stdout. On non-zero exit, throws a `GhError` carrying the toolcall input and raw command. */
 export async function ghExec(
   args: string[],
@@ -407,11 +353,20 @@ async function getJobLog(
       // Not cached, fetch from GitHub
     }
 
-    const log = await ghExec(["api", `/repos/${effectiveRepo}/actions/jobs/${jobId}/logs`], {
-      cwd,
-      signal,
-      input,
-    });
+    // `gh api` refuses to print responses that contain terminal escape
+    // sequences unless `--allow-escape-sequences` is passed. Job logs are a
+    // binary zip, so without this flag the download always fails with
+    // "the response contains terminal escape sequences; pass
+    // --allow-escape-sequences to output it anyway". The ANSI escapes are
+    // stripped later by `cleanStepOutput`, so there is no injection surface.
+    const log = await ghExec(
+      ["api", "--allow-escape-sequences", `/repos/${effectiveRepo}/actions/jobs/${jobId}/logs`],
+      {
+        cwd,
+        signal,
+        input,
+      },
+    );
 
     // Write to cache
     await mkdir(cacheDir, { recursive: true });
@@ -1026,7 +981,8 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "read-github-pr-status",
     label: "GitHub PR Status",
-    description: "Get status checks and CI results for a GitHub pull request.",
+    description:
+      "Get the current status checks and CI results for a GitHub pull request. Returns the current snapshot immediately; pending checks are reported as-is, not waited on. Use wait-github-pr-checks to block until checks finish.",
     promptSnippet: "Read GitHub PR status checks",
     parameters: Type.Object({
       number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
@@ -1036,16 +992,16 @@ export default function (pi: ExtensionAPI) {
       const { number, repo } = params;
       const args = ["pr", "checks", String(number), ...repoArgs(repo)];
 
-      // Pending is not an error — poll until checks fail or all pass.
-      const final = await pollChecksResult(() => runGh(args, { cwd: ctx.cwd, signal }), {
-        signal,
-      });
+      // `gh pr checks` exit codes: 0 = all passed, 1 = some failed, 8 = some
+      // pending. All three are valid states — return the current snapshot
+      // as-is without waiting. `wait-github-pr-checks` is the blocking variant.
+      const result = await runGh(args, { cwd: ctx.cwd, signal });
 
-      if (final.code !== 0 && final.code !== 1 && final.code !== 8) {
+      if (result.code !== 0 && result.code !== 1 && result.code !== 8) {
         // Anything else is a real error (cancelled, auth, network, ...)
-        throw new GhError(args, final, params);
+        throw new GhError(args, result, params);
       }
-      return toToolResult(final.stdout, params);
+      return toToolResult(result.stdout, params);
     },
   });
 

package/src/opencode-edit-engine.ts

@@ -0,0 +1,465 @@
+/**
+ * Opencode edit matching engine.
+ *
+ * The core replacers and replace() function are copied directly from
+ * https://github.com/anomalyco/opencode (packages/opencode/src/tool/edit.ts)
+ * and wrapped in a pi extension so the behaviour is identical to opencode.
+ *
+ * Shared by:
+ *   - opencode-edit.ts  — the edit tool implementation
+ *   - workspace-guard.ts — the diff preview shown in the approval dialog
+ */
+
+// ── BOM & line ending helpers ─────────────────────────────────────────────────
+
+export function stripBom(content: string): { bom: string; text: string } {
+  return content.startsWith("\uFEFF")
+    ? { bom: "\uFEFF", text: content.slice(1) }
+    : { bom: "", text: content };
+}
+
+export function detectLineEnding(content: string): "\r\n" | "\n" {
+  return content.includes("\r\n") ? "\r\n" : "\n";
+}
+
+export function normalizeToLF(text: string): string {
+  return text.replaceAll("\r\n", "\n");
+}
+
+export function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string {
+  return ending === "\r\n" ? text.replaceAll("\n", "\r\n") : text;
+}
+
+/** Strip BOM and normalize line endings to LF (what the replacers expect). */
+export function normalizeForEdit(content: string): string {
+  const { text } = stripBom(content);
+  return normalizeToLF(text);
+}
+
+// ── copied from opencode ──────────────────────────────────────────────────────
+
+function levenshtein(a: string, b: string): number {
+  if (a === "" || b === "") {
+    return Math.max(a.length, b.length);
+  }
+  const matrix = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  );
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost,
+      );
+    }
+  }
+  return matrix[a.length][b.length];
+}
+
+type Replacer = (content: string, find: string) => Generator<string, void, unknown>;
+
+const SINGLE_CANDIDATE_SIMILARITY_THRESHOLD = 0.65;
+const MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD = 0.65;
+
+const SimpleReplacer: Replacer = function* (_content, find) {
+  yield find;
+};
+
+const LineTrimmedReplacer: Replacer = function* (content, find) {
+  const originalLines = content.split("\n");
+  const searchLines = find.split("\n");
+  if (searchLines[searchLines.length - 1] === "") {
+    searchLines.pop();
+  }
+  for (let i = 0; i <= originalLines.length - searchLines.length; i++) {
+    let matches = true;
+    for (let j = 0; j < searchLines.length; j++) {
+      const originalTrimmed = originalLines[i + j].trim();
+      const searchTrimmed = searchLines[j].trim();
+      if (originalTrimmed !== searchTrimmed) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) {
+      let matchStartIndex = 0;
+      for (let k = 0; k < i; k++) {
+        matchStartIndex += originalLines[k].length + 1;
+      }
+      let matchEndIndex = matchStartIndex;
+      for (let k = 0; k < searchLines.length; k++) {
+        matchEndIndex += originalLines[i + k].length;
+        if (k < searchLines.length - 1) {
+          matchEndIndex += 1;
+        }
+      }
+      yield content.substring(matchStartIndex, matchEndIndex);
+    }
+  }
+};
+
+const BlockAnchorReplacer: Replacer = function* (content, find) {
+  const originalLines = content.split("\n");
+  const searchLines = find.split("\n");
+  if (searchLines.length < 3) {
+    return;
+  }
+  if (searchLines[searchLines.length - 1] === "") {
+    searchLines.pop();
+  }
+  const firstLineSearch = searchLines[0].trim();
+  const lastLineSearch = searchLines[searchLines.length - 1].trim();
+  const searchBlockSize = searchLines.length;
+  const maxLineDelta = Math.max(1, Math.floor(searchBlockSize * 0.25));
+
+  const candidates: Array<{ startLine: number; endLine: number }> = [];
+  for (let i = 0; i < originalLines.length; i++) {
+    if (originalLines[i].trim() !== firstLineSearch) {
+      continue;
+    }
+    for (let j = i + 2; j < originalLines.length; j++) {
+      if (originalLines[j].trim() === lastLineSearch) {
+        const actualBlockSize = j - i + 1;
+        if (Math.abs(actualBlockSize - searchBlockSize) <= maxLineDelta) {
+          candidates.push({ startLine: i, endLine: j });
+        }
+        break;
+      }
+    }
+  }
+  if (candidates.length === 0) {
+    return;
+  }
+
+  if (candidates.length === 1) {
+    const { startLine, endLine } = candidates[0];
+    const actualBlockSize = endLine - startLine + 1;
+    let similarity = 0;
+    const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2);
+    if (linesToCheck > 0) {
+      for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
+        const originalLine = originalLines[startLine + j].trim();
+        const searchLine = searchLines[j].trim();
+        const maxLen = Math.max(originalLine.length, searchLine.length);
+        if (maxLen === 0) {
+          continue;
+        }
+        const distance = levenshtein(originalLine, searchLine);
+        similarity += (1 - distance / maxLen) / linesToCheck;
+        if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
+          break;
+        }
+      }
+    } else {
+      similarity = 1.0;
+    }
+    if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
+      let matchStartIndex = 0;
+      for (let k = 0; k < startLine; k++) {
+        matchStartIndex += originalLines[k].length + 1;
+      }
+      let matchEndIndex = matchStartIndex;
+      for (let k = startLine; k <= endLine; k++) {
+        matchEndIndex += originalLines[k].length;
+        if (k < endLine) {
+          matchEndIndex += 1;
+        }
+      }
+      yield content.substring(matchStartIndex, matchEndIndex);
+    }
+    return;
+  }
+
+  let bestMatch: { startLine: number; endLine: number } | null = null;
+  let maxSimilarity = -1;
+  for (const candidate of candidates) {
+    const { startLine, endLine } = candidate;
+    const actualBlockSize = endLine - startLine + 1;
+    let similarity = 0;
+    const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2);
+    if (linesToCheck > 0) {
+      for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
+        const originalLine = originalLines[startLine + j].trim();
+        const searchLine = searchLines[j].trim();
+        const maxLen = Math.max(originalLine.length, searchLine.length);
+        if (maxLen === 0) {
+          continue;
+        }
+        const distance = levenshtein(originalLine, searchLine);
+        similarity += 1 - distance / maxLen;
+      }
+      similarity /= linesToCheck;
+    } else {
+      similarity = 1.0;
+    }
+    if (similarity > maxSimilarity) {
+      maxSimilarity = similarity;
+      bestMatch = candidate;
+    }
+  }
+  if (maxSimilarity >= MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD && bestMatch) {
+    const { startLine, endLine } = bestMatch;
+    let matchStartIndex = 0;
+    for (let k = 0; k < startLine; k++) {
+      matchStartIndex += originalLines[k].length + 1;
+    }
+    let matchEndIndex = matchStartIndex;
+    for (let k = startLine; k <= endLine; k++) {
+      matchEndIndex += originalLines[k].length;
+      if (k < endLine) {
+        matchEndIndex += 1;
+      }
+    }
+    yield content.substring(matchStartIndex, matchEndIndex);
+  }
+};
+
+const WhitespaceNormalizedReplacer: Replacer = function* (content, find) {
+  const normalizeWhitespace = (text: string) => text.replace(/\s+/g, " ").trim();
+  const normalizedFind = normalizeWhitespace(find);
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (normalizeWhitespace(line) === normalizedFind) {
+      yield line;
+    } else {
+      const normalizedLine = normalizeWhitespace(line);
+      if (normalizedLine.includes(normalizedFind)) {
+        const words = find.trim().split(/\s+/);
+        if (words.length > 0) {
+          const pattern = words
+            .map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("\\s+");
+          try {
+            const regex = new RegExp(pattern);
+            const match = line.match(regex);
+            if (match) {
+              yield match[0];
+            }
+          } catch {
+            // Invalid regex pattern, skip
+          }
+        }
+      }
+    }
+  }
+  const findLines = find.split("\n");
+  if (findLines.length > 1) {
+    for (let i = 0; i <= lines.length - findLines.length; i++) {
+      const block = lines.slice(i, i + findLines.length);
+      if (normalizeWhitespace(block.join("\n")) === normalizedFind) {
+        yield block.join("\n");
+      }
+    }
+  }
+};
+
+const IndentationFlexibleReplacer: Replacer = function* (content, find) {
+  const removeIndentation = (text: string) => {
+    const lines = text.split("\n");
+    const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+    if (nonEmptyLines.length === 0) return text;
+    const minIndent = Math.min(
+      ...nonEmptyLines.map((line) => {
+        const match = line.match(/^(\s*)/);
+        return match ? match[1].length : 0;
+      }),
+    );
+    return lines
+      .map((line) => (line.trim().length === 0 ? line : line.slice(minIndent)))
+      .join("\n");
+  };
+  const normalizedFind = removeIndentation(find);
+  const contentLines = content.split("\n");
+  const findLines = find.split("\n");
+  for (let i = 0; i <= contentLines.length - findLines.length; i++) {
+    const block = contentLines.slice(i, i + findLines.length).join("\n");
+    if (removeIndentation(block) === normalizedFind) {
+      yield block;
+    }
+  }
+};
+
+const EscapeNormalizedReplacer: Replacer = function* (content, find) {
+  const unescapeString = (str: string): string => {
+    return str.replace(/\\(n|t|r|'|"|`|\\|\n|\$)/g, (_match, capturedChar) => {
+      switch (capturedChar) {
+        case "n":
+          return "\n";
+        case "t":
+          return "\t";
+        case "r":
+          return "\r";
+        case "'":
+          return "'";
+        case '"':
+          return '"';
+        case "`":
+          return "`";
+        case "\\":
+          return "\\";
+        case "\n":
+          return "\n";
+        case "$":
+          return "$";
+        default:
+          return _match;
+      }
+    });
+  };
+  const unescapedFind = unescapeString(find);
+  if (content.includes(unescapedFind)) {
+    yield unescapedFind;
+  }
+  const lines = content.split("\n");
+  const findLines = unescapedFind.split("\n");
+  for (let i = 0; i <= lines.length - findLines.length; i++) {
+    const block = lines.slice(i, i + findLines.length).join("\n");
+    const unescapedBlock = unescapeString(block);
+    if (unescapedBlock === unescapedFind) {
+      yield block;
+    }
+  }
+};
+
+const MultiOccurrenceReplacer: Replacer = function* (content, find) {
+  let startIndex = 0;
+  while (true) {
+    const index = content.indexOf(find, startIndex);
+    if (index === -1) break;
+    yield find;
+    startIndex = index + find.length;
+  }
+};
+
+const TrimmedBoundaryReplacer: Replacer = function* (content, find) {
+  const trimmedFind = find.trim();
+  if (trimmedFind === find) {
+    return;
+  }
+  if (content.includes(trimmedFind)) {
+    yield trimmedFind;
+  }
+  const lines = content.split("\n");
+  const findLines = find.split("\n");
+  for (let i = 0; i <= lines.length - findLines.length; i++) {
+    const block = lines.slice(i, i + findLines.length).join("\n");
+    if (block.trim() === trimmedFind) {
+      yield block;
+    }
+  }
+};
+
+const ContextAwareReplacer: Replacer = function* (content, find) {
+  const findLines = find.split("\n");
+  if (findLines.length < 3) {
+    return;
+  }
+  if (findLines[findLines.length - 1] === "") {
+    findLines.pop();
+  }
+  const contentLines = content.split("\n");
+  const firstLine = findLines[0].trim();
+  const lastLine = findLines[findLines.length - 1].trim();
+  for (let i = 0; i < contentLines.length; i++) {
+    if (contentLines[i].trim() !== firstLine) continue;
+    for (let j = i + 2; j < contentLines.length; j++) {
+      if (contentLines[j].trim() === lastLine) {
+        const blockLines = contentLines.slice(i, j + 1);
+        const block = blockLines.join("\n");
+        if (blockLines.length === findLines.length) {
+          let matchingLines = 0;
+          let totalNonEmptyLines = 0;
+          for (let k = 1; k < blockLines.length - 1; k++) {
+            const blockLine = blockLines[k].trim();
+            const findLine = findLines[k].trim();
+            if (blockLine.length > 0 || findLine.length > 0) {
+              totalNonEmptyLines++;
+              if (blockLine === findLine) {
+                matchingLines++;
+              }
+            }
+          }
+          if (totalNonEmptyLines === 0 || matchingLines / totalNonEmptyLines >= 0.5) {
+            yield block;
+            break;
+          }
+        }
+        break;
+      }
+    }
+  }
+};
+
+function isDisproportionateMatch(search: string, oldString: string) {
+  const oldLines = oldString.split("\n").length;
+  const searchLines = search.split("\n").length;
+  if (searchLines >= Math.max(oldLines + 3, oldLines * 2)) return true;
+  if (oldLines === 1) return false;
+  return (
+    search.trim().length > Math.max(oldString.trim().length + 500, oldString.trim().length * 4)
+  );
+}
+
+/**
+ * Replace `oldString` with `newString` in `content`, using opencode's matching
+ * engine. Expects LF-normalized content (see `normalizeForEdit`).
+ * Throws when oldString cannot be matched or the match is ambiguous.
+ */
+export function replace(
+  content: string,
+  oldString: string,
+  newString: string,
+  replaceAll = false,
+): string {
+  if (oldString === newString) {
+    throw new Error("No changes to apply: oldString and newString are identical.");
+  }
+  if (oldString === "") {
+    throw new Error(
+      "oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement.",
+    );
+  }
+
+  let notFound = true;
+
+  for (const replacer of [
+    SimpleReplacer,
+    LineTrimmedReplacer,
+    BlockAnchorReplacer,
+    WhitespaceNormalizedReplacer,
+    IndentationFlexibleReplacer,
+    EscapeNormalizedReplacer,
+    TrimmedBoundaryReplacer,
+    ContextAwareReplacer,
+    MultiOccurrenceReplacer,
+  ]) {
+    for (const search of replacer(content, oldString)) {
+      const index = content.indexOf(search);
+      if (index === -1) continue;
+      notFound = false;
+      if (isDisproportionateMatch(search, oldString)) {
+        throw new Error(
+          "Refusing replacement because the matched span is much larger than oldString. Re-read the file and provide the full exact oldString for the intended replacement.",
+        );
+      }
+      if (replaceAll) {
+        return content.replaceAll(search, newString);
+      }
+      const lastIndex = content.lastIndexOf(search);
+      if (index !== lastIndex) continue;
+      return content.substring(0, index) + newString + content.substring(index + search.length);
+    }
+  }
+
+  if (notFound) {
+    throw new Error(
+      "Could not find oldString in the file. It must match exactly, including whitespace, indentation, and line endings.",
+    );
+  }
+  throw new Error(
+    "Found multiple matches for oldString. Provide more surrounding context to make the match unique.",
+  );
+}

package/src/opencode-edit.ts

@@ -2,9 +2,8 @@
  * Opencode Edit Extension — Replaces the built-in edit tool with opencode's
  * schema and matching engine.
  *
- * The core replacers and replace() function are copied directly from
- * https://github.com/anomalyco/opencode (packages/opencode/src/tool/edit.ts)
- * and wrapped in a pi extension so the behaviour is identical to opencode.
+ * The matching engine (replacers + replace()) lives in opencode-edit-engine.ts
+ * and is also used by workspace-guard for the diff preview.
  *
  * Usage:
  *   pi -e ./opencode-edit.ts
@@ -16,6 +15,13 @@ import {
   generateUnifiedPatch,
   withFileMutationQueue,
 } from "@earendil-works/pi-coding-agent";
+import {
+  detectLineEnding,
+  normalizeToLF,
+  replace,
+  restoreLineEndings,
+  stripBom,
+} from "./opencode-edit-engine.js";
 import { constants } from "fs";
 import { access, readFile, writeFile } from "fs/promises";
 import { isAbsolute, resolve } from "path";
@@ -34,449 +40,6 @@ const editSchema = Type.Object({
   ),
 });
 
-// ── BOM & line ending helpers ─────────────────────────────────────────────────
-
-function stripBom(content: string): { bom: string; text: string } {
-  return content.startsWith("\uFEFF")
-    ? { bom: "\uFEFF", text: content.slice(1) }
-    : { bom: "", text: content };
-}
-
-function detectLineEnding(content: string): "\r\n" | "\n" {
-  return content.includes("\r\n") ? "\r\n" : "\n";
-}
-
-function normalizeToLF(text: string): string {
-  return text.replaceAll("\r\n", "\n");
-}
-
-function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string {
-  return ending === "\r\n" ? text.replaceAll("\n", "\r\n") : text;
-}
-
-// ── copied from opencode ──────────────────────────────────────────────────────
-
-function levenshtein(a: string, b: string): number {
-  if (a === "" || b === "") {
-    return Math.max(a.length, b.length);
-  }
-  const matrix = Array.from({ length: a.length + 1 }, (_, i) =>
-    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
-  );
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      matrix[i][j] = Math.min(
-        matrix[i - 1][j] + 1,
-        matrix[i][j - 1] + 1,
-        matrix[i - 1][j - 1] + cost,
-      );
-    }
-  }
-  return matrix[a.length][b.length];
-}
-
-type Replacer = (content: string, find: string) => Generator<string, void, unknown>;
-
-const SINGLE_CANDIDATE_SIMILARITY_THRESHOLD = 0.65;
-const MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD = 0.65;
-
-const SimpleReplacer: Replacer = function* (_content, find) {
-  yield find;
-};
-
-const LineTrimmedReplacer: Replacer = function* (content, find) {
-  const originalLines = content.split("\n");
-  const searchLines = find.split("\n");
-  if (searchLines[searchLines.length - 1] === "") {
-    searchLines.pop();
-  }
-  for (let i = 0; i <= originalLines.length - searchLines.length; i++) {
-    let matches = true;
-    for (let j = 0; j < searchLines.length; j++) {
-      const originalTrimmed = originalLines[i + j].trim();
-      const searchTrimmed = searchLines[j].trim();
-      if (originalTrimmed !== searchTrimmed) {
-        matches = false;
-        break;
-      }
-    }
-    if (matches) {
-      let matchStartIndex = 0;
-      for (let k = 0; k < i; k++) {
-        matchStartIndex += originalLines[k].length + 1;
-      }
-      let matchEndIndex = matchStartIndex;
-      for (let k = 0; k < searchLines.length; k++) {
-        matchEndIndex += originalLines[i + k].length;
-        if (k < searchLines.length - 1) {
-          matchEndIndex += 1;
-        }
-      }
-      yield content.substring(matchStartIndex, matchEndIndex);
-    }
-  }
-};
-
-const BlockAnchorReplacer: Replacer = function* (content, find) {
-  const originalLines = content.split("\n");
-  const searchLines = find.split("\n");
-  if (searchLines.length < 3) {
-    return;
-  }
-  if (searchLines[searchLines.length - 1] === "") {
-    searchLines.pop();
-  }
-  const firstLineSearch = searchLines[0].trim();
-  const lastLineSearch = searchLines[searchLines.length - 1].trim();
-  const searchBlockSize = searchLines.length;
-  const maxLineDelta = Math.max(1, Math.floor(searchBlockSize * 0.25));
-
-  const candidates: Array<{ startLine: number; endLine: number }> = [];
-  for (let i = 0; i < originalLines.length; i++) {
-    if (originalLines[i].trim() !== firstLineSearch) {
-      continue;
-    }
-    for (let j = i + 2; j < originalLines.length; j++) {
-      if (originalLines[j].trim() === lastLineSearch) {
-        const actualBlockSize = j - i + 1;
-        if (Math.abs(actualBlockSize - searchBlockSize) <= maxLineDelta) {
-          candidates.push({ startLine: i, endLine: j });
-        }
-        break;
-      }
-    }
-  }
-  if (candidates.length === 0) {
-    return;
-  }
-
-  if (candidates.length === 1) {
-    const { startLine, endLine } = candidates[0];
-    const actualBlockSize = endLine - startLine + 1;
-    let similarity = 0;
-    const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2);
-    if (linesToCheck > 0) {
-      for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
-        const originalLine = originalLines[startLine + j].trim();
-        const searchLine = searchLines[j].trim();
-        const maxLen = Math.max(originalLine.length, searchLine.length);
-        if (maxLen === 0) {
-          continue;
-        }
-        const distance = levenshtein(originalLine, searchLine);
-        similarity += (1 - distance / maxLen) / linesToCheck;
-        if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
-          break;
-        }
-      }
-    } else {
-      similarity = 1.0;
-    }
-    if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
-      let matchStartIndex = 0;
-      for (let k = 0; k < startLine; k++) {
-        matchStartIndex += originalLines[k].length + 1;
-      }
-      let matchEndIndex = matchStartIndex;
-      for (let k = startLine; k <= endLine; k++) {
-        matchEndIndex += originalLines[k].length;
-        if (k < endLine) {
-          matchEndIndex += 1;
-        }
-      }
-      yield content.substring(matchStartIndex, matchEndIndex);
-    }
-    return;
-  }
-
-  let bestMatch: { startLine: number; endLine: number } | null = null;
-  let maxSimilarity = -1;
-  for (const candidate of candidates) {
-    const { startLine, endLine } = candidate;
-    const actualBlockSize = endLine - startLine + 1;
-    let similarity = 0;
-    const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2);
-    if (linesToCheck > 0) {
-      for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
-        const originalLine = originalLines[startLine + j].trim();
-        const searchLine = searchLines[j].trim();
-        const maxLen = Math.max(originalLine.length, searchLine.length);
-        if (maxLen === 0) {
-          continue;
-        }
-        const distance = levenshtein(originalLine, searchLine);
-        similarity += 1 - distance / maxLen;
-      }
-      similarity /= linesToCheck;
-    } else {
-      similarity = 1.0;
-    }
-    if (similarity > maxSimilarity) {
-      maxSimilarity = similarity;
-      bestMatch = candidate;
-    }
-  }
-  if (maxSimilarity >= MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD && bestMatch) {
-    const { startLine, endLine } = bestMatch;
-    let matchStartIndex = 0;
-    for (let k = 0; k < startLine; k++) {
-      matchStartIndex += originalLines[k].length + 1;
-    }
-    let matchEndIndex = matchStartIndex;
-    for (let k = startLine; k <= endLine; k++) {
-      matchEndIndex += originalLines[k].length;
-      if (k < endLine) {
-        matchEndIndex += 1;
-      }
-    }
-    yield content.substring(matchStartIndex, matchEndIndex);
-  }
-};
-
-const WhitespaceNormalizedReplacer: Replacer = function* (content, find) {
-  const normalizeWhitespace = (text: string) => text.replace(/\s+/g, " ").trim();
-  const normalizedFind = normalizeWhitespace(find);
-  const lines = content.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (normalizeWhitespace(line) === normalizedFind) {
-      yield line;
-    } else {
-      const normalizedLine = normalizeWhitespace(line);
-      if (normalizedLine.includes(normalizedFind)) {
-        const words = find.trim().split(/\s+/);
-        if (words.length > 0) {
-          const pattern = words
-            .map((word) => word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-            .join("\\s+");
-          try {
-            const regex = new RegExp(pattern);
-            const match = line.match(regex);
-            if (match) {
-              yield match[0];
-            }
-          } catch {
-            // Invalid regex pattern, skip
-          }
-        }
-      }
-    }
-  }
-  const findLines = find.split("\n");
-  if (findLines.length > 1) {
-    for (let i = 0; i <= lines.length - findLines.length; i++) {
-      const block = lines.slice(i, i + findLines.length);
-      if (normalizeWhitespace(block.join("\n")) === normalizedFind) {
-        yield block.join("\n");
-      }
-    }
-  }
-};
-
-const IndentationFlexibleReplacer: Replacer = function* (content, find) {
-  const removeIndentation = (text: string) => {
-    const lines = text.split("\n");
-    const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
-    if (nonEmptyLines.length === 0) return text;
-    const minIndent = Math.min(
-      ...nonEmptyLines.map((line) => {
-        const match = line.match(/^(\s*)/);
-        return match ? match[1].length : 0;
-      }),
-    );
-    return lines
-      .map((line) => (line.trim().length === 0 ? line : line.slice(minIndent)))
-      .join("\n");
-  };
-  const normalizedFind = removeIndentation(find);
-  const contentLines = content.split("\n");
-  const findLines = find.split("\n");
-  for (let i = 0; i <= contentLines.length - findLines.length; i++) {
-    const block = contentLines.slice(i, i + findLines.length).join("\n");
-    if (removeIndentation(block) === normalizedFind) {
-      yield block;
-    }
-  }
-};
-
-const EscapeNormalizedReplacer: Replacer = function* (content, find) {
-  const unescapeString = (str: string): string => {
-    return str.replace(/\\(n|t|r|'|"|`|\\|\n|\$)/g, (_match, capturedChar) => {
-      switch (capturedChar) {
-        case "n":
-          return "\n";
-        case "t":
-          return "\t";
-        case "r":
-          return "\r";
-        case "'":
-          return "'";
-        case '"':
-          return '"';
-        case "`":
-          return "`";
-        case "\\":
-          return "\\";
-        case "\n":
-          return "\n";
-        case "$":
-          return "$";
-        default:
-          return _match;
-      }
-    });
-  };
-  const unescapedFind = unescapeString(find);
-  if (content.includes(unescapedFind)) {
-    yield unescapedFind;
-  }
-  const lines = content.split("\n");
-  const findLines = unescapedFind.split("\n");
-  for (let i = 0; i <= lines.length - findLines.length; i++) {
-    const block = lines.slice(i, i + findLines.length).join("\n");
-    const unescapedBlock = unescapeString(block);
-    if (unescapedBlock === unescapedFind) {
-      yield block;
-    }
-  }
-};
-
-const MultiOccurrenceReplacer: Replacer = function* (content, find) {
-  let startIndex = 0;
-  while (true) {
-    const index = content.indexOf(find, startIndex);
-    if (index === -1) break;
-    yield find;
-    startIndex = index + find.length;
-  }
-};
-
-const TrimmedBoundaryReplacer: Replacer = function* (content, find) {
-  const trimmedFind = find.trim();
-  if (trimmedFind === find) {
-    return;
-  }
-  if (content.includes(trimmedFind)) {
-    yield trimmedFind;
-  }
-  const lines = content.split("\n");
-  const findLines = find.split("\n");
-  for (let i = 0; i <= lines.length - findLines.length; i++) {
-    const block = lines.slice(i, i + findLines.length).join("\n");
-    if (block.trim() === trimmedFind) {
-      yield block;
-    }
-  }
-};
-
-const ContextAwareReplacer: Replacer = function* (content, find) {
-  const findLines = find.split("\n");
-  if (findLines.length < 3) {
-    return;
-  }
-  if (findLines[findLines.length - 1] === "") {
-    findLines.pop();
-  }
-  const contentLines = content.split("\n");
-  const firstLine = findLines[0].trim();
-  const lastLine = findLines[findLines.length - 1].trim();
-  for (let i = 0; i < contentLines.length; i++) {
-    if (contentLines[i].trim() !== firstLine) continue;
-    for (let j = i + 2; j < contentLines.length; j++) {
-      if (contentLines[j].trim() === lastLine) {
-        const blockLines = contentLines.slice(i, j + 1);
-        const block = blockLines.join("\n");
-        if (blockLines.length === findLines.length) {
-          let matchingLines = 0;
-          let totalNonEmptyLines = 0;
-          for (let k = 1; k < blockLines.length - 1; k++) {
-            const blockLine = blockLines[k].trim();
-            const findLine = findLines[k].trim();
-            if (blockLine.length > 0 || findLine.length > 0) {
-              totalNonEmptyLines++;
-              if (blockLine === findLine) {
-                matchingLines++;
-              }
-            }
-          }
-          if (totalNonEmptyLines === 0 || matchingLines / totalNonEmptyLines >= 0.5) {
-            yield block;
-            break;
-          }
-        }
-        break;
-      }
-    }
-  }
-};
-
-function isDisproportionateMatch(search: string, oldString: string) {
-  const oldLines = oldString.split("\n").length;
-  const searchLines = search.split("\n").length;
-  if (searchLines >= Math.max(oldLines + 3, oldLines * 2)) return true;
-  if (oldLines === 1) return false;
-  return (
-    search.trim().length > Math.max(oldString.trim().length + 500, oldString.trim().length * 4)
-  );
-}
-
-function replace(
-  content: string,
-  oldString: string,
-  newString: string,
-  replaceAll = false,
-): string {
-  if (oldString === newString) {
-    throw new Error("No changes to apply: oldString and newString are identical.");
-  }
-  if (oldString === "") {
-    throw new Error(
-      "oldString cannot be empty when editing an existing file. Provide the exact text to replace, or use write for an intentional full-file replacement.",
-    );
-  }
-
-  let notFound = true;
-
-  for (const replacer of [
-    SimpleReplacer,
-    LineTrimmedReplacer,
-    BlockAnchorReplacer,
-    WhitespaceNormalizedReplacer,
-    IndentationFlexibleReplacer,
-    EscapeNormalizedReplacer,
-    TrimmedBoundaryReplacer,
-    ContextAwareReplacer,
-    MultiOccurrenceReplacer,
-  ]) {
-    for (const search of replacer(content, oldString)) {
-      const index = content.indexOf(search);
-      if (index === -1) continue;
-      notFound = false;
-      if (isDisproportionateMatch(search, oldString)) {
-        throw new Error(
-          "Refusing replacement because the matched span is much larger than oldString. Re-read the file and provide the full exact oldString for the intended replacement.",
-        );
-      }
-      if (replaceAll) {
-        return content.replaceAll(search, newString);
-      }
-      const lastIndex = content.lastIndexOf(search);
-      if (index !== lastIndex) continue;
-      return content.substring(0, index) + newString + content.substring(index + search.length);
-    }
-  }
-
-  if (notFound) {
-    throw new Error(
-      "Could not find oldString in the file. It must match exactly, including whitespace, indentation, and line endings.",
-    );
-  }
-  throw new Error(
-    "Found multiple matches for oldString. Provide more surrounding context to make the match unique.",
-  );
-}
-
 // ── extension ─────────────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {

package/src/workspace-guard.ts

@@ -4,6 +4,7 @@
  * File-modifying tools (write, edit) are gated:
  * - Paths inside the workspace or /tmp are auto-allowed.
  * - Paths outside require user approval via confirmation dialog.
+ *   The dialog shows a ```diff code block preview of the pending change.
  *
  * Read tools (read, ls, find, grep) are unrestricted.
  *
@@ -11,14 +12,23 @@
  *   pi -e workspace-guard
  */
 
-import { isAbsolute, join, resolve, relative, sep } from "node:path";
+import { basename, isAbsolute, join, resolve, relative, sep } from "node:path";
 import { homedir } from "node:os";
-import type { ExtensionAPI, ToolCallEvent } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import {
+  generateUnifiedPatch,
+  type ExtensionAPI,
+  type ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import { normalizeForEdit, replace } from "./opencode-edit-engine.js";
 
 const WRITE_TOOLS = new Set(["write", "edit"]);
 const ALWAYS_ALLOW = ["/tmp"];
 
-function getWriteTarget(input: ToolCallEvent["input"]): string | undefined {
+/** Maximum lines of the diff preview shown in the approval dialog. */
+const MAX_PREVIEW_LINES = 100;
+
+export function getWriteTarget(input: ToolCallEvent["input"]): string | undefined {
   if (typeof input !== "object" || input === null) return undefined;
   if ("path" in input && typeof input.path === "string") return input.path;
   if ("filePath" in input && typeof input.filePath === "string") return input.filePath;
@@ -52,6 +62,115 @@ function isPathAllowed(resolvedPath: string, cwd: string): boolean {
   return false;
 }
 
+/**
+ * Type guard for built-in edit entries `{ oldText, newText }`.
+ */
+function isEditPair(value: unknown): value is { oldText: string; newText: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "oldText" in value &&
+    typeof value.oldText === "string" &&
+    "newText" in value &&
+    typeof value.newText === "string"
+  );
+}
+
+/**
+ * Extract the opencode-style edit pair `{ oldString, newString, replaceAll }`.
+ */
+function getOpencodeEditPair(
+  input: ToolCallEvent["input"],
+): { oldString: string; newString: string; replaceAll: boolean } | undefined {
+  if (typeof input !== "object" || input === null) return undefined;
+  if (!("oldString" in input) || !("newString" in input)) return undefined;
+  if (typeof input.oldString !== "string" || typeof input.newString !== "string") return undefined;
+  return {
+    oldString: input.oldString,
+    newString: input.newString,
+    replaceAll: "replaceAll" in input && input.replaceAll === true,
+  };
+}
+
+/**
+ * Apply the pending write/edit to `content`.
+ * Returns undefined when the change cannot be applied (missing fields or oldText not found).
+ */
+function applyChange(
+  toolName: string,
+  input: ToolCallEvent["input"],
+  content: string,
+): string | undefined {
+  if (typeof input !== "object" || input === null) return undefined;
+
+  if (toolName === "write") {
+    return "content" in input && typeof input.content === "string" ? input.content : undefined;
+  }
+
+  // Built-in edit: { path, edits: [{ oldText, newText }] }
+  if ("edits" in input && Array.isArray(input.edits)) {
+    let next = content;
+    for (const edit of input.edits) {
+      if (!isEditPair(edit)) return undefined;
+      if (!next.includes(edit.oldText)) return undefined;
+      next = next.replace(edit.oldText, edit.newText);
+    }
+    return next;
+  }
+
+  return undefined;
+}
+
+/** Wrap patch text in a ```diff code block, truncating very large diffs. */
+function wrapDiff(patch: string): string {
+  const lines = patch.split("\n");
+  if (lines.length > MAX_PREVIEW_LINES) {
+    const truncated = lines.slice(0, MAX_PREVIEW_LINES).join("\n");
+    return `\`\`\`diff\n${truncated}\n… (preview truncated to ${MAX_PREVIEW_LINES} lines)\n\`\`\``;
+  }
+  return `\`\`\`diff\n${patch}\n\`\`\``;
+}
+
+/**
+ * Build a ```diff code block preview of the pending change.
+ * Returns undefined when the diff cannot be computed.
+ */
+export async function buildDiffPreview(
+  toolName: string,
+  input: ToolCallEvent["input"],
+  resolvedPath: string,
+): Promise<string | undefined> {
+  let oldContent = "";
+  try {
+    oldContent = await readFile(resolvedPath, "utf-8");
+  } catch {
+    // Unreadable or missing file: treat as empty so writes show as full additions.
+  }
+
+  // opencode-edit: reuse the real matching engine to locate oldString, giving a
+  // line-numbered patch when it matches. Fall back to a parameter diff when the
+  // edit cannot be applied (oldString not found, ambiguous, or no file).
+  const pair = getOpencodeEditPair(input);
+  if (pair) {
+    try {
+      const normalized = normalizeForEdit(oldContent);
+      const newContent = replace(normalized, pair.oldString, pair.newString, pair.replaceAll);
+      // The full path is shown in the dialog title, so the patch header only
+      // carries the file name.
+      return wrapDiff(generateUnifiedPatch(basename(resolvedPath), normalized, newContent));
+    } catch {
+      const removed = pair.oldString.split("\n").map((line) => `-${line}`);
+      const added = pair.newString.split("\n").map((line) => `+${line}`);
+      return wrapDiff([...removed, ...added].join("\n"));
+    }
+  }
+
+  const newContent = applyChange(toolName, input, oldContent);
+  if (newContent === undefined) return undefined;
+
+  return wrapDiff(generateUnifiedPatch(basename(resolvedPath), oldContent, newContent));
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", (event, ctx) => {
     const currentCwd = ctx.cwd;
@@ -83,13 +202,17 @@ export default function (pi: ExtensionAPI) {
 
     let choice: string | undefined;
     while (!choice) {
-      choice = await ctx.ui.select(
+      const diffPreview = await buildDiffPreview(event.toolName, event.input, resolved);
+
+      const title =
         `Model requests write access outside workspace:\n\n` +
-          `  Tool:  ${event.toolName}\n` +
-          `  Path:  ${rawPath}\n` +
-          `  Resolved: ${resolved}\n\nAllow?`,
-        ["Approve once", "Block", "Block with reason"],
-      );
+        `  Tool:  ${event.toolName}\n` +
+        `  Path:  ${rawPath}\n` +
+        `  Resolved: ${resolved}\n` +
+        (diffPreview ? `\n${diffPreview}\n` : "") +
+        `\nAllow?`;
+
+      choice = await ctx.ui.select(title, ["Approve once", "Block", "Block with reason"]);
 
       if (typeof choice === "undefined") {
         ctx.abort();