@geastack/cli 0.1.53 → 0.1.55

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/esp32/idf-version.mjs

@@ -0,0 +1,89 @@
+// ESP-IDF target-version resolution.
+//
+// One pinned default in code, an env var / CLI option that overrides it
+// outright (pin an older release or try a release candidate), and a
+// best-effort GitHub "latest release" lookup used only when nothing
+// overrides the pin. The network call is injected (`fetchImpl`/`fetchLatest`)
+// so real usage hits GitHub while tests supply a fake and never touch the
+// network.
+
+const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/
+const VERSION_IN_TEXT = /v?(\d+)\.(\d+)\.(\d+)/i
+
+// The version GeaStack targets when nothing overrides it and the latest
+// release cannot be determined (offline, GitHub unreachable, rate limited).
+// Bump this alongside board-script updates.
+export const DEFAULT_ESP_IDF_VERSION = 'v6.0.2'
+
+const GITHUB_LATEST_RELEASE_URL = 'https://api.github.com/repos/espressif/esp-idf/releases/latest'
+
+// Parses a strict `vX.Y.Z` release tag. Returns null for anything else,
+// including release candidates and betas (`v6.1.0-rc1`), so callers can
+// filter those out of the "latest" lookup.
+export function parseStableIdfTag(value) {
+  const match = STABLE_TAG.exec(String(value || '').trim())
+  if (!match) return null
+  return { tag: match[0], major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) }
+}
+
+// Pulls a `major.minor(.patch)` out of free-form text such as
+// `idf.py --version`'s `ESP-IDF v6.0.2-dirty` output.
+export function extractIdfVersionFromText(text) {
+  const match = VERSION_IN_TEXT.exec(String(text || ''))
+  if (!match) return null
+  return { majorMinor: `${match[1]}.${match[2]}`, full: `${match[1]}.${match[2]}.${match[3]}` }
+}
+
+// Best-effort lookup of the latest stable ESP-IDF release tag from GitHub.
+// Never throws: returns '' when the request fails, times out (~4s default),
+// the machine is offline, or the latest release is not a stable vX.Y.Z tag.
+// `fetchImpl` defaults to the global fetch; tests inject a fake instead of
+// touching the network.
+export async function fetchLatestEspIdfVersion({ fetchImpl = globalThis.fetch, timeoutMs = 4000, log = () => {} } = {}) {
+  if (typeof fetchImpl !== 'function') return ''
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(GITHUB_LATEST_RELEASE_URL, {
+      signal: controller.signal,
+      headers: { Accept: 'application/vnd.github+json' }
+    })
+    if (!response?.ok) return ''
+    const body = await response.json()
+    return parseStableIdfTag(body?.tag_name)?.tag || ''
+  } catch (error) {
+    log(`Could not determine the latest ESP-IDF release (${error.message}); using ${DEFAULT_ESP_IDF_VERSION}.`)
+    return ''
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// Resolves the ESP-IDF version tag to install/verify against, in order:
+//   1. `override` (--idf-version) or GEA_ESP_IDF_VERSION -- explicit pin or
+//      a release candidate to test; used as-is (not required to be stable).
+//   2. the latest stable GitHub release, when `fetchLatest` can determine one.
+//   3. DEFAULT_ESP_IDF_VERSION.
+export async function resolveEspIdfVersion({ override, env = process.env, fetchLatest = fetchLatestEspIdfVersion, log = () => {} } = {}) {
+  const requested = override || env.GEA_ESP_IDF_VERSION
+  if (requested) return requested.startsWith('v') ? requested : `v${requested}`
+  const latest = await fetchLatest({ log })
+  return latest || DEFAULT_ESP_IDF_VERSION
+}
+
+// True when an installed ESP-IDF's version.cmake-derived version satisfies
+// the resolved target: same-or-newer major.minor. This is a floor, not an
+// exact-match: an installed 6.0.2 must not be rejected just because the
+// resolved target moved on to, say, 6.1.0 -- reinstalling isn't required
+// unless the installed major.minor genuinely trails the target's.
+// An unparsable target is treated as "anything installed is acceptable".
+export function idfVersionMeetsTarget(installedVersion, targetTag) {
+  const target = extractIdfVersionFromText(targetTag)
+  if (!target) return true
+  const [targetMajor, targetMinor] = target.majorMinor.split('.').map(Number)
+  const parts = String(installedVersion?.majorMinor || '').split('.').map(Number)
+  if (parts.length < 2 || parts.some((part) => Number.isNaN(part))) return false
+  const [installedMajor, installedMinor] = parts
+  if (installedMajor !== targetMajor) return installedMajor > targetMajor
+  return installedMinor >= targetMinor
+}

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,10 @@ 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;
+  // fetchEspIdfLatest likewise lets tests answer the setup wizard's ESP-IDF
+  // "latest release" lookup without touching the network.
+  const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice, fetchEspIdfLatest: io.fetchEspIdfLatest }
 
   // A platform name in --target (web, macos, ...) is not a board.
   const target = option(parsed, 'target', '')
@@ -137,10 +141,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: '' }))
   }
 }