@geastack/cli 0.1.9 → 0.1.10

package/README.md

@@ -73,20 +73,13 @@ flowchart TD
   ota --> reviewKnown["Review board setup"]
   reviewKnown --> writeKnown["Write .gea/boards.json"]
 
-  interactive -->|"Custom board profile"| custom["Collect hardware profile"]
-  custom --> core["Alias, MCU, closest base target"]
-  core --> depth{"Detail level?"}
-  depth -->|"Full"| chips["Display, touch,<br/>WiFi/BLE, GPS, audio"]
-  depth -->|"Fast"| fast["Display, touch,<br/>default peripherals"]
-  chips --> peripherals["Storage, sensors, power,<br/>USB serial or OTA"]
-  fast --> connection["USB serial or OTA"]
-  peripherals --> connection
-  connection --> notes["Notes and datasheet links"]
-  notes --> reviewCustom["Review custom profile"]
-  reviewCustom --> writeProfile["Write .gea/boards/alias.json"]
-  writeProfile --> maybeAlias{"Base target selected?"}
-  maybeAlias -->|"Yes"| writeCustomAlias["Write alias to .gea/boards.json"]
-  maybeAlias -->|"No"| profileOnly["Profile only, not flash-ready yet"]
+  interactive -->|"Custom board target"| custom["Choose MCU and compatible chips"]
+  custom --> chipConfig["Ask interface and pin questions<br/>from @geastack/chips/catalog.json"]
+  chipConfig --> features["Optional microSD and launcher button"]
+  features --> connection["Detect initial USB connection"]
+  connection --> reviewCustom["Review native composition"]
+  reviewCustom --> writeProfile["Write .gea/targets/alias.json"]
+  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"]
@@ -94,7 +87,6 @@ flowchart TD
   writeKnown --> initialize["Initialize board target"]
   writeCustomAlias --> initialize
   initialize --> ready["Ready: npx gea flash --board alias --monitor"]
-  profileOnly --> done["Done"]
   npmInstall --> done
   idfOnly --> done
   directIdf --> done
@@ -107,6 +99,19 @@ host bindings, and the other native packages from npm. A project can use a
 local CLI with `npx gea` or a global installation with `gea`; neither command
 depends on a GeaStack source checkout.
 
+Custom boards remain editable after setup:
+
+```sh
+gea chips list
+gea chips info co5300
+gea chips add co5300 ft3168 --board my-board
+gea chips remove ft3168 --board my-board
+```
+
+These commands update the app-local target definition. They do not copy native
+sources into the application; the target adapter compiles the selected drivers
+directly from the installed `@geastack/chips` package.
+
 ## Development
 
 ```sh

package/docs/NPX-COMMANDS.md

@@ -23,7 +23,7 @@ Use these release packages instead:
   the `create-geastack` bin.
 - `@geastack/cli`: scoped private Gea CLI package exposing the `gea` bin.
 
-`create-geastack` should add `@geastack/cli` as a devDependency in generated
+`create-geastack` should add `@geastack/cli` as a dependency in generated
 projects and install dependencies by default in interactive terminals. After
 that, inside the project, `npx gea ...` works because npm finds the local
 `node_modules/.bin/gea` binary. It does not require an npm package named `gea`.
@@ -31,7 +31,7 @@ that, inside the project, `npx gea ...` works because npm finds the local
 If someone is wiring an existing app by hand, install the package first:
 
 ```sh
-npm install --save-dev @geastack/cli
+npm install @geastack/cli
 npx gea setup
 ```
 
@@ -89,7 +89,7 @@ packages are scoped and configured for restricted npmjs publication.
 `gea setup` with no `--board` or `--target` opens a guided setup flow:
 
 - known supported board, with descriptions for each board;
-- custom board profile, with fast and full hardware paths;
+- custom board target composed from the installed chip catalog;
 - npm dependency check/install only;
 - ESP-IDF toolchain check/install only.
 
@@ -102,38 +102,35 @@ initializes the selected board target so the next command can be
 .gea/boards.json
 ```
 
-Custom-board setup can run in two depths:
-
-- `Full hardware profile`: display, touch, WiFi/BLE, GPS, audio, storage,
-  sensors, power, transport, and notes.
-- `Fast profile`: core board identity, display/touch, transport, and inferred
-  defaults for optional peripherals.
-
-Both paths show a review screen before writing a profile under:
+Custom-board setup reads `@geastack/chips/catalog.json`, offers only drivers
+with a compatible platform binding, and asks the configuration questions
+declared by each selected driver. It shows a review before writing the target:
 
 ```text
-.gea/boards/<alias>.json
+.gea/targets/<alias>.json
 ```
 
-The full profile captures:
+The target captures:
 
 - MCU / SoC;
-- closest existing base target;
-- display type, controller, interface, resolution;
-- touch controller and interface;
-- WiFi and BLE;
-- GPS module and interface;
-- audio codec, input, and output;
-- storage;
-- sensors;
-- power path;
-- USB serial and OTA transports;
-- notes/datasheet links.
-
-If the user selects a base target, the wizard also writes an experimental board
-alias that points at that base target and references the custom profile. If no
-base target is selected, the profile is generated without claiming the board is
-flash-ready.
+- the generic platform base and adapter;
+- display controller, interface, dimensions, bus, and pins;
+- touch controller, bus, reset, and interrupt pins;
+- power, IMU, and audio drivers;
+- shared buses and audio pins;
+- optional storage and launcher-button pins;
+- the initial USB serial connection.
+
+The wizard also writes `.gea/boards.json`, where the physical board alias points
+to that definition. A partial composition is saved but is not described as
+flash-ready. It can be completed later with:
+
+```sh
+npx gea chips list
+npx gea chips info co5300
+npx gea chips add co5300 --board my-board
+npx gea chips remove co5300 --board my-board
+```
 
 ESP-IDF setup is available as:
 

package/docs/SPEC.md

@@ -87,6 +87,23 @@ The CLI should pass through board aliases from the active board config. A projec
 uses its own `.gea/boards.json`; otherwise the CLI reads the board catalog shipped
 by the installed `@geastack/targets` package.
 
+### `gea chips`
+
+Inspects the installed `@geastack/chips` catalog and composes a custom board
+definition without copying native driver source into the app.
+
+```sh
+gea chips list
+gea chips info co5300
+gea chips add co5300 ft3168 --board my-board
+gea chips remove ft3168 --board my-board
+```
+
+`add` asks only the interface and pin questions declared by each chip. Automation
+can answer them with repeated `--set chip.path=value` options. The command rejects
+chips without a binding for the board adapter and MCU before changing the target
+definition.
+
 ### `gea monitor`
 
 Starts a log monitor for a configured board or target.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
   "publishConfig": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@geastack/core": "0.1.4",
-    "@geastack/targets": "0.1.4"
+    "@geastack/targets": "0.1.5"
   },
   "scripts": {
     "check": "node --check bin/gea.mjs && node --check bin/create-geastack.mjs && find src test packages -name '*.mjs' -print0 | xargs -0 -n1 node --check",

package/src/chips.mjs

@@ -0,0 +1,295 @@
+import path from 'node:path'
+
+import { flag, option } from './args.mjs'
+import { ExitCode, fail } from './errors.mjs'
+import { exists, readJson, writeJson } from './fs-utils.mjs'
+import { ask, choose, createPrompt } from './prompts.mjs'
+
+export async function runChips(ctx, parsed, rest, io = {}) {
+  const action = rest[0] || 'list'
+  const chipIds = rest.slice(1)
+  const stdout = io.stdout || console.log
+  const catalog = loadChipCatalog(ctx)
+
+  if (action === 'list') {
+    const entries = Object.entries(catalog).sort((a, b) => a[0].localeCompare(b[0]))
+    if (flag(parsed, 'json')) stdout(JSON.stringify(Object.fromEntries(entries), null, 2))
+    else {
+      for (const [id, chip] of entries) {
+        const adapters = Object.keys(chip.adapters || {})
+        stdout(`${id}\t${chip.category}\t${chip.label}${adapters.length ? `\t${adapters.join(',')}` : '\tunbound'}`)
+      }
+    }
+    return 0
+  }
+
+  if (action === 'info') {
+    if (chipIds.length !== 1) fail('chips info requires one chip id.', ExitCode.usage)
+    const chip = catalog[chipIds[0]]
+    if (!chip) failUnknownChip(chipIds[0], catalog)
+    if (flag(parsed, 'json')) stdout(JSON.stringify({ id: chipIds[0], ...chip }, null, 2))
+    else {
+      stdout(`${chipIds[0]}: ${chip.label}`)
+      stdout(`Category: ${chip.category}`)
+      stdout(`Interfaces: ${(chip.interfaces || []).join(', ') || 'none'}`)
+      stdout(`Adapters: ${Object.keys(chip.adapters || {}).join(', ') || 'no platform binding yet'}`)
+      for (const field of chip.configuration || []) stdout(`Configure: ${field.path} (${field.label})`)
+    }
+    return 0
+  }
+
+  if (action !== 'add' && action !== 'remove') {
+    fail(`Unknown chips action '${action}'. Expected list, info, add, or remove.`, ExitCode.usage)
+  }
+  if (chipIds.length === 0) fail(`chips ${action} requires at least one chip id.`, ExitCode.usage)
+
+  const location = resolveTargetDefinition(ctx, parsed)
+  const definition = readJson(location.definitionPath)
+  definition.chips ||= {}
+
+  if (action === 'remove') {
+    for (const id of chipIds) {
+      const role = Object.keys(definition.chips).find((key) => selectedDriver(definition.chips[key]) === id)
+      if (!role) fail(`Chip '${id}' is not selected by board '${location.boardName}'.`, ExitCode.usage)
+      delete definition.chips[role]
+      stdout(`Removed ${id} from ${location.boardName}.`)
+    }
+    writeJson(location.definitionPath, definition)
+    return 0
+  }
+
+  const prompt = createPrompt(io)
+  try {
+    const provided = parseSetOptions(parsed)
+    for (const id of chipIds) {
+      const descriptor = catalog[id]
+      if (!descriptor) failUnknownChip(id, catalog)
+      const role = await configureChipSelection({
+        definition,
+        id,
+        descriptor,
+        provided,
+        prompt,
+        io,
+        replace: flag(parsed, 'replace'),
+        boardName: location.boardName
+      })
+      stdout(`Added ${id} as ${role} on ${location.boardName}.`)
+    }
+    if (provided.size > 0) {
+      fail(`Unused --set values: ${[...provided.keys()].join(', ')}`, ExitCode.usage)
+    }
+    validateGpioAssignments(definition)
+    writeJson(location.definitionPath, definition)
+    stdout(`Updated ${location.definitionPath}`)
+    return 0
+  } finally {
+    await prompt.close()
+  }
+}
+
+export async function configureChipSelection({ definition, id, descriptor, provided = new Map(), prompt, io = {}, replace = false, boardName = definition.id }) {
+  definition.chips ||= {}
+  const adapter = definition.adapter || 'esp32-idf'
+  const binding = descriptor.adapters?.[adapter]
+  if (!binding) fail(`Chip '${id}' has no ${adapter} binding. 'gea chips info ${id}' shows its current support.`, ExitCode.targetUnavailable)
+  if (Array.isArray(binding.mcus) && !binding.mcus.includes(definition.mcu)) {
+    fail(`Chip '${id}' does not support MCU '${definition.mcu}' through ${adapter}.`, ExitCode.targetUnavailable)
+  }
+
+  const role = descriptor.category
+  const previous = definition.chips[role]
+  if (previous && selectedDriver(previous) !== id && !replace) {
+    fail(`Board '${boardName}' already uses '${selectedDriver(previous)}' as ${role}. Pass --replace to change it.`, ExitCode.usage)
+  }
+  const selection = previous && selectedDriver(previous) === id ? structuredClone(previous) : { driver: id }
+  selection.driver = id
+  delete selection.controller
+  selection.interface = await configuredInterface({ id, descriptor, selection, provided, prompt, io })
+  if (selection.interface === 'i2c') {
+    definition.buses ||= {}
+    definition.buses.i2c ||= {}
+    await configureFields({
+      id: 'i2c',
+      target: definition.buses.i2c,
+      fields: [
+        { path: 'sda', label: 'Shared I2C SDA pin', type: 'pin' },
+        { path: 'scl', label: 'Shared I2C SCL pin', type: 'pin' }
+      ],
+      provided,
+      prompt,
+      io
+    })
+  }
+  await configureFields({ id, target: selection, fields: descriptor.configuration || [], provided, prompt, io })
+  definition.chips[role] = selection
+  return role
+}
+
+export function loadChipCatalog(ctx) {
+  const catalogPath = path.join(ctx.chipsPackageDir || '', 'catalog.json')
+  if (!ctx.chipsPackageDir || !exists(catalogPath)) {
+    fail(`Missing @geastack/chips catalog: ${catalogPath || '@geastack/chips/catalog.json'}`, ExitCode.missingDependency)
+  }
+  const catalog = readJson(catalogPath)
+  if (catalog.schemaVersion !== 1 || !catalog.chips || typeof catalog.chips !== 'object') {
+    fail(`Unsupported @geastack/chips catalog schema in ${catalogPath}.`, ExitCode.missingDependency)
+  }
+  return catalog.chips
+}
+
+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)
+  const boards = readJson(configPath)
+  const requested = option(parsed, 'board', '')
+  const customBoards = Object.entries(boards).filter(([, entry]) => typeof entry?.targetDefinition === 'string' && entry.targetDefinition)
+  const boardName = requested || (customBoards.length === 1 ? customBoards[0][0] : '')
+  if (!boardName) fail('Select a custom board with --board <alias>.', ExitCode.usage)
+  const board = boards[boardName]
+  if (!board) fail(`Unknown board '${boardName}' in ${configPath}.`, ExitCode.usage)
+  if (!board.targetDefinition) fail(`Board '${boardName}' is a preset and has no editable target definition.`, ExitCode.usage)
+  const definitionPath = path.resolve(path.dirname(configPath), board.targetDefinition)
+  if (!exists(definitionPath)) fail(`Target definition for '${boardName}' does not exist: ${definitionPath}`, ExitCode.usage)
+  return { boardName, board, configPath, definitionPath }
+}
+
+export function validateGpioAssignments(definition) {
+  const pins = []
+  collectGpioAssignments(definition, [], false, pins)
+  const used = new Map()
+  for (const [label, pin] of pins) {
+    const previous = used.get(pin)
+    if (previous) fail(`GPIO ${pin} is assigned to both ${previous} and ${label}.`, ExitCode.usage)
+    used.set(pin, label)
+  }
+}
+
+function collectGpioAssignments(value, pathParts, pinMap, out) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return
+  for (const [key, entry] of Object.entries(value)) {
+    const nextPath = [...pathParts, key]
+    const nextPinMap = pinMap || key === 'pins' || pathParts[0] === 'buses'
+    if (typeof entry === 'number' && entry >= 0 && (nextPinMap || key === 'pin')) {
+      out.push([nextPath.join('.'), entry])
+    } else if (entry && typeof entry === 'object') {
+      collectGpioAssignments(entry, nextPath, nextPinMap, out)
+    }
+  }
+}
+
+async function configuredInterface({ id, descriptor, selection, provided, prompt, io }) {
+  const interfaces = Array.isArray(descriptor.interfaces) ? descriptor.interfaces : []
+  const supplied = provided.get(`${id}.interface`)
+  if (supplied !== undefined) {
+    provided.delete(`${id}.interface`)
+    if (!interfaces.includes(supplied)) fail(`Chip '${id}' does not support interface '${supplied}'.`, ExitCode.usage)
+    return supplied
+  }
+  if (selection.interface && interfaces.includes(selection.interface)) return selection.interface
+  if (interfaces.length === 1) return interfaces[0]
+  if (!canAnswer(prompt, io)) fail(`Set ${id}.interface with --set ${id}.interface=<value>.`, ExitCode.usage)
+  return choose(prompt, {
+    message: `${descriptor.label} interface`,
+    choices: interfaces.map((value) => ({ value, label: value.toUpperCase() })),
+    defaultValue: interfaces[0]
+  })
+}
+
+async function configureFields({ id, target, fields, provided, prompt, io }) {
+  for (const field of fields) {
+    const supplied = provided.get(`${id}.${field.path}`)
+    if (supplied !== undefined) {
+      provided.delete(`${id}.${field.path}`)
+      const error = validateFieldValue(supplied, field)
+      if (error) fail(`Invalid ${id}.${field.path}: ${error}.`, ExitCode.usage)
+      setPath(target, field.path, parseFieldValue(supplied, field))
+      continue
+    }
+    const current = getPath(target, field.path)
+    if (current !== undefined && current !== null) continue
+    if (!canAnswer(prompt, io)) {
+      if (field.default !== undefined) {
+        setPath(target, field.path, field.default)
+        continue
+      }
+      if (field.optional) {
+        setPath(target, field.path, null)
+        continue
+      }
+      fail(`Missing ${id}.${field.path}. Pass --set ${id}.${field.path}=<value> or run interactively.`, ExitCode.usage)
+    }
+    if (field.type === 'choice') {
+      const value = await choose(prompt, {
+        message: field.label,
+        choices: field.values.map((entry) => ({ value: entry, label: entry })),
+        defaultValue: field.default || field.values[0]
+      })
+      setPath(target, field.path, value)
+      continue
+    }
+    const value = await ask(prompt, {
+      message: field.optional ? `${field.label} (blank for none)` : field.label,
+      defaultValue: field.default === undefined ? '' : String(field.default),
+      validate: (entry) => validateFieldValue(entry, field)
+    })
+    setPath(target, field.path, field.optional && value === '' ? null : parseFieldValue(value, field))
+  }
+}
+
+function parseSetOptions(parsed) {
+  const raw = parsed.options.set
+  const entries = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw]
+  const out = new Map()
+  for (const entry of entries) {
+    const index = String(entry).indexOf('=')
+    if (index <= 0) fail(`Invalid --set '${entry}'. Expected --set chip.path=value.`, ExitCode.usage)
+    out.set(String(entry).slice(0, index), String(entry).slice(index + 1))
+  }
+  return out
+}
+
+function parseFieldValue(value, field) {
+  if (field.optional && (value === '' || value === 'none' || value === 'null')) return null
+  if (field.type === 'integer' || field.type === 'pin') return Number.parseInt(value, 10)
+  return String(value)
+}
+
+function validateFieldValue(value, field) {
+  if (field.optional && value === '') return ''
+  if (field.type === 'choice') return field.values.includes(value) ? '' : `choose one of ${field.values.join(', ')}`
+  if (field.type !== 'integer' && field.type !== 'pin') return ''
+  if (!/^-?\d+$/.test(String(value))) return 'enter an integer'
+  const number = Number(value)
+  const min = field.type === 'pin' ? 0 : field.min
+  const max = field.type === 'pin' ? 48 : field.max
+  if (min !== undefined && number < min) return `minimum is ${min}`
+  if (max !== undefined && number > max) return `maximum is ${max}`
+  return ''
+}
+
+function getPath(value, dottedPath) {
+  return dottedPath.split('.').reduce((current, part) => current?.[part], value)
+}
+
+function setPath(value, dottedPath, next) {
+  const parts = dottedPath.split('.')
+  let current = value
+  for (const part of parts.slice(0, -1)) current = current[part] ||= {}
+  current[parts.at(-1)] = next
+}
+
+function selectedDriver(selection) {
+  return String(selection?.driver || selection?.controller || '')
+}
+
+function failUnknownChip(id, catalog) {
+  const available = Object.keys(catalog).sort().join(', ')
+  fail(`Unknown chip '${id}'. Available chips: ${available}`, ExitCode.usage)
+}
+
+function canAnswer(prompt, io) {
+  return Boolean(io.prompt || io.stdin?.isTTY || (!io.stdin && process.stdin.isTTY))
+}

package/src/context.mjs

@@ -13,7 +13,7 @@ export function createContext(parsed, _env = process.env, cwd = process.cwd()) {
   const absoluteCwd = path.resolve(cwd)
   const projectRoot = findNodeProjectRoot(absoluteCwd) || absoluteCwd
   const initialAnchors = [projectRoot, cliPackageRoot]
-  const targetsRoot = resolveInstalledPackageDir('@geastack/targets', initialAnchors)
+  const targetsRoot = _env.GEA_TARGETS_ROOT || resolveInstalledPackageDir('@geastack/targets', initialAnchors)
   const corePackageDir = resolveInstalledPackageDir('@geastack/core', initialAnchors)
   const packageAnchors = [projectRoot, cliPackageRoot, targetsRoot, corePackageDir].filter(Boolean)
   const compilerPackageDir = resolveInstalledPackageDir('@geastack/compiler', packageAnchors)
@@ -28,7 +28,7 @@ export function createContext(parsed, _env = process.env, cwd = process.cwd()) {
     cliPackageRoot,
     compilerPackageDir,
     corePackageDir,
-    chipsPackageDir: resolveInstalledPackageDir('@geastack/chips', packageAnchors),
+    chipsPackageDir: _env.GEA_CHIPS_DIR || resolveInstalledPackageDir('@geastack/chips', packageAnchors),
     elementsPackageDir: resolveInstalledPackageDir('@geastack/elements', packageAnchors),
     enginePackageDir: resolveInstalledPackageDir('@geastack/engine', packageAnchors),
     geaosPackageDir: resolveInstalledPackageDir('@geastack/geaos', packageAnchors),

package/src/create-geastack.mjs

@@ -308,11 +308,11 @@ function packageJson({ appId, displayName, targets, entry, coreDependency, cliDe
     dependencies: {
       ...(sourcePackage.dependencies || {}),
       '@geajs/core': sourcePackage.dependencies?.['@geajs/core'] || '^1.3.0',
-      '@geastack/core': coreDependency
+      '@geastack/core': coreDependency,
+      '@geastack/cli': cliDependency
     },
     devDependencies: {
       ...(sourcePackage.devDependencies || {}),
-      '@geastack/cli': cliDependency,
       typescript: sourcePackage.devDependencies?.typescript || 'latest',
       ...(targets.web ? { vite: sourcePackage.devDependencies?.vite || 'latest' } : {})
     },

package/src/gea.mjs

@@ -3,6 +3,7 @@ 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 { ExitCode, fail } from './errors.mjs'
 import { exists, readJson } from './fs-utils.mjs'
@@ -59,6 +60,8 @@ export async function runGea(argv, io = {}) {
       return build(ctx, parsed, rest, { stdout, env })
     case 'setup':
       return setup(ctx, parsed, { stdout, env, stdin, output, prompt })
+    case 'chips':
+      return runChips(ctx, parsed, rest, { stdout, env, stdin, output, prompt })
     case 'flash':
       return flash(ctx, parsed, rest, { stdout, env })
     case 'monitor':
@@ -432,6 +435,10 @@ function 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]

package/src/setup-wizard.mjs

@@ -3,6 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 
 import { knownBoards } from './board-catalog.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'
@@ -143,7 +144,7 @@ async function setupKnownBoard(ctx, parsed, io, prompt) {
 }
 
 async function setupCustomBoard(ctx, parsed, io, prompt) {
-  renderStep(io, 'Board', ['Name the profile and pick the closest target backend.'])
+  renderStep(io, 'Board', ['Create an app-local hardware target from the installed chip catalog.'])
   const alias = await ask(prompt, {
     message: 'Custom board alias',
     defaultValue: 'custom-board',
@@ -151,230 +152,119 @@ async function setupCustomBoard(ctx, parsed, io, prompt) {
   })
   const mcu = await choose(prompt, {
     message: 'MCU / SoC',
-    choices: [
-      { value: 'esp32-s3', label: 'ESP32-S3' },
-      { value: 'esp32-p4', label: 'ESP32-P4' },
-      { value: 'esp32-c6', label: 'ESP32-C6' },
-      { value: 'esp32', label: 'ESP32' },
-      { value: 'other', label: 'Other / not listed' }
-    ],
-    defaultValue: 'esp32-s3'
-  })
-  const mcuName = mcu === 'other' ? await ask(prompt, { message: 'MCU / SoC name', defaultValue: '' }) : mcu
-  const baseTarget = await choose(prompt, {
-    message: 'Closest existing target to start from',
-    choices: [
-      { value: '', label: 'None yet, generate profile only' },
-      ...knownBoards.map((board) => ({ value: board.target, label: `${board.label} (${board.target})` }))
-    ],
-    defaultValue: ''
-  })
-  const depth = await choose(prompt, {
-    message: 'How much hardware detail do you want to enter?',
     choices: [
       {
-        value: 'full',
-        label: 'Full hardware profile',
-        description: 'Display, touch, wireless, GPS, audio, storage, sensors, power, and transport.'
-      },
-      {
-        value: 'quick',
-        label: 'Fast profile',
-        description: 'Core board, display/touch, transport, and sensible defaults for everything else.'
+        value: 'esp32s3',
+        label: 'ESP32-S3',
+        description: 'Composable ESP-IDF target with display, touch, power, IMU, audio, WiFi, BLE, and OTA support.'
       }
     ],
-    defaultValue: 'full'
+    defaultValue: 'esp32s3'
   })
 
-  renderStep(io, 'Display and touch', ['Describe what the user can see and touch on the board.'])
-  const displayKind = await choose(prompt, {
-    message: 'Display type',
-    choices: [
-      { value: 'amoled', label: 'AMOLED' },
-      { value: 'tft-lcd', label: 'TFT LCD' },
-      { value: 'epaper', label: 'E-paper' },
-      { value: 'monochrome-oled', label: 'Monochrome OLED' },
-      { value: 'none', label: 'No display' },
-      { value: 'other', label: 'Other' }
-    ],
-    defaultValue: 'tft-lcd'
-  })
-  const displayController = displayKind === 'none' ? '' : await ask(prompt, { message: 'Display controller/chip', defaultValue: '' })
-  const displayInterface = displayKind === 'none' ? '' : await choose(prompt, {
-    message: 'Display interface',
-    choices: [
-      { value: 'spi', label: 'SPI' },
-      { value: 'qspi', label: 'QSPI' },
-      { value: 'rgb', label: 'RGB parallel' },
-      { value: 'i8080', label: '8080 parallel' },
-      { value: 'mipi-dsi', label: 'MIPI DSI' },
-      { value: 'i2c', label: 'I2C' },
-      { value: 'other', label: 'Other' }
-    ],
-    defaultValue: 'spi'
-  })
-  const resolution = displayKind === 'none' ? '' : await ask(prompt, { message: 'Display resolution, for example 480x480', defaultValue: '' })
-  const touchController = await ask(prompt, { message: 'Touch controller/chip (blank for none)', defaultValue: '' })
-  const touchInterface = touchController ? await choose(prompt, {
-    message: 'Touch interface',
-    choices: [
-      { value: 'i2c', label: 'I2C' },
-      { value: 'spi', label: 'SPI' },
-      { value: 'gpio', label: 'GPIO buttons/interrupts' },
-      { value: 'other', label: 'Other' }
-    ],
-    defaultValue: 'i2c'
-  }) : ''
-
-  const defaults = defaultCustomPeripherals(mcuName)
-  let wifi = defaults.wifi
-  let ble = defaults.ble
-  let gpsModule = ''
-  let gpsInterface = ''
-  let audioCodec = ''
-  let audioOutput = ''
-  let audioInput = ''
-  let storage = defaults.storage
-  let sensors = ''
-  let power = 'USB'
-
-  if (depth === 'full') {
-    renderStep(io, 'Peripherals', ['Add wireless, location, audio, storage, sensors, and power details.'])
-    wifi = await choose(prompt, {
-      message: 'WiFi',
+  const definition = {
+    id: alias,
+    extends: 'esp32-s3',
+    adapter: 'esp32-idf',
+    mcu,
+    buses: {},
+    chips: {},
+    storage: {
+      microSD: {
+        interface: 'sdmmc-1bit',
+        pins: { clk: null, cmd: null, data0: null }
+      }
+    },
+    controls: {
+      launcherButton: { pin: null, activeLevel: 0 }
+    }
+  }
+
+  const catalog = loadChipCatalog(ctx)
+  const roles = [
+    ['display', 'Display controller'],
+    ['touch', 'Touch controller'],
+    ['power', 'Power-management controller'],
+    ['imu', 'Inertial measurement unit'],
+    ['audio', 'Audio codec']
+  ]
+  renderStep(io, 'Chips', ['Choose each controller from @geastack/chips. Pin questions come from the installed catalog.'])
+  for (const [role, label] of roles) {
+    const compatible = Object.entries(catalog)
+      .filter(([, chip]) => chip.category === role && chip.adapters?.['esp32-idf']?.mcus?.includes(mcu))
+    const selected = await choose(prompt, {
+      message: label,
       choices: [
-        { value: 'built-in', label: 'Built into MCU/module' },
-        { value: 'external', label: 'External WiFi chip/module' },
-        { value: 'none', label: 'None' }
+        ...compatible.map(([id, chip]) => ({ value: id, label: `${id} — ${chip.label}` })),
+        { value: '', label: 'None / configure later' }
       ],
-      defaultValue: defaults.wifi
+      defaultValue: compatible[0]?.[0] || ''
     })
-    ble = await choose(prompt, {
-      message: 'BLE',
-      choices: [
-        { value: 'built-in', label: 'Built into MCU/module' },
-        { value: 'external', label: 'External BLE chip/module' },
-        { value: 'none', label: 'None' }
-      ],
-      defaultValue: defaults.ble
+    if (!selected) continue
+    await configureChipSelection({
+      definition,
+      id: selected,
+      descriptor: catalog[selected],
+      prompt,
+      io,
+      replace: true,
+      boardName: alias
     })
-    gpsModule = await ask(prompt, { message: 'GPS module/chip (blank for none)', defaultValue: '' })
-    gpsInterface = gpsModule ? await choose(prompt, {
-      message: 'GPS interface',
-      choices: [
-        { value: 'uart', label: 'UART' },
-        { value: 'i2c', label: 'I2C' },
-        { value: 'spi', label: 'SPI' },
-        { value: 'other', label: 'Other' }
-      ],
-      defaultValue: 'uart'
-    }) : ''
-    audioCodec = await ask(prompt, { message: 'Audio codec/chip (blank for none)', defaultValue: '' })
-    audioOutput = audioCodec ? await choose(prompt, {
-      message: 'Audio output',
-      choices: [
-        { value: 'i2s-speaker', label: 'I2S speaker/output' },
-        { value: 'dac', label: 'DAC output' },
-        { value: 'pwm', label: 'PWM/buzzer' },
-        { value: 'other', label: 'Other' }
-      ],
-      defaultValue: 'i2s-speaker'
-    }) : ''
-    audioInput = audioCodec ? await choose(prompt, {
-      message: 'Audio input',
+  }
+
+  renderStep(io, 'Board features', ['Configure physical features that are not separate chip drivers.'])
+  if (await confirm(prompt, { message: 'Does this board expose a microSD slot?', defaultValue: false })) {
+    definition.storage.microSD.pins.clk = await askPin(prompt, 'microSD clock pin')
+    definition.storage.microSD.pins.cmd = await askPin(prompt, 'microSD command pin')
+    definition.storage.microSD.pins.data0 = await askPin(prompt, 'microSD data 0 pin')
+  }
+  if (await confirm(prompt, { message: 'Use a hardware button to return to the launcher?', defaultValue: false })) {
+    definition.controls.launcherButton.pin = await askPin(prompt, 'Launcher button pin')
+    definition.controls.launcherButton.activeLevel = Number(await choose(prompt, {
+      message: 'Launcher button active level',
       choices: [
-        { value: 'none', label: 'None' },
-        { value: 'i2s-mic', label: 'I2S microphone' },
-        { value: 'pdm-mic', label: 'PDM microphone' },
-        { value: 'analog-mic', label: 'Analog microphone' },
-        { value: 'other', label: 'Other' }
+        { value: '0', label: 'Active low' },
+        { value: '1', label: 'Active high' }
       ],
-      defaultValue: 'none'
-    }) : ''
-    storage = await ask(prompt, { message: 'Storage chips/features, comma-separated', defaultValue: defaults.storage })
-    sensors = await ask(prompt, { message: 'Sensors, comma-separated (IMU, light, temp, etc.)', defaultValue: '' })
-    power = await ask(prompt, { message: 'Power path (USB, battery charger, PMIC, etc.)', defaultValue: 'USB' })
-  } else {
-    renderStep(io, 'Peripherals', [
-      `Using defaults: WiFi ${wifi}, BLE ${ble}, storage ${storage}, power USB.`,
-      `You can edit .gea/boards/${alias}.json later if the board has GPS, audio, or sensors.`
-    ])
+      defaultValue: '0'
+    }))
   }
 
-  renderStep(io, 'Connection', ['Choose how GeaStack should flash and monitor the board.'])
-  const transport = await choose(prompt, {
-    message: 'Primary flash/monitor transport',
-    choices: [
-      { value: 'usbSerial', label: 'USB serial' },
-      { value: 'ota', label: 'WiFi OTA' },
-      { value: 'both', label: 'USB serial + OTA' },
-      { value: 'custom', label: 'Custom' }
-    ],
-    defaultValue: 'usbSerial'
+  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 = transport === 'usbSerial' || transport === 'both'
-    ? await selectUsbSerial(prompt, io, { message: 'USB serial number (optional)' })
-    : ''
-  const otaHost = transport === 'ota' || transport === 'both'
-    ? await ask(prompt, { message: 'OTA host/IP (optional)', defaultValue: '' })
-    : ''
-  const notes = await ask(prompt, { message: 'Notes / links to schematic, display datasheet, etc. (optional)', defaultValue: '' })
-
-  const profile = compactObject({
-    alias,
-    kind: 'custom-board-profile',
-    targetFamily: 'esp32',
+
+  const configPath = boardConfigPath(ctx, parsed)
+  const definitionPath = path.join(path.dirname(configPath), 'targets', `${alias}.json`)
+  const relativeDefinition = path.relative(path.dirname(configPath), definitionPath)
+  const entry = compactObject({
+    target: alias,
+    targetDefinition: relativeDefinition,
     adapter: 'esp32-idf',
-    baseTarget,
-    mcu: mcuName,
-    display: compactObject({
-      kind: displayKind,
-      controller: displayController,
-      interface: displayInterface,
-      resolution
-    }),
-    touch: compactObject({
-      controller: touchController,
-      interface: touchInterface
-    }),
-    wireless: compactObject({ wifi, ble }),
-    gps: compactObject({ module: gpsModule, interface: gpsInterface }),
-    audio: compactObject({ codec: audioCodec, output: audioOutput, input: audioInput }),
-    storage: csv(storage),
-    sensors: csv(sensors),
-    power,
+    appPlatform: 'esp32',
     transports: compactObject({
-      usbSerial: usbSerial ? { serial: usbSerial } : undefined,
-      ota: otaHost ? { host: otaHost } : undefined
-    }),
-    notes
+      usbSerial: usbSerial ? { serial: usbSerial } : undefined
+    })
   })
-
-  const profilePath = path.join(ctx.cwd, '.gea', 'boards', `${alias}.json`)
-  const configPath = boardConfigPath(ctx, parsed)
-  renderCustomBoardReview(io, { alias, profile, profilePath, configPath, flashReady: Boolean(baseTarget) })
-  if (!await shouldSaveSetup(parsed, prompt, 'Save this custom board profile?')) {
+  const requiredRoles = roles.map(([role]) => role)
+  const missingRoles = requiredRoles.filter((role) => !definition.chips[role])
+  validateGpioAssignments(definition)
+  renderCustomBoardReview(io, { alias, definition, definitionPath, configPath, entry, missingRoles })
+  if (!await shouldSaveSetup(parsed, prompt, 'Save this custom board target?')) {
     return { alias, cancelled: true }
   }
-  writeJsonEnsured(profilePath, profile)
-  io.stdout(`Wrote custom board profile to ${profilePath}`)
-
-  if (baseTarget) {
-    const config = readBoardConfig(configPath)
-    config[alias] = compactObject({
-      target: baseTarget,
-      adapter: 'esp32-idf',
-      customProfile: profilePath,
-      transports: profile.transports
-    })
-    writeJsonEnsured(configPath, config)
-    io.stdout(`Wrote experimental board alias '${alias}' to ${configPath}`)
-    return { alias, flashReady: true }
-  } else {
-    io.stdout('No board alias was added because no base target was selected.')
-    io.stdout('Add a target backend before flashing this custom profile.')
-    return { alias, flashReady: false }
+
+  writeJsonEnsured(definitionPath, definition)
+  const config = readBoardConfig(configPath)
+  config[alias] = entry
+  writeJsonEnsured(configPath, config)
+  io.stdout(`Wrote custom target to ${definitionPath}`)
+  io.stdout(`Wrote board alias '${alias}' to ${configPath}`)
+  if (missingRoles.length) {
+    io.stdout(`Add the remaining roles with: npx gea chips add <chip> --board ${alias}`)
   }
+  return { alias, flashReady: missingRoles.length === 0 }
 }
 
 function renderHeader(io, title, lines = []) {
@@ -405,25 +295,24 @@ function renderKnownBoardReview(io, { alias, board, configPath, entry }) {
   ])
 }
 
-function renderCustomBoardReview(io, { alias, profile, profilePath, configPath, flashReady }) {
+function renderCustomBoardReview(io, { alias, definition, definitionPath, configPath, entry, missingRoles }) {
   renderStep(io, 'Review', [
     'This is what GeaStack will save.'
   ])
   writeRows(io, [
     ['Alias', alias],
-    ['MCU / SoC', profile.mcu],
-    ['Base target', profile.baseTarget || 'none yet'],
-    ['Display', describeObject(profile.display)],
-    ['Touch', describeObject(profile.touch)],
-    ['Wireless', describeObject(profile.wireless)],
-    ['GPS', describeObject(profile.gps)],
-    ['Audio', describeObject(profile.audio)],
-    ['Storage', list(profile.storage)],
-    ['Sensors', list(profile.sensors)],
-    ['Power', profile.power || 'not set'],
-    ['Transport', describeObject(profile.transports)],
-    ['Profile', profilePath],
-    ['Board config', flashReady ? configPath : 'not written until a base target is selected']
+    ['MCU / SoC', definition.mcu],
+    ['Platform base', definition.extends],
+    ['Display', describeObject(definition.chips.display)],
+    ['Touch', describeObject(definition.chips.touch)],
+    ['Power', describeObject(definition.chips.power)],
+    ['IMU', describeObject(definition.chips.imu)],
+    ['Audio', describeObject(definition.chips.audio)],
+    ['I2C', describeObject(definition.buses.i2c)],
+    ['USB serial', entry.transports?.usbSerial?.serial || 'auto / pass --port'],
+    ['Missing roles', missingRoles.join(', ') || 'none'],
+    ['Target definition', definitionPath],
+    ['Board config', configPath]
   ])
 }
 
@@ -461,17 +350,6 @@ function describeObject(value) {
   return entries.length ? entries.join('; ') : 'not set'
 }
 
-function defaultCustomPeripherals(mcuName) {
-  const normalized = String(mcuName || '').toLowerCase()
-  const espWithWireless = ['esp32', 'esp32-s3', 'esp32-c3', 'esp32-c6', 'esp32-h2'].includes(normalized)
-  const hasPsramByDefault = ['esp32-s3', 'esp32-p4'].includes(normalized)
-  return {
-    wifi: espWithWireless && normalized !== 'esp32-h2' ? 'built-in' : 'none',
-    ble: espWithWireless ? 'built-in' : 'none',
-    storage: hasPsramByDefault ? 'flash, psram' : 'flash'
-  }
-}
-
 async function maybeInstallNpmDependencies(ctx, parsed, io, prompt, { force = false } = {}) {
   const install = force || option(parsed, 'install') === true || await confirm(prompt, {
     message: 'Install npm dependencies now if package.json exists?',
@@ -612,6 +490,18 @@ function validateAlias(value) {
   return ''
 }
 
+async function askPin(prompt, message) {
+  return Number(await ask(prompt, {
+    message,
+    defaultValue: '',
+    validate: (value) => {
+      if (!/^\d+$/.test(value)) return 'enter a GPIO number from 0 through 48'
+      const pin = Number(value)
+      return pin >= 0 && pin <= 48 ? '' : 'enter a GPIO number from 0 through 48'
+    }
+  }))
+}
+
 function compactObject(value) {
   return Object.fromEntries(Object.entries(value).filter(([, entry]) => {
     if (entry === undefined || entry === null || entry === '') return false
@@ -620,14 +510,3 @@ function compactObject(value) {
     return true
   }))
 }
-
-function csv(value) {
-  return String(value || '')
-    .split(',')
-    .map((entry) => entry.trim())
-    .filter(Boolean)
-}
-
-function list(value) {
-  return Array.isArray(value) && value.length ? value.join(', ') : 'not set'
-}