@superhq/shuru 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,88 @@
+# @superhq/shuru
+
+TypeScript SDK for [shuru](https://github.com/superhq-ai/shuru) — programmatic access to ephemeral Linux microVMs on macOS.
+
+## Install
+
+```sh
+bun add @superhq/shuru
+```
+
+## Usage
+
+```ts
+import { Sandbox } from "@superhq/shuru";
+
+const sb = await Sandbox.start();
+
+const result = await sb.exec("echo hello");
+console.log(result.stdout); // "hello\n"
+
+await sb.writeFile("/tmp/app.ts", "console.log('hi')");
+const content = await sb.readFile("/tmp/app.ts");
+
+await sb.checkpoint("my-env"); // saves disk state and stops the VM
+```
+
+### Start from a checkpoint
+
+```ts
+const sb = await Sandbox.start({ from: "my-env" });
+```
+
+### Options
+
+```ts
+const sb = await Sandbox.start({
+  from: "my-env",
+  cpus: 4,
+  memory: 4096,
+  diskSize: 8192,
+  allowNet: true,
+  ports: ["8080:80"],
+  mounts: { "./src": "/workspace" },
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `from` | `string` | Checkpoint name to start from |
+| `cpus` | `number` | Number of vCPUs |
+| `memory` | `number` | Memory in MB |
+| `diskSize` | `number` | Disk size in MB |
+| `allowNet` | `boolean` | Enable network access |
+| `ports` | `string[]` | Port forwards (`"host:guest"`) |
+| `mounts` | `Record<string, string>` | Directory mounts (`{ hostPath: guestPath }`) |
+| `shuruBin` | `string` | Path to shuru binary (default: `"shuru"`) |
+
+## API
+
+### `Sandbox.start(opts?): Promise<Sandbox>`
+
+Boot a new microVM. Returns when the VM is ready.
+
+### `sandbox.exec(command): Promise<ExecResult>`
+
+Run a shell command in the VM. Returns `{ stdout, stderr, exitCode }`.
+
+### `sandbox.readFile(path): Promise<string>`
+
+Read a file from the VM.
+
+### `sandbox.writeFile(path, content): Promise<void>`
+
+Write a file to the VM.
+
+### `sandbox.checkpoint(name): Promise<void>`
+
+Save the VM's disk state and stop the VM. To continue working, call `Sandbox.start({ from: name })`.
+
+### `sandbox.stop(): Promise<void>`
+
+Stop the VM without saving. All changes are discarded.
+
+## Requirements
+
+- macOS 14+ on Apple Silicon
+- [shuru CLI](https://github.com/superhq-ai/shuru) installed
+- Bun runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superhq/shuru",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/sandbox.ts

@@ -3,6 +3,7 @@ import type { ExecResult, StartOptions } from "./types";
 
 export class Sandbox {
 	private proc: ShuruProcess;
+	private stopped = false;
 
 	private constructor(proc: ShuruProcess) {
 		this.proc = proc;
@@ -70,9 +71,13 @@ export class Sandbox {
 		if (resp.type !== "checkpoint") {
 			throw new Error(`unexpected response type: ${resp.type}`);
 		}
+		this.stopped = true;
+		await this.proc.stop();
 	}
 
 	async stop(): Promise<void> {
+		if (this.stopped) return;
+		this.stopped = true;
 		await this.proc.stop();
 	}
 }