Merge branch 'main' into discord-rpc

Author: Pickysaurus

CHANGELOG.md

@@ -1,3 +1,46 @@
+# v0.14.3 2025-07-30
+This release adds search to the Library and enables creating collections. We also worked on adding support for the Epic Games Store version of Cyberpunk 2077; however, due to some problems with the 2.3 update, we've delayed this feature to a future release. 
+
+## Create Collections
+You can now organise your installed mods into collections in the left menu, allowing you to set up groups of mods that you can quickly toggle on or off. Simply click the new option below "My Mods" to get started. 
+
+![An animation showing the process of creating a new collection in the app.](https://staticdelivery.nexusmods.com/mods/2295/images/26/26-1753777005-5560856.gif)
+
+From the Library page, you can select which Collection to add mods to. The newest collection will be the default option. 
+
+![An animation showing how to add multiple mods to a specific collection from the Library.](https://staticdelivery.nexusmods.com/mods/2295/images/26/26-1753777011-1671552141.gif)
+
+In future versions, we will enable sharing your collections on Nexus Mods and editing collections you have downloaded from the website. 
+
+**Note: Uploading collections to Nexus Mods is disabled by default in this release. You can enable it in the Experimental Settings, but use it at your own risk.**
+
+## Library Search
+One of the most requested features from community feedback was the ability to search installed mods. We've added this to the Library section and will be including it on other relevant pages in a future release. 
+
+![The Library filtered by the term "better" show results.](./docs/changelog-assets/90ea236a6c44e03555f00d8d155eb881.webp)
+
+## More Features
+* The app will now load the latest game version data every 30 minutes in the background.
+
+## Technical Changes
+* Added validation to app settings to prevent bad values from being saved.
+* Collection metadata will now refresh each time the page is loaded in the app. 
+* Improve error reporting for the Nexus Mods API requests.
+
+## Bug Fixes
+* Fixed a bug which prevented the app from properly recognising GOG DLCs.
+* Fixed an exception that would often appear when viewing External Changes.
+* Improved the error reporting around "Missing archive" errors to provide more useful information that will help fix it. 
+
+## Known Issues
+* Once a collection created by the user is removed from the app, it can no longer be edited, even if it was exported to the website.
+* Exported collections do not include a valid version number.
+* The game version is not checked when adding a collection, meaning you can install outdated mods without being warned. 
+* The sort order for some columns does not work as expected.
+* The table header sorting and active tab states are not saved and are reset each time the view is loaded.
+* When deleting the second-to-last editable collection, an error message will show. This can be ignored. 
+
+
 # v0.13.4 2025-07-02
 This release includes the ability to change your storage location, new game artwork and lots of bug fixes.
 

docs/changelog-assets/90ea236a6c44e03555f00d8d155eb881.webp

@@ -0,0 +1,140 @@
+# Jobs System
+
+## Overview
+
+The Jobs system in NexusMods.App is how long-running background tasks are spawned.
+
+These feature progress tracking, cancellation support, and error handling.
+
+Examples of jobs include downloading files and installations.
+
+## Architecture
+
+The Jobs system is built around several key components that work together to provide a comprehensive task management solution:
+
+```mermaid
+graph TB
+    subgraph "Job States"
+        Created[Created]
+        Running[Running]
+        Paused[Paused]
+        Completed[Completed]
+        Cancelled[Cancelled]
+        Failed[Failed]
+    end
+    
+    %% Job lifecycle
+    Created --> Running
+    Running --> Paused
+    Paused --> Running
+    Running --> Completed
+    Running --> Cancelled
+    Running --> Failed
+    Paused --> Cancelled
+```
+
+```mermaid
+graph LR
+    subgraph "Job Creation & Usage"
+        User[User Code] --> |creates| IJobDefinitionWithStart
+        IJobDefinitionWithStart --> |passed to via 'Begin'| JobMonitor
+        JobMonitor --> |creates| JobContext
+        JobMonitor --> |returns| JobTask
+        JobTask --> |returned to| User
+        JobTask --> |wraps| JobContext
+        JobContext --> |contains and cancels using| JobGroup["JobGroup<br/>(with cancellation token)"]
+        JobContext --> |calls StartAsync on| IJobDefinitionWithStart
+    end
+```
+
+!!! note "JobGroup instances are created internally via JobGroupCreator"
+
+    But that class is currently effectively unused.
+
+## Core Components
+
+### IJobDefinition
+
+The base interface for all job definitions. Job definitions describe what work needs to be done and contain any parameters needed for execution.
+
+```csharp
+public interface IJobDefinition;
+
+public interface IJobDefinition<TResultType> : IJobDefinition
+    where TResultType : notnull;
+```
+
+### IJobDefinitionWithStart
+
+A specialized job definition that includes its own execution logic via the `StartAsync` method:
+
+```csharp
+public interface IJobDefinitionWithStart<in TParent, TResultType> : IJobDefinition<TResultType>
+    where TParent : IJobDefinition<TResultType>
+    where TResultType : notnull
+{
+    ValueTask<TResultType> StartAsync(IJobContext<TParent> context);
+}
+```
+
+### IJobMonitor
+
+The central component that manages job execution, tracking, and lifecycle:
+
+```csharp
+public interface IJobMonitor
+{
+    // Start a job with external task logic
+    IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(
+        TJobType job, 
+        Func<IJobContext<TJobType>, ValueTask<TResultType>> task);
+    
+    // Start a self-executing job
+    IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(TJobType job);
+    
+    // Job management
+    void Cancel(JobId jobId);
+    void CancelGroup(IJobGroup group);
+    void CancelAll();
+    
+    // Observability
+    ReadOnlyObservableCollection<IJob> Jobs { get; }
+    IObservable<IChangeSet<IJob, JobId>> GetObservableChangeSet<TJob>();
+}
+```
+
+### IJobContext
+
+Provides the execution context for jobs, including progress reporting and cancellation support:
+
+```csharp
+public interface IJobContext<out TJobDefinition> : IJobContext 
+    where TJobDefinition: IJobDefinition
+{
+    TJobDefinition Definition { get; }
+    Task YieldAsync();
+    CancellationToken CancellationToken { get; }
+    IJobMonitor Monitor { get; }
+    IJobGroup Group { get; }
+    
+    void SetPercent<TVal>(TVal current, TVal max);
+    void SetRateOfProgress(double rate);
+}
+```
+
+### IJobGroup
+
+Groups related jobs together for batch operations and shared cancellation:
+
+```csharp
+public interface IJobGroup : IReadOnlyCollection<IJob>
+{
+    CancellationToken CancellationToken { get; }
+    void Cancel();
+    bool IsCancelled { get; }
+}
+```
+
+## Usage Examples
+
+**📋 [View All Job Examples - (in `src/Examples/Jobs`)](https://github.com/Nexus-Mods/NexusMods.App/tree/main/src/Examples/Jobs)**

docs/developers/development-guidelines/JobsSystem.md

@@ -112,6 +112,7 @@ nav:
         - UI Coding Guidelines: developers/development-guidelines/UICodingGuidelines.md
         - UI Styling Guidelines: developers/development-guidelines/UIStylingGuidelines.md
         - Using Workspaces: developers/development-guidelines/UsingWorkspaces.md
+        - Jobs System: developers/development-guidelines/JobsSystem.md
         - Diagnostics: developers/development-guidelines/Diagnostics.md
         - Processes:
           - Release Process: developers/development-guidelines/Processes/ReleaseProcess.md

mkdocs.yml

@@ -12,9 +12,13 @@
         <PackageReference Include="Avalonia.Controls.DataGrid" />
         <PackageReference Include="Avalonia.Svg.Skia" />
         <PackageReference Include="Projektanker.Icons.Avalonia.MaterialDesign" />
+        <PackageReference Include="NexusMods.Paths" />
+        <PackageReference Include="Microsoft.Extensions.Logging" />
     </ItemGroup>
 
     <ItemGroup>
+        <ProjectReference Include="..\NexusMods.Jobs\NexusMods.Jobs.csproj" />
+        <ProjectReference Include="..\NexusMods.FileExtractor\NexusMods.FileExtractor.csproj" />
         <ProjectReference Include="..\NexusMods.Abstractions.Settings\NexusMods.Abstractions.Settings.csproj" />
         <ProjectReference Include="..\NexusMods.App.UI\NexusMods.App.UI.csproj" />
         <ProjectReference Include="..\NexusMods.App\NexusMods.App.csproj" />

src/Examples/Examples.csproj

@@ -0,0 +1,98 @@
+# Jobs Examples
+
+This folder contains examples demonstrating how to use the NexusMods.App Jobs
+system for background task management with progress tracking, cancellation
+support, and error handling.
+
+## Usage Examples
+
+### Creating a Simple Job Definition
+
+Simple job definitions (using the `Begin` method with a lambda) are used when
+you want to handle the execution logic in the same method where you call
+`Begin`.
+
+The job definition serves as context/data, while the actual work is done in the
+lambda callback right where you need it.
+
+See [**SimpleJobDefinitionExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/SimpleJobDefinitionExample.cs).
+
+### Self-Executing Job
+
+A job with entirely self-contained logic/context, to fire and (sometimes)
+forget.
+
+The fields you store in the job definition are effectively method parameters
+passed in to run the job.
+
+See [**SelfExecutingJobExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/SelfExecutingJobExample.cs).
+
+## Best Practices
+
+### Cancellation and Error Handling
+
+Always call `context.YieldAsync()` around expensive, time-consuming code to
+support job cancellation.
+
+**For Job Callers:** Use `JobMonitor.Cancel()`, `CancelGroup()`, or
+`CancelAll()` to cancel jobs.
+
+**For Job Implementations:** Use `YieldAsync()` to check for cancellation at
+natural breakpoints.
+
+**Jobs Cancelling Themselves:** Jobs can cancel themselves using
+`context.CancelAndThrow()` when conditions require termination.
+
+**Interactive Cancellation:** Jobs may interact with external components (like
+UI dialogs) that can cancel. Propagate external `OperationCanceledException`
+through `context.CancelAndThrow()`.
+
+See [**CancellationExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/BestPractices/CancellationExample.cs) and
+[**InteractiveCancellationExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/BestPractices/InteractiveCancellationExample.cs).
+
+### Progress Reporting
+
+Use percentage for determinate progress when total work is known. For
+indeterminate progress, use `Size.One` as maximum to avoid division by zero.
+
+See [**DeterminateProgressExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/BestPractices/DeterminateProgressExample.cs)
+and [**IndeterminateProgressExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/BestPractices/IndeterminateProgressExample.cs).
+
+### Factory Methods
+
+Often you want to fire a job right away after it is created. In this case,
+make `Create()` helper functions to encapsulate the job creation and job
+starting logic as one.
+
+Factory methods encapsulate dependency injection and job configuration,
+creating reusable job creation patterns.
+
+See [**FactoryMethodExample.cs**](../../../tests/NexusMods.Jobs.Tests/Examples/BestPractices/FactoryMethodExample.cs).
+
+## General Guidelines
+
+- Use `record` types for job definitions as they should not mutate parameters
+- Handle resource cleanup within job execution logic before completion
+- Follow existing codebase patterns
+
+## Caveats
+
+!!! warning "Job Disposal Not Implemented"
+
+    While jobs can implement `IDisposable` or `IAsyncDisposable`, they're not
+    actually disposed by the job system. If you need resource cleanup, handle
+    it within the job's execution logic before completion.
+
+## Common Patterns
+
+- Use `record` types for job definitions as they should not mutate their
+  parameters
+- Call `context.YieldAsync()` around expensive operations to support
+  cancellation
+- Use `SetPercent()` with `Size.From()` for progress reporting
+- Access job data through `context.Definition`
+
+## Related Documentation
+
+For comprehensive architecture details and core interfaces, see the
+[Jobs System Documentation](../../../docs/developers/development-guidelines/JobsSystem.md).

src/Examples/Jobs/README.md

@@ -8,7 +8,7 @@ public class Program
 {
     [STAThread]
     public static int Main() => 0;
-
+    
     /// <summary>
     /// Don't Delete this method. It's used by the Avalonia Designer.
     /// </summary>

src/Examples/Program.cs

@@ -9,6 +9,13 @@ and [Using Workspaces](https://nexus-mods.github.io/NexusMods.App/development-gu
 
 - [Diagnostics](./Diagnostics/README.md)
   - [Using Diagnostics](./Diagnostics/UsingDiagnostics.cs)
+- [Jobs](./Jobs/README.md)
+  - [Simple Job Definition Example](./Jobs/SimpleJobDefinitionExample.cs)
+  - [Self-Executing Job Example](./Jobs/SelfExecutingJobExample.cs)
+  - [Best Practices](./Jobs/BestPractices/README.md)
+    - [Cancellation Examples](./Jobs/BestPractices/CancellationExample.cs)
+    - [Progress Reporting Examples](./Jobs/BestPractices/ProgressReportingExample.cs)
+    - [Factory Method Examples](./Jobs/BestPractices/FactoryMethodExample.cs)
 - [Workspaces](./Workspaces/README.md)
     - [Querying Windows and Workspaces](./Workspaces/001-querying-windows-and-workspaces.cs)
     - [Opening new Pages in a Workspace](./Workspaces/002-opening-new-pages.cs)

src/Examples/README.md

@@ -1,5 +1,8 @@
+using System.Collections.Frozen;
 using JetBrains.Annotations;
+using NexusMods.Abstractions.GameLocators;
 using NexusMods.Abstractions.Loadouts;
+using NexusMods.Abstractions.Loadouts.Synchronizers;
 
 namespace NexusMods.Abstractions.Diagnostics.Emitters;
 
@@ -16,5 +19,14 @@ public interface ILoadoutDiagnosticEmitter : IDiagnosticEmitter
     /// <summary>
     /// Diagnoses a loadout and creates instances of <see cref="Diagnostic"/>.
     /// </summary>
+    [Obsolete("To be replaced with the overload that takes in the sync tree")]
     IAsyncEnumerable<Diagnostic> Diagnose(Loadout.ReadOnly loadout, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Diagnoses a loadout and creates instances of <see cref="Diagnostic"/>.
+    /// </summary>
+    IAsyncEnumerable<Diagnostic> Diagnose(Loadout.ReadOnly loadout, FrozenDictionary<GamePath, SyncNode> syncTree, CancellationToken cancellationToken)
+    {
+        return Diagnose(loadout, cancellationToken);
+    }
 }

src/NexusMods.Abstractions.Games.Diagnostics/Emitters/ILoadoutDiagnosticEmitter.cs

@@ -15,7 +15,6 @@ IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(TJobType job, Func<
         where TJobType : IJobDefinition<TResultType>
         where TResultType : notnull;
 
-
     /// <summary>
     /// Starts a job given the job definition.
     /// </summary>
@@ -38,6 +37,11 @@ IJobTask<TJobType, TResultType> Begin<TJobType, TResultType>(TJobType job)
     /// </summary>
     void Cancel(JobId jobId);
 
+    /// <summary>
+    /// Cancels a specific job by its task
+    /// </summary>
+    void Cancel(IJobTask jobTask);
+    
     /// <summary>
     /// Cancels all jobs in the specified group
     /// </summary>