文档中 hapi runner start --foreground 选项未实现

[xiaoxuan010]

What version of HAPI is running?

hapi version: 0.17.2

What platform is your computer?

Windows 11 24H2

What issue are you seeing?

在 docs/guide/installation.md 中，多处文档示例使用 hapi runner start --foreground（如 pm2、nohup、launchd、systemd 场景），但实际 CLI 源码 cli/src/commands/runner.ts 并未解析或实现该参数。实际运行 hapi runner start --foreground 时，runner 依然以 detached（后台）方式运行，--foreground 被忽略，导致行为与文档描述不符，易导致误用。

What steps can reproduce the bug?

1. 按文档执行命令：hapi runner start --foreground
2. runner 实际依然以后台 detached 方式启动
3. 查看对应 CLI 源码 cli/src/commands/runner.ts，未有 foreground 参数相关逻辑

What is the expected behavior?

• CLI 层支持 --foreground，可以不以 detached 方式启动并让进程保持前台运行，方便 systemd/supervisor/容器等进程管理工具集成
  或
• 文档同步修正，移除/更正该参数用法，避免引起误导

Additional information

相关参考：

• 文档: docs/guide/installation.md
• CLI 代码: cli/src/commands/runner.ts

该问题会影响进程托管、自动重启、可观测性等生产级部署场景。

[github-actions]

已确认：当前代码中没有发现 --foreground 选项的解析或实现，文档里的示例与 CLI 行为不一致。

从当前实现看，hapi runner start 会固定启动一个 detached 的 runner start-sync 子进程，并忽略未解析的额外参数；公开帮助里也只列出了 --workspace-root，没有 --foreground。

Relevant code:

• cli/src/commands/runner.ts:104 - runner start 分支入口
• cli/src/commands/runner.ts:105 - 子进程参数固定为 ['runner', 'start-sync']
• cli/src/commands/runner.ts:109 - 通过 spawnHappyCLI(...) 启动 runner
• cli/src/commands/runner.ts:110 - detached: true
• cli/src/commands/runner.ts:134 - runner start-sync 分支会直接执行 startRunner({ workspaceRoot })
• cli/src/commands/runner.ts:169 - CLI 帮助只列出 --workspace-root <path>
• docs/guide/installation.md:369 - pm2 示例使用 hapi runner start --foreground
• docs/guide/installation.md:388 - nohup 示例使用 hapi runner start --foreground
• docs/guide/installation.md:476 - launchd 示例包含 --foreground
• docs/guide/installation.md:540 - systemd 示例使用 hapi runner start --foreground

Need more info:

• 期望修复方向：实现 hapi runner start --foreground，还是先修正文档移除该参数？

---

HAPI Bot