peachsim 0.1.527

package/cli/commands/maestro.ts

@@ -0,0 +1,536 @@
+// rnx maestro — drop-in replacement for the real `maestro` cli.
+//
+// users with an existing `.maestro/` directory can swap `maestro test`
+// for `rnx maestro test` and have their flows execute against
+// 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.
+
+import * as fs from 'fs'
+import * as path from 'path'
+import yaml from 'yaml'
+import { resolveCliAuth } from '../auth'
+import { parseFlowFile } from '../flow-file'
+import { registerRun, shouldRegisterRun, stepSummaryFromTrace } from '../run-registry'
+import { RnxExit } from '../run-rnx'
+import {
+  findUnexpectedFlowArgs,
+  FLOW_ARG_VALUE_FLAGS,
+  getLastFlowPreviewUploadResult,
+  getLastFlowTraceSteps,
+  hoistLeadingSimFlag,
+  runMaestroAuthoring,
+  runFlowPlayback,
+} from './flow'
+import { resolveDefaultUploadOrigin } from './upload'
+
+export interface RunMaestroOptions {
+  port?: number
+  verbose?: boolean
+}
+
+const MAESTRO_DIRS = ['.maestro', 'maestro']
+
+function printHelp() {
+  console.log(`
+rnx maestro — author and run Maestro YAML flows against rnx
+
+usage:
+  rnx maestro                         # discover .maestro/ or maestro/ in cwd, run all
+  rnx maestro test <flow-or-dir>      # mirrors "maestro test"
+  rnx maestro test .maestro/          # every *.yaml / *.yml in a directory
+  rnx maestro generate "<goal>"       # generate, run, and upload a Maestro flow
+  rnx maestro start|keep|end          # author a flow from live CLI actions
+  rnx maestro validate <flow>         # validate a Maestro YAML file
+  rnx maestro init                    # scaffold .maestro/login.yaml
+  rnx maestro --list-compat           # print supported/unsupported verbs
+
+options:
+  --env KEY=VALUE        set env vars for \${KEY} interpolation (repeatable)
+  --continuous           accepted for maestro cli compat; rnx runs the flow once
+  --format <fmt>         accepted for maestro cli compat (not used)
+  --device <model>       override the flow frontmatter device for this run
+  --new                  force a fresh browser window for this run
+  --headed               force a fresh, VISIBLE window (implies --new,
+                         overrides --headless) — watch the flow run live
+  --record               record a webm while the flow runs
+  --preview              record events+video, upload, and print /preview/<id>
+  --preview-open         open the uploaded preview link after a successful run
+  --preview-origin <url> upload target for --preview
+  --preview-public-origin <url>
+                         public link origin for --preview
+  --slow <ms>            delay between steps for natural pacing
+
+examples:
+  rnx maestro test .maestro/login.yaml
+  rnx maestro test .maestro/
+  rnx maestro generate "log in and verify the welcome screen"
+  rnx maestro start
+  rnx maestro end --output .maestro/login.yaml --validate
+  rnx maestro --env USERNAME=alice test .maestro/login.yaml
+  rnx maestro init
+`)
+}
+
+function printCompatMatrix() {
+  console.log(`
+rnx maestro — compatibility matrix
+
+supported verbs:
+  launchApp (including arguments), stopApp, clearState, clearKeychain (warn-only),
+  tapOn, tapAtCoords, longPressOn,
+  inputText, pressKey, dispatchKey, hideKeyboard, eraseText,
+  assertVisible, assertNotVisible, assertTreeContains,
+  waitFor, extendedWaitUntil, waitForAnimationToEnd,
+  scroll, scrollUntilVisible, scrollTo, swipe, pinch,
+  takeScreenshot, dumpTree, back,
+  repeat (times), retry (maxRetries + commands), runFlow (file / inline commands / env / when),
+  runScript (maestro JS: http, json(), output, env vars, console.log),
+  evalScript, copyTextFrom (\${maestro.copiedText}), openLink,
+  when: (visible / notVisible / platform / true),
+  optional:, label:, onFlowStart, onFlowComplete,
+  \${...} JS-expression interpolation at step execution time
+  (env vars as globals, output.*, maestro.*, \${EXPR || 'default'}).
+
+workspace mode (directory runs):
+  config.yaml / config.yml discovery, flows: inclusion globs,
+  includeTags / excludeTags against flow frontmatter tags.
+
+launch behavior:
+  launchApp.arguments: a JSON object available before guest app entry through
+    react-native-launch-arguments and NativeModules.SettingsManager.settings.
+  stopApp: keeps the guest stopped until launchApp or openLink starts it.
+  openLink: replaces the guest, then delivers the URL to the new tenant.
+
+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 — 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.
+  env — rnx seeds the JS env from the full shell environment, not just
+    MAESTRO_* (so \${SOOTSIM_*} credentials resolve); a bare \${NAME} that is
+    undefined fails the step loudly instead of typing "undefined".
+
+not yet implemented (will throw "unsupported maestro verb"):
+  travel, setLocation, setAirplaneMode, killApp, faker,
+  addMedia, startRecording, stopRecording (use --record flag),
+  repeat.while (only repeat.times is supported).
+`)
+}
+
+function looksLikeFlag(s: string): boolean {
+  return s.startsWith('-')
+}
+
+// extract --env KEY=VALUE pairs from argv and apply to process.env for the
+// duration of the run. returns argv with the consumed flags removed so the
+// rest can be forwarded to runFlowPlayback verbatim.
+function applyEnvFlags(args: string[]): string[] {
+  const out: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--env' || args[i] === '-e') {
+      const kv = args[i + 1]
+      if (!kv || !kv.includes('=')) {
+        throw new Error(`--env expects KEY=VALUE (got ${JSON.stringify(kv ?? '')})`)
+      }
+      const eq = kv.indexOf('=')
+      const key = kv.slice(0, eq)
+      const value = kv.slice(eq + 1)
+      process.env[key] = value
+      i += 1
+      continue
+    }
+    out.push(args[i])
+  }
+  return out
+}
+
+// maestro-cli flags with no rnx equivalent, accepted so an existing script can
+// swap `maestro` for `rnx maestro` unedited. each one says out loud that it is
+// being ignored: an option that is quietly dropped is how a run reports success
+// while doing something other than what was asked. `--origin` is consumed here
+// because only this command reads it; everything else this function leaves
+// alone rides on to the flow runner, which rejects what it does not know.
+function stripMaestroCompatFlags(args: string[]): string[] {
+  const out: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--format' || a === '--output') {
+      console.warn(`  warn: ${a} is accepted for maestro cli compatibility and ignored`)
+      i += 1
+      continue
+    }
+    if (a === '--origin') {
+      // read above for the run-registration origin. the flow runner has no
+      // --origin, so it must not ride into playbackArgs.
+      i += 1
+      continue
+    }
+    if (a === '-d') {
+      // maestro's short form for --device. rnx's device flag names a device
+      // model, and the flow runner reads it under the long spelling only.
+      out.push('--device')
+      continue
+    }
+    if (a === '--continuous') {
+      console.warn('  warn: --continuous is not implemented in rnx — running once')
+      continue
+    }
+    out.push(a)
+  }
+  return out
+}
+
+function findDefaultMaestroTarget(cwd: string): string | null {
+  for (const dir of MAESTRO_DIRS) {
+    const abs = path.join(cwd, dir)
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) return abs
+  }
+  return null
+}
+
+interface MaestroWorkspaceConfig {
+  flows?: string[]
+  includeTags?: string[]
+  excludeTags?: string[]
+}
+
+// workspace planning for directory targets — mirrors maestro's
+// WorkspaceExecutionPlanner: discover config.yaml/config.yml in the
+// directory, walk it recursively for *.yaml/*.yml flow files (config files
+// excluded), keep the ones matching the config's `flows:` globs (default
+// `*` = top level only), then filter by includeTags/excludeTags against
+// each flow's frontmatter `tags:`.
+export function collectFlowFiles(target: string): string[] {
+  const stat = fs.statSync(target)
+  if (stat.isFile()) return [target]
+  if (!stat.isDirectory()) {
+    throw new Error(`not a file or directory: ${target}`)
+  }
+
+  let config: MaestroWorkspaceConfig = {}
+  const configPath = ['config.yaml', 'config.yml']
+    .map((name) => path.join(target, name))
+    .find((p) => fs.existsSync(p))
+  if (configPath) {
+    // yaml.parse returns any; shape-check the fields we use below instead
+    // of trusting the file
+    const parsed = yaml.parse(fs.readFileSync(configPath, 'utf8'))
+    if (parsed && typeof parsed === 'object') {
+      config = parsed
+    }
+  }
+
+  const globs =
+    Array.isArray(config.flows) && config.flows.length > 0 ? config.flows : ['*']
+  const isFlowFile = (rel: string) => {
+    const base = path.basename(rel)
+    if (base.startsWith('.')) return false
+    if (!base.endsWith('.yaml') && !base.endsWith('.yml')) return false
+    if (base === 'config.yaml' || base === 'config.yml') return false
+    return true
+  }
+  const matched = new Set<string>()
+  for (const glob of globs) {
+    for (const rel of fs.globSync(glob, { cwd: target })) {
+      if (!isFlowFile(rel)) continue
+      const abs = path.join(target, rel)
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) matched.add(abs)
+    }
+  }
+  let files = [...matched].sort()
+
+  const includeTags = Array.isArray(config.includeTags) ? config.includeTags : []
+  const excludeTags = Array.isArray(config.excludeTags) ? config.excludeTags : []
+  if (includeTags.length > 0 || excludeTags.length > 0) {
+    files = files.filter((file) => {
+      const { frontmatter } = parseFlowFile(fs.readFileSync(file, 'utf8'))
+      const tags: string[] = Array.isArray(frontmatter.tags) ? frontmatter.tags : []
+      if (includeTags.length > 0 && !tags.some((t) => includeTags.includes(t))) {
+        return false
+      }
+      if (tags.some((t) => excludeTags.includes(t))) return false
+      return true
+    })
+  }
+  return files
+}
+
+async function runInit(cwd: string): Promise<number> {
+  const dir = path.join(cwd, '.maestro')
+  fs.mkdirSync(dir, { recursive: true })
+  const outPath = path.join(dir, 'login.yaml')
+  if (fs.existsSync(outPath)) {
+    console.error(`  error: ${outPath} already exists`)
+    return 1
+  }
+  const starter = `# rnx maestro starter flow — drop-in compatible with the maestro cli.
+# run: rnx maestro test .maestro/login.yaml
+appId: com.example.app
+---
+- launchApp
+- tapOn:
+    id: "email"
+- inputText: "user@example.com"
+- tapOn:
+    id: "password"
+- inputText: "secret123"
+- tapOn: "Sign in"
+- assertVisible: "Welcome"
+`
+  fs.writeFileSync(outPath, starter, 'utf8')
+  console.log(`  + wrote ${outPath}`)
+  console.log(`  next: rnx maestro test .maestro/login.yaml`)
+  return 0
+}
+
+export async function runMaestro(
+  args: string[],
+  opts: RunMaestroOptions = {},
+): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp()
+    return 0
+  }
+  if (args.includes('--list-compat')) {
+    printCompatMatrix()
+    return 0
+  }
+
+  let remaining: string[]
+  try {
+    remaining = applyEnvFlags(args)
+  } catch (err) {
+    console.error(`  error: ${(err as Error).message}`)
+    return 1
+  }
+  // bin.ts prepends the global `--sim <id>` to argv. without hoisting it
+  // out, `remaining[0]` is `--sim` instead of the `test` subcommand, so
+  // maestro auto-discovered a default flow and forwarded `--sim`/`test`/
+  // the path as bogus flow args — the explicit sim was silently dropped
+  // (QA F21-4). hoist it to the tail so it still rides into forwardArgs →
+  // runFlowPlayback, where parseBridgeCliArgs sees simIdSource === 'flag'.
+  remaining = hoistLeadingSimFlag(remaining)
+
+  const cwd = process.cwd()
+  const sub = remaining[0]
+
+  if (sub === 'init') {
+    return runInit(cwd)
+  }
+  if (sub === 'generate') {
+    const { runMaestroGenerate } = await import('./maestro-generate')
+    return runMaestroGenerate(remaining.slice(1))
+  }
+  if (
+    sub === 'start' ||
+    sub === 'keep' ||
+    sub === 'good' ||
+    sub === 'end' ||
+    sub === 'validate'
+  ) {
+    return runMaestroAuthoring(remaining)
+  }
+  // `--origin` names the Contrast instance that hosts the run row. this command
+  // is its only reader, so read it before stripMaestroCompatFlags consumes it.
+  const originFlagIndex = remaining.indexOf('--origin')
+  const originFlagValue =
+    originFlagIndex >= 0 ? remaining[originFlagIndex + 1] : undefined
+  remaining = stripMaestroCompatFlags(remaining)
+
+  // resolve the target flow file or directory.
+  let target: string | null = null
+  let forwardArgs: string[]
+
+  if (sub === 'test') {
+    // `rnx maestro test <flow-or-dir> [flags...]`. the flow path is the first
+    // token that is neither a flag nor the value of one — without the second
+    // half, `test --sim a2 login.yaml` takes `a2` as the flow file. remove it
+    // by index, since a path can equal a flag value elsewhere in the argv.
+    const rest = remaining.slice(1)
+    const positionalIndex = rest.findIndex(
+      (a, i) =>
+        !looksLikeFlag(a) && !(i > 0 && FLOW_ARG_VALUE_FLAGS.includes(rest[i - 1])),
+    )
+    if (positionalIndex >= 0) {
+      target = path.resolve(cwd, rest[positionalIndex])
+      forwardArgs = rest.filter((_, i) => i !== positionalIndex)
+    } else {
+      target = findDefaultMaestroTarget(cwd)
+      forwardArgs = rest
+    }
+  } else if (sub && !looksLikeFlag(sub)) {
+    // `rnx maestro <flow-or-dir>` — tolerate the shorthand.
+    target = path.resolve(cwd, sub)
+    forwardArgs = remaining.slice(1)
+  } else {
+    // no positional — auto-discover.
+    target = findDefaultMaestroTarget(cwd)
+    forwardArgs = remaining
+  }
+
+  // every flag here is forwarded to each flow, so check the vocabulary once,
+  // before anything opens a sim. runFlowPlayback checks again for its
+  // programmatic callers; doing it here keeps a directory run from printing
+  // the same rejection once per flow after it has already started work.
+  const unexpected = findUnexpectedFlowArgs(['<flow>', ...forwardArgs])
+  if (unexpected.length > 0) {
+    for (const problem of unexpected) {
+      console.error(`  error: ${problem.message}`)
+    }
+    console.error('\n  run `rnx maestro --help` for the flags this command accepts')
+    return 1
+  }
+
+  if (!target) {
+    console.error(`
+  error: no maestro flows found.
+  expected one of: ${MAESTRO_DIRS.map((d) => `./${d}/`).join(', ')}
+  or pass a flow explicitly:    rnx maestro test path/to/flow.yaml
+  or scaffold a starter flow:   rnx maestro init
+`)
+    return 1
+  }
+
+  if (!fs.existsSync(target)) {
+    console.error(`  error: ${target} not found`)
+    return 1
+  }
+
+  let files: string[]
+  try {
+    files = collectFlowFiles(target)
+  } catch (err) {
+    console.error(`  error: ${(err as Error).message}`)
+    return 1
+  }
+
+  if (files.length === 0) {
+    console.error(`  error: no *.yaml or *.yml files found in ${target}`)
+    return 1
+  }
+
+  console.log(`
+  rnx maestro — ${files.length} flow${files.length === 1 ? '' : 's'}
+  root: ${path.relative(cwd, target) || '.'}
+`)
+
+  // registration target for hosted run rows — resolved once per invocation.
+  const auth = resolveCliAuth()
+  const flagValue = (name: string) => {
+    const index = forwardArgs.indexOf(name)
+    return index >= 0 ? forwardArgs[index + 1] : undefined
+  }
+  // only `registerRun` below consumes this, and only for runs that register.
+  // resolving it up front probed https://contrast.localhost:3000 and blocked
+  // every flow — including ones that upload and register nothing — for the
+  // probe's full 2s timeout whenever no local Contrast stack was listening.
+  // resolve on first use instead, and keep the one probe per invocation.
+  let registerOriginPromise: Promise<string> | null = null
+  const registerOrigin = () =>
+    (registerOriginPromise ??= resolveDefaultUploadOrigin(
+      flagValue('--preview-origin') ?? originFlagValue,
+    ))
+
+  let worstExit = 0
+  const results: Array<{ file: string; exit: number }> = []
+  for (const file of files) {
+    console.log(`\n  ▶ ${path.relative(cwd, file)}`)
+    const playbackArgs = [file, ...forwardArgs]
+    // `--port` is the BRIDGE port everywhere else in the CLI, so forward it as
+    // 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 `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.
+    if (opts.port) {
+      playbackArgs.push('--port', String(opts.port))
+    }
+    let exit = 0
+    const startedAt = Date.now()
+    try {
+      exit = await runFlowPlayback(playbackArgs)
+    } catch (err) {
+      // rnxExit is a deliberate exit that already printed its own reason.
+      // reporting the sentinel's own text on top of it reads like a second,
+      // unrelated failure.
+      if (err instanceof RnxExit) {
+        exit = err.code || 1
+      } else {
+        console.error(`  x ${(err as Error).message}`)
+        exit = 1
+      }
+    }
+    results.push({ file, exit })
+    if (exit !== 0 && worstExit === 0) worstExit = exit
+
+    const upload = getLastFlowPreviewUploadResult()
+    if (upload?.shareId || upload?.previewUrl) {
+      try {
+        fs.writeFileSync(
+          path.join(cwd, 'preview-result.json'),
+          JSON.stringify({
+            previewId: upload.shareId,
+            previewUrl: upload.previewUrl,
+          }),
+        )
+      } catch {}
+    } else if (args.includes('--preview')) {
+      console.error('  error: required hosted recording upload failed')
+      if (exit === 0) exit = 1
+      if (worstExit === 0) worstExit = 1
+    }
+
+    if (shouldRegisterRun({ uploadedShare: Boolean(upload), auth })) {
+      const traceSteps = getLastFlowTraceSteps()
+      const failedStep = traceSteps.find((step) => step.status === 'failure')
+      const run = await registerRun({
+        origin: await registerOrigin(),
+        kind: 'maestro',
+        name: path.relative(cwd, file),
+        status: exit === 0 ? 'passed' : 'failed',
+        failureMessage: exit === 0 ? null : (failedStep?.error ?? 'flow playback failed'),
+        previewShareId: upload?.shareId ?? null,
+        owner: flagValue('--owner') ?? null,
+        repo: flagValue('--repo') ?? null,
+        durationMs: Date.now() - startedAt,
+        ...stepSummaryFromTrace(traceSteps),
+        auth,
+      })
+      if (run) {
+        console.log(`  run: ${run.id}${run.traceUrl ? ` · replay: ${run.traceUrl}` : ''}`)
+        try {
+          fs.writeFileSync(
+            path.join(cwd, 'test-result.json'),
+            JSON.stringify({
+              runId: run.id,
+              previewUrl: run.previewUrl,
+              traceUrl: run.traceUrl,
+            }),
+          )
+        } catch {}
+      } else if (process.env.RNX_REQUIRE_REGISTRATION === 'true') {
+        console.error('  error: required hosted run registration failed')
+        if (exit === 0) exit = 1
+        if (worstExit === 0) worstExit = 1
+      }
+    }
+  }
+
+  if (files.length > 1) {
+    console.log(`\n  maestro summary:`)
+    for (const r of results) {
+      const label = r.exit === 0 ? 'pass' : 'fail'
+      console.log(`    ${label}  ${path.relative(cwd, r.file)}`)
+    }
+    const passed = results.filter((r) => r.exit === 0).length
+    console.log(`  ${passed}/${results.length} passed`)
+  }
+
+  return worstExit
+}

package/cli/commands/mode.ts

@@ -0,0 +1,58 @@
+import { rnxExit } from '../run-rnx'
+import { runScreenshotMode } from './screenshot-mode'
+import { runThreeMode } from './three-mode'
+
+interface ModeOptions {
+  port?: number
+  verbose?: boolean
+}
+
+const VALUE_FLAGS = new Set(['--sim', '--port', '-p'])
+const SUBCOMMANDS = new Set(['screenshot', 'three'])
+
+function findSubcommand(args: string[]): { name: string; index: number } | null {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('-')) {
+      if (VALUE_FLAGS.has(arg)) i++
+      continue
+    }
+    return SUBCOMMANDS.has(arg) ? { name: arg, index: i } : null
+  }
+  return null
+}
+
+function withoutSubcommand(args: string[], index: number): string[] {
+  return [...args.slice(0, index), ...args.slice(index + 1)]
+}
+
+function printHelp(): void {
+  console.log(`
+rnx mode — toggle live display modes
+
+usage:
+  rnx mode screenshot [on|off|toggle]
+  rnx mode three [on|off|toggle]
+  rnx mode three configure [options]
+`)
+}
+
+export async function runMode(args: string[], opts: ModeOptions): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp()
+    return
+  }
+
+  const sub = findSubcommand(args)
+  if (!sub) {
+    printHelp()
+    rnxExit(1)
+  }
+
+  const rest = withoutSubcommand(args, sub.index)
+  if (sub.name === 'screenshot') {
+    await runScreenshotMode(rest, opts)
+    return
+  }
+  await runThreeMode(rest, opts)
+}

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

@@ -0,0 +1,80 @@
+// shared hint printed when the CLI has no bridge or no desktop companion.
+
+import { findDesktopCompanion } from '../desktop-companion'
+import type { BridgeSimInfo } from '../ws-bridge'
+
+export function printMissingCompanionHint() {
+  console.error('  no rnx desktop companion found.')
+  console.error('')
+  console.error('  install the desktop app:')
+  console.error('    rnx desktop install')
+  console.error('')
+  console.error('  or install the recommended background service:')
+  console.error('    rnx daemon install')
+  console.error('')
+}
+
+export function printMissingBridgeHint(port: number) {
+  const companion = findDesktopCompanion()
+  console.log(`  note: no rnx bridge detected on port ${port}`)
+  if (companion) {
+    console.log(`  launch the installed companion with:`)
+    console.log(`    rnx desktop`)
+    return
+  }
+  console.log('')
+  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.')
+}
+
+export function printMissingSimHint(port: number) {
+  console.error('')
+  console.error(`  no sim is connected to the rnx bridge on port ${port}.`)
+  console.error('')
+  console.error('  start your app dev server, then open it in rnx:')
+  console.error('    npx expo start --localhost --port 8081')
+  console.error('    rnx open 8081')
+  console.error('')
+  console.error('  then inspect the live app:')
+  console.error('    rnx describe')
+}
+
+// printed when a command targeted a specific `--sim <id>` that the bridge
+// does not know — distinct from printMissingSimHint, which assumes the bridge
+// has no sims at all. when other sims *are* connected, "no sim is connected"
+// is a flat-out lie; list the valid ids instead so the user can pick one.
+export async function printUnknownSimHint(
+  bridge: { listSims: () => Promise<BridgeSimInfo[]> },
+  port: number,
+  requestedId: string,
+) {
+  let sims: BridgeSimInfo[] = []
+  try {
+    sims = await bridge.listSims()
+  } catch {
+    // bridge unreachable while reporting — fall through to the generic hint
+  }
+  console.error('')
+  if (sims.length === 0) {
+    printMissingSimHint(port)
+    return
+  }
+  console.error(
+    `  no sim with id "${requestedId}" is connected to the bridge on port ${port}.`,
+  )
+  console.error('')
+  console.error('  connected sims:')
+  for (const sim of sims) {
+    const flags = [
+      sim.isPrimary ? 'primary' : null,
+      sim.readyState,
+      sim.userVisible === false ? 'hidden' : sim.userVisible === true ? 'visible' : null,
+      sim.userFocused ? 'focused' : null,
+    ]
+      .filter(Boolean)
+      .join(', ')
+    console.error(`    ${sim.id}  (${flags})`)
+  }
+  console.error('')
+  console.error('  pass a valid --sim id, or run `rnx list` to see all sessions.')
+}