feat: add HttpFs, mount() helper, and graceful redirection error handling

[jcourson-bg]

Example

import { Bash, HttpFs, mount } from "just-bash";

const fs = mount({
  "/data": new HttpFs("https://cdn.example.com/dataset", [
    "train.csv",
    "test.csv",
    "metadata.json",
  ]),
});

const bash = new Bash({ fs });

await bash.exec("wc -l /data/train.csv");       // fetches once, then cached
await bash.exec("cat /data/metadata.json | jq .name"); // reads from cache
await bash.exec("ls /data");                     // from manifest, no network
await bash.exec("echo x > /data/new.txt");       // bash: /data/new.txt: Read-only file system

What's in here

• HttpFs — read-only filesystem backed by HTTP. You declare the file paths up front (a manifest), and they're fetched lazily on first read, then cached. Supports custom headers and a custom fetch function for auth, proxies, etc.
• mount() helper — shorthand for composing filesystems. Creates an initialised InMemoryFs base (with /dev, /proc, /bin) automatically when you don't provide "/".
• Graceful redirection errors — redirections (>, >>, &>, etc.) now catch FS write errors and produce bash-style messages (bash: file: Read-only file system) instead of propagating raw JS errors. Without this, echo x > /mounted/file on a read-only mount throws an unhandled error instead of behaving like real bash.
• MountableFs sync helpers — added mkdirSync, writeFileSync, and writeFileLazy delegation so initFilesystem() and registerCommand() work when the top-level FS is a MountableFs.

Design decisions

• Manifest-based — HTTP has no standard directory listing, so HttpFs requires declaring file paths up front. This means readdir/ls/exists work without network calls, and commands like grep -r won't trigger surprise fetches.
• Read-only — all write operations throw EROFS. For read-write over HTTP, compose with MountableFs (writable InMemoryFs base + read-only HttpFs mount).
• Object.create(null) — FS_ERROR_LABELS and reqHeaders use null-prototype objects per the project's prototype pollution guidelines.

Known follow-up

Command-level error messages (mkdir, rm, etc.) still surface raw JS errors like EROFS: read-only file system, mkdir '/path' rather than bash-style messages. Separate concern from redirection handling — can be addressed in a follow-up.

Made with Cursor

[vercel]

@jcourson-bg is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[cramforce]

I think this would be better as a sibling package