@geastack/cli 0.1.53 → 0.1.55

package/README.md

@@ -60,7 +60,7 @@ flowchart TD
 flowchart TD
   setup["npx gea setup"] --> mode{"Mode?"}
 
-  mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.1"]
+  mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.2"]
   mode -->|"--board alias"| directBoard["Run target setup for board alias"]
   mode -->|"--target target-id"| directTarget["Run target setup directly"]
 
@@ -69,7 +69,7 @@ flowchart TD
   interactive -->|"Known supported board"| knownBoard["Pick board"]
   knownBoard --> alias["Set board alias"]
   alias --> serial["Detect serial devices"]
-  serial --> saveSerial["Save stable USB serial"]
+  serial --> saveSerial["Detect the USB serial (registry + GEADEV ping)"]
   saveSerial --> ota["Optional OTA host"]
   ota --> reviewKnown["Review board setup"]
   reviewKnown --> writeKnown["Write .gea/boards.json"]
@@ -83,7 +83,7 @@ flowchart TD
   writeProfile --> writeCustomAlias["Write alias to .gea/boards.json"]
 
   interactive -->|"npm dependencies only"| npmInstall["Run npm install when package.json exists"]
-  interactive -->|"ESP-IDF toolchain only"| idfOnly["Install or check ESP-IDF v6.0.1"]
+  interactive -->|"ESP-IDF toolchain only"| idfOnly["Install or check ESP-IDF v6.0.2"]
 
   writeKnown --> initialize["Initialize board target"]
   writeCustomAlias --> initialize
@@ -100,6 +100,18 @@ host bindings, and the other native packages from npm. A project can use a
 local CLI with `npx gea` or a global installation with `gea`; neither command
 depends on a GeaStack source checkout.
 
+Boards are managed without editing JSON by hand; aliases live in
+`~/.geastack/boards.json` (this machine) and the project's `.gea/boards.json`
+(overrides):
+
+```sh
+gea boards discover                    # which registered board is on which USB port, its app and IP
+gea boards list
+gea boards set amoled host 192.168.1.100
+gea boards rename amoled desk-amoled
+gea boards remove desk-amoled
+```
+
 Custom boards remain editable after setup:
 
 ```sh
@@ -169,4 +181,5 @@ First implementation is in place:
 - `list` and `inspect` helpers;
 - `create-geastack` with a bundled counter starter, a blank application, and a
   GitHub-backed rich example flow for web, embedded, GeaOS, iOS, macOS, and Android apps,
-  all with `.gea/boards.json`.
+  all with `.gea/boards.json`, plus `gea boards` for machine-wide aliases in
+  `~/.geastack/boards.json`.

package/docs/ESP32-WAVESHARE-AMOLED-QUICKSTART.md

@@ -90,7 +90,7 @@ You do not need to run that before every command unless `gea doctor` says ESP-ID
 
 If the wizard finds a connected serial device, pick it. If no board is plugged in yet, that is fine; you can provide the port later.
 
-The wizard writes the board config into your app at `.gea/boards.json` and initializes the selected board target.
+The wizard writes the board alias into your app's `.gea/boards.json` (or `~/.geastack/boards.json` with `--global`, for every project on this machine) and initializes the selected board target.
 
 ## 4. Flash
 
@@ -134,4 +134,4 @@ Most first-run issues are one of:
 - ESP-IDF is not activated in the current shell.
 - The USB cable is power-only.
 - The serial port needs to be passed with `--port`.
-- The board alias does not match the name in `.gea/boards.json`.
+- The board alias does not match a name in `npx gea boards list` (`~/.geastack/boards.json` plus the app's `.gea/boards.json`). `npx gea boards discover` shows which registered board each USB port is.

package/docs/NPX-COMMANDS.md

@@ -93,8 +93,11 @@ packages are scoped and configured for restricted npmjs publication.
 - npm dependency check/install only;
 - ESP-IDF toolchain check/install only.
 
-Known-board setup detects attached serial devices, asks for a stable USB serial,
-shows a review screen, writes a board alias into the active boards config, then
+Known-board setup asks whether the board is plugged in, reads each USB
+device's serial from the OS and pings it (so a board is picked by the app it
+reports running, never by a `/dev` name), shows a review screen, writes a board alias into the active boards config
+(`--global` for `~/.geastack/boards.json`, `--local` for the project's
+`.gea/boards.json`; by default the project config when it exists), then
 initializes the selected board target so the next command can be
 `npx gea flash --board <alias> --monitor`. In generated apps, that config is:
 
@@ -138,5 +141,8 @@ ESP-IDF setup is available as:
 npx gea setup --esp-idf
 ```
 
-It installs or dry-runs ESP-IDF v6.0.1 with the ESP32, ESP32-S3, and ESP32-P4
-toolchains.
+It installs or dry-runs ESP-IDF with the ESP32, ESP32-S3, and ESP32-P4
+toolchains. The version is resolved dynamically: `--idf-version <tag>` or
+`GEA_ESP_IDF_VERSION` pins an exact release, otherwise GeaStack tries the
+latest stable ESP-IDF release on GitHub and falls back to its pinned default
+(currently v6.0.2) when that cannot be determined.

package/docs/SETUP.md

@@ -34,8 +34,8 @@ For ESP32 hardware:
 - Node.js 20.19 or newer.
 - npm.
 - Python 3.
-- ESP-IDF v6.0.1.
-- `.gea/boards.json` configured for your board.
+- ESP-IDF v6.0.2 (GeaStack's pinned default; see ESP-IDF For ESP32 Targets below).
+- a board alias for your board (`~/.geastack/boards.json` or the project's `.gea/boards.json`, see Board Configuration).
 
 For the Waveshare ESP32-S3 AMOLED board, use
 [ESP32-WAVESHARE-AMOLED-QUICKSTART.md](ESP32-WAVESHARE-AMOLED-QUICKSTART.md).
@@ -69,9 +69,21 @@ npm --version
 
 ## ESP-IDF For ESP32 Targets
 
-The embedded board scripts currently target ESP-IDF v6.0.1. Newer ESP-IDF
-6.0.x releases may work, but v6.0.1 is the known target until the board scripts
-are updated.
+The embedded board scripts target ESP-IDF v6.0.2 by default. GeaStack resolves
+the version it installs or verifies dynamically, in this order:
+
+1. `--idf-version <tag>` (e.g. `npx gea setup --esp-idf --idf-version v6.1.0-rc1`)
+   to pin an exact release or try a release candidate.
+2. `GEA_ESP_IDF_VERSION` (same shape) when no `--idf-version` is given.
+3. The latest stable ESP-IDF release on GitHub, when it can be determined
+   (release candidates and betas are ignored).
+4. The pinned default, v6.0.2, when nothing above applies (offline, GitHub
+   unreachable, etc).
+
+Verifying an existing install accepts any installed version whose
+major.minor is the same as or newer than the resolved target -- an installed
+6.0.2 is never rejected just because the resolved target moved on to, say,
+6.1.0, unless it genuinely trails it.
 
 Command-line install:
 
@@ -84,7 +96,7 @@ Equivalent manual install:
 ```sh
 mkdir -p "$HOME/esp"
 cd "$HOME/esp"
-git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git
+git clone -b v6.0.2 --recursive https://github.com/espressif/esp-idf.git
 cd esp-idf
 ./install.sh esp32,esp32s3,esp32p4
 . ./export.sh
@@ -106,7 +118,7 @@ export GEA_EMBEDDED_IDF_EXPORT="/path/to/esp-idf/export.sh"
 ```
 
 The board script also checks common locations such as `$HOME/esp/esp-idf`,
-`$HOME/esp32/esp-idf`, and `$HOME/esp32/esp-idf-v6.0.1`.
+`$HOME/esp32/esp-idf`, and `$HOME/esp32/esp-idf-v6.0.2`.
 
 Verify through GeaStack:
 
@@ -224,9 +236,44 @@ manager or from python.org.
 
 ## Board Configuration
 
-Board aliases are project-local machine configuration. `create-geastack`
-creates an empty `.gea/boards.json`, and `npx gea setup` writes aliases there.
-Example:
+A board alias names one physical unit: `gea flash --board amoled` resolves
+`amoled` to a target, a USB serial and, optionally, an IP. Aliases are
+machine-local configuration and never come from a package. The CLI merges two
+files, project over home:
+
+| file | holds | written by |
+| --- | --- | --- |
+| `~/.geastack/boards.json` | every board on this machine (`GEA_HOME` relocates the directory) | `gea boards add --global`, `gea boards set` |
+| `<project>/.gea/boards.json` | aliases specific to one application; overrides a home alias of the same name | `create-geastack` (empty), `gea boards add` |
+
+`--boards-config <file>` (or `GEA_BOARDS_CONFIG`) replaces both with exactly
+that file. By default `gea boards add` writes to the project config when the
+project has one and to the home config otherwise; an existing alias is always
+edited where it lives.
+
+```sh
+npx gea boards discover                 # what is plugged in: alias, app, IP
+npx gea boards add                      # register a board (guided)
+npx gea boards list                     # every alias and which file it lives in
+npx gea boards set amoled host 192.168.1.100
+npx gea boards rename amoled desk-amoled
+npx gea boards remove desk-amoled
+npx gea doctor
+```
+
+`gea boards discover` sends one `GEADEV PING` to each serial device without
+resetting it; a board running gea firmware answers with its app id, its IP
+(when it has joined WiFi) and its MAC, and the CLI pairs the reply with an
+alias by USB serial. `--save` writes a reported IP into
+`transports.ota.host`, which is what `gea ota`, `gea logs` and
+`gea screenshot` use over WiFi.
+
+### Entry shapes
+
+Every entry names a `target` (`gea targets list`) and its `adapter`, then the
+transports the board offers. The USB serial is the stable identity: on ESP32
+boards it is the station MAC, and the CLI resolves it to today's `/dev` port
+at call time, so never record a port path.
 
 ```json
 {
@@ -234,22 +281,53 @@ Example:
     "target": "esp32-s3-touch-amoled-2.06",
     "adapter": "esp32-idf",
     "transports": {
-      "usbSerial": {
-        "serial": "YOUR_BOARD_USB_SERIAL"
-      }
+      "usbSerial": { "serial": "80:B5:4E:DA:73:88" },
+      "ota": { "host": "192.168.1.100" }
+    }
+  },
+  "rotary": {
+    "target": "esp32-s3-elecrow-rotary-2.1",
+    "adapter": "esp32-idf",
+    "transports": {
+      "usbSerial": { "serial": "14:C1:9F:26:65:08", "restartAfterFlash": "manual" }
+    }
+  },
+  "tufty": {
+    "target": "rp2350-tufty-2350",
+    "adapter": "rp2350-pico",
+    "transports": { "usbSerial": { "serial": "fa59949adbb4802f" } }
+  },
+  "linux": {
+    "target": "geaos",
+    "adapter": "geaos-linux",
+    "transports": {
+      "telnet": { "host": "192.168.7.2", "port": 2323 },
+      "fastboot": { "serial": "geaos001" }
+    }
+  },
+  "lokmat": {
+    "target": "lokmat-applp2max",
+    "adapter": "geaos-arm64",
+    "transports": {
+      "usbSerial": { "serial": "geaos01" },
+      "fastboot": { "serial": "0123456789ABCDEF" },
+      "mtk": { "workdir": "~/lokmat-root" }
     }
+  },
+  "my-board": {
+    "target": "my-board",
+    "targetDefinition": "targets/my-board.json",
+    "adapter": "esp32-idf",
+    "transports": { "usbSerial": { "serial": "YOUR_BOARD_USB_SERIAL" } }
   }
 }
 ```
 
-Then check discovery:
-
-```sh
-npx gea setup
-npx gea list boards
-npx gea list targets
-npx gea doctor
-```
+- `restartAfterFlash: "manual"` marks a board whose USB-Serial-JTAG port
+  re-enters ROM download mode after a flash; the CLI stops and asks for a
+  power cycle instead of pulsing the reset lines.
+- `targetDefinition` points at a custom target composed by `gea setup` /
+  `gea chips`, relative to the file the alias lives in.
 
 ## Common Verification Flow
 

package/docs/SPEC.md

@@ -83,9 +83,12 @@ gea flash --app bouncing-balls-jsx --board amoled --monitor
 gea flash --app css-3d-cube --target android
 ```
 
-The CLI should pass through board aliases from the active board config. A project
-uses its own `.gea/boards.json`; otherwise the CLI reads the board catalog shipped
-by the installed `@geastack/targets` package.
+The CLI resolves board aliases from two machine-local files merged project over
+home: `~/.geastack/boards.json` (every board on the machine, `GEA_HOME`
+relocates it) and the project's `.gea/boards.json`. `--boards-config` replaces
+both. No package ships aliases. `gea boards` manages them: `list`, `show`,
+`add`, `set <alias> <key> <value>`, `remove`, `rename`, and `discover`, which
+identifies connected boards over USB (`GEADEV PING` reports app, IP and MAC).
 
 ### `gea chips`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/cli",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "type": "module",
   "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
   "publishConfig": {

package/src/boards/config.mjs

@@ -1,19 +1,70 @@
+import os from 'node:os'
 import path from 'node:path'
 
 import { ExitCode, fail } from '../errors.mjs'
-import { exists, readJson } from '../fs-utils.mjs'
+import { exists, readJson, writeJson } from '../fs-utils.mjs'
 
-// Board aliases: an explicit --boards-config, else the project's
-// .gea/boards.json, else the boards.json shipped by @geastack/targets.
+// Board aliases are machine-local configuration: which physical board answers
+// to `--board amoled`, its USB serial, its IP. They live in two tiers that
+// are merged, project over home:
+//
+//   ~/.geastack/boards.json   every board on this machine (GEA_HOME overrides
+//                             the directory)
+//   <project>/.gea/boards.json aliases specific to one project, overriding a
+//                             home alias of the same name
+//
+// An explicit --boards-config (or GEA_BOARDS_CONFIG) replaces both tiers: a
+// caller naming a file wants exactly that file. Nothing is ever read from an
+// installed package -- a board catalog shipped in @geastack/targets was a
+// development convenience that described one developer's bench, and every
+// npm install would have to overwrite it.
+
+export function homeBoardsConfigPath(env = process.env) {
+  const home = env.GEA_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.geastack')
+  return path.join(home, 'boards.json')
+}
+
+// Every file that contributes aliases, lowest precedence first. The list is
+// the same whether or not the files exist so writers can target a tier that
+// has not been created yet.
+export function boardConfigTiers(ctx) {
+  if (ctx.boardsConfig) return [{ scope: 'explicit', file: ctx.boardsConfig }]
+  const tiers = []
+  if (ctx.homeBoardsConfig) tiers.push({ scope: 'home', file: ctx.homeBoardsConfig })
+  if (ctx.projectBoardsConfig) tiers.push({ scope: 'project', file: ctx.projectBoardsConfig })
+  return tiers
+}
+
+// The single path older callers print or check: the explicit file, else the
+// highest-precedence tier that exists, else where `gea boards add` would
+// write (project when the project already has a config, else home).
 export function boardConfigPath(ctx) {
+  const tiers = boardConfigTiers(ctx)
+  const existing = [...tiers].reverse().find((tier) => exists(tier.file))
+  return existing ? existing.file : boardConfigWritePath(ctx)
+}
+
+// Where a write goes when the caller does not say: `--global` / `--local`
+// pick a tier, an alias that already exists is edited in place, a new alias
+// joins the project config if the project has one and the home config
+// otherwise.
+export function boardConfigWritePath(ctx, { scope = '', alias = '' } = {}) {
+  const tiers = boardConfigTiers(ctx)
   if (ctx.boardsConfig) return ctx.boardsConfig
-  if (ctx.projectBoardsConfig && exists(ctx.projectBoardsConfig)) return ctx.projectBoardsConfig
-  return ctx.targetsRoot ? path.join(ctx.targetsRoot, 'boards.json') : ''
+  if (scope === 'global' || scope === 'home') return ctx.homeBoardsConfig
+  if (scope === 'project') return ctx.projectBoardsConfig
+  if (scope) fail(`Unknown board config scope '${scope}'. Expected --global or --local.`, ExitCode.usage)
+  if (alias) {
+    const origin = boardConfigOrigins(ctx).get(alias)
+    if (origin) return origin
+  }
+  const project = tiers.find((tier) => tier.scope === 'project')
+  if (project && exists(project.file)) return project.file
+  return ctx.homeBoardsConfig || project?.file || path.join(ctx.cwd || process.cwd(), '.gea', 'boards.json')
 }
 
-export function loadBoardConfig(ctx) {
-  const file = boardConfigPath(ctx)
-  if (!file || !exists(file)) return {}
+function readTier(file) {
+  if (!exists(file)) return {}
   try {
     return normalizeBoardConfig(readJson(file))
   } catch (error) {
@@ -21,6 +72,37 @@ export function loadBoardConfig(ctx) {
   }
 }
 
+// Merged aliases plus, for each, the file it came from: a `targetDefinition`
+// is relative to its own file, and `gea boards list` says which tier an alias
+// lives in.
+export function loadBoardConfigWithOrigins(ctx) {
+  const boards = {}
+  const origins = new Map()
+  for (const tier of boardConfigTiers(ctx)) {
+    for (const [alias, board] of Object.entries(readTier(tier.file))) {
+      boards[alias] = board
+      origins.set(alias, tier.file)
+    }
+  }
+  return { boards, origins }
+}
+
+export function loadBoardConfig(ctx) {
+  return loadBoardConfigWithOrigins(ctx).boards
+}
+
+export function boardConfigOrigins(ctx) {
+  return loadBoardConfigWithOrigins(ctx).origins
+}
+
+export function readBoardConfigFile(file) {
+  return readTier(file)
+}
+
+export function writeBoardConfigFile(file, boards) {
+  writeJson(file, boards)
+}
+
 export function normalizeBoardConfig(raw) {
   if (!raw || typeof raw !== 'object') return {}
   if (raw.boards && typeof raw.boards === 'object') return raw.boards

package/src/boards/resolve.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 
-import { loadBoardConfig, normalizeBoardConfig } from './config.mjs'
+import { boardConfigOrigins, boardConfigPath, loadBoardConfig, normalizeBoardConfig } from './config.mjs'
 import { loadTargets } from './targets.mjs'
 import { resolveUsbSerialPort } from './usb.mjs'
 
@@ -30,14 +30,16 @@ export function resolveBoardSelection({
   needs = {},
   targets = ctx ? loadTargets(ctx) : {},
   config = ctx ? loadBoardConfig(ctx) : {},
-  configDir = ctx ? (ctx.boardsConfig ? path.dirname(ctx.boardsConfig) : path.dirname(ctx.projectBoardsConfig)) : process.cwd(),
+  // A targetDefinition is relative to the file its alias came from, which
+  // differs between the home and project tiers.
+  configDir = ctx ? path.dirname((boardName && boardConfigOrigins(ctx).get(boardName)) || boardConfigPath(ctx)) : 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.`)
+    throw new Error(`Unknown board '${boardName}'. Run gea boards list, or gea boards add to register it.`)
   }
 
   let target = board?.target || targetName || ''

package/src/boards/usb.mjs

@@ -113,6 +113,47 @@ function macUsbCalloutPortsForSerial(serial, ioreg = runIoreg) {
   return [...matches].sort()
 }
 
+// Every USB callout port the registry knows, with the serial and product
+// name inherited from the enclosing USB device: the inverse of
+// macUsbCalloutPortsForSerial, for `gea boards discover` and the setup
+// wizard. The /dev name carries no identity (the usbmodem number changes on
+// every enumeration and identical boards share it), so this is the only
+// place a port's serial can come from on macOS.
+export function listMacUsbCalloutPorts(ioreg = runIoreg) {
+  let output = ''
+  try {
+    output = ioreg(['-p', 'IOService', '-l', '-w0'], { maxBuffer: 64 * 1024 * 1024 })
+  } catch {
+    return []
+  }
+  const stack = []
+  const ports = new Map()
+  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: '', product: '' })
+      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 productValue = ioregStringProperty(line, 'kUSBProductString') || ioregStringProperty(line, 'USB Product Name')
+    if (productValue) current.product = productValue
+    const callout = ioregStringProperty(line, 'IOCalloutDevice')
+    if (!callout || !path.basename(callout).startsWith('cu.')) continue
+    // A callout with no USB serial above it is not a USB device at all
+    // (Bluetooth SPP, the debug console); probing those is a wasted timeout.
+    const serial = [...stack].reverse().find((entry) => entry.serial)?.serial || ''
+    if (!serial) continue
+    const label = [...stack].reverse().find((entry) => entry.product)?.product || ''
+    ports.set(callout, { path: callout, serial, label })
+  }
+  return [...ports.values()].sort((a, b) => a.path.localeCompare(b.path))
+}
+
 function runIoreg(args, options = {}) {
   return execFileSync('ioreg', args, { encoding: 'utf8', ...options })
 }

package/src/chips.mjs

@@ -142,7 +142,7 @@ export function resolveTargetDefinition(ctx, parsed) {
   const configPath = option(parsed, 'boards-config')
     ? path.resolve(ctx.cwd, option(parsed, 'boards-config'))
     : ctx.projectBoardsConfig
-  if (!configPath || !exists(configPath)) fail('No project .gea/boards.json was found. Run gea setup and create a custom board first.', ExitCode.usage)
+  if (!configPath || !exists(configPath)) fail(`No board config was found at ${configPath || '.gea/boards.json'}. Run gea setup and create a custom board first.`, ExitCode.usage)
   const boards = readJson(configPath)
   const requested = option(parsed, 'board', '')
   const customBoards = Object.entries(boards).filter(([, entry]) => typeof entry?.targetDefinition === 'string' && entry.targetDefinition)

package/src/commands/apps.mjs

@@ -2,7 +2,6 @@ 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'
@@ -161,38 +160,7 @@ async function iconSheet(ctx, parsed, options) {
   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)
-}
+// gea targets ...
 
 export function targetsCommand(ctx, parsed, rest, options) {
   const sub = rest[0] || 'list'

package/src/commands/board.mjs

@@ -11,7 +11,7 @@ import { eraseSlot, flashFirmware, flashImageSet, flashOptions, postFlashRestart
 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 { assertTargetEnabled, assertValidApp, discoverApps, resolveRequestedApp, targetEnabledForApp } from '../manifest.mjs'
 import { buildRp2350, flashRp2350, rp2350BuildDir } from '../rp2350/adapter.mjs'
 import { runTargetHook } from '../taurus/adapter.mjs'
 
@@ -69,9 +69,22 @@ function io(parsed, options) {
 
 // ---- build ------------------------------------------------------------------
 
+// Firmware is built per app and the ESP32/RP2350 CMake refuses to configure
+// without one (its script-mode pass would otherwise analyze a directory), so
+// those adapters need an app even for --configure-only; the geaos and taurus
+// adapters have app-less actions.
+const appRequiredAdapters = new Set(['esp32-idf', 'rp2350-pico'])
+
+function requireAppForAdapter(ctx, parsed, selection, app) {
+  if (app || !appRequiredAdapters.has(selection.adapter)) return app
+  const candidates = discoverApps(ctx).filter((candidate) => targetEnabledForApp(ctx, candidate, selection.boardName || selection.target))
+  const hint = candidates.length > 0 ? `apps targeting '${selection.boardName || selection.target}': ${candidates.map((candidate) => candidate.id).join(', ')}` : `no app in ${ctx.projectRoot} targets '${selection.boardName || selection.target}' yet`
+  fail(`Board '${selection.boardName || selection.target}' builds one app at a time: pass --app <id> or run inside the app folder (${hint}).`, ExitCode.usage)
+}
+
 export async function buildCommand(ctx, parsed, rest, options) {
   const selection = selectBoard(ctx, parsed)
-  const app = optionalApp(ctx, parsed, rest, selection)
+  const app = requireAppForAdapter(ctx, parsed, selection, optionalApp(ctx, parsed, rest, selection))
   const base = io(parsed, options)
   const env = createChildEnv(ctx, base.env)
   switch (selection.adapter) {