dsh-stm32 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 (82) hide show
  1. package/README.md +127 -29
  2. package/README_EN.md +125 -29
  3. package/client/client.js +682 -0
  4. package/docs/development-notes.md +1385 -5
  5. package/docs/logic-audit.md +607 -0
  6. package/docs/reading-guide.md +738 -0
  7. package/lib/client.js +682 -0
  8. package/lib/commands/register.js +214 -12
  9. package/lib/data/chips.js +134 -4
  10. package/lib/data/clock-f1.js +158 -0
  11. package/lib/data/cmsis-sources.js +316 -0
  12. package/lib/data/f1-ram.generated.js +34 -0
  13. package/lib/data/firmware-packages.js +352 -0
  14. package/lib/data/install-guides.js +190 -0
  15. package/lib/data/search-roots.js +135 -15
  16. package/lib/data/stm32f1.js +186 -0
  17. package/lib/data/toolchain-config.js +310 -0
  18. package/lib/engine/build.js +121 -16
  19. package/lib/engine/cache.js +336 -0
  20. package/lib/engine/clock-plan.js +608 -0
  21. package/lib/engine/cmake-sources.js +428 -0
  22. package/lib/engine/code-patch.js +18 -6
  23. package/lib/engine/debug-session.js +163 -4
  24. package/lib/engine/debug.js +84 -19
  25. package/lib/engine/doctor.js +395 -4
  26. package/lib/engine/fetch.js +287 -0
  27. package/lib/engine/firmware-install.js +668 -0
  28. package/lib/engine/flash.js +145 -15
  29. package/lib/engine/fs-longpath.js +107 -0
  30. package/lib/engine/generate-cache.js +118 -0
  31. package/lib/engine/generate-script.js +30 -8
  32. package/lib/engine/generate.js +296 -14
  33. package/lib/engine/hal-chip.js +230 -0
  34. package/lib/engine/ioc-plan.js +47 -8
  35. package/lib/engine/msys2-install.js +1870 -0
  36. package/lib/engine/probe.js +57 -6
  37. package/lib/engine/project-export.js +129 -0
  38. package/lib/engine/register-clock.js +132 -0
  39. package/lib/engine/register-linker.js +129 -0
  40. package/lib/engine/register-template.js +449 -0
  41. package/lib/engine/regs.js +18 -4
  42. package/lib/engine/route-plan.js +553 -0
  43. package/lib/engine/scaffold.js +303 -72
  44. package/lib/engine/subprocess-runner.js +2 -0
  45. package/lib/engine/tar.js +250 -0
  46. package/lib/engine/text-file.js +150 -0
  47. package/lib/engine/thirdparty.js +243 -0
  48. package/lib/engine/tool-env.js +51 -0
  49. package/lib/engine/toolchain-gate.js +386 -0
  50. package/lib/engine/vscode-config.js +99 -0
  51. package/lib/engine/web-api.js +375 -0
  52. package/lib/engine/web-routes.js +100 -0
  53. package/lib/engine/xcube-catalog.js +102 -0
  54. package/lib/engine/xcube.js +254 -0
  55. package/lib/engine/zip.js +142 -0
  56. package/lib/index.js +44 -2
  57. package/lib/skill/stm32-workflow.js +3 -3
  58. package/lib/tools/build.js +55 -3
  59. package/lib/tools/cache.js +250 -0
  60. package/lib/tools/code-patch.js +29 -2
  61. package/lib/tools/debug-session.js +56 -14
  62. package/lib/tools/debug.js +43 -2
  63. package/lib/tools/doctor.js +16 -3
  64. package/lib/tools/env-install.js +472 -0
  65. package/lib/tools/env-probe.js +6 -2
  66. package/lib/tools/firmware-install.js +255 -0
  67. package/lib/tools/flash.js +41 -2
  68. package/lib/tools/generate.js +96 -10
  69. package/lib/tools/ioc-apply.js +27 -11
  70. package/lib/tools/ioc-inspect.js +4 -2
  71. package/lib/tools/ioc-plan.js +209 -11
  72. package/lib/tools/project-create.js +229 -21
  73. package/lib/tools/project-dir.js +95 -0
  74. package/lib/tools/project-export.js +100 -0
  75. package/lib/tools/regs.js +82 -7
  76. package/lib/tools/route-plan.js +467 -0
  77. package/package.json +11 -4
  78. package/templates/register/CMakeLists.txt +52 -0
  79. package/templates/register/Core/Src/main.c +72 -0
  80. package/templates/scaffold/openocd.cfg +8 -0
  81. package/templates/scaffold/vscode/launch.json +8 -6
  82. package/templates/scaffold/vscode/settings.json +5 -11
@@ -0,0 +1,1870 @@
1
+ /**
2
+ * MSYS2 安装器(L2):把"这台机器缺工具链"从一句建议变成一次可复核的安装。
3
+ *
4
+ * 三条设计红线,都是为了"只做用户授权过的事":
5
+ * 1. 默认只出计划。计划里连目标目录都不建、配置不写、注册表不碰——真装要写几百 MB 磁盘
6
+ * 还要改用户级 PATH,这种动作必须由用户明确点一次(工具层 dryRun:false + confirm:true)。
7
+ * 2. 绝不请求管理员。PATH 只改 HKCU\Environment(用户级),不碰 HKLM;也不用 setx
8
+ * (setx 会在 1024 字符处截断 PATH,还会丢掉 REG_EXPAND_SZ 的变量展开语义)。
9
+ * 3. 不做卸载,也不删用户的任何东西。只清理自己建的暂存目录与 .part 半成品;目标目录非空
10
+ * 就停下来报警——宁可让用户换目录,也不猜"这个 msys64 目录能不能覆盖"。
11
+ *
12
+ * 为什么装完不需要用户重读环境变量:插件自己读工具链配置(data/toolchain-config)里的绝对
13
+ * 路径,装完立刻生效;PATH 只是顺手给命令行和其他工具用的。
14
+ *
15
+ * 下载只用系统 curl、解压只用官方 sfx,不引第三方包(插件保持零运行时依赖)。
16
+ */
17
+ import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
18
+ import { tmpdir } from "node:os";
19
+ import { dirname, join } from "node:path";
20
+ import { DEFAULT_BIN_DIRS, decodeRegistryText, dedupePaths, discoverInstalls, discoveryDisabled, normalizePathEntry, resolveSearchConfig, splitList, } from "../data/search-roots.js";
21
+ import { readToolchainConfig, toolchainConfigPath, updateToolchainConfig, } from "../data/toolchain-config.js";
22
+ import { buildTargets, probeAll } from "./probe.js";
23
+ import { runCapture } from "./subprocess-runner.js";
24
+ /** 下载/解压/补包都是分钟级:默认给 15 分钟,调用方可用 timeoutMs 覆盖。 */
25
+ const DEFAULT_COMMAND_TIMEOUT_MS = 15 * 60_000;
26
+ /** 自检只跑版本命令,不该慢。 */
27
+ const PROBE_TIMEOUT_MS = 15_000;
28
+ /**
29
+ * pacman -Q 的预算:比版本命令宽得多。MSYS2 的 pacman 在本机实测要 6–11 s
30
+ * (bash -lc 起一遍 profile 更慢),拿 15 s 去问必然超时,计划就又把「已装齐」说成「缺 5 个」。
31
+ */
32
+ const PACMAN_QUERY_TIMEOUT_MS = 60_000;
33
+ const WINDOWS = process.platform === "win32";
34
+ /**
35
+ * 官方自解压包。名字里必须带 base:GitHub releases 上**没有** msys2-x86_64-latest.sfx.exe
36
+ * 这个资产(msys2-x86_64-latest.exe 是图形安装器),sfx 只有 msys2-base-x86_64-latest.sfx.exe。
37
+ * 它解压出一个顶层 msys64 目录,所以官方文档写 -y -oC:\ 就会得到 C:\msys64。
38
+ */
39
+ const INSTALLER_FILE = "msys2-base-x86_64-latest.sfx.exe";
40
+ /**
41
+ * 同一个安装包在不同地方有两个文件名:镜像用 msys2-x86_64-latest.sfx.exe,
42
+ * GitHub releases 用 msys2-base-x86_64-latest.sfx.exe。两个都试——一个名字 404
43
+ * 不代表这个源没有包(实测 TUNA 只有 msys2-x86_64- 那个)。
44
+ */
45
+ const INSTALLER_NAMES = ["msys2-x86_64-latest.sfx.exe", INSTALLER_FILE];
46
+ /**
47
+ * 安装包候选源(实测 2026-10,HEAD):TUNA / NJU / 阿里云 均 200 且 43,117,824 B;
48
+ * USTC 的 distrib 目录回 403(仍留作候选:它可能只挡 HEAD,真下能成)。
49
+ * 镜像同步时点不同 → 字节数不同 → 不能跨源钉同一个 sha256,只能做 F3d 的三道粗检。
50
+ */
51
+ const INSTALLER_MIRRORS = [
52
+ { label: "清华 TUNA", base: "https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib" },
53
+ { label: "中科大 USTC", base: "https://mirrors.ustc.edu.cn/msys2/distrib" },
54
+ { label: "南大 NJU", base: "https://mirror.nju.edu.cn/msys2/distrib" },
55
+ { label: "阿里云", base: "https://mirrors.aliyun.com/msys2/distrib" },
56
+ ];
57
+ /** 官方兜底:GitHub releases/latest。F3e 要求「GitHub 类下载不改顺序」,它在候选链的最后。 */
58
+ const INSTALLER_GITHUB = "https://github.com/msys2/msys2-installer/releases/latest/download";
59
+ export const MSYS2_INSTALLER_URL = INSTALLER_GITHUB + "/" + INSTALLER_FILE;
60
+ /** 该资产的字节数(实测 43,060,392);只用于计划里的用量估算,不参与校验。 */
61
+ export const MSYS2_INSTALLER_BYTES = 43_060_392;
62
+ /**
63
+ * 真包的体量下限(实测 42.9–43.1 MB)。小于它就是半截文件或错误页:
64
+ * 半截文件若被当成有效缓存,解压会永远失败,用户只能自己猜该删哪个文件(F3d)。
65
+ */
66
+ const MIN_INSTALLER_BYTES = 40_000_000;
67
+ /** 下载中被判「这条线不行」的两个阈值:10 s 内平均不足 1 KB/s 就换源。 */
68
+ const DOWNLOAD_STALL_MS = 10_000;
69
+ const DOWNLOAD_MIN_BYTES_PER_SEC = 1024;
70
+ /** 默认补的包:编译器 / 调试器 / 烧录服务端 / 构建系统 / 构建工具。 */
71
+ export const DEFAULT_MSYS2_PACKAGES = [
72
+ "mingw-w64-ucrt-x86_64-arm-none-eabi-gcc",
73
+ "mingw-w64-ucrt-x86_64-gdb-multiarch",
74
+ "mingw-w64-ucrt-x86_64-openocd",
75
+ "mingw-w64-ucrt-x86_64-cmake",
76
+ "mingw-w64-ucrt-x86_64-ninja",
77
+ ];
78
+ /** 配置与自动发现都没有时建议装这里;只作为建议,不自动采用("装到哪"得用户点头)。 */
79
+ export const MSYS2_SUGGESTED_ROOT = "C:/msys64";
80
+ /** 自检关注的 5 个组件(覆盖 toolchain-gate 的 build/flash/debug 三项能力)。 */
81
+ const VERIFY_IDS = ["gcc", "cmake", "ninja", "openocd", "gdb"];
82
+ /** 每步的 id + 人话标签;顺序就是执行顺序。 */
83
+ const STEP_DEFS = [
84
+ { id: "prepare", label: "准备安装目录" },
85
+ { id: "download", label: "下载 MSYS2 安装包" },
86
+ { id: "extract", label: "静默解压到目标目录" },
87
+ { id: "pacman", label: "pacman 补装工具链组件" },
88
+ { id: "path", label: "写用户级 PATH" },
89
+ { id: "verify", label: "自检 5 个组件" },
90
+ { id: "config", label: "写入工具链配置" },
91
+ ];
92
+ /** 单包下载字节估算;只用于"计划总量"那句话,缺省值给个数量级即可。 */
93
+ const PACKAGE_BYTES = {
94
+ "mingw-w64-ucrt-x86_64-arm-none-eabi-gcc": 62_000_000,
95
+ "mingw-w64-ucrt-x86_64-gdb-multiarch": 22_000_000,
96
+ "mingw-w64-ucrt-x86_64-openocd": 3_000_000,
97
+ "mingw-w64-ucrt-x86_64-cmake": 33_000_000,
98
+ "mingw-w64-ucrt-x86_64-ninja": 600_000,
99
+ };
100
+ const PACKAGE_BYTES_DEFAULT = 10_000_000;
101
+ const PATH_KEY = "HKCU\\Environment";
102
+ /* ------------------------------ 小工具 ------------------------------ */
103
+ function toPosix(value) {
104
+ return normalizePathEntry(value);
105
+ }
106
+ function toWindowsDir(dir) {
107
+ return dir.replace(/\//gu, "\\");
108
+ }
109
+ function describeError(error) {
110
+ return error instanceof Error ? error.message : String(error);
111
+ }
112
+ /**
113
+ * 人读的体量;估算值也走这里,保证卡片上单位一致。
114
+ * 十进制(1 MB = 1e6 B):GitHub release 页面和 pacman 的 "Total Download Size" 都是十进制,
115
+ * 用 1024 进制会凭空多报 4.86%,用户对不上号(43 060 392 B 应显示 43.1 MB,不是 41.1 MB)。
116
+ */
117
+ export function formatBytes(bytes) {
118
+ if (!Number.isFinite(bytes) || bytes <= 0)
119
+ return "0 MB";
120
+ const value = bytes / 1_000_000;
121
+ return (value >= 100 ? value.toFixed(0) : value.toFixed(1)) + " MB";
122
+ }
123
+ function dedupeStrings(values) {
124
+ const seen = new Set();
125
+ const out = [];
126
+ for (const value of values) {
127
+ const trimmed = value.trim();
128
+ if (trimmed === "")
129
+ continue;
130
+ const key = trimmed.toLowerCase();
131
+ if (seen.has(key))
132
+ continue;
133
+ seen.add(key);
134
+ out.push(trimmed);
135
+ }
136
+ return out;
137
+ }
138
+ /** 取最后一行非空内容:把子进程噪音压成一句给用户看。 */
139
+ function lastLine(text) {
140
+ const lines = text.split(/\r?\n/u);
141
+ for (let index = lines.length - 1; index >= 0; index -= 1) {
142
+ const trimmed = (lines[index] ?? "").trim();
143
+ if (trimmed !== "")
144
+ return trimmed;
145
+ }
146
+ return "";
147
+ }
148
+ function fileSize(path) {
149
+ try {
150
+ const stat = statSync(path);
151
+ return stat.isFile() ? stat.size : 0;
152
+ }
153
+ catch {
154
+ return 0;
155
+ }
156
+ }
157
+ /**
158
+ * 缓存是不是一个真的 exe(MZ 头)。
159
+ * 为什么查:下载中断留下的半截文件若只按 size>0 判断,会被下一次当成有效缓存,
160
+ * 于是解压永远失败,用户只能自己猜该删哪个文件。
161
+ */
162
+ function looksLikeExecutable(path) {
163
+ if (fileSize(path) < 2)
164
+ return false;
165
+ let fd = -1;
166
+ try {
167
+ fd = openSync(path, "r");
168
+ const buffer = Buffer.alloc(2);
169
+ const read = readSync(fd, buffer, 0, 2, 0);
170
+ return read === 2 && buffer[0] === 0x4d && buffer[1] === 0x5a;
171
+ }
172
+ catch {
173
+ return false;
174
+ }
175
+ finally {
176
+ if (fd >= 0) {
177
+ try {
178
+ closeSync(fd);
179
+ }
180
+ catch {
181
+ // 关不掉不影响结论
182
+ }
183
+ }
184
+ }
185
+ }
186
+ /**
187
+ * 缓存能不能当"已经下好的安装包"用(F3d):MZ 头 + 体量下限。
188
+ * 只查 size>0 时,一次超时留下的 12 MB 半截文件会被下一次当成有效缓存,解压永远失败。
189
+ * 返回可用字节数,0 表示不可用。
190
+ */
191
+ function cachedInstallerBytes(path) {
192
+ const bytes = fileSize(path);
193
+ if (bytes < MIN_INSTALLER_BYTES)
194
+ return 0;
195
+ return looksLikeExecutable(path) ? bytes : 0;
196
+ }
197
+ function safeList(dir) {
198
+ try {
199
+ return readdirSync(dir);
200
+ }
201
+ catch {
202
+ return [];
203
+ }
204
+ }
205
+ function removeFileQuietly(path) {
206
+ try {
207
+ if (existsSync(path))
208
+ unlinkSync(path);
209
+ }
210
+ catch {
211
+ // 清理失败不影响主结论
212
+ }
213
+ }
214
+ /**
215
+ * 清掉暂存目录/半成品。
216
+ * 只对**我们自己建的**路径调用(.part 与 .dsh-msys2-staging):用户的东西一个都不删。
217
+ */
218
+ function removeDirQuietly(dir) {
219
+ try {
220
+ rmSync(dir, { recursive: true, force: true });
221
+ }
222
+ catch {
223
+ // 删不掉就留着,不影响结论
224
+ }
225
+ }
226
+ /**
227
+ * 是不是 Windows 盘根(C:/、C:、D:\ 这类)。
228
+ * Node 的 mkdirSync 对盘根会抛 EPERM(Windows 不允许 mkdir 在盘根上"创建"它),
229
+ * 而 targetDir=C:/msys64 时 parent 恰好就是盘根——那是本插件自己建议的默认装法,
230
+ * 不能让推荐路径变成必炸路径。
231
+ */
232
+ export function isDriveRoot(dir) {
233
+ const posix = toPosix(dir).replace(/\/+$/u, "");
234
+ return /^[A-Za-z]:$/u.test(posix);
235
+ }
236
+ /**
237
+ * 确保父目录存在:盘根直接 existsSync 校验(永远存在),其余才走 mkdirSync。
238
+ * 返回空串表示成功,非空是中文错误原因。
239
+ */
240
+ function ensureParentDir(parent) {
241
+ if (isDriveRoot(parent)) {
242
+ return existsSync(parent) ? "" : "盘根不存在:" + parent;
243
+ }
244
+ try {
245
+ mkdirSync(parent, { recursive: true });
246
+ return "";
247
+ }
248
+ catch (error) {
249
+ return describeError(error);
250
+ }
251
+ }
252
+ function isMsys2Root(dir) {
253
+ return dir !== "" && existsSync(dir + "/usr/bin/bash.exe");
254
+ }
255
+ function msys2PackagesTotal(packages) {
256
+ let total = 0;
257
+ for (const name of packages)
258
+ total += PACKAGE_BYTES[name] ?? PACKAGE_BYTES_DEFAULT;
259
+ return total;
260
+ }
261
+ function isAborted(signal) {
262
+ return signal?.aborted === true;
263
+ }
264
+ /** 候选链的人话标签,报错时能说清"试过哪些源、各是怎么失败的"。 */
265
+ export function installerSourceLabel(url) {
266
+ for (const mirror of INSTALLER_MIRRORS) {
267
+ if (url.startsWith(mirror.base))
268
+ return mirror.label;
269
+ }
270
+ return url.startsWith(INSTALLER_GITHUB) ? "GitHub" : "自定义地址";
271
+ }
272
+ /**
273
+ * 安装包候选地址(F3a):环境变量整体替换 > MSYS2_MIRROR 前缀 > 国内镜像链 → GitHub。
274
+ *
275
+ * 为什么不再只写死 GitHub:releases/latest 在部分网络里连不上(与 CMSIS 头同一个墙),
276
+ * 一次 43 MB 的下载失败就等于这次安装整个作废,而国内镜像本来就有同名包。
277
+ * 每个源都试两个文件名(镜像用 msys2-x86_64-,GitHub 用 msys2-base-)。
278
+ * MSYS2_MIRROR 给全(以 .exe/.7z/.zip 结尾)就直接当完整地址,否则当前缀拼两个文件名。
279
+ */
280
+ export function resolveInstallerUrls(env) {
281
+ const direct = (env["MSYS2_INSTALLER_URL"] ?? "").trim();
282
+ if (direct !== "") {
283
+ return { urls: [direct], note: "安装包地址来自环境变量 MSYS2_INSTALLER_URL(只用这一个源)" };
284
+ }
285
+ const mirror = (env["MSYS2_MIRROR"] ?? "").trim().replace(/\/+$/u, "");
286
+ if (mirror !== "") {
287
+ const urls = /\.(exe|7z|zip)$/iu.test(mirror)
288
+ ? [mirror]
289
+ : INSTALLER_NAMES.map((name) => mirror + "/" + name);
290
+ return {
291
+ urls,
292
+ note: "安装包地址来自环境变量 MSYS2_MIRROR(镜像);官方源是 " + MSYS2_INSTALLER_URL,
293
+ };
294
+ }
295
+ const urls = [];
296
+ for (const source of INSTALLER_MIRRORS) {
297
+ for (const name of INSTALLER_NAMES)
298
+ urls.push(source.base + "/" + name);
299
+ }
300
+ for (const name of INSTALLER_NAMES)
301
+ urls.push(INSTALLER_GITHUB + "/" + name);
302
+ return {
303
+ urls,
304
+ note: "安装包按 " +
305
+ INSTALLER_MIRRORS.map((source) => source.label).join(" → ") +
306
+ " → GitHub 依次尝试,前一个源不通就换下一个(每个源两个文件名)",
307
+ };
308
+ }
309
+ /** 配置目录(与 toolchain-config 同目录);不可用时退回系统临时目录。 */
310
+ function stateDir(env) {
311
+ const configPath = toolchainConfigPath(env);
312
+ const dir = toPosix(dirname(configPath));
313
+ return dir === "" ? toPosix(tmpdir()) : dir;
314
+ }
315
+ function cacheFilePath(env) {
316
+ // 固定文件名:换镜像/换版本不会堆一堆包体;要换版本就自己删这个文件。
317
+ return stateDir(env) + "/msys2-latest.sfx.exe";
318
+ }
319
+ /* --------------------------- pacman 镜像(F3b) --------------------------- */
320
+ /**
321
+ * 国内镜像的 pacman 地址。实测 2026-10:四家的 msys/x86_64/msys.db 都是 200 且同一份
322
+ * 516,869 B(校验和一致 → 同步是齐的)。放在官方列表**前面**,官方条目原样保留在后面兜底。
323
+ */
324
+ const PACMAN_MIRRORS = [
325
+ {
326
+ label: "清华 TUNA",
327
+ msys: "https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch/",
328
+ mingw: "https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/$repo/",
329
+ },
330
+ {
331
+ label: "中科大 USTC",
332
+ msys: "https://mirrors.ustc.edu.cn/msys2/msys/$arch/",
333
+ mingw: "https://mirrors.ustc.edu.cn/msys2/mingw/$repo/",
334
+ },
335
+ {
336
+ label: "南大 NJU",
337
+ msys: "https://mirror.nju.edu.cn/msys2/msys/$arch/",
338
+ mingw: "https://mirror.nju.edu.cn/msys2/mingw/$repo/",
339
+ },
340
+ {
341
+ label: "阿里云",
342
+ msys: "https://mirrors.aliyun.com/msys2/msys/$arch/",
343
+ mingw: "https://mirrors.aliyun.com/msys2/mingw/$repo/",
344
+ },
345
+ ];
346
+ const MIRRORLIST_HEADER = "# dsh-stm32:把国内镜像放到最前面(官方源原样保留在后面兜底)。\n" +
347
+ "# 想去掉这段:删掉本注释与紧随其后的几行 Server = 即可,其余内容不受影响。\n";
348
+ /** 把一组 Server 行提到最前;已有的不重复添加(幂等,重复调不会越堆越长)。 */
349
+ export function preferMirrorServers(text, servers) {
350
+ const present = new Set(text
351
+ .split(/\r?\n/u)
352
+ .map((line) => line.trim())
353
+ .filter((line) => line.toLowerCase().startsWith("server ="))
354
+ .map((line) => line.slice("server =".length).trim()));
355
+ const missing = servers.filter((server) => !present.has(server));
356
+ if (missing.length === 0)
357
+ return text;
358
+ const block = MIRRORLIST_HEADER + missing.map((server) => "Server = " + server).join("\n") + "\n\n";
359
+ return block + text;
360
+ }
361
+ /**
362
+ * 给新解压出来的 MSYS2 换上国内镜像(F3b)。只在"刚解压完"时调用:
363
+ * 已有 MSYS2 是用户自己的东西,改人家的 pacman 配置不在本工具的授权范围内。
364
+ * 只动 mirrorlist.msys($arch)与 mirrorlist.mingw($repo)两个文件,写前不备份也不删内容。
365
+ */
366
+ export function preferChinaMirrors(msys64) {
367
+ const dir = msys64 + "/etc/pacman.d";
368
+ const targets = [
369
+ { file: dir + "/mirrorlist.msys", servers: PACMAN_MIRRORS.map((item) => item.msys) },
370
+ { file: dir + "/mirrorlist.mingw", servers: PACMAN_MIRRORS.map((item) => item.mingw) },
371
+ ];
372
+ const updated = [];
373
+ for (const target of targets) {
374
+ if (!existsSync(target.file))
375
+ continue;
376
+ try {
377
+ const before = readFileSync(target.file, "utf8");
378
+ const after = preferMirrorServers(before, target.servers);
379
+ if (after === before)
380
+ continue;
381
+ writeFileSync(target.file, after, "utf8");
382
+ updated.push(target.file.slice(dir.length + 1));
383
+ }
384
+ catch {
385
+ // 改不动就算了:官方源还在列表里,pacman 仍能装,只是慢一点。
386
+ }
387
+ }
388
+ const note = updated.length === 0
389
+ ? ""
390
+ : "已把 " +
391
+ PACMAN_MIRRORS.map((item) => item.label).join(" / ") +
392
+ " 放到 pacman 镜像列表最前(" +
393
+ updated.join("、") +
394
+ "),官方源保留在后面兜底;pacman 补包因此走国内线路。";
395
+ return { files: updated, note };
396
+ }
397
+ /** 路径所在盘符是否真的存在:跨机器的配置(配置里是 D:/app/msys64,本机没有 D 盘)不能当安装目标。 */
398
+ function driveUsable(path, exists = existsSync) {
399
+ const match = /^([A-Za-z]):/u.exec(path);
400
+ if (match === null || match[1] === undefined)
401
+ return true;
402
+ return exists(match[1].toUpperCase() + ":/");
403
+ }
404
+ /** "D:/app/msys64/ucrt64/bin" → "D:/app/msys64";"C:/msys64/mingw64/bin" 同理。 */
405
+ function rootFromBinDir(binDir) {
406
+ const normalized = toPosix(binDir);
407
+ if (normalized === "")
408
+ return "";
409
+ const withoutBin = normalized.replace(/\/bin$/iu, "");
410
+ return withoutBin.replace(/\/(ucrt64|mingw64|clang64|mingw32|usr)$/iu, "");
411
+ }
412
+ /** 候选根:默认候选表 + 自动发现的 bin 目录。纯计算,不 spawn。 */
413
+ function msys64Candidates(env) {
414
+ const roots = [];
415
+ for (const binDir of DEFAULT_BIN_DIRS) {
416
+ const root = rootFromBinDir(binDir);
417
+ if (root !== "")
418
+ roots.push(root);
419
+ }
420
+ if (!discoveryDisabled(env)) {
421
+ for (const binDir of discoverInstalls().binDirs) {
422
+ const root = rootFromBinDir(binDir);
423
+ if (root !== "")
424
+ roots.push(root);
425
+ }
426
+ }
427
+ return dedupePaths(roots);
428
+ }
429
+ /**
430
+ * 决策顺序:显式 targetDir > 配置里的 msys64 > 自动发现的(判 <root>/usr/bin/bash.exe)> 都没有。
431
+ * 都没有时**不猜**:装到哪必须由用户说一句。
432
+ */
433
+ export function resolveTargetDir(explicit, config, env,
434
+ /** 单测注入用;生产代码不要传(默认看真实文件系统)。 */
435
+ exists = existsSync) {
436
+ const fromArg = explicit === undefined ? "" : toPosix(explicit);
437
+ if (fromArg !== "")
438
+ return { msys64: fromArg, via: "arg", warning: "" };
439
+ const fromConfig = config === null ? "" : toPosix(config.msys64);
440
+ if (fromConfig !== "") {
441
+ if (driveUsable(fromConfig, exists))
442
+ return { msys64: fromConfig, via: "config", warning: "" };
443
+ // 配置可能是从别的机器拷来的:盘符都不存在,既不能当安装目标,也不能当"已装"。
444
+ const warning = "配置里的 MSYS2 根 " +
445
+ fromConfig +
446
+ " 在本机不存在(盘符都没有,配置大概是从别的机器拷来的),已忽略,请指定 targetDir";
447
+ for (const candidate of msys64Candidates(env)) {
448
+ if (isMsys2Root(candidate))
449
+ return { msys64: candidate, via: "discovered", warning };
450
+ }
451
+ return { msys64: "", via: "", warning };
452
+ }
453
+ for (const candidate of msys64Candidates(env)) {
454
+ // 只认"能跑"的:目录在但缺 usr/bin/bash.exe 的半成品不算已安装。
455
+ if (isMsys2Root(candidate))
456
+ return { msys64: candidate, via: "discovered", warning: "" };
457
+ }
458
+ return { msys64: "", via: "", warning: "" };
459
+ }
460
+ /** 需要决策时建议装哪:发现表里已经存在的目录优先(可能是用户以前装过的位置),否则 C:/msys64。 */
461
+ function suggestMsys64Root(env) {
462
+ for (const candidate of msys64Candidates(env)) {
463
+ if (existsSync(candidate))
464
+ return candidate;
465
+ }
466
+ return MSYS2_SUGGESTED_ROOT;
467
+ }
468
+ export function viaLabel(via) {
469
+ switch (via) {
470
+ case "arg":
471
+ return "参数 targetDir";
472
+ case "config":
473
+ return "配置里的 msys64";
474
+ case "discovered":
475
+ return "自动发现";
476
+ case "suggested":
477
+ // 契约里的保留值:自动采用建议路径会把"装到哪"变成隐式决定,我们不这么做。
478
+ return "建议路径(尚未确认)";
479
+ default:
480
+ return "还没决定";
481
+ }
482
+ }
483
+ /** 读失败:raw 归成空串只是让类型上有个值,调用方必须先看 readable 再决定能不能写。 */
484
+ function emptyUserPath(error) {
485
+ return { raw: "", entries: [], found: false, readable: false, error };
486
+ }
487
+ /** reg 明确回答"没有这个值":可以新建,此时的空串不代表会丢数据。 */
488
+ function absentUserPath() {
489
+ return { raw: "", entries: [], found: false, readable: true, error: "" };
490
+ }
491
+ /** reg query 报"找不到"的本地化写法(zh-CN / en-US);命中即"这个值不存在"。 */
492
+ const MISSING_VALUE_MARKERS = [
493
+ "unable to find",
494
+ "无法找到",
495
+ "找不到指定的注册表",
496
+ "cannot find",
497
+ "does not exist",
498
+ "不存在",
499
+ ];
500
+ function looksLikeMissingValue(text) {
501
+ const lowered = text.toLowerCase();
502
+ return MISSING_VALUE_MARKERS.some((marker) => lowered.includes(marker));
503
+ }
504
+ /** 从 reg query 的输出里抠出值(形如: Path REG_EXPAND_SZ C:\a;D:\b)。 */
505
+ function parseRegLine(text, name) {
506
+ const lowered = name.toLowerCase();
507
+ for (const line of text.split(/\r?\n/u)) {
508
+ const trimmed = line.trim();
509
+ if (!trimmed.toLowerCase().startsWith(lowered))
510
+ continue;
511
+ const match = /^\S+\s{2,}(REG_[A-Z_]+)\s{2,}([\s\S]*)$/u.exec(trimmed);
512
+ if (match !== null)
513
+ return { found: true, value: (match[2] ?? "").trim() };
514
+ }
515
+ return { found: false, value: "" };
516
+ }
517
+ function parseRegValue(text, name) {
518
+ return parseRegLine(text, name).value;
519
+ }
520
+ /**
521
+ * 跑一次 reg query,并把**原始字节**拿回来。
522
+ *
523
+ * 为什么要绕一层 cmd.exe 重定向:宿主的 subprocess 只给解码后的字符串
524
+ * (CollectedReader.readFrom().text),而 reg.exe 是控制台程序,写的是系统 ANSI 代码页的
525
+ * 字节(中文 Windows 是 GBK)。直接从管道读,带中文的 PATH 条目必然变成 U+FFFD,
526
+ * 再被当成"用户原来的旧值"写回注册表,就把整条用户级 PATH 写坏了(B3 的备份也会是乱码)。
527
+ * 所以让 cmd 把输出重定向到临时文件,再用 readFileSync 取 Buffer,交给 decodeRegistryText
528
+ * 按 UTF-8 / GB18030 探测。临时目录里只有这一次的输出,用完就删。
529
+ */
530
+ async function queryUserPathBytes(subprocess, signal) {
531
+ let dir = "";
532
+ try {
533
+ dir = mkdtempSync(join(tmpdir(), "dsh-msys2-reg-"));
534
+ }
535
+ catch (error) {
536
+ return {
537
+ text: "",
538
+ exitCode: null,
539
+ spawnError: "建临时目录失败:" + describeError(error),
540
+ timedOut: false,
541
+ decodeError: "",
542
+ };
543
+ }
544
+ const dump = join(dir, "dump.txt");
545
+ try {
546
+ // 这一行故意不带任何引号、也不用绝对路径(cwd 就是临时目录):cmd /c 对 \" 的转义规则
547
+ // 很容易踩坑,而 HKCU\Environment 与 dump.txt 都不含空格,省事且最不容易出错。
548
+ const outcome = await runCapture(subprocess, {
549
+ argv: ["cmd.exe", "/d", "/s", "/c", "reg.exe query " + PATH_KEY + " /v Path > dump.txt 2>&1"],
550
+ cwd: dir,
551
+ timeoutMs: 10_000,
552
+ ...(signal === undefined ? {} : { signal }),
553
+ });
554
+ let bytes = null;
555
+ try {
556
+ bytes = readFileSync(dump);
557
+ }
558
+ catch {
559
+ // 文件没写出来(安全软件拦了 cmd、或重定向被改写):退回宿主给的文本——
560
+ // 至少"系统找不到指定的注册表项或值"这类纯 ASCII 结论还认得出来。
561
+ bytes = null;
562
+ }
563
+ const decoded = decodeRegistryText(bytes === null ? outcome.stdout + "\n" + outcome.stderr : bytes, "reg query 输出");
564
+ return {
565
+ text: decoded.ok ? decoded.text : "",
566
+ exitCode: outcome.exitCode,
567
+ spawnError: outcome.spawnError,
568
+ timedOut: outcome.timedOut,
569
+ decodeError: decoded.ok ? "" : decoded.error,
570
+ };
571
+ }
572
+ finally {
573
+ removeDirQuietly(dir);
574
+ }
575
+ }
576
+ async function readUserPath(subprocess, signal) {
577
+ if (!WINDOWS)
578
+ return emptyUserPath("非 Windows:没有用户级 PATH 可写");
579
+ const outcome = await queryUserPathBytes(subprocess, signal);
580
+ if (outcome.spawnError !== null)
581
+ return emptyUserPath("reg query 起不来:" + outcome.spawnError);
582
+ if (outcome.timedOut)
583
+ return emptyUserPath("reg query 超时(10 秒没有返回)");
584
+ // 字节解不出来就当作读不到:宁可让用户手动加一条,也不把乱码写回注册表。
585
+ if (outcome.decodeError !== "") {
586
+ return emptyUserPath("reg query 的输出解不出来(" + outcome.decodeError + ")");
587
+ }
588
+ if (outcome.exitCode !== 0) {
589
+ // 退出码非 0 分两类:①「系统找不到指定的注册表项或值」= 用户变量里真的没有 Path,可以新建;
590
+ // ②被组策略 / EDR 拦住、参数不对等 = 读不可信,绝不能拿空串去 reg add 覆盖。
591
+ if (looksLikeMissingValue(outcome.text))
592
+ return absentUserPath();
593
+ const reason = lastLine(outcome.text) || "没有输出";
594
+ return emptyUserPath("reg query 退出码 " + String(outcome.exitCode) + ":" + reason);
595
+ }
596
+ const parsed = parseRegLine(outcome.text, "Path");
597
+ // 退出码 0 却一行都没认出来:多半是输出格式 / 系统语言与预期不符(也可能是值名被改过),
598
+ // 一律按"读不到"处理——宁可让用户手动加一条,也不要 blind 覆盖。
599
+ if (!parsed.found) {
600
+ return emptyUserPath("reg query 的输出里没有 Path 那一行(输出格式与预期不符)");
601
+ }
602
+ return { raw: parsed.value, entries: splitList(parsed.value), found: true, readable: true, error: "" };
603
+ }
604
+ function composeUserPath(raw, entry) {
605
+ const base = raw.replace(/\s+$/u, "").replace(/;+$/u, "");
606
+ return base === "" ? entry : base + ";" + entry;
607
+ }
608
+ function pathContains(current, entry) {
609
+ const key = toPosix(entry).toLowerCase();
610
+ if (key === "")
611
+ return false;
612
+ return current.entries.some((item) => item.toLowerCase() === key);
613
+ }
614
+ /** 读不到时的兜底说明:给可手动执行的写法,但要求用户自己先确认旧值(我们读不到就无法替他拼)。 */
615
+ function manualPathHint(entry) {
616
+ return ("先在命令行跑 reg query \"" +
617
+ PATH_KEY +
618
+ "\" /v Path 确认能读到旧值,再在「环境变量 → 用户变量 → Path」末尾加一条 " +
619
+ entry +
620
+ ";等价命令 reg add \"" +
621
+ PATH_KEY +
622
+ "\" /v Path /t REG_EXPAND_SZ /d \"<完整旧值>;" +
623
+ entry +
624
+ "\" /f —— 其中 <完整旧值> 必须换成真的旧值(别用空串;也别用 setx,setx 会在 1024 字符处截断 PATH)");
625
+ }
626
+ /** 读失败时的统一开场白:卡片、步骤 detail、message 都用它,测试与用户都能一眼认出。 */
627
+ const UNREADABLE_PATH_PREFIX = "读不到当前用户 PATH";
628
+ function planPathState(current, binDir, writePath) {
629
+ const state = {
630
+ done: false,
631
+ changed: false,
632
+ before: current.raw,
633
+ after: current.raw,
634
+ backup: "",
635
+ error: "",
636
+ };
637
+ if (binDir === "" || !writePath)
638
+ return state;
639
+ const entry = toWindowsDir(binDir);
640
+ if (!current.readable) {
641
+ // 读失败时连 after 都不算:拿空串拼出来的"新值"会把用户原有的一整条 Path 抹掉。
642
+ state.error =
643
+ UNREADABLE_PATH_PREFIX +
644
+ "(" +
645
+ (current.error === "" ? "原因不明" : current.error) +
646
+ "),为安全起见不会写注册表;手动:" +
647
+ manualPathHint(entry);
648
+ return state;
649
+ }
650
+ // 已经在里面:after 与 before 相同,卡片上就看得出"不会变"。
651
+ if (pathContains(current, entry))
652
+ return state;
653
+ state.after = composeUserPath(current.raw, entry);
654
+ return state;
655
+ }
656
+ /** 旧 PATH 落盘备份(写注册表前);备份失败就不写 PATH——有回滚能力比省一次点击重要。 */
657
+ function writePathBackup(raw, env) {
658
+ const dir = stateDir(env);
659
+ const stamp = new Date().toISOString().replace(/[:.]/gu, "-");
660
+ const path = dir + "/path-backup-" + stamp + ".txt";
661
+ try {
662
+ mkdirSync(dir, { recursive: true });
663
+ writeFileSync(path, raw + "\n", "utf8");
664
+ return { path, error: "" };
665
+ }
666
+ catch (error) {
667
+ return { path: "", error: describeError(error) };
668
+ }
669
+ }
670
+ async function applyUserPath(subprocess, env, binDir, request) {
671
+ // 就在要写之前再读一次:计划阶段到真装之间,用户可能自己动过环境变量。
672
+ const current = await readUserPath(subprocess, request.signal);
673
+ const state = planPathState(current, binDir, request.writePath);
674
+ if (binDir === "" || !request.writePath)
675
+ return state;
676
+ // 读失败:原因与手动命令已经由 planPathState 写进 error。这里既不备份空串,也不碰注册表——
677
+ // 备份空串等于没有回滚能力,而带 /f 的 reg add 会把用户整条用户级 Path 换成一条。
678
+ if (!current.readable)
679
+ return state;
680
+ const entry = toWindowsDir(binDir);
681
+ if (pathContains(current, entry)) {
682
+ state.done = true;
683
+ return state;
684
+ }
685
+ if (!WINDOWS) {
686
+ state.error =
687
+ "只有 Windows 有 HKCU\\Environment;当前平台请自己把 " + binDir + " 加进 shell 的 PATH";
688
+ return state;
689
+ }
690
+ const backup = writePathBackup(current.raw, env);
691
+ if (backup.error !== "") {
692
+ state.error = "备份旧 PATH 失败,为安全起见没写注册表:" + backup.error;
693
+ return state;
694
+ }
695
+ state.backup = backup.path;
696
+ const outcome = await runCapture(subprocess, {
697
+ argv: ["reg.exe", "add", PATH_KEY, "/v", "Path", "/t", "REG_EXPAND_SZ", "/d", state.after, "/f"],
698
+ timeoutMs: 15_000,
699
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
700
+ });
701
+ if (outcome.spawnError !== null) {
702
+ state.error = "reg add 起不来:" + outcome.spawnError;
703
+ return state;
704
+ }
705
+ if (outcome.exitCode !== 0) {
706
+ state.error =
707
+ "reg add 退出码 " +
708
+ String(outcome.exitCode) +
709
+ ":" +
710
+ (lastLine(outcome.stderr) || lastLine(outcome.stdout));
711
+ return state;
712
+ }
713
+ state.done = true;
714
+ state.changed = true;
715
+ return state;
716
+ }
717
+ /** 取消不是"解压失败":文案上必须分开,别让用户以为安装包坏了。 */
718
+ const EXTRACT_CANCELLED = "已取消(解压还没做完)";
719
+ /**
720
+ * 静默解压。
721
+ *
722
+ * 为什么不直接 -o<targetParent>:官方 sfx 里带一个顶层 msys64 目录,只有目标目录名恰好叫
723
+ * msys64 时"解压到父目录"才成立。先解到同级暂存目录再 rename,任何 targetDir 都成立;
724
+ * 而且暂存目录建在 targetDir 的父目录下,rename 是同盘操作,不会真拷几百 MB。
725
+ */
726
+ async function extractInstaller(subprocess, sfxPath, targetDir, request, timeoutMs) {
727
+ const parent = toPosix(dirname(targetDir));
728
+ const staging = parent + "/.dsh-msys2-staging";
729
+ // 只清自己建的暂存目录(固定名字):上次崩在中途,残渣也不会被当成成功。
730
+ removeDirQuietly(staging);
731
+ try {
732
+ mkdirSync(staging, { recursive: true });
733
+ }
734
+ catch (error) {
735
+ return {
736
+ ok: false,
737
+ cancelled: false,
738
+ detail: "建不了暂存目录 " + staging + ":" + describeError(error),
739
+ staging: "",
740
+ };
741
+ }
742
+ // 两种写法都试:7z SFX 认 -o<dir>,带引号的写法在含空格的路径上更稳。
743
+ const variants = [
744
+ ["-y", "-o" + staging],
745
+ ["-y", '-o"' + staging + '"'],
746
+ ];
747
+ let lastError = "";
748
+ let extractedRoot = "";
749
+ for (const args of variants) {
750
+ const outcome = await runCapture(subprocess, {
751
+ argv: [sfxPath, ...args],
752
+ cwd: staging,
753
+ timeoutMs,
754
+ maxBytes: 64 * 1024,
755
+ awaitQuiescence: true,
756
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
757
+ });
758
+ // A29:用户按了停止(或被上层 abort)不是"解压失败"。先判取消,别走失败路径去删暂存目录:
759
+ // 半份解压结果留着,下次进这里第一件事就是清它,不用用户自己收拾。
760
+ if (outcome.aborted || isAborted(request.signal)) {
761
+ return { ok: false, cancelled: true, detail: EXTRACT_CANCELLED, staging };
762
+ }
763
+ if (outcome.spawnError !== null) {
764
+ lastError = "安装包起不来:" + outcome.spawnError;
765
+ continue;
766
+ }
767
+ if (outcome.timedOut) {
768
+ lastError = "解压超时(" + String(Math.round(timeoutMs / 1000)) + " s)";
769
+ continue;
770
+ }
771
+ if (outcome.exitCode !== 0) {
772
+ lastError =
773
+ "退出码 " +
774
+ String(outcome.exitCode) +
775
+ ":" +
776
+ (lastLine(outcome.stderr) || lastLine(outcome.stdout) || "(无输出)");
777
+ continue;
778
+ }
779
+ const found = [staging + "/msys64", staging].find((dir) => isMsys2Root(dir));
780
+ if (found === undefined) {
781
+ lastError =
782
+ "解压完没找到 usr/bin/bash.exe;暂存目录内容:" + safeList(staging).slice(0, 8).join("、");
783
+ continue;
784
+ }
785
+ extractedRoot = found;
786
+ break;
787
+ }
788
+ if (extractedRoot === "") {
789
+ removeDirQuietly(staging);
790
+ return {
791
+ ok: false,
792
+ cancelled: false,
793
+ detail: lastError === "" ? "解压失败(没有更多信息)" : lastError,
794
+ staging: "",
795
+ };
796
+ }
797
+ try {
798
+ if (existsSync(targetDir)) {
799
+ if (safeList(targetDir).length > 0) {
800
+ return {
801
+ ok: false,
802
+ cancelled: false,
803
+ detail: "解压好了,但目标目录在解压期间变成非空:" +
804
+ targetDir +
805
+ "(没有覆盖它);解压结果留在 " +
806
+ extractedRoot,
807
+ staging,
808
+ };
809
+ }
810
+ // 只删空目录(rmdir 不会带走任何文件)。
811
+ rmdirSync(targetDir);
812
+ }
813
+ renameSync(extractedRoot, targetDir);
814
+ }
815
+ catch (error) {
816
+ return {
817
+ ok: false,
818
+ cancelled: false,
819
+ detail: "移动解压结果失败:" + describeError(error) + ";解压结果留在 " + extractedRoot,
820
+ staging,
821
+ };
822
+ }
823
+ removeDirQuietly(staging);
824
+ return { ok: true, cancelled: false, detail: targetDir, staging: "" };
825
+ }
826
+ /* ---------------------------- pacman 补包 ---------------------------- */
827
+ /**
828
+ * 整体升级一次。
829
+ * 为什么不再用 "pacman -Sy --noconfirm && pacman -S …":那是 Arch/MSYS2 官方明确劝阻的"局部升级",
830
+ * 陈旧的部分库配上新包会解不开依赖,用户只会在同一条命令上反复失败。
831
+ */
832
+ const PACMAN_UPGRADE_COMMAND = "pacman -Syu --noconfirm";
833
+ /** 一条 pacman 命令算不算成功(起不来 / 超时 / 非 0 都算失败)。 */
834
+ function pacmanOk(outcome) {
835
+ return outcome.spawnError === null && !outcome.timedOut && outcome.exitCode === 0;
836
+ }
837
+ /** 只用现有数据库补包:已有 MSYS2 上不先 -Sy,免得"局部升级"把依赖解析搞崩。 */
838
+ function pacmanInstallCommand(packages) {
839
+ return "pacman -S --noconfirm --needed " + packages.join(" ");
840
+ }
841
+ /** `pacman -Q <包名…>` 的输出 → { 包名 → 已装版本 };找不到的包只会出现在 stderr,这里天然收不到。 */
842
+ export function parsePacmanQuery(output) {
843
+ const found = new Map();
844
+ for (const raw of output.split(/\r?\n/u)) {
845
+ const line = raw.trim();
846
+ if (line === "")
847
+ continue;
848
+ const match = /^(\S+)\s+(\S+)$/u.exec(line);
849
+ if (match === null || match[1] === undefined || match[2] === undefined)
850
+ continue;
851
+ found.set(match[1], match[2]);
852
+ }
853
+ return found;
854
+ }
855
+ function bashLine(msys64, command) {
856
+ return (msys64 === "" ? "<msys64>" : msys64) + "/usr/bin/bash.exe -lc \"" + command + "\"";
857
+ }
858
+ /** keyring 没初始化时 pacman 会报这两类话:要先 pacman-key --init / --populate 再重试。 */
859
+ function needsKeyringInit(outcome) {
860
+ const text = (outcome.stdout + "\n" + outcome.stderr).toLowerCase();
861
+ return text.includes("keyring") || text.includes("invalid or corrupted package");
862
+ }
863
+ /* --------------------------- 步骤簿记 --------------------------- */
864
+ /**
865
+ * 安装中卡片的步骤骨架。
866
+ *
867
+ * 计划在"什么都不用做"时只返回一句话(steps 为空),但真装 job 的卡片仍需列出 7 步,
868
+ * 否则用户看到一个没有步骤的"安装中"卡片,不知道在等什么。
869
+ */
870
+ export function msys2StepSkeleton() {
871
+ return makeSteps();
872
+ }
873
+ function makeSteps() {
874
+ return STEP_DEFS.map((def) => ({ id: def.id, label: def.label, status: "pending", detail: "" }));
875
+ }
876
+ function stepOf(steps, id) {
877
+ for (const step of steps) {
878
+ if (step.id === id)
879
+ return step;
880
+ }
881
+ const created = { id, label: id, status: "pending", detail: "" };
882
+ steps.push(created);
883
+ return created;
884
+ }
885
+ function setStep(step, status, detail) {
886
+ step.status = status;
887
+ step.detail = detail;
888
+ }
889
+ function beginStep(steps, step, onProgress) {
890
+ step.status = "running";
891
+ if (onProgress !== undefined) {
892
+ onProgress("[" + String(steps.indexOf(step) + 1) + "/" + String(steps.length) + "] " + step.label + "…");
893
+ }
894
+ }
895
+ /** 关键步骤失败后把后面还 pending 的标成 skipped,避免卡片上出现"一半 pending"的歧义。 */
896
+ function skipAfter(steps, id, detail) {
897
+ let seen = false;
898
+ for (const step of steps) {
899
+ if (seen && step.status === "pending")
900
+ setStep(step, "skipped", detail);
901
+ if (step.id === id)
902
+ seen = true;
903
+ }
904
+ }
905
+ function shortPackageName(name) {
906
+ return name.replace("mingw-w64-ucrt-x86_64-", "");
907
+ }
908
+ /**
909
+ * 计划模式下每步写清"将要做什么",**以及已经不需要做什么**。
910
+ *
911
+ * 这里最容易犯的错是把"用户机器上早就装齐了"也写成"待执行":
912
+ * 计划卡片一边说"已存在的完整 MSYS2 直接复用",一边说"下载 43.1 MB 安装包",
913
+ * 用户会以为要重装。所以凡是能只读判断出来的,都据实标 skipped 并写原因。
914
+ */
915
+ function fillPlanDetails(steps, context) {
916
+ const rootLabel = context.msys64 === "" ? "(装哪还没定)" : context.msys64;
917
+ setStep(stepOf(steps, "prepare"), context.existing ? "skipped" : "pending", context.msys64 === ""
918
+ ? "目标目录待定;定了之后先确保它的父目录存在"
919
+ : context.existing
920
+ ? context.msys64 + " 里已经有一份能用的 MSYS2(有 usr/bin/bash.exe),不用建目录、不用重装"
921
+ : "确保父目录存在:" +
922
+ (context.parent === "" ? context.msys64 : context.parent) +
923
+ "(目标目录不存在或不是完整 MSYS2 时才会装)");
924
+ setStep(stepOf(steps, "download"), context.existing ? "skipped" : "pending", context.existing
925
+ ? "已有完整 MSYS2,不需要安装包(省 " + formatBytes(MSYS2_INSTALLER_BYTES) + " 下载)"
926
+ : context.cacheOk
927
+ ? "复用缓存:" + context.cachePath + "(" + formatBytes(MSYS2_INSTALLER_BYTES) + ",不会再下载)"
928
+ : "按候选链下载(国内镜像优先,GitHub 兜底),第一个成功的落盘到 " +
929
+ context.cachePath +
930
+ "(约 " +
931
+ formatBytes(MSYS2_INSTALLER_BYTES) +
932
+ ",curl -C - 断点续传、10 s 内不足 1 KB/s 就换源;缓存已有且是有效 exe 直接复用,命令示例:curl.exe -L --fail -C - -o " +
933
+ context.cachePath +
934
+ " " +
935
+ context.cacheUrl +
936
+ ")");
937
+ setStep(stepOf(steps, "extract"), context.existing ? "skipped" : "pending", context.existing
938
+ ? "已有 MSYS2,不需要解压"
939
+ : context.msys64 === ""
940
+ ? "把安装包静默解压到同级暂存目录,再把解压出的 msys64 移到目标目录(不覆盖已有目录)"
941
+ : context.cachePath + " -y -o" + context.parent + " → 再把解压出的 msys64 移到 " + context.msys64);
942
+ const missingDetail = context.pacmanUnknown
943
+ ? "计划里没问出来(pacman 超时或起不来):真装时会先 pacman -Q 问一遍,只补缺的包,已装的包不动、也不升级(要升级自己跑 pacman -Syu)"
944
+ : context.missing.length === 0
945
+ ? context.packages
946
+ .map((name) => shortPackageName(name) + " " + (context.installed.get(name) ?? ""))
947
+ .join("、") + " 都已经装了,不会重复安装,也不升级(要升级自己跑 pacman -Syu)"
948
+ : context.existing
949
+ ? "先 pacman -Q 问过一遍:缺 " +
950
+ String(context.missing.length) +
951
+ " 个(" +
952
+ context.missing.map(shortPackageName).join("、") +
953
+ ");将跑 pacman -S --noconfirm --needed " +
954
+ context.missing.join(" ") +
955
+ "(已装的 " +
956
+ String(context.installed.size) +
957
+ " 个不动,也不升级)"
958
+ : bashLine(context.msys64, "pacman -Q " + context.packages.join(" ")) +
959
+ ":先问一遍装没装,已装的直接跳过(不重复安装、也不擅自升级);只对缺的包跑 pacman -S --noconfirm --needed <缺的包>;" +
960
+ "刚解压出来、一件包都还没装的那种空库,会先整体升级一次(pacman -Syu --noconfirm)再补包 —— " +
961
+ "不会做「-Sy 之后立刻 -S 单个包」那种局部升级,那在 MSYS2 上会解不开依赖。";
962
+ setStep(stepOf(steps, "pacman"), context.missing.length === 0 ? "skipped" : "pending", missingDetail);
963
+ setStep(stepOf(steps, "path"), !context.writePath || context.pathEntryPresent ? "skipped" : "pending", !context.writePath
964
+ ? "writePath=false:不动 PATH(失败也不致命,插件按配置里的绝对路径找工具)"
965
+ : context.binDir === ""
966
+ ? "把 <msys64>/ucrt64/bin 追加到用户级 PATH"
967
+ : context.pathEntryPresent
968
+ ? "用户 PATH 里已经有 " + toWindowsDir(context.binDir) + ",不会重复写"
969
+ : context.pathError !== ""
970
+ ? "⚠ 会失败:" + context.pathError
971
+ : "把 " +
972
+ toWindowsDir(context.binDir) +
973
+ " 追加到用户级 PATH(HKCU\\Environment,REG_EXPAND_SZ;旧值先备份)");
974
+ setStep(stepOf(steps, "verify"), context.verifyOk ? "done" : "pending", context.verifyText !== ""
975
+ ? context.verifyOk
976
+ ? context.verifyText + "(计划模式只读跑了一遍,没装任何东西)"
977
+ : "现在:" + context.verifyText + ";补完包会再跑一次"
978
+ : context.binDir === ""
979
+ ? "用装好的 bin 目录跑 gcc / cmake / ninja / openocd / gdb 的版本命令"
980
+ : "用 " + context.binDir + " 跑 gcc / cmake / ninja / openocd / gdb 的版本命令");
981
+ setStep(stepOf(steps, "config"), context.configMatches ? "skipped" : "pending", context.configMatches
982
+ ? "配置已经是这个样子(" + context.configPath + " 里 msys64 与 packages 都对得上),不用改"
983
+ : "写 " +
984
+ context.configPath +
985
+ ":msys64=" +
986
+ rootLabel +
987
+ "、binDirs、packages(与已有 packages 合并去重,不动 cubeMxRoot)");
988
+ }
989
+ /* ------------------------------ 文案 ------------------------------ */
990
+ /**
991
+ * 计划卡片的第一句话:按"实际要做什么"分三档,别把"已经装好了"说成"要装"。
992
+ *
993
+ * 三种现场:
994
+ * 1. 已装齐(existing && 无缺件)→ 什么都不用做;
995
+ * 2. 已有 MSYS2 但缺包 → 只补缺的,不下载安装包;
996
+ * 3. 全新安装 → 原来的文案(下载安装包 + 补全部组件)。
997
+ */
998
+ function planMessage(msys64, via, packages, download, facts) {
999
+ if (facts.existing && facts.missing.length === 0) {
1000
+ return ("什么都不用装:MSYS2 已经在 " +
1001
+ msys64 +
1002
+ "(来源:" +
1003
+ viaLabel(via) +
1004
+ ",有 usr/bin/bash.exe)," +
1005
+ String(packages.length) +
1006
+ " 个组件也都装着" +
1007
+ (facts.pathEntryPresent ? ",用户 PATH 里也有它" : "") +
1008
+ (facts.configMatches ? ",配置已经写好" : "") +
1009
+ "。没有下载、没有建目录、没有写注册表、没有改配置。");
1010
+ }
1011
+ if (facts.existing && facts.pacmanUnknown) {
1012
+ return ("计划(还没动手):复用 " +
1013
+ msys64 +
1014
+ " 里已有的 MSYS2(来源:" +
1015
+ viaLabel(via) +
1016
+ ");计划里没问出这 " +
1017
+ String(packages.length) +
1018
+ " 个组件装没装(pacman 超时或起不来),真装时会先 pacman -Q 问一遍,只补缺的,已装的包不动、也不升级。" +
1019
+ "确认后才真装——现在没有下载、没有建目录、没有写注册表、没有改配置。");
1020
+ }
1021
+ if (facts.existing) {
1022
+ return ("计划(还没动手):复用 " +
1023
+ msys64 +
1024
+ " 里已有的 MSYS2(来源:" +
1025
+ viaLabel(via) +
1026
+ "),只补 " +
1027
+ String(facts.missing.length) +
1028
+ " 个组件(缺 " +
1029
+ facts.missing.map(shortPackageName).join("、") +
1030
+ ");不用下载安装包,已装的 " +
1031
+ String(facts.installed.size) +
1032
+ " 个不动、也不升级。确认后才真装——现在什么都没动。");
1033
+ }
1034
+ return ("计划(还没动手):把 MSYS2 装到 " +
1035
+ msys64 +
1036
+ "(来源:" +
1037
+ viaLabel(via) +
1038
+ "),再补 " +
1039
+ String(packages.length) +
1040
+ " 个组件;安装包 " +
1041
+ formatBytes(download.bytes) +
1042
+ (download.cached ? "(本机已有缓存,不会再下载)" : "(需要下载)") +
1043
+ "。确认后才真装——现在没有下载、没有建目录、没有写注册表、没有改配置。");
1044
+ }
1045
+ /** 没有现场事实时(真装路径、目录还没定时)的默认值:一律按"没装过"处理。 */
1046
+ function emptyFacts(packages) {
1047
+ return {
1048
+ existing: false,
1049
+ installed: new Map(),
1050
+ missing: [...packages],
1051
+ cacheOk: false,
1052
+ pacmanUnknown: false,
1053
+ pathEntryPresent: false,
1054
+ pathError: "",
1055
+ configMatches: false,
1056
+ verifyOk: false,
1057
+ verifyText: "",
1058
+ };
1059
+ }
1060
+ /** 用量估算:已装齐就明说"不用下载任何东西",别让用户以为要重装。 */
1061
+ function usageNote(facts, download, packages) {
1062
+ if (facts !== null && facts.existing && facts.missing.length === 0) {
1063
+ return "用量估算:不用下载任何东西(MSYS2 与 " + String(packages.length) + " 个组件都已在本机)。";
1064
+ }
1065
+ if (facts !== null && facts.existing && facts.pacmanUnknown) {
1066
+ return "用量估算:不用下载安装包;缺几个包要等真装时 pacman -Q 才知道(已装的包不动、也不升级)。";
1067
+ }
1068
+ if (facts !== null && facts.existing) {
1069
+ return ("用量估算:不用下载安装包;只补 " +
1070
+ String(facts.missing.length) +
1071
+ " 个包,pacman 下载约 " +
1072
+ formatBytes(msys2PackagesTotal(facts.missing)) +
1073
+ "(按单包大小估算,实际以 pacman 为准)。");
1074
+ }
1075
+ return ("用量估算:安装包 " +
1076
+ formatBytes(download.bytes) +
1077
+ (download.cached ? "(已缓存)" : "") +
1078
+ " + pacman 分包下载约 " +
1079
+ formatBytes(msys2PackagesTotal(packages)) +
1080
+ ";装完磁盘占用约 " +
1081
+ formatBytes((MSYS2_INSTALLER_BYTES + msys2PackagesTotal(packages)) * 3) +
1082
+ "(估算:安装包 + 分包的总量按 3 倍粗算,含解压后的文件与 pacman 缓存,不是精确占用)。");
1083
+ }
1084
+ function decisionMessage(suggested, packages, download) {
1085
+ return ("需要你先决定装哪:这台机器上没有可用的 MSYS2(配置里没有、自动扫描也没找到 usr/bin/bash.exe)," +
1086
+ "我不猜路径。建议装到 " +
1087
+ suggested +
1088
+ "(安装包 " +
1089
+ formatBytes(download.bytes) +
1090
+ " + 分包约 " +
1091
+ formatBytes(msys2PackagesTotal(packages)) +
1092
+ " 估算)。给我 targetDir、或回一句「装到 " +
1093
+ suggested +
1094
+ "」,我再出计划;现在什么都没装。");
1095
+ }
1096
+ function verifySummary(verify) {
1097
+ const found = verify.tools.filter((tool) => tool.found);
1098
+ const missing = verify.tools.filter((tool) => !tool.found);
1099
+ if (missing.length === 0) {
1100
+ if (found.length === 0)
1101
+ return "自检没有可跑的组件";
1102
+ const versions = found
1103
+ .map((tool) => tool.id + (tool.version === "" ? "" : " " + tool.version))
1104
+ .join("、");
1105
+ return "5 个组件都能跑(" + versions + ")";
1106
+ }
1107
+ return "缺 " + missing.map((tool) => tool.label).join("、");
1108
+ }
1109
+ /**
1110
+ * path 是不是在 dir 之下(大小写与斜杠不敏感)。
1111
+ * 自检用它确认"跑起来的那个工具"确实来自目标 binDir,而不是 PATH 上的同名文件。
1112
+ */
1113
+ function isInsideDir(path, dir) {
1114
+ const base = toPosix(dir).replace(/\/+$/u, "").toLowerCase();
1115
+ const target = toPosix(path).replace(/\/+$/u, "").toLowerCase();
1116
+ if (base === "" || target === "")
1117
+ return false;
1118
+ return target === base || target.startsWith(base + "/");
1119
+ }
1120
+ function toVerifyState(results) {
1121
+ return {
1122
+ ok: results.length > 0 && results.every((result) => result.found),
1123
+ tools: results.map((result) => ({
1124
+ id: result.id,
1125
+ label: result.label,
1126
+ found: result.found,
1127
+ version: result.version,
1128
+ })),
1129
+ };
1130
+ }
1131
+ /** curl 的一次调用:返回退出码/超时/spawn 错误,调用方自己决定"这条线算不算死"。 */
1132
+ async function curlOnce(subprocess, url, partPath, cacheDir, timeoutMs, resume, signal) {
1133
+ const argv = [
1134
+ WINDOWS ? "curl.exe" : "curl",
1135
+ "-L",
1136
+ "--fail",
1137
+ "--retry",
1138
+ "2",
1139
+ "--connect-timeout",
1140
+ "20",
1141
+ // F3c:10 s 内平均不足 1 KB/s 就自己退出(退出码 28),由外层换下一个源。
1142
+ "--speed-limit",
1143
+ String(DOWNLOAD_MIN_BYTES_PER_SEC),
1144
+ "--speed-time",
1145
+ String(Math.round(DOWNLOAD_STALL_MS / 1000)),
1146
+ ];
1147
+ // F3c:-C - 断点续传。缓存目录里有 .part 时从它的长度接着下;没有就当普通下载。
1148
+ if (resume)
1149
+ argv.push("-C", "-");
1150
+ argv.push("-o", partPath, url);
1151
+ return runCapture(subprocess, {
1152
+ argv,
1153
+ cwd: cacheDir,
1154
+ timeoutMs,
1155
+ maxBytes: 64 * 1024,
1156
+ ...(signal === undefined ? {} : { signal }),
1157
+ });
1158
+ }
1159
+ /**
1160
+ * 按候选链下载安装包(F3a):一个源不通就换下一个,全都不通才报错。
1161
+ *
1162
+ * 换源时**一定从零开始**(先删 .part):镜像与 GitHub 的包体字节数不同(同步时点不同),
1163
+ * 把 A 源的前半段接在 B 源的后半段上,拼出来的 exe 一定解不开。
1164
+ * 同一个源内部的续传是安全的:curl -C - 续的是同一条线路上的同一个文件。
1165
+ */
1166
+ async function downloadInstaller(subprocess, urls, partPath, cacheDir, request, timeoutMs) {
1167
+ const attempts = [];
1168
+ for (const [index, url] of urls.entries()) {
1169
+ if (isAborted(request.signal))
1170
+ return { ok: false, bytes: 0, url: "", attempts };
1171
+ request.onProgress?.("下载 " + formatBytes(MSYS2_INSTALLER_BYTES) + "(" +
1172
+ installerSourceLabel(url) + ",第 " + String(index + 1) + "/" + String(urls.length) + " 个候选):" + url);
1173
+ removeFileQuietly(partPath);
1174
+ let outcome = await curlOnce(subprocess, url, partPath, cacheDir, timeoutMs, true, request.signal);
1175
+ // 33 = 服务器不支持字节范围,续传请求被拒;去掉 -C - 再来一次(从头下)。
1176
+ if (outcome.exitCode === 33) {
1177
+ removeFileQuietly(partPath);
1178
+ outcome = await curlOnce(subprocess, url, partPath, cacheDir, timeoutMs, false, request.signal);
1179
+ }
1180
+ const bytes = fileSize(partPath);
1181
+ if (outcome.spawnError !== null) {
1182
+ attempts.push(installerSourceLabel(url) + " → curl 起不来:" + outcome.spawnError);
1183
+ removeFileQuietly(partPath);
1184
+ continue;
1185
+ }
1186
+ if (outcome.timedOut) {
1187
+ attempts.push(installerSourceLabel(url) + " → 超时(" + String(Math.round(timeoutMs / 1000)) + " s," + formatBytes(bytes) + ")");
1188
+ removeFileQuietly(partPath);
1189
+ continue;
1190
+ }
1191
+ if (outcome.exitCode !== 0) {
1192
+ const detail = lastLine(outcome.stderr) || lastLine(outcome.stdout) || "(无输出)";
1193
+ // 28 是 --speed-time 触发的"太慢",单独说清楚,否则用户只看到一个退出码。
1194
+ const kind = outcome.exitCode === 28 ? "太慢(10 s 内不足 1 KB/s)" : "退出码 " + String(outcome.exitCode);
1195
+ attempts.push(installerSourceLabel(url) + " → " + kind + ":" + detail);
1196
+ removeFileQuietly(partPath);
1197
+ continue;
1198
+ }
1199
+ if (bytes < MIN_INSTALLER_BYTES) {
1200
+ attempts.push(installerSourceLabel(url) + " → 只下到 " + formatBytes(bytes) + "(小于 " + formatBytes(MIN_INSTALLER_BYTES) + ",像半截文件或错误页)");
1201
+ removeFileQuietly(partPath);
1202
+ continue;
1203
+ }
1204
+ if (!looksLikeExecutable(partPath)) {
1205
+ attempts.push(installerSourceLabel(url) + " → 下回来的开头不是 MZ(不是 exe)");
1206
+ removeFileQuietly(partPath);
1207
+ continue;
1208
+ }
1209
+ return { ok: true, bytes, url, attempts };
1210
+ }
1211
+ removeFileQuietly(partPath);
1212
+ return { ok: false, bytes: 0, url: "", attempts };
1213
+ }
1214
+ export async function planOrInstallMsys2(subprocess, request, env = process.env) {
1215
+ const started = Date.now();
1216
+ const configRead = readToolchainConfig(env);
1217
+ const target = resolveTargetDir(request.targetDir, configRead.config, env);
1218
+ const suggested = target.msys64 === "" ? suggestMsys64Root(env) : "";
1219
+ const packages = dedupeStrings(request.packages !== undefined && request.packages.length > 0
1220
+ ? request.packages
1221
+ : [...DEFAULT_MSYS2_PACKAGES]);
1222
+ const installer = resolveInstallerUrls(env);
1223
+ // 计划卡片上只能写一个地址:写候选链的第一个(真装时按链逐个试)。
1224
+ const primaryUrl = installer.urls[0] ?? MSYS2_INSTALLER_URL;
1225
+ const cachePath = cacheFilePath(env);
1226
+ // F3d:缓存只认「MZ 头 + ≥40 MB」。半截文件被当成已下好,解压就会永远失败。
1227
+ const cachedBytes = cachedInstallerBytes(cachePath);
1228
+ const cachedOk = cachedBytes > 0;
1229
+ const msys64 = target.msys64;
1230
+ const binDir = msys64 === "" ? "" : msys64 + "/ucrt64/bin";
1231
+ const parent = msys64 === "" ? "" : toPosix(dirname(msys64));
1232
+ let download = {
1233
+ url: primaryUrl,
1234
+ bytes: cachedOk ? cachedBytes : MSYS2_INSTALLER_BYTES,
1235
+ cached: cachedOk,
1236
+ };
1237
+ const steps = makeSteps();
1238
+ const userPath = await readUserPath(subprocess, request.signal);
1239
+ let pathState = planPathState(userPath, binDir, request.writePath);
1240
+ const notes = [];
1241
+ if (target.warning !== "")
1242
+ notes.push("⚠ " + target.warning);
1243
+ const warningPrefix = target.warning === "" ? "" : "⚠ " + target.warning + ";";
1244
+ notes.push("装完后插件按配置里的绝对路径找工具" +
1245
+ (binDir === "" ? "" : "(" + binDir + ")") +
1246
+ ",本进程不需要重读环境变量,也不要求重开 DSH。");
1247
+ notes.push("刻意没做卸载:要删就删安装目录" +
1248
+ (msys64 === "" ? "" : " " + msys64) +
1249
+ " 并去掉配置里的 msys64 / binDirs 两项,PATH 里那条也手动删掉。");
1250
+ if (installer.note !== "")
1251
+ notes.push(installer.note);
1252
+ // -- 计划模式:零副作用(只做只读判断:pacman -Q、版本命令、读注册表)--------
1253
+ if (request.mode !== "install") {
1254
+ const existing = isMsys2Root(msys64);
1255
+ const bashPath = msys64 === "" ? "" : msys64 + "/usr/bin/bash.exe";
1256
+ const pacmanExe = msys64 === "" ? "" : msys64 + "/usr/bin/pacman.exe";
1257
+ let installed = new Map();
1258
+ let missing = [...packages];
1259
+ let pacmanUnknown = false;
1260
+ if (existing && (pacmanExe !== "" && existsSync(pacmanExe) || existsSync(bashPath))) {
1261
+ // 只读:问一句"装没装",与真装第 4 步同一个命令。
1262
+ // 计划因此不会把"已经装好的 5 个包"说成"再补 5 个组件"。
1263
+ // 优先直接跑 pacman.exe:少了 bash 起 profile 那一步(本机实测 11 s → 6.5 s)。
1264
+ const argv = pacmanExe !== "" && existsSync(pacmanExe)
1265
+ ? [pacmanExe, "-Q", ...packages]
1266
+ : [bashPath, "-lc", "pacman -Q " + packages.join(" ")];
1267
+ const query = await runCapture(subprocess, {
1268
+ argv,
1269
+ cwd: msys64,
1270
+ timeoutMs: PACMAN_QUERY_TIMEOUT_MS,
1271
+ maxBytes: 512 * 1024,
1272
+ awaitQuiescence: true,
1273
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
1274
+ });
1275
+ if (query.spawnError === null && !query.timedOut) {
1276
+ installed = parsePacmanQuery(query.stdout);
1277
+ missing = packages.filter((name) => !installed.has(name));
1278
+ // 一条都没解析出来、退出码又不是 0:多半是 pacman 自己在报错(不是"全都没装")。
1279
+ if (installed.size === 0 && (query.exitCode ?? 1) !== 0)
1280
+ pacmanUnknown = true;
1281
+ }
1282
+ else {
1283
+ pacmanUnknown = true;
1284
+ notes.push("⚠ 计划里问不了 pacman(" +
1285
+ (query.spawnError !== null ? query.spawnError : "超时") +
1286
+ "):真装时会先 pacman -Q 再决定装哪几个,这里不猜。");
1287
+ }
1288
+ }
1289
+ // 计划模式也真跑一遍自检:只读、只跑版本命令,结论能直接回答"现在到底能不能用"。
1290
+ let planProbed = [];
1291
+ let verifyOk = false;
1292
+ let verifyText = "";
1293
+ // CubeMX 不在这 5 件里,但它决定能不能走 HAL 路线:缺它时紧凑卡片必须补一句,
1294
+ // 否则"工具链完整"会让人以为 HAL 工程也能直接生成。
1295
+ let cubemxReady = false;
1296
+ if (binDir !== "" && existsSync(binDir)) {
1297
+ const searchConfig = resolveSearchConfig(env);
1298
+ const probeConfig = { binDirs: [binDir], cubeMxRoots: [...searchConfig.cubeMxRoots] };
1299
+ const wanted = buildTargets(probeConfig);
1300
+ const probeWanted = wanted.filter((item) => VERIFY_IDS.includes(item.id));
1301
+ planProbed = await probeAll(subprocess, probeWanted, probeConfig, {
1302
+ timeoutMs: PROBE_TIMEOUT_MS,
1303
+ allowPathFallback: false,
1304
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
1305
+ });
1306
+ const probedState = toVerifyState(planProbed);
1307
+ verifyOk = probedState.ok;
1308
+ verifyText = probedState.ok
1309
+ ? verifySummary(probedState)
1310
+ : "缺 " +
1311
+ probedState.tools
1312
+ .filter((tool) => !tool.found)
1313
+ .map((tool) => tool.label)
1314
+ .join("、");
1315
+ // 两项都要找到才算装好:只有 STM32CubeMX.exe、没有 jre/bin/java.exe 时无头生成仍会失败。
1316
+ const cubemxProbed = await probeAll(subprocess, wanted.filter((item) => item.id === "cubemx" || item.id === "cubemx-java"), probeConfig, {
1317
+ timeoutMs: PROBE_TIMEOUT_MS,
1318
+ allowPathFallback: false,
1319
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
1320
+ });
1321
+ cubemxReady = cubemxProbed.length === 2 && cubemxProbed.every((item) => item.found);
1322
+ }
1323
+ const currentConfig = configRead.config;
1324
+ const configMatches = currentConfig !== null &&
1325
+ toPosix(currentConfig.msys64) === toPosix(msys64) &&
1326
+ (currentConfig.binDirs.length === 0 ||
1327
+ currentConfig.binDirs.some((dir) => toPosix(dir) === toPosix(binDir))) &&
1328
+ packages.every((name) => currentConfig.packages.includes(name));
1329
+ const facts = {
1330
+ existing,
1331
+ installed,
1332
+ missing,
1333
+ cacheOk: cachedOk,
1334
+ pacmanUnknown,
1335
+ pathEntryPresent: binDir !== "" && userPath.readable && pathContains(userPath, toWindowsDir(binDir)),
1336
+ pathError: pathState.error,
1337
+ configMatches,
1338
+ verifyOk,
1339
+ verifyText,
1340
+ };
1341
+ // 已有 MSYS2 时"下载 0 字节"才是实话:安装包根本不会碰。
1342
+ if (existing)
1343
+ download = { url: primaryUrl, bytes: 0, cached: cachedOk };
1344
+ const decided = msys64 !== "";
1345
+ const nothingToDo = decided && existing && missing.length === 0 && !pacmanUnknown;
1346
+ // 什么都不用做时只回一句话:不列 7 个"已跳过"的步骤,也不贴 notes。
1347
+ // 卡片上把"没有可做的事"画成七行详情,用户会以为还有一堆动作在排队。
1348
+ if (nothingToDo && verifyOk) {
1349
+ return {
1350
+ ok: true,
1351
+ mode: "plan",
1352
+ needsDecision: "",
1353
+ msys64,
1354
+ resolvedVia: target.via,
1355
+ binDirs: binDir === "" ? [] : [binDir],
1356
+ packages,
1357
+ steps: [],
1358
+ download,
1359
+ path: pathState,
1360
+ config: { path: configRead.path, written: false, error: "" },
1361
+ verify: toVerifyState(planProbed),
1362
+ message: warningPrefix +
1363
+ "工具链完整,不需要装任何东西:" +
1364
+ packages.length +
1365
+ " 个组件都能跑,PATH 与配置都已就位(" +
1366
+ (binDir === "" ? msys64 : binDir) +
1367
+ ")。" +
1368
+ (cubemxReady
1369
+ ? ""
1370
+ : "要写 HAL 库程序还需要从 ST 官网装 STM32CubeMX(含内置 JRE,约 1.5 GB," +
1371
+ "https://www.st.com/en/development-tools/stm32cubemx.html);纯寄存器程序不需要它。"),
1372
+ nextStep: "",
1373
+ notes: [],
1374
+ durationMs: Date.now() - started,
1375
+ };
1376
+ }
1377
+ fillPlanDetails(steps, {
1378
+ ...facts,
1379
+ msys64,
1380
+ parent,
1381
+ binDir,
1382
+ packages,
1383
+ cachePath,
1384
+ cacheUrl: primaryUrl,
1385
+ configPath: configRead.path,
1386
+ writePath: request.writePath,
1387
+ });
1388
+ notes.push(usageNote(facts, download, packages));
1389
+ notes.push("这只是计划:没有下载、没有建目录、没有写注册表、没有改配置。");
1390
+ const confirmHint = nothingToDo
1391
+ ? "已经齐了:直接 stm32_env_probe 看四项能力,或 stm32_build 编译;要换一份 MSYS2 就传 targetDir。"
1392
+ : existing && pacmanUnknown
1393
+ ? "确认无误就带 confirm:true、dryRun:false 再调一次(真装时会先 pacman -Q,只补缺的包,不升级已装的);想只装指定包就传 packages。"
1394
+ : existing
1395
+ ? "确认无误就带 confirm:true、dryRun:false 再调一次(只补缺的 " +
1396
+ String(missing.length) +
1397
+ " 个包,不升级已装的);想只装指定包就传 packages。"
1398
+ : "确认无误就带 confirm:true、dryRun:false 再调一次(会真下载并安装);只想装指定包就传 packages。";
1399
+ return {
1400
+ ok: decided,
1401
+ mode: "plan",
1402
+ needsDecision: decided ? "" : "msys64Dir",
1403
+ msys64,
1404
+ resolvedVia: target.via,
1405
+ binDirs: binDir === "" ? [] : [binDir],
1406
+ packages,
1407
+ steps,
1408
+ download,
1409
+ path: pathState,
1410
+ config: { path: configRead.path, written: false, error: "" },
1411
+ verify: toVerifyState(planProbed),
1412
+ message: warningPrefix +
1413
+ (decided
1414
+ ? planMessage(msys64, target.via, packages, download, facts)
1415
+ : decisionMessage(suggested, packages, download)),
1416
+ nextStep: decided
1417
+ ? confirmHint
1418
+ : "定下安装位置(targetDir,或回一句「装到 " + suggested + "」),我再出一份计划。",
1419
+ notes,
1420
+ durationMs: Date.now() - started,
1421
+ };
1422
+ }
1423
+ // -- 真装:不知道装哪就一步都不做 ------------------------------------
1424
+ if (msys64 === "") {
1425
+ fillPlanDetails(steps, {
1426
+ ...emptyFacts(packages),
1427
+ msys64,
1428
+ parent,
1429
+ binDir,
1430
+ packages,
1431
+ cachePath,
1432
+ cacheUrl: primaryUrl,
1433
+ configPath: configRead.path,
1434
+ writePath: request.writePath,
1435
+ });
1436
+ return {
1437
+ ok: false,
1438
+ mode: "install",
1439
+ needsDecision: "msys64Dir",
1440
+ msys64: "",
1441
+ resolvedVia: "",
1442
+ binDirs: [],
1443
+ packages,
1444
+ steps,
1445
+ download,
1446
+ path: pathState,
1447
+ config: { path: configRead.path, written: false, error: "" },
1448
+ verify: { ok: false, tools: [] },
1449
+ message: warningPrefix + decisionMessage(suggested, packages, download),
1450
+ nextStep: "带上 targetDir 再调一次(例如 targetDir=\"" + suggested + "\")。",
1451
+ notes,
1452
+ durationMs: Date.now() - started,
1453
+ };
1454
+ }
1455
+ const timeoutMs = request.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
1456
+ const alreadyInstalled = isMsys2Root(msys64);
1457
+ let verifyState = { ok: false, tools: [] };
1458
+ let configState = { path: configRead.path, written: false, error: "" };
1459
+ const finish = (ok, message, nextStep) => ({
1460
+ ok,
1461
+ mode: "install",
1462
+ needsDecision: "",
1463
+ msys64,
1464
+ resolvedVia: target.via,
1465
+ binDirs: [binDir],
1466
+ packages,
1467
+ steps,
1468
+ download,
1469
+ path: pathState,
1470
+ config: configState,
1471
+ verify: verifyState,
1472
+ message,
1473
+ nextStep,
1474
+ notes,
1475
+ durationMs: Date.now() - started,
1476
+ });
1477
+ const prepareStep = stepOf(steps, "prepare");
1478
+ const downloadStep = stepOf(steps, "download");
1479
+ const extractStep = stepOf(steps, "extract");
1480
+ const pacmanStep = stepOf(steps, "pacman");
1481
+ const pathStep = stepOf(steps, "path");
1482
+ const verifyStep = stepOf(steps, "verify");
1483
+ const configStep = stepOf(steps, "config");
1484
+ const abortRest = (step) => {
1485
+ setStep(step, "failed", "已取消");
1486
+ skipAfter(steps, step.id, "上一步被取消,未执行");
1487
+ return finish(false, "已取消:已经做过的步骤都留着了(不删任何东西)。", "需要时再调一次;已完成的步骤会自动跳过,不会重复下载、不会重复写 PATH。");
1488
+ };
1489
+ // a) 准备目录
1490
+ beginStep(steps, prepareStep, request.onProgress);
1491
+ if (isAborted(request.signal))
1492
+ return abortRest(prepareStep);
1493
+ if (alreadyInstalled) {
1494
+ setStep(prepareStep, "done", msys64 + " 里已经有一份能用的 MSYS2(有 usr/bin/bash.exe),跳过下载与解压");
1495
+ }
1496
+ else {
1497
+ try {
1498
+ const mkdirError = ensureParentDir(parent);
1499
+ if (mkdirError !== "")
1500
+ throw new Error(mkdirError + "(父目录 " + parent + ")");
1501
+ if (existsSync(msys64)) {
1502
+ const entries = safeList(msys64);
1503
+ if (entries.length > 0) {
1504
+ setStep(prepareStep, "failed", "目标目录已存在且非空(" +
1505
+ String(entries.length) +
1506
+ " 项),但不是完整 MSYS2(缺 usr/bin/bash.exe)");
1507
+ skipAfter(steps, "prepare", "目标目录不可用,未执行");
1508
+ return finish(false, "没有开始:目标目录 " + msys64 + " 已存在且不是一份完整 MSYS2,我不覆盖也不删除它。", "换一个空目录(例如 " +
1509
+ (msys64 === MSYS2_SUGGESTED_ROOT ? "D:/msys64" : MSYS2_SUGGESTED_ROOT) +
1510
+ ")再装,或先确认那个目录里放的是什么。");
1511
+ }
1512
+ }
1513
+ setStep(prepareStep, "done", "父目录就绪:" + parent);
1514
+ }
1515
+ catch (error) {
1516
+ const reason = describeError(error);
1517
+ setStep(prepareStep, "failed", reason);
1518
+ skipAfter(steps, "prepare", "父目录建不了,未执行");
1519
+ // 0c:失败时给一条不依赖本工具的手动兜底——下载好的 sfx 安装包自己就能解压,
1520
+ // 手动装好后重跑本工具会直接走 alreadyInstalled(检测的是 usr/bin/bash.exe,不是本工具写的标记)。
1521
+ const manualSteps = [
1522
+ "手动兜底(不依赖本工具):",
1523
+ " 1. 下载安装包(任一源都行):" + primaryUrl,
1524
+ " 2. 手动解压到目标盘:进入下载目录后执行 <安装包文件> -y -o" + (parent === "" ? "C:\\\\" : toWindowsDir(parent)),
1525
+ " (sfx 会在所选目录下解压出 msys64/;把它改名或移动到 " + msys64 + " 即可)",
1526
+ " 3. 重跑本工具:它会检测到 usr/bin/bash.exe 并直接复用,不再下载、不再解压。",
1527
+ ].join("\n");
1528
+ return finish(false, "没能准备安装目录:" + reason, "检查路径是否合法、有没有写权限,或换一个 targetDir。\n" + manualSteps);
1529
+ }
1530
+ }
1531
+ // b) 下载安装包
1532
+ beginStep(steps, downloadStep, request.onProgress);
1533
+ if (isAborted(request.signal))
1534
+ return abortRest(downloadStep);
1535
+ if (alreadyInstalled) {
1536
+ setStep(downloadStep, "skipped", "目标里已有 MSYS2,不需要安装包");
1537
+ }
1538
+ else if (cachedOk) {
1539
+ download = { url: primaryUrl, bytes: cachedBytes, cached: true };
1540
+ setStep(downloadStep, "done", "复用缓存:" + cachePath + "(" + formatBytes(cachedBytes) + ")");
1541
+ }
1542
+ else {
1543
+ const cacheDir = toPosix(dirname(cachePath));
1544
+ // 先下到 .part 再改名:半截文件绝不能被下一次当成"有效缓存"。
1545
+ const partPath = cachePath + ".part";
1546
+ try {
1547
+ mkdirSync(cacheDir, { recursive: true });
1548
+ }
1549
+ catch (error) {
1550
+ const reason = describeError(error);
1551
+ setStep(downloadStep, "failed", "建不了缓存目录 " + cacheDir + ":" + reason);
1552
+ skipAfter(steps, "download", "缓存目录不可用,未执行");
1553
+ return finish(false, "没能下载安装包:" + reason, "换一个可写目录后重试。");
1554
+ }
1555
+ const fetched = await downloadInstaller(subprocess, installer.urls, partPath, cacheDir, request, timeoutMs);
1556
+ if (isAborted(request.signal))
1557
+ return abortRest(downloadStep);
1558
+ if (!fetched.ok) {
1559
+ const reason = fetched.attempts.length === 0
1560
+ ? "一个候选源都没试(已取消)"
1561
+ : fetched.attempts.join(";");
1562
+ setStep(downloadStep, "failed", "所有候选源都没下下来:" + reason);
1563
+ skipAfter(steps, "download", "安装包没下来,未执行");
1564
+ return finish(false, "下载安装包失败:试过 " +
1565
+ String(installer.urls.length) +
1566
+ " 个候选源(国内镜像优先,GitHub 兜底)都不通。", "逐源原因:\n " +
1567
+ fetched.attempts.join("\n ") +
1568
+ "\n可以自己下到 " +
1569
+ cachePath +
1570
+ " 再重试(有效缓存会直接复用,不重新下载);内网/代理可在 MSYS2_MIRROR 或 MSYS2_INSTALLER_URL 里指定一个能用的源。");
1571
+ }
1572
+ try {
1573
+ renameSync(partPath, cachePath);
1574
+ }
1575
+ catch (error) {
1576
+ removeFileQuietly(partPath);
1577
+ const reason = describeError(error);
1578
+ setStep(downloadStep, "failed", "下载完成但改名失败:" + reason);
1579
+ skipAfter(steps, "download", "安装包落位失败,未执行");
1580
+ return finish(false, "安装包下载完成但没法落位:" + reason, "检查缓存目录权限后重试。");
1581
+ }
1582
+ download = { url: fetched.url, bytes: fileSize(cachePath), cached: false };
1583
+ setStep(downloadStep, "done", "已从 " + installerSourceLabel(fetched.url) + " 下载:" + cachePath + "(" + formatBytes(download.bytes) + ")");
1584
+ }
1585
+ // c) 静默解压
1586
+ beginStep(steps, extractStep, request.onProgress);
1587
+ if (isAborted(request.signal))
1588
+ return abortRest(extractStep);
1589
+ if (alreadyInstalled) {
1590
+ setStep(extractStep, "skipped", "目标里已有 MSYS2,跳过解压");
1591
+ }
1592
+ else {
1593
+ const extracted = await extractInstaller(subprocess, cachePath, msys64, request, timeoutMs);
1594
+ if (extracted.cancelled) {
1595
+ // 取消 ≠ 失败:什么都没坏,安装包还在缓存里,暂存目录也留着(下次进来先清掉重来)。
1596
+ setStep(extractStep, "failed", EXTRACT_CANCELLED);
1597
+ skipAfter(steps, "extract", "已取消,未执行");
1598
+ return finish(false, "已取消:解压还没做完,安装包已缓存在 " +
1599
+ cachePath +
1600
+ (extracted.staging === "" ? "" : ",暂存目录 " + extracted.staging + " 保留着") +
1601
+ "。", "取消不等于失败——要接着装就再调一次(已下载的安装包直接用),暂存目录会在下次解压开始时自动清掉,不用你先收拾。");
1602
+ }
1603
+ if (!extracted.ok) {
1604
+ setStep(extractStep, "failed", extracted.detail);
1605
+ skipAfter(steps, "extract", "解压没成功,未执行");
1606
+ return finish(false, "解压失败:" + extracted.detail, "安装包已缓存在 " + cachePath + ",修好问题后重试不会重新下载;也可以手动把它解压到 " + msys64 + "。");
1607
+ }
1608
+ // F3d 第三道:解压自检。sfx 退出码 0 不代表解出来的是完整 MSYS2——
1609
+ // 半截安装包有时也能压出一半目录,缺 usr/bin/bash.exe 就等于白装。
1610
+ if (!existsSync(msys64 + "/usr/bin/bash.exe")) {
1611
+ setStep(extractStep, "failed", "解压完了但 " + msys64 + "/usr/bin/bash.exe 不存在,这份 MSYS2 不完整");
1612
+ // 缓存大概率是坏的:改名成 .broken 而不是删掉,留证据也留在用户手里;下次会重新下载。
1613
+ try {
1614
+ if (existsSync(cachePath))
1615
+ renameSync(cachePath, cachePath + ".broken");
1616
+ }
1617
+ catch {
1618
+ // 改名失败也不影响结论:下次同样会走到这里。
1619
+ }
1620
+ skipAfter(steps, "extract", "MSYS2 本体不完整,未执行");
1621
+ return finish(false, "解压出来的 MSYS2 不完整(缺 usr/bin/bash.exe):" + msys64, "坏掉的安装包已改名成 " + cachePath + ".broken(没有删,想留证据就留着);重跑一次会重新下载并重装," +
1622
+ "也可以手动把这个安装包解压到 " + msys64 + "。");
1623
+ }
1624
+ setStep(extractStep, "done", "已解压到 " + msys64);
1625
+ }
1626
+ // c2) 把国内镜像放到 pacman 列表最前(F3b)。只对刚解压出来的这份生效:
1627
+ // 已有的 MSYS2 是用户自己的环境,改人家的 pacman 配置不在本工具的授权范围内。
1628
+ if (!alreadyInstalled) {
1629
+ const mirrors = preferChinaMirrors(msys64);
1630
+ if (mirrors.note !== "") {
1631
+ notes.push(mirrors.note);
1632
+ request.onProgress?.(mirrors.note);
1633
+ }
1634
+ }
1635
+ // d) pacman 补包
1636
+ beginStep(steps, pacmanStep, request.onProgress);
1637
+ if (isAborted(request.signal))
1638
+ return abortRest(pacmanStep);
1639
+ const bashPath = msys64 + "/usr/bin/bash.exe";
1640
+ if (!existsSync(bashPath)) {
1641
+ setStep(pacmanStep, "failed", "找不到 " + bashPath + ",这份 MSYS2 不完整,没法补包");
1642
+ skipAfter(steps, "pacman", "MSYS2 不完整,未执行");
1643
+ return finish(false, "MSYS2 本体不完整(缺 usr/bin/bash.exe):" + msys64, "删掉这个目录后重装(安装包已在缓存里,重装不用重新下载),或换一个 targetDir。");
1644
+ }
1645
+ const runPacman = (line) => runCapture(subprocess, {
1646
+ argv: [bashPath, "-lc", line],
1647
+ cwd: msys64,
1648
+ timeoutMs,
1649
+ maxBytes: 512 * 1024,
1650
+ awaitQuiescence: true,
1651
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
1652
+ });
1653
+ // 先问一句"哪些已经装了"。pacman -S 对已装的包不是"跳过"而是"顺手升级",
1654
+ // 在第 4 步把用户整套 mingw 工具链升一个大版本不是本工具的活(那是 pacman -Syu 的事)。
1655
+ const query = await runPacman("pacman -Q " + packages.join(" "));
1656
+ const installed = parsePacmanQuery(query.stdout);
1657
+ const missing = packages.filter((name) => !installed.has(name));
1658
+ if (missing.length === 0) {
1659
+ setStep(pacmanStep, "skipped", packages.map((name) => name.replace("mingw-w64-ucrt-x86_64-", "") + " " + (installed.get(name) ?? "")).join("、") +
1660
+ " 都已经装了,没有重复安装,也没有升级(要升级自己跑 pacman -Syu)。");
1661
+ }
1662
+ else {
1663
+ // 全新解压出来的 MSYS2 里一个包都没有(库也是空的):先整体升级一次把库与基包拉到最新,
1664
+ // 再补缺的包。已有 MSYS2 只补缺的那几个 —— 在第 4 步把用户整套 mingw 工具链升一个大版本不是本工具的活。
1665
+ const needsSync = installed.size === 0;
1666
+ const installCommand = pacmanInstallCommand(missing);
1667
+ // B14:不再 "-Sy 之后立刻 -S <pkg>"。官方把那种局部升级列为会解不开依赖的操作,
1668
+ // 用户只会在同一条命令上反复失败;新解压的基包里 -Syu 本来就是该做的第一件事。
1669
+ let command = needsSync ? PACMAN_UPGRADE_COMMAND : installCommand;
1670
+ if (needsSync) {
1671
+ request.onProgress?.("刚解压出来的 MSYS2 里还没有包数据库:先整体升级一次(pacman -Syu --noconfirm),再补包");
1672
+ }
1673
+ let pacman = await runPacman(command);
1674
+ if (isAborted(request.signal))
1675
+ return abortRest(pacmanStep);
1676
+ if (needsKeyringInit(pacman)) {
1677
+ request.onProgress?.("pacman 的 keyring 没初始化:先 pacman-key --init / --populate msys2,再重试一次");
1678
+ const init = await runPacman("pacman-key --init && pacman-key --populate msys2");
1679
+ if (isAborted(request.signal))
1680
+ return abortRest(pacmanStep);
1681
+ if (init.exitCode === 0) {
1682
+ pacman = await runPacman(command);
1683
+ if (isAborted(request.signal))
1684
+ return abortRest(pacmanStep);
1685
+ }
1686
+ else {
1687
+ setStep(pacmanStep, "failed", "pacman-key 初始化失败(退出码 " +
1688
+ String(init.exitCode) +
1689
+ "):" +
1690
+ (lastLine(init.stderr) || lastLine(init.stdout) || "(无输出)") +
1691
+ "\n手动:" +
1692
+ bashLine(msys64, "pacman-key --init && pacman-key --populate msys2"));
1693
+ skipAfter(steps, "pacman", "补包失败,未执行");
1694
+ return finish(false, "pacman 的 keyring 初始化失败,包没装上。", "在 " +
1695
+ msys64 +
1696
+ " 里手动跑一遍 " +
1697
+ bashLine(msys64, "pacman-key --init && pacman-key --populate msys2") +
1698
+ " 后重试。");
1699
+ }
1700
+ }
1701
+ // -Syu 成功只代表库和基包是新的,我们缺的 5 个组件还得单独补。
1702
+ if (needsSync && command === PACMAN_UPGRADE_COMMAND && pacmanOk(pacman)) {
1703
+ command = installCommand;
1704
+ pacman = await runPacman(command);
1705
+ if (isAborted(request.signal))
1706
+ return abortRest(pacmanStep);
1707
+ }
1708
+ if (!pacmanOk(pacman)) {
1709
+ const reason = pacman.spawnError !== null
1710
+ ? "bash 起不来:" + pacman.spawnError
1711
+ : pacman.timedOut
1712
+ ? "pacman 超时(" + String(Math.round(timeoutMs / 1000)) + " s)"
1713
+ : "退出码 " +
1714
+ String(pacman.exitCode) +
1715
+ ":" +
1716
+ (lastLine(pacman.stderr) || lastLine(pacman.stdout) || "(无输出)");
1717
+ // A30:上次被强杀/断电留下的锁文件会让 pacman 一律拒绝开工;给具体命令,但不替用户删。
1718
+ const lockPath = msys64 + "/var/lib/pacman/db.lck";
1719
+ if (existsSync(lockPath)) {
1720
+ notes.push("pacman 的锁还在:" +
1721
+ lockPath +
1722
+ "(一般是被中断或强杀留下的)。先确认没有 pacman / bash 进程在跑,删掉它再重试:" +
1723
+ bashLine(msys64, "rm -f /var/lib/pacman/db.lck") +
1724
+ ";锁在的时候 pacman 会一律拒绝开工。");
1725
+ }
1726
+ // A30:文件冲突不是靠重试能过去的,指条明路就行(不自动 --overwrite,那会覆盖别人的文件)。
1727
+ if (/conflicting files|exists in filesystem|conflicts with/u.test((pacman.stdout + " " + pacman.stderr).toLowerCase())) {
1728
+ notes.push("pacman 报的是文件冲突(conflicting files / exists in filesystem):先整体升级一次(" +
1729
+ bashLine(msys64, PACMAN_UPGRADE_COMMAND) +
1730
+ ");确认某几个文件被别的包占着、确实要顶掉时再自己加 --overwrite。本工具不会替你覆盖别人的文件。");
1731
+ }
1732
+ // 不当场放弃:MSYS2 本体在,PATH / 配置照写,报告里把失败点写清楚。
1733
+ setStep(pacmanStep, "failed", reason +
1734
+ "\n手动:" +
1735
+ bashLine(msys64, command) +
1736
+ (reason.includes("无法满足依赖关系") || needsSync
1737
+ ? "\n这条一般是 MSYS2 的库与已装包不同步(局部升级解不开依赖):先在 " +
1738
+ msys64 +
1739
+ " 里跑 pacman -Syu(整体升级),再重调本工具 —— 别只同步库就补单个包。"
1740
+ : ""));
1741
+ }
1742
+ else {
1743
+ setStep(pacmanStep, "done", "pacman 退出码 0;补装的包:" + missing.join("、"));
1744
+ }
1745
+ }
1746
+ // e) 用户级 PATH
1747
+ beginStep(steps, pathStep, request.onProgress);
1748
+ if (isAborted(request.signal))
1749
+ return abortRest(pathStep);
1750
+ if (!request.writePath) {
1751
+ setStep(pathStep, "skipped", "writePath=false:没动 PATH;要给命令行用就自己把 " + toWindowsDir(binDir) + " 加进 PATH");
1752
+ }
1753
+ else {
1754
+ pathState = await applyUserPath(subprocess, env, binDir, request);
1755
+ if (pathState.done && !pathState.changed) {
1756
+ setStep(pathStep, "done", "用户 PATH 里已经有 " + toWindowsDir(binDir) + ",没有重复写");
1757
+ }
1758
+ else if (pathState.done) {
1759
+ setStep(pathStep, "done", "已把 " +
1760
+ toWindowsDir(binDir) +
1761
+ " 追加到用户级 PATH(REG_EXPAND_SZ);旧值备份在 " +
1762
+ pathState.backup);
1763
+ }
1764
+ else {
1765
+ // 失败不致命:插件按配置里的绝对路径找工具,PATH 只是给命令行/其他工具用的。
1766
+ // 读失败的情形 error 里已经带了手动命令,别把两套"手动:"叠在一起让人误读。
1767
+ const manual = pathState.error.includes("手动:")
1768
+ ? ""
1769
+ : "\n手动:把 " +
1770
+ toWindowsDir(binDir) +
1771
+ " 追加到「环境变量 → 用户变量 → Path」(不要用 setx,它会在 1024 字符处截断 PATH)";
1772
+ setStep(pathStep, "failed", pathState.error + manual);
1773
+ }
1774
+ }
1775
+ // f) 自检
1776
+ beginStep(steps, verifyStep, request.onProgress);
1777
+ if (isAborted(request.signal))
1778
+ return abortRest(verifyStep);
1779
+ const probeConfig = { binDirs: [binDir], cubeMxRoots: [] };
1780
+ const targets = buildTargets(probeConfig).filter((item) => VERIFY_IDS.includes(item.id));
1781
+ const probed = await probeAll(subprocess, targets, probeConfig, {
1782
+ timeoutMs: PROBE_TIMEOUT_MS,
1783
+ // 自检只认这个目录。允许 PATH 兜底的话,机器上另一份同名工具(STM32CubeIDE 自带、
1784
+ // xpack、旧的 msys64)会让"没装进目标目录"看起来像"装好了"。
1785
+ allowPathFallback: false,
1786
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
1787
+ });
1788
+ verifyState = toVerifyState(probed);
1789
+ // 绝对候选理论上仍可能指到目录之外,兜一层:只有命中的工具都真的躺在 binDir 里,
1790
+ // "这个目录装好了"才成立。
1791
+ const strayTools = probed.filter((result) => result.found && !isInsideDir(result.path, binDir));
1792
+ setStep(verifyStep, verifyState.ok ? "done" : "failed", verifyState.ok
1793
+ ? verifySummary(verifyState) +
1794
+ (strayTools.length === 0
1795
+ ? ""
1796
+ : "(其中 " + strayTools.map((tool) => tool.path).join("、") + " 不在 " + binDir + " 里)")
1797
+ : "缺 " +
1798
+ verifyState.tools
1799
+ .filter((tool) => !tool.found)
1800
+ .map((tool) => tool.label)
1801
+ .join("、") +
1802
+ "(只在 " + binDir + " 里找:PATH 上另一份同名工具不算装到这个目录)");
1803
+ // g) 写配置(与已有 packages 合并去重,别的字段原样保留)
1804
+ beginStep(steps, configStep, request.onProgress);
1805
+ const beforeConfig = readToolchainConfig(env);
1806
+ const merged = dedupeStrings([...(beforeConfig.config?.packages ?? []), ...packages]);
1807
+ // A28:带上刚才读到的快照做 CAS。读和写之间要是别的进程(另开的 DSH 窗口、用户手改)动了配置,
1808
+ // 就重读、重新合并再写一次,而不是把对方那份直接覆盖掉。
1809
+ const written = updateToolchainConfig({ msys64, binDirs: [binDir], packages: merged }, env, {
1810
+ expect: { mtimeMs: beforeConfig.mtimeMs, updatedAt: beforeConfig.config?.updatedAt ?? "" },
1811
+ });
1812
+ configState = { path: written.path, written: written.ok, error: written.error };
1813
+ const conflictNote = written.attempts > 1 ? "(配置文件刚被别人改过,已重读后重试一次)" : "";
1814
+ setStep(configStep, written.ok ? "done" : "failed", written.ok
1815
+ ? "已写入 " + written.path + "(msys64 / binDirs / packages " + String(merged.length) + " 个)" + conflictNote
1816
+ : written.error);
1817
+ // 只有 PATH 允许失败不致命:其余任何一步失败都算没装成。
1818
+ // 一个例外:pacman 补装失败,但 5 个组件都**从 binDir 里**跑起来了(自检通过且没有外来工具),
1819
+ // 说明这个目录本来就不缺东西——那不是"没装成",如实记一行、继续当成功。
1820
+ // 反过来,只要有一个工具来自 binDir 之外,就不能改判:配置里最终指的是这个目录,
1821
+ // 而它其实没装好,用户下次编译才会撞上。
1822
+ if (verifyState.ok && strayTools.length === 0 && pacmanStep.status === "failed") {
1823
+ pacmanStep.status = "done";
1824
+ pacmanStep.detail =
1825
+ pacmanStep.detail +
1826
+ "\n但自检显示 5 个组件都是在 " +
1827
+ binDir +
1828
+ " 里跑起来的,按「已装」处理(插件不替你升级,要升级自己跑 pacman -Syu)。";
1829
+ }
1830
+ const fatal = steps.find((step) => step.status === "failed" && step.id !== "path");
1831
+ const ok = fatal === undefined;
1832
+ const pathFailed = pathStep.status === "failed";
1833
+ const message = ok
1834
+ ? "MSYS2 装到 " +
1835
+ msys64 +
1836
+ " 了," +
1837
+ verifySummary(verifyState) +
1838
+ ";现在可以编译 / 烧录 / 调试。" +
1839
+ // 读不到 PATH 与"写了但失败"是两种事:前者一句"没写成功"会让用户以为是我们写坏了,
1840
+ // 所以这里把"为安全起见没动注册表"直接写进 message。
1841
+ (pathFailed
1842
+ ? pathState.error.startsWith(UNREADABLE_PATH_PREFIX)
1843
+ ? "(用户级 PATH 没动:读不到当前值,为安全起见不会写注册表;不影响插件按绝对路径找工具)"
1844
+ : "(用户 PATH 没写成功,不影响插件按绝对路径找工具)"
1845
+ : "")
1846
+ : "安装没全部成功:" +
1847
+ steps
1848
+ .filter((step) => step.status === "failed")
1849
+ .map((step) => step.label)
1850
+ .join("、") +
1851
+ "(每一步的原因都在 steps 里)。" +
1852
+ // 自检禁用了 PATH 兜底,这里必须说清"能跑"不等于"装到了目标目录",
1853
+ // 否则用户看着别处的 gcc 好好的,会以为是我们判错了。
1854
+ (strayTools.length > 0
1855
+ ? " 能跑的那几个不在 " +
1856
+ binDir +
1857
+ " 里(" +
1858
+ strayTools.map((tool) => tool.path).join("、") +
1859
+ "),说明它们本来就在别的目录,这个目录并没有装好。"
1860
+ : pacmanStep.status === "failed" && !verifyState.ok
1861
+ ? " 自检只在 " + binDir + " 里找:PATH 上另一份同名工具不算装到这个目录。"
1862
+ : "") +
1863
+ // B14:pacman 那步失败时把「先 -Syu 整体升级」提到 message,别让用户重调同一条命令循环失败。
1864
+ (pacmanStep.status === "failed"
1865
+ ? " pacman 那一步的修法:先在 " + msys64 + " 里跑 " + bashLine(msys64, PACMAN_UPGRADE_COMMAND) + "(整体升级),再重调本工具;只同步软件库再补单个包属于局部升级,依赖会解不开。"
1866
+ : "");
1867
+ return finish(ok, message, ok
1868
+ ? "直接重跑你刚才的工具(stm32_build / stm32_flash / stm32_debug_run);也可以用 stm32_env_probe 复看一遍。"
1869
+ : "看 steps 里失败那一步的 detail;修好后重调本工具,已完成的步骤会自动跳过(不会重复下载、不会重复写 PATH)。");
1870
+ }