@zhushanwen/pi-file-lock 0.1.1

package/index.ts

@@ -0,0 +1,7 @@
+// Re-export barrel：pi 包惯例（源码在 src/，包根 index.ts 只做转发）。
+export {
+	withFileLock,
+	withFileLockSync,
+	type FileLockOptions,
+	type SyncFileLockOptions,
+} from "./src/file-lock.ts";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@zhushanwen/pi-file-lock",
+  "version": "0.1.1",
+  "description": "Shared async cross-process file lock for Pi extensions — proper-lockfile wrapper with stale takeover and exponential-backoff retries, aligned with the runtime-side lock protocol (shared library, not a Pi extension).",
+  "type": "module",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "lock",
+    "lockfile",
+    "cross-process",
+    "shared"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/file-lock.test.ts

@@ -0,0 +1,149 @@
+// src/__tests__/file-lock.test.ts
+//
+// 跨进程文件锁单测（真实文件系统，不 mock fs）：
+//   - async/sync 版临界区互斥（并发不交错）
+//   - unlock 后可再锁（finally 释放语义）
+//   - sync 版 fail-fast（ELOCKED 预算耗尽抛错，不用默认 1s——测试覆盖盖短预算）
+//   - 真实跨进程互斥：两个 node 子进程并发 RMW 同一 JSON 文件，计数零丢失
+//     （「两写方并发不丢条目」的 D5a/D1e 核心验收形态）
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { withFileLock, withFileLockSync } from "../file-lock.ts";
+
+const PKG_DIR = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+describe("withFileLock (async)", () => {
+	let tmpDir: string;
+	let target: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-test-"));
+		target = path.join(tmpDir, "target.json");
+	});
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+	it("并发临界区互斥：计数无交错丢失", async () => {
+		let counter = 0;
+		const inside: number[] = [];
+		const tasks = Array.from({ length: 20 }, () =>
+			withFileLock(target, async () => {
+				counter += 1;
+				inside.push(counter);
+				// 让出 event loop 制造无锁时必交错的窗口
+				await new Promise((r) => setTimeout(r, 1));
+			}),
+		);
+		await Promise.all(tasks);
+		expect(counter).toBe(20);
+		// 每个临界区进入时的 counter 单调 +1（无两个临界区读到同值）
+		expect(new Set(inside).size).toBe(20);
+	});
+
+	it("fn 抛错也释放锁（finally 语义：后续可再锁）", async () => {
+		await expect(
+			withFileLock(target, async () => {
+				throw new Error("boom");
+			}),
+		).rejects.toThrow("boom");
+		// 同一 target 立即可再锁 = 前次已释放
+		await expect(withFileLock(target, async () => "ok")).resolves.toBe("ok");
+	});
+
+	it("锁内 RMW：并发各 +1 一百次，文件终值 100（丢更新=锁失效）", async () => {
+		fs.writeFileSync(target, JSON.stringify({ n: 0 }), "utf-8");
+		const bump = (): Promise<void> =>
+			withFileLock(target, async () => {
+				const cur = JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number };
+				cur.n += 1;
+				fs.writeFileSync(target, JSON.stringify(cur), "utf-8");
+			});
+		await Promise.all(Array.from({ length: 100 }, bump));
+		expect((JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number }).n).toBe(100);
+	});
+});
+
+describe("withFileLockSync", () => {
+	let tmpDir: string;
+	let target: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-sync-test-"));
+		target = path.join(tmpDir, "target.json");
+	});
+	afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
+
+	it("返回 fn 结果且锁已释放（可立即再锁）", () => {
+		expect(withFileLockSync(target, () => 42)).toBe(42);
+		expect(withFileLockSync(target, () => "again")).toBe("again");
+	});
+
+	it("fn 抛错也释放锁", () => {
+		expect(() =>
+			withFileLockSync(target, () => {
+				throw new Error("boom");
+			}),
+		).toThrow("boom");
+		expect(withFileLockSync(target, () => "ok")).toBe("ok");
+	});
+
+	it("ELOCKED fail-fast：预算耗尽抛带 code 的错误（不用默认 1s 预算）", () => {
+		// 先占锁（外层 sync 锁），再在 fn 内嵌套取锁 → 必 ELOCKED → 短预算快速失败
+		expect(() =>
+			withFileLockSync(
+				target,
+				() =>
+					withFileLockSync(target, () => "never", {
+						staleMs: 60_000, // stale 远大于预算，锁不会被夺取
+						retryDelayMs: 10,
+						retryBudgetMs: 30,
+					}),
+				{ staleMs: 60_000 },
+			),
+		).toThrowError(/ELOCKED 重试预算 30ms 耗尽/);
+	});
+});
+
+describe("真实跨进程互斥（D5a/D1e 验收形态）", () => {
+	it("两个子进程并发 RMW 同一 JSON 各 50 次，终值 100 零丢失", () => {
+		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "file-lock-xproc-"));
+		const target = path.join(tmpDir, "shared.json");
+		fs.writeFileSync(target, JSON.stringify({ n: 0 }), "utf-8");
+		try {
+			// 子进程脚本：--experimental-strip-types 直接跑 TS（Node >= 22.6），
+			// 循环 50 次锁内读-改-写。exitCode 非 0 = 子进程自身失败（锁/IO 异常）。
+			const worker = `
+import * as fs from "node:fs";
+import { withFileLock } from "${PKG_DIR}/src/file-lock.ts";
+const target = process.argv[2];
+for (let i = 0; i < 50; i++) {
+	await withFileLock(target, async () => {
+		const cur = JSON.parse(fs.readFileSync(target, "utf-8"));
+		cur.n += 1;
+		fs.writeFileSync(target, JSON.stringify(cur), "utf-8");
+	});
+}
+`;
+			const workerFile = path.join(tmpDir, "worker.ts");
+			fs.writeFileSync(workerFile, worker, "utf-8");
+			const procs = [1, 2].map(() =>
+				spawnSync(process.execPath, ["--experimental-strip-types", workerFile, target], {
+					encoding: "utf-8",
+					timeout: 60_000,
+				}),
+			);
+			for (const p of procs) {
+				expect(p.status).toBe(0);
+			}
+			expect((JSON.parse(fs.readFileSync(target, "utf-8")) as { n: number }).n).toBe(100);
+		} finally {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+});

package/src/file-lock.ts

@@ -0,0 +1,169 @@
+// src/file-lock.ts
+//
+// 跨进程异步文件锁（extension 侧共享 util，D5a/D1e，integrity-hardening.md §3.5）。
+//
+// 为什么存在：worktrees.json（多 pi 进程各一份扩展实例写）与 ext-config 家族
+// （runtime + 扩展双写）都是跨进程 RMW——Node 单线程只能保证进程内不交错，
+// 挡不住跨进程「后写者基于旧快照覆盖先写者」。
+//
+// 为什么是 async API 而非 runtime 侧的 withFileLockSync：扩展跑在 pi 子进程的
+// async hook 上下文（session_start 等），同步 busy-wait 会阻塞整个 event loop；
+// proper-lockfile 的 async lock() 原生支持 retries 指数退避（sync API 与 retries
+// 组合抛 ESYNC），不需要 runtime 侧那套自实现 busy-wait。
+//
+// 锁协议（与 runtime 侧 packages/runtime/src/utils/file-lock.ts 对齐，登记表
+// docs/architecture/data-source-registry.md §6）：
+//   - lockfile 路径 = <目标文件>.lock（proper-lockfile 默认，双方路径一致才互斥）
+//   - realpath:false —— 目标文件不存在也可锁（realpath 默认 true 时 ENOENT），
+//     与 runtime 侧参数一致；锁前确保父目录存在
+//   - stale 30s：持锁进程崩溃后锁可被夺取（对齐 auth 惯例）
+//   - async 版 retries 指数退避：10 次 / factor 2 / 100ms~10s / randomize（对齐 pi
+//     FileAuthStorageBackend.withLockAsync，见 runtime auth-storage.ts:48-74 范本）
+//   - sync 版 busy-wait 重试（25ms / 预算 1s fail-fast）：对齐 runtime 侧
+//     withFileLockSync——proper-lockfile 的 sync API 与 retries 组合抛 ESYNC，
+//     重试必须在外层同步循环做；ext-config 家族的扩展侧写方（saveConfig）
+//     保持 sync 签名（调用链零波及），与 runtime 对端用同一把 lockfile 互斥
+//   - onCompromised：锁被判定 stale 夺取时标记，fn 执行前抛错——防止在失去
+//     互斥保证的锁下写盘（对齐 pi throwIfCompromised 语义）
+//
+// 契约：fn 内禁止任何 await / 再次对本文件加锁（嵌套取锁 ELOCKED → 重试耗尽 →
+// 抛错）；持锁范围应为「读文件 + 纯内存变更 + 原子写」，毫秒级。
+
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+import lockfile from "proper-lockfile";
+
+/** 锁参数（默认值对齐 auth-storage.ts 范本；测试可覆盖以缩短等待）。 */
+export interface FileLockOptions {
+	/** 锁 mtime 超过该值视为持锁者已死可夺取（stale 语义）。默认 30_000ms。 */
+	staleMs?: number;
+	/** retries 总次数。默认 10。 */
+	retries?: number;
+}
+
+/** sync 版锁参数（对齐 runtime withFileLockSync 默认值；测试可覆盖以缩短等待）。 */
+export interface SyncFileLockOptions {
+	/** 锁 mtime 超过该值视为持锁者已死可夺取（stale 语义）。默认 30_000ms。 */
+	staleMs?: number;
+	/** ELOCKED 重试间隔（同步 sleep）。默认 25ms。 */
+	retryDelayMs?: number;
+	/** ELOCKED 重试总预算，耗尽 fail-fast。默认 1_000ms。 */
+	retryBudgetMs?: number;
+}
+
+// 默认锁参数（sync 版导出供对照测试断言与 runtime 侧 utils/file-lock.ts 默认值相等
+// ——两侧参数漂移会破坏「同一把锁」的互斥语义；runtime 侧 test/file-lock-parity.test.ts）
+export const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_RETRIES = 10;
+export const DEFAULT_RETRY_DELAY_MS = 25;
+export const DEFAULT_RETRY_BUDGET_MS = 1_000;
+
+/**
+ * 跨进程文件锁内执行 async fn：拿不到锁时指数退避重试（100ms~10s/randomize），
+ * 重试耗尽抛 proper-lockfile 的 ELOCKED 错误（调用方决定降级路径）；
+ * unlock 放 finally（fn 抛错也释放，compromised 时 unlock 失败可忽略）。
+ */
+export async function withFileLock<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+	opts?: FileLockOptions,
+): Promise<T> {
+	// 锁前确保父目录存在：proper-lockfile 创建 lockfile（<目标>.lock）需要目录在
+	const dir = dirname(filePath);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+	// onCompromised：锁被 stale 夺取（进程卡死超时等）时标记，fn 执行前抛错，
+	// 防止在失去互斥保证的锁下写盘（对齐 pi throwIfCompromised）。
+	let compromised: Error | undefined;
+	const release = await lockfile.lock(filePath, {
+		realpath: false,
+		retries: {
+			retries: opts?.retries ?? DEFAULT_RETRIES,
+			factor: 2,
+			minTimeout: 100,
+			maxTimeout: 10_000,
+			randomize: true,
+		},
+		stale: opts?.staleMs ?? DEFAULT_STALE_MS,
+		onCompromised: (err: Error) => {
+			compromised = err;
+		},
+	});
+	try {
+		if (compromised) throw compromised;
+		return await fn();
+	} finally {
+		try {
+			await release();
+		} catch (unlockErr) {
+			// 锁已 compromised（被 stale 夺取）时 unlock 必然失败且可忽略——
+			// 记录留痕（对齐 pi finally 的 catch 语义：不外抛、不静默）。
+			console.debug(
+				"[file-lock] unlock failed after compromise (ignorable):",
+				unlockErr instanceof Error ? unlockErr.message : String(unlockErr),
+			);
+		}
+	}
+}
+
+/**
+ * 同步跨进程文件锁内执行 fn：lockSync(realpath:false) + ELOCKED busy-wait 重试，
+ * 预算耗尽抛带 ELOCKED code 的错误；unlock 放 finally（fn 抛错也释放）。
+ *
+ * 与 async 版锁同一把 lockfile（<目标文件>.lock）——sync/async API 在磁盘上
+ * 是同一协议，互斥不依赖调用形态。适用场景：调用链必须保持 sync 签名
+ * （如 llm-shared saveConfig，permission/rename-session 的命令回调零波及）。
+ * sleep 用 Atomics.wait（真 sleep 不烧 CPU，对齐 runtime 侧实现）。
+ */
+export function withFileLockSync<T>(
+	filePath: string,
+	fn: () => T,
+	opts?: SyncFileLockOptions,
+): T {
+	const staleMs = opts?.staleMs ?? DEFAULT_STALE_MS;
+	const retryDelayMs = opts?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+	const retryBudgetMs = opts?.retryBudgetMs ?? DEFAULT_RETRY_BUDGET_MS;
+
+	const dir = dirname(filePath);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+	const deadline = Date.now() + retryBudgetMs;
+	let release: (() => void) | undefined;
+	while (release === undefined) {
+		try {
+			release = lockfile.lockSync(filePath, { realpath: false, stale: staleMs });
+		} catch (err) {
+			if (!isElocked(err)) throw err;
+			if (Date.now() >= deadline) {
+				throw Object.assign(
+					new Error(
+						`[file-lock] ${filePath} 写锁获取失败：ELOCKED 重试预算 ${retryBudgetMs}ms 耗尽` +
+						`（持锁方临界区异常或已崩溃，stale ${staleMs}ms 后可夺取）。恢复指引：稍后重试本次写入。`,
+						// cause 挂原始 ELOCKED 错误，保留 proper-lockfile 诊断信息
+						{ cause: err },
+					),
+					{ code: "ELOCKED" },
+				);
+			}
+			sleepSync(retryDelayMs);
+		}
+	}
+	try {
+		return fn();
+	} finally {
+		release();
+	}
+}
+
+function isElocked(err: unknown): boolean {
+	// in 收窄而非 as 断言（extensions taste/no-unsafe-catch：全可选属性断言 = 无校验）
+	return err instanceof Error && "code" in err && err.code === "ELOCKED";
+}
+
+/** Atomics.wait 需要一个共享内存对象作等待目标；4 字节 = 一个 Int32 元素，仅占位不被写入。 */
+const SLEEP_WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+
+function sleepSync(ms: number): void {
+	Atomics.wait(SLEEP_WAIT_BUFFER, 0, 0, ms);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+	withFileLock,
+	withFileLockSync,
+	type FileLockOptions,
+	type SyncFileLockOptions,
+} from "./file-lock.ts";