🐧 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.