Porting a macOS-First App to Windows: Every Assumption You Didn't Know You Made

Building on macOS first is a completely reasonable default for a lot of teams. The cost shows up later: a long tail of small, platform-specific assumptions baked into the codebase that nobody consciously decided to make, and that only surface once you actually try to run the app somewhere else. A real cross-platform porting effort touched, among other things: native terminal support on Windows via node-pty instead of requiring WSL, guards around macOS-only APIs like clipboard access via pbcopy and iMessage integration so they don't get invoked (and fail opaquely) on non-Darwin platforms, a WMIC-based branch for Windows-specific system queries, and an osascript guard for AppleScript calls that have no Windows equivalent. Notably, this wasn't a single cleanup pass, it took a distinct second batch of audit fixes to catch what the first pass missed. That two-pass structure is worth planning for deliberately rather than discovering by accident. The first audit pass usually catches the obvious platform-specific calls, clipboard, notifications, native dialogs. The second pass catches the ones that only show up once you're running real workflows on the target platform, not just reading the code. Building an explicit capability table, which OS-specific APIs each integration point depends on, and which platforms each one supports, turns this from permanent bug-report whack-a-mole into a systematic, closeable audit.