@dshtrading/dsh-home 0.5.0 → 0.6.1

package/lib/file-lock.d.ts

@@ -0,0 +1,17 @@
+//#region src/file-lock.d.ts
+interface HomeFileLockOptions {
+  /** 等锁上限（毫秒）；超时抛错，不静默降级。 */
+  readonly timeoutMs?: number;
+  /** 锁文件 mtime 超过该毫秒数视为陈旧（持锁者已崩溃），可被后来者回收。 */
+  readonly staleMs?: number;
+}
+/** 等锁超时：本次调用按「明确失败」处理，磁盘上的数据保持持锁者的版本。 */
+declare class HomeFileLockTimeoutError extends Error {
+  readonly lockPath: string;
+  readonly timeoutMs: number;
+  constructor(lockPath: string, timeoutMs: number);
+}
+/** 在跨进程锁内执行 work；无论成功失败都释放锁（进程崩溃时由陈旧阈值兜底）。 */
+declare function withHomeFileLock<T>(filePath: string, work: () => Promise<T>, options?: HomeFileLockOptions): Promise<T>;
+//#endregion
+export { HomeFileLockOptions, HomeFileLockTimeoutError, withHomeFileLock };

package/lib/file-lock.js

@@ -0,0 +1,100 @@
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import { mkdir, open, rename, stat, unlink, utimes } from "node:fs/promises";
+//#region src/file-lock.ts
+/**
+* home 数据文件的跨进程排他锁（2026-10-09 事故「多进程整表回写互相覆盖」的机制基座）。
+*
+* 为什么不是 flock/fcntl：Node 无内建 flock，Windows 与网络盘语义不一致；锁文件
+* （O_EXCL 创建 + pid/host/心跳 mtime）三平台一致，且持锁进程崩溃后可由后来者按
+* 陈旧阈值回收——不依赖持锁者自己清理。
+*
+* 语义：进入临界区前必得锁；拿不到时等待（缺省 5s），仍拿不到抛
+* {@link HomeFileLockTimeoutError}——「明确告知失败」这条出路，绝不静默按陈旧
+* 快照写盘。持锁期间的临界区应只包住「读盘 + 合并 + 原子写」这一小段。
+*/
+/** 等锁超时：本次调用按「明确失败」处理，磁盘上的数据保持持锁者的版本。 */
+var HomeFileLockTimeoutError = class extends Error {
+	lockPath;
+	timeoutMs;
+	constructor(lockPath, timeoutMs) {
+		super(`waiting for home file lock ${lockPath} timed out after ${timeoutMs}ms (another process holds it; this process wrote nothing)`);
+		this.name = "HomeFileLockTimeoutError";
+		this.lockPath = lockPath;
+		this.timeoutMs = timeoutMs;
+	}
+};
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_STALE_MS = 3e4;
+const RETRY_MS = 15;
+const delay = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+/**
+* 陈旧锁回收：返回 true 表示可立刻重试拿锁（锁已不在，或已被本次回收）。
+*
+* 抢占用 rename 做原子裁决（同一陈旧 inode 只可能被一个进程搬走）；搬走后复核
+* mtime，若发现抢到的是别人刚重建的新锁（极窄窗口），原样搬回，避免误删活锁。
+*/
+async function reclaimIfStale(lockPath, staleMs) {
+	let ageMs;
+	try {
+		ageMs = Date.now() - (await stat(lockPath)).mtimeMs;
+	} catch {
+		return true;
+	}
+	if (ageMs <= staleMs) return false;
+	const claimPath = `${lockPath}.stale-${process.pid}-${Date.now()}`;
+	try {
+		await rename(lockPath, claimPath);
+	} catch {
+		return true;
+	}
+	const claimed = await stat(claimPath).catch(() => void 0);
+	if (claimed !== void 0 && Date.now() - claimed.mtimeMs <= staleMs) {
+		await rename(claimPath, lockPath).catch(() => unlink(claimPath).catch(() => {}));
+		return false;
+	}
+	await unlink(claimPath).catch(() => {});
+	console.warn(`[dsh-home] reclaimed stale home file lock ${lockPath} (mtime older than ${staleMs}ms; the holding process likely crashed)`);
+	return true;
+}
+/** 在跨进程锁内执行 work；无论成功失败都释放锁（进程崩溃时由陈旧阈值兜底）。 */
+async function withHomeFileLock(filePath, work, options = {}) {
+	const lockPath = `${filePath}.lock`;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	await mkdir(dirname(filePath), { recursive: true });
+	const deadline = Date.now() + timeoutMs;
+	let handle;
+	while (handle === void 0) {
+		try {
+			handle = await open(lockPath, "wx");
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		if (handle !== void 0) break;
+		if (Date.now() >= deadline) throw new HomeFileLockTimeoutError(lockPath, timeoutMs);
+		if (await reclaimIfStale(lockPath, staleMs)) continue;
+		await delay(RETRY_MS);
+	}
+	const heartbeat = setInterval(() => {
+		const now = /* @__PURE__ */ new Date();
+		utimes(lockPath, now, now).catch(() => {});
+	}, Math.max(1e3, Math.floor(staleMs / 3)));
+	heartbeat.unref?.();
+	try {
+		await handle.writeFile(JSON.stringify({
+			pid: process.pid,
+			host: hostname(),
+			at: Date.now()
+		}), "utf8");
+		return await work();
+	} finally {
+		clearInterval(heartbeat);
+		await handle.close().catch(() => {});
+		await unlink(lockPath).catch(() => {});
+	}
+}
+//#endregion
+export { HomeFileLockTimeoutError, withHomeFileLock };

package/lib/index.d.ts

@@ -1,10 +1,20 @@
 import { writeJsonAtomic } from "./fs-atomic.js";
+import { HomeFileLockOptions, HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
+import { SKIP_WRITE, SkipWrite, TransactStoreOptions, transactStore } from "./store-transaction.js";
 //#region src/index.d.ts
 /**
  * 解析 dsh home 根目录。
  * @param env 环境变量映射，缺省读 `process.env`；空白 `$DSH_HOME` 视为未设。
+ * @param options.warn 告警出口（缺省写 stderr；测试注入以便断言）。
+ *
+ * **告警（不改返回值）**：解析结果落在缺省 home（`~/.dsh`）而 `~/.dsh-trading` 存在时，打一行告警。
+ * 场景是 2026-10-01 实测过的：agent 会话继承宿主的 `DSH_HOME=~/.dsh`，于是交易数据被解析到宿主 home ——
+ * 而这一切**不会报错**，脚本照常"成功"，只是作用在另一个实例的数据上。
+ * 这一行只把"静默跑错 home"变成"响亮但可忽略"：**返回值、优先级、语义全不变**（改默认值属于架构决策，另议）。
  */
-declare function dshHomeDir(env?: Record<string, string | undefined>): string;
+declare function dshHomeDir(env?: Record<string, string | undefined>, options?: {
+  readonly warn?: ((message: string) => void) | undefined;
+}): string;
 /** 缺省 home（`~/.dsh`）——迁移判据用：解析结果等于它就没有旧 home 可迁。 */
 declare function defaultDshHome(): string;
 /**
@@ -51,4 +61,4 @@ interface LegacyHomeMigrationResult {
  */
 declare function migrateLegacyTradingHome(options?: LegacyHomeMigrationOptions): LegacyHomeMigrationResult | null;
 //#endregion
-export { HOME_MIGRATION_MARKER, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, writeJsonAtomic };
+export { HOME_MIGRATION_MARKER, type HomeFileLockOptions, HomeFileLockTimeoutError, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, SKIP_WRITE, type SkipWrite, TRADING_HOME_ENTRIES, type TransactStoreOptions, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, transactStore, withHomeFileLock, writeJsonAtomic };

package/lib/index.js

@@ -1,4 +1,6 @@
 import { writeJsonAtomic } from "./fs-atomic.js";
+import { HomeFileLockTimeoutError, withHomeFileLock } from "./file-lock.js";
+import { SKIP_WRITE, transactStore } from "./store-transaction.js";
 import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -14,6 +16,16 @@ import { join, resolve } from "node:path";
 * （2026-09-08 DSH_HOME 分离，note: implemented/process/2026-09-08-separate-dsh-home.md）。
 */
 const DEFAULT_HOME_DIR_NAME = ".dsh";
+/** 交易 home 的目录名（与 CLI wrapper / 各脚本的约定一致）。 */
+const TRADING_HOME_DIR_NAME = ".dsh-trading";
+/** stderr 去重标记（**去重只发生在默认出口**：注入的 warn 每次都调，测试才确定）。 */
+let warnedToStderr = false;
+/** 默认告警出口：写 stderr，且进程内只写一次（脏日志比没有日志更糟）。 */
+function warnOnceToStderr(message) {
+	if (warnedToStderr) return;
+	warnedToStderr = true;
+	process.stderr.write(message + String.fromCharCode(10));
+}
 /** 展开 `~` 与 `~/` 前缀（对齐宿主 expandHomePath；Windows 反斜杠前缀同样接受）。 */
 function expandHomePath(path) {
 	const home = homedir();
@@ -24,11 +36,19 @@ function expandHomePath(path) {
 /**
 * 解析 dsh home 根目录。
 * @param env 环境变量映射，缺省读 `process.env`；空白 `$DSH_HOME` 视为未设。
+* @param options.warn 告警出口（缺省写 stderr；测试注入以便断言）。
+*
+* **告警（不改返回值）**：解析结果落在缺省 home（`~/.dsh`）而 `~/.dsh-trading` 存在时，打一行告警。
+* 场景是 2026-10-01 实测过的：agent 会话继承宿主的 `DSH_HOME=~/.dsh`，于是交易数据被解析到宿主 home ——
+* 而这一切**不会报错**，脚本照常"成功"，只是作用在另一个实例的数据上。
+* 这一行只把"静默跑错 home"变成"响亮但可忽略"：**返回值、优先级、语义全不变**（改默认值属于架构决策，另议）。
 */
-function dshHomeDir(env = process.env) {
+function dshHomeDir(env = process.env, options = {}) {
 	const fromEnv = env.DSH_HOME;
 	const configured = fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : resolve(homedir(), DEFAULT_HOME_DIR_NAME);
-	return resolve(expandHomePath(configured));
+	const resolvedHome = resolve(expandHomePath(configured));
+	if (resolvedHome === defaultDshHome() && existsSync(resolve(homedir(), TRADING_HOME_DIR_NAME))) (options.warn ?? warnOnceToStderr)("[dsh-home] 解析到缺省 home " + resolvedHome + "，而本机存在 " + resolve(homedir(), TRADING_HOME_DIR_NAME) + "：交易数据可能正被写到宿主 home。若这不是本意，请显式设置 DSH_HOME=" + resolve(homedir(), TRADING_HOME_DIR_NAME) + "。（本告警不影响返回值）");
+	return resolvedHome;
 }
 /** 缺省 home（`~/.dsh`）——迁移判据用：解析结果等于它就没有旧 home 可迁。 */
 function defaultDshHome() {
@@ -121,4 +141,4 @@ function migrateLegacyTradingHome(options = {}) {
 	};
 }
 //#endregion
-export { HOME_MIGRATION_MARKER, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, writeJsonAtomic };
+export { HOME_MIGRATION_MARKER, HomeFileLockTimeoutError, SKIP_WRITE, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, transactStore, withHomeFileLock, writeJsonAtomic };

package/lib/store-transaction.d.ts

@@ -0,0 +1,26 @@
+//#region src/store-transaction.d.ts
+/** mutate 返回它表示「本次无内容变化」：不落盘，但缓存仍取锁内新鲜值。 */
+declare const SKIP_WRITE: unique symbol;
+/** {@link SKIP_WRITE} 的类型形态：写 mutate 签名时用它标注「可能无变化」。 */
+type SkipWrite = typeof SKIP_WRITE;
+interface TransactStoreOptions {
+  /** 等锁上限（毫秒）；超时抛 {@link HomeFileLockTimeoutError}。 */
+  readonly timeoutMs?: number;
+  /** 陈旧锁回收阈值（毫秒）。 */
+  readonly staleMs?: number;
+}
+/**
+ * 在跨进程锁内读-改-写一份 JSON 表。
+ *
+ * @param filePath - 目标 JSON 文件
+ * @param readFromDisk - **新鲜**读盘（不得回传内存缓存）；由各 store 提供 parse
+ *   感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
+ * @param mutate - 在锁内新鲜值上做本次修改；返回新内存值，或 {@link SKIP_WRITE}
+ *   表示无变化不落盘
+ * @param serialize - 新内存值 → 落盘形状（数组、按 id 为键的对象、容器包裹皆可）
+ * @param logPrefix - 失败日志前缀，与各 store 原 writeJsonAtomic 调用逐字一致
+ * @returns 落盘后的当前值（SKIP_WRITE 时即锁内新鲜值）
+ */
+declare function transactStore<T>(filePath: string, readFromDisk: () => Promise<T>, mutate: (onDisk: T) => T | SkipWrite | Promise<T | SkipWrite>, serialize: (value: T) => unknown, logPrefix: string, options?: TransactStoreOptions): Promise<T>;
+//#endregion
+export { SKIP_WRITE, SkipWrite, TransactStoreOptions, transactStore };

package/lib/store-transaction.js

@@ -0,0 +1,62 @@
+import { writeJsonAtomic } from "./fs-atomic.js";
+import { withHomeFileLock } from "./file-lock.js";
+//#region src/store-transaction.ts
+/**
+* 整表 JSON 的跨进程「锁内读 - 改 - 原子写」（2026-10-09 事故修复的共享入口）。
+*
+* 背景：下列 store 都是「进程内内存缓存 + 整表回写」，两个宿主进程共用同一
+* DSH_HOME 时后写者用自己那份陈旧快照覆盖先写者（last-writer-wins，静默丢数据；
+* 实测抹掉 indicators/chart.json 的 symbolParams 与 hiddenScopes）。
+*
+* {@link transactStore} 是全仓唯一的跨进程临界区实现，各 store 只调它，不各自复制：
+* 1. 取该文件的跨进程排他锁（{@link withHomeFileLock}）；
+* 2. 锁内**新鲜重读磁盘**（readFromDisk，不是进临界区前的缓存）；
+* 3. mutate 在这份新鲜值上做本次修改并返回新的内存值；
+* 4. tmp+rename 原子写落盘，返回值即调用方应缓存的当前值。
+*
+* 「读 - 改」整体在锁内，所以两个进程各自的**新增、删除**都不丢：后到者是在先到者的
+* 结果上继续改，而不是用陈旧快照覆盖。这是「先读回并合并双方数据」的具体形态，
+* 而不是「拒绝第二实例写」——本机桌面端与 CLI 长期共用同一 home，拒绝写会让第二
+* 实例完全存不了设置。等锁超时抛 {@link HomeFileLockTimeoutError}：那是明确失败，
+* 绝不静默按陈旧快照覆盖。
+*
+* 合并粒度是条目（行表按 id、嵌套表按各自键）：同一条目被两个进程同时改时，后写者
+* 在该条目上的整条值胜出（不做字段级三方合并，见 note 的 Residue）。
+*
+* 幂等 no-op（删除不存在的 id、重复写入同值）由调用方在 mutate 里返回
+* {@link SKIP_WRITE} 表达——此时不落盘（保持既有「无变化不重写」语义），返回值仍是
+* 锁内新鲜读到的值，调用方缓存照旧刷新。
+*/
+/** 合并入口的缺省等锁上限：比 store 内部调用更宽松，避免正常并发被误判超时。 */
+const DEFAULT_TIMEOUT_MS = 1e4;
+/** mutate 返回它表示「本次无内容变化」：不落盘，但缓存仍取锁内新鲜值。 */
+const SKIP_WRITE = Symbol("dsh-home:skip-write");
+function lockOptionsOf(options) {
+	return {
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		...options.staleMs !== void 0 ? { staleMs: options.staleMs } : {}
+	};
+}
+/**
+* 在跨进程锁内读-改-写一份 JSON 表。
+*
+* @param filePath - 目标 JSON 文件
+* @param readFromDisk - **新鲜**读盘（不得回传内存缓存）；由各 store 提供 parse
+*   感知的读取，使坏形/坏 JSON 的降级口径与自身 load() 一致
+* @param mutate - 在锁内新鲜值上做本次修改；返回新内存值，或 {@link SKIP_WRITE}
+*   表示无变化不落盘
+* @param serialize - 新内存值 → 落盘形状（数组、按 id 为键的对象、容器包裹皆可）
+* @param logPrefix - 失败日志前缀，与各 store 原 writeJsonAtomic 调用逐字一致
+* @returns 落盘后的当前值（SKIP_WRITE 时即锁内新鲜值）
+*/
+async function transactStore(filePath, readFromDisk, mutate, serialize, logPrefix, options = {}) {
+	return withHomeFileLock(filePath, async () => {
+		const onDisk = await readFromDisk();
+		const next = await mutate(onDisk);
+		if (next === SKIP_WRITE) return onDisk;
+		await writeJsonAtomic(filePath, serialize(next), logPrefix);
+		return next;
+	}, lockOptionsOf(options));
+}
+//#endregion
+export { SKIP_WRITE, transactStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/dsh-home",
   "description": "dsh home 根目录解析（$DSH_HOME 环境变量感知，缺省 ~/.dsh，对齐宿主 dsh-home-paths 语义）——dsh-trading 各包 home 数据文件的唯一路径来源",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",