@geastack/cli 0.1.52 → 0.1.54

package/src/boards/usb.mjs

@@ -0,0 +1,252 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+
+// A board is identified by its USB SERIAL, never by a /dev path: enumerated
+// paths change on every plug-in and identical boards routinely share one.
+// Everything here maps a stable serial to whatever port the OS gave it today.
+
+const serialPatterns = [
+  /^cu\.usbmodem/,
+  /^tty\.usbmodem/,
+  /^cu\.usbserial/,
+  /^tty\.usbserial/,
+  /^cu\.SLAB_USBtoUART/,
+  /^tty\.SLAB_USBtoUART/,
+  /^ttyACM/,
+  /^ttyUSB/
+]
+
+export function serialPortCandidates() {
+  const dev = '/dev'
+  if (!existsSync(dev)) return []
+  return readdirSync(dev)
+    .filter((name) => serialPatterns.some((pattern) => pattern.test(name)))
+    .map((name) => path.join(dev, name))
+    .sort()
+}
+
+export function resolveAutoUsbPort() {
+  const candidates = serialPortCandidates()
+  const callout = candidates.filter((candidate) => path.basename(candidate).startsWith('cu.'))
+  const usable = callout.length > 0 ? callout : candidates
+  if (usable.length <= 1) return usable[0] || ''
+  throw new Error(
+    ['Multiple USB serial ports are present; use --board <alias> with a registered USB serial.', ...usable.map((c) => `  ${c}`)].join('\n')
+  )
+}
+
+export function normalizedSerial(value) {
+  return String(value || '').replace(/[^a-z0-9]/gi, '').toLowerCase()
+}
+
+function linuxSerialByIdCandidates(serial) {
+  const dir = '/dev/serial/by-id'
+  if (!existsSync(dir)) return []
+  const needle = normalizedSerial(serial)
+  return readdirSync(dir)
+    .filter((name) => normalizedSerial(name).includes(needle))
+    .map((name) => path.join(dir, name))
+}
+
+function ioregStringProperty(line, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return line.match(new RegExp(`"${escaped}"\\s*=\\s*"([^"]*)"`))?.[1] || ''
+}
+
+function ioregNumberProperty(line, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const value = line.match(new RegExp(`"${escaped}"\\s*=\\s*(\\d+)`))?.[1] || ''
+  return value ? Number(value) : 0
+}
+
+function macUsbDeviceForSerial(serial, ioreg = runIoreg) {
+  const output = ioreg(['-p', 'IOUSB', '-l', '-w0'])
+  let current = null
+  const devices = []
+  for (const line of output.split(/\r?\n/)) {
+    // One `| ` per nesting level -- devices behind hubs carry several.
+    const node = line.match(/^([\s|]*)[+\\-]*o .*@([0-9a-fA-F]+)\s+<class IOUSBHostDevice/)
+    if (node) {
+      if (current) devices.push(current)
+      current = { locationHex: node[2], text: line }
+      continue
+    }
+    if (current) current.text += `\n${line}`
+  }
+  if (current) devices.push(current)
+  const needle = normalizedSerial(serial)
+  return devices.find((device) =>
+    device.text.split(/\r?\n/).some((line) => {
+      const value = ioregStringProperty(line, 'kUSBSerialNumberString') || ioregStringProperty(line, 'USB Serial Number')
+      return value && normalizedSerial(value) === needle
+    })
+  ) || null
+}
+
+function locationDigits(locationHex) {
+  return locationHex.toLowerCase().replace(/^0+/, '').replace(/0+$/, '').replace(/[^0-9a-f]/g, '')
+}
+
+function macUsbCalloutPortsForSerial(serial, ioreg = runIoreg) {
+  const output = ioreg(['-p', 'IOService', '-l', '-w0'], { maxBuffer: 64 * 1024 * 1024 })
+  const stack = []
+  const matches = new Set()
+  const needle = normalizedSerial(serial)
+  for (const line of output.split(/\r?\n/)) {
+    const node = line.match(/^([\s|]*)[+\\-]*o\s+/)
+    if (node) {
+      const depth = (node[1].match(/\|/g) || []).length
+      while (stack.length > 0 && stack[stack.length - 1].depth >= depth) stack.pop()
+      stack.push({ depth, serial: '' })
+      continue
+    }
+    if (stack.length === 0) continue
+    const current = stack[stack.length - 1]
+    const serialValue = ioregStringProperty(line, 'kUSBSerialNumberString') || ioregStringProperty(line, 'USB Serial Number')
+    if (serialValue) current.serial = serialValue
+    const callout = ioregStringProperty(line, 'IOCalloutDevice')
+    if (!callout || !path.basename(callout).startsWith('cu.')) continue
+    const inherited = [...stack].reverse().find((entry) => entry.serial)?.serial || ''
+    if (normalizedSerial(inherited) === needle) matches.add(callout)
+  }
+  return [...matches].sort()
+}
+
+// Every USB callout port the registry knows, with the serial and product
+// name inherited from the enclosing USB device: the inverse of
+// macUsbCalloutPortsForSerial, for `gea boards discover` and the setup
+// wizard. The /dev name carries no identity (the usbmodem number changes on
+// every enumeration and identical boards share it), so this is the only
+// place a port's serial can come from on macOS.
+export function listMacUsbCalloutPorts(ioreg = runIoreg) {
+  let output = ''
+  try {
+    output = ioreg(['-p', 'IOService', '-l', '-w0'], { maxBuffer: 64 * 1024 * 1024 })
+  } catch {
+    return []
+  }
+  const stack = []
+  const ports = new Map()
+  for (const line of output.split(/\r?\n/)) {
+    const node = line.match(/^([\s|]*)[+\\-]*o\s+/)
+    if (node) {
+      const depth = (node[1].match(/\|/g) || []).length
+      while (stack.length > 0 && stack[stack.length - 1].depth >= depth) stack.pop()
+      stack.push({ depth, serial: '', product: '' })
+      continue
+    }
+    if (stack.length === 0) continue
+    const current = stack[stack.length - 1]
+    const serialValue = ioregStringProperty(line, 'kUSBSerialNumberString') || ioregStringProperty(line, 'USB Serial Number')
+    if (serialValue) current.serial = serialValue
+    const productValue = ioregStringProperty(line, 'kUSBProductString') || ioregStringProperty(line, 'USB Product Name')
+    if (productValue) current.product = productValue
+    const callout = ioregStringProperty(line, 'IOCalloutDevice')
+    if (!callout || !path.basename(callout).startsWith('cu.')) continue
+    // A callout with no USB serial above it is not a USB device at all
+    // (Bluetooth SPP, the debug console); probing those is a wasted timeout.
+    const serial = [...stack].reverse().find((entry) => entry.serial)?.serial || ''
+    if (!serial) continue
+    const label = [...stack].reverse().find((entry) => entry.product)?.product || ''
+    ports.set(callout, { path: callout, serial, label })
+  }
+  return [...ports.values()].sort((a, b) => a.path.localeCompare(b.path))
+}
+
+function runIoreg(args, options = {}) {
+  return execFileSync('ioreg', args, { encoding: 'utf8', ...options })
+}
+
+function resolveMacUsbSerialPort(serial, ioreg = runIoreg) {
+  const candidates = serialPortCandidates().filter((candidate) => path.basename(candidate).startsWith('cu.'))
+  const needle = normalizedSerial(serial)
+  const serialMatches = candidates.filter((candidate) => normalizedSerial(path.basename(candidate)).includes(needle))
+  if (serialMatches.length === 1) return serialMatches[0]
+
+  const location = macUsbDeviceForSerial(serial, ioreg)?.locationHex || ''
+  const digits = locationDigits(location)
+  if (digits) {
+    const locationMatches = candidates.filter((candidate) => normalizedSerial(path.basename(candidate)).includes(digits))
+    if (locationMatches.length === 1) return locationMatches[0]
+    const registryMatches = macUsbCalloutPortsForSerial(serial, ioreg)
+    if (registryMatches.length === 1) return registryMatches[0]
+    if (registryMatches.length > 1) {
+      throw new Error([`USB serial ${serial} maps to multiple /dev/cu.* ports:`, ...registryMatches.map((c) => `  ${c}`)].join('\n'))
+    }
+  }
+  throw new Error(`Could not map USB serial ${serial} to a /dev/cu.* port. Check that the board is attached.`)
+}
+
+export function resolveUsbSerialPort({ serial }, { platform = process.platform, ioreg = runIoreg } = {}) {
+  if (!serial) throw new Error('A USB serial number is required to locate the board; /dev paths are not accepted.')
+  if (platform === 'linux') {
+    const matches = linuxSerialByIdCandidates(serial)
+    if (matches.length === 1) return realpathSync(matches[0])
+    throw new Error(`Could not map USB serial ${serial} to a /dev/serial/by-id entry. Check that the board is attached.`)
+  }
+  if (platform === 'darwin') return resolveMacUsbSerialPort(serial, ioreg)
+  throw new Error(`USB serial lookup is not implemented on ${platform}.`)
+}
+
+// picotool selects by bus/address on macOS (its --ser matching is unreliable
+// there); everywhere else the serial itself is the selector.
+export function resolvePicotoolSelection({ serial }, { platform = process.platform, ioreg = runIoreg } = {}) {
+  if (!serial) return []
+  if (platform !== 'darwin') return ['--ser', serial]
+  let device = null
+  try {
+    device = macUsbDeviceForSerial(serial, ioreg)
+  } catch {
+    device = null
+  }
+  if (!device?.locationHex) return ['--ser', serial]
+  const bus = Number.parseInt(device.locationHex.slice(0, 2), 16)
+  const address = device.text
+    .split(/\r?\n/)
+    .map((line) => ioregNumberProperty(line, 'USB Address') || ioregNumberProperty(line, 'kUSBAddress'))
+    .find(Boolean) || 0
+  if (!bus || !address) return ['--ser', serial]
+  return ['--bus', String(bus), '--address', String(address)]
+}
+
+// Poll until the board's port exists. A board reboots (and re-enumerates)
+// after a flash, so callers retry on the SERIAL, not on a cached path.
+export async function waitForSerialPort({
+  port = '',
+  serial = '',
+  timeoutSeconds = 300,
+  label = 'USB serial port',
+  pollSeconds = 1,
+  log = (line) => process.stderr.write(`${line}\n`),
+  resolver = resolveUsbSerialPort
+} = {}) {
+  const startedAt = Date.now()
+  let nextLog = startedAt
+  while (true) {
+    if (port) {
+      if (existsSync(port)) return port
+    } else if (serial) {
+      try {
+        const resolved = resolver({ serial })
+        if (resolved && existsSync(resolved)) return resolved
+      } catch {
+        // not attached yet
+      }
+    } else {
+      const candidate = serialPortCandidates()[0]
+      if (candidate) return candidate
+    }
+    const elapsed = (Date.now() - startedAt) / 1000
+    if (timeoutSeconds > 0 && elapsed >= timeoutSeconds) {
+      const where = port ? ` at ${port}` : serial ? ` with USB serial ${serial}` : ''
+      throw new Error(`Timed out waiting for ${label}${where}.`)
+    }
+    if (Date.now() >= nextLog) {
+      const where = port ? ` at ${port}` : serial ? ` with USB serial ${serial}` : ''
+      log(`Waiting for ${label}${where}...`)
+      nextLog = Date.now() + 5000
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollSeconds * 1000))
+  }
+}

package/src/chips.mjs

@@ -142,7 +142,7 @@ export function resolveTargetDefinition(ctx, parsed) {
   const configPath = option(parsed, 'boards-config')
     ? path.resolve(ctx.cwd, option(parsed, 'boards-config'))
     : ctx.projectBoardsConfig
-  if (!configPath || !exists(configPath)) fail('No project .gea/boards.json was found. Run gea setup and create a custom board first.', ExitCode.usage)
+  if (!configPath || !exists(configPath)) fail(`No board config was found at ${configPath || '.gea/boards.json'}. Run gea setup and create a custom board first.`, ExitCode.usage)
   const boards = readJson(configPath)
   const requested = option(parsed, 'board', '')
   const customBoards = Object.entries(boards).filter(([, entry]) => typeof entry?.targetDefinition === 'string' && entry.targetDefinition)

package/src/commands/apps.mjs

@@ -0,0 +1,204 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+
+import { flag, option, optionList } from '../args.mjs'
+import { loadTargets } from '../boards/targets.mjs'
+import { ExitCode, fail } from '../errors.mjs'
+import { exists } from '../fs-utils.mjs'
+import { appCmakeMeta, appSummary, assertValidApp, discoverApps, resolveRequestedApp } from '../manifest.mjs'
+
+// gea apps ... : the app catalog and everything generated from it.
+
+export async function appsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  const args = rest.slice(1)
+  switch (sub) {
+    case 'list': return listApps(ctx, parsed, options)
+    case 'inspect': return inspectApp(ctx, parsed, args, options)
+    case 'pack': return packApp(ctx, parsed, args, options)
+    case 'index': return appIndex(ctx, parsed, options)
+    case 'launcher': return launcher(ctx, parsed, options)
+    case 'icons': return icons(ctx, parsed, args, options)
+    case 'icon-sheet': return iconSheet(ctx, parsed, options)
+    case 'apple-icons': return appleIcons(ctx, parsed, args, options)
+    default:
+      fail(`Unknown apps subcommand '${sub}'. Expected list, inspect, pack, index, launcher, icons, icon-sheet, or apple-icons.`, ExitCode.usage)
+  }
+}
+
+function listApps(ctx, parsed, options) {
+  const target = option(parsed, 'target', '')
+  const apps = discoverApps(ctx).filter((app) => !target || app.targets?.[target] === true)
+  if (flag(parsed, 'json')) options.stdout(JSON.stringify(apps.map((app) => appSummary(ctx, app)), null, 2))
+  else for (const app of apps) options.stdout(app.id)
+  return 0
+}
+
+function inspectApp(ctx, parsed, args, options) {
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const format = option(parsed, 'format', flag(parsed, 'json') ? 'json' : 'text')
+  const summary = appSummary(ctx, app)
+  if (format === 'cmake') options.stdout(appCmakeMeta(ctx, app))
+  else if (format === 'shell') options.stdout(`${summary.root}\t${app.entry}\t${app.runtime}\t${app.name}`)
+  else if (format === 'json') options.stdout(JSON.stringify(summary, null, 2))
+  else options.stdout(`${app.id}\t${app.name}\t${summary.root}\t${app.entry}`)
+  return 0
+}
+
+async function packApp(ctx, parsed, args, options) {
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const target = option(parsed, 'target', 'geaos')
+  const { createGeaBundle } = await import('../apps/bundle-writer.mjs')
+  const out = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'dist', `${app.id}-${target}.gea.zip`)))
+  const artifactDir = option(parsed, 'artifact-dir', '')
+  const manifest = createGeaBundle({ repoRoot: ctx.projectRoot, app, target, outputPath: out, artifactDir: artifactDir ? path.resolve(ctx.cwd, artifactDir) : '' })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputPath: out, manifest }, null, 2) : out)
+  return 0
+}
+
+async function appIndex(ctx, parsed, options) {
+  const { generateAppIndex } = await import('../apps/app-index-writer.mjs')
+  const outputFile = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'simulator', 'src', 'generated', 'app-index.ts')))
+  const apps = generateAppIndex({ apps: discoverApps(ctx).map((app) => appSummary(ctx, app)), outputFile })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputFile, apps }, null, 2) : outputFile)
+  return 0
+}
+
+async function launcher(ctx, parsed, options) {
+  const { generateLauncherCatalog } = await import('../apps/launcher-catalog.mjs')
+  const target = option(parsed, 'target', 'geaos')
+  const outputFile = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'apps', 'app-launcher', 'generated', 'LauncherCatalog.tsx')))
+  const apps = generateLauncherCatalog({ repoRoot: ctx.projectRoot, apps: discoverApps(ctx), target, outputFile })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputFile, apps: apps.map((app) => appSummary(ctx, app)) }, null, 2) : outputFile)
+  return 0
+}
+
+async function icons(ctx, parsed, args, options) {
+  const requested = args[0] || option(parsed, 'app', '')
+  if (!requested) fail('gea apps icons <app-id|all> [--target <t>] [--model <m>] [--concurrency <n>] [--exclude a,b]', ExitCode.usage)
+  const { generateIconSets } = await import('../apps/openai-icons.mjs')
+  const excluded = new Set(optionList(parsed, 'exclude'))
+  const iconTarget = option(parsed, 'target', '')
+  const all = discoverApps(ctx)
+  const apps = requested === 'all'
+    ? all
+      .filter((app) => iconTarget && iconTarget !== 'all'
+        ? app.targets?.[iconTarget] === true
+        : ['geaos', 'esp32', 'ios', 'macos'].some((candidate) => app.targets?.[candidate] === true))
+      .filter((app) => !excluded.has(app.id))
+    : [resolveRequestedApp(ctx, parsed, [requested])]
+  await generateIconSets({
+    repoRoot: ctx.projectRoot,
+    apps,
+    model: option(parsed, 'model', ctx.env.GEA_OPENAI_IMAGE_MODEL || 'gpt-image-2'),
+    concurrency: Math.max(1, Number.parseInt(option(parsed, 'concurrency', '1'), 10) || 1)
+  })
+  return 0
+}
+
+// The Apple build scripts call this per app: the iOS generator wants an
+// AppIcon.appiconset inside its asset catalog, the macOS bundle wants an
+// AppIcon.icns in Resources. --signature prints a digest of every input the
+// icon depends on so the scripts can skip regeneration when nothing changed.
+async function appleIcons(ctx, parsed, args, options) {
+  const usage = 'gea apps apple-icons <app-id> --platform ios --assets-dir <dir> | --platform macos --build-dir <dir> --resources-dir <dir> [--signature]'
+  const app = resolveRequestedApp(ctx, parsed, args)
+  assertValidApp(app)
+  const platform = option(parsed, 'platform', '')
+  if (platform !== 'ios' && platform !== 'macos') fail(usage, ExitCode.usage)
+  const icons = await import('../apps/apple-icons.mjs')
+  const repoRoot = ctx.projectRoot
+  if (flag(parsed, 'signature')) {
+    const { createHash } = await import('node:crypto')
+    const { readFileSync } = await import('node:fs')
+    const hash = createHash('sha256')
+    const addFile = (file) => {
+      hash.update(file)
+      hash.update('\0')
+      hash.update(readFileSync(file))
+      hash.update('\0')
+    }
+    addFile(path.join(ctx.cliPackageRoot, 'src', 'apps', 'apple-icons.mjs'))
+    hash.update(JSON.stringify({ id: app.id, root: appSummary(ctx, app).root, icons: app.icons || {}, platform }))
+    addFile(icons.resolveAppleIconSourcePath(repoRoot, app))
+    options.stdout(hash.digest('hex'))
+    return 0
+  }
+  if (platform === 'ios') {
+    const assetsDir = option(parsed, 'assets-dir', '')
+    if (!assetsDir) fail(usage, ExitCode.usage)
+    options.stdout(icons.prepareIosAppIconAssets({ repoRoot, app, assetsDir: path.resolve(ctx.cwd, assetsDir) }))
+    return 0
+  }
+  const buildDir = option(parsed, 'build-dir', '')
+  const resourcesDir = option(parsed, 'resources-dir', '')
+  if (!buildDir || !resourcesDir) fail(usage, ExitCode.usage)
+  options.stdout(icons.prepareMacosAppIcon({ repoRoot, app, buildDir: path.resolve(ctx.cwd, buildDir), resourcesDir: path.resolve(ctx.cwd, resourcesDir) }))
+  return 0
+}
+
+async function iconSheet(ctx, parsed, options) {
+  const { generateIconStyleSheet } = await import('../apps/openai-icons.mjs')
+  const excluded = new Set(optionList(parsed, 'exclude'))
+  const iconTarget = option(parsed, 'target', 'geaos')
+  const outputPath = path.resolve(ctx.cwd, option(parsed, 'out', path.join(ctx.projectRoot, 'docs', 'icon-style-preview', `${iconTarget}-icon-style-sheet.png`)))
+  const apps = discoverApps(ctx)
+    .filter((app) => iconTarget === 'all' || app.targets?.[iconTarget] === true)
+    .filter((app) => flag(parsed, 'include-hidden') || !app.launcher.hidden)
+    .filter((app) => app.icons && Object.keys(app.icons).length > 0)
+    .filter((app) => !excluded.has(app.id))
+  if (apps.length === 0) fail(`No apps matched target '${iconTarget}'`, ExitCode.usage)
+  const sheet = await generateIconStyleSheet({
+    apps,
+    model: option(parsed, 'model', ctx.env.GEA_OPENAI_IMAGE_MODEL || 'gpt-image-2'),
+    outputPath,
+    columns: Math.max(1, Number.parseInt(option(parsed, 'columns', '5'), 10) || 5)
+  })
+  options.stdout(flag(parsed, 'json') ? JSON.stringify({ outputPath: sheet.outputPath, apps: apps.map((app) => appSummary(ctx, app)) }, null, 2) : sheet.outputPath)
+  return 0
+}
+
+// gea targets ...
+
+export function targetsCommand(ctx, parsed, rest, options) {
+  const sub = rest[0] || 'list'
+  let targets
+  try {
+    targets = loadTargets(ctx)
+  } catch (error) {
+    fail(error.message, ExitCode.missingDependency)
+  }
+  if (sub === 'list') {
+    if (flag(parsed, 'json')) options.stdout(JSON.stringify(targets, null, 2))
+    else for (const id of Object.keys(targets).sort()) options.stdout(`${id}\t${targets[id].adapter}\t${exists(targets[id].targetDir) ? targets[id].targetDir : '(not installed)'}`)
+    return 0
+  }
+  if (sub === 'show') {
+    const id = rest[1] || ''
+    if (!targets[id]) fail(`Unknown target '${id}'. Run gea targets list.`, ExitCode.usage)
+    options.stdout(JSON.stringify(targets[id], null, 2))
+    return 0
+  }
+  fail(`Unknown targets subcommand '${sub}'. Expected list or show.`, ExitCode.usage)
+}
+
+export async function heapReportCommand(ctx, parsed, rest, options) {
+  const { DEFAULT_TITLE, parseLogs, renderHtml } = await import('../heap-report.mjs')
+  const { mkdirSync, writeFileSync } = await import('node:fs')
+  let inputs = rest.map((file) => path.resolve(ctx.cwd, file))
+  const logsDir = path.join(ctx.projectRoot, 'docs', 'esp32-perf-logs')
+  if (inputs.length === 0 && exists(logsDir)) {
+    inputs = readdirSync(logsDir).filter((name) => /\.(txt|log)$/.test(name)).map((name) => path.join(logsDir, name))
+  }
+  if (inputs.length === 0) fail('No heap log inputs found. Pass log files or place .txt/.log files in docs/esp32-perf-logs/.', ExitCode.usage)
+  const out = path.resolve(ctx.cwd, option(parsed, 'out', path.join(logsDir, 'heap-map-report.html')))
+  const maps = optionList(parsed, 'map').map((file) => path.resolve(ctx.cwd, file))
+  const data = parseLogs(inputs, maps)
+  mkdirSync(path.dirname(out), { recursive: true })
+  writeFileSync(out, renderHtml(data, option(parsed, 'title', DEFAULT_TITLE)))
+  options.stdout(`Wrote heap map report: ${out}`)
+  options.stdout(`Parsed ${data.snapshots.length} heap-map snapshots, ${data.probes.length} probes, ${data.liveAllocations.length} live allocations, ${data.linkerMaps.length} linker map(s)`)
+  return 0
+}