@geastack/cli 0.1.84 → 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
@@ -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.84",
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": {
package/src/gea.mjs CHANGED
@@ -113,6 +113,18 @@ 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
+ // 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
+ }
116
128
  // DOM is the default web development and emulator runtime. The embedded
117
129
  // framebuffer simulator remains available through simulate --renderer wasm.
118
130
  if ((command === 'dev' || command === 'build') && (target === 'web' || (!target && command === 'dev'))) {
@@ -236,11 +248,13 @@ ${heading('Run on this machine (no board needed):')}
236
248
  gea dev [app] [--port N] real DOM + CSS dev server with HMR (same as --target web)
237
249
  gea build --target web [app] [--out-dir d] build the app as a real web app
238
250
 
239
- ${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):')}
240
252
  gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
241
253
  gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
242
254
  gea run --target ios [app] [--mode simulator|device] build, then install and launch on a simulator or iPhone
243
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
244
258
 
245
259
  ${heading('Build and deploy (device commands take --board <alias>, see gea boards list; with one registered board it can be left out):')}
246
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
+ }