feat: add native Windows PowerShell support

[szymdzum]

Problem

Currently, bdg only works on Windows via WSL (Windows Subsystem for Linux). Native PowerShell and Git Bash are not supported due to Unix-specific dependencies.

From README.md:

• ✅ Windows via WSL (Windows Subsystem for Linux)
• ❌ PowerShell and Git Bash on Windows (not yet supported)

The CLI uses Unix domain sockets for inter-process communication. Windows users should run bdg inside WSL for full compatibility.

This limits adoption on Windows, where many developers use PowerShell or Git Bash as their primary shell.

Root Causes

After investigating the codebase, here are the blockers for Windows support:

1. Unix Domain Sockets (Primary Blocker)

Current implementation: src/daemon/server/SocketServer.ts, src/session/paths.ts

• Uses Unix domain sockets (daemon.sock) for IPC between CLI and daemon
• Unix sockets work on macOS/Linux but have limited support on Windows
• Node.js supports Unix sockets on Windows 10+ via named pipes, but path handling differs

Files affected:

• src/daemon/server/SocketServer.ts - Socket server implementation
• src/ipc/client.ts - IPC client connection
• src/session/paths.ts - Socket path generation (daemon.sock)

Windows alternative:

• Named pipes: \\.\pipe\bdg-daemon instead of ~/.bdg/daemon.sock
• TCP sockets: localhost:random_port with port file

2. Process Management (Partial Support)

Current implementation: src/session/process.ts

• Already has Windows support via taskkill for Chrome process killing
• Uses platform detection: process.platform === 'win32'
• killChromeProcess() handles Windows correctly with taskkill /pid <pid> /T /F

✅ Status: This is already cross-platform!

3. Shell Scripts (Tests Only)

Current implementation: All tests are Bash scripts (.sh)

• tests/run-all-tests.sh
• tests/integration/*.test.sh
• tests/error-scenarios/*.sh

Impact: Tests won't run natively on Windows, but this doesn't block user functionality.

Solutions:

• Add PowerShell equivalents (.ps1)
• Or migrate to cross-platform test runner (e.g., vitest, bats-core)

4. Chrome Launcher (Already Cross-Platform)

Current implementation: src/connection/launcher.ts

• Uses chrome-launcher package which supports Windows
• Comment on line 113: "Supports macOS, Linux, and Windows"

✅ Status: Already supports Windows!

Proposed Solution

Phase 1: Add Named Pipe Support (Critical)

Goal: Make IPC work on Windows using named pipes as a fallback.

Implementation:

1. Detect platform and use appropriate IPC mechanism:

   // src/session/paths.ts
   export function getDaemonSocketPath(): string {
     if (process.platform === 'win32') {
       return '\\\\.\\pipe\\bdg-daemon';  // Named pipe
     }
     return path.join(getSessionDir(), 'daemon.sock');  // Unix socket
   }

2. Update SocketServer to handle both:

   // src/daemon/server/SocketServer.ts
   async start(socketPath: string, handler: ConnectionHandler): Promise<void> {
     // On Windows, named pipes don't need unlinking
     if (process.platform !== 'win32') {
       this.cleanupStaleSocket();
     }
     // ... rest of implementation
   }

3. Test on Windows 10/11 with PowerShell

Files to modify:

• src/session/paths.ts - Platform-specific socket paths
• src/daemon/server/SocketServer.ts - Skip socket cleanup on Windows
• src/ipc/client.ts - Handle named pipe connections

Phase 2: Add PowerShell Test Scripts (Optional)

Goal: Enable test suite on Windows.

Options:

1. Add .ps1 equivalents for all .sh scripts
2. Migrate to cross-platform test framework (vitest or bats-core)
3. Use GitHub Actions Windows runners for CI validation

Phase 3: Documentation Updates

Files to update:

• README.md - Update platform support section
• docs/CLI_REFERENCE.md - Add Windows-specific notes
• .claude/skills/bdg/TROUBLESHOOTING.md - Add Windows troubleshooting

Benefits

• ✅ Broader Windows developer adoption
• ✅ Native PowerShell support (no WSL required)
• ✅ Git Bash compatibility
• ✅ Aligns with existing cross-platform Chrome/process support
• ✅ Unlocks Windows CI/CD environments

Trade-offs

Pros:

• Minimal code changes (mostly path handling)
• Named pipes are well-supported on Windows 10+
• Already have Windows process management

Cons:

• Additional testing matrix (macOS/Linux/Windows)
• Named pipe behavior differs slightly from Unix sockets
• Test scripts need PowerShell equivalents or migration

Testing Strategy

1. Local testing on Windows 10/11:

   • PowerShell 7+
   • Git Bash
   • WSL (ensure no regression)

2. CI/CD:

   • Add Windows runner to GitHub Actions
   • Run integration tests on all platforms

3. Edge cases:

   • Named pipe path limits on Windows
   • Daemon recovery on Windows
   • Chrome profile directories with Windows paths

References

• Node.js named pipes: https://nodejs.org/api/net.html#ipc-support
• Windows named pipe format: \\.\pipe\<name>
• Existing Windows support: src/session/process.ts (killChromeProcess)
• Current socket implementation: src/daemon/server/SocketServer.ts

Related Issues

• Roadmap mentions "Binaries built for macOS, Linux, Windows" (docs/roadmap/04_COMMUNITY_PREVIEW.md:300)