Read-Write FS (#13)

* Read-Write FS

* knip

Author: cramforce

README.md

@@ -16,7 +16,7 @@ Supports optional network access via `curl` with secure-by-default URL filtering
   - [Basic API](#basic-api)
   - [Configuration](#configuration)
   - [Custom Commands](#custom-commands)
-  - [OverlayFs (Copy-on-Write)](#overlayfs-copy-on-write)
+  - [Filesystem Options](#filesystem-options)
   - [AI SDK Tool](#ai-sdk-tool)
   - [Vercel Sandbox Compatible API](#vercel-sandbox-compatible-api)
   - [CLI Binary](#cli-binary)
@@ -91,31 +91,46 @@ const upper = defineCommand("upper", async (args, ctx) => {
 
 const bash = new Bash({ customCommands: [hello, upper] });
 
-await bash.exec("hello Alice");              // "Hello, Alice!\n"
-await bash.exec("echo 'test' | upper");      // "TEST\n"
+await bash.exec("hello Alice"); // "Hello, Alice!\n"
+await bash.exec("echo 'test' | upper"); // "TEST\n"
 ```
 
 Custom commands receive the full `CommandContext` with access to `fs`, `cwd`, `env`, `stdin`, and `exec` for running subcommands.
 
-### OverlayFs (Copy-on-Write)
+### Filesystem Options
 
-Seed the bash environment with files from a real directory. The agent can read but not write to the real filesystem - all changes stay in memory.
+Three filesystem implementations are available:
+
+**InMemoryFs** (default) - Pure in-memory filesystem, no disk access:
+
+```typescript
+import { Bash } from "just-bash";
+const env = new Bash(); // Uses InMemoryFs by default
+```
+
+**OverlayFs** - Copy-on-write over a real directory. Reads come from disk, writes stay in memory:
 
 ```typescript
-import { Bash, OverlayFs } from "just-bash";
+import { Bash } from "just-bash";
+import { OverlayFs } from "just-bash/fs/overlay-fs";
 
-// Files are mounted at /home/user/project by default
 const overlay = new OverlayFs({ root: "/path/to/project" });
 const env = new Bash({ fs: overlay, cwd: overlay.getMountPoint() });
 
-// Reads come from the real filesystem
-await env.exec("cat package.json"); // reads /path/to/project/package.json
+await env.exec("cat package.json"); // reads from disk
+await env.exec('echo "modified" > package.json'); // stays in memory
+```
+
+**ReadWriteFs** - Direct read-write access to a real directory. Use this if you want the agent to be agle to write to your disk:
+
+```typescript
+import { Bash } from "just-bash";
+import { ReadWriteFs } from "just-bash/fs/read-write-fs";
 
-// Writes stay in memory (real files unchanged)
-await env.exec('echo "modified" > package.json');
+const rwfs = new ReadWriteFs({ root: "/path/to/sandbox" });
+const env = new Bash({ fs: rwfs });
 
-// Custom mount point
-const overlay2 = new OverlayFs({ root: "/path/to/project", mountPoint: "/" });
+await env.exec('echo "hello" > file.txt'); // writes to real filesystem
 ```
 
 ### AI SDK Tool

package.json

@@ -66,7 +66,7 @@
     "build:cli": "esbuild dist/cli/just-bash.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node'",
     "build:shell": "esbuild dist/cli/shell.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin/shell --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node'",
     "prepublishOnly": "pnpm validate",
-    "validate": "pnpm build && pnpm typecheck && pnpm lint && pnpm knip && pnpm test:run && pnpm test:dist",
+    "validate": "pnpm lint && pnpm knip && pnpm typecheck &&  pnpm build && pnpm test:run && pnpm test:dist",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",

src/Bash.ts

@@ -19,8 +19,8 @@ import {
   createLazyCustomCommand,
   isLazyCommand,
 } from "./custom-commands.js";
-import { type IFileSystem, VirtualFs } from "./fs.js";
-import type { InitialFiles } from "./fs-interface.js";
+import { InMemoryFs } from "./fs/in-memory-fs/in-memory-fs.js";
+import type { IFileSystem, InitialFiles } from "./fs/interface.js";
 import {
   ArithmeticError,
   ExecutionLimitError,
@@ -132,7 +132,7 @@ export class Bash {
   private state: InterpreterState;
 
   constructor(options: BashOptions = {}) {
-    const fs = options.fs ?? new VirtualFs(options.files);
+    const fs = options.fs ?? new InMemoryFs(options.files);
     this.fs = fs;
 
     this.useDefaultLayout = !options.cwd && !options.files;
@@ -195,8 +195,8 @@ export class Bash {
       loopDepth: 0,
     };
 
-    // Create essential directories for VirtualFs
-    if (fs instanceof VirtualFs) {
+    // Create essential directories for InMemoryFs
+    if (fs instanceof InMemoryFs) {
       try {
         // Always create /bin for PATH-based command resolution
         fs.mkdirSync("/bin", { recursive: true });
@@ -211,7 +211,7 @@ export class Bash {
       }
     }
 
-    if (cwd !== "/" && fs instanceof VirtualFs) {
+    if (cwd !== "/" && fs instanceof InMemoryFs) {
       try {
         fs.mkdirSync(cwd, { recursive: true });
       } catch {
@@ -245,7 +245,7 @@ export class Bash {
   registerCommand(command: Command): void {
     this.commands.set(command.name, command);
     // Always create command stubs in /bin for PATH-based resolution
-    if (this.fs instanceof VirtualFs) {
+    if (this.fs instanceof InMemoryFs) {
       try {
         this.fs.writeFileSync(
           `/bin/${command.name}`,

src/ai/index.ts

@@ -2,7 +2,7 @@ import { type Tool, tool, zodSchema } from "ai";
 import { z } from "zod";
 import { Bash, type BashOptions } from "../Bash.js";
 import type { CommandName } from "../commands/registry.js";
-import type { IFileSystem, InitialFiles } from "../fs-interface.js";
+import type { IFileSystem, InitialFiles } from "../fs/interface.js";
 
 type BashToolInput = { command: string };
 type BashToolOutput = { stdout: string; stderr: string; exitCode: number };

src/cli/just-bash.ts

@@ -39,7 +39,7 @@
 
 import { resolve } from "node:path";
 import { Bash } from "../Bash.js";
-import { OverlayFs } from "../overlay-fs/index.js";
+import { OverlayFs } from "../fs/overlay-fs/index.js";
 
 interface CliOptions {
   script?: string;

src/fs-buffer.test.ts src/fs/in-memory-fs/in-memory-fs.test.tssrc/fs-buffer.test.ts renamed to src/fs/in-memory-fs/in-memory-fs.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { VirtualFs } from "./fs.js";
+import { InMemoryFs } from "./in-memory-fs.js";
 
-describe("VirtualFs Buffer and Encoding Support", () => {
+describe("InMemoryFs Buffer and Encoding Support", () => {
   describe("basic Buffer operations", () => {
     it("should write and read Uint8Array", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
 
       await fs.writeFile("/binary.bin", data);
@@ -14,7 +14,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should write Uint8Array and read as string", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
 
       await fs.writeFile("/test.txt", data);
@@ -24,7 +24,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should write string and read as Uint8Array", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello");
       const result = await fs.readFileBuffer("/test.txt");
@@ -33,7 +33,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should handle binary data with null bytes", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x00, 0x01, 0x00, 0xff, 0x00]);
 
       await fs.writeFile("/binary.bin", data);
@@ -43,7 +43,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should calculate correct size for binary files", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x00, 0x01, 0x02, 0x03, 0x04]);
 
       await fs.writeFile("/binary.bin", data);
@@ -55,7 +55,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
 
   describe("encoding support", () => {
     it("should write and read with utf8 encoding", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello 世界", "utf8");
       const result = await fs.readFile("/test.txt", "utf8");
@@ -64,7 +64,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should write and read with base64 encoding", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       // "Hello" in base64 is "SGVsbG8="
       await fs.writeFile("/test.txt", "SGVsbG8=", "base64");
@@ -74,7 +74,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should read as base64", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello");
       const result = await fs.readFile("/test.txt", "base64");
@@ -83,7 +83,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should write and read with hex encoding", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       // "Hello" in hex is "48656c6c6f"
       await fs.writeFile("/test.txt", "48656c6c6f", "hex");
@@ -93,7 +93,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should read as hex", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello");
       const result = await fs.readFile("/test.txt", "hex");
@@ -102,7 +102,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should write with latin1 encoding", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       // Latin1 character é is 0xe9
       await fs.writeFile("/test.txt", "café", "latin1");
@@ -112,7 +112,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should support encoding in options object", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "SGVsbG8=", { encoding: "base64" });
       const result = await fs.readFile("/test.txt", { encoding: "utf8" });
@@ -123,7 +123,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
 
   describe("appendFile with Buffer", () => {
     it("should append Uint8Array to existing file", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello");
       await fs.appendFile(
@@ -136,7 +136,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should append string to file with Buffer content", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const initial = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
 
       await fs.writeFile("/test.txt", initial);
@@ -147,7 +147,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should append with encoding", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/test.txt", "Hello");
       // " World" in base64 is "IFdvcmxk"
@@ -160,7 +160,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
 
   describe("constructor with Buffer content", () => {
     it("should initialize files with Uint8Array content", async () => {
-      const fs = new VirtualFs({
+      const fs = new InMemoryFs({
         "/binary.bin": new Uint8Array([0x00, 0x01, 0x02]),
         "/text.txt": "Hello",
       });
@@ -175,7 +175,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
 
   describe("edge cases", () => {
     it("should handle empty Uint8Array", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
 
       await fs.writeFile("/empty.bin", new Uint8Array(0));
       const result = await fs.readFileBuffer("/empty.bin");
@@ -185,7 +185,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should handle large binary files", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const size = 1024 * 1024; // 1MB
       const data = new Uint8Array(size);
       for (let i = 0; i < size; i++) {
@@ -202,7 +202,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should preserve binary content through copy", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x00, 0xff, 0x00, 0xff]);
 
       await fs.writeFile("/src.bin", data);
@@ -213,7 +213,7 @@ describe("VirtualFs Buffer and Encoding Support", () => {
     });
 
     it("should follow symlinks for binary files", async () => {
-      const fs = new VirtualFs();
+      const fs = new InMemoryFs();
       const data = new Uint8Array([0x48, 0x69]);
 
       await fs.writeFile("/real.bin", data);