PriceUpdaterAppv2/docs/windows-troubleshooting.md

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:

  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

chcp 65001

PowerShell Profile Setup

Add to your PowerShell profile ($PROFILE):

# 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:

   chcp 65001
   npm run tui
   

2. Windows Terminal Configuration:

   {
   	"profiles": {
   		"defaults": {
   			"fontFace": "Cascadia Code",
   			"fontSize": 12
   		}
   	}
   }
   

3. PowerShell Configuration:

   $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+):

   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:

   # 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:

   {
   	"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:

   {
   	"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

# Windows Terminal optimization
FORCE_COLOR=1
NO_COLOR=0

# Console encoding
PYTHONIOENCODING=utf-8

PowerShell Environment

# 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:

# 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:

   # Right-click Command Prompt/PowerShell
   # Select "Run as administrator"
   npm install
   

2. Configure NPM Prefix:

   npm config set prefix %APPDATA%\npm
   

Dependency Installation Problems

Issue: Native module compilation failures

Solutions:

1. Install Build Tools:

   npm install -g windows-build-tools
   

2. Visual Studio Build Tools:

   # Download from Microsoft
   # Install C++ build tools
   

Performance Optimization

Windows Terminal Settings

{
	"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

set DEBUG=shopify-price-updater:*
npm run tui

Log Collection

# Redirect output to file
npm run tui > debug.log 2>&1

System Information

# Collect system info
systeminfo > system-info.txt
node --version >> system-info.txt
npm --version >> system-info.txt

Advanced Configuration

Registry Settings

# 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

{
	"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:

   winver
   

2. Terminal Information:

   echo $env:TERM
   

3. Node.js Version:

   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