@boxlite-ai/boxlite 0.1.0

package/dist/simplebox.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleBox = void 0;
+const native_1 = require("./native");
+/**
+ * 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;
+ *   }
+ * }
+ * ```
+ */
+class SimpleBox {
+    /**
+     * 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 = {}) {
+        const JsBoxlite = (0, native_1.getJsBoxlite)();
+        // Use provided runtime or get global default
+        if (options.runtime) {
+            this._runtime = options.runtime;
+        }
+        else {
+            this._runtime = JsBoxlite.withDefaultConfig();
+        }
+        // Convert options to BoxOptions format
+        const boxOpts = {
+            image: options.image,
+            cpus: options.cpus,
+            memoryMib: options.memoryMib,
+            autoRemove: options.autoRemove ?? true,
+            detach: options.detach ?? false,
+            workingDir: options.workingDir,
+            env: options.env
+                ? Object.entries(options.env).map(([key, value]) => ({ key, value }))
+                : undefined,
+            volumes: options.volumes,
+            ports: options.ports,
+        };
+        this._name = options.name;
+        this._box = this._runtime.create(boxOpts, options.name);
+    }
+    /**
+     * Get the box ID (ULID format).
+     */
+    get id() {
+        return this._box.id;
+    }
+    /**
+     * Get the box name (if set).
+     */
+    get name() {
+        return this._name;
+    }
+    /**
+     * Get box metadata.
+     */
+    info() {
+        return this._box.info();
+    }
+    async exec(cmd, argsOrFirstArg, envOrSecondArg, ...restArgs) {
+        // Parse overloaded arguments
+        let args;
+        let env;
+        if (Array.isArray(argsOrFirstArg)) {
+            // exec(cmd, args[], env?)
+            args = argsOrFirstArg;
+            env = envOrSecondArg;
+        }
+        else {
+            // exec(cmd, ...args, env?)
+            // Collect all arguments
+            const allArgs = [
+                argsOrFirstArg,
+                envOrSecondArg,
+                ...restArgs,
+            ].filter(a => a !== undefined);
+            // Check if last arg is env object (before filtering to strings)
+            const lastArg = allArgs[allArgs.length - 1];
+            if (lastArg && typeof lastArg === 'object' && !Array.isArray(lastArg)) {
+                env = lastArg;
+                args = allArgs.slice(0, -1).filter((a) => typeof a === 'string');
+            }
+            else {
+                env = undefined;
+                args = allArgs.filter((a) => typeof a === 'string');
+            }
+        }
+        // Convert env to array of tuples
+        const envArray = env
+            ? Object.entries(env).map(([k, v]) => [k, v])
+            : undefined;
+        // Execute via Rust (returns Execution)
+        const execution = await this._box.exec(cmd, args, envArray, false);
+        // Collect stdout and stderr
+        const stdoutLines = [];
+        const stderrLines = [];
+        // Get streams
+        let stdout;
+        let stderr;
+        try {
+            stdout = await execution.stdout();
+        }
+        catch (err) {
+            // Stream not available (expected for some commands)
+            stdout = null;
+        }
+        try {
+            stderr = await execution.stderr();
+        }
+        catch (err) {
+            // Stream not available (expected for some commands)
+            stderr = null;
+        }
+        // Read stdout
+        if (stdout) {
+            try {
+                while (true) {
+                    const line = await stdout.next();
+                    if (line === null)
+                        break;
+                    stdoutLines.push(line);
+                }
+            }
+            catch (err) {
+                // Stream ended or error occurred
+            }
+        }
+        // Read stderr
+        if (stderr) {
+            try {
+                while (true) {
+                    const line = await stderr.next();
+                    if (line === null)
+                        break;
+                    stderrLines.push(line);
+                }
+            }
+            catch (err) {
+                // Stream ended or error occurred
+            }
+        }
+        // Wait for completion
+        const result = await execution.wait();
+        return {
+            exitCode: result.exitCode,
+            stdout: stdoutLines.join(''),
+            stderr: stderrLines.join(''),
+        };
+    }
+    /**
+     * 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');
+     * ```
+     */
+    async stop() {
+        await this._box.stop();
+    }
+    /**
+     * 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
+     * ```
+     */
+    async [Symbol.asyncDispose]() {
+        await this.stop();
+    }
+}
+exports.SimpleBox = SimpleBox;
+//# sourceMappingURL=simplebox.js.map

package/dist/simplebox.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@boxlite-ai/boxlite",
+  "version": "0.1.0",
+  "description": "BoxLite - Embeddable micro-VM runtime for secure, isolated code execution",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:debug": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0-alpha.62",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.2.0",
+    "vitest": "^2.0.0"
+  },
+  "optionalDependencies": {
+    "@boxlite-ai/boxlite-darwin-arm64": "0.1.0",
+    "@boxlite-ai/boxlite-darwin-x64": "0.1.0",
+    "@boxlite-ai/boxlite-linux-x64-gnu": "0.1.0",
+    "@boxlite-ai/boxlite-linux-arm64-gnu": "0.1.0"
+  },
+  "keywords": [
+    "boxlite",
+    "sandbox",
+    "container",
+    "virtualization",
+    "vm",
+    "kvm",
+    "hypervisor",
+    "isolation",
+    "security",
+    "code-execution"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boxlite-ai/boxlite.git",
+    "directory": "sdks/node"
+  },
+  "bugs": {
+    "url": "https://github.com/boxlite-ai/boxlite/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Dorian Zheng <xingzhengde72@gmail.com>",
+  "dependencies": {
+    "@node-rs/helper": "^1.6.0"
+  }
+}