@boxlite-ai/boxlite 0.1.0

package/dist/interactivebox.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * InteractiveBox - Interactive terminal sessions with PTY support.
+ *
+ * Provides automatic PTY-based interactive sessions, similar to `docker exec -it`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractiveBox = void 0;
+const native_1 = require("./native");
+/**
+ * Interactive box with automatic PTY and terminal forwarding.
+ *
+ * When used as a context manager, automatically:
+ * 1. Auto-detects terminal size (like Docker)
+ * 2. Starts a shell with PTY
+ * 3. Sets local terminal to raw mode
+ * 4. Forwards stdin/stdout bidirectionally
+ * 5. Restores terminal mode on exit
+ *
+ * ## Example
+ *
+ * ```typescript
+ * const box = new InteractiveBox({ image: 'alpine:latest' });
+ * try {
+ *   await box.start();
+ *   // You're now in an interactive shell!
+ *   // Type commands, see output in real-time
+ *   // Type "exit" to close
+ *   await box.wait();
+ * } finally {
+ *   await box.stop();
+ * }
+ * ```
+ *
+ * Or with async disposal (TypeScript 5.2+):
+ *
+ * ```typescript
+ * await using box = new InteractiveBox({ image: 'alpine:latest' });
+ * await box.start();
+ * await box.wait();
+ * // Automatically stopped when leaving scope
+ * ```
+ */
+class InteractiveBox {
+    /**
+     * Create an interactive box.
+     *
+     * @param options - InteractiveBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const box = new InteractiveBox({
+     *   image: 'alpine:latest',
+     *   shell: '/bin/sh',
+     *   tty: true,
+     *   memoryMib: 512,
+     *   cpus: 1
+     * });
+     * ```
+     */
+    constructor(options) {
+        this._ioTasks = [];
+        this._exited = false;
+        const JsBoxlite = (0, native_1.getJsBoxlite)();
+        // Use provided runtime or get global default
+        if (options.runtime) {
+            this._runtime = options.runtime;
+        }
+        else {
+            this._runtime = JsBoxlite.default();
+        }
+        // Create box directly (no SimpleBox wrapper)
+        const { shell = '/bin/sh', tty, env, ...boxOptions } = options;
+        this._box = this._runtime.create(boxOptions, options.name);
+        this._shell = shell;
+        this._env = env;
+        // Determine TTY mode: undefined = auto-detect, true = force, false = disable
+        if (tty === undefined) {
+            this._tty = process.stdin.isTTY ?? false;
+        }
+        else {
+            this._tty = tty;
+        }
+    }
+    /**
+     * Get the box ID (ULID format).
+     */
+    get id() {
+        return this._box.id;
+    }
+    /**
+     * Start the interactive shell session.
+     *
+     * This method:
+     * 1. Starts the shell with PTY
+     * 2. Sets terminal to raw mode (if tty=true)
+     * 3. Begins I/O forwarding
+     *
+     * @example
+     * ```typescript
+     * await box.start();
+     * ```
+     */
+    async start() {
+        // Convert env to array format if provided
+        const envArray = this._env
+            ? Object.entries(this._env).map(([k, v]) => [k, v])
+            : undefined;
+        // Start shell with PTY
+        this._execution = await this._box.exec(this._shell, [], envArray, true);
+        // Get streams
+        try {
+            this._stdin = this._execution.stdin();
+        }
+        catch (err) {
+            // stdin not available
+        }
+        try {
+            this._stdout = this._execution.stdout();
+        }
+        catch (err) {
+            // stdout not available
+        }
+        try {
+            this._stderr = this._execution.stderr();
+        }
+        catch (err) {
+            // stderr not available
+        }
+        // Only set raw mode and start forwarding if tty=true
+        if (this._tty && process.stdin.isTTY) {
+            // Set terminal to raw mode
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            // Start bidirectional I/O forwarding
+            this._ioTasks.push(this._forwardStdin(), this._forwardOutput(), this._forwardStderr(), this._waitForExit());
+        }
+        else {
+            // No I/O forwarding, just wait for execution
+            this._ioTasks.push(this._waitForExit());
+        }
+    }
+    /**
+     * Wait for the shell to exit.
+     *
+     * @example
+     * ```typescript
+     * await box.start();
+     * await box.wait();  // Blocks until shell exits
+     * ```
+     */
+    async wait() {
+        await Promise.all(this._ioTasks);
+    }
+    /**
+     * Stop the box and restore terminal settings.
+     *
+     * @example
+     * ```typescript
+     * await box.stop();
+     * ```
+     */
+    async stop() {
+        // Restore terminal settings
+        if (this._tty && process.stdin.isTTY) {
+            try {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+            }
+            catch (err) {
+                // Ignore errors during cleanup
+            }
+        }
+        // Wait for I/O tasks to complete (with timeout)
+        try {
+            await Promise.race([
+                Promise.all(this._ioTasks),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 3000))
+            ]);
+        }
+        catch (err) {
+            // Timeout or error - continue with shutdown
+        }
+        // Stop the box
+        await this._box.stop();
+    }
+    /**
+     * Implement async disposable pattern (TypeScript 5.2+).
+     *
+     * Allows using `await using` syntax for automatic cleanup.
+     *
+     * @example
+     * ```typescript
+     * await using box = new InteractiveBox({ image: 'alpine' });
+     * await box.start();
+     * // Box automatically stopped when leaving scope
+     * ```
+     */
+    async [Symbol.asyncDispose]() {
+        await this.stop();
+    }
+    /**
+     * Forward stdin to PTY (internal).
+     */
+    async _forwardStdin() {
+        if (!this._stdin)
+            return;
+        try {
+            process.stdin.on('data', async (data) => {
+                if (!this._exited && this._stdin) {
+                    try {
+                        await this._stdin.write(data);
+                    }
+                    catch (err) {
+                        // Ignore write errors (box may be shutting down)
+                    }
+                }
+            });
+            // Wait for exit
+            await new Promise((resolve) => {
+                const checkExit = setInterval(() => {
+                    if (this._exited) {
+                        clearInterval(checkExit);
+                        resolve();
+                    }
+                }, 100);
+            });
+        }
+        catch (err) {
+            // Ignore errors during shutdown
+        }
+    }
+    /**
+     * Forward PTY output to stdout (internal).
+     */
+    async _forwardOutput() {
+        if (!this._stdout)
+            return;
+        try {
+            while (true) {
+                const chunk = await this._stdout.next();
+                if (chunk === null)
+                    break;
+                // Write to stdout
+                if (typeof chunk === 'string') {
+                    process.stdout.write(chunk);
+                }
+                else {
+                    process.stdout.write(chunk);
+                }
+            }
+        }
+        catch (err) {
+            // Stream ended or error
+        }
+    }
+    /**
+     * Forward PTY stderr to stderr (internal).
+     */
+    async _forwardStderr() {
+        if (!this._stderr)
+            return;
+        try {
+            while (true) {
+                const chunk = await this._stderr.next();
+                if (chunk === null)
+                    break;
+                // Write to stderr
+                if (typeof chunk === 'string') {
+                    process.stderr.write(chunk);
+                }
+                else {
+                    process.stderr.write(chunk);
+                }
+            }
+        }
+        catch (err) {
+            // Stream ended or error
+        }
+    }
+    /**
+     * Wait for the shell to exit (internal).
+     */
+    async _waitForExit() {
+        try {
+            if (this._execution) {
+                await this._execution.wait();
+            }
+        }
+        catch (err) {
+            // Ignore errors during shutdown
+        }
+        finally {
+            this._exited = true;
+        }
+    }
+}
+exports.InteractiveBox = InteractiveBox;
+//# sourceMappingURL=interactivebox.js.map

package/dist/interactivebox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactivebox.js","sourceRoot":"","sources":["../lib/interactivebox.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,qCAAwC;AAuBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAa,cAAc;IAazB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,OAA8B;QAnBhC,aAAQ,GAAoB,EAAE,CAAC;QAC/B,YAAO,GAAY,KAAK,CAAC;QAmBjC,MAAM,SAAS,GAAG,IAAA,qBAAY,GAAE,CAAC;QAEjC,6CAA6C;QAC7C,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;QACtC,CAAC;QAED,6CAA6C;QAC7C,MAAM,EAAE,KAAK,GAAG,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;QAE/D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAEhB,6EAA6E;QAC7E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK;QACT,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI;YACxB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAqB,CAAC;YACvE,CAAC,CAAC,SAAS,CAAC;QAEd,uBAAuB;QACvB,IAAI,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAExE,cAAc;QACd,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sBAAsB;QACxB,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uBAAuB;QACzB,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uBAAuB;QACzB,CAAC;QAED,qDAAqD;QACrD,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACrC,2BAA2B;YAC3B,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAEvB,qCAAqC;YACrC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChB,IAAI,CAAC,aAAa,EAAE,EACpB,IAAI,CAAC,cAAc,EAAE,EACrB,IAAI,CAAC,cAAc,EAAE,EACrB,IAAI,CAAC,YAAY,EAAE,CACpB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,6CAA6C;YAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI;QACR,4BAA4B;QAC5B,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAChC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACxB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,+BAA+B;YACjC,CAAC;QACH,CAAC;QAED,gDAAgD;QAChD,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC;gBACjB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAC1B,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;aACjF,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,4CAA4C;QAC9C,CAAC;QAED,eAAe;QACf,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;QACzB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,aAAa;QACzB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QAEzB,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE;gBAC9C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBACjC,IAAI,CAAC;wBACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAChC,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,iDAAiD;oBACnD,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,gBAAgB;YAChB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;oBACjC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;wBACjB,aAAa,CAAC,SAAS,CAAC,CAAC;wBACzB,OAAO,EAAE,CAAC;oBACZ,CAAC;gBACH,CAAC,EAAE,GAAG,CAAC,CAAC;YACV,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gCAAgC;QAClC,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc;QAC1B,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,KAAK,KAAK,IAAI;oBAAE,MAAM;gBAE1B,kBAAkB;gBAClB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wBAAwB;QAC1B,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc;QAC1B,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,KAAK,KAAK,IAAI;oBAAE,MAAM;gBAE1B,kBAAkB;gBAClB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wBAAwB;QAC1B,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,YAAY;QACxB,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpB,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gCAAgC;QAClC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;CACF;AAlRD,wCAkRC"}

package/dist/native.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Native module loader for BoxLite Node.js SDK.
+ *
+ * This module centralizes native binding loading to avoid duplication
+ * across simplebox.ts, interactivebox.ts, and index.ts.
+ */
+/**
+ * Load and return the native BoxLite module.
+ *
+ * Uses @node-rs/helper for platform-specific package selection.
+ * Caches the result for subsequent calls.
+ *
+ * @throws Error if the native extension is not found or fails to load
+ */
+export declare function getNativeModule(): any;
+/**
+ * Get the JsBoxlite runtime class from the native module.
+ */
+export declare function getJsBoxlite(): any;
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../lib/native.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,GAAG,CAYrC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,GAAG,CAElC"}

package/dist/native.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Native module loader for BoxLite Node.js SDK.
+ *
+ * This module centralizes native binding loading to avoid duplication
+ * across simplebox.ts, interactivebox.ts, and index.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNativeModule = getNativeModule;
+exports.getJsBoxlite = getJsBoxlite;
+const helper_1 = require("@node-rs/helper");
+const path_1 = require("path");
+// Cache the loaded native module
+let _nativeModule = null;
+/**
+ * Load and return the native BoxLite module.
+ *
+ * Uses @node-rs/helper for platform-specific package selection.
+ * Caches the result for subsequent calls.
+ *
+ * @throws Error if the native extension is not found or fails to load
+ */
+function getNativeModule() {
+    if (_nativeModule === null) {
+        try {
+            _nativeModule = (0, helper_1.loadBinding)((0, path_1.join)(__dirname, '..'), 'boxlite', '@boxlite/boxlite');
+        }
+        catch (err) {
+            throw new Error(`BoxLite native extension not found: ${err}. ` +
+                `Please build the extension first with: npm run build`);
+        }
+    }
+    return _nativeModule;
+}
+/**
+ * Get the JsBoxlite runtime class from the native module.
+ */
+function getJsBoxlite() {
+    return getNativeModule().JsBoxlite;
+}
+//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../lib/native.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAgBH,0CAYC;AAKD,oCAEC;AAjCD,4CAA8C;AAC9C,+BAA4B;AAE5B,iCAAiC;AACjC,IAAI,aAAa,GAAQ,IAAI,CAAC;AAE9B;;;;;;;GAOG;AACH,SAAgB,eAAe;IAC7B,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,aAAa,GAAG,IAAA,oBAAW,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;QACpF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uCAAuC,GAAG,IAAI;gBAC9C,sDAAsD,CACvD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,eAAe,EAAE,CAAC,SAAS,CAAC;AACrC,CAAC"}

package/dist/simplebox.d.ts

@@ -0,0 +1,175 @@
+/**
+ * SimpleBox - Foundation for specialized container types.
+ *
+ * Provides common functionality for all specialized boxes (CodeBox, BrowserBox, etc.)
+ * This class encapsulates common patterns:
+ * 1. Automatic runtime lifecycle management
+ * 2. Command execution with output collection
+ * 3. Try/finally cleanup patterns
+ */
+import type { ExecResult } from './exec';
+type Boxlite = any;
+type Box = any;
+/**
+ * Options for creating a SimpleBox.
+ */
+export interface SimpleBoxOptions {
+    /** Container image to use (e.g., 'python:slim', 'alpine:latest') */
+    image?: string;
+    /** Memory limit in MiB */
+    memoryMib?: number;
+    /** Number of CPU cores */
+    cpus?: number;
+    /** Optional runtime instance (uses global default if not provided) */
+    runtime?: Boxlite;
+    /** Optional name for the box (must be unique) */
+    name?: string;
+    /** Remove box when stopped (default: true) */
+    autoRemove?: boolean;
+    /** Run box in detached mode (survives parent process exit, default: false) */
+    detach?: boolean;
+    /** Working directory inside container */
+    workingDir?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Volume mounts */
+    volumes?: Array<{
+        hostPath: string;
+        guestPath: string;
+        readOnly?: boolean;
+    }>;
+    /** Port mappings */
+    ports?: Array<{
+        hostPort?: number;
+        guestPort: number;
+        protocol?: string;
+    }>;
+}
+/**
+ * Base class for specialized container types.
+ *
+ * This class provides the foundation for all specialized boxes:
+ * - CodeBox: Python code execution sandbox
+ * - BrowserBox: Browser automation
+ * - ComputerBox: Desktop automation
+ * - InteractiveBox: PTY terminal sessions
+ *
+ * ## Usage
+ *
+ * SimpleBox can be used directly for simple command execution:
+ *
+ * ```typescript
+ * const box = new SimpleBox({ image: 'alpine:latest' });
+ * try {
+ *   const result = await box.exec('ls', '-la', '/');
+ *   console.log(result.stdout);
+ * } finally {
+ *   await box.stop();
+ * }
+ * ```
+ *
+ * Or extended for specialized use cases:
+ *
+ * ```typescript
+ * class MyBox extends SimpleBox {
+ *   constructor() {
+ *     super({ image: 'my-custom-image:latest' });
+ *   }
+ *
+ *   async myMethod() {
+ *     const result = await this.exec('my-command');
+ *     return result.stdout;
+ *   }
+ * }
+ * ```
+ */
+export declare class SimpleBox {
+    protected _runtime: Boxlite;
+    protected _box: Box;
+    protected _name?: string;
+    /**
+     * Create a new SimpleBox.
+     *
+     * @param options - Box configuration options
+     *
+     * @example
+     * ```typescript
+     * const box = new SimpleBox({
+     *   image: 'python:slim',
+     *   memoryMib: 512,
+     *   cpus: 2,
+     *   name: 'my-box'
+     * });
+     * ```
+     */
+    constructor(options?: SimpleBoxOptions);
+    /**
+     * Get the box ID (ULID format).
+     */
+    get id(): string;
+    /**
+     * Get the box name (if set).
+     */
+    get name(): string | undefined;
+    /**
+     * Get box metadata.
+     */
+    info(): any;
+    /**
+     * Execute a command in the box and collect the output.
+     *
+     * This is a convenience method that:
+     * 1. Starts the command
+     * 2. Collects all stdout and stderr
+     * 3. Waits for completion
+     * 4. Returns the result
+     *
+     * For streaming output, use the lower-level `this._box.exec()` directly.
+     *
+     * @param cmd - Command to execute (e.g., 'ls', 'python')
+     * @param args - Arguments to the command
+     * @param env - Environment variables (optional)
+     *
+     * @returns Promise resolving to ExecResult with exit code and output
+     *
+     * @example
+     * ```typescript
+     * // Simple execution
+     * const result = await box.exec('ls', '-la', '/');
+     * console.log(`Exit code: ${result.exitCode}`);
+     * console.log(`Output:\n${result.stdout}`);
+     *
+     * // With environment variables
+     * const result = await box.exec('env', [], { FOO: 'bar' });
+     * console.log(result.stdout);
+     * ```
+     */
+    exec(cmd: string, ...args: string[]): Promise<ExecResult>;
+    exec(cmd: string, args: string[], env: Record<string, string>): Promise<ExecResult>;
+    /**
+     * Stop the box.
+     *
+     * Sends a graceful shutdown signal to the VM. If `autoRemove` is true
+     * (default), the box files will be deleted after stopping.
+     *
+     * @example
+     * ```typescript
+     * await box.stop();
+     * console.log('Box stopped');
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Implement async disposable pattern (TypeScript 5.2+).
+     *
+     * Allows using `await using` syntax for automatic cleanup:
+     *
+     * ```typescript
+     * await using box = new SimpleBox({ image: 'alpine' });
+     * // Box automatically stopped when leaving scope
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};
+//# sourceMappingURL=simplebox.d.ts.map

package/dist/simplebox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplebox.d.ts","sourceRoot":"","sources":["../lib/simplebox.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAIzC,KAAK,OAAO,GAAG,GAAG,CAAC;AACnB,KAAK,GAAG,GAAG,GAAG,CAAC;AAIf;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,oBAAoB;IACpB,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IAEH,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,SAAS;IACpB,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC;IACpB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;OAcG;gBACS,OAAO,GAAE,gBAAqB;IA6B1C;;OAEG;IACH,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAE7B;IAED;;OAEG;IACH,IAAI;IAIJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAqGzF;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;;;OASG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}