@narumitw/pi-sync 0.24.0 → 0.28.0

package/src/lock.ts

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+} from "node:fs";
+import fs from "node:fs/promises";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
+import { ensureStateDir, lockPath } from "./config.js";
+import type { CommandOptions, LockFile } from "./types.js";
+
+const LOCK_STALE_MS = 30 * 60 * 1000;
+const GUARD_STALE_MS = 30_000;
+const GUARD_UPDATE_MS = 10_000;
+const MAX_PROCESS_ID = 2_147_483_647;
+
+type LockfileFsAdapter = {
+	mkdir: typeof mkdir;
+	mkdirSync: typeof mkdirSync;
+	realpath: typeof realpath;
+	realpathSync: typeof realpathSync;
+	rmdir: typeof rmdir;
+	rmdirSync: typeof rmdirSync;
+	stat: typeof stat;
+	statSync: typeof statSync;
+	utimes: typeof utimes;
+	utimesSync: typeof utimesSync;
+};
+
+const LOCKFILE_FS_ADAPTER: LockfileFsAdapter = {
+	mkdir,
+	mkdirSync,
+	realpath,
+	realpathSync,
+	rmdir,
+	rmdirSync,
+	stat,
+	statSync,
+	utimes,
+	utimesSync,
+};
+
+interface Guard {
+	release: () => Promise<void>;
+	throwIfCompromised: () => void;
+	isCompromised: () => boolean;
+}
+
+export type LockInspection =
+	| { status: "missing" }
+	| { status: "unreadable" }
+	| { status: "valid"; lock: LockFile };
+
+export async function withLock<T>(command: string, fn: () => Promise<T>): Promise<T> {
+	await ensureStateDir();
+	const lock: LockFile = {
+		id: randomUUID(),
+		pid: process.pid,
+		command,
+		startedAt: new Date().toISOString(),
+	};
+	let guard: Guard | undefined;
+	let result: T | undefined;
+	let failed = false;
+	let failure: unknown;
+	try {
+		try {
+			guard = await acquireGuard();
+		} catch (error) {
+			if (!isLockHeldError(error)) throw error;
+			throw await describeHeldLock();
+		}
+
+		const inspection = await inspectLock();
+		if (inspection.status === "valid" && isStaleLock(inspection.lock)) {
+			throw new Error(
+				`pi-sync lock is stale (pid ${inspection.lock.pid}). Run /sync unlock --stale, then retry.`,
+			);
+		}
+		if (inspection.status === "valid") {
+			throw new Error(
+				`pi-sync is already running (${inspection.lock.command}, pid ${inspection.lock.pid}, started ${inspection.lock.startedAt}).`,
+			);
+		}
+		if (inspection.status === "unreadable") {
+			throw new Error(
+				"pi-sync lock metadata is unreadable. Run /sync unlock --stale after verifying no sync is running.",
+			);
+		}
+
+		await fs.writeFile(lockPath(), JSON.stringify(lock, null, "\t"), { flag: "wx" });
+		guard.throwIfCompromised();
+		result = await fn();
+		guard.throwIfCompromised();
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+
+	try {
+		const current = await readLock();
+		if (current?.id === lock.id) await fs.rm(lockPath(), { force: true });
+	} catch (error) {
+		if (!failed) {
+			failed = true;
+			failure = error;
+		}
+	}
+	if (guard) {
+		const releaseError = await releaseGuard(guard);
+		if (releaseError && !failed) {
+			failed = true;
+			failure = releaseError;
+		}
+	}
+	if (failed) throw failure;
+	return result as T;
+}
+
+export async function inspectLock(): Promise<LockInspection> {
+	try {
+		const text = await fs.readFile(lockPath(), "utf8");
+		if (text.trim().length === 0) return { status: "unreadable" };
+		const parsed = JSON.parse(text) as unknown;
+		return isLockFile(parsed) ? { status: "valid", lock: parsed } : { status: "unreadable" };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { status: "missing" };
+		if (error instanceof SyntaxError) return { status: "unreadable" };
+		throw error;
+	}
+}
+
+export async function readLock(): Promise<LockFile | undefined> {
+	const inspection = await inspectLock();
+	return inspection.status === "valid" ? inspection.lock : undefined;
+}
+
+export async function lockFileExists(): Promise<boolean> {
+	try {
+		await fs.stat(lockPath());
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+export function isLockGuardHeld() {
+	return lockfile.check(lockPath(), {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: `${lockPath()}.guard`,
+		realpath: false,
+		stale: GUARD_STALE_MS,
+	});
+}
+
+export function isStaleLock(lock: LockFile) {
+	try {
+		process.kill(lock.pid, 0);
+		return false;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ESRCH") return true;
+		return Date.now() - Date.parse(lock.startedAt) > LOCK_STALE_MS;
+	}
+}
+
+export async function unlock(ctx: ExtensionCommandContext, options: CommandOptions) {
+	await ensureStateDir();
+	let guard: Guard;
+	try {
+		guard = await acquireGuard();
+	} catch (error) {
+		if (!isLockHeldError(error)) throw error;
+		ctx.ui.notify((await describeHeldLock()).message, "warning");
+		return;
+	}
+
+	let failed = false;
+	let failure: unknown;
+	try {
+		await unlockGuarded(ctx, options);
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+	const releaseError = await releaseGuard(guard);
+	if (releaseError && !failed) {
+		failed = true;
+		failure = releaseError;
+	}
+	if (failed) throw failure;
+}
+
+async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptions) {
+	let inspection = await inspectLock();
+	if (inspection.status === "missing") {
+		ctx.ui.notify("No pi-sync lock is present.", "info");
+		return;
+	}
+	if (inspection.status === "unreadable") {
+		if (!options.stale) {
+			ctx.ui.notify(
+				"Pi-sync lock metadata is unreadable. Use /sync unlock --stale only after verifying no sync is running.",
+				"warning",
+			);
+			return;
+		}
+		inspection = await inspectLock();
+		if (inspection.status === "unreadable") {
+			// Legacy writers expose an empty file before writing owner metadata, so no
+			// automatic test can prove this file is abandoned. The explicit --stale
+			// flag is the user's confirmation that no legacy sync is still running.
+			await fs.rm(lockPath(), { force: true });
+			ctx.ui.notify("Removed unreadable pi-sync lock.", "info");
+			return;
+		}
+		if (inspection.status === "missing") {
+			ctx.ui.notify("No pi-sync lock is present.", "info");
+			return;
+		}
+	}
+	if (!isStaleLock(inspection.lock)) {
+		ctx.ui.notify("Lock owner is still live; refusing to remove it.", "warning");
+		return;
+	}
+	await fs.rm(lockPath(), { force: true });
+	ctx.ui.notify("Removed stale pi-sync lock.", "info");
+}
+
+async function releaseGuard(guard: Guard) {
+	try {
+		await guard.release();
+		return undefined;
+	} catch (error) {
+		return guard.isCompromised() ? undefined : error;
+	}
+}
+
+async function acquireGuard(): Promise<Guard> {
+	let compromisedError: Error | undefined;
+	const release = await lockfile.lock(lockPath(), {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: `${lockPath()}.guard`,
+		realpath: false,
+		stale: GUARD_STALE_MS,
+		update: GUARD_UPDATE_MS,
+		onCompromised: (error) => {
+			compromisedError = error;
+		},
+	});
+	return {
+		release,
+		throwIfCompromised: () => {
+			if (compromisedError) throw compromisedError;
+		},
+		isCompromised: () => compromisedError !== undefined,
+	};
+}
+
+async function describeHeldLock() {
+	const current = await readLock();
+	if (current && isStaleLock(current)) {
+		return new Error("pi-sync lock owner exited; retry shortly while the lock guard expires.");
+	}
+	if (current) {
+		return new Error(
+			`Pi-sync is currently running (${current.command}, pid ${current.pid}, started ${current.startedAt}).`,
+		);
+	}
+	return new Error(
+		"Pi-sync is currently running (lock metadata is unreadable or still being written).",
+	);
+}
+
+function isLockHeldError(error: unknown) {
+	return (error as NodeJS.ErrnoException).code === "ELOCKED";
+}
+
+function isLockFile(value: unknown): value is LockFile {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const lock = value as Partial<LockFile>;
+	return (
+		typeof lock.id === "string" &&
+		lock.id.length > 0 &&
+		Number.isInteger(lock.pid) &&
+		(lock.pid ?? 0) > 0 &&
+		(lock.pid ?? 0) <= MAX_PROCESS_ID &&
+		typeof lock.command === "string" &&
+		lock.command.length > 0 &&
+		typeof lock.startedAt === "string" &&
+		Number.isFinite(Date.parse(lock.startedAt))
+	);
+}

package/src/snapshot-apply.ts

@@ -3,7 +3,14 @@ import type { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { agentDir } from "./config.js";
-import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "./paths.js";
+import {
+	assertWithinRoot,
+	isDeniedPath,
+	isPathInside,
+	parentPaths,
+	safeJoin,
+	toPosix,
+} from "./paths.js";
 import {
 	createSnapshot,
 	isSessionFilePath,
@@ -25,11 +32,12 @@ function fileHashMap(snapshot: Snapshot) {
 export async function applySnapshot(
 	snapshot: Snapshot,
 	protectedRelativePaths = new Set<string>(),
-	options: Pick<SnapshotOptions, "sessionDir" | "extraFiles"> = {},
+	options: Pick<SnapshotOptions, "syncFiles" | "sessionDir" | "extraFiles"> = {},
 ) {
 	const root = agentDir();
 	const { sessionDir } = options;
 	const current = await createSnapshot(snapshot.profile, {
+		syncFiles: options.syncFiles,
 		syncSessions: snapshotIncludesSessions(snapshot),
 		sessionDir,
 		extraFiles: options.extraFiles,
@@ -79,7 +87,8 @@ export function preflightSnapshotApply(
 
 		const target = snapshotTarget(root, normalized, options.sessionDir);
 		const content = decodeBase64Strict(file.contentBase64, normalized);
-		if (sha256(content) !== file.sha256) throw new Error(`Checksum mismatch in snapshot file: ${normalized}`);
+		if (sha256(content) !== file.sha256)
+			throw new Error(`Checksum mismatch in snapshot file: ${normalized}`);
 		writes.push({ target, content });
 	}
 
@@ -108,7 +117,9 @@ export function protectSnapshotApplyPlan(
 ): SnapshotApplyPlan {
 	if (protectedRelativePaths.size === 0) return plan;
 	const protectedTargets = new Set(
-		[...protectedRelativePaths].map((relativePath) => snapshotTarget(root, relativePath, sessionDir)),
+		[...protectedRelativePaths].map((relativePath) =>
+			snapshotTarget(root, relativePath, sessionDir),
+		),
 	);
 	return {
 		writes: plan.writes.filter((item) => !protectedTargets.has(item.target)),
@@ -141,7 +152,11 @@ export async function addTopLevelCaseVariantDeletes(
 	const deletes = new Set(plan.deletes);
 	for (const entry of entries) {
 		const canonicalPath = topLevelPaths.get(entry.name.toLowerCase());
-		if (canonicalPath && entry.name !== canonicalPath && (entry.isFile() || entry.isSymbolicLink())) {
+		if (
+			canonicalPath &&
+			entry.name !== canonicalPath &&
+			(entry.isFile() || entry.isSymbolicLink())
+		) {
 			deletes.add(safeJoin(root, entry.name));
 		}
 	}
@@ -198,7 +213,11 @@ async function preflightSnapshotMutations(
 		await assertNoSymlinkParents(rootForTarget(root, target, sessionDir), target);
 	}
 	for (const item of plan.writes) {
-		await prepareSnapshotWrite(rootForTarget(root, item.target, sessionDir), item.target, deletePaths);
+		await prepareSnapshotWrite(
+			rootForTarget(root, item.target, sessionDir),
+			item.target,
+			deletePaths,
+		);
 	}
 }
 
@@ -212,7 +231,8 @@ async function prepareSnapshotWrite(root: string, target: string, deletePaths: S
 	await ensureSafeDirectory(root, path.dirname(target));
 	try {
 		const stat = await fs.lstat(target);
-		if (stat.isSymbolicLink()) throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
+		if (stat.isSymbolicLink())
+			throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
 		if (stat.isDirectory() && !deletePaths.has(target)) {
 			throw new Error(`Refusing to overwrite directory during snapshot apply: ${target}`);
 		}
@@ -230,8 +250,10 @@ async function ensureSafeDirectory(root: string, directory: string) {
 		current = path.join(current, part);
 		try {
 			const stat = await fs.lstat(current);
-			if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
-			if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
+			if (stat.isSymbolicLink())
+				throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
+			if (!stat.isDirectory())
+				throw new Error(`Snapshot path parent is not a directory: ${current}`);
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 			await fs.mkdir(current);
@@ -249,8 +271,10 @@ async function assertNoSymlinkParents(root: string, target: string) {
 		current = path.join(current, part);
 		try {
 			const stat = await fs.lstat(current);
-			if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
-			if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
+			if (stat.isSymbolicLink())
+				throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
+			if (!stat.isDirectory())
+				throw new Error(`Snapshot path parent is not a directory: ${current}`);
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
 			throw error;