feat: infrastructure for publisher catalogs and enhanced acquisition tracking

GenHub/Directory.Packages.props

@@ -54,4 +54,4 @@
     <PackageVersion Include="HeyRed.ImageSharp.Heif" Version="2.1.3" />
     <PackageVersion Include="LibHeif.Native" Version="1.15.1" />
   </ItemGroup>
-</Project>
+</Project>

GenHub/GenHub.Core/Constants/AppUpdateConstants.cs

@@ -153,6 +153,33 @@ public static class AppUpdateConstants
         "3. Launch the installed version (will be in %LOCALAPPDATA%\\GenHub)\n\n" +
         "Update available: v{1}";
 
+    /// <summary>
+    /// Default update notification title.
+    /// </summary>
+    public const string UpdateNotificationTitle = "Update Available";
+
+    /// <summary>
+    /// Update available notification message format.
+    /// {0}: Version.
+    /// </summary>
+    public const string UpdateAvailableMessageFormat = "A new version ({0}) is available.";
+
+    /// <summary>
+    /// Branch/Artifact update notification title.
+    /// </summary>
+    public const string BranchUpdateNotificationTitle = "Branch Update Available";
+
+    /// <summary>
+    /// Branch update available notification message format.
+    /// {0}: Version, {1}: Branch.
+    /// </summary>
+    public const string BranchUpdateAvailableMessageFormat = "A new build ({0}) is available on branch '{1}'.";
+
+    /// <summary>
+    /// "View Updates" action text.
+    /// </summary>
+    public const string ViewUpdatesAction = "View Updates";
+
     /// <summary>
     /// Delay before exit after applying update (5 seconds).
     /// </summary>

GenHub/GenHub.Core/Constants/InfoConstants.cs

@@ -17,6 +17,26 @@ public static class InfoConstants
     /// </summary>
     public const string FaqDefaultLanguage = "en";
 
+    /// <summary>
+    /// Section ID for the quickstart guide.
+    /// </summary>
+    public const string QuickstartSectionId = "quickstart";
+
+    /// <summary>
+    /// Module name for the GenHub Guide.
+    /// </summary>
+    public const string ModuleGuide = "GenHub Guide";
+
+    /// <summary>
+    /// Module name for Zero Hour.
+    /// </summary>
+    public const string ModuleZeroHour = "Zero Hour";
+
+    /// <summary>
+    /// Module name for GeneralsOnline.
+    /// </summary>
+    public const string ModuleGeneralsOnline = "GeneralsOnline";
+
     /// <summary>
     /// The list of supported languages for the FAQ.
     /// </summary>

GenHub/GenHub.Core/Constants/ModDBParserConstants.cs

@@ -245,4 +245,18 @@ public static class ModDBParserConstants
 
     /// <summary>Pattern for games URLs.</summary>
     public const string GamesUrlPattern = "/games/";
+
+    // ===== Mod Detail Page Selectors =====
+
+    /// <summary>Selector for the downloads section on mod pages.</summary>
+    public const string DownloadsSectionSelector = "#downloads, .downloads, .files";
+
+    /// <summary>Selector for the addons section on mod pages.</summary>
+    public const string AddonsSectionSelector = "#addons, .addons";
+
+    /// <summary>Selector for the tabs/navigation on mod pages.</summary>
+    public const string TabsSelector = ".tabs, .navigation, nav";
+
+    /// <summary>Selector for individual tab links.</summary>
+    public const string TabLinkSelector = "a[href*='/downloads'], a[href*='/addons']";
 }

GenHub/GenHub.Core/Extensions/ContentAcquisitionProgressExtensions.cs

@@ -0,0 +1,76 @@
+using GenHub.Core.Models.Content;
+using GenHub.Core.Models.Enums;
+
+namespace GenHub.Core.Extensions;
+
+/// <summary>
+/// Extension methods for ContentAcquisitionProgress.
+/// </summary>
+public static class ContentAcquisitionProgressExtensions
+{
+    /// <summary>
+    /// Formats a user-friendly progress status message with stage indicators.
+    /// </summary>
+    /// <param name="progress">The progress object to format.</param>
+    /// <returns>A formatted progress status string.</returns>
+    public static string FormatProgressStatus(this ContentAcquisitionProgress progress)
+    {
+        ArgumentNullException.ThrowIfNull(progress);
+
+        // Use the new staged progress format if available
+        if (progress.TotalStages > 0 && progress.CurrentStage > 0)
+        {
+            var stagePart = $"{progress.CurrentStage}/{progress.TotalStages}";
+            var description = !string.IsNullOrEmpty(progress.StageDescription)
+                ? progress.StageDescription
+                : progress.CurrentOperation;
+
+            // Add percentage for stages that have measurable progress
+            var percentPart = progress.StageProgress > 0 && progress.StageProgress < 100
+                ? $" ({progress.StageProgress:F0}%)"
+                : string.Empty;
+
+            // Add bottleneck indicator if applicable
+            var bottleneckPart = progress.IsBottleneck && !string.IsNullOrEmpty(progress.BottleneckReason)
+                ? $" - {progress.BottleneckReason}"
+                : string.Empty;
+
+            // Add file count if processing multiple files
+            var filesPart = progress.TotalFiles > 1
+                ? $" [{progress.FilesProcessed}/{progress.TotalFiles}]"
+                : string.Empty;
+
+            return $"{stagePart} - {description}{percentPart}{filesPart}{bottleneckPart}";
+        }
+
+        // Fallback to phase-based format
+        var phaseName = progress.Phase switch
+        {
+            ContentAcquisitionPhase.Downloading => "Downloading",
+            ContentAcquisitionPhase.Extracting => "Extracting",
+            ContentAcquisitionPhase.Copying => "Copying",
+            ContentAcquisitionPhase.ValidatingManifest => "Validating manifest",
+            ContentAcquisitionPhase.ValidatingFiles => "Validating files",
+            ContentAcquisitionPhase.Delivering => "Installing",
+            ContentAcquisitionPhase.Completed => "Complete",
+            _ => "Processing",
+        };
+
+        if (!string.IsNullOrEmpty(progress.CurrentOperation))
+        {
+            return $"{phaseName}: {progress.CurrentOperation}";
+        }
+
+        var percentText = progress.ProgressPercentage > 0 ? $"{progress.ProgressPercentage:F0}%" : string.Empty;
+
+        if (progress.TotalFiles > 0)
+        {
+            var phasePercent = progress.TotalFiles > 0
+                ? (int)((double)progress.FilesProcessed / progress.TotalFiles * 100)
+                : 0;
+            return $"{phaseName}: {progress.FilesProcessed}/{progress.TotalFiles} files ({phasePercent}%)";
+        }
+
+        return !string.IsNullOrEmpty(percentText) ? $"{phaseName}... {percentText}" : $"{phaseName}...";
+    }
+}

GenHub/GenHub.Core/Extensions/ContentTypeExtensions.cs

@@ -74,7 +74,8 @@ public static bool IsStandalone(this ContentType contentType)
         {
             ContentType.ModdingTool => true,
             ContentType.Executable => true,
+            ContentType.Addon => true,
             _ => false,
         };
     }
-}
+}

GenHub/GenHub.Core/Interfaces/Providers/IPublisherCatalogParser.cs

@@ -0,0 +1,33 @@
+using GenHub.Core.Models.Providers;
+using GenHub.Core.Models.Results;
+
+namespace GenHub.Core.Interfaces.Providers;
+
+/// <summary>
+/// Parses publisher catalog JSON into structured models.
+/// </summary>
+public interface IPublisherCatalogParser
+{
+    /// <summary>
+    /// Parses a catalog from JSON content.
+    /// </summary>
+    /// <param name="catalogJson">The raw JSON content of the catalog.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The parsed catalog or an error.</returns>
+    Task<OperationResult<PublisherCatalog>> ParseCatalogAsync(string catalogJson, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Validates that a catalog conforms to the expected schema version.
+    /// </summary>
+    /// <param name="catalog">The catalog to validate.</param>
+    /// <returns>Validation result with any errors.</returns>
+    OperationResult<bool> ValidateCatalog(PublisherCatalog catalog);
+
+    /// <summary>
+    /// Verifies the catalog signature if present.
+    /// </summary>
+    /// <param name="catalogJson">The raw JSON content.</param>
+    /// <param name="catalog">The parsed catalog with signature field.</param>
+    /// <returns>True if signature is valid or not required.</returns>
+    bool VerifySignature(string catalogJson, PublisherCatalog catalog);
+}

GenHub/GenHub.Core/Interfaces/Providers/IPublisherCatalogRefreshService.cs

@@ -0,0 +1,24 @@
+using GenHub.Core.Models.Results;
+
+namespace GenHub.Core.Interfaces.Providers;
+
+/// <summary>
+/// Service for refreshing subscribed publisher catalogs.
+/// </summary>
+public interface IPublisherCatalogRefreshService
+{
+    /// <summary>
+    /// Refreshes all subscribed catalogs.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Summary of the refresh operation.</returns>
+    Task<OperationResult<bool>> RefreshAllAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Refreshes a specific publisher's catalog.
+    /// </summary>
+    /// <param name="publisherId">The publisher identifier.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if refreshed, false otherwise.</returns>
+    Task<OperationResult<bool>> RefreshPublisherAsync(string publisherId, CancellationToken cancellationToken = default);
+}

GenHub/GenHub.Core/Interfaces/Providers/IPublisherSubscriptionStore.cs

@@ -0,0 +1,68 @@
+using GenHub.Core.Models.Enums;
+using GenHub.Core.Models.Providers;
+using GenHub.Core.Models.Results;
+
+namespace GenHub.Core.Interfaces.Providers;
+
+/// <summary>
+/// Manages user subscriptions to publisher catalogs.
+/// Subscriptions are stored locally and enable discovery of creator content.
+/// </summary>
+public interface IPublisherSubscriptionStore
+{
+    /// <summary>
+    /// Gets all active publisher subscriptions.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>List of active subscriptions.</returns>
+    Task<OperationResult<IEnumerable<PublisherSubscription>>> GetSubscriptionsAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets a specific subscription by publisher ID.
+    /// </summary>
+    /// <param name="publisherId">The publisher identifier.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The subscription if found, null otherwise.</returns>
+    Task<OperationResult<PublisherSubscription?>> GetSubscriptionAsync(string publisherId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Adds a new publisher subscription.
+    /// </summary>
+    /// <param name="subscription">The subscription to add.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Operation result indicating success or failure.</returns>
+    Task<OperationResult<bool>> AddSubscriptionAsync(PublisherSubscription subscription, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a publisher subscription.
+    /// </summary>
+    /// <param name="publisherId">The publisher identifier to remove.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Operation result indicating success or failure.</returns>
+    Task<OperationResult<bool>> RemoveSubscriptionAsync(string publisherId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Updates an existing subscription.
+    /// </summary>
+    /// <param name="subscription">The updated subscription data.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Operation result indicating success or failure.</returns>
+    Task<OperationResult<bool>> UpdateSubscriptionAsync(PublisherSubscription subscription, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks if a publisher subscription exists.
+    /// </summary>
+    /// <param name="publisherId">The publisher identifier.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if subscribed, false otherwise.</returns>
+    Task<OperationResult<bool>> IsSubscribedAsync(string publisherId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Updates the trust level for a publisher.
+    /// </summary>
+    /// <param name="publisherId">The publisher identifier.</param>
+    /// <param name="trustLevel">The new trust level.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Operation result indicating success or failure.</returns>
+    Task<OperationResult<bool>> UpdateTrustLevelAsync(string publisherId, TrustLevel trustLevel, CancellationToken cancellationToken = default);
+}

GenHub/GenHub.Core/Interfaces/Providers/IVersionSelector.cs

@@ -0,0 +1,31 @@
+using GenHub.Core.Models.Providers;
+
+namespace GenHub.Core.Interfaces.Providers;
+
+/// <summary>
+/// Filters content releases based on version display policy.
+/// </summary>
+public interface IVersionSelector
+{
+    /// <summary>
+    /// Selects releases based on the specified policy.
+    /// </summary>
+    /// <param name="releases">All available releases.</param>
+    /// <param name="policy">The version selection policy.</param>
+    /// <returns>Filtered releases according to policy.</returns>
+    IEnumerable<ContentRelease> SelectReleases(IEnumerable<ContentRelease> releases, VersionPolicy policy);
+
+    /// <summary>
+    /// Gets the latest stable release from a collection.
+    /// </summary>
+    /// <param name="releases">All available releases.</param>
+    /// <returns>The latest stable release, or null if none exist.</returns>
+    ContentRelease? GetLatestStable(IEnumerable<ContentRelease> releases);
+
+    /// <summary>
+    /// Gets the latest release (including prereleases) from a collection.
+    /// </summary>
+    /// <param name="releases">All available releases.</param>
+    /// <returns>The latest release, or null if none exist.</returns>
+    ContentRelease? GetLatest(IEnumerable<ContentRelease> releases);
+}

GenHub/GenHub.Core/Interfaces/Providers/VersionPolicy.cs

@@ -0,0 +1,22 @@
+namespace GenHub.Core.Interfaces.Providers;
+
+/// <summary>
+/// Defines the version filtering policy for content display.
+/// </summary>
+public enum VersionPolicy
+{
+    /// <summary>
+    /// Show only the latest stable release (default).
+    /// </summary>
+    LatestStableOnly,
+
+    /// <summary>
+    /// Show all versions including older releases.
+    /// </summary>
+    AllVersions,
+
+    /// <summary>
+    /// Include prerelease versions in addition to stable releases.
+    /// </summary>
+    IncludePrereleases,
+}

GenHub/GenHub.Core/Messages/CloseContentDetailMessage.cs

@@ -0,0 +1,10 @@
+using CommunityToolkit.Mvvm.Messaging.Messages;
+
+namespace GenHub.Core.Messages;
+
+/// <summary>
+/// Message sent when a user wants to close the content details view.
+/// </summary>
+public class CloseContentDetailMessage() : ValueChangedMessage<bool>(true)
+{
+}

GenHub/GenHub.Core/Messages/ClosePublisherDetailsMessage.cs

@@ -0,0 +1,10 @@
+using CommunityToolkit.Mvvm.Messaging.Messages;
+
+namespace GenHub.Core.Messages;
+
+/// <summary>
+/// Message sent when a user wants to close the publisher details view and return to the dashboard.
+/// </summary>
+public class ClosePublisherDetailsMessage() : ValueChangedMessage<bool>(true)
+{
+}

GenHub/GenHub.Core/Messages/OpenPublisherDetailsMessage.cs

@@ -0,0 +1,11 @@
+using CommunityToolkit.Mvvm.Messaging.Messages;
+
+namespace GenHub.Core.Messages;
+
+/// <summary>
+/// Message sent when a user wants to view details for a specific publisher.
+/// </summary>
+/// <param name="publisherId">The ID of the publisher to view.</param>
+public class OpenPublisherDetailsMessage(string publisherId) : ValueChangedMessage<string>(publisherId)
+{
+}