feat(index): project-level [indices] artifact/source with pin-forces-git rule (#269)

IndexSpec gains artifact/source, parsed from both mcpp.toml and
config.toml [indices] long forms; ensure_project_index_dir passes them
through to the project seed. artifact_applicable() encodes the design
rule: rev/tag/branch pins (and local path) force git because the artifact
channel only tracks the latest pointer — a declared-but-inapplicable
artifact warns instead of silently syncing the wrong revision.

Author: Sunrisepeak

src/config.cppm

@@ -596,6 +596,8 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
                 if (auto it = sub.find("tag");    it != sub.end() && it->second.is_string()) spec.tag    = it->second.as_string();
                 if (auto it = sub.find("branch"); it != sub.end() && it->second.is_string()) spec.branch = it->second.as_string();
                 if (auto it = sub.find("path");   it != sub.end() && it->second.is_string()) spec.path   = it->second.as_string();
+                if (auto it = sub.find("artifact"); it != sub.end() && it->second.is_string()) spec.artifact = it->second.as_string();
+                if (auto it = sub.find("source");   it != sub.end() && it->second.is_string()) spec.source   = it->second.as_string();
             }
             if (!spec.url.empty() || !spec.path.empty())
                 cfg.indices[k] = std::move(spec);
@@ -731,7 +733,18 @@ bool ensure_project_index_dir(
             customRepos.push_back({ name, source.generic_string(), "", "" });
             continue;
         }
-        customRepos.push_back({ name, spec.url, "", "" });
+        // #269: pass a declared artifact source through to xlings unless a
+        // rev/tag/branch pin forces git (the artifact channel only tracks
+        // the latest published pointer).
+        mcpp::xlings::SeedRepo repo{ name, spec.url, "", "" };
+        if (spec.artifact_applicable()) {
+            repo.artifact = spec.artifact;
+            repo.source   = spec.source;
+        } else if (!spec.artifact.empty()) {
+            std::println("warning: [indices].{}: artifact source ignored "
+                         "(rev/tag/branch/path pins force git)", name);
+        }
+        customRepos.push_back(std::move(repo));
     }
 
     // NOTE: the official global `xim` index is deliberately NOT injected into

src/manifest/toml.cppm

@@ -1146,6 +1146,8 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
                 if (auto it = sub.find("tag");    it != sub.end() && it->second.is_string()) spec.tag    = it->second.as_string();
                 if (auto it = sub.find("branch"); it != sub.end() && it->second.is_string()) spec.branch = it->second.as_string();
                 if (auto it = sub.find("path");   it != sub.end() && it->second.is_string()) spec.path   = it->second.as_string();
+                if (auto it = sub.find("artifact"); it != sub.end() && it->second.is_string()) spec.artifact = it->second.as_string();
+                if (auto it = sub.find("source");   it != sub.end() && it->second.is_string()) spec.source   = it->second.as_string();
                 if (spec.url.empty() && spec.path.empty()) {
                     return std::unexpected(error(origin, std::format(
                         "[indices].{} must specify 'url' or 'path'", k)));

src/pm/index_spec.cppm

@@ -18,9 +18,18 @@ struct IndexSpec {
     std::string              tag;       // git tag
     std::string              branch;    // git branch
     std::filesystem::path    path;      // local path (takes priority over url)
+    std::string              artifact;  // optional artifact source base (xlings >= 0.4.68, #269)
+    std::string              source;    // optional "auto" | "artifact" | "git"
 
     bool is_local()   const { return !path.empty(); }
     bool is_pinned()  const { return !rev.empty(); }
+    // The artifact channel only tracks the latest published pointer; any
+    // rev/tag/branch pin (and local path) therefore forces git and the
+    // artifact declaration is ignored (with a warning at seed time).
+    bool artifact_applicable() const {
+        return !artifact.empty() && rev.empty() && tag.empty()
+            && branch.empty() && path.empty();
+    }
     // R6: `name == "mcpplibs"` alone used to mean "builtin" unconditionally,
     // which was correct while the only way to reach that name was the
     // literal `[indices] mcpplibs = { url = ..., rev = ... }` pin form (still

tests/unit/test_manifest.cpp

@@ -2601,3 +2601,30 @@ mcpp = {
     EXPECT_EQ(host->modules.sources, nativeTarget->modules.sources);
     EXPECT_EQ(host->buildConfig.cxxflags, nativeTarget->buildConfig.cxxflags);
 }
+
+TEST(Manifest, IndicesArtifactAndSourceParsedAndPinSuppresses) {
+    // #269: [indices] entries may declare an xlings >= 0.4.68 artifact
+    // source. rev/tag/branch pins force git (the artifact channel only
+    // tracks the latest pointer), which artifact_applicable() encodes.
+    constexpr auto src = R"(
+[package]
+name = "hello"
+version = "0.1.0"
+[language]
+standard = "c++23"
+[modules]
+sources = ["src/**/*.cppm"]
+[indices]
+fast   = { url = "https://example.com/i.git", artifact = "https://example.com/res/i", source = "auto" }
+pinned = { url = "https://example.com/i.git", artifact = "https://example.com/res/i", rev = "abc123" }
+)";
+    auto m = mcpp::manifest::parse_string(src);
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    auto& fast = m->indices.at("fast");
+    EXPECT_EQ(fast.artifact, "https://example.com/res/i");
+    EXPECT_EQ(fast.source, "auto");
+    EXPECT_TRUE(fast.artifact_applicable());
+    auto& pinned = m->indices.at("pinned");
+    EXPECT_EQ(pinned.artifact, "https://example.com/res/i");
+    EXPECT_FALSE(pinned.artifact_applicable());
+}