@geastack/cli 0.1.53 → 0.1.54

package/README.md

@@ -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

@@ -94,7 +94,9 @@ packages are scoped and configured for restricted npmjs publication.
 - 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
+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:
 

package/docs/SETUP.md

@@ -35,7 +35,7 @@ For ESP32 hardware:
 - npm.
 - Python 3.
 - ESP-IDF v6.0.1.
-- `.gea/boards.json` configured for your board.
+- 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).
@@ -224,9 +224,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 +269,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.54",
   "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/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

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 
 import { flag } from '../args.mjs'
-import { boardConfigPath, loadBoardConfig } from '../boards/config.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'
@@ -53,10 +53,10 @@ export async function doctorCommand(ctx, parsed, rest, options) {
   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)
+  const boardFiles = boardConfigTiers(ctx).filter((tier) => exists(tier.file)).map((tier) => tier.file)
   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)
+    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)
   }

package/src/context.mjs

@@ -2,6 +2,7 @@ import path from 'node:path'
 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))
@@ -31,13 +32,15 @@ export function createContext(parsed, env = process.env, cwd = process.cwd()) {
   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,
     cliBin,
     boardsConfig: boardsConfig ? path.resolve(absoluteCwd, boardsConfig) : '',

package/src/gea.mjs

@@ -2,7 +2,8 @@ import fs from 'node:fs'
 
 import { flag, option, parseArgs } from './args.mjs'
 import { runChips } from './chips.mjs'
-import { appsCommand, boardsCommand, heapReportCommand, targetsCommand } from './commands/apps.mjs'
+import { appsCommand, heapReportCommand, targetsCommand } from './commands/apps.mjs'
+import { boardsCommand } from './commands/boards.mjs'
 import { buildCommand, cleanCommand, devctlCommand, flashCommand, geaosDeviceCommand, logsCommand, monitorCommand, otaCommand, screenshotCommand } from './commands/board.mjs'
 import { doctorCommand } from './commands/doctor.mjs'
 import { createContext } from './context.mjs'
@@ -42,7 +43,8 @@ export async function runGea(argv, io = {}) {
 
   const ctx = createContext(parsed, env, cwd)
   const rest = parsed.positionals.slice(1)
-  const options = { stdout, stderr, env, stdin, output, prompt }
+  // probeSerialDevice lets tests answer `gea boards discover` without a port.
+  const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice }
 
   // A platform name in --target (web, macos, ...) is not a board.
   const target = option(parsed, 'target', '')
@@ -137,10 +139,11 @@ Device access:
 
 Catalogs:
   gea apps list|inspect|pack|index|launcher|icons|icon-sheet|apple-icons
-  gea boards list|show <alias>|add
+  gea boards list|show|add|set|remove|rename|discover  (gea boards help)
   gea targets list|show <id>
   gea chips ...                                  custom board composition from the chip catalog
   gea heap-report [logs...] [--out file] [--map elf.map]
 
-Global options: --project <dir>  --boards-config <file>  --dry-run  --json`
+Global options: --project <dir>  --boards-config <file>  --global|--local (boards writes)  --dry-run  --json
+Board aliases: ~/.geastack/boards.json (this machine) + <project>/.gea/boards.json (overrides)`
 }

package/src/serial-devices.mjs

@@ -2,10 +2,16 @@ import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 
-export function detectSerialDevices({ env = process.env, platform = process.platform } = {}) {
+import { listMacUsbCalloutPorts } from './boards/usb.mjs'
+
+// Serial devices with, where the OS can tell, the USB serial that identifies
+// the board. A /dev name is never that identity -- `cu.usbmodem1101` is a
+// slot number that changes on every enumeration -- so a device whose serial
+// the registry does not know reports an empty one and the caller asks.
+export function detectSerialDevices({ env = process.env, platform = process.platform, ioreg = undefined } = {}) {
   if (env.GEA_SERIAL_DEVICES) return parseSerialDevices(env.GEA_SERIAL_DEVICES)
   if (platform === 'win32') return detectWindowsSerialDevices(env)
-  return detectUnixSerialDevices()
+  return detectUnixSerialDevices({ platform, ioreg })
 }
 
 export function formatSerialDevice(device) {
@@ -32,13 +38,28 @@ function parseSerialDevices(value) {
     .filter((device) => device.path)
 }
 
-function detectUnixSerialDevices() {
+function detectUnixSerialDevices({ platform, ioreg }) {
   const devices = new Map()
   addLinuxByIdDevices(devices)
-  addDevPatternDevices(devices)
+  addDevPatternDevices(devices, platform)
+  if (platform === 'darwin') mergeRegistryDevices(devices, ioreg ? listMacUsbCalloutPorts(ioreg) : listMacUsbCalloutPorts())
   return [...devices.values()].sort((a, b) => a.path.localeCompare(b.path))
 }
 
+// Overlays what the USB registry knows (serial, product name) on the ports
+// found under /dev, and adds callout ports /dev scanning did not match.
+export function mergeRegistryDevices(devices, registry) {
+  for (const entry of registry) {
+    const known = devices.get(entry.path)
+    devices.set(entry.path, normalizeDevice({
+      path: entry.path,
+      label: entry.label || known?.label || entry.path,
+      serial: entry.serial || known?.serial || ''
+    }))
+  }
+  return devices
+}
+
 function addLinuxByIdDevices(devices) {
   const byId = '/dev/serial/by-id'
   if (!isDirectory(byId)) return
@@ -52,27 +73,18 @@ function addLinuxByIdDevices(devices) {
   }
 }
 
-function addDevPatternDevices(devices) {
+// On macOS only the call-up (`cu.`) device is listed: `tty.` is the same
+// port waiting for carrier, and opening it blocks.
+function addDevPatternDevices(devices, platform) {
   const dev = '/dev'
   if (!isDirectory(dev)) return
-  const patterns = [
-    /^cu\.usbmodem/,
-    /^tty\.usbmodem/,
-    /^cu\.usbserial/,
-    /^tty\.usbserial/,
-    /^cu\.SLAB_USBtoUART/,
-    /^tty\.SLAB_USBtoUART/,
-    /^ttyACM/,
-    /^ttyUSB/
-  ]
+  const patterns = platform === 'darwin'
+    ? [/^cu\.usbmodem/, /^cu\.usbserial/, /^cu\.SLAB_USBtoUART/, /^cu\.wchusbserial/]
+    : [/^ttyACM/, /^ttyUSB/]
   for (const name of safeReaddir(dev)) {
     if (!patterns.some((pattern) => pattern.test(name))) continue
     const devicePath = path.join(dev, name)
-    devices.set(devicePath, normalizeDevice({
-      path: devicePath,
-      label: name,
-      serial: serialFromDeviceName(name)
-    }))
+    devices.set(devicePath, normalizeDevice({ path: devicePath, label: name, serial: '' }))
   }
 }
 

package/src/setup-wizard.mjs

@@ -3,6 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 
 import { knownBoards } from './board-catalog.mjs'
+import { boardConfigWritePath } from './boards/config.mjs'
 import { configureChipSelection, loadChipCatalog, validateGpioAssignments } from './chips.mjs'
 import { flag, option } from './args.mjs'
 import { ExitCode, fail } from './errors.mjs'
@@ -380,8 +381,7 @@ async function maybeInitializeBoardTarget(ctx, parsed, io, boardSetup) {
   io.stdout(`Initializing board target '${boardSetup.alias}'...`)
   const { buildCommand } = await import('./commands/board.mjs')
   const setupParsed = { ...parsed, options: { ...parsed.options, board: boardSetup.alias, 'configure-only': true } }
-  const reloaded = { ...ctx, boardsConfig: boardConfigPath(ctx, parsed) }
-  return buildCommand(reloaded, setupParsed, [], io)
+  return buildCommand(ctx, setupParsed, [], io)
 }
 
 async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false } = {}) {
@@ -464,10 +464,13 @@ async function selectUsbSerial(prompt, io, { message }) {
   })
 }
 
+// --global writes the alias to ~/.geastack/boards.json, --local to the
+// project's .gea/boards.json; otherwise the project config when it exists,
+// else the home one (src/boards/config.mjs owns that rule).
 function boardConfigPath(ctx, parsed) {
-  const explicit = option(parsed, 'boards-config') || ctx.boardsConfig
+  const explicit = option(parsed, 'boards-config')
   if (explicit) return path.resolve(ctx.cwd, explicit)
-  return ctx.projectBoardsConfig || path.join(ctx.cwd, '.gea', 'boards.json')
+  return boardConfigWritePath(ctx, { scope: flag(parsed, 'global') ? 'global' : flag(parsed, 'local') ? 'project' : '' })
 }
 
 function readBoardConfig(filePath) {