helloloop 0.8.6 → 0.10.0

package/src/cli_args.mjs

@@ -1,29 +1,60 @@
 const REPO_ROOT_PLACEHOLDER = "<REPO_ROOT>";
 const DOCS_PATH_PLACEHOLDER = "<DOCS_PATH>";
-const KNOWN_COMMANDS = new Set([
-  "__supervise",
-  "analyze",
-  "install",
-  "uninstall",
-  "init",
-  "status",
-  "next",
-  "run-once",
-  "run-loop",
-  "doctor",
-  "help",
-  "--help",
-  "-h",
+const KNOWN_ENGINES = new Set([
+  "codex",
+  "claude",
+  "gemini",
 ]);
+const COMMAND_ALIASES = Object.freeze({
+  "__supervise": "__supervise",
+  "__supervise-worker": "__supervise-worker",
+  "__web-server": "__web-server",
+  analyze: "analyze",
+  a: "analyze",
+  dashboard: "dashboard",
+  dash: "dashboard",
+  db: "dashboard",
+  tui: "tui",
+  web: "web",
+  install: "install",
+  i: "install",
+  uninstall: "uninstall",
+  un: "uninstall",
+  init: "init",
+  resume: "resume-host",
+  rh: "resume-host",
+  "resume-host": "resume-host",
+  status: "status",
+  st: "status",
+  watch: "watch",
+  w: "watch",
+  next: "next",
+  n: "next",
+  "run-once": "run-once",
+  once: "run-once",
+  "run-loop": "run-loop",
+  loop: "run-loop",
+  doctor: "doctor",
+  dr: "doctor",
+  help: "help",
+  "--help": "help",
+  "-h": "help",
+});
+const KNOWN_COMMANDS = new Set(Object.keys(COMMAND_ALIASES));
+
+function normalizeCommand(value = "") {
+  return COMMAND_ALIASES[String(value || "").trim()] || "";
+}
 
 export function parseArgs(argv) {
   const [first = "", ...restArgs] = argv;
+  const normalizedFirstCommand = normalizeCommand(first);
   const command = !first
     ? "analyze"
-    : (KNOWN_COMMANDS.has(first) ? first : "analyze");
+    : (normalizedFirstCommand || "analyze");
   const rest = !first
     ? []
-    : (KNOWN_COMMANDS.has(first) ? restArgs : argv);
+    : (normalizedFirstCommand ? restArgs : argv);
   const options = {
     requiredDocs: [],
     constraints: [],
@@ -34,11 +65,11 @@ export function parseArgs(argv) {
     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 === "--allow-high-risk" || arg === "-r") 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 === "--task-id" || arg === "-t") { options.taskId = rest[index + 1]; index += 1; }
+    else if (arg === "--max-tasks" || arg === "-m") { 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; }
@@ -51,12 +82,32 @@ export function parseArgs(argv) {
     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 === "--session-file") { options.sessionFile = rest[index + 1]; index += 1; }
-    else if (arg === "--supervised") options.supervised = true;
+    else if (arg === "--launch-id") { options.launchId = rest[index + 1]; index += 1; }
+    else if (arg === "--watch" || arg === "-w") options.watch = true;
+    else if (arg === "--detach" || arg === "-d") options.detach = true;
+    else if (arg === "--foreground") options.foreground = true;
+    else if (arg === "--stop") options.stop = true;
+    else if (arg === "--json" || arg === "-j") options.json = true;
+    else if (arg === "--compact" || arg === "-c") options.compact = true;
+    else if (arg === "--events" || arg === "-e") options.events = true;
+    else if (arg === "--session-id") { options.sessionId = rest[index + 1]; index += 1; }
+    else if (arg === "--watch-poll-ms") { options.watchPollMs = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--poll-ms" || arg === "-p") { options.pollMs = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--port") { options.port = Number(rest[index + 1]); index += 1; }
+    else if (arg === "--bind") { options.bind = 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); }
   }
 
+  const [leadingPositional = "", ...remainingPositionals] = options.positionalArgs;
+  const normalizedLeadingEngine = String(leadingPositional || "").trim().toLowerCase();
+  if (!options.engine && KNOWN_ENGINES.has(normalizedLeadingEngine)) {
+    options.engine = normalizedLeadingEngine;
+    options.engineSource = "leading_positional";
+    options.positionalArgs = remainingPositionals;
+  }
+
   return { command, options };
 }
 
@@ -65,15 +116,21 @@ function helpText() {
     "用法：helloloop [command] [engine] [path|需求说明...] [options]",
     "",
     "命令：",
-    "  analyze               自动分析并生成执行确认单；确认后继续自动接续开发（默认）",
-    "  install               安装插件到 Codex Home（适合 npx / npm bin 分发）",
-    "  uninstall             从所选宿主卸载插件并清理注册信息",
+    "  analyze | a           自动分析并生成执行确认单；确认后继续自动接续开发（默认）",
+    "  dashboard | dash | db 在当前终端启动动态 TUI 看板（默认总控台）",
+    "  tui                   dashboard 的显式别名，适合从主终端直接打开实时任务看板",
+    "  web                   启动本地 Web 看板；默认后台启动并输出访问地址",
+    "  install | i           安装插件到 Codex Home（适合 npx / npm bin 分发）",
+    "  uninstall | un        从所选宿主卸载插件并清理注册信息",
     "  init                  初始化 .helloloop 配置",
-    "  status                查看 backlog 与下一任务",
-    "  next                  生成下一任务干跑预览",
-    "  run-once              执行一个任务",
-    "  run-loop              连续执行多个任务",
-    "  doctor                检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
+    "  resume-host | resume | rh",
+    "                        输出当前仓库的宿主续跑自然语言提示，供主 CLI / 主代理中断后继续输入",
+    "  status | st           查看 backlog 与下一任务",
+    "  watch | w             附着到后台 supervisor，持续查看实时进度",
+    "  next | n              生成下一任务干跑预览",
+    "  run-once | once       执行一个任务",
+    "  run-loop | loop       连续执行多个任务",
+    "  doctor | dr           检查 Codex、当前插件 bundle 与目标仓库 .helloloop 配置是否可用",
     "",
     "选项：",
     "  --host <name>        安装宿主：codex | claude | gemini | all（默认 codex）",
@@ -86,12 +143,20 @@ function helpText() {
     "  --config-dir <dir>    配置目录，默认 .helloloop",
     "  -y, --yes             跳过交互确认，分析后直接开始自动执行",
     "  --dry-run             只分析并输出确认单，不真正开始自动执行",
-    "  --task-id <id>        指定任务 id",
-    "  --max-tasks <n>       run-loop 最多执行 n 个任务",
+    "  -t, --task-id <id>    指定任务 id",
+    "  -m, --max-tasks <n>   run-loop 最多执行 n 个任务",
     "  --max-attempts <n>    每种策略内最多重试 n 次",
     "  --max-strategies <n>  单任务最多切换 n 种策略继续重试",
-    "  --supervised          兼容保留；当前版本默认就会通过独立 supervisor 后台执行",
-    "  --allow-high-risk     允许执行 medium/high/critical 风险任务",
+    "  -w, --watch           启动后台 supervisor 后，当前终端继续附着观察实时输出",
+    "  -d, --detach          仅启动后台 supervisor 后立即返回，不进入观察模式",
+    "  --foreground          web 命令以前台模式运行本地服务",
+    "  --stop                web 命令停止当前本地看板服务",
+    "  -j, --json            以 JSON / NDJSON 形式输出结构化状态",
+    "  --session-id <id>     status/watch 指定附着的后台会话 ID",
+    "  -r, --allow-high-risk 手动 run-once/run-loop 时允许执行 medium/high/critical 风险任务",
+    "  -p, --poll-ms <n>     dashboard 轮询间隔（毫秒）",
+    "  --port <n>            web 命令指定监听端口，默认优先尝试 3210",
+    "  --bind <addr>         web 命令指定监听地址，默认 127.0.0.1",
     "  --rebuild-existing    分析判断当前项目与文档冲突时，自动清理当前项目后按文档重建",
     "  --required-doc <p>    增加一个全局必读文档（AGENTS.md 会被自动忽略）",
     "  --constraint <text>   增加一个全局实现约束",
@@ -100,6 +165,15 @@ function helpText() {
     "  analyze 默认支持在命令后混合传入引擎、路径和自然语言要求。",
     "  如果同时检测到多个可用引擎且没有明确指定，会先询问你选择。",
     "  当前版本默认会把自动执行 / run-once / run-loop 切到后台 supervisor。",
+    "  `helloloop dashboard` / `helloloop tui` 会打开终端实时总控台，不再把文本 dashboard 作为默认交互形态。",
+    "  `helloloop dashboard --json --watch` 仍可为宿主主代理提供结构化状态流。",
+    "  `helloloop web` 会启动本地 Web 看板，适合长时间像 Jira 一样查看多仓任务板。",
+    "  `helloloop resume-host --json` 会输出结构化续跑提示；不带 `--json` 时直接输出自然语言续跑内容。",
+    "  Windows 下 `analyze -y --detach` 会直接切到隐藏后台引导，不再保留前台空白控制台等待分析完成。",
+    "  Windows 下运行 Codex 时会优先绕过 codex.ps1，直接以隐藏原生 codex.exe 启动，并把内部 pwsh/powershell 调度重定向到隐藏代理，尽量避免额外 PowerShell 窗口闪烁。",
+    "  `watch` / `status --watch` / `dashboard --json --watch` 会按全局设置自动重试附着或重连；后台守护进程也会按设置保活重拉起。",
+    "  交互终端默认会自动附着观察；如只想立即返回，请显式加 --detach。",
+    "  任何时候都可运行 `helloloop watch` / `helloloop w` 或 `helloloop status --watch` / `helloloop st -w` 重新附着观察。",
     "  示例：npx helloloop claude <DOCS_PATH> <PROJECT_ROOT> 先分析偏差，不要执行",
   ].join("\n");
 }

package/src/cli_command_handlers.mjs

@@ -1,32 +1,21 @@
 import path from "node:path";
 
 import { createContext } from "./context.mjs";
+import { runDashboardCommand } from "./dashboard_command.mjs";
+import { runDashboardTuiCommand } from "./dashboard_tui.mjs";
+import { runDashboardWebCommand } from "./dashboard_web.mjs";
 import { loadBacklog, scaffoldIfMissing } from "./config.mjs";
 import { syncUserSettingsFile } from "./engine_selection_settings.mjs";
+import { readHostContinuationSnapshot, runHostContinuationCommand } from "./host_continuation.mjs";
 import { installPluginBundle, uninstallPluginBundle } from "./install.mjs";
 import { runLoop, runOnce, renderStatusText } from "./runner.mjs";
+import { collectRepoStatusSnapshot } from "./runner_status.mjs";
 import { renderInstallSummary, renderUninstallSummary } from "./cli_render.mjs";
 import {
-  launchSupervisedCommand,
-  renderSupervisorLaunchSummary,
-} from "./supervisor_runtime.mjs";
-
-function shouldUseSupervisor(options = {}) {
-  return !options.dryRun
-    && process.env.HELLOLOOP_SUPERVISOR_ACTIVE !== "1";
-}
-
-async function runSupervised(context, command, options = {}) {
-  const session = launchSupervisedCommand(context, command, options);
-  console.log(renderSupervisorLaunchSummary(session));
-  console.log("- 已切换为后台执行；可稍后运行 `helloloop status` 查看进度。");
-  return {
-    detached: true,
-    exitCode: 0,
-    ok: true,
-    session,
-  };
-}
+  launchAndMaybeWatchSupervisedCommand,
+  shouldUseSupervisor,
+} from "./supervisor_cli_support.mjs";
+import { watchSupervisorSessionWithRecovery } from "./supervisor_watch.mjs";
 
 export function handleInstallCommand(options) {
   const userSettings = syncUserSettingsFile({
@@ -79,9 +68,68 @@ export async function handleDoctorCommand(context, options, runDoctor) {
   return 0;
 }
 
-export function handleStatusCommand(context, options) {
-  console.log(renderStatusText(context, options));
-  return 0;
+export async function handleStatusCommand(context, options) {
+  const hostResume = readHostContinuationSnapshot(context, {
+    refresh: true,
+    sessionId: options.sessionId || "",
+  });
+  if (options.json) {
+    console.log(JSON.stringify({
+      ...collectRepoStatusSnapshot(context, options),
+      hostResume,
+    }, null, 2));
+  } else {
+    console.log(renderStatusText(context, {
+      ...options,
+      hostResume,
+    }));
+  }
+  if (!options.watch) {
+    return 0;
+  }
+
+  const result = await watchSupervisorSessionWithRecovery(context, {
+    sessionId: options.sessionId,
+    pollMs: options.watchPollMs,
+    globalConfigFile: options.globalConfigFile,
+  });
+  if (result.empty) {
+    console.log("当前没有正在运行的后台 supervisor。");
+    return 1;
+  }
+  return result.exitCode || 0;
+}
+
+export async function handleDashboardCommand(options) {
+  if (options.json === true) {
+    return runDashboardCommand(options);
+  }
+  return runDashboardTuiCommand(options);
+}
+
+export async function handleTuiCommand(options) {
+  return runDashboardTuiCommand(options);
+}
+
+export async function handleWebCommand(options) {
+  return runDashboardWebCommand(options);
+}
+
+export async function handleResumeHostCommand(context, options) {
+  return runHostContinuationCommand(context, options);
+}
+
+export async function handleWatchCommand(context, options) {
+  const result = await watchSupervisorSessionWithRecovery(context, {
+    sessionId: options.sessionId,
+    pollMs: options.watchPollMs,
+    globalConfigFile: options.globalConfigFile,
+  });
+  if (result.empty) {
+    console.log("当前没有正在运行的后台 supervisor。");
+    return 1;
+  }
+  return result.exitCode || 0;
 }
 
 export async function handleNextCommand(context, options) {
@@ -109,7 +157,7 @@ export async function handleNextCommand(context, options) {
 
 export async function handleRunOnceCommand(context, options) {
   if (shouldUseSupervisor(options)) {
-    const payload = await runSupervised(context, "run-once", options);
+    const payload = await launchAndMaybeWatchSupervisedCommand(context, "run-once", options);
     return payload.exitCode || 0;
   }
 
@@ -133,7 +181,7 @@ export async function handleRunOnceCommand(context, options) {
 
 export async function handleRunLoopCommand(context, options) {
   if (shouldUseSupervisor(options)) {
-    const payload = await runSupervised(context, "run-loop", options);
+    const payload = await launchAndMaybeWatchSupervisedCommand(context, "run-loop", options);
     return payload.exitCode || 0;
   }
 

package/src/cli_support.mjs

@@ -19,6 +19,7 @@ function probeCodexVersion() {
   const codexVersion = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
     encoding: "utf8",
     shell: invocation.shell,
+    windowsHide: process.platform === "win32",
   });
   const ok = codexVersion.status === 0;
   return {
@@ -113,6 +114,7 @@ function probeNamedCliVersion(commandName, toolDisplayName) {
   const result = spawnSync(invocation.command, [...invocation.argsPrefix, "--version"], {
     encoding: "utf8",
     shell: invocation.shell,
+    windowsHide: process.platform === "win32",
   });
   const ok = result.status === 0;
   return {

package/src/common.mjs

@@ -26,6 +26,11 @@ export function writeText(filePath, content) {
   fs.writeFileSync(filePath, content, "utf8");
 }
 
+export function appendText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, content, "utf8");
+}
+
 export function writeJson(filePath, value) {
   writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
@@ -64,3 +69,9 @@ export function resolveFrom(rootDir, ...segments) {
 export function normalizeRelative(rootDir, targetPath) {
   return path.relative(rootDir, targetPath).replaceAll("\\", "/");
 }
+
+export function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, Math.max(0, Number(ms || 0)));
+  });
+}