@isol8/core 0.13.0-alpha.0

package/dist/engine/docker.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @module engine/docker
+ *
+ * The Docker-backed isol8 engine. Creates and manages Docker containers
+ * for executing untrusted code with resource limits, network controls, and
+ * output sanitization.
+ */
+import Docker from "dockerode";
+import type { ExecutionRequest, ExecutionResult, Isol8Engine, Isol8Options, StartOptions, StreamEvent } from "../types";
+/** Options for constructing a {@link DockerIsol8} instance. Extends {@link Isol8Options} with Docker-specific settings. */
+export interface DockerIsol8Options extends Isol8Options {
+    /** Custom dockerode instance. Defaults to connecting to the local Docker socket. */
+    docker?: Docker;
+}
+/**
+ * Docker-backed isol8 engine that executes code in isolated containers.
+ *
+ * Supports two modes:
+ * - **Ephemeral** — a new container is created and destroyed per `execute()` call.
+ * - **Persistent** — a long-lived container is reused across calls, preserving state.
+ *
+ * @example
+ * ```typescript
+ * const isol8 = new DockerIsol8({ network: "none", memoryLimit: "256m" });
+ * await isol8.start();
+ * const result = await isol8.execute({ code: "print(1+1)", runtime: "python" });
+ * await isol8.stop();
+ * ```
+ */
+export declare class DockerIsol8 implements Isol8Engine {
+    private readonly docker;
+    private readonly mode;
+    private readonly network;
+    private readonly networkFilter?;
+    private readonly cpuLimit;
+    private readonly memoryLimit;
+    private readonly pidsLimit;
+    private readonly readonlyRootFs;
+    private readonly maxOutputSize;
+    private readonly secrets;
+    private readonly defaultTimeoutMs;
+    private readonly overrideImage?;
+    private readonly semaphore;
+    private readonly sandboxSize;
+    private readonly tmpSize;
+    private readonly security;
+    private readonly persist;
+    private readonly logNetwork;
+    private readonly poolStrategy;
+    private readonly poolSize;
+    private readonly dependencies;
+    private readonly auditLogger?;
+    private readonly remoteCodePolicy;
+    private container;
+    private persistentRuntime;
+    private pool;
+    private readonly imageCache;
+    private resolveExecutionRequest;
+    /**
+     * @param options - Sandbox configuration options.
+     * @param maxConcurrent - Maximum number of concurrent executions (controls the internal semaphore).
+     */
+    constructor(options?: DockerIsol8Options, maxConcurrent?: number);
+    /**
+     * Initialize isol8.
+     *
+     * In ephemeral mode this can optionally pre-warm the container pool.
+     * In persistent mode the container is created lazily on first execute.
+     */
+    start(options?: StartOptions): Promise<void>;
+    /** Stop and remove the container (if one exists). Safe to call multiple times. */
+    stop(): Promise<void>;
+    /**
+     * Execute code in isol8. Acquires a semaphore permit to enforce
+     * the concurrency limit, then delegates to ephemeral or persistent execution.
+     */
+    execute(req: ExecutionRequest): Promise<ExecutionResult>;
+    /**
+     * Record an audit entry for the execution.
+     */
+    private recordAudit;
+    /**
+     * Collect security events from the container (e.g., network filter blocks).
+     */
+    private collectSecurityEvents;
+    /**
+     * Collect network logs from the container (requests made through the proxy).
+     */
+    private collectNetworkLogs;
+    /**
+     * Upload a file into the running container via a tar archive.
+     * Only available in persistent mode after at least one `execute()` call.
+     *
+     * @param path - Absolute path inside the container.
+     * @param content - File contents.
+     * @throws {Error} If no container is active.
+     */
+    putFile(path: string, content: Buffer | string): Promise<void>;
+    /**
+     * Download a file from the running container.
+     *
+     * @param path - Absolute path inside the container.
+     * @returns File contents as a Buffer.
+     * @throws {Error} If no container is active.
+     */
+    getFile(path: string): Promise<Buffer>;
+    /** The Docker container ID, or `null` if no container is active. Used by the server for session tracking. */
+    get containerId(): string | null;
+    /**
+     * Execute code and stream output chunks as they arrive.
+     * Yields {@link StreamEvent} objects for stdout, stderr, exit, and error events.
+     */
+    executeStream(req: ExecutionRequest): AsyncIterable<StreamEvent>;
+    private resolveImage;
+    private ensurePool;
+    private executeEphemeral;
+    private executePersistent;
+    private retrieveFiles;
+    private getFileFromContainer;
+    private startPersistentContainer;
+    private getAdapter;
+    private buildHostConfig;
+    private buildSecurityOpts;
+    private loadDefaultSeccompProfile;
+    private buildEnv;
+    private streamExecOutput;
+    private collectExecOutput;
+    private postProcessOutput;
+    /**
+     * Remove all isol8 containers (both running and stopped).
+     *
+     * This static utility method finds and removes all containers created by isol8,
+     * identified by images starting with `isol8:`.
+     *
+     * @param docker - Optional Docker instance. If not provided, creates a new one.
+     * @returns Promise resolving to an object with counts of removed and failed containers.
+     *
+     * @example
+     * ```typescript
+     * import { DockerIsol8 } from "isol8";
+     *
+     * // Remove all isol8 containers
+     * const result = await DockerIsol8.cleanup();
+     * console.log(`Removed ${result.removed} containers`);
+     * if (result.failed > 0) {
+     *   console.log(`Failed to remove ${result.failed} containers`);
+     * }
+     * ```
+     */
+    static cleanup(docker?: Docker): Promise<{
+        removed: number;
+        failed: number;
+        errors: string[];
+    }>;
+    /**
+     * Remove all isol8 Docker images.
+     *
+     * Images are identified by repo tags starting with `isol8:`
+     * (for example `isol8:python` or `isol8:python-custom-<hash>`).
+     */
+    static cleanupImages(docker?: Docker): Promise<{
+        removed: number;
+        failed: number;
+        errors: string[];
+    }>;
+}
+//# sourceMappingURL=docker.d.ts.map

package/dist/engine/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/engine/docker.ts"],"names":[],"mappings":"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"}

package/dist/engine/image-builder.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module engine/image-builder
+ *
+ * Builds Docker images for each supported runtime. Base images are built from
+ * the multi-stage `docker/Dockerfile`. Custom images layer user-specified
+ * packages on top of the base images.
+ */
+import type Docker from "dockerode";
+import type { Isol8Config } from "../types";
+/**
+ * Normalize package lists for stable tags/cache hits.
+ * - trims whitespace
+ * - removes empty entries
+ * - de-duplicates
+ * - sorts lexicographically
+ */
+export declare function normalizePackages(packages: string[]): string[];
+/**
+ * Returns deterministic custom image tag for a runtime + package set.
+ * Uses a short deps hash suffix to avoid tag collisions across different
+ * dependency sets for the same runtime.
+ */
+export declare function getCustomImageTag(runtime: string, packages: string[]): string;
+/** Progress update emitted during image builds. */
+interface BuildProgress {
+    /** Runtime being built (e.g. `"python"`). */
+    runtime: string;
+    /** Current build status. */
+    status: "building" | "done" | "error";
+    /** Optional status message (error text, package list, etc). */
+    message?: string;
+}
+type ProgressCallback = (progress: BuildProgress) => void;
+/**
+ * Builds the base `isol8:<runtime>` images for all registered runtimes.
+ * Each image is built from the multi-stage Dockerfile in `docker/`.
+ *
+ * Uses smart build logic: computes a hash of the docker directory contents
+ * and skips builds if the image already exists with matching hash.
+ * Cleans up dangling images after rebuilding.
+ *
+ * @param docker - Dockerode instance.
+ * @param onProgress - Optional callback for build progress updates.
+ * @param force - If true, always rebuild even if image is up to date.
+ */
+export declare function buildBaseImages(docker: Docker, onProgress?: ProgressCallback, force?: boolean, onlyRuntimes?: string[]): Promise<void>;
+/**
+ * Builds custom images with user-specified dependencies layered on top of
+ * the base images. Reads package lists from the config's `dependencies` field.
+ *
+ * Uses smart build logic: computes a hash of the dependency list and
+ * skips builds if the image already exists with matching hash.
+ * Cleans up dangling images after rebuilding.
+ *
+ * @param docker - Dockerode instance.
+ * @param config - Resolved isol8 configuration.
+ * @param onProgress - Optional callback for build progress updates.
+ * @param force - If true, always rebuild even if image is up to date.
+ */
+export declare function buildCustomImages(docker: Docker, config: Isol8Config, onProgress?: ProgressCallback, force?: boolean): Promise<void>;
+export declare function buildCustomImage(docker: Docker, runtime: import("../types").Runtime | string, packages: string[], onProgress?: ProgressCallback, force?: boolean): Promise<void>;
+/**
+ * Checks if an image exists locally.
+ */
+export declare function imageExists(docker: Docker, imageName: string): Promise<boolean>;
+/**
+ * Ensures all base images are built.
+ */
+export declare function ensureImages(docker: Docker, onProgress?: ProgressCallback): Promise<void>;
+export {};
+//# sourceMappingURL=image-builder.d.ts.map

package/dist/engine/image-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-builder.d.ts","sourceRoot":"","sources":["../../src/engine/image-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AA6F5C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAK7E;AAkCD,mDAAmD;AACnD,UAAU,aAAa;IACrB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;IACtC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,gBAAgB,GAAG,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,gBAAgB,EAC7B,KAAK,UAAQ,EACb,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAuEf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,gBAAgB,EAC7B,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,UAAU,EAAE,OAAO,GAAG,MAAM,EAC5C,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,CAAC,EAAE,gBAAgB,EAC7B,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC,CA2Ff;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa/F"}

package/dist/engine/pool.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @module engine/pool
+ *
+ * Warm container pool for fast ephemeral execution. Pre-creates and
+ * starts containers so they're ready for immediate use, eliminating
+ * the create+start overhead (~100-200ms per execution).
+ *
+ * Supports two strategies:
+ * - "secure": Clean container before returning (slower but ensures clean state)
+ * - "fast": Dual-pool system - instant acquire from clean pool, background cleanup
+ */
+import type Docker from "dockerode";
+/** Configuration for the container pool. */
+export interface PoolOptions {
+    /** Docker client instance. */
+    docker: Docker;
+    /** Pool strategy: "secure" or "fast". @default "fast" */
+    poolStrategy?: "secure" | "fast";
+    /** Pool size configuration.
+     * For "secure" mode: number of containers to keep warm
+     * For "fast" mode: { clean: ready containers, dirty: being cleaned }
+     * @default 1 (for fast mode: { clean: 1, dirty: 1 })
+     */
+    poolSize?: number | {
+        clean: number;
+        dirty: number;
+    };
+    /** Container creation options (HostConfig, Env, etc). */
+    createOptions: Omit<Docker.ContainerCreateOptions, "Image">;
+    /** Network mode to determine if iptables cleanup is needed. */
+    networkMode: "none" | "host" | "filtered";
+    /** Security mode - if strict, run process cleanup between executions */
+    securityMode: "strict" | "unconfined" | "custom";
+}
+/**
+ * A per-image warm container pool. Maintains pre-started containers
+ * ready for immediate exec, recycling them after use.
+ *
+ * Supports two strategies:
+ * - "secure": Single pool, cleanup in acquire (current behavior)
+ * - "fast": Dual pools (clean/dirty), instant acquire, background cleanup
+ */
+export declare class ContainerPool {
+    private readonly docker;
+    private readonly poolStrategy;
+    private readonly cleanPoolSize;
+    private readonly dirtyPoolSize;
+    private readonly createOptions;
+    private readonly networkMode;
+    private readonly securityMode;
+    private readonly pools;
+    private readonly replenishing;
+    private readonly pendingReplenishments;
+    private cleaningInterval;
+    constructor(options: PoolOptions);
+    /**
+     * Acquire a started container for the given image.
+     * - "secure" mode: Clean container before returning
+     * - "fast" mode: Instant return from clean pool, create new if empty
+     */
+    acquire(image: string): Promise<Docker.Container>;
+    /**
+     * Return a container to the pool.
+     * - "secure" mode: Add to pool, cleanup happens on next acquire
+     * - "fast" mode: Add to dirty pool for background cleaning
+     */
+    release(container: Docker.Container, image: string): Promise<void>;
+    /**
+     * Start background cleaning for fast mode.
+     * Runs every 5 seconds to clean dirty containers.
+     */
+    private startBackgroundCleaning;
+    /**
+     * Clean a dirty container immediately and add to clean pool.
+     */
+    private cleanDirtyImmediate;
+    private cleanupContainer;
+    /**
+     * Pre-warm the pool for a specific image.
+     */
+    warm(image: string): Promise<void>;
+    /**
+     * Stop the pool and clean up resources.
+     * Alias for drain() - destroys all containers and stops background cleaning.
+     */
+    stop(): Promise<void>;
+    /**
+     * Destroy all pooled containers and clear the pool.
+     */
+    drain(): Promise<void>;
+    private createContainer;
+    private replenish;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/engine/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/engine/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAGpC,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,yDAAyD;IACzD,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;IAC5D,+DAA+D;IAC/D,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1C,wEAAwE;IACxE,YAAY,EAAE,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;CAClD;AAYD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+C;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqC;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA4B;IAClE,OAAO,CAAC,gBAAgB,CAA+C;gBAE3D,OAAO,EAAE,WAAW;IA0BhC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;IAkDvD;;;;OAIG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCxE;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;;OAEG;YACW,mBAAmB;YAenB,gBAAgB;IA4B9B;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAyBd,eAAe;IAW7B,OAAO,CAAC,SAAS;CAsDlB"}

package/dist/engine/stats.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module engine/stats
+ *
+ * Resource usage statistics collection from Docker containers.
+ * Uses dockerode's container.stats() API to get CPU, memory, and network metrics.
+ */
+import type Docker from "dockerode";
+/**
+ * Resource usage metrics for a container execution.
+ */
+export interface ContainerResourceUsage {
+    /** CPU usage as percentage (0-100 * num_cores) */
+    cpuPercent: number;
+    /** Current memory usage in megabytes */
+    memoryMB: number;
+    /** Peak memory usage in megabytes (if tracked) */
+    peakMemoryMB?: number;
+    /** Bytes received during execution */
+    networkBytesIn: number;
+    /** Bytes sent during execution */
+    networkBytesOut: number;
+}
+/**
+ * Get resource usage snapshot for a container.
+ *
+ * @param container - Docker container instance
+ * @returns Resource usage metrics
+ */
+export declare function getContainerStats(container: Docker.Container): Promise<ContainerResourceUsage>;
+/**
+ * Calculate resource usage delta between two stat snapshots.
+ * Useful for getting per-execution metrics.
+ */
+export declare function calculateResourceDelta(before: ContainerResourceUsage, after: ContainerResourceUsage): ContainerResourceUsage;
+//# sourceMappingURL=stats.d.ts.map

package/dist/engine/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/engine/stats.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;CACzB;AA+ED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,CAAC,SAAS,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CAgBjC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,sBAAsB,GAC5B,sBAAsB,CAUxB"}

package/dist/engine/utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module engine/utils
+ *
+ * Low-level utility functions used by the Docker engine: memory parsing,
+ * output truncation, secret masking, and POSIX tar archive creation/extraction.
+ */
+/**
+ * Parses a human-readable memory limit string into bytes.
+ *
+ * @param limit - Memory string (e.g. `"512m"`, `"1g"`, `"256k"`, `"1024"`).
+ * @returns The limit in bytes.
+ * @throws {Error} If the format is invalid.
+ *
+ * @example
+ * ```typescript
+ * parseMemoryLimit("512m"); // 536870912
+ * parseMemoryLimit("1g");   // 1073741824
+ * ```
+ */
+export declare function parseMemoryLimit(limit: string): number;
+/**
+ * Truncates output to a maximum byte length. If truncated, appends a
+ * summary line indicating the original and limit sizes.
+ *
+ * @param output - The full output string.
+ * @param maxBytes - Maximum allowed byte length.
+ * @returns Object with the (possibly truncated) text and a truncation flag.
+ */
+export declare function truncateOutput(output: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Replaces all occurrences of secret values in a string with `***`.
+ * Empty secret values are skipped.
+ *
+ * @param text - The text to sanitize.
+ * @param secrets - Map of secret names to values.
+ * @returns The sanitized text.
+ */
+export declare function maskSecrets(text: string, secrets: Record<string, string>): string;
+/**
+ * Creates a POSIX tar archive buffer containing a single file.
+ *
+ * Uses a minimal tar header (512-byte blocks) followed by data blocks
+ * and a 1024-byte end-of-archive marker.
+ *
+ * @param filePath - Path for the file inside the archive (leading `/` is stripped).
+ * @param content - File contents as a string or Buffer.
+ * @returns A Buffer containing the complete tar archive.
+ */
+export declare function createTarBuffer(filePath: string, content: Buffer | string): Buffer;
+/**
+ * Extracts a single file from a tar archive buffer.
+ *
+ * @param tarBuffer - The tar archive buffer.
+ * @param targetPath - Path of the file to extract (leading `/` is stripped for matching).
+ * @returns The extracted file contents as a Buffer.
+ * @throws {Error} If the file is not found in the archive.
+ */
+export declare function extractFromTar(tarBuffer: Buffer, targetPath: string): Buffer;
+/**
+ * Validates a package name to prevent command injection.
+ * allow alphanumeric, dash, underscore, dot, @, / (for scoped packages), and = (for versions)
+ *
+ * @param name - The package name to validate.
+ * @returns The name if valid.
+ * @throws {Error} If the name contains invalid characters.
+ */
+export declare function validatePackageName(name: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/engine/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/engine/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAetC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CA8ClF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAoC5E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module @isol8/core
+ *
+ * Public API for the isol8 secure code execution engine.
+ * Import from `"@isol8/core"` to access the engine, client, config, runtime registry.
+ */
+export type { RemoteIsol8Options } from "./client/remote";
+export { RemoteIsol8 } from "./client/remote";
+export { loadConfig } from "./config";
+export { Semaphore } from "./engine/concurrency";
+export type { DockerIsol8Options } from "./engine/docker";
+export { DockerIsol8 } from "./engine/docker";
+export { buildBaseImages, buildCustomImages } from "./engine/image-builder";
+export { BunAdapter, bashAdapter, DenoAdapter, NodeAdapter, PythonAdapter, RuntimeRegistry, } from "./runtime";
+export type { RuntimeAdapter } from "./runtime/adapter";
+export type { ExecutionRequest, ExecutionResult, Isol8Config, Isol8Engine, Isol8Mode, Isol8Options, NetworkFilterConfig, NetworkMode, RemoteCodePolicy, Runtime, StreamEvent, } from "./types";
+export { logger } from "./utils/logger";
+export { VERSION } from "./version";
+//# 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;;;;;GAKG;AAIH,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE5E,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,WAAW,GACZ,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}