fix: avoid false settings backups

Author: hellowind777

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "HelloLoop 的 Claude Code 原生插件元数据，用于多 CLI 宿主分发。",
   "author": {
     "name": "HelloLoop"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件，Codex 路径为首发与参考实现。",
   "author": {
     "name": "HelloLoop"

README.md

@@ -294,7 +294,8 @@ npx helloloop install --host all --force
 - `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
 - `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
 - 安装 / 升级 / 重装时，会同步校准 `~/.helloloop/settings.json` 的当前版本结构：补齐缺失项、清理未知项、保留已知项现有值
-- 如果 `~/.helloloop/settings.json` 不是合法 JSON，会先备份原文件，再按当前版本结构重建
+- 如果 `~/.helloloop/settings.json` 被确认不是合法 JSON，会先备份原文件，再按当前版本结构重建
+- 如果只是首次读取时出现瞬时异常，但重读后内容合法，则不会误生成备份文件
 - 如果宿主自己的配置 JSON（如 `Codex marketplace.json`、`Claude settings.json`、`known_marketplaces.json`、`installed_plugins.json`）本身已损坏，`HelloLoop` 会先明确报错并停止，不会先清理现有安装再失败
 
 ### 卸载
@@ -442,7 +443,8 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 
 - 这里不保存项目 backlog、状态、运行记录
 - 安装 / 升级 / 重装时，会对 `settings.json` 做结构校准，但不会校验或篡改你已存在的已知项内容
-- 如果 `settings.json` 非法，会先备份，再重建为当前版本结构
+- 只有在 `settings.json` 被确认非法时，才会先备份，再重建为当前版本结构
+- 如果只是读取瞬时异常、重读后合法，不会误生成 `.bak`
 
 ## `.helloloop/` 状态目录
 

hosts/gemini/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
   "contextFileName": "GEMINI.md",
   "excludeTools": [

package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloloop",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
   "author": "HelloLoop",
   "license": "Apache-2.0",

src/engine_selection_settings.mjs

@@ -148,6 +148,10 @@ export function saveUserSettings(settings, options = {}) {
   });
 }
 
+function tryParseUserSettingsText(text) {
+  return JSON.parse(String(text || ""));
+}
+
 export function syncUserSettingsFile(options = {}) {
   const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
   const defaults = defaultUserSettings();
@@ -161,12 +165,33 @@ export function syncUserSettingsFile(options = {}) {
     };
   }
 
-  let parsed;
+  const firstText = readText(settingsFile);
   try {
-    parsed = readJson(settingsFile);
+    const parsed = tryParseUserSettingsText(firstText);
+    writeJson(settingsFile, syncUserSettingsShape(parsed));
+    return {
+      settingsFile,
+      action: "synced",
+      backupFile: "",
+    };
   } catch (error) {
+    const retryText = readText(settingsFile);
+    if (retryText !== firstText) {
+      try {
+        const parsed = tryParseUserSettingsText(retryText);
+        writeJson(settingsFile, syncUserSettingsShape(parsed));
+        return {
+          settingsFile,
+          action: "synced",
+          backupFile: "",
+          recoveredAfterRetry: true,
+        };
+      } catch {
+      }
+    }
+
     const backupFile = `${settingsFile}.invalid-${timestampForFile()}.bak`;
-    writeText(backupFile, readText(settingsFile));
+    writeText(backupFile, retryText);
     writeJson(settingsFile, defaults);
     return {
       settingsFile,
@@ -175,11 +200,4 @@ export function syncUserSettingsFile(options = {}) {
       error: String(error?.message || error || ""),
     };
   }
-
-  writeJson(settingsFile, syncUserSettingsShape(parsed));
-  return {
-    settingsFile,
-    action: "synced",
-    backupFile: "",
-  };
 }

tests/host_lifecycle_integrity.test.mjs

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { syncUserSettingsFile } from "../src/engine_selection_settings.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -466,3 +467,44 @@ test("install 遇到非法 settings.json 时会备份后重建当前版本结构
     fs.rmSync(tempRoot, { recursive: true, force: true });
   }
 });
+
+test("settings.json 在首次读取瞬间异常、重读后合法时不会产生备份文件", () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "helloloop-settings-retry-"));
+  const helloLoopHome = path.join(tempRoot, "helloloop-home");
+  const settingsFile = path.join(helloLoopHome, "settings.json");
+  const originalReadFileSync = fs.readFileSync;
+  let firstRead = true;
+
+  writeJson(settingsFile, {
+    defaultEngine: "",
+    lastSelectedEngine: "codex",
+    notifications: {
+      email: {
+        enabled: false,
+      },
+    },
+  });
+
+  fs.readFileSync = ((filePath, ...args) => {
+    if (String(filePath) === settingsFile && firstRead) {
+      firstRead = false;
+      return "{ invalid";
+    }
+    return originalReadFileSync.call(fs, filePath, ...args);
+  });
+
+  try {
+    const result = syncUserSettingsFile({ userSettingsFile: settingsFile });
+    assert.equal(result.action, "synced");
+    assert.equal(result.backupFile, "");
+    assert.equal(result.recoveredAfterRetry, true);
+    const backupFiles = fs.readdirSync(helloLoopHome)
+      .filter((item) => item.startsWith("settings.json.invalid-") && item.endsWith(".bak"));
+    assert.deepEqual(backupFiles, []);
+    const settings = readJson(settingsFile);
+    assert.equal(settings.lastSelectedEngine, "codex");
+  } finally {
+    fs.readFileSync = originalReadFileSync;
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});