rnxsim 0.1.380 → 0.1.382

package/cli/commands/inspect/core.ts

@@ -1,4 +1,4 @@
-// transport-agnostic sootsim inspect-verb kernels.
+// transport-agnostic rnx inspect-verb kernels.
 //
 // each function here sends the smallest bridge command its verb needs and
 // returns *structured data* — no arg parsing or stdout. the
@@ -29,7 +29,7 @@ import type {
   SootSimTimelineQuery,
   SootSimTimelineQueryResult,
   SootSimTimelineSummary,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 // resolve a `--max-ms <n>` flag, tolerating the spellings agents and humans
 // actually type (`--maxMs`, `--maxms`, `--max_ms`). a silently-ignored
@@ -48,8 +48,9 @@ export function resolveMaxMsFlag(args: string[], fallbackMs: number): number {
 }
 
 // the minimal bridge an inspect kernel needs: a JSON command channel into a
-// sootsim instance.
+// rnx instance.
 export interface InspectBridge {
+  readonly plane?: 'local' | 'cloud'
   send(
     cmd: { type: string; [k: string]: any },
     opts?: { timeoutMs?: number },
@@ -285,7 +286,7 @@ export async function inspectDescribe(
 // fields with `styling:true` / `--styling`.
 //
 // the SAME LayoutElement shape is produced by both preview surfaces:
-//   - native/sootsim — `LAYOUT_GET_NATIVE_EVAL` reads the engine node tree via
+//   - native/rnx — `LAYOUT_GET_NATIVE_EVAL` reads the engine node tree via
 //     __sootsimTest.listInspectable() (the source `describe` uses), where each
 //     SootSimInspectInfo already carries absolute layout and optional style /
 //     box-model data.
@@ -703,7 +704,7 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
 export const LAYOUT_GET_NATIVE_EVAL = layoutGetNativeEval()
 
 // `get-layout` (native) — bounding boxes for visible meaningful elements on the
-// sootsim/native preview. transport-agnostic: the CLI runs it over its WS
+// rnx/native preview. transport-agnostic: the CLI runs it over its WS
 // bridge, the agent runs it over its in-process preview bridge.
 export async function inspectGetLayout(
   bridge: InspectBridge,
@@ -1128,7 +1129,10 @@ export async function inspectWaitSelector(
     {
       type: 'waitFor',
       waitForOptions: {
-        condition: { type: gone ? 'absent' : 'present', testID: testId },
+        condition: {
+          type: gone ? 'absent' : 'present',
+          selector: { testID: testId },
+        },
         timeoutMs,
       },
     },
@@ -1352,6 +1356,51 @@ export interface LogFilterOptions {
 // not installed yet, return an empty snapshot so validation tools don't turn a
 // missing diagnostics buffer into the app failure being diagnosed.
 export async function inspectLogs(bridge: InspectBridge): Promise<LogEntry[]> {
+  if (bridge.plane === 'cloud') {
+    const state: unknown = await bridge.send({
+      type: 'state',
+      stateOptions: {
+        screenshot: false,
+        tree: false,
+        route: false,
+        errors: false,
+        logs: true,
+        logLimit: 100,
+      },
+    })
+    const recentLogs =
+      state &&
+      typeof state === 'object' &&
+      Array.isArray(Reflect.get(state, 'recentLogs'))
+        ? Reflect.get(state, 'recentLogs')
+        : []
+    return recentLogs.flatMap((entry: unknown, index: number) => {
+      if (!entry || typeof entry !== 'object') return []
+      const text = Reflect.get(entry, 'text')
+      const rawLevel = Reflect.get(entry, 'level')
+      if (typeof text !== 'string') return []
+      const level: LogLevel =
+        rawLevel === 'log' ||
+        rawLevel === 'info' ||
+        rawLevel === 'warn' ||
+        rawLevel === 'error' ||
+        rawLevel === 'debug'
+          ? rawLevel
+          : 'error'
+      const at = Reflect.get(entry, 'at')
+      const ts = typeof at === 'number' && Number.isFinite(at) ? at : 0
+      return [
+        {
+          id: `cloud-${ts}-${index}`,
+          source: 'rnx-cloud',
+          level,
+          ts,
+          args: [text],
+          stack: null,
+        },
+      ]
+    })
+  }
   const res = (await bridge.send({
     type: 'evaluate',
     code: `(() => {
@@ -1402,7 +1451,9 @@ export function filterLogEntries(
   if (!opts.showInternal) {
     out = out.filter((e) => {
       const first = e.args[0]
-      return !(typeof first === 'string' && first.startsWith('[rnx]'))
+      return !(
+        typeof first === 'string' && /^\[(?:rnx|sootsim)(?:\s[^\]]*)?\]/.test(first)
+      )
     })
   }
   if (opts.level) out = out.filter((e) => opts.level!.has(e.level))

package/cli/commands/inspect/env.ts

@@ -13,10 +13,12 @@ const AGENT_ENV_VARS = [
   'AIDER_MODEL',
 ]
 
-export function isAgentEnv(): boolean {
-  if (process.env.RNX_AGENT === '0') return false
+export function isAgentEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (env.RNX_AGENT === '0') return false
   for (const name of AGENT_ENV_VARS) {
-    const v = process.env[name]
+    const v = env[name]
     if (v && v.trim() && v !== '0') return true
   }
   return false

package/cli/commands/inspect/shared.ts

@@ -12,7 +12,7 @@ import {
   type WsBridge,
 } from '../../ws-bridge'
 import { getShellState, inspectWaitReady, isShellCommandUnavailable } from './core'
-import type { SootSimScreenTransitionWaitResult } from '@sootsim/globals'
+import type { SootSimScreenTransitionWaitResult } from '@rnx/globals'
 
 // shell-state helpers live in the transport-agnostic kernel module so the CLI
 // and the in-browser agent share one implementation. re-exported here so
@@ -93,6 +93,7 @@ export async function maybeWaitForStartedScreenTransitions(
   bridge: WsBridge,
   opts: { verbose?: boolean } = {},
 ) {
+  if (bridge.plane === 'cloud') return
   try {
     const result = await callTestBridge<SootSimScreenTransitionWaitResult>(
       bridge,

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

@@ -26,7 +26,7 @@ import type {
   SootSimTimelineEvent,
   SootSimTimelineQuery,
   SootSimTimelineQueryResult,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 interface WaitEventOptions {
   bridge: WsBridge

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

@@ -33,13 +33,23 @@ export async function runWaitReadySubcommand(opts: {
     errors,
     bridgeError,
   } = await inspectWaitReady(bridge, timeoutMs, {
-    onProgress(status) {
-      console.error(
-        `  still waiting after ${status.elapsedMs}ms — ${waitReadyReason(status)} (nodes: ${status.nodes}, targets: ${status.targets}, live surfaces: ${status.liveFrameActive ? status.liveFrameChannels : 0}, errors: ${status.errors})`,
-      )
-    },
+    ...(bridge.plane !== 'cloud'
+      ? {
+          onProgress(status) {
+            console.error(
+              `  still waiting after ${status.elapsedMs}ms — ${waitReadyReason(status)} (nodes: ${status.nodes}, targets: ${status.targets}, live surfaces: ${status.liveFrameActive ? status.liveFrameChannels : 0}, errors: ${status.errors})`,
+            )
+          },
+        }
+      : {}),
   })
   if (ready) {
+    if (bridge.plane === 'cloud') {
+      console.log(
+        `  ready in ${elapsedMs}ms: ${nodes} nodes, ${targets} targets${liveFrameActive ? `, ${liveFrameChannels} live surfaces` : ''}`,
+      )
+      return
+    }
     const remainingMs = timeoutMs - elapsedMs
     const idleBudgetMs = Math.max(100, Math.min(10_000, remainingMs))
     const idle = await waitForSootsimIdle({

package/cli/commands/inspect.ts

@@ -1,8 +1,8 @@
-// sootsim inspect — dump node tree, accessibility info, query nodes
-// connects to the sootsim WS bridge (no Playwright)
+// rnx inspect — dump node tree, accessibility info, query nodes
+// connects to the rnx WS bridge (no Playwright)
 
-import { getCliInspectVerbMeta } from '@sootsim/skills/cli'
-import { renderCliCommandHelp, renderCliGroupHelp } from '@sootsim/skills/cli/renderers'
+import { getCliInspectVerbMeta } from '@rnx/skills/cli'
+import { renderCliCommandHelp, renderCliGroupHelp } from '@rnx/skills/cli/renderers'
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import { DEFAULT_SOOTSIM_SHELL_URL } from '../../src/cli-constants'
 import { resetGuestAppStateEval } from '../app-state-reset'
@@ -105,7 +105,7 @@ import type {
   SootSimRequestEntry,
   SootSimScreenTransitionWaitResult,
   SootSimScrollPerformanceTrace,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 interface InspectOptions {
   port?: number
@@ -1112,7 +1112,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
     `  usage: ${inspectCommand(name)}${tail ? ` ${tail}` : ''}`
 
   if (!subcommand || args.includes('--help') || args.includes('-h')) {
-    // all help output comes from the registry in packages/sootsim-skills
+    // all help output comes from the registry in packages/rnx-skills
     // so `rnx do --help`, `rnx get --help`, the website docs, and
     // the Contrast skill markdown stay in lock-step. a drift check in
     // test/sootsimCliRegistry.test.ts fails CI if a verb lands without a
@@ -1183,7 +1183,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
   }
 
   // `rnx list --drivers` — pure local registry view, no bridge needed.
-  // short-circuit here so users can discover drivers even when no sootsim
+  // short-circuit here so users can discover drivers even when no rnx
   // session is running.
   if (
     subcommand === 'list' &&
@@ -1840,6 +1840,28 @@ export async function runInspect(args: string[], opts: InspectOptions) {
           console.error('  resolves testID, id, then text — dumps full node info as JSON')
           rnxExit(1)
         }
+        if (bridge.plane === 'cloud') {
+          const byTestId = await inspectFind(bridge, { testId: matcher })
+          const byText = byTestId?.result
+            ? null
+            : await inspectFind(bridge, { text: matcher })
+          const node = byTestId?.result ?? byText?.result ?? null
+          console.log(
+            JSON.stringify(
+              node
+                ? {
+                    matcher,
+                    found: true,
+                    resolvedVia: byTestId?.result ? 'testID' : 'text',
+                    node,
+                  }
+                : { matcher, found: false },
+              null,
+              2,
+            ),
+          )
+          break
+        }
         // resolve in order: testID → id → text. first hit wins, includes the
         // resolved transform and a parent chain so agents can skip the usual
         // __sootsimRoot walk.
@@ -3607,7 +3629,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
         if (!code) {
           console.error(inspectUsage('js', '<javascript>'))
           console.error('')
-          console.error('  runs the snippet in the engine realm. SootSim is the')
+          console.error('  runs the snippet in the engine realm. rnx is the')
           console.error('  canonical state surface — reach into it directly.')
           console.error('')
           console.error('  examples:')
@@ -3679,7 +3701,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
       }
 
       case 'globals': {
-        // show all available sootsim globals and their methods
+        // show all available rnx globals and their methods
         const info = await bridge.send({
           type: 'evaluate',
           code: `(async () => {

package/cli/commands/install-desktop.ts

@@ -1,6 +1,6 @@
-// sootsim desktop install — download and install the optional desktop GUI
+// rnx desktop install — download and install the optional desktop GUI
 //
-// the CLI + daemon are the canonical sootsim surface; this command is only
+// the CLI + daemon are the canonical rnx surface; this command is only
 // for users who want the Electron-based GUI companion on top of that.
 //
 // fetches the right platform artifact from https://contrast.dev/api/electron-release/

package/cli/commands/maestro.ts

@@ -2,7 +2,7 @@
 //
 // users with an existing `.maestro/` directory can swap `maestro test`
 // for `rnx maestro test` and have their flows execute against
-// sootsim's in-browser engine. the heavy lifting lives in `flow.ts` +
+// rnx's in-browser engine. the heavy lifting lives in `flow.ts` +
 // `bridge-flow-runner.ts`; this file just re-maps the maestro argv shape
 // onto the existing flow runner and handles directory iteration + init.
 
@@ -102,7 +102,7 @@ partial:
   clearKeychain — warn-only, rnx has no keychain surface.
   when.platform — rnx reports iOS for this runner.
   openLink: app routing works; no OS-level Safari fallback.
-  launchApp.resetRuntime — sootsim-only extension for recorded benchmarks:
+  launchApp.resetRuntime — rnx-only extension for recorded benchmarks:
     keep tenant storage/auth, but soft-reload the guest app inside launchApp.
   takeScreenshot — maestro string form works unchanged; rnx also accepts
     { path, withFrame } for framed export.
@@ -402,7 +402,7 @@ export async function runMaestro(
     // one. sending it on as `--url` made it an app target instead, which left
     // the playback bridge on whichever world resolveBridgeWorld picks by
     // default (a live Vite dev shell selected from the development registry).
-    // so `sootsim --port <installed daemon> maestro …` silently ran the flow
+    // so `rnx --port <installed daemon> maestro …` silently ran the flow
     // against the dev engine, then failed trying to resolve a bundle at the
     // bridge port. an explicit command-level `--port` still wins, since
     // parseBridgeCliArgs takes the last occurrence.

package/cli/commands/permissions.ts

@@ -10,7 +10,7 @@ import type {
   SystemPermissionKind,
   SystemPermissionMutation,
   SystemPermissionStatus,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 interface PermissionsOptions {
   port?: number

package/cli/commands/platform.ts

@@ -15,6 +15,7 @@ import {
 } from 'sootsim-engine/settings'
 import { settingsStore } from 'sootsim-engine/settings/store'
 import { rnxPublicBrand } from '../../src/public-brand'
+import { rethrowIfExit } from '../run-rnx'
 
 const PLATFORM_LABEL: Record<RuntimePlatform, string> = {
   ios: 'iOS',
@@ -25,6 +26,36 @@ function isDeviceModel(value: string): value is DeviceModel {
   return value in devices
 }
 
+function cloudBundleFromArgs(args: string[]): string | null {
+  const positional: string[] = []
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (arg === '--cloud') continue
+    if (arg === '--device') {
+      index++
+      continue
+    }
+    if (
+      arg === '--sim' ||
+      arg === '--session' ||
+      arg === '--tab' ||
+      arg.startsWith('--sim=') ||
+      arg.startsWith('--session=') ||
+      arg.startsWith('--tab=')
+    ) {
+      throw new Error('rnx ios --cloud creates a new simulator and cannot target --sim')
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`rnx ios --cloud does not support ${arg}`)
+    }
+    positional.push(arg)
+  }
+  if (positional.length !== 1) {
+    throw new Error('usage: rnx ios --cloud <local bundle.js> [--device <model>]')
+  }
+  return positional[0] ?? null
+}
+
 export async function runPlatformCommand(
   platform: RuntimePlatform,
   args: string[],
@@ -34,6 +65,7 @@ export async function runPlatformCommand(
   // contradiction shows up here as a platform mismatch. refuse it by name
   // rather than silently overriding whichever one the user meant.
   const explicitDevice = args.find((_, i) => args[i - 1] === '--device')
+  let selectedDevice: DeviceModel
   if (explicitDevice !== undefined) {
     if (!isDeviceModel(explicitDevice)) {
       console.error(
@@ -53,6 +85,7 @@ export async function runPlatformCommand(
       )
       return 1
     }
+    selectedDevice = explicitDevice
   } else {
     // keep the user's own device when it already belongs to the platform they
     // asked for, so `rnx ios` after `rnx device set iphone-16` does not
@@ -60,6 +93,64 @@ export async function runPlatformCommand(
     const current = settingsStore.get('deviceModel')
     if (getRuntimePlatform(current) !== platform) {
       settingsStore.apply({ deviceModel: DEFAULT_DEVICE_BY_PLATFORM[platform] })
+      selectedDevice = DEFAULT_DEVICE_BY_PLATFORM[platform]
+    } else {
+      selectedDevice = current
+    }
+  }
+
+  if (args.includes('--cloud')) {
+    if (platform !== 'ios') {
+      console.error(
+        `  ${rnxPublicBrand.commandName} android --cloud is not available; RNX Cloud currently supports iOS`,
+      )
+      return 1
+    }
+    try {
+      const bundlePath = cloudBundleFromArgs(args)
+      if (!bundlePath) throw new Error('rnx ios --cloud requires a local bundle.js')
+      const {
+        publishCloudSessionToShell,
+        readCloudSession,
+        requireCloudSessionShellUpdate,
+      } = await import('../cloud-session')
+      if (readCloudSession()) {
+        throw new Error(
+          'this shell already has an RNX Cloud simulator; run `rnx close` or create the next simulator in another shell',
+        )
+      }
+      const descriptor = requireCloudSessionShellUpdate()
+      const { authHeaderOrExit } = await import('../auth')
+      const { closeCloudSimulator, createCloudSimulator } =
+        await import('../cloud-client')
+      const { header } = authHeaderOrExit('ios --cloud')
+      const created = await createCloudSimulator({
+        bundlePath,
+        device: selectedDevice,
+        authorization: header,
+      })
+      try {
+        publishCloudSessionToShell(created.session, descriptor)
+      } catch (error) {
+        await closeCloudSimulator(created.session)
+        throw error
+      }
+      const receipt = created.receipt
+      console.log(`  cloud sim: ${receipt.simId}`)
+      console.log(`  artifact: ${receipt.artifact.id} (${receipt.artifact.bytes} bytes)`)
+      console.log(`  claim expires: ${receipt.claim.expiresAt}`)
+      console.log(
+        '  reads: describe, find, get tree|node|count, wait ready|selector, logs, state, screenshot',
+      )
+      return 0
+    } catch (error) {
+      rethrowIfExit(error)
+      console.error(
+        `  ${rnxPublicBrand.commandName} ios --cloud failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      return 1
     }
   }
 

package/cli/commands/record.ts

@@ -1,6 +1,6 @@
 // rnx record — drives the engine's built-in canvas recorder over
 // the WS bridge. no playwright, no ffmpeg. encoding happens in the
-// running sootsim page (webm via MediaRecorder, mp4 via WebCodecs, gif
+// running rnx page (webm via MediaRecorder, mp4 via WebCodecs, gif
 // via gifenc, raw png frames via a shared bitmap sampler).
 
 import {
@@ -180,7 +180,7 @@ function readRepoScope(args: string[]): RepoScope {
 
 export async function runRecord(args: string[], opts: RecordOptions) {
   // note: `--help` / `-h` never reach here — bin.ts intercepts them and
-  // renders the registry-driven help page (packages/sootsim-skills meta.ts).
+  // renders the registry-driven help page (packages/rnx-skills meta.ts).
 
   const sub = findRecordSubcommand(args)
   if (sub) {
@@ -583,7 +583,7 @@ async function assertRecorderAvailable(bridge: WsBridge) {
 
 // frame-capturing recordings (video / gif / png / combined) drive their
 // encoder off requestAnimationFrame and throttled timers, which browsers
-// clamp to ~1fps when the sootsim tab is hidden (backgrounded, or its chrome
+// clamp to ~1fps when the rnx tab is hidden (backgrounded, or its chrome
 // window minimized). that silently produced a frozen-looking file and is
 // exactly why agents started pre-checking `document.hidden` by hand. refuse
 // up front with an actionable message instead. checkSimHealth already emits

package/cli/commands/report-issue.ts

@@ -1,4 +1,4 @@
-// sootsim report-issue — submit an explicitly approved compatibility report.
+// rnx report-issue — submit an explicitly approved compatibility report.
 
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve } from 'node:path'

package/cli/commands/runtime.ts

@@ -136,7 +136,7 @@ async function activateVersion(version: string) {
   const notified = await tellDaemonRuntimeChanged(version)
   if (!notified) {
     console.log(
-      `  (no daemon running — next sootsim/electron launch will pick up ${version})`,
+      `  (no daemon running — next rnx/electron launch will pick up ${version})`,
     )
   }
 }

package/cli/commands/screenshot-mode.ts

@@ -1,5 +1,5 @@
 // rnx mode screenshot — toggle the "screenshot mode" chrome overlay
-// in the running sootsim sim. orthogonal to `--no-shell` on the
+// in the running rnx sim. orthogonal to `--no-shell` on the
 // `screenshot` command: this hides the DOM browser chrome (rail, menubar,
 // window controls) while still rendering the iOS shell inside the canvas.
 //

package/cli/commands/screenshot.ts

@@ -13,6 +13,7 @@ import { launchReapedChrome } from '../../../../scripts/lib/reap-browser'
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import { composeFramedScreenshot } from '../../src/screenshots/frame-compose'
 import { buildResolveRectEval, type SampleRect } from '../browser-evals'
+import { createCloudBridgeForParsed } from '../cloud-client'
 import { rnxExit } from '../run-rnx'
 import {
   callInBridge,
@@ -120,6 +121,30 @@ examples:
     stripValueFlags: ['--output', '--area', '--id', '--text'],
   })
   const outputArg = resolveOutputPath(args)
+  const cloudBridge = createCloudBridgeForParsed(parsed)
+  if (cloudBridge) {
+    try {
+      const dataUrl: unknown = await cloudBridge.send({ type: 'screenshot' })
+      const pngPrefix = 'data:image/png;base64,'
+      if (typeof dataUrl !== 'string' || !dataUrl.startsWith(pngPrefix)) {
+        throw new Error('RNX Cloud screenshot returned invalid image data')
+      }
+      const outputPath = resolve(process.cwd(), outputArg || '/tmp/rnx-inspect.png')
+      mkdirSync(dirname(outputPath), { recursive: true })
+      const png = Buffer.from(dataUrl.slice(pngPrefix.length), 'base64')
+      if (png.length === 0) throw new Error('RNX Cloud screenshot returned no image data')
+      writeFileSync(outputPath, png)
+      console.log(`  saved: ${outputPath}`)
+    } catch (error) {
+      console.error(
+        `  screenshot failed: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      rnxExit(1)
+    } finally {
+      cloudBridge.close()
+    }
+    return
+  }
   const rect = await parseRect(args)
   const usingBridge = await probeBridge(parsed.wsPort)
 

package/cli/commands/serve.ts

@@ -56,7 +56,7 @@ examples:
   }
   const quiet = args.includes('--quiet') || args.includes('-q')
 
-  // only one bridge per sootsim home. refuse to start a second one
+  // only one bridge per rnx home. refuse to start a second one
   // regardless of requested port, since both would try to write the same
   // daemon.json and electron/cli clients only read one lockfile.
   const existingLock = readDaemonLockfile()

package/cli/commands/skills.ts

@@ -216,7 +216,7 @@ function symlinkPointsTo(dest: string, src: string): boolean {
 }
 
 // a store entry left by an older CLI is safe to upgrade: either a real dir
-// whose only content is a SKILL.md symlink into a sootsim skills source (the
+// whose only content is a SKILL.md symlink into an rnx skills source (the
 // pre-dir-layout install — possibly broken after the source moved), or a dir
 // holding a byte-identical copy of the skill. only our installer creates
 // those shapes, so replacing them can't lose user work.

package/cli/commands/timeline.ts

@@ -2,7 +2,7 @@
 //
 // `rnx record` is for video/screen capture; `rnx debug record` is
 // for the engine-internal debug-channel ring; this command is the third
-// surface and explicitly distinct: it manages SootSim.bridges.timeline,
+// surface and explicitly distinct: it manages the SootSim.bridges.timeline API,
 // the unified, agent-facing semantic event stream across host / shell
 // worker / tenant worker.
 //

package/cli/commands/upgrade.ts

@@ -10,12 +10,15 @@ import { compareSemver } from '@contrast/runtime-delivery'
 import { getCliVersion } from '../../src/cli-version'
 import { isSootsimDevCheckout, readActiveRuntime, runtimeDir } from '../../src/home-paths'
 import { resolveRNXAppConfig } from '../app-config'
+import {
+  DEFAULT_CLI_RELEASE_ORIGIN,
+  fetchCliReleaseFile,
+  refreshCliUpdateCache,
+} from '../cli-update'
 import { fetchRuntimeReleaseNotes, formatRuntimeReleaseNotes } from '../runtime-notes'
 import { IS_STANDALONE } from '../standalone'
 import { runRuntime } from './runtime'
 
-const DEFAULT_CLI_RELEASE_ORIGIN = 'https://r2.rnxsim.com/rnx-cli'
-const CLI_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
 const SHA256_PATTERN = /^[a-f0-9]{64}$/
 
 export interface UpgradeOptions {
@@ -100,14 +103,7 @@ export async function upgradeCli(options: UpgradeOptions = {}): Promise<void> {
     '',
   )
   const current = getCliVersion()
-  const latest = (await fetchRequired(`${releaseOrigin}/channels/stable`, 8_000))
-    .toString('utf8')
-    .trim()
-  if (!CLI_VERSION_PATTERN.test(latest)) {
-    throw new Error(
-      `rnx update service returned an invalid version: ${latest || '(empty)'}`,
-    )
-  }
+  const { latestVersion: latest } = await refreshCliUpdateCache({ releaseOrigin })
   if (compareSemver(latest, current) <= 0) {
     console.log(`  v${current} (latest)`)
     return
@@ -115,7 +111,7 @@ export async function upgradeCli(options: UpgradeOptions = {}): Promise<void> {
 
   const artifact = cliArtifactName()
   const artifactUrl = `${releaseOrigin}/${latest}/${artifact}`
-  const expectedSha = (await fetchRequired(`${artifactUrl}.sha256`, 8_000))
+  const expectedSha = (await fetchCliReleaseFile(`${artifactUrl}.sha256`, 8_000))
     .toString('utf8')
     .trim()
   if (!SHA256_PATTERN.test(expectedSha)) {
@@ -124,7 +120,7 @@ export async function upgradeCli(options: UpgradeOptions = {}): Promise<void> {
 
   console.log(`  v${current} → v${latest}`)
   console.log(`  downloading ${artifact}...`)
-  const executable = await fetchRequired(artifactUrl, 120_000)
+  const executable = await fetchCliReleaseFile(artifactUrl, 120_000)
   const actualSha = createHash('sha256').update(executable).digest('hex')
   if (actualSha !== expectedSha) {
     throw new Error(
@@ -157,28 +153,6 @@ function cliArtifactName(): string {
   return `rnx-${platform}-${process.arch}`
 }
 
-async function fetchRequired(url: string, timeoutMs: number): Promise<Buffer> {
-  let response: Response
-  try {
-    response = await fetch(url, {
-      headers: { accept: 'application/octet-stream' },
-      signal: AbortSignal.timeout(timeoutMs),
-    })
-  } catch (error) {
-    throw new Error(
-      `could not reach the rnx update service: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    )
-  }
-  if (!response.ok) {
-    throw new Error(
-      `rnx update download failed: ${response.status} ${response.statusText}`,
-    )
-  }
-  return Buffer.from(await response.arrayBuffer())
-}
-
 function verifyCandidate(candidatePath: string, expectedVersion: string): void {
   const result = spawnSync(candidatePath, ['--version'], {
     encoding: 'utf8',