@geastack/cli 0.1.52 → 0.1.54

package/src/commands/boards.mjs

@@ -0,0 +1,334 @@
+import { flag, option } from '../args.mjs'
+import {
+  boardConfigOrigins,
+  boardConfigPath,
+  boardConfigTiers,
+  boardConfigWritePath,
+  loadBoardConfigWithOrigins,
+  readBoardConfigFile,
+  writeBoardConfigFile
+} from '../boards/config.mjs'
+import { normalizedSerial } from '../boards/usb.mjs'
+import { SerialDevice, geadev } from '../device/serial.mjs'
+import { ExitCode, fail } from '../errors.mjs'
+import { exists } from '../fs-utils.mjs'
+import { detectSerialDevices } from '../serial-devices.mjs'
+
+export const boardsUsage = `gea boards <subcommand> [--global | --local]
+
+  list [--json]                         every alias, with the file it lives in
+  show <alias> [--json]
+  add                                   register a board (guided; gea setup)
+  set <alias> <key> <value>             edit one field; an empty value removes it
+  remove <alias>
+  rename <alias> <new-alias>
+  discover [--json] [--save]            identify the boards plugged in over USB
+
+Keys for set: host (transports.ota.host), serial (transports.usbSerial.serial),
+restart (transports.usbSerial.restartAfterFlash), target, adapter, or any
+dotted path such as transports.telnet.port.
+
+Aliases are read from ~/.geastack/boards.json (every board on this machine)
+and the project's .gea/boards.json (project overrides), or only from
+--boards-config when given. --global / --local choose where a write goes
+(the machine-wide file or the project's); by default an existing alias is
+edited where it lives and a new one joins the project config when the project
+has one.`
+
+const keyShorthands = {
+  host: 'transports.ota.host',
+  ip: 'transports.ota.host',
+  serial: 'transports.usbSerial.serial',
+  usb: 'transports.usbSerial.serial',
+  restart: 'transports.usbSerial.restartAfterFlash',
+  restartAfterFlash: 'transports.usbSerial.restartAfterFlash'
+}
+
+// --project is already the global "project directory" option, so the
+// project tier is selected with --local.
+function writeScope(parsed) {
+  if (flag(parsed, 'global') && flag(parsed, 'local')) fail('Pass either --global or --local, not both.', ExitCode.usage)
+  return flag(parsed, 'global') ? 'global' : flag(parsed, 'local') ? 'project' : ''
+}
+
+function tierLabel(ctx, file) {
+  const tier = boardConfigTiers(ctx).find((candidate) => candidate.file === file)
+  return tier ? tier.scope : file
+}
+
+function requireAlias(boards, alias, verb) {
+  if (!alias) fail(`gea boards ${verb} needs a board alias.\n${boardsUsage}`, ExitCode.usage)
+  if (!boards[alias]) fail(`Unknown board '${alias}'. Run gea boards list.`, ExitCode.usage)
+}
+
+export function boardSummaryLine(alias, board, scope = '') {
+  const bits = [board.target || '(no 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}`)
+  if (board.transports?.telnet?.host) bits.push(`telnet ${board.transports.telnet.host}`)
+  if (scope) bits.push(`[${scope}]`)
+  return `${alias}\t${bits.join('  ')}`
+}
+
+// A value typed on the command line: numbers and booleans become JSON
+// values (transports.telnet.port is a number), everything else stays a
+// string. IPs, MAC-style serials and hostnames never parse as JSON.
+export function parseFieldValue(raw) {
+  if (raw === '' || raw === undefined) return undefined
+  if (/^(true|false|null|-?\d+(\.\d+)?)$/.test(raw) || /^[[{]/.test(raw)) {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return raw
+    }
+  }
+  return raw
+}
+
+export function setFieldPath(board, keyPath, value) {
+  const segments = keyPath.split('.').filter(Boolean)
+  if (segments.length === 0) fail('The key to set is empty.', ExitCode.usage)
+  let cursor = board
+  for (const segment of segments.slice(0, -1)) {
+    if (cursor[segment] === undefined || cursor[segment] === null || typeof cursor[segment] !== 'object') {
+      if (value === undefined) return board
+      cursor[segment] = {}
+    }
+    cursor = cursor[segment]
+  }
+  const last = segments[segments.length - 1]
+  if (value === undefined) delete cursor[last]
+  else cursor[last] = value
+  pruneEmptyObjects(board)
+  return board
+}
+
+function pruneEmptyObjects(value) {
+  for (const [key, child] of Object.entries(value)) {
+    if (child && typeof child === 'object' && !Array.isArray(child)) {
+      pruneEmptyObjects(child)
+      if (Object.keys(child).length === 0 && key !== 'transports') delete value[key]
+    }
+  }
+}
+
+function updateBoardFile(file, mutate) {
+  const boards = readBoardConfigFile(file)
+  const next = mutate(boards)
+  writeBoardConfigFile(file, next)
+  return next
+}
+
+// ---- discover -----------------------------------------------------------------
+
+// Asks a serial device who it is with one GEADEV PING. A board that is mid
+// boot, running a firmware without device control, or not a gea board at
+// all answers nothing and is reported as such; nothing here resets the port
+// (SerialDevice.open never touches DTR/RTS).
+export async function probeSerialDevice(device, { baudRate = 115200, timeoutMs = 1500, env = process.env } = {}) {
+  let serial = null
+  try {
+    serial = await SerialDevice.open({ path: device.path, baudRate: Number(env.GEA_SERIAL_BAUD) || baudRate })
+    await serial.drainInput(60, 200)
+    const reply = await serial.command('GEADEV PING', ['GEADEV:PONG'], timeoutMs)
+    const values = parsePong(reply)
+    return { ok: true, ...values }
+  } catch (error) {
+    return { ok: false, error: error.message }
+  } finally {
+    if (serial) await serial.close().catch(() => {})
+  }
+}
+
+export function parsePong(reply) {
+  const values = {}
+  for (const token of String(reply).split(/\s+/).slice(1)) {
+    const eq = token.indexOf('=')
+    if (eq > 0) values[token.slice(0, eq)] = token.slice(eq + 1)
+  }
+  return {
+    app: values.app || '',
+    ip: values.ip && values.ip !== '0.0.0.0' ? values.ip : '',
+    mac: values.mac || ''
+  }
+}
+
+// Pure: pairs detected serial devices with configured aliases by USB serial
+// (the MAC on ESP32 boards, so a PONG's mac= confirms the same thing), and
+// records what each device answered.
+export async function discoverBoards({ devices, boards, probe }) {
+  const results = []
+  for (const device of devices) {
+    const probed = await probe(device)
+    const serials = [device.serial, probed.mac].map(normalizedSerial).filter(Boolean)
+    const alias = Object.keys(boards).find((name) => {
+      const configured = normalizedSerial(boards[name]?.transports?.usbSerial?.serial)
+      return configured && serials.includes(configured)
+    })
+    results.push({
+      path: device.path,
+      label: device.label || '',
+      serial: device.serial || probed.mac || '',
+      alias: alias || '',
+      target: alias ? boards[alias].target || '' : '',
+      configuredHost: alias ? boards[alias].transports?.ota?.host || '' : '',
+      responds: probed.ok,
+      app: probed.app || '',
+      ip: probed.ip || '',
+      mac: probed.mac || '',
+      error: probed.ok ? '' : probed.error || ''
+    })
+  }
+  return results
+}
+
+export function formatDiscovery(result) {
+  const who = result.alias ? `${result.alias} (${result.target})` : 'not configured'
+  const bits = [result.path, who]
+  if (result.serial) bits.push(`serial ${result.serial}`)
+  if (result.responds) {
+    bits.push(result.app ? `app ${result.app}` : 'app ?')
+    bits.push(result.ip ? `ip ${result.ip}` : 'no ip')
+  } else {
+    bits.push('no GEADEV reply')
+  }
+  return bits.join('  ')
+}
+
+// ---- command --------------------------------------------------------------------
+
+export async function boardsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  const json = flag(parsed, 'json')
+  const { boards, origins } = loadBoardConfigWithOrigins(ctx)
+
+  if (sub === 'help') {
+    options.stdout(boardsUsage)
+    return 0
+  }
+
+  if (sub === 'list') {
+    const names = Object.keys(boards).sort()
+    if (json) {
+      options.stdout(JSON.stringify(boards, null, 2))
+      return 0
+    }
+    if (names.length === 0) {
+      const tiers = boardConfigTiers(ctx).map((tier) => `${tier.file}${exists(tier.file) ? '' : ' (missing)'}`)
+      options.stdout(`No boards configured. Looked in:\n  ${tiers.join('\n  ')}\nRun gea boards add, or gea boards discover to see what is plugged in.`)
+      return 0
+    }
+    for (const name of names) options.stdout(boardSummaryLine(name, boards[name], tierLabel(ctx, origins.get(name))))
+    return 0
+  }
+
+  if (sub === 'show') {
+    const name = rest[1] || option(parsed, 'board', '')
+    requireAlias(boards, name, 'show')
+    if (json) options.stdout(JSON.stringify({ [name]: boards[name] }, null, 2))
+    else {
+      options.stdout(`${name}: ${origins.get(name)}`)
+      options.stdout(JSON.stringify(boards[name], null, 2))
+    }
+    return 0
+  }
+
+  if (sub === 'add') {
+    const { runSetupWizard } = await import('../setup-wizard.mjs')
+    return runSetupWizard(ctx, parsed, options)
+  }
+
+  if (sub === 'set') {
+    const [, name, key, ...valueParts] = rest
+    requireAlias(boards, name, 'set')
+    if (!key) fail(`gea boards set needs a key and a value.\n${boardsUsage}`, ExitCode.usage)
+    const keyPath = keyShorthands[key] || key
+    const value = parseFieldValue(valueParts.join(' '))
+    const file = boardConfigWritePath(ctx, { scope: writeScope(parsed), alias: name })
+    const scope = writeScope(parsed)
+    updateBoardFile(file, (current) => {
+      // Moving an alias between tiers with --global/--project copies the
+      // merged entry so the edit lands on a complete board, not a fragment.
+      const base = current[name] ?? structuredClone(boards[name])
+      current[name] = setFieldPath(base, keyPath, value)
+      return current
+    })
+    if (scope && origins.get(name) && origins.get(name) !== file) {
+      options.stderr(`Note: '${name}' also exists in ${origins.get(name)}; the project entry is the one commands see.`)
+    }
+    options.stdout(value === undefined ? `Removed ${keyPath} from '${name}' in ${file}` : `Set ${keyPath}=${JSON.stringify(value)} on '${name}' in ${file}`)
+    return 0
+  }
+
+  if (sub === 'remove' || sub === 'rm' || sub === 'delete') {
+    const name = rest[1]
+    requireAlias(boards, name, 'remove')
+    const scope = writeScope(parsed)
+    const files = scope ? [boardConfigWritePath(ctx, { scope })] : boardConfigTiers(ctx).map((tier) => tier.file)
+    let removedFrom = []
+    for (const file of files) {
+      if (!exists(file)) continue
+      const current = readBoardConfigFile(file)
+      if (!current[name]) continue
+      delete current[name]
+      writeBoardConfigFile(file, current)
+      removedFrom.push(file)
+    }
+    if (removedFrom.length === 0) fail(`'${name}' is not defined in ${files.join(' or ')}.`, ExitCode.usage)
+    options.stdout(`Removed '${name}' from ${removedFrom.join(', ')}`)
+    return 0
+  }
+
+  if (sub === 'rename' || sub === 'mv') {
+    const [, from, to] = rest
+    requireAlias(boards, from, 'rename')
+    if (!to || !/^[a-z0-9][a-z0-9._-]*$/i.test(to)) fail(`gea boards rename needs a new alias made of letters, digits, dots, dashes or underscores.`, ExitCode.usage)
+    if (boards[to]) fail(`A board named '${to}' already exists. Remove it first.`, ExitCode.usage)
+    const file = boardConfigWritePath(ctx, { scope: writeScope(parsed), alias: from })
+    updateBoardFile(file, (current) => {
+      const entry = current[from] ?? structuredClone(boards[from])
+      delete current[from]
+      current[to] = entry
+      return current
+    })
+    options.stdout(`Renamed '${from}' to '${to}' in ${file}`)
+    return 0
+  }
+
+  if (sub === 'discover' || sub === 'scan') {
+    const devices = detectSerialDevices({ env: options.env || ctx.env || process.env })
+    const timeoutMs = Number(option(parsed, 'timeout', '1500')) || 1500
+    const probe = options.probeSerialDevice || ((device) => probeSerialDevice(device, { timeoutMs, env: options.env || ctx.env || process.env }))
+    const results = await discoverBoards({ devices, boards, probe: flag(parsed, 'no-probe') ? async () => ({ ok: false, error: 'not probed' }) : probe })
+    if (json) {
+      options.stdout(JSON.stringify(results, null, 2))
+    } else if (results.length === 0) {
+      options.stdout('No serial devices detected. Plug a board in over USB and retry.')
+    } else {
+      for (const result of results) options.stdout(formatDiscovery(result))
+      const unconfigured = results.filter((result) => !result.alias && result.serial)
+      for (const result of unconfigured) {
+        options.stdout(`  -> register it: gea boards add   (USB serial ${result.serial}${result.app ? `, running ${result.app}` : ''})`)
+      }
+      for (const result of results.filter((entry) => entry.alias && entry.ip && entry.ip !== entry.configuredHost)) {
+        options.stdout(`  -> '${result.alias}' is at ${result.ip}${result.configuredHost ? ` (config says ${result.configuredHost})` : ''}: gea boards set ${result.alias} host ${result.ip}, or rerun with --save`)
+      }
+    }
+    if (flag(parsed, 'save')) {
+      for (const result of results.filter((entry) => entry.alias && entry.ip && entry.ip !== entry.configuredHost)) {
+        const file = boardConfigWritePath(ctx, { scope: writeScope(parsed), alias: result.alias })
+        updateBoardFile(file, (current) => {
+          const base = current[result.alias] ?? structuredClone(boards[result.alias])
+          current[result.alias] = setFieldPath(base, 'transports.ota.host', result.ip)
+          return current
+        })
+        options.stdout(`Saved transports.ota.host=${result.ip} for '${result.alias}' in ${file}`)
+      }
+    }
+    return 0
+  }
+
+  fail(`Unknown boards subcommand '${sub}'.\n${boardsUsage}`, ExitCode.usage)
+}
+
+export { boardConfigPath, boardConfigOrigins }

package/src/commands/doctor.mjs

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+import { flag } from '../args.mjs'
+import { boardConfigPath, boardConfigTiers, loadBoardConfig } from '../boards/config.mjs'
+import { ExitCode } from '../errors.mjs'
+import { findEspIdf, findIdfPythonEnv } from '../esp32/idf-env.mjs'
+import { exists } from '../fs-utils.mjs'
+import { discoverApps, resolveRequestedApp, validateApp } from '../manifest.mjs'
+import { commandVersion, nodeAtLeast } from '../toolchain.mjs'
+
+function packageExists(dir) {
+  return Boolean(dir) && exists(path.join(dir, 'package.json'))
+}
+
+function onPath(name, env) {
+  return String(env.PATH || '').split(path.delimiter).some((dir) => dir && existsSync(path.join(dir, name)))
+}
+
+async function serialportAvailable() {
+  try {
+    await import('serialport')
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function doctorCommand(ctx, parsed, rest, options) {
+  const env = options.env || process.env
+  const checks = []
+  const add = (name, ok, detail, required) => checks.push({ name, ok: Boolean(ok), detail: String(detail ?? ''), required })
+
+  add('project root', exists(ctx.projectRoot), ctx.projectRoot, true)
+  add('Node >= 20.19', nodeAtLeast(20, 19), process.version, true)
+  add('@geastack/targets', packageExists(ctx.targetsRoot), ctx.targetsRoot || 'not installed in this project', true)
+  add('@geastack/core', packageExists(ctx.corePackageDir), ctx.corePackageDir || 'not installed', true)
+  add('@geastack/compiler', packageExists(ctx.compilerPackageDir), ctx.compilerPackageDir || 'not installed', true)
+  add('@geastack/geatsc-plugin-gea', packageExists(ctx.pluginPackageDir), ctx.pluginPackageDir || 'not installed', true)
+  for (const [name, dir] of [['@geastack/chips', ctx.chipsPackageDir], ['@geastack/engine', ctx.enginePackageDir], ['@geastack/host', ctx.hostPackageDir], ['@geastack/elements', ctx.elementsPackageDir], ['@geastack/geaos', ctx.geaosPackageDir]]) {
+    add(name, packageExists(dir), dir || 'not installed', false)
+  }
+  add('serialport (USB device access)', await serialportAvailable(), 'npm package', false)
+
+  const idfDir = findEspIdf(env)
+  const pythonEnv = idfDir ? findIdfPythonEnv(idfDir, env) : ''
+  add('ESP-IDF', Boolean(idfDir), idfDir || 'not found (set IDF_PATH)', false)
+  add('ESP-IDF python env', Boolean(pythonEnv), pythonEnv || 'run install.sh in ESP-IDF', false)
+  add('cmake', onPath('cmake', env) || Boolean(pythonEnv), commandVersion('cmake', ['--version'], env).split('\n')[0] || 'from ESP-IDF tools', false)
+  add('ninja', onPath('ninja', env), onPath('ninja', env) ? 'on PATH' : 'optional; Unix Makefiles used otherwise', false)
+  add('ccache', onPath('ccache', env), onPath('ccache', env) ? 'on PATH' : 'optional', false)
+  add('arm-none-eabi-gcc (RP2350)', onPath('arm-none-eabi-gcc', env) || Boolean(env.PICO_TOOLCHAIN_PATH), env.PICO_TOOLCHAIN_PATH || 'optional', false)
+  add('picotool (RP2350)', onPath('picotool', env), onPath('picotool', env) ? 'on PATH' : 'optional', false)
+  add('swift (BLE OTA)', onPath('swift', env), onPath('swift', env) ? 'on PATH' : 'optional; macOS only', false)
+
+  const boardFiles = boardConfigTiers(ctx).filter((tier) => exists(tier.file)).map((tier) => tier.file)
+  try {
+    const boards = boardFiles.length ? loadBoardConfig(ctx) : {}
+    add('boards.json', true, boardFiles.length ? `${boardFiles.join(', ')} (${Object.keys(boards).length} board(s))` : `not configured (gea boards add; looked for ${boardConfigPath(ctx)})`, false)
+  } catch (error) {
+    add('boards.json', false, error.message, true)
+  }
+
+  const apps = discoverApps(ctx)
+  add('app catalog', apps.length > 0, `${apps.length} app(s)`, true)
+  let currentApp = null
+  try {
+    currentApp = resolveRequestedApp(ctx, parsed, [])
+  } catch {
+    currentApp = null
+  }
+  if (currentApp) {
+    const errors = validateApp(currentApp)
+    add(`app manifest (${currentApp.id})`, errors.length === 0, errors.length === 0 ? currentApp.root : errors.join('; '), true)
+  }
+
+  const failedRequired = checks.filter((check) => check.required && !check.ok)
+  const failedOptional = checks.filter((check) => !check.required && !check.ok)
+  if (flag(parsed, 'json')) {
+    options.stdout(JSON.stringify({ ok: failedRequired.length === 0, checks }, null, 2))
+  } else {
+    for (const check of checks) {
+      const marker = check.ok ? '[ok]' : check.required ? '[fail]' : '[warn]'
+      options.stdout(`${marker} ${check.name}: ${check.detail}`)
+    }
+    if (failedRequired.length > 0 || failedOptional.length > 0) options.stdout('Setup guide: cli/docs/SETUP.md')
+  }
+  if (failedRequired.length > 0) return ExitCode.missingDependency
+  if (failedOptional.length > 0 && flag(parsed, 'strict')) return ExitCode.missingDependency
+  return 0
+}

package/src/context.mjs

@@ -1,65 +1,72 @@
 import path from 'node:path'
-import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 
 import { option } from './args.mjs'
+import { homeBoardsConfigPath } from './boards/config.mjs'
 import { exists, findUp } from './fs-utils.mjs'
 
 const srcDir = path.dirname(fileURLToPath(import.meta.url))
 export const cliPackageRoot = path.resolve(srcDir, '..')
-const requireFromCli = createRequire(import.meta.url)
+export const cliBin = path.join(cliPackageRoot, 'bin', 'gea.mjs')
 
-export function createContext(parsed, _env = process.env, cwd = process.cwd()) {
+// Every @geastack package the CLI reads. They are sources and data (IDF
+// projects, chip catalogs, C++ trees, the compiler) and they belong to the
+// USER'S project: the CLI resolves them from the project's node_modules the
+// way node itself would, never from its own install. The CLI has no @geastack
+// dependencies of its own, so availability of a command is simply "is that
+// package installed here".
+const geastackPackages = Object.freeze({
+  targetsRoot: { name: '@geastack/targets', env: 'GEA_TARGETS_ROOT' },
+  corePackageDir: { name: '@geastack/core', env: 'GEA_CORE_DIR' },
+  compilerPackageDir: { name: '@geastack/compiler', env: 'GEA_COMPILER_DIR' },
+  chipsPackageDir: { name: '@geastack/chips', env: 'GEA_CHIPS_DIR' },
+  elementsPackageDir: { name: '@geastack/elements', env: 'GEA_ELEMENTS_DIR' },
+  enginePackageDir: { name: '@geastack/engine', env: 'GEA_ENGINE_DIR' },
+  geaosPackageDir: { name: '@geastack/geaos', env: 'GEA_GEAOS_PACKAGE_DIR' },
+  hostPackageDir: { name: '@geastack/host', env: 'GEA_HOST_DIR' },
+  pluginPackageDir: { name: '@geastack/geatsc-plugin-gea', env: 'GEA_PLUGIN_DIR' }
+})
+
+export function createContext(parsed, env = process.env, cwd = process.cwd()) {
   const absoluteCwd = path.resolve(cwd)
-  const projectRoot = findNodeProjectRoot(absoluteCwd) || absoluteCwd
-  const initialAnchors = [projectRoot, cliPackageRoot]
-  const targetsRoot = _env.GEA_TARGETS_ROOT || resolveInstalledPackageDir('@geastack/targets', initialAnchors)
-  const corePackageDir = resolveInstalledPackageDir('@geastack/core', initialAnchors)
-  const packageAnchors = [projectRoot, cliPackageRoot, targetsRoot, corePackageDir].filter(Boolean)
-  const compilerPackageDir = resolveInstalledPackageDir('@geastack/compiler', packageAnchors)
+  const explicitProject = option(parsed, 'project') || env.GEA_PROJECT_ROOT || ''
+  const projectRoot = explicitProject ? path.resolve(absoluteCwd, explicitProject) : findNodeProjectRoot(absoluteCwd) || absoluteCwd
   const projectBoardsConfig = path.join(projectRoot, '.gea', 'boards.json')
-  const explicitBoardsConfig = option(parsed, 'boards-config') || ''
-  const boardsConfig = explicitBoardsConfig || (exists(projectBoardsConfig) ? projectBoardsConfig : '')
+  // Only an explicit file is `boardsConfig`; the project and home tiers are
+  // merged by src/boards/config.mjs, which also decides where a write goes.
+  const boardsConfig = option(parsed, 'boards-config') || env.GEA_BOARDS_CONFIG || ''
 
   const ctx = {
     cwd: absoluteCwd,
     projectRoot,
     projectBoardsConfig,
+    homeBoardsConfig: homeBoardsConfigPath(env),
     cliPackageRoot,
-    compilerPackageDir,
-    corePackageDir,
-    chipsPackageDir: _env.GEA_CHIPS_DIR || resolveInstalledPackageDir('@geastack/chips', packageAnchors),
-    elementsPackageDir: resolveInstalledPackageDir('@geastack/elements', packageAnchors),
-    enginePackageDir: resolveInstalledPackageDir('@geastack/engine', packageAnchors),
-    geaosPackageDir: resolveInstalledPackageDir('@geastack/geaos', packageAnchors),
-    hostPackageDir: resolveInstalledPackageDir('@geastack/host', packageAnchors),
-    pluginPackageDir: resolveInstalledPackageDir('@geastack/geatsc-plugin-gea', packageAnchors),
+    cliBin,
     boardsConfig: boardsConfig ? path.resolve(absoluteCwd, boardsConfig) : '',
-    examplesRoot: projectRoot,
-    simulatorRoot: '',
-    androidRoot: '',
-    appleRoot: '',
-    targetsRoot
+    // Generated state (IDF build directories, sdkconfigs, generated board
+    // headers) lives in the project, never inside an installed package.
+    buildRoot: env.GEA_PROJECT_BUILD_ROOT
+      ? path.resolve(absoluteCwd, env.GEA_PROJECT_BUILD_ROOT)
+      : path.join(projectRoot, '.gea', 'build'),
+    env
   }
-  ctx.scripts = {
-    board: packageFile(ctx.targetsRoot, 'scripts', 'board'),
-    webBuild: '',
-    webDev: '',
-    androidBuild: '',
-    macosBuild: '',
-    iosBuild: '',
-    geaEmbedded: packageFile(ctx.corePackageDir, 'bin', 'gea-embedded.mjs')
+  for (const [field, { name, env: envName }] of Object.entries(geastackPackages)) {
+    ctx[field] = env[envName] || resolveInstalledPackageDir(name, projectRoot)
   }
+  ctx.packageName = (field) => geastackPackages[field]?.name || field
   return ctx
 }
 
-export function createChildEnv(ctx, env = process.env) {
+// Environment handed to every build system the CLI drives (IDF/CMake, the
+// Pico SDK, the geaos scripts). They receive exact package paths and never
+// resolve anything themselves.
+export function createChildEnv(ctx, env = ctx.env || process.env) {
   const out = {
     ...env,
     GEA_APPS_ROOT: ctx.projectRoot,
-    GEA_CLI_BIN: path.join(ctx.cliPackageRoot, 'bin', 'gea.mjs'),
+    GEA_CLI_BIN: ctx.cliBin,
     GEA_CHIPS_DIR: ctx.chipsPackageDir,
-    GEA_CORE_PACKAGE: ctx.corePackageDir,
     GEA_CORE_DIR: ctx.corePackageDir,
     GEA_COMPILER_DIR: ctx.compilerPackageDir,
     GEA_ELEMENTS_DIR: ctx.elementsPackageDir,
@@ -77,28 +84,17 @@ export function createChildEnv(ctx, env = process.env) {
   return out
 }
 
-function resolveInstalledPackageDir(packageName, anchors) {
-  for (const anchor of anchors) {
-    let current = path.resolve(anchor)
-    while (true) {
-      const candidate = path.join(current, 'node_modules', ...packageName.split('/'))
-      if (exists(path.join(candidate, 'package.json'))) return candidate
-      const parent = path.dirname(current)
-      if (parent === current) break
-      current = parent
-    }
-  }
-  try {
-    return path.dirname(requireFromCli.resolve(`${packageName}/package.json`))
-  } catch {
-    return ''
+export function resolveInstalledPackageDir(packageName, anchor) {
+  let current = path.resolve(anchor)
+  while (true) {
+    const candidate = path.join(current, 'node_modules', ...packageName.split('/'))
+    if (exists(path.join(candidate, 'package.json'))) return candidate
+    const parent = path.dirname(current)
+    if (parent === current) return ''
+    current = parent
   }
 }
 
-function packageFile(packageRoot, ...segments) {
-  return packageRoot ? path.join(packageRoot, ...segments) : ''
-}
-
 function appendPathList(current, value) {
   const entries = String(current || '').split(path.delimiter).filter(Boolean)
   if (value && !entries.includes(value)) entries.push(value)

package/src/device/device.mjs

@@ -0,0 +1,96 @@
+import { waitForSerialPort } from '../boards/usb.mjs'
+import { ExitCode, fail } from '../errors.mjs'
+import { writeImage } from './image.mjs'
+import { SerialDevice, geadev, streamSerialMonitor } from './serial.mjs'
+import { fetchScreenshot, setHighBrightnessMode, tailLogs } from './wifi.mjs'
+
+// One handle for "the board", whichever cable (or no cable) reaches it. Logs
+// and screenshots are written once against this interface; the transport
+// decides how the bytes travel.
+
+export const transports = Object.freeze(['auto', 'usb', 'wifi', 'ble'])
+
+// 'auto' prefers WiFi whenever the board can be addressed by IP: that works
+// whether or not a cable is attached, and a dropped USB enumeration is the
+// exact situation where you most want to see the screen or the log.
+export function chooseTransport(requested, selection, { host = '' } = {}) {
+  const wanted = requested || 'auto'
+  if (!transports.includes(wanted)) fail(`--transport must be one of ${transports.join(', ')}.`, ExitCode.usage)
+  if (wanted === 'ble') fail('BLE device access is not available yet; use --transport usb or wifi.', ExitCode.usage)
+  if (wanted !== 'auto') return wanted
+  if (host || selection.otaHost) return 'wifi'
+  return 'usb'
+}
+
+export function serialBaudRate(selection, env = process.env) {
+  if (env.GEA_SERIAL_BAUD) return Number(env.GEA_SERIAL_BAUD)
+  return (selection.idfTarget || '') === 'esp32p4' ? 921600 : 115200
+}
+
+export async function openDevice({ selection, transport, host = '', port = '', env = process.env, trace = false, stderr = () => {}, waitSeconds = 0 }) {
+  if (transport === 'wifi') {
+    const address = host || selection.otaHost
+    if (!address) fail(`Board '${selection.boardName || selection.target}' has no transports.ota.host and no --host was passed.`, ExitCode.usage)
+    return new WifiDevice(address, { stderr })
+  }
+  if (!selection.usbSerial && !port) {
+    fail(`Board '${selection.boardName || selection.target}' has no transports.usbSerial.serial; use --transport wifi or add the USB serial.`, ExitCode.usage)
+  }
+  const devicePath = await waitForSerialPort({ port, serial: selection.usbSerial, timeoutSeconds: waitSeconds, label: 'USB serial port', log: stderr })
+  const serial = await SerialDevice.open({ path: devicePath, baudRate: serialBaudRate(selection, env), trace, stderr })
+  return new UsbDevice(serial, { stderr })
+}
+
+export class WifiDevice {
+  constructor(host, { stderr }) {
+    this.kind = 'wifi'
+    this.host = host
+    this.stderr = stderr
+    this.description = `${host} (WiFi)`
+  }
+
+  async logs({ follow = false, write, timeoutMs, signal }) {
+    await tailLogs({ host: this.host, follow, timeoutMs, write, stderr: this.stderr, signal })
+  }
+
+  async screenshot() {
+    return fetchScreenshot({ host: this.host })
+  }
+
+  async hbm(enabled) {
+    return setHighBrightnessMode({ host: this.host, enabled })
+  }
+
+  async close() {}
+}
+
+export class UsbDevice {
+  constructor(serial, { stderr }) {
+    this.kind = 'usb'
+    this.serial = serial
+    this.stderr = stderr
+    this.description = `${serial.path} (USB)`
+  }
+
+  async logs({ write, timestamps = false, logFile = '', signal }) {
+    await streamSerialMonitor(this.serial, { write, timestamps, logFile, signal })
+  }
+
+  async screenshot(options = {}) {
+    return geadev.screenshot(this.serial, options)
+  }
+
+  async hbm() {
+    fail('High-brightness mode is toggled over WiFi (POST /display/hbm); use --transport wifi.', ExitCode.usage)
+  }
+
+  async close() {
+    await this.serial.close()
+  }
+}
+
+export async function saveScreenshot(device, file, options = {}) {
+  const shot = await device.screenshot(options)
+  writeImage(file, shot.width, shot.height, shot.rgb)
+  return shot
+}