Just a whole lot of crap
This commit is contained in:
443
docs/windows-troubleshooting.md
Normal file
443
docs/windows-troubleshooting.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# Windows Troubleshooting Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide addresses common issues when running the Shopify Price Updater TUI on Windows systems and provides solutions for optimal performance.
|
||||
|
||||
## Terminal Compatibility
|
||||
|
||||
### Recommended Terminals
|
||||
|
||||
#### Windows Terminal (Best Experience)
|
||||
|
||||
- **Download**: Microsoft Store or GitHub releases
|
||||
- **Features**: Full Unicode support, true color, modern key handling
|
||||
- **Configuration**: No additional setup required
|
||||
|
||||
#### PowerShell 7+ (Good Experience)
|
||||
|
||||
- **Download**: GitHub releases or Windows Package Manager
|
||||
- **Features**: Good Unicode support, color support
|
||||
- **Setup**:
|
||||
```powershell
|
||||
winget install Microsoft.PowerShell
|
||||
```
|
||||
|
||||
#### Command Prompt (Basic Experience)
|
||||
|
||||
- **Features**: Limited color support, basic functionality
|
||||
- **Limitations**: No Unicode characters, limited colors
|
||||
|
||||
### Terminal Setup
|
||||
|
||||
#### Enable UTF-8 Support
|
||||
|
||||
```cmd
|
||||
chcp 65001
|
||||
```
|
||||
|
||||
#### PowerShell Profile Setup
|
||||
|
||||
Add to your PowerShell profile (`$PROFILE`):
|
||||
|
||||
```powershell
|
||||
# Enable UTF-8 encoding
|
||||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||||
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
|
||||
|
||||
# Set console to support ANSI escape sequences
|
||||
$Host.UI.RawUI.WindowTitle = "PowerShell"
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: Unicode Characters Not Displaying
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Boxes, question marks, or missing characters in the TUI
|
||||
- Progress bars showing incorrect characters
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Set Console Code Page:**
|
||||
|
||||
```cmd
|
||||
chcp 65001
|
||||
npm run tui
|
||||
```
|
||||
|
||||
2. **Windows Terminal Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"defaults": {
|
||||
"fontFace": "Cascadia Code",
|
||||
"fontSize": 12
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **PowerShell Configuration:**
|
||||
```powershell
|
||||
$OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding
|
||||
```
|
||||
|
||||
### Issue: Colors Not Working
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- No colors in the interface
|
||||
- All text appears in default terminal color
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Enable ANSI Support (Windows 10+):**
|
||||
|
||||
```cmd
|
||||
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
|
||||
```
|
||||
|
||||
2. **Use Windows Terminal:**
|
||||
|
||||
- Download from Microsoft Store
|
||||
- Automatically supports modern color features
|
||||
|
||||
3. **PowerShell Color Support:**
|
||||
```powershell
|
||||
# Check if colors are supported
|
||||
$Host.UI.SupportsVirtualTerminal
|
||||
```
|
||||
|
||||
### Issue: Keyboard Input Problems
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Arrow keys not working
|
||||
- Special keys producing unexpected characters
|
||||
- Navigation not responding
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Windows Terminal (Recommended):**
|
||||
|
||||
- Use Windows Terminal for best keyboard support
|
||||
- Supports all modern key sequences
|
||||
|
||||
2. **PowerShell ISE Alternative:**
|
||||
|
||||
- Don't use PowerShell ISE - use regular PowerShell or Windows Terminal
|
||||
|
||||
3. **Command Prompt Limitations:**
|
||||
- Limited key support - consider upgrading to Windows Terminal
|
||||
|
||||
### Issue: Performance Problems
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Slow rendering
|
||||
- Flickering interface
|
||||
- High CPU usage
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Windows Terminal Optimization:**
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"defaults": {
|
||||
"useAcrylic": false,
|
||||
"acrylicOpacity": 1.0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Disable Windows Defender Real-time Scanning:**
|
||||
|
||||
- Add Node.js to exclusions
|
||||
- Add project directory to exclusions
|
||||
|
||||
3. **Close Unnecessary Applications:**
|
||||
- Free up system resources
|
||||
- Close other terminal windows
|
||||
|
||||
### Issue: Font and Display Problems
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Misaligned text
|
||||
- Incorrect character spacing
|
||||
- Overlapping text
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use Monospace Fonts:**
|
||||
|
||||
- Cascadia Code (recommended)
|
||||
- Consolas
|
||||
- Courier New
|
||||
|
||||
2. **Windows Terminal Font Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"defaults": {
|
||||
"fontFace": "Cascadia Code",
|
||||
"fontSize": 12,
|
||||
"fontWeight": "normal"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Adjust Terminal Size:**
|
||||
- Ensure minimum 80x24 characters
|
||||
- Avoid very small terminal windows
|
||||
|
||||
## Windows-Specific Features
|
||||
|
||||
### Windows Terminal Integration
|
||||
|
||||
The TUI includes specific optimizations for Windows Terminal:
|
||||
|
||||
- **True Color Support**: Full 24-bit color palette
|
||||
- **Unicode Rendering**: Enhanced character support
|
||||
- **Mouse Support**: Click interactions where appropriate
|
||||
- **Resize Handling**: Automatic layout adjustment
|
||||
|
||||
### PowerShell Integration
|
||||
|
||||
- **Profile Integration**: Works with PowerShell profiles
|
||||
- **Module Loading**: Compatible with PowerShell modules
|
||||
- **Error Handling**: Windows-specific error messages
|
||||
|
||||
### Command Prompt Compatibility
|
||||
|
||||
- **Graceful Degradation**: Reduced features for compatibility
|
||||
- **Basic Colors**: Limited color palette
|
||||
- **Essential Functions**: Core functionality maintained
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Windows-Specific Settings
|
||||
|
||||
```env
|
||||
# Windows Terminal optimization
|
||||
FORCE_COLOR=1
|
||||
NO_COLOR=0
|
||||
|
||||
# Console encoding
|
||||
PYTHONIOENCODING=utf-8
|
||||
```
|
||||
|
||||
### PowerShell Environment
|
||||
|
||||
```powershell
|
||||
# Set in PowerShell profile
|
||||
$env:FORCE_COLOR = "1"
|
||||
$env:NO_COLOR = "0"
|
||||
```
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Node.js Version Problems
|
||||
|
||||
**Issue:** TUI fails to start with Node.js version errors
|
||||
|
||||
**Solution:**
|
||||
|
||||
```cmd
|
||||
# Check Node.js version
|
||||
node --version
|
||||
|
||||
# Should be 16.0.0 or higher
|
||||
# Update if necessary from nodejs.org
|
||||
```
|
||||
|
||||
### NPM Permission Issues
|
||||
|
||||
**Issue:** Permission denied errors during npm install
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Run as Administrator:**
|
||||
|
||||
```cmd
|
||||
# Right-click Command Prompt/PowerShell
|
||||
# Select "Run as administrator"
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Configure NPM Prefix:**
|
||||
```cmd
|
||||
npm config set prefix %APPDATA%\npm
|
||||
```
|
||||
|
||||
### Dependency Installation Problems
|
||||
|
||||
**Issue:** Native module compilation failures
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install Build Tools:**
|
||||
|
||||
```cmd
|
||||
npm install -g windows-build-tools
|
||||
```
|
||||
|
||||
2. **Visual Studio Build Tools:**
|
||||
```cmd
|
||||
# Download from Microsoft
|
||||
# Install C++ build tools
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Windows Terminal Settings
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"defaults": {
|
||||
"useAcrylic": false,
|
||||
"scrollbarState": "hidden",
|
||||
"snapOnInput": true,
|
||||
"historySize": 9001
|
||||
}
|
||||
},
|
||||
"rendering": {
|
||||
"forceFullRepaint": false,
|
||||
"software": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### System Optimization
|
||||
|
||||
1. **Disable Visual Effects:**
|
||||
|
||||
- Control Panel → System → Advanced → Performance → Adjust for best performance
|
||||
|
||||
2. **Power Settings:**
|
||||
|
||||
- Set to "High Performance" mode
|
||||
|
||||
3. **Background Apps:**
|
||||
- Disable unnecessary background applications
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Debug Mode
|
||||
|
||||
```cmd
|
||||
set DEBUG=shopify-price-updater:*
|
||||
npm run tui
|
||||
```
|
||||
|
||||
### Log Collection
|
||||
|
||||
```cmd
|
||||
# Redirect output to file
|
||||
npm run tui > debug.log 2>&1
|
||||
```
|
||||
|
||||
### System Information
|
||||
|
||||
```cmd
|
||||
# Collect system info
|
||||
systeminfo > system-info.txt
|
||||
node --version >> system-info.txt
|
||||
npm --version >> system-info.txt
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Registry Settings
|
||||
|
||||
```cmd
|
||||
# Enable ANSI escape sequences (Windows 10+)
|
||||
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
|
||||
|
||||
# Disable QuickEdit mode (prevents accidental pausing)
|
||||
reg add HKCU\Console /v QuickEdit /t REG_DWORD /d 0
|
||||
```
|
||||
|
||||
### Windows Terminal Custom Actions
|
||||
|
||||
```json
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"command": {
|
||||
"action": "sendInput",
|
||||
"input": "npm run tui\r"
|
||||
},
|
||||
"keys": "ctrl+shift+t"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Information to Collect
|
||||
|
||||
When reporting Windows-specific issues, include:
|
||||
|
||||
1. **Windows Version:**
|
||||
|
||||
```cmd
|
||||
winver
|
||||
```
|
||||
|
||||
2. **Terminal Information:**
|
||||
|
||||
```cmd
|
||||
echo $env:TERM
|
||||
```
|
||||
|
||||
3. **Node.js Version:**
|
||||
|
||||
```cmd
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
4. **Error Messages:**
|
||||
- Full error output
|
||||
- Stack traces if available
|
||||
|
||||
### Support Resources
|
||||
|
||||
- **Windows Terminal Issues**: GitHub repository
|
||||
- **PowerShell Issues**: PowerShell GitHub repository
|
||||
- **Node.js Issues**: Node.js support channels
|
||||
- **Application Issues**: Project repository
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Environment
|
||||
|
||||
1. **Use Windows Terminal** for the best experience
|
||||
2. **Keep Node.js Updated** to the latest LTS version
|
||||
3. **Use PowerShell 7+** instead of Windows PowerShell 5.1
|
||||
4. **Configure UTF-8 Encoding** in your terminal profile
|
||||
|
||||
### Production Usage
|
||||
|
||||
1. **Test in Target Environment** before deployment
|
||||
2. **Document Terminal Requirements** for end users
|
||||
3. **Provide Fallback Instructions** for older terminals
|
||||
4. **Monitor Performance** on target systems
|
||||
|
||||
### Maintenance
|
||||
|
||||
1. **Regular Updates** of terminal applications
|
||||
2. **Monitor Windows Updates** that might affect terminal behavior
|
||||
3. **Keep Dependencies Updated** for security and compatibility
|
||||
4. **Test After System Updates** to ensure continued functionality
|
||||
Reference in New Issue
Block a user