@ultime/cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.3 - 2026-11-10
+
+- 修复 `--key=value` 的值含等号时被截断：`--define=KEY=VALUE` 现在完整保留。
+- 包内新增 `llms.txt` / `SKILLS.md` 作为消费侧 AI 入口；`rules/` 留仓，操作约束并入 `AGENTS.md`。
+
+## 0.1.2 - 2026-11-09
+
+- 移除仓库内遗留的 `bin/ultime.js`：它不是本包的公开入口，引用的路径也已不存在。
+- `runCli` 捕获非 `Error` 异常时输出字符串，不再显示 `undefined`。
+- 文档、规则与测试改为领域中立；新增参数 / 运行时覆盖与包内容边界测试。
+- `keywords` 改为通用 CLI 词，避免被当成领域工具。
+
 ## 0.1.1 - 2026-11-04
 
 - 仓库自带 `pnpm-lock.yaml` 并声明 `packageManager`，依赖可复现，CI 用 `--frozen-lockfile`。
@@ -8,4 +20,4 @@
 ## 0.1.0 - 2026-11-04
 
 - 首次发布：通用命令行设施——`parseArgs` / `runCli` / `processContext` 与相关类型。
-- 零领域依赖，不内置任何命令；`ultime` 的 init / build / schema 归 `@ultime/core`。
+- 零领域依赖，不内置任何具体命令；具体命令归调用方包。

package/CONTRIBUTING.md

@@ -2,18 +2,33 @@
 
 > 给贡献者与 AI 的最短协作规则。命令见 [README](./README.md)。
 
-## 工作流
+## Git 流程
 
-1. 从 `main` 切 `feat/<主题>` / `fix/<主题>`。
-2. 完成后 `git rebase main` 再合并；主分支不保留中间提交。
-3. 一次提交一件事，提交信息用 `type(scope): subject`。
+1. 从 `main` 切 `feat/<主题>` / `fix/<主题>` / `docs-<主题>`。
+2. 开发完成后 `git rebase main`；一次提交一件事，提交信息用 `type(scope): subject`。
+3. push 分支并开 PR；CI 必须通过，评论必须解决。
+4. 用 rebase / squash 合并，删除分支；`main` 不保留中间提交。
+5. 不直接 push `main`，不 force push、不删除 `main`；`main` 受保护，管理员也一样。
+6. 发布按包版本打 tag，由 CI 执行；tag 规则见仓库保护设置。
 
 ## 改动规则
 
-- CLI 只做参数 / 路径 / IO / 退出码；配置合法性与产物内容归 `@ultime/core/tools`。
-- 不 import core 内部源码，只用包名 + exports。
-- 不自维护字段清单；`schema` 从 core 的 studio / tools 投影。
-- 新增命令或退出码：同步 README、`skills.md`、测试与版本戳。
+- CLI 只做参数 / 路径 / IO / 退出码；配置合法性与产物内容归调用方包。
+- 不 import 任何调用方包的源码，只通过公开包名与 exports 依赖。
+- 不自维护具体项目的字段清单；`schema` 之类由调用方投影。
+- 新增命令或退出码：同步 README、`SKILLS.md`、测试与版本戳。
+
+## Review
+
+提交 PR 前自查五件事：
+
+- **文档**：README / 用法 / 示例是否仍准确；链接、版本、CHANGELOG 是否同步。
+- **注释**：只写为什么、约束、反直觉处；不复述代码。
+- **冗余**：同一事实只有一份正文；新增说明先改真源，其他位置只留指针。
+- **缺漏**：新增能力是否有入口、示例与验证命令。
+- **漂移**：`package.json` / README / `CHANGELOG` / VERSION（及适用的 AI 文档）版本是否一致。
+
+机械检查交给 CI；人审看架构、边界、语义与取舍。
 
 ## 验证
 
@@ -27,4 +42,4 @@ npm pack --dry-run
 ## 版本
 
 - 0.x 阶段命令面与退出码仍可能调整；破坏性变更写进 README「版本与兼容」。
-- 发布顺序：studio → core → cli。
+- 协议变更先发 cli，再发依赖它的包。

package/README.md

@@ -1,6 +1,6 @@
 # cli
 
-**通用命令行设施**：参数解析、命令注册、上下文与退出码。零领域依赖，不内置任何 `ultime` 命令。
+**通用命令行设施**：参数解析、命令注册、上下文与退出码。零领域依赖，不内置任何具体命令。
 
 [![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D22.18-black)](./package.json)
@@ -44,12 +44,13 @@ process.exitCode = runCli(spec, process.argv.slice(2), processContext())
 
 `parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`；`-h/--help` 与 `-v/--version` 是保留 flag。
 
+AI 入口：[`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)（能力表）随包发布。
+
 ## 边界
 
-- **零领域依赖**：不 import core / kit / viewer，也不知道 token、组件或设计稿。
-- **不引第三方解析 / 着色库**：解析用现成的零依赖实现，着色直接用 ANSI；Node 内置的 `util.parseArgs` / `util.styleText` 是后续替换首选，等出现嵌套子命令或补全需求再评估 `commander` 一类工具。
-- **不复用于 skills CLI**：skills 通过复制安装（不带 `node_modules`），且支持 Node 20；本包是 Node 22.18 的内部设施，两者只共享契约与夹具，不共享运行时。
-- **不内置命令**：`ultime init/build/schema` 属于 `@ultime/core`；kit / viewer 将来各发自己的 bin。
+- **零领域依赖**：不 import 任何领域包，也不认识具体业务对象。
+- **不引第三方解析 / 着色库**：解析用零依赖实现，着色直接用 ANSI；Node 内置的 `util.parseArgs` / `util.styleText` 是后续替换首选，等出现嵌套子命令或补全需求再评估 `commander` 一类工具。
+- **不内置命令**：具体命令由调用方包注册，各自发布自己的 bin。
 - **不做 IO 策略**：读盘写盘、配置路径由命令自己决定；本包只提供 `cwd` 与 `out/err`。
 
 ## 目录
@@ -67,7 +68,7 @@ tests/         参数与运行时分发
 
 - 当前 `0.1.x`；0.x 阶段 API 仍可能调整。
 - 破坏性变更写进 [CHANGELOG](./CHANGELOG.md)，并在本节目说明迁移方式。
-- 发布顺序：本包是基础设施，先于 studio / core。
+- 发布顺序：本包是基础设施，先于依赖它的包。
 
 ## 许可
 

package/SECURITY.md

@@ -9,6 +9,6 @@
 
 ## 范围
 
-- CLI 读取项目配置与 seed，写产物文件；不执行配置里的任意命令，也不发起网络请求。
+- 本包自身不读盘写盘；调用方命令可能读取项目配置与文件，路径校验与写入范围由调用方负责。
 - 主要风险是路径穿越、覆盖非预期文件、把凭据写进配置或产物。
 - 发现泄露先轮换凭据，再修代码；修复进入 `fix/<主题>` 分支。

package/SKILLS.md

@@ -0,0 +1,42 @@
+# @ultime/cli · 可调用能力
+
+> 定位：AI 可调用的通用命令设施。领域命令不在这里。
+> 适用版本：0.1.x
+> 同步基线：0.1.x（手写；API 变化时同批更新）
+
+---
+
+## 入口
+
+```ts
+import { parseArgs, runCli, processContext } from '@ultime/cli'
+import type { ParsedArgs, CliContext, CliSpec, CommandSpec } from '@ultime/cli'
+```
+
+| 能力 | 输入 | 输出 |
+|---|---|---|
+| `parseArgs(argv)` | 字符串数组 | `{ command, flags, positional }` |
+| `runCli(spec, argv, ctx?)` | `CliSpec` + 参数 | 退出码；版本 / 帮助 / 未知命令 / 异常由它处理 |
+| `processContext()` | — | `{ cwd, out, err }` |
+
+## `CliSpec`
+
+```ts
+{
+  name: string
+  version: string
+  usage: string
+  commands: Record<string, { help?: string; run(args, ctx): number }>
+}
+```
+
+## 错误语义
+
+- 未知命令：`err` 写错误，`out` 写 usage，返回 1；
+- 命令抛异常：`err` 写 message，返回 1；
+- 版本 / 帮助：返回 0，不执行命令。
+
+## 反例
+
+- 把 `--check` 当成 cli 内置 flag：它属于调用方的命令。
+- 在 cli 里读具体项目配置：IO 与配置语义属于调用方命令。

package/dist/index.js

@@ -14,16 +14,17 @@ function parseArgs(argv) {
 			continue;
 		}
 		if (token.startsWith("--")) {
-			const [key, inline] = token.slice(2).split("=", 2);
-			if (inline != null) {
-				flags[key] = inline;
+			const body = token.slice(2);
+			const equal = body.indexOf("=");
+			if (equal !== -1) {
+				flags[body.slice(0, equal)] = body.slice(equal + 1);
 				continue;
 			}
 			const next = argv[i + 1];
 			if (next && !next.startsWith("-")) {
-				flags[key] = next;
+				flags[body] = next;
 				i += 1;
-			} else flags[key] = true;
+			} else flags[body] = true;
 			continue;
 		}
 		if (!command) command = token;
@@ -73,7 +74,7 @@ function runCli(spec, argv, ctx = processContext()) {
 	try {
 		return command.run(args, ctx);
 	} catch (error) {
-		ctx.err(`✗ ${error.message}`);
+		ctx.err(`✗ ${error instanceof Error ? error.message : String(error)}`);
 		return 1;
 	}
 }

package/llms.txt

@@ -0,0 +1,16 @@
+# @ultime/cli · AI 索引
+
+适用版本：0.1.x
+
+## 去哪找
+
+- 怎么用：[README.md](./README.md)
+- 可调用能力：[SKILLS.md](./SKILLS.md)
+
+## 机器入口
+
+- 公共出口：`@ultime/cli` 的 `parseArgs` / `runCli` / `processContext` 与类型。
+
+## 边界
+
+- 通用设施，不含任何领域命令；读盘写盘归调用方。

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@ultime/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
   "keywords": [
+    "argument-parser",
     "cli",
-    "codegen",
-    "css-variables",
-    "design-system",
-    "design-tokens",
-    "dtcg"
+    "command-line",
+    "command-registry",
+    "exit-code",
+    "typescript"
   ],
   "homepage": "https://github.com/ultime-space/cli#readme",
   "bugs": {
@@ -24,6 +24,8 @@
     "dist",
     "src",
     "README.md",
+    "llms.txt",
+    "SKILLS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md"
@@ -49,7 +51,7 @@
     "@types/node": "^22.20.5",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
-    "vite-plus": "1.4.0"
+    "vite-plus": "1.5.1"
   },
   "engines": {
     "node": ">=22.18"

package/src/args.ts

@@ -27,17 +27,18 @@ export function parseArgs(argv: string[]): ParsedArgs {
       continue
     }
     if (token.startsWith('--')) {
-      const [key, inline] = token.slice(2).split('=', 2)
-      if (inline != null) {
-        flags[key] = inline
+      const body = token.slice(2)
+      const equal = body.indexOf('=')
+      if (equal !== -1) {
+        flags[body.slice(0, equal)] = body.slice(equal + 1)
         continue
       }
       const next = argv[i + 1]
       if (next && !next.startsWith('-')) {
-        flags[key] = next
+        flags[body] = next
         i += 1
       } else {
-        flags[key] = true
+        flags[body] = true
       }
       continue
     }

package/src/run.ts

@@ -48,7 +48,7 @@ export function runCli(spec: CliSpec, argv: string[], ctx: CliContext = processC
   try {
     return command.run(args, ctx)
   } catch (error) {
-    ctx.err(`✗ ${(error as Error).message}`)
+    ctx.err(`✗ ${error instanceof Error ? error.message : String(error)}`)
     return 1
   }
 }