feat(index): per-repo artifact source plumbing — IndexRepo/SeedRepo/toml/template (#269)

IndexRepo gains optional artifact/source; [index.repos.*] parses both keys;
the default template and add_default declare the xlings-res/mcpp-index
artifact base; canonicalize fills it in memory for pre-artifact configs
(source="git" is the opt-out, user-set bases win). seed_xlings_json now
takes SeedRepo spans and emits artifact/source only when set — output for
plain repos stays byte-identical (locked by test). Older xlings (<0.4.68)
ignores both keys.

Author: Sunrisepeak

src/config.cppm

@@ -36,6 +36,8 @@ inline constexpr std::string_view kXlingsPinnedVersion = mcpp::xlings::pinned::k
 struct IndexRepo {
     std::string name;
     std::string url;
+    std::string artifact;   // optional artifact source base (xlings >= 0.4.68, #269)
+    std::string source;     // optional "auto" | "artifact" | "git" ("" = xlings default auto)
 };
 
 // Canonical mcpplibs index coordinates. The index repository moved from the
@@ -375,7 +377,9 @@ home   = ""
 default = "mcpplibs"
 
 [index.repos."mcpplibs"]
-url = "https://github.com/mcpplibs/mcpp-index.git"
+url      = "https://github.com/mcpplibs/mcpp-index.git"
+artifact = "https://github.com/xlings-res/mcpp-index"
+# source = "auto"  # default: artifact first, git fallback; set "git" to force git
 # xlings auto-adds xim / awesome / scode / d2x as defaults.
 
 [cache]
@@ -393,10 +397,11 @@ bool write_default_xlings_json(const std::filesystem::path& path,
                                const std::vector<IndexRepo>& repos,
                                std::string_view mirror_override = {})
 {
-    // Delegate to xlings module. Convert IndexRepo vec to pair span.
-    std::vector<std::pair<std::string,std::string>> pairs;
+    // Delegate to xlings module. Convert IndexRepo vec to SeedRepo span.
+    std::vector<mcpp::xlings::SeedRepo> pairs;
     pairs.reserve(repos.size());
-    for (auto& r : repos) pairs.emplace_back(r.name, r.url);
+    for (auto& r : repos)
+        pairs.push_back({ r.name, r.url, r.artifact, r.source });
     // seed_xlings_json writes to env.home / ".xlings.json", so we
     // construct a temporary Env with home = path.parent_path().
     mcpp::xlings::Env env;
@@ -469,6 +474,12 @@ void canonicalize_legacy_index_names(GlobalConfig& cfg) {
         // repo that happens to be named "mcpp-index" untouched.
         if (r.name == "mcpp-index" && r.url == kMcpplibsIndexUrl)
             r.name = "mcpplibs";
+        // ③ In-memory artifact default for the official index (#269): heals
+        // configs written by pre-artifact templates on every load without
+        // text surgery on user-editable config.toml. `source = "git"` is the
+        // explicit opt-out; a user-set artifact base always wins.
+        if (r.url == kMcpplibsIndexUrl && r.artifact.empty() && r.source != "git")
+            r.artifact = std::string(kMcpplibsIndexArtifact);
         bool duplicate = std::any_of(normalized.begin(), normalized.end(),
             [&](const IndexRepo& existing) {
                 return existing.name == r.name && existing.url == r.url;
@@ -562,7 +573,12 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
             auto& tt = val.as_table();
             auto it = tt.find("url");
             if (it == tt.end() || !it->second.is_string()) continue;
-            cfg.indexRepos.push_back({ name, it->second.as_string() });
+            IndexRepo r{ name, it->second.as_string() };
+            if (auto a = tt.find("artifact"); a != tt.end() && a->second.is_string())
+                r.artifact = a->second.as_string();
+            if (auto s = tt.find("source"); s != tt.end() && s->second.is_string())
+                r.source = s->second.as_string();
+            cfg.indexRepos.push_back(std::move(r));
         }
     }
     // [indices] — new-schema custom index repositories.
@@ -592,11 +608,13 @@ std::expected<GlobalConfig, ConfigError> load_or_init(
     // them ourselves can cause cross-index name conflicts during
     // dependency resolution (e.g. linux-headers existing in both
     // scode and xim). See docs/21 §VII.
-    auto add_default = [&](std::string_view name, std::string_view url) {
+    auto add_default = [&](std::string_view name, std::string_view url,
+                           std::string_view artifact = {}) {
         for (auto& r : cfg.indexRepos) if (r.name == name) return;
-        cfg.indexRepos.push_back({ std::string(name), std::string(url) });
+        cfg.indexRepos.push_back({ std::string(name), std::string(url),
+                                   std::string(artifact), std::string() });
     };
-    add_default("mcpplibs", kMcpplibsIndexUrl);
+    add_default("mcpplibs", kMcpplibsIndexUrl, kMcpplibsIndexArtifact);
     canonicalize_legacy_index_names(cfg);
 
     // 5. Seed registry/.xlings.json if missing; migrate legacy cached
@@ -687,8 +705,10 @@ void print_env(const GlobalConfig& cfg) {
     std::println("Index repos:");
     for (auto& r : cfg.indexRepos) {
         bool isDefault = (r.name == cfg.defaultIndex);
-        std::println("  {} {}{}",
-                     r.name, r.url, isDefault ? "  (default)" : "");
+        std::println("  {} {}{}{}",
+                     r.name, r.url,
+                     r.artifact.empty() ? "" : "  [artifact]",
+                     isDefault ? "  (default)" : "");
     }
 }
 
@@ -701,17 +721,17 @@ bool ensure_project_index_dir(
     // Collect custom non-builtin indices that need xlings project-scope data.
     // Local path indices are also seeded so xlings can create its own
     // project-local repo link and install packages from that index.
-    std::vector<std::pair<std::string,std::string>> customRepos;
+    std::vector<mcpp::xlings::SeedRepo> customRepos;
     for (auto& [name, spec] : indices) {
         if (spec.is_builtin()) continue;
         if (spec.is_local()) {
             auto source = resolve_project_index_path(projectDir, spec);
             std::error_code ec;
             std::filesystem::remove(source / ".xlings-index-cache.json", ec);
-            customRepos.emplace_back(name, source.generic_string());
+            customRepos.push_back({ name, source.generic_string(), "", "" });
             continue;
         }
-        customRepos.emplace_back(name, spec.url);
+        customRepos.push_back({ name, spec.url, "", "" });
     }
 
     // NOTE: the official global `xim` index is deliberately NOT injected into

src/xlings.cppm

@@ -247,8 +247,19 @@ struct ProjectEnv {
     }
 };
 
+// One index_repos entry for seed_xlings_json. `artifact`/`source` are the
+// xlings >= 0.4.68 per-repo artifact-sync fields (#269); empty means "do not
+// emit the key", which keeps pre-artifact output byte-identical and matches
+// xlings' "undeclared = plain git" semantics. Older xlings ignores both keys.
+struct SeedRepo {
+    std::string name;
+    std::string url;
+    std::string artifact;   // artifact source base, e.g. https://github.com/xlings-res/mcpp-index
+    std::string source;     // "auto" | "artifact" | "git"
+};
+
 void seed_xlings_json(const Env& env,
-                      std::span<const std::pair<std::string,std::string>> repos,
+                      std::span<const SeedRepo> repos,
                       std::string_view mirror = "auto",
                       const ProjectEnv& penv = {});
 
@@ -1108,18 +1119,24 @@ int install_direct(const Env& env, std::string_view target, bool quiet) {
 // ─── Sandbox lifecycle ──────────────────────────────────────────────
 
 void seed_xlings_json(const Env& env,
-                      std::span<const std::pair<std::string,std::string>> repos,
+                      std::span<const SeedRepo> repos,
                       std::string_view mirror,
                       const ProjectEnv& penv)
 {
     auto path = env.home / ".xlings.json";
     std::string json = "{\n";
     json += "  \"index_repos\": [\n";
     for (std::size_t i = 0; i < repos.size(); ++i) {
-        json += std::format("    {{ \"name\": \"{}\", \"url\": \"{}\" }}{}\n",
-                            json_escape(repos[i].first),
-                            json_escape(repos[i].second),
-                            i + 1 == repos.size() ? "" : ",");
+        json += std::format("    {{ \"name\": \"{}\", \"url\": \"{}\"",
+                            json_escape(repos[i].name),
+                            json_escape(repos[i].url));
+        if (!repos[i].artifact.empty())
+            json += std::format(", \"artifact\": \"{}\"",
+                                json_escape(repos[i].artifact));
+        if (!repos[i].source.empty())
+            json += std::format(", \"source\": \"{}\"",
+                                json_escape(repos[i].source));
+        json += std::format(" }}{}\n", i + 1 == repos.size() ? "" : ",");
     }
     json += "  ],\n";
     // [xlings] build environment (L-1): materialize deps/workspace/subos/envs

tests/unit/test_config.cpp

@@ -223,3 +223,30 @@ TEST(ConfigIndexMigration, MigrateConfigTomlRewritesOrgUrlIdempotently) {
     EXPECT_EQ(read_all(p), text);
     std::filesystem::remove_all(dir);
 }
+
+TEST(ConfigIndexMigration, CanonicalizeFillsDefaultArtifactForOfficialRepo) {
+    mcpp::config::GlobalConfig cfg;
+    cfg.indexRepos.push_back({ "mcpplibs",
+        std::string(mcpp::config::kMcpplibsIndexUrlLegacy) });
+    mcpp::config::canonicalize_legacy_index_names(cfg);
+    ASSERT_EQ(cfg.indexRepos.size(), 1u);
+    EXPECT_EQ(cfg.indexRepos[0].artifact, mcpp::config::kMcpplibsIndexArtifact);
+}
+
+TEST(ConfigIndexMigration, CanonicalizeRespectsExplicitGitSourceAndCustomArtifact) {
+    mcpp::config::GlobalConfig cfg;
+    mcpp::config::IndexRepo git{ "mcpplibs",
+        std::string(mcpp::config::kMcpplibsIndexUrl) };
+    git.source = "git";
+    cfg.indexRepos.push_back(git);
+    mcpp::config::IndexRepo custom{ "mirror",
+        std::string(mcpp::config::kMcpplibsIndexUrl) };
+    custom.artifact = "https://example.com/my-mirror";
+    cfg.indexRepos.push_back(custom);
+    cfg.indexRepos.push_back({ "other", "https://example.com/other-index.git" });
+    mcpp::config::canonicalize_legacy_index_names(cfg);
+    ASSERT_EQ(cfg.indexRepos.size(), 3u);
+    EXPECT_TRUE(cfg.indexRepos[0].artifact.empty());        // explicit git opt-out
+    EXPECT_EQ(cfg.indexRepos[1].artifact, "https://example.com/my-mirror");
+    EXPECT_TRUE(cfg.indexRepos[2].artifact.empty());        // foreign repo untouched
+}

tests/unit/test_xlings.cpp

@@ -408,3 +408,49 @@ TEST(XlingsHomeTool, FindsPayloadUnderNonXimPrefix) {
 
     std::filesystem::remove_all(tmp);
 }
+
+// ─── seed_xlings_json — per-repo artifact/source emission (#269) ──────
+
+namespace {
+
+std::string read_seeded(const std::filesystem::path& home) {
+    std::stringstream ss;
+    ss << std::ifstream(home / ".xlings.json").rdbuf();
+    return ss.str();
+}
+
+}  // namespace
+
+TEST(XlingsSeed, PlainRepoEmissionIsByteStable) {
+    // Zero-diff gate: repos without artifact/source must serialize exactly
+    // as before the SeedRepo extension.
+    auto dir = make_tempdir("mcpp-seed-plain");
+    mcpp::xlings::Env env;
+    env.home = dir;
+    std::vector<mcpp::xlings::SeedRepo> repos{
+        { "mcpplibs", "https://x.git", "", "" } };
+    mcpp::xlings::seed_xlings_json(env, repos);
+    auto text = read_seeded(dir);
+    EXPECT_NE(text.find(
+        "    { \"name\": \"mcpplibs\", \"url\": \"https://x.git\" }\n"),
+        std::string::npos) << text;
+    EXPECT_EQ(text.find("artifact"), std::string::npos);
+    EXPECT_EQ(text.find("source"), std::string::npos);
+    std::filesystem::remove_all(dir);
+}
+
+TEST(XlingsSeed, ArtifactAndSourceEmittedWhenSet) {
+    auto dir = make_tempdir("mcpp-seed-art");
+    mcpp::xlings::Env env;
+    env.home = dir;
+    std::vector<mcpp::xlings::SeedRepo> repos{
+        { "mcpplibs", "https://x.git",
+          "https://github.com/xlings-res/mcpp-index", "auto" } };
+    mcpp::xlings::seed_xlings_json(env, repos);
+    auto text = read_seeded(dir);
+    EXPECT_NE(text.find(
+        "\"url\": \"https://x.git\", \"artifact\": "
+        "\"https://github.com/xlings-res/mcpp-index\", \"source\": \"auto\""),
+        std::string::npos) << text;
+    std::filesystem::remove_all(dir);
+}