@geastack/cli 0.1.4 → 0.1.6

package/README.md

@@ -26,15 +26,15 @@ gea inspect --json
 
 ```mermaid
 flowchart TD
-  create["npx @geastack/create-geastack my-app"] --> identity["Resolve app identity<br/>argument, optional --id, optional --name"]
+  create["gea create 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 -->|"Embedded component counter"| counter["Copy the touchscreen counter used in the embedded tutorial"]
 
-  starter -->|"Empty app"| empty["Generate minimal app files"]
+  starter -->|"Blank application"| empty["Generate a minimal browser application"]
   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"]
+  starter -->|"Example application"| pickExample["Pick from the example gallery<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"]

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

@@ -30,27 +30,31 @@ You do not clone GeaStack.
 
 ```sh
 npm login
-npx @geastack/create-geastack my-app
+npm install --global @geastack/cli
+gea create 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
+? What do you want to build?
+  Embedded component counter
+    Touchscreen +/− counter with local state and BLE updates, ready for ESP32.
+  Blank application
+    A minimal screen for building your own Gea application.
+  Example application
+    Choose a complete application from the GeaStack example gallery.
 ```
 
-For the fastest first flash, choose `Counter starter`.
+For the fastest first flash, choose `Embedded component counter`.
 
-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`.
+That creates a tiny JSX app and installs all of its project dependencies.
 
 ## 3. Set Up The Board
 
 ```sh
-npx gea setup
+gea setup
 ```
 
 Choose:
@@ -82,7 +86,7 @@ If ESP-IDF was installed, the CLI prints this for future shells:
 . "$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.
+You do not need to run that before every command unless `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.
 
@@ -93,13 +97,13 @@ The wizard writes the board config into your app at `.gea/boards.json` and initi
 Flash and open the serial monitor:
 
 ```sh
-npx gea flash --board amoled --monitor
+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
+gea flash --board amoled --port /dev/cu.usbmodemXXXX --monitor
 ```
 
 ## Rich Examples
@@ -109,10 +113,10 @@ The bundled starter is intentionally tiny. Rich examples live in the GeaStack ex
 For example:
 
 ```sh
-npx @geastack/create-geastack watch-demo --starter example --example watch
+gea create watch-demo --starter example --example watch
 cd watch-demo
-npx gea setup
-npx gea flash --board amoled --monitor
+gea setup
+gea flash --board amoled --monitor
 ```
 
 The CLI owns the example catalog, so the user does not need to clone the examples repo.
@@ -122,7 +126,7 @@ The CLI owns the example catalog, so the user does not need to clone the example
 Run:
 
 ```sh
-npx gea doctor
+gea doctor
 ```
 
 Most first-run issues are one of:

package/docs/NPX-COMMANDS.md

@@ -44,20 +44,20 @@ 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
+What do you want to build?
+1. Embedded component counter
+2. Blank application
+3. Example application
 ```
 
-`Counter starter` is the only bundled source starter. It is intentionally tiny:
-JSX, one `store.ts`, and enough styling to run.
+`Embedded component counter` is the bundled tutorial starter. It uses local
+component state, targets ESP32, and enables BLE updates.
 
-`Empty app` creates the smallest starter: `index.tsx`, `styles.css`,
+`Blank application` creates the smallest browser 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
+`Example application` 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

package/docs/SPEC.md

@@ -115,7 +115,7 @@ Minimum checks:
 Human-readable output should point to [SETUP.md](SETUP.md) whenever a required
 or optional dependency is missing.
 
-### `create-geastack`
+### `gea create`
 
 Scaffolds a new app folder with:
 
@@ -130,9 +130,10 @@ Scaffolds a new app folder with:
 
 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
+- `Embedded component counter`: create a touchscreen counter with local
+  component state, an ESP32 target, and BLE updates enabled.
+- `Blank application`: generate a minimal browser application as a clean slate.
+- `Example application`: 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
   "publishConfig": {

package/src/create-geastack.mjs

@@ -15,6 +15,8 @@ import {
   formatStarterChoice
 } from './starter-catalog.mjs'
 
+const cliVersion = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
 export async function runCreateGeastack(argv, io = {}) {
   const parsed = parseArgs(argv)
   const stdout = io.stdout || console.log
@@ -38,12 +40,9 @@ export async function runCreateGeastack(argv, io = {}) {
   const ctx = createContext(parsed, env, cwd)
   const displayName = option(parsed, 'name', titleFromId(appId))
   const coreDependency = option(parsed, 'core-dependency') || '^0.1.4'
-  const cliDependency = option(parsed, 'cli-dependency') || '^0.1.4'
+  const cliDependency = option(parsed, 'cli-dependency') || `^${cliVersion}`
   const starter = await resolveStarter(ctx, parsed, io)
-  const entry = projectRelativePath(option(parsed, 'entry') || starter.starter?.entry || starter.example?.entry || 'index.tsx', 'entry')
-  if (option(parsed, 'entry') && starter.kind !== 'empty') {
-    fail('--entry can only be used with --starter empty.', ExitCode.usage)
-  }
+  const entry = projectRelativePath(starter.starter?.entry || starter.example?.entry || 'index.tsx', 'entry')
 
   fs.mkdirSync(targetDir, { recursive: true })
   if (starter.kind === 'empty') {
@@ -68,26 +67,28 @@ export async function runCreateGeastack(argv, io = {}) {
 
   const sourcePackage = readPackageJson(targetDir)
   const sourceManifest = sourcePackage.gea || starter.starter?.manifest || starter.example?.manifest || {}
-  const targets = optionList(parsed, 'targets').length === 0
-    ? targetManifestFromObject(sourceManifest.targets)
-    : targetManifest(optionList(parsed, 'targets'))
+  const requestedTargets = optionList(parsed, 'targets')
+  const targets = requestedTargets.length > 0
+    ? targetManifest(requestedTargets)
+    : starter.kind === 'empty'
+      ? targetManifest(['web'])
+      : targetManifestFromObject(sourceManifest.targets)
   writeJson(path.join(targetDir, 'package.json'), packageJson({
     appId,
     displayName,
     targets,
     entry,
-    bleOta: flag(parsed, 'ble-ota'),
     coreDependency,
     cliDependency,
     sourcePackage,
     sourceManifest
   }))
-  ensureFile(path.join(targetDir, 'index.html'), () => indexHtml(displayName, entry))
+  if (targets.web) ensureFile(path.join(targetDir, 'index.html'), () => indexHtml(displayName, entry))
   fs.mkdirSync(path.join(targetDir, '.gea'), { recursive: true })
   writeJson(path.join(targetDir, '.gea', 'boards.json'), {})
   ensureJson(path.join(targetDir, 'tsconfig.json'), tsconfigJson)
-  ensureFile(path.join(targetDir, 'vite.config.ts'), viteConfigTs)
-  fs.writeFileSync(path.join(targetDir, 'README.md'), readme({ appId, displayName, starter }))
+  if (targets.web) ensureFile(path.join(targetDir, 'vite.config.ts'), viteConfigTs)
+  fs.writeFileSync(path.join(targetDir, 'README.md'), readme({ appId, displayName, starter, targets }))
 
   const installDependencies = shouldInstallDependencies(parsed, io)
   if (installDependencies) {
@@ -155,11 +156,23 @@ async function resolveStarter(ctx, parsed, io) {
 async function chooseStarterMode({ interactive, prompt, bundled, examples }) {
   if (!interactive) return bundled.length > 0 ? 'counter' : 'empty'
   return choose(prompt, {
-    message: 'Starter app',
+    message: 'What do you want to build?',
     choices: [
-      ...(bundled.length > 0 ? [{ value: 'counter', label: 'Counter starter - bundled minimal JSX app' }] : []),
-      { value: 'empty', label: 'Empty app - minimal blank Gea app' },
-      ...(examples.length > 0 ? [{ value: 'example', label: 'Rich example - fetch from GitHub examples repo' }] : [])
+      ...(bundled.length > 0 ? [{
+        value: 'counter',
+        label: 'Embedded component counter',
+        description: 'Touchscreen +/− counter with local state and BLE updates, ready for ESP32.'
+      }] : []),
+      {
+        value: 'empty',
+        label: 'Blank application',
+        description: 'A minimal screen for building your own Gea application.'
+      },
+      ...(examples.length > 0 ? [{
+        value: 'example',
+        label: 'Example application',
+        description: 'Choose a complete application from the GeaStack example gallery.'
+      }] : [])
     ],
     defaultValue: bundled.length > 0 ? 'counter' : 'empty'
   })
@@ -211,7 +224,7 @@ function targetManifestFromObject(targets = {}) {
   }
 }
 
-function packageJson({ appId, displayName, targets, entry, bleOta, coreDependency, cliDependency, sourcePackage = {}, sourceManifest = {} }) {
+function packageJson({ appId, displayName, targets, entry, coreDependency, cliDependency, sourcePackage = {}, sourceManifest = {} }) {
   const geaManifest = {
     ...sourceManifest,
     id: appId,
@@ -219,7 +232,6 @@ function packageJson({ appId, displayName, targets, entry, bleOta, coreDependenc
     entry,
     targets
   }
-  if (bleOta) geaManifest.ota = { ...(geaManifest.ota || {}), ble: true }
   if (!geaManifest.runtime || geaManifest.runtime === 'gea') delete geaManifest.runtime
 
   return {
@@ -229,8 +241,7 @@ function packageJson({ appId, displayName, targets, entry, bleOta, coreDependenc
     type: 'module',
     scripts: {
       ...(sourcePackage.scripts || {}),
-      dev: 'gea dev',
-      build: 'gea build --target web',
+      ...(targets.web ? { dev: 'gea dev', build: 'gea build --target web' } : {}),
       check: 'tsc --noEmit'
     },
     dependencies: {
@@ -242,7 +253,7 @@ function packageJson({ appId, displayName, targets, entry, bleOta, coreDependenc
       ...(sourcePackage.devDependencies || {}),
       '@geastack/cli': cliDependency,
       typescript: sourcePackage.devDependencies?.typescript || 'latest',
-      vite: sourcePackage.devDependencies?.vite || 'latest'
+      ...(targets.web ? { vite: sourcePackage.devDependencies?.vite || 'latest' } : {})
     },
     gea: geaManifest,
     license: 'MIT'
@@ -356,12 +367,22 @@ export default defineConfig({
 `
 }
 
-function readme({ appId, displayName, starter }) {
+function readme({ appId, displayName, starter, targets }) {
   const starterLine = starter.kind === 'example'
     ? `Started from GitHub example: \`${starter.example.name}\` (\`${starter.example.id}\`).`
     : starter.kind === 'bundled'
       ? `Started from bundled starter: \`${starter.starter.name}\` (\`${starter.starter.id}\`).`
-      : 'Started from an empty app.'
+      : 'Started from a blank app.'
+  const commands = targets.web
+    ? `npx gea setup
+npx gea dev
+npx gea build --target web`
+    : targets.esp32
+      ? `npx gea setup
+npx gea build --board <alias>
+npx gea flash --board <alias> --monitor`
+      : `npx gea setup
+npx gea build`
   return `# ${displayName}
 
 GeaStack app id: \`${appId}\`.
@@ -369,9 +390,7 @@ GeaStack app id: \`${appId}\`.
 ${starterLine}
 
 \`\`\`sh
-npx gea setup
-npx gea dev
-npx gea build --target web
+${commands}
 \`\`\`
 `
 }
@@ -439,8 +458,6 @@ Options:
   --examples-repo <git-url-or-local-path>
   --examples-ref <git-ref>
   --targets web,esp32,rp2350,geaos,macos,ios,android
-  --entry <relative-path>
-  --ble-ota
   --core-dependency <specifier>
   --cli-dependency <specifier>
   --install / --no-install

package/starters/bundled/counter/package.json

@@ -3,30 +3,31 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "Minimal JSX counter with one tiny store.",
+  "description": "Touchscreen counter with component-local reactive state.",
   "scripts": {
-    "build": "vite build",
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@geajs/core": "^1.3.0"
+    "@geajs/core": "latest"
   },
   "devDependencies": {
-    "typescript": "latest",
-    "vite": "latest"
+    "typescript": "latest"
   },
   "gea": {
     "id": "counter",
-    "name": "Counter",
-    "description": "Minimal JSX counter with one tiny store.",
-    "entry": "index.tsx",
+    "name": "Component Counter",
+    "description": "Touchscreen counter with component-local reactive state.",
+    "entry": "src/index.tsx",
     "targets": {
-      "web": true,
+      "web": false,
       "esp32": true,
-      "rp2350": true,
-      "geaos": true,
+      "rp2350": false,
+      "geaos": false,
       "macos": false,
       "ios": false
+    },
+    "ota": {
+      "ble": true
     }
   }
 }

package/starters/bundled/counter/src/App.tsx

@@ -0,0 +1,28 @@
+import { ReactiveComponent } from '@geastack/core'
+import './styles.css'
+
+export class App extends ReactiveComponent {
+  count = 0
+
+  decrement() {
+    this.count = this.count - 1
+  }
+
+  increment() {
+    this.count = this.count + 1
+  }
+
+  template() {
+    return (
+      <div class="screen">
+        <span class="eyebrow">GEASTACK</span>
+        <span class="title">Component state</span>
+        <span class="count">{this.count}</span>
+        <div class="controls">
+          <button class="button secondary" onClick={() => this.decrement()}>−</button>
+          <button class="button primary" onClick={() => this.increment()}>+</button>
+        </div>
+      </div>
+    )
+  }
+}

package/starters/bundled/counter/src/index.tsx

@@ -0,0 +1,4 @@
+import { mount } from '@geastack/core'
+import { App } from './App'
+
+mount(App)

package/starters/bundled/counter/src/styles.css

@@ -0,0 +1,20 @@
+.screen {
+  display: flex;
+  flex-direction: column;
+  width: 100vw;
+  height: 100vh;
+  padding: 28px;
+  gap: 16px;
+  align-items: center;
+  justify-content: center;
+  background-color: #080b12;
+  color: #f8fafc;
+}
+
+.eyebrow { color: #2dd4bf; font-size: 13px; }
+.title { color: #cbd5e1; font-size: 22px; }
+.count { color: #ffffff; font-size: 76px; line-height: 1; }
+.controls { display: flex; flex-direction: row; gap: 16px; }
+.button { width: 92px; height: 58px; border-radius: 14px; border-width: 2px; font-size: 30px; }
+.secondary { color: #f8fafc; background-color: #1e293b; border-color: #475569; }
+.primary { color: #042f2e; background-color: #2dd4bf; border-color: #5eead4; }

package/starters/bundled/counter/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "jsx": "preserve",
+    "types": []
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts"]
+}

package/starters/catalog.json

@@ -3,15 +3,15 @@
   "starters": [
     {
       "id": "counter",
-      "name": "Counter",
-      "description": "Minimal JSX counter with one tiny store.",
+      "name": "Component Counter",
+      "description": "Touchscreen counter with component-local reactive state and BLE updates.",
       "path": "bundled/counter",
-      "entry": "index.tsx",
+      "entry": "src/index.tsx",
       "targets": {
-        "web": true,
+        "web": false,
         "esp32": true,
-        "rp2350": true,
-        "geaos": true,
+        "rp2350": false,
+        "geaos": false,
         "macos": false,
         "ios": false,
         "android": false

package/starters/bundled/counter/index.tsx

@@ -1,25 +0,0 @@
-import { mount } from '@geastack/core'
-import { counter } from './store'
-import './styles.css'
-
-function App() {
-  function increment() {
-    const value = counter.increment()
-    const count = document.querySelector('[data-count]')
-    if (count) count.textContent = String(value)
-  }
-
-  return (
-    <body class="app">
-      <main class="panel">
-        <p class="eyebrow">GeaStack</p>
-        <h1>Counter</h1>
-        <button class="button" onClick={increment}>
-          Count <span data-count>0</span>
-        </button>
-      </main>
-    </body>
-  )
-}
-
-mount(App)

package/starters/bundled/counter/store.ts

@@ -1,7 +0,0 @@
-export const counter = {
-  value: 0,
-  increment() {
-    this.value += 1
-    return this.value
-  }
-}

package/starters/bundled/counter/styles.css

@@ -1,39 +0,0 @@
-.app {
-  width: 100vw;
-  height: 100vh;
-  margin: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: #101418;
-  color: #f8fafc;
-  font-family: Inter, system-ui, sans-serif;
-}
-
-.panel {
-  width: min(320px, calc(100vw - 32px));
-  padding: 24px;
-  border: 1px solid #2dd4bf;
-  background: #182026;
-}
-
-.eyebrow {
-  margin: 0 0 8px;
-  color: #2dd4bf;
-  font-size: 12px;
-  text-transform: uppercase;
-}
-
-h1 {
-  margin: 0 0 16px;
-  font-size: 28px;
-}
-
-.button {
-  min-width: 120px;
-  min-height: 40px;
-  border: 0;
-  background: #2dd4bf;
-  color: #081018;
-  font: inherit;
-}