@limrun/api 0.28.4 → 0.28.6

package/src/ios-client.ts

@@ -4,7 +4,7 @@ import path from 'path';
 import fs from 'fs';
 import { WebSocket, Data } from 'ws';
 import { EventEmitter } from 'events';
-import { isNonRetryableError } from './tunnel';
+import { assertPort, isNonRetryableError, startReverseTcpTunnel, type ReverseTunnel } from './tunnel';
 import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
 import { createIgnoreFn } from './folder-sync-ignore';
 import { downloadFileToLocalPath } from './internal/download-file';
@@ -21,11 +21,31 @@ export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'rec
 export type ConnectionStateCallback = (state: ConnectionState) => void;
 
 const ACTIVE_RECORDING_FILENAME = 'recording.mp4';
+export const REVERSE_TUNNEL_REMOTE_PORT_MIN = 57090;
+export const REVERSE_TUNNEL_REMOTE_PORT_MAX = 57099;
 
 function buildDownloadUrl(apiUrl: string): string {
   return `${apiUrl}/files?name=${encodeURIComponent(ACTIVE_RECORDING_FILENAME)}`;
 }
 
+export function deriveReverseTunnelUrl(apiUrl: string, remotePort: number): string {
+  const url = new URL(apiUrl);
+  if (url.protocol === 'https:') {
+    url.protocol = 'wss:';
+  } else if (url.protocol === 'http:') {
+    url.protocol = 'ws:';
+  } else {
+    throw new Error(`Unsupported apiUrl protocol for reverse tunnel: ${url.protocol}`);
+  }
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/reverse-tunnel`;
+  url.search = '';
+  url.hash = '';
+  url.searchParams.set('remotePort', String(remotePort));
+  return url.toString();
+}
+
+export type { ReverseTunnel } from './tunnel';
+
 /**
  * Events emitted by a simctl execution
  */
@@ -227,6 +247,35 @@ export type SoftResetOptions = {
   strategy?: SoftResetStrategy;
 };
 
+export type LaunchAppMode = 'ForegroundIfRunning' | 'RelaunchIfRunning';
+
+export type DetoxLaunchRuntime = {
+  kind: 'detox';
+  serverUrl: string;
+  sessionId: string;
+  version?: string;
+};
+
+export type LaunchAppRuntime = DetoxLaunchRuntime;
+
+type StandardLaunchAppOptions = {
+  /**
+   * Launch behavior when the app may already be running.
+   * Defaults to `ForegroundIfRunning` server-side.
+   */
+  mode?: LaunchAppMode;
+  runtime?: undefined;
+};
+
+type RuntimeLaunchAppOptions = {
+  /** Runtime launches must relaunch so runtime injection is applied. */
+  mode?: Extract<LaunchAppMode, 'RelaunchIfRunning'>;
+  /** Optional app runtime to attach during launch. */
+  runtime: LaunchAppRuntime;
+};
+
+export type LaunchAppOptions = StandardLaunchAppOptions | RuntimeLaunchAppOptions;
+
 /**
  * Result of a {@link InstanceClient.softReset} call.
  */
@@ -244,6 +293,17 @@ export type SoftResetResult = {
   durationMs: number;
 };
 
+export type ReverseTunnelOptions = {
+  /** Port to listen on near the simulator. Must be in 57090-57099. */
+  remotePort: number;
+  /** Local port for a client-first service on the user's machine. Defaults to remotePort. */
+  localPort?: number;
+  /** Local host on the user's machine. Defaults to 127.0.0.1. */
+  localHost?: string;
+  /** Controls tunnel logging verbosity. Defaults to the instance client's log level. */
+  logLevel?: LogLevel;
+};
+
 /**
  * Result from a command execution (xcrun, xcodebuild, etc.)
  */
@@ -431,8 +491,12 @@ export type InstanceClient = {
    * @param mode Optional launch mode:
    *   - 'ForegroundIfRunning' (default): bring to foreground if already running
    *   - 'RelaunchIfRunning': terminate and relaunch if already running
+   *   Or a launch options object with optional mode and launch runtime.
    */
-  launchApp: (bundleId: string, mode?: 'ForegroundIfRunning' | 'RelaunchIfRunning') => Promise<void>;
+  launchApp: {
+    (bundleId: string, mode?: LaunchAppMode): Promise<void>;
+    (bundleId: string, options: LaunchAppOptions): Promise<void>;
+  };
 
   /**
    * Terminate a running app by bundle identifier.
@@ -625,6 +689,12 @@ export type InstanceClient = {
    */
   softReset: (bundleId: string, options?: SoftResetOptions) => Promise<SoftResetResult>;
 
+  /**
+   * Start a reverse tunnel from the simulator-facing LISTEN_IP:remotePort
+   * to a user-local client-first TCP service, such as HTTP or WebSocket.
+   */
+  startReverseTunnel: (options: ReverseTunnelOptions) => Promise<ReverseTunnel>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -1291,6 +1361,21 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return `ts-client-${Date.now()}-${Math.random().toString(36).substring(7)}`;
     };
 
+    const redactRequestForDebug = (request: Record<string, unknown>): Record<string, unknown> => {
+      if (request['type'] !== 'launchApp') {
+        return request;
+      }
+
+      const runtime = request['runtime'] as LaunchAppRuntime | undefined;
+      return {
+        type: request['type'],
+        id: request['id'],
+        bundleId: request['bundleId'],
+        mode: request['mode'],
+        runtime: runtime ? { kind: runtime.kind, version: runtime.version } : undefined,
+      };
+    };
+
     // Generic request sender with timeout and response handling
     const sendRequest = <T>(
       type: string,
@@ -1316,7 +1401,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         );
 
         const request = { type, id, ...params };
-        logger.debug('Sending request:', request);
+        logger.debug('Sending request:', redactRequestForDebug(request));
 
         ws.send(JSON.stringify(request), (err?: Error) => {
           if (err) {
@@ -1552,6 +1637,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             clearStoreKitConfig,
             discoverStoreKitConfig,
             softReset,
+            startReverseTunnel,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
@@ -1636,11 +1722,24 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<void>('toggleKeyboard');
     };
 
-    const launchApp = (
-      bundleId: string,
-      mode?: 'ForegroundIfRunning' | 'RelaunchIfRunning',
-    ): Promise<void> => {
-      return sendRequest<void>('launchApp', { bundleId, mode });
+    const launchApp = (bundleId: string, modeOrOptions?: LaunchAppMode | LaunchAppOptions): Promise<void> => {
+      const launchOptions: LaunchAppOptions =
+        typeof modeOrOptions === 'string' ? { mode: modeOrOptions } : modeOrOptions ?? {};
+      const requestedMode =
+        typeof modeOrOptions === 'object' ?
+          (modeOrOptions as { mode?: LaunchAppMode }).mode
+        : launchOptions.mode;
+      if (launchOptions.runtime && requestedMode === 'ForegroundIfRunning') {
+        return Promise.reject(
+          new Error('launchApp runtime launches require RelaunchIfRunning so runtime injection is applied.'),
+        );
+      }
+      const mode = launchOptions.runtime ? 'RelaunchIfRunning' : launchOptions.mode;
+      return sendRequest<void>('launchApp', {
+        bundleId,
+        mode,
+        runtime: launchOptions.runtime,
+      });
     };
 
     const terminateApp = (bundleId: string): Promise<void> => {
@@ -2018,6 +2117,24 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return out;
     };
 
+    const startReverseTunnel = async (tunnelOptions: ReverseTunnelOptions): Promise<ReverseTunnel> => {
+      assertPort(
+        tunnelOptions.remotePort,
+        'remotePort',
+        REVERSE_TUNNEL_REMOTE_PORT_MIN,
+        REVERSE_TUNNEL_REMOTE_PORT_MAX,
+      );
+      const localPort = tunnelOptions.localPort ?? tunnelOptions.remotePort;
+      assertPort(localPort, 'localPort', 1, 65535);
+
+      const remoteURL = deriveReverseTunnelUrl(options.apiUrl, tunnelOptions.remotePort);
+      return startReverseTcpTunnel(remoteURL, options.token, {
+        localHost: tunnelOptions.localHost ?? '127.0.0.1',
+        localPort,
+        logLevel: tunnelOptions.logLevel ?? logLevel,
+      });
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();

package/src/resources/index.ts

@@ -36,4 +36,5 @@ export {
   type XcodeClient,
   type XcodeProjectConfig,
   type XcodeBuildOptions,
+  type ReactNativeBuildConfig,
 } from './xcode-instances-helpers';

package/src/resources/xcode-instances-helpers.ts

@@ -52,6 +52,11 @@ export type XcodeProjectConfig = {
   project?: string;
   scheme?: string;
   sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
+  /**
+   * xcodebuild configuration. Omit to use limbuild's project-type default:
+   * Debug for native Xcode builds and Release for React Native / Expo builds.
+   */
+  configuration?: 'Debug' | 'Release';
 };
 
 export type XcodeSigningConfig = {
@@ -60,9 +65,25 @@ export type XcodeSigningConfig = {
   provisioningProfileBase64?: string;
 };
 
+export type ReactNativeBuildConfig = {
+  /**
+   * Relative path from the synced workspace root to the Expo app directory.
+   * Omit to let limbuild auto-detect the app.
+   */
+  expoAppDir?: string;
+  /**
+   * Direct Metro / Expo development server URL for RN/Expo Debug builds, such
+   * as the https://...exp.direct URL printed by `expo start --tunnel`.
+   * Requires `configuration: 'Debug'`, Expo SDK 52+, React Native 0.76+, and
+   * the default Swift AppDelegate generated by Expo prebuild.
+   */
+  devServerURL?: string;
+};
+
 export type XcodeBuildOptions = {
   upload?: { assetName: string } | { signedUploadUrl: string };
   signing?: XcodeSigningConfig;
+  reactNative?: ReactNativeBuildConfig;
 };
 
 export type XcodeClient = {
@@ -232,9 +253,13 @@ export class XcodeInstances extends GeneratedXcodeInstances {
       },
 
       xcodebuild(settings?: XcodeProjectConfig, options?: XcodeBuildOptions): ExecChildProcess {
+        if (options?.reactNative?.devServerURL && settings?.configuration !== 'Debug') {
+          throw new Error("reactNative.devServerURL requires xcodebuild configuration 'Debug'");
+        }
         const request: ExecRequest = {
           command: 'xcodebuild',
           ...(settings && { xcodebuild: settings }),
+          ...(options?.reactNative && { reactNative: options.reactNative }),
           ...(options?.signing && { signing: options.signing }),
         };