@geastack/cli 0.1.52 → 0.1.54

package/src/manifest.mjs

@@ -1,21 +1,31 @@
 import path from 'node:path'
 
+import { loadBoardConfig, normalizeBoardConfig } from './boards/config.mjs'
+import { loadTargets } from './boards/targets.mjs'
 import { CliError, ExitCode, fail } from './errors.mjs'
 import { exists, findUp, isDirectory, listDirectories, readJson } from './fs-utils.mjs'
 
+// App discovery. A Gea app is a package.json with a `gea` block; the project
+// root, its apps/ and examples/ children, and any GEA_EXTRA_APP_DIRS entries
+// are searched. The normalized shape is the one every consumer (IDF, the
+// Pico SDK, geaos, the bundle writer, the launcher generator) reads.
+
+export function readPathList(value) {
+  return String(value || '').split(path.delimiter).map((entry) => entry.trim()).filter(Boolean)
+}
+
 export function discoverApps(ctx) {
-  const roots = [ctx.projectRoot]
+  const roots = [ctx.projectRoot, ...readPathList(ctx.env?.GEA_EXTRA_APP_DIRS)]
   const seen = new Set()
   const apps = []
   for (const root of roots) {
     for (const app of discoverAppsInRoot(root)) {
-      const key = app.root
-      if (seen.has(key)) continue
-      seen.add(key)
+      if (seen.has(app.root) || apps.some((known) => known.id === app.id)) continue
+      seen.add(app.root)
       apps.push(app)
     }
   }
-  return apps.sort((a, b) => a.id.localeCompare(b.id))
+  return apps.sort((a, b) => a.launcher.order - b.launcher.order || a.id.localeCompare(b.id))
 }
 
 export function discoverAppsInRoot(root) {
@@ -37,16 +47,17 @@ export function discoverAppsInRoot(root) {
   })
 }
 
-export function resolveRequestedApp(ctx, parsed, positionals) {
+export function resolveRequestedApp(ctx, parsed, positionals = []) {
   const requested = parsed.options.app || positionals[0]
   if (requested) {
-    const app = findAppById(ctx, String(Array.isArray(requested) ? requested.at(-1) : requested))
-    if (!app) fail(`Could not find Gea app '${requested}' in ${ctx.projectRoot}.`, ExitCode.usage)
+    const id = String(Array.isArray(requested) ? requested.at(-1) : requested)
+    const app = findAppById(ctx, id)
+    if (!app) fail(`Could not find Gea app '${id}' in ${ctx.projectRoot}.`, ExitCode.usage)
     return app
   }
   const current = findCurrentApp(ctx.cwd)
   if (current) return current
-  fail('No app selected. Pass --app <id>, pass an app id, or run inside a Gea app folder.', ExitCode.usage)
+  fail('No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
 }
 
 export function findAppById(ctx, id) {
@@ -54,7 +65,7 @@ export function findAppById(ctx, id) {
 }
 
 export function findCurrentApp(cwd) {
-  const packageDir = findUp(cwd, (dir) => exists(path.join(dir, 'package.json')) && hasGeaManifest(path.join(dir, 'package.json')))
+  const packageDir = findUp(cwd, (dir) => hasGeaManifest(path.join(dir, 'package.json')))
   if (!packageDir) return null
   return normalizeApp(packageDir, readJson(path.join(packageDir, 'package.json')))
 }
@@ -66,6 +77,9 @@ export function validateApp(app) {
   if (app.entry && !exists(path.join(app.root, app.entry))) errors.push(`gea.entry does not exist: ${app.entry}`)
   if (!app.runtime) errors.push('gea.runtime is required or must default to gea')
   if (!app.targets || typeof app.targets !== 'object' || Array.isArray(app.targets)) errors.push('gea.targets must be an object')
+  for (const source of app.nativeSources) {
+    if (!exists(path.join(app.root, source))) errors.push(`gea.nativeSources entry does not exist: ${source}`)
+  }
   return errors
 }
 
@@ -78,8 +92,7 @@ export function assertValidApp(app) {
 
 export function targetEnabledForApp(ctx, app, targetOrPlatform) {
   if (!targetOrPlatform) return true
-  const platforms = appPlatformsForTarget(ctx, targetOrPlatform)
-  return platforms.some((platform) => app.targets?.[platform] === true)
+  return appPlatformsForTarget(ctx, targetOrPlatform).some((platform) => app.targets?.[platform] === true)
 }
 
 export function assertTargetEnabled(ctx, app, targetOrPlatform) {
@@ -89,16 +102,18 @@ export function assertTargetEnabled(ctx, app, targetOrPlatform) {
   }
 }
 
+export const knownPlatforms = Object.freeze(['web', 'esp32', 'rp2350', 'geaos', 'macos', 'ios', 'android'])
+
 export function appPlatformForTarget(ctx, targetOrBoard) {
   return appPlatformsForTarget(ctx, targetOrBoard)[0] || ''
 }
 
 export function appPlatformsForTarget(ctx, targetOrBoard) {
   if (!targetOrBoard) return []
-  if (['web', 'esp32', 'rp2350', 'geaos', 'macos', 'ios', 'android'].includes(targetOrBoard)) return [targetOrBoard]
-  const targets = loadTargetMetadata(ctx)
+  if (knownPlatforms.includes(targetOrBoard)) return [targetOrBoard]
+  const targets = safeTargets(ctx)
   if (targets[targetOrBoard]?.appPlatform) return targetAppPlatforms(targets[targetOrBoard])
-  const boards = loadBoardConfig(ctx)
+  const boards = safeBoards(ctx)
   const board = boards[targetOrBoard]
   const boardTarget = board?.target
   if (board?.appPlatform) {
@@ -112,25 +127,54 @@ export function appPlatformsForTarget(ctx, targetOrBoard) {
   return [targetOrBoard]
 }
 
-export function loadTargetMetadata(ctx) {
-  const file = path.join(ctx.targetsRoot, 'scripts', 'boards', 'targets.json')
-  return exists(file) ? readJson(file) : {}
+// Consumers (CMake, the apple/geaos build scripts) join a relative root onto
+// GEA_APPS_ROOT; an app outside the project keeps its absolute path.
+export function appRootFor(ctx, app) {
+  const relative = path.relative(ctx.projectRoot, app.root)
+  if (!relative) return '.'
+  return relative.startsWith('..') || path.isAbsolute(relative) ? app.root : relative.split(path.sep).join('/')
 }
 
-export function loadBoardConfig(ctx) {
-  const file = boardConfigPath(ctx)
-  return exists(file) ? readJson(file) : {}
+// `root;entry;runtime;nativeSource...` -- the one line CMake splits on ';'.
+export function appCmakeMeta(ctx, app) {
+  return [appRootFor(ctx, app), app.entry, app.runtime, ...app.nativeSources].join(';')
+}
+
+export function appSummary(ctx, app) {
+  return {
+    id: app.id,
+    name: app.name,
+    packageName: app.packageName,
+    version: app.version,
+    root: appRootFor(ctx, app),
+    entry: app.entry,
+    runtime: app.runtime,
+    targets: app.targets,
+    icons: app.icons,
+    nativeSources: app.nativeSources,
+    launcher: app.launcher
+  }
 }
 
-export function boardConfigPath(ctx) {
-  if (ctx.boardsConfig) return ctx.boardsConfig
-  if (ctx.projectBoardsConfig && exists(ctx.projectBoardsConfig)) return ctx.projectBoardsConfig
-  return path.join(ctx.targetsRoot, 'boards.json')
+function safeTargets(ctx) {
+  try {
+    return loadTargets(ctx)
+  } catch {
+    return {}
+  }
+}
+
+function safeBoards(ctx) {
+  try {
+    return normalizeBoardConfig(loadBoardConfig(ctx))
+  } catch {
+    return {}
+  }
 }
 
 function hasGeaManifest(packagePath) {
   try {
-    return Boolean(readJson(packagePath).gea)
+    return exists(packagePath) && Boolean(readJson(packagePath).gea)
   } catch {
     return false
   }
@@ -152,19 +196,74 @@ function uniquePlatforms(values) {
   return out
 }
 
-function normalizeApp(root, packageJson) {
+function packageId(packageName) {
+  const last = String(packageName || '').split('/').pop() || ''
+  return last.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'app'
+}
+
+function normalizeTargets(raw) {
+  if (Array.isArray(raw)) return Object.fromEntries(raw.map((name) => [String(name), true]))
+  if (!raw || typeof raw !== 'object') return {}
+  const out = {}
+  for (const [name, value] of Object.entries(raw)) {
+    if (!name) continue
+    if (value && typeof value === 'object') out[name] = value.enabled !== false
+    else out[name] = value === true
+  }
+  return out
+}
+
+function normalizeIcons(raw) {
+  if (!raw || typeof raw !== 'object') return {}
+  const icons = {}
+  for (const [size, file] of Object.entries(raw)) {
+    const numericSize = Number(size)
+    if (!Number.isInteger(numericSize) || numericSize <= 0) continue
+    if (typeof file !== 'string' || file.length === 0) continue
+    icons[numericSize] = file
+  }
+  return icons
+}
+
+function normalizeLauncher(raw) {
+  if (!raw || typeof raw !== 'object') return { description: '', order: 0, accent: '', hidden: false }
+  return {
+    description: typeof raw.description === 'string' ? raw.description : '',
+    order: Number.isFinite(raw.order) ? raw.order : 0,
+    accent: typeof raw.accent === 'string' ? raw.accent : '',
+    hidden: raw.hidden === true
+  }
+}
+
+function normalizeManifestRelativePath(value) {
+  const normalized = path.posix.normalize(String(value || '').replaceAll('\\', '/'))
+  if (!normalized || normalized === '.' || normalized === '..') return ''
+  if (path.posix.isAbsolute(normalized) || normalized.startsWith('../')) return ''
+  if (normalized.includes('/../') || normalized.includes(';')) return ''
+  return normalized
+}
+
+export function normalizeNativeSources(raw) {
+  if (!Array.isArray(raw)) return []
+  const sources = raw.map(normalizeManifestRelativePath).filter((source) => /\.(?:c|cc|cpp|cxx|m|mm|S)$/.test(source))
+  return [...new Set(sources)]
+}
+
+export function normalizeApp(root, packageJson) {
   const gea = packageJson.gea || {}
+  const id = typeof gea.id === 'string' && gea.id ? gea.id : packageId(packageJson.name)
   return {
-    id: String(gea.id || ''),
-    name: String(gea.name || packageJson.name || gea.id || ''),
-    packageName: packageJson.name || '',
-    version: packageJson.version || '',
+    id,
+    name: typeof gea.name === 'string' && gea.name ? gea.name : packageJson.name || id,
+    packageName: packageJson.name || id,
+    version: packageJson.version || '0.0.0',
     root: path.resolve(root),
-    entry: gea.entry || 'index.tsx',
-    runtime: gea.runtime || 'gea',
-    targets: gea.targets || {},
-    icons: gea.icons || {},
-    launcher: gea.launcher || {},
+    entry: typeof gea.entry === 'string' && gea.entry ? gea.entry : 'index.tsx',
+    runtime: typeof gea.runtime === 'string' && gea.runtime ? gea.runtime : 'gea',
+    targets: normalizeTargets(gea.targets),
+    icons: normalizeIcons(gea.icons),
+    nativeSources: normalizeNativeSources(gea.nativeSources),
+    launcher: normalizeLauncher(gea.launcher),
     manifest: gea,
     packageJson
   }

package/src/rp2350/adapter.mjs

@@ -0,0 +1,155 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { resolvePicotoolSelection } from '../boards/usb.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { appCmakeMeta } from '../manifest.mjs'
+import { formatCommand } from '../run.mjs'
+
+// Raspberry Pi RP2350 boards through the Pico SDK: cmake configure + build,
+// then UF2 over the BOOTSEL volume or picotool.
+
+const firmwareStems = {
+  'rp2350-waveshare-touch-amoled-2.41': 'gea_rp2350_touch_amoled_241',
+  'rp2350-tufty-2350': 'gea_rp2350_tufty_2350'
+}
+
+function toolchainHasRuntime(root) {
+  if (!existsSync(path.join(root, 'bin', 'arm-none-eabi-gcc'))) return false
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()
+    let entries = []
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name === 'nosys.specs') return true
+      if (entry.isDirectory()) stack.push(path.join(dir, entry.name))
+    }
+  }
+  return false
+}
+
+function globDirs(pattern) {
+  const parent = path.dirname(pattern)
+  const prefix = path.basename(pattern).replace(/\*.*$/, '')
+  const suffix = pattern.includes('*') ? pattern.slice(pattern.indexOf('*') + 1) : ''
+  try {
+    return readdirSync(parent)
+      .filter((name) => name.startsWith(prefix))
+      .map((name) => path.join(parent, name, suffix))
+      .filter((dir) => existsSync(dir))
+  } catch {
+    return []
+  }
+}
+
+export function prepareArmToolchain(env, stderr = () => {}) {
+  if (env.PICO_TOOLCHAIN_PATH) {
+    return { ...env, PATH: `${path.join(env.PICO_TOOLCHAIN_PATH, 'bin')}${path.delimiter}${env.PATH || ''}` }
+  }
+  const probe = spawnSync('arm-none-eabi-gcc', ['-print-file-name=nosys.specs'], { env, encoding: 'utf8' })
+  const specs = (probe.stdout || '').trim()
+  if (probe.status === 0 && specs && specs !== 'nosys.specs' && existsSync(specs)) return env
+  const candidates = [
+    ...globDirs(path.join(os.homedir(), 'Tools', 'arm-gnu-toolchain-*', 'extract', 'Payload')),
+    ...globDirs('/Applications/ArmGNUToolchain/*/arm-none-eabi')
+  ]
+  for (const candidate of candidates) {
+    if (toolchainHasRuntime(candidate)) {
+      stderr(`Using RP2350 ARM toolchain: ${candidate}`)
+      return { ...env, PICO_TOOLCHAIN_PATH: candidate, PATH: `${path.join(candidate, 'bin')}${path.delimiter}${env.PATH || ''}` }
+    }
+  }
+  fail('RP2350 Pico SDK builds need an arm-none-eabi toolchain with newlib/nosys.specs.\nInstall the official Arm GNU Embedded toolchain or set PICO_TOOLCHAIN_PATH to its root.', ExitCode.missingDependency)
+}
+
+export function cmakeBinary(env) {
+  if (env.CMAKE) return env.CMAKE
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    if (dir && existsSync(path.join(dir, 'cmake'))) return path.join(dir, 'cmake')
+  }
+  for (const candidate of ['/opt/homebrew/bin/cmake', '/usr/local/bin/cmake', '/Applications/CMake.app/Contents/bin/cmake']) {
+    if (existsSync(candidate)) return candidate
+  }
+  fail('CMake is required for RP2350 Pico SDK builds. Install cmake or set CMAKE=/path/to/cmake.', ExitCode.missingDependency)
+}
+
+export function firmwareTarget(selection, app) {
+  const stem = firmwareStems[selection.target]
+  if (!stem) fail(`No RP2350 firmware target is registered for '${selection.target}'.`, ExitCode.usage)
+  return app ? `${stem}_app` : `${stem}_bringup`
+}
+
+function run(command, args, { cwd, env, dryRun, stdout, failureCode = ExitCode.buildFailed }) {
+  if (dryRun) {
+    stdout(formatCommand([command, ...args]))
+    return
+  }
+  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)
+}
+
+export function rp2350BuildDir(ctx, selection) {
+  return path.join(ctx.buildRoot, selection.target)
+}
+
+export function buildRp2350({ ctx, selection, app = null, env, dryRun = false, stdout, stderr, configureOnly = false }) {
+  const toolEnv = prepareArmToolchain(env, stderr)
+  const cmake = cmakeBinary(toolEnv)
+  const buildDir = rp2350BuildDir(ctx, selection)
+  const configure = ['-S', selection.targetDir, '-B', buildDir]
+  const buildEnv = { ...toolEnv }
+  if (app) {
+    const meta = appCmakeMeta(ctx, app)
+    configure.push(`-DGEA_EMBEDDED_APP=${app.id}`, `-DGEA_EMBEDDED_APP_META=${meta}`)
+    buildEnv.GEA_EMBEDDED_APP = app.id
+    buildEnv.GEA_EMBEDDED_APP_META = meta
+  }
+  run(cmake, configure, { cwd: selection.targetDir, env: buildEnv, dryRun, stdout })
+  if (configureOnly) return { buildDir, uf2: '' }
+  const target = firmwareTarget(selection, app)
+  run(cmake, ['--build', buildDir, '--target', target], { cwd: selection.targetDir, env: buildEnv, dryRun, stdout })
+  return { buildDir, uf2: path.join(buildDir, `${target}.uf2`) }
+}
+
+function bootselVolumes(env) {
+  const user = env.USER || 'user'
+  return [
+    ...globDirs('/Volumes/RPI-RP2*'),
+    ...globDirs('/Volumes/RP2350*'),
+    `/media/${user}/RPI-RP2`,
+    `/media/${user}/RP2350`,
+    `/run/media/${user}/RPI-RP2`,
+    `/run/media/${user}/RP2350`
+  ].filter((dir) => existsSync(dir))
+}
+
+export function flashRp2350({ selection, uf2, env, dryRun = false, stdout }) {
+  if (!dryRun && !existsSync(uf2)) fail(`UF2 image not found after build: ${uf2}`, ExitCode.deployFailed)
+  const [volume] = bootselVolumes(env)
+  if (volume) {
+    const copyArgs = process.platform === 'darwin' ? ['-X', uf2, `${volume}/`] : [uf2, `${volume}/`]
+    run('cp', copyArgs, { env, dryRun, stdout, failureCode: ExitCode.deployFailed })
+    if (!dryRun) spawnSync('sync', [], { stdio: 'ignore' })
+    stdout(`Copied UF2 to ${volume}. The board should reboot automatically.`)
+    return
+  }
+  const picotool = spawnSync('picotool', ['version'], { env, stdio: 'ignore' })
+  if (!picotool.error) {
+    const selectionArgs = selection.usbSerial ? resolvePicotoolSelection({ serial: selection.usbSerial }) : []
+    run('picotool', ['load', ...selectionArgs, '-f', '-x', uf2], { env, dryRun, stdout, failureCode: ExitCode.deployFailed })
+    return
+  }
+  if (dryRun) {
+    stdout(formatCommand(['picotool', 'load', '-f', '-x', uf2]))
+    return
+  }
+  fail('Could not flash RP2350 target.\nInstall picotool or put the board in BOOTSEL mode so RPI-RP2/RP2350 is mounted, then retry.', ExitCode.deployFailed)
+}

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,9 +3,9 @@ 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 { createChildEnv } from './context.mjs'
 import { ExitCode, fail } from './errors.mjs'
 import { exists, readJson, writeJson } from './fs-utils.mjs'
 import { ask, choose, confirm, createPrompt } from './prompts.mjs'
@@ -374,18 +374,14 @@ async function maybeInitializeBoardTarget(ctx, parsed, io, boardSetup) {
     io.stdout(`Board initialization skipped. Later: npx gea setup --board ${boardSetup.alias}`)
     return 0
   }
-  if (!exists(ctx.scripts.board)) {
-    io.stdout(`Board backend not found. Later: npx gea setup --board ${boardSetup.alias}`)
+  if (!ctx.targetsRoot) {
+    io.stdout(`@geastack/targets is not installed. Later: npx gea setup --board ${boardSetup.alias}`)
     return 0
   }
   io.stdout(`Initializing board target '${boardSetup.alias}'...`)
-  return runExternal(ctx.scripts.board, ['setup', `--board=${boardSetup.alias}`], {
-    cwd: ctx.targetsRoot,
-    env: createChildEnv(ctx, io.env || process.env),
-    dryRun: flag(parsed, 'dry-run'),
-    failureCode: ExitCode.buildFailed,
-    stdout: io.stdout
-  })
+  const { buildCommand } = await import('./commands/board.mjs')
+  const setupParsed = { ...parsed, options: { ...parsed.options, board: boardSetup.alias, 'configure-only': true } }
+  return buildCommand(ctx, setupParsed, [], io)
 }
 
 async function maybeSetupEspIdf(ctx, parsed, io, prompt, { force = false } = {}) {
@@ -468,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) {

package/src/taurus/adapter.mjs

@@ -0,0 +1,52 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { resolveUsbSerialPort } from '../boards/usb.mjs'
+import { CliError, ExitCode, fail } from '../errors.mjs'
+import { formatCommand } from '../run.mjs'
+
+// The one per-target hook: a target directory may ship a board.mjs whose
+// `commandFor({ action, app, port, serial, pedalRoot })` names the external
+// command to run. taurus-s3 uses it to defer to the taurus-pedal firmware
+// tree, which lives in its own repository.
+
+export function pedalRootCandidates(ctx, env) {
+  if (env.TAURUS_PEDAL_ROOT) return [path.resolve(env.TAURUS_PEDAL_ROOT)]
+  const targetsRoot = ctx.targetsRoot || ctx.projectRoot
+  return [path.resolve(targetsRoot, '../taurus-pedal'), path.resolve(targetsRoot, '../../coyotiv/taurus-pedal')]
+}
+
+export async function runTargetHook({ ctx, selection, action, app = null, env, dryRun = false, stdout }) {
+  const hook = path.join(selection.targetDir, 'board.mjs')
+  if (!existsSync(hook)) fail(`Target '${selection.target}' has no board.mjs hook at ${hook}.`, ExitCode.missingDependency)
+  const module = await import(pathToFileURL(hook).href)
+  if (typeof module.commandFor !== 'function') fail(`${hook} does not export commandFor().`, ExitCode.missingDependency)
+  const candidates = pedalRootCandidates(ctx, env)
+  const pedalRoot = candidates.find((candidate) => existsSync(path.join(candidate, 'esp32-s3-a2-full/flash-s3.sh'))) || ''
+  let port = selection.port
+  if (!port && selection.usbSerial && action === 'flash' && !dryRun) {
+    try {
+      port = resolveUsbSerialPort({ serial: selection.usbSerial })
+    } catch {
+      port = ''
+    }
+  }
+  let command
+  try {
+    command = module.commandFor({ action, app: app?.id || '', port, serial: selection.usbSerial, pedalRoot: pedalRoot || candidates[0] })
+  } catch (error) {
+    fail(error.message, ExitCode.usage)
+  }
+  if (!command) return 0
+  if (dryRun) {
+    stdout(formatCommand([command.executable, ...command.args]))
+    return 0
+  }
+  if (!pedalRoot) fail('Set TAURUS_PEDAL_ROOT to the taurus-pedal checkout; firmware sources remain in that repository.', ExitCode.missingDependency)
+  const result = spawnSync(command.executable, command.args, { env, stdio: 'inherit' })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new CliError(`ERROR: Command failed (${result.status ?? 1}): ${formatCommand([command.executable, ...command.args])}`, ExitCode.deployFailed)
+  return 0
+}