@superhq/shuru 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,89 @@
+# @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 data = await sb.readFile("/tmp/app.ts"); // Uint8Array
+const text = new TextDecoder().decode(data);
+
+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<Uint8Array>`
+
+Read a file from the VM. Returns raw bytes. Use `new TextDecoder().decode(data)` for text files.
+
+### `sandbox.writeFile(path, content: Uint8Array | string): Promise<void>`
+
+Write a file to the VM. Accepts raw bytes or a string.
+
+### `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,10 +1,15 @@
 {
   "name": "@superhq/shuru",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "files": ["src"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/superhq-ai/shuru",
+    "directory": "packages/sdk"
+  },
   "scripts": {
     "test": "bun test test/unit/",
     "test:integration": "bun test test/integration/",

package/src/index.ts

@@ -1,2 +1,2 @@
 export { Sandbox } from "./sandbox";
-export type { ExecResult, StartOptions, StdioResponse } from "./types";
+export type { ExecResult, StartOptions } from "./types";

package/src/process.ts

@@ -1,15 +1,17 @@
 import type { Subprocess } from "bun";
-import type { StdioResponse } from "./types";
+import type { JsonRpcResponse, JsonRpcResult } from "./types";
 
 interface PendingRequest {
-	resolve: (value: StdioResponse) => void;
+	resolve: (value: JsonRpcResult) => void;
 	reject: (reason: Error) => void;
 }
 
 export class ShuruProcess {
 	private proc: Subprocess<"pipe", "pipe", "inherit"> | null = null;
-	private pending = new Map<string, PendingRequest>();
+	private pending = new Map<number, PendingRequest>();
 	private idCounter = 0;
+	private onReady: (() => void) | null = null;
+	private onReadyError: ((err: Error) => void) | null = null;
 
 	async start(args: string[]): Promise<void> {
 		this.proc = Bun.spawn(args, {
@@ -25,27 +27,28 @@ export class ShuruProcess {
 				reject(new Error("shuru: timed out waiting for ready signal (30s)"));
 			}, 30_000);
 
-			this.pending.set("__ready__", {
-				resolve: () => {
-					clearTimeout(timeout);
-					resolve();
-				},
-				reject: (err: Error) => {
-					clearTimeout(timeout);
-					reject(err);
-				},
-			});
+			this.onReady = () => {
+				clearTimeout(timeout);
+				resolve();
+			};
+			this.onReadyError = (err: Error) => {
+				clearTimeout(timeout);
+				reject(err);
+			};
 		});
 	}
 
-	async send(msg: Record<string, unknown>): Promise<StdioResponse> {
+	send(
+		method: string,
+		params: Record<string, unknown>,
+	): Promise<JsonRpcResult> {
 		if (!this.proc) throw new Error("shuru process not started");
 
-		const id = String(++this.idCounter);
-		const line = `${JSON.stringify({ id, ...msg })}\n`;
+		const id = ++this.idCounter;
+		const line = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
 		const proc = this.proc;
 
-		return new Promise<StdioResponse>((resolve, reject) => {
+		return new Promise<JsonRpcResult>((resolve, reject) => {
 			this.pending.set(id, { resolve, reject });
 			proc.stdin.write(line);
 			proc.stdin.flush();
@@ -88,21 +91,26 @@ export class ShuruProcess {
 
 		const reader = this.proc.stdout.getReader();
 		const decoder = new TextDecoder();
-		let buffer = "";
+		let remainder = "";
 
 		try {
 			while (true) {
 				const { done, value } = await reader.read();
 				if (done) break;
 
-				buffer += decoder.decode(value, { stream: true });
-				const lines = buffer.split("\n");
-				buffer = lines.pop() ?? "";
+				remainder += decoder.decode(value, { stream: true });
+
+				while (true) {
+					const newlineIdx = remainder.indexOf("\n");
+					if (newlineIdx === -1) break;
+					const line = remainder.slice(0, newlineIdx);
+					remainder = remainder.slice(newlineIdx + 1);
 
-				for (const line of lines) {
 					if (!line) continue;
+
 					try {
-						this.dispatch(JSON.parse(line) as StdioResponse);
+						const msg = JSON.parse(line) as JsonRpcResponse;
+						this.dispatch(msg);
 					} catch {
 						// malformed line
 					}
@@ -112,33 +120,38 @@ export class ShuruProcess {
 			// stream closed
 		}
 
+		if (this.onReadyError) {
+			this.onReadyError(new Error("shuru process exited unexpectedly"));
+			this.onReady = null;
+			this.onReadyError = null;
+		}
 		for (const [, req] of this.pending) {
 			req.reject(new Error("shuru process exited unexpectedly"));
 		}
 		this.pending.clear();
 	}
 
-	private dispatch(msg: StdioResponse): void {
-		if (msg.type === "ready") {
-			const req = this.pending.get("__ready__");
-			if (req) {
-				this.pending.delete("__ready__");
-				req.resolve(msg);
+	private dispatch(msg: JsonRpcResponse): void {
+		if ("method" in msg && msg.method === "ready") {
+			if (this.onReady) {
+				this.onReady();
+				this.onReady = null;
+				this.onReadyError = null;
 			}
 			return;
 		}
 
-		const { id } = msg;
-		if (!id) return;
+		if (!("id" in msg) || msg.id == null) return;
+		const id = msg.id as number;
 
 		const req = this.pending.get(id);
 		if (!req) return;
 		this.pending.delete(id);
 
-		if (msg.type === "error") {
-			req.reject(new Error(msg.error));
+		if ("error" in msg) {
+			req.reject(new Error(msg.error.message));
 		} else {
-			req.resolve(msg);
+			req.resolve(msg as JsonRpcResult);
 		}
 	}
 }

package/src/sandbox.ts

@@ -1,8 +1,16 @@
 import { ShuruProcess } from "./process";
 import type { ExecResult, StartOptions } from "./types";
 
+const Method = {
+	EXEC: "exec",
+	READ_FILE: "read_file",
+	WRITE_FILE: "write_file",
+	CHECKPOINT: "checkpoint",
+} as const;
+
 export class Sandbox {
 	private proc: ShuruProcess;
+	private stopped = false;
 
 	private constructor(proc: ShuruProcess) {
 		this.proc = proc;
@@ -19,60 +27,41 @@ export class Sandbox {
 	}
 
 	async exec(command: string): Promise<ExecResult> {
-		const resp = await this.proc.send({
-			type: "exec",
+		const resp = await this.proc.send(Method.EXEC, {
 			argv: ["sh", "-c", command],
 		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
+		const r = resp.result as {
+			stdout: string;
+			stderr: string;
+			exit_code: number;
+		};
 		return {
-			stdout: resp.stdout,
-			stderr: resp.stderr,
-			exitCode: resp.exit_code,
+			stdout: r.stdout,
+			stderr: r.stderr,
+			exitCode: r.exit_code,
 		};
 	}
 
-	async readFile(path: string): Promise<string> {
-		const resp = await this.proc.send({
-			type: "exec",
-			argv: ["cat", path],
-		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
-		if (resp.exit_code !== 0) {
-			throw new Error(
-				`readFile failed (exit ${resp.exit_code}): ${resp.stderr}`,
-			);
-		}
-		return resp.stdout;
+	async readFile(path: string): Promise<Uint8Array> {
+		const resp = await this.proc.send(Method.READ_FILE, { path });
+		const r = resp.result as { content: string };
+		return new Uint8Array(Buffer.from(r.content, "base64"));
 	}
 
-	async writeFile(path: string, content: string): Promise<void> {
-		const b64 = btoa(content);
-		const resp = await this.proc.send({
-			type: "exec",
-			argv: ["sh", "-c", `echo '${b64}' | base64 -d > "$1"`, "--", path],
-		});
-		if (resp.type !== "exec") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
-		if (resp.exit_code !== 0) {
-			throw new Error(
-				`writeFile failed (exit ${resp.exit_code}): ${resp.stderr}`,
-			);
-		}
+	async writeFile(path: string, content: Uint8Array | string): Promise<void> {
+		const b64 = Buffer.from(content).toString("base64");
+		await this.proc.send(Method.WRITE_FILE, { path, content: b64 });
 	}
 
 	async checkpoint(name: string): Promise<void> {
-		const resp = await this.proc.send({ type: "checkpoint", name });
-		if (resp.type !== "checkpoint") {
-			throw new Error(`unexpected response type: ${resp.type}`);
-		}
+		await this.proc.send(Method.CHECKPOINT, { name });
+		this.stopped = true;
+		await this.proc.stop();
 	}
 
 	async stop(): Promise<void> {
+		if (this.stopped) return;
+		this.stopped = true;
 		await this.proc.stop();
 	}
 }

package/src/types.ts

@@ -15,14 +15,26 @@ export interface ExecResult {
 	exitCode: number;
 }
 
-export type StdioResponse =
-	| { type: "ready" }
-	| {
-			type: "exec";
-			id: string;
-			stdout: string;
-			stderr: string;
-			exit_code: number;
-	  }
-	| { type: "checkpoint"; id: string; ok: boolean }
-	| { type: "error"; id: string; error: string };
+// --- JSON-RPC 2.0 wire types (internal) ---
+
+export interface JsonRpcResult {
+	jsonrpc: "2.0";
+	id: number;
+	result: unknown;
+}
+
+export interface JsonRpcError {
+	jsonrpc: "2.0";
+	id: number;
+	error: { code: number; message: string };
+}
+
+export interface JsonRpcNotification {
+	jsonrpc: "2.0";
+	method: string;
+}
+
+export type JsonRpcResponse =
+	| JsonRpcResult
+	| JsonRpcError
+	| JsonRpcNotification;