@geastack/cli 0.1.3 → 0.1.5

package/README.md

@@ -9,23 +9,24 @@ keeping target-specific build logic behind stable backend contracts.
 ## Commands
 
 ```sh
-npx @geastack/create-geastack my-panel
+npm install --global @geastack/cli
+gea create 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
+gea doctor
+gea setup
+gea dev
+gea build --target web
+gea build --target ios
+gea flash --board amoled --monitor
+gea monitor --board amoled
+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"]
+  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"]

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

@@ -30,7 +30,8 @@ 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
 ```
 
@@ -45,12 +46,12 @@ When the wizard asks what to create, choose:
 
 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`.
+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 +83,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 +94,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 +110,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 +123,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/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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,13 +40,19 @@ 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.3'
+  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)
+  }
 
   fs.mkdirSync(targetDir, { recursive: true })
   if (starter.kind === 'empty') {
-    fs.writeFileSync(path.join(targetDir, 'index.tsx'), indexTsx(displayName))
-    fs.writeFileSync(path.join(targetDir, 'styles.css'), stylesCss())
+    const entryPath = path.join(targetDir, entry)
+    fs.mkdirSync(path.dirname(entryPath), { recursive: true })
+    fs.writeFileSync(entryPath, indexTsx(displayName))
+    fs.writeFileSync(path.join(path.dirname(entryPath), 'styles.css'), stylesCss())
   } else if (starter.kind === 'bundled') {
     copyStarterFiles(starter.starter.root, targetDir)
   } else if (starter.kind === 'example') {
@@ -69,12 +77,14 @@ export async function runCreateGeastack(argv, io = {}) {
     appId,
     displayName,
     targets,
+    entry,
+    bleOta: flag(parsed, 'ble-ota'),
     coreDependency,
     cliDependency,
     sourcePackage,
     sourceManifest
   }))
-  ensureFile(path.join(targetDir, 'index.html'), () => indexHtml(displayName))
+  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)
@@ -203,14 +213,15 @@ function targetManifestFromObject(targets = {}) {
   }
 }
 
-function packageJson({ appId, displayName, targets, coreDependency, cliDependency, sourcePackage = {}, sourceManifest = {} }) {
+function packageJson({ appId, displayName, targets, entry, bleOta, coreDependency, cliDependency, sourcePackage = {}, sourceManifest = {} }) {
   const geaManifest = {
     ...sourceManifest,
     id: appId,
     name: displayName,
-    entry: sourceManifest.entry || 'index.tsx',
+    entry,
     targets
   }
+  if (bleOta) geaManifest.ota = { ...(geaManifest.ota || {}), ble: true }
   if (!geaManifest.runtime || geaManifest.runtime === 'gea') delete geaManifest.runtime
 
   return {
@@ -299,7 +310,7 @@ h1 {
 `
 }
 
-function indexHtml(displayName) {
+function indexHtml(displayName, entry = 'index.tsx') {
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -309,7 +320,7 @@ function indexHtml(displayName) {
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/index.tsx"></script>
+    <script type="module" src="/${entry}"></script>
   </body>
 </html>
 `
@@ -398,6 +409,14 @@ function normalizeStarter(value) {
   return normalized
 }
 
+function projectRelativePath(value, label) {
+  const normalized = path.posix.normalize(String(value || '').replaceAll('\\', '/')).replace(/^\.\//, '')
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+    fail(`--${label} must be a path inside the project.`, ExitCode.usage)
+  }
+  return normalized
+}
+
 function readPackageJson(targetDir) {
   const packagePath = path.join(targetDir, 'package.json')
   if (!exists(packagePath)) return {}
@@ -422,6 +441,8 @@ 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/src/gea.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path'
+import fs from 'node:fs'
 
 import { flag, option, parseArgs } from './args.mjs'
+import { runCreateGeastack } from './create-geastack.mjs'
 import { createChildEnv, createContext } from './context.mjs'
 import { ExitCode, fail } from './errors.mjs'
 import { exists, readJson } from './fs-utils.mjs'
@@ -18,7 +20,7 @@ import { runExternal } from './run.mjs'
 import { runSetupWizard } from './setup-wizard.mjs'
 import { commandVersion, nodeAtLeast } from './toolchain.mjs'
 
-const version = '0.1.1'
+const version = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
 export async function runGea(argv, io = {}) {
   const parsed = parseArgs(argv)
@@ -35,6 +37,11 @@ export async function runGea(argv, io = {}) {
     stdout(version)
     return 0
   }
+  if (command === 'create') {
+    const createArgs = argv.slice(1)
+    if (option(parsed, 'install') === undefined) createArgs.push('--install')
+    return runCreateGeastack(createArgs, io)
+  }
   if (!command || command === 'help' || flag(parsed, 'help')) {
     stdout(usage())
     return 0
@@ -422,6 +429,7 @@ function requirePath(filePath, label) {
 
 function usage() {
   return `Usage:
+  gea create <name> [--starter counter|empty|example] [--targets <list>]
   gea doctor [--strict] [--json]
   gea setup --board <alias>
   gea dev [app] [--target web] [--port 5181]