@sandboxxjs/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,87 +1,181 @@
-/**
-* Core type definitions for SandboX
-*/
-type Runtime = "bash" | "node" | "python" | "docker";
-type IsolatorType = "local" | "cloudflare" | "e2b" | "firecracker" | "docker";
+import { WithState, StateLog } from "@sandboxxjs/state";
+type IsolatorType = "local" | "cloudflare" | "e2b" | "docker";
+type Runtime = "shell" | "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 {
-	runtime: Runtime;
+	/** Isolator type */
 	isolator: IsolatorType;
+	/** Runtime type (default: shell) */
+	runtime?: Runtime;
+	/** Resource limits */
 	limits?: ResourceLimits;
-	isolation?: IsolationConfig;
+	/** 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 IsolationConfig {
-	networkAccess?: boolean;
-	fileSystemAccess?: boolean;
-	envVars?: Record<string, string>;
+interface NodeConfig {
+	/** Package manager */
+	packageManager?: "npm" | "yarn" | "pnpm" | "bun";
+	/** Node version */
+	version?: string;
 }
-interface ExecuteOptions {
-	code: string;
-	env?: Record<string, string>;
-	timeout?: number;
+interface PythonConfig {
+	/** Python version */
+	version?: string;
+	/** Whether to use virtual environment */
+	useVenv?: boolean;
+}
+/**
+* Base Sandbox interface - 4 core APIs + ID
+*/
+interface Sandbox {
+	/** Unique sandbox ID */
+	readonly id: string;
+	/** Execute shell command */
+	shell(command: string): Promise<ShellResult>;
+	/** 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 capability
+*/
+interface WithExecute {
+	execute(code: string): Promise<ExecuteResult>;
 }
 interface ExecuteResult {
+	/** Whether execution succeeded */
 	success: boolean;
-	data?: unknown;
-	stdout?: string;
-	stderr?: string;
-	error?: string;
-	exitCode?: number;
-	metadata: {
-		executionTime: number
-		timestamp: string
-	};
-}
-interface FileSystem {
-	write(path: string, data: string): Promise<void>;
-	read(path: string): Promise<string>;
-	list(path: string): Promise<string[]>;
-	delete(path: string): Promise<void>;
-	exists(path: string): Promise<boolean>;
-}
-type EventHandler = (...args: unknown[]) => void;
-declare class Sandbox {
-	private isolator;
-	private runtime;
-	private eventHandlers;
-	fs: FileSystem;
-	constructor(config: SandboxConfig);
-	private createIsolator;
-	private createRuntime;
-	execute(options: ExecuteOptions): Promise<ExecuteResult>;
-	writeFile(filePath: string, data: string): Promise<void>;
-	readFile(filePath: string): Promise<string>;
-	destroy(): Promise<void>;
-	on(event: string, handler: EventHandler): void;
-	private emit;
+	/** Standard output */
+	stdout: string;
+	/** Standard error */
+	stderr: string;
+	/** Exit code */
+	exitCode: number;
+	/** Execution time in milliseconds */
+	executionTime: number;
+}
+/** Node sandbox = Base + State + Execute */
+type NodeSandbox = Sandbox & WithState & WithExecute;
+/** Python sandbox = Base + State + Execute */
+type PythonSandbox = Sandbox & WithState & WithExecute;
+/** Sandbox with State only */
+type StateSandbox = Sandbox & WithState;
+/** Sandbox constructor type */
+type SandboxConstructor<T extends Sandbox = Sandbox> = new (config: SandboxConfig) => T;
+/** Mixin function type */
+type SandboxMixin<
+	T extends Sandbox,
+	U
+> = (Base: SandboxConstructor<T>) => SandboxConstructor<T & U>;
+interface ShellOptions {
+	timeout?: number;
+	env?: Record<string, string>;
 }
 declare abstract class Isolator {
-	abstract execute(options: ExecuteOptions): Promise<ExecuteResult>;
-	abstract getFileSystem(): FileSystem;
+	/**
+	* Execute shell command in isolated environment
+	*/
+	abstract shell(command: string, options?: ShellOptions): Promise<ShellResult>;
+	/**
+	* 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>;
+	/**
+	* 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 LocalIsolator extends Isolator {
 	private workDir;
-	private runtime;
-	constructor(runtime?: string);
-	execute(options: ExecuteOptions): Promise<ExecuteResult>;
+	constructor();
 	/**
-	* Build command array based on runtime
+	* Execute shell command
+	*/
+	shell(command: string, options?: ShellOptions): Promise<ShellResult>;
+	/**
+	* Upload file to sandbox
+	*/
+	upload(data: Buffer, remotePath: string): Promise<void>;
+	/**
+	* Download file from sandbox
+	*/
+	download(remotePath: string): Promise<Buffer>;
+	/**
+	* Destroy isolator and cleanup
 	*/
-	private buildCommand;
-	getFileSystem(): FileSystem;
 	destroy(): Promise<void>;
 }
 declare class CloudflareContainerIsolator extends Isolator {
 	private serverProcess?;
 	private serverUrl?;
 	private isReady;
-	private runtime;
-	constructor(runtime?: string);
+	constructor();
 	/**
 	* Find an available port
 	*/
@@ -98,22 +192,37 @@ declare class CloudflareContainerIsolator extends Isolator {
 	* Ensure server is running
 	*/
 	private ensureServerRunning;
-	execute(options: ExecuteOptions): Promise<ExecuteResult>;
-	getFileSystem(): FileSystem;
+	/**
+	* Execute shell command
+	*/
+	shell(command: string, options?: ShellOptions): Promise<ShellResult>;
+	/**
+	* 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 abstract class Runtime2 {
-	abstract execute(options: ExecuteOptions): Promise<ExecuteResult>;
-	abstract prepare(): Promise<void>;
-	abstract cleanup(): Promise<void>;
-}
-declare class GenericRuntime extends Runtime2 {
-	private isolator;
-	constructor(isolator: Isolator);
-	execute(options: ExecuteOptions): Promise<ExecuteResult>;
-	prepare(): Promise<void>;
-	cleanup(): 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>;
+/**
+* Add Node.js execute capability to sandbox
+*/
+declare function withNodeExecute<T extends Sandbox>(Base: SandboxConstructor<T>): SandboxConstructor<T & WithExecute>;
+/**
+* Add Python execute capability to sandbox
+*/
+declare function withPythonExecute<T extends Sandbox>(Base: SandboxConstructor<T>): SandboxConstructor<T & WithExecute>;
 /**
 * Error types for SandboX
 */
@@ -129,7 +238,4 @@ declare class TimeoutError extends SandboxError {
 declare class IsolationError extends SandboxError {
 	constructor(message: string);
 }
-declare class FileSystemError extends SandboxError {
-	constructor(message: string);
-}
-export { TimeoutError, SandboxError, SandboxConfig, Sandbox, Runtime2 as Runtime, ResourceLimits, LocalIsolator, IsolatorType, Isolator, IsolationError, IsolationConfig, GenericRuntime, FileSystemError, FileSystem, ExecutionError, ExecuteResult, ExecuteOptions, EventHandler, CloudflareContainerIsolator };
+export { withState, withPythonExecute, withNodeExecute, loadStateLog, buildStateLog, WithState3 as WithState, WithExecute, TimeoutError, Storage, StateStorage, StateSandbox, StateLogEntry, StateLog2 as StateLog, StateFS, StateError, StateEnv, StateConfig, ShellResult, SandboxMixin, SandboxError, SandboxConstructor, SandboxConfig, Sandbox, Runtime, ResourceLimits, PythonSandbox, PythonConfig, NodeSandbox, NodeConfig, LocalIsolator, IsolatorType, Isolator, IsolationError, FileSystemError, FileSystem, ExecutionError, ExecuteResult, Environment, CloudflareContainerIsolator, BaseSandbox };