@geastack/cli 0.1.51 → 0.1.53

package/src/commands/board.mjs

@@ -0,0 +1,402 @@
+import path from 'node:path'
+
+import { flag, option, optionList } from '../args.mjs'
+import { resolveBoardSelection } from '../boards/resolve.mjs'
+import { createChildEnv } from '../context.mjs'
+import { chooseTransport, openDevice, saveScreenshot } from '../device/device.mjs'
+import { geadev } from '../device/serial.mjs'
+import { ExitCode, fail } from '../errors.mjs'
+import { buildEsp32Firmware, buildImages, esp32BuildDir, fullCleanEsp32, requireEspIdf } from '../esp32/build.mjs'
+import { eraseSlot, flashFirmware, flashImageSet, flashOptions, postFlashRestartNote, restoreBootMetadata, stageImage } from '../esp32/flash.mjs'
+import { bleOta, otaEraseSlot, otaFlash, otaStage, waitForReboot } from '../esp32/ota.mjs'
+import { manifestRequestsBleOta } from '../esp32/capabilities.mjs'
+import { runGeaos } from '../geaos/adapter.mjs'
+import { assertTargetEnabled, assertValidApp, resolveRequestedApp } from '../manifest.mjs'
+import { buildRp2350, flashRp2350, rp2350BuildDir } from '../rp2350/adapter.mjs'
+import { runTargetHook } from '../taurus/adapter.mjs'
+
+// Every board-facing command: resolve the alias, pick the adapter, run.
+
+export function selectBoard(ctx, parsed, needs = {}) {
+  const boardName = option(parsed, 'board', '')
+  const targetName = option(parsed, 'target', '')
+  if (!boardName && !targetName) fail('--board <alias> is required (see gea boards list).', ExitCode.usage)
+  try {
+    return resolveBoardSelection({
+      ctx,
+      boardName,
+      targetName,
+      requestedPort: option(parsed, 'port', ''),
+      requestedHost: option(parsed, 'host', ''),
+      needs,
+      deferUsbPort: true
+    })
+  } catch (error) {
+    fail(error.message, ExitCode.usage)
+  }
+}
+
+function optionalApp(ctx, parsed, rest, selection, { required = false } = {}) {
+  const requested = option(parsed, 'app') || rest[0]
+  let app = null
+  if (requested || required) {
+    app = resolveRequestedApp(ctx, parsed, rest)
+  } else {
+    try {
+      app = resolveRequestedApp(ctx, parsed, [])
+    } catch {
+      app = null
+    }
+  }
+  if (!app) return null
+  assertValidApp(app)
+  assertTargetEnabled(ctx, app, selection.boardName || selection.target)
+  return app
+}
+
+function bleOtaRequested(parsed, app, env) {
+  return option(parsed, 'transport') === 'ble' || env.GEA_EMBEDDED_BLE_OTA === '1' || manifestRequestsBleOta(app?.packageJson)
+}
+
+function io(parsed, options) {
+  return {
+    env: options.env,
+    dryRun: flag(parsed, 'dry-run'),
+    stdout: options.stdout,
+    stderr: options.stderr
+  }
+}
+
+// ---- build ------------------------------------------------------------------
+
+export async function buildCommand(ctx, parsed, rest, options) {
+  const selection = selectBoard(ctx, parsed)
+  const app = optionalApp(ctx, parsed, rest, selection)
+  const base = io(parsed, options)
+  const env = createChildEnv(ctx, base.env)
+  switch (selection.adapter) {
+    case 'esp32-idf': {
+      buildEsp32Firmware({ ctx, selection, app, env, bleOta: bleOtaRequested(parsed, app, env), dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr, configureOnly: flag(parsed, 'configure-only') })
+      return 0
+    }
+    case 'rp2350-pico':
+      buildRp2350({ ctx, selection, app, env, dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr, configureOnly: flag(parsed, 'configure-only') })
+      return 0
+    case 'geaos-linux':
+    case 'geaos-arm64':
+      return runGeaos({ ctx, selection, action: 'build', app, positionals: rest, env, dryRun: base.dryRun, stdout: base.stdout })
+    case 'taurus-s3':
+      return runTargetHook({ ctx, selection, action: 'build', app, env, dryRun: base.dryRun, stdout: base.stdout })
+    default:
+      fail(`Unknown adapter '${selection.adapter}' for target '${selection.target}'.`, ExitCode.usage)
+  }
+}
+
+export async function cleanCommand(ctx, parsed, rest, options) {
+  const selection = selectBoard(ctx, parsed)
+  const app = optionalApp(ctx, parsed, rest, selection)
+  const base = io(parsed, options)
+  if (selection.adapter === 'esp32-idf') {
+    fullCleanEsp32({ ctx, selection, app, env: base.env, stdout: base.stdout })
+    return 0
+  }
+  if (selection.adapter === 'rp2350-pico') {
+    const dir = rp2350BuildDir(ctx, selection)
+    base.stdout(`Removing build artifacts in ${dir}...`)
+    const { rmSync } = await import('node:fs')
+    rmSync(dir, { recursive: true, force: true })
+    return 0
+  }
+  fail(`'clean' is not supported for ${selection.adapter} boards.`, ExitCode.usage)
+}
+
+// ---- flash / run --------------------------------------------------------------
+
+async function flashEsp32(ctx, parsed, rest, options, selection, { monitor }) {
+  const base = io(parsed, options)
+  const env = createChildEnv(ctx, base.env)
+  const idf = requireEspIdf(env, base.stdout)
+  const flashEnv = idf.env
+  const opts = flashOptions(flashEnv, { manualBoot: flag(parsed, 'manual-boot'), noReset: option(parsed, 'reset') === false, baud: option(parsed, 'flash-baud', '') })
+  const common = { idf, selection, options: opts, port: selection.port, env: flashEnv, dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr }
+  const slotImages = optionList(parsed, 'slot-image')
+  const eraseSlotName = option(parsed, 'erase-slot', '')
+  const slot = option(parsed, 'slot', '')
+  const explicitImage = option(parsed, 'image', '')
+  const app = explicitImage && !option(parsed, 'app') && !rest[0] ? null : optionalApp(ctx, parsed, rest, selection, { required: !explicitImage && !slotImages.length && !eraseSlotName && !flag(parsed, 'restore-boot') })
+
+  const buildDir = esp32BuildDir(ctx, selection, app?.id, flashEnv)
+  const images = { ...buildImages(buildDir), buildDir }
+
+  if (eraseSlotName) {
+    await eraseSlot({ ...common, slot: eraseSlotName })
+    return 0
+  }
+  if (flag(parsed, 'restore-boot')) {
+    await restoreBootMetadata({ ...common, images })
+    return 0
+  }
+  if (slotImages.length) {
+    await flashImageSet({ ...common, images, slotImages })
+    postFlashRestartNote(selection, base.stderr)
+    return 0
+  }
+
+  let image = explicitImage ? path.resolve(ctx.cwd, explicitImage) : images.app
+  if (!explicitImage && !flag(parsed, 'no-build')) {
+    buildEsp32Firmware({ ctx, selection, app, env, bleOta: bleOtaRequested(parsed, app, env), dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr })
+  }
+  const appLabel = app?.id || 'prebuilt image'
+  if (slot) {
+    await stageImage({ ...common, image, slot, appLabel })
+    return 0
+  }
+  await flashFirmware({ ...common, images, appImage: image, appLabel })
+  if (!monitor) {
+    postFlashRestartNote(selection, base.stderr)
+    return 0
+  }
+  return monitorCommand(ctx, parsed, rest, options, selection)
+}
+
+export async function flashCommand(ctx, parsed, rest, options, { monitor = false } = {}) {
+  const selection = selectBoard(ctx, parsed, { usbPort: true })
+  const base = io(parsed, options)
+  const env = createChildEnv(ctx, base.env)
+  switch (selection.adapter) {
+    case 'esp32-idf':
+      return flashEsp32(ctx, parsed, rest, options, selection, { monitor })
+    case 'rp2350-pico': {
+      const app = optionalApp(ctx, parsed, rest, selection)
+      const { uf2 } = buildRp2350({ ctx, selection, app, env, dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr })
+      flashRp2350({ selection, uf2, env, dryRun: base.dryRun, stdout: base.stdout })
+      return monitor ? monitorCommand(ctx, parsed, rest, options, selection) : 0
+    }
+    case 'geaos-linux':
+    case 'geaos-arm64': {
+      const app = optionalApp(ctx, parsed, rest, selection)
+      return runGeaos({ ctx, selection, action: monitor ? 'flash-monitor' : 'flash', app, positionals: rest, env, dryRun: base.dryRun, stdout: base.stdout })
+    }
+    case 'taurus-s3': {
+      const app = optionalApp(ctx, parsed, rest, selection)
+      return runTargetHook({ ctx, selection, action: 'flash', app, env, dryRun: base.dryRun, stdout: base.stdout })
+    }
+    default:
+      fail(`Unknown adapter '${selection.adapter}' for target '${selection.target}'.`, ExitCode.usage)
+  }
+}
+
+// ---- ota ------------------------------------------------------------------------
+
+export async function otaCommand(ctx, parsed, rest, options) {
+  const transport = option(parsed, 'transport', 'wifi')
+  if (transport !== 'wifi' && transport !== 'ble') fail("--transport must be 'wifi' or 'ble'.", ExitCode.usage)
+  const selection = selectBoard(ctx, parsed, transport === 'wifi' ? { otaHost: true } : {})
+  if (selection.adapter !== 'esp32-idf') fail(`OTA is only available for ESP32 boards (board '${selection.boardName}' is ${selection.adapter}).`, ExitCode.usage)
+  const base = io(parsed, options)
+  const env = createChildEnv(ctx, base.env)
+  const slot = option(parsed, 'slot', '')
+  const eraseSlotName = option(parsed, 'erase-slot', '')
+  const explicitImage = option(parsed, 'image', '')
+
+  if (eraseSlotName) {
+    await otaEraseSlot({ selection, host: selection.host, slot: eraseSlotName, dryRun: base.dryRun, stdout: base.stdout })
+    return 0
+  }
+
+  const app = explicitImage && !option(parsed, 'app') && !rest[0] ? null : optionalApp(ctx, parsed, rest, selection, { required: !explicitImage })
+  let image = explicitImage ? path.resolve(ctx.cwd, explicitImage) : ''
+  if (!explicitImage) {
+    const prepared = flag(parsed, 'no-build')
+      ? { images: buildImages(esp32BuildDir(ctx, selection, app.id, env)) }
+      : buildEsp32Firmware({ ctx, selection, app, env, bleOta: transport === 'ble' || bleOtaRequested(parsed, app, env), dryRun: base.dryRun, stdout: base.stdout, stderr: base.stderr })
+    image = prepared.images.app
+  }
+
+  if (transport === 'ble') {
+    bleOta({ cliPackageRoot: ctx.cliPackageRoot, image, deviceName: option(parsed, 'device', ''), env, dryRun: base.dryRun, stdout: base.stdout })
+    return 0
+  }
+  if (slot) {
+    await otaStage({ selection, host: selection.host, image, slot, boot: flag(parsed, 'boot'), reboot: flag(parsed, 'reboot'), appLabel: app?.id || 'prebuilt image', dryRun: base.dryRun, stdout: base.stdout })
+    return 0
+  }
+  await otaFlash({ host: selection.host, image, dryRun: base.dryRun, stdout: base.stdout })
+  if (flag(parsed, 'monitor') || flag(parsed, 'logs')) {
+    if (base.dryRun) return 0
+    await waitForReboot({ host: selection.host, stdout: base.stdout })
+    return logsCommand(ctx, { ...parsed, options: { ...parsed.options, transport: 'wifi', follow: true } }, rest, options, selection)
+  }
+  return 0
+}
+
+// ---- monitor / logs / screenshot ---------------------------------------------
+
+function abortOnSigint() {
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once('SIGINT', onSigint)
+  return { signal: controller.signal, release: () => process.removeListener('SIGINT', onSigint) }
+}
+
+async function withDevice(ctx, parsed, options, selection, transport, fn) {
+  const base = io(parsed, options)
+  if (base.dryRun) {
+    base.stdout(`[dry-run] ${transport} device: ${transport === 'wifi' ? option(parsed, 'host', '') || selection.otaHost : selection.port || `usb serial ${selection.usbSerial}`}`)
+    return 0
+  }
+  const device = await openDevice({
+    selection,
+    transport,
+    host: option(parsed, 'host', ''),
+    port: selection.port,
+    env: base.env,
+    trace: flag(parsed, 'trace'),
+    stderr: base.stderr,
+    waitSeconds: Number(option(parsed, 'wait', base.env.GEA_ESP32_MONITOR_WAIT_SECONDS || 0))
+  })
+  try {
+    return (await fn(device, base)) ?? 0
+  } finally {
+    await device.close()
+  }
+}
+
+export async function monitorCommand(ctx, parsed, rest, options, preselected = null) {
+  const selection = preselected || selectBoard(ctx, parsed, { usbPort: true })
+  if (selection.adapter === 'geaos-linux' || selection.adapter === 'geaos-arm64') {
+    const base = io(parsed, options)
+    return runGeaos({ ctx, selection, action: 'monitor', positionals: rest, env: createChildEnv(ctx, base.env), dryRun: base.dryRun, stdout: base.stdout })
+  }
+  return withDevice(ctx, parsed, options, selection, 'usb', async (device, base) => {
+    base.stderr(`Opening serial monitor on ${device.description}... (Ctrl+C to exit)`)
+    const { signal, release } = abortOnSigint()
+    try {
+      await device.logs({ write: (line) => base.stdout(line), timestamps: flag(parsed, 'timestamps'), logFile: option(parsed, 'log-file', ''), signal })
+    } finally {
+      release()
+    }
+  })
+}
+
+export async function logsCommand(ctx, parsed, rest, options, preselected = null) {
+  const selection = preselected || selectBoard(ctx, parsed, {})
+  const transport = chooseTransport(option(parsed, 'transport', 'auto'), selection, { host: option(parsed, 'host', '') })
+  if (transport === 'usb') return monitorCommand(ctx, parsed, rest, options, preselected || selectBoard(ctx, parsed, { usbPort: true }))
+  return withDevice(ctx, parsed, options, selection, 'wifi', async (device, base) => {
+    const follow = flag(parsed, 'follow')
+    base.stderr(`Connecting to diagnostics stream at ${device.host}:8081${follow ? ' (Ctrl+C to exit)' : ''}`)
+    const { signal, release } = abortOnSigint()
+    try {
+      await device.logs({ follow, write: (chunk) => process.stdout.write(chunk), timeoutMs: Number(option(parsed, 'timeout', 10)) * 1000, signal })
+    } finally {
+      release()
+    }
+  })
+}
+
+export async function screenshotCommand(ctx, parsed, rest, options) {
+  const selection = selectBoard(ctx, parsed, {})
+  const transport = chooseTransport(option(parsed, 'transport', 'auto'), selection, { host: option(parsed, 'host', '') })
+  const file = path.resolve(ctx.cwd, rest[0] || option(parsed, 'out', '') || 'screenshot.png')
+  const usbSelection = transport === 'usb' ? selectBoard(ctx, parsed, { usbPort: true }) : selection
+  return withDevice(ctx, parsed, options, usbSelection, transport, async (device, base) => {
+    const timeoutMs = Number(option(parsed, 'timeout', transport === 'wifi' ? 30 : 12)) * 1000
+    const shot = await saveScreenshot(device, file, { timeoutMs, legacy: flag(parsed, 'legacy') })
+    base.stdout(`Saved ${shot.width}x${shot.height} screenshot${shot.app ? ` of ${shot.app}` : ''} from ${device.description} to ${file}`)
+  })
+}
+
+// ---- devctl -------------------------------------------------------------------------
+
+const devctlUsage = `gea devctl <verb> [args] --board <alias> [--transport auto|usb|wifi]
+
+Verbs (USB, GEADEV protocol):
+  ping | app | state | mem | summary | i2cscan | reboot
+  node <class>            hit <x> <y>            tap <x> <y> [holdMs]
+  drag <x1> <y1> <x2> <y2> [steps] [delayMs]      swipe <x> <y1> <y2>
+  back                    key <code>             notify <text>
+  storage get <key> | storage set <key> <value>
+  set-default <app-id>    set-time [epochSeconds]
+  brightness [0-100]      ls [path]              rm <path>
+  push <local> <remote> [--base64]               pull <remote> <local>
+  playfile <path>
+Verbs (WiFi):
+  hbm on|off              -- high-brightness mode (POST /display/hbm)`
+
+export async function devctlCommand(ctx, parsed, rest, options) {
+  const verb = rest[0]
+  const args = rest.slice(1)
+  if (!verb || verb === 'help') {
+    options.stdout(devctlUsage)
+    return verb ? 0 : ExitCode.usage
+  }
+  const selection = selectBoard(ctx, parsed, {})
+  const wifiVerbs = new Set(['hbm'])
+  const requested = option(parsed, 'transport', wifiVerbs.has(verb) ? 'wifi' : 'usb')
+  const transport = chooseTransport(requested, selection, { host: option(parsed, 'host', '') })
+  const usbSelection = transport === 'usb' ? selectBoard(ctx, parsed, { usbPort: true }) : selection
+  return withDevice(ctx, parsed, options, usbSelection, transport, async (device, base) => {
+    if (verb === 'hbm') {
+      const state = args[0]
+      if (!['on', 'off', '1', '0'].includes(state)) fail('devctl hbm expects on|off.', ExitCode.usage)
+      const reply = await device.hbm(state === 'on' || state === '1')
+      base.stdout(JSON.stringify(reply))
+      return 0
+    }
+    if (device.kind !== 'usb') fail(`devctl ${verb} needs the USB transport.`, ExitCode.usage)
+    const d = device.serial
+    const num = (value, name) => {
+      const n = Number(value)
+      if (!Number.isFinite(n)) fail(`devctl ${verb}: ${name} must be a number.`, ExitCode.usage)
+      return n
+    }
+    const need = (count) => {
+      if (args.length < count) fail(`devctl ${verb} needs ${count} argument(s).\n${devctlUsage}`, ExitCode.usage)
+    }
+    const print = (value) => base.stdout(String(value))
+    switch (verb) {
+      case 'ping': print(await geadev.ping(d)); break
+      case 'app': print(await geadev.app(d)); break
+      case 'state': print(await geadev.state(d)); break
+      case 'mem': print(await geadev.mem(d)); break
+      case 'summary': print(await geadev.summary(d)); break
+      case 'i2cscan': print(await geadev.i2cScan(d)); break
+      case 'reboot': print(await geadev.reboot(d)); break
+      case 'node': need(1); print(await geadev.node(d, args[0])); break
+      case 'hit': need(2); print(await geadev.hit(d, num(args[0], 'x'), num(args[1], 'y'))); break
+      case 'tap': need(2); print(await geadev.tap(d, num(args[0], 'x'), num(args[1], 'y'), args[2] ? num(args[2], 'holdMs') : 80)); break
+      case 'drag': need(4); print(await geadev.drag(d, num(args[0], 'x1'), num(args[1], 'y1'), num(args[2], 'x2'), num(args[3], 'y2'), args[4] ? num(args[4], 'steps') : 6, args[5] ? num(args[5], 'delayMs') : 24)); break
+      case 'swipe': need(3); print(await geadev.swipe(d, num(args[0], 'x'), num(args[1], 'y1'), num(args[2], 'y2'))); break
+      case 'back': print(await geadev.back(d)); break
+      case 'key': need(1); print(await geadev.key(d, args[0])); break
+      case 'notify': need(1); print(await geadev.notify(d, args.join(' '))); break
+      case 'storage':
+        need(2)
+        if (args[0] === 'get') print((await geadev.storageGet(d, args[1])).value)
+        else if (args[0] === 'set') { need(3); print(await geadev.storageSet(d, args[1], args.slice(2).join(' '))) }
+        else fail('devctl storage expects get <key> or set <key> <value>.', ExitCode.usage)
+        break
+      case 'set-default': need(1); print(await geadev.setDefault(d, args[0])); break
+      case 'set-time': print(await geadev.setTime(d, args[0] ? num(args[0], 'epoch') : Math.floor(Date.now() / 1000))); break
+      case 'brightness': print(await geadev.brightness(d, args[0] === undefined ? undefined : num(args[0], 'value'))); break
+      case 'ls': print(await geadev.ls(d, args[0] || '/sdcard')); break
+      case 'rm': need(1); print(await geadev.rm(d, args[0])); break
+      case 'push': need(2); print(await geadev.pushFile(d, path.resolve(ctx.cwd, args[0]), args[1], { base64: flag(parsed, 'base64'), stderr: base.stderr })); break
+      case 'pull': need(2); print(await geadev.pullFile(d, args[0], path.resolve(ctx.cwd, args[1]))); break
+      case 'playfile': need(1); print(await geadev.playFile(d, args[0])); break
+      default:
+        fail(`Unknown devctl verb '${verb}'.\n${devctlUsage}`, ExitCode.usage)
+    }
+    return 0
+  })
+}
+
+// ---- geaos device passthrough -------------------------------------------------
+
+export async function geaosDeviceCommand(ctx, parsed, rest, options) {
+  const selection = selectBoard(ctx, parsed, { usbPort: true })
+  if (selection.adapter !== 'geaos-linux' && selection.adapter !== 'geaos-arm64') fail(`'${rest[0]}' is a geaos device action; board '${selection.boardName}' is ${selection.adapter}.`, ExitCode.usage)
+  const base = io(parsed, options)
+  return runGeaos({ ctx, selection, action: rest[0], positionals: rest.slice(1), env: createChildEnv(ctx, base.env), dryRun: base.dryRun, stdout: base.stdout })
+}

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, 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 boardFile = boardConfigPath(ctx)
+  try {
+    const boards = exists(boardFile) ? loadBoardConfig(ctx) : {}
+    add('boards.json', true, exists(boardFile) ? `${boardFile} (${Object.keys(boards).length} board(s))` : 'not configured (gea setup)', 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,5 +1,4 @@
 import path from 'node:path'
-import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 
 import { option } from './args.mjs'
@@ -7,16 +6,30 @@ 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 : '')
@@ -26,40 +39,31 @@ export function createContext(parsed, _env = process.env, cwd = process.cwd()) {
     projectRoot,
     projectBoardsConfig,
     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 +81,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)