@superhq/shuru 0.1.2 → 0.3.1

package/README.md

@@ -15,14 +15,27 @@ import { Sandbox } from "@superhq/shuru";
 
 const sb = await Sandbox.start();
 
+// Buffered exec — run a command and get the full result
 const result = await sb.exec("echo hello");
 console.log(result.stdout); // "hello\n"
 
+// Streaming spawn — real-time stdout/stderr
+const proc = await sb.spawn("npm run dev");
+proc.on("stdout", (data) => process.stdout.write(data));
+proc.on("stderr", (data) => process.stderr.write(data));
+proc.on("exit", (code) => console.log("exited:", code));
+
+// File watching — guest-side inotify events
+await sb.watch("/workspace", (event) => {
+  console.log(event.event, event.path); // "modify" "/workspace/src/main.ts"
+});
+
+// File I/O
 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
+// Checkpoint — save disk state and stop
+await sb.checkpoint("my-env");
 ```
 
 ### Start from a checkpoint
@@ -42,6 +55,10 @@ const sb = await Sandbox.start({
   allowNet: true,
   ports: ["8080:80"],
   mounts: { "./src": "/workspace" },
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+  network: { allow: ["api.openai.com", "registry.npmjs.org"] },
 });
 ```
 
@@ -54,6 +71,8 @@ const sb = await Sandbox.start({
 | `allowNet` | `boolean` | Enable network access |
 | `ports` | `string[]` | Port forwards (`"host:guest"`) |
 | `mounts` | `Record<string, string>` | Directory mounts (`{ hostPath: guestPath }`) |
+| `secrets` | `Record<string, SecretConfig>` | Secrets to inject via proxy |
+| `network` | `NetworkConfig` | Network access policy |
 | `shuruBin` | `string` | Path to shuru binary (default: `"shuru"`) |
 
 ## API
@@ -64,7 +83,47 @@ 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 }`.
+Run a shell command in the VM. Returns `{ stdout, stderr, exitCode }`. Stdout and stderr are buffered — the promise resolves when the command finishes.
+
+### `sandbox.spawn(command, opts?): Promise<SandboxProcess>`
+
+Spawn a long-running command in the VM. Returns a `SandboxProcess` handle immediately, streaming output in real-time.
+
+```ts
+const proc = await sb.spawn("npm run dev", { cwd: "/workspace" });
+
+proc.on("stdout", (data: Buffer) => { /* real-time chunks */ });
+proc.on("stderr", (data: Buffer) => { /* real-time chunks */ });
+proc.on("exit", (code: number) => { /* process exited */ });
+
+proc.write("input to stdin\n"); // write to stdin
+await proc.kill();               // send SIGTERM
+const exitCode = await proc.exited; // await completion
+console.log(proc.pid);             // process ID
+```
+
+**`SpawnOptions`:**
+| Option | Type | Description |
+|--------|------|-------------|
+| `cwd` | `string` | Working directory for the command |
+| `env` | `Record<string, string>` | Environment variables |
+
+### `sandbox.watch(path, handler, opts?): Promise<void>`
+
+Watch a directory for file changes inside the guest VM. Uses guest-side inotify, so it detects writes to tmpfs overlays that host-side watchers cannot see.
+
+```ts
+await sb.watch("/workspace", (event) => {
+  console.log(event.event, event.path);
+  // event.event: "create" | "modify" | "delete" | "rename"
+  // event.path: full path of the changed file
+});
+```
+
+**`WatchOptions`:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `recursive` | `boolean` | `true` | Watch subdirectories recursively |
 
 ### `sandbox.readFile(path): Promise<Uint8Array>`
 
@@ -82,6 +141,45 @@ Save the VM's disk state and stop the VM. To continue working, call `Sandbox.sta
 
 Stop the VM without saving. All changes are discarded.
 
+### Secrets
+
+Secrets keep API keys on the host. The guest receives a random placeholder token; the proxy substitutes the real value only on HTTPS requests to the specified hosts.
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+});
+// Inside the VM, $API_KEY is a placeholder token.
+// Requests to api.openai.com get the real key injected by the proxy.
+```
+
+### Network policy
+
+Restrict which domains the guest can reach:
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  network: { allow: ["api.openai.com", "*.npmjs.org"] },
+});
+```
+
+Omit `network.allow` to allow all domains.
+
+## Concurrency
+
+Multiple `spawn()` calls run concurrently in the same VM. Each gets a unique pid and independent stdout/stderr streams. You can mix `spawn()`, `exec()`, and `watch()` freely:
+
+```ts
+// Start a dev server, run tests, and watch for changes — all at once
+const server = await sb.spawn("npm run dev", { cwd: "/workspace" });
+const watcher = sb.watch("/workspace", (e) => console.log(e));
+const tests = await sb.exec("npm test");
+```
+
 ## Requirements
 
 - macOS 14+ on Apple Silicon

package/package.json

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

package/src/index.ts

@@ -1,2 +1,12 @@
+export { SandboxProcess } from "./process-handle";
 export { Sandbox } from "./sandbox";
-export type { ExecResult, StartOptions } from "./types";
+export type {
+	ExecOptions,
+	ExecResult,
+	FileChangeEvent,
+	NetworkConfig,
+	SecretConfig,
+	SpawnOptions,
+	StartOptions,
+	WatchOptions,
+} from "./types";

package/src/process-handle.ts

@@ -0,0 +1,54 @@
+import type { ShuruProcess } from "./process";
+
+type EventMap = {
+	stdout: (data: Buffer) => void;
+	stderr: (data: Buffer) => void;
+	exit: (code: number) => void;
+};
+
+export class SandboxProcess {
+	readonly pid: string;
+	readonly exited: Promise<number>;
+	private proc: ShuruProcess;
+	private listeners: {
+		stdout: ((data: Buffer) => void)[];
+		stderr: ((data: Buffer) => void)[];
+		exit: ((code: number) => void)[];
+	} = { stdout: [], stderr: [], exit: [] };
+
+	constructor(proc: ShuruProcess, pid: string) {
+		this.proc = proc;
+		this.pid = pid;
+
+		this.exited = new Promise<number>((resolve) => {
+			proc.processHandlers.set(pid, {
+				onStdout: (data) => {
+					for (const h of this.listeners.stdout) h(data);
+				},
+				onStderr: (data) => {
+					for (const h of this.listeners.stderr) h(data);
+				},
+				onExit: (code) => {
+					for (const h of this.listeners.exit) h(code);
+					resolve(code);
+				},
+			});
+		});
+	}
+
+	on<K extends keyof EventMap>(event: K, handler: EventMap[K]): this {
+		this.listeners[event].push(handler);
+		return this;
+	}
+
+	write(data: Buffer | string): void {
+		this.proc.sendNotification("input", {
+			pid: this.pid,
+			data: Buffer.from(data).toString("base64"),
+		});
+	}
+
+	async kill(): Promise<void> {
+		await this.proc.send("kill", { pid: this.pid });
+	}
+}

package/src/process.ts

@@ -1,11 +1,17 @@
 import type { Subprocess } from "bun";
-import type { JsonRpcResponse, JsonRpcResult } from "./types";
+import type { FileChangeEvent, JsonRpcResponse, JsonRpcResult } from "./types";
 
 interface PendingRequest {
 	resolve: (value: JsonRpcResult) => void;
 	reject: (reason: Error) => void;
 }
 
+export interface ProcessEventHandlers {
+	onStdout: (data: Buffer) => void;
+	onStderr: (data: Buffer) => void;
+	onExit: (code: number) => void;
+}
+
 export class ShuruProcess {
 	private proc: Subprocess<"pipe", "pipe", "inherit"> | null = null;
 	private pending = new Map<number, PendingRequest>();
@@ -13,6 +19,12 @@ export class ShuruProcess {
 	private onReady: (() => void) | null = null;
 	private onReadyError: ((err: Error) => void) | null = null;
 
+	/** Handlers for spawned process output/exit, keyed by pid. */
+	readonly processHandlers = new Map<string, ProcessEventHandlers>();
+
+	/** Handler for file change events from the guest watcher. */
+	fileChangeHandler: ((event: FileChangeEvent) => void) | null = null;
+
 	async start(args: string[]): Promise<void> {
 		this.proc = Bun.spawn(args, {
 			stdin: "pipe",
@@ -55,6 +67,14 @@ export class ShuruProcess {
 		});
 	}
 
+	/** Send a fire-and-forget notification (no id, no response expected). */
+	sendNotification(method: string, params: Record<string, unknown>): void {
+		if (!this.proc) throw new Error("shuru process not started");
+		const line = `${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`;
+		this.proc.stdin.write(line);
+		this.proc.stdin.flush();
+	}
+
 	async stop(): Promise<void> {
 		if (!this.proc) return;
 
@@ -132,11 +152,47 @@ export class ShuruProcess {
 	}
 
 	private dispatch(msg: JsonRpcResponse): void {
-		if ("method" in msg && msg.method === "ready") {
-			if (this.onReady) {
-				this.onReady();
-				this.onReady = null;
-				this.onReadyError = null;
+		// Handle notifications (no id)
+		if ("method" in msg && !("id" in msg)) {
+			const params = msg.params as Record<string, unknown> | undefined;
+
+			switch (msg.method) {
+				case "ready": {
+					if (this.onReady) {
+						this.onReady();
+						this.onReady = null;
+						this.onReadyError = null;
+					}
+					return;
+				}
+				case "output": {
+					if (!params) return;
+					const pid = params.pid as string;
+					const h = this.processHandlers.get(pid);
+					if (!h) return;
+					const buf = Buffer.from(params.data as string, "base64");
+					if (params.stream === "stdout") h.onStdout(buf);
+					else if (params.stream === "stderr") h.onStderr(buf);
+					return;
+				}
+				case "exit": {
+					if (!params) return;
+					const pid = params.pid as string;
+					const h = this.processHandlers.get(pid);
+					if (h) {
+						h.onExit(params.code as number);
+						this.processHandlers.delete(pid);
+					}
+					return;
+				}
+				case "file_change": {
+					if (!params) return;
+					this.fileChangeHandler?.({
+						path: params.path as string,
+						event: params.event as FileChangeEvent["event"],
+					});
+					return;
+				}
 			}
 			return;
 		}

package/src/sandbox.ts

@@ -1,11 +1,21 @@
 import { ShuruProcess } from "./process";
-import type { ExecResult, StartOptions } from "./types";
+import { SandboxProcess } from "./process-handle";
+import type {
+	ExecOptions,
+	ExecResult,
+	FileChangeEvent,
+	SpawnOptions,
+	StartOptions,
+	WatchOptions,
+} from "./types";
 
 const Method = {
 	EXEC: "exec",
+	SPAWN: "spawn",
 	READ_FILE: "read_file",
 	WRITE_FILE: "write_file",
 	CHECKPOINT: "checkpoint",
+	WATCH: "watch",
 } as const;
 
 export class Sandbox {
@@ -26,10 +36,15 @@ export class Sandbox {
 		return new Sandbox(proc);
 	}
 
-	async exec(command: string): Promise<ExecResult> {
-		const resp = await this.proc.send(Method.EXEC, {
-			argv: ["sh", "-c", command],
-		});
+	async exec(
+		command: string | string[],
+		opts?: ExecOptions,
+	): Promise<ExecResult> {
+		const argv =
+			typeof command === "string"
+				? [opts?.shell ?? "sh", "-c", command]
+				: command;
+		const resp = await this.proc.send(Method.EXEC, { argv });
 		const r = resp.result as {
 			stdout: string;
 			stderr: string;
@@ -42,6 +57,35 @@ export class Sandbox {
 		};
 	}
 
+	async spawn(
+		command: string | string[],
+		opts?: SpawnOptions,
+	): Promise<SandboxProcess> {
+		const argv =
+			typeof command === "string"
+				? [opts?.shell ?? "sh", "-c", command]
+				: command;
+		const resp = await this.proc.send(Method.SPAWN, {
+			argv,
+			cwd: opts?.cwd,
+			env: opts?.env,
+		});
+		const { pid } = resp.result as { pid: string };
+		return new SandboxProcess(this.proc, pid);
+	}
+
+	async watch(
+		path: string,
+		handler: (event: FileChangeEvent) => void,
+		opts?: WatchOptions,
+	): Promise<void> {
+		this.proc.fileChangeHandler = handler;
+		await this.proc.send(Method.WATCH, {
+			path,
+			recursive: opts?.recursive ?? true,
+		});
+	}
+
 	async readFile(path: string): Promise<Uint8Array> {
 		const resp = await this.proc.send(Method.READ_FILE, { path });
 		const r = resp.result as { content: string };
@@ -76,6 +120,18 @@ export function buildArgs(bin: string, opts: StartOptions): string[] {
 	if (opts.diskSize) args.push("--disk-size", String(opts.diskSize));
 	if (opts.allowNet) args.push("--allow-net");
 
+	if (opts.secrets) {
+		for (const [name, secret] of Object.entries(opts.secrets)) {
+			args.push("--secret", `${name}=${secret.from}@${secret.hosts.join(",")}`);
+		}
+	}
+
+	if (opts.network?.allow) {
+		for (const host of opts.network.allow) {
+			args.push("--allow-host", host);
+		}
+	}
+
 	if (opts.ports) {
 		for (const p of opts.ports) {
 			args.push("-p", p);

package/src/types.ts

@@ -1,3 +1,15 @@
+export interface SecretConfig {
+	/** Host environment variable containing the real value. */
+	from: string;
+	/** Domains where this secret may be sent (e.g. "api.openai.com"). */
+	hosts: string[];
+}
+
+export interface NetworkConfig {
+	/** Allowed domain patterns. Omit to allow all. */
+	allow?: string[];
+}
+
 export interface StartOptions {
 	from?: string;
 	cpus?: number;
@@ -6,6 +18,8 @@ export interface StartOptions {
 	allowNet?: boolean;
 	ports?: string[];
 	mounts?: Record<string, string>;
+	secrets?: Record<string, SecretConfig>;
+	network?: NetworkConfig;
 	shuruBin?: string;
 }
 
@@ -15,6 +29,27 @@ export interface ExecResult {
 	exitCode: number;
 }
 
+export interface ExecOptions {
+	/** Shell to use when command is a string. Defaults to "sh". Ignored when command is an array. */
+	shell?: string;
+}
+
+export interface SpawnOptions {
+	cwd?: string;
+	env?: Record<string, string>;
+	/** Shell to use when command is a string. Defaults to "sh". Ignored when command is an array. */
+	shell?: string;
+}
+
+export interface WatchOptions {
+	recursive?: boolean;
+}
+
+export interface FileChangeEvent {
+	path: string;
+	event: "create" | "modify" | "delete" | "rename";
+}
+
 // --- JSON-RPC 2.0 wire types (internal) ---
 
 export interface JsonRpcResult {
@@ -32,6 +67,7 @@ export interface JsonRpcError {
 export interface JsonRpcNotification {
 	jsonrpc: "2.0";
 	method: string;
+	params?: Record<string, unknown>;
 }
 
 export type JsonRpcResponse =