@limrun/api 0.22.2 → 0.23.1

package/src/folder-sync.ts

@@ -4,9 +4,9 @@ import os from 'os';
 import crypto from 'crypto';
 import { spawn } from 'child_process';
 import { watchFolderTree } from './folder-sync-watcher';
+import { type IgnoreFn } from './folder-sync-ignore';
 import { Readable } from 'stream';
 import * as zlib from 'zlib';
-import ignore, { type Ignore } from 'ignore';
 
 // =============================================================================
 // Folder Sync (HTTP batch)
@@ -21,32 +21,32 @@ 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 `.limsync-cache/`.
+   * Defaults to a temporary directory under the OS temp directory.
    */
-  basisCacheDir?: string;
-  install?: boolean;
-  launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
+  basisCacheDir: string;
+  install: boolean;
+  launchMode: 'ForegroundIfRunning' | 'RelaunchIfRunning';
   /** If true, watch the folder and re-sync on any changes (debounced, single-flight). */
-  watch?: boolean;
+  watch: boolean;
   /** Max patch size (bytes) to send as delta before falling back to full upload. */
-  maxPatchBytes?: number;
+  maxPatchBytes: number;
   /** Controls logging verbosity */
-  log?: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+  log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
   /**
-   * Optional filter function to include/exclude files and directories.
+   * Predicate for ignoring files and directories during sync.
    * Called with the relative path from localFolderPath (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
+   * ignoreFn: (path) => path.startsWith('build/')
    *
    * @example
-   * // Only include source files
-   * filter: (path) => path.startsWith('src/') || path.endsWith('.json')
+   * // Ignore anything outside src/ and JSON files
+   * ignoreFn: (path) => !(path.startsWith('src/') || path.endsWith('.json'))
    */
-  filter?: (relativePath: string) => boolean;
+  ignoreFn: IgnoreFn;
 };
 
 export type SyncFolderResult = {
@@ -246,40 +246,30 @@ async function sha256FileHex(filePath: string): Promise<string> {
   });
 }
 
-async function walkFiles(root: string, filter?: (relativePath: string) => boolean): Promise<FileEntry[]> {
+async function walkFiles(root: string, ignoreFn: IgnoreFn): 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) {
-      // 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;
+        // Check custom ignores (directories have trailing slash)
+        if (ignoreFn(relDir)) continue;
         stack.push(abs);
         continue;
       }
       if (!ent.isFile()) continue;
 
-      // Check custom filter for files
-      if (filter && !filter(rel)) continue;
+      // Check custom ignores for files
+      if (ignoreFn(rel)) continue;
 
       const st = await fs.promises.stat(abs);
       const sha256 = await sha256FileHex(abs);
@@ -292,22 +282,6 @@ async function walkFiles(root: string, filter?: (relativePath: string) => boolea
   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) {
@@ -338,19 +312,6 @@ async function runXdelta3Encode(basis: string, target: string, outPatch: string)
   });
 }
 
-function localBasisCacheRoot(opts: FolderSyncOptions, localFolderPath: string): string {
-  const hostKey = opts.apiUrl.replace(/[:/]+/g, '_');
-  const resolved = path.resolve(localFolderPath);
-  const base = path.basename(resolved);
-  const hash = crypto.createHash('sha1').update(resolved).digest('hex').slice(0, 8);
-  const rootOverride =
-    opts.basisCacheDir ?
-      path.resolve(process.cwd(), opts.basisCacheDir)
-    : 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}`);
-}
-
 async function cachePut(cacheRoot: string, relPath: string, srcFile: string): Promise<void> {
   const dst = path.join(cacheRoot, relPath.split('/').join(path.sep));
   await fs.promises.mkdir(path.dirname(dst), { recursive: true });
@@ -361,9 +322,14 @@ function cacheGet(cacheRoot: string, relPath: string): string {
   return path.join(cacheRoot, relPath.split('/').join(path.sep));
 }
 
-export type SyncAppResult = SyncFolderResult;
-
-export async function syncApp(localFolderPath: string, opts: FolderSyncOptions): Promise<SyncFolderResult> {
+export async function syncFolder(
+  localFolderPath: string,
+  opts: FolderSyncOptions,
+): Promise<SyncFolderResult> {
+  const log = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
+    (opts.log ?? noopLogger)(level, `syncFolder: ${msg}`);
+  };
+  log('debug', `setup ${localFolderPath} watch=${opts.watch} basisCacheDir=${opts.basisCacheDir}`);
   if (!opts.watch) {
     const result = await syncFolderOnce(localFolderPath, opts);
     return result;
@@ -389,13 +355,10 @@ export async function syncApp(localFolderPath: string, opts: FolderSyncOptions):
       }
     }
   };
-
-  const watcherLog = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
-    (opts.log ?? noopLogger)(level, `syncApp: ${msg}`);
-  };
   const watcher = await watchFolderTree({
     rootPath: localFolderPath,
-    log: watcherLog,
+    log,
+    ignoreFn: opts.ignoreFn,
     onChange: (reason) => {
       void run(reason);
     },
@@ -417,24 +380,18 @@ async function syncFolderOnce(
 ): Promise<SyncFolderResult> {
   const totalStart = nowMs();
   const log = opts.log ?? noopLogger;
-  const slog = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => log(level, `syncApp: ${msg}`);
+  const slog = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => log(level, `syncFolder: ${msg}`);
   const maxPatchBytes = opts.maxPatchBytes ?? 4 * 1024 * 1024;
-
-  const tEnsureStart = nowMs();
   await ensureXdelta3();
-  const tEnsureMs = nowMs() - tEnsureStart;
 
-  const tWalkStart = nowMs();
-  const files = await walkFiles(localFolderPath, opts.filter);
-  const tWalkMs = nowMs() - tWalkStart;
+  const files = await walkFiles(localFolderPath, opts.ignoreFn);
   const fileMap = new Map(files.map((f) => [f.path, f]));
 
   const syncId = genId('sync');
   const rootName = path.basename(path.resolve(localFolderPath));
   const preferredCompression = (zlib as any).createZstdCompress ? 'zstd' : 'gzip';
 
-  const cacheRoot = localBasisCacheRoot(opts, localFolderPath);
-  await fs.promises.mkdir(cacheRoot, { recursive: true });
+  await fs.promises.mkdir(opts.basisCacheDir, { recursive: true });
 
   // Track how many bytes we actually transmit to the server (single HTTP request).
   let bytesSentFull = 0;
@@ -447,7 +404,7 @@ async function syncFolderOnce(
   const encodeLimit = concurrencyLimit();
   const changed: FileEntry[] = [];
   for (const f of files) {
-    const basisPath = cacheGet(cacheRoot, f.path);
+    const basisPath = cacheGet(opts.basisCacheDir, f.path);
     if (!fs.existsSync(basisPath)) {
       changed.push(f);
       continue;
@@ -459,7 +416,7 @@ async function syncFolderOnce(
   }
 
   const encodedPayloads = await mapLimit(changed, encodeLimit, async (f): Promise<EncodedPayload> => {
-    const basisPath = cacheGet(cacheRoot, f.path);
+    const basisPath = cacheGet(opts.basisCacheDir, f.path);
     if (fs.existsSync(basisPath)) {
       const basisSha = await sha256FileHex(basisPath);
       const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'limulator-xdelta3-'));
@@ -505,7 +462,7 @@ async function syncFolderOnce(
   const meta: FolderSyncHttpMeta = {
     id: syncId,
     rootName,
-    install: opts.install ?? true,
+    install: opts.install,
     ...(opts.launchMode ? { launchMode: opts.launchMode } : {}),
     files: files.map((f) => ({ path: f.path, size: f.size, sha256: f.sha256.toLowerCase(), mode: f.mode })),
     payloads: encodedPayloads.map((p) => p.payload),
@@ -513,7 +470,7 @@ async function syncFolderOnce(
   const hasDelta = encodedPayloads.some((p) => p.payload.kind === 'delta');
   const compression: 'zstd' | 'gzip' | 'identity' = hasDelta ? 'identity' : preferredCompression;
   slog(
-    'info',
+    'debug',
     `sync started files=${files.length}${reason ? ` reason=${reason}` : ''} compression=${compression}`,
   );
 
@@ -590,18 +547,11 @@ async function syncFolderOnce(
   const tookMs = nowMs() - totalStart;
   const totalBytes = bytesSentFull + bytesSentDelta;
   slog(
-    'info',
+    'debug',
     `sync finished files=${files.length} sent=${fmtBytes(totalBytes)} syncWork=${fmtMs(
       syncWorkMs,
     )} total=${fmtMs(tookMs)}`,
   );
-  slog('debug', `sync bytes full=${fmtBytes(bytesSentFull)} delta=${fmtBytes(bytesSentDelta)}`);
-  slog(
-    'debug',
-    `timing ensureXdelta3=${fmtMs(tEnsureMs)} walk=${fmtMs(tWalkMs)} httpSend=${fmtMs(
-      httpSendMsTotal,
-    )} deltaEncode=${fmtMs(deltaEncodeMsTotal)}`,
-  );
   const out: SyncFolderResult = {};
   if (resp.installedAppPath) {
     out.installedAppPath = resp.installedAppPath;
@@ -611,7 +561,7 @@ async function syncFolderOnce(
   }
   // Update local cache optimistically: after a successful sync, cache reflects current local tree.
   for (const f of files) {
-    await cachePut(cacheRoot, f.path, f.absPath);
+    await cachePut(opts.basisCacheDir, f.path, f.absPath);
   }
   return out;
 }

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[]> => {