@limrun/api 0.46.14 → 0.47.1

package/src/instance-client.ts

@@ -152,9 +152,76 @@ export type InstanceClient = {
   /**
    * 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.
+   * The file must already exist on the Android instance, for example after
+   * uploading it with {@link pushFile} or pushing it with ADB.
    */
   playOnMicrophone: (path: string, options?: PlayOnMicrophoneOptions) => Promise<PlayOnMicrophoneResult>;
+  /**
+   * Upload a local file to the instance, without needing an ADB connection.
+   *
+   * With no destination, the instance stores the file under an internal name
+   * and returns its path. With a destination, behaves like `adb push`: the
+   * write is performed with the same permissions the ADB shell user has, so
+   * writable locations (e.g. `/data/local/tmp`, `/sdcard`) succeed and
+   * protected ones are rejected, exactly as they would be for `adb push`.
+   *
+   * @param path The path of the local file to upload.
+   * @param destination Optional absolute path on the instance to write to.
+   * @returns A promise that resolves to the absolute path of the file on the
+   *   instance, usable with {@link playOnMicrophone}.
+   */
+  pushFile: (path: string, destination?: string) => Promise<string>;
+  /**
+   * Play a local video file as the camera feed.
+   *
+   * Uploads the file to the instance and switches the virtual camera source
+   * to it, replacing the live WebRTC camera until {@link clearCameraVideo} is
+   * called. Apps see the video through their regular Camera2/CameraX
+   * pipeline, and the file's audio track (if any) plays through the
+   * microphone in sync.
+   *
+   * By default the video loops; with `loop: false` it plays once and the
+   * feed freezes on the last frame.
+   *
+   * @param path The path of the local video file to play as the camera.
+   * @param opts Playback options (currently just `loop`).
+   * @throws If the file has no decodable video track or the instance does not
+   *   support camera injection (Android 14 and older).
+   */
+  setCameraVideo: (path: string, opts?: CameraVideoOptions) => Promise<void>;
+  /**
+   * Stop video-file camera playback and restore the default WebRTC camera
+   * source. Safe to call when no video is playing.
+   */
+  clearCameraVideo: () => Promise<void>;
+  /**
+   * Run a shell command on the instance, without needing `adb` installed
+   * locally. The command runs with the same permissions the ADB shell user
+   * has (exactly like `adb shell`), and its stdout, stderr, and exit code are
+   * returned separately.
+   *
+   * The command and each argument are safely quoted before being sent, so
+   * argument values cannot be interpreted as extra shell syntax (no injection
+   * from untrusted args), mirroring `child_process.execFile`:
+   *
+   * ```ts
+   * await client.adbShell('pm', ['list', 'packages', '-3']);
+   * await client.adbShell('getprop', ['ro.build.version.sdk']);
+   * ```
+   *
+   * To use shell features such as pipes or redirection, invoke a shell
+   * explicitly and pass the script as an argument:
+   *
+   * ```ts
+   * await client.adbShell('sh', ['-c', 'dumpsys battery | grep level']);
+   * ```
+   *
+   * @param command The executable or shell builtin to run.
+   * @param args Arguments passed to the command; each is individually quoted.
+   * @throws If the command times out or the ADB transport is unavailable. A
+   *   non-zero `exitCode` is returned in the result, not thrown.
+   */
+  adbShell: (command: string, args?: string[], options?: AdbShellOptions) => Promise<AdbShellResult>;
   /**
    * Set Android Wi-Fi bandwidth limits in Kbps. Omit a direction to leave it unchanged;
    * pass `0` to clear that direction's limit.
@@ -443,6 +510,18 @@ export type PlayOnMicrophoneOptions = {
   once?: boolean;
 };
 
+/**
+ * Options for playing a video file as the virtual camera feed.
+ */
+export type CameraVideoOptions = {
+  /**
+   * Whether to restart the video when it ends. When false the video
+   * plays once and the camera feed freezes on its last frame.
+   * @default true
+   */
+  loop?: boolean;
+};
+
 export type PlayOnMicrophoneResult = {
   /** Duration of the decoded audio in microseconds. */
   duration: number;
@@ -455,6 +534,46 @@ export type WifiBandwidthOptions = {
   upKbps?: number;
 };
 
+/**
+ * Quotes each token so the remote `sh -c` receives them as literal,
+ * separate arguments — values cannot inject extra shell syntax. Uses
+ * POSIX single-quoting: wrap in single quotes and escape embedded single
+ * quotes as `'\''`.
+ */
+function quoteShellArgs(tokens: string[]): string {
+  return tokens.map((token) => `'${token.replace(/'/g, `'\\''`)}'`).join(' ');
+}
+
+/**
+ * Options for {@link InstanceClient.adbShell}.
+ */
+export type AdbShellOptions = {
+  /**
+   * Maximum time to wait for the command to finish, in milliseconds.
+   * @default 30000
+   */
+  timeoutMs?: number;
+  /**
+   * Encoding used to decode stdout/stderr into strings.
+   * @default 'utf8'
+   */
+  encoding?: BufferEncoding;
+};
+
+/**
+ * Result of a shell command run via {@link InstanceClient.adbShell}.
+ */
+export type AdbShellResult = {
+  /** Standard output, decoded with the requested encoding. */
+  stdout: string;
+  /** Standard error, decoded with the requested encoding. */
+  stderr: string;
+  /** Process exit code (`-1` if the device reported no exit status). */
+  exitCode: number;
+  /** True if output exceeded the capture limit and was truncated. */
+  truncated: boolean;
+};
+
 type EmptyCommandResult = Record<string, never>;
 
 type ScreenshotErrorResponse = {
@@ -589,6 +708,15 @@ type PlayOnMicrophoneResultMessage = {
   error?: CommandError;
 };
 
+// The server sends camera control results "flat": fields at the top level and
+// `error` as a plain string, with no payload envelope.
+type CameraControlResultMessage = {
+  type: 'cameraControlResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: string;
+};
+
 type SetWifiBandwidthResultMessage = {
   type: 'setWifiBandwidthResult';
   id: string;
@@ -596,6 +724,19 @@ type SetWifiBandwidthResultMessage = {
   error?: CommandError;
 };
 
+// The server sends adb shell results "flat": stdout/stderr (base64) and
+// exitCode at the top level, with `error` as a plain string.
+type AdbShellResultMessage = {
+  type: 'adbShellResult';
+  id: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+  truncated?: boolean;
+  payload?: EmptyCommandResult;
+  error?: string;
+};
+
 type StartVideoRecordingResultMessage = {
   type: 'startRecordingResult';
   id: string;
@@ -625,6 +766,8 @@ type KnownCommandResultMessage =
   | WatchAppResultMessage
   | UnwatchAppResultMessage
   | PlayOnMicrophoneResultMessage
+  | CameraControlResultMessage
+  | AdbShellResultMessage
   | SetWifiBandwidthResultMessage
   | StartVideoRecordingResultMessage
   | StopVideoRecordingResultMessage;
@@ -651,6 +794,8 @@ type CommandRequestMap = {
   watchApp: { packageName: string; execId: string };
   unwatchApp: { execId: string };
   playOnMicrophone: { path: string; once?: boolean };
+  cameraControl: { action: 'setSource'; source: 'video'; arg: string; loop?: boolean } | { action: 'reset' };
+  adbShell: { command: string; timeoutMs?: number };
   setWifiBandwidth: WifiBandwidthOptions;
   startRecording: { quality?: RecordingQuality };
   stopRecording: { upload?: { presignedUrl: string } };
@@ -671,6 +816,8 @@ type CommandResultMap = {
   watchApp: { packageName?: string };
   unwatchApp: EmptyCommandResult;
   playOnMicrophone: PlayOnMicrophoneResult;
+  cameraControl: EmptyCommandResult;
+  adbShell: AdbShellResultMessage;
   setWifiBandwidth: EmptyCommandResult;
   startRecording: EmptyCommandResult;
   stopRecording: EmptyCommandResult;
@@ -812,6 +959,11 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       if ('message' in message && typeof message.message === 'string') {
         return message.message;
       }
+      // "Flat" results (e.g. cameraControlResult, playOnMicrophoneResult)
+      // carry the error as a plain string instead of a CommandError object.
+      if ('error' in message && typeof message.error === 'string' && message.error) {
+        return message.error;
+      }
       if ('error' in message && message.error && typeof message.error === 'object') {
         const obj = message.error as CommandError;
         if (typeof obj.message === 'string' && obj.message) {
@@ -845,6 +997,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         case 'watchAppResult':
         case 'unwatchAppResult':
         case 'playOnMicrophoneResult':
+        case 'cameraControlResult':
+        case 'adbShellResult':
         case 'setWifiBandwidthResult':
         case 'startRecordingResult':
         case 'stopRecordingResult':
@@ -1116,6 +1270,10 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             terminateApp,
             watchApp,
             playOnMicrophone,
+            pushFile,
+            setCameraVideo,
+            clearCameraVideo,
+            adbShell,
             setWifiBandwidth,
             startRecording,
             stopRecording,
@@ -1279,6 +1437,74 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       });
     };
 
+    const pushFile = async (filePath: string, destination?: string): Promise<string> => {
+      const uploadUrl =
+        destination === undefined ?
+          `${options.apiUrl}/files`
+        : `${options.apiUrl}/files?path=${encodeURIComponent(destination)}`;
+      const fileStream = fs.createReadStream(filePath);
+      // Node's fetch (undici) supports streaming request bodies but TS DOM types may not include
+      // `duplex` and may not accept Node ReadStreams as BodyInit in some configs.
+      const response = await nodeProxyTransport.fetch(uploadUrl, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': fs.statSync(filePath).size.toString(),
+          Authorization: `Bearer ${options.token}`,
+        },
+        body: fileStream as any,
+        duplex: 'half' as any,
+      } as any);
+      if (!response.ok) {
+        const errorBody = await response.text();
+        logger.debug(`Upload failed: ${response.status} ${errorBody}`);
+        throw new Error(`Upload failed: ${response.status} ${errorBody}`);
+      }
+      const result = (await response.json()) as { path: string };
+      return result.path;
+    };
+
+    const setCameraVideo = async (filePath: string, cameraOptions?: CameraVideoOptions): Promise<void> => {
+      const remotePath = await pushFile(filePath);
+      await sendRequest('cameraControl', {
+        action: 'setSource',
+        source: 'video',
+        arg: remotePath,
+        loop: cameraOptions?.loop ?? true,
+      });
+    };
+
+    const clearCameraVideo = async (): Promise<void> => {
+      await sendRequest('cameraControl', { action: 'reset' });
+    };
+
+    const adbShell = async (
+      command: string,
+      args: string[] = [],
+      adbOptions?: AdbShellOptions,
+    ): Promise<AdbShellResult> => {
+      if (!command) {
+        throw new Error('command must be a non-empty string');
+      }
+      const commandLine = quoteShellArgs([command, ...args]);
+      const timeoutMs = adbOptions?.timeoutMs;
+      // Wait a little longer than the device-side timeout so the server's own
+      // error surfaces instead of a generic client timeout.
+      const requestTimeoutMs = (timeoutMs ?? 30000) + 15000;
+      const result = await sendRequest(
+        'adbShell',
+        { command: commandLine, ...(timeoutMs === undefined ? {} : { timeoutMs }) },
+        requestTimeoutMs,
+      );
+      const encoding = adbOptions?.encoding ?? 'utf8';
+      return {
+        stdout: Buffer.from(result.stdout ?? '', 'base64').toString(encoding),
+        stderr: Buffer.from(result.stderr ?? '', 'base64').toString(encoding),
+        exitCode: typeof result.exitCode === 'number' ? result.exitCode : -1,
+        truncated: result.truncated === true,
+      };
+    };
+
     const setWifiBandwidth = async (bandwidthOptions: WifiBandwidthOptions): Promise<void> => {
       const request: CommandRequestMap['setWifiBandwidth'] = {};
       if (bandwidthOptions.downKbps !== undefined) {

package/src/resources/daemon-client-shared.ts

@@ -88,9 +88,19 @@ export type AssetUploadOptions = {
   deeplink?: string;
 };
 
+/**
+ * Default TTL for build-product uploads. Every build upload without an
+ * explicit ttl pushes the asset's expiry to 14 days from that upload, so
+ * abandoned build artifacts don't accumulate in Asset Storage forever.
+ * Assets uploaded through the general asset API keep no expiry by default.
+ */
+export const DEFAULT_BUILD_ASSET_TTL = '336h';
+
 /**
  * Mints presigned upload/download URLs for a named asset via assets.getOrCreate,
  * wrapping failures with the asset name (and the original error as cause).
+ * All build-product upload paths (xcodebuild, gradlebuild, RBE) go through
+ * here, which is what scopes DEFAULT_BUILD_ASSET_TTL to build uploads.
  */
 export function mintAssetUploadUrls(
   assets: {
@@ -100,7 +110,7 @@ export function mintAssetUploadUrls(
   ttl?: string,
   uploadOptions?: AssetUploadOptions,
 ): Promise<AssetUploadUrls> {
-  return assets.getOrCreate({ name, ...(ttl && { ttl }), ...uploadOptions }).catch((err) => {
+  return assets.getOrCreate({ name, ttl: ttl || DEFAULT_BUILD_ASSET_TTL, ...uploadOptions }).catch((err) => {
     const message = `Failed to create upload URL for asset '${name}': ${
       err instanceof Error ? err.message : err
     }`;

package/src/resources/gradle-instances-helpers.ts

@@ -56,7 +56,19 @@ export type GradleBuildOptions = {
   /** Relative path to the Gradle root when auto-discovery is ambiguous. */
   projectPath?: string;
   /** Upload the built artifact as a named org asset, or to a presigned URL. */
-  upload?: { assetName: string; signedUploadUrl?: never } | { signedUploadUrl: string; assetName?: never };
+  upload?:
+    | {
+        assetName: string;
+        /**
+         * Asset TTL as a Go duration (e.g. "24h", "30m"; "1d" is invalid),
+         * forwarded to assets.getOrCreate. Defaults to 336h (14 days): each
+         * build upload without an explicit ttl pushes the asset's expiry to
+         * 14 days from that upload.
+         */
+        ttl?: string;
+        signedUploadUrl?: never;
+      }
+    | { signedUploadUrl: string; assetName?: never; ttl?: never };
   /** React Native / Expo tuning. */
   reactNative?: GradleReactNativeConfig;
   /** Release signing config; presence makes bundleRelease the default task. */
@@ -183,13 +195,15 @@ class GradleInstancesHelpers extends GradleInstances {
         };
 
         if (options?.upload && 'assetName' in options.upload) {
-          const requestPromise = mintAssetUploadUrls(client.assets, options.upload.assetName).then(
-            (asset) => {
-              request.signedUploadUrl = asset.signedUploadUrl;
-              request.additionalMetadata = { signedDownloadUrl: asset.signedDownloadUrl };
-              return request;
-            },
-          );
+          const requestPromise = mintAssetUploadUrls(
+            client.assets,
+            options.upload.assetName,
+            options.upload.ttl,
+          ).then((asset) => {
+            request.signedUploadUrl = asset.signedUploadUrl;
+            request.additionalMetadata = { signedDownloadUrl: asset.signedDownloadUrl };
+            return request;
+          });
           return exec(requestPromise, { apiUrl, token, log });
         }
 

package/src/resources/xcode-instances-helpers.ts

@@ -90,8 +90,12 @@ export type SyncOptions = {
 export type XcodeRunOptions = {
   /** Working directory relative to the synced workspace root. Defaults to ".". */
   cwd?: string;
-  /** Environment variables to add to limbuild's curated sandbox environment. */
-  env?: Record<string, string>;
+  /**
+   * Ordered KEY=VALUE entries added to limbuild's curated sandbox
+   * environment. Server-managed variables (PATH, HOME, ...) cannot be
+   * overridden; when a key repeats, the last entry wins.
+   */
+  env?: string[];
   /** Server-side timeout in seconds. Defaults to 3600; maximum 21600. */
   timeoutSeconds?: number;
 };
@@ -105,6 +109,14 @@ export type XcodeProjectConfig = {
    * Debug for native Xcode builds and Release for React Native / Expo builds.
    */
   configuration?: 'Debug' | 'Release';
+  /**
+   * Full filename of the built app bundle, including the .app extension
+   * (e.g. "MyApp-dev.app"). When set, limbuild takes the artifact from
+   * this name in the built products directory verbatim, skipping artifact
+   * discovery. Use when the scheme name differs from the product name and
+   * discovery picks the wrong bundle.
+   */
+  artifactName?: string;
 };
 
 export type XcodeGenConfig = {
@@ -173,12 +185,28 @@ export type ReactNativeBuildConfig = {
    * server URL you want opened.
    */
   devServerURL?: string;
+  /**
+   * Run `expo prebuild` even when the synced workspace already contains the
+   * native ios/ tree, regenerating it in place. Use when the tree holds
+   * client-synced files the server treats as user-owned (for example
+   * committed Podfile customizations) while the Xcode project itself is
+   * generated and gitignored. Requires a detectable Expo project. Older
+   * limbuild servers silently ignore this option.
+   */
+  expoForcePrebuild?: boolean;
 };
 
 export type XcodeBuildOptions = {
   upload?:
     | {
         assetName: string;
+        /**
+         * Asset TTL as a Go duration (e.g. "24h", "30m"; "1d" is invalid),
+         * forwarded to assets.getOrCreate. Defaults to 336h (14 days): each
+         * build upload without an explicit ttl pushes the asset's expiry to
+         * 14 days from that upload.
+         */
+        ttl?: string;
         /**
          * App metadata to record on the asset up front. limbuild extracts
          * the same metadata from the built bundle after the build and
@@ -207,6 +235,16 @@ export type XcodeBuildOptions = {
    */
   xcodegen?: XcodeGenConfig;
   buildSettings?: Record<string, string>;
+  /**
+   * Ordered KEY=VALUE entries added to the environment of every build
+   * pipeline command (dependency installs, expo prebuild, pod install,
+   * xcodebuild and its script phases). Server-managed variables (PATH,
+   * HOME, ...) cannot be overridden; when a key repeats, the last entry
+   * wins. Dependency installs always include devDependencies, so
+   * NODE_ENV=production cannot break them. Older limbuild servers
+   * silently ignore this option.
+   */
+  env?: string[];
   /**
    * Run `git init` in the synced workspace before project generation,
    * dependency resolution, and xcodebuild.
@@ -323,7 +361,12 @@ export type RbeUploadOptions =
   | {
       /** Upload as a named asset: the SDK mints the presigned upload URL via assets.getOrCreate. */
       assetName: string;
-      /** Optional asset TTL as a Go duration (e.g. "24h", "30m"; "1d" is invalid), forwarded to assets.getOrCreate. */
+      /**
+       * Optional asset TTL as a Go duration (e.g. "24h", "30m"; "1d" is
+       * invalid), forwarded to assets.getOrCreate. Defaults to 336h (14
+       * days): each upload without an explicit ttl pushes the asset's
+       * expiry to 14 days from that upload.
+       */
       ttl?: string;
       signedUploadUrl?: never;
     }
@@ -813,6 +856,7 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           // testflight until the exec API is revised separately.
           ...(options?.appstore && { testflight: options.appstore }),
           ...(options?.buildSettings && { buildSettings: options.buildSettings }),
+          ...(options?.env?.length && { env: options.env }),
           ...(options?.gitInit !== undefined && { gitInit: options.gitInit }),
           ...(options?.webhook && { webhook: options.webhook }),
         };
@@ -821,7 +865,7 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           const requestPromise = mintAssetUploadUrls(
             client.assets,
             options.upload.assetName,
-            undefined,
+            options.upload.ttl,
             options.upload.uploadOptions,
           ).then((asset) => {
             request.signedUploadUrl = asset.signedUploadUrl;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.46.14'; // x-release-please-version
+export const VERSION = '0.47.1'; // x-release-please-version

package/version.d.mts

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

package/version.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,YAAY,CAAC"}
+{"version":3,"file":"version.d.mts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/version.d.ts

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

package/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,YAAY,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/version.js

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

package/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,SAAS,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}

package/version.mjs

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

package/version.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,2BAA2B"}
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,2BAA2B"}