feat(toolchain): MSVC system-toolchain detection & selection (msvc@system) (0.0.88)

MSVC joins as the first *system* toolchain: mcpp locates and identifies an
installed Visual Studio / Build Tools (vswhere → env → well-known paths;
cl.exe banner → compiler version/arch, localization-tolerant) but never
installs or removes MSVC itself.

- toolchain default msvc: detect + report (VS product, VC tools, cl version,
  std.ixx availability), persist stable 'msvc@system'; absent → install
  guidance (VS Installer C++ workload / winget BuildTools), exit non-zero.
  msvc@<prefix> acts as pin-verify against the detected install.
- toolchain list: Windows 'System:' section; install msvc reports what's
  there or guides; remove msvc refuses (system component).
- self doctor: Windows 'msvc (system)' check section.
- manifest [toolchain] windows = "msvc@system" now actually works; msvc
  specs on non-Windows hosts error clearly.
- build: native cl.exe (.ifc) pipeline is gated off with one owned message
  pointing at llvm@20.1.7 (MSVC-ABI Clang) until it lands.
- detect(): cl.exe classification path (filename short-circuit, banner
  enrich); bmi_traits gains the MSVC .ifc branch.
- tests: unit (banner/guidance/spec/traits) + e2e 95 (Windows, requires msvc
  cap) / 96 (non-Windows rejection); run_all.sh msvc capability.
- design: .agents/docs/2026-07-13-msvc-system-toolchain-detection-design.md

Author: Sunrisepeak

.github/workflows/ci-windows.yml

@@ -230,6 +230,38 @@ jobs:
           "$MCPP" clean --bmi-cache
           "$MCPP" build 2>&1 | tee build.log; grep -q "Resolved llvm@20.1.7" build.log
 
+      # windows-latest ships VS 2022 Enterprise with the VC workload, so
+      # msvc@system detection MUST succeed here — a failure is a regression
+      # in the discovery/identification chain (vswhere → env → paths).
+      - name: "Toolchain: MSVC — detection & selection (msvc@system)"
+        shell: bash
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+
+          out=$("$MCPP_SELF" toolchain default msvc); echo "$out"
+          grep -q "Detected"     <<<"$out"
+          grep -q "msvc@system"  <<<"$out"
+
+          "$MCPP_SELF" toolchain list | tee tc-list.txt
+          grep -E '\*\s*msvc' tc-list.txt
+
+          "$MCPP_SELF" self doctor 2>&1 | tee doctor.txt || true
+          grep -qi "msvc" doctor.txt
+
+          # native cl.exe builds are gated with one owned message
+          TMP=$(mktemp -d); cd "$TMP"
+          "$MCPP_SELF" new hello_msvc && cd hello_msvc
+          set +e
+          bout=$("$MCPP_SELF" build 2>&1); brc=$?
+          set -e
+          echo "$bout"
+          test $brc -ne 0
+          grep -q "not yet supported" <<<"$bout"
+
+          # restore the LLVM default for the remaining steps
+          cd "$GITHUB_WORKSPACE"
+          "$MCPP_SELF" toolchain default llvm@20.1.7
+
       - name: Package Windows release zip
         id: package
         shell: bash

CHANGELOG.md

@@ -3,6 +3,30 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.0.88] — 2026-07-13
+
+### 新增
+
+- **MSVC 系统工具链支持(`msvc@system`,detection-first)**。MSVC 作为首个
+  "系统工具链"接入:mcpp 负责**定位与识别**(vswhere → `VSINSTALLDIR`/
+  `VS*COMNTOOLS` → 标准安装路径三级发现;cl.exe banner 解析出编译器版本/架构,
+  容错本地化 banner),**从不安装/卸载** MSVC 本体。
+  - `mcpp toolchain default msvc`:检测系统 MSVC,打印 VS 产品/VC tools/
+    cl 版本与 `std.ixx`(import std)可用性,持久化稳定 spec `msvc@system`
+    (不落具体版本,VS 升级后配置依然有效);未安装时输出安装指引
+    (VS Installer C++ 工作负载 / `winget install …BuildTools`)并退出非零。
+    `msvc@19.44` 形式为 pin 校验(仍取最新 VC tools,前缀不符则报错)。
+  - `mcpp toolchain list`:Windows 上新增 `System:` 段展示检测到的 MSVC;
+    `install msvc` 报告已装现状或给指引;`remove msvc` 明确拒绝(系统组件)。
+  - `mcpp self doctor`:Windows 上新增 "msvc (system)" 检查段。
+  - manifest 支持 `[toolchain] windows = "msvc@system"`(types.cppm 注释中的
+    既有 schema 首次落地);非 Windows 主机使用 msvc spec 时给出明确报错。
+  - `mcpp build`:原生 cl.exe 构建(.ifc 管线)**本版暂不支持**,在工具链解析
+    后以单一 owned 错误信息拦截,并提示可用的 `llvm@20.1.7`(MSVC-ABI Clang)。
+  - detect() 新增 cl.exe 分类路径(文件名短路,banner → 版本/triple),
+    `bmi_traits` 预置 MSVC `.ifc` 分支;e2e 95/96 + 单测覆盖。
+  - 设计文档:`.agents/docs/2026-07-13-msvc-system-toolchain-detection-design.md`。
+
 ## [0.0.87] — 2026-07-09
 
 ### 修复

docs/03-toolchains.md

@@ -69,6 +69,52 @@ Available (run `mcpp toolchain install <compiler> <version>`):
 
 The entry marked with `*` is the current default toolchain. `@mcpp/...` is shorthand for `~/.mcpp/...`, used to keep the output narrower.
 
+## MSVC (System Toolchain, Windows)
+
+MSVC is different from every other toolchain mcpp manages: it is a **system
+toolchain**. mcpp locates and identifies an installed Visual Studio / Build
+Tools — it never installs, updates, or removes MSVC itself.
+
+```bash
+mcpp toolchain default msvc
+```
+
+On a machine with MSVC installed, mcpp auto-locates it (via `vswhere.exe`,
+then `VSINSTALLDIR`/`VS*COMNTOOLS`, then the standard install paths),
+identifies the versions involved, and persists the stable spec `msvc@system`:
+
+```
+Detected   msvc 19.44.35211 (VS 2022 BuildTools) (VC tools 14.44.35207)
+           cl: C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64\cl.exe
+           import std: available (std.ixx)
+Default    set to msvc@system (was: llvm@20.1.7)
+```
+
+If MSVC is **not** installed, mcpp prints installation guidance instead
+(Visual Studio Installer with the *Desktop development with C++* workload, or
+`winget install Microsoft.VisualStudio.2022.BuildTools`) and exits non-zero —
+install it yourself, then re-run the command.
+
+`mcpp toolchain list` shows the detected MSVC in a separate `System:` section,
+and `mcpp self doctor` reports its status on Windows. In a manifest you can
+pin it per-platform:
+
+```toml
+[toolchain]
+windows = "msvc@system"
+```
+
+`msvc@<prefix>` (e.g. `msvc@19.44`) acts as a pin-verify: mcpp still uses the
+newest installed VC tools, but errors if the detected version doesn't match
+the prefix.
+
+> [!NOTE]
+> Selection and detection are supported today; **building with native MSVC
+> (cl.exe) is not yet supported** — `mcpp build` fails with a clear message
+> naming the detected version. For building on Windows use the MSVC-ABI Clang
+> toolchain: `mcpp toolchain default llvm@20.1.7` (it borrows the MSVC STL
+> from the same detected installation).
+
 ## Project-Level Version Pinning
 
 If a project needs to pin a specific version rather than rely on the global default, declare it in the project's `mcpp.toml`:

mcpp.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "0.0.87"
+version     = "0.0.88"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

src/build/prepare.cppm

@@ -18,6 +18,7 @@ import mcpp.modgraph.validate;
 import mcpp.toolchain.clang;
 import mcpp.toolchain.detect;
 import mcpp.toolchain.fingerprint;
+import mcpp.toolchain.msvc;
 import mcpp.toolchain.registry;
 import mcpp.toolchain.stdmod;
 import mcpp.toolchain.post_install;
@@ -682,7 +683,28 @@ prepare_build(bool print_fingerprint,
         }
     }
 
-    if (tcSpec.has_value() && *tcSpec != "system") {
+    // msvc@system: a *system* toolchain — located on the machine, never
+    // resolved through xim packages. mcpp does not install MSVC.
+    bool tcSpecIsMsvc = false;
+    if (tcSpec.has_value()) {
+        if (auto s = mcpp::toolchain::parse_toolchain_spec(*tcSpec);
+            s && mcpp::toolchain::is_system_toolchain(*s))
+            tcSpecIsMsvc = true;
+    }
+    if (tcSpecIsMsvc) {
+        if (!mcpp::platform::is_windows) {
+            return std::unexpected(std::format(
+                "toolchain '{}' is only available on Windows hosts", *tcSpec));
+        }
+        auto inst = mcpp::toolchain::msvc::detect_installation();
+        if (!inst) {
+            return std::unexpected(mcpp::toolchain::msvc::install_guidance());
+        }
+        explicit_compiler = inst->clPath;
+        mcpp::ui::info("Resolved", std::format(
+            "msvc@system → msvc {} ({})",
+            inst->display_version(), inst->clPath.string()));
+    } else if (tcSpec.has_value() && *tcSpec != "system") {
         auto spec = mcpp::toolchain::parse_toolchain_spec(*tcSpec);
         if (!spec || spec->version.empty()) {
             return std::unexpected(std::format(
@@ -841,6 +863,19 @@ prepare_build(bool print_fingerprint,
     auto tc = mcpp::toolchain::detect(explicit_compiler);
     if (!tc) return std::unexpected(tc.error().message);
 
+    // Native MSVC builds are gated off until the cl.exe/.ifc pipeline lands.
+    // Selection & detection (`mcpp toolchain default msvc`, `list`, `doctor`)
+    // work; the build must fail here with one owned message rather than an
+    // incidental error deep in the GCC/Clang-shaped flag machinery.
+    if (tc->compiler == mcpp::toolchain::CompilerId::MSVC) {
+        return std::unexpected(std::format(
+            "native MSVC (cl.exe) builds are not yet supported by mcpp.\n"
+            "       detected: msvc {} at {} (selection & detection work today)\n"
+            "       for building on Windows use the MSVC-ABI Clang toolchain instead:\n"
+            "         mcpp toolchain default llvm@20.1.7",
+            tc->version, tc->binaryPath.string()));
+    }
+
     // For musl-gcc the toolchain is fully self-contained
     // (`<root>/x86_64-linux-musl/{include,lib}` is its own sysroot).
     // musl-gcc's `-dumpmachine` reports `x86_64-linux-musl`.

src/doctor.cppm

@@ -16,8 +16,10 @@ import mcpp.build.plan;
 import mcpp.config;
 import mcpp.fallback.install_integrity;
 import mcpp.fetcher.progress;
+import mcpp.platform;
 import mcpp.platform.process;
 import mcpp.toolchain.detect;
+import mcpp.toolchain.msvc;
 import mcpp.toolchain.registry;
 import mcpp.toolchain.stdmod;
 import mcpp.toolchain.abi;
@@ -96,6 +98,30 @@ export int doctor_report() {
         ok(std::format("{} at {}", tc->label(), tc->binaryPath.string()));
     }
 
+    // Windows: report the system MSVC (msvc@system). Absence is a warning,
+    // not an error — mcpp works with LLVM/Clang without it, and mcpp never
+    // installs MSVC itself.
+    if (mcpp::platform::is_windows) {
+        mcpp::ui::status("Checking", "msvc (system)");
+        if (auto inst = mcpp::toolchain::msvc::detect_installation()) {
+            ok(std::format("msvc {}{} (VC tools {})",
+                inst->display_version(),
+                inst->vsProduct.empty()
+                    ? std::string{}
+                    : std::format(" (VS {})", inst->vsProduct),
+                inst->toolsVersion));
+            ok(std::format("cl at {}", inst->clPath.string()));
+            if (inst->hasStdModules) {
+                ok("import std: std.ixx available");
+            } else {
+                warn("MSVC STL std.ixx missing (VC tools too old for import std?)");
+            }
+        } else {
+            warn("msvc not detected — run `mcpp toolchain default msvc` for "
+                 "setup guidance (mcpp does not install MSVC)");
+        }
+    }
+
     mcpp::ui::status("Checking", "std module");
     if (tc) {
         auto cacheRoot = mcpp::toolchain::default_cache_root();

src/toolchain/detect.cppm

@@ -8,6 +8,7 @@ export import mcpp.toolchain.probe;
 import std;
 import mcpp.toolchain.clang;
 import mcpp.toolchain.gcc;
+import mcpp.toolchain.msvc;
 import mcpp.xlings;
 
 export namespace mcpp::toolchain {
@@ -38,6 +39,17 @@ detect(const std::filesystem::path& explicit_compiler) {
 
     Toolchain tc;
     tc.binaryPath = *bin_r;
+
+    // MSVC cl.exe has no --version / -dumpmachine / -print-sysroot; classify
+    // it by filename and take a dedicated enrich path (banner → version,
+    // arch → triple, std.ixx lookup). No runtime dirs / sysroot / payloads —
+    // those concepts are GCC/Clang-shaped.
+    if (auto stem = lower_copy(tc.binaryPath.stem().string()); stem == "cl") {
+        if (auto r = mcpp::toolchain::msvc::enrich_toolchain_from_cl(tc); !r)
+            return std::unexpected(r.error());
+        return tc;
+    }
+
     tc.compilerRuntimeDirs = discover_compiler_runtime_dirs(tc.binaryPath);
     auto envPrefix = compiler_env_prefix(tc);
 

src/toolchain/fingerprint.cppm

@@ -18,7 +18,7 @@ import mcpp.toolchain.detect;
 
 export namespace mcpp::toolchain {
 
-inline constexpr std::string_view MCPP_VERSION = "0.0.87";
+inline constexpr std::string_view MCPP_VERSION = "0.0.88";
 
 struct FingerprintInputs {
     Toolchain                       toolchain;