SuperShell 🐚 🚀

SuperShell is a terminal-based RPG that turns your command line into a video game.

It runs silently in the background of your actual shell (Zsh/Bash). As you navigate your file system and run real commands, SuperShell tracks your progress, unlocks chapters, and guides you through a sci-fi narrative—all while teaching you actual CLI skills.

🎮 How to Play

1. The Game

Start the game by launching the first mission:

supershell

2. The Menu

Or start the game by opening the mission selector:

supershell --menu

3. Hints

If you're stuck on a certain task, try to get a hint from the system.

supershell --hint

🚀 How it Works

SuperShell monitors your terminal activity via a shell hook. When you complete a task defined in a quest's YAML file located in the library/ directory, the engine provides immediate feedback, plays narrative cutscenes, and advances the quest state.

🛠 Features

• Hierarchical Design: Lessons are organized into Quests (Seasons), Chapters (Episodes), and atomic Tasks.
• Narrative-Driven: Separate fields for "Flavor Text" and "Technical Objectives."
• Persistent State: Progress is saved automatically to your system's standard data directory.
• Hybrid Validation: Uses a mix of system checks (IsDirectory, PathMissing) and Regex pattern matching to verify objectives.

⌨️ Commands

• supershell: Displays the current chapter title and your active objective.
• supershell --reset: Wipes all progress and restarts the curriculum from the beginning.
• supershell --menu: Displays the quest/module selection menu.
• supershell --hint: Displays a hint for the current in-game task.

📂 Data Locations (Linux/MacOS)

Supershell adheres to the XDG Base Directory Specification:

• Content: ~/.local/share/supershell/quests.yaml
• Save Data: ~/.local/share/supershell/save.json

🛠️ Installation

Option 1: The Rust Way (Recommended)

If you have Rust installed, you can grab the game directly from crates.io:

cargo install supershell
supershell

Option 2: Standalone Binary

1. Download the latest release for your OS from the Releases Page.
2. Extract the archive.
3. Run the binary:

   ./supershell
   

(Note: The game will automatically install its game files to your system on the first run.)

Note on the Shell Hook: The installer adds a small function to your shell config. This function runs supershell --check "$HISTORY" after every command you type, allowing the game to react to your actions in real-time.

📂 The Construct

Most missions take place inside a safe, sandboxed directory called The Construct:

~/Construct

The game will automatically generate files, folders, and puzzles inside this directory. You can delete it at any time; the game will rebuild it when you load a mission.

🧱 Creating Custom Quests

SuperShell is data-driven. You can write your own missions using YAML files in the library/ folder.

Example Quest Structure:

quests:
  - id: "03_permissions"
    title: "Module 03: Security"
    construct: true  # Requires user to be in ~/Construct
    chapters:
      - title: "The Locked Door"
        intro: "You encounter a file you cannot read..."
        setup_actions:
          - type: CreateFile
            path: "secret.data"
            content: "TOP SECRET"
        tasks:
          - description: "Change permissions"
            objective: "chmod +x secret.data"
            conditions:
              - type: CommandMatches
                pattern: "^chmod \\+x"

🐛 Troubleshooting

"The game isn't reacting!"

1. Ensure you have selected a mission via supershell --menu.
2. Restart your terminal to ensure the shell hook is loaded.
3. Check if you are inside ~/Construct (if the mission requires it).

"I want to uninstall" Remove the supershell binary and delete the lines added to your .zshrc or .bashrc.

rm -rf ~/.local/share/supershell

📜 Release History

v0.4.1: The "Self-Extracting" Update

Summary: This release radically simplifies installation. The supershell binary now carries the entire game library inside itself. When you run it for the first time, it automatically installs the necessary assets to your system.

New Features:

• 📦 Self-Extracting Binary: The library/ folder is now embedded in the executable. No external installation scripts are required.
• 🚀 Crates.io Support: You can now install the full game with a single command: cargo install supershell.
• 🛠️ Auto-Repair: If the game detects the library folder is missing (e.g., accidental deletion), it will automatically restore the default quests on the next launch.

Changes:

• Removed install.sh and uninstall.sh (deprecated).
• Simplified distribution artifacts to just the binary and README.
• Updated internal path resolution to handle embedded asset extraction.

v0.4.0 - The Stability Update

• Universal YAML Loader: The engine now intelligently parses quest files in multiple formats (Wrapped Object, List, or Single Object), preventing crashes when loading user-created content.
• Graceful Degradation: Optional fields in Quest/Chapter definitions (like setup_actions) are now handled gracefully. Missing fields no longer cause the application to panic or fail silently.
• Startup Fixes: Resolved an issue where a fresh installation would initialize with an empty Quest ID, causing the game to boot into a "do nothing" state. The default is now set to 01_awakening.
• Error Visibility: File system errors (permissions, missing directories) during the library scan are now logged to stderr as [CRITICAL ERROR] instead of being swallowed silently.

v0.3.1 (The Distribution Patch)

• Fixed: Critical installer bug on macOS regarding Read-only file system errors.
• Fixed: Improved shell detection to correctly identify Zsh vs Bash based on user login.
• Fixed: Aligned install.sh data paths with Rust's native directories crate on macOS.

v0.3.0 (The Architecture Update)

• Breaking: Complete engine rewrite to 4-tier hierarchy (Quest -> Chapter -> Task).
• Breaking: Renamed Checkpoint to Task in internal logic.
• Breaking: Previous save.json files are incompatible. Run with --reset.
• New: Added support for multi-chapter "Quests" (Seasons).
• New: Cinematic Intros and Outros now trigger on Chapter transitions.
• New: Added native Condition types (e.g., IsDirectory, WorkingDir) for robust validation.
• Fixed: Input handling now correctly accepts [ENTER] to advance cutscenes.

v0.2.0 (The Hierarchy Update)

• Breaking: New YAML structure (Chapters & Checkpoints).
• New: Automated "Next Objective" reveals after tasks.
• New: Added --reset flag for easier testing.
• Fixed: Prevented "Success Loop" on final missions.

v0.1.0

• Initial proof of concept with flat quest list.

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.