fix(index): refresh official xim index for toolchains

Author: Sunrisepeak

.agents/docs/2026-05-31-index-refresh-cache-labels-plan.md

@@ -132,6 +132,22 @@ uses only the xlings NDJSON interface path for regular xpkg installs, while
 `mcpp.xlings::install_with_progress()` already documents the direct CLI path
 as more reliable for large package installs.
 
+### 6. Fresh mcpplibs marker does not imply fresh official xim index
+
+The direct-install fallback exposed the next failing layer in Linux CI:
+
+```text
+[error] package 'xim:musl-gcc@15.1.0' not found
+error: toolchain 'gcc@15.1.0-musl': xlings install of 'xim:musl-gcc@15.1.0' failed (interface exit 1, direct exit 1)
+```
+
+The same workflow's earlier e2e suite could install/build with musl-gcc in an
+isolated fresh home, so the package resource was available. The failing later
+step used the main mcpp sandbox, where `mcpplibs/.mcpp-index-updated` can be
+fresh while `xim-pkgindex/pkgs` is missing or stale. Toolchains are resolved
+from xlings' official `xim-pkgindex`, so mcpp must track that index separately
+from the default modular-library `mcpplibs` index.
+
 ## Implementation Plan
 
 - [x] Add focused regression coverage for default-index refresh quietness.
@@ -145,6 +161,8 @@ as more reliable for large package installs.
 - [x] Add a direct `xlings install <target> -y` fallback after interface
       install failure, preserving visible direct-install output for CI
       diagnostics.
+- [x] Track official `xim-pkgindex` freshness independently and refresh it
+      before auto-installing `xim:` toolchain packages.
 - [x] Validate with the local xlings checkout using the new mcpp binary.
 - [x] Push a draft PR and use it as the multi-commit checkpoint.
 
@@ -198,3 +216,20 @@ as more reliable for large package installs.
     `src/pm/package_fetcher.cppm`.
   - Re-ran local `mcpp build --no-cache`, `mcpp test --
     --gtest_filter=XlingsIndexFreshness.*`, and the three related e2e tests.
+  - The fallback made the hidden root cause visible on the second run:
+    the main sandbox could not find `xim:musl-gcc@15.1.0` because the official
+    `xim-pkgindex` data was missing/stale even though mcpp's default
+    `mcpplibs` marker was fresh.
+  - Added `is_official_index_fresh()` / `ensure_official_index_fresh()` and
+    call it before `xim:` auto-installs.
+  - Added unit coverage for a fresh default index with a missing official
+    `xim-pkgindex`.
+  - Local verification after this fix:
+    - `mcpp build --no-cache` passed.
+    - `mcpp test -- --gtest_filter=XlingsIndexFreshness.*` passed with 6
+      matching `test_xlings` cases.
+    - e2e `49_bmi_cache_nested_custom_index.sh`,
+      `52_local_path_namespaced_index.sh`, and `53_namespaced_cache_label.sh`
+      passed.
+    - `/tmp/mcpp-fresh-codex clean && /tmp/mcpp-fresh-codex build --target
+      x86_64-linux-musl` passed and resolved `gcc@15.1.0-musl`.

src/pm/package_fetcher.cppm

@@ -692,6 +692,12 @@ Fetcher::resolve_xpkg_path(std::string_view target,
 
     // 3. Install via xlings (primary path).
     if (autoInstall) {
+        if (parsed.indexName == "xim") {
+            mcpp::xlings::Env xlEnv{ cfg_.xlingsBinary, cfg_.xlingsHome() };
+            mcpp::xlings::ensure_official_index_fresh(
+                xlEnv, cfg_.searchTtlSeconds, /*quiet=*/true);
+        }
+
         std::vector<std::string> targets {
             std::format("{}:{}@{}", parsed.indexName, parsed.packageName, parsed.version)
         };

src/xlings.cppm

@@ -241,6 +241,11 @@ void ensure_ninja(const Env& env, bool quiet,
 // Returns true if index is present and fresh, false otherwise.
 bool is_index_fresh(const Env& env, std::int64_t ttlSeconds);
 
+// Check whether xlings' official xim index data exists and is fresh.
+// This is separate from mcpp's default mcpplibs index because xlings
+// toolchains live in xim-pkgindex, while modular libraries live in mcpplibs.
+bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds);
+
 // Run `xlings update` to refresh all index repos. Streams output to stdout.
 // Returns the xlings exit code.
 int update_index(const Env& env, bool quiet = false);
@@ -250,6 +255,9 @@ int update_index(const Env& env, bool quiet = false);
 // when no update is needed.
 void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = false);
 
+// Ensure xlings' official xim index is present and fresh.
+void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = false);
+
 // ─── run_capture utility ────────────────────────────────────────────
 
 std::expected<std::string, std::string> run_capture(const std::string& cmd);
@@ -278,21 +286,23 @@ std::filesystem::path default_index_dir(const Env& env) {
     return paths::index_data(env) / "mcpplibs";
 }
 
-std::filesystem::path default_index_pkgs_dir(const Env& env) {
-    return default_index_dir(env) / "pkgs";
+std::filesystem::path official_index_dir(const Env& env) {
+    return paths::index_data(env) / "xim-pkgindex";
 }
 
-std::filesystem::path default_index_refresh_marker(const Env& env) {
-    return default_index_dir(env) / ".mcpp-index-updated";
+std::filesystem::path index_pkgs_dir(const std::filesystem::path& indexDir) {
+    return indexDir / "pkgs";
 }
 
-void mark_default_index_refreshed(const Env& env) {
-    if (!env.projectDir.empty()) return;
-    if (!std::filesystem::exists(default_index_pkgs_dir(env))) return;
+std::filesystem::path index_refresh_marker(const std::filesystem::path& indexDir) {
+    return indexDir / ".mcpp-index-updated";
+}
 
+void mark_index_refreshed(const std::filesystem::path& indexDir) {
+    if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return;
     std::error_code ec;
-    std::filesystem::create_directories(default_index_dir(env), ec);
-    auto marker = default_index_refresh_marker(env);
+    std::filesystem::create_directories(indexDir, ec);
+    auto marker = index_refresh_marker(indexDir);
     {
         std::ofstream os(marker, std::ios::trunc);
         if (!os) return;
@@ -302,6 +312,27 @@ void mark_default_index_refreshed(const Env& env) {
         marker, std::filesystem::file_time_type::clock::now(), ec);
 }
 
+void mark_known_indexes_refreshed(const Env& env) {
+    if (!env.projectDir.empty()) return;
+    mark_index_refreshed(default_index_dir(env));
+    mark_index_refreshed(official_index_dir(env));
+}
+
+bool is_index_dir_fresh(const std::filesystem::path& indexDir, std::int64_t ttlSeconds) {
+    std::error_code ec;
+    if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return false;
+
+    auto marker = index_refresh_marker(indexDir);
+    if (!std::filesystem::exists(marker)) return false;
+
+    auto newest = std::filesystem::last_write_time(marker, ec);
+    if (ec) return false;
+
+    auto now = std::filesystem::file_time_type::clock::now();
+    auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest);
+    return age.count() < ttlSeconds;
+}
+
 void write_file(const std::filesystem::path& p, std::string_view content) {
     std::error_code ec;
     std::filesystem::create_directories(p.parent_path(), ec);
@@ -978,20 +1009,11 @@ void ensure_ninja(const Env& env, bool quiet,
 // ─── Index freshness ────────────────────────────────────────────────
 
 bool is_index_fresh(const Env& env, std::int64_t ttlSeconds) {
-    std::error_code ec;
-    auto pkgsDir = default_index_pkgs_dir(env);
-    if (!std::filesystem::exists(pkgsDir)) return false;
-
-    auto marker = default_index_refresh_marker(env);
-    if (!std::filesystem::exists(marker)) return false;
-
-    auto newest = std::filesystem::last_write_time(marker, ec);
-    if (ec) return false;
+    return is_index_dir_fresh(default_index_dir(env), ttlSeconds);
+}
 
-    // Check TTL
-    auto now = std::filesystem::file_time_type::clock::now();
-    auto age = std::chrono::duration_cast<std::chrono::seconds>(now - newest);
-    return age.count() < ttlSeconds;
+bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds) {
+    return is_index_dir_fresh(official_index_dir(env), ttlSeconds);
 }
 
 int update_index(const Env& env, bool quiet) {
@@ -1000,7 +1022,7 @@ int update_index(const Env& env, bool quiet) {
         [quiet](std::string_view line) {
             if (!quiet) std::println("{}", line);
         });
-    if (rc == 0) mark_default_index_refreshed(env);
+    if (rc == 0) mark_known_indexes_refreshed(env);
     return rc;
 }
 
@@ -1011,4 +1033,11 @@ void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet) {
     update_index(env, /*quiet=*/true);
 }
 
+void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet) {
+    if (is_official_index_fresh(env, ttlSeconds)) return;
+    if (!quiet)
+        print_status("Updating", "package index (auto-refresh)");
+    update_index(env, /*quiet=*/true);
+}
+
 } // namespace mcpp::xlings

tests/unit/test_xlings.cpp

@@ -62,3 +62,27 @@ TEST(XlingsIndexFreshness, RejectsStaleRefreshMarker) {
 
     std::filesystem::remove_all(home);
 }
+
+TEST(XlingsIndexFreshness, RequiresOfficialXimIndexEvenWhenDefaultIndexIsFresh) {
+    auto home = make_tempdir("mcpp-xlings-index-freshness");
+    std::filesystem::create_directories(home / "data" / "mcpplibs" / "pkgs");
+    std::ofstream(home / "data" / "mcpplibs" / ".mcpp-index-updated") << "ok\n";
+
+    mcpp::xlings::Env env{.home = home};
+
+    EXPECT_FALSE(mcpp::xlings::is_official_index_fresh(env, 3600));
+
+    std::filesystem::remove_all(home);
+}
+
+TEST(XlingsIndexFreshness, AcceptsFreshOfficialXimIndex) {
+    auto home = make_tempdir("mcpp-xlings-index-freshness");
+    std::filesystem::create_directories(home / "data" / "xim-pkgindex" / "pkgs");
+    std::ofstream(home / "data" / "xim-pkgindex" / ".mcpp-index-updated") << "ok\n";
+
+    mcpp::xlings::Env env{.home = home};
+
+    EXPECT_TRUE(mcpp::xlings::is_official_index_fresh(env, 3600));
+
+    std::filesystem::remove_all(home);
+}