feat: implement CSVDiscoverer and catalog registry models

GenHub/GenHub.Core/Constants/ConfigurationKeys.cs

@@ -106,4 +106,16 @@ public static class ConfigurationKeys
     /// Configuration key for application data path.
     /// </summary>
     public const string AppDataPath = "GenHub:AppDataPath";
+
+    // CSV Catalog configuration keys
+
+    /// <summary>
+    /// Configuration key for the CSV catalog index file path.
+    /// </summary>
+    public const string CsvCatalogIndexPath = "GenHub:CsvCatalog:IndexFilePath";
+
+    /// <summary>
+    /// Configuration key for the CSV validation catalogs fallback.
+    /// </summary>
+    public const string CsvValidationCatalogs = "GenHub:CsvCatalog:ValidationCatalogs";
 }

GenHub/GenHub.Core/Interfaces/Common/IAppConfiguration.cs

@@ -1,3 +1,4 @@
+using GenHub.Core.Models.Content;
 using GenHub.Core.Models.Enums;
 using Microsoft.Extensions.Logging;
 
@@ -81,4 +82,10 @@ public interface IAppConfiguration
     /// <summary>Gets the maximum allowed download buffer size in bytes.</summary>
     /// <returns>The maximum buffer size in bytes.</returns>
     int GetMaxDownloadBufferSizeBytes();
+
+    /// <summary>
+    /// Gets the CSV catalog configuration.
+    /// </summary>
+    /// <returns>The CSV catalog configuration.</returns>
+    CsvCatalogConfiguration GetCsvCatalogConfiguration();
 }

GenHub/GenHub.Core/Interfaces/Common/IConfigurationProviderService.cs

@@ -1,4 +1,5 @@
 using GenHub.Core.Models.Common;
+using GenHub.Core.Models.Content;
 using GenHub.Core.Models.Enums;
 using GenHub.Core.Models.Storage;
 
@@ -155,4 +156,10 @@ public interface IConfigurationProviderService
     /// </summary>
     /// <returns>The logs directory path.</returns>
     string GetLogsPath();
+
+    /// <summary>
+    /// Gets the CSV catalog configuration.
+    /// </summary>
+    /// <returns>The CSV catalog configuration.</returns>
+    CsvCatalogConfiguration GetCsvCatalogConfiguration();
 }

GenHub/GenHub.Core/Models/Content/CsvCatalogConfiguration.cs

@@ -0,0 +1,53 @@
+using System.Collections.Generic;
+
+namespace GenHub.Core.Models.Content;
+
+/// <summary>
+/// Configuration for CSV Catalog discovery.
+/// Binds to "CsvValidationCatalogs" and "CsvCatalogIndexPath" in configuration.
+/// </summary>
+public class CsvCatalogConfiguration
+{
+    /// <summary>
+    /// Gets or sets the list of fallback validation catalogs defined in configuration.
+    /// Used when index.json cannot be reached.
+    /// </summary>
+    public List<CsvValidationCatalog> CsvValidationCatalogs { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the path to the index.json file relative to the docs directory.
+    /// </summary>
+    public string IndexFilePath { get; set; } = "docs/GameInstallationFilesRegistry/index.json";
+}
+
+/// <summary>
+/// Represents a CSV catalog defined in appsettings.json.
+/// Matches the structure of CsvCatalogRegistryEntry but optimized for config binding.
+/// </summary>
+public class CsvValidationCatalog
+{
+    /// <summary>
+    /// Gets or sets the URL to the CSV file.
+    /// </summary>
+    public string Url { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the game type.
+    /// </summary>
+    public string GameType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the version string.
+    /// </summary>
+    public string Version { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the supported languages.
+    /// </summary>
+    public List<string> SupportedLanguages { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the file count.
+    /// </summary>
+    public int FileCount { get; set; }
+}

GenHub/GenHub.Core/Models/Content/CsvCatalogRegistryIndex.cs

@@ -0,0 +1,57 @@
+using System;
+using System.Collections.Generic;
+
+namespace GenHub.Core.Models.Content;
+
+/// <summary>
+/// Index of available CSV catalog registries.
+/// Represents the structure of the docs/GameInstallationFilesRegistry/index.json file.
+/// </summary>
+public class CsvCatalogRegistryIndex
+{
+    /// <summary>
+    /// Gets or sets the schema version.
+    /// </summary>
+    public int Version { get; set; } = 1;
+
+    /// <summary>
+    /// Gets or sets when the index was last updated.
+    /// </summary>
+    public DateTime LastUpdatedAt { get; set; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// Gets or sets the list of available catalog entries.
+    /// </summary>
+    public List<CsvCatalogRegistryEntry> Entries { get; set; } = [];
+}
+
+/// <summary>
+/// Represents a single CSV catalog entry in the registry.
+/// </summary>
+public class CsvCatalogRegistryEntry
+{
+    /// <summary>
+    /// Gets or sets the URL to the CSV file.
+    /// </summary>
+    public string Url { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the game type (e.g., "Generals", "ZeroHour").
+    /// </summary>
+    public string GameType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the game version (e.g., "1.08", "1.04").
+    /// </summary>
+    public string Version { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the list of supported languages in this CSV.
+    /// </summary>
+    public List<string> SupportedLanguages { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the optional file count in the CSV.
+    /// </summary>
+    public int? FileCount { get; set; }
+}

GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Content/CSVDiscovererTests.cs

@@ -0,0 +1,95 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using FluentAssertions;
+using GenHub.Core.Interfaces.Common;
+using GenHub.Core.Models.Content;
+using GenHub.Core.Models.Enums;
+using GenHub.Core.Models.Results.Content;
+using GenHub.Features.Content.Services.ContentDiscoverers;
+using Microsoft.Extensions.Logging;
+using Moq;
+using Xunit;
+
+namespace GenHub.Tests.Core.Features.Content;
+
+// the whole file is made by AI
+
+/// <summary>
+/// Unit tests for <see cref="CSVDiscoverer"/>.
+/// </summary>
+public class CSVDiscovererTests
+{
+    /// <summary>
+    /// Verifies that <see cref="CSVDiscoverer.DiscoverAsync"/> returns a valid result when querying for Generals.
+    /// </summary>
+    /// <returns>A task representing the asynchronous test operation.</returns>
+    [Fact]
+    public async Task DiscoverAsync_WithGeneralsQuery_ReturnsValidResult()
+    {
+        // Arrange
+        var config = new CsvCatalogConfiguration
+        {
+            IndexFilePath = "non-existent-index.json",
+            CsvValidationCatalogs = new List<CsvValidationCatalog>
+            {
+                new CsvValidationCatalog
+                {
+                    Url = "https://example.com/generals.csv",
+                    GameType = "Generals",
+                    Version = "1.08",
+                    SupportedLanguages = new List<string> { "en" },
+                    FileCount = 100,
+                },
+            },
+        };
+
+        var mockConfig = new Mock<IConfigurationProviderService>();
+        mockConfig.Setup(o => o.GetCsvCatalogConfiguration()).Returns(config);
+
+        var discoverer = new CSVDiscoverer(
+            Mock.Of<ILogger<CSVDiscoverer>>(),
+            mockConfig.Object);
+
+        var query = new ContentSearchQuery { TargetGame = GameType.Generals };
+
+        // Act
+        var result = await discoverer.DiscoverAsync(query);
+
+        // Assert
+        result.Success.Should().BeTrue();
+        result.Data.Should().NotBeNull();
+        result.Data!.Items.Should().NotBeEmpty();
+        result.Data.Items.First().ResolverMetadata.Should().ContainKey("csvUrl");
+        result.Data.Items.First().ResolverMetadata["csvUrl"].Should().Be("https://example.com/generals.csv");
+    }
+
+    /// <summary>
+    /// Verifies that <see cref="CSVDiscoverer.DiscoverAsync"/> returns an empty result when the content type is not GameInstallation.
+    /// </summary>
+    /// <returns>A task representing the asynchronous test operation.</returns>
+    [Fact]
+    public async Task DiscoverAsync_WithNonGameInstallationContentType_ReturnsEmptyResult()
+    {
+        // Arrange
+        var mockConfig = new Mock<IConfigurationProviderService>();
+        mockConfig.Setup(o => o.GetCsvCatalogConfiguration()).Returns(new CsvCatalogConfiguration());
+
+        var discoverer = new CSVDiscoverer(
+            Mock.Of<ILogger<CSVDiscoverer>>(),
+            mockConfig.Object);
+
+        var query = new ContentSearchQuery { ContentType = GenHub.Core.Models.Enums.ContentType.Map };
+
+        // Act
+        var result = await discoverer.DiscoverAsync(query);
+
+        // Assert
+        result.Success.Should().BeTrue();
+        result.Data.Should().NotBeNull();
+        result.Data!.Items.Should().BeEmpty();
+    }
+
+}
+

GenHub/GenHub/Common/Services/AppConfiguration.cs

@@ -3,6 +3,7 @@
 using GenHub.Core.Constants;
 using GenHub.Core.Interfaces.Common;
 using GenHub.Core.Models.Enums;
+using GenHub.Core.Models.Content;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
 
@@ -226,4 +227,10 @@ public string GetConfiguredDataPath()
             ? configured
             : Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), AppConstants.AppName);
     }
+
+    /// <inheritdoc />
+    public CsvCatalogConfiguration GetCsvCatalogConfiguration()
+    {
+        return _configuration?.GetSection("GenHub:CsvCatalog").Get<CsvCatalogConfiguration>() ?? new CsvCatalogConfiguration();
+    }
 }

GenHub/GenHub/Common/Services/ConfigurationProviderService.cs

@@ -5,6 +5,7 @@
 using GenHub.Core.Constants;
 using GenHub.Core.Interfaces.Common;
 using GenHub.Core.Models.Common;
+using GenHub.Core.Models.Content;
 using GenHub.Core.Models.Enums;
 using GenHub.Core.Models.Storage;
 using Microsoft.Extensions.Logging;
@@ -342,6 +343,9 @@ public string GetLogsPath()
             DirectoryNames.Logs.ToLowerInvariant());
     }
 
+    /// <inheritdoc />
+    public CsvCatalogConfiguration GetCsvCatalogConfiguration() => _appConfig.GetCsvCatalogConfiguration();
+
     private void MigrateContentDirectory()
     {
         try