# prefix-dev/shell architecture

> Architecture diagram of the GitHub repository prefix-dev/shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prefix-dev/shell
- Repository: https://github.com/prefix-dev/shell

## Overview

##### Project Type and Purpose
- This is an open-source, cross-platform command-line shell written in Rust. It aims to emulate Bash behavior (parsing, built-ins, piping, etc.) natively on Windows, macOS, and Linux.
- It is structured as a Cargo workspace with multiple crates:
- crates/deno_task_shell – a parsing/execution library (shared logic)
- crates/shell – the main CLI application (binary)
- crates/tests – integration test harness and test data
- It also includes example scripts (in /scripts) and CI, formatting, and container configurations at the repo root.

##### File Structure Analysis
- Top-level: workspace root, tooling configs (.github workflows, .devcontainer, .vscode, Cargo.toml, etc.).
- crates/deno_task_shell:
- Implements a Pest grammar (grammar.pest) and parser.rs
- Defines core execution logic, types, shell command definitions (in shell/commands/*).
- crates/shell:
- Binary entry point (main.rs)
- CLI interaction and REPL (completion.rs using rustyline)
- Execution engine (execute.rs), command dispatcher, helpers.
- Built-in commands (commands/*).
- crates/tests: defines test_runner and test_builder to execute the shell against sample scripts in test-data.
- scripts/: example shell scripts used by developers and CI.

##### Key Architecture Insights from README
- Uses Pest for parsing shell syntax.
- Links to coreutils crate for many Unix-style commands.
- Supports tab completion and history via rustyline.
- Provides both interactive REPL and one-off script execution modes.
- Early alpha but usable for daily scripting.

a. Main Components
- CLI Frontend / REPL Layer
- Script Runner / Batch Mode Layer
- Parser Module (Pest grammar → AST)
- Execution Engine / Dispatcher
- Built-In Command Modules
- External Command Invoker (coreutils, OS subprocesses)
- Environment & State (variables, working dir, I/O streams)
- Test Harness (for integration tests)
b. Relationships & Data Flow
- User Input (keyboard or script file) → Rustyline REPL or script runner
- → Parser → AST → Execution Engine
- Execution Engine decides:
- Built-In? → call Rust implementation (e.g., cd, echo)
- External? → spawn via coreutils crate / OS
- Execution results feed back into the Environment (exit codes, variable exports)
- REPL displays output and updates history
- Test Harness drives the script runner, captures results for CI
c. Architectural Patterns and Principles
- Modular “crate” decomposition (library vs. binary vs. tests)
- Separation of Concerns: parsing (deno_task_shell) vs. runtime (shell)
- Clean layering: CLI → Parser → Dispatcher → Executor → OS
- Dependency inversion: coreutils for external commands, Pest for parsing
d. Technologies & Frameworks
- Rust & Cargo workspace
- Pest (parser generator)
- rustyline (REPL, history, tab completion)
- coreutils crate (cross-platform commands)
- CI: GitHub Actions for linting, testing, coverage
- Devcontainer for reproducible dev environments

##### Essential Details
- How environment state (vars, cwd) flows between built-ins and external commands.
- Don’t omit the test harness and example scripts—they validate core functionality.
- Workspace structure (three crates) and how they depend on each other.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    User["User Input\n(keyboard)"]:::user
    ScriptFile["Script File"]:::artifact
    CI["CI Pipeline"]:::external

    %% Workspace Libraries
    subgraph "Workspace Libraries"
        direction TB
        subgraph "crates/deno_task_shell" 
            direction TB
            Grammar["grammar.pest"]:::library
            ParserRS["parser.rs"]:::library
            Types["types.rs\n(Environment & State)"]:::library
            FSUtil["fs_util.rs"]:::library
            SharedCommands["commands/*.rs\n(Built-In Shared)"]:::library
            CoreExecute["execute.rs\n(Execution Engine)"]:::library
        end
        subgraph "crates/shell"
            direction TB
            MainRS["main.rs\n(CLI Frontend)"]:::binary
            Completion["completion.rs\n(Tab Completion)"]:::binary
            LibRS["lib.rs\n(Script Runner)"]:::binary
            ShellExecute["execute.rs\n(Batch Mode)"]:::binary
            CLICommands["commands/*.rs\n(Built-In CLI)"]:::binary
        end
        subgraph "crates/tests"
            direction TB
            TestRunner["test_runner.rs"]:::test
            TestBuilder["test_builder.rs"]:::test
            TestData["test-data/"]:::test
        end
    end

    %% Scripts and Config
    Scripts["scripts/"]:::artifact
    Config[".github/, .devcontainer/, .vscode/, Cargo.toml"]:::config

    %% External Integrations
    Pest["Pest Parser"]:::external
    Rustyline["rustyline REPL"]:::external
    Coreutils["coreutils crate"]:::external
    OS["OS/Subprocess"]:::external

    %% Flow: Interactive
    User -->|types command| MainRS
    MainRS --> Completion
    MainRS -->|reads| Rustyline
    MainRS -->|forwards| ParserRS
    Completion -->|uses| Rustyline

    %% Flow: Batch
    ScriptFile --> LibRS
    LibRS --> ShellExecute

    %% Parsing
    Grammar --> ParserRS
    ParserRS -->|generates AST| CoreExecute
    CoreExecute -->|invokes| SharedCommands
    CoreExecute -->|spawns| Executable

    %% Execution (CLI and Batch)
    ShellExecute -->|calls| CoreExecute
    ShellExecute -->|uses| SharedCommands
    ShellExecute -->|forks| Executable

    %% Command Dispatch
    CoreExecute -->|dispatch| SharedCommands
    SharedCommands -->|may use| FSUtil
    CLICommands -->|override/extensions| SharedCommands

    CoreExecute -->|external| Coreutils
    Executable ---|spawns| OS

    %% Environment & State
    Types --> CoreExecute
    Types --> SharedCommands
    FSUtil --> SharedCommands
    Types --> Executable

    %% Test Harness
    TestRunner --> TestBuilder
    TestBuilder --> Scripts
    TestRunner --> LibRS

    %% CI Pipeline
    CI --> TestRunner
    CI --> Scripts
    CI --> Config

    %% Click Events
    click MainRS "https://github.com/prefix-dev/shell/blob/main/crates/shell/src/main.rs"
    click Completion "https://github.com/prefix-dev/shell/blob/main/crates/shell/src/completion.rs"
    click LibRS "https://github.com/prefix-dev/shell/blob/main/crates/shell/src/lib.rs"
    click ShellExecute "https://github.com/prefix-dev/shell/blob/main/crates/shell/src/execute.rs"
    click Grammar "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/grammar.pest"
    click ParserRS "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/parser.rs"
    click CoreExecute "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/shell/execute.rs"
    click SharedCommands "https://github.com/prefix-dev/shell/tree/main/crates/deno_task_shell/src/shell/commands/"
    click CLICommands "https://github.com/prefix-dev/shell/tree/main/crates/shell/src/commands/"
    click Executable "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/shell/commands/executable.rs"
    click Types "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/shell/types.rs"
    click FSUtil "https://github.com/prefix-dev/shell/blob/main/crates/deno_task_shell/src/shell/fs_util.rs"
    click TestRunner "https://github.com/prefix-dev/shell/blob/main/crates/tests/src/test_runner.rs"
    click TestBuilder "https://github.com/prefix-dev/shell/blob/main/crates/tests/src/test_builder.rs"
    click TestData "https://github.com/prefix-dev/shell/tree/main/crates/tests/test-data/"
    click Scripts "https://github.com/prefix-dev/shell/tree/main/scripts/"

    %% Styles
    classDef library fill:#D6EFFF,stroke:#005B96,color:#003F6B
    classDef binary fill:#DFFFE0,stroke:#228B22,color:#006400
    classDef test fill:#FFF4C1,stroke:#CCA300,color:#7F6000
    classDef external fill:#F0F0F0,stroke:#888888,color:#555555
    classDef user fill:#FFEBE0,stroke:#CC5500,color:#8B0000
    classDef artifact fill:#E8F4FF,stroke:#4682B4,color:#104E8B
    classDef config fill:#F5F5F5,stroke:#A9A9A9,color:#696969
```
