feat: add feature flag module with permissions-like architecture (#28)

* feat: add feature flag module with permissions-like architecture

Add a complete FeatureFlags module that follows the permissions pattern:
modules declare features via IModuleFeatures marker classes, the source
generator auto-discovers them, and a runtime service resolves flag state
with user/role override support.

## Framework (SimpleModule.Core)
- IModuleFeatures marker interface for compile-time feature discovery
- IFeatureFlagService for cross-module runtime checks
- IFeatureFlagRegistry singleton with all known flag definitions
- FeatureFlagRegistryBuilder merging discovered + configured definitions
- EndpointFeatureFlagExtensions with .RequireFeature() endpoint filter
- ConfigureFeatureFlags() added to IModule interface

## Source Generator
- Feature class discovery mirroring permission class pattern
- Diagnostics SM0045-SM0048 (sealed class, naming, duplicates, fields)
- Auto-registration of feature classes and definitions in AddModules()

## Module Implementation
- Contracts: IFeatureFlagContracts, DTOs, events, OverrideType enum
- Entities using Entity<int> base class (auto timestamps, concurrency)
- FeatureFlagService with cached resolution (user > role > global > default)
- FeatureFlagSyncService for startup DB sync with table auto-creation
- FeatureFlagMiddleware injecting flags into Inertia shared data
- Full API endpoints (CRUD flags, overrides, check)
- Admin UI (React) with toggle switches and override management
- useFeatureFlag() React hook for frontend consumption
- Permissions: FeatureFlags.View, FeatureFlags.Manage

## Tests
- 14 unit + integration tests (service logic, endpoint auth, CRUD)
- Playwright e2e smoke + flow tests
- Test infrastructure integration (WebApplicationFactory)

* fix: add FeatureFlags migration and harden middleware error handling

- Add EF Core migration (AddFeatureFlagsModule) to create the
  FeatureFlags and FeatureFlagOverrides tables
- Catch DbException in FeatureFlagMiddleware so a missing or
  unreachable database does not crash the entire request pipeline
  with a 500 — feature flags degrade gracefully instead
- Update HostDbContext model snapshot to include FeatureFlags entities

Author: antosubash

SimpleModule.slnx

@@ -69,6 +69,11 @@
         <Project Path="modules/FileStorage/src/SimpleModule.FileStorage/SimpleModule.FileStorage.csproj" />
         <Project Path="modules/FileStorage/tests/SimpleModule.FileStorage.Tests/SimpleModule.FileStorage.Tests.csproj" />
     </Folder>
+    <Folder Name="/modules/FeatureFlags/">
+        <Project Path="modules/FeatureFlags/src/SimpleModule.FeatureFlags.Contracts/SimpleModule.FeatureFlags.Contracts.csproj" />
+        <Project Path="modules/FeatureFlags/src/SimpleModule.FeatureFlags/SimpleModule.FeatureFlags.csproj" />
+        <Project Path="modules/FeatureFlags/tests/SimpleModule.FeatureFlags.Tests/SimpleModule.FeatureFlags.Tests.csproj" />
+    </Folder>
     <Folder Name="/modules/AuditLogs/">
         <Project Path="modules/AuditLogs/src/SimpleModule.AuditLogs.Contracts/SimpleModule.AuditLogs.Contracts.csproj" />
         <Project Path="modules/AuditLogs/src/SimpleModule.AuditLogs/SimpleModule.AuditLogs.csproj" />

framework/SimpleModule.Core/FeatureFlags/EndpointFeatureFlagExtensions.cs

@@ -0,0 +1,49 @@
+using System.Security.Claims;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace SimpleModule.Core.FeatureFlags;
+
+public static class EndpointFeatureFlagExtensions
+{
+    public static TBuilder RequireFeature<TBuilder>(this TBuilder builder, string featureName)
+        where TBuilder : IEndpointConventionBuilder
+    {
+        builder.AddEndpointFilter(
+            async (context, next) =>
+            {
+                var featureFlagService =
+                    context.HttpContext.RequestServices.GetService<IFeatureFlagService>();
+
+                // If the service is not registered, allow the request (feature enabled by default)
+                if (featureFlagService is null)
+                {
+                    return await next(context);
+                }
+
+                var userId = context.HttpContext.User.FindFirstValue(
+                    ClaimTypes.NameIdentifier
+                );
+                var roles = context
+                    .HttpContext.User.FindAll(ClaimTypes.Role)
+                    .Select(c => c.Value);
+
+                var isEnabled = await featureFlagService.IsEnabledAsync(
+                    featureName,
+                    userId,
+                    roles
+                );
+
+                if (!isEnabled)
+                {
+                    return Results.NotFound();
+                }
+
+                return await next(context);
+            }
+        );
+
+        return builder;
+    }
+}

framework/SimpleModule.Core/FeatureFlags/FeatureFlagBuilder.cs

@@ -0,0 +1,14 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+public sealed class FeatureFlagBuilder : IFeatureFlagBuilder
+{
+    private readonly List<FeatureFlagDefinition> _definitions = [];
+
+    public IFeatureFlagBuilder Add(FeatureFlagDefinition definition)
+    {
+        _definitions.Add(definition);
+        return this;
+    }
+
+    public List<FeatureFlagDefinition> ToList() => [.. _definitions];
+}

framework/SimpleModule.Core/FeatureFlags/FeatureFlagDefinition.cs

@@ -0,0 +1,8 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+public class FeatureFlagDefinition
+{
+    public string Name { get; set; } = string.Empty;
+    public string Description { get; set; } = string.Empty;
+    public bool DefaultEnabled { get; set; }
+}

framework/SimpleModule.Core/FeatureFlags/FeatureFlagRegistry.cs

@@ -0,0 +1,28 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+public sealed class FeatureFlagRegistry : IFeatureFlagRegistry
+{
+    private readonly Dictionary<string, FeatureFlagDefinition> _definitions;
+
+    public FeatureFlagRegistry(
+        HashSet<string> allNames,
+        List<FeatureFlagDefinition> definitions
+    )
+    {
+        // allNames parameter kept for API compatibility with generated code.
+        // Build() already ensures definitions contains entries for all names.
+        _ = allNames;
+        _definitions = definitions.ToDictionary(d => d.Name);
+    }
+
+    public FeatureFlagDefinition? GetDefinition(string name) =>
+        _definitions.GetValueOrDefault(name);
+
+    public IReadOnlyList<FeatureFlagDefinition> GetAllDefinitions() =>
+        _definitions.Values.ToList();
+
+    public bool IsKnownFeature(string name) => _definitions.ContainsKey(name);
+
+    public IReadOnlySet<string> GetAllFeatureNames() =>
+        _definitions.Keys.ToHashSet(StringComparer.Ordinal);
+}

framework/SimpleModule.Core/FeatureFlags/FeatureFlagRegistryBuilder.cs

@@ -0,0 +1,57 @@
+using System.Reflection;
+
+namespace SimpleModule.Core.FeatureFlags;
+
+public sealed class FeatureFlagRegistryBuilder
+{
+    private readonly HashSet<string> _allNames = [];
+    private readonly Dictionary<string, FeatureFlagDefinition> _definitions = new();
+
+    public void AddFeatures<T>()
+        where T : class
+    {
+        var fields = typeof(T)
+            .GetFields(BindingFlags.Public | BindingFlags.Static | BindingFlags.FlattenHierarchy)
+            .Where(f => f.IsLiteral && !f.IsInitOnly && f.FieldType == typeof(string));
+
+        foreach (var field in fields)
+        {
+            var value = (string)field.GetRawConstantValue()!;
+            _allNames.Add(value);
+        }
+    }
+
+    public void AddDefinition(FeatureFlagDefinition definition)
+    {
+        _allNames.Add(definition.Name);
+        _definitions[definition.Name] = definition;
+    }
+
+    public void AddDefinitions(List<FeatureFlagDefinition> definitions)
+    {
+        foreach (var definition in definitions)
+        {
+            AddDefinition(definition);
+        }
+    }
+
+    public FeatureFlagRegistry Build()
+    {
+        // For names discovered via IModuleFeatures but without a definition,
+        // create a default definition (disabled by default).
+        var allDefinitions = new List<FeatureFlagDefinition>();
+        foreach (var name in _allNames)
+        {
+            if (_definitions.TryGetValue(name, out var def))
+            {
+                allDefinitions.Add(def);
+            }
+            else
+            {
+                allDefinitions.Add(new FeatureFlagDefinition { Name = name });
+            }
+        }
+
+        return new FeatureFlagRegistry(_allNames, allDefinitions);
+    }
+}

framework/SimpleModule.Core/FeatureFlags/IFeatureFlagBuilder.cs

@@ -0,0 +1,6 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+public interface IFeatureFlagBuilder
+{
+    IFeatureFlagBuilder Add(FeatureFlagDefinition definition);
+}

framework/SimpleModule.Core/FeatureFlags/IFeatureFlagRegistry.cs

@@ -0,0 +1,9 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+public interface IFeatureFlagRegistry
+{
+    FeatureFlagDefinition? GetDefinition(string name);
+    IReadOnlyList<FeatureFlagDefinition> GetAllDefinitions();
+    bool IsKnownFeature(string name);
+    IReadOnlySet<string> GetAllFeatureNames();
+}

framework/SimpleModule.Core/FeatureFlags/IFeatureFlagService.cs

@@ -0,0 +1,19 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+/// <summary>
+/// Minimal runtime interface for checking feature flag state.
+/// Lives in Core so any module can depend on it without referencing FeatureFlags.Contracts.
+/// </summary>
+public interface IFeatureFlagService
+{
+    Task<bool> IsEnabledAsync(
+        string flagName,
+        string? userId = null,
+        IEnumerable<string>? roles = null
+    );
+
+    Task<Dictionary<string, bool>> GetAllEnabledAsync(
+        string? userId = null,
+        IEnumerable<string>? roles = null
+    );
+}

framework/SimpleModule.Core/FeatureFlags/IModuleFeatures.cs

@@ -0,0 +1,10 @@
+namespace SimpleModule.Core.FeatureFlags;
+
+/// <summary>
+/// Marker interface for feature flag classes. Implementations are auto-discovered
+/// by the source generator and registered with the feature flag registry.
+/// Feature classes must be sealed and contain only public const string fields.
+/// </summary>
+#pragma warning disable CA1040 // Avoid empty interfaces
+public interface IModuleFeatures;
+#pragma warning restore CA1040