helloloop 0.7.1 → 0.7.3

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -293,6 +293,10 @@ npx helloloop install --host all --force
 - `Codex` 会刷新插件目录和 marketplace 条目
 - `Claude` 会刷新 marketplace、缓存插件目录，以及 `settings.json` / `known_marketplaces.json` / `installed_plugins.json` 中的 `helloloop` 条目
 - `Gemini` 会刷新 `extensions/helloloop/`，不会动同目录下其他扩展
+- 安装 / 升级 / 重装时，会同步校准 `~/.helloloop/settings.json` 的当前版本结构：补齐缺失项、清理未知项、保留已知项现有值
+- 如果 `~/.helloloop/settings.json` 被确认不是合法 JSON，会先备份原文件，再按当前版本结构重建
+- 如果只是首次读取时出现瞬时异常，但重读后内容合法，则不会误生成备份文件
+- 如果宿主自己的配置 JSON（如 `Codex marketplace.json`、`Claude settings.json`、`known_marketplaces.json`、`installed_plugins.json`）本身已损坏，`HelloLoop` 会先明确报错并停止，不会先清理现有安装再失败
 
 ### 卸载
 
@@ -426,6 +430,22 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 
 `HelloLoop` 只维护自己的目录和自己的注册项，不会重写别的插件条目。
 
+## 用户目录写入范围
+
+全局用户目录 `~/.helloloop/` 只保留一份全局设置：
+
+```text
+~/.helloloop/
+└── settings.json
+```
+
+说明：
+
+- 这里不保存项目 backlog、状态、运行记录
+- 安装 / 升级 / 重装时，会对 `settings.json` 做结构校准，但不会校验或篡改你已存在的已知项内容
+- 只有在 `settings.json` 被确认非法时，才会先备份，再重建为当前版本结构
+- 如果只是读取瞬时异常、重读后合法，不会误生成 `.bak`
+
 ## `.helloloop/` 状态目录
 
 `HelloLoop` 的 backlog、状态和运行记录始终写入目标仓库根目录下的：
@@ -441,6 +461,7 @@ npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_
 ```
 
 不会写回插件目录自身。
+也不会写入 `~/.helloloop/`。
 
 ## 跨平台与安全
 

package/hosts/gemini/extension/gemini-extension.json

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

package/package.json

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

package/src/cli_command_handlers.mjs

@@ -2,11 +2,15 @@ import path from "node:path";
 
 import { createContext } from "./context.mjs";
 import { loadBacklog, scaffoldIfMissing } from "./config.mjs";
+import { syncUserSettingsFile } from "./engine_selection_settings.mjs";
 import { installPluginBundle, uninstallPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
 import { renderInstallSummary, renderUninstallSummary } from "./cli_render.mjs";
 
 export function handleInstallCommand(options) {
+  const userSettings = syncUserSettingsFile({
+    userSettingsFile: options.userSettingsFile,
+  });
   const context = createContext({
     repoRoot: options.repoRoot,
     configDirName: options.configDirName,
@@ -18,6 +22,7 @@ export function handleInstallCommand(options) {
     claudeHome: options.claudeHome,
     geminiHome: options.geminiHome,
     force: options.force,
+    userSettings,
   });
   console.log(renderInstallSummary(result));
   return 0;

package/src/cli_render.mjs

@@ -29,6 +29,22 @@ export function renderInstallSummary(result) {
     }
   }
 
+  if (result.userSettings?.settingsFile) {
+    lines.push("");
+    lines.push("全局设置：");
+    lines.push(`- 配置文件：${result.userSettings.settingsFile}`);
+    if (result.userSettings.action === "created") {
+      lines.push("- 结构校准：已创建默认 settings.json");
+    } else if (result.userSettings.action === "reset_invalid_json") {
+      lines.push("- 结构校准：检测到非法 JSON，已重建为当前版本结构");
+      if (result.userSettings.backupFile) {
+        lines.push(`- 备份文件：${result.userSettings.backupFile}`);
+      }
+    } else {
+      lines.push("- 结构校准：已按当前版本同步 settings.json 项");
+    }
+  }
+
   lines.push("");
   lines.push("使用入口：");
   lines.push("- Codex：`$helloloop` / `npx helloloop`");

package/src/engine_selection.mjs

@@ -327,9 +327,7 @@ export function rememberEngineSelection(context, engineResolution, options = {})
     });
   }
 
-  const userSettings = loadUserSettings(options);
   saveUserSettings({
-    ...userSettings,
     lastSelectedEngine: engine,
   }, options);
 }

package/src/engine_selection_settings.mjs

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 
-import { fileExists, readJson, writeJson } from "./common.mjs";
+import { fileExists, readJson, readText, timestampForFile, writeJson, writeText } from "./common.mjs";
 import { normalizeEngineName } from "./engine_metadata.mjs";
 
 function defaultEmailNotificationSettings() {
@@ -34,6 +34,57 @@ function defaultUserSettings() {
   };
 }
 
+function cloneJsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function syncValueBySchema(schemaValue, currentValue) {
+  if (!isPlainObject(schemaValue)) {
+    return currentValue === undefined ? cloneJsonValue(schemaValue) : currentValue;
+  }
+
+  const source = isPlainObject(currentValue) ? currentValue : {};
+  const next = {};
+  for (const [key, childSchema] of Object.entries(schemaValue)) {
+    next[key] = syncValueBySchema(childSchema, Object.hasOwn(source, key) ? source[key] : undefined);
+  }
+  return next;
+}
+
+function mergeValueBySchema(schemaValue, baseValue, patchValue) {
+  if (!isPlainObject(schemaValue)) {
+    return patchValue === undefined ? baseValue : patchValue;
+  }
+
+  const baseObject = isPlainObject(baseValue) ? baseValue : {};
+  const patchObject = isPlainObject(patchValue) ? patchValue : {};
+  const next = {};
+  for (const [key, childSchema] of Object.entries(schemaValue)) {
+    const nextBaseValue = Object.hasOwn(baseObject, key) ? baseObject[key] : undefined;
+    const hasPatchedKey = isPlainObject(patchValue) && Object.hasOwn(patchObject, key);
+    next[key] = mergeValueBySchema(
+      childSchema,
+      nextBaseValue,
+      hasPatchedKey ? patchObject[key] : undefined,
+    );
+  }
+  return next;
+}
+
+export function syncUserSettingsShape(settings = {}) {
+  return syncValueBySchema(defaultUserSettings(), settings);
+}
+
+function readRawUserSettingsDocument(options = {}) {
+  const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
+  const settings = fileExists(settingsFile) ? readJson(settingsFile) : {};
+  return syncUserSettingsShape(settings);
+}
+
 export function resolveUserSettingsHome() {
   return String(process.env.HELLOLOOP_HOME || "").trim()
     || path.join(os.homedir(), ".helloloop");
@@ -63,11 +114,9 @@ function normalizeEmailNotificationSettings(emailSettings = {}) {
 }
 
 export function loadUserSettingsDocument(options = {}) {
-  const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
-  const settings = fileExists(settingsFile) ? readJson(settingsFile) : {};
+  const settings = readRawUserSettingsDocument(options);
 
   return {
-    ...defaultUserSettings(),
     ...settings,
     defaultEngine: normalizeEngineName(settings?.defaultEngine),
     lastSelectedEngine: normalizeEngineName(settings?.lastSelectedEngine),
@@ -87,18 +136,68 @@ export function loadUserSettings(options = {}) {
 }
 
 export function saveUserSettings(settings, options = {}) {
-  const currentSettings = loadUserSettingsDocument(options);
+  const currentSettings = readRawUserSettingsDocument(options);
+  const mergedSettings = mergeValueBySchema(
+    defaultUserSettings(),
+    currentSettings,
+    settings,
+  );
+
   writeJson(resolveUserSettingsFile(options.userSettingsFile), {
-    ...currentSettings,
-    ...settings,
-    defaultEngine: normalizeEngineName(settings?.defaultEngine ?? currentSettings.defaultEngine),
-    lastSelectedEngine: normalizeEngineName(settings?.lastSelectedEngine ?? currentSettings.lastSelectedEngine),
-    notifications: {
-      ...(currentSettings.notifications || {}),
-      ...(settings?.notifications || {}),
-      email: normalizeEmailNotificationSettings(
-        settings?.notifications?.email ?? currentSettings.notifications?.email ?? {},
-      ),
-    },
+    ...syncUserSettingsShape(mergedSettings),
   });
 }
+
+function tryParseUserSettingsText(text) {
+  return JSON.parse(String(text || ""));
+}
+
+export function syncUserSettingsFile(options = {}) {
+  const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
+  const defaults = defaultUserSettings();
+
+  if (!fileExists(settingsFile)) {
+    writeJson(settingsFile, defaults);
+    return {
+      settingsFile,
+      action: "created",
+      backupFile: "",
+    };
+  }
+
+  const firstText = readText(settingsFile);
+  try {
+    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, retryText);
+    writeJson(settingsFile, defaults);
+    return {
+      settingsFile,
+      action: "reset_invalid_json",
+      backupFile,
+      error: String(error?.message || error || ""),
+    };
+  }
+}

package/src/install.mjs

@@ -38,6 +38,7 @@ export function installPluginBundle(options = {}) {
     installedHosts,
     targetPluginRoot: codexResult?.targetRoot || "",
     marketplaceFile: codexResult?.marketplaceFile || "",
+    userSettings: options.userSettings || null,
   };
 }
 

package/src/install_claude.mjs

@@ -6,13 +6,14 @@ import {
   CLAUDE_PLUGIN_KEY,
   assertPathInside,
   copyDirectory,
+  readExistingJsonOrThrow,
   removePathIfExists,
   removeTargetIfNeeded,
   resolveHomeDir,
 } from "./install_shared.mjs";
 
-function updateClaudeSettings(settingsFile, marketplaceRoot) {
-  const settings = fileExists(settingsFile) ? readJson(settingsFile) : {};
+function updateClaudeSettings(settingsFile, marketplaceRoot, existingSettings = null) {
+  const settings = existingSettings || (fileExists(settingsFile) ? readJson(settingsFile) : {});
 
   settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
   settings.enabledPlugins = settings.enabledPlugins || {};
@@ -27,12 +28,12 @@ function updateClaudeSettings(settingsFile, marketplaceRoot) {
   writeJson(settingsFile, settings);
 }
 
-function removeClaudeSettingsEntries(settingsFile) {
+function removeClaudeSettingsEntries(settingsFile, existingSettings = null) {
   if (!fileExists(settingsFile)) {
     return false;
   }
 
-  const settings = readJson(settingsFile);
+  const settings = existingSettings || readJson(settingsFile);
   let changed = false;
 
   if (settings.extraKnownMarketplaces && Object.hasOwn(settings.extraKnownMarketplaces, CLAUDE_MARKETPLACE_NAME)) {
@@ -50,8 +51,13 @@ function removeClaudeSettingsEntries(settingsFile) {
   return changed;
 }
 
-function updateClaudeKnownMarketplaces(knownMarketplacesFile, marketplaceRoot, updatedAt) {
-  const knownMarketplaces = fileExists(knownMarketplacesFile) ? readJson(knownMarketplacesFile) : {};
+function updateClaudeKnownMarketplaces(
+  knownMarketplacesFile,
+  marketplaceRoot,
+  updatedAt,
+  existingKnownMarketplaces = null,
+) {
+  const knownMarketplaces = existingKnownMarketplaces || (fileExists(knownMarketplacesFile) ? readJson(knownMarketplacesFile) : {});
   knownMarketplaces[CLAUDE_MARKETPLACE_NAME] = {
     source: {
       source: "directory",
@@ -63,12 +69,12 @@ function updateClaudeKnownMarketplaces(knownMarketplacesFile, marketplaceRoot, u
   writeJson(knownMarketplacesFile, knownMarketplaces);
 }
 
-function removeClaudeKnownMarketplace(knownMarketplacesFile) {
+function removeClaudeKnownMarketplace(knownMarketplacesFile, existingKnownMarketplaces = null) {
   if (!fileExists(knownMarketplacesFile)) {
     return false;
   }
 
-  const knownMarketplaces = readJson(knownMarketplacesFile);
+  const knownMarketplaces = existingKnownMarketplaces || readJson(knownMarketplacesFile);
   if (!Object.hasOwn(knownMarketplaces, CLAUDE_MARKETPLACE_NAME)) {
     return false;
   }
@@ -78,10 +84,18 @@ function removeClaudeKnownMarketplace(knownMarketplacesFile) {
   return true;
 }
 
-function updateClaudeInstalledPlugins(installedPluginsFile, pluginRoot, pluginVersion, updatedAt) {
-  const installedPlugins = fileExists(installedPluginsFile)
-    ? readJson(installedPluginsFile)
-    : { version: 2, plugins: {} };
+function updateClaudeInstalledPlugins(
+  installedPluginsFile,
+  pluginRoot,
+  pluginVersion,
+  updatedAt,
+  existingInstalledPlugins = null,
+) {
+  const installedPlugins = existingInstalledPlugins
+    ? existingInstalledPlugins
+    : (fileExists(installedPluginsFile)
+      ? readJson(installedPluginsFile)
+      : { version: 2, plugins: {} });
 
   installedPlugins.version = 2;
   installedPlugins.plugins = installedPlugins.plugins || {};
@@ -98,12 +112,12 @@ function updateClaudeInstalledPlugins(installedPluginsFile, pluginRoot, pluginVe
   writeJson(installedPluginsFile, installedPlugins);
 }
 
-function removeClaudeInstalledPlugin(installedPluginsFile) {
+function removeClaudeInstalledPlugin(installedPluginsFile, existingInstalledPlugins = null) {
   if (!fileExists(installedPluginsFile)) {
     return false;
   }
 
-  const installedPlugins = readJson(installedPluginsFile);
+  const installedPlugins = existingInstalledPlugins || readJson(installedPluginsFile);
   if (!installedPlugins.plugins || !Object.hasOwn(installedPlugins.plugins, CLAUDE_PLUGIN_KEY)) {
     return false;
   }
@@ -125,6 +139,9 @@ export function installClaudeHost(bundleRoot, options = {}) {
   const knownMarketplacesFile = path.join(targetPluginsRoot, "known_marketplaces.json");
   const installedPluginsFile = path.join(targetPluginsRoot, "installed_plugins.json");
   const settingsFile = path.join(resolvedClaudeHome, "settings.json");
+  const existingSettings = readExistingJsonOrThrow(settingsFile, "Claude settings 配置");
+  const existingKnownMarketplaces = readExistingJsonOrThrow(knownMarketplacesFile, "Claude known_marketplaces 配置");
+  const existingInstalledPlugins = readExistingJsonOrThrow(installedPluginsFile, "Claude installed_plugins 配置");
 
   if (!fileExists(sourceManifest)) {
     throw new Error(`未找到 Claude 插件 manifest：${sourceManifest}`);
@@ -144,9 +161,20 @@ export function installClaudeHost(bundleRoot, options = {}) {
   copyDirectory(sourceMarketplaceRoot, targetMarketplaceRoot);
   copyDirectory(path.join(sourceMarketplaceRoot, "plugins", "helloloop"), targetInstalledPluginRoot);
   const updatedAt = nowIso();
-  updateClaudeSettings(settingsFile, targetMarketplaceRoot);
-  updateClaudeKnownMarketplaces(knownMarketplacesFile, targetMarketplaceRoot, updatedAt);
-  updateClaudeInstalledPlugins(installedPluginsFile, targetInstalledPluginRoot, pluginVersion, updatedAt);
+  updateClaudeSettings(settingsFile, targetMarketplaceRoot, existingSettings);
+  updateClaudeKnownMarketplaces(
+    knownMarketplacesFile,
+    targetMarketplaceRoot,
+    updatedAt,
+    existingKnownMarketplaces,
+  );
+  updateClaudeInstalledPlugins(
+    installedPluginsFile,
+    targetInstalledPluginRoot,
+    pluginVersion,
+    updatedAt,
+    existingInstalledPlugins,
+  );
 
   return {
     host: "claude",
@@ -165,12 +193,15 @@ export function uninstallClaudeHost(options = {}) {
   const knownMarketplacesFile = path.join(targetPluginsRoot, "known_marketplaces.json");
   const installedPluginsFile = path.join(targetPluginsRoot, "installed_plugins.json");
   const settingsFile = path.join(resolvedClaudeHome, "settings.json");
+  const existingSettings = readExistingJsonOrThrow(settingsFile, "Claude settings 配置");
+  const existingKnownMarketplaces = readExistingJsonOrThrow(knownMarketplacesFile, "Claude known_marketplaces 配置");
+  const existingInstalledPlugins = readExistingJsonOrThrow(installedPluginsFile, "Claude installed_plugins 配置");
 
   const removedMarketplaceDir = removePathIfExists(targetMarketplaceRoot);
   const removedCacheDir = removePathIfExists(targetCachePluginsRoot);
-  const removedKnownMarketplace = removeClaudeKnownMarketplace(knownMarketplacesFile);
-  const removedInstalledPlugin = removeClaudeInstalledPlugin(installedPluginsFile);
-  const removedSettingsEntries = removeClaudeSettingsEntries(settingsFile);
+  const removedKnownMarketplace = removeClaudeKnownMarketplace(knownMarketplacesFile, existingKnownMarketplaces);
+  const removedInstalledPlugin = removeClaudeInstalledPlugin(installedPluginsFile, existingInstalledPlugins);
+  const removedSettingsEntries = removeClaudeSettingsEntries(settingsFile, existingSettings);
 
   return {
     host: "claude",

package/src/install_codex.mjs

@@ -5,21 +5,23 @@ import {
   assertPathInside,
   codexBundleEntries,
   copyBundleEntries,
+  readExistingJsonOrThrow,
   removePathIfExists,
   removeTargetIfNeeded,
   resolveHomeDir,
 } from "./install_shared.mjs";
 
-function updateCodexMarketplace(marketplaceFile) {
-  const marketplace = fileExists(marketplaceFile)
-    ? readJson(marketplaceFile)
-    : {
-      name: "local-plugins",
-      interface: {
-        displayName: "Local Plugins",
-      },
-      plugins: [],
-    };
+function updateCodexMarketplace(marketplaceFile, existingMarketplace = null) {
+  const marketplace = existingMarketplace
+    || (fileExists(marketplaceFile)
+      ? readJson(marketplaceFile)
+      : {
+        name: "local-plugins",
+        interface: {
+          displayName: "Local Plugins",
+        },
+        plugins: [],
+      });
 
   marketplace.interface = marketplace.interface || {
     displayName: "Local Plugins",
@@ -49,12 +51,12 @@ function updateCodexMarketplace(marketplaceFile) {
   writeJson(marketplaceFile, marketplace);
 }
 
-function removeCodexMarketplaceEntry(marketplaceFile) {
+function removeCodexMarketplaceEntry(marketplaceFile, existingMarketplace = null) {
   if (!fileExists(marketplaceFile)) {
     return false;
   }
 
-  const marketplace = readJson(marketplaceFile);
+  const marketplace = existingMarketplace || readJson(marketplaceFile);
   const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
   const nextPlugins = plugins.filter((plugin) => plugin?.name !== "helloloop");
   if (nextPlugins.length === plugins.length) {
@@ -72,6 +74,7 @@ export function installCodexHost(bundleRoot, options = {}) {
   const targetPluginRoot = path.join(targetPluginsRoot, "helloloop");
   const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
   const manifestFile = path.join(bundleRoot, ".codex-plugin", "plugin.json");
+  const existingMarketplace = readExistingJsonOrThrow(marketplaceFile, "Codex marketplace 配置");
 
   if (!fileExists(manifestFile)) {
     throw new Error(`未找到 Codex 插件 manifest：${manifestFile}`);
@@ -86,7 +89,7 @@ export function installCodexHost(bundleRoot, options = {}) {
   removePathIfExists(path.join(targetPluginRoot, ".git"));
 
   ensureDir(path.dirname(marketplaceFile));
-  updateCodexMarketplace(marketplaceFile);
+  updateCodexMarketplace(marketplaceFile, existingMarketplace);
 
   return {
     host: "codex",
@@ -100,9 +103,10 @@ export function uninstallCodexHost(options = {}) {
   const resolvedCodexHome = resolveHomeDir(options.codexHome, ".codex");
   const targetPluginRoot = path.join(resolvedCodexHome, "plugins", "helloloop");
   const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
+  const existingMarketplace = readExistingJsonOrThrow(marketplaceFile, "Codex marketplace 配置");
 
   const removedPlugin = removePathIfExists(targetPluginRoot);
-  const removedMarketplace = removeCodexMarketplaceEntry(marketplaceFile);
+  const removedMarketplace = removeCodexMarketplaceEntry(marketplaceFile, existingMarketplace);
 
   return {
     host: "codex",

package/src/install_shared.mjs

@@ -132,6 +132,17 @@ export function loadOrInitJson(filePath, fallbackValue) {
   return readJson(filePath);
 }
 
+export function readExistingJsonOrThrow(filePath, label) {
+  if (!fileExists(filePath)) {
+    return null;
+  }
+  try {
+    return readJson(filePath);
+  } catch (error) {
+    throw new Error(`${label} 不是合法 JSON：${filePath}`);
+  }
+}
+
 export function writeJsonFile(filePath, value) {
   ensureDir(path.dirname(filePath));
   writeJson(filePath, value);