@ultime/cli 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.4 - 2026-11-10
+
+- 构建改用 `vp pack`，产物同时生成 `dist/index.js` 与 `dist/index.d.ts`。
+- `exports.types` 指向 `dist/index.d.ts`，包体不再包含 `src/`；安装后类型解析不依赖源码。
+- 无运行时 API 变化。
+
+## 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`：它不是本包的公开入口，引用的路径也已不存在。

package/CONTRIBUTING.md

@@ -2,25 +2,43 @@
 
 > 给贡献者与 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 / 退出码；配置合法性与产物内容归调用方包。
 - 不 import 任何调用方包的源码，只通过公开包名与 exports 依赖。
 - 不自维护具体项目的字段清单；`schema` 之类由调用方投影。
-- 新增命令或退出码：同步 README、`skills.md`、测试与版本戳。
+- 新增命令或退出码：同步 README、`SKILLS.md`、测试与版本戳。
+
+## Review
+
+提交 PR 前自查五件事：
+
+- **文档**：README / 用法 / 示例是否仍准确；链接、版本、CHANGELOG 是否同步。
+- **注释**：只写为什么、约束、反直觉处；不复述代码。
+- **冗余**：同一事实只有一份正文；新增说明先改真源，其他位置只留指针。
+- **缺漏**：新增能力是否有入口、示例与验证命令。
+- **漂移**：`package.json` / README / `CHANGELOG` / VERSION（及适用的 AI 文档）版本是否一致。
+- **包体**：`npm pack --dry-run` 不含 `tests` / `scripts` / `rules` / 包根 `AGENTS.md` / 构建配置 / lockfile；`exports` 与类型入口一致。
+- **基线**：`engines.node >= 22.18`、产物 `target: node22` 未偏离；开发端脚本与依赖不进入发布包。
+
+机械检查交给 CI；人审看架构、边界、语义与取舍。
 
 ## 验证
 
 ```bash
 pnpm check
 pnpm test
-pnpm typecheck
+pnpm build          # 含 publint / attw / unused
+pnpm size           # 体积只报告，不设门禁
 npm pack --dry-run
 ```
 

package/README.md

@@ -9,7 +9,7 @@
 pnpm add @ultime/cli
 ```
 
-需要 Node >= 22.18；包发的是编译后的 ESM（`dist/`），类型来自 `src/*.ts`。
+需要 Node >= 22.18；包发的是编译后的 ESM（`dist/`），类型来自 `dist/*.d.ts`。
 
 ## 用它做什么
 
@@ -44,6 +44,8 @@ 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 任何领域包，也不认识具体业务对象。

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.d.ts

@@ -0,0 +1,34 @@
+/**
+ * args.ts — 命令行参数解析（纯函数）
+ * ---------------------------------------------------------------------------
+ * 只认三种形态：`command`、`--flag`、`--key value` / `--key=value`；
+ * 不引第三方解析库 —— CLI 必须零依赖可跑。
+ */
+interface ParsedArgs {
+  command: string;
+  flags: Record<string, string | true>;
+  positional: string[];
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** 命令上下文：把「往哪写、怎么写」抽出来，测试里换成内存收集器即可，不用起子进程。 */
+interface CliContext {
+  /** 工作目录：配置与产物路径都相对它解析 */
+  cwd: string;
+  out: (line: string) => void;
+  err: (line: string) => void;
+}
+export declare function processContext(): CliContext;
+interface CommandSpec {
+  /** 单条命令的 help；缺省时回落到全局 usage */
+  help?: string;
+  run: (args: ParsedArgs, ctx: CliContext) => number;
+}
+interface CliSpec {
+  /** 用于错误与帮助文案，例如 `ultime` */
+  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 };

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;
@@ -35,6 +36,7 @@ function parseArgs(argv) {
 		positional
 	};
 }
+
 // src/context.ts
 function processContext() {
 	return {
@@ -43,6 +45,7 @@ function processContext() {
 		err: (line) => console.error(line)
 	};
 }
+
 // src/run.ts
 /**
 * run.ts — 命令注册与退出码
@@ -77,4 +80,5 @@ function runCli(spec, argv, ctx = processContext()) {
 		return 1;
 	}
 }
-export { parseArgs, processContext, runCli };
+
+export { parseArgs, processContext, runCli };

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,6 +1,6 @@
 {
   "name": "@ultime/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
   "keywords": [
     "argument-parser",
@@ -22,8 +22,9 @@
   },
   "files": [
     "dist",
-    "src",
     "README.md",
+    "llms.txt",
+    "SKILLS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md"
@@ -31,7 +32,7 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
@@ -39,18 +40,32 @@
     "access": "public"
   },
   "scripts": {
-    "build": "vp build",
-    "check": "vp check",
+    "build": "vp pack",
+    "check": "vp check && checks run && pnpm cycles",
+    "checks": "checks run",
+    "cycles": "vp lint --import-plugin --deny=import/no-cycle src",
     "test": "vp test",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm check && pnpm test && pnpm build"
+    "size": "size-limit --json",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm build",
+    "prepare": "vp config --no-agent"
   },
   "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@size-limit/preset-small-lib": "^14.3.0",
     "@types/node": "^22.20.5",
-    "tsx": "^4.23.15",
+    "@ultime/checks": "^0.2.0",
+    "publint": "^0.3.25",
+    "size-limit": "^14.3.0",
     "typescript": "^5.9.3",
-    "vite-plus": "1.4.0"
+    "unplugin-unused": "^0.6.0",
+    "vite-plus": "1.5.1"
   },
+  "size-limit": [
+    {
+      "name": "@ultime/cli",
+      "path": "dist/index.js"
+    }
+  ],
   "engines": {
     "node": ">=22.18"
   },

package/src/args.ts

@@ -1,49 +0,0 @@
-/**
- * args.ts — 命令行参数解析（纯函数）
- * ---------------------------------------------------------------------------
- * 只认三种形态：`command`、`--flag`、`--key value` / `--key=value`；
- * 不引第三方解析库 —— CLI 必须零依赖可跑。
- */
-
-export interface ParsedArgs {
-  command: string
-  flags: Record<string, string | true>
-  positional: string[]
-}
-
-export function parseArgs(argv: string[]): ParsedArgs {
-  const flags: Record<string, string | true> = {}
-  const positional: string[] = []
-  let command = ''
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i]
-    if (token === '-h' || token === '--help') {
-      flags.help = true
-      continue
-    }
-    if (token === '-v' || token === '--version') {
-      flags.version = true
-      continue
-    }
-    if (token.startsWith('--')) {
-      const [key, inline] = token.slice(2).split('=', 2)
-      if (inline != null) {
-        flags[key] = inline
-        continue
-      }
-      const next = argv[i + 1]
-      if (next && !next.startsWith('-')) {
-        flags[key] = next
-        i += 1
-      } else {
-        flags[key] = true
-      }
-      continue
-    }
-    if (!command) command = token
-    else positional.push(token)
-  }
-
-  return { command, flags, positional }
-}

package/src/context.ts

@@ -1,15 +0,0 @@
-/** 命令上下文：把「往哪写、怎么写」抽出来，测试里换成内存收集器即可，不用起子进程。 */
-export interface CliContext {
-  /** 工作目录：配置与产物路径都相对它解析 */
-  cwd: string
-  out: (line: string) => void
-  err: (line: string) => void
-}
-
-export function processContext(): CliContext {
-  return {
-    cwd: process.cwd(),
-    out: (line) => console.log(line),
-    err: (line) => console.error(line),
-  }
-}

package/src/index.ts

@@ -1,3 +0,0 @@
-export { parseArgs, type ParsedArgs } from './args.ts'
-export { processContext, type CliContext } from './context.ts'
-export { runCli, type CommandSpec, type CliSpec } from './run.ts'

package/src/run.ts

@@ -1,54 +0,0 @@
-/**
- * run.ts — 命令注册与退出码
- * ---------------------------------------------------------------------------
- * 通用设施：只负责版本 / 帮助 / 未知命令 / 异常转退出码；
- * 具体命令由调用方注册，cli 包不出现任何领域命令。
- */
-
-import { parseArgs, type ParsedArgs } from './args.ts'
-import { processContext, type CliContext } from './context.ts'
-
-export interface CommandSpec {
-  /** 单条命令的 help；缺省时回落到全局 usage */
-  help?: string
-  run: (args: ParsedArgs, ctx: CliContext) => number
-}
-
-export interface CliSpec {
-  /** 用于错误与帮助文案，例如 `ultime` */
-  name: string
-  version: string
-  usage: string
-  commands: Record<string, CommandSpec>
-}
-
-export function runCli(spec: CliSpec, argv: string[], ctx: CliContext = processContext()): number {
-  const args = parseArgs(argv)
-
-  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)
-    return 0
-  }
-  if (!args.command) {
-    ctx.out(spec.usage)
-    return 1
-  }
-
-  const command = spec.commands[args.command]
-  if (!command) {
-    ctx.err(`✗ 未知命令：${args.command}\n`)
-    ctx.out(spec.usage)
-    return 1
-  }
-
-  try {
-    return command.run(args, ctx)
-  } catch (error) {
-    ctx.err(`✗ ${error instanceof Error ? error.message : String(error)}`)
-    return 1
-  }
-}