@context-fs/just-bash

Adapter that wraps a @context-fs/core VirtualFileSystem to implement the IFileSystem interface from just-bash. Run bash scripts against virtual filesystems.

Installation

``bash
npm install @context-fs/just-bash
`

Peer Dependencies

`bash
npm install @context-fs/core just-bash
`

Quick Start

`typescript
import { createFileSystem, read } from "@context-fs/core";
import { ContextFS } from "@context-fs/just-bash";
import { createBash } from "just-bash";

// Create a virtual filesystem
const vfs = createFileSystem({
"hello.txt": {
[read]: () => "Hello from the virtual filesystem!",
},
data: {
"config.json": {
[read]: (c) => c.json({ debug: true, version: "1.0" }),
},
},
});

// Wrap it for just-bash
const fs = new ContextFS(vfs);
const bash = createBash({ fs });

// Run bash commands against the virtual filesystem
const result = await bashcat /hello.txt;
console.log(result.stdout); // "Hello from the virtual filesystem!"

const config = await bashcat /data/config.json | jq .version;
console.log(config.stdout); // "1.0"
`

API

$3

Adapter class implementing IFileSystem from just-bash.

`typescript
import { ContextFS } from "@context-fs/just-bash";

const fs = new ContextFS(vfs);
`

#### Supported Operations (Read-Only)

| Method | Description |
| -------------------------- | ---------------------------------- |
| readFile(path, options?) | Read file as string |
| readFileBuffer(path) | Read file as Uint8Array |
| exists(path) | Check if path exists |
| stat(path) | Get file stats (follows symlinks) |
| lstat(path) | Get file stats (no symlink follow) |
| readdir(path) | List directory contents |
| readlink(path) | Read symlink target |
| resolvePath(base, path) | Resolve relative paths |

#### Unsupported Operations

Write operations throw an error since VirtualFileSystem is primarily read-only:

- writeFile()
- appendFile()
- mkdir()
- rm()
- cp()
- mv()
- chmod()
- symlink()
- link()

Use Cases

$3

Test bash scripts against mock filesystems:

`typescript
const mockFs = createFileSystem({
etc: {
hosts: {
[read]: () => "127.0.0.1 localhost\n192.168.1.1 myserver",
},
},
});

const fs = new ContextFS(mockFs);
const bash = createBash({ fs });

const result = await bashgrep myserver /etc/hosts | cut -d' ' -f1;
expect(result.stdout.trim()).toBe("192.168.1.1");
`

$3

Let AI execute bash commands against a controlled virtual filesystem:

`typescript
const sandboxFs = createFileSystem({
workspace: {
":file": {
[list]: () => [{ file: "readme.md" }, { file: "config.yaml" }],
[read]: (c) => getFileContent(c.params.file),
},
},
});

const fs = new ContextFS(sandboxFs);
const bash = createBash({ fs });

// AI can explore but can't modify or escape
const aiCommand = userInput; // e.g., "ls /workspace && cat /workspace/readme.md"
const result = await bash([aiCommand]);
`

$3

Serve computed content that bash scripts can consume:

`typescript
const apiFs = createFileSystem({
api: {
"users.json": {
[read]: async () => {
const users = await fetchUsersFromAPI();
return JSON.stringify(users);
},
},
"stats.txt": {
[read]: () =>
Uptime: ${process.uptime()}s\nMemory: ${process.memoryUsage().heapUsed},
},
},
});

const fs = new ContextFS(apiFs);
const bash = createBash({ fs });

await bashcat /api/users.json | jq '.[0].name';
await bashcat /api/stats.txt | grep Uptime;
`

Limitations

1. Read-only: Write operations are not supported
2. No process spawning: Can't use features that spawn real processes
3. Path resolution: Relative paths are resolved within the virtual filesystem

Related Packages

- @context-fs/core` - Virtual filesystem core
- just-bash - Bash interpreter for JavaScript

License

MIT