@limrun/api 0.33.1 → 0.33.3

package/src/app-archive.ts

@@ -0,0 +1,345 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { pipeline } from 'stream/promises';
+import * as yauzl from 'yauzl';
+
+type LogFn = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
+
+export type PreparedAppBundle = {
+  appPath: string;
+  cacheIdentityPath: string;
+  isArchive: boolean;
+  archivePath?: string;
+};
+
+export type ArchiveWatcher = {
+  close: () => void;
+};
+
+const noopLogger: LogFn = () => {};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function stableArchiveRoot(archivePath: string): string {
+  const resolved = path.resolve(archivePath);
+  const hash = crypto.createHash('sha1').update(resolved).digest('hex').slice(0, 12);
+  const base = path
+    .basename(resolved, path.extname(resolved))
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const safeBase = base === '' ? 'app' : base;
+  return path.join(os.tmpdir(), `limrun-sync-app-${safeBase}-${hash}`);
+}
+
+function stableAppPath(archivePath: string): string {
+  return path.join(stableArchiveRoot(archivePath), 'Extracted.app');
+}
+
+function toZipPath(name: string): string {
+  return name.replace(/\\/g, '/');
+}
+
+function isUnsafeZipPath(name: string): boolean {
+  if (name.includes('\0')) return true;
+  if (path.posix.isAbsolute(name)) return true;
+  return name.split('/').some((part) => part === '..');
+}
+
+function entryMode(entry: yauzl.Entry): number {
+  return (entry.externalFileAttributes >>> 16) & 0xffff;
+}
+
+function isSymlinkEntry(entry: yauzl.Entry): boolean {
+  return (entryMode(entry) & 0o170000) === 0o120000;
+}
+
+function isDirectoryEntry(entry: yauzl.Entry): boolean {
+  return entry.fileName.endsWith('/');
+}
+
+function entryPerm(entry: yauzl.Entry, fallback: number): number {
+  return entryMode(entry) & 0o7777 || fallback;
+}
+
+async function openZip(archivePath: string): Promise<yauzl.ZipFile> {
+  try {
+    return await yauzl.openPromise(archivePath, {
+      autoClose: false,
+      lazyEntries: true,
+      strictFileNames: true,
+      validateEntrySizes: true,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? `: ${err.message}` : '';
+    throw new Error(
+      `The path is not a valid app bundle directory or ZIP/IPA archive: ${archivePath}${message}`,
+    );
+  }
+}
+
+async function readEntries(zip: yauzl.ZipFile): Promise<yauzl.Entry[]> {
+  const entries: yauzl.Entry[] = [];
+  for await (const entry of zip.eachEntry()) {
+    entries.push(entry);
+  }
+  return entries;
+}
+
+async function ensureDirectoryNotSymlink(dir: string): Promise<void> {
+  const stat = await fs.promises.lstat(dir).catch((err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+  await fs.promises.mkdir(dir, { recursive: true });
+}
+
+function discoverPayloadApp(entries: yauzl.Entry[], archivePath: string): string {
+  const appNames = new Set<string>();
+  const appsWithInfoPlist = new Set<string>();
+
+  for (const entry of entries) {
+    const name = toZipPath(entry.fileName);
+    if (isUnsafeZipPath(name)) {
+      throw new Error(`ZIP entry has an unsafe path: ${entry.fileName}`);
+    }
+    if (isDirectoryEntry(entry)) {
+      continue;
+    }
+    const rest = name.startsWith('Payload/') ? name.slice('Payload/'.length) : '';
+    if (rest === '') {
+      continue;
+    }
+    const [appName, ...parts] = rest.split('/');
+    if (!appName?.endsWith('.app')) {
+      continue;
+    }
+    appNames.add(appName);
+    if (parts.join('/') === 'Info.plist') {
+      appsWithInfoPlist.add(appName);
+    }
+  }
+
+  if (appNames.size === 0) {
+    throw new Error(`ZIP/IPA archive contains no Payload/*.app bundle: ${archivePath}`);
+  }
+  if (appNames.size > 1) {
+    throw new Error(
+      `ZIP/IPA archive contains more than one Payload/*.app bundle (${[...appNames].join(
+        ', ',
+      )}); expected exactly one`,
+    );
+  }
+
+  const appName = [...appNames][0]!;
+  if (!appsWithInfoPlist.has(appName)) {
+    throw new Error(`ZIP/IPA archive app bundle is missing Info.plist: Payload/${appName}/Info.plist`);
+  }
+  return appName;
+}
+
+async function extractEntry(
+  zip: yauzl.ZipFile,
+  entry: yauzl.Entry,
+  target: string,
+  appRoot: string,
+): Promise<void> {
+  if (isDirectoryEntry(entry)) {
+    await fs.promises.mkdir(target, { recursive: true, mode: entryPerm(entry, 0o755) });
+    return;
+  }
+
+  await fs.promises.mkdir(path.dirname(target), { recursive: true });
+  if (isSymlinkEntry(entry)) {
+    const stream = await zip.openReadStreamPromise(entry);
+    const chunks: Buffer[] = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const linkTarget = Buffer.concat(chunks).toString('utf8');
+    const resolved = path.resolve(path.dirname(target), linkTarget);
+    const appRootResolved = path.resolve(appRoot);
+    if (resolved !== appRootResolved && !resolved.startsWith(appRootResolved + path.sep)) {
+      throw new Error(`ZIP/IPA symlink escapes app bundle: ${entry.fileName} -> ${linkTarget}`);
+    }
+    await fs.promises.rm(target, { force: true });
+    await fs.promises.symlink(linkTarget, target);
+    return;
+  }
+
+  const stream = await zip.openReadStreamPromise(entry);
+  await pipeline(stream, fs.createWriteStream(target, { mode: entryPerm(entry, 0o644) }));
+  await fs.promises.chmod(target, entryPerm(entry, 0o644));
+}
+
+export async function extractAppArchiveToStablePath(archivePath: string): Promise<PreparedAppBundle> {
+  const resolvedArchivePath = path.resolve(archivePath);
+  const appPath = stableAppPath(resolvedArchivePath);
+  const stableRoot = path.dirname(appPath);
+
+  await ensureDirectoryNotSymlink(stableRoot);
+  const zip = await openZip(resolvedArchivePath);
+  try {
+    const entries = await readEntries(zip);
+    const appName = discoverPayloadApp(entries, resolvedArchivePath);
+    const payloadPrefix = `Payload/${appName}/`;
+    await fs.promises.rm(appPath, { recursive: true, force: true });
+    await ensureDirectoryNotSymlink(appPath);
+
+    for (const entry of entries) {
+      const name = toZipPath(entry.fileName);
+      if (name !== `Payload/${appName}` && !name.startsWith(payloadPrefix)) {
+        continue;
+      }
+      const rel = name === `Payload/${appName}` ? '' : name.slice(payloadPrefix.length);
+      if (rel === '') {
+        await fs.promises.mkdir(appPath, { recursive: true });
+        continue;
+      }
+      if (isUnsafeZipPath(rel)) {
+        throw new Error(`ZIP entry has an unsafe app-relative path: ${entry.fileName}`);
+      }
+      const target = path.join(appPath, rel.split('/').join(path.sep));
+      const stagingAppResolved = path.resolve(appPath);
+      const targetResolved = path.resolve(target);
+      if (
+        targetResolved !== stagingAppResolved &&
+        !targetResolved.startsWith(stagingAppResolved + path.sep)
+      ) {
+        throw new Error(`ZIP entry escapes app bundle: ${entry.fileName}`);
+      }
+      await extractEntry(zip, entry, target, appPath);
+    }
+
+    return {
+      appPath,
+      cacheIdentityPath: resolvedArchivePath,
+      isArchive: true,
+      archivePath: resolvedArchivePath,
+    };
+  } finally {
+    zip.close();
+  }
+}
+
+export async function prepareAppBundlePath(inputPath: string): Promise<PreparedAppBundle> {
+  const resolvedPath = path.resolve(inputPath);
+  const stat = await fs.promises.stat(resolvedPath);
+  if (stat.isDirectory()) {
+    return {
+      appPath: resolvedPath,
+      cacheIdentityPath: resolvedPath,
+      isArchive: false,
+    };
+  }
+  if (!stat.isFile()) {
+    throw new Error(`The path is neither an app bundle directory nor a ZIP/IPA archive: ${inputPath}`);
+  }
+  return await extractAppArchiveToStablePath(resolvedPath);
+}
+
+async function waitForStableArchiveFile(archivePath: string, shouldStop: () => boolean): Promise<boolean> {
+  const deadline = Date.now() + 10_000;
+  let previous: { size: number; mtimeMs: number } | undefined;
+
+  while (!shouldStop() && Date.now() < deadline) {
+    const stat = await fs.promises.stat(archivePath).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    });
+
+    if (stat?.isFile()) {
+      const current = { size: stat.size, mtimeMs: stat.mtimeMs };
+      if (previous && previous.size === current.size && previous.mtimeMs === current.mtimeMs) {
+        return true;
+      }
+      previous = current;
+    } else {
+      previous = undefined;
+    }
+
+    await sleep(100);
+  }
+
+  return false;
+}
+
+export function watchAppArchive(opts: {
+  archivePath: string;
+  log?: LogFn;
+  onExtracted?: () => void | Promise<void>;
+}): ArchiveWatcher {
+  const archivePath = path.resolve(opts.archivePath);
+  const log = opts.log ?? noopLogger;
+  const parentDir = path.dirname(archivePath);
+  const archiveBase = path.basename(archivePath);
+  let timer: NodeJS.Timeout | undefined;
+  let inFlight = false;
+  let queued = false;
+  let closed = false;
+
+  const run = async () => {
+    if (closed) return;
+    if (inFlight) {
+      queued = true;
+      return;
+    }
+    inFlight = true;
+    try {
+      const ready = await waitForStableArchiveFile(archivePath, () => closed);
+      if (!ready) {
+        if (!closed) {
+          log('warn', `ZIP/IPA archive did not become readable after change: ${archivePath}`);
+        }
+        return;
+      }
+      await extractAppArchiveToStablePath(archivePath);
+      log('debug', `re-extracted ZIP/IPA archive: ${archivePath}`);
+      await opts.onExtracted?.();
+    } catch (err) {
+      log(
+        'error',
+        `failed to re-extract ZIP/IPA archive ${archivePath}: ${err instanceof Error ? err.message : err}`,
+      );
+    } finally {
+      inFlight = false;
+      if (queued) {
+        queued = false;
+        void run();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (closed) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      void run();
+    }, 500);
+  };
+
+  const watcher = fs.watch(parentDir, (_eventType, filename) => {
+    if (filename?.toString() === archiveBase) {
+      schedule();
+    }
+  });
+  log('debug', `watchAppArchive: ${archivePath}`);
+
+  return {
+    close: () => {
+      closed = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher.close();
+    },
+  };
+}

package/src/instance-client.ts

@@ -88,6 +88,12 @@ export type InstanceClient = {
    * Open a URL/deeplink on Android.
    */
   openUrl: (url: string) => Promise<OpenUrlResult>;
+  /**
+   * Play an on-device WAV/MP3 file as microphone input.
+   *
+   * The file must already exist on the Android instance, for example after pushing it with ADB.
+   */
+  playOnMicrophone: (path: string, options?: PlayOnMicrophoneOptions) => Promise<PlayOnMicrophoneResult>;
   /**
    * Set Android Wi-Fi bandwidth limits in Kbps. Omit a direction to leave it unchanged;
    * pass `0` to clear that direction's limit.
@@ -287,6 +293,17 @@ export type OpenUrlResult = {
   url: string;
 };
 
+export type PlayOnMicrophoneOptions = {
+  once?: boolean;
+};
+
+export type PlayOnMicrophoneResult = {
+  /** Duration of the decoded audio in microseconds. */
+  duration: number;
+  once: boolean;
+  generation: number;
+};
+
 export type WifiBandwidthOptions = {
   downKbps?: number;
   upKbps?: number;
@@ -381,6 +398,13 @@ type OpenUrlResultMessage = {
   error?: CommandError;
 };
 
+type PlayOnMicrophoneResultMessage = {
+  type: 'playOnMicrophoneResult';
+  id: string;
+  payload?: PlayOnMicrophoneResult;
+  error?: CommandError;
+};
+
 type SetWifiBandwidthResultMessage = {
   type: 'setWifiBandwidthResult';
   id: string;
@@ -412,6 +436,7 @@ type KnownCommandResultMessage =
   | ScrollScreenResultMessage
   | ScrollElementResultMessage
   | OpenUrlResultMessage
+  | PlayOnMicrophoneResultMessage
   | SetWifiBandwidthResultMessage
   | StartVideoRecordingResultMessage
   | StopVideoRecordingResultMessage;
@@ -433,6 +458,7 @@ type CommandRequestMap = {
   scrollScreen: { direction: ScrollDirection; amount?: number };
   scrollElement: AndroidElementTarget & { direction: ScrollDirection; amount?: number };
   openUrl: { url: string };
+  playOnMicrophone: { path: string; once?: boolean };
   setWifiBandwidth: WifiBandwidthOptions;
   startRecording: { quality?: RecordingQuality };
   stopRecording: { upload?: { presignedUrl: string } };
@@ -448,6 +474,7 @@ type CommandResultMap = {
   scrollScreen: ScrollResult;
   scrollElement: ScrollResult;
   openUrl: OpenUrlResult;
+  playOnMicrophone: PlayOnMicrophoneResult;
   setWifiBandwidth: EmptyCommandResult;
   startRecording: EmptyCommandResult;
   stopRecording: EmptyCommandResult;
@@ -614,6 +641,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         case 'scrollScreenResult':
         case 'scrollElementResult':
         case 'openUrlResult':
+        case 'playOnMicrophoneResult':
         case 'setWifiBandwidthResult':
         case 'startRecordingResult':
         case 'stopRecordingResult':
@@ -854,6 +882,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             scrollScreen,
             scrollElement,
             openUrl,
+            playOnMicrophone,
             setWifiBandwidth,
             startRecording,
             stopRecording,
@@ -947,6 +976,19 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       };
     };
 
+    const playOnMicrophone = async (
+      inputPath: string,
+      microphoneOptions?: PlayOnMicrophoneOptions,
+    ): Promise<PlayOnMicrophoneResult> => {
+      if (!inputPath) {
+        throw new Error('path must be a non-empty string');
+      }
+      return sendRequest('playOnMicrophone', {
+        path: inputPath,
+        ...(microphoneOptions?.once === undefined ? {} : { once: microphoneOptions.once }),
+      });
+    };
+
     const setWifiBandwidth = async (bandwidthOptions: WifiBandwidthOptions): Promise<void> => {
       const request: CommandRequestMap['setWifiBandwidth'] = {};
       if (bandwidthOptions.downKbps !== undefined) {

package/src/ios-client.ts

@@ -7,6 +7,7 @@ import { EventEmitter } from 'events';
 import { assertPort, isNonRetryableError, startReverseTcpTunnel, type ReverseTunnel } from './tunnel';
 import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
 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';
@@ -1900,7 +1901,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         watch?: boolean;
       },
     ): Promise<SyncFolderResult> => {
-      const infoPlistPath = path.join(localAppBundlePath, 'Info.plist');
+      const preparedApp = await prepareAppBundlePath(localAppBundlePath);
+      const appBundlePath = preparedApp.appPath;
+      const infoPlistPath = path.join(appBundlePath, '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}`);
@@ -1908,11 +1911,12 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       if (!cachedDeviceInfo) {
         throw new Error('Device info not available yet; wait for client connection to be established.');
       }
-      const resolvedPath = path.resolve(localAppBundlePath);
+      const resolvedPath = path.resolve(preparedApp.cacheIdentityPath);
       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 shouldWatch = opts?.watch ?? true;
       const syncLog: FolderSyncOptions['log'] = (level, msg) => {
         switch (level) {
           case 'debug':
@@ -1936,15 +1940,31 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         apiUrl: options.apiUrl,
         token: options.token,
         udid: cacheKey,
-        ignoreFn: await createIgnoreFn(localAppBundlePath, { basisCacheDir, log: syncLog }),
+        ignoreFn: await createIgnoreFn(appBundlePath, { basisCacheDir, log: syncLog }),
         basisCacheDir,
         log: syncLog,
         install: opts?.install ?? true,
         maxPatchBytes: opts?.maxPatchBytes ?? 4 * 1024 * 1024,
         launchMode: opts?.launchMode ?? 'ForegroundIfRunning',
-        watch: opts?.watch ?? true,
+        watch: preparedApp.isArchive ? false : shouldWatch,
+      };
+      const result = await syncFolder(appBundlePath, folderSyncOpts);
+      if (!preparedApp.isArchive || !preparedApp.archivePath || !shouldWatch) {
+        return result;
+      }
+      const archiveWatcher = watchAppArchive({
+        archivePath: preparedApp.archivePath,
+        log: syncLog,
+        onExtracted: async () => {
+          await syncFolder(appBundlePath, folderSyncOpts);
+        },
+      });
+      return {
+        ...result,
+        stopWatching: () => {
+          archiveWatcher.close();
+        },
       };
-      return await syncFolder(localAppBundlePath, folderSyncOpts);
     };
 
     const lsof = (): Promise<LsofEntry[]> => {

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.33.1'; // x-release-please-version
+export const VERSION = '0.33.3'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.33.1";
+export declare const VERSION = "0.33.3";
 //# 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.33.1'; // x-release-please-version
+exports.VERSION = '0.33.3'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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