@geastack/cli 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @geastack/cli
+
+Command-line front door for GeaStack.
+
+This repo contains the `gea` CLI orchestrator and the `create-geastack`
+scaffolder. The CLI turns GeaStack into an npm-first developer workflow while
+keeping target-specific build logic behind stable backend contracts.
+
+## Commands
+
+```sh
+npx @geastack/create-geastack my-panel
+cd my-panel
+npx gea doctor
+npx gea setup
+npx gea dev
+npx gea build --target web
+npx gea build --target ios
+npx gea flash --board amoled --monitor
+npx gea monitor --board amoled
+npx gea inspect --json
+```
+
+## Interactive Menu Map
+
+```mermaid
+flowchart TD
+  create["npx @geastack/create-geastack my-app"] --> identity["Resolve app identity<br/>argument, optional --id, optional --name"]
+  identity --> starter{"Starter app?"}
+
+  starter -->|"Counter starter"| counter["Copy bundled minimal JSX counter"]
+
+  starter -->|"Empty app"| empty["Generate minimal app files"]
+  empty --> emptyFiles["index.tsx, styles.css, index.html,<br/>tsconfig.json, vite.config.ts"]
+
+  starter -->|"Rich example"| pickExample["Pick from hard-coded example list<br/>web, ESP32, GeaOS, iOS, macOS, Android"]
+  pickExample --> fetchExample["Fetch selected app from GitHub"]
+  fetchExample --> copyExample["Copy fetched example files"]
+  copyExample --> rewriteExample["Rewrite package name and gea manifest"]
+
+  counter --> projectWiring["Add @geastack/core and @geastack/cli"]
+  rewriteExample --> projectWiring["Add @geastack/core and @geastack/cli"]
+  emptyFiles --> projectWiring
+  projectWiring --> boardConfig["Create .gea/boards.json"]
+  boardConfig --> install["Install npm dependencies<br/>(interactive default)"]
+  install --> setup["Next: npx gea setup"]
+
+  auto["Automation flags"] -.-> starter
+  auto --> autoEmpty["--starter empty --yes"]
+  auto --> autoExample["--starter example --example watch"]
+```
+
+```mermaid
+flowchart TD
+  setup["npx gea setup"] --> mode{"Mode?"}
+
+  mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.1"]
+  mode -->|"--board alias"| directBoard["Run target setup for board alias"]
+  mode -->|"--target target-id"| directTarget["Run target setup directly"]
+
+  mode -->|"Interactive"| interactive{"What do you want to set up?"}
+
+  interactive -->|"Known supported board"| knownBoard["Pick board"]
+  knownBoard --> alias["Set board alias"]
+  alias --> serial["Detect serial devices"]
+  serial --> saveSerial["Save stable USB serial"]
+  saveSerial --> ota["Optional OTA host"]
+  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 -->|"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"]
+
+  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
+  directBoard --> done
+  directTarget --> done
+```
+
+The CLI resolves `@geastack/core`, `@geastack/targets`, the compiler, chips,
+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.
+
+## Development
+
+```sh
+npm test
+npm run check
+```
+
+Run from this repo during local development:
+
+```sh
+node bin/gea.mjs doctor
+node bin/gea.mjs --help
+node bin/create-geastack.mjs demo-panel --dir ./demo-panel --dry-run
+```
+
+## Machine Setup
+
+Use [docs/SETUP.md](docs/SETUP.md) for Node/npm, ESP-IDF, Emscripten, Xcode,
+Python, and board configuration. For the Waveshare ESP32-S3 AMOLED path, use
+[docs/ESP32-WAVESHARE-AMOLED-QUICKSTART.md](docs/ESP32-WAVESHARE-AMOLED-QUICKSTART.md).
+`npx gea doctor` checks the same dependencies and prints warnings for optional
+target toolchains that are not installed.
+
+[docs/NPX-COMMANDS.md](docs/NPX-COMMANDS.md) captures the private npmjs
+`npx` command shape for release.
+
+## Responsibilities
+
+The CLI should own:
+
+- command parsing and help output;
+- project scaffolding;
+- Gea app manifest validation;
+- target discovery and target backend dispatch;
+- consistent output, diagnostics, and exit codes;
+- `doctor` checks for local toolchains, board config, and target backends.
+
+The CLI should not own target implementation details. ESP32, GeaOS, Apple, and
+web targets should keep their target-specific build logic in their own repos and
+expose stable command contracts.
+
+## Documentation
+
+- [docs/SPEC.md](docs/SPEC.md): command surface, manifest expectations, and
+  backend contract for the first implementation.
+
+## Current Status
+
+First implementation is in place:
+
+- `doctor` for local toolchain checks;
+- npm-resolved embedded board builds for ESP32 and RP2350;
+- `flash`, `monitor`, WiFi OTA, and BLE OTA through `@geastack/targets`;
+- `list` and `inspect` helpers;
+- `create-geastack` with a bundled counter starter, an empty starter, and a
+  GitHub-backed rich example flow for web, embedded, GeaOS, iOS, macOS, and Android apps,
+  all with `.gea/boards.json`.

package/bin/create-geastack.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runCreateGeastack } from '../src/create-geastack.mjs'
+import { CliError } from '../src/errors.mjs'
+
+try {
+  const exitCode = await runCreateGeastack(process.argv.slice(2))
+  if (exitCode) process.exit(exitCode)
+} catch (error) {
+  if (error instanceof CliError) {
+    console.error(error.message)
+    process.exit(error.exitCode)
+  }
+  console.error(error && error.stack ? error.stack : String(error))
+  process.exit(1)
+}

package/bin/gea.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runGea } from '../src/gea.mjs'
+import { CliError } from '../src/errors.mjs'
+
+try {
+  const exitCode = await runGea(process.argv.slice(2))
+  if (exitCode) process.exit(exitCode)
+} catch (error) {
+  if (error instanceof CliError) {
+    console.error(error.message)
+    process.exit(error.exitCode)
+  }
+  console.error(error && error.stack ? error.stack : String(error))
+  process.exit(1)
+}

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

@@ -0,0 +1,133 @@
+# ESP32 Waveshare AMOLED Quickstart
+
+Goal: fresh computer to flashed Waveshare ESP32-S3 Touch AMOLED app without cloning any GeaStack repo.
+
+You should only need four moves:
+
+1. Install the system basics.
+2. Create a Gea app.
+3. Run the setup wizard.
+4. Flash the board.
+
+## 1. Install The Basics
+
+Install:
+
+- Git
+- Node.js 20.19 or newer
+- npm
+- Python 3
+
+On macOS, also make sure Apple command line tools are installed:
+
+```sh
+xcode-select --install
+```
+
+You do not clone GeaStack.
+
+## 2. Create The App
+
+```sh
+npm login
+npx @geastack/create-geastack my-app
+cd my-app
+```
+
+When the wizard asks what to create, choose:
+
+```text
+? What do you want to create?
+  Counter starter - bundled minimal JSX app
+  Empty app - minimal blank Gea app
+  Rich example - fetch from GitHub examples repo
+```
+
+For the fastest first flash, choose `Counter starter`.
+
+That creates a tiny JSX app with one store and installs the project-local Gea CLI, so inside the app you can run `npx gea`.
+
+## 3. Set Up The Board
+
+```sh
+npx gea setup
+```
+
+Choose:
+
+```text
+? What do you want to set up?
+  Known supported board
+
+? Board
+  Waveshare ESP32-S3 Touch AMOLED 2.06
+
+? Board alias
+  amoled
+
+? Save this board setup?
+  Yes
+```
+
+If ESP-IDF is not installed, accept the installer when offered:
+
+```text
+? ESP-IDF was not found. Install it now?
+  Yes
+```
+
+If ESP-IDF was installed, the CLI prints this for future shells:
+
+```sh
+. "$HOME/esp/esp-idf/export.sh"
+```
+
+You do not need to run that before every command unless `npx gea doctor` says ESP-IDF is not active.
+
+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.
+
+## 4. Flash
+
+Flash and open the serial monitor:
+
+```sh
+npx gea flash --board amoled --monitor
+```
+
+If you need to specify the serial port manually:
+
+```sh
+npx gea flash --board amoled --port /dev/cu.usbmodemXXXX --monitor
+```
+
+## Rich Examples
+
+The bundled starter is intentionally tiny. Rich examples live in the GeaStack examples repo and are fetched on demand by name.
+
+For example:
+
+```sh
+npx @geastack/create-geastack watch-demo --starter example --example watch
+cd watch-demo
+npx gea setup
+npx gea flash --board amoled --monitor
+```
+
+The CLI owns the example catalog, so the user does not need to clone the examples repo.
+
+## If Something Fails
+
+Run:
+
+```sh
+npx gea doctor
+```
+
+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`.

package/docs/NPX-COMMANDS.md

@@ -0,0 +1,144 @@
+# Private npm Command Shape
+
+The intended private npmjs onboarding should not require cloning GeaStack repos.
+
+Desired user flow:
+
+```sh
+npm login
+npx @geastack/create-geastack my-app
+cd my-app
+npx gea setup
+npx gea flash --board amoled --monitor
+```
+
+## Package Name Reality
+
+There should not be an unscoped npm package. Private npmjs packages must be
+scoped.
+
+Use these release packages instead:
+
+- `@geastack/create-geastack`: scoped private project/app scaffolder exposing
+  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
+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`.
+
+If someone is wiring an existing app by hand, install the package first:
+
+```sh
+npm install --save-dev @geastack/cli
+npx gea setup
+```
+
+Creator-style scaffolding is:
+
+```sh
+npx @geastack/create-geastack my-app
+```
+
+In an interactive terminal, `create-geastack` asks:
+
+```text
+Starter app
+1. Counter starter - bundled minimal JSX app
+2. Empty app - minimal blank Gea app
+3. Rich example - fetch from GitHub examples repo
+```
+
+`Counter starter` is the only bundled source starter. It is intentionally tiny:
+JSX, one `store.ts`, and enough styling to run.
+
+`Empty app` creates the smallest starter: `index.tsx`, `styles.css`,
+`index.html`, `tsconfig.json`, `vite.config.ts`, `package.json`, and
+`.gea/boards.json`.
+
+`Rich example` opens an example picker populated from the hard-coded
+`examples/catalog.json` shipped inside `@geastack/cli`. The catalog contains web,
+ESP32, GeaOS, iOS, macOS, and Android examples with names, descriptions, target
+flags, and GitHub paths. When the user selects an example, the CLI fetches that app from
+`geastack/examples`, copies it into the new project, then rewrites
+`package.json`, app id, app name, `@geastack/core`, `@geastack/cli`, and
+`.gea/boards.json`.
+
+Automation can skip prompts:
+
+```sh
+npx @geastack/create-geastack my-app --starter counter
+npx @geastack/create-geastack my-app --starter empty --yes
+npx @geastack/create-geastack my-app --starter example --example watch
+npx @geastack/create-geastack my-ios-app --starter example --example ios-native-showcase
+npx gea build --target ios --mode simulator
+npx @geastack/create-geastack cube-app --starter example --example css-3d-cube
+npx gea build --target android --mode device
+```
+
+The private npmjs flow does not depend on a cloned examples repo. The rich
+examples are fetched by the CLI when selected.
+
+Do not change GitHub repository privacy while preparing this shape. The npm
+packages are scoped and configured for restricted npmjs publication.
+
+## Setup Wizard Contract
+
+`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;
+- npm dependency check/install only;
+- 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
+initializes the selected board target so the next command can be
+`npx gea flash --board <alias> --monitor`. In generated apps, that config is:
+
+```text
+.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:
+
+```text
+.gea/boards/<alias>.json
+```
+
+The full profile 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.
+
+ESP-IDF setup is available as:
+
+```sh
+npx gea setup --esp-idf
+```
+
+It installs or dry-runs ESP-IDF v6.0.1 with the ESP32, ESP32-S3, and ESP32-P4
+toolchains.