@davideasden/pi-undo 0.1.0

package/src/git-runner.ts

@@ -0,0 +1,308 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export const DEFAULT_STDERR_LIMIT = 64 * 1024;
+const TERMINATION_GRACE_MS = 50;
+const PROCESS_TREE_EXIT_TIMEOUT_MS = 1_000;
+const PROCESS_TREE_POLL_MS = 10;
+const activeProcessGroups = new Set<number>();
+
+process.once("exit", () => {
+	for (const processGroup of activeProcessGroups) {
+		try {
+			process.kill(-processGroup, "SIGKILL");
+		} catch {
+			// 进程组已经结束时无需处理。
+		}
+	}
+});
+
+export interface GitRunOptions {
+	readonly cwd?: string;
+	readonly env?: Readonly<Record<string, string | undefined>>;
+	readonly stdin?: string | Uint8Array;
+	readonly signal?: AbortSignal;
+	readonly timeoutMs?: number;
+	readonly stderrLimit?: number;
+}
+
+export interface GitRunResult {
+	readonly stdout: string;
+	readonly stdoutBytes: Uint8Array;
+	readonly stderr: string;
+	readonly code: number | null;
+	readonly killed: boolean;
+	readonly timedOut: boolean;
+	readonly aborted: boolean;
+}
+
+export type GitRunErrorCode = "git_failed" | "git_spawn_failed" | "git_termination_failed";
+
+export class GitRunError extends Error {
+	readonly code: GitRunErrorCode;
+	readonly result?: GitRunResult;
+
+	constructor(code: GitRunErrorCode, message: string, result?: GitRunResult) {
+		super(message);
+		this.name = "GitRunError";
+		this.code = code;
+		this.result = result;
+	}
+}
+
+export interface GitRunner {
+	run(args: readonly string[], options?: GitRunOptions): Promise<GitRunResult>;
+}
+
+export class GitRunner {
+	async run(args: readonly string[], options: GitRunOptions = {}): Promise<GitRunResult> {
+		const stderrLimit = options.stderrLimit ?? DEFAULT_STDERR_LIMIT;
+		if (!Number.isInteger(stderrLimit) || stderrLimit < 0) {
+			throw new RangeError("stderrLimit 必须是非负整数");
+		}
+		if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+			throw new RangeError("timeoutMs 必须是非负有限数字");
+		}
+		if (options.signal?.aborted) {
+			return {
+				stdout: "",
+				stdoutBytes: new Uint8Array(),
+				stderr: "",
+				code: null,
+				killed: true,
+				timedOut: false,
+				aborted: true,
+			};
+		}
+
+		return new Promise<GitRunResult>((resolve, reject) => {
+			const environment = mergeEnvironment(options.env);
+			let child;
+			try {
+				child = spawn("git", [...args], {
+					cwd: options.cwd,
+					detached: process.platform !== "win32",
+					env: environment,
+					shell: false,
+					stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+				});
+			} catch (error) {
+				reject(new GitRunError("git_spawn_failed", errorMessage(error)));
+				return;
+			}
+			trackProcessGroup(child);
+
+			const stdout: Buffer[] = [];
+			const stderr: Buffer[] = [];
+			let stderrBytes = 0;
+			let killed = false;
+			let timedOut = false;
+			let aborted = false;
+			let settled = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let forceKill: NodeJS.Timeout | undefined;
+			let closeResult: { code: number | null; signal: NodeJS.Signals | null } | undefined;
+			let terminationFinalized = false;
+			let terminationFailed = false;
+
+			child.stdout?.on("data", (chunk: Buffer | string) => {
+				stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+			});
+			child.stderr?.on("data", (chunk: Buffer | string) => {
+				if (stderrBytes >= stderrLimit) {
+					return;
+				}
+				const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+				const remaining = stderrLimit - stderrBytes;
+				const captured = bytes.length > remaining ? bytes.subarray(0, remaining) : bytes;
+				stderr.push(captured);
+				stderrBytes += captured.length;
+			});
+			if (options.stdin !== undefined) {
+				child.stdin?.end(typeof options.stdin === "string" ? options.stdin : Buffer.from(options.stdin));
+			}
+
+			const terminate = (reason: "timeout" | "abort"): void => {
+				if (settled || killed) {
+					return;
+				}
+				killed = true;
+				timedOut = reason === "timeout";
+				aborted = reason === "abort";
+				signalProcessTree(child, "SIGTERM");
+				forceKill = setTimeout(() => {
+					void forceTerminateProcessTree(child).then((stopped) => {
+						terminationFailed = !stopped;
+						terminationFinalized = true;
+						finish();
+					});
+				}, TERMINATION_GRACE_MS);
+			};
+
+			const onAbort = (): void => terminate("abort");
+			options.signal?.addEventListener("abort", onAbort, { once: true });
+			if (options.timeoutMs !== undefined) {
+				timeout = setTimeout(() => terminate("timeout"), options.timeoutMs);
+			}
+
+			const cleanUp = (): void => {
+				settled = true;
+				if (timeout) {
+					clearTimeout(timeout);
+				}
+				if (forceKill) {
+					clearTimeout(forceKill);
+				}
+				untrackProcessGroup(child);
+				options.signal?.removeEventListener("abort", onAbort);
+			};
+
+			const finish = (): void => {
+				if (settled || closeResult === undefined || (killed && !terminationFinalized)) {
+					return;
+				}
+				cleanUp();
+				const stdoutBuffer = Buffer.concat(stdout);
+				const result: GitRunResult = {
+					stdout: stdoutBuffer.toString("utf8"),
+					stdoutBytes: new Uint8Array(stdoutBuffer),
+					stderr: Buffer.concat(stderr).toString("utf8"),
+					code: closeResult.code,
+					killed: killed || closeResult.signal !== null,
+					timedOut,
+					aborted,
+				};
+				if (terminationFailed) {
+					reject(new GitRunError("git_termination_failed", "Git 进程组未能完全终止", result));
+					return;
+				}
+				if (!killed && closeResult.code !== 0) {
+					reject(new GitRunError("git_failed", `git 退出码为 ${String(closeResult.code)}`, result));
+					return;
+				}
+				resolve(result);
+			};
+
+			child.once("error", (error) => {
+				if (settled) {
+					return;
+				}
+				cleanUp();
+				reject(new GitRunError("git_spawn_failed", error.message));
+			});
+
+			child.once("close", (code, signal) => {
+				if (settled) {
+					return;
+				}
+				closeResult = { code, signal };
+				if (!killed) {
+					terminationFinalized = true;
+				}
+				finish();
+			});
+		});
+	}
+}
+
+async function forceTerminateProcessTree(child: ChildProcess): Promise<boolean> {
+	if (process.platform === "win32" && child.pid !== undefined) {
+		await runTaskkill(child.pid, child);
+		return true;
+	}
+	signalProcessTree(child, "SIGKILL");
+	if (child.pid === undefined) {
+		return true;
+	}
+	const deadline = Date.now() + PROCESS_TREE_EXIT_TIMEOUT_MS;
+	while (processGroupExists(child.pid)) {
+		if (Date.now() >= deadline) {
+			return false;
+		}
+		await delay(PROCESS_TREE_POLL_MS);
+	}
+	return true;
+}
+
+function runTaskkill(pid: number, child: ChildProcess): Promise<void> {
+	return new Promise((resolve) => {
+		const killer = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		let settled = false;
+		const finish = (): void => {
+			if (settled) return;
+			settled = true;
+			resolve();
+		};
+		killer.once("error", () => {
+			child.kill("SIGKILL");
+			finish();
+		});
+		killer.once("close", finish);
+	});
+}
+
+function processGroupExists(processGroup: number): boolean {
+	try {
+		process.kill(-processGroup, 0);
+		return true;
+	} catch (error) {
+		return !hasErrorCode(error, "ESRCH");
+	}
+}
+
+function trackProcessGroup(child: ChildProcess): void {
+	if (process.platform !== "win32" && child.pid !== undefined) {
+		activeProcessGroups.add(child.pid);
+	}
+}
+
+function untrackProcessGroup(child: ChildProcess): void {
+	if (child.pid !== undefined) {
+		activeProcessGroups.delete(child.pid);
+	}
+}
+
+function signalProcessTree(child: ChildProcess, signal: NodeJS.Signals): void {
+	if (process.platform !== "win32" && child.pid !== undefined) {
+		try {
+			process.kill(-child.pid, signal);
+			return;
+		} catch (error) {
+			if (!hasErrorCode(error, "ESRCH")) {
+				child.kill(signal);
+			}
+			return;
+		}
+	}
+	child.kill(signal);
+}
+
+export function createGitRunner(): GitRunner {
+	return new GitRunner();
+}
+
+function mergeEnvironment(overrides: Readonly<Record<string, string | undefined>> | undefined): NodeJS.ProcessEnv {
+	const environment: NodeJS.ProcessEnv = { ...process.env };
+	for (const [key, value] of Object.entries(overrides ?? {})) {
+		if (value === undefined) {
+			delete environment[key];
+		} else {
+			environment[key] = value;
+		}
+	}
+	return environment;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function delay(milliseconds: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/src/journal.ts

@@ -0,0 +1,297 @@
+import { appendFile, lstat, readFile, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { fsyncDirectory, fsyncFile, writeContentAddressed, writeJsonAtomic } from "./atomic-fs.ts";
+import {
+	assertCursor,
+	assertJournalState,
+	assertOperationDescriptor,
+	canonicalJson,
+	checksum,
+} from "./encoding.ts";
+import type {
+	CursorState,
+	JournalPhase,
+	JournalState,
+	OperationDescriptor,
+} from "./model.ts";
+import { MutationJournal } from "./mutation-journal.ts";
+
+export interface PendingJournal {
+	readonly descriptor: OperationDescriptor;
+	readonly plan: unknown;
+	readonly state: JournalState;
+}
+
+export interface JournalStoreOptions {
+	readonly transactionsRoot: string;
+}
+
+export interface JournalPhaseOptions {
+	readonly observedLogicalLeaf?: string | null;
+}
+
+export type CursorMarkerInspection =
+	| { readonly kind: "absent" }
+	| { readonly kind: "match"; readonly needsTrailingNewline: boolean }
+	| { readonly kind: "conflict" };
+
+export interface RecoveryDecision {
+	readonly action: "rollback" | "roll_forward" | "lock" | "discard";
+	readonly reason: string;
+}
+
+export class JournalStore {
+	private readonly transactionsRoot: string;
+
+	constructor(options: JournalStoreOptions) {
+		this.transactionsRoot = options.transactionsRoot;
+	}
+
+	mutationJournal(opId: string): MutationJournal {
+		return new MutationJournal(join(this.operationDirectory(opId), "mutations.jsonl"), opId);
+	}
+
+	async prepare(descriptor: OperationDescriptor, plan: unknown): Promise<void> {
+		assertOperationDescriptor(descriptor);
+		if (!isPlanForDescriptor(plan, descriptor)) {
+			throw new Error("restore plan 与 descriptor 不匹配");
+		}
+		const directory = this.operationDirectory(descriptor.opId);
+		await writeContentAddressed(join(directory, "descriptor.json"), Buffer.from(canonicalJson(descriptor), "utf8"));
+		await writeContentAddressed(join(directory, "restore-plan.json"), Buffer.from(canonicalJson(plan), "utf8"));
+		const statePath = join(directory, "state.json");
+		try {
+			const existing = assertJournalState(JSON.parse(await readFile(statePath, "utf8")));
+			if (existing.opId !== descriptor.opId || existing.descriptorChecksum !== descriptor.checksum) {
+				throw new Error("已存在 journal state 与 descriptor 不匹配");
+			}
+		} catch (error) {
+			if (!hasErrorCode(error, "ENOENT")) {
+				throw error;
+			}
+			await writeJsonAtomic(statePath, makeState(descriptor, "PREPARED", 1));
+		}
+	}
+
+	async setPhase(opId: string, phase: JournalPhase, options: JournalPhaseOptions = {}): Promise<void> {
+		const pending = await this.load(opId);
+		if (!canTransition(pending.state.phase, phase)) {
+			throw new Error(`journal phase 不能回退或跳跃：${pending.state.phase} -> ${phase}`);
+		}
+		const observedLogicalLeaf = options.observedLogicalLeaf === undefined
+			? pending.state.observedLogicalLeaf
+			: options.observedLogicalLeaf;
+		await writeJsonAtomic(
+			join(this.operationDirectory(opId), "state.json"),
+			makeState(pending.descriptor, phase, pending.state.revision + 1, observedLogicalLeaf),
+		);
+	}
+
+	async loadPending(): Promise<readonly PendingJournal[]> {
+		let entries;
+		try {
+			entries = await readdir(this.transactionsRoot, { withFileTypes: true });
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) return [];
+			throw error;
+		}
+		const result: PendingJournal[] = [];
+		for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+			if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+			try {
+				const state = await lstat(join(this.transactionsRoot, entry.name, "state.json"));
+				if (!state.isFile() || state.isSymbolicLink()) throw new Error("journal state 文件类型无效");
+			} catch (error) {
+				if (hasErrorCode(error, "ENOENT")) continue;
+				throw error;
+			}
+			const journal = await this.load(entry.name);
+			if (journal.state.phase !== "COMMITTED" && journal.state.phase !== "ABORTED") {
+				result.push(journal);
+			}
+		}
+		return result;
+	}
+
+	async markCommitted(opId: string): Promise<void> {
+		await this.mutationJournal(opId).assertCleaned();
+		await this.setPhase(opId, "COMMITTED");
+	}
+
+	/** 仅在恢复器已经重新验证 workspace 与 cursor 后，允许中间 phase 收敛到终态。 */
+	async settleRecovery(opId: string, phase: "COMMITTED" | "ABORTED"): Promise<void> {
+		await this.mutationJournal(opId).assertCleaned();
+		const pending = await this.load(opId);
+		if (pending.state.phase === phase) return;
+		if (pending.state.phase === "COMMITTED" || pending.state.phase === "ABORTED") {
+			throw new Error("journal 已处于不同终态");
+		}
+		await writeJsonAtomic(
+			join(this.operationDirectory(opId), "state.json"),
+			makeState(
+				pending.descriptor,
+				phase,
+				pending.state.revision + 1,
+				pending.state.observedLogicalLeaf,
+			),
+		);
+	}
+
+	async removeIfSettled(opId: string): Promise<void> {
+		const pending = await this.load(opId);
+		if (pending.state.phase !== "COMMITTED" && pending.state.phase !== "ABORTED") {
+			return;
+		}
+		await rm(this.operationDirectory(opId), { recursive: true, force: true });
+	}
+
+	private async load(opId: string): Promise<PendingJournal> {
+		const directory = this.operationDirectory(opId);
+		const [descriptorBytes, planBytes, stateBytes] = await Promise.all([
+			readFile(join(directory, "descriptor.json"), "utf8"),
+			readFile(join(directory, "restore-plan.json"), "utf8"),
+			readFile(join(directory, "state.json"), "utf8"),
+		]);
+		const descriptor = assertOperationDescriptor(JSON.parse(descriptorBytes));
+		if (descriptor.opId !== opId) {
+			throw new Error("journal directory 与 descriptor opId 不匹配");
+		}
+		const plan: unknown = JSON.parse(planBytes);
+		if (!isPlanForDescriptor(plan, descriptor)) {
+			throw new Error("journal restore plan 与 descriptor 不匹配");
+		}
+		const state = assertJournalState(JSON.parse(stateBytes));
+		if (state.opId !== descriptor.opId || state.descriptorChecksum !== descriptor.checksum) {
+			throw new Error("journal state 与 descriptor 不匹配");
+		}
+		return { descriptor, plan, state };
+	}
+
+	private operationDirectory(opId: string): string {
+		if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(opId)) {
+			throw new Error("journal opId 无效");
+		}
+		return join(this.transactionsRoot, opId);
+	}
+}
+
+export async function inspectCursorMarkers(
+	sessionFile: string,
+	descriptor: OperationDescriptor,
+): Promise<CursorMarkerInspection> {
+	assertOperationDescriptor(descriptor);
+	let content: string;
+	try {
+		content = await readFile(sessionFile, "utf8");
+	} catch (error) {
+		if (hasErrorCode(error, "ENOENT")) return { kind: "absent" };
+		throw error;
+	}
+	const lines = content.split("\n");
+	const finalLine = lines.length - 1;
+	let matched: string | undefined;
+	let needsTrailingNewline = false;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (line === undefined || line.trim() === "") continue;
+		let entry: unknown;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (!isCursorEntry(entry)) continue;
+		const rawData = entry.data;
+		const rawOpId = isRecord(rawData) && typeof rawData.opId === "string" ? rawData.opId : undefined;
+		let cursor: CursorState;
+		try {
+			cursor = assertCursor(rawData);
+		} catch {
+			if (rawOpId === descriptor.opId) return { kind: "conflict" };
+			continue;
+		}
+		if (cursor.opId !== descriptor.opId) continue;
+		if (!matchesDescriptor(cursor, descriptor)) return { kind: "conflict" };
+		const encoded = canonicalJson(cursor);
+		if (matched !== undefined && matched !== encoded) return { kind: "conflict" };
+		matched = encoded;
+		needsTrailingNewline = index === finalLine && !content.endsWith("\n");
+	}
+	return matched === undefined ? { kind: "absent" } : { kind: "match", needsTrailingNewline };
+}
+
+export function decideRecovery(inspection: CursorMarkerInspection): RecoveryDecision {
+	if (inspection.kind === "match") return { action: "roll_forward", reason: "durable_cursor" };
+	if (inspection.kind === "absent") return { action: "rollback", reason: "cursor_absent" };
+	return { action: "lock", reason: "cursor_conflict" };
+}
+
+export async function finalizeCursorMarker(
+	sessionFile: string,
+	descriptor: OperationDescriptor,
+	inspection: Extract<CursorMarkerInspection, { kind: "match" }>,
+): Promise<void> {
+	if (inspection.needsTrailingNewline) {
+		await appendFile(sessionFile, "\n");
+	}
+	await fsyncFile(sessionFile);
+	await fsyncDirectory(dirname(sessionFile));
+	const verified = await inspectCursorMarkers(sessionFile, descriptor);
+	if (verified.kind !== "match" || verified.needsTrailingNewline) {
+		throw new Error("cursor marker 耐久化校验失败");
+	}
+}
+
+function makeState(
+	descriptor: OperationDescriptor,
+	phase: JournalPhase,
+	revision: number,
+	observedLogicalLeaf?: string | null,
+): JournalState {
+	const content = {
+		schemaVersion: 1 as const,
+		opId: descriptor.opId,
+		phase,
+		revision,
+		descriptorChecksum: descriptor.checksum,
+		...(observedLogicalLeaf === undefined ? {} : { observedLogicalLeaf }),
+	};
+	return { ...content, checksum: checksum(canonicalJson(content)) };
+}
+
+function canTransition(current: JournalPhase, next: JournalPhase): boolean {
+	if (current === next || current === "COMMITTED" || current === "ABORTED") return false;
+	if (next === "RECOVERY_REQUIRED") return true;
+	if (next === "ABORTING") return current !== "ABORTING";
+	if (next === "ABORTED") return current === "ABORTING";
+	const order: JournalPhase[] = [
+		"PREPARED", "SESSION_MOVED", "APPLYING", "FILES_VERIFIED", "CURSOR_COMMITTED", "COMMITTED",
+	];
+	return order.indexOf(next) === order.indexOf(current) + 1;
+}
+
+function matchesDescriptor(cursor: CursorState, descriptor: OperationDescriptor): boolean {
+	return cursor.descriptorChecksum === descriptor.checksum &&
+		cursor.action === descriptor.action &&
+		cursor.targetManifestId === descriptor.targetManifestId &&
+		cursor.rollbackManifestId === descriptor.rollbackManifestId &&
+		cursor.sessionIdentity.path === descriptor.sessionIdentity.path &&
+		cursor.sessionIdentity.headerChecksum === descriptor.sessionIdentity.headerChecksum;
+}
+
+function isPlanForDescriptor(value: unknown, descriptor: OperationDescriptor): boolean {
+	return isRecord(value) && value.planDigest === descriptor.planDigest;
+}
+
+function isCursorEntry(value: unknown): value is { type: "custom"; customType: "pi-undo:cursor"; data: unknown } {
+	return isRecord(value) && value.type === "custom" && value.customType === "pi-undo:cursor";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}