@geastack/cli 0.1.52 → 0.1.54

package/src/gea.mjs

@@ -1,28 +1,21 @@
-import path from 'node:path'
 import fs from 'node:fs'
 
 import { flag, option, parseArgs } from './args.mjs'
-import { runCreateGeastack } from './create-geastack.mjs'
 import { runChips } from './chips.mjs'
-import { createChildEnv, createContext } from './context.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'
+import { runCreateGeastack } from './create-geastack.mjs'
 import { ExitCode, fail } from './errors.mjs'
-import { exists, readJson } from './fs-utils.mjs'
-import {
-  assertTargetEnabled,
-  boardConfigPath,
-  assertValidApp,
-  discoverApps,
-  loadBoardConfig,
-  loadTargetMetadata,
-  resolveRequestedApp,
-  validateApp
-} from './manifest.mjs'
-import { runExternal } from './run.mjs'
+import { knownPlatforms } from './manifest.mjs'
 import { runSetupWizard } from './setup-wizard.mjs'
-import { commandVersion, nodeAtLeast } from './toolchain.mjs'
 
 const version = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
+const geaosDeviceActions = new Set(['bringup', 'probe', 'shell', 'push', 'record', 'tap', 'drag', 'down', 'move', 'up', 'flash-kernel'])
+
 export async function runGea(argv, io = {}) {
   const parsed = parseArgs(argv)
   const stdout = io.stdout || console.log
@@ -50,438 +43,107 @@ 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 }
+
+  // A platform name in --target (web, macos, ...) is not a board.
+  const target = option(parsed, 'target', '')
+  if (target && knownPlatforms.includes(target) && ['build', 'flash', 'run', 'monitor', 'ota'].includes(command)) {
+    if (target === 'esp32' || target === 'rp2350' || target === 'geaos') {
+      fail(`--target ${target} names a platform; pass --board <alias> (gea boards list) or --target <target id> (gea targets list).`, ExitCode.usage)
+    }
+    fail(`The ${target} build is not driven by gea; run its build script in the ${target} target project.`, ExitCode.usage)
+  }
 
   switch (command) {
     case 'doctor':
-      return doctor(ctx, parsed, { stdout, env })
-    case 'dev':
-      return dev(ctx, parsed, rest, { stdout, env })
-    case 'build':
-      return build(ctx, parsed, rest, { stdout, env })
+      return doctorCommand(ctx, parsed, rest, options)
     case 'setup':
-      return setup(ctx, parsed, { stdout, env, stdin, output, prompt })
+      return option(parsed, 'board') || option(parsed, 'target')
+        ? buildCommand(ctx, { ...parsed, options: { ...parsed.options, 'configure-only': true } }, rest, options)
+        : runSetupWizard(ctx, parsed, options)
     case 'chips':
-      return runChips(ctx, parsed, rest, { stdout, env, stdin, output, prompt })
+      return runChips(ctx, parsed, rest, options)
+    case 'build':
+      return buildCommand(ctx, parsed, rest, options)
+    case 'clean':
+      return cleanCommand(ctx, parsed, rest, options)
     case 'flash':
-      return flash(ctx, parsed, rest, { stdout, env })
+      return flashCommand(ctx, parsed, rest, options, { monitor: flag(parsed, 'monitor') })
+    case 'run':
+      return flashCommand(ctx, parsed, rest, options, { monitor: true })
     case 'monitor':
-      return monitor(ctx, parsed, rest, { stdout, env })
+      return monitorCommand(ctx, parsed, rest, options)
+    case 'logs':
+    case 'tail':
+      return logsCommand(ctx, parsed, rest, options)
     case 'screenshot':
-      return screenshot(ctx, parsed, rest, { stdout, env })
+      return screenshotCommand(ctx, parsed, rest, options)
     case 'ota':
-      return ota(ctx, parsed, rest, { stdout, env })
+      return otaCommand(ctx, parsed, rest, options)
+    case 'devctl':
+      return devctlCommand(ctx, parsed, rest, options)
+    case 'apps':
+      return appsCommand(ctx, parsed, rest, options)
+    case 'boards':
+      return boardsCommand(ctx, parsed, rest, options)
+    case 'targets':
+      return targetsCommand(ctx, parsed, rest, options)
+    case 'heap-report':
+      return heapReportCommand(ctx, parsed, rest, options)
     case 'list':
-      return list(ctx, parsed, rest, { stdout })
+      return legacyList(ctx, parsed, rest, options)
     case 'inspect':
-      return inspect(ctx, parsed, rest, { stdout })
+      return appsCommand(ctx, parsed, ['inspect', ...rest], options)
     default:
+      if (geaosDeviceActions.has(command)) return geaosDeviceCommand(ctx, parsed, [command, ...rest], options)
       stderr(`Unknown command: ${command}`)
       stdout(usage())
       return 1
   }
 }
 
-function dev(ctx, parsed, rest, io) {
-  const app = resolveRequestedApp(ctx, parsed, rest)
-  assertValidApp(app)
-  const target = option(parsed, 'target', 'web')
-  assertTargetEnabled(ctx, app, target)
-
-  if (target !== 'web') {
-    io.stdout(`No live dev loop is registered for target '${target}' yet. Use 'gea flash --app ${app.id} --board <alias> --monitor'.`)
-    return 0
-  }
-
-  requirePath(ctx.scripts.webDev, 'web dev script')
-  const args = [ctx.scripts.webDev, app.id]
-  const port = option(parsed, 'port')
-  if (port) args.push('--port', String(port))
-  return runExternal('node', args, {
-    cwd: ctx.simulatorRoot,
-    env: createChildEnv(ctx, io.env),
-    dryRun: flag(parsed, 'dry-run'),
-    failureCode: ExitCode.buildFailed,
-    stdout: io.stdout
-  })
-}
-
-function build(ctx, parsed, rest, io) {
-  const app = resolveRequestedApp(ctx, parsed, rest)
-  assertValidApp(app)
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', board ? '' : 'web')
-  assertTargetEnabled(ctx, app, board || target)
-
-  if (target === 'web' && !board) {
-    requirePath(ctx.scripts.webBuild, 'web build script')
-    return runExternal(ctx.scripts.webBuild, [app.id], {
-      cwd: ctx.simulatorRoot,
-      env: createChildEnv(ctx, io.env),
-      dryRun: flag(parsed, 'dry-run'),
-      failureCode: ExitCode.buildFailed,
-      stdout: io.stdout
-    })
-  }
-
-  if (target === 'macos') {
-    requirePath(ctx.scripts.macosBuild, 'macOS build script')
-    const outputTag = option(parsed, 'output-tag')
-    if (outputTag !== undefined && (typeof outputTag !== 'string' || outputTag.length === 0)) {
-      fail('--output-tag requires a non-empty value.', ExitCode.usage)
-    }
-    const args = [app.id]
-    if (outputTag !== undefined) args.push('--output-tag', outputTag)
-    return runExternal(ctx.scripts.macosBuild, args, {
-      cwd: ctx.appleRoot,
-      env: createChildEnv(ctx, io.env),
-      dryRun: flag(parsed, 'dry-run'),
-      failureCode: ExitCode.buildFailed,
-      stdout: io.stdout
-    })
-  }
-
-  if (target === 'ios') {
-    requirePath(ctx.scripts.iosBuild, 'iOS build script')
-    const mode = option(parsed, 'mode', 'simulator')
-    return runExternal(ctx.scripts.iosBuild, [app.id, mode], {
-      cwd: ctx.appleRoot,
-      env: createChildEnv(ctx, io.env),
-      dryRun: flag(parsed, 'dry-run'),
-      failureCode: ExitCode.buildFailed,
-      stdout: io.stdout
-    })
-  }
-
-  if (target === 'android') {
-    return runAndroid(ctx, parsed, {
-      appId: app.id,
-      mode: option(parsed, 'mode', 'debug'),
-      failureCode: ExitCode.buildFailed,
-      stdout: io.stdout,
-      env: io.env
-    })
-  }
-
-  return runBoard(ctx, 'build', parsed, {
-    app,
-    appId: app.id,
-    board,
-    target,
-    failureCode: ExitCode.buildFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function setup(ctx, parsed, io) {
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', '')
-  if (!board && !target) {
-    return runSetupWizard(ctx, parsed, io)
-  }
-  return runBoard(ctx, 'setup', parsed, {
-    board,
-    target,
-    failureCode: ExitCode.buildFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function flash(ctx, parsed, rest, io) {
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', '')
-  if (!board && !target) fail('flash requires --board <alias> or --target <target>.', ExitCode.usage)
-  if (flag(parsed, 'bringup')) {
-    return runBoard(ctx, flag(parsed, 'monitor') ? 'flash-monitor' : 'flash', parsed, {
-      board,
-      target,
-      failureCode: ExitCode.deployFailed,
-      stdout: io.stdout,
-      env: io.env
-    })
-  }
-
-  const app = resolveRequestedApp(ctx, parsed, rest)
-  assertValidApp(app)
-  assertTargetEnabled(ctx, app, board || target)
-
-  if (!board && target === 'android') {
-    return runAndroid(ctx, parsed, {
-      appId: app.id,
-      mode: 'device',
-      failureCode: ExitCode.deployFailed,
-      stdout: io.stdout,
-      env: io.env
-    })
-  }
-
-  return runBoard(ctx, flag(parsed, 'monitor') ? 'flash-monitor' : 'flash', parsed, {
-    app,
-    appId: app.id,
-    board,
-    target,
-    failureCode: ExitCode.deployFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function ota(ctx, parsed, rest, io) {
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', '')
-  if (!board && !target) fail('ota requires --board <alias> or --target <target>.', ExitCode.usage)
-
-  const app = resolveRequestedApp(ctx, parsed, rest)
-  assertValidApp(app)
-  assertTargetEnabled(ctx, app, board || target)
-
-  const transport = option(parsed, 'transport', 'wifi')
-  if (transport !== 'wifi' && transport !== 'ble') {
-    fail("--transport must be 'wifi' or 'ble'.", ExitCode.usage)
-  }
-  return runBoard(ctx, transport === 'ble' ? 'ble-ota' : 'ota', parsed, {
-    app,
-    appId: app.id,
-    board,
-    target,
-    failureCode: ExitCode.deployFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function monitor(ctx, parsed, rest, io) {
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', '')
-  if (!board && !target) fail('monitor requires --board <alias> or --target <target>.', ExitCode.usage)
-  if (!board && target === 'android') {
-    return runAndroid(ctx, parsed, {
-      appId: 'css-3d-cube',
-      mode: 'monitor',
-      failureCode: ExitCode.deployFailed,
-      stdout: io.stdout,
-      env: io.env
-    })
-  }
-  return runBoard(ctx, 'monitor', parsed, {
-    board,
-    target,
-    failureCode: ExitCode.deployFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function screenshot(ctx, parsed, rest, io) {
-  const board = option(parsed, 'board', '')
-  const target = option(parsed, 'target', '')
-  if (!board && !target) fail('screenshot requires --board <alias> or --target <target>.', ExitCode.usage)
-
-  const output = path.resolve(ctx.cwd, rest[0] || 'screenshot.png')
-  const extraArgs = [output]
-  const timeout = option(parsed, 'timeout')
-  if (timeout !== undefined) extraArgs.push(`--timeout=${timeout}`)
-  if (flag(parsed, 'legacy')) extraArgs.push('--legacy')
-
-  return runBoard(ctx, 'screenshot', parsed, {
-    board,
-    target,
-    extraArgs,
-    namedPort: true,
-    failureCode: ExitCode.deployFailed,
-    stdout: io.stdout,
-    env: io.env
-  })
-}
-
-function runBoard(ctx, action, parsed, opts) {
-  requirePath(ctx.scripts.board, 'board script')
-  const args = [action]
-  if (opts.board) args.push(`--board=${opts.board}`)
-  if (opts.target) args.push(`--target=${opts.target}`)
-  if (opts.appId) args.push(`--app=${opts.appId}`)
-  const port = option(parsed, 'port')
-  if (port) args.push(opts.namedPort ? `--port=${port}` : String(port))
-  if (flag(parsed, 'manual-boot')) args.push('--manual-boot')
-  if (option(parsed, 'reset') === false) args.push('--no-reset')
-  const flashBaud = option(parsed, 'flash-baud')
-  if (flashBaud !== undefined) args.push(`--flash-baud=${flashBaud}`)
-  if (opts.extraArgs) args.push(...opts.extraArgs)
-  args.push(...parsed.passthrough)
-  const childEnv = createChildEnv(ctx, opts.env)
-  if (opts.app?.manifest?.ota?.ble === true) childEnv.GEA_EMBEDDED_BLE_OTA = '1'
-  return runExternal(ctx.scripts.board, args, {
-    cwd: ctx.targetsRoot,
-    env: childEnv,
-    dryRun: flag(parsed, 'dry-run'),
-    failureCode: opts.failureCode,
-    stdout: opts.stdout
-  })
-}
-
-function runAndroid(ctx, parsed, opts) {
-  requirePath(ctx.scripts.androidBuild, 'Android build script')
-  return runExternal(ctx.scripts.androidBuild, [opts.appId, opts.mode, ...parsed.passthrough], {
-    cwd: ctx.androidRoot,
-    env: createChildEnv(ctx, opts.env),
-    dryRun: flag(parsed, 'dry-run'),
-    failureCode: opts.failureCode,
-    stdout: opts.stdout
-  })
-}
-
-function list(ctx, parsed, rest, io) {
+function legacyList(ctx, parsed, rest, options) {
   const subject = rest[0] || 'apps'
-  if (subject === 'apps') {
-    const target = option(parsed, 'target')
-    const apps = discoverApps(ctx)
-      .filter((app) => !target || app.targets?.[target] === true)
-      .map((app) => ({ id: app.id, name: app.name, targets: app.targets, root: app.root }))
-    if (flag(parsed, 'json')) io.stdout(JSON.stringify(apps, null, 2))
-    else for (const app of apps) io.stdout(app.id)
-    return 0
-  }
-  if (subject === 'targets') {
-    const targets = loadTargetMetadata(ctx)
-    if (flag(parsed, 'json')) io.stdout(JSON.stringify(targets, null, 2))
-    else for (const id of Object.keys(targets).sort()) io.stdout(id)
-    return 0
-  }
-  if (subject === 'boards') {
-    const boards = loadBoardConfig(ctx)
-    if (flag(parsed, 'json')) io.stdout(JSON.stringify(boards, null, 2))
-    else for (const id of Object.keys(boards).sort()) io.stdout(id)
-    return 0
-  }
+  if (subject === 'apps') return appsCommand(ctx, parsed, ['list'], options)
+  if (subject === 'targets') return targetsCommand(ctx, parsed, ['list'], options)
+  if (subject === 'boards') return boardsCommand(ctx, parsed, ['list'], options)
   fail(`Unknown list subject '${subject}'. Expected apps, targets, or boards.`, ExitCode.usage)
 }
 
-function inspect(ctx, parsed, rest, io) {
-  const app = resolveRequestedApp(ctx, parsed, rest)
-  assertValidApp(app)
-  const payload = {
-    id: app.id,
-    name: app.name,
-    root: app.root,
-    entry: app.entry,
-    runtime: app.runtime,
-    targets: app.targets,
-    icons: app.icons,
-    launcher: app.launcher
-  }
-  if (flag(parsed, 'json')) io.stdout(JSON.stringify(payload, null, 2))
-  else io.stdout(`${app.id}\t${app.name}\t${app.root}\t${app.entry}`)
-  return 0
-}
-
-function doctor(ctx, parsed, io) {
-  const checks = []
-  addCheck(checks, '@geastack/targets', packageExists(ctx.targetsRoot), ctx.targetsRoot, true)
-  addCheck(checks, '@geastack/core', packageExists(ctx.corePackageDir), ctx.corePackageDir, true)
-  addCheck(checks, '@geastack/compiler', packageExists(ctx.compilerPackageDir), ctx.compilerPackageDir, true)
-  addCheck(checks, 'project root', exists(ctx.projectRoot), ctx.projectRoot, true)
-  addCheck(checks, 'web dev adapter', exists(ctx.scripts.webDev), ctx.scripts.webDev, false)
-  addCheck(checks, 'web build adapter', exists(ctx.scripts.webBuild), ctx.scripts.webBuild, false)
-  addCheck(checks, 'Android build adapter', exists(ctx.scripts.androidBuild), ctx.scripts.androidBuild, false)
-  addCheck(checks, 'board script', exists(ctx.scripts.board), ctx.scripts.board, true)
-  addCheck(checks, 'Node >= 20.19', nodeAtLeast(20, 19), process.version, true)
-  const npmVersion = commandVersion('npm', ['--version'], io.env)
-  const pythonCommand = commandVersion('python3', ['--version'], io.env) ? 'python3' : 'python'
-  const pythonVersion = commandVersion(pythonCommand, ['--version'], io.env)
-  const idfVersion = commandVersion('idf.py', ['--version'], io.env)
-  const emccVersion = commandVersion('emcc', ['--version'], io.env)
-  const xcodeVersion = commandVersion('xcodebuild', ['-version'], io.env)
-  const adbVersion = commandVersion('adb', ['version'], io.env)
-  const javacVersion = commandVersion('javac', ['--version'], io.env)
-  const androidSdk = io.env.ANDROID_HOME || io.env.ANDROID_SDK_ROOT || path.join(process.env.HOME || '', 'Library', 'Android', 'sdk')
-  addCheck(checks, 'npm', Boolean(npmVersion), npmVersion, false)
-  addCheck(checks, 'Python', Boolean(pythonVersion), pythonVersion, false)
-  addCheck(checks, 'ESP-IDF', Boolean(idfVersion) || Boolean(io.env.IDF_PATH), io.env.IDF_PATH || idfVersion, false)
-  addCheck(checks, 'Emscripten', Boolean(emccVersion), emccVersion.split('\n')[0], false)
-  addCheck(checks, 'Xcode', Boolean(xcodeVersion), xcodeVersion.split('\n')[0], false)
-  addCheck(checks, 'Android SDK', exists(androidSdk), androidSdk, false)
-  addCheck(checks, 'adb', Boolean(adbVersion), adbVersion.split('\n')[0], false)
-  addCheck(checks, 'javac', Boolean(javacVersion), javacVersion.split('\n')[0], false)
-
-  const boardFile = boardConfigPath(ctx)
-  try {
-    if (exists(boardFile)) readJson(boardFile)
-    addCheck(checks, 'boards.json', exists(boardFile), exists(boardFile) ? boardFile : 'not configured', false)
-  } catch (error) {
-    addCheck(checks, 'boards.json', false, error.message, true)
-  }
-
-  const apps = discoverApps(ctx)
-  addCheck(checks, 'app catalog', apps.length > 0, `${apps.length} app(s)`, true)
-
-  const currentApp = (() => {
-    try {
-      return resolveRequestedApp(ctx, parsed, [])
-    } catch {
-      return null
-    }
-  })()
-  if (currentApp) {
-    const errors = validateApp(currentApp)
-    addCheck(checks, `app manifest (${currentApp.id})`, errors.length === 0, errors.length === 0 ? currentApp.root : errors.join('; '), true)
-  }
-
-  const failedRequired = checks.filter((check) => check.required && !check.ok)
-  const failedOptional = checks.filter((check) => !check.required && !check.ok)
-
-  if (flag(parsed, 'json')) {
-    io.stdout(JSON.stringify({ ok: failedRequired.length === 0, checks }, null, 2))
-  } else {
-    for (const check of checks) {
-      const marker = check.ok ? '[ok]' : check.required ? '[fail]' : '[warn]'
-      io.stdout(`${marker} ${check.name}: ${check.detail}`)
-    }
-    if (failedRequired.length > 0 || failedOptional.length > 0) {
-      io.stdout('Setup guide: cli/docs/SETUP.md')
-    }
-  }
-
-  if (failedRequired.length > 0) return ExitCode.missingDependency
-  if (failedOptional.length > 0 && flag(parsed, 'strict')) return ExitCode.missingDependency
-  return 0
-}
-
-function addCheck(checks, name, ok, detail, required) {
-  checks.push({ name, ok: Boolean(ok), detail: detail || (ok ? 'ok' : 'missing'), required: Boolean(required) })
-}
-
-function packageExists(packageDir) {
-  return Boolean(packageDir) && exists(path.join(packageDir, 'package.json'))
-}
-
-function requirePath(filePath, label) {
-  if (!exists(filePath)) fail(`Missing ${label}: ${filePath}`, ExitCode.missingDependency)
-}
-
 function usage() {
-  return `Usage:
-  gea create <name> [--starter counter|empty|example] [--targets <list>]
-  gea doctor [--strict] [--json]
-  gea setup --board <alias>
-  gea chips list [--json]
-  gea chips info <chip> [--json]
-  gea chips add <chip...> [--board <alias>] [--set chip.path=value]
-  gea chips remove <chip...> [--board <alias>]
-  gea dev [app] [--target web] [--port 5181]
-  gea build [app] [--target web|macos|ios|android|<target>] [--board <alias>] [--output-tag <tag>]
-  gea flash [app] --board <alias> [--monitor] [--port auto] [--manual-boot] [--no-reset] [--flash-baud <rate>]
-  gea flash [app] --target android
-  gea flash --bringup --board <alias> [--monitor] [--port auto]
-  gea monitor --board <alias>
-  gea monitor --target android
-  gea screenshot [output.png] --board <alias> [--port auto] [--timeout <seconds>] [--legacy]
-  gea ota [app] --board <alias> [--transport wifi|ble]
-  gea list [apps|targets|boards] [--json]
-  gea inspect [app] [--json]
-
-Global options:
-  --boards-config <file>
-  --dry-run
-`
+  return `gea ${version}
+
+Usage:
+  gea create <name>                              scaffold a new Gea project
+  gea setup [--board <alias>]                    guided board setup, or configure a board's build
+  gea doctor [--json] [--strict]                 check packages and toolchains
+
+Build and deploy (every device command takes --board <alias>, see gea boards list):
+  gea build --board <alias> [--app <id>]         build firmware (ESP-IDF / Pico SDK / geaos)
+  gea flash --board <alias> [--app <id>]         build + flash over USB   [--monitor] [--manual-boot] [--no-reset] [--flash-baud N]
+      --slot ota_N [--image file]                stage an app image into an OTA slot only
+      --slot-image ota_N=file ...                provision several prebuilt images
+      --erase-slot ota_N | --restore-boot        slot maintenance
+  gea run --board <alias> [--app <id>]           build + flash + serial monitor
+  gea ota --board <alias> [--app <id>]           build + WiFi OTA (transports.ota.host)  [--monitor]
+      --transport ble [--device name]            BLE OTA (macOS)
+      --slot ota_N [--boot] [--reboot] | --erase-slot ota_N
+  gea clean --board <alias> [--app <id>]         remove build artifacts
+
+Device access:
+  gea logs --board <alias> [--follow]            log stream (WiFi when the board has an IP, else USB)  [--transport auto|usb|wifi]
+  gea monitor --board <alias>                    raw USB serial monitor  [--timestamps] [--log-file f]
+  gea screenshot [file.png] --board <alias>      grab the screen  [--transport auto|usb|wifi]
+  gea devctl <verb> ... --board <alias>          GEADEV device control (gea devctl help)
+
+Catalogs:
+  gea apps list|inspect|pack|index|launcher|icons|icon-sheet|apple-icons
+  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>  --global|--local (boards writes)  --dry-run  --json
+Board aliases: ~/.geastack/boards.json (this machine) + <project>/.gea/boards.json (overrides)`
 }

package/src/geaos/adapter.mjs

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+import { resolveUsbSerialPort } from '../boards/usb.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { formatCommand } from '../run.mjs'
+
+// GeaOS phones and watches. The heavy lifting (docker cross-builds, boot
+// image repacking, fastboot/BROM flashing) stays in the target project's
+// scripts; the CLI resolves the board, the packages and the device, and
+// hands them over as environment.
+
+function geaosEnv(ctx, selection, env) {
+  const out = { ...env, GEA_BOARD_TARGET: selection.target, GEA_APPS_ROOT: ctx.projectRoot }
+  if (selection.telnetHost) {
+    out.GEA_BOARD_TELNET_HOST = selection.telnetHost
+    out.GEAOS_DEVICE_HOST = selection.telnetHost
+  }
+  if (selection.telnetPort) {
+    out.GEA_BOARD_TELNET_PORT = selection.telnetPort
+    out.GEAOS_DEVICE_PORT = selection.telnetPort
+  }
+  if (selection.fastbootSerial) {
+    out.GEA_BOARD_FASTBOOT_SERIAL = selection.fastbootSerial
+    out.GEAOS_FASTBOOT_SERIAL = selection.fastbootSerial
+  }
+  if (selection.usbSerial) out.GEA_BOARD_USB_SERIAL = selection.usbSerial
+  for (const [key, value] of Object.entries({
+    GEA_BOARD_MTK_WORKDIR: selection.mtkWorkdir,
+    GEA_BOARD_MTK_BOOT_SLOT: selection.mtkBootSlot,
+    GEA_BOARD_MTK_METHOD: selection.mtkMethod,
+    GEA_BOARD_MTK_MONITOR_GLOB: selection.mtkMonitorGlob
+  })) {
+    if (value) out[key] = value
+  }
+  // The device is addressed by its USB SERIAL, never by path order. A
+  // detached watch must still build, so an unresolved port stays empty and
+  // the flasher falls through to its own (BROM) path -- pinned to a glob only
+  // this serial can match, so another attached geaos device is never grabbed.
+  let port = selection.port
+  if (!port && selection.usbSerial) {
+    try {
+      port = resolveUsbSerialPort({ serial: selection.usbSerial })
+    } catch {
+      port = ''
+    }
+  }
+  if (port) {
+    out.GEAOS_SERIAL_PORT = port
+    out.GEAOS_MTK_GADGET_GLOB = port
+    out.GEA_BOARD_MTK_MONITOR_GLOB = port
+  } else if (selection.usbSerial) {
+    out.GEAOS_MTK_GADGET_GLOB = `/dev/cu.usbmodem*${selection.usbSerial}*`
+    out.GEA_BOARD_MTK_MONITOR_GLOB = `/dev/cu.usbmodem*${selection.usbSerial}*`
+  }
+  return out
+}
+
+function run(command, args, { cwd, env, dryRun, stdout, failureCode }) {
+  if (dryRun) {
+    stdout(formatCommand([command, ...args]))
+    return 0
+  }
+  if (!existsSync(command)) fail(`${command} was not found. Is the geaos target project available at ${cwd}?`, ExitCode.missingDependency)
+  const result = spawnSync(command, args, { cwd, env, stdio: 'inherit' })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new CliError(`ERROR: Command failed (${result.status ?? 1}): ${formatCommand([command, ...args])}`, failureCode)
+  return 0
+}
+
+export function runGeaos({ ctx, selection, action, app = null, positionals = [], env, dryRun = false, stdout }) {
+  const childEnv = geaosEnv(ctx, selection, env)
+  const targetDir = selection.targetDir
+  const appId = app?.id || positionals[0] || ''
+  const needApp = () => {
+    if (!appId) fail('A geaos app id is required (--app <id>).', ExitCode.usage)
+    return appId
+  }
+  if (selection.adapter === 'geaos-arm64') {
+    const script = path.join(targetDir, 'flash-geaos-arm64.sh')
+    switch (action) {
+      case 'build':
+      case 'flash':
+      case 'flash-monitor':
+        return run(script, [needApp()], { cwd: targetDir, env: { ...childEnv, GEAOS_ARM64_ACTION: action }, dryRun, stdout, failureCode: action === 'build' ? ExitCode.buildFailed : ExitCode.deployFailed })
+      case 'monitor':
+        return run(script, [appId || 'tic-tac-toe'], { cwd: targetDir, env: { ...childEnv, GEAOS_ARM64_ACTION: 'monitor' }, dryRun, stdout, failureCode: ExitCode.deployFailed })
+      default:
+        fail(`'${action}' is not supported by geaos-arm64 boards (build|flash|run|monitor).`, ExitCode.usage)
+    }
+  }
+  const deviceArgs = []
+  if (selection.telnetHost) deviceArgs.push('--host', selection.telnetHost)
+  if (selection.telnetPort) deviceArgs.push('--port', selection.telnetPort)
+  switch (action) {
+    case 'build':
+      return run(path.join(targetDir, 'build-geaos.sh'), [needApp()], { cwd: targetDir, env: childEnv, dryRun, stdout, failureCode: ExitCode.buildFailed })
+    case 'flash':
+    case 'flash-monitor':
+      return run(path.join(targetDir, 'flash-geaos.sh'), [needApp()], { cwd: targetDir, env: childEnv, dryRun, stdout, failureCode: ExitCode.deployFailed })
+    case 'flash-kernel':
+      return run(path.join(targetDir, 'flash-kernel.sh'), positionals, { cwd: targetDir, env: childEnv, dryRun, stdout, failureCode: ExitCode.deployFailed })
+    case 'bringup':
+    case 'probe':
+    case 'shell':
+    case 'push':
+    case 'screenshot':
+    case 'record':
+    case 'tap':
+    case 'drag':
+    case 'down':
+    case 'move':
+    case 'up':
+      return run(path.join(targetDir, 'geaos-device.py'), [...deviceArgs, action, ...positionals], { cwd: targetDir, env: childEnv, dryRun, stdout, failureCode: ExitCode.deployFailed })
+    default:
+      fail(`'${action}' is not supported by geaos-linux boards.`, ExitCode.usage)
+  }
+}