@larkup/sandbox 0.1.1

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @larkup/sandbox — Main entry point.
+ *
+ * Re-exports the public API for the sandbox package.
+ */
+export { SandboxManager } from './sandbox-manager.js';
+export { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';

package/dist/sandbox-manager.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+import type { SandboxConfig, ExecutionRequest, ExecutionResult, SandboxHealthCheck } from './types.js';
+export declare class SandboxManager {
+    private config;
+    constructor(config?: Partial<SandboxConfig>);
+    /** Check if the sandbox backend is available and ready. */
+    healthCheck(): Promise<SandboxHealthCheck>;
+    /** Set up the sandbox backend (e.g., build Docker image). */
+    setup(onProgress?: (msg: string) => void): Promise<void>;
+    /** Execute code in the sandbox. */
+    execute(request: ExecutionRequest): Promise<ExecutionResult>;
+}

package/dist/sandbox-manager.js

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+import { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';
+const defaultDockerConfig = {
+    imageName: 'larkup-sandbox:latest',
+    memoryMB: 512,
+    cpuShares: 1024,
+    timeoutMs: 30_000,
+    networkDisabled: true,
+};
+export class SandboxManager {
+    config;
+    constructor(config) {
+        this.config = {
+            backend: config?.backend ?? 'docker',
+            docker: config?.docker,
+            remote: config?.remote,
+        };
+    }
+    /** Check if the sandbox backend is available and ready. */
+    async healthCheck() {
+        switch (this.config.backend) {
+            case '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}`,
+                };
+        }
+    }
+    /** Set up the sandbox backend (e.g., build Docker image). */
+    async setup(onProgress) {
+        switch (this.config.backend) {
+            case 'docker':
+                await buildSandboxImage(onProgress);
+                break;
+            default:
+                throw new Error(`Setup not supported for backend: ${this.config.backend}`);
+        }
+    }
+    /** Execute code in the sandbox. */
+    async execute(request) {
+        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 = {
+                    ...defaultDockerConfig,
+                    ...this.config.docker,
+                };
+                return executeInDocker(request, dockerConfig);
+            }
+            case 'e2b':
+            case 'modal':
+            case 'custom':
+                return {
+                    stdout: '',
+                    stderr: `${this.config.backend} backend is not yet implemented.`,
+                    exitCode: 1,
+                    artifacts: [],
+                    executionTimeMs: 0,
+                };
+            default:
+                return {
+                    stdout: '',
+                    stderr: `Unknown backend: ${this.config.backend}`,
+                    exitCode: 1,
+                    artifacts: [],
+                    executionTimeMs: 0,
+                };
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export type SandboxBackend = "docker" | "e2b" | "modal" | "custom";
+export interface DockerConfig {
+    /** Docker image to use (default: "larkup-sandbox:latest") */
+    imageName: string;
+    /** Memory limit in MB (default: 512) */
+    memoryMB: number;
+    /** CPU shares (default: 1024 = 1 core) */
+    cpuShares: number;
+    /** Max execution time in ms (default: 30000) */
+    timeoutMs: number;
+    /** 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;
+}
+export declare const DEFAULT_DOCKER_CONFIG: DockerConfig;
+export type SandboxLanguage = "python" | "javascript" | "typescript";
+export interface SandboxFile {
+    /** Filename inside the sandbox (e.g., "data.csv") */
+    name: string;
+    /** File content as a string (text) or base64 (binary) */
+    content: string;
+    /** Whether content is base64-encoded (default: false) */
+    isBase64?: boolean;
+}
+export interface ExecutionRequest {
+    /** Code to execute */
+    code: string;
+    /** Programming language */
+    language: SandboxLanguage;
+    /** Files to mount into the sandbox working directory */
+    files?: SandboxFile[];
+    /** Max execution time in ms (overrides config default) */
+    timeout?: number;
+}
+export interface ExecutionArtifact {
+    /** Filename of the generated artifact */
+    name: string;
+    /** MIME type (e.g., "image/png", "text/csv") */
+    mimeType: string;
+    /** Content as base64-encoded string */
+    data: string;
+}
+export interface ExecutionResult {
+    /** Standard output from the execution */
+    stdout: string;
+    /** Standard error output */
+    stderr: string;
+    /** Process exit code (0 = success) */
+    exitCode: number;
+    /** Generated files (charts, CSVs, etc.) */
+    artifacts: ExecutionArtifact[];
+    /** Wall-clock execution time in ms */
+    executionTimeMs: number;
+}
+export type SandboxStatus = "ready" | "docker-not-found" | "image-not-found" | "building-image" | "error";
+export interface SandboxHealthCheck {
+    status: SandboxStatus;
+    backend: SandboxBackend;
+    dockerVersion?: string;
+    imageReady?: boolean;
+    error?: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_DOCKER_CONFIG = {
+    imageName: "larkup-sandbox:latest",
+    memoryMB: 512,
+    cpuShares: 1024,
+    timeoutMs: 30_000,
+    networkDisabled: true,
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@larkup/sandbox",
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./docker-runner": {
+      "types": "./dist/docker-runner.d.ts",
+      "import": "./dist/docker-runner.js",
+      "default": "./dist/docker-runner.js"
+    },
+    "./sandbox-manager": {
+      "types": "./dist/sandbox-manager.d.ts",
+      "import": "./dist/sandbox-manager.js",
+      "default": "./dist/sandbox-manager.js"
+    }
+  },
+  "dependencies": {
+    "dockerode": "^4.0.7"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.38",
+    "typescript": "5.7.3"
+  },
+  "scripts": {
+    "build": "tsc --outDir dist",
+    "type-check": "tsc --noEmit"
+  }
+}