Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# AGENTS.md — @ultime/cli

> 给在本仓库工作的 AI 与协作者:入口、可写 / 只读、红线与验收。
> 适用版本:0.2.x
> 适用版本:0.3.x

## 先读

Expand All @@ -27,7 +27,9 @@
- **不发 bin、不做命令发现**:每个产品包自带入口;本包不聚合、不扫描其他包的 bin。
- **不做 IO 策略**:读盘写盘与配置路径由命令自己决定。
- **不引第三方解析库**:`parseArgs` 保持零依赖。
- **API 变化同步**:`runCli` / `ParsedArgs` / `CliContext` 变化时同步 README、`SKILLS.md` 与测试。
- **runCli 异步**:命令返回 `number | Promise<number>`;入口必须 `await` 后再赋给 `process.exitCode`。
- **开发方式**:测试先行;阶段完成先 review 代码与文档;文档简洁、机制优先。
- **API 变化同步**:`runCli` / `ParsedArgs` / `FlagSpec` / `CliContext` 变化时同步 README、`SKILLS.md` 与测试。

## 验证

Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 0.3.0 - 2026-11-15

### Added

- `parseArgs(argv, { flags })` 与 `FlagSpec`:命令级声明 `boolean` / `string`,布尔 flag 不再吞后面的 token;`--` 之后全部按 positional 处理。
- `CommandSpec.flags`:声明后 `runCli` 拒绝未知参数、布尔显式值与带值 flag 缺值,统一报 `USAGE`。
- `runCli` 支持异步命令与 `mapError`;`help` 支持函数,用于二级命令帮助。
- 导出 `flagValue` / `flagBool` / `reportError` / `exitCodeOf` 与 `EXIT_OK` / `EXIT_FAIL` / `EXIT_USAGE`。

### Changed

- **Breaking**:`runCli` 返回 `Promise<number>`;入口改为 `process.exitCode = await runCli(...)`。
- 传入 `flags` schema 时,未声明的 flag 按布尔解析,交给命令校验拒绝;未传 schema 保持旧的自由解析。
- 空字符串 `--key ""` 保留为值,不再退化成 `true`。

### Fixed

- `--` 不再被当成空名 flag;`--key ''` 与 `--key=` 行为一致。

## 0.2.0 - 2026-11-12

### Added
Expand Down
50 changes: 37 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,33 +16,54 @@ pnpm add @ultime/cli
包作者只写自己的命令,参数、help、未知命令与退出码交给本包:

```ts
import { runCli, processContext } from '@ultime/cli'
import { flagBool, flagValue, processContext, runCli } from '@ultime/cli'

const spec = {
name: 'my-cli',
version: '0.1.0',
usage: 'my-cli <command>',
commands: {
build: {
help: 'my-cli build [--check]',
help: 'my-cli build [--check] [--config <path>]',
flags: { check: 'boolean', config: 'string' },
run: (args, ctx) => {
ctx.out(`check=${Boolean(args.flags.check)}`)
ctx.out(`check=${flagBool(args, 'check')} config=${flagValue(args, 'config') ?? '-'}`)
return 0
},
},
},
}

process.exitCode = runCli(spec, process.argv.slice(2), processContext())
process.exitCode = await runCli(spec, process.argv.slice(2), processContext())
```

命令可以返回 `number`,也可以返回 `Promise<number>`;`runCli` 会等待结果。

## 出口

| 入口 | 提供 |
|---|---|
| `@ultime/cli` | `parseArgs` / `runCli` / `processContext` / `CliError` / `toErrorShape` / `CliContext` / `CliSpec` / `CommandSpec` |
| `@ultime/cli` | `parseArgs` / `flagBool` / `flagValue` / `runCli` / `reportError` / `processContext` / `CliError` / `toErrorShape` / `exitCodeOf` / `EXIT_OK` / `EXIT_FAIL` / `EXIT_USAGE` / `CliContext` / `CliSpec` / `CommandSpec` / `FlagType` / `FlagSpec` / `ParseOptions` / `ParsedArgs` / `CliErrorOptions` / `CliErrorShape` |

`parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`;`-h/--help`、`-v/--version` 与 `--json` 是保留 flag。`--` 之后全部按 positional 处理,`--key ""` 保留空字符串。

## 声明参数

给命令加 `flags` 后,参数语义由声明决定,未知参数会在执行前被拒绝:

```ts
commands: {
deploy: {
flags: { 'dry-run': 'boolean', config: 'string' },
run: (args, ctx) => 0,
},
}
```

`parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`;`-h/--help`、`-v/--version` 与 `--json` 是保留 flag。
- `boolean`:永不消费下一个 token,只接受 `--dry-run`;
- `string`:消费下一个 token,支持 `--config path` / `--config=path` / `--config ''`;
- 未声明:传了 schema 时按布尔解析,再由 `runCli` 以 `USAGE` 拒绝;不传 schema 时保持旧的自由解析;
- 同一 flag 在所有命令中的类型必须一致;命令要么全部声明 `flags`,要么全部省略。

## 错误与退出码

Expand All @@ -64,7 +85,9 @@ throw new CliError('缺少 --config', {
| 命令返回的码 | 原样透传 |
| 命令抛普通异常 | 1,`code: 'ERROR'` |
| `CliError` | `exitCode`,默认 2(用法或配置错误) |
| 无命令、未知命令 | 2 |
| 未知命令、未知参数、布尔参数带值、带值参数缺值 | 2 |

`runCli` 是异步的:版本 / 帮助 / 无命令等分支也会返回 `Promise<number>`。

- 未知命令给最近候选;没有候选时列出可用命令。
- `--json` 时错误只写 stderr:
Expand All @@ -80,26 +103,27 @@ AI 入口:[`llms.txt`](./llms.txt)(路由)与 [`SKILLS.md`](./SKILLS.md)
## 边界

- **零领域依赖**:不 import 任何领域包,也不认识具体业务对象。
- **不引第三方解析 / 着色库**:解析用零依赖实现,着色直接用 ANSI。Node 内置 `util.parseArgs` 表达不了自由 `--key value`,暂不切换。
- **不引第三方解析 / 着色库**:解析用零依赖实现,着色直接用 ANSI。Node 内置 `util.parseArgs` 表达不了自由 `--key value` 与命令级 flag schema,暂不切换。
- **不内置命令、不发 bin**:具体命令由调用方包注册,各自发布自己的 bin;本包不做命令发现与聚合。
- **不做 IO 策略**:读盘写盘、配置路径由命令自己决定;本包只提供 `cwd` 与 `out/err`。

## 目录

```text
src/
args.ts 参数解析(纯函数)
args.ts 参数解析(纯函数)、flag schema 与读取
context.ts 命令上下文(cwd / out / err)
error.ts 机器可读错误与统一转换
run.ts 命令注册、help、未知命令与退出码
error.ts 机器可读错误、退出码与统一转换
run.ts 命令注册、flags 校验、help、未知命令与退出码
index.ts 公共出口
tests/ 参数、运行时分发与包内容边界
tests/ 参数、运行时、声明校验与包内容边界
```

## 版本与兼容

- 当前 `0.2.x`;0.x 阶段 API 仍可能调整。
- 当前 `0.3.x`;0.x 阶段 API 仍可能调整。
- 退出码语义:0 成功 / 1 命令执行失败 / 2 用法或配置错误;这是 0.2 起的新约定,升级时按本节目迁移。
- 0.3 的破坏性变更:`runCli` 改为异步;声明 `flags` 后未知参数与缺值会被拒绝。迁移方式:入口改成 `process.exitCode = await runCli(...)`,并给命令补 `flags`;不补 `flags` 的命令仍按旧规则解析。
- 破坏性变更写进 [CHANGELOG](./CHANGELOG.md),并在本节目说明迁移方式。
- 发布顺序:本包是基础设施,先于依赖它的包。

Expand Down
39 changes: 32 additions & 7 deletions SKILLS.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,36 @@
# @ultime/cli · 可调用能力

> 定位:AI 可调用的通用命令设施。领域命令不在这里。
> 适用版本:0.2.x
> 同步基线:0.2.x(手写;API 变化时同批更新)
> 适用版本:0.3.x
> 同步基线:0.3.x(手写;API 变化时同批更新)

---

## 入口

```ts
import { parseArgs, runCli, processContext, CliError } from '@ultime/cli'
import type { ParsedArgs, CliContext, CliSpec, CommandSpec, CliErrorOptions, CliErrorShape } from '@ultime/cli'
import { flagBool, flagValue, parseArgs, processContext, reportError, runCli, CliError } from '@ultime/cli'
import type {
CliContext,
CliSpec,
CommandSpec,
FlagSpec,
FlagType,
ParseOptions,
ParsedArgs,
CliErrorOptions,
CliErrorShape,
} from '@ultime/cli'
```

| 能力 | 输入 | 输出 |
|---|---|---|
| `parseArgs(argv)` | 字符串数组 | `{ command, flags, positional }` |
| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | 退出码;版本 / 帮助 / 未知命令 / 错误由它处理 |
| `parseArgs(argv, options?)` | 字符串数组 + 可选 `flags` schema | `{ command, flags, positional }` |
| `flagBool(args, name)` | 解析结果 + flag 名 | 是否显式为 `true` |
| `flagValue(args, name)` | 解析结果 + flag 名 | 字符串或 `undefined`;缺值抛 `CliError` |
| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | `Promise<退出码>`;版本 / 帮助 / 未知命令 / 校验 / 错误由它处理 |
| `reportError(ctx, error, json)` | 上下文 + 任意异常 + 是否 JSON | 统一错误输出 |
| `exitCodeOf(error)` | 任意异常 | `CliError.exitCode` 或 1 |
| `processContext()` | — | `{ cwd, out, err }` |
| `CliError(message, options)` | 文案 + `code` / `path` / `hint` / `details` / `exitCode` | 可被 `runCli` 统一输出的错误 |
| `toErrorShape(error)` | 任意异常 | `{ code, message, path?, hint?, details? }` |
Expand All @@ -28,19 +42,30 @@ import type { ParsedArgs, CliContext, CliSpec, CommandSpec, CliErrorOptions, Cli
name: string
version: string
usage: string
commands: Record<string, { help?: string; run(args, ctx): number }>
commands: Record<string, {
help?: string | ((args: ParsedArgs) => string)
flags?: Record<string, 'boolean' | 'string'>
run(args, ctx): number | Promise<number>
}>
mapError?: (error: unknown) => CliError | undefined
}
```

## 错误语义

- 未知命令:`err` 写错误与候选,`out` 写 usage,返回 2;
- 无命令:`out` 写 usage,返回 2;
- 未知参数 / 布尔参数带值 / 带值参数缺值:`CliError`(`USAGE`),返回 2;
- 普通异常:`err` 写 message,`code: 'ERROR'`,返回 1;
- `CliError`:带 `code` / `path` / `hint`,返回 `exitCode`(默认 2);
- `--json`:错误以 `{ "error": { … } }` 只写 stderr;
- 版本 / 帮助:返回 0,不执行命令。

## 边界

- 参数解析与命令级校验是通用设施;业务 flag 由调用方声明。
- 声明 `flags` 后未知参数会被拒绝;未声明时保持旧的自由解析。

## 反例

- 把 `--check` 当成 cli 内置 flag:它属于调用方的命令。
Expand Down
4 changes: 2 additions & 2 deletions llms.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# @ultime/cli · AI 索引

适用版本:0.2.x
适用版本:0.3.x

## 去哪找

Expand All @@ -9,7 +9,7 @@

## 机器入口

- 公共出口:`@ultime/cli` 的 `parseArgs` / `runCli` / `processContext` / `CliError` / `toErrorShape` 与类型。
- 公共出口:`@ultime/cli` 的 `parseArgs` / `flagBool` / `flagValue` / `runCli` / `reportError` / `processContext` / `CliError` / `toErrorShape` / `exitCodeOf` 与类型。

## 边界

Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@ultime/cli",
"version": "0.2.0",
"version": "0.3.0",
"description": "Ultime · cli:通用命令行设施(参数 / 命令注册 / 上下文 / 退出码),零领域依赖",
"keywords": [
"argument-parser",
Expand Down Expand Up @@ -58,7 +58,7 @@
"size-limit": "^14.3.0",
"typescript": "^5.9.3",
"unplugin-unused": "^0.6.0",
"vite-plus": "1.5.1"
"vite-plus": "1.6.0"
},
"size-limit": [
{
Expand Down
Loading
Loading