@trim21/personal-pi-extensions 0.0.304 → 0.0.306

package/package.json

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

package/src/aft/ast-edit.ts

@@ -11,7 +11,11 @@
  * 防呆不同，ast_edit 不要求先读）。
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  type ExtensionAPI,
+  generateDiffString,
+  generateUnifiedPatch,
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
@@ -114,6 +118,35 @@ export function mapEditItems(
   });
 }
 
+/**
+ * 参照 Edit 工具的结果输出：把 preview 的 before/after 转成行号 diff、
+ * unified patch 与首个变更行。多文件（glob 批量）时逐文件拼接 diff/patch，
+ * firstChangedLine 取首个文件的。
+ */
+export function buildEditDiffDetails(
+  previewFiles: PreviewFile[],
+  fallbackFile: string,
+): { diff: string; patch: string; firstChangedLine: number | undefined } {
+  const parts = previewFiles.map((f) => {
+    const file = f.file || fallbackFile;
+    const diff = generateDiffString(f.before, f.after);
+    return {
+      file,
+      diff: diff.diff,
+      patch: generateUnifiedPatch(file, f.before, f.after),
+      firstChangedLine: diff.firstChangedLine,
+    };
+  });
+  if (parts.length === 0) {
+    return { diff: "", patch: "", firstChangedLine: undefined };
+  }
+  return {
+    diff: parts.map((p) => `--- ${p.file}\n${p.diff}`).join("\n"),
+    patch: parts.map((p) => `--- ${p.file}\n${p.patch}`).join("\n"),
+    firstChangedLine: parts[0]?.firstChangedLine,
+  };
+}
+
 // ── 工具 ────────────────────────────────────────────────────────────────────
 
 const EditItemParams = Type.Object({
@@ -262,6 +295,7 @@ export function registerAstEditTool(pi: ExtensionAPI, ctx: AftToolContext): void
         content: [{ type: "text", text }],
         details: {
           files,
+          ...buildEditDiffDetails(previewFiles, filePath),
           pendant: {
             markdown: buildPendantMarkdown({
               title: "ast_edit",

package/src/aft/imports.ts

@@ -0,0 +1,125 @@
+/**
+ * aft_import —— language-aware import add / remove。
+ *
+ * 参数经 bridge.toolCall 以 agent 工具名 "import" 分派，Rust 侧 subc 翻译层
+ * 按 op 转成内部命令（add_import / remove_import）。
+ * 与 aft_refactor 相同：不支持 preview，写保护为路径级审批。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type ToolPendant } from "../lib/pendant.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+import { callAftTool } from "./bridge.js";
+import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+
+const IMPORT_OPS = ["add", "remove"] as const;
+const VALIDATE_LEVELS = ["syntax", "full"] as const;
+
+const ImportParams = Type.Object(
+  {
+    op: Type.Union(
+      IMPORT_OPS.map((op) => Type.Literal(op)),
+      { description: "import 操作" },
+    ),
+    path: Type.String({ description: "目标文件路径（绝对或相对项目根）" }),
+    module: Type.Optional(
+      Type.String({ description: "模块路径（add/remove 必填），如 'react'、'./utils'" }),
+    ),
+    names: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "要添加的具名导入，用语言原生的具名导入写法，支持按名 `as` 别名，如 ['useState']、Solidity ['ERC20', 'IERC20 as IToken']",
+      }),
+    ),
+    default_import: Type.Optional(Type.String({ description: "默认导入名（仅 ES），如 'React'" })),
+    namespace: Type.Optional(
+      Type.String({
+        description:
+          "命名空间绑定：`import * as ns from 'mod'`（ES）、`* as N from \"./X.sol\"`（Solidity）",
+      }),
+    ),
+    alias: Type.Optional(
+      Type.String({ description: '整模块别名。Solidity：`import "./X.sol" as X`' }),
+    ),
+    modifiers: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "语句级修饰符，按语言校验：Java/C# 'static'、C# 'global'/'unsafe'、Java/Kotlin/Scala 'wildcard'、Swift '@testable'",
+      }),
+    ),
+    import_kind: Type.Optional(
+      Type.String({
+        description:
+          "符号类导入：PHP 'function'/'const'、Swift 'struct'/'class'/'enum'、Scala 'given'",
+      }),
+    ),
+    remove_name: Type.Optional(
+      Type.String({ description: "要移除的具名导入；缺省移除整个 import" }),
+    ),
+    type_only: Type.Optional(Type.Boolean({ description: "仅类型导入（仅 TS）" })),
+    validate: Type.Optional(
+      Type.Union(
+        VALIDATE_LEVELS.map((level) => Type.Literal(level)),
+        {
+          description: "编辑后校验级别（默认 syntax）",
+        },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export function registerImportTool(pi: ExtensionAPI, ctx: AftToolContext): void {
+  pi.registerTool({
+    name: "aft_import",
+    label: "aft_import",
+    description: [
+      "语言感知的 import 管理：add / remove。",
+      "支持 TS, JS, TSX, Python, Rust, Go, Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, C, C++, Perl, Vue。",
+      "add：添加默认/具名/命名空间导入；remove：移除具名导入或整个 import。",
+      "import 排序整理交给 lint（如 import/order + --fix），本工具不负责。",
+    ].join("\n"),
+    promptSnippet: "Language-aware import add / remove",
+    parameters: ImportParams,
+    async execute(_id, params, _signal, _onUpdate, extCtx) {
+      if (params.module === undefined || params.module.trim() === "") {
+        throw new Error(`'module' is required for '${params.op}' op`);
+      }
+
+      const filePath = resolvePathArg(extCtx.cwd, params.path);
+      await guardWriteAccess(extCtx, { toolName: "aft_import", absolutePath: filePath });
+
+      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
+      if (params.module !== undefined && params.module.trim() !== "") {
+        rawArgs.module = params.module;
+      }
+      if (params.names !== undefined) rawArgs.names = params.names;
+      if (params.default_import !== undefined) rawArgs.defaultImport = params.default_import;
+      if (params.namespace !== undefined) rawArgs.namespace = params.namespace;
+      if (params.alias !== undefined) rawArgs.alias = params.alias;
+      if (params.modifiers !== undefined) rawArgs.modifiers = params.modifiers;
+      if (params.import_kind !== undefined) rawArgs.importKind = params.import_kind;
+      if (params.remove_name !== undefined) rawArgs.removeName = params.remove_name;
+      if (params.type_only !== undefined) rawArgs.typeOnly = params.type_only;
+      if (params.validate !== undefined) rawArgs.validate = params.validate;
+
+      const { text } = await callAftTool(bridgeFor(ctx), "import", rawArgs, extCtx);
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          files: [filePath],
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_import",
+              input: params,
+              output: text,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
+      };
+    },
+  });
+}

package/src/aft/index.ts

@@ -1,12 +1,14 @@
 /**
  * AFT 扩展入口：感知工具（aft_outline / aft_zoom / aft_callgraph / aft_search）
- * + ast_edit（符号级编辑，套用本仓库写保护机制）。
+ * + ast_edit（符号级编辑，套用本仓库写保护机制）+ aft_refactor / aft_import
+ * （workspace-wide 重构与 import 管理，路径级写保护）。
  *
  * 感知工具只读，不触碰本仓库自己的 read/write/edit/bash 工具及其安全机制
  * （bwrap 沙箱、write-guard、reads 记账）。aft_search 仅当用户级
  * aft.jsonc 开启 semantic_search 时注册（本地语义索引需 ONNX 运行时，
  * 内网默认关闭）。ast_edit 是写工具：用 AFT 的 preview 计算 diff，落盘走
- * 本仓库的 write-guard + reads 记账 + 写管线。
+ * 本仓库的 write-guard + reads 记账 + 写管线。aft_refactor / aft_import 的
+ * Rust 命令不支持 preview，写保护退化为路径级审批。
  *
  * 二进制缺失或 pool 创建失败时降级：不注册任何工具并在 session 开始时报
  * 一次错，而不是让每个工具调用失败。
@@ -21,6 +23,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAstEditTool } from "./ast-edit.js";
 import { type AftPool, createAftPool, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
+import { registerImportTool } from "./imports.js";
+import { registerRefactorTool } from "./refactor.js";
 import {
   registerCallgraphTool,
   registerOutlineTool,
@@ -52,6 +56,8 @@ export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
   registerZoomTool(pi, toolCtx);
   registerCallgraphTool(pi, toolCtx);
   registerAstEditTool(pi, toolCtx);
+  registerRefactorTool(pi, toolCtx);
+  registerImportTool(pi, toolCtx);
   if (cfg.semanticSearch) {
     registerSearchTool(pi, toolCtx);
   }

package/src/aft/refactor.ts

@@ -0,0 +1,144 @@
+/**
+ * aft_refactor —— workspace-wide refactoring（move / extract / inline）。
+ *
+ * 参数经 bridge.toolCall 以 agent 工具名 "refactor" 分派，Rust 侧 subc 翻译层
+ * 按 op 转成内部命令（move_symbol / extract_function / inline_symbol）。
+ * 与 ast_edit 不同，这些命令不支持 preview：写保护退化为路径级审批
+ * （workspace 内自动放行，外部路径经 write-guard 确认，无 diff 预览）。
+ */
+
+import { coerceOptionalInt } from "@cortexkit/aft-bridge";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type ToolPendant } from "../lib/pendant.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+import { callAftTool } from "./bridge.js";
+import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+
+const REFACTOR_OPS = ["move", "extract", "inline"] as const;
+
+function requireField(value: unknown, name: string, op: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`'${name}' is required for '${op}' op`);
+  }
+}
+
+const RefactorParams = Type.Object(
+  {
+    op: Type.Union(
+      REFACTOR_OPS.map((op) => Type.Literal(op)),
+      { description: "重构操作" },
+    ),
+    path: Type.String({
+      description: "源文件路径（绝对或相对项目根；move 为符号当前所在文件）",
+    }),
+    symbol: Type.Optional(Type.String({ description: "符号名（move / inline 必填）" })),
+    destination: Type.Optional(Type.String({ description: "目标文件（move 必填）" })),
+    scope: Type.Optional(Type.String({ description: "move 消歧作用域" })),
+    name: Type.Optional(Type.String({ description: "新函数名（extract 必填）" })),
+    start_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "extract 起始行（1 起，必填）",
+      }),
+    ),
+    end_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "extract 结束行（含，必填）",
+      }),
+    ),
+    call_site_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "inline 调用点行号（1 起，必填）",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export function registerRefactorTool(pi: ExtensionAPI, ctx: AftToolContext): void {
+  pi.registerTool({
+    name: "aft_refactor",
+    label: "aft_refactor",
+    description: [
+      "workspace-wide 重构：更新跨文件的 import 与引用。",
+      "move：把顶层符号（非嵌套函数/类方法）移到另一文件，全 workspace 重写 import；执行前自动创建 checkpoint。",
+      "extract：把行区间抽成新函数（TS/JS/TSX、Python）。",
+      "inline：把调用点替换为函数体。",
+      "move / rename 整个文件用 aft_move（OS 层操作，不更新引用）；移动代码符号用本工具 op=move。",
+    ].join("\n"),
+    promptSnippet: "Workspace-wide symbol move / function extraction / inlining",
+    parameters: RefactorParams,
+    async execute(_id, params, _signal, _onUpdate, extCtx) {
+      const startLine = coerceOptionalInt(
+        params.start_line,
+        "start_line",
+        1,
+        Number.MAX_SAFE_INTEGER,
+      );
+      const endLine = coerceOptionalInt(params.end_line, "end_line", 1, Number.MAX_SAFE_INTEGER);
+      const callSiteLine = coerceOptionalInt(
+        params.call_site_line,
+        "call_site_line",
+        1,
+        Number.MAX_SAFE_INTEGER,
+      );
+
+      if (params.op === "move") {
+        requireField(params.symbol, "symbol", "move");
+        requireField(params.destination, "destination", "move");
+      } else if (params.op === "extract") {
+        requireField(params.name, "name", "extract");
+        if (startLine === undefined) throw new Error("'start_line' is required for 'extract' op");
+        if (endLine === undefined) throw new Error("'end_line' is required for 'extract' op");
+      } else {
+        requireField(params.symbol, "symbol", "inline");
+        if (callSiteLine === undefined) {
+          throw new Error("'call_site_line' is required for 'inline' op");
+        }
+      }
+
+      const filePath = resolvePathArg(extCtx.cwd, params.path);
+      const destination =
+        params.destination === undefined || params.destination.trim() === ""
+          ? undefined
+          : resolvePathArg(extCtx.cwd, params.destination);
+
+      const targets = destination === undefined ? [filePath] : [filePath, destination];
+      for (const target of targets) {
+        await guardWriteAccess(extCtx, { toolName: "aft_refactor", absolutePath: target });
+      }
+
+      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
+      if (params.symbol !== undefined && params.symbol.trim() !== "") {
+        rawArgs.symbol = params.symbol;
+      }
+      if (destination !== undefined) rawArgs.destination = destination;
+      if (params.scope !== undefined && params.scope.trim() !== "") {
+        rawArgs.scope = params.scope;
+      }
+      if (params.name !== undefined && params.name.trim() !== "") {
+        rawArgs.name = params.name;
+      }
+      if (startLine !== undefined) rawArgs.startLine = startLine;
+      if (endLine !== undefined) rawArgs.endLine = endLine;
+      if (callSiteLine !== undefined) rawArgs.callSiteLine = callSiteLine;
+
+      const { text } = await callAftTool(bridgeFor(ctx), "refactor", rawArgs, extCtx);
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          files: targets,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_refactor",
+              input: params,
+              output: text,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
+      };
+    },
+  });
+}

package/src/lib/write-guard.ts

@@ -108,7 +108,11 @@ export interface WriteGuardOptions {
   toolName: string;
   /** The resolved absolute target path (caller has already parsed its args). */
   absolutePath: string;
-  change: PendingChange;
+  /**
+   * 待审批的变更内容；缺省时（如 aft_refactor/aft_import 无 preview diff）
+   * 审批对话框不展示 diff 预览，仅按路径审批。
+   */
+  change?: PendingChange;
 }
 
 /**
@@ -137,7 +141,7 @@ export async function guardWriteAccess(
   }
 
   while (true) {
-    const diffPreview = await buildDiffPreview(absolutePath, opts.change);
+    const diffPreview = opts.change ? await buildDiffPreview(absolutePath, opts.change) : undefined;
     const title =
       `Model requests write access outside workspace:\n\n` +
       `  Tool:  ${opts.toolName}\n` +