refactor: extract platform abstraction layer into src/platform/

Create a unified platform abstraction layer that consolidates all
platform-specific code into dedicated modules under src/platform/:

- common.cppm:   compile-time constants, platform detection, naming
- process.cppm:  unified subprocess execution (auto-closes stdin on
                 POSIX — fixes macOS first-run hang where xcrun/xcode-
                 select would block waiting for user input)
- fs.cppm:       self_exe_path(), which(), RAII FileLock
- shell.cppm:    platform-aware shell argument quoting
- env.cppm:      environment variable operations
- macos.cppm:    Xcode CLT detection, xcrun SDK discovery
- linux.cppm:    LD_LIBRARY_PATH construction, runtime lib dirs
- windows.cppm:  PATH manipulation
- platform.cppm: facade that re-exports all sub-modules

Migrated consumers:
- config.cppm:         use platform::fs::self_exe_path(), which()
- xlings.cppm:         use platform::shell, process, env (all raw
                       popen/system calls removed)
- probe.cppm:          use platform::fs::which(), macos::sdk_path(),
                       linux_::build_ld_library_path_prefix()
- bmi_cache.cppm:      use platform::fs::FileLock (RAII)
- ninja_backend.cppm:  use platform::fs::self_exe_path()
- clang.cppm:          use platform::exe_suffix for tool paths
- cli.cppm:            use platform::name constant

Deleted:
- src/platform.cppm:  replaced by src/platform/common.cppm
- src/process.cppm:   absorbed by src/platform/process.cppm + shell.cppm

Net result: ~550 lines of scattered #ifdef blocks removed, all
subprocess calls now go through platform::process which auto-redirects
stdin from /dev/null on POSIX.

Author: Sunrisepeak

.agents/docs/platform-abstraction-plan.md

@@ -0,0 +1,102 @@
+# Platform Abstraction Layer — Architecture & Implementation Plan
+
+## 1. Problem Statement
+
+mcpp has ~45+ `#if defined(...)` blocks scattered across 10+ source files for platform-specific logic. This causes:
+- **stdin leakage**: subprocess calls on macOS don't close stdin → first-run hangs
+- **Code duplication**: `self_exe_path()` duplicated in `config.cppm` and `ninja_backend.cppm`
+- **Inconsistent abstractions**: `process.cppm` wraps some calls, but many files still use raw `std::system()`/`popen()`
+- **Maintenance burden**: adding platform support requires editing 10+ files
+
+## 2. Target Architecture
+
+```
+src/platform/
+├── platform.cppm          # Unified facade (re-exports all platform capabilities)
+├── common.cppm            # Cross-platform constants + compile-time detection
+├── process.cppm           # Unified process execution (auto-closes stdin on POSIX)
+├── fs.cppm                # Platform filesystem ops (exe path, file lock, which)
+├── env.cppm               # Environment variable operations
+├── shell.cppm             # Shell quoting + command building
+├── macos.cppm             # macOS: xcrun, SDK discovery, Xcode CLT detection
+├── linux.cppm             # Linux: /proc, LD_LIBRARY_PATH, patchelf
+└── windows.cppm           # Windows: vswhere, MSVC, _putenv_s, registry
+```
+
+## 3. Module Responsibilities
+
+### common.cppm — Compile-time constants & platform detection
+- Platform booleans: `is_windows`, `is_macos`, `is_linux`
+- Binary naming: `exe_suffix`, `static_lib_ext`, `shared_lib_ext`, `lib_prefix`
+- Platform name string
+- Null redirect string
+
+### process.cppm — Unified process execution (CORE FIX)
+- `capture()` — run command, capture stdout (auto `</dev/null` on POSIX)
+- `run_silent()` — run without caring about output
+- `run_streaming()` — stream stdout line-by-line via callback
+- All subprocess calls go through here → stdin leak impossible
+
+### fs.cppm — Platform filesystem operations
+- `self_exe_path()` — current executable path (Win: GetModuleFileName, macOS: _NSGetExecutablePath, Linux: /proc/self/exe)
+- `FileLock` — RAII exclusive file lock (Win: LockFileEx, POSIX: flock)
+- `which()` — find executable (Win: `where`, POSIX: `command -v`)
+
+### env.cppm — Environment variable operations
+- `set()` / `get()` — platform-aware env var manipulation
+- `build_env_prefix()` — construct env prefix for commands
+
+### shell.cppm — Shell quoting
+- `quote()` — platform-aware shell argument quoting
+- `silent_redirect` — full silent redirect string
+
+### macos.cppm — macOS-specific
+- `has_xcode_clt()` — check Xcode Command Line Tools
+- `sdk_path()` — xcrun SDK discovery
+- `runtime_lib_dirs()` — macOS library search paths
+
+### linux.cppm — Linux-specific
+- `build_ld_library_path()` — LD_LIBRARY_PATH construction
+- `runtime_lib_dirs()` — Linux library search paths
+
+### windows.cppm — Windows-specific
+- `find_visual_studio()` — VS discovery via vswhere/env/paths
+- `find_std_module_source()` — MSVC STL module source
+- `prepend_path()` — Windows PATH manipulation
+
+### platform.cppm — Unified facade
+- Re-exports all common modules
+- Conditionally exports platform-specific modules
+
+## 4. Migration Impact
+
+| Source File | Changes | Effort |
+|-------------|---------|--------|
+| `config.cppm` | Use `fs::self_exe_path()`, `fs::which()`, `process::run_silent()` | Medium |
+| `xlings.cppm` | Use `shell::quote()`, `process::run_streaming()`, `env::*` | Large |
+| `process.cppm` | DELETE — absorbed by `platform/process.cppm` + `platform/shell.cppm` | Delete |
+| `probe.cppm` | Use `fs::which()`, `macos::sdk_path()` | Medium |
+| `bmi_cache.cppm` | Use `fs::FileLock` | Small |
+| `ninja_backend.cppm` | Use `fs::self_exe_path()` | Small |
+| `flags.cppm` | Use `common` constants | Small |
+| `clang.cppm` | Use `windows::find_std_module_source()` | Small |
+| `msvc.cppm` | Discovery logic moves to `platform/windows.cppm` | Medium |
+| `cli.cppm` | Use `common::name` | Small |
+
+## 5. Implementation Phases
+
+### Phase 1: Skeleton (parallel-safe)
+Create directory + `common.cppm` (move from existing `platform.cppm`)
+
+### Phase 2: Core modules (parallelizable)
+- 2a: `process.cppm` — includes stdin fix
+- 2b: `fs.cppm` — self_exe_path + FileLock + which
+- 2c: `env.cppm` + `shell.cppm`
+- 2d: `macos.cppm` + `linux.cppm` + `windows.cppm`
+- 2e: `platform.cppm` facade
+
+### Phase 3: Consumer migration
+Migrate all files to use new platform modules, remove old `process.cppm`
+
+### Phase 4: Build config + CI verification
+Update `mcpp.toml`, verify on all platforms

src/bmi_cache.cppm

@@ -15,18 +15,11 @@
 // dep cache without trashing manifest.txt (docs/26 §5.4 V2).
 
 module;
-#if defined(_WIN32)
-#include <io.h>
-#include <windows.h>
-#else
-#include <fcntl.h>
-#include <sys/file.h>
-#include <unistd.h>
-#endif
 
 export module mcpp.bmi_cache;
 
 import std;
+import mcpp.platform;
 
 export namespace mcpp::bmi_cache {
 
@@ -188,56 +181,6 @@ stage_into(const CacheKey& key,
 }
 
 namespace {
-
-// Acquire an exclusive non-blocking lock on <dir>/.lock. Returns a handle
-// on success, or -1/INVALID_HANDLE if another mcpp is already populating.
-#if defined(_WIN32)
-// Windows: use LockFileEx on a file handle
-HANDLE try_lock_dir(const std::filesystem::path& dir) {
-    std::error_code ec;
-    std::filesystem::create_directories(dir, ec);
-    auto lockPath = dir / ".lock";
-    HANDLE h = CreateFileW(lockPath.wstring().c_str(),
-        GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE,
-        NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
-    if (h == INVALID_HANDLE_VALUE) return h;
-    OVERLAPPED ov = {};
-    if (!LockFileEx(h, LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY,
-                    0, 1, 0, &ov)) {
-        CloseHandle(h);
-        return INVALID_HANDLE_VALUE;
-    }
-    return h;
-}
-
-void release_lock(HANDLE h) {
-    if (h == INVALID_HANDLE_VALUE) return;
-    OVERLAPPED ov = {};
-    UnlockFileEx(h, 0, 1, 0, &ov);
-    CloseHandle(h);
-}
-#else
-// POSIX: use flock(2)
-int try_lock_dir(const std::filesystem::path& dir) {
-    std::error_code ec;
-    std::filesystem::create_directories(dir, ec);
-    auto lockPath = dir / ".lock";
-    int fd = ::open(lockPath.c_str(), O_CREAT | O_RDWR | O_CLOEXEC, 0644);
-    if (fd < 0) return -1;
-    if (::flock(fd, LOCK_EX | LOCK_NB) != 0) {
-        ::close(fd);
-        return -1;
-    }
-    return fd;
-}
-
-void release_lock(int fd) {
-    if (fd < 0) return;
-    ::flock(fd, LOCK_UN);
-    ::close(fd);
-}
-#endif
-
 } // namespace
 
 std::expected<void, std::string>
@@ -246,26 +189,11 @@ populate_from(const CacheKey& key,
               const DepArtifacts& arts)
 {
     auto cacheDir = key.dir();
-#if defined(_WIN32)
-    HANDLE lockHandle = try_lock_dir(cacheDir);
-    if (lockHandle == INVALID_HANDLE_VALUE) {
-        return {};
-    }
-    struct LockGuard {
-        HANDLE h;
-        ~LockGuard() { release_lock(h); }
-    } guard{ lockHandle };
-#else
-    int lockFd = try_lock_dir(cacheDir);
-    if (lockFd < 0) {
+    auto lock = mcpp::platform::fs::FileLock::try_acquire(cacheDir);
+    if (!lock) {
         // Another writer holds the lock; treat as success (they'll do it).
         return {};
     }
-    struct LockGuard {
-        int fd;
-        ~LockGuard() { release_lock(fd); }
-    } guard{ lockFd };
-#endif
 
     auto cacheBmi = key.bmiDir();
     auto cacheObj = key.objDir();

src/build/ninja_backend.cppm

@@ -15,11 +15,8 @@ module;
 #include <cstdio>
 #include <cstdlib>
 #if defined(_WIN32)
-#include <windows.h>
 #define popen  _popen
 #define pclose _pclose
-#elif defined(__APPLE__)
-#include <mach-o/dyld.h>  // _NSGetExecutablePath
 #endif
 
 export module mcpp.build.ninja;
@@ -33,6 +30,7 @@ import mcpp.dyndep;
 import mcpp.toolchain.detect;
 import mcpp.toolchain.registry;
 import mcpp.xlings;
+import mcpp.platform;
 
 export namespace mcpp::build {
 
@@ -119,27 +117,7 @@ bool dyndep_mode_enabled() {
 }
 
 std::filesystem::path mcpp_exe_path() {
-    std::error_code ec;
-#if defined(_WIN32)
-    char buf[MAX_PATH];
-    DWORD len = GetModuleFileNameA(NULL, buf, MAX_PATH);
-    if (len > 0 && len < MAX_PATH) {
-        auto p = std::filesystem::canonical(buf, ec);
-        if (!ec) return p;
-    }
-#elif defined(__APPLE__)
-    char buf[4096];
-    uint32_t size = sizeof(buf);
-    if (_NSGetExecutablePath(buf, &size) == 0) {
-        auto p = std::filesystem::canonical(buf, ec);
-        if (!ec) return p;
-    }
-#else
-    auto p = std::filesystem::read_symlink("/proc/self/exe", ec);
-    if (!ec)
-        return p;
-#endif
-    return "mcpp";  // fall back to PATH lookup
+    return mcpp::platform::fs::self_exe_path();
 }
 
 bool is_c_source(const std::filesystem::path& src) {

src/cli.cppm

@@ -36,6 +36,7 @@ import mcpp.publish.xpkg_emit;
 import mcpp.pack;
 import mcpp.config;
 import mcpp.xlings;
+import mcpp.platform;
 import mcpp.fetcher;
 import mcpp.pm.resolver;   // PR-R4: extracted from cli.cppm
 import mcpp.pm.commands;   // PR-R5: cmd_add / cmd_remove / cmd_update live here now
@@ -1016,16 +1017,7 @@ prepare_build(bool print_fingerprint,
         return &*cfg_opt;
     };
 
-    constexpr std::string_view kCurrentPlatform =
-#if defined(__linux__)
-        "linux";
-#elif defined(__APPLE__)
-        "macos";
-#elif defined(_WIN32)
-        "windows";
-#else
-        "unknown";
-#endif
+    constexpr std::string_view kCurrentPlatform = mcpp::platform::name;
 
     // M5.5: toolchain resolution priority:
     //   0. --target X / --static, looked up in [target.<triple>]

src/config.cppm

@@ -14,22 +14,15 @@
 // the directory tree exists and seeds .xlings.json if missing.
 
 module;
-#include <cstdio>
 #include <cstdlib>
-#if defined(_WIN32)
-#include <windows.h>
-#define popen  _popen
-#define pclose _pclose
-#elif defined(__APPLE__)
-#include <mach-o/dyld.h>  // _NSGetExecutablePath
-#endif
 
 export module mcpp.config;
 
 import std;
 import mcpp.libs.toml;
 import mcpp.pm.index_spec;
 import mcpp.xlings;
+import mcpp.platform;
 
 export namespace mcpp::config {
 
@@ -180,22 +173,8 @@ std::filesystem::path home_dir() {
         return std::filesystem::path(e);
 
     std::error_code ec;
-#if defined(_WIN32)
-    char _exe_buf[MAX_PATH];
-    DWORD _exe_len = GetModuleFileNameA(NULL, _exe_buf, MAX_PATH);
-    std::filesystem::path exe;
-    if (_exe_len > 0 && _exe_len < MAX_PATH)
-        exe = std::filesystem::canonical(_exe_buf, ec);
-#elif defined(__APPLE__)
-    char _exe_buf[4096];
-    uint32_t _exe_size = sizeof(_exe_buf);
-    std::filesystem::path exe;
-    if (_NSGetExecutablePath(_exe_buf, &_exe_size) == 0)
-        exe = std::filesystem::canonical(_exe_buf, ec);
-#else
-    auto exe = std::filesystem::canonical("/proc/self/exe", ec);
-#endif
-    if (!ec && exe.parent_path().filename() == "bin") {
+    auto exe = mcpp::platform::fs::self_exe_path();
+    if (exe.has_parent_path() && exe.parent_path().filename() == "bin") {
         // Dev builds emit binaries at target/<triple>/<fp>/bin/<exe>,
         // matching the bin/ shape. Any ancestor literally named
         // "target" disqualifies self-contained mode and falls through
@@ -367,14 +346,10 @@ acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet)
     }
 
     // 2. Copy from system (`which xlings`)
-#if defined(_WIN32)
-    auto sys = run_capture("where xlings.exe 2>nul");
-#else
-    auto sys = run_capture("command -v xlings 2>/dev/null");
-#endif
-    if (sys) {
-        std::string p = *sys;
-        while (!p.empty() && (p.back() == '\n' || p.back() == '\r')) p.pop_back();
+    auto xlings_name = std::string("xlings") + std::string(mcpp::platform::exe_suffix);
+    auto sysXlings = mcpp::platform::fs::which(xlings_name);
+    if (sysXlings) {
+        std::string p = sysXlings->string();
         if (!p.empty() && std::filesystem::exists(p)) {
             std::filesystem::copy_file(p, destBin,
                 std::filesystem::copy_options::overwrite_existing, ec);
@@ -453,11 +428,8 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     // <XLINGS_HOME>/bin/xlings, which satisfies xlings's own shim-
     // creation guard (`if fs::exists(homeDir/"bin"/"xlings")`),
     // making ensure_sandbox_xlings_binary() a no-op.
-#if defined(_WIN32)
-    cfg.xlingsBinary  = cfg.registryDir / "bin" / "xlings.exe";
-#else
-    cfg.xlingsBinary  = cfg.registryDir / "bin" / "xlings";
-#endif
+    cfg.xlingsBinary  = cfg.registryDir / "bin" /
+        (std::string("xlings") + std::string(mcpp::platform::exe_suffix));
     cfg.bmiCacheDir   = cfg.mcppHome / "bmi";
     cfg.metaCacheDir  = cfg.mcppHome / "cache";
     cfg.logDir        = cfg.mcppHome / "log";
@@ -552,16 +524,11 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
         auto xbin = acquire_xlings_binary(cfg.xlingsBinary, quiet);
         if (!xbin) return std::unexpected(ConfigError{xbin.error()});
     } else if (cfg.xlingsBinaryMode == "system") {
-#if defined(_WIN32)
-        auto sys = run_capture("where xlings.exe 2>nul");
-#else
-        auto sys = run_capture("command -v xlings 2>/dev/null");
-#endif
-        if (!sys || sys->empty())
+        auto sysPath = mcpp::platform::fs::which(
+            std::string("xlings") + std::string(mcpp::platform::exe_suffix));
+        if (!sysPath)
             return std::unexpected(ConfigError{"system xlings not found in PATH"});
-        std::string p = *sys;
-        while (!p.empty() && (p.back() == '\n' || p.back() == '\r')) p.pop_back();
-        cfg.xlingsBinary = p;
+        cfg.xlingsBinary = *sysPath;
     } else {
         cfg.xlingsBinary = cfg.xlingsBinaryMode;
         if (!std::filesystem::exists(cfg.xlingsBinary))