Add LazyFs for lazy in-memory files

[defrex]

I've ben loving just-bash! It's solved a ton of problems for me by enabling filesystem agents without a full sandbox.

However, I'm loading so many files in there that initializing the tool has gotten quite slow, and most of the time the agent doesn't even need the files.

The new LazyFs class has allowed me to quickly initialize the virtual filesystem and only load files that directories on an as-needed bases, which has greatly improved performance.

In addition to the unit tests in the PR, I've integrated this into my agents and run through my evals, etc confirming that this is working great for me.

README Snippet

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:

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.

[vercel]

@defrex is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[cramforce]

Should OverlayFS just be lazy?

[defrex]

Should OverlayFS just be lazy?

That seems like a good default for OverlayFS, since it could work the same while skipping unnecessary IO.

Though to clarify, that wouldn't solve my use-case since I specifically need to load data from a database, not the filesystem.