windows-compatibility

Context

Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), git -C with Windows paths (unreliable), forward-slash paths in Node.js on Windows.

Patterns

Filenames & Timestamps

• Never use colons in filenames: ISO 8601 format 2026-03-15T05:30:00Z is illegal on Windows
• Use safeTimestamp() utility: Replaces colons with hyphens → 2026-03-15T05-30-00Z
• Centralize formatting: Don't inline .toISOString().replace(/:/g, '-') — use the utility

Git Commands

• Never use git -C {path}: Unreliable with Windows paths (backslashes, spaces, drive letters)
• Always cd first: Change directory, then run git commands
• Check for changes before commit: git diff --cached --quiet (exit 0 = no changes)

Commit Messages

• Never embed newlines in -m flag: Backtick-n (\n) fails silently in PowerShell
• Use temp file + -F flag: Write message to file, commit with git commit -F $msgFile