@geastack/cli 0.1.0

package/docs/SETUP.md

@@ -0,0 +1,276 @@
+# GeaStack Setup
+
+This guide gets a fresh machine ready to create, build, simulate, and flash Gea
+apps through the npm-first GeaStack flow.
+
+Start by running:
+
+```sh
+npx gea doctor
+```
+
+`doctor` checks the active app, board configuration, and the toolchains below.
+
+## Minimum Setup
+
+Private npmjs command shape:
+
+```sh
+npm login
+npx @geastack/create-geastack my-app
+cd my-app
+npx gea setup
+```
+
+For simulator-only development:
+
+- Node.js 20.19 or newer.
+- npm.
+- Emscripten SDK if you want `npx gea build --target web` and the WASM simulator
+  bundle path.
+
+For ESP32 hardware:
+
+- Node.js 20.19 or newer.
+- npm.
+- Python 3.
+- ESP-IDF v6.0.1.
+- `.gea/boards.json` configured for your board.
+
+For the Waveshare ESP32-S3 AMOLED board, use
+[ESP32-WAVESHARE-AMOLED-QUICKSTART.md](ESP32-WAVESHARE-AMOLED-QUICKSTART.md).
+
+For Apple targets:
+
+- macOS.
+- Xcode with iOS/macOS SDKs.
+- Xcode command line tools.
+- iOS Simulator runtime if building/running iOS simulator apps.
+
+For Android targets:
+
+- Android SDK command-line tools and platform tools.
+- `adb` on `PATH`.
+- A Java JDK with `javac`.
+- `ANDROID_HOME` or `ANDROID_SDK_ROOT` pointing at the Android SDK.
+
+## Node And npm
+
+Install Node.js from the official download page or your normal version manager.
+GeaStack currently requires Node.js 20.19 or newer. Node 24 LTS is a good
+default on new machines.
+
+Verify:
+
+```sh
+node --version
+npm --version
+```
+
+## ESP-IDF For ESP32 Targets
+
+The embedded board scripts currently target ESP-IDF v6.0.1. Newer ESP-IDF
+6.0.x releases may work, but v6.0.1 is the known target until the board scripts
+are updated.
+
+Command-line install:
+
+```sh
+npx gea setup --esp-idf
+```
+
+Equivalent manual install:
+
+```sh
+mkdir -p "$HOME/esp"
+cd "$HOME/esp"
+git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git
+cd esp-idf
+./install.sh esp32,esp32s3,esp32p4
+. ./export.sh
+idf.py --version
+```
+
+For every new shell where you build or flash ESP32 firmware, source the export
+script:
+
+```sh
+. "$HOME/esp/esp-idf/export.sh"
+```
+
+If ESP-IDF lives somewhere else, either source that location's `export.sh` before
+running Gea commands or set:
+
+```sh
+export GEA_EMBEDDED_IDF_EXPORT="/path/to/esp-idf/export.sh"
+```
+
+The board script also checks common locations such as `$HOME/esp/esp-idf`,
+`$HOME/esp32/esp-idf`, and `$HOME/esp32/esp-idf-v6.0.1`.
+
+Verify through GeaStack:
+
+```sh
+npx gea doctor
+npx gea setup
+npx gea build --board amoled --dry-run
+```
+
+Remove `--dry-run` when your board config is ready.
+
+## Emscripten For Web/WASM Simulator Builds
+
+The live web dev loop uses Vite. The WASM simulator build path additionally
+needs `emcc` from the Emscripten SDK.
+
+Install with `emsdk`:
+
+```sh
+git clone https://github.com/emscripten-core/emsdk.git "$HOME/emsdk"
+cd "$HOME/emsdk"
+./emsdk install latest
+./emsdk activate latest
+. ./emsdk_env.sh
+emcc --version
+```
+
+For every new shell where you run `npx gea build --target web`, source:
+
+```sh
+. "$HOME/emsdk/emsdk_env.sh"
+```
+
+Verify:
+
+```sh
+npx gea doctor
+npx gea build --target web
+```
+
+## Xcode For Apple Targets
+
+Install Xcode from the Mac App Store or Apple Developer resources. Then make
+sure command line tools point at the Xcode installation:
+
+```sh
+xcode-select --install
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+xcodebuild -version
+```
+
+Open Xcode once to finish first-run setup and install any required simulator
+runtimes from Xcode Settings > Platforms.
+
+For signed iOS device builds, set your Apple development team:
+
+```sh
+export GEA_IOS_DEVELOPMENT_TEAM=ABCDE12345
+```
+
+Verify:
+
+```sh
+npx gea doctor
+npx gea build --target macos
+npx gea build --target ios --mode simulator
+```
+
+## Android SDK
+
+Install Android Studio or the Android SDK command-line tools. Make sure the SDK
+has at least one platform and build-tools package installed, then export:
+
+```sh
+export ANDROID_HOME="$HOME/Library/Android/sdk"
+export PATH="$ANDROID_HOME/platform-tools:$PATH"
+```
+
+Verify:
+
+```sh
+adb version
+javac --version
+npx gea doctor
+npx gea build css-3d-cube --target android
+```
+
+For an attached Android device or board with USB debugging enabled:
+
+```sh
+npx gea build css-3d-cube --target android --mode device
+```
+
+If more than one adb is installed, point Gea at the one you want:
+
+```sh
+GEA_ANDROID_ADB="$ANDROID_HOME/platform-tools/adb" \
+GEA_ANDROID_SERIAL="<adb-serial>" \
+npx gea build css-3d-cube --target android --mode device
+```
+
+## Python
+
+Python 3 is used by device helpers, serial helpers, screenshots, and GeaOS
+device scripts.
+
+Verify:
+
+```sh
+python3 --version
+```
+
+If your platform does not provide Python 3, install it with your OS package
+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:
+
+```json
+{
+  "amoled": {
+    "target": "esp32-s3-touch-amoled-2.06",
+    "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
+```
+
+## Common Verification Flow
+
+After installing tools:
+
+```sh
+npx gea doctor
+npx gea inspect
+npx gea dev
+npx gea build --target web
+npx gea setup
+npx gea build --board amoled --dry-run
+npx gea flash --board amoled --monitor
+```
+
+Use `--dry-run` first when checking command routing. Remove it when the target
+toolchain and board config are ready.
+
+## Useful References
+
+- ESP-IDF Programming Guide: https://docs.espressif.com/projects/esp-idf/
+- Emscripten SDK downloads: https://emscripten.org/docs/getting_started/downloads.html
+- Node.js downloads: https://nodejs.org/en/download
+- Xcode resources: https://developer.apple.com/xcode/resources/

package/docs/SPEC.md

@@ -0,0 +1,217 @@
+# Gea CLI Specification
+
+This document captures the first useful shape of the `gea` command. The first
+implementation now ships in this repo; keep this spec aligned as the command
+surface grows.
+
+## Goals
+
+The CLI should make GeaStack feel like one npm-first toolchain:
+
+- start a web simulator for an app;
+- build an app for a selected target;
+- flash or install an app on hardware;
+- monitor logs;
+- diagnose missing toolchains, target backends, and board configuration;
+- scaffold a new app with a valid `gea` manifest.
+
+## Non-Goals
+
+The CLI should not duplicate target internals. It should delegate to stable
+backend commands owned by target repos.
+
+Examples:
+
+- ESP32 board flashing stays in `targets`.
+- Web simulator launch stays in `simulator`.
+- Apple project generation stays in `apple`.
+- Android APK packaging stays in `android`.
+- GeaOS image and device helpers stay in `geaos`.
+
+## Command Surface
+
+### `gea dev`
+
+Starts the fastest local development loop for an app.
+
+Expected behavior:
+
+- Resolve the app from the current folder, `--app`, or `package.json`.
+- Pick a default target of `web` unless `--target` says otherwise.
+- For web, delegate to `simulator/targets/web/dev-web.mjs`.
+- For hardware targets, print the intended build/deploy path and recommend
+  `gea flash` when live dev is not available.
+
+### `gea build`
+
+Builds an app for a target without mutating hardware.
+
+Expected options:
+
+```sh
+gea build --app bouncing-balls-jsx --target web
+gea build --app bouncing-balls-jsx --target esp32-s3-touch-amoled-2.06
+gea build --app notes-native --target macos
+gea build --app css-3d-cube --target android
+```
+
+### `gea setup`
+
+Runs one-time target initialization for a board or built-in target.
+
+Expected options:
+
+```sh
+gea setup --board amoled
+gea setup --target esp32-s3-touch-amoled-2.06
+```
+
+Without `--board` or `--target`, `gea setup` opens the interactive setup wizard.
+The wizard should support known boards and rich custom board profiles. When the
+selected profile is flash-ready, the wizard initializes the board target before
+returning.
+
+### `gea flash`
+
+Builds and deploys an app to a physical target.
+
+Expected options:
+
+```sh
+gea flash --app bouncing-balls-jsx --board amoled
+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.
+
+### `gea monitor`
+
+Starts a log monitor for a configured board or target.
+
+Expected options:
+
+```sh
+gea monitor --board amoled
+gea monitor --target esp32-s3-touch-amoled-2.06
+```
+
+### `gea doctor`
+
+Checks the local environment.
+
+Minimum checks:
+
+- Node/npm availability where required;
+- ESP-IDF availability for ESP32 targets;
+- Xcode availability for Apple targets;
+- Android SDK and adb availability for Android targets;
+- Python availability for device helpers;
+- configured boards file validity;
+- app manifest validity for the current folder.
+
+Human-readable output should point to [SETUP.md](SETUP.md) whenever a required
+or optional dependency is missing.
+
+### `create-geastack`
+
+Scaffolds a new app folder with:
+
+- `package.json` containing a `gea` manifest;
+- a bundled counter starter, an empty starter, or a selected GitHub example;
+- `index.tsx` or `index.ts`;
+- `tsconfig.json`;
+- `vite.config.ts`;
+- `.gea/boards.json`;
+- optional icons;
+- target compatibility flags.
+
+Interactive starter choices must explain the tradeoff in-line:
+
+- `Counter starter`: copy the bundled minimal JSX counter with one tiny store.
+- `Empty app`: generate the smallest blank app with no example-specific code.
+- `Rich example`: fetch a selected app from `geastack/examples`, then rewrite
+  package name, app id, dependencies, and board config for the new project.
+
+Rich example choices come from the hard-coded `examples/catalog.json`
+included in the `@geastack/cli` package. The package does not vendor rich
+example source files; it fetches the selected example from GitHub when the user
+chooses it. Native examples are first-class catalog entries: an iOS example must
+preserve `gea.targets.ios: true` so `npx gea build --target ios` routes through
+the Apple backend, and a macOS example must preserve `gea.targets.macos: true`.
+
+## App Manifest
+
+The CLI should recognize the `gea` field in `package.json`.
+
+Core fields:
+
+```json
+{
+  "gea": {
+    "id": "bouncing-balls-jsx",
+    "name": "Balls JSX",
+    "entry": "index.tsx",
+    "runtime": "gea",
+    "targets": {
+      "web": true,
+      "esp32": true,
+      "geaos": true,
+      "macos": false,
+      "ios": false,
+      "android": false
+    }
+  }
+}
+```
+
+Validation rules:
+
+- `id` is required and should be stable.
+- `entry` is required and must exist.
+- `runtime` defaults to `gea` when omitted.
+- `targets` must be explicit for generated apps.
+- target backends may reject apps whose runtime or capabilities they do not
+  support.
+
+## Backend Contract
+
+Each target backend should expose enough metadata for the CLI to:
+
+- list target id, display name, platform, and capabilities;
+- check local prerequisites;
+- build one app;
+- deploy one app when supported;
+- monitor logs when supported;
+- report useful errors in a structured way.
+
+A backend command can be a script, Node module, or binary. The CLI should keep
+the user-facing command stable even if a backend changes implementation
+language.
+
+## Exit Codes
+
+Use predictable exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Generic command failure. |
+| `2` | Invalid CLI usage or manifest. |
+| `3` | Missing local dependency. |
+| `4` | Target/backend unavailable. |
+| `5` | Build failed. |
+| `6` | Deploy or monitor failed. |
+
+## First Implementation Slice
+
+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`.
+5. Add `create-geastack` with one JSX app template.
+
+Status: implemented.