# CLI Template V1

一个面向长期演进的 TypeScript CLI 模板。它不是只服务 AI 编程场景，而是可以作为多种 CLI 产品的基础骨架：

- 桌面软件控制 CLI
- 配置初始化与环境诊断 CLI
- 工作流与自动化任务 CLI
- 再进一步扩展成 Agent / AI 助手型 CLI

## 当前能力

- TypeScript + Node 20
- `RuntimeServices` 统一注入运行时能力
- `command / use-case / presenter` 分层
- 模块注册表、任务注册表、运行时插件加载
- `text / json` 双输出模式
- 配置文件持久化服务
- 统一错误模型与 CLI 错误边界
- `node:test` 测试基座
- 可作为 npm CLI 包发布

## 项目结构

```text
.
├─ plugins/                 # 运行时插件目录，启动时会扫描这里的 *.js
├─ src/
│  ├─ bootstrap/            # CLI 应用装配
│  ├─ runtime/              # services/errors/output/config/plugin/task-registry
│  ├─ modules/              # 业务模块，按 command/use-case/presenter 划分
│  ├─ test/                 # 测试聚合入口
│  ├─ plugins/              # 插件示例源码
│  └─ ui/renderers/         # 纯渲染层
└─ dist/                    # 编译产物
```

## 快速开始

```bash
pnpm install
pnpm dev -- --help
pnpm dev -- demo
pnpm dev -- config init
pnpm dev -- --output json config show
pnpm dev -- --output json task list
pnpm dev -- --output json task run doctor
pnpm test
```

## 全局安装后的命令名

包名和命令名现在统一为：

```bash
npm install -g cli-template-v1
cli-template-v1 --help
cli-template-v1 task list
cli-template-v1 --output json config show
```

这样用户安装的包名和实际执行命令一致，不会出现安装了 `cli-template-v1`，却要执行 `cli-starter` 的割裂体验。

## CLI 示例

文本输出：

```bash
pnpm dev -- task list
```

JSON 输出：

```bash
pnpm dev -- --output json task run doctor
```

读取配置：

```bash
pnpm dev -- --output json config show
```

## 插件机制

运行时会扫描当前工作目录下的 `plugins/*.js` 文件，并尝试加载插件。

插件需要导出一个 `CliPlugin` 对象，可提供：

- `modules`: 新命令模块
- `tasks`: 新任务定义

项目里有两个相关位置：

- [plugins/example-plugin.js](/D:/VScodeProject/cli-codex/plugins/example-plugin.js)
  这是当前真正会被运行时扫描到的示例插件。
- [src/plugins/example-plugin.js](/D:/VScodeProject/cli-codex/src/plugins/example-plugin.js)
  这是源码层面的示例参考。

加载成功后，插件任务会自动出现在 `task list` 里。

## 开发约定

### 1. 新增命令模块

在 `src/modules/<name>/` 下新增模块，至少拆成：

- `command.ts`: 只负责 CLI 参数解析和流程编排
- `use-case.ts`: 只负责业务逻辑
- `presenter.ts`: 只负责输出格式

然后在 [registry.ts](/D:/VScodeProject/cli-codex/src/modules/registry.ts) 注册。

### 2. 新增任务

在 `src/modules/task/tasks/` 下新增一个 `PluginTask`，然后在 [registry.ts](/D:/VScodeProject/cli-codex/src/modules/task/tasks/registry.ts) 注册。

### 3. 使用配置存储

通过 `services.configStore.read/write/patch` 读写 `cli-template-v1.config.json`，不要在业务模块里直接操作文件系统。

### 4. 使用输出模式

通过 `services.output.mode` 判断当前模式，通过 `services.output.writeText/writeData` 输出，避免在 presenter 或 use-case 外随意 `console.log`。

### 5. 使用统一错误

抛出 `AppError`，携带：

- `code`
- `exitCode`
- `details`

CLI 会自动按 text/json 两种模式输出错误结果。

## 测试

当前测试基座基于 Node 内置测试框架，入口在：

- [all.test.ts](/D:/VScodeProject/cli-codex/src/test/all.test.ts)

已有示例测试：

- [use-case.test.ts](/D:/VScodeProject/cli-codex/src/modules/config/use-case.test.ts)
- [task-registry.test.ts](/D:/VScodeProject/cli-codex/src/runtime/task-registry.test.ts)

执行：

```bash
pnpm test
```

## 发布 npm 包

发布前建议先检查打包内容：

```bash
pnpm pack:check
```

正式发布：

```bash
npm publish
```

当前发布配置已限制只发布：

- `dist/`
- `README.md`
- `LICENSE`

注意：`repository`、`homepage`、`bugs` 目前是占位地址，发布前应替换成你的真实仓库链接。

## 适合继续演进的方向

- 配置 schema 校验与迁移
- 插件签名与权限模型
- 错误码和 exit code 文档化
- fixture runner 与端到端命令测试
- 发布流程和单文件打包