@geastack/cli 0.1.52 → 0.1.54

package/README.md

@@ -100,6 +100,18 @@ 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.
 
+Boards are managed without editing JSON by hand; aliases live in
+`~/.geastack/boards.json` (this machine) and the project's `.gea/boards.json`
+(overrides):
+
+```sh
+gea boards discover                    # which registered board is on which USB port, its app and IP
+gea boards list
+gea boards set amoled host 192.168.1.100
+gea boards rename amoled desk-amoled
+gea boards remove desk-amoled
+```
+
 Custom boards remain editable after setup:
 
 ```sh
@@ -169,4 +181,5 @@ First implementation is in place:
 - `list` and `inspect` helpers;
 - `create-geastack` with a bundled counter starter, a blank application, and a
   GitHub-backed rich example flow for web, embedded, GeaOS, iOS, macOS, and Android apps,
-  all with `.gea/boards.json`.
+  all with `.gea/boards.json`, plus `gea boards` for machine-wide aliases in
+  `~/.geastack/boards.json`.

package/docs/ESP32-WAVESHARE-AMOLED-QUICKSTART.md

@@ -90,7 +90,7 @@ You do not need to run that before every command unless `gea doctor` says ESP-ID
 
 If the wizard finds a connected serial device, pick it. If no board is plugged in yet, that is fine; you can provide the port later.
 
-The wizard writes the board config into your app at `.gea/boards.json` and initializes the selected board target.
+The wizard writes the board alias into your app's `.gea/boards.json` (or `~/.geastack/boards.json` with `--global`, for every project on this machine) and initializes the selected board target.
 
 ## 4. Flash
 
@@ -134,4 +134,4 @@ Most first-run issues are one of:
 - ESP-IDF is not activated in the current shell.
 - The USB cable is power-only.
 - The serial port needs to be passed with `--port`.
-- The board alias does not match the name in `.gea/boards.json`.
+- The board alias does not match a name in `npx gea boards list` (`~/.geastack/boards.json` plus the app's `.gea/boards.json`). `npx gea boards discover` shows which registered board each USB port is.

package/docs/NPX-COMMANDS.md

@@ -94,7 +94,9 @@ packages are scoped and configured for restricted npmjs publication.
 - ESP-IDF toolchain check/install only.
 
 Known-board setup detects attached serial devices, asks for a stable USB serial,
-shows a review screen, writes a board alias into the active boards config, then
+shows a review screen, writes a board alias into the active boards config
+(`--global` for `~/.geastack/boards.json`, `--local` for the project's
+`.gea/boards.json`; by default the project config when it exists), then
 initializes the selected board target so the next command can be
 `npx gea flash --board <alias> --monitor`. In generated apps, that config is:
 

package/docs/SETUP.md

@@ -35,7 +35,7 @@ For ESP32 hardware:
 - npm.
 - Python 3.
 - ESP-IDF v6.0.1.
-- `.gea/boards.json` configured for your board.
+- a board alias for your board (`~/.geastack/boards.json` or the project's `.gea/boards.json`, see Board Configuration).
 
 For the Waveshare ESP32-S3 AMOLED board, use
 [ESP32-WAVESHARE-AMOLED-QUICKSTART.md](ESP32-WAVESHARE-AMOLED-QUICKSTART.md).
@@ -224,9 +224,44 @@ manager or from python.org.
 
 ## Board Configuration
 
-Board aliases are project-local machine configuration. `create-geastack`
-creates an empty `.gea/boards.json`, and `npx gea setup` writes aliases there.
-Example:
+A board alias names one physical unit: `gea flash --board amoled` resolves
+`amoled` to a target, a USB serial and, optionally, an IP. Aliases are
+machine-local configuration and never come from a package. The CLI merges two
+files, project over home:
+
+| file | holds | written by |
+| --- | --- | --- |
+| `~/.geastack/boards.json` | every board on this machine (`GEA_HOME` relocates the directory) | `gea boards add --global`, `gea boards set` |
+| `<project>/.gea/boards.json` | aliases specific to one application; overrides a home alias of the same name | `create-geastack` (empty), `gea boards add` |
+
+`--boards-config <file>` (or `GEA_BOARDS_CONFIG`) replaces both with exactly
+that file. By default `gea boards add` writes to the project config when the
+project has one and to the home config otherwise; an existing alias is always
+edited where it lives.
+
+```sh
+npx gea boards discover                 # what is plugged in: alias, app, IP
+npx gea boards add                      # register a board (guided)
+npx gea boards list                     # every alias and which file it lives in
+npx gea boards set amoled host 192.168.1.100
+npx gea boards rename amoled desk-amoled
+npx gea boards remove desk-amoled
+npx gea doctor
+```
+
+`gea boards discover` sends one `GEADEV PING` to each serial device without
+resetting it; a board running gea firmware answers with its app id, its IP
+(when it has joined WiFi) and its MAC, and the CLI pairs the reply with an
+alias by USB serial. `--save` writes a reported IP into
+`transports.ota.host`, which is what `gea ota`, `gea logs` and
+`gea screenshot` use over WiFi.
+
+### Entry shapes
+
+Every entry names a `target` (`gea targets list`) and its `adapter`, then the
+transports the board offers. The USB serial is the stable identity: on ESP32
+boards it is the station MAC, and the CLI resolves it to today's `/dev` port
+at call time, so never record a port path.
 
 ```json
 {
@@ -234,22 +269,53 @@ Example:
     "target": "esp32-s3-touch-amoled-2.06",
     "adapter": "esp32-idf",
     "transports": {
-      "usbSerial": {
-        "serial": "YOUR_BOARD_USB_SERIAL"
-      }
+      "usbSerial": { "serial": "80:B5:4E:DA:73:88" },
+      "ota": { "host": "192.168.1.100" }
+    }
+  },
+  "rotary": {
+    "target": "esp32-s3-elecrow-rotary-2.1",
+    "adapter": "esp32-idf",
+    "transports": {
+      "usbSerial": { "serial": "14:C1:9F:26:65:08", "restartAfterFlash": "manual" }
+    }
+  },
+  "tufty": {
+    "target": "rp2350-tufty-2350",
+    "adapter": "rp2350-pico",
+    "transports": { "usbSerial": { "serial": "fa59949adbb4802f" } }
+  },
+  "linux": {
+    "target": "geaos",
+    "adapter": "geaos-linux",
+    "transports": {
+      "telnet": { "host": "192.168.7.2", "port": 2323 },
+      "fastboot": { "serial": "geaos001" }
     }
+  },
+  "lokmat": {
+    "target": "lokmat-applp2max",
+    "adapter": "geaos-arm64",
+    "transports": {
+      "usbSerial": { "serial": "geaos01" },
+      "fastboot": { "serial": "0123456789ABCDEF" },
+      "mtk": { "workdir": "~/lokmat-root" }
+    }
+  },
+  "my-board": {
+    "target": "my-board",
+    "targetDefinition": "targets/my-board.json",
+    "adapter": "esp32-idf",
+    "transports": { "usbSerial": { "serial": "YOUR_BOARD_USB_SERIAL" } }
   }
 }
 ```
 
-Then check discovery:
-
-```sh
-npx gea setup
-npx gea list boards
-npx gea list targets
-npx gea doctor
-```
+- `restartAfterFlash: "manual"` marks a board whose USB-Serial-JTAG port
+  re-enters ROM download mode after a flash; the CLI stops and asks for a
+  power cycle instead of pulsing the reset lines.
+- `targetDefinition` points at a custom target composed by `gea setup` /
+  `gea chips`, relative to the file the alias lives in.
 
 ## Common Verification Flow
 

package/docs/SPEC.md

@@ -83,9 +83,12 @@ gea flash --app bouncing-balls-jsx --board amoled --monitor
 gea flash --app css-3d-cube --target android
 ```
 
-The CLI should pass through board aliases from the active board config. A project
-uses its own `.gea/boards.json`; otherwise the CLI reads the board catalog shipped
-by the installed `@geastack/targets` package.
+The CLI resolves board aliases from two machine-local files merged project over
+home: `~/.geastack/boards.json` (every board on the machine, `GEA_HOME`
+relocates it) and the project's `.gea/boards.json`. `--boards-config` replaces
+both. No package ships aliases. `gea boards` manages them: `list`, `show`,
+`add`, `set <alias> <key> <value>`, `remove`, `rename`, and `discover`, which
+identifies connected boards over USB (`GEADEV PING` reports app, IP and MAC).
 
 ### `gea chips`
 
@@ -228,8 +231,8 @@ Use predictable exit codes:
 1. Implement `gea doctor` for toolchain discovery and app manifest validation.
 2. Implement `gea dev --target web` by delegating to the simulator repo.
 3. Implement `gea build --target web`.
-4. Implement `gea flash --board <alias>` by delegating to
-   `targets/scripts/board`.
+4. Implement `gea flash --board <alias>` natively (ESP-IDF, esptool, OTA and
+   device transports live in `src/esp32` and `src/device`).
 5. Add `create-geastack` with one JSX app template.
 
 Status: implemented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/cli",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "type": "module",
   "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
   "publishConfig": {
@@ -27,8 +27,7 @@
     "create-geastack": "bin/create-geastack.mjs"
   },
   "dependencies": {
-    "@geastack/core": "0.1.10",
-    "@geastack/targets": "0.1.47"
+    "serialport": "^13.0.0"
   },
   "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/apps/app-index-writer.mjs

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// apps are discovered by the caller (cli manifest)
+
+export function generateAppIndex({ apps, outputFile }) {
+  if (!Array.isArray(apps)) throw new Error('generateAppIndex requires apps')
+  if (!outputFile) throw new Error('generateAppIndex requires outputFile')
+  mkdirSync(path.dirname(outputFile), { recursive: true })
+  writeFileSync(
+    outputFile,
+    `// Auto-generated by gea apps index. Do not edit.\nexport const GEA_APPS = ${JSON.stringify(apps, null, 2)} as const\n`
+  )
+  return apps
+}

package/src/apps/apple-icons.mjs

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { ICON_SIZES } from './openai-icons.mjs'
+
+export const IOS_APP_ICON_IMAGES = [
+  { idiom: 'iphone', size: '20x20', scale: '2x', pixels: 40, filename: 'AppIcon-20@2x.png' },
+  { idiom: 'iphone', size: '20x20', scale: '3x', pixels: 60, filename: 'AppIcon-20@3x.png' },
+  { idiom: 'iphone', size: '29x29', scale: '2x', pixels: 58, filename: 'AppIcon-29@2x.png' },
+  { idiom: 'iphone', size: '29x29', scale: '3x', pixels: 87, filename: 'AppIcon-29@3x.png' },
+  { idiom: 'iphone', size: '40x40', scale: '2x', pixels: 80, filename: 'AppIcon-40@2x.png' },
+  { idiom: 'iphone', size: '40x40', scale: '3x', pixels: 120, filename: 'AppIcon-40@3x.png' },
+  { idiom: 'iphone', size: '60x60', scale: '2x', pixels: 120, filename: 'AppIcon-60@2x.png' },
+  { idiom: 'iphone', size: '60x60', scale: '3x', pixels: 180, filename: 'AppIcon-60@3x.png' },
+  { idiom: 'ipad', size: '20x20', scale: '1x', pixels: 20, filename: 'AppIcon-iPad-20.png' },
+  { idiom: 'ipad', size: '20x20', scale: '2x', pixels: 40, filename: 'AppIcon-iPad-20@2x.png' },
+  { idiom: 'ipad', size: '29x29', scale: '1x', pixels: 29, filename: 'AppIcon-iPad-29.png' },
+  { idiom: 'ipad', size: '29x29', scale: '2x', pixels: 58, filename: 'AppIcon-iPad-29@2x.png' },
+  { idiom: 'ipad', size: '40x40', scale: '1x', pixels: 40, filename: 'AppIcon-iPad-40.png' },
+  { idiom: 'ipad', size: '40x40', scale: '2x', pixels: 80, filename: 'AppIcon-iPad-40@2x.png' },
+  { idiom: 'ipad', size: '76x76', scale: '1x', pixels: 76, filename: 'AppIcon-iPad-76.png' },
+  { idiom: 'ipad', size: '76x76', scale: '2x', pixels: 152, filename: 'AppIcon-iPad-76@2x.png' },
+  { idiom: 'ipad', size: '83.5x83.5', scale: '2x', pixels: 167, filename: 'AppIcon-iPad-83.5@2x.png' },
+  { idiom: 'ios-marketing', size: '1024x1024', scale: '1x', pixels: 1024, filename: 'AppIcon-1024.png' },
+]
+
+export const MACOS_ICONSET_IMAGES = [
+  { filename: 'icon_16x16.png', pixels: 16 },
+  { filename: 'icon_16x16@2x.png', pixels: 32 },
+  { filename: 'icon_32x32.png', pixels: 32 },
+  { filename: 'icon_32x32@2x.png', pixels: 64 },
+  { filename: 'icon_128x128.png', pixels: 128 },
+  { filename: 'icon_128x128@2x.png', pixels: 256 },
+  { filename: 'icon_256x256.png', pixels: 256 },
+  { filename: 'icon_256x256@2x.png', pixels: 512 },
+  { filename: 'icon_512x512.png', pixels: 512 },
+  { filename: 'icon_512x512@2x.png', pixels: 1024 },
+]
+
+export const MACOS_ICNS_CHUNKS = [
+  { type: 'icp4', filename: 'icon_16x16.png' },
+  { type: 'icp5', filename: 'icon_32x32.png' },
+  { type: 'icp6', filename: 'icon_32x32@2x.png' },
+  { type: 'ic07', filename: 'icon_128x128.png' },
+  { type: 'ic08', filename: 'icon_256x256.png' },
+  { type: 'ic09', filename: 'icon_512x512.png' },
+  { type: 'ic10', filename: 'icon_512x512@2x.png' },
+]
+
+export function appleIconConfig() {
+  return Object.fromEntries(ICON_SIZES.map((size) => [String(size), `icons/icon-${size}.png`]))
+}
+
+export function resolveAppleIconSourcePath(repoRoot, app) {
+  const sourcePath = path.resolve(repoRoot, app.root, 'icons', 'icon-source.png')
+  if (existsSync(sourcePath)) return sourcePath
+
+  for (const size of ['1024', '512', '256', '128', '64', '32']) {
+    const iconPath = app.icons?.[size]
+    if (!iconPath) continue
+    const resolved = path.resolve(repoRoot, app.root, iconPath)
+    if (existsSync(resolved)) return resolved
+  }
+
+  throw new Error(`Missing Apple icon source for ${app.id}: expected ${sourcePath} or a declared package icon`)
+}
+
+function resizePng(sourcePath, outputPath, pixels) {
+  mkdirSync(path.dirname(outputPath), { recursive: true })
+  const result = spawnSync('sips', ['-s', 'format', 'png', '-z', String(pixels), String(pixels), sourcePath, '--out', outputPath], {
+    encoding: 'utf8',
+  })
+  if (result.status !== 0) {
+    const detail = result.stderr || result.stdout || `exit ${result.status}`
+    throw new Error(`Failed to resize icon ${sourcePath} to ${pixels}x${pixels}: ${detail.trim()}`)
+  }
+}
+
+export function writeIosAppIconContents(appIconSetDir) {
+  const contents = {
+    images: IOS_APP_ICON_IMAGES.map(({ idiom, size, scale, filename }) => ({
+      idiom,
+      size,
+      scale,
+      filename,
+    })),
+    info: {
+      author: 'xcode',
+      version: 1,
+    },
+  }
+  writeFileSync(path.join(appIconSetDir, 'Contents.json'), `${JSON.stringify(contents, null, 2)}\n`)
+}
+
+export function prepareIosAppIconAssets({ repoRoot, app, assetsDir }) {
+  if (!repoRoot) throw new Error('prepareIosAppIconAssets requires repoRoot')
+  if (!app) throw new Error('prepareIosAppIconAssets requires app')
+  if (!assetsDir) throw new Error('prepareIosAppIconAssets requires assetsDir')
+
+  const sourcePath = resolveAppleIconSourcePath(repoRoot, app)
+  const appIconSetDir = path.join(assetsDir, 'AppIcon.appiconset')
+  rmSync(appIconSetDir, { recursive: true, force: true })
+  mkdirSync(appIconSetDir, { recursive: true })
+
+  for (const image of IOS_APP_ICON_IMAGES) {
+    resizePng(sourcePath, path.join(appIconSetDir, image.filename), image.pixels)
+  }
+  writeIosAppIconContents(appIconSetDir)
+  return appIconSetDir
+}
+
+export function writeIcnsFromIconset({ iconsetDir, icnsPath }) {
+  const chunks = MACOS_ICNS_CHUNKS.map(({ type, filename }) => {
+    const data = readFileSync(path.join(iconsetDir, filename))
+    const header = Buffer.alloc(8)
+    header.write(type, 0, 'ascii')
+    header.writeUInt32BE(data.length + 8, 4)
+    return Buffer.concat([header, data])
+  })
+  const length = 8 + chunks.reduce((sum, chunk) => sum + chunk.length, 0)
+  const header = Buffer.alloc(8)
+  header.write('icns', 0, 'ascii')
+  header.writeUInt32BE(length, 4)
+  writeFileSync(icnsPath, Buffer.concat([header, ...chunks], length))
+}
+
+export function prepareMacosAppIcon({ repoRoot, app, buildDir, resourcesDir }) {
+  if (!repoRoot) throw new Error('prepareMacosAppIcon requires repoRoot')
+  if (!app) throw new Error('prepareMacosAppIcon requires app')
+  if (!buildDir) throw new Error('prepareMacosAppIcon requires buildDir')
+  if (!resourcesDir) throw new Error('prepareMacosAppIcon requires resourcesDir')
+
+  const sourcePath = resolveAppleIconSourcePath(repoRoot, app)
+  const iconsetDir = path.join(buildDir, 'AppIcon.iconset')
+  const icnsPath = path.join(resourcesDir, 'AppIcon.icns')
+  rmSync(iconsetDir, { recursive: true, force: true })
+  mkdirSync(iconsetDir, { recursive: true })
+  mkdirSync(resourcesDir, { recursive: true })
+
+  for (const image of MACOS_ICONSET_IMAGES) {
+    resizePng(sourcePath, path.join(iconsetDir, image.filename), image.pixels)
+  }
+
+  writeIcnsFromIconset({ iconsetDir, icnsPath })
+  return icnsPath
+}

package/src/apps/bundle-writer.mjs

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+
+import { writeZip } from './zip-writer.mjs'
+
+const FORMAT = 'dev.gea.geaos.app.bundle'
+const FORMAT_VERSION = 1
+const ICON_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg'])
+
+function sha256(buffer) {
+  return `sha256-${createHash('sha256').update(buffer).digest('hex')}`
+}
+
+function targetArtifact(repoRoot, app, target) {
+  if (target === 'geaos') {
+    return {
+      target: 'geaos-armv7',
+      sourcePath: path.join(repoRoot, 'targets', 'geaos', 'dist', app.id, app.id),
+      bundlePath: `bin/geaos-armv7/${app.id}`,
+      executable: true
+    }
+  }
+  throw new Error(`Unsupported bundle target '${target}'`)
+}
+
+function readBundleFile(sourcePath, bundlePath, executable = false) {
+  if (!existsSync(sourcePath)) throw new Error(`Missing bundle input: ${sourcePath}`)
+  return {
+    name: bundlePath,
+    data: readFileSync(sourcePath),
+    executable
+  }
+}
+
+function pngDimensions(buffer) {
+  const signature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+  if (buffer.length < 24) return null
+  if (!signature.every((byte, index) => buffer[index] === byte)) return null
+  if (buffer.subarray(12, 16).toString('ascii') !== 'IHDR') return null
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+    format: 'png'
+  }
+}
+
+function jpegDimensions(buffer) {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null
+  let offset = 2
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1
+      continue
+    }
+    const marker = buffer[offset + 1]
+    offset += 2
+    if (marker === 0xd9 || marker === 0xda) break
+    if (offset + 2 > buffer.length) break
+    const length = buffer.readUInt16BE(offset)
+    if (length < 2 || offset + length > buffer.length) break
+    const isSof = (marker >= 0xc0 && marker <= 0xc3) || (marker >= 0xc5 && marker <= 0xc7) ||
+      (marker >= 0xc9 && marker <= 0xcb) || (marker >= 0xcd && marker <= 0xcf)
+    if (isSof && length >= 7) {
+      return {
+        height: buffer.readUInt16BE(offset + 3),
+        width: buffer.readUInt16BE(offset + 5),
+        format: 'jpeg'
+      }
+    }
+    offset += length
+  }
+  return null
+}
+
+export function validateIconFile(sourcePath, expectedSize) {
+  const ext = path.extname(sourcePath).toLowerCase()
+  if (!ICON_EXTENSIONS.has(ext)) {
+    throw new Error(`Icon must be a PNG or JPEG: ${sourcePath}`)
+  }
+  const buffer = readFileSync(sourcePath)
+  const dimensions = ext === '.png' ? pngDimensions(buffer) : jpegDimensions(buffer)
+  if (!dimensions) throw new Error(`Icon has unsupported or invalid image data: ${sourcePath}`)
+  if (dimensions.width !== expectedSize || dimensions.height !== expectedSize) {
+    throw new Error(`Icon ${sourcePath} must be ${expectedSize}x${expectedSize}; got ${dimensions.width}x${dimensions.height}`)
+  }
+}
+
+function iconEntries(repoRoot, app) {
+  const entries = []
+  for (const [size, iconPath] of Object.entries(app.icons)) {
+    const sourcePath = path.resolve(repoRoot, app.root, iconPath)
+    validateIconFile(sourcePath, Number(size))
+    entries.push(readBundleFile(sourcePath, `icons/icon-${size}${path.extname(iconPath).toLowerCase()}`))
+  }
+  return entries
+}
+
+function packageEntry(repoRoot, app) {
+  return readBundleFile(path.resolve(repoRoot, app.root, 'package.json'), 'package.json')
+}
+
+export function createGeaBundle({ repoRoot, app, target = 'geaos', outputPath }) {
+  if (!repoRoot) throw new Error('createGeaBundle requires repoRoot')
+  if (!app) throw new Error('createGeaBundle requires app')
+  if (!app.targets?.[target] === true) throw new Error(`App '${app.id}' does not enable target '${target}'`)
+  if (!outputPath) throw new Error('createGeaBundle requires outputPath')
+
+  const artifact = targetArtifact(repoRoot, app, target)
+  const payloadEntries = [
+    packageEntry(repoRoot, app),
+    ...iconEntries(repoRoot, app),
+    readBundleFile(artifact.sourcePath, artifact.bundlePath, artifact.executable)
+  ]
+  const checksums = Object.fromEntries(payloadEntries.map((entry) => [entry.name, sha256(entry.data)]))
+  const icons = Object.fromEntries(
+    Object.entries(app.icons).map(([size, iconPath]) => [
+      size,
+      `icons/icon-${size}${path.extname(iconPath).toLowerCase()}`
+    ])
+  )
+
+  const manifest = {
+    format: FORMAT,
+    formatVersion: FORMAT_VERSION,
+    createdAt: new Date().toISOString(),
+    app: {
+      id: app.id,
+      name: app.name,
+      packageName: app.packageName,
+      version: app.version,
+      runtime: app.runtime,
+      entry: app.entry,
+      launcher: app.launcher
+    },
+    icons,
+    artifacts: [
+      {
+        target: artifact.target,
+        path: artifact.bundlePath,
+        executable: artifact.executable
+      }
+    ],
+    checksums
+  }
+
+  writeZip(outputPath, [
+    {
+      name: 'gea-bundle.json',
+      data: `${JSON.stringify(manifest, null, 2)}\n`
+    },
+    ...payloadEntries
+  ])
+  return manifest
+}

package/src/apps/launcher-catalog.mjs

@@ -0,0 +1,114 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// apps are discovered by the caller (cli manifest)
+
+function q(value) {
+  return JSON.stringify(String(value ?? ''))
+}
+
+function jsxText(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\{/g, '&#123;')
+    .replace(/\}/g, '&#125;')
+}
+
+function readJson(file) {
+  return JSON.parse(readFileSync(file, 'utf8'))
+}
+
+function preferredIcon(app) {
+  for (const size of ['64', '128', '32', '256', '512']) {
+    if (app.icons[size]) return { size, file: app.icons[size] }
+  }
+  return null
+}
+
+function configuredLauncherAppIds(repoRoot) {
+  const manifestPath = path.join(repoRoot, 'apps', 'app-launcher', 'package.json')
+  if (!existsSync(manifestPath)) return null
+  const manifest = readJson(manifestPath)
+  const ids = manifest?.gea?.launcherCatalog?.appIds
+  return Array.isArray(ids) ? ids.map((id) => String(id).trim()).filter(Boolean) : null
+}
+
+function orderedIncludeFilter(apps, includeAppIds) {
+  if (!includeAppIds || includeAppIds.length === 0) return apps
+  const byId = new Map(apps.map((app) => [app.id, app]))
+  return includeAppIds.map((id) => byId.get(id)).filter(Boolean)
+}
+
+function launcherApps(allApps, target, includeAppIds = null) {
+  const apps = allApps
+    .filter((app) => app.runtime === 'gea')
+    .filter((app) => app.targets?.[target] === true)
+    .filter((app) => app.launcher.hidden !== true)
+    .sort((a, b) => {
+      const order = a.launcher.order - b.launcher.order
+      return order || a.name.localeCompare(b.name)
+    })
+  return orderedIncludeFilter(apps, includeAppIds)
+}
+
+function copyLauncherIcon({ repoRoot, app, outputFile }) {
+  const icon = preferredIcon(app)
+  if (!icon) return ''
+  const sourcePath = path.resolve(repoRoot, app.root, icon.file)
+  if (!existsSync(sourcePath)) return ''
+  const iconsDir = path.join(path.dirname(outputFile), 'icons')
+  mkdirSync(iconsDir, { recursive: true })
+  const ext = path.extname(icon.file).toLowerCase() || '.png'
+  const outputName = `${app.id}-${icon.size}${ext}`
+  copyFileSync(sourcePath, path.join(iconsDir, outputName))
+  return `generated/icons/${outputName}`
+}
+
+export function generateLauncherCatalog({ repoRoot, apps: allApps, target = 'geaos', outputFile }) {
+  if (!repoRoot) throw new Error('generateLauncherCatalog requires repoRoot')
+  if (!Array.isArray(allApps)) throw new Error('generateLauncherCatalog requires apps')
+  if (!outputFile) throw new Error('generateLauncherCatalog requires outputFile')
+  const includeAppIds = configuredLauncherAppIds(repoRoot)
+  const apps = launcherApps(allApps, target, includeAppIds)
+  const generatedDir = path.dirname(outputFile)
+  rmSync(path.join(generatedDir, 'icons'), { recursive: true, force: true })
+  mkdirSync(generatedDir, { recursive: true })
+
+  const lines = [
+    '// Auto-generated by gea apps launcher. Do not edit.',
+    "import { Apps } from '@geastack/core'",
+    "import '../components/LauncherButton.css'",
+    '',
+    'export function LauncherCatalog() {',
+    '  return (',
+    '    <div class="launcher-list" momentum>'
+  ]
+
+  for (const app of apps) {
+    const iconSrc = copyLauncherIcon({ repoRoot, app, outputFile })
+    const style = app.launcher.accent ? ` style={{ borderColor: ${q(app.launcher.accent)} }}` : ''
+    lines.push(`      <div class="launcher-card"${style} onClick={() => Apps.launch(${q(app.id)})}>`)
+    if (iconSrc) {
+      lines.push(`        <img class="launcher-card-icon" src=${q(iconSrc)} />`)
+    } else {
+      lines.push('        <div class="launcher-card-icon launcher-card-icon-placeholder" />')
+    }
+    lines.push(
+      '        <div class="launcher-card-copy">',
+      `          <span class="launcher-card-title">${jsxText(app.name)}</span>`,
+      '        </div>',
+      '      </div>'
+    )
+  }
+
+  lines.push(
+    '    </div>',
+    '  )',
+    '}',
+    ''
+  )
+  writeFileSync(outputFile, `${lines.join('\n')}`)
+  return apps
+}