@buddhilive/sandbox 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+export declare interface FileStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    size: number;
+    mtimeMs: number;
+    mode: number;
+}
+
+export declare class FsNamespace {
+    private bridge;
+    private adapter;
+    constructor(bridge: WorkerBridge, adapter?: PersistenceAdapter | null);
+    setPersistenceAdapter(adapter: PersistenceAdapter | null): void;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, encoding: 'utf-8'): Promise<string>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    stat(path: string): Promise<FileStat>;
+    symlink(target: string, path: string): Promise<void>;
+}
+
+export declare interface ListenEvent {
+    port: number;
+    url: string;
+}
+
+export declare class OOMError extends SandboxError {
+    constructor(message?: string);
+}
+
+export declare interface PersistenceAdapter {
+    save(path: string, data: Uint8Array): Promise<void>;
+    load(path: string): Promise<Uint8Array | null>;
+    delete(path: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+declare type PortListener = (event: ListenEvent) => void;
+
+export declare class PortsNamespace {
+    private bridge;
+    private listeners;
+    private activePorts;
+    constructor(bridge: WorkerBridge);
+    on(event: 'listen' | 'close', listener: PortListener): () => void;
+    off(event: 'listen' | 'close', listener: PortListener): void;
+    getPreviewUrl(port: number): string | undefined;
+}
+
+export declare interface ProcessExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+
+export declare interface ProcessHandle {
+    readonly pid: number;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly stdin: WritableStream<Uint8Array>;
+    readonly exit: Promise<number>;
+    kill(signal?: string): Promise<void>;
+}
+
+export declare class ProcessNamespace {
+    private bridge;
+    private exitResolvers;
+    constructor(bridge: WorkerBridge);
+    spawn(command: string, args?: string[], options?: {
+        env?: Record<string, string>;
+        cwd?: string;
+    }): Promise<ProcessHandle>;
+    exec(commandLine: string): Promise<ProcessExecResult>;
+    kill(pid: number, signal?: string): Promise<void>;
+}
+
+export declare class Sandbox {
+    readonly fs: FsNamespace;
+    readonly process: ProcessNamespace;
+    readonly ports: PortsNamespace;
+    private bridge;
+    private isDisposed;
+    private constructor();
+    static create(options?: SandboxOptions): Promise<Sandbox>;
+    dispose(): Promise<void>;
+}
+
+export declare class SandboxError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+
+/**
+ * Core type declarations for @buddhilive/sandbox
+ */
+export declare interface SandboxOptions {
+    /** Maximum memory quota in megabytes (default: 512) */
+    maxMemoryMb?: number;
+    /** Default command execution timeout in milliseconds (default: 30000) */
+    commandTimeoutMs?: number;
+    /** NPM registry URL (default: 'https://registry.npmjs.org') */
+    registryUrl?: string;
+    /** Optional persistence adapter for VirtualFS state */
+    persistenceAdapter?: 'opfs' | 'indexeddb' | null;
+    /** Optional URL or custom path to sandbox.worker.js */
+    workerUrl?: string;
+    /** Optional URL or custom path to WebAssembly core binary */
+    wasmUrl?: string;
+}
+
+declare class WorkerBridge {
+    private worker;
+    private pendingRequests;
+    private messageListeners;
+    constructor(worker: Worker);
+    postMessage(msg: WorkerInboundMessage, transfer?: Transferable[]): void;
+    request<T = any>(msg: WorkerInboundMessage & {
+        id: string;
+    }): Promise<T>;
+    onMessage(listener: (msg: WorkerOutboundMessage) => void): () => void;
+    terminate(): void;
+}
+
+declare type WorkerInboundMessage = {
+    type: 'init';
+    options: SandboxOptions;
+} | {
+    type: 'fs:read';
+    id: string;
+    path: string;
+} | {
+    type: 'fs:write';
+    id: string;
+    path: string;
+    data: Uint8Array;
+} | {
+    type: 'fs:mkdir';
+    id: string;
+    path: string;
+    recursive?: boolean;
+} | {
+    type: 'fs:readdir';
+    id: string;
+    path: string;
+} | {
+    type: 'fs:rm';
+    id: string;
+    path: string;
+    recursive?: boolean;
+} | {
+    type: 'fs:stat';
+    id: string;
+    path: string;
+} | {
+    type: 'fs:symlink';
+    id: string;
+    target: string;
+    path: string;
+} | {
+    type: 'process:spawn';
+    id: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+} | {
+    type: 'process:kill';
+    pid: number;
+    signal?: string;
+} | {
+    type: 'port:listen_ack';
+    port: number;
+    messagePort: MessagePort;
+};
+
+declare type WorkerOutboundMessage = {
+    type: 'ready';
+} | {
+    type: 'error';
+    message: string;
+    code?: string;
+} | {
+    type: 'fs:response';
+    id: string;
+    error?: string;
+    result?: unknown;
+} | {
+    type: 'process:spawned';
+    id: string;
+    pid: number;
+    stdoutSab: SharedArrayBuffer;
+    stderrSab: SharedArrayBuffer;
+    stdinSab: SharedArrayBuffer;
+} | {
+    type: 'process:exit';
+    pid: number;
+    code: number;
+} | {
+    type: 'port:listen';
+    port: number;
+} | {
+    type: 'port:close';
+    port: number;
+} | {
+    type: 'toolchain:needed';
+    pkg: string;
+} | {
+    type: 'oom';
+    message: string;
+};
+
+export { }