theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/rules/java/patterns.md

@@ -0,0 +1,147 @@
+---
+paths:
+  - "**/*.java"
+---
+# Patrones de Java
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de Java.
+
+## Patrón Repository
+
+Encapsula el acceso a datos detrás de una interfaz:
+
+```java
+public interface OrderRepository {
+    Optional<Order> findById(Long id);
+    List<Order> findAll();
+    Order save(Order order);
+    void deleteById(Long id);
+}
+```
+
+Las implementaciones concretas se encargan de los detalles de almacenamiento (JPA, JDBC, en memoria para tests).
+
+## Capa de servicio
+
+La lógica de negocio vive en clases de servicio; mantén los controladores y repositorios delgados:
+
+```java
+public class OrderService {
+    private final OrderRepository orderRepository;
+    private final PaymentGateway paymentGateway;
+
+    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
+        this.orderRepository = orderRepository;
+        this.paymentGateway = paymentGateway;
+    }
+
+    public OrderSummary placeOrder(CreateOrderRequest request) {
+        var order = Order.from(request);
+        paymentGateway.charge(order.total());
+        var saved = orderRepository.save(order);
+        return OrderSummary.from(saved);
+    }
+}
+```
+
+## Inyección por constructor
+
+Usa siempre inyección por constructor — nunca inyección por campo:
+
+```java
+// BIEN — inyección por constructor (testeable, inmutable)
+public class NotificationService {
+    private final EmailSender emailSender;
+
+    public NotificationService(EmailSender emailSender) {
+        this.emailSender = emailSender;
+    }
+}
+
+// MAL — inyección por campo (no testeable sin reflexión, requiere magia del framework)
+public class NotificationService {
+    @Inject // o @Autowired
+    private EmailSender emailSender;
+}
+```
+
+## Mapeo de DTOs
+
+Usa records para los DTOs. Mapea en las fronteras de servicio/controlador:
+
+```java
+public record OrderResponse(Long id, String customer, BigDecimal total) {
+    public static OrderResponse from(Order order) {
+        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
+    }
+}
+```
+
+## Patrón Builder
+
+Úsalo para objetos con muchos parámetros opcionales:
+
+```java
+public class SearchCriteria {
+    private final String query;
+    private final int page;
+    private final int size;
+    private final String sortBy;
+
+    private SearchCriteria(Builder builder) {
+        this.query = builder.query;
+        this.page = builder.page;
+        this.size = builder.size;
+        this.sortBy = builder.sortBy;
+    }
+
+    public static class Builder {
+        private String query = "";
+        private int page = 0;
+        private int size = 20;
+        private String sortBy = "id";
+
+        public Builder query(String query) { this.query = query; return this; }
+        public Builder page(int page) { this.page = page; return this; }
+        public Builder size(int size) { this.size = size; return this; }
+        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
+        public SearchCriteria build() { return new SearchCriteria(this); }
+    }
+}
+```
+
+## Tipos sellados para modelos de dominio
+
+```java
+public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
+    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+}
+
+// Manejo exhaustivo (Java 21+)
+String message = switch (result) {
+    case PaymentSuccess s -> "Pagado: " + s.transactionId();
+    case PaymentFailure f -> "Falló: " + f.errorCode();
+};
+```
+
+## Envoltura de respuestas de API
+
+Respuestas de API consistentes:
+
+```java
+public record ApiResponse<T>(boolean success, T data, String error) {
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(true, data, null);
+    }
+    public static <T> ApiResponse<T> error(String message) {
+        return new ApiResponse<>(false, null, message);
+    }
+}
+```
+
+## Referencias
+
+Consulta la skill `patrones-springboot` para patrones de arquitectura con Spring Boot.
+Consulta la skill `patrones-quarkus` para patrones de arquitectura con Quarkus (REST, Panache y mensajería).
+Consulta la skill `patrones-jpa` para diseño de entidades y optimización de consultas.

package/vendor/theus-arsenal/rules/java/security.md

@@ -0,0 +1,101 @@
+---
+paths:
+  - "**/*.java"
+---
+# Seguridad en Java
+
+> Este archivo extiende [common/security.md](../common/security.md) con contenido específico de Java.
+
+## Gestión de secretos
+
+- Nunca escribas claves de API, tokens ni credenciales directamente en el código fuente
+- Usa variables de entorno: `System.getenv("API_KEY")`
+- Usa un gestor de secretos (Vault, AWS Secrets Manager) para los secretos de producción
+- Mantén los archivos de configuración locales con secretos en `.gitignore`
+
+```java
+// MAL
+private static final String API_KEY = "sk-abc123...";
+
+// BIEN — variable de entorno
+String apiKey = System.getenv("PAYMENT_API_KEY");
+Objects.requireNonNull(apiKey, "PAYMENT_API_KEY debe estar definida");
+```
+
+## Prevención de inyección SQL
+
+- Usa siempre consultas parametrizadas — nunca concatenes entrada del usuario en SQL
+- Usa `PreparedStatement` o la API de consultas parametrizadas de tu framework
+- Valida y sanitiza cualquier entrada usada en consultas nativas
+
+```java
+// MAL — inyección SQL por concatenación de strings
+Statement stmt = conn.createStatement();
+String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
+stmt.executeQuery(sql);
+
+// BIEN — PreparedStatement con consulta parametrizada
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
+ps.setString(1, name);
+
+// BIEN — plantilla JDBC
+jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
+```
+
+## Validación de entrada
+
+- Valida toda entrada del usuario en las fronteras del sistema antes de procesarla
+- Usa Bean Validation (`@NotNull`, `@NotBlank`, `@Size`) en los DTOs cuando uses un framework de validación
+- Sanitiza rutas de archivos y strings provenientes del usuario antes de usarlos
+- Rechaza la entrada que no pase la validación con mensajes de error claros
+
+```java
+// Validación manual en Java plano
+public Order createOrder(String customerName, BigDecimal amount) {
+    if (customerName == null || customerName.isBlank()) {
+        throw new IllegalArgumentException("El nombre del cliente es obligatorio");
+    }
+    if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
+        throw new IllegalArgumentException("El monto debe ser positivo");
+    }
+    return new Order(customerName, amount);
+}
+```
+
+## Autenticación y autorización
+
+- Nunca implementes criptografía de autenticación propia — usa bibliotecas consolidadas
+- Almacena contraseñas con bcrypt o Argon2, nunca MD5/SHA1
+- Aplica las comprobaciones de autorización en las fronteras de servicio
+- Elimina los datos sensibles de los logs — nunca registres contraseñas, tokens ni PII
+
+## Seguridad de dependencias
+
+- Ejecuta `mvn dependency:tree` o `./gradlew dependencies` para auditar las dependencias transitivas
+- Usa OWASP Dependency-Check o Snyk para escanear CVEs conocidas
+- Mantén las dependencias actualizadas — configura Dependabot o Renovate
+
+## Mensajes de error
+
+- Nunca expongas trazas de pila, rutas internas ni errores de SQL en las respuestas de la API
+- Mapea las excepciones a mensajes genéricos y seguros para el cliente en las fronteras de los manejadores
+- Registra los errores detallados en el servidor; devuelve mensajes genéricos a los clientes
+
+```java
+// Registra el detalle, devuelve un mensaje genérico
+try {
+    return orderService.findById(id);
+} catch (OrderNotFoundException ex) {
+    log.warn("Pedido no encontrado: id={}", id);
+    return ApiResponse.error("Recurso no encontrado");  // genérico, sin detalles internos
+} catch (Exception ex) {
+    log.error("Error inesperado procesando el pedido id={}", id, ex);
+    return ApiResponse.error("Error interno del servidor");  // nunca expongas ex.getMessage()
+}
+```
+
+## Referencias
+
+Consulta la skill `seguridad-springboot` para patrones de autenticación y autorización con Spring Security.
+Consulta la skill `seguridad-quarkus` para seguridad en Quarkus con JWT/OIDC, RBAC y CDI.
+Consulta la skill `revision-seguridad` para checklists de seguridad generales.

package/vendor/theus-arsenal/rules/java/testing.md

@@ -0,0 +1,133 @@
+---
+paths:
+  - "**/*.java"
+---
+# Testing en Java
+
+> Este archivo extiende [common/testing.md](../common/testing.md) con contenido específico de Java.
+
+## Framework de tests
+
+- **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
+- **AssertJ** para aserciones fluidas (`assertThat(result).isEqualTo(expected)`)
+- **Mockito** para simular dependencias
+- **Testcontainers** para tests de integración que requieren bases de datos o servicios
+
+## Organización de los tests
+
+```
+src/test/java/com/example/app/
+  service/           # Tests unitarios de la capa de servicio
+  controller/        # Tests de la capa web / API
+  repository/        # Tests de acceso a datos
+  integration/       # Tests de integración entre capas
+```
+
+Refleja la estructura de paquetes de `src/main/java` en `src/test/java`.
+
+## Patrón de test unitario
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() {
+        orderService = new OrderService(orderRepository);
+    }
+
+    @Test
+    @DisplayName("findById devuelve el pedido cuando existe")
+    void findById_existingOrder_returnsOrder() {
+        var order = new Order(1L, "Alice", BigDecimal.TEN);
+        when(orderRepository.findById(1L)).thenReturn(Optional.of(order));
+
+        var result = orderService.findById(1L);
+
+        assertThat(result.customerName()).isEqualTo("Alice");
+        verify(orderRepository).findById(1L);
+    }
+
+    @Test
+    @DisplayName("findById lanza excepción cuando el pedido no existe")
+    void findById_missingOrder_throws() {
+        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> orderService.findById(99L))
+            .isInstanceOf(OrderNotFoundException.class)
+            .hasMessageContaining("99");
+    }
+}
+```
+
+## Tests parametrizados
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "100.00, 10, 90.00",
+    "50.00, 0, 50.00",
+    "200.00, 25, 150.00"
+})
+@DisplayName("el descuento se aplica correctamente")
+void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
+    assertThat(PricingUtils.discount(price, pct)).isEqualByComparingTo(expected);
+}
+```
+
+## Tests de integración
+
+Usa Testcontainers para integración con una base de datos real:
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
+
+    private OrderRepository repository;
+
+    @BeforeEach
+    void setUp() {
+        var dataSource = new PGSimpleDataSource();
+        dataSource.setUrl(postgres.getJdbcUrl());
+        dataSource.setUser(postgres.getUsername());
+        dataSource.setPassword(postgres.getPassword());
+        repository = new JdbcOrderRepository(dataSource);
+    }
+
+    @Test
+    void save_and_findById() {
+        var saved = repository.save(new Order(null, "Bob", BigDecimal.ONE));
+        var found = repository.findById(saved.getId());
+        assertThat(found).isPresent();
+    }
+}
+```
+
+Para tests de integración con Spring Boot, consulta la skill `tdd-springboot`.
+Para tests de integración con Quarkus, consulta la skill `tdd-quarkus`.
+
+## Nombres de los tests
+
+Usa nombres descriptivos con `@DisplayName`:
+- `nombreMetodo_escenario_comportamientoEsperado()` para los nombres de métodos
+- `@DisplayName("descripción legible para humanos")` para los reportes
+
+## Cobertura
+
+- Apunta a 80%+ de cobertura de líneas
+- Usa JaCoCo para el reporte de cobertura
+- Céntrate en la lógica de servicio y de dominio — omite getters triviales y clases de configuración
+
+## Referencias
+
+Consulta la skill `tdd-springboot` para patrones de TDD en Spring Boot con MockMvc y Testcontainers.
+Consulta la skill `tdd-quarkus` para patrones de TDD en Quarkus con REST Assured y Dev Services.
+Consulta la skill `estandares-java` para las expectativas de testing.

package/vendor/theus-arsenal/rules/kotlin/coding-style.md

@@ -0,0 +1,86 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Estilo de código Kotlin
+
+> Este archivo extiende [common/coding-style.md](../common/coding-style.md) con contenido específico de Kotlin.
+
+## Formato
+
+- **ktlint** o **Detekt** para hacer cumplir el estilo
+- Estilo de código oficial de Kotlin (`kotlin.code.style=official` en `gradle.properties`)
+
+## Inmutabilidad
+
+- Prefiere `val` sobre `var` — usa `val` por defecto y `var` solo cuando la mutación sea necesaria
+- Usa `data class` para tipos de valor; usa colecciones inmutables (`List`, `Map`, `Set`) en las APIs públicas
+- Copia al escribir para actualizar estado: `state.copy(field = newValue)`
+
+## Nombres
+
+Sigue las convenciones de Kotlin:
+- `camelCase` para funciones y propiedades
+- `PascalCase` para clases, interfaces, objects y alias de tipo
+- `SCREAMING_SNAKE_CASE` para constantes (`const val` o `@JvmStatic`)
+- Nombra las interfaces por su comportamiento, sin prefijo `I`: `Clickable`, no `IClickable`
+
+## Null safety
+
+- Nunca uses `!!` — prefiere `?.`, `?:`, `requireNotNull()` o `checkNotNull()`
+- Usa `?.let {}` para operaciones null-safe con alcance limitado
+- Devuelve tipos anulables desde funciones que legítimamente pueden no tener resultado
+
+```kotlin
+// MAL
+val name = user!!.name
+
+// BIEN
+val name = user?.name ?: "Desconocido"
+val name = requireNotNull(user) { "User debe estar definido antes de acceder a name" }.name
+```
+
+## Tipos sellados
+
+Usa clases/interfaces selladas para modelar jerarquías de estado cerradas:
+
+```kotlin
+sealed interface UiState<out T> {
+    data object Loading : UiState<Nothing>
+    data class Success<T>(val data: T) : UiState<T>
+    data class Error(val message: String) : UiState<Nothing>
+}
+```
+
+Usa siempre `when` exhaustivo con tipos sellados — sin rama `else`.
+
+## Funciones de extensión
+
+Usa funciones de extensión para operaciones utilitarias, pero mantenlas descubribles:
+- Colócalas en un archivo nombrado según el tipo receptor (`StringExt.kt`, `FlowExt.kt`)
+- Limita su alcance — no agregues extensiones a `Any` ni a tipos demasiado genéricos
+
+## Funciones de alcance (scope functions)
+
+Usa la función de alcance adecuada:
+- `let` — comprobación de nulo + transformación: `user?.let { greet(it) }`
+- `run` — calcular un resultado usando el receptor: `service.run { fetch(config) }`
+- `apply` — configurar un objeto: `builder.apply { timeout = 30 }`
+- `also` — efectos secundarios: `result.also { log(it) }`
+- Evita anidar funciones de alcance en profundidad (máximo 2 niveles)
+
+## Manejo de errores
+
+- Usa `Result<T>` o tipos sellados propios
+- Usa `runCatching {}` para envolver código que puede lanzar excepciones
+- Nunca captures `CancellationException` — siempre relánzala
+- Evita `try-catch` como flujo de control
+
+```kotlin
+// MAL — usar excepciones como flujo de control
+val user = try { repository.getUser(id) } catch (e: NotFoundException) { null }
+
+// BIEN — retorno anulable
+val user: User? = repository.findUser(id)
+```

package/vendor/theus-arsenal/rules/kotlin/hooks.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/build.gradle.kts"
+---
+# Hooks para Kotlin
+
+> Este archivo extiende [common/hooks.md](../common/hooks.md) con contenido específico de Kotlin.
+
+## Hooks PostToolUse
+
+Configúralos en `~/.theus/settings.json`:
+
+- **ktfmt/ktlint**: formatea automáticamente los archivos `.kt` y `.kts` después de editarlos
+- **detekt**: ejecuta análisis estático después de editar archivos Kotlin
+- **./gradlew build**: verifica la compilación después de los cambios

package/vendor/theus-arsenal/rules/kotlin/patterns.md

@@ -0,0 +1,146 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Patrones de Kotlin
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de Kotlin y Android/KMP.
+
+## Inyección de dependencias
+
+Prefiere la inyección por constructor. Usa Koin (KMP) o Hilt (solo Android):
+
+```kotlin
+// Koin — declarar módulos
+val dataModule = module {
+    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
+    factory { GetItemsUseCase(get()) }
+    viewModelOf(::ItemListViewModel)
+}
+
+// Hilt — anotaciones
+@HiltViewModel
+class ItemListViewModel @Inject constructor(
+    private val getItems: GetItemsUseCase
+) : ViewModel()
+```
+
+## Patrón ViewModel
+
+Un solo objeto de estado, receptor de eventos, flujo de datos unidireccional:
+
+```kotlin
+data class ScreenState(
+    val items: List<Item> = emptyList(),
+    val isLoading: Boolean = false
+)
+
+class ScreenViewModel(private val useCase: GetItemsUseCase) : ViewModel() {
+    private val _state = MutableStateFlow(ScreenState())
+    val state = _state.asStateFlow()
+
+    fun onEvent(event: ScreenEvent) {
+        when (event) {
+            is ScreenEvent.Load -> load()
+            is ScreenEvent.Delete -> delete(event.id)
+        }
+    }
+}
+```
+
+## Patrón Repository
+
+- Las funciones `suspend` devuelven `Result<T>` o un tipo de error propio
+- `Flow` para streams reactivos
+- Coordina las fuentes de datos locales y remotas
+
+```kotlin
+interface ItemRepository {
+    suspend fun getById(id: String): Result<Item>
+    suspend fun getAll(): Result<List<Item>>
+    fun observeAll(): Flow<List<Item>>
+}
+```
+
+## Patrón UseCase
+
+Responsabilidad única, `operator fun invoke`:
+
+```kotlin
+class GetItemUseCase(private val repository: ItemRepository) {
+    suspend operator fun invoke(id: String): Result<Item> {
+        return repository.getById(id)
+    }
+}
+
+class GetItemsUseCase(private val repository: ItemRepository) {
+    suspend operator fun invoke(): Result<List<Item>> {
+        return repository.getAll()
+    }
+}
+```
+
+## expect/actual (KMP)
+
+Úsalo para implementaciones específicas de plataforma:
+
+```kotlin
+// commonMain
+expect fun platformName(): String
+expect class SecureStorage {
+    fun save(key: String, value: String)
+    fun get(key: String): String?
+}
+
+// androidMain
+actual fun platformName(): String = "Android"
+actual class SecureStorage {
+    actual fun save(key: String, value: String) { /* EncryptedSharedPreferences */ }
+    actual fun get(key: String): String? = null /* ... */
+}
+
+// iosMain
+actual fun platformName(): String = "iOS"
+actual class SecureStorage {
+    actual fun save(key: String, value: String) { /* Keychain */ }
+    actual fun get(key: String): String? = null /* ... */
+}
+```
+
+## Patrones de corrutinas
+
+- Usa `viewModelScope` en los ViewModels y `coroutineScope` para trabajo hijo estructurado
+- Usa `stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initialValue)` para obtener StateFlow a partir de Flows fríos
+- Usa `supervisorScope` cuando los fallos de los hijos deban ser independientes
+
+## Patrón Builder con DSL
+
+```kotlin
+class HttpClientConfig {
+    var baseUrl: String = ""
+    var timeout: Long = 30_000
+    private val interceptors = mutableListOf<Interceptor>()
+
+    fun interceptor(block: () -> Interceptor) {
+        interceptors.add(block())
+    }
+}
+
+fun httpClient(block: HttpClientConfig.() -> Unit): HttpClient {
+    val config = HttpClientConfig().apply(block)
+    return HttpClient(config)
+}
+
+// Uso
+val client = httpClient {
+    baseUrl = "https://api.example.com"
+    timeout = 15_000
+    interceptor { AuthInterceptor(tokenProvider) }
+}
+```
+
+## Referencias
+
+Consulta la skill `corrutinas-flows-kotlin` para patrones de corrutinas en detalle.
+Consulta la skill `arquitectura-limpia-android` para patrones de módulos y capas.