claude-code-arcane 1.2.0 → 1.3.0

package/skills/dotnet-architecture/references/project-structure.md

@@ -0,0 +1,78 @@
+# Estructura de Directorios
+
+Dos formas válidas de estructurar un backend .NET 10 / ASP.NET Core. Elegí según
+complejidad del dominio (ver `when-to-use` en la SKILL).
+
+## Vertical Slice Architecture (un proyecto)
+
+Cada feature es un folder autocontenido: request, handler, validator y endpoint
+viven juntos. Tocás un caso de uso → tocás un solo archivo/carpeta.
+
+```
+src/
+  Features/
+    Orders/
+      CreateOrder.cs          ← record Command + Handler + Validator juntos
+      GetOrders.cs            ← record Query + Handler (paginación/proyección)
+      OrderEndpoints.cs       ← MapGroup("/orders") + TypedResults
+    Customers/
+      RegisterCustomer.cs
+      CustomerEndpoints.cs
+  Common/
+    Behaviors/                ← ValidationBehavior, LoggingBehavior, TxBehavior
+    Result.cs                 ← Result<T> / Error compartido
+  Infrastructure/
+    AppDbContext.cs           ← EF Core DbContext (DbSet<> por entidad)
+    Migrations/               ← migraciones versionadas en git
+  Program.cs                  ← composition root: DI, pipeline, MapEndpoints
+appsettings.json
+```
+
+- Cada slice depende de `Common` e `Infrastructure`, no de otros slices.
+- Un slice nuevo = un archivo nuevo; borrarlo no rompe a los demás (bajo acoplamiento).
+- El `DbContext` es compartido; cada handler usa solo los `DbSet<>` que necesita.
+
+## Clean Architecture (cuatro proyectos)
+
+Separación por capa técnica. Las dependencias apuntan **hacia adentro**: el dominio
+no conoce a nadie; la infraestructura y la API dependen de las capas internas.
+
+```
+src/
+  MyApp.Domain/             ← Entidades, value objects, domain events, reglas
+    Entities/Order.cs       ← cero deps externas (ni EF, ni ASP.NET)
+    ValueObjects/Money.cs
+    Common/Entity.cs
+  MyApp.Application/        ← Casos de uso (handlers), DTOs, interfaces
+    Orders/CreateOrder.cs
+    Common/IApplicationDbContext.cs   ← expone DbSet<> + SaveChangesAsync
+    Common/Behaviors/
+  MyApp.Infrastructure/     ← EF Core, Identity, servicios externos
+    Persistence/AppDbContext.cs       ← : DbContext, IApplicationDbContext
+    Persistence/Migrations/
+    Services/EmailSender.cs
+    DependencyInjection.cs
+  MyApp.Api/                ← Endpoints, Program.cs, wiring de DI
+    Endpoints/OrderEndpoints.cs
+    Program.cs
+```
+
+### Dirección de las referencias (`.csproj`)
+
+```
+MyApp.Api            → referencia → MyApp.Infrastructure, MyApp.Application
+MyApp.Infrastructure → referencia → MyApp.Application
+MyApp.Application    → referencia → MyApp.Domain
+MyApp.Domain         → referencia → (NADA)
+```
+
+- `Domain.csproj` no tiene ningún `<ProjectReference>` ni paquete de framework.
+- `Application` define `IApplicationDbContext`; `Infrastructure` lo implementa.
+  Así la lógica de negocio depende de una abstracción, no de EF Core directamente.
+- La inversión de dependencias se logra en `Api/Program.cs`, que es el único lugar
+  que conoce a las cuatro capas y arma el grafo de DI.
+
+> Regla de oro: si una flecha de dependencia apunta hacia afuera del dominio, la
+> arquitectura está rota. El dominio es el centro estable.
+
+_Ref: https://github.com/ardalis/CleanArchitecture · https://github.com/nadirbad/VerticalSliceArchitecture · https://www.milanjovanovic.tech/blog/vertical-slice-architecture-dotnet_

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

@@ -0,0 +1,76 @@
+---
+name: dotnet-best-practices
+description: "ASP.NET Core / C# production best practices: 40 reglas en 10 categorías (arquitectura, DI, errores, seguridad, performance, async, EF Core, testing, API, devops) priorizadas por impacto. Usar al escribir/revisar código .NET backend."
+category: "backend"
+argument-hint: "[architecture|di|errors|security|performance|async|database|testing|api|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# dotnet-best-practices — Guía priorizada por impacto
+
+40 reglas para aplicaciones ASP.NET Core (.NET 10) production-ready, organizadas en 10 categorías y priorizadas de **CRITICAL** a **LOW-MEDIUM**. Cada regla del catálogo (en `references/`) trae impacto, ejemplo incorrecto, ejemplo correcto y link a docs.
+
+## MANDATORY WORKFLOW
+
+**No aplicar las 40 reglas a ciegas. Diagnosticar primero, priorizar por impacto.**
+
+### Step 0: Determinar scope
+
+1. **¿Código nuevo o auditoría de existente?** Si es auditoría, leer primero el feature/proyecto objetivo.
+2. **¿Qué categoría aplica?** Mapear el área del problema (ver tabla) o usar `all` para review completa.
+3. **¿Hay síntomas concretos?** (deadlocks, N+1, 500 inconsistentes, leaks) → ir directo a la categoría relevante.
+
+### Step 1: Priorizar por impacto
+
+Aplicar en este orden — no bajar de nivel hasta resolver el anterior:
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Architecture | CRITICAL | `references/architecture.md` |
+| 2 | Dependency Injection | CRITICAL | `references/dependency-injection.md` |
+| 3 | Async & Concurrency | HIGH | `references/async.md` |
+| 4 | Error Handling | HIGH | `references/error-handling.md` |
+| 5 | Security | HIGH | `references/security.md` |
+| 6 | Performance | HIGH | `references/performance.md` |
+| 7 | Database & EF Core | MEDIUM-HIGH | `references/database.md` |
+| 8 | Testing | MEDIUM-HIGH | `references/testing.md` |
+| 9 | API Design | MEDIUM | `references/api-design.md` |
+| 10 | DevOps & Deployment | LOW-MEDIUM | `references/devops.md` |
+
+### Step 2: Aplicar + verificar
+
+Para cada regla relevante: leer el ejemplo correcto en el reference, aplicarlo, y verificar contra el checklist de cierre.
+
+### Step 3: Checklist de cierre
+
+- [ ] `<Nullable>enable</Nullable>` + warnings as errors; cero `#nullable disable`
+- [ ] Async end-to-end con `CancellationToken`; cero `.Result`/`.Wait()`/`.GetAwaiter().GetResult()`
+- [ ] DI por constructor con scope correcto; sin `BuildServiceProvider()` manual ni service locator
+- [ ] Errores vía `ProblemDetails` (RFC 7807); sin stack traces expuestos
+- [ ] Sin N+1 en EF Core (`Include`/projection); `AsNoTracking()` en lecturas
+- [ ] Migraciones versionadas; nunca `EnsureCreated()` en prod
+- [ ] AuthZ por policies declarativas; secrets en secret manager (no en `appsettings.json`)
+- [ ] Structured logging (Serilog JSON) + health checks
+- [ ] Tests con xUnit; integración contra Postgres real (Testcontainers), no mocks de DbContext
+
+Si todo el checklist pasa → código **COMPLIANT**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla de mapeo síntoma → categoría
+
+| Síntoma | Categoría |
+|---------|-----------|
+| Deadlocks / thread pool starvation / app cuelga | Async, Performance |
+| Lentitud en endpoints, muchas queries | Performance, Database |
+| `InvalidOperationException` de DI / scopes / captured dependency | DI, Architecture |
+| Errores 500 inconsistentes / leaks de stack traces | Error Handling |
+| Endpoints expuestos / brute force / data sensible en logs | Security |
+| Tests frágiles o que pegan a servicios/DB reales sin control | Testing |
+| Respuestas inconsistentes / over-fetching de entidades | API Design |
+
+## Próximos pasos
+
+Para estructurar el proyecto → `/dotnet-architecture`. Para iniciar un backend nuevo con estos defaults → `/dotnet-scaffold`.
+
+---
+
+_Adaptado de [github/awesome-copilot](https://github.com/github/awesome-copilot) (dotnet-best-practices), [dotnet/skills](https://github.com/dotnet/skills) y [Aaronontheweb/dotnet-skills](https://github.com/Aaronontheweb/dotnet-skills). Reorganizado al formato skill+references de Arcane._

package/skills/dotnet-best-practices/references/api-design.md

@@ -0,0 +1,75 @@
+# 9. API Design (MEDIUM)
+
+## 9.1 DTOs, Never Expose EF Entities — MEDIUM
+
+Serializar entidades de EF filtra columnas internas, arrastra relaciones y acopla el contrato HTTP al schema de la base. Usar DTOs/records dedicados.
+
+**Incorrecto:**
+```csharp
+app.MapGet("/users/{id}", async (int id, AppDbContext db) => await db.Users.FindAsync(id)); // expone la entidad
+```
+**Correcto:**
+```csharp
+public record UserDto(int Id, string Email);
+app.MapGet("/users/{id}", async (int id, AppDbContext db) =>
+    await db.Users.Where(u => u.Id == id).Select(u => new UserDto(u.Id, u.Email)).FirstOrDefaultAsync());
+```
+
+## 9.2 API Versioning — MEDIUM
+
+Versionar la API permite evolucionar el contrato sin romper clientes existentes. `Asp.Versioning` lo integra con minimal APIs y OpenAPI.
+
+**Correcto:**
+```csharp
+builder.Services.AddApiVersioning(o => o.DefaultApiVersion = new ApiVersion(1, 0));
+var v1 = app.NewVersionedApi().MapGroup("/api/v{version:apiVersion}").HasApiVersion(1.0);
+v1.MapGet("/orders", GetOrders);
+```
+
+## 9.3 Consistent Errors with ProblemDetails — MEDIUM
+
+`ProblemDetails` (RFC 9457) da un formato de error estándar y machine-readable en toda la API.
+
+**Correcto:**
+```csharp
+builder.Services.AddProblemDetails();
+app.UseExceptionHandler();
+// en un handler:
+return TypedResults.Problem(title: "Order not found", statusCode: StatusCodes.Status404NotFound);
+```
+
+## 9.4 Correct Status Codes via TypedResults — MEDIUM
+
+`TypedResults` devuelve el status code correcto de forma tipada y mejora los metadatos de OpenAPI.
+
+**Correcto:**
+```csharp
+app.MapPost("/orders", async (CreateOrder cmd, IOrderService svc) =>
+{
+    var order = await svc.CreateAsync(cmd);
+    return TypedResults.Created($"/orders/{order.Id}", order); // 201 + Location
+});
+```
+
+## 9.5 Pagination & Idempotency for Writes — MEDIUM
+
+Paginar colecciones evita respuestas ilimitadas; una Idempotency-Key hace que un POST repetido (reintento de red) no duplique el recurso.
+
+**Correcto:**
+```csharp
+app.MapGet("/orders", (int page = 1, int pageSize = 20) => /* Skip/Take con límites */ );
+app.MapPost("/payments", ([FromHeader(Name = "Idempotency-Key")] string key, Payment p) =>
+    /* deduplicar por key antes de procesar */ );
+```
+
+## 9.6 Built-in OpenAPI — LOW
+
+`Microsoft.AspNetCore.OpenApi` genera el documento OpenAPI sin dependencias externas.
+
+**Correcto:**
+```csharp
+builder.Services.AddOpenApi();
+app.MapOpenApi(); // /openapi/v1.json
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/apiversioning · https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/responses_

package/skills/dotnet-best-practices/references/architecture.md

@@ -0,0 +1,62 @@
+# 1. Architecture (CRITICAL)
+
+## 1.1 Organize by Feature, Not Technical Layers — CRITICAL
+
+Carpetas por feature (vertical slice) → cohesión alta y cambios localizados; las carpetas por capa técnica dispersan un cambio en 5 sitios.
+
+**Incorrecto** — carpetas técnicas globales:
+```csharp
+// Controllers/, Services/, Repositories/, Dtos/ ... un cambio toca 4 carpetas
+```
+**Correcto** — un slice por feature:
+```csharp
+// Features/Orders/{ CreateOrder.cs, GetOrder.cs, OrdersEndpoints.cs, OrderDto.cs }
+// Features/Users/{ RegisterUser.cs, UsersEndpoints.cs, UserDto.cs }
+```
+
+## 1.2 Thin Endpoints — CRITICAL
+
+El endpoint parsea, delega y forma la respuesta. Sin lógica de negocio: así es testeable y reutilizable desde otros transportes.
+
+**Incorrecto:**
+```csharp
+app.MapPost("/orders", async (CreateOrderDto dto, AppDbContext db) =>
+{
+    if (dto.Items.Count == 0) return Results.BadRequest();   // negocio en el endpoint
+    var total = dto.Items.Sum(i => i.Price * i.Qty);          // negocio en el endpoint
+    db.Orders.Add(new Order { Total = total });
+    await db.SaveChangesAsync();
+    return Results.Ok();
+});
+```
+**Correcto:**
+```csharp
+app.MapPost("/orders", async (CreateOrderRequest req, CreateOrderHandler handler, CancellationToken ct) =>
+{
+    var result = await handler.HandleAsync(req, ct);
+    return result.IsSuccess ? Results.Created($"/orders/{result.Value.Id}", result.Value) : result.ToProblem();
+});
+```
+
+## 1.3 Dependencies Point Inward / Slices Independent — HIGH
+
+El dominio no conoce infraestructura (Clean Architecture): el handler depende de una abstracción `IOrderRepository`, no de `AppDbContext`. Entre slices, sin acoplamiento directo; coordinar vía eventos de dominio o un mediador.
+
+## 1.4 Single Responsibility per Handler — HIGH
+
+Un handler resuelve un caso de uso. `CreateOrderHandler` no envía emails ni cobra: emite un evento y otro handler reacciona. Mejora testabilidad y limita el blast radius de cada cambio.
+
+## 1.5 Program.cs as Composition Root Only — MEDIUM-HIGH
+
+`Program.cs` solo registra servicios y arma el pipeline; nada de lógica de negocio. Mover el wiring a extensiones (`builder.Services.AddOrdersFeature()`) mantiene el root legible.
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddOrdersFeature().AddAuthFeature();
+var app = builder.Build();
+app.UseExceptionHandler().UseAuthorization();
+app.MapOrdersEndpoints();
+app.Run();
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/min-api-filters_

package/skills/dotnet-best-practices/references/async.md

@@ -0,0 +1,62 @@
+# 3. Async & Concurrency (HIGH)
+
+## 3.1 Async All the Way — CRITICAL
+
+`.Result`, `.Wait()` y `.GetAwaiter().GetResult()` bloquean el hilo: deadlocks y thread-pool starvation bajo carga. Propagar `async`/`await` de punta a punta.
+
+**Incorrecto:**
+```csharp
+public Order Get(int id) => repo.GetAsync(id).Result; // bloquea el thread-pool
+```
+**Correcto:**
+```csharp
+public async Task<Order> GetAsync(int id, CancellationToken ct) => await repo.GetAsync(id, ct);
+```
+
+## 3.2 Accept and Propagate CancellationToken — HIGH
+
+El token aborta el trabajo cuando el cliente corta la conexión, liberando hilos y conexiones de DB. Pasarlo a cada llamada async, hasta EF Core y `HttpClient`.
+
+**Correcto:**
+```csharp
+app.MapGet("/orders/{id:int}", async (int id, AppDbContext db, CancellationToken ct) =>
+    await db.Orders.FirstOrDefaultAsync(o => o.Id == id, ct) is { } o ? Results.Ok(o) : Results.NotFound());
+```
+
+## 3.3 No async void — HIGH
+
+`async void` no se puede esperar y sus excepciones tumban el proceso. Usar `async Task`. La única excepción son los event handlers de UI/eventos.
+
+**Incorrecto:**
+```csharp
+public async void Process() => await DoWorkAsync(); // excepción => crash no observable
+```
+**Correcto:**
+```csharp
+public async Task ProcessAsync(CancellationToken ct) => await DoWorkAsync(ct);
+```
+
+## 3.4 ConfigureAwait(false) in Libraries — MEDIUM-HIGH
+
+En código de librería reutilizable, `ConfigureAwait(false)` evita volver al contexto capturado y previene deadlocks en hosts con `SynchronizationContext`. En apps ASP.NET Core (sin contexto) no hace falta.
+
+```csharp
+var data = await httpClient.GetStringAsync(url, ct).ConfigureAwait(false);
+```
+
+## 3.5 Task.WhenAll for Parallel Independent Work — MEDIUM-HIGH
+
+Operaciones independientes en paralelo en vez de secuencial. No compartir un `DbContext` entre tasks concurrentes (no es thread-safe): usar un scope/contexto por task.
+
+```csharp
+var (user, prefs) = (await Task.WhenAll(GetUserAsync(id, ct), GetPrefsAsync(id, ct))) switch
+{
+    var r => (r[0], r[1])
+};
+```
+
+## 3.6 No Fire-and-Forget Without Error Handling — HIGH
+
+Un `Task` descartado traga excepciones y puede morir al reciclar el proceso. Para trabajo en background usar un `BackgroundService` / cola, con logging del error.
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/async-scenarios · https://learn.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern_

package/skills/dotnet-best-practices/references/database.md

@@ -0,0 +1,69 @@
+# 7. Database & EF Core (MEDIUM-HIGH)
+
+## 7.1 Avoid N+1 with Include or Projection — HIGH
+
+Acceder a relaciones en un loop dispara una query por fila. Usar `Include` o proyectar a un DTO con `Select` resuelve todo en una sola query.
+
+**Incorrecto:**
+```csharp
+var orders = await db.Orders.ToListAsync();
+foreach (var o in orders) o.Customer = await db.Customers.FindAsync(o.CustomerId); // N+1
+```
+**Correcto:**
+```csharp
+var orders = await db.Orders
+    .Select(o => new OrderDto(o.Id, o.Customer.Name, o.Total))
+    .ToListAsync();
+```
+
+## 7.2 AsNoTracking for Read-Only Queries — HIGH
+
+El change tracker añade overhead innecesario en lecturas. `AsNoTracking()` evita las snapshots y reduce allocations.
+
+**Correcto:**
+```csharp
+var products = await db.Products.AsNoTracking().Where(p => p.Active).ToListAsync();
+```
+
+## 7.3 DbContext is the Unit of Work — MEDIUM-HIGH
+
+`DbContext` ya implementa Unit of Work + Repository. Envolverlo en un repositorio genérico oculta `Include`, proyecciones y `SaveChanges`, añadiendo abstracción sin valor.
+
+**Incorrecto:**
+```csharp
+public class GenericRepository<T> { Task<T> GetById(int id); /* envuelve DbSet sin necesidad */ }
+```
+**Correcto:**
+```csharp
+// Inyectar AppDbContext (o un servicio de dominio que lo use) directamente
+public sealed class OrderService(AppDbContext db) { /* usa db.Orders, db.SaveChangesAsync */ }
+```
+
+## 7.4 Versioned Migrations, Never EnsureCreated in Prod — MEDIUM-HIGH
+
+`EnsureCreated()` no usa migraciones y no es upgradeable: hay que migrar el schema versionado con la CLI de EF.
+
+**Incorrecto:**
+```csharp
+await db.Database.EnsureCreatedAsync(); // no migrable, pierde historial de schema
+```
+**Correcto:**
+```bash
+dotnet ef migrations add AddOrderIndex
+dotnet ef database update    # en deploy: db.Database.MigrateAsync()
+```
+
+## 7.5 Connection Resiliency & Split Queries — MEDIUM
+
+Habilitar reintentos ante fallos transitorios y `AsSplitQuery()` para `Include` grandes evita la explosión cartesiana de un único JOIN.
+
+**Correcto:**
+```csharp
+builder.Services.AddDbContext<AppDbContext>(o =>
+    o.UseNpgsql(conn, npgsql => npgsql.EnableRetryOnFailure()));
+
+var blogs = await db.Blogs.Include(b => b.Posts).Include(b => b.Tags)
+    .AsSplitQuery().ToListAsync();
+```
+
+_Ref: https://learn.microsoft.com/en-us/ef/core/querying/related-data/eager-loading · https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations · https://learn.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency_

package/skills/dotnet-best-practices/references/dependency-injection.md

@@ -0,0 +1,73 @@
+# 2. Dependency Injection (CRITICAL)
+
+## 2.1 Prefer Constructor Injection (Primary Constructors) — CRITICAL
+
+Dependencias explícitas, type-safe y testeables. Con primary constructors (C# 12+) el boilerplate desaparece.
+
+**Correcto:**
+```csharp
+public sealed class CreateOrderHandler(IOrderRepository repo, ILogger<CreateOrderHandler> logger)
+{
+    public async Task HandleAsync(CreateOrderRequest req, CancellationToken ct)
+    {
+        logger.LogInformation("Creating order for {Customer}", req.CustomerId);
+        await repo.AddAsync(req.ToOrder(), ct);
+    }
+}
+```
+
+## 2.2 Use Correct Lifetimes — CRITICAL
+
+`Scoped` para `DbContext` y handlers (una instancia por request). `Singleton` solo para servicios stateless y thread-safe. `Transient` para servicios livianos sin estado.
+
+```csharp
+builder.Services.AddDbContext<AppDbContext>(o => o.UseNpgsql(cs)); // Scoped por defecto
+builder.Services.AddScoped<CreateOrderHandler>();
+builder.Services.AddSingleton<IClock, SystemClock>(); // stateless
+```
+
+## 2.3 Never Inject Scoped into Singleton — CRITICAL
+
+Es la "captured dependency": el Singleton retiene una instancia Scoped muerta tras el primer request → datos corruptos o `ObjectDisposedException`. Resolverlo bajo demanda con un scope.
+
+**Incorrecto:**
+```csharp
+public sealed class CacheWarmer(AppDbContext db) : IHostedService { } // Singleton captura DbContext Scoped
+```
+**Correcto:**
+```csharp
+public sealed class CacheWarmer(IServiceScopeFactory scopeFactory) : IHostedService
+{
+    public async Task StartAsync(CancellationToken ct)
+    {
+        await using var scope = scopeFactory.CreateAsyncScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+    }
+}
+```
+
+## 2.4 No Service Locator / No Manual BuildServiceProvider() — HIGH
+
+`provider.GetService<T>()` dentro de la lógica oculta dependencias y rompe los tests. `BuildServiceProvider()` en `Program.cs` crea un container paralelo (singletons duplicados, fugas). Inyectar por constructor (2.1).
+
+## 2.5 Register by Interface — HIGH
+
+Registrar contra la abstracción permite sustituir implementaciones (tests, features) sin tocar consumidores.
+
+```csharp
+builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
+```
+
+## 2.6 IOptions<T> Pattern for Config — MEDIUM-HIGH
+
+Bind tipado y validado de configuración, en vez de leer `IConfiguration` con strings por todo el código.
+
+```csharp
+builder.Services.AddOptions<JwtOptions>()
+    .Bind(builder.Configuration.GetSection("Jwt"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+// constructor(IOptions<JwtOptions> options) => _opts = options.Value;
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection · https://learn.microsoft.com/en-us/dotnet/core/extensions/options_

package/skills/dotnet-best-practices/references/devops.md

@@ -0,0 +1,76 @@
+# 10. DevOps & Deployment (LOW-MEDIUM)
+
+## 10.1 Multi-Stage Dockerfile, Non-Root User — MEDIUM
+
+Compilar con la imagen SDK y correr sobre la imagen `aspnet` runtime reduce el tamaño y la superficie de ataque. Usar un usuario no-root limita el blast radius.
+
+**Correcto:**
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet publish -c Release -o /app
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+WORKDIR /app
+COPY --from=build /app .
+USER $APP_UID
+ENTRYPOINT ["dotnet", "Api.dll"]
+```
+
+## 10.2 Health Checks (Liveness/Readiness) — MEDIUM
+
+Los orquestadores (Kubernetes) necesitan endpoints separados: liveness (¿está vivo?) y readiness (¿puede recibir tráfico?, p. ej. DB conectada).
+
+**Correcto:**
+```csharp
+builder.Services.AddHealthChecks().AddNpgSql(conn, tags: ["ready"]);
+app.MapHealthChecks("/health/live", new() { Predicate = _ => false });
+app.MapHealthChecks("/health/ready", new() { Predicate = c => c.Tags.Contains("ready") });
+```
+
+## 10.3 Structured Logging (Serilog JSON) — MEDIUM
+
+Logs en JSON son parseables por agregadores (Loki, ELK). Serilog con sink de consola en formato compacto facilita la observabilidad.
+
+**Correcto:**
+```csharp
+builder.Host.UseSerilog((ctx, cfg) =>
+    cfg.WriteTo.Console(new Serilog.Formatting.Compact.CompactJsonFormatter()));
+```
+
+## 10.4 OpenTelemetry for Traces & Metrics — MEDIUM
+
+OpenTelemetry instrumenta traces y métricas de forma estándar y exportable a cualquier backend OTLP.
+
+**Correcto:**
+```csharp
+builder.Services.AddOpenTelemetry()
+    .WithTracing(t => t.AddAspNetCoreInstrumentation().AddOtlpExporter())
+    .WithMetrics(m => m.AddAspNetCoreInstrumentation().AddOtlpExporter());
+```
+
+## 10.5 Config per Environment & Graceful Shutdown — LOW-MEDIUM
+
+Nunca hardcodear secrets ni connection strings: usar `appsettings.{Environment}.json` y variables de entorno. Registrar limpieza ante el shutdown con `IHostApplicationLifetime`.
+
+**Correcto:**
+```csharp
+var conn = builder.Configuration.GetConnectionString("Default"); // env / appsettings, no hardcoded
+app.Lifetime.ApplicationStopping.Register(() => Log.Information("Draining connections..."));
+```
+
+## 10.6 CI: build, test, format — LOW
+
+El pipeline debe fallar ante código que no compila, tests rojos o formato inconsistente.
+
+**Correcto:**
+```yaml
+steps:
+  - run: dotnet restore
+  - run: dotnet build --no-restore -c Release
+  - run: dotnet test --no-build -c Release
+  - run: dotnet format --verify-no-changes
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/core/docker/build-container · https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks · https://learn.microsoft.com/en-us/dotnet/core/diagnostics/observability-with-otel · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host_

package/skills/dotnet-best-practices/references/error-handling.md

@@ -0,0 +1,72 @@
+# 4. Error Handling (HIGH)
+
+## 4.1 Global IExceptionHandler + ProblemDetails — CRITICAL
+
+Respuestas de error consistentes y estandarizadas (RFC 7807) sin try/catch repetido en cada endpoint. Registrar `AddProblemDetails()` y un `IExceptionHandler`.
+
+**Correcto:**
+```csharp
+public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken ct)
+    {
+        logger.LogError(ex, "Unhandled exception on {Path}", ctx.Request.Path);
+        await Results.Problem(statusCode: StatusCodes.Status500InternalServerError, title: "An error occurred")
+            .ExecuteAsync(ctx);
+        return true;
+    }
+}
+// Program.cs
+builder.Services.AddProblemDetails();
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
+app.UseExceptionHandler();
+```
+
+## 4.2 Don't Leak Stack Traces — CRITICAL
+
+En producción no exponer `ex.Message`, stack traces ni detalles internos: filtran rutas, versiones y vectores de ataque. Loggear el detalle, devolver un mensaje genérico (ver 4.1).
+
+## 4.3 Result Pattern for Expected Failures — HIGH
+
+Fallos esperados (validación, "not found", reglas de negocio) no son excepciones: las excepciones son caras y para lo excepcional. Devolver un `Result`.
+
+**Incorrecto:**
+```csharp
+if (order is null) throw new NotFoundException(); // control de flujo con excepciones
+```
+**Correcto:**
+```csharp
+public readonly record struct Result<T>(bool IsSuccess, T? Value, string? Error)
+{
+    public static Result<T> Ok(T value) => new(true, value, null);
+    public static Result<T> Fail(string error) => new(false, default, error);
+}
+return order is null ? Result<Order>.Fail("Order not found") : Result<Order>.Ok(order);
+```
+
+## 4.4 Validation → ValidationProblemDetails — HIGH
+
+Los errores de validación se devuelven como `ValidationProblemDetails` (400) con el mapa campo→errores, no como 500.
+
+```csharp
+return Results.ValidationProblem(new Dictionary<string, string[]>
+{
+    ["email"] = ["Email is required"]
+});
+```
+
+## 4.5 No Empty Catch; Log With Context — MEDIUM-HIGH
+
+`catch {}` oculta fallos y vuelve la app indebuggeable. Capturar tipos específicos, loggear con structured logging y re-lanzar o devolver un `Result`.
+
+**Incorrecto:**
+```csharp
+try { await Pay(ct); } catch { } // se traga el error
+```
+**Correcto:**
+```csharp
+try { await Pay(ct); }
+catch (PaymentException ex) { logger.LogError(ex, "Payment failed for {OrderId}", orderId); throw; }
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling · https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors_