cevio/hile-cli

@hile/cli SKILL

本文档面向代码生成器与维护者，强调“可执行约束”，而非入门说明。

1. 强约束（必须遵守）

1. hile.auto_load_packages 只允许模块名，禁止文件路径。
2. src/services/ 下 *.boot.* 与 *.service.* 同属 service 模块（均 defineService）；.boot = CLI 自启动，.service = loadService 依赖加载。
3. *.boot.ts / *.boot.js 必须位于 src/services/（如 src/services/index.boot.ts），禁止放在 src/ 根目录。
4. *.service.ts / *.service.js（依赖加载的 service 模块）必须同放在 src/services/。
5. boot 文件必须 export default 合法 Hile 服务（defineService / register 结果）。
6. 加载顺序必须固定：auto_load_packages → 扫描 boot。
7. 运行目录优先级必须固定：HILE_RUNTIME_DIR → src(dev) → dist。
8. CLI 必须订阅 container.on 并输出关键生命周期日志。
9. 进程退出时必须通过 registerExitHook(offEvent) 注册退出钩子；实现内对 @hile/core 的全局 container 调用 await container.shutdown()，仅在其完成后（含 TTY 下对 process.stdin.unref() 的收尾）在 finally 中执行 offEvent() 与 exit()；shutdown 未完成时进程挂起不退出（受 forceExitTimeout 上限保护）。

2. 容器事件日志约束

最小事件集：

• service:init
• service:ready
• service:error
• service:shutdown:start
• service:shutdown:done
• service:shutdown:error
• container:shutdown:start
• container:shutdown:done
• container:error

要求：

• 保留原始错误对象（错误单独一行输出，便于堆栈阅读）
• 输出统一日志前缀 [hile]，目标与状态自然拼接
• 记录可用耗时字段（durationMs），如 ready (12ms)
• 仅在 TTY 时启用 ANSI 颜色（成功绿、错误红、警告黄、中性 dim），非 TTY 不输出转义码

3. 反模式（禁止）

3.1 在 CLI 中重复实现容器语义

// ✗ 不要在 CLI 内自建另一套生命周期/依赖管理

// ✓ 复用 @hile/core 的 onEvent、shutdown、resolve 语义

3.2 boot 文件导出普通函数或配置

// ✗
export default function main() {}

// ✓
export default defineService('http', async (shutdown) => {
  // ...
})

3.3 忘记取消事件订阅

// ✗ 只订阅不释放
const off = container.on(listener)

// ✓ 退出时在 registerExitHook 的 finally 中调用 off()

3.4 退出钩子不调用 container.shutdown

// ✗ 直接 exit 不关闭容器
exitHook(exit => exit())

// ✓ 使用 registerExitHook(offEvent)，内部 await container.shutdown() 再 exit

4. 边界条件清单

• [ ] 无可加载服务时打印 no services to load 并退出
• [ ] 非法默认导出时报错包含目标文件或模块标识
• [ ] --dev 与非 dev 的 NODE_ENV 行为一致
• [ ] 多个 --env-file 加载顺序可预测
• [ ] shutdown 期间异常不会吞掉主错误
• [ ] 退出钩子：exit() 仅在 container.shutdown() 完成后调用；shutdown 未完成时进程挂起（见 exitHook 单测）
• [ ] TTY 场景下退出前对 process.stdin 调用 unref()，避免 stdin 拖住进程退出