sirius-framework-mcp 0.1.0

package/dist/resources/biz/testing.md

@@ -0,0 +1,127 @@
+# Testing
+
+Tests in sirius-biz are written in Kotlin using JUnit 5 with the `SiriusExtension`.
+This extension boots the full Sirius framework (DI, databases, config) before tests
+run, giving you access to real services and database connections.
+
+## Test Structure
+
+- **Test files:** `src/test/kotlin/sirius/biz/**/*Test.kt` (Kotlin)
+- **Test entities:** `src/test/java/sirius/biz/**/*.java` (Java, for test-only entities)
+- **Test config:** `src/test/resources/test.conf`
+- **Test suite:** `TestSuite.java` using `ScenarioSuite`
+
+## SiriusExtension and DI
+
+Every test class must use `@ExtendWith(SiriusExtension::class)`. This boots the
+Sirius framework once per test run (shared across all test classes).
+
+Use `@Part` in a `companion object` with `@JvmStatic` to inject services.
+Always wait for database readiness in `@BeforeAll`:
+
+```kotlin
+@BeforeAll
+@JvmStatic
+fun setup() {
+    oma.readyFuture.await(Duration.ofSeconds(60))
+}
+```
+
+**Important:** `@Part` fields must be in the `companion object` (static), not on
+the test instance. Sirius DI only injects static fields.
+
+## Test Naming
+
+Use Kotlin backtick syntax for descriptive test names. This produces readable test
+output while being valid Kotlin method names.
+
+## Complete Example
+
+```kotlin
+@ExtendWith(SiriusExtension::class)
+class TenantsTest {
+
+    companion object {
+        @Part
+        @JvmStatic
+        private lateinit var oma: OMA
+
+        @BeforeAll
+        @JvmStatic
+        fun setup() {
+            oma.readyFuture.await(Duration.ofSeconds(60))
+        }
+    }
+
+    @Test
+    fun `installTestTenant works`() {
+        TenantsHelper.installTestTenant()
+        assertTrue {
+            UserContext.get().getUser().hasPermission(UserInfo.PERMISSION_LOGGED_IN)
+        }
+    }
+}
+```
+
+## Test Entities
+
+Test-only entities live in `src/test/java/` (not `src/main/java/`). They are
+written in Java (not Kotlin) because the Mixing ORM annotation processor requires
+Java source files:
+
+```java
+// src/test/java/sirius/biz/mymodule/TestProduct.java
+@Framework("test")
+public class TestProduct extends BizEntity {
+    @Autoloaded
+    @Length(100)
+    private String name;
+
+    // getters and setters
+}
+```
+
+Enable the test framework in `test.conf`:
+
+```hocon
+sirius.frameworks {
+    test = true
+}
+```
+
+## Test Configuration
+
+`src/test/resources/test.conf` enables the frameworks needed for testing:
+
+```hocon
+sirius.frameworks {
+    biz.tenants = true
+    biz.tenants-jdbc = true
+    biz.storage = true
+    biz.storage-blob-jdbc = true
+    biz.isenguard = true
+    biz.processes = true
+    biz.locks = true
+}
+```
+
+Docker services (MariaDB, MongoDB, Elasticsearch, Redis) must be running for
+integration tests. Use `docker-compose up -d` in the project root.
+
+## Common Mistakes
+
+1. **`@Part` on instance fields** — DI injection only works on static fields.
+   Place `@Part` fields in the `companion object` with `@JvmStatic`.
+
+2. **Missing `@BeforeAll` database wait** — Tests that run before the schema is
+   ready will fail intermittently. Always await `oma.readyFuture`.
+
+3. **Test entities in Kotlin** — The Mixing ORM requires Java source files for
+   entity classes. Test entities must be `.java` files even though tests are Kotlin.
+
+4. **Not cleaning up test data** — Tests share the same database. Create unique
+   test data (e.g., with random suffixes) or clean up in `@AfterEach` to avoid
+   interference between tests.
+
+5. **Forgetting `@JvmStatic`** — Without `@JvmStatic` on companion object fields,
+   Sirius DI cannot find and populate the fields.

package/dist/resources/db/composites.md

@@ -0,0 +1,145 @@
+# Composites
+
+A `Composite` is a reusable group of fields that can be embedded into any entity
+or other composite. It lives in `sirius.db.mixing.Composite` and extends `Mixable`,
+meaning it can itself be extended via mixins.
+
+## How Composites Work
+
+When a composite is declared as a field in an entity, all of the composite's fields
+become properties of the entity. The field name of the composite is **prepended**
+to each property name, separated by `_`:
+
+```java
+public class Customer extends SQLTenantAware {
+    private final PersonData person = new PersonData();
+    // Creates columns: person_title, person_firstname, person_lastname, etc.
+}
+```
+
+This prefixing means the same composite class can appear multiple times in one entity
+under different field names without column conflicts:
+
+```java
+public class Order extends SQLTenantAware {
+    private final AddressData billingAddress = new AddressData();
+    private final AddressData shippingAddress = new AddressData();
+    // billingAddress_street, billingAddress_city, ...
+    // shippingAddress_street, shippingAddress_city, ...
+}
+```
+
+## Mapping Constants
+
+Every composite field should declare a `Mapping` constant to enable type-safe
+references in queries and templates:
+
+```java
+public class PersonData extends Composite {
+
+    public static final Mapping FIRSTNAME = Mapping.named("firstname");
+    @Length(150)
+    @Trim
+    @Autoloaded
+    @NullAllowed
+    @AutoImport
+    private String firstname;
+
+    public static final Mapping LASTNAME = Mapping.named("lastname");
+    @Length(150)
+    @Trim
+    @Autoloaded
+    @NullAllowed
+    @AutoImport
+    private String lastname;
+
+    // getters/setters...
+}
+```
+
+## Accessing Nested Fields with Mapping.inner()
+
+When querying or referencing a composite field from the entity level, use
+`Mapping.inner()` to build the prefixed path:
+
+```java
+// In a query on the Customer entity:
+oma.select(Customer.class)
+   .eq(Customer.PERSON.inner(PersonData.LASTNAME), "Smith")
+   .queryList();
+```
+
+This resolves to the column `person_lastname` in the database.
+
+## Standard Annotations
+
+These annotations can be placed on fields in composites (and entities):
+
+- `@Length(n)` — Maximum column/field length (required for strings).
+- `@Trim` — Automatically trims whitespace on load/save.
+- `@NullAllowed` — Permits null values. Without this, nulls cause validation errors.
+- `@Unique` — Enforces uniqueness. Supports `within` parameter for scoped uniqueness.
+- `@Transient` — Excludes the field from persistence entirely.
+- `@Autoloaded` — Auto-populates the field from web request parameters.
+- `@AutoImport` — Auto-populates the field during data import.
+
+## Lifecycle Annotations
+
+These method-level annotations on the containing entity (or composite) hook into
+the persistence lifecycle:
+
+- `@BeforeSave` — Called before the entity is written to the database. Use for
+  computed fields, normalization, or throwing exceptions to abort the save.
+- `@OnValidate` — Called during validation. The annotated method receives a
+  `Consumer<String>` to collect warning messages without aborting.
+- `@ValidatedBy(ValidatorClass.class)` — Delegates field validation to an external
+  validator class.
+
+```java
+public class InvoiceData extends Composite {
+
+    public static final Mapping INVOICE_NUMBER = Mapping.named("invoiceNumber");
+    @Length(50)
+    @NullAllowed
+    private String invoiceNumber;
+
+    @BeforeSave
+    protected void generateInvoiceNumber() {
+        if (Strings.isEmpty(invoiceNumber)) {
+            invoiceNumber = sequences.generateId("invoices");
+        }
+    }
+
+    @OnValidate
+    protected void validate(Consumer<String> validationConsumer) {
+        if (Strings.isEmpty(invoiceNumber)) {
+            validationConsumer.accept("Invoice number is required.");
+        }
+    }
+}
+```
+
+## PersonData — Standard Example
+
+`PersonData` in `sirius.biz.model` is the canonical composite example. It stores
+title, salutation, firstname, and lastname. It provides helper methods like
+`getAddressableName()` and `getShortName()`, and validation helpers
+(`verifySalutation()`, `validateSalutation()`) that the containing entity can
+call from its own `@BeforeSave` or `@OnValidate` methods.
+
+## Common Mistakes
+
+1. **Forgetting the prefix in queries** — A field `firstname` inside a composite
+   field `person` becomes `person_firstname` in the database. Always use
+   `Mapping.inner()` to construct the correct path.
+
+2. **Not declaring Mapping constants** — Without `Mapping.named()` constants,
+   queries require raw strings, which are error-prone and not refactoring-safe.
+
+3. **Mutable composite instances** — Composite fields should be declared `final`
+   in the entity. The composite object is created once and its internal fields are
+   mutated, but the composite reference itself should not change.
+
+4. **Missing @NullAllowed** — String fields default to non-null. If a field
+   legitimately can be empty, annotate it with `@NullAllowed` or provide a
+   `@DefaultValue`.

package/dist/resources/db/entities.md

@@ -0,0 +1,156 @@
+# Entities
+
+Sirius-db provides three entity base classes, one per supported database. All share
+a common ancestor: `BaseEntity<I>` (in `sirius.db.mixing`), which extends `Mixable`
+and implements `Entity`. The type parameter `I` is the ID type.
+
+## SQLEntity — JDBC / SQL Databases
+
+`SQLEntity` uses `Long` IDs auto-generated by the database. It supports optimistic
+locking via a `version` field that is automatically incremented on each update.
+
+```java
+public abstract class SQLEntity extends BaseEntity<Long> {
+    // id: long, auto-assigned by the database
+    // version: int, used for optimistic locking
+}
+```
+
+An entity is considered new (not yet persisted) when `id < 0`. The sentinel value
+is `SQLEntity.NON_PERSISTENT_ENTITY_ID` (-1).
+
+**Mapper:** `OMA` (Object Mapper for rdbms Access)
+
+## MongoEntity — MongoDB
+
+`MongoEntity` uses `String` IDs generated by `KeyGenerator` -- NOT MongoDB's native
+ObjectId. This produces short, URL-safe string identifiers. Optimistic locking is
+supported via a `version` field.
+
+```java
+@Index(name = "id", columns = "id", columnSettings = Mango.INDEX_ASCENDING, unique = true)
+public abstract class MongoEntity extends BaseEntity<String> {
+    // id: String, generated by KeyGenerator before insert
+    // version: int, used for optimistic locking
+}
+```
+
+An entity is new when `id == null`. The ID is generated in `generateId()` during
+the create operation, after before-save checks have executed.
+
+**Mapper:** `Mango`
+
+## ElasticEntity — Elasticsearch
+
+`ElasticEntity` uses `String` IDs auto-generated by Elasticsearch. It uses
+`primaryTerm` and `seqNo` for optimistic concurrency control instead of a simple
+version counter.
+
+```java
+public abstract class ElasticEntity extends BaseEntity<String> {
+    // id: String, auto-generated by Elasticsearch
+    // primaryTerm, seqNo: used for optimistic concurrency
+}
+```
+
+For performance, annotate a field with `@RoutedBy` to enable custom routing:
+
+```java
+@RoutedBy(tenantRef)
+public class EventLog extends ElasticEntity { ... }
+```
+
+**Mapper:** `Elastic`
+
+## Hierarchy in sirius-biz
+
+sirius-biz extends these base classes to add tracing, journaling, and tenant
+awareness. The full hierarchies are:
+
+**SQL path:**
+```
+BaseEntity<Long>
+  +-- SQLEntity
+        +-- BizEntity                  (adds TraceData)
+              +-- SQLTenantAware       (adds tenant reference)
+```
+
+**MongoDB path:**
+```
+BaseEntity<String>
+  +-- MongoEntity
+        +-- PrefixSearchableEntity     (adds search prefix support)
+              +-- MongoBizEntity       (adds TraceData)
+                    +-- MongoTenantAware   (adds tenant reference)
+```
+
+When creating a tenant-aware entity, extend `SQLTenantAware` or `MongoTenantAware`.
+When creating a non-tenant entity with tracing, extend `BizEntity` or `MongoBizEntity`.
+
+## Entity Registration
+
+Entities are discovered automatically at startup. Use `@Framework` to gate an entity
+behind a framework flag:
+
+```java
+@Framework("biz.tenants-jdbc")
+public class SQLTenant extends SQLTenantAware implements Tenant<Long> { ... }
+```
+
+The entity will only be registered (and its table/collection created) when the
+framework flag `biz.tenants-jdbc` is enabled in the config.
+
+## Concrete SQL Example
+
+```java
+@Framework("myapp.products")
+public class Product extends SQLTenantAware {
+
+    public static final Mapping NAME = Mapping.named("name");
+    @Length(255)
+    @Trim
+    @Autoloaded
+    private String name;
+
+    public static final Mapping PRICE = Mapping.named("price");
+    @Autoloaded
+    private int price;
+
+    // getters/setters...
+}
+```
+
+## Concrete Mongo Example
+
+```java
+@Framework("myapp.products")
+public class MongoProduct extends MongoTenantAware {
+
+    public static final Mapping NAME = Mapping.named("name");
+    @Length(255)
+    @Trim
+    @Autoloaded
+    private String name;
+
+    // getters/setters...
+}
+```
+
+## Common Mistakes
+
+1. **Using MongoDB ObjectId** — MongoEntity does NOT use ObjectId. IDs are generated
+   as strings by `KeyGenerator`. Do not try to parse them as ObjectId.
+
+2. **Setting the SQL ID manually** — The `id` field is managed by the database.
+   Never assign a value to `setId()` unless you are doing a low-level data migration.
+
+3. **Forgetting @Framework** — Without a framework annotation, the entity is always
+   registered. This can cause table creation in databases where it is not wanted.
+
+4. **Extending concrete entity classes** — Superclasses of entities should always
+   be `abstract`. The framework does not support merging distinct subclasses into
+   one table.
+
+5. **Ignoring optimistic locking** — If a concurrent update causes a version
+   mismatch, an `OptimisticLockException` is thrown. Catch and handle it
+   (e.g., reload and retry) rather than letting it propagate as a 500 error.

package/dist/resources/db/mixing.md

@@ -0,0 +1,176 @@
+# Mixing ORM
+
+Mixing is the core ORM (Object-Relational/Document Mapping) layer in sirius-db.
+It provides a unified abstraction over SQL, MongoDB, and Elasticsearch, handling
+entity discovery, schema management, property mapping, and validation.
+
+## Overview
+
+The Mixing system consists of three main components:
+
+1. **`Mixing`** — The central registry. Discovers all entity classes at startup,
+   creates their descriptors, and provides lookup by class or name.
+2. **`EntityDescriptor`** — Describes a single entity type: its properties,
+   lifecycle handlers, relation name, and validation rules.
+3. **`Property`** — Maps a single Java field to a database column/field. Handles
+   type conversion, validation, and access.
+
+## Mixing — The Registry
+
+`Mixing` is a singleton (`@Register`) that initializes at startup by:
+
+1. Scanning for all `BaseEntity` subclasses (via `EntityLoadAction`)
+2. Creating an `EntityDescriptor` for each
+3. Linking cross-references between descriptors
+4. Optionally executing schema updates
+
+Inject it with `@Part`:
+
+```java
+@Part
+private Mixing mixing;
+```
+
+Key methods:
+- `mixing.getDescriptor(Class)` — returns the descriptor for an entity class
+- `mixing.getDescriptor(String)` — returns the descriptor by type name
+  (upper-cased simple class name, e.g., `"PRODUCT"`)
+- `mixing.findDescriptor(Class)` — returns Optional (no exception if missing)
+- `mixing.getDescriptors()` — returns all known descriptors
+
+## EntityDescriptor
+
+Each entity class has exactly one `EntityDescriptor`. It holds:
+
+- **Properties** — the list of `Property` objects for each mapped field
+- **Relation name** — the table/collection/index name in the database
+- **Realm** — which database instance to use (via `@Realm` annotation)
+- **Lifecycle handlers** — methods annotated with `@BeforeSave`, `@AfterSave`,
+  `@BeforeDelete`, `@AfterDelete`, `@OnValidate`
+- **Version flag** — whether optimistic locking is enabled (`@Versioned`)
+
+```java
+EntityDescriptor descriptor = mixing.getDescriptor(Product.class);
+descriptor.getRelationName();    // e.g., "product"
+descriptor.getRealm();           // e.g., "mixing" (default)
+descriptor.getProperties();      // all Property objects
+descriptor.isVersioned();        // true if @Versioned
+```
+
+Change detection is built into the descriptor:
+
+```java
+descriptor.isChanged(entity, property);  // checks if a field was modified
+entity.isChanged(Product.NAME);          // convenience on the entity itself
+entity.isAnyMappingChanged();            // any field changed at all
+```
+
+## Property Abstraction
+
+A `Property` bridges a Java field and its database representation:
+
+- `getName()` — the effective property name (prefixed for composites/mixins)
+- `getPropertyName()` — the column/field name in the database
+- `getValue(entity)` — reads the current value from the entity
+- `setValue(entity, value)` — writes a value to the entity
+- `getValueForDatasource(mapperClass, entity)` — converts the value for storage
+- `parseValue(entity, Value)` — converts a raw value back into the Java type
+
+Properties are created by `PropertyFactory` implementations. Each Java type
+(String, int, LocalDateTime, EntityRef, Composite, etc.) has a corresponding
+property factory that knows how to map it.
+
+## Entity Discovery and @Framework
+
+Entities are discovered by scanning for all concrete subclasses of `BaseEntity`.
+To conditionally include an entity, use `@Framework`:
+
+```java
+@Framework("myapp.products")
+public class Product extends SQLTenantAware { ... }
+```
+
+If the framework flag `myapp.products` is not enabled in `sirius.frameworks`,
+the entity class is not loaded, its table is not created, and its descriptor
+does not exist in the `Mixing` registry.
+
+## Mapper Hierarchy
+
+Each database backend has its own mapper that extends `BaseMapper`:
+
+| Mapper | Entity Base | Query Type | ID Type |
+|--------|-------------|------------|---------|
+| `OMA` | `SQLEntity` | `SmartQuery` | `Long` |
+| `Mango` | `MongoEntity` | `MongoQuery` | `String` |
+| `Elastic` | `ElasticEntity` | `ElasticQuery` | `String` |
+
+All mappers provide the same core operations: `find()`, `select()`, `update()`,
+`delete()`, `tryUpdate()`, `tryDelete()`.
+
+## Descriptor-Based Validation
+
+Validation runs automatically before save via the descriptor. Sources of
+validation rules include:
+
+- **@Length** — property length check
+- **@NullAllowed** — null check (fields are non-null by default)
+- **@Unique** — uniqueness check via database query
+- **@OnValidate** — custom validation methods on the entity or composite
+- **@ValidatedBy** — external validator class
+- **@BeforeSave** — pre-save hooks that can throw to abort
+
+```java
+@OnValidate
+protected void validate(Consumer<String> validationConsumer) {
+    if (Strings.isEmpty(getName())) {
+        validationConsumer.accept("Name is required.");
+    }
+}
+```
+
+Validation messages collected by `@OnValidate` are warnings. To hard-fail,
+throw an exception in a `@BeforeSave` handler instead.
+
+## Schema Synchronization
+
+Mixing can automatically update database schemas at startup. The behavior is
+controlled by `mixing.autoUpdateSchema` in the config:
+
+- `"safe"` — executes non-destructive changes (add columns, create tables)
+- `"all"` — executes all changes including potentially destructive ones
+- `"off"` — no automatic schema changes
+
+## Mixins
+
+Mixins add fields to existing entities without modifying them. A mixin targets
+a specific entity type via `@Mixin`:
+
+```java
+@Mixin(Product.class)
+public class ProductExtension extends Mixable {
+    public static final Mapping EXTERNAL_ID = Mapping.named("externalId");
+    @Length(100) @NullAllowed
+    private String externalId;
+}
+```
+
+This adds an `externalId` column to the `Product` table. Useful for extending
+framework-provided entities from application code.
+
+## Common Mistakes
+
+1. **Querying before Mixing is ready** — At startup, `Mixing.initialize()` must
+   complete before any database operations. In tests, await `oma.readyFuture`
+   or `mango.readyFuture`.
+
+2. **Using getDescriptor() for unregistered classes** — If the entity's framework
+   flag is disabled, `getDescriptor()` throws. Use `findDescriptor()` when the
+   entity may not exist.
+
+3. **Confusing property name and field name** — A composite field `person` with
+   a sub-field `firstname` produces property name `person_firstname`. The Java
+   field name is just `firstname`.
+
+4. **Ignoring the realm** — Entities default to the `"mixing"` realm. If your
+   application uses multiple databases, annotate entities with `@Realm("other")`
+   to direct them to the correct database.