Skip to content

README.md

Latest commit

 

History

History
430 lines (312 loc) · 9.99 KB

README.md

File metadata and controls

430 lines (312 loc) · 9.99 KB
Raw

PhoenixNebula 🐚

A feature-rich, customizable Unix shell implementation written in Python with theme support, job control, and comprehensive command handling.

Python 3.11+ License: MIT PyPI version Code style: black

Features ✨

  • Interactive Command Execution - Full support for executing system commands with proper I/O handling
  • Theme Support - 5 built-in themes (Dracula, Solarized Dark, Nord, Monokai, Gruvbox) plus custom themes
  • Job Control - Background and foreground job management with jobs, fg, and bg commands
  • Pipeline Support - Chain commands using the pipe operator (|)
  • Output Redirection - Redirect output and error streams to files (>, >>, 2>, 2>>)
  • Command Aliases - Create and manage command aliases
  • History Management - Full command history with persistence and custom history files
  • Tab Completion - Smart tab completion for commands and file paths
  • Signal Handling - Proper handling of SIGINT, SIGTSTP, SIGQUIT, and SIGWINCH
  • PTY Support - Interactive programs (vim, git, ssh, etc.) run with proper terminal control
  • Security - No external dependencies, safe input handling, no eval/exec

Installation 📦

Via pip (Recommended)

pip install phoenixnebula-cli
phoenixnebula

Via git + setup.py

git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
sudo python3 setup.py install
phoenixnebula

Via Docker

docker pull nobodydeveloper/phoenixnebula:latest
docker run -it nobodydeveloper/phoenixnebula:latest

Binary Distribution 🛠️

PhoenixNebula can be distributed as a standalone binary, so users can run it without installing Python.

Build with PyInstaller (Recommended)

Install PyInstaller:

pip install pyinstaller
git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
pyinstaller --onefile phoenixnebula/phoenixnebula.py
Run it directly: ./dist/phoenixnebula

### From source (Development)

```bash
git clone https://github.com/SysTechSalihY/phoenixnebula.git
cd phoenixnebula
pip install -e .
phoenixnebula

Quick Start 🚀

Basic Commands

$ echo "Hello, World!"
Hello, World!

$ pwd
/home/user

$ cd Documents

$ ls -la

Background Jobs

Append & to run a command in the background:

$ sleep 100 &
[1] 12345

$ jobs
[1]  Running  sleep 100

$ fg %1

Piping Commands

$ cat file.txt | grep "search_term" | wc -l

Output Redirection

$ echo "text" > output.txt          # Write to file
$ echo "text" >> output.txt         # Append to file
$ command 2> errors.txt             # Redirect stderr
$ command 2>> errors.txt            # Append stderr

Themes

$ theme list
Available themes:
  - dracula *
  - nord
  - solarized_dark
  - monokai
  - gruvbox

$ theme set nord
Theme applied: Nord

Configuration 🎨

Shell Configuration File

Create ~/.phoenixnebularc for aliases and settings:

alias ll=ls -la
alias ..=cd ..
alias gs=git status
export PS1="\u@\h \w\$ "

Themes

PhoenixNebula comes with 5 built-in themes. Create custom themes at ~/.phoenixnebula/themes/mytheme.json:

{
  "name": "My Custom Theme",
  "background": "#1e1e1e",
  "foreground": "#e0e0e0",
  "cursor_color": "#e0e0e0",
  "black": "#000000",
  "red": "#ff0000",
  "green": "#00ff00",
  "yellow": "#ffff00",
  "blue": "#0000ff",
  "purple": "#ff00ff",
  "cyan": "#00ffff",
  "white": "#ffffff",
  "bright_black": "#808080",
  "bright_red": "#ff8080",
  "bright_green": "#80ff80",
  "bright_yellow": "#ffff80",
  "bright_blue": "#8080ff",
  "bright_purple": "#ff80ff",
  "bright_cyan": "#80ffff",
  "bright_white": "#ffffff",
  "prompt_user": "#00ff00",
  "prompt_host": "#00ffff",
  "prompt_path": "#ffff00",
  "prompt_symbol": "#ff00ff"
}

Then apply it:

$ theme set mytheme

Built-in Commands 💻

Navigation & Execution

Command Usage Description
cd cd [directory] Change current directory
pwd pwd Print working directory
echo echo [text] Print text to output
exit exit [code] Exit the shell
type type <command> Display command type
clear clear Clear terminal screen

Command History

Command Usage Description
history history [n] Show last n commands
history -r <file> Load history from file
history -w <file> Write history to file
history -a <file> Append history to file

Aliases

Command Usage Description
alias alias List all aliases
alias [name]=[value] alias ll='ls -la' Create alias
unalias unalias <n> Remove alias

Environment & Variables

Command Usage Description
export export VAR=value Set environment variable
unset unset VAR Unset environment variable
set set [VAR=value] Get/set shell variables

Job Control

Command Usage Description
jobs jobs List background jobs
fg fg %jobid Bring job to foreground
bg bg %jobid Resume job in background

Themes

Command Usage Description
theme theme Show available themes
theme list List all themes
theme set <n> theme set dracula Apply theme
theme current Show current theme

Advanced Features 🔧

Pipeline Operations

Chain multiple commands with pipes:

$ cat data.txt | sort | uniq | wc -l

Variable Expansion

Expand environment variables:

$ echo $HOME
/home/user

$ echo ${PATH}
/usr/local/bin:/usr/bin:/bin

Tilde Expansion

Home directory shortcut:

$ cd ~/Documents
$ cat ~/.bashrc

Interactive Programs

The shell automatically detects and runs interactive programs with proper terminal control:

$ vim file.txt
$ git commit
$ python3

Security 🔒

  • No External Dependencies - Uses only Python standard library
  • Safe Input Handling - All input is validated and parsed safely using shlex
  • No Code Injection - Never uses eval(), exec(), or __import__()
  • Secure Variable Expansion - Variables are safely expanded with fallbacks
  • Signal Safety - Proper signal handling without race conditions
  • Process Isolation - Background jobs properly isolated using process groups

See SECURITY.md for detailed security information.

Testing 🧪

Run the comprehensive test suite:

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ -v --cov=phoenixnebula

# Run specific test class
pytest tests/test_phoenixnebula.py::TestSecurityInputValidation -v

Project Structure 📁

phoenixnebula/
├── phoenixnebula/
│   ├── __init__.py
│   └── phoenixnebula.py
├── tests/
│   └── test_phoenixnebula.py
├── Dockerfile
├── Dockerfile.prod
├── docker-compose.yml
├── setup.py
├── setup.cfg
├── pyproject.toml
├── MANIFEST.in
├── README.md
├── LICENSE
└── .gitignore

Keyboard Shortcuts ⌨️

  • Ctrl+C - Cancel current command
  • Ctrl+Z - Suspend current command
  • Ctrl+D - Exit shell (EOF)
  • Tab - Auto-complete command or file path
  • Up/Down Arrows - Navigate command history
  • Ctrl+R - Reverse history search (if supported)

Environment Variables 🌍

Variable Description
PATH Search path for executables
HOME User's home directory
HISTFILE Location of command history file
SHELL Current shell name
USER Current user name
HOSTNAME System hostname

Troubleshooting 🔧

Shell Exits Unexpectedly

Check your ~/.phoenixnebularc file for errors:

cat ~/.phoenixnebularc

History Not Saving

Ensure the history file location is writable:

export HISTFILE=~/.phoenixnebula_history

Tab Completion Not Working

Verify Python readline module is available:

python3 -c "import readline; print('readline available')"

Interactive Programs Not Working Properly

Ensure your terminal emulator supports ANSI escape codes and PTY operations. Try clearing the screen:

clear

Theme Colors Not Applying

Try resetting the terminal:

reset
phoenixnebula

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/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License 📜

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

Acknowledgments 🙏

  • Inspired by bash, zsh, and other Unix shells
  • Theme colors from popular terminal themes
  • Built with Python's standard library

Support 💬

For issues, questions, or suggestions:

  1. Check existing GitHub Issues
  2. Create a new issue with detailed description
  3. Submit a Pull Request with improvements

Security Policy 🔐

If you discover a security vulnerability, please email salihyilboga98@gmail.com instead of using the issue tracker.

Enjoy using PhoenixNebula! 🎉

For more information and advanced usage, visit the GitHub repository.