Module bashlite 

bashlite — a tiny, total, sandboxed shell that scripts the platform’s filesystem in one pass (the cost unlock: a multi-step fs chore collapses from N LLM rounds to ONE execute_script tool call). Native-testable core over a bashlite::BashHost trait. See src/bashlite/ + design/bashlite.md. bashlite — a tiny, deterministic, TOTAL shell that scripts the platform’s filesystem in ONE pass (see design/bashlite.md).

The cost unlock: an agent doing a multi-step fs chore today burns one LLM round (full context + ~70 tool schemas) per step. bashlite collapses the chore into a single execute_script tool call — the platform runs the whole script locally and only the final stdout returns to the model.

Shape (mirrors rustlite/): lexer → parser → eval over a [BashHost] trait, so the whole interpreter is native-testable (cargo test) and the browser/CLI just supply the host. NO eval, NO process spawning, NO network.

v1 language subset (this module)

• Variables: x=value, x=$(cmd); $x / ${x} interpolation; $? exit.
• Pipes: a | b | c (stdout → stdin).
• Short-circuit chains: a && b (run b iff a exited 0), a || b (iff nonzero); mixed cond && a || b is the ternary (skip, not break).
• Control flow: if/elif/else/fi, for NAME in …; do … done, while …; do … done.
• Tests: [ … ] / test … (string =/!=/-z/-n, int -eq/-lt/…, file -e/-f/-d PATH).
• Command substitution: $(…) (nested, subshell vars, shared fuel).
• Builtins (fs): echo, cd, pwd, ls, cat, grep, find, wc, head/tail (first/last N stdin lines), mkdir, write/create (CREATE-only), true/false.
• Composition (run/source/.): execute another .bl script in a nested evaluator (shared fs + fuel) — a script is a composition of scripts. FRACTAL: the sub-script can itself run more, bounded by the shared fuel.
• Host extension: a [BashHost] adds commands by overriding run_builtin (e.g. the lh-* platform reads in [platform]) — the evaluator routes every non-control command through it, so “localharnesslite” is just more commands.
• for NAME in $(…) FIELD-SPLITS on whitespace (the fan-out pattern).
• Quoting: 'single' literal, "double" interpolating, \ escape.
• BOUNDED: a fuel budget caps total commands + loop iterations so a while true (or run-recursion) can’t hang; output is byte-capped.

Deferred to v2 (intentionally NOT in v1 — see design/bashlite.md)

• Value-MOVING lh-* commands (lh-send, lh-create, …) + the dry-run-manifest confirm flow. (Read-only lh-* ship in [platform].)
• break / continue / return, functions, here-docs, redirection (>/>>/< — REJECTED with a parse error, never lexed as literal args), real regex grep, file-arg wc, field splitting of unquoted expansions OUTSIDE for items, globbing, arithmetic $(( )).

Re-exports

pub use eval::Evaluator;

pub use eval::ScriptResult;

pub use eval::DEFAULT_FUEL;

pub use eval::MAX_OUTPUT_BYTES;

pub use eval::MAX_SCRIPT_SIZE;

pub use host::BashHost;

pub use host::Output;

Modules

ast

Script AST. Abstract syntax for bashlite — a tiny, total shell.

builtins

FS-only builtin commands over crate::filesystem::Filesystem. The v1 builtin commands — fs-only, over crate::filesystem::Filesystem.

eval

Bounded, total evaluator. The evaluator: walk a parsed script, expand words, run pipelines through the BashHost, and accumulate stdout. TOTAL + BOUNDED — every loop iteration and command spends one unit of FUEL, so a while true can’t hang the tab (it returns a clear “fuel exhausted” error instead).

host

The BashHost seam + Output. The host seam: BashHost is everything the pure evaluator needs from the outside world. Eval never touches a real filesystem or clock directly — it goes through this trait, so the lexer/parser/eval run unchanged under cargo test with an in-memory host and in the browser over OPFS.

lexer

Shell-shaped byte lexer. Byte-level lexer: source → [Token]s. Shell-shaped, not Rust-shaped.

parser

Recursive-descent parser. Recursive-descent parser: [Token]s → a list of [Stmt]s.

platform

Read-only lh-* platform commands (localharnesslite). Needs wallet. localharnesslite — read-only lh-* platform commands for bashlite.

token

Token kinds. Token types for the bashlite lexer.

Structs

BashError

An error from any stage (lex, parse, or a fatal runtime condition like fuel exhaustion). A command FAILING (nonzero exit) is NOT an error — that’s a normal Output with a nonzero code that the script can branch on. Only a malformed script or a runaway guard produces a BashError.

Enums

BashErrorKind

The category of a BashError.

Functions

resolve_path

Resolve path against cwd into a normalized sandbox path the way the fs builtins do — so a host that reads a file ITSELF (e.g. lh-publish’s source arg, before platform::dispatch_write) resolves it identically. Absolute path ignores cwd; ./.. collapse; .. clamps to root (no escape).

run

Compile + run source against host with the default fuel budget, returning the accumulated stdout/stderr/exit code.

run_with_fuel

Like run but with an explicit fuel budget (commands + loop iterations).