aigroup-workflow 2.1.2 → 2.2.1

package/skills/java/kotlin-specialist/references/multiplatform-kmp.md

@@ -0,0 +1,380 @@
+# Kotlin Multiplatform (KMP)
+
+## Project Structure
+
+```
+project/
+├── commonMain/
+│   ├── kotlin/
+│   │   ├── data/
+│   │   │   └── User.kt
+│   │   ├── repository/
+│   │   │   └── UserRepository.kt
+│   │   └── Platform.kt (expect)
+│   └── resources/
+├── androidMain/
+│   └── kotlin/
+│       └── Platform.android.kt (actual)
+├── iosMain/
+│   └── kotlin/
+│       └── Platform.ios.kt (actual)
+└── jvmMain/
+    └── kotlin/
+        └── Platform.jvm.kt (actual)
+```
+
+## Gradle Configuration
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("multiplatform") version "1.9.22"
+    kotlin("plugin.serialization") version "1.9.22"
+}
+
+kotlin {
+    // JVM target
+    jvm {
+        compilations.all {
+            kotlinOptions.jvmTarget = "17"
+        }
+    }
+
+    // Android target
+    androidTarget {
+        compilations.all {
+            kotlinOptions.jvmTarget = "17"
+        }
+    }
+
+    // iOS targets
+    listOf(
+        iosX64(),
+        iosArm64(),
+        iosSimulatorArm64()
+    ).forEach { iosTarget ->
+        iosTarget.binaries.framework {
+            baseName = "shared"
+            isStatic = true
+        }
+    }
+
+    // JS target
+    js(IR) {
+        browser()
+        nodejs()
+    }
+
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
+                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
+                implementation("io.ktor:ktor-client-core:2.3.7")
+            }
+        }
+
+        val commonTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3")
+            }
+        }
+
+        val androidMain by getting {
+            dependencies {
+                implementation("io.ktor:ktor-client-okhttp:2.3.7")
+            }
+        }
+
+        val iosMain by getting {
+            dependencies {
+                implementation("io.ktor:ktor-client-darwin:2.3.7")
+            }
+        }
+
+        val jvmMain by getting {
+            dependencies {
+                implementation("io.ktor:ktor-client-cio:2.3.7")
+            }
+        }
+    }
+}
+```
+
+## Expect/Actual Pattern
+
+```kotlin
+// commonMain/kotlin/Platform.kt
+expect class Platform() {
+    val name: String
+    fun currentTimeMillis(): Long
+}
+
+expect fun getPlatform(): Platform
+
+// androidMain/kotlin/Platform.android.kt
+import android.os.Build
+
+actual class Platform {
+    actual val name: String = "Android ${Build.VERSION.SDK_INT}"
+
+    actual fun currentTimeMillis(): Long =
+        System.currentTimeMillis()
+}
+
+actual fun getPlatform(): Platform = Platform()
+
+// iosMain/kotlin/Platform.ios.kt
+import platform.UIKit.UIDevice
+import platform.Foundation.NSDate
+
+actual class Platform {
+    actual val name: String =
+        UIDevice.currentDevice.systemName() + " " + UIDevice.currentDevice.systemVersion
+
+    actual fun currentTimeMillis(): Long =
+        (NSDate().timeIntervalSince1970 * 1000).toLong()
+}
+
+actual fun getPlatform(): Platform = Platform()
+```
+
+## Common Code Patterns
+
+```kotlin
+// commonMain - Shared business logic
+class UserRepository(private val api: ApiService) {
+    private val _users = MutableStateFlow<List<User>>(emptyList())
+    val users: StateFlow<List<User>> = _users.asStateFlow()
+
+    suspend fun loadUsers() {
+        try {
+            val result = api.getUsers()
+            _users.value = result
+        } catch (e: Exception) {
+            // Handle error
+        }
+    }
+}
+
+// Shared models
+@Serializable
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val createdAt: Long
+)
+
+// Sealed class for platform-agnostic results
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Error(val exception: Exception) : Result<Nothing>()
+    object Loading : Result<Nothing>()
+}
+```
+
+## Platform-Specific Implementations
+
+```kotlin
+// commonMain
+expect class DatabaseDriver()
+
+expect suspend fun DatabaseDriver.query(sql: String): List<Map<String, Any>>
+
+// androidMain
+import android.content.Context
+import androidx.sqlite.db.SupportSQLiteDatabase
+
+actual class DatabaseDriver(private val context: Context) {
+    private val db: SupportSQLiteDatabase = // Initialize Android SQLite
+}
+
+actual suspend fun DatabaseDriver.query(sql: String): List<Map<String, Any>> =
+    withContext(Dispatchers.IO) {
+        // Android-specific query execution
+    }
+
+// iosMain
+import platform.Foundation.NSFileManager
+
+actual class DatabaseDriver() {
+    private val db = // Initialize iOS SQLite
+}
+
+actual suspend fun DatabaseDriver.query(sql: String): List<Map<String, Any>> =
+    withContext(Dispatchers.Default) {
+        // iOS-specific query execution
+    }
+```
+
+## Ktor Client Multiplatform
+
+```kotlin
+// commonMain
+class ApiClient {
+    private val client = HttpClient {
+        install(ContentNegotiation) {
+            json(Json {
+                prettyPrint = true
+                isLenient = true
+                ignoreUnknownKeys = true
+            })
+        }
+        install(Logging) {
+            level = LogLevel.INFO
+        }
+    }
+
+    suspend fun getUsers(): List<User> =
+        client.get("https://api.example.com/users").body()
+
+    suspend fun createUser(user: User): User =
+        client.post("https://api.example.com/users") {
+            contentType(ContentType.Application.Json)
+            setBody(user)
+        }.body()
+}
+```
+
+## Source Set Hierarchy
+
+```kotlin
+// Intermediate source sets for iOS
+kotlin {
+    sourceSets {
+        val commonMain by getting
+        val commonTest by getting
+
+        val iosMain by creating {
+            dependsOn(commonMain)
+        }
+
+        val iosX64Main by getting {
+            dependsOn(iosMain)
+        }
+
+        val iosArm64Main by getting {
+            dependsOn(iosMain)
+        }
+
+        val iosSimulatorArm64Main by getting {
+            dependsOn(iosMain)
+        }
+    }
+}
+```
+
+## Native Interop (iOS)
+
+```kotlin
+// iosMain - Calling Objective-C/Swift
+import platform.Foundation.NSBundle
+import platform.UIKit.UIApplication
+
+fun getAppVersion(): String =
+    NSBundle.mainBundle.objectForInfoDictionaryKey("CFBundleShortVersionString") as? String
+        ?: "Unknown"
+
+fun openURL(url: String) {
+    val nsUrl = NSURL.URLWithString(url)
+    UIApplication.sharedApplication.openURL(nsUrl ?: return)
+}
+
+// Freezing for thread safety (Kotlin/Native memory model)
+class IosViewModel {
+    private val scope = MainScope()
+
+    fun loadData() {
+        scope.launch {
+            val data = api.getData().freeze() // Freeze for iOS
+            updateUI(data)
+        }
+    }
+}
+```
+
+## Testing Multiplatform Code
+
+```kotlin
+// commonTest
+class UserRepositoryTest {
+    private lateinit var repository: UserRepository
+
+    @BeforeTest
+    fun setup() {
+        repository = UserRepository(FakeApiService())
+    }
+
+    @Test
+    fun testLoadUsers() = runTest {
+        repository.loadUsers()
+
+        val users = repository.users.value
+        assertEquals(2, users.size)
+    }
+}
+
+// Platform-specific tests
+// androidTest
+class AndroidUserRepositoryTest {
+    @Test
+    fun testAndroidSpecific() {
+        // Android-only test
+    }
+}
+
+// iosTest
+class IosUserRepositoryTest {
+    @Test
+    fun testIosSpecific() {
+        // iOS-only test
+    }
+}
+```
+
+## Publishing KMP Library
+
+```kotlin
+// build.gradle.kts
+plugins {
+    `maven-publish`
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("kotlinMultiplatform") {
+            groupId = "com.example"
+            artifactId = "shared"
+            version = "1.0.0"
+        }
+    }
+
+    repositories {
+        maven {
+            url = uri("https://maven.pkg.github.com/user/repo")
+            credentials {
+                username = System.getenv("GITHUB_ACTOR")
+                password = System.getenv("GITHUB_TOKEN")
+            }
+        }
+    }
+}
+```
+
+## Quick Reference
+
+| Pattern | Purpose |
+|---------|---------|
+| `expect class` | Declare platform-specific type in common |
+| `actual class` | Implement platform-specific type |
+| `commonMain` | Shared code across all platforms |
+| `androidMain` | Android-specific implementations |
+| `iosMain` | iOS-specific implementations (all targets) |
+| `jvmMain` | JVM/Desktop-specific code |
+| `jsMain` | JavaScript-specific code |
+| `*Test` | Platform-specific tests |
+| `dependsOn` | Source set hierarchy |
+| `.freeze()` | iOS memory model (legacy) |
+| `kotlin("multiplatform")` | KMP Gradle plugin |

package/skills/java/spring-boot-engineer/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: spring-boot-engineer
+description: Generates Spring Boot 3.x configurations, creates REST controllers, implements Spring Security 6 authentication flows, sets up Spring Data JPA repositories, and configures reactive WebFlux endpoints. Use when building Spring Boot 3.x applications, microservices, or reactive Java applications; invoke for Spring Data JPA, Spring Security 6, WebFlux, Spring Cloud integration, Java REST API design, or Microservices Java architecture.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: backend
+  triggers: Spring Boot, Spring Framework, Spring Cloud, Spring Security, Spring Data JPA, Spring WebFlux, Microservices Java, Java REST API, Reactive Java
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: java-architect, database-optimizer, microservices-architect, devops-engineer
+---
+
+# Spring Boot Engineer
+
+## Core Workflow
+
+1. **Analyze requirements** — Identify service boundaries, APIs, data models, security needs
+2. **Design architecture** — Plan microservices, data access, cloud integration, security; confirm design before coding
+3. **Implement** — Create services with constructor injection and layered architecture (see Quick Start below)
+4. **Secure** — Add Spring Security, OAuth2, method security, CORS configuration; verify security rules compile and pass tests. If compilation or tests fail: review error output, fix the failing rule or configuration, and re-run before proceeding
+5. **Test** — Write unit, integration, and slice tests; run `./mvnw test` (or `./gradlew test`) and confirm all pass before proceeding. If tests fail: review the stack trace, isolate the failing assertion or component, fix the issue, and re-run the full suite
+6. **Deploy** — Configure health checks and observability via Actuator; validate `/actuator/health` returns `UP`. If health is `DOWN`: check the `components` detail in the response, resolve the failing component (e.g., datasource, broker), and re-validate
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Web Layer | `references/web.md` | Controllers, REST APIs, validation, exception handling |
+| Data Access | `references/data.md` | Spring Data JPA, repositories, transactions, projections |
+| Security | `references/security.md` | Spring Security 6, OAuth2, JWT, method security |
+| Cloud Native | `references/cloud.md` | Spring Cloud, Config, Discovery, Gateway, resilience |
+| Testing | `references/testing.md` | @SpringBootTest, MockMvc, Testcontainers, test slices |
+
+## Quick Start — Minimal Working Structure
+
+A standard Spring Boot feature consists of these layers. Use these as copy-paste starting points.
+
+### Entity
+
+```java
+@Entity
+@Table(name = "products")
+public class Product {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @NotBlank
+    private String name;
+
+    @DecimalMin("0.0")
+    private BigDecimal price;
+
+    // getters / setters or use @Data (Lombok)
+}
+```
+
+### Repository
+
+```java
+public interface ProductRepository extends JpaRepository<Product, Long> {
+    List<Product> findByNameContainingIgnoreCase(String name);
+}
+```
+
+### Service (constructor injection)
+
+```java
+@Service
+public class ProductService {
+    private final ProductRepository repo;
+
+    public ProductService(ProductRepository repo) { // constructor injection — no @Autowired
+        this.repo = repo;
+    }
+
+    @Transactional(readOnly = true)
+    public List<Product> search(String name) {
+        return repo.findByNameContainingIgnoreCase(name);
+    }
+
+    @Transactional
+    public Product create(ProductRequest request) {
+        var product = new Product();
+        product.setName(request.name());
+        product.setPrice(request.price());
+        return repo.save(product);
+    }
+}
+```
+
+### REST Controller
+
+```java
+@RestController
+@RequestMapping("/api/v1/products")
+@Validated
+public class ProductController {
+    private final ProductService service;
+
+    public ProductController(ProductService service) {
+        this.service = service;
+    }
+
+    @GetMapping
+    public List<Product> search(@RequestParam(defaultValue = "") String name) {
+        return service.search(name);
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public Product create(@Valid @RequestBody ProductRequest request) {
+        return service.create(request);
+    }
+}
+```
+
+### DTO (record)
+
+```java
+public record ProductRequest(
+    @NotBlank String name,
+    @DecimalMin("0.0") BigDecimal price
+) {}
+```
+
+### Global Exception Handler
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    @ResponseStatus(HttpStatus.BAD_REQUEST)
+    public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
+        return ex.getBindingResult().getFieldErrors().stream()
+            .collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage));
+    }
+
+    @ExceptionHandler(EntityNotFoundException.class)
+    @ResponseStatus(HttpStatus.NOT_FOUND)
+    public Map<String, String> handleNotFound(EntityNotFoundException ex) {
+        return Map.of("error", ex.getMessage());
+    }
+}
+```
+
+### Test Slice
+
+```java
+@WebMvcTest(ProductController.class)
+class ProductControllerTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean ProductService service;
+
+    @Test
+    void createProduct_validRequest_returns201() throws Exception {
+        var product = new Product(); product.setName("Widget"); product.setPrice(BigDecimal.TEN);
+        when(service.create(any())).thenReturn(product);
+
+        mockMvc.perform(post("/api/v1/products")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""{"name":"Widget","price":10.0}"""))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.name").value("Widget"));
+    }
+}
+```
+
+## Constraints
+
+### MUST DO
+
+| Rule | Correct Pattern |
+|------|----------------|
+| Constructor injection | `public MyService(Dep dep) { this.dep = dep; }` |
+| Validate API input | `@Valid @RequestBody MyRequest req` on every mutating endpoint |
+| Type-safe config | `@ConfigurationProperties(prefix = "app")` bound to a record/class |
+| Appropriate stereotype | `@Service` for business logic, `@Repository` for data, `@RestController` for HTTP |
+| Transaction scope | `@Transactional` on multi-step writes; `@Transactional(readOnly = true)` on reads |
+| Hide internals | Catch domain exceptions in `@RestControllerAdvice`; return problem details, not stack traces |
+| Externalize secrets | Use environment variables or Spring Cloud Config — never `application.properties` |
+
+### MUST NOT DO
+- Use field injection (`@Autowired` on fields)
+- Skip input validation on API endpoints
+- Use `@Component` when `@Service`/`@Repository`/`@Controller` applies
+- Mix blocking and reactive code (e.g., calling `.block()` inside a WebFlux chain)
+- Store secrets or credentials in `application.properties`/`application.yml`
+- Hardcode URLs, credentials, or environment-specific values
+- Use deprecated Spring Boot 2.x patterns (e.g., `WebSecurityConfigurerAdapter`)