sirius-framework-mcp 0.1.0

package/dist/resources/kernel/commons.md

@@ -0,0 +1,203 @@
+# Commons Utilities
+
+Sirius-kernel provides a set of utility classes in `sirius.kernel.commons` for
+everyday programming tasks: internationalization, string handling, type-safe
+value wrapping, and decimal arithmetic.
+
+## NLS — Internationalization
+
+`NLS` (Native Language Support) is the central class for i18n. Translations
+are stored in `.properties` files and accessed via keys.
+
+### Simple Lookup
+
+```java
+// Looks up key "MyEntity.name" in the current language
+String label = NLS.get("MyEntity.name");
+```
+
+### Formatted Messages
+
+`NLS.fmtr()` provides named-parameter formatting:
+
+```java
+// Given property: "welcome = Welcome, {{name}}! You have {{count}} items."
+String msg = NLS.fmtr("welcome")
+    .set("name", userName)
+    .set("count", itemCount)
+    .format();
+```
+
+The `{{param}}` syntax is Sirius-specific — it uses named parameters rather
+than positional ones, making translations much easier to maintain.
+
+### Smart Formatting
+
+`NLS.toUserString(Object)` converts any value to a locale-appropriate string:
+- Numbers are formatted with locale-specific grouping and decimals.
+- Dates/times use the locale's standard format.
+- `Amount` values respect precision and locale.
+
+### Property Files
+
+Translation files follow the pattern `basename_lang.properties`:
+- `biz_en.properties` — English
+- `biz_de.properties` — German
+
+They are loaded from the classpath under `resources/`.
+
+## Strings
+
+`Strings` provides null-safe string operations:
+
+```java
+// Null-safe emptiness checks
+Strings.isEmpty(null);     // true
+Strings.isEmpty("");       // true
+Strings.isEmpty("  ");    // true (trims first)
+Strings.isFilled(value);  // opposite of isEmpty
+
+// Null-safe equality
+Strings.areEqual(a, b);           // null == null is true
+Strings.equalIgnoreCase(a, b);
+
+// Join with separator, skipping empty values
+Strings.join(", ", firstName, lastName);  // Skips nulls/empty
+
+// Apply a string operation only if filled
+Strings.apply("%s (%s)", name, code);  // Returns "" if name is empty
+```
+
+### Strings.join
+
+A commonly used pattern for building display strings:
+
+```java
+// Produces "John, Doe" — skips empty parts
+String fullName = Strings.join(" ", title, firstName, lastName);
+```
+
+## Value
+
+`Value` is a type-safe wrapper around an arbitrary object, providing fluent
+conversion and null-safe access:
+
+```java
+Value val = Value.of(someObject);
+
+// Type conversions with defaults
+String s   = val.asString();           // "" if null
+int n      = val.asInt(0);             // 0 if not convertible
+boolean b  = val.asBoolean();          // false if null
+LocalDate d = val.asLocalDate(fallback);
+
+// Check state
+val.isNull();
+val.isFilled();
+val.isEmpty();
+
+// Conditional execution
+val.ifFilled(v -> process(v));
+```
+
+`Value` is used extensively in the web layer for request parameters and in the
+import framework for cell values.
+
+## Amount
+
+`Amount` provides precise decimal arithmetic, replacing `BigDecimal` with a
+more ergonomic API. It is the standard type for monetary values and quantities.
+
+```java
+Amount price = Amount.of(19.99);
+Amount quantity = Amount.of(3);
+
+// Arithmetic
+Amount total = price.times(quantity);       // 59.97
+Amount discounted = total.subtract(Amount.of(5));
+
+// Rounding
+Amount rounded = total.round(RoundingMode.HALF_UP, 2);
+
+// Comparison
+total.isGreaterThan(Amount.of(50));  // true
+total.isZeroOrNull();                // false
+
+// Safe null handling — Amount.NOTHING represents "no value"
+Amount.NOTHING.add(Amount.of(10));   // Amount.of(10)
+```
+
+### Amount vs BigDecimal
+
+`Amount` wraps `BigDecimal` but adds:
+- Null safety via `Amount.NOTHING` (acts as identity in arithmetic).
+- Fluent API: `a.add(b).times(c)` reads naturally.
+- Built-in formatting: `amount.toSmartRoundedString()`.
+
+## Formatter (Strings.apply)
+
+`Strings.apply()` provides printf-like formatting but with Sirius conventions:
+
+```java
+Strings.apply("User %s logged in from %s", username, ip);
+```
+
+For more complex cases, use `NLS.fmtr()` with named parameters.
+
+## @Explain Annotation
+
+`@Explain` is a documentation annotation used to justify code decisions that
+might otherwise trigger review comments or static analysis warnings:
+
+```java
+@Explain("We use a constant here because the interface pattern is intentional")
+public interface Permissions {
+    String PERMISSION_MANAGE_USERS = "permission-manage-users";
+}
+```
+
+It has no runtime effect — it serves purely as inline documentation for
+reviewers and maintainers. Common uses:
+- Constants in interfaces (a Sirius convention).
+- Intentional fallthrough in switch statements.
+- Suppressed warnings that need justification.
+
+## Tuple and MultiLanguageString
+
+### Tuple
+
+A simple pair container:
+
+```java
+Tuple<String, Integer> pair = Tuple.create("key", 42);
+pair.getFirst();   // "key"
+pair.getSecond();  // 42
+```
+
+### MultiLanguageString
+
+Stores text in multiple languages:
+
+```java
+MultiLanguageString mls = new MultiLanguageString();
+mls.addText("en", "Hello");
+mls.addText("de", "Hallo");
+
+// Gets text for current language, falls back to default
+String text = mls.getText();
+```
+
+Used in entities that need multi-language content (product names, descriptions).
+
+## Best Practices
+
+1. **Use `Strings.isFilled()`** instead of `str != null && !str.isEmpty()`.
+
+2. **Use `Amount`** for all monetary and quantity values — never `double`.
+
+3. **Use `NLS.fmtr()`** with named parameters for user-facing messages. Positional
+   parameters break when translations reorder words.
+
+4. **Use `Value`** when dealing with loosely typed data (web params, imports).
+
+5. **Use `@Explain`** to document non-obvious code choices proactively.

package/dist/resources/kernel/config.md

@@ -0,0 +1,155 @@
+# Configuration System
+
+Sirius uses Typesafe Config (HOCON format) for all configuration. The system
+supports layered config files with well-defined precedence and a framework
+flag mechanism for enabling/disabling modules.
+
+## HOCON Format
+
+HOCON (Human-Optimized Config Object Notation) is a superset of JSON:
+
+```hocon
+http {
+    port = 9000
+    sessionTimeout = 30 minutes
+    ssl.enabled = false
+}
+
+# Lists
+allowed.hosts = ["localhost", "example.com"]
+
+# Substitutions
+app.url = "http://"${http.host}":"${http.port}
+```
+
+Key features: comments with `#`, duration/size literals (`30 minutes`, `512MB`),
+path expressions with dots, and variable substitution.
+
+## File Precedence
+
+Config files are loaded in this order, with later files overriding earlier ones:
+
+1. **`component-NNN-name.conf`** — Framework defaults, loaded by classpath scan.
+   The numeric prefix controls load order (e.g., `component-050-kernel.conf`
+   loads before `component-070-biz.conf`).
+
+2. **`application.conf`** — Application-level defaults. This is where a Sirius
+   application defines its own configuration.
+
+3. **`develop.conf`** — Development overrides. Loaded only when the system
+   property `sirius.debug` is set (automatically set in dev mode). Use this
+   for local database URLs, debug flags, etc.
+
+4. **`instance.conf`** — Instance-specific configuration. Loaded last, used
+   for production secrets, deployment-specific URLs, and other environment
+   settings. Typically not checked into version control.
+
+### Merge Behavior
+
+Later files **merge** with earlier ones — they do not replace the entire tree.
+A key in `instance.conf` overrides only that specific key; everything else
+from earlier files remains.
+
+## Framework Flags
+
+The `sirius.frameworks` config section controls which modules are active:
+
+```hocon
+sirius.frameworks {
+    biz.tenants       = true
+    biz.tenants-jdbc  = true
+    biz.tenants-mongo = false
+    biz.storage       = true
+    biz.jobs          = true
+    biz.processes     = true
+    biz.analytics     = false
+}
+```
+
+**All flags default to `false`.** A module must be explicitly enabled by the
+application or it will not be loaded.
+
+Framework flags affect two things:
+
+1. **Entity loading** — Entities annotated with `@Framework("flag.name")` are
+   only registered in the ORM when the flag is `true`.
+
+2. **Service loading** — Services annotated with `@Register(framework = "flag.name")`
+   are only instantiated and registered when the flag is `true`.
+
+### Naming Convention
+
+Framework flags follow the pattern `module.feature` or `module.feature-variant`:
+- `biz.tenants` — The tenants module
+- `biz.tenants-jdbc` — JDBC variant of tenants
+- `biz.tenants-mongo` — MongoDB variant of tenants
+
+## @ConfigValue Injection
+
+Configuration values can be injected directly into fields:
+
+```java
+@ConfigValue("http.port")
+private int port;
+
+@ConfigValue("product.name")
+private String productName;
+
+@ConfigValue("feature.enabled")
+private boolean enabled;
+
+@ConfigValue("http.sessionTimeout")
+private Duration sessionTimeout;
+
+@ConfigValue("allowed.hosts")
+private List<String> hosts;
+```
+
+The injection happens at startup time and values are immutable after that.
+
+## Accessing Config Programmatically
+
+For dynamic access, use the `Sirius` class:
+
+```java
+// Get a config value
+String value = Sirius.getSettings().getString("my.config.key");
+
+// Check if a framework is enabled
+boolean enabled = Sirius.isFrameworkEnabled("biz.tenants");
+```
+
+## Extension Configs
+
+Libraries can provide default configuration by including a
+`component-NNN-name.conf` file in their JAR's classpath root. The naming
+convention:
+
+- `component-050-kernel.conf` — sirius-kernel defaults
+- `component-060-web.conf` — sirius-web defaults
+- `component-060-db.conf` — sirius-db defaults
+- `component-070-biz.conf` — sirius-biz defaults
+
+The numbering ensures correct load order: kernel before web, web before biz.
+
+## System Properties
+
+Some settings can be overridden via JVM system properties:
+
+- `-Dsirius.debug=true` — Enables development mode (loads `develop.conf`)
+- `-Dport=9000` — Override HTTP port
+- `-Dsirius.nodeName=node1` — Set the cluster node name
+
+## Best Practices
+
+1. **Never hardcode values** that might vary between environments. Use config.
+
+2. **Put secrets in `instance.conf`** and exclude it from version control.
+
+3. **Use `develop.conf`** for local database URLs and debug settings.
+
+4. **Document config keys** in your `component-*.conf` with comments — these
+   serve as the default values and documentation for downstream users.
+
+5. **Check framework flags** before depending on a module's services. If your
+   code is optional, guard it with a framework flag on your own `@Register`.

package/dist/resources/kernel/di.md

@@ -0,0 +1,138 @@
+# Dependency Injection
+
+Sirius uses its own lightweight DI system built into sirius-kernel. All injection
+happens at startup time — there is no runtime resolution or request-scoped injection.
+
+## @Register — Publishing a Service
+
+Every class that should participate in DI must be annotated with `@Register`:
+
+```java
+@Register(classes = {MyService.class, Startable.class})
+public class MyServiceImpl implements MyService, Startable {
+    // ...
+}
+```
+
+**Critical rule:** The `classes` parameter must list **every interface and superclass**
+the component should be discoverable as. If you implement `Startable` but omit it
+from `classes`, the framework will never call `started()`.
+
+Parameters:
+- `classes` — Array of types this component registers as (required when implementing interfaces).
+- `framework` — The framework flag that must be enabled for this component to load
+  (e.g., `@Register(framework = "biz.tenants")`).
+- `name` — Optional name for named lookups.
+
+If a class has no interfaces and no special lifecycle, a bare `@Register` suffices.
+
+## @Framework — For Entities
+
+Entities (database-mapped classes) use `@Framework` instead of `@Register(framework = ...)`:
+
+```java
+@Framework("biz.tenants-jdbc")
+public class SQLTenant extends SQLTenantAware<SQLTenant, SQLUserAccount>
+        implements Tenant<Long> {
+}
+```
+
+The distinction: `@Register(framework = ...)` controls service loading;
+`@Framework` controls entity registration in the schema and ORM layer.
+
+## @Part — Injecting a Singleton
+
+`@Part` injects a single implementation of a type:
+
+```java
+@Part
+private OMA oma;
+
+@Part
+private Tasks tasks;
+```
+
+The field is populated after the object is constructed, before `started()` is called.
+
+If no implementation is registered, the field remains `null` — no error is thrown.
+Guard against this in optional dependencies.
+
+### configPath
+
+For interfaces with multiple named implementations, use `configPath`:
+
+```java
+@Part(configPath = "storage.layer1.engine")
+private ObjectStorageEngine engine;
+```
+
+This reads the implementation class name from the config file, allowing runtime
+selection of the concrete implementation.
+
+## @Parts — Injecting All Implementations
+
+`@Parts` injects every registered implementation of a given interface as a
+`PartCollection`:
+
+```java
+@Parts(SidebarProvider.class)
+private PartCollection<SidebarProvider> providers;
+```
+
+`PartCollection` is iterable and provides `getAll()` returning a list. The
+implementations are returned in no guaranteed order.
+
+## @PriorityParts — Ordered Injection
+
+Like `@Parts`, but returns implementations sorted by their `Priorized.getPriority()`
+value (lower values first):
+
+```java
+@PriorityParts(LinkTarget.class)
+private List<LinkTarget> targets;
+```
+
+Use this when execution order matters — e.g., filter chains, interceptors, or
+fallback strategies.
+
+## @ConfigValue — Injecting Configuration
+
+`@ConfigValue` injects values from the Typesafe Config system:
+
+```java
+@ConfigValue("product.baseUrl")
+private String baseUrl;
+
+@ConfigValue("http.sessionTimeout")
+private Duration sessionTimeout;
+
+@ConfigValue("security.enabled")
+private boolean securityEnabled;
+
+@ConfigValue("cache.maxSize")
+private int maxSize;
+
+@ConfigValue("allowed.hosts")
+private List<String> allowedHosts;
+```
+
+Supported types: `String`, `int`, `long`, `boolean`, `Duration`, `List<String>`.
+The config path refers to a key in the HOCON configuration (see config resource).
+
+## Common Mistakes
+
+1. **Missing `classes` in @Register** — The most frequent DI bug. If your class
+   implements `Startable` or `Initializable` and you write `@Register` without
+   listing those interfaces in `classes`, the lifecycle methods will never be called.
+
+2. **Circular dependencies** — Sirius does not support circular `@Part` injection.
+   Use `Injector.context().findPart(...)` for lazy resolution when needed.
+
+3. **Using DI in constructors** — `@Part` fields are not yet populated during
+   construction. Use `Startable.started()` or `Initializable.initialize()` for
+   init logic that depends on injected parts.
+
+4. **Forgetting the framework flag** — If your service only makes sense when a
+   specific framework is active, always set `@Register(framework = "...")`.
+   Otherwise the class loads unconditionally and may fail if its dependencies
+   are not present.

package/dist/resources/kernel/lifecycle.md

@@ -0,0 +1,146 @@
+# Lifecycle Interfaces
+
+Sirius-kernel defines three lifecycle interfaces that components can implement to
+hook into the application startup and shutdown process. All three extend `Priorized`,
+which controls execution order.
+
+## Startable
+
+`Startable` is called once after dependency injection is complete. This is the
+primary hook for initialization logic that depends on injected `@Part` fields.
+
+```java
+@Register(classes = {MyService.class, Startable.class})
+public class MyServiceImpl implements MyService, Startable {
+
+    @Part
+    private OMA oma;
+
+    @Override
+    public int getPriority() {
+        return PriorityCollector.DEFAULT_PRIORITY;
+    }
+
+    @Override
+    public void started() {
+        // All @Part fields are populated at this point.
+        // Initialize caches, start background work, etc.
+    }
+}
+```
+
+**Key points:**
+- `started()` is called exactly once, during framework boot.
+- All `@Part` fields are guaranteed to be injected before `started()` runs.
+- Components are started in priority order (lower `getPriority()` values first).
+- The `started()` method should not block indefinitely — long-running work should
+  be dispatched to an executor via the `Tasks` service.
+
+## Stoppable
+
+`Stoppable` is called during graceful shutdown. It **must not block** for extended
+periods — it should signal threads to stop, release non-critical resources, and
+return quickly.
+
+```java
+@Register(classes = {CacheManager.class, Startable.class, Stoppable.class})
+public class CacheManager implements Startable, Stoppable {
+
+    @Override
+    public void started() {
+        // Initialize caches
+    }
+
+    @Override
+    public void stopped() {
+        // Signal cache eviction threads to stop.
+        // Must return quickly — do NOT block here.
+    }
+}
+```
+
+**Key points:**
+- `stopped()` is called in reverse priority order (highest priority stopped first).
+- Must not block. If you need to wait for cleanup, implement `Killable` instead.
+- Called before `Killable.killed()`, so resources may still be partially available.
+
+## Killable
+
+`Killable` is the final shutdown hook. Unlike `Stoppable`, it **may block** to
+perform thorough cleanup — closing database connections, flushing buffers,
+writing final state.
+
+```java
+@Register(classes = {ConnectionPool.class, Startable.class, Killable.class})
+public class ConnectionPool implements Startable, Killable {
+
+    @Override
+    public void started() {
+        // Open connection pool
+    }
+
+    @Override
+    public void killed() {
+        // Close all connections, wait for pending queries.
+        // Blocking is acceptable here.
+    }
+}
+```
+
+**Key points:**
+- `killed()` is called after all `Stoppable` instances have been stopped.
+- May block for cleanup — this is the last chance before the JVM exits.
+- Called in reverse priority order.
+
+## Priorized
+
+All lifecycle interfaces extend `Priorized`:
+
+```java
+public interface Priorized {
+    int getPriority();
+}
+```
+
+Priority values control execution order:
+- **Startup**: lower values start first (priority 10 starts before priority 100).
+- **Shutdown**: higher values stop/kill first (reverse order).
+
+Common priority constants from `PriorityCollector`:
+- `DEFAULT_PRIORITY` (100) — Use unless you have a specific ordering need.
+
+## Registration Pattern
+
+The most important pattern: always list lifecycle interfaces in `@Register(classes = ...)`:
+
+```java
+// CORRECT
+@Register(classes = {MyService.class, Startable.class, Stoppable.class})
+public class MyServiceImpl implements MyService, Startable, Stoppable { ... }
+
+// WRONG — lifecycle methods will never be called!
+@Register
+public class MyServiceImpl implements MyService, Startable, Stoppable { ... }
+```
+
+This is a common mistake. The framework discovers lifecycle participants by
+looking up registered classes — if `Startable.class` is not in the `classes`
+list, the framework does not know the component is startable.
+
+## Initialization Order Summary
+
+1. All `@Register` components are instantiated.
+2. All `@Part` fields are injected.
+3. `Startable.started()` is called in priority order (ascending).
+4. Application runs.
+5. Shutdown signal received.
+6. `Stoppable.stopped()` is called in reverse priority order (non-blocking).
+7. `Killable.killed()` is called in reverse priority order (may block).
+8. JVM exits.
+
+## Initializable
+
+A less common alternative: `Initializable` provides an `initialize()` method
+that is called even earlier than `started()`, during the injection phase itself.
+Use this only when your component must be ready before other `@Part` injections
+complete. In most cases, prefer `Startable`.

package/dist/resources/loader.d.ts

@@ -0,0 +1,9 @@
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    layer: string;
+    mimeType: string;
+    content: string;
+}
+export declare function loadResource(layer: string, name: string, description: string): ResourceDefinition;

package/dist/resources/loader.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function loadResource(layer, name, description) {
+    const filePath = join(__dirname, layer, `${name}.md`);
+    const content = readFileSync(filePath, "utf-8");
+    return {
+        uri: `sirius://${layer}/${name}`,
+        name: `${layer}/${name}`,
+        description,
+        layer,
+        mimeType: "text/markdown",
+        content,
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/resources/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/resources/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAW1D,MAAM,UAAU,YAAY,CAC1B,KAAa,EACb,IAAY,EACZ,WAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO;QACL,GAAG,EAAE,YAAY,KAAK,IAAI,IAAI,EAAE;QAChC,IAAI,EAAE,GAAG,KAAK,IAAI,IAAI,EAAE;QACxB,WAAW;QACX,KAAK;QACL,QAAQ,EAAE,eAAe;QACzB,OAAO;KACR,CAAC;AACJ,CAAC"}