@c0x12c/ai-toolkit 1.15.0

package/rules/backend-micronaut/KOTLIN.md

@@ -0,0 +1,414 @@
+# Kotlin Rules
+
+> Full guide: use `/kotlin-best-practices` skill
+
+## Null Safety (CRITICAL)
+
+**The force unwrap operator `!!` is FORBIDDEN in this codebase.**
+
+It causes runtime crashes, makes code unpredictable, and goes against Kotlin's null safety. There are no exceptions.
+
+### What to Use Instead
+
+```kotlin
+// Safe call + elvis
+val email = decodedToken.email ?: return AuthError.INVALID_CREDENTIALS.asException().left()
+
+// Null check (enables smart cast)
+if (user == null) {
+    return AuthError.AUTHENTICATION_FAILED.asException().left()
+}
+generateTokensAndResponse(user, provider.value) // user is non-null here
+
+// requireNotNull (only when null = programming error)
+val validUser = requireNotNull(user) { "User must not be null here" }
+```
+
+---
+
+## No Workarounds (CRITICAL)
+
+**NEVER use workarounds. Always fix the root cause. This rule has no exceptions.**
+
+**Forbidden patterns:**
+
+| Pattern | Instead |
+|---------|---------|
+| `@Suppress("UNUSED_PARAMETER")` | Remove the parameter, update call sites |
+| `@Suppress("DEPRECATION")` | Use the non-deprecated replacement |
+| `// TODO: Fix this later` + `!!` | Fix it now with proper null handling |
+| `// HACK:` comments | Fix the root cause using proper layers |
+| Placeholder parameters `reserved: String = ""` | Only include parameters you use |
+
+```kotlin
+// WRONG
+@Suppress("UNUSED_PARAMETER")
+private fun createCommit(employeeId: UUID, authorUsername: String)
+
+// CORRECT — remove unused param, update all call sites
+private fun createCommit(authorUsername: String)
+```
+
+**Always**: understand root cause, fix actual problem, update all related code (call sites, tests, docs).
+
+---
+
+## Error Handling
+
+### Use Either for All Fallible Operations
+
+Return `Either<ClientException, T>` from managers. Never throw exceptions in business logic.
+
+```kotlin
+suspend fun loginUser(email: String): Either<ClientException, User> {
+    val user = userRepository.byEmail(email)
+        ?: return ClientError.USER_NOT_FOUND.asException().left()
+    return user.right()
+}
+```
+
+```kotlin
+// Good - return error type
+fun validateEmail(email: String): Either<ValidationError, String> {
+    return if (email.contains("@")) {
+        email.right()
+    } else {
+        ValidationError.INVALID_EMAIL.left()
+    }
+}
+
+// Bad - throwing exceptions
+fun validateEmail(email: String): String {
+    if (!email.contains("@")) {
+        throw IllegalArgumentException("Invalid email")
+    }
+    return email
+}
+```
+
+### Exhaustive When Expressions
+
+Use exhaustive `when` on enums (no `else` needed if all cases covered):
+```kotlin
+when (provider) {
+    OAuthProvider.GOOGLE -> handleGoogle()
+    OAuthProvider.GITHUB -> handleGithub()
+    OAuthProvider.TWITTER -> handleTwitter()
+}
+```
+
+### Transaction Safety
+
+Always return from transaction blocks and handle nullable results:
+```kotlin
+transaction(db.primary) {
+    val user = userRepository.byId(userId)
+    if (user == null) {
+        return@transaction AuthError.USER_NOT_FOUND.asException().left()
+    }
+    return@transaction Success(user).right()
+}
+```
+
+---
+
+## Enum Usage
+
+**NEVER hardcode strings when an enum exists.** Use `EnumName.VALUE.value` everywhere: return values, fallback values, comparisons, default values.
+
+```kotlin
+// WRONG - hardcoded string
+ifLeft = { "critical" }
+val status = "healthy"
+if (value == "at_risk") { ... }
+
+// CORRECT - use the enum
+ifLeft = { HealthStatus.CRITICAL.value }
+val status = HealthStatus.HEALTHY.value
+if (value == HealthStatus.AT_RISK.value) { ... }
+```
+
+**Why**: Hardcoded strings break silently when enum values change. The compiler can't catch typos in strings.
+
+**Known enums**: `HealthStatus`, `ReportType`, `EvaluationMode`, `ProjectRole`, `ProjectStatus`.
+
+Convert String -> enum at boundaries (controllers). Use enum references everywhere else.
+
+---
+
+## Conversions
+
+Put `companion object { fun from(entity) }` inside Response DTOs. **Never** create separate mapper files or private extension functions.
+
+```kotlin
+data class UserResponse(val id: UUID, val email: String, val displayName: String) {
+  companion object {
+    fun from(entity: UserEntity) = UserResponse(
+      id = entity.id,
+      email = entity.email,
+      displayName = entity.displayName ?: entity.email
+    )
+  }
+}
+```
+
+When extra data needed, pass as additional params: `fun from(entity, extraData, count)`.
+When extra data needs fetching, use a private manager helper that calls `Response.from()`.
+
+**Never do:** separate mapper files, private extension functions in managers, scattered inline mapping.
+
+**Location:** Response DTOs go in `module-client/response/`. `module-client` depends on `module-repository`.
+
+---
+
+## Style
+
+### No Magic Numbers
+
+Never hardcode durations, timeouts, limits. Put them in `application.yml` and inject via config class.
+
+```kotlin
+// WRONG
+val expiresAt = Instant.now().plus(7, ChronoUnit.DAYS)
+val maxRetries = 3
+
+// CORRECT
+val expiresAt = Instant.now().plusSeconds(tokenConfig.refreshTokenExpirationSeconds)
+val maxRetries = appConfig.maxRetries
+```
+
+### No Inline Fully-Qualified Imports
+
+Always use `import` at the top. Never write fully-qualified class names inline.
+
+```kotlin
+// WRONG
+val token = java.util.UUID.randomUUID().toString()
+
+// CORRECT
+import java.util.UUID
+val token = UUID.randomUUID().toString()
+```
+
+### Config Objects Over Individual Fields
+
+Inject the config object. Don't unpack fields into separate constructor params.
+
+```kotlin
+// WRONG — too many params, fragile
+class AuthManager(
+  private val refreshTokenExpirationSeconds: Long,
+  private val passwordResetExpirationSeconds: Long,
+  private val emailVerificationExpirationSeconds: Long
+)
+
+// CORRECT — one config object
+class AuthManager(
+  private val tokenExpirationConfig: TokenExpirationConfig
+)
+```
+
+### JSON Naming
+
+Backend uses `snake_case` for all JSON. Jackson does this automatically.
+Kotlin code stays `camelCase` — Jackson converts at serialization time.
+
+### Named Arguments
+Use named arguments for 2+ parameters:
+```kotlin
+fn(a = x, b = y)
+```
+
+### Comments
+Comments explain **WHY**, not **WHAT**. No KDoc that restates the function name.
+
+```kotlin
+// WRONG - useless comments
+/**
+ * Default implementation of [UserManager].
+ * Provides CRUD operations for users with validation.
+ */
+class DefaultUserManager(...) : UserManager
+
+/**
+ * Validates a configuration value.
+ * @param configKey The configuration key
+ * @param value The value to validate
+ * @return ValidationResult
+ */
+fun validate(configKey: String, value: JsonNode): ValidationResult
+```
+
+```kotlin
+// CORRECT - no comments needed, code is self-explanatory
+class DefaultUserManager(...) : UserManager
+
+fun validate(configKey: String, value: JsonNode): ValidationResult
+```
+
+```kotlin
+// CORRECT - comments that explain WHY
+// Twilio requires E.164 format, strip any formatting
+val normalized = phoneNumber.replace(Regex("[^+\\d]"), "")
+
+// Cache for 5 minutes to reduce DB load during peak hours
+val CACHE_TTL = 5.minutes
+```
+
+### Configuration URLs
+Wrap default URL values in backticks in YAML:
+```yaml
+# Good
+base-url: ${VENDOR_BASE_URL:`https://api.example.com`}
+
+# Bad - may cause build errors
+base-url: ${VENDOR_BASE_URL:https://api.example.com}
+```
+
+### Formatting
+- **2-space indentation**, no tabs
+- **LF line endings** (Unix style)
+- **120 char** line length guide, 1000 hard limit
+- UTF-8 encoding, final newline always
+- No star imports (wildcard imports disabled)
+- Import order: `*,java.*,javax.*,kotlin.*`
+
+```kotlin
+// Braces on same line
+class MyClass {
+  fun myFunction() {
+    // code
+  }
+}
+
+// Multiline parameters - aligned
+fun longFunctionName(
+  firstParameter: String,
+  secondParameter: Int,
+  thirdParameter: Boolean
+) {
+  // body
+}
+```
+
+### Enforcement
+```bash
+./gradlew ktlintCheck     # Check style
+./gradlew ktlintFormat    # Auto-fix style
+```
+
+---
+
+## Constants Registry
+
+Use the right pattern for the right kind of constant:
+
+| Use Case | Pattern |
+|----------|---------|
+| Finite, known values (status, role) | `enum class` |
+| Open-ended, growing list (event names, metrics) | `object` with `const val` |
+| Structured paths (S3 keys, URLs) | Type-safe builder class |
+
+```kotlin
+// Enums for BOUNDED sets
+enum class ProjectStatus(val value: String) {
+  ACTIVE("active"), ARCHIVED("archived")
+}
+
+// Object registries for OPEN-ENDED sets
+object ActivityNames {
+  const val AGENT_CONVERSATION = "AgentConversation"
+  const val PROCESS_DOCUMENT = "ProcessDocument"
+  const val SYNC_USER_PROFILE = "SyncUserProfile"
+}
+
+// Type-safe builders for STRUCTURED paths
+object StorageKey {
+  fun user(userId: UUID) = UserStorageKey(userId)
+
+  class UserStorageKey(private val userId: UUID) {
+    fun avatar() = "user/$userId/avatar"
+    fun document(docId: UUID) = "user/$userId/documents/$docId"
+  }
+}
+```
+
+Once a registry passes ~50 constants, split by domain with nested objects:
+```kotlin
+object ActivityNames {
+  object Agent {
+    const val CONVERSATION = "AgentConversation"
+  }
+  object Document {
+    const val PROCESS = "ProcessDocument"
+  }
+}
+// Usage: ActivityNames.Agent.CONVERSATION
+```
+
+---
+
+## Nested Input/Output Data Classes
+
+For internal service contracts, nest `Input`/`Output` inside the class that uses them:
+
+```kotlin
+class ProcessDocumentService {
+  data class Input(
+    val documentId: UUID,
+    val userId: UUID,
+    val options: ProcessOptions = ProcessOptions()
+  )
+  data class Output(
+    val resultId: UUID,
+    val pageCount: Int
+  )
+
+  suspend fun run(input: Input): Either<ClientException, Output> { ... }
+}
+
+// Usage is self-documenting:
+val result = service.run(ProcessDocumentService.Input(documentId = id, userId = userId))
+```
+
+**When to use:** Internal service-to-service contracts, background jobs, batch operations.
+**When NOT to use:** API request/response models — those go in `module-client`.
+
+---
+
+## No Silent Try-Catch
+
+Never catch and swallow exceptions. If you need a fallback, log the failure first.
+
+```kotlin
+// WRONG — silent swallow, hides bugs
+val result = try {
+  expensiveOperation()
+} catch (e: Exception) {
+  fallbackValue  // No logging — bug disappears silently
+}
+
+// CORRECT for non-suspend — log then fallback
+val result = runCatching { blockingOperation() }
+  .onFailure { logger.warn("Operation failed, using fallback", it) }
+  .getOrDefault(fallbackValue)
+
+// CAREFUL — runCatching catches ALL Throwables including CancellationException.
+// In suspend code, this breaks cancellation silently:
+val result = runCatching { suspendFunction() }  // WRONG — swallows CancellationException
+  .getOrDefault(fallback)
+
+// CORRECT for suspend — rethrow CancellationException
+val result = runCatching { suspendFunction() }
+  .onFailure { if (it is CancellationException) throw it }
+  .onFailure { logger.warn("Operation failed", it) }
+  .getOrDefault(fallback)
+
+// BEST — use Either, no exceptions at all
+suspend fun doWork(): Either<ClientException, Result> { ... }
+```
+
+**Rules:**
+- Never catch-and-swallow. Log the failure if you need a fallback.
+- `runCatching` is fine for non-suspend code. For suspend functions, always rethrow `CancellationException` or use Either.
+- If you don't need a fallback, use Either and let the caller decide.

package/rules/backend-micronaut/RETROFIT_PLACEMENT.md

@@ -0,0 +1,290 @@
+# Retrofit Client Placement Rules
+
+> Full guide: use `/kotlin-best-practices` skill
+
+---
+
+## Core Rule
+
+**NEVER place Retrofit client interfaces in modules that have kapt enabled for Micronaut.**
+
+### Correct Pattern
+
+```
+module-client/                    # NO kapt
+├── src/main/kotlin/
+│   └── com/yourcompany/client/
+│       ├── TemplateServiceClient.kt    ✅ Retrofit @GET/@POST
+│       ├── TerraformServiceClient.kt   ✅ Retrofit interfaces
+│       └── dto/
+│           ├── template/
+│           │   └── TemplateDtos.kt     ✅ Plain data classes
+│           └── terraform/
+│               └── TerraformDtos.kt    ✅ No Micronaut annotations
+└── build.gradle
+    # NO kotlin-kapt plugin ✅
+    dependencies {
+      implementation(libs.networking.retrofit)
+      implementation(libs.networking.okhttp)
+      implementation(libs.arrow.core)
+      implementation(libs.jackson.*)
+    }
+```
+
+### Incorrect Pattern
+
+```
+module-auth/                      # HAS kapt enabled
+├── src/main/kotlin/
+│   └── com/yourcompany/auth/
+│       ├── client/
+│       │   ├── TemplateServiceClient.kt    ❌ WILL FAIL
+│       │   └── TerraformServiceClient.kt   ❌ kapt can't process
+│       └── dto/
+│           └── TemplateDtos.kt             ❌ @Serdeable conflicts
+└── build.gradle
+    plugins {
+      id("kotlin-kapt")  ❌ PROBLEM
+    }
+```
+
+---
+
+## Why This Fails
+
+### Kapt Limitations
+
+1. **Type Alias Issues**
+   ```kotlin
+   // Kapt can't handle this in stub generation:
+   typealias EitherCall<R> = Call<Either<ErrorResponse, R>>
+   ```
+
+2. **Complex Generic Types**
+   ```kotlin
+   // Kapt fails to resolve nested generics:
+   fun getStatus(): Call<Either<ErrorResponse, TerraformStatusDto>>
+   ```
+
+3. **Annotation Processor Conflicts**
+   - Micronaut processors try to process Retrofit interfaces
+   - Results in `@error.NonExistentClass()` in generated stubs
+   - Build fails with "incompatible types" errors
+
+---
+
+## Implementation Checklist
+
+When adding new external service clients:
+
+### 1. Create Client Interface in module-client
+
+```kotlin
+package com.yourcompany.client
+
+import arrow.core.Either
+import com.yourcompany.retrofit.ErrorResponse
+import retrofit2.Call
+import retrofit2.http.*
+
+interface MyServiceClient {
+  @GET("/api/resource")
+  fun getResource(): Call<Either<ErrorResponse, ResourceDto>>
+
+  @POST("/api/resource")
+  fun createResource(@Body request: CreateRequestDto): Call<Either<ErrorResponse, ResourceDto>>
+}
+```
+
+**Key Points:**
+- ✅ Package: `com.yourcompany.client` (NOT `com.yourcompany.auth.client`)
+- ✅ Use full type: `Call<Either<ErrorResponse, T>>` (NOT `EitherCall<T>`)
+- ✅ Explicit imports (NOT wildcard `import com.yourcompany.client.dto.*`)
+
+### 2. Create DTOs in module-client
+
+```kotlin
+package com.yourcompany.client.dto.myservice
+
+// NO Micronaut annotations! ❌ @Serdeable
+data class ResourceDto(
+  val id: String,
+  val name: String,
+  val createdAt: Instant
+)
+
+data class CreateRequestDto(
+  val name: String,
+  val options: Map<String, Any>
+)
+```
+
+**Key Points:**
+- ✅ Plain Kotlin data classes
+- ✅ NO `@Serdeable` annotation
+- ✅ Jackson handles serialization automatically
+- ✅ Package: `com.yourcompany.client.dto.*`
+
+### 3. Create Client Factory in module-auth
+
+```kotlin
+package com.yourcompany.auth.config
+
+import com.yourcompany.client.MyServiceClient
+import io.micronaut.context.annotation.Factory
+import jakarta.inject.Singleton
+
+@Factory
+class MyServiceConfig(
+  @Value("\${app.myservice.url}")
+  private val serviceUrl: String,
+  private val objectMapper: ObjectMapper
+) {
+
+  @Singleton
+  fun myServiceClient(): MyServiceClient {
+    val retrofit = Retrofits.createRetrofit(
+      baseUrl = serviceUrl.toHttpUrl(),
+      mapper = objectMapper
+    )
+    return retrofit.create(MyServiceClient::class.java)
+  }
+}
+```
+
+**Key Points:**
+- ✅ Factory is in module-auth (has kapt for `@Factory`)
+- ✅ Client interface is in module-client (no kapt)
+- ✅ Clean separation of concerns
+
+### 4. Update module-auth Dependencies
+
+```groovy
+// module-auth/build.gradle
+
+dependencies {
+  // Client module (contains Retrofit interfaces)
+  implementation(project(":module-client"))
+
+  // Retrofit runtime (needed for creating clients in factories)
+  implementation(libs.networking.retrofit)
+  implementation(libs.networking.retrofit.jackson)
+  implementation(libs.networking.okhttp)
+  implementation(libs.networking.okhttp.logging)
+
+  // Arrow (for Either type)
+  implementation(libs.arrow.core)
+}
+```
+
+---
+
+## Troubleshooting
+
+### Error: `@error.NonExistentClass()`
+
+**Cause:** Retrofit client interface in a module with kapt enabled
+
+**Solution:** Move client to `module-client`
+
+### Error: `Unresolved reference 'Serdeable'`
+
+**Cause:** DTOs use Micronaut annotation but module lacks dependency
+
+**Solution:** Remove `@Serdeable` - Jackson handles it automatically
+
+### Error: `when expression must be exhaustive`
+
+**Cause:** Nullable enum in when expression
+
+**Solution:**
+```kotlin
+// ❌ Before:
+when (task.automationType) { ... }
+
+// ✅ After:
+val type = task.automationType ?: return ...
+when (type) { ... }
+```
+
+---
+
+## Module Architecture
+
+```
+backend/
+├── app/
+│   ├── module-auth/              # Micronaut controllers/services
+│   │   ├── build.gradle          # HAS kapt
+│   │   ├── controller/           # @Controller, @Get, @Post
+│   │   ├── service/              # @Singleton services
+│   │   └── config/               # @Factory for clients
+│   │
+│   └── module-client/            # Retrofit clients ONLY
+│       ├── build.gradle          # NO kapt ✅
+│       └── src/.../client/       # Retrofit interfaces
+│
+└── core/
+    └── module-retrofit/          # Shared Retrofit utilities
+        └── EitherCall.kt         # Type aliases, adapters
+```
+
+---
+
+## Benefits
+
+1. **Clean Compilation**
+   - Kapt only processes Micronaut beans
+   - Retrofit clients compile with standard Kotlin compiler
+
+2. **Clear Separation**
+   - Micronaut infrastructure ↔ External API clients
+   - Easy to test and mock
+
+3. **Reusability**
+   - Clients can be used in other modules
+   - No Micronaut dependency pollution
+
+---
+
+## Related Rules
+
+- `KOTLIN.md` — Null safety, no force unwraps
+- `NAMING_CONVENTIONS.md` — Package naming
+- `SCHEMA.md` — Repository patterns
+
+---
+
+---
+
+## Always Retrofit Over Raw OkHttp
+
+Always prefer Retrofit interfaces over raw OkHttp for HTTP clients. ~80% less boilerplate.
+
+```kotlin
+// WRONG — 198 lines of OkHttp boilerplate per client
+class DefaultSearchClient(private val okHttpClient: OkHttpClient) {
+  fun search(query: String): SearchResult {
+    val request = Request.Builder()
+      .url("$baseUrl/search")
+      .post(objectMapper.writeValueAsString(body).toRequestBody())
+      .addHeader("Authorization", "Bearer $apiKey")
+      .build()
+    val response = okHttpClient.newCall(request).execute()
+    // 40+ lines of response parsing, error handling...
+  }
+}
+
+// CORRECT — 25 lines, Retrofit handles the plumbing
+interface SearchClient {
+  @POST("/search")
+  suspend fun search(
+    @Header("Authorization") auth: String,
+    @Body request: SearchRequest
+  ): Response<SearchResult>
+}
+```
+
+---
+
+**TL;DR:** Retrofit clients → `module-client` (no kapt). Micronaut beans → `module-auth` (has kapt). Never mix. Always Retrofit, never raw OkHttp.