powershell-reliable

# PowerShell Reliable Execution

Execute commands reliably on Windows PowerShell. Avoid common pitfalls like `&&` chaining, parameter swallowing, and session interruptions.

## Problem Statement

Windows PowerShell differs from bash in critical ways:

| Issue | Bash | PowerShell | Solution |
|-------|------|------------|----------|
| Command chaining | `cmd1 && cmd2` | `cmd1 -ErrorAction Stop; if ($?) { cmd2 }` | Use semicolons + error handling |
| Parameter parsing | `-arg value` | `-Argument value` (case-insensitive) | Use full parameter names |
| Path separators | `/` | `\` (or `/` in some cmdlets) | Use `Join-Path` |
| Output redirection | `>` `>>` | `>` `>>` (encoding issues) | Use `Out-File -Encoding UTF8` |
| Environment vars | `$VAR` | `$env:VAR` | Use `$env:` prefix |

## Core Patterns

### 1. Safe Command Chaining

**Wrong**:
```powershell
mkdir test && cd test && echo done
```

**Right**:
```powershell
$ErrorActionPreference = 'Stop'
try {
    New-Item -ItemType Directory -Path test -Force
    Set-Location test
    Write-Host 'done'
} catch {
    Write-Error "Failed: $_"
    exit 1
}
```

### 2. Parameter Safety

**Wrong**:
```powershell
git commit -m "message"
```

**Right**:
```powershell
git commit -Message "message"
# Or use splatting:
$params = @{ Message = "message" }
git commit @params
```

### 3. Path Handling

**Wrong**:
```powershell
$path = "C:/Users/name/file.txt"
```

**Right**:
```powershell
$path = Join-Path $env:USERPROFILE "file.txt"
# Or use literal paths:
$path = 'C:\Users\name\file.txt'
```

### 4. Output Encoding

**Wrong**:
```powershell
echo "text" > file.txt
```

**Right**:
```powershell
"text" | Out-File -FilePath file.txt -Encoding UTF8
```

### 5. Session Continuity

For long-running commands:

```powershell
# Start background job
$job = Start-Job -ScriptBlock {
    param($arg)
    # Long operation
} -ArgumentList $arg

# Wait with timeout
Wait-Job $job -Timeout 300

# Get results
if ($job.State -eq 'Completed') {
    Receive-Jo...