@limrun/api 0.19.3 → 0.20.1

package/src/exec-client.ts

@@ -0,0 +1,327 @@
+/**
+ * Client for executing commands on limbuild server with streaming output.
+ *
+ * The interface is designed to be similar to Node.js's child_process.spawn()
+ * for familiarity and ease of extension.
+ */
+
+import { createEventSource, type EventSourceClient, type EventSourceMessage } from 'eventsource-client';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ExecRequest = {
+  command: 'xcodebuild';
+  xcodebuild?: {
+    workspace?: string;
+    project?: string;
+    scheme?: string;
+  };
+};
+
+export type ExecOptions = {
+  apiUrl: string;
+  token: string;
+  log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+};
+
+export type ExecResult = {
+  exitCode: number;
+  execId: string;
+  status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
+};
+
+type DataListener = (chunk: string) => void;
+type CloseListener = () => void;
+type ExitListener = (code: number) => void;
+
+/**
+ * A Readable-like stream interface, similar to Node.js stream.Readable.
+ * Emits 'data' for each chunk and 'close' when the stream ends.
+ */
+export class ReadableStream {
+  private dataListeners: DataListener[] = [];
+  private closeListeners: CloseListener[] = [];
+  private closed = false;
+
+  on(event: 'data', listener: DataListener): this;
+  on(event: 'close', listener: CloseListener): this;
+  on(event: 'data' | 'close', listener: DataListener | CloseListener): this {
+    if (event === 'data') {
+      this.dataListeners.push(listener as DataListener);
+    } else if (event === 'close') {
+      this.closeListeners.push(listener as CloseListener);
+    }
+    return this;
+  }
+
+  /** @internal */
+  emit(event: 'data', chunk: string): void;
+  emit(event: 'close'): void;
+  emit(event: 'data' | 'close', arg?: string): void {
+    if (event === 'data' && typeof arg === 'string') {
+      for (const l of this.dataListeners) l(arg);
+    } else if (event === 'close' && !this.closed) {
+      this.closed = true;
+      for (const l of this.closeListeners) l();
+    }
+  }
+}
+
+/**
+ * A ChildProcess-like object similar to Node.js's ChildProcess.
+ *
+ * Implements PromiseLike so it can be awaited directly.
+ *
+ * @example
+ * // Stream-based (like Node.js spawn)
+ * const proc = exec({ command: 'xcodebuild' }, options);
+ * proc.stdout.on('data', (chunk) => process.stdout.write(chunk));
+ * proc.stderr.on('data', (chunk) => process.stderr.write(chunk));
+ * proc.on('exit', (code) => console.log(`Exited with code ${code}`));
+ *
+ * // Promise-based (can be awaited)
+ * const { exitCode, status } = await proc;
+ */
+export class ExecChildProcess implements PromiseLike<ExecResult> {
+  /** Stdout stream - emits 'data' and 'close' events */
+  readonly stdout = new ReadableStream();
+
+  /** Stderr stream - emits 'data' and 'close' events */
+  readonly stderr = new ReadableStream();
+
+  /** The remote process/build identifier (similar to pid in Node.js) */
+  execId: string | undefined;
+
+  private readonly resultPromise: Promise<ExecResult>;
+  private readonly exitListeners: ExitListener[] = [];
+  private abortController = new AbortController();
+  private sseConnection: EventSourceClient | null = null;
+  private killed = false;
+  private readonly options: ExecOptions;
+  private readonly log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+
+  constructor(request: ExecRequest, options: ExecOptions) {
+    this.options = options;
+    this.log = options.log ?? (() => {});
+    this.resultPromise = this.run(request);
+  }
+
+  /** Implement PromiseLike so this object can be awaited */
+  then<TResult1 = ExecResult, TResult2 = never>(
+    onfulfilled?: ((value: ExecResult) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.resultPromise.then(onfulfilled, onrejected);
+  }
+
+  /** Catch errors */
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<ExecResult | TResult> {
+    return this.resultPromise.catch(onrejected);
+  }
+
+  /** Finally handler */
+  finally(onfinally?: (() => void) | null): Promise<ExecResult> {
+    return this.resultPromise.finally(onfinally);
+  }
+
+  /** Listen for process events */
+  on(event: 'exit', listener: ExitListener): this {
+    if (event === 'exit') {
+      this.exitListeners.push(listener);
+    }
+    return this;
+  }
+
+  /** Send a signal to terminate the process */
+  async kill(): Promise<void> {
+    this.killed = true;
+    this.abortController.abort();
+    if (this.sseConnection) {
+      this.sseConnection.close();
+      this.sseConnection = null;
+    }
+    if (!this.execId) {
+      this.log('warn', 'Failed to cancel build: execId is not set');
+      return;
+    }
+    try {
+      await fetch(`${this.options.apiUrl}/exec/${this.execId}/cancel`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.options.token}`,
+        },
+      });
+      this.log('info', 'Build cancelled');
+    } catch (err) {
+      this.log('warn', `Failed to cancel build: ${err}`);
+    }
+  }
+
+  private async run(request: ExecRequest): Promise<ExecResult> {
+    const { log } = this;
+    const { apiUrl, token } = this.options;
+
+    // 1. Trigger the build via POST /exec
+    log('debug', `POST ${apiUrl}/exec`);
+    let execRes: Response;
+    try {
+      execRes = await fetch(`${apiUrl}/exec`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(request),
+        signal: this.abortController.signal,
+      });
+    } catch (err) {
+      if (this.killed) {
+        this.stdout.emit('close');
+        this.stderr.emit('close');
+        for (const listener of this.exitListeners) {
+          listener(-1);
+        }
+        return { exitCode: -1, execId: '', status: 'CANCELLED' };
+      }
+      throw err;
+    }
+
+    if (!execRes.ok) {
+      const text = await execRes.text();
+      throw new Error(`exec failed: ${execRes.status} ${text}`);
+    }
+
+    const execData = (await execRes.json()) as { execId: string };
+    this.execId = execData.execId;
+    log('info', `Build started: ${this.execId}`);
+
+    // 2. Stream logs via SSE and wait for exit code
+    const eventsUrl = `${apiUrl}/exec/${this.execId}/events`;
+    log('debug', `GET ${eventsUrl} (SSE)`);
+
+    const timeoutMs = 3600 * 1000; // 1 hour max
+    let exitCode: number;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      exitCode = await Promise.race([
+        this.connectSSE(eventsUrl),
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error('SSE timeout')), timeoutMs);
+        }),
+      ]);
+    } catch {
+      if (this.killed) {
+        log('info', 'Build killed');
+        exitCode = -1;
+      } else {
+        log('warn', 'SSE completion timeout');
+        exitCode = 1;
+      }
+    } finally {
+      clearTimeout(timeoutId);
+      if (this.sseConnection) {
+        this.sseConnection.close();
+        this.sseConnection = null;
+      }
+    }
+
+    // Emit close events on streams
+    this.stdout.emit('close');
+    this.stderr.emit('close');
+
+    // Emit exit event
+    for (const listener of this.exitListeners) {
+      listener(exitCode);
+    }
+
+    // Determine status from exit code
+    const status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED' =
+      exitCode === 0 ? 'SUCCEEDED'
+      : exitCode === -1 ? 'CANCELLED'
+      : 'FAILED';
+
+    const result: ExecResult = {
+      exitCode,
+      execId: this.execId!,
+      status,
+    };
+
+    this.log('info', `Build finished: ${result.status} (exit ${result.exitCode})`);
+    return result;
+  }
+
+  /**
+   * Opens an SSE connection and routes events to stdout/stderr streams.
+   * Resolves with the exit code when an 'exitCode' event arrives.
+   * Rejects when the abort signal fires (kill or cleanup).
+   */
+  private connectSSE(eventsUrl: string): Promise<number> {
+    return new Promise<number>((resolve, reject) => {
+      if (this.abortController.signal.aborted) {
+        reject(new Error('killed'));
+        return;
+      }
+
+      try {
+        const eventSource = createEventSource({
+          url: eventsUrl,
+          headers: { Authorization: `Bearer ${this.options.token}` },
+          onMessage: (message: EventSourceMessage) => {
+            const data = typeof message.data === 'string' ? message.data : String(message.data ?? '');
+            const eventType = message.event;
+            if (eventType === 'stdout') {
+              this.stdout.emit('data', data);
+            } else if (eventType === 'stderr') {
+              this.stderr.emit('data', data);
+            } else if (eventType === 'exitCode') {
+              const exitCode = parseInt(data, 10);
+              if (Number.isNaN(exitCode)) {
+                this.log('warn', `SSE exitCode event has invalid data: ${data}`);
+                return;
+              }
+              this.log('debug', `Build completed via SSE: exitCode=${exitCode}`);
+              resolve(exitCode);
+            }
+          },
+          onDisconnect: () => {
+            if (!this.killed) {
+              this.log('warn', 'SSE disconnected');
+            }
+          },
+        });
+        this.sseConnection = eventSource;
+
+        this.abortController.signal.addEventListener('abort', () => reject(new Error('killed')), {
+          once: true,
+        });
+      } catch (err) {
+        if (!this.killed) {
+          this.log('warn', `SSE setup failed: ${err}`);
+        }
+        reject(err);
+      }
+    });
+  }
+}
+
+/**
+ * Execute a command on the limbuild server.
+ * Returns a ChildProcess-like object with stdout/stderr streams.
+ *
+ * @example
+ * const proc = exec({ command: 'xcodebuild' }, { apiUrl: '...', token: '...' });
+ *
+ * // Stream output
+ * proc.stdout.on('data', (chunk) => console.log('[stdout]', chunk));
+ * proc.stderr.on('data', (chunk) => console.error('[stderr]', chunk));
+ *
+ * // Wait for completion
+ * const { exitCode, status } = await proc;
+ */
+export function exec(request: ExecRequest, options: ExecOptions): ExecChildProcess {
+  return new ExecChildProcess(request, options);
+}

package/src/folder-sync.ts

@@ -6,6 +6,7 @@ import { spawn } from 'child_process';
 import { watchFolderTree } from './folder-sync-watcher';
 import { Readable } from 'stream';
 import * as zlib from 'zlib';
+import ignore, { type Ignore } from 'ignore';
 
 // =============================================================================
 // Folder Sync (HTTP batch)
@@ -20,7 +21,7 @@ export type FolderSyncOptions = {
    * Used to store the last-synced “basis” copies of files (and related sync metadata) so we can compute xdelta patches
    * on subsequent syncs without re-downloading server state.
    *
-   * Can be absolute or relative to process.cwd(). Defaults to `.lim-metadata-cache/`.
+   * Can be absolute or relative to process.cwd(). Defaults to `.limsync-cache/`.
    */
   basisCacheDir?: string;
   install?: boolean;
@@ -31,6 +32,21 @@ export type FolderSyncOptions = {
   maxPatchBytes?: number;
   /** Controls logging verbosity */
   log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+  /**
+   * Optional filter function to include/exclude files and directories.
+   * Called with the relative path from localFolderPath (using forward slashes).
+   * For directories, the path ends with '/'.
+   * Return true to include, false to exclude.
+   *
+   * @example
+   * // Exclude build folder
+   * filter: (path) => !path.startsWith('build/')
+   *
+   * @example
+   * // Only include source files
+   * filter: (path) => path.startsWith('src/') || path.endsWith('.json')
+   */
+  filter?: (relativePath: string) => boolean;
 };
 
 export type SyncFolderResult = {
@@ -63,6 +79,10 @@ type FolderSyncHttpMeta = {
 type FolderSyncHttpResponse = {
   ok: boolean;
   needFull?: string[];
+  // Timing fields
+  syncDurationMs?: number;
+  installDurationMs?: number; // limulator only
+  // Install result fields (limulator only)
   installedAppPath?: string;
   bundleId?: string;
   error?: string;
@@ -123,7 +143,7 @@ async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T) => Promis
 }
 
 function folderSyncHttpUrl(apiUrl: string): string {
-  return `${apiUrl}/folder-sync`;
+  return `${apiUrl}/sync`;
 }
 
 function u32be(n: number): Buffer {
@@ -226,23 +246,42 @@ async function sha256FileHex(filePath: string): Promise<string> {
   });
 }
 
-async function walkFiles(root: string): Promise<FileEntry[]> {
-  const out: FileEntry[] = [];
-  const stack: string[] = [root];
+async function walkFiles(root: string, filter?: (relativePath: string) => boolean): Promise<FileEntry[]> {
   const rootResolved = path.resolve(root);
+
+  // Load .gitignore if it exists
+  const ig = await loadGitignore(rootResolved);
+
+  const out: FileEntry[] = [];
+  const stack: string[] = [rootResolved];
   while (stack.length) {
     const dir = stack.pop()!;
     const entries = await fs.promises.readdir(dir, { withFileTypes: true });
     for (const ent of entries) {
-      if (ent.name === '.DS_Store') continue;
+      // Always skip .git folder and .DS_Store
+      if (ent.name === '.DS_Store' || ent.name === '.git') continue;
+
       const abs = path.join(dir, ent.name);
+      const rel = path.relative(rootResolved, abs).split(path.sep).join('/');
+
+      // Check if ignored by .gitignore
+      if (ig.ignores(rel)) continue;
+
       if (ent.isDirectory()) {
+        // For directories, check with trailing slash
+        const relDir = rel + '/';
+        if (ig.ignores(relDir)) continue;
+        // Check custom filter (directories have trailing slash)
+        if (filter && !filter(relDir)) continue;
         stack.push(abs);
         continue;
       }
       if (!ent.isFile()) continue;
+
+      // Check custom filter for files
+      if (filter && !filter(rel)) continue;
+
       const st = await fs.promises.stat(abs);
-      const rel = path.relative(rootResolved, abs).split(path.sep).join('/');
       const sha256 = await sha256FileHex(abs);
       // Preserve POSIX permission bits (including +x). Mask out file-type bits.
       const mode = st.mode & 0o7777;
@@ -253,6 +292,22 @@ async function walkFiles(root: string): Promise<FileEntry[]> {
   return out;
 }
 
+/**
+ * Load and parse .gitignore file if it exists.
+ * Returns an Ignore instance that can be used to test paths.
+ */
+async function loadGitignore(rootDir: string): Promise<Ignore> {
+  const ig = ignore();
+  const gitignorePath = path.join(rootDir, '.gitignore');
+  try {
+    const content = await fs.promises.readFile(gitignorePath, 'utf-8');
+    ig.add(content);
+  } catch {
+    // No .gitignore file, return empty ignore instance
+  }
+  return ig;
+}
+
 let xdelta3Ready: Promise<void> | null = null;
 async function ensureXdelta3(): Promise<void> {
   if (!xdelta3Ready) {
@@ -291,7 +346,7 @@ function localBasisCacheRoot(opts: FolderSyncOptions, localFolderPath: string):
   const rootOverride =
     opts.basisCacheDir ?
       path.resolve(process.cwd(), opts.basisCacheDir)
-    : path.join(process.cwd(), '.lim-metadata-cache');
+    : path.join(process.cwd(), '.limsync-cache');
   // Include folder identity to avoid collisions between different roots.
   return path.join(rootOverride, 'folder-sync', hostKey, opts.udid, `${base}-${hash}`);
 }
@@ -310,7 +365,8 @@ export type SyncAppResult = SyncFolderResult;
 
 export async function syncApp(localFolderPath: string, opts: FolderSyncOptions): Promise<SyncFolderResult> {
   if (!opts.watch) {
-    return await syncFolderOnce(localFolderPath, opts);
+    const result = await syncFolderOnce(localFolderPath, opts);
+    return result;
   }
   // Initial sync, then watch for changes and re-run sync in the background.
   const first = await syncFolderOnce(localFolderPath, opts, 'startup');
@@ -353,14 +409,6 @@ export async function syncApp(localFolderPath: string, opts: FolderSyncOptions):
   };
 }
 
-// Back-compat alias (older callers)
-export async function syncFolder(
-  localFolderPath: string,
-  opts: FolderSyncOptions,
-): Promise<SyncFolderResult> {
-  return await syncApp(localFolderPath, opts);
-}
-
 async function syncFolderOnce(
   localFolderPath: string,
   opts: FolderSyncOptions,
@@ -377,7 +425,7 @@ async function syncFolderOnce(
   const tEnsureMs = nowMs() - tEnsureStart;
 
   const tWalkStart = nowMs();
-  const files = await walkFiles(localFolderPath);
+  const files = await walkFiles(localFolderPath, opts.filter);
   const tWalkMs = nowMs() - tWalkStart;
   const fileMap = new Map(files.map((f) => [f.path, f]));
 

package/src/index.ts

@@ -8,6 +8,22 @@ export { Limrun, type ClientOptions } from './client';
 export { PagePromise } from './core/pagination';
 export * from './instance-client';
 export * as Ios from './ios-client';
+export {
+  createXCodeSandboxClient,
+  type XCodeSandboxClient,
+  type CreateXCodeSandboxClientOptions,
+  type SimulatorConfig,
+  type SyncOptions,
+  type SyncResult,
+  type XcodeBuildConfig,
+} from './sandbox-client';
+export {
+  exec,
+  type ExecRequest,
+  type ExecOptions,
+  type ExecResult,
+  type ExecChildProcess,
+} from './exec-client';
 export {
   LimrunError,
   APIError,

package/src/internal/parse.ts

@@ -29,6 +29,12 @@ export async function defaultParseResponse<T>(client: Limrun, props: APIResponse
     const mediaType = contentType?.split(';')[0]?.trim();
     const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
     if (isJSON) {
+      const contentLength = response.headers.get('content-length');
+      if (contentLength === '0') {
+        // if there is no content we can't do anything
+        return undefined as T;
+      }
+
       const json = await response.json();
       return json as T;
     }

package/src/ios-client.ts

@@ -153,12 +153,22 @@ export type InstanceClient = {
   elementTree: (point?: AccessibilityPoint) => Promise<string>;
 
   /**
-   * Tap at the specified coordinates
+   * Tap at the specified coordinates (uses device's native screen dimensions)
    * @param x X coordinate in points
    * @param y Y coordinate in points
    */
   tap: (x: number, y: number) => Promise<void>;
 
+  /**
+   * Tap at coordinates with explicit screen size.
+   * Use this when coordinates are in a different coordinate space than the device's native dimensions.
+   * @param x X coordinate in the provided screen coordinate space
+   * @param y Y coordinate in the provided screen coordinate space
+   * @param screenWidth Width of the coordinate space
+   * @param screenHeight Height of the coordinate space
+   */
+  tapWithScreenSize: (x: number, y: number, screenWidth: number, screenHeight: number) => Promise<void>;
+
   /**
    * Tap an accessibility element by selector
    * @param selector The selector criteria to find the element
@@ -805,9 +815,6 @@ export class LogStream extends EventEmitter {
   }
 }
 
-/** @deprecated Use LogStream instead */
-export const AppLogStream = LogStream;
-
 /**
  * Creates a client for interacting with a Limrun iOS instance
  * @param options Configuration options including webrtcUrl, token and log level
@@ -1159,6 +1166,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             screenshot,
             elementTree,
             tap,
+            tapWithScreenSize,
             tapElement,
             incrementElement,
             decrementElement,
@@ -1202,7 +1210,29 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     };
 
     const tap = (x: number, y: number): Promise<void> => {
-      return sendRequest<void>('tap', { x, y });
+      return sendRequest<void>('tap', {
+        x,
+        y,
+        screenWidth: cachedDeviceInfo?.screenWidth,
+        screenHeight: cachedDeviceInfo?.screenHeight,
+      });
+    };
+
+    /**
+     * Tap at coordinates with explicit screen size.
+     * Use this when coordinates are in a different coordinate space than the device's native dimensions.
+     * @param x - X coordinate in the provided screen coordinate space
+     * @param y - Y coordinate in the provided screen coordinate space
+     * @param screenWidth - Width of the coordinate space
+     * @param screenHeight - Height of the coordinate space
+     */
+    const tapWithScreenSize = (
+      x: number,
+      y: number,
+      screenWidth: number,
+      screenHeight: number,
+    ): Promise<void> => {
+      return sendRequest<void>('tap', { x, y, screenWidth, screenHeight });
     };
 
     const tapElement = (selector: AccessibilitySelector): Promise<TapElementResult> => {