just-bash 1.4.2 → 1.5.3

package/README.md

@@ -239,6 +239,10 @@ pnpm shell --no-network
 
 `awk`, `base64`, `comm`, `cut`, `diff`, `grep` (+ `egrep`, `fgrep`), `head`, `jq`, `md5sum`, `od`, `paste`, `printf`, `sed`, `sha1sum`, `sha256sum`, `sort`, `tac`, `tail`, `tr`, `uniq`, `wc`, `xargs`
 
+### Compression
+
+`gzip` (+ `gunzip`, `zcat`)
+
 ### Navigation & Environment
 
 `basename`, `cd`, `dirname`, `du`, `echo`, `env`, `export`, `find`, `hostname`, `printenv`, `pwd`, `tee`
@@ -361,6 +365,16 @@ pnpm build       # Build TypeScript
 pnpm shell       # Run interactive shell
 ```
 
+## AI Agent Instructions
+
+For AI agents working with just-bash, additional guidance is available in `AGENTS.md`:
+
+```bash
+cat node_modules/just-bash/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

@@ -0,0 +1,202 @@
+
+# AGENTS.md - just-bash
+
+Instructions for AI agents using just-bash in projects.
+
+## What is just-bash?
+
+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";
+
+const bash = new Bash({
+  files: { "/data/input.txt": "content" }, // Initial files
+  cwd: "/data", // Working directory
+});
+
+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
+```
+
+## 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 { generateText } from "ai";
+
+const bashTool = createBashTool({
+  files: {
+    "/data/users.json": '[{"name": "Alice"}, {"name": "Bob"}]',
+    "/data/config.yaml": "debug: true\nport: 3000",
+  },
+});
+
+const result = await generateText({
+  model: "anthropic/claude-haiku-4.5",
+  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",
+});
+```
+
+### With Network Access
+
+```typescript
+import { createBashTool } from "just-bash/ai";
+
+const bashTool = createBashTool({
+  network: {
+    allowedUrlPrefixes: ["https://api.github.com/"],
+  },
+});
+```
+
+### 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(),
+});
+```
+
+### 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.
+
+2. **No real filesystem**: By default, commands only see the virtual filesystem. Use `OverlayFs` to read from a real directory (writes stay in memory).
+
+3. **No network by default**: `curl` doesn't exist unless you configure `network` options with URL allowlists.
+
+4. **No binaries/WASM**: Only built-in commands work. You cannot run node, python, or other binaries.
+
+## Available Commands
+
+**Text processing**: `awk`, `cat`, `cut`, `grep`, `head`, `jq`, `sed`, `sort`, `tail`, `tr`, `uniq`, `wc`, `xargs`
+
+**File operations**: `cp`, `find`, `ls`, `mkdir`, `mv`, `rm`, `touch`, `tree`
+
+**Utilities**: `base64`, `date`, `diff`, `echo`, `env`, `printf`, `seq`, `tee`
+
+All commands support `--help` for usage details.
+
+## Common Patterns
+
+### Process JSON with jq
+
+```bash
+cat data.json | jq '.items[] | select(.active) | .name'
+```
+
+### Find and process files
+
+```bash
+find . -name "*.ts" -type f | xargs grep -l "TODO"
+```
+
+### Text transformation pipeline
+
+```bash
+cat input.txt | grep -v "^#" | sort | uniq -c | sort -rn | head -10
+```
+
+### AWK for columnar data
+
+```bash
+cat data.csv | awk -F',' '{sum += $3} END {print sum}'
+```
+
+## Limitations
+
+- **32-bit integers only**: Arithmetic operations use 32-bit signed integers
+- **No job control**: No `&`, `bg`, `fg`, or process suspension
+- **No external binaries**: Only built-in commands are available
+- **Execution limits**: Loops, recursion, and command counts have configurable limits to prevent runaway execution
+
+## Error Handling
+
+Always check `exitCode`:
+
+```typescript
+import { Bash } from "just-bash";
+
+const bash = new Bash({ files: { "/file.txt": "some content" } });
+const result = await bash.exec("grep pattern file.txt");
+if (result.exitCode !== 0) {
+  // Command failed - check result.stderr for details
+}
+```
+
+Common exit codes:
+
+- `0` - Success
+- `1` - General error or no matches (grep)
+- `2` - Misuse of command (invalid options)
+- `127` - Command not found
+
+## Debugging Tips
+
+1. **Check stderr**: Error messages go to `result.stderr`
+2. **Use --help**: All commands support `--help` for usage
+3. **Test incrementally**: Build pipelines step by step
+4. **Quote variables**: Use `"$var"` to handle spaces in values
+
+## Security Model
+
+- Virtual filesystem is isolated from the real system
+- Network access requires explicit URL allowlists
+- Execution limits prevent infinite loops
+- No shell injection possible (commands are parsed, not eval'd)

package/dist/bin/chunks/gzip-VLTXZB2V.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import{a as z}from"./chunk-TA7RUHGQ.js";import{a as w,b as $}from"./chunk-GTNBSMZR.js";import"./chunk-SJXDWN5X.js";import{constants as x,gunzipSync as C,gzipSync as b}from"node:zlib";var I={name:"gzip",summary:"compress or expand files",usage:"gzip [OPTION]... [FILE]...",description:`Compress FILEs (by default, in-place).
+
+When no FILE is given, or when FILE is -, read from standard input.
+
+With -d, decompress instead.`,options:["-c, --stdout      write to standard output, keep original files","-d, --decompress  decompress","-f, --force       force overwrite of output file","-k, --keep        keep (don't delete) input files","-l, --list        list compressed file contents","-n, --no-name     do not save or restore the original name and timestamp","-N, --name        save or restore the original file name and timestamp","-q, --quiet       suppress all warnings","-r, --recursive   operate recursively on directories","-S, --suffix=SUF  use suffix SUF on compressed files (default: .gz)","-t, --test        test compressed file integrity","-v, --verbose     verbose mode","-1, --fast        compress faster","-9, --best        compress better","    --help        display this help and exit"]},q={name:"gunzip",summary:"decompress files",usage:"gunzip [OPTION]... [FILE]...",description:`Decompress FILEs (by default, in-place).
+
+When no FILE is given, or when FILE is -, read from standard input.`,options:["-c, --stdout      write to standard output, keep original files","-f, --force       force overwrite of output file","-k, --keep        keep (don't delete) input files","-l, --list        list compressed file contents","-n, --no-name     do not restore the original name and timestamp","-N, --name        restore the original file name and timestamp","-q, --quiet       suppress all warnings","-r, --recursive   operate recursively on directories","-S, --suffix=SUF  use suffix SUF on compressed files (default: .gz)","-t, --test        test compressed file integrity","-v, --verbose     verbose mode","    --help        display this help and exit"]},P={name:"zcat",summary:"decompress files to stdout",usage:"zcat [OPTION]... [FILE]...",description:`Decompress FILEs to standard output.
+
+When no FILE is given, or when FILE is -, read from standard input.`,options:["-f, --force       force; read compressed data even from a terminal","-l, --list        list compressed file contents","-q, --quiet       suppress all warnings","-S, --suffix=SUF  use suffix SUF on compressed files (default: .gz)","-t, --test        test compressed file integrity","-v, --verbose     verbose mode","    --help        display this help and exit"]},D={stdout:{short:"c",long:"stdout",type:"boolean"},toStdout:{long:"to-stdout",type:"boolean"},decompress:{short:"d",long:"decompress",type:"boolean"},uncompress:{long:"uncompress",type:"boolean"},force:{short:"f",long:"force",type:"boolean"},keep:{short:"k",long:"keep",type:"boolean"},list:{short:"l",long:"list",type:"boolean"},noName:{short:"n",long:"no-name",type:"boolean"},name:{short:"N",long:"name",type:"boolean"},quiet:{short:"q",long:"quiet",type:"boolean"},recursive:{short:"r",long:"recursive",type:"boolean"},suffix:{short:"S",long:"suffix",type:"string",default:".gz"},test:{short:"t",long:"test",type:"boolean"},verbose:{short:"v",long:"verbose",type:"boolean"},fast:{short:"1",long:"fast",type:"boolean"},level2:{short:"2",type:"boolean"},level3:{short:"3",type:"boolean"},level4:{short:"4",type:"boolean"},level5:{short:"5",type:"boolean"},level6:{short:"6",type:"boolean"},level7:{short:"7",type:"boolean"},level8:{short:"8",type:"boolean"},best:{short:"9",long:"best",type:"boolean"}};function F(e){return e.best?x.Z_BEST_COMPRESSION:e.level8?8:e.level7?7:e.level6?6:e.level5?5:e.level4?4:e.level3?3:e.level2?2:e.fast?x.Z_BEST_SPEED:x.Z_DEFAULT_COMPRESSION}function S(e){if(e.length<10)return{originalName:null,mtime:null,headerSize:0};if(e[0]!==31||e[1]!==139)return{originalName:null,mtime:null,headerSize:0};let t=e[3],o=e[4]|e[5]<<8|e[6]<<16|e[7]<<24,r=10;if(t&4){if(r+2>e.length)return{originalName:null,mtime:null,headerSize:0};let n=e[r]|e[r+1]<<8;r+=2+n}let s=null;if(t&8){let n=r;for(;r<e.length&&e[r]!==0;)r++;r<e.length&&(s=new TextDecoder().decode(e.slice(n,r)),r++)}if(t&16){for(;r<e.length&&e[r]!==0;)r++;r++}return t&2&&(r+=2),{originalName:s,mtime:o>0?new Date(o*1e3):null,headerSize:r}}function L(e){if(e.length<4)return 0;let t=e.length;return e[t-4]|e[t-3]<<8|e[t-2]<<16|e[t-1]<<24}function y(e){return e.length>=2&&e[0]===31&&e[1]===139}async function E(e,t,o,r,s,n){let u=o.suffix,c,p,d;if(t==="-"||t==="")if(d=new TextEncoder().encode(e.stdin),s){if(!y(d))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: stdin: not in gzip format
+`,exitCode:1};try{let l=C(d);return{stdout:new TextDecoder().decode(l),stderr:"",exitCode:0}}catch(l){let i=l instanceof Error?l.message:"unknown error";return{stdout:"",stderr:`${r}: stdin: ${i}
+`,exitCode:1}}}else{let l=F(o),i=b(d,{level:l});return{stdout:String.fromCharCode(...i),stderr:"",exitCode:0}}c=e.fs.resolvePath(e.cwd,t);try{if((await e.fs.stat(c)).isDirectory)return o.recursive?await k(e,c,o,r,s,n):o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t}: is a directory -- ignored
+`,exitCode:1}}catch{return{stdout:"",stderr:`${r}: ${t}: No such file or directory
+`,exitCode:1}}try{d=await e.fs.readFileBuffer(c)}catch{return{stdout:"",stderr:`${r}: ${t}: No such file or directory
+`,exitCode:1}}if(s){if(!t.endsWith(u))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t}: unknown suffix -- ignored
+`,exitCode:1};if(!y(d))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t}: not in gzip format
+`,exitCode:1};let l;try{l=C(d)}catch(i){let f=i instanceof Error?i.message:"unknown error";return{stdout:"",stderr:`${r}: ${t}: ${f}
+`,exitCode:1}}if(n)return{stdout:new TextDecoder().decode(l),stderr:"",exitCode:0};if(o.name){let i=S(d);i.originalName?p=e.fs.resolvePath(e.cwd,i.originalName):p=c.slice(0,-u.length)}else p=c.slice(0,-u.length);if(!o.force)try{return await e.fs.stat(p),{stdout:"",stderr:`${r}: ${p} already exists; not overwritten
+`,exitCode:1}}catch{}if(await e.fs.writeFile(p,l),!o.keep&&!n&&await e.fs.rm(c),o.verbose){let i=d.length>0?((1-d.length/l.length)*100).toFixed(1):"0.0";return{stdout:"",stderr:`${t}:	${i}% -- replaced with ${p.split("/").pop()}
+`,exitCode:0}}return{stdout:"",stderr:"",exitCode:0}}else{if(t.endsWith(u))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t} already has ${u} suffix -- unchanged
+`,exitCode:1};let l=F(o),i;try{i=b(d,{level:l})}catch(f){let a=f instanceof Error?f.message:"unknown error";return{stdout:"",stderr:`${r}: ${t}: ${a}
+`,exitCode:1}}if(n)return{stdout:String.fromCharCode(...i),stderr:"",exitCode:0};if(p=c+u,!o.force)try{return await e.fs.stat(p),{stdout:"",stderr:`${r}: ${p} already exists; not overwritten
+`,exitCode:1}}catch{}if(await e.fs.writeFile(p,i),!o.keep&&!n&&await e.fs.rm(c),o.verbose){let f=d.length>0?((1-i.length/d.length)*100).toFixed(1):"0.0";return{stdout:"",stderr:`${t}:	${f}% -- replaced with ${p.split("/").pop()}
+`,exitCode:0}}return{stdout:"",stderr:"",exitCode:0}}}async function k(e,t,o,r,s,n){let u=await e.fs.readdir(t),c="",p="",d=0;for(let l of u){let i=e.fs.resolvePath(t,l),f=await e.fs.stat(i);if(f.isDirectory){let a=await k(e,i,o,r,s,n);c+=a.stdout,p+=a.stderr,a.exitCode!==0&&(d=a.exitCode)}else if(f.isFile){let a=o.suffix;if(s&&!l.endsWith(a)||!s&&l.endsWith(a))continue;let m=i.startsWith(`${e.cwd}/`)?i.slice(e.cwd.length+1):i,g=await E(e,m,o,r,s,n);c+=g.stdout,p+=g.stderr,g.exitCode!==0&&(d=g.exitCode)}}return{stdout:c,stderr:p,exitCode:d}}async function T(e,t,o,r){let s;if(t==="-"||t==="")s=new TextEncoder().encode(e.stdin);else{let i=e.fs.resolvePath(e.cwd,t);try{s=await e.fs.readFileBuffer(i)}catch{return{stdout:"",stderr:`${r}: ${t}: No such file or directory
+`,exitCode:1}}}if(!y(s))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t}: not in gzip format
+`,exitCode:1};let n=s.length,u=L(s),c=u>0?((1-n/u)*100).toFixed(1):"0.0",d=S(s).originalName||(t==="-"?"":t.replace(/\.gz$/,""));return{stdout:`${n.toString().padStart(10)} ${u.toString().padStart(10)} ${c.padStart(5)}% ${d}
+`,stderr:"",exitCode:0}}async function O(e,t,o,r){let s;if(t==="-"||t==="")s=new TextEncoder().encode(e.stdin);else{let n=e.fs.resolvePath(e.cwd,t);try{s=await e.fs.readFileBuffer(n)}catch{return{stdout:"",stderr:`${r}: ${t}: No such file or directory
+`,exitCode:1}}}if(!y(s))return o.quiet?{stdout:"",stderr:"",exitCode:1}:{stdout:"",stderr:`${r}: ${t}: not in gzip format
+`,exitCode:1};try{return C(s),o.verbose?{stdout:"",stderr:`${t}:	OK
+`,exitCode:0}:{stdout:"",stderr:"",exitCode:0}}catch(n){let u=n instanceof Error?n.message:"invalid";return{stdout:"",stderr:`${r}: ${t}: ${u}
+`,exitCode:1}}}async function v(e,t,o){let r=o==="zcat"?P:o==="gunzip"?q:I;if($(e))return w(r);let s=z(o,e,D);if(!s.ok)return s.error.stderr.includes("unrecognized option"),s.error;let n=s.result.flags,u=s.result.positional,c=o==="gunzip"||o==="zcat"||n.decompress||n.uncompress,p=o==="zcat"||n.stdout||n.toStdout;if(n.list){u.length===0&&(u=["-"]);let f=`  compressed uncompressed  ratio uncompressed_name
+`,a="",m=0;for(let g of u){let h=await T(t,g,n,o);f+=h.stdout,a+=h.stderr,h.exitCode!==0&&(m=h.exitCode)}return{stdout:f,stderr:a,exitCode:m}}if(n.test){u.length===0&&(u=["-"]);let f="",a="",m=0;for(let g of u){let h=await O(t,g,n,o);f+=h.stdout,a+=h.stderr,h.exitCode!==0&&(m=h.exitCode)}return{stdout:f,stderr:a,exitCode:m}}u.length===0&&(u=["-"]);let d="",l="",i=0;for(let f of u){let a=await E(t,f,n,o,c,p);d+=a.stdout,l+=a.stderr,a.exitCode!==0&&(i=a.exitCode)}return{stdout:d,stderr:l,exitCode:i}}var H={name:"gzip",async execute(e,t){return v(e,t,"gzip")}},B={name:"gunzip",async execute(e,t){return v(e,t,"gunzip")}},G={name:"zcat",async execute(e,t){return v(e,t,"zcat")}};export{B as gunzipCommand,H as gzipCommand,G as zcatCommand};