@ultime/cli 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 - 2026-11-12
+
+### Added
+
+- `CliError` / `toErrorShape`：机器可读错误，带 `code` / `path` / `hint` / `details` / `exitCode`。
+- `--json` 作为保留布尔 flag：错误以 `{ "error": { … } }` 只写 stderr。
+- 未知命令给最近候选；单命令 help 缺省时按命令名生成。
+
+### Changed
+
+- 退出码语义：0 成功 / 1 命令执行失败 / 2 用法或配置错误；无命令与未知命令从 1 改为 2。
+- 本包不发布 bin、不做命令发现；各产品包自带入口。
+
 ## 0.1.4 - 2026-11-10
 
 - 构建改用 `vp pack`，产物同时生成 `dist/index.js` 与 `dist/index.d.ts`。

package/README.md

@@ -40,17 +40,48 @@ process.exitCode = runCli(spec, process.argv.slice(2), processContext())
 
 | 入口 | 提供 |
 |---|---|
-| `@ultime/cli` | `parseArgs` / `runCli` / `processContext` / `CliContext` / `CommandSpec` / `CliSpec` |
+| `@ultime/cli` | `parseArgs` / `runCli` / `processContext` / `CliError` / `toErrorShape` / `CliContext` / `CliSpec` / `CommandSpec` |
 
-`parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`；`-h/--help` 与 `-v/--version` 是保留 flag。
+`parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`；`-h/--help`、`-v/--version` 与 `--json` 是保留 flag。
+
+## 错误与退出码
+
+命令用 `CliError` 抛机器可读错误；普通异常退化成 `code: 'ERROR'`：
+
+```ts
+import { CliError } from '@ultime/cli'
+
+throw new CliError('缺少 --config', {
+  code: 'USAGE',
+  path: '--config',
+  hint: '补上 --config <path>',
+})
+```
+
+| 情况 | 退出码 |
+|---|---|
+| 版本 / 帮助 | 0 |
+| 命令返回的码 | 原样透传 |
+| 命令抛普通异常 | 1，`code: 'ERROR'` |
+| `CliError` | `exitCode`，默认 2（用法或配置错误） |
+| 无命令、未知命令 | 2 |
+
+- 未知命令给最近候选；没有候选时列出可用命令。
+- `--json` 时错误只写 stderr：
+
+```json
+{ "error": { "code": "USAGE", "message": "缺少 --config", "path": "--config", "hint": "补上 --config <path>" } }
+```
+
+- 人类文案与 JSON 同源，由 `toErrorShape` 统一转换。
 
 AI 入口：[`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)（能力表）随包发布。
 
 ## 边界
 
 - **零领域依赖**：不 import 任何领域包，也不认识具体业务对象。
-- **不引第三方解析 / 着色库**：解析用零依赖实现，着色直接用 ANSI；Node 内置的 `util.parseArgs` / `util.styleText` 是后续替换首选，等出现嵌套子命令或补全需求再评估 `commander` 一类工具。
-- **不内置命令**：具体命令由调用方包注册，各自发布自己的 bin。
+- **不引第三方解析 / 着色库**：解析用零依赖实现，着色直接用 ANSI。Node 内置 `util.parseArgs` 表达不了自由 `--key value`，暂不切换。
+- **不内置命令、不发 bin**：具体命令由调用方包注册，各自发布自己的 bin；本包不做命令发现与聚合。
 - **不做 IO 策略**：读盘写盘、配置路径由命令自己决定；本包只提供 `cwd` 与 `out/err`。
 
 ## 目录
@@ -59,14 +90,16 @@ AI 入口：[`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)
 src/
   args.ts      参数解析（纯函数）
   context.ts   命令上下文（cwd / out / err）
+  error.ts     机器可读错误与统一转换
   run.ts       命令注册、help、未知命令与退出码
   index.ts     公共出口
-tests/         参数与运行时分发
+tests/         参数、运行时分发与包内容边界
 ```
 
 ## 版本与兼容
 
-- 当前 `0.1.x`；0.x 阶段 API 仍可能调整。
+- 当前 `0.2.x`；0.x 阶段 API 仍可能调整。
+- 退出码语义：0 成功 / 1 命令执行失败 / 2 用法或配置错误；这是 0.2 起的新约定，升级时按本节目迁移。
 - 破坏性变更写进 [CHANGELOG](./CHANGELOG.md)，并在本节目说明迁移方式。
 - 发布顺序：本包是基础设施，先于依赖它的包。
 

package/SKILLS.md

@@ -1,23 +1,25 @@
 # @ultime/cli · 可调用能力
 
 > 定位：AI 可调用的通用命令设施。领域命令不在这里。
-> 适用版本：0.1.x
-> 同步基线：0.1.x（手写；API 变化时同批更新）
+> 适用版本：0.2.x
+> 同步基线：0.2.x（手写；API 变化时同批更新）
 
 ---
 
 ## 入口
 
 ```ts
-import { parseArgs, runCli, processContext } from '@ultime/cli'
-import type { ParsedArgs, CliContext, CliSpec, CommandSpec } from '@ultime/cli'
+import { parseArgs, runCli, processContext, CliError } from '@ultime/cli'
+import type { ParsedArgs, CliContext, CliSpec, CommandSpec, CliErrorOptions, CliErrorShape } from '@ultime/cli'
 ```
 
 | 能力 | 输入 | 输出 |
 |---|---|---|
 | `parseArgs(argv)` | 字符串数组 | `{ command, flags, positional }` |
-| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | 退出码；版本 / 帮助 / 未知命令 / 异常由它处理 |
+| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | 退出码；版本 / 帮助 / 未知命令 / 错误由它处理 |
 | `processContext()` | — | `{ cwd, out, err }` |
+| `CliError(message, options)` | 文案 + `code` / `path` / `hint` / `details` / `exitCode` | 可被 `runCli` 统一输出的错误 |
+| `toErrorShape(error)` | 任意异常 | `{ code, message, path?, hint?, details? }` |
 
 ## `CliSpec`
 
@@ -32,11 +34,15 @@ import type { ParsedArgs, CliContext, CliSpec, CommandSpec } from '@ultime/cli'
 
 ## 错误语义
 
-- 未知命令：`err` 写错误，`out` 写 usage，返回 1；
-- 命令抛异常：`err` 写 message，返回 1；
+- 未知命令：`err` 写错误与候选，`out` 写 usage，返回 2；
+- 无命令：`out` 写 usage，返回 2；
+- 普通异常：`err` 写 message，`code: 'ERROR'`，返回 1；
+- `CliError`：带 `code` / `path` / `hint`，返回 `exitCode`（默认 2）；
+- `--json`：错误以 `{ "error": { … } }` 只写 stderr；
 - 版本 / 帮助：返回 0，不执行命令。
 
 ## 反例
 
 - 把 `--check` 当成 cli 内置 flag：它属于调用方的命令。
 - 在 cli 里读具体项目配置：IO 与配置语义属于调用方命令。
+- 在 cli 里发现或聚合其他包的 bin：每个包自带入口，本包不发 bin。

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  * ---------------------------------------------------------------------------
  * 只认三种形态：`command`、`--flag`、`--key value` / `--key=value`；
  * 不引第三方解析库 —— CLI 必须零依赖可跑。
+ * `--json` 是通用输出开关，固定按布尔解析，不吞后面的命令名。
  */
 interface ParsedArgs {
   command: string;
@@ -18,17 +19,51 @@ interface CliContext {
   err: (line: string) => void;
 }
 export declare function processContext(): CliContext;
+/**
+ * error.ts — 机器可读错误
+ * ---------------------------------------------------------------------------
+ * 命令抛 `CliError`，`runCli` 统一转成人类文案或 `--json` 结构；
+ * 普通异常没有字段信息，退化成 `code: 'ERROR'`，退出码 1。
+ */
+interface CliErrorOptions {
+  /** 稳定错误码，例如 `USAGE` / `CONFIG`；上层可追加自己的码。 */
+  code: string;
+  /** 出错位置：字段路径或参数名。 */
+  path?: string;
+  /** 可执行的修复建议。 */
+  hint?: string;
+  /** 附加诊断数据，原样进入 JSON 输出。 */
+  details?: unknown;
+  /** 退出码，默认 2（用法或配置错误）。 */
+  exitCode?: number;
+}
+export declare class CliError extends Error {
+  readonly code: string;
+  readonly path?: string;
+  readonly hint?: string;
+  readonly details?: unknown;
+  readonly exitCode: number;
+  constructor(message: string, options: CliErrorOptions);
+}
+interface CliErrorShape {
+  code: string;
+  message: string;
+  path?: string;
+  hint?: string;
+  details?: unknown;
+}
+export declare function toErrorShape(error: unknown): CliErrorShape;
 interface CommandSpec {
-  /** 单条命令的 help；缺省时回落到全局 usage */
+  /** 单条命令的 help；缺省时生成 `<name> <command> [options]` */
   help?: string;
   run: (args: ParsedArgs, ctx: CliContext) => number;
 }
 interface CliSpec {
-  /** 用于错误与帮助文案，例如 `ultime` */
+  /** 用于错误与帮助文案，例如 `my-cli` */
   name: string;
   version: string;
   usage: string;
   commands: Record<string, CommandSpec>;
 }
 export declare function runCli(spec: CliSpec, argv: string[], ctx?: CliContext): number;
-export type { CliContext, CliSpec, CommandSpec, ParsedArgs };
+export type { CliContext, CliErrorOptions, CliErrorShape, CliSpec, CommandSpec, ParsedArgs };

package/dist/index.js

@@ -1,4 +1,6 @@
 // src/args.ts
+/** 通用布尔 flag：只表达输出形态，不承载业务语义。 */
+const BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json"]);
 function parseArgs(argv) {
 	const flags = {};
 	const positional = [];
@@ -20,6 +22,10 @@ function parseArgs(argv) {
 				flags[body.slice(0, equal)] = body.slice(equal + 1);
 				continue;
 			}
+			if (BOOLEAN_FLAGS.has(body)) {
+				flags[body] = true;
+				continue;
+			}
 			const next = argv[i + 1];
 			if (next && !next.startsWith("-")) {
 				flags[body] = next;
@@ -46,39 +52,116 @@ function processContext() {
 	};
 }
 
+// src/error.ts
+var CliError = class extends Error {
+	code;
+	path;
+	hint;
+	details;
+	exitCode;
+	constructor(message, options) {
+		super(message);
+		this.name = "CliError";
+		this.code = options.code;
+		this.path = options.path;
+		this.hint = options.hint;
+		this.details = options.details;
+		this.exitCode = options.exitCode ?? 2;
+	}
+};
+function toErrorShape(error) {
+	if (error instanceof CliError) return {
+		code: error.code,
+		message: error.message,
+		...error.path === void 0 ? {} : { path: error.path },
+		...error.hint === void 0 ? {} : { hint: error.hint },
+		...error.details === void 0 ? {} : { details: error.details }
+	};
+	return {
+		code: "ERROR",
+		message: error instanceof Error ? error.message : String(error)
+	};
+}
+
 // src/run.ts
 /**
-* run.ts — 命令注册与退出码
+* run.ts — 命令注册、退出码与错误输出
 * ---------------------------------------------------------------------------
-* 通用设施：只负责版本 / 帮助 / 未知命令 / 异常转退出码；
+* 通用设施：只负责版本 / 帮助 / 未知命令 / 错误转换；
 * 具体命令由调用方注册，cli 包不出现任何领域命令。
 */
+/** 未知命令的候选阈值：太小漏提示，太大乱提示。 */
+const SUGGEST_DISTANCE = 2;
+function distance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let row = 1; row <= left.length; row += 1) {
+		const current = [row];
+		for (let col = 1; col <= right.length; col += 1) {
+			const cost = left[row - 1] === right[col - 1] ? 0 : 1;
+			current[col] = Math.min(previous[col] + 1, current[col - 1] + 1, previous[col - 1] + cost);
+		}
+		previous = current;
+	}
+	return previous[right.length];
+}
+function nearest(input, candidates) {
+	let best;
+	for (const name of candidates) {
+		const value = distance(input, name);
+		if (value > SUGGEST_DISTANCE) continue;
+		if (!best || value < best.distance) best = {
+			name,
+			distance: value
+		};
+	}
+	return best?.name;
+}
+function reportError(ctx, error, json) {
+	const shape = toErrorShape(error);
+	if (json) {
+		ctx.err(JSON.stringify({ error: shape }));
+		return;
+	}
+	ctx.err(`✗ ${shape.message}`);
+	if (shape.path) ctx.err(`  位置：${shape.path}`);
+	if (shape.hint) ctx.err(`  提示：${shape.hint}`);
+}
+function exitCodeOf(error) {
+	return error instanceof CliError ? error.exitCode : 1;
+}
 function runCli(spec, argv, ctx = processContext()) {
 	const args = parseArgs(argv);
+	const json = args.flags.json === true;
 	if (args.flags.version) {
 		ctx.out(spec.version);
 		return 0;
 	}
 	if (args.flags.help) {
-		ctx.out(args.command && spec.commands[args.command]?.help ? spec.commands[args.command].help : spec.usage);
+		const command = args.command ? spec.commands[args.command] : void 0;
+		ctx.out(command ? command.help ?? `${spec.name} ${args.command} [options]` : spec.usage);
 		return 0;
 	}
 	if (!args.command) {
 		ctx.out(spec.usage);
-		return 1;
+		return 2;
 	}
 	const command = spec.commands[args.command];
 	if (!command) {
-		ctx.err(`✗ 未知命令：${args.command}\n`);
-		ctx.out(spec.usage);
-		return 1;
+		const suggestion = nearest(args.command, Object.keys(spec.commands));
+		reportError(ctx, new CliError(`未知命令：${args.command}`, {
+			code: "USAGE",
+			path: args.command,
+			hint: suggestion ? `是否想用 ${suggestion}？` : `可用命令：${Object.keys(spec.commands).join(" / ")}`
+		}), json);
+		if (!json) ctx.out(spec.usage);
+		return 2;
 	}
 	try {
 		return command.run(args, ctx);
 	} catch (error) {
-		ctx.err(`✗ ${error instanceof Error ? error.message : String(error)}`);
-		return 1;
+		reportError(ctx, error, json);
+		return exitCodeOf(error);
 	}
 }
 
-export { parseArgs, processContext, runCli };
+export { CliError, parseArgs, processContext, runCli, toErrorShape };

package/llms.txt

@@ -1,6 +1,6 @@
 # @ultime/cli · AI 索引
 
-适用版本：0.1.x
+适用版本：0.2.x
 
 ## 去哪找
 
@@ -9,8 +9,9 @@
 
 ## 机器入口
 
-- 公共出口：`@ultime/cli` 的 `parseArgs` / `runCli` / `processContext` 与类型。
+- 公共出口：`@ultime/cli` 的 `parseArgs` / `runCli` / `processContext` / `CliError` / `toErrorShape` 与类型。
 
 ## 边界
 
 - 通用设施，不含任何领域命令；读盘写盘归调用方。
+- 不发 bin、不做命令发现；每个产品包发布自己的入口。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
   "keywords": [
     "argument-parser",
@@ -41,8 +41,8 @@
   },
   "scripts": {
     "build": "vp pack",
-    "check": "vp check && checks run && pnpm cycles",
-    "checks": "checks run",
+    "check": "vp check && ultime-checks run && pnpm cycles",
+    "checks": "ultime-checks run",
     "cycles": "vp lint --import-plugin --deny=import/no-cycle src",
     "test": "vp test",
     "size": "size-limit --json",
@@ -53,7 +53,7 @@
     "@arethetypeswrong/core": "^0.18.5",
     "@size-limit/preset-small-lib": "^14.3.0",
     "@types/node": "^22.20.5",
-    "@ultime/checks": "^0.2.0",
+    "@ultime/checks": "^0.3.0",
     "publint": "^0.3.25",
     "size-limit": "^14.3.0",
     "typescript": "^5.9.3",