Add LazyFs for lazy in-memory files

.gitignore

@@ -3,6 +3,7 @@ package-lock.json
 .DS_Store
 .vscode
 .idea
+.claude/
 .env
 .env.*
 dist

README.md

@@ -99,7 +99,7 @@ Custom commands receive the full `CommandContext` with access to `fs`, `cwd`, `e
 
 ### Filesystem Options
 
-Four filesystem implementations are available:
+Five filesystem implementations are available:
 
 **InMemoryFs** (default) - Pure in-memory filesystem, no disk access:
 
@@ -171,6 +171,39 @@ const fs = new MountableFs({
 });
 ```
 
+**LazyFs** - Lazy-loading filesystem that loads content on-demand via callbacks. Ideal for remote content, API-backed storage, or large datasets where you don't want to load everything upfront:
+
+```typescript
+import { Bash, LazyFs, MountableFs, InMemoryFs } from "just-bash";
+
+const lazyFs = new LazyFs({
+  // Called when reading a directory - return entries or null
+  listDir: async (dirPath) => {
+    // Replace with your API call, e.g.: await fetchDirectoryFromAPI(dirPath)
+    return [
+      { name: "file.txt", type: "file" as const },
+      { name: "subdir", type: "directory" as const },
+    ];
+  },
+  // Called when reading a file - return content or null
+  loadFile: async (filePath) => {
+    // Replace with your API call, e.g.: await fetchFileFromAPI(filePath)
+    return { content: "file content here" };
+  },
+  allowWrites: true, // default, writes go to in-memory cache
+});
+
+// Mount it at a path
+const fs = new MountableFs({ base: new InMemoryFs() });
+fs.mount("/mnt/remote", lazyFs);
+
+const bash = new Bash({ fs });
+await bash.exec("ls /mnt/remote"); // triggers listDir("/")
+await bash.exec("cat /mnt/remote/data.txt"); // triggers loadFile("/data.txt")
+```
+
+Content is cached after first access. Writes and deletes stay in memory and shadow the lazy-loaded content.
+
 ### AI SDK Tool
 
 For AI agents, use [`bash-tool`](https://github.com/vercel-labs/bash-tool) which is optimized for just-bash and provides a ready-to-use [AI SDK](https://ai-sdk.dev/) tool:

src/fs/lazy-fs/index.ts

@@ -0,0 +1,9 @@
+export {
+  type LazyDirEntry,
+  type LazyDirListing,
+  type LazyFileContent,
+  LazyFs,
+  type LazyFsOptions,
+  type LazyListDir,
+  type LazyLoadFile,
+} from "./lazy-fs.js";