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,668 @@
1
+ /**
2
+ * 固件包下载/组装引擎:把 GitHub 上的 HAL 驱动 + CMSIS 设备支持 + 内核头拼成
3
+ * CubeMX 认的 STM32Cube_FW_<族>_V<版本> 目录(实测见 docs §14)。
4
+ *
5
+ * 装到哪(按优先级,default_target = auto):
6
+ * ① 本机 CubeMX 仓库里已经有这个包 → 什么都不做(existing)
7
+ * ② <cubeMxRoot>/dsh-firmware/<包名>(插件自建,与 Repository 并列)→ 默认落点(cubeMx)
8
+ * ③ 显式 target=repository 且仓库可写 → 装进官方仓库(repository)
9
+ * ④ 上面都不行 → 落到用户缓存 <cacheRoot>/firmware/<包名>(cache)
10
+ *
11
+ * 为什么默认不装进 Repository(2026-10 实测,docs §14):把自造版本号丢进官方仓库,
12
+ * CubeMX **不报错也不认**,生成时静默退回它自己认识的版本(拷出来的 HAL 字节数不对)。
13
+ * 真正让 CubeMX 用上指定包的唯一机制是脚本命令 project setCustomFWPath <包目录>,
14
+ * 由 generate.ts 在 config load 之后发出去 —— 所以落点与 .ioc 无关,换机器也没有绝对路径残留。
15
+ *
16
+ * 刻意不做的事:不覆盖已有官方包(升级走 CubeMX 包管理器)、不动 Repository 里的其它包。
17
+ */
18
+ import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
19
+ import path from "node:path";
20
+ import { dshFirmwareDir, firmwarePlanFor, verifyFirmwarePackage, } from "../data/firmware-packages.js";
21
+ import { cacheRoot } from "./cache.js";
22
+ import { fetchAll } from "./fetch.js";
23
+ import { extractTarGz } from "./tar.js";
24
+ function slash(value) {
25
+ let out = value.split("\\").join("/");
26
+ while (out.endsWith("/"))
27
+ out = out.slice(0, -1);
28
+ return out;
29
+ }
30
+ function kindLabel(kind) {
31
+ switch (kind) {
32
+ case "existing":
33
+ return "CubeMX 仓库里已有的官方包";
34
+ case "cubeMx":
35
+ return "CubeMX 目录里的 dsh-firmware";
36
+ case "repository":
37
+ return "CubeMX 仓库";
38
+ case "cache":
39
+ return "下载缓存";
40
+ case "custom":
41
+ return "调用方指定的目录";
42
+ default:
43
+ return "未定";
44
+ }
45
+ }
46
+ function stepOf(steps, id) {
47
+ const found = steps.find((step) => step.id === id);
48
+ if (found !== undefined)
49
+ return found;
50
+ const fresh = { id, label: id, status: "pending", detail: "" };
51
+ steps.push(fresh);
52
+ return fresh;
53
+ }
54
+ /** 在候选 CubeMX 根里找已经装好的包(找 <root>/Repository/<包名>)。 */
55
+ export function findInstalledFirmware(cubeMxRoots, packageName) {
56
+ for (const root of cubeMxRoots) {
57
+ if (root.trim() === "")
58
+ continue;
59
+ const candidate = slash(root) + "/Repository/" + packageName;
60
+ if (existsSync(candidate + "/package.xml") || existsSync(candidate + "/Drivers"))
61
+ return candidate;
62
+ }
63
+ return "";
64
+ }
65
+ /* ------------------------- 安装记录(B10 的桥) ------------------------- */
66
+ /** 安装记录文件名:<cacheRoot>/firmware/installed.json 里一串落点,generate 靠它找回落在 CubeMX 根以外的包。 */
67
+ export const FIRMWARE_RECORD_FILE = "installed.json";
68
+ /** 记录文件路径(正斜杠)。 */
69
+ export function firmwareRecordPath(env = process.env) {
70
+ return slash(cacheRoot(env)) + "/firmware/" + FIRMWARE_RECORD_FILE;
71
+ }
72
+ /**
73
+ * 读安装记录。文件不存在 / 坏 JSON / 字段不认识都当"没有记录":
74
+ * 这是给 generate 的提示,不是判据 —— 读不到最多是找不到包,不该让调用方炸。
75
+ */
76
+ export function readFirmwareInstallRecords(env = process.env) {
77
+ let text;
78
+ try {
79
+ text = readFileSync(firmwareRecordPath(env), "utf8");
80
+ }
81
+ catch {
82
+ return [];
83
+ }
84
+ let parsed;
85
+ try {
86
+ parsed = JSON.parse(text);
87
+ }
88
+ catch {
89
+ return [];
90
+ }
91
+ if (!Array.isArray(parsed))
92
+ return [];
93
+ const out = [];
94
+ for (const item of parsed) {
95
+ if (typeof item !== "object" || item === null)
96
+ continue;
97
+ const record = item;
98
+ const kind = record.kind;
99
+ if (typeof record.packageName !== "string" || record.packageName === "")
100
+ continue;
101
+ if (typeof record.dir !== "string" || record.dir.trim() === "")
102
+ continue;
103
+ if (kind !== "cubeMx" && kind !== "repository" && kind !== "cache" && kind !== "custom")
104
+ continue;
105
+ out.push({
106
+ packageName: record.packageName,
107
+ dir: slash(record.dir),
108
+ kind,
109
+ at: typeof record.at === "string" ? record.at : "",
110
+ });
111
+ }
112
+ return out;
113
+ }
114
+ /**
115
+ * 固件包除了 CubeMX 根以外还可能在哪:
116
+ * · <cacheRoot>/firmware —— stm32_firmware_install 没找到可写 CubeMX 根时的落点(目录里就是包);
117
+ * · installed.json 里记的每条落点 —— 显式 targetDir 之类的任意位置。
118
+ * 都只是"多找一处",找不到不影响调用方。
119
+ *
120
+ * 为什么放在引擎这一层而不是各自实现:generate 与 scaffold 都要搜同一批位置,
121
+ * 两处各写一份迟早对不上(一边认、另一边看不见,用户就会"装好了但生成/建工程找不到")。
122
+ */
123
+ export function firmwareExtraDirs(env = process.env) {
124
+ const out = [{ dir: slash(cacheRoot(env)) + "/firmware", source: "cache" }];
125
+ for (const record of readFirmwareInstallRecords(env)) {
126
+ if (record.kind === "cubeMx" || record.kind === "repository")
127
+ continue;
128
+ if (out.some((extra) => extra.dir === record.dir))
129
+ continue;
130
+ out.push({ dir: record.dir, source: record.kind === "cache" ? "cache" : "custom" });
131
+ }
132
+ return out;
133
+ }
134
+ /**
135
+ * 记一条落点(同一个包名后写的覆盖先写的)。返回空串表示记下了,否则是给人看的一句原因。
136
+ * 为什么不让它失败:记录只是给 generate 的线索,写不进去不该把"包已经装好并自检通过"反转成失败。
137
+ */
138
+ function rememberFirmwareInstall(env, packageName, dir, kind) {
139
+ const recordPath = firmwareRecordPath(env);
140
+ const kept = readFirmwareInstallRecords(env).filter((record) => record.packageName !== packageName);
141
+ kept.push({ packageName, dir: slash(dir), kind, at: new Date().toISOString() });
142
+ const tmpPath = recordPath + ".tmp-" + String(process.pid);
143
+ try {
144
+ mkdirSync(path.dirname(recordPath), { recursive: true });
145
+ writeFileSync(tmpPath, JSON.stringify(kept, null, 1), "utf8");
146
+ try {
147
+ renameSync(tmpPath, recordPath);
148
+ }
149
+ catch {
150
+ // Windows 上目标被占用时 rename 会失败:先删再改名,仍不行就把临时文件留着、报一句原因。
151
+ rmSync(recordPath, { force: true });
152
+ renameSync(tmpPath, recordPath);
153
+ }
154
+ return "";
155
+ }
156
+ catch (error) {
157
+ rmSync(tmpPath, { force: true });
158
+ return error instanceof Error ? error.message : String(error);
159
+ }
160
+ }
161
+ /**
162
+ * 是不是受保护的系统目录(Windows 上普通用户建不了子目录的那几个)。
163
+ *
164
+ * 实测动机(2026-10-25 宿主冒烟):本机 CubeMX 在 D:/app/STM32CubeMX,但自动发现把
165
+ * C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX 排在前面;那个目录在本机
166
+ * 根本不存在,plan 模式下 Node 的 accessSync(W_OK) 只看只读属性、不看 ACL,于是
167
+ * 「最近一个已存在的祖先」C:/Program Files 被判成可写,计划就落到了一个装不进去的地方。
168
+ */
169
+ export function isProtectedSystemDir(dir, env = process.env) {
170
+ const target = slash(dir).toLowerCase();
171
+ if (target === "")
172
+ return false;
173
+ const roots = [];
174
+ const push = (value) => {
175
+ if (value === undefined || value.trim() === "")
176
+ return;
177
+ const normalized = slash(value).toLowerCase();
178
+ if (normalized !== "" && roots.includes(normalized) === false)
179
+ roots.push(normalized);
180
+ };
181
+ push(env["ProgramFiles"]);
182
+ push(env["ProgramFiles(x86)"]);
183
+ push(env["ProgramW6432"]);
184
+ push(env["ProgramData"]);
185
+ push(env["SystemRoot"]);
186
+ // 刻意不把整块系统盘(C:/)算进来:用户目录 %TEMP%、%LOCALAPPDATA% 都在 C: 上,那样会误伤一切。
187
+ for (const root of roots) {
188
+ if (target === root || target.startsWith(root.endsWith("/") ? root : root + "/"))
189
+ return true;
190
+ }
191
+ return false;
192
+ }
193
+ /** 候选根排序:本机真存在的排前面(存在的才可能是真装过 CubeMX 的那份)。 */
194
+ export function orderCubeMxRoots(roots) {
195
+ const kept = roots.map((root) => root.trim()).filter((root) => root !== "");
196
+ const existing = kept.filter((root) => existsSync(root));
197
+ const missing = kept.filter((root) => existsSync(root) === false);
198
+ return [...existing, ...missing];
199
+ }
200
+ /**
201
+ * 这个根里有没有 STM32CubeMX.exe(判定"像不像装过 CubeMX"的宽松版)。
202
+ * 为什么必须判:自动发现会把别的机器上的默认安装路径也列进来;对那种"假根"建 dsh-firmware,
203
+ * 盘上就多出一份谁也认不到的包,而计划与真装还会给出两个不同落点(B12)。
204
+ * 与 data/search-roots.ts 的 looksLikeCubeMxRoot 的区别:那个还要求 jre/bin/java.exe(无头生成要它),
205
+ * 这里只决定"往哪放固件包",缺 JRE 但装了 CubeMX 的机器也该能落到 dsh-firmware。
206
+ */
207
+ export function hasCubeMxExe(root) {
208
+ const base = slash(root.trim());
209
+ if (base === "")
210
+ return false;
211
+ return existsSync(base + "/STM32CubeMX.exe");
212
+ }
213
+ /** 目录能不能写。plan 模式只做只读探测(不建目录),install 模式才真的 mkdir + 试写。 */
214
+ function dirWritable(dir, create) {
215
+ if (!create) {
216
+ // 计划模式:目录可能还不存在(CubeMX 刚装、Repository 还没建),按最近的已存在祖先判可写性。
217
+ let probe = dir;
218
+ while (!existsSync(probe)) {
219
+ const parent = path.dirname(probe);
220
+ if (parent === probe || parent.length <= 3)
221
+ break;
222
+ probe = parent;
223
+ }
224
+ if (probe !== dir && isProtectedSystemDir(probe)) {
225
+ // Windows 的 accessSync(W_OK) 只看只读属性,不看 ACL,Program Files 一样报"可写"。
226
+ // 这里不猜:没装到那台机器上的根,祖先又是系统目录,就按不可写算,让落点退回能写的那一支。
227
+ return { ok: false, dir, error: "位于受保护的系统目录 " + slash(probe) + " 下,普通权限建不了子目录" };
228
+ }
229
+ try {
230
+ accessSync(probe, constants.W_OK);
231
+ return { ok: true, dir, error: "" };
232
+ }
233
+ catch (error) {
234
+ const message = error instanceof Error ? error.message : String(error);
235
+ return { ok: false, dir, error: message };
236
+ }
237
+ }
238
+ // install 模式(create=true)以前直接 mkdir + 试写,把受保护目录判定整个绕过去了:候选根不存在、
239
+ // 祖先又是 Program Files 时,普通用户会把假根真建出来,targetKind 还报 cubeMx(B12)。
240
+ // 这里按"最近一个已存在的祖先"先判一遍,判不了就不建。
241
+ let existing = dir;
242
+ while (!existsSync(existing)) {
243
+ const parent = path.dirname(existing);
244
+ if (parent === existing || parent.length <= 3)
245
+ break;
246
+ existing = parent;
247
+ }
248
+ if (existing !== dir && isProtectedSystemDir(existing)) {
249
+ return { ok: false, dir, error: "位于受保护的系统目录 " + slash(existing) + " 下,普通权限建不了子目录" };
250
+ }
251
+ try {
252
+ mkdirSync(dir, { recursive: true });
253
+ const probe = path.join(dir, ".dsh-write-probe-" + String(process.pid));
254
+ writeFileSync(probe, "ok");
255
+ rmSync(probe, { force: true });
256
+ return { ok: true, dir, error: "" };
257
+ }
258
+ catch (error) {
259
+ const message = error instanceof Error ? error.message : String(error);
260
+ return { ok: false, dir, error: message };
261
+ }
262
+ }
263
+ /** 官方仓库能不能写(<root>/Repository)。 */
264
+ function repositoryWritable(root, create) {
265
+ return dirWritable(slash(root) + "/Repository", create);
266
+ }
267
+ function decideTarget(request, plan, create) {
268
+ const notes = [];
269
+ const explicit = request.targetDir;
270
+ if (explicit !== undefined && explicit.trim() !== "") {
271
+ return { kind: "custom", dir: slash(explicit), notes };
272
+ }
273
+ const existing = findInstalledFirmware(request.cubeMxRoots, plan.dirName);
274
+ if (existing !== "") {
275
+ return { kind: "existing", dir: existing, notes: ["CubeMX 仓库里已经有 " + plan.dirName + ",直接用它,不下载。"] };
276
+ }
277
+ const want = request.target ?? "auto";
278
+ // 本机真存在的根优先:自动发现会把别的机器上的默认安装路径也列进来,
279
+ // 那种根在 plan 模式下判不出可写性,排在前面就会把落点带偏。
280
+ const roots = orderCubeMxRoots(request.cubeMxRoots);
281
+ if (want === "repository") {
282
+ for (const root of roots) {
283
+ if (!hasCubeMxExe(root)) {
284
+ notes.push("跳过 " + slash(root) + ":这里没有 STM32CubeMX.exe,不像装过 CubeMX,不往里建 Repository。");
285
+ continue;
286
+ }
287
+ const writable = repositoryWritable(root, create);
288
+ if (writable.ok) {
289
+ return {
290
+ kind: "repository",
291
+ dir: writable.dir + "/" + plan.dirName,
292
+ notes: [
293
+ "落进 CubeMX 官方仓库:" + writable.dir + "/" + plan.dirName + "。实测这种自造版本号 CubeMX 不会自动认," +
294
+ "生成代码照样靠脚本命令 setCustomFWPath 指过去。",
295
+ ],
296
+ };
297
+ }
298
+ notes.push("CubeMX 仓库 " + writable.dir + " 写不进去(" + writable.error + ")。");
299
+ }
300
+ notes.push("要求装进 CubeMX 仓库,但没有一个可写的仓库根,只好落到别处。");
301
+ }
302
+ if (want !== "cache") {
303
+ // 默认落点:CubeMX 安装根下自建 dsh-firmware(与 Repository 并列,绝不往官方目录里塞)。
304
+ for (const root of roots) {
305
+ if (!hasCubeMxExe(root)) {
306
+ notes.push("跳过 " + slash(root) + ":这里没有 STM32CubeMX.exe,不像装过 CubeMX,不往里建 dsh-firmware。");
307
+ continue;
308
+ }
309
+ const own = dirWritable(dshFirmwareDir(root), create);
310
+ if (own.ok) {
311
+ return {
312
+ kind: "cubeMx",
313
+ dir: own.dir + "/" + plan.dirName,
314
+ notes: [
315
+ "落点:" + own.dir + "/" + plan.dirName + "(CubeMX 目录里的 dsh-firmware,与 Repository 并列,不动官方包)。",
316
+ ],
317
+ };
318
+ }
319
+ notes.push("建不了 " + own.dir + "(" + own.error + ")。");
320
+ }
321
+ }
322
+ const dir = slash(cacheRoot(request.env ?? process.env)) + "/firmware/" + plan.dirName;
323
+ notes.push("落点:" + dir + ":没有可用的 CubeMX 目录(没装、或装的位置写不进去、或候选根里没有 STM32CubeMX.exe)," +
324
+ "只能放用户目录下的缓存;生成时 stm32_generate 会按缓存与安装记录找到它,靠脚本命令 setCustomFWPath 指过去,不会写进 .ioc。");
325
+ return { kind: "cache", dir, notes };
326
+ }
327
+ function baseSteps(plan) {
328
+ return [
329
+ { id: "prepare", label: "准备目标目录", status: "pending", detail: "" },
330
+ {
331
+ id: "download",
332
+ label: "下载 HAL 驱动与设备支持",
333
+ status: "pending",
334
+ detail: plan.archives.map((archive) => archive.label).join(" + ") +
335
+ " 两个归档,外加 " +
336
+ String(plan.coreTargets.length) +
337
+ " 个 CMSIS 内核头(合计约 2 MB;每个文件 3 条候选源,前一条不通自动换)",
338
+ },
339
+ {
340
+ id: "extract",
341
+ label: "解包并摆成固件包布局",
342
+ status: "pending",
343
+ detail: "只保留 " + plan.halDir + "/{Inc,Src} 与 " + plan.deviceDir + "/{Include,Source},其它(.github、文档、示例)不落盘",
344
+ },
345
+ {
346
+ id: "package",
347
+ label: "写 package.xml 与第三方声明",
348
+ status: "pending",
349
+ detail: "Release " + plan.releaseTag + " / Patch " + plan.patchTag + "(CubeMX 靠这个文件认版本)",
350
+ },
351
+ {
352
+ id: "verify",
353
+ label: "按三条判据自检",
354
+ status: "pending",
355
+ detail: "HAL 驱动 Inc/Src + 设备头 Include + gcc 启动文件都在才算装成(CubeMX 缺包时不报错,必须自查)",
356
+ },
357
+ ];
358
+ }
359
+ function emptyResult(mode, message) {
360
+ return {
361
+ ok: false,
362
+ mode,
363
+ family: "",
364
+ version: "",
365
+ packageName: "",
366
+ targetKind: "",
367
+ targetDir: "",
368
+ cacheRoot: "",
369
+ cubeMxRoots: [],
370
+ steps: [],
371
+ verify: { ok: false, checks: [] },
372
+ download: { files: 0, bytes: 0 },
373
+ notes: [],
374
+ message,
375
+ nextStep: "",
376
+ };
377
+ }
378
+ function planResult(request, plan, decision) {
379
+ const steps = baseSteps(plan);
380
+ const prepare = stepOf(steps, "prepare");
381
+ prepare.detail = "装到 " + decision.dir + "(" + kindLabel(decision.kind) + ")";
382
+ const notes = [...decision.notes];
383
+ const roots = request.cubeMxRoots.map((root) => slash(root));
384
+ if (decision.kind === "existing") {
385
+ for (const step of steps) {
386
+ step.status = "skipped";
387
+ step.detail = "本机已有官方包,不需要这一步";
388
+ }
389
+ const verify = verifyFirmwarePackage(decision.dir, plan.family);
390
+ return {
391
+ ok: verify.ok,
392
+ mode: "plan",
393
+ family: plan.family,
394
+ version: plan.version,
395
+ packageName: plan.dirName,
396
+ targetKind: decision.kind,
397
+ targetDir: decision.dir,
398
+ cacheRoot: slash(cacheRoot(request.env ?? process.env)),
399
+ cubeMxRoots: roots,
400
+ steps,
401
+ verify,
402
+ download: { files: 0, bytes: 0 },
403
+ notes,
404
+ message: verify.ok
405
+ ? "本机已经有了 " + plan.dirName + "(" + decision.dir + "),自检也过了,不用下载,直接生成代码就行。"
406
+ : "本机有个 " + plan.dirName + ",但自检不过(缺 " + verify.missing.join("、") + "),建议用 CubeMX 包管理器重装。",
407
+ nextStep: "直接调 stm32_generate(.ioc 里 ProjectManager.FirmwarePackage 写 STM32Cube FW_" + plan.family + " V" + plan.version + ")。",
408
+ };
409
+ }
410
+ return {
411
+ ok: true,
412
+ mode: "plan",
413
+ family: plan.family,
414
+ version: plan.version,
415
+ packageName: plan.dirName,
416
+ targetKind: decision.kind,
417
+ targetDir: decision.dir,
418
+ cacheRoot: slash(cacheRoot(request.env ?? process.env)),
419
+ cubeMxRoots: roots,
420
+ steps,
421
+ verify: { ok: false, checks: [] },
422
+ download: { files: 0, bytes: 0 },
423
+ notes,
424
+ message: "计划(还没动手):把 " +
425
+ plan.dirName +
426
+ " 下载并组装到 " +
427
+ decision.dir +
428
+ "(" +
429
+ kindLabel(decision.kind) +
430
+ "):2 个归档 + " +
431
+ String(plan.coreTargets.length) +
432
+ " 个内核头,约 2 MB;现在没有下载、没有建目录、没动 CubeMX 安装目录。",
433
+ nextStep: "要我装吗?回一句「装固件包」,我给 dryRun:false + confirm:true 真下(约 2 MB)。",
434
+ };
435
+ }
436
+ /** 计划模式:只读探测,零副作用。 */
437
+ export function firmwareInstallPlan(request) {
438
+ const plan = firmwarePlanFor(request);
439
+ if (!plan.ok)
440
+ return emptyResult("plan", plan.error);
441
+ return planResult(request, plan, decideTarget(request, plan, false));
442
+ }
443
+ /** 按归档的 dirs 表把压缩包里的路径映射到包布局。 */
444
+ function mapperFor(archive) {
445
+ return (rel) => {
446
+ for (const dir of archive.dirs) {
447
+ if (rel === dir.from || rel.startsWith(dir.from + "/")) {
448
+ return dir.to + rel.slice(dir.from.length);
449
+ }
450
+ }
451
+ return null;
452
+ };
453
+ }
454
+ const NOTICES_FILE = "THIRD_PARTY_NOTICES.md";
455
+ /** 清掉以前崩溃/被杀留下的 .dsh-download-* 暂存目录(只清超过 1 小时的,不碰并发的那一份)。 */
456
+ function sweepStaleTemps(dir) {
457
+ try {
458
+ const now = Date.now();
459
+ for (const name of readdirSync(dir)) {
460
+ if (!/^\.dsh-download-\d+-\d+$/u.test(name))
461
+ continue;
462
+ const full = path.join(dir, name);
463
+ try {
464
+ if (now - statSync(full).mtimeMs < 60 * 60 * 1000)
465
+ continue;
466
+ rmSync(full, { recursive: true, force: true });
467
+ }
468
+ catch {
469
+ // 被占用/没权限就留着:下次再来。
470
+ }
471
+ }
472
+ }
473
+ catch {
474
+ // 目录读不了不影响安装。
475
+ }
476
+ }
477
+ /**
478
+ * 装好之后该干什么:按落点分档(A13)。
479
+ * 以前无论装到哪都念同一段"直接调 stm32_generate",落到缓存或显式目录时用户照着做
480
+ * 也不一定知道 CubeMX GUI 里看不见这个包。
481
+ */
482
+ function nextStepFor(kind, dir, packageName) {
483
+ const locate = "它会按 .ioc 的 ProjectManager.FirmwarePackage 找这个包(CubeMX 根、" + packageName +
484
+ " 的安装记录、下载缓存都搜),用脚本命令 setCustomFWPath 指过去(" + dir + "),不往 .ioc 里写绝对路径。";
485
+ if (kind === "cubeMx") {
486
+ return "直接调 stm32_generate:" + locate + "CubeMX GUI 如果正开着,先关掉或重启它——它只在启动时扫这类自建目录。";
487
+ }
488
+ if (kind === "repository") {
489
+ return "直接调 stm32_generate:" + locate + "这个包在 CubeMX 官方 Repository 里,GUI 的包管理器也能看到它。";
490
+ }
491
+ if (kind === "cache") {
492
+ return "直接调 stm32_generate:" + locate + "注意包在下载缓存里、不在 CubeMX 安装目录,CubeMX 包管理器里看不到;" +
493
+ "要让它出现在包管理器里,重装时用 target=auto 并保证 CubeMX 根可写(落到 dsh-firmware)。";
494
+ }
495
+ return "直接调 stm32_generate:" + locate + "这个目录是调用方显式指定的:换机器或挪了目录之后要重新装(或更新安装记录),否则 generate 找不到。";
496
+ }
497
+ /** 真装。失败时已下载的东西会留在目标目录里(方便重试),最终判据是三条自检。 */
498
+ export async function installFirmware(request) {
499
+ const plan = firmwarePlanFor(request);
500
+ if (!plan.ok)
501
+ return emptyResult("install", plan.error);
502
+ const decision = decideTarget(request, plan, true);
503
+ const steps = baseSteps(plan);
504
+ const notes = [...decision.notes];
505
+ const roots = request.cubeMxRoots.map((root) => slash(root));
506
+ const progress = request.onProgress ?? (() => { });
507
+ const cloud = "install";
508
+ const finish = (extra) => ({
509
+ ...emptyResult(cloud, ""),
510
+ family: plan.family,
511
+ version: plan.version,
512
+ packageName: plan.dirName,
513
+ targetKind: decision.kind,
514
+ targetDir: decision.dir,
515
+ cacheRoot: slash(cacheRoot(request.env ?? process.env)),
516
+ cubeMxRoots: roots,
517
+ steps,
518
+ notes,
519
+ ...extra,
520
+ });
521
+ const prepare = stepOf(steps, "prepare");
522
+ if (decision.kind === "existing") {
523
+ const verify = verifyFirmwarePackage(decision.dir, plan.family);
524
+ for (const step of steps) {
525
+ step.status = "skipped";
526
+ step.detail = "本机已有官方包,不需要这一步";
527
+ }
528
+ return finish({
529
+ ok: verify.ok,
530
+ verify,
531
+ message: verify.ok
532
+ ? "本机已经有 " + plan.dirName + "(" + decision.dir + "),不用下载。"
533
+ : "本机有个 " + plan.dirName + ",但自检不过(缺 " + verify.missing.join("、") + ")。",
534
+ nextStep: "直接调 stm32_generate。",
535
+ });
536
+ }
537
+ try {
538
+ mkdirSync(decision.dir, { recursive: true });
539
+ prepare.status = "done";
540
+ prepare.detail = "已建 " + decision.dir + "(" + kindLabel(decision.kind) + ")";
541
+ }
542
+ catch (error) {
543
+ const message = error instanceof Error ? error.message : String(error);
544
+ prepare.status = "failed";
545
+ prepare.detail = "建不了 " + decision.dir + ":" + message;
546
+ return finish({ ok: false, message: "固件包没装成:建不了目标目录 —— " + message });
547
+ }
548
+ progress("目标目录:" + decision.dir);
549
+ // 暂存目录每次唯一(A11):固定名 .dsh-download 在崩溃/被杀之后会留残渣,
550
+ // 下一次安装可能读到上次的半截归档;清理也必须在 try 里——删不掉不能顶掉真正的结果。
551
+ const tempDir = path.join(decision.dir, ".dsh-download-" + String(process.pid) + "-" + String(Date.now()));
552
+ sweepStaleTemps(decision.dir);
553
+ try {
554
+ mkdirSync(tempDir, { recursive: true });
555
+ }
556
+ catch (error) {
557
+ const message = error instanceof Error ? error.message : String(error);
558
+ return finish({ ok: false, message: "固件包没装成:建不了下载暂存目录 —— " + message });
559
+ }
560
+ try {
561
+ const download = stepOf(steps, "download");
562
+ download.status = "running";
563
+ const archiveTargets = plan.archives.map((archive) => ({
564
+ path: archive.id + ".tgz",
565
+ urls: archive.urls,
566
+ minBytes: 100_000,
567
+ }));
568
+ const options = {
569
+ ...(request.signal === undefined ? {} : { signal: request.signal }),
570
+ ...(request.fetchImpl === undefined ? {} : { fetchImpl: request.fetchImpl }),
571
+ ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
572
+ onProgress: (outcome, done, total) => {
573
+ progress("下载 " + String(done) + "/" + String(total) + ":" + outcome.path + (outcome.ok ? " OK" : " 失败(" + outcome.error + ")"));
574
+ },
575
+ };
576
+ const archives = await fetchAll(archiveTargets, tempDir, options);
577
+ const coreDir = path.join(decision.dir, "Drivers", "CMSIS", "Include");
578
+ mkdirSync(coreDir, { recursive: true });
579
+ const cores = await fetchAll(plan.coreTargets, coreDir, options);
580
+ const files = archives.ok + cores.ok;
581
+ const bytes = archives.bytes + cores.bytes;
582
+ const failures = [...archives.results, ...cores.results].filter((item) => !item.ok);
583
+ if (failures.length > 0) {
584
+ download.status = "failed";
585
+ download.detail =
586
+ "有 " + String(failures.length) + " 个文件没下下来:" +
587
+ failures.slice(0, 3).map((item) => item.path + "(" + item.error + ")").join(";");
588
+ return finish({ ok: false, download: { files, bytes }, message: "固件包没装成:下载失败。", nextStep: "网络恢复后重试;或按 guides 里的手动步骤在 CubeMX 里装。" });
589
+ }
590
+ download.status = "done";
591
+ download.detail = "下载 " + String(files) + " 个文件,共 " + String(Math.round(bytes / 1024)) + " KB";
592
+ const extract = stepOf(steps, "extract");
593
+ extract.status = "running";
594
+ let extracted = 0;
595
+ for (const archive of plan.archives) {
596
+ const archivePath = path.join(tempDir, archive.id + ".tgz");
597
+ const buffer = readFileSync(archivePath);
598
+ const result = extractTarGz(buffer, decision.dir, { stripComponents: 1, mapPath: mapperFor(archive) });
599
+ if (!result.ok) {
600
+ extract.status = "failed";
601
+ extract.detail = archive.label + " 解包失败:" + result.error;
602
+ return finish({ ok: false, download: { files, bytes }, message: "固件包没装成:解包失败 —— " + result.error });
603
+ }
604
+ extracted += result.files.length;
605
+ progress("解包 " + archive.label + ":" + String(result.files.length) + " 个文件");
606
+ }
607
+ extract.status = "done";
608
+ extract.detail = "摆了 " + String(extracted) + " 个文件进 " + plan.dirName;
609
+ const packageStep = stepOf(steps, "package");
610
+ writeFileSync(path.join(decision.dir, "package.xml"), plan.packageXml, "utf8");
611
+ writeFileSync(path.join(decision.dir, NOTICES_FILE), plan.license, "utf8");
612
+ packageStep.status = "done";
613
+ packageStep.detail = "package.xml " + String(plan.packageXml.length) + " B(Release " + plan.releaseTag + " / Patch " + plan.patchTag + ")+ " + NOTICES_FILE;
614
+ const verify = verifyFirmwarePackage(decision.dir, plan.family);
615
+ const verifyStep = stepOf(steps, "verify");
616
+ if (!verify.ok) {
617
+ verifyStep.status = "failed";
618
+ verifyStep.detail = "缺:" + verify.missing.join("、");
619
+ return finish({
620
+ ok: false,
621
+ download: { files, bytes },
622
+ verify,
623
+ message: "固件包没装成:自检缺 " + verify.missing.join("、") + "。",
624
+ nextStep: "把这段报错贴给我;或者改用 CubeMX 包管理器装官方包。",
625
+ });
626
+ }
627
+ verifyStep.status = "done";
628
+ verifyStep.detail = "三条判据全过(" + String(verify.checks.length) + " 项检查)";
629
+ // 落点记进 <cacheRoot>/firmware/installed.json:cubeMx 落点靠扫根就能找到,但 cache / 显式 targetDir
630
+ // 在 CubeMX 根以外,generate 只能靠这条记录 + 缓存目录把它们找回来(B10)。
631
+ const recordProblem = rememberFirmwareInstall(request.env ?? process.env, plan.dirName, decision.dir, decision.kind);
632
+ if (recordProblem !== "") {
633
+ notes.push("没写进安装记录(" + recordProblem + "):stm32_generate 仍会搜下载缓存,但显式指定的目录可能找不到。");
634
+ }
635
+ return finish({
636
+ ok: true,
637
+ download: { files, bytes },
638
+ verify,
639
+ message: "固件包装好了:" + plan.dirName + " 在 " + decision.dir + "(" + kindLabel(decision.kind) + ")。" +
640
+ "下载 " + String(files) + " 个文件 / " + String(Math.round(bytes / 1024)) + " KB,三条判据全过。",
641
+ nextStep: nextStepFor(decision.kind, decision.dir, plan.dirName),
642
+ });
643
+ }
644
+ catch (error) {
645
+ // 没预料到的异常(杀软锁文件、磁盘满、路径超长)也要变成一份报告,而不是把异常抛给工具层(A11)。
646
+ const message = error instanceof Error ? error.message : String(error);
647
+ for (const step of steps) {
648
+ if (step.status === "running") {
649
+ step.status = "failed";
650
+ step.detail = message;
651
+ }
652
+ }
653
+ return finish({ ok: false, message: "固件包没装成:安装过程抛了没预料到的异常 —— " + message });
654
+ }
655
+ finally {
656
+ try {
657
+ rmSync(tempDir, { recursive: true, force: true });
658
+ }
659
+ catch (error) {
660
+ const message = error instanceof Error ? error.message : String(error);
661
+ notes.push("下载暂存目录没清掉(" + message + "):" + tempDir + ",可以手工删。");
662
+ }
663
+ }
664
+ }
665
+ /** 计划 / 真装的总入口。 */
666
+ export async function planOrInstallFirmware(request) {
667
+ return (request.mode ?? "plan") === "install" ? installFirmware(request) : firmwareInstallPlan(request);
668
+ }