@limrun/api 0.49.2 → 0.50.0

package/src/folder-sync-ignore.ts

@@ -11,12 +11,15 @@ export type IgnoreFn = (relativePath: string) => boolean;
 export type IgnoreLogger = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
 
 export type IgnoreFnOptions = {
-  /** User-supplied extra excludes (the CLI's --ignore). Consulted after every built-in layer. */
+  /**
+   * User-supplied extra excludes (the CLI's --ignore). Matches override
+   * built-in force-includes, but a matching --include still wins.
+   */
   additional?: IgnoreFn;
   /**
    * User-supplied force-includes (the CLI's --include): matches sync even when
-   * covered by a built-in exclude, gitignored, or covered by the default Xcode
-   * excludes. The basis cache remains excluded to prevent sync loops. Note:
+   * covered by --ignore, a built-in exclude, gitignored, or covered by the
+   * default Xcode excludes. The basis cache remains excluded to prevent sync loops. Note:
    * the walk prunes excluded directories, so to rescue files under a
    * wholly-excluded parent the predicate must also match the parent directory
    * paths (probed with a trailing slash), e.g. `^ios/` reaches
@@ -105,22 +108,22 @@ const XCODE_DEFAULT_EXCLUDE_PREFIXES = [
  * Builds the layered sync ignore predicate. First decisive answer wins:
  *
  *  1. The basis cache: excluded, never overridable.
- *  2. User include (--include): explicit intent beats every other exclusion.
- *  3. `.git` and `.DS_Store`.
- *  4. Default Xcode/dependency excludes (when xcodeDefaults is set).
- *  5. Built-in force-include: `*.xcconfig` and `.env` files (gitignored
+ *  2. User include (--include): explicit intent beats --ignore and every
+ *     overridable exclusion.
+ *  3. User ignore (--ignore): explicit exclusion beats built-in force-includes.
+ *  4. `.git` and `.DS_Store`.
+ *  5. Default Xcode/dependency excludes (when xcodeDefaults is set).
+ *  6. Built-in force-include: `*.xcconfig` and `.env` files (gitignored
  *     xcconfigs and env files are still required to reproduce the build
  *     remotely; Expo app configs routinely read `.env`). Gitignored projects
  *     are NOT force-included: limbuild regenerates them from project.yml, and
  *     exact-version holdouts force-sync theirs with `--include`.
- *  6. `.gitignore` chain: the root file, plus nested ones with git semantics
+ *  7. `.gitignore` chain: the root file, plus nested ones with git semantics
  *     when xcodeDefaults is set (rules bind relative to their containing
- *     directory, deeper files override shallower ones). Only a decisive
- *     *exclude* short-circuits; a negation re-include defers to layer 7.
- *     Directory pruning in the walk means only layers 2 and 5 can reach a
+ *     directory, deeper files override shallower ones).
+ *     Directory pruning in the walk means only layers 2 and 6 can reach a
  *     file whose parent directory is gitignore-excluded, and only when the
  *     predicate matches the pruned parent directory paths too.
- *  7. User ignore (--ignore).
  */
 export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions): Promise<IgnoreFn> {
   const rootResolved = path.resolve(rootDir);
@@ -210,7 +213,9 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     }
     // 2. User include.
     if (options.include?.(normalized)) return false;
-    // 3. Built-in excludes.
+    // 3. User ignore.
+    if (options.additional?.(normalized)) return true;
+    // 4. Built-in excludes.
     if (
       withoutTrailingSlash === '.git' ||
       withoutTrailingSlash.startsWith('.git/') ||
@@ -221,14 +226,14 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     ) {
       return true;
     }
-    // 4. Default Xcode/dependency excludes.
+    // 5. Default Xcode/dependency excludes.
     if (options.xcodeDefaults) {
       for (const prefix of XCODE_DEFAULT_EXCLUDE_PREFIXES) {
         if (normalized.startsWith(prefix)) return true;
       }
       if (normalized.includes('/xcuserdata/') || normalized.includes('.dSYM/')) return true;
     }
-    // 5. Built-in force-include: gitignored xcconfigs and .env files are
+    // 6. Built-in force-include: gitignored xcconfigs and .env files are
     // still required to reproduce the build remotely (Expo app configs read
     // .env / .env.local / .env.production at prebuild time). Gitignored
     // .xcodeproj bundles are NOT force-included: limbuild regenerates them
@@ -237,10 +242,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     if (withoutTrailingSlash.endsWith('.xcconfig')) return false;
     const basename = withoutTrailingSlash.slice(withoutTrailingSlash.lastIndexOf('/') + 1);
     if (basename.endsWith('.env') || basename.startsWith('.env.')) return false;
-    // 6. The .gitignore chain. Only a decisive *exclude* short-circuits; a
-    // negation re-include (decision.ignored === false) still falls through to
-    // the user --ignore layer, matching the pre-restructure precedence where
-    // gitignore never overrode --ignore for a re-included path.
+    // 7. The .gitignore chain.
     const decision = gitignoreDecision(normalized);
     if (decision?.ignored) {
       if (
@@ -260,8 +262,6 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
       }
       return true;
     }
-    // 7. User ignore.
-    if (options.additional?.(normalized)) return true;
     return false;
   };
 }

package/src/index.ts

@@ -133,6 +133,7 @@ export {
   type GradleClient,
   type GradleSyncOptions,
   type GradleBuildOptions,
+  type GradleRunOptions,
   type GradleBuildLog,
 } from './resources/gradle-instances-helpers';
 export { type AssetUploadOptions } from './resources/daemon-client-shared';

package/src/instance-client.ts

@@ -26,8 +26,11 @@ import { deriveDestinationTunnelURL } from './internal/destination-tunnel-url';
 import { persistFields, type PersistOption } from './internal/persist-option';
 import { streamSessionEntries } from './internal/session-stream';
 import type { SessionLogLine, SessionEvent } from './resources/session-artifacts';
+import { LogcatProcess } from './logcat-process';
 
 export { type PersistOption } from './internal/persist-option';
+export { LogStream, type LogStreamEvents } from './log-stream';
+export { LogcatProcess, type LogcatProcessEvents } from './logcat-process';
 
 const ANDROID_RECORDING_PATH = '/data/local/tmp/recordings/video_recording.mp4';
 const ANDROID_SIGNALING_PATH = '/ws';
@@ -278,6 +281,14 @@ export type InstanceClient = {
    *   non-zero `exitCode` is returned in the result, not thrown.
    */
   adbShell: (command: string, args?: string[], options?: AdbShellOptions) => Promise<AdbShellResult>;
+  /**
+   * Run logcat with the given arguments and stream its output over a
+   * per-run SSE stream. Arguments are forwarded to logcat verbatim, so dump
+   * vs follow is logcat's own vocabulary: `['-d']` or `['-t', '50']` exits
+   * after the dump, `['-T', '50']` or no arguments follows until
+   * {@link LogcatProcess.stop}. 'exit' fires with logcat's exit code.
+   */
+  logcat: (args?: string[]) => LogcatProcess;
   /**
    * Set Android Wi-Fi bandwidth limits in Kbps. Omit a direction to leave it unchanged;
    * pass `0` to clear that direction's limit.
@@ -1466,6 +1477,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             setCameraVideo,
             clearCameraVideo,
             adbShell,
+            logcat,
             setWifiBandwidth,
             startRecording,
             stopRecording,
@@ -1721,6 +1733,10 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       };
     };
 
+    const logcat = (args: string[] = []): LogcatProcess => {
+      return new LogcatProcess(options.apiUrl, options.token, args);
+    };
+
     const setWifiBandwidth = async (bandwidthOptions: WifiBandwidthOptions): Promise<void> => {
       const request: CommandRequestMap['setWifiBandwidth'] = {};
       if (bandwidthOptions.downKbps !== undefined) {

package/src/ios-client.ts

@@ -28,8 +28,10 @@ import { startXcrunShim as startClientXcrunShim } from './ios-shim';
 import { persistFields, type PersistOption } from './internal/persist-option';
 import { streamSessionEntries } from './internal/session-stream';
 import type { SessionLogLine, SessionEvent } from './resources/session-artifacts';
+import { LogStream } from './log-stream';
 
 export { type PersistOption } from './internal/persist-option';
+export { LogStream, type LogStreamEvents } from './log-stream';
 
 /**
  * Connection state of the instance client
@@ -1457,135 +1459,6 @@ 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 {
-    const proxyAgent = nodeProxyTransport.getWebSocketAgent(this.wsUrl);
-    this.ws = new WebSocket(this.wsUrl, proxyAgent ? { agent: proxyAgent } : {});
-
-    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
@@ -1675,6 +1548,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     }
     if (ws) {
       ws.removeAllListeners();
+      // A retired socket can emit an error when an unfinished handshake is cancelled.
+      ws.on('error', () => {});
       if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
         ws.close();
       }

package/src/log-stream.ts

@@ -0,0 +1,132 @@
+import { EventEmitter } from 'events';
+import { WebSocket, Data } from 'ws';
+import { nodeProxyTransport } from './internal/proxy-transport';
+
+/**
+ * Handle for a running log stream subscription (app logs, syslog, or logcat).
+ *
+ * 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 {
+    const proxyAgent = nodeProxyTransport.getWebSocketAgent(this.wsUrl);
+    this.ws = new WebSocket(this.wsUrl, proxyAgent ? { agent: proxyAgent } : {});
+
+    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 {
+        // 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;
+    });
+  }
+}

package/src/logcat-process.ts

@@ -0,0 +1,151 @@
+import { EventEmitter } from 'events';
+import { nodeProxyTransport } from './internal/proxy-transport';
+import { streamSessionEntries } from './internal/session-stream';
+
+/**
+ * Handle for one logcat invocation on an Android instance.
+ *
+ * The instance runs `logcat` with the caller's arguments and serves its
+ * output over a per-run SSE stream (same machinery as session capture
+ * streams), batched every ~500ms. Lines arrive via 'lines'/'line'; 'exit'
+ * fires once with logcat's exit code, or -1 when stopped or the stream is
+ * lost.
+ */
+export interface LogcatProcessEvents {
+  lines: (lines: string[]) => void;
+  line: (line: string) => void;
+  error: (error: Error) => void;
+  exit: (exitCode: number) => void;
+}
+
+/** @internal - One frame of the per-run logcat SSE stream */
+type LogcatEntry = {
+  ts: number;
+  lines?: string[];
+  error?: string;
+  exitCode?: number;
+};
+
+export class LogcatProcess extends EventEmitter {
+  private stopStream: (() => void) | null = null;
+  private runId: string | null = null;
+  private stopped = false;
+  private exited = false;
+  private readonly exitPromise: Promise<number>;
+  private settleExit!: (code: number) => void;
+
+  /** @internal */
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    args: string[],
+  ) {
+    super();
+    this.exitPromise = new Promise((resolve) => {
+      this.settleExit = resolve;
+    });
+    void this.start(args);
+  }
+
+  override on<E extends keyof LogcatProcessEvents>(event: E, listener: LogcatProcessEvents[E]): this {
+    return super.on(event, listener as any);
+  }
+
+  override once<E extends keyof LogcatProcessEvents>(event: E, listener: LogcatProcessEvents[E]): this {
+    return super.once(event, listener as any);
+  }
+
+  override off<E extends keyof LogcatProcessEvents>(event: E, listener: LogcatProcessEvents[E]): this {
+    return super.off(event, listener as any);
+  }
+
+  /** Resolves with logcat's exit code; -1 when stopped or the stream was lost. */
+  wait(): Promise<number> {
+    return this.exitPromise;
+  }
+
+  /** Stop the remote logcat process and close the stream. */
+  stop(): void {
+    if (this.stopped || this.exited) return;
+    this.stopped = true;
+    this.deleteRun(this.runId);
+    this.finish(-1);
+  }
+
+  private deleteRun(runId: string | null): void {
+    if (!runId) return;
+    // Fire and forget: the server's idle sweep reaps the run if this is lost.
+    void nodeProxyTransport
+      .fetch(`${this.apiUrl}/logcat/${runId}`, {
+        method: 'DELETE',
+        headers: { Authorization: `Bearer ${this.token}` },
+      })
+      .catch(() => {});
+  }
+
+  private finish(code: number): void {
+    if (this.exited) return;
+    this.exited = true;
+    this.stopStream?.();
+    this.stopStream = null;
+    this.settleExit(code);
+    this.emit('exit', code);
+  }
+
+  private fail(error: Error): void {
+    if (this.exited) return;
+    // The remote process must not outlive a lost stream; the idle sweep is
+    // only the fallback for when this delete is lost too.
+    this.deleteRun(this.runId);
+    this.emit('error', error);
+    this.finish(-1);
+  }
+
+  private async start(args: string[]): Promise<void> {
+    let id: string;
+    try {
+      const response = await nodeProxyTransport.fetch(`${this.apiUrl}/logcat`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ args }),
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`logcat failed to start: HTTP ${response.status}${text ? ` ${text.trim()}` : ''}`);
+      }
+      const data = (await response.json()) as { id?: string };
+      if (!data.id) {
+        throw new Error('logcat failed to start: server returned no run id');
+      }
+      id = data.id;
+    } catch (err) {
+      this.fail(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    if (this.stopped) {
+      // stop() raced the POST; kill the run it just created.
+      this.deleteRun(id);
+      return;
+    }
+    this.runId = id;
+    this.stopStream = streamSessionEntries<LogcatEntry>({
+      url: `${this.apiUrl}/logcat/${id}/events`,
+      token: this.token,
+      onEntry: (entry) => {
+        if (entry.lines && entry.lines.length > 0) {
+          this.emit('lines', entry.lines);
+          for (const line of entry.lines) {
+            this.emit('line', line);
+          }
+        }
+        if (entry.error) {
+          this.emit('error', new Error(entry.error));
+        }
+        if (typeof entry.exitCode === 'number') {
+          this.finish(entry.exitCode);
+        }
+      },
+      onError: (error) => this.fail(error),
+    });
+  }
+}

package/src/mise-tools.ts

@@ -0,0 +1,55 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { parse, stringify, type TomlTable } from 'smol-toml';
+
+export function parseToolRequests(requests: string[]): Record<string, string> {
+  const tools: Record<string, string> = {};
+  for (const request of requests) {
+    const at = request.lastIndexOf('@');
+    if (at <= 0 || !request.slice(at + 1).trim())
+      throw new Error(`Expected tool@version, received ${JSON.stringify(request)}.`);
+    const name = request.slice(0, at);
+    if (!/^[A-Za-z0-9][A-Za-z0-9:_./-]*$/.test(name))
+      throw new Error(`Invalid tool name ${JSON.stringify(name)}.`);
+    tools[name] = request.slice(at + 1);
+  }
+  return tools;
+}
+
+async function readConfig(file: string): Promise<TomlTable> {
+  try {
+    return parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw new Error(`Cannot read mise configuration ${file}: ${String(error)}`);
+  }
+}
+
+/** Save requested tool versions in the project configuration. */
+export async function writeMiseTools(directory: string, tools: Record<string, string>): Promise<string> {
+  let file = path.join(directory, 'mise.toml');
+  // Update the highest-precedence existing file in this directory.
+  for (const name of ['mise.toml', '.mise.toml', 'mise.local.toml', '.mise.local.toml']) {
+    const candidate = path.join(directory, name);
+    try {
+      await fs.access(candidate);
+      file = candidate;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+  const config = await readConfig(file);
+  const existing = config['tools'];
+  if (existing !== undefined && (!existing || typeof existing !== 'object' || Array.isArray(existing)))
+    throw new Error(`Expected [tools] in ${file}.`);
+  config['tools'] = { ...(existing as TomlTable | undefined), ...tools };
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(temporary, stringify(config), { mode: 0o600, flag: 'wx' });
+    await fs.rename(temporary, file);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+  return file;
+}

package/src/resources/android-instances.ts

@@ -197,6 +197,11 @@ export namespace AndroidInstanceCreateParams {
      */
     jurisdiction?: 'us' | 'eu' | 'as';
 
+    /**
+     * The Android device model. Default is phone.
+     */
+    model?: 'phone' | 'tablet';
+
     /**
      * Where the instance will be created. If not given, the region is decided based on
      * scheduling clues (client IP) and availability.