@geastack/cli 0.1.103 → 0.1.104

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.
@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs'
2
2
  import { mkdirSync, writeFileSync } from 'node:fs'
3
3
  import path from 'node:path'
4
4
  import { execFileSync } from 'node:child_process'
5
+ import { createRequire } from 'node:module'
6
+ import { randomBytes } from 'node:crypto'
5
7
 
6
8
  import { crc32, decodeRgb565Raw, decodeRgb565Rle } from './image.mjs'
7
9
 
@@ -16,8 +18,9 @@ import { crc32, decodeRgb565Raw, decodeRgb565Rle } from './image.mjs'
16
18
  // freshly flashed board. serialport with hupcl off leaves the lines alone.
17
19
 
18
20
  let serialportModule = null
19
- async function loadSerialport() {
21
+ export async function loadSerialport() {
20
22
  if (serialportModule) return serialportModule
23
+ if (process.platform === 'win32') settleWindowsSerialCallbacks()
21
24
  try {
22
25
  serialportModule = await import('serialport')
23
26
  } catch (error) {
@@ -26,6 +29,42 @@ async function loadSerialport() {
26
29
  return serialportModule
27
30
  }
28
31
 
32
+ // @serialport/bindings-cpp completes Windows reads and writes on its own
33
+ // thread and calls back into JavaScript from a uv_async handle with a plain
34
+ // napi Call. Since Node.js 26.4 nothing drains the microtask queue after such a
35
+ // call (nodejs/node#66158), so the promise the binding resolves only continues
36
+ // when some other macrotask runs: every write and read waited for the next
37
+ // timer or console line, GEADEV commands timed out, and a chatty app stalled
38
+ // on a console the host stopped draining. Until the binding scopes its
39
+ // callbacks (serialport/bindings-cpp#243), each native read/write callback
40
+ // queues a setImmediate, after which Node drains microtasks. This must run
41
+ // before load-bindings.js promisifies the native functions, i.e. before
42
+ // anything imports serialport.
43
+ let windowsCallbacksSettled = false
44
+ function settleWindowsSerialCallbacks() {
45
+ if (windowsCallbacksSettled) return
46
+ windowsCallbacksSettled = true
47
+ let binding
48
+ try {
49
+ const fromSerialport = createRequire(createRequire(import.meta.url).resolve('serialport/package.json'))
50
+ binding = fromSerialport('@serialport/bindings-cpp/dist/serialport-bindings').binding
51
+ } catch {
52
+ return
53
+ }
54
+ const settle = () => {}
55
+ for (const name of ['read', 'write']) {
56
+ const native = binding?.[name]
57
+ if (typeof native !== 'function') continue
58
+ binding[name] = (...args) => {
59
+ const callback = args.pop()
60
+ return native(...args, (...result) => {
61
+ callback(...result)
62
+ setImmediate(settle)
63
+ })
64
+ }
65
+ }
66
+ }
67
+
29
68
  export function geadevFragment(line) {
30
69
  const index = line.indexOf('GEADEV:')
31
70
  return index >= 0 ? line.slice(index) : line
@@ -462,35 +501,29 @@ export const geadev = {
462
501
  // Installs an app image through the running app (GEADEV OTA): it lands in
463
502
  // the next OTA slot and the board restarts into it. Same throttled raw
464
503
  // stream as pushFile.
465
- async otaUpdate(d, source, { timeoutMs = 120000, stderr = () => {} } = {}) {
466
- const data = readFileSync(source)
467
- // End whatever partial line the console holds first. A failed ROM-downloader
468
- // attempt leaves esptool's sync bytes in it with no newline, and the command
469
- // appended to them is refused as line-too-long -- every retry, until a bare
470
- // newline clears it.
471
- await d.writeRaw(Buffer.from('\n'))
472
- await new Promise((resolve) => setTimeout(resolve, 100))
473
- await d.writeLine(`GEADEV OTA ${data.length} ${crc32(data)}`)
474
- const ready = await waitFor(d, 'GEADEV:OTA READY', 'GEADEV:OTA ERR', 15000, 'OTA READY')
475
- const startedAt = Date.now()
476
- await new Promise((resolve) => setTimeout(resolve, 300))
477
- const burst = 2048
478
- for (let offset = 0; offset < data.length; offset += burst) {
479
- await d.writeRaw(data.subarray(offset, Math.min(offset + burst, data.length)))
480
- await new Promise((resolve) => setTimeout(resolve, 4))
481
- if (((offset / burst) | 0) % 128 === 0) stderr(` upload ${Math.floor((offset * 100) / data.length)}%`)
482
- }
483
- let line
484
- try {
485
- line = await waitFor(d, 'GEADEV:OTA OK', 'GEADEV:OTA ERR', timeoutMs, 'OTA OK')
486
- } catch (error) {
487
- // The board restarts right after the reply, and firmware whose console
488
- // drops output on a full TX FIFO can lose it; the caller decides from
489
- // what boots.
490
- if (!error.message.startsWith('GEADEV:OTA ERR')) error.uploaded = true
491
- throw error
504
+ //
505
+ // An interrupted install (host killed mid-upload, BOOT pressed) must not
506
+ // poison the next one. Two leftovers can greet the next host: the dead
507
+ // transfer's receive loop may still be running and swallow whatever is sent
508
+ // as payload, and its `OTA ERR transfer-failed` line -- printed after the
509
+ // host vanished -- waits in the TinyUSB TX FIFO (kept while DTR is low) and
510
+ // is delivered the moment the port opens. So every attempt resyncs the
511
+ // console first, streams only after a READY for this size, and takes as its
512
+ // result only a reply that can belong to this transfer. A failed attempt is
513
+ // retried once after another resync.
514
+ async otaUpdate(d, source, { timeoutMs = 120000, stderr = () => {}, attempts = 2 } = {}) {
515
+ const data = Buffer.isBuffer(source) ? source : readFileSync(source)
516
+ const crc = crc32(data)
517
+ for (let attempt = 1; ; attempt++) {
518
+ try {
519
+ return await otaAttempt(d, data, crc, { timeoutMs, stderr })
520
+ } catch (error) {
521
+ // uploaded: the image went out and the board may be restarting into it;
522
+ // noApp: nothing answers the console. Neither is helped by a retry here.
523
+ if (error.uploaded || error.noApp || attempt >= attempts) throw error
524
+ stderr(` in-app install attempt ${attempt} failed (${error.message}); resyncing the console and retrying`)
525
+ }
492
526
  }
493
- return { ready, line, bytes: data.length, seconds: (Date.now() - startedAt) / 1000 }
494
527
  },
495
528
 
496
529
  async pullFile(d, source, destination, { timeoutMs = 300000 } = {}) {
@@ -516,6 +549,139 @@ export const geadev = {
516
549
  }
517
550
  }
518
551
 
552
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
553
+
554
+ // Brings the console to a state where the next line it reads is a command:
555
+ // ends any partial line (a failed ROM-downloader attempt leaves esptool's sync
556
+ // bytes without a newline, and the command appended to them is refused as
557
+ // line-too-long), drops whatever output was queued before the port opened, and
558
+ // waits for a PONG to a fresh ping. Firmware that echoes `nonce=` is matched
559
+ // exactly; older firmware's PONG carries none and any PONG after the drain is
560
+ // taken. A board that stays silent is most likely still inside an earlier
561
+ // OTA/PUSH receive loop that took the ping as payload: it gives up after a
562
+ // silence (~3 s on current firmware, ~10 s on older), so stay silent that long
563
+ // and ping again.
564
+ export async function resyncConsole(d, { timeoutMs = 35000, pingTimeoutMs = 2500, quietMs = 12000, stderr = () => {} } = {}) {
565
+ const deadline = Date.now() + timeoutMs
566
+ let waited = false
567
+ while (Date.now() < deadline) {
568
+ await d.writeRaw(Buffer.from('\n'))
569
+ await d.drainInput(150, 1500)
570
+ const nonce = randomBytes(4).toString('hex')
571
+ await d.writeLine(`GEADEV PING ${nonce}`)
572
+ let transferEnded = false
573
+ const pong = await readFrame(d, Math.min(pingTimeoutMs, Math.max(0, deadline - Date.now())), (frame) => {
574
+ if (transferEndPattern.test(frame)) transferEnded = true
575
+ if (!frame.startsWith('GEADEV:PONG')) return false
576
+ const echoed = parseKeyValues(frame).nonce
577
+ return echoed === undefined || echoed === nonce
578
+ })
579
+ if (pong) {
580
+ // A PONG to a ping swallowed earlier can trail this one; drop it.
581
+ await d.drainInput(100, 500)
582
+ return pong
583
+ }
584
+ if (Date.now() >= deadline) break
585
+ // The dead transfer gave up while we waited for the PONG: ping again now.
586
+ if (transferEnded) continue
587
+ if (!waited) stderr(' the board is still inside an interrupted transfer; waiting for it to give up...')
588
+ waited = true
589
+ // Send nothing: every byte restarts the dead transfer's silence timer. Its
590
+ // closing ERR line means the command loop is back.
591
+ await readFrame(d, Math.min(quietMs, Math.max(0, deadline - Date.now())), (frame) => transferEndPattern.test(frame))
592
+ await sleep(200)
593
+ }
594
+ const error = new Error('no running gea app answered GEADEV PING on USB')
595
+ error.noApp = true
596
+ throw error
597
+ }
598
+
599
+ // The closing line of a receive loop that gave up (OTA, PUSH, PUSH64).
600
+ const transferEndPattern = /^GEADEV:(?:OTA|PUSH|PUSH64) ERR\b/
601
+
602
+ // Reads lines until one whose GEADEV frame satisfies `match`; null on timeout.
603
+ async function readFrame(d, timeoutMs, match) {
604
+ const deadline = Date.now() + timeoutMs
605
+ while (true) {
606
+ const remaining = deadline - Date.now()
607
+ if (remaining <= 0) return null
608
+ const line = await d.readLine(remaining)
609
+ if (line === null) return null
610
+ if (d.trace) d.stderr(line)
611
+ const frame = geadevFragment(line)
612
+ if (match(frame)) return frame
613
+ }
614
+ }
615
+
616
+ // Whether an `OTA ERR` line can be this transfer's reply. transfer-failed and
617
+ // crc-mismatch only follow a payload, so before READY they are leftovers of an
618
+ // earlier transfer; after it, their want= must match this image when present.
619
+ function otaErrorIsOurs(frame, { size, crc, streamed }) {
620
+ const values = parseKeyValues(frame)
621
+ const kind = frame.slice('GEADEV:OTA ERR'.length).trim().split(/\s+/)[0] || ''
622
+ if (kind.startsWith('transfer-failed')) return streamed && (values.want === undefined || Number(values.want) === size)
623
+ if (kind.startsWith('crc-mismatch')) return streamed && (values.want === undefined || Number.parseInt(values.want, 16) === crc)
624
+ return true
625
+ }
626
+
627
+ async function otaAttempt(d, data, crc, { timeoutMs, stderr }) {
628
+ const size = data.length
629
+ await resyncConsole(d, { stderr })
630
+ await d.writeLine(`GEADEV OTA ${size} ${crc}`)
631
+ const readyDeadline = Date.now() + 15000
632
+ let ready = null
633
+ while (!ready) {
634
+ const frame = await readFrame(d, readyDeadline - Date.now(), (f) => f.startsWith('GEADEV:OTA ') || f.startsWith('GEADEV:ERR'))
635
+ if (frame === null) throw new Error('timed out waiting for OTA READY')
636
+ if (frame.startsWith('GEADEV:ERR')) throw new Error(frame)
637
+ if (frame.startsWith('GEADEV:OTA READY')) {
638
+ const bytes = parseKeyValues(frame).bytes
639
+ if (bytes === undefined || Number(bytes) === size) ready = frame
640
+ continue
641
+ }
642
+ if (frame.startsWith('GEADEV:OTA ERR')) {
643
+ if (otaErrorIsOurs(frame, { size, crc, streamed: false })) throw new Error(frame)
644
+ stderr(` ignoring a stale reply from an earlier transfer: ${frame}`)
645
+ }
646
+ }
647
+ const startedAt = Date.now()
648
+ await sleep(300)
649
+ const burst = 2048
650
+ for (let offset = 0; offset < size; offset += burst) {
651
+ await d.writeRaw(data.subarray(offset, Math.min(offset + burst, size)))
652
+ await sleep(4)
653
+ if (((offset / burst) | 0) % 128 === 0) stderr(` upload ${Math.floor((offset * 100) / size)}%`)
654
+ }
655
+ const doneDeadline = Date.now() + timeoutMs
656
+ while (true) {
657
+ let frame
658
+ try {
659
+ frame = await readFrame(d, doneDeadline - Date.now(), (f) => f.startsWith('GEADEV:OTA OK') || f.startsWith('GEADEV:OTA ERR'))
660
+ } catch (error) {
661
+ error.uploaded = true
662
+ throw error
663
+ }
664
+ if (frame === null) {
665
+ // The board restarts right after the reply, and firmware whose console
666
+ // drops output on a full TX FIFO can lose it; the caller decides from
667
+ // what boots.
668
+ const error = new Error('timed out waiting for OTA OK')
669
+ error.uploaded = true
670
+ throw error
671
+ }
672
+ if (frame.startsWith('GEADEV:OTA OK')) {
673
+ const values = parseKeyValues(frame)
674
+ const okCrc = values.crc === undefined ? crc : Number.parseInt(values.crc, 16)
675
+ if ((values.bytes === undefined || Number(values.bytes) === size) && okCrc === crc) {
676
+ return { ready, line: frame, bytes: size, seconds: (Date.now() - startedAt) / 1000 }
677
+ }
678
+ } else if (otaErrorIsOurs(frame, { size, crc, streamed: true })) {
679
+ throw new Error(frame)
680
+ }
681
+ stderr(` ignoring a stale reply from an earlier transfer: ${frame}`)
682
+ }
683
+ }
684
+
519
685
  async function waitFor(d, okPrefix, errPrefix, timeoutMs, what) {
520
686
  const deadline = Date.now() + timeoutMs
521
687
  while (true) {
@@ -1,14 +1,17 @@
1
1
  import { debugFps } from '../debug-fps.mjs'
2
2
  import { spawnSync } from 'node:child_process'
3
+ import { createHash } from 'node:crypto'
3
4
  import { appForNativeDebugger, resolveBuildConfig, writeBuildConfig } from '../build-config.mjs'
4
- import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
5
+ import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
5
6
  import path from 'node:path'
6
7
 
8
+ import { geastackHome } from '../boards/config.mjs'
7
9
  import { loadChipCatalogFromDir, writeCustomTarget } from '../boards/custom-target.mjs'
8
10
  import { CliError, ExitCode, fail } from '../errors.mjs'
9
11
  import { appCmakeMeta, appCmakeLdFragments, appTargetConfig, appTargetPaths } from '../manifest.mjs'
10
12
  import { quietSteps, runQuiet } from '../run.mjs'
11
13
  import { resolveAppCapabilities, withRendererFeatureDefines } from './capabilities.mjs'
14
+ import { prepareCapabilityDependencies } from './dependencies.mjs'
12
15
  import { activateEspIdf, idfPyCommand } from './idf-env.mjs'
13
16
  import { espIdfVersionForTarget } from './idf-version.mjs'
14
17
  import { Sdkconfig, prepareBuildLocalSdkconfig } from './sdkconfig.mjs'
@@ -17,7 +20,7 @@ import { listAppSources } from './source-set.mjs'
17
20
  import { writeFlashPlan } from './partitions.mjs'
18
21
  import { generateWifiConfig } from './wifi-config.mjs'
19
22
  import { hint, warn } from '../report.mjs'
20
- import { envPath } from '../env-path.mjs'
23
+ import { onPath } from '../toolchain.mjs'
21
24
 
22
25
  // The ESP-IDF build. Everything the old bash board script decided about a
23
26
  // build lives here: where the build directory is, what the app-local
@@ -41,6 +44,80 @@ export function esp32BuildDir(ctx, selection, appId, env = ctx.env || process.en
41
44
  return path.join(ctx.buildRoot, selection.target, 'app-builds', key)
42
45
  }
43
46
 
47
+ // Where CMake actually builds. Windows' toolchain still lives under MAX_PATH
48
+ // (260 characters): GCC cannot open the dependency file of an object nested
49
+ // a few components deep (esp-idf/mbedtls/.../tfpsacrypto.dir/...) once the
50
+ // build directory is an app's .gea/build/<target>/app-builds/<app>, which
51
+ // is already over 100 characters. So on Windows CMake builds in a short
52
+ // directory under the CLI's home (~\.geastack\build), named by a hash of the
53
+ // build directory it stands in for -- the same one on every rebuild, so
54
+ // builds stay incremental -- and the build directory is a junction to it
55
+ // (see linkEsp32BinaryDir), which keeps the firmware, logs and everything the
56
+ // flash, monitor and debugger steps read where they always were. A build
57
+ // root chosen with GEA_PROJECT_BUILD_ROOT is used as it is: whoever set it
58
+ // has already decided where builds live (and how long that path is). Other
59
+ // hosts always build in place.
60
+ export function esp32BinaryDir(buildDir, env = process.env, platform = process.platform) {
61
+ if (platform !== 'win32' || env.GEA_PROJECT_BUILD_ROOT) return buildDir
62
+ return path.win32.join(esp32ShortBuildRoot(env), createHash('sha256').update(windowsPathKey(buildDir)).digest('hex').slice(0, 16))
63
+ }
64
+
65
+ // Not under %LOCALAPPDATA%: a packaged (MSIX) app's writes there are
66
+ // redirected into its own private LocalCache, which both lengthens the path
67
+ // again and leaves the junction dangling for every process outside the
68
+ // package. The user profile itself is not redirected.
69
+ function esp32ShortBuildRoot(env) {
70
+ return path.win32.join(geastackHome(env), 'build')
71
+ }
72
+
73
+ // Windows paths compare without regard to case or separator spelling.
74
+ function windowsPathKey(file) {
75
+ return path.win32.resolve(file).toLowerCase()
76
+ }
77
+
78
+ function linkTarget(file) {
79
+ try {
80
+ return lstatSync(file).isSymbolicLink() ? readlinkSync(file) : null
81
+ } catch {
82
+ return null
83
+ }
84
+ }
85
+
86
+ // Makes buildDir a junction to binaryDir. An existing link to it is kept, so
87
+ // the build is incremental. Anything else at buildDir -- a build from before
88
+ // builds moved, or a link to another directory -- is replaced; its CMake
89
+ // cache names a different binary directory, so it could not be reused. When
90
+ // buildDir is missing (deleted to force a clean build), binaryDir starts
91
+ // empty as well, so deleting the build directory still means a clean build.
92
+ export function linkEsp32BinaryDir(buildDir, binaryDir, log = () => {}) {
93
+ if (binaryDir === buildDir) return
94
+ const current = linkTarget(buildDir)
95
+ if (current !== null && windowsPathKey(current) === windowsPathKey(binaryDir) && existsSync(binaryDir)) return
96
+ if (current !== null) {
97
+ unlinkSync(buildDir)
98
+ } else if (existsSync(buildDir)) {
99
+ log(`Replacing ${buildDir} with a link to ${binaryDir}`)
100
+ rmSync(buildDir, { recursive: true, force: true })
101
+ }
102
+ rmSync(binaryDir, { recursive: true, force: true })
103
+ mkdirSync(binaryDir, { recursive: true })
104
+ mkdirSync(path.dirname(buildDir), { recursive: true })
105
+ symlinkSync(binaryDir, buildDir, 'junction')
106
+ }
107
+
108
+ // The short directories the build directories under `dir` link to. Only
109
+ // links into the CLI's own short root count; a link a user made elsewhere is
110
+ // never followed into.
111
+ function linkedBinaryDirs(dir, env) {
112
+ const root = windowsPathKey(esp32ShortBuildRoot(env)) + path.win32.sep
113
+ const candidates = [dir, path.join(dir, 'default')]
114
+ const appBuilds = path.join(dir, 'app-builds')
115
+ if (existsSync(appBuilds) && !linkTarget(appBuilds)) {
116
+ for (const entry of readdirSync(appBuilds)) candidates.push(path.join(appBuilds, entry))
117
+ }
118
+ return candidates.map(linkTarget).filter((target) => target && windowsPathKey(target).startsWith(root))
119
+ }
120
+
44
121
  export function buildImages(buildDir) {
45
122
  return {
46
123
  app: path.join(buildDir, 'gea_embedded.bin'),
@@ -332,17 +409,30 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
332
409
  const resolvedBuild = resolveBuildConfig({ app: env.GEA_NATIVE_DEBUGGER === '1' ? appForNativeDebugger(app, 'esp32') : app, platform: 'esp32', board: selection.target, targetBase: selection.targetBase, targetsRoot: ctx.targetsRoot, env, capabilities: buildCapabilities })
333
410
  const idfTarget = selection.idfTarget || 'esp32s3'
334
411
  const buildDir = esp32BuildDir(ctx, selection, app?.id, env)
412
+ // Everything CMake is told about -- its binary directory and the files the
413
+ // CLI generates for it -- is spelled with the short path, so no object or
414
+ // dependency file is ever named through the long one.
415
+ const binaryDir = esp32BinaryDir(buildDir, env)
416
+ linkEsp32BinaryDir(buildDir, binaryDir, log)
417
+ if (binaryDir !== buildDir) log(`CMake builds in ${binaryDir}, linked from ${buildDir}`)
335
418
  // gea.targets.esp32.sdkconfig: the app's own Kconfig defaults, layered over
336
419
  // the board's. IDF reads a ';'-separated SDKCONFIG_DEFAULTS list in order, so
337
420
  // the app's file is last and wins wherever the two disagree.
338
421
  const appEsp32Config = app ? appTargetConfig(app, 'esp32') : null
339
422
  const appSdkconfigFile = appEsp32Config?.sdkconfig ? path.join(app.root, appEsp32Config.sdkconfig) : ''
340
- const { file: sdkconfigFile, defaultsFile, regenerated } = prepareBuildLocalSdkconfig(selection.targetDir, buildDir, appSdkconfigFile)
423
+ const { file: sdkconfigFile, defaultsFile, regenerated } = prepareBuildLocalSdkconfig(selection.targetDir, binaryDir, appSdkconfigFile)
341
424
  if (regenerated) log('sdkconfig defaults changed; the generated sdkconfig was rebuilt from them')
342
425
  log(`Using ESP32 target '${selection.target}' at ${selection.targetDir} (idf=${idfTarget} chip=${selection.esptoolChip || idfTarget} flash=${selection.flashSize})`)
343
426
 
344
427
  const childEnv = { ...env }
345
- const buildConfig = writeBuildConfig(buildDir, resolvedBuild)
428
+ for (const name of Object.keys(childEnv)) if (name.startsWith('GEA_EMBEDDED_CAPABILITY_')) delete childEnv[name]
429
+ if (resolvedBuild.settings.services?.wifi === 'disabled') {
430
+ if (capabilities.network) fail('services.wifi=disabled conflicts with the app network capabilities', ExitCode.usage)
431
+ capabilities.network = false
432
+ }
433
+ Object.assign(capabilities, resolvedBuild.capabilities)
434
+ const dependencyDirectory = prepareCapabilityDependencies(selection.targetDir, binaryDir, capabilities)
435
+ const buildConfig = writeBuildConfig(binaryDir, resolvedBuild, { capabilityDependencyDirectory: dependencyDirectory })
346
436
  const idfArgs = [`-DIDF_TARGET=${idfTarget}`, `-DGEA_BUILD_CONFIG_FILE=${cmakeValue(buildConfig.cmake)}`, `-DGEA_BUILD_CONFIG_JSON=${cmakeValue(buildConfig.json)}`, `-DGEA_BUILD_CONFIG_HASH=${buildConfig.hash}`]
347
437
  childEnv.GEA_BUILD_CONFIG_FILE = cmakeValue(buildConfig.cmake)
348
438
  childEnv.GEA_BUILD_CONFIG_JSON = cmakeValue(buildConfig.json)
@@ -352,7 +442,7 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
352
442
  if (selection.targetDefinition) {
353
443
  // The board header and target.cmake are generated here, once; CMake only
354
444
  // includes them.
355
- const outDir = path.join(buildDir, 'gea-custom-target')
445
+ const outDir = path.join(binaryDir, 'gea-custom-target')
356
446
  if (!ctx.chipsPackageDir) fail('@geastack/chips is not installed in this project; custom boards need its chip catalog.', ExitCode.missingDependency)
357
447
  const generated = writeCustomTarget({
358
448
  definitionPath: selection.targetDefinition,
@@ -447,13 +537,13 @@ function preparePartitions(app, config, buildDir, targetId) {
447
537
  // Runs before the partition table is read and before configure, because it
448
538
  // is what produces the files embedFiles and a partition's data refer to.
449
539
  runAppPrebuild(app, esp32Config, { dryRun, log })
450
- const partitions = preparePartitions(app, esp32Config, buildDir, selection.target)
540
+ const partitions = preparePartitions(app, esp32Config, binaryDir, selection.target)
451
541
  appPartitionCsv = partitions.csv
452
542
  const partitionPayloads = partitions.payloads
453
543
  const appNative = {
454
544
  GEA_EMBEDDED_APP_DEFINES: appDefines,
455
545
  GEA_EMBEDDED_APP_LDFRAGMENTS: appCmakeLdFragments(app),
456
- GEA_EMBEDDED_APP_COMPONENT_DIRS: appTargetPaths(app, 'esp32', 'componentDirs').join(';'),
546
+ GEA_EMBEDDED_APP_COMPONENT_DIRS: [...appTargetPaths(app, 'esp32', 'componentDirs'), dependencyDirectory].filter(Boolean).join(';'),
457
547
  // Component names the app's own native sources include headers from or
458
548
  // take PUBLIC compile definitions from. They land on the shared
459
549
  // gea_framework component's REQUIRES, which is transitive, so the app's
@@ -486,15 +576,9 @@ function preparePartitions(app, config, buildDir, targetId) {
486
576
  childEnv.GEA_EMBEDDED_APP = app.id
487
577
  childEnv.GEA_EMBEDDED_APP_META = cmakeValue(meta)
488
578
  for (const [name, value] of Object.entries(appNative)) if (value) childEnv[name] = cmakeValue(value)
489
- childEnv.GEA_EMBEDDED_CAPABILITY_NETWORK = capabilities.network ? '1' : '0'
490
- childEnv.GEA_EMBEDDED_CAPABILITY_BLE = capabilities.ble ? '1' : '0'
491
- childEnv.GEA_EMBEDDED_CAPABILITY_AUDIO = capabilities.audio ? '1' : '0'
492
- childEnv.GEA_EMBEDDED_CAPABILITY_CAMERA = capabilities.bindings.includes('camera') ? '1' : '0'
493
- childEnv.GEA_EMBEDDED_CAPABILITY_RTC = rtcUsed ? '1' : '0'
494
- childEnv.GEA_EMBEDDED_CAPABILITY_H264 = h264Used ? '1' : '0'
495
579
  if (bleOta) childEnv.GEA_EMBEDDED_BLE_OTA = '1'
496
580
  log(`App capabilities: network=${capabilities.network ? 1 : 0} ble=${capabilities.ble ? 1 : 0} audio=${capabilities.audio ? 1 : 0}`)
497
- generateWifiConfig(app.root, path.join(buildDir, 'apps', app.id, 'wifi_config.h'))
581
+ generateWifiConfig(app.root, path.join(binaryDir, 'apps', app.id, 'wifi_config.h'))
498
582
  }
499
583
 
500
584
  applySdkconfigPolicy(new Sdkconfig(sdkconfigFile, defaultsFile, appSdkconfigFile), {
@@ -511,16 +595,7 @@ function preparePartitions(app, config, buildDir, targetId) {
511
595
 
512
596
  const defaultsArg = [defaultsFile, appSdkconfigFile].filter(Boolean).join(';')
513
597
  const sourceSet = app ? listAppSources(app.root) : []
514
- return { buildDir, sdkconfigFile, defaultsFile, appSdkconfigFile, defaultsArg, idfArgs, childEnv, capabilities, sourceSet, images: buildImages(buildDir) }
515
- }
516
-
517
- // Windows executables carry an extension from PATHEXT, so probing for the bare
518
- // name finds nothing even when the tool is installed and on PATH -- which is
519
- // how an ESP-IDF install that ships ninja.exe still read as "no ninja".
520
- function executableNames(name, env) {
521
- if (process.platform !== 'win32') return [name]
522
- const extensions = String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
523
- return [name, ...extensions.map((extension) => name + extension)]
598
+ return { buildDir, binaryDir, sdkconfigFile, defaultsFile, appSdkconfigFile, defaultsArg, idfArgs, childEnv, capabilities, sourceSet, images: buildImages(buildDir) }
524
599
  }
525
600
 
526
601
  // A path handed to CMake on its command line, or through the environment
@@ -533,15 +608,9 @@ export function cmakeValue(value, platform = process.platform) {
533
608
  return platform === 'win32' ? String(value).replace(/\\/g, '/') : String(value)
534
609
  }
535
610
 
536
- function commandExists(name, env) {
537
- const dirs = envPath(env).split(path.delimiter).filter(Boolean)
538
- const names = executableNames(name, env)
539
- return dirs.some((dir) => names.some((candidate) => existsSync(path.join(dir, candidate))))
540
- }
541
-
542
611
  export function configureArguments(prepared, env) {
543
612
  const args = []
544
- if ((env.GEA_IDF_CCACHE || '1') !== '0' && commandExists('ccache', env)) args.push('--ccache')
613
+ if ((env.GEA_IDF_CCACHE || '1') !== '0' && onPath('ccache', env)) args.push('--ccache')
545
614
  // A CMake generator is immutable once a build directory has been
546
615
  // configured. Prefer Ninja for new builds (its no-op dependency traversal
547
616
  // is dramatically cheaper) while leaving existing Make builds untouched.
@@ -549,7 +618,7 @@ export function configureArguments(prepared, env) {
549
618
  // idf.py accepts only Ninja on Windows, so the probe must not decide there:
550
619
  // a false negative would pick a generator the build refuses outright.
551
620
  const windows = process.platform === 'win32'
552
- const generator = env.GEA_IDF_GENERATOR || (windows || commandExists('ninja', env) ? 'Ninja' : 'Unix Makefiles')
621
+ const generator = env.GEA_IDF_GENERATOR || (windows || onPath('ninja', env) ? 'Ninja' : 'Unix Makefiles')
553
622
  if (generator !== 'Ninja' && generator !== 'Unix Makefiles') {
554
623
  fail(`GEA_IDF_GENERATOR must be 'Ninja' or 'Unix Makefiles' (got '${generator}').`, ExitCode.usage)
555
624
  }
@@ -558,7 +627,7 @@ export function configureArguments(prepared, env) {
558
627
  }
559
628
  args.push('-G', generator)
560
629
  }
561
- args.push('-B', cmakeValue(prepared.buildDir), `-DSDKCONFIG=${cmakeValue(prepared.sdkconfigFile)}`, `-DSDKCONFIG_DEFAULTS=${cmakeValue(prepared.defaultsArg || prepared.defaultsFile)}`)
630
+ args.push('-B', cmakeValue(prepared.binaryDir || prepared.buildDir), `-DSDKCONFIG=${cmakeValue(prepared.sdkconfigFile)}`, `-DSDKCONFIG_DEFAULTS=${cmakeValue(prepared.defaultsArg || prepared.defaultsFile)}`)
562
631
  return args
563
632
  }
564
633
 
@@ -661,7 +730,7 @@ export async function buildEsp32Firmware({ ctx, selection, app = null, env = ctx
661
730
 
662
731
  detail(app ? `Building firmware for app '${app.id}' in ${prepared.buildDir}...` : 'Building firmware...')
663
732
  await ensureConfigured({ idf, prepared, env: buildEnv, dryRun, verbose, stdout, stderr })
664
- await runInTarget('cmake', ['--build', prepared.buildDir, '--parallel', buildJobs(buildEnv)], {
733
+ await runInTarget('cmake', ['--build', prepared.binaryDir, '--parallel', buildJobs(buildEnv)], {
665
734
  cwd: selection.targetDir,
666
735
  env: buildEnv,
667
736
  dryRun,
@@ -712,5 +781,6 @@ function buildSummaryLine(idf, selection, capabilities) {
712
781
  export function fullCleanEsp32({ ctx, selection, app = null, env = ctx.env || process.env, stdout = console.log }) {
713
782
  const dir = app ? esp32BuildDir(ctx, selection, app.id, env) : path.join(ctx.buildRoot, selection.target)
714
783
  stdout(`Removing build artifacts in ${dir}...`)
784
+ for (const binaryDir of linkedBinaryDirs(dir, env)) rmSync(binaryDir, { recursive: true, force: true })
715
785
  spawnSync('rm', ['-rf', dir], { stdio: 'inherit' })
716
786
  }
@@ -210,6 +210,10 @@ export function analyzeApp(ctx, app, { env = ctx.env || process.env } = {}) {
210
210
 
211
211
  export function resolveAppCapabilities(ctx, app, options = {}) {
212
212
  const analysis = analyzeApp(ctx, app, options)
213
+ return capabilitiesFromAnalysis(app, analysis)
214
+ }
215
+
216
+ export function capabilitiesFromAnalysis(app, analysis) {
213
217
  const bindings = new Set(analysis.bindings)
214
218
  const features = new Set(withNativeCssFeatures(app, analysis.features))
215
219
  const manifestBleOta = manifestRequestsBleOta(app.packageJson)
@@ -218,6 +222,8 @@ export function resolveAppCapabilities(ctx, app, options = {}) {
218
222
  ble: bindings.has('ble') || manifestBleOta,
219
223
  bleApi: bindings.has('ble'),
220
224
  audio: bindings.has('audio'),
225
+ camera: bindings.has('camera'),
226
+ aec: bindings.has('audio') && features.has('audio-capture') && features.has('audio-playback'),
221
227
  bindings: [...bindings].sort(),
222
228
  features: [...features].sort()
223
229
  }
@@ -0,0 +1,36 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
2
+ import path from 'node:path'
3
+
4
+ export function selectDependencies(catalog, capabilities) {
5
+ const dependencies = {}
6
+ for (const [name, entry] of Object.entries(catalog)) {
7
+ if (entry.when.some(capability => capabilities[capability] === true)) {
8
+ // This component aggregates SDKs used by the application, so their headers
9
+ // and compile requirements must propagate beyond the aggregate itself.
10
+ dependencies[name] = { ...entry.dependency, require: 'public' }
11
+ }
12
+ }
13
+ return dependencies
14
+ }
15
+
16
+ export function prepareCapabilityDependencies(targetDir, buildDir, capabilities) {
17
+ const file = path.join(targetDir, 'main', 'gea-dependencies.json')
18
+ if (!existsSync(file)) {
19
+ const manifest = path.join(targetDir, 'main', 'idf_component.yml')
20
+ if (existsSync(manifest) && readFileSync(manifest, 'utf8').includes('$GEA_EMBEDDED_CAPABILITY_')) {
21
+ throw new Error('This target uses legacy environment-based SDK selection. Update @geastack/targets together with @geastack/cli.')
22
+ }
23
+ return ''
24
+ }
25
+ const dependencies = selectDependencies(JSON.parse(readFileSync(file, 'utf8')), capabilities)
26
+ const directory = path.join(buildDir, 'gea_app_dependencies')
27
+ mkdirSync(directory, { recursive: true })
28
+ for (const [name, contents] of [
29
+ ['idf_component.yml', JSON.stringify({ dependencies }, null, 2) + '\n'],
30
+ ['CMakeLists.txt', 'idf_component_register()\n'],
31
+ ]) {
32
+ const destination = path.join(directory, name)
33
+ if (!existsSync(destination) || readFileSync(destination, 'utf8') !== contents) writeFileSync(destination, contents)
34
+ }
35
+ return directory
36
+ }
@@ -91,6 +91,10 @@ export async function runEsptoolOverUsb({ idf, selection, options, args, port =
91
91
  label: attempt === 1 ? `Flashing over USB on ${flashPort}` : `USB flash attempt ${attempt} on ${flashPort}`,
92
92
  logFile,
93
93
  appendLog: attempt > 1,
94
+ // The S31's USB port disappears as the board resets, and esptool exits 1
95
+ // from its teardown after a verified write. That is the expected end of a
96
+ // flash, so it must not read as a red failure with an error dump.
97
+ accept: () => flashCompleted(logFile, args, attemptLogOffset) ? 'the board left USB as it reset' : '',
94
98
  stdout,
95
99
  stderr
96
100
  })
@@ -105,8 +109,9 @@ export async function runEsptoolOverUsb({ idf, selection, options, args, port =
105
109
  // A completed write that only failed on esptool's own teardown is a
106
110
  // success: the images are on the board and it has been reset. Report it
107
111
  // as one, so the retry loop does not re-flash and re-reboot for minutes.
108
- if (flashCompleted(logFile, args, attemptLogOffset)) {
109
- warn(stderr, `esptool exited ${status} after resetting the board; the flash itself completed.`)
112
+ if (step.accepted || flashCompleted(logFile, args, attemptLogOffset)) {
113
+ // The spinner already said so; passthrough output showed esptool's error.
114
+ if (!step.accepted) warn(stderr, `esptool exited ${status} after resetting the board; the flash itself completed.`)
110
115
  if (step.quiet) stdout(flashSummary(logFile))
111
116
  return 0
112
117
  }
@@ -150,6 +150,11 @@ function parseKeyValueExport(output) {
150
150
  return values
151
151
  }
152
152
 
153
+ function withoutKey(object, key) {
154
+ const { [key]: _omitted, ...rest } = object
155
+ return rest
156
+ }
157
+
153
158
  const activationCache = new Map()
154
159
 
155
160
  // Returns the environment and command prefixes for one ESP-IDF install, or
@@ -158,7 +163,11 @@ const activationCache = new Map()
158
163
  // The tool export is cached per installation; the caller's environment is
159
164
  // layered on fresh every time so per-invocation settings (jobs, variants,
160
165
  // flash baud) are never frozen into a cached activation.
161
- export function activateEspIdf({ env = process.env, home = env.HOME || env.USERPROFILE || os.homedir(), log = () => {}, minVersion = '', defaultVersion = '' } = {}) {
166
+ export function activateEspIdf({ env: callerEnv = process.env, home = callerEnv.HOME || callerEnv.USERPROFILE || os.homedir(), log = () => {}, minVersion = '', defaultVersion = '' } = {}) {
167
+ // ESP-IDF's tools exit with "MSys/Mingw is not supported" when MSYSTEM is
168
+ // set, which Git Bash does. The native Windows toolchain runs fine from
169
+ // there, so the variable is left out of everything ESP-IDF sees.
170
+ const env = callerEnv.MSYSTEM ? withoutKey(callerEnv, 'MSYSTEM') : callerEnv
162
171
  const idfDir = findEspIdf(env, home, { minVersion, defaultVersion })
163
172
  if (!idfDir) return null
164
173
  // A venv exported by a different active checkout belongs to that checkout.
@@ -71,7 +71,8 @@ export async function fetchLatestEspIdfVersion({ fetchImpl = globalThis.fetch, t
71
71
  // 3. DEFAULT_ESP_IDF_VERSION.
72
72
  export async function resolveEspIdfVersion({ override, env = process.env, fetchLatest = fetchLatestEspIdfVersion, log = () => {} } = {}) {
73
73
  const requested = override || env.GEA_ESP_IDF_VERSION
74
- if (requested) return requested.startsWith('v') ? requested : `v${requested}`
74
+ // Only a bare version gains the tag's `v`; a branch (`master`) is cloned as named.
75
+ if (requested) return /^\d/.test(requested) ? `v${requested}` : requested
75
76
  const latest = await fetchLatest({ log })
76
77
  return latest || DEFAULT_ESP_IDF_VERSION
77
78
  }
@@ -14,7 +14,9 @@ export function nativeCssSourceNeedsSupport(text) {
14
14
  if (/#\s*include\s+(?![<"])[A-Za-z_]/.test(text)) return true
15
15
  for (const match of text.matchAll(/#\s*include\s*[<"]([^>"\n]+)[>"]/g)) {
16
16
  const header = match[1].replaceAll('\\', '/')
17
- if (header.endsWith('ui/tree_inspection.h')) continue
17
+ // Refresh tracing only reads/writes diagnostic stage atomics; it cannot
18
+ // construct nodes or change CSS, unlike the mutable UI headers below.
19
+ if (header.endsWith('ui/tree_inspection.h') || header.endsWith('ui/refresh_trace.h')) continue
18
20
  if (header.startsWith('css/') || header.startsWith('ui/') || privateUiHeader.test(header)) return true
19
21
  }
20
22
  return /\b(?:AnimationEngine|DeclarativeAnimations|ComputedStyle|StyleSheet|CssCompiledValue|CssDeclarationId|NodeText|NodeType|NodeClassList|ImageElement|InputElement|VirtualKeyboard)\b|\bProperty\s*::|(?:\.|->)\s*(?:style|cssText)\b|\b(?:setClassName|classList|setProperty|applyTransformComponentsFast|applyTransformSlotsFast|setDevicePixelRatio|setViewportMetrics|gea_style_set_device_pixel_ratio|gea_style_set_viewport_metrics)\s*\(/.test(text)