@geastack/cli 0.1.52 → 0.1.53

package/src/device/wifi.mjs

@@ -0,0 +1,190 @@
+import { createReadStream, statSync } from 'node:fs'
+import http from 'node:http'
+import net from 'node:net'
+
+import { decodeRgb565Raw } from './image.mjs'
+
+// The cable-free transport. Two services on the board:
+//   TCP 8081 -- diagnostics stream, framed [channel, type, len_lo, len_hi] + payload;
+//               channel 1 is the console/ESP_LOG stream (8 KiB ring replayed on connect).
+//   HTTP 8080 -- the OTA server: POST /ota, /ota/erase, GET /ota/status,
+//               GET /screenshot (rgb565-raw-v1 with X-Gea-* geometry headers),
+//               POST /display/hbm.
+
+export const diagnosticsPort = 8081
+export const otaPort = 8080
+const channelLog = 1
+const headerBytes = 4
+
+export function otaBaseUrl(host) {
+  const text = String(host)
+  if (/^https?:\/\//.test(text)) return text.replace(/\/$/, '')
+  if (text.includes(':')) return `http://${text}`
+  return `http://${text}:${otaPort}`
+}
+
+function enableKeepalive(socket) {
+  // A board that reboots never closes the connection; it just stops
+  // existing. Keepalive probes turn that into an error instead of a hang.
+  socket.setKeepAlive(true, 5000)
+}
+
+// Streams channel-1 payloads to `write` until the board goes away. Resolves
+// { connected } so a follow loop can tell "rebooted mid-stream" apart from
+// "nothing is listening".
+export function streamLogsOnce({ host, port = diagnosticsPort, timeoutMs = 10000, write, onConnect }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host, port })
+    let connected = false
+    let buffer = Buffer.alloc(0)
+    socket.setTimeout(timeoutMs)
+    socket.on('timeout', () => {
+      if (!connected) {
+        socket.destroy()
+        const error = new Error(`Timed out connecting to ${host}:${port}.`)
+        error.code = 'ETIMEDOUT'
+        reject(error)
+      }
+    })
+    socket.on('connect', () => {
+      connected = true
+      socket.setTimeout(0)
+      enableKeepalive(socket)
+      if (onConnect) onConnect()
+    })
+    socket.on('data', (chunk) => {
+      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk
+      let offset = 0
+      while (buffer.length - offset >= headerBytes) {
+        const channel = buffer[offset]
+        const payloadLength = buffer[offset + 2] | (buffer[offset + 3] << 8)
+        const frameLength = headerBytes + payloadLength
+        if (buffer.length - offset < frameLength) break
+        if (channel === channelLog && payloadLength > 0) write(buffer.subarray(offset + headerBytes, offset + frameLength))
+        offset += frameLength
+      }
+      buffer = offset ? buffer.subarray(offset) : buffer
+    })
+    socket.on('error', (error) => {
+      error.connected = connected
+      reject(error)
+    })
+    socket.on('close', () => resolve({ connected }))
+  })
+}
+
+const transientErrors = new Set(['ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'EHOSTDOWN'])
+
+export async function tailLogs({ host, port = diagnosticsPort, follow = false, timeoutMs = 10000, write, stderr, signal }) {
+  let connectedBefore = false
+  let firstAttempt = true
+  while (true) {
+    let connected = false
+    try {
+      const result = await streamLogsOnce({ host, port, timeoutMs, write, onConnect: () => { connected = true } })
+      connected = result.connected
+    } catch (error) {
+      connected = error.connected || connected
+      if (error.code === 'ECONNREFUSED' && !connected && firstAttempt) {
+        throw new Error(
+          `${host}:${port} refused the connection. The board is reachable but its firmware has no diagnostics server -- rebuild the target with GEA_EMBEDDED_DIAGNOSTICS_ENABLED=1.`
+        )
+      }
+      if (!transientErrors.has(error.code)) throw error
+      if (!connected && !follow) throw new Error(`Could not reach ${host}:${port}: ${error.message}`)
+    }
+    firstAttempt = false
+    if (!follow || signal?.aborted) return
+    if (connected) {
+      stderr(`-- reconnecting to ${host}:${port} --`)
+      connectedBefore = true
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+    if (signal?.aborted) return
+  }
+}
+
+function httpRequest(url, { method = 'GET', body = null, headers = {}, timeoutMs = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const request = http.request(url, { method, headers, timeout: timeoutMs }, (response) => {
+      const chunks = []
+      response.on('data', (chunk) => chunks.push(chunk))
+      response.on('end', () => resolve({ status: response.statusCode, headers: response.headers, body: Buffer.concat(chunks) }))
+      response.on('error', reject)
+    })
+    request.on('timeout', () => request.destroy(new Error(`Timed out after ${timeoutMs / 1000}s waiting for ${url}`)))
+    request.on('error', (error) => reject(new Error(`Could not reach ${url}: ${error.message}`)))
+    if (body && typeof body.pipe === 'function') body.pipe(request)
+    else request.end(body || undefined)
+  })
+}
+
+export async function fetchScreenshot({ host, port = otaPort, timeoutMs = 30000 }) {
+  const url = `http://${host}:${port}/screenshot`
+  const response = await httpRequest(url, { timeoutMs })
+  if (response.status !== 200) throw new Error(`${url} returned HTTP ${response.status}`)
+  const width = Number(response.headers['x-gea-width'] || 0)
+  const height = Number(response.headers['x-gea-height'] || 0)
+  const encoding = response.headers['x-gea-encoding'] || ''
+  const app = response.headers['x-gea-app'] || ''
+  if (encoding !== 'rgb565-raw-v1') throw new Error(`Unexpected screenshot encoding '${encoding}' (expected rgb565-raw-v1)`)
+  if (width <= 0 || height <= 0) throw new Error(`Board reported an unusable size: ${width}x${height}`)
+  return { width, height, app, rgb: decodeRgb565Raw(response.body, width * height) }
+}
+
+export async function otaStatus(host) {
+  const response = await httpRequest(`${otaBaseUrl(host)}/ota/status`, { timeoutMs: 5000 })
+  if (response.status !== 200) throw new Error(`OTA status returned HTTP ${response.status}`)
+  return JSON.parse(response.body.toString('utf8'))
+}
+
+export async function otaUpload({ host, image, slot = '', boot = false, reboot = false, timeoutMs = 600000, stdout }) {
+  const query = slot ? `?slot=${encodeURIComponent(slot)}&boot=${boot ? 1 : 0}&reboot=${reboot ? 1 : 0}` : ''
+  const url = `${otaBaseUrl(host)}/ota${query}`
+  const size = statSync(image).size
+  const startedAt = Date.now()
+  const response = await httpRequest(url, {
+    method: 'POST',
+    body: createReadStream(image),
+    headers: { 'Content-Type': 'application/octet-stream', 'Content-Length': String(size) },
+    timeoutMs
+  })
+  const seconds = (Date.now() - startedAt) / 1000
+  if (response.status !== 200) {
+    throw new Error(`OTA upload to ${url} failed with HTTP ${response.status}: ${response.body.toString('utf8').trim()}`)
+  }
+  const text = response.body.toString('utf8').trim()
+  if (text) stdout(text)
+  stdout(`WiFi OTA transfer: ${size} bytes in ${seconds.toFixed(3)}s (${Math.round(size / Math.max(seconds, 0.001))} bytes/s)`)
+  return { size, seconds }
+}
+
+export async function otaErase({ host, slot }) {
+  const url = `${otaBaseUrl(host)}/ota/erase?slot=${encodeURIComponent(slot)}`
+  const response = await httpRequest(url, { method: 'POST', timeoutMs: 120000 })
+  if (response.status !== 200) throw new Error(`Erase via ${url} failed with HTTP ${response.status}`)
+  return response.body.toString('utf8').trim()
+}
+
+export async function setHighBrightnessMode({ host, enabled }) {
+  const url = `${otaBaseUrl(host)}/display/hbm?on=${enabled ? 1 : 0}`
+  const response = await httpRequest(url, { method: 'POST', timeoutMs: 10000 })
+  if (response.status === 501) throw new Error('This board has no high-brightness mode.')
+  if (response.status !== 200) throw new Error(`${url} returned HTTP ${response.status}`)
+  return JSON.parse(response.body.toString('utf8'))
+}
+
+export function waitForOtaServer({ host, timeoutMs = 120000, pollMs = 2000 }) {
+  const deadline = Date.now() + timeoutMs
+  return new Promise((resolve, reject) => {
+    const attempt = async () => {
+      try {
+        resolve(await otaStatus(host))
+      } catch (error) {
+        if (Date.now() >= deadline) reject(new Error(`Board at ${host} did not come back within ${timeoutMs / 1000}s: ${error.message}`))
+        else setTimeout(attempt, pollMs)
+      }
+    }
+    attempt()
+  })
+}

package/src/esp32/build.mjs

@@ -0,0 +1,321 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+import { loadChipCatalogFromDir, writeCustomTarget } from '../boards/custom-target.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { appCmakeMeta } from '../manifest.mjs'
+import { formatCommand } from '../run.mjs'
+import { resolveAppCapabilities } from './capabilities.mjs'
+import { activateEspIdf, idfPyCommand } from './idf-env.mjs'
+import { Sdkconfig, prepareBuildLocalSdkconfig } from './sdkconfig.mjs'
+import { generateWifiConfig } from './wifi-config.mjs'
+
+// The ESP-IDF build. Everything the old bash board script decided about a
+// build lives here: where the build directory is, what the app-local
+// sdkconfig must say, which capabilities the firmware links, and when a
+// reconfigure is actually needed.
+
+function safePathFragment(value) {
+  return String(value).replace(/[^A-Za-z0-9_.-]/g, '_')
+}
+
+export function esp32BuildDir(ctx, selection, appId, env = ctx.env || process.env) {
+  if (!appId) return path.join(ctx.buildRoot, selection.target, 'default')
+  let key = safePathFragment(appId)
+  const variant = env.GEA_IDF_BUILD_VARIANT || ''
+  if (variant) {
+    if (!/^[A-Za-z0-9._-]+$/.test(variant)) {
+      fail("GEA_IDF_BUILD_VARIANT may contain only letters, digits, '.', '_' and '-'.", ExitCode.usage)
+    }
+    key = `${key}__variant-${variant}`
+  }
+  return path.join(ctx.buildRoot, selection.target, 'app-builds', key)
+}
+
+export function buildImages(buildDir) {
+  return {
+    app: path.join(buildDir, 'gea_embedded.bin'),
+    bootloader: path.join(buildDir, 'bootloader', 'bootloader.bin'),
+    partitionTable: path.join(buildDir, 'partition_table', 'partition-table.bin'),
+    otaData: path.join(buildDir, 'ota_data_initial.bin')
+  }
+}
+
+export function requireEspIdf(env, log) {
+  let idf
+  try {
+    idf = activateEspIdf({ env, log })
+  } catch (error) {
+    fail(error.message, ExitCode.missingDependency)
+  }
+  if (!idf) {
+    fail('ESP-IDF was not found. Install it and set IDF_PATH (or place it under ~/esp or ~/esp32).', ExitCode.missingDependency)
+  }
+  return idf
+}
+
+// The per-app sdkconfig policy: development logging, the board's stack
+// sizes, the S3 instruction cache and the BLE host exactly as the app needs.
+export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities, bleOta }) {
+  const set = (key, value) => sdkconfig.set(key, value)
+  const unset = (key) => sdkconfig.unset(key)
+
+  set('CONFIG_ESP_MAIN_TASK_STACK_SIZE', String(selection.mainTaskStackSize || 32768))
+  set('CONFIG_ESP_IPC_TASK_STACK_SIZE', String(selection.ipcTaskStackSize || 16384))
+  set('CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY', 'y')
+  set('CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL', '0')
+
+  // The S3's default 16 KB instruction cache is too small for a frame's code
+  // working set; 32 KB cut a whole frame ~35% for 16 KB of internal SRAM.
+  // Cache config lives in the generated (sticky) sdkconfig, so defaults alone
+  // would never reach an existing build directory.
+  if ((selection.idfTarget || 'esp32s3') === 'esp32s3') {
+    unset('CONFIG_ESP32S3_INSTRUCTION_CACHE_16KB')
+    set('CONFIG_ESP32S3_INSTRUCTION_CACHE_32KB', 'y')
+  }
+
+  unset('CONFIG_GEA_EMBEDDED_PRODUCTION_LOCKDOWN')
+  for (const level of ['NONE', 'ERROR', 'WARN', 'DEBUG', 'VERBOSE']) unset(`CONFIG_LOG_DEFAULT_LEVEL_${level}`)
+  set('CONFIG_LOG_DEFAULT_LEVEL_INFO', 'y')
+  set('CONFIG_LOG_DEFAULT_LEVEL', '3')
+  set('CONFIG_LOG_MAXIMUM_EQUALS_DEFAULT', 'y')
+  unset('CONFIG_LOG_MAXIMUM_LEVEL_DEBUG')
+  unset('CONFIG_LOG_MAXIMUM_LEVEL_VERBOSE')
+  set('CONFIG_LOG_MAXIMUM_LEVEL', '3')
+
+  // The M5StickC S3's OTA partitions are small and the binary sits at the
+  // ceiling; assertion strings push it over. Boards that already disable or
+  // silence assertions in their defaults keep that choice.
+  if (selection.boardName === 'sticks3' || sdkconfig.defaultIsSet('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE')) {
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE')
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE', 'y')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL', '0')
+  } else if (sdkconfig.defaultIsSet('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT')) {
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE')
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT', 'y')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL', '1')
+  } else {
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE')
+    unset('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE', 'y')
+    set('CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL', '2')
+  }
+
+  for (const level of ['NONE', 'ERROR', 'WARN', 'DEBUG', 'VERBOSE']) unset(`CONFIG_BOOTLOADER_LOG_LEVEL_${level}`)
+  set('CONFIG_BOOTLOADER_LOG_LEVEL_INFO', 'y')
+  set('CONFIG_BOOTLOADER_LOG_LEVEL', '3')
+
+  // taurus-display OTAs into hardware provisioned with taurus-pedal's legacy
+  // partition table; its image must stay byte-compatible with the field.
+  if (app?.id === 'taurus-display') {
+    set('CONFIG_PARTITION_TABLE_CUSTOM_FILENAME', '"partitions-taurus-display.csv"')
+  }
+
+  if (!app) return sdkconfig
+  if (capabilities.ble) {
+    set('CONFIG_BT_ENABLED', 'y')
+    unset('CONFIG_BT_BLUEDROID_ENABLED')
+    set('CONFIG_BT_NIMBLE_ENABLED', 'y')
+    set('CONFIG_BT_NIMBLE_MEM_ALLOC_MODE_EXTERNAL', 'y')
+    set('CONFIG_BT_NIMBLE_ROLE_BROADCASTER', 'y')
+    set('CONFIG_BT_NIMBLE_ROLE_PERIPHERAL', 'y')
+    if (bleOta && !capabilities.bleApi) {
+      set('CONFIG_BT_NIMBLE_MAX_CONNECTIONS', '1')
+      unset('CONFIG_BT_NIMBLE_ROLE_CENTRAL')
+      unset('CONFIG_BT_NIMBLE_ROLE_OBSERVER')
+    } else {
+      // Apps using the BLE API inherit the board policy (the amoled 2.06 uses
+      // four links plus central/observer for HID-host and MIDI roles).
+      set('CONFIG_BT_NIMBLE_MAX_CONNECTIONS', sdkconfig.defaultValue('CONFIG_BT_NIMBLE_MAX_CONNECTIONS') || '1')
+      if (sdkconfig.defaultIsSet('CONFIG_BT_NIMBLE_ROLE_CENTRAL')) set('CONFIG_BT_NIMBLE_ROLE_CENTRAL', 'y')
+      if (sdkconfig.defaultIsSet('CONFIG_BT_NIMBLE_ROLE_OBSERVER')) set('CONFIG_BT_NIMBLE_ROLE_OBSERVER', 'y')
+    }
+  } else if (sdkconfig.has(/^(CONFIG_BT_ENABLED=|# CONFIG_BT_ENABLED is not set)/m)) {
+    // A minimal no-BLE build excludes the whole bt component, so its Kconfig
+    // symbols do not exist; re-adding an "is not set" line there makes
+    // Kconfig delete it and invalidates CMake on every invocation.
+    unset('CONFIG_BT_ENABLED')
+  }
+  return sdkconfig
+}
+
+// Resolves every input of an ESP32 build without running it: build dir,
+// sdkconfig, generated headers, cache arguments and the child environment.
+export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env || process.env, log = () => {}, bleOta = false }) {
+  if (!selection.targetDir || !existsSync(path.join(selection.targetDir, 'CMakeLists.txt'))) {
+    fail(`ESP32 target '${selection.target}' has no project directory (${selection.targetDir || 'unset'}). Is @geastack/targets installed?`, ExitCode.missingDependency)
+  }
+  const idfTarget = selection.idfTarget || 'esp32s3'
+  const buildDir = esp32BuildDir(ctx, selection, app?.id, env)
+  const { file: sdkconfigFile, defaultsFile } = prepareBuildLocalSdkconfig(selection.targetDir, buildDir)
+  log(`Using ESP32 target '${selection.target}' at ${selection.targetDir} (idf=${idfTarget} chip=${selection.esptoolChip || idfTarget} flash=${selection.flashSize})`)
+
+  const childEnv = { ...env }
+  const idfArgs = [`-DIDF_TARGET=${idfTarget}`, `-DGEA_APPS_ROOT=${ctx.projectRoot}`]
+  if (selection.targetDefinition) {
+    // The board header and target.cmake are generated here, once; CMake only
+    // includes them.
+    const outDir = path.join(buildDir, 'gea-custom-target')
+    if (!ctx.chipsPackageDir) fail('@geastack/chips is not installed in this project; custom boards need its chip catalog.', ExitCode.missingDependency)
+    const generated = writeCustomTarget({ definitionPath: selection.targetDefinition, outDir, catalog: loadChipCatalogFromDir(ctx.chipsPackageDir) })
+    idfArgs.push(`-DGEA_BOARD_DEFINITION=${selection.targetDefinition}`, `-DGEA_CUSTOM_TARGET_DIR=${outDir}`)
+    childEnv.GEA_BOARD_DEFINITION = selection.targetDefinition
+    childEnv.GEA_CUSTOM_TARGET_DIR = outDir
+    log(`Generated custom board files in ${outDir} (${path.basename(generated.headerPath)}, ${path.basename(generated.cmakePath)})`)
+  }
+
+  let capabilities = { network: false, ble: false, bleApi: false, audio: false, bindings: [], features: [] }
+  if (app) {
+    capabilities = resolveAppCapabilities(ctx, app, { env })
+    if (bleOta) capabilities.ble = true
+    const meta = appCmakeMeta(ctx, app)
+    idfArgs.push(`-DGEA_EMBEDDED_APP=${app.id}`, `-DGEA_EMBEDDED_APP_META=${meta}`)
+    idfArgs.push(
+      `-DGEA_EMBEDDED_CAPABILITY_NETWORK=${capabilities.network ? 1 : 0}`,
+      `-DGEA_EMBEDDED_CAPABILITY_BLE=${capabilities.ble ? 1 : 0}`,
+      `-DGEA_EMBEDDED_CAPABILITY_AUDIO=${capabilities.audio ? 1 : 0}`
+    )
+    // IDF's MINIMAL_BUILD component-requirements pass runs before normal
+    // CMake cache propagation; environment values stay visible there, so
+    // conditional components such as bt enter the dependency graph.
+    childEnv.GEA_EMBEDDED_APP = app.id
+    childEnv.GEA_EMBEDDED_APP_META = meta
+    childEnv.GEA_EMBEDDED_CAPABILITY_NETWORK = capabilities.network ? '1' : '0'
+    childEnv.GEA_EMBEDDED_CAPABILITY_BLE = capabilities.ble ? '1' : '0'
+    childEnv.GEA_EMBEDDED_CAPABILITY_AUDIO = capabilities.audio ? '1' : '0'
+    if (bleOta) childEnv.GEA_EMBEDDED_BLE_OTA = '1'
+    log(`App capabilities: network=${capabilities.network ? 1 : 0} ble=${capabilities.ble ? 1 : 0} audio=${capabilities.audio ? 1 : 0}`)
+    generateWifiConfig(app.root, path.join(buildDir, 'apps', app.id, 'wifi_config.h'))
+  }
+
+  applySdkconfigPolicy(new Sdkconfig(sdkconfigFile, defaultsFile), { selection, app, capabilities, bleOta }).save()
+
+  return { buildDir, sdkconfigFile, defaultsFile, idfArgs, childEnv, capabilities, images: buildImages(buildDir) }
+}
+
+function commandExists(name, env) {
+  const dirs = String(env.PATH || '').split(path.delimiter).filter(Boolean)
+  return dirs.some((dir) => existsSync(path.join(dir, name)))
+}
+
+export function configureArguments(prepared, env) {
+  const args = []
+  if ((env.GEA_IDF_CCACHE || '1') !== '0' && commandExists('ccache', env)) args.push('--ccache')
+  // A CMake generator is immutable once a build directory has been
+  // configured. Prefer Ninja for new builds (its no-op dependency traversal
+  // is dramatically cheaper) while leaving existing Make builds untouched.
+  if (!existsSync(path.join(prepared.buildDir, 'CMakeCache.txt'))) {
+    const generator = env.GEA_IDF_GENERATOR || (commandExists('ninja', env) ? 'Ninja' : 'Unix Makefiles')
+    if (generator !== 'Ninja' && generator !== 'Unix Makefiles') {
+      fail(`GEA_IDF_GENERATOR must be 'Ninja' or 'Unix Makefiles' (got '${generator}').`, ExitCode.usage)
+    }
+    args.push('-G', generator)
+  }
+  args.push('-B', prepared.buildDir, `-DSDKCONFIG=${prepared.sdkconfigFile}`, `-DSDKCONFIG_DEFAULTS=${prepared.defaultsFile}`)
+  return args
+}
+
+function runInTarget(command, args, { cwd, env, dryRun, stdout, failureCode = ExitCode.buildFailed }) {
+  if (dryRun) {
+    stdout(formatCommand([command, ...args]))
+    return
+  }
+  const result = spawnSync(command, args, { cwd, env, stdio: 'inherit' })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new CliError(`ERROR: Command failed (${result.status ?? 1}): ${formatCommand([command, ...args])}`, failureCode)
+}
+
+// App capability flags are CMake cache entries. Reconfigure only when those
+// inputs change; ordinary source/CMake dependency changes remain the build
+// system's responsibility. This retains Ninja's sub-second no-op.
+export function ensureConfigured({ idf, prepared, env, dryRun = false, stdout }) {
+  const signatureFile = path.join(prepared.buildDir, '.gea-configure-args')
+  const signature = [`-DSDKCONFIG=${prepared.sdkconfigFile}`, `-DSDKCONFIG_DEFAULTS=${prepared.defaultsFile}`, ...prepared.idfArgs].join('\n') + '\n'
+  if (existsSync(path.join(prepared.buildDir, 'CMakeCache.txt')) && existsSync(signatureFile) && readFileSync(signatureFile, 'utf8') === signature) {
+    return false
+  }
+  const { command, args } = idfPyCommand(idf, [...configureArguments(prepared, env), ...prepared.idfArgs, 'reconfigure'])
+  runInTarget(command, args, { cwd: prepared.targetDir, env, dryRun, stdout })
+  if (!dryRun) {
+    mkdirSync(prepared.buildDir, { recursive: true })
+    const tmp = `${signatureFile}.tmp.${process.pid}`
+    writeFileSync(tmp, signature)
+    renameSync(tmp, signatureFile)
+  }
+  return true
+}
+
+export function buildJobs(env) {
+  const jobs = env.GEA_IDF_JOBS || '8'
+  if (!/^[1-9]\d*$/.test(jobs)) fail(`GEA_IDF_JOBS must be a positive integer (got '${jobs}').`, ExitCode.usage)
+  return jobs
+}
+
+// Opt-in workspace-wide serialization for benchmark-grade builds
+// (GEA_SERIALIZE_HEAVY_BUILDS=1). Concurrent builds are the normal workflow;
+// the lock only exists so a measurement is not taken beside another compile.
+export function acquireHeavyBuildLock({ ctx, env, label, stderr }) {
+  if (env.GEA_SERIALIZE_HEAVY_BUILDS !== '1') return () => {}
+  const lockPath = env.GEA_HEAVY_BUILD_LOCK_PATH || path.join(ctx.buildRoot, '.heavy-build.lock')
+  mkdirSync(path.dirname(lockPath), { recursive: true })
+  const contents = `pid=${process.pid}\nkind=esp32\nlabel=${label}\nstarted_at=${new Date().toISOString()}\n`
+  for (;;) {
+    try {
+      writeFileSync(lockPath, contents, { flag: 'wx', mode: 0o600 })
+      break
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error
+      const owner = readFileSync(lockPath, 'utf8')
+      const pid = Number(owner.match(/^pid=(\d+)$/m)?.[1])
+      let live = false
+      try {
+        process.kill(pid, 0)
+        live = Number.isFinite(pid)
+      } catch {
+        live = false
+      }
+      if (live) {
+        stderr(`Another heavyweight build is already using this workspace:\n${owner.trim()}\n(lock: ${lockPath})`)
+        fail('Heavy-build lock is held; retry when that build finishes or unset GEA_SERIALIZE_HEAVY_BUILDS.', ExitCode.buildFailed)
+      }
+      unlinkSync(lockPath)
+    }
+  }
+  return () => {
+    try {
+      if (readFileSync(lockPath, 'utf8') === contents) unlinkSync(lockPath)
+    } catch {
+      // already gone
+    }
+  }
+}
+
+export function buildEsp32Firmware({ ctx, selection, app = null, env = ctx.env || process.env, bleOta = false, dryRun = false, stdout = console.log, stderr = console.error, configureOnly = false }) {
+  const idf = requireEspIdf(env, stdout)
+  const prepared = prepareEsp32Build({ ctx, selection, app, env: idf.env, log: stdout, bleOta })
+  prepared.targetDir = selection.targetDir
+  const buildEnv = { ...prepared.childEnv }
+  const release = acquireHeavyBuildLock({ ctx, env: buildEnv, label: app ? `${selection.target} app=${app.id}` : selection.target, stderr })
+  try {
+    if (configureOnly) {
+      stdout(`Configuring target ${selection.idfTarget || 'esp32s3'}...`)
+      ensureConfigured({ idf, prepared, env: buildEnv, dryRun, stdout })
+      return prepared
+    }
+    stdout(app ? `Building firmware for app '${app.id}' in ${prepared.buildDir}...` : 'Building firmware...')
+    ensureConfigured({ idf, prepared, env: buildEnv, dryRun, stdout })
+    runInTarget('cmake', ['--build', prepared.buildDir, '--parallel', buildJobs(buildEnv)], { cwd: selection.targetDir, env: buildEnv, dryRun, stdout })
+  } finally {
+    release()
+  }
+  return prepared
+}
+
+export function fullCleanEsp32({ ctx, selection, app = null, env = ctx.env || process.env, stdout = console.log }) {
+  const dir = app ? esp32BuildDir(ctx, selection, app.id, env) : path.join(ctx.buildRoot, selection.target)
+  stdout(`Removing build artifacts in ${dir}...`)
+  spawnSync('rm', ['-rf', dir], { stdio: 'inherit' })
+}

package/src/esp32/capabilities.mjs

@@ -0,0 +1,54 @@
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+
+import { ExitCode, fail } from '../errors.mjs'
+import { exists } from '../fs-utils.mjs'
+
+// What the firmware must link for this app. The compiler analyses the entry
+// (with the gea plugin) and reports the host bindings the program reaches;
+// a network stack, the BLE host and the audio pipeline are only built when
+// something actually uses them.
+const networkBindings = ['wifi', 'fetch', 'http', 'websocket', 'rtc']
+
+export function parseAnalysis(output) {
+  const bindings = output.match(/^bindings=(.*)$/m)?.[1]?.split(';').filter(Boolean) ?? []
+  const features = output.match(/^features=(.*)$/m)?.[1]?.split(';').filter(Boolean) ?? []
+  return { bindings, features }
+}
+
+export function manifestRequestsBleOta(packageJson) {
+  return packageJson?.gea?.ota?.ble === true
+}
+
+export function analyzeApp(ctx, app, { env = ctx.env || process.env } = {}) {
+  const compiler = path.join(ctx.compilerPackageDir || '', 'dist', 'cli.js')
+  const plugin = path.join(ctx.pluginPackageDir || '', 'dist', 'index.js')
+  if (!ctx.compilerPackageDir || !exists(compiler)) {
+    fail(`@geastack/compiler is not installed in this project (expected ${compiler}).`, ExitCode.missingDependency)
+  }
+  if (!ctx.pluginPackageDir || !exists(plugin)) {
+    fail(`@geastack/geatsc-plugin-gea is not installed in this project (expected ${plugin}).`, ExitCode.missingDependency)
+  }
+  const output = execFileSync(process.execPath, [compiler, 'analyze', path.join(app.root, app.entry), '--plugin', plugin], {
+    cwd: ctx.compilerPackageDir,
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'inherit']
+  })
+  return parseAnalysis(output)
+}
+
+export function resolveAppCapabilities(ctx, app, options = {}) {
+  const analysis = analyzeApp(ctx, app, options)
+  const bindings = new Set(analysis.bindings)
+  const features = new Set(analysis.features)
+  const manifestBleOta = manifestRequestsBleOta(app.packageJson)
+  return {
+    network: networkBindings.some((binding) => bindings.has(binding)) || features.has('https'),
+    ble: bindings.has('ble') || manifestBleOta,
+    bleApi: bindings.has('ble'),
+    audio: bindings.has('audio'),
+    bindings: [...bindings].sort(),
+    features: [...features].sort()
+  }
+}