@geastack/cli 0.1.100 → 0.1.102

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
@@ -237,6 +237,13 @@ target is not required for debugging; the source manifest is unchanged. On Mac,
237
237
  `gea run --debug` defaults to native for an app that already declares macOS.
238
238
  `gea run --debug --target web` uses the existing DOM/CSS runtime with Vite HMR.
239
239
 
240
+ `gea build --debug --target macos` produces the same instrumented native app
241
+ without launching it or opening Chrome. `gea build --debug --board amoled`
242
+ builds ESP32 debug firmware without flashing or opening USB. Both commands use
243
+ the same debug configuration as `run`, including editable CSS. macOS retains
244
+ full symbols and unoptimized code by default; `--no-debug-sources` disables
245
+ that source-debugging build override.
246
+
240
247
  Elements inspects the native tree, authored class CSS, common inline/computed
241
248
  styles, text, attributes and layout. Inline CSS and tree edits affect the actual
242
249
  AppKit window. The Console runs JavaScriptCore scripts with `document`, `$0`,
@@ -280,7 +287,10 @@ shows native C++ locals; paused-frame evaluation accepts GDB C++ expressions.
280
287
  The board has two breakpoint slots. Its matching ELF is verified before attach;
281
288
  older firmware needs a fresh build. Tree/style inspection does not start JTAG
282
289
  by default. `GEA_DEBUGGER_JTAG=1` also opts in; `--no-debug-sources` overrides it.
283
- Native Mac source stepping is not implemented yet. Inline
290
+ On macOS, source debugging is enabled by default. LLDB uses full symbols and
291
+ unoptimized native code for original TS/TSX breakpoints and Step Over/Into/Out.
292
+ Scopes expose native C++ values; paused expressions use C++ syntax. Use
293
+ `--no-debug-sources` to run tree/style inspection without LLDB. Inline
284
294
  styles, authored class rules, attributes, text, append/remove and compiled event clicks affect the
285
295
  actual device. Live changes are sampled every 750 ms. See the debugger README
286
296
  for supported properties, USB bounds, and example scripts.
@@ -293,3 +303,11 @@ on current debug firmware without rebuilding/flashing. Omitting the flag leaves
293
303
  an existing attached app's cap alone; a fresh build defaults to normal pacing.
294
304
  The cap persists after disconnecting. Firmware from before snapshot integrity
295
305
  and FPS control support needs one rebuild.
306
+
307
+ DevTools edits on macOS and boards go into a shared Gea Changes history that you
308
+ can undo and save. `--save-overrides edits.json` writes the net edits when the
309
+ debugger exits. `--overrides edits.json` replays them as soon as it attaches:
310
+
311
+ ```sh
312
+ gea run --debug --target macos --overrides edits.json --save-overrides edits.json
313
+ ```
@@ -118,7 +118,7 @@ effective build choices unchanged.
118
118
  | compiler.moduleGraph | auto, compile, only, disabled |
119
119
  | compiler.allowAny | boolean; default false |
120
120
  | ui.styleStorage | inline or shared; the existing default remains inline |
121
- | renderer.bandedUi | boolean; default false; application opt-in for DMA band rendering |
121
+ | renderer.bandedUi | boolean; default false; app opt-in for DMA band rendering on ESP32 and RP2350 |
122
122
  | renderer.fuseReplayFlush | boolean |
123
123
  | renderer.subtreeRevealChecks | boolean; keep true when content can move into view from outside a recorded clip |
124
124
  | renderer.recordInlinePositions | boolean; false requires the app to refresh positions through its reactive updates |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.100",
3
+ "version": "0.1.102",
4
4
  "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -37,19 +37,21 @@
37
37
  ],
38
38
  "dependencies": {
39
39
  "@clack/prompts": "^1.8.0",
40
- "@geastack/debugger": "^0.1.0",
41
- "@geastack/simulator": "^0.1.14",
42
- "@geastack/targets": "^0.1.98",
40
+ "@geastack/simulator": "^0.1.15",
41
+ "@geastack/targets": "^0.1.101",
43
42
  "picocolors": "^1.1.1",
44
43
  "serialport": "^13.0.0"
45
44
  },
46
45
  "starterDependencies": {
47
- "@geastack/core": "^0.1.34",
48
- "@geastack/targets": "^0.1.98",
49
- "@geastack/apple": "^0.2.13"
46
+ "@geastack/core": "^0.1.40",
47
+ "@geastack/targets": "^0.1.101",
48
+ "@geastack/apple": "^0.2.15"
50
49
  },
51
50
  "scripts": {
52
51
  "check": "node --check bin/gea.mjs && node --check bin/create-geastack.mjs && find src test packages -name '*.mjs' -print0 | xargs -0 -n1 node --check",
53
52
  "test": "node --test"
53
+ },
54
+ "optionalDependencies": {
55
+ "@geastack/debugger": "^0.1.0"
54
56
  }
55
57
  }
@@ -9,7 +9,7 @@ import { chooseTransport, openDevice, saveScreenshot } from '../device/device.mj
9
9
  import { geadev } from '../device/serial.mjs'
10
10
  import { ExitCode, fail } from '../errors.mjs'
11
11
  import { buildEsp32Firmware, buildImages, esp32BuildDir, fullCleanEsp32, requireEspIdf } from '../esp32/build.mjs'
12
- import { eraseSlot, flashFirmware, flashImageSet, flashOptions, postFlashRestartNote, restoreBootMetadata, stageImage } from '../esp32/flash.mjs'
12
+ import { eraseSlot, flashFirmware, flashImageSet, flashOptions, postFlashRestartNote, restoreBootMetadata, stageImage, runEsptoolOverUsb } from '../esp32/flash.mjs'
13
13
  import { bleOta, otaEraseSlot, otaFlash, otaStage, waitForReboot } from '../esp32/ota.mjs'
14
14
  import { manifestRequestsBleOta } from '../esp32/capabilities.mjs'
15
15
  import { runGeaos } from '../geaos/adapter.mjs'
@@ -117,7 +117,7 @@ function requireApp(ctx, selection, app) {
117
117
 
118
118
  export async function buildCommand(ctx, parsed, rest, options) {
119
119
  const selection = selectBoard(ctx, parsed)
120
- const app = requireAppForAdapter(ctx, parsed, selection, optionalApp(ctx, parsed, rest, selection))
120
+ const app = options.debugApp || requireAppForAdapter(ctx, parsed, selection, optionalApp(ctx, parsed, rest, selection))
121
121
  const base = io(parsed, options)
122
122
  const env = createChildEnv(ctx, base.env)
123
123
  switch (selection.adapter) {
@@ -216,7 +216,7 @@ async function flashEsp32(ctx, parsed, rest, options, selection, { monitor }) {
216
216
  async function usbAppUpdate({ selection, image, appLabel, env, stdout, stderr }) {
217
217
  let device
218
218
  try {
219
- device = await openDevice({ selection, transport: 'usb', env, stderr: () => {}, waitSeconds: 5 })
219
+ device = await openDevice({ selection, transport: 'usb', env, stderr: () => {}, waitSeconds: 20 })
220
220
  } catch {
221
221
  stderr('No running gea app answered on USB; falling back to the ROM downloader (hold BOOT while powering on).')
222
222
  return false
@@ -255,7 +255,7 @@ async function usbAppAnswers({ selection, appLabel, env }) {
255
255
  while (Date.now() < deadline) {
256
256
  let device
257
257
  try {
258
- device = await openDevice({ selection, transport: 'usb', env, stderr: () => {}, waitSeconds: 5 })
258
+ device = await openDevice({ selection, transport: 'usb', env, stderr: () => {}, waitSeconds: 20 })
259
259
  const pong = await geadev.ping(device.serial)
260
260
  return /\bapp=(\S+)/.exec(pong)?.[1] === appLabel
261
261
  } catch {
@@ -442,7 +442,8 @@ Verbs (USB, GEADEV protocol):
442
442
  set-default <app-id> set-time [epochSeconds]
443
443
  ls [path] rm <path>
444
444
  push <local> <remote> [--base64] pull <remote> <local>
445
- playfile <path>
445
+ read-flash <offset> <size> <file> ESP32 ROM/stub flash backup [--no-stub]
446
+ playfile <path> format <mount> (erase + re-format a file volume, e.g. /nand)
446
447
 
447
448
  Display knobs (either transport; no value reports the current one):
448
449
  brightness [0-100] hbm [on|off] vsync [on|off]`
@@ -503,6 +504,18 @@ export async function devctlCommand(ctx, parsed, rest, options) {
503
504
  return verb ? 0 : ExitCode.usage
504
505
  }
505
506
  const selection = selectBoard(ctx, parsed, {})
507
+ if (verb === 'read-flash') {
508
+ if (selection.adapter !== 'esp32-idf' || args.length !== 3) fail('devctl read-flash <offset> <size> <file> needs an ESP32 board.', ExitCode.usage)
509
+ const offset = Number(args[0])
510
+ const size = Number(args[1])
511
+ if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(size) || size <= 0) fail('Flash offset and size must be nonnegative/positive integers.', ExitCode.usage)
512
+ const env = createChildEnv(ctx, options.env)
513
+ const idf = requireEspIdf(env, options.stdout, selection)
514
+ const opts = flashOptions(idf.env, { idf, selection, baud: option(parsed, 'flash-baud', '') })
515
+ const destination = path.resolve(ctx.cwd, args[2])
516
+ await runEsptoolOverUsb({ idf, selection, options: opts, env: idf.env, logDir: path.dirname(destination), verbose: true, stdout: options.stdout, stderr: options.stderr, args: ['--chip', selection.esptoolChip || selection.idfTarget || 'esp32s3', '--before', opts.before, '--after', opts.after, '-b', opts.baud, ...(option(parsed, 'stub') === false ? ['--no-stub'] : []), 'read-flash', String(offset), String(size), destination] })
517
+ return 0
518
+ }
506
519
  // Display knobs answer on both transports, so they follow the board's own
507
520
  // preference (WiFi when it has an address) instead of forcing one; every
508
521
  // other verb is GEADEV-only and needs the cable.
@@ -553,6 +566,7 @@ export async function devctlCommand(ctx, parsed, rest, options) {
553
566
  case 'set-time': print(await geadev.setTime(d, args[0] ? num(args[0], 'epoch') : Math.floor(Date.now() / 1000))); break
554
567
  case 'ls': print(await geadev.ls(d, args[0] || '/sdcard')); break
555
568
  case 'rm': need(1); print(await geadev.rm(d, args[0])); break
569
+ case 'format': need(1); print(await geadev.format(d, args[0])); break
556
570
  case 'push': need(2); print(await geadev.pushFile(d, path.resolve(ctx.cwd, args[0]), args[1], { base64: flag(parsed, 'base64'), stderr: base.stderr })); break
557
571
  case 'pull': need(2); print(await geadev.pullFile(d, args[0], path.resolve(ctx.cwd, args[1]))); break
558
572
  case 'playfile': need(1); print(await geadev.playFile(d, args[0])); break
package/src/debugger.mjs CHANGED
@@ -43,40 +43,96 @@ export function sourceDebuggingRequested(parsed, env = process.env) {
43
43
  return env.GEA_DEBUGGER_JTAG === '1'
44
44
  }
45
45
 
46
- export async function runDebug({ app, env, dryRun = false, stdout, port = 5181, debugPort = 9222, target = 'web', open = true }) {
46
+ // Build and run share instrumentation and manifest overrides. Launching a
47
+ // debugger is a separate step, so a build never needs a browser or device.
48
+ export function nativeDebugBuildOf(app, platform, env, { sources = platform === 'macos', fps = 0 } = {}) {
49
+ if (!['macos', 'esp32'].includes(platform)) fail('--debug builds support native macOS and ESP32 targets.', ExitCode.usage)
50
+ if (app.runtime !== 'gea') fail(`Debugger requires the gea runtime; '${app.id}' uses '${app.runtime}'.`, ExitCode.usage)
51
+ const entry = debuggerEntry(env, platform === 'macos' ? 'launch.mjs' : 'device.mjs')
52
+ const debuggerRoot = path.resolve(path.dirname(entry), '..')
53
+ const nativeEnv = { ...env, GEA_NATIVE_DEBUGGER: '1' }
54
+ if (platform === 'macos') {
55
+ const source = path.join(debuggerRoot, 'native/macos.mm')
56
+ if (!existsSync(source)) fail(`Native debugger source not found: ${source}`, ExitCode.missingDependency)
57
+ nativeEnv.GEA_DEBUGGER_NATIVE_SOURCE = source
58
+ if (sources) {
59
+ nativeEnv.GEA_MACOS_DEBUG_INFO = 'full'
60
+ nativeEnv.GEA_MACOS_OPT_LEVEL = '-O0'
61
+ }
62
+ const stack = path.resolve(debuggerRoot, '..')
63
+ for (const [key, relative, marker] of [
64
+ ['GEA_APPLE_ROOT', 'apple/packages/geastack-apple', 'targets/macos/build-macos.sh'],
65
+ ['GEA_CORE', 'core/packages/core', 'gea_sources.mjs'],
66
+ ['GEA_COMPILER', 'compiler', 'dist/cli.js'],
67
+ ['GEA_PLUGIN', 'core/packages/geatsc-plugin-gea', 'dist/index.js']
68
+ ]) {
69
+ const directory = path.join(stack, relative)
70
+ if (!nativeEnv[key] && existsSync(path.join(directory, marker))) nativeEnv[key] = directory
71
+ }
72
+ if (!nativeEnv.GEA_GEATSC_BIN && nativeEnv.GEA_COMPILER) nativeEnv.GEA_GEATSC_BIN = path.join(nativeEnv.GEA_COMPILER, 'dist/cli.js')
73
+ } else if (platform === 'esp32') {
74
+ nativeEnv.GEA_DEBUGGER_FPS = String(fps)
75
+ nativeEnv.GEA_GEATSC_DEBUG_INFO = '1'
76
+ }
77
+ return { app: appForNativeDebugger(app, platform), env: nativeEnv, debuggerRoot }
78
+ }
79
+
80
+ function boardDebugContext(ctx, env, debuggerRoot) {
81
+ const debugCtx = { ...ctx, env }
82
+ const stack = path.resolve(debuggerRoot, '..')
83
+ for (const [field, key, relative] of [
84
+ ['targetsRoot', 'GEA_TARGETS_ROOT', 'targets'],
85
+ ['compilerPackageDir', 'GEA_COMPILER_DIR', 'compiler'],
86
+ ...['core', 'engine', 'host', 'chips', 'elements', 'geaos'].map(name => [name + 'PackageDir', 'GEA_' + name.toUpperCase() + (name === 'geaos' ? '_PACKAGE_DIR' : '_DIR'), 'core/packages/' + name]),
87
+ ['pluginPackageDir', 'GEA_PLUGIN_DIR', 'core/packages/geatsc-plugin-gea']
88
+ ]) { const directory = path.join(stack, relative); if (!env[key] && existsSync(path.join(directory, 'package.json'))) debugCtx[field] = directory }
89
+ return debugCtx
90
+ }
91
+
92
+ export async function buildBoardDebug({ ctx, parsed, rest, options, app }) {
93
+ const { selectBoard, buildCommand } = await import('./commands/board.mjs')
94
+ const built = nativeDebugBuildOf(app, 'esp32', options.env, { fps: debugFps(option(parsed, 'debug-fps')) })
95
+ const debugCtx = boardDebugContext(ctx, built.env, built.debuggerRoot)
96
+ const selection = selectBoard(debugCtx, parsed)
97
+ if (selection.adapter !== 'esp32-idf') fail('--debug board support currently requires an ESP32 target.', ExitCode.usage)
98
+ if (sourceDebuggingRequested(parsed, built.env) && (selection.idfTarget || 'esp32s3') !== 'esp32s3')
99
+ fail('--debug-sources requires an ESP32-S3 board with USB JTAG.', ExitCode.usage)
100
+ return buildCommand(debugCtx, parsed, rest, { ...options, env: built.env, debugApp: built.app })
101
+ }
102
+
103
+ // Gea Changes overrides: --overrides applies a saved file once the debugger
104
+ // attaches, --save-overrides writes the session's net edits on exit.
105
+ function overrideFiles({ overrides, saveOverrides }) {
106
+ const file = (value, name) => {
107
+ if (value === undefined) return undefined
108
+ if (typeof value !== 'string' || !value) fail(`${name} requires a file path.`, ExitCode.usage)
109
+ return path.resolve(value)
110
+ }
111
+ return { overrides: file(overrides, '--overrides'), saveOverrides: file(saveOverrides, '--save-overrides') }
112
+ }
113
+
114
+ export async function runDebug({ app, env, dryRun = false, stdout, port = 5181, debugPort = 9222, target = 'web', open = true, sources = true, overrides, saveOverrides }) {
47
115
  if (app.runtime !== 'gea') fail(`Debugger requires the gea runtime; '${app.id}' uses '${app.runtime}'.`, ExitCode.usage)
48
116
  const entry = debuggerEntry(env)
117
+ const overrideOptions = overrideFiles({ overrides, saveOverrides })
118
+ if (target !== 'macos' && (overrideOptions.overrides || overrideOptions.saveOverrides)) fail('--overrides and --save-overrides require --debug with native macOS or an ESP32 board.', ExitCode.usage)
49
119
  try {
50
120
  const { launchDebugger, chromeArgs, chromeExecutable, portNumber } = await import(pathToFileURL(entry).href)
51
121
  port = portNumber(port, '--port')
52
122
  debugPort = portNumber(debugPort, '--debug-port')
53
123
  if (target === 'macos') {
54
124
  if (process.platform !== 'darwin') fail('Native macOS debugging requires a Mac.', ExitCode.usage)
55
- const debuggerRoot = path.resolve(path.dirname(entry), '..')
56
- const source = path.join(debuggerRoot, 'native/macos.mm')
57
- if (!existsSync(source)) fail(`Native debugger source not found: ${source}`, ExitCode.missingDependency)
58
- const nativeEnv = { ...env, GEA_NATIVE_DEBUGGER: '1', GEA_DEBUGGER_NATIVE_SOURCE: source }
59
- // Contributor checkouts use one source stack and the shared compiler.
60
- // Explicit overrides win; installed packages retain npm resolution.
61
- const stack = path.resolve(debuggerRoot, '..')
62
- for (const [key, relative, marker] of [
63
- ['GEA_APPLE_ROOT', 'apple/packages/geastack-apple', 'targets/macos/build-macos.sh'],
64
- ['GEA_CORE', 'core/packages/core', 'gea_sources.mjs'],
65
- ['GEA_COMPILER', 'compiler', 'dist/cli.js'],
66
- ['GEA_PLUGIN', 'core/packages/geatsc-plugin-gea', 'dist/index.js']
67
- ]) {
68
- const directory = path.join(stack, relative)
69
- if (!nativeEnv[key] && existsSync(path.join(directory, marker))) nativeEnv[key] = directory
70
- }
71
- if (!nativeEnv.GEA_GEATSC_BIN && nativeEnv.GEA_COMPILER) nativeEnv.GEA_GEATSC_BIN = path.join(nativeEnv.GEA_COMPILER, 'dist/cli.js')
72
- await runMacos({ app: appForNativeDebugger(app, 'macos'), env: nativeEnv, dryRun, stdout })
125
+ const built = nativeDebugBuildOf(app, 'macos', env, { sources })
126
+ const { debuggerRoot } = built
127
+ await runMacos({ app: built.app, env: built.env, dryRun, stdout })
73
128
  const outputRoot = path.resolve(app.root, env.GEA_MACOS_OUTPUT_DIR || 'dist/macos')
74
129
  const subpath = env.GEA_MACOS_OUTPUT_TAG ? path.join('.namespaces', env.GEA_MACOS_OUTPUT_TAG, app.id) : app.id
75
130
  const executable = path.join(outputRoot, subpath, `${app.name}.app`, 'Contents/MacOS', app.name)
76
- if (dryRun) { stdout(formatCommand([executable])); stdout(`Native CDP: ws://127.0.0.1:${debugPort}/devtools/page/gea`); return 0 }
131
+ if (dryRun) { stdout(formatCommand([executable])); stdout(`Native CDP: ws://127.0.0.1:${debugPort}/devtools/page/gea`); if (sources) stdout('Native Sources: LLDB with full symbols and no optimization.'); return 0 }
77
132
  if (!existsSync(executable)) fail(`Built native executable not found: ${executable}`, ExitCode.buildFailed)
78
133
  const { launchNativeDebugger } = await import(pathToFileURL(path.join(debuggerRoot, 'src/native.mjs')).href)
79
- return await launchNativeDebugger({ executable, appRoot: app.root, title: app.name, env, debugPort, stdout, open })
134
+ const metadata = path.join(outputRoot, '.generated', subpath, 'gea-debug-source.json')
135
+ return await launchNativeDebugger({ executable, appRoot: app.root, title: app.name, env, debugPort, stdout, open, nativeDebug: sources ? { metadata } : undefined, ...overrideOptions })
80
136
  }
81
137
  const script = path.join(resolveSimulatorDir(env), 'targets/web/dev-web.mjs')
82
138
  if (!existsSync(script)) fail(`Web dev server not found: ${script}`, ExitCode.missingDependency)
@@ -102,17 +158,11 @@ export async function runBoardDebug({ ctx, parsed, rest, options, app }) {
102
158
  const { openDevice } = await import('./device/device.mjs')
103
159
  const { encodePng } = await import('./device/image.mjs')
104
160
  const entry = debuggerEntry(options.env, 'device.mjs')
105
- const root = path.resolve(path.dirname(entry), '..')
106
161
  const fps = debugFps(option(parsed, 'debug-fps'))
107
- const env = { ...options.env, GEA_NATIVE_DEBUGGER: '1', GEA_DEBUGGER_FPS: String(fps), GEA_GEATSC_DEBUG_INFO: '1' }
108
- const stack = path.resolve(root, '..')
109
- const debugCtx = { ...ctx, env }
110
- for (const [field, key, relative] of [
111
- ['targetsRoot', 'GEA_TARGETS_ROOT', 'targets'],
112
- ['compilerPackageDir', 'GEA_COMPILER_DIR', 'compiler'],
113
- ...['core', 'engine', 'host', 'chips', 'elements', 'geaos'].map(name => [name + 'PackageDir', 'GEA_' + name.toUpperCase() + (name === 'geaos' ? '_PACKAGE_DIR' : '_DIR'), 'core/packages/' + name]),
114
- ['pluginPackageDir', 'GEA_PLUGIN_DIR', 'core/packages/geatsc-plugin-gea']
115
- ]) { const directory = path.join(stack, relative); if (!env[key] && existsSync(path.join(directory, 'package.json'))) debugCtx[field] = directory }
162
+ const overrideOptions = overrideFiles({ overrides: option(parsed, 'overrides'), saveOverrides: option(parsed, 'save-overrides') })
163
+ const built = nativeDebugBuildOf(app, 'esp32', options.env, { fps })
164
+ const { env, debuggerRoot: root } = built
165
+ const debugCtx = boardDebugContext(ctx, env, root)
116
166
  const selection = selectBoard(debugCtx, parsed, { usb: true })
117
167
  if (selection.adapter !== 'esp32-idf') fail('--debug board support currently requires an ESP32 target.', ExitCode.usage)
118
168
  const sources = sourceDebuggingRequested(parsed, env)
@@ -122,9 +172,9 @@ export async function runBoardDebug({ ctx, parsed, rest, options, app }) {
122
172
  const debugPort = portNumber(option(parsed, 'debug-port', 9222), '--debug-port')
123
173
  if (option(parsed, 'open', true) !== false) chromeExecutable(env)
124
174
  const { launchDeviceDebugger } = await import(pathToFileURL(entry).href)
125
- if (!flag(parsed, 'attach')) await flashCommand(debugCtx, parsed, rest, { ...options, env, debugApp: appForNativeDebugger(app, 'esp32') }, { monitor: false })
175
+ if (!flag(parsed, 'attach')) await flashCommand(debugCtx, parsed, rest, { ...options, env, debugApp: built.app }, { monitor: false })
126
176
  if (flag(parsed, 'dry-run')) { options.stdout(`Device CDP: ws://127.0.0.1:${debugPort}/devtools/page/gea`); if(fps)options.stdout(`Device debug FPS cap: ${fps}`); if(sources)options.stdout('Native Sources: USB JTAG requested.'); return 0 }
127
- let nativeDebug
177
+ let nativeDebug, listenerSources
128
178
  if (sources) {
129
179
  const { nativeDebugBuilds } = await import('./debugger-builds.mjs')
130
180
  const builds = nativeDebugBuilds(debugCtx, selection, app, env)
@@ -134,8 +184,21 @@ export async function runBoardDebug({ ctx, parsed, rest, options, app }) {
134
184
  nativeDebug = {builds,serial:selection.usbSerial,env:idf.env,
135
185
  gdbExecutable:env.GEA_GDB_BIN || 'xtensa-esp32s3-elf-gdb',openocdExecutable:env.GEA_OPENOCD_BIN || 'openocd'}
136
186
  } else fail('--debug-sources requires matching local ELF/source metadata. Rebuild without --attach to generate source debugging files.', ExitCode.missingDependency)
137
- } else options.stdout('Native Sources: disabled; --debug-sources explicitly enables USB JTAG for breakpoints and stepping.')
187
+ } else {
188
+ options.stdout('Native Sources: read-only; --debug-sources explicitly enables USB JTAG for breakpoints and stepping.')
189
+ // Event Listeners link to TSX through the firmware's ELF; no JTAG needed.
190
+ try {
191
+ const { nativeDebugBuilds } = await import('./debugger-builds.mjs')
192
+ const builds = nativeDebugBuilds(debugCtx, selection, app, env)
193
+ if (builds.length) {
194
+ const { activateEspIdf } = await import('./esp32/idf-env.mjs')
195
+ const idf = activateEspIdf({ env })
196
+ const chip = selection.idfTarget || 'esp32s3'
197
+ if (idf) listenerSources = { builds, env: idf.env, gdbExecutable: env.GEA_GDB_BIN || (['esp32', 'esp32s2', 'esp32s3'].includes(chip) ? `xtensa-${chip}-elf-gdb` : 'riscv32-esp-elf-gdb') }
198
+ }
199
+ } catch {}
200
+ }
138
201
  const device = await openDevice({ selection, transport: 'usb', env, stderr: options.stderr, waitSeconds: 15 })
139
- try { return await launchDeviceDebugger({ serial: device.serial, screenshot: async () => { const shot = await device.screenshot(); return encodePng(shot.width, shot.height, shot.rgb).toString('base64') }, appRoot: app.root, title: app.name, env, debugPort, debugFps: fps, nativeDebug, stdout: options.stdout, open: option(parsed, 'open', true) !== false }) }
202
+ try { return await launchDeviceDebugger({ serial: device.serial, screenshot: async () => { const shot = await device.screenshot(); return encodePng(shot.width, shot.height, shot.rgb).toString('base64') }, appRoot: app.root, title: app.name, env, debugPort, debugFps: fps, nativeDebug, listenerSources, stdout: options.stdout, open: option(parsed, 'open', true) !== false, ...overrideOptions }) }
140
203
  finally { await device.close() }
141
204
  }
@@ -72,15 +72,18 @@ export class SerialDevice {
72
72
  try {
73
73
  owners = execFileSync('/usr/sbin/lsof', [
74
74
  '-t',
75
+ '-nP',
75
76
  devicePath.replace('/dev/tty.', '/dev/cu.'),
76
77
  devicePath.replace('/dev/cu.', '/dev/tty.')
77
78
  ], {
78
79
  encoding: 'utf8',
79
- timeout: 2000,
80
+ timeout: 15000,
80
81
  stdio: ['ignore', 'pipe', 'ignore']
81
82
  }).trim()
82
83
  } catch (error) {
83
- if (error.status !== 1 && error.code !== 'ENOENT') {
84
+ // A loaded host can take seconds to list open files; a timed-out
85
+ // check is not a busy port, and the flock below still catches one.
86
+ if (error.status !== 1 && error.code !== 'ENOENT' && error.code !== 'ETIMEDOUT' && error.signal !== 'SIGTERM') {
84
87
  throw new Error(`Could not check serial ownership for ${devicePath}`, { cause: error })
85
88
  }
86
89
  owners = error.stdout?.toString().trim() || ''
@@ -287,6 +290,8 @@ export const geadev = {
287
290
  reboot: (d) => d.command('GEADEV REBOOT', ['GEADEV:OK REBOOT']),
288
291
  notify: (d, text) => d.command(`GEADEV NOTIFY ${text}`, ['GEADEV:OK NOTIFY']),
289
292
  rm: (d, devicePath) => d.command(`GEADEV RM ${devicePath}`, ['GEADEV:RM OK', 'GEADEV:RM ERR']),
293
+ // Erases and re-formats a board's file volume (everything on it is lost); a chip erase takes a while.
294
+ format: (d, mount) => d.command(`GEADEV FORMAT ${mount}`, ['GEADEV:FORMAT OK', 'GEADEV:FORMAT ERR'], 180000),
290
295
  playFile: (d, devicePath) => d.command(`GEADEV PLAYFILE ${devicePath}`, ['GEADEV:PLAYFILE OK', 'GEADEV:PLAYFILE ERR'], 30000),
291
296
 
292
297
  async brightness(d, value) {
@@ -459,6 +464,12 @@ export const geadev = {
459
464
  // stream as pushFile.
460
465
  async otaUpdate(d, source, { timeoutMs = 120000, stderr = () => {} } = {}) {
461
466
  const data = readFileSync(source)
467
+ // End whatever partial line the console holds first. A failed ROM-downloader
468
+ // attempt leaves esptool's sync bytes in it with no newline, and the command
469
+ // appended to them is refused as line-too-long -- every retry, until a bare
470
+ // newline clears it.
471
+ await d.writeRaw(Buffer.from('\n'))
472
+ await new Promise((resolve) => setTimeout(resolve, 100))
462
473
  await d.writeLine(`GEADEV OTA ${data.length} ${crc32(data)}`)
463
474
  const ready = await waitFor(d, 'GEADEV:OTA READY', 'GEADEV:OTA ERR', 15000, 'OTA READY')
464
475
  const startedAt = Date.now()
@@ -433,6 +433,13 @@ function preparePartitions(app, config, buildDir, targetId) {
433
433
  // `set(... CACHE STRING ...)`, so a -D of the same name, which exists before
434
434
  // the board's CMakeLists runs, wins without the board knowing about apps.
435
435
  const cssDpr = cssDevicePixelRatioLiteral(resolvedBuild.cssDevicePixelRatio)
436
+ const rtcExcluded = resolvedBuild.defines.includes('GEA_EMBEDDED_RTC_UNUSED=1')
437
+ if (rtcExcluded && capabilities.bindings.includes('rtc'))
438
+ fail('GEA_EMBEDDED_RTC_UNUSED=1 conflicts with the app RTC binding', ExitCode.usage)
439
+ const rtcUsed = capabilities.network && !rtcExcluded
440
+ // Video reachability is not yet part of analysis. Keep H264 by default;
441
+ // an app that only uses PCM/JPEG can explicitly exclude it.
442
+ const h264Used = capabilities.network && !resolvedBuild.defines.includes('GEA_EMBEDDED_H264_UNUSED=1')
436
443
  const appDefines = [env.GEA_NATIVE_DEBUGGER === '1' && 'GEA_NATIVE_DEBUGGER=1', env.GEA_NATIVE_DEBUGGER === '1' && `GEA_NATIVE_DEBUGGER_FPS=${debugFps(env.GEA_DEBUGGER_FPS === '0' ? undefined : env.GEA_DEBUGGER_FPS)}`, withRendererFeatureDefines(resolvedBuild.defines.join(';'), env.GEA_NATIVE_DEBUGGER === '1' ? capabilities.features.filter(f => f === 'worker-realms') : capabilities.features, { devicePixelRatio: cssDpr ? Number(cssDpr) : undefined }), cssDpr && `GEA_EMBEDDED_CSS_LAYOUT_DEVICE_PIXEL_RATIO=${cssDpr}`]
437
444
  .filter(Boolean)
438
445
  .join(';')
@@ -468,7 +475,10 @@ function preparePartitions(app, config, buildDir, targetId) {
468
475
  idfArgs.push(
469
476
  `-DGEA_EMBEDDED_CAPABILITY_NETWORK=${capabilities.network ? 1 : 0}`,
470
477
  `-DGEA_EMBEDDED_CAPABILITY_BLE=${capabilities.ble ? 1 : 0}`,
471
- `-DGEA_EMBEDDED_CAPABILITY_AUDIO=${capabilities.audio ? 1 : 0}`
478
+ `-DGEA_EMBEDDED_CAPABILITY_AUDIO=${capabilities.audio ? 1 : 0}`,
479
+ `-DGEA_EMBEDDED_CAPABILITY_CAMERA=${capabilities.bindings.includes('camera') ? 1 : 0}`,
480
+ `-DGEA_EMBEDDED_CAPABILITY_RTC=${rtcUsed ? 1 : 0}`,
481
+ `-DGEA_EMBEDDED_CAPABILITY_H264=${h264Used ? 1 : 0}`
472
482
  )
473
483
  // IDF's MINIMAL_BUILD component-requirements pass runs before normal
474
484
  // CMake cache propagation; environment values stay visible there, so
@@ -479,6 +489,9 @@ function preparePartitions(app, config, buildDir, targetId) {
479
489
  childEnv.GEA_EMBEDDED_CAPABILITY_NETWORK = capabilities.network ? '1' : '0'
480
490
  childEnv.GEA_EMBEDDED_CAPABILITY_BLE = capabilities.ble ? '1' : '0'
481
491
  childEnv.GEA_EMBEDDED_CAPABILITY_AUDIO = capabilities.audio ? '1' : '0'
492
+ childEnv.GEA_EMBEDDED_CAPABILITY_CAMERA = capabilities.bindings.includes('camera') ? '1' : '0'
493
+ childEnv.GEA_EMBEDDED_CAPABILITY_RTC = rtcUsed ? '1' : '0'
494
+ childEnv.GEA_EMBEDDED_CAPABILITY_H264 = h264Used ? '1' : '0'
482
495
  if (bleOta) childEnv.GEA_EMBEDDED_BLE_OTA = '1'
483
496
  log(`App capabilities: network=${capabilities.network ? 1 : 0} ble=${capabilities.ble ? 1 : 0} audio=${capabilities.audio ? 1 : 0}`)
484
497
  generateWifiConfig(app.root, path.join(buildDir, 'apps', app.id, 'wifi_config.h'))
package/src/gea.mjs CHANGED
@@ -59,7 +59,24 @@ export async function runGea(argv, io = {}) {
59
59
  const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice, fetchEspIdfLatest: io.fetchEspIdfLatest }
60
60
 
61
61
  if (option(parsed, 'debug-fps') !== undefined && !flag(parsed, 'debug')) fail('--debug-fps requires --debug.', ExitCode.usage)
62
- if (flag(parsed, 'debug-sources') && !flag(parsed, 'debug')) fail('--debug-sources requires --debug with an ESP32-S3 board.', ExitCode.usage)
62
+ if (flag(parsed, 'debug-sources') && !flag(parsed, 'debug')) fail('--debug-sources requires --debug with macOS or an ESP32-S3 board.', ExitCode.usage)
63
+ for (const name of ['overrides', 'save-overrides'])
64
+ if (option(parsed, name) !== undefined && !(['run', 'dev', 'simulate'].includes(command) && flag(parsed, 'debug'))) fail(`--${name} requires gea run --debug.`, ExitCode.usage)
65
+
66
+ if (command === 'build' && flag(parsed, 'debug')) {
67
+ const target = option(parsed, 'target', '')
68
+ const app = webApp(ctx, parsed, rest, cwd)
69
+ const { nativeDebugBuildOf, buildBoardDebug, sourceDebuggingRequested } = await import('./debugger.mjs')
70
+ if (option(parsed, 'debug-sources') !== undefined) sourceDebuggingRequested(parsed, env)
71
+ if (target === 'macos' || (!target && !option(parsed, 'board') && process.platform === 'darwin' && app.targets?.macos && !declaresBoardTarget(app))) {
72
+ if (option(parsed, 'debug-fps') !== undefined) fail('--debug-fps currently requires --debug with an ESP32 board.', ExitCode.usage)
73
+ const built = nativeDebugBuildOf(app, 'macos', env, { sources: option(parsed, 'debug-sources', true) !== false })
74
+ const { runMacos } = await import('./macos/adapter.mjs')
75
+ return runMacos({ app: built.app, env: built.env, dryRun: flag(parsed, 'dry-run'), stdout })
76
+ }
77
+ if (target && knownPlatforms.includes(target) && target !== 'esp32') fail('--debug builds support native macOS and ESP32 targets.', ExitCode.usage)
78
+ return buildBoardDebug({ ctx, parsed, rest, options, app })
79
+ }
63
80
 
64
81
  if (['run', 'dev', 'simulate'].includes(command) && flag(parsed, 'debug')) {
65
82
  const target = option(parsed, 'target', '')
@@ -71,10 +88,15 @@ export async function runGea(argv, io = {}) {
71
88
  fail('--debug supports the DOM runtime, native macOS, and ESP32 boards over USB.', ExitCode.usage)
72
89
  }
73
90
  if (option(parsed, 'debug-fps') !== undefined) fail('--debug-fps currently requires --debug with an ESP32 board.', ExitCode.usage)
74
- if (flag(parsed, 'debug-sources')) fail('--debug-sources requires --debug with an ESP32-S3 board.', ExitCode.usage)
75
91
  const app = webApp(ctx, parsed, rest, cwd)
92
+ const debugTarget = target || (command === 'run' && process.platform === 'darwin' && app.targets?.macos ? 'macos' : 'web')
93
+ if (flag(parsed, 'debug-sources') && debugTarget !== 'macos') fail('--debug-sources requires --debug with macOS or an ESP32-S3 board.', ExitCode.usage)
94
+ if (option(parsed, 'debug-sources') !== undefined) {
95
+ const { sourceDebuggingRequested } = await import('./debugger.mjs')
96
+ sourceDebuggingRequested(parsed, env)
97
+ }
76
98
  const { runDebug } = await import('./debugger.mjs')
77
- return runDebug({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, port: option(parsed, 'port', 5181), debugPort: option(parsed, 'debug-port', 9222), target: target || (command === 'run' && process.platform === 'darwin' && app.targets?.macos ? 'macos' : 'web'), open: option(parsed, 'open', true) !== false })
99
+ return runDebug({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, port: option(parsed, 'port', 5181), debugPort: option(parsed, 'debug-port', 9222), target: debugTarget, open: option(parsed, 'open', true) !== false, sources: option(parsed, 'debug-sources', true) !== false, overrides: option(parsed, 'overrides'), saveOverrides: option(parsed, 'save-overrides') })
78
100
  }
79
101
 
80
102
  // Xbox is both a platform and a concrete built-in UWP target.
@@ -266,7 +288,7 @@ ${heading('Usage:')}
266
288
  gea doctor [--json] [--strict] check packages and toolchains
267
289
 
268
290
  ${heading('Run on this machine (no board needed):')}
269
- gea run [app] --debug [--debug-port N] live tree/CSS in Chrome DevTools [--target macos|web|esp32] [--board alias] [--attach] [--debug-fps 1..120] [--debug-sources]
291
+ gea run [app] --debug [--debug-port N] live tree/CSS in Chrome DevTools [--target macos|web|esp32] [--board alias] [--attach] [--debug-fps 1..120] [--debug-sources] [--overrides file] [--save-overrides file]
270
292
  gea simulate [app] [--port N] DOM emulator with HMR [--renderer dom|wasm] [--no-open] [--width W --height H --dpr D --zoom Z]
271
293
  gea dev [app] [--port N] real DOM + CSS dev server with HMR (same as --target web)
272
294
  gea build --target web [app] [--out-dir d] build the app as a real web app
@@ -17,7 +17,7 @@ export function runIos({ app, env, dryRun = false, stdout, mode = '', run = fals
17
17
  if (destination !== 'simulator' && destination !== 'device') {
18
18
  fail(`--mode ${mode} is not an iOS destination; expected simulator or device.`, ExitCode.usage)
19
19
  }
20
- const { script, require } = appleTargetScript(app, 'ios', 'build-ios.sh')
20
+ const { script, require } = appleTargetScript(app, 'ios', 'build-ios.sh', env)
21
21
  const childEnv = appleChildEnv(app, nativeScriptBuildEnv(app, 'ios', env, { dryRun }), require)
22
22
  if (!run && childEnv.GEA_IOS_SKIP_LAUNCH === undefined) childEnv.GEA_IOS_SKIP_LAUNCH = '1'
23
23
  if (dryRun) {