fix(pm): explain exact index route misses

Author: speak-agent

src/pm/commands.cppm

@@ -249,6 +249,10 @@ inline int cmd_add(const mcpplibs::cmdline::ParsedArgs& parsed) {
                 hint += "\n  hint: `mcpp index update` if it was published "
                         "recently";
             }
+            if (!selector.candidates.empty()) {
+                hint += "\n  route: " +
+                    route.describe(selector.candidates.front().namespace_);
+            }
             mcpp::ui::error(std::format(
                 "package '{}' not found in any configured index\n  tried: {}{}",
                 canonicalSelector, detail::format_tried(selector.candidates),

src/pm/index_route.cppm

@@ -59,6 +59,11 @@ struct IndexRoute {
     bool lazy_git(std::string_view ns) const;
     // Can a miss in this namespace be taken as proof of absence?
     bool authoritative_for(std::string_view ns) const;
+    // Privacy-safe route state for a failed exact lookup.  This deliberately
+    // omits filesystem paths: CI and user diagnostics need to distinguish a
+    // missing declaration from a missing local checkout without publishing
+    // workstation-specific locations.
+    std::string describe(std::string_view ns) const;
     // Read the descriptor for one coordinate through the right transport.
     std::optional<std::string> read(const DependencyCoordinate& coord) const;
 };
@@ -134,6 +139,35 @@ bool IndexRoute::authoritative_for(std::string_view ns) const {
     return ns.starts_with(std::string(kDefaultNamespace) + ".");
 }
 
+std::string IndexRoute::describe(std::string_view ns) const {
+    auto* idx = find_for_ns(ns);
+    if (!idx) {
+        return std::format(
+            "builtin index for namespace '{}': registry {}",
+            ns, cfg ? "available" : "unavailable");
+    }
+    if (idx->is_local()) {
+        const auto root = mcpp::config::resolve_project_index_path(
+            projectRoot, *idx);
+        std::error_code ec;
+        const bool rootPresent = std::filesystem::is_directory(root, ec);
+        ec.clear();
+        const bool pkgsPresent =
+            std::filesystem::is_directory(root / "pkgs", ec);
+        const auto label = idx->name.empty() ? std::string(ns) : idx->name;
+        return std::format(
+            "local index '{}': root {}, pkgs {}", label,
+            rootPresent ? "present" : "absent",
+            pkgsPresent ? "present" : "absent");
+    }
+    if (idx->is_builtin()) {
+        return std::format(
+            "builtin index '{}': registry {}", idx->name,
+            cfg ? "available" : "unavailable");
+    }
+    return std::format("git index '{}': checkout pending", idx->name);
+}
+
 std::optional<std::string>
 IndexRoute::read(const DependencyCoordinate& coord) const {
     auto* idx = find_for_ns(coord.namespace_);

tests/e2e/12_add_command.sh

@@ -193,6 +193,10 @@ diff -q "$TMP/before" mcpp.toml || { cat mcpp.toml; echo "mcpp.toml mutated for
 # (11) Same for an explicitly-namespaced miss in a readable index.
 err=$("$MCPP" add acme.nope@1.0.0 2>&1) && { echo "expected error for missing acme package"; exit 1; }
 [[ "$err" == *"(acme, nope)"* ]] || { echo "wrong error: $err"; exit 1; }
+[[ "$err" == *"route: local index 'acme': root present, pkgs present"* ]] || {
+    echo "missing privacy-safe local-index route state: $err"
+    exit 1
+}
 diff -q "$TMP/before" mcpp.toml || { cat mcpp.toml; echo "mcpp.toml mutated for missing package"; exit 1; }
 
 # (12) A namespace no readable index covers cannot be refuted, so the add goes

tests/unit/test_pm_index_route.cpp

@@ -64,6 +64,26 @@ TEST(PmIndexRoute, LocalPathIndexIsAuthoritative) {
     EXPECT_TRUE(route.authoritative_for("acme"));
 }
 
+TEST(PmIndexRoute, RouteDescriptionDoesNotExposeItsLocalPath) {
+    LocalIndex idx("diagnostic-privacy");
+    auto indices = local_map(idx);
+    mcpp::pm::IndexRoute route{ &indices, "/nowhere", nullptr };
+
+    const auto description = route.describe("acme");
+    EXPECT_EQ(description, "local index 'acme': root present, pkgs present");
+    EXPECT_EQ(description.find(idx.root.string()), std::string::npos);
+}
+
+TEST(PmIndexRoute, RouteDescriptionDistinguishesAMissingLocalRoot) {
+    mcpp::pm::IndexMap indices;
+    indices["acme"] = mcpp::pm::IndexSpec{
+        .name = "acme", .path = "missing-local-index" };
+    mcpp::pm::IndexRoute route{ &indices, "/nowhere", nullptr };
+
+    EXPECT_EQ(route.describe("acme"),
+              "local index 'acme': root absent, pkgs absent");
+}
+
 // The regression behind #305/#307: a dotted selector is one exact NAMESPACE
 // PATH, so it resolves through the coordinate the manifest parser derives. Probing the
 // literal short name can never match — `package.name` is a single atomic
@@ -202,6 +222,8 @@ version = "0.1.0"
               (root / "index").lexically_normal());
 
     mcpp::pm::IndexRoute route{ &indices, root / "member", nullptr };
+    EXPECT_EQ(route.describe("acme"),
+              "local index 'acme': root present, pkgs present");
     auto selector = mcpp::pm::resolve_dependency_selector("acme.util");
     auto found = mcpp::pm::lookup_descriptor(route, selector.candidates);
     ASSERT_TRUE(found.hit.has_value());