@davideasden/pi-undo 0.2.22 → 0.2.25

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,11 @@
-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 type { MutationJournal } from "./mutation-journal.ts";
 
 const NATIVE_TIMEOUT_MS = 120_000;
@@ -20,9 +21,11 @@ export async function createNativeFileBatch(options: {
 	readonly workspaceRoot: string;
 	readonly planDigest: string;
 	readonly journal: MutationJournal;
+	/** 测试注入用；默认使用随包分发的平台二进制。 */
+	readonly executable?: string;
 }): 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);
@@ -33,6 +36,8 @@ export async function createNativeFileBatch(options: {
 		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 +68,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,7 +77,8 @@ 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;
 			}
 		},
@@ -90,57 +96,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 响应无效");
+	}
 }

package/src/operation-context.ts

@@ -0,0 +1,266 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type OperationErrorCode = "operation_cancelled" | "operation_timeout";
+
+/**
+ * 一次可取消操作的共享作用域。调用方（撤回/捕获/恢复入口）创建 context，
+ * 低层只读取当前继承的 context：deadline 是硬上限，signal 是取消通道。
+ */
+export interface ProcessDiagnostic {
+	readonly command: string;
+	readonly durationMs: number;
+	readonly outcome: string;
+	readonly exitCode: number | null;
+}
+
+export interface OperationContext {
+	readonly signal: AbortSignal;
+	readonly deadline: number;
+	readonly onProgress?: (phase: string) => void;
+	readonly onProcess?: (diagnostic: ProcessDiagnostic) => void;
+}
+
+export class OperationError extends Error {
+	readonly code: OperationErrorCode;
+
+	constructor(code: OperationErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "OperationError";
+		this.code = code;
+	}
+}
+
+/** 超时与主动取消都走 AbortSignal；用固定 reason 区分两者。 */
+const OPERATION_TIMEOUT_REASON = "operation_timeout";
+
+const storage = new AsyncLocalStorage<OperationContext | undefined>();
+const unsafeContexts = new WeakSet<OperationContext>();
+
+export function markProcessExitUnconfirmed(): void {
+	const context = storage.getStore();
+	if (context !== undefined) unsafeContexts.add(context);
+}
+
+export function operationHasUnconfirmedExit(): boolean {
+	const context = storage.getStore();
+	return context !== undefined && unsafeContexts.has(context);
+}
+
+/**
+ * 在 context 下运行 body；context 为 undefined 时清除继承的 context，
+ * 保证嵌套作用域之间不会泄漏取消状态。
+ */
+export function runWithOperationContext<T>(context: OperationContext | undefined, body: () => T): T {
+	return storage.run(context, body);
+}
+
+export function currentOperationContext(): OperationContext | undefined {
+	return storage.getStore();
+}
+
+/**
+ * 取消或超时检查：可在任意 await 边界调用。没有 context 时是空操作。
+ * 已取消/超时抛 OperationError，code 区分 operation_cancelled 与 operation_timeout。
+ */
+export function checkOperation(): void {
+	const context = storage.getStore();
+	if (context === undefined) {
+		return;
+	}
+	if (unsafeContexts.has(context)) throw Object.assign(new Error("子进程未确认退出"), { code: "process_exit_unconfirmed" });
+	if (context.signal.aborted) {
+		throw operationErrorFromAbortReason(context.signal.reason);
+	}
+	if (Date.now() >= context.deadline) {
+		throw new OperationError("operation_timeout", "操作超过截止时间");
+	}
+}
+
+/** 报告可读阶段（供状态显示使用）；没有 context 或没有 onProgress 时是空操作。 */
+export function reportOperationProgress(phase: string): void {
+	storage.getStore()?.onProgress?.(phase);
+}
+
+export function reportProcessDiagnostic(diagnostic: ProcessDiagnostic): void {
+	try {
+		storage.getStore()?.onProcess?.(diagnostic);
+	} catch {
+		// 诊断失败不能改变事务结果。
+	}
+}
+
+export interface OperationProcessOptions {
+	readonly signal?: AbortSignal;
+	readonly timeoutMs: number;
+}
+
+/**
+ * 低层子进程包装器使用的预算：取「剩余 deadline」与 defaultTimeoutMs 的较小值。
+ * 已取消或已超时直接抛出，避免取消后继续启动新工作。
+ */
+export function operationProcessOptions(defaultTimeoutMs = 120_000): OperationProcessOptions {
+	if (!Number.isFinite(defaultTimeoutMs) || defaultTimeoutMs < 0) {
+		throw new RangeError("defaultTimeoutMs 必须是非负有限数字");
+	}
+	const context = storage.getStore();
+	if (context === undefined) {
+		return { timeoutMs: defaultTimeoutMs };
+	}
+	checkOperation();
+	const remaining = context.deadline - Date.now();
+	return {
+		signal: context.signal,
+		timeoutMs: Math.min(defaultTimeoutMs, remaining),
+	};
+}
+
+export interface OperationScopeOptions {
+	/** 不传表示没有 deadline（只受 signal 控制）。 */
+	readonly timeoutMs?: number;
+	/** 上层取消（例如 /undo-cancel 或父作用域）会传播到本作用域。 */
+	readonly signal?: AbortSignal;
+	readonly onProgress?: (phase: string) => void;
+	readonly onProcess?: (diagnostic: ProcessDiagnostic) => void;
+	readonly now?: () => number;
+}
+
+export interface OperationScope {
+	readonly context: OperationContext;
+	/** 请求主动取消。 */
+	cancel(): void;
+	/** 清除超时计时器与父 signal 监听。 */
+	dispose(): void;
+}
+
+/**
+ * 创建一次可取消操作的 context。超时通过计时器把 signal 置为 timeout reason，
+ * 使 checkOperation/operationProcessOptions 能区分超时与主动取消。
+ */
+export function createOperationScope(options: OperationScopeOptions = {}): OperationScope {
+	const now = options.now ?? Date.now;
+	const controller = new AbortController();
+	const deadline = options.timeoutMs === undefined
+		? Number.POSITIVE_INFINITY
+		: now() + options.timeoutMs;
+	let timeout: NodeJS.Timeout | undefined;
+	if (options.timeoutMs !== undefined) {
+		timeout = setTimeout(() => controller.abort(OPERATION_TIMEOUT_REASON), Math.max(0, options.timeoutMs));
+		timeout.unref();
+	}
+	const onParentAbort = (): void => controller.abort(options.signal?.reason ?? "operation_cancelled");
+	if (options.signal !== undefined) {
+		if (options.signal.aborted) {
+			onParentAbort();
+		} else {
+			options.signal.addEventListener("abort", onParentAbort, { once: true });
+		}
+	}
+	const context: OperationContext = {
+		signal: controller.signal,
+		deadline,
+		...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+		...(options.onProcess === undefined ? {} : { onProcess: options.onProcess }),
+	};
+	return {
+		context,
+		cancel: () => controller.abort("operation_cancelled"),
+		dispose: () => {
+			if (timeout !== undefined) {
+				clearTimeout(timeout);
+			}
+			options.signal?.removeEventListener("abort", onParentAbort);
+		},
+	};
+}
+
+export async function allCompleted<T extends readonly unknown[]>(tasks: T): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
+	const outcomes = await Promise.allSettled(tasks);
+	const failure = outcomes.find((outcome) => outcome.status === "rejected");
+	if (failure?.status === "rejected") throw failure.reason;
+	return outcomes.map((outcome) => (outcome as PromiseFulfilledResult<unknown>).value) as { -readonly [K in keyof T]: Awaited<T[K]> };
+}
+
+export function configuredTimeout(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (raw === undefined || raw === "") return fallback;
+	const value = Number(raw);
+	if (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647) throw new Error(`${name} 必须是正整数毫秒`);
+	return value;
+}
+
+export async function withRecoveryBudget<T>(body: () => Promise<T>, options: OperationScopeOptions = {}): Promise<T> {
+	if (operationHasUnconfirmedExit()) checkOperation();
+	const scope = createOperationScope({
+		timeoutMs: configuredTimeout("PI_UNDO_OPERATION_TIMEOUT_MS", 300_000),
+		onProcess: currentOperationContext()?.onProcess,
+		...options,
+	});
+	try {
+		return await runWithOperationContext(scope.context, async () => {
+			try {
+				return await body();
+			} finally {
+				if (operationHasUnconfirmedExit()) checkOperation();
+			}
+		});
+	} catch (error) {
+		if (isUnconfirmedExit(error)) markProcessExitUnconfirmed();
+		throw error;
+	} finally {
+		scope.dispose();
+	}
+}
+
+export function isUnconfirmedExit(error: unknown): boolean {
+	return errorChain(error).some((value) => value.code === "git_termination_failed" || value.code === "process_exit_unconfirmed");
+}
+
+/** 包装层保留 cause 时仍能识别取消，避免被误报为普通 capture 失败。 */
+export function operationFailure(error: unknown): OperationErrorCode | undefined {
+	for (const value of errorChain(error)) {
+		if (value.code === "operation_cancelled" || value.code === "operation_timeout") return value.code;
+		const result = value.result as { timedOut?: boolean; aborted?: boolean } | undefined;
+		if (result?.timedOut) return "operation_timeout";
+		if (result?.aborted) return "operation_cancelled";
+	}
+	return undefined;
+}
+
+export function rethrowOperationFailure(error: unknown): void {
+	if (isUnconfirmedExit(error) || operationFailure(error) !== undefined) throw error;
+}
+
+function errorChain(error: unknown): Array<Record<string, unknown>> {
+	const chain: Array<Record<string, unknown>> = [];
+	const seen = new Set<unknown>();
+	while (typeof error === "object" && error !== null && !seen.has(error)) {
+		seen.add(error);
+		const value = error as Record<string, unknown>;
+		chain.push(value);
+		error = value.cause;
+	}
+	return chain;
+}
+
+function operationErrorFromAbortReason(reason: unknown): OperationError {
+	if (isTimeoutReason(reason)) {
+		return new OperationError("operation_timeout", "操作超过截止时间");
+	}
+	return new OperationError("operation_cancelled", "操作已被取消");
+}
+
+/** 判断 AbortSignal 的 reason 是否代表超时（而不是主动取消）。 */
+export function isOperationTimeoutReason(reason: unknown): boolean {
+	return isTimeoutReason(reason);
+}
+
+function isTimeoutReason(reason: unknown): boolean {
+	if (reason === OPERATION_TIMEOUT_REASON) {
+		return true;
+	}
+	if (typeof reason !== "object" || reason === null) {
+		return false;
+	}
+	const value = reason as { readonly code?: unknown; readonly name?: unknown };
+	return value.code === OPERATION_TIMEOUT_REASON || value.name === "TimeoutError";
+}