just-bash 1.5.3 → 2.0.0

package/README.md

@@ -135,10 +135,14 @@ 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/), because [agents love bash](https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools).
+For AI agents, use [`bash-tool`](https://github.com/vercel-labs/bash-tool) which is optimized for just-bash and provides a ready-to-use [AI SDK](https://ai-sdk.dev/) tool:
+
+```bash
+npm install bash-tool
+```
 
 ```typescript
-import { createBashTool } from "just-bash/ai";
+import { createBashTool } from "bash-tool";
 import { generateText } from "ai";
 
 const bashTool = createBashTool({
@@ -146,13 +150,13 @@ const bashTool = createBashTool({
 });
 
 const result = await generateText({
-  model: "anthropic/claude-haiku-4.5",
+  model: "anthropic/claude-sonnet-4",
   tools: { bash: bashTool },
   prompt: "Count the users in /data/users.json",
 });
 ```
 
-See [`examples/bash-agent`](./examples/bash-agent) for a full implementation.
+See the [bash-tool documentation](https://github.com/vercel-labs/bash-tool) for more details and examples.
 
 ### Vercel Sandbox Compatible API
 
@@ -367,14 +371,12 @@ pnpm shell       # Run interactive shell
 
 ## AI Agent Instructions
 
-For AI agents working with just-bash, additional guidance is available in `AGENTS.md`:
+For AI agents, we recommend using [`bash-tool`](https://github.com/vercel-labs/bash-tool) which is optimized for just-bash and provides additional guidance in its `AGENTS.md`:
 
 ```bash
-cat node_modules/just-bash/dist/AGENTS.md
+cat node_modules/bash-tool/dist/AGENTS.md
 ```
 
-This file contains quick reference patterns, common pitfalls, and debugging tips specifically for AI agents.
-
 ## License
 
 Apache-2.0

package/dist/AGENTS.md

@@ -8,111 +8,50 @@ Instructions for AI agents using just-bash in projects.
 A sandboxed bash interpreter with an in-memory virtual filesystem. Use it when you need to:
 
 - Execute shell commands without real filesystem access
-- Provide a bash tool for AI agents
 - Run untrusted scripts safely
 - Process text with standard Unix tools (grep, sed, awk, jq, etc.)
 
-## Quick Reference
-
-```typescript
-import { Bash } from "just-bash";
+## For AI Agents
 
-const bash = new Bash({
-  files: { "/data/input.txt": "content" }, // Initial files
-  cwd: "/data", // Working directory
-});
+If you're building an AI agent that needs a bash tool, use [`bash-tool`](https://github.com/vercel-labs/bash-tool) which is optimized for just-bash:
 
-const result = await bash.exec("cat input.txt | grep pattern");
-// result.stdout  - command output
-// result.stderr  - error output
-// result.exitCode - 0 = success, non-zero = failure
+```sh
+npm install bash-tool
 ```
 
-## Building an AI Agent
-
-just-bash integrates with the [AI SDK](https://ai-sdk.dev/) to provide a bash tool for AI agents.
-
-### Basic Agent Setup
-
 ```typescript
-import { createBashTool } from "just-bash/ai";
+import { createBashTool } from "bash-tool";
 import { generateText } from "ai";
 
 const bashTool = createBashTool({
-  files: {
-    "/data/users.json": '[{"name": "Alice"}, {"name": "Bob"}]',
-    "/data/config.yaml": "debug: true\nport: 3000",
-  },
+  files: { "/data/users.json": '[{"name": "Alice"}, {"name": "Bob"}]' },
 });
 
 const result = await generateText({
-  model: "anthropic/claude-haiku-4.5",
+  model: "anthropic/claude-sonnet-4",
   tools: { bash: bashTool },
   prompt: "Count the users in /data/users.json",
 });
 ```
 
-### With ToolLoopAgent
-
-For multi-step tasks, use `ToolLoopAgent` which automatically loops until completion:
-
-```typescript
-import { ToolLoopAgent } from "ai";
-import { createBashTool } from "just-bash/ai";
-
-const bashTool = createBashTool({
-  files: {
-    "/project/src/index.ts": "export const version = '1.0.0';",
-    "/project/src/utils.ts": "// TODO: implement\nexport function helper() {}",
-    "/project/package.json": '{"name": "my-app", "version": "1.0.0"}',
-  },
-});
-
-const agent = new ToolLoopAgent({
-  model: "anthropic/claude-haiku-4.5",
-  tools: { bash: bashTool },
-});
-
-const result = await agent.generate({
-  prompt: "Find all TODO comments in the project and list the files containing them",
-});
-```
+See the [bash-tool documentation](https://github.com/vercel-labs/bash-tool) for more details.
 
-### With Network Access
+## Quick Reference
 
 ```typescript
-import { createBashTool } from "just-bash/ai";
+import { Bash } from "just-bash";
 
-const bashTool = createBashTool({
-  network: {
-    allowedUrlPrefixes: ["https://api.github.com/"],
-  },
+const bash = new Bash({
+  files: { "/data/input.txt": "content" }, // Initial files
+  cwd: "/data", // Working directory
 });
-```
 
-### With Real Filesystem (Read-Only)
-
-```typescript
-import { createBashTool } from "just-bash/ai";
-import { OverlayFs } from "just-bash/fs/overlay-fs";
-
-const overlay = new OverlayFs({ root: "/path/to/project" });
-const bashTool = createBashTool({
-  fs: overlay,
-  cwd: overlay.getMountPoint(),
-});
+const result = await bash.exec("cat input.txt | grep pattern");
+// result.stdout  - command output
+// result.stderr  - error output
+// result.exitCode - 0 = success, non-zero = failure
 ```
 
-### Tool Options
-
-- `files` - Initial virtual files
-- `fs` - Custom filesystem (e.g., OverlayFs)
-- `network` - URL allowlist for curl
-- `commands` - Restrict available commands
-- `customCommands` - Add custom commands
-- `onCall` - Callback before each execution
-- `logger` - Execution tracing
-
 ## Key Behaviors
 
 1. **Isolation**: Each `exec()` call is isolated. Environment variables, functions, and cwd changes don't persist between calls. Only filesystem changes persist.
@@ -200,3 +139,26 @@ Common exit codes:
 - Network access requires explicit URL allowlists
 - Execution limits prevent infinite loops
 - No shell injection possible (commands are parsed, not eval'd)
+
+## Discovering Types
+
+TypeScript types are available in the `.d.ts` files. Use JSDoc-style exploration to understand the API:
+
+```bash
+# Find all type definition files
+find node_modules/just-bash/dist -name "*.d.ts" | head -20
+
+# View main exports and their types
+cat node_modules/just-bash/dist/index.d.ts
+
+# View Bash class options
+grep -A 30 "interface BashOptions" node_modules/just-bash/dist/Bash.d.ts
+
+# Search for specific types
+grep -r "interface.*Options" node_modules/just-bash/dist/*.d.ts
+```
+
+Key types to explore:
+- `BashOptions` - Constructor options for `new Bash()`
+- `ExecResult` - Return type of `bash.exec()`
+- `InitialFiles` - File specification format

package/dist/browser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Browser-compatible entry point for just-bash.
+ *
+ * Excludes Node.js-specific modules:
+ * - OverlayFs (requires node:fs)
+ * - ReadWriteFs (requires node:fs)
+ * - Sandbox (uses OverlayFs)
+ *
+ * Note: The gzip/gunzip/zcat commands will fail at runtime in browsers
+ * since they use node:zlib. All other commands work.
+ */
+export type { BashLogger, BashOptions, ExecOptions } from "./Bash.js";
+export { Bash } from "./Bash.js";
+export type { AllCommandName, CommandName, NetworkCommandName, } from "./commands/registry.js";
+export { getCommandNames, getNetworkCommandNames, } from "./commands/registry.js";
+export type { CustomCommand, LazyCommand } from "./custom-commands.js";
+export { defineCommand } from "./custom-commands.js";
+export { InMemoryFs } from "./fs/in-memory-fs/index.js";
+export type { BufferEncoding, CpOptions, DirectoryEntry, FileContent, FileEntry, FileInit, FileSystemFactory, FsEntry, FsStat, InitialFiles, MkdirOptions, RmOptions, SymlinkEntry, } from "./fs/interface.js";
+export type { NetworkConfig } from "./network/index.js";
+export { NetworkAccessDeniedError, RedirectNotAllowedError, TooManyRedirectsError, } from "./network/index.js";
+export type { BashExecResult, Command, CommandContext, ExecResult, IFileSystem, } from "./types.js";