@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/dotnet/aspnet-core/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ASP.NET Core Web API
+description: Modern ASP.NET Core patterns for building RESTful APIs.
+metadata:
+  labels: [aspnet, webapi, rest, minimal-api]
+  triggers:
+    files: ['**/*.cs', 'Program.cs']
+    keywords: [WebApplication, MapGet, MapPost, Controller, ApiController]
+---
+
+# ASP.NET Core Web API
+
+## **Priority: P1 (OPERATIONAL)**
+
+Modern ASP.NET Core patterns for building RESTful APIs.
+
+## Implementation Guidelines
+
+- **Minimal APIs**: Use for simple endpoints. `app.MapGet()`, route groups, endpoint filters.
+- **Controllers**: Use `[ApiController]` for automatic model validation and binding.
+- **Middleware**: Order matters. Custom middleware with `app.Use()`.
+- **Filters**: Action filters for cross-cutting concerns. Exception filters for error handling.
+- **Validation**: FluentValidation or DataAnnotations. Return `ProblemDetails` on errors.
+- **Versioning**: URL-based (`/api/v1/`) or header-based versioning.
+- **OpenAPI**: Always configure Swagger for API documentation.
+- **Response Types**: Use `TypedResults` for compile-time safety.
+
+## Anti-Patterns
+
+- **No `HttpClient` without `IHttpClientFactory`**: Socket exhaustion risk.
+- **No blocking async**: Never `.Result` or `.Wait()` in controllers.
+- **No business logic in controllers**: Controllers should only orchestrate.
+- **No returning `Task` without `async`**: Use `async` keyword or return directly.
+
+## Code
+
+```csharp
+// Minimal API with route groups
+var app = WebApplication.CreateBuilder(args).Build();
+
+var users = app.MapGroup("/api/users")
+    .WithTags("Users")
+    .RequireAuthorization();
+
+users.MapGet("/", async (IUserService service) =>
+    TypedResults.Ok(await service.GetAllAsync()));
+
+users.MapGet("/{id:int}", async (int id, IUserService service) =>
+    await service.GetByIdAsync(id) is { } user
+        ? TypedResults.Ok(user)
+        : TypedResults.NotFound());
+
+users.MapPost("/", async (CreateUserDto dto, IUserService service) =>
+{
+    var user = await service.CreateAsync(dto);
+    return TypedResults.Created($"/api/users/{user.Id}", user);
+}).AddEndpointFilter<ValidationFilter<CreateUserDto>>();
+
+// Controller with proper patterns
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+public class OrdersController(IOrderService orderService) : ControllerBase
+{
+    [HttpGet("{id:int}")]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetOrder(int id, CancellationToken ct)
+    {
+        var order = await orderService.GetByIdAsync(id, ct);
+        return order is null ? NotFound() : Ok(order);
+    }
+
+    [HttpPost]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
+    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> CreateOrder(CreateOrderDto dto, CancellationToken ct)
+    {
+        var order = await orderService.CreateAsync(dto, ct);
+        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
+    }
+}
+```
+
+## Reference & Examples
+
+For middleware, exception handling, and HttpClientFactory:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+security | razor-pages | blazor

package/rules/dotnet/aspnet-core/references/REFERENCE.md

@@ -0,0 +1,335 @@
+# ASP.NET Core Web API Reference
+
+Middleware, exception handling, and advanced patterns.
+
+## References
+
+- [**Middleware**](middleware.md) - Custom middleware patterns.
+- [**Exception Handling**](exception-handling.md) - Global error handling.
+- [**HttpClientFactory**](httpclient-factory.md) - Typed HTTP clients.
+
+## Global Exception Handling Middleware
+
+```csharp
+public class ExceptionMiddleware(
+    RequestDelegate next,
+    ILogger<ExceptionMiddleware> logger,
+    IHostEnvironment env)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await next(context);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unhandled exception: {Message}", ex.Message);
+            await HandleExceptionAsync(context, ex);
+        }
+    }
+
+    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
+    {
+        context.Response.ContentType = "application/problem+json";
+
+        var (statusCode, title) = exception switch
+        {
+            NotFoundException => (StatusCodes.Status404NotFound, "Not Found"),
+            ValidationException => (StatusCodes.Status400BadRequest, "Validation Error"),
+            UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
+            ForbiddenException => (StatusCodes.Status403Forbidden, "Forbidden"),
+            _ => (StatusCodes.Status500InternalServerError, "Internal Server Error")
+        };
+
+        context.Response.StatusCode = statusCode;
+
+        var problem = new ProblemDetails
+        {
+            Status = statusCode,
+            Title = title,
+            Detail = env.IsDevelopment() ? exception.Message : null,
+            Instance = context.Request.Path
+        };
+
+        if (exception is ValidationException validationEx)
+        {
+            problem.Extensions["errors"] = validationEx.Errors;
+        }
+
+        await context.Response.WriteAsJsonAsync(problem);
+    }
+}
+
+// Registration
+app.UseMiddleware<ExceptionMiddleware>();
+```
+
+## Minimal API Endpoint Filters
+
+```csharp
+// Validation filter
+public class ValidationFilter<T> : IEndpointFilter where T : class
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var model = context.Arguments.OfType<T>().FirstOrDefault();
+
+        if (model is null)
+            return TypedResults.BadRequest("Request body is required");
+
+        var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
+
+        if (validator is not null)
+        {
+            var result = await validator.ValidateAsync(model);
+            if (!result.IsValid)
+            {
+                return TypedResults.ValidationProblem(
+                    result.ToDictionary());
+            }
+        }
+
+        return await next(context);
+    }
+}
+
+// Logging filter
+public class LoggingFilter(ILogger<LoggingFilter> logger) : IEndpointFilter
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var path = context.HttpContext.Request.Path;
+        logger.LogInformation("Request started: {Path}", path);
+
+        var sw = Stopwatch.StartNew();
+        var result = await next(context);
+        sw.Stop();
+
+        logger.LogInformation("Request completed: {Path} in {ElapsedMs}ms",
+            path, sw.ElapsedMilliseconds);
+
+        return result;
+    }
+}
+
+// Usage
+app.MapPost("/api/users", handler)
+   .AddEndpointFilter<ValidationFilter<CreateUserDto>>()
+   .AddEndpointFilter<LoggingFilter>();
+```
+
+## IHttpClientFactory Typed Clients
+
+```csharp
+// Typed client
+public class PaymentClient(HttpClient httpClient)
+{
+    public async Task<PaymentResult?> ProcessPaymentAsync(PaymentRequest request)
+    {
+        var response = await httpClient.PostAsJsonAsync("/payments", request);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<PaymentResult>();
+    }
+
+    public async Task<PaymentStatus?> GetStatusAsync(string paymentId)
+    {
+        return await httpClient.GetFromJsonAsync<PaymentStatus>($"/payments/{paymentId}");
+    }
+}
+
+// Registration with resilience
+builder.Services.AddHttpClient<PaymentClient>(client =>
+{
+    client.BaseAddress = new Uri(builder.Configuration["Payment:BaseUrl"]!);
+    client.DefaultRequestHeaders.Add("X-Api-Key",
+        builder.Configuration["Payment:ApiKey"]);
+    client.Timeout = TimeSpan.FromSeconds(30);
+})
+.AddStandardResilienceHandler(); // Polly retry, circuit breaker
+
+// Manual resilience configuration
+builder.Services.AddHttpClient<PaymentClient>()
+    .AddResilienceHandler("payment-pipeline", builder =>
+    {
+        builder
+            .AddRetry(new HttpRetryStrategyOptions
+            {
+                MaxRetryAttempts = 3,
+                Delay = TimeSpan.FromSeconds(1),
+                BackoffType = DelayBackoffType.Exponential
+            })
+            .AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
+            {
+                SamplingDuration = TimeSpan.FromSeconds(30),
+                FailureRatio = 0.5,
+                MinimumThroughput = 10,
+                BreakDuration = TimeSpan.FromSeconds(30)
+            })
+            .AddTimeout(TimeSpan.FromSeconds(10));
+    });
+```
+
+## Background Services
+
+```csharp
+public class OrderProcessingService(
+    IServiceScopeFactory scopeFactory,
+    ILogger<OrderProcessingService> logger) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation("Order processing service started");
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await ProcessPendingOrdersAsync(stoppingToken);
+            }
+            catch (Exception ex)
+            {
+                logger.LogError(ex, "Error processing orders");
+            }
+
+            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
+        }
+    }
+
+    private async Task ProcessPendingOrdersAsync(CancellationToken ct)
+    {
+        using var scope = scopeFactory.CreateScope();
+        var orderService = scope.ServiceProvider.GetRequiredService<IOrderService>();
+
+        var pendingOrders = await orderService.GetPendingOrdersAsync(ct);
+
+        foreach (var order in pendingOrders)
+        {
+            await orderService.ProcessAsync(order.Id, ct);
+            logger.LogInformation("Processed order {OrderId}", order.Id);
+        }
+    }
+}
+
+// Registration
+builder.Services.AddHostedService<OrderProcessingService>();
+```
+
+## Health Checks
+
+```csharp
+// Registration
+builder.Services.AddHealthChecks()
+    .AddDbContextCheck<AppDbContext>("database")
+    .AddRedis(builder.Configuration.GetConnectionString("Redis")!, "redis")
+    .AddUrlGroup(new Uri("https://api.external.com/health"), "external-api")
+    .AddCheck<CustomHealthCheck>("custom");
+
+// Custom health check
+public class CustomHealthCheck(IOrderService orderService) : IHealthCheck
+{
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken ct = default)
+    {
+        try
+        {
+            var count = await orderService.GetPendingCountAsync(ct);
+
+            if (count > 1000)
+            {
+                return HealthCheckResult.Degraded(
+                    $"High pending orders: {count}");
+            }
+
+            return HealthCheckResult.Healthy();
+        }
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy("Order service unavailable", ex);
+        }
+    }
+}
+
+// Endpoints
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapHealthChecks("/health/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+
+app.MapHealthChecks("/health/live", new HealthCheckOptions
+{
+    Predicate = _ => false // Just checks if app is running
+});
+```
+
+## Model Binding and Validation
+
+```csharp
+// FluentValidation
+public class CreateOrderDtoValidator : AbstractValidator<CreateOrderDto>
+{
+    public CreateOrderDtoValidator()
+    {
+        RuleFor(x => x.CustomerId)
+            .NotEmpty()
+            .WithMessage("Customer ID is required");
+
+        RuleFor(x => x.Items)
+            .NotEmpty()
+            .WithMessage("Order must have at least one item");
+
+        RuleForEach(x => x.Items).ChildRules(item =>
+        {
+            item.RuleFor(x => x.ProductId).NotEmpty();
+            item.RuleFor(x => x.Quantity).GreaterThan(0);
+        });
+
+        RuleFor(x => x.ShippingAddress)
+            .NotNull()
+            .SetValidator(new AddressValidator());
+    }
+}
+
+// Registration
+builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderDtoValidator>();
+
+// Pipeline behavior for MediatR
+public class ValidationBehavior<TRequest, TResponse>(
+    IEnumerable<IValidator<TRequest>> validators)
+    : IPipelineBehavior<TRequest, TResponse>
+    where TRequest : notnull
+{
+    public async Task<TResponse> Handle(
+        TRequest request,
+        RequestHandlerDelegate<TResponse> next,
+        CancellationToken ct)
+    {
+        if (!validators.Any())
+            return await next();
+
+        var context = new ValidationContext<TRequest>(request);
+        var results = await Task.WhenAll(
+            validators.Select(v => v.ValidateAsync(context, ct)));
+
+        var failures = results
+            .SelectMany(r => r.Errors)
+            .Where(f => f != null)
+            .ToList();
+
+        if (failures.Count != 0)
+            throw new ValidationException(failures);
+
+        return await next();
+    }
+}
+```

package/rules/dotnet/best-practices/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: C# Best Practices
+description: Idiomatic C# patterns for clean, maintainable code.
+metadata:
+  labels: [csharp, conventions, naming, structure, di]
+  triggers:
+    files: ['**/*.cs']
+    keywords: [class, namespace, using, public, private, internal]
+---
+
+# C# Best Practices
+
+## **Priority: P1 (OPERATIONAL)**
+
+Idiomatic patterns for clean, maintainable C# code.
+
+## Implementation Guidelines
+
+- **Naming Conventions**:
+  - `PascalCase`: Types, methods, properties, events, namespaces
+  - `camelCase`: Parameters, local variables
+  - `_camelCase`: Private fields
+  - `IPascalCase`: Interfaces (prefix with `I`)
+  - `TPascalCase`: Type parameters (prefix with `T`)
+- **Project Structure**: Clean/Onion architecture. Feature folders over layer folders.
+- **Dependency Injection**: Constructor injection only. Register in `IServiceCollection`.
+- **Logging**: `ILogger<T>` with structured logging. Use appropriate log levels.
+- **Configuration**: `IOptions<T>` pattern with validation. Never hardcode settings.
+- **File Organization**: One type per file. Use `global using` for common namespaces.
+- **Immutability**: Prefer `readonly`, `init`, `record` for data integrity.
+- **Expression-bodied Members**: Use for simple single-line methods/properties.
+
+## Anti-Patterns
+
+- **No static services**: Use DI instead of `static class ServiceHelper`.
+- **No service locator**: Avoid `IServiceProvider.GetService()` in business logic.
+- **No `new()` for dependencies**: Inject via constructor.
+- **No magic strings**: Use `nameof()`, constants, or configuration.
+- **No God classes**: Split large classes by responsibility.
+- **No regions**: Use partial classes or extract types instead.
+
+## Code
+
+```csharp
+// Proper DI registration
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
+    {
+        services.AddScoped<IUserService, UserService>();
+        services.AddScoped<IOrderService, OrderService>();
+
+        services.AddOptions<EmailSettings>()
+            .BindConfiguration("Email")
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        return services;
+    }
+}
+
+// Structured logging with semantic names
+public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
+{
+    public async Task<Order?> GetOrderAsync(int orderId, CancellationToken ct)
+    {
+        logger.LogDebug("Fetching order {OrderId}", orderId);
+
+        var order = await repo.GetByIdAsync(orderId, ct);
+
+        if (order is null)
+            logger.LogWarning("Order {OrderId} not found", orderId);
+
+        return order;
+    }
+}
+
+// Options pattern with validation
+public class EmailSettings
+{
+    public const string SectionName = "Email";
+
+    [Required]
+    public string SmtpHost { get; init; } = string.Empty;
+
+    [Range(1, 65535)]
+    public int SmtpPort { get; init; } = 587;
+
+    [Required, EmailAddress]
+    public string FromAddress { get; init; } = string.Empty;
+}
+```
+
+## Reference & Examples
+
+For project structure templates and DI patterns:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | security | tooling