@ultime/cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 - 2026-11-04
+
+- 首次发布：通用命令行设施——`parseArgs` / `runCli` / `processContext` 与相关类型。
+- 零领域依赖，不内置任何命令；`ultime` 的 init / build / schema 归 `@ultime/core`。

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+> 给贡献者与 AI 的最短协作规则。命令见 [README](./README.md)。
+
+## 工作流
+
+1. 从 `main` 切 `feat/<主题>` / `fix/<主题>`。
+2. 完成后 `git rebase main` 再合并；主分支不保留中间提交。
+3. 一次提交一件事，提交信息用 `type(scope): subject`。
+
+## 改动规则
+
+- CLI 只做参数 / 路径 / IO / 退出码；配置合法性与产物内容归 `@ultime/core/tools`。
+- 不 import core 内部源码，只用包名 + exports。
+- 不自维护字段清单；`schema` 从 core 的 studio / tools 投影。
+- 新增命令或退出码：同步 README、`skills.md`、测试与版本戳。
+
+## 验证
+
+```bash
+pnpm check
+pnpm test
+pnpm typecheck
+npm pack --dry-run
+```
+
+## 版本
+
+- 0.x 阶段命令面与退出码仍可能调整；破坏性变更写进 README「版本与兼容」。
+- 发布顺序：studio → core → cli。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultime contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**通用命令行设施**：参数解析、命令注册、上下文与退出码。零领域依赖，不内置任何 `ultime` 命令。
+
+[![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D22.18-black)](./package.json)
+
+```bash
+pnpm add @ultime/cli
+```
+
+需要 Node >= 22.18；包发的是编译后的 ESM（`dist/`），类型来自 `src/*.ts`。
+
+## 用它做什么
+
+包作者只写自己的命令，参数、help、未知命令与退出码交给本包：
+
+```ts
+import { runCli, processContext } from '@ultime/cli'
+
+const spec = {
+  name: 'my-cli',
+  version: '0.1.0',
+  usage: 'my-cli <command>',
+  commands: {
+    build: {
+      help: 'my-cli build [--check]',
+      run: (args, ctx) => {
+        ctx.out(`check=${Boolean(args.flags.check)}`)
+        return 0
+      },
+    },
+  },
+}
+
+process.exitCode = runCli(spec, process.argv.slice(2), processContext())
+```
+
+## 出口
+
+| 入口 | 提供 |
+|---|---|
+| `@ultime/cli` | `parseArgs` / `runCli` / `processContext` / `CliContext` / `CommandSpec` / `CliSpec` |
+
+`parseArgs` 只认 `command`、`--flag`、`--key value` / `--key=value`；`-h/--help` 与 `-v/--version` 是保留 flag。
+
+## 边界
+
+- **零领域依赖**：不 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。
+- **不做 IO 策略**：读盘写盘、配置路径由命令自己决定；本包只提供 `cwd` 与 `out/err`。
+
+## 目录
+
+```text
+src/
+  args.ts      参数解析（纯函数）
+  context.ts   命令上下文（cwd / out / err）
+  run.ts       命令注册、help、未知命令与退出码
+  index.ts     公共出口
+tests/         参数与运行时分发
+```
+
+## 版本与兼容
+
+- 当前 `0.1.x`；0.x 阶段 API 仍可能调整。
+- 破坏性变更写进 [CHANGELOG](./CHANGELOG.md)，并在本节目说明迁移方式。
+- 发布顺序：本包是基础设施，先于 studio / core。
+
+## 许可
+
+MIT，见 [LICENSE](./LICENSE)。

package/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+> 漏洞与凭据泄露的报告方式；不在这里披露细节。
+
+## 报告
+
+- 不要在公开 Issue 中粘贴密钥、客户数据或可利用细节。
+- 通过仓库的私有安全通道联系维护者；没有通道时先开一个不含敏感信息的 Issue，说明「需要私下同步」。
+
+## 范围
+
+- CLI 读取项目配置与 seed，写产物文件；不执行配置里的任意命令，也不发起网络请求。
+- 主要风险是路径穿越、覆盖非预期文件、把凭据写进配置或产物。
+- 发现泄露先轮换凭据，再修代码；修复进入 `fix/<主题>` 分支。

package/dist/index.js

@@ -0,0 +1,80 @@
+// src/args.ts
+function parseArgs(argv) {
+	const flags = {};
+	const positional = [];
+	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
+	};
+}
+// src/context.ts
+function processContext() {
+	return {
+		cwd: process.cwd(),
+		out: (line) => console.log(line),
+		err: (line) => console.error(line)
+	};
+}
+// src/run.ts
+/**
+* run.ts — 命令注册与退出码
+* ---------------------------------------------------------------------------
+* 通用设施：只负责版本 / 帮助 / 未知命令 / 异常转退出码；
+* 具体命令由调用方注册，cli 包不出现任何领域命令。
+*/
+function runCli(spec, argv, ctx = processContext()) {
+	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.message}`);
+		return 1;
+	}
+}
+export { parseArgs, processContext, runCli };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@ultime/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Ultime · cli：通用命令行设施（参数 / 命令注册 / 上下文 / 退出码），零领域依赖",
+  "keywords": [
+    "cli",
+    "codegen",
+    "css-variables",
+    "design-system",
+    "design-tokens",
+    "dtcg"
+  ],
+  "homepage": "https://github.com/ultime-space/cli#readme",
+  "bugs": {
+    "url": "https://github.com/ultime-space/cli/issues"
+  },
+  "license": "MIT",
+  "author": "Ultime contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ultime-space/cli.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp build",
+    "check": "vp check",
+    "test": "vp test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vite-plus": "1.4.0"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/args.ts

@@ -0,0 +1,49 @@
+/**
+ * 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

@@ -0,0 +1,15 @@
+/** 命令上下文：把「往哪写、怎么写」抽出来，测试里换成内存收集器即可，不用起子进程。 */
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,54 @@
+/**
+ * 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 as Error).message}`)
+    return 1
+  }
+}