@geastack/cli 0.1.102 → 0.1.104

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.
@@ -90,8 +90,20 @@ All of these need the USB transport.
90
90
  | `mem` | heap and PSRAM figures |
91
91
  | `summary` | a combined status report |
92
92
  | `i2cscan` | addresses responding on the I2C bus |
93
+ | `netdiag` | network task counters and the native Wi-Fi driver's diagnostic dump |
94
+ | `taskstats` | state, priority, core and CPU counters for the target's known runtime and media tasks |
93
95
  | `reboot` | restart the board |
94
96
 
97
+ `netdiag` and `taskstats` print the complete report between its `BEGIN` and
98
+ `END` markers, including native driver output. They require firmware that
99
+ implements the corresponding diagnostic command. Task CPU deltas cover the
100
+ interval since the preceding sample; the first sample has zero deltas.
101
+
102
+ ```sh
103
+ npx gea devctl netdiag --board mosaico --transport usb
104
+ npx gea devctl taskstats --board mosaico --transport usb
105
+ ```
106
+
95
107
  ### Input injection
96
108
 
97
109
  | verb | arguments |
@@ -0,0 +1,154 @@
1
+ # Native Linux board deployment
2
+
3
+ `linux-native` is a separate board adapter for `raspberry-pi-os`. It does not
4
+ reinterpret an existing `geaos-linux` alias. Registration is local only:
5
+
6
+ ```
7
+ gea boards add <new-alias> --linux-config <absolute-reviewed-registration.json>
8
+ gea boards show <new-alias> --json
9
+ gea flash --board <new-alias> --app <app-id> --dry-run
10
+ ```
11
+
12
+ Real-board deployment is not yet covered by tests.
13
+
14
+ ## Registration authority
15
+
16
+ The JSON entry must declare `target` and `appPlatform` as `raspberry-pi-os`, and
17
+ `adapter` as `linux-native`. `transports.ssh` contains explicit `host`, `user`,
18
+ integer `port`, `hostKeyAlias`, absolute `knownHosts`, and absolute `identityFile`.
19
+ The public known-hosts file has exactly one ordinary key entry for that alias.
20
+ The local files must be owned regular files, not group/world writable; the
21
+ identity file must be private. Host identity comes from an independently trusted
22
+ key, never `ssh-keyscan` acceptance or a first-connection prompt.
23
+
24
+ `linuxDeployment` contains:
25
+
26
+ - `releaseRoot`: explicit canonical remote directory owned by the registered
27
+ user, mode0700. It may be freshly created under a safe existing parent. No
28
+ filesystem-root staging or symlink ancestors are admitted.
29
+ - `hookSource`: absolute local reviewed Python transaction implementation.
30
+ - `hookSha256`: exact hash of that source. Those bytes are streamed and stored
31
+ in the transaction, so a newly preinstalled board hook is not required.
32
+ - `profile`: explicit product/board authority consumed by that implementation.
33
+ `audioOff:true`, `quiet:true` and absolute `stateDirectory` are mandatory for
34
+ this currently bounded deployment mode. This is a deployment admission, not a
35
+ permanent restriction on user-enabled product audio. Service, display/session,
36
+ storage helper, protected mount identities, backup/preimages, namespace and
37
+ rollback expectations belong in the reviewed profile/handler, not CLI guesses.
38
+ The schema requires a service unit name, `storage:{program,sha256}`, and
39
+ `session:{uid,runtimeDirectory,type,display}` with actual x11/wayland authority.
40
+ Their shape is validated locally; only the reviewed handler's real observations
41
+ can establish that those identities and the session exist on the board.
42
+
43
+ An existing alias cannot be overwritten by registration. `boards set` validates
44
+ an entire native Linux entry before writing it. Files in the registration remain
45
+ local authority; do not publish private-key bytes in a project or receipt.
46
+
47
+ ## Build and release authority
48
+
49
+ `gea flash` performs the actual native Linux SDK build. There is no `--no-build`
50
+ artifact shortcut. The executable comes from the SDK's existing
51
+ `dist/raspberry-pi-os/<app>/<app>` path; resources come only from the adjacent
52
+ `resources` directory. Output overrides are not supported by this deployment
53
+ route. The release manifest includes every regular resource, exact bytes, mode,
54
+ size and SHA; symlinks and special files are refused. Bounds are4096 files,
55
+ 64MiB per file and128MiB total. Empty directories are not release artifacts.
56
+
57
+ Before opening SSH the ELF gate uses explicitly supplied absolute
58
+ `GEA_NATIVE_READELF` and `GEA_NATIVE_NM`: ELF64 little-endian AArch64 executable
59
+ with interpreter, actual SDL2 dependency/imports and defined SDK presentation
60
+ producers. WebKit/WebView/JavaScriptCore coexistence is refused. This structural
61
+ gate does not establish visual, input, audio or full application acceptance.
62
+
63
+ The SSH invocation ignores ambient config, proxy/jump, multiplexing, forwarding
64
+ and password/interactive authentication. It uses the registered identity only,
65
+ `StrictHostKeyChecking=yes`, explicit `HostKeyAlias`, explicit known-hosts file,
66
+ and no global known-hosts fallback. Every resume establishes the same pinned
67
+ identity again. `--host` override and `gea run`/monitor are refused.
68
+
69
+ ## Streamed transaction protocol
70
+
71
+ The generic transport is `src/linux/transaction.py`, invoked through SSH with
72
+ JSON input. It never selects a systemd service, changes protection, opens a
73
+ picker, starts the app or reboots on its own. The reviewed streamed handler is
74
+ executed as Python in isolated mode with the selected phase argument and bounded
75
+ JSON context on stdin. It has only PATH/LANG environment. The registered profile
76
+ must provide all nine `phaseTimeoutSeconds` (prepare, quiesce, backup, activate,
77
+ verify, protect, observe, rollback, inspect), each an integer from1 through600,
78
+ and `transferTimeoutSeconds` from1 through300. The SSH outer budget is the sum
79
+ of those phase budgets, transfer budget and30 seconds. Products must choose
80
+ budgets covering their real stop, inventory and archive bounds; a product's own
81
+ handler may require longer explicit minima. Timeout kills and waits for the hook process
82
+ group; the local regression additionally verifies its authored child disappears. A handler which schedules an
83
+ intentional later reboot must return its pending receipt before the connection
84
+ is lost. There is no successful receipt inferred from SSH disconnect.
85
+
86
+ Context binds `protocol:1`, transaction UUID, release hash, app id, exact profile,
87
+ hook hash, current phase, staged release directory, complete manifest and previous
88
+ phase receipts. Each response must repeat protocol/transaction/release/phase and
89
+ supply actual observed `bootId`. The mandatory sequence is:
90
+
91
+ | Phase | Required response fields |
92
+ | --- | --- |
93
+ | prepare | `maintenance_required`, or `maintenance_ready` with `profileVerified:true` and `rollbackReady:true` |
94
+ | quiesce | `ok`, `processReaped:true`, `flushed:true` |
95
+ | backup | `ok`, `backupVerified:true`, exact `backupSha256` |
96
+ | activate | `ok`; the handler must preserve a durable rollback before changes |
97
+ | verify | `ok`, `releaseVerified:true`, `statePreserved:true`, `sessionVerified:true` |
98
+ | protect | `ok`, `rebootRequired:true`; this is pending, not installed acceptance |
99
+ | observe | `protected`, a different bootId, release/state/session verification true |
100
+ | inspect | `inspection`, `readOnly:true`; retained product state, no mutation |
101
+ | rollback | separate explicit recovery: `rolled_back`, `statePreserved:true`, `rollbackVerified:true` |
102
+
103
+ These fields are a handler contract, not independent proof from booleans. The
104
+ handler/profile must retain concrete externally reviewable hashes, process and
105
+ storage observations and actual backup/rollback receipts. A handler that merely
106
+ prints those fields is not a product installation profile.
107
+
108
+ Transport stores each phase's inflight marker before invoking the handler, then
109
+ fsyncs the state and parent directory. Interrupted/inflight or failed transactions
110
+ cannot automatically retry mutation. Their retained state requires explicit
111
+ recovery. It never silently deletes the old release, backup or failed candidate.
112
+ Release bytes and binding are checked again on resume. Canonical private
113
+ transaction directories, one release-root nonblocking flock and durable active
114
+ transaction ownership prevent competing UUIDs during pending or failed phases.
115
+ Product handlers must independently serialize their canonical service/state
116
+ authority, including aliases using different release roots.
117
+ Trust is the registered remote account; adversarial same-UID modification is not
118
+ claimed to be prevented.
119
+
120
+ Pending maintenance, candidate acceptance, exact transition review and protected
121
+ boot return status2 and retain a local
122
+ transaction receipt. Resume through the same CLI/board with
123
+ `gea flash --board <alias> --app <app-id> --transaction <uuid>` after the reviewed
124
+ maintenance/protect operation. The build and release must still match. `complete`
125
+ is returned only after the handler's subsequent protected-boot observation.
126
+
127
+ ## Tests
128
+
129
+ Run `node --test test/linux-deploy.test.mjs` and the existing
130
+ `test/linux-target.test.mjs` separately. The former uses actual local Python
131
+ transport and isolated authored files, plus a pure ELF-inspection oracle; it never
132
+ opens SSH or executes systemd/storage programs. Every write-capable CLI test
133
+ requires an explicit boards config inside its own fixture before invocation.
134
+
135
+ ## Inspection and explicit recovery
136
+
137
+ `gea flash --board <alias> --app <app-id> --transaction <uuid> --inspect-transaction`
138
+ uses the stored manifest, profile and pinned hook; it does not rebuild or require
139
+ replacement artifacts. Its local receipt includes the exact transport-state SHA
140
+ and product observation. It never treats inspection as successful installation.
141
+
142
+ `--rollback --authorization <absolute-json>` is a separate recovery invocation.
143
+ The exact bounded authorization bytes and SHA are preserved. The object binds
144
+ transaction, release, hook, `phase:"rollback"` and the inspected
145
+ `transportStateSHA256`; a product handler may additionally require the inspected
146
+ `productRecordSHA256` and any exact lifecycle state delta. Wrong or stale state
147
+ pins refuse before the recovery hook.
148
+
149
+ Errors and timeouts preserve the failed inflight phase and active ownership;
150
+ there is no automatic rollback or retry of uncertain work. Only verified terminal
151
+ rollback or protected completion releases ownership. Prepare/verify/observe may
152
+ pause for review without advancing mutation phases. A phase-specific authorization
153
+ is passed only to its exact phase, and byte/hash/JSON disagreement refuses before
154
+ invoking any hook.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.102",
3
+ "version": "0.1.104",
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.101",
41
+ "@geastack/targets": "^0.1.104",
42
42
  "picocolors": "^1.1.1",
43
43
  "serialport": "^13.0.0"
44
44
  },
@@ -19,9 +19,13 @@ import { exists, readJson, writeJson } from '../fs-utils.mjs'
19
19
  // development convenience that described one developer's bench, and every
20
20
  // npm install would have to overwrite it.
21
21
 
22
+ // The CLI's per-user directory: GEA_HOME, else ~/.geastack.
23
+ export function geastackHome(env = process.env) {
24
+ return env.GEA_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.geastack')
25
+ }
26
+
22
27
  export function homeBoardsConfigPath(env = process.env) {
23
- const home = env.GEA_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.geastack')
24
- return path.join(home, 'boards.json')
28
+ return path.join(geastackHome(env), 'boards.json')
25
29
  }
26
30
 
27
31
  // Every file that contributes aliases, lowest precedence first. The list is
@@ -147,6 +147,7 @@ export function resolveBoardSelection({
147
147
 
148
148
  const selection = {
149
149
  boardName,
150
+ ...(adapter === 'linux-native' ? {linuxBoard: board} : {}),
150
151
  targetBase,
151
152
  target,
152
153
  adapter,
@@ -19,12 +19,14 @@ const serialPatterns = [
19
19
  /^ttyUSB/
20
20
  ]
21
21
 
22
- export function serialPortCandidates() {
22
+ export function serialPortCandidates(env = process.env) {
23
23
  // Windows has no /dev: a port is `COM3`, enumerated through the OS rather
24
24
  // than listed in a directory. Everything below that asks "is this port here?"
25
25
  // has to go through the same enumeration, because existsSync('COM3') is
26
- // always false and made every Windows wait time out.
27
- if (process.platform === 'win32') return detectSerialDevices({}).map((device) => device.path).sort()
26
+ // always false and made every Windows wait time out. It is the command's
27
+ // environment that is enumerated, so a GEA_SERIAL_DEVICES given to the
28
+ // command replaces the OS list here as it does when resolving a serial.
29
+ if (process.platform === 'win32') return detectSerialDevices({ env }).map((device) => device.path).sort()
28
30
  const dev = '/dev'
29
31
  if (!existsSync(dev)) return []
30
32
  return readdirSync(dev)
@@ -34,10 +36,10 @@ export function serialPortCandidates() {
34
36
  }
35
37
 
36
38
  // Windows port names are case-insensitive, so compare them that way.
37
- export function serialPortPresent(port) {
39
+ export function serialPortPresent(port, env = process.env) {
38
40
  if (!port) return false
39
41
  if (process.platform !== 'win32') return existsSync(port)
40
- return serialPortCandidates().some((candidate) => candidate.toUpperCase() === port.toUpperCase())
42
+ return serialPortCandidates(env).some((candidate) => candidate.toUpperCase() === port.toUpperCase())
41
43
  }
42
44
 
43
45
  export function resolveAutoUsbPort() {
@@ -193,13 +195,15 @@ export function resolveUsbSerialPort({ serial }, { platform = process.platform,
193
195
  if (!serial) throw new Error('A USB serial number is required to locate the board; /dev paths are not accepted.')
194
196
  // GEA_SERIAL_DEVICES replaces OS enumeration everywhere (see detectSerialDevices);
195
197
  // resolution honors it with the same exact-serial rule, so a declared device list
196
- // can never map one board's serial onto another's port.
197
- if (env.GEA_SERIAL_DEVICES) {
198
+ // can never map one board's serial onto another's port. Windows enumeration
199
+ // already reports each COM port's serial, so it resolves the same way.
200
+ if (env.GEA_SERIAL_DEVICES || platform === 'win32') {
198
201
  const needle = normalizedSerial(serial)
199
- const matches = detectSerialDevices({ env }).filter((device) => device.serial && normalizedSerial(device.serial) === needle)
202
+ const matches = detectSerialDevices({ env, platform }).filter((device) => device.serial && normalizedSerial(device.serial) === needle)
200
203
  if (matches.length === 1) return matches[0].path
201
204
  if (matches.length > 1) throw new Error([`USB serial ${serial} maps to multiple ports:`, ...matches.map((device) => ` ${device.path}`)].join('\n'))
202
- throw new Error(`Could not map USB serial ${serial} to a port in GEA_SERIAL_DEVICES. Check that the board is attached.`)
205
+ const source = env.GEA_SERIAL_DEVICES ? 'a port in GEA_SERIAL_DEVICES' : 'a COM port'
206
+ throw new Error(`Could not map USB serial ${serial} to ${source}. Check that the board is attached.`)
203
207
  }
204
208
  if (platform === 'linux') {
205
209
  const matches = linuxSerialByIdCandidates(serial)
@@ -248,7 +252,7 @@ export async function waitForSerialPort({
248
252
  let nextLog = startedAt
249
253
  while (true) {
250
254
  if (port) {
251
- if (portPresent(port)) {
255
+ if (portPresent(port, env)) {
252
256
  if (!serial) return port
253
257
  try {
254
258
  if (resolver({ serial }, { env }) === port) return port
@@ -259,12 +263,12 @@ export async function waitForSerialPort({
259
263
  } else if (serial) {
260
264
  try {
261
265
  const resolved = resolver({ serial }, { env })
262
- if (resolved && portPresent(resolved)) return resolved
266
+ if (resolved && portPresent(resolved, env)) return resolved
263
267
  } catch {
264
268
  // not attached yet
265
269
  }
266
270
  } else {
267
- const candidate = serialPortCandidates()[0]
271
+ const candidate = serialPortCandidates(env)[0]
268
272
  if (candidate) return candidate
269
273
  }
270
274
  const elapsed = (Date.now() - startedAt) / 1000
@@ -212,7 +212,19 @@ export function resolveBuildConfig({ app, platform, board = '', targetsRoot = ''
212
212
  if (platform === 'esp32' && inferred.runtime.mode === 'canvas' && !managedDefines.some(d => d.startsWith('GEA_EMBEDDED_WIFI_DISABLED='))) managedDefines.push('GEA_EMBEDDED_WIFI_DISABLED=1')
213
213
  }
214
214
  defines.push(...managedDefines)
215
- return { platform, board, inferred, settings: unflatten(flat), origins, inapplicable, defines, managedDefines, cssDevicePixelRatio, cssDevicePixelRatioOrigin: cssOrigin }
215
+ const selectedCapabilities = capabilities && {
216
+ ...capabilities,
217
+ aec: Boolean(capabilities.audio && (defines.includes('GEA_AUDIO_ECHO_CANCELLATION=1') ||
218
+ (capabilities.aec && !defines.includes('GEA_AUDIO_ECHO_CANCELLATION=0')))),
219
+ rtc: capabilities.network && !defines.includes('GEA_EMBEDDED_RTC_UNUSED=1'),
220
+ h264: capabilities.network && !defines.includes('GEA_EMBEDDED_H264_UNUSED=1'),
221
+ }
222
+ if (selectedCapabilities?.aec) {
223
+ for (const name of ['GEA_AUDIO_ECHO_CANCELLATION', 'GEA_AUDIO_FULL_DUPLEX']) {
224
+ if (!defines.some(define => define.startsWith(name + '='))) defines.push(name + '=1')
225
+ }
226
+ }
227
+ return { platform, board, inferred, settings: unflatten(flat), origins, inapplicable, defines, managedDefines, cssDevicePixelRatio, cssDevicePixelRatioOrigin: cssOrigin, ...(selectedCapabilities && { capabilities: selectedCapabilities }) }
216
228
  }
217
229
 
218
230
  function inferRuntime(app, platform, capabilities, target) {
@@ -222,10 +234,10 @@ function inferRuntime(app, platform, capabilities, target) {
222
234
  const proofs = features.filter(f => f.startsWith('runtime-analysis-'))
223
235
  const native = app?.manifest || {}
224
236
  const platformNative = typeof native.targets?.[platform] === 'object' ? native.targets[platform] : {}
225
- const extensionKeys = ['nativeSources', 'componentDirs', 'componentRequires', 'linkOptions', 'compilerPlugins']
237
+ const extensionKeys = ['nativeSources', 'nativeLibraries', 'nativeIncludeDirectories', 'nativeSystemLibraries', 'nativeResources', 'frameworks', 'componentDirs', 'componentRequires', 'linkOptions', 'compilerPlugins']
226
238
  if (!proofs.length || proofs.some(p => p !== 'runtime-analysis-v1')) reason = 'no supported complete runtime analysis'
227
239
  else if (!features.includes('runtime-canvas-only')) reason = 'app requires the full runtime or source analysis is inconclusive'
228
- else if (extensionKeys.some(key => native[key]?.length || platformNative[key]?.length)) reason = 'native extensions cannot be proven independent of the UI and services'
240
+ else if (extensionKeys.some(key => native[key]?.length || platformNative[key]?.length) || Object.keys(platformNative.nativeResources || {}).length) reason = 'native extensions cannot be proven independent of the UI and services'
229
241
  else if (capabilities.network || capabilities.ble || capabilities.audio || (capabilities.bindings || []).some(b => b !== 'display')) reason = 'app requires host services outside the canvas runtime'
230
242
  else return { runtime: { mode: 'canvas', reason: 'complete source analysis proves direct display drawing without UI or host services' } }
231
243
  }
@@ -253,14 +265,24 @@ export function renderBuildCmake(resolved) {
253
265
  lines.push(`set(${buildVariable(key)} "${typeof value === 'boolean' ? Number(value) : value}")`)
254
266
  }
255
267
  lines.push(`set(GEA_APP_CANVAS_ONLY "${Number(resolved.inferred?.runtime.mode === 'canvas')}")`)
268
+ if (resolved.capabilities) lines.push('set(GEA_APP_CAPABILITY_ANALYSIS_VERSION 1)')
269
+ for (const [name, enabled] of Object.entries(resolved.capabilities || {})) {
270
+ if (!/^[a-z][a-z0-9_]*$/.test(name) || typeof enabled !== 'boolean') continue
271
+ lines.push(`set(GEA_EMBEDDED_CAPABILITY_${name.toUpperCase()} ${Number(enabled)} CACHE BOOL "Analyzed app capability" FORCE)`)
272
+ }
273
+ if (resolved.capabilityDependencies) {
274
+ lines.push('set(GEA_APP_CAPABILITY_DEPENDENCIES 1)')
275
+ lines.push(`set(GEA_APP_CAPABILITY_DEPENDENCY_DIR "${resolved.capabilityDependencyDirectory.replaceAll('\\', '/').replaceAll('"', '\\"')}")`)
276
+ }
256
277
  return lines.join('\n') + '\n'
257
278
  }
258
- export function writeBuildConfig(buildDir, resolved) {
279
+ export function writeBuildConfig(buildDir, resolved, { capabilityDependencyDirectory = '' } = {}) {
259
280
  fs.mkdirSync(buildDir, { recursive: true })
260
281
  const cmake = path.join(buildDir, 'gea-build-config.cmake')
261
282
  const json = path.join(buildDir, 'gea-build-config.json')
262
283
  const contents = JSON.stringify(resolved, null, 2) + '\n'
263
- for (const [file, value] of [[cmake, renderBuildCmake(resolved)], [json, contents]]) {
284
+ const native = renderBuildCmake({ ...resolved, capabilityDependencies: Boolean(capabilityDependencyDirectory), capabilityDependencyDirectory })
285
+ for (const [file, value] of [[cmake, native], [json, contents]]) {
264
286
  if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== value) fs.writeFileSync(file, value)
265
287
  }
266
288
  return { cmake, json, hash: createHash('sha256').update(contents).digest('hex') }
@@ -1,3 +1,4 @@
1
+ import { syncNativeResources } from '../native-resources.mjs'
1
2
  import { readdirSync } from 'node:fs'
2
3
  import path from 'node:path'
3
4
 
@@ -14,6 +15,12 @@ export async function appsCommand(ctx, parsed, rest, options) {
14
15
  const args = rest.slice(1)
15
16
  switch (sub) {
16
17
  case 'list': return listApps(ctx, parsed, options)
18
+ case 'sync-native-resources': {
19
+ const app=resolveRequestedApp(ctx,parsed,args);assertValidApp(app);const target=option(parsed,'target',''),output=option(parsed,'output','');
20
+ if(!target||!output)fail('sync-native-resources requires --target and --output',ExitCode.usage);
21
+ if(!app.targets[target]||!['macos','raspberry-pi-os'].includes(target))fail('Unsupported or disabled native resource target',ExitCode.usage);
22
+ options.stdout(JSON.stringify(syncNativeResources(app.root,target,app.targetConfig[target]?.nativeResources||{},path.resolve(output))));return 0
23
+ }
17
24
  case 'inspect': return inspectApp(ctx, parsed, args, options)
18
25
  case 'index': return appIndex(ctx, parsed, options)
19
26
  case 'launcher': return launcher(ctx, parsed, options)
@@ -17,6 +17,8 @@ import { assertTargetEnabled, assertValidApp, discoverApps, resolveRequestedApp,
17
17
  import { buildRp2350, flashRp2350, rp2350BuildDir } from '../rp2350/adapter.mjs'
18
18
  import { runXbox } from '../xbox/adapter.mjs'
19
19
  import { success } from '../report.mjs'
20
+ import {runLinux} from '../linux/adapter.mjs'
21
+ import {deployLinux} from '../linux/deploy.mjs'
20
22
 
21
23
  // Every board-facing command: resolve the alias, pick the adapter, run.
22
24
 
@@ -101,7 +103,7 @@ function io(parsed, options) {
101
103
  // without one (its script-mode pass would otherwise analyze a directory), so
102
104
  // those adapters need an app even for --configure-only; the geaos adapter has
103
105
  // app-less actions.
104
- const appRequiredAdapters = new Set(['esp32-idf', 'rp2350-pico', 'xbox-uwp'])
106
+ const appRequiredAdapters = new Set(['esp32-idf', 'rp2350-pico', 'xbox-uwp', 'linux-native'])
105
107
 
106
108
  function requireAppForAdapter(ctx, parsed, selection, app) {
107
109
  if (app || !appRequiredAdapters.has(selection.adapter)) return app
@@ -121,6 +123,8 @@ export async function buildCommand(ctx, parsed, rest, options) {
121
123
  const base = io(parsed, options)
122
124
  const env = createChildEnv(ctx, base.env)
123
125
  switch (selection.adapter) {
126
+ case 'linux-native':
127
+ return runLinux({app,env,dryRun:base.dryRun,stdout:base.stdout})
124
128
  case 'xbox-uwp':
125
129
  return runXbox({ app, action: 'build', env, dryRun: base.dryRun, stdout: base.stdout })
126
130
  case 'esp32-idf': {
@@ -235,8 +239,19 @@ async function usbAppUpdate({ selection, image, appLabel, env, stdout, stderr })
235
239
  return true
236
240
  }
237
241
  }
238
- stderr(`USB app update failed: ${error.message}. Falling back to the ROM downloader (hold BOOT while powering on).`)
239
- return false
242
+ if (error.noApp) {
243
+ stderr('No running gea app answered on USB; falling back to the ROM downloader (hold BOOT while powering on).')
244
+ return false
245
+ }
246
+ // The app answered but the install failed (already retried once after a
247
+ // console resync). Falling into the ROM downloader here would retry
248
+ // forever on a board that needs BOOT to enter it, so stop and say so.
249
+ fail(
250
+ `USB app update of '${appLabel}' failed: ${error.message}. ` +
251
+ (error.uploaded ? 'The image was sent but the board did not come back running it. ' : 'The running app was left in place. ') +
252
+ 'Run gea flash again, or pass --manual-boot to use the ROM downloader (hold BOOT while powering on).',
253
+ ExitCode.deployFailed
254
+ )
240
255
  } finally {
241
256
  if (device) await device.close().catch(() => {})
242
257
  }
@@ -250,7 +265,7 @@ async function usbAppAnswers({ selection, appLabel, env }) {
250
265
  try {
251
266
  port = resolveUsbSerialPort({ serial: selection.usbSerial }, { env })
252
267
  } catch {}
253
- if (port && serialPortPresent(port)) return false
268
+ if (port && serialPortPresent(port, env)) return false
254
269
  const deadline = Date.now() + 30000
255
270
  while (Date.now() < deadline) {
256
271
  let device
@@ -272,6 +287,15 @@ export async function flashCommand(ctx, parsed, rest, options, { monitor = false
272
287
  const base = io(parsed, options)
273
288
  const env = createChildEnv(ctx, base.env)
274
289
  switch (selection.adapter) {
290
+ case 'linux-native': {
291
+ if (monitor) fail('Linux native run/monitor is not yet supported; use gea flash and the transaction receipt.', ExitCode.usage)
292
+ if (option(parsed,'host','')) fail('Linux deployment uses only the registered SSH identity; --host is refused.', ExitCode.usage)
293
+ const action=flag(parsed,'inspect-transaction')?'inspect':flag(parsed,'rollback')?'rollback':'deploy'
294
+ if(flag(parsed,'inspect-transaction')&&flag(parsed,'rollback'))fail('Select inspection or rollback, not both.',ExitCode.usage)
295
+ if(action!=='deploy'&&!option(parsed,'transaction',''))fail('Explicit --transaction is required for inspection/rollback.',ExitCode.usage)
296
+ const app=optionalApp(ctx,parsed,rest,selection,{required:true})
297
+ return deployLinux({app,selection,env,action,dryRun:base.dryRun,stdout:base.stdout,authorizationFile:option(parsed,'authorization',''),...(option(parsed,'transaction','') ? {transaction:option(parsed,'transaction')} : {})})
298
+ }
275
299
  case 'xbox-uwp': {
276
300
  const app = optionalApp(ctx, parsed, rest, selection, { required: true })
277
301
  return runXbox({ app, action: 'deploy', env, host: option(parsed, 'host', '') || selection.otaHost,
@@ -434,7 +458,7 @@ export async function screenshotCommand(ctx, parsed, rest, options) {
434
458
  const devctlUsage = `gea devctl <verb> [args] [--board <alias>] [--transport auto|usb|wifi]
435
459
 
436
460
  Verbs (USB, GEADEV protocol):
437
- ping | app | state | mem | summary | i2cscan | reboot
461
+ ping | app | state | mem | summary | i2cscan | netdiag | taskstats | reboot
438
462
  node <class> hit <x> <y> tap <x> <y> [holdMs]
439
463
  drag <x1> <y1> <x2> <y2> [steps] [delayMs] swipe <x> <y1> <y2>
440
464
  back key <code> notify <text>
@@ -547,6 +571,20 @@ export async function devctlCommand(ctx, parsed, rest, options) {
547
571
  case 'mem': print(await geadev.mem(d)); break
548
572
  case 'summary': print(await geadev.summary(d)); break
549
573
  case 'i2cscan': print(await geadev.i2cScan(d)); break
574
+ case 'netdiag':
575
+ case 'taskstats': {
576
+ const command = verb.toUpperCase()
577
+ // Keep the driver's unprefixed diagnostic lines inside the report,
578
+ // while ignoring unrelated console output before its BEGIN marker.
579
+ const { begin, lines } = await d.collect(`GEADEV ${command}`, {
580
+ begin: `GEADEV:${command} BEGIN`,
581
+ data: '\0',
582
+ end: `GEADEV:${command} END`,
583
+ timeoutMs: 8000
584
+ })
585
+ print([begin, ...lines].join('\n'))
586
+ break
587
+ }
550
588
  case 'reboot': print(await geadev.reboot(d)); break
551
589
  case 'node': need(1); print(await geadev.node(d, args[0])); break
552
590
  case 'hit': need(2); print(await geadev.hit(d, num(args[0], 'x'), num(args[1], 'y'))); break
@@ -1,3 +1,5 @@
1
+ import fs from 'node:fs'
2
+ import {validateLinuxBoard} from '../linux/deploy.mjs'
1
3
  import { flag, option } from '../args.mjs'
2
4
  import {
3
5
  boardConfigOrigins,
@@ -20,6 +22,7 @@ export const boardsUsage = `gea boards <subcommand> [--global | --local]
20
22
  list [--json] every alias, with the file it lives in
21
23
  show <alias> [--json]
22
24
  add register a board (guided; gea setup)
25
+ add <alias> --linux-config <file> register reviewed native Linux SSH/profile
23
26
  set <alias> <key> <value> edit one field; an empty value removes it
24
27
  remove <alias>
25
28
  rename <alias> <new-alias>
@@ -234,6 +237,18 @@ export async function boardsCommand(ctx, parsed, rest, options) {
234
237
  return 0
235
238
  }
236
239
 
240
+ if (sub === 'add' && option(parsed,'linux-config','')) {
241
+ const name=rest[1]
242
+ if(!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(name||'')) fail('A valid new Linux board alias is required.',ExitCode.usage)
243
+ if(boards[name]) fail(`Board '${name}' already exists; registration never repurposes it.`,ExitCode.usage)
244
+ const entry=JSON.parse(fs.readFileSync(option(parsed,'linux-config'),'utf8'))
245
+ validateLinuxBoard(entry)
246
+ const file=boardConfigWritePath(ctx,{scope:writeScope(parsed)})
247
+ updateBoardFile(file,current=>{current[name]=entry;return current})
248
+ success(options.stdout,`Registered Linux board '${name}' in ${file}; no connection opened`)
249
+ return 0
250
+ }
251
+
237
252
  if (sub === 'add') {
238
253
  const { runSetupWizard } = await import('../setup-wizard.mjs')
239
254
  return runSetupWizard(ctx, parsed, options)
@@ -251,7 +266,9 @@ export async function boardsCommand(ctx, parsed, rest, options) {
251
266
  // Moving an alias between tiers with --global/--project copies the
252
267
  // merged entry so the edit lands on a complete board, not a fragment.
253
268
  const base = current[name] ?? structuredClone(boards[name])
254
- current[name] = setFieldPath(base, keyPath, value)
269
+ const updated=setFieldPath(base, keyPath, value)
270
+ if(base.adapter==='linux-native'||updated.adapter==='linux-native') validateLinuxBoard(updated)
271
+ current[name] = updated
255
272
  return current
256
273
  })
257
274
  if (scope && origins.get(name) && origins.get(name) !== file) {
@@ -2,6 +2,7 @@ import path from 'node:path'
2
2
 
3
3
  import { flag } from '../args.mjs'
4
4
  import { boardConfigPath, boardConfigTiers, loadBoardConfig } from '../boards/config.mjs'
5
+ import { loadSerialport } from '../device/serial.mjs'
5
6
  import { ExitCode } from '../errors.mjs'
6
7
  import { findEspIdf, findIdfPythonEnv } from '../esp32/idf-env.mjs'
7
8
  import { exists } from '../fs-utils.mjs'
@@ -15,7 +16,7 @@ function packageExists(dir) {
15
16
 
16
17
  async function serialportAvailable() {
17
18
  try {
18
- await import('serialport')
19
+ await loadSerialport()
19
20
  return true
20
21
  } catch {
21
22
  return false