@cosmicdrift/kumiko-bundled-features 0.3.0 → 0.4.1

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

package/src/template-resolver/__tests__/handlers.integration.ts

@@ -0,0 +1,403 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createTemplateResolverFeature } from "../feature";
+import { TemplateResolverHandlers, TemplateResolverQueries } from "../qualified-names";
+import { templateResourceEntity } from "../table";
+
+let stack: TestStack;
+let db: DbConnection;
+
+const systemAdmin = TestUsers.systemAdmin;
+// Explizite, distinct tenantIds — createTestUser default-falls auf
+// TestUsers.admin.tenantId (alle User im selben Tenant). Wir testen
+// Tenant-Isolation, deshalb pro Test-User eigener Tenant.
+const tenantA_Admin = createTestUser({
+  id: 2,
+  roles: ["TenantAdmin"],
+  tenantId: testTenantId(10),
+});
+const tenantB_Admin = createTestUser({
+  id: 3,
+  roles: ["TenantAdmin"],
+  tenantId: testTenantId(20),
+});
+const normalUser = createTestUser({ id: 4, tenantId: testTenantId(10) });
+
+const feature = createTemplateResolverFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, templateResourceEntity);
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+const basePayload = {
+  slug: "test-slug",
+  kind: "mail-html" as const,
+  locale: "de",
+  content: "Hello {{variables.name}}",
+  contentFormat: "markdown" as const,
+  variableSchema: { name: { type: "string" } },
+  linkedResources: {},
+};
+
+// Audit-Trail via event-store-executor: kein dedizierter Test, weil
+// `stack.events.postSave` im aktuellen Test-Stack-Setup nicht aktiv
+// populated wird (Pipeline-Hooks-Wiring unterschiedlich zum Prod-Path).
+// Indirekter Beweis: alle Resolver/Handler-Tests funktionieren — würde
+// der executor nicht in die DB schreiben, würden findById/list/
+// resolveTemplate alles nichts finden. Wenn echtes Audit-Log-Test
+// gebraucht wird: direkt `read_events`-Tabelle abfragen.
+describe("template-resolver :: upsertSystem", () => {
+  test("SystemAdmin kann System-Template anlegen", async () => {
+    const result = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "system-new" },
+      systemAdmin,
+    );
+    expect(result).toMatchObject({ slug: "system-new", isNew: true });
+  });
+
+  test("idempotent — zweiter Call updated existing System-Template", async () => {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "system-idem", content: "v1" },
+      systemAdmin,
+    );
+    const result = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "system-idem", content: "v2" },
+      systemAdmin,
+    );
+    expect(result).toMatchObject({ slug: "system-idem", isNew: false });
+  });
+
+  test("TenantAdmin denied (access_denied)", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "tenant-blocked" },
+      tenantA_Admin,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("normal User denied", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "user-blocked" },
+      normalUser,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("invalid slug rejected", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "Invalid Slug!" },
+      systemAdmin,
+    );
+    expectErrorIncludes(err, "validation_error");
+  });
+});
+
+describe("template-resolver :: upsertTenant", () => {
+  test("TenantAdmin kann Override für eigenen Tenant anlegen", async () => {
+    const result = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "tenant-own" },
+      tenantA_Admin,
+    );
+    expect(result).toMatchObject({ slug: "tenant-own", isNew: true });
+  });
+
+  test("default-status ist draft, explizites active geht auch", async () => {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "tenant-default-draft" },
+      tenantA_Admin,
+    );
+    const fetched = await stack.http.queryOk<Record<string, unknown>>(
+      TemplateResolverQueries.list,
+      { kind: "mail-html", locale: "de", includeSystem: false },
+      tenantA_Admin,
+    );
+    const found = (fetched as unknown as Array<{ slug: string; status: string }>).find(
+      (r) => r.slug === "tenant-default-draft",
+    );
+    expect(found?.status).toBe("draft");
+
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "tenant-explicit-active", status: "active" },
+      tenantA_Admin,
+    );
+    const fetched2 = await stack.http.queryOk<Record<string, unknown>>(
+      TemplateResolverQueries.list,
+      { kind: "mail-html", locale: "de", includeSystem: false },
+      tenantA_Admin,
+    );
+    const found2 = (fetched2 as unknown as Array<{ slug: string; status: string }>).find(
+      (r) => r.slug === "tenant-explicit-active",
+    );
+    expect(found2?.status).toBe("active");
+  });
+
+  test("SystemAdmin kann via tenantIdOverride cross-tenant schreiben", async () => {
+    const result = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "system-override", tenantIdOverride: tenantA_Admin.tenantId },
+      systemAdmin,
+    );
+    expect(result).toMatchObject({ slug: "system-override", isNew: true });
+  });
+
+  test("SystemAdmin-Override auf SYSTEM_TENANT_ID → access_denied (use upsertSystem)", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "denied-system-override", tenantIdOverride: SYSTEM_TENANT_ID },
+      systemAdmin,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("TenantAdmin-Override-Versuch → access_denied", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "denied-override", tenantIdOverride: tenantB_Admin.tenantId },
+      tenantA_Admin,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("normal User denied", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "user-denied" },
+      normalUser,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+});
+
+describe("template-resolver :: publish + archive", () => {
+  test("publish setzt status auf active", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "publish-test", status: "draft" },
+      tenantA_Admin,
+    );
+    const published = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.publish,
+      { id: created.id },
+      tenantA_Admin,
+    );
+    expect(published).toMatchObject({ status: "active" });
+  });
+
+  test("publish: TenantA kann TenantB's Template nicht publishen (NotFound)", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "isolation-publish" },
+      tenantA_Admin,
+    );
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.publish,
+      { id: created.id },
+      tenantB_Admin,
+    );
+    expectErrorIncludes(err, "not_found");
+  });
+
+  test("publish: nicht-existierender ID → NotFound", async () => {
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.publish,
+      { id: "00000000-0000-4000-8000-000000000999" },
+      tenantA_Admin,
+    );
+    expectErrorIncludes(err, "not_found");
+  });
+
+  test("archive setzt status auf archived", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "archive-test", status: "active" },
+      tenantA_Admin,
+    );
+    const archived = await stack.http.writeOk<Record<string, unknown>>(
+      TemplateResolverHandlers.archive,
+      { id: created.id },
+      tenantA_Admin,
+    );
+    expect(archived).toMatchObject({ status: "archived" });
+  });
+
+  test("archive: tenant-isolation (NotFound bei fremdem Tenant)", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "isolation-archive" },
+      tenantA_Admin,
+    );
+    const err = await stack.http.writeErr(
+      TemplateResolverHandlers.archive,
+      { id: created.id },
+      tenantB_Admin,
+    );
+    expectErrorIncludes(err, "not_found");
+  });
+
+  // SystemAdmin-Cross-Tenant-Publish/Archive nicht implementiert: ctx.db ist
+  // tenant-scoped (createTenantDb in dispatcher). Braucht `tenantIdOverride`
+  // im Schema wie upsertTenant. M2-Erweiterung wenn Admin-UI das fordert.
+});
+
+describe("template-resolver :: findById query", () => {
+  test("findet eigenes Template", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "find-own" },
+      tenantA_Admin,
+    );
+    const result = await stack.http.queryOk<Record<string, unknown>>(
+      TemplateResolverQueries.findById,
+      { id: created.id },
+      tenantA_Admin,
+    );
+    expect(result).toMatchObject({ slug: "find-own", scope: "tenant" });
+  });
+
+  test("returnt null bei fremdem Tenant", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "find-isolation" },
+      tenantA_Admin,
+    );
+    const result = await stack.http.queryOk(
+      TemplateResolverQueries.findById,
+      { id: created.id },
+      tenantB_Admin,
+    );
+    expect(result).toBeNull();
+  });
+
+  test("System-Templates sind für alle authentifizierten User sichtbar", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "find-system" },
+      systemAdmin,
+    );
+    const result = await stack.http.queryOk<Record<string, unknown>>(
+      TemplateResolverQueries.findById,
+      { id: created.id },
+      tenantA_Admin,
+    );
+    expect(result).toMatchObject({ slug: "find-system", scope: "system" });
+    expect((result as { tenantId: string }).tenantId).toBe(SYSTEM_TENANT_ID);
+  });
+
+  // SystemAdmin-Cross-Tenant-FindById nicht implementiert — gleicher Grund
+  // wie publish/archive. ctx.db tenant-scoped, braucht tenantIdOverride im
+  // findById-Schema. M2-Erweiterung.
+});
+
+describe("template-resolver :: list query", () => {
+  test("includeSystem=true zeigt eigene + system", async () => {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "list-system-1", locale: "de", kind: "mail-html" },
+      systemAdmin,
+    );
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "list-tenant-1", locale: "de", kind: "mail-html" },
+      tenantA_Admin,
+    );
+    const result = (await stack.http.queryOk(
+      TemplateResolverQueries.list,
+      { kind: "mail-html", locale: "de", includeSystem: true },
+      tenantA_Admin,
+    )) as Array<{ slug: string; scope: string }>;
+    const slugs = result.map((r) => r.slug);
+    expect(slugs).toContain("list-system-1");
+    expect(slugs).toContain("list-tenant-1");
+  });
+
+  test("includeSystem=false zeigt nur eigenen Tenant", async () => {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertSystem,
+      { ...basePayload, slug: "list-system-2", locale: "tr", kind: "notification" },
+      systemAdmin,
+    );
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "list-tenant-2", locale: "tr", kind: "notification" },
+      tenantA_Admin,
+    );
+    const result = (await stack.http.queryOk(
+      TemplateResolverQueries.list,
+      { kind: "notification", locale: "tr", includeSystem: false },
+      tenantA_Admin,
+    )) as Array<{ slug: string; scope: string }>;
+    const slugs = result.map((r) => r.slug);
+    expect(slugs).toContain("list-tenant-2");
+    expect(slugs).not.toContain("list-system-2");
+  });
+
+  test("tenant-isolation: TenantA's templates nicht für TenantB", async () => {
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "list-iso", locale: "fr", kind: "notification" },
+      tenantA_Admin,
+    );
+    const result = (await stack.http.queryOk(
+      TemplateResolverQueries.list,
+      { kind: "notification", locale: "fr", includeSystem: false },
+      tenantB_Admin,
+    )) as Array<{ slug: string }>;
+    expect(result.map((r) => r.slug)).not.toContain("list-iso");
+  });
+
+  test("status-Filter funktioniert", async () => {
+    const draft = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      { ...basePayload, slug: "filter-draft", locale: "es", kind: "notification", status: "draft" },
+      tenantA_Admin,
+    );
+    await stack.http.writeOk(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        ...basePayload,
+        slug: "filter-active",
+        locale: "es",
+        kind: "notification",
+        status: "active",
+      },
+      tenantA_Admin,
+    );
+    const drafts = (await stack.http.queryOk(
+      TemplateResolverQueries.list,
+      { kind: "notification", locale: "es", status: "draft", includeSystem: false },
+      tenantA_Admin,
+    )) as Array<{ slug: string }>;
+    expect(drafts.map((r) => r.slug)).toContain("filter-draft");
+    expect(drafts.map((r) => r.slug)).not.toContain("filter-active");
+
+    // Sicherstellen dass draft existiert
+    expect(draft.id).toBeTruthy();
+  });
+});