@superhq/shuru 0.1.0

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@superhq/shuru",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src"],
+  "scripts": {
+    "test": "bun test test/unit/",
+    "test:integration": "bun test test/integration/",
+    "check": "biome check src/",
+    "format": "biome check --write src/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.5",
+    "@types/bun": "^1.3.10"
+  }
+}

package/src/index.ts

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

package/src/process.ts

@@ -0,0 +1,144 @@
+import type { Subprocess } from "bun";
+import type { StdioResponse } from "./types";
+
+interface PendingRequest {
+	resolve: (value: StdioResponse) => void;
+	reject: (reason: Error) => void;
+}
+
+export class ShuruProcess {
+	private proc: Subprocess<"pipe", "pipe", "inherit"> | null = null;
+	private pending = new Map<string, PendingRequest>();
+	private idCounter = 0;
+
+	async start(args: string[]): Promise<void> {
+		this.proc = Bun.spawn(args, {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "inherit",
+		});
+
+		this.readLoop();
+
+		await new Promise<void>((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				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);
+				},
+			});
+		});
+	}
+
+	async send(msg: Record<string, unknown>): Promise<StdioResponse> {
+		if (!this.proc) throw new Error("shuru process not started");
+
+		const id = String(++this.idCounter);
+		const line = `${JSON.stringify({ id, ...msg })}\n`;
+		const proc = this.proc;
+
+		return new Promise<StdioResponse>((resolve, reject) => {
+			this.pending.set(id, { resolve, reject });
+			proc.stdin.write(line);
+			proc.stdin.flush();
+		});
+	}
+
+	async stop(): Promise<void> {
+		if (!this.proc) return;
+
+		try {
+			this.proc.stdin.end();
+		} catch {
+			// stdin may already be closed
+		}
+
+		const exited = this.proc.exited;
+		const timeout = new Promise<never>((_, reject) =>
+			setTimeout(
+				() => reject(new Error("shuru: shutdown timed out (5s)")),
+				5_000,
+			),
+		);
+
+		try {
+			await Promise.race([exited, timeout]);
+		} catch {
+			this.proc.kill();
+			await this.proc.exited;
+		}
+
+		for (const [, req] of this.pending) {
+			req.reject(new Error("shuru process stopped"));
+		}
+		this.pending.clear();
+		this.proc = null;
+	}
+
+	private async readLoop(): Promise<void> {
+		if (!this.proc?.stdout) return;
+
+		const reader = this.proc.stdout.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+
+		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() ?? "";
+
+				for (const line of lines) {
+					if (!line) continue;
+					try {
+						this.dispatch(JSON.parse(line) as StdioResponse);
+					} catch {
+						// malformed line
+					}
+				}
+			}
+		} catch {
+			// stream closed
+		}
+
+		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);
+			}
+			return;
+		}
+
+		const { id } = msg;
+		if (!id) return;
+
+		const req = this.pending.get(id);
+		if (!req) return;
+		this.pending.delete(id);
+
+		if (msg.type === "error") {
+			req.reject(new Error(msg.error));
+		} else {
+			req.resolve(msg);
+		}
+	}
+}

package/src/sandbox.ts

@@ -0,0 +1,103 @@
+import { ShuruProcess } from "./process";
+import type { ExecResult, StartOptions } from "./types";
+
+export class Sandbox {
+	private proc: ShuruProcess;
+
+	private constructor(proc: ShuruProcess) {
+		this.proc = proc;
+	}
+
+	static async start(opts: StartOptions = {}): Promise<Sandbox> {
+		const bin = opts.shuruBin ?? "shuru";
+		const args = buildArgs(bin, opts);
+
+		const proc = new ShuruProcess();
+		await proc.start(args);
+
+		return new Sandbox(proc);
+	}
+
+	async exec(command: string): Promise<ExecResult> {
+		const resp = await this.proc.send({
+			type: "exec",
+			argv: ["sh", "-c", command],
+		});
+		if (resp.type !== "exec") {
+			throw new Error(`unexpected response type: ${resp.type}`);
+		}
+		return {
+			stdout: resp.stdout,
+			stderr: resp.stderr,
+			exitCode: resp.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 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 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}`);
+		}
+	}
+
+	async stop(): Promise<void> {
+		await this.proc.stop();
+	}
+}
+
+/** @internal exported for testing */
+export function buildArgs(bin: string, opts: StartOptions): string[] {
+	const args = [...bin.split(/\s+/), "run", "--stdio"];
+
+	if (opts.from) args.push("--from", opts.from);
+	if (opts.cpus) args.push("--cpus", String(opts.cpus));
+	if (opts.memory) args.push("--memory", String(opts.memory));
+	if (opts.diskSize) args.push("--disk-size", String(opts.diskSize));
+	if (opts.allowNet) args.push("--allow-net");
+
+	if (opts.ports) {
+		for (const p of opts.ports) {
+			args.push("-p", p);
+		}
+	}
+
+	if (opts.mounts) {
+		for (const [host, guest] of Object.entries(opts.mounts)) {
+			args.push("--mount", `${host}:${guest}`);
+		}
+	}
+
+	return args;
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export interface StartOptions {
+	from?: string;
+	cpus?: number;
+	memory?: number;
+	diskSize?: number;
+	allowNet?: boolean;
+	ports?: string[];
+	mounts?: Record<string, string>;
+	shuruBin?: string;
+}
+
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	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 };