@davideasden/pi-undo 0.1.0

package/src/model.ts

@@ -0,0 +1,160 @@
+export type RootState = "active" | "uninitialized" | "broken";
+
+export type ManifestId = string & {
+	readonly __manifestId: unique symbol;
+};
+
+export type TopologyFingerprint = string;
+export type WorkspaceFingerprint = string;
+
+export type ResultCode =
+	| "ok"
+	| "noop"
+	| "busy"
+	| "idle_timeout"
+	| "capture_failed"
+	| "restore_failed_safe"
+	| "partial_restore"
+	| "recovery_required"
+	| "history_paused"
+	| "refill_skipped"
+	| "refill_failed";
+
+export interface RootTopologyIdentity {
+	readonly relativeRoot: string;
+	readonly parentRoot: string | null;
+	readonly state: RootState;
+	readonly sourceIdentity: string;
+	readonly privateRepositoryId: string;
+	readonly gitlinkOid?: string;
+}
+
+export interface DiscoveryRoot extends RootTopologyIdentity {
+	readonly treeId: string | null;
+	readonly gitBacked: boolean;
+}
+
+export interface SnapshotRoot extends RootTopologyIdentity {
+	readonly treeId: string | null;
+	readonly coverage: string;
+	readonly ignorePolicy: string;
+	readonly ignoredPresentPaths: readonly string[];
+	readonly ignoreClosure: string;
+	readonly objectClosure: string;
+}
+
+export interface SnapshotManifest {
+	readonly schemaVersion: 1;
+	readonly manifestId: ManifestId;
+	readonly workspaceIdentity: WorkspaceFingerprint;
+	readonly topologyFingerprint: TopologyFingerprint;
+	readonly coverage: string;
+	readonly roots: readonly SnapshotRoot[];
+	readonly createdAt: string;
+}
+
+export interface CheckpointRecord {
+	readonly schemaVersion: 1;
+	readonly checkpointId: string;
+	readonly runId: string;
+	readonly sessionIdentity: SessionFileIdentity;
+	readonly startEntryId: string;
+	readonly userEntryId: string;
+	readonly endLeafId: string;
+	readonly rawPrompt: string;
+	readonly beforeManifestId: ManifestId;
+	readonly afterManifestId: ManifestId;
+	readonly changedPaths: readonly string[];
+	readonly checksum: string;
+}
+
+export interface SessionFileIdentity {
+	readonly path: string;
+	readonly headerChecksum: string;
+}
+
+export interface CursorState {
+	readonly schemaVersion: 1;
+	readonly opId: string;
+	readonly action: "undo" | "redo" | "tree";
+	readonly sessionIdentity: SessionFileIdentity;
+	readonly fromLogicalLeaf: string | null;
+	readonly toLogicalLeaf: string | null;
+	readonly targetManifestId: ManifestId;
+	readonly rollbackManifestId: ManifestId;
+	readonly undoHead: string | null;
+	readonly redoStack: readonly string[];
+	readonly descriptorChecksum: string;
+	readonly checksum: string;
+}
+
+export type JournalPhase =
+	| "PREPARING"
+	| "PREPARED"
+	| "SESSION_MOVED"
+	| "APPLYING"
+	| "FILES_VERIFIED"
+	| "CURSOR_COMMITTED"
+	| "COMMITTED"
+	| "ABORTING"
+	| "ABORTED"
+	| "RECOVERY_REQUIRED";
+
+export interface OperationDescriptor {
+	readonly schemaVersion: 1;
+	readonly opId: string;
+	readonly sessionIdentity: SessionFileIdentity;
+	readonly workspaceIdentity: WorkspaceFingerprint;
+	readonly action: "undo" | "redo" | "tree";
+	readonly fromLogicalLeaf: string | null;
+	readonly toLogicalLeaf: string | null;
+	readonly targetManifestId: ManifestId;
+	readonly rollbackManifestId: ManifestId;
+	readonly coverage: string;
+	readonly scopePaths: readonly string[];
+	readonly planDigest: string;
+	readonly checksum: string;
+}
+
+export interface JournalState {
+	readonly schemaVersion: 1;
+	readonly opId: string;
+	readonly phase: JournalPhase;
+	readonly revision: number;
+	readonly descriptorChecksum: string;
+	readonly observedLogicalLeaf?: string | null;
+	readonly checksum: string;
+}
+
+export type MutationState =
+	| "INTENT"
+	| "SOURCE_QUARANTINED"
+	| "SOURCE_VERIFIED"
+	| "TARGET_INSTALLED"
+	| "TARGET_VERIFIED"
+	| "CLEANED";
+
+export interface MutationRecord {
+	readonly schemaVersion: 1;
+	readonly opId: string;
+	readonly ordinal: number;
+	readonly state: MutationState;
+	readonly kind: "write" | "delete" | "symlink";
+	readonly path: string;
+	readonly sourceArtifact: string;
+	readonly targetArtifact: string | null;
+	readonly sourceFingerprint: string;
+	readonly targetFingerprint: string;
+	readonly previousChecksum: string | null;
+	readonly checksum: string;
+}
+
+export interface RestorePath {
+	readonly relativePath: string;
+	readonly kind: "file" | "directory" | "symlink";
+	readonly mode: number;
+	readonly blobId: string | null;
+	readonly size: number;
+	readonly rootHash: string;
+	readonly linkText?: string;
+}

package/src/mutation-journal.ts

@@ -0,0 +1,229 @@
+import { open, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { fsyncDirectory } from "./atomic-fs.ts";
+import { assertMutationRecord, assertOperationId, canonicalJson, checksum } from "./encoding.ts";
+import type { MutationRecord, MutationState } from "./model.ts";
+
+export interface MutationIntent {
+	readonly kind: MutationRecord["kind"];
+	readonly path: string;
+	readonly sourceArtifact: string;
+	readonly targetArtifact: string | null;
+	readonly sourceFingerprint: string;
+	readonly targetFingerprint: string;
+}
+
+const stateOrder: readonly MutationState[] = [
+	"INTENT",
+	"SOURCE_QUARANTINED",
+	"SOURCE_VERIFIED",
+	"TARGET_INSTALLED",
+	"TARGET_VERIFIED",
+	"CLEANED",
+];
+
+export class MutationJournal {
+	private readonly path: string;
+	private readonly opId: string;
+	private mutationQueue: Promise<void> = Promise.resolve();
+
+	constructor(path: string, opId: string) {
+		this.path = path;
+		this.opId = assertOperationId(opId);
+	}
+
+	get operationId(): string {
+		return this.opId;
+	}
+
+	get storagePath(): string {
+		return this.path;
+	}
+
+	async load(): Promise<readonly MutationRecord[]> {
+		return (await this.readRecords()).latest;
+	}
+
+	begin(intent: MutationIntent): Promise<MutationRecord> {
+		return this.enqueueMutation(() => this.beginMutation(intent));
+	}
+
+	private async beginMutation(intent: MutationIntent): Promise<MutationRecord> {
+		const current = await this.readRecords();
+		const content = {
+			schemaVersion: 1 as const,
+			opId: this.opId,
+			ordinal: current.latest.length + 1,
+			state: "INTENT" as const,
+			kind: intent.kind,
+			path: intent.path,
+			sourceArtifact: intent.sourceArtifact,
+			targetArtifact: intent.targetArtifact,
+			sourceFingerprint: intent.sourceFingerprint,
+			targetFingerprint: intent.targetFingerprint,
+			previousChecksum: current.tail?.checksum ?? null,
+		};
+		const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
+		await this.append(record, current.durableEnd, current.hasNonDurableTail);
+		return record;
+	}
+
+	advance(ordinal: number, state: MutationState): Promise<MutationRecord> {
+		return this.enqueueMutation(() => this.advanceMutation(ordinal, state));
+	}
+
+	markRollbackCleaned(ordinal: number): Promise<MutationRecord> {
+		return this.enqueueMutation(() => this.markRollbackCleanedMutation(ordinal));
+	}
+
+	private async markRollbackCleanedMutation(ordinal: number): Promise<MutationRecord> {
+		const current = await this.readRecords();
+		const previous = current.latest[ordinal - 1];
+		if (previous === undefined || previous.state === "CLEANED") {
+			throw new Error(`mutation rollback 终结状态无效：${previous?.state ?? "missing"}`);
+		}
+		return this.appendState(current, previous, "CLEANED");
+	}
+
+	private async advanceMutation(ordinal: number, state: MutationState): Promise<MutationRecord> {
+		const current = await this.readRecords();
+		const previous = current.latest[ordinal - 1];
+		if (previous === undefined || stateOrder.indexOf(state) !== stateOrder.indexOf(previous.state) + 1) {
+			throw new Error(`mutation state 必须严格推进：${previous?.state ?? "missing"} -> ${state}`);
+		}
+		return this.appendState(current, previous, state);
+	}
+
+	private async appendState(
+		current: Awaited<ReturnType<MutationJournal["readRecords"]>>,
+		previous: MutationRecord,
+		state: MutationState,
+	): Promise<MutationRecord> {
+		const content = {
+			schemaVersion: previous.schemaVersion,
+			opId: previous.opId,
+			ordinal: previous.ordinal,
+			state,
+			kind: previous.kind,
+			path: previous.path,
+			sourceArtifact: previous.sourceArtifact,
+			targetArtifact: previous.targetArtifact,
+			sourceFingerprint: previous.sourceFingerprint,
+			targetFingerprint: previous.targetFingerprint,
+			previousChecksum: current.tail?.checksum ?? null,
+		};
+		const record = assertMutationRecord({ ...content, checksum: checksum(canonicalJson(content)) });
+		await this.append(record, current.durableEnd, current.hasNonDurableTail);
+		return record;
+	}
+
+	private enqueueMutation<T>(operation: () => Promise<T>): Promise<T> {
+		const result = this.mutationQueue.then(operation);
+		this.mutationQueue = result.then(() => undefined, () => undefined);
+		return result;
+	}
+
+	async activeArtifacts(): Promise<ReadonlySet<string>> {
+		const artifacts = new Set<string>();
+		for (const record of await this.load()) {
+			if (record.state === "CLEANED") continue;
+			artifacts.add(record.sourceArtifact);
+			if (record.targetArtifact !== null) artifacts.add(record.targetArtifact);
+		}
+		return artifacts;
+	}
+
+	async assertCleaned(): Promise<void> {
+		if ((await this.load()).some((record) => record.state !== "CLEANED")) {
+			throw new Error("mutation journal 仍有未清理 artifact");
+		}
+	}
+
+	private async readRecords(): Promise<{
+		readonly latest: readonly MutationRecord[];
+		readonly tail: MutationRecord | undefined;
+		readonly durableEnd: number;
+		readonly hasNonDurableTail: boolean;
+	}> {
+		let bytes: Buffer;
+		try {
+			bytes = await readFile(this.path);
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) {
+				return { latest: [], tail: undefined, durableEnd: 0, hasNonDurableTail: false };
+			}
+			throw error;
+		}
+
+		const durableEnd = bytes.at(-1) === 0x0a ? bytes.length : bytes.lastIndexOf(0x0a) + 1;
+		const durable = bytes.subarray(0, durableEnd).toString("utf8");
+		const lines = durable === "" ? [] : durable.slice(0, -1).split("\n");
+		const latest: MutationRecord[] = [];
+		let tail: MutationRecord | undefined;
+
+		for (const line of lines) {
+			const record = assertMutationRecord(JSON.parse(line));
+			if (record.opId !== this.opId) throw new Error("mutation record opId 与 journal 不匹配");
+			if (record.previousChecksum !== (tail?.checksum ?? null)) {
+				throw new Error("mutation journal hash chain 断裂");
+			}
+
+			const previous = latest[record.ordinal - 1];
+			if (previous === undefined) {
+				if (record.ordinal !== latest.length + 1) throw new Error("mutation ordinal 不连续");
+				if (record.state !== "INTENT") throw new Error("mutation ordinal 必须从 INTENT 开始");
+			} else {
+				if (immutablePayload(previous) !== immutablePayload(record)) {
+					throw new Error("同一 mutation ordinal 的 immutable payload 冲突");
+				}
+				if (!isValidDurableTransition(previous.state, record.state)) {
+					throw new Error("mutation state 未严格推进");
+				}
+			}
+			latest[record.ordinal - 1] = record;
+			tail = record;
+		}
+
+		return { latest, tail, durableEnd, hasNonDurableTail: durableEnd !== bytes.length };
+	}
+
+	private async append(record: MutationRecord, durableEnd: number, hasNonDurableTail: boolean): Promise<void> {
+		const directory = dirname(this.path);
+		const handle = await open(this.path, "a+", 0o600);
+		try {
+			if (hasNonDurableTail) {
+				await handle.truncate(durableEnd);
+				await handle.sync();
+				await fsyncDirectory(directory);
+			}
+			await handle.writeFile(`${canonicalJson(record)}\n`);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await fsyncDirectory(directory);
+	}
+}
+
+function isValidDurableTransition(previous: MutationState, next: MutationState): boolean {
+	return stateOrder.indexOf(next) === stateOrder.indexOf(previous) + 1 ||
+		(next === "CLEANED" && previous !== "CLEANED");
+}
+
+function immutablePayload(record: MutationRecord): string {
+	return canonicalJson({
+		opId: record.opId,
+		ordinal: record.ordinal,
+		kind: record.kind,
+		path: record.path,
+		sourceArtifact: record.sourceArtifact,
+		targetArtifact: record.targetArtifact,
+		sourceFingerprint: record.sourceFingerprint,
+		targetFingerprint: record.targetFingerprint,
+	});
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/src/path-safety.ts

@@ -0,0 +1,121 @@
+import { lstat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export type PathSafetyErrorCode = "unsafe_path" | "symlink_escape";
+
+export class PathSafetyError extends Error {
+	readonly code: PathSafetyErrorCode;
+
+	constructor(code: PathSafetyErrorCode, message: string) {
+		super(message);
+		this.name = "PathSafetyError";
+		this.code = code;
+	}
+}
+
+export function relativeSafePath(root: string, candidate: string): string {
+	if (typeof root !== "string" || root.length === 0 || root.includes("\0")) {
+		fail("unsafe_path", "root 路径无效");
+	}
+	assertRelativeCandidate(candidate);
+	if (candidate === ".") {
+		return candidate;
+	}
+
+	const canonicalRoot = resolve(root);
+	const absoluteCandidate = resolve(canonicalRoot, candidate);
+	const canonicalRelative = relative(canonicalRoot, absoluteCandidate);
+	if (
+		canonicalRelative === ".." ||
+		canonicalRelative.startsWith(`..${sep}`) ||
+		isAbsolute(canonicalRelative)
+	) {
+		fail("unsafe_path", "candidate 不在 root 内或不是规范路径");
+	}
+	return candidate;
+}
+
+export async function assertNoSymlinkEscape(root: string, relativePath: string): Promise<void> {
+	const safePath = relativeSafePath(root, relativePath);
+	if (safePath === ".") {
+		return;
+	}
+
+	let current = resolve(root);
+	const parts = safePath.split("/");
+	for (let index = 0; index < parts.length; index += 1) {
+		current = join(current, parts[index]);
+		try {
+			const metadata = await lstat(current);
+			if (index < parts.length - 1) {
+				if (metadata.isSymbolicLink()) {
+					fail("symlink_escape", "中间路径组件不能是 symlink");
+				}
+				if (!metadata.isDirectory()) {
+					fail("unsafe_path", "中间路径组件不是目录");
+				}
+			}
+		} catch (error) {
+			if (hasErrorCode(error, "ENOENT")) {
+				return;
+			}
+			throw error;
+		}
+	}
+}
+
+export function sortDeletePaths(paths: readonly string[]): string[] {
+	return sortPaths(paths, -1);
+}
+
+export function sortWritePaths(paths: readonly string[]): string[] {
+	return sortPaths(paths, 1);
+}
+
+function sortPaths(paths: readonly string[], direction: -1 | 1): string[] {
+	for (const path of paths) {
+		assertRelativeCandidate(path);
+	}
+	return [...paths].sort((left, right) => {
+		const depthDifference = pathDepth(left) - pathDepth(right);
+		if (depthDifference !== 0) {
+			return depthDifference * direction;
+		}
+		return comparePaths(left, right);
+	});
+}
+
+function assertRelativeCandidate(candidate: string): void {
+	if (
+		typeof candidate !== "string" ||
+		candidate.length === 0 ||
+		candidate.includes("\0") ||
+		candidate.includes("\\") ||
+		isAbsolute(candidate) ||
+		/^[A-Za-z]:/.test(candidate)
+	) {
+		fail("unsafe_path", "candidate 必须是相对 POSIX 路径");
+	}
+	if (candidate === ".") {
+		return;
+	}
+	if (candidate.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+		fail("unsafe_path", "candidate 包含不安全路径组件");
+	}
+}
+
+function pathDepth(path: string): number {
+	return path === "." ? 0 : path.split("/").length;
+}
+
+function comparePaths(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function hasErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function fail(code: PathSafetyErrorCode, message: string): never {
+	throw new PathSafetyError(code, message);
+}