just-bash 2.9.8 → 2.10.0

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
@@ -435,6 +436,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;
 }