@narumitw/pi-sync 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-sync",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"description": "Pi extension that syncs Pi configuration through Cloudflare R2 or S3-compatible storage.",
 	"type": "module",
 	"license": "MIT",
@@ -28,9 +28,13 @@
 		"format": "biome check --write .",
 		"typecheck": "tsc --noEmit"
 	},
+	"dependencies": {
+		"proper-lockfile": "^4.1.2"
+	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.3",
 		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@types/proper-lockfile": "^4.1.4",
 		"typescript": "7.0.2"
 	},
 	"repository": {

package/src/config.ts

@@ -1,17 +1,15 @@
-import { randomUUID } from "node:crypto";
 import type { Dirent } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isDeniedPath, safeName } from "./paths.js";
-import type { LockFile, PartialConfig, Snapshot, SyncConfig, SyncState } from "./types.js";
+import type { PartialConfig, Snapshot, SyncConfig, SyncState } from "./types.js";
 
 const VERSION = 1;
 const DEFAULT_PROFILE = "default";
 const DEFAULT_PREFIX = "pi-sync";
 const DEFAULT_REGION = "auto";
-const LOCK_STALE_MS = 30 * 60 * 1000;
 const TOP_LEVEL_FILES = new Set(["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md"]);
 const TOP_LEVEL_FILE_NAMES = new Set([...TOP_LEVEL_FILES].map((name) => name.toLowerCase()));
 const TOP_LEVEL_DIRS = new Set(["skills", "prompts", "themes", "extensions"]);
@@ -42,37 +40,6 @@ function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext)
 		: undefined;
 }
 
-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 handle: fs.FileHandle | undefined;
-	try {
-		handle = await fs.open(lockPath(), "wx");
-		await handle.writeFile(JSON.stringify(lock, null, "\t"));
-		await handle.close();
-		handle = undefined;
-		return await fn();
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
-			const current = await readLock();
-			if (current && isStaleLock(current)) {
-				throw new Error(`pi-sync lock is stale (pid ${current.pid}). Run /pisync unlock --stale, then retry.`);
-			}
-			throw new Error(`pi-sync is already running${current ? ` (${current.command}, pid ${current.pid}, started ${current.startedAt})` : ""}.`);
-		}
-		throw error;
-	} finally {
-		await handle?.close();
-		const current = await readLock();
-		if (current?.id === lock.id) await fs.rm(lockPath(), { force: true });
-	}
-}
-
 export async function loadConfigInternal(): Promise<SyncConfig> {
 	const partial = await loadPartialConfig();
 	const endpoint = partial.endpoint;
@@ -204,21 +171,6 @@ export async function ensureStateDir() {
 	await fs.mkdir(stateDir(), { recursive: true });
 }
 
-export async function readLock() {
-	return readJsonIfExists<LockFile>(lockPath());
-}
-
-export function isStaleLock(lock: LockFile) {
-	if (!Number.isInteger(lock.pid) || lock.pid <= 0) return true;
-	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;
-	}
-}
-
 async function readJsonIfExists<T>(filePath: string): Promise<T | undefined> {
 	try {
 		return JSON.parse(await fs.readFile(filePath, "utf8")) as T;

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 /pisync 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 /pisync 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 /pisync 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/sync.ts

@@ -12,12 +12,9 @@ import {
 	ensureStateDir,
 	extraFilePathsByLower,
 	isMissingConfigError,
-	isStaleLock,
 	loadPartialConfig,
 	localConfigPath,
-	lockPath,
 	normalizeExtraFiles,
-	readLock,
 	stateDir,
 	writeJson,
 	configuredSessionDir,
@@ -29,9 +26,9 @@ import {
 	sessionDirForApply,
 	sessionTokenWarnings,
 	syncSessionsWarnings,
-	withLock,
 	writeState,
 } from "./config.js";
+import { inspectLock, isLockGuardHeld, isStaleLock, unlock, withLock } from "./lock.js";
 import { encodeKey, posixJoin, safeJoin, safeName, toPosix } from "./paths.js";
 import {
 	historyKey,
@@ -346,8 +343,25 @@ async function doctor(ctx: ExtensionCommandContext) {
 		messages.push(`secret scan: ok (${local.files.length} files checked)`);
 	}
 
-	const lock = await readLock();
-	messages.push(lock ? `lock: held by pid ${lock.pid} since ${lock.startedAt}` : "lock: free");
+	const lock = await inspectLock();
+	if (lock.status === "valid" && isStaleLock(lock.lock)) {
+		level = "warning";
+		messages.push(
+			`lock: stale (pid ${lock.lock.pid}); run /pisync unlock after verifying no sync is running`,
+		);
+	} else if (lock.status === "valid") {
+		messages.push(`lock: held by pid ${lock.lock.pid} since ${lock.lock.startedAt}`);
+	} else if (lock.status === "unreadable") {
+		level = "warning";
+		messages.push(
+			"lock: unreadable; use /pisync unlock --stale only after verifying no sync is running",
+		);
+	} else if (await isLockGuardHeld()) {
+		level = "warning";
+		messages.push("lock: guard active while metadata is missing or still being initialized");
+	} else {
+		messages.push("lock: free");
+	}
 	ctx.ui.notify(messages.join("\n"), level);
 }
 
@@ -619,20 +633,6 @@ async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
 	await maybeReload(ctx);
 }
 
-async function unlock(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const lock = await readLock();
-	if (!lock) {
-		ctx.ui.notify("No pi-sync lock is present.", "info");
-		return;
-	}
-	if (!options.stale && !isStaleLock(lock)) {
-		ctx.ui.notify("Lock is not stale. Use /pisync unlock --stale only after verifying no sync is running.", "warning");
-		return;
-	}
-	await fs.rm(lockPath(), { force: true });
-	ctx.ui.notify("Removed stale pi-sync lock.", "info");
-}
-
 function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext) {
 	const getSessionFile = ctx.sessionManager.getSessionFile;
 	if (typeof getSessionFile !== "function") return new Set<string>();