Text
' | html-to-markdown ``` ### Format Conversion with yq ```bash # JSON to YAML yq -p json '.' data.json # YAML to JSON yq -o json '.' data.yaml # YAML to TOML yq -o toml '.' config.yaml # TOML to JSON yq -o json '.' Cargo.toml # CSV to JSON yq -p csv -o json '.' data.csv # XML to YAML yq -p xml '.' data.xml ``` ## 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, command counts, and output sizes have configurable limits to prevent runaway execution (exit code 126 when exceeded) ## 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) - `126` - Execution limit exceeded (loops, output size, string length) - `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 and resource exhaustion - No shell injection possible (commands are parsed, not eval'd) ### Execution Limits All limits are configurable via `executionLimits` in `BashOptions`: ```typescript const bash = new Bash({ executionLimits: { maxCommandCount: 10000, // Max commands per exec() maxLoopIterations: 10000, // Max bash loop iterations maxCallDepth: 100, // Max function recursion depth maxStringLength: 10485760, // Max string size (10MB) maxArrayElements: 100000, // Max array elements maxGlobOperations: 100000, // Max glob filesystem operations maxAwkIterations: 10000, // Max AWK loop iterations maxSedIterations: 10000, // Max sed branch loop iterations maxJqIterations: 10000, // Max jq loop iterations maxSubstitutionDepth: 50, // Max $() nesting depth maxHeredocSize: 10485760, // Max heredoc size (10MB) }, }); ``` **Output size limits**: AWK, sed, jq, and printf enforce `maxStringLength` on their output buffers. Commands that exceed the limit exit with code 126. **File read size limits**: `OverlayFs` and `ReadWriteFs` default to a 10MB max file read size. Override with `maxFileReadSize` in filesystem options (set to `0` to disable). **Network response size**: `maxResponseSize` in `NetworkConfig` caps HTTP response bodies (default: 10MB). ## 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 ## Bundling just-bash just-bash ships pre-bundled (`dist/bundle/index.js`, `index.cjs`), but a handful of dependencies are deliberately left **external** — the bundle imports them by name instead of inlining them. Under plain Node this is invisible: they are declared dependencies, so the package manager installs them and the imports resolve at runtime. It matters when you run just-bash through **another** bundler (Next.js, webpack, esbuild, rollup) for a serverless or edge target. That bundler will try to inline these, and some of them cannot be inlined. Mark all six as external: | Package | What it is | | --- | --- | | `@mongodb-js/zstd` | native binding (`optionalDependencies`) | | `node-liblzma` | native binding (`optionalDependencies`) | | `sql.js` | ships a `.wasm` asset | | `run` | embeds the QuickJS WASM runtime | | `seek-bzip` | CommonJS-only bzip2 decoder | | `guarded-fetch` | imports `node:dns/promises`, `node:net`, `node:dns` | `guarded-fetch` is the one that bites bundlers targeting a non-Node context: inlining it pulls in Node builtins, and a bundler whose chunking context has no concept of them fails the build (Turbopack reports `the chunking context (unknown) does not support external modules (request: node:dns/promises)`). Next.js 15+: ```ts // next.config.ts const nextConfig = { serverExternalPackages: [ "just-bash", "@mongodb-js/zstd", "node-liblzma", "seek-bzip", "sql.js", "run", "guarded-fetch", ], }; ``` Older Next.js uses `experimental.serverComponentsExternalPackages`. webpack: add them to `externals` (or use `webpack-node-externals`). esbuild/rollup: `--external: