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
@@ -5,25 +5,85 @@
5
5
  * openocd -f <cfg> -c "program <elf> verify reset exit"
6
6
  * 跑完 reset run 就退出,探针立刻释放,不留后台 server,也不停核。
7
7
  */
8
- import { existsSync, readFileSync, statSync } from "node:fs";
9
- import { basename, isAbsolute, resolve } from "node:path";
8
+ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
9
+ import { basename, dirname, isAbsolute, resolve } from "node:path";
10
10
  import { describeSearchScope, resolveSearchConfig } from "../data/search-roots.js";
11
- import { detectBuildDir, findElf } from "./build.js";
11
+ import { usbDiagnosis } from "./doctor.js";
12
+ import { detectBuildDir, elfSelectionNote, findElf } from "./build.js";
12
13
  import { findIocFile } from "./generate.js";
13
14
  import { summarizeIoc } from "./ioc.js";
14
- import { resolveFromDirs } from "./probe.js";
15
+ import { resolveToolIn } from "./probe.js";
15
16
  import { runStreaming } from "./subprocess-runner.js";
16
17
  /**
17
18
  * A5 守卫:.ioc 里没启用 Serial Wire 时,CubeMX 会生成 __HAL_AFIO_REMAP_SWJ_DISABLE(),
18
19
  * 烧完 SWD 就废了,下一次只能靠 BOOT0 进系统 bootloader 救回来。
19
20
  * 所以**烧录前**先看 .ioc,宁可拒绝也不要烧成砖。没有 .ioc 时不拦(可能是别人给的 hex 工程)。
20
21
  */
21
- export function checkNoDebugGuard(projectDir, allowNoDebug = false) {
22
+ export function checkNoDebugGuard(projectDir, allowNoDebug = false, explicitIoc = "") {
22
23
  if (allowNoDebug)
23
24
  return { blocked: false, errors: [], notes: [] };
24
- const iocPath = findIocFile(projectDir);
25
- if (iocPath === null)
26
- return { blocked: false, errors: [], notes: [] };
25
+ const iocPath = explicitIoc !== ""
26
+ ? (isAbsolute(explicitIoc) ? explicitIoc : resolve(projectDir, explicitIoc))
27
+ : findIocFile(projectDir);
28
+ if (iocPath === null || !existsSync(iocPath)) {
29
+ // 审计 A6:findIocFile 只认「唯一」,0 个或有多个都返回 null。以前这里静默放行,
30
+ // 用户拿别人的工程(或 demo.ioc + demo_backup.ioc)时 SWD 守卫等于不存在,
31
+ // 烧下去 SWD 被关掉只能 BOOT0 救砖。现在至少要把"守卫没生效"说清楚。
32
+ let names = [];
33
+ try {
34
+ names = existsSync(projectDir)
35
+ ? readdirSync(projectDir).filter((name) => name.toLowerCase().endsWith(".ioc"))
36
+ : [];
37
+ }
38
+ catch {
39
+ names = [];
40
+ }
41
+ const why = iocPath !== null && explicitIoc !== ""
42
+ ? "指定的 .ioc 不存在:" + iocPath
43
+ : names.length === 0
44
+ ? "工程里没有 .ioc"
45
+ : "工程里有 " + String(names.length) + " 个 .ioc(" + names.join("、") + "),分不清用哪个";
46
+ // 2c:没有 .ioc(寄存器工程就是这样)时退回看 openocd.cfg 的 transport——
47
+ // 插件生成的 cfg 固定是 hla_swd;用户换成 jtag 的 cfg 就给警告,守卫从此也覆盖寄存器工程。
48
+ const cfg = findProjectConfig(projectDir);
49
+ if (cfg !== null) {
50
+ try {
51
+ const cfgText = readFileSync(cfg, "utf8");
52
+ const isSwd = /transport\s+select\s+(?:hla_)?swd/iu.test(cfgText);
53
+ const isJtag = /transport\s+select\s+jtag/iu.test(cfgText);
54
+ if (isSwd) {
55
+ return {
56
+ blocked: false,
57
+ errors: [],
58
+ notes: ["SWD 守卫(openocd.cfg 版):transport 是 swd,探针侧不会关调试口;固件侧仍可能自己关 SWD,烧录前自行确认固件没动 AFIO_MAPR。"],
59
+ };
60
+ }
61
+ if (isJtag) {
62
+ return {
63
+ blocked: false,
64
+ errors: [],
65
+ notes: [
66
+ "SWD 守卫(openocd.cfg 版):openocd.cfg 选了 jtag 而不是 swd。F103 的 JTAG 引脚与 SWD 引脚复用," +
67
+ "用 JTAG 烧录前确认固件没有把 PA13/PA14 改作他用。",
68
+ ],
69
+ };
70
+ }
71
+ return { blocked: false, errors: [], notes: ["SWD 守卫没生效:" + why + ";openocd.cfg 里也没有 transport select,无法判断。"] };
72
+ }
73
+ catch {
74
+ return { blocked: false, errors: [], notes: ["读不了 openocd.cfg(" + cfg + "),跳过 SWD 守卫"] };
75
+ }
76
+ }
77
+ return {
78
+ blocked: false,
79
+ errors: [],
80
+ notes: [
81
+ "SWD 守卫没生效:" + why + "。烧录前请自己确认 .ioc 里 PA13 是 SYS_JTMS-SWDIO、PA14 是 SYS_JTCK-SWCLK;" +
82
+ "没启用 Serial Wire 时烧下去会关掉 SWD,之后只能 BOOT0=1 进系统 bootloader 救回来。",
83
+ "想让它自动检查:工程根目录只留一个 .ioc,或给 stm32_flash 传 iocPath 指向正确的那份。",
84
+ ],
85
+ };
86
+ }
27
87
  let summary;
28
88
  try {
29
89
  summary = summarizeIoc(readFileSync(iocPath, "utf8"), iocPath);
@@ -98,11 +158,38 @@ export function resolveElf(projectDir, request) {
98
158
  return { elf: null, buildDir, note: "构建目录里没有 .elf(先跑 stm32_build)" };
99
159
  return { elf: elfInfo.path, buildDir, note: "" };
100
160
  }
161
+ /** 按日志行特征归码(2d):一行命中即返回,多类并存时按先见者优先。 */
162
+ export function errorCodeOfLines(lines) {
163
+ for (const raw of lines) {
164
+ const line = raw.toLowerCase();
165
+ if (/unable to find a matching cmsis-dap device|no device found/.test(line))
166
+ return "no-probe";
167
+ if (/adapter speed could not be limited|target is openocd and must be halted/.test(line))
168
+ return "probe-busy";
169
+ // 真板子取证(2026-10-28):两个 openocd 同时抓同一个 CMSIS-DAP 时,openocd 不会报"忙",
170
+ // 而是两边交替收发导致 DAP 事务错位——满屏 transfer count mismatch / command mismatch。
171
+ if (/cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/.test(line))
172
+ return "probe-busy";
173
+ if (/error connecting dp|cannot read idr|ap lock|sticky error/.test(line))
174
+ return "swd-locked";
175
+ if (/flash programming|write protected|read protected|memory protected/.test(line))
176
+ return "flash-protected";
177
+ if (/target voltage may be too low|no power/.test(line))
178
+ return "no-power";
179
+ if (/device id|cannot identify|unexpected idcode/.test(line))
180
+ return "target-mismatch";
181
+ }
182
+ return "unknown";
183
+ }
101
184
  /** 认 openocd 的 ** Programming Finished ** / ** Verified OK ** 与 Error: 行。 */
102
185
  export function parseFlashLog(text) {
103
186
  const programmed = /\*\*\s*Programming Finished\s*\*\*/u.test(text);
104
187
  const verified = /\*\*\s*Verified OK\s*\*\*/u.test(text);
188
+ // A25:以成功序列为主判据。openocd 成功时也会打 Error: 前缀的行(无关 ACK / DAP 噪声),
189
+ // 以前把它们一律当失败,于是「烧录成功、已校验」被判成失败。
190
+ const succeeded = programmed && verified;
105
191
  const errors = [];
192
+ const noise = [];
106
193
  const seen = new Set();
107
194
  for (const raw of text.split(/\r?\n/u)) {
108
195
  const line = raw.trim();
@@ -118,12 +205,28 @@ export function parseFlashLog(text) {
118
205
  if (seen.has(line))
119
206
  continue;
120
207
  seen.add(line);
121
- errors.push(line);
208
+ if (succeeded)
209
+ noise.push(line);
210
+ else
211
+ errors.push(line);
122
212
  }
123
- return { programmed, verified, errors };
213
+ const flat = [...errors, ...noise];
214
+ const errorCode = succeeded ? "" : errorCodeOfLines(flat.length === 0 ? [text] : flat);
215
+ return { programmed, verified, errors, noise, errorCode };
216
+ }
217
+ export const HINT_DP = "连不上芯片(Error connecting DP):固件里可能关了 SWD(__HAL_AFIO_REMAP_SWJ_DISABLE),需要 BOOT0=1 重启进系统 bootloader 再烧,或按住复位键在连接瞬间松开。";
218
+ export const HINT_PROBE = "找不到 CMSIS-DAP 探针:检查 USB、是否被 openocd/调试会话占用(先停掉正在跑的调试)。";
219
+ export const HINT_BUSY = "探针被别的进程同时访问(两个 openocd 抢同一个 CMSIS-DAP 时不会报错,而是满屏 transfer count mismatch):先关掉调试会话或另一个 openocd,再烧一次。";
220
+ /** openocd 报"找不到设备"的那几行错误行(2a 的判定基准,纯函数便于单测)。 */
221
+ export function probeMissingLines(errors) {
222
+ return errors.filter((line) => /CMSIS-DAP device|no device found/iu.test(line));
223
+ }
224
+ /** USB 形态诊断的结论该以什么 note 呈现(unknown 静默:诊断失败不能把失败报告搞得更吵)。 */
225
+ export function usbNoteFor(kind, detail) {
226
+ if (kind === "unknown")
227
+ return null;
228
+ return "USB 形态:" + detail;
124
229
  }
125
- const HINT_DP = "连不上芯片(Error connecting DP):固件里可能关了 SWD(__HAL_AFIO_REMAP_SWJ_DISABLE),需要 BOOT0=1 重启进系统 bootloader 再烧,或按住复位键在连接瞬间松开。";
126
- const HINT_PROBE = "找不到 CMSIS-DAP 探针:检查 USB、是否被 openocd/调试会话占用(先停掉正在跑的调试)。";
127
230
  export async function runFlash(subprocess, request) {
128
231
  const projectDir = resolve(request.projectDir);
129
232
  const config = resolveSearchConfig(process.env, request.binDirs === undefined ? {} : { binDirs: request.binDirs });
@@ -139,8 +242,14 @@ export async function runFlash(subprocess, request) {
139
242
  }
140
243
  const elfPath = elfResolved.elf;
141
244
  const elfSize = statSync(elfPath).size;
245
+ // F1:多个 .elf 并存时说清"烧的是哪一个、为什么是它"。
246
+ const selectionNote = elfSelectionNote(dirname(elfPath));
247
+ if (selectionNote !== "")
248
+ notes.push(selectionNote);
142
249
  // A5:先看 .ioc,别把 SWD 烧死。
143
- const guard = checkNoDebugGuard(projectDir, request.allowNoDebug === true);
250
+ const guard = checkNoDebugGuard(projectDir, request.allowNoDebug === true, request.iocPath ?? "");
251
+ if (!guard.blocked && guard.notes.length > 0)
252
+ notes.push(...guard.notes);
144
253
  if (guard.blocked) {
145
254
  return {
146
255
  ok: false, projectDir, elfPath, elfSize, command: "", args: [], configs: [],
@@ -151,7 +260,7 @@ export async function runFlash(subprocess, request) {
151
260
  }
152
261
  const openOcd = request.openOcdPath !== undefined && request.openOcdPath !== ""
153
262
  ? request.openOcdPath
154
- : resolveFromDirs("openocd", config.binDirs);
263
+ : await resolveToolIn(subprocess, ["openocd"], config.binDirs);
155
264
  if (openOcd === null) {
156
265
  return {
157
266
  ok: false, projectDir, elfPath, elfSize, command: "", args: [], configs: [],
@@ -200,10 +309,22 @@ export async function runFlash(subprocess, request) {
200
309
  errors.push("openocd 启动失败:" + outcome.spawnError);
201
310
  if (outcome.timedOut)
202
311
  errors.push("超时(" + String(request.timeoutMs ?? 120_000) + " ms):烧录没跑完");
312
+ if (verdict.noise.length > 0) {
313
+ notes.push("openocd 成功路径上的 " + String(verdict.noise.length) + " 条 Error: 行按噪声处理(首条:" +
314
+ (verdict.noise[0] ?? "") + ")");
315
+ }
203
316
  if (errors.some((line) => /Error connecting DP/u.test(line)))
204
317
  notes.push(HINT_DP);
205
- if (errors.some((line) => /CMSIS-DAP device|no device found/iu.test(line)))
318
+ const probeMissing = probeMissingLines(errors);
319
+ if (probeMissing.length > 0) {
206
320
  notes.push(HINT_PROBE);
321
+ // 2a:找不到设备时顺手做一次 USB 形态诊断——"没插"与"这台机器根本没 USB"是两种答案。
322
+ // 诊断失败静默(unknown 不进 notes),绝不能让诊断把失败报告搞得更吵。
323
+ const usb = await usbDiagnosis(subprocess, request.signal);
324
+ const extra = usbNoteFor(usb.kind, usb.detail);
325
+ if (extra !== null)
326
+ notes.push(extra);
327
+ }
207
328
  const ok = outcome.exitCode === 0 && outcome.spawnError === null && !outcome.timedOut && verdict.programmed && errors.length === 0;
208
329
  if (!ok && verdict.programmed && !verdict.verified)
209
330
  notes.push("写入成功但校验没过,建议重试或降低 adapter speed");
@@ -212,11 +333,20 @@ export async function runFlash(subprocess, request) {
212
333
  const message = ok
213
334
  ? "烧录成功(" + ((Date.now() - startedAt) / 1000).toFixed(1) + " s" + (verdict.verified ? ",已校验" : "") + ")"
214
335
  : "烧录失败:" + (errors[0] ?? "openocd 退出码 " + String(outcome.exitCode));
336
+ // 2d:errorCode 供模型分流(重试 / 换线 / 停会话 / 直接问人)。
337
+ let errorCode = verdict.errorCode;
338
+ if (!ok && (outcome.spawnError !== null || outcome.timedOut))
339
+ errorCode = "unknown";
340
+ if (!ok && errorCode === "swd-locked" && errors.some((line) => /Error connecting DP/u.test(line)))
341
+ errorCode = "swd-locked";
342
+ if (!ok && errorCode === "probe-busy")
343
+ notes.push(HINT_BUSY);
215
344
  return {
216
345
  ok, projectDir, elfPath, elfSize, command, args, configs,
217
346
  durationMs: Date.now() - startedAt,
218
347
  ...(outcome.exitCode === null ? {} : { exitCode: outcome.exitCode }),
219
348
  programmed: verdict.programmed, verified: verdict.verified,
349
+ ...(errorCode === "" ? {} : { errorCode }),
220
350
  errors, message, logTail: log.split(/\r?\n/u).slice(-25).join("\n"), notes,
221
351
  };
222
352
  }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * L0:文件系统与 Windows 长路径(> 260 字符)的适配。
3
+ *
4
+ * 为什么单独一个模块:建工程要做的两件事全踩在这条线上 ——
5
+ * ① 从固件包原样拷 Drivers/**(层级深:Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc/…);
6
+ * ② 目标工程常在长路径下(C:\Users\<长用户名>\OneDrive\…\工程)。
7
+ * 两条路径一拼就可能超过 Windows 的 MAX_PATH,表现是 fs 抛 ENAMETOOLONG / ENOENT,
8
+ * 而报告里只说"写盘失败",看不出是路径长度问题(审计 B17)。
9
+ *
10
+ * 做法:Windows 上把**绝对**路径规范成 \\?\ 扩展长度形式再交给 fs(相对路径不碰:
11
+ * 加了前缀反而会指到别的根)。POSIX 原样返回 —— 那边没有 260 字符上限,加前缀只会让路径不存在。
12
+ *
13
+ * 目录追踪(mkdirTrackedLong)也放这里,而不是留在 scaffold:写完要能"精确清掉本次新建的目录",
14
+ * 两个实现各写一份迟早会对不上(清理漏一个 = 留下半成品目录)。
15
+ */
16
+ import fs from "node:fs";
17
+ import path from "node:path";
18
+ /** Windows 的扩展长度前缀。 */
19
+ const LONG_PREFIX = "\\\\?\\";
20
+ /** UNC 路径(\\server\share)要用 \\?\UNC\ 而不是 \\?\ 直接拼。 */
21
+ const UNC_PREFIX = "\\\\?\\UNC\\";
22
+ /**
23
+ * 把路径规范成 Windows 扩展长度形式(只在需要时加前缀)。
24
+ * 已经是 \\?\ 开头的原样返回;相对路径也原样返回(前缀化会让它指到错误的根)。
25
+ */
26
+ export function toLongPath(p) {
27
+ if (process.platform !== "win32")
28
+ return p;
29
+ if (p === "" || p.startsWith(LONG_PREFIX))
30
+ return p;
31
+ if (!path.isAbsolute(p))
32
+ return p;
33
+ // \\?\ 之后 Windows 不再做任何规范化:正斜杠、"."、".." 都会被当字面量,
34
+ // 所以这里只把分隔符统一成反斜杠,其余原样交给调用方(scaffold 传进来的都是 path.join 的结果)。
35
+ const normalized = p.replace(/\//gu, "\\");
36
+ if (normalized.startsWith("\\\\"))
37
+ return UNC_PREFIX + normalized.slice(2);
38
+ return LONG_PREFIX + normalized;
39
+ }
40
+ /** 存在性检查(长路径安全)。 */
41
+ export function existsLong(p) {
42
+ return fs.existsSync(toLongPath(p));
43
+ }
44
+ /**
45
+ * mkdir -p,同时记下**这次真正新建**的目录。
46
+ * 为什么要记:写盘中途失败时要清掉半成品目录,而"清"必须精确到本次新建的,
47
+ * 用户原有的目录一个都不能动(递归删用户目录 = 把审计里的丢数据问题换个地方重演)。
48
+ */
49
+ export function mkdirTrackedLong(dir, created) {
50
+ const missing = [];
51
+ let cursor = path.resolve(dir);
52
+ while (!existsLong(cursor)) {
53
+ missing.push(cursor);
54
+ const parent = path.dirname(cursor);
55
+ if (parent === cursor)
56
+ break;
57
+ cursor = parent;
58
+ }
59
+ fs.mkdirSync(toLongPath(dir), { recursive: true });
60
+ created.push(...missing);
61
+ }
62
+ /** 复制失败时的中文说明:把"路径太长"这个最容易被误判成权限/杀软的原因写清楚。 */
63
+ export function describeCopyFailure(from, to, error) {
64
+ const code = error?.code ?? "";
65
+ const detail = error instanceof Error ? error.message : String(error);
66
+ const tooLong = code === "ENAMETOOLONG" || Math.max(from.length, to.length) > 240;
67
+ const hint = tooLong
68
+ ? "路径太长(Windows 默认上限 260 字符,已尝试 \\?\ 前缀):把工程或固件包挪到更短的目录(例如 D:\\work\\blink)再试。"
69
+ : "检查源文件是否存在、目标目录是否可写。";
70
+ return "复制失败(" + (code === "" ? "未知错误" : code) + "):" + from + " -> " + to + "。" + hint + " 原始错误:" + detail;
71
+ }
72
+ /** 单文件复制(长路径安全)。目标目录必须由调用方先建好(用 mkdirTrackedLong)。 */
73
+ export function copyFileLong(from, to) {
74
+ try {
75
+ fs.copyFileSync(toLongPath(from), toLongPath(to));
76
+ }
77
+ catch (error) {
78
+ throw new Error(describeCopyFailure(from, to, error));
79
+ }
80
+ }
81
+ /**
82
+ * 整树复制(长路径安全),返回复制的文件数。
83
+ * skipPrefixes 是相对源根、带结尾斜杠的前缀("CMSIS/docs/"),命中就整棵跳过。
84
+ * created 收集本次新建的目录,供写盘失败时精确清理。
85
+ */
86
+ export function copyTreeLong(from, to, skipPrefixes = [], created = []) {
87
+ let count = 0;
88
+ const walk = (src, dest, relDir) => {
89
+ mkdirTrackedLong(dest, created);
90
+ for (const entry of fs.readdirSync(toLongPath(src), { withFileTypes: true })) {
91
+ const rel = relDir === "" ? entry.name : relDir + "/" + entry.name;
92
+ const source = path.join(src, entry.name);
93
+ const target = path.join(dest, entry.name);
94
+ if (entry.isDirectory()) {
95
+ if (skipPrefixes.some((prefix) => (rel + "/").startsWith(prefix)))
96
+ continue;
97
+ walk(source, target, rel);
98
+ }
99
+ else {
100
+ copyFileLong(source, target);
101
+ count += 1;
102
+ }
103
+ }
104
+ };
105
+ walk(from, to, "");
106
+ return count;
107
+ }
@@ -0,0 +1,118 @@
1
+ /**
2
+ * L2:generate 的复用缓存 —— 让「.ioc 没变」的再次生成零成本。
3
+ *
4
+ * 实测依据(docs/development-notes.md 的「generate 为什么慢」一节):
5
+ * 同一个 .ioc、同一个 CubeMX 版本、同一种布局,两次生成的 6 个文件字节完全一致
6
+ * (整树 sha256 = a78a451d…b8f5d99);把 thirdparties/pdsc 停放掉再生成,产物依然
7
+ * 一模一样。所以产物可以按「.ioc 内容 + CubeMX 二进制指纹 + 布局」缓存:
8
+ * 命中且工程里每个目标文件的 hash 都对得上时,直接跳过 CubeMX(3–4 分钟 → 毫秒)。
9
+ *
10
+ * 这里只做确定性计算与读写,不启动进程、不碰工程源码,便于单测。
11
+ */
12
+ import { createHash } from "node:crypto";
13
+ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
14
+ import { join } from "node:path";
15
+ /** 缓存文件名(放在工程的 .dsh-stm32/ 下,跟着工程走)。 */
16
+ export const CACHE_FILE = "generate-cache.json";
17
+ /** 缓存格式版本:结构变了就 +1,旧缓存自动失效。 */
18
+ export const CACHE_VERSION = 1;
19
+ /** 文本/内容的 sha256(hex)。 */
20
+ export function sha256Text(text) {
21
+ return createHash("sha256").update(text, "utf8").digest("hex");
22
+ }
23
+ /** 文件内容的 sha256;文件不存在或读不到时返回 null。 */
24
+ export function sha256File(absPath) {
25
+ try {
26
+ if (!existsSync(absPath))
27
+ return null;
28
+ return createHash("sha256").update(readFileSync(absPath)).digest("hex");
29
+ }
30
+ catch {
31
+ return null;
32
+ }
33
+ }
34
+ /**
35
+ * CubeMX 二进制指纹:java + jar 的大小与 mtime。
36
+ *
37
+ * 不用版本号字符串:CubeMX 的 jar 里没有稳定可解析的版本入口,而大小+mtime
38
+ * 在「升级/重装 CubeMX」时一定会变,这正是缓存该失效的时刻。
39
+ */
40
+ export function cubeMxStamp(javaPath, jarPath) {
41
+ const part = (p) => {
42
+ try {
43
+ const st = statSync(p);
44
+ return String(st.size) + ":" + String(Math.round(st.mtimeMs));
45
+ }
46
+ catch {
47
+ return "missing";
48
+ }
49
+ };
50
+ return part(javaPath) + "|" + part(jarPath);
51
+ }
52
+ export function computeCacheKey(iocSha256, cubeMxStampValue, layout) {
53
+ return sha256Text("v" + String(CACHE_VERSION) + "\n" + iocSha256 + "\n" + cubeMxStampValue + "\n" + layout);
54
+ }
55
+ /** 一次算齐键的三部分(ioc 内容、CubeMX 指纹、布局)。 */
56
+ export function cacheKeyFor(iocText, javaPath, jarPath, layout) {
57
+ const iocSha256 = sha256Text(iocText);
58
+ const stamp = cubeMxStamp(javaPath, jarPath);
59
+ return { key: computeCacheKey(iocSha256, stamp, layout), iocSha256, cubeMxStamp: stamp };
60
+ }
61
+ /** 读缓存;文件缺失/损坏/版本不符都返回 null(当作没有缓存)。 */
62
+ export function readCache(stateDir) {
63
+ const path = join(stateDir, CACHE_FILE);
64
+ if (!existsSync(path))
65
+ return null;
66
+ try {
67
+ const parsed = JSON.parse(readFileSync(path, "utf8"));
68
+ if (parsed === null || typeof parsed !== "object")
69
+ return null;
70
+ if (parsed.version !== CACHE_VERSION)
71
+ return null;
72
+ if (typeof parsed.key !== "string" || !Array.isArray(parsed.files))
73
+ return null;
74
+ return parsed;
75
+ }
76
+ catch {
77
+ return null;
78
+ }
79
+ }
80
+ export function writeCache(stateDir, entry) {
81
+ mkdirSync(stateDir, { recursive: true });
82
+ writeFileSync(join(stateDir, CACHE_FILE), JSON.stringify(entry, null, 1) + "\n", "utf8");
83
+ }
84
+ /** 按本次真正落位的文件算一条缓存记录;任何一个文件 hash 取不到就返回 null(不缓存)。 */
85
+ export function entryFromFiles(key, iocSha256, cubeMxStampValue, layout, projectDir, targets, now = Date.now()) {
86
+ const files = [];
87
+ for (const target of targets) {
88
+ const hash = sha256File(join(projectDir, target));
89
+ if (hash === null)
90
+ return null;
91
+ files.push({ target, sha256: hash });
92
+ }
93
+ return { version: CACHE_VERSION, key, iocSha256, cubeMxStamp: cubeMxStampValue, layout, createdAt: now, files };
94
+ }
95
+ /**
96
+ * 判断缓存能否直接复用。
97
+ *
98
+ * 三重校验:键一致(.ioc + CubeMX 指纹 + 布局)、文件都在、每个文件内容 hash 对得上。
99
+ * 只要有一个文件被手改/删掉,就不算命中——宁可重跑 CubeMX,也不把过期产物当好结果。
100
+ */
101
+ export function cacheHit(entry, key, projectDir) {
102
+ if (entry === null)
103
+ return { hit: false, reason: "没有可用缓存(本工程还没成功生成过)", entry: null, fileCount: 0 };
104
+ if (entry.key !== key) {
105
+ return { hit: false, reason: ".ioc 内容、CubeMX 版本或布局变过(缓存键不一致)", entry: null, fileCount: 0 };
106
+ }
107
+ if (entry.files.length === 0)
108
+ return { hit: false, reason: "缓存里没有文件清单", entry: null, fileCount: 0 };
109
+ for (const file of entry.files) {
110
+ const actual = sha256File(join(projectDir, file.target));
111
+ if (actual === null)
112
+ return { hit: false, reason: "缓存里的产物不见了:" + file.target, entry: null, fileCount: 0 };
113
+ if (actual !== file.sha256) {
114
+ return { hit: false, reason: "产物与缓存不一致(被改过):" + file.target, entry: null, fileCount: 0 };
115
+ }
116
+ }
117
+ return { hit: true, reason: "", entry, fileCount: entry.files.length };
118
+ }
@@ -10,19 +10,26 @@
10
10
  export function layoutCommand(layout) {
11
11
  return layout === "coupled" ? "generate all_code_in_main" : "generate one_file_per_ip";
12
12
  }
13
+ /** 路径里有空格就加引号(CubeMX 脚本按空格切参数)。 */
14
+ function quoteArg(value) {
15
+ return value.includes(" ") ? '"' + value + '"' : value;
16
+ }
13
17
  /**
14
18
  * CubeMX -q 脚本正文。
15
19
  *
16
20
  * 注意:generate code 的参数必须是**目录**;传 .ioc 路径会静默无操作(M0 E3)。
21
+ *
22
+ * firmwareDir 非空时插一行 project setCustomFWPath —— 这是实测**唯一**能让 CubeMX
23
+ * 真的用上指定固件包的机制(docs §14:丢进 Repository 会被静默忽略、只改 .ioc 会挂死)。
24
+ * 它必须排在 config load 之后、generate code 之前。
17
25
  */
18
- export function buildGenerateScript(iocPath, outDir, layout) {
19
- return [
20
- "config load " + iocPath,
21
- layoutCommand(layout),
22
- "generate code " + outDir,
23
- "exit",
24
- "",
25
- ].join("\n");
26
+ export function buildGenerateScript(iocPath, outDir, layout, firmwareDir = "") {
27
+ const lines = ["config load " + iocPath];
28
+ const firmware = firmwareDir.trim();
29
+ if (firmware !== "")
30
+ lines.push("project setCustomFWPath " + quoteArg(firmware));
31
+ lines.push(layoutCommand(layout), "generate code " + outDir, "exit", "");
32
+ return lines.join("\n");
26
33
  }
27
34
  /** CubeMX 自己拼写为 "Code succesfully generated under ..."。 */
28
35
  const SUCCESS_PATTERN = /Code succesfully generated under/iu;
@@ -40,15 +47,26 @@ const KNOWN_NOISE = [
40
47
  function isKnownNoise(line) {
41
48
  return KNOWN_NOISE.some((entry) => entry.pattern.test(line));
42
49
  }
50
+ /**
51
+ * 脚本命令不认(CubeMX 版本换了命令名)时的标志。
52
+ * 为什么单独判:setCustomFWPath 被忽略时 CubeMX 照样打印生成成功,
53
+ * 于是会拿到一个「成功但用错固件包」的结果 —— 比直接失败更难查。
54
+ */
55
+ const UNKNOWN_COMMAND_PATTERN = /Unknown command|Unrecognized command|Invalid command|command not found|Command not recognized/iu;
43
56
  /** 把 CubeMX 输出判成结论。只要出现成功行就算成功,其余按错误归类。 */
44
57
  export function parseGenerateLog(text) {
45
58
  const errors = [];
59
+ const commandErrors = [];
46
60
  const knownNoise = [];
47
61
  let successLine = "";
48
62
  for (const rawLine of text.split(/\r?\n/u)) {
49
63
  const line = rawLine.trim();
50
64
  if (line === "")
51
65
  continue;
66
+ if (UNKNOWN_COMMAND_PATTERN.test(line)) {
67
+ commandErrors.push(line.slice(0, 300));
68
+ continue;
69
+ }
52
70
  if (SUCCESS_PATTERN.test(line)) {
53
71
  successLine = line;
54
72
  continue;
@@ -63,6 +81,10 @@ export function parseGenerateLog(text) {
63
81
  continue;
64
82
  errors.push(line.slice(0, 300));
65
83
  }
84
+ // 脚本命令不被认(例如 setCustomFWPath)时,成功行也不作数。
85
+ if (commandErrors.length > 0) {
86
+ return { ok: false, successLine, errors: [...commandErrors, ...errors], knownNoise };
87
+ }
66
88
  // 有成功行就以成功行为准:CubeMX 过程中偶发的 ERROR(如 Updater is busy)不代表生成失败。
67
89
  if (successLine !== "") {
68
90
  for (const error of errors)