theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,314 @@
+---
+name: patrones-springboot
+description: Patrones de arquitectura Spring Boot, diseño de APIs REST, servicios por capas, acceso a
+  datos, caché, procesamiento asíncrono y logging. Úsala para trabajo de backend en Java con Spring Boot.
+---
+
+# Patrones de desarrollo con Spring Boot
+
+Arquitectura y patrones de API de Spring Boot para servicios escalables y de grado productivo.
+
+## Cuándo activarla
+
+- Al construir APIs REST con Spring MVC o WebFlux
+- Al estructurar las capas controlador → servicio → repositorio
+- Al configurar Spring Data JPA, caché o procesamiento asíncrono
+- Al añadir validación, manejo de excepciones o paginación
+- Al configurar perfiles para entornos de dev/staging/producción
+- Al implementar patrones dirigidos por eventos con Spring Events o Kafka
+
+## Estructura de una API REST
+
+```java
+@RestController
+@RequestMapping("/api/markets")
+@Validated
+class MarketController {
+  private final MarketService marketService;
+
+  MarketController(MarketService marketService) {
+    this.marketService = marketService;
+  }
+
+  @GetMapping
+  ResponseEntity<Page<MarketResponse>> list(
+      @RequestParam(defaultValue = "0") int page,
+      @RequestParam(defaultValue = "20") int size) {
+    Page<Market> markets = marketService.list(PageRequest.of(page, size));
+    return ResponseEntity.ok(markets.map(MarketResponse::from));
+  }
+
+  @PostMapping
+  ResponseEntity<MarketResponse> create(@Valid @RequestBody CreateMarketRequest request) {
+    Market market = marketService.create(request);
+    return ResponseEntity.status(HttpStatus.CREATED).body(MarketResponse.from(market));
+  }
+}
+```
+
+## Patrón de repositorio (Spring Data JPA)
+
+```java
+public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
+  @Query("select m from MarketEntity m where m.status = :status order by m.volume desc")
+  List<MarketEntity> findActive(@Param("status") MarketStatus status, Pageable pageable);
+}
+```
+
+## Capa de servicio con transacciones
+
+```java
+@Service
+public class MarketService {
+  private final MarketRepository repo;
+
+  public MarketService(MarketRepository repo) {
+    this.repo = repo;
+  }
+
+  @Transactional
+  public Market create(CreateMarketRequest request) {
+    MarketEntity entity = MarketEntity.from(request);
+    MarketEntity saved = repo.save(entity);
+    return Market.from(saved);
+  }
+}
+```
+
+## DTOs y validación
+
+```java
+public record CreateMarketRequest(
+    @NotBlank @Size(max = 200) String name,
+    @NotBlank @Size(max = 2000) String description,
+    @NotNull @FutureOrPresent Instant endDate,
+    @NotEmpty List<@NotBlank String> categories) {}
+
+public record MarketResponse(Long id, String name, MarketStatus status) {
+  static MarketResponse from(Market market) {
+    return new MarketResponse(market.id(), market.name(), market.status());
+  }
+}
+```
+
+## Manejo de excepciones
+
+```java
+@ControllerAdvice
+class GlobalExceptionHandler {
+  @ExceptionHandler(MethodArgumentNotValidException.class)
+  ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
+    String message = ex.getBindingResult().getFieldErrors().stream()
+        .map(e -> e.getField() + ": " + e.getDefaultMessage())
+        .collect(Collectors.joining(", "));
+    return ResponseEntity.badRequest().body(ApiError.validation(message));
+  }
+
+  @ExceptionHandler(AccessDeniedException.class)
+  ResponseEntity<ApiError> handleAccessDenied() {
+    return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiError.of("Forbidden"));
+  }
+
+  @ExceptionHandler(Exception.class)
+  ResponseEntity<ApiError> handleGeneric(Exception ex) {
+    // Registrar errores inesperados con la traza de la pila
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .body(ApiError.of("Internal server error"));
+  }
+}
+```
+
+## Caché
+
+Requiere `@EnableCaching` en una clase de configuración.
+
+```java
+@Service
+public class MarketCacheService {
+  private final MarketRepository repo;
+
+  public MarketCacheService(MarketRepository repo) {
+    this.repo = repo;
+  }
+
+  @Cacheable(value = "market", key = "#id")
+  public Market getById(Long id) {
+    return repo.findById(id)
+        .map(Market::from)
+        .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+  }
+
+  @CacheEvict(value = "market", key = "#id")
+  public void evict(Long id) {}
+}
+```
+
+## Procesamiento asíncrono
+
+Requiere `@EnableAsync` en una clase de configuración.
+
+```java
+@Service
+public class NotificationService {
+  @Async
+  public CompletableFuture<Void> sendAsync(Notification notification) {
+    // enviar email/SMS
+    return CompletableFuture.completedFuture(null);
+  }
+}
+```
+
+## Logging (SLF4J)
+
+```java
+@Service
+public class ReportService {
+  private static final Logger log = LoggerFactory.getLogger(ReportService.class);
+
+  public Report generate(Long marketId) {
+    log.info("generate_report marketId={}", marketId);
+    try {
+      // lógica
+    } catch (Exception ex) {
+      log.error("generate_report_failed marketId={}", marketId, ex);
+      throw ex;
+    }
+    return new Report();
+  }
+}
+```
+
+## Middleware / Filtros
+
+```java
+@Component
+public class RequestLoggingFilter extends OncePerRequestFilter {
+  private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain filterChain) throws ServletException, IOException {
+    long start = System.currentTimeMillis();
+    try {
+      filterChain.doFilter(request, response);
+    } finally {
+      long duration = System.currentTimeMillis() - start;
+      log.info("req method={} uri={} status={} durationMs={}",
+          request.getMethod(), request.getRequestURI(), response.getStatus(), duration);
+    }
+  }
+}
+```
+
+## Paginación y ordenamiento
+
+```java
+PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
+Page<Market> results = marketService.list(page);
+```
+
+## Llamadas externas resilientes a errores
+
+```java
+public <T> T withRetry(Supplier<T> supplier, int maxRetries) {
+  int attempts = 0;
+  while (true) {
+    try {
+      return supplier.get();
+    } catch (Exception ex) {
+      attempts++;
+      if (attempts >= maxRetries) {
+        throw ex;
+      }
+      try {
+        Thread.sleep((long) Math.pow(2, attempts) * 100L);
+      } catch (InterruptedException ie) {
+        Thread.currentThread().interrupt();
+        throw ex;
+      }
+    }
+  }
+}
+```
+
+## Rate limiting (Filtro + Bucket4j)
+
+**Nota de seguridad**: la cabecera `X-Forwarded-For` no es confiable por defecto porque los clientes pueden falsificarla.
+Usa cabeceras reenviadas solo cuando:
+1. Tu app está detrás de un proxy inverso confiable (nginx, AWS ALB, etc.)
+2. Has registrado `ForwardedHeaderFilter` como bean
+3. Has configurado `server.forward-headers-strategy=NATIVE` o `FRAMEWORK` en las propiedades de la aplicación
+4. Tu proxy está configurado para sobrescribir (no anexar a) la cabecera `X-Forwarded-For`
+
+Cuando `ForwardedHeaderFilter` está correctamente configurado, `request.getRemoteAddr()` devolverá
+automáticamente la IP correcta del cliente a partir de las cabeceras reenviadas. Sin esta configuración, usa
+`request.getRemoteAddr()` directamente: devuelve la IP de la conexión inmediata, que es el único
+valor confiable.
+
+```java
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+  /*
+   * SEGURIDAD: Este filtro usa request.getRemoteAddr() para identificar clientes en el rate limiting.
+   *
+   * Si tu aplicación está detrás de un proxy inverso (nginx, AWS ALB, etc.), DEBES configurar
+   * Spring para que maneje las cabeceras reenviadas correctamente y así detectar bien la IP del cliente:
+   *
+   * 1. Establece server.forward-headers-strategy=NATIVE (para plataformas cloud) o FRAMEWORK en
+   *    application.properties/yaml
+   * 2. Si usas la estrategia FRAMEWORK, registra ForwardedHeaderFilter:
+   *
+   *    @Bean
+   *    ForwardedHeaderFilter forwardedHeaderFilter() {
+   *        return new ForwardedHeaderFilter();
+   *    }
+   *
+   * 3. Asegúrate de que tu proxy sobrescriba (no anexe) la cabecera X-Forwarded-For para evitar falsificación
+   * 4. Configura server.tomcat.remoteip.trusted-proxies o su equivalente para tu contenedor
+   *
+   * Sin esta configuración, request.getRemoteAddr() devuelve la IP del proxy, no la del cliente.
+   * NO leas X-Forwarded-For directamente: es trivialmente falsificable sin un manejo de proxy confiable.
+   */
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain filterChain) throws ServletException, IOException {
+    // Usa getRemoteAddr(), que devuelve la IP correcta del cliente cuando ForwardedHeaderFilter
+    // está configurado, o la IP de conexión directa en caso contrario. Nunca confíes en las
+    // cabeceras X-Forwarded-For directamente sin una configuración de proxy adecuada.
+    String clientIp = request.getRemoteAddr();
+
+    Bucket bucket = buckets.computeIfAbsent(clientIp,
+        k -> Bucket.builder()
+            .addLimit(Bandwidth.classic(100, Refill.greedy(100, Duration.ofMinutes(1))))
+            .build());
+
+    if (bucket.tryConsume(1)) {
+      filterChain.doFilter(request, response);
+    } else {
+      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
+    }
+  }
+}
+```
+
+## Trabajos en segundo plano
+
+Usa `@Scheduled` de Spring o intégralo con colas (p. ej., Kafka, SQS, RabbitMQ). Mantén los manejadores idempotentes y observables.
+
+## Observabilidad
+
+- Logging estructurado (JSON) mediante el encoder de Logback
+- Métricas: Micrometer + Prometheus/OTel
+- Trazas: Micrometer Tracing con backend OpenTelemetry o Brave
+
+## Valores por defecto de producción
+
+- Prefiere la inyección por constructor, evita la inyección por campo
+- Activa `spring.mvc.problemdetails.enabled=true` para errores RFC 7807 (Spring Boot 3+)
+- Configura los tamaños del pool de HikariCP según la carga de trabajo, define timeouts
+- Usa `@Transactional(readOnly = true)` para las consultas
+- Impón null-safety mediante `@NonNull` y `Optional` donde corresponda
+
+**Recuerda**: mantén los controladores delgados, los servicios enfocados, los repositorios simples y los errores manejados de forma centralizada. Optimiza para mantenibilidad y testabilidad.

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

@@ -0,0 +1,261 @@
+---
+name: patrones-swiftui
+description: Patrones de arquitectura SwiftUI — gestión de estado con @Observable, composición de vistas,
+  navegación type-safe, optimización de rendimiento y buenas prácticas modernas de UI para iOS/macOS.
+---
+
+# Patrones de SwiftUI
+
+Patrones modernos de SwiftUI para construir interfaces declarativas y performantes en las plataformas de Apple. Cubre el framework Observation, la composición de vistas, la navegación type-safe y la optimización de rendimiento.
+
+## Cuándo usarla
+
+- Al construir vistas SwiftUI y gestionar estado (`@State`, `@Observable`, `@Binding`).
+- Al diseñar flujos de navegación con `NavigationStack`.
+- Al estructurar view models y flujo de datos.
+- Al optimizar el rendimiento de renderizado en listas y layouts complejos.
+- Al trabajar con valores de entorno e inyección de dependencias en SwiftUI.
+
+## Gestión de estado
+
+### Selección del property wrapper
+
+Elige el wrapper más simple que encaje:
+
+| Wrapper | Caso de uso |
+|---------|-------------|
+| `@State` | Tipos por valor locales a la vista (toggles, campos de formulario, presentación de sheets) |
+| `@Binding` | Referencia bidireccional al `@State` del padre |
+| Clase `@Observable` + `@State` | Modelo propio con múltiples propiedades |
+| Clase `@Observable` (sin wrapper) | Referencia de solo lectura pasada desde el padre |
+| `@Bindable` | Binding bidireccional a una propiedad de un `@Observable` |
+| `@Environment` | Dependencias compartidas inyectadas vía `.environment()` |
+
+### ViewModel con @Observable
+
+Usa `@Observable` (no `ObservableObject`) — rastrea cambios a nivel de propiedad, así SwiftUI solo re-renderiza las vistas que leen la propiedad cambiada:
+
+```swift
+@Observable
+final class ItemListViewModel {
+    private(set) var items: [Item] = []
+    private(set) var isLoading = false
+    var searchText = ""
+
+    private let repository: any ItemRepository
+
+    init(repository: any ItemRepository = DefaultItemRepository()) {
+        self.repository = repository
+    }
+
+    func load() async {
+        isLoading = true
+        defer { isLoading = false }
+        items = (try? await repository.fetchAll()) ?? []
+    }
+}
+```
+
+### Vista que consume el ViewModel
+
+```swift
+struct ItemListView: View {
+    @State private var viewModel: ItemListViewModel
+
+    init(viewModel: ItemListViewModel = ItemListViewModel()) {
+        _viewModel = State(initialValue: viewModel)
+    }
+
+    var body: some View {
+        List(viewModel.items) { item in
+            ItemRow(item: item)
+        }
+        .searchable(text: $viewModel.searchText)
+        .overlay { if viewModel.isLoading { ProgressView() } }
+        .task { await viewModel.load() }
+    }
+}
+```
+
+### Inyección por entorno
+
+Reemplaza `@EnvironmentObject` por `@Environment`:
+
+```swift
+// Inyectar
+ContentView()
+    .environment(authManager)
+
+// Consumir
+struct ProfileView: View {
+    @Environment(AuthManager.self) private var auth
+
+    var body: some View {
+        Text(auth.currentUser?.name ?? "Invitado")
+    }
+}
+```
+
+## Composición de vistas
+
+### Extrae subvistas para acotar la invalidación
+
+Divide las vistas en structs pequeños y enfocados. Cuando cambia el estado, solo se re-renderiza la subvista que lo lee:
+
+```swift
+struct OrderView: View {
+    @State private var viewModel = OrderViewModel()
+
+    var body: some View {
+        VStack {
+            OrderHeader(title: viewModel.title)
+            OrderItemList(items: viewModel.items)
+            OrderTotal(total: viewModel.total)
+        }
+    }
+}
+```
+
+### ViewModifier para estilos reutilizables
+
+```swift
+struct CardModifier: ViewModifier {
+    func body(content: Content) -> some View {
+        content
+            .padding()
+            .background(.regularMaterial)
+            .clipShape(RoundedRectangle(cornerRadius: 12))
+    }
+}
+
+extension View {
+    func cardStyle() -> some View {
+        modifier(CardModifier())
+    }
+}
+```
+
+## Navegación
+
+### NavigationStack type-safe
+
+Usa `NavigationStack` con `NavigationPath` para enrutado programático y con tipos seguros:
+
+```swift
+@Observable
+final class Router {
+    var path = NavigationPath()
+
+    func navigate(to destination: Destination) {
+        path.append(destination)
+    }
+
+    func popToRoot() {
+        path = NavigationPath()
+    }
+}
+
+enum Destination: Hashable {
+    case detail(Item.ID)
+    case settings
+    case profile(User.ID)
+}
+
+struct RootView: View {
+    @State private var router = Router()
+
+    var body: some View {
+        NavigationStack(path: $router.path) {
+            HomeView()
+                .navigationDestination(for: Destination.self) { dest in
+                    switch dest {
+                    case .detail(let id): ItemDetailView(itemID: id)
+                    case .settings: SettingsView()
+                    case .profile(let id): ProfileView(userID: id)
+                    }
+                }
+        }
+        .environment(router)
+    }
+}
+```
+
+## Rendimiento
+
+### Usa contenedores lazy para colecciones grandes
+
+`LazyVStack` y `LazyHStack` crean las vistas solo cuando son visibles:
+
+```swift
+ScrollView {
+    LazyVStack(spacing: 8) {
+        ForEach(items) { item in
+            ItemRow(item: item)
+        }
+    }
+}
+```
+
+### Identificadores estables
+
+Usa siempre IDs estables y únicos en `ForEach` — evita los índices del array:
+
+```swift
+// Usa conformance a Identifiable o un id explícito
+ForEach(items, id: \.stableID) { item in
+    ItemRow(item: item)
+}
+```
+
+### Evita trabajo costoso en body
+
+- Nunca hagas I/O, llamadas de red ni cómputo pesado dentro de `body`.
+- Usa `.task {}` para trabajo asíncrono — se cancela automáticamente cuando la vista desaparece.
+- Usa `.sensoryFeedback()` y `.geometryGroup()` con moderación en scroll views.
+- Minimiza `.shadow()`, `.blur()` y `.mask()` en listas — disparan renderizado fuera de pantalla.
+
+### Conformance a Equatable
+
+Para vistas con bodies costosos, conforma a `Equatable` para saltar re-renderizados innecesarios:
+
+```swift
+struct ExpensiveChartView: View, Equatable {
+    let dataPoints: [DataPoint] // DataPoint debe conformar a Equatable
+
+    static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.dataPoints == rhs.dataPoints
+    }
+
+    var body: some View {
+        // Renderizado complejo del gráfico
+    }
+}
+```
+
+## Previews
+
+Usa el macro `#Preview` con datos mock inline para iterar rápido:
+
+```swift
+#Preview("Estado vacío") {
+    ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository()))
+}
+
+#Preview("Con datos") {
+    ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository()))
+}
+```
+
+## Antipatrones a evitar
+
+- Usar `ObservableObject` / `@Published` / `@StateObject` / `@EnvironmentObject` en código nuevo — migra a `@Observable`.
+- Poner trabajo asíncrono directamente en `body` o `init` — usa `.task {}` o métodos de carga explícitos.
+- Crear view models como `@State` dentro de vistas hijas que no son dueñas de los datos — pásalos desde el padre.
+- Usar el borrado de tipos con `AnyView` — prefiere `@ViewBuilder` o `Group` para vistas condicionales.
+- Ignorar los requisitos de `Sendable` al pasar datos hacia/desde actores.
+
+## Skills relacionadas
+
+- `persistencia-actores-swift` — patrones de persistencia basados en actores.
+- `testing-protocolos-di-swift` — DI por protocolos y testing con Swift Testing.
+- `concurrencia-swift-6-2` — modelo de concurrencia de Swift 6.2.