@larkup/sandbox 0.1.2 → 0.1.4

package/src/sandbox-manager.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const dockerRunner = vi.hoisted(() => ({
+  checkDockerHealth: vi.fn(),
+  ensureImage: vi.fn(),
+  executeInDocker: vi.fn(),
+}));
+const localRunner = vi.hoisted(() => ({
+  checkLocalRuntime: vi.fn(),
+  executeLocally: vi.fn(),
+}));
+
+vi.mock('./docker-runner.js', () => ({
+  checkDockerHealth: dockerRunner.checkDockerHealth,
+  ensureImage: dockerRunner.ensureImage,
+  executeInDocker: dockerRunner.executeInDocker,
+  buildSandboxImage: vi.fn(),
+}));
+
+vi.mock('./providers/index.js', () => ({
+  getSandboxProviderAdapter: vi.fn(),
+}));
+vi.mock('./local-runner.js', () => ({
+  checkLocalRuntime: localRunner.checkLocalRuntime,
+  executeLocally: localRunner.executeLocally,
+}));
+
+import { SandboxManager } from './sandbox-manager.js';
+
+describe('SandboxManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a safe recovery message when Docker is unavailable', async () => {
+    dockerRunner.checkDockerHealth.mockResolvedValue({
+      status: 'docker-not-found',
+      backend: 'docker',
+      error: 'connect ENOENT /var/run/docker.sock',
+    });
+
+    const result = await new SandboxManager({ backend: 'docker' }).execute({
+      code: 'print(1)',
+      language: 'python',
+    });
+
+    expect(result).toMatchObject({
+      exitCode: 1,
+      stdout: '',
+      artifacts: [],
+      executionTimeMs: 0,
+    });
+    expect(result.stderr).toContain('Docker is not running');
+    expect(result.stderr).not.toContain('/var/run/docker.sock');
+    expect(dockerRunner.ensureImage).not.toHaveBeenCalled();
+    expect(dockerRunner.executeInDocker).not.toHaveBeenCalled();
+  });
+
+  it('uses the local runtime by default without contacting Docker', async () => {
+    localRunner.executeLocally.mockResolvedValue({
+      stdout: '1\n',
+      stderr: '',
+      exitCode: 0,
+      artifacts: [],
+      executionTimeMs: 1,
+    });
+
+    const result = await new SandboxManager().execute({ code: 'print(1)', language: 'python' });
+
+    expect(result.exitCode).toBe(0);
+    expect(localRunner.executeLocally).toHaveBeenCalledOnce();
+    expect(dockerRunner.checkDockerHealth).not.toHaveBeenCalled();
+  });
+});

package/src/sandbox-manager.ts

@@ -2,8 +2,9 @@
  * Sandbox manager — high-level API for code execution.
  *
  * Provides a unified interface that routes to the appropriate backend
- * (Docker, E2B, etc.) based on configuration. Handles health checks,
- * image setup, and execution lifecycle.
+ * (Docker or one of the remote providers in ./providers) based on
+ * configuration. Handles health checks, image setup, and execution
+ * lifecycle.
  */
 
 import type {
@@ -12,7 +13,6 @@ import type {
   ExecutionResult,
   SandboxHealthCheck,
   DockerConfig,
-  DEFAULT_DOCKER_CONFIG,
 } from './types.js';
 import {
   checkDockerHealth,
@@ -20,6 +20,8 @@ import {
   ensureImage,
   executeInDocker,
 } from './docker-runner.js';
+import { checkLocalRuntime, executeLocally } from './local-runner.js';
+import { getSandboxProviderAdapter } from './providers/index.js';
 
 const defaultDockerConfig: DockerConfig = {
   imageName: 'larkup-sandbox:latest',
@@ -34,39 +36,33 @@ export class SandboxManager {
 
   constructor(config?: Partial<SandboxConfig>) {
     this.config = {
-      backend: config?.backend ?? 'docker',
+      backend: config?.backend ?? 'local',
       docker: config?.docker,
-      remote: config?.remote,
+      credentials: config?.credentials,
     };
   }
 
   /** Check if the sandbox backend is available and ready. */
   async healthCheck(): Promise<SandboxHealthCheck> {
-    switch (this.config.backend) {
-      case 'docker':
-        return checkDockerHealth();
+    if (this.config.backend === 'local') return checkLocalRuntime();
+    if (this.config.backend === 'docker') return checkDockerHealth();
 
-      case 'e2b':
-      case 'modal':
-      case 'custom':
-        return {
-          status: 'error',
-          backend: this.config.backend,
-          error: `${this.config.backend} backend is not yet implemented. Use Docker for local execution.`,
-        };
-
-      default:
-        return {
-          status: 'error',
-          backend: this.config.backend,
-          error: `Unknown backend: ${this.config.backend}`,
-        };
+    const adapter = getSandboxProviderAdapter(this.config.backend);
+    if (!adapter) {
+      return {
+        status: 'error',
+        backend: this.config.backend,
+        error: `Unknown or unsupported backend: ${this.config.backend}`,
+      };
     }
+    return adapter.healthCheck(this.config.credentials ?? {});
   }
 
   /** Set up the sandbox backend (e.g., build Docker image). */
   async setup(onProgress?: (msg: string) => void): Promise<void> {
     switch (this.config.backend) {
+      case 'local':
+        return;
       case 'docker':
         await buildSandboxImage(onProgress);
         break;
@@ -78,47 +74,71 @@ export class SandboxManager {
 
   /** Execute code in the sandbox. */
   async execute(request: ExecutionRequest): Promise<ExecutionResult> {
-    switch (this.config.backend) {
-      case 'docker': {
-        // Ensure image is available
-        const imageReady = await ensureImage();
-        if (!imageReady) {
-          return {
-            stdout: '',
-            stderr: 'Sandbox image not available. Run setup first or ensure Docker is installed.',
-            exitCode: 1,
-            artifacts: [],
-            executionTimeMs: 0,
-          };
-        }
-
-        const dockerConfig: DockerConfig = {
-          ...defaultDockerConfig,
-          ...this.config.docker,
-        };
-
-        return executeInDocker(request, dockerConfig);
-      }
-
-      case 'e2b':
-      case 'modal':
-      case 'custom':
+    if (this.config.backend === 'local') return executeLocally(request);
+    if (this.config.backend === 'docker') {
+      const health = await checkDockerHealth();
+      if (health.status === 'docker-not-found' || health.status === 'error') {
         return {
           stdout: '',
-          stderr: `${this.config.backend} backend is not yet implemented.`,
+          stderr:
+            'Local code execution is unavailable because Docker is not running. Start Docker, choose a configured remote sandbox provider, or continue without code execution.',
           exitCode: 1,
           artifacts: [],
           executionTimeMs: 0,
         };
+      }
 
-      default:
+      const imageReady = health.imageReady || (await ensureImage().catch(() => false));
+      if (!imageReady) {
         return {
           stdout: '',
-          stderr: `Unknown backend: ${this.config.backend}`,
+          stderr:
+            'Local code execution is not ready. Build the Larkup sandbox image, choose a configured remote sandbox provider, or continue without code execution.',
           exitCode: 1,
           artifacts: [],
           executionTimeMs: 0,
         };
+      }
+
+      const dockerConfig: DockerConfig = {
+        ...defaultDockerConfig,
+        ...this.config.docker,
+      };
+
+      return executeInDocker(request, dockerConfig);
     }
+
+    const adapter = getSandboxProviderAdapter(this.config.backend);
+    if (!adapter) {
+      return {
+        stdout: '',
+        stderr: `Unknown or unsupported backend: ${this.config.backend}`,
+        exitCode: 1,
+        artifacts: [],
+        executionTimeMs: 0,
+      };
+    }
+    return adapter.execute(request, this.config.credentials ?? {});
+  }
+}
+
+/** Verifies a remote provider's credentials — powers the Settings "Verify" button. */
+export async function verifySandboxProvider(
+  backend: SandboxConfig['backend'],
+  credentials: Record<string, string>,
+): Promise<void> {
+  if (backend === 'local') {
+    const health = await checkLocalRuntime();
+    if (health.status !== 'ready')
+      throw new Error(health.error ?? 'Local runtime is not available.');
+    return;
+  }
+  if (backend === 'docker') {
+    const health = await checkDockerHealth();
+    if (health.status !== 'ready') throw new Error(health.error ?? 'Docker is not available.');
+    return;
   }
+  const adapter = getSandboxProviderAdapter(backend);
+  if (!adapter) throw new Error(`Unknown or unsupported backend: ${backend}`);
+  await adapter.verifyCredentials(credentials);
 }

package/src/types.ts

@@ -1,4 +1,16 @@
-export type SandboxBackend = "docker" | "e2b" | "modal" | "custom";
+export type SandboxBackend =
+  | 'local'
+  | 'docker'
+  | 'e2b'
+  | 'vercel'
+  | 'modal'
+  | 'daytona'
+  | 'browserbase'
+  | 'flyio'
+  | 'northflank'
+  | 'cloudflare'
+  | 'webcontainers'
+  | 'custom';
 
 export interface DockerConfig {
   /** Docker image to use (default: "larkup-sandbox:latest") */
@@ -13,31 +25,26 @@ export interface DockerConfig {
   networkDisabled: boolean;
 }
 
-export interface RemoteConfig {
-  provider: "e2b" | "modal" | "custom";
-  apiKey: string;
-  endpoint?: string;
-}
-
 export interface SandboxConfig {
   backend: SandboxBackend;
   docker?: Partial<DockerConfig>;
-  remote?: RemoteConfig;
+  /**
+   * Credentials for the selected remote provider, keyed by the field `key`s
+   * declared in that provider's `SandboxProviderDescriptor` (see registry.ts).
+   * Unused by local and Docker backends.
+   */
+  credentials?: Record<string, string>;
 }
 
 export const DEFAULT_DOCKER_CONFIG: DockerConfig = {
-  imageName: "larkup-sandbox:latest",
+  imageName: 'larkup-sandbox:latest',
   memoryMB: 512,
   cpuShares: 1024,
   timeoutMs: 30_000,
   networkDisabled: true,
 };
 
-/* ------------------------------------------------------------------ */
-/* Execution request / result                                          */
-/* ------------------------------------------------------------------ */
-
-export type SandboxLanguage = "python" | "javascript" | "typescript";
+export type SandboxLanguage = 'python' | 'javascript' | 'typescript';
 
 export interface SandboxFile {
   /** Filename inside the sandbox (e.g., "data.csv") */
@@ -81,16 +88,14 @@ export interface ExecutionResult {
   executionTimeMs: number;
 }
 
-/* ------------------------------------------------------------------ */
-/* Sandbox status                                                      */
-/* ------------------------------------------------------------------ */
-
 export type SandboxStatus =
-  | "ready"
-  | "docker-not-found"
-  | "image-not-found"
-  | "building-image"
-  | "error";
+  | 'ready'
+  | 'docker-not-found'
+  | 'image-not-found'
+  | 'building-image'
+  | 'missing-credentials'
+  | 'unsupported'
+  | 'error';
 
 export interface SandboxHealthCheck {
   status: SandboxStatus;
@@ -99,3 +104,56 @@ export interface SandboxHealthCheck {
   imageReady?: boolean;
   error?: string;
 }
+
+export type SandboxFieldType = 'text' | 'password';
+
+/** A single credential/config field a sandbox provider needs. The Settings
+ * UI renders these dynamically per provider, the same way vector store and
+ * embedding provider fields are rendered from their own registries. */
+export interface SandboxCredentialField {
+  key: string;
+  label: string;
+  type: SandboxFieldType;
+  required: boolean;
+  placeholder?: string;
+  help?: string;
+  secret?: boolean;
+}
+
+export interface SandboxProviderDescriptor {
+  id: SandboxBackend;
+  label: string;
+  description: string;
+  /** npm package this adapter dynamically imports at runtime. Never a hard
+   * dependency of @larkup/sandbox — installing all nine SDKs unconditionally
+   * would bloat every consumer, so each adapter lazy-imports its own. */
+  sdkPackage?: string;
+  docsUrl: string;
+  /** Path under /public/icons (or /public) in the web app. */
+  icon: string;
+  /**
+   * Whether `execute()` genuinely runs arbitrary code/commands and returns
+   * output, or the provider is architecturally something else (browser
+   * automation, a client-only runtime, a Worker binding). Surfaced in the
+   * UI so operators don't pick a provider that can't do what they expect.
+   */
+  executionSupport: 'full' | 'unsupported';
+  /** Shown in the UI when executionSupport !== "full". */
+  executionCaveat?: string;
+  fields: SandboxCredentialField[];
+}
+
+/**
+ * Adapter contract every remote sandbox backend implements. Docker is
+ * handled separately (docker-runner.ts) since it talks to the local daemon
+ * and needs no credentials.
+ */
+export interface SandboxProviderAdapter {
+  readonly id: SandboxBackend;
+  /** Cheap call that proves the credentials are valid — powers the "Verify" button. */
+  verifyCredentials(credentials: Record<string, string>): Promise<void>;
+  /** Confirms the backend is reachable/configured without spinning up a full sandbox. */
+  healthCheck(credentials: Record<string, string>): Promise<SandboxHealthCheck>;
+  /** Runs code/commands inside a fresh sandbox instance and tears it down afterward. */
+  execute(request: ExecutionRequest, credentials: Record<string, string>): Promise<ExecutionResult>;
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    exclude: ['node_modules/**'],
+    environment: 'node',
+  },
+});