theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/patrones-docker/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: patrones-docker
+description: Patrones de Docker y Docker Compose para desarrollo local, seguridad de contenedores, redes, estrategias de volúmenes y orquestación multi-servicio.
+---
+
+# Patrones de Docker
+
+Buenas prácticas de Docker y Docker Compose para desarrollo en contenedores.
+
+## Cuándo activarla
+
+- Al configurar Docker Compose para desarrollo local
+- Al diseñar arquitecturas multi-contenedor
+- Al diagnosticar problemas de redes o volúmenes de contenedores
+- Al revisar Dockerfiles por seguridad y tamaño de imagen
+- Al migrar de desarrollo local a un flujo de trabajo en contenedores
+
+## Docker Compose para desarrollo local
+
+### Stack estándar de aplicación web
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build:
+      context: .
+      target: dev                     # Usa la etapa dev del Dockerfile multi-etapa
+    ports:
+      - "3000:3000"
+    volumes:
+      - .:/app                        # Bind mount para hot reload
+      - /app/node_modules             # Volumen anónimo — preserva las dependencias del contenedor
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
+      - REDIS_URL=redis://redis:6379/0
+      - NODE_ENV=development
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    command: npm run dev
+
+  db:
+    image: postgres:16-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app_dev
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redisdata:/data
+
+  mailpit:                            # Pruebas de email en local
+    image: axllent/mailpit
+    ports:
+      - "8025:8025"                   # Interfaz web
+      - "1025:1025"                   # SMTP
+
+volumes:
+  pgdata:
+  redisdata:
+```
+
+### Dockerfile de desarrollo vs producción
+
+```dockerfile
+# Etapa: dependencias
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Etapa: dev (hot reload, herramientas de depuración)
+FROM node:22-alpine AS dev
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+# Etapa: build
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build && npm prune --production
+
+# Etapa: producción (imagen mínima)
+FROM node:22-alpine AS production
+WORKDIR /app
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
+USER appuser
+COPY --from=build --chown=appuser:appgroup /app/dist ./dist
+COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=build --chown=appuser:appgroup /app/package.json ./
+ENV NODE_ENV=production
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/server.js"]
+```
+
+### Archivos de override
+
+```yaml
+# docker-compose.override.yml (se carga automáticamente, ajustes solo de desarrollo)
+services:
+  app:
+    environment:
+      - DEBUG=app:*
+      - LOG_LEVEL=debug
+    ports:
+      - "9229:9229"                   # Depurador de Node.js
+
+# docker-compose.prod.yml (explícito para producción)
+services:
+  app:
+    build:
+      target: production
+    restart: always
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 512M
+```
+
+```bash
+# Desarrollo (carga automáticamente el override)
+docker compose up
+
+# Producción
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## Redes
+
+### Descubrimiento de servicios
+
+Los servicios de la misma red de Compose se resuelven por nombre de servicio:
+```
+# Desde el contenedor "app":
+postgres://postgres:postgres@db:5432/app_dev    # "db" resuelve al contenedor db
+redis://redis:6379/0                             # "redis" resuelve al contenedor redis
+```
+
+### Redes personalizadas
+
+```yaml
+services:
+  frontend:
+    networks:
+      - frontend-net
+
+  api:
+    networks:
+      - frontend-net
+      - backend-net
+
+  db:
+    networks:
+      - backend-net              # Solo alcanzable desde api, no desde frontend
+
+networks:
+  frontend-net:
+  backend-net:
+```
+
+### Exponer solo lo necesario
+
+```yaml
+services:
+  db:
+    ports:
+      - "127.0.0.1:5432:5432"   # Solo accesible desde el host, no desde la red
+    # En producción, omite ports por completo — accesible solo dentro de la red de Docker
+```
+
+## Estrategias de volúmenes
+
+```yaml
+volumes:
+  # Volumen con nombre: persiste entre reinicios del contenedor, gestionado por Docker
+  pgdata:
+
+  # Bind mount: mapea un directorio del host dentro del contenedor (para desarrollo)
+  # - ./src:/app/src
+
+  # Volumen anónimo: preserva contenido generado por el contenedor frente al override del bind mount
+  # - /app/node_modules
+```
+
+### Patrones comunes
+
+```yaml
+services:
+  app:
+    volumes:
+      - .:/app                   # Código fuente (bind mount para hot reload)
+      - /app/node_modules        # Protege el node_modules del contenedor frente al host
+      - /app/.next               # Protege la caché de build
+
+  db:
+    volumes:
+      - pgdata:/var/lib/postgresql/data          # Datos persistentes
+      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # Scripts de inicialización
+```
+
+## Seguridad de contenedores
+
+### Endurecimiento del Dockerfile
+
+```dockerfile
+# 1. Usa tags específicos (nunca :latest)
+FROM node:22.12-alpine3.20
+
+# 2. Ejecuta como usuario no-root
+RUN addgroup -g 1001 -S app && adduser -S app -u 1001
+USER app
+
+# 3. Elimina capabilities (en compose)
+# 4. Sistema de archivos raíz de solo lectura cuando sea posible
+# 5. Nada de secretos en las capas de la imagen
+```
+
+### Seguridad en Compose
+
+```yaml
+services:
+  app:
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /app/.cache
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE          # Solo si se enlaza a puertos < 1024
+```
+
+### Gestión de secretos
+
+```yaml
+# BIEN: usar variables de entorno (inyectadas en tiempo de ejecución)
+services:
+  app:
+    env_file:
+      - .env                     # Nunca commitear .env a git
+    environment:
+      - API_KEY                  # Hereda del entorno del host
+
+# BIEN: secretos de Docker (modo Swarm)
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+
+services:
+  db:
+    secrets:
+      - db_password
+
+# MAL: hardcodeado en la imagen
+# ENV API_KEY=sk-proj-xxxxx      # NUNCA HAGAS ESTO
+```
+
+## .dockerignore
+
+```
+node_modules
+.git
+.env
+.env.*
+dist
+coverage
+*.log
+.next
+.cache
+docker-compose*.yml
+Dockerfile*
+README.md
+tests/
+```
+
+## Depuración
+
+### Comandos comunes
+
+```bash
+# Ver logs
+docker compose logs -f app           # Seguir los logs de app
+docker compose logs --tail=50 db     # Últimas 50 líneas de db
+
+# Ejecutar comandos en un contenedor en marcha
+docker compose exec app sh           # Shell dentro de app
+docker compose exec db psql -U postgres  # Conectar a postgres
+
+# Inspeccionar
+docker compose ps                     # Servicios en ejecución
+docker compose top                    # Procesos de cada contenedor
+docker stats                          # Uso de recursos
+
+# Reconstruir
+docker compose up --build             # Reconstruir imágenes
+docker compose build --no-cache app   # Forzar reconstrucción completa
+
+# Limpiar
+docker compose down                   # Detener y eliminar contenedores
+docker compose down -v                # También elimina volúmenes (DESTRUCTIVO)
+docker system prune                   # Elimina imágenes/contenedores sin uso
+```
+
+### Depurar problemas de red
+
+```bash
+# Verificar la resolución DNS dentro del contenedor
+docker compose exec app nslookup db
+
+# Verificar conectividad
+docker compose exec app wget -qO- http://api:3000/health
+
+# Inspeccionar la red
+docker network ls
+docker network inspect <proyecto>_default
+```
+
+## Anti-patrones
+
+```
+# MAL: usar docker compose en producción sin orquestación
+# Usa Kubernetes, ECS o Docker Swarm para cargas multi-contenedor en producción
+
+# MAL: guardar datos en contenedores sin volúmenes
+# Los contenedores son efímeros — sin volúmenes, todos los datos se pierden al reiniciar
+
+# MAL: ejecutar como root
+# Crea y usa siempre un usuario no-root
+
+# MAL: usar el tag :latest
+# Fija versiones específicas para builds reproducibles
+
+# MAL: un contenedor gigante con todos los servicios
+# Separa responsabilidades: un proceso por contenedor
+
+# MAL: poner secretos en docker-compose.yml
+# Usa archivos .env (fuera de git) o secretos de Docker
+```

package/vendor/theus-arsenal/skills/patrones-dotnet/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: patrones-dotnet
+description: Patrones idiomáticos de C# y .NET; convenciones, inyección de dependencias,
+  async/await y buenas prácticas para construir aplicaciones .NET robustas y mantenibles.
+---
+
+# Patrones de desarrollo .NET
+
+Patrones idiomáticos de C# y .NET para construir aplicaciones robustas, performantes y mantenibles.
+
+## Cuándo usarla
+
+- Al escribir código C# nuevo.
+- Al revisar código C#.
+- Al refactorizar aplicaciones .NET existentes.
+- Al diseñar arquitecturas de servicios con ASP.NET Core.
+
+## Principios fundamentales
+
+### 1. Prefiere la inmutabilidad
+
+Usa records y propiedades init-only para los modelos de datos. La mutabilidad debe ser una decisión explícita y justificada.
+
+```csharp
+// Bien: objeto de valor inmutable
+public sealed record Money(decimal Amount, string Currency);
+
+// Bien: DTO inmutable con setters init
+public sealed class CreateOrderRequest
+{
+    public required string CustomerId { get; init; }
+    public required IReadOnlyList<OrderItem> Items { get; init; }
+}
+
+// Mal: modelo mutable con setters públicos
+public class Order
+{
+    public string CustomerId { get; set; }
+    public List<OrderItem> Items { get; set; }
+}
+```
+
+### 2. Explícito antes que implícito
+
+Sé claro con la nulabilidad, los modificadores de acceso y la intención.
+
+```csharp
+// Bien: modificadores de acceso y nulabilidad explícitos
+public sealed class UserService
+{
+    private readonly IUserRepository _repository;
+    private readonly ILogger<UserService> _logger;
+
+    public UserService(IUserRepository repository, ILogger<UserService> logger)
+    {
+        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task<User?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
+    {
+        return await _repository.FindByIdAsync(id, cancellationToken);
+    }
+}
+```
+
+### 3. Depende de abstracciones
+
+Usa interfaces en los límites de servicio. Regístralas en el contenedor de DI.
+
+```csharp
+// Bien: dependencia basada en interfaz
+public interface IOrderRepository
+{
+    Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    Task<IReadOnlyList<Order>> FindByCustomerAsync(string customerId, CancellationToken cancellationToken);
+    Task AddAsync(Order order, CancellationToken cancellationToken);
+}
+
+// Registro
+builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();
+```
+
+## Patrones async/await
+
+### Uso correcto de async
+
+```csharp
+// Bien: async de principio a fin, con CancellationToken
+public async Task<OrderSummary> GetOrderSummaryAsync(
+    Guid orderId,
+    CancellationToken cancellationToken)
+{
+    var order = await _repository.FindByIdAsync(orderId, cancellationToken)
+        ?? throw new NotFoundException($"Pedido {orderId} no encontrado");
+
+    var customer = await _customerService.GetAsync(order.CustomerId, cancellationToken);
+
+    return new OrderSummary(order, customer);
+}
+
+// Mal: bloquear sobre código async
+public OrderSummary GetOrderSummary(Guid orderId)
+{
+    var order = _repository.FindByIdAsync(orderId, CancellationToken.None).Result; // Riesgo de deadlock
+    return new OrderSummary(order);
+}
+```
+
+### Operaciones async en paralelo
+
+```csharp
+// Bien: operaciones independientes concurrentes
+public async Task<DashboardData> LoadDashboardAsync(CancellationToken cancellationToken)
+{
+    var ordersTask = _orderService.GetRecentAsync(cancellationToken);
+    var metricsTask = _metricsService.GetCurrentAsync(cancellationToken);
+    var alertsTask = _alertService.GetActiveAsync(cancellationToken);
+
+    await Task.WhenAll(ordersTask, metricsTask, alertsTask);
+
+    return new DashboardData(
+        Orders: await ordersTask,
+        Metrics: await metricsTask,
+        Alerts: await alertsTask);
+}
+```
+
+## Patrón Options
+
+Vincula secciones de configuración a objetos fuertemente tipados.
+
+```csharp
+public sealed class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public required string Host { get; init; }
+    public required int Port { get; init; }
+    public required string Username { get; init; }
+    public bool UseSsl { get; init; } = true;
+}
+
+// Registro
+builder.Services.Configure<SmtpOptions>(
+    builder.Configuration.GetSection(SmtpOptions.SectionName));
+
+// Uso vía inyección
+public class EmailService(IOptions<SmtpOptions> options)
+{
+    private readonly SmtpOptions _smtp = options.Value;
+}
+```
+
+## Patrón Result
+
+Devuelve éxito/fallo explícito en lugar de lanzar excepciones para fallos esperados.
+
+```csharp
+public sealed record Result<T>
+{
+    public bool IsSuccess { get; }
+    public T? Value { get; }
+    public string? Error { get; }
+
+    private Result(T value) { IsSuccess = true; Value = value; }
+    private Result(string error) { IsSuccess = false; Error = error; }
+
+    public static Result<T> Success(T value) => new(value);
+    public static Result<T> Failure(string error) => new(error);
+}
+
+// Uso
+public async Task<Result<Order>> PlaceOrderAsync(CreateOrderRequest request)
+{
+    if (request.Items.Count == 0)
+        return Result<Order>.Failure("El pedido debe contener al menos un artículo");
+
+    var order = Order.Create(request);
+    await _repository.AddAsync(order, CancellationToken.None);
+    return Result<Order>.Success(order);
+}
+```
+
+## Patrón Repository con EF Core
+
+```csharp
+public sealed class SqlOrderRepository : IOrderRepository
+{
+    private readonly AppDbContext _db;
+
+    public SqlOrderRepository(AppDbContext db) => _db = db;
+
+    public async Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
+    {
+        return await _db.Orders
+            .Include(o => o.Items)
+            .AsNoTracking()
+            .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);
+    }
+
+    public async Task<IReadOnlyList<Order>> FindByCustomerAsync(
+        string customerId,
+        CancellationToken cancellationToken)
+    {
+        return await _db.Orders
+            .Where(o => o.CustomerId == customerId)
+            .OrderByDescending(o => o.CreatedAt)
+            .AsNoTracking()
+            .ToListAsync(cancellationToken);
+    }
+
+    public async Task AddAsync(Order order, CancellationToken cancellationToken)
+    {
+        _db.Orders.Add(order);
+        await _db.SaveChangesAsync(cancellationToken);
+    }
+}
+```
+
+## Middleware y pipeline
+
+```csharp
+// Middleware personalizado
+public sealed class RequestTimingMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestTimingMiddleware> _logger;
+
+    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var stopwatch = Stopwatch.StartNew();
+        try
+        {
+            await _next(context);
+        }
+        finally
+        {
+            stopwatch.Stop();
+            _logger.LogInformation(
+                "Petición {Method} {Path} completada en {ElapsedMs}ms con estado {StatusCode}",
+                context.Request.Method,
+                context.Request.Path,
+                stopwatch.ElapsedMilliseconds,
+                context.Response.StatusCode);
+        }
+    }
+}
+```
+
+## Patrones de Minimal API
+
+```csharp
+// Organización con grupos de rutas
+var orders = app.MapGroup("/api/orders")
+    .RequireAuthorization()
+    .WithTags("Orders");
+
+orders.MapGet("/{id:guid}", async (
+    Guid id,
+    IOrderRepository repository,
+    CancellationToken cancellationToken) =>
+{
+    var order = await repository.FindByIdAsync(id, cancellationToken);
+    return order is not null
+        ? TypedResults.Ok(order)
+        : TypedResults.NotFound();
+});
+
+orders.MapPost("/", async (
+    CreateOrderRequest request,
+    IOrderService service,
+    CancellationToken cancellationToken) =>
+{
+    var result = await service.PlaceOrderAsync(request, cancellationToken);
+    return result.IsSuccess
+        ? TypedResults.Created($"/api/orders/{result.Value!.Id}", result.Value)
+        : TypedResults.BadRequest(result.Error);
+});
+```
+
+## Cláusulas de guarda
+
+```csharp
+// Bien: retornos tempranos con validación clara
+public async Task<ProcessResult> ProcessPaymentAsync(
+    PaymentRequest request,
+    CancellationToken cancellationToken)
+{
+    ArgumentNullException.ThrowIfNull(request);
+
+    if (request.Amount <= 0)
+        throw new ArgumentOutOfRangeException(nameof(request.Amount), "El monto debe ser positivo");
+
+    if (string.IsNullOrWhiteSpace(request.Currency))
+        throw new ArgumentException("La moneda es obligatoria", nameof(request.Currency));
+
+    // El camino feliz continúa aquí sin anidamiento
+    var gateway = _gatewayFactory.Create(request.Currency);
+    return await gateway.ChargeAsync(request, cancellationToken);
+}
+```
+
+## Antipatrones a evitar
+
+| Antipatrón | Corrección |
+|---|---|
+| Métodos `async void` | Devuelve `Task` (salvo manejadores de eventos) |
+| `.Result` o `.Wait()` | Usa `await` |
+| `catch (Exception) { }` | Maneja o relanza con contexto |
+| `new Service()` en constructores | Usa inyección por constructor |
+| Campos `public` | Usa propiedades con los accesores apropiados |
+| `dynamic` en lógica de negocio | Usa genéricos o tipos explícitos |
+| Estado `static` mutable | Usa scoping de DI o `ConcurrentDictionary` |
+| `string.Format` en bucles | Usa `StringBuilder` o interpolated string handlers |