feat: Windows support — LLVM/Clang + MSVC STL + full CI pipeline

.agents/docs/2026-05-17-windows-llvm-support-design.md

@@ -0,0 +1,49 @@
+# Windows LLVM/Clang 支持设计方案
+
+Date: 2026-05-17
+
+## 目标
+
+mcpp 在 Windows x86_64 上通过 xmake bootstrap 达到可用水平，产出 mcpp.exe 作为后续自举依赖。
+
+## 平台特征
+
+### Windows LLVM 包（xlings-res 20.1.7）
+
+```
+bin/clang.exe, clang++.exe, clang-cl.exe, lld-link.exe
+bin/llvm-ar.exe, llvm-lib.exe, llvm-rc.exe
+lib/clang/20/lib/windows/clang_rt.*.lib
+没有 libc++（没有 include/c++/v1，没有 std.cppm）
+没有 clang-scan-deps.exe
+```
+
+Windows LLVM 包不含 libc++。Windows 上 clang 搭配 MSVC STL。
+
+### Bootstrap 策略
+
+用 xmake + MSVC（和 xlings 自身做法一致）：
+- GitHub Actions windows-latest 预装 Visual Studio
+- xmake 对 MSVC C++23 modules 支持成熟
+- 不需要额外安装 LLVM（MSVC 即可）
+
+## 代码适配清单
+
+### 必须修改
+
+| 文件 | 问题 | 方案 |
+|------|------|------|
+| ninja_backend.cppm | POSIX shell 命令 | #if _WIN32 cmd.exe 语法 |
+| ninja_backend.cppm | mcpp_exe_path() 缺 Windows | GetModuleFileNameA() |
+| config.cppm | MCPP_HOME 路径发现缺 Windows | 同上 |
+| probe.cppm | command -v Unix only | where.exe |
+| probe.cppm | LD_LIBRARY_PATH | Windows 用 PATH |
+| flags.cppm | 链接 flags 缺 Windows 分支 | 无 sysroot/rpath |
+| xlings.cppm | popen | _popen |
+
+## 执行顺序
+
+1. 创建 ci-windows.yml 用 xmake 构建，看编译错误
+2. 根据 CI 错误逐步修代码
+3. 产出 mcpp.exe bootstrap binary
+4. 上传到 xlings-res

.agents/docs/2026-05-19-pack-windows-design.md

@@ -0,0 +1,97 @@
+# Windows Pack Design
+
+**Date:** 2026-05-19
+**Status:** Planned (stub guard in place, implementation not yet started)
+
+## Current state
+
+`mcpp pack` is fully functional on Linux and macOS. On Windows it exits early
+with a clear error message directing users to the CI workflow:
+
+```
+error: `mcpp pack` is not yet supported on Windows.
+       Use the CI workflow (ci-windows.yml) to produce Windows zip packages.
+       Windows PE packaging (DLL collection + zip) is planned.
+```
+
+The guard lives at the top of `mcpp::pack::run()` in `src/pack/pack.cppm`.
+
+## Why the current implementation cannot run on Windows
+
+The POSIX implementation relies on three Linux/macOS-only mechanisms:
+
+| Mechanism | POSIX usage | Windows equivalent |
+|---|---|---|
+| `LD_TRACE_LOADED_OBJECTS=1` | Tells the ELF dynamic linker to print deps without executing `main()` | No direct equivalent. Would need `dumpbin /dependents` (MSVC) or `ldd` emulation via `LoadLibraryEx` |
+| `patchelf` | Rewrites `RUNPATH` / `PT_INTERP` ELF headers in-place | Not applicable to PE/COFF. DLL search order is controlled by the OS loader and manifest, not embedded paths |
+| `tar -czf` | GNU tar — not universally present on Windows before Win11 22H2 | `Compress-Archive` (PowerShell), `7z`, or Win32 `CreateFile`/`MiniZip` |
+
+## Planned Windows pack implementation
+
+### Goal
+
+Produce a self-contained `.zip` archive (not `.tar.gz`) that users can
+extract and run with no additional setup:
+
+```
+<name>-<version>-x86_64-pc-windows-msvc.zip
+└── <name>-<version>-x86_64-pc-windows-msvc/
+    ├── <name>.exe
+    ├── *.dll         (bundled DLLs, if any)
+    └── README.md / LICENSE (if present)
+```
+
+### DLL discovery
+
+Replace `ldd_parse()` with a Win32 equivalent:
+
+1. **Primary: `dumpbin /dependents <binary>`** — available when MSVC tools are
+   on `PATH`. Produces a list of DLL names; resolve each against `PATH` /
+   `%SystemRoot%\System32` / side-by-side assemblies.
+
+2. **Fallback: `PE header walk`** — open the PE file, walk the Import Directory,
+   extract DLL names.  Can be implemented with `<windows.h>` + `ImageNtHeader`.
+
+3. **Skip-list**: mirror the manylinux skip-list concept for Windows:
+   `kernel32.dll`, `user32.dll`, `ntdll.dll`, `vcruntime*.dll` (Redist),
+   `api-ms-win-*.dll` (API sets), `ucrtbase.dll`.
+
+### Archive creation
+
+Use `std::filesystem` to copy files into a staging directory, then produce
+the zip with one of:
+
+- **PowerShell** `Compress-Archive` — available on all modern Windows.
+  Invoke via `run_capture("powershell -Command \"Compress-Archive ..."`)`.
+  Slow for large trees; fine for typical release packages.
+- **libzip / minizip** — statically linkable; avoid the PowerShell dependency.
+  Preferred long-term.
+
+### Format
+
+- Output file: `.zip` (not `.tar.gz`) on Windows.
+- `pack::Format` enum needs a new `Zip` variant (or auto-select by platform).
+- `make_plan()` should derive the output extension from the target platform.
+
+### Entry point
+
+No shell wrapper needed on Windows — users double-click `<name>.exe` or run
+it from `cmd.exe` / PowerShell directly.  If DLLs are bundled, they should be
+placed in the **same directory** as the executable (the Win32 loader checks
+`%EXE_DIR%` first, before `%PATH%`).
+
+### Implementation checklist (for the future PR)
+
+- [ ] Add `Format::Zip` (or `Format::ZipAuto`) to `pack::Format`
+- [ ] Implement `dumpbin_parse()` (or PE header walk fallback) in `pack.cppm`
+      under `#if defined(_WIN32)`
+- [ ] Implement `make_zip()` (PowerShell or libzip) in `pack.cppm`
+- [ ] Remove the `#if defined(_WIN32)` early-return guard from `pack::run()`
+      once the above are ready
+- [ ] Add a Windows-specific integration test to `ci-windows.yml`
+
+### CI workflow (current workaround)
+
+Until this is implemented, `ci-windows.yml` zips the raw build output with
+PowerShell `Compress-Archive`. This is good enough for CI artifacts but does
+not collect/bundle DLLs or apply the staging-directory layout.

.agents/docs/2026-05-19-windows-e2e-parity-plan.md

@@ -0,0 +1,43 @@
+# Windows E2E 与 macOS 对齐方案
+
+> 目标：Windows E2E 从 20/49 提升到 ~32/49，与 macOS 33/49 对齐。
+
+## 根因分析
+
+| 类别 | 测试数 | 问题 | 修复方式 |
+|------|--------|------|----------|
+| mcpp run/test 单引号 | 1 (02) | `cli.cppm` 用 POSIX 单引号执行 binary | `_WIN32` 改双引号 |
+| clang-scan-deps 查找 | 1 (16) | `cli.cppm` 硬编码无 .exe | 调用已有 `find_scan_deps()` |
+| symlink 依赖 | 4 (10,24,27,32) | `_inherit_toolchain.sh` 用 `ln -sf` | 加 `cp -r` fallback |
+| bash-specific 语法 | 1 (19) | `compgen -G` 不在 Git Bash | 改用 `find` |
+| unix-shell 误标 | 1 (38_mirror) | 实际只需 symlink fallback | 改标签 |
+| import-std-libcxx 硬编码路径 | 4 (37,38,40,41) | 测试用 Linux 路径 | 加 Windows 路径 |
+
+## 修复计划
+
+### Fix 1: cli.cppm 单引号 → 双引号 (解锁 02)
+- `src/cli.cppm:2611` — `mcpp run` 执行 binary 用 `'{}'` → Windows 改 `"{}"`
+- `src/cli.cppm:2522` — fast-path ninja 同上
+- `src/cli.cppm:3159` — test PATH prefix 是 POSIX 语法，Windows 跳过
+
+### Fix 2: clang-scan-deps 查找 (解锁 16)
+- `src/cli.cppm:2162-2167` — 直接查找 `clang-scan-deps`，不走 `find_scan_deps()`
+- 改为调用 `mcpp::toolchain::clang::find_scan_deps(*tc)` 已正确处理 .exe
+
+### Fix 3: _inherit_toolchain.sh cp fallback (解锁 10,24,27,32)
+- 当 `ln -sf` 失败时用 `cp -r` 替代
+- 自动检测 symlink 可用性
+
+### Fix 4: 19_bmi_cache_reuse.sh bash 兼容 (解锁 19)
+- `compgen -G` → `find ... | grep -q .`
+
+### Fix 5: LLVM 测试 Windows 路径 (解锁 37,38,40,41)
+- 参照 36_llvm_toolchain.sh 的模式加 Windows 路径和 .exe 处理
+
+### Fix 6: 标签修正
+- `38_self_config_mirror.sh` 改标签
+- `run_all.sh` 移除已修复测试的标签限制
+
+## 预期结果
+
+修复后：**~32 passed, 0 failed, ~17 skipped** (与 macOS 33 passed 对齐)

.agents/docs/2026-05-19-windows-maturity-v2-plan.md

@@ -0,0 +1,40 @@
+# Windows 成熟度提升 V2 方案
+
+> 基于 GPT-5.5 评审反馈，将 Windows 从 22/48 提升到 30+/48。
+
+## 任务清单
+
+### T1: 修复 fresh-sandbox 能力 + git clone 单引号
+**目标：解锁 02, 24, 27_self, 32（+4 tests）**
+
+- `cli.cppm:1963-1970` — git clone 用 `'{}'` 单引号，Windows cmd.exe 不支持
+- `run_all.sh` — Windows 添加 `fresh-sandbox` 能力
+- `27_self_contained_home.sh` — 误标 `elf`，实际逻辑是 Windows 可移植的
+
+### T2: process.cppm 实际接入
+**目标：消除散落的 popen/system 拼接**
+
+优先替换 5 个高风险 call site：
+- `probe.cppm:90` — compiler probing
+- `pm/publisher.cppm:211,239` — sha256sum, git archive
+- `toolchain/stdmod.cppm:64` — std module compilation
+- `build/ninja_backend.cppm:98` — ninja invocation
+
+### T3: provider.cppm 接入 flags/ninja
+**目标：消除散落的 is_clang/is_gcc/isMusl 检查**
+
+- `flags.cppm` — 用 `capabilities_for(tc)` 决定 compile/link flags
+- `ninja_backend.cppm:155` — scanner 策略用 provider
+- `stdmod.cppm:102,122` — BMI 路径用 provider
+
+### T4: 更新过时文档
+**目标：文档与代码同步**
+
+- 更新 `.agents/docs/2026-05-19-windows-platform-maturity-plan.md`
+- 48 tests（非 49），P1/P2/P3/P5 已完成基础设施
+
+### T5: E2E 标签修正
+**目标：最大化 Windows 可运行测试**
+
+- `27_self_contained_home.sh` — `elf` → 空（逻辑是 Windows 可移植的）
+- `10_env_command.sh` — 验证是否仍需 symlink

.agents/docs/2026-05-19-windows-platform-maturity-plan.md

@@ -0,0 +1,165 @@
+# Windows 平台成熟度提升方案
+
+> 基于 PR #52 code review 反馈，针对 Windows 支持从"可自举"到"生产就绪"的优化路径。
+
+## 当前状态
+
+| 能力 | Linux | macOS | Windows | 差距 |
+|------|-------|-------|---------|------|
+| self-host | ✅ | ✅ | ✅ | — |
+| `mcpp test` (unit) | ✅ | ✅ | ❌ | 缺 clang-scan-deps |
+| E2E 覆盖 | 46/46 | 33/46 | 22/48 | 26 项 skip |
+| `mcpp pack` | ✅ (musl static) | ✅ (手动) | ❌ (CI 手写 zip) | pack 不支持 PE |
+| release workflow | ✅ | ✅ | ✅ | build-windows job 已加 |
+| MSVC 工具链 | N/A | N/A | 模型预留 | detect 不支持 |
+| 默认工具链回退 | gcc@15.1.0-musl | llvm@20.1.7 | llvm@20.1.7 | ✅ 已修 |
+
+## 优化方案（按优先级）
+
+### P0: 补齐 release workflow + 减少 E2E skip — DONE
+
+**目标：** Windows 二进制进入正式 release 发布流程。
+
+#### 1. release.yml 加 build-windows job — DONE
+
+`release.yml` 中已有 `build-windows` job，产出 `mcpp-<version>-windows-x86_64.zip` + sha256，上传到 GitHub Release。
+
+#### 2. 修复高价值 E2E skip 项
+
+按投入产出排序：
+
+| 测试 | 修复方式 | 工作量 |
+|------|----------|--------|
+| `02_new_build_run.sh` | 检查 `bin/hello` 或 `bin/hello.exe` | 小 |
+| `16_test_failing.sh` | 调查 Windows 上 exit code 传递 | 小 |
+| `35_workspace.sh` | 同上，binary 名加 `.exe` 检查 | 小 |
+| `36_llvm_toolchain.sh` | 同上 | 小 |
+| `19_bmi_cache_reuse.sh` | 修复 `cp_bmi` rule 的混合路径 | 中 |
+| `24_git_dependency.sh` | CRLF + Windows 路径处理 | 中 |
+| `38_self_config_mirror.sh` | xlings mirror cmd.exe 路径 | 中 |
+
+**预计可把 E2E 从 22 passed 提升到 ~30 passed。**
+
+### P1: PlatformTraits 抽象 — DONE (infrastructure)
+
+**目标：** 减少散落的 `#if defined(_WIN32)` / `#if defined(__APPLE__)`。
+
+`src/platform.cppm` 已创建，集中平台差异（exe_suffix、lib_prefix、null_redirect、shell_quote 等）。
+
+**受益文件：** `plan.cppm`、`flags.cppm`、`ninja_backend.cppm`、`probe.cppm`、`clang.cppm`、`config.cppm`（待各文件迁移到 `mcpp::platform` 命名空间）
+
+### P2: ToolchainProvider 重构 — TODO (src/provider.cppm 待创建)
+
+**目标：** 把工具链行为从散落的 `if (isClang)` / `if (isGcc)` 收敛到 provider 接口。
+
+当前工具链代码分散在：
+- `gcc.cppm` — GCC 行为
+- `clang.cppm` — Clang/libc++ 行为 + MSVC STL fallback
+- `llvm.cppm` — xlings 包映射
+- `detect.cppm` — 只处理 GCC/Clang
+- `flags.cppm` — 编译/链接 flags 按平台分支
+- `ninja_backend.cppm` — 构建规则按平台分支
+
+建议拆成明确的 provider：
+
+```
+ToolchainProvider (interface)
+  ├── GccProvider          — GCC + glibc/musl
+  ├── ClangLibcxxProvider  — Clang + libc++ (Linux/macOS)
+  ├── ClangMsvcProvider    — Clang + MSVC STL (Windows)
+  └── MsvcProvider         — cl.exe (未来)
+```
+
+每个 provider 声明：
+- `frontend()` → 编译器路径
+- `c_compiler()` → C 编译器
+- `archive_tool()` → ar/llvm-ar/lib.exe
+- `scanner()` → clang-scan-deps 路径
+- `stdlib_id()` → libc++/libstdc++/msvc-stl
+- `find_std_module()` → std.cppm/std.cc/std.ixx
+- `compile_flags()` → 平台相关编译 flags
+- `link_flags()` → 平台相关链接 flags
+- `bmi_traits()` → .gcm/.pcm/.ifc
+
+> **注：** `src/provider.cppm` 尚未创建；现有调用者（gcc.cppm、clang.cppm 等）待迁移。
+
+### P3: 跨平台 Process Runner — DONE (infrastructure, callers pending)
+
+**目标：** 消除 shell 字符串拼接，统一子进程执行。
+
+`src/process.cppm` 已创建，提供 `ProcessOptions` / `ProcessResult` / `run()` 接口：
+- POSIX: `fork/exec` + `pipe`
+- Windows: `CreateProcessW` + `STARTUPINFOW`
+
+> **注：** 现有调用点（`probe.cppm`、`xlings.cppm`、`stdmod.cppm`、`ninja_backend.cppm`、`config.cppm`）仍使用 `popen`，待逐步迁移到 `process::run()`。
+
+### P4: `mcpp pack` Windows 支持
+
+**目标：** `mcpp pack` 原生支持 Windows PE 打包。
+
+当前 `pack.cppm` 依赖：
+- `LD_TRACE_LOADED_OBJECTS` (Linux ELF)
+- `patchelf` (RPATH 修改)
+- `tar -czf` (打包格式)
+
+Windows 需要：
+- DLL 依赖收集（`dumpbin /dependents` 或 `llvm-objdump`）
+- 无需 RPATH（DLL 在 exe 同目录自动找到）
+- `.zip` 打包 + `.bat` wrapper
+
+建议 pack 做成平台策略：
+
+```
+PackStrategy (interface)
+  ├── LinuxElfPack   — ldd + patchelf + tar.gz
+  ├── MacosMachoPack — otool + install_name_tool + tar.gz
+  └── WindowsPePack  — dumpbin + zip + .bat
+```
+
+### P5: E2E 能力标签化 — DONE (infrastructure)
+
+**目标：** 从"平台 skip 列表"升级为"能力标签"。
+
+能力标签体系已全面落地：
+- 全部 48 个 E2E 脚本头部均已声明 `# requires:` 行
+- `run_all.sh` 自动检测平台能力（elf、gcc、musl、pack、symlink、scan-deps、import-std-libcxx、unix-shell、fresh-sandbox）并动态 skip
+- 不再维护平台 skip 列表
+
+支持的标签：
+
+```bash
+# requires: elf          — 需要 ELF 工具链
+# requires: gcc          — 需要 GCC
+# requires: symlink      — 需要 ln -sf（仅 Linux/macOS 或 Windows Developer Mode）
+# requires: scan-deps    — 需要 clang-scan-deps
+# requires: import-std-libcxx — 需要 import std (std.cppm via libc++)
+# requires: pack         — 需要 mcpp pack
+# requires: unix-shell   — 需要 bash 风格 shell（非 cmd.exe）
+# requires: fresh-sandbox — 需要隔离 MCPP_HOME
+```
+
+## 实施顺序
+
+```
+P0 release + E2E 修复   ✅ DONE（release.yml build-windows job 已加）
+  ↓
+P1 PlatformTraits       ✅ DONE（src/platform.cppm 已创建，待调用者迁移）
+  ↓
+P2 ToolchainProvider    ← src/provider.cppm 待创建 + 调用者迁移
+  ↓
+P3 Process Runner       ✅ DONE（src/process.cppm 已创建，待调用者迁移）
+  ↓
+P4 mcpp pack Windows    ← 产品化打包
+  ↓
+P5 E2E 标签化           ✅ DONE（全部 48 个测试已标签化）
+```
+
+## 预期里程碑
+
+| 阶段 | 目标 | Windows E2E 通过率 |
+|------|------|-------------------|
+| 当前 | self-host + 基础 E2E | 22/48 (46%) |
+| P0 完成 | release + 高价值 E2E | ~30/48 (63%) |
+| P1+P2 完成 | 平台抽象 + provider | ~35/48 (73%) |
+| P3+P4 完成 | process runner + pack | ~40/48 (83%) |
+| P5 完成 | 能力标签 | 动态评估 |