444 lines
8.4 KiB
Markdown
444 lines
8.4 KiB
Markdown
# 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
|