@limrun/api 0.22.2 → 0.23.0

package/src/ios-client.ts

@@ -1,8 +1,14 @@
 import { WebSocket, Data } from 'ws';
 import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
 import { EventEmitter } from 'events';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
 import { isNonRetryableError } from './tunnel';
-import { syncApp as syncAppImpl, type SyncFolderResult, type FolderSyncOptions } from './folder-sync';
+import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
+import { createIgnoreFn } from './folder-sync-ignore';
 
 /**
  * Connection state of the instance client
@@ -14,6 +20,46 @@ export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'rec
  */
 export type ConnectionStateCallback = (state: ConnectionState) => void;
 
+function generateRecordingFilename(): string {
+  const rand = Math.random().toString(36).slice(2, 5).padEnd(3, '0');
+  const now = new Date();
+  const formattedDate = now.toISOString().replace(/[-:]/g, '_').replace('T', '_').replace(/\..+/, '');
+
+  // Example: 20240602_17_45_30 for June 2, 2024 17:45:30 UTC
+  return `ios_video_${formattedDate}_${rand}.mp4`;
+}
+
+async function downloadFileToLocalPath(url: string, token: string, localPath: string): Promise<void> {
+  const maxRetries = 3;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      const isRetriable = response.status >= 500 && response.status < 600;
+      if (isRetriable && attempt < maxRetries) {
+        continue;
+      }
+      throw new Error(`Download failed: ${response.status} ${errorBody}`);
+    }
+    if (!response.body) {
+      throw new Error('Download failed: response body is missing');
+    }
+    await fs.promises.mkdir(path.dirname(localPath), { recursive: true });
+    await pipeline(Readable.fromWeb(response.body as any), fs.createWriteStream(localPath));
+    return;
+  }
+}
+
+function buildDownloadUrl(apiUrl: string, filename: string): string {
+  return `${apiUrl}/files?name=${encodeURIComponent(filename)}`;
+}
+
 /**
  * Events emitted by a simctl execution
  */
@@ -295,13 +341,36 @@ export type InstanceClient = {
     options?: { coordinate?: [number, number]; momentum?: number },
   ) => Promise<void>;
 
+  /**
+   * Start recording simulator video. Use stopRecording() to stop the recording.
+   */
+  startRecording: () => Promise<void>;
+
+  /**
+   * Stop the active recording for this client instance.
+   * If `saveTo.presignedUrl` is provided, the server uploads the completed file there before resolving.
+   * If `saveTo.localPath` is provided, the client downloads the completed file to that path.
+   * If both are provided, both are performed.
+   * Returns a download URL for the completed recording that can be used to download using the token.
+   * Note that the download URL is only valid while the instance is running.
+   */
+  stopRecording: (saveTo: { presignedUrl?: string; localPath?: string }) => Promise<string>;
+
   /**
    * Sync an iOS app bundle folder to the server and (optionally) install/launch it.
+   * @param localAppBundlePath The path to the local app bundle folder
+   * @param opts Optional sync options
+   * @param opts.install If true, install the app after syncing. Defaults to true.
+   * @param opts.basisCacheDir Directory for the client-side folder-sync cache.
+   * @param opts.maxPatchBytes Max patch size (bytes) to send as delta before falling back to full upload. Defaults to 4MB.
+   * @param opts.launchMode Launch mode after installation: "ForegroundIfRunning" (default): bring to foreground if already running, otherwise launch, "RelaunchIfRunning": kill and relaunch if already running
+   * @param opts.watch If true, watch the folder and re-sync on any changes (debounced, single-flight).
    */
   syncApp: (
     localAppBundlePath: string,
     opts?: {
       install?: boolean;
+      basisCacheDir?: string;
       maxPatchBytes?: number;
       launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
       watch?: boolean;
@@ -513,6 +582,7 @@ type ServerResponse = {
   elementType?: string;
   apps?: string;
   url?: string;
+  filename?: string;
   bundleId?: string;
   files?: LsofEntry[];
   // Device info fields
@@ -850,6 +920,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
   let reconnectTimeout: NodeJS.Timeout | undefined;
   let intentionalDisconnect = false;
   let lastError: string | undefined;
+  let activeRecordingFilename: string | undefined;
 
   // Centralized pending requests map - handles all request/response patterns
   const pendingRequests: Map<string, PendingRequest<any>> = new Map();
@@ -1028,6 +1099,10 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         url: msg.url || '',
         bundleId: msg.bundleId || '',
       }),
+      startVideoRecordingResult: () => undefined,
+      stopVideoRecordingResult: (msg) => ({
+        filename: msg.filename || '',
+      }),
       setOrientationResult: () => undefined,
       scrollResult: () => undefined,
       xcrunResult: (msg): CommandResult => ({
@@ -1061,7 +1136,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         if (message.type === 'simctlStream') {
           const execution = simctlExecutions.get(message.id);
           if (!execution) {
-            logger.warn(`Received simctl stream for unknown execution: ${message.id}`);
+            logger.debug(`Received simctl stream for unknown execution: ${message.id}`);
             return;
           }
 
@@ -1200,6 +1275,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             installApp,
             setOrientation,
             scroll,
+            startRecording,
+            stopRecording,
             syncApp,
             disconnect,
             getConnectionState,
@@ -1341,22 +1418,74 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       });
     };
 
+    const startRecording = async (): Promise<void> => {
+      if (activeRecordingFilename) {
+        throw new Error(`A recording is already active for this client: ${activeRecordingFilename}`);
+      }
+      const finalFilename = generateRecordingFilename();
+      activeRecordingFilename = finalFilename;
+      try {
+        await sendRequest<void>('startVideoRecording', { filename: finalFilename });
+      } catch (error) {
+        if (activeRecordingFilename === finalFilename) {
+          activeRecordingFilename = undefined;
+        }
+        throw error;
+      }
+    };
+
+    const stopRecording = async (saveTo: { presignedUrl?: string; localPath?: string }): Promise<string> => {
+      const filename = activeRecordingFilename;
+      if (!filename) {
+        throw new Error('No active recording for this client. Call startRecording() first.');
+      }
+      const result = await sendRequest<{ filename: string }>('stopVideoRecording', {
+        filename,
+        upload: saveTo.presignedUrl ? { presignedUrl: saveTo.presignedUrl } : undefined,
+      });
+      const finalFilename = result.filename || filename;
+      const downloadUrl = buildDownloadUrl(options.apiUrl, finalFilename);
+      if (saveTo.localPath) {
+        try {
+          await downloadFileToLocalPath(downloadUrl, options.token, saveTo.localPath);
+        } finally {
+          activeRecordingFilename = undefined;
+        }
+      } else {
+        activeRecordingFilename = undefined;
+      }
+      return downloadUrl;
+    };
+
     const syncApp = async (
       localAppBundlePath: string,
       opts?: {
         install?: boolean;
+        basisCacheDir?: string;
         maxPatchBytes?: number;
         launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
         watch?: boolean;
       },
     ): Promise<SyncFolderResult> => {
+      const infoPlistPath = path.join(localAppBundlePath, 'Info.plist');
+      const infoPlistStat = await fs.promises.stat(infoPlistPath).catch(() => null);
+      if (!infoPlistStat?.isFile()) {
+        throw new Error(`The folder is not a valid app bundle: missing Info.plist at ${infoPlistPath}`);
+      }
       if (!cachedDeviceInfo) {
         throw new Error('Device info not available yet; wait for client connection to be established.');
       }
-      const appSyncOpts: FolderSyncOptions = {
+      const resolvedPath = path.resolve(localAppBundlePath);
+      const folderName = path.basename(resolvedPath);
+      const hash = crypto.createHash('sha1').update(resolvedPath).digest('hex').slice(0, 8);
+      const cacheKey = `limsync-cache-${folderName}-${hash}`;
+      const basisCacheDir = opts?.basisCacheDir ?? path.join(os.tmpdir(), cacheKey);
+      const folderSyncOpts: FolderSyncOptions = {
         apiUrl: options.apiUrl,
         token: options.token,
-        udid: cachedDeviceInfo.udid,
+        udid: cacheKey,
+        ignoreFn: await createIgnoreFn(localAppBundlePath, { basisCacheDir }),
+        basisCacheDir,
         log: (level, msg) => {
           switch (level) {
             case 'debug':
@@ -1376,12 +1505,12 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
               break;
           }
         },
-        ...(opts?.install !== undefined ? { install: opts.install } : {}),
-        ...(opts?.maxPatchBytes !== undefined ? { maxPatchBytes: opts.maxPatchBytes } : {}),
-        ...(opts?.launchMode !== undefined ? { launchMode: opts.launchMode } : {}),
-        ...(opts?.watch !== undefined ? { watch: opts.watch } : {}),
+        install: opts?.install ?? true,
+        maxPatchBytes: opts?.maxPatchBytes ?? 4 * 1024 * 1024,
+        launchMode: opts?.launchMode ?? 'ForegroundIfRunning',
+        watch: opts?.watch ?? true,
       };
-      return await syncAppImpl(localAppBundlePath, appSyncOpts);
+      return await syncFolder(localAppBundlePath, folderSyncOpts);
     };
 
     const lsof = (): Promise<LsofEntry[]> => {

package/src/sandbox-client.ts

@@ -1,5 +1,9 @@
-import { syncApp as syncFolderImpl, type FolderSyncOptions } from './folder-sync';
+import os from 'os';
+import path from 'path';
+import { syncFolder as syncFolderImpl, type FolderSyncOptions } from './folder-sync';
 import { exec, ExecChildProcess } from './exec-client';
+import { createIgnoreFn } from './folder-sync-ignore';
+import crypto from 'crypto';
 
 export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
 
@@ -27,32 +31,37 @@ export type SimulatorConfig = {
  */
 export type SyncOptions = {
   /**
-   * Cache scoping key for delta basis caching. Defaults to 'xcode-sandbox'.
-   * This is not sent to the server.
+   * If true, watch the folder and re-sync on any changes. Defaults to true.
    */
-  cacheKey?: string;
-  basisCacheDir?: string;
-  maxPatchBytes?: number;
+  watch?: boolean;
   /**
-   * If true, watch the folder and re-sync on any changes.
+   * Directory for the client-side folder-sync cache.
+   * 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.
+   *
+   * Defaults to a temporary directory under the OS temp directory.
    */
-  watch?: boolean;
-  log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+  basisCacheDir?: string;
+  /** Max patch size (bytes) to send as delta before falling back to full upload. */
+  maxPatchBytes?: number;
+  /** If true, install the app after syncing. Defaults to true. */
+  install?: boolean;
   /**
-   * Optional filter function to include/exclude files and directories.
+   * Optional predicate for ignoring files and directories during sync.
+   * Applied in addition to built-in sync and Xcode-specific ignore rules.
    * Called with the relative path from the sync root (using forward slashes).
    * For directories, the path ends with '/'.
-   * Return true to include, false to exclude.
+   * Return true to ignore, false to keep.
    *
    * @example
-   * // Exclude build folder
-   * filter: (path) => !path.startsWith('build/')
+   * // Ignore build folder
+   * ignore: (path) => path.startsWith('build/')
    *
    * @example
-   * // Only include source files
-   * filter: (path) => path.startsWith('src/') || path.endsWith('.json')
+   * // Ignore anything outside src/ and JSON files
+   * ignore: (path) => !(path.startsWith('src/') || path.endsWith('.json'))
    */
-  filter?: (relativePath: string) => boolean;
+  ignore?: (relativePath: string) => boolean;
 };
 
 /**
@@ -150,7 +159,7 @@ export async function createXCodeSandboxClient(
     },
   };
 
-  const logFn = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
+  const log = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
     switch (level) {
       case 'debug':
         logger.debug(msg);
@@ -196,54 +205,55 @@ export async function createXCodeSandboxClient(
 
   return {
     async sync(localCodePath: string, opts?: SyncOptions): Promise<SyncResult> {
+      // Use folder name and hash of absolute path to scope basisCacheDir uniquely for each sync root
+      const resolvedPath = path.resolve(localCodePath);
+      const folderName = path.basename(resolvedPath);
+      const hash = crypto.createHash('sha1').update(resolvedPath).digest('hex').slice(0, 8);
+      const cacheKey = `limsync-cache-${folderName}-${hash}`;
+      const basisCacheDir = opts?.basisCacheDir ?? path.join(os.tmpdir(), cacheKey);
       const codeSyncOpts: FolderSyncOptions = {
         apiUrl: options.apiUrl,
         token: options.token,
-        udid: opts?.cacheKey ?? 'xcode-sandbox',
-        install: false,
-        filter: (relativePath: string) => {
-          if (
-            relativePath.startsWith('build/') ||
-            relativePath.startsWith('.build/') ||
-            relativePath.startsWith('DerivedData/') ||
-            relativePath.startsWith('Index.noindex/') ||
-            relativePath.startsWith('ModuleCache.noindex/') ||
-            relativePath.startsWith('.index-build/')
-          ) {
+        udid: cacheKey,
+        install: opts?.install ?? true,
+        ignoreFn: await createIgnoreFn(localCodePath, {
+          basisCacheDir,
+          additional: (relativePath: string) => {
+            if (
+              relativePath.startsWith('build/') ||
+              relativePath.startsWith('.build/') ||
+              relativePath.startsWith('DerivedData/') ||
+              relativePath.startsWith('Index.noindex/') ||
+              relativePath.startsWith('ModuleCache.noindex/') ||
+              relativePath.startsWith('.index-build/')
+            ) {
+              return true;
+            }
+            if (
+              relativePath.startsWith('.swiftpm/') ||
+              relativePath.startsWith('Pods/') ||
+              relativePath.startsWith('Carthage/Build/')
+            ) {
+              return true;
+            }
+            if (relativePath.includes('/xcuserdata/')) {
+              return true;
+            }
+            if (relativePath.includes('.dSYM/')) {
+              return true;
+            }
+            // User-provided ignores
+            if (opts?.ignore?.(relativePath)) {
+              return true;
+            }
             return false;
-          }
-          if (
-            relativePath.startsWith('.swiftpm/') ||
-            relativePath.startsWith('Pods/') ||
-            relativePath.startsWith('Carthage/Build/')
-          ) {
-            return false;
-          }
-          if (
-            relativePath.startsWith('.git/') ||
-            relativePath.startsWith('.limsync-cache/') ||
-            relativePath === '.DS_Store' ||
-            relativePath.endsWith('/.DS_Store')
-          ) {
-            return false;
-          }
-          if (relativePath.includes('/xcuserdata/')) {
-            return false;
-          }
-          if (relativePath.includes('.dSYM/')) {
-            return false;
-          }
-
-          // User-provided filter
-          if (opts?.filter && !opts.filter(relativePath)) {
-            return false;
-          }
-          return true;
-        },
-        ...(opts?.basisCacheDir ? { basisCacheDir: opts.basisCacheDir } : {}),
-        ...(opts?.maxPatchBytes !== undefined ? { maxPatchBytes: opts.maxPatchBytes } : {}),
-        ...(opts?.watch !== undefined ? { watch: opts.watch } : {}),
-        log: opts?.log ?? logFn,
+          },
+        }),
+        basisCacheDir,
+        watch: opts?.watch ?? true,
+        maxPatchBytes: opts?.maxPatchBytes ?? 4 * 1024 * 1024,
+        launchMode: 'ForegroundIfRunning',
+        log,
       };
 
       const result = await syncFolderImpl(localCodePath, codeSyncOpts);
@@ -259,7 +269,7 @@ export async function createXCodeSandboxClient(
         {
           apiUrl: options.apiUrl,
           token: options.token,
-          log: logFn,
+          log,
         },
       );
     },

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.22.2'; // x-release-please-version
+export const VERSION = '0.23.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.22.2";
+export declare const VERSION = "0.23.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.22.2";
+export declare const VERSION = "0.23.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.22.2'; // x-release-please-version
+exports.VERSION = '0.23.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.22.2'; // x-release-please-version
+export const VERSION = '0.23.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map