@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/rules/java/security.md

@@ -0,0 +1,100 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Security
+
+> This file extends [common/security.md](../common/security.md) with Java-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Use environment variables: `System.getenv("API_KEY")`
+- Use a secret manager (Vault, AWS Secrets Manager) for production secrets
+- Keep local config files with secrets in `.gitignore`
+
+```java
+// BAD
+private static final String API_KEY = "sk-abc123...";
+
+// GOOD — environment variable
+String apiKey = System.getenv("PAYMENT_API_KEY");
+Objects.requireNonNull(apiKey, "PAYMENT_API_KEY must be set");
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries — never concatenate user input into SQL
+- Use `PreparedStatement` or your framework's parameterized query API
+- Validate and sanitize any input used in native queries
+
+```java
+// BAD — SQL injection via string concatenation
+Statement stmt = conn.createStatement();
+String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
+stmt.executeQuery(sql);
+
+// GOOD — PreparedStatement with parameterized query
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
+ps.setString(1, name);
+
+// GOOD — JDBC template
+jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
+```
+
+## Input Validation
+
+- Validate all user input at system boundaries before processing
+- Use Bean Validation (`@NotNull`, `@NotBlank`, `@Size`) on DTOs when using a validation framework
+- Sanitize file paths and user-provided strings before use
+- Reject input that fails validation with clear error messages
+
+```java
+// Validate manually in plain Java
+public Order createOrder(String customerName, BigDecimal amount) {
+    if (customerName == null || customerName.isBlank()) {
+        throw new IllegalArgumentException("Customer name is required");
+    }
+    if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
+        throw new IllegalArgumentException("Amount must be positive");
+    }
+    return new Order(customerName, amount);
+}
+```
+
+## Authentication and Authorization
+
+- Never implement custom auth crypto — use established libraries
+- Store passwords with bcrypt or Argon2, never MD5/SHA1
+- Enforce authorization checks at service boundaries
+- Clear sensitive data from logs — never log passwords, tokens, or PII
+
+## Dependency Security
+
+- Run `mvn dependency:tree` or `./gradlew dependencies` to audit transitive dependencies
+- Use OWASP Dependency-Check or Snyk to scan for known CVEs
+- Keep dependencies updated — set up Dependabot or Renovate
+
+## Error Messages
+
+- Never expose stack traces, internal paths, or SQL errors in API responses
+- Map exceptions to safe, generic client messages at handler boundaries
+- Log detailed errors server-side; return generic messages to clients
+
+```java
+// Log the detail, return a generic message
+try {
+    return orderService.findById(id);
+} catch (OrderNotFoundException ex) {
+    log.warn("Order not found: id={}", id);
+    return ApiResponse.error("Resource not found");  // generic, no internals
+} catch (Exception ex) {
+    log.error("Unexpected error processing order id={}", id, ex);
+    return ApiResponse.error("Internal server error");  // never expose ex.getMessage()
+}
+```
+
+## References
+
+See skill: `springboot-security` for Spring Security authentication and authorization patterns.
+See skill: `security-review` for general security checklists.

package/.agent/rules/java/testing.md

@@ -0,0 +1,131 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Java-specific content.
+
+## Test Framework
+
+- **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
+- **AssertJ** for fluent assertions (`assertThat(result).isEqualTo(expected)`)
+- **Mockito** for mocking dependencies
+- **Testcontainers** for integration tests requiring databases or services
+
+## Test Organization
+
+```
+src/test/java/com/example/app/
+  service/           # Unit tests for service layer
+  controller/        # Web layer / API tests
+  repository/        # Data access tests
+  integration/       # Cross-layer integration tests
+```
+
+Mirror the `src/main/java` package structure in `src/test/java`.
+
+## Unit Test Pattern
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() {
+        orderService = new OrderService(orderRepository);
+    }
+
+    @Test
+    @DisplayName("findById returns order when exists")
+    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 throws when order not found")
+    void findById_missingOrder_throws() {
+        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> orderService.findById(99L))
+            .isInstanceOf(OrderNotFoundException.class)
+            .hasMessageContaining("99");
+    }
+}
+```
+
+## Parameterized Tests
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "100.00, 10, 90.00",
+    "50.00, 0, 50.00",
+    "200.00, 25, 150.00"
+})
+@DisplayName("discount applied correctly")
+void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
+    assertThat(PricingUtils.discount(price, pct)).isEqualByComparingTo(expected);
+}
+```
+
+## Integration Tests
+
+Use Testcontainers for real database integration:
+
+```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();
+    }
+}
+```
+
+For Spring Boot integration tests, see skill: `springboot-tdd`.
+
+## Test Naming
+
+Use descriptive names with `@DisplayName`:
+- `methodName_scenario_expectedBehavior()` for method names
+- `@DisplayName("human-readable description")` for reports
+
+## Coverage
+
+- Target 80%+ line coverage
+- Use JaCoCo for coverage reporting
+- Focus on service and domain logic — skip trivial getters/config classes
+
+## References
+
+See skill: `springboot-tdd` for Spring Boot TDD patterns with MockMvc and Testcontainers.
+See skill: `java-coding-standards` for testing expectations.

package/.agent/rules/kotlin/coding-style.md

@@ -0,0 +1,86 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Kotlin-specific content.
+
+## Formatting
+
+- **ktlint** or **Detekt** for style enforcement
+- Official Kotlin code style (`kotlin.code.style=official` in `gradle.properties`)
+
+## Immutability
+
+- Prefer `val` over `var` — default to `val` and only use `var` when mutation is required
+- Use `data class` for value types; use immutable collections (`List`, `Map`, `Set`) in public APIs
+- Copy-on-write for state updates: `state.copy(field = newValue)`
+
+## Naming
+
+Follow Kotlin conventions:
+- `camelCase` for functions and properties
+- `PascalCase` for classes, interfaces, objects, and type aliases
+- `SCREAMING_SNAKE_CASE` for constants (`const val` or `@JvmStatic`)
+- Prefix interfaces with behavior, not `I`: `Clickable` not `IClickable`
+
+## Null Safety
+
+- Never use `!!` — prefer `?.`, `?:`, `requireNotNull()`, or `checkNotNull()`
+- Use `?.let {}` for scoped null-safe operations
+- Return nullable types from functions that can legitimately have no result
+
+```kotlin
+// BAD
+val name = user!!.name
+
+// GOOD
+val name = user?.name ?: "Unknown"
+val name = requireNotNull(user) { "User must be set before accessing name" }.name
+```
+
+## Sealed Types
+
+Use sealed classes/interfaces to model closed state hierarchies:
+
+```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>
+}
+```
+
+Always use exhaustive `when` with sealed types — no `else` branch.
+
+## Extension Functions
+
+Use extension functions for utility operations, but keep them discoverable:
+- Place in a file named after the receiver type (`StringExt.kt`, `FlowExt.kt`)
+- Keep scope limited — don't add extensions to `Any` or overly generic types
+
+## Scope Functions
+
+Use the right scope function:
+- `let` — null check + transform: `user?.let { greet(it) }`
+- `run` — compute a result using receiver: `service.run { fetch(config) }`
+- `apply` — configure an object: `builder.apply { timeout = 30 }`
+- `also` — side effects: `result.also { log(it) }`
+- Avoid deep nesting of scope functions (max 2 levels)
+
+## Error Handling
+
+- Use `Result<T>` or custom sealed types
+- Use `runCatching {}` for wrapping throwable code
+- Never catch `CancellationException` — always rethrow it
+- Avoid `try-catch` for control flow
+
+```kotlin
+// BAD — using exceptions for control flow
+val user = try { repository.getUser(id) } catch (e: NotFoundException) { null }
+
+// GOOD — nullable return
+val user: User? = repository.findUser(id)
+```

package/.agent/rules/kotlin/hooks.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/build.gradle.kts"
+---
+# Kotlin Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Kotlin-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **ktfmt/ktlint**: Auto-format `.kt` and `.kts` files after edit
+- **detekt**: Run static analysis after editing Kotlin files
+- **./gradlew build**: Verify compilation after changes

package/.agent/rules/kotlin/patterns.md

@@ -0,0 +1,146 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Kotlin and Android/KMP-specific content.
+
+## Dependency Injection
+
+Prefer constructor injection. Use Koin (KMP) or Hilt (Android-only):
+
+```kotlin
+// Koin — declare modules
+val dataModule = module {
+    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
+    factory { GetItemsUseCase(get()) }
+    viewModelOf(::ItemListViewModel)
+}
+
+// Hilt — annotations
+@HiltViewModel
+class ItemListViewModel @Inject constructor(
+    private val getItems: GetItemsUseCase
+) : ViewModel()
+```
+
+## ViewModel Pattern
+
+Single state object, event sink, one-way data flow:
+
+```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)
+        }
+    }
+}
+```
+
+## Repository Pattern
+
+- `suspend` functions return `Result<T>` or custom error type
+- `Flow` for reactive streams
+- Coordinate local + remote data sources
+
+```kotlin
+interface ItemRepository {
+    suspend fun getById(id: String): Result<Item>
+    suspend fun getAll(): Result<List<Item>>
+    fun observeAll(): Flow<List<Item>>
+}
+```
+
+## UseCase Pattern
+
+Single responsibility, `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)
+
+Use for platform-specific implementations:
+
+```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 /* ... */
+}
+```
+
+## Coroutine Patterns
+
+- Use `viewModelScope` in ViewModels, `coroutineScope` for structured child work
+- Use `stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initialValue)` for StateFlow from cold Flows
+- Use `supervisorScope` when child failures should be independent
+
+## Builder Pattern with 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)
+}
+
+// Usage
+val client = httpClient {
+    baseUrl = "https://api.example.com"
+    timeout = 15_000
+    interceptor { AuthInterceptor(tokenProvider) }
+}
+```
+
+## References
+
+See skill: `kotlin-coroutines-flows` for detailed coroutine patterns.
+See skill: `android-clean-architecture` for module and layer patterns.

package/.agent/rules/kotlin/security.md

@@ -0,0 +1,82 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Security
+
+> This file extends [common/security.md](../common/security.md) with Kotlin and Android/KMP-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Use `local.properties` (git-ignored) for local development secrets
+- Use `BuildConfig` fields generated from CI secrets for release builds
+- Use `EncryptedSharedPreferences` (Android) or Keychain (iOS) for runtime secret storage
+
+```kotlin
+// BAD
+val apiKey = "sk-abc123..."
+
+// GOOD — from BuildConfig (generated at build time)
+val apiKey = BuildConfig.API_KEY
+
+// GOOD — from secure storage at runtime
+val token = secureStorage.get("auth_token")
+```
+
+## Network Security
+
+- Use HTTPS exclusively — configure `network_security_config.xml` to block cleartext
+- Pin certificates for sensitive endpoints using OkHttp `CertificatePinner` or Ktor equivalent
+- Set timeouts on all HTTP clients — never leave defaults (which may be infinite)
+- Validate and sanitize all server responses before use
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+</network-security-config>
+```
+
+## Input Validation
+
+- Validate all user input before processing or sending to API
+- Use parameterized queries for Room/SQLDelight — never concatenate user input into SQL
+- Sanitize file paths from user input to prevent path traversal
+
+```kotlin
+// BAD — SQL injection
+@Query("SELECT * FROM items WHERE name = '$input'")
+
+// GOOD — parameterized
+@Query("SELECT * FROM items WHERE name = :input")
+fun findByName(input: String): List<ItemEntity>
+```
+
+## Data Protection
+
+- Use `EncryptedSharedPreferences` for sensitive key-value data on Android
+- Use `@Serializable` with explicit field names — don't leak internal property names
+- Clear sensitive data from memory when no longer needed
+- Use `@Keep` or ProGuard rules for serialized classes to prevent name mangling
+
+## Authentication
+
+- Store tokens in secure storage, not in plain SharedPreferences
+- Implement token refresh with proper 401/403 handling
+- Clear all auth state on logout (tokens, cached user data, cookies)
+- Use biometric authentication (`BiometricPrompt`) for sensitive operations
+
+## ProGuard / R8
+
+- Keep rules for all serialized models (`@Serializable`, Gson, Moshi)
+- Keep rules for reflection-based libraries (Koin, Retrofit)
+- Test release builds — obfuscation can break serialization silently
+
+## WebView Security
+
+- Disable JavaScript unless explicitly needed: `settings.javaScriptEnabled = false`
+- Validate URLs before loading in WebView
+- Never expose `@JavascriptInterface` methods that access sensitive data
+- Use `WebViewClient.shouldOverrideUrlLoading()` to control navigation

package/.agent/rules/kotlin/testing.md

@@ -0,0 +1,128 @@
+---
+paths:
+  - "**/*.kt"
+  - "**/*.kts"
+---
+# Kotlin Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Kotlin and Android/KMP-specific content.
+
+## Test Framework
+
+- **kotlin.test** for multiplatform (KMP) — `@Test`, `assertEquals`, `assertTrue`
+- **JUnit 4/5** for Android-specific tests
+- **Turbine** for testing Flows and StateFlow
+- **kotlinx-coroutines-test** for coroutine testing (`runTest`, `TestDispatcher`)
+
+## ViewModel Testing with Turbine
+
+```kotlin
+@Test
+fun `loading state emitted then data`() = runTest {
+    val repo = FakeItemRepository()
+    repo.addItem(testItem)
+    val viewModel = ItemListViewModel(GetItemsUseCase(repo))
+
+    viewModel.state.test {
+        assertEquals(ItemListState(), awaitItem())     // initial state
+        viewModel.onEvent(ItemListEvent.Load)
+        assertTrue(awaitItem().isLoading)               // loading
+        assertEquals(listOf(testItem), awaitItem().items) // loaded
+    }
+}
+```
+
+## Fakes Over Mocks
+
+Prefer hand-written fakes over mocking frameworks:
+
+```kotlin
+class FakeItemRepository : ItemRepository {
+    private val items = mutableListOf<Item>()
+    var fetchError: Throwable? = null
+
+    override suspend fun getAll(): Result<List<Item>> {
+        fetchError?.let { return Result.failure(it) }
+        return Result.success(items.toList())
+    }
+
+    override fun observeAll(): Flow<List<Item>> = flowOf(items.toList())
+
+    fun addItem(item: Item) { items.add(item) }
+}
+```
+
+## Coroutine Testing
+
+```kotlin
+@Test
+fun `parallel operations complete`() = runTest {
+    val repo = FakeRepository()
+    val result = loadDashboard(repo)
+    advanceUntilIdle()
+    assertNotNull(result.items)
+    assertNotNull(result.stats)
+}
+```
+
+Use `runTest` — it auto-advances virtual time and provides `TestScope`.
+
+## Ktor MockEngine
+
+```kotlin
+val mockEngine = MockEngine { request ->
+    when (request.url.encodedPath) {
+        "/api/items" -> respond(
+            content = Json.encodeToString(testItems),
+            headers = headersOf(HttpHeaders.ContentType, ContentType.Application.Json.toString())
+        )
+        else -> respondError(HttpStatusCode.NotFound)
+    }
+}
+
+val client = HttpClient(mockEngine) {
+    install(ContentNegotiation) { json() }
+}
+```
+
+## Room/SQLDelight Testing
+
+- Room: Use `Room.inMemoryDatabaseBuilder()` for in-memory testing
+- SQLDelight: Use `JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)` for JVM tests
+
+```kotlin
+@Test
+fun `insert and query items`() = runTest {
+    val driver = JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY)
+    Database.Schema.create(driver)
+    val db = Database(driver)
+
+    db.itemQueries.insert("1", "Sample Item", "description")
+    val items = db.itemQueries.getAll().executeAsList()
+    assertEquals(1, items.size)
+}
+```
+
+## Test Naming
+
+Use backtick-quoted descriptive names:
+
+```kotlin
+@Test
+fun `search with empty query returns all items`() = runTest { }
+
+@Test
+fun `delete item emits updated list without deleted item`() = runTest { }
+```
+
+## Test Organization
+
+```
+src/
+├── commonTest/kotlin/     # Shared tests (ViewModel, UseCase, Repository)
+├── androidUnitTest/kotlin/ # Android unit tests (JUnit)
+├── androidInstrumentedTest/kotlin/  # Instrumented tests (Room, UI)
+└── iosTest/kotlin/        # iOS-specific tests
+```
+
+Minimum test coverage: ViewModel + UseCase for every feature.