@davideasden/pi-undo 0.2.24 → 0.2.26

package/src/native-directory-scan.ts

@@ -0,0 +1,114 @@
+import { constants } from "node:fs";
+import { access, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
+import { probeNativeCapability } from "./native-capabilities.ts";
+import { nativeExecutable } from "./native-restore.ts";
+import { checkOperation, configuredTimeout, OperationError, operationProcessOptions } from "./operation-context.ts";
+
+export interface NativeRepositoryCandidate {
+	readonly path: string;
+	readonly dev: bigint;
+	readonly ino: bigint;
+}
+
+export interface NativeDirectoryScan {
+	readonly directories: number;
+	readonly repositories: readonly NativeRepositoryCandidate[];
+}
+
+export interface NativeDirectoryScanPort {
+	scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined>;
+}
+
+/** 只缓存 helper 能力；每个拓扑检查点均重新完整扫描工作区，包括 ignored 目录。 */
+export class NativeDirectoryScanner implements NativeDirectoryScanPort {
+	private readonly executable: string | undefined;
+	private capability: Promise<boolean> | undefined;
+
+	constructor(executable = nativeExecutable()) {
+		this.executable = process.env.PI_UNDO_DISABLE_NATIVE === "1" || process.platform === "win32"
+			? undefined : executable;
+	}
+
+	async scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined> {
+		checkOperation();
+		if (this.executable === undefined || (this.capability !== undefined && !await this.capability)) return undefined;
+		const requestDirectory = await mkdtemp(join(tmpdir(), "pi-undo-native-scan-"));
+		try {
+			this.capability ??= this.supportsScan(requestDirectory).catch((error) => {
+				// 取消或未确认终止不能污染后续操作的能力缓存。
+				this.capability = undefined;
+				throw error;
+			});
+			if (!await this.capability) return undefined;
+			const budget = operationProcessOptions(configuredTimeout("PI_UNDO_OPERATION_TIMEOUT_MS", 300_000));
+			const requestPath = join(requestDirectory, "request.json");
+			await writeFile(requestPath, JSON.stringify({ schemaVersion: 1, workspaceRoot }), { mode: 0o600, flag: "wx" });
+			const result = await runSupervisedProcess({
+				command: this.executable,
+				args: ["--scan-directories", requestPath],
+				...budget,
+				outputLimitBytes: 32 * 1024 * 1024,
+				outputOverflow: "terminate",
+			});
+			if (!result.stopped) throw new GitRunError("git_termination_failed", "native 目录扫描进程未能确认终止");
+			if (result.outcome === "cancelled") {
+				checkOperation();
+				throw new OperationError("operation_cancelled", "native 目录扫描已被取消");
+			}
+			if (result.outcome === "timeout") throw new OperationError("operation_timeout", "native 目录扫描超时");
+			if (result.outcome !== "exit" || result.code !== 0) {
+				throw new Error(`native 目录扫描失败：${result.stderr.toString("utf8").trim() || result.outcome}`);
+			}
+			checkOperation();
+			return parseScanResponse(result.stdout.toString("utf8"));
+		} finally {
+			await rm(requestDirectory, { recursive: true, force: true }).catch(() => {});
+		}
+	}
+
+	private async supportsScan(directory: string): Promise<boolean> {
+		try {
+			await access(this.executable!, constants.X_OK);
+		} catch {
+			return false;
+		}
+		return probeNativeCapability(this.executable!, "scan-directories-v1", directory);
+	}
+}
+
+function parseScanResponse(text: string): NativeDirectoryScan | undefined {
+	const value: unknown = JSON.parse(text);
+	// 深度上限是执行器的资源边界；此时丢弃部分结果，由 TypeScript 从根完整重扫。
+	if (isRecord(value) && value.ok === false && value.code === "depth_limit") return undefined;
+	if (!isRecord(value) || value.ok !== true || !Number.isSafeInteger(value.directories) ||
+		(value.directories as number) < 1 || !Array.isArray(value.repositories) ||
+		value.repositories.length >= (value.directories as number)) {
+		throw new Error("native 目录扫描响应无效");
+	}
+	const seen = new Set<string>();
+	const repositories = value.repositories.map((candidate): NativeRepositoryCandidate => {
+		if (!isRecord(candidate) || typeof candidate.path !== "string" || candidate.path.includes("\0") ||
+			candidate.path.split("/").some((part) => part === "" || part === "." || part === ".." || part === ".git") ||
+			seen.has(candidate.path)) {
+			throw new Error("native 仓库候选路径无效");
+		}
+		seen.add(candidate.path);
+		return { path: candidate.path, dev: parseIdentity(candidate.dev), ino: parseIdentity(candidate.ino) };
+	});
+	return { directories: value.directories as number, repositories };
+}
+
+function parseIdentity(value: unknown): bigint {
+	if (typeof value !== "string" || !/^(?:0|[1-9][0-9]{0,19})$/.test(value) || BigInt(value) > (1n << 64n) - 1n) {
+		throw new Error("native 目录身份字段无效");
+	}
+	return BigInt(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/native-metadata.ts

@@ -1,13 +1,16 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { access, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
+import { OperationError, type OperationProcessOptions, operationProcessOptions } from "./operation-context.ts";
 import { nativeExecutable } from "./native-restore.ts";
 
 const NATIVE_INSPECT_TIMEOUT_MS = 30_000;
 const NATIVE_INSPECT_OUTPUT_LIMIT = 32 * 1024 * 1024;
+const NATIVE_PROBE_TIMEOUT_MS = 5_000;
+const NATIVE_PROBE_OUTPUT_LIMIT = 64 * 1024;
 
 export interface NativeMetadataEntry {
 	readonly path: string;
@@ -43,6 +46,8 @@ export class NativeMetadataInspector implements NativeMetadataPort {
 		requestDirectory: string,
 	): Promise<readonly NativeMetadataEntry[] | undefined> {
 		if (paths.length === 0) return [];
+		// 已取消/超时的操作不启动新的 helper，也不写出请求文件。
+		const budget = operationProcessOptions(NATIVE_INSPECT_TIMEOUT_MS);
 		if (!await this.supportsInspect(requestDirectory)) return undefined;
 		const executable = this.executable!;
 		const requestPath = join(requestDirectory, `native-inspect-${process.pid}-${randomUUID()}.json`);
@@ -52,7 +57,7 @@ export class NativeMetadataInspector implements NativeMetadataPort {
 				workspaceRoot,
 				paths,
 			}), { mode: 0o600, flag: "wx" });
-			return await runNativeInspect(executable, requestPath, paths);
+			return await runNativeInspect(executable, requestPath, paths, budget);
 		} finally {
 			await rm(requestPath, { force: true }).catch(() => {});
 		}
@@ -73,100 +78,55 @@ export class NativeMetadataInspector implements NativeMetadataPort {
 	}
 }
 
-function probeNativeInspect(executable: string, isolatedDirectory: string): Promise<boolean> {
-	return new Promise((resolve) => {
-		const child = spawn(executable, ["--capabilities"], {
+async function probeNativeInspect(executable: string, isolatedDirectory: string): Promise<boolean> {
+	try {
+		const result = await runSupervisedProcess({
+			command: executable,
+			args: ["--capabilities"],
 			cwd: isolatedDirectory,
-			shell: false,
-			stdio: ["ignore", "pipe", "ignore"],
-			windowsHide: true,
+			timeoutMs: NATIVE_PROBE_TIMEOUT_MS,
+			outputLimitBytes: NATIVE_PROBE_OUTPUT_LIMIT,
+			outputOverflow: "terminate",
 		});
-		const stdout: Buffer[] = [];
-		let bytes = 0;
-		let settled = false;
-		const timeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
-		child.stdout?.on("data", (chunk: Buffer | string) => {
-			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-			bytes += value.length;
-			if (bytes <= 64 * 1024) stdout.push(value);
-			else child.kill("SIGKILL");
-		});
-		child.once("error", () => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			resolve(false);
-		});
-		child.once("close", (code) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			if (code !== 0 || bytes > 64 * 1024) return resolve(false);
-			try {
-				const value: unknown = JSON.parse(Buffer.concat(stdout).toString("utf8"));
-				resolve(isRecord(value) && value.ok === true && Array.isArray(value.capabilities) &&
-					value.capabilities.includes("inspect-v1"));
-			} catch {
-				resolve(false);
-			}
-		});
-	});
+		if (!result.stopped || result.outcome !== "exit" || result.code !== 0) return false;
+		const value: unknown = JSON.parse(result.stdout.toString("utf8"));
+		return isRecord(value) && value.ok === true && Array.isArray(value.capabilities) &&
+			value.capabilities.includes("inspect-v1");
+	} catch {
+		return false;
+	}
 }
 
-function runNativeInspect(
+async function runNativeInspect(
 	executable: string,
 	requestPath: string,
 	expectedPaths: readonly string[],
+	budget: OperationProcessOptions,
 ): Promise<readonly NativeMetadataEntry[]> {
-	return new Promise((resolve, reject) => {
-		const child = spawn(executable, ["--inspect", requestPath], {
-			shell: false,
-			stdio: ["ignore", "pipe", "pipe"],
-			windowsHide: true,
-		});
-		const stdout: Buffer[] = [];
-		const stderr: Buffer[] = [];
-		let outputBytes = 0;
-		let settled = false;
-		let overflow = false;
-		const timeout = setTimeout(() => child.kill("SIGKILL"), NATIVE_INSPECT_TIMEOUT_MS);
-		const capture = (target: Buffer[]) => (chunk: Buffer | string): void => {
-			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-			if (outputBytes + bytes.length > NATIVE_INSPECT_OUTPUT_LIMIT) {
-				overflow = true;
-				child.kill("SIGKILL");
-				return;
-			}
-			target.push(bytes);
-			outputBytes += bytes.length;
-		};
-		child.stdout?.on("data", capture(stdout));
-		child.stderr?.on("data", capture(stderr));
-		child.once("error", (error) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			reject(error);
-		});
-		child.once("close", (code) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			if (overflow) {
-				reject(new Error("native metadata inspect 输出超过限制"));
-				return;
-			}
-			if (code !== 0) {
-				reject(new Error(`native metadata inspect 失败：${Buffer.concat(stderr).toString("utf8").trim()}`));
-				return;
-			}
-			try {
-				resolve(parseInspectResponse(Buffer.concat(stdout).toString("utf8"), expectedPaths));
-			} catch (error) {
-				reject(error);
-			}
-		});
+	const result = await runSupervisedProcess({
+		command: executable,
+		args: ["--inspect", requestPath],
+		signal: budget.signal,
+		timeoutMs: budget.timeoutMs,
+		outputLimitBytes: NATIVE_INSPECT_OUTPUT_LIMIT,
+		outputOverflow: "terminate",
 	});
+	if (!result.stopped) {
+		throw new GitRunError("git_termination_failed", "native metadata inspect 进程未能确认终止");
+	}
+	if (result.outcome === "cancelled") {
+		throw new OperationError("operation_cancelled", "native metadata inspect 已被取消");
+	}
+	if (result.outcome === "timeout") {
+		throw new OperationError("operation_timeout", "native metadata inspect 超时");
+	}
+	if (result.outcome === "output_overflow") {
+		throw new Error("native metadata inspect 输出超过限制");
+	}
+	if (result.code !== 0) {
+		throw new Error(`native metadata inspect 失败：${result.stderr.toString("utf8").trim()}`);
+	}
+	return parseInspectResponse(result.stdout.toString("utf8"), expectedPaths);
 }
 
 function parseInspectResponse(text: string, expectedPaths: readonly string[]): readonly NativeMetadataEntry[] {

package/src/native-restore.ts

@@ -1,10 +1,12 @@
-import { spawn } from "node:child_process";
 import { constants } from "node:fs";
 import { access, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
 import type { DurablePack } from "./durable-pack.ts";
+import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
+import { OperationError, type OperationProcessOptions, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
+import { probeNativeCapability } from "./native-capabilities.ts";
 import type { MutationJournal } from "./mutation-journal.ts";
 
 const NATIVE_TIMEOUT_MS = 120_000;
@@ -20,19 +22,27 @@ export async function createNativeFileBatch(options: {
 	readonly workspaceRoot: string;
 	readonly planDigest: string;
 	readonly journal: MutationJournal;
+	/** 测试注入用；默认使用随包分发的平台二进制。 */
+	readonly executable?: string;
+	readonly requiredCapability?: "restore-files-v2";
 }): Promise<NativeFileBatch | undefined> {
 	if (process.env.PI_UNDO_DISABLE_NATIVE === "1") return undefined;
-	const executable = nativeExecutable();
+	const executable = options.executable ?? nativeExecutable();
 	if (executable === undefined) return undefined;
 	try {
 		await access(executable, constants.X_OK);
 	} catch {
 		return undefined;
 	}
+	if (options.requiredCapability !== undefined && !await probeNativeCapability(
+		executable, options.requiredCapability, dirname(options.journal.storagePath),
+	)) return undefined;
 	const execute = async (pack: DurablePack, requestPath: string, verifyOnly: boolean): Promise<void> => {
 		const paths = pack.paths();
 		if (paths.length === 0) return;
 		if (pack.planDigest !== options.planDigest) throw new Error("native file batch planDigest 不匹配");
+		// 取消/超时检查在写出 request 之前：已取消的操作不产生新工作，也不留下请求文件。
+		const budget = operationProcessOptions(NATIVE_TIMEOUT_MS);
 		const request = {
 			schemaVersion: 1,
 			opId: options.journal.operationId,
@@ -63,7 +73,7 @@ export async function createNativeFileBatch(options: {
 			}),
 		};
 		await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
-		await runNative(executable, requestPath, paths.length);
+		await runNative(executable, requestPath, paths.length, budget);
 	};
 	return {
 		available: true,
@@ -72,13 +82,21 @@ export async function createNativeFileBatch(options: {
 			try {
 				await execute(pack, join(dirname(pack.storagePath), `native-verify-${process.pid}.json`), true);
 				return true;
-			} catch {
+			} catch (error) {
+				rethrowOperationFailure(error);
 				return false;
 			}
 		},
 	};
 }
 
+export function nativeRestoreCapability(pack: DurablePack): "restore-files-v2" | undefined {
+	const paths = pack.paths();
+	const deletes = paths.filter((path) => pack.artifacts(path)?.target === null);
+	return deletes.some((path) => path.includes("/")) || (deletes.length > 0 && deletes.length < paths.length)
+		? "restore-files-v2" : undefined;
+}
+
 export function nativeExecutable(): string | undefined {
 	const platform = process.platform === "darwin"
 		? "darwin"
@@ -90,57 +108,44 @@ export function nativeExecutable(): string | undefined {
 	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> {
-	return new Promise((resolve, reject) => {
-		const child = spawn(executable, [requestPath], {
-			shell: false,
-			stdio: ["ignore", "pipe", "pipe"],
-			windowsHide: true,
-		});
-		const stdout: Buffer[] = [];
-		const stderr: Buffer[] = [];
-		let outputBytes = 0;
-		let settled = false;
-		const timeout = setTimeout(() => child.kill("SIGKILL"), NATIVE_TIMEOUT_MS);
-		const capture = (target: Buffer[]) => (chunk: Buffer | string): void => {
-			if (outputBytes >= NATIVE_OUTPUT_LIMIT) return;
-			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-			const captured = bytes.subarray(0, NATIVE_OUTPUT_LIMIT - outputBytes);
-			target.push(captured);
-			outputBytes += captured.length;
-		};
-		child.stdout?.on("data", capture(stdout));
-		child.stderr?.on("data", capture(stderr));
-		child.once("error", (error) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			reject(error);
-		});
-		child.once("close", (code) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeout);
-			if (code !== 0) {
-				reject(new Error(`native restore 失败：${Buffer.concat(stderr).toString("utf8").trim()}`));
-				return;
-			}
-			try {
-				const result: unknown = JSON.parse(Buffer.concat(stdout).toString("utf8"));
-				if (
-					typeof result !== "object" ||
-					result === null ||
-					!("ok" in result) ||
-					result.ok !== true ||
-					!("processed" in result) ||
-					result.processed !== expected
-				) {
-					throw new Error("native restore 响应无效");
-				}
-				resolve();
-			} catch (error) {
-				reject(error);
-			}
-		});
+async function runNative(
+	executable: string,
+	requestPath: string,
+	expected: number,
+	budget: OperationProcessOptions,
+): Promise<void> {
+	const result = await runSupervisedProcess({
+		command: executable,
+		args: [requestPath],
+		signal: budget.signal,
+		timeoutMs: budget.timeoutMs,
+		outputLimitBytes: NATIVE_OUTPUT_LIMIT,
 	});
+	if (!result.stopped) {
+		// 无法证明 helper 已停止：保留 lease，让上层走恢复流程。
+		throw new GitRunError("git_termination_failed", "native restore 进程未能确认终止");
+	}
+	if (result.outcome === "cancelled") {
+		throw new OperationError("operation_cancelled", "native restore 已被取消");
+	}
+	if (result.outcome === "timeout") {
+		throw new OperationError("operation_timeout", "native restore 超时");
+	}
+	if (result.outcome === "output_overflow") {
+		throw new Error("native restore 输出超过限制");
+	}
+	if (result.code !== 0) {
+		throw new Error(`native restore 失败：${result.stderr.toString("utf8").trim()}`);
+	}
+	const parsed: unknown = JSON.parse(result.stdout.toString("utf8"));
+	if (
+		typeof parsed !== "object" ||
+		parsed === null ||
+		!("ok" in parsed) ||
+		parsed.ok !== true ||
+		!("processed" in parsed) ||
+		parsed.processed !== expected
+	) {
+		throw new Error("native restore 响应无效");
+	}
 }