@ultime/cli 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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` 现在完整保留。

package/CONTRIBUTING.md

@@ -27,6 +27,8 @@
 - **冗余**：同一事实只有一份正文；新增说明先改真源，其他位置只留指针。
 - **缺漏**：新增能力是否有入口、示例与验证命令。
 - **漂移**：`package.json` / README / `CHANGELOG` / VERSION（及适用的 AI 文档）版本是否一致。
+- **包体**：`npm pack --dry-run` 不含 `tests` / `scripts` / `rules` / 包根 `AGENTS.md` / 构建配置 / lockfile；`exports` 与类型入口一致。
+- **基线**：`engines.node >= 22.18`、产物 `target: node22` 未偏离；开发端脚本与依赖不进入发布包。
 
 机械检查交给 CI；人审看架构、边界、语义与取舍。
 
@@ -35,7 +37,8 @@
 ```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`。
 
 ## 用它做什么
 

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
   "keywords": [
     "argument-parser",
@@ -22,7 +22,6 @@
   },
   "files": [
     "dist",
-    "src",
     "README.md",
     "llms.txt",
     "SKILLS.md",
@@ -33,7 +32,7 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
@@ -41,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",
+    "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,50 +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 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[body] = next
-        i += 1
-      } else {
-        flags[body] = 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
-  }
-}