rnxsim 0.1.376 → 0.1.377

package/cli/command-contract.ts

@@ -0,0 +1,221 @@
+export type RnxBackendKind = 'node' | 'browser'
+
+export interface CommandWriter {
+  stdout(text: string): void
+  stderr(text: string): void
+}
+
+export interface SemanticInvocation {
+  tool: string
+  input: unknown
+  success: boolean
+  details?: unknown
+}
+
+export interface ImageCommandArtifact {
+  kind: 'image'
+  name: string
+  mediaType: string
+  data: Uint8Array | string
+  runtimeClaim?: unknown
+}
+
+export interface FileCommandArtifact {
+  kind: 'file'
+  path: string
+  mediaType?: string
+  runtimeClaim?: unknown
+}
+
+export interface RuntimeCommandArtifact {
+  kind: 'runtime'
+  runtimeClaim: unknown
+}
+
+export interface UrlCommandArtifact {
+  kind: 'url'
+  url: string
+  label?: string
+  runtimeClaim?: unknown
+}
+
+export type CommandArtifact =
+  | ImageCommandArtifact
+  | FileCommandArtifact
+  | RuntimeCommandArtifact
+  | UrlCommandArtifact
+
+export interface CommandExecutionResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+  invocations: SemanticInvocation[]
+  artifacts: CommandArtifact[]
+}
+
+export interface RnxInvocationBase {
+  command: string
+  args: string[]
+  globalFlags: Record<string, string | boolean | number>
+}
+
+export interface RnxParsedCommandInput {
+  command: string
+  args: string[]
+  globalFlags: Record<string, string | boolean | number>
+}
+
+export interface RnxPreviewInvocation extends RnxInvocationBase {
+  family: 'preview'
+  command: 'web' | 'ios'
+  platform: 'web' | 'ios'
+  selection: 'select-or-ensure-existing'
+}
+
+export interface RnxRuntimeInvocation extends RnxInvocationBase {
+  family: 'runtime'
+}
+
+export interface RnxTreeInvocation extends RnxInvocationBase {
+  family: 'tree'
+}
+
+export interface RnxLayoutInvocation extends RnxInvocationBase {
+  family: 'layout'
+}
+
+export interface RnxFindInvocation extends RnxInvocationBase {
+  family: 'find'
+  command: 'find'
+}
+
+export interface RnxWaitInvocation extends RnxInvocationBase {
+  family: 'wait'
+  command: 'wait'
+}
+
+export interface RnxActionInvocation extends RnxInvocationBase {
+  family: 'action'
+}
+
+export interface RnxScreenshotInvocation extends RnxInvocationBase {
+  family: 'screenshot'
+  command: 'screenshot'
+}
+
+export interface RnxLogsInvocation extends RnxInvocationBase {
+  family: 'logs'
+}
+
+export interface RnxNetworkInvocation extends RnxInvocationBase {
+  family: 'network'
+}
+
+export interface RnxStorageInvocation extends RnxInvocationBase {
+  family: 'storage'
+  command: 'storage'
+}
+
+export interface RnxHistoryInvocation extends RnxInvocationBase {
+  family: 'history'
+  command: 'timeline' | 'what-happened'
+}
+
+export interface RnxEvidenceInvocation extends RnxInvocationBase {
+  family: 'evidence'
+}
+
+export type RnxCommandInvocation =
+  | RnxPreviewInvocation
+  | RnxRuntimeInvocation
+  | RnxTreeInvocation
+  | RnxLayoutInvocation
+  | RnxFindInvocation
+  | RnxWaitInvocation
+  | RnxActionInvocation
+  | RnxScreenshotInvocation
+  | RnxLogsInvocation
+  | RnxNetworkInvocation
+  | RnxStorageInvocation
+  | RnxHistoryInvocation
+  | RnxEvidenceInvocation
+
+export interface RnxExecutionContext {
+  writer: CommandWriter
+  signal: AbortSignal
+}
+
+export interface RnxBackendExecution {
+  exitCode: number
+  invocations: SemanticInvocation[]
+  artifacts: CommandArtifact[]
+}
+
+export interface RnxCommandBackend {
+  readonly kind: RnxBackendKind
+  execute(
+    invocation: RnxCommandInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+}
+
+export interface RnxBrowserOperations {
+  selectPreview(
+    invocation: RnxPreviewInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  readRuntime(
+    invocation: RnxRuntimeInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  inspectTree(
+    invocation: RnxTreeInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  inspectLayout(
+    invocation: RnxLayoutInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  find(
+    invocation: RnxFindInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  wait(
+    invocation: RnxWaitInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  act(
+    invocation: RnxActionInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  screenshot(
+    invocation: RnxScreenshotInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  readLogs(
+    invocation: RnxLogsInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  readNetwork(
+    invocation: RnxNetworkInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  accessStorage(
+    invocation: RnxStorageInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  readHistory(
+    invocation: RnxHistoryInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+  collectEvidence(
+    invocation: RnxEvidenceInvocation,
+    context: RnxExecutionContext,
+  ): Promise<RnxBackendExecution>
+}
+
+export interface RunRnxCoreOptions {
+  backend: RnxCommandBackend
+  signal?: AbortSignal
+  writer?: CommandWriter
+}

package/cli/command-registry.ts

@@ -0,0 +1,291 @@
+import type {
+  RnxBackendKind,
+  RnxCommandInvocation,
+  RnxParsedCommandInput,
+} from './command-contract'
+
+export type RnxBrowserCommandFamily = RnxCommandInvocation['family']
+
+export interface RnxCommandRegistration {
+  name: string
+  node: boolean
+  browserFamily: RnxBrowserCommandFamily | null
+}
+
+export interface RnxCommandAvailability {
+  available: boolean
+  reason: string | null
+}
+
+const NODE_COMMAND_NAMES = [
+  'detox',
+  'maestro',
+  'record',
+  'film',
+  'storage',
+  'permissions',
+  'perf',
+  'screenshot',
+  'state',
+  'reset',
+  'camera',
+  'mode',
+  'debug',
+  'timeline',
+  'what-happened',
+  'shell',
+  'assert',
+  'device',
+  'open',
+  'ios',
+  'android',
+  'box',
+  'list',
+  'use',
+  'claim',
+  'close',
+  'compat',
+  'report-issue',
+  'desktop',
+  'login',
+  'logout',
+  'auth',
+  'setup',
+  'serve',
+  'daemon',
+  'runtime',
+  'upgrade',
+  'version',
+  'skill',
+  'config',
+  'cleanup',
+  'app-fonts',
+  'agent-wrapper',
+  'agent',
+  'describe',
+  'find',
+  'get',
+  'do',
+  'wait',
+  'network',
+  'logs',
+] satisfies string[]
+
+const BROWSER_FAMILIES = new Map<string, RnxBrowserCommandFamily>([
+  ['web', 'preview'],
+  ['ios', 'preview'],
+  ['list', 'runtime'],
+  ['use', 'runtime'],
+  ['state', 'runtime'],
+  ['describe', 'tree'],
+  ['find', 'find'],
+  ['get', 'runtime'],
+  ['wait', 'wait'],
+  ['do', 'action'],
+  ['shell', 'action'],
+  ['reset', 'action'],
+  ['screenshot', 'screenshot'],
+  ['logs', 'logs'],
+  ['network', 'network'],
+  ['storage', 'storage'],
+  ['timeline', 'history'],
+  ['what-happened', 'history'],
+  ['assert', 'evidence'],
+  ['debug', 'evidence'],
+  ['perf', 'evidence'],
+])
+
+const registrations = [
+  ...new Set([...NODE_COMMAND_NAMES, 'web']),
+].map<RnxCommandRegistration>((name) => ({
+  name,
+  node: name !== 'web',
+  browserFamily: BROWSER_FAMILIES.get(name) ?? null,
+}))
+
+export const RNX_COMMAND_REGISTRY: readonly RnxCommandRegistration[] = registrations
+export const RNX_COMMAND_NAMES = new Set(registrations.map((entry) => entry.name))
+
+// retained for registry drift checks that compare the established node CLI
+// with its generated public docs. browser-only selectors have local help.
+export const RNX_NODE_COMMAND_NAMES = new Set(NODE_COMMAND_NAMES)
+
+const VALUE_FLAGS = new Set([
+  '--sim',
+  '--session',
+  '--tab',
+  '--port',
+  '-p',
+  '--timeout',
+  '--device',
+  '--output',
+  '-o',
+  '--out',
+  '--plan',
+  '--level',
+  '--filter',
+  '--threshold',
+  '--limit',
+  '--since',
+  '--kinds',
+])
+
+const BROWSER_SCREENSHOT_SUBCOMMANDS = new Set(['capture', 'ask', 'appearance', 'motion'])
+
+export function getRnxFirstPositional(args: readonly string[]): string | null {
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (arg.startsWith('-')) {
+      if (VALUE_FLAGS.has(arg)) index++
+      continue
+    }
+    return arg
+  }
+  return null
+}
+
+export function getRnxCommandRegistration(name: string): RnxCommandRegistration | null {
+  return RNX_COMMAND_REGISTRY.find((entry) => entry.name === name) ?? null
+}
+
+export function getRnxCommandAvailability(
+  command: string,
+  args: readonly string[],
+  backend: RnxBackendKind,
+): RnxCommandAvailability {
+  const registration = getRnxCommandRegistration(command)
+  if (!registration) {
+    return { available: false, reason: `unknown command: ${command}` }
+  }
+
+  if (backend === 'node') {
+    return registration.node
+      ? { available: true, reason: null }
+      : {
+          available: false,
+          reason:
+            'rnx web is available in the browser backend, where it selects the existing web preview.',
+        }
+  }
+
+  if (!registration.browserFamily) {
+    return {
+      available: false,
+      reason: `rnx ${command} is unavailable in the browser backend; it requires the node backend.`,
+    }
+  }
+
+  const subcommand = getRnxFirstPositional(args)
+  if (command === 'shell' && subcommand && subcommand !== 'appearance') {
+    return {
+      available: false,
+      reason: `rnx shell ${subcommand} is unavailable in the browser backend; Factory exposes no semantic operation for it.`,
+    }
+  }
+  if (
+    command === 'shell' &&
+    subcommand === 'appearance' &&
+    args[1] !== undefined &&
+    args[1] !== 'light' &&
+    args[1] !== 'dark'
+  ) {
+    return {
+      available: false,
+      reason: 'rnx shell appearance supports light or dark in the browser backend.',
+    }
+  }
+  if (command === 'storage' && subcommand === 'profile') {
+    return {
+      available: false,
+      reason:
+        'rnx storage profile is unavailable in the browser backend; use rnx storage clear for the selected preview.',
+    }
+  }
+  const screenshotSubcommand = command === 'screenshot' ? subcommand : null
+  if (
+    screenshotSubcommand !== null &&
+    !BROWSER_SCREENSHOT_SUBCOMMANDS.has(screenshotSubcommand)
+  ) {
+    return {
+      available: false,
+      reason: `rnx screenshot ${screenshotSubcommand} is unavailable in the browser backend; it requires the node backend.`,
+    }
+  }
+  if (command === 'timeline' && subcommand === 'dump') {
+    return {
+      available: false,
+      reason:
+        'rnx timeline dump is unavailable in the browser backend because it writes to the host filesystem.',
+    }
+  }
+
+  return { available: true, reason: null }
+}
+
+export function createRnxCommandInvocation(
+  input: RnxParsedCommandInput,
+): RnxCommandInvocation {
+  const common = {
+    command: input.command,
+    args: [...input.args],
+    globalFlags: { ...input.globalFlags },
+  }
+
+  switch (input.command) {
+    case 'web':
+      return {
+        ...common,
+        family: 'preview',
+        command: 'web',
+        platform: 'web',
+        selection: 'select-or-ensure-existing',
+      }
+    case 'ios':
+      return {
+        ...common,
+        family: 'preview',
+        command: 'ios',
+        platform: 'ios',
+        selection: 'select-or-ensure-existing',
+      }
+    case 'describe':
+      return { ...common, family: 'tree' }
+    case 'find':
+      return { ...common, family: 'find', command: 'find' }
+    case 'get': {
+      const noun = getRnxFirstPositional(input.args)
+      if (noun === 'tree' || noun === 'a11y') return { ...common, family: 'tree' }
+      if (noun === 'layout') return { ...common, family: 'layout' }
+      if (noun === 'requests') return { ...common, family: 'network' }
+      if (noun === 'errors' || noun === 'warnings') return { ...common, family: 'logs' }
+      if (noun === 'diagnosis') return { ...common, family: 'evidence' }
+      return { ...common, family: 'runtime' }
+    }
+    case 'wait':
+      return { ...common, family: 'wait', command: 'wait' }
+    case 'do':
+    case 'shell':
+    case 'reset':
+    case 'permissions':
+    case 'camera':
+      return { ...common, family: 'action' }
+    case 'screenshot':
+      return { ...common, family: 'screenshot', command: 'screenshot' }
+    case 'logs':
+      return { ...common, family: 'logs', command: 'logs' }
+    case 'network':
+      return { ...common, family: 'network', command: 'network' }
+    case 'storage':
+      return { ...common, family: 'storage', command: 'storage' }
+    case 'timeline':
+      return { ...common, family: 'history', command: 'timeline' }
+    case 'what-happened':
+      return { ...common, family: 'history', command: 'what-happened' }
+    case 'assert':
+    case 'debug':
+    case 'perf':
+      return { ...common, family: 'evidence' }
+    default:
+      return { ...common, family: 'runtime' }
+  }
+}

package/cli/commands/agent-wrapper.ts

@@ -229,7 +229,7 @@ export async function runAgentWrapper(argv: string[]): Promise<number> {
         bin: resolvedAgentBin,
         cwd,
         env: {
-          SOOTSIM_CLI_IDENTITY: sessionId,
+          RNX_CLI_IDENTITY: sessionId,
           SOOTSIM_PROJECT_ID: projectId,
         },
       })
@@ -827,7 +827,7 @@ function buildClaudeTurnRunner(deps: ClaudeTurnDeps): TurnRunner {
         stdio: ['ignore', 'pipe', 'pipe'],
         env: {
           ...process.env,
-          SOOTSIM_CLI_IDENTITY: sessionId,
+          RNX_CLI_IDENTITY: sessionId,
           SOOTSIM_PROJECT_ID: projectId,
         },
       },

package/cli/commands/app-fonts.ts

@@ -1,4 +1,4 @@
-// sootsim app-fonts stage — fetch the config-plugin fonts declared on an
+// rnx app-fonts stage — fetch the config-plugin fonts declared on an
 // engine `?appFonts=` wire, gzip them, and merge asset descriptors into a
 // build's asset manifest.
 //
@@ -9,7 +9,7 @@
 // after the asset capture; the descriptors land in the same manifest the
 // upload step already PUTs, keyed by sha256(url) so the rendered build resolves
 // each font through /api/preview/share/fetch?url=<fontUrl> identically to the
-// preview path (`sootsim record upload`). both pipelines share fetchAppFontFiles.
+// preview path (`rnx record upload`). both pipelines share fetchAppFontFiles.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'

package/cli/commands/assert.ts

@@ -1,4 +1,4 @@
-// `sootsim assert <verb> <verb-args...> <assertion-flags...>`
+// `rnx assert <verb> <verb-args...> <assertion-flags...>`
 //
 // thin wrapper that runs any read verb with --json forced on, captures the
 // JSON payload, and converts predicate flags into a bisect-friendly exit
@@ -17,7 +17,7 @@ import { spawn } from 'child_process'
 import { rnxExit } from '../run-rnx'
 
 // READ_VERBS lists every command whose stdout we know is valid JSON under
-// --json. keeping this explicit means `sootsim assert tap 100 200` fails
+// --json. keeping this explicit means `rnx assert tap 100 200` fails
 // fast with a clear message instead of silently running a write verb and
 // trying to parse "  tapped 100,200" as JSON.
 const READ_VERBS = new Set([
@@ -46,7 +46,7 @@ const READ_VERBS = new Set([
 
 // assertion flags that assert recognizes. everything else is passed through
 // to the inner verb untouched. keeping this as a set (rather than positional
-// parsing) means `sootsim assert find --testid X --count 4` reads naturally.
+// parsing) means `rnx assert find --testid X --count 4` reads naturally.
 const BOOL_ASSERT_FLAGS = new Set([
   '--exists',
   '--empty',

package/cli/commands/auth.ts

@@ -9,7 +9,7 @@ rnx auth — inspect CLI auth
 usage:
   rnx auth
 
-API keys are read from RNX_API_KEY, or SOOTSIM_API_KEY if that is unset.
+API keys are read from RNX_API_KEY.
 Use \`rnx login\` to sign in and \`rnx logout\` to clear the desktop session.
 `)
 }

package/cli/commands/box/cloud-box.ts

@@ -11,7 +11,7 @@
 // exist, and pointing at a URL that answers nothing would advertise a
 // capability that always fails.
 
-import WebSocket from 'ws'
+import { WebSocket } from 'ws'
 import type { CheckoutFilePlane } from './checkout-plane'
 import type { HarnessShellResult } from '@contrast/harness/shell'
 

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

@@ -17,10 +17,10 @@
 // resolveBridgeWorld reports source 'default' and hands back
 // DEFAULT_SOOTSIM_BRIDGE_PORT, which on a machine running a real daemon is
 // that daemon. registering there would attach a test's or a benchmark's box to
-// another session's daemon, which is exactly what a private SOOTSIM_HOME
+// another session's daemon, which is exactly what a private RNX_HOME
 // exists to prevent. so a guessed port is refused by name.
 
-import WebSocket from 'ws'
+import { WebSocket } from 'ws'
 import { bridgeWsUrl, resolveBridgeWorld } from '../../ws-bridge'
 
 const REGISTER_TIMEOUT_MS = 1500

package/cli/commands/box.ts

@@ -313,12 +313,10 @@ async function runLocalBox(opts: BoxCommandOptions): Promise<number> {
 
   const shell = createHarnessShell({
     projectFs: new HarnessProjectFs(plane),
-    commands: [
-      createRnxCommand({ root, shellCwd: () => shell.cwd }),
-      // overrides just-bash's JavaScript rg, which reads every file body
-      // through the plane. see search-command.ts for the numbers.
-      createSearchCommand({ root }),
-    ],
+    commands: [createRnxCommand({ root, shellCwd: () => shell.cwd })],
+    // just-bash's JavaScript rg reads every file body through the plane.
+    // see search-command.ts for the numbers.
+    builtInCommandOverrides: [createSearchCommand({ root })],
   })
 
   const relative = path.relative(root, process.cwd())

package/cli/commands/compat.ts

@@ -1,4 +1,4 @@
-// sootsim compat — scan dependencies with the shared compatibility engine.
+// rnx compat — scan dependencies with the shared compatibility engine.
 
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'

package/cli/commands/config.ts

@@ -9,8 +9,8 @@ usage:
   rnx config telemetry [on|off|status]
 
 environment:
-  SOOTSIM_HINTS=off       suppress CLI hints
-  SOOTSIM_HINTS=always    show every CLI hint every time
+  RNX_HINTS=off       suppress CLI hints
+  RNX_HINTS=always    show every CLI hint every time
 `)
 }