refactor: extract fallback code into src/fallback/ modules

Move fallback implementations from config.cppm, package_fetcher.cppm,
and probe.cppm into dedicated modules under src/fallback/:

- xpkg_copy.cppm: copy xpkg from global ~/.xlings/ to sandbox
- xlings_binary.cppm: xlings binary acquisition chain
- config_migration.cppm: legacy index name migration
- sysroot_complete.cppm: sysroot header symlink completion
- legacy_dirs.cppm: legacy xpkg directory scan
- probe_sysroot.cppm: sysroot detection strategies

Also refactors resolve_xpkg_path() priority:
  Before: sandbox → copy → install
  After:  sandbox → install → copy (fallback)

Author: Sunrisepeak

src/config.cppm

@@ -24,6 +24,8 @@ import mcpp.pm.index_spec;
 import mcpp.xlings;
 import mcpp.platform;
 import mcpp.log;
+import mcpp.fallback.xlings_binary;
+import mcpp.fallback.config_migration;
 
 export namespace mcpp::config {
 
@@ -265,55 +267,7 @@ bool write_default_xlings_json(const std::filesystem::path& path,
     return std::filesystem::exists(path);
 }
 
-bool replace_all(std::string& text, std::string_view from, std::string_view to) {
-    bool changed = false;
-    for (std::size_t pos = 0;
-         (pos = text.find(from, pos)) != std::string::npos;) {
-        text.replace(pos, from.size(), to);
-        pos += to.size();
-        changed = true;
-    }
-    return changed;
-}
-
-bool write_text_if_changed(const std::filesystem::path& path,
-                           const std::string& original,
-                           const std::string& updated) {
-    if (updated == original) return false;
-    write_file(path, updated);
-    return true;
-}
-
-bool migrate_legacy_config_toml_index_names(const std::filesystem::path& path) {
-    std::ifstream is(path);
-    if (!is) return false;
-    std::stringstream ss;
-    ss << is.rdbuf();
-    auto original = ss.str();
-    auto updated = original;
-
-    replace_all(updated, "default = \"mcpp-index\"", "default = \"mcpplibs\"");
-    replace_all(updated, "[index.repos.\"mcpp-index\"]", "[index.repos.\"mcpplibs\"]");
-
-    return write_text_if_changed(path, original, updated);
-}
-
-bool migrate_legacy_xlings_json_index_names(const std::filesystem::path& path) {
-    std::ifstream is(path);
-    if (!is) return false;
-    std::stringstream ss;
-    ss << is.rdbuf();
-    auto original = ss.str();
-    auto updated = original;
-
-    // Older mcpp sandboxes seeded the package index under the repository
-    // name. Keep the URL and all xlings state intact; only rename the index
-    // key so xlings config/list output matches mcpp's default namespace.
-    replace_all(updated, "\"name\": \"mcpp-index\"", "\"name\": \"mcpplibs\"");
-    replace_all(updated, "\"name\":\"mcpp-index\"", "\"name\":\"mcpplibs\"");
-
-    return write_text_if_changed(path, original, updated);
-}
+// Migration helpers delegated to mcpp.fallback.config_migration.
 
 void canonicalize_legacy_index_names(GlobalConfig& cfg) {
     if (cfg.defaultIndex == "mcpp-index")
@@ -334,65 +288,7 @@ void canonicalize_legacy_index_names(GlobalConfig& cfg) {
     cfg.indexRepos = std::move(normalized);
 }
 
-// Try to acquire xlings binary. Returns the path if successful.
-std::expected<std::filesystem::path, std::string>
-acquire_xlings_binary(const std::filesystem::path& destBin, bool quiet)
-{
-    if (std::filesystem::exists(destBin)) return destBin;
-
-    std::error_code ec;
-    std::filesystem::create_directories(destBin.parent_path(), ec);
-
-    // 1. Explicit override
-    if (auto* e = std::getenv("MCPP_VENDORED_XLINGS"); e && *e) {
-        std::filesystem::path src{e};
-        if (std::filesystem::exists(src)) {
-            std::filesystem::copy_file(src, destBin,
-                std::filesystem::copy_options::overwrite_existing, ec);
-            if (!ec) {
-                std::filesystem::permissions(destBin,
-                    std::filesystem::perms::owner_exec
-                  | std::filesystem::perms::group_exec
-                  | std::filesystem::perms::others_exec,
-                  std::filesystem::perm_options::add, ec);
-                if (!quiet) print_status("Bundled",
-                    std::format("xlings v{} (from MCPP_VENDORED_XLINGS)", kXlingsPinnedVersion));
-                return destBin;
-            }
-        }
-    }
-
-    // 2. Copy from system (`which xlings`)
-    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);
-            if (!ec) {
-                std::filesystem::permissions(destBin,
-                    std::filesystem::perms::owner_exec
-                  | std::filesystem::perms::group_exec
-                  | std::filesystem::perms::others_exec,
-                  std::filesystem::perm_options::add, ec);
-                if (!quiet) print_status("Bundled",
-                    std::format("xlings (copied from system: {})", p));
-                return destBin;
-            }
-        }
-    }
-
-    // 3. Download from GitHub Release (placeholder — real impl uses curl)
-    // We delegate to curl/wget in the bash bootstrap; for in-process robustness
-    // we just instruct the user.
-    return std::unexpected(std::format(
-        "xlings binary not found. Either:\n"
-        "  - install via: curl -fsSL https://raw.githubusercontent.com/d2learn/xlings/refs/heads/main/tools/other/quick_install.sh | bash\n"
-        "  - export MCPP_VENDORED_XLINGS=/abs/path/to/xlings\n"
-        "  - set [xlings].binary = \"system\" in {}",
-        (destBin.parent_path().parent_path() / "config.toml").string()));
-}
+// Xlings binary acquisition delegated to mcpp.fallback.xlings_binary.
 
 // Run `xlings self init` against the sandbox to create the standard
 // directory layout (subos/default/{bin,lib,usr,generations}, data/, config/,
@@ -471,7 +367,7 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     // 3. Seed config.toml if missing
     bool fresh_config = !std::filesystem::exists(cfg.configFile);
     if (fresh_config) write_default_config_toml(cfg.configFile);
-    else migrate_legacy_config_toml_index_names(cfg.configFile);
+    else mcpp::fallback::migrate_config_toml_index_names(cfg.configFile);
 
     // 4. Load config.toml
     auto doc = t::parse_file(cfg.configFile);
@@ -556,12 +452,12 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     if (!std::filesystem::exists(xjson)) {
         write_default_xlings_json(xjson, cfg.indexRepos);
     } else {
-        migrate_legacy_xlings_json_index_names(xjson);
+        mcpp::fallback::migrate_xlings_json_index_names(xjson);
     }
 
     // 6. Acquire xlings binary if needed
     if (cfg.xlingsBinaryMode == "bundled") {
-        auto xbin = acquire_xlings_binary(cfg.xlingsBinary, quiet);
+        auto xbin = mcpp::fallback::acquire_xlings_binary(cfg.xlingsBinary, quiet);
         if (!xbin) return std::unexpected(ConfigError{xbin.error()});
     } else if (cfg.xlingsBinaryMode == "system") {
         auto sysPath = mcpp::platform::fs::which(

src/fallback/config_migration.cppm

@@ -0,0 +1,83 @@
+// mcpp.fallback.config_migration — legacy index name migration.
+//
+// Older mcpp sandboxes used "mcpp-index" as the default index name.
+// These helpers rename it to "mcpplibs" in config.toml and .xlings.json
+// so xlings config/list output matches mcpp's default namespace.
+
+export module mcpp.fallback.config_migration;
+
+import std;
+
+export namespace mcpp::fallback {
+
+// Migrate config.toml: rename "mcpp-index" to "mcpplibs".
+// Returns true if the file was modified.
+bool migrate_config_toml_index_names(const std::filesystem::path& path);
+
+// Migrate .xlings.json: rename "mcpp-index" to "mcpplibs".
+// Returns true if the file was modified.
+bool migrate_xlings_json_index_names(const std::filesystem::path& path);
+
+} // namespace mcpp::fallback
+
+namespace mcpp::fallback {
+
+namespace {
+
+bool replace_all(std::string& text, std::string_view from, std::string_view to) {
+    bool changed = false;
+    for (std::size_t pos = 0;
+         (pos = text.find(from, pos)) != std::string::npos;) {
+        text.replace(pos, from.size(), to);
+        pos += to.size();
+        changed = true;
+    }
+    return changed;
+}
+
+void write_file(const std::filesystem::path& p, std::string_view content) {
+    std::error_code ec;
+    std::filesystem::create_directories(p.parent_path(), ec);
+    std::ofstream os(p);
+    os << content;
+}
+
+bool write_text_if_changed(const std::filesystem::path& path,
+                           const std::string& original,
+                           const std::string& updated) {
+    if (updated == original) return false;
+    write_file(path, updated);
+    return true;
+}
+
+} // namespace
+
+bool migrate_config_toml_index_names(const std::filesystem::path& path) {
+    std::ifstream is(path);
+    if (!is) return false;
+    std::stringstream ss;
+    ss << is.rdbuf();
+    auto original = ss.str();
+    auto updated = original;
+
+    replace_all(updated, "default = \"mcpp-index\"", "default = \"mcpplibs\"");
+    replace_all(updated, "[index.repos.\"mcpp-index\"]", "[index.repos.\"mcpplibs\"]");
+
+    return write_text_if_changed(path, original, updated);
+}
+
+bool migrate_xlings_json_index_names(const std::filesystem::path& path) {
+    std::ifstream is(path);
+    if (!is) return false;
+    std::stringstream ss;
+    ss << is.rdbuf();
+    auto original = ss.str();
+    auto updated = original;
+
+    replace_all(updated, "\"name\": \"mcpp-index\"", "\"name\": \"mcpplibs\"");
+    replace_all(updated, "\"name\":\"mcpp-index\"", "\"name\":\"mcpplibs\"");
+
+    return write_text_if_changed(path, original, updated);
+}
+
+} // namespace mcpp::fallback

src/fallback/legacy_dirs.cppm

@@ -0,0 +1,34 @@
+// mcpp.fallback.legacy_dirs — legacy xpkg directory scan.
+//
+// Last-resort fallback scan (COMPAT, remove in 1.0.0): walk xpkgs/
+// for any directory ending with -x-<qualifiedName> or -x-<shortName>.
+
+export module mcpp.fallback.legacy_dirs;
+
+import std;
+
+export namespace mcpp::fallback {
+
+// Scan the xpkgs base directory for a legacy install directory whose
+// name ends with "-x-<qualifiedName>" or "-x-<shortName>".
+// Returns the matching directory name (not the full path) if found.
+std::optional<std::string>
+scan_legacy_install_dirs(const std::filesystem::path& xpkgsBase,
+                         std::string_view qualifiedName,
+                         std::string_view shortName) {
+    std::error_code ec;
+    std::string suffix1 = std::format("-x-{}", qualifiedName);
+    std::string suffix2 = std::format("-x-{}", shortName);
+
+    for (auto& entry : std::filesystem::directory_iterator(xpkgsBase, ec)) {
+        if (!entry.is_directory()) continue;
+        auto dirname = entry.path().filename().string();
+        if (dirname.ends_with(suffix1))
+            return dirname;
+        if (suffix2 != suffix1 && dirname.ends_with(suffix2))
+            return dirname;
+    }
+    return std::nullopt;
+}
+
+} // namespace mcpp::fallback

src/fallback/probe_sysroot.cppm

@@ -0,0 +1,75 @@
+// mcpp.fallback.probe_sysroot — sysroot detection strategies.
+//
+// Three strategies for discovering the sysroot:
+//   1. Remap GCC's baked-in build-time sysroot to the local xpkgs layout
+//   2. Parse Clang's .cfg file for --sysroot=
+//   3. macOS: use xcrun to discover the SDK path
+
+module;
+#include <cstdlib>
+
+export module mcpp.fallback.probe_sysroot;
+
+import std;
+import mcpp.xlings;
+import mcpp.platform;
+import mcpp.log;
+
+export namespace mcpp::fallback {
+
+// When GCC reports a sysroot ending in "subos/default" that doesn't exist
+// on the current machine (baked build-time path), remap it to the
+// equivalent sysroot relative to the compiler's own xpkgs directory.
+std::optional<std::filesystem::path>
+remap_xlings_baked_sysroot(std::string_view reportedPath,
+                           const std::filesystem::path& compilerBin) {
+    if (reportedPath.empty()) return std::nullopt;
+    if (!reportedPath.ends_with("subos/default")) return std::nullopt;
+    if (std::filesystem::exists(std::string(reportedPath))) return std::nullopt;
+
+    if (auto xpkgs = mcpp::xlings::paths::xpkgs_from_compiler(compilerBin)) {
+        // xpkgs is <registry>/data/xpkgs -> registry = xpkgs/../..
+        auto registrySysroot = xpkgs->parent_path().parent_path()
+                               / "subos" / "default";
+        if (std::filesystem::exists(registrySysroot / "usr" / "include"))
+            return registrySysroot;
+    }
+    return std::nullopt;
+}
+
+// Parse a Clang .cfg file alongside the compiler binary for --sysroot=.
+std::optional<std::filesystem::path>
+parse_clang_cfg_sysroot(const std::filesystem::path& compilerBin) {
+    auto stem = compilerBin.stem().string();
+    auto cfgPath = compilerBin.parent_path() / (stem + ".cfg");
+    if (!std::filesystem::exists(cfgPath)) return std::nullopt;
+
+    std::ifstream ifs(cfgPath);
+    std::string line;
+    while (std::getline(ifs, line)) {
+        constexpr std::string_view prefix = "--sysroot=";
+        if (line.starts_with(prefix)) {
+            // Trim whitespace
+            auto val = std::string(line.substr(prefix.size()));
+            while (!val.empty() && (val.back() == '\n' || val.back() == '\r' || val.back() == ' '))
+                val.pop_back();
+            while (!val.empty() && (val.front() == '\n' || val.front() == '\r' || val.front() == ' '))
+                val.erase(val.begin());
+            if (!val.empty() && std::filesystem::exists(val))
+                return std::filesystem::path(val);
+        }
+    }
+    return std::nullopt;
+}
+
+// macOS fallback: use xcrun to discover the SDK path.
+std::optional<std::filesystem::path>
+probe_macos_sdk_sysroot() {
+    auto sdk = mcpp::platform::macos::sdk_path();
+    if (sdk) {
+        mcpp::log::verbose("probe", std::format("sysroot (macOS SDK): {}", sdk->string()));
+    }
+    return sdk;
+}
+
+} // namespace mcpp::fallback