fix(index): refresh missing xim package metadata

Author: Sunrisepeak

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

@@ -148,6 +148,28 @@ 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.
 
+### 7. Fresh official index marker does not imply the target package exists
+
+The third PR checkpoint still failed in the same Linux musl step. The package
+lookup error remained:
+
+```text
+[error] package 'xim:musl-gcc@15.1.0' not found
+```
+
+That means a restored CI cache can still satisfy the coarse check
+`xim-pkgindex/pkgs + .mcpp-index-updated` while missing the package file added
+later:
+
+```text
+xim-pkgindex/pkgs/m/musl-gcc.lua
+```
+
+For `xim:` auto-installs, the freshness guard must therefore check the target
+package's index file, not just the official index directory. If the package
+file is absent, mcpp should silently run `xlings update` before calling either
+the NDJSON interface install path or the direct CLI fallback.
+
 ## Implementation Plan
 
 - [x] Add focused regression coverage for default-index refresh quietness.
@@ -163,6 +185,8 @@ from the default modular-library `mcpplibs` index.
       diagnostics.
 - [x] Track official `xim-pkgindex` freshness independently and refresh it
       before auto-installing `xim:` toolchain packages.
+- [x] Require the target package file to exist before treating an official
+      `xim:` index as fresh.
 - [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.
 
@@ -233,3 +257,19 @@ from the default modular-library `mcpplibs` index.
       passed.
     - `/tmp/mcpp-fresh-codex clean && /tmp/mcpp-fresh-codex build --target
       x86_64-linux-musl` passed and resolved `gcc@15.1.0-musl`.
+  - The next CI run still failed at the same musl step, proving the remaining
+    stale-cache shape is target-package-level, not just official-index-level.
+  - Added `is_official_package_index_fresh()` /
+    `ensure_official_package_index_fresh()` and wired `xim:` auto-installs to
+    check the concrete package file (for example `pkgs/m/musl-gcc.lua`).
+  - Added two more unit tests for a fresh official index marker with a missing
+    target package file.
+  - Local verification after this package-file fix:
+    - `mcpp test -- --gtest_filter=XlingsIndexFreshness.*` passed with 8
+      matching `test_xlings` cases.
+    - `mcpp build --no-cache` passed.
+    - 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

@@ -694,8 +694,8 @@ Fetcher::resolve_xpkg_path(std::string_view target,
     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);
+            mcpp::xlings::ensure_official_package_index_fresh(
+                xlEnv, parsed.packageName, cfg_.searchTtlSeconds, /*quiet=*/true);
         }
 
         std::vector<std::string> targets {

src/xlings.cppm

@@ -246,6 +246,13 @@ bool is_index_fresh(const Env& env, std::int64_t ttlSeconds);
 // toolchains live in xim-pkgindex, while modular libraries live in mcpplibs.
 bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds);
 
+// Check whether a specific package file exists in xlings' official xim index
+// and the index is fresh. This catches restored CI caches that have an index
+// directory and marker but predate a package added later.
+bool is_official_package_index_fresh(const Env& env,
+                                     std::string_view packageName,
+                                     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);
@@ -258,6 +265,12 @@ void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = fa
 // Ensure xlings' official xim index is present and fresh.
 void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet = false);
 
+// Ensure a specific package file exists in xlings' official xim index.
+void ensure_official_package_index_fresh(const Env& env,
+                                         std::string_view packageName,
+                                         std::int64_t ttlSeconds,
+                                         bool quiet = false);
+
 // ─── run_capture utility ────────────────────────────────────────────
 
 std::expected<std::string, std::string> run_capture(const std::string& cmd);
@@ -298,6 +311,12 @@ std::filesystem::path index_refresh_marker(const std::filesystem::path& indexDir
     return indexDir / ".mcpp-index-updated";
 }
 
+std::filesystem::path official_package_file(const Env& env, std::string_view packageName) {
+    if (packageName.empty()) return {};
+    std::string name(packageName);
+    return official_index_dir(env) / "pkgs" / std::string(1, name[0]) / (name + ".lua");
+}
+
 void mark_index_refreshed(const std::filesystem::path& indexDir) {
     if (!std::filesystem::exists(index_pkgs_dir(indexDir))) return;
     std::error_code ec;
@@ -1016,6 +1035,14 @@ bool is_official_index_fresh(const Env& env, std::int64_t ttlSeconds) {
     return is_index_dir_fresh(official_index_dir(env), ttlSeconds);
 }
 
+bool is_official_package_index_fresh(const Env& env,
+                                     std::string_view packageName,
+                                     std::int64_t ttlSeconds) {
+    if (!is_official_index_fresh(env, ttlSeconds)) return false;
+    auto pkg = official_package_file(env, packageName);
+    return !pkg.empty() && std::filesystem::exists(pkg);
+}
+
 int update_index(const Env& env, bool quiet) {
     std::string cmd = build_command_prefix(env) + " update 2>&1";
     int rc = mcpp::platform::process::run_streaming(cmd,
@@ -1040,4 +1067,14 @@ void ensure_official_index_fresh(const Env& env, std::int64_t ttlSeconds, bool q
     update_index(env, /*quiet=*/true);
 }
 
+void ensure_official_package_index_fresh(const Env& env,
+                                         std::string_view packageName,
+                                         std::int64_t ttlSeconds,
+                                         bool quiet) {
+    if (is_official_package_index_fresh(env, packageName, ttlSeconds)) return;
+    if (!quiet)
+        print_status("Updating", "package index (auto-refresh)");
+    update_index(env, /*quiet=*/true);
+}
+
 } // namespace mcpp::xlings

tests/unit/test_xlings.cpp

@@ -86,3 +86,28 @@ TEST(XlingsIndexFreshness, AcceptsFreshOfficialXimIndex) {
 
     std::filesystem::remove_all(home);
 }
+
+TEST(XlingsIndexFreshness, RequiresOfficialPackageFileEvenWhenOfficialIndexIsFresh) {
+    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_FALSE(mcpp::xlings::is_official_package_index_fresh(env, "musl-gcc", 3600));
+
+    std::filesystem::remove_all(home);
+}
+
+TEST(XlingsIndexFreshness, AcceptsFreshOfficialPackageFile) {
+    auto home = make_tempdir("mcpp-xlings-index-freshness");
+    std::filesystem::create_directories(home / "data" / "xim-pkgindex" / "pkgs" / "m");
+    std::ofstream(home / "data" / "xim-pkgindex" / ".mcpp-index-updated") << "ok\n";
+    std::ofstream(home / "data" / "xim-pkgindex" / "pkgs" / "m" / "musl-gcc.lua") << "package = {}\n";
+
+    mcpp::xlings::Env env{.home = home};
+
+    EXPECT_TRUE(mcpp::xlings::is_official_package_index_fresh(env, "musl-gcc", 3600));
+
+    std::filesystem::remove_all(home);
+}