rnxsim 0.1.380 → 0.1.382

package/README.md

@@ -1,21 +1,33 @@
 # rnx
 
-The public, publishable face of rnx: a CLI, two pairs of bundler plugins, a
-Detox/Maestro test surface, and a skills registry for driving a browser-native
-React Native simulator.
+The source owner for the standalone `rnx` executable and the public `rnxsim`
+integration library used to drive a browser-native React Native simulator.
 
 ## Overview
 
-`rnxsim` is everything you install to *talk to* an rnx instance — it
-contains **no rendering code**. The canvas engine (CanvasKit renderer, Yoga
-layout, iOS/Android shell chrome, Electron shell) lives in the private
-`sootsim-engine` workspace package and is shipped at runtime as a versioned
-tarball, fetched from the contrast.dev CDN and unpacked into `~/.rnx`.
-
-What this package gives you:
-
-- the `rnx` CLI — the primary debugging and automation surface (inspect the
-  UI tree, tap elements, capture flows, screenshot, record, run agents)
+The CLI and library are separate public artifacts. The recommended installer
+downloads one Bun-compiled `rnx` executable that needs no Node.js, npm, or Bun
+installation. The `rnxsim` npm package contains bundler plugins, testing
+drivers, and library exports, with no command-line binary.
+
+The executable updates itself with `rnx upgrade`. Successful interactive human
+commands refresh a cached stable CLI version in a detached process at most once
+every 20 hours. A newer version produces one short notice on stderr, once per
+version and no more than weekly. CI, agents, JSON output, pipes, and
+noninteractive commands stay silent. Set `RNX_UPDATE_CHECK=off` to disable the
+check and notice; `rnx version` checks explicitly, while `rnx --version` remains
+offline.
+
+Neither artifact contains rendering code. The canvas engine (CanvasKit
+renderer, Yoga layout, iOS/Android shell chrome, Electron shell) lives in the
+private `sootsim-engine` workspace package and is shipped at runtime as a
+versioned tarball, fetched from the contrast.dev CDN and unpacked into `~/.rnx`.
+
+What this workspace gives you:
+
+- the standalone `rnx` CLI source and binary build, which provides the primary
+  debugging and automation surface (inspect the UI tree, tap elements, capture
+  flows, screenshot, record, run agents)
 - `rnxsim/vite` and `rnxsim/metro` — bundler plugins that serve the installed
   engine runtime from your own dev server
 - `rnxsim/jump-to-source-babel` — an optional Babel plugin that annotates JSX
@@ -33,14 +45,14 @@ chrome, gesture + three-button nav, system UI/window metrics with cutout-safe
 insets) but is not full parity until the Android launch gates in the Contrast
 repo plan pass.
 
-## What's in this package (and what's not)
+## What's in each distribution
 
-| in `rnxsim` | in `sootsim-engine` (private, not published) |
-| --- | --- |
-| CLI, bridge client, drivers | CanvasKit renderer, Yoga layout |
-| bridge daemon host (`SootSimBridgeHost`) | iOS/Android shell chrome, home grid, app switcher |
-| vite/metro plugins, RN resolver, native stubs | Electron shell, wasm |
-| Detox/Maestro runners, screenshots, skills | the actual pixels |
+| standalone `rnx` executable | `rnxsim` npm package | private engine runtime |
+| --- | --- | --- |
+| CLI commands and bridge client | Vite and Metro plugins | CanvasKit renderer and Yoga layout |
+| bridge daemon host | SDK and bridge contracts | iOS/Android shell chrome, home grid, app switcher |
+| runtime, browser, and desktop launchers | Detox driver and Jest preset | Electron shell and wasm |
+| Maestro, screenshots, recording, skills | native-resolution helpers and skills registry | the actual pixels |
 
 The engine is delivered at runtime, never bundled into this package. A
 committed-but-unbuilt engine fix has no effect on a running sim until the
@@ -197,6 +209,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans `agent:event`/`session-status` pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | `src/host/agent-host.ts`, `src/agent-sessions.ts`, `src/attached-projects.ts`, `src/agent-daemon-client.ts` |
 | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: `/__server-scan` discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | `src/host/fetch-proxy-handler.ts`, `src/host/websocket-proxy.ts`, `scripts/dev-server-scanner.ts`, `src/dev-bundle-resolution.ts` |
 | runtime delivery + rnx home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. rnx binds it to `https://contrast.dev` and `~/.rnx/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts` |
+| standalone CLI delivery | Cached stable-version checks, bounded interactive notices, and verified atomic executable replacement. | `cli/cli-update.ts`, `cli/commands/upgrade.ts`, `cli/commands/version.ts`, `src/cli-version.ts` |
 | `rnxsim/vite` + `rnxsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.rnx/runtimes/<version>` so an app's own dev server can host the sim shell; either plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
 | `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `rnxsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/compat/src/stub-manifest.ts` |
 | skills registry | rnx agent skills (`rnx-setup`, `rnx-debug`, `rnx-test`, `rnx-visual`, and the generated `contrast` index) installable with `rnx skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
@@ -244,10 +257,13 @@ window for a selected device (same device list as the `Window >` menu).
 
 ### Privacy
 
-rnx does not phone home by default. On an unsigned-in first run, its only
-internet request is the runtime manifest/archive it is about to execute. The
-first human run asks once, defaults to no, and never prompts in a non-TTY shell,
-CI, or an agent. An automated first run is declined for that process without
+rnx sends no analytics, crash report, command event, app data, project data, or
+identity by default. An unsigned-in interactive run may request the runtime it
+is about to execute and the stable standalone CLI version document. The latter
+runs after the command in a detached process at most once every 20 hours and can
+be disabled with `RNX_UPDATE_CHECK=off`. The first human run asks once about
+bounded diagnostics, defaults to no, and never prompts in a non-TTY shell, CI,
+or an agent. An automated first run is declined for that process without
 consuming the later human choice. Legacy browser and Electron telemetry senders
 are removed rather than being enabled by this consent.
 
@@ -515,12 +531,12 @@ frame for quick art-direction passes.
 `<skill-name>/SKILL.md` layout used by Codex and Claude Code. The bundled
 skills cover setup, debugging/perf/accessibility, testing, visual review, and
 the generated `contrast` command index. The published CLI registry and generated
-website docs both come from `packages/sootsim-skills/`:
+website docs both come from `packages/rnx-skills/`:
 
 - `packages/sootsim/skills/contrast/SKILL.md` is generated from that registry
 - `src/features/site/docs/rnx/cli/*` is generated output, not hand-edited
 
-When command docs or examples drift, update `packages/sootsim-skills/` and run:
+When command docs or examples drift, update `packages/rnx-skills/` and run:
 
 ```sh
 bun run generate:sootsim-docs
@@ -545,6 +561,7 @@ verifies its sha256, and unpacks it under `~/.rnx`:
 ├── profiles/             persistent named app storage, without browser caches
 ├── electron/userData/    desktop app storage, with bounded browser caches
 ├── daemon.json           lockfile: pid, ports, active runtime, heartbeat
+├── cli-update.json       cached standalone CLI version and notice state
 ├── automatic-cleanup-v1.json  completed legacy cleanup generation
 └── config.json           user prefs: update channel, cdn origin override
 ```

package/cli/app-fonts.ts

@@ -124,7 +124,7 @@ export function discoverNativeLinkedAppFonts(opts: {
 
   // @react-native-vector-icons links fonts from its configured local font
   // directory and each installed icon package into the native app. those files
-  // never enter the metro module graph, so SootSim must stage them through the
+  // never enter the metro module graph, so rnx must stage them through the
   // same native-linked font wire as expo-font config-plugin assets. Font Awesome
   // Pro installs its licensed faces under the local directory rather than
   // publishing them in the npm package.

package/cli/bin.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-// sootsim CLI entry point. the full command and verb surface lives in the
-// registry at `packages/sootsim-skills/src/cli/meta.ts` — help output,
+// rnx CLI entry point. the full command and verb surface lives in the
+// registry at `packages/rnx-skills/src/cli/meta.ts` — help output,
 // website docs, and agent skills all read from there. do not duplicate
-// command listings in this file; run `sootsim --help` for the canonical
+// command listings in this file; run `rnx --help` for the canonical
 // surface.
 
 import { rnxPublicBrand } from '../src/public-brand'
@@ -11,6 +11,37 @@ import { parseArgs, TOP_LEVEL_RUNTIME_COMMANDS } from './parse-args'
 import { RnxExit } from './run-rnx'
 import { IS_STANDALONE } from './standalone'
 
+if (process.argv[2] === '__shell-init') {
+  const { renderRnxShellInit } = await import('./shell-init')
+  try {
+    process.stdout.write(renderRnxShellInit(process.argv[3] ?? ''))
+    process.exit(0)
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  }
+}
+
+if (process.argv[2] === '__cloud-confirm') {
+  try {
+    const [{ confirmCloudSimulator }, { readCloudSession }] = await Promise.all([
+      import('./cloud-client'),
+      import('./cloud-session'),
+    ])
+    const session = readCloudSession()
+    if (!session) throw new Error('RNX cloud confirmation has no shell session')
+    await confirmCloudSimulator(session)
+    process.exit(0)
+  } catch (error) {
+    process.stderr.write(
+      `RNX cloud confirmation failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`,
+    )
+    process.exit(1)
+  }
+}
+
 // `./help` is loaded lazily (only on help paths) — it statically pulls the full
 // CLI registry renderers and engine settings, which would otherwise add ~400ms
 // of eager chunk load to every command, including hot-path reads like
@@ -25,7 +56,7 @@ import { IS_STANDALONE } from './standalone'
 // don't paper over real bugs.
 function handleTopLevelError(err: unknown): never {
   const msg = err instanceof Error ? err.message : String(err)
-  // sootsim's known top-level errors are all single-line, narrow strings.
+  // rnx's known top-level errors are all single-line, narrow strings.
   // everything else gets the full stack so unexpected crashes still surface.
   const isKnownCliFailure =
     /^command timed out after \d+s$/.test(msg) ||
@@ -70,10 +101,24 @@ const isAutomaticCleanupWorker =
   parsed.command === 'cleanup' &&
   parsed.commandArgs.length === 1 &&
   parsed.commandArgs[0] === '--automatic-worker'
+const isCliUpdateWorker =
+  parsed.command === 'upgrade' &&
+  parsed.commandArgs.length === 1 &&
+  parsed.commandArgs[0] === '--check-worker'
 const isBareWelcome = !parsed.command && parsed.commandArgs.length === 0
 const isReadOnlyInvocation =
   parsed.version || parsed.help || parsed.commandArgs.includes('--dry-run')
 
+if (isCliUpdateWorker) {
+  if (IS_STANDALONE) {
+    try {
+      const { refreshCliUpdateCache } = await import('./cli-update')
+      await refreshCliUpdateCache()
+    } catch {}
+  }
+  process.exit(0)
+}
+
 if (
   !isAutomaticCleanupWorker &&
   !isBareWelcome &&
@@ -105,6 +150,25 @@ if (!isReadOnlyInvocation && parsed.command !== 'serve' && parsed.command !== 'd
 }
 
 let automaticCleanupFinished = false
+async function spawnDetachedSelf(
+  args: string[],
+  stderr: 'ignore' | 'inherit',
+): Promise<import('node:child_process').ChildProcess> {
+  const { spawn } = await import('node:child_process')
+  const options: import('node:child_process').SpawnOptions = {
+    detached: true,
+    stdio: ['ignore', 'ignore', stderr],
+    env: process.env,
+  }
+  const entry = process.argv[1]
+  const child = IS_STANDALONE
+    ? spawn(process.execPath, args, options)
+    : entry
+      ? spawn(process.execPath, [entry, ...args], options)
+      : spawn(rnxPublicBrand.commandName, args, options)
+  return child
+}
+
 async function scheduleAutomaticCleanup(): Promise<void> {
   if (automaticCleanupFinished) return
   automaticCleanupFinished = true
@@ -122,26 +186,8 @@ async function scheduleAutomaticCleanup(): Promise<void> {
     const { shouldSkipAutomaticSootsimCleanup } = await import('../src/disk-cleanup')
     if (shouldSkipAutomaticSootsimCleanup()) return
 
-    const { spawn } = await import('node:child_process')
     const workerArgs = ['cleanup', '--automatic-worker']
-    const entry = process.argv[1]
-    const child = IS_STANDALONE
-      ? spawn(process.execPath, workerArgs, {
-          detached: true,
-          stdio: ['ignore', 'ignore', 'inherit'],
-          env: process.env,
-        })
-      : entry
-        ? spawn(process.execPath, [entry, ...workerArgs], {
-            detached: true,
-            stdio: ['ignore', 'ignore', 'inherit'],
-            env: process.env,
-          })
-        : spawn(rnxPublicBrand.commandName, workerArgs, {
-            detached: true,
-            stdio: ['ignore', 'ignore', 'inherit'],
-            env: process.env,
-          })
+    const child = await spawnDetachedSelf(workerArgs, 'inherit')
     child.once('error', (error) => {
       process.stderr.write(
         `  ${rnxPublicBrand.name} automatic cleanup will retry on the next run: ${error.message}\n`,
@@ -157,9 +203,48 @@ async function scheduleAutomaticCleanup(): Promise<void> {
   }
 }
 
+let automaticCliUpdateFinished = false
+async function scheduleAutomaticCliUpdate(exitCode: number): Promise<void> {
+  if (automaticCliUpdateFinished) return
+  automaticCliUpdateFinished = true
+  if (!IS_STANDALONE) return
+  const {
+    claimAutomaticCliUpdateCheck,
+    shouldUseAutomaticCliUpdateCheck,
+    takeCliUpdateNotification,
+  } = await import('./cli-update')
+  if (
+    !shouldUseAutomaticCliUpdateCheck({
+      command: parsed.command,
+      commandArgs: parsed.commandArgs,
+      exitCode,
+      standalone: IS_STANDALONE,
+      stderrIsTTY: process.stderr.isTTY === true,
+      stdoutIsTTY: process.stdout.isTTY === true,
+      version: parsed.version,
+    })
+  ) {
+    return
+  }
+
+  const update = takeCliUpdateNotification()
+  if (update) {
+    process.stderr.write(
+      `  update: rnx v${update.currentVersion} → v${update.latestVersion} · run \`rnx upgrade\`\n`,
+    )
+  }
+  if (!claimAutomaticCliUpdateCheck()) return
+  try {
+    const child = await spawnDetachedSelf(['upgrade', '--check-worker'], 'ignore')
+    child.once('error', () => {})
+    child.unref()
+  } catch {}
+}
+
 async function exitWithFlush(code: number): Promise<never> {
   const { flushCliTelemetry } = await import('./telemetry')
   await flushCliTelemetry()
+  await scheduleAutomaticCliUpdate(code)
   await scheduleAutomaticCleanup()
   process.exit(code)
 }
@@ -222,7 +307,7 @@ if (!parsed.command && parsed.commandArgs.length === 0) {
 }
 
 // route to command. an empty command at this point only happens if the
-// caller passed bare positional args without a verb (e.g. `sootsim -- foo`),
+// caller passed bare positional args without a verb (e.g. `rnx -- foo`),
 // which used to fall through to the bundler-wrap behavior in `dev`. now that
 // `dev` is gone, treat it as "show help".
 const command = parsed.command ?? ''
@@ -280,7 +365,7 @@ if (
     // shell and perf subcommands are documented by their runtime dispatchers.
     // don't try to route through generated per-verb docs.
   } else if (isGroupingVerb && !subVerb) {
-    // bare `sootsim <group> --help` — render from the registry.
+    // bare `rnx <group> --help` — render from the registry.
     const { printGroupHelp } = await import('./help')
     if (printGroupHelp(command)) await exitWithFlush(0)
     // fall through — runInspect shows the full help for anything the
@@ -296,6 +381,12 @@ if (
   }
 }
 
+const { dispatchCloudBoundary } = await import('./cloud-dispatch')
+const cloudBoundary = await dispatchCloudBoundary({
+  command,
+  args: commandArgsWithSim,
+})
+if (cloudBoundary.handled) await exitWithFlush(cloudBoundary.code)
 // the command modules stop by throwing RnxExit rather than ending the
 // process, because the same command has to run in a box shell and in
 // workerd, where process.exit() cancels the whole request. this is the
@@ -331,7 +422,7 @@ try {
         const { runMaestro } = await import('./commands/maestro')
         // Maestro forwards playback argv to the shared runner, so it must
         // receive the global `--sim`. passing the bare
-        // parsed.commandArgs dropped an explicit `sootsim --sim <id> maestro
+        // parsed.commandArgs dropped an explicit `rnx --sim <id> maestro
         // …`, silently falling back to the current/saved sim (QA F21-4).
         const code = await runMaestro(commandArgsWithSim, { port, verbose })
         // bridge + dynamic imports leave handles open that keep node alive.
@@ -589,4 +680,5 @@ try {
   throw error
 }
 
+await scheduleAutomaticCliUpdate(0)
 await scheduleAutomaticCleanup()

package/cli/bridge-diagnostics.ts

@@ -1,7 +1,7 @@
 import { MERGED_CONSOLE_COUNT_EVAL, inspectErrors } from './commands/inspect/core'
 import { formatLogTimestamp } from './commands/inspect/shared'
 import type { WsBridge } from './ws-bridge'
-import type { SootSimRequestEntry } from '@sootsim/globals'
+import type { SootSimRequestEntry } from '@rnx/globals'
 
 interface ConsoleSummaryOptions {
   includeTail?: boolean

package/cli/bridge-flow-runner.ts

@@ -18,7 +18,7 @@ import type { WsBridge } from './ws-bridge'
 import type {
   SootSimExternalAppLifecycleOptions,
   SootSimLaunchArguments,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 const DEFAULT_TIMEOUT = 10000
 // hosted-runner previews reach first-render much slower than local dev: the
@@ -174,7 +174,7 @@ export interface MaestroStep {
   launchApp?: any
   // maestro canonical form: object with `file` XOR inline `commands`, plus
   // optional `when` gate and `env` vars scoped to the sub-flow. legacy
-  // sootsim also accepts a bare path string.
+  // rnx also accepts a bare path string.
   runFlow?:
     | string
     | {
@@ -1087,7 +1087,7 @@ export class SootSimBridgeFlowRunner {
       // single tap can land on a transitioning node and never grant focus —
       // the keys then go nowhere and the field stays empty, silently breaking
       // submit (the bluesky login-submit RCA, 2026-06-11). re-resolve + re-tap
-      // until the input reports focused, the same gate sootsim's `type-into`
+      // until the input reports focused, the same gate rnx's `type-into`
       // command uses. non-text-input taps keep the single-tap path.
       const tapInputAttempts = element.isTextInput ? 4 : 1
       for (let attempt = 0; attempt < tapInputAttempts; attempt++) {
@@ -1198,14 +1198,14 @@ export class SootSimBridgeFlowRunner {
 
   async inputText(text: string) {
     // real maestro types into the currently-focused field, and its driver's
-    // tap synchronously focuses it. in sootsim, focus propagates async across
+    // tap synchronously focuses it. in rnx, focus propagates async across
     // the tenant→shell worker boundary (tap → focusTextInput → keyboard show),
     // so a preceding `tapOn` on a text input may not have landed focus by the
     // time we dispatch keystrokes — especially right after a re-render storm
     // (e.g. bluesky dismissing the custom-server dialog before tapping the
     // username field). without a focused input the keys go nowhere and the
     // field stays empty, silently breaking submit. wait for a focused text
-    // input first — the same focus gate sootsim's own `type-into` uses (see
+    // input first — the same focus gate rnx's own `type-into` uses (see
     // the 2026-04-17 bluesky tap-routing regression in commands/inspect.ts).
     if (!(await this.waitForFocusedTextInput())) {
       throw new Error(
@@ -1572,7 +1572,7 @@ export class SootSimBridgeFlowRunner {
     )
     if (typeof tree === 'string') write('tree.txt', tree)
 
-    // 6. console buffer + failed requests (captured by sootsim's native-globals
+    // 6. console buffer + failed requests (captured by rnx's native-globals
     // hook / request recorder; same shape as `rnx get errors` etc.).
     const consoleBuf = await safeEval<{
       errors: unknown[]
@@ -1922,7 +1922,7 @@ export class SootSimBridgeFlowRunner {
         })
         await this.waitForTree(120000)
       } else if (wantsResetRuntime) {
-        // SootSim benchmark flows need app auth/storage kept warm while the
+        // rnx benchmark flows need app auth/storage kept warm while the
         // guest React runtime starts fresh inside the timed/recorded boundary.
         // the reload re-runs the app entry inside the mounted app surface, so
         // it only does anything while the shell is showing the app. issued from
@@ -2096,7 +2096,7 @@ export class SootSimBridgeFlowRunner {
     await this.rearmCaptureAfterRuntimeReload()
   }
 
-  // maestro clearKeychain: there is no real keychain in sootsim's browser
+  // maestro clearKeychain: there is no real keychain in rnx's browser
   // sandbox. log loudly so the author notices, then continue — matching the
   // "loud warning, not silent skip" policy in the plan.
   clearKeychain() {
@@ -2187,7 +2187,7 @@ export class SootSimBridgeFlowRunner {
       return !el
     }
     if (when.platform !== undefined) {
-      // sootsim emulates iOS — match against the context's platform the way
+      // rnx emulates iOS — match against the context's platform the way
       // upstream compares against cachedDeviceInfo.platform. keeps
       // cross-platform maestro flows running without stripping guards.
       return when.platform.toLowerCase() === this.js.maestro.platform.toLowerCase()

package/cli/browser-evals.ts

@@ -1,8 +1,8 @@
 // browser-side evaluator snippets for CLI inspect commands.
 //
-// the sootsim CLI ships some commands that need to observe the live
-// SootSim tree or its rendered pixels. we send these strings over the WS
-// bridge where they run inside the sootsim host's `evaluate` handler.
+// the rnx CLI ships some commands that need to observe the live
+// rnx tree or its rendered pixels. we send these strings over the rnx host's
+// `evaluate` handler.
 //
 // cropping happens once, in the capture module (`bridges.screenshot`),
 // via its `crop` option. these evals intentionally defer to that bridge