@davideasden/pi-undo 0.2.6 → 0.2.8

package/README.md

@@ -15,7 +15,7 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 - **External concurrency detection** — file fingerprint and inode checks detect external modification. Conflicting changes are never silently overwritten; the system fails closed or enters `recovery required`.
 - **No Git workflow** — snapshots use a private object database. No `git commit`, `git stash`, `git reset`, branches, or forges are required.
 - **Nested repositories** and **initialized submodules** are handled as independent roots. Their `.git` metadata is never modified.
-- **Performance** — batch WAL operations (up to 1,024 files per batch), scoped safety snapshots, prebuilt durable transaction packs, native Rust no-clobber file helper for macOS arm64, indexed WAL record and conflict lookups, and parallel manifest blob reads keep restore fast at scale. Unsupported platforms and failed integrity checks automatically use the TypeScript path.
+- **Performance** — batch WAL operations (up to 1,024 files per batch), scoped safety snapshots, prebuilt durable transaction packs, native Rust no-clobber file helper (macOS/Linux, arm64/x64), indexed WAL record and conflict lookups, and parallel manifest blob reads keep restore fast at scale. Unsupported platforms and failed integrity checks automatically use the TypeScript fallback.
 
 ## Requirements
 
@@ -23,28 +23,47 @@ Each completed agent run creates a checkpoint that captures both the Pi session
 - Node.js `22.19.0` or later.
 - Git available on `PATH` (used internally for content-addressed snapshots).
 
+### Rust 原生加速
+
+pi-undo 包含跨平台 Rust 原生 helper（`pi-undo-fs`），用于加速文件系统操作。发布包会同时包含以下六个预编译二进制：
+
+| 平台 | 架构 | 二进制名称 |
+|---|---|---|
+| macOS | arm64 | `pi-undo-fs-darwin-arm64` |
+| macOS | x64 | `pi-undo-fs-darwin-x64` |
+| Linux | arm64 | `pi-undo-fs-linux-arm64` |
+| Linux | x64 | `pi-undo-fs-linux-x64` |
+| Windows | arm64 | `pi-undo-fs-win32-arm64.exe` |
+| Windows | x64 | `pi-undo-fs-win32-x64.exe` |
+
+扩展会根据当前运行环境自动选择对应二进制，因此用户无需安装 Rust，也无需手动选择平台。Windows 二进制带有 `.exe` 后缀。对于尚未提供预编译二进制的平台，扩展会自动回退到 TypeScript 路径，功能仍然可用。
+
 ## Installation
 
-Install the published package from npm:
+### 从 npm 安装（推荐）
+
+所有受支持的平台使用同一个安装命令；npm 包会包含 macOS/Linux/Windows 的 arm64/x64 预编译 Rust helper，扩展启动时自动选择当前平台的版本：
 
 ```bash
 pi install npm:@davideasden/pi-undo
 ```
 
-Restart Pi if the extension is not already loaded.
+重启 Pi 即可加载扩展。用户不需要安装 Rust，也不需要手动选择或安装平台专用包。
 
-To install from a local checkout:
+### 从本地源码安装
 
 ```bash
 pi install /path/to/pi-undo
 ```
 
-During development, load the extension directly:
+### 开发模式直接加载
 
 ```bash
 pi -e /absolute/path/to/pi-undo/extensions/pi-undo.ts
 ```
 
+> **注意**：`pi install` 会将整个包（包括 `native/bin/` 下的预编译二进制）复制到 Pi 的扩展目录。如果你从源码构建后想要包含新编译的原生二进制，确保运行 `npm run build:native` 后再执行 `pi install`。
+
 ## Usage
 
 Work with Pi normally. `pi-undo` automatically records a boundary after each completed agent run.
@@ -227,6 +246,8 @@ A transaction directory may contain `descriptor.json`, `restore-plan.json`, `sta
 
 ## Development
 
+### 依赖
+
 Clone the repository and install dependencies:
 
 ```bash
@@ -235,6 +256,25 @@ cd pi-undo
 npm install
 ```
 
+### 构建 Rust 原生 helper
+
+如果需要构建或更新原生二进制，确保已安装 [Rust 工具链](https://rustup.rs/)：
+
+```bash
+npm run build:native
+```
+
+`npm run build:native` 会在 `native/pi-undo-fs/target/release/` 下生成当前构建平台的 `pi-undo-fs`。发布流程会在 macOS、Linux 和 Windows runner 上分别构建 arm64/x64 版本，统一重命名后放入 `native/bin/`，再打包成包含六个二进制的 npm 包。
+
+本地开发时，如果只需要验证当前平台，可以将生成的文件复制到 `native/bin/` 并按平台重命名，例如：Windows 生成的文件应使用对应的 `.exe` 文件名。
+
+```bash
+cp native/pi-undo-fs/target/release/pi-undo-fs native/bin/pi-undo-fs-darwin-arm64
+chmod +x native/bin/pi-undo-fs-darwin-arm64
+```
+
+发布包必须包含 Requirements 中列出的六个平台二进制；CI 会在打包前检查这一点，并在推送 `v*` tag 时发布该 CI 构建的完整 npm 包。npm 仓库需要为此 GitHub Actions workflow 配置 npm Trusted Publishing（OIDC）。如果当前平台没有对应二进制，扩展会自动使用 TypeScript 回退路径。
+
 ### Project Layout
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davideasden/pi-undo",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "Persistent workspace undo and redo for Pi",
 	"type": "module",
 	"keywords": [

package/src/durable-pack.ts

@@ -6,7 +6,7 @@ import { fsyncDirectory, fsyncFile } from "./atomic-fs.ts";
 import { canonicalJson, checksum } from "./encoding.ts";
 import type { MutationJournal } from "./mutation-journal.ts";
 import { assertNoSymlinkEscape, relativeSafePath } from "./path-safety.ts";
-import { fingerprintAbsent, fingerprintBytes, fingerprintFile, fingerprintSymlink } from "./quarantine.ts";
+import { fingerprintAbsent, fingerprintBytes, fingerprintFile, fingerprintLeaf, fingerprintSymlink } from "./quarantine.ts";
 
 const PACK_FILE = "durable-pack-v1.bin";
 const MAGIC = Buffer.from("PIUNDO-PACK-V1\0", "ascii");
@@ -315,13 +315,36 @@ export async function finalizeDurablePack(
 	const directories = new Set<string>();
 	await mapConcurrent(pack.paths(), FINALIZE_CONCURRENCY, async (path) => {
 		const targetFingerprint = pack.targetFingerprint(path);
-		if (targetFingerprint === undefined || targetFingerprint === null) return;
-		const leaf = pack.leaf(path, targetFingerprint);
-		if (leaf === undefined || leaf.kind === "absent") throw new Error(`durable pack target leaf 缺失：${path}`);
+		const targetLeaf = targetFingerprint === undefined || targetFingerprint === null
+			? undefined
+			: pack.leaf(path, targetFingerprint);
 		relativeSafePath(canonicalRoot, path);
 		await assertNoSymlinkEscape(canonicalRoot, path);
 		const absolute = join(canonicalRoot, ...path.split("/"));
 		directories.add(dirname(absolute));
+		if (targetLeaf?.kind === "absent") {
+			if (await fingerprintLeaf(absolute, path) !== fingerprintAbsent(path)) {
+				throw new Error(`durable finalization delete 原路径不是 absent：${path}`);
+			}
+			const sourceFingerprint = pack.sourceFingerprint(path);
+			const sourceArtifact = pack.artifacts(path)?.source;
+			if (sourceFingerprint === undefined || sourceArtifact === undefined) {
+				throw new Error(`durable finalization delete source 缺失：${path}`);
+			}
+			const sourcePath = join(canonicalRoot, ...sourceArtifact.split("/"));
+			try {
+				if (await fingerprintFile(sourcePath, path) !== sourceFingerprint) {
+					throw new Error(`durable finalization delete source fingerprint 冲突：${path}`);
+				}
+				await fsyncFile(sourcePath);
+				directories.add(dirname(sourcePath));
+			} catch (error) {
+				if (!hasErrorCode(error, "ENOENT") || mutationStates?.get(path) !== "CLEANED") throw error;
+			}
+			return;
+		}
+		const leaf = targetLeaf;
+		if (leaf === undefined) throw new Error(`durable pack target leaf 缺失：${path}`);
 		if (leaf.kind === "file") {
 			const artifacts = pack.artifacts(path);
 			if (artifacts?.target === null || artifacts?.target === undefined) {

package/src/native-restore.ts

@@ -48,10 +48,8 @@ export async function createNativeFileBatch(options: {
 				const targetFingerprint = pack.targetFingerprint(path);
 				if (
 					artifacts === undefined ||
-					artifacts.target === null ||
 					sourceFingerprint === undefined ||
-					targetFingerprint === undefined ||
-					targetFingerprint === null
+					targetFingerprint === undefined
 				) {
 					throw new Error(`native file batch pack entry 无效：${path}`);
 				}
@@ -84,10 +82,12 @@ export async function createNativeFileBatch(options: {
 function nativeExecutable(): string | undefined {
 	const platform = process.platform === "darwin"
 		? "darwin"
-		: process.platform === "linux" ? "linux" : undefined;
+		: process.platform === "linux" ? "linux"
+		: process.platform === "win32" ? "win32" : undefined;
 	const architecture = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "x64" : undefined;
 	if (platform === undefined || architecture === undefined) return undefined;
-	return fileURLToPath(new URL(`../native/bin/pi-undo-fs-${platform}-${architecture}`, import.meta.url));
+	const extension = process.platform === "win32" ? ".exe" : "";
+	return fileURLToPath(new URL(`../native/bin/pi-undo-fs-${platform}-${architecture}${extension}`, import.meta.url));
 }
 
 function runNative(executable: string, requestPath: string, expected: number): Promise<void> {

package/src/packed-recovery.ts

@@ -44,20 +44,28 @@ export async function recoverPackedMutations(options: {
 		const pack = await loadDurablePack(options.journal, options.planDigest, true);
 		const records = await ensurePackedIntents(options.journal, pack, await options.journal.load());
 		await mapConcurrent(records, PACKED_RECOVERY_CONCURRENCY, async (record) => {
-			if (record.kind !== "write" || record.targetArtifact === null) throw new Error("packed recovery 只支持普通文件 write");
+			if (record.state === "CLEANED" && record.kind === "delete") {
+				if (options.decision === "rollback") {
+					throw new Error(`CLEANED delete mutation 不能 rollback：${record.path}`);
+				}
+				return;
+			}
 			const source = pack.leaf(record.path, record.sourceFingerprint);
 			const target = pack.leaf(record.path, record.targetFingerprint);
-			if (source === undefined || target === undefined || target.kind !== "file") {
+			if (source === undefined || target === undefined) {
 				throw new Error(`packed recovery variant 缺失：${record.path}`);
 			}
-			await normalizeRecord(
-				workspaceRoot,
-				record,
-				source,
-				target,
-				options.decision,
-				options.retainArtifacts === true,
-			);
+			if (record.kind === "delete") {
+				if (record.targetArtifact !== null || source.kind !== "file" || target.kind !== "absent") {
+					throw new Error(`packed recovery delete variant 无效：${record.path}`);
+				}
+				await normalizeDeletedRecord(workspaceRoot, record, source, options.decision, options.retainArtifacts === true);
+				return;
+			}
+			if (record.kind !== "write" || record.targetArtifact === null || target.kind !== "file") {
+				throw new Error(`packed recovery write variant 无效：${record.path}`);
+			}
+			await normalizeRecord(workspaceRoot, record, source, target, options.decision, options.retainArtifacts === true);
 		});
 		const terminalState: MutationState = options.retainArtifacts === true ? "TARGET_VERIFIED" : "CLEANED";
 		const terminalIndex = stateOrder.indexOf(terminalState);
@@ -87,20 +95,29 @@ export async function cleanupPackedMutations(options: {
 	const records = [...await options.journal.load()];
 	const cleanupDirectories = new Set<string>();
 	await mapConcurrent(records, PACKED_RECOVERY_CONCURRENCY, async (record) => {
-		if (
-			(record.state !== "TARGET_VERIFIED" && record.state !== "CLEANED") ||
-			record.kind !== "write" ||
-			record.targetArtifact === null
-		) {
+		if (record.state !== "TARGET_VERIFIED" && record.state !== "CLEANED") {
 			throw new Error(`packed cleanup mutation 状态无效：${record.path}`);
 		}
 		relativeSafePath(workspaceRoot, record.path);
 		await assertNoSymlinkEscape(workspaceRoot, record.path);
 		const original = join(workspaceRoot, ...record.path.split("/"));
 		const sourceArtifact = join(workspaceRoot, ...record.sourceArtifact.split("/"));
-		const targetArtifact = join(workspaceRoot, ...record.targetArtifact.split("/"));
 		const source = pack.leaf(record.path, record.sourceFingerprint);
 		if (source === undefined) throw new Error(`packed cleanup source variant 缺失：${record.path}`);
+		if (record.kind === "delete") {
+			if (record.targetArtifact !== null || pack.targetFingerprint(record.path) !== fingerprintAbsent(record.path)) {
+				throw new Error(`packed cleanup delete mutation 无效：${record.path}`);
+			}
+			if (await fingerprintLeaf(original, record.path) !== fingerprintAbsent(record.path)) {
+				throw new Error(`packed cleanup delete original 不是 absent：${record.path}`);
+			}
+			await cleanupArtifact(sourceArtifact, record.path, record.sourceFingerprint, cleanupDirectories);
+			return;
+		}
+		if (record.kind !== "write" || record.targetArtifact === null) {
+			throw new Error(`packed cleanup write mutation 无效：${record.path}`);
+		}
+		const targetArtifact = join(workspaceRoot, ...record.targetArtifact.split("/"));
 		if (await pathExists(targetArtifact)) {
 			await assertSameFileIdentity(original, targetArtifact, record.path);
 		} else if (record.state !== "CLEANED") {
@@ -140,22 +157,18 @@ function packedIntent(pack: DurablePack, path: string) {
 	const artifacts = pack.artifacts(path);
 	const sourceFingerprint = pack.sourceFingerprint(path);
 	const targetFingerprint = pack.targetFingerprint(path);
-	if (
-		artifacts === undefined ||
-		artifacts.target === null ||
-		sourceFingerprint === undefined ||
-		targetFingerprint === undefined ||
-		targetFingerprint === null
-	) {
+	if (artifacts === undefined || sourceFingerprint === undefined || targetFingerprint === undefined) {
 		throw new Error(`packed recovery intent 缺失：${path}`);
 	}
 	return {
-		kind: "write" as const,
+		kind: artifacts.target === null && (targetFingerprint === null || targetFingerprint === fingerprintAbsent(path))
+			? "delete" as const
+			: "write" as const,
 		path,
 		sourceArtifact: artifacts.source,
 		targetArtifact: artifacts.target,
 		sourceFingerprint,
-		targetFingerprint,
+		targetFingerprint: targetFingerprint ?? fingerprintAbsent(path),
 	};
 }
 
@@ -173,6 +186,35 @@ function assertPackedRecord(pack: DurablePack, path: string, record: MutationRec
 	}
 }
 
+async function normalizeDeletedRecord(
+	workspaceRoot: string,
+	record: MutationRecord,
+	source: DurableLeaf,
+	decision: "rollback" | "roll_forward",
+	retainArtifacts: boolean,
+): Promise<void> {
+	if (source.kind !== "file" || record.targetArtifact !== null) {
+		throw new Error(`delete mutation variant 无效：${record.path}`);
+	}
+	relativeSafePath(workspaceRoot, record.path);
+	await assertNoSymlinkEscape(workspaceRoot, record.path);
+	const original = join(workspaceRoot, ...record.path.split("/"));
+	const sourceArtifact = join(workspaceRoot, ...record.sourceArtifact.split("/"));
+	const absent = fingerprintAbsent(record.path);
+	const observed = await fingerprintLeaf(original, record.path);
+	if (observed !== absent && observed !== record.sourceFingerprint) {
+		throw new Error(`delete mutation original 冲突：${record.path}`);
+	}
+	await assertArtifact(sourceArtifact, record.path, record.sourceFingerprint, false);
+	if (decision === "rollback") {
+		if (observed === absent) await materialize(original, record.path, source);
+		if (!retainArtifacts) await cleanupArtifact(sourceArtifact, record.path, record.sourceFingerprint);
+		return;
+	}
+	if (observed !== absent) throw new Error(`delete mutation roll-forward original 未删除：${record.path}`);
+	if (!retainArtifacts) await cleanupArtifact(sourceArtifact, record.path, record.sourceFingerprint);
+}
+
 async function normalizeRecord(
 	workspaceRoot: string,
 	record: MutationRecord,

package/src/pi-runtime.ts

@@ -4,7 +4,6 @@ import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
-	ReadonlySessionManager,
 } from "@earendil-works/pi-coding-agent";
 
 import {
@@ -30,6 +29,8 @@ import { SnapshotStore } from "./snapshot-store.ts";
 import { StatusReporter } from "./status-reporter.ts";
 import { WorkspaceLock } from "./workspace-lock.ts";
 
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+
 export async function createPiUndoRuntime(context: ExtensionContext, pi: ExtensionAPI) {
 	const manager = context.sessionManager;
 	const sessionState = sessionStateFor(manager);

package/src/restore-engine.ts

@@ -253,7 +253,7 @@ export class RestoreEngine {
 	): Promise<void> {
 		const plan = await this.plan(current, target, scopePaths);
 		const prepared = this.takePreparedPlan(plan);
-		if (prepared === undefined || !this.canUseNativeFilePlan(plan, prepared.targetPaths)) return;
+		if (prepared === undefined || !this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
 		const cacheRoot = await this.store.durableCacheDirectory();
 		const cacheOpId = `cache-${plan.planDigest}`;
 		const cacheJournal = new MutationJournal(
@@ -528,7 +528,7 @@ export class RestoreEngine {
 			!compatibilityMode &&
 			options.deferDurability === true &&
 			options.forceTargetArtifactSync !== true &&
-			this.canUseNativeFilePlan(plan, targetPaths)
+			this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
 		) {
 			try {
 				const cached = this.durablePackCache.get(plan.planDigest);
@@ -574,7 +574,7 @@ export class RestoreEngine {
 			);
 		}
 		const durablePackEnabled = durablePack !== undefined;
-		if (nativeFileBatch !== undefined && durablePack !== undefined && this.canUseNativeFilePlan(plan, targetPaths)) {
+		if (nativeFileBatch !== undefined && durablePack !== undefined && this.canUseNativeFilePlan(plan, currentPaths, targetPaths)) {
 			const result = await this.applyNativeFilePlan(
 				plan,
 				current,
@@ -661,11 +661,20 @@ export class RestoreEngine {
 
 	private canUseNativeFilePlan(
 		plan: RestorePlan,
+		currentPaths: ReadonlyMap<string, OwnedPath>,
 		targetPaths: ReadonlyMap<string, OwnedPath>,
 	): boolean {
-		return plan.deletePaths.length === 0 &&
+		const writeOnly = plan.deletePaths.length === 0 &&
 			plan.writePaths.length > 0 &&
 			plan.writePaths.every((path) => targetPaths.get(path)?.entry.kind === "file");
+		const deleteOnly = process.platform !== "win32" &&
+			plan.writePaths.length === 0 &&
+			plan.deletePaths.length > 0 &&
+			plan.deletePaths.every((path) =>
+				currentPaths.get(path)?.entry.kind === "file" &&
+				targetPaths.get(path) === undefined &&
+				!path.includes("/"));
+		return writeOnly || deleteOnly;
 	}
 
 	private async applyNativeFilePlan(
@@ -694,10 +703,11 @@ export class RestoreEngine {
 						: [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
 				}),
 			);
+			const totalPaths = plan.deletePaths.length + plan.writePaths.length;
 			if ((await options.mutationJournal.load()).length !== 0) {
-				return { code: "recovery_required", verifiedPaths: 0, totalPaths: plan.writePaths.length };
+				return { code: "recovery_required", verifiedPaths: 0, totalPaths };
 			}
-			return { code: "ok", verifiedPaths: plan.writePaths.length, totalPaths: plan.writePaths.length };
+			return { code: "ok", verifiedPaths: totalPaths, totalPaths };
 		} catch {
 			const packedRecovery = await recoverPackedMutations({
 				workspaceRoot: this.workspaceRoot,
@@ -706,7 +716,11 @@ export class RestoreEngine {
 				decision: "rollback",
 			});
 			if (packedRecovery.kind !== "clean") {
-				return { code: "recovery_required", verifiedPaths: 0, totalPaths: plan.writePaths.length };
+				return {
+					code: "recovery_required",
+					verifiedPaths: 0,
+					totalPaths: plan.deletePaths.length + plan.writePaths.length,
+				};
 			}
 			return this.rollback(
 				current,
@@ -761,7 +775,7 @@ export class RestoreEngine {
 				sourceArtifact: artifact("source"),
 				targetArtifact: targetLeaf?.kind === "file" ? artifact("target") : null,
 				sourceFingerprint: currentLeaf?.fingerprint ?? absent.fingerprint,
-				targetFingerprint: targetLeaf?.fingerprint ?? null,
+				targetFingerprint: targetLeaf?.fingerprint ?? absent.fingerprint,
 				variants: [...variants.values()],
 			});
 		}