@davideasden/pi-undo 0.1.1 → 0.2.0

package/src/diff-ui.ts

@@ -0,0 +1,116 @@
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { renderDiff } from "@earendil-works/pi-coding-agent";
+import { type Component, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { buildFileLabel, type FileDiff, sanitizeDisplayText } from "./diff-view.ts";
+
+const CLOSE_LABEL = "← Close";
+
+/**
+ * 在 TUI 中交互浏览一次 Agent run 的逐文件 diff：
+ * 上层 select 列出改动文件，选中后用可滚动彩色查看器展示该文件 diff，返回后回到列表。
+ */
+export async function browseDiff(context: ExtensionCommandContext, title: string, diffs: readonly FileDiff[]): Promise<void> {
+	const labels = new Map<string, FileDiff>();
+	const options: string[] = [];
+	for (const diff of diffs) {
+		const label = uniqueLabel(buildFileLabel(diff), labels);
+		labels.set(label, diff);
+		options.push(label);
+	}
+	options.push(CLOSE_LABEL);
+
+	for (;;) {
+		const choice = await context.ui.select(title, options);
+		if (choice === undefined || choice === CLOSE_LABEL) return;
+		const diff = labels.get(choice);
+		if (diff === undefined) return;
+		await showFileDiff(context, diff);
+	}
+}
+
+function uniqueLabel(label: string, used: ReadonlyMap<string, FileDiff>): string {
+	if (!used.has(label)) return label;
+	let index = 2;
+	while (used.has(`${label} (${index})`)) index += 1;
+	return `${label} (${index})`;
+}
+
+async function showFileDiff(context: ExtensionCommandContext, diff: FileDiff): Promise<void> {
+	await context.ui.custom<void>((tui, theme, _keybindings, done) => new DiffViewer(tui, theme, diff, done), {
+		overlay: true,
+		overlayOptions: { width: "90%", maxHeight: "90%" },
+	});
+}
+
+/** 只读、可滚动的单文件 diff 查看器；不修改任何会话或存储状态。 */
+class DiffViewer implements Component {
+	private readonly lines: readonly string[];
+	private offset = 0;
+
+	constructor(
+		private readonly tui: { requestRender(force?: boolean): void },
+		private readonly theme: Theme,
+		private readonly diff: FileDiff,
+		private readonly done: (result: void) => void,
+	) {
+		this.lines = this.buildLines();
+	}
+
+	invalidate(): void {}
+
+	private buildLines(): string[] {
+		if (this.diff.kind === "binary") return [this.theme.fg("dim", "Binary file changed; line-by-line diff unavailable.")];
+		if (this.diff.diff === "") return [this.theme.fg("dim", "No textual change (mode or type only).")];
+		return renderDiff(this.diff.diff).split("\n");
+	}
+
+	private viewportRows(): number {
+		const rows = process.stdout.rows ?? 24;
+		// 预留 overlay 边框、标题、footer 的空间。
+		return Math.max(3, Math.min(this.lines.length, rows - 8));
+	}
+
+	private maxOffset(): number {
+		return Math.max(0, this.lines.length - this.viewportRows());
+	}
+
+	handleInput(data: string): void {
+		const rows = this.viewportRows();
+		const previous = this.offset;
+		if (matchesKey(data, "escape") || matchesKey(data, "q") || matchesKey(data, "enter")) {
+			this.done();
+			return;
+		}
+		if (matchesKey(data, "up") || matchesKey(data, "k")) this.offset -= 1;
+		else if (matchesKey(data, "down") || matchesKey(data, "j")) this.offset += 1;
+		else if (matchesKey(data, "pageUp")) this.offset -= rows;
+		else if (matchesKey(data, "pageDown") || matchesKey(data, "space")) this.offset += rows;
+		else if (matchesKey(data, "home") || matchesKey(data, "g")) this.offset = 0;
+		else if (matchesKey(data, "end") || matchesKey(data, "shift+g")) this.offset = this.maxOffset();
+		this.offset = Math.max(0, Math.min(this.maxOffset(), this.offset));
+		if (this.offset !== previous) this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const rows = this.viewportRows();
+		// 终端 resize 会改变 viewportRows，重绘时必须重新夹紧滚动位置。
+		this.offset = Math.max(0, Math.min(this.maxOffset(), this.offset));
+		const stats = this.diff.kind === "binary"
+			? "binary"
+			: `+${this.diff.additions} -${this.diff.deletions}`;
+		const safePath = sanitizeDisplayText(this.diff.path, 240);
+		const header = truncateToWidth(this.theme.fg("accent", `${this.diff.status.toUpperCase()} ${safePath}`) + this.theme.fg("dim", `  ${stats}`), width);
+		const out: string[] = [header, this.theme.fg("borderMuted", "─".repeat(Math.min(width, 80)))];
+		const visible = this.lines.slice(this.offset, this.offset + rows);
+		for (const line of visible) {
+			out.push(visibleWidth(line) > width ? truncateToWidth(line, width) : line);
+		}
+		for (let index = visible.length; index < rows; index += 1) out.push("");
+		const position = this.lines.length <= rows
+			? "all"
+			: `${this.offset + 1}-${Math.min(this.offset + rows, this.lines.length)}/${this.lines.length}`;
+		out.push(this.theme.fg("dim", `↑↓/PgUp/PgDn scroll · ${position} · Esc/q close`));
+		return out;
+	}
+}

package/src/diff-view.ts

@@ -0,0 +1,169 @@
+import { generateDiffString } from "@earendil-works/pi-coding-agent";
+
+import type { ManifestId, RestorePath, SnapshotManifest } from "./model.ts";
+
+/** SnapshotStore 的只读子集；/diff 只需要读取 manifest 与 blob，不触碰任何恢复路径。 */
+export interface DiffSource {
+	loadManifest(id: ManifestId): Promise<SnapshotManifest>;
+	listTree(id: ManifestId, root: string): Promise<readonly RestorePath[]>;
+	readBlob(id: ManifestId, root: string, blobId: string): Promise<Uint8Array>;
+}
+
+export type FileDiffStatus = "added" | "deleted" | "modified";
+export type FileDiffKind = "text" | "binary" | "symlink";
+
+export interface FileDiff {
+	readonly path: string;
+	readonly status: FileDiffStatus;
+	readonly kind: FileDiffKind;
+	readonly additions: number;
+	readonly deletions: number;
+	/** 带行号的展示 diff；二进制文件或无逐行差异时为空字符串。 */
+	readonly diff: string;
+}
+
+export interface CheckpointDiffRequest {
+	readonly beforeManifestId: ManifestId;
+	readonly afterManifestId: ManifestId;
+	readonly changedPaths: readonly string[];
+}
+
+interface LeafEntry {
+	readonly rootPath: string;
+	readonly entry: RestorePath;
+}
+
+interface LeafContent {
+	readonly binary: boolean;
+	readonly symlink: boolean;
+	readonly text: string;
+}
+
+/**
+ * 基于 checkpoint 的 before/after 快照计算逐文件 diff。
+ * changedPaths 中的目录项与两侧都不存在的路径会被跳过，只保留叶子文件与符号链接。
+ */
+export async function computeCheckpointDiff(
+	source: DiffSource,
+	request: CheckpointDiffRequest,
+): Promise<FileDiff[]> {
+	const [before, after] = await Promise.all([
+		source.loadManifest(request.beforeManifestId),
+		source.loadManifest(request.afterManifestId),
+	]);
+	const [beforePaths, afterPaths] = await Promise.all([
+		readLeafEntries(source, before),
+		readLeafEntries(source, after),
+	]);
+
+	const result: FileDiff[] = [];
+	for (const path of request.changedPaths) {
+		const beforeLeaf = beforePaths.get(path);
+		const afterLeaf = afterPaths.get(path);
+		if (beforeLeaf === undefined && afterLeaf === undefined) continue;
+		const status: FileDiffStatus = beforeLeaf === undefined
+			? "added"
+			: afterLeaf === undefined ? "deleted" : "modified";
+		const beforeContent = beforeLeaf === undefined
+			? emptyContent()
+			: await readLeafContent(source, request.beforeManifestId, beforeLeaf);
+		const afterContent = afterLeaf === undefined
+			? emptyContent()
+			: await readLeafContent(source, request.afterManifestId, afterLeaf);
+		if (beforeContent.binary || afterContent.binary) {
+			result.push({ path, status, kind: "binary", additions: 0, deletions: 0, diff: "" });
+			continue;
+		}
+		const kind: FileDiffKind = beforeContent.symlink || afterContent.symlink ? "symlink" : "text";
+		const { diff } = generateDiffString(beforeContent.text, afterContent.text);
+		result.push({ path, status, kind, ...countChanges(diff), diff });
+	}
+	return result;
+}
+
+async function readLeafEntries(source: DiffSource, manifest: SnapshotManifest): Promise<Map<string, LeafEntry>> {
+	const result = new Map<string, LeafEntry>();
+	for (const root of manifest.roots) {
+		if (root.state !== "active" || root.treeId === null) continue;
+		for (const entry of await source.listTree(manifest.manifestId, root.relativeRoot)) {
+			if (entry.kind === "directory") continue;
+			const path = root.relativeRoot === "." ? entry.relativePath : `${root.relativeRoot}/${entry.relativePath}`;
+			if (!result.has(path)) result.set(path, { rootPath: root.relativeRoot, entry });
+		}
+	}
+	return result;
+}
+
+async function readLeafContent(source: DiffSource, manifestId: ManifestId, leaf: LeafEntry): Promise<LeafContent> {
+	if (leaf.entry.kind === "symlink") {
+		return { binary: false, symlink: true, text: sanitizeDiffContent(leaf.entry.linkText ?? "") };
+	}
+	if (leaf.entry.blobId === null) {
+		return { binary: true, symlink: false, text: "" };
+	}
+	const bytes = await source.readBlob(manifestId, leaf.rootPath, leaf.entry.blobId);
+	const text = decodeLossless(bytes);
+	return text === null
+		? { binary: true, symlink: false, text: "" }
+		: { binary: false, symlink: false, text: sanitizeDiffContent(text) };
+}
+
+function emptyContent(): LeafContent {
+	return { binary: false, symlink: false, text: "" };
+}
+
+function decodeLossless(bytes: Uint8Array): string | null {
+	if (bytes.includes(0)) return null;
+	const buffer = Buffer.from(bytes);
+	const text = buffer.toString("utf8");
+	return Buffer.from(text, "utf8").equals(buffer) ? text : null;
+}
+
+function sanitizeDiffContent(text: string): string {
+	return text
+		.replace(/\x1B/g, "[ESC]")
+		.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001A\u001C-\u001F\u007F]/g, "?");
+}
+
+function countChanges(diff: string): { additions: number; deletions: number } {
+	let additions = 0;
+	let deletions = 0;
+	for (const line of diff.split("\n")) {
+		if (line.startsWith("+")) additions += 1;
+		else if (line.startsWith("-")) deletions += 1;
+	}
+	return { additions, deletions };
+}
+
+const STATUS_CHAR: Record<FileDiffStatus, string> = { added: "A", deleted: "D", modified: "M" };
+
+/** 单个文件的一行摘要，用于文件清单与非 TUI 降级展示。 */
+export function buildFileLabel(diff: FileDiff): string {
+	const stats = diff.kind === "binary"
+		? "(binary)"
+		: diff.additions === 0 && diff.deletions === 0 ? "(no textual change)" : `+${diff.additions} -${diff.deletions}`;
+	return `${STATUS_CHAR[diff.status]} ${sanitizeDisplayText(diff.path, 240)}  ${stats}`;
+}
+
+/** 整个 checkpoint 的一行摘要，用于非 TUI 模式的 notify。 */
+export function formatDiffSummary(diffs: readonly FileDiff[]): string {
+	let additions = 0;
+	let deletions = 0;
+	for (const diff of diffs) {
+		additions += diff.additions;
+		deletions += diff.deletions;
+	}
+	const paths = diffs.map((diff) => sanitizeDisplayText(diff.path, 160)).join(", ");
+	return sanitizeDisplayText(`${diffs.length} file(s), +${additions} -${deletions}: ${paths}`, 500);
+}
+
+/** 清理可能进入终端 UI 的外部文本，避免 ANSI/控制序列注入。 */
+export function sanitizeDisplayText(value: string, maxLength = 200): string {
+	return value
+		.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "")
+		.replace(/\x1B\][^\u0007]*(?:\u0007|\x1B\\)/g, "")
+		.replace(/[\u0000-\u001F\u007F]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, maxLength);
+}

package/src/pi-runtime.ts

@@ -154,6 +154,7 @@ export async function createPiUndoRuntime(context: ExtensionContext, pi: Extensi
 	return {
 		controller,
 		reporter: new StatusReporter(context),
+		diffSource: store,
 		recovery: startupRecovery.kind === "locked"
 			? { files: startupRecovery.files, opId: startupRecovery.opId }
 			: undefined,

package/src/restore-engine.ts

@@ -22,6 +22,8 @@ import {
 } from "./quarantine.ts";
 import { SnapshotStoreError, type SnapshotStore } from "./snapshot-store.ts";
 
+const PREPARED_PLAN_CACHE_LIMIT = 16;
+
 export interface RestorePlan {
 	currentManifestId: ManifestId;
 	targetManifestId: ManifestId;
@@ -69,6 +71,12 @@ interface OwnedPath {
 	readonly root: SnapshotRoot;
 }
 
+interface PreparedRestorePlan {
+	readonly plan: RestorePlan;
+	readonly currentPaths: ReadonlyMap<string, OwnedPath>;
+	readonly targetPaths: ReadonlyMap<string, OwnedPath>;
+}
+
 interface MutationContext {
 	readonly phase: RestoreMutation["phase"];
 	readonly sourceManifestId: ManifestId;
@@ -88,6 +96,7 @@ export class RestoreEngine {
 	private readonly store: SnapshotStore;
 	private readonly discovery: RootDiscovery;
 	private readonly beforeMutation: RestoreEngineOptions["beforeMutation"];
+	private readonly preparedPlans = new Map<string, PreparedRestorePlan>();
 
 	constructor(options: RestoreEngineOptions) {
 		this.requestedWorkspaceRoot = resolve(options.workspaceRoot);
@@ -174,10 +183,33 @@ export class RestoreEngine {
 			writePaths,
 			...(scope === undefined ? {} : { scopePaths: [...scope] }),
 		};
-		return {
+		const plan = {
 			...semanticPlan,
 			planDigest: checksum(canonicalJson(semanticPlan)),
 		};
+		this.rememberPreparedPlan(plan, currentPaths, targetPaths);
+		return plan;
+	}
+
+	private rememberPreparedPlan(
+		plan: RestorePlan,
+		currentPaths: ReadonlyMap<string, OwnedPath>,
+		targetPaths: ReadonlyMap<string, OwnedPath>,
+	): void {
+		const cachedPlan = cloneRestorePlan(plan);
+		this.preparedPlans.set(preparedPlanKey(cachedPlan), { plan: cachedPlan, currentPaths, targetPaths });
+		while (this.preparedPlans.size > PREPARED_PLAN_CACHE_LIMIT) {
+			const oldest = this.preparedPlans.keys().next().value as string | undefined;
+			if (oldest === undefined) break;
+			this.preparedPlans.delete(oldest);
+		}
+	}
+
+	private takePreparedPlan(plan: RestorePlan): PreparedRestorePlan | undefined {
+		const key = preparedPlanKey(plan);
+		const prepared = this.preparedPlans.get(key);
+		if (prepared !== undefined) this.preparedPlans.delete(key);
+		return prepared;
 	}
 
 	async apply(
@@ -285,8 +317,10 @@ export class RestoreEngine {
 		}
 		assertCompatibleManifests(current, target);
 		let expectedPlan: RestorePlan;
+		let prepared: PreparedRestorePlan | undefined;
 		try {
 			expectedPlan = await this.plan(current, target, plan.scopePaths);
+			prepared = this.takePreparedPlan(expectedPlan);
 		} catch (error) {
 			if (error instanceof SnapshotStoreError && error.code === "object_missing") {
 				return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
@@ -307,10 +341,9 @@ export class RestoreEngine {
 		} catch {
 			return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
 		}
-		const [currentPaths, targetPaths] = await Promise.all([
-			this.readOwnedPaths(current),
-			this.readOwnedPaths(target),
-		]);
+		const [currentPaths, targetPaths] = prepared === undefined
+			? await Promise.all([this.readOwnedPaths(current), this.readOwnedPaths(target)])
+			: [prepared.currentPaths, prepared.targetPaths];
 		const quarantine = new QuarantineManager({
 			workspaceRoot: this.requestedWorkspaceRoot,
 			journal: options.mutationJournal,
@@ -817,12 +850,11 @@ export class RestoreEngine {
 			}
 		}
 
-		const live = await this.store.capture(topology, undefined, {
+		const livePaths = await this.store.listVisibleLeafPaths(topology, {
 			excludePaths: mutationJournal === undefined ? undefined : [...await mutationJournal.activeArtifacts()],
 		});
-		await this.store.assertComplete(live.manifestId);
-		for (const [path, owned] of await this.readOwnedPaths(live)) {
-			if (owned.entry.kind !== "directory" && !allowedPaths.has(path)) {
+		for (const path of livePaths) {
+			if (!allowedPaths.has(path)) {
 				throw new Error(`complete coverage 发现 manifest 集合外路径：${path}`);
 			}
 		}
@@ -1025,6 +1057,22 @@ export class RestoreEngine {
 	}
 }
 
+function preparedPlanKey(plan: RestorePlan): string {
+	return `${plan.currentManifestId}\0${plan.targetManifestId}\0${plan.planDigest}`;
+}
+
+function cloneRestorePlan(plan: RestorePlan): RestorePlan {
+	return {
+		currentManifestId: plan.currentManifestId,
+		targetManifestId: plan.targetManifestId,
+		boundaryRoots: [...plan.boundaryRoots],
+		deletePaths: [...plan.deletePaths],
+		writePaths: [...plan.writePaths],
+		...(plan.scopePaths === undefined ? {} : { scopePaths: [...plan.scopePaths] }),
+		planDigest: plan.planDigest,
+	};
+}
+
 function sameEntry(left: RestorePath, right: RestorePath): boolean {
 	return left.kind === right.kind &&
 		left.mode === right.mode &&

package/src/root-discovery.ts

@@ -5,6 +5,8 @@ import { checksum, topologyFingerprint } from "./encoding.ts";
 import { GitRunner } from "./git-runner.ts";
 import type { DiscoveryRoot } from "./model.ts";
 
+const DIRECTORY_SCAN_CONCURRENCY = 16;
+
 interface RepositoryInfo {
 	readonly absoluteRoot: string;
 	readonly commonGitDir: string;
@@ -87,22 +89,27 @@ export class RootDiscovery {
 		directory: string,
 		activeRoots: Map<string, DiscoveredRoot>,
 	): Promise<void> {
-		if (!await isSafeDirectory(directory, workspaceIdentity)) {
-			return;
-		}
-		const entries = await readdir(directory, { withFileTypes: true });
-		if (!await isSafeDirectory(directory, workspaceIdentity)) {
-			return;
-		}
-		for (const entry of entries) {
-			if (entry.name === ".git" || entry.isSymbolicLink() || !entry.isDirectory()) {
-				continue;
-			}
-			const candidate = join(directory, entry.name);
-			if (!await isSafeDirectory(candidate, workspaceIdentity)) {
-				continue;
+		let level: Array<{ readonly path: string; readonly inspect: boolean }> = [{ path: directory, inspect: false }];
+		while (level.length > 0) {
+			const next: Array<{ readonly path: string; readonly inspect: true }> = [];
+			for (let index = 0; index < level.length; index += DIRECTORY_SCAN_CONCURRENCY) {
+				const children = await Promise.all(level.slice(index, index + DIRECTORY_SCAN_CONCURRENCY).map(
+					(candidate) => this.scanDirectoryNode(workspaceIdentity, candidate, activeRoots),
+				));
+				for (const group of children) next.push(...group);
 			}
-			const inspection = await this.inspectRepository(candidate, workspaceIdentity);
+			level = next;
+		}
+	}
+
+	private async scanDirectoryNode(
+		workspaceIdentity: string,
+		candidate: { readonly path: string; readonly inspect: boolean },
+		activeRoots: Map<string, DiscoveredRoot>,
+	): Promise<Array<{ readonly path: string; readonly inspect: true }>> {
+		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
+		if (candidate.inspect) {
+			const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
 			if (inspection.kind === "active") {
 				activeRoots.set(
 					inspection.repository.absoluteRoot,
@@ -111,8 +118,13 @@ export class RootDiscovery {
 			} else if (inspection.kind === "broken") {
 				activeRoots.set(inspection.absoluteRoot, brokenRoot(workspaceIdentity, inspection.absoluteRoot));
 			}
-			await this.scanDirectory(workspaceIdentity, candidate, activeRoots);
+			if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
 		}
+		const entries = await readdir(candidate.path, { withFileTypes: true });
+		if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
+		return entries
+			.filter((entry) => entry.name !== ".git" && !entry.isSymbolicLink() && entry.isDirectory())
+			.map((entry) => ({ path: join(candidate.path, entry.name), inspect: true as const }));
 	}
 
 	private async inspectRepository(candidate: string, workspaceIdentity: string): Promise<RepositoryInspection> {