bashrs 6.66.0

A bidirectional shell safety tool that transpiles Rust to deterministic POSIX shell scripts and purifies legacy bash into safe, portable shell. Also known as Rash (the library crate). Part of the PAIML Sovereign AI Stack transpiler family alongside depyler and decy.

Table of Contents

• What is bashrs?
• Installation
• Quick Start
• Features
• Architecture
• Quality
• Sovereign AI Stack
• Documentation
• License

What is bashrs?

Shell scripts power CI/CD pipelines, deployment automation, and system configuration across every production environment. They are also notoriously fragile -- unquoted variables, non-idempotent operations, and injection vulnerabilities are the norm, not the exception.

bashrs solves this in two directions:

1. Rust to Shell -- Write type-safe Rust, transpile to deterministic POSIX shell with automatic safety guarantees.
2. Shell to Shell -- Purify existing bash scripts by rewriting unsafe patterns at the AST level, not just warning about them.

Generated scripts run on any POSIX-compliant system with zero runtime dependencies. Same input always produces identical output.

Installation

CLI

cargo install bashrs

Library

Add to your Cargo.toml:

[dependencies]
bashrs = "6.65"

Quick Start

Write Rust, Get Safe Shell

// install.rs
#[rash::main]
fn main() {
    let version = env_var_or("VERSION", "1.0.0");
    let prefix = env_var_or("PREFIX", "/usr/local");

    echo("Installing MyApp {version} to {prefix}");

    mkdir_p("{prefix}/bin");
    mkdir_p("{prefix}/share/myapp");

    if exec("cp myapp {prefix}/bin/") {
        echo("Binary installed");
    } else {
        eprint("Failed to install binary");
        exit(1);
    }
}

Transpile to safe POSIX shell:

bashrs build install.rs -o install.sh

Purify Existing Bash

Before (unsafe bash):

#!/bin/bash
SESSION_ID=$RANDOM                      # Non-deterministic
mkdir /app/releases/$RELEASE            # Non-idempotent
rm /app/current                         # Fails if missing

After (purified by Rash):

#!/bin/sh
session_id="session-${version}"         # Deterministic
mkdir -p "/app/releases/${release}"     # Idempotent
rm -f "/app/current"                    # Safe removal

CLI Usage

# Transpile Rust to shell
bashrs build input.rs -o output.sh

# Purify legacy bash scripts
bashrs purify messy.sh -o clean.sh

# Lint shell scripts (including Dockerfiles)
bashrs lint script.sh

# Quality scoring
bashrs score script.sh

# Interactive REPL
bashrs repl

# Mutation testing
bashrs mutate script.sh --count 10

Features

• POSIX Compliance -- Generated scripts target POSIX sh and run on sh, dash, bash, ash, zsh, and mksh.
• Injection Prevention -- Automatic variable quoting, word-split protection, and glob expansion suppression at the AST level.
• ShellCheck Integration -- All transpiler output passes strict ShellCheck validation (99.9% compliance).
• Dockerfile/Makefile Transpilation -- Transpile and lint Dockerfiles and Makefiles alongside shell scripts.
• Built-in Linter -- 100+ lint rules with auto-fix, severity levels, .bashrsignore support, and watch mode.
• Built-in Formatter -- Configurable shell script formatter with TOML configuration.
• Deterministic Output -- Same input always produces identical scripts. Verified across 17,882 corpus entries.
• MCP Server -- Model Context Protocol server for AI-assisted shell generation (rash-mcp, registered as io.github.paiml/rash).
• LSP Server -- Language Server Protocol for editor integration.
• Mutation Testing -- 10 mutation operators (string, command, conditional, redirect) for test quality verification.

Beyond ShellCheck

Architecture

bashrs is a workspace of five crates:

The transpilation pipeline:

Rust Source --> Parse (syn) --> Rash IR --> POSIX Shell AST --> Emit
                                  |
                                  +--> Makefile AST --> Emit
                                  |
                                  +--> Dockerfile AST --> Emit

The purification pipeline:

Bash Source --> Parse (AST) --> Safety Analysis --> Rewrite --> Emit

Quality

bashrs uses Popperian falsification -- tests attempt to disprove functionality rather than confirm it. A passing test means the falsification attempt failed.

# 130-point transpiler falsification checklist
cargo test -p bashrs --test transpiler_tcode_tests

# 30-point Dockerfile falsification checklist
cargo test -p bashrs --test dockerfile_dcode_tests

Performance

Sovereign AI Stack

bashrs is part of the PAIML Sovereign AI Stack -- a pure-Rust ecosystem for privacy-preserving ML infrastructure.

Documentation

• The Rash Book: paiml.github.io/bashrs -- canonical documentation with tested examples
• API Reference: docs.rs/bashrs
• Cookbook: bashrs-cookbook -- examples and recipes
• Changelog: CHANGELOG.md

Contributing

1. Fork the repository
2. Make changes on the master branch
3. Run quality gates: make lint && make test
4. Run coverage: make coverage
5. Submit a pull request

License

MIT License. See LICENSE for details.