@geastack/cli 0.1.83 → 0.1.85

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -165,6 +165,9 @@ expose stable command contracts.
165
165
 
166
166
  ## Documentation
167
167
 
168
+ - [docs/PEBBLE-QUICKSTART.md](docs/PEBBLE-QUICKSTART.md): install the Pebble SDK,
169
+ enable a TSX app, build a `.pbw`, and run on Pebble Time 2 or its emulator.
170
+
168
171
  - [docs/SPEC.md](docs/SPEC.md): command surface, manifest expectations, and
169
172
  backend contract for the first implementation.
170
173
  - [docs/SETUP.md](docs/SETUP.md): toolchains per target, the ESP-IDF version
@@ -192,3 +195,25 @@ built on it. The only GeaStack code under a different license is
192
195
  the embedded board support (`targets` and `@geastack/chips`, GPL-3.0-only):
193
196
  shipping closed-source firmware through those needs a commercial license.
194
197
  Contact [contact@geastack.com](mailto:contact@geastack.com) for commercial terms, support and hosted builds.
198
+
199
+ ## Browser development and emulation
200
+
201
+ `gea dev` (equivalently `gea dev --target web`) runs the Gea DOM/CSS app with
202
+ Vite HMR. `gea simulate` uses that same pipeline inside a device viewport and
203
+ opens the browser. Use `--no-open` to suppress opening, and `--width`, `--height`,
204
+ `--zoom`, and `--dpr` to configure the preview. DPR is a simulated Display API
205
+ value; it does not override the browser's pixel ratio.
206
+
207
+ The default for `simulate` changed from WASM to DOM. To retain the embedded
208
+ renderer and framebuffer workflow, use `gea simulate --renderer wasm`; this
209
+ explicit mode still requires Emscripten. Unknown renderer values are rejected.
210
+
211
+ `gea build --target web` emits HTML/JS/CSS into `.gea/build/web/site` (override
212
+ with `--out-dir`). The app's `index.html` is honored. Web-only Vite customization
213
+ belongs in `vite.web.config.ts`; new web apps scaffold this file. Existing
214
+ `vite.config.*` files remain dedicated to their previous build pipeline.
215
+
216
+ Compatible component edits and CSS changes update without reloading the page;
217
+ reactive state is preserved for compatible component edits. Incompatible edits
218
+ reload. Browser previews use simulated device APIs and browser layout; use the
219
+ WASM renderer or a physical device to validate embedded rendering.
@@ -0,0 +1,82 @@
1
+ # Pebble Time 2 quickstart
2
+
3
+ Requires Gea CLI 0.1.85 or newer, Node.js 20.19 or newer, Bash, and the Pebble
4
+ SDK. This target builds ordinary `.pbw` apps for Pebble Time 2 (`emery`);
5
+ it does not flash watch firmware. The build script supports macOS and Linux.
6
+
7
+ ## Install
8
+
9
+ Install the SDK and its toolchain:
10
+
11
+ ```sh
12
+ uv tool install --python 3.13 pebble-tool
13
+ pebble sdk install latest
14
+ ```
15
+
16
+ In an existing Gea TSX app:
17
+
18
+ ```sh
19
+ npm install @geastack/core@^0.1.26 @geastack/pebble@^0.1.0
20
+ npm install --save-dev @geastack/cli@^0.1.85
21
+ ```
22
+
23
+ The Pebble package installs the native engine, host, elements and geaos
24
+ packages it needs; core supplies the compiler and Gea compiler plugin.
25
+ Keep your existing app dependencies and add `pebble` to its manifest:
26
+
27
+ ```json
28
+ {
29
+ "gea": {
30
+ "id": "my-watch-app",
31
+ "name": "My Watch App",
32
+ "entry": "index.tsx",
33
+ "runtime": "gea",
34
+ "targets": { "pebble": true }
35
+ }
36
+ }
37
+ ```
38
+
39
+ This is a fragment to merge into `package.json`. Preserve other targets you
40
+ already use. A custom entry such as `src/watch.tsx` is supported.
41
+ The generic scaffold wizard does not yet offer a Pebble preset; enable the
42
+ platform on an existing app as above. No board alias is required.
43
+
44
+ ## Build and run
45
+
46
+ Run from the app directory:
47
+
48
+ ```sh
49
+ npx gea build --target pebble
50
+ npx gea run --target pebble
51
+ npx gea run --target pebble --phone 192.168.1.23
52
+ ```
53
+
54
+ Build writes `dist/pebble/<gea.id>.pbw`. Run builds first, then installs on the
55
+ `emery` emulator by default. For a physical watch, enable the developer
56
+ connection in the Pebble phone app, keep the watch connected to the phone,
57
+ and pass the phone's reachable IP address. UP/DOWN move focus, SELECT presses
58
+ the focused control, BACK exits, and touch taps controls.
59
+
60
+ In a workspace, select an app with `--app <gea.id>`. `--dry-run` prints the
61
+ build command without compiling or installing; it still requires the Pebble
62
+ package to be installed.
63
+
64
+ ## Troubleshooting and limits
65
+
66
+ - Missing `@geastack/pebble`: run the npm install commands in the app directory.
67
+ - Missing SDK toolchain: run `pebble sdk install latest`, or set
68
+ `PEBBLE_SDK_ROOT` to your SDK directory. Ensure `pebble` is on `PATH`.
69
+ - Build failure: inspect `dist/pebble/obj/codegen.log` and
70
+ `dist/pebble/obj/pebble-build.log`; the command prints the failing log's tail.
71
+ - Failed phone installation: check the phone's developer connection, IP and
72
+ network reachability. A successful build alone does not verify installation.
73
+ - This target has a 64 KB app-image limit and shares 128 KB between code and
74
+ heap. Only the `emery` platform is supported. JavaScript exceptions end the
75
+ app; `catch` does not run on this target.
76
+
77
+ LLVM plus a matching `ld.lld` is optional and produces smaller programs.
78
+ `GEA_PEBBLE_TOOLCHAIN=gcc` forces the SDK's GCC;
79
+ `GEA_PEBBLE_UI=engine` disables build-time UI specialization.
80
+
81
+ See the [Pebble package documentation](https://github.com/geastack/pebble/tree/main/packages/geastack-pebble)
82
+ for rendering support, memory limits, diagnostics and implementation details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.83",
3
+ "version": "0.1.85",
4
4
  "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -37,13 +37,13 @@
37
37
  ],
38
38
  "dependencies": {
39
39
  "@clack/prompts": "^1.8.0",
40
- "@geastack/simulator": "^0.1.6",
40
+ "@geastack/simulator": "^0.1.9",
41
41
  "@geastack/targets": "^0.1.82",
42
42
  "picocolors": "^1.1.1",
43
43
  "serialport": "^13.0.0"
44
44
  },
45
45
  "starterDependencies": {
46
- "@geastack/core": "^0.1.24",
46
+ "@geastack/core": "^0.1.26",
47
47
  "@geastack/targets": "^0.1.82",
48
48
  "@geastack/apple": "^0.2.9"
49
49
  },
@@ -97,7 +97,7 @@ export async function runCreateGeastack(argv, io = {}) {
97
97
  writeJson(path.join(targetDir, '.gea', 'boards.json'), {})
98
98
  ensureJson(path.join(targetDir, 'tsconfig.json'), () => tsconfigJson(targets))
99
99
  ensureFile(path.join(targetDir, '.gitignore'), gitignore)
100
- if (targets.web) ensureFile(path.join(targetDir, 'vite.config.ts'), viteConfigTs)
100
+ if (targets.web) ensureFile(path.join(targetDir, 'vite.web.config.ts'), viteConfigTs)
101
101
  fs.writeFileSync(path.join(targetDir, 'README.md'), readme({ appId, displayName, starter, targets }))
102
102
 
103
103
  const installDependencies = shouldInstallDependencies(parsed, io)
@@ -472,7 +472,7 @@ function tsconfigJson(targets) {
472
472
  types: []
473
473
  },
474
474
  include: ['**/*.ts', '**/*.tsx', '**/*.d.ts'],
475
- exclude: ['node_modules', 'dist', '.gea', 'vite.config.ts']
475
+ exclude: ['node_modules', 'dist', '.gea', 'vite.config.ts', 'vite.web.config.ts']
476
476
  }
477
477
  }
478
478
 
@@ -488,11 +488,7 @@ function viteConfigTs() {
488
488
  return `import { defineConfig } from 'vite'
489
489
 
490
490
  export default defineConfig({
491
- root: __dirname,
492
- build: {
493
- outDir: 'dist',
494
- emptyOutDir: true
495
- }
491
+ // Gea adds the DOM runtime and JSX transforms. Add web-only options here.
496
492
  })
497
493
  `
498
494
  }
package/src/gea.mjs CHANGED
@@ -113,11 +113,20 @@ export async function runGea(argv, io = {}) {
113
113
  const { runIos } = await import('./ios/adapter.mjs')
114
114
  return runIos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, mode: option(parsed, 'mode', ''), run: command === 'run' })
115
115
  }
116
- // `web` names two targets, and both are driven by gea, so it leaves the
117
- // refusal below the way macos does above. `gea simulate` is the WASM device
118
- // simulator; `gea {dev,build} --target web` is a real DOM/CSS web app. A bare
119
- // `gea dev` means the latter -- it is the only target with a dev server, and
120
- // it is what `gea create` scaffolds into a new app's package.json.
116
+ // Pebble is driven by one script inside @geastack/pebble, like iOS inside
117
+ // @geastack/apple, and like iOS it is never a host default. `gea build
118
+ // --target pebble` produces the .pbw; `gea run --target pebble` installs it on
119
+ // the emery emulator, or on a watch through the phone at `--phone <ip>`.
120
+ if ((command === 'build' || command === 'run') && target === 'pebble') {
121
+ const app = parsed.options.app || rest[0] ? findAppById(ctx, String(parsed.options.app || rest[0])) : findCurrentApp(cwd)
122
+ if (!app?.targets?.pebble) {
123
+ fail(app ? `'${app.id}' does not declare gea.targets.pebble.` : 'No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
124
+ }
125
+ const { runPebble } = await import('./pebble/adapter.mjs')
126
+ return runPebble({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, phone: option(parsed, 'phone', ''), run: command === 'run' })
127
+ }
128
+ // DOM is the default web development and emulator runtime. The embedded
129
+ // framebuffer simulator remains available through simulate --renderer wasm.
121
130
  if ((command === 'dev' || command === 'build') && (target === 'web' || (!target && command === 'dev'))) {
122
131
  const app = webApp(ctx, parsed, rest, cwd)
123
132
  const { runWebBuild, runWebDev } = await import('./web/adapter.mjs')
@@ -127,15 +136,24 @@ export async function runGea(argv, io = {}) {
127
136
  }
128
137
  if (command === 'simulate') {
129
138
  const app = webApp(ctx, parsed, rest, cwd)
139
+ const renderer = option(parsed, 'renderer', 'dom')
140
+ if (!['dom', 'wasm'].includes(renderer)) fail(`Unknown renderer '${renderer}'. Use dom or wasm.`, ExitCode.usage)
141
+ for (const key of ['width', 'height', 'dpr', 'zoom']) {
142
+ const value = option(parsed, key)
143
+ if (value !== undefined && (typeof value === 'boolean' || !Number.isFinite(Number(value)) || Number(value) <= 0)) {
144
+ fail(`--${key} must be a positive number.`, ExitCode.usage)
145
+ }
146
+ }
130
147
  const { runSimulate } = await import('./web/adapter.mjs')
131
148
  return runSimulate({
149
+ renderer,
132
150
  ctx,
133
151
  app,
134
152
  env,
135
153
  dryRun: flag(parsed, 'dry-run'),
136
154
  stdout,
137
155
  port: option(parsed, 'port', ''),
138
- open: !flag(parsed, 'no-open'),
156
+ open: option(parsed, 'open', true) !== false,
139
157
  view: {
140
158
  width: option(parsed, 'width', ''),
141
159
  height: option(parsed, 'height', ''),
@@ -226,15 +244,17 @@ ${heading('Usage:')}
226
244
  gea doctor [--json] [--strict] check packages and toolchains
227
245
 
228
246
  ${heading('Run on this machine (no board needed):')}
229
- gea simulate [app] [--port N] build to WASM + open the device simulator [--no-open] [--width W --height H --dpr D --zoom Z]
247
+ gea simulate [app] [--port N] DOM emulator with HMR [--renderer dom|wasm] [--no-open] [--width W --height H --dpr D --zoom Z]
230
248
  gea dev [app] [--port N] real DOM + CSS dev server with HMR (same as --target web)
231
249
  gea build --target web [app] [--out-dir d] build the app as a real web app
232
250
 
233
- ${heading('Native desktop and mobile apps (scripts ship in @geastack/apple and @geastack/windows):')}
251
+ ${heading('Native desktop, mobile and watch apps (scripts ship in @geastack/apple, @geastack/windows and @geastack/pebble):')}
234
252
  gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
235
253
  gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
236
254
  gea run --target ios [app] [--mode simulator|device] build, then install and launch on a simulator or iPhone
237
255
  gea build|run --target windows [app] build (and launch) the Windows executable
256
+ gea build --target pebble [app] build a Pebble Time 2 app (.pbw); needs the Pebble SDK
257
+ gea run --target pebble [app] [--phone <ip>] build, then install on the emery emulator or a watch via its phone
238
258
 
239
259
  ${heading('Build and deploy (device commands take --board <alias>, see gea boards list; with one registered board it can be left out):')}
240
260
  gea build --board <alias> [--app <id>] build firmware (ESP-IDF / Pico SDK / geaos) [--verbose] [--output file.bin]
package/src/manifest.mjs CHANGED
@@ -148,7 +148,7 @@ export function assertTargetEnabled(ctx, app, targetOrPlatform) {
148
148
  fail(`App '${app.id}' does not enable target '${platform}'.`, ExitCode.targetUnavailable)
149
149
  }
150
150
 
151
- export const knownPlatforms = Object.freeze(['web', 'esp32', 'rp2350', 'geaos', 'macos', 'ios', 'android', 'windows', 'xbox'])
151
+ export const knownPlatforms = Object.freeze(['web', 'esp32', 'rp2350', 'geaos', 'macos', 'ios', 'android', 'windows', 'xbox', 'pebble'])
152
152
 
153
153
  export function appPlatformForTarget(ctx, targetOrBoard) {
154
154
  return appPlatformsForTarget(ctx, targetOrBoard)[0] || ''
@@ -0,0 +1,41 @@
1
+ import path from 'node:path'
2
+ import { spawnSync } from 'node:child_process'
3
+ import { existsSync } from 'node:fs'
4
+ import { createRequire } from 'node:module'
5
+
6
+ import { CliError, ExitCode, fail } from '../errors.mjs'
7
+ import { formatCommand } from '../run.mjs'
8
+
9
+ export function pebbleBuildArgs(script, { app, phone = '', run = false }) {
10
+ const args = [script, app.root, '--entry', app.entry || 'index.tsx']
11
+ if (run) args.push('--install', phone || 'emulator')
12
+ return args
13
+ }
14
+
15
+ // Pebble is a platform, not a board: a Gea app becomes an ordinary .pbw that
16
+ // installs next to every other Pebble app, with the watch firmware untouched.
17
+ // Like macOS and iOS, the whole target is one script shipped inside a package
18
+ // the app depends on (@geastack/pebble), found through the app's own module
19
+ // resolution. `gea build --target pebble` produces the .pbw; `gea run --target
20
+ // pebble` also installs it -- on the emery emulator, or on a watch through the
21
+ // Pebble phone app's developer connection when `--phone <ip>` names one.
22
+ export function runPebble({ app, env, dryRun = false, stdout, phone = '', run = false }) {
23
+ const require = createRequire(path.join(app.root, 'package.json'))
24
+ let pebbleRoot = ''
25
+ try {
26
+ pebbleRoot = path.dirname(require.resolve('@geastack/pebble/package.json'))
27
+ } catch {
28
+ fail(`'${app.id}' targets Pebble but @geastack/pebble is not installed in ${app.root} — run npm install there.`, ExitCode.missingDependency)
29
+ }
30
+ const script = path.join(pebbleRoot, 'targets', 'pebble', 'build-pebble.sh')
31
+ if (!existsSync(script)) fail(`Pebble build script not found: ${script}`, ExitCode.missingDependency)
32
+ const args = pebbleBuildArgs(script, { app, phone, run })
33
+ if (dryRun) {
34
+ stdout(formatCommand(['bash', ...args]))
35
+ return 0
36
+ }
37
+ const result = spawnSync('bash', args, { cwd: app.root, env, stdio: 'inherit' })
38
+ if (result.error) throw result.error
39
+ if (result.status !== 0) throw new CliError(`Pebble build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
40
+ return 0
41
+ }
@@ -10,29 +10,9 @@ import { appSummary, discoverApps } from '../manifest.mjs'
10
10
  import { formatCommand } from '../run.mjs'
11
11
  import { onPath } from '../toolchain.mjs'
12
12
 
13
- // `web` is two targets wearing one name, and the CLI keeps them apart.
14
- //
15
- // gea simulate the SIMULATOR. The app's C++ is generated with the
16
- // same geatsc flags an ESP32 firmware uses -- same
17
- // board profile, same font DPR, same renderer -- and
18
- // only the final compile differs (emcc/WASM + an
19
- // RGB565 framebuffer on a canvas, instead of clang +
20
- // a QSPI panel). Gea's own layout engine does layout,
21
- // so what you see is what the board will show.
22
- //
23
- // gea {dev,build} --target web
24
- // a REAL WEB APP. The same TSX compiled onto the
25
- // @geajs/core reactive DOM runtime: real DOM nodes,
26
- // the browser's own CSSOM, native HMR. Faster to
27
- // iterate on, and deployable -- but the *browser*
28
- // does layout, so it drifts from the device exactly
29
- // where a simulator would need to be trusted.
30
- //
31
- // Both live in @geastack/simulator. Unlike the Apple targets -- where the app
32
- // depends on @geastack/apple and the app's own resolution finds the script --
33
- // nothing here is declared by the app: a gea app is simulatable because it is
34
- // buildable, so the CLI owns the dependency and resolves it from its own
35
- // installation.
13
+ // Web development and the default emulator use Gea's DOM/CSS runtime.
14
+ // `gea simulate --renderer wasm` retains the embedded renderer compiled with
15
+ // Emscripten for framebuffer/device-rendering comparisons.
36
16
 
37
17
  const require = createRequire(import.meta.url)
38
18
 
@@ -150,7 +130,8 @@ export function buildSimulatorApp({ app, env, dryRun = false, stdout }) {
150
130
  return { simulatorDir, paths }
151
131
  }
152
132
 
153
- export async function runSimulate({ ctx, app, env, dryRun = false, stdout, port, open = true, view = {} }) {
133
+ export async function runSimulate({ ctx, app, env, dryRun = false, stdout, port, open = true, view = {}, renderer = 'dom' }) {
134
+ if (renderer === 'dom') return runWebDev({ app, env, dryRun, stdout, port, emulator: true, open, view })
154
135
  const { simulatorDir, paths } = buildSimulatorApp({ app, env, dryRun, stdout })
155
136
  const url = await startSimulatorServer({ ctx, app, env, simulatorDir, paths, port, dryRun, stdout, view })
156
137
  if (dryRun) return 0
@@ -235,13 +216,22 @@ function openBrowser(url, env) {
235
216
  // The DOM target resolves the app from the directory itself rather than from an
236
217
  // id looked up under an apps root, so `gea dev --target web` works in any app
237
218
  // folder on disk.
238
- export function runWebDev({ app, env, dryRun = false, stdout, port }) {
219
+ export function runWebDev({ app, env, dryRun = false, stdout, port, emulator = false, open = false, view = {} }) {
239
220
  requireWebTarget(app)
240
221
  const simulatorDir = resolveSimulatorDir(env)
241
222
  const script = path.join(simulatorDir, 'targets', 'web', 'dev-web.mjs')
242
223
  if (!existsSync(script)) fail(`Web dev server not found: ${script}`, ExitCode.missingDependency)
243
224
  const args = [script, '--app-dir', app.root]
244
225
  if (port) args.push('--port', String(port))
226
+ if (emulator) args.push('--emulator')
227
+ if (open) args.push('--open')
228
+ for (const key of ['width', 'height', 'dpr', 'zoom']) {
229
+ if (view[key] !== undefined && view[key] !== '') {
230
+ const value = Number(view[key])
231
+ if (!Number.isFinite(value) || value <= 0) fail(`--${key} must be a positive number.`, ExitCode.usage)
232
+ args.push(`--${key}`, String(value))
233
+ }
234
+ }
245
235
  return runScript('node', args, {
246
236
  cwd: app.root,
247
237
  env,
@@ -8,7 +8,7 @@
8
8
  "check": "tsc --noEmit"
9
9
  },
10
10
  "dependencies": {
11
- "@geajs/core": "1.4.2"
11
+ "@geajs/core": "1.4.3"
12
12
  },
13
13
  "devDependencies": {
14
14
  "typescript": "latest"