Windows Terminal & PowerShell Patterns

1. Script-Based Execution (Recommended)

Instead of direct terminal commands, create PowerShell scripts in scripts/:

# scripts/run-worker.ps1
<#
.SYNOPSIS
    Starts the Python worker for card processing
.DESCRIPTION
    Activates virtual environment and starts the worker process
#>

# Navigate to project root
$ProjectRoot = Split-Path -Parent $PSScriptRoot
Set-Location $ProjectRoot

# Activate virtual environment if exists
if (Test-Path ".venv\Scripts\Activate.ps1") {
    & .venv\Scripts\Activate.ps1
}

# Start worker
python worker/worker.py

2. Always Specify PowerShell Syntax

In your Cursor rules or when prompting:

# Add to .cursorrules or prompt
"I'm on Windows. Use PowerShell syntax:
- Use ; to chain commands, not &&
- Use $env:VAR not $VAR
- Use \ for paths, not /
- Wrap complex commands in .ps1 scripts"

3. Common Command Translations

scripts/
├── setup/
│   ├── install-dependencies.ps1    # npm install + pip install
│   ├── configure-environment.ps1    # Set up .env files
│   └── init-database.ps1           # Run migrations
├── dev/
│   ├── start-frontend.ps1          # npm run dev
│   ├── start-worker.ps1            # python worker/worker.py
│   └── start-all.ps1               # Starts everything
├── test/
│   ├── run-frontend-tests.ps1     # Jest/Playwright
│   ├── run-python-tests.ps1       # PyTest
│   └── run-all-tests.ps1          # Full test suite
└── README.md                       # Script documentation

The Python worker requires special handling on Windows:

Virtual Environment Activation

# Current (complex) way:
.venv\Scripts\Activate.ps1; cd worker; python worker.py

# Better: Use a script
./scripts/dev/start-worker.ps1

Path Issues

Always use raw strings or escape backslashes in Python:

# Bad
path = "C:\Users\user\project"  # Double escaping issues

# Good
path = r"C:\Users\user\project"  # Raw string
path = Path("C:/Users/user/project")  # Forward slashes work

Cursor Hangs on "Generating..."

• Type continue or ? to nudge it
• Check if it's stuck on Unix commands
• Create new session if context is corrupted

Commands Fail Silently

• Check terminal output for && errors
• Verify PowerShell is the active shell
• Use $ErrorActionPreference = "Stop" in scripts

Database Connection Issues

# Windows often needs explicit UTF-8 encoding
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONUTF8 = "1"