@superhq/shuru 0.2.0 → 0.4.0

package/README.md

@@ -15,14 +15,37 @@ 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
+// Filesystem operations
+await sb.mkdir("/workspace/src");
+const entries = await sb.readDir("/workspace"); // { name, type, size }[]
+const info = await sb.stat("/tmp/app.ts");      // { size, mode, mtime, isDir, ... }
+await sb.copy("/tmp/app.ts", "/tmp/backup.ts");
+await sb.rename("/tmp/backup.ts", "/tmp/old.ts");
+await sb.chmod("/tmp/app.ts", 0o755);
+await sb.remove("/tmp/old.ts");
+if (await sb.exists("/tmp/app.ts")) { /* ... */ }
+
+// Checkpoint — save disk state and stop
+await sb.checkpoint("my-env");
 ```
 
 ### Start from a checkpoint
@@ -58,8 +81,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 (see below) |
-| `network` | `NetworkConfig` | Network access policy (see below) |
+| `secrets` | `Record<string, SecretConfig>` | Secrets to inject via proxy |
+| `network` | `NetworkConfig` | Network access policy |
 | `shuruBin` | `string` | Path to shuru binary (default: `"shuru"`) |
 
 ## API
@@ -70,7 +93,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>`
 
@@ -80,6 +143,50 @@ Read a file from the VM. Returns raw bytes. Use `new TextDecoder().decode(data)`
 
 Write a file to the VM. Accepts raw bytes or a string.
 
+### `sandbox.mkdir(path, opts?): Promise<void>`
+
+Create a directory. Creates parent directories by default.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `recursive` | `boolean` | `true` | Create parent directories |
+
+### `sandbox.readDir(path): Promise<DirEntry[]>`
+
+List the contents of a directory. Each entry has `name`, `type` (`"file"`, `"dir"`, or `"symlink"`), and `size` in bytes.
+
+### `sandbox.stat(path): Promise<StatResult>`
+
+Get file metadata. Returns `{ size, mode, mtime, isDir, isFile, isSymlink }`. `mtime` is seconds since the Unix epoch. `mode` includes the file type bits (e.g. `0o100644` for a regular file with 644 permissions).
+
+### `sandbox.remove(path, opts?): Promise<void>`
+
+Delete a file or empty directory. To remove a non-empty directory, pass `{ recursive: true }`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `recursive` | `boolean` | `false` | Remove directories and their contents |
+
+### `sandbox.rename(oldPath, newPath): Promise<void>`
+
+Move or rename a file or directory within the guest filesystem. Atomic on the same filesystem.
+
+### `sandbox.copy(src, dst, opts?): Promise<void>`
+
+Copy a file. To copy a directory tree, pass `{ recursive: true }`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `recursive` | `boolean` | `false` | Copy directories recursively |
+
+### `sandbox.chmod(path, mode): Promise<void>`
+
+Change file permissions. `mode` is a numeric permission value (e.g. `0o755`).
+
+### `sandbox.exists(path): Promise<boolean>`
+
+Check if a path exists. Returns `true` if it does, `false` otherwise.
+
 ### `sandbox.checkpoint(name): Promise<void>`
 
 Save the VM's disk state and stop the VM. To continue working, call `Sandbox.start({ from: name })`.
@@ -116,6 +223,17 @@ const sb = await Sandbox.start({
 
 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.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -1,7 +1,17 @@
+export { SandboxProcess } from "./process-handle";
 export { Sandbox } from "./sandbox";
 export type {
+	CopyOptions,
+	DirEntry,
+	ExecOptions,
 	ExecResult,
+	FileChangeEvent,
+	MkdirOptions,
 	NetworkConfig,
+	RemoveOptions,
 	SecretConfig,
+	SpawnOptions,
 	StartOptions,
+	StatResult,
+	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,33 @@
 import { ShuruProcess } from "./process";
-import type { ExecResult, StartOptions } from "./types";
+import { SandboxProcess } from "./process-handle";
+import type {
+	CopyOptions,
+	DirEntry,
+	ExecOptions,
+	ExecResult,
+	FileChangeEvent,
+	MkdirOptions,
+	RemoveOptions,
+	SpawnOptions,
+	StartOptions,
+	StatResult,
+	WatchOptions,
+} from "./types";
 
 const Method = {
 	EXEC: "exec",
+	SPAWN: "spawn",
 	READ_FILE: "read_file",
 	WRITE_FILE: "write_file",
 	CHECKPOINT: "checkpoint",
+	WATCH: "watch",
+	MKDIR: "mkdir",
+	READ_DIR: "read_dir",
+	STAT: "stat",
+	REMOVE: "remove",
+	RENAME: "rename",
+	COPY: "copy",
+	CHMOD: "chmod",
 } as const;
 
 export class Sandbox {
@@ -26,10 +48,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 +69,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 };
@@ -53,6 +109,74 @@ export class Sandbox {
 		await this.proc.send(Method.WRITE_FILE, { path, content: b64 });
 	}
 
+	async mkdir(path: string, opts?: MkdirOptions): Promise<void> {
+		await this.proc.send(Method.MKDIR, {
+			path,
+			recursive: opts?.recursive ?? true,
+		});
+	}
+
+	async readDir(path: string): Promise<DirEntry[]> {
+		const resp = await this.proc.send(Method.READ_DIR, { path });
+		const r = resp.result as { entries: DirEntry[] };
+		return r.entries;
+	}
+
+	async stat(path: string): Promise<StatResult> {
+		const resp = await this.proc.send(Method.STAT, { path });
+		const r = resp.result as {
+			size: number;
+			mode: number;
+			mtime: number;
+			is_dir: boolean;
+			is_file: boolean;
+			is_symlink: boolean;
+		};
+		return {
+			size: r.size,
+			mode: r.mode,
+			mtime: r.mtime,
+			isDir: r.is_dir,
+			isFile: r.is_file,
+			isSymlink: r.is_symlink,
+		};
+	}
+
+	async remove(path: string, opts?: RemoveOptions): Promise<void> {
+		await this.proc.send(Method.REMOVE, {
+			path,
+			recursive: opts?.recursive ?? false,
+		});
+	}
+
+	async rename(oldPath: string, newPath: string): Promise<void> {
+		await this.proc.send(Method.RENAME, {
+			old_path: oldPath,
+			new_path: newPath,
+		});
+	}
+
+	async copy(src: string, dst: string, opts?: CopyOptions): Promise<void> {
+		await this.proc.send(Method.COPY, {
+			src,
+			dst,
+			recursive: opts?.recursive ?? false,
+		});
+	}
+
+	async chmod(path: string, mode: number): Promise<void> {
+		await this.proc.send(Method.CHMOD, { path, mode });
+	}
+
+	async exists(path: string): Promise<boolean> {
+		try {
+			await this.stat(path);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
 	async checkpoint(name: string): Promise<void> {
 		await this.proc.send(Method.CHECKPOINT, { name });
 		this.stopped = true;

package/src/types.ts

@@ -29,6 +29,57 @@ 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";
+}
+
+// --- Filesystem types ---
+
+export interface DirEntry {
+	name: string;
+	type: "file" | "dir" | "symlink";
+	size: number;
+}
+
+export interface StatResult {
+	size: number;
+	mode: number;
+	/** Seconds since Unix epoch */
+	mtime: number;
+	isDir: boolean;
+	isFile: boolean;
+	isSymlink: boolean;
+}
+
+export interface MkdirOptions {
+	recursive?: boolean;
+}
+
+export interface RemoveOptions {
+	recursive?: boolean;
+}
+
+export interface CopyOptions {
+	recursive?: boolean;
+}
+
 // --- JSON-RPC 2.0 wire types (internal) ---
 
 export interface JsonRpcResult {
@@ -46,6 +97,7 @@ export interface JsonRpcError {
 export interface JsonRpcNotification {
 	jsonrpc: "2.0";
 	method: string;
+	params?: Record<string, unknown>;
 }
 
 export type JsonRpcResponse =