filesystem-ghost

README

🔒 FileSystem Ghost

A Cyberpunk Linux Command Learning Game

╔══════════════════════════════════════════════════════════════╗
║  ███████╗██╗██╗     ███████╗███████╗██╗   ██╗███████╗        ║
║  ██╔════╝██║██║     ██╔════╝██╔════╝╚██╗ ██╔╝██╔════╝        ║
║  █████╗  ██║██║     █████╗  ███████╗ ╚████╔╝ ███████╗        ║
║  ██╔══╝  ██║██║     ██╔══╝  ╚════██║  ╚██╔╝  ╚════██║        ║
║  ██║     ██║███████╗███████╗███████║   ██║   ███████║        ║
║  ╚═╝     ╚═╝╚══════╝╚══════╝╚══════╝   ╚═╝   ╚══════╝        ║
║                    ██████╗ ██╗  ██╗ ██████╗ ███████╗████████╗║
║                   ██╔════╝ ██║  ██║██╔═══██╗██╔════╝╚══██╔══╝║
║                   ██║  ███╗███████║██║   ██║███████╗   ██║   ║
║                   ██║   ██║██╔══██║██║   ██║╚════██║   ██║   ║
║                   ╚██████╔╝██║  ██║╚██████╔╝███████║   ██║   ║
║                    ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   ║
╚══════════════════════════════════════════════════════════════╝

🎮 About

FileSystem Ghost is an immersive, cyberpunk-themed terminal game that teaches Linux commands through stealth-based gameplay. You play as an intrusive process that has awakened in a corporate server. To survive and escalate to Root, you must manipulate the environment using real Linux commands.

Features

• 🖥️ Beautiful TUI - Cyberpunk red aesthetic with glitch effects
• 📚 Learn Linux - Master essential commands: ls, cd, cat, mkdir, rm, chmod, and more
• 🕵️ Stealth Mechanics - Avoid detection by security processes
• 📈 Progressive Difficulty - 4 levels from Apprentice to Root
• ⌨️ Fish-style Suggestions - Inline command autocompletion
• 🎯 Objectives System - Find keys, avoid guards, hack permissions

---

🚀 Quick Install

⚡ One Command Install (Recommended)

go install github.com/sazardev/filesystem-ghost/cmd/ghost@latest

That's it! Now run:

ghost

From Source

# Clone the repository
git clone https://github.com/sazardev/filesystem-ghost.git
cd filesystem-ghost

# Install with make
make install

# Or run directly
make run

Script Install (Alternative)

curl -sSL https://raw.githubusercontent.com/sazardev/filesystem-ghost/main/install.sh | bash

---

📦 Requirements

• Go 1.21+ (for building from source)
• Terminal with 256-color support
• Minimum size: 80x24 characters (recommended: 120x40)

Supported Platforms

Platform	Architecture	Status
Linux	amd64, arm64	✅ Fully Supported
macOS	amd64, arm64	✅ Fully Supported
Windows	amd64	⚠️ Experimental (use WSL)

---

🎮 How to Play

Controls

Key	Action
Enter	Execute command
Tab	Autocomplete / Cycle suggestions
→	Accept inline suggestion
↑/↓	Navigate command history
Ctrl+C	Quit game

Basic Commands

ls              # List files in current directory
ls -la          # List all files including hidden
cd <folder>     # Change directory
cat <file>      # Read file contents
pwd             # Show current path
help            # Show available commands
status          # Show your current stats
disconnect      # Complete level objective
disconnect --menu  # Return to main menu

Game Tips

1. Use ls -a to find hidden files (files starting with .)
2. Read everything with cat - files contain clues and keys
3. Watch your noise level - too much noise alerts security
4. Find the keys before using disconnect to advance
5. Use status to check your progress and objectives

---

📖 Levels

Level	Name	Commands	Objective
1	Apprentice	ls, cd, cat, pwd	Find the level1.key
2	Script Kiddie	+ mkdir, touch, rm	Locate admin.key
3	Infiltrator	+ mv, cp, chmod	Retrieve root.key
4	Root User	+ ps, kill, grep	Achieve root access

---

🛠️ Development

Build Commands

make help       # Show all available commands
make build      # Build for current platform
make dev        # Build with debug info
make run        # Build and run
make test       # Run tests
make clean      # Clean build artifacts
make release    # Build for all platforms
make install    # Install system-wide (sudo)
make uninstall  # Remove from system

Project Structure

filesystem-ghost/
├── cmd/ghost/          # Main entry point
├── internal/
│   ├── adapter/
│   │   ├── commands/   # Command handler
│   │   ├── filesystem/ # Virtual filesystem
│   │   └── ui/         # TUI components
│   ├── application/
│   │   └── levels/     # Level definitions
│   └── domain/
│       └── entity/     # Game entities
├── Makefile            # Build automation
├── install.sh          # Quick install script
└── README.md

Tech Stack

• Bubble Tea - TUI framework
• Lip Gloss - Terminal styling
• Bubbles - TUI components
• Afero - Virtual filesystem

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

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

---

🙏 Acknowledgments

• Charm.sh for their amazing TUI libraries
• The Linux community for inspiring this educational game
• Cyberpunk aesthetics for the visual inspiration

---

Happy Hacking! 🔓