@geastack/cli 0.1.5 → 0.1.7

package/README.md

@@ -29,12 +29,12 @@ flowchart TD
   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

@@ -38,13 +38,16 @@ 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 and installs all of its project dependencies.
 

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

@@ -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.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
   "publishConfig": {

package/src/create-geastack.mjs

@@ -22,9 +22,10 @@ export async function runCreateGeastack(argv, io = {}) {
   const stdout = io.stdout || console.log
   const env = io.env || process.env
   const cwd = io.cwd || process.cwd()
+  const commandName = io.commandName || 'create-geastack'
 
   if (flag(parsed, 'help') || parsed.positionals[0] === 'help') {
-    stdout(usage())
+    stdout(usage(commandName))
     return 0
   }
 
@@ -42,10 +43,7 @@ export async function runCreateGeastack(argv, io = {}) {
   const coreDependency = option(parsed, 'core-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') {
@@ -70,26 +68,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) {
@@ -157,11 +157,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'
   })
@@ -213,7 +225,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,
@@ -221,7 +233,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 {
@@ -231,8 +242,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: {
@@ -244,7 +254,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'
@@ -358,12 +368,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}\`.
@@ -371,9 +391,7 @@ GeaStack app id: \`${appId}\`.
 ${starterLine}
 
 \`\`\`sh
-npx gea setup
-npx gea dev
-npx gea build --target web
+${commands}
 \`\`\`
 `
 }
@@ -431,21 +449,28 @@ function ensureJson(filePath, create) {
   if (!exists(filePath)) writeJson(filePath, create())
 }
 
-function usage() {
+function usage(commandName = 'create-geastack') {
   return `Usage:
-  create-geastack <name> [--dir <path>] [--id <app-id>] [--name <display-name>]
+  ${commandName} <name>
+
+Run without options for guided setup. The CLI asks what you want to build and
+derives the source layout, targets, and runtime configuration from your choice.
 
 Options:
-  --starter counter|empty|example
+  --starter counter|blank|example
   --example <example-id>
+  --no-install
+
+Automation options:
+  --dir <path>
+  --id <app-id>
+  --name <display-name>
   --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
+  --install
   --dry-run
   --yes
   --force

package/src/gea.mjs

@@ -40,7 +40,7 @@ export async function runGea(argv, io = {}) {
   if (command === 'create') {
     const createArgs = argv.slice(1)
     if (option(parsed, 'install') === undefined) createArgs.push('--install')
-    return runCreateGeastack(createArgs, io)
+    return runCreateGeastack(createArgs, { ...io, commandName: 'gea create' })
   }
   if (!command || command === 'help' || flag(parsed, 'help')) {
     stdout(usage())

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;
-}