helloloop 0.3.1 → 0.7.0

package/src/engine_selection_settings.mjs

@@ -0,0 +1,104 @@
+import os from "node:os";
+import path from "node:path";
+
+import { fileExists, readJson, writeJson } from "./common.mjs";
+import { normalizeEngineName } from "./engine_metadata.mjs";
+
+function defaultEmailNotificationSettings() {
+  return {
+    enabled: false,
+    to: [],
+    from: "",
+    smtp: {
+      host: "",
+      port: 465,
+      secure: true,
+      starttls: false,
+      username: "",
+      usernameEnv: "",
+      password: "",
+      passwordEnv: "",
+      timeoutSeconds: 30,
+      rejectUnauthorized: true,
+    },
+  };
+}
+
+function defaultUserSettings() {
+  return {
+    defaultEngine: "",
+    lastSelectedEngine: "",
+    notifications: {
+      email: defaultEmailNotificationSettings(),
+    },
+  };
+}
+
+export function resolveUserSettingsHome() {
+  return String(process.env.HELLOLOOP_HOME || "").trim()
+    || path.join(os.homedir(), ".helloloop");
+}
+
+export function resolveUserSettingsFile(userSettingsFile = "") {
+  return userSettingsFile
+    || String(process.env.HELLOLOOP_SETTINGS_FILE || "").trim()
+    || path.join(resolveUserSettingsHome(), "settings.json");
+}
+
+function normalizeEmailNotificationSettings(emailSettings = {}) {
+  const defaults = defaultEmailNotificationSettings();
+  const smtp = emailSettings?.smtp || {};
+
+  return {
+    ...defaults,
+    ...emailSettings,
+    to: Array.isArray(emailSettings?.to)
+      ? emailSettings.to.map((item) => String(item || "").trim()).filter(Boolean)
+      : (typeof emailSettings?.to === "string" && emailSettings.to.trim() ? [emailSettings.to.trim()] : []),
+    smtp: {
+      ...defaults.smtp,
+      ...smtp,
+    },
+  };
+}
+
+export function loadUserSettingsDocument(options = {}) {
+  const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
+  const settings = fileExists(settingsFile) ? readJson(settingsFile) : {};
+
+  return {
+    ...defaultUserSettings(),
+    ...settings,
+    defaultEngine: normalizeEngineName(settings?.defaultEngine),
+    lastSelectedEngine: normalizeEngineName(settings?.lastSelectedEngine),
+    notifications: {
+      ...(settings?.notifications || {}),
+      email: normalizeEmailNotificationSettings(settings?.notifications?.email || {}),
+    },
+  };
+}
+
+export function loadUserSettings(options = {}) {
+  const settings = loadUserSettingsDocument(options);
+  return {
+    defaultEngine: settings.defaultEngine,
+    lastSelectedEngine: settings.lastSelectedEngine,
+  };
+}
+
+export function saveUserSettings(settings, options = {}) {
+  const currentSettings = loadUserSettingsDocument(options);
+  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 ?? {},
+      ),
+    },
+  });
+}

package/src/global_config.mjs

@@ -0,0 +1,21 @@
+import { fileExists } from "./common.mjs";
+import { loadUserSettingsDocument, resolveUserSettingsFile } from "./engine_selection_settings.mjs";
+
+export function resolveGlobalConfigFile(explicitFile = "") {
+  return resolveUserSettingsFile(explicitFile);
+}
+
+export function loadGlobalConfig(options = {}) {
+  const configFile = resolveGlobalConfigFile(options.globalConfigFile);
+  const loaded = loadUserSettingsDocument({
+    userSettingsFile: configFile,
+  });
+
+  return {
+    ...loaded,
+    _meta: {
+      configFile,
+      exists: fileExists(configFile),
+    },
+  };
+}

package/src/guardrails.mjs

@@ -35,12 +35,19 @@ const mandatoryGuardrails = [
   "目标实现必须兼容 Windows、macOS、Linux，禁止硬编码平台专属路径分隔符或 shell 语法。",
 ];
 
+const mandatoryEngineeringPrinciples = [
+  "代码是唯一事实源；文档与代码不一致时，以当前代码、测试和真实目录结构为准。",
+  "代码体积控制：文件/类超过 300 行、函数/方法超过 40 行时必须评估是否拆分；文件/类超过 400 行、函数/方法超过 60 行时，除生成代码、大型测试夹具、迁移脚本、协议常量表等例外外，必须在完成功能后按职责拆分。",
+  "禁止通过压缩代码排版、删除必要空行、合并本应独立的函数、缩短命名等方式规避行数；允许按职责拆模块、拆子组件、拆 hooks/services/adapters/mappers、拆类型定义与常量文件；有冗余时应精简死代码、重复逻辑和过时注释。",
+  "仅为复杂逻辑添加注释；新增公共函数必须写简洁 docstring。",
+  "不添加不必要的抽象层。",
+  "所有产出都必须达到专业级水准：编码任务要求架构清晰、代码健壮、UI 精致、交互流畅；非编码任务要求逻辑严密、结构清晰、表达专业、格式规范，不接受“能用就行”的交付。",
+];
+
 const defaultProjectConstraints = [
-  "代码是事实源；文档与代码冲突时，以当前代码、测试和真实目录结构为准。",
-  "产出必须达到专业级水准：架构清晰、实现完整、表达专业，不接受“能用就行”的交付。",
+  "用户需求明确且当前任务可直接完成时，必须一次性完成本轮应交付的全部工作；禁止做一半后用“如果你要”“是否继续”等话术中途停下，只有真实歧义、关键信息缺失或必须用户决策时才允许确认。",
+  "最终回复禁止添加“如果你要我可以继续”“如果你需要进一步…”“希望这对你有帮助”等客套收尾；完成就直接结束，只保留必要的结果、验证和剩余风险。",
   "所有文件修改必须使用当前环境提供的安全编辑方式，例如 apply_patch，而不是危险的原地批量命令。",
-  "不得通过压缩代码、删除必要空行、缩短命名来规避体积控制；单文件超过 400 行后按职责拆分。",
-  "不添加不必要的抽象层；仅为复杂逻辑添加必要注释，新增公共函数补简洁说明。",
   "完成前必须主动运行验证；失败后先分析根因，再修复并重跑。",
   "不允许静默失败、静默降级、静默回退；遇到阻塞必须明确说明原因。",
 ];
@@ -49,6 +56,10 @@ export function listMandatoryGuardrails() {
   return [...mandatoryGuardrails];
 }
 
+export function listMandatoryEngineeringPrinciples() {
+  return [...mandatoryEngineeringPrinciples];
+}
+
 export function hasCustomProjectConstraints(items = []) {
   return uniqueRules(items).length > 0;
 }

package/src/install.mjs

@@ -1,415 +1,14 @@
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { ensureDir, fileExists, nowIso, readJson, writeJson } from "./common.mjs";
+import { installClaudeHost, uninstallClaudeHost } from "./install_claude.mjs";
+import { installCodexHost, uninstallCodexHost } from "./install_codex.mjs";
+import { installGeminiHost, uninstallGeminiHost } from "./install_gemini.mjs";
+import { runtimeBundleEntries, supportedHosts } from "./install_shared.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export const runtimeBundleEntries = [
-  ".claude-plugin",
-  ".codex-plugin",
-  "LICENSE",
-  "README.md",
-  "bin",
-  "hosts",
-  "package.json",
-  "scripts",
-  "skills",
-  "src",
-  "templates",
-];
-
-const codexBundleEntries = runtimeBundleEntries.filter((entry) => ![
-  ".claude-plugin",
-  "hosts",
-].includes(entry));
-
-const supportedHosts = ["codex", "claude", "gemini"];
-const CLAUDE_MARKETPLACE_NAME = "helloloop-local";
-const CLAUDE_PLUGIN_KEY = "helloloop@helloloop-local";
-
-function resolveHomeDir(homeDir, defaultDirName) {
-  return path.resolve(homeDir || path.join(os.homedir(), defaultDirName));
-}
-
-function assertPathInside(parentDir, targetDir, label) {
-  const relative = path.relative(parentDir, targetDir);
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-    throw new Error(`${label} 超出允许范围：${targetDir}`);
-  }
-}
-
-function removeTargetIfNeeded(targetPath, force) {
-  if (!fileExists(targetPath)) {
-    return;
-  }
-  if (!force) {
-    throw new Error(`目标目录已存在：${targetPath}。若要覆盖，请追加 --force。`);
-  }
-  fs.rmSync(targetPath, { recursive: true, force: true });
-}
-
-function removePathIfExists(targetPath) {
-  if (!fileExists(targetPath)) {
-    return false;
-  }
-  fs.rmSync(targetPath, { recursive: true, force: true });
-  return true;
-}
-
-function copyBundleEntries(bundleRoot, targetRoot, entries) {
-  for (const entry of entries) {
-    const sourcePath = path.join(bundleRoot, entry);
-    if (!fileExists(sourcePath)) {
-      continue;
-    }
-
-    fs.cpSync(sourcePath, path.join(targetRoot, entry), {
-      force: true,
-      recursive: true,
-    });
-  }
-}
-
-function copyDirectory(sourceRoot, targetRoot) {
-  fs.cpSync(sourceRoot, targetRoot, {
-    force: true,
-    recursive: true,
-  });
-}
-
-function updateCodexMarketplace(marketplaceFile) {
-  const marketplace = fileExists(marketplaceFile)
-    ? readJson(marketplaceFile)
-    : {
-        name: "local-plugins",
-        interface: {
-          displayName: "Local Plugins",
-        },
-        plugins: [],
-      };
-
-  marketplace.interface = marketplace.interface || {
-    displayName: "Local Plugins",
-  };
-  marketplace.plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
-
-  const nextEntry = {
-    name: "helloloop",
-    source: {
-      source: "local",
-      path: "./plugins/helloloop",
-    },
-    policy: {
-      installation: "AVAILABLE",
-      authentication: "ON_INSTALL",
-    },
-    category: "Coding",
-  };
-
-  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin?.name === "helloloop");
-  if (existingIndex >= 0) {
-    marketplace.plugins.splice(existingIndex, 1, nextEntry);
-  } else {
-    marketplace.plugins.push(nextEntry);
-  }
-
-  writeJson(marketplaceFile, marketplace);
-}
-
-function removeCodexMarketplaceEntry(marketplaceFile) {
-  if (!fileExists(marketplaceFile)) {
-    return false;
-  }
-
-  const marketplace = readJson(marketplaceFile);
-  const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
-  const nextPlugins = plugins.filter((plugin) => plugin?.name !== "helloloop");
-  if (nextPlugins.length === plugins.length) {
-    return false;
-  }
-
-  marketplace.plugins = nextPlugins;
-  writeJson(marketplaceFile, marketplace);
-  return true;
-}
-
-function updateClaudeSettings(settingsFile, marketplaceRoot) {
-  const settings = fileExists(settingsFile)
-    ? readJson(settingsFile)
-    : {};
-
-  settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
-  settings.enabledPlugins = settings.enabledPlugins || {};
-
-  settings.extraKnownMarketplaces[CLAUDE_MARKETPLACE_NAME] = {
-    source: {
-      source: "directory",
-      path: marketplaceRoot,
-    },
-  };
-  settings.enabledPlugins[CLAUDE_PLUGIN_KEY] = true;
-
-  writeJson(settingsFile, settings);
-}
-
-function removeClaudeSettingsEntries(settingsFile) {
-  if (!fileExists(settingsFile)) {
-    return false;
-  }
-
-  const settings = readJson(settingsFile);
-  let changed = false;
-
-  if (settings.extraKnownMarketplaces && Object.hasOwn(settings.extraKnownMarketplaces, CLAUDE_MARKETPLACE_NAME)) {
-    delete settings.extraKnownMarketplaces[CLAUDE_MARKETPLACE_NAME];
-    changed = true;
-  }
-
-  if (settings.enabledPlugins && Object.hasOwn(settings.enabledPlugins, CLAUDE_PLUGIN_KEY)) {
-    delete settings.enabledPlugins[CLAUDE_PLUGIN_KEY];
-    changed = true;
-  }
-
-  if (changed) {
-    writeJson(settingsFile, settings);
-  }
-  return changed;
-}
-
-function updateClaudeKnownMarketplaces(knownMarketplacesFile, marketplaceRoot, updatedAt) {
-  const knownMarketplaces = fileExists(knownMarketplacesFile)
-    ? readJson(knownMarketplacesFile)
-    : {};
-
-  knownMarketplaces[CLAUDE_MARKETPLACE_NAME] = {
-    source: {
-      source: "directory",
-      path: marketplaceRoot,
-    },
-    installLocation: marketplaceRoot,
-    lastUpdated: updatedAt,
-  };
-
-  writeJson(knownMarketplacesFile, knownMarketplaces);
-}
-
-function removeClaudeKnownMarketplace(knownMarketplacesFile) {
-  if (!fileExists(knownMarketplacesFile)) {
-    return false;
-  }
-
-  const knownMarketplaces = readJson(knownMarketplacesFile);
-  if (!Object.hasOwn(knownMarketplaces, CLAUDE_MARKETPLACE_NAME)) {
-    return false;
-  }
-
-  delete knownMarketplaces[CLAUDE_MARKETPLACE_NAME];
-  writeJson(knownMarketplacesFile, knownMarketplaces);
-  return true;
-}
-
-function updateClaudeInstalledPlugins(installedPluginsFile, pluginRoot, pluginVersion, updatedAt) {
-  const installedPlugins = fileExists(installedPluginsFile)
-    ? readJson(installedPluginsFile)
-    : {
-        version: 2,
-        plugins: {},
-      };
-
-  installedPlugins.version = 2;
-  installedPlugins.plugins = installedPlugins.plugins || {};
-  installedPlugins.plugins[CLAUDE_PLUGIN_KEY] = [
-    {
-      scope: "user",
-      installPath: pluginRoot,
-      version: pluginVersion,
-      installedAt: updatedAt,
-      lastUpdated: updatedAt,
-    },
-  ];
-
-  writeJson(installedPluginsFile, installedPlugins);
-}
-
-function removeClaudeInstalledPlugin(installedPluginsFile) {
-  if (!fileExists(installedPluginsFile)) {
-    return false;
-  }
-
-  const installedPlugins = readJson(installedPluginsFile);
-  if (!installedPlugins.plugins || !Object.hasOwn(installedPlugins.plugins, CLAUDE_PLUGIN_KEY)) {
-    return false;
-  }
-
-  delete installedPlugins.plugins[CLAUDE_PLUGIN_KEY];
-  writeJson(installedPluginsFile, installedPlugins);
-  return true;
-}
-
-function installCodexHost(bundleRoot, options) {
-  const resolvedCodexHome = resolveHomeDir(options.codexHome, ".codex");
-  const targetPluginsRoot = path.join(resolvedCodexHome, "plugins");
-  const targetPluginRoot = path.join(targetPluginsRoot, "helloloop");
-  const marketplaceFile = path.join(resolvedCodexHome, ".agents", "plugins", "marketplace.json");
-  const manifestFile = path.join(bundleRoot, ".codex-plugin", "plugin.json");
-
-  if (!fileExists(manifestFile)) {
-    throw new Error(`未找到 Codex 插件 manifest：${manifestFile}`);
-  }
-
-  assertPathInside(resolvedCodexHome, targetPluginRoot, "Codex 目标插件目录");
-  removeTargetIfNeeded(targetPluginRoot, options.force);
-
-  ensureDir(targetPluginsRoot);
-  ensureDir(targetPluginRoot);
-  copyBundleEntries(bundleRoot, targetPluginRoot, codexBundleEntries);
-
-  const gitMetadataPath = path.join(targetPluginRoot, ".git");
-  if (fileExists(gitMetadataPath)) {
-    fs.rmSync(gitMetadataPath, { recursive: true, force: true });
-  }
-
-  ensureDir(path.dirname(marketplaceFile));
-  updateCodexMarketplace(marketplaceFile);
-
-  return {
-    host: "codex",
-    displayName: "Codex",
-    targetRoot: targetPluginRoot,
-    marketplaceFile,
-  };
-}
-
-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 removedPlugin = removePathIfExists(targetPluginRoot);
-  const removedMarketplace = removeCodexMarketplaceEntry(marketplaceFile);
-
-  return {
-    host: "codex",
-    displayName: "Codex",
-    targetRoot: targetPluginRoot,
-    removed: removedPlugin || removedMarketplace,
-    marketplaceFile,
-  };
-}
-
-function installClaudeHost(bundleRoot, options) {
-  const resolvedClaudeHome = resolveHomeDir(options.claudeHome, ".claude");
-  const sourceMarketplaceRoot = path.join(bundleRoot, "hosts", "claude", "marketplace");
-  const sourceManifest = path.join(bundleRoot, ".claude-plugin", "plugin.json");
-  const pluginVersion = readJson(sourceManifest).version || readJson(path.join(bundleRoot, "package.json")).version;
-  const targetPluginsRoot = path.join(resolvedClaudeHome, "plugins");
-  const targetMarketplaceRoot = path.join(targetPluginsRoot, "marketplaces", CLAUDE_MARKETPLACE_NAME);
-  const targetCachePluginsRoot = path.join(targetPluginsRoot, "cache", CLAUDE_MARKETPLACE_NAME, "helloloop");
-  const targetInstalledPluginRoot = path.join(targetCachePluginsRoot, pluginVersion);
-  const knownMarketplacesFile = path.join(targetPluginsRoot, "known_marketplaces.json");
-  const installedPluginsFile = path.join(targetPluginsRoot, "installed_plugins.json");
-  const settingsFile = path.join(resolvedClaudeHome, "settings.json");
-
-  if (!fileExists(sourceManifest)) {
-    throw new Error(`未找到 Claude 插件 manifest：${sourceManifest}`);
-  }
-  if (!fileExists(path.join(sourceMarketplaceRoot, ".claude-plugin", "marketplace.json"))) {
-    throw new Error(`未找到 Claude marketplace 模板：${sourceMarketplaceRoot}`);
-  }
-
-  assertPathInside(resolvedClaudeHome, targetMarketplaceRoot, "Claude marketplace 目录");
-  assertPathInside(resolvedClaudeHome, targetInstalledPluginRoot, "Claude 插件缓存目录");
-  removeTargetIfNeeded(targetMarketplaceRoot, options.force);
-  removeTargetIfNeeded(targetCachePluginsRoot, options.force);
-
-  ensureDir(path.dirname(targetMarketplaceRoot));
-  ensureDir(path.dirname(targetInstalledPluginRoot));
-  copyDirectory(sourceMarketplaceRoot, targetMarketplaceRoot);
-  copyDirectory(path.join(sourceMarketplaceRoot, "plugins", "helloloop"), targetInstalledPluginRoot);
-  ensureDir(targetPluginsRoot);
-  const updatedAt = nowIso();
-  updateClaudeSettings(settingsFile, targetMarketplaceRoot);
-  updateClaudeKnownMarketplaces(knownMarketplacesFile, targetMarketplaceRoot, updatedAt);
-  updateClaudeInstalledPlugins(installedPluginsFile, targetInstalledPluginRoot, pluginVersion, updatedAt);
-
-  return {
-    host: "claude",
-    displayName: "Claude",
-    targetRoot: targetInstalledPluginRoot,
-    marketplaceFile: path.join(targetMarketplaceRoot, ".claude-plugin", "marketplace.json"),
-    settingsFile,
-  };
-}
-
-function uninstallClaudeHost(options) {
-  const resolvedClaudeHome = resolveHomeDir(options.claudeHome, ".claude");
-  const targetPluginsRoot = path.join(resolvedClaudeHome, "plugins");
-  const targetMarketplaceRoot = path.join(targetPluginsRoot, "marketplaces", CLAUDE_MARKETPLACE_NAME);
-  const targetCachePluginsRoot = path.join(targetPluginsRoot, "cache", CLAUDE_MARKETPLACE_NAME);
-  const knownMarketplacesFile = path.join(targetPluginsRoot, "known_marketplaces.json");
-  const installedPluginsFile = path.join(targetPluginsRoot, "installed_plugins.json");
-  const settingsFile = path.join(resolvedClaudeHome, "settings.json");
-
-  const removedMarketplaceDir = removePathIfExists(targetMarketplaceRoot);
-  const removedCacheDir = removePathIfExists(targetCachePluginsRoot);
-  const removedKnownMarketplace = removeClaudeKnownMarketplace(knownMarketplacesFile);
-  const removedInstalledPlugin = removeClaudeInstalledPlugin(installedPluginsFile);
-  const removedSettingsEntries = removeClaudeSettingsEntries(settingsFile);
-
-  return {
-    host: "claude",
-    displayName: "Claude",
-    targetRoot: targetCachePluginsRoot,
-    removed: [
-      removedMarketplaceDir,
-      removedCacheDir,
-      removedKnownMarketplace,
-      removedInstalledPlugin,
-      removedSettingsEntries,
-    ].some(Boolean),
-    marketplaceFile: path.join(targetMarketplaceRoot, ".claude-plugin", "marketplace.json"),
-    settingsFile,
-  };
-}
-
-function installGeminiHost(bundleRoot, options) {
-  const resolvedGeminiHome = resolveHomeDir(options.geminiHome, ".gemini");
-  const sourceExtensionRoot = path.join(bundleRoot, "hosts", "gemini", "extension");
-  const targetExtensionRoot = path.join(resolvedGeminiHome, "extensions", "helloloop");
-
-  if (!fileExists(path.join(sourceExtensionRoot, "gemini-extension.json"))) {
-    throw new Error(`未找到 Gemini 扩展清单：${sourceExtensionRoot}`);
-  }
-
-  assertPathInside(resolvedGeminiHome, targetExtensionRoot, "Gemini 扩展目录");
-  removeTargetIfNeeded(targetExtensionRoot, options.force);
-
-  ensureDir(path.dirname(targetExtensionRoot));
-  copyDirectory(sourceExtensionRoot, targetExtensionRoot);
-
-  return {
-    host: "gemini",
-    displayName: "Gemini",
-    targetRoot: targetExtensionRoot,
-  };
-}
-
-function uninstallGeminiHost(options) {
-  const resolvedGeminiHome = resolveHomeDir(options.geminiHome, ".gemini");
-  const targetExtensionRoot = path.join(resolvedGeminiHome, "extensions", "helloloop");
-
-  return {
-    host: "gemini",
-    displayName: "Gemini",
-    targetRoot: targetExtensionRoot,
-    removed: removePathIfExists(targetExtensionRoot),
-  };
-}
-
 function resolveInstallHosts(hostOption) {
   const normalized = String(hostOption || "codex").trim().toLowerCase();
   if (normalized === "all") {
@@ -421,6 +20,8 @@ function resolveInstallHosts(hostOption) {
   return [normalized];
 }
 
+export { runtimeBundleEntries };
+
 export function installPluginBundle(options = {}) {
   const bundleRoot = path.resolve(options.bundleRoot || path.join(__dirname, ".."));
   const selectedHosts = resolveInstallHosts(options.host);