smolmachines 0.0.1 → 0.1.0

package/README.md

@@ -1,12 +1,86 @@
-# smolmachines
+# smol (Node SDK)
 
-**Name reserved.** This is a pre-release placeholder (`0.0.1`).
+Embed isolated **microVM sandboxes** directly in your Node.js code — no server to
+run. The smolvm engine is linked in-process via a native addon.
 
-The official **smolmachines** SDK — embed isolated microVM sandboxes directly in
-your code, running locally (embedded) or on the smolfleet cloud — ships in the
-`0.1.0`+ release.
+> **Supported platforms** (native *local* transport): macOS **Apple Silicon**, and
+> **Linux x64/arm64 with glibc ≥ 2.34** (RHEL 9, Ubuntu 22.04+, Debian 12, Amazon
+> Linux 2023). The **cloud** transport works anywhere the package installs.
+> Not yet prebuilt: macOS Intel, and Linux with glibc < 2.34.
 
-- Project: https://github.com/smol-machines/smol
-- Site: https://smolmachines.com
+Run the **same code** against the local embedded engine or the smolfleet **cloud** —
+the backend is chosen by `ConnectOptions`:
 
-Apache-2.0.
+```ts
+// Local (embedded, default) — no server, no config:
+const local = await Machine.create({ resources: { cpus: 2, memoryMb: 1024 } });
+
+// Cloud (smolfleet) — pass an API key, or set SMOL_CLOUD_TOKEN (e.g. via `smol login`):
+const cloud = await Machine.create(
+  { image: 'python:3.12' },
+  { target: 'cloud', apiKey: process.env.SMOL_CLOUD_TOKEN },
+);
+const res = await cloud.exec(['python', '-c', 'print(40 + 2)']);
+```
+
+Cloud-only gaps (`run`, `execStream`, `pullImage`, `listImages`) throw `NotSupportedError`;
+the common surface (create/exec/files/state/stop/delete) is identical on both.
+
+## Install
+
+```bash
+npm install smolmachines
+```
+
+Requires Node.js ≥ 18 on a host the engine supports (macOS Apple Silicon, or Linux
+with KVM).
+
+## Usage
+
+```ts
+import { Machine } from 'smolmachines';
+
+const m = await Machine.create({ resources: { cpus: 2, memoryMb: 1024 } });
+try {
+  // Run a command in a container image
+  const res = await m.run('python:3.12', ['python', '-c', 'print(2 ** 10)']);
+  res.assertSuccess();
+  console.log(res.stdout); // "1024\n"
+
+  // Or exec directly in the VM, move files in/out
+  await m.writeFile('/tmp/hello.txt', 'hi');
+  const back = await m.readFile('/tmp/hello.txt');
+  console.log(back.toString()); // "hi"
+} finally {
+  await m.delete();
+}
+```
+
+## API
+
+- `Machine.create(config?, conn?)` — create and start a machine.
+- `machine.exec(command, opts?)` / `machine.run(image, command, opts?)` → `ExecResult`.
+- `machine.execStream(command, opts?)` → `AsyncGenerator<ExecEvent>`.
+- `machine.readFile(path)` / `machine.writeFile(path, data, mode?)`.
+- `machine.pullImage(image)` / `machine.listImages()`.
+- `machine.stop()` / `machine.delete()` / `await machine.state()` → `"running" | "stopped"`.
+
+Errors are typed: `SmolError` (with `.code`), `ExecutionError`, `NotSupportedError`, `InvalidConfigError`.
+
+## Building from source
+
+This package's native core lives alongside it (Rust, `src/*.rs`) and links the
+sibling `smolvm` repo's engine + `libkrun`. From this directory:
+
+```bash
+npm install
+npm run build        # napi build (native) + tsc (types) + bundle
+```
+
+The native build needs the Rust toolchain, `@napi-rs/cli`, and `libkrun` available
+in the `smolvm` repo's `lib/` (this package expects the `smolvm` repo checked out
+three levels up).
+
+## License
+
+Apache-2.0

package/dist/assets.d.ts

@@ -0,0 +1,14 @@
+/** Auto-wiring for bundled native assets.
+ *
+ *  Points the engine at the package's bundled, signed boot helper and hypervisor
+ *  libraries so the SDK works on a plain `node` with no manual env setup:
+ *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
+ *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
+ *      `node` needs no entitlement).
+ *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
+ *
+ *  A user-provided value always wins. Exposed as a function (and self-invoked)
+ *  so it runs reliably regardless of import elision/ordering — `native.ts` calls
+ *  it before loading the addon.
+ */
+export declare function wireBundledAssets(): void;

package/dist/assets.js

@@ -0,0 +1,45 @@
+"use strict";
+/** Auto-wiring for bundled native assets.
+ *
+ *  Points the engine at the package's bundled, signed boot helper and hypervisor
+ *  libraries so the SDK works on a plain `node` with no manual env setup:
+ *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
+ *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
+ *      `node` needs no entitlement).
+ *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
+ *
+ *  A user-provided value always wins. Exposed as a function (and self-invoked)
+ *  so it runs reliably regardless of import elision/ordering — `native.ts` calls
+ *  it before loading the addon.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wireBundledAssets = wireBundledAssets;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+let wired = false;
+function wireBundledAssets() {
+    if (wired)
+        return;
+    wired = true;
+    const platformArch = `${process.platform}-${process.arch}`;
+    const helperName = process.platform === 'win32' ? 'smol-vmm.exe' : 'smol-vmm';
+    // `__dirname` is the package root from source (tsx) and `dist/` when built —
+    // check both layouts.
+    const candidates = [
+        (0, node_path_1.join)(__dirname, 'native', platformArch),
+        (0, node_path_1.join)(__dirname, '..', 'native', platformArch),
+    ];
+    for (const nativeDir of candidates) {
+        if (!(0, node_fs_1.existsSync)(nativeDir))
+            continue;
+        const helper = (0, node_path_1.join)(nativeDir, helperName);
+        if (!process.env.SMOLVM_BOOT_BINARY && (0, node_fs_1.existsSync)(helper)) {
+            process.env.SMOLVM_BOOT_BINARY = helper;
+        }
+        if (!process.env.SMOLVM_LIB_DIR) {
+            process.env.SMOLVM_LIB_DIR = nativeDir;
+        }
+        return;
+    }
+}
+wireBundledAssets();

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/** Typed errors for the `smol` SDK.
+ *
+ *  The native addon reports errors as `Error` objects whose message is
+ *  prefixed with a bracketed code, e.g. `"[KVM_UNAVAILABLE] …"`. We parse that
+ *  back into a typed hierarchy so callers can branch on `err.code` /`instanceof`.
+ */
+export declare class SmolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** The active backend can't serve this operation (e.g. volumes on local). */
+export declare class NotSupportedError extends SmolError {
+    constructor(message: string);
+}
+/** A required configuration value is missing or invalid (a usage error). */
+export declare class InvalidConfigError extends SmolError {
+    constructor(message: string);
+}
+/** A command ran but exited non-zero (raised by `ExecResult.assertSuccess()`). */
+export declare class ExecutionError extends SmolError {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(exitCode: number, stdout: string, stderr: string);
+}
+/** Convert any error thrown by the native addon into a typed `SmolError`. */
+export declare function wrapNativeError(err: unknown): SmolError;

package/dist/errors.js

@@ -0,0 +1,53 @@
+"use strict";
+/** Typed errors for the `smol` SDK.
+ *
+ *  The native addon reports errors as `Error` objects whose message is
+ *  prefixed with a bracketed code, e.g. `"[KVM_UNAVAILABLE] …"`. We parse that
+ *  back into a typed hierarchy so callers can branch on `err.code` /`instanceof`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionError = exports.InvalidConfigError = exports.NotSupportedError = exports.SmolError = void 0;
+exports.wrapNativeError = wrapNativeError;
+class SmolError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+exports.SmolError = SmolError;
+/** The active backend can't serve this operation (e.g. volumes on local). */
+class NotSupportedError extends SmolError {
+    constructor(message) {
+        super('NOT_SUPPORTED', message);
+    }
+}
+exports.NotSupportedError = NotSupportedError;
+/** A required configuration value is missing or invalid (a usage error). */
+class InvalidConfigError extends SmolError {
+    constructor(message) {
+        super('INVALID_CONFIG', message);
+    }
+}
+exports.InvalidConfigError = InvalidConfigError;
+/** A command ran but exited non-zero (raised by `ExecResult.assertSuccess()`). */
+class ExecutionError extends SmolError {
+    constructor(exitCode, stdout, stderr) {
+        super('COMMAND_FAILED', `Command exited with code ${exitCode}`);
+        this.exitCode = exitCode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+exports.ExecutionError = ExecutionError;
+const BRACKETED = /^\[([A-Z_]+)\]\s*(.*)$/s;
+/** Convert any error thrown by the native addon into a typed `SmolError`. */
+function wrapNativeError(err) {
+    if (err instanceof SmolError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    const m = BRACKETED.exec(message);
+    if (m)
+        return new SmolError(m[1], m[2]);
+    return new SmolError('SMOLVM_ERROR', message);
+}