sirius-framework-mcp 0.1.0

package/dist/resources/biz/jobs.md

@@ -0,0 +1,145 @@
+# Jobs Framework
+
+The jobs framework provides a system for defining, parameterizing, and executing
+background tasks. Jobs are stateless factories (`JobFactory`) that produce work
+which runs either interactively (in the browser) or as batch processes on
+distributed worker nodes.
+
+## JobFactory Interface
+
+`JobFactory` is the top-level interface, annotated with `@AutoRegister` so that
+implementations are automatically discovered. In practice, always subclass
+`BasicJobFactory` which handles parameter collection, validation, and execution
+setup.
+
+```java
+@AutoRegister
+public interface JobFactory extends Named, Priorized {
+    String getLabel();
+    String getIcon();
+    String getDescription();
+    List<Parameter<?, ?>> getParameters();
+    // ...
+}
+```
+
+## Class Hierarchy — Choose the Right Base Class
+
+The hierarchy branches into two paths: interactive and batch.
+
+**Interactive jobs** run synchronously while the user waits:
+
+- `BasicJobFactory`
+  - `InteractiveJobFactory` — base for all interactive jobs
+    - `ReportJobFactory` — produces tabular HTML reports
+    - `DoughnutChartJobFactory` — renders a doughnut chart
+    - `LinearChartJobFactory` — renders a line chart
+    - `TimeseriesChartJobFactory` — renders a time-series chart
+    - `PolarAreaChartJobFactory` — renders a polar area chart
+
+**Batch jobs** run asynchronously in a distributed process:
+
+- `BasicJobFactory`
+  - `BatchProcessJobFactory` — creates a `Process` and dispatches work via `DistributedTasks`
+    - `SimpleBatchProcessJobFactory` — single `execute(ProcessContext)` method
+    - `ImportBatchProcessFactory` — file-based import workflows
+    - `ExportBatchProcessFactory` — file-based export workflows
+    - `CheckBatchProcessFactory` — data validation/checking workflows
+    - `ReportBatchProcessFactory` — long-running report generation
+
+**Key rule:** Pick the most specific base class. If your job imports data from a
+file, extend `ImportBatchProcessFactory`, not `SimpleBatchProcessJobFactory`.
+
+## Defining Parameters
+
+Override `collectParameters()` to declare the job's inputs:
+
+```java
+@Override
+protected void collectParameters(Consumer<Parameter<?, ?>> parameterCollector) {
+    parameterCollector.accept(DATE_RANGE_PARAMETER);
+    parameterCollector.accept(ACTIVE_ONLY_PARAMETER);
+}
+```
+
+Common parameter types (all in `sirius.biz.jobs.params`):
+
+| Type                   | Description                                |
+|------------------------|--------------------------------------------|
+| `StringParameter`      | Free-text input                            |
+| `BooleanParameter`     | Checkbox toggle                            |
+| `EnumParameter`        | Dropdown from a Java enum                  |
+| `EntityParameter`      | Autocomplete for a database entity         |
+| `LocalDateParameter`   | Date picker                                |
+| `DateRangeParameter`   | Date range selector                        |
+| `CodeListParameter`    | Selection from a code list                 |
+| `FileParameter`        | File upload (references Layer 2 blobs)     |
+| `IntParameter`         | Integer input                              |
+| `SelectStringParameter`| Dropdown from a fixed list of strings      |
+
+Parameters are built using a fluent API:
+
+```java
+private static final Parameter<String, StringParameter> NAME_PARAM =
+        new StringParameter("name", "$MyJob.name")
+                .withDescription("$MyJob.name.help")
+                .markRequired()
+                .build();
+```
+
+## SimpleBatchProcessJobFactory
+
+The simplest way to create a batch job. Override `execute(ProcessContext)`:
+
+```java
+@Register
+public class MyCleanupJob extends SimpleBatchProcessJobFactory {
+
+    @Override
+    protected String getLabel() { return "Cleanup old records"; }
+
+    @Override
+    protected void collectParameters(Consumer<Parameter<?, ?>> parameterCollector) {
+        parameterCollector.accept(MAX_AGE_PARAMETER);
+    }
+
+    @Override
+    protected void execute(ProcessContext process) throws Exception {
+        int maxAge = process.getParameter(MAX_AGE_PARAMETER).orElse(30);
+        // do work, use process.log() to report progress
+    }
+
+    @Override
+    public String getCategory() {
+        return StandardCategories.SYSTEM_ADMINISTRATION;
+    }
+}
+```
+
+**Important:** Override `execute(ProcessContext)`, not `executeInBackground()`.
+The process context is already set up for you.
+
+## Categories
+
+Group jobs in the UI using `StandardCategories`:
+
+- `StandardCategories.MISC` — miscellaneous
+- `StandardCategories.SYSTEM_ADMINISTRATION` — system admin tasks
+- `StandardCategories.MONITORING` — monitoring jobs
+- `StandardCategories.USERS_AND_TENANTS` — user/tenant management
+
+Or define your own category string constant (prefix with `$` for NLS lookup).
+
+## Common Mistakes
+
+1. **Storing state in the factory** — `JobFactory` is a singleton. Never store
+   per-execution state in fields. Use `ProcessContext` or a `BatchJob` subclass.
+
+2. **Wrong base class** — Using `SimpleBatchProcessJobFactory` for an import that
+   should extend `ImportBatchProcessFactory` loses file handling, progress tracking,
+   and error reporting that the more specific class provides.
+
+3. **Missing `getCategory()`** — Jobs without a category are hard to find in the UI.
+
+4. **Forgetting required permissions** — Override `getRequiredPermissions()` to
+   restrict who can run the job. Without it, any logged-in user can trigger it.

package/dist/resources/biz/processes.md

@@ -0,0 +1,155 @@
+# Processes
+
+The process framework provides a way to track, log, and monitor long-running
+background operations. Processes are stored in Elasticsearch and provide a
+real-time UI for viewing progress, logs, and outputs.
+
+## The Processes Service
+
+`Processes` is the central service, registered with framework flag `biz.processes`:
+
+```java
+@Register(classes = Processes.class, framework = Processes.FRAMEWORK_PROCESSES)
+public class Processes { ... }
+```
+
+Enable it in your configuration:
+
+```hocon
+sirius.frameworks {
+    biz.processes = true
+}
+```
+
+## Two Types of Processes
+
+### Normal Processes
+
+Created for a finite task, run to completion, then terminate:
+
+```java
+@Part
+private Processes processes;
+
+public void runExport() {
+    String processId = processes.createProcess(
+            "export",                      // type (for filtering)
+            "Export Products",             // title shown in UI
+            "fa-solid fa-download",        // icon
+            UserContext.getCurrentUser(),   // owning user
+            PersistencePeriod.THREE_MONTHS, // how long to keep
+            Map.of("format", "csv")        // context data
+    );
+
+    processes.execute(processId, process -> {
+        // process is a ProcessContext
+        process.log(ProcessLog.info().withMessage("Starting export..."));
+        // do work
+        process.addTiming("products", watchElapsed);
+        process.forceUpdateState("Exported 500 products");
+    });
+}
+```
+
+- `execute(processId, consumer)` — runs the consumer and marks the process as
+  completed (or errored) when done.
+- `partiallyExecute(processId, consumer)` — runs the consumer but leaves the
+  process open for further work (even from other nodes).
+
+### Standby Processes
+
+Long-lived processes for recurring background activity (e.g., a webhook receiver
+that logs errors):
+
+```java
+processes.executeInStandbyProcess(
+        "webhook-receiver",                         // type
+        () -> "Webhook Receiver",                   // title supplier
+        "fa-solid fa-satellite-dish",               // icon
+        () -> "Processing incoming webhooks...",     // state supplier
+        process -> {
+            // This runs each time the standby process is invoked
+            process.log(ProcessLog.warn().withMessage("Received invalid payload"));
+        }
+);
+```
+
+Standby processes are created on demand and reused. The system periodically cleans
+up old log entries to prevent unbounded growth.
+
+## ProcessContext — The Client API
+
+Inside `execute()` or `partiallyExecute()`, you interact with a `ProcessContext`:
+
+| Method                            | Description                                  |
+|-----------------------------------|----------------------------------------------|
+| `log(ProcessLog)`                 | Writes a log entry (info, warn, error)       |
+| `addTiming(counter, millis)`      | Increments a named performance counter       |
+| `addDebugTiming(counter, millis)` | Counter visible only when debugging enabled  |
+| `incCounter(counter)`             | Increment a counter by one                   |
+| `forceUpdateState(text)`          | Updates the process state text immediately   |
+| `updateTitle(text)`               | Changes the process title                    |
+| `addOutput(ProcessOutput)`        | Adds a structured output (table, chart)      |
+| `getProcessId()`                  | Returns the process ID                       |
+| `isActive()`                      | Returns false if the process was cancelled    |
+
+### Structured Outputs
+
+Processes can produce tables and charts, not just log lines:
+
+```java
+TableOutput table = process.addTable("results", "Results", columns);
+table.addRow("product-1", "Widget", "42");
+
+ChartOutput chart = process.addChart("timeline", "Timeline");
+```
+
+## Process Entity
+
+`Process` is an Elasticsearch entity gated by `@Framework(Processes.FRAMEWORK_PROCESSES)`.
+It stores:
+- Process metadata (type, title, icon, user, tenant)
+- State (RUNNING, STANDBY, TERMINATED, CANCELED, ERRORED)
+- Counters and timings
+- Context map (arbitrary key-value pairs)
+- Persistence period (how long to retain)
+
+`ProcessLog` is a separate Elasticsearch entity for individual log entries,
+also gated by `@Framework(Processes.FRAMEWORK_PROCESSES)`.
+
+## Layered Cache Architecture
+
+Because Elasticsearch has a ~1-second write-visibility delay, `Processes` uses a
+two-level cache:
+
+1. **First-level cache** — very short-lived, for direct modifications on the same node.
+2. **Second-level cache** — coherent cache for reading "static" process data
+   (context, user, title) across nodes.
+
+Standby processes have their own coherent cache since they are long-lived and few
+in number.
+
+## PersistencePeriod
+
+Controls how long a completed process is retained before automatic cleanup:
+
+- `PersistencePeriod.ONE_DAY`
+- `PersistencePeriod.TWO_WEEKS`
+- `PersistencePeriod.THREE_MONTHS`
+- `PersistencePeriod.SIX_MONTHS`
+- `PersistencePeriod.ONE_YEAR`
+- `PersistencePeriod.FOREVER`
+
+## Common Mistakes
+
+1. **Using `execute()` when `partiallyExecute()` is needed** — If multiple nodes
+   or tasks contribute to one process, `execute()` will prematurely mark it as done.
+
+2. **Logging too much** — Every `ProcessLog` is an Elasticsearch document.
+   Use `addTiming()` for high-frequency counters instead of logging each item.
+
+3. **Ignoring `isActive()`** — Always check `process.isActive()` in long loops.
+   If the user cancels, you should stop promptly.
+
+4. **Forgetting the framework flag** — Without `biz.processes = true` in the
+   config, the `Processes` service will not load and `@Part Processes` will be null.

package/dist/resources/biz/storage.md

@@ -0,0 +1,149 @@
+# Storage
+
+The storage module provides a three-layer architecture for managing files and
+binary content. Each layer serves a different purpose and can be configured
+independently.
+
+## Layer 1 — Physical Storage
+
+Layer 1 handles the raw byte storage. It abstracts over different storage backends:
+
+- **`FSObjectStorageSpace`** — local filesystem storage (development, small deployments)
+- **`S3ObjectStorageSpace`** — S3-compatible object storage (production)
+
+Configuration is done per "space" in HOCON:
+
+```hocon
+storage.layer1 {
+    spaces {
+        default {
+            engine = "fs"
+            basePath = "/data/storage"
+        }
+        documents {
+            engine = "s3"
+            bucketName = "my-bucket"
+        }
+    }
+}
+```
+
+Key classes:
+- `ObjectStorage` — service for accessing storage spaces
+- `ObjectStorageSpace` — a configured storage area
+- `FileHandle` — represents a downloaded file with metadata
+
+## Layer 2 — Metadata and Blobs
+
+Layer 2 adds metadata, versioning, and variant management on top of Layer 1.
+This is the primary API for working with files in application code.
+
+### Core Concepts
+
+- **`BlobStorageSpace`** — a logical container for blobs (configured per space)
+- **`Blob`** — a file with metadata (name, size, content type, tenant, etc.)
+- **`BlobContainer`** — groups related blobs (e.g., attachments for an entity)
+- **`Directory`** — optional directory structure within a space
+
+### JDBC vs MongoDB
+
+Layer 2 metadata can be stored in either database:
+
+| Component       | JDBC                    | MongoDB                  |
+|-----------------|-------------------------|--------------------------|
+| Storage class   | `SQLBlobStorage`        | `MongoBlobStorage`       |
+| Blob entity     | `SQLBlob`               | `MongoBlob`              |
+| Directory       | `SQLDirectory`          | `MongoDirectory`         |
+| Framework flag  | `biz.storage-blob-jdbc` | `biz.storage-blob-mongo` |
+
+### Referencing Blobs from Entities
+
+Use `BlobHardRef` or `BlobSoftRef` in entity fields:
+
+```java
+// Hard ref — blob is deleted when the entity is deleted
+private final BlobHardRef logo =
+        new BlobHardRef(this, "logo", "tenant-logos");
+
+// Soft ref — blob survives entity deletion
+private final BlobSoftRef attachment =
+        new BlobSoftRef(this, "attachment", "documents");
+```
+
+### Working with Blobs
+
+```java
+@Part
+private BlobStorage blobStorage;
+
+// Upload
+BlobStorageSpace space = blobStorage.getSpace("documents");
+Blob blob = space.createBlob("report.pdf", "application/pdf", tenantId);
+try (OutputStream out = blob.createOutputStream()) {
+    // write content
+}
+
+// Download
+try (InputStream in = blob.createInputStream()) {
+    // read content
+}
+```
+
+## Layer 3 — Virtual File System (VFS)
+
+Layer 3 provides a unified directory/file tree view over Layer 2 spaces and other
+sources. It powers the file manager UI and FTP/WebDAV access.
+
+### VirtualFile
+
+`VirtualFile` is the abstraction for both files and directories:
+
+```java
+@Part
+private VirtualFileSystem vfs;
+
+VirtualFile root = vfs.root();
+VirtualFile docs = root.resolve("documents");
+for (VirtualFile child : docs.children()) {
+    if (child.isDirectory()) {
+        // traverse
+    } else {
+        // access file content via child.createInputStream()
+    }
+}
+```
+
+### VFS Roots
+
+The VFS tree is assembled from `VFSRoot` implementations. Each root contributes
+a subtree (e.g., one root for tenant documents, another for shared templates).
+Custom roots are registered via `@Register(classes = VFSRoot.class)`.
+
+## Framework Flags
+
+Storage requires multiple framework flags depending on which layers and backends
+you use:
+
+```hocon
+sirius.frameworks {
+    biz.storage = true             # Core storage (required)
+    biz.storage-blob-jdbc = true   # Layer 2 metadata in JDBC
+    biz.storage-blob-mongo = false # Layer 2 metadata in MongoDB
+    biz.storage-replication-jdbc = false   # Replication tasks in JDBC
+    biz.storage-replication-mongo = false  # Replication tasks in MongoDB
+}
+```
+
+## Common Mistakes
+
+1. **Wrong ref type** — Using `BlobHardRef` when the blob should outlive the entity
+   (e.g., shared documents). Use `BlobSoftRef` if the blob has independent lifecycle.
+
+2. **Missing framework flags** — `biz.storage` alone is not enough. You also need
+   `biz.storage-blob-jdbc` or `biz.storage-blob-mongo` for Layer 2 to work.
+
+3. **Not closing streams** — Always close `InputStream` and `OutputStream` from blob
+   operations. Unclosed streams leak file handles and may corrupt uploads.
+
+4. **Ignoring variants** — Layer 2 supports automatic variant generation (e.g.,
+   thumbnails). Configure variants per space rather than generating them manually.

package/dist/resources/biz/tenants.md

@@ -0,0 +1,159 @@
+# Tenants
+
+The tenants module provides multi-tenant user management. Every piece of business
+data belongs to a tenant, and every user belongs to a tenant. The framework enforces
+tenant isolation automatically.
+
+## Core Interfaces
+
+### Tenant<I>
+
+The database-independent interface for a tenant (company/organization):
+
+```java
+public interface Tenant<I extends Serializable>
+        extends Entity, Transformable, Traced, Journaled, RateLimitedEntity, PerformanceFlagged {
+
+    Mapping TENANT_DATA = Mapping.named("tenantData");
+    TenantData getTenantData();
+    boolean hasPermission(String permission);
+    Set<String> getPermissions();
+}
+```
+
+### UserAccount<I, T>
+
+The database-independent interface for a user account within a tenant:
+
+```java
+public interface UserAccount<I extends Serializable, T extends Tenant<I>>
+        extends Entity, Transformable, Traced, Journaled {
+
+    Mapping USER_ACCOUNT_DATA = Mapping.named("userAccountData");
+    UserAccountData getUserAccountData();
+    BaseEntityRef<I, T> getTenant();
+}
+```
+
+## TenantData and UserAccountData
+
+All tenant fields live in the `TenantData` composite, shared between SQL and Mongo
+implementations. Similarly, user fields live in `UserAccountData`. This avoids
+field duplication across implementations.
+
+Key fields in `TenantData`:
+- `name` — display name of the tenant
+- `accountNumber` — unique business identifier
+- `address` — embedded `InternationalAddressData` composite
+- `packageData` — permissions/features assigned to this tenant
+
+Key fields in `UserAccountData`:
+- `person` — embedded `PersonData` composite (name, salutation, email)
+- `login` — embedded `LoginData` composite (username, password hash)
+- `permissions` — assigned permissions/roles
+
+## JDBC and MongoDB Implementations
+
+| Interface        | JDBC Implementation    | Mongo Implementation     |
+|------------------|------------------------|--------------------------|
+| `Tenant<I>`      | `SQLTenant`            | `MongoTenant`            |
+| `UserAccount`    | `SQLUserAccount`       | `MongoUserAccount`       |
+
+These follow the entity triple pattern (see entity-triple resource). Both are
+gated behind framework flags:
+- `biz.tenants-jdbc` for SQL implementations
+- `biz.tenants-mongo` for MongoDB implementations
+
+## Tenant-Aware Entities
+
+Entities that belong to a tenant extend `SQLTenantAware` or `MongoTenantAware`:
+
+```java
+public class SQLProduct extends SQLTenantAware {
+    // Automatically gets a tenant reference field
+    // Tenant is auto-filled on create via fillWithCurrentTenant()
+}
+```
+
+`SQLTenantAware` extends `BizEntity` and adds:
+- A `tenant` field (`SQLEntityRef<SQLTenant>`) — write-once, reject-on-delete
+- `fillWithCurrentTenant()` — fills the tenant from the current session
+- `assertSameTenant()` — validates that a referenced entity belongs to the same tenant
+
+The Mongo equivalent (`MongoTenantAware`) works identically with `MongoRef`.
+
+## Tenants Service
+
+The `Tenants<I, T, U>` service provides tenant operations:
+
+```java
+@Part
+private Tenants<?, ?, ?> tenants;
+
+// Get current tenant
+Tenant<?> currentTenant = tenants.getRequiredTenant();
+
+// Check if current user is in the system tenant
+boolean isSystem = tenants.isCurrentTenantSystemTenant();
+
+// Filter a query to the current tenant
+SmartQuery<SQLProduct> query = tenants.forCurrentTenant(oma.select(SQLProduct.class));
+```
+
+Concrete implementations: `SQLTenants` (JDBC) and `MongoTenants` (MongoDB).
+
+## TenantUserManager
+
+`TenantUserManager` is the `UserManager` implementation for the tenants module.
+It bridges the web security framework with the tenant/user database:
+
+- Authenticates users via login credentials
+- Resolves permissions from user roles + tenant package
+- Provides session management
+- Supports "spy" mode (system tenant admins can act as another tenant)
+
+Key permissions:
+- `TenantUserManager.PERMISSION_SYSTEM_TENANT_MEMBER` — user belongs to the system tenant
+- `TenantUserManager.PERMISSION_SYSTEM_ADMINISTRATOR` — user is a system admin
+- `Tenant.PERMISSION_SYSTEM_TENANT` — flag on the tenant entity itself
+
+## Permission Model
+
+Permissions flow from multiple sources:
+
+1. **Tenant package** — `PackageData` on the tenant defines which features are enabled
+2. **User roles** — roles assigned to the user, each granting a set of permissions
+3. **Role mapping** — configured in HOCON, maps role names to permission sets
+4. **System tenant flag** — system tenant users get additional administrative permissions
+
+```hocon
+security.tenantPermissions {
+    admin = ["permission-manage-users", "permission-manage-products"]
+    viewer = ["permission-view-products"]
+}
+```
+
+## System Tenant
+
+One tenant is designated as the "system tenant" (configured by ID). Users in the
+system tenant can:
+- Manage all other tenants
+- "Spy" on other tenants (act as if they belong to another tenant)
+- Access system administration features
+
+The system tenant flag is checked via `Tenant.hasPermission(Tenant.PERMISSION_SYSTEM_TENANT)`.
+
+## Common Mistakes
+
+1. **Not using `findForTenant()`** — Using `find()` in controllers allows access
+   to entities from other tenants. Always use `findForTenant()` for tenant-scoped data.
+
+2. **Forgetting to enable the framework** — Without `biz.tenants-jdbc = true` or
+   `biz.tenants-mongo = true`, tenant entities are not registered.
+
+3. **Manual tenant assignment** — Do not set the tenant reference manually.
+   `SQLTenantAware.fillWithCurrentTenant()` is called automatically during entity
+   creation. Manual assignment can cause tenant mismatch errors.
+
+4. **Confusing tenant permissions with user permissions** — `Tenant.hasPermission()`
+   checks tenant-level features. User permissions are checked via `UserInfo.hasPermission()`.