@dshtrading/dsh-home 0.1.6 → 0.2.1

package/lib/fs-atomic.d.ts

@@ -0,0 +1,4 @@
+//#region src/fs-atomic.d.ts
+declare function writeJsonAtomic(filePath: string, data: unknown, logPrefix: string): Promise<void>;
+//#endregion
+export { writeJsonAtomic };

package/lib/fs-atomic.js

@@ -0,0 +1,37 @@
+import { dirname } from "node:path";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+//#region src/fs-atomic.ts
+/**
+* home 数据文件原子写单一实现（2026-09-09 收敛，原为 7 个包的 9+ 处同体副本）：
+* tmp（唯一名）+ rename，EPERM/EBUSY（Windows 目标占用）25ms 退避重试 3 次；
+* 重试耗尽或任何失败保留旧文件、清理 tmp、log + throw——目标文件永远只被
+* 原子 rename 触碰，绝不非原子直写（半截写会损坏 JSON 导致 load 静默重置）。
+*
+* logPrefix 是失败日志在文件路径之前的完整前缀，逐字保留各调用方既有日志
+* （如 '[dsh-trading/knowledge] failed to atomic flush knowledge cards to'）。
+*/
+async function writeJsonAtomic(filePath, data, logPrefix) {
+	const dir = dirname(filePath);
+	const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+	const text = JSON.stringify(data, null, 2);
+	try {
+		await mkdir(dir, { recursive: true });
+		await writeFile(tmpPath, text, "utf8");
+		let lastError;
+		for (let attempt = 0; attempt < 3; attempt++) try {
+			await rename(tmpPath, filePath);
+			return;
+		} catch (err) {
+			if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
+			lastError = err;
+			await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+		}
+		throw lastError;
+	} catch (error) {
+		console.error(`${logPrefix} ${filePath}:`, error);
+		await unlink(tmpPath).catch(() => {});
+		throw error;
+	}
+}
+//#endregion
+export { writeJsonAtomic };

package/lib/index.d.ts

@@ -1,14 +1,5 @@
+import { writeJsonAtomic } from "./fs-atomic.js";
 //#region src/index.d.ts
-/**
- * dsh home 根目录解析，与宿主 @deepseek-ai/dsh-home-paths 同语义：
- * 优先级 显式传入 > `$DSH_HOME`（空白视为未设，支持 `~` 展开）> `~/.dsh`，
- * 相对路径按 CWD 解析。
- *
- * dsh-trading 各包的 home 数据文件（watchlists.json、knowledge/cards.json、
- * trading-tasks/ledger 等）一律经此解析，使整套 trading 实例可以通过
- * `DSH_HOME=~/.dsh-trading` 迁到独立 home，与 dsh web 宿主 home 彻底分开
- * （2026-09-08 DSH_HOME 分离，note: implemented/process/2026-09-08-separate-dsh-home.md）。
- */
 /**
  * 解析 dsh home 根目录。
  * @param env 环境变量映射，缺省读 `process.env`；空白 `$DSH_HOME` 视为未设。
@@ -60,4 +51,4 @@ interface LegacyHomeMigrationResult {
  */
 declare function migrateLegacyTradingHome(options?: LegacyHomeMigrationOptions): LegacyHomeMigrationResult | null;
 //#endregion
-export { HOME_MIGRATION_MARKER, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome };
+export { HOME_MIGRATION_MARKER, LegacyHomeMigrationOptions, LegacyHomeMigrationResult, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, writeJsonAtomic };

package/lib/index.js

@@ -1,3 +1,4 @@
+import { writeJsonAtomic } from "./fs-atomic.js";
 import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -120,4 +121,4 @@ function migrateLegacyTradingHome(options = {}) {
 	};
 }
 //#endregion
-export { HOME_MIGRATION_MARKER, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome };
+export { HOME_MIGRATION_MARKER, TRADING_HOME_ENTRIES, defaultDshHome, dshHomeDir, migrateLegacyTradingHome, writeJsonAtomic };

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.1.6",
+  "version": "0.2.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",