just-bash 2.9.8 → 2.10.1

package/README.md

@@ -26,6 +26,7 @@ Supports optional network access via `curl` with secure-by-default URL filtering
 - [Default Layout](#default-layout)
 - [Network Access](#network-access)
 - [Execution Protection](#execution-protection)
+- [AST Transform Plugins](#ast-transform-plugins)
 - [Development](#development)
 
 ## Security model
@@ -73,6 +74,22 @@ const env = new Bash({
 await env.exec("echo $TEMP", { env: { TEMP: "value" }, cwd: "/tmp" });
 ```
 
+#### Lazy Files
+
+File values can be functions (sync or async). The function is called on first read and the result is cached — if the file is written to before being read, the function is never called:
+
+```typescript
+const env = new Bash({
+  files: {
+    "/data/config.json": () => JSON.stringify({ key: "value" }),
+    "/data/remote.txt": async () => (await fetch("https://example.com")).text(),
+    "/data/static.txt": "always loaded",
+  },
+});
+```
+
+This is useful for large or expensive-to-compute content that may not be needed.
+
 ### Custom Commands
 
 Extend just-bash with your own TypeScript commands using `defineCommand`:
@@ -435,6 +452,30 @@ const env = new Bash({
 
 All limits have sensible defaults. Error messages include hints on which limit to increase. Feel free to increase if your scripts intentionally go beyond them.
 
+## AST Transform Plugins
+
+Parse bash scripts into an AST, run transform plugins, and serialize back to executable bash. Useful for instrumenting scripts (e.g., capturing per-command stdout/stderr) or analyzing them (e.g., extracting command names) before execution.
+
+```typescript
+import { Bash, BashTransformPipeline, TeePlugin, CommandCollectorPlugin } from "just-bash";
+
+// Standalone pipeline — output can be run by any shell
+const pipeline = new BashTransformPipeline()
+  .use(new TeePlugin({ outputDir: "/tmp/logs" }))
+  .use(new CommandCollectorPlugin());
+const result = pipeline.transform("echo hello | grep hello");
+result.script;             // transformed bash string
+result.metadata.commands;  // ["echo", "grep", "tee"]
+
+// Integrated API — exec() auto-applies transforms and returns metadata
+const bash = new Bash();
+bash.registerTransformPlugin(new CommandCollectorPlugin());
+const execResult = await bash.exec("echo hello | grep hello");
+execResult.metadata?.commands; // ["echo", "grep"]
+```
+
+See [src/transform/README.md](src/transform/README.md) for the full API, built-in plugins, and how to write custom plugins.
+
 ## Development
 
 ```bash

package/dist/Bash.d.ts

@@ -13,6 +13,7 @@ import type { IFileSystem, InitialFiles } from "./fs/interface.js";
 import { type ExecutionLimits } from "./limits.js";
 import { type NetworkConfig } from "./network/index.js";
 import type { DefenseInDepthConfig } from "./security/types.js";
+import type { BashTransformResult, TransformPlugin } from "./transform/types.js";
 import type { BashExecResult, Command, FeatureCoverageWriter, TraceCallback } from "./types.js";
 export type { ExecutionLimits } from "./limits.js";
 /**
@@ -167,6 +168,7 @@ export declare class Bash {
     private logger?;
     private defenseInDepthConfig?;
     private coverageWriter?;
+    private transformPlugins;
     private state;
     constructor(options?: BashOptions);
     registerCommand(command: Command): void;
@@ -176,4 +178,6 @@ export declare class Bash {
     writeFile(path: string, content: string): Promise<void>;
     getCwd(): string;
     getEnv(): Record<string, string>;
+    registerTransformPlugin(plugin: TransformPlugin<any>): void;
+    transform(commandLine: string): BashTransformResult;
 }