just-bash 1.0.0 → 1.1.0

package/README.md

@@ -15,7 +15,8 @@ Supports optional network access via `curl` with secure-by-default URL filtering
 - [Usage](#usage)
   - [Basic API](#basic-api)
   - [Configuration](#configuration)
-  - [OverlayFs (Copy-on-Write)](#overlayfs-copy-on-write)
+  - [Custom Commands](#custom-commands)
+  - [Filesystem Options](#filesystem-options)
   - [AI SDK Tool](#ai-sdk-tool)
   - [Vercel Sandbox Compatible API](#vercel-sandbox-compatible-api)
   - [CLI Binary](#cli-binary)
@@ -72,30 +73,69 @@ const env = new Bash({
 await env.exec("echo $TEMP", { env: { TEMP: "value" }, cwd: "/tmp" });
 ```
 
-### OverlayFs (Copy-on-Write)
+### Custom Commands
 
-Seed the bash environment with files from a real directory. The agent can read but not write to the real filesystem - all changes stay in memory.
+Extend just-bash with your own TypeScript commands using `defineCommand`:
 
 ```typescript
-import { Bash, OverlayFs } from "just-bash";
+import { Bash, defineCommand } from "just-bash";
+
+const hello = defineCommand("hello", async (args, ctx) => {
+  const name = args[0] || "world";
+  return { stdout: `Hello, ${name}!\n`, stderr: "", exitCode: 0 };
+});
+
+const upper = defineCommand("upper", async (args, ctx) => {
+  return { stdout: ctx.stdin.toUpperCase(), stderr: "", exitCode: 0 };
+});
+
+const bash = new Bash({ customCommands: [hello, upper] });
+
+await bash.exec("hello Alice"); // "Hello, Alice!\n"
+await bash.exec("echo 'test' | upper"); // "TEST\n"
+```
+
+Custom commands receive the full `CommandContext` with access to `fs`, `cwd`, `env`, `stdin`, and `exec` for running subcommands.
+
+### Filesystem Options
+
+Three filesystem implementations are available:
+
+**InMemoryFs** (default) - Pure in-memory filesystem, no disk access:
+
+```typescript
+import { Bash } from "just-bash";
+const env = new Bash(); // Uses InMemoryFs by default
+```
+
+**OverlayFs** - Copy-on-write over a real directory. Reads come from disk, writes stay in memory:
+
+```typescript
+import { Bash } from "just-bash";
+import { OverlayFs } from "just-bash/fs/overlay-fs";
 
-// Files are mounted at /home/user/project by default
 const overlay = new OverlayFs({ root: "/path/to/project" });
 const env = new Bash({ fs: overlay, cwd: overlay.getMountPoint() });
 
-// Reads come from the real filesystem
-await env.exec("cat package.json"); // reads /path/to/project/package.json
+await env.exec("cat package.json"); // reads from disk
+await env.exec('echo "modified" > package.json'); // stays in memory
+```
+
+**ReadWriteFs** - Direct read-write access to a real directory. Use this if you want the agent to be agle to write to your disk:
+
+```typescript
+import { Bash } from "just-bash";
+import { ReadWriteFs } from "just-bash/fs/read-write-fs";
 
-// Writes stay in memory (real files unchanged)
-await env.exec('echo "modified" > package.json');
+const rwfs = new ReadWriteFs({ root: "/path/to/sandbox" });
+const env = new Bash({ fs: rwfs });
 
-// Custom mount point
-const overlay2 = new OverlayFs({ root: "/path/to/project", mountPoint: "/" });
+await env.exec('echo "hello" > file.txt'); // writes to real filesystem
 ```
 
 ### AI SDK Tool
 
-Creates a bash tool for use with the [AI SDK](https://ai-sdk.dev/):
+Creates a bash tool for use with the [AI SDK](https://ai-sdk.dev/), because [agents love bash](https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools).
 
 ```typescript
 import { createBashTool } from "just-bash/ai";

package/dist/Bash.d.ts

@@ -8,8 +8,8 @@
  * and delegates execution to the Interpreter.
  */
 import { type CommandName } from "./commands/registry.js";
-import { type IFileSystem } from "./fs.js";
-import type { InitialFiles } from "./fs-interface.js";
+import { type CustomCommand } from "./custom-commands.js";
+import type { IFileSystem, InitialFiles } from "./fs/interface.js";
 import { type ExecutionLimits } from "./limits.js";
 import { type NetworkConfig } from "./network/index.js";
 import type { BashExecResult, Command } from "./types.js";
@@ -53,6 +53,24 @@ export interface BashOptions {
      * Useful for testing with mock clocks.
      */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Custom commands to register alongside built-in commands.
+     * These take precedence over built-ins with the same name.
+     *
+     * @example
+     * ```ts
+     * import { defineCommand } from "just-bash";
+     *
+     * const hello = defineCommand("hello", async (args) => ({
+     *   stdout: `Hello, ${args[0] || "world"}!\n`,
+     *   stderr: "",
+     *   exitCode: 0,
+     * }));
+     *
+     * const bash = new Bash({ customCommands: [hello] });
+     * ```
+     */
+    customCommands?: CustomCommand[];
 }
 export interface ExecOptions {
     /**

package/dist/ai/index.d.ts

@@ -1,7 +1,7 @@
 import { type Tool } from "ai";
 import { type BashOptions } from "../Bash.js";
 import type { CommandName } from "../commands/registry.js";
-import type { IFileSystem, InitialFiles } from "../fs-interface.js";
+import type { IFileSystem, InitialFiles } from "../fs/interface.js";
 type BashToolInput = {
     command: string;
 };