@kevlns/u-cli-mod 0.1.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 (51) hide show
  1. package/LICENSE +30 -0
  2. package/README.md +152 -0
  3. package/dist/authenticode.d.ts +13 -0
  4. package/dist/authenticode.js +72 -0
  5. package/dist/cli.d.ts +4 -0
  6. package/dist/cli.js +142 -0
  7. package/dist/commands/cacheClean.d.ts +7 -0
  8. package/dist/commands/cacheClean.js +13 -0
  9. package/dist/commands/cliInstall.d.ts +14 -0
  10. package/dist/commands/cliInstall.js +20 -0
  11. package/dist/commands/doctor.d.ts +22 -0
  12. package/dist/commands/doctor.js +41 -0
  13. package/dist/commands/exec.d.ts +14 -0
  14. package/dist/commands/exec.js +48 -0
  15. package/dist/commands/pipelineInstall.d.ts +17 -0
  16. package/dist/commands/pipelineInstall.js +19 -0
  17. package/dist/commands/routesCmd.d.ts +11 -0
  18. package/dist/commands/routesCmd.js +17 -0
  19. package/dist/commands/setup.d.ts +10 -0
  20. package/dist/commands/setup.js +21 -0
  21. package/dist/config.d.ts +12 -0
  22. package/dist/config.js +42 -0
  23. package/dist/download.d.ts +26 -0
  24. package/dist/download.js +110 -0
  25. package/dist/ensure.d.ts +25 -0
  26. package/dist/ensure.js +102 -0
  27. package/dist/errors.d.ts +4 -0
  28. package/dist/errors.js +8 -0
  29. package/dist/index.d.ts +12 -0
  30. package/dist/index.js +10 -0
  31. package/dist/installer.d.ts +24 -0
  32. package/dist/installer.js +141 -0
  33. package/dist/integrity.d.ts +36 -0
  34. package/dist/integrity.js +84 -0
  35. package/dist/paths.d.ts +7 -0
  36. package/dist/paths.js +21 -0
  37. package/dist/pipeline.d.ts +19 -0
  38. package/dist/pipeline.js +139 -0
  39. package/dist/projectVersion.d.ts +16 -0
  40. package/dist/projectVersion.js +44 -0
  41. package/dist/routes.d.ts +40 -0
  42. package/dist/routes.js +81 -0
  43. package/dist/transform.d.ts +17 -0
  44. package/dist/transform.js +178 -0
  45. package/dist/unityGuard.d.ts +23 -0
  46. package/dist/unityGuard.js +55 -0
  47. package/package.json +66 -0
  48. package/routes/2022.3.62f3c1.json +28 -0
  49. package/routes/expected-tree/2022.3.62f3c1.json +391 -0
  50. package/templates/2022.3.62f3c1/dll-importer-body.txt +31 -0
  51. package/templates/2022.3.62f3c1/mono-importer-body.txt +9 -0
package/LICENSE ADDED
@@ -0,0 +1,30 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kevlns
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ Notice: this tool (u-cli-mod) downloads the Unity Editor CLI binary and the
26
+ com.unity.pipeline package from Unity's official endpoints at runtime and
27
+ applies compatibility patches locally. Those downloaded assets are governed by
28
+ their own license terms (Unity Package Distribution License and Unity CLI
29
+ terms). They are NOT distributed with this package and never land in this
30
+ repository. This MIT license covers only the tool code in this repository.
package/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # u-cli-mod
2
+
3
+ 按 **精确 Unity Editor 版本**路由、下载并安装 Unity CLI 与适配后 `com.unity.pipeline` 的命令行工具(**Windows-first**)。
4
+
5
+ - 仓库:<https://github.com/kevlns/u-cli-mod>
6
+ - npm 包:`@kevlns/u-cli-mod`(当前为 beta 预发布版本)
7
+ - **这不是 Unity 官方项目**,与 Unity Technologies 无隶属关系;`com.unity.pipeline` 的 Unity 2022 适配属于非官方移植。
8
+
9
+ ## 本仓库/包 与 不包含
10
+
11
+ - ✅ 只包含本工具自己的 TypeScript 代码、版本路由元数据与哈希清单。
12
+ - ✅ Unity CLI 与 `com.unity.pipeline` 在**运行时**从 Unity 官方地址下载到**用户缓存**。
13
+ - ❌ 仓库和 npm 包**不包含**任何 Unity 二进制(`.exe`/`.dll`)、tgz 或 `com.unity.pipeline` 源码。
14
+ - ❌ 无 `postinstall`;安装 npm 包不会下载或修改任何工程。
15
+
16
+ ## 原理
17
+
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` 变体覆盖目标工程**。
24
+
25
+ > **缓存目录说明**:用户缓存默认为 `%LOCALAPPDATA%\editor-pipeline-cli`;该目录名沿用历史名称,以避免破坏已通过验证的缓存/收据契约。工程内的安装事务目录 `Library/editor-pipeline-cli` 同理保留。这两个目录名与 npm 包名 `@kevlns/u-cli-mod` 无关,属于兼容性保留项。
26
+
27
+ ## 安装与构建
28
+
29
+ ```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 一键
36
+ ```
37
+
38
+ 要求 Node.js >= 20(Windows 10+)。
39
+
40
+ ## 使用
41
+
42
+ 安装 beta 版本:
43
+
44
+ ```bash
45
+ npm install --global @kevlns/u-cli-mod@beta
46
+ # 或不安装,直接运行:
47
+ npx --package @kevlns/u-cli-mod@beta u-cli-mod routes
48
+ ```
49
+
50
+ 常用命令:
51
+
52
+ ```bash
53
+ # 只读检查工程与路由
54
+ u-cli-mod doctor C:\Projects\Debussy\debussy-client
55
+
56
+ # 列出支持的 Editor 路由
57
+ u-cli-mod routes
58
+
59
+ # 下载固定版本 CLI(SHA-256 + Authenticode)
60
+ u-cli-mod cli install
61
+
62
+ # 预览 Pipeline 安装(不写入)
63
+ u-cli-mod pipeline install C:\Projects\Debussy\debussy-client --dry-run
64
+
65
+ # 正式安装(先关闭目标工程的 Unity Editor)
66
+ u-cli-mod pipeline install C:\Projects\Debussy\debussy-client
67
+
68
+ # CLI + Pipeline 一键准备
69
+ u-cli-mod setup C:\Projects\Debussy\debussy-client
70
+
71
+ # 执行 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
74
+
75
+ # 清理缓存
76
+ u-cli-mod cache clean
77
+ ```
78
+
79
+ `exec` 会把 `--project-path <工程>` 追加到 Unity CLI 参数末尾;传入任何形式的 `--project-path`(含 `-projectPath`、`--projectPath`、大小写混合)会直接报错。
80
+
81
+ beta 阶段请显式使用 `@kevlns/u-cli-mod@beta`;发布稳定版并设置 `latest` 标签后,可使用 `npx --package @kevlns/u-cli-mod u-cli-mod ...`。
82
+
83
+ ## 质量与 CI
84
+
85
+ ### 单元测试与打包守卫
86
+
87
+ ```bash
88
+ npm run check # build + lint + 94 个 vitest 测试 + pack guard
89
+ ```
90
+
91
+ `pack:guard` 会执行真实 `npm pack`(含文件清单校验),断言发布包:
92
+
93
+ - 包名为 `@kevlns/u-cli-mod`、tgz 文件名为 `kevlns-u-cli-mod-*`;
94
+ - 不出现:
95
+
96
+ ```text
97
+ *.exe *.dll *.tgz *.pdb
98
+ *.cs *.unity *.asmdef *.prefab *.asset
99
+ 完整 com.unity.pipeline 目录树
100
+ ```
101
+
102
+ ### 本地 tarball 安装矩阵(三模式验证)
103
+
104
+ ```bash
105
+ npm run test:package
106
+ ```
107
+
108
+ 构建真实 tgz,并在本地验证三种消费方式:工程 devDependency(`node_modules/.bin`)、
109
+ 带临时 `--prefix` 的全局安装、`npx --package <本地tgz>`;每种都执行 `u-cli-mod --version` 与
110
+ `u-cli-mod routes`。**不会**向任何 registry 发布。报告:`C:/tmp/u-cli-mod-package-test-report.json`。
111
+
112
+ ### 自托管 Runner 与 Unity E2E
113
+
114
+ ```bash
115
+ npm run preflight:runner # 注册前环境预检(Node/npm/Git/Unity 版本/revision/许可证探针)
116
+ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命令/重载/重启/多编辑器)
117
+ ```
118
+
119
+ - `preflight:runner` 只读,不下载/注册 Runner;结果 JSON 输出到 stdout。
120
+ - `e2e:windows` 使用**隔离缓存**(干净环境)或显式复用已验证缓存,创建 `C:/tmp/u-cli-mod-e2e/` 下独立临时工程,全部结束后杀掉它启动的所有 Unity 进程并清理临时工程;报告写入 `C:/tmp/u-cli-mod-e2e-report.json`。
121
+ - 验收指标:200 次只读调用 100% 成功并记录 P50/P95、20 轮资源修改、5 次 Domain Reload 首次恢复、强杀重启恢复、双工程显式路由 60 次无误选、运行中 Editor 防护与 `--project-path` 覆盖拒绝。
122
+
123
+ 详细说明见 `docs/SELF_HOSTED_RUNNER.md`。
124
+
125
+ ### GitHub Actions
126
+
127
+ - `.github/workflows/ci.yml`:hosted windows runner 上跑 `npm ci` + `npm run check` + `npm audit --omit=dev` + 禁用扩展名扫描;push/PR 触发。
128
+ - `.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`。
129
+
130
+ ## 支持的路由
131
+
132
+ | Editor | Revision | CLI | Pipeline | 状态 |
133
+ |---|---|---|---|---|
134
+ | `2022.3.62f3c1` | `1623fc0bbb97` | `1.0.0-beta.2` | `0.5.0-exp.1`(适配版) | 已验证(非官方移植) |
135
+
136
+ 新增 Editor 版本时必须:新增 `routes/<版本>.json` 与 `routes/expected-tree/<版本>.json`、对应转换模板与补丁规则,并在该版本 Unity 上重新完成编译与回归测试。不得让相近版本复用既有路由。
137
+
138
+ ## 目录
139
+
140
+ ```text
141
+ routes/ 精确版本路由 + expected-tree 哈希清单
142
+ routes/expected-tree/ 385 文件 SHA-256 清单(含 Tests.meta)
143
+ templates/ Unity 生成的 .meta 模板(数据,非 Unity 源码)
144
+ src/ TypeScript 实现
145
+ tests/ Vitest 单元测试(自编合成 fixture,不含 Unity 源码)
146
+ scripts/ pack-guard / preflight-runner / e2e-windows / test-package-install
147
+ .github/workflows/ hosted CI + self-hosted E2E
148
+ ```
149
+
150
+ ## 许可
151
+
152
+ 本工具代码为 MIT(见 LICENSE)。运行时下载的 Unity CLI 与 `com.unity.pipeline` 归其各自的 Unity 许可(如 Unity Package Distribution License)约束,不在本仓库/包内分发。本工具与 Unity 无关,非官方项目。
@@ -0,0 +1,13 @@
1
+ export interface AuthenticodeResult {
2
+ status: string;
3
+ statusMessage: string;
4
+ subject: string;
5
+ thumbprint: string;
6
+ notBefore: string;
7
+ notAfter: string;
8
+ sha256: string;
9
+ }
10
+ /** Verify Authenticode: status Valid + signer subject contains expected + thumbprint matches. */
11
+ export declare function verifyAuthenticode(file: string, expectedSubjectContains: string, expectedThumbprint: string, { powershell }?: {
12
+ powershell?: string;
13
+ }): Promise<AuthenticodeResult>;
@@ -0,0 +1,72 @@
1
+ import { execFile } from 'node:child_process';
2
+ import { promisify } from 'node:util';
3
+ import { CliError } from './errors.js';
4
+ const execFileAsync = promisify(execFile);
5
+ const SCRIPT_HEAD = String.raw `$p = `;
6
+ const SCRIPT_TAIL = String.raw `
7
+ $s = Get-AuthenticodeSignature -LiteralPath $p
8
+ [pscustomobject]@{
9
+ Status = $s.Status.ToString()
10
+ StatusMessage = $s.StatusMessage
11
+ Subject = if ($s.SignerCertificate) { $s.SignerCertificate.Subject } else { $null }
12
+ Thumbprint = if ($s.SignerCertificate) { $s.SignerCertificate.Thumbprint } else { $null }
13
+ NotBefore = if ($s.SignerCertificate) { $s.SignerCertificate.NotBefore.ToString('o') } else { $null }
14
+ NotAfter = if ($s.SignerCertificate) { $s.SignerCertificate.NotAfter.ToString('o') } else { $null }
15
+ Sha256 = (Get-FileHash -LiteralPath $p -Algorithm SHA256).Hash.ToLowerInvariant()
16
+ } | ConvertTo-Json -Compress
17
+ `;
18
+ /** PowerShell -EncodedCommand payload: script with the target path embedded. */
19
+ function encodedCommand(file) {
20
+ // Path is embedded directly (single-quoted, ''-escaped) instead of a param
21
+ // block: `param()` in a -Command/-EncodedCommand script only binds from the
22
+ // process command line, not from text appended inside the script.
23
+ const script = `${SCRIPT_HEAD}'${file.replace(/'/g, "''")}'${SCRIPT_TAIL}`.replace(/\r?\n/g, '\r\n');
24
+ // UTF-16LE base64 is what PowerShell's -EncodedCommand expects.
25
+ const encoded = Buffer.from(script, 'utf16le').toString('base64');
26
+ return { script, encoded };
27
+ }
28
+ /** Verify Authenticode: status Valid + signer subject contains expected + thumbprint matches. */
29
+ export async function verifyAuthenticode(file, expectedSubjectContains, expectedThumbprint, { powershell = 'powershell.exe' } = {}) {
30
+ let stdout;
31
+ try {
32
+ const { encoded } = encodedCommand(file);
33
+ const result = await execFileAsync(powershell, [
34
+ '-NoProfile',
35
+ '-NonInteractive',
36
+ '-ExecutionPolicy',
37
+ 'Bypass',
38
+ '-EncodedCommand',
39
+ encoded,
40
+ ], { maxBuffer: 4 * 1024 * 1024, timeout: 120_000, windowsHide: true });
41
+ stdout = result.stdout;
42
+ }
43
+ catch (err) {
44
+ throw new CliError(`无法执行 Authenticode 校验(需要 Windows PowerShell):${err instanceof Error ? err.message : String(err)}`);
45
+ }
46
+ let result;
47
+ try {
48
+ const parsed = JSON.parse(stdout.trim());
49
+ result = {
50
+ status: String(parsed.Status ?? ''),
51
+ statusMessage: String(parsed.StatusMessage ?? ''),
52
+ subject: String(parsed.Subject ?? ''),
53
+ thumbprint: String(parsed.Thumbprint ?? ''),
54
+ notBefore: String(parsed.NotBefore ?? ''),
55
+ notAfter: String(parsed.NotAfter ?? ''),
56
+ sha256: String(parsed.Sha256 ?? ''),
57
+ };
58
+ }
59
+ catch {
60
+ throw new CliError(`Authenticode 校验输出无法解析:${stdout.slice(0, 300)}`);
61
+ }
62
+ if (result.status !== 'Valid') {
63
+ throw new CliError(`CLI Authenticode 无效:${result.status} ${result.statusMessage}`);
64
+ }
65
+ if (!result.subject.includes(expectedSubjectContains)) {
66
+ throw new CliError(`CLI 签名主体不匹配。期望包含 "${expectedSubjectContains}",实际 "${result.subject}"`);
67
+ }
68
+ if (result.thumbprint.toLowerCase() !== expectedThumbprint.toLowerCase()) {
69
+ throw new CliError(`CLI 签名证书指纹不匹配。期望 ${expectedThumbprint},实际 ${result.thumbprint}`);
70
+ }
71
+ return result;
72
+ }
package/dist/cli.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { Command } from 'commander';
3
+ export declare function buildProgram(): Command;
4
+ export declare function main(argv: string[]): Promise<number>;
package/dist/cli.js ADDED
@@ -0,0 +1,142 @@
1
+ #!/usr/bin/env node
2
+ import { Command } from 'commander';
3
+ import { CliError } from './errors.js';
4
+ import { runDoctor } from './commands/doctor.js';
5
+ import { runRoutes } from './commands/routesCmd.js';
6
+ import { runCliInstall } from './commands/cliInstall.js';
7
+ import { runPipelineInstall } from './commands/pipelineInstall.js';
8
+ import { runSetup } from './commands/setup.js';
9
+ import { runExec } from './commands/exec.js';
10
+ import { runCacheClean } from './commands/cacheClean.js';
11
+ import { readFileSync } from 'node:fs';
12
+ import { join, dirname } from 'node:path';
13
+ import { fileURLToPath, pathToFileURL } from 'node:url';
14
+ function packageVersion() {
15
+ try {
16
+ const root = join(dirname(fileURLToPath(import.meta.url)), '..');
17
+ const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
18
+ return pkg.version ?? '0.0.0';
19
+ }
20
+ catch {
21
+ return '0.0.0';
22
+ }
23
+ }
24
+ function printJson(value) {
25
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
26
+ }
27
+ export function buildProgram() {
28
+ const program = new Command();
29
+ program
30
+ .name('u-cli-mod')
31
+ .description('按精确 Unity Editor 版本路由、下载并安装 Unity CLI 与适配后的 com.unity.pipeline(Windows-first,非 Unity 官方项目)')
32
+ .version(packageVersion())
33
+ // Required so `exec` can use passThroughOptions (args after the project
34
+ // positional are passed verbatim to the routed Unity CLI).
35
+ .enablePositionalOptions(true);
36
+ program
37
+ .command('doctor <project>')
38
+ .description('检查工程版本、路由、CLI 与 Pipeline 状态')
39
+ .option('--allow-running-editor', '允许查询运行中的 Editor 时不失败')
40
+ .action(async (project, opts) => {
41
+ const result = await runDoctor(project, { allowRunningEditor: opts.allowRunningEditor });
42
+ printJson(result);
43
+ });
44
+ program
45
+ .command('routes')
46
+ .description('列出所有已配置的 Editor 精确路由')
47
+ .option('-e, --editor <version>', '只显示指定版本')
48
+ .action((opts) => {
49
+ printJson(runRoutes(opts.editor));
50
+ });
51
+ const cliCmd = program
52
+ .command('cli')
53
+ .description('下载并校验固定版本的 Unity CLI(SHA-256 + Authenticode)');
54
+ cliCmd
55
+ .command('install')
56
+ .description('下载并校验固定版本的 Unity CLI(SHA-256 + Authenticode)')
57
+ .option('--editor <version>', '限定 Editor 版本,默认全部路由')
58
+ .option('--force', '强制重新下载')
59
+ .action(async (opts) => {
60
+ printJson(await runCliInstall({ editorVersion: opts.editor, force: opts.force }));
61
+ });
62
+ const pipelineCmd = program
63
+ .command('pipeline')
64
+ .description('按工程 Editor 版本事务式安装适配后的 com.unity.pipeline');
65
+ pipelineCmd
66
+ .command('install <project>')
67
+ .description('按工程 Editor 版本事务式安装适配后的 com.unity.pipeline')
68
+ .option('--force', '覆盖现有不一致的包(先备份)')
69
+ .option('--allow-running-editor', '跳过运行中 Editor 的 fail-closed 保护')
70
+ .option('--dry-run', '只校验与预览,不写入工程')
71
+ .action(async (project, opts) => {
72
+ printJson(await runPipelineInstall(project, {
73
+ force: opts.force,
74
+ allowRunningEditor: opts.allowRunningEditor,
75
+ dryRun: opts.dryRun,
76
+ }));
77
+ });
78
+ program
79
+ .command('setup <project>')
80
+ .description('cli install + pipeline install')
81
+ .option('--force', '覆盖现有不一致的包')
82
+ .option('--allow-running-editor', '跳过运行中 Editor 的 fail-closed 保护')
83
+ .option('--dry-run', '只校验与预览,不写入工程')
84
+ .option('--skip-cli', '跳过 CLI 下载')
85
+ .action(async (project, opts) => {
86
+ printJson(await runSetup(project, {
87
+ force: opts.force,
88
+ allowRunningEditor: opts.allowRunningEditor,
89
+ dryRun: opts.dryRun,
90
+ skipCli: opts.skipCli,
91
+ }));
92
+ });
93
+ const execCmd = program
94
+ .command('exec <project>')
95
+ .description('调用路由 CLI 执行 Unity Pipeline 命令;--project-path 由工具统一绑定')
96
+ .option('--download-if-missing', 'CLI 缺失时自动下载')
97
+ .allowUnknownOption(true)
98
+ .allowExcessArguments(true)
99
+ .passThroughOptions(true);
100
+ execCmd.action(async (project, opts, command) => {
101
+ const extra = command.args.slice(1);
102
+ const { exitCode } = await runExec(project, extra, {
103
+ downloadIfMissing: opts.downloadIfMissing,
104
+ });
105
+ process.exitCode = exitCode;
106
+ });
107
+ const cacheCmd = program
108
+ .command('cache')
109
+ .description('清理下载缓存与生成的适配包');
110
+ cacheCmd
111
+ .command('clean')
112
+ .description('清理下载缓存与生成的适配包')
113
+ .option('--all', '连 CLI 缓存一起清理')
114
+ .action(async (opts) => {
115
+ printJson(await runCacheClean({ all: opts.all }));
116
+ });
117
+ return program;
118
+ }
119
+ export async function main(argv) {
120
+ const program = buildProgram();
121
+ try {
122
+ await program.parseAsync(argv);
123
+ return typeof process.exitCode === 'number' ? process.exitCode : 0;
124
+ }
125
+ catch (err) {
126
+ if (err instanceof CliError) {
127
+ process.stderr.write(`error: ${err.message}\n`);
128
+ return err.exitCode;
129
+ }
130
+ process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
131
+ return 1;
132
+ }
133
+ }
134
+ if (process.argv[1] &&
135
+ import.meta.url === pathToFileURL(process.argv[1]).href) {
136
+ main(process.argv).then((code) => {
137
+ process.exitCode = code;
138
+ }, (err) => {
139
+ process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
140
+ process.exitCode = 1;
141
+ });
142
+ }
@@ -0,0 +1,7 @@
1
+ export interface CacheCleanOptions {
2
+ all?: boolean;
3
+ }
4
+ export declare function runCacheClean(options?: CacheCleanOptions): Promise<{
5
+ cacheRoot: string;
6
+ removed: string[];
7
+ }>;
@@ -0,0 +1,13 @@
1
+ import { rm } from 'node:fs/promises';
2
+ import { cacheRoot, cliCacheDir, pipelineCacheDir, generatedDir, logsDir } from '../config.js';
3
+ export async function runCacheClean(options = {}) {
4
+ const removed = [];
5
+ const targets = options.all
6
+ ? [cliCacheDir(), pipelineCacheDir(), generatedDir(), logsDir()]
7
+ : [generatedDir(), pipelineCacheDir()];
8
+ for (const dir of targets) {
9
+ await rm(dir, { recursive: true, force: true });
10
+ removed.push(dir);
11
+ }
12
+ return { cacheRoot: cacheRoot(), removed };
13
+ }
@@ -0,0 +1,14 @@
1
+ export interface CliInstallOptions {
2
+ editorVersion?: string;
3
+ force?: boolean;
4
+ }
5
+ export declare function runCliInstall(options?: CliInstallOptions): Promise<{
6
+ cacheDir: string;
7
+ results: {
8
+ editorVersion: string;
9
+ cliVersion: string;
10
+ path: string;
11
+ state: "valid" | "downloaded";
12
+ sha256: string;
13
+ }[];
14
+ }>;
@@ -0,0 +1,20 @@
1
+ import { ensureCliBinary } from '../ensure.js';
2
+ import { loadRoute, listEditorVersions } from '../routes.js';
3
+ import { ensureCacheLayout, cliCacheDir } from '../config.js';
4
+ export async function runCliInstall(options = {}) {
5
+ ensureCacheLayout();
6
+ const versions = options.editorVersion ? [options.editorVersion] : listEditorVersions();
7
+ const results = [];
8
+ for (const version of versions) {
9
+ const route = loadRoute(version);
10
+ const result = await ensureCliBinary(route.cli, { force: options.force });
11
+ results.push({
12
+ editorVersion: version,
13
+ cliVersion: route.cli.version,
14
+ path: result.path,
15
+ state: result.state,
16
+ sha256: result.sha256,
17
+ });
18
+ }
19
+ return { cacheDir: cliCacheDir(), results };
20
+ }
@@ -0,0 +1,22 @@
1
+ export interface DoctorOptions {
2
+ allowRunningEditor?: boolean;
3
+ }
4
+ export declare function runDoctor(projectPath: string, options?: DoctorOptions): Promise<{
5
+ projectPath: string;
6
+ editorVersion: string;
7
+ editorRevision: string | null;
8
+ routeSupported: boolean;
9
+ routeRevision: string;
10
+ cli: {
11
+ version: string;
12
+ path: string;
13
+ state: string;
14
+ };
15
+ pipeline: {
16
+ version: string;
17
+ sourceReady: boolean;
18
+ installed: boolean;
19
+ };
20
+ unityProcesses: string[];
21
+ supportedVersions: string[];
22
+ }>;
@@ -0,0 +1,41 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { readProjectInfo } from '../projectVersion.js';
4
+ import { resolveRouteForProject, listEditorVersions } from '../routes.js';
5
+ import { cliBinaryPath, generatedPackageDir } from '../paths.js';
6
+ import { sha256File } from '../integrity.js';
7
+ import { queryUnityProcesses } from '../unityGuard.js';
8
+ export async function runDoctor(projectPath, options = {}) {
9
+ const project = readProjectInfo(projectPath);
10
+ const route = resolveRouteForProject(project);
11
+ const cliPath = cliBinaryPath(route.cli);
12
+ let cliState = 'missing';
13
+ if (existsSync(cliPath)) {
14
+ const hash = await sha256File(cliPath);
15
+ cliState = hash === route.cli.sha256.toLowerCase() ? 'valid' : 'hash-mismatch';
16
+ }
17
+ const generated = generatedPackageDir(project.editorVersion);
18
+ const pipelineInstalled = existsSync(join(project.projectPath, 'Packages', 'com.unity.pipeline', 'package.json'));
19
+ const pipelineSourceReady = existsSync(join(generated, 'package.json'));
20
+ let editors = [];
21
+ if (!options.allowRunningEditor) {
22
+ try {
23
+ const { all } = await queryUnityProcesses(project.projectPath);
24
+ editors = all.map((p) => `PID ${p.processId}`);
25
+ }
26
+ catch (err) {
27
+ editors = [`<query failed: ${err instanceof Error ? err.message : String(err)}>`];
28
+ }
29
+ }
30
+ return {
31
+ projectPath: project.projectPath,
32
+ editorVersion: project.editorVersion,
33
+ editorRevision: project.revision,
34
+ routeSupported: true,
35
+ routeRevision: route.editorRevision,
36
+ cli: { version: route.cli.version, path: cliPath, state: cliState },
37
+ pipeline: { version: route.pipeline.version, sourceReady: pipelineSourceReady, installed: pipelineInstalled },
38
+ unityProcesses: editors,
39
+ supportedVersions: listEditorVersions(),
40
+ };
41
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Every --project-path variant must be rejected: the wrapper owns targeting.
3
+ * Case-insensitive; covers --project-path, -projectPath, --project_path,
4
+ * -project-path=C:\x and every mixed-case combination.
5
+ */
6
+ export declare function findProjectPathOverride(args: string[]): string | null;
7
+ /** The wrapper always appends its own resolved project path as the last args. */
8
+ export declare function buildExecArgs(cliArgs: string[], projectPath: string): string[];
9
+ export interface ExecOptions {
10
+ downloadIfMissing?: boolean;
11
+ }
12
+ export declare function runExec(projectPath: string, cliArgs: string[], options?: ExecOptions): Promise<{
13
+ exitCode: number;
14
+ }>;
@@ -0,0 +1,48 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { readProjectInfo } from '../projectVersion.js';
3
+ import { resolveRouteForProject } from '../routes.js';
4
+ import { verifyCliBinary, ensureCliBinary } from '../ensure.js';
5
+ import { cliBinaryPath } from '../paths.js';
6
+ import { CliError } from '../errors.js';
7
+ /**
8
+ * Every --project-path variant must be rejected: the wrapper owns targeting.
9
+ * Case-insensitive; covers --project-path, -projectPath, --project_path,
10
+ * -project-path=C:\x and every mixed-case combination.
11
+ */
12
+ export function findProjectPathOverride(args) {
13
+ for (const arg of args) {
14
+ if (/^--?project[-_]?path(=.*)?$/i.test(arg)) {
15
+ return arg;
16
+ }
17
+ }
18
+ return null;
19
+ }
20
+ /** The wrapper always appends its own resolved project path as the last args. */
21
+ export function buildExecArgs(cliArgs, projectPath) {
22
+ return [...cliArgs, '--project-path', projectPath];
23
+ }
24
+ export async function runExec(projectPath, cliArgs, options = {}) {
25
+ const project = readProjectInfo(projectPath);
26
+ const route = resolveRouteForProject(project);
27
+ const override = findProjectPathOverride(cliArgs);
28
+ if (override !== null) {
29
+ throw new CliError(`exec 统一管理 --project-path,禁止在参数中覆盖目标工程:${override}`);
30
+ }
31
+ let cliPath = cliBinaryPath(route.cli);
32
+ const { existsSync } = await import('node:fs');
33
+ if (!existsSync(cliPath)) {
34
+ if (!options.downloadIfMissing) {
35
+ throw new CliError(`该路由的 CLI 尚未下载:${cliPath}。请先运行 "u-cli-mod cli install",或使用 --download-if-missing。`);
36
+ }
37
+ await ensureCliBinary(route.cli);
38
+ cliPath = cliBinaryPath(route.cli);
39
+ }
40
+ // Re-verify the hash on every invocation (fail closed on tamper).
41
+ await verifyCliBinary(route.cli);
42
+ const args = buildExecArgs(cliArgs, project.projectPath);
43
+ const child = spawnSync(cliPath, args, { stdio: 'inherit', windowsHide: true });
44
+ if (child.error) {
45
+ throw new CliError(`CLI 执行失败:${child.error.message}`);
46
+ }
47
+ return { exitCode: child.status ?? 1 };
48
+ }
@@ -0,0 +1,17 @@
1
+ export interface PipelineInstallOptions {
2
+ force?: boolean;
3
+ allowRunningEditor?: boolean;
4
+ dryRun?: boolean;
5
+ }
6
+ export declare function runPipelineInstall(projectPath: string, options?: PipelineInstallOptions): Promise<{
7
+ sourceDir: string;
8
+ sourceFileCount: number;
9
+ status: "Installed" | "AlreadyInstalled" | "DryRun";
10
+ projectPath: string;
11
+ editorVersion: string;
12
+ editorRevision: string;
13
+ pipelineVersion: string;
14
+ packagePath: string;
15
+ fileCount: number;
16
+ backupPath?: string;
17
+ }>;
@@ -0,0 +1,19 @@
1
+ import { readProjectInfo } from '../projectVersion.js';
2
+ import { resolveRouteForProject } from '../routes.js';
3
+ import { ensurePipelineSource } from '../ensure.js';
4
+ import { installPipeline } from '../installer.js';
5
+ import { loadExpectedTree } from '../routes.js';
6
+ export async function runPipelineInstall(projectPath, options = {}) {
7
+ const project = readProjectInfo(projectPath);
8
+ const route = resolveRouteForProject(project);
9
+ const expectedTree = loadExpectedTree(project.editorVersion);
10
+ const { sourceDir, fileCount } = await ensurePipelineSource(project.editorVersion, route, {
11
+ force: options.force,
12
+ });
13
+ const result = await installPipeline(project, route, sourceDir, expectedTree.files, {
14
+ force: options.force,
15
+ allowRunningEditor: options.allowRunningEditor,
16
+ dryRun: options.dryRun,
17
+ });
18
+ return { ...result, sourceDir, sourceFileCount: fileCount };
19
+ }
@@ -0,0 +1,11 @@
1
+ export declare function runRoutes(editorVersion?: string): {
2
+ routes: {
3
+ editorVersion: string;
4
+ editorRevision: string;
5
+ cliVersion: string;
6
+ cliSha256: string;
7
+ pipelineVersion: string;
8
+ pipelineSha256: string;
9
+ status: string;
10
+ }[];
11
+ };