@geastack/cli 0.1.52 → 0.1.53

package/src/boards/resolve.mjs

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+import { loadBoardConfig, normalizeBoardConfig } from './config.mjs'
+import { loadTargets } from './targets.mjs'
+import { resolveUsbSerialPort } from './usb.mjs'
+
+export const usbSerialAdapters = new Set(['esp32-idf', 'rp2350-pico', 'taurus-s3'])
+export const geaosAdapters = new Set(['geaos-linux', 'geaos-arm64'])
+
+function boardTransport(board, name) {
+  return board?.transports?.[name] || {}
+}
+
+function isAuto(value) {
+  return !value || /^auto$/i.test(value) || value === '<auto>'
+}
+
+// Turns a board alias (or a bare target id) into everything a command needs:
+// the target project directory, its adapter, chip/flash metadata and the
+// transports the command asked for. `needs.usbPort` resolves the board's USB
+// serial to today's /dev port; `needs.otaHost` resolves transports.ota.host.
+// Commands state what they need instead of the resolver guessing from names.
+export function resolveBoardSelection({
+  ctx = null,
+  boardName = '',
+  targetName = '',
+  requestedPort = '',
+  requestedHost = '',
+  needs = {},
+  targets = ctx ? loadTargets(ctx) : {},
+  config = ctx ? loadBoardConfig(ctx) : {},
+  configDir = ctx ? (ctx.boardsConfig ? path.dirname(ctx.boardsConfig) : path.dirname(ctx.projectBoardsConfig)) : process.cwd(),
+  usbSerialResolver = resolveUsbSerialPort,
+  deferUsbPort = false
+} = {}) {
+  const boards = normalizeBoardConfig(config)
+  const board = boardName ? boards[boardName] : null
+  if (boardName && !board) {
+    throw new Error(`Unknown board '${boardName}'. Add it to .gea/boards.json (gea boards add) or run gea boards list.`)
+  }
+
+  let target = board?.target || targetName || ''
+  if (!target) throw new Error('No board selected. Pass --board <alias> (gea boards list) or --target <id>.')
+  let targetBase = target
+  let targetDefinition = ''
+  let definition = null
+  if (board?.targetDefinition) {
+    targetDefinition = path.resolve(configDir, board.targetDefinition)
+    if (!existsSync(targetDefinition)) {
+      throw new Error(`Target definition for board '${boardName}' was not found: ${targetDefinition}`)
+    }
+    definition = JSON.parse(readFileSync(targetDefinition, 'utf8'))
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+      throw new Error(`Target definition must be a JSON object: ${targetDefinition}`)
+    }
+    if (!definition.id) throw new Error(`Target definition is missing id: ${targetDefinition}`)
+    if (!definition.extends) throw new Error(`Target definition is missing extends: ${targetDefinition}`)
+    if (board.target && board.target !== definition.id) {
+      throw new Error(`Board '${boardName}' selects target '${board.target}', but ${targetDefinition} defines '${definition.id}'.`)
+    }
+    target = definition.id
+    targetBase = definition.extends
+  }
+  const targetInfo = targets[targetBase] || {}
+  const adapter = board?.adapter || definition?.adapter || targetInfo.adapter || ''
+  if (!adapter) throw new Error(`Unknown target '${target}'. It is not in targets.json and the board declares no adapter.`)
+
+  const usb = boardTransport(board, 'usbSerial')
+  if (usb.path) {
+    throw new Error(`Board '${boardName}' uses transports.usbSerial.path, which is no longer supported; set transports.usbSerial.serial instead.`)
+  }
+  let port = ''
+  let host = ''
+  const usbSerial = usb.serial || ''
+
+  if (needs.usbPort && usbSerialAdapters.has(adapter)) {
+    if (!isAuto(requestedPort)) {
+      port = requestedPort
+    } else if (usbSerial) {
+      if (!deferUsbPort) port = usbSerialResolver({ serial: usbSerial })
+    } else if (boardName) {
+      // A WiFi-only board hits this on monitor/screenshot. Point at the
+      // cable-free command instead of dead-ending on USB.
+      const wireless = boardTransport(board, 'ota').host
+        ? ` This board has transports.ota.host, so 'gea logs --board ${boardName}' and 'gea screenshot --board ${boardName}' work with no cable.`
+        : ''
+      throw new Error(`Board '${boardName}' does not define transports.usbSerial.serial, and no USB port was passed.${wireless}`)
+    }
+  }
+
+  // geaos devices are identified by USB serial too, but tolerantly: a build
+  // with the watch detached must still work, so an unresolved port stays
+  // empty and the adapter errors at the point it needs the device.
+  if (needs.usbPort && geaosAdapters.has(adapter)) {
+    if (!isAuto(requestedPort)) {
+      port = requestedPort
+    } else if (usbSerial && !deferUsbPort) {
+      try {
+        port = usbSerialResolver({ serial: usbSerial })
+      } catch {
+        port = ''
+      }
+    }
+  }
+
+  if (needs.otaHost) {
+    if (!isAuto(requestedHost)) {
+      host = requestedHost
+    } else {
+      host = boardTransport(board, 'ota').host || ''
+      if (!host) throw new Error(`Board '${boardName || target}' does not define transports.ota.host, and no --host was passed.`)
+    }
+  }
+
+  const selection = {
+    boardName,
+    target,
+    adapter,
+    targetDir: board?.targetDir || targetInfo.targetDir || '',
+    flashSize: board?.flashSize || targetInfo.flashSize || '',
+    appPlatform: board?.appPlatform || targetInfo.appPlatform || '',
+    compatibleAppPlatforms: Array.isArray(targetInfo.compatibleAppPlatforms) ? targetInfo.compatibleAppPlatforms : [],
+    idfTarget: board?.idfTarget || targetInfo.idfTarget || '',
+    esptoolChip: board?.esptoolChip || targetInfo.esptoolChip || '',
+    mainTaskStackSize: board?.mainTaskStackSize || targetInfo.mainTaskStackSize || '',
+    ipcTaskStackSize: board?.ipcTaskStackSize || targetInfo.ipcTaskStackSize || '',
+    port,
+    host,
+    usbSerial,
+    usbRestartAfterFlash: usb.restartAfterFlash || '',
+    otaHost: boardTransport(board, 'ota').host || '',
+    telnetHost: boardTransport(board, 'telnet').host || board?.telnetHost || targetInfo.telnetHost || '',
+    telnetPort: String(boardTransport(board, 'telnet').port || board?.telnetPort || targetInfo.telnetPort || ''),
+    fastbootSerial: boardTransport(board, 'fastboot').serial || board?.fastbootSerial || '',
+    mtkWorkdir: boardTransport(board, 'mtk').workdir || board?.mtkWorkdir || '',
+    mtkBootSlot: boardTransport(board, 'mtk').bootSlot || board?.mtkBootSlot || '',
+    mtkMethod: boardTransport(board, 'mtk').method || board?.mtkMethod || '',
+    mtkMonitorGlob: boardTransport(board, 'mtk').monitorGlob || board?.mtkMonitorGlob || '',
+    targetDefinition
+  }
+  return selection
+}

package/src/boards/targets.mjs

@@ -0,0 +1,45 @@
+import path from 'node:path'
+
+import { ExitCode, fail } from '../errors.mjs'
+import { exists, readJson } from '../fs-utils.mjs'
+
+// Built-in targets are DATA shipped by @geastack/targets (targets.json at the
+// package root). Each entry names an adapter and where its project lives; the
+// project may sit in another package (geaos boards live in @geastack/geaos).
+export function loadTargets(ctx) {
+  if (!ctx.targetsRoot) return {}
+  const file = path.join(ctx.targetsRoot, 'targets.json')
+  if (!exists(file)) return {}
+  const raw = readJson(file)
+  const out = {}
+  for (const [id, entry] of Object.entries(raw)) {
+    const { targetPath, package: packageName, ...rest } = entry
+    if (!targetPath) fail(`Built-in target '${id}' is missing targetPath in ${file}.`, ExitCode.missingDependency)
+    const packageRoot = packageName ? packageDirFor(ctx, packageName) : ctx.targetsRoot
+    out[id] = {
+      ...rest,
+      id,
+      package: packageName || '@geastack/targets',
+      targetDir: packageRoot ? path.join(packageRoot, targetPath) : ''
+    }
+  }
+  return out
+}
+
+export function requireTargets(ctx) {
+  if (!ctx.targetsRoot) {
+    fail('@geastack/targets is not installed in this project (npm i @geastack/targets).', ExitCode.missingDependency)
+  }
+  const targets = loadTargets(ctx)
+  if (Object.keys(targets).length === 0) {
+    fail(`No targets.json found in ${ctx.targetsRoot}.`, ExitCode.missingDependency)
+  }
+  return targets
+}
+
+function packageDirFor(ctx, packageName) {
+  for (const field of Object.keys(ctx)) {
+    if (typeof ctx.packageName === 'function' && ctx.packageName(field) === packageName) return ctx[field]
+  }
+  return ''
+}

package/src/boards/usb.mjs

@@ -0,0 +1,211 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+
+// A board is identified by its USB SERIAL, never by a /dev path: enumerated
+// paths change on every plug-in and identical boards routinely share one.
+// Everything here maps a stable serial to whatever port the OS gave it today.
+
+const serialPatterns = [
+  /^cu\.usbmodem/,
+  /^tty\.usbmodem/,
+  /^cu\.usbserial/,
+  /^tty\.usbserial/,
+  /^cu\.SLAB_USBtoUART/,
+  /^tty\.SLAB_USBtoUART/,
+  /^ttyACM/,
+  /^ttyUSB/
+]
+
+export function serialPortCandidates() {
+  const dev = '/dev'
+  if (!existsSync(dev)) return []
+  return readdirSync(dev)
+    .filter((name) => serialPatterns.some((pattern) => pattern.test(name)))
+    .map((name) => path.join(dev, name))
+    .sort()
+}
+
+export function resolveAutoUsbPort() {
+  const candidates = serialPortCandidates()
+  const callout = candidates.filter((candidate) => path.basename(candidate).startsWith('cu.'))
+  const usable = callout.length > 0 ? callout : candidates
+  if (usable.length <= 1) return usable[0] || ''
+  throw new Error(
+    ['Multiple USB serial ports are present; use --board <alias> with a registered USB serial.', ...usable.map((c) => `  ${c}`)].join('\n')
+  )
+}
+
+export function normalizedSerial(value) {
+  return String(value || '').replace(/[^a-z0-9]/gi, '').toLowerCase()
+}
+
+function linuxSerialByIdCandidates(serial) {
+  const dir = '/dev/serial/by-id'
+  if (!existsSync(dir)) return []
+  const needle = normalizedSerial(serial)
+  return readdirSync(dir)
+    .filter((name) => normalizedSerial(name).includes(needle))
+    .map((name) => path.join(dir, name))
+}
+
+function ioregStringProperty(line, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return line.match(new RegExp(`"${escaped}"\\s*=\\s*"([^"]*)"`))?.[1] || ''
+}
+
+function ioregNumberProperty(line, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const value = line.match(new RegExp(`"${escaped}"\\s*=\\s*(\\d+)`))?.[1] || ''
+  return value ? Number(value) : 0
+}
+
+function macUsbDeviceForSerial(serial, ioreg = runIoreg) {
+  const output = ioreg(['-p', 'IOUSB', '-l', '-w0'])
+  let current = null
+  const devices = []
+  for (const line of output.split(/\r?\n/)) {
+    // One `| ` per nesting level -- devices behind hubs carry several.
+    const node = line.match(/^([\s|]*)[+\\-]*o .*@([0-9a-fA-F]+)\s+<class IOUSBHostDevice/)
+    if (node) {
+      if (current) devices.push(current)
+      current = { locationHex: node[2], text: line }
+      continue
+    }
+    if (current) current.text += `\n${line}`
+  }
+  if (current) devices.push(current)
+  const needle = normalizedSerial(serial)
+  return devices.find((device) =>
+    device.text.split(/\r?\n/).some((line) => {
+      const value = ioregStringProperty(line, 'kUSBSerialNumberString') || ioregStringProperty(line, 'USB Serial Number')
+      return value && normalizedSerial(value) === needle
+    })
+  ) || null
+}
+
+function locationDigits(locationHex) {
+  return locationHex.toLowerCase().replace(/^0+/, '').replace(/0+$/, '').replace(/[^0-9a-f]/g, '')
+}
+
+function macUsbCalloutPortsForSerial(serial, ioreg = runIoreg) {
+  const output = ioreg(['-p', 'IOService', '-l', '-w0'], { maxBuffer: 64 * 1024 * 1024 })
+  const stack = []
+  const matches = new Set()
+  const needle = normalizedSerial(serial)
+  for (const line of output.split(/\r?\n/)) {
+    const node = line.match(/^([\s|]*)[+\\-]*o\s+/)
+    if (node) {
+      const depth = (node[1].match(/\|/g) || []).length
+      while (stack.length > 0 && stack[stack.length - 1].depth >= depth) stack.pop()
+      stack.push({ depth, serial: '' })
+      continue
+    }
+    if (stack.length === 0) continue
+    const current = stack[stack.length - 1]
+    const serialValue = ioregStringProperty(line, 'kUSBSerialNumberString') || ioregStringProperty(line, 'USB Serial Number')
+    if (serialValue) current.serial = serialValue
+    const callout = ioregStringProperty(line, 'IOCalloutDevice')
+    if (!callout || !path.basename(callout).startsWith('cu.')) continue
+    const inherited = [...stack].reverse().find((entry) => entry.serial)?.serial || ''
+    if (normalizedSerial(inherited) === needle) matches.add(callout)
+  }
+  return [...matches].sort()
+}
+
+function runIoreg(args, options = {}) {
+  return execFileSync('ioreg', args, { encoding: 'utf8', ...options })
+}
+
+function resolveMacUsbSerialPort(serial, ioreg = runIoreg) {
+  const candidates = serialPortCandidates().filter((candidate) => path.basename(candidate).startsWith('cu.'))
+  const needle = normalizedSerial(serial)
+  const serialMatches = candidates.filter((candidate) => normalizedSerial(path.basename(candidate)).includes(needle))
+  if (serialMatches.length === 1) return serialMatches[0]
+
+  const location = macUsbDeviceForSerial(serial, ioreg)?.locationHex || ''
+  const digits = locationDigits(location)
+  if (digits) {
+    const locationMatches = candidates.filter((candidate) => normalizedSerial(path.basename(candidate)).includes(digits))
+    if (locationMatches.length === 1) return locationMatches[0]
+    const registryMatches = macUsbCalloutPortsForSerial(serial, ioreg)
+    if (registryMatches.length === 1) return registryMatches[0]
+    if (registryMatches.length > 1) {
+      throw new Error([`USB serial ${serial} maps to multiple /dev/cu.* ports:`, ...registryMatches.map((c) => `  ${c}`)].join('\n'))
+    }
+  }
+  throw new Error(`Could not map USB serial ${serial} to a /dev/cu.* port. Check that the board is attached.`)
+}
+
+export function resolveUsbSerialPort({ serial }, { platform = process.platform, ioreg = runIoreg } = {}) {
+  if (!serial) throw new Error('A USB serial number is required to locate the board; /dev paths are not accepted.')
+  if (platform === 'linux') {
+    const matches = linuxSerialByIdCandidates(serial)
+    if (matches.length === 1) return realpathSync(matches[0])
+    throw new Error(`Could not map USB serial ${serial} to a /dev/serial/by-id entry. Check that the board is attached.`)
+  }
+  if (platform === 'darwin') return resolveMacUsbSerialPort(serial, ioreg)
+  throw new Error(`USB serial lookup is not implemented on ${platform}.`)
+}
+
+// picotool selects by bus/address on macOS (its --ser matching is unreliable
+// there); everywhere else the serial itself is the selector.
+export function resolvePicotoolSelection({ serial }, { platform = process.platform, ioreg = runIoreg } = {}) {
+  if (!serial) return []
+  if (platform !== 'darwin') return ['--ser', serial]
+  let device = null
+  try {
+    device = macUsbDeviceForSerial(serial, ioreg)
+  } catch {
+    device = null
+  }
+  if (!device?.locationHex) return ['--ser', serial]
+  const bus = Number.parseInt(device.locationHex.slice(0, 2), 16)
+  const address = device.text
+    .split(/\r?\n/)
+    .map((line) => ioregNumberProperty(line, 'USB Address') || ioregNumberProperty(line, 'kUSBAddress'))
+    .find(Boolean) || 0
+  if (!bus || !address) return ['--ser', serial]
+  return ['--bus', String(bus), '--address', String(address)]
+}
+
+// Poll until the board's port exists. A board reboots (and re-enumerates)
+// after a flash, so callers retry on the SERIAL, not on a cached path.
+export async function waitForSerialPort({
+  port = '',
+  serial = '',
+  timeoutSeconds = 300,
+  label = 'USB serial port',
+  pollSeconds = 1,
+  log = (line) => process.stderr.write(`${line}\n`),
+  resolver = resolveUsbSerialPort
+} = {}) {
+  const startedAt = Date.now()
+  let nextLog = startedAt
+  while (true) {
+    if (port) {
+      if (existsSync(port)) return port
+    } else if (serial) {
+      try {
+        const resolved = resolver({ serial })
+        if (resolved && existsSync(resolved)) return resolved
+      } catch {
+        // not attached yet
+      }
+    } else {
+      const candidate = serialPortCandidates()[0]
+      if (candidate) return candidate
+    }
+    const elapsed = (Date.now() - startedAt) / 1000
+    if (timeoutSeconds > 0 && elapsed >= timeoutSeconds) {
+      const where = port ? ` at ${port}` : serial ? ` with USB serial ${serial}` : ''
+      throw new Error(`Timed out waiting for ${label}${where}.`)
+    }
+    if (Date.now() >= nextLog) {
+      const where = port ? ` at ${port}` : serial ? ` with USB serial ${serial}` : ''
+      log(`Waiting for ${label}${where}...`)
+      nextLog = Date.now() + 5000
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollSeconds * 1000))
+  }
+}

package/src/commands/apps.mjs

@@ -0,0 +1,236 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+
+import { flag, option, optionList } from '../args.mjs'
+import { loadBoardConfig, normalizeBoardConfig, boardConfigPath } from '../boards/config.mjs'
+import { loadTargets } from '../boards/targets.mjs'
+import { ExitCode, fail } from '../errors.mjs'
+import { exists } from '../fs-utils.mjs'
+import { appCmakeMeta, appSummary, assertValidApp, discoverApps, resolveRequestedApp } from '../manifest.mjs'
+
+// gea apps ... : the app catalog and everything generated from it.
+
+export async function appsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  const args = rest.slice(1)
+  switch (sub) {
+    case 'list': return listApps(ctx, parsed, options)
+    case 'inspect': return inspectApp(ctx, parsed, args, options)
+    case 'pack': return packApp(ctx, parsed, args, options)
+    case 'index': return appIndex(ctx, parsed, options)
+    case 'launcher': return launcher(ctx, parsed, options)
+    case 'icons': return icons(ctx, parsed, args, options)
+    case 'icon-sheet': return iconSheet(ctx, parsed, options)
+    case 'apple-icons': return appleIcons(ctx, parsed, args, options)
+    default:
+      fail(`Unknown apps subcommand '${sub}'. Expected list, inspect, pack, index, launcher, icons, icon-sheet, or apple-icons.`, ExitCode.usage)
+  }
+}
+
+function listApps(ctx, parsed, options) {
+  const target = option(parsed, 'target', '')
+  const apps = discoverApps(ctx).filter((app) => !target || app.targets?.[target] === true)
+  if (flag(parsed, 'json')) options.stdout(JSON.stringify(apps.map((app) => appSummary(ctx, app)), null, 2))
+  else for (const app of apps) options.stdout(app.id)
+  return 0
+}
+
+function inspectApp(ctx, parsed, args, options) {
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const format = option(parsed, 'format', flag(parsed, 'json') ? 'json' : 'text')
+  const summary = appSummary(ctx, app)
+  if (format === 'cmake') options.stdout(appCmakeMeta(ctx, app))
+  else if (format === 'shell') options.stdout(`${summary.root}\t${app.entry}\t${app.runtime}\t${app.name}`)
+  else if (format === 'json') options.stdout(JSON.stringify(summary, null, 2))
+  else options.stdout(`${app.id}\t${app.name}\t${summary.root}\t${app.entry}`)
+  return 0
+}
+
+async function packApp(ctx, parsed, args, options) {
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const target = option(parsed, 'target', 'geaos')
+  const { createGeaBundle } = await import('../apps/bundle-writer.mjs')
+  const out = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'dist', `${app.id}-${target}.gea.zip`)))
+  const artifactDir = option(parsed, 'artifact-dir', '')
+  const manifest = createGeaBundle({ repoRoot: ctx.projectRoot, app, target, outputPath: out, artifactDir: artifactDir ? path.resolve(ctx.cwd, artifactDir) : '' })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputPath: out, manifest }, null, 2) : out)
+  return 0
+}
+
+async function appIndex(ctx, parsed, options) {
+  const { generateAppIndex } = await import('../apps/app-index-writer.mjs')
+  const outputFile = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'simulator', 'src', 'generated', 'app-index.ts')))
+  const apps = generateAppIndex({ apps: discoverApps(ctx).map((app) => appSummary(ctx, app)), outputFile })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputFile, apps }, null, 2) : outputFile)
+  return 0
+}
+
+async function launcher(ctx, parsed, options) {
+  const { generateLauncherCatalog } = await import('../apps/launcher-catalog.mjs')
+  const target = option(parsed, 'target', 'geaos')
+  const outputFile = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'apps', 'app-launcher', 'generated', 'LauncherCatalog.tsx')))
+  const apps = generateLauncherCatalog({ repoRoot: ctx.projectRoot, apps: discoverApps(ctx), target, outputFile })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputFile, apps: apps.map((app) => appSummary(ctx, app)) }, null, 2) : outputFile)
+  return 0
+}
+
+async function icons(ctx, parsed, args, options) {
+  const requested = args[0] || option(parsed, 'app', '')
+  if (!requested) fail('gea apps icons <app-id|all> [--target <t>] [--model <m>] [--concurrency <n>] [--exclude a,b]', ExitCode.usage)
+  const { generateIconSets } = await import('../apps/openai-icons.mjs')
+  const excluded = new Set(optionList(parsed, 'exclude'))
+  const iconTarget = option(parsed, 'target', '')
+  const all = discoverApps(ctx)
+  const apps = requested === 'all'
+    ? all
+      .filter((app) => iconTarget && iconTarget !== 'all'
+        ? app.targets?.[iconTarget] === true
+        : ['geaos', 'esp32', 'ios', 'macos'].some((candidate) => app.targets?.[candidate] === true))
+      .filter((app) => !excluded.has(app.id))
+    : [resolveRequestedApp(ctx, parsed, [requested])]
+  await generateIconSets({
+    repoRoot: ctx.projectRoot,
+    apps,
+    model: option(parsed, 'model', ctx.env.GEA_OPENAI_IMAGE_MODEL || 'gpt-image-2'),
+    concurrency: Math.max(1, Number.parseInt(option(parsed, 'concurrency', '1'), 10) || 1)
+  })
+  return 0
+}
+
+// The Apple build scripts call this per app: the iOS generator wants an
+// AppIcon.appiconset inside its asset catalog, the macOS bundle wants an
+// AppIcon.icns in Resources. --signature prints a digest of every input the
+// icon depends on so the scripts can skip regeneration when nothing changed.
+async function appleIcons(ctx, parsed, args, options) {
+  const usage = 'gea apps apple-icons <app-id> --platform ios --assets-dir <dir> | --platform macos --build-dir <dir> --resources-dir <dir> [--signature]'
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const platform = option(parsed, 'platform', '')
+  if (platform !== 'ios' && platform !== 'macos') fail(usage, ExitCode.usage)
+  const icons = await import('../apps/apple-icons.mjs')
+  const repoRoot = ctx.projectRoot
+  if (flag(parsed, 'signature')) {
+    const { createHash } = await import('node:crypto')
+    const { readFileSync } = await import('node:fs')
+    const hash = createHash('sha256')
+    const addFile = (file) => {
+      hash.update(file)
+      hash.update('\0')
+      hash.update(readFileSync(file))
+      hash.update('\0')
+    }
+    addFile(path.join(ctx.cliPackageRoot, 'src', 'apps', 'apple-icons.mjs'))
+    hash.update(JSON.stringify({ id: app.id, root: appSummary(ctx, app).root, icons: app.icons || {}, platform }))
+    addFile(icons.resolveAppleIconSourcePath(repoRoot, app))
+    options.stdout(hash.digest('hex'))
+    return 0
+  }
+  if (platform === 'ios') {
+    const assetsDir = option(parsed, 'assets-dir', '')
+    if (!assetsDir) fail(usage, ExitCode.usage)
+    options.stdout(icons.prepareIosAppIconAssets({ repoRoot, app, assetsDir: path.resolve(ctx.cwd, assetsDir) }))
+    return 0
+  }
+  const buildDir = option(parsed, 'build-dir', '')
+  const resourcesDir = option(parsed, 'resources-dir', '')
+  if (!buildDir || !resourcesDir) fail(usage, ExitCode.usage)
+  options.stdout(icons.prepareMacosAppIcon({ repoRoot, app, buildDir: path.resolve(ctx.cwd, buildDir), resourcesDir: path.resolve(ctx.cwd, resourcesDir) }))
+  return 0
+}
+
+async function iconSheet(ctx, parsed, options) {
+  const { generateIconStyleSheet } = await import('../apps/openai-icons.mjs')
+  const excluded = new Set(optionList(parsed, 'exclude'))
+  const iconTarget = option(parsed, 'target', 'geaos')
+  const outputPath = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'docs', 'icon-style-preview', `${iconTarget}-icon-style-sheet.png`)))
+  const apps = discoverApps(ctx)
+    .filter((app) => iconTarget === 'all' || app.targets?.[iconTarget] === true)
+    .filter((app) => flag(parsed, 'include-hidden') || !app.launcher.hidden)
+    .filter((app) => app.icons && Object.keys(app.icons).length > 0)
+    .filter((app) => !excluded.has(app.id))
+  if (apps.length === 0) fail(`No apps matched target '${iconTarget}'`, ExitCode.usage)
+  const sheet = await generateIconStyleSheet({
+    apps,
+    model: option(parsed, 'model', ctx.env.GEA_OPENAI_IMAGE_MODEL || 'gpt-image-2'),
+    outputPath,
+    columns: Math.max(1, Number.parseInt(option(parsed, 'columns', '5'), 10) || 5)
+  })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputPath: sheet.outputPath, apps: apps.map((app) => appSummary(ctx, app)) }, null, 2) : sheet.outputPath)
+  return 0
+}
+
+// gea boards ... / gea targets ...
+
+export async function boardsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  const boards = normalizeBoardConfig(loadBoardConfig(ctx))
+  if (sub === 'list') {
+    if (flag(parsed, 'json')) options.stdout(JSON.stringify(boards, null, 2))
+    else {
+      const names = Object.keys(boards).sort()
+      if (names.length === 0) options.stdout(`No boards configured in ${boardConfigPath(ctx)}. Run gea setup, or gea boards add.`)
+      for (const name of names) {
+        const board = boards[name]
+        const bits = [board.target]
+        if (board.transports?.usbSerial?.serial) bits.push(`usb ${board.transports.usbSerial.serial}`)
+        if (board.transports?.ota?.host) bits.push(`wifi ${board.transports.ota.host}`)
+        options.stdout(`${name}\t${bits.join('  ')}`)
+      }
+    }
+    return 0
+  }
+  if (sub === 'show') {
+    const name = rest[1] || option(parsed, 'board', '')
+    if (!name || !boards[name]) fail(`Unknown board '${name}'. Run gea boards list.`, ExitCode.usage)
+    options.stdout(JSON.stringify({ [name]: boards[name] }, null, 2))
+    return 0
+  }
+  if (sub === 'add') {
+    const { runSetupWizard } = await import('../setup-wizard.mjs')
+    return runSetupWizard(ctx, parsed, options)
+  }
+  fail(`Unknown boards subcommand '${sub}'. Expected list, show, or add.`, ExitCode.usage)
+}
+
+export function targetsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  let targets
+  try {
+    targets = loadTargets(ctx)
+  } catch (error) {
+    fail(error.message, ExitCode.missingDependency)
+  }
+  if (sub === 'list') {
+    if (flag(parsed, 'json')) options.stdout(JSON.stringify(targets, null, 2))
+    else for (const id of Object.keys(targets).sort()) options.stdout(`${id}\t${targets[id].adapter}\t${exists(targets[id].targetDir) ? targets[id].targetDir : '(not installed)'}`)
+    return 0
+  }
+  if (sub === 'show') {
+    const id = rest[1] || ''
+    if (!targets[id]) fail(`Unknown target '${id}'. Run gea targets list.`, ExitCode.usage)
+    options.stdout(JSON.stringify(targets[id], null, 2))
+    return 0
+  }
+  fail(`Unknown targets subcommand '${sub}'. Expected list or show.`, ExitCode.usage)
+}
+
+export async function heapReportCommand(ctx, parsed, rest, options) {
+  const { DEFAULT_TITLE, parseLogs, renderHtml } = await import('../heap-report.mjs')
+  const { mkdirSync, writeFileSync } = await import('node:fs')
+  let inputs = rest.map((file) => path.resolve(ctx.cwd, file))
+  const logsDir = path.join(ctx.projectRoot, 'docs', 'esp32-perf-logs')
+  if (inputs.length === 0 && exists(logsDir)) {
+    inputs = readdirSync(logsDir).filter((name) => /\.(txt|log)$/.test(name)).map((name) => path.join(logsDir, name))
+  }
+  if (inputs.length === 0) fail('No heap log inputs found. Pass log files or place .txt/.log files in docs/esp32-perf-logs/.', ExitCode.usage)
+  const out = path.resolve(ctx.cwd, option(parsed, 'out', path.join(logsDir, 'heap-map-report.html')))
+  const maps = optionList(parsed, 'map').map((file) => path.resolve(ctx.cwd, file))
+  const data = parseLogs(inputs, maps)
+  mkdirSync(path.dirname(out), { recursive: true })
+  writeFileSync(out, renderHtml(data, option(parsed, 'title', DEFAULT_TITLE)))
+  options.stdout(`Wrote heap map report: ${out}`)
+  options.stdout(`Parsed ${data.snapshots.length} heap-map snapshots, ${data.probes.length} probes, ${data.liveAllocations.length} live allocations, ${data.linkerMaps.length} linker map(s)`)
+  return 0
+}