helloloop 0.2.1 → 0.6.1

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() {
@@ -28,34 +28,30 @@ function probeCodexVersion() {
   };
 }
 
-export function collectDoctorChecks(context) {
-  const codexVersion = probeCodexVersion();
+function shouldCheckProjectRuntime(context, options = {}) {
+  if (options.repoRoot || options.inputPath) {
+    return true;
+  }
+
+  if (context.repoRoot !== context.toolRoot) {
+    return true;
+  }
+
   return [
+    context.backlogFile,
+    context.policyFile,
+    context.projectFile,
+  ].some((filePath) => fileExists(filePath));
+}
+
+export function collectDoctorChecks(context, options = {}) {
+  const codexVersion = probeCodexVersion();
+  const checks = [
     {
       name: "codex CLI",
       ok: codexVersion.ok,
       detail: codexVersion.detail,
     },
-    {
-      name: "backlog.json",
-      ok: fileExists(context.backlogFile),
-      detail: context.backlogFile,
-    },
-    {
-      name: "policy.json",
-      ok: fileExists(context.policyFile),
-      detail: context.policyFile,
-    },
-    {
-      name: "verify.yaml",
-      ok: fileExists(context.repoVerifyFile),
-      detail: context.repoVerifyFile,
-    },
-    {
-      name: "project.json",
-      ok: fileExists(context.projectFile),
-      detail: context.projectFile,
-    },
     {
       name: "plugin manifest",
       ok: fileExists(context.pluginManifestFile),
@@ -72,6 +68,33 @@ export function collectDoctorChecks(context) {
       detail: context.installScriptFile,
     },
   ];
+
+  if (shouldCheckProjectRuntime(context, options)) {
+    checks.splice(1, 0,
+      {
+        name: "backlog.json",
+        ok: fileExists(context.backlogFile),
+        detail: context.backlogFile,
+      },
+      {
+        name: "policy.json",
+        ok: fileExists(context.policyFile),
+        detail: context.policyFile,
+      },
+      {
+        name: "verify.yaml",
+        ok: fileExists(context.repoVerifyFile),
+        detail: context.repoVerifyFile,
+      },
+      {
+        name: "project.json",
+        ok: fileExists(context.projectFile),
+        detail: context.projectFile,
+      },
+    );
+  }
+
+  return checks;
 }
 
 function probeNamedCliVersion(commandName, toolDisplayName) {
@@ -108,7 +131,7 @@ function normalizeDoctorHosts(hostOption) {
 }
 
 function collectCodexDoctorChecks(context, options = {}) {
-  const checks = collectDoctorChecks(context);
+  const checks = collectDoctorChecks(context, options);
   if (options.codexHome) {
     checks.push({
       name: "codex installed plugin",
@@ -265,19 +288,57 @@ 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();
+  }
+}
+
+export function shouldConfirmRepoRebuild(analysis, discovery) {
+  return analysis?.repoDecision?.action === "confirm_rebuild"
+    && discovery?.resolution?.repo?.exists !== false;
+}
+
+export async function confirmRepoConflictResolution(analysis) {
+  const decision = analysis?.repoDecision || {};
+  const promptSession = createPromptSession();
+
+  const promptText = [
+    "检测到当前项目与开发文档目标存在明显冲突：",
+    `- ${decision.reason || "分析结果认为当前项目更适合先确认处理方式。"}`,
+    "请选择后续动作：",
+    "1. 继续在当前项目上尝试接续",
+    "2. 清理当前项目内容后按文档目标重新开始（推荐）",
+    "3. 取消本次执行",
+    "请输入 1 / 2 / 3：",
+  ].join("\n");
+
+  try {
+    const answer = String(await promptSession.question(promptText) || "").trim();
+    if (["2", "重建", "rebuild"].includes(answer.toLowerCase ? answer.toLowerCase() : answer)) {
+      return "rebuild";
+    }
+    if (["1", "继续", "continue"].includes(answer.toLowerCase ? answer.toLowerCase() : answer)) {
+      return "continue";
+    }
+    return "cancel";
+  } finally {
+    promptSession.close();
   }
 }
 
+export function renderRepoConflictStopMessage(analysis) {
+  return [
+    "当前项目与开发文档目标存在明显冲突，已暂停自动执行。",
+    analysis?.repoDecision?.reason ? `原因：${analysis.repoDecision.reason}` : "",
+    "请重新运行交互式 `npx helloloop` 进行选择，或显式追加 `--rebuild-existing` 后再执行。",
+  ].filter(Boolean).join("\n");
+}
+
 export function renderAnalyzeStopMessage(reason) {
   return reason || "当前没有可自动执行的任务。";
 }
@@ -285,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 = [
     "自动执行结果",
     "============",
@@ -316,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 {