helloloop 0.2.1 → 0.6.1

package/src/engine_selection.mjs

@@ -0,0 +1,335 @@
+import { loadProjectConfig, saveProjectConfig } from "./config.mjs";
+import {
+  getEngineDisplayName,
+  getHostDisplayName,
+  normalizeEngineName,
+  normalizeHostContext,
+} from "./engine_metadata.mjs";
+import { classifySwitchableEngineFailure } from "./engine_selection_failure.mjs";
+import {
+  buildCrossHostSwitchMessage,
+  buildEngineSelectionRequiredMessage,
+  buildNoAvailableEngineMessage,
+  buildUnavailableRequestedEngineMessage,
+  candidate,
+  detectEngineIntentFromRequestText,
+  engineSourceLabel,
+  isUserDirectedSource,
+} from "./engine_selection_messages.mjs";
+import { confirmCrossHostSwitch, promptSelectEngine } from "./engine_selection_prompt.mjs";
+import { probeExecutionEngines } from "./engine_selection_probe.mjs";
+import { loadUserSettings, resolveUserSettingsFile, saveUserSettings } from "./engine_selection_settings.mjs";
+
+function preferredRecommendationOrder(hostContext) {
+  return [
+    hostContext !== "terminal" ? hostContext : "",
+    "codex",
+    "claude",
+    "gemini",
+  ].filter(Boolean);
+}
+
+function recommendEngine({
+  hostContext,
+  availableEngines = [],
+  projectConfig = {},
+  userSettings = {},
+}) {
+  const recommendedCandidates = [
+    projectConfig.defaultEngine,
+    projectConfig.lastSelectedEngine,
+    userSettings.defaultEngine,
+    userSettings.lastSelectedEngine,
+    ...preferredRecommendationOrder(hostContext),
+  ].map((item) => normalizeEngineName(item)).filter(Boolean);
+
+  for (const candidate of recommendedCandidates) {
+    if (availableEngines.includes(candidate)) {
+      return candidate;
+    }
+  }
+  return availableEngines[0] || "";
+}
+
+function buildRecommendationBasis({
+  hostContext,
+  projectConfig = {},
+  userSettings = {},
+  recommendedEngine,
+}) {
+  if (!recommendedEngine) {
+    return "";
+  }
+  if (normalizeEngineName(projectConfig.defaultEngine) === recommendedEngine) {
+    return `推荐：项目默认引擎是 ${getEngineDisplayName(recommendedEngine)}。`;
+  }
+  if (normalizeEngineName(projectConfig.lastSelectedEngine) === recommendedEngine) {
+    return `推荐：项目上次使用的引擎是 ${getEngineDisplayName(recommendedEngine)}。`;
+  }
+  if (normalizeEngineName(userSettings.defaultEngine) === recommendedEngine) {
+    return `推荐：用户默认引擎是 ${getEngineDisplayName(recommendedEngine)}。`;
+  }
+  if (normalizeEngineName(userSettings.lastSelectedEngine) === recommendedEngine) {
+    return `推荐：用户上次使用的引擎是 ${getEngineDisplayName(recommendedEngine)}。`;
+  }
+  if (hostContext !== "terminal" && normalizeEngineName(hostContext) === recommendedEngine) {
+    return `推荐：当前宿主是 ${getHostDisplayName(hostContext)}。`;
+  }
+  return `推荐：当前可用引擎中更适合优先尝试 ${getEngineDisplayName(recommendedEngine)}。`;
+}
+
+async function promptForExplicitEngineSelection({
+  availableEngines,
+  hostContext,
+  projectConfig,
+  userSettings,
+}) {
+  const recommendedEngine = recommendEngine({
+    hostContext,
+    availableEngines,
+    projectConfig,
+    userSettings,
+  });
+  return promptSelectEngine(availableEngines, {
+    hostContext,
+    recommendedEngine,
+    message: [
+      "本轮开始前必须先明确执行引擎；未明确引擎时不会自动选择。",
+      `当前宿主：${getHostDisplayName(hostContext)}。`,
+      buildRecommendationBasis({
+        hostContext,
+        projectConfig,
+        userSettings,
+        recommendedEngine,
+      }),
+      "",
+      "请选择本次要使用的执行引擎：",
+    ].filter(Boolean).join("\n"),
+  });
+}
+
+function buildResolution({
+  engine,
+  source,
+  basis,
+  hostContext,
+  probes,
+}) {
+  const availableEngines = probes.filter((item) => item.ok).map((item) => item.engine);
+  return {
+    ok: true,
+    engine,
+    displayName: getEngineDisplayName(engine),
+    hostContext,
+    hostDisplayName: getHostDisplayName(hostContext),
+    source,
+    sourceLabel: engineSourceLabel(source),
+    basis: Array.isArray(basis) ? basis.filter(Boolean) : [],
+    probes,
+    availableEngines,
+  };
+}
+
+export { classifySwitchableEngineFailure, loadUserSettings, probeExecutionEngines, resolveUserSettingsFile, saveUserSettings };
+
+export function resolveHostContext(options = {}) {
+  const envCandidate = process.env.HELLOLOOP_HOST_CONTEXT || process.env.HELLOLOOP_HOST;
+  return normalizeHostContext(options.hostContext || envCandidate || "terminal");
+}
+
+export async function resolveEngineSelection({
+  context,
+  policy = {},
+  options = {},
+  interactive = true,
+} = {}) {
+  const hostContext = resolveHostContext(options);
+  const probes = probeExecutionEngines(policy);
+  const availableEngines = probes.filter((item) => item.ok).map((item) => item.engine);
+  const projectConfig = context ? loadProjectConfig(context) : {};
+  const userSettings = loadUserSettings(options);
+  const requestIntent = detectEngineIntentFromRequestText(
+    options.userRequestText || options.userIntent?.requestText || "",
+  );
+  const candidates = [];
+  const requestedEngine = normalizeEngineName(options.engine);
+  const requestedEngineSource = options.engineSource || "flag";
+
+  if (requestedEngine) {
+    candidates.push(candidate(requestedEngine, requestedEngineSource, [
+      requestedEngineSource === "leading_positional"
+        ? `命令首参数显式指定了 ${getEngineDisplayName(requestedEngine)}。`
+        : `命令参数显式指定了 ${getEngineDisplayName(requestedEngine)}。`,
+    ]));
+  } else if (requestIntent && !requestIntent.ambiguous) {
+    candidates.push(candidate(requestIntent.engine, "request_text", requestIntent.basis));
+  }
+
+  const attempted = new Set();
+  for (const item of candidates) {
+    if (!item.engine || attempted.has(item.engine)) {
+      continue;
+    }
+    attempted.add(item.engine);
+
+    if (availableEngines.includes(item.engine)) {
+      if (
+        hostContext !== "terminal"
+        && item.engine !== hostContext
+        && isUserDirectedSource(item.source)
+      ) {
+        if (!interactive) {
+          return {
+            ok: false,
+            code: "cross_host_engine_confirmation_required",
+            message: buildCrossHostSwitchMessage(hostContext, item.engine),
+            hostContext,
+            probes,
+            availableEngines,
+          };
+        }
+
+        const confirmed = await confirmCrossHostSwitch(hostContext, item.engine, buildCrossHostSwitchMessage);
+        if (!confirmed) {
+          return {
+            ok: false,
+            code: "cross_host_engine_cancelled",
+            message: "已取消跨宿主引擎切换，本次未开始执行。",
+            hostContext,
+            probes,
+            availableEngines,
+          };
+        }
+      }
+
+      return buildResolution({
+        engine: item.engine,
+        source: item.source,
+        basis: item.basis,
+        hostContext,
+        probes,
+      });
+    }
+
+    if (isUserDirectedSource(item.source)) {
+      const failedProbe = probes.find((probe) => probe.engine === item.engine);
+      if (!interactive || !availableEngines.length) {
+        return {
+          ok: false,
+          code: "requested_engine_unavailable",
+          message: buildUnavailableRequestedEngineMessage(item.engine, availableEngines, failedProbe),
+          hostContext,
+          probes,
+          availableEngines,
+        };
+      }
+
+      const fallbackEngine = await promptSelectEngine(availableEngines, {
+        hostContext,
+        recommendedEngine: recommendEngine({
+          hostContext,
+          availableEngines,
+          projectConfig,
+          userSettings,
+        }),
+        message: [
+          buildUnavailableRequestedEngineMessage(item.engine, availableEngines, failedProbe),
+          "",
+          "请选择一个可继续使用的引擎：",
+        ].join("\n"),
+      });
+      if (!fallbackEngine) {
+        return {
+          ok: false,
+          code: "requested_engine_cancelled",
+          message: "已取消执行引擎选择，本次未开始执行。",
+          hostContext,
+          probes,
+          availableEngines,
+        };
+      }
+
+      return buildResolution({
+        engine: fallbackEngine,
+        source: "interactive_choice",
+        basis: [
+          `原始指定引擎 ${getEngineDisplayName(item.engine)} 当前不可用。`,
+          `用户改为选择 ${getEngineDisplayName(fallbackEngine)}。`,
+        ],
+        hostContext,
+        probes,
+      });
+    }
+  }
+
+  if (!availableEngines.length) {
+    return {
+      ok: false,
+      code: "no_available_engine",
+      message: buildNoAvailableEngineMessage(hostContext, probes),
+      hostContext,
+      probes,
+      availableEngines,
+    };
+  }
+
+  if (!interactive) {
+    return {
+      ok: false,
+      code: "engine_selection_required",
+      message: [
+        "本轮开始前必须先明确执行引擎；当前未检测到用户已明确指定引擎。",
+        buildEngineSelectionRequiredMessage(hostContext, availableEngines),
+      ].join("\n\n"),
+      hostContext,
+      probes,
+      availableEngines,
+    };
+  }
+
+  const selectedEngine = await promptForExplicitEngineSelection({
+    availableEngines,
+    hostContext,
+    projectConfig,
+    userSettings,
+  });
+  if (!selectedEngine) {
+    return {
+      ok: false,
+      code: "engine_selection_cancelled",
+      message: "已取消执行引擎选择，本次未开始执行。",
+      hostContext,
+      probes,
+      availableEngines,
+    };
+  }
+
+  return buildResolution({
+    engine: selectedEngine,
+    source: "interactive_choice",
+    basis: [`用户在交互中选择了 ${getEngineDisplayName(selectedEngine)}。`],
+    hostContext,
+    probes,
+  });
+}
+
+export function rememberEngineSelection(context, engineResolution, options = {}) {
+  const engine = normalizeEngineName(engineResolution?.engine);
+  if (!engine) {
+    return;
+  }
+
+  if (context) {
+    const projectConfig = loadProjectConfig(context);
+    saveProjectConfig(context, {
+      ...projectConfig,
+      lastSelectedEngine: engine,
+    });
+  }
+
+  const userSettings = loadUserSettings(options);
+  saveUserSettings({
+    ...userSettings,
+    lastSelectedEngine: engine,
+  }, options);
+}

package/src/engine_selection_failure.mjs

@@ -0,0 +1,51 @@
+const SWITCHABLE_FAILURE_MATCHERS = [
+  {
+    code: "quota",
+    reason: "当前引擎可能遇到额度、配额或限流问题。",
+    patterns: [
+      "429",
+      "rate limit",
+      "too many requests",
+      "quota",
+      "credit",
+      "usage limit",
+      "capacity",
+      "overloaded",
+      "insufficient balance",
+    ],
+  },
+  {
+    code: "auth",
+    reason: "当前引擎可能未登录、鉴权失效或权限不足。",
+    patterns: [
+      "not authenticated",
+      "authentication",
+      "unauthorized",
+      "forbidden",
+      "login",
+      "api key",
+      "token",
+      "subscription",
+      "setup-token",
+      "sign in",
+    ],
+  },
+];
+
+export function classifySwitchableEngineFailure(detail = "") {
+  const normalized = String(detail || "").toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+
+  for (const matcher of SWITCHABLE_FAILURE_MATCHERS) {
+    if (matcher.patterns.some((pattern) => normalized.includes(pattern))) {
+      return {
+        code: matcher.code,
+        reason: matcher.reason,
+      };
+    }
+  }
+
+  return null;
+}

package/src/engine_selection_messages.mjs

@@ -0,0 +1,119 @@
+import { getEngineDisplayName, getHostDisplayName, normalizeEngineName } from "./engine_metadata.mjs";
+import { renderEngineList } from "./engine_selection_probe.mjs";
+
+const ENGINE_SOURCE_LABELS = {
+  flag: "命令参数",
+  leading_positional: "命令首参数",
+  request_text: "自然语言要求",
+  host_context: "当前宿主",
+  project_default: "项目默认引擎",
+  project_last: "项目上次引擎",
+  user_default: "用户默认引擎",
+  user_last: "用户上次引擎",
+  only_available: "唯一可用引擎",
+  interactive_choice: "交互选择",
+};
+
+export function detectEngineIntentFromRequestText(requestText = "") {
+  const normalized = String(requestText || "").toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+
+  const matches = new Set();
+  const pattern = /(^|[^a-z0-9])(codex|claude|gemini)(?=[^a-z0-9]|$)/g;
+  let match = pattern.exec(normalized);
+  while (match) {
+    matches.add(match[2]);
+    match = pattern.exec(normalized);
+  }
+
+  if (!matches.size) {
+    return null;
+  }
+
+  const engines = [...matches];
+  if (engines.length === 1) {
+    return {
+      engine: engines[0],
+      source: "request_text",
+      basis: [`补充要求里明确提到了 ${getEngineDisplayName(engines[0])}。`],
+      ambiguous: false,
+    };
+  }
+
+  return {
+    engine: "",
+    source: "request_text",
+    basis: [`补充要求里同时提到了多个引擎：${renderEngineList(engines)}。`],
+    ambiguous: true,
+    engines,
+  };
+}
+
+export function engineSourceLabel(source) {
+  return ENGINE_SOURCE_LABELS[source] || "自动判断";
+}
+
+export function candidate(engine, source, basis = []) {
+  return {
+    engine: normalizeEngineName(engine),
+    source,
+    basis: Array.isArray(basis) ? basis.filter(Boolean) : [],
+  };
+}
+
+export function isUserDirectedSource(source) {
+  return ["flag", "leading_positional", "request_text"].includes(source);
+}
+
+function describeProbeFailures(probes = []) {
+  return probes
+    .filter((item) => !item.ok)
+    .map((item) => `- ${getEngineDisplayName(item.engine)}：${item.detail || "不可用"}`);
+}
+
+export function buildEngineSelectionRequiredMessage(hostContext, availableEngines) {
+  const engineSummary = availableEngines.length > 1
+    ? `检测到可用执行引擎：${renderEngineList(availableEngines)}。`
+    : `检测到唯一可用执行引擎：${renderEngineList(availableEngines)}。`;
+  return [
+    engineSummary,
+    `当前宿主：${getHostDisplayName(hostContext)}。`,
+    "请显式指定要使用的引擎，例如：",
+    "- `npx helloloop codex`",
+    "- `npx helloloop claude <PATH>`",
+    "- `npx helloloop gemini <PATH> 继续开发`",
+  ].join("\n");
+}
+
+export function buildNoAvailableEngineMessage(hostContext, probes = []) {
+  const failureLines = describeProbeFailures(probes);
+  return [
+    `当前宿主：${getHostDisplayName(hostContext)}。`,
+    "未发现可安全执行的开发引擎（Codex / Claude / Gemini）。",
+    ...(failureLines.length ? ["", "检查结果：", ...failureLines] : []),
+    "",
+    "请先安装并确认至少一个 CLI 可正常执行，然后重试。",
+  ].join("\n");
+}
+
+export function buildUnavailableRequestedEngineMessage(engine, availableEngines, probe) {
+  const lines = [`你指定的执行引擎当前不可用：${getEngineDisplayName(engine)}。`];
+
+  if (probe?.detail) {
+    lines.push(`原因：${probe.detail}`);
+  }
+  if (availableEngines.length) {
+    lines.push(`当前仍可用的引擎：${renderEngineList(availableEngines)}。`);
+  }
+  lines.push("请改用可用引擎，或先修复该 CLI 的安装 / 登录 / 配额问题。");
+  return lines.join("\n");
+}
+
+export function buildCrossHostSwitchMessage(hostContext, engine) {
+  return [
+    `当前从 ${getHostDisplayName(hostContext)} 宿主发起，但本次将改用 ${getEngineDisplayName(engine)} 执行。`,
+    "这不会静默切换；请确认是否继续。",
+  ].join("\n");
+}

package/src/engine_selection_probe.mjs

@@ -0,0 +1,78 @@
+import { spawnSync } from "node:child_process";
+
+import { getEngineDisplayName, getEngineMetadata, listKnownEngines, normalizeEngineName } from "./engine_metadata.mjs";
+import { resolveCliInvocation } from "./shell_invocation.mjs";
+
+function resolveExecutableOverride(policy = {}, engine) {
+  const envExecutable = String(process.env[`HELLOLOOP_${String(engine || "").toUpperCase()}_EXECUTABLE`] || "").trim();
+  if (envExecutable) {
+    return envExecutable;
+  }
+  return String(policy?.[engine]?.executable || "").trim();
+}
+
+function probeEngineAvailability(engine, policy = {}) {
+  const meta = getEngineMetadata(engine);
+  const invocation = resolveCliInvocation({
+    commandName: meta.commandName,
+    toolDisplayName: meta.displayName,
+    explicitExecutable: resolveExecutableOverride(policy, engine),
+  });
+
+  if (invocation.error) {
+    return {
+      engine,
+      ok: false,
+      detail: invocation.error,
+    };
+  }
+
+  const result = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
+    encoding: "utf8",
+    shell: invocation.shell,
+  });
+  const ok = result.status === 0;
+  return {
+    engine,
+    ok,
+    detail: ok
+      ? String(result.stdout || "").trim()
+      : String(result.stderr || result.error || `无法执行 ${meta.commandName} --version`).trim(),
+  };
+}
+
+export function probeExecutionEngines(policy = {}) {
+  return listKnownEngines().map((engine) => probeEngineAvailability(engine, policy));
+}
+
+export function uniqueEngines(items = []) {
+  const result = [];
+  const seen = new Set();
+  for (const item of items) {
+    const normalized = normalizeEngineName(item);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+export function rankEngines(engines, hostContext = "terminal") {
+  const preferredOrder = uniqueEngines([hostContext, "codex", "claude", "gemini"]);
+  return [...engines].sort((left, right) => {
+    const leftIndex = preferredOrder.indexOf(left);
+    const rightIndex = preferredOrder.indexOf(right);
+    const normalizedLeft = leftIndex >= 0 ? leftIndex : Number.MAX_SAFE_INTEGER;
+    const normalizedRight = rightIndex >= 0 ? rightIndex : Number.MAX_SAFE_INTEGER;
+    if (normalizedLeft !== normalizedRight) {
+      return normalizedLeft - normalizedRight;
+    }
+    return left.localeCompare(right, "en");
+  });
+}
+
+export function renderEngineList(engines = []) {
+  return rankEngines(engines).map((engine) => getEngineDisplayName(engine)).join("、");
+}

package/src/engine_selection_prompt.mjs

@@ -0,0 +1,48 @@
+import { getEngineDisplayName } from "./engine_metadata.mjs";
+import { rankEngines } from "./engine_selection_probe.mjs";
+import { createPromptSession } from "./prompt_session.mjs";
+
+function parseAffirmative(answer) {
+  const raw = String(answer || "").trim();
+  const normalized = raw.toLowerCase();
+  return ["y", "yes", "ok", "确认", "是", "继续", "好的"].includes(normalized)
+    || ["确认", "是", "继续", "好的"].includes(raw);
+}
+
+export async function confirmCrossHostSwitch(hostContext, engine, buildMessage) {
+  const promptSession = createPromptSession();
+  try {
+    const answer = await promptSession.question(
+      `${buildMessage(hostContext, engine)}\n请输入 y / yes / 确认 继续，其它任意输入取消：`,
+    );
+    return parseAffirmative(answer);
+  } finally {
+    promptSession.close();
+  }
+}
+
+export async function promptSelectEngine(availableEngines, options = {}) {
+  const promptSession = createPromptSession();
+  const ranked = rankEngines(availableEngines, options.hostContext);
+  const choiceLines = ranked.map((engine, index) => {
+    const suffix = engine === options.recommendedEngine ? "（推荐）" : "";
+    return `${index + 1}. ${getEngineDisplayName(engine)}${suffix}`;
+  });
+
+  try {
+    const answer = await promptSession.question([
+      options.message || "请选择本次要使用的执行引擎：",
+      ...choiceLines,
+      "",
+      "请输入编号；直接回车取消。",
+      "> ",
+    ].join("\n"));
+    const choiceIndex = Number(String(answer || "").trim());
+    if (!Number.isInteger(choiceIndex) || choiceIndex < 1 || choiceIndex > ranked.length) {
+      return "";
+    }
+    return ranked[choiceIndex - 1];
+  } finally {
+    promptSession.close();
+  }
+}

package/src/engine_selection_settings.mjs

@@ -0,0 +1,38 @@
+import os from "node:os";
+import path from "node:path";
+
+import { fileExists, readJson, writeJson } from "./common.mjs";
+import { normalizeEngineName } from "./engine_metadata.mjs";
+
+function defaultUserSettings() {
+  return {
+    defaultEngine: "",
+    lastSelectedEngine: "",
+  };
+}
+
+export function resolveUserSettingsFile(userSettingsFile = "") {
+  return userSettingsFile
+    || String(process.env.HELLOLOOP_USER_SETTINGS_FILE || "").trim()
+    || path.join(os.homedir(), ".helloloop", "settings.json");
+}
+
+export function loadUserSettings(options = {}) {
+  const settingsFile = resolveUserSettingsFile(options.userSettingsFile);
+  if (!fileExists(settingsFile)) {
+    return defaultUserSettings();
+  }
+
+  const settings = readJson(settingsFile);
+  return {
+    defaultEngine: normalizeEngineName(settings?.defaultEngine),
+    lastSelectedEngine: normalizeEngineName(settings?.lastSelectedEngine),
+  };
+}
+
+export function saveUserSettings(settings, options = {}) {
+  writeJson(resolveUserSettingsFile(options.userSettingsFile), {
+    defaultEngine: normalizeEngineName(settings?.defaultEngine),
+    lastSelectedEngine: normalizeEngineName(settings?.lastSelectedEngine),
+  });
+}