@limrun/api 0.41.0 → 0.42.0

package/src/index.ts

@@ -13,6 +13,10 @@ export { buildSettingKeyPattern, parseBuildSettingEntries, validateBuildSettings
 export {
   exec,
   type ExecRequest,
+  type XcodeBuildExecRequest,
+  type GradleAndroidABI,
+  type GradleBuildExecRequest,
+  type GradleReactNativeConfig,
   type ExecOptions,
   type ExecResult,
   type ExecChildProcess,
@@ -46,6 +50,12 @@ export {
   type SimulatorDeviceInfo,
   type SimulatorInstallState,
 } from './resources/xcode-instances-helpers';
+export {
+  type GradleCreateClientParams,
+  type GradleClient,
+  type GradleSyncOptions,
+  type GradleBuildOptions,
+} from './resources/gradle-instances-helpers';
 export {
   LIMRUN_DIR,
   TRY_IMPORT_LINE,

package/src/ios-client.ts

@@ -210,6 +210,20 @@ export type HttpProxyOptions = {
   localPort: number;
 };
 
+/**
+ * Targets a file operation at an installed app's container instead of the
+ * sandbox staging folder. Mirrors `simctl get_app_container` semantics.
+ */
+export type ContainerTargetOptions = {
+  /** Bundle ID of the installed app whose container should be targeted. */
+  bundleId: string;
+  /**
+   * Container to target: `app`, `data`, or a specific App Group identifier.
+   * Defaults to `app` server-side, matching `simctl get_app_container`.
+   */
+  containerType?: string;
+};
+
 /**
  * Result of auto-discovering a StoreKit configuration from the
  * simulator's cached sandbox response.
@@ -794,12 +808,45 @@ export type InstanceClient = {
   simctl: (args: string[], opts?: { disconnectOnExit?: boolean }) => SimctlExecution;
 
   /**
-   * Copy a file to the sandbox of the simulator. Returns the path of the file that can be used in simctl commands.
-   * @param name The name of the file in the sandbox of the simulator.
-   * @param path The path of the file to copy to the sandbox of the simulator.
-   * @returns A promise that resolves to the path of the file that can be used in simctl commands.
+   * Push a local file to the simulator. Returns the path of the file on the simulator host
+   * that can be used in simctl commands.
+   *
+   * When `opts.bundleId` is provided, `destination` is treated as a relative path inside
+   * that app's container on the simulator (intermediate directories are created
+   * as needed) instead of a filename in the sandbox staging folder.
+   *
+   * @param path The path of the local file to copy to the simulator.
+   * @param destination The name of the file in the sandbox of the simulator, or a relative path inside the app container when `opts.bundleId` is set.
+   * @param opts Optional app container targeting.
+   * @param opts.bundleId Bundle ID of the installed app whose container should receive the file.
+   * @param opts.containerType Container to target: `app`, `data`, or a specific App Group identifier. Defaults to `app` server-side, matching `simctl get_app_container`.
+   * @returns A promise that resolves to the path of the file on the simulator host.
    */
-  cp: (name: string, path: string) => Promise<string>;
+  pushFile: (path: string, destination: string, opts?: ContainerTargetOptions) => Promise<string>;
+
+  /**
+   * Read a file from the simulator and return its content.
+   *
+   * When `opts.bundleId` is provided, `name` is treated as a relative path inside
+   * that app's container; otherwise it addresses the sandbox staging folder
+   * (the same namespace `pushFile` uploads to without a bundle ID).
+   *
+   * @param name The name of the file, or a relative path inside the app container when `opts.bundleId` is set.
+   * @param opts Optional app container targeting (see `pushFile`).
+   * @returns A promise that resolves to the file content.
+   */
+  pullFile: (name: string, opts?: ContainerTargetOptions) => Promise<Buffer>;
+
+  /**
+   * Delete a file or folder (recursively) on the simulator.
+   *
+   * When `opts.bundleId` is provided, `name` is treated as a relative path inside
+   * that app's container; otherwise it addresses the sandbox staging folder.
+   *
+   * @param name The name of the file, or a relative path inside the app container when `opts.bundleId` is set.
+   * @param opts Optional app container targeting (see `pushFile`).
+   */
+  deleteFile: (name: string, opts?: ContainerTargetOptions) => Promise<void>;
 
   /**
    * Run `xcrun` command with the given arguments.
@@ -1821,7 +1868,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             xcrun,
             startXcrunShim,
             xcodebuild,
-            cp,
+            pushFile,
+            pullFile,
+            deleteFile,
             lsof,
             deviceInfo: cachedDeviceInfo,
           });
@@ -2245,9 +2294,24 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return execution;
     };
 
-    const cp = async (name: string, filePath: string): Promise<string> => {
+    const buildFilesUrl = (name: string, opts?: ContainerTargetOptions): string => {
+      const params = new URLSearchParams({ name });
+      if (opts?.bundleId) {
+        params.set('bundleId', opts.bundleId);
+        if (opts.containerType) {
+          params.set('containerType', opts.containerType);
+        }
+      }
+      return `${options.apiUrl}/files?${params.toString()}`;
+    };
+
+    const pushFile = async (
+      filePath: string,
+      destination: string,
+      opts?: ContainerTargetOptions,
+    ): Promise<string> => {
       const fileStream = fs.createReadStream(filePath);
-      const uploadUrl = `${options.apiUrl}/files?name=${encodeURIComponent(name)}`;
+      const uploadUrl = buildFilesUrl(destination, opts);
       try {
         // 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.
@@ -2274,6 +2338,33 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       }
     };
 
+    const pullFile = async (name: string, opts?: ContainerTargetOptions): Promise<Buffer> => {
+      const response = await nodeProxyTransport.fetch(buildFilesUrl(name, opts), {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${options.token}`,
+        },
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(`Download of '${name}' failed: ${response.status} ${errorBody}`);
+      }
+      return Buffer.from(await response.arrayBuffer());
+    };
+
+    const deleteFile = async (name: string, opts?: ContainerTargetOptions): Promise<void> => {
+      const response = await nodeProxyTransport.fetch(buildFilesUrl(name, opts), {
+        method: 'DELETE',
+        headers: {
+          Authorization: `Bearer ${options.token}`,
+        },
+      });
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(`Deletion of '${name}' failed: ${response.status} ${errorBody}`);
+      }
+    };
+
     const setStoreKitConfig = async (bundleId: string, storekit: Buffer | Uint8Array): Promise<void> => {
       const body = Buffer.isBuffer(storekit) ? storekit : Buffer.from(storekit);
       const url = `${options.apiUrl}/payments/storeKitConfigs/${encodeURIComponent(bundleId)}`;

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

@@ -0,0 +1,71 @@
+// Helpers and platform-neutral types shared by the per-instance build-daemon
+// clients (xcode, gradle).
+
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+
+/**
+ * Derives the client-side folder-sync cache location for a local project.
+ * The key format is a compatibility contract: changing it orphans every
+ * user's existing basis cache, so both daemon clients must share this one
+ * derivation.
+ */
+export function deriveBasisCache(
+  localCodePath: string,
+  override?: string,
+): { cacheKey: string; basisCacheDir: string } {
+  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}`;
+  return { cacheKey, basisCacheDir: override ?? path.join(os.tmpdir(), cacheKey) };
+}
+
+export type SyncResult = {
+  /**
+   * Number of bytes transmitted to the server for this sync (full uploads plus
+   * delta patches, before transport compression). In watch mode, this reflects
+   * the initial sync only.
+   */
+  bytesSent?: number;
+  /** Present only when watch=true; call to stop watching */
+  stopWatching?: () => Promise<void>;
+};
+
+export type AssetUploadUrls = { signedUploadUrl: string; signedDownloadUrl: string };
+
+/**
+ * Mints presigned upload/download URLs for a named asset via assets.getOrCreate,
+ * wrapping failures with the asset name (and the original error as cause).
+ */
+export function mintAssetUploadUrls(
+  assets: { getOrCreate: (body: { name: string; ttl?: string }) => Promise<AssetUploadUrls> },
+  name: string,
+  ttl?: string,
+): Promise<AssetUploadUrls> {
+  return assets.getOrCreate({ name, ...(ttl && { ttl }) }).catch((err) => {
+    const message = `Failed to create upload URL for asset '${name}': ${
+      err instanceof Error ? err.message : err
+    }`;
+    // @ts-ignore - not all envs have native support for cause yet
+    throw new Error(message, { cause: err });
+  });
+}
+
+const logLevels: LogLevel[] = ['none', 'error', 'warn', 'info', 'debug'];
+
+export function createDaemonLogger(prefix: string, logLevel: LogLevel) {
+  const threshold = logLevels.indexOf(logLevel);
+  const shouldLog = (level: LogLevel) => threshold >= logLevels.indexOf(level);
+  return (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => {
+    if (!shouldLog(level)) return;
+    if (level === 'error' || level === 'warn') {
+      console[level](prefix, msg);
+    } else {
+      console.log(prefix, msg);
+    }
+  };
+}

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

@@ -0,0 +1,155 @@
+import { GradleInstances as GeneratedGradleInstances, type GradleInstance } from './gradle-instances';
+import {
+  exec,
+  type ExecChildProcess,
+  type GradleBuildExecRequest,
+  type GradleReactNativeConfig,
+} from '../exec-client';
+import { syncFolder as syncFolderImpl, type FolderSyncOptions } from '../folder-sync';
+import { createIgnoreFn } from '../folder-sync-ignore';
+import {
+  createDaemonLogger,
+  deriveBasisCache,
+  mintAssetUploadUrls,
+  type LogLevel,
+  type SyncResult,
+} from './daemon-client-shared';
+
+export type GradleCreateClientParams = { logLevel?: LogLevel } & (
+  | { instance: GradleInstance }
+  | { apiUrl: string; token: string }
+);
+
+export type GradleSyncOptions = {
+  /**
+   * Directory for the client-side folder-sync cache.
+   * Defaults to a temporary directory under the OS temp directory.
+   */
+  basisCacheDir?: string;
+  /**
+   * Optional predicate for ignoring files and directories during sync.
+   * Called with the relative path from the sync root (using forward slashes).
+   * For directories, the path ends with '/'.
+   * Return true to ignore, false to keep.
+   */
+  ignore?: (relativePath: string) => boolean;
+  /**
+   * Optional predicate for force-including paths that would otherwise be
+   * dropped. Same calling convention as `ignore`; return true to force-sync.
+   */
+  include?: (relativePath: string) => boolean;
+};
+
+export type GradleBuildOptions = {
+  /** Gradle tasks to run. Omit for the server default (assembleDebug). */
+  tasks?: string[];
+  /** Relative path to the Gradle root when auto-discovery is ambiguous. */
+  projectPath?: string;
+  /** Upload the built APK as a named org asset, or to a presigned URL. */
+  upload?: { assetName: string; signedUploadUrl?: never } | { signedUploadUrl: string; assetName?: never };
+  /** React Native / Expo tuning. */
+  reactNative?: GradleReactNativeConfig;
+};
+
+export type GradleClient = {
+  sync(localCodePath: string, opts?: GradleSyncOptions): Promise<SyncResult>;
+  gradlebuild(options?: GradleBuildOptions): ExecChildProcess;
+};
+
+// Machine-local or regenerable files that must never reach the build
+// sandbox: local.properties points at the developer's own SDK and would
+// shadow the image's. Only ROOT-level cache/output dirs are defaulted;
+// nested module build/ dirs are the project .gitignore's job (dropping any
+// 'build' segment would silently exclude legitimate packages named build).
+function gradleDefaultIgnore(relativePath: string): boolean {
+  const trimmed = relativePath.endsWith('/') ? relativePath.slice(0, -1) : relativePath;
+  const segments = trimmed.split('/');
+  if (segments[segments.length - 1] === 'local.properties') {
+    return true;
+  }
+  return segments.length === 1 && (trimmed === '.gradle' || trimmed === '.kotlin' || trimmed === 'build');
+}
+
+export class GradleInstances extends GeneratedGradleInstances {
+  async createClient(params: GradleCreateClientParams): Promise<GradleClient> {
+    let apiUrl: string;
+    let token: string;
+    if ('instance' in params) {
+      if (!params.instance.status.apiUrl) {
+        throw new Error('Instance not ready: apiUrl is not available');
+      }
+      apiUrl = params.instance.status.apiUrl;
+      token = params.instance.status.token;
+    } else {
+      apiUrl = params.apiUrl;
+      token = params.token;
+    }
+
+    const log = createDaemonLogger('[GradleInstance]', params.logLevel ?? 'info');
+    const client = this._client;
+
+    return {
+      async sync(localCodePath: string, opts?: GradleSyncOptions): Promise<SyncResult> {
+        const { cacheKey, basisCacheDir } = deriveBasisCache(localCodePath, opts?.basisCacheDir);
+        const userIgnore = opts?.ignore;
+        const codeSyncOpts: FolderSyncOptions = {
+          apiUrl,
+          token,
+          udid: cacheKey,
+          install: false,
+          ignoreFn: await createIgnoreFn(localCodePath, {
+            basisCacheDir,
+            log,
+            xcodeDefaults: false,
+            // Honor nested module .gitignore files (app/.gitignore's /build,
+            // etc.); gradleDefaultIgnore only covers root-level build/.gradle/
+            // .kotlin, so without this a locally-built project would sync its
+            // nested build/ artifact trees.
+            nestedGitignore: true,
+            additional: userIgnore ? (p) => gradleDefaultIgnore(p) || userIgnore(p) : gradleDefaultIgnore,
+            ...(opts?.include ? { include: opts.include } : {}),
+          }),
+          basisCacheDir,
+          // Gradle builds are one-shot; no dev-loop watch like xcode.
+          watch: false,
+          launchMode: 'ForegroundIfRunning',
+          log,
+          syncSymlinks: true,
+        };
+
+        const result = await syncFolderImpl(localCodePath, codeSyncOpts);
+        const out: SyncResult = {};
+        if (result.bytesSent !== undefined) {
+          out.bytesSent = result.bytesSent;
+        }
+        return out;
+      },
+
+      gradlebuild(options?: GradleBuildOptions): ExecChildProcess {
+        const request: GradleBuildExecRequest = {
+          command: 'gradlebuild',
+          ...(options?.tasks?.length && { tasks: options.tasks }),
+          ...(options?.projectPath && { projectPath: options.projectPath }),
+          ...(options?.reactNative && { reactNative: options.reactNative }),
+        };
+
+        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;
+            },
+          );
+          return exec(requestPromise, { apiUrl, token, log });
+        }
+
+        if (options?.upload && 'signedUploadUrl' in options.upload) {
+          request.signedUploadUrl = options.upload.signedUploadUrl;
+        }
+
+        return exec(request, { apiUrl, token, log });
+      },
+    };
+  }
+}

package/src/resources/gradle-instances.ts

@@ -0,0 +1,206 @@
+// Hand-written following the Stainless resource pattern; a future generation
+// from the OpenAPI spec reconciles with this file.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { Items, type ItemsParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class GradleInstances extends APIResource {
+  /**
+   * Create a gradle instance
+   */
+  create(params: GradleInstanceCreateParams, options?: RequestOptions): APIPromise<GradleInstance> {
+    const { reuseIfExists, wait, ...body } = params;
+    return this._client.post('/v1/gradle_instances', { query: { reuseIfExists, wait }, body, ...options });
+  }
+
+  /**
+   * List gradle instances
+   */
+  list(
+    query: GradleInstanceListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<GradleInstancesItems, GradleInstance> {
+    return this._client.getAPIList('/v1/gradle_instances', Items<GradleInstance>, { query, ...options });
+  }
+
+  /**
+   * Delete gradle instance with given name
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/gradle_instances/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Get gradle instance with given ID
+   */
+  get(id: string, options?: RequestOptions): APIPromise<GradleInstance> {
+    return this._client.get(path`/v1/gradle_instances/${id}`, options);
+  }
+}
+
+export type GradleInstancesItems = Items<GradleInstance>;
+
+export interface GradleInstance {
+  metadata: GradleInstance.Metadata;
+
+  spec: GradleInstance.Spec;
+
+  status: GradleInstance.Status;
+}
+
+export namespace GradleInstance {
+  export interface Metadata {
+    id: string;
+
+    createdAt: string;
+
+    organizationId: string;
+
+    displayName?: string;
+
+    labels?: { [key: string]: string };
+
+    terminatedAt?: string;
+  }
+
+  export interface Spec {
+    inactivityTimeout: string;
+
+    region: string;
+
+    hardTimeout?: string;
+  }
+
+  export interface Status {
+    token: string;
+
+    state: 'unknown' | 'creating' | 'assigned' | 'ready' | 'terminated';
+
+    apiUrl?: string;
+
+    errorMessage?: string;
+
+    /**
+     * Machine-readable reason the instance was terminated. Always present once state
+     * is "terminated", never present before that. New values may be added over time,
+     * so treat any unrecognized value as "Unknown". Known values:
+     *
+     * - "UserRequested": terminated by a delete request to the API.
+     * - "InactivityTimeout": the timeout given in spec.inactivityTimeout elapsed.
+     * - "HardTimeout": the timeout given in spec.hardTimeout elapsed.
+     * - "Unknown": terminated for a cause the platform did not attribute, including
+     *   instances that failed to get ready during creation. See errorMessage for
+     *   details when available.
+     */
+    terminationReason?: string;
+  }
+}
+
+export interface GradleInstanceCreateParams {
+  /**
+   * Query param: If there is another instance with given labels and region, return
+   * that one instead of creating a new instance.
+   */
+  reuseIfExists?: boolean;
+
+  /**
+   * Query param: Return after the instance is ready to connect.
+   */
+  wait?: boolean;
+
+  /**
+   * Body param
+   */
+  metadata?: GradleInstanceCreateParams.Metadata;
+
+  /**
+   * Body param
+   */
+  spec?: GradleInstanceCreateParams.Spec;
+}
+
+export namespace GradleInstanceCreateParams {
+  export interface Metadata {
+    displayName?: string;
+
+    labels?: { [key: string]: string };
+  }
+
+  export interface Spec {
+    clues?: Array<Spec.Clue>;
+
+    /**
+     * After how many minutes should the instance be terminated. Example values 1m,
+     * 10m, 3h. Default is "0" which means no hard timeout.
+     */
+    hardTimeout?: string;
+
+    /**
+     * After how many minutes of inactivity should the instance be terminated. Example
+     * values 1m, 10m, 3h. Default is 5m.
+     */
+    inactivityTimeout?: string;
+
+    /**
+     * Where the instance will be created. If not given, the region is decided based on
+     * scheduling clues (client IP) and availability.
+     *
+     * A region is a preference, not a hard pin: the request always overflows to every
+     * other available region, ordered by proximity, when the preferred ones are full.
+     *
+     * Accepted values:
+     *
+     * - A specific region name (e.g. "us-west1"). It is tried first, then the
+     *   remaining regions in order of proximity to it. Scheduling clues (client IP)
+     *   are ignored when a region is given.
+     * - A region group name (e.g. "us", "eu"). Its member regions are tried first in
+     *   their listed order, then the remaining regions by proximity to the first
+     *   member.
+     * - A pipe-separated, ordered list of regions (e.g. "us-east1|us-west1"). Those
+     *   are tried first in the given order, then the remaining regions by proximity to
+     *   the first.
+     */
+    region?: string;
+  }
+
+  export namespace Spec {
+    export interface Clue {
+      kind: 'ClientIP';
+
+      clientIp?: string;
+    }
+  }
+}
+
+export interface GradleInstanceListParams extends ItemsParams {
+  /**
+   * Labels filter to apply to instances to return. Expects a comma-separated list of
+   * key=value pairs (e.g., env=prod,region=us-west).
+   */
+  labelSelector?: string;
+
+  /**
+   * State filter to apply to gradle instances to return. Each comma-separated state
+   * will be used as part of an OR clause, e.g. "assigned,ready" will return all
+   * instances that are either assigned or ready.
+   *
+   * Valid states: creating, assigned, ready, terminated, unknown
+   */
+  state?: string;
+}
+
+export declare namespace GradleInstances {
+  export {
+    type GradleInstance as GradleInstance,
+    type GradleInstancesItems as GradleInstancesItems,
+    type GradleInstanceCreateParams as GradleInstanceCreateParams,
+    type GradleInstanceListParams as GradleInstanceListParams,
+  };
+}

package/src/resources/index.ts

@@ -37,6 +37,12 @@ export {
   type XcodeInstanceListParams,
   type XcodeInstancesItems,
 } from './xcode-instances';
+export {
+  type GradleInstance,
+  type GradleInstanceCreateParams,
+  type GradleInstanceListParams,
+  type GradleInstancesItems,
+} from './gradle-instances';
 
 export { Assets, AssetGetOrUploadParams, AssetGetOrUploadResponse } from './assets-helpers';
 export {
@@ -57,3 +63,10 @@ export {
   type SimulatorInstallState,
   type RbeInstallResult,
 } from './xcode-instances-helpers';
+export {
+  GradleInstances,
+  type GradleCreateClientParams,
+  type GradleClient,
+  type GradleSyncOptions,
+  type GradleBuildOptions,
+} from './gradle-instances-helpers';