@zhushanwen/pi-llm-shared 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime caching. Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
@@ -17,6 +17,9 @@
     "src/",
     "index.ts"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-file-lock": "0.1.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*"
@@ -32,6 +35,7 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "scripts": {

package/src/__tests__/config.test.ts

@@ -1,10 +1,11 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import * as fs from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { clearConfigCache, getConfigPath, loadConfig, saveConfig } from "../config.ts";
+import * as fileLock from "@zhushanwen/pi-file-lock";
 
 // node:fs 的 ESM namespace 不可配置，vi.spyOn 对具名导出失效（vitest 限制）。
 // 用 vi.mock 包装 readFileSync/renameSync（默认走 actual，个别 test override），
@@ -128,6 +129,12 @@ describe("loadConfig", () => {
 });
 
 describe("saveConfig", () => {
+	/** tmp 残留断言（D1e 唯一化后 tmp 名为 <path>.tmp_<pid>_<rand>，用前缀 glob 断言）。 */
+	function tmpResidues(pkg: string): string[] {
+		const cfgDir = join(dir, "config");
+		return readdirSync(cfgDir).filter((f) => f.startsWith(`${pkg}-ext-config.json.tmp`));
+	}
+
 	it("TC16 原子写：文件落盘 + 内容正确 + 无 tmp 残留", () => {
 		const result = saveConfig("test", { b: 2 });
 		expect(result.success).toBe(true);
@@ -135,7 +142,7 @@ describe("saveConfig", () => {
 		const cfgPath = join(dir, "config", "test-ext-config.json");
 		expect(existsSync(cfgPath)).toBe(true);
 		expect(JSON.parse(readFileSync(cfgPath, "utf-8"))).toEqual({ b: 2 });
-		expect(existsSync(`${cfgPath}.tmp`)).toBe(false); // 无 tmp 残留
+		expect(tmpResidues("test")).toEqual([]); // 无 tmp 残留（唯一化 tmp 名，前缀断言）
 	});
 
 	it("TC16 文件 mode 0o600", () => {
@@ -164,8 +171,8 @@ describe("saveConfig", () => {
 
 		expect(result.success).toBe(false);
 		expect(result.error).toContain("EPERM");
-		// tmp 文件被 catch 块的 unlinkSync 清理
-		expect(existsSync(join(dir, "config", "fail-ext-config.json.tmp"))).toBe(false);
+		// tmp 文件被 catch 块的 unlinkSync 清理（唯一化 tmp 名，前缀断言）
+		expect(tmpResidues("fail")).toEqual([]);
 		// 目标文件未被创建（rename 失败）
 		expect(existsSync(join(dir, "config", "fail-ext-config.json"))).toBe(false);
 	});
@@ -185,9 +192,10 @@ describe("saveConfig", () => {
 		expect(onWarning).toHaveBeenCalledTimes(1);
 		const warning = String(onWarning.mock.calls[0][0]);
 		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "enoent-ext-config.json") + "'");
+		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "enoent-ext-config.json") + "'");
 		expect(warning).toContain("ENOENT");
-		// tmp 清理 + 目标未创建
-		expect(existsSync(join(dir, "config", "enoent-ext-config.json.tmp"))).toBe(false);
+		// tmp 清理（前缀断言）+ 目标未创建
+		expect(tmpResidues("enoent")).toEqual([]);
 		expect(existsSync(join(dir, "config", "enoent-ext-config.json"))).toBe(false);
 	});
 
@@ -204,8 +212,8 @@ describe("saveConfig", () => {
 		const warning = String(onWarning.mock.calls[0][0]);
 		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "eperm-ext-config.json") + "'");
 		expect(warning).toContain("EPERM");
-		// tmp 清理（Windows 目标占用场景 rename 失败后 tmp 残留被清理）
-		expect(existsSync(join(dir, "config", "eperm-ext-config.json.tmp"))).toBe(false);
+		// tmp 清理（Windows 目标占用场景 rename 失败后 tmp 残留被清理；前缀断言）
+		expect(tmpResidues("eperm")).toEqual([]);
 		expect(existsSync(join(dir, "config", "eperm-ext-config.json"))).toBe(false);
 	});
 
@@ -214,4 +222,26 @@ describe("saveConfig", () => {
 		expect(saveConfig("test", { v: 2 }).success).toBe(true);
 		expect(JSON.parse(readFileSync(join(dir, "config", "test-ext-config.json"), "utf-8"))).toEqual({ v: 2 });
 	});
+
+	it("W4 锁不可用（ELOCKED 预算耗尽）→ {success:false} + 不降级无锁写（目标文件不落盘）", () => {
+		// 模拟 runtime 对端长期持锁：withFileLockSync 抛 ELOCKED。扩展侧契约 =
+		// 不降级无锁写（降级会与 runtime 持锁写交错丢字段），按保存失败返回。
+		const lockErr = Object.assign(new Error("[file-lock] lock unavailable: ELOCKED"), { code: "ELOCKED" });
+		const spy = vi.spyOn(fileLock, "withFileLockSync").mockImplementation(() => {
+			throw lockErr;
+		});
+		const onWarning = vi.fn();
+
+		try {
+			const result = saveConfig("lockbusy", { x: 1 }, onWarning);
+
+			expect(result.success).toBe(false);
+			expect(result.error).toContain("lock unavailable");
+			expect(onWarning).toHaveBeenCalledTimes(1);
+			// 关键：未降级写盘（无锁写会破坏与 runtime 的互斥）
+			expect(existsSync(join(dir, "config", "lockbusy-ext-config.json"))).toBe(false);
+		} finally {
+			spy.mockRestore();
+		}
+	});
 });

package/src/config.ts

@@ -23,6 +23,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync,
 import { dirname, join } from "node:path";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { withFileLockSync } from "@zhushanwen/pi-file-lock";
 
 /** JSON 序列化缩进格数（permission/config.ts 同款）。 */
 const JSON_INDENT = 2;
@@ -114,13 +115,35 @@ export function loadConfig<T>(
 	}
 }
 
-// ──────────────────────── 保存（原子写） ────────────────────────
+// ──────────────────────── 保存（锁内原子写） ────────────────────────
 
 /**
- * 保存配置（原子写：tmp 文件 + rename）。
+ * 生成并发唯一的 tmp 文件名（D1e 附带风险修复：双侧 tmp 中间文件同名 `<path>.tmp`
+ * 并发可碰撞——runtime 侧 atomicWrite 未传 uniqueSuffix 也是固定名，扩展侧唯一化
+ * 后两侧名字空间不相交，碰撞面消除）。
+ *
+ * 后缀 = pid + 36 进制随机段：同进程多写方（多 session）与跨进程写方均不重名。
+ */
+const TMP_RANDOM_BASE = 36;
+const TMP_RANDOM_SLICE_START = 2; // 跳过 Math.random 字符串的 "0." 前缀
+const TMP_RANDOM_SLICE_END = 10;
+function uniqueTmpPath(configPath: string): string {
+	return `${configPath}.tmp_${process.pid}_${Math.random().toString(TMP_RANDOM_BASE).slice(TMP_RANDOM_SLICE_START, TMP_RANDOM_SLICE_END)}`;
+}
+
+/**
+ * 保存配置（锁内原子写：withFileLockSync + tmp 文件 + rename）。
  *
  * @returns 成功 {success:true}；失败 {success:false, error}
  *
+ * 🔒 跨进程锁（D1e/W4，integrity-hardening.md §3.1，登记表 §6 rename-session 行）：
+ * ext-config 家族被 xyz runtime（如 setRenameModel 写 model 字段，W1b 已持锁）与
+ * pi 子进程内扩展（本函数）双写。互斥只依赖同一 lockfile（<config>.lock），本侧
+ * withFileLockSync 协议与 runtime 侧 settings.json 写锁逐字对齐（realpath:false +
+ * stale 30s + busy-wait 1s 预算 fail-fast）。锁获取失败不降级无锁写——对端
+ * runtime 可能正持锁写，无锁写会交错丢字段；返回 {success:false} 由调用方按
+ * 保存失败处理（下次 save 重试）。
+ *
  * 原子性：writeFileSync(tmp) + renameSync(tmp→target)，rename 是原子的（POSIX/Windows）。
  * tmp 失败清理（review RK3）：writeFileSync 或 renameSync 抛错时，catch 块 unlinkSync(tmp)
  * 清理残留 tmp 文件（unlink 本身 try/catch，避免二次抛错）。
@@ -137,44 +160,55 @@ export function saveConfig(
 	onWarning?: (msg: string) => void,
 ): { success: boolean; error?: string } {
 	const configPath = getConfigPath(pkgName);
-	const tmpPath = `${configPath}.tmp`;
+	const tmpPath = uniqueTmpPath(configPath);
 	const content = `${JSON.stringify(config, null, JSON_INDENT)}\n`;
 
-	try {
-		mkdirSync(dirname(configPath), { recursive: true });
-		writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
-		renameSync(tmpPath, configPath);
-
-		// 写后更新缓存（用新文件 mtime+size + 写入的 config）
+	const writeLocked = (): { success: boolean; error?: string } => {
 		try {
-			const newStat = statSync(configPath);
-			configCache.set(configPath, {
-				mtimeMs: newStat.mtimeMs,
-				size: newStat.size,
-				config: clone(config),
-			});
-		} catch (statErr) {
-			// stat 失败不影响保存成功；缓存下次 load 时会重读
-			console.warn(
-				`[llm-shared] saveConfig stat after write failed:`,
-				statErr instanceof Error ? statErr.message : String(statErr),
-			);
+			mkdirSync(dirname(configPath), { recursive: true });
+			writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+			renameSync(tmpPath, configPath);
+
+			// 写后更新缓存（用新文件 mtime+size + 写入的 config）
+			try {
+				const newStat = statSync(configPath);
+				configCache.set(configPath, {
+					mtimeMs: newStat.mtimeMs,
+					size: newStat.size,
+					config: clone(config),
+				});
+			} catch (statErr) {
+				// stat 失败不影响保存成功；缓存下次 load 时会重读
+				console.warn(
+					`[llm-shared] saveConfig stat after write failed:`,
+					statErr instanceof Error ? statErr.message : String(statErr),
+				);
+			}
+
+			return { success: true };
+		} catch (error) {
+			// RK3: 清理残留 tmp 文件（writeFileSync 或 renameSync 失败时 tmp 可能残留）
+			try {
+				if (existsSync(tmpPath)) unlinkSync(tmpPath);
+			} catch (cleanupErr) {
+				// tmp 清理失败不能阻塞保存失败的返回；记录原因
+				console.warn(
+					`[llm-shared] saveConfig tmp cleanup failed:`,
+					cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+				);
+			}
+			const message = error instanceof Error ? error.message : String(error);
+			onWarning?.(`[llm-shared] Failed to save config at '${configPath}': ${message}`);
+			return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
 		}
+	};
 
-		return { success: true };
-	} catch (error) {
-		// RK3: 清理残留 tmp 文件（writeFileSync 或 renameSync 失败时 tmp 可能残留）
-		try {
-			if (existsSync(tmpPath)) unlinkSync(tmpPath);
-		} catch (cleanupErr) {
-			// tmp 清理失败不能阻塞保存失败的返回；记录原因
-			console.warn(
-				`[llm-shared] saveConfig tmp cleanup failed:`,
-				cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
-			);
-		}
-		const message = error instanceof Error ? error.message : String(error);
-		onWarning?.(`[llm-shared] Failed to save config at '${configPath}': ${message}`);
-		return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
+	try {
+		return withFileLockSync(configPath, writeLocked);
+	} catch (lockErr) {
+		// 锁获取失败（ELOCKED 预算耗尽等）：不降级无锁写（见 docstring），按保存失败返回
+		const message = lockErr instanceof Error ? lockErr.message : String(lockErr);
+		onWarning?.(`[llm-shared] Config write lock unavailable at '${configPath}': ${message}`);
+		return { success: false, error: `Config write lock unavailable at '${configPath}': ${message}` };
 	}
 }