@geastack/cli 0.1.51 → 0.1.53

package/docs/SPEC.md

@@ -228,8 +228,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.51",
+  "version": "0.1.53",
   "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.46"
+    "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
+}