peachsim 0.1.527

package/cli/cloud-dispatch.ts

@@ -0,0 +1,206 @@
+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
+}
+
+const CLOUD_DO_VERBS = new Set([
+  'tap',
+  'tap-id',
+  'tap-text',
+  'tap-best',
+  'double-tap',
+  'long-press',
+  'type',
+  'key',
+  'key-sequence',
+  'scroll',
+  'sleep',
+  'settle',
+])
+
+function doChainVerbs(positional: string[]): string[] {
+  const verbs: string[] = []
+  let expectingVerb = true
+  for (const argument of positional) {
+    if (argument === '--then') {
+      expectingVerb = true
+      continue
+    }
+    if (expectingVerb && !argument.startsWith('-')) {
+      verbs.push(argument)
+      expectingVerb = false
+    }
+  }
+  return verbs
+}
+
+function supportsCloudDo(positional: string[]): boolean {
+  const verbs = doChainVerbs(positional)
+  if (verbs.length === 0) return true
+  return verbs.every((verb) => CLOUD_DO_VERBS.has(verb))
+}
+
+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' || verb === 'memory'
+  }
+  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', '--id', '--no-shell', '--shell-only', '--text', '--with-frame'].includes(
+        arg,
+      ),
+    )
+  }
+  if (command === 'do') return supportsCloudDo(positional)
+  if (command === 'reset') return true
+  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 a remote simulator`)
+  return { handled: true, code: 1 }
+}
+
+export async function dispatchCloudBoundary({
+  command,
+  args,
+}: CloudBoundaryInvocation): Promise<CloudBoundaryResult> {
+  if ((command === 'ios' || command === 'android') && args.includes('--remote')) {
+    return { handled: false }
+  }
+  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 === 'close') {
+    if (args.includes('--all') || args.includes('--others')) {
+      return refuseCloudInvocation(command, parsed.positional)
+    }
+    try {
+      const descriptor = cloudSession.requireCloudSessionShellUpdate()
+      await cloudClient.closeCloudSession(session)
+      cloudSession.publishCloudSessionToShell(null, descriptor)
+      console.log(`  closed: remote simulator ${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 }
+    }
+  }
+
+  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 }
+    }
+  }
+
+  // these inputs use the same perform executor as an inline chain. a CPU
+  // simulator has focused text inputs but no browser keyboard to inspect.
+  if (
+    command === 'do' &&
+    supportsCloudDo(parsed.positional) &&
+    doChainVerbs(parsed.positional).some(
+      (verb) => verb === 'type' || verb === 'key' || verb === 'key-sequence',
+    )
+  ) {
+    const { runDoChain } = await import('./commands/do-chain')
+    return { handled: true, code: await runDoChain(args) }
+  }
+
+  return supportsCloudRead(command, args, parsed.positional)
+    ? { handled: false }
+    : refuseCloudInvocation(command, parsed.positional)
+}

package/cli/cloud-session.ts

@@ -0,0 +1,227 @@
+import { fstatSync, writeSync } from 'node:fs'
+import { isLoopbackHost } from '../src/backend-origin.ts'
+
+const CLOUD_SESSION_VERSION = 3 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`
+
+// the shell's remote target: one simulator on the instance API, addressed by
+// its own id and token.
+export type CloudSession = CloudSimSession
+
+export type RemotePlatform = 'ios' | 'android'
+
+export interface CloudSessionArtifactIdentity {
+  sha256: string
+  bytes?: number
+}
+
+/**
+ * one remote simulator and the claim ordinary commands drive it with. the
+ * watch URL the create returned rides along so a reattach reopens the same
+ * simulator. a nano-box simulator keeps the box that hosts it; an instance
+ * API simulator has no box.
+ */
+export interface CloudSimSession {
+  version: 3
+  service: 'sim'
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+  streamUrl?: string | null
+  platform?: RemotePlatform
+  device?: string
+  artifact?: CloudSessionArtifactIdentity
+  /** nano-box simulators only: the box that hosts them. absent on the instance API. */
+  boxId?: string
+  boxToken?: 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 remote simulator origin: ${source}`)
+  }
+  if (
+    (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') ||
+    parsed.username ||
+    parsed.password ||
+    parsed.pathname !== '/' ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`remote simulator origin must be an HTTP(S) origin: ${source}`)
+  }
+  if (parsed.protocol === 'http:' && !isLoopbackHost(parsed.hostname)) {
+    throw new Error(`remote simulator origin requires HTTPS outside loopback: ${source}`)
+  }
+  return parsed.origin
+}
+
+export function createCloudSession(input: {
+  simId: string
+  apiOrigin: string
+  claimId: string
+  token: string
+  streamUrl?: string | null
+  platform?: RemotePlatform
+  device?: string
+  artifact?: CloudSessionArtifactIdentity
+  boxId?: string
+  boxToken?: string
+}): CloudSimSession {
+  const boxId = input.boxId?.trim() ?? ''
+  const boxToken = input.boxToken ?? ''
+  if ((boxId === '') !== (boxToken === '')) {
+    throw new Error('cloud session names a box with both its id and its token')
+  }
+  const session: CloudSimSession = {
+    version: CLOUD_SESSION_VERSION,
+    service: 'sim',
+    simId: input.simId.trim(),
+    apiOrigin: normalizeCloudOrigin(input.apiOrigin.trim()),
+    claimId: input.claimId.trim(),
+    token: input.token,
+    ...(input.streamUrl ? { streamUrl: input.streamUrl } : {}),
+    ...(input.platform ? { platform: input.platform } : {}),
+    ...(input.device?.trim() ? { device: input.device.trim() } : {}),
+    ...(input.artifact ? { artifact: input.artifact } : {}),
+    ...(boxId && boxToken ? { boxId, boxToken } : {}),
+  }
+  if (!session.simId || !session.claimId || !session.token) {
+    throw new Error('cloud session requires a simulator, an origin, a claim, and a token')
+  }
+  return session
+}
+
+export function serializeCloudSession(session: CloudSession): string {
+  const validated = createCloudSession(session)
+  return Buffer.from(JSON.stringify(validated), '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 apiOrigin = parsed.apiOrigin
+  if (typeof apiOrigin !== 'string') {
+    throw new Error(`${RNX_CLOUD_SESSION_ENV} is invalid`)
+  }
+  const platform =
+    parsed.platform === 'ios' || parsed.platform === 'android'
+      ? parsed.platform
+      : undefined
+  const device = typeof parsed.device === 'string' ? parsed.device : undefined
+  const artifact =
+    isRecord(parsed.artifact) && typeof parsed.artifact.sha256 === 'string'
+      ? {
+          sha256: parsed.artifact.sha256,
+          bytes:
+            typeof parsed.artifact.bytes === 'number' ? parsed.artifact.bytes : undefined,
+        }
+      : undefined
+  const streamUrl = typeof parsed.streamUrl === 'string' ? parsed.streamUrl : undefined
+  const boxId = typeof parsed.boxId === 'string' ? parsed.boxId : undefined
+  const boxToken = typeof parsed.boxToken === 'string' ? parsed.boxToken : undefined
+  try {
+    const simId = parsed.simId
+    const claimId = parsed.claimId
+    const token = parsed.token
+    if (
+      parsed.service !== 'sim' ||
+      typeof simId !== 'string' ||
+      typeof claimId !== 'string' ||
+      typeof token !== 'string'
+    ) {
+      throw new Error('unreadable cloud session')
+    }
+    return createCloudSession({
+      simId,
+      apiOrigin,
+      claimId,
+      token,
+      streamUrl,
+      platform,
+      device,
+      artifact,
+      boxId,
+      boxToken,
+    })
+  } 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 remote simulator stays connected to 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

@@ -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' | 'android'
+  platform: 'web' | 'ios' | 'android'
+  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
+}