sirius-framework-mcp 0.1.0

package/dist/resources/web/controllers.md

@@ -0,0 +1,151 @@
+# Controllers
+
+Controllers in sirius-web handle HTTP requests by mapping URI patterns to methods.
+They live in `sirius.web.controller` (base framework) and `sirius.biz.web` (business layer).
+
+## BasicController — The Base Class
+
+All controllers extend `BasicController`, which provides:
+
+- `getUser()` — returns the current `UserInfo`
+- `hasPermission(String)` — checks if the current user holds a permission
+- `assertPermission(String)` — throws if the permission is missing
+- `assertNotNull(Object)` — throws a 404-style error if the object is null
+- `showSavedMessage()` — flashes a "Changes have been saved" message
+- `showDeletedMessage()` — flashes a "Object was deleted" message
+- `fail(WebContext, HandledException)` — renders an error template
+
+In sirius-biz, controllers typically extend `BizController` which adds tenant-aware
+helpers like `findForTenant()` and `assertTenant()`.
+
+## @Routed — Mapping URIs to Methods
+
+`@Routed` attaches a URI pattern to a controller method:
+
+```java
+@Routed("/products/:1/edit")
+public void editProduct(WebContext webContext, String productId) {
+    // :1 binds the path segment to the first String parameter after WebContext
+}
+```
+
+**Pattern elements:**
+- String literal (`/products`) — must match exactly
+- `:1`, `:2`, ... — captures the path segment into the n-th method parameter (after WebContext)
+- `*` — matches any single path segment (value is discarded)
+- `**` — variadic, must be last; matched segments go into a `List<String>` parameter
+- `#{name}` — captures the segment into a request attribute
+- `${i18n.key}` — matches the NLS-translated value of the key
+
+**Priority:** When routes conflict (e.g., `/foo/:1` vs `/foo/special`), set
+`priority` on the more specific route to a value below `PriorityCollector.DEFAULT_PRIORITY`:
+
+```java
+@Routed(value = "/foo/special", priority = 90)
+```
+
+**HTTP methods:** By default all methods are accepted. Restrict with:
+
+```java
+@Routed(value = "/api/items", methods = HttpMethod.POST)
+```
+
+## @LoginRequired and @Permission
+
+Place these on routed methods to enforce access control:
+
+```java
+@Routed("/admin/users")
+@LoginRequired
+@Permission("permission-manage-users")
+public void users(WebContext webContext) { ... }
+```
+
+`@LoginRequired` requires any authenticated user. `@Permission("name")` requires
+the named permission. Both can be combined; the login check runs first.
+
+## @DefaultRoute — Fallback on Error
+
+Mark one routed method per controller with `@DefaultRoute`. If any other route in
+the same controller throws an error, the framework re-dispatches to the default
+route and displays the error message there, rather than showing a generic error page:
+
+```java
+@Routed("/products")
+@DefaultRoute
+public void products(WebContext webContext) {
+    // This serves as the fallback — e.g., list view
+}
+```
+
+## WebContext — The Request Object
+
+Every routed method receives a `WebContext` as its first parameter. Key methods:
+
+- `webContext.get("paramName")` — returns a `Value` for a query/form parameter
+- `webContext.isSafePOST()` — true if POST with a valid CSRF token
+- `webContext.ensureSafePOST()` — like `isSafePOST()` but throws on invalid token
+- `webContext.respondWith().template("/templates/path.html.pasta", args...)` — render a Pasta template
+- `webContext.respondWith().redirectToGet(url)` — HTTP redirect after POST
+
+## Concrete Example
+
+```java
+@Register
+public class ProductController extends BizController {
+
+    @Routed("/products")
+    @DefaultRoute
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void products(WebContext webContext) {
+        SQLQuery<Product> query = oma.select(Product.class)
+                                     .orderAsc(Product.NAME);
+        webContext.respondWith()
+                  .template("/templates/products/list.html.pasta", query);
+    }
+
+    @Routed("/product/:1/edit")
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void editProduct(WebContext webContext, String productId) {
+        Product product = findForTenant(Product.class, productId);
+
+        if (webContext.ensureSafePOST()) {
+            load(webContext, product);
+            oma.update(product);
+            showSavedMessage();
+            webContext.respondWith().redirectToGet("/products");
+            return;
+        }
+
+        webContext.respondWith()
+                  .template("/templates/products/edit.html.pasta", product);
+    }
+
+    @Routed("/product/:1/delete")
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void deleteProduct(WebContext webContext, String productId) {
+        Product product = findForTenant(Product.class, productId);
+        oma.delete(product);
+        showDeletedMessage();
+        webContext.respondWith().redirectToGet("/products");
+    }
+}
+```
+
+## Common Mistakes
+
+1. **Forgetting `@Register`** — Controllers must be annotated with `@Register`
+   or they will not be discovered by the framework.
+
+2. **Missing CSRF check on mutations** — Always use `ensureSafePOST()` or
+   `isSafePOST()` before modifying data. Skipping this opens CSRF vulnerabilities.
+
+3. **Route priority conflicts** — If `/items/:1` and `/items/new` both exist,
+   the generic route may match first. Set a lower `priority` value on `/items/new`.
+
+4. **Returning after redirect** — After calling `redirectToGet()`, always `return`
+   from the method. Otherwise the code continues and may try to render a template,
+   causing a "response already committed" error.

package/dist/resources/web/services.md

@@ -0,0 +1,136 @@
+# Web Services (API Endpoints)
+
+Sirius-web provides annotations to mark controller methods as structured API
+endpoints that automatically handle envelope wrapping and error formatting.
+These live in `sirius.web.services`.
+
+## @PublicService — External API
+
+`@PublicService` marks a routed method as part of the public API. These services
+are listed in the built-in API explorer (`/system/api`):
+
+```java
+@Routed("/api/v1/products")
+@PublicService(apiName = "products", format = Format.JSON)
+@LoginRequired
+public void listProducts(WebContext webContext, JSONStructuredOutput out) {
+    out.beginArray("products");
+    oma.select(Product.class).iterateAll(product -> {
+        out.beginObject("product");
+        out.property("id", product.getIdAsString());
+        out.property("name", product.getName());
+        out.endObject();
+    });
+    out.endArray();
+}
+```
+
+**Parameters:**
+- `apiName` — Groups the service in the API explorer. Each API name needs a
+  matching config block under `http.api`.
+- `format` — One of `Format.JSON`, `Format.XML`, or `Format.RAW`.
+- `priority` — Sort order in the API explorer (default: 100).
+- `path` — Custom documentation path, useful when the `@Routed` pattern contains
+  parameter placeholders (e.g., turning `/ps/:1/api` into `/ps/{process}/api`).
+- `documentationUri` — Optional link to external documentation.
+- `enforceMaintenanceMode` — If `true`, blocks calls when the scope is locked.
+
+When `format` is `JSON`, the method must accept `JSONStructuredOutput` as its
+second parameter. When `XML`, it must accept `XMLStructuredOutput`.
+
+## @InternalService — Internal API
+
+`@InternalService` works identically to `@PublicService` but is not listed in the
+public API explorer. Use it for endpoints consumed only by internal systems:
+
+```java
+@Routed("/api/internal/sync")
+@InternalService(format = Format.JSON)
+public void sync(WebContext webContext, JSONStructuredOutput out) {
+    out.property("status", "ok");
+}
+```
+
+The only parameter is `format` (defaults to `Format.JSON`).
+
+## Automatic Envelope Wrapping
+
+For both annotations, the framework automatically:
+
+1. Calls `beginResult()` before your method
+2. Calls `endResult()` after your method
+3. Sets `success: true` on normal completion
+
+**Successful JSON response:**
+```json
+{
+    "success": true,
+    "error": false,
+    "products": [ ... ]
+}
+```
+
+**Error JSON response (on exception):**
+```json
+{
+    "success": false,
+    "error": true,
+    "message": "The product was not found.",
+    "code": "PRODUCT_NOT_FOUND"
+}
+```
+
+The error code and HTTP status can be set via exception hints:
+
+```java
+throw Exceptions.createHandled()
+                .withDirectMessage("The product was not found.")
+                .hint(Controller.ERROR_CODE, "PRODUCT_NOT_FOUND")
+                .hint(Controller.HTTP_STATUS, 404)
+                .handle();
+```
+
+For `Format.RAW`, error responses simply return the appropriate HTTP status code
+without a structured body.
+
+## Format.RAW
+
+Use `Format.RAW` when the method produces a non-structured response (e.g., a file
+download or plain text). The method does not receive a structured output parameter
+and handles the response directly via `WebContext`:
+
+```java
+@Routed("/api/v1/export")
+@PublicService(apiName = "export", format = Format.RAW)
+public void export(WebContext webContext) {
+    webContext.respondWith().direct(HttpResponseStatus.OK, "text/csv", csvData);
+}
+```
+
+## Swagger / OpenAPI Parameter Documentation
+
+Service parameters should be documented with `@io.swagger.v3.oas.annotations.Parameter`
+on each accepted query or form parameter. The API explorer picks these up:
+
+```java
+@Routed("/api/v1/products")
+@PublicService(apiName = "products", format = Format.JSON)
+@io.swagger.v3.oas.annotations.Parameter(name = "query", description = "Search filter")
+@io.swagger.v3.oas.annotations.Parameter(name = "limit", description = "Max results")
+public void listProducts(WebContext webContext, JSONStructuredOutput out) { ... }
+```
+
+## Common Mistakes
+
+1. **Wrong second parameter type** — `Format.JSON` requires `JSONStructuredOutput`;
+   `Format.XML` requires `XMLStructuredOutput`. Mismatching causes a startup error.
+
+2. **Calling beginResult/endResult manually** — The framework handles this
+   automatically. Calling it again produces malformed output.
+
+3. **Forgetting the apiName config** — Every `apiName` used in `@PublicService`
+   needs a corresponding `http.api.<apiName>` block in the config, or the API
+   explorer will not display the service correctly.
+
+4. **Using @Routed(jsonCall = true)** — This is deprecated since 2021. Use
+   `@InternalService(format = Format.JSON)` instead.

package/dist/resources/web/templates.md

@@ -0,0 +1,162 @@
+# Templates (Pasta / Tagliatelle)
+
+Sirius uses the Pasta/Tagliatelle template engine for server-side HTML rendering.
+Template files use the `.html.pasta` extension and live under
+`src/main/resources/default/templates/`.
+
+## File Structure
+
+```
+src/main/resources/default/
+    templates/biz/           # Page templates
+    taglib/                  # Custom tag definitions (w:, t:, k:)
+    extensions/              # Extension point templates
+    mail/                    # Email templates
+```
+
+Templates are invoked from controllers via:
+
+```java
+webContext.respondWith().template("/templates/products/list.html.pasta", query);
+```
+
+## Typed Arguments — `<i:arg>`
+
+Every template declares its parameters at the top with `<i:arg>`:
+
+```html
+<i:arg type="sirius.db.jdbc.SmartQuery" name="query"/>
+<i:arg type="String" name="title"/>
+```
+
+The types must be fully qualified Java class names. The arguments are passed
+positionally from the controller's `template()` call.
+
+## Control Flow
+
+**Conditionals:**
+```html
+<i:if test="product.isNew()">
+    <h1>Create Product</h1>
+</i:if>
+<i:else>
+    <h1>Edit @product.getName()</h1>
+</i:else>
+```
+
+**Loops:**
+```html
+<i:for type="sirius.biz.model.Product" var="product" items="query.queryList()">
+    <tr>
+        <td>@product.getName()</td>
+        <td>@product.getPrice()</td>
+    </tr>
+</i:for>
+```
+
+**Local variables:**
+```html
+<i:local name="count" value="query.count()"/>
+<p>Total: @count</p>
+```
+
+**Inline expressions:**
+Use `@` to output Java expressions directly: `@product.getName()`. For more
+complex expressions, use `@(expression)`.
+
+## Taglib Prefixes
+
+Custom tags are organized by prefix:
+
+- **`w:`** — Web widgets from sirius-web (e.g., `<w:page>`, `<w:table>`)
+- **`t:`** — Tycho UI components from sirius-biz (e.g., `<t:page>`, `<t:sidebar>`,
+  `<t:searchHeader>`, `<t:datacards>`)
+- **`e:`** — Extension points that can be filled by other modules
+
+Tycho (`t:`) is the standard modern UI framework for sirius-biz applications.
+Most pages use `<t:page>` as their root element.
+
+## Internationalization — `@i18n`
+
+Use `@i18n("key")` to output a translated string from the NLS system:
+
+```html
+<h1>@i18n("Product.plural")</h1>
+<button>@i18n("NLS.save")</button>
+```
+
+The key is resolved via `NLS.get()` using the current request's language.
+
+## Pragmas
+
+Pragmas provide metadata about the template. They are declared at the top:
+
+```html
+<i:pragma name="title" value="Products"/>
+<i:pragma name="description" value="Lists all products"/>
+```
+
+Pragmas can be read by parent templates or the framework to set page titles,
+breadcrumbs, or other metadata.
+
+## Concrete Template Example
+
+```html
+<i:arg type="sirius.biz.model.Product" name="product"/>
+
+<i:pragma name="title" value="@apply('Edit: %s', product.getName())"/>
+
+<t:page>
+    <i:block name="breadcrumbs">
+        <li><a href="/products">@i18n("Product.plural")</a></li>
+        <li>@product.getName()</li>
+    </i:block>
+
+    <i:block name="page-header">
+        <t:pageHeader title="@product.getName()"/>
+    </i:block>
+
+    <t:editForm url="@apply('/product/%s/edit', product.getIdAsString())">
+        <div class="row">
+            <t:textfield name="name" value="@product.getName()"
+                         label="@i18n('Product.name')"
+                         class="col-md-6"/>
+            <t:textfield name="price" value="@toUserString(product.getPrice())"
+                         label="@i18n('Product.price')"
+                         class="col-md-6"/>
+        </div>
+    </t:editForm>
+</t:page>
+```
+
+## Extension Points
+
+Extensions allow modules to inject content into templates without modifying them:
+
+```html
+<!-- In the base template -->
+<e:extensions target="product-details" product="@product"/>
+
+<!-- In an extension template under extensions/product-details/ -->
+<i:arg type="sirius.biz.model.Product" name="product"/>
+<t:textfield name="sku" value="@product.getSku()" label="SKU"/>
+```
+
+All templates found under `extensions/<target-name>/` are rendered at the
+extension point, in alphabetical filename order.
+
+## Common Mistakes
+
+1. **Non-qualified type in `<i:arg>`** — Always use the fully qualified class name.
+   Writing `SmartQuery` instead of `sirius.db.jdbc.SmartQuery` causes a compile error.
+
+2. **Forgetting to pass all arguments** — The `template()` call must pass arguments
+   in the same order as the `<i:arg>` declarations. Missing arguments cause
+   runtime errors.
+
+3. **Using `@` in HTML attributes without quotes** — Expressions in attributes
+   must be quoted: `href="@url"`, not `href=@url`.
+
+4. **Modifying taglib templates directly** — Tags under `taglib/` are framework-
+   provided. Override behavior through extensions or by creating custom tags rather
+   than editing built-in ones.

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { listEntities, listFrameworkFlags, listRoutes, listJobs, listComposites, listControllers, } from "./introspection.js";
+export type { EntityInfo, FrameworkFlag, FullRouteInfo, ControllerInfo, } from "./introspection.js";
+export { scaffoldEntity, scaffoldJob, scaffoldTest, scaffoldComposite, scaffoldController, toUpperSnake, } from "./scaffold.js";
+export type { FieldDefinition, ScaffoldFile, ScaffoldResult, ScaffoldEntityOptions, ScaffoldJobOptions, ScaffoldTestOptions, ScaffoldCompositeOptions, ScaffoldControllerOptions, } from "./scaffold.js";

package/dist/tools/index.js

@@ -0,0 +1,3 @@
+export { listEntities, listFrameworkFlags, listRoutes, listJobs, listComposites, listControllers, } from "./introspection.js";
+export { scaffoldEntity, scaffoldJob, scaffoldTest, scaffoldComposite, scaffoldController, toUpperSnake, } from "./scaffold.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,cAAc,EACd,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/tools/introspection.d.ts

@@ -0,0 +1,55 @@
+import { JavaClassInfo, RouteInfo } from "../java-parser.js";
+export interface EntityInfo {
+    name: string;
+    packageName: string;
+    superClass: string;
+    type: "sql" | "mongo" | "elastic" | "unknown";
+    annotations: JavaClassInfo["annotations"];
+    mappings: string[];
+    filePath: string;
+}
+export interface FrameworkFlag {
+    name: string;
+    defaultValue: boolean;
+    description: string;
+    filePath: string;
+}
+export interface FullRouteInfo extends RouteInfo {
+    controller: string;
+    filePath: string;
+}
+export interface ControllerInfo {
+    name: string;
+    packageName: string;
+    superClass: string;
+    routes: RouteInfo[];
+    filePath: string;
+}
+/**
+ * Scan for entity classes whose superClass matches known entity superclasses.
+ */
+export declare function listEntities(basePath: string): Promise<EntityInfo[]>;
+/**
+ * Parse HOCON component-*.conf files and extract sirius.frameworks flags.
+ */
+export declare function listFrameworkFlags(basePath: string): Promise<FrameworkFlag[]>;
+/**
+ * Extract routes from all Java files. Optionally filter by URI prefix.
+ */
+export declare function listRoutes(basePath: string, prefix?: string): Promise<FullRouteInfo[]>;
+/**
+ * Find JobFactory implementations by matching known job superclasses.
+ */
+export declare function listJobs(basePath: string): Promise<(JavaClassInfo & {
+    filePath: string;
+})[]>;
+/**
+ * Find Composite classes (superClass === "Composite").
+ */
+export declare function listComposites(basePath: string): Promise<(JavaClassInfo & {
+    filePath: string;
+})[]>;
+/**
+ * Find controller classes by matching known controller superclasses.
+ */
+export declare function listControllers(basePath: string): Promise<ControllerInfo[]>;