@@ -182,6 +182,15 @@ Firmware (ADR-370, cross-platform esptool):
182182 flash --port <p> --bundle <dir> [--variant ...] [--baud 460800] --confirm
183183 [--boot-log-seconds 15] [--allow-unverified] write flash, then capture boot evidence
184184
185+ Node config (YAML: ~/.ruview/nodes.yaml, see firmware/esp32-csi-node/nodes.example.yaml):
186+ node [plan] validate the config, list nodes, firmware + secrets plan
187+ node status read-only: live CSI per node + each node's :8032 status
188+ node apply [--port P | --all | --watch] [--confirm] bring the board (by MAC) to its config: config steps,
189+ default flash → provision WiFi/NVS → validate
190+ node apply --firmware-only [...] flash + validate; keeps WiFi/node settings
191+ at a terminal: shows the plan and asks "yes" per board; --confirm skips the
192+ question; pipes/--json without --confirm only print the plan
193+
185194Devices (ADR-373) — run on the machine the hardware is attached to:
186195 devices classify USB serial devices (ESP32, Realtek, mmWave, RPLIDAR)
187196 esp32 [--udp-port 5005] [--seconds 10] [--bind 0.0.0.0] receive + summarize ESP32 / Realtek RAC1 node UDP streams
@@ -224,6 +233,122 @@ Hosts implemented and tested locally: claude-code (-p), codex (exec)`);
224233 return 0 ;
225234}
226235
236+ /** `ruview node [plan|status|apply]` — declarative node config (node-config.js). */
237+ async function nodeConfig ( rest , flags ) {
238+ const action = rest [ 0 ] && ! rest [ 0 ] . startsWith ( '--' ) ? rest [ 0 ] : 'plan' ;
239+ if ( ! [ 'plan' , 'status' , 'apply' ] . includes ( action ) ) {
240+ console . error ( 'Usage: ruview node [plan|status|apply] [--config ~/.ruview/nodes.yaml] [--port P | --all | --watch] [--firmware-only] [--confirm] [--json]' ) ;
241+ return 2 ;
242+ }
243+ const flow = action === 'apply' && flags [ 'firmware-only' ] === true ? 'firmware' : 'apply' ;
244+ const [ fl , { OPERATOR_DEPS } , { captureEsp32 } ] = await Promise . all ( [ import ( './node-config.js' ) , tools ( ) , import ( './devices/esp32.js' ) ] ) ;
245+ const asJson = flags . json === true || ! process . stdout . isTTY ;
246+ const out = ( kind , res ) => ( asJson ? pjson ( res ) : console . log ( fl . formatNodes ( kind , res ) ) ) ;
247+ let config ;
248+ try {
249+ config = fl . loadNodeConfig ( typeof flags . config === 'string' ? flags . config : fl . DEFAULT_CONFIG_PATH ) ;
250+ } catch ( e ) {
251+ if ( ! ( e instanceof fl . NodeConfigError ) ) throw e ;
252+ out ( 'error' , { ok : false , reason : e . reason , detail : e . message , errors : e . errors } ) ;
253+ return 2 ;
254+ }
255+ // cwd first (an explicit checkout wins), then the checkout this CLI ships in,
256+ // so `ruview node` works from any directory.
257+ const repoRoot = OPERATOR_DEPS . findRepoRoot ( ) || OPERATOR_DEPS . findRepoRoot ( ROOT ) ;
258+ const tty = process . stderr . isTTY && ! asJson ;
259+ const deps = {
260+ exec : OPERATOR_DEPS . exec , python : OPERATOR_DEPS . python , fetch : OPERATOR_DEPS . fetch ,
261+ capture : ( args ) => captureEsp32 ( args ) , repoRoot, env : process . env ,
262+ log : ( msg ) => { if ( tty ) process . stderr . write ( ` … ${ msg } \n` ) ; } ,
263+ } ;
264+
265+ if ( action === 'plan' ) { const res = fl . planNodes ( config , { repoRoot } ) ; out ( 'plan' , res ) ; return res . ok ? 0 : 1 ; }
266+ if ( action === 'status' ) {
267+ const res = await withProgress ( `Listening on UDP :${ config . aggregator . port } ` , config . validate . udp_secs , ( ) => fl . nodeStatus ( config , deps ) ) ;
268+ out ( 'status' , res ) ; return res . ok ? 0 : 1 ;
269+ }
270+
271+ // apply: one port, every ESP32 candidate (--all), or each new one (--watch).
272+ // --confirm writes without asking. Otherwise a person at a terminal sees the
273+ // plan and must type yes; pipes/--json/MCP only ever get the plan (fail closed).
274+ const confirm = flags . confirm === true ;
275+ const interactive = ! confirm && ! asJson && process . stdin . isTTY === true && process . stderr . isTTY === true ;
276+ const askYes = async ( question ) => {
277+ const { createInterface } = await import ( 'node:readline/promises' ) ;
278+ const rl = createInterface ( { input : process . stdin , output : process . stderr } ) ;
279+ try { return / ^ ( y | y e s ) $ / i. test ( ( await rl . question ( question ) ) . trim ( ) ) ; }
280+ catch { return false ; } // Ctrl+C / closed stdin = no
281+ finally { rl . close ( ) ; }
282+ } ;
283+ const one = async ( port ) => {
284+ if ( confirm ) {
285+ const res = await fl . applyBoard ( config , { port, flow, confirm : true } , deps ) ;
286+ out ( action , res ) ;
287+ return res . ok ;
288+ }
289+ const plan = await fl . applyBoard ( config , { port, flow, confirm : false } , deps ) ;
290+ if ( interactive && plan . ok ) delete plan . next ;
291+ out ( action , plan ) ;
292+ if ( ! plan . ok || ! interactive ) return plan . ok ;
293+ const parts = plan . steps . filter ( ( x ) => [ 'flash' , 'wifi' ] . includes ( x ) ) . map ( ( x ) => ( x === 'flash' ? 'firmware' : 'WiFi/node settings' ) ) ;
294+ const what = `write ${ parts . join ( ' + ' ) || 'nothing' } to` ;
295+ if ( ! ( await askYes ( ` ? ${ what } ${ plan . mac } (node ${ plan . node_id } ) on ${ port } ? Type yes to continue [y/N] ` ) ) ) {
296+ console . error ( ' skipped — nothing was written' ) ;
297+ return true ;
298+ }
299+ const res = await fl . applyBoard ( config , { port, flow, confirm : true ,
300+ expectedIdentity : { mac : plan . mac , nodeId : plan . node_id } } , deps ) ;
301+ out ( action , res ) ;
302+ return res . ok ;
303+ } ;
304+ const candidates = async ( ) => {
305+ const { scanDevices } = await import ( './devices/registry.js' ) ;
306+ const scan = await scanDevices ( OPERATOR_DEPS ) ;
307+ if ( ! scan . ok ) {
308+ // Name the interpreter: an unrelated active venv shadowing python3 is the usual cause.
309+ const py = OPERATOR_DEPS . python ( ) || 'python3' ;
310+ throw new fl . NodeConfigError ( scan . reason , scan . reason === 'pyserial_missing'
311+ ? `${ py } has no pyserial; run \`${ py } -m pip install pyserial esptool\` or put a venv that has them first on PATH`
312+ : ( scan . remedy || 'serial scan failed' ) ) ;
313+ }
314+ return scan . devices . filter ( ( d ) => d . likelyRoles . includes ( 'esp32' ) ) . map ( ( d ) => d . port ) ;
315+ } ;
316+ try {
317+ if ( typeof flags . port === 'string' ) return ( await one ( flags . port ) ) ? 0 : 1 ;
318+ if ( flags . watch === true ) {
319+ if ( ! confirm && ! interactive ) { console . error ( 'node: --watch needs a terminal (asks per board) or --confirm' ) ; return 2 ; }
320+ const done = new Set ( ) ;
321+ let stop = false ; let failures = 0 ;
322+ process . once ( 'SIGINT' , ( ) => { stop = true ; } ) ;
323+ console . error ( `Watching for ESP32 boards (${ flow } ). Plug them in one at a time; Ctrl+C to finish.` ) ;
324+ while ( ! stop ) {
325+ const ports = await candidates ( ) ;
326+ for ( const p of done ) if ( ! ports . includes ( p ) ) done . delete ( p ) ; // unplugged → socket reusable
327+ const next = ports . find ( ( p ) => ! done . has ( p ) ) ;
328+ if ( ! next ) { await new Promise ( ( r ) => setTimeout ( r , 1000 ) ) ; continue ; }
329+ await new Promise ( ( r ) => setTimeout ( r , 1000 ) ) ; // let the port settle
330+ if ( ! ( await one ( next ) ) ) failures += 1 ;
331+ done . add ( next ) ;
332+ console . error ( '→ unplug it and plug in the next board' ) ;
333+ }
334+ return failures ? 1 : 0 ;
335+ }
336+ const ports = await candidates ( ) ;
337+ if ( flags . all === true ) {
338+ if ( ! ports . length ) { console . error ( 'node: no ESP32 candidates found (ruview devices)' ) ; return 1 ; }
339+ let ok = true ;
340+ for ( const p of ports ) ok = ( await one ( p ) ) && ok ;
341+ return ok ? 0 : 1 ;
342+ }
343+ if ( ports . length !== 1 ) { console . error ( `node: found ${ ports . length } ESP32 candidates (${ ports . join ( ', ' ) || 'none' } ); pass --port, --all or --watch` ) ; return 2 ; }
344+ return ( await one ( ports [ 0 ] ) ) ? 0 : 1 ;
345+ } catch ( e ) {
346+ if ( ! ( e instanceof fl . NodeConfigError ) ) throw e ;
347+ out ( 'error' , { ok : false , reason : e . reason , detail : e . message } ) ;
348+ return 1 ;
349+ }
350+ }
351+
227352/** tiny flag parser: --k v / --k=v / --flag (boolean) */
228353function parseFlags ( rest ) {
229354 const f = { } ;
@@ -291,6 +416,7 @@ export async function run(args, opts = {}) {
291416
292417 switch ( cmd ) {
293418 case 'doctor' : return doctor ( flags ) ;
419+ case 'node' : return nodeConfig ( rest , flags ) ;
294420 case 'skills' : console . log ( listSkills ( ) . join ( '\n' ) || '(none)' ) ; return 0 ;
295421 case 'skill' : {
296422 const n = rest [ 0 ] ;
0 commit comments