@geastack/cli 0.1.101 → 0.1.103
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 +19 -1
- package/docs/NATIVE-BUILD-CONFIG.md +1 -1
- package/package.json +6 -6
- package/src/commands/board.mjs +19 -5
- package/src/debugger.mjs +98 -35
- package/src/device/serial.mjs +13 -2
- package/src/esp32/build.mjs +14 -1
- package/src/gea.mjs +26 -4
- package/src/ios/adapter.mjs +1 -1
- package/src/manifest.mjs +8 -5
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
|
-
|
|
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;
|
|
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.
|
|
3
|
+
"version": "0.1.103",
|
|
4
4
|
"description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -37,15 +37,15 @@
|
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@clack/prompts": "^1.8.0",
|
|
40
|
-
"@geastack/simulator": "^0.1.
|
|
41
|
-
"@geastack/targets": "^0.1.
|
|
40
|
+
"@geastack/simulator": "^0.1.15",
|
|
41
|
+
"@geastack/targets": "^0.1.101",
|
|
42
42
|
"picocolors": "^1.1.1",
|
|
43
43
|
"serialport": "^13.0.0"
|
|
44
44
|
},
|
|
45
45
|
"starterDependencies": {
|
|
46
|
-
"@geastack/core": "^0.1.
|
|
47
|
-
"@geastack/targets": "^0.1.
|
|
48
|
-
"@geastack/apple": "^0.2.
|
|
46
|
+
"@geastack/core": "^0.1.40",
|
|
47
|
+
"@geastack/targets": "^0.1.101",
|
|
48
|
+
"@geastack/apple": "^0.2.15"
|
|
49
49
|
},
|
|
50
50
|
"scripts": {
|
|
51
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",
|
package/src/commands/board.mjs
CHANGED
|
@@ -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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
56
|
-
const
|
|
57
|
-
|
|
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
|
-
|
|
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
|
|
108
|
-
const
|
|
109
|
-
const
|
|
110
|
-
|
|
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:
|
|
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
|
|
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
|
}
|
package/src/device/serial.mjs
CHANGED
|
@@ -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:
|
|
80
|
+
timeout: 15000,
|
|
80
81
|
stdio: ['ignore', 'pipe', 'ignore']
|
|
81
82
|
}).trim()
|
|
82
83
|
} catch (error) {
|
|
83
|
-
|
|
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()
|
package/src/esp32/build.mjs
CHANGED
|
@@ -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:
|
|
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
|
package/src/ios/adapter.mjs
CHANGED
|
@@ -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) {
|
package/src/manifest.mjs
CHANGED
|
@@ -319,15 +319,15 @@ function normalizeLauncher(raw) {
|
|
|
319
319
|
}
|
|
320
320
|
}
|
|
321
321
|
|
|
322
|
-
function normalizeManifestRelativePath(value) {
|
|
322
|
+
function normalizeManifestRelativePath(value, allowParent = false) {
|
|
323
323
|
const normalized = path.posix.normalize(String(value || '').replaceAll('\\', '/'))
|
|
324
324
|
if (!normalized || normalized === '.' || normalized === '..') return ''
|
|
325
|
-
if (path.posix.isAbsolute(normalized) || normalized.startsWith('../')) return ''
|
|
326
|
-
if (normalized.includes('/../') || normalized.includes(';')) return ''
|
|
325
|
+
if (path.posix.isAbsolute(normalized) || (allowParent !== true && normalized.startsWith('../'))) return ''
|
|
326
|
+
if ((allowParent !== true && normalized.includes('/../')) || normalized.includes(';')) return ''
|
|
327
327
|
return normalized
|
|
328
328
|
}
|
|
329
329
|
|
|
330
|
-
// A nativeSources entry is either a path
|
|
330
|
+
// A nativeSources entry is either a path relative to the app or a file in one of its
|
|
331
331
|
// packages. App-relative wins when it exists, so nothing already declared can
|
|
332
332
|
// change meaning; anything else is handed to node resolution, which is what
|
|
333
333
|
// lets an app name `@geastack/native-webgl-angle/native/audio_host.mm` instead
|
|
@@ -347,7 +347,10 @@ export function resolveAppSourcePath(root, source) {
|
|
|
347
347
|
|
|
348
348
|
export function normalizeNativeSources(raw) {
|
|
349
349
|
if (!Array.isArray(raw)) return []
|
|
350
|
-
|
|
350
|
+
// Shared native code can live beside an app's directory. These are explicit
|
|
351
|
+
// compiler inputs, unlike app assets, and resolveAppSourcePath/validateApp
|
|
352
|
+
// must see missing sibling files instead of silently dropping the entries.
|
|
353
|
+
const sources = raw.map((source) => normalizeManifestRelativePath(source, true)).filter((source) => /\.(?:c|cc|cpp|cxx|m|mm|S)$/.test(source))
|
|
351
354
|
return [...new Set(sources)]
|
|
352
355
|
}
|
|
353
356
|
|