@kevlns/u-cli-mod 0.1.0 → 0.1.2

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 (2) hide show
  1. package/README.md +98 -47
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,57 +1,62 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/kevlns/u-cli-mod/main/logo.png" alt="u-cli-mod logo" width="320" />
4
+
1
5
  # u-cli-mod
2
6
 
3
- 按 **精确 Unity Editor 版本**路由、下载并安装 Unity CLI 与适配后 `com.unity.pipeline` 的命令行工具(**Windows-first**)。
7
+ **按精确 Unity Editor 版本路由、下载并安装 Unity CLI 与适配后 `com.unity.pipeline` 的命令行工具(Windows-first)。**
4
8
 
5
- - 仓库:<https://github.com/kevlns/u-cli-mod>
6
- - npm 包:`@kevlns/u-cli-mod`
7
- - **这不是 Unity 官方项目**,与 Unity Technologies 无隶属关系;`com.unity.pipeline` 的 Unity 2022 适配属于非官方移植。
9
+ [![npm version](https://img.shields.io/npm/v/%40kevlns%2Fu-cli-mod?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@kevlns/u-cli-mod)
10
+ [![npm downloads](https://img.shields.io/npm/dm/%40kevlns%2Fu-cli-mod?style=flat-square&color=4c8bf5)](https://www.npmjs.com/package/@kevlns/u-cli-mod)
11
+ [![CI](https://img.shields.io/github/actions/workflow/status/kevlns/u-cli-mod/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/kevlns/u-cli-mod/actions/workflows/ci.yml)
12
+ [![license](https://img.shields.io/github/license/kevlns/u-cli-mod?style=flat-square&color=2e8b57)](./LICENSE)
8
13
 
9
- ## 本仓库/包 与 不包含
14
+ [Getting started](#getting-started) · [Usage](#usage) · [Routes](#routes) · [Package family](#package-family)
10
15
 
11
- - ✅ 只包含本工具自己的 TypeScript 代码、版本路由元数据与哈希清单。
12
- - ✅ Unity CLI 与 `com.unity.pipeline` 在**运行时**从 Unity 官方地址下载到**用户缓存**。
13
- - ❌ 仓库和 npm 包**不包含**任何 Unity 二进制(`.exe`/`.dll`)、tgz 或 `com.unity.pipeline` 源码。
14
- - ❌ 无 `postinstall`;安装 npm 包不会下载或修改任何工程。
16
+ </div>
15
17
 
16
- ## 原理
18
+ ---
17
19
 
18
- 1. 读取目标工程 `ProjectSettings/ProjectVersion.txt`,要求 `m_EditorVersion` 与 `m_EditorVersionWithRevision` **同时存在且与路由完全一致**(fail-closed,无通配、无“最近版本”回退)。
19
- 2. 按路由下载固定版本的 Unity CLI:HTTPS 白名单(仅 Unity 官方 CDN),校验固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹,临时文件原子更名为最终文件。
20
- 3. 按路由下载固定版本的 `com.unity.pipeline` tgz:固定 SHA-256(主)+ SHA-1(交叉),安全解包(解包前逐项拒绝绝对路径、`..`、符号/硬链接等非常规条目)。
21
- 4. 在**用户缓存**中确定性转换:`package.json` 最低 Unity 版本、`PhysicsMaterial` 兼容、`rawRenderQueue` 读取兼容、Roslyn DLL 的 `.meta` 转为 Unity 2022 格式(保留 GUID)、删除 `Tests` 源码与失效签名文件;输出必须与 `routes/expected-tree/*.json`(含 `Tests.meta` 共 385 个文件)逐字节一致。
22
- 5. 事务式安装到 `Packages/com.unity.pipeline`:staging → 校验 → 备份 → 替换 → 再校验 → receipt;任一步失败自动回滚。运行中的 Unity Editor 会 fail-closed 阻止安装。
23
- 6. `exec` 每次调用前重新校验 CLI 哈希,并**禁止任何 `--project-path` 变体覆盖目标工程**。
20
+ > **这不是 Unity 官方项目**,与 Unity Technologies 无隶属关系;`com.unity.pipeline` 的 Unity 2022 适配属于非官方移植。
24
21
 
25
- > **缓存目录说明**:用户缓存默认为 `%LOCALAPPDATA%\editor-pipeline-cli`;该目录名沿用历史名称,以避免破坏已通过验证的缓存/收据契约。工程内的安装事务目录 `Library/editor-pipeline-cli` 同理保留。这两个目录名与 npm 包名 `@kevlns/u-cli-mod` 无关,属于兼容性保留项。
22
+ ## Why u-cli-mod?
26
23
 
27
- ## 安装与构建
24
+ Unity 工程自动化通常需要把「编辑器版本」与「CLI 工具链」精确锁定。u-cli-mod 让这件事在 Windows 上**可复现、可校验、可回滚**:
25
+
26
+ - **精确版本路由** - 以 `m_EditorVersion` + revision 双重匹配定位路由,没有“就近版本”回退,版本不在路由表内时如实报告而非猜测
27
+ - **可验证下载** - Unity CLI 固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹;`com.unity.pipeline` 固定 SHA-256(主)+ SHA-1(交叉)
28
+ - **确定性转换** - 在用户缓存中把 `com.unity.pipeline` 适配到 Unity 2022,输出与 `routes/expected-tree/*.json`(385 个文件)逐字节一致
29
+ - **事务式安装** - staging → 校验 → 备份 → 替换 → 再校验 → receipt,任一步失败自动回滚;运行中的 Editor fail-closed
30
+ - **工程绑定** - `exec` 每次重新校验 CLI 哈希,并禁止任何 `--project-path` 变体覆盖目标工程
31
+
32
+ ## Getting started
33
+
34
+ ### Install
28
35
 
29
36
  ```bash
30
- npm ci
31
- npm run build
32
- npm test
33
- npm run lint
34
- npm run pack:guard # 真实 npm pack + 内容守卫(禁 exe/dll/tgz/Unity 源码)
35
- npm run check # build + lint + test + pack:guard 一键
37
+ npm install -g @kevlns/u-cli-mod
38
+
39
+ # 或不安装,直接运行:
40
+ npx --package @kevlns/u-cli-mod u-cli-mod routes
36
41
  ```
37
42
 
38
43
  要求 Node.js >= 20(Windows 10+)。
39
44
 
40
- ## 使用
41
-
42
- 安装:
45
+ ### Quick start
43
46
 
44
47
  ```bash
45
- npm install --global @kevlns/u-cli-mod
46
- # 或不安装,直接运行:
47
- npx --package @kevlns/u-cli-mod u-cli-mod routes
48
+ u-cli-mod doctor <project> # 只读体检:路由 / CLI / 适配包状态
49
+ u-cli-mod setup <project> # CLI + 适配包一键就绪(推荐首次入口)
50
+ u-cli-mod routes # 列出支持的 Editor 路由
48
51
  ```
49
52
 
50
- 常用命令:
53
+ ## Usage
54
+
55
+ > 示例中的 `<project>` 指代你的 Unity 工程目录,请替换为实际路径。
51
56
 
52
57
  ```bash
53
58
  # 只读检查工程与路由
54
- u-cli-mod doctor C:\Projects\Debussy\debussy-client
59
+ u-cli-mod doctor <project>
55
60
 
56
61
  # 列出支持的 Editor 路由
57
62
  u-cli-mod routes
@@ -60,17 +65,17 @@ u-cli-mod routes
60
65
  u-cli-mod cli install
61
66
 
62
67
  # 预览 Pipeline 安装(不写入)
63
- u-cli-mod pipeline install C:\Projects\Debussy\debussy-client --dry-run
68
+ u-cli-mod pipeline install <project> --dry-run
64
69
 
65
70
  # 正式安装(先关闭目标工程的 Unity Editor)
66
- u-cli-mod pipeline install C:\Projects\Debussy\debussy-client
71
+ u-cli-mod pipeline install <project>
67
72
 
68
73
  # CLI + Pipeline 一键准备
69
- u-cli-mod setup C:\Projects\Debussy\debussy-client
74
+ u-cli-mod setup <project>
70
75
 
71
76
  # 执行 Unity Pipeline 命令(自动绑定目标工程)
72
- u-cli-mod exec C:\Projects\Debussy\debussy-client -- command editor_status
73
- u-cli-mod exec C:\Projects\Debussy\debussy-client -- command get_scene_hierarchy
77
+ u-cli-mod exec <project> -- command editor_status
78
+ u-cli-mod exec <project> -- command get_scene_hierarchy
74
79
 
75
80
  # 清理缓存
76
81
  u-cli-mod cache clean
@@ -78,19 +83,35 @@ u-cli-mod cache clean
78
83
 
79
84
  `exec` 会把 `--project-path <工程>` 追加到 Unity CLI 参数末尾;传入任何形式的 `--project-path`(含 `-projectPath`、`--projectPath`、大小写混合)会直接报错。
80
85
 
81
- 已发布正式版,可直接使用 `npm install -g @kevlns/u-cli-mod`,或用 `npx --package @kevlns/u-cli-mod u-cli-mod ...`。
86
+ ## 原理
87
+
88
+ 1. 读取目标工程 `ProjectSettings/ProjectVersion.txt`,要求 `m_EditorVersion` 与 `m_EditorVersionWithRevision` **同时存在且与路由完全一致**(fail-closed,无通配、无“最近版本”回退)。
89
+ 2. 按路由下载固定版本的 Unity CLI:HTTPS 白名单(仅 Unity 官方 CDN),校验固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹,临时文件原子更名为最终文件。
90
+ 3. 按路由下载固定版本的 `com.unity.pipeline` tgz:固定 SHA-256(主)+ SHA-1(交叉),安全解包(解包前逐项拒绝绝对路径、`..`、符号/硬链接等非常规条目)。
91
+ 4. 在**用户缓存**中确定性转换:`package.json` 最低 Unity 版本、`PhysicsMaterial` 兼容、`rawRenderQueue` 读取兼容、Roslyn DLL 的 `.meta` 转为 Unity 2022 格式(保留 GUID)、删除 `Tests` 源码与失效签名文件;输出必须与 `routes/expected-tree/*.json`(含 `Tests.meta` 共 385 个文件)逐字节一致。
92
+ 5. 事务式安装到 `Packages/com.unity.pipeline`:staging → 校验 → 备份 → 替换 → 再校验 → receipt;任一步失败自动回滚。运行中的 Unity Editor 会 fail-closed 阻止安装。
93
+ 6. `exec` 每次调用前重新校验 CLI 哈希,并**禁止任何 `--project-path` 变体覆盖目标工程**。
94
+
95
+ > **缓存目录说明**:用户缓存默认为 `%LOCALAPPDATA%\editor-pipeline-cli`;该目录名沿用历史名称,以避免破坏已通过验证的缓存/收据契约。工程内的安装事务目录 `Library/editor-pipeline-cli` 同理保留。这两个目录名与 npm 包名 `@kevlns/u-cli-mod` 无关,属于兼容性保留项。
96
+
97
+ ## 本仓库/包 与 不包含
98
+
99
+ - ✅ 只包含本工具自己的 TypeScript 代码、版本路由元数据与哈希清单。
100
+ - ✅ Unity CLI 与 `com.unity.pipeline` 在**运行时**从 Unity 官方地址下载到**用户缓存**。
101
+ - ❌ 仓库和 npm 包**不包含**任何 Unity 二进制(`.exe`/`.dll`)、tgz 或 `com.unity.pipeline` 源码。
102
+ - ❌ 无 `postinstall`;安装 npm 包不会下载或修改任何工程。
82
103
 
83
104
  ## 质量与 CI
84
105
 
85
106
  ### 单元测试与打包守卫
86
107
 
87
108
  ```bash
88
- npm run check # build + lint + 107 个 vitest 测试 + pack guard
109
+ npm run check # build + lint + 110 个 vitest 测试 + pack guard
89
110
  ```
90
111
 
91
112
  `pack:guard` 会执行真实 `npm pack`(含文件清单校验),断言发布包:
92
113
 
93
- - 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.0.tgz`(与 package.json 版本一致);
114
+ - 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.2.tgz`(与 package.json 版本一致);
94
115
  - `files` 必须包含 `v-cli.plugin.json`,且清单身份字段(schemaVersion/package/command/bin/platforms)与包一致;
95
116
  - 不出现:
96
117
 
@@ -110,9 +131,7 @@ npm run check # build + lint + 107 个 vitest 测试 + pack guard
110
131
  npm run test:package
111
132
  ```
112
133
 
113
- 构建真实 tgz,并在本地验证三种消费方式:工程 devDependency(`node_modules/.bin`)、
114
- 带临时 `--prefix` 的全局安装、`npx --package <本地tgz>`;每种都执行 `u-cli-mod --version` 与
115
- `u-cli-mod routes`。**不会**向任何 registry 发布。报告:`C:/tmp/u-cli-mod-package-test-report.json`。
134
+ 构建真实 tgz,并在本地验证三种消费方式:工程 devDependency(`node_modules/.bin`)、带临时 `--prefix` 的全局安装、`npx --package <本地tgz>`;每种都执行 `u-cli-mod --version` 与 `u-cli-mod routes`。**不会**向任何 registry 发布。报告:`<临时目录>/u-cli-mod-package-test-report.json`(可用 `EPC_PKG_REPORT` 覆盖)。
116
135
 
117
136
  ### 自托管 Runner 与 Unity E2E
118
137
 
@@ -122,7 +141,7 @@ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命
122
141
  ```
123
142
 
124
143
  - `preflight:runner` 只读,不下载/注册 Runner;结果 JSON 输出到 stdout。
125
- - `e2e:windows` 使用**隔离缓存**(干净环境)或显式复用已验证缓存,创建 `C:/tmp/u-cli-mod-e2e/` 下独立临时工程,全部结束后杀掉它启动的所有 Unity 进程并清理临时工程;报告写入 `C:/tmp/u-cli-mod-e2e-report.json`。
144
+ - `e2e:windows` 使用**隔离缓存**(干净环境)或显式复用已验证缓存,创建 `<临时目录>/u-cli-mod-e2e/` 下独立临时工程,全部结束后杀掉它启动的所有 Unity 进程并清理临时工程;报告写入 `<临时目录>/u-cli-mod-e2e-report.json`(分别可用 `EPC_E2E_ROOT`、`EPC_E2E_REPORT` 覆盖)。
126
145
  - 验收指标:200 次只读调用 100% 成功并记录 P50/P95、20 轮资源修改、5 次 Domain Reload 首次恢复、强杀重启恢复、双工程显式路由 60 次无误选、运行中 Editor 防护与 `--project-path` 覆盖拒绝。
127
146
 
128
147
  详细说明见 `docs/SELF_HOSTED_RUNNER.md`。
@@ -132,7 +151,7 @@ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命
132
151
  - `.github/workflows/ci.yml`:hosted windows runner 上跑 `npm ci` + `npm run check` + `npm audit --omit=dev` + 禁用扩展名扫描;push/PR 触发。
133
152
  - `.github/workflows/e2e-windows.yml`:**self-hosted** runner(标签 `self-hosted/windows/unity-2022.3.62f3c1`)上跑 Unity E2E;仅 `workflow_dispatch` 与受保护 `v*` tag 触发,不跑 pull_request,不发布;权限最小化(contents: read);产物 `u-cli-mod-e2e-report`。
134
153
 
135
- ## 支持的路由
154
+ ## Routes
136
155
 
137
156
  | Editor | Revision | CLI | Pipeline | 状态 |
138
157
  |---|---|---|---|---|
@@ -154,6 +173,38 @@ scripts/ pack-guard / preflight-runner / e2e-windows / test-package-inst
154
173
  .github/workflows/ hosted CI + self-hosted E2E
155
174
  ```
156
175
 
157
- ## 许可
176
+ ## Package family
177
+
178
+ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
179
+
180
+ | Package | Purpose | Status |
181
+ | --- | --- | --- |
182
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.1 |
183
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.2 |
184
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first,本仓库) | v0.1.2 |
185
+
186
+ ## Compatibility
187
+
188
+ | Runtime | Supported versions |
189
+ | --- | --- |
190
+ | Node.js | `20` and later |
191
+ | Unity Editor | `2022.3.62f3c1` / `2022.3.59f1c1`(精确路由,见 Routes) |
192
+
193
+ ## Contributing
194
+
195
+ ```bash
196
+ npm ci
197
+ npm run check # build + lint + test + pack:guard 一键
198
+ ```
199
+
200
+ For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/u-cli-mod/issues).
201
+
202
+ ## License
203
+
204
+ 本工具代码为 MIT(见 LICENSE)。运行时下载的 Unity CLI 与 `com.unity.pipeline` 归其各自的 Unity 许可(如 Unity Package Distribution License)约束,不在本仓库/包内分发。本工具与 Unity 无关,非官方项目。
205
+
206
+ <div align="center">
207
+
208
+ Part of the **kevlns** tool family.
158
209
 
159
- 本工具代码为 MIT(见 LICENSE)。运行时下载的 Unity CLI 与 `com.unity.pipeline` 归其各自的 Unity 许可(如 Unity Package Distribution License)约束,不在本仓库/包内分发。本工具与 Unity 无关,非官方项目。
210
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kevlns/u-cli-mod",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "u-cli-mod: pin exact Unity Editor version routes and install the adapted com.unity.pipeline package for Unity 2022 (Windows-first). Downloads Unity assets at runtime into the user cache; the package itself contains no Unity binaries or package source. Not an official Unity project.",
5
5
  "private": false,
6
6
  "publishConfig": {