@limrun/api 0.28.5 → 0.28.7

package/src/client.ts

@@ -53,6 +53,7 @@ import {
   XcodeClient,
   XcodeProjectConfig,
   XcodeBuildOptions,
+  ReactNativeBuildConfig,
 } from './resources/xcode-instances-helpers';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
@@ -850,5 +851,6 @@ export declare namespace Limrun {
     type XcodeClient as XcodeClient,
     type XcodeProjectConfig as XcodeProjectConfig,
     type XcodeBuildOptions as XcodeBuildOptions,
+    type ReactNativeBuildConfig as ReactNativeBuildConfig,
   };
 }

package/src/exec-client.ts

@@ -19,6 +19,11 @@ export type ExecRequest = {
     project?: string;
     scheme?: string;
     sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
+    configuration?: 'Debug' | 'Release';
+  };
+  reactNative?: {
+    expoAppDir?: string;
+    devServerURL?: string;
   };
   signing?: {
     certificateP12Base64?: string;

package/src/http-proxy.ts

@@ -0,0 +1,85 @@
+import http from 'http';
+import https from 'https';
+
+export type HttpProxy = {
+  port: number;
+  close: () => Promise<void>;
+};
+
+export type StartHttpProxyOptions = {
+  localPort?: number;
+  remoteBaseUrl: string;
+  headers?: Record<string, string>;
+};
+
+export async function startHttpProxy({
+  localPort = 0,
+  remoteBaseUrl,
+  headers = {},
+}: StartHttpProxyOptions): Promise<HttpProxy> {
+  const base = trimTrailingSlashes(remoteBaseUrl);
+  const server = http.createServer((req, res) => {
+    const pathAndQuery = req.url || '/';
+    const upstreamUrl = new URL(`${base}${pathAndQuery.startsWith('/') ? pathAndQuery : `/${pathAndQuery}`}`);
+    const transport = upstreamUrl.protocol === 'https:' ? https : http;
+    const upstream = transport.request(
+      upstreamUrl,
+      {
+        method: req.method,
+        headers: {
+          ...req.headers,
+          host: upstreamUrl.host,
+          ...headers,
+        },
+      },
+      (upstreamResponse) => {
+        res.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+        upstreamResponse.pipe(res);
+      },
+    );
+
+    upstream.on('error', (error) => {
+      if (!res.headersSent) {
+        res.writeHead(502, { 'content-type': 'text/plain' });
+      }
+      res.end(error.message);
+    });
+    req.pipe(upstream);
+  });
+
+  await listen(server, localPort);
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to start HTTP proxy.');
+  }
+  return {
+    port: address.port,
+    close: () => closeServer(server),
+  };
+}
+
+function trimTrailingSlashes(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+function listen(server: http.Server, port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+function closeServer(server: http.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export { Limrun, type ClientOptions } from './client';
 export { PagePromise } from './core/pagination';
 export * from './instance-client';
 export * as Ios from './ios-client';
+export { startHttpProxy, type HttpProxy, type StartHttpProxyOptions } from './http-proxy';
 export {
   exec,
   type ExecRequest,
@@ -20,6 +21,7 @@ export {
   type XcodeClient,
   type XcodeProjectConfig,
   type XcodeBuildOptions,
+  type ReactNativeBuildConfig,
 } from './resources/xcode-instances-helpers';
 export {
   LimrunError,

package/src/ios-client.ts

@@ -9,6 +9,8 @@ import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './fol
 import { createIgnoreFn } from './folder-sync-ignore';
 import { downloadFileToLocalPath } from './internal/download-file';
 import { nodeProxyTransport } from './internal/proxy-transport';
+import { startHttpProxy as startLocalHttpProxy } from './http-proxy';
+import { startXcrunShim as startClientXcrunShim } from './ios-shim';
 
 /**
  * Connection state of the instance client
@@ -198,6 +200,11 @@ export type AppInstallationResult = {
   bundleId: string;
 };
 
+export type HttpProxyOptions = {
+  remoteBaseUrl: string;
+  localPort: number;
+};
+
 /**
  * Result of auto-discovering a StoreKit configuration from the
  * simulator's cached sandbox response.
@@ -695,6 +702,14 @@ export type InstanceClient = {
    */
   startReverseTunnel: (options: ReverseTunnelOptions) => Promise<ReverseTunnel>;
 
+  /**
+   * Start a local HTTP proxy to a port exposed by the iOS instance.
+   *
+   * Returns the local port the proxy is listening on. The proxy is closed when
+   * the client disconnects.
+   */
+  startHttpProxy: (options: HttpProxyOptions) => Promise<number>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -791,6 +806,14 @@ export type InstanceClient = {
    */
   xcrun: (args: string[]) => Promise<CommandResult>;
 
+  /**
+   * Start a local `xcrun` shim for this iOS instance.
+   *
+   * The returned directory contains an `xcrun` executable that can be prepended
+   * to PATH for tools that shell out to `xcrun simctl`.
+   */
+  startXcrunShim: () => Promise<string>;
+
   /**
    * Run `xcodebuild` command with the given arguments.
    * Returns the complete output once the command finishes (non-streaming).
@@ -1257,6 +1280,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
   // Simctl uses streaming, so it needs separate handling
   const simctlExecutions: Map<string, SimctlExecution> = new Map();
 
+  const xcrunShimCleanups: Array<() => Promise<void>> = [];
+  const httpProxyCleanups: Array<() => Promise<void>> = [];
+
   const stateChangeCallbacks: Set<ConnectionStateCallback> = new Set();
 
   // Logger functions
@@ -1300,7 +1326,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     simctlExecutions.clear();
   };
 
-  const cleanup = (): void => {
+  const cleanupConnection = (): void => {
     if (reconnectTimeout) {
       clearTimeout(reconnectTimeout);
       reconnectTimeout = undefined;
@@ -1318,6 +1344,22 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     }
   };
 
+  const cleanupClientResources = (): void => {
+    const shimCleanups = xcrunShimCleanups.splice(0);
+    for (const closeShim of shimCleanups) {
+      closeShim().catch((error) => logger.warn('Failed to close xcrun shim:', error));
+    }
+    const proxyCleanups = httpProxyCleanups.splice(0);
+    for (const closeProxy of proxyCleanups) {
+      closeProxy().catch((error) => logger.warn('Failed to close HTTP proxy:', error));
+    }
+  };
+
+  const cleanup = (): void => {
+    cleanupConnection();
+    cleanupClientResources();
+  };
+
   let pingInterval: NodeJS.Timeout | undefined;
   const keepAliveSessionId =
     Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
@@ -1469,7 +1511,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     };
 
     const setupWebSocket = (): void => {
-      cleanup();
+      cleanupConnection();
       updateConnectionState('connecting');
 
       const proxyAgent = nodeProxyTransport.getWebSocketAgent(endpointWebSocketUrl);
@@ -1638,11 +1680,13 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             discoverStoreKitConfig,
             softReset,
             startReverseTunnel,
+            startHttpProxy,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
             simctl,
             xcrun,
+            startXcrunShim,
             xcodebuild,
             cp,
             lsof,
@@ -1911,6 +1955,17 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<CommandResult>('xcrun', { args });
     };
 
+    const startXcrunShim = async (): Promise<string> => {
+      const shim = await startClientXcrunShim({
+        deviceInfo: cachedDeviceInfo,
+        listApps,
+        simctl,
+        syncApp,
+      });
+      xcrunShimCleanups.push(shim.close);
+      return shim.dir;
+    };
+
     const xcodebuild = (args: string[]): Promise<CommandResult> => {
       return sendRequest<CommandResult>('xcodebuild', { args });
     };
@@ -2135,6 +2190,20 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       });
     };
 
+    const startHttpProxy = async (proxyOptions: HttpProxyOptions): Promise<number> => {
+      assertPort(proxyOptions.localPort, 'localPort', 1, 65535);
+
+      const proxy = await startLocalHttpProxy({
+        localPort: proxyOptions.localPort,
+        remoteBaseUrl: proxyOptions.remoteBaseUrl,
+        headers: {
+          authorization: `Bearer ${options.token}`,
+        },
+      });
+      httpProxyCleanups.push(proxy.close);
+      return proxy.port;
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();

package/src/ios-shim.ts

@@ -0,0 +1,401 @@
+import fs from 'fs';
+import http, { type IncomingMessage, type ServerResponse } from 'http';
+import os from 'os';
+import path from 'path';
+
+import type { InstalledApp, InstanceClient } from './ios-client';
+
+const FORWARDED_SIMCTL_COMMANDS = new Set([
+  'openurl',
+  'launch',
+  'terminate',
+  'uninstall',
+  'privacy',
+  'location',
+  'status_bar',
+  'spawn',
+]);
+
+export type IosXcrunShimServer = {
+  url: string;
+  close: () => Promise<void>;
+};
+
+export type IosXcrunShim = {
+  dir: string;
+  close: () => Promise<void>;
+};
+
+export type IosXcrunShimClient = Pick<InstanceClient, 'deviceInfo' | 'listApps' | 'simctl' | 'syncApp'>;
+
+export type IosShimSimctlResult = {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+export async function startXcrunShim(client: IosXcrunShimClient): Promise<IosXcrunShim> {
+  const server = await startXcrunShimServer({ client, udid: client.deviceInfo.udid });
+  try {
+    const dir = await createXcrunShim({ shimUrl: server.url, udid: client.deviceInfo.udid });
+    return {
+      dir,
+      close: async () => {
+        await server.close();
+        fs.rmSync(dir, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    await server.close().catch(() => {});
+    throw error;
+  }
+}
+
+export async function startXcrunShimServer({
+  client,
+  udid,
+}: {
+  client: IosXcrunShimClient;
+  udid: string;
+}): Promise<IosXcrunShimServer> {
+  const server = http.createServer(async (req, res) => {
+    if (req.method !== 'POST' || req.url !== '/xcrun') {
+      sendJson(res, 404, { code: 127, stdout: '', stderr: 'not found' });
+      return;
+    }
+    try {
+      const body = (await readJson(req)) as { args?: string[] };
+      const args = body.args ?? [];
+      const result = await handleShimmedXcrun(client, udid, args);
+      sendJson(res, 200, result);
+    } catch {
+      sendJson(res, 200, {
+        code: 1,
+        stdout: '',
+        stderr: 'limrun xcrun shim failed to execute the requested command.',
+      });
+    }
+  });
+
+  await listen(server, 0);
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to start Limrun xcrun shim server.');
+  }
+  return {
+    url: `http://127.0.0.1:${address.port}/xcrun`,
+    close: () => closeServer(server),
+  };
+}
+
+export async function createXcrunShim(options?: { shimUrl: string; udid: string }): Promise<string> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'limrun-xcrun-shim-'));
+  const shimPath = path.join(dir, 'xcrun');
+  fs.writeFileSync(shimPath, xcrunShimSource(options), 'utf8');
+  fs.chmodSync(shimPath, 0o755);
+  return dir;
+}
+
+async function handleShimmedXcrun(
+  client: IosXcrunShimClient,
+  udid: string,
+  args: string[],
+): Promise<IosShimSimctlResult> {
+  if (args[0] !== 'simctl') {
+    return { code: 127, stdout: '', stderr: `unsupported xcrun command: ${args.join(' ')}` };
+  }
+
+  const simctlArgs = args.slice(1);
+  const command = simctlArgs[0];
+  const target = simctlTarget(command, simctlArgs);
+
+  if (command === 'list') {
+    // Maestro's device picker expects the full CoreSimulator JSON shape. Limrun
+    // only has one remote simulator in this context, so we synthesize that entry.
+    return simctlList(client.deviceInfo.udid, simctlArgs);
+  }
+
+  if (!isLimrunTarget(target, udid)) {
+    return { code: 64, stdout: '', stderr: `unsupported non-Limrun simctl target '${target ?? ''}'.` };
+  }
+
+  if (command === 'listapps') {
+    const apps = await client.listApps();
+    return {
+      code: 0,
+      stdout: `${JSON.stringify(toSimctlListApps(apps))}\n`,
+      stderr: '',
+    };
+  }
+
+  if (command === 'install') {
+    const appPath = simctlArgs[2];
+    if (!appPath) {
+      return { code: 64, stdout: '', stderr: 'simctl install requires a local .app path.' };
+    }
+    await client.syncApp(appPath, { install: true, watch: false });
+    return { code: 0, stdout: '', stderr: '' };
+  }
+
+  const unsupported = unsupportedPathBearingCommand(command);
+  if (unsupported) {
+    return unsupported;
+  }
+
+  if (!command || !FORWARDED_SIMCTL_COMMANDS.has(command)) {
+    return { code: 64, stdout: '', stderr: `limrun xcrun shim does not support simctl ${command ?? ''}.` };
+  }
+
+  return await client.simctl(simctlArgs).wait();
+}
+
+function simctlList(udid: string, simctlArgs: string[]): IosShimSimctlResult {
+  if (!simctlArgs.includes('-j')) {
+    return { code: 64, stdout: '', stderr: 'limrun xcrun shim only supports `xcrun simctl list -j`.' };
+  }
+  return {
+    code: 0,
+    stdout: `${JSON.stringify(toSimctlList(udid))}\n`,
+    stderr: '',
+  };
+}
+
+function unsupportedPathBearingCommand(command: string | undefined): IosShimSimctlResult | undefined {
+  // These commands either return local simulator filesystem paths or consume
+  // host-side media files. They need explicit staging/translation before they
+  // are safe to claim as supported.
+  if (command === 'get_app_container') {
+    return {
+      code: 64,
+      stdout: '',
+      stderr:
+        'limrun xcrun shim does not support get_app_container because upstream tools expect a local filesystem path.',
+    };
+  }
+  if (command === 'keychain') {
+    return { code: 64, stdout: '', stderr: 'limrun xcrun shim does not support simctl keychain in v1.' };
+  }
+  if (command === 'io') {
+    return {
+      code: 64,
+      stdout: '',
+      stderr: 'limrun xcrun shim does not support simctl io recordVideo in v1.',
+    };
+  }
+  if (command === 'push' || command === 'addmedia') {
+    return {
+      code: 64,
+      stdout: '',
+      stderr: `limrun xcrun shim does not support path-bearing simctl ${command} in v1.`,
+    };
+  }
+  return undefined;
+}
+
+function isLimrunTarget(value: string | undefined, udid: string): boolean {
+  return value === udid || value === 'booted';
+}
+
+function simctlTarget(command: string | undefined, simctlArgs: string[]): string | undefined {
+  if (command === 'launch') {
+    return simctlArgs.slice(1).find((arg) => !arg.startsWith('-'));
+  }
+  return simctlArgs[1];
+}
+
+function toSimctlList(udid: string): Record<string, unknown> {
+  const runtimeIdentifier = 'com.apple.CoreSimulator.SimRuntime.iOS-18-0';
+  const deviceTypeIdentifier = 'com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro';
+  return {
+    devices: {
+      [runtimeIdentifier]: [
+        {
+          availability: '(available)',
+          dataPath: `/tmp/limrun-sim/${udid}/data`,
+          logPath: `/tmp/limrun-sim/${udid}/logs`,
+          isAvailable: true,
+          name: process.env['LIMRUN_IOS_DEVICE_NAME'] || 'Limrun iPhone',
+          state: 'Booted',
+          udid,
+          deviceTypeIdentifier,
+          availabilityError: null,
+        },
+      ],
+    },
+    devicetypes: [
+      {
+        bundlePath: '',
+        identifier: deviceTypeIdentifier,
+        maxRuntimeVersion: 999999,
+        maxRuntimeVersionString: null,
+        minRuntimeVersion: 0,
+        minRuntimeVersionString: null,
+        modelIdentifier: 'iPhone17,1',
+        name: 'iPhone 16 Pro',
+        productFamily: 'iPhone',
+      },
+    ],
+    pairs: {},
+    runtimes: [
+      {
+        availability: '(available)',
+        bundlePath: '',
+        buildversion: '22A000',
+        identifier: runtimeIdentifier,
+        isInternal: false,
+        isAvailable: true,
+        name: process.env['LIMRUN_IOS_RUNTIME_NAME'] || 'iOS 18.0',
+        platform: 'iOS',
+        runtimeRoot: '',
+        supportedDeviceTypes: [],
+        version: '18.0',
+      },
+    ],
+  };
+}
+
+function toSimctlListApps(
+  apps: InstalledApp[],
+): Record<string, { CFBundleIdentifier: string; CFBundleName?: string }> {
+  return Object.fromEntries(
+    apps.map((app) => [
+      app.bundleId,
+      {
+        CFBundleIdentifier: app.bundleId,
+        ...(app.name ? { CFBundleName: app.name } : {}),
+      },
+    ]),
+  );
+}
+
+function xcrunShimSource(options?: { shimUrl: string; udid: string }): string {
+  // Keep the executable tiny: it decides whether this is a Limrun-targeted
+  // simctl call, then asks the local shim server to perform the real work.
+  // Non-Limrun calls still delegate to the host xcrun.
+  const embeddedShimUrl = options ? JSON.stringify(options.shimUrl) : 'process.env.LIMRUN_XCRUN_SHIM_URL';
+  const embeddedUdid = options ? JSON.stringify(options.udid) : 'process.env.LIMRUN_IOS_UDID';
+  return `#!/usr/bin/env node
+const http = require('node:http');
+const { spawnSync } = require('node:child_process');
+
+const args = process.argv.slice(2);
+const realXcrun = process.env.LIMRUN_REAL_XCRUN || '/usr/bin/xcrun';
+
+function delegate() {
+  const result = spawnSync(realXcrun, args, { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write(String(result.error.message || result.error) + '\\n');
+    process.exit(127);
+  }
+  process.exit(result.status ?? 1);
+}
+
+function fail(message) {
+  process.stderr.write('limrun xcrun shim: ' + message + '\\n');
+  process.exit(64);
+}
+
+if (args[0] !== 'simctl') {
+  delegate();
+}
+
+const shimUrl = ${embeddedShimUrl};
+const udid = ${embeddedUdid};
+if (!shimUrl || !udid) {
+  fail('LIMRUN_XCRUN_SHIM_URL and LIMRUN_IOS_UDID are required.');
+}
+
+const simctlArgs = args.slice(1);
+const command = simctlArgs[0];
+function simctlTarget(command, simctlArgs) {
+  if (command === 'launch') {
+    return simctlArgs.slice(1).find((arg) => !arg.startsWith('-'));
+  }
+  return simctlArgs[1];
+}
+const target = simctlTarget(command, simctlArgs);
+function isLimrunTarget(value) {
+  return value === udid || value === 'booted';
+}
+
+if (command !== 'list' && !isLimrunTarget(target)) {
+  delegate();
+}
+
+const parsed = new URL(shimUrl);
+const body = JSON.stringify({ args });
+const req = http.request(parsed, {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body),
+  },
+}, (res) => {
+  const chunks = [];
+  res.on('data', (chunk) => chunks.push(chunk));
+  res.on('end', () => {
+    let payload;
+    try {
+      payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch (error) {
+      process.stderr.write('limrun xcrun shim: invalid shim response\\n');
+      process.exit(1);
+    }
+    if (payload.stdout) process.stdout.write(payload.stdout);
+    if (payload.stderr) process.stderr.write(payload.stderr);
+    process.exit(typeof payload.code === 'number' ? payload.code : 1);
+  });
+});
+req.on('error', (error) => {
+  process.stderr.write('limrun xcrun shim: ' + error.message + '\\n');
+  process.exit(1);
+});
+req.end(body);
+`;
+}
+
+function listen(server: http.Server, port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+function closeServer(server: http.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+function readJson(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res: ServerResponse, statusCode: number, payload: unknown): void {
+  const body = JSON.stringify(payload);
+  res.writeHead(statusCode, {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}

package/src/resources/index.ts

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