rnxsim 0.1.380 → 0.1.382

package/cli/cloud-dispatch.ts

@@ -0,0 +1,165 @@
+interface CloudBoundaryInvocation {
+  command: string
+  args: string[]
+}
+
+export type CloudBoundaryResult = { handled: false } | { handled: true; code: number }
+
+const CLOUD_TARGET_COMMANDS = new Set([
+  'assert',
+  'camera',
+  'claim',
+  'close',
+  'debug',
+  'describe',
+  'detox',
+  'do',
+  'film',
+  'find',
+  'get',
+  'logs',
+  'maestro',
+  'mode',
+  'network',
+  'perf',
+  'permissions',
+  'record',
+  'reset',
+  'screenshot',
+  'shell',
+  'state',
+  'storage',
+  'timeline',
+  'wait',
+  'what-happened',
+])
+
+function firstVerb(positional: string[]): string | null {
+  return positional.find((value) => !value.startsWith('-')) ?? null
+}
+
+function supportsCloudRead(
+  command: string,
+  args: string[],
+  positional: string[],
+): boolean {
+  if (command === 'describe' || command === 'find') return true
+  if (command === 'state') return firstVerb(positional) === null
+  if (command === 'get') {
+    const verb = firstVerb(positional)
+    return verb === 'tree' || verb === 'node' || verb === 'count'
+  }
+  if (command === 'wait') {
+    const verb = firstVerb(positional)
+    return verb === 'ready' || verb === 'selector'
+  }
+  if (command === 'logs') {
+    const verb = firstVerb(positional)
+    return (
+      !args.includes('--tail') &&
+      !args.includes('-f') &&
+      verb !== 'tail' &&
+      verb !== 'clear' &&
+      verb !== 'purge'
+    )
+  }
+  if (command === 'screenshot') {
+    return !args.some((arg) =>
+      [
+        '--area',
+        '--gallery',
+        '--id',
+        '--no-shell',
+        '--shell-only',
+        '--text',
+        '--themes',
+        '--with-frame',
+      ].includes(arg),
+    )
+  }
+  return false
+}
+
+function refuseCloudInvocation(
+  command: string,
+  positional: string[],
+): CloudBoundaryResult {
+  const verb = firstVerb(positional)
+  const name = verb ? `${command} ${verb}` : command
+  console.error(`  rnx ${name} is not available for an RNX Cloud simulator`)
+  return { handled: true, code: 1 }
+}
+
+export async function dispatchCloudBoundary({
+  command,
+  args,
+}: CloudBoundaryInvocation): Promise<CloudBoundaryResult> {
+  if (command === 'ios' && args.includes('--cloud')) return { handled: false }
+  if (command === 'android' && args.includes('--cloud')) {
+    console.error(
+      '  rnx android --cloud is not available; RNX Cloud currently supports iOS',
+    )
+    return { handled: true, code: 1 }
+  }
+  if (!CLOUD_TARGET_COMMANDS.has(command)) return { handled: false }
+
+  const [{ parseBridgeCliArgs }, cloudClient, cloudSession] = await Promise.all([
+    import('./ws-bridge'),
+    import('./cloud-client'),
+    import('./cloud-session'),
+  ])
+  const parsed = parseBridgeCliArgs(args)
+  const positionalTarget =
+    command === 'claim' || command === 'close' ? firstVerb(parsed.positional) : null
+  const target: Pick<typeof parsed, 'simId' | 'simIdSource'> = positionalTarget
+    ? { simId: positionalTarget, simIdSource: 'flag' }
+    : parsed
+  let session
+  try {
+    session = cloudClient.resolveCloudSessionForParsed(target)
+  } catch (error) {
+    console.error(`  ${error instanceof Error ? error.message : String(error)}`)
+    return { handled: true, code: 1 }
+  }
+  if (!session) return { handled: false }
+
+  if (command === 'claim') {
+    try {
+      const descriptor = cloudSession.requireCloudSessionShellUpdate()
+      const claimed = await cloudClient.claimCloudSimulator(session, {
+        force: args.includes('--force'),
+      })
+      cloudSession.publishCloudSessionToShell(claimed.session, descriptor)
+      console.log(`  claimed: ${session.simId}`)
+      console.log(`  expires: ${claimed.claim.expiresAt}`)
+      return { handled: true, code: 0 }
+    } catch (error) {
+      console.error(
+        `  claim failed: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      return { handled: true, code: 1 }
+    }
+  }
+
+  if (command === 'close') {
+    if (args.includes('--all') || args.includes('--others')) {
+      return refuseCloudInvocation(command, parsed.positional)
+    }
+    try {
+      const descriptor = cloudSession.requireCloudSessionShellUpdate()
+      await cloudClient.closeCloudSimulator(session)
+      cloudSession.publishCloudSessionToShell(null, descriptor)
+      console.log(`  closed: ${session.simId}`)
+      return { handled: true, code: 0 }
+    } catch (error) {
+      console.error(
+        `  close failed: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      return { handled: true, code: 1 }
+    }
+  }
+
+  return supportsCloudRead(command, args, parsed.positional)
+    ? { handled: false }
+    : refuseCloudInvocation(command, parsed.positional)
+}

package/cli/cloud-session.ts

@@ -0,0 +1,156 @@
+import { fstatSync, writeSync } from 'node:fs'
+import { isLoopbackHost } from '../src/backend-origin'
+
+const CLOUD_SESSION_VERSION = 1 as const
+const SHELL_UPDATE_FD_ENV = 'RNX_SHELL_UPDATE_FD'
+const MAX_ENCODED_SESSION_BYTES = 32 * 1024
+
+export const RNX_CLOUD_SESSION_ENV = 'RNX_CLOUD_SESSION'
+export const RNX_SHELL_UPDATE_PREFIX = '__RNX_SHELL_UPDATE_V1__'
+export const RNX_SHELL_UPDATE_SET_PREFIX = `${RNX_SHELL_UPDATE_PREFIX}set:`
+export const RNX_SHELL_UPDATE_UNSET = `${RNX_SHELL_UPDATE_PREFIX}unset`
+
+export interface CloudSession {
+  version: 1
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function normalizeCloudOrigin(source: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(source)
+  } catch {
+    throw new Error(`invalid RNX Cloud origin: ${source}`)
+  }
+  if (
+    (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') ||
+    parsed.username ||
+    parsed.password ||
+    parsed.pathname !== '/' ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`RNX Cloud origin must be an HTTP(S) origin: ${source}`)
+  }
+  if (parsed.protocol === 'http:' && !isLoopbackHost(parsed.hostname)) {
+    throw new Error(`RNX Cloud origin requires HTTPS outside loopback: ${source}`)
+  }
+  return parsed.origin
+}
+
+export function createCloudSession(input: {
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+}): CloudSession {
+  const session = {
+    version: CLOUD_SESSION_VERSION,
+    simId: input.simId.trim(),
+    apiOrigin: normalizeCloudOrigin(input.apiOrigin.trim()),
+    claimId: input.claimId.trim(),
+    token: input.token,
+  } satisfies CloudSession
+  if (!session.simId || !session.claimId || !session.token) {
+    throw new Error('cloud session requires simulator, origin, claim, and token')
+  }
+  return session
+}
+
+export function serializeCloudSession(session: CloudSession): string {
+  return Buffer.from(JSON.stringify(createCloudSession(session)), 'utf8').toString(
+    'base64url',
+  )
+}
+
+export function parseCloudSession(encoded: string): CloudSession {
+  const value = encoded.trim()
+  if (
+    !value ||
+    value.length > MAX_ENCODED_SESSION_BYTES ||
+    !/^[A-Za-z0-9_-]+$/.test(value)
+  ) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  let parsed: unknown
+  try {
+    const bytes = Buffer.from(value, 'base64url')
+    if (bytes.toString('base64url') !== value) {
+      throw new Error('non-canonical cloud session')
+    }
+    parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+  } catch {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  if (!isRecord(parsed) || parsed.version !== CLOUD_SESSION_VERSION) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  const simId = parsed.simId
+  const apiOrigin = parsed.apiOrigin
+  const claimId = parsed.claimId
+  const token = parsed.token
+  if (
+    typeof simId !== 'string' ||
+    typeof apiOrigin !== 'string' ||
+    typeof claimId !== 'string' ||
+    typeof token !== 'string'
+  ) {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  try {
+    return createCloudSession({ simId, apiOrigin, claimId, token })
+  } catch {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+}
+
+export function readCloudSession(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): CloudSession | null {
+  const encoded = environment[RNX_CLOUD_SESSION_ENV]
+  return encoded?.trim() ? parseCloudSession(encoded) : null
+}
+
+function shellUpdateFd(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): number | null {
+  const source = environment[SHELL_UPDATE_FD_ENV]
+  if (!source) return null
+  const descriptor = Number(source)
+  if (!Number.isSafeInteger(descriptor) || descriptor < 3) {
+    throw new Error('RNX shell integration provided an invalid update channel')
+  }
+  try {
+    fstatSync(descriptor)
+  } catch {
+    throw new Error('RNX shell integration update channel is unavailable')
+  }
+  return descriptor
+}
+
+export function requireCloudSessionShellUpdate(): number {
+  const descriptor = shellUpdateFd()
+  if (descriptor === null) {
+    throw new Error(
+      'RNX shell integration is required so this cloud session stays in the current shell; restart the shell after installing RNX',
+    )
+  }
+  return descriptor
+}
+
+export function publishCloudSessionToShell(
+  session: CloudSession | null,
+  descriptor = requireCloudSessionShellUpdate(),
+): void {
+  const update = session
+    ? `${RNX_SHELL_UPDATE_SET_PREFIX}${serializeCloudSession(session)}`
+    : RNX_SHELL_UPDATE_UNSET
+  writeSync(descriptor, `${update}\n`)
+}

package/cli/command-contract.ts

@@ -67,8 +67,8 @@ export interface RnxParsedCommandInput {
 
 export interface RnxPreviewInvocation extends RnxInvocationBase {
   family: 'preview'
-  command: 'web' | 'ios'
-  platform: 'web' | 'ios'
+  command: 'web' | 'ios' | 'android'
+  platform: 'web' | 'ios' | 'android'
   selection: 'select-or-ensure-existing'
 }
 

package/cli/command-registry.ts

@@ -74,6 +74,7 @@ const NODE_COMMAND_NAMES = [
 const BROWSER_FAMILIES = new Map<string, RnxBrowserCommandFamily>([
   ['web', 'preview'],
   ['ios', 'preview'],
+  ['android', 'preview'],
   ['list', 'runtime'],
   ['use', 'runtime'],
   ['state', 'runtime'],
@@ -248,6 +249,14 @@ export function createRnxCommandInvocation(
         platform: 'ios',
         selection: 'select-or-ensure-existing',
       }
+    case 'android':
+      return {
+        ...common,
+        family: 'preview',
+        command: 'android',
+        platform: 'android',
+        selection: 'select-or-ensure-existing',
+      }
     case 'describe':
       return { ...common, family: 'tree' }
     case 'find':

package/cli/commands/agent-wrapper.ts

@@ -1,10 +1,10 @@
-// agent-wrapper — long-running bridge process between sootsim desktop and a
+// agent-wrapper — long-running bridge process between rnx desktop and a
 // local coding agent (codex / claude).
 //
-// shipped as an internal sootsim CLI subcommand so it survives `bun build
+// shipped as an internal rnx CLI subcommand so it survives `bun build
 // --compile` bundling. callers spawn it as:
 //
-//   sootsim agent-wrapper \
+//   rnx agent-wrapper \
 //     --session-id <id> --project-id <id> --provider codex \
 //     --cwd <path> --prompt-in <fifo> --events-out <fifo> \
 //     [--transcript <file>]
@@ -407,7 +407,7 @@ export async function runAgentWrapper(argv: string[]): Promise<number> {
   }
 
   // open prompt.in with O_RDWR so our own write end keeps the FIFO alive
-  // across external writer open/close cycles. `sootsim agent prompt` opens,
+  // across external writer open/close cycles. `rnx agent prompt` opens,
   // writes one line, closes — without a self-writer the reader would EOF
   // after the first prompt and subsequent prompts would be lost.
   const promptFd = openSync(promptIn, fsConstants.O_RDWR)

package/cli/commands/agent.ts

@@ -1,4 +1,4 @@
-// user-facing `sootsim agent` command tree.
+// user-facing `rnx agent` command tree.
 //
 // session-lifecycle commands (start, prompt, end, watch) route through
 // the bridge daemon — the daemon owns the single FIFO reader per
@@ -8,7 +8,7 @@
 //
 // disk-only inspection commands (projects, sessions, paths, transcript,
 // attach, project show/remove) read the attached-projects JSON directly —
-// no daemon needed, so `sootsim agent projects` stays fast when no
+// no daemon needed, so `rnx agent projects` stays fast when no
 // wrapper is live.
 
 import fs from 'node:fs'
@@ -96,7 +96,7 @@ async function withDaemon<T>(fn: (client: AgentDaemonClient) => Promise<T>): Pro
 }
 
 function printHelp(): void {
-  // delegate to the meta-driven renderer so bare `sootsim agent`, `--help`,
+  // delegate to the meta-driven renderer so bare `rnx agent`, `--help`,
   // and `unknown subcommand` paths all show the same rich help (header,
   // options, examples) instead of a sparse hand-coded summary.
   printCommandHelp('agent')

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

@@ -12,7 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
-import type { ProjectFileMeta, ProjectFilePlane } from '@contrast/harness/plane'
+import type { ProjectFileMeta, ProjectFilePlane } from '@rnx/box/plane'
 
 export class CheckoutRequiresGitError extends Error {}
 
@@ -20,7 +20,7 @@ export class CheckoutRequiresGitError extends Error {}
 // rather than acted on here: moving a binary file is byte-exact and perfectly
 // fine, and so is deleting one, but a shell command that produced TEXT cannot
 // be allowed to overwrite it, because that text is a lossy decode of the
-// file's own bytes. HarnessProjectFs owns that refusal. detecting it at write
+// file's own bytes. BoxProjectFs owns that refusal. detecting it at write
 // time instead 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 fact has to be in the index where the filesystem layer can read it.
@@ -88,10 +88,15 @@ export class CheckoutFilePlane implements ProjectFilePlane {
   // long a wedged git is waited on, never whether it is waited on, so proving
   // the kill does not have to cost the production deadline.
   private readonly listTimeoutMs: number
+  private readonly trackedOnly: boolean
 
-  constructor(root: string, options: { listTimeoutMs?: number } = {}) {
+  constructor(
+    root: string,
+    options: { listTimeoutMs?: number; trackedOnly?: boolean } = {},
+  ) {
     this.root = path.resolve(root)
     this.listTimeoutMs = options.listTimeoutMs ?? LIST_FILES_TIMEOUT_MS
+    this.trackedOnly = options.trackedOnly ?? false
   }
 
   index(): ReadonlyMap<string, ProjectFileMeta> {
@@ -101,10 +106,13 @@ export class CheckoutFilePlane implements ProjectFilePlane {
   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".
-      stdout = execFileSync('git', ['ls-files', '-co', '--exclude-standard', '-z'], {
+      // -z keeps paths containing spaces or newlines intact. a local Box sees
+      // tracked plus visible untracked files, while a durable cloud import is
+      // deliberately restricted to the checkout's tracked source.
+      const args = this.trackedOnly
+        ? ['ls-files', '-z']
+        : ['ls-files', '-co', '--exclude-standard', '-z']
+      stdout = execFileSync('git', args, {
         cwd: this.root,
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
@@ -137,7 +145,7 @@ export class CheckoutFilePlane implements ProjectFilePlane {
     // than a broken box, and nothing would say so.
     if (stdout.length === 0) {
       throw new CheckoutRequiresGitError(
-        `git listed no files in ${this.root}. either git tracks nothing there and nothing untracked is visible to it, or this machine could not read the child process's output.`,
+        `git listed no ${this.trackedOnly ? 'tracked ' : ''}files in ${this.root}. either the checkout contains no eligible files, or this machine could not read the child process's output.`,
       )
     }
 

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

@@ -8,8 +8,8 @@
 
 import { spawn } from 'node:child_process'
 import path from 'node:path'
-import { defineCommand, type CustomCommand } from '@contrast/harness/shell'
-import { PROJECT_MOUNT } from '@contrast/harness/shell'
+import { defineCommand, type CustomCommand } from '@rnx/box/shell'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
 import { rnxPublicBrand } from '../../../src/public-brand'
 import { RNX_PLACEMENT_ENV } from '../../ws-bridge'
 

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

@@ -32,8 +32,8 @@
 // whose "no match here" had to be merged.
 
 import { spawn } from 'node:child_process'
-import { defineCommand, type CustomCommand } from '@contrast/harness/shell'
-import { PROJECT_MOUNT } from '@contrast/harness/shell'
+import { defineCommand, type CustomCommand } from '@rnx/box/shell'
+import { PROJECT_MOUNT } from '@rnx/box/shell'
 
 // generous next to a 414ms p95: this bounds a wedged child, it does not cut off
 // a large search.