@kevlns/u-cli-mod 0.1.0 → 0.1.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 (2) hide show
  1. package/README.md +89 -40
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,53 +1,56 @@
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?
23
+
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
26
33
 
27
- ## 安装与构建
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
51
54
 
52
55
  ```bash
53
56
  # 只读检查工程与路由
@@ -78,19 +81,35 @@ u-cli-mod cache clean
78
81
 
79
82
  `exec` 会把 `--project-path <工程>` 追加到 Unity CLI 参数末尾;传入任何形式的 `--project-path`(含 `-projectPath`、`--projectPath`、大小写混合)会直接报错。
80
83
 
81
- 已发布正式版,可直接使用 `npm install -g @kevlns/u-cli-mod`,或用 `npx --package @kevlns/u-cli-mod u-cli-mod ...`。
84
+ ## 原理
85
+
86
+ 1. 读取目标工程 `ProjectSettings/ProjectVersion.txt`,要求 `m_EditorVersion` 与 `m_EditorVersionWithRevision` **同时存在且与路由完全一致**(fail-closed,无通配、无“最近版本”回退)。
87
+ 2. 按路由下载固定版本的 Unity CLI:HTTPS 白名单(仅 Unity 官方 CDN),校验固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹,临时文件原子更名为最终文件。
88
+ 3. 按路由下载固定版本的 `com.unity.pipeline` tgz:固定 SHA-256(主)+ SHA-1(交叉),安全解包(解包前逐项拒绝绝对路径、`..`、符号/硬链接等非常规条目)。
89
+ 4. 在**用户缓存**中确定性转换:`package.json` 最低 Unity 版本、`PhysicsMaterial` 兼容、`rawRenderQueue` 读取兼容、Roslyn DLL 的 `.meta` 转为 Unity 2022 格式(保留 GUID)、删除 `Tests` 源码与失效签名文件;输出必须与 `routes/expected-tree/*.json`(含 `Tests.meta` 共 385 个文件)逐字节一致。
90
+ 5. 事务式安装到 `Packages/com.unity.pipeline`:staging → 校验 → 备份 → 替换 → 再校验 → receipt;任一步失败自动回滚。运行中的 Unity Editor 会 fail-closed 阻止安装。
91
+ 6. `exec` 每次调用前重新校验 CLI 哈希,并**禁止任何 `--project-path` 变体覆盖目标工程**。
92
+
93
+ > **缓存目录说明**:用户缓存默认为 `%LOCALAPPDATA%\editor-pipeline-cli`;该目录名沿用历史名称,以避免破坏已通过验证的缓存/收据契约。工程内的安装事务目录 `Library/editor-pipeline-cli` 同理保留。这两个目录名与 npm 包名 `@kevlns/u-cli-mod` 无关,属于兼容性保留项。
94
+
95
+ ## 本仓库/包 与 不包含
96
+
97
+ - ✅ 只包含本工具自己的 TypeScript 代码、版本路由元数据与哈希清单。
98
+ - ✅ Unity CLI 与 `com.unity.pipeline` 在**运行时**从 Unity 官方地址下载到**用户缓存**。
99
+ - ❌ 仓库和 npm 包**不包含**任何 Unity 二进制(`.exe`/`.dll`)、tgz 或 `com.unity.pipeline` 源码。
100
+ - ❌ 无 `postinstall`;安装 npm 包不会下载或修改任何工程。
82
101
 
83
102
  ## 质量与 CI
84
103
 
85
104
  ### 单元测试与打包守卫
86
105
 
87
106
  ```bash
88
- npm run check # build + lint + 107 个 vitest 测试 + pack guard
107
+ npm run check # build + lint + 110 个 vitest 测试 + pack guard
89
108
  ```
90
109
 
91
110
  `pack:guard` 会执行真实 `npm pack`(含文件清单校验),断言发布包:
92
111
 
93
- - 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.0.tgz`(与 package.json 版本一致);
112
+ - 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.1.tgz`(与 package.json 版本一致);
94
113
  - `files` 必须包含 `v-cli.plugin.json`,且清单身份字段(schemaVersion/package/command/bin/platforms)与包一致;
95
114
  - 不出现:
96
115
 
@@ -110,9 +129,7 @@ npm run check # build + lint + 107 个 vitest 测试 + pack guard
110
129
  npm run test:package
111
130
  ```
112
131
 
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`。
132
+ 构建真实 tgz,并在本地验证三种消费方式:工程 devDependency(`node_modules/.bin`)、带临时 `--prefix` 的全局安装、`npx --package <本地tgz>`;每种都执行 `u-cli-mod --version` 与 `u-cli-mod routes`。**不会**向任何 registry 发布。报告:`C:/tmp/u-cli-mod-package-test-report.json`。
116
133
 
117
134
  ### 自托管 Runner 与 Unity E2E
118
135
 
@@ -132,7 +149,7 @@ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命
132
149
  - `.github/workflows/ci.yml`:hosted windows runner 上跑 `npm ci` + `npm run check` + `npm audit --omit=dev` + 禁用扩展名扫描;push/PR 触发。
133
150
  - `.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
151
 
135
- ## 支持的路由
152
+ ## Routes
136
153
 
137
154
  | Editor | Revision | CLI | Pipeline | 状态 |
138
155
  |---|---|---|---|---|
@@ -154,6 +171,38 @@ scripts/ pack-guard / preflight-runner / e2e-windows / test-package-inst
154
171
  .github/workflows/ hosted CI + self-hosted E2E
155
172
  ```
156
173
 
157
- ## 许可
174
+ ## Package family
175
+
176
+ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
177
+
178
+ | Package | Purpose | Status |
179
+ | --- | --- | --- |
180
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.1 |
181
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.2 |
182
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first,本仓库) | v0.1.1 |
183
+
184
+ ## Compatibility
185
+
186
+ | Runtime | Supported versions |
187
+ | --- | --- |
188
+ | Node.js | `20` and later |
189
+ | Unity Editor | `2022.3.62f3c1` / `2022.3.59f1c1`(精确路由,见 Routes) |
190
+
191
+ ## Contributing
192
+
193
+ ```bash
194
+ npm ci
195
+ npm run check # build + lint + test + pack:guard 一键
196
+ ```
197
+
198
+ For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/u-cli-mod/issues).
199
+
200
+ ## License
201
+
202
+ 本工具代码为 MIT(见 LICENSE)。运行时下载的 Unity CLI 与 `com.unity.pipeline` 归其各自的 Unity 许可(如 Unity Package Distribution License)约束,不在本仓库/包内分发。本工具与 Unity 无关,非官方项目。
203
+
204
+ <div align="center">
205
+
206
+ Part of the **kevlns** tool family.
158
207
 
159
- 本工具代码为 MIT(见 LICENSE)。运行时下载的 Unity CLI 与 `com.unity.pipeline` 归其各自的 Unity 许可(如 Unity Package Distribution License)约束,不在本仓库/包内分发。本工具与 Unity 无关,非官方项目。
208
+ </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.1",
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": {