@fredlackey/devutils 0.0.1 → 0.0.3

package/src/installs/winpty.md

@@ -0,0 +1,620 @@
+# Installing winpty
+
+## Overview
+
+winpty is a Windows software package that provides an interface similar to a Unix pty-master for communicating with Windows console programs. It enables interactive console applications (like Python REPL, Node.js REPL, and Docker) to work correctly in terminal emulators that do not natively support Windows console programs, such as MinTTY (used by Git Bash), Cygwin terminals, and MSYS2.
+
+The package consists of:
+
+- **libwinpty** - A library for embedding pty functionality
+- **winpty.exe** - A command-line wrapper for running Windows console programs
+- **winpty-agent.exe** - A background process that bridges between console API and terminal I/O
+
+winpty works by starting a hidden console window via winpty-agent.exe, which bridges between the Windows console API and terminal input/output escape codes. It polls the hidden console's screen buffer for changes and generates corresponding output streams.
+
+**Important**: winpty is a Windows-only tool. It is not needed on Unix-like systems (macOS, Linux) because those operating systems have native pseudoterminal (PTY) support built into the kernel.
+
+This guide documents winpty installation procedures for all platforms supported by DevUtils CLI.
+
+## Dependencies
+
+### macOS (Homebrew)
+- **Required:** None
+- **Note:** winpty is Windows-only and is not applicable to macOS. macOS has native PTY support.
+
+### Ubuntu (APT/Snap)
+- **Required:** None
+- **Note:** winpty is Windows-only and is not applicable to Ubuntu/Linux. Linux has native PTY support via `/dev/pts`.
+
+### Raspberry Pi OS (APT/Snap)
+- **Required:** None
+- **Note:** winpty is Windows-only and is not applicable to Raspberry Pi OS. Linux has native PTY support.
+
+### Amazon Linux (DNF/YUM)
+- **Required:** None
+- **Note:** winpty is Windows-only and is not applicable to Amazon Linux. Linux has native PTY support.
+
+### Windows (Chocolatey/winget)
+- **Required:** None (winpty is bundled with Git for Windows by default)
+- **Optional:**
+  - `git` - If Git for Windows is installed, winpty is already available via `choco install git -y`
+- **Auto-installed:** None
+
+### Git Bash (Manual/Portable)
+- **Required:**
+  - `git` - Git for Windows must be installed. Install via `choco install git -y` from an Administrator PowerShell/CMD. winpty is bundled with Git for Windows.
+- **Optional:** None
+- **Auto-installed:** winpty is automatically installed as part of Git for Windows
+
+## Prerequisites
+
+Before installing winpty on any platform, understand these key points:
+
+1. **winpty is Windows-only** - It solves a Windows-specific problem where terminal emulators like MinTTY cannot directly communicate with Windows console programs
+2. **Git for Windows includes winpty** - If you have Git Bash installed, you already have winpty
+3. **No installation needed on Unix systems** - macOS, Linux, and other Unix-like systems have native PTY support and do not need winpty
+
+## Platform-Specific Installation
+
+### macOS (Homebrew)
+
+#### Not Applicable
+
+winpty is a Windows-only utility and is not available or needed on macOS.
+
+**Why winpty is not needed on macOS:**
+
+macOS is a Unix-based operating system with native pseudoterminal (PTY) support built into the kernel. The PTY system in macOS allows terminal emulators (like Terminal.app, iTerm2) to communicate directly with console programs without requiring a translation layer.
+
+The functionality that winpty provides on Windows (bridging between terminal emulators and console programs) is handled natively by macOS through:
+
+- The `/dev/pty*` device files
+- The `posix_openpt()` and related POSIX functions
+- Native support in all macOS terminal emulators
+
+**If you are looking for PTY-related functionality for development:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+brew install --quiet pexpect
+pip3 install pexpect
+```
+
+---
+
+### Ubuntu/Debian (APT)
+
+#### Not Applicable
+
+winpty is a Windows-only utility and is not available or needed on Ubuntu/Debian Linux.
+
+**Why winpty is not needed on Ubuntu:**
+
+Ubuntu and Debian are Linux distributions with native pseudoterminal (PTY) support built into the kernel. The PTY subsystem in Linux allows terminal emulators (like GNOME Terminal, Konsole, xterm) to communicate directly with console programs.
+
+Linux provides PTY functionality through:
+
+- The `/dev/pts` filesystem (devpts)
+- The `posix_openpt()`, `grantpt()`, `unlockpt()`, and `ptsname()` functions
+- Native kernel support via the `CONFIG_UNIX98_PTYS` option
+
+**If you are looking for PTY-related functionality for development:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-pexpect
+```
+
+---
+
+### Raspberry Pi OS (APT)
+
+#### Not Applicable
+
+winpty is a Windows-only utility and is not available or needed on Raspberry Pi OS.
+
+**Why winpty is not needed on Raspberry Pi OS:**
+
+Raspberry Pi OS is based on Debian Linux and has native pseudoterminal (PTY) support built into the kernel. This applies to both 32-bit (armhf) and 64-bit (arm64) versions of Raspberry Pi OS.
+
+The PTY system works identically to standard Linux:
+
+- PTY devices are available at `/dev/pts/*`
+- All terminal emulators communicate directly with console programs
+- No translation layer is required
+
+**If you are looking for PTY-related functionality for development:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-pexpect
+```
+
+---
+
+### Amazon Linux (DNF/YUM)
+
+#### Not Applicable
+
+winpty is a Windows-only utility and is not available or needed on Amazon Linux.
+
+**Why winpty is not needed on Amazon Linux:**
+
+Amazon Linux (both AL2 and AL2023) is a Linux distribution with native pseudoterminal (PTY) support built into the kernel. Whether running on EC2 instances or other environments, PTY support is available out of the box.
+
+**If you are looking for PTY-related functionality for development:**
+
+**For Amazon Linux 2023:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+sudo dnf install -y python3-pexpect
+```
+
+**For Amazon Linux 2:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+sudo yum install -y python3-pexpect
+```
+
+---
+
+### Windows (Git for Windows - Recommended)
+
+#### Prerequisites
+
+- Windows 10 version 1903 or higher (64-bit), or Windows 11
+- Administrator PowerShell or Command Prompt
+- Internet connectivity
+
+**Important**: winpty is bundled with Git for Windows. If you have Git for Windows installed, winpty is already available. This is the recommended approach because Git for Windows is widely used and includes winpty automatically.
+
+#### Installation Steps
+
+**Option: Install Git for Windows (includes winpty)**
+
+Run the following command in an Administrator PowerShell or Command Prompt:
+
+```powershell
+choco install git -y
+```
+
+The `-y` flag automatically confirms all prompts, enabling fully non-interactive installation. This installs:
+
+- Git command-line tools
+- Git Bash (MinTTY terminal)
+- winpty (for interactive console program support in MinTTY)
+- Git Credential Manager
+
+After installation, close and reopen your terminal to ensure PATH changes take effect.
+
+#### Verification
+
+Open Git Bash and verify winpty is available:
+
+```bash
+which winpty
+```
+
+Expected output:
+
+```
+/usr/bin/winpty
+```
+
+Test winpty by running an interactive program:
+
+```bash
+winpty cmd.exe
+```
+
+This should open a Windows Command Prompt within Git Bash. Type `exit` to return to Git Bash.
+
+Verify the version (winpty does not have a `--version` flag, but you can check it exists):
+
+```bash
+winpty --help
+```
+
+Expected output includes usage information:
+
+```
+Usage: winpty [options] [--] program [args]
+...
+```
+
+#### Troubleshooting
+
+**Problem**: `winpty: command not found` in Git Bash
+
+**Solution**: winpty is included with Git for Windows. If Git Bash is installed but winpty is missing, your Git for Windows installation may be corrupted or very old. Reinstall Git for Windows:
+
+```powershell
+choco uninstall git -y
+choco install git -y
+```
+
+**Problem**: winpty is present but interactive programs still do not work
+
+**Solution**: Ensure you are prefixing the command with `winpty`:
+
+```bash
+# Wrong - may not work with interactive programs
+python
+
+# Correct - use winpty prefix
+winpty python
+```
+
+**Problem**: "the input device is not a TTY" error
+
+**Solution**: This error occurs when running interactive programs without winpty in Git Bash. Use the winpty prefix:
+
+```bash
+winpty docker run -it ubuntu bash
+winpty python
+winpty node
+```
+
+**Problem**: winpty breaks piping or redirection
+
+**Solution**: winpty is designed for interactive use, not for piping. When piping data, run commands without winpty:
+
+```bash
+# Without winpty for piping
+echo "print('hello')" | python
+
+# With winpty for interactive use
+winpty python
+```
+
+---
+
+### WSL (Ubuntu)
+
+#### Not Applicable
+
+winpty is a Windows-only utility and is not needed within WSL.
+
+**Why winpty is not needed in WSL:**
+
+WSL (Windows Subsystem for Linux) runs a real Linux kernel (WSL 2) or a Linux-compatible layer (WSL 1). Within WSL, you have native Linux PTY support through the kernel, just like any other Linux distribution.
+
+The WSL terminal environment communicates with programs using standard Linux PTY mechanisms, so winpty is unnecessary.
+
+**Important distinction:**
+
+- **Inside WSL**: You are running Linux; use native PTY (no winpty needed)
+- **In Windows outside WSL**: Use winpty with Git Bash/MinTTY for interactive Windows console programs
+
+**If you are looking for PTY-related functionality for development in WSL:**
+
+```bash
+# Python's built-in pty module (no installation needed)
+python3 -c "import pty; print('PTY support available')"
+
+# For more advanced PTY handling in Python
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y python3-pexpect
+```
+
+---
+
+### Git Bash (Bundled Installation)
+
+#### Prerequisites
+
+- Windows 10 or Windows 11 (64-bit)
+- Git for Windows installed
+- Internet connectivity (for initial Git installation)
+
+**Note**: winpty is automatically included with Git for Windows. When you install Git for Windows, winpty is installed as part of the package and is immediately available in Git Bash.
+
+#### Installation Steps
+
+winpty is bundled with Git for Windows. To install or reinstall Git for Windows (which includes winpty), run the following command in an Administrator PowerShell or Command Prompt:
+
+```powershell
+choco install git -y
+```
+
+The `-y` flag automatically confirms all prompts, enabling fully non-interactive installation.
+
+After installation, close and reopen Git Bash to ensure the updated PATH is loaded.
+
+**Launching Git Bash:**
+
+- From Start Menu: Search for "Git Bash"
+- From Command Prompt: Run `"C:\Program Files\Git\bin\bash.exe"`
+- From File Explorer: Right-click in a folder and select "Git Bash Here"
+
+#### Verification
+
+In Git Bash, verify winpty is available:
+
+```bash
+which winpty
+```
+
+Expected output:
+
+```
+/usr/bin/winpty
+```
+
+Test winpty with an interactive command:
+
+```bash
+winpty python --version
+```
+
+Or start an interactive Python session:
+
+```bash
+winpty python
+```
+
+Expected behavior: Python REPL opens and accepts input. Type `exit()` or press Ctrl+D to exit.
+
+Check the winpty installation location:
+
+```bash
+ls -la /usr/bin/winpty*
+```
+
+Expected output shows multiple winpty files:
+
+```
+-rwxr-xr-x 1 user group  xxxxx  /usr/bin/winpty
+-rwxr-xr-x 1 user group  xxxxx  /usr/bin/winpty-agent
+-rwxr-xr-x 1 user group  xxxxx  /usr/bin/winpty-debugserver
+```
+
+#### Troubleshooting
+
+**Problem**: Interactive commands do not display properly or hang
+
+**Solution**: Prefix interactive Windows console programs with `winpty`:
+
+```bash
+# Interactive Python
+winpty python
+
+# Interactive Node.js
+winpty node
+
+# Interactive Docker container
+winpty docker run -it ubuntu bash
+
+# Interactive MySQL client
+winpty mysql -u root -p
+```
+
+**Problem**: Creating aliases for common interactive programs
+
+**Solution**: Add aliases to your `~/.bashrc` file:
+
+```bash
+# Add these lines to ~/.bashrc
+echo 'alias python="winpty python"' >> ~/.bashrc
+echo 'alias node="winpty node"' >> ~/.bashrc
+echo 'alias ipython="winpty ipython"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Problem**: winpty causes issues with non-interactive commands
+
+**Solution**: winpty is only needed for interactive use. For scripts and piping, run commands without winpty:
+
+```bash
+# Without winpty for non-interactive use
+python script.py
+node app.js
+echo "SELECT 1;" | mysql -u root
+
+# With winpty for interactive use
+winpty python
+winpty node
+winpty mysql -u root -p
+```
+
+**Problem**: "stdout is not a tty" error
+
+**Solution**: This can occur when winpty interferes with piping. Run without winpty for piped commands:
+
+```bash
+# This may fail
+winpty python -c "print('hello')" | grep hello
+
+# This works
+python -c "print('hello')" | grep hello
+```
+
+**Problem**: MSYS path conversion issues with winpty
+
+**Solution**: Git Bash/MSYS2 converts Unix-style paths to Windows paths automatically. To prevent this:
+
+```bash
+MSYS_NO_PATHCONV=1 winpty some-command /path/to/file
+```
+
+---
+
+## Post-Installation Configuration
+
+### Creating Shell Aliases for Common Programs
+
+If you frequently use interactive programs in Git Bash, create aliases to automatically use winpty:
+
+```bash
+# Open ~/.bashrc in an editor
+notepad ~/.bashrc
+```
+
+Add the following aliases:
+
+```bash
+# Interactive program aliases for Git Bash
+alias python='winpty python'
+alias python3='winpty python3'
+alias node='winpty node'
+alias ipython='winpty ipython'
+alias php='winpty php -a'
+alias mysql='winpty mysql'
+alias psql='winpty psql'
+alias mongo='winpty mongo'
+alias redis-cli='winpty redis-cli'
+```
+
+Reload your shell configuration:
+
+```bash
+source ~/.bashrc
+```
+
+### Conditional Aliases (Optional)
+
+For more sophisticated setups, you can create conditional aliases that only apply winpty when running interactively:
+
+```bash
+# Add to ~/.bashrc
+if [ -t 1 ]; then
+    # Only apply these aliases when running in an interactive terminal
+    alias python='winpty python'
+    alias node='winpty node'
+fi
+```
+
+---
+
+## Common Issues
+
+### Issue: "the input device is not a TTY"
+
+**Symptoms**: Error message when running Docker, Python, or Node.js interactively in Git Bash
+
+**Solution**: This is the primary use case for winpty. Prefix your command with `winpty`:
+
+```bash
+# Instead of:
+docker run -it ubuntu bash
+
+# Use:
+winpty docker run -it ubuntu bash
+```
+
+### Issue: Arrow Keys and Special Keys Not Working
+
+**Symptoms**: Arrow keys produce escape sequences like `^[[A` instead of navigating
+
+**Solution**: Use winpty to enable proper key handling:
+
+```bash
+winpty python
+winpty node
+```
+
+### Issue: Colored Output Not Displaying
+
+**Symptoms**: Programs that should show colored output display plain text or escape codes
+
+**Solution**: winpty handles ANSI escape sequences. Ensure you are using winpty:
+
+```bash
+winpty npm test
+```
+
+### Issue: Programs Hang or Freeze
+
+**Symptoms**: Interactive programs become unresponsive in Git Bash
+
+**Solutions**:
+
+1. Use winpty:
+   ```bash
+   winpty program-name
+   ```
+
+2. If using winpty already, try running without it (for non-interactive use):
+   ```bash
+   program-name --some-flag
+   ```
+
+3. Try running in Windows Command Prompt instead of Git Bash for problematic programs
+
+### Issue: winpty Not Available After Git Update
+
+**Symptoms**: winpty stops working after updating Git for Windows
+
+**Solution**: Reinstall Git for Windows to ensure all components are properly installed:
+
+```powershell
+choco uninstall git -y
+choco install git -y
+```
+
+### Issue: Incorrect Path Handling
+
+**Symptoms**: File paths are mangled or converted incorrectly when using winpty
+
+**Solution**: Disable MSYS path conversion for specific commands:
+
+```bash
+MSYS_NO_PATHCONV=1 winpty command /path/to/file
+```
+
+Or use Windows-style paths:
+
+```bash
+winpty command "C:\path\to\file"
+```
+
+---
+
+## How winpty Works
+
+Understanding how winpty works can help troubleshoot issues:
+
+1. **Problem**: MinTTY (Git Bash's terminal) uses Unix-style PTY communication, but Windows console programs expect Windows Console API calls.
+
+2. **Solution**: winpty creates a hidden Windows console window and runs the target program in it. The winpty-agent process monitors this hidden console and translates:
+   - Keyboard input from MinTTY into Windows console input events
+   - Console screen buffer changes into terminal escape sequences for MinTTY
+
+3. **Architecture**:
+   ```
+   MinTTY <-> winpty.exe <-> winpty-agent.exe <-> Hidden Console <-> Target Program
+   ```
+
+4. **Limitations**:
+   - winpty adds overhead compared to native console programs
+   - Some advanced console features may not translate perfectly
+   - Piping and redirection should be done without winpty
+
+---
+
+## References
+
+- [winpty GitHub Repository](https://github.com/rprichard/winpty)
+- [winpty Releases](https://github.com/rprichard/winpty/releases)
+- [Git for Windows](https://gitforwindows.org/)
+- [Git for Windows FAQ](https://gitforwindows.org/faq)
+- [MSYS2 winpty Package](https://packages.msys2.org/packages/winpty)
+- [Scoop winpty Package](https://bjansen.github.io/scoop-apps/extras/winpty/)
+- [MinTTY Terminal](https://mintty.github.io/)
+- [Windows Console and Terminal Ecosystem](https://docs.microsoft.com/en-us/windows/console/)