theus-cli 0.2.83 → 0.2.84

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

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

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

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

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

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

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