@hile/cli 1.0.14 → 1.0.16

package/README.md

@@ -1,6 +1,6 @@
 # @hile/cli
 
-Hile 命令行工具，用于启动基于 `@hile/core` 的服务应用。支持通过 `package.json` 配置和/或自动扫描 `*.boot.{ts,js}` 文件加载服务，并注册退出钩子实现优雅关闭。
+Hile 命令行工具，用于启动基于 `@hile/core` 的服务应用。支持通过 `package.json` 配置和/或自动扫描 `*.boot.{ts,js}` 加载服务，并在进程退出时执行优雅关闭。
 
 ## 安装
 
@@ -8,7 +8,7 @@ Hile 命令行工具，用于启动基于 `@hile/core` 的服务应用。支持
 pnpm add @hile/cli
 ```
 
-全局安装后可直接使用 `hile` 命令：
+全局使用：
 
 ```bash
 pnpm add -g @hile/cli
@@ -18,43 +18,59 @@ pnpm add -g @hile/cli
 
 ### `hile start`
 
-在**当前工作目录**（通常为项目根，且含 `package.json`）下启动服务。按以下顺序加载服务并启动：
+在当前工作目录（通常为项目根，且包含 `package.json`）启动服务。加载顺序如下：
 
-1. **package.json 中的 `hile.auto_load_packages`**（若存在）：按数组顺序加载所列**模块名**的默认导出作为服务。
-2. **运行时目录下的 `*.boot.ts` / `*.boot.js`**：扫描并加载每个文件的默认导出作为服务。
+1. `package.json` 中的 `hile.auto_load_packages`（如存在）
+2. 运行时目录下的 `*.boot.ts` / `*.boot.js`
 
-若上述两者均未提供任何可加载项，CLI 会输出 `no services to load` 并退出。每个加载项（模块或 boot 文件）的默认导出须通过 `isService` 校验，否则会抛出 `invalid service file`。
+若两者都未提供可加载服务，CLI 输出 `no services to load` 并退出。每个加载项的默认导出都必须通过 `isService` 校验，否则抛出 `invalid service file`。
 
 ```bash
-hile start          # 生产模式：NODE_ENV=production，扫描 dist/ 目录
-hile start --dev    # 开发模式：NODE_ENV=development，扫描 src/ 目录（通过 tsx 支持 TypeScript）
+hile start
+hile start --dev
 ```
 
 | 选项 | 说明 | 默认值 |
 |------|------|--------|
-| `-d, --dev` | 开发模式：设置 `NODE_ENV=development`，使用 tsx 运行 TypeScript，扫描 `src/` | `false` |
-| `-e, --env-file <path>` | 加载指定 env 文件到 `process.env`（与 Node 原生 `--env-file` 语义一致：先加载的优先，已存在的 key 不覆盖）。可多次指定 | — |
+| `-d, --dev` | 开发模式：`NODE_ENV=development`，使用 tsx，扫描 `src/` | `false` |
+| `-e, --env-file <path>` | 加载 env 文件到 `process.env`，可多次指定 | — |
 
-未使用 `--dev` 时，CLI 会将 `process.env.NODE_ENV` 设为 `production`；使用 `--dev` 时设为 `development`，便于业务代码区分环境。
+- 非 `--dev` 模式：`NODE_ENV=production`
+- `--dev` 模式：`NODE_ENV=development`
 
-**示例：** `hile start --env-file .env --env-file .env.local` 会先加载 `.env`，再加载 `.env.local`（后者不会覆盖前者已设置的变量）。依赖 Node 20.12+ 原生 `process.loadEnvFile()`。
+示例：
 
-### 其他
+```bash
+hile start --env-file .env --env-file .env.local
+```
+
+依赖 Node 20.12+ 原生 `process.loadEnvFile()`。
+
+### 启动日志（基于 @hile/core 事件）
+
+CLI 已接入容器事件日志，默认会输出：
+
+- 服务启动：`service:init` / `service:ready`（含耗时）
+- 服务失败：`service:error`
+- 关闭阶段：`service:shutdown:start` / `service:shutdown:done`
+- 容器关闭：`container:shutdown:start` / `container:shutdown:done`
+
+这使得线上启动问题与关闭过程更容易观测。
+
+### 其他命令
 
 ```bash
-hile -v    # 查看版本号
-hile -h    # 查看帮助
+hile -v
+hile -h
 ```
 
 ## 运行时目录
 
-CLI 按以下优先级确定扫描目录：
-
-1. 环境变量 `HILE_RUNTIME_DIR`（如果设置）
-2. 开发模式（`--dev`）→ `src/`
-3. 生产模式 → `dist/`
+扫描目录优先级：
 
-可通过环境变量自定义：
+1. `HILE_RUNTIME_DIR`（若设置）
+2. `--dev` 模式：`src/`
+3. 生产模式：`dist/`
 
 ```bash
 HILE_RUNTIME_DIR=./custom hile start
@@ -62,7 +78,7 @@ HILE_RUNTIME_DIR=./custom hile start
 
 ## package.json 配置（可选）
 
-在项目根目录的 `package.json` 中可增加 `hile.auto_load_packages`，用于在扫描 boot 文件**之前**先加载指定模块的默认导出作为服务：
+可在项目根目录配置 `hile.auto_load_packages`，用于在扫描 boot 文件之前先加载指定模块：
 
 ```json
 {
@@ -73,14 +89,15 @@ HILE_RUNTIME_DIR=./custom hile start
 }
 ```
 
-- **含义**：数组中的每一项为**模块名**（与 `import('模块名')` 一致），不能写文件路径。
-- **顺序**：按数组顺序依次加载，再加载运行时目录下的 `*.boot.{ts,js}`。
-- **要求**：每个模块的默认导出必须是 `defineService` / `container.register` 的返回值（通过 `isService` 校验）。若无 `hile` 或 `auto_load_packages`，则仅通过 boot 文件加载服务。
-- **注意**：`hile` 配置为可选项。若当前工作目录存在 `package.json`，会读取其中可选的 `hile.auto_load_packages` 并优先加载；未配置该项时，仅通过 boot 文件加载服务。
+规则：
+
+- 数组项必须是模块名（与 `import('module')` 语义一致）
+- 按数组顺序加载，然后再扫描 `*.boot.{ts,js}`
+- 每个模块默认导出必须是合法 Hile 服务（通过 `isService`）
 
 ## Boot 文件规范
 
-每个 `*.boot.ts` 文件必须默认导出一个通过 `defineService` 定义的服务：
+每个 `*.boot.ts` / `*.boot.js` 文件必须默认导出一个服务：
 
 ```typescript
 // src/database.boot.ts
@@ -95,37 +112,38 @@ export default defineService(async (shutdown) => {
 })
 ```
 
-**要求：**
-- 文件名必须以 `.boot.ts` 或 `.boot.js` 结尾
-- 必须有 `default` 导出
-- 导出值必须是 `defineService` / `container.register` 的返回值（通过 `isService` 校验）
+要求：
+
+- 文件名后缀必须为 `.boot.ts` 或 `.boot.js`
+- 必须存在 `default` 导出
+- 导出值必须为 `defineService` / `container.register` 返回值
 
 ## 优雅关闭
 
-进程收到退出信号时（SIGTERM、SIGINT 等），CLI 自动调用 `container.shutdown()` 按逆序销毁所有已启动的服务，确保资源正确释放。
+进程收到 `SIGTERM`、`SIGINT` 等信号时，CLI 会自动调用 `container.shutdown()`，按逆序销毁已启动服务。
 
 ## 项目结构示例
 
-```
+```text
 my-app/
 ├── src/
-│   ├── database.boot.ts    # 数据库服务（自启动）
-│   ├── http.boot.ts        # HTTP 服务（自启动）
+│   ├── database.boot.ts
+│   ├── http.boot.ts
 │   └── services/
-│       ├── config.ts        # 配置服务（被依赖，不自启动）
-│       └── cache.ts         # 缓存服务（被依赖，不自启动）
-├── package.json             # 可含 hile.auto_load_packages
+│       ├── config.ts
+│       └── cache.ts
+├── package.json
 └── tsconfig.json
 ```
 
-服务加载来源：先按 `package.json` 的 `hile.auto_load_packages`（若有）加载模块默认导出，再扫描运行时目录下的 `*.boot.{ts,js}`；其余服务通过 `loadService` 按需加载。
+服务加载来源：先加载 `hile.auto_load_packages`（如有），再加载运行时目录下的 `*.boot.{ts,js}`。其余服务通过 `loadService` 按需加载。
 
 ## 开发
 
 ```bash
 pnpm install
-pnpm build        # 编译
-pnpm dev          # 监听模式
+pnpm build
+pnpm dev
 ```
 
 ## License

package/dist/index.js

@@ -11,6 +11,37 @@ const require = createRequire(import.meta.url);
 function loadEnvFile(filePath) {
     process.loadEnvFile(resolve(process.cwd(), filePath));
 }
+function logContainerEvent(event) {
+    switch (event.type) {
+        case 'service:init':
+            console.info(`[hile] service#${event.id} init`);
+            break;
+        case 'service:ready':
+            console.info(`[hile] service#${event.id} ready (${event.durationMs}ms)`);
+            break;
+        case 'service:error':
+            console.error(`[hile] service#${event.id} failed (${event.durationMs}ms):`, event.error);
+            break;
+        case 'service:shutdown:start':
+            console.info(`[hile] service#${event.id} stopping`);
+            break;
+        case 'service:shutdown:done':
+            console.info(`[hile] service#${event.id} stopped (${event.durationMs}ms)`);
+            break;
+        case 'service:shutdown:error':
+            console.error(`[hile] service#${event.id} shutdown error:`, event.error);
+            break;
+        case 'container:shutdown:start':
+            console.info('[hile] container shutdown start');
+            break;
+        case 'container:shutdown:done':
+            console.info(`[hile] container shutdown done (${event.durationMs}ms)`);
+            break;
+        case 'container:error':
+            console.error('[hile] container error:', event.error);
+            break;
+    }
+}
 program.version(pkg.version, '-v, --version', '当前版本号');
 /**
  * 启动服务
@@ -28,6 +59,7 @@ program
     .option('-e, --env-file <path>', '加载指定 env 文件（兼容 Node --env-file 语义；可多次指定，先加载的不被后加载覆盖）', (v, acc) => (acc.push(v), acc), [])
     .description('启动服务，加载所有后缀为 boot.ts 或 boot.js 的服务，并注册退出钩子，在进程退出时销毁所有服务')
     .action(async (options) => {
+    const offEvent = container.onEvent(logContainerEvent);
     // 先加载 --env-file（与 Node --env-file 行为一致：先加载的优先，已存在的 key 不被覆盖）
     const envFiles = options.envFile ?? [];
     for (const p of envFiles) {
@@ -68,13 +100,17 @@ program
     // 如果没有服务要加载，则提示
     if (!files.length) {
         console.warn('no services to load');
+        offEvent();
         return;
     }
     // 注册退出钩子，在进程退出时销毁所有服务
     exitHook(exit => {
         container.shutdown()
             .catch(e => console.error(e))
-            .finally(exit);
+            .finally(() => {
+            offEvent();
+            exit();
+        });
     });
 });
 program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/cli",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -23,11 +23,11 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/core": "^1.0.16",
+    "@hile/core": "^1.0.18",
     "async-exit-hook": "^2.0.1",
     "commander": "^14.0.3",
     "glob": "^13.0.6",
     "tsx": "^4.21.0"
   },
-  "gitHead": "7e174bc0b7bac23bef7aebb0883e4ce86ec7795a"
+  "gitHead": "81347b9de460b693ed82af46c0f4a287d4527323"
 }