@limrun/api 0.45.1 → 0.45.3

package/src/exec-client.ts

@@ -37,7 +37,8 @@ export type XcodeBuildExecRequest = {
     certificatePassword?: string;
     provisioningProfileBase64?: string;
   };
-  testflight?: TestflightUploadConfig;
+  /** Wire name retained for compatibility with the limbuild exec API. */
+  testflight?: AppStoreUploadConfig;
   buildSettings?: Record<string, string>;
   gitInit?: boolean;
   signedUploadUrl?: string;
@@ -110,12 +111,16 @@ export type GradleSigningConfig = {
 
 export type GradleBuildExecRequest = {
   command: 'gradlebuild';
-  /** Gradle tasks to run. Omit for the server default (assembleDebug). */
+  /**
+   * Gradle tasks to run. Omit for the server default (assembleDebug, or
+   * bundleRelease when signing is set).
+   */
   tasks?: string[];
   /** Relative path to the Gradle root when auto-discovery is ambiguous. */
   projectPath?: string;
   reactNative?: GradleReactNativeConfig;
   signing?: GradleSigningConfig;
+  playstore?: GradlePlaystoreConfig;
   signedUploadUrl?: string;
   webhook?: WebhookConfig;
   additionalMetadata?: {
@@ -123,6 +128,45 @@ export type GradleBuildExecRequest = {
   };
 };
 
+/**
+ * Publish the built AAB to a Google Play track after a successful build.
+ * Requires signing. Exactly one of accessToken or serviceAccountJsonBase64
+ * must be set; the credential is held in memory for the build duration
+ * only. Progress and failure causes stream as `playstore` SSE events.
+ */
+export type GradlePlaystoreConfig = {
+  /** OAuth bearer token carrying the androidpublisher scope. */
+  accessToken?: string;
+  /** Base64-encoded service-account JSON key invited in Play Console. */
+  serviceAccountJsonBase64?: string;
+  /**
+   * Play track ID, passed to Google verbatim: internal (default), alpha,
+   * beta, production, or a custom closed-testing track. Publishing
+   * replaces the track's existing releases, including an in-progress
+   * staged rollout on that track.
+   */
+  track?: string;
+  /**
+   * completed (default) makes the release live on the track; draft
+   * commits it without rollout. Publishing to the production track
+   * requires setting it explicitly.
+   */
+  releaseStatus?: 'draft' | 'completed';
+  /** Package name to publish under. Omit to read it from the built AAB. */
+  packageName?: string;
+  /**
+   * Set the versionCode to one more than the highest already known to
+   * Google Play (1 for an app with no artifacts), so repeat publishes
+   * never collide. Resolved with the publish credential before the build
+   * and stamped into the workspace copy: android.versionCode in the Expo
+   * config (requires a static app.json), or the single literal
+   * versionCode in a native project's conventional app/ module build
+   * script (computed or flavor-split versionCodes are rejected at
+   * request time).
+   */
+  autoIncrementVersionCode?: boolean;
+};
+
 export type RunExecRequest = {
   command: 'run';
   commandLine: string;
@@ -143,10 +187,16 @@ export type ExecResult = {
   status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
   signedDownloadUrl?: string;
   /**
-   * Last TestFlight state streamed by the server. Absent when the build ran
-   * without a testflight request, or when the server predates the feature.
+   * Last App Store Connect upload state streamed by the server. Absent when
+   * the build ran without an App Store upload, or when the server predates
+   * the feature.
    */
-  testflight?: TestflightEvent;
+  appstore?: AppStoreEvent;
+  /**
+   * Last Play Store state streamed by the server. Absent when the build ran
+   * without a playstore request, or when the server predates the feature.
+   */
+  playstore?: PlaystoreEvent;
   /**
    * True when the client gave up waiting for the build's event stream. The
    * exit code is fabricated in that case; the remote build may still be
@@ -155,14 +205,24 @@ export type ExecResult = {
   timedOut?: boolean;
 };
 
-export type TestflightEvent = {
-  /** 'unknown' means a testflight event arrived but its payload was unreadable. */
+export type AppStoreEvent = {
+  /** 'unknown' means an App Store upload event arrived but its payload was unreadable. */
   state: 'uploading' | 'processing' | 'accepted' | 'failed' | 'unknown';
   uploadId?: string;
   buildId?: string;
 };
 
-export type TestflightUploadConfig = {
+export type PlaystoreEvent = {
+  /** 'unknown' means a playstore event arrived but its payload was unreadable. */
+  state: 'uploading' | 'accepted' | 'failed' | 'unknown';
+  versionCode?: number;
+  track?: string;
+  /** Machine-readable failure code; present only on failed. */
+  code?: string;
+  message?: string;
+};
+
+export type AppStoreUploadConfig = {
   /** App Store Connect API key ID, e.g. 2X9R4HXF34. */
   apiKeyId: string;
   /** Issuer ID for team API keys. Omit for individual API keys. */
@@ -255,7 +315,8 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
   private sseConnection: EventSourceClient | null = null;
   private killed = false;
   private detached = false;
-  private testflightEvent: TestflightEvent | null = null;
+  private appStoreEvent: AppStoreEvent | null = null;
+  private playstoreEvent: PlaystoreEvent | null = null;
   private readonly options: ExecOptions;
   private readonly log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
 
@@ -475,7 +536,8 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
       execId: this.execId!,
       status,
       ...('additionalMetadata' in request ? request.additionalMetadata ?? {} : {}),
-      ...(this.testflightEvent ? { testflight: this.testflightEvent } : {}),
+      ...(this.appStoreEvent ? { appstore: this.appStoreEvent } : {}),
+      ...(this.playstoreEvent ? { playstore: this.playstoreEvent } : {}),
       ...(timedOut ? { timedOut } : {}),
     };
 
@@ -511,13 +573,23 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
               this.stderr.emit('data', data);
             } else if (eventType === 'testflight') {
               try {
-                this.testflightEvent = JSON.parse(data) as TestflightEvent;
+                this.appStoreEvent = JSON.parse(data) as AppStoreEvent;
               } catch {
-                // The event itself proves the server ran the TestFlight step,
+                // The wire event itself proves the server ran the App Store upload,
                 // so never let a payload glitch look like a missing feature.
-                this.testflightEvent = { state: 'unknown' };
+                this.appStoreEvent = { state: 'unknown' };
                 this.log('warn', `SSE testflight event has invalid data: ${data}`);
               }
+            } else if (eventType === 'playstore') {
+              try {
+                this.playstoreEvent = JSON.parse(data) as PlaystoreEvent;
+              } catch {
+                // Same contract as the App Store upload event: its presence proves the server
+                // ran the Play Store step, so a payload glitch must not
+                // read as a missing feature.
+                this.playstoreEvent = { state: 'unknown' };
+                this.log('warn', `SSE playstore event has invalid data: ${data}`);
+              }
             } else if (eventType === 'exitCode') {
               const exitCode = parseInt(data, 10);
               if (Number.isNaN(exitCode)) {

package/src/http-proxy.ts

@@ -1,5 +1,6 @@
 import http from 'http';
 import https from 'https';
+import { pipeline } from 'stream';
 
 export type HttpProxy = {
   port: number;
@@ -12,6 +13,10 @@ export type StartHttpProxyOptions = {
   headers?: Record<string, string>;
 };
 
+/**
+ * Legacy origin-form reverse proxy: forwards every request on the local port
+ * to `remoteBaseUrl`. New callers should prefer `startForwardHttpProxy`.
+ */
 export async function startHttpProxy({
   localPort = 0,
   remoteBaseUrl,
@@ -58,6 +63,139 @@ export async function startHttpProxy({
   };
 }
 
+export type StartForwardHttpProxyOptions = {
+  /** Loopback requests to this port are rewritten to remoteBaseUrl; everything else passes through. */
+  matchPort: number;
+  remoteBaseUrl: string;
+  headers?: Record<string, string>;
+};
+
+// Hop-by-hop headers must not be forwarded by an HTTP proxy (RFC 9110 §7.6.1).
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'proxy-connection',
+  'keep-alive',
+  'proxy-authorization',
+  'proxy-authenticate',
+  'te',
+  'trailer',
+  'upgrade',
+]);
+
+function withoutHopByHop(headers: http.IncomingHttpHeaders): http.IncomingHttpHeaders {
+  return Object.fromEntries(Object.entries(headers).filter(([name]) => !HOP_BY_HOP_HEADERS.has(name)));
+}
+
+/**
+ * Single-destination HTTP forward proxy (absolute-form request targets, as sent
+ * by clients configured with e.g. JVM -Dhttp.proxyHost). Loopback requests on
+ * `matchPort` are forwarded to `remoteBaseUrl`; every other target is refused,
+ * so the proxy can only ever reach the destination it was configured with.
+ */
+export async function startForwardHttpProxy({
+  matchPort,
+  remoteBaseUrl,
+  headers = {},
+}: StartForwardHttpProxyOptions): Promise<HttpProxy> {
+  const base = trimTrailingSlashes(remoteBaseUrl);
+  // The driver polls the runner continuously, so upstream connections must be
+  // reused instead of paying a TCP/TLS handshake per driver call.
+  const agents = {
+    'http:': new http.Agent({ keepAlive: true }),
+    'https:': new https.Agent({ keepAlive: true }),
+  };
+  const server = http.createServer((req, res) => {
+    let target: URL | undefined;
+    try {
+      target = new URL(req.url ?? '');
+    } catch {
+      // Falls through to the guard below.
+    }
+    if (!target || (target.protocol !== 'http:' && target.protocol !== 'https:')) {
+      res.writeHead(400, { 'content-type': 'text/plain' });
+      res.end('Limrun forward proxy only accepts absolute-form request targets.');
+      return;
+    }
+
+    // matchPort is always explicit (an ephemeral port or 7001), so a target
+    // without a port can never match. Anything else is refused rather than
+    // forwarded: the requested host never selects the destination, so this
+    // proxy cannot be pointed at another host.
+    if (!isLoopbackHost(target.hostname) || Number(target.port) !== matchPort) {
+      res.writeHead(403, { 'content-type': 'text/plain' });
+      res.end(`Limrun forward proxy only forwards 127.0.0.1:${matchPort}.`);
+      return;
+    }
+
+    const upstreamUrl = new URL(`${base}${target.pathname}${target.search}`);
+    const transport = upstreamUrl.protocol === 'https:' ? https : http;
+    const upstream = transport.request(
+      upstreamUrl,
+      {
+        agent: agents[upstreamUrl.protocol as keyof typeof agents],
+        method: req.method,
+        headers: {
+          ...withoutHopByHop(req.headers),
+          host: upstreamUrl.host,
+          ...headers,
+        },
+      },
+      (upstreamResponse) => {
+        res.writeHead(upstreamResponse.statusCode ?? 502, withoutHopByHop(upstreamResponse.headers));
+        // pipeline tears down whichever side is still alive when the other one
+        // dies, instead of leaking it or raising an unhandled 'error'.
+        pipeline(upstreamResponse, res, () => {});
+      },
+    );
+
+    upstream.on('error', (error) => {
+      if (res.headersSent) {
+        // Mid-stream failure: abort instead of appending error text to a
+        // partial body.
+        res.destroy(error);
+        return;
+      }
+      res.writeHead(502, { 'content-type': 'text/plain' });
+      res.end(error.message);
+    });
+    // A client that aborts mid-call must not leak the upstream socket.
+    res.on('close', () => {
+      if (!res.writableFinished) {
+        upstream.destroy();
+      }
+    });
+    pipeline(req, upstream, () => {});
+  });
+
+  // HTTPS clients open CONNECT tunnels; we deliberately keep TLS traffic off this
+  // proxy (only http.proxyHost is set on the JVM side), so refuse loudly instead
+  // of tunneling blind.
+  server.on('connect', (_req, socket) => {
+    socket.end('HTTP/1.1 501 Not Implemented\r\n\r\nLimrun forward proxy does not tunnel CONNECT.\r\n');
+  });
+
+  await listen(server, 0);
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to start HTTP forward proxy.');
+  }
+  return {
+    port: address.port,
+    close: async () => {
+      await closeServer(server);
+      agents['http:'].destroy();
+      agents['https:'].destroy();
+    },
+  };
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  // URL.hostname keeps brackets around IPv6 hosts.
+  return (
+    hostname === 'localhost' || hostname === '[::1]' || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)
+  );
+}
+
 function trimTrailingSlashes(value: string): string {
   return value.replace(/\/+$/, '');
 }

package/src/index.ts

@@ -8,7 +8,22 @@ 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 {
+  startHttpProxy,
+  startForwardHttpProxy,
+  type HttpProxy,
+  type StartHttpProxyOptions,
+  type StartForwardHttpProxyOptions,
+} from './http-proxy';
+export {
+  prepareMaestroRun,
+  isMaestroRunnerRunning,
+  waitForMaestroRunner,
+  maestroSpawnOptions,
+  MAESTRO_RUNNER_BUNDLE_ID,
+  MAESTRO_RUNNER_PORT,
+  type MaestroRun,
+} from './ios-maestro';
 export { buildSettingKeyPattern, parseBuildSettingEntries, validateBuildSettings } from './build-settings';
 export {
   exec,
@@ -16,13 +31,15 @@ export {
   type XcodeBuildExecRequest,
   type GradleAndroidABI,
   type GradleBuildExecRequest,
+  type GradlePlaystoreConfig,
   type GradleReactNativeConfig,
   type GradleSigningConfig,
   type ExecOptions,
   type ExecResult,
   type ExecChildProcess,
-  type TestflightEvent,
-  type TestflightUploadConfig,
+  type AppStoreEvent,
+  type AppStoreUploadConfig,
+  type PlaystoreEvent,
   type WebhookConfig,
 } from './exec-client';
 export {

package/src/ios-client.ts

@@ -10,7 +10,11 @@ import { createIgnoreFn } from './folder-sync-ignore';
 import { prepareAppBundlePath, watchAppArchive } from './app-archive';
 import { downloadFileToLocalPath } from './internal/download-file';
 import { nodeProxyTransport } from './internal/proxy-transport';
-import { startHttpProxy as startLocalHttpProxy } from './http-proxy';
+import {
+  startHttpProxy as startLocalHttpProxy,
+  startForwardHttpProxy as startLocalForwardHttpProxy,
+  type StartForwardHttpProxyOptions,
+} from './http-proxy';
 import { startXcrunShim as startClientXcrunShim } from './ios-shim';
 
 /**
@@ -210,6 +214,8 @@ export type HttpProxyOptions = {
   localPort: number;
 };
 
+export type ForwardHttpProxyOptions = Omit<StartForwardHttpProxyOptions, 'headers'>;
+
 /**
  * Targets a file operation at an installed app's container instead of the
  * sandbox staging folder. Mirrors `simctl get_app_container` semantics.
@@ -749,6 +755,16 @@ export type InstanceClient = {
    */
   startHttpProxy: (options: HttpProxyOptions) => Promise<number>;
 
+  /**
+   * Start a local HTTP forward proxy (for clients driven by JVM/system proxy
+   * settings, like Maestro) that rewrites loopback requests on `matchPort` to a
+   * port exposed by the iOS instance and passes other targets through.
+   *
+   * Returns the local port the proxy is listening on. The proxy is closed when
+   * the client disconnects.
+   */
+  startForwardHttpProxy: (options: ForwardHttpProxyOptions) => Promise<number>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -1861,6 +1877,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             softReset,
             startReverseTunnel,
             startHttpProxy,
+            startForwardHttpProxy,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
@@ -2507,6 +2524,20 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return proxy.port;
     };
 
+    const startForwardHttpProxy = async (proxyOptions: ForwardHttpProxyOptions): Promise<number> => {
+      assertPort(proxyOptions.matchPort, 'matchPort', 1, 65535);
+
+      const proxy = await startLocalForwardHttpProxy({
+        matchPort: proxyOptions.matchPort,
+        remoteBaseUrl: proxyOptions.remoteBaseUrl,
+        headers: {
+          authorization: `Bearer ${options.token}`,
+        },
+      });
+      httpProxyCleanups.push(proxy.close);
+      return proxy.port;
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();

package/src/ios-maestro.ts

@@ -0,0 +1,154 @@
+import path from 'path';
+import net from 'net';
+import { execFile } from 'child_process';
+
+import type { InstanceClient } from './ios-client';
+
+export const MAESTRO_RUNNER_BUNDLE_ID = 'dev.mobile.maestro-driver-iosUITests.xctrunner';
+/** Port the patched Maestro XCTest runner listens on inside the simulator. */
+export const MAESTRO_RUNNER_PORT = 22087;
+
+// Maestro installs as a .bat/.cmd wrapper on Windows, which spawn can only
+// execute through a shell.
+export const maestroSpawnOptions = { shell: process.platform === 'win32' } as const;
+
+export type MaestroRun = {
+  maestroVersion: string;
+  driverPort: number;
+  /** Environment overrides for the `maestro` process; merge over process.env. */
+  env: Record<string, string>;
+  /** Arguments to place between `maestro test` and the flow arguments. */
+  args: string[];
+};
+
+/**
+ * Wire a locally installed stock Maestro CLI to this instance's remote XCTest
+ * runner: starts the xcrun shim and an HTTP forward proxy, and returns the
+ * environment and `maestro test` arguments that route the driver traffic to
+ * the remote runner. Both are torn down when the client disconnects.
+ *
+ * Maestro's driver talks plain HTTP to 127.0.0.1:<driverPort>. Nothing listens
+ * there: the JVM proxy settings route those requests (absolute-form) to the
+ * forward proxy, which rewrites them to the remote runner and passes other
+ * targets through.
+ */
+export async function prepareMaestroRun(
+  client: InstanceClient,
+  options: { runnerUrl: string },
+): Promise<MaestroRun> {
+  const [maestroVersion, shimDir] = await Promise.all([detectMaestroVersion(), client.startXcrunShim()]);
+  // Maestro 2.5.x hardcodes driver port 7001 and has no --driver-host-port
+  // flag; 2.6+ picks a random port unless the flag is passed.
+  const withDriverHostPortFlag = supportsDriverHostPort(maestroVersion);
+  const driverPort = withDriverHostPortFlag ? await findFreePort() : 7001;
+  const proxyPort = await client.startForwardHttpProxy({
+    remoteBaseUrl: options.runnerUrl,
+    matchPort: driverPort,
+  });
+  const maestroOpts = [
+    process.env['MAESTRO_OPTS'],
+    `-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=${proxyPort} -Dhttp.nonProxyHosts=`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  return {
+    maestroVersion,
+    driverPort,
+    env: {
+      MAESTRO_OPTS: maestroOpts,
+      PATH: `${shimDir}${path.delimiter}${process.env['PATH'] ?? ''}`,
+      USE_XCODE_TEST_RUNNER: '1',
+    },
+    args: [
+      '--platform',
+      'ios',
+      '--device',
+      client.deviceInfo.udid,
+      '--no-reinstall-driver',
+      ...(withDriverHostPortFlag ? ['--driver-host-port', String(driverPort)] : []),
+    ],
+  };
+}
+
+/** Poll the remote Maestro XCTest runner until it responds, e.g. right after launching it. */
+export async function waitForMaestroRunner(
+  runnerUrl: string,
+  token: string,
+  timeoutMs = 15000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isMaestroRunnerRunning(runnerUrl, token)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  return false;
+}
+
+/** Probe the remote Maestro XCTest runner's /status endpoint. */
+export async function isMaestroRunnerRunning(runnerUrl: string, token: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetch(`${runnerUrl}/status`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    // Also on failure: a pending timer keeps the event loop alive.
+    clearTimeout(timeout);
+  }
+}
+
+function detectMaestroVersion(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('maestro', ['--version'], { encoding: 'utf8', ...maestroSpawnOptions }, (error, stdout) => {
+      if (error) {
+        reject(
+          new Error(
+            'Failed to run `maestro --version`. Install the Maestro CLI first: https://docs.maestro.dev/getting-started/installing-maestro',
+          ),
+        );
+        return;
+      }
+      // stdout only: update notices can also start with a version string and
+      // land on stderr or after the real version.
+      const version = stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => /^\d+\.\d+\.\d+/.test(line));
+      if (!version) {
+        reject(new Error('Could not parse the Maestro CLI version from `maestro --version` output.'));
+        return;
+      }
+      resolve(version);
+    });
+  });
+}
+
+function supportsDriverHostPort(version: string): boolean {
+  const [major = 0, minor = 0] = version.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  return major > 2 || (major === 2 && minor >= 6);
+}
+
+// Finds a free port and releases it immediately: Maestro validates that the
+// driver port is bindable, so it must stay unbound on our side.
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close();
+        reject(new Error('Failed to find a free port.'));
+        return;
+      }
+      server.close(() => resolve(address.port));
+    });
+  });
+}