fix(index): quiet refresh and canonical cache labels

Closes #90

Author: Sunrisepeak

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

@@ -0,0 +1,159 @@
+# Index Refresh And Dependency Cache Label Fix
+
+> Date: 2026-05-31 | Status: active | Branch:
+> `codex/quiet-index-refresh-cache-labels`
+
+Tracking issue: https://github.com/mcpp-community/mcpp/issues/90
+
+## Scope
+
+This document tracks the mcpp-side fixes found while validating `mcpp build`
+against the `xlings` project.
+
+The current work is intentionally limited to build-tool behavior:
+
+- make automatic package-index refresh quiet from the mcpp user's perspective;
+- make index freshness use a reliable mcpp-owned timestamp marker;
+- make dependency cache status use canonical dependency identities;
+- keep local xlings validation as the integration proof.
+
+## Findings
+
+### 1. Auto-refresh leaks xlings update output
+
+`mcpp build` calls `ensure_index_fresh()` when a project has version-source
+dependencies. That path currently calls `xlings update` with `quiet=false`.
+
+Observed output:
+
+```text
+Updating package index (auto-refresh)
+[1/7] awesome::/home/speak/.mcpp/registry/data/xim-index-repos/...
+...
+index updated
+```
+
+The `[N/M] awesome::...` lines are xlings internals. mcpp users should only see
+the mcpp-level status line unless they explicitly run a verbose/manual index
+update command.
+
+### 2. Freshness check uses an unstable directory mtime
+
+`is_index_fresh()` currently checks:
+
+```text
+~/.mcpp/registry/data/mcpplibs/pkgs
+```
+
+Local evidence showed:
+
+```text
+mcpplibs/pkgs             2026-05-31 01:55:40
+mcpplibs/.git/FETCH_HEAD  2026-05-31 04:31:24
+xim-indexrepos.json       2026-05-31 04:31:27
+```
+
+So `xlings update` can refresh the repository without updating the `pkgs/`
+directory mtime. Once the TTL expires, every full `prepare_build()` can decide
+that the index is stale again.
+
+### 3. Dependency status labels can say `Compiling` for cached deps
+
+For xlings:
+
+```toml
+[dependencies.mcpplibs]
+xpkg = "0.0.41"
+tinyhttps = "0.2.3"
+```
+
+The UI prints dependency names as `mcpplibs.xpkg` and `mcpplibs.tinyhttps`.
+The cache hit label is currently built from the dependency package's own
+`mcpp.toml` name. For tinyhttps that manifest uses:
+
+```toml
+namespace = "mcpplibs"
+name = "tinyhttps"
+version = "0.2.3"
+```
+
+The cache directory is therefore:
+
+```text
+~/.mcpp/bmi/<fingerprint>/deps/mcpplibs/tinyhttps@0.2.3
+```
+
+The UI compares `tinyhttps` against `mcpplibs.tinyhttps`, so it can print
+`Compiling mcpplibs.tinyhttps` even when the cache entry exists.
+
+### 4. libxpkg 0.0.41 has stale embedded mcpp metadata
+
+The installed `mcpplibs.xpkg@0.0.41` archive contains:
+
+```toml
+name = "xpkg"
+version = "0.0.39"
+```
+
+This causes mcpp to cache the resolved package as:
+
+```text
+deps/mcpplibs/xpkg@0.0.39
+```
+
+while the consumer dependency remains `mcpplibs.xpkg v0.0.41`.
+
+## Implementation Plan
+
+- [x] Add focused regression coverage for default-index refresh quietness.
+- [x] Add a reliable mcpp-owned index freshness marker after successful update.
+- [x] Make automatic refresh call `update_index(..., quiet=true)`.
+- [x] Keep explicit/manual index update output available for diagnostics.
+- [x] Canonicalize dependency identity used for cache-hit labels.
+- [x] Avoid using stale embedded package version as the user-facing resolved
+      dependency version when the index resolution already knows the requested
+      version.
+- [x] Validate with the local xlings checkout using the new mcpp binary.
+- [ ] Push a draft PR and use it as the multi-commit checkpoint.
+
+## Verification Plan
+
+- [x] Run targeted unit/e2e coverage in mcpp.
+- [x] Build mcpp itself.
+- [x] Run `mcpp build` in `/home/speak/test/tmp/xlings` with the new binary.
+- [x] Confirm auto-refresh no longer prints xlings `[N/M] index::path` lines.
+- [x] Confirm repeated xlings full prepare does not refresh the index again
+      while the marker is inside TTL.
+- [x] Confirm cached dependencies display as `Cached` when their artifacts are
+      staged.
+- [ ] Record CI status on the PR.
+
+## Dynamic Notes
+
+- `mcpp build` has a 0.01s fast path when `build.ninja` is newer than source
+  files; the noisy path happens when full `prepare_build()` runs.
+- A no-change `ninja -C target/... -n` in the local xlings checkout reported
+  `ninja: no work to do`, so the status-line issue is partly UI/cache identity
+  rather than always an actual compiler invocation.
+- Added regression tests:
+  - `tests/unit/test_xlings.cpp` now requires `.mcpp-index-updated` for a
+    fresh default index.
+  - `tests/e2e/53_namespaced_cache_label.sh` verifies quiet auto-refresh,
+    marker creation, and canonical `Cached compat.widget v1.0.0` output.
+- Local mcpp verification:
+  - `mcpp test -- --gtest_filter=XlingsIndexFreshness.*` passed; the command
+    built and ran all 16 test binaries, with `test_xlings` covering the filter.
+  - `mcpp build --no-cache` passed and produced
+    `target/x86_64-linux-gnu/4d24c8b57fdbbbb4/bin/mcpp`.
+  - `MCPP=.../bin/mcpp bash tests/e2e/49_bmi_cache_nested_custom_index.sh`
+    passed.
+  - `MCPP=.../bin/mcpp bash tests/e2e/52_local_path_namespaced_index.sh`
+    passed.
+  - `MCPP=.../bin/mcpp bash tests/e2e/53_namespaced_cache_label.sh` passed.
+- Local xlings verification with the new mcpp binary:
+  - First `build --print-fingerprint`: exit `0`, displayed only
+    `Updating package index (auto-refresh)` with no xlings `[N/M]` lines.
+  - Second `build --print-fingerprint`: exit `0`, no index refresh line, and
+    `mcpplibs.tinyhttps` / `mcpplibs.xpkg` displayed as `Cached`.
+  - Marker was written at
+    `~/.mcpp/registry/data/mcpplibs/.mcpp-index-updated`.

src/cli.cppm

@@ -1514,11 +1514,16 @@ prepare_build(bool print_fingerprint,
     // unique_ptr is not load-bearing for liveness — it's a leftover from
     // an earlier design and harmless).
     std::vector<std::unique_ptr<mcpp::manifest::Manifest>> dep_manifests;
-    std::vector<std::string> dep_cache_indices;
     auto cache_index_name = [](std::string_view ns) {
         if (ns.empty()) return std::string(mcpp::pm::kDefaultNamespace);
         return std::string(ns);
     };
+    struct DepCacheIdentity {
+        std::string indexName;
+        std::string packageName;
+        std::string version;
+    };
+    std::vector<DepCacheIdentity> dep_cache_identities;
 
     struct ResolvedKey {
         std::string ns;
@@ -2049,7 +2054,11 @@ prepare_build(bool print_fingerprint,
 
                     dep_manifests.push_back(
                         std::make_unique<mcpp::manifest::Manifest>(std::move(stagedManifest)));
-                    dep_cache_indices.push_back(cache_index_name(key.ns));
+                    dep_cache_identities.push_back({
+                        .indexName   = cache_index_name(key.ns),
+                        .packageName = mangled,
+                        .version     = spec.version,
+                    });
                     packages.push_back({secStage, *dep_manifests.back()});
                     auto added = propagateIncludeDirs(secStage, *dep_manifests.back());
 
@@ -2134,6 +2143,8 @@ prepare_build(bool print_fingerprint,
 
                 it->second.version            = *merged;
                 it->second.includeDirsAdded   = std::move(added);
+                if (it->second.depIndex < dep_cache_identities.size())
+                    dep_cache_identities[it->second.depIndex].version = *merged;
 
                 // Walk the *new* manifest's deps so their constraints feed
                 // future merges. Already-resolved children dedup via the
@@ -2274,7 +2285,13 @@ prepare_build(bool print_fingerprint,
         // by depIndex (the SemVer merger needs to overwrite the slot).
         dep_manifests.push_back(
             std::make_unique<mcpp::manifest::Manifest>(std::move(*dep_manifest)));
-        dep_cache_indices.push_back(cache_index_name(key.ns));
+        dep_cache_identities.push_back({
+            .indexName   = cache_index_name(key.ns),
+            .packageName = name,
+            .version     = sourceKind == "version"
+                ? spec.version
+                : dep_manifests.back()->package.version,
+        });
         packages.push_back({dep_root, *dep_manifests.back()});
 
         // Record this dep as resolved so future encounters of the same
@@ -2433,8 +2450,17 @@ prepare_build(bool print_fingerprint,
         };
         for (std::size_t i = 1; i < packages.size(); ++i) {  // skip [0] = main
             const auto& pkgRoot   = packages[i];
-            const auto& depName   = pkgRoot.manifest.package.name;
-            const auto& depVer    = pkgRoot.manifest.package.version;
+            const auto* depIdent  = i - 1 < dep_cache_identities.size()
+                ? &dep_cache_identities[i - 1]
+                : nullptr;
+            const auto fallbackName = pkgRoot.manifest.package.namespace_.empty()
+                ? pkgRoot.manifest.package.name
+                : std::format("{}.{}", pkgRoot.manifest.package.namespace_,
+                              pkgRoot.manifest.package.name);
+            const auto& depName   = depIdent ? depIdent->packageName : fallbackName;
+            const auto& depVer    = depIdent && !depIdent->version.empty()
+                ? depIdent->version
+                : pkgRoot.manifest.package.version;
 
             // Find this dep's spec from the consumer manifest to know
             // if it's path-based or version-based.
@@ -2455,8 +2481,8 @@ prepare_build(bool print_fingerprint,
             mcpp::bmi_cache::CacheKey key {
                 .mcppHome    = (*cfg2)->mcppHome,
                 .fingerprint = fp.hex,
-                .indexName   = i - 1 < dep_cache_indices.size()
-                    ? dep_cache_indices[i - 1]
+                .indexName   = depIdent
+                    ? depIdent->indexName
                     : (*cfg2)->defaultIndex,
                 .packageName = depName,
                 .version     = depVer,

src/xlings.cppm

@@ -270,6 +270,34 @@ void print_status(std::string_view verb, std::string_view msg) {
     }
 }
 
+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 default_index_refresh_marker(const Env& env) {
+    return default_index_dir(env) / ".mcpp-index-updated";
+}
+
+void mark_default_index_refreshed(const Env& env) {
+    if (!env.projectDir.empty()) return;
+    if (!std::filesystem::exists(default_index_pkgs_dir(env))) return;
+
+    std::error_code ec;
+    std::filesystem::create_directories(default_index_dir(env), ec);
+    auto marker = default_index_refresh_marker(env);
+    {
+        std::ofstream os(marker, std::ios::trunc);
+        if (!os) return;
+        os << "ok\n";
+    }
+    std::filesystem::last_write_time(
+        marker, std::filesystem::file_time_type::clock::now(), ec);
+}
+
 void write_file(const std::filesystem::path& p, std::string_view content) {
     std::error_code ec;
     std::filesystem::create_directories(p.parent_path(), ec);
@@ -932,10 +960,13 @@ void ensure_ninja(const Env& env, bool quiet,
 
 bool is_index_fresh(const Env& env, std::int64_t ttlSeconds) {
     std::error_code ec;
-    auto pkgsDir = paths::index_data(env) / "mcpplibs" / "pkgs";
+    auto pkgsDir = default_index_pkgs_dir(env);
     if (!std::filesystem::exists(pkgsDir)) return false;
 
-    auto newest = std::filesystem::last_write_time(pkgsDir, ec);
+    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;
 
     // Check TTL
@@ -946,17 +977,19 @@ bool is_index_fresh(const Env& env, std::int64_t ttlSeconds) {
 
 int update_index(const Env& env, bool quiet) {
     std::string cmd = build_command_prefix(env) + " update 2>&1";
-    return mcpp::platform::process::run_streaming(cmd,
+    int rc = mcpp::platform::process::run_streaming(cmd,
         [quiet](std::string_view line) {
             if (!quiet) std::println("{}", line);
         });
+    if (rc == 0) mark_default_index_refreshed(env);
+    return rc;
 }
 
 void ensure_index_fresh(const Env& env, std::int64_t ttlSeconds, bool quiet) {
     if (is_index_fresh(env, ttlSeconds)) return;
     if (!quiet)
         print_status("Updating", "package index (auto-refresh)");
-    update_index(env, quiet);
+    update_index(env, /*quiet=*/true);
 }
 
 } // namespace mcpp::xlings