fix: mcpp self config --mirror X hangs on fresh MCPP_HOME

Root cause: `cmd_self_config` called the full `load_or_init`, whose step 7
(xlings sandbox bootstrap — `xlings self init`, ensure_patchelf,
ensure_ninja) hits the network using the *current* `.xlings.json` mirror.
On a fresh MCPP_HOME that's the seeded default `"CN"`, so the act of
running `mcpp self config --mirror GLOBAL` would download from CN before
having a chance to switch — the very chicken-and-egg the command is
supposed to break.

Fix:
- `config::load_or_init` grows a `skip_xlings_bootstrap` parameter
  (default false, all existing callers unchanged). When true, steps 1-6
  still run (dirs / config.toml / .xlings.json seed / xlings binary
  acquisition — all local) but step 7 (the network roundtrip) is skipped.
- New `xlings::set_mirror_in_xlings_json(path, mirror)`: in-place text
  edit of just the `"mirror"` field, preserving every other key (no
  subprocess, no network, safe pre-bootstrap).
- `cmd_self_config` rewritten:
   * `--mirror X` path: `load_or_init(skip_xlings_bootstrap=true)` then
     `set_mirror_in_xlings_json`. Pure local file ops, completes in ms.
   * no-arg show path: same `skip_xlings_bootstrap=true`, since
     `xlings config` only reads `.xlings.json` (doesn't need patchelf
     or ninja).

The next mcpp invocation that genuinely needs bootstrap (build / run /
toolchain install) runs the full bootstrap with the just-saved mirror
in effect.

TODO comments added at both `seed_xlings_json` and `cmd_self_config`
about the long-term direction of the default mirror — either flip to
`GLOBAL` (with docs covering the CN opt-in switch) or auto-detect
(env hint + a quick HEAD probe with a tight timeout, pinning the
winning value).

Test: tests/e2e/46_self_config_mirror_no_bootstrap.sh — fresh MCPP_HOME,
runs `mcpp self config --mirror GLOBAL` under a 10s timeout, asserts
.xlings.json picks up GLOBAL and that xim-x-patchelf / xim-x-ninja
were NOT installed by this command (proving no network bootstrap fired).
Round-trips back to CN as a second pure-local edit.

Existing test 38_self_config_mirror.sh still passes: it always called
`mcpp self env` first (which uses the original full-bootstrap path), so
the "default mirror is CN" invariant is preserved.

Author: Sunrisepeak

src/cli.cppm

@@ -4355,33 +4355,58 @@ std::string upper_ascii(std::string s) {
 }
 
 int cmd_self_config(const mcpplibs::cmdline::ParsedArgs& parsed) {
-    auto cfg = mcpp::config::load_or_init(/*quiet=*/false, make_bootstrap_progress_callback());
-    if (!cfg) {
-        mcpp::ui::error(cfg.error().message);
-        return 4;
-    }
-
-    auto env = mcpp::config::make_xlings_env(*cfg);
     auto mirror = parsed.option_or_empty("mirror").value();
-    if (mirror.empty()) {
-        auto rc = mcpp::xlings::config_show(env);
-        return rc == 0 ? 0 : 1;
-    }
 
-    mirror = upper_ascii(std::move(mirror));
-    if (mirror != "CN" && mirror != "GLOBAL") {
-        mcpp::ui::error(std::format(
-            "invalid mirror '{}'; expected CN or GLOBAL", mirror));
-        return 2;
+    // `--mirror` write path: deliberately skip the xlings sandbox bootstrap
+    // (patchelf + ninja install over the network) so that switching the
+    // mirror does NOT itself trigger the very network roundtrip the user
+    // is trying to redirect. Mirror is persisted directly into .xlings.json
+    // — no xlings subprocess needed for that, and the next mcpp command
+    // (build / run / toolchain install) will run the bootstrap with the
+    // chosen mirror in effect.
+    //
+    // TODO(mirror-default): see the matching comment on seed_xlings_json
+    // for the long-term plan (flip default to GLOBAL or auto-detect).
+    if (!mirror.empty()) {
+        mirror = upper_ascii(std::move(mirror));
+        if (mirror != "CN" && mirror != "GLOBAL") {
+            mcpp::ui::error(std::format(
+                "invalid mirror '{}'; expected CN or GLOBAL", mirror));
+            return 2;
+        }
+
+        auto cfg = mcpp::config::load_or_init(
+            /*quiet=*/true,
+            make_bootstrap_progress_callback(),
+            /*skip_xlings_bootstrap=*/true);
+        if (!cfg) {
+            mcpp::ui::error(cfg.error().message);
+            return 4;
+        }
+
+        auto xlingsJson = cfg->xlingsHome() / ".xlings.json";
+        if (!mcpp::xlings::set_mirror_in_xlings_json(xlingsJson, mirror)) {
+            mcpp::ui::error(std::format(
+                "failed to update mirror in '{}'", xlingsJson.string()));
+            return 1;
+        }
+        mcpp::ui::status("Configured", std::format("xlings mirror = {}", mirror));
+        return 0;
     }
 
-    auto rc = mcpp::xlings::config_set_mirror(env, mirror, /*quiet=*/true);
-    if (rc != 0) {
-        mcpp::ui::error(std::format("failed to set xlings mirror to {}", mirror));
-        return 1;
+    // Show path: also takes the lite init — `xlings config` only reads
+    // .xlings.json, so the sandbox bootstrap isn't required for it either.
+    auto cfg = mcpp::config::load_or_init(
+        /*quiet=*/false,
+        make_bootstrap_progress_callback(),
+        /*skip_xlings_bootstrap=*/true);
+    if (!cfg) {
+        mcpp::ui::error(cfg.error().message);
+        return 4;
     }
-    mcpp::ui::status("Configured", std::format("xlings mirror = {}", mirror));
-    return 0;
+    auto env = mcpp::config::make_xlings_env(*cfg);
+    auto rc = mcpp::xlings::config_show(env);
+    return rc == 0 ? 0 : 1;
 }
 
 // Used both by `mcpp explain <CODE>` (top-level) and `mcpp self explain

src/config.cppm

@@ -186,9 +186,17 @@ using BootstrapFile             = mcpp::xlings::BootstrapFile;
 using BootstrapProgress         = mcpp::xlings::BootstrapProgress;
 using BootstrapProgressCallback = mcpp::xlings::BootstrapProgressCallback;
 
+// `skip_xlings_bootstrap`: when true, steps 1-6 still run (dirs, config.toml,
+// .xlings.json seed, xlings binary placement — all local, no network), but
+// step 7 (xlings self init + ensure_patchelf + ensure_ninja, which all hit
+// the network) is skipped. Used by `mcpp self config --mirror` so the user
+// can change the mirror BEFORE the very first network roundtrip — otherwise
+// the act of running `self config` would itself trigger a CN-mirror
+// bootstrap that they were trying to avoid (chicken-and-egg).
 std::expected<GlobalConfig, ConfigError> load_or_init(
     bool quiet = false,
-    BootstrapProgressCallback onBootstrapProgress = {});
+    BootstrapProgressCallback onBootstrapProgress = {},
+    bool skip_xlings_bootstrap = false);
 
 // Pretty-print resolved config for `mcpp env` command.
 void print_env(const GlobalConfig& cfg);
@@ -385,7 +393,8 @@ void ensure_sandbox_patchelf(const GlobalConfig& cfg, bool quiet,
 
 std::expected<GlobalConfig, ConfigError> load_or_init(
     bool quiet,
-    BootstrapProgressCallback onBootstrapProgress)
+    BootstrapProgressCallback onBootstrapProgress,
+    bool skip_xlings_bootstrap)
 {
     GlobalConfig cfg;
 
@@ -538,6 +547,13 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     //    TODO(xlings-upstream): collapse into a single
     //    `xlings sandbox bootstrap --home <X>` once that command exists
     //    upstream (see docs/short-term-vs-long-track plan).
+    //
+    //    Skipped by `mcpp self config --mirror` so that command never hits
+    //    the network. The next mcpp invocation that needs bootstrap (build,
+    //    run, toolchain install) will run this block with the just-saved
+    //    mirror in effect.
+    if (skip_xlings_bootstrap) return cfg;
+
     ensure_sandbox_xlings_binary(cfg, quiet);
     ensure_sandbox_init(cfg, quiet);
     {

src/xlings.cppm

@@ -197,10 +197,34 @@ int install_with_progress(const Env& env, std::string_view target,
 // ─── Sandbox lifecycle ──────────────────────────────────────────────
 
 // Write .xlings.json seed file.
+//
+// TODO(mirror-default): the default `"CN"` here is the historical setting
+// for the project's initial Chinese-mainland user base, but it bites
+// overseas users (and CI on GitHub-hosted runners) — the first network
+// roundtrip goes through a CN mirror that is slow/unreachable for them.
+// Two reasonable future directions:
+//   (a) flip the default to `"GLOBAL"` and have CN users opt in via
+//       `mcpp self config --mirror CN` (smaller blast radius once docs
+//       cover the switch);
+//   (b) auto-detect on first init (env hint like `LANG`, a quick HEAD
+//       to github.com vs. ghproxy with a tight timeout, and pin the
+//       winning value into .xlings.json).
+// Either way, this default is a deliberate placeholder, not a final
+// decision. Discussion: ../docs/ (none yet — open an issue when ready).
 void seed_xlings_json(const Env& env,
                       std::span<const std::pair<std::string,std::string>> repos,
                       std::string_view mirror = "CN");
 
+// Update only the `"mirror"` field of an existing .xlings.json in place,
+// preserving every other key (including any user-added index_repos that
+// were not seeded by mcpp). If the file is absent or unparseable, the
+// caller is responsible for having seeded it first; this function returns
+// false in that case so the caller can fall back to seed_xlings_json.
+//
+// No subprocess. No network. Safe to call before xlings sandbox bootstrap.
+bool set_mirror_in_xlings_json(const std::filesystem::path& xlingsJson,
+                               std::string_view mirror);
+
 // Persist the xlings mirror selection in .xlings.json via xlings itself.
 int config_show(const Env& env);
 int config_set_mirror(const Env& env, std::string_view mirror, bool quiet = false);
@@ -790,6 +814,43 @@ void seed_xlings_json(const Env& env,
     write_file(path, json);
 }
 
+bool set_mirror_in_xlings_json(const std::filesystem::path& xlingsJson,
+                               std::string_view mirror)
+{
+    std::error_code ec;
+    if (!std::filesystem::exists(xlingsJson, ec)) return false;
+
+    std::ifstream is(xlingsJson);
+    if (!is) return false;
+    std::stringstream ss; ss << is.rdbuf();
+    std::string text = ss.str();
+
+    // Find the existing `"mirror"` key and replace just its string value,
+    // preserving every other character (whitespace, key order, comments
+    // would survive — though .xlings.json is strict JSON). The format we
+    // emit in seed_xlings_json always contains a mirror key, so this path
+    // is the expected one. Callers that see false should re-seed the file.
+    static constexpr std::string_view kKey = "\"mirror\"";
+    auto keyPos = text.find(kKey);
+    if (keyPos == std::string::npos) return false;
+
+    auto p = keyPos + kKey.size();
+    while (p < text.size() && (text[p] == ' ' || text[p] == '\t' || text[p] == ':'))
+        ++p;
+    if (p >= text.size() || text[p] != '"') return false;
+
+    auto valStart = p + 1;
+    auto valEnd   = text.find('"', valStart);
+    if (valEnd == std::string::npos) return false;
+
+    text.replace(valStart, valEnd - valStart, mirror);
+
+    std::ofstream os(xlingsJson, std::ios::trunc);
+    if (!os) return false;
+    os << text;
+    return static_cast<bool>(os);
+}
+
 int config_show(const Env& env) {
     auto cmd = std::format("{} config", build_command_prefix(env));
     return mcpp::platform::process::run_silent(cmd);

tests/e2e/46_self_config_mirror_no_bootstrap.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# requires:
+# 46_self_config_mirror_no_bootstrap.sh — `mcpp self config --mirror X` must
+# NOT trigger the xlings sandbox bootstrap (patchelf + ninja download). The
+# whole point of this command is to let the user redirect the mirror BEFORE
+# the first network roundtrip; the previous implementation made it
+# impossible to do so because the command itself would download from CN.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+# Truly fresh MCPP_HOME — no inherited toolchain, no inherited bootstrap.
+export MCPP_HOME="$TMP/fresh-mcpp-home"
+unset MCPP_VENDORED_XLINGS   # the test must work without a pre-staged xlings
+
+# 10s budget. Real local file writes take milliseconds; if the command
+# tries to install patchelf / ninja it will blow this budget. timeout(124)
+# is distinguished from a normal error so the failure message is clear.
+TIMEOUT_CMD=""
+if   command -v timeout  &>/dev/null; then TIMEOUT_CMD=timeout
+elif command -v gtimeout &>/dev/null; then TIMEOUT_CMD=gtimeout
+fi
+if [[ -z "$TIMEOUT_CMD" ]]; then
+    # No timeout available — proceed without it; the e2e runner caps the test.
+    "$MCPP" self config --mirror GLOBAL > "$TMP/out.log" 2>&1
+    rc=$?
+else
+    "$TIMEOUT_CMD" 10 "$MCPP" self config --mirror GLOBAL > "$TMP/out.log" 2>&1
+    rc=$?
+fi
+if [[ $rc -ne 0 ]]; then
+    cat "$TMP/out.log"
+    if [[ $rc -eq 124 ]]; then
+        echo "FAIL: 'self config --mirror' hung (>10s) — it should be a pure local write, not bootstrap"
+    else
+        echo "FAIL: 'self config --mirror' exited $rc on fresh MCPP_HOME"
+    fi
+    exit 1
+fi
+
+# .xlings.json must exist with the requested mirror.
+grep -q '"mirror": "GLOBAL"' "$MCPP_HOME/registry/.xlings.json" || {
+    cat "$MCPP_HOME/registry/.xlings.json" 2>/dev/null || true
+    echo "FAIL: .xlings.json did not pick up GLOBAL"
+    exit 1
+}
+
+# Crucial: bootstrap tools must NOT have been installed by this command.
+# If they were, the user's mirror choice came too late to matter.
+for tool in xim-x-patchelf xim-x-ninja; do
+    if [[ -d "$MCPP_HOME/registry/data/xpkgs/$tool" ]]; then
+        ls "$MCPP_HOME/registry/data/xpkgs/$tool"
+        echo "FAIL: '$tool' was installed by self config --mirror — that path"
+        echo "      defeats the whole purpose of letting the user redirect"
+        echo "      the mirror before the first network roundtrip."
+        exit 1
+    fi
+done
+
+# Round-trip: switching back to CN should also be a pure local edit.
+"$MCPP" self config --mirror CN > "$TMP/cn.log" 2>&1 || {
+    cat "$TMP/cn.log"
+    echo "FAIL: switching mirror back to CN failed"
+    exit 1
+}
+grep -q '"mirror": "CN"' "$MCPP_HOME/registry/.xlings.json" || {
+    cat "$MCPP_HOME/registry/.xlings.json"
+    echo "FAIL: .xlings.json did not pick up CN on switch back"
+    exit 1
+}
+
+echo "OK"