@trim21/personal-pi-extensions 0.0.225 → 0.0.230

package/src/claude-code/search.ts

@@ -1,218 +1,22 @@
-import { glob as fsGlob, stat } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+/**
+ * Claude Code style search tools — `Glob` and `Grep`.
+ *
+ * Aggregation entry that registers both tools; each tool also lives in its own
+ * file (glob.ts / grep.ts) so spawn-agent subagents can load them
+ * independently via the `Glob` / `Grep` frontmatter tool names.
+ */
 
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 
-import { throwIfAborted } from "./common.js";
-
-const GLOB_RESULT_LIMIT = 100;
-const GREP_OUTPUT_MODES = ["content", "files_with_matches", "count"] as const;
-
-type GrepOutputMode = (typeof GREP_OUTPUT_MODES)[number];
-
-function searchRoot(path: string | undefined, cwd: string): string {
-  if (!path) return cwd;
-  return isAbsolute(path) ? path : resolve(cwd, path);
-}
-
-function truncateOutput(output: string, maxCharacters = 30_000): string {
-  if (output.length <= maxCharacters) return output;
-  return `${output.slice(0, maxCharacters)}\n\n[Output truncated at ${maxCharacters} characters]`;
-}
-
-export async function globFiles(
-  pattern: string,
-  cwd: string,
-  signal?: AbortSignal,
-): Promise<string[]> {
-  throwIfAborted(signal);
-  const matches: { path: string; mtimeMs: number }[] = [];
-  for await (const match of fsGlob(pattern, { cwd, exclude: [".git/**"], withFileTypes: false })) {
-    throwIfAborted(signal);
-    const absolutePath = resolve(cwd, match);
-    try {
-      const value = await stat(absolutePath);
-      if (value.isFile()) matches.push({ path: absolutePath, mtimeMs: value.mtimeMs });
-    } catch {
-      // A concurrent filesystem change can remove a match before stat.
-    }
-  }
-  return matches
-    .toSorted((left, right) => right.mtimeMs - left.mtimeMs || left.path.localeCompare(right.path))
-    .slice(0, GLOB_RESULT_LIMIT)
-    .map((match) => match.path);
-}
-
-interface GrepParameters {
-  pattern: string;
-  path?: string;
-  glob?: string;
-  output_mode?: GrepOutputMode;
-  "-B"?: number;
-  "-A"?: number;
-  "-C"?: number;
-  context?: number;
-  "-n"?: boolean;
-  "-i"?: boolean;
-  type?: string;
-  head_limit?: number;
-  offset?: number;
-  multiline?: boolean;
-}
-
-export function buildGrepArguments(params: GrepParameters, cwd: string): string[] {
-  const mode = params.output_mode ?? "files_with_matches";
-  const args = ["--color=never"];
-  switch (mode) {
-    case "files_with_matches": {
-      args.push("--files-with-matches");
-      break;
-    }
-    case "count": {
-      args.push("--count-matches");
-      break;
-    }
-    case "content": {
-      args.push("--no-heading", "--with-filename");
-      if (params["-n"] !== false) args.push("--line-number");
-      const before = params["-B"];
-      const after = params["-A"];
-      const around = params.context ?? params["-C"];
-      if (around === undefined) {
-        if (before !== undefined) args.push("--before-context", String(before));
-        if (after !== undefined) args.push("--after-context", String(after));
-      } else args.push("--context", String(around));
-
-      break;
-    }
-    // No default
-  }
-  if (params["-i"] === true) args.push("--ignore-case");
-  if (params.glob) args.push("--glob", params.glob);
-  if (params.type) args.push("--type", params.type);
-  if (params.multiline === true) args.push("--multiline", "--multiline-dotall");
-  args.push("--", params.pattern, searchRoot(params.path, cwd));
-  return args;
-}
-
-export function pageGrepOutput(output: string, offset = 0, headLimit = 0): string {
-  const lines = output ? output.replace(/\n$/, "").split("\n") : [];
-  if (offset >= lines.length && lines.length > 0) return "No entries at this offset";
-  const selected = headLimit > 0 ? lines.slice(offset, offset + headLimit) : lines.slice(offset);
-  return truncateOutput(selected.join("\n"));
-}
+import { registerGlobTool } from "./glob.js";
+import { registerGrepTool } from "./grep.js";
 
 export function registerSearchTools(pi: ExtensionAPI): void {
-  pi.registerTool({
-    name: "Glob",
-    label: "Glob",
-    description: [
-      "Fast file pattern matching tool that works with any codebase size.",
-      'Supports glob patterns such as "**/*.js" and "src/**/*.ts".',
-      "Returns matching file paths sorted by modification time.",
-    ].join("\n"),
-    parameters: Type.Object(
-      {
-        pattern: Type.String({ description: "The glob pattern to match files against" }),
-        path: Type.Optional(
-          Type.String({
-            description:
-              "The directory to search in. If omitted, the current working directory is used.",
-          }),
-        ),
-      },
-      { additionalProperties: false },
-    ),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const root = searchRoot(params.path, ctx.cwd);
-      const matches = await globFiles(params.pattern, root, signal);
-      return {
-        content: [
-          { type: "text", text: matches.length > 0 ? matches.join("\n") : "No files found" },
-        ],
-        details: { count: matches.length },
-      };
-    },
-  });
-
-  pi.registerTool({
-    name: "Grep",
-    label: "Grep",
-    description: [
-      "A powerful search tool built on ripgrep.",
-      "Supports regular expressions, file globs, file types, multiline matching, context lines, and paginated output.",
-      'output_mode defaults to "files_with_matches"; use "content" for matching lines or "count" for match counts.',
-    ].join("\n"),
-    parameters: Type.Object(
-      {
-        pattern: Type.String({ description: "The regular expression pattern to search for" }),
-        path: Type.Optional(
-          Type.String({
-            description: "File or directory to search. Defaults to the current directory.",
-          }),
-        ),
-        glob: Type.Optional(
-          Type.String({ description: 'Glob filter such as "*.js" or "*.{ts,tsx}"' }),
-        ),
-        output_mode: Type.Optional(
-          StringEnum(GREP_OUTPUT_MODES, {
-            description: "Output mode. Defaults to files_with_matches.",
-          }),
-        ),
-        "-B": Type.Optional(
-          Type.Number({ description: "Lines to show before each match in content mode" }),
-        ),
-        "-A": Type.Optional(
-          Type.Number({ description: "Lines to show after each match in content mode" }),
-        ),
-        "-C": Type.Optional(
-          Type.Number({ description: "Lines to show before and after each match" }),
-        ),
-        context: Type.Optional(
-          Type.Number({ description: "Lines to show before and after each match" }),
-        ),
-        "-n": Type.Optional(
-          Type.Boolean({ description: "Show line numbers in content mode; defaults true" }),
-        ),
-        "-i": Type.Optional(Type.Boolean({ description: "Case-insensitive search" })),
-        type: Type.Optional(
-          Type.String({ description: "ripgrep file type such as js, py, rust, or go" }),
-        ),
-        head_limit: Type.Optional(
-          Type.Number({ description: "Limit output to the first N entries after offset" }),
-        ),
-        offset: Type.Optional(Type.Number({ description: "Skip the first N output entries" })),
-        multiline: Type.Optional(
-          Type.Boolean({ description: "Allow patterns to span multiple lines" }),
-        ),
-      },
-      { additionalProperties: false },
-    ),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      if (
-        params.offset !== undefined &&
-        (!Number.isSafeInteger(params.offset) || params.offset < 0)
-      ) {
-        throw new Error("offset must be a non-negative integer");
-      }
-      if (
-        params.head_limit !== undefined &&
-        (!Number.isSafeInteger(params.head_limit) || params.head_limit < 0)
-      ) {
-        throw new Error("head_limit must be a non-negative integer");
-      }
-      const result = await pi.exec("rg", buildGrepArguments(params, ctx.cwd), { signal });
-      throwIfAborted(signal);
-      if (result.code !== 0 && result.code !== 1) {
-        throw new Error(result.stderr.trim() || `ripgrep exited with code ${result.code}`);
-      }
-      if (result.code === 1 || result.stdout === "") {
-        return { content: [{ type: "text", text: "No files found" }], details: { matches: 0 } };
-      }
-      const text = pageGrepOutput(result.stdout, params.offset ?? 0, params.head_limit ?? 0);
-      return { content: [{ type: "text", text }], details: undefined };
-    },
-  });
+  registerGlobTool(pi);
+  registerGrepTool(pi);
 }
+
+// Re-exported for tests and other modules that import pure functions from
+// "./search.js"; the implementations live in the split files above.
+export { globFiles } from "./glob.js";
+export { buildGrepArguments, pageGrepOutput } from "./grep.js";

package/src/claude-code/session-tools.ts

@@ -2,6 +2,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { selectWithOptionalInput } from "../lib/ui.js";
+
 const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
 const OTHER_OPTION = "Other";
 const DONE_OPTION = "Done";
@@ -45,15 +47,17 @@ async function askSingle(
   signal: AbortSignal | undefined,
 ): Promise<string> {
   const title = `${question.header}: ${question.question}`;
-  const selected = await ctx.ui.select(
+  const result = await selectWithOptionalInput(
     title,
-    [...question.options.map((option) => option.label), OTHER_OPTION],
+    [
+      ...question.options.map((option) => ({ label: option.label })),
+      { label: OTHER_OPTION, inputPrompt: "Type your answer" },
+    ],
+    ctx.ui,
     { signal },
   );
-  if (selected === undefined) return "Unanswered";
-  if (selected !== OTHER_OPTION) return selected;
-  const answer = await ctx.ui.input(title, "Type your answer", { signal });
-  return answer?.trim() || "Unanswered";
+  if (result === undefined) return "Unanswered";
+  return result.prompted ? result.input || "Unanswered" : result.label;
 }
 
 async function askMultiple(
@@ -65,16 +69,22 @@ async function askMultiple(
   const remaining = new Set(question.options.map((option) => option.label));
   const selected: string[] = [];
   while (remaining.size > 0) {
-    const choice = await ctx.ui.select(title, [...remaining, OTHER_OPTION, DONE_OPTION], {
-      signal,
-    });
-    if (choice === undefined || choice === DONE_OPTION) break;
-    if (choice === OTHER_OPTION) {
-      const answer = await ctx.ui.input(title, "Type your answer", { signal });
-      if (answer?.trim()) selected.push(answer.trim());
+    const result = await selectWithOptionalInput(
+      title,
+      [
+        ...[...remaining].map((label) => ({ label })),
+        { label: OTHER_OPTION, inputPrompt: "Type your answer" },
+        { label: DONE_OPTION },
+      ],
+      ctx.ui,
+      { signal },
+    );
+    if (result === undefined || result.label === DONE_OPTION) break;
+    if (result.prompted) {
+      if (result.input) selected.push(result.input);
       break;
     }
-    if (remaining.delete(choice)) selected.push(choice);
+    if (remaining.delete(result.label)) selected.push(result.label);
   }
   return selected.length > 0 ? selected.join(", ") : "Unanswered";
 }

package/src/claude-code/shell.ts

@@ -8,6 +8,7 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 600_000;
 
 export function registerShellTools(pi: ExtensionAPI): void {
+  bwrapRuntime.setup(pi);
   pi.registerTool({
     name: "Bash",
     label: "Bash",

package/src/lib/ui.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared interactive UI helpers used by multiple extensions.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface SelectAction {
+  label: string;
+  /**
+   * Set to turn this entry into a free-text input: picking it opens an input
+   * dialog instead of returning immediately. The typed text (trimmed) is
+   * reported via `SelectActionResult.input`; `undefined` means the input
+   * dialog was cancelled, `""` that an empty value was submitted.
+   */
+  inputPrompt?: string;
+}
+
+export interface SelectActionResult {
+  label: string;
+  /** Whether the picked action carries an inputPrompt (false for plain actions) */
+  prompted: boolean;
+  /** Meaningful when prompted: undefined=cancelled input, ""=blank submission, otherwise the trimmed text */
+  input?: string;
+}
+
+/**
+ * Combined select + optional input dialog.
+ *
+ * Shows a selection list built from `actions`. If the user picks an action
+ * with `inputPrompt`, an input dialog opens for free-text entry. Returns
+ * `undefined` when the selection list is dismissed.
+ */
+export async function selectWithOptionalInput(
+  title: string,
+  actions: readonly SelectAction[],
+  ui: ExtensionContext["ui"],
+  opts: { signal?: AbortSignal } = {},
+): Promise<SelectActionResult | undefined> {
+  const { signal } = opts;
+  const choice = await ui.select(
+    title,
+    actions.map((action) => action.label),
+    { signal },
+  );
+  if (choice === undefined) return undefined;
+  const action = actions.find((candidate) => candidate.label === choice);
+  if (action?.inputPrompt === undefined) return { label: choice, prompted: false };
+  const answer = await ui.input(title, action.inputPrompt, { signal });
+  return {
+    label: choice,
+    prompted: true,
+    input: answer === undefined ? undefined : answer.trim(),
+  };
+}

package/src/lib/write-guard.ts

@@ -0,0 +1,153 @@
+/**
+ * Workspace write guard, embedded directly in each write/edit tool.
+ *
+ * File-modifying tools gate themselves:
+ * - Paths inside the workspace or /tmp are auto-allowed.
+ * - Paths outside require user approval via a confirmation dialog showing a
+ *   `diff` code block preview of the pending change.
+ * - Headless sessions (no UI) reject outside writes outright.
+ *
+ * Callers have already parsed their tool arguments, so the guard only takes the
+ * resolved pieces: the raw target path and the pending change (oldText/newText).
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, relative, sep } from "node:path";
+
+import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+
+import { normalizeForEdit, replace } from "../opencode/edit-engine.js";
+
+const ALWAYS_ALLOW = ["/tmp"];
+const MAX_PREVIEW_LINES = 100;
+
+function isInside(dir: string, filePath: string): boolean {
+  const rel = relative(dir, filePath);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function isPathAllowed(absolutePath: string, cwd: string): boolean {
+  if (isInside(cwd, absolutePath)) return true;
+
+  for (const allowed of ALWAYS_ALLOW) {
+    if (isInside(allowed, absolutePath)) return true;
+  }
+
+  return false;
+}
+
+/** 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\`\`\``;
+}
+
+/** The pending file change, described by the caller from already-parsed args. */
+export interface PendingChange {
+  /** Text to replace; empty for whole-file writes. */
+  oldText: string;
+  /** Replacement text. */
+  newText: string;
+  /** Replace all occurrences of oldText (edits only). */
+  replaceAll?: boolean;
+}
+
+/**
+ * Build a `diff` code block preview of the pending change.
+ * Returns undefined when the diff cannot be computed.
+ */
+export async function buildDiffPreview(
+  resolvedPath: string,
+  change: PendingChange,
+): Promise<string | undefined> {
+  let oldContent = "";
+  try {
+    oldContent = await readFile(resolvedPath, "utf8");
+  } catch {
+    // Unreadable or missing file: treat as empty so writes show as full additions.
+  }
+
+  if (change.oldText === "") {
+    // Whole-file write: show the full addition/replacement patch.
+    return wrapDiff(generateUnifiedPatch(basename(resolvedPath), oldContent, change.newText, 2));
+  }
+
+  // Edit: reuse the real matching engine to locate oldText, giving a
+  // line-numbered patch when it matches. Fall back to a parameter diff when the
+  // edit cannot be applied (oldText not found, ambiguous, or no file).
+  try {
+    const normalized = normalizeForEdit(oldContent);
+    const newContent = replace(normalized, change.oldText, change.newText, change.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, 2));
+  } catch {
+    const removed = change.oldText.split("\n").map((line) => `-${line}`);
+    const added = change.newText.split("\n").map((line) => `+${line}`);
+    return wrapDiff([...removed, ...added].join("\n"));
+  }
+}
+
+export interface WriteGuardContext {
+  cwd: string;
+  hasUI: boolean;
+  abort?: () => void;
+  ui?: {
+    select: (title: string, options: string[]) => Promise<string | undefined>;
+    input: (title: string, placeholder?: string) => Promise<string | undefined>;
+  };
+}
+
+export interface WriteGuardOptions {
+  toolName: string;
+  /** The resolved absolute target path (caller has already parsed its args). */
+  absolutePath: string;
+  change: PendingChange;
+}
+
+/**
+ * Gate a write/edit call by its target path: auto-allows workspace and /tmp
+ * writes, otherwise asks for user approval (or rejects in headless sessions).
+ * Throws when the write is denied.
+ */
+export async function guardWriteAccess(
+  ctx: WriteGuardContext | undefined,
+  opts: WriteGuardOptions,
+): Promise<void> {
+  if (!ctx) return;
+  const { absolutePath } = opts;
+  if (isPathAllowed(absolutePath, ctx.cwd)) return;
+
+  if (!ctx.hasUI || !ctx.ui) {
+    throw new Error(`Path "${absolutePath}" is outside workspace. No UI available for approval.`);
+  }
+
+  while (true) {
+    const diffPreview = await buildDiffPreview(absolutePath, opts.change);
+    const title =
+      `Model requests write access outside workspace:\n\n` +
+      `  Tool:  ${opts.toolName}\n` +
+      `  Path:  ${absolutePath}\n` +
+      (diffPreview ? `\n${diffPreview}\n` : "") +
+      `\nAllow?`;
+
+    const choice = await ctx.ui.select(title, ["Approve once", "Block", "Block with reason"]);
+    if (choice === undefined) {
+      ctx.abort?.();
+      throw new Error("Write outside workspace cancelled by user.");
+    }
+    if (choice === "Approve once") return;
+    if (choice === "Block") throw new Error("Write outside workspace denied by user.");
+    const feedback = await ctx.ui.input("Why was this write denied?");
+    if (feedback === undefined) continue;
+    throw new Error(
+      feedback
+        ? `Write outside workspace denied: ${feedback}`
+        : "Write outside workspace denied by user.",
+    );
+  }
+}

package/src/opencode/bash.ts

@@ -8,6 +8,7 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 600_000;
 
 export default function opencodeBash(pi: ExtensionAPI): void {
+  bwrapRuntime.setup(pi);
   pi.registerTool({
     name: "bash",
     label: "bash",
@@ -27,7 +28,10 @@ export default function opencodeBash(pi: ExtensionAPI): void {
           }),
         ),
         timeout: Type.Optional(
-          Type.Number({ description: "Optional timeout in milliseconds (max 600000)" }),
+          Type.Number({
+            description: "Optional timeout in milliseconds (max 600000)",
+            default: 600,
+          }),
         ),
         dangerouslyDisableSandbox: Type.Optional(
           Type.Boolean({

package/src/opencode/edit-engine.ts

@@ -7,8 +7,8 @@
  * 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
+ *   - opencode-edit.ts — the edit tool implementation
+ *   - lib/write-guard.ts — the diff preview shown in the approval dialog
  */
 
 // ── BOM & line ending helpers ─────────────────────────────────────────────────

package/src/opencode/edit.ts

@@ -11,7 +11,7 @@
  * formatter run.
  *
  * The matching engine (replacers + replace()) lives in opencode/edit-engine.ts
- * and is also used by workspace-guard for the diff preview.
+ * and is also used by lib/write-guard for the diff preview.
  *
  * Usage:
  *   pi -e ./opencode-edit.ts
@@ -29,6 +29,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   detectLineEnding,
   normalizeToLF,
@@ -79,6 +80,12 @@ export default function opencodeEdit(pi: ExtensionAPI) {
 
       const absolutePath = isAbsolute(filePath) ? filePath : resolve(ctx.cwd, filePath);
 
+      await guardWriteAccess(ctx, {
+        toolName: "edit",
+        absolutePath,
+        change: { oldText: oldString, newText: newString, replaceAll },
+      });
+
       const throwIfAborted = (): void => {
         if (signal?.aborted) throw new Error("Operation aborted");
       };

package/src/opencode/index.ts

@@ -3,7 +3,7 @@
  *
  * 聚合 read / edit / write / todo / question / bash 六个工具，一次加载全部注册；
  * 各工具的公开 API（匹配引擎、纯函数等）也从这里重新导出，方便
- * 测试与其他模块（如 workspace-guard）引用。
+ * 测试与其他模块（如 lib/write-guard）引用。
  *
  * Usage:
  *   pi -e ./opencode/index.ts

package/src/opencode/question.ts

@@ -23,6 +23,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { selectWithOptionalInput } from "../lib/ui.js";
+
 // ── constants ────────────────────────────────────────────────────────────────
 
 export const TOOL_NAME = "question";
@@ -117,14 +119,16 @@ function dialogTitle(q: Question): string {
 
 async function askSingle(q: Question, ctx: ExtensionContext): Promise<Answer> {
   const title = dialogTitle(q);
-  const options = [...q.options.map((o) => o.label), CUSTOM_LABEL];
-  const choice = await ctx.ui.select(title, options);
-  if (choice === undefined) return [];
-  if (choice === CUSTOM_LABEL) {
-    const typed = await ctx.ui.input(title, "Type your answer…");
-    return typed?.trim() ? [typed.trim()] : [];
-  }
-  return [choice];
+  const result = await selectWithOptionalInput(
+    title,
+    [
+      ...q.options.map((o) => ({ label: o.label })),
+      { label: CUSTOM_LABEL, inputPrompt: "Type your answer…" },
+    ],
+    ctx.ui,
+  );
+  if (result === undefined) return [];
+  return result.prompted ? (result.input ? [result.input] : []) : [result.label];
 }
 
 async function askMultiple(q: Question, ctx: ExtensionContext): Promise<Answer> {

package/src/opencode/write.ts

@@ -28,6 +28,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { guardWriteAccess } from "../lib/write-guard.js";
 import { stripBom } from "./edit-engine.js";
 
 /**
@@ -69,6 +70,11 @@ export default function opencodeWrite(pi: ExtensionAPI) {
     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: { oldText: "", newText: content },
+      });
       const dir = dirname(absolutePath);
 
       const throwIfAborted = () => {