@geastack/cli 0.1.54 → 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

package/docs/NPX-COMMANDS.md

@@ -93,8 +93,9 @@ 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
+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
@@ -140,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,7 +34,7 @@ For ESP32 hardware:
 - Node.js 20.19 or newer.
 - npm.
 - Python 3.
-- ESP-IDF v6.0.1.
+- 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
@@ -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:
 

package/package.json

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

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) {

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

@@ -43,8 +43,10 @@ export async function runGea(argv, io = {}) {
 
   const ctx = createContext(parsed, env, cwd)
   const rest = parsed.positionals.slice(1)
-  // probeSerialDevice lets tests answer `gea boards discover` without a port.
-  const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice }
+  // 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', '')

package/src/setup-wizard.mjs

@@ -3,30 +3,34 @@ import os from 'node:os'
 import path from 'node:path'
 
 import { knownBoards } from './board-catalog.mjs'
-import { boardConfigWritePath } from './boards/config.mjs'
+import { boardConfigWritePath, loadBoardConfig } from './boards/config.mjs'
+import { discoverBoards, probeSerialDevice } from './commands/boards.mjs'
+import { discoverApps, resolveRequestedApp, targetEnabledForApp } from './manifest.mjs'
 import { configureChipSelection, loadChipCatalog, validateGpioAssignments } from './chips.mjs'
 import { flag, option } from './args.mjs'
 import { ExitCode, fail } from './errors.mjs'
+import { espIdfVersion as readInstalledEspIdfVersion, findEspIdf } from './esp32/idf-env.mjs'
+import { extractIdfVersionFromText, fetchLatestEspIdfVersion, idfVersionMeetsTarget, resolveEspIdfVersion } from './esp32/idf-version.mjs'
 import { exists, readJson, writeJson } from './fs-utils.mjs'
 import { ask, choose, confirm, createPrompt } from './prompts.mjs'
 import { runExternal } from './run.mjs'
-import { detectSerialDevices, formatSerialDevice } from './serial-devices.mjs'
+import { detectSerialDevices } from './serial-devices.mjs'
 import { commandVersion } from './toolchain.mjs'
 
-const espIdfVersion = 'v6.0.1'
 const espIdfInstallTargets = 'esp32,esp32s3,esp32p4'
 
 export async function runSetupWizard(ctx, parsed, io) {
   const stdout = io.stdout || console.log
   const prompt = createPrompt(io)
   try {
+    const targetIdfVersion = await resolveEspIdfVersionForWizard(parsed, io)
     renderHeader(io, 'GeaStack setup', [
       `Project: ${ctx.projectRoot}`,
       `Boards: ${boardConfigPath(ctx, parsed)}`
     ])
     if (option(parsed, 'esp-idf') === true) {
       renderStep(io, 'Toolchain', ['Checking ESP-IDF for ESP32 builds.'])
-      await maybeSetupEspIdf(ctx, parsed, io, prompt, { force: true })
+      await maybeSetupEspIdf(ctx, parsed, io, prompt, { force: true, targetVersion: targetIdfVersion })
       return 0
     }
     const mode = await choose(prompt, {
@@ -50,7 +54,7 @@ export async function runSetupWizard(ctx, parsed, io) {
         {
           value: 'esp-idf',
           label: 'Only install/check ESP-IDF toolchain',
-          description: `Installs or verifies ESP-IDF ${espIdfVersion}.`
+          description: `Installs or verifies ESP-IDF ${targetIdfVersion}.`
         }
       ],
       defaultValue: 'known'
@@ -64,7 +68,7 @@ export async function runSetupWizard(ctx, parsed, io) {
 
     if (mode === 'esp-idf') {
       renderStep(io, 'Toolchain', ['Checking ESP-IDF for ESP32 builds.'])
-      await maybeSetupEspIdf(ctx, parsed, io, prompt, { force: true })
+      await maybeSetupEspIdf(ctx, parsed, io, prompt, { force: true, targetVersion: targetIdfVersion })
       return 0
     }
 
@@ -77,11 +81,11 @@ export async function runSetupWizard(ctx, parsed, io) {
     }
 
     renderStep(io, 'Toolchain', ['Checking ESP-IDF before board initialization.'])
-    await maybeSetupEspIdf(ctx, parsed, io, prompt)
+    await maybeSetupEspIdf(ctx, parsed, io, prompt, { targetVersion: targetIdfVersion })
     if (option(parsed, 'install') === true) {
       await maybeInstallNpmDependencies(ctx, parsed, io, prompt, { force: true })
     }
-    await maybeInitializeBoardTarget(ctx, parsed, io, boardSetup)
+    await maybeInitializeBoardTarget(ctx, parsed, io, prompt, boardSetup)
     if (boardSetup?.flashReady) {
       stdout(`Ready: npx gea flash --board ${boardSetup.alias} --monitor`)
     } else {
@@ -114,8 +118,8 @@ async function setupKnownBoard(ctx, parsed, io, prompt) {
     validate: validateAlias
   })
   renderStep(io, 'Connection', ['Use a detected serial device, enter one manually, or skip it for now.'])
-  const serial = await selectUsbSerial(prompt, io, {
-    message: 'USB serial number (leave blank to pass --port manually)'
+  const serial = await selectUsbSerial(prompt, io, ctx, {
+    message: 'The USB serial identifies this board whatever port it lands on.'
   })
   const otaHost = await ask(prompt, {
     message: 'OTA host/IP (optional)',
@@ -231,8 +235,8 @@ async function setupCustomBoard(ctx, parsed, io, prompt) {
   }
 
   renderStep(io, 'Connection', ['The first flash uses USB. BLE OTA can take over after the initial firmware is running.'])
-  const usbSerial = await selectUsbSerial(prompt, io, {
-    message: 'USB serial number (leave blank to auto-detect or pass --port)'
+  const usbSerial = await selectUsbSerial(prompt, io, ctx, {
+    message: 'The USB serial identifies this board whatever port it lands on.'
   })
 
   const configPath = boardConfigPath(ctx, parsed)
@@ -368,32 +372,78 @@ async function maybeInstallNpmDependencies(ctx, parsed, io, prompt, { force = fa
   })
 }
 
-async function maybeInitializeBoardTarget(ctx, parsed, io, boardSetup) {
+// A board target is configured for one app (the firmware is built per app,
+// and its CMake refuses to run without one), so initialization needs an
+// app: the current one when the wizard runs inside an app, else the only
+// app in the project that targets this board, else the user's pick.
+async function maybeInitializeBoardTarget(ctx, parsed, io, prompt, boardSetup) {
   if (!boardSetup?.alias || !boardSetup.flashReady) return 0
   if (option(parsed, 'initialize') === false) {
-    io.stdout(`Board initialization skipped. Later: npx gea setup --board ${boardSetup.alias}`)
+    io.stdout(`Board initialization skipped. Later: npx gea setup --board ${boardSetup.alias} --app <id>`)
     return 0
   }
   if (!ctx.targetsRoot) {
-    io.stdout(`@geastack/targets is not installed. Later: npx gea setup --board ${boardSetup.alias}`)
+    io.stdout(`@geastack/targets is not installed. Later: npx gea setup --board ${boardSetup.alias} --app <id>`)
     return 0
   }
-  io.stdout(`Initializing board target '${boardSetup.alias}'...`)
+  const app = await chooseAppForBoard(ctx, parsed, io, prompt, boardSetup.alias)
+  if (!app) return 0
+  io.stdout(`Initializing board target '${boardSetup.alias}' for app '${app.id}'...`)
   const { buildCommand } = await import('./commands/board.mjs')
-  const setupParsed = { ...parsed, options: { ...parsed.options, board: boardSetup.alias, 'configure-only': true } }
+  const setupParsed = { ...parsed, options: { ...parsed.options, board: boardSetup.alias, app: app.id, 'configure-only': true } }
   return buildCommand(ctx, setupParsed, [], io)
 }
 
-async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false } = {}) {
+async function chooseAppForBoard(ctx, parsed, io, prompt, alias) {
+  let current = null
+  try {
+    current = resolveRequestedApp(ctx, parsed, [])
+  } catch {
+    current = null
+  }
+  if (current && targetEnabledForApp(ctx, current, alias)) return current
+  const candidates = discoverApps(ctx).filter((app) => targetEnabledForApp(ctx, app, alias))
+  if (candidates.length === 0) {
+    io.stdout(`No app in ${ctx.projectRoot} targets '${alias}' yet; skipping board initialization. Later: npx gea setup --board ${alias} --app <id>`)
+    return null
+  }
+  if (candidates.length === 1) return candidates[0]
+  const picked = await choose(prompt, {
+    message: `Which app should the first '${alias}' build target?`,
+    choices: [
+      ...candidates.map((app) => ({ value: app.id, label: app.id, description: app.root })),
+      { value: '', label: 'Skip board initialization for now' }
+    ],
+    defaultValue: candidates[0].id
+  })
+  return picked ? candidates.find((app) => app.id === picked) : null
+}
+
+// Resolves the ESP-IDF version target once for the whole wizard run:
+// --idf-version / GEA_ESP_IDF_VERSION win outright; otherwise a best-effort
+// GitHub "latest release" lookup, falling back to the pinned default when it
+// cannot be determined. `io.fetchEspIdfLatest` lets callers (tests) inject a
+// fake fetch instead of touching the network -- mirrors `probeSerialDevice`.
+async function resolveEspIdfVersionForWizard(parsed, io) {
+  return resolveEspIdfVersion({
+    override: option(parsed, 'idf-version'),
+    env: io.env || process.env,
+    fetchLatest: io.fetchEspIdfLatest || fetchLatestEspIdfVersion,
+    log: io.stderr || (() => {})
+  })
+}
+
+async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false, targetVersion } = {}) {
   const env = io.env || process.env
-  const status = detectEspIdf(env)
+  const resolvedVersion = targetVersion || await resolveEspIdfVersionForWizard(parsed, io)
+  const status = detectEspIdf(env, resolvedVersion)
   if (status.available) {
     if (force) io.stdout(`ESP-IDF found: ${status.detail}`)
     return 0
   }
 
   const install = force || await confirm(prompt, {
-    message: `ESP-IDF ${espIdfVersion} was not found. Install it now?`,
+    message: `ESP-IDF ${resolvedVersion} was not found${status.detail ? ` (found ${status.detail})` : ''}. Install it now?`,
     defaultValue: false
   })
   if (!install) {
@@ -405,7 +455,7 @@ async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false } = {})
   const dryRun = flag(parsed, 'dry-run')
   if (!dryRun) fs.mkdirSync(path.dirname(idfDir), { recursive: true })
   if (!exists(path.join(idfDir, 'install.sh')) && !exists(path.join(idfDir, 'install.bat'))) {
-    runExternal('git', ['clone', '-b', espIdfVersion, '--recursive', 'https://github.com/espressif/esp-idf.git', idfDir], {
+    runExternal('git', ['clone', '-b', resolvedVersion, '--recursive', 'https://github.com/espressif/esp-idf.git', idfDir], {
       cwd: ctx.cwd,
       env,
       dryRun,
@@ -429,39 +479,74 @@ async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false } = {})
   return 0
 }
 
-function detectEspIdf(env) {
-  const idfVersion = commandVersion('idf.py', ['--version'], env)
-  if (idfVersion) return { available: true, detail: idfVersion }
-  if (env.IDF_PATH) return { available: true, detail: env.IDF_PATH }
+// Prefers the same conventional-directory detection the build path uses
+// (`findEspIdf` + its version.cmake), which lets a version-floor check run;
+// falls back to a bare `idf.py --version` on PATH when no such directory is
+// found but some ESP-IDF install has still put idf.py on PATH.
+function detectEspIdf(env, targetVersion) {
+  const idfDir = findEspIdf(env)
+  if (idfDir) {
+    const installed = readInstalledEspIdfVersion(idfDir)
+    const detail = `${installed?.full || 'unknown version'} at ${idfDir}`
+    return { available: idfVersionMeetsTarget(installed, targetVersion), detail }
+  }
+  const legacyOutput = commandVersion('idf.py', ['--version'], env)
+  if (legacyOutput) {
+    const installed = extractIdfVersionFromText(legacyOutput)
+    const available = !installed || idfVersionMeetsTarget(installed, targetVersion)
+    return { available, detail: legacyOutput }
+  }
   return { available: false, detail: '' }
 }
 
-async function selectUsbSerial(prompt, io, { message }) {
-  const devices = detectSerialDevices({ env: io.env || process.env })
-  if (devices.length === 0) {
-    return ask(prompt, {
-      message,
-      defaultValue: ''
+// Nobody knows their board's USB serial by heart, so the wizard never asks
+// for one. It asks whether the board is plugged in, reads the serial from the
+// USB registry, and PINGs each port so the user picks by what the board says
+// it is running rather than by a /dev name. A board that is not connected is
+// registered without a serial; `gea boards discover --save` fills it in later.
+async function selectUsbSerial(prompt, io, ctx, { message }) {
+  const env = io.env || process.env
+  io.stdout(message)
+  const connected = await confirm(prompt, { message: 'Is the board connected over USB right now?', defaultValue: true })
+  if (!connected) {
+    io.stdout('No USB serial recorded. Later, with the board plugged in: gea boards discover --save')
+    return ''
+  }
+  const known = loadBoardConfig(ctx)
+  const probe = io.probeSerialDevice || ((device) => probeSerialDevice(device, { env }))
+  while (true) {
+    const devices = detectSerialDevices({ env }).filter((device) => device.serial)
+    if (devices.length === 0) {
+      io.stdout('No USB board detected. Check the cable (some are power-only) and that the board is on.')
+      const retry = await confirm(prompt, { message: 'Retry detection?', defaultValue: true })
+      if (retry) continue
+      io.stdout('No USB serial recorded. Later, with the board plugged in: gea boards discover --save')
+      return ''
+    }
+    const results = await discoverBoards({ devices, boards: known, probe })
+    const describe = (result) => {
+      const bits = [result.label && result.label !== result.path ? `${result.label} on ${result.path}` : result.path, `serial ${result.serial}`]
+      if (result.responds) bits.push(result.app ? `running ${result.app}` : 'gea firmware')
+      if (result.alias) bits.push(`already registered as '${result.alias}'`)
+      return bits.join(', ')
+    }
+    if (results.length === 1) {
+      io.stdout(`Detected ${describe(results[0])}`)
+      return results[0].serial
+    }
+    const selected = await choose(prompt, {
+      message: 'Several USB devices are connected. Which one is this board?',
+      choices: [
+        ...results.map((result, index) => ({ value: `device-${index}`, label: describe(result) })),
+        { value: 'retry', label: 'Unplug the others and detect again' },
+        { value: 'skip', label: 'Skip for now' }
+      ],
+      defaultValue: 'device-0'
     })
+    if (selected === 'skip') return ''
+    if (selected === 'retry') continue
+    return results[Number.parseInt(selected.slice('device-'.length), 10)].serial
   }
-
-  const selected = await choose(prompt, {
-    message: 'Detected serial devices. Which board is connected?',
-    choices: [
-      ...devices.map((device, index) => ({ value: `device-${index}`, label: formatSerialDevice(device) })),
-      { value: 'manual', label: 'Enter stable USB serial manually' },
-      { value: 'skip', label: 'Skip for now' }
-    ],
-    defaultValue: 'device-0'
-  })
-  if (selected === 'skip') return ''
-  if (selected === 'manual') return ask(prompt, { message, defaultValue: '' })
-  const index = Number.parseInt(selected.slice('device-'.length), 10)
-  const device = devices[index]
-  return ask(prompt, {
-    message: `Stable USB serial for ${device.path}`,
-    defaultValue: device.serial || ''
-  })
 }
 
 // --global writes the alias to ~/.geastack/boards.json, --local to the