rnxsim 0.1.366 → 0.1.368

package/README.md

@@ -23,7 +23,8 @@ What this package gives you:
   editor
 - `rnxsim/detox` — a drop-in Detox driver + jest preset
 - `rnxsim/sdk` — the inspect/interact verbs as a programmatic API
-- `rnxsim/mcp` — a transport-neutral, injected-sim MCP tool registry
+- `rnxsim/bridge-contract-input` — parsers turning untrusted JSON into
+  bridge-contract arguments
 - `rnxsim/skills` — a registry of Contrast-flavored automation skills
 
 Platform status: iOS is the parity baseline. Android is bootstrapped and usable
@@ -189,7 +190,7 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 | rnx CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, owns the private-by-default one-time choice, lazy-imports one command per run, and routes direct open/runtime/inspection flows. | `cli/bin.ts`, `cli/privacy.ts`, `cli/parse-args.ts`, `cli/help.ts`, `cli/commands/setup.ts`, `cli/commands/control.ts` |
 | WsBridge client | Client side of the CLI→daemon link. Resolves the daemon port from the lockfile, opens a WS to `:7668`, sends JSON commands and awaits `{id,result}`/`{id,error}`. Used by every interactive command. | `cli/ws-bridge.ts`, `src/bridge-constants.ts`, `cli/current-sim.ts` |
 | inspect / SDK command surface | Runtime inspection + interaction verbs (describe, find, do tap, get errors, wait, layout, settle). Re-exported as `rnxsim/sdk` so programmatic callers drive a sim the same way the CLI does. | `cli/commands/inspect/core.ts`, `cli/commands/inspect/actions.ts`, `cli/commands/inspect.ts`, `src/sdk.ts` |
-| per-sim MCP adapter | Strict JSON-schema tools over one injected `SimClient`. The schemas expose no sim selector, and the adapter owns no transport or server lifecycle. | `src/mcp.ts`, `src/sim-client.ts` |
+| bridge-contract input parsers | Turn untrusted JSON into typed bridge-contract arguments, so a transport in front of a sim validates request bodies once instead of writing a second reader. | `src/bridge-contract-input.ts`, `src/bridge-contract.ts` |
 | Maestro / Detox runners | Drop-in test compatibility. `bridge-flow-runner.ts` runs Maestro YAML and recorded flows over the bridge; `detox/` provides a `by`/`element`/`expect`/`device` driver + jest preset so existing Detox suites run unchanged. | `cli/bridge-flow-runner.ts`, `cli/commands/maestro.ts`, `cli/commands/detox.ts`, `detox/index.ts`, `detox/jest-preset.cjs` |
 | sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; Electron owns the native desktop surface. The current sim is reused unless `--new`, `--profile`, or `--ephemeral` requests a separate one. | `cli/drivers/index.ts`, `cli/drivers/registry.ts`, `cli/drivers/electron.ts`, `cli/drivers/playwright.ts` |
 | SootSimBridgeHost (serve/daemon) | The bridge process (`rnx serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
@@ -306,6 +307,7 @@ rnx find --testid cta # inspect one node deeply
 rnx debug enable animated,layout
 rnx debug trace shell on 240
 rnx do tap-text "..." # interact
+rnx do tap email --then type user@example.com --then tap submit
 rnx debug snapshot before
 rnx debug snapshot after
 rnx debug diff before after
@@ -323,6 +325,16 @@ connected. With multiple driveable sims, the bridge lists their ids and refuses
 to choose. Run `rnx use <id>` to pin later commands, or pass `--sim <id>` to
 target one command.
 
+Use an inline `rnx do` chain for a short action sequence that should execute as
+one engine batch. Repeat `--then` before each additional action. Each phrase
+uses the same positional grammar as its standalone `do` command. Touch timing
+stays inside the sim, the batch stops at the first failure, and `--json` prints
+the complete per-step result. Reusable file-based flows stay in Maestro YAML.
+
+```sh
+rnx do tap email --then type user@example.com --then tap submit
+```
+
 ## Bundler plugins (`rnxsim/vite` and `rnxsim/metro`)
 
 The Vite plugin serves the installed RNX runtime from your existing dev server.

package/cli/bin.ts

@@ -318,6 +318,12 @@ if (
 exitIfStandaloneBlocked(command)
 
 if (TOP_LEVEL_RUNTIME_COMMANDS.has(command)) {
+  if (command === 'do') {
+    const { hasDoChain, runDoChain } = await import('./commands/do-chain')
+    if (hasDoChain(commandArgsWithSim)) {
+      await exitWithFlush(await runDoChain(commandArgsWithSim, { port }))
+    }
+  }
   const { runInspect } = await import('./commands/inspect')
   await runInspect([command, ...commandArgsWithSim], { port, verbose })
 } else {
@@ -434,6 +440,18 @@ if (TOP_LEVEL_RUNTIME_COMMANDS.has(command)) {
       break
     }
 
+    case 'ios':
+    case 'android': {
+      const { runPlatformCommand } = await import('./commands/platform')
+      const code = await runPlatformCommand(command, commandArgsWithSim, { port })
+      await exitWithFlush(typeof code === 'number' ? code : 0)
+    }
+
+    case 'box': {
+      const { runBox } = await import('./commands/box')
+      await exitWithFlush(await runBox(commandArgsWithSim, { port, verbose }))
+    }
+
     case 'use': {
       const { runUseCommand } = await import('./commands/control')
       await runUseCommand(commandArgsWithSim, { port })

package/cli/bridge-flow-runner.ts

@@ -7,14 +7,7 @@ import {
   framesIdentical,
 } from '../detox/proof-frame.cjs'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
-import {
-  READY_NODE_STABLE_MS,
-  READY_PROBE_POLL_MS,
-  WAIT_READY_PROBE,
-  readyProbeHasContent,
-  readyProbeHasTargetContent,
-  type ReadyProbe,
-} from './commands/inspect/core'
+import { inspectWaitReady, waitReadyReason } from './commands/inspect/core'
 import { waitForSootsimIdle } from './commands/inspect/settling'
 import { callShellCommandWhenReady, getShellState } from './commands/inspect/shared'
 import { FlowLiveStatusReporter } from './flow-live-status'
@@ -424,7 +417,6 @@ export class SootSimBridgeFlowRunner {
   private lastRecordingDurationMs: number | null = null
   private lastRecordingFrameStats: unknown = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
-  private simRouteHint: string | null = null
   // set by runStep when a step throws — lets the outer flow command
   // dump a rich per-step failure bundle (screenshot + describe.json +
   // console + network) keyed by the failing step.
@@ -432,8 +424,8 @@ export class SootSimBridgeFlowRunner {
 
   constructor(
     readonly bridge: WsBridge,
-    // simId rotates when the bridge picks a different open sim mid-flow;
-    // the rest of opts is stable.
+    // simId identifies the browser tab for the whole flow, including reloads;
+    // the rest of opts is stable too.
     private readonly opts: {
       screenshotDir: string
       flowDir: string
@@ -473,58 +465,6 @@ export class SootSimBridgeFlowRunner {
     return this.opts.simId
   }
 
-  setSimRouteHint(urlLike: string | null | undefined) {
-    this.simRouteHint = this.normalizeSimRoute(urlLike)
-  }
-
-  private normalizeSimRoute(urlLike: string | null | undefined): string | null {
-    if (!urlLike) return null
-    try {
-      const url = new URL(urlLike)
-      url.searchParams.delete('inspectOpen')
-      const search = url.searchParams.toString()
-      return `${url.origin}${url.pathname}${search ? `?${search}` : ''}`
-    } catch {
-      return urlLike
-    }
-  }
-
-  // sim ids rotate on `window.location.reload()` when the shell reconnects.
-  // after launchApp we re-resolve the primary sim so the rest of the flow
-  // doesn't send commands to a dead id.
-  private async refreshSimId(): Promise<void> {
-    if (!this.opts.simId) return
-    try {
-      const sims = await this.bridge.listSims()
-      const current = sims.find((b) => b.id === this.opts.simId)
-      if (current) {
-        this.simRouteHint = this.normalizeSimRoute(current.url || current.origin)
-      }
-      const stillThere = sims.find(
-        (b) => b.id === this.opts.simId && b.readyState === 'open',
-      )
-      if (stillThere) return
-      if (!this.simRouteHint) return
-      const hinted =
-        this.simRouteHint &&
-        sims.find(
-          (b) =>
-            b.readyState === 'open' &&
-            this.normalizeSimRoute(b.url || b.origin) === this.simRouteHint,
-        )
-      if (!hinted) return
-      const primary = sims.find((b) => b.isPrimary && b.readyState === 'open')
-      const firstOpen = sims.find((b) => b.readyState === 'open')
-      const next = hinted ?? primary ?? firstOpen
-      if (next) {
-        this.opts.simId = next.id
-        console.log(`  [flow] sim rotated to ${next.id}`)
-      }
-    } catch {
-      // bridge unreachable — let the next command surface the real error
-    }
-  }
-
   private async evaluate<T = unknown>(code: string, timeoutMs?: number): Promise<T> {
     return this.bridge.send(
       {
@@ -556,90 +496,19 @@ export class SootSimBridgeFlowRunner {
   }
 
   async waitForTree(timeout: number = DEFAULT_TIMEOUT) {
-    const deadline = Date.now() + scaledTimeout(timeout)
-    const startedAt = Date.now()
-    let lastError: Error | null = null
-    // a not-ready app still answers `evaluate` (the probe body returns
-    // `{count, loading}`); a sim that can't even run the probe — bridge
-    // disconnect, command timeout — is a stale orphan or a dead tab. count
-    // those distinctly so we can fail fast instead of polling the full
-    // (up to 120s) timeout with no output, which reads as a dead hang (B1).
-    let consecutiveBridgeFailures = 0
-    let lastProgressAt = 0
-    // readiness mirrors `sootsim wait ready` (shared WAIT_READY_PROBE + the
-    // readyProbeHasContent decision). the previous inline probe used
-    // findByText('loading'/'capturing'/'opening app'), which substring-matched
-    // ordinary forum copy ("...still loading the card...") and reported a
-    // fully-painted screen as perpetually loading. WAIT_READY_PROBE only treats
-    // an exact, isolated loading label as "loading" and prefers the guest app's
-    // own ready signal, so a content-rich screen no longer false-positives.
-    let lastNodes = -1
-    let nodeStableSince = startedAt
-    while (Date.now() < deadline) {
-      try {
-        const probe = await this.evaluate<ReadyProbe | null>(
-          WAIT_READY_PROBE,
-          // the readiness probe is cheap — cap it well under the bridge-wide
-          // command timeout so a non-responsive sim is detected in seconds,
-          // not after a full 15s-per-poll stall.
-          8000,
-        )
-        consecutiveBridgeFailures = 0
-        if (probe?.externalError) {
-          throw new Error(`app failed to load: ${probe.externalError}`)
-        }
-        if (probe) {
-          const now = Date.now()
-          if (probe.nodes !== lastNodes) {
-            lastNodes = probe.nodes
-            nodeStableSince = now
-          }
-          const hasReadySignal = probe.flag === true && readyProbeHasContent(probe)
-          const hasRenderedContentWithoutReadySignal =
-            probe.flag !== true && readyProbeHasTargetContent(probe)
-          const ready =
-            (hasReadySignal || hasRenderedContentWithoutReadySignal) &&
-            probe.externalReady !== false &&
-            !probe.externalError &&
-            !probe.loadingText &&
-            now - nodeStableSince >= READY_NODE_STABLE_MS
-          if (ready) return
-        }
-      } catch (err) {
-        lastError = err instanceof Error ? err : new Error(String(err))
-        // a real load error reported by the probe body — not a bridge
-        // failure. surface it immediately rather than retrying.
-        if (lastError.message.startsWith('app failed to load:')) {
-          throw lastError
-        }
-        consecutiveBridgeFailures++
-        if (consecutiveBridgeFailures >= 4) {
-          throw new Error(
-            `target sim is not responding to the bridge (${lastError.message}). ` +
-              `it is likely a stale orphan — run \`rnx list\`, then close it ` +
-              `with \`rnx close <id>\` or start a fresh one with \`rnx open --new <port>\`.`,
-          )
-        }
-        await this.refreshSimId()
-      }
-      // surface progress every ~5s so a slow-loading app or a sim mid-boot
-      // does not look like a dead hang while waitForTree polls (B1).
-      const elapsed = Date.now() - startedAt
-      if (elapsed - lastProgressAt >= 5000) {
-        lastProgressAt = elapsed
-        console.log(
-          `  [flow] waiting for app to be ready… (${Math.round(elapsed / 1000)}s)`,
-        )
-      }
-      // same cadence as inspectWaitReady, which runs this identical readiness
-      // decision for `sootsim wait ready`. polling slower here only delayed
-      // every launchApp by up to a poll interval.
-      await sleep(READY_PROBE_POLL_MS)
+    const status = await inspectWaitReady(this.bridge, scaledTimeout(timeout))
+    if (status.ready) return
+    if (status.externalError) {
+      throw new Error(`app failed to load: ${status.externalError}`)
     }
-    if (lastError?.message.startsWith('app failed to load:')) {
-      throw lastError
+    if (status.bridgeError) {
+      throw new Error(
+        `target sim is not responding to the bridge (${status.bridgeError}). ` +
+          `it is likely a stale orphan; run \`rnx list\`, then close it ` +
+          `with \`rnx close <id>\` or start a fresh one with \`rnx open --new <port>\`.`,
+      )
     }
-    throw new Error(`app not ready after ${timeout}ms`)
+    throw new Error(`app not ready after ${timeout}ms: ${waitReadyReason(status)}`)
   }
 
   private async ensureRecordingStarted() {
@@ -1966,10 +1835,6 @@ export class SootSimBridgeFlowRunner {
   private async reloadGuestApp() {
     // hard page reload resets the tenant worker.
     await this.evaluate('window.location.reload()').catch(() => {})
-    // the sim id rotates on a page reload; pick up the new primary before any
-    // further command, or waitForTree loops against a dead id.
-    await sleep(500)
-    await this.refreshSimId()
   }
 
   private async resetGuestAppData(
@@ -2014,7 +1879,6 @@ export class SootSimBridgeFlowRunner {
     const deadline = Date.now() + 10000
     let lastError: unknown = null
     while (Date.now() < deadline) {
-      await this.refreshSimId()
       try {
         if (this.recordingEnabled) await this.ensureRecordingStarted()
         if (this.profilingEnabled) await this.startProfile()
@@ -2032,7 +1896,6 @@ export class SootSimBridgeFlowRunner {
   }
 
   async launchApp(opts: any) {
-    await this.refreshSimId()
     let hasLaunchArguments = false
     let launchArguments: SootSimLaunchArguments | undefined
     if (isObjectRecord(opts) && Object.prototype.hasOwnProperty.call(opts, 'arguments')) {

package/cli/commands/assert.ts

@@ -536,6 +536,6 @@ examples:
   rnx assert describe --contains "swap-form-header"
   rnx assert get errors --count 0
   rnx assert find --testid submit --exists --within 3000
-  rnx assert describe --jq '.shell.state == "app"'
+  rnx assert describe --jq '.tree | contains("swap-form-header")'
 `)
 }

package/cli/commands/box/checkout-plane.ts

@@ -0,0 +1,126 @@
+// ProjectFilePlane over a real local checkout — the third provider behind the
+// seam Contrast's browser host and its server host already implement. writes
+// land on the user's actual disk, so this plane refuses anything it cannot
+// represent faithfully rather than round-tripping it through a string.
+//
+// the file set comes from `git ls-files -co --exclude-standard`, which is the
+// project's own definition of what belongs to it. a hardcoded skip list was
+// measured against this repo and is not viable: it walked 230,229 files
+// (16.5 GB) in 4.9 s, where git returns the same project as 14,984 paths in
+// 67 ms. `index()` is a synchronous whole-project map, so the size of that set
+// is the whole cost model.
+
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness'
+
+const execFileAsync = promisify(execFile)
+
+export class CheckoutRequiresGitError extends Error {}
+
+// a NUL byte is the usual "this is not text" test. the plane serves strings,
+// so a binary file cannot survive a read/write round trip. reading one gives
+// the same garbage real `cat` gives, which is fine; WRITING one back would
+// corrupt a file on the user's actual disk, so binary files are published as
+// read-only and the write path refuses them by name. detecting this at read
+// time is not an option: just-bash's `cat` discards every readFile error and
+// reports "No such file or directory" whatever the error says, so the refusal
+// has to live in the index where the filesystem layer can act on it.
+const BINARY_SNIFF_BYTES = 8192
+
+function looksBinary(filePath: string, size: number): boolean {
+  if (size === 0) return false
+  let fd: number | undefined
+  try {
+    fd = fs.openSync(filePath, 'r')
+    const buffer = Buffer.alloc(Math.min(BINARY_SNIFF_BYTES, size))
+    const read = fs.readSync(fd, buffer, 0, buffer.length, 0)
+    return buffer.subarray(0, read).includes(0)
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd)
+  }
+}
+
+export class CheckoutFilePlane implements ProjectFilePlane {
+  readonly root: string
+  private entries = new Map<string, ProjectFileMeta>()
+
+  constructor(root: string) {
+    this.root = path.resolve(root)
+  }
+
+  index(): ReadonlyMap<string, ProjectFileMeta> {
+    return this.entries
+  }
+
+  async refresh(): Promise<void> {
+    let stdout: string
+    try {
+      // -z so paths containing spaces or newlines survive; -co --exclude-standard
+      // is tracked plus untracked-not-ignored, which is what a person means by
+      // "the files in my project".
+      const result = await execFileAsync(
+        'git',
+        ['ls-files', '-co', '--exclude-standard', '-z'],
+        { cwd: this.root, maxBuffer: 64 * 1024 * 1024 },
+      )
+      stdout = result.stdout
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new CheckoutRequiresGitError(
+        `could not list the project's files with git in ${this.root}: ${message}`,
+      )
+    }
+
+    const next = new Map<string, ProjectFileMeta>()
+    for (const relative of stdout.split('\0')) {
+      if (!relative) continue
+      let stat: fs.Stats
+      try {
+        stat = fs.statSync(path.join(this.root, relative))
+      } catch {
+        // listed but gone (a deleted-but-tracked file); it is simply not there
+        continue
+      }
+      if (!stat.isFile()) continue
+      next.set(relative, {
+        size: stat.size,
+        readOnly: looksBinary(path.join(this.root, relative), stat.size),
+      })
+    }
+    this.entries = next
+  }
+
+  private absolute(planePath: string): string {
+    const resolved = path.resolve(this.root, planePath)
+    // the shell resolves "." and ".." before calling us, but the plane owns the
+    // checkout boundary and must not depend on that.
+    if (resolved !== this.root && !resolved.startsWith(`${this.root}${path.sep}`)) {
+      throw new Error(`path escapes the project: ${planePath}`)
+    }
+    return resolved
+  }
+
+  async read(planePath: string): Promise<string> {
+    return fs.promises.readFile(this.absolute(planePath), 'utf8')
+  }
+
+  async write(planePath: string, content: string): Promise<void> {
+    const absolute = this.absolute(planePath)
+    await fs.promises.mkdir(path.dirname(absolute), { recursive: true })
+    await fs.promises.writeFile(absolute, content, 'utf8')
+    this.entries.set(planePath, {
+      size: Buffer.byteLength(content, 'utf8'),
+      readOnly: false,
+    })
+  }
+
+  async delete(planePath: string): Promise<void> {
+    await fs.promises.rm(this.absolute(planePath), { force: true })
+    this.entries.delete(planePath)
+  }
+}

package/cli/commands/box/rnx-command.ts

@@ -0,0 +1,68 @@
+// step 4: RNX operations registered as just-bash commands.
+//
+// `rnx` inside a box shell is the same CLI, re-invoked as a child process with
+// the shell's own cwd. that is deliberate — spelling the verbs a second time
+// in shell-command form would be a second implementation of every command, and
+// the spec is explicit that the CLI and the in-shell commands are clients of
+// one implementation, not two.
+
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { defineCommand, type CustomCommand } from '@contrast/harness'
+import { PROJECT_MOUNT } from '@contrast/harness'
+import { rnxPublicBrand } from '../../../src/public-brand'
+import { RNX_PLACEMENT_ENV } from '../../ws-bridge'
+
+// the standalone binary is its own entry; the npm package runs through node
+// with the CLI as argv[1]. this is the same shape bin.ts uses to respawn
+// itself for automatic cleanup.
+function selfInvocation(): { command: string; prefix: string[] } {
+  const entry = process.argv[1]
+  if (!entry) return { command: process.execPath, prefix: [] }
+  return { command: process.execPath, prefix: [entry] }
+}
+
+// map a shell path under /project back onto the real checkout, so a child
+// process started from `cd src && rnx describe` sees the directory the user
+// is actually standing in.
+function hostCwd(root: string, shellCwd: string): string {
+  if (shellCwd === PROJECT_MOUNT) return root
+  if (!shellCwd.startsWith(`${PROJECT_MOUNT}/`)) return root
+  return path.join(root, shellCwd.slice(PROJECT_MOUNT.length + 1))
+}
+
+export function createRnxCommand(options: {
+  root: string
+  shellCwd: () => string
+}): CustomCommand {
+  return defineCommand(rnxPublicBrand.commandName, async (args) => {
+    const { command, prefix } = selfInvocation()
+    const child = spawn(command, [...prefix, ...args], {
+      cwd: hostCwd(options.root, options.shellCwd()),
+      // mark the child as running inside a local box. this is the only thing
+      // that sets a placement — nothing infers one from cwd — and it is what
+      // lets `rnx box` refuse to nest inside itself.
+      env: { ...process.env, [RNX_PLACEMENT_ENV]: 'local-box' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk)
+    })
+
+    const exitCode = await new Promise<number>((resolve) => {
+      child.once('error', (error) => {
+        stderr += `${rnxPublicBrand.commandName}: ${error.message}\n`
+        resolve(1)
+      })
+      child.once('close', (code) => resolve(code ?? 0))
+    })
+
+    return { stdout, stderr, exitCode }
+  })
+}