@ebowwa/sandbox 0.1.1

package/src/index.ts

@@ -0,0 +1,515 @@
+/**
+ * @ebowwa/sandbox
+ *
+ * Composable sandbox primitives for multi-language code execution.
+ * Jupyter/REPL-style with Python+Rust+JS+TS+WASM support.
+ *
+ * @example
+ * ```typescript
+ * import { Sandbox, createNotebook, createREPL } from "@ebowwa/sandbox";
+ *
+ * // Quick execution
+ * const sandbox = new Sandbox();
+ * const result = await sandbox.execute("console.log('Hello')", "javascript");
+ *
+ * // Notebook
+ * const notebook = createNotebook({ name: "My Notebook" });
+ * notebook.addCell({ language: "javascript", source: "const x = 42" });
+ * notebook.runAll();
+ *
+ * // REPL
+ * const repl = createREPL({ language: "python" });
+ * repl.start();
+ * ```
+ */
+
+// Core types - re-export for convenience
+export type {
+  Language,
+  LanguageCapabilities,
+  PermissionLevel,
+  Permissions,
+  Limits,
+  Cell,
+  ExecutionResult,
+  ExecutionOptions,
+  ExecutionContext,
+  ExecutionError,
+  ExecutionMetrics,
+  DisplayOutput,
+  NotebookMetadata,
+  NotebookRunOptions,
+  NotebookResult,
+  PolyglotCell,
+  LanguageBridge,
+  Sandbox as SandboxInterface,
+  SandboxOptions,
+  SessionOptions,
+  NotebookOptions,
+  Session,
+  Notebook,
+  Kernel,
+  Compiler,
+  Runtime,
+} from "./core/types.js";
+
+// Type utilities
+export {
+  permissionsFromLevel,
+  parseMemory,
+  parseTime,
+} from "./core/types.js";
+
+// Compiler exports
+export type {
+  CompileResult,
+  ImportDefinition,
+  CompilerOptions,
+  ICompiler,
+} from "./core/compiler.js";
+
+export {
+  BaseCompiler,
+  WasmCompiler,
+  CompilerRegistry,
+  defaultCompilerRegistry,
+} from "./core/compiler.js";
+
+// Runtime exports
+export type {
+  RuntimeOptions,
+  ExecutionRequest,
+  IRuntime,
+  RuntimeCapabilities,
+} from "./core/runtime.js";
+
+export {
+  Wasm2WasmRuntime,
+  NativeWasmRuntime,
+  RuntimeRegistry,
+  defaultRuntimeRegistry,
+} from "./core/runtime.js";
+
+// Elevated permission runtimes
+export type {
+  ProcessRuntimeConfig,
+  DockerRuntimeConfig,
+  ContainerOptions,
+} from "./runtimes/index.js";
+
+export {
+  ProcessRuntime,
+  DockerRuntime,
+} from "./runtimes/index.js";
+
+// Permission exports
+export {
+  PermissionChecker,
+  PermissionBuilder,
+  createPermissions,
+  mergePermissions,
+  impliesPermission,
+  upgradePermissions,
+} from "./core/permissions.js";
+
+// Limits exports
+export type { ParsedLimits } from "./core/limits.js";
+
+export {
+  DEFAULT_LIMITS,
+  LimitsParser,
+  LimitsEnforcer,
+  LimitsBuilder,
+  mergeLimits,
+} from "./core/limits.js";
+
+// Cell exports
+export type {
+  CellMetadata,
+  CellState,
+  ExecutableCell,
+} from "./core/cell.js";
+
+export {
+  CellBuilder,
+  CellExecutor,
+  CellRegistry,
+  createCell,
+  createCellsFromMarkdown,
+  cellsToMarkdown,
+} from "./core/cell.js";
+
+// Session exports
+export type {
+  KernelState,
+  KernelOptions,
+  KernelStats,
+  NotebookState,
+  NotebookEvents,
+  REPLOptions,
+  REPLHistoryEntry,
+  REPLState,
+} from "./session/index.js";
+
+export {
+  BaseKernel,
+  KernelManager,
+  BaseNotebook,
+  createNotebook,
+  BaseREPL,
+  createREPL,
+} from "./session/index.js";
+
+// Multi-language exports
+export type {
+  PolyglotOptions,
+  VariableBinding,
+  PolyglotContext,
+} from "./multi/index.js";
+
+export {
+  PolyglotSession,
+  PolyglotNotebook,
+  createPolyglotSession,
+  createPolyglotNotebook,
+} from "./multi/index.js";
+
+// Import for implementation
+import type {
+  Language,
+  Permissions,
+  Limits,
+  PermissionLevel,
+  ExecutionResult,
+  ExecutionOptions,
+  SandboxOptions,
+  SessionOptions,
+  NotebookOptions as NotebookOpts,
+} from "./core/types.js";
+import type { KernelOptions } from "./session/kernel.js";
+import { BaseKernel, KernelManager } from "./session/kernel.js";
+import { BaseNotebook, createNotebook } from "./session/notebook.js";
+import { BaseREPL, createREPL } from "./session/repl.js";
+import { PolyglotSession } from "./multi/polyglot.js";
+import { defaultCompilerRegistry } from "./core/compiler.js";
+import { defaultRuntimeRegistry } from "./core/runtime.js";
+import { createPermissions, permissionsFromLevel } from "./core/permissions.js";
+import { DEFAULT_LIMITS } from "./core/limits.js";
+import { ProcessRuntime } from "./runtimes/process.js";
+import { DockerRuntime } from "./runtimes/docker.js";
+
+// Register elevated permission runtimes
+defaultRuntimeRegistry.register(new ProcessRuntime());
+defaultRuntimeRegistry.register(new DockerRuntime());
+
+/**
+ * Normalize permissions to Permissions object
+ */
+function normalizePermissions(
+  perms: PermissionLevel | Permissions | undefined
+): Permissions {
+  if (!perms) {
+    return createPermissions("isolated");
+  }
+  if (typeof perms === "string") {
+    return permissionsFromLevel(perms as PermissionLevel);
+  }
+  return perms;
+}
+
+/**
+ * Sandbox Implementation
+ *
+ * Main entry point for sandboxed execution.
+ */
+export class Sandbox {
+  private kernelManager = new KernelManager();
+
+  constructor(private defaultOptions?: SandboxOptions) {}
+
+  /**
+   * Quick execute (isolated, no state)
+   */
+  async execute(
+    code: string,
+    language: Language = "javascript",
+    options?: SandboxOptions
+  ): Promise<ExecutionResult> {
+    const merged = this.mergeOptions(options);
+    const perms = normalizePermissions(merged.permissions);
+
+    // Get compiler and runtime
+    const compiler = defaultCompilerRegistry.get(language);
+    if (!compiler) {
+      throw new Error(`No compiler for language: ${language}`);
+    }
+
+    const runtime = defaultRuntimeRegistry.selectBest({
+      filesystem: perms.fs?.write,
+      network: perms.network?.outbound,
+    });
+    if (!runtime) {
+      throw new Error("No available runtime");
+    }
+
+    // Compile
+    const compiled = await compiler.compile(
+      code,
+      perms,
+      merged.limits ?? {}
+    );
+
+    // Execute
+    return runtime.execute(
+      { wasm: compiled },
+      {
+        permissions: perms,
+        limits: merged.limits ?? {},
+        env: merged.environment,
+        cwd: merged.workingDirectory,
+      }
+    );
+  }
+
+  /**
+   * Quick execute with preset
+   */
+  async quick(
+    code: string,
+    preset: "isolated" | "trusted" | "admin" = "isolated"
+  ): Promise<ExecutionResult> {
+    const levelMap: Record<string, PermissionLevel> = {
+      isolated: "isolated",
+      trusted: "filesystem",
+      admin: "admin",
+    };
+
+    const permissions = permissionsFromLevel(levelMap[preset] as PermissionLevel);
+    const limits = DEFAULT_LIMITS[preset];
+
+    return this.execute(code, "javascript", {
+      permissions,
+      limits: {
+        memory: limits.memoryBytes,
+        timeout: limits.timeoutMs,
+        cpuTime: limits.cpuTimeMs,
+        maxInstructions: limits.maxInstructions,
+        maxOutputSize: limits.maxOutputBytes,
+        maxStackDepth: limits.maxStackDepth,
+      },
+    });
+  }
+
+  /**
+   * Create a session for interactive use
+   */
+  createSession(options?: SessionOptions): SandboxSession {
+    const merged = this.mergeOptions(options);
+    return new SandboxSession(
+      this.kernelManager,
+      {
+        permissions: normalizePermissions(merged.permissions),
+        limits: merged.limits ?? {},
+        environment: merged.environment,
+        workingDirectory: merged.workingDirectory,
+        sharedMemory: options?.sharedMemory ?? false,
+      }
+    );
+  }
+
+  /**
+   * Create a notebook
+   */
+  createNotebook(options?: NotebookOpts): BaseNotebook {
+    const merged = this.mergeOptions(options);
+    return createNotebook({
+      name: options?.name,
+      defaultLanguage: options?.defaultLanguage,
+      permissions: normalizePermissions(merged.permissions),
+      limits: merged.limits,
+      kernelManager: this.kernelManager,
+    });
+  }
+
+  /**
+   * Create a REPL
+   */
+  createREPL(options?: SessionOptions & { language?: Language }): BaseREPL {
+    const merged = this.mergeOptions(options);
+    return createREPL({
+      language: options?.language,
+      permissions: normalizePermissions(merged.permissions),
+      limits: merged.limits,
+      kernelManager: this.kernelManager,
+    });
+  }
+
+  /**
+   * Create polyglot session
+   */
+  createPolyglot(options?: { permissions?: Permissions; limits?: Limits }): PolyglotSession {
+    const merged = this.mergeOptions(options);
+    return new PolyglotSession({
+      permissions: normalizePermissions(merged.permissions),
+      limits: merged.limits,
+      kernelManager: this.kernelManager,
+    });
+  }
+
+  /**
+   * Merge options with defaults
+   */
+  private mergeOptions(options?: SandboxOptions): {
+    permissions: Permissions;
+    limits: Limits | undefined;
+    language: Language | undefined;
+    environment: Record<string, string>;
+    workingDirectory: string;
+  } {
+    const rawPerms = options?.permissions ?? this.defaultOptions?.permissions ?? "isolated";
+    return {
+      permissions: normalizePermissions(rawPerms),
+      limits: options?.limits ?? this.defaultOptions?.limits,
+      language: options?.language ?? this.defaultOptions?.language,
+      environment: options?.environment ?? this.defaultOptions?.environment ?? {},
+      workingDirectory: options?.workingDirectory ?? this.defaultOptions?.workingDirectory ?? process.cwd(),
+    };
+  }
+}
+
+/**
+ * Sandbox Session
+ *
+ * Stateful execution context.
+ */
+export class SandboxSession {
+  readonly id: string;
+  private kernelManager: KernelManager;
+  private kernels = new Map<Language, BaseKernel>();
+  private sharedState = new Map<string, unknown>();
+  private options: {
+    permissions: Permissions;
+    limits: Limits;
+    environment: Record<string, string>;
+    workingDirectory: string;
+    sharedMemory: boolean;
+  };
+
+  constructor(
+    kernelManager: KernelManager,
+    options: {
+      permissions: Permissions;
+      limits: Limits;
+      environment: Record<string, string>;
+      workingDirectory: string;
+      sharedMemory: boolean;
+    }
+  ) {
+    this.id = `session-${Date.now()}`;
+    this.kernelManager = kernelManager;
+    this.options = options;
+  }
+
+  /**
+   * Get kernel for language
+   */
+  getKernel(language: Language): BaseKernel | undefined {
+    return this.kernels.get(language);
+  }
+
+  /**
+   * Start kernel for language
+   */
+  async startKernel(language: Language): Promise<BaseKernel> {
+    let kernel = this.kernels.get(language);
+
+    if (!kernel) {
+      const compiler = defaultCompilerRegistry.get(language);
+      const runtime = defaultRuntimeRegistry.selectBest({});
+
+      if (!compiler || !runtime) {
+        throw new Error(`Cannot create kernel for ${language}`);
+      }
+
+      const kernelOptions: KernelOptions = {
+        language,
+        compiler,
+        runtime,
+        permissions: this.options.permissions,
+        limits: this.options.limits,
+        env: this.options.environment,
+        cwd: this.options.workingDirectory,
+      };
+
+      kernel = await this.kernelManager.createKernel(kernelOptions);
+      this.kernels.set(language, kernel);
+    }
+
+    return kernel;
+  }
+
+  /**
+   * Execute code
+   */
+  async execute(
+    code: string,
+    language: Language,
+    options?: ExecutionOptions
+  ): Promise<ExecutionResult> {
+    const kernel = await this.startKernel(language);
+    return kernel.execute(code, options);
+  }
+
+  /**
+   * Get shared state
+   */
+  getSharedState(): Map<string, unknown> {
+    return new Map(this.sharedState);
+  }
+
+  /**
+   * Set shared state
+   */
+  setSharedState(key: string, value: unknown): void {
+    this.sharedState.set(key, value);
+  }
+
+  /**
+   * Shutdown session
+   */
+  async shutdown(): Promise<void> {
+    for (const language of this.kernels.keys()) {
+      await this.kernelManager.shutdownKernel(
+        this.kernels.get(language)!.getId()
+      );
+    }
+    this.kernels.clear();
+    this.sharedState.clear();
+  }
+}
+
+/**
+ * Create default sandbox instance
+ */
+export const sandbox = new Sandbox();
+
+/**
+ * Quick execute helper
+ */
+export async function execute(
+  code: string,
+  language: Language = "javascript",
+  options?: SandboxOptions
+): Promise<ExecutionResult> {
+  return sandbox.execute(code, language, options);
+}
+
+/**
+ * Quick execute with preset helper
+ */
+export async function quick(
+  code: string,
+  preset: "isolated" | "trusted" | "admin" = "isolated"
+): Promise<ExecutionResult> {
+  return sandbox.quick(code, preset);
+}

package/src/multi/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Multi-Language Primitives
+ *
+ * Execute code across multiple languages with shared state.
+ */
+
+// Polyglot - Multi-language execution
+export type {
+  PolyglotOptions,
+  VariableBinding,
+  PolyglotContext,
+} from "./polyglot.js";
+
+export {
+  PolyglotSession,
+  PolyglotNotebook,
+  createPolyglotSession,
+  createPolyglotNotebook,
+} from "./polyglot.js";
+
+// Re-export bridge type
+export type { LanguageBridge } from "../core/types.js";