@softspark/ai-toolkit 1.0.0

package/app/skills/kotlin-patterns/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: kotlin-patterns
+description: "Loaded when user asks about Kotlin development patterns"
+effort: medium
+user-invocable: false
+---
+
+# Kotlin Patterns Skill
+
+## Project Structure
+
+### Gradle KTS Multi-Module Layout
+```
+project-root/
+├── build.gradle.kts
+├── settings.gradle.kts
+├── gradle/libs.versions.toml
+├── app/
+│   ├── build.gradle.kts
+│   └── src/{main,test}/kotlin/com/example/app/
+├── domain/
+│   └── src/main/kotlin/com/example/domain/
+│       ├── model/
+│       ├── repository/
+│       └── usecase/
+└── infrastructure/
+    └── src/main/kotlin/com/example/infra/
+```
+
+### settings.gradle.kts
+```kotlin
+rootProject.name = "my-project"
+dependencyResolutionManagement {
+    versionCatalogs { create("libs") { from(files("gradle/libs.versions.toml")) } }
+}
+include(":app", ":domain", ":infrastructure")
+```
+
+### Module build.gradle.kts
+```kotlin
+plugins {
+    alias(libs.plugins.kotlin.jvm)
+    alias(libs.plugins.kotlin.serialization)
+}
+dependencies {
+    implementation(project(":domain"))
+    implementation(libs.kotlinx.coroutines.core)
+    testImplementation(libs.bundles.testing)
+}
+kotlin { jvmToolchain(21) }
+```
+
+---
+
+## Idioms / Code Style
+
+### Data Classes + Value Classes
+```kotlin
+data class User(
+    val id: UserId,
+    val name: String,
+    val email: String,
+    val role: Role = Role.USER,
+) {
+    init {
+        require(name.isNotBlank()) { "Name must not be blank" }
+        require(email.contains("@")) { "Invalid email format" }
+    }
+}
+
+@JvmInline
+value class UserId(val value: String)  // Zero-overhead type-safe ID
+enum class Role { ADMIN, USER, GUEST }
+```
+
+### Sealed Interfaces for Domain Modeling
+```kotlin
+sealed interface PaymentResult {
+    data class Success(val transactionId: String, val amount: Money) : PaymentResult
+    data class Declined(val reason: String) : PaymentResult
+    data class Error(val exception: Throwable) : PaymentResult
+}
+
+// Exhaustive when -- compiler enforces all branches
+fun handlePayment(result: PaymentResult): String = when (result) {
+    is PaymentResult.Success -> "Paid: ${result.amount}"
+    is PaymentResult.Declined -> "Declined: ${result.reason}"
+    is PaymentResult.Error -> "Error: ${result.exception.message}"
+}
+```
+
+### Extension Functions
+```kotlin
+fun String.toSlug(): String =
+    lowercase().replace(Regex("[^a-z0-9\\s-]"), "").replace(Regex("\\s+"), "-").trim('-')
+
+// Scoped extensions -- visible only inside containing class
+class OrderService {
+    private fun Order.totalWithTax(): Money = total * (1 + taxRate)
+}
+```
+
+### Null Safety
+```kotlin
+fun getDisplayName(user: User?): String =
+    user?.name?.takeIf { it.isNotBlank() } ?: "Anonymous"
+
+fun processEmail(email: String?) { email?.let { sendWelcomeEmail(it) } }
+
+fun loadConfig(path: String?): Config {
+    val resolved = requireNotNull(path) { "Config path must not be null" }
+    return parseConfig(resolved)
+}
+```
+
+### Scope Functions
+
+| Function | Ref | Returns | Use case |
+|----------|-----|---------|----------|
+| `let` | `it` | Lambda result | Null check + transform |
+| `run` | `this` | Lambda result | Config + compute |
+| `apply` | `this` | Object itself | Object initialization |
+| `also` | `it` | Object itself | Side effects |
+
+```kotlin
+val conn = Connection().apply { host = "localhost"; port = 5432 }
+fun createUser(req: CreateUserRequest): User =
+    userRepository.save(req.toUser()).also { logger.info("Created: ${it.id}") }
+```
+
+### Type-Safe Builders (DSL)
+```kotlin
+fun html(block: HtmlBuilder.() -> Unit): String = HtmlBuilder().apply(block).build()
+
+val page = html {
+    head { title("My Page") }
+    body { p("Hello, world!") }
+}
+```
+
+---
+
+## Error Handling
+
+### Result<T> and runCatching
+```kotlin
+fun findUser(id: UserId): Result<User> = runCatching {
+    userRepository.findById(id) ?: throw UserNotFoundException(id)
+}
+
+fun getUserDisplayName(id: UserId): String =
+    findUser(id).map { it.name }.recover { "Unknown User" }.getOrThrow()
+
+fun handleLookup(id: UserId): Response = findUser(id).fold(
+    onSuccess = { Response.ok(it) },
+    onFailure = { Response.notFound(it.message) },
+)
+```
+
+### Sealed Class Error Hierarchy
+```kotlin
+sealed class DomainError(override val message: String) : Exception(message) {
+    data class NotFound(val resource: String, val id: String) : DomainError("$resource not found: $id")
+    data class Validation(val field: String, val reason: String) : DomainError("Invalid $field: $reason")
+    data class Conflict(val detail: String) : DomainError("Conflict: $detail")
+}
+
+fun handleError(error: DomainError): Response = when (error) {
+    is DomainError.NotFound -> Response.status(404).body(error.message)
+    is DomainError.Validation -> Response.status(422).body(error.message)
+    is DomainError.Conflict -> Response.status(409).body(error.message)
+}
+```
+
+### Preconditions
+```kotlin
+fun transferMoney(from: Account, to: Account, amount: Money) {
+    require(amount.value > 0) { "Transfer amount must be positive" }
+    require(from.id != to.id) { "Cannot transfer to same account" }
+    check(from.balance >= amount) { "Insufficient funds: ${from.balance}" }
+}
+```
+
+---
+
+## Testing Patterns
+
+### JUnit 5 + MockK
+```kotlin
+class UserServiceTest {
+    private val repository = mockk<UserRepository>()
+    private val notifier = mockk<NotificationService>(relaxed = true)
+    private val service = UserService(repository, notifier)
+
+    @Test
+    fun `creates user and sends welcome notification`() {
+        val expected = User(UserId("1"), "Alice", "alice@test.com")
+        every { repository.save(any()) } returns expected
+
+        val result = service.createUser(CreateUserRequest("Alice", "alice@test.com"))
+
+        assertThat(result).isEqualTo(expected)
+        verify(exactly = 1) { notifier.sendWelcome(expected) }
+    }
+
+    @Test
+    fun `throws on duplicate email`() {
+        every { repository.save(any()) } throws DomainError.Conflict("Email exists")
+        assertThrows<DomainError.Conflict> {
+            service.createUser(CreateUserRequest("Bob", "dup@test.com"))
+        }
+    }
+}
+```
+
+### Kotest + Property-Based Testing
+```kotlin
+class MoneySpec : FunSpec({
+    test("addition is commutative") {
+        checkAll(Arb.positiveLong(), Arb.positiveLong()) { a, b ->
+            Money(a) + Money(b) shouldBe Money(b) + Money(a)
+        }
+    }
+    test("cannot create negative money") {
+        shouldThrow<IllegalArgumentException> { Money(-1) }
+    }
+})
+```
+
+### assertSoftly + Parameterized Tests
+```kotlin
+@Test
+fun `user has correct defaults`() {
+    val user = User.create("Alice", "alice@test.com")
+    assertSoftly(user) {
+        name shouldBe "Alice"
+        role shouldBe Role.USER
+        isActive shouldBe true
+    }
+}
+
+@ParameterizedTest
+@CsvSource("alice@test.com, true", "not-an-email, false", "'', false")
+fun `validates email format`(input: String, expected: Boolean) {
+    assertThat(isValidEmail(input)).isEqualTo(expected)
+}
+```
+
+---
+
+## Common Frameworks
+
+### Spring Boot with Kotlin
+```kotlin
+@RestController
+@RequestMapping("/api/v1/users")
+class UserController(private val userService: UserService) {
+    @GetMapping("/{id}")
+    fun getUser(@PathVariable id: String): ResponseEntity<UserDto> =
+        userService.findById(UserId(id))?.let { ResponseEntity.ok(it.toDto()) }
+            ?: ResponseEntity.notFound().build()
+
+    @PostMapping
+    fun createUser(@Valid @RequestBody req: CreateUserRequest): ResponseEntity<UserDto> {
+        val user = userService.create(req)
+        return ResponseEntity.created(URI("/api/v1/users/${user.id.value}")).body(user.toDto())
+    }
+}
+```
+
+### Ktor
+```kotlin
+fun Application.configureRouting() {
+    routing {
+        route("/api/v1/users") {
+            get { call.respond(userService.listAll()) }
+            get("/{id}") {
+                val id = call.parameters["id"] ?: return@get call.respond(HttpStatusCode.BadRequest)
+                val user = userService.findById(UserId(id)) ?: return@get call.respond(HttpStatusCode.NotFound)
+                call.respond(user)
+            }
+            post {
+                val req = call.receive<CreateUserRequest>()
+                call.respond(HttpStatusCode.Created, userService.create(req))
+            }
+        }
+    }
+}
+
+fun Application.configurePlugins() {
+    install(ContentNegotiation) { json() }
+    install(StatusPages) {
+        exception<DomainError.NotFound> { call, e -> call.respond(HttpStatusCode.NotFound, e.message) }
+    }
+}
+```
+
+### Exposed (SQL DSL)
+```kotlin
+object Users : Table("users") {
+    val id = varchar("id", 36)
+    val name = varchar("name", 255)
+    val email = varchar("email", 255).uniqueIndex()
+    val role = enumerationByName<Role>("role", 20)
+    override val primaryKey = PrimaryKey(id)
+}
+
+suspend fun findByRole(role: Role): List<User> = newSuspendedTransaction(Dispatchers.IO) {
+    Users.selectAll().where { Users.role eq role }.map { it.toUser() }
+}
+```
+
+### kotlinx.serialization
+```kotlin
+@Serializable
+data class ApiResponse<T>(val data: T, val meta: Meta? = null)
+
+@Serializable
+data class Meta(val page: Int, val totalPages: Int, val totalItems: Long)
+```
+
+### Koin (DI)
+```kotlin
+val appModule = module {
+    singleOf(::UserRepository)
+    singleOf(::UserService)
+    factoryOf(::CreateUserUseCase)
+}
+fun Application.configureKoin() { install(Koin) { modules(appModule) } }
+```
+
+---
+
+## Performance Tips
+
+### Inline Functions
+```kotlin
+inline fun <T> measureTimeAndReturn(block: () -> T): Pair<T, Duration> {
+    val start = System.nanoTime()
+    val result = block()
+    return result to Duration.ofNanos(System.nanoTime() - start)
+}
+// crossinline: prevents non-local returns
+inline fun transaction(crossinline block: () -> Unit) {
+    begin(); try { block() } catch (e: Exception) { rollback(); throw e }; commit()
+}
+```
+
+### Value Classes
+```kotlin
+@JvmInline value class Email(val value: String) {
+    init { require(value.contains("@")) }
+}
+@JvmInline value class Meters(val value: Double)
+// Compiles to raw String/Double -- zero object allocation
+```
+
+### Sequences vs Lists
+```kotlin
+// Bad: 3 intermediate lists
+users.filter { it.isActive }.map { it.name }.take(10)
+// Good: lazy, single pass, stops after 10
+users.asSequence().filter { it.isActive }.map { it.name }.take(10).toList()
+// Rule: sequences for 3+ chained ops on 1000+ elements
+```
+
+### Coroutines
+```kotlin
+suspend fun loadDashboard(userId: String): Dashboard = coroutineScope {
+    val profile = async { userService.getProfile(userId) }
+    val orders = async { orderService.getRecent(userId) }
+    val notifs = async { notificationService.getUnread(userId) }
+    Dashboard(profile.await(), orders.await(), notifs.await())
+}
+
+fun observeOrders(): Flow<Order> =
+    orderRepository.observe().map { it.toDomain() }.catch { emit(Order.EMPTY) }.flowOn(Dispatchers.IO)
+```
+
+### Avoid Reflection
+```kotlin
+// Bad: Gson uses reflection -- slow, no compile-time safety
+val json = Gson().toJson(user)
+// Good: kotlinx.serialization uses compile-time codegen
+@Serializable data class User(val id: String, val name: String)
+val json = Json.encodeToString(user)
+```
+
+---
+
+## Build / Package Management
+
+### Version Catalog (gradle/libs.versions.toml)
+```toml
+[versions]
+kotlin = "2.1.0"
+coroutines = "1.10.1"
+ktor = "3.0.3"
+kotest = "5.9.1"
+mockk = "1.13.14"
+
+[libraries]
+kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version = "1.7.3" }
+ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
+mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
+kotest-runner = { module = "io.kotest:kotest-runner-junit5", version.ref = "kotest" }
+kotest-assertions = { module = "io.kotest:kotest-assertions-core", version.ref = "kotest" }
+
+[bundles]
+testing = ["mockk", "kotest-runner", "kotest-assertions"]
+
+[plugins]
+kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+```
+
+### Kotlin Multiplatform
+```kotlin
+kotlin {
+    jvm(); iosArm64(); iosSimulatorArm64(); js(IR) { browser() }
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.kotlinx.coroutines.core)
+            implementation(libs.kotlinx.serialization.json)
+        }
+        commonTest.dependencies { implementation(kotlin("test")) }
+        jvmMain.dependencies { implementation(libs.ktor.server.core) }
+    }
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| `!!` everywhere | NPE at runtime | Safe calls, elvis, `requireNotNull` |
+| `var` by default | Mutability bugs | Default to `val` |
+| Catching `Exception` | Swallows `CancellationException` | Catch specific types |
+| Mutable data class props | Breaks hashCode/equals | Use `val` in data classes |
+| Stringly-typed IDs | Mix up userId/orderId | Value classes |
+| Blocking in coroutine | Thread starvation | `withContext(Dispatchers.IO)` |
+| Ignoring `Result` failures | Silent errors | Always handle both paths |
+| God object / util class | No cohesion | Extension functions |

package/app/skills/lint/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: lint
+description: "Lint code with auto-detected tools and fix suggestions"
+effort: low
+disable-model-invocation: true
+argument-hint: "[path]"
+allowed-tools: Bash, Read
+---
+
+# Lint Runner
+
+$ARGUMENTS
+
+Run linting and type checking based on detected project type.
+
+## Project context
+
+- Project files: !`ls pyproject.toml package.json composer.json pubspec.yaml go.mod 2>/dev/null`
+
+## Auto-Detection
+
+Run the bundled script to detect available linters:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/detect-linters.py .
+```
+
+## Usage
+
+```
+/lint [path]
+```
+
+## Commands by Project Type
+
+| Project Type | Lint Command | Type Check |
+|--------------|--------------|------------|
+| **Python** | `ruff check .` | `mypy .` |
+| **TypeScript/Node** | `npx eslint .` | `npx tsc --noEmit` |
+| **PHP** | `./vendor/bin/phpstan analyse` | - |
+| **Go** | `golangci-lint run` | - |
+| **Rust** | `cargo clippy` | - |
+| **Flutter/Dart** | `dart analyze` | - |
+
+## Python Projects
+
+```bash
+# Linting
+ruff check .
+
+# Type checking
+mypy .
+
+# Auto-fix
+ruff check --fix .
+ruff format .
+```
+
+## TypeScript/Node Projects
+
+```bash
+# Linting
+npx eslint .
+
+# Type checking
+npx tsc --noEmit
+
+# Auto-fix
+npx eslint --fix .
+```
+
+## PHP Projects
+
+```bash
+# Static analysis
+./vendor/bin/phpstan analyse
+
+# Code style
+./vendor/bin/phpcs
+./vendor/bin/phpcbf  # auto-fix
+```
+
+## Docker Execution (if applicable)
+
+```bash
+# Generic pattern - replace {container} with your app container
+docker exec {container} make lint
+docker exec {container} make typecheck
+```
+
+## Quality Gates
+
+- Linting: 0 errors
+- Type checking: 0 errors (for new code)
+
+## Common Issues
+
+| Error | Fix |
+|-------|-----|
+| Missing type hints | Add type annotations |
+| Unused imports | Remove or use `# noqa: F401` |
+| Line too long | Break line or disable for that line |
+| Import order | Let linter fix with `--fix` |

package/app/skills/lint/scripts/detect-linters.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Detect available linters and build combined lint/format commands for a project.
+
+Scans a project directory for Python, Node.js, PHP, Go, and Dart
+configuration files, checks which linters are installed or configured,
+and returns a JSON object with individual linter entries, a combined
+check command, and available format commands.
+
+Usage::
+
+    python3 detect-linters.py [project_directory]
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+from _lib.detect_utils import is_installed, read_json, read_text, run_detector
+
+
+def detect(project_dir: Path) -> dict[str, Any]:
+    """Detect linters configured or installed for the project."""
+    linters: list[dict[str, Any]] = []
+    format_commands: list[str] = []
+
+    # Python: pyproject.toml
+    pyproject = read_text(project_dir / "pyproject.toml")
+    if pyproject or (project_dir / "setup.py").exists():
+        py_linters: dict[str, dict[str, str | None]] = {
+            "ruff": {"check": "ruff check .", "fix": "ruff check --fix .", "format": "ruff format ."},
+            "flake8": {"check": "flake8 .", "fix": None, "format": None},
+            "pylint": {"check": "pylint src/", "fix": None, "format": None},
+            "mypy": {"check": "mypy .", "fix": None, "format": None},
+            "black": {"check": "black --check .", "fix": None, "format": "black ."},
+        }
+        for name, cmds in py_linters.items():
+            configured = pyproject and name in pyproject if pyproject else False
+            installed = is_installed(name)
+            if configured or installed:
+                linters.append({"name": name, "language": "python", "installed": installed,
+                                "configured": configured, "check_command": cmds["check"],
+                                "fix_command": cmds["fix"]})
+                if cmds.get("format"):
+                    format_commands.append(cmds["format"])  # type: ignore[arg-type]
+
+    # Node.js: package.json
+    pkg = read_json(project_dir / "package.json")
+    if pkg:
+        dev_deps = {**pkg.get("devDependencies", {}), **pkg.get("dependencies", {})}
+        node_linters: dict[str, dict[str, str | None]] = {
+            "eslint": {"check": "npx eslint .", "fix": "npx eslint --fix ."},
+            "prettier": {"check": "npx prettier --check .", "format": "npx prettier --write ."},
+            "tsc": {"check": "npx tsc --noEmit", "fix": None},
+        }
+        for name, cmds in node_linters.items():
+            in_deps = name in dev_deps or (name == "tsc" and "typescript" in dev_deps)
+            installed = is_installed(f"npx {name}") if name != "tsc" else is_installed("npx tsc")
+            if in_deps:
+                linters.append({"name": name, "language": "javascript/typescript",
+                                "installed": True, "configured": in_deps,
+                                "check_command": cmds["check"], "fix_command": cmds.get("fix")})
+                if cmds.get("format"):
+                    format_commands.append(cmds["format"])  # type: ignore[arg-type]
+
+    # PHP: composer.json
+    composer = read_json(project_dir / "composer.json")
+    if composer:
+        require_dev: dict[str, str] = composer.get("require-dev", {})
+        php_linters: dict[str, dict[str, str]] = {
+            "phpstan": {"check": "./vendor/bin/phpstan analyse", "pkg": "phpstan/phpstan"},
+            "psalm": {"check": "./vendor/bin/psalm", "pkg": "vimeo/psalm"},
+            "phpcs": {"check": "./vendor/bin/phpcs", "pkg": "squizlabs/php_codesniffer"},
+        }
+        for name, info in php_linters.items():
+            in_deps = any(info["pkg"] in k for k in require_dev)
+            if in_deps:
+                linters.append({"name": name, "language": "php", "installed": True,
+                                "configured": True, "check_command": info["check"], "fix_command": None})
+
+    # Go: .golangci.yml
+    if (project_dir / "go.mod").exists():
+        go_lint: dict[str, str | None] = {"check": "golangci-lint run", "fix": None}
+        configured = (project_dir / ".golangci.yml").exists() or (project_dir / ".golangci.yaml").exists()
+        installed = is_installed("golangci-lint")
+        if configured or installed:
+            linters.append({"name": "golangci-lint", "language": "go", "installed": installed,
+                            "configured": configured, "check_command": go_lint["check"], "fix_command": None})
+        linters.append({"name": "go-vet", "language": "go", "installed": True,
+                        "configured": True, "check_command": "go vet ./...", "fix_command": None})
+
+    # Dart: pubspec.yaml
+    if (project_dir / "pubspec.yaml").exists():
+        linters.append({"name": "dart-analyze", "language": "dart", "installed": is_installed("dart"),
+                        "configured": True, "check_command": "dart analyze", "fix_command": "dart fix --apply"})
+
+    # Build combined command
+    check_parts = [l["check_command"] for l in linters if l.get("installed") and l.get("check_command")]
+    combined = " && ".join(check_parts) if check_parts else None
+
+    return {
+        "linters": linters,
+        "combined_command": combined,
+        "format_commands": format_commands,
+        "linter_count": len(linters),
+        "installed_count": sum(1 for l in linters if l.get("installed")),
+    }
+
+
+if __name__ == "__main__":
+    run_detector(detect)