🐧 PenguShell (pengushell)

A lightweight compatibility layer for Windows PowerShell that allows developers to run typical Linux/Unix commands natively. Written entirely in Node.js, PenguShell requires no external Linux binaries, WSL, or virtual machines, making it the perfect developer-experience enhancement tool on Windows.

🚀 Features

• 🟢 Native Node.js Implementation: Completely portable cross-platform JavaScript under the hood.
• 🔀 Pipes & Streams: Full standard stream pipe (|) support to chain commands (e.g. cat file.log | grep Error).
• 📁 Smart Path Conversion: Automatic translation between Windows paths (e.g., C:\Users\...) and Linux style path syntax (e.g., /c/users/...).
• ⚙️ Recursive Alias Engine: Expand shortcuts dynamically (e.g. ll to ls -l, la to ls -la) with built-in loop/cycle detection.
• 🛠️ Raw Mode Text Editor: Built-in nano (MVP clone) with cursor navigation, modifications tracking, and safe file saving.
• 🎨 Hacker Green UI: Highly readable, premium retro terminal styling powered by chalk with user toggling.
• 🔍 POSIX-Grade Grep: Highly optimized searching, regular expressions support, matching highlights, line numbers, counting, and inversion.
• ⌨️ Tab Autocomplete: Interactive command and file/folder path completions in the REPL.
• 📜 Persistent Session History: Commands logged to %APPDATA%/pengushell/history.log to persist shell history across sessions.
• 📂 Wildcard Globbing: Native pattern expansion (* and ? wildcard operators) integrated directly into the parser.

📦 Installation

To use PenguShell globally anywhere in your terminal, install it via NPM:

# Install globally
npm install -g pengushell

Alternatively, you can run it directly using npx:

npx pengushell

🎮 Usage

PenguShell can be run in two modes:

1. Interactive REPL Mode

Running pengushell with no arguments starts an interactive session:

pengushell

Example output:

username@hostname:~$ ls -l
drw-rw-rw- 1 user group        0 30/05/2026, 17:40:00 bin
-rw-rw-rw- 1 user group      726 30/05/2026, 17:40:00 package.json

2. Direct Execution Mode

Run a one-off compatibility command or pipeline and exit with standard codes:

pengushell ls -la
pengushell "cat package.json | grep chalk"

3. Extended Shell Features

PenguShell provides several built-in desktop terminal experiences natively:

• Native Wildcard Globbing: Use standard pattern matching (* and ? operators) for file parameters:

  # List all files ending in .json
  pengushell ls *.json
  
  # Find references to "chalk" in any package file
  pengushell "grep chalk package*.json"

• Command & Path Autocomplete: In interactive REPL mode, press Tab once to view matching commands or double-tab to complete directory and file paths:

  user@hostname:~$ cd s[Tab]
  # Completes automatically to:
  user@hostname:~$ cd src/

• Persistent Command History: Command navigation is saved automatically. Hit the Up and Down arrow keys in the REPL to browse commands run in past terminal sessions. Logs are saved inside %APPDATA%/pengushell/history.log.

🛠️ Commands Reference

| Command | Options | Description | | :--- | :--- | :--- | | ls | -a, -l | Lists directory contents with permissions, owner, sizes, and timestamps | | cd | [path] | Changes the current working directory (supports ~ home directory) | | pwd | None | Prints the current directory in Unix format | | cat | -n | Concatenates and displays files (reads from standard input if empty) | | mkdir| -p | Creates directories (ignores existing directories with -p) | | rm | -r, -f | Removes files and directories recursively and/or forcefully | | cp | -r | Copies files and directories recursively | | mv | None | Moves files and directories (handles cross-drive EXDEV copy-and-delete fallbacks) | | touch| None | Creates new files or updates access and modification timestamps | | grep | -i, -v, -c, -n, -F | Searches text streams/files using regular expressions or literals | | nano | [file] | MVP text editor with raw terminal inputs, save (^O), and exit (^X) | | clear| None | Resets the terminal screen output | | echo | -n | Prints text (omits trailing newline with -n) | | whoami| None | Outputs the current logged-in user name | | hostname| None | Prints the system host name |

⚙️ Configuration

PenguShell generates a config file at:

• Windows: %APPDATA%/pengushell/config.json
• macOS/Linux: ~/.config/pengushell/config.json

Interactive Configuration

You can manage settings interactively:

pengushell config

CLI Config Options

# View configuration settings and path
pengushell config list

# View only the config file location
pengushell config path

# Modify settings directly
pengushell config set useColors false
pengushell config set hackerGreenMode true

💻 Development & Testing

Setup

Clone the repository, install dependencies, and run:

git clone https://github.com/aneesh-srivastava-11/PenguShell.git
cd PenguShell
npm install

Run Tests

PenguShell includes a comprehensive test suite targeting lexing, parsing, configs, and command outputs:

npm test

Local CLI Linking

To link the command globally for local testing:

npm link

📤 Publishing Instructions

To publish your own version of pengushell to the NPM registry, execute:

1. Log in to NPM:

   npm login

2. Ensure Tests Pass:

   npm test

3. Bump Version (Select major, minor, or patch):

   npm version patch

4. Publish Package:

   npm publish --access public

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository.
2. Create a 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

Distributed under the MIT License. See LICENSE for more information.