@larkup/sandbox 0.1.1 → 0.1.3

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-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") */
     imageName: string;
@@ -11,18 +11,18 @@ export interface DockerConfig {
     /** Disable network access in the container (default: true) */
     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 declare const DEFAULT_DOCKER_CONFIG: DockerConfig;
-export type SandboxLanguage = "python" | "javascript" | "typescript";
+export type SandboxLanguage = 'python' | 'javascript' | 'typescript';
 export interface SandboxFile {
     /** Filename inside the sandbox (e.g., "data.csv") */
     name: string;
@@ -61,7 +61,7 @@ export interface ExecutionResult {
     /** Wall-clock execution time in ms */
     executionTimeMs: number;
 }
-export type SandboxStatus = "ready" | "docker-not-found" | "image-not-found" | "building-image" | "error";
+export type SandboxStatus = 'ready' | 'docker-not-found' | 'image-not-found' | 'building-image' | 'missing-credentials' | 'unsupported' | 'error';
 export interface SandboxHealthCheck {
     status: SandboxStatus;
     backend: SandboxBackend;
@@ -69,3 +69,52 @@ 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/dist/types.js

@@ -1,5 +1,5 @@
 export const DEFAULT_DOCKER_CONFIG = {
-    imageName: "larkup-sandbox:latest",
+    imageName: 'larkup-sandbox:latest',
     memoryMB: 512,
     cpuShares: 1024,
     timeoutMs: 30_000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larkup/sandbox",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "publishConfig": {
     "access": "public"
   },
@@ -27,17 +27,34 @@
       "types": "./dist/sandbox-manager.d.ts",
       "import": "./dist/sandbox-manager.js",
       "default": "./dist/sandbox-manager.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "default": "./dist/registry.js"
     }
   },
   "dependencies": {
-    "dockerode": "^4.0.7"
+    "dockerode": "^5.0.1"
+  },
+  "optionalDependencies": {
+    "e2b": "^2.39.0",
+    "@vercel/sandbox": "^3.0.0",
+    "modal": "^0.9.0",
+    "@daytonaio/sdk": "^0.204.1",
+    "@browserbasehq/sdk": "^2.17.0",
+    "playwright-core": "^1.62.1",
+    "@fly/sprites": "^0.2.0",
+    "@northflank/js-client": "^0.10.1"
   },
   "devDependencies": {
-    "@types/dockerode": "^3.3.38",
-    "typescript": "5.7.3"
+    "@types/dockerode": "^4.0.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "tsc --outDir dist",
-    "type-check": "tsc --noEmit"
+    "build": "tsc -p tsconfig.build.json --outDir dist",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/docker-runner.ts

@@ -6,7 +6,6 @@
  * generated files, then auto-removes the container.
  */
 
-import Docker from 'dockerode';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -25,21 +24,20 @@ const OUTPUT_DIR = '/sandbox/output';
 const INPUT_DIR = '/sandbox/input';
 const DOCKERFILE_DIR = path.join(import.meta.dirname ?? __dirname, '..');
 
-let dockerInstance: Docker | null = null;
+let dockerInstance: any | null = null;
 
-function getDocker(): Docker {
+async function getDocker(): Promise<any> {
   if (!dockerInstance) {
+    // Dynamic import prevents Turbopack from statically bundling dockerode
+    // and mangling its module name with a hash suffix.
+    const { default: Docker } = await import(/* turbopackIgnore: true */ 'dockerode');
     dockerInstance = new Docker();
   }
   return dockerInstance;
 }
 
-/* ------------------------------------------------------------------ */
-/* Health check                                                        */
-/* ------------------------------------------------------------------ */
-
 export async function checkDockerHealth(): Promise<SandboxHealthCheck> {
-  const docker = getDocker();
+  const docker = await getDocker();
   try {
     const info = await docker.version();
     const images = await docker.listImages({
@@ -52,20 +50,21 @@ export async function checkDockerHealth(): Promise<SandboxHealthCheck> {
       imageReady: images.length > 0,
     };
   } catch (err: any) {
+    const raw = err?.message ?? '';
+    const dockerMissing =
+      /ENOENT|ECONNREFUSED|EACCES|no such file|cannot connect to the docker daemon/i.test(raw);
     return {
       status: 'docker-not-found',
       backend: 'docker',
-      error: err.message ?? 'Docker daemon not available',
+      error: dockerMissing
+        ? "Docker isn't installed or running on this machine. Local code execution is optional — install Docker Desktop to enable it, or configure a remote sandbox provider below."
+        : raw || 'Docker daemon not available',
     };
   }
 }
 
-/* ------------------------------------------------------------------ */
-/* Image management                                                    */
-/* ------------------------------------------------------------------ */
-
 export async function buildSandboxImage(onProgress?: (msg: string) => void): Promise<void> {
-  const docker = getDocker();
+  const docker = await getDocker();
   const dockerfilePath = path.join(DOCKERFILE_DIR, 'Dockerfile');
 
   // Check if Dockerfile exists in the package
@@ -105,7 +104,7 @@ export async function buildSandboxImage(onProgress?: (msg: string) => void): Pro
 }
 
 export async function ensureImage(): Promise<boolean> {
-  const docker = getDocker();
+  const docker = await getDocker();
   const images = await docker.listImages({
     filters: { reference: [SANDBOX_IMAGE] },
   });
@@ -119,10 +118,6 @@ export async function ensureImage(): Promise<boolean> {
   }
 }
 
-/* ------------------------------------------------------------------ */
-/* Code execution                                                      */
-/* ------------------------------------------------------------------ */
-
 /**
  * Build the Python wrapper script that:
  * 1. Sets up pandas compatibility shims to handle deprecated APIs
@@ -279,7 +274,7 @@ export async function executeInDocker(
   request: ExecutionRequest,
   config: DockerConfig,
 ): Promise<ExecutionResult> {
-  const docker = getDocker();
+  const docker = await getDocker();
   const startTime = Date.now();
 
   // Create a temporary directory for input files
@@ -292,6 +287,22 @@ export async function executeInDocker(
   // Write input files
   if (request.files) {
     for (const file of request.files) {
+      if (
+        !file.name ||
+        file.name === '.' ||
+        file.name === '..' ||
+        file.name.includes('/') ||
+        file.name.includes('\\') ||
+        file.name.includes('\0')
+      ) {
+        return {
+          stdout: '',
+          stderr: 'Sandbox file names must be plain file names.',
+          exitCode: 1,
+          artifacts: [],
+          executionTimeMs: Date.now() - startTime,
+        };
+      }
       const filePath = path.join(inputDir, file.name);
       if (file.isBase64) {
         await fs.writeFile(filePath, Buffer.from(file.content, 'base64'));
@@ -304,22 +315,25 @@ export async function executeInDocker(
   // Prepare the execution code
   let execCode: string;
   let cmd: string[];
+  let scriptName: string;
 
   if (request.language === 'python') {
     execCode = wrapPythonCode(request.code);
     const scriptPath = path.join(tmpDir, 'run.py');
     await fs.writeFile(scriptPath, execCode, 'utf8');
+    scriptName = 'run.py';
     cmd = ['python3', '/sandbox/run.py'];
   } else {
     // JavaScript/TypeScript (future)
     const scriptPath = path.join(tmpDir, 'run.js');
     await fs.writeFile(scriptPath, request.code, 'utf8');
+    scriptName = 'run.js';
     cmd = ['node', '/sandbox/run.js'];
   }
 
   const timeout = request.timeout ?? config.timeoutMs;
 
-  let container: Docker.Container | null = null;
+  let container: any | null = null;
   try {
     container = await docker.createContainer({
       Image: config.imageName,
@@ -334,7 +348,7 @@ export async function executeInDocker(
         Binds: [
           `${inputDir}:${INPUT_DIR}:ro`,
           `${outputDir}:${OUTPUT_DIR}:rw`,
-          `${tmpDir}/run.py:/sandbox/run.py:ro`,
+          `${tmpDir}/${scriptName}:/sandbox/${scriptName}:ro`,
         ],
         ReadonlyRootfs: false,
       },
@@ -347,8 +361,9 @@ export async function executeInDocker(
 
     // Wait for completion with timeout
     const waitPromise = container.wait();
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
     const timeoutPromise = new Promise<never>((_, reject) => {
-      setTimeout(async () => {
+      timeoutHandle = setTimeout(async () => {
         try {
           await container?.kill();
         } catch {
@@ -359,6 +374,7 @@ export async function executeInDocker(
     });
 
     const result = await Promise.race([waitPromise, timeoutPromise]);
+    if (timeoutHandle) clearTimeout(timeoutHandle);
 
     // Capture logs
     const logs = await container.logs({
@@ -423,10 +439,6 @@ export async function executeInDocker(
   }
 }
 
-/* ------------------------------------------------------------------ */
-/* Helpers                                                             */
-/* ------------------------------------------------------------------ */
-
 /**
  * Docker multiplexes stdout/stderr into a single stream with 8-byte headers.
  * Header format: [type(1)][0(3)][size(4)] where type: 1=stdout, 2=stderr

package/src/index.ts

@@ -4,18 +4,24 @@
  * Re-exports the public API for the sandbox package.
  */
 
-export { SandboxManager } from './sandbox-manager.js';
+export { SandboxManager, verifySandboxProvider } from './sandbox-manager.js';
 export {
   checkDockerHealth,
   buildSandboxImage,
   ensureImage,
   executeInDocker,
 } from './docker-runner.js';
+export { checkLocalRuntime, executeLocally } from './local-runner.js';
+export {
+  SANDBOX_PROVIDERS,
+  SANDBOX_PROVIDER_LIST,
+  getSandboxProvider,
+  validateSandboxCredentials,
+} from './registry.js';
 export type {
   SandboxBackend,
   SandboxConfig,
   DockerConfig,
-  RemoteConfig,
   SandboxLanguage,
   SandboxFile,
   ExecutionRequest,
@@ -23,4 +29,7 @@ export type {
   ExecutionArtifact,
   SandboxStatus,
   SandboxHealthCheck,
+  SandboxCredentialField,
+  SandboxProviderDescriptor,
+  SandboxProviderAdapter,
 } from './types.js';

package/src/local-runner.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { executeLocally } from './local-runner.js';
+
+describe('executeLocally', () => {
+  it('runs JavaScript without Docker and returns output artifacts', async () => {
+    const result = await executeLocally({
+      language: 'javascript',
+      code: `
+        const fs = require('node:fs/promises');
+        void (async () => {
+          await fs.writeFile(process.env.LARKUP_OUTPUT_DIR + '/result.txt', 'done');
+          console.log('local runtime');
+        })();
+      `,
+    });
+
+    expect(result).toMatchObject({ exitCode: 0, stdout: expect.stringContaining('local runtime') });
+    expect(result.artifacts).toEqual([
+      expect.objectContaining({ name: 'result.txt', mimeType: 'text/plain' }),
+    ]);
+  });
+});

package/src/local-runner.ts

@@ -0,0 +1,199 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import type { EventEmitter } from 'node:events';
+import type {
+  ExecutionArtifact,
+  ExecutionRequest,
+  ExecutionResult,
+  SandboxHealthCheck,
+} from './types.js';
+import { getMimeType } from './mime.js';
+
+type Command = { executable: string; args: string[] };
+
+let pythonCommand: Command | null | undefined;
+
+function run(command: Command, args: string[], cwd?: string, timeoutMs = 10_000) {
+  return new Promise<{ stdout: string; stderr: string; exitCode: number }>((resolve, reject) => {
+    const child = spawn(command.executable, [...command.args, ...args], {
+      cwd,
+      env: process.env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // Node ChildProcess is an EventEmitter at runtime. TypeScript 7's narrowed stdio return type
+    // omits that inherited surface, so retain it explicitly for lifecycle events.
+    const lifecycle = child as unknown as EventEmitter;
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => {
+      stdout = (stdout + chunk).slice(-1_000_000);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = (stderr + chunk).slice(-1_000_000);
+    });
+    lifecycle.once('error', (error: Error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    lifecycle.once('close', (code: number | null) => {
+      clearTimeout(timer);
+      resolve({
+        stdout,
+        stderr: timedOut ? `${stderr}\nExecution timed out.`.trim() : stderr,
+        exitCode: timedOut ? 124 : code ?? 1,
+      });
+    });
+  });
+}
+
+async function resolvePython(): Promise<Command | null> {
+  if (pythonCommand !== undefined) return pythonCommand;
+  const candidates: Command[] = process.env.LARKUP_PYTHON
+    ? [{ executable: process.env.LARKUP_PYTHON, args: [] }]
+    : process.platform === 'win32'
+    ? [
+        { executable: 'py', args: ['-3'] },
+        { executable: 'python', args: [] },
+      ]
+    : [
+        { executable: 'python3', args: [] },
+        { executable: 'python', args: [] },
+      ];
+
+  for (const candidate of candidates) {
+    try {
+      if ((await run(candidate, ['--version'])).exitCode === 0) {
+        pythonCommand = candidate;
+        return candidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+  pythonCommand = null;
+  return null;
+}
+
+function assertSafeFileName(name: string) {
+  if (!name || name === '.' || name === '..' || /[\\/\0]/.test(name)) {
+    throw new Error('Sandbox file names must be plain file names.');
+  }
+}
+
+function pythonWrapper(code: string, outputDir: string) {
+  return `import base64, os, sys, traceback
+os.makedirs(${JSON.stringify(outputDir)}, exist_ok=True)
+os.environ.setdefault('MPLBACKEND', 'Agg')
+try:
+    import numpy as np
+    import pandas as pd
+except ImportError:
+    pass
+try:
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    def _save_figures(*args, **kwargs):
+        for i, number in enumerate(plt.get_fignums()):
+            plt.figure(number).savefig(os.path.join(${JSON.stringify(
+              outputDir,
+            )}, f'chart_{i}.png'), dpi=150, bbox_inches='tight')
+        plt.close('all')
+    plt.show = _save_figures
+except ImportError:
+    pass
+try:
+    exec(compile(base64.b64decode(${JSON.stringify(
+      Buffer.from(code).toString('base64'),
+    )}), 'analysis.py', 'exec'))
+    if 'plt' in globals() and plt.get_fignums():
+        plt.show()
+except Exception as error:
+    traceback.print_exception(error, file=sys.stderr)
+    sys.exit(1)
+`;
+}
+
+/** Checks whether the host can run Python analysis without Docker. */
+export async function checkLocalRuntime(): Promise<SandboxHealthCheck> {
+  const python = await resolvePython();
+  if (!python) {
+    return {
+      status: 'error',
+      backend: 'local',
+      error:
+        'Local code execution needs Python 3. Install Python or choose Docker or a remote sandbox provider.',
+    };
+  }
+  return { status: 'ready', backend: 'local' };
+}
+
+/** Executes trusted code in a temporary host workspace and collects its output. */
+export async function executeLocally(request: ExecutionRequest): Promise<ExecutionResult> {
+  const startTime = Date.now();
+  const tempDir = path.join(os.tmpdir(), `larkup-local-${randomUUID()}`);
+  const inputDir = path.join(tempDir, 'input');
+  const outputDir = path.join(tempDir, 'output');
+  try {
+    await fs.mkdir(inputDir, { recursive: true });
+    await fs.mkdir(outputDir, { recursive: true });
+    for (const file of request.files ?? []) {
+      assertSafeFileName(file.name);
+      await fs.writeFile(
+        path.join(inputDir, file.name),
+        file.isBase64 ? Buffer.from(file.content, 'base64') : file.content,
+      );
+    }
+
+    const isPython = request.language === 'python';
+    const command = isPython ? await resolvePython() : { executable: process.execPath, args: [] };
+    if (!command) {
+      return {
+        stdout: '',
+        stderr:
+          'Local code execution needs Python 3. Install Python or choose Docker or a remote sandbox provider.',
+        exitCode: 1,
+        artifacts: [],
+        executionTimeMs: Date.now() - startTime,
+      };
+    }
+
+    const script = path.join(tempDir, isPython ? 'run.py' : 'run.js');
+    const source = isPython
+      ? pythonWrapper(request.code, outputDir)
+      : `process.env.LARKUP_OUTPUT_DIR = ${JSON.stringify(outputDir)};\n${request.code}`;
+    await fs.writeFile(script, source, 'utf8');
+    const result = await run(command, [script], inputDir, request.timeout ?? 30_000);
+    const artifacts: ExecutionArtifact[] = [];
+    for (const name of await fs.readdir(outputDir).catch(() => [])) {
+      const filePath = path.join(outputDir, name);
+      const stat = await fs.stat(filePath).catch(() => null);
+      if (!stat?.isFile()) continue;
+      artifacts.push({
+        name,
+        mimeType: getMimeType(name),
+        data: (await fs.readFile(filePath)).toString('base64'),
+      });
+    }
+    return { ...result, artifacts, executionTimeMs: Date.now() - startTime };
+  } catch (error) {
+    return {
+      stdout: '',
+      stderr: error instanceof Error ? error.message : 'Local execution failed.',
+      exitCode: 1,
+      artifacts: [],
+      executionTimeMs: Date.now() - startTime,
+    };
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/mime.ts

@@ -0,0 +1,17 @@
+const MIME_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  svg: 'image/svg+xml',
+  gif: 'image/gif',
+  csv: 'text/csv',
+  json: 'application/json',
+  txt: 'text/plain',
+  html: 'text/html',
+  pdf: 'application/pdf',
+};
+
+export function getMimeType(filename: string): string {
+  const ext = filename.slice(filename.lastIndexOf('.') + 1).toLowerCase();
+  return MIME_TYPES[ext] ?? 'application/octet-stream';
+}

package/src/providers/browserbase.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+const listMock = vi.fn();
+
+vi.mock('@browserbasehq/sdk', () => ({
+  default: vi.fn().mockImplementation(function () {
+    return { projects: { list: listMock } };
+  }),
+}));
+
+const { browserbaseAdapter } = await import('./browserbase.js');
+
+beforeEach(() => {
+  listMock.mockReset();
+});
+
+describe('browserbaseAdapter.execute', () => {
+  it('always fails fast — Browserbase is browser automation, not a code-execution sandbox', async () => {
+    const result = await browserbaseAdapter.execute({ code: 'print(1)', language: 'python' }, {
+      apiKey: 'k',
+      projectId: 'p',
+    });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('Playwright/Puppeteer');
+    expect(listMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('browserbaseAdapter.verifyCredentials', () => {
+  it('requires both apiKey and projectId', async () => {
+    await expect(browserbaseAdapter.verifyCredentials({ apiKey: 'k' })).rejects.toThrow(
+      'Browserbase API key and project ID are both required.',
+    );
+  });
+
+  it('checks that the project is visible to the API key', async () => {
+    listMock.mockResolvedValue([{ id: 'other-project' }]);
+    await expect(browserbaseAdapter.verifyCredentials({ apiKey: 'k', projectId: 'p' })).rejects.toThrow(
+      'cannot see the given Browserbase project ID',
+    );
+  });
+
+  it('succeeds when the project ID is in the returned list', async () => {
+    listMock.mockResolvedValue([{ id: 'p' }]);
+    await expect(browserbaseAdapter.verifyCredentials({ apiKey: 'k', projectId: 'p' })).resolves.toBeUndefined();
+  });
+});
+
+describe('browserbaseAdapter.healthCheck', () => {
+  it('reports status "unsupported" even when credentials are valid', async () => {
+    listMock.mockResolvedValue([{ id: 'p' }]);
+    const result = await browserbaseAdapter.healthCheck({ apiKey: 'k', projectId: 'p' });
+    expect(result.status).toBe('unsupported');
+  });
+});