Merge pull request #2077 from thomhurst/feature/plugin-system

feat: Add plugin system for extensibility

Author: thomhurst

src/ModularPipelines/Exceptions/PluginInitializationException.cs

@@ -0,0 +1,53 @@
+namespace ModularPipelines.Exceptions;
+
+/// <summary>
+/// Exception thrown when a plugin fails to initialize during pipeline setup.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This exception is thrown when a plugin's <c>ConfigureServices</c> or <c>ConfigurePipeline</c>
+/// method throws an exception. Plugin initialization failures are fatal and stop the pipeline
+/// from executing.
+/// </para>
+/// <para><b>Example:</b></para>
+/// <code>
+/// try
+/// {
+///     await pipelineBuilder.ExecutePipelineAsync();
+/// }
+/// catch (PluginInitializationException ex)
+/// {
+///     Console.WriteLine($"Plugin '{ex.PluginName}' failed: {ex.Message}");
+/// }
+/// </code>
+/// </remarks>
+public class PluginInitializationException : PipelineException
+{
+    /// <summary>
+    /// Gets the name of the plugin that failed to initialize.
+    /// </summary>
+    public string PluginName { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PluginInitializationException"/> class.
+    /// </summary>
+    /// <param name="message">The message that describes the error.</param>
+    /// <param name="pluginName">The name of the plugin that failed.</param>
+    public PluginInitializationException(string message, string pluginName)
+        : base(message)
+    {
+        PluginName = pluginName;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PluginInitializationException"/> class.
+    /// </summary>
+    /// <param name="message">The message that describes the error.</param>
+    /// <param name="pluginName">The name of the plugin that failed.</param>
+    /// <param name="innerException">The exception that is the cause of the current exception.</param>
+    public PluginInitializationException(string message, string pluginName, Exception innerException)
+        : base(message, innerException)
+    {
+        PluginName = pluginName;
+    }
+}

src/ModularPipelines/PipelineBuilder.cs

@@ -8,6 +8,7 @@
 using ModularPipelines.Engine;
 using ModularPipelines.Exceptions;
 using ModularPipelines.Options;
+using ModularPipelines.Plugins;
 using ModularPipelines.Validation;
 using Vertical.SpectreLogger.Options;
 
@@ -243,17 +244,23 @@ private async Task<IPipeline> BuildPipelineAsync()
     {
         LoadModularPipelineAssembliesIfNotLoadedYet();
 
+        // Apply plugin configuration to the builder (modules, hooks, options)
+        PluginIntegration.ApplyPluginConfiguration(this);
+
         // Configure the host with our collected configuration
         _hostBuilder.ConfigureAppConfiguration((_, config) =>
         {
             config.AddConfiguration(_configuration);
         });
 
-        // Configure services: first the core services, then user services
+        // Configure services: first the core services, then plugins, then user services
         _hostBuilder.ConfigureServices((_, services) =>
         {
             DependencyInjectionSetup.Initialize(services);
 
+            // Apply plugin services after core services
+            PluginIntegration.ApplyPluginServices(services);
+
             // Configure pipeline options
             services.Configure<PipelineOptions>(opts =>
             {

src/ModularPipelines/Plugins/IModularPipelinesPlugin.cs

@@ -0,0 +1,35 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ModularPipelines.Plugins;
+
+/// <summary>
+/// Defines a plugin that can extend ModularPipelines functionality.
+/// Plugins self-register via [ModuleInitializer] methods calling <see cref="PluginRegistry.Register"/>.
+/// </summary>
+public interface IModularPipelinesPlugin
+{
+    /// <summary>
+    /// Gets the unique name identifying this plugin.
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Gets the execution priority. Lower values run first. Default is 0.
+    /// </summary>
+    int Priority => 0;
+
+    /// <summary>
+    /// Configure services in the DI container.
+    /// Called during host setup, before the pipeline is built.
+    /// </summary>
+    /// <param name="services">The service collection to configure.</param>
+    void ConfigureServices(IServiceCollection services);
+
+    /// <summary>
+    /// Configure the pipeline builder.
+    /// Register hooks, modules, and other pipeline components.
+    /// Called after services are configured, before execution.
+    /// </summary>
+    /// <param name="pipelineBuilder">The pipeline builder to configure.</param>
+    void ConfigurePipeline(PipelineBuilder pipelineBuilder);
+}

src/ModularPipelines/Plugins/PluginIntegration.cs

@@ -0,0 +1,58 @@
+using Microsoft.Extensions.DependencyInjection;
+using ModularPipelines.Exceptions;
+
+namespace ModularPipelines.Plugins;
+
+/// <summary>
+/// Handles integration of registered plugins into the pipeline setup process.
+/// </summary>
+internal static class PluginIntegration
+{
+    /// <summary>
+    /// Applies all registered plugins' service configuration.
+    /// Called during DI setup, before the host is built.
+    /// </summary>
+    /// <param name="services">The service collection to configure.</param>
+    /// <exception cref="PluginInitializationException">Thrown if a plugin fails to configure services.</exception>
+    public static void ApplyPluginServices(IServiceCollection services)
+    {
+        foreach (var plugin in PluginRegistry.Plugins)
+        {
+            try
+            {
+                plugin.ConfigureServices(services);
+            }
+            catch (Exception ex)
+            {
+                throw new PluginInitializationException(
+                    $"Plugin '{plugin.Name}' failed during ConfigureServices: {ex.Message}",
+                    plugin.Name,
+                    ex);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Applies all registered plugins' pipeline configuration.
+    /// Called during pipeline building, after services are configured.
+    /// </summary>
+    /// <param name="pipelineBuilder">The pipeline builder to configure.</param>
+    /// <exception cref="PluginInitializationException">Thrown if a plugin fails to configure the pipeline.</exception>
+    public static void ApplyPluginConfiguration(PipelineBuilder pipelineBuilder)
+    {
+        foreach (var plugin in PluginRegistry.Plugins)
+        {
+            try
+            {
+                plugin.ConfigurePipeline(pipelineBuilder);
+            }
+            catch (Exception ex)
+            {
+                throw new PluginInitializationException(
+                    $"Plugin '{plugin.Name}' failed during ConfigurePipeline: {ex.Message}",
+                    plugin.Name,
+                    ex);
+            }
+        }
+    }
+}

src/ModularPipelines/Plugins/PluginRegistry.cs

@@ -0,0 +1,38 @@
+namespace ModularPipelines.Plugins;
+
+/// <summary>
+/// Static registry for ModularPipelines plugins.
+/// Plugins register themselves via [ModuleInitializer] methods during assembly load.
+/// </summary>
+public static class PluginRegistry
+{
+    private static readonly List<IModularPipelinesPlugin> Registered = [];
+
+    /// <summary>
+    /// Gets all registered plugins, ordered by priority (ascending).
+    /// </summary>
+    public static IReadOnlyList<IModularPipelinesPlugin> Plugins =>
+        Registered.OrderBy(p => p.Priority).ToList();
+
+    /// <summary>
+    /// Registers a plugin. Call this from a [ModuleInitializer] method.
+    /// </summary>
+    /// <param name="plugin">The plugin to register.</param>
+    /// <exception cref="InvalidOperationException">Thrown if a plugin with the same name is already registered.</exception>
+    public static void Register(IModularPipelinesPlugin plugin)
+    {
+        ArgumentNullException.ThrowIfNull(plugin);
+
+        if (Registered.Any(p => p.Name == plugin.Name))
+        {
+            throw new InvalidOperationException($"Plugin '{plugin.Name}' is already registered.");
+        }
+
+        Registered.Add(plugin);
+    }
+
+    /// <summary>
+    /// Clears all registered plugins. For testing purposes only.
+    /// </summary>
+    internal static void Clear() => Registered.Clear();
+}

src/ModularPipelines/Plugins/PluginTestHelper.cs

@@ -0,0 +1,50 @@
+namespace ModularPipelines.Plugins;
+
+/// <summary>
+/// Helper class for testing plugins in isolation.
+/// </summary>
+public static class PluginTestHelper
+{
+    /// <summary>
+    /// Creates an isolated plugin registry scope for testing.
+    /// Clears all registered plugins and restores them when disposed.
+    /// </summary>
+    /// <returns>A disposable scope that restores the original plugins when disposed.</returns>
+    /// <example>
+    /// <code>
+    /// [Test]
+    /// public async Task MyPlugin_Should_Register_Services()
+    /// {
+    ///     using var _ = PluginTestHelper.IsolatedRegistry();
+    ///     PluginRegistry.Register(new MyTestPlugin());
+    ///
+    ///     // Test plugin behavior in isolation...
+    /// }
+    /// </code>
+    /// </example>
+    public static IDisposable IsolatedRegistry()
+    {
+        var snapshot = PluginRegistry.Plugins.ToList();
+        PluginRegistry.Clear();
+        return new RegistryRestorer(snapshot);
+    }
+
+    private sealed class RegistryRestorer : IDisposable
+    {
+        private readonly List<IModularPipelinesPlugin> _snapshot;
+
+        public RegistryRestorer(List<IModularPipelinesPlugin> snapshot)
+        {
+            _snapshot = snapshot;
+        }
+
+        public void Dispose()
+        {
+            PluginRegistry.Clear();
+            foreach (var plugin in _snapshot)
+            {
+                PluginRegistry.Register(plugin);
+            }
+        }
+    }
+}