rnxsim 0.1.352 → 0.1.353

package/README.md

@@ -132,9 +132,10 @@ graph TD
 ```
 
 **The CLI process** (`cli/bin.ts`) parses argv and lazy-imports exactly one
-command module per run. Bare `rnx` discovers a running React Native development
-server and opens it directly. `rnx setup` remains the explicit path for
-repository preparation and the optional background daemon. `rnx open`
+command module per run. Bare `rnx` opens ConnectRN, whose simulator UI discovers
+running React Native development servers. The first human run offers the
+recommended background service and optional Desktop app, then opens the simulator
+before asking about private diagnostics or an optional repository install. `rnx open`
 ensures the engine runtime exists and starts a local foreground bridge when no
 daemon is reachable, then opens a `WsBridge` (`cli/ws-bridge.ts`) on **port
 7668** and sends JSON commands. Inspection/interaction verbs live in
@@ -200,15 +201,15 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 ## Getting started
 
 ```sh
-npx rnxsim           # discover your running app and open it in the simulator
+npx rnxsim          # open ConnectRN and choose a running app in the simulator
 rnx open /settings  # dispatch a React Native deep link into that app
 ```
 
 Start Metro, Expo, One, or another supported React Native development server
-the way you normally do, then run `npx rnxsim` from any directory. If one app is
-running, rnx opens it immediately. If several are running, a human terminal gets
-one short choice. CI and agents refuse to guess and print one explicit
-`rnx open <port>` command for each discovered app.
+the way you normally do, then run `npx rnxsim` from any directory. The simulator
+opens ConnectRN, which shows the available local apps and lets you connect one.
+Pass a target to `rnx open <port-or-url>` when a script or agent needs an explicit
+selection.
 
 The first `rnx open` launches an isolated Chrome for Testing sim. The CLI
 resolves Playwright from the app or CLI install, asks that exact package for
@@ -221,17 +222,17 @@ consume memory and CPU on shared machines.
 
 There is no required global or per-app install. Optional global installs can
 use `npm install --global rnxsim`, `bun add --global rnxsim`, or
-`pnpm add --global rnxsim`. `rnx setup` is optional machine/repository tuning:
-start your Metro, Expo, or One dev server the way you already do, then open it
-from the CLI. There is no iOS native build in the inner loop; Metro alone is
+`pnpm add --global rnxsim`. Start your Metro, Expo, or One dev server the way you
+already do, then open it from the CLI. There is no iOS native build in the inner loop; Metro alone is
 enough. The manifest bundle path and query remain authoritative. When both the
 discovery request and manifest target are loopback addresses, RNX keeps the
 loopback host that answered discovery so an IPv6-only listener is not reopened
 through an unreachable IPv4 address. `rnx open` starts a local bridge when no
-daemon is reachable; the guided setup installs the faster background daemon so
-later CLI commands reuse one server. A desktop GUI (Electron) is optional on
-top, via `rnx desktop
-install`. Native Electron windows created by `rnx open` belong to that CLI
+daemon is reachable. The background service is strongly recommended for local
+agent work because inspect, interaction, and test commands reuse one ready bridge
+and runtime. Enable it at any time with `rnx daemon install`; it is never required
+in CI. The packaged Desktop app is optional and available through first-run
+onboarding or `rnx desktop install`. Native Electron windows created by `rnx open` belong to that CLI
 session and close when the session exits; `rnx desktop` keeps the persistent
 desktop-app lifecycle. In Electron, `File > New Window`
 duplicates the focused simulator, while `File > New Simulator >` opens a new
@@ -257,7 +258,7 @@ To uninstall the machine daemon and cached runtimes, run
 `rnx daemon uninstall`. It stops current and legacy launchd / systemd
 services, removes daemon logs, and removes `~/.sootsim/` (runtimes, profiles,
 recordings, and lockfiles). It does not remove the optional
-`/Applications/sootsim.app` desktop bundle or macOS preference plist. To inspect
+`/Applications/rnx.app` desktop bundle or macOS preference plist. To inspect
 existing disk usage before uninstalling, run `rnx cleanup`; add `--apply`
 only after reviewing the preview.
 

package/cli/bin.ts

@@ -88,12 +88,15 @@ const isAutomaticCleanupWorker =
   parsed.command === 'cleanup' &&
   parsed.commandArgs.length === 1 &&
   parsed.commandArgs[0] === '--automatic-worker'
+const isBareWelcome = !parsed.command && parsed.commandArgs.length === 0
 
 if (
   !isAutomaticCleanupWorker &&
+  !isBareWelcome &&
   !parsed.help &&
   !parsed.version &&
   parsed.command !== 'config' &&
+  parsed.command !== 'setup' &&
   parsed.command !== 'telemetry'
 ) {
   const { ensurePrivacyChoice } = await import('./privacy')
@@ -169,8 +172,6 @@ async function scheduleAutomaticCleanup(): Promise<void> {
   }
 }
 
-// fast-exit helper: diagnostic error shapes are best-effort, but explicit exit
-// paths still give a permitted queued diagnostic a chance to drain.
 async function exitWithFlush(code: number): Promise<never> {
   const { flushCliTelemetry } = await import('./telemetry')
   await flushCliTelemetry()
@@ -228,8 +229,8 @@ if (device || theme) {
   settingsStore.apply(overrides)
 }
 
-// no command, no args: discover the running app and open it directly. explicit
-// `rnx setup` remains available for repository and background-service choices.
+// no command, no args: guide first-time machine setup, then open ConnectRN.
+// returning runs open ConnectRN directly; app discovery belongs inside it.
 if (!parsed.command && parsed.commandArgs.length === 0) {
   const { runWelcome } = await import('./commands/welcome')
   await exitWithFlush(await runWelcome())

package/cli/commands/control.ts

@@ -25,6 +25,7 @@ import {
   readActiveRuntime,
   readDaemonLockfile,
   readLiveRuntimeVersions,
+  readSimulatorDriverPreference,
   runtimeDir,
 } from '../../src/home-paths'
 import { applyHotMode } from '../../src/native-dev-bundle-url'
@@ -65,6 +66,7 @@ import {
   type BridgeSimInfo,
 } from '../ws-bridge'
 import { WAIT_READY_PROBE, readyProbeHasContent, type ReadyProbe } from './inspect/core'
+import { isAgentEnv } from './inspect/env'
 import type { DriverId, DriverLaunchResult } from '../drivers/types'
 
 interface ControlCommandOptions {
@@ -228,7 +230,7 @@ export async function ensureBridgeForOpen(
       (await canConnectToBridge(nextLock.bridgePort, 250))
     ) {
       console.error(
-        `  started local bridge on port ${nextLock.bridgePort}; run \`sootsim setup\` to install the background daemon`,
+        `  Started a local bridge on port ${nextLock.bridgePort}. Run \`rnx daemon install\` to keep it ready between commands.`,
       )
       return nextLock.bridgePort
     }
@@ -1219,6 +1221,7 @@ function printOpenedSim(
     | 'direct shell open'
     | 'current sim'
     | `${string} driver`,
+  quiet = false,
 ) {
   const [printableOpenUrl, printableSimUrl] = [openUrl, sim.url].map((value) => {
     if (!value) return value
@@ -1231,6 +1234,10 @@ function printOpenedSim(
     } catch {}
     return value
   })
+  if (quiet) {
+    console.log(`  Opened ConnectRN [${mode}]`)
+    return
+  }
   console.log(
     `  ${mode === 'current sim' ? 'loaded' : 'opened'}: ${printableOpenUrl} [${mode}]`,
   )
@@ -1428,6 +1435,7 @@ export async function runOpenCommand(
       '--hot',
       '--no-hmr',
       '--no-describe',
+      '--quiet',
     ],
     stripValueFlags: [
       '--base-url',
@@ -1440,6 +1448,7 @@ export async function runOpenCommand(
     ],
   })
   const requestedProfileId = args.find((_, i) => args[i - 1] === '--profile')
+  const quiet = args.includes('--quiet')
   const ephemeralProfile = args.includes('--ephemeral')
   // --cdp-port exposes Chrome's remote-debugging endpoint on the opened sim so
   // it can be cpu-profiled while bridge-driven (playwright driver only).
@@ -1548,7 +1557,13 @@ export async function runOpenCommand(
   }
   const driverId: DriverId = isDriverId(requestedDriverId)
     ? requestedDriverId
-    : 'playwright'
+    : process.env.CI === '1' ||
+        process.env.CI === 'true' ||
+        process.env.GITHUB_ACTIONS === 'true' ||
+        isAgentEnv() ||
+        !process.stdin.isTTY
+      ? 'playwright'
+      : readSimulatorDriverPreference() || 'playwright'
   const driverHeadless = resolveDriverHeadless(args, driverId)
   if (cdpPort && driverId !== 'playwright') {
     console.error('  rnx open: --cdp-port is only honored by the playwright driver')
@@ -1568,7 +1583,7 @@ export async function runOpenCommand(
     console.error('  rnx open: --hot and --no-hmr cannot be combined')
     process.exit(1)
   }
-  const hotMode = hotFlag ? true : noHmrFlag ? false : requestedDriverId !== 'playwright'
+  const hotMode = hotFlag ? true : noHmrFlag ? false : driverId !== 'playwright'
 
   // --device <model> seeds the device profile for the opened sim (stamped on
   // the engine URL, so both playwright and electron honor it). without it
@@ -1735,7 +1750,7 @@ export async function runOpenCommand(
             applySootSimConfigToUrl(resolvedBaseUrl, runtimeConfig),
             buildShellUrlOpts,
           ))
-        printOpenedSim(shellUrl, { ...targetSim, url: shellUrl }, 'current sim')
+        printOpenedSim(shellUrl, { ...targetSim, url: shellUrl }, 'current sim', quiet)
         await maybeDescribeAfterOpen(parsed.wsPort, targetSim.id, args)
         return parsed.wsPort
       }
@@ -1814,7 +1829,7 @@ export async function runOpenCommand(
   const match = outcome.sim
   saveCurrentSimId(match.id)
   signalDriverLaunchConnected(result)
-  printOpenedSim(openUrl, match, `${driver.name} driver`)
+  printOpenedSim(openUrl, match, `${driver.name} driver`, quiet)
   await maybeDescribeAfterOpen(parsed.wsPort, match.id, args)
   return parsed.wsPort
 }

package/cli/commands/daemon-mac-app.ts

@@ -142,7 +142,7 @@ function renderLauncherScript(
   const stdout = shellSingleQuote(logDir.stdout)
   const stderr = shellSingleQuote(logDir.stderr)
   return `#!/bin/sh
-# SootSim Daemon launcher — auto-generated by 'rnx setup'.
+# sootsim daemon launcher generated by 'rnx daemon install'.
 # launchd spawns this; we exec the real rnx invocation in place so
 # launchd tracks the daemon process, not the shell wrapper.
 #

package/cli/commands/daemon.ts

@@ -5,7 +5,7 @@
 // registration time, so `npm update -g sootsim` + `sootsim daemon restart`
 // picks up the upgrade without touching the plist/unit file.
 //
-// `daemonInstall` is shared by `sootsim setup` and the explicit
+// `daemonInstall` is shared by `rnx setup` and the explicit
 // `sootsim daemon install` machine-bootstrap path.
 //
 //   macOS:  ~/Library/LaunchAgents/dev.sootsim.daemon.plist (launchd)
@@ -656,7 +656,7 @@ async function daemonRestart() {
   if (process.platform === 'darwin') {
     const path = macPlistPath()
     if (!existsSync(path)) {
-      console.error('  daemon not registered — run `rnx setup`')
+      console.error('  daemon not registered. run `rnx daemon install`')
       process.exit(1)
     }
     const res = spawnSync(
@@ -674,7 +674,7 @@ async function daemonRestart() {
   if (process.platform === 'linux') {
     const path = linuxUnitPath()
     if (!existsSync(path)) {
-      console.error('  daemon not registered — run `rnx setup`')
+      console.error('  daemon not registered. run `rnx daemon install`')
       process.exit(1)
     }
     const res = spawnSync('systemctl', ['--user', 'restart', SERVICE_NAME_LINUX], {
@@ -696,7 +696,7 @@ async function daemonStart() {
   if (process.platform === 'darwin') {
     const path = macPlistPath()
     if (!existsSync(path)) {
-      console.error('  daemon not registered — run `rnx setup`')
+      console.error('  daemon not registered. run `rnx daemon install`')
       process.exit(1)
     }
     const res = spawnSync(
@@ -714,7 +714,7 @@ async function daemonStart() {
   if (process.platform === 'linux') {
     const path = linuxUnitPath()
     if (!existsSync(path)) {
-      console.error('  daemon not registered — run `rnx setup`')
+      console.error('  daemon not registered. run `rnx daemon install`')
       process.exit(1)
     }
     const res = spawnSync('systemctl', ['--user', 'start', SERVICE_NAME_LINUX], {
@@ -788,9 +788,7 @@ async function daemonLogs(rest: string[]) {
     const err = resolve(LOG_DIR, 'bridge.err.log')
     const present = [out, err].filter((p) => existsSync(p))
     if (present.length === 0) {
-      console.error(
-        `  no daemon logs yet at ${LOG_DIR} — run \`rnx setup\` to install the daemon`,
-      )
+      console.error(`  no daemon logs yet at ${LOG_DIR}. run \`rnx daemon install\``)
       process.exit(1)
     }
     const args = follow

package/cli/commands/install-desktop.ts

@@ -5,8 +5,8 @@
 //
 // fetches the right platform artifact from https://contrast.dev/api/electron-release/
 // and installs it into the OS-native location that findDesktopCompanion() looks for:
-//   macOS: ~/Applications/sootsim.app (or /Applications if writable)
-//   linux: ~/Applications/sootsim.AppImage
+//   macos: ~/Applications/rnx.app (or /Applications if writable)
+//   linux: ~/Applications/rnx.AppImage
 //   win:   spawns the NSIS installer
 //
 // post-install the electron-updater feed (same URL) handles upgrades inside the
@@ -27,6 +27,7 @@ import { tmpdir } from 'os'
 import { dirname, join, resolve } from 'path'
 import { findDesktopCompanion } from '../desktop-companion'
 import { confirm } from '../prompt'
+import { accent, bold, failure, muted, success, withSpinner } from '../ui'
 
 const DOWNLOAD_BASE = 'https://contrast.dev/api/electron-release'
 
@@ -122,7 +123,7 @@ function renderProgress(received: number, total: number | null): string {
   const totalMb = (total / (1024 * 1024)).toFixed(1)
   const barWidth = 24
   const filled = Math.round((pct / 100) * barWidth)
-  const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled)
+  const bar = accent('█'.repeat(filled)) + muted('░'.repeat(barWidth - filled))
   return `  ${bar} ${pct}%  ${mb} / ${totalMb} MB`
 }
 
@@ -169,7 +170,7 @@ async function installMacDmg(dmgPath: string): Promise<string> {
     mkdirSync(destRoot, { recursive: true })
   }
 
-  const appDest = join(destRoot, 'sootsim.app')
+  const appDest = join(destRoot, 'rnx.app')
   if (existsSync(appDest)) rmSync(appDest, { recursive: true, force: true })
 
   const copy = spawnSync('cp', ['-R', appSource, appDest])
@@ -193,7 +194,7 @@ async function installMacDmg(dmgPath: string): Promise<string> {
 async function installLinuxAppImage(appImagePath: string): Promise<string> {
   const destDir = resolve(process.env.HOME || '', 'Applications')
   mkdirSync(destDir, { recursive: true })
-  const dest = join(destDir, 'sootsim.AppImage')
+  const dest = join(destDir, 'rnx.AppImage')
   if (existsSync(dest)) rmSync(dest, { force: true })
   // copyFile + unlink instead of rename: /tmp and ~/Applications are
   // routinely on separate mounts in containers / VMs, where renameSync
@@ -217,17 +218,20 @@ async function installWindowsExe(exePath: string): Promise<string> {
       else rejectPromise(new Error(`installer exited with code ${code}`))
     })
   })
-  return exePath
+  const installed = findDesktopCompanion()
+  if (!installed) {
+    throw new Error('the installer finished but the rnx application was not registered')
+  }
+  return installed.path
 }
 
 export async function runInstallDesktop(args: string[]) {
   if (args.includes('--help') || args.includes('-h')) {
     console.log(`
-rnx desktop install — download and install the optional desktop GUI
+rnx desktop install
 
-the CLI + daemon are the canonical rnx surface; the GUI is optional.
-if you just want to drive a running metro/expo dev server from the
-terminal, you don't need this.
+Download and install the optional rnx Desktop app.
+The CLI works without it. Choose Desktop when you want a dedicated native window.
 
 usage:
   rnx desktop install [options]
@@ -253,28 +257,31 @@ examples:
 
   const existing = findDesktopCompanion()
   if (existing && !force) {
-    console.log(`  rnx desktop already installed at: ${existing.path}`)
-    console.log('  pass --force to reinstall.')
+    console.log(`  ${success('✓')} Desktop app is already installed at ${existing.path}`)
+    console.log(`  ${muted('Pass --force to reinstall.')}`)
     return
   }
 
   const target = detectTarget()
   if (!target) {
-    console.error(`  no desktop build available for ${process.platform}/${process.arch}.`)
     console.error(
-      '  supported: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64',
+      `  ${failure('×')} No desktop build is available for ${process.platform}/${process.arch}.`,
+    )
+    console.error(
+      '  Supported: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64',
     )
     process.exit(1)
   }
 
-  console.log(`  platform:  ${target.platform}`)
-  console.log(`  download:  ${target.url}`)
+  console.log(`  ${bold('Desktop app')}`)
+  console.log(`  Platform  ${target.platform}`)
+  console.log(`  Download  ${target.url}`)
   console.log()
 
   if (!skipConfirm) {
-    const ok = await confirm('download and install now?', true)
+    const ok = await confirm('Download and install now?', true)
     if (!ok) {
-      console.log('  cancelled.')
+      console.log(`  ${muted('Cancelled.')}`)
       return
     }
     console.log()
@@ -284,7 +291,7 @@ examples:
   const downloadPath = join(workDir, target.filename)
 
   let lastDraw = 0
-  process.stdout.write(`  downloading ${target.filename}...\n`)
+  process.stdout.write(`  Downloading ${target.filename}...\n`)
 
   try {
     await download({
@@ -302,36 +309,39 @@ examples:
   } catch (err) {
     rmSync(workDir, { recursive: true, force: true })
     const message = err instanceof Error ? err.message : String(err)
-    console.error(`\n  download failed: ${message}`)
+    console.error(`\n  ${failure('×')} Download failed: ${message}`)
     console.error(
-      `  the ${target.platform} desktop build may not be published yet, or your`,
+      `  The ${target.platform} desktop build may not be published yet, or your`,
     )
     console.error(
-      '  network blocked the request. check your connection and try again later;',
+      '  network blocked the request. Check your connection and try again later.',
     )
-    console.error('  the CLI + daemon work without the desktop app (run: rnx --help).')
+    console.error('  The CLI and daemon work without the desktop app. Run `rnx --help`.')
     process.exit(1)
   }
 
   if (process.stdout.isTTY) process.stdout.write('\n')
   const size = statSync(downloadPath).size
-  console.log(`  downloaded ${(size / (1024 * 1024)).toFixed(1)} MB`)
+  console.log(`  ${success('✓')} Downloaded ${(size / (1024 * 1024)).toFixed(1)} MB`)
   console.log()
-  console.log(`  installing...`)
 
   try {
-    const installedAt = await target.install(downloadPath)
-    console.log(`  installed: ${installedAt}`)
+    const installedAt = await withSpinner('Installing the desktop app', () =>
+      target.install(downloadPath),
+    )
+    console.log(`  Installed at ${installedAt}`)
   } catch (err) {
-    console.error(`  install failed: ${err instanceof Error ? err.message : String(err)}`)
-    console.error(`  keeping download at ${downloadPath} for manual install.`)
+    console.error(
+      `  ${failure('×')} Install failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    console.error(`  Keeping the download at ${downloadPath} for manual installation.`)
     process.exit(1)
   } finally {
     rmSync(workDir, { recursive: true, force: true })
   }
 
   console.log()
-  console.log('  next steps:')
-  console.log('    rnx desktop         launch the desktop app')
-  console.log('    rnx open <target>   open a demo or bundle in it')
+  console.log(`  ${bold('Ready')}`)
+  console.log('  rnx desktop         Launch the desktop app')
+  console.log('  rnx open <target>   Open a demo or bundle in it')
 }

package/cli/commands/no-bridge-hint.ts

@@ -9,8 +9,8 @@ export function printMissingCompanionHint() {
   console.error('  install the desktop app:')
   console.error('    rnx desktop install')
   console.error('')
-  console.error('  or run setup to install the background daemon:')
-  console.error('    rnx setup')
+  console.error('  or install the recommended background service:')
+  console.error('    rnx daemon install')
   console.error('')
 }
 
@@ -23,7 +23,7 @@ export function printMissingBridgeHint(port: number) {
     return
   }
   console.log('')
-  console.log('  run `rnx setup` to install the background daemon,')
+  console.log('  run `rnx daemon install` to enable the faster background service,')
   console.log('  or run `rnx serve` in another shell for a foreground bridge.')
 }
 

package/cli/commands/serve.ts

@@ -6,7 +6,7 @@
 // them; electron fetches renderer assets over http from the same port.
 //
 // run in the foreground (ctrl-c to stop). the persistent launchd/systemd
-// daemon installation is handled by `sootsim setup`.
+// daemon installation is handled by `rnx daemon install`.
 
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import {