@geastack/cli 0.1.52 → 0.1.54

package/src/esp32/flash.mjs

@@ -0,0 +1,181 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+
+import { waitForSerialPort } from '../boards/usb.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { formatCommand } from '../run.mjs'
+import { esptoolCommand } from './idf-env.mjs'
+import { flashOffsetForBuildImage, loadPartitions, normalizeOtaSlot, partitionByName, sizeToBytes } from './partitions.mjs'
+
+// USB flashing through esptool, with the board addressed by its USB serial:
+// a board re-enumerates after every reset, so the port is resolved again on
+// every attempt rather than cached.
+
+export function flashOptions(env, { manualBoot = false, noReset = false, baud = '' } = {}) {
+  const flashBaud = String(baud || env.GEA_ESP32_FLASH_BAUD || '921600')
+  if (!/^[1-9]\d*$/.test(flashBaud)) fail(`--flash-baud must be a positive integer (got '${flashBaud}').`, ExitCode.usage)
+  return {
+    before: manualBoot ? 'no_reset' : 'default_reset',
+    after: noReset ? 'no_reset' : 'hard_reset',
+    baud: flashBaud,
+    retrySeconds: Number(env.GEA_ESP32_FLASH_RETRY_SECONDS ?? 300),
+    manualBootGraceSeconds: Number(env.GEA_ESP32_MANUAL_BOOT_GRACE_SECONDS ?? 4)
+  }
+}
+
+function esptoolPrefix(selection, options) {
+  return ['--chip', selection.esptoolChip || selection.idfTarget || 'esp32s3', '--before', options.before, '--after', options.after, '-b', options.baud]
+}
+
+function writeFlashArgs(selection, options, pairs) {
+  return [...esptoolPrefix(selection, options), 'write_flash', '--flash_mode', 'dio', '--flash_freq', '80m', '--flash_size', selection.flashSize, ...pairs]
+}
+
+export async function runEsptoolOverUsb({ idf, selection, options, args, port = '', env, dryRun = false, stdout = console.log, stderr = console.error }) {
+  const startedAt = Date.now()
+  let attempt = 1
+  let status = 1
+  for (;;) {
+    let remaining = options.retrySeconds
+    if (options.retrySeconds > 0) {
+      remaining = options.retrySeconds - (Date.now() - startedAt) / 1000
+      if (remaining <= 0) {
+        throw new CliError('ERROR: Timed out waiting for USB flash connection.', ExitCode.deployFailed)
+      }
+    }
+    const flashPort = dryRun
+      ? port || `<usb serial ${selection.usbSerial}>`
+      : await waitForSerialPort({ port, serial: selection.usbSerial, timeoutSeconds: remaining, label: 'ESP32 USB flash port', log: stderr })
+    if (options.before === 'no_reset') {
+      stdout('Manual boot mode: hold BOOT/IO0, reset or power-cycle the board, then keep BOOT held until esptool connects.')
+      stdout('Manual boot mode: esptool will not toggle reset before connecting.')
+      if (options.manualBootGraceSeconds > 0 && !dryRun) {
+        stdout(`Manual boot mode: waiting ${options.manualBootGraceSeconds}s before attempt ${attempt}...`)
+        await new Promise((resolve) => setTimeout(resolve, options.manualBootGraceSeconds * 1000))
+      }
+    }
+    stdout(`USB flash attempt ${attempt} on ${flashPort}...`)
+    const { command, args: fullArgs } = esptoolCommand(idf, ['-p', flashPort, ...args])
+    if (dryRun) {
+      stdout(formatCommand([command, ...fullArgs]))
+      return 0
+    }
+    const result = spawnSync(command, fullArgs, { cwd: selection.targetDir, env, stdio: 'inherit' })
+    if (result.error) throw result.error
+    status = result.status ?? 1
+    if (status === 0) return 0
+    if (status === 130 || status === 143) throw new CliError('ERROR: USB flash interrupted.', ExitCode.deployFailed)
+    if (options.retrySeconds > 0 && (Date.now() - startedAt) / 1000 >= options.retrySeconds) {
+      throw new CliError(`ERROR: USB flash failed after ${attempt} attempt(s).`, ExitCode.deployFailed)
+    }
+    stderr(`USB flash attempt ${attempt} failed with status ${status}; waiting for board and retrying...`)
+    attempt += 1
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+  }
+}
+
+function requireImage(file, what) {
+  if (!existsSync(file)) fail(`${what} not found: ${file}`, ExitCode.deployFailed)
+  return file
+}
+
+function assertFits(image, slot, slotSize) {
+  const imageSize = statSync(image).size
+  if (imageSize > slotSize) {
+    fail(`App image is ${imageSize} bytes but ${slot} only has ${slotSize} bytes.\nRegenerate a partition plan with fewer apps or larger slots.`, ExitCode.deployFailed)
+  }
+}
+
+export function slotGeometry(selection, slot) {
+  const name = normalizeOtaSlot(slot)
+  const partition = partitionByName(loadPartitions(selection.targetDir), name)
+  return { name, offset: partition.offset, size: sizeToBytes(partition.size) }
+}
+
+// Bootloader + partition table + otadata + app in ota_0: a full provisioning
+// of the board from one build directory.
+export async function flashFirmware({ idf, selection, images, appImage = images.app, appLabel = 'prebuilt image', options, port, env, dryRun, stdout, stderr }) {
+  const image = requireImage(appImage, 'App image')
+  for (const required of [images.bootloader, images.partitionTable, images.otaData]) {
+    if (!existsSync(required)) fail(`${required} was not found. Build the launcher once first.`, ExitCode.deployFailed)
+  }
+  const partitions = loadPartitions(selection.targetDir)
+  const app = partitionByName(partitions, 'ota_0')
+  const otadata = partitionByName(partitions, 'otadata')
+  assertFits(image, 'ota_0', sizeToBytes(app.size))
+  const buildDir = images.buildDir
+  const pairs = [
+    flashOffsetForBuildImage(buildDir, images.bootloader, '0x0'), images.bootloader,
+    app.offset, image,
+    flashOffsetForBuildImage(buildDir, images.partitionTable, '0x8000'), images.partitionTable,
+    otadata.offset, images.otaData
+  ]
+  stdout(`Flashing '${appLabel}' from ${image} to ota_0 (${app.offset}) over USB...`)
+  stdout('Writing bootloader, partition table, default OTA boot metadata, and app image.')
+  await runEsptoolOverUsb({ idf, selection, options, args: writeFlashArgs(selection, options, pairs), port, env, dryRun, stdout, stderr })
+  stdout(`Flashed '${appLabel}' in ota_0 and reset OTA boot metadata to ota_0.`)
+}
+
+export async function flashImageSet({ idf, selection, images, slotImages, options, port, env, dryRun, stdout, stderr }) {
+  for (const required of [images.bootloader, images.partitionTable, images.otaData]) {
+    if (!existsSync(required)) fail(`${required} was not found. Build the launcher once first.`, ExitCode.deployFailed)
+  }
+  const partitions = loadPartitions(selection.targetDir)
+  const otadata = partitionByName(partitions, 'otadata')
+  const buildDir = images.buildDir
+  const pairs = [
+    flashOffsetForBuildImage(buildDir, images.bootloader, '0x0'), images.bootloader,
+    flashOffsetForBuildImage(buildDir, images.partitionTable, '0x8000'), images.partitionTable,
+    otadata.offset, images.otaData
+  ]
+  for (const entry of slotImages) {
+    const eq = entry.indexOf('=')
+    if (eq <= 0 || eq === entry.length - 1) fail(`Invalid --slot-image value '${entry}'. Use --slot-image=ota_<n>=<bin>.`, ExitCode.usage)
+    const slot = slotGeometry(selection, entry.slice(0, eq))
+    const image = requireImage(entry.slice(eq + 1), `App image for ${slot.name}`)
+    assertFits(image, slot.name, slot.size)
+    pairs.push(slot.offset, image)
+  }
+  stdout(`Flashing ${slotImages.length} prebuilt app image(s) over USB...`)
+  stdout('Writing bootloader, partition table, default OTA boot metadata, and app images.')
+  await runEsptoolOverUsb({ idf, selection, options, args: writeFlashArgs(selection, options, pairs), port, env, dryRun, stdout, stderr })
+  stdout(options.after === 'no_reset' ? 'Flashed app images. Device was not reset after flashing.' : 'Flashed app images. Device was reset after flashing.')
+}
+
+// App image only, into a chosen OTA slot; boot selection is untouched.
+export async function stageImage({ idf, selection, image, slot, appLabel = 'prebuilt image', options, port, env, dryRun, stdout, stderr }) {
+  const geometry = slotGeometry(selection, slot)
+  requireImage(image, 'App image')
+  assertFits(image, geometry.name, geometry.size)
+  stdout(`Staging '${appLabel}' from ${image} to ${geometry.name} (${geometry.offset}) over USB...`)
+  stdout('Writing app image only; bootloader, partition table, and otadata are unchanged.')
+  await runEsptoolOverUsb({ idf, selection, options, args: writeFlashArgs(selection, options, [geometry.offset, image]), port, env, dryRun, stdout, stderr })
+  stdout(`Staged '${appLabel}' in ${geometry.name}. Boot selection was not changed.`)
+}
+
+export async function restoreBootMetadata({ idf, selection, images, options, port, env, dryRun, stdout, stderr }) {
+  if (!existsSync(images.otaData)) fail(`${images.otaData} was not found. Flash the launcher once first.`, ExitCode.deployFailed)
+  const otadata = partitionByName(loadPartitions(selection.targetDir), 'otadata')
+  stdout(`Restoring OTA boot metadata at ${otadata.offset}...`)
+  await runEsptoolOverUsb({ idf, selection, options, args: writeFlashArgs(selection, options, [otadata.offset, images.otaData]), port, env, dryRun, stdout, stderr })
+  stdout('Launcher OTA boot metadata restored.')
+}
+
+export async function eraseSlot({ idf, selection, slot, options, port, env, dryRun, stdout, stderr }) {
+  const geometry = slotGeometry(selection, slot)
+  stdout(`Erasing ${geometry.name} (${geometry.offset}, ${geometry.size} bytes) over USB...`)
+  await runEsptoolOverUsb({ idf, selection, options, args: [...esptoolPrefix(selection, options), 'erase_region', geometry.offset, String(geometry.size)], port, env, dryRun, stdout, stderr })
+  stdout(`Erased ${geometry.name}.`)
+}
+
+export function postFlashRestartNote(selection, stderr) {
+  if (selection.usbRestartAfterFlash !== 'manual') return
+  stderr(`
+  ┌──────────────────────────────────────────────────────────────────────────┐
+  │  Flash complete. This board does NOT auto-restart after a USB flash.        │
+  │  Tap the RESET button (or unplug/replug power) to launch the app.           │
+  │                                                                             │
+  │  Why: its USB-Serial-JTAG re-enters ROM download mode when the flash port   │
+  │  is closed. It boots normally from a reset/power-cycle (no host involved).  │
+  └──────────────────────────────────────────────────────────────────────────┘`)
+}

package/src/esp32/idf-env.mjs

@@ -0,0 +1,171 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// ESP-IDF activation without `source export.sh`. export.sh re-checks Python,
+// dependencies, outdated tools and shell completion on every invocation; the
+// installation itself already knows the exact tool paths (idf_tools.py
+// export) and which Python env it installed, so the CLI reads those and runs
+// `<venv>/bin/python $IDF_PATH/tools/idf.py` directly.
+
+const idfVersionFile = 'tools/cmake/version.cmake'
+
+export function espIdfVersion(idfDir) {
+  const file = path.join(idfDir, idfVersionFile)
+  if (existsSync(file)) {
+    const text = readFileSync(file, 'utf8')
+    const major = text.match(/set\(IDF_VERSION_MAJOR\s+(\d+)\)/)?.[1]
+    const minor = text.match(/set\(IDF_VERSION_MINOR\s+(\d+)\)/)?.[1]
+    const patch = text.match(/set\(IDF_VERSION_PATCH\s+(\d+)\)/)?.[1]
+    if (major && minor) return { majorMinor: `${major}.${minor}`, full: `${major}.${minor}.${patch || 0}` }
+  }
+  const named = path.basename(idfDir).match(/^esp-idf-v(\d+\.\d+)(?:\.(\d+))?/)
+  if (named) return { majorMinor: named[1], full: `${named[1]}.${named[2] || 0}` }
+  return null
+}
+
+function isIdfDir(dir) {
+  return Boolean(dir) && existsSync(path.join(dir, 'tools', 'idf.py'))
+}
+
+function versionKey(dir) {
+  const version = espIdfVersion(dir)?.full || '0.0.0'
+  return version.split('.').map((part) => Number(part) || 0)
+}
+
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) - (b[i] || 0)
+  }
+  return 0
+}
+
+// Where an ESP-IDF checkout may live. Explicit settings win; otherwise the
+// newest install under the conventional directories is used, because the
+// firmware tracks the current IDF major (older ones do not compile it).
+export function findEspIdf(env = process.env, home = os.homedir()) {
+  const explicit = [env.IDF_PATH, envExportDir(env.GEA_EMBEDDED_IDF_EXPORT), envExportDir(env.ESP_IDF_EXPORT)]
+  for (const candidate of explicit) {
+    if (isIdfDir(candidate)) return path.resolve(candidate)
+  }
+  const roots = [path.join(home, 'esp'), path.join(home, 'esp32'), home]
+  const found = []
+  for (const root of roots) {
+    for (const name of ['esp-idf']) {
+      const dir = path.join(root, name)
+      if (isIdfDir(dir)) found.push(dir)
+    }
+    let entries = []
+    try {
+      entries = readdirSync(root)
+    } catch {
+      entries = []
+    }
+    for (const name of entries) {
+      if (!/^esp-idf-v\d/.test(name)) continue
+      const dir = path.join(root, name)
+      if (isIdfDir(dir)) found.push(dir)
+    }
+  }
+  if (found.length === 0) return ''
+  found.sort((a, b) => compareVersions(versionKey(b), versionKey(a)))
+  return found[0]
+}
+
+function envExportDir(exportScript) {
+  return exportScript ? path.dirname(exportScript) : ''
+}
+
+export function findIdfPythonEnv(idfDir, env = process.env, home = os.homedir()) {
+  const explicit = env.IDF_PYTHON_ENV_PATH
+  if (explicit && existsSync(path.join(explicit, 'bin', 'python'))) return explicit
+  const version = espIdfVersion(idfDir)?.majorMinor
+  if (!version) return ''
+  const envRoot = path.join(env.IDF_TOOLS_PATH || path.join(home, '.espressif'), 'python_env')
+  let entries = []
+  try {
+    entries = readdirSync(envRoot)
+  } catch {
+    return ''
+  }
+  const prefix = `idf${version}_py`
+  const candidates = entries
+    .filter((name) => name.startsWith(prefix) && name.endsWith('_env'))
+    .sort()
+    .map((name) => path.join(envRoot, name))
+    .filter((dir) => existsSync(path.join(dir, 'bin', 'python')))
+  return candidates[0] || ''
+}
+
+function parseKeyValueExport(output) {
+  const values = {}
+  for (const line of output.split(/\r?\n/)) {
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    values[line.slice(0, eq)] = line.slice(eq + 1)
+  }
+  return values
+}
+
+const activationCache = new Map()
+
+// Returns the environment and command prefixes for one ESP-IDF install, or
+// null when none is installed. `python` is the IDF venv interpreter, which
+// is also where esptool lives.
+// The tool export is cached per installation; the caller's environment is
+// layered on fresh every time so per-invocation settings (jobs, variants,
+// flash baud) are never frozen into a cached activation.
+export function activateEspIdf({ env = process.env, home = os.homedir(), log = () => {} } = {}) {
+  const idfDir = findEspIdf(env, home)
+  if (!idfDir) return null
+  const pythonEnv = findIdfPythonEnv(idfDir, env, home)
+  if (!pythonEnv) {
+    throw new Error(
+      `ESP-IDF at ${idfDir} has no installed Python environment under ${env.IDF_TOOLS_PATH || path.join(home, '.espressif')}/python_env. Run its install.sh once.`
+    )
+  }
+  const python = path.join(pythonEnv, 'bin', 'python')
+  const idfToolsPy = path.join(idfDir, 'tools', 'idf_tools.py')
+  const cacheKey = `${idfDir}\n${pythonEnv}`
+  let exported = activationCache.get(cacheKey)
+  if (!exported) {
+    try {
+      exported = parseKeyValueExport(
+        execFileSync(python, [idfToolsPy, 'export', '--format', 'key-value'], {
+          encoding: 'utf8',
+          env: { ...env, IDF_PATH: idfDir },
+          stdio: ['ignore', 'pipe', 'ignore']
+        })
+      )
+    } catch (error) {
+      throw new Error(`ESP-IDF tool export failed for ${idfDir}: ${error.message}`)
+    }
+    activationCache.set(cacheKey, exported)
+    log(`Using ESP-IDF ${espIdfVersion(idfDir)?.full || ''} at ${idfDir} (python env ${pythonEnv})`)
+  }
+  const exportedPath = (exported.PATH || '').replace(/\$PATH|%PATH%/g, env.PATH || '')
+  return {
+    idfDir,
+    version: espIdfVersion(idfDir),
+    pythonEnv,
+    python,
+    idfPy: path.join(idfDir, 'tools', 'idf.py'),
+    env: {
+      ...env,
+      ...Object.fromEntries(Object.entries(exported).filter(([key]) => key !== 'PATH' && key !== 'IDF_DEACTIVATE_FILE_PATH')),
+      IDF_PATH: idfDir,
+      IDF_PYTHON_ENV_PATH: pythonEnv,
+      VIRTUAL_ENV: pythonEnv,
+      PATH: [path.join(pythonEnv, 'bin'), exportedPath || env.PATH || ''].filter(Boolean).join(path.delimiter)
+    }
+  }
+}
+
+export function esptoolCommand(idf, args) {
+  return { command: idf.python, args: ['-m', 'esptool', ...args] }
+}
+
+export function idfPyCommand(idf, args) {
+  return { command: idf.python, args: [idf.idfPy, ...args] }
+}

package/src/esp32/ota.mjs

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+import { otaErase, otaUpload, waitForOtaServer } from '../device/wifi.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { formatCommand } from '../run.mjs'
+import { slotGeometry } from './flash.mjs'
+
+// Over-the-air delivery: WiFi through the board's OTA server, or BLE through
+// the CoreBluetooth helper. Neither touches the bootloader or partition table.
+
+function requireImage(image) {
+  if (!existsSync(image)) fail(`App image not found: ${image}`, ExitCode.deployFailed)
+  return image
+}
+
+export async function otaFlash({ host, image, dryRun = false, stdout = console.log }) {
+  requireImage(image)
+  stdout(`Sending OTA update to ${host}...`)
+  if (dryRun) {
+    stdout(`POST http://${host}:8080/ota <- ${image}`)
+    return
+  }
+  await otaUpload({ host, image, stdout })
+  stdout('OTA complete. Board is rebooting.')
+}
+
+export async function otaStage({ selection, host, image, slot, boot = false, reboot = false, appLabel = 'prebuilt image', dryRun = false, stdout = console.log }) {
+  const geometry = slotGeometry(selection, slot)
+  requireImage(image)
+  const size = statSync(image).size
+  if (size > geometry.size) {
+    fail(`App image is ${size} bytes but ${geometry.name} only has ${geometry.size} bytes.\nRegenerate a partition plan with fewer apps or larger slots.`, ExitCode.deployFailed)
+  }
+  stdout(`Staging '${appLabel}' from ${image} to ${geometry.name} over WiFi OTA...`)
+  if (dryRun) {
+    stdout(`POST http://${host}:8080/ota?slot=${geometry.name}&boot=${boot ? 1 : 0}&reboot=${reboot ? 1 : 0} <- ${image}`)
+    return
+  }
+  await otaUpload({ host, image, slot: geometry.name, boot, reboot, stdout })
+  stdout(`Staged '${appLabel}' in ${geometry.name} over OTA. Boot selection was not changed.`)
+}
+
+export async function otaEraseSlot({ selection, host, slot, dryRun = false, stdout = console.log }) {
+  const geometry = slotGeometry(selection, slot)
+  stdout(`Erasing ${geometry.name} over WiFi OTA...`)
+  if (dryRun) {
+    stdout(`POST http://${host}:8080/ota/erase?slot=${geometry.name}`)
+    return
+  }
+  const reply = await otaErase({ host, slot: geometry.name })
+  if (reply) stdout(reply)
+  stdout(`Erased ${geometry.name} over OTA.`)
+}
+
+export async function waitForReboot({ host, stdout = console.log, timeoutMs = 120000 }) {
+  stdout('OTA sent. Waiting for reboot + WiFi reconnect...')
+  await new Promise((resolve) => setTimeout(resolve, 8000))
+  await waitForOtaServer({ host, timeoutMs })
+}
+
+export function bleOtaHelperPath(cliPackageRoot) {
+  return path.join(cliPackageRoot, 'src', 'ble', 'ble-ota.swift')
+}
+
+export function bleOta({ cliPackageRoot, image, deviceName, env, dryRun = false, stdout = console.log }) {
+  requireImage(image)
+  const helper = bleOtaHelperPath(cliPackageRoot)
+  const args = [helper, image, deviceName || env.GEA_BLE_OTA_DEVICE || 'Geastack OTA']
+  if (dryRun) {
+    stdout(formatCommand(['swift', ...args]))
+    return
+  }
+  const probe = spawnSync('swift', ['--version'], { env, stdio: 'ignore' })
+  if (probe.error || probe.status !== 0) fail('BLE OTA currently requires Swift/CoreBluetooth on macOS.', ExitCode.missingDependency)
+  const result = spawnSync('swift', args, { env, stdio: 'inherit' })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new CliError(`ERROR: BLE OTA failed (${result.status}).`, ExitCode.deployFailed)
+}

package/src/esp32/partitions.mjs

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// partitions.csv is the target project's flash layout; OTA slots and otadata
+// are looked up there so images are written where the bootloader expects them.
+
+export function parsePartitionsCsv(text) {
+  const rows = []
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const fields = line.split(',').map((field) => field.trim())
+    if (fields.length < 5) continue
+    rows.push({ name: fields[0], type: fields[1], subtype: fields[2], offset: fields[3], size: fields[4], flags: fields[5] || '' })
+  }
+  return rows
+}
+
+export function loadPartitions(targetDir, file = 'partitions.csv') {
+  const csvPath = path.join(targetDir, file)
+  if (!existsSync(csvPath)) throw new Error(`Partition table not found: ${csvPath}`)
+  return parsePartitionsCsv(readFileSync(csvPath, 'utf8'))
+}
+
+export function normalizeOtaSlot(slot) {
+  const value = String(slot || '')
+  if (value.startsWith('ota_')) return value
+  if (/^\d+$/.test(value)) return `ota_${value}`
+  return value
+}
+
+export function partitionByName(partitions, name) {
+  const found = partitions.find((partition) => partition.name === name)
+  if (!found) throw new Error(`Partition '${name}' was not found in partitions.csv.`)
+  return found
+}
+
+export function sizeToBytes(value) {
+  const text = String(value).trim()
+  const match = text.match(/^(0x[0-9a-fA-F]+|\d+)\s*([KkMm]?)$/)
+  if (!match) throw new Error(`Unrecognised partition size '${value}'.`)
+  const base = match[1].toLowerCase().startsWith('0x') ? Number.parseInt(match[1], 16) : Number.parseInt(match[1], 10)
+  const unit = match[2].toUpperCase()
+  return unit === 'K' ? base * 1024 : unit === 'M' ? base * 1024 * 1024 : base
+}
+
+// IDF writes the real offsets of bootloader/partition-table images into
+// flash_args once a build has configured; fall back to the chip defaults.
+export function flashOffsetForBuildImage(buildDir, imagePath, fallback) {
+  const flashArgs = path.join(buildDir, 'flash_args')
+  const relative = imagePath.startsWith(`${buildDir}${path.sep}`) ? imagePath.slice(buildDir.length + 1) : imagePath
+  if (existsSync(flashArgs)) {
+    for (const line of readFileSync(flashArgs, 'utf8').split(/\r?\n/)) {
+      const fields = line.trim().split(/\s+/)
+      if (fields.length >= 2 && fields[fields.length - 1] === relative) return fields[fields.length - 2]
+    }
+  }
+  return fallback
+}

package/src/esp32/sdkconfig.mjs

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// ESP-IDF's generated sdkconfig is mutable build state. It lives beside the
+// CMake cache that owns it (inside the app's own build directory), so
+// configuring one app can never rewrite another app's configuration or the
+// stale target-root sdkconfig old builds left behind. The file starts empty:
+// a partial sdkconfig is valid Kconfig input and IDF fills everything else
+// from sdkconfig.defaults on the first configure.
+export function prepareBuildLocalSdkconfig(targetDir, buildDir) {
+  const normalized = path.normalize(buildDir)
+  if (!buildDir || normalized === '..' || normalized.startsWith(`..${path.sep}`) || normalized.split(path.sep).includes('..')) {
+    throw new Error(`Invalid ESP32 build directory: ${buildDir}`)
+  }
+  const file = path.isAbsolute(buildDir) ? path.join(buildDir, 'sdkconfig') : path.join(targetDir, buildDir, 'sdkconfig')
+  const defaultsFile = path.join(targetDir, 'sdkconfig.defaults')
+  if (!existsSync(defaultsFile)) throw new Error(`ESP32 sdkconfig defaults not found: ${defaultsFile}`)
+  mkdirSync(path.dirname(file), { recursive: true })
+  if (!existsSync(file)) writeFileSync(file, '')
+  return { file, defaultsFile }
+}
+
+function splitLines(text) {
+  const lines = text.split('\n')
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  return lines
+}
+
+export function withSdkconfigValue(text, key, value) {
+  const lines = splitLines(text)
+  const wanted = `${key}=${value}`
+  if (lines.includes(wanted)) return text
+  const out = []
+  let written = false
+  for (const line of lines) {
+    if (line.startsWith(`${key}=`) || line === `# ${key} is not set`) {
+      if (!written) {
+        out.push(wanted)
+        written = true
+      }
+      continue
+    }
+    out.push(line)
+  }
+  if (!written) out.push(wanted)
+  return `${out.join('\n')}\n`
+}
+
+export function withSdkconfigUnset(text, key) {
+  const lines = splitLines(text)
+  const unset = `# ${key} is not set`
+  if (lines.includes(unset) && !lines.some((line) => line.startsWith(`${key}=`))) return text
+  const out = []
+  let written = false
+  for (const line of lines) {
+    if (line.startsWith(`${key}=`) || line === unset) {
+      if (!written) {
+        out.push(unset)
+        written = true
+      }
+      continue
+    }
+    out.push(line)
+  }
+  if (!written) out.push(unset)
+  return `${out.join('\n')}\n`
+}
+
+export class Sdkconfig {
+  constructor(file, defaultsFile) {
+    this.file = file
+    this.defaultsFile = defaultsFile
+    this.text = existsSync(file) ? readFileSync(file, 'utf8') : ''
+    this.defaults = existsSync(defaultsFile) ? readFileSync(defaultsFile, 'utf8') : ''
+  }
+
+  set(key, value) {
+    this.text = withSdkconfigValue(this.text, key, value)
+    return this
+  }
+
+  unset(key) {
+    this.text = withSdkconfigUnset(this.text, key)
+    return this
+  }
+
+  has(pattern) {
+    return pattern.test(this.text)
+  }
+
+  defaultValue(key) {
+    return this.defaults.match(new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}=(.*)$`, 'm'))?.[1] ?? ''
+  }
+
+  defaultIsSet(key) {
+    return this.defaultValue(key) === 'y'
+  }
+
+  save() {
+    const current = existsSync(this.file) ? readFileSync(this.file, 'utf8') : null
+    if (current !== this.text) writeFileSync(this.file, this.text)
+  }
+}

package/src/esp32/wifi-config.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// WiFi credentials come from the app's .env (GEA_WIFI_SSID / GEA_WIFI_PASSWORD)
+// and are compiled in as a generated header inside the build directory.
+
+export function readDotEnv(file) {
+  let text = ''
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    throw error
+  }
+  const values = {}
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const equals = line.indexOf('=')
+    if (equals < 0) continue
+    let key = line.slice(0, equals).trim()
+    if (key.startsWith('export ')) key = key.slice(7).trim()
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
+    let value = line.slice(equals + 1).trim()
+    if (value.length >= 2 && ((value[0] === '"' && value.endsWith('"')) || (value[0] === "'" && value.endsWith("'")))) {
+      value = value.slice(1, -1)
+    }
+    values[key] = value
+  }
+  return values
+}
+
+export function quoteCString(value) {
+  let output = '"'
+  for (const character of String(value)) {
+    const code = character.codePointAt(0)
+    if (character === '\\') output += '\\\\'
+    else if (character === '"') output += '\\"'
+    else if (character === '\n') output += '\\n'
+    else if (character === '\r') output += '\\r'
+    else if (character === '\t') output += '\\t'
+    else if (code < 0x20 || code === 0x7f) output += `\\x${code.toString(16).padStart(2, '0')}""`
+    else output += character
+  }
+  return `${output}"`
+}
+
+export function wifiConfigContents(values) {
+  const ssid = values.GEA_WIFI_SSID || ''
+  const password = values.GEA_WIFI_PASSWORD || ''
+  return [
+    '#pragma once',
+    `#define GEA_EMBEDDED_WIFI_SSID ${quoteCString(ssid)}`,
+    `#define GEA_EMBEDDED_WIFI_PASSWORD ${quoteCString(password)}`,
+    `#define GEA_EMBEDDED_WIFI_EARLY_CONNECT ${ssid ? 1 : 0}`,
+    ''
+  ].join('\n')
+}
+
+export function generateWifiConfig(appDir, outputFile) {
+  const contents = wifiConfigContents(readDotEnv(path.join(appDir, '.env')))
+  fs.mkdirSync(path.dirname(outputFile), { recursive: true })
+  let current = ''
+  try {
+    current = fs.readFileSync(outputFile, 'utf8')
+  } catch {
+    current = ''
+  }
+  if (current !== contents) fs.writeFileSync(outputFile, contents, { mode: 0o600 })
+  fs.chmodSync(outputFile, 0o600)
+  return outputFile
+}