theus-cli 0.2.83 → 0.2.84

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

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

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