rnxsim 0.1.369 → 0.1.370

package/cli/commands/debug.ts

@@ -20,6 +20,7 @@
 
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import { printBridgeFailureDiagnostics } from '../bridge-diagnostics'
+import { rethrowIfExit, rnxExit } from '../run-rnx'
 import {
   createBridgeFromParsed,
   evalInBridge,
@@ -399,7 +400,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
 
   if (!subcommand || args.includes('--help') || args.includes('-h')) {
     printHelp()
-    process.exit(0)
+    rnxExit(0)
   }
 
   const wsPort = parsed.wsPort
@@ -438,7 +439,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
           console.error(
             `  usage: rnx debug enable <channel[,channel,...]>\n  known: ${KNOWN_CHANNELS.join(', ')}`,
           )
-          process.exit(1)
+          rnxExit(1)
         }
         const active = await setDebugChannels(bridge, 'enable', channels)
         console.log(fmt({ active }, pretty))
@@ -456,7 +457,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
         const channel = rest[0]
         if (!channel) {
           console.error('  usage: rnx debug toggle <channel>')
-          process.exit(1)
+          rnxExit(1)
         }
         const result = await call(
           bridge,
@@ -516,7 +517,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
         const b = rest[1]
         if (!a || !b) {
           console.error('  usage: rnx debug diff <labelA> <labelB>')
-          process.exit(1)
+          rnxExit(1)
         }
         // Maps don't serialize — project added/removed/changed arrays only
         const code = `(() => {
@@ -557,7 +558,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
               '  zero draws means either nothing on screen is an image, or the audit\n' +
               '  is not attached to the surface that paints.',
           )
-          process.exit(2)
+          rnxExit(2)
         }
         const under = report.rows.filter(
           (row) => row.shortfall !== null && row.shortfall < minimum,
@@ -567,7 +568,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
         } else {
           printImageAudit(report, args.includes('--all') ? report.rows : under, minimum)
         }
-        if (under.length > 0) process.exit(1)
+        if (under.length > 0) rnxExit(1)
         break
       }
 
@@ -578,7 +579,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
           console.log(fmt(result, pretty))
         } else {
           console.error('  usage: rnx debug find <sheets|portals|boundaries>')
-          process.exit(1)
+          rnxExit(1)
         }
         break
       }
@@ -596,7 +597,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
             console.error(
               '  usage: rnx debug trace anim <on|off|status|clear|<id>> [id|limit]',
             )
-            process.exit(1)
+            rnxExit(1)
           }
           if (sub === 'on') {
             const raw = rest[2] ?? 'all'
@@ -604,7 +605,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
             const target: number | 'all' = raw === 'all' ? 'all' : Number(raw)
             if (target !== 'all' && !Number.isFinite(target)) {
               console.error(`  invalid target: ${raw}`)
-              process.exit(1)
+              rnxExit(1)
             }
             await callTestBridge(bridge, 'enableAnimationTrace', target, limit)
             const listed = await callTestBridge(bridge, 'listAnimationTraces')
@@ -616,7 +617,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
             const target: number | 'all' = raw === 'all' ? 'all' : Number(raw)
             if (target !== 'all' && !Number.isFinite(target)) {
               console.error(`  invalid target: ${raw}`)
-              process.exit(1)
+              rnxExit(1)
             }
             await callTestBridge(bridge, 'disableAnimationTrace', target)
             console.log(fmt({ disabled: target }, pretty))
@@ -633,7 +634,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
           const id = Number(sub)
           if (!Number.isFinite(id)) {
             console.error(`  invalid id: ${sub}`)
-            process.exit(1)
+            rnxExit(1)
           }
           const limit = rest[2] ? Number(rest[2]) : undefined
           const samples = await callTestBridge(bridge, 'getAnimationTrace', id, limit)
@@ -642,7 +643,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
         }
         if (traceTarget !== 'shell') {
           console.error('  usage: rnx debug trace <shell|anim> [args]')
-          process.exit(1)
+          rnxExit(1)
         }
         if (!traceCommand || /^[0-9]+$/.test(traceCommand)) {
           const recentLimit = traceCommand ? Number(traceCommand) : 50
@@ -674,7 +675,7 @@ export async function runDebug(args: string[], opts: DebugOptions) {
         console.error(
           '  usage: rnx debug trace shell [on [limit]|off|status|clear|recentLimit]',
         )
-        process.exit(1)
+        rnxExit(1)
       }
 
       case 'record': {
@@ -702,16 +703,17 @@ export async function runDebug(args: string[], opts: DebugOptions) {
       default:
         console.error(`  unknown subcommand: ${sub}`)
         printHelp()
-        process.exit(1)
+        rnxExit(1)
     }
   } catch (err: any) {
+    rethrowIfExit(err)
     console.error(`  debug failed: ${err.message}`)
     await printBridgeFailureDiagnostics(bridge, {
       errorsCommand: `rnx get errors 5${simHint}`,
       warningsCommand: `rnx get warnings 5${simHint}`,
       requestsCommand: `rnx get requests 5${simHint}`,
     })
-    process.exit(1)
+    rnxExit(1)
   } finally {
     bridge.close()
   }

package/cli/commands/detox.ts

@@ -18,6 +18,7 @@ import { dirname, resolve, join, relative } from 'path'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { resolveCliAuth } from '../auth'
 import { registerRun, shouldRegisterRun } from '../run-registry'
+import { rnxExit } from '../run-rnx'
 import { discoverSootsimUrl } from './flow'
 import { resolveDefaultUploadOrigin } from './upload'
 
@@ -57,7 +58,7 @@ expected port. disable with --no-launch if you're managing the shell yourself.
 export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise<void> {
   if (args.includes('--help') || args.includes('-h')) {
     console.log(HELP)
-    process.exit(0)
+    rnxExit(0)
   }
 
   if (args[0] === 'init') {
@@ -125,7 +126,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
       `  error: no detox tests found. expected one of: ${detoxDirs.join(', ')}\n` +
         `  run 'rnx detox init' to scaffold a starter suite.`,
     )
-    process.exit(1)
+    rnxExit(1)
   }
 
   // auto-launch: make sure a sootsim shell is reachable before running jest.
@@ -278,7 +279,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     })
     if (run) console.log(`  run: ${run.id}`)
   }
-  process.exit(code)
+  rnxExit(code)
 }
 
 type JestRunSummary = {
@@ -410,5 +411,5 @@ describe('example', () => {
   console.log(`\n  next:`)
   console.log(`    rnx detox        # run the sample`)
   console.log(`    rnx detox --watch`)
-  process.exit(0)
+  rnxExit(0)
 }

package/cli/commands/device.ts

@@ -4,6 +4,7 @@ import {
   listSelectableDeviceModels,
   type DeviceModel,
 } from 'sootsim-engine/settings'
+import { rnxExit } from '../run-rnx'
 import {
   callInBridge,
   createBridgeFromParsed,
@@ -74,7 +75,7 @@ async function readCurrentDevice(
 export async function runDeviceCommand(args: string[], opts: DeviceCommandOptions) {
   if (args.includes('--help') || args.includes('-h')) {
     usage()
-    process.exit(0)
+    rnxExit(0)
   }
 
   const subcommand = args[0]
@@ -83,7 +84,7 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     const current = await readCurrentDevice(parsed)
     if (!current) {
       console.error('  error: could not read current device from the target sim')
-      process.exit(1)
+      rnxExit(1)
     }
     console.log(
       `  ${current.model}  ${current.width}x${current.height} pt  ${current.width * current.scale}x${current.height * current.scale} px  ${current.name}`,
@@ -101,12 +102,12 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     const model = args[1]
     if (!model) {
       console.error('  error: device set expects a model')
-      process.exit(1)
+      rnxExit(1)
     }
     if (!(model in devices)) {
       console.error(`  error: unknown device "${model}"`)
       console.error('  run `rnx device list` to see valid models')
-      process.exit(1)
+      rnxExit(1)
     }
     const parsed = parseBridgeCliArgs(args, { port: opts.port })
     const bridge = createBridgeFromParsed(parsed)
@@ -129,5 +130,5 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
 
   usage()
   console.error(`  unknown subcommand: ${subcommand}`)
-  process.exit(1)
+  rnxExit(1)
 }

package/cli/commands/electron.ts

@@ -7,6 +7,7 @@ import { ensureProfile } from '../../src/profiles'
 import { findDesktopCompanion } from '../desktop-companion'
 import { electronDriver } from '../drivers'
 import { confirm } from '../prompt'
+import { rnxExit } from '../run-rnx'
 import { buildShellUrl } from './control'
 import { printMissingCompanionHint } from './no-bridge-hint'
 
@@ -22,7 +23,7 @@ function parseInlinePort(args: string[]): number | undefined {
   const port = raw ? Number(raw) : Number.NaN
   if (!Number.isInteger(port) || port <= 0) {
     console.error(`  invalid --port value: ${raw || '(missing)'}`)
-    process.exit(1)
+    rnxExit(1)
   }
   return port
 }
@@ -53,14 +54,14 @@ examples:
   rnx desktop --port 5173
   rnx desktop --profile qa
 `)
-    process.exit(0)
+    rnxExit(0)
   }
 
   const profileArg = args.find((_, i) => args[i - 1] === '--profile')
   const ephemeralProfile = args.includes('--ephemeral')
   if (profileArg && ephemeralProfile) {
     console.error('  rnx desktop: --profile cannot be combined with --ephemeral')
-    process.exit(1)
+    rnxExit(1)
   }
   const profileId = profileArg ? ensureProfile(profileArg).id : undefined
   let install = findDesktopCompanion()
@@ -76,7 +77,7 @@ examples:
       await runInstallDesktop(['--yes'])
       install = findDesktopCompanion()
     }
-    if (!install) process.exit(1)
+    if (!install) rnxExit(1)
   }
   console.log(`  launching ${install.path}`)
 
@@ -89,7 +90,7 @@ examples:
   })
   if (!result.launched) {
     console.error(`  ${result.message}`)
-    process.exit(1)
+    rnxExit(1)
   }
   console.log(`  ${result.message}`)
 }

package/cli/commands/flow.ts

@@ -23,6 +23,7 @@ import {
   keepFlowCandidate,
   startFlowSession,
 } from '../flow-session'
+import { rnxExit } from '../run-rnx'
 import { createBridge, createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
 import {
   buildShellUrl,
@@ -176,13 +177,13 @@ flow extension:
     path: marketing/hero
     withFrame: true
 `)
-    process.exit(0)
+    rnxExit(0)
   }
 
   const flowPath = args[0]
   if (!fs.existsSync(flowPath)) {
     console.error(`  error: ${flowPath} not found`)
-    process.exit(1)
+    rnxExit(1)
   }
 
   const getFlag = (name: string) => args.find((_, i) => args[i - 1] === name)
@@ -240,7 +241,7 @@ flow extension:
     : ''
   if (previewBillingKind && previewBillingKind !== 'test_run') {
     console.error(`  error: invalid --billing-kind: ${previewBillingKind}`)
-    process.exit(1)
+    rnxExit(1)
   }
   const replaceArgs = args.flatMap((arg, index) =>
     args[index - 1] === '--replace' ? ['--replace', arg] : [],
@@ -271,7 +272,7 @@ flow extension:
   const { frontmatter, steps } = parseFlowFile(flowContent)
   if (steps.length === 0) {
     console.error('  error: flow file must contain a YAML array of steps')
-    process.exit(1)
+    rnxExit(1)
   }
   const targetDevice = deviceOverride || frontmatter.device || ''
   const targetTheme = frontmatter.theme || ''
@@ -323,7 +324,7 @@ flow extension:
     console.error(
       '  error: desktop companion not found. install or build it first with `bun run build:electron`',
     )
-    process.exit(1)
+    rnxExit(1)
   }
 
   const mode = wantElectron ? 'desktop companion' : 'bridge'
@@ -371,7 +372,7 @@ flow extension:
     const discovered = await discoverSootsimUrl()
     if (!discovered) {
       console.error('  error: no current sim and no sootsim target found')
-      process.exit(1)
+      rnxExit(1)
     }
     openTarget = discovered
   }
@@ -934,7 +935,7 @@ async function runFlowSession(args: string[]) {
       const result = keepFlowCandidate()
       if (!result.active) {
         console.error('  no active flow draft — run `sootsim maestro start` first')
-        process.exit(1)
+        rnxExit(1)
       }
       if (!result.kept) {
         console.log('  no pending action to keep')
@@ -963,7 +964,7 @@ async function runFlowSession(args: string[]) {
       )
       if (!result.active) {
         console.error('  no active flow draft — run `sootsim maestro start` first')
-        process.exit(1)
+        rnxExit(1)
       }
       if (!result.valid) {
         console.error('  flow draft is not valid:')
@@ -971,7 +972,7 @@ async function runFlowSession(args: string[]) {
         console.error(
           '  draft preserved — keep at least one real interaction or run `sootsim maestro start` to reset',
         )
-        process.exit(1)
+        rnxExit(1)
       }
 
       if (validate) {
@@ -1016,13 +1017,13 @@ async function runFlowSession(args: string[]) {
       const flowPath = args[1]
       if (!flowPath || flowPath.startsWith('-')) {
         console.error('  usage: sootsim maestro validate <path>')
-        process.exit(1)
+        rnxExit(1)
       }
       const issues = validateFlowFile(flowPath)
       if (issues.length > 0) {
         console.error(`  x ${flowPath} failed validation:`)
         for (const issue of issues) console.error(`    - ${issue}`)
-        process.exit(1)
+        rnxExit(1)
       }
       console.log(`  + ${flowPath} looks valid`)
       return

package/cli/commands/inspect/find.ts

@@ -1,4 +1,5 @@
 import { maybeHint } from '../../hints'
+import { rnxExit } from '../../run-rnx'
 import { inspectFind, inspectNodeCount, rankInteractive, tapCommandForNode } from './core'
 import { printJson, wantsJson } from './shared'
 import type { WsBridge } from '../../ws-bridge'
@@ -56,7 +57,7 @@ export async function runFindSubcommand(opts: {
         '<text> | --text <t> | --testid <id> | --role <r> | --type <t> | --pressable | --visible | --interactive-targets',
       ),
     )
-    process.exit(1)
+    rnxExit(1)
   }
   const { mode, result } = found
   const jsonOut = wantsJson(args)

package/cli/commands/inspect/keyboard.ts

@@ -5,6 +5,7 @@
 // id (if any). reads from `__sootsimKeyboard.getLayout()`, which is
 // populated by shell-worker `keyboard.layout` broadcasts.
 
+import { rnxExit } from '../../run-rnx'
 import { inspectKeyboard } from './core'
 import type { WsBridge } from '../../ws-bridge'
 
@@ -16,7 +17,7 @@ export async function runKeyboardSubcommand(
 
   if ('error' in result) {
     console.error(result.error)
-    process.exit(1)
+    rnxExit(1)
   }
 
   if (opts.json) {

package/cli/commands/inspect/sleep.ts

@@ -1,3 +1,4 @@
+import { rnxExit } from '../../run-rnx'
 import { sleep } from './shared'
 
 export async function runSleepSubcommand(opts: {
@@ -7,7 +8,7 @@ export async function runSleepSubcommand(opts: {
   const seconds = opts.positional[1] ? Number(opts.positional[1]) : 0.5
   if (!Number.isFinite(seconds) || seconds < 0) {
     console.error(opts.inspectUsage('sleep', '[seconds]'))
-    process.exit(1)
+    rnxExit(1)
   }
   await sleep(seconds * 1000)
   console.log(`  slept ${seconds}s`)

package/cli/commands/inspect/wait-event.ts

@@ -20,6 +20,7 @@
 // human-paced UI events we care about and stays compatible with the
 // existing query surface.
 
+import { rnxExit } from '../../run-rnx'
 import type { WsBridge } from '../../ws-bridge'
 import type {
   SootSimTimelineEvent,
@@ -120,7 +121,7 @@ export async function runWaitEventSubcommand(opts: WaitEventOptions): Promise<vo
         '<kind> [--max-ms 5000] [--filter <substring>] [--equals <exact>] [--since now|cursor]',
       ),
     )
-    process.exit(1)
+    rnxExit(1)
   }
   if (!KNOWN_KINDS.has(kind)) {
     console.error(
@@ -171,7 +172,7 @@ export async function runWaitEventSubcommand(opts: WaitEventOptions): Promise<vo
       console.error(
         `  could not query timeline: ${result && 'error' in result ? result.error : 'unknown'}`,
       )
-      process.exit(1)
+      rnxExit(1)
     }
     const evts = result.result.events ?? []
     for (const ev of evts) {
@@ -206,5 +207,5 @@ export async function runWaitEventSubcommand(opts: WaitEventOptions): Promise<vo
       `  ⚠ wait event ${kind} timed out after ${elapsed}ms${filter ? ` (filter: ${filter})` : ''}${equals ? ` (equals: ${equals})` : ''}`,
     )
   }
-  process.exit(1)
+  rnxExit(1)
 }

package/cli/commands/inspect/wait-idle.ts

@@ -1,3 +1,4 @@
+import { rnxExit } from '../../run-rnx'
 import { resolveMaxMsFlag } from './core'
 import { waitForSootsimIdle } from './settling'
 import type { WsBridge } from '../../ws-bridge'
@@ -19,6 +20,6 @@ export async function runWaitIdleSubcommand(opts: {
     console.log(`  idle in ${elapsed}ms`)
   } else {
     console.error(`  ⚠ wait idle timed out after ${elapsed}ms (may still be animating)`)
-    process.exit(1)
+    rnxExit(1)
   }
 }

package/cli/commands/inspect/wait-ready.ts

@@ -1,3 +1,4 @@
+import { rnxExit } from '../../run-rnx'
 import { inspectWaitReady, resolveMaxMsFlag, waitReadyReason } from './core'
 import { waitForSootsimIdle } from './settling'
 import type { WsBridge } from '../../ws-bridge'
@@ -51,7 +52,7 @@ export async function runWaitReadySubcommand(opts: {
       console.error(
         `  ⚠ wait ready timed out after ${elapsedMs + idle.elapsed}ms — app mounted but did not settle (nodes: ${nodes}, targets: ${targets})`,
       )
-      process.exit(1)
+      rnxExit(1)
     }
     console.log(
       `  ready in ${elapsedMs + idle.elapsed}ms: ${nodes} nodes, ${targets} targets${liveFrameActive ? `, ${liveFrameChannels} live surfaces` : ''}`,
@@ -70,5 +71,5 @@ export async function runWaitReadySubcommand(opts: {
   console.error(
     `  ⚠ wait ready timed out after ${elapsedMs}ms — ${reason} (nodes: ${nodes}, targets: ${targets}, live surfaces: ${liveFrameActive ? liveFrameChannels : 0}, errors: ${errors})`,
   )
-  process.exit(1)
+  rnxExit(1)
 }

package/cli/commands/inspect/wait-selector.ts

@@ -1,3 +1,4 @@
+import { rnxExit } from '../../run-rnx'
 import { inspectWaitSelector } from './core'
 import type { WsBridge } from '../../ws-bridge'
 
@@ -14,7 +15,7 @@ export async function runWaitSelectorSubcommand(opts: {
   const testId = positional[1]
   if (!testId) {
     console.error(inspectUsage('selector', '<testid> [--max-ms 5000] [--gone]'))
-    process.exit(1)
+    rnxExit(1)
   }
   const maxMsIdx = args.indexOf('--max-ms')
   const timeoutMs =
@@ -32,7 +33,7 @@ export async function runWaitSelectorSubcommand(opts: {
       console.error(
         `  ⚠ wait selector #${testId} --gone timed out after ${elapsed ?? timeoutMs}ms (still present)`,
       )
-      process.exit(1)
+      rnxExit(1)
     }
     return
   }
@@ -45,6 +46,6 @@ export async function runWaitSelectorSubcommand(opts: {
     console.error(
       `  ⚠ wait selector #${testId} timed out after ${elapsed ?? timeoutMs}ms`,
     )
-    process.exit(1)
+    rnxExit(1)
   }
 }

package/cli/commands/inspect/wait.ts

@@ -1,4 +1,5 @@
 import { rememberFlowCandidate } from '../../flow-session'
+import { rnxExit } from '../../run-rnx'
 import { waitForSimReady } from './shared'
 
 export async function runWaitSubcommand(opts: {
@@ -19,7 +20,7 @@ export async function runWaitSubcommand(opts: {
   })
   if (!ready) {
     console.error(`  timed out waiting for sim reconnect`)
-    process.exit(1)
+    rnxExit(1)
   }
   ready.bridge.close()
   rememberFlowCandidate({