@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

npm install @context-fs/just-bash

Peer Dependencies

npm install @context-fs/core just-bash

Quick Start

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 bash`cat /hello.txt`;
console.log(result.stdout); // "Hello from the virtual filesystem!"

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

API

ContextFS

Adapter class implementing IFileSystem from just-bash.

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

Testing Shell Scripts

Test bash scripts against mock filesystems:

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 bash`grep myserver /etc/hosts | cut -d' ' -f1`;
expect(result.stdout.trim()).toBe("192.168.1.1");

AI/LLM Sandboxing

Let AI execute bash commands against a controlled virtual filesystem:

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]);

Dynamic Content

Serve computed content that bash scripts can consume:

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 bash`cat /api/users.json | jq '.[0].name'`;
await bash`cat /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