@c0x12c/ai-toolkit 1.15.0

package/skills/database-table-creator/kotlin-templates.md

@@ -0,0 +1,400 @@
+# Kotlin Implementation Templates
+
+Code templates for Steps 3-10 of the database table creation workflow.
+Referenced from SKILL.md — use these templates when generating Kotlin code.
+
+## Step 3: Create Kotlin Table Object
+
+Location: `app/module-repository/src/main/kotlin/com/yourcompany/postgresql/table/{TableName}Table.kt`
+
+```kotlin
+package com.yourcompany.postgresql.table
+
+import org.jetbrains.exposed.dao.id.UUIDTable
+import org.jetbrains.exposed.sql.javatime.timestamp
+import java.time.Instant
+
+object {TableName}Table : UUIDTable("{table_name}") {  // MUST extend UUIDTable
+  // Business columns
+  val name = text("name")  // Use text() not varchar()
+  val email = text("email").nullable()
+  val status = text("status").default("active")
+  val userId = uuid("user_id").nullable()
+  val count = integer("count").default(0)
+  val isActive = bool("is_active").default(true)
+  val metadata = jsonb<Map<String, Any>>("metadata").nullable()
+
+  // Standard timestamps (REQUIRED)
+  val createdAt = timestamp("created_at").clientDefault { Instant.now() }
+  val updatedAt = timestamp("updated_at").nullable()
+  val deletedAt = timestamp("deleted_at").nullable()
+}
+```
+
+**Key Points**:
+- MUST extend `UUIDTable` (not `Table`)
+- Use `text()` for strings (not `varchar()`)
+- Column names match SQL exactly (snake_case in SQL)
+- Use `.nullable()` for optional fields
+- All three timestamp columns required
+
+## Step 4: Create Entity Data Class
+
+Location: `app/module-repository/src/main/kotlin/com/yourcompany/postgresql/entity/{TableName}Entity.kt`
+
+```kotlin
+package com.yourcompany.postgresql.entity
+
+import java.time.Instant
+import java.util.UUID
+
+data class {TableName}Entity(
+  override val id: UUID = UUID.randomUUID(),
+  val name: String,
+  val email: String? = null,
+  val status: String = "active",
+  val userId: UUID? = null,
+  val count: Int = 0,
+  val isActive: Boolean = true,
+  val metadata: Map<String, Any>? = null,
+  override val createdAt: Instant = Instant.now(),
+  override val updatedAt: Instant? = null,
+  override val deletedAt: Instant? = null
+) : Entity<Instant>  // MUST implement Entity<Instant>
+```
+
+**Key Points**:
+- MUST be `data class`
+- MUST implement `Entity<Instant>`
+- MUST override: id, createdAt, updatedAt, deletedAt
+- Use proper Kotlin types (String for TEXT, UUID for ids, Instant for timestamps)
+- Nullable fields have `? = null` defaults
+
+## Step 5: Create Constants/Enums (if needed)
+
+Location: `app/module-repository/src/main/kotlin/com/yourcompany/postgresql/constant/`
+
+```kotlin
+package com.yourcompany.postgresql.constant
+
+enum class {TableName}Status {
+  ACTIVE,
+  INACTIVE,
+  ARCHIVED
+}
+```
+
+Create enums for status, type, or role columns.
+
+## Step 6: Create Repository Interface
+
+Location: `app/module-repository/src/main/kotlin/com/yourcompany/postgresql/repository/{TableName}Repository.kt`
+
+```kotlin
+package com.yourcompany.postgresql.repository
+
+import com.yourcompany.postgresql.entity.{TableName}Entity
+import java.util.UUID
+
+interface {TableName}Repository {
+  fun insert(entity: {TableName}Entity): {TableName}Entity
+  fun update(id: UUID, name: String?, email: String?): {TableName}Entity?
+  fun byId(id: UUID): {TableName}Entity?
+  fun byEmail(email: String): {TableName}Entity?
+  fun deleteById(id: UUID): {TableName}Entity?
+  fun restoreById(id: UUID): {TableName}Entity?
+}
+```
+
+## Step 7: Create Repository Implementation
+
+Location: `app/module-repository/src/main/kotlin/com/yourcompany/postgresql/repository/Default{TableName}Repository.kt`
+
+```kotlin
+package com.yourcompany.postgresql.repository
+
+import com.yourcompany.database.DatabaseContext
+import com.yourcompany.postgresql.entity.{TableName}Entity
+import com.yourcompany.postgresql.table.{TableName}Table
+import org.jetbrains.exposed.sql.*
+import org.jetbrains.exposed.sql.SqlExpressionBuilder.eq
+import org.jetbrains.exposed.sql.transactions.transaction
+import java.time.Instant
+import java.util.UUID
+
+class Default{TableName}Repository(
+  private val db: DatabaseContext
+) : {TableName}Repository {
+
+  override fun insert(entity: {TableName}Entity): {TableName}Entity {
+    return transaction(db.primary) {  // Use db.primary for writes
+      {TableName}Table.insert {
+        it[id] = entity.id
+        it[name] = entity.name
+        it[email] = entity.email
+        it[status] = entity.status
+        // ... map all fields
+        it[createdAt] = entity.createdAt
+        it[updatedAt] = entity.updatedAt
+        it[deletedAt] = entity.deletedAt
+      }
+      entity
+    }
+  }
+
+  override fun update(
+    id: UUID,
+    name: String?,
+    email: String?
+  ): {TableName}Entity? {
+    return transaction(db.primary) {
+      val updated = {TableName}Table.update(
+        where = {
+          {TableName}Table.id eq id and
+          {TableName}Table.deletedAt.isNull()  // CRITICAL: Filter soft deletes
+        }
+      ) {
+        name?.let { value -> it[{TableName}Table.name] = value }
+        email?.let { value -> it[{TableName}Table.email] = value }
+        // updatedAt automatically set by trigger
+      }
+      if (updated > 0) byId(id) else null
+    }
+  }
+
+  override fun byId(id: UUID): {TableName}Entity? {
+    return transaction(db.replica) {  // Use db.replica for reads
+      {TableName}Table
+        .selectAll()
+        .where { {TableName}Table.id eq id }
+        .andWhere { {TableName}Table.deletedAt.isNull() }  // CRITICAL
+        .map { convert(it) }
+        .singleOrNull()  // Return null if not found
+    }
+  }
+
+  override fun byEmail(email: String): {TableName}Entity? {
+    return transaction(db.replica) {
+      {TableName}Table
+        .selectAll()
+        .where { {TableName}Table.email eq email }
+        .andWhere { {TableName}Table.deletedAt.isNull() }  // ALWAYS filter
+        .map { convert(it) }
+        .singleOrNull()
+    }
+  }
+
+  override fun deleteById(id: UUID): {TableName}Entity? {
+    return transaction(db.primary) {
+      val updated = {TableName}Table.update(
+        where = {
+          {TableName}Table.id eq id and
+          {TableName}Table.deletedAt.isNull()  // Only delete active records
+        }
+      ) {
+        it[deletedAt] = Instant.now()  // Soft delete: set timestamp
+      }
+      if (updated > 0) {
+        // Return soft-deleted entity
+        {TableName}Table
+          .selectAll()
+          .where { {TableName}Table.id eq id }
+          .map { convert(it) }
+          .singleOrNull()
+      } else null
+    }
+  }
+
+  override fun restoreById(id: UUID): {TableName}Entity? {
+    return transaction(db.primary) {
+      val updated = {TableName}Table.update(
+        where = {
+          {TableName}Table.id eq id and
+          {TableName}Table.deletedAt.isNotNull()  // Only restore deleted
+        }
+      ) {
+        it[deletedAt] = null  // Restore: clear timestamp
+      }
+      if (updated > 0) byId(id) else null
+    }
+  }
+
+  // Private helper for mapping
+  private fun convert(row: ResultRow): {TableName}Entity {
+    return {TableName}Entity(
+      id = row[{TableName}Table.id].value,  // UUID needs .value
+      name = row[{TableName}Table.name],
+      email = row[{TableName}Table.email],
+      status = row[{TableName}Table.status],
+      userId = row[{TableName}Table.userId],
+      count = row[{TableName}Table.count],
+      isActive = row[{TableName}Table.isActive],
+      metadata = row[{TableName}Table.metadata],
+      createdAt = row[{TableName}Table.createdAt],
+      updatedAt = row[{TableName}Table.updatedAt],
+      deletedAt = row[{TableName}Table.deletedAt]
+    )
+  }
+}
+```
+
+**Critical**:
+- Use `transaction(db.primary)` for writes
+- Use `transaction(db.replica)` for reads
+- ALWAYS filter `deletedAt.isNull()` in queries
+- Soft delete sets `deletedAt = Instant.now()`
+- Return null when not found (don't throw)
+- NO `!!` operators anywhere
+
+## Step 8: Register Factory Bean
+
+Edit `app/module-repository/src/main/kotlin/com/yourcompany/runtime/factory/RepositoryFactory.kt`:
+
+```kotlin
+@Factory
+class RepositoryFactory {
+
+  @Singleton
+  fun provide{TableName}Repository(db: DatabaseContext): {TableName}Repository {
+    return Default{TableName}Repository(db)
+  }
+}
+```
+
+## Step 9: Write Repository Tests
+
+Location: `app/module-repository/src/test/kotlin/com/yourcompany/postgresql/repository/Default{TableName}RepositoryTest.kt`
+
+```kotlin
+package com.yourcompany.postgresql.repository
+
+import assertk.assertThat
+import assertk.assertions.*
+import com.yourcompany.postgresql.entity.{TableName}Entity
+import io.micronaut.test.extensions.junit5.annotation.MicronautTest
+import jakarta.inject.Inject
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+import java.util.UUID
+
+@MicronautTest(environments = ["test"])
+class Default{TableName}RepositoryTest : AbstractRepositoryTest() {
+
+  @Inject
+  lateinit var repository: {TableName}Repository
+
+  @BeforeEach
+  fun setup() {
+    database.primary.truncateAllTables()
+  }
+
+  @Test
+  fun `insert - creates entity successfully`() {
+    val entity = dummyEntity()
+
+    val result = repository.insert(entity)
+
+    assertThat(result.id).isEqualTo(entity.id)
+    assertThat(result.name).isEqualTo(entity.name)
+  }
+
+  @Test
+  fun `update - updates selected fields only`() {
+    val entity = repository.insert(dummyEntity())
+    val newName = "Updated Name"
+
+    val updated = repository.update(
+      id = entity.id,
+      name = newName,
+      email = null
+    )
+
+    assertThat(updated).isNotNull()
+    assertThat(updated?.name).isEqualTo(newName)
+    assertThat(updated?.email).isEqualTo(entity.email)  // Unchanged
+  }
+
+  @Test
+  fun `byId - returns entity when exists`() {
+    val entity = repository.insert(dummyEntity())
+
+    val result = repository.byId(entity.id)
+
+    assertThat(result).isNotNull()
+    assertThat(result?.id).isEqualTo(entity.id)
+  }
+
+  @Test
+  fun `byId - returns null when not exists`() {
+    val randomId = UUID.randomUUID()
+
+    val result = repository.byId(randomId)
+
+    assertThat(result).isNull()
+  }
+
+  @Test
+  fun `byId - returns null when soft deleted`() {
+    val entity = repository.insert(dummyEntity())
+    repository.deleteById(entity.id)
+
+    val result = repository.byId(entity.id)
+
+    assertThat(result).isNull()  // Critical: soft deleted not returned
+  }
+
+  @Test
+  fun `deleteById - soft deletes entity`() {
+    val entity = repository.insert(dummyEntity())
+
+    val deleted = repository.deleteById(entity.id)
+
+    assertThat(deleted).isNotNull()
+    assertThat(deleted?.deletedAt).isNotNull()  // Has timestamp
+    assertThat(repository.byId(entity.id)).isNull()  // Not found
+  }
+
+  @Test
+  fun `restoreById - restores soft deleted entity`() {
+    val entity = repository.insert(dummyEntity())
+    repository.deleteById(entity.id)
+
+    val restored = repository.restoreById(entity.id)
+
+    assertThat(restored).isNotNull()
+    assertThat(restored?.deletedAt).isNull()  // Timestamp cleared
+    assertThat(repository.byId(entity.id)).isNotNull()  // Found again
+  }
+
+  private fun dummyEntity(
+    id: UUID = UUID.randomUUID(),
+    name: String = randomText(),
+    email: String = randomEmail()
+  ) = {TableName}Entity(
+    id = id,
+    name = name,
+    email = email
+  )
+}
+```
+
+**Required tests** (minimum 7):
+1. Insert happy path
+2. Update modifies fields
+3. byId returns entity when exists
+4. byId returns null when not exists
+5. byId returns null when soft deleted (critical)
+6. deleteById soft deletes
+7. restoreById restores soft deleted
+
+## Step 10: Run Tests
+
+```bash
+# Run repository tests
+./gradlew :app:module-repository:test --tests "Default{TableName}RepositoryTest"
+
+# Run all tests
+./gradlew test
+```
+
+All tests MUST pass.

package/skills/database-table-creator/migration-template.sql

@@ -0,0 +1,68 @@
+-- ============================================================================
+-- Description: [REPLACE: Describe what this migration does]
+-- Table: [REPLACE: table_name]
+-- Date: [REPLACE: YYYY-MM-DD]
+-- ============================================================================
+
+-- Create table
+CREATE TABLE [REPLACE_table_name] (
+    -- Primary key (REQUIRED for all tables)
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+    -- [REPLACE: Add your business columns here]
+    -- Examples:
+    -- name TEXT NOT NULL,
+    -- email TEXT,
+    -- status TEXT DEFAULT 'active',
+    -- user_id UUID,
+    -- count INTEGER DEFAULT 0,
+    -- is_active BOOLEAN DEFAULT true,
+    -- metadata JSONB,
+
+    -- Standard timestamp columns (REQUIRED for all tables)
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP,
+    deleted_at TIMESTAMP
+);
+
+-- Indexes
+-- CRITICAL: ALL indexes MUST include "WHERE deleted_at IS NULL"
+
+-- Unique index example (prevents duplicate active records, allows duplicate soft-deleted)
+-- CREATE UNIQUE INDEX idx_[REPLACE_table_name]_[REPLACE_column]_unique
+--     ON [REPLACE_table_name]([REPLACE_column]) WHERE deleted_at IS NULL;
+
+-- Foreign key index example (no FK constraint, just index for performance)
+-- CREATE INDEX idx_[REPLACE_table_name]_[REPLACE_foreign_key]
+--     ON [REPLACE_table_name]([REPLACE_foreign_key]) WHERE deleted_at IS NULL;
+
+-- Soft delete index (REQUIRED for all tables with soft deletes)
+CREATE INDEX idx_[REPLACE_table_name]_deleted_at
+    ON [REPLACE_table_name](deleted_at) WHERE deleted_at IS NOT NULL;
+
+-- Update trigger (REQUIRED for all tables except immutable audit tables)
+CREATE TRIGGER update_[REPLACE_table_name]_updated_at
+BEFORE UPDATE ON [REPLACE_table_name]
+FOR EACH ROW
+EXECUTE FUNCTION update_updated_at();
+
+-- ============================================================================
+-- CRITICAL RULES (from rules/database/SCHEMA.md):
+-- ============================================================================
+-- ✅ Use TEXT for strings (NEVER VARCHAR)
+-- ✅ Use UUID for primary keys and foreign keys
+-- ✅ Use TIMESTAMP for dates/times
+-- ✅ Include: id, created_at, updated_at, deleted_at
+-- ✅ Add WHERE deleted_at IS NULL to ALL indexes
+-- ✅ Add soft delete index on deleted_at
+-- ✅ Add update trigger for updated_at
+--
+-- ❌ NO FOREIGN KEY constraints
+-- ❌ NO REFERENCES clauses
+-- ❌ NO ON DELETE CASCADE
+-- ❌ NO VARCHAR (use TEXT instead)
+-- ============================================================================
+
+-- [OPTIONAL: Add comments explaining business logic]
+-- COMMENT ON TABLE [REPLACE_table_name] IS 'Brief description of table purpose';
+-- COMMENT ON COLUMN [REPLACE_table_name].[REPLACE_column] IS 'Brief description of column';