@cloudflare/sandbox 0.3.7 → 0.4.1

package/src/clients/git-client.ts

@@ -0,0 +1,92 @@
+import type { GitCheckoutResult } from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions, SessionRequest } from './types';
+
+// Re-export for convenience
+export type { GitCheckoutResult };
+
+/**
+ * Request interface for Git checkout operations
+ */
+export interface GitCheckoutRequest extends SessionRequest {
+  repoUrl: string;
+  branch?: string;
+  targetDir?: string;
+}
+
+/**
+ * Client for Git repository operations
+ */
+export class GitClient extends BaseHttpClient {
+
+  /**
+   * Clone a Git repository
+   * @param repoUrl - URL of the Git repository to clone
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (branch, targetDir)
+   */
+  async checkout(
+    repoUrl: string,
+    sessionId: string,
+    options?: {
+      branch?: string;
+      targetDir?: string;
+    }
+  ): Promise<GitCheckoutResult> {
+    try {
+      // Determine target directory - use provided path or generate from repo name
+      let targetDir = options?.targetDir;
+      if (!targetDir) {
+        const repoName = this.extractRepoName(repoUrl);
+        // Ensure absolute path in /workspace
+        targetDir = `/workspace/${repoName}`;
+      }
+
+      const data: GitCheckoutRequest = {
+        repoUrl,
+        sessionId,
+        targetDir,
+      };
+
+      // Only include branch if explicitly specified
+      // This allows Git to use the repository's default branch
+      if (options?.branch) {
+        data.branch = options.branch;
+      }
+
+      const response = await this.post<GitCheckoutResult>(
+        '/api/git/checkout',
+        data
+      );
+
+      this.logSuccess(
+        'Repository cloned',
+        `${repoUrl} (branch: ${response.branch}) -> ${response.targetDir}`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('checkout', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Extract repository name from URL for default directory name
+   */
+  private extractRepoName(repoUrl: string): string {
+    try {
+      const url = new URL(repoUrl);
+      const pathParts = url.pathname.split('/');
+      const repoName = pathParts[pathParts.length - 1];
+      
+      // Remove .git extension if present
+      return repoName.replace(/\.git$/, '');
+    } catch {
+      // Fallback for invalid URLs
+      const parts = repoUrl.split('/');
+      const repoName = parts[parts.length - 1];
+      return repoName.replace(/\.git$/, '') || 'repo';
+    }
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,63 @@
+// Main client exports
+
+
+// Command client types
+export type {
+  ExecuteRequest,
+  ExecuteResponse,
+} from './command-client';
+
+// Domain-specific clients
+export { CommandClient } from './command-client';
+// File client types
+export type {
+  FileOperationRequest,
+  MkdirRequest,
+  ReadFileRequest,
+  WriteFileRequest,
+} from './file-client';
+export { FileClient } from './file-client';
+// Git client types
+export type {
+  GitCheckoutRequest,
+  GitCheckoutResult,
+} from './git-client';
+export { GitClient } from './git-client';
+export { type ExecutionCallbacks, InterpreterClient } from './interpreter-client';
+// Port client types
+export type {
+  ExposePortRequest,
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+  UnexposePortRequest,
+} from './port-client';
+export { PortClient } from './port-client';
+// Process client types
+export type {
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  StartProcessRequest,
+} from './process-client';
+export { ProcessClient } from './process-client';
+export { SandboxClient } from './sandbox-client';
+// Types and interfaces
+export type {
+  BaseApiResponse,
+  ContainerStub,
+  ErrorResponse,
+  HttpClientOptions,
+  RequestConfig,
+  ResponseHandler,
+  SessionRequest,
+} from './types';
+// Utility client types
+export type {
+  CommandsResponse,
+  PingResponse,
+} from './utility-client';
+export { UtilityClient } from './utility-client';

package/src/{interpreter-client.ts → clients/interpreter-client.ts}

@@ -1,25 +1,17 @@
-import { HttpClient } from "./client.js";
-import { isRetryableError, parseErrorResponse } from "./errors.js";
-import type {
-  CodeContext,
-  CreateContextOptions,
-  ExecutionError,
-  OutputMessage,
-  Result,
-} from "./interpreter-types.js";
-
-// API Response types
-interface ContextResponse {
-  id: string;
-  language: string;
-  cwd: string;
-  createdAt: string; // ISO date string from JSON
-  lastUsed: string; // ISO date string from JSON
-}
-
-interface ContextListResponse {
-  contexts: ContextResponse[];
-}
+import {
+  type CodeContext,
+  type ContextCreateResult,
+  type ContextListResult,
+  type CreateContextOptions,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
+  ResultImpl,
+} from '@repo/shared';
+import type { ErrorResponse } from '../errors';
+import { createErrorFromResponse, ErrorCode, InterpreterNotReadyError } from '../errors';
+import { BaseHttpClient } from './base-client.js';
+import type { HttpClientOptions } from './types.js';
 
 // Streaming execution data from the server
 interface StreamingExecutionData {
@@ -62,7 +54,7 @@ export interface ExecutionCallbacks {
   onError?: (error: ExecutionError) => void | Promise<void>;
 }
 
-export class InterpreterClient extends HttpClient {
+export class InterpreterClient extends BaseHttpClient {
   private readonly maxRetries = 3;
   private readonly retryDelayMs = 1000;
 
@@ -81,16 +73,21 @@ export class InterpreterClient extends HttpClient {
       });
 
       if (!response.ok) {
-        throw await parseErrorResponse(response);
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      const data = (await response.json()) as ContextCreateResult;
+      if (!data.success) {
+        throw new Error(`Failed to create context: ${JSON.stringify(data)}`);
       }
 
-      const data = (await response.json()) as ContextResponse;
       return {
-        id: data.id,
+        id: data.contextId,
         language: data.language,
-        cwd: data.cwd,
-        createdAt: new Date(data.createdAt),
-        lastUsed: new Date(data.lastUsed),
+        cwd: data.cwd || '/workspace',
+        createdAt: new Date(data.timestamp),
+        lastUsed: new Date(data.timestamp),
       };
     });
   }
@@ -99,7 +96,8 @@ export class InterpreterClient extends HttpClient {
     contextId: string | undefined,
     code: string,
     language: string | undefined,
-    callbacks: ExecutionCallbacks
+    callbacks: ExecutionCallbacks,
+    timeoutMs?: number
   ): Promise<void> {
     return this.executeWithRetry(async () => {
       const response = await this.doFetch("/api/execute/code", {
@@ -112,11 +110,13 @@ export class InterpreterClient extends HttpClient {
           context_id: contextId,
           code,
           language,
+          ...(timeoutMs !== undefined && { timeout_ms: timeoutMs })
         }),
       });
 
       if (!response.ok) {
-        throw await parseErrorResponse(response);
+        const error = await this.parseErrorResponse(response);
+        throw error;
       }
 
       if (!response.body) {
@@ -130,6 +130,112 @@ export class InterpreterClient extends HttpClient {
     });
   }
 
+  async listCodeContexts(): Promise<CodeContext[]> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/contexts", {
+        method: "GET",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      const data = (await response.json()) as ContextListResult;
+      if (!data.success) {
+        throw new Error(`Failed to list contexts: ${JSON.stringify(data)}`);
+      }
+
+      return data.contexts.map((ctx) => ({
+        id: ctx.id,
+        language: ctx.language,
+        cwd: ctx.cwd || '/workspace',
+        createdAt: new Date(data.timestamp),
+        lastUsed: new Date(data.timestamp),
+      }));
+    });
+  }
+
+  async deleteCodeContext(contextId: string): Promise<void> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch(`/api/contexts/${contextId}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * Execute an operation with automatic retry for transient errors
+   */
+  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        this.logError('executeWithRetry', error);
+        lastError = error as Error;
+
+        // Check if it's a retryable error (interpreter not ready)
+        if (this.isRetryableError(error)) {
+          // Don't retry on the last attempt
+          if (attempt < this.maxRetries - 1) {
+            // Exponential backoff with jitter
+            const delay =
+              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+
+        // Not retryable or last attempt - throw the error
+        throw error;
+      }
+    }
+
+    throw lastError || new Error("Execution failed after retries");
+  }
+
+  private isRetryableError(error: unknown): boolean {
+    if (error instanceof InterpreterNotReadyError) {
+      return true;
+    }
+
+    if (error instanceof Error) {
+      return (
+        error.message.includes("not ready") ||
+        error.message.includes("initializing")
+      );
+    }
+
+    return false;
+  }
+
+  private async parseErrorResponse(response: Response): Promise<Error> {
+    try {
+      const errorData = await response.json() as ErrorResponse;
+      return createErrorFromResponse(errorData);
+    } catch {
+      // Fallback if response isn't JSON
+      const errorResponse: ErrorResponse = {
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `HTTP ${response.status}: ${response.statusText}`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: new Date().toISOString()
+      };
+      return createErrorFromResponse(errorResponse);
+    }
+  }
+
   private async *readLines(
     stream: ReadableStream<Uint8Array>
   ): AsyncGenerator<string> {
@@ -167,8 +273,13 @@ export class InterpreterClient extends HttpClient {
   ) {
     if (!line.trim()) return;
 
+    // Skip lines that don't start with "data: " (SSE format)
+    if (!line.startsWith('data: ')) return;
+
     try {
-      const data = JSON.parse(line) as StreamingExecutionData;
+      // Strip "data: " prefix and parse JSON
+      const jsonData = line.substring(6); // "data: " is 6 characters
+      const data = JSON.parse(jsonData) as StreamingExecutionData;
 
       switch (data.type) {
         case "stdout":
@@ -191,34 +302,8 @@ export class InterpreterClient extends HttpClient {
 
         case "result":
           if (callbacks.onResult) {
-            // Convert raw result to Result interface
-            const result: Result = {
-              text: data.text,
-              html: data.html,
-              png: data.png,
-              jpeg: data.jpeg,
-              svg: data.svg,
-              latex: data.latex,
-              markdown: data.markdown,
-              javascript: data.javascript,
-              json: data.json,
-              chart: data.chart,
-              data: data.data,
-              formats: () => {
-                const formats: string[] = [];
-                if (data.text) formats.push("text");
-                if (data.html) formats.push("html");
-                if (data.png) formats.push("png");
-                if (data.jpeg) formats.push("jpeg");
-                if (data.svg) formats.push("svg");
-                if (data.latex) formats.push("latex");
-                if (data.markdown) formats.push("markdown");
-                if (data.javascript) formats.push("javascript");
-                if (data.json) formats.push("json");
-                if (data.chart) formats.push("chart");
-                return formats;
-              },
-            };
+            // Create a ResultImpl instance from the raw data
+            const result = new ResultImpl(data);
             await callbacks.onResult(result);
           }
           break;
@@ -227,126 +312,18 @@ export class InterpreterClient extends HttpClient {
           if (callbacks.onError) {
             await callbacks.onError({
               name: data.ename || "Error",
-              value: data.evalue || data.text || "Unknown error",
+              message: data.evalue || "Unknown error",
               traceback: data.traceback || [],
-              lineNumber: data.lineNumber,
             });
           }
           break;
 
         case "execution_complete":
-          // Execution completed successfully
+          // Signal completion - callbacks can handle cleanup if needed
           break;
       }
     } catch (error) {
-      console.error(
-        "[InterpreterClient] Error parsing execution result:",
-        error
-      );
+      this.logError('parseExecutionResult', error);
     }
   }
-
-  async listCodeContexts(): Promise<CodeContext[]> {
-    return this.executeWithRetry(async () => {
-      const response = await this.doFetch("/api/contexts", {
-        method: "GET",
-        headers: { "Content-Type": "application/json" },
-      });
-
-      if (!response.ok) {
-        throw await parseErrorResponse(response);
-      }
-
-      const data = (await response.json()) as ContextListResponse;
-      return data.contexts.map((ctx) => ({
-        id: ctx.id,
-        language: ctx.language,
-        cwd: ctx.cwd,
-        createdAt: new Date(ctx.createdAt),
-        lastUsed: new Date(ctx.lastUsed),
-      }));
-    });
-  }
-
-  async deleteCodeContext(contextId: string): Promise<void> {
-    return this.executeWithRetry(async () => {
-      const response = await this.doFetch(`/api/contexts/${contextId}`, {
-        method: "DELETE",
-        headers: { "Content-Type": "application/json" },
-      });
-
-      if (!response.ok) {
-        throw await parseErrorResponse(response);
-      }
-    });
-  }
-
-  // Override parent doFetch to be public for this class
-  public async doFetch(path: string, options?: RequestInit): Promise<Response> {
-    return super.doFetch(path, options);
-  }
-
-  /**
-   * Execute an operation with automatic retry for transient errors
-   */
-  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
-    let lastError: Error | undefined;
-
-    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
-      try {
-        return await operation();
-      } catch (error) {
-        lastError = error as Error;
-
-        // Check if it's a retryable error (circuit breaker or interpreter not ready)
-        if (this.isRetryableError(error)) {
-          // Don't retry on the last attempt
-          if (attempt < this.maxRetries - 1) {
-            // Exponential backoff with jitter
-            const delay =
-              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            continue;
-          }
-        }
-
-        // Non-retryable error or last attempt - throw immediately
-        throw error;
-      }
-    }
-
-    // All retries exhausted - throw a clean error without implementation details
-    if (lastError?.message.includes("Code execution")) {
-      // If the error already has a clean message about code execution, use it
-      throw lastError;
-    }
-
-    // Otherwise, throw a generic but user-friendly error
-    throw new Error("Unable to execute code at this time");
-  }
-
-  /**
-   * Check if an error is retryable
-   */
-  private isRetryableError(error: unknown): boolean {
-    // Use the SDK's built-in retryable check
-    if (isRetryableError(error)) {
-      return true;
-    }
-
-    // Also check for circuit breaker specific errors
-    if (error instanceof Error) {
-      // Circuit breaker errors (from the container's response)
-      if (error.message.includes("Circuit breaker is open")) {
-        return true;
-      }
-
-      // Check if error has a status property
-      if ("status" in error && error.status === "circuit_open") {
-        return true;
-      }
-    }
-
-    return false;
-  }
 }

package/src/clients/port-client.ts

@@ -0,0 +1,105 @@
+import type {
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions } from './types';
+
+// Re-export for convenience
+export type {
+  PortExposeResult,
+  PortCloseResult,
+  PortListResult,
+};
+
+/**
+ * Request interface for exposing ports
+ */
+export interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Request interface for unexposing ports
+ */
+export interface UnexposePortRequest {
+  port: number;
+}
+
+/**
+ * Client for port management and preview URL operations
+ */
+export class PortClient extends BaseHttpClient {
+
+  /**
+   * Expose a port and get a preview URL
+   * @param port - Port number to expose
+   * @param sessionId - The session ID for this operation
+   * @param name - Optional name for the port
+   */
+  async exposePort(
+    port: number,
+    sessionId: string,
+    name?: string
+  ): Promise<PortExposeResult> {
+    try {
+      const data = { port, sessionId, name };
+
+      const response = await this.post<PortExposeResult>(
+        '/api/expose-port',
+        data
+      );
+
+      this.logSuccess(
+        'Port exposed',
+        `${port} exposed at ${response.url}${name ? ` (${name})` : ''}`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('exposePort', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Unexpose a port and remove its preview URL
+   * @param port - Port number to unexpose
+   * @param sessionId - The session ID for this operation
+   */
+  async unexposePort(port: number, sessionId: string): Promise<PortCloseResult> {
+    try {
+      const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.delete<PortCloseResult>(url);
+
+      this.logSuccess('Port unexposed', `${port}`);
+      return response;
+    } catch (error) {
+      this.logError('unexposePort', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get all currently exposed ports
+   * @param sessionId - The session ID for this operation
+   */
+  async getExposedPorts(sessionId: string): Promise<PortListResult> {
+    try {
+      const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.get<PortListResult>(url);
+
+      this.logSuccess(
+        'Exposed ports retrieved',
+        `${response.ports.length} ports exposed`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('getExposedPorts', error);
+      throw error;
+    }
+  }
+}