@geastack/cli 0.1.116 → 0.1.117

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
@@ -18,41 +18,43 @@ gea dev
18
18
  gea build --target web
19
19
  gea build --target ios
20
20
  gea build --target tvos
21
- gea flash --board amoled --monitor
22
- gea screenshot board.png --board amoled
23
- gea monitor --board amoled
24
- gea inspect --json
21
+ gea flash --board <alias> --monitor
22
+ gea screenshot board.png --board <alias>
23
+ gea monitor --board <alias>
24
+ gea apps inspect --json
25
25
  ```
26
26
 
27
+ The CLI needs Node.js 22 or later. `gea --help` prints the full command
28
+ surface; `gea apps inspect --json` runs inside an app directory.
29
+
27
30
  ## Interactive Menu Map
28
31
 
29
32
  ```mermaid
30
33
  flowchart TD
31
34
  create["gea create my-app"] --> identity["Resolve app identity<br/>argument, optional --id, optional --name"]
32
- identity --> starter{"Starter app?"}
33
-
34
- starter -->|"Embedded component counter"| counter["Copy the touchscreen counter used in the embedded tutorial"]
35
+ identity --> starter{"What do you want to build?"}
35
36
 
36
- starter -->|"Blank application"| emptyTarget{"Where should it run?"}
37
+ starter -->|"Blank application"| emptyTarget{"Where should this application run?"}
37
38
  emptyTarget -->|"Web browser"| emptyWeb["Generate browser entry, HTML, and Vite config"]
38
- emptyTarget -->|"ESP32 board"| emptyEsp["Generate native entry<br/>Ask whether to enable Bluetooth updates"]
39
- emptyTarget -->|"Other native target"| emptyNative["Generate native entry for the selected platform"]
39
+ emptyTarget -->|"ESP32 board"| emptyEsp["Generate native entry<br/>Ask whether to enable wireless firmware updates over Bluetooth"]
40
+ emptyTarget -->|"RP2350, GeaOS, macOS, iOS, tvOS, Android, or Windows"| emptyNative["Generate native entry for the selected platform"]
40
41
 
41
- starter -->|"Example application"| pickExample["Pick from the example gallery<br/>web, ESP32, GeaOS, iOS, tvOS, macOS, Android"]
42
- pickExample --> fetchExample["Fetch selected app from GitHub"]
43
- fetchExample --> copyExample["Copy fetched example files"]
44
- copyExample --> rewriteExample["Rewrite package name and gea manifest"]
42
+ starter -->|"Example application"| pickExample["Pick from the example gallery<br/>bundled Component Counter first, then GitHub examples<br/>for web, ESP32, RP2350, GeaOS, iOS, macOS, Android, and Windows"]
43
+ pickExample -->|"Component Counter"| counter["Copy the bundled touchscreen counter used in the embedded tutorial"]
44
+ pickExample -->|"GitHub example"| fetchExample["Fetch selected app from GitHub"]
45
+ fetchExample --> rewriteExample["Rewrite package name and gea manifest"]
45
46
 
46
- counter --> projectWiring["Add @geastack/core and @geastack/cli"]
47
- rewriteExample --> projectWiring["Add @geastack/core and @geastack/cli"]
47
+ counter --> projectWiring["Add @geastack/core, @geastack/cli, @geajs/core, TypeScript<br/>+ @geastack/targets for ESP32/RP2350, @geastack/apple for macOS/iOS/tvOS,<br/>@geastack/windows for Windows, Vite for web"]
48
+ rewriteExample --> projectWiring
48
49
  emptyWeb --> projectWiring
49
50
  emptyEsp --> projectWiring
50
51
  emptyNative --> projectWiring
51
52
  projectWiring --> boardConfig["Create .gea/boards.json"]
52
- boardConfig --> install["Install npm dependencies<br/>(interactive default)"]
53
+ boardConfig --> install["Install npm dependencies<br/>(interactive default; --no-install skips)"]
53
54
  install --> setup["Next: npx gea setup"]
54
55
 
55
56
  auto["Automation flags"] -.-> starter
57
+ auto --> autoCounter["--yes or no terminal: Component Counter"]
56
58
  auto --> autoEmpty["--starter blank --yes"]
57
59
  auto --> autoExample["--starter example --example watch"]
58
60
  ```
@@ -61,33 +63,33 @@ flowchart TD
61
63
  flowchart TD
62
64
  setup["npx gea setup"] --> mode{"Mode?"}
63
65
 
64
- mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.2"]
65
- mode -->|"--board alias"| directBoard["Run target setup for board alias"]
66
- mode -->|"--target target-id"| directTarget["Run target setup directly"]
66
+ mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.2<br/>(--idf-version installs another release)<br/>plus the 6.2-dev line the ESP32-S31 builds with"]
67
+ mode -->|"--board alias"| directBoard["Configure the build for that board alias"]
68
+ mode -->|"--target target-id"| directTarget["Configure the build for that target directly"]
67
69
 
68
70
  mode -->|"Interactive"| interactive{"What do you want to set up?"}
69
71
 
70
- interactive -->|"Known supported board"| knownBoard["Pick board"]
71
- knownBoard --> alias["Set board alias"]
72
- alias --> serial["Detect serial devices"]
73
- serial --> saveSerial["Detect the USB serial (registry + GEADEV ping)"]
74
- saveSerial --> ota["Optional OTA host"]
75
- ota --> reviewKnown["Review board setup"]
76
- reviewKnown --> writeKnown["Write .gea/boards.json"]
77
-
78
- interactive -->|"Custom board target"| custom["Choose MCU and compatible chips"]
79
- custom --> chipConfig["Ask interface and pin questions<br/>from @geastack/chips/catalog.json"]
80
- chipConfig --> features["Optional microSD and launcher button"]
81
- features --> connection["Detect initial USB connection"]
82
- connection --> reviewCustom["Review native composition"]
83
- reviewCustom --> writeProfile["Write .gea/targets/alias.json"]
84
- writeProfile --> writeCustomAlias["Write alias to .gea/boards.json"]
85
-
86
- interactive -->|"npm dependencies only"| npmInstall["Run npm install when package.json exists"]
87
- interactive -->|"ESP-IDF toolchain only"| idfOnly["Install or check ESP-IDF v6.0.2"]
88
-
89
- writeKnown --> initialize["Initialize board target"]
90
- writeCustomAlias --> initialize
72
+ interactive -->|"Known supported board"| knownBoard["Which board do you have?"]
73
+ knownBoard --> alias["Board alias"]
74
+ alias --> serial["Is the board connected over USB right now?<br/>detect its USB serial (registry + GEADEV ping)"]
75
+ serial --> ota["OTA host/IP (optional)"]
76
+ ota --> reviewKnown["Review, then: Save this board setup?"]
77
+ reviewKnown --> writeKnown["Write the alias to boards.json"]
78
+
79
+ interactive -->|"Custom board profile"| custom["Custom board alias, then MCU / SoC (ESP32-S3)"]
80
+ custom --> chipConfig["Display, touch, power, IMU, audio and I/O expander<br/>with bus and pin questions from @geastack/chips/catalog.json"]
81
+ chipConfig --> features["Optional microSD slot and launcher button"]
82
+ features --> connection["Detect the USB serial"]
83
+ connection --> reviewCustom["Review, then: Save this custom board target?"]
84
+ reviewCustom --> writeProfile["Write targets/alias.json next to boards.json"]
85
+ writeProfile --> writeCustomAlias["Write the alias to boards.json"]
86
+
87
+ interactive -->|"Only install/check project npm dependencies"| npmInstall["Run npm install when package.json exists"]
88
+ interactive -->|"Only install/check ESP-IDF toolchain"| idfOnly["Same as --esp-idf"]
89
+
90
+ writeKnown --> idfCheck["Check ESP-IDF for the board, offer to install it"]
91
+ writeCustomAlias --> idfCheck
92
+ idfCheck --> initialize["Initialize board target for an app"]
91
93
  initialize --> ready["Ready: npx gea flash --board alias --monitor"]
92
94
  npmInstall --> done
93
95
  idfOnly --> done
@@ -96,6 +98,12 @@ flowchart TD
96
98
  directTarget --> done
97
99
  ```
98
100
 
101
+ The wizard writes `boards.json` (and a custom board's `targets/<alias>.json`)
102
+ to `<project>/.gea/` when the project already has a `.gea/boards.json`, which
103
+ every `gea create` project does, and to `~/.geastack/` otherwise. `--local`
104
+ forces the project directory, `--global` forces `~/.geastack/`, and
105
+ `--boards-config <file>` names the file outright.
106
+
99
107
  The CLI resolves `@geastack/core`, `@geastack/targets`, the compiler, chips,
100
108
  host bindings, and the other native packages from npm. A project can use a
101
109
  local CLI with `npx gea` or a global installation with `gea`; neither command
@@ -108,9 +116,9 @@ Boards are managed without editing JSON by hand; aliases live in
108
116
  ```sh
109
117
  gea boards discover # which registered board is on which USB port, its app and IP
110
118
  gea boards list
111
- gea boards set amoled host 192.168.1.100
112
- gea boards rename amoled desk-amoled
113
- gea boards remove desk-amoled
119
+ gea boards set <alias> host 192.168.1.100
120
+ gea boards rename <alias> <new-alias>
121
+ gea boards remove <new-alias>
114
122
  ```
115
123
 
116
124
  Custom boards remain editable after setup:
@@ -122,7 +130,8 @@ gea chips add co5300 ft3168 --board my-board
122
130
  gea chips remove ft3168 --board my-board
123
131
  ```
124
132
 
125
- These commands update the app-local target definition. They do not copy native
133
+ These commands update the custom board's target definition
134
+ (`targets/<alias>.json`). They do not copy native
126
135
  sources into the application; the target adapter compiles the selected drivers
127
136
  directly from the installed `@geastack/chips` package.
128
137
 
@@ -146,9 +155,13 @@ Run from this repo during local development:
146
155
  ```sh
147
156
  node bin/gea.mjs doctor
148
157
  node bin/gea.mjs --help
149
- node bin/create-geastack.mjs demo-panel --dir ./demo-panel --dry-run
150
158
  ```
151
159
 
160
+ `GEA_DEBUGGER_DIR` points `gea run --debug` at a debugger checkout instead of
161
+ the installed `@geastack/debugger`. Contributor native debug launches use the
162
+ sibling `apple` and `core` checkouts and the shared compiler; explicit
163
+ overrides win.
164
+
152
165
  ## Machine Setup
153
166
 
154
167
  Use [docs/SETUP.md](docs/SETUP.md) for Node/npm, ESP-IDF, Emscripten, Xcode,
@@ -176,34 +189,37 @@ expose stable command contracts.
176
189
 
177
190
  - [docs/PEBBLE-QUICKSTART.md](docs/PEBBLE-QUICKSTART.md): install the Pebble SDK,
178
191
  enable a TSX app, build a `.pbw`, and run on Pebble Time 2 or its emulator.
179
-
180
192
  - [docs/SPEC.md](docs/SPEC.md): command surface, manifest expectations, and
181
193
  backend contract for the first implementation.
182
194
  - [docs/SETUP.md](docs/SETUP.md): toolchains per target, the ESP-IDF version
183
195
  GeaStack resolves, and the board configuration files.
184
196
  - [docs/DEVICE-CONTROL.md](docs/DEVICE-CONTROL.md): `gea devctl` in full, both
185
197
  wire protocols, and the display knobs.
186
-
187
- ## Current Status
188
-
189
- First implementation is in place:
190
-
191
- - `doctor` for local toolchain checks;
192
- - npm-resolved embedded board builds for ESP32 and RP2350;
193
- - `flash`, `monitor`, WiFi OTA, and BLE OTA through `@geastack/targets`;
194
- - `list` and `inspect` helpers;
195
- - `create-geastack` with a bundled counter starter, a blank application, and a
196
- GitHub-backed rich example flow for web, embedded, GeaOS, iOS, tvOS, macOS, and Android apps,
197
- all with `.gea/boards.json`, plus `gea boards` for machine-wide aliases in
198
- `~/.geastack/boards.json`.
199
-
200
- ## License
201
-
202
- Apache-2.0 (see `LICENSE`). You can ship closed-source products
203
- built on it. The only GeaStack code under a different license is
204
- the embedded board support (`targets` and `@geastack/chips`, GPL-3.0-only):
205
- shipping closed-source firmware through those needs a commercial license.
206
- Contact [contact@geastack.com](mailto:contact@geastack.com) for commercial terms, support and hosted builds.
198
+ - [docs/NATIVE-BUILD-CONFIG.md](docs/NATIVE-BUILD-CONFIG.md): native build
199
+ settings, their precedence, and board overrides.
200
+ - [docs/LINUX-NATIVE-DEPLOYMENT.md](docs/LINUX-NATIVE-DEPLOYMENT.md): register
201
+ and deploy to a Raspberry Pi OS board over SSH.
202
+ - [docs/qspi-panels.md](docs/qspi-panels.md): panel startup settings for custom
203
+ boards with a `co5300` or `sh8601` QSPI display.
204
+
205
+ ## Command Surface
206
+
207
+ - `gea create`, `gea setup`, `gea doctor`: scaffolding, guided board and
208
+ toolchain setup, and dependency checks.
209
+ - `gea dev`, `gea simulate`, `gea build --target web`: browser development,
210
+ device-viewport emulation, and static web builds.
211
+ - `gea build|run --target macos|ios|tvos|windows|raspberry-pi-os|pebble`:
212
+ native desktop, mobile, TV, and watch apps through `@geastack/apple`,
213
+ `@geastack/windows`, `@geastack/linux`, and `@geastack/pebble`.
214
+ - `gea build|flash|run|ota|clean --board <alias>`: ESP32 and RP2350 firmware
215
+ through `@geastack/targets`, with USB flashing, WiFi and BLE OTA, and OTA
216
+ slot management.
217
+ - `gea logs`, `gea monitor`, `gea screenshot`, `gea devctl`: device access over
218
+ USB or WiFi.
219
+ - `gea run --debug`: Chrome DevTools for native macOS apps and ESP32 boards.
220
+ - `gea apps`, `gea boards`, `gea targets`, `gea chips`, `gea config`,
221
+ `gea heap-report`: app, board, target, and chip catalogs, effective build
222
+ settings, and heap analysis.
207
223
 
208
224
  ## Browser development and emulation
209
225
 
@@ -213,9 +229,9 @@ opens the browser. Use `--no-open` to suppress opening, and `--width`, `--height
213
229
  `--zoom`, and `--dpr` to configure the preview. DPR is a simulated Display API
214
230
  value; it does not override the browser's pixel ratio.
215
231
 
216
- The default for `simulate` changed from WASM to DOM. To retain the embedded
217
- renderer and framebuffer workflow, use `gea simulate --renderer wasm`; this
218
- explicit mode still requires Emscripten. Unknown renderer values are rejected.
232
+ `gea simulate` uses the DOM renderer by default. For the embedded renderer and
233
+ framebuffer workflow, use `gea simulate --renderer wasm`; that mode requires
234
+ Emscripten. Unknown renderer values are rejected.
219
235
 
220
236
  `gea build --target web` emits HTML/JS/CSS into `.gea/build/web/site` (override
221
237
  with `--out-dir`). The app's `index.html` is honored. Web-only Vite customization
@@ -239,7 +255,7 @@ target is not required for debugging; the source manifest is unchanged. On Mac,
239
255
  `gea run --debug --target web` uses the existing DOM/CSS runtime with Vite HMR.
240
256
 
241
257
  `gea build --debug --target macos` produces the same instrumented native app
242
- without launching it or opening Chrome. `gea build --debug --board amoled`
258
+ without launching it or opening Chrome. `gea build --debug --board <alias>`
243
259
  builds ESP32 debug firmware without flashing or opening USB. Both commands use
244
260
  the same debug configuration as `run`, including editable CSS. macOS retains
245
261
  full symbols and unoptimized code by default; `--no-debug-sources` disables
@@ -258,19 +274,15 @@ Use `--debug-port 9223` for CDP and `--port 5182` for the DOM server. Native
258
274
  or browser stops the session. Other native targets, WASM and
259
275
  direct AppKit widget graphs outside the Gea retained tree remain unsupported.
260
276
 
261
- The CLI installs `@geastack/debugger` automatically. Debugging requires Node.js
262
- 22 or later and Chrome/Chromium. Native builds need matching compiler and target
263
- runtimes with debugger instrumentation; this release ships the host adapter and
264
- CLI integration. `GEA_DEBUGGER_DIR` selects a development checkout;
265
- contributor native launches use sibling Apple,
266
- core/plugin packages and the shared compiler; explicit overrides win. Set
267
- `GEA_CHROME_PATH` for a custom browser. Chrome uses its own app profile inside
277
+ The CLI installs `@geastack/debugger` automatically. Debugging requires
278
+ Chrome/Chromium, and native builds need compiler and target runtimes with
279
+ debugger instrumentation. Set `GEA_CHROME_PATH` for a custom browser. Chrome uses its own app profile inside
268
280
  `.gea/build/web`.
269
281
 
270
282
 
271
- From your app directory, `gea run --debug --board amoled --debug-fps 10` builds and flashes debug
272
- firmware on the registered AMOLED 2.06, then opens Chrome DevTools through USB.
273
- Other ESP32 aliases use the same adapter. `--attach` connects to already-running
283
+ From your app directory, `gea run --debug --board <alias> --debug-fps 10` builds
284
+ and flashes debug firmware on a registered ESP32 board, then opens Chrome
285
+ DevTools through USB. `--attach` connects to already-running
274
286
  debug firmware without flashing; regular firmware is rejected before JTAG or
275
287
  Chrome starts. `--no-open` exposes only the CDP endpoint.
276
288
  `--port` selects the USB device when using `--board`, while `--debug-port` selects
@@ -312,3 +324,11 @@ debugger exits. `--overrides edits.json` replays them as soon as it attaches:
312
324
  ```sh
313
325
  gea run --debug --target macos --overrides edits.json --save-overrides edits.json
314
326
  ```
327
+
328
+ ## License
329
+
330
+ Apache-2.0 (see `LICENSE`). You can ship closed-source products
331
+ built on it. The only GeaStack code under a different license is
332
+ the embedded board support (`targets` and `@geastack/chips`, GPL-3.0-only):
333
+ shipping closed-source firmware through those needs a commercial license.
334
+ Contact [contact@geastack.com](mailto:contact@geastack.com) for commercial terms, support and hosted builds.
@@ -14,7 +14,7 @@ You should only need four moves:
14
14
  Install:
15
15
 
16
16
  - Git
17
- - Node.js 20.19 or newer
17
+ - Node.js 22 or newer
18
18
  - npm
19
19
  - Python 3
20
20
 
@@ -1,6 +1,6 @@
1
1
  # Pebble Time 2 quickstart
2
2
 
3
- Requires Gea CLI 0.1.85 or newer, Node.js 20.19 or newer, Bash, and the Pebble
3
+ Requires Gea CLI 0.1.85 or newer, Node.js 22 or newer, Bash, and the Pebble
4
4
  SDK. This target builds ordinary `.pbw` apps for Pebble Time 2 (`emery`);
5
5
  it does not flash watch firmware. The build script supports macOS and Linux.
6
6
 
package/docs/SETUP.md CHANGED
@@ -21,14 +21,14 @@ npx gea setup
21
21
 
22
22
  For simulator-only development:
23
23
 
24
- - Node.js 20.19 or newer.
24
+ - Node.js 22 or newer.
25
25
  - npm.
26
26
  - Emscripten SDK if you want `npx gea build --target web` and the WASM simulator
27
27
  bundle path.
28
28
 
29
29
  For ESP32 hardware:
30
30
 
31
- - Node.js 20.19 or newer.
31
+ - Node.js 22 or newer.
32
32
  - npm.
33
33
  - Python 3.
34
34
  - ESP-IDF v6.0.2 (GeaStack's pinned default; see ESP-IDF For ESP32 Targets below).
@@ -54,7 +54,7 @@ For Android targets:
54
54
  ## Node And npm
55
55
 
56
56
  Install Node.js from the official download page or your normal version manager.
57
- GeaStack currently requires Node.js 20.19 or newer. Node 24 LTS is a good
57
+ GeaStack currently requires Node.js 22 or newer. Node 24 LTS is a good
58
58
  default on new machines.
59
59
 
60
60
  Verify:
@@ -66,21 +66,15 @@ npm --version
66
66
 
67
67
  ## ESP-IDF For ESP32 Targets
68
68
 
69
- The embedded board scripts target ESP-IDF v6.0.2 by default. GeaStack resolves
70
- the version it installs or verifies dynamically, in this order:
69
+ ESP32 builds use ESP-IDF v6.0.2, and `gea setup` installs or verifies that
70
+ release. To install another one instead:
71
71
 
72
72
  1. `--idf-version <tag>` (e.g. `npx gea setup --esp-idf --idf-version v6.1.0-rc1`)
73
- to pin an exact release or try a release candidate.
74
- 2. `GEA_ESP_IDF_VERSION` (same shape) when no `--idf-version` is given.
75
- 3. The latest stable ESP-IDF release on GitHub, when it can be determined
76
- (release candidates and betas are ignored).
77
- 4. The pinned default, v6.0.2, when nothing above applies (offline, GitHub
78
- unreachable, etc).
79
-
80
- Verifying an existing install accepts any installed version whose
81
- major.minor is the same as or newer than the resolved target -- an installed
82
- 6.0.2 is never rejected just because the resolved target moved on to, say,
83
- 6.1.0, unless it genuinely trails it.
73
+ names an exact release, a release candidate or a branch.
74
+ 2. `GEA_ESP_IDF_VERSION` (same shape) applies when no `--idf-version` is given.
75
+
76
+ Builds pick the v6.0.2 install on their own. To build with any other ESP-IDF,
77
+ point `IDF_PATH` at it.
84
78
 
85
79
  Command-line install:
86
80
 
@@ -152,21 +152,6 @@
152
152
  "ios": false
153
153
  }
154
154
  },
155
- {
156
- "id": "car-dashboard",
157
- "name": "Car Dashboard",
158
- "description": "1280x720 cluster",
159
- "path": "apps/car-dashboard",
160
- "entry": "index.tsx",
161
- "runtime": "gea",
162
- "targets": {
163
- "web": true,
164
- "esp32": true,
165
- "geaos": true,
166
- "macos": false,
167
- "ios": false
168
- }
169
- },
170
155
  {
171
156
  "id": "counter-jsx",
172
157
  "name": "Counter",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.116",
3
+ "version": "0.1.117",
4
4
  "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -38,7 +38,7 @@
38
38
  "dependencies": {
39
39
  "@clack/prompts": "^1.8.0",
40
40
  "@geastack/simulator": "^0.1.15",
41
- "@geastack/targets": "^0.1.113",
41
+ "@geastack/targets": "^0.1.114",
42
42
  "picocolors": "^1.1.1",
43
43
  "serialport": "^13.0.0"
44
44
  },
@@ -128,7 +128,7 @@ export function validateBuildManifest(manifest) {
128
128
  if (!isObject(target.boards)) fail(where + '.boards must be an object')
129
129
  for (const [id, board] of Object.entries(target.boards)) {
130
130
  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(id) || !isObject(board)) fail(where + '.boards must contain board IDs mapped to objects')
131
- for (const key of Object.keys(board)) if (!['build', 'cssDevicePixelRatio', 'defines', 'buttons'].includes(key)) fail(`Unknown setting ${where}.boards.${id}.${key}`)
131
+ for (const key of Object.keys(board)) if (!['build', 'cssDevicePixelRatio', 'defines', 'buttons', 'psram', 'flashFreq', 'display', 'sdkconfig'].includes(key)) fail(`Unknown setting ${where}.boards.${id}.${key}`)
132
132
  boardDefines(board.defines, where + '.boards.' + id + '.defines')
133
133
  flatten(board.build, where + '.boards.' + id + '.build')
134
134
  if (board.cssDevicePixelRatio !== undefined) ratio(board.cssDevicePixelRatio, where + '.boards.' + id + '.cssDevicePixelRatio')
@@ -165,6 +165,7 @@ export function targetsCommand(ctx, parsed, rest, options) {
165
165
  fail(error.message, ExitCode.missingDependency)
166
166
  }
167
167
  if (sub === 'list') {
168
+ if (Object.keys(targets).length === 0 && !flag(parsed, 'json')) fail(`No targets found: @geastack/targets is not installed in ${ctx.projectRoot}. Run this inside a GeaStack project after npm install.`, ExitCode.missingDependency)
168
169
  if (flag(parsed, 'json')) options.stdout(JSON.stringify(targets, null, 2))
169
170
  else for (const id of Object.keys(targets).sort()) options.stdout(`${id}\t${targets[id].adapter}\t${exists(targets[id].targetDir) ? targets[id].targetDir : '(not installed)'}`)
170
171
  return 0
@@ -324,6 +324,7 @@ export async function flashCommand(ctx, parsed, rest, options, { monitor = false
324
324
  export async function otaCommand(ctx, parsed, rest, options) {
325
325
  const transport = option(parsed, 'transport', '') || defaultOtaTransport(ctx, parsed, rest)
326
326
  if (transport !== 'wifi' && transport !== 'ble') fail("--transport must be 'wifi' or 'ble'.", ExitCode.usage)
327
+ if (transport === 'wifi' && option(parsed, 'port', '')) fail('--port names a USB serial port; a Wi-Fi OTA takes the board address with --host.', ExitCode.usage)
327
328
  const selection = selectBoard(ctx, parsed, transport === 'wifi' ? { otaHost: true } : {})
328
329
  if (selection.bootMode === 'ram-only') {
329
330
  if (transport !== 'wifi' || option(parsed, 'slot') || option(parsed, 'erase-slot') ||
@@ -5,6 +5,7 @@ import { boardConfigPath, boardConfigTiers, loadBoardConfig } from '../boards/co
5
5
  import { loadSerialport } from '../device/serial.mjs'
6
6
  import { ExitCode } from '../errors.mjs'
7
7
  import { findEspIdf, findIdfPythonEnv } from '../esp32/idf-env.mjs'
8
+ import { DEFAULT_ESP_IDF_VERSION } from '../esp32/idf-version.mjs'
8
9
  import { exists } from '../fs-utils.mjs'
9
10
  import { discoverApps, resolveRequestedApp, validateApp } from '../manifest.mjs'
10
11
  import { commandVersion, nodeAtLeast, onPath } from '../toolchain.mjs'
@@ -29,7 +30,7 @@ export async function doctorCommand(ctx, parsed, rest, options) {
29
30
  const add = (name, ok, detail, required) => checks.push({ name, ok: Boolean(ok), detail: String(detail ?? ''), required })
30
31
 
31
32
  add('project root', exists(ctx.projectRoot), ctx.projectRoot, true)
32
- add('Node >= 20.19', nodeAtLeast(20, 19), process.version, true)
33
+ add('Node >= 22', nodeAtLeast(22, 0), process.version, true)
33
34
  add('@geastack/targets', packageExists(ctx.targetsRoot), ctx.targetsRoot || 'not installed in this project', true)
34
35
  add('@geastack/core', packageExists(ctx.corePackageDir), ctx.corePackageDir || 'not installed', true)
35
36
  add('@geastack/compiler', packageExists(ctx.compilerPackageDir), ctx.compilerPackageDir || 'not installed', true)
@@ -39,14 +40,16 @@ export async function doctorCommand(ctx, parsed, rest, options) {
39
40
  }
40
41
  add('serialport (USB device access)', await serialportAvailable(), 'npm package', false)
41
42
 
42
- const idfDir = findEspIdf(env)
43
+ // The install a build would pick: the pinned release, or whatever IDF_PATH names.
44
+ const idfDir = findEspIdf(env, undefined, { defaultVersion: DEFAULT_ESP_IDF_VERSION.slice(1) })
43
45
  const pythonEnv = idfDir ? findIdfPythonEnv(idfDir, env) : ''
44
- add('ESP-IDF', Boolean(idfDir), idfDir || 'not found (set IDF_PATH)', false)
46
+ add(`ESP-IDF ${DEFAULT_ESP_IDF_VERSION}`, Boolean(idfDir), idfDir || 'not found (gea setup --esp-idf, or set IDF_PATH)', false)
45
47
  add('ESP-IDF python env', Boolean(pythonEnv), pythonEnv || 'run install.sh in ESP-IDF', false)
46
48
  add('cmake', onPath('cmake', env) || Boolean(pythonEnv), commandVersion('cmake', ['--version'], env).split('\n')[0] || 'from ESP-IDF tools', false)
47
49
  add('ninja', onPath('ninja', env), onPath('ninja', env) ? 'on PATH' : 'optional; Unix Makefiles used otherwise', false)
48
50
  add('ccache', onPath('ccache', env), onPath('ccache', env) ? 'on PATH' : 'optional', false)
49
51
  add('arm-none-eabi-gcc (RP2350)', onPath('arm-none-eabi-gcc', env) || Boolean(env.PICO_TOOLCHAIN_PATH), env.PICO_TOOLCHAIN_PATH || 'optional', false)
52
+ add('PICO_SDK_PATH (RP2350)', Boolean(env.PICO_SDK_PATH) && exists(env.PICO_SDK_PATH), env.PICO_SDK_PATH || 'optional; needed for RP2350 builds', false)
50
53
  add('picotool (RP2350)', onPath('picotool', env), onPath('picotool', env) ? 'on PATH' : 'optional', false)
51
54
  add('swift (BLE OTA)', onPath('swift', env), onPath('swift', env) ? 'on PATH' : 'optional; macOS only', false)
52
55
  // gea simulate compiles the app with emcc and links with em++, and hashes
@@ -134,7 +134,9 @@ export async function runCreateGeastack(argv, io = {}) {
134
134
  ? `Example: fetched ${starter.example.name}`
135
135
  : 'Starter: blank application'
136
136
  ])
137
- done.outro(installDependencies ? `Next: cd ${targetDir} && npx gea setup` : `Next: cd ${targetDir} && npm install && npx gea setup`)
137
+ // `gea setup` is the board and toolchain wizard; a web-only app has nothing for it to do.
138
+ const firstCommand = isWebOnly(targets) ? 'npx gea dev' : 'npx gea setup'
139
+ done.outro(installDependencies ? `Next: cd ${targetDir} && ${firstCommand}` : `Next: cd ${targetDir} && npm install && ${firstCommand}`)
138
140
  return 0
139
141
  }
140
142
 
@@ -520,7 +522,10 @@ function readme({ appId, displayName, starter, targets }) {
520
522
  : starter.kind === 'bundled'
521
523
  ? `Started from bundled starter: \`${starter.starter.name}\` (\`${starter.starter.id}\`).`
522
524
  : 'Started from a blank app.'
523
- const commands = targets.web
525
+ const commands = isWebOnly(targets)
526
+ ? `npx gea dev
527
+ npx gea build --target web`
528
+ : targets.web
524
529
  ? `npx gea setup
525
530
  npx gea dev
526
531
  npx gea build --target web`
@@ -554,6 +559,10 @@ ${commands}
554
559
  `
555
560
  }
556
561
 
562
+ function isWebOnly(targets) {
563
+ return targets.web === true && Object.entries(targets).every(([name, enabled]) => name === 'web' || enabled !== true)
564
+ }
565
+
557
566
  function shouldInstallDependencies(parsed, io) {
558
567
  const explicit = option(parsed, 'install')
559
568
  if (explicit !== undefined) return explicit === true || explicit === 'true'
@@ -365,7 +365,7 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
365
365
  // Flash and PSRAM share the MSPI core clock, so the flash clock must divide
366
366
  // the one PSRAM runs from: octal PSRAM at 120MHz needs a 240MHz core, which
367
367
  // 80MHz quad flash cannot share (ESP-IDF has no tuning table for it).
368
- const flashFreq = Number(app?.targetConfig?.esp32?.flashFreq) || Number(selection.flashFreq) || 0
368
+ const flashFreq = (app ? Number(appTargetConfig(app, 'esp32', selection.target).flashFreq) : 0) || Number(selection.flashFreq) || 0
369
369
  if (flashFreq) {
370
370
  for (const mhz of [20, 26, 40, 80, 120]) {
371
371
  if (mhz !== flashFreq) unset(`CONFIG_ESPTOOLPY_FLASHFREQ_${mhz}M`)
@@ -558,7 +558,7 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
558
558
  // gea.targets.esp32.sdkconfig: the app's own Kconfig defaults, layered over
559
559
  // the board's. IDF reads a ';'-separated SDKCONFIG_DEFAULTS list in order, so
560
560
  // the app's file is last and wins wherever the two disagree.
561
- const appEsp32Config = app ? appTargetConfig(app, 'esp32') : null
561
+ const appEsp32Config = app ? appTargetConfig(app, 'esp32', selection.target) : null
562
562
  const appSdkconfigFile = appEsp32Config?.sdkconfig ? path.join(app.root, appEsp32Config.sdkconfig) : ''
563
563
  // gea.targets.esp32.display: the RGB panel pipeline an app opts into.
564
564
  // copyBack: 'dma' the strip copy-back runs on GDMA, freeing the worker core;
@@ -1,17 +1,12 @@
1
1
  // ESP-IDF target-version resolution.
2
2
  //
3
- // One pinned default in code, an env var / CLI option that overrides it
4
- // outright (pin an older release or try a release candidate), and a
5
- // best-effort GitHub "latest release" lookup used only when nothing
6
- // overrides the pin. The network call is injected (`fetchImpl`/`fetchLatest`)
7
- // so real usage hits GitHub while tests supply a fake and never touch the
8
- // network.
3
+ // One pinned default in code, and an env var / CLI option that overrides it
4
+ // outright (pin another release or try a release candidate).
9
5
 
10
6
  const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/
11
7
  const VERSION_IN_TEXT = /v?(\d+)\.(\d+)\.(\d+)/i
12
8
 
13
- // The version GeaStack targets when nothing overrides it and the latest
14
- // release cannot be determined (offline, GitHub unreachable, rate limited).
9
+ // The version GeaStack targets when nothing overrides it.
15
10
  // Bump this alongside board-script updates.
16
11
  export const DEFAULT_ESP_IDF_VERSION = 'v6.0.2'
17
12
 
@@ -20,11 +15,8 @@ export function espIdfVersionForTarget(target) {
20
15
  return target === 'esp32-s31-espressif-mosaico' ? '6.2-dev' : DEFAULT_ESP_IDF_VERSION.slice(1)
21
16
  }
22
17
 
23
- const GITHUB_LATEST_RELEASE_URL = 'https://api.github.com/repos/espressif/esp-idf/releases/latest'
24
-
25
18
  // Parses a strict `vX.Y.Z` release tag. Returns null for anything else,
26
- // including release candidates and betas (`v6.1.0-rc1`), so callers can
27
- // filter those out of the "latest" lookup.
19
+ // including release candidates and betas (`v6.1.0-rc1`).
28
20
  export function parseStableIdfTag(value) {
29
21
  const match = STABLE_TAG.exec(String(value || '').trim())
30
22
  if (!match) return null
@@ -39,42 +31,27 @@ export function extractIdfVersionFromText(text) {
39
31
  return { majorMinor: `${match[1]}.${match[2]}`, full: `${match[1]}.${match[2]}.${match[3]}` }
40
32
  }
41
33
 
42
- // Best-effort lookup of the latest stable ESP-IDF release tag from GitHub.
43
- // Never throws: returns '' when the request fails, times out (~4s default),
44
- // the machine is offline, or the latest release is not a stable vX.Y.Z tag.
45
- // `fetchImpl` defaults to the global fetch; tests inject a fake instead of
46
- // touching the network.
47
- export async function fetchLatestEspIdfVersion({ fetchImpl = globalThis.fetch, timeoutMs = 4000, log = () => {} } = {}) {
48
- if (typeof fetchImpl !== 'function') return ''
49
- const controller = new AbortController()
50
- const timer = setTimeout(() => controller.abort(), timeoutMs)
51
- try {
52
- const response = await fetchImpl(GITHUB_LATEST_RELEASE_URL, {
53
- signal: controller.signal,
54
- headers: { Accept: 'application/vnd.github+json' }
55
- })
56
- if (!response?.ok) return ''
57
- const body = await response.json()
58
- return parseStableIdfTag(body?.tag_name)?.tag || ''
59
- } catch (error) {
60
- log(`Could not determine the latest ESP-IDF release (${error.message}); using ${DEFAULT_ESP_IDF_VERSION}.`)
61
- return ''
62
- } finally {
63
- clearTimeout(timer)
64
- }
65
- }
66
-
67
34
  // Resolves the ESP-IDF version tag to install/verify against, in order:
68
35
  // 1. `override` (--idf-version) or GEA_ESP_IDF_VERSION -- explicit pin or
69
36
  // a release candidate to test; used as-is (not required to be stable).
70
- // 2. the latest stable GitHub release, when `fetchLatest` can determine one.
71
- // 3. DEFAULT_ESP_IDF_VERSION.
72
- export async function resolveEspIdfVersion({ override, env = process.env, fetchLatest = fetchLatestEspIdfVersion, log = () => {} } = {}) {
37
+ // 2. DEFAULT_ESP_IDF_VERSION.
38
+ // Builds accept exactly the release espIdfVersionForTarget names, so setup
39
+ // installs that one: a newer stable release would install cleanly and then be
40
+ // refused by every build.
41
+ export async function resolveEspIdfVersion({ override, env = process.env } = {}) {
73
42
  const requested = override || env.GEA_ESP_IDF_VERSION
74
43
  // Only a bare version gains the tag's `v`; a branch (`master`) is cloned as named.
75
44
  if (requested) return /^\d/.test(requested) ? `v${requested}` : requested
76
- const latest = await fetchLatest({ log })
77
- return latest || DEFAULT_ESP_IDF_VERSION
45
+ return DEFAULT_ESP_IDF_VERSION
46
+ }
47
+
48
+ // True when an installed ESP-IDF satisfies the setup target. For the pinned
49
+ // default that means being that exact release, because builds look for exactly
50
+ // it: reporting a newer release as "found" leaves a machine no build accepts.
51
+ // A version the user asked for by name keeps the major.minor floor.
52
+ export function idfVersionSatisfiesTarget(installedVersion, targetTag) {
53
+ if (targetTag !== DEFAULT_ESP_IDF_VERSION) return idfVersionMeetsTarget(installedVersion, targetTag)
54
+ return installedVersion?.full === DEFAULT_ESP_IDF_VERSION.slice(1)
78
55
  }
79
56
 
80
57
  // True when an installed ESP-IDF's version.cmake-derived version satisfies
package/src/gea.mjs CHANGED
@@ -53,10 +53,8 @@ export async function runGea(argv, io = {}) {
53
53
 
54
54
  const ctx = createContext(parsed, env, cwd)
55
55
  const rest = parsed.positionals.slice(1)
56
- // probeSerialDevice lets tests answer `gea boards discover` without a port;
57
- // fetchEspIdfLatest likewise lets tests answer the setup wizard's ESP-IDF
58
- // "latest release" lookup without touching the network.
59
- const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice, fetchEspIdfLatest: io.fetchEspIdfLatest }
56
+ // probeSerialDevice lets tests answer `gea boards discover` without a port.
57
+ const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice }
60
58
 
61
59
  if (option(parsed, 'debug-fps') !== undefined && !flag(parsed, 'debug')) fail('--debug-fps requires --debug.', ExitCode.usage)
62
60
  if (flag(parsed, 'debug-sources') && !flag(parsed, 'debug')) fail('--debug-sources requires --debug with macOS or an ESP32-S3 board.', ExitCode.usage)
@@ -117,11 +115,12 @@ export async function runGea(argv, io = {}) {
117
115
  // selection for a bare `gea build`, so the command still reports which board
118
116
  // it needs rather than quietly producing a .app in place of firmware. For those
119
117
  // apps the Mac build is the documented `gea build --target macos`.
120
- if (command === 'build' && (target === 'macos' || (!target && !option(parsed, 'board')))) {
118
+ // `gea run` is the same selection followed by launching the built .app.
119
+ if ((command === 'build' || command === 'run') && (target === 'macos' || (!target && !option(parsed, 'board')))) {
121
120
  const app = parsed.options.app || rest[0] ? findAppById(ctx, String(parsed.options.app || rest[0])) : findCurrentApp(cwd)
122
121
  if (app?.targets?.macos && (target === 'macos' || (process.platform === 'darwin' && !declaresBoardTarget(app)))) {
123
122
  const { runMacos } = await import('./macos/adapter.mjs')
124
- return runMacos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout })
123
+ return runMacos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, run: command === 'run' })
125
124
  }
126
125
  if (target === 'macos') {
127
126
  fail(app ? `'${app.id}' does not declare gea.targets.macos.` : 'No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
@@ -301,6 +300,7 @@ ${heading('Run on this machine (no board needed):')}
301
300
  ${heading('Native desktop, mobile and watch apps (scripts ship in @geastack/apple, @geastack/windows and @geastack/pebble):')}
302
301
  gea build --target raspberry-pi-os [app] build an SDL Linux native executable (no launch)
303
302
  gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
303
+ gea run --target macos [app] build, then open the Mac .app
304
304
  gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
305
305
  gea build --target tvos [app] [--mode simulator|device] build the tvOS .app
306
306
  gea run --target tvos [app] [--mode simulator|device] install and launch on Apple TV or its simulator
@@ -13,19 +13,36 @@ import { formatCommand } from '../run.mjs'
13
13
  // @geastack/apple -- which an apple-native app already depends on -- so the
14
14
  // app's own module resolution is what finds it. An app declares `targets.macos`
15
15
  // and nothing else; the script reads the rest from the same manifest.
16
- export function runMacos({ app, env, dryRun = false, stdout }) {
16
+ export function runMacos({ app, env, dryRun = false, stdout, run = false }) {
17
17
  const { script, require } = appleTargetScript(app, 'macos', 'build-macos.sh', env)
18
18
  const childEnv = appleChildEnv(app, nativeScriptBuildEnv(app, 'macos', env, { dryRun }), require)
19
+ const bundle = macosAppBundle(app, env)
19
20
  if (dryRun) {
20
21
  stdout(formatCommand(['bash', script, app.id]))
22
+ if (run) stdout(formatCommand(['open', bundle]))
21
23
  return 0
22
24
  }
25
+ if (run && process.platform !== 'darwin') fail('gea run --target macos launches the app, which requires a Mac. Use gea build --target macos to build only.', ExitCode.usage)
23
26
  const result = spawnSync('bash', [script, app.id], { cwd: app.root, env: childEnv, stdio: 'inherit' })
24
27
  if (result.error) throw result.error
25
28
  if (result.status !== 0) throw new CliError(`macOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
29
+ if (!run) return 0
30
+ if (!existsSync(bundle)) fail(`Built app not found: ${bundle}`, ExitCode.buildFailed)
31
+ const launched = spawnSync('open', [bundle], { cwd: app.root, stdio: 'inherit' })
32
+ if (launched.error) throw launched.error
33
+ if (launched.status !== 0) throw new CliError(`Could not launch ${bundle} (${launched.status ?? 1}).`, ExitCode.deployFailed)
26
34
  return 0
27
35
  }
28
36
 
37
+ // Where build-macos.sh leaves the bundle: <output root>/<app id>/<name>.app,
38
+ // with the same GEA_MACOS_OUTPUT_DIR / GEA_MACOS_OUTPUT_TAG overrides the
39
+ // script reads.
40
+ export function macosAppBundle(app, env = process.env) {
41
+ const outputRoot = path.resolve(app.root, env.GEA_MACOS_OUTPUT_DIR || 'dist/macos')
42
+ const subpath = env.GEA_MACOS_OUTPUT_TAG ? path.join('.namespaces', env.GEA_MACOS_OUTPUT_TAG, app.id) : app.id
43
+ return path.join(outputRoot, subpath, `${app.name}.app`)
44
+ }
45
+
29
46
  // Both Apple targets ship as one script each inside @geastack/apple, and both
30
47
  // resolve it the same way: through the app's own dependencies. iOS reuses this
31
48
  // from src/ios/adapter.mjs rather than restating the resolution.
package/src/manifest.mjs CHANGED
@@ -214,8 +214,21 @@ export function appCmakeDefines(app) {
214
214
  return app.defines.join(';')
215
215
  }
216
216
 
217
- export function appTargetConfig(app, target) {
218
- return app.targetConfig[target] || emptyTargetConfig()
217
+ // A board's block (gea.targets.<target>.boards.<board-id>) may overrule the
218
+ // board settings an app picks for itself: psram and display merge over the
219
+ // target-wide value, a nonzero flashFreq replaces it, and a board's own
220
+ // `sdkconfig` file is used in place of the target-wide one.
221
+ export function appTargetConfig(app, target, boardId = '') {
222
+ const config = app.targetConfig?.[target] || emptyTargetConfig()
223
+ const board = boardId ? config.boardSettings?.[boardId] : null
224
+ if (!board) return config
225
+ return {
226
+ ...config,
227
+ psram: board.psram ? { ...config.psram, ...board.psram } : config.psram,
228
+ flashFreq: board.flashFreq || config.flashFreq,
229
+ sdkconfig: board.sdkconfig || config.sdkconfig,
230
+ display: board.display ? { ...config.display, ...board.display } : config.display
231
+ }
219
232
  }
220
233
 
221
234
  // Paths a target's config names are relative to the app; absolute them once
@@ -417,7 +430,7 @@ export function normalizeDefines(raw) {
417
430
 
418
431
 
419
432
  function emptyTargetConfig() {
420
- return { nativeSources: [], providers: {}, tsconfig: '', nativeIncludeDirectories: [], nativeSystemLibraries: [], nativeResources: {}, nativeLibraries: [], frameworks: [], ldFragments: [], componentDirs: [], componentRequires: [], linkOptions: [], embedFiles: {}, partitions: null, partitionsByTarget: {}, sdkconfig: '', psram: null, flashFreq: 0, display: null, prebuild: '', output: '' }
433
+ return { nativeSources: [], providers: {}, tsconfig: '', nativeIncludeDirectories: [], nativeSystemLibraries: [], nativeResources: {}, nativeLibraries: [], frameworks: [], ldFragments: [], componentDirs: [], componentRequires: [], linkOptions: [], embedFiles: {}, partitions: null, partitionsByTarget: {}, sdkconfig: '', psram: null, flashFreq: 0, display: null, boardSettings: {}, prebuild: '', output: '' }
421
434
  }
422
435
 
423
436
  function normalizeStringList(raw) {
@@ -507,6 +520,7 @@ function normalizeTargetConfig(raw) {
507
520
  // How the RGB panel's repaints reach PSRAM, for apps that redraw the whole
508
521
  // screen every frame (games): { copyBack: 'dma', bounceRows, gridStrips }.
509
522
  display: value.display && typeof value.display === 'object' && !Array.isArray(value.display) ? { ...value.display } : null,
523
+ boardSettings: normalizeBoardSettings(value.boards),
510
524
  prebuild: typeof value.prebuild === 'string' ? value.prebuild.trim() : '',
511
525
  output: typeof value.output === 'string' && value.output.trim() ? normalizeManifestRelativePath(value.output) : ''
512
526
  }
@@ -514,6 +528,12 @@ function normalizeTargetConfig(raw) {
514
528
  return configs
515
529
  }
516
530
 
531
+ function normalizeBoardSettings(boards) {
532
+ if (!boards || typeof boards !== 'object' || Array.isArray(boards)) return {}
533
+ const object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : null)
534
+ return Object.fromEntries(Object.entries(boards).filter(([, board]) => object(board)).map(([id, board]) => [id, { psram: object(board.psram), flashFreq: Number(board.flashFreq) || 0, sdkconfig: typeof board.sdkconfig === 'string' && board.sdkconfig.trim() ? normalizeManifestRelativePath(board.sdkconfig) : '', display: object(board.display) }]))
535
+ }
536
+
517
537
  export function normalizeApp(root, packageJson) {
518
538
  const gea = packageJson.gea || {}
519
539
  const id = typeof gea.id === 'string' && gea.id ? gea.id : packageId(packageJson.name)
@@ -10,9 +10,9 @@ import { configureChipSelection, loadChipCatalog, validateGpioAssignments } from
10
10
  import { flag, option } from './args.mjs'
11
11
  import { ExitCode, fail } from './errors.mjs'
12
12
  import { espIdfVersion as readInstalledEspIdfVersion, findEspIdf, findIdfPythonEnv } from './esp32/idf-env.mjs'
13
- import { espIdfVersionForTarget, extractIdfVersionFromText, fetchLatestEspIdfVersion, idfVersionMeetsTarget, resolveEspIdfVersion } from './esp32/idf-version.mjs'
13
+ import { espIdfVersionForTarget, extractIdfVersionFromText, DEFAULT_ESP_IDF_VERSION, idfVersionMeetsTarget, idfVersionSatisfiesTarget, resolveEspIdfVersion } from './esp32/idf-version.mjs'
14
14
  import { exists, readJson, writeJson } from './fs-utils.mjs'
15
- import { BACK, ask, choose, confirm, createPrompt, ui } from './prompts.mjs'
15
+ import { BACK, ask, canPrompt, choose, confirm, createPrompt, ui } from './prompts.mjs'
16
16
  import { runExternal, runQuiet } from './run.mjs'
17
17
  import { detectSerialDevices } from './serial-devices.mjs'
18
18
  import { commandVersion } from './toolchain.mjs'
@@ -26,6 +26,9 @@ const s31EspIdf = { version: '6.2-dev', ref: 'master', dir: path.join('esp32', '
26
26
 
27
27
  export async function runSetupWizard(ctx, parsed, io) {
28
28
  const stdout = io.stdout || console.log
29
+ if (!canPrompt(io) && option(parsed, 'esp-idf') !== true) {
30
+ fail('gea setup asks questions and needs a terminal. Without one, pass --board <alias>, --target <id> or --esp-idf.', ExitCode.usage)
31
+ }
29
32
  const prompt = createPrompt(io)
30
33
  try {
31
34
  const targetIdfVersion = await resolveEspIdfVersionForWizard(parsed, io)
@@ -443,16 +446,12 @@ async function chooseAppForBoard(ctx, parsed, io, prompt, alias) {
443
446
  }
444
447
 
445
448
  // Resolves the ESP-IDF version target once for the whole wizard run:
446
- // --idf-version / GEA_ESP_IDF_VERSION win outright; otherwise a best-effort
447
- // GitHub "latest release" lookup, falling back to the pinned default when it
448
- // cannot be determined. `io.fetchEspIdfLatest` lets callers (tests) inject a
449
- // fake fetch instead of touching the network -- mirrors `probeSerialDevice`.
449
+ // --idf-version / GEA_ESP_IDF_VERSION win outright; otherwise the pinned
450
+ // release, which is the one every build looks for.
450
451
  async function resolveEspIdfVersionForWizard(parsed, io) {
451
452
  return resolveEspIdfVersion({
452
453
  override: option(parsed, 'idf-version'),
453
- env: io.env || process.env,
454
- fetchLatest: io.fetchEspIdfLatest || fetchLatestEspIdfVersion,
455
- log: io.stderr || (() => {})
454
+ env: io.env || process.env
456
455
  })
457
456
  }
458
457
 
@@ -564,8 +563,9 @@ function installEspIdf(ctx, parsed, io, { idfDir, ref, targets }) {
564
563
  }
565
564
 
566
565
  // Prefers the same conventional-directory detection the build path uses
567
- // (`findEspIdf` + its version.cmake), which lets a version-floor check run;
568
- // falls back to a bare `idf.py --version` on PATH when no such directory is
566
+ // (`findEspIdf` + its version.cmake), asking for the target release first so
567
+ // the answer is the directory a build would pick; falls back to a bare
568
+ // `idf.py --version` on PATH when no such directory is
569
569
  // found but some ESP-IDF install has still put idf.py on PATH.
570
570
  // An explicit --idf-dir is the only directory that counts: another install
571
571
  // elsewhere is not the one asked for, and a branch target such as `master`
@@ -574,7 +574,13 @@ function detectEspIdf(env, targetVersion, explicitDir = '') {
574
574
  if (explicitDir && !fs.existsSync(path.join(explicitDir, 'tools', 'idf.py'))) {
575
575
  return { available: false, detail: '' }
576
576
  }
577
- const idfDir = explicitDir ? path.resolve(explicitDir) : findEspIdf(env)
577
+ // For the pinned default, "found" means the directory a build would pick:
578
+ // builds look for that exact release (IDF_PATH aside), so a newer one on
579
+ // its own is reported, not accepted.
580
+ const home = env.HOME || env.USERPROFILE || os.homedir()
581
+ const pinned = !explicitDir && targetVersion === DEFAULT_ESP_IDF_VERSION
582
+ const buildDir = pinned ? findEspIdf(env, home, { defaultVersion: DEFAULT_ESP_IDF_VERSION.slice(1) }) : ''
583
+ const idfDir = explicitDir ? path.resolve(explicitDir) : buildDir || findEspIdf(env, home)
578
584
  if (idfDir) {
579
585
  const installed = readInstalledEspIdfVersion(idfDir)
580
586
  // A checkout is not an installation. `install.bat`/`install.sh` still has to
@@ -583,12 +589,12 @@ function detectEspIdf(env, targetVersion, explicitDir = '') {
583
589
  // success and leaves nothing that can compile.
584
590
  const toolsInstalled = Boolean(findIdfPythonEnv(idfDir, env))
585
591
  const detail = `${installed?.full || 'unknown version'} at ${idfDir}${toolsInstalled ? '' : ' (tools not installed)'}`
586
- return { available: toolsInstalled && idfVersionMeetsTarget(installed, targetVersion), detail }
592
+ return { available: toolsInstalled && (pinned ? Boolean(buildDir) : idfVersionMeetsTarget(installed, targetVersion)), detail }
587
593
  }
588
594
  const legacyOutput = commandVersion('idf.py', ['--version'], env)
589
595
  if (legacyOutput) {
590
596
  const installed = extractIdfVersionFromText(legacyOutput)
591
- const available = !installed || idfVersionMeetsTarget(installed, targetVersion)
597
+ const available = !installed || idfVersionSatisfiesTarget(installed, targetVersion)
592
598
  return { available, detail: legacyOutput }
593
599
  }
594
600
  return { available: false, detail: '' }
@@ -170,7 +170,8 @@ async function startSimulatorServer({ ctx, app, env, simulatorDir, paths, port,
170
170
  __GEA_WEB_DIST_FS_ROOT__: JSON.stringify(paths.dist)
171
171
  },
172
172
  server: {
173
- port,
173
+ // No --port leaves this an empty string; newer Node rejects that as a port.
174
+ ...(port ? { port: Number(port) } : {}),
174
175
  fs: { allow: [appRoot, paths.dist, paths.public] }
175
176
  }
176
177
  })