@cosmicdrift/kumiko-bundled-features 0.3.0 → 0.4.0

package/src/renderer-foundation/api.ts

@@ -0,0 +1,106 @@
+// RendererFoundationApi — Cross-Feature-Schnittstelle. Konsumenten
+// (delivery, mail-Sender, Solon NKA-PDF-Generator) holen sich pro
+// Render-Call den passenden Plugin via `createRendererForTenant`.
+// Pattern symmetrisch zu ai-foundation's `createLLMProviderForTenant`.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { DEFAULT_PLUGIN_BY_KIND, type RenderKind } from "./constants";
+import { RendererError, type RendererPlugin } from "./types";
+
+export type RendererFoundationApi = {
+  /**
+   * Wählt + returnt ein RendererPlugin für (tenantId × kind). Caller
+   * rufen anschließend `plugin.render(req, ctx)`.
+   *
+   * **Auswahl-Reihenfolge:**
+   *   1. Tenant-spezifische Config (config-Bundle: `rendererPluginByKind`)
+   *   2. DEFAULT_PLUGIN_BY_KIND aus constants
+   *   3. Erstes Plugin im Pool das das kind bedient
+   *   4. `RendererError("no_plugin_for_kind")` wenn nichts passt
+   *
+   * **Caller-Pattern:** `tenantId` MUSS vom Server kommen (typisch
+   * `ctx.user.tenantId`). Plugins, die Service-Access brauchen (z.B.
+   * `renderer-mail-html` für Layout-Resolve via `template-resolver`),
+   * erhalten `RendererContext` als zweites Argument zu `render()` —
+   * matcht das Pattern von `DeliveryChannel.send(addr, msg, ctx)`.
+   * Plugins ohne Service-Deps (z.B. `renderer-simple`) ignorieren ctx.
+   */
+  readonly createRendererForTenant: (args: {
+    readonly tenantId: TenantId;
+    readonly kind: RenderKind;
+  }) => RendererPlugin;
+};
+
+// Plugin-Pool wird zur Boot-Zeit aus Extension-Usages aufgebaut.
+// Aus dem Registry kommen alle registrierten Plugins. Foundation-Feature
+// baut den Pool via `collectRendererPlugins(registry)` und steckt das
+// Result in extraContext.
+export function createRendererFoundationApi(
+  plugins: ReadonlyArray<RendererPlugin>,
+  tenantConfigLookup: (tenantId: TenantId) => Record<string, string> | null = () => null,
+): RendererFoundationApi {
+  const byKind = indexByKind(plugins);
+  return {
+    createRendererForTenant: ({ tenantId, kind }) => {
+      const tenantConfig = tenantConfigLookup(tenantId) ?? {};
+
+      // 1. Tenant-Override
+      const tenantPluginName = tenantConfig[kind];
+      if (tenantPluginName) {
+        const plugin = plugins.find((p) => p.name === tenantPluginName && p.kinds.includes(kind));
+        if (plugin) return plugin;
+        // Tenant-Config zeigt auf nicht-registriertes Plugin — fällt durch zu Default
+      }
+
+      // 2. Default-Plugin
+      const defaultName = DEFAULT_PLUGIN_BY_KIND[kind];
+      if (defaultName) {
+        const plugin = plugins.find((p) => p.name === defaultName && p.kinds.includes(kind));
+        if (plugin) return plugin;
+      }
+
+      // 3. Erstes Plugin im Pool das das kind bedient
+      const first = byKind.get(kind)?.[0];
+      if (first) return first;
+
+      // 4. Kein Plugin → Error
+      throw new RendererError(
+        `[renderer-foundation] no plugin registered for kind="${kind}". Mount at least one plugin (renderer-simple, renderer-mail-html, renderer-puppeteer-client) for this kind.`,
+        "no_plugin_for_kind",
+      );
+    },
+  };
+}
+
+function indexByKind(plugins: ReadonlyArray<RendererPlugin>): Map<RenderKind, RendererPlugin[]> {
+  const map = new Map<RenderKind, RendererPlugin[]>();
+  for (const plugin of plugins) {
+    for (const kind of plugin.kinds) {
+      const list = map.get(kind) ?? [];
+      list.push(plugin);
+      map.set(kind, list);
+    }
+  }
+  return map;
+}
+
+// Single point of truth für "dieser Handler braucht renderer-foundation".
+// Pattern symmetrisch zu requireTemplateResolver + requireTextContent.
+export function requireRendererFoundation(
+  ctx: { readonly rendererFoundation?: RendererFoundationApi } | object,
+  callerName: string,
+): RendererFoundationApi {
+  // @cast-boundary engine-bridge — rendererFoundation kommt per extraContext
+  // aus App-Bootstrap.
+  const api = (ctx as { rendererFoundation?: RendererFoundationApi }).rendererFoundation;
+  if (!api) {
+    throw new InternalError({
+      message:
+        `[${callerName}] ctx.rendererFoundation missing — App-Bootstrap muss ` +
+        `extraContext: { rendererFoundation: createRendererFoundationApi(plugins) } setzen ` +
+        `(siehe renderer-foundation/README.md).`,
+    });
+  }
+  return api;
+}

package/src/renderer-foundation/constants.ts

@@ -0,0 +1,21 @@
+// Re-export aus template-resolver — gleiche RenderKind-Domäne. Beide
+// Bundles teilen sich die Enum, damit Plugins (renderer-mail-html etc.)
+// nicht zwei Quellen importieren müssen. Cross-feature-Imports gehen
+// über das Barrel (../template-resolver), nicht via deep-import.
+import type { RenderKind as RenderKindLocal } from "../template-resolver";
+
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  RENDER_KINDS,
+  type RenderKind,
+} from "../template-resolver";
+
+// Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
+// gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.
+export const DEFAULT_PLUGIN_BY_KIND: Readonly<Record<RenderKindLocal, string>> = {
+  notification: "simple",
+  "mail-html": "mail-html",
+  "document-pdf": "puppeteer",
+  "image-snapshot": "puppeteer",
+};

package/src/renderer-foundation/feature.ts

@@ -0,0 +1,47 @@
+import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { RendererPlugin } from "./types";
+
+// renderer-foundation — Plugin-Foundation für Renderer (Notification,
+// HTML-Mail, PDF, Image). Plan-Doc:
+// kumiko-platform/docs/plans/features/renderer-foundation.md
+//
+// Pattern symmetrisch zu ai-foundation: Foundation definiert den
+// Extension-Point `renderer`, Plugins (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client) registrieren sich via `r.useExtension`.
+// Konsumenten holen sich Plugin runtime via createRendererForTenant.
+export function createRendererFoundationFeature() {
+  return defineFeature("renderer-foundation", (r) => {
+    r.requires("template-resolver");
+
+    r.extendsRegistrar("renderer", {
+      onRegister: () => {
+        // Plugin-Konformitäts-Check könnte hier: shape-validation der
+        // options (kinds, render-Funktion present). Aktuell kein
+        // shape-check — Caller's TypeScript-Type-Sicherheit greift.
+      },
+    });
+
+    return {};
+  });
+}
+
+// Plugin-Pool-Aufbau zur Boot-Zeit. App-Bootstrap ruft das nach
+// Feature-Registration auf, baut den Pool, gibt ihn via extraContext
+// an die Handlers weiter.
+//
+// Symmetrisch zu collectChannels / collectRenderers in delivery-service.
+export function collectRendererPlugins(registry: Registry): RendererPlugin[] {
+  const usages = registry.getExtensionUsages("renderer");
+  return usages.map((usage) => {
+    // @cast-boundary engine-payload — extension-usage carries unknown options
+    const opts = usage.options as {
+      kinds: RendererPlugin["kinds"];
+      render: RendererPlugin["render"];
+    };
+    return {
+      name: usage.entityName,
+      kinds: opts.kinds,
+      render: opts.render,
+    };
+  });
+}

package/src/renderer-foundation/index.ts

@@ -0,0 +1,25 @@
+export {
+  createRendererFoundationApi,
+  type RendererFoundationApi,
+  requireRendererFoundation,
+} from "./api";
+export {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  DEFAULT_PLUGIN_BY_KIND,
+  RENDER_KINDS,
+  type RenderKind,
+} from "./constants";
+export { collectRendererPlugins, createRendererFoundationFeature } from "./feature";
+export {
+  type DocumentPayload,
+  type ImageOptions,
+  type MailHtmlPayload,
+  type NotificationPayload,
+  type PdfOptions,
+  type RendererContext,
+  RendererError,
+  type RendererPlugin,
+  type RenderRequest,
+  type RenderResponse,
+} from "./types";

package/src/renderer-foundation/types.ts

@@ -0,0 +1,109 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ContentFormat, RenderKind } from "./constants";
+
+// RenderRequest — Plugins erhalten das. Resource-Mode wählt der Caller
+// (renderer-foundation api) je nach kind oder explizit. Plugin selbst
+// entscheidet nicht — es bekommt eine schon aufgelöste Form.
+export type RenderRequest =
+  | { kind: "notification"; payload: NotificationPayload }
+  | { kind: "mail-html"; payload: MailHtmlPayload }
+  | { kind: "document-pdf"; payload: DocumentPayload; options?: PdfOptions }
+  | { kind: "image-snapshot"; payload: DocumentPayload; options?: ImageOptions };
+
+export type RenderResponse =
+  | { kind: "notification"; html: string }
+  | { kind: "mail-html"; html: string; text: string }
+  | { kind: "document-pdf"; pdfBytes: Uint8Array; pageCount: number; sizeBytes: number }
+  | {
+      kind: "image-snapshot";
+      imageBytes: Uint8Array;
+      format: "png" | "jpg";
+      width: number;
+      height: number;
+    };
+
+export type NotificationPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type MailHtmlPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  readonly subject?: string;
+};
+
+export type DocumentPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type PdfOptions = {
+  readonly format?: "A4" | "Letter";
+  readonly marginMm?: { top?: number; right?: number; bottom?: number; left?: number };
+  readonly headerTemplate?: string;
+  readonly footerTemplate?: string;
+  readonly printBackground?: boolean;
+  readonly displayHeaderFooter?: boolean;
+};
+
+export type ImageOptions = {
+  readonly width?: number;
+  readonly height?: number;
+  readonly format?: "png" | "jpg";
+  readonly quality?: number;
+};
+
+// RendererContext — schmale Surface (Kumiko-Style, matcht FileProviderContext
+// + ChannelContext). Plugins, die Service-Access brauchen, holen sich
+// templateResolver/etc. via direkten Bundle-Import + ctx.db (cross-feature-
+// public-API). KEIN extraContext-Pass-Through — Plugin importiert pure-
+// Function-Factories statt App-ctx zu casten.
+//
+// **Beispiel renderer-mail-html:**
+//   import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+//   const tplApi = createTemplateResolverApi(ctx.db);
+//   const layout = await tplApi.resolveTemplate({ tenantId: ctx.tenantId, slug, kind });
+export type RendererContext = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+};
+
+// RendererPlugin-Contract — pro Plugin (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client). Plugin deklariert welche kinds es bedienen
+// kann; Foundation-Resolver wählt basierend auf Tenant-Config + kind.
+//
+// **Plugin-Invarianten:**
+// - `kinds` muss min. 1 Element haben (sonst nie ausgewählt)
+// - `render(req, ctx)`-Response.kind MUSS req.kind matchen
+// - Plugin ist zustandslos: kein internal-state zwischen render-Calls
+// - Plugin wirft `RendererError` für domain-Fehler (nicht bare Error)
+// - `ctx` ist required. Plugins ohne Service-Deps (z.B. renderer-simple)
+//   ignorieren ihn einfach — TS function-arg variance erlaubt `(req) => ...`-
+//   Implementations weiterhin (Implementation-Args ≤ Contract-Args ist OK).
+export type RendererPlugin = {
+  readonly name: string;
+  readonly kinds: ReadonlyArray<RenderKind>;
+  render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+};
+
+export class RendererError extends Error {
+  constructor(
+    message: string,
+    public readonly code: "no_plugin_for_kind" | "invalid_payload" | "other",
+  ) {
+    super(message);
+    this.name = "RendererError";
+  }
+}

package/src/renderer-simple/__tests__/adapter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { RendererError } from "../../renderer-foundation";
+import { adaptToFoundation } from "../feature";
+
+describe("renderer-simple :: adaptToFoundation", () => {
+  test("kind='notification' rendert via simpleRenderer und gibt RenderResponse zurück", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: {
+        template: "welcome",
+        variables: { title: "Welcome!", body: "Hello there" },
+      },
+    });
+    expect(res.kind).toBe("notification");
+    if (res.kind === "notification") {
+      // simpleRenderer baut HTML mit title als header + body als section
+      expect(res.html).toContain("Welcome!");
+      expect(res.html).toContain("Hello there");
+      expect(res.html).toContain("<!DOCTYPE html>");
+    }
+  });
+
+  test("leere variables → leerer body, kein crash", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: { template: "", variables: {} },
+    });
+    expect(res.kind).toBe("notification");
+  });
+
+  test("non-notification kind → RendererError mit code 'invalid_payload'", async () => {
+    await expect(
+      adaptToFoundation({
+        kind: "mail-html",
+        payload: { content: "test", contentFormat: "markdown" },
+      }),
+    ).rejects.toThrow(RendererError);
+
+    try {
+      await adaptToFoundation({
+        kind: "document-pdf",
+        payload: { content: "test", contentFormat: "markdown" },
+      });
+      expect.fail("expected RendererError");
+    } catch (e) {
+      expect(e).toBeInstanceOf(RendererError);
+      expect((e as RendererError).code).toBe("invalid_payload");
+    }
+  });
+});

package/src/renderer-simple/feature.ts

@@ -1,12 +1,37 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { RendererError, type RenderRequest, type RenderResponse } from "../renderer-foundation";
 import { simpleRenderer } from "./simple-renderer";
 
+// Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
+// NotificationRenderer-Contract), renderer-foundation erwartet
+// `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
+// die simpleRenderer-Implementierung (Template-Strings → HTML mit
+// Inline-CSS) und packt sie in den RendererPlugin-Contract.
+//
+// Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
+export async function adaptToFoundation(req: RenderRequest): Promise<RenderResponse> {
+  if (req.kind !== "notification") {
+    // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
+    // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
+    throw new RendererError(
+      `renderer-simple supports only kind="notification", got "${req.kind}"`,
+      "invalid_payload",
+    );
+  }
+  const html = await simpleRenderer.render({
+    template: req.payload.template ?? "",
+    variables: req.payload.variables ?? {},
+  });
+  return { kind: "notification", html };
+}
+
 export function createRendererSimpleFeature(): FeatureDefinition {
   return defineFeature("rendererSimple", (r) => {
-    r.requires("delivery");
+    r.requires("renderer-foundation");
 
-    r.useExtension("notificationRenderer", "simple", {
-      render: simpleRenderer.render,
+    r.useExtension("renderer", "simple", {
+      kinds: ["notification"] as const,
+      render: adaptToFoundation,
     });
   });
 }

package/src/template-resolver/README.md

@@ -0,0 +1,89 @@
+# template-resolver
+
+Strukturierter Template-Storage mit Tenant-Override-Hierarchie, Locale-Fallback und Resource-Linking via `file-foundation`.
+
+**Plan-Doc:** [`kumiko-platform/docs/plans/features/template-resolver.md`](../../../../../../kumiko-platform/docs/plans/features/template-resolver.md)
+
+**Status (2026-05-19):** 45 Integration-Tests grün, typecheck grün, self+advisor-reviewed. Implementierungs-Erkenntnisse im Plan-Doc.
+
+## Mount
+
+```typescript
+// App-Bootstrap
+import {
+  createTemplateResolverApi,
+  createTemplateResolverFeature,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+
+const features = [
+  createTemplateResolverFeature(),
+  // ... weitere Features
+];
+
+const app = createKumikoApp({
+  features,
+  extraContext: ({ db }) => ({
+    templateResolver: createTemplateResolverApi(db),
+  }),
+});
+```
+
+## Konsumtion (in Feature-Handlern)
+
+```typescript
+import { requireTemplateResolver } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+
+async function someHandler(ctx) {
+  const templateResolver = requireTemplateResolver(ctx, "someHandler");
+  const template = await templateResolver.resolveTemplate({
+    tenantId: ctx.user.tenantId,
+    slug: "nka-versand",
+    kind: "mail-html",
+    locale: "de",
+  });
+  // template.content + template.variableSchema + template.linkedResources verwenden
+  // ...
+}
+```
+
+## Resolver-Reihenfolge (4-Stufen-Fallback)
+
+1. `tenantId` + requested locale
+2. `SYSTEM_TENANT_ID` + requested locale
+3. `tenantId` + `FALLBACK_LOCALE` (default "de")
+4. `SYSTEM_TENANT_ID` + `FALLBACK_LOCALE`
+
+Wenn nichts gefunden → `TemplateNotFoundError`.
+
+## Admin-Workflows (Write-Handlers + Queries)
+
+| Handler | QN | Wer | Was |
+|---|---|---|---|
+| `TemplateResolverHandlers.upsertSystem` | `template-resolver:write:upsert-system` | SystemAdmin | Erstellt/Updated System-Default-Templates (`SYSTEM_TENANT_ID`, scope='system', status='active') |
+| `TemplateResolverHandlers.upsertTenant` | `template-resolver:write:upsert-tenant` | TenantAdmin (eigener Tenant) + SystemAdmin via `tenantIdOverride` | Erstellt/Updated Tenant-Overrides (scope='tenant'), default-status='draft' |
+| `TemplateResolverHandlers.publish` | `template-resolver:write:publish` | TenantAdmin (eigener Tenant) | Setzt status='active' |
+| `TemplateResolverHandlers.archive` | `template-resolver:write:archive` | TenantAdmin (eigener Tenant) | Setzt status='archived' (Resolver ignoriert es danach) |
+| `TemplateResolverQueries.findById` | `template-resolver:query:find-by-id` | TenantAdmin + User (eigener Tenant + system-templates sichtbar) | Raw-Lookup für Edit-UI |
+| `TemplateResolverQueries.list` | `template-resolver:query:list` | gleich | Filter nach kind/locale/status, optional includeSystem |
+
+**SystemAdmin-Cross-Tenant für publish/archive/findById:** aktuell nicht implementiert. `ctx.db` ist tenant-scoped (createTenantDb in dispatcher), SystemAdmin sieht ohne explicit `tenantIdOverride` keine fremden Tenants. Wenn Admin-UI das fordert: Schema-Erweiterung in einer M2-Iteration.
+
+## Status-Lifecycle
+
+```
+upsertSystem  ──┐
+                ├──► status: "active" (System-Default sofort aktiv)
+upsertTenant  ──┴──► status: "draft" (Default) | "active" (explizit)
+
+publish ───────► status: "active"
+archive ───────► status: "archived"
+```
+
+Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
+
+## Out-of-Scope
+
+- Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`
+- Resource-URL-Substitution (signed-URL vs. data-URI) — Caller-Verantwortung je nach kind
+- Visual Template-Editor — `designer`-Bundle (geplant)
+- A/B-Testing — eigenes Bundle wenn Bedarf real