@superhq/shuru 0.3.1 → 0.4.1

package/README.md

@@ -34,6 +34,16 @@ await sb.watch("/workspace", (event) => {
 await sb.writeFile("/tmp/app.ts", "console.log('hi')");
 const data = await sb.readFile("/tmp/app.ts"); // Uint8Array
 
+// 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");
 ```
@@ -133,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 })`.

package/package.json

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

package/src/index.ts

@@ -1,12 +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/sandbox.ts

@@ -1,11 +1,16 @@
 import { ShuruProcess } from "./process";
 import { SandboxProcess } from "./process-handle";
 import type {
+	CopyOptions,
+	DirEntry,
 	ExecOptions,
 	ExecResult,
 	FileChangeEvent,
+	MkdirOptions,
+	RemoveOptions,
 	SpawnOptions,
 	StartOptions,
+	StatResult,
 	WatchOptions,
 } from "./types";
 
@@ -16,6 +21,13 @@ const Method = {
 	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 {
@@ -97,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;
@@ -119,6 +199,7 @@ export function buildArgs(bin: string, opts: StartOptions): string[] {
 	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.allowHostWrites) args.push("--allow-host-writes");
 
 	if (opts.secrets) {
 		for (const [name, secret] of Object.entries(opts.secrets)) {

package/src/types.ts

@@ -16,7 +16,10 @@ export interface StartOptions {
 	memory?: number;
 	diskSize?: number;
 	allowNet?: boolean;
+	/** Allow :rw mounts to write to host filesystem. Default: false. */
+	allowHostWrites?: boolean;
 	ports?: string[];
+	/** Directory mounts. Key is host path, value is guest path or guest path with mode suffix (e.g. "/workspace" or "/workspace:rw"). */
 	mounts?: Record<string, string>;
 	secrets?: Record<string, SecretConfig>;
 	network?: NetworkConfig;
@@ -50,6 +53,36 @@ export interface FileChangeEvent {
 	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 {