@sandboxxjs/core 0.5.0 → 2.0.0

package/dist/index.d.ts

@@ -1,327 +1,26 @@
-import { WithState, StateLog } from "@sandboxxjs/state";
-type IsolatorType = "none" | "srt" | "cloudflare" | "e2b";
-type RuntimeType = "node" | "python";
-interface StateConfig {
-	/** Simple environment variable initialization */
-	env?: Record<string, string>;
-	/** Initialize state from StateLog */
-	initializeLog?: StateLog;
-	/** Enable state recording */
-	enableRecord?: boolean;
-	/** Store type (default: resourcex, test: memory) */
-	store?: "resourcex" | "memory";
-}
-interface SandboxConfig {
-	/** Isolator type */
-	isolator: IsolatorType;
-	/** Runtime type */
-	runtime: RuntimeType;
-	/** Resource limits */
-	limits?: ResourceLimits;
-	/** State configuration */
-	state?: StateConfig;
-	/** Node-specific configuration */
-	node?: NodeConfig;
-	/** Python-specific configuration */
-	python?: PythonConfig;
-}
-interface ResourceLimits {
-	/** Timeout in milliseconds */
-	timeout?: number;
-	/** Memory limit in bytes */
-	memory?: number;
-	/** CPU limit as percentage */
-	cpu?: number;
-}
-interface NodeConfig {
-	/** Package manager */
-	packageManager?: "npm" | "yarn" | "pnpm" | "bun";
-	/** Node version */
-	version?: string;
-}
-interface PythonConfig {
-	/** Python version */
-	version?: string;
-	/** Whether to use virtual environment */
-	useVenv?: boolean;
-}
 /**
-* Base Sandbox interface - core APIs
-*/
-interface Sandbox {
-	/** Unique sandbox ID */
-	readonly id: string;
-	/** Execute shell command */
-	shell(command: string): Promise<ShellResult>;
-	/** Execute code (script mode - stdout) */
-	execute(code: string): Promise<ExecuteResult>;
-	/** Evaluate expression (REPL mode - return value) */
-	evaluate(expr: string): Promise<EvaluateResult>;
-	/** Upload file to sandbox */
-	upload(data: Buffer, remotePath: string): Promise<void>;
-	/** Download file from sandbox */
-	download(remotePath: string): Promise<Buffer>;
-	/** Destroy sandbox */
-	destroy(): Promise<void>;
-}
-/**
-* Shell execution result
-*/
-interface ShellResult {
-	/** Whether execution succeeded */
-	success: boolean;
-	/** Standard output */
-	stdout: string;
-	/** Standard error */
-	stderr: string;
-	/** Exit code */
-	exitCode: number;
-	/** Execution time in milliseconds */
-	executionTime: number;
-}
-/**
-* Code execution result (same as ShellResult)
-*/
-interface ExecuteResult {
-	/** Whether execution succeeded */
-	success: boolean;
-	/** Standard output */
-	stdout: string;
-	/** Standard error */
-	stderr: string;
-	/** Exit code */
-	exitCode: number;
-	/** Execution time in milliseconds */
-	executionTime: number;
-}
-/**
-* Expression evaluation result
-*/
-interface EvaluateResult {
-	/** Expression result value (as string) */
-	value: string;
-	/** Execution time in milliseconds */
-	executionTime: number;
-}
-/** Sandbox with State (fs, env, storage) */
-type StateSandbox = Sandbox & WithState;
-/** Sandbox constructor type */
-type SandboxConstructor<T extends Sandbox = Sandbox> = new (config: SandboxConfig) => T;
-interface IsolatorOptions {
-	timeout?: number;
-	env?: Record<string, string>;
-}
-declare abstract class Isolator {
-	protected runtime: RuntimeType;
-	constructor(runtime: RuntimeType);
-	/**
-	* Execute code (script mode - stdout)
-	* Command depends on runtime: node -e / python3 -c
-	*/
-	abstract execute(code: string, options?: IsolatorOptions): Promise<ExecuteResult>;
-	/**
-	* Evaluate expression (REPL mode - return value)
-	* Command depends on runtime: node -p / python3 -c 'print(...)'
-	*/
-	abstract evaluate(expr: string, options?: IsolatorOptions): Promise<EvaluateResult>;
-	/**
-	* Upload file to isolated environment
-	*/
-	abstract upload(data: Buffer, remotePath: string): Promise<void>;
-	/**
-	* Download file from isolated environment
-	*/
-	abstract download(remotePath: string): Promise<Buffer>;
-	/**
-	* Destroy isolator and cleanup resources
-	*/
-	abstract destroy(): Promise<void>;
-}
-declare class BaseSandbox implements Sandbox {
-	readonly id: string;
-	protected isolator: Isolator;
-	protected config: SandboxConfig;
-	constructor(config: SandboxConfig);
-	private createIsolator;
-	/**
-	* Execute shell command
-	*/
-	shell(command: string): Promise<ShellResult>;
-	/**
-	* Execute code (script mode)
-	*/
-	execute(code: string): Promise<ExecuteResult>;
-	/**
-	* Evaluate expression (REPL mode)
-	*/
-	evaluate(expr: string): Promise<EvaluateResult>;
-	/**
-	* Upload file to sandbox
-	*/
-	upload(data: Buffer, remotePath: string): Promise<void>;
-	/**
-	* Download file from sandbox
-	*/
-	download(remotePath: string): Promise<Buffer>;
-	/**
-	* Destroy sandbox and cleanup resources
-	*/
-	destroy(): Promise<void>;
-}
-declare class NoneIsolator extends Isolator {
-	private workDir;
-	constructor(runtime: RuntimeType);
-	/**
-	* Execute shell command
-	*/
-	shell(command: string, options?: IsolatorOptions): Promise<ShellResult>;
-	/**
-	* Execute code (script mode)
-	*/
-	execute(code: string, options?: IsolatorOptions): Promise<ExecuteResult>;
-	/**
-	* Evaluate expression (REPL mode)
-	*/
-	evaluate(expr: string, options?: IsolatorOptions): Promise<EvaluateResult>;
-	/**
-	* Build execute command based on runtime
-	*/
-	private buildExecuteCommand;
-	/**
-	* Build evaluate command based on runtime
-	*/
-	private buildEvaluateCommand;
-	/**
-	* Run command in work directory
-	*/
-	private runCommand;
-	/**
-	* Upload file to sandbox
-	*/
-	upload(data: Buffer, remotePath: string): Promise<void>;
-	/**
-	* Download file from sandbox
-	*/
-	download(remotePath: string): Promise<Buffer>;
-	/**
-	* Destroy isolator and cleanup
-	*/
-	destroy(): Promise<void>;
-}
-declare class SrtIsolator extends Isolator {
-	private workDir;
-	private initialized;
-	constructor(runtime: RuntimeType);
-	/**
-	* Initialize SandboxManager if not already initialized
-	*/
-	private ensureInitialized;
-	/**
-	* Execute shell command with srt isolation
-	*/
-	shell(command: string, options?: IsolatorOptions): Promise<ShellResult>;
-	/**
-	* Execute code (script mode) with srt isolation
-	*/
-	execute(code: string, options?: IsolatorOptions): Promise<ExecuteResult>;
-	/**
-	* Evaluate expression (REPL mode) with srt isolation
-	*/
-	evaluate(expr: string, options?: IsolatorOptions): Promise<EvaluateResult>;
-	/**
-	* Build execute command based on runtime
-	*/
-	private buildExecuteCommand;
-	/**
-	* Build evaluate command based on runtime
-	*/
-	private buildEvaluateCommand;
-	/**
-	* Run command with srt sandbox wrapper
-	*/
-	private runCommand;
-	/**
-	* Upload file to sandbox
-	*/
-	upload(data: Buffer, remotePath: string): Promise<void>;
-	/**
-	* Download file from sandbox
-	*/
-	download(remotePath: string): Promise<Buffer>;
-	/**
-	* Destroy isolator and cleanup
-	*/
-	destroy(): Promise<void>;
-}
-declare class CloudflareContainerIsolator extends Isolator {
-	private serverProcess?;
-	private serverUrl?;
-	private isReady;
-	constructor(runtime: RuntimeType);
-	/**
-	* Find an available port
-	*/
-	private findFreePort;
-	/**
-	* Get binary path from installed package
-	*/
-	private getBinaryPath;
-	/**
-	* Wait for server to be ready
-	*/
-	private waitForReady;
-	/**
-	* Ensure server is running
-	*/
-	private ensureServerRunning;
-	/**
-	* Execute shell command
-	*/
-	shell(command: string, options?: IsolatorOptions): Promise<ShellResult>;
-	/**
-	* Execute code (script mode)
-	*/
-	execute(code: string, options?: IsolatorOptions): Promise<ExecuteResult>;
-	/**
-	* Evaluate expression (REPL mode)
-	*/
-	evaluate(expr: string, options?: IsolatorOptions): Promise<EvaluateResult>;
-	/**
-	* Call server to execute command
-	*/
-	private callServer;
-	/**
-	* Upload file to sandbox
-	*/
-	upload(_data: Buffer, _remotePath: string): Promise<void>;
-	/**
-	* Download file from sandbox
-	*/
-	download(_remotePath: string): Promise<Buffer>;
-	/**
-	* Destroy isolator and cleanup
-	*/
-	destroy(): Promise<void>;
-}
-import { StateFS, StateEnv, StateStorage, buildStateLog, loadStateLog, StateLog as StateLog2, StateLogEntry, FileSystem, Environment, Storage, WithState as WithState3, StateError, FileSystemError } from "@sandboxxjs/state";
-import { WithState as WithState2 } from "@sandboxxjs/state";
-/**
-* Add state capabilities to sandbox
-*/
-declare function withState<T extends Sandbox>(Base: SandboxConstructor<T>): SandboxConstructor<T & WithState2>;
-/**
-* Error types for SandboX
-*/
-declare class SandboxError extends Error {
-	constructor(message: string);
-}
-declare class ExecutionError extends SandboxError {
-	constructor(message: string);
-}
-declare class TimeoutError extends SandboxError {
-	constructor(message: string);
-}
-declare class IsolationError extends SandboxError {
-	constructor(message: string);
-}
-export { withState, loadStateLog, buildStateLog, WithState3 as WithState, TimeoutError, Storage, StateStorage, StateSandbox, StateLogEntry, StateLog2 as StateLog, StateFS, StateError, StateEnv, StateConfig, SrtIsolator, ShellResult, SandboxError, SandboxConstructor, SandboxConfig, Sandbox, RuntimeType, ResourceLimits, PythonConfig, NoneIsolator, NodeConfig, IsolatorType, Isolator, IsolationError, FileSystemError, FileSystem, ExecutionError, ExecuteResult, EvaluateResult, Environment, CloudflareContainerIsolator, BaseSandbox };
+ * @sandboxxjs/core — Sandbox abstraction framework.
+ *
+ * Unified lifecycle for any sandbox environment:
+ *
+ *   Allocate → Prepare → Register → Ready → Command
+ *
+ *   1. Allocator provisions resources, returns SandboxContainer (status: pending)
+ *   2. Sandbox environment starts, sandbox-client prepares
+ *   3. sandbox-client connects to Registry via WebSocket, registers
+ *   4. Registry marks sandbox as ready
+ *   5. Router dispatches commands through Registry to sandbox-client
+ *
+ * Platform differences are injected via SandboxProvider:
+ *   - @sandboxxjs/node-provider: child_process + node:fs
+ *   - @sandboxxjs/web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, WASM, etc.
+ */
+export type { AllocateRequest, SandboxAllocator, SandboxContainer, SandboxContainerType, SandboxStatus, } from "./allocator";
+export type { SandboxClient, SandboxClientOptions } from "./client";
+export { createSandboxClient } from "./create-client";
+export type { SandboxExecutor, SandboxFileSystem, SandboxProcessManager, SandboxProvider, } from "./provider";
+export type { SandboxConnection, SandboxRegistry } from "./registry";
+export type { SandboxRouter } from "./router";
+export type { ExecOptions, ExecResult, FileInfo, ProcessInfo, Sandbox } from "./sandbox";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}