computesdk 1.13.0 → 1.15.0

package/dist/index.d.mts

@@ -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>;
 }
 
 /**
@@ -1925,8 +1980,8 @@ declare class Child {
 /**
  * Overlay - Resource namespace for filesystem overlay operations
  *
- * Overlays enable instant sandbox setup from template directories by symlinking
- * files first for instant access, then copying heavy directories in the background.
+ * 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
@@ -1936,6 +1991,8 @@ interface CreateOverlayOptions {
     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
@@ -1945,11 +2002,11 @@ type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
  * Statistics about an overlay
  */
 interface OverlayStats {
-    /** Number of symlinked files */
-    symlinkedFiles: number;
-    /** Number of symlinked directories */
-    symlinkedDirs: number;
-    /** Paths that were skipped (e.g., .git) */
+    /** 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[];
 }
 /**
@@ -1980,8 +2037,8 @@ interface OverlayResponse {
     target: string;
     created_at: string;
     stats: {
-        symlinked_files: number;
-        symlinked_dirs: number;
+        copied_files: number;
+        copied_dirs: number;
         skipped: string[];
     };
     copy_status: string;
@@ -2032,13 +2089,14 @@ declare class Overlay {
     /**
      * 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"])
      * @returns Overlay info with copy status
      */
     create(options: CreateOverlayOptions): Promise<OverlayInfo>;
@@ -2513,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
@@ -2520,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)
@@ -2534,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 */
@@ -2599,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
  */
@@ -3176,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)
@@ -3190,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',
@@ -3209,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>;
@@ -3233,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

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>;
 }
 
 /**
@@ -1925,8 +1980,8 @@ declare class Child {
 /**
  * Overlay - Resource namespace for filesystem overlay operations
  *
- * Overlays enable instant sandbox setup from template directories by symlinking
- * files first for instant access, then copying heavy directories in the background.
+ * 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
@@ -1936,6 +1991,8 @@ interface CreateOverlayOptions {
     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
@@ -1945,11 +2002,11 @@ type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
  * Statistics about an overlay
  */
 interface OverlayStats {
-    /** Number of symlinked files */
-    symlinkedFiles: number;
-    /** Number of symlinked directories */
-    symlinkedDirs: number;
-    /** Paths that were skipped (e.g., .git) */
+    /** 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[];
 }
 /**
@@ -1980,8 +2037,8 @@ interface OverlayResponse {
     target: string;
     created_at: string;
     stats: {
-        symlinked_files: number;
-        symlinked_dirs: number;
+        copied_files: number;
+        copied_dirs: number;
         skipped: string[];
     };
     copy_status: string;
@@ -2032,13 +2089,14 @@ declare class Overlay {
     /**
      * 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"])
      * @returns Overlay info with copy status
      */
     create(options: CreateOverlayOptions): Promise<OverlayInfo>;
@@ -2513,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
@@ -2520,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)
@@ -2534,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 */
@@ -2599,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
  */
@@ -3176,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)
@@ -3190,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',
@@ -3209,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>;
@@ -3233,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