computesdk 1.13.0 → 1.16.0

package/dist/index.mjs

@@ -1335,10 +1335,15 @@ var Server = class {
     this.stopHandler = handlers.stop;
     this.restartHandler = handlers.restart;
     this.updateStatusHandler = handlers.updateStatus;
+    this.logsHandler = handlers.logs;
   }
   /**
    * Start a new managed server with optional supervisor settings
    *
+   * **Install Phase:**
+   * If `install` is provided, it runs blocking before `start` (e.g., "npm install").
+   * The server status will be `installing` during this phase.
+   *
    * **Restart Policies:**
    * - `never` (default): No automatic restart on exit
    * - `on-failure`: Restart only on non-zero exit code
@@ -1356,14 +1361,15 @@ var Server = class {
    * // Basic server
    * const server = await sandbox.server.start({
    *   slug: 'web',
-   *   command: 'npm run dev',
+   *   start: 'npm run dev',
    *   path: '/app',
    * });
    *
-   * // With supervisor settings
+   * // With install command
    * const server = await sandbox.server.start({
    *   slug: 'api',
-   *   command: 'node server.js',
+   *   install: 'npm install',
+   *   start: 'node server.js',
    *   environment: { NODE_ENV: 'production' },
    *   restart_policy: 'always',
    *   max_restarts: 0, // unlimited
@@ -1415,6 +1421,29 @@ var Server = class {
   async updateStatus(slug, status) {
     await this.updateStatusHandler(slug, status);
   }
+  /**
+   * Retrieve captured output (logs) for a managed server
+   * @param slug - The server slug
+   * @param options - Options for log retrieval
+   * @returns Server logs info
+   *
+   * @example
+   * ```typescript
+   * // Get combined logs (default)
+   * const logs = await sandbox.server.logs('api');
+   * console.log(logs.logs);
+   *
+   * // Get only stdout
+   * const stdout = await sandbox.server.logs('api', { stream: 'stdout' });
+   *
+   * // Get only stderr
+   * const stderr = await sandbox.server.logs('api', { stream: 'stderr' });
+   * ```
+   */
+  async logs(slug, options) {
+    const response = await this.logsHandler(slug, options);
+    return response.data;
+  }
 };
 
 // src/client/resources/watcher.ts
@@ -1773,6 +1802,7 @@ var Run = class {
   constructor(handlers) {
     this.codeHandler = handlers.code;
     this.commandHandler = handlers.command;
+    this.waitHandler = handlers.wait;
   }
   /**
    * Execute code with automatic language detection
@@ -1796,10 +1826,38 @@ var Run = class {
    * @param options.background - Run in background (optional)
    * @param options.cwd - Working directory for the command (optional)
    * @param options.env - Environment variables (optional)
+   * @param options.waitForCompletion - If true (with background), wait for command to complete
    * @returns Command execution result with stdout, stderr, exit code, and duration
    */
   async command(command, options) {
-    return this.commandHandler(command, options);
+    const result = await this.commandHandler(command, options);
+    if (options?.background && options?.waitForCompletion && result.cmdId && result.terminalId) {
+      if (!this.waitHandler) {
+        throw new Error("Wait handler not configured");
+      }
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitHandler(result.terminalId, result.cmdId, waitOptions);
+    }
+    return result;
+  }
+  /**
+   * Wait for a background command to complete
+   *
+   * Uses the configured wait handler to block until the command
+   * is complete or fails (typically via server-side long-polling).
+   * Throws an error if the command fails or times out.
+   *
+   * @param terminalId - Terminal ID from background command result
+   * @param cmdId - Command ID from background command result
+   * @param options - Wait options passed to the handler
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   */
+  async waitForCompletion(terminalId, cmdId, options) {
+    if (!this.waitHandler) {
+      throw new Error("Wait handler not configured");
+    }
+    return this.waitHandler(terminalId, cmdId, options);
   }
 };
 
@@ -1856,18 +1914,25 @@ var Overlay = class {
   /**
    * Create a new overlay from a template directory
    *
-   * The overlay symlinks files from the source directory into the target path,
-   * allowing instant access to template files. Heavy directories (node_modules,
-   * .venv, etc.) are copied in the background.
+   * The overlay copies files from the source directory into the target path
+   * for better isolation. Heavy directories (node_modules, .venv, etc.) are
+   * copied in the background. Use the `ignore` option to exclude files/directories.
    *
    * @param options - Overlay creation options
    * @param options.source - Absolute path to source directory
    * @param options.target - Relative path in sandbox
+   * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
+   * @param options.waitForCompletion - If true or options object, wait for background copy to complete
    * @returns Overlay info with copy status
    */
   async create(options) {
     const response = await this.createHandler(options);
-    return this.toOverlayInfo(response);
+    const overlay = this.toOverlayInfo(response);
+    if (options.waitForCompletion) {
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitForCompletion(overlay.id, waitOptions);
+    }
+    return overlay;
   }
   /**
    * List all overlays for the current sandbox
@@ -1896,6 +1961,48 @@ var Overlay = class {
   async destroy(id) {
     return this.destroyHandler(id);
   }
+  /**
+   * Wait for an overlay's background copy to complete
+   *
+   * Polls the overlay status with exponential backoff until the copy
+   * is complete or fails. Throws an error if the copy fails or times out.
+   *
+   * @param id - Overlay ID
+   * @param options - Polling options
+   * @returns Overlay info with final copy status
+   * @throws Error if copy fails or times out
+   */
+  async waitForCompletion(id, options = {}) {
+    const maxRetries = options.maxRetries ?? 60;
+    const initialDelayMs = options.initialDelayMs ?? 500;
+    const maxDelayMs = options.maxDelayMs ?? 5e3;
+    const backoffFactor = options.backoffFactor ?? 1.5;
+    let currentDelay = initialDelayMs;
+    for (let i = 0; i < maxRetries; i++) {
+      const overlay = await this.retrieve(id);
+      if (overlay.copyStatus === "complete") {
+        return overlay;
+      }
+      if (overlay.copyStatus === "failed") {
+        throw new Error(
+          `Overlay copy failed: ${overlay.copyError || "Unknown error"}
+Overlay ID: ${id}`
+        );
+      }
+      if (i < maxRetries - 1) {
+        await new Promise((resolve) => setTimeout(resolve, currentDelay));
+        currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+      }
+    }
+    const finalOverlay = await this.retrieve(id);
+    throw new Error(
+      `Overlay copy timed out after ${maxRetries} attempts.
+Overlay ID: ${id}
+Current status: ${finalOverlay.copyStatus}
+
+Try increasing maxRetries or check if the source directory is very large.`
+    );
+  }
   /**
    * Convert API response to OverlayInfo
    */
@@ -1906,8 +2013,8 @@ var Overlay = class {
       target: response.target,
       createdAt: response.created_at,
       stats: {
-        symlinkedFiles: response.stats.symlinked_files,
-        symlinkedDirs: response.stats.symlinked_dirs,
+        copiedFiles: response.stats.copied_files,
+        copiedDirs: response.stats.copied_dirs,
         skipped: response.stats.skipped
       },
       copyStatus: this.validateCopyStatus(response.copy_status),
@@ -1939,6 +2046,7 @@ function isCommandExitError(error) {
 }
 
 // src/client/index.ts
+var MAX_TUNNEL_TIMEOUT_SECONDS = 300;
 var Sandbox = class {
   constructor(config) {
     this._token = null;
@@ -2057,8 +2165,15 @@ var Sandbox = class {
           stdout: result.data.stdout,
           stderr: result.data.stderr,
           exitCode: result.data.exit_code ?? 0,
-          durationMs: result.data.duration_ms ?? 0
+          durationMs: result.data.duration_ms ?? 0,
+          // Include cmdId and terminalId for background commands
+          cmdId: result.data.cmd_id,
+          terminalId: result.data.terminal_id,
+          status: result.data.status
         };
+      },
+      wait: async (terminalId, cmdId, options) => {
+        return this.waitForCommandCompletion(terminalId, cmdId, options);
       }
     });
     this.server = new Server({
@@ -2071,7 +2186,8 @@ var Sandbox = class {
       restart: async (slug) => this.restartServer(slug),
       updateStatus: async (slug, status) => {
         await this.updateServerStatus(slug, status);
-      }
+      },
+      logs: async (slug, options) => this.getServerLogs(slug, options)
     });
     this.watcher = new Watcher({
       create: async (path, options) => this.createWatcher(path, options),
@@ -2728,6 +2844,47 @@ API request failed (${response.status}): ${error}`
     const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
     return this.request(endpoint);
   }
+  /**
+   * Wait for a background command to complete using long-polling
+   *
+   * Uses the server's long-polling endpoint with configurable timeout.
+   * The tunnel supports up to 5 minutes (300 seconds) via X-Request-Timeout header.
+   *
+   * @param terminalId - The terminal ID
+   * @param cmdId - The command ID
+   * @param options - Wait options (timeoutSeconds, default 300)
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   * @internal
+   */
+  async waitForCommandCompletion(terminalId, cmdId, options) {
+    const timeoutSeconds = options?.timeoutSeconds ?? MAX_TUNNEL_TIMEOUT_SECONDS;
+    const response = await this.waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds);
+    return {
+      stdout: response.data.stdout,
+      stderr: response.data.stderr,
+      exitCode: response.data.exit_code ?? 0,
+      durationMs: response.data.duration_ms ?? 0,
+      cmdId: response.data.cmd_id,
+      terminalId,
+      status: response.data.status
+    };
+  }
+  /**
+   * Wait for a command with extended timeout support
+   * Uses X-Request-Timeout header for tunnel timeout configuration
+   * @internal
+   */
+  async waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds) {
+    const params = new URLSearchParams({ timeout: timeoutSeconds.toString() });
+    const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait?${params}`;
+    const requestTimeout = Math.min(timeoutSeconds, MAX_TUNNEL_TIMEOUT_SECONDS);
+    return this.request(endpoint, {
+      headers: {
+        "X-Request-Timeout": requestTimeout.toString()
+      }
+    });
+  }
   // ============================================================================
   // File Watchers
   // ============================================================================
@@ -2916,7 +3073,8 @@ API request failed (${response.status}): ${error}`
    *
    * @param options - Server configuration
    * @param options.slug - Unique server identifier
-   * @param options.command - Command to start the server
+   * @param options.install - Install command (optional, runs blocking before start, e.g., "npm install")
+   * @param options.start - Command to start the server (e.g., "npm run dev")
    * @param options.path - Working directory (optional)
    * @param options.env_file - Path to .env file relative to path (optional)
    * @param options.environment - Inline environment variables (merged with env_file if both provided)
@@ -2930,14 +3088,15 @@ API request failed (${response.status}): ${error}`
    * // Basic server
    * await sandbox.startServer({
    *   slug: 'web',
-   *   command: 'npm run dev',
+   *   start: 'npm run dev',
    *   path: '/app',
    * });
    *
-   * // With supervisor settings
+   * // With install command and supervisor settings
    * await sandbox.startServer({
    *   slug: 'api',
-   *   command: 'node server.js',
+   *   install: 'npm install',
+   *   start: 'node server.js',
    *   path: '/app',
    *   environment: { NODE_ENV: 'production', PORT: '3000' },
    *   restart_policy: 'on-failure',
@@ -2984,6 +3143,21 @@ API request failed (${response.status}): ${error}`
       }
     );
   }
+  /**
+   * Get logs for a managed server
+   * @param slug - Server slug
+   * @param options - Options for log retrieval
+   */
+  async getServerLogs(slug, options) {
+    const params = new URLSearchParams();
+    if (options?.stream) {
+      params.set("stream", options.stream);
+    }
+    const queryString = params.toString();
+    return this.request(
+      `/servers/${encodeURIComponent(slug)}/logs${queryString ? `?${queryString}` : ""}`
+    );
+  }
   /**
    * Update server status (internal use)
    * @param slug - Server slug
@@ -3265,7 +3439,9 @@ var PROVIDER_HEADERS = {
     tokenSecret: "X-Modal-Token-Secret"
   },
   railway: {
-    apiToken: "X-Railway-API-Token"
+    apiToken: "X-Railway-API-Key",
+    projectId: "X-Railway-Project-ID",
+    environmentId: "X-Railway-Environment-ID"
   },
   daytona: {
     apiKey: "X-Daytona-API-Key"