Feature/storm 109 (#110)

Add Ktor integration support. (#109)

Author: zantvoort

docs/ai.md

@@ -56,17 +56,18 @@ For each selected tool, Storm installs two types of AI context:
 
 | Skill | Purpose |
 |-------|---------|
+| storm-setup | Configure dependencies (detects Spring Boot, Ktor, or standalone) |
 | storm-docs | Load full Storm documentation |
 | storm-entity-kotlin | Create Kotlin entities |
 | storm-entity-java | Create Java entities |
-| storm-repository-kotlin | Write Kotlin repositories |
+| storm-repository-kotlin | Write Kotlin repositories (framework-aware: Spring Boot, Ktor, standalone) |
 | storm-repository-java | Write Java repositories |
 | storm-query-kotlin | Kotlin QueryBuilder queries |
 | storm-query-java | Java QueryBuilder queries |
 | storm-sql-kotlin | Kotlin SQL Templates |
 | storm-sql-java | Java SQL Templates |
 | storm-json-kotlin / storm-json-java | JSON columns and JSON aggregation |
-| storm-serialization-kotlin / storm-serialization-java | Entity serialization for REST APIs (Ref handling) |
+| storm-serialization-kotlin / storm-serialization-java | Entity serialization for REST APIs (framework-aware content negotiation) |
 | storm-migration | Write Flyway/Liquibase migration SQL |
 
 ### 3. Database connection (optional)

docs/configuration.md

@@ -3,7 +3,7 @@ import TabItem from '@theme/TabItem';
 
 # Configuration
 
-Storm can be configured through `StormConfig`, system properties, or Spring Boot's `application.yml`. These properties control runtime behavior for features like dirty checking and entity caching. All properties have sensible defaults, so **configuration is optional**. Storm works out of the box without any configuration.
+Storm can be configured through `StormConfig`, system properties, Spring Boot's `application.yml`, or Ktor's `application.conf`. These properties control runtime behavior for features like dirty checking and entity caching. All properties have sensible defaults, so **configuration is optional**. Storm works out of the box without any configuration.
 
 ---
 
@@ -17,7 +17,7 @@ Storm can be configured through `StormConfig`, system properties, or Spring Boot
 | `storm.entity_cache.retention` | `default` | Cache retention mode: `default` or `light` |
 | `storm.template_cache.size` | `2048` | Maximum number of compiled templates to cache |
 | `storm.validation.record_mode` | `fail` | Record validation mode: `fail`, `warn`, or `none` |
-| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot only) |
+| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
 | `storm.validation.strict` | `false` | Treat schema validation warnings as errors |
 | `storm.validation.interpolation_mode` | `warn` | Interpolation safety mode: `warn`, `fail`, or `none` (see [Interpolation Safety](#interpolation-safety)) |
 | `st.orm.scrollable.maxSize` | `1000` | Maximum window size allowed in a serialized cursor (system property only) |
@@ -44,9 +44,9 @@ java -Dstorm.update.default_mode=FIELD \
 
 ```kotlin
 val config = StormConfig.of(mapOf(
-    "storm.update.default_mode" to "FIELD",
-    "storm.entity_cache.retention" to "light",
-    "storm.template_cache.size" to "4096"
+    UPDATE_DEFAULT_MODE to "FIELD",
+    ENTITY_CACHE_RETENTION to "light",
+    TEMPLATE_CACHE_SIZE to "4096"
 ))
 
 val orm = ORMTemplate.of(dataSource, config)
@@ -60,9 +60,9 @@ val orm = dataSource.orm(config)
 
 ```java
 var config = StormConfig.of(Map.of(
-    "storm.update.default_mode", "FIELD",
-    "storm.entity_cache.retention", "light",
-    "storm.template_cache.size", "4096"
+    UPDATE_DEFAULT_MODE, "FIELD",
+    ENTITY_CACHE_RETENTION, "light",
+    TEMPLATE_CACHE_SIZE, "4096"
 ));
 
 var orm = ORMTemplate.of(dataSource, config);
@@ -94,6 +94,32 @@ storm:
 
 The Spring Boot Starter binds these properties and builds a `StormConfig` that is passed to the `ORMTemplate` factory. Values not set in YAML fall back to system properties and then to built-in defaults. See [Spring Integration](spring-integration.md#configuration-via-applicationyml) for details.
 
+**In Ktor's `application.conf`** (requires `storm-ktor`):
+
+```hocon
+storm {
+    ansiEscaping = false
+    update {
+        defaultMode = "ENTITY"
+        dirtyCheck = "INSTANCE"
+        maxShapes = 5
+    }
+    entityCache {
+        retention = "default"
+    }
+    templateCache {
+        size = 2048
+    }
+    validation {
+        recordMode = "fail"
+        schemaMode = "none"
+        strict = false
+    }
+}
+```
+
+The Storm Ktor plugin reads these properties and builds a `StormConfig` that is passed to the `ORMTemplate` factory. HOCON supports environment variable substitution with `${?VAR_NAME}` syntax. See [Ktor Integration](ktor-integration.md#configuration) for details.
+
 ---
 
 ## ORMTemplate Factory Overloads

docs/dirty-checking.md

@@ -402,7 +402,7 @@ data class User(
 Globally via `StormConfig` or system property:
 
 ```kotlin
-val config = StormConfig.of(mapOf("storm.update.dirty_check" to "VALUE"))
+val config = StormConfig.of(mapOf(UPDATE_DIRTY_CHECK to "VALUE"))
 ```
 
 ```bash
@@ -453,7 +453,7 @@ Storm enforces a **maximum number of UPDATE shapes per entity**. Once this limit
 **Configure via `StormConfig` or system property:**
 
 ```kotlin
-val config = StormConfig.of(mapOf("storm.update.max_shapes" to "10"))
+val config = StormConfig.of(mapOf(UPDATE_MAX_SHAPES to "10"))
 ```
 
 ```bash
@@ -491,9 +491,9 @@ For cache retention settings, see [Entity Cache Configuration](entity-cache.md#c
 ```kotlin
 // Via StormConfig
 val config = StormConfig.of(mapOf(
-    "storm.update.default_mode" to "FIELD",
-    "storm.update.dirty_check" to "VALUE",
-    "storm.update.max_shapes" to "10"
+    UPDATE_DEFAULT_MODE to "FIELD",
+    UPDATE_DIRTY_CHECK to "VALUE",
+    UPDATE_MAX_SHAPES to "10"
 ))
 val orm = ORMTemplate.of(dataSource, config)
 ```

docs/entity-cache.md

@@ -213,7 +213,7 @@ The `default` mode retains entities for the duration of the transaction, which p
 Configure retention behavior via `StormConfig` or system property:
 
 ```kotlin
-val config = StormConfig.of(mapOf("storm.entity_cache.retention" to "light"))
+val config = StormConfig.of(mapOf(ENTITY_CACHE_RETENTION to "light"))
 val orm = ORMTemplate.of(dataSource, config)
 ```
 

docs/first-entity.md

@@ -158,7 +158,7 @@ The `insertAndFetch` method sends an INSERT statement, retrieves the auto-genera
 
 ```kotlin
 // Find by ID
-val user: User? = orm.entity(User::class).findById(userId)
+val user: User? = orm.entity<User>().findById(userId)
 
 // Find by field value using the metamodel (requires storm-metamodel-processor)
 val user: User? = orm.find { User_.email eq "alice@example.com" }

docs/getting-started.md

@@ -46,6 +46,7 @@ Once `storm init` has configured your tool, you can ask it to add the right depe
 
 For example:
 - "Add Storm to this project with Spring Boot and PostgreSQL"
+- "Set up Storm with Ktor and PostgreSQL"
 - "Create entities for the users and orders tables"
 - "Write a repository method that finds orders by status with pagination"
 

docs/index.md

@@ -221,7 +221,8 @@ If you are a tech lead or architect evaluating Storm for a production system, th
 
 1. [Storm vs Other Frameworks](comparison.md) -- feature-level comparison across frameworks
 2. [Spring Integration](spring-integration.md) -- Spring Boot auto-configuration, repository scanning, DI
-3. [Batch Processing and Streaming](batch-streaming.md) -- bulk operations and large dataset handling
+3. [Ktor Integration](ktor-integration.md) -- Ktor plugin, HOCON configuration, coroutine-native transactions
+4. [Batch Processing and Streaming](batch-streaming.md) -- bulk operations and large dataset handling
 4. [Testing](testing.md) -- JUnit 5 integration, statement capture, and test isolation
 5. [Configuration](configuration.md) -- runtime tuning, dirty checking modes, cache retention
 6. [Database Dialects](dialects.md) -- database-specific optimizations
@@ -230,7 +231,7 @@ If you are a tech lead or architect evaluating Storm for a production system, th
 
 Storm is focused on being a great ORM and SQL template engine. It intentionally does not include:
 
-- **Schema migration or DDL generation.** Storm does not create, alter, or drop tables. Use [Flyway](https://flywaydb.org/) or [Liquibase](https://www.liquibase.com/) for schema versioning and migrations.
+- **Schema migration or DDL generation.** Storm does not automatically create, alter, or drop tables at runtime. With Storm's [AI integration](/ai), your coding assistant can read your database schema and generate Flyway or Liquibase migration scripts on demand. For schema versioning, use [Flyway](https://flywaydb.org/) or [Liquibase](https://www.liquibase.com/).
 - **Second-level cache.** Storm's entity cache is transaction-scoped and cleared on commit. For cross-transaction caching, use Spring's `@Cacheable` or a dedicated cache layer like Caffeine or Redis.
 - **Lazy loading proxies.** Entities are plain records with no proxies. Related entities are loaded eagerly in a single query via JOINs. For deferred loading, use [Refs](refs.md) to explicitly control when related data is fetched.
 

docs/installation.md

@@ -193,6 +193,20 @@ implementation("st.orm:storm-kotlin-spring-boot-starter")
 </TabItem>
 </Tabs>
 
+### Ktor Integration
+
+For Ktor applications, add the Ktor plugin module. It provides a `Storm` plugin that manages the DataSource lifecycle, reads HOCON configuration, and exposes the `ORMTemplate` through extension properties on `Application`, `ApplicationCall`, and `RoutingContext`. See [Ktor Integration](ktor-integration.md) for full setup details.
+
+```kotlin
+implementation("st.orm:storm-ktor")
+```
+
+For testing:
+
+```kotlin
+testImplementation("st.orm:storm-ktor-test")
+```
+
 ### JSON Support
 
 Storm supports storing and reading JSON-typed columns. Pick the module that matches your serialization library:
@@ -214,6 +228,8 @@ storm-foundation (base interfaces)
 └── storm-kotlin / storm-java21 (your primary dependency)
     ├── storm-kotlin-spring / storm-spring (Spring Framework)
     │   └── storm-kotlin-spring-boot-starter / storm-spring-boot-starter
+    ├── storm-ktor (Ktor)
+    │   └── storm-ktor-test (testing support)
     ├── dialect modules (postgresql, mysql, mariadb, oracle, mssqlserver, sqlite, h2)
     └── JSON modules (jackson2, jackson3, kotlinx-serialization)
 ```