@limrun/api 0.19.2 → 0.20.0

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
@@ -209,6 +219,26 @@ export type InstanceClient = {
    */
   launchApp: (bundleId: string) => Promise<void>;
 
+  /**
+   * Fetch the last N lines of app logs (combined stdout/stderr)
+   * @param bundleId Bundle identifier of the app
+   * @param lines Number of lines to return (clamped to server limit)
+   */
+  appLogTail: (bundleId: string, lines: number) => Promise<string>;
+
+  /**
+   * Stream app logs for a bundle ID (batched lines every ~500ms)
+   * @param bundleId Bundle identifier of the app
+   * @returns LogStream handle (use .stop() to unsubscribe)
+   */
+  streamAppLog: (bundleId: string) => LogStream;
+
+  /**
+   * Stream syslog (batched lines every ~500ms)
+   * @returns LogStream handle (use .stop() to unsubscribe)
+   */
+  streamSyslog: () => LogStream;
+
   /**
    * List installed apps on the simulator
    * @returns Array of installed apps with bundleId, name, and installType
@@ -479,6 +509,10 @@ type ServerResponse = {
   stdout?: string;
   stderr?: string;
   exitCode?: number;
+  // Log tail fields
+  logs?: string;
+  // App log streaming fields
+  lines?: string[];
 };
 
 /**
@@ -653,6 +687,134 @@ export class SimctlExecution extends EventEmitter {
   }
 }
 
+/**
+ * Handle for a running log stream subscription (app logs or syslog).
+ *
+ * Uses a dedicated WebSocket connection separate from the main signaling connection.
+ * Emits batched log lines every ~500ms when new lines arrive.
+ */
+export interface LogStreamEvents {
+  lines: (lines: string[]) => void;
+  line: (line: string) => void;
+  error: (error: Error) => void;
+  close: () => void;
+}
+
+/** @internal - Message from log stream WebSocket */
+type LogStreamMessage = {
+  type: string;
+  id: string;
+  lines?: string[];
+  error?: string;
+};
+
+/**
+ * Log stream with dedicated WebSocket connection.
+ * Each LogStream opens its own WebSocket to isolate log traffic from signaling.
+ */
+export class LogStream extends EventEmitter {
+  private ws: WebSocket | null = null;
+  private subscriptionId: string;
+  private stopped = false;
+  private terminateMessageType: string;
+
+  /** @internal */
+  constructor(
+    private wsUrl: string,
+    private subscribeMessage: object,
+    terminateMessageType: string,
+    subscriptionId: string,
+  ) {
+    super();
+    this.terminateMessageType = terminateMessageType;
+    this.subscriptionId = subscriptionId;
+    this._connect();
+  }
+
+  override on<E extends keyof LogStreamEvents>(event: E, listener: LogStreamEvents[E]): this {
+    return super.on(event, listener as any);
+  }
+
+  override once<E extends keyof LogStreamEvents>(event: E, listener: LogStreamEvents[E]): this {
+    return super.once(event, listener as any);
+  }
+
+  override off<E extends keyof LogStreamEvents>(event: E, listener: LogStreamEvents[E]): this {
+    return super.off(event, listener as any);
+  }
+
+  /** Stop the log stream and close the dedicated WebSocket connection */
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      // Send terminate message before closing
+      const terminateMsg = { type: this.terminateMessageType, id: this.subscriptionId };
+      try {
+        this.ws.send(JSON.stringify(terminateMsg));
+      } catch {
+        // Ignore send errors during shutdown
+      }
+      this.ws.close();
+    }
+    this.ws = null;
+    this.emit('close');
+  }
+
+  /** @internal - Establish the dedicated WebSocket connection */
+  private _connect(): void {
+    this.ws = new WebSocket(this.wsUrl);
+
+    this.ws.on('open', () => {
+      if (this.stopped) {
+        this.ws?.close();
+        return;
+      }
+      // Send subscription message
+      this.ws?.send(JSON.stringify(this.subscribeMessage), (err?: Error) => {
+        if (err) {
+          this.emit('error', err);
+          this.stop();
+        }
+      });
+    });
+
+    this.ws.on('message', (data: Data) => {
+      if (this.stopped) return;
+      try {
+        const message: LogStreamMessage = JSON.parse(data.toString());
+        if (message.error) {
+          this.emit('error', new Error(message.error));
+          return;
+        }
+        if (message.lines && message.lines.length > 0) {
+          this.emit('lines', message.lines);
+          for (const line of message.lines) {
+            this.emit('line', line);
+          }
+        }
+      } catch (e) {
+        // Ignore parse errors for non-JSON messages
+      }
+    });
+
+    this.ws.on('error', (err: Error) => {
+      if (!this.stopped) {
+        this.emit('error', err);
+      }
+    });
+
+    this.ws.on('close', () => {
+      if (!this.stopped) {
+        this.stopped = true;
+        this.emit('close');
+      }
+      this.ws = null;
+    });
+  }
+}
+
 /**
  * Creates a client for interacting with a Limrun iOS instance
  * @param options Configuration options including webrtcUrl, token and log level
@@ -835,6 +997,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       typeTextResult: () => undefined,
       pressKeyResult: () => undefined,
       launchAppResult: () => undefined,
+      appLogTailResult: (msg) => msg.logs ?? '',
       listAppsResult: (msg) => JSON.parse(msg.apps || '[]') as InstalledApp[],
       listOpenFilesResult: (msg) => msg.files || [],
       deviceInfoResult: (msg) => ({
@@ -1003,6 +1166,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             screenshot,
             elementTree,
             tap,
+            tapWithScreenSize,
             tapElement,
             incrementElement,
             decrementElement,
@@ -1010,6 +1174,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             typeText,
             pressKey,
             launchApp,
+            appLogTail,
+            streamAppLog,
+            streamSyslog,
             listApps,
             openUrl,
             installApp,
@@ -1043,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> => {
@@ -1074,6 +1263,22 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<void>('launchApp', { bundleId });
     };
 
+    const appLogTail = (bundleId: string, lines: number): Promise<string> => {
+      return sendRequest<string>('appLogTail', { bundleId, lines });
+    };
+
+    const streamAppLog = (bundleId: string): LogStream => {
+      const id = generateId();
+      const subscribeMessage = { type: 'streamAppLog', id, bundleId };
+      return new LogStream(endpointWebSocketUrl, subscribeMessage, 'streamAppLogTerminate', id);
+    };
+
+    const streamSyslog = (): LogStream => {
+      const id = generateId();
+      const subscribeMessage = { type: 'streamSyslog', id };
+      return new LogStream(endpointWebSocketUrl, subscribeMessage, 'streamSyslogTerminate', id);
+    };
+
     const listApps = (): Promise<InstalledApp[]> => {
       return sendRequest<InstalledApp[]>('listApps');
     };