xz-pi-worktree 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 lajarre
+Copyright (c) 2026 xz-pi-vim contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# xz-pi-worktree
+
+一个职责单一的 Pi 扩展：管理本地 Git Worktree 的创建、检查、Patch 捕获、应用和清理。
+
+它不启动或调度 Agent，不依赖 `xz-pi-subagents`，也不会自动响应任何 Agent 生命周期。
+
+## 安装
+
+要求 Node.js 22+、Pi 0.84.4+：
+
+```bash
+pi install ./xz-pi-worktree
+```
+
+安装后执行 `/reload` 或重启 Pi。
+
+扩展以当前用户权限执行 Git 命令，不是安全沙箱。修改操作仅允许在 Pi 已信任的项目中运行。
+
+## 使用
+
+直接告诉 main：
+
+> 创建一个名为 feature-api 的 Git Worktree。
+
+扩展只注册一个模型工具 `xz_worktree`，支持以下 action：
+
+| action | 必需参数 | 行为 |
+| --- | --- | --- |
+| `create` | `name` | 从当前 HEAD 创建受管 Worktree |
+| `status` | `id` | 查看状态、路径以及是否有修改 |
+| `list` | 无 | 列出当前仓库的受管 Worktree |
+| `capture` | `id` | 捕获 tracked、staged、删除、未跟踪及二进制修改 |
+| `apply` | `id` | 检查并应用 Patch 到主 checkout，成功后清理 |
+| `remove` | `id` | 删除无修改的 Worktree；`force: true` 可丢弃修改 |
+
+`cwd` 可用于 `create/list`，省略时使用 Pi 当前目录。
+
+## 生命周期
+
+典型流程：
+
+1. `create` 返回稳定的 `id`、`worktreePath` 和 `executionCwd`。
+2. 用户或外部程序在 `executionCwd` 中工作。
+3. `capture` 生成二进制 Patch 并返回 `changedFiles`。
+4. `apply` 再次捕获最新修改，要求主 checkout 的 HEAD 未变化且工作区干净。
+5. Patch 通过 `git apply --check` 后应用；成功时删除 Worktree 和临时分支。
+6. 冲突时不修改主 checkout，并保留 Worktree、Patch 和 manifest。
+
+该流程不会 commit、merge 或 rebase。
+
+## 文件位置
+
+Worktree 默认创建在仓库同级目录：
+
+```text
+<repo-parent>/.xz-pi-worktrees/<repo>-<name>-<id前8位>
+```
+
+持久状态和 Patch 位于 Pi agent 目录：
+
+```text
+<agent-dir>/xz-pi-worktree/runs/<id>/
+├── manifest.json
+└── changes.patch
+```
+
+删除 Worktree 不删除 manifest 和 Patch，便于审计和恢复。
+
+## 安全边界
+
+- `create` 要求主仓库干净。
+- `apply` 要求主仓库仍位于创建时的 HEAD，并且工作区干净。
+- `remove` 默认拒绝删除有修改的 Worktree。
+- 只有显式 `force: true` 才丢弃 Worktree 修改。
+- Git 凭据提示被关闭，命令不会等待交互输入。
+- 同一扩展实例中的 Worktree 操作串行执行，避免并行 Git 元数据修改。
+- 状态目录不是长期备份；重要 Patch 应另行保存。
+
+## 与 xz-pi-subagents 的关系
+
+两个包完全独立：
+
+- 不互相依赖或调用
+- 不共享类型或运行时状态
+- 可以单独安装、更新和卸载
+- `xz-pi-subagents` 始终在当前项目目录运行，不会自动进入这里创建的 Worktree
+
+## 开发
+
+从仓库根目录运行：
+
+```bash
+npm run check -w xz-pi-worktree
+npm pack --dry-run -w xz-pi-worktree
+```

package/index.ts

@@ -0,0 +1,82 @@
+import { resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { getAgentDir, truncateHead, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { WorktreeService } from "./src/service.js";
+
+const ACTIONS = ["create", "status", "list", "capture", "apply", "remove"] as const;
+type Action = typeof ACTIONS[number];
+interface ToolInput { action: Action; id?: string; name?: string; cwd?: string; force?: boolean }
+
+function serialQueue() {
+  let tail: Promise<void> = Promise.resolve();
+  return <T>(work: () => Promise<T>): Promise<T> => {
+    const result = tail.then(work, work);
+    tail = result.then(() => undefined, () => undefined);
+    return result;
+  };
+}
+
+function pathFrom(cwd: string, value?: string): string {
+  const normalized = value?.startsWith("@") ? value.slice(1) : value;
+  return resolve(cwd, normalized || ".");
+}
+
+export default function xzPiWorktree(pi: ExtensionAPI): void {
+  const service = new WorktreeService({ stateRoot: resolve(getAgentDir(), "xz-pi-worktree", "runs") });
+  const serial = serialQueue();
+
+  pi.registerTool({
+    name: "xz_worktree",
+    label: "Git worktree",
+    description: "Manage standalone Git worktrees. Actions: create a managed sibling worktree, inspect status, list manifests, capture a binary patch, apply a captured worktree to a clean unchanged main checkout, or remove it. State and patches persist under the Pi agent directory. Mutating actions require a trusted project.",
+    promptSnippet: "Create, inspect, capture, apply, or remove standalone Git worktrees",
+    promptGuidelines: [
+      "Use xz_worktree only for explicit Git worktree lifecycle requests.",
+      "Before xz_worktree apply or remove, preserve the returned id. Never use force removal unless the user accepts discarding remaining worktree changes.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(ACTIONS, { description: "Worktree lifecycle action" }),
+      id: Type.Optional(Type.String({ description: "Managed worktree id; required except for create/list" })),
+      name: Type.Optional(Type.String({ minLength: 1, maxLength: 40, pattern: "^[a-zA-Z0-9_-]+$", description: "Label for create" })),
+      cwd: Type.Optional(Type.String({ description: "Repository path for create/list; defaults to current cwd" })),
+      force: Type.Optional(Type.Boolean({ description: "Allow remove to discard worktree changes" })),
+    }),
+    async execute(_toolCallId, input: ToolInput, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const mutating = input.action !== "status" && input.action !== "list";
+      if (mutating && !ctx.isProjectTrusted()) throw new Error("xz_worktree mutation requires a trusted project");
+      const result = await serial(async () => {
+        signal?.throwIfAborted();
+        if (input.action === "create") {
+          if (!input.name) throw new Error("create requires name");
+          return service.create({ cwd: pathFrom(ctx.cwd, input.cwd), name: input.name }, signal);
+        }
+        if (input.action === "list") return service.list(pathFrom(ctx.cwd, input.cwd), signal);
+        if (!input.id) throw new Error(`${input.action} requires id`);
+        if (input.action === "status") return service.status(input.id, signal);
+        if (input.action === "capture") return service.capture(input.id, signal);
+        if (input.action === "apply") return service.apply(input.id, signal);
+        return service.remove(input.id, input.force ?? false, signal);
+      });
+      const json = JSON.stringify(result, null, 2);
+      const bounded = truncateHead(json, { maxBytes: 50_000, maxLines: 2000 });
+      return {
+        content: [{ type: "text", text: bounded.content + (bounded.truncated ? "\n[Result truncated]" : "") }],
+        details: { action: input.action, result },
+      };
+    },
+    renderCall(args, theme) {
+      const target = args.name ?? args.id ?? args.cwd ?? "";
+      return new Text(theme.fg("toolTitle", `Git worktree · ${args.action}${target ? ` · ${target}` : ""}`), 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      if (isPartial) return new Text(theme.fg("muted", "Git worktree operation running…"), 0, 0);
+      const details = result.details as { action?: string; result?: unknown } | undefined;
+      const summary = details?.action ? `${details.action} completed` : "completed";
+      const body = expanded ? `\n${result.content.filter(item => item.type === "text").map(item => item.text).join("\n")}` : "";
+      return new Text(theme.fg("success", `✓ ${summary}`) + body, 0, 0);
+    },
+  });
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "xz-pi-worktree",
+  "version": "0.1.0",
+  "description": "Standalone Git worktree lifecycle management for Pi",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "git",
+    "worktree"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xuzan9396/xz-pi.git",
+    "directory": "xz-pi-worktree"
+  },
+  "homepage": "https://github.com/Xuzan9396/xz-pi/tree/main/xz-pi-worktree",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test 'test/**/*.test.ts'",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.9.0"
+  }
+}

package/src/git.ts

@@ -0,0 +1,20 @@
+import { execFile } from "node:child_process";
+
+const MAX_GIT_OUTPUT = 64 * 1024 * 1024;
+
+export function git(cwd: string, args: string[], signal?: AbortSignal): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      maxBuffer: MAX_GIT_OUTPUT,
+      windowsHide: true,
+      signal,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    }, (error, stdout, stderr) => {
+      if (error) {
+        const detail = String(stderr).trim();
+        reject(new Error(`${error.message}${detail ? `\n${detail}` : ""}`));
+      } else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}

package/src/service.ts

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { git } from "./git.js";
+import { WorktreeStore } from "./store.js";
+import type { CreateOptions, WorktreeManifest, WorktreeStoreOptions } from "./types.js";
+
+const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,40}$/;
+
+export class WorktreeService {
+  readonly store: WorktreeStore;
+  private readonly worktreeParentName: string;
+
+  constructor(options: WorktreeStoreOptions) {
+    this.store = new WorktreeStore(options.stateRoot);
+    this.worktreeParentName = options.worktreeParentName ?? ".xz-pi-worktrees";
+  }
+
+  async create(options: CreateOptions, signal?: AbortSignal): Promise<WorktreeManifest> {
+    if (!NAME_PATTERN.test(options.name)) throw new Error("Worktree name must be 1–40 letters, digits, underscores, or hyphens");
+    const [{ stdout: rootOut }, { stdout: prefixOut }] = await Promise.all([
+      git(options.cwd, ["rev-parse", "--show-toplevel"], signal),
+      git(options.cwd, ["rev-parse", "--show-prefix"], signal),
+    ]);
+    const repoRoot = rootOut.trim();
+    const { stdout: status } = await git(repoRoot, ["status", "--porcelain", "--untracked-files=all"], signal);
+    if (status.trim()) throw new Error("Creating a managed worktree requires a clean Git checkout. Commit or stash existing changes first.");
+    const { stdout: baseOut } = await git(repoRoot, ["rev-parse", "HEAD"], signal);
+    const id = randomUUID();
+    const suffix = `${options.name}-${id.slice(0, 8)}`;
+    const parent = join(dirname(repoRoot), this.worktreeParentName);
+    const worktreePath = join(parent, `${basename(repoRoot)}-${suffix}`);
+    const runDir = this.store.runDir(id);
+    const now = new Date().toISOString();
+    const manifest: WorktreeManifest = {
+      version: 1,
+      id,
+      name: options.name,
+      repoRoot,
+      sourcePrefix: prefixOut.trim(),
+      worktreePath,
+      executionCwd: join(worktreePath, prefixOut.trim()),
+      branch: `xz-pi-worktree/${suffix}`,
+      baseCommit: baseOut.trim(),
+      patchPath: join(runDir, "changes.patch"),
+      changedFiles: [],
+      status: "created",
+      createdAt: now,
+      updatedAt: now,
+    };
+    await Promise.all([
+      mkdir(parent, { recursive: true, mode: 0o700 }),
+      mkdir(runDir, { recursive: true, mode: 0o700 }),
+    ]);
+    try {
+      await git(repoRoot, ["worktree", "add", "-b", manifest.branch, worktreePath, manifest.baseCommit], signal);
+      await this.store.save(manifest);
+      return manifest;
+    } catch (error) {
+      if (existsSync(worktreePath)) await git(repoRoot, ["worktree", "remove", "--force", worktreePath]).catch(() => {});
+      await git(repoRoot, ["branch", "-D", manifest.branch]).catch(() => {});
+      await rm(runDir, { recursive: true, force: true }).catch(() => {});
+      throw error;
+    }
+  }
+
+  async status(id: string, signal?: AbortSignal): Promise<WorktreeManifest & { worktreeExists: boolean; dirty: boolean }> {
+    const manifest = await this.store.load(id);
+    const worktreeExists = existsSync(manifest.worktreePath);
+    let dirty = false;
+    if (worktreeExists) {
+      const result = await git(manifest.worktreePath, ["status", "--porcelain", "--untracked-files=all"], signal);
+      dirty = Boolean(result.stdout.trim());
+    }
+    return { ...manifest, worktreeExists, dirty };
+  }
+
+  async list(cwd?: string, signal?: AbortSignal): Promise<WorktreeManifest[]> {
+    const manifests = await this.store.list();
+    if (!cwd) return manifests;
+    const { stdout } = await git(cwd, ["rev-parse", "--show-toplevel"], signal);
+    const root = stdout.trim();
+    return manifests.filter(manifest => manifest.repoRoot === root);
+  }
+
+  async capture(id: string, signal?: AbortSignal): Promise<WorktreeManifest> {
+    const manifest = await this.store.load(id);
+    this.requireLive(manifest);
+    await git(manifest.worktreePath, ["add", "-N", "--all"], signal);
+    const [{ stdout: patch }, { stdout: names }] = await Promise.all([
+      git(manifest.worktreePath, ["diff", "--binary", "--no-ext-diff", manifest.baseCommit, "--"], signal),
+      git(manifest.worktreePath, ["diff", "--name-only", "-z", manifest.baseCommit, "--"], signal),
+    ]);
+    manifest.changedFiles = names.split("\0").filter(Boolean);
+    manifest.status = manifest.changedFiles.length ? "captured" : "no_changes";
+    manifest.error = undefined;
+    await writeFile(manifest.patchPath, patch, { mode: 0o600 });
+    await this.store.save(manifest);
+    return manifest;
+  }
+
+  async apply(id: string, signal?: AbortSignal): Promise<WorktreeManifest> {
+    const manifest = await this.capture(id, signal);
+    if (!manifest.changedFiles.length) {
+      manifest.status = "no_changes";
+      await this.cleanup(manifest, signal);
+      await this.store.save(manifest);
+      return manifest;
+    }
+    try {
+      const [{ stdout: headOut }, { stdout: mainStatus }] = await Promise.all([
+        git(manifest.repoRoot, ["rev-parse", "HEAD"], signal),
+        git(manifest.repoRoot, ["status", "--porcelain", "--untracked-files=all"], signal),
+      ]);
+      if (headOut.trim() !== manifest.baseCommit) throw new Error("Main HEAD changed after the managed worktree was created");
+      if (mainStatus.trim()) throw new Error("Applying a managed worktree requires a clean main checkout");
+      const patch = await readFile(manifest.patchPath);
+      if (!patch.length) throw new Error("Captured patch is empty despite changed files");
+      await git(manifest.repoRoot, ["apply", "--check", manifest.patchPath], signal);
+      await git(manifest.repoRoot, ["apply", manifest.patchPath], signal);
+    } catch (error) {
+      manifest.status = "conflict";
+      manifest.error = String(error);
+      await this.store.save(manifest);
+      throw new Error(`Worktree patch was not applied; worktree and patch preserved. ${String(error)}`);
+    }
+    manifest.status = "applied";
+    manifest.error = undefined;
+    try {
+      await this.store.save(manifest);
+      await this.cleanup(manifest, signal);
+      await this.store.save(manifest);
+      return manifest;
+    } catch (error) {
+      manifest.error = `Patch applied, but finalization failed: ${String(error)}`;
+      await this.store.save(manifest).catch(() => {});
+      throw new Error(manifest.error);
+    }
+  }
+
+  async remove(id: string, force = false, signal?: AbortSignal): Promise<WorktreeManifest> {
+    const manifest = await this.store.load(id);
+    if (existsSync(manifest.worktreePath) && !force) {
+      const { stdout } = await git(manifest.worktreePath, ["status", "--porcelain", "--untracked-files=all"], signal);
+      if (stdout.trim()) throw new Error("Worktree has changes. Capture/apply them first or set force: true.");
+    }
+    await this.cleanup(manifest, signal, force);
+    if (manifest.cleanupError) throw new Error(`Worktree cleanup incomplete: ${manifest.cleanupError}`);
+    manifest.status = "removed";
+    manifest.error = undefined;
+    await this.store.save(manifest);
+    return manifest;
+  }
+
+  private requireLive(manifest: WorktreeManifest): void {
+    if (!existsSync(manifest.worktreePath)) throw new Error(`Managed worktree no longer exists: ${manifest.worktreePath}`);
+    if (manifest.status === "applied" || manifest.status === "removed") throw new Error(`Worktree is already ${manifest.status}`);
+  }
+
+  private async cleanup(manifest: WorktreeManifest, signal?: AbortSignal, force = true): Promise<void> {
+    const errors: string[] = [];
+    if (existsSync(manifest.worktreePath)) {
+      const args = ["worktree", "remove", ...(force ? ["--force"] : []), manifest.worktreePath];
+      try { await git(manifest.repoRoot, args, signal); }
+      catch (error) { errors.push(`worktree remove: ${String(error)}`); }
+    }
+    try { await git(manifest.repoRoot, ["branch", "-D", manifest.branch], signal); }
+    catch (error) {
+      const branches = await git(manifest.repoRoot, ["branch", "--list", manifest.branch], signal).catch(() => ({ stdout: manifest.branch, stderr: "" }));
+      if (branches.stdout.trim()) errors.push(`branch delete: ${String(error)}`);
+    }
+    try { await rm(dirname(manifest.worktreePath), { recursive: false }); } catch { /* Shared parent remains while non-empty. */ }
+    manifest.cleanupError = errors.length ? errors.join("\n") : undefined;
+  }
+}

package/src/store.ts

@@ -0,0 +1,46 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { WorktreeManifest } from "./types.js";
+
+const ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export class WorktreeStore {
+  constructor(readonly root: string) {}
+
+  runDir(id: string): string {
+    if (!ID_PATTERN.test(id)) throw new Error("Invalid worktree id");
+    return join(this.root, id);
+  }
+
+  manifestPath(id: string): string {
+    return join(this.runDir(id), "manifest.json");
+  }
+
+  async save(manifest: WorktreeManifest): Promise<void> {
+    manifest.updatedAt = new Date().toISOString();
+    const dir = this.runDir(manifest.id);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(this.manifestPath(manifest.id), JSON.stringify(manifest, null, 2), { mode: 0o600 });
+  }
+
+  async load(id: string): Promise<WorktreeManifest> {
+    const value = JSON.parse(await readFile(this.manifestPath(id), "utf8")) as WorktreeManifest;
+    if (value.version !== 1 || value.id !== id) throw new Error(`Invalid manifest for worktree ${id}`);
+    return value;
+  }
+
+  async list(): Promise<WorktreeManifest[]> {
+    let entries;
+    try { entries = await readdir(this.root, { withFileTypes: true }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+    const manifests: WorktreeManifest[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !ID_PATTERN.test(entry.name)) continue;
+      try { manifests.push(await this.load(entry.name)); } catch { /* Ignore corrupt entries in list; direct status reports them. */ }
+    }
+    return manifests.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+export type WorktreeStatus = "created" | "captured" | "applied" | "no_changes" | "conflict" | "removed";
+
+export interface WorktreeManifest {
+  version: 1;
+  id: string;
+  name: string;
+  repoRoot: string;
+  sourcePrefix: string;
+  worktreePath: string;
+  executionCwd: string;
+  branch: string;
+  baseCommit: string;
+  patchPath: string;
+  changedFiles: string[];
+  status: WorktreeStatus;
+  createdAt: string;
+  updatedAt: string;
+  cleanupError?: string;
+  error?: string;
+}
+
+export interface CreateOptions {
+  cwd: string;
+  name: string;
+}
+
+export interface WorktreeStoreOptions {
+  stateRoot: string;
+  worktreeParentName?: string;
+}