theus-cli 0.2.82 → 0.2.84

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

@@ -1,363 +0,0 @@
----
-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

@@ -1,321 +0,0 @@
----
-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 |