helloloop 0.3.1 → 0.7.0

package/src/cli_analyze_command.mjs

@@ -0,0 +1,248 @@
+import { analyzeExecution } from "./backlog.mjs";
+import { renderAnalyzeConfirmation, resolveAutoRunMaxTasks } from "./analyze_confirmation.mjs";
+import {
+  confirmAutoExecution,
+  confirmRepoConflictResolution,
+  renderAnalyzeStopMessage,
+  renderAutoRunSummary,
+  renderRepoConflictStopMessage,
+} from "./cli_support.mjs";
+import { analyzeWorkspace } from "./analyzer.mjs";
+import {
+  hasBlockingInputIssues,
+  renderBlockingInputIssueMessage,
+} from "./analyze_user_input.mjs";
+import { loadBacklog, loadPolicy } from "./config.mjs";
+import { createContext } from "./context.mjs";
+import { createDiscoveryPromptSession, resolveDiscoveryFailureInteractively } from "./discovery_prompt.mjs";
+import { resolveEngineSelection } from "./engine_selection.mjs";
+import { resetRepoForRebuild } from "./rebuild.mjs";
+import { runLoop } from "./runner.mjs";
+import { renderRebuildSummary } from "./cli_render.mjs";
+import { shouldConfirmRepoRebuild } from "./cli_support.mjs";
+
+async function resolveAnalyzeEngineSelection(options) {
+  if (options.engineResolution?.ok) {
+    return options.engineResolution;
+  }
+
+  const provisionalContext = createContext({
+    repoRoot: options.repoRoot || process.cwd(),
+    configDirName: options.configDirName,
+  });
+  return resolveEngineSelection({
+    context: provisionalContext,
+    policy: loadPolicy(provisionalContext),
+    options,
+    interactive: !options.yes,
+  });
+}
+
+async function analyzeWithResolvedDiscovery(options) {
+  let currentOptions = { ...options };
+  let lastResult = null;
+  let promptSession = null;
+
+  function getPromptSession() {
+    if (currentOptions.yes) {
+      return null;
+    }
+    if (!promptSession) {
+      promptSession = createDiscoveryPromptSession();
+    }
+    return promptSession;
+  }
+
+  try {
+    const engineResolution = await resolveAnalyzeEngineSelection(currentOptions);
+    if (!engineResolution.ok) {
+      return {
+        options: currentOptions,
+        result: {
+          ok: false,
+          code: engineResolution.code,
+          summary: engineResolution.message,
+          discovery: null,
+          engineResolution,
+        },
+      };
+    }
+    currentOptions = {
+      ...currentOptions,
+      engineResolution,
+    };
+
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      lastResult = await analyzeWorkspace({
+        cwd: process.cwd(),
+        inputPath: currentOptions.inputPath,
+        repoRoot: currentOptions.repoRoot,
+        docsPath: currentOptions.docsPath,
+        configDirName: currentOptions.configDirName,
+        allowNewRepoRoot: currentOptions.allowNewRepoRoot,
+        engine: currentOptions.engine,
+        engineSource: currentOptions.engineSource,
+        engineResolution: currentOptions.engineResolution,
+        hostContext: currentOptions.hostContext,
+        userRequestText: currentOptions.userRequestText,
+        yes: currentOptions.yes,
+        selectionSources: currentOptions.selectionSources,
+        userIntent: currentOptions.userIntent,
+      });
+
+      if (lastResult.ok) {
+        return { options: currentOptions, result: lastResult };
+      }
+
+      const nextOptions = await resolveDiscoveryFailureInteractively(
+        lastResult,
+        currentOptions,
+        process.cwd(),
+        !currentOptions.yes,
+        getPromptSession(),
+      );
+      if (!nextOptions) {
+        break;
+      }
+      currentOptions = nextOptions;
+    }
+  } finally {
+    promptSession?.close();
+  }
+
+  return { options: currentOptions, result: lastResult };
+}
+
+function printAnalyzeConfirmation(result, activeOptions) {
+  console.log(renderAnalyzeConfirmation(
+    result.context,
+    result.analysis,
+    result.backlog,
+    activeOptions,
+    result.discovery,
+  ));
+  console.log("");
+}
+
+async function resolveRepoConflict(analyzed, result, activeOptions) {
+  if (!shouldConfirmRepoRebuild(result.analysis, result.discovery)) {
+    return { state: "ready", analyzed, result, activeOptions };
+  }
+
+  if (activeOptions.rebuildExisting) {
+    const resetSummary = resetRepoForRebuild(result.context, result.discovery);
+    console.log(renderRebuildSummary(resetSummary));
+    console.log("");
+    return {
+      state: "reanalyze",
+      options: {
+        ...activeOptions,
+        repoRoot: result.context.repoRoot,
+        rebuildExisting: false,
+      },
+    };
+  }
+
+  if (activeOptions.yes) {
+    console.log(renderRepoConflictStopMessage(result.analysis));
+    return { state: "exit", exitCode: 1 };
+  }
+
+  const repoConflictDecision = await confirmRepoConflictResolution(result.analysis);
+  if (repoConflictDecision === "cancel") {
+    console.log("已取消自动执行；分析结果与 backlog 已保留在 .helloloop/。");
+    return { state: "done" };
+  }
+  if (repoConflictDecision === "continue") {
+    return { state: "ready", analyzed, result, activeOptions };
+  }
+
+  const resetSummary = resetRepoForRebuild(result.context, result.discovery);
+  console.log(renderRebuildSummary(resetSummary));
+  console.log("");
+  return {
+    state: "reanalyze",
+    options: {
+      ...activeOptions,
+      repoRoot: result.context.repoRoot,
+      rebuildExisting: false,
+    },
+  };
+}
+
+async function prepareAnalyzeExecution(initialOptions) {
+  let analyzed = await analyzeWithResolvedDiscovery(initialOptions);
+  let result = analyzed.result;
+  let activeOptions = analyzed.options;
+
+  while (true) {
+    if (!result.ok) {
+      console.error(result.summary);
+      return { exitCode: 1 };
+    }
+    if (result.engineResolution?.ok) {
+      activeOptions = {
+        ...activeOptions,
+        engineResolution: result.engineResolution,
+      };
+    }
+
+    printAnalyzeConfirmation(result, activeOptions);
+    const conflictResolution = await resolveRepoConflict(analyzed, result, activeOptions);
+    if (conflictResolution.state === "ready") {
+      return { result, activeOptions };
+    }
+    if (conflictResolution.state === "done" || conflictResolution.state === "exit") {
+      return { exitCode: conflictResolution.exitCode || 0 };
+    }
+
+    analyzed = await analyzeWithResolvedDiscovery(conflictResolution.options);
+    result = analyzed.result;
+    activeOptions = analyzed.options;
+  }
+}
+
+async function maybeRunAutoExecution(result, activeOptions) {
+  const execution = analyzeExecution(result.backlog, activeOptions);
+
+  if (activeOptions.dryRun) {
+    console.log("已按 --dry-run 跳过自动执行。");
+    return 0;
+  }
+  if (execution.state !== "ready") {
+    console.log(renderAnalyzeStopMessage(execution.blockedReason || "当前 backlog 已无可自动执行任务。"));
+    return 0;
+  }
+
+  const approved = activeOptions.yes ? true : await confirmAutoExecution();
+  if (!approved) {
+    console.log("已取消自动执行；分析结果与 backlog 已保留在 .helloloop/。");
+    return 0;
+  }
+
+  console.log("");
+  console.log("开始自动接续执行...");
+  const results = await runLoop(result.context, {
+    ...activeOptions,
+    engineResolution: result.engineResolution?.ok ? result.engineResolution : activeOptions.engineResolution,
+    maxTasks: resolveAutoRunMaxTasks(result.backlog, activeOptions) || undefined,
+    fullAutoMainline: true,
+  });
+  const refreshedBacklog = loadBacklog(result.context);
+  console.log(renderAutoRunSummary(result.context, refreshedBacklog, results, activeOptions));
+  return results.some((item) => !item.ok) ? 1 : 0;
+}
+
+export async function handleAnalyzeCommand(options) {
+  if (hasBlockingInputIssues(options.inputIssues)) {
+    console.error(renderBlockingInputIssueMessage(options.inputIssues));
+    return 1;
+  }
+
+  const prepared = await prepareAnalyzeExecution(options);
+  if (!prepared.result) {
+    return prepared.exitCode || 0;
+  }
+
+  return maybeRunAutoExecution(prepared.result, prepared.activeOptions);
+}

package/src/cli_args.mjs

@@ -0,0 +1,106 @@
+const REPO_ROOT_PLACEHOLDER = "<REPO_ROOT>";
+const DOCS_PATH_PLACEHOLDER = "<DOCS_PATH>";
+const KNOWN_COMMANDS = new Set([
+  "analyze",
+  "install",
+  "uninstall",
+  "init",
+  "status",
+  "next",
+  "run-once",
+  "run-loop",
+  "doctor",
+  "help",
+  "--help",
+  "-h",
+]);
+
+export function parseArgs(argv) {
+  const [first = "", ...restArgs] = argv;
+  const command = !first
+    ? "analyze"
+    : (KNOWN_COMMANDS.has(first) ? first : "analyze");
+  const rest = !first
+    ? []
+    : (KNOWN_COMMANDS.has(first) ? restArgs : argv);
+  const options = {
+    requiredDocs: [],
+    constraints: [],
+    positionalArgs: [],
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--yes" || arg === "-y") options.yes = true;
+    else if (arg === "--allow-high-risk") options.allowHighRisk = true;
+    else if (arg === "--rebuild-existing") options.rebuildExisting = true;
+    else if (arg === "--force") options.force = true;
+    else if (arg === "--task-id") { options.taskId = rest[index + 1]; index += 1; }
+    else if (arg === "--max-tasks") { options.maxTasks = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--max-attempts") { options.maxAttempts = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--max-strategies") { options.maxStrategies = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--repo") { options.repoRoot = rest[index + 1]; index += 1; }
+    else if (arg === "--docs") { options.docsPath = rest[index + 1]; index += 1; }
+    else if (arg === "--host") { options.host = rest[index + 1]; index += 1; }
+    else if (arg === "--engine") { options.engine = rest[index + 1]; options.engineSource = "flag"; index += 1; }
+    else if (arg === "--host-context") { options.hostContext = rest[index + 1]; index += 1; }
+    else if (arg === "--codex-home") { options.codexHome = rest[index + 1]; index += 1; }
+    else if (arg === "--claude-home") { options.claudeHome = rest[index + 1]; index += 1; }
+    else if (arg === "--gemini-home") { options.geminiHome = rest[index + 1]; index += 1; }
+    else if (arg === "--config-dir") { options.configDirName = rest[index + 1]; index += 1; }
+    else if (arg === "--required-doc") { options.requiredDocs.push(rest[index + 1]); index += 1; }
+    else if (arg === "--constraint") { options.constraints.push(rest[index + 1]); index += 1; }
+    else { options.positionalArgs.push(arg); }
+  }
+
+  return { command, options };
+}
+
+function helpText() {
+  return [
+    "用法：helloloop [command] [engine] [path|需求说明...] [options]",
+    "",
+    "命令：",
+    "  analyze               自动分析并生成执行确认单；确认后继续自动接续开发（默认）",
+    "  install               安装插件到 Codex Home（适合 npx / npm bin 分发）",
+    "  uninstall             从所选宿主卸载插件并清理注册信息",
+    "  init                  初始化 .helloloop 配置",
+    "  status                查看 backlog 与下一任务",
+    "  next                  生成下一任务干跑预览",
+    "  run-once              执行一个任务",
+    "  run-loop              连续执行多个任务",
+    "  doctor                检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
+    "",
+    "选项：",
+    "  --host <name>        安装宿主：codex | claude | gemini | all（默认 codex）",
+    "  --codex-home <dir>    Codex Home，install 默认使用 ~/.codex",
+    "  --claude-home <dir>   Claude Home，install 默认使用 ~/.claude",
+    "  --gemini-home <dir>   Gemini Home，install 默认使用 ~/.gemini",
+    "  [engine]             analyze 默认支持直接写：codex | claude | gemini",
+    "  --repo <dir>          高级选项：显式指定项目仓库根目录",
+    "  --docs <dir|file>     高级选项：显式指定开发文档目录或文件",
+    "  --config-dir <dir>    配置目录，默认 .helloloop",
+    "  -y, --yes             跳过交互确认，分析后直接开始自动执行",
+    "  --dry-run             只分析并输出确认单，不真正开始自动执行",
+    "  --task-id <id>        指定任务 id",
+    "  --max-tasks <n>       run-loop 最多执行 n 个任务",
+    "  --max-attempts <n>    每种策略内最多重试 n 次",
+    "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
+    "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
+    "  --rebuild-existing    分析判断当前项目与文档冲突时，自动清理当前项目后按文档重建",
+    "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
+    "  --constraint <text>   增加一个全局实现约束",
+    "",
+    "补充说明：",
+    "  analyze 默认支持在命令后混合传入引擎、路径和自然语言要求。",
+    "  如果同时检测到多个可用引擎且没有明确指定，会先询问你选择。",
+    "  示例：npx helloloop claude <DOCS_PATH> <PROJECT_ROOT> 先分析偏差，不要执行",
+  ].join("\n");
+}
+
+export function printHelp() {
+  console.log(helpText());
+}
+
+export { DOCS_PATH_PLACEHOLDER, REPO_ROOT_PLACEHOLDER };

package/src/cli_command_handlers.mjs

@@ -0,0 +1,120 @@
+import path from "node:path";
+
+import { createContext } from "./context.mjs";
+import { loadBacklog, scaffoldIfMissing } from "./config.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 context = createContext({
+    repoRoot: options.repoRoot,
+    configDirName: options.configDirName,
+  });
+  const result = installPluginBundle({
+    bundleRoot: context.bundleRoot,
+    host: options.host,
+    codexHome: options.codexHome,
+    claudeHome: options.claudeHome,
+    geminiHome: options.geminiHome,
+    force: options.force,
+  });
+  console.log(renderInstallSummary(result));
+  return 0;
+}
+
+export function handleUninstallCommand(options) {
+  const result = uninstallPluginBundle({
+    host: options.host,
+    codexHome: options.codexHome,
+    claudeHome: options.claudeHome,
+    geminiHome: options.geminiHome,
+  });
+  console.log(renderUninstallSummary(result));
+  return 0;
+}
+
+export function handleInitCommand(context) {
+  const created = scaffoldIfMissing(context);
+  if (!created.length) {
+    console.log("HelloLoop 配置已存在，无需初始化。");
+    return 0;
+  }
+
+  console.log([
+    "已初始化以下文件：",
+    ...created.map((item) => `- ${path.relative(context.repoRoot, item).replaceAll("\\", "/")}`),
+  ].join("\n"));
+  return 0;
+}
+
+export async function handleDoctorCommand(context, options, runDoctor) {
+  await runDoctor(context, options);
+  return 0;
+}
+
+export function handleStatusCommand(context, options) {
+  console.log(renderStatusText(context, options));
+  return 0;
+}
+
+export async function handleNextCommand(context, options) {
+  const result = await runOnce(context, { ...options, dryRun: true });
+  if (!result.task) {
+    console.log("当前没有可执行任务。");
+    return 0;
+  }
+
+  console.log([
+    "下一任务预览",
+    "============",
+    `任务：${result.task.title}`,
+    `编号：${result.task.id}`,
+    `运行目录：${result.runDir}`,
+    "",
+    "验证命令：",
+    ...result.verifyCommands.map((item) => `- ${item}`),
+    "",
+    "提示词：",
+    result.prompt,
+  ].join("\n"));
+  return 0;
+}
+
+export async function handleRunOnceCommand(context, options) {
+  const result = await runOnce(context, options);
+  if (!result.ok) {
+    console.error(result.summary || "执行失败。");
+    return 1;
+  }
+  if (options.dryRun) {
+    console.log(result.task
+      ? `已生成干跑预览：${result.task.title}\n运行目录：${result.runDir}`
+      : "当前没有可执行任务。");
+    return 0;
+  }
+
+  console.log(result.task
+    ? `完成任务：${result.task.title}\n运行目录：${result.runDir}`
+    : "没有可执行任务。");
+  return 0;
+}
+
+export async function handleRunLoopCommand(context, options) {
+  const results = await runLoop(context, options);
+  const failed = results.find((item) => !item.ok);
+
+  for (const item of results) {
+    if (!item.task) {
+      console.log("没有更多可执行任务。");
+      break;
+    }
+    console.log(`${item.ok ? "成功" : "失败"}：${item.task.title}`);
+  }
+
+  if (failed) {
+    console.error(failed.summary || "连续执行中断。");
+    return 1;
+  }
+  return 0;
+}

package/src/cli_context.mjs

@@ -0,0 +1,31 @@
+import { createContext } from "./context.mjs";
+import { resolveRepoRoot } from "./discovery.mjs";
+
+export function resolveContextFromOptions(options) {
+  const resolvedRepo = resolveRepoRoot({
+    cwd: process.cwd(),
+    repoRoot: options.repoRoot,
+    inputPath: options.inputPath,
+  });
+
+  if (!resolvedRepo.ok) {
+    throw new Error(resolvedRepo.message);
+  }
+
+  return createContext({
+    repoRoot: resolvedRepo.repoRoot,
+    configDirName: options.configDirName,
+  });
+}
+
+export function resolveStandardCommandOptions(options) {
+  const nextOptions = { ...options };
+  const positionals = Array.isArray(nextOptions.positionalArgs) ? nextOptions.positionalArgs : [];
+  if (positionals.length > 1) {
+    throw new Error(`未知参数：${positionals.slice(1).join(" ")}`);
+  }
+  if (positionals.length === 1 && !nextOptions.inputPath) {
+    nextOptions.inputPath = positionals[0];
+  }
+  return nextOptions;
+}

package/src/cli_render.mjs

@@ -0,0 +1,70 @@
+import { DOCS_PATH_PLACEHOLDER, REPO_ROOT_PLACEHOLDER } from "./cli_args.mjs";
+
+function renderFollowupExamples() {
+  return [
+    "下一步示例：",
+    "npx helloloop",
+    "npx helloloop <PATH>",
+    "npx helloloop codex",
+    "npx helloloop claude <PATH>",
+    "npx helloloop gemini <PATH> 继续完成后续开发",
+    "npx helloloop --dry-run",
+    "npx helloloop install --host all",
+    "npx helloloop uninstall --host all",
+    "npx helloloop next",
+    `如需显式补充路径：npx helloloop --repo ${REPO_ROOT_PLACEHOLDER} --docs ${DOCS_PATH_PLACEHOLDER}`,
+  ].join("\n");
+}
+
+export function renderInstallSummary(result) {
+  const lines = ["HelloLoop 已安装到以下宿主："];
+
+  for (const item of result.installedHosts) {
+    lines.push(`- ${item.displayName}：${item.targetRoot}`);
+    if (item.marketplaceFile) {
+      lines.push(`  marketplace：${item.marketplaceFile}`);
+    }
+    if (item.settingsFile) {
+      lines.push(`  settings：${item.settingsFile}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("使用入口：");
+  lines.push("- Codex：`$helloloop` / `npx helloloop`");
+  lines.push("- Claude：`/helloloop`");
+  lines.push("- Gemini：`/helloloop`");
+  lines.push("");
+  lines.push(renderFollowupExamples());
+  return lines.join("\n");
+}
+
+export function renderUninstallSummary(result) {
+  const lines = ["HelloLoop 已从以下宿主卸载："];
+
+  for (const item of result.uninstalledHosts) {
+    lines.push(`- ${item.displayName}：${item.removed ? "已清理" : "未发现现有安装"}`);
+    lines.push(`  目标目录：${item.targetRoot}`);
+    if (item.marketplaceFile) {
+      lines.push(`  marketplace：${item.marketplaceFile}`);
+    }
+    if (item.settingsFile) {
+      lines.push(`  settings：${item.settingsFile}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("如需重新安装：");
+  lines.push("- `npx helloloop install --host codex`");
+  lines.push("- `npx helloloop install --host all`");
+  return lines.join("\n");
+}
+
+export function renderRebuildSummary(resetSummary) {
+  return [
+    "已按确认结果清理当前项目，并准备按开发文档重新开始。",
+    `- 已清理顶层条目：${resetSummary.removedEntries.length ? resetSummary.removedEntries.join("，") : "无"}`,
+    `- 已保留开发文档：${resetSummary.preservedDocs.length ? resetSummary.preservedDocs.join("，") : "无"}`,
+    `- 重建记录：${resetSummary.manifestFile.replaceAll("\\", "/")}`,
+  ].join("\n");
+}

package/src/cli_support.mjs

@@ -1,9 +1,9 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
-import { createInterface } from "node:readline/promises";
 
 import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
 import { fileExists, readJson } from "./common.mjs";
+import { createPromptSession } from "./prompt_session.mjs";
 import { resolveCliInvocation, resolveCodexInvocation } from "./shell_invocation.mjs";
 
 function probeCodexVersion() {
@@ -288,16 +288,13 @@ function isAffirmativeAnswer(answer) {
 }
 
 export async function confirmAutoExecution() {
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const promptSession = createPromptSession();
 
   try {
-    const answer = await readline.question("是否开始自动接续执行？输入 y / yes / 确认 继续，其它任意输入取消：");
+    const answer = await promptSession.question("是否开始自动接续执行？输入 y / yes / 确认 继续，其它任意输入取消：");
     return isAffirmativeAnswer(answer);
   } finally {
-    readline.close();
+    promptSession.close();
   }
 }
 
@@ -308,10 +305,7 @@ export function shouldConfirmRepoRebuild(analysis, discovery) {
 
 export async function confirmRepoConflictResolution(analysis) {
   const decision = analysis?.repoDecision || {};
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const promptSession = createPromptSession();
 
   const promptText = [
     "检测到当前项目与开发文档目标存在明显冲突：",
@@ -324,7 +318,7 @@ export async function confirmRepoConflictResolution(analysis) {
   ].join("\n");
 
   try {
-    const answer = String(await readline.question(promptText) || "").trim();
+    const answer = String(await promptSession.question(promptText) || "").trim();
     if (["2", "重建", "rebuild"].includes(answer.toLowerCase ? answer.toLowerCase() : answer)) {
       return "rebuild";
     }
@@ -333,7 +327,7 @@ export async function confirmRepoConflictResolution(analysis) {
     }
     return "cancel";
   } finally {
-    readline.close();
+    promptSession.close();
   }
 }
 
@@ -352,6 +346,7 @@ export function renderAnalyzeStopMessage(reason) {
 export function renderAutoRunSummary(context, backlog, results, options = {}) {
   const summary = summarizeBacklog(backlog);
   const execution = analyzeExecution(backlog, options);
+  const mainlineClosed = results.some((item) => item.kind === "mainline-complete");
   const lines = [
     "自动执行结果",
     "============",
@@ -383,7 +378,9 @@ export function renderAutoRunSummary(context, backlog, results, options = {}) {
   lines.push("");
   lines.push("结论：");
   if (execution.state === "done") {
-    lines.push("- backlog 已全部完成");
+    lines.push(mainlineClosed
+      ? "- backlog 已全部完成，且主线终态复核通过"
+      : "- backlog 已全部完成");
   } else if (execution.blockedReason) {
     lines.push(`- 当前停止原因：${execution.blockedReason}`);
   } else {