@hile/cli 2.1.1 → 3.0.1

package/AI.md

@@ -0,0 +1,334 @@
+# AI Guide For @hile/cli
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Run hile start, scan boot files, load auto-loaded services, and start registries from the command line.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Start an app, manage lifecycle, graceful shutdown | `@hile/core`, `@hile/cli`, `@hile/bootstrap` | `packages/core-lifecycle.md` |
+
+
+
+# Core Lifecycle, Bootstrap, CLI, Logger, Redis, TypeORM
+
+Packages: `@hile/core`, `@hile/bootstrap`, `@hile/cli`, `@hile/logger`, `@hile/ioredis`, `@hile/typeorm`.
+
+## Use When
+
+Use these packages when an app needs managed startup, singleton resources, dependency ordering, environment-file loading, graceful shutdown, logs, Redis, or SQL database connections.
+
+## Do Not Use When
+
+- Do not use `loadService()` at module top level.
+- Do not use `auto_load_packages` for file paths. It accepts package names only.
+- Do not use the default `@hile/ioredis` or `@hile/typeorm` services when one app needs multiple Redis or database connections; define separate services with separate keys.
+
+## Install
+
+```bash
+pnpm add @hile/core @hile/logger @hile/ioredis @hile/typeorm
+pnpm add -D @hile/cli
+```
+
+## Imports
+
+```ts
+import { defineService, loadService, container } from '@hile/core'
+import { createLogger } from '@hile/logger'
+import redisService, { createRedis } from '@hile/ioredis'
+import typeormService, { createDataSource, transaction } from '@hile/typeorm'
+```
+
+## Copy-Paste Example
+
+```ts
+// src/services/http.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
+
+export default defineService('http', async (shutdown) => {
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
+})
+```
+
+Run:
+
+```bash
+hile start --dev --env-file .env
+```
+
+## More Examples
+
+Use `package.json` auto-load for integration services that default-export a Hile service:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "hile start --dev --env-file .env",
+    "start": "hile start --env-file .env.prod"
+  },
+  "hile": {
+    "auto_load_packages": ["@hile/logger", "@hile/ioredis", "@hile/typeorm"]
+  }
+}
+```
+
+Inside another service, load dependencies:
+
+```ts
+import { defineService, loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import typeormService from '@hile/typeorm'
+
+export default defineService('user.service', async () => {
+  const [redis, ds] = await Promise.all([
+    loadService(redisService),
+    loadService(typeormService),
+  ])
+  return { redis, ds }
+})
+```
+
+## Compose With
+
+- Use `@hile/http` boot services to start APIs.
+- Use `@hile/model` services arrays to load TypeORM or Redis for business logic.
+- Use `@hile/cache`, `@hile/redis-lock`, queues, rate limits, and idempotency with a Redis client from `@hile/ioredis`.
+
+## Runtime And Lifecycle Notes
+
+- `defineService(key, fn)` registers a service factory and does not execute it.
+- `loadService(service)` executes the factory on first call and returns the cached value afterwards.
+- The `shutdown` callback registers teardown functions; they run in LIFO order.
+- The container tracks dependencies when service factories call `loadService()`.
+- `container.shutdown()` triggers registered teardowns.
+- `@hile/bootstrap` loads env files first, sets `NODE_ENV`, imports auto-load packages, scans boot files, and installs exit hooks.
+- `@hile/logger.createLogger()` returns `{ logger, teardown }`.
+- `@hile/ioredis.createRedis()` waits for `connect`.
+- `@hile/typeorm.createDataSource()` initializes a TypeORM `DataSource`.
+
+## Anti-Patterns
+
+- Reusing one service key for unrelated factories.
+- Missing `shutdown()` callbacks for network connections or servers.
+- Assuming TypeORM env config fills entities automatically when `TYPEORM_ENTITIES` is not set.
+- Calling `transaction()` and manually committing; the helper commits or rolls back internally.
+
+## Verification Checklist
+
+- Boot files default-export `defineService(...)`.
+- Long-lived resources register teardown callbacks.
+- `auto_load_packages` contains package names, not local files.
+- `hile start --dev` can find `src/**/*.boot.ts`.
+- Production build emits `dist/**/*.boot.js`.
+
+# create-hile
+
+Package: `create-hile`.
+
+## Copy-Paste Example
+
+Create a project:
+
+```bash
+npx create-hile create my-app
+cd my-app
+pnpm install
+pnpm run dev
+```
+
+Skip dependency install:
+
+```bash
+npx create-hile create my-app --skip-install
+```
+
+## More Examples
+
+Template choices:
+
+```text
+default          HTTP API with @hile/http
+next             Next.js + Hile controllers on one port
+micro-http       Microservice plus HTTP endpoint
+micro            Pure microservice
+micro-http-next  Next.js + microservice + HTTP
+monorepo         Lerna + pnpm workspace
+```
+
+Generated default HTTP shape:
+
+```text
+src/
+  controllers/
+    index.controller.ts
+  services/
+    index.boot.ts
+```
+
+## Use When
+
+Use `create-hile` when starting a new Hile application or workspace.
+
+## Do Not Use When
+
+- Do not use generated templates as the final architecture for complex apps without introducing models, services, and context boundaries.
+- Do not trust stale template README files if they mention unrelated application domains; regenerate or rewrite them from current template files.
+
+## Install
+
+Usually no install is needed:
+
+```bash
+npx create-hile create my-app
+```
+
+## Imports
+
+The CLI entrypoint exports a `create` command. Application code does not import `create-hile`.
+
+## Compose With
+
+- Generated apps use `@hile/cli` for `hile start`.
+- HTTP templates use `@hile/core` and `@hile/http`.
+- Next templates use `@hile/http-next` and `@hile/model`.
+- Micro templates use `@hile/micro` and `@hile/message-loader`.
+
+## Runtime And Lifecycle Notes
+
+- Templates use `_env`, `_env.prod`, and `_gitignore`; creation renames them to dotfiles.
+- The CLI prompts for a template and optional dependency installation.
+- The package manager preference is `pnpm`, then `yarn`, then `npm`.
+
+## Anti-Patterns
+
+- Leaving template package versions stale after publishing new Hile packages.
+- Shipping template READMEs copied from unrelated projects.
+- Starting production without running the build command required by the selected template.
+
+## Verification Checklist
+
+- New project has `"type": "module"`.
+- Dev script runs `hile start --dev`.
+- Production script runs `hile start` after build.
+- Boot files default-export `defineService(...)`.
+
+
+
+# Related Recipes
+
+
+
+# New Project Scaffold
+
+## Complete Example
+
+```bash
+npx create-hile create orders-api
+cd orders-api
+pnpm install
+pnpm run dev
+```
+
+Default HTTP controller:
+
+```ts
+// src/controllers/index.controller.ts
+import { defineController } from '@hile/http'
+
+export default defineController('GET', async () => {
+  return { ok: true }
+})
+```
+
+Default HTTP boot:
+
+```ts
+// src/services/index.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
+
+export default defineService('http', async (shutdown) => {
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
+})
+```
+
+## File Layout
+
+```text
+orders-api/
+  src/controllers/index.controller.ts
+  src/services/index.boot.ts
+  package.json
+  .env
+```
+
+## User Intent
+
+Use this recipe when the user wants a new Hile app or template guidance.
+
+## Packages To Use
+
+- `create-hile`
+- Template-selected Hile packages
+
+## Implementation Steps
+
+1. Choose a template by app shape.
+2. Make sure scripts use `hile start --dev` for development.
+3. Keep boot files under `src/**`.
+4. Add models when domain logic grows beyond a sample controller.
+
+## Failure And Cleanup Behavior
+
+- Generated apps rely on `@hile/cli` to find boot files and call container shutdown.
+- Production needs build output under `dist`.
+
+## Verification Checklist
+
+- `package.json` has `"type": "module"`.
+- `pnpm run dev` starts `hile start --dev`.
+- Boot file registers server close function.
+- Template README matches the selected template, not an unrelated app.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,159 +1,64 @@
 # @hile/cli
 
-Hile 命令行工具，用于启动基于 `@hile/core` 的服务应用。支持通过 `package.json` 配置和/或自动扫描 `*.boot.{ts,js}` 加载服务，并在进程退出时执行优雅关闭。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Run hile start, scan boot files, load auto-loaded services, and start registries from the command line.
 
-```bash
-pnpm add @hile/cli
-```
-
-全局使用：
-
-```bash
-pnpm add -g @hile/cli
-```
-
-## 命令
-
-### `hile start`
-
-在当前工作目录（通常为项目根，且包含 `package.json`）启动服务。加载顺序如下：
-
-1. `package.json` 中的 `hile.auto_load_packages`（如存在）
-2. 运行时目录下的 `*.boot.ts` / `*.boot.js`
-
-若两者都未提供可加载服务，CLI 输出 `no services to load` 并退出。每个加载项的默认导出都必须通过 `isService` 校验，否则抛出 `invalid service file`。
-
-```bash
-hile start
-hile start --dev
-```
-
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `-d, --dev` | 开发模式：`NODE_ENV=development`，使用 tsx，扫描 `src/` | `false` |
-| `-e, --env-file <path>` | 加载 env 文件到 `process.env`，可多次指定 | — |
-
-- 非 `--dev` 模式：`NODE_ENV=production`
-- `--dev` 模式：`NODE_ENV=development`
-
-示例：
-
-```bash
-hile start --env-file .env --env-file .env.local
-```
-
-依赖 Node 20.12+ 原生 `process.loadEnvFile()`。
-
-### 启动日志（基于 @hile/core 事件）
-
-CLI 已接入容器事件日志（仅开发模式输出）：
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-- 服务启动：`service:init` / `service:ready`（含耗时）
-- 服务失败：`service:error`（错误对象单独一行）
-- 关闭阶段：`service:shutdown:start` / `service:shutdown:done`
-- 容器关闭：`container:shutdown:start` / `container:shutdown:done`
+## When To Use
 
-在 TTY 环境下会使用颜色（成功绿、错误红、警告黄等）；重定向或管道时自动禁用颜色，便于日志采集。
+Use these packages when an app needs managed startup, singleton resources, dependency ordering, environment-file loading, graceful shutdown, logs, Redis, or SQL database connections.
 
-### 其他命令
+## Install
 
 ```bash
-hile -v
-hile -h
-```
-
-## 运行时目录
-
-扫描目录优先级：
-
-1. `HILE_RUNTIME_DIR`（若设置）
-2. `--dev` 模式：`src/`
-3. 生产模式：`dist/`
-
-```bash
-HILE_RUNTIME_DIR=./custom hile start
-```
-
-## package.json 配置（可选）
-
-可在项目根目录配置 `hile.auto_load_packages`，用于在扫描 boot 文件之前先加载指定模块：
-
-```json
-{
-  "name": "my-app",
-  "hile": {
-    "auto_load_packages": ["@hile/http", "my-local-service"]
-  }
-}
+pnpm add @hile/cli
 ```
 
-规则：
-
-- 数组项必须是模块名（与 `import('module')` 语义一致）
-- 按数组顺序加载，然后再扫描 `*.boot.{ts,js}`
-- 每个模块默认导出必须是合法 Hile 服务（通过 `isService`）
+## Copy-Paste Example
 
-## Boot 文件规范
-
-**约定**：**`src/services/`** 下 **`*.boot.*`** 与 **`*.service.*`** **同属 service 模块**（均 **`defineService`**）：**`.boot`** = CLI **自启动**，**`.service`** = **`loadService`** **依赖加载**。二者**必须**位于 **`src/services/`**。
-
-每个 `*.boot.ts` / `*.boot.js` 文件必须默认导出一个服务：
-
-```typescript
-// src/services/database.boot.ts（*.boot 须放在 src/services/）
-import { defineService, loadService } from '@hile/core'
-import { configService } from './config.service'
+```ts
+// src/services/http.boot.ts
+import { defineService } from '@hile/core'
+import { Http } from '@hile/http'
 
 export default defineService('http', async (shutdown) => {
-  const config = await loadService(configService)
-  const pool = await createPool(config.dbUrl)
-  shutdown(() => pool.end())
-  return pool
+  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
+  await http.load(new URL('../controllers', import.meta.url).pathname)
+  const close = await http.listen()
+  shutdown(close)
+  return http
 })
 ```
 
-要求：
-
-- 文件名后缀必须为 `.boot.ts` 或 `.boot.js`
-- 必须存在 `default` 导出
-- 导出值必须为 `defineService` / `container.register` 返回值
-
-## 优雅关闭
-
-进程收到 `SIGTERM`、`SIGINT` 等信号时，CLI 通过 `registerExitHook` 注册的退出钩子会：
+Run:
 
-1. 先 **await** `container.shutdown()`（确保所有在 defineService 中注册的 shutdown 回调被执行）
-2. **仅在其完成后**再取消事件订阅并调用 exit 退出进程
-
-若 `shutdown()` 未完成，进程会挂起不退出；内部将 async-exit-hook 的强制退出超时设为极大值，等效于「等 shutdown 完成再退出」。
+```bash
+hile start --dev --env-file .env
+```
 
-## 项目结构示例
+## Boundaries
 
-```text
-my-app/
-├── src/
-│   └── services/
-│       ├── http.boot.ts
-│       ├── database.boot.ts
-│       ├── config.service.ts
-│       └── cache.service.ts
-├── package.json
-└── tsconfig.json
-```
+- Do not use `loadService()` at module top level.
+- Do not use `auto_load_packages` for file paths. It accepts package names only.
+- Do not use the default `@hile/ioredis` or `@hile/typeorm` services when one app needs multiple Redis or database connections; define separate services with separate keys.
 
-服务加载来源：先加载 `hile.auto_load_packages`（如有），再加载运行时目录下的 `*.boot.{ts,js}`。其余服务通过 `loadService` 按需加载。
+- Reusing one service key for unrelated factories.
+- Missing `shutdown()` callbacks for network connections or servers.
+- Assuming TypeORM env config fills entities automatically when `TYPEORM_ENTITIES` is not set.
+- Calling `transaction()` and manually committing; the helper commits or rolls back internally.
 
-## 开发
+## Verify
 
-```bash
-pnpm install
-pnpm build
-pnpm dev
-pnpm test
-```
+- Boot files default-export `defineService(...)`.
+- Long-lived resources register teardown callbacks.
+- `auto_load_packages` contains package names, not local files.
+- `hile start --dev` can find `src/**/*.boot.ts`.
+- Production build emits `dist/**/*.boot.js`.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/cli",
-  "version": "2.1.1",
+  "version": "3.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI.md"
   ],
   "bin": {
     "hile": "./dist/index.js"
@@ -27,12 +28,12 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/bootstrap": "^2.1.1",
-    "@hile/logger": "^2.1.1",
-    "@hile/micro": "^2.1.1",
+    "@hile/bootstrap": "^3.0.0",
+    "@hile/logger": "^3.0.0",
+    "@hile/micro": "^3.0.1",
     "commander": "^14.0.3",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.9.0"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }