computesdk 1.12.1 → 1.15.0

package/dist/index.d.ts

@@ -1109,8 +1109,10 @@ declare class Terminal {
 interface ServerStartOptions {
     /** Unique server identifier (URL-safe) */
     slug: string;
-    /** Command to start the server */
-    command: string;
+    /** Install command to run before starting (optional, runs blocking, e.g., "npm install") */
+    install?: string;
+    /** Command to start the server (e.g., "npm run dev") */
+    start: string;
     /** Working directory (optional) */
     path?: string;
     /** Path to .env file relative to path (optional) */
@@ -1139,14 +1141,22 @@ interface ServerStartOptions {
  * // Start a basic server
  * const server = await sandbox.server.start({
  *   slug: 'api',
- *   command: 'npm start',
+ *   start: 'npm start',
+ *   path: '/app',
+ * });
+ *
+ * // Start with install command (runs before start)
+ * const server = await sandbox.server.start({
+ *   slug: 'web',
+ *   install: 'npm install',
+ *   start: 'npm run dev',
  *   path: '/app',
  * });
  *
  * // Start with supervisor settings (auto-restart on failure)
  * const server = await sandbox.server.start({
  *   slug: 'web',
- *   command: 'node server.js',
+ *   start: 'node server.js',
  *   path: '/app',
  *   environment: { NODE_ENV: 'production', PORT: '3000' },
  *   restart_policy: 'on-failure',
@@ -1167,6 +1177,24 @@ interface ServerStartOptions {
  * await sandbox.server.restart('api');
  * ```
  */
+/**
+ * Options for retrieving server logs
+ */
+interface ServerLogsOptions {
+    /** Which output stream to return: 'stdout', 'stderr', or 'combined' (default) */
+    stream?: ServerLogStream;
+}
+/**
+ * Server logs info returned from the logs method
+ */
+interface ServerLogsInfo {
+    /** Server slug identifier */
+    slug: string;
+    /** Which stream was returned */
+    stream: ServerLogStream;
+    /** The captured logs */
+    logs: string;
+}
 declare class Server {
     private startHandler;
     private listHandler;
@@ -1174,6 +1202,7 @@ declare class Server {
     private stopHandler;
     private restartHandler;
     private updateStatusHandler;
+    private logsHandler;
     constructor(handlers: {
         start: (options: ServerStartOptions) => Promise<ServerResponse>;
         list: () => Promise<ServersListResponse>;
@@ -1181,10 +1210,15 @@ declare class Server {
         stop: (slug: string) => Promise<ServerStopResponse | void>;
         restart: (slug: string) => Promise<ServerResponse>;
         updateStatus: (slug: string, status: ServerStatus) => Promise<void>;
+        logs: (slug: string, options?: ServerLogsOptions) => Promise<ServerLogsResponse>;
     });
     /**
      * 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
@@ -1202,14 +1236,15 @@ declare class Server {
      * // 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
@@ -1245,6 +1280,26 @@ declare class Server {
      * @param status - New status
      */
     updateStatus(slug: string, status: ServerStatus): Promise<void>;
+    /**
+     * 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' });
+     * ```
+     */
+    logs(slug: string, options?: ServerLogsOptions): Promise<ServerLogsInfo>;
 }
 
 /**
@@ -1922,6 +1977,158 @@ declare class Child {
     }): Promise<void>;
 }
 
+/**
+ * Overlay - Resource namespace for filesystem overlay operations
+ *
+ * Overlays enable instant sandbox setup from template directories by copying
+ * files directly for isolation, with heavy directories copied in the background.
+ */
+/**
+ * Options for creating an overlay
+ */
+interface CreateOverlayOptions {
+    /** Absolute path to source directory (template) */
+    source: string;
+    /** Relative path in sandbox where overlay will be mounted */
+    target: string;
+    /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
+    ignore?: string[];
+}
+/**
+ * Copy status for overlay background operations
+ */
+type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+/**
+ * Statistics about an overlay
+ */
+interface OverlayStats {
+    /** Number of copied files */
+    copiedFiles: number;
+    /** Number of copied directories (heavy dirs copied in background) */
+    copiedDirs: number;
+    /** Paths that were skipped (e.g., .git, ignored patterns) */
+    skipped: string[];
+}
+/**
+ * Overlay information (client-side normalized type)
+ */
+interface OverlayInfo {
+    /** Unique overlay identifier */
+    id: string;
+    /** Absolute path to source directory */
+    source: string;
+    /** Relative path in sandbox */
+    target: string;
+    /** When the overlay was created */
+    createdAt: string;
+    /** Statistics about the overlay */
+    stats: OverlayStats;
+    /** Copy status for background operations */
+    copyStatus: OverlayCopyStatus;
+    /** Error message if copy failed */
+    copyError?: string;
+}
+/**
+ * API response for overlay operations (snake_case from server)
+ */
+interface OverlayResponse {
+    id: string;
+    source: string;
+    target: string;
+    created_at: string;
+    stats: {
+        copied_files: number;
+        copied_dirs: number;
+        skipped: string[];
+    };
+    copy_status: string;
+    copy_error?: string;
+}
+/**
+ * API response for listing overlays
+ */
+interface OverlayListResponse {
+    overlays: OverlayResponse[];
+}
+/**
+ * Overlay resource namespace
+ *
+ * @example
+ * ```typescript
+ * // Create an overlay from a template directory
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ * });
+ * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+ *
+ * // List all overlays
+ * const overlays = await sandbox.filesystem.overlay.list();
+ *
+ * // Get a specific overlay (useful for polling copy status)
+ * const overlay = await sandbox.filesystem.overlay.retrieve('overlay-id');
+ * if (overlay.copyStatus === 'complete') {
+ *   console.log('Background copy finished!');
+ * }
+ *
+ * // Delete an overlay
+ * await sandbox.filesystem.overlay.destroy('overlay-id');
+ * ```
+ */
+declare class Overlay {
+    private createHandler;
+    private listHandler;
+    private retrieveHandler;
+    private destroyHandler;
+    constructor(handlers: {
+        create: (options: CreateOverlayOptions) => Promise<OverlayResponse>;
+        list: () => Promise<OverlayListResponse>;
+        retrieve: (id: string) => Promise<OverlayResponse>;
+        destroy: (id: string) => Promise<void>;
+    });
+    /**
+     * Create a new overlay from a template directory
+     *
+     * 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"])
+     * @returns Overlay info with copy status
+     */
+    create(options: CreateOverlayOptions): Promise<OverlayInfo>;
+    /**
+     * List all overlays for the current sandbox
+     * @returns Array of overlay info
+     */
+    list(): Promise<OverlayInfo[]>;
+    /**
+     * Retrieve a specific overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay info
+     */
+    retrieve(id: string): Promise<OverlayInfo>;
+    /**
+     * Destroy (delete) an overlay
+     * @param id - Overlay ID
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Convert API response to OverlayInfo
+     */
+    private toOverlayInfo;
+    /**
+     * Validate and return copy status, defaulting to 'pending' for unknown values
+     */
+    private validateCopyStatus;
+}
+
 /**
  * Binary WebSocket Protocol Implementation
  *
@@ -2030,6 +2237,14 @@ declare function isCommandExitError(error: unknown): error is CommandExitError;
  * Node.js: Pass WebSocket implementation (e.g., 'ws' library)
  */
 
+/**
+ * Extended filesystem interface with overlay support
+ */
+interface ExtendedFileSystem extends SandboxFileSystem {
+    /** Overlay operations for template directories */
+    readonly overlay: Overlay;
+}
+
 /**
  * WebSocket constructor type
  */
@@ -2356,6 +2571,7 @@ interface TerminalResponse {
 /**
  * Server status types
  *
+ * - `installing`: Running install command (e.g., npm install) before starting
  * - `starting`: Initial startup of the server process
  * - `running`: Server process is running
  * - `ready`: Server is running and ready to accept traffic
@@ -2363,7 +2579,7 @@ interface TerminalResponse {
  * - `stopped`: Server was intentionally stopped
  * - `restarting`: Server is being automatically restarted by the supervisor
  */
-type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
+type ServerStatus = 'installing' | 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
 /**
  * Server restart policy
  * - `never`: No automatic restart (default)
@@ -2377,8 +2593,10 @@ type RestartPolicy = 'never' | 'on-failure' | 'always';
 interface ServerInfo {
     /** Unique server identifier */
     slug: string;
+    /** Install command (optional, runs blocking before start) */
+    install?: string;
     /** Command used to start the server */
-    command: string;
+    start: string;
     /** Working directory path */
     path: string;
     /** Original path before resolution */
@@ -2442,6 +2660,22 @@ interface ServerStopResponse {
         slug: string;
     };
 }
+/**
+ * Server logs stream type
+ */
+type ServerLogStream = 'stdout' | 'stderr' | 'combined';
+/**
+ * Server logs response
+ */
+interface ServerLogsResponse {
+    status: string;
+    message: string;
+    data: {
+        slug: string;
+        stream: ServerLogStream;
+        logs: string;
+    };
+}
 /**
  * Server status update response
  */
@@ -2593,7 +2827,7 @@ interface BatchWriteResponse {
 declare class Sandbox {
     readonly sandboxId: string;
     readonly provider: string;
-    readonly filesystem: SandboxFileSystem;
+    readonly filesystem: ExtendedFileSystem;
     readonly terminal: Terminal;
     readonly run: Run;
     readonly server: Server;
@@ -2827,6 +3061,47 @@ declare class Sandbox {
         operation: 'write' | 'delete';
         content?: string;
     }>): Promise<BatchWriteResponse>;
+    /**
+     * Create a new filesystem overlay from a template directory
+     *
+     * Overlays enable instant sandbox setup by symlinking template files first,
+     * then copying heavy directories (node_modules, .venv, etc.) in the background.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory (template)
+     * @param options.target - Relative path in sandbox where overlay will be mounted
+     * @returns Overlay response with copy status
+     *
+     * @example
+     * ```typescript
+     * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+     * const overlay = await sandbox.filesystem.overlay.create({
+     *   source: '/templates/nextjs',
+     *   target: 'project',
+     * });
+     * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+     * ```
+     */
+    createOverlay(options: CreateOverlayOptions): Promise<OverlayResponse>;
+    /**
+     * List all filesystem overlays for the current sandbox
+     * @returns List of overlays with their copy status
+     */
+    listOverlays(): Promise<OverlayListResponse>;
+    /**
+     * Get a specific filesystem overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay details with current copy status
+     */
+    getOverlay(id: string): Promise<OverlayResponse>;
+    /**
+     * Delete a filesystem overlay
+     * @param id - Overlay ID
+     */
+    deleteOverlay(id: string): Promise<void>;
     /**
      * Create a new persistent terminal session
      *
@@ -2978,7 +3253,8 @@ declare class Sandbox {
      *
      * @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)
@@ -2992,14 +3268,15 @@ declare class Sandbox {
      * // 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',
@@ -3011,7 +3288,8 @@ declare class Sandbox {
      */
     startServer(options: {
         slug: string;
-        command: string;
+        install?: string;
+        start: string;
         path?: string;
         env_file?: string;
         environment?: Record<string, string>;
@@ -3035,6 +3313,14 @@ declare class Sandbox {
      * @param slug - Server slug
      */
     restartServer(slug: string): Promise<ServerResponse>;
+    /**
+     * Get logs for a managed server
+     * @param slug - Server slug
+     * @param options - Options for log retrieval
+     */
+    getServerLogs(slug: string, options?: {
+        stream?: ServerLogStream;
+    }): Promise<ServerLogsResponse>;
     /**
      * Update server status (internal use)
      * @param slug - Server slug