@kevlns/v-cli 0.1.1-beta.1 → 0.2.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +73 -0
  2. package/README.md +89 -16
  3. package/dist/cli.mjs +824 -38
  4. package/package.json +13 -5
  5. package/schemas/v-cli-plugin.schema.json +144 -0
package/AGENTS.md ADDED
@@ -0,0 +1,73 @@
1
+ # AGENTS.md
2
+
3
+ <!-- v-cli-agents:generated -->
4
+
5
+ > 本文件由 `scripts/generate-agents.mjs` 自动生成，请勿手改。
6
+ > 修改插件清单后运行 `npm run generate:agents` 重新生成，`npm run check:agents` 校验漂移。
7
+
8
+ ## 核心约定（v-cli 本体）
9
+
10
+ - 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.1
11
+ - 命令分三类：builtin（内置）、local（~/.v-cli/commands/ 下的本地插件）、official（官方插件白名单）；
12
+ **最新、live 的命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
13
+ - 单个命令的完整元数据用 `v-cli agent describe <命令名> --json` 查看
14
+ - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
15
+ 不解析、不改写插件的 stdout/stderr；插件 `--help`/`--json` 等参数由插件自己消费
16
+ - 插件对 worktree 的写入/提交行为以插件清单 v-cli.plugin.json 的 `agent.safety` 为准：
17
+ v-cli 不替插件做 diff/write-back/commit；**未经显式 flag 不得 push**
18
+
19
+ ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
20
+
21
+ **版本**：0.1.0-beta.2
22
+ **描述**：Pin a Unity project to its exact editor version route, download the verified Unity CLI and install the adapted com.unity.pipeline package for Unity 2022 (Windows-first, non-official Unity tooling).
23
+ **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
24
+
25
+ **何时使用**：Use for Windows-first Unity Editor 2022 workflows that must stay pinned to an exact editor version: diagnose a project against its route, list pinned routes, download the verified Unity CLI, transactionally install the adapted com.unity.pipeline package, or run Unity Pipeline CLI commands with enforced project targeting. Never use on non-Windows hosts.
26
+
27
+ **全局选项**：
28
+ - `-V, --version` — output the version number
29
+ - `-h, --help` — display help for command
30
+
31
+ **子命令**：
32
+ - `doctor` — 检查工程版本、路由、CLI 与 Pipeline 状态（用法：`v-cli unity doctor <project> [options]`）
33
+ - 安全标签：read-only; never writes the project or the cache；fail-closed exact m_EditorVersion + m_EditorVersionWithRevision match (no wildcard, no fallback)；queries running Unity.exe processes via PowerShell; a failed query is reported in the unityProcesses output, not fatal
34
+ - `routes` — 列出所有已配置的 Editor 精确路由（用法：`v-cli unity routes [options]`）
35
+ - 安全标签：read-only; no network access；uses only embedded pinned route metadata shipped in the package
36
+ - `cli install` — 下载并校验固定版本的 Unity CLI（SHA-256 + Authenticode）（用法：`v-cli unity cli install [options]`）
37
+ - 安全标签：writes only under the user cache: %LOCALAPPDATA%\editor-pipeline-cli\cache\cli；downloads from the pinned Unity official CDN HTTPS URL only；verifies fixed SHA-256 + expected size + Authenticode signer subject and certificate thumbprint before the binary is placed；unverified temp download is deleted on any failure; the final file is created by atomic rename
38
+ - `pipeline install` — 按工程 Editor 版本事务式安装适配后的 com.unity.pipeline（用法：`v-cli unity pipeline install <project> [options]`）
39
+ - 安全标签：transactional install: stage -> verify -> backup -> replace -> re-verify -> receipt; automatic rollback on any failure；fail-closed when a matching Unity Editor is running, unless --allow-running-editor；--dry-run never writes the project and never writes a receipt；source and destination trees must match the pinned expected-tree (385 files, SHA-256) before and after placement；writes only under <project>/Packages/com.unity.pipeline and <project>/Library/editor-pipeline-cli
40
+ - `setup` — cli install + pipeline install（用法：`v-cli unity setup <project> [options]`）
41
+ - 安全标签：combines the cli install and pipeline install safety contracts；fail-closed running-Editor guard unless --allow-running-editor；--dry-run never writes the project；--skip-cli avoids all CLI downloads
42
+ - `exec` — 调用路由 CLI 执行 Unity Pipeline 命令；--project-path 由工具统一绑定（用法：`v-cli unity exec <project> [options] -- <unity-cli-args...>`）
43
+ - 安全标签：re-verifies the pinned CLI SHA-256 before every invocation (fail-closed on tamper)；rejects every --project-path variant (case-insensitive: --project-path, --projectPath, -projectPath, --project_path, mixed case)；always appends the resolved --project-path as the final argument; the wrapper owns project targeting；no route fallback: the project must match a pinned route exactly；the documented -- separator is consumed by the wrapper and never forwarded to the Unity CLI
44
+ - `cache clean` — 清理下载缓存与生成的适配包（用法：`v-cli unity cache clean [options]`）
45
+ - 安全标签：removes only directories under the user cache root %LOCALAPPDATA%\editor-pipeline-cli；default scope: generated packages + pipeline downloads only; without --all the CLI cache and logs are preserved
46
+
47
+ ## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
48
+
49
+ **版本**：1.2.1-beta.2
50
+ **描述**：Visual resolver for Git merge conflicts in .xlsx/.xlsm planning tables: three-way sheet/row/cell diff, local UI, write-back and commit.
51
+ **平台**：darwin, linux, win32
52
+
53
+ **何时使用**：When a user asks to resolve Git merge conflicts in .xlsx/.xlsm planning or configuration tables (策划表/配置表冲突): run detect first; when count > 0 run launch and give the returned url to the user. Do not inspect workbook cells or summarize diffs yourself; the resolver owns diff, choices, write-back and commit.
54
+
55
+ **全局选项**：
56
+ - `--repo <path>` — Git repository (default: current directory; searches upward for the Git root).
57
+ - `--runtime-dir <dir>` — Optional directory for extracted Git stage workbooks and manifest (default: system temp). Used by prepare, resolve and launch.
58
+
59
+ **子命令**：
60
+ - `detect` — List unresolved .xlsx/.xlsm files in the repository.（用法：`v-cli xlmerge --repo <repo> detect`）
61
+ - 安全标签：read-only；no-worktree-modification
62
+ - `prepare` — Extract base/ours/theirs stage versions from the Git index and build a sheet-aware manifest.（用法：`v-cli xlmerge --repo <repo> prepare [--path <file>]`）
63
+ - 安全标签：writes-runtime-dir；no-worktree-modification；no-commit
64
+ - `resolve` — Prepare conflicts and serve the local visual resolver in the foreground (blocking).（用法：`v-cli xlmerge --repo <repo> resolve [--path <file>] [--no-browser]`）
65
+ - 安全标签：blocking；binds-loopback；opens-browser-by-default；no-push；writes-runtime-dir；writes-worktree-via-ui；commits-by-default-via-ui
66
+ - `launch` — Prepare conflicts, start the visual resolver in the background and return its URL.（用法：`v-cli xlmerge --repo <repo> launch [--path <file>] [--no-browser]`）
67
+ - 安全标签：starts-background-server；binds-loopback；opens-browser-by-default；no-push；writes-runtime-dir；writes-worktree-via-ui；commits-by-default-via-ui
68
+ - `apply` — Write back decisions from a decisions JSON without launching the UI.（用法：`v-cli xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push] [--message <text>]`）
69
+ - 安全标签：writes-worktree；commits-by-default；pushes-only-with-flag
70
+
71
+ ---
72
+
73
+ 所有清单字段的解释见 `schemas/v-cli-plugin.schema.json` 与 `v-cli agent describe` 输出。
package/README.md CHANGED
@@ -23,8 +23,10 @@ v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个
23
23
  它被设计为**依赖极少、秒级启动、写个文件就能扩展**，与 kevlns 工具家族的其余部分可自由组合。
24
24
 
25
25
  - **插件化架构** - 内置命令走注册表随版本发布；本地插件放进 `~/.v-cli/commands/` 立即生效，无需发版
26
- - **容错加载** - 单个插件语法错误或形状不符只会被跳过并报告，绝不阻断其他命令
27
- - **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr；全局 `--json` 任意位置生效
26
+ - **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）与 `@kevlns/u-cli-mod`（`unity`）是唯一被路由的官方插件，安装后在子进程中运行
27
+ - **容错加载** - 单个插件语法错误、契约不符或注册异常只会被跳过并报告，绝不阻断其他命令
28
+ - **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr
29
+ - **agent 友好** - `agent index/describe` 输出统一索引与完整元数据；仓库内 AGENTS.md 自动生成并有漂移检查
28
30
  - **TypeScript-first** - 严格类型编写，tsup 将核心逻辑打包为单文件 ESM，仅保留 `commander` 运行依赖
29
31
 
30
32
  ## Getting started
@@ -41,16 +43,32 @@ npm install -g git+https://github.com/kevlns/v-cli.git
41
43
 
42
44
  发布稳定版并设置 `latest` 标签后，可直接使用 `npm install -g @kevlns/v-cli`。
43
45
 
46
+ 需要 Node.js **>= 20**。
47
+
44
48
  ### Quick start
45
49
 
46
50
  ```bash
47
- v-cli doctor # 环境体检：node/版本、主目录、配置、插件状态
48
- v-cli plugin list # 列出内置命令与本地插件
51
+ v-cli doctor # 环境体检：node/版本、主目录、配置、官方/本地插件状态
52
+ v-cli plugin list # 列出内置命令、本地插件与官方插件状态
49
53
  v-cli ts 1710000000 # 时间戳互转
54
+ v-cli agent index # 命令 + agent 元数据索引（--json 输出机器可读）
55
+ v-cli agent describe xlmerge --json
56
+ ```
57
+
58
+ ### 控制器命令（官方插件）
59
+
60
+ ```bash
61
+ npm install -g @kevlns/xlmerge@1.2.1-beta.2 # 安装后即可
62
+ v-cli xlmerge --repo <repo> detect # 路由到 xlmerge 子进程
63
+ v-cli xlmerge --repo <repo> resolve
64
+
65
+ # Unity 工具链（仅 Windows 主机可用；其他平台 v-cli 会拒绝路由并说明原因）
66
+ npm install -g @kevlns/u-cli-mod@0.1.0-beta.2
67
+ v-cli unity doctor <project>
50
68
  ```
51
69
 
52
- > [!TIP]
53
- > 所有命令都支持 `--json`（任意位置）：`v-cli doctor --json` 输出机器可读结果，方便脚本消费。
70
+ `v-cli <插件命令> …` 的执行语义：插件在**子进程**中运行（stdio 继承），
71
+ `--json`/`--help`/`--`/插件自有选项一律**原样转发**给插件，v-cli 不解析、不改写插件输出。
54
72
 
55
73
  ## Examples
56
74
 
@@ -61,6 +79,7 @@ v-cli ts 1710000000 # 时间戳互转
61
79
  export default {
62
80
  name: "hello",
63
81
  description: "示例插件",
82
+ apiVersion: 1, // v-cli 0.2 起的插件契约版本，必填
64
83
  register(program, ctx) {
65
84
  program.action(() => ctx.log.result("hello world"));
66
85
  },
@@ -74,46 +93,97 @@ v-cli hello # hello world
74
93
  v-cli plugin list # [local] hello 已出现
75
94
  ```
76
95
 
96
+ > 旧版插件（无 `apiVersion: 1`）会被拒绝并给出解释性错误，请补上字段后重载。
97
+ > 本地插件不能占用内置命令名（`doctor`/`plugin`/`ts`/`agent`/`help`）或官方命令名（`xlmerge`/`unity`）。
98
+
77
99
  ### 在脚本中消费输出
78
100
 
79
101
  ```bash
80
102
  v-cli ts 1710000000 --json | jq .seconds
103
+ v-cli --json ts 1710000000 | jq .seconds # 前置全局 --json 同样生效
81
104
  ```
82
105
 
106
+ ## `--json` 语义（v-cli 0.2）
107
+
108
+ - **前置全局**：`v-cli --json <cmd> …` —— `--json` 出现在首个命令词之前时被 v-cli 消费，`ctx.json` 为真
109
+ - **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
110
+ - 其他中间位置（如 `v-cli plugin --json list`）不承诺 JSON 输出
111
+ - 插件转发示例：`v-cli xlmerge detect --json` 会把 `--json` 转给 xlmerge；`v-cli --json xlmerge detect` 则消费掉全局 `--json`、只转发 `detect`
112
+
83
113
  ## API
84
114
 
85
115
  ### 内置命令
86
116
 
87
117
  | 命令 | 说明 |
88
118
  | --- | --- |
89
- | `v-cli doctor` | 环境体检：node/v-cli 版本、主目录、config 可写性、本地插件与加载错误 |
90
- | `v-cli plugin list` | 列出全部命令（标注 builtin/local 来源） |
119
+ | `v-cli doctor` | 环境体检：node/v-cli 版本、主目录、config 可写性、本地插件与官方插件状态 |
120
+ | `v-cli plugin list` | 列出全部命令（builtin/local/official 来源与状态） |
91
121
  | `v-cli plugin path` | 打印本地插件目录 |
92
122
  | `v-cli ts [value]` | 无参=当前时间；数字（秒/毫秒自动识别）=转可读时间；日期串=转时间戳 |
123
+ | `v-cli agent index [--json]` | 全部命令的 agent 索引（builtin/local/official，含元数据状态） |
124
+ | `v-cli agent describe <name> [--json]` | 单个命令的完整记录；未找到时 stderr 报错并退出 1 |
93
125
 
94
- ### 插件契约 `CliCommand`
126
+ ### 插件契约 `CliCommand`（apiVersion 1）
95
127
 
96
128
  ```ts
97
129
  interface CliCommand {
98
130
  name: string; // 子命令名
99
131
  description: string;
132
+ apiVersion: 1; // v-cli 0.2 起必填
100
133
  hidden?: boolean;
134
+ agent?: { // agent 索引元数据（可选）
135
+ whenToUse?: string; // 什么场景该调用
136
+ globalOptions?: { flags: string; description: string }[];
137
+ commands?: { path: string[]; description: string; usage?: string }[];
138
+ };
101
139
  register(program: Command, ctx: CliContext): void;
102
140
  }
103
141
 
104
142
  interface CliContext {
105
143
  log: Logger; // result() 走 stdout，info/warn/error 走 stderr
106
144
  config: ConfigStore; // <home>/config.json 惰性读写
107
- json: boolean; // 全局 --json 开关，命令必须尊重
145
+ json: boolean; // 全局 --json 开关（来自前置段扫描），命令必须尊重
108
146
  homeDir: string; // 主目录（默认 ~/.v-cli）
109
147
  }
110
148
  ```
111
149
 
150
+ #### 官方插件注入的环境变量
151
+
152
+ | 变量 | 值 | 说明 |
153
+ | --- | --- | --- |
154
+ | `V_CLI_HOST_VERSION` | v-cli 版本 | 插件可据此判断宿主能力 |
155
+ | `V_CLI_PLUGIN_API` | `1` | 插件契约版本 |
156
+ | `V_CLI_INVOKED_BY` | `v-cli` | 标识本次调用来自 v-cli |
157
+
112
158
  #### 环境变量
113
159
 
114
160
  | 变量 | 默认值 | 说明 |
115
161
  | --- | --- | --- |
116
162
  | `V_CLI_HOME` | `~/.v-cli` | 覆盖主目录（配置、本地插件都从这里找） |
163
+ | `V_CLI_PLUGIN_RESOLVE_FROM` | — | 测试/开发钩子：官方插件从 `<值>/node_modules/{包}` 解析 |
164
+
165
+ ## 官方插件清单契约
166
+
167
+ - 每个官方插件包内包含 `v-cli.plugin.json`（`package.json` 的 `vCli.manifest` 可指向其他文件名）
168
+ - 清单 schema 见 `schemas/v-cli-plugin.schema.json`（`schemaVersion: 1`）；v-cli 内置等价校验器
169
+ - 身份校验：清单 `package`/`bin` 必须与包的 `package.json` 一致；`bin` 目标必须是字符串、解析后位于包目录内、且文件存在，否则视为 `invalid`/`missing` 并拒绝路由
170
+ - 平台门禁：`platforms` 不含当前平台时拒绝路由（如 `unity` 仅 `win32`）
171
+
172
+ ## 仓库工具脚本
173
+
174
+ ```bash
175
+ npm run generate:agents # 默认从【已安装的官方依赖】确定性生成 AGENTS.md
176
+ npm run check:agents # AGENTS.md 漂移检查（默认与已安装依赖比对；不一致时非零退出）
177
+ npm run pack:guard # 发布内容护栏：身份/必需文件/禁止内容/依赖精确固定/engines
178
+ npm run test:package # 发布后安装冒烟：npm pack → 隔离 prefix 全局安装 → 运行 bin wrapper 断言
179
+ npm run check # build + typecheck + test + check:agents + pack:guard
180
+ ```
181
+
182
+ > `@kevlns/xlmerge@1.2.1-beta.2` / `@kevlns/u-cli-mod@0.1.0-beta.2` 已发布并由 `npm install`
183
+ > 装入仓库 node_modules：`generate:agents`/`check:agents` 的默认（installed-deps）检查即为
184
+ > 最终形态，`npm run check` 因此才能全绿，CI 的 `check:agents` 步骤也随之总是生效
185
+ > （不依赖 sibling 仓库检出；若未来仍需要在预发布阶段以 sibling 清单 bootstrap，
186
+ > 可显式传 `--manifest <path>`）。
117
187
 
118
188
  ## Package family
119
189
 
@@ -121,17 +191,20 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
121
191
 
122
192
  | Package | Purpose | Status |
123
193
  | --- | --- | --- |
124
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.1.1-beta.1 |
125
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.1 |
194
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.0-beta.1 |
195
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.2 |
196
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.1.0-beta.2 |
126
197
 
127
198
  ## Compatibility
128
199
 
129
200
  | Runtime | Supported versions |
130
201
  | --- | --- |
131
- | Node.js | `18` and later |
202
+ | Node.js | `20` and later |
132
203
  | TypeScript | `5.6` and later（仅开发时） |
133
204
 
134
- CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时仅依赖 `commander`。
205
+ CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时依赖 `commander` 与两个官方插件包
206
+ （`@kevlns/xlmerge`、`@kevlns/u-cli-mod`，均为精确固定版本；安装 v-cli 时一起安装，
207
+ 未装时 `plugin list`/`doctor`/`agent index` 会诚实报告 `missing` 状态）。
135
208
 
136
209
  ## Contributing
137
210
 
@@ -139,7 +212,7 @@ CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时仅依赖
139
212
  git clone https://github.com/kevlns/v-cli.git
140
213
  cd v-cli
141
214
  npm install
142
- npm run build && npm test
215
+ npm run check
143
216
  ```
144
217
 
145
218
  For bugs and feature requests, use
@@ -153,4 +226,4 @@ Released under the [MIT License](./LICENSE).
153
226
 
154
227
  Part of the **kevlns** tool family.
155
228
 
156
- </div>
229
+ </div>