@cosmicdrift/kumiko-bundled-features 0.104.0 → 0.105.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.104.0",
+  "version": "0.105.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -82,6 +82,7 @@
     "./text-content/seeding": "./src/text-content/seeding.ts",
     "./text-content/web": "./src/text-content/web/index.ts",
     "./template-resolver": "./src/template-resolver/index.ts",
+    "./template-resolver/seeding": "./src/template-resolver/seeding.ts",
     "./template-resolver/testing": "./src/template-resolver/testing.ts",
     "./renderer-foundation": "./src/renderer-foundation/index.ts",
     "./legal-pages": "./src/legal-pages/index.ts",
@@ -92,11 +93,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.104.0",
-    "@cosmicdrift/kumiko-framework": "0.104.0",
-    "@cosmicdrift/kumiko-headless": "0.104.0",
-    "@cosmicdrift/kumiko-renderer": "0.104.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.104.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.105.1",
+    "@cosmicdrift/kumiko-framework": "0.105.1",
+    "@cosmicdrift/kumiko-headless": "0.105.1",
+    "@cosmicdrift/kumiko-renderer": "0.105.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.105.1",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

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

@@ -1,16 +1,26 @@
 import { describe, expect, test } from "bun:test";
-import { RendererError } from "../../renderer-foundation";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type RendererContext, RendererError } from "../../renderer-foundation";
 import { adaptToFoundation } from "../feature";
 
+const STUB_CTX: RendererContext = {
+  db: null as never,
+  registry: null as never,
+  tenantId: "11111111-1111-4111-8111-111111111111" as TenantId,
+};
+
 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" },
+    const res = await adaptToFoundation(
+      {
+        kind: "notification",
+        payload: {
+          template: "welcome",
+          variables: { title: "Welcome!", body: "Hello there" },
+        },
       },
-    });
+      STUB_CTX,
+    );
     expect(res.kind).toBe("notification");
     if (res.kind === "notification") {
       // simpleRenderer baut HTML mit title als header + body als section
@@ -21,26 +31,35 @@ describe("renderer-simple :: adaptToFoundation", () => {
   });
 
   test("leere variables → leerer body, kein crash", async () => {
-    const res = await adaptToFoundation({
-      kind: "notification",
-      payload: { template: "", variables: {} },
-    });
+    const res = await adaptToFoundation(
+      {
+        kind: "notification",
+        payload: { template: "", variables: {} },
+      },
+      STUB_CTX,
+    );
     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" },
-      }),
+      adaptToFoundation(
+        {
+          kind: "mail-html",
+          payload: { content: "test", contentFormat: "markdown" },
+        },
+        STUB_CTX,
+      ),
     ).rejects.toThrow(RendererError);
 
     try {
-      await adaptToFoundation({
-        kind: "document-pdf",
-        payload: { content: "test", contentFormat: "markdown" },
-      });
+      await adaptToFoundation(
+        {
+          kind: "document-pdf",
+          payload: { content: "test", contentFormat: "markdown" },
+        },
+        STUB_CTX,
+      );
       throw new Error("expected RendererError");
     } catch (e) {
       expect(e).toBeInstanceOf(RendererError);

package/src/renderer-simple/__tests__/template-resolver.integration.test.ts

@@ -0,0 +1,102 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import type { RendererContext } from "../../renderer-foundation";
+import { SYSTEM_TENANT_ID } from "../../template-resolver/constants";
+import { createTemplateResolverFeature } from "../../template-resolver/feature";
+import { templateResourceEntity, templateResourcesTable } from "../../template-resolver/table";
+import { adaptToFoundation } from "../feature";
+
+let stack: TestStack;
+let db: DbConnection;
+
+const TENANT_ID = "11111111-1111-4111-8111-111111111111" as TenantId;
+
+const templateResolverFeature = createTemplateResolverFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [templateResolverFeature] });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, templateResourceEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function rendererCtx(): RendererContext {
+  return { db, registry: stack.registry, tenantId: TENANT_ID };
+}
+
+async function seedPlainNotificationTemplate(content: string): Promise<void> {
+  await insertOne(db, templateResourcesTable, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "welcome-mail",
+    kind: "notification",
+    locale: "de",
+    scope: "system",
+    status: "active",
+    content,
+    contentFormat: "plain",
+    variableSchema: JSON.stringify({}),
+    linkedResources: JSON.stringify({}),
+    parentTemplateId: null,
+    createdBy: "test",
+    updatedBy: "test",
+  });
+}
+
+describe("renderer-simple :: template-resolver integration", () => {
+  test("resolves slug via template-resolver and merges runtime variables", async () => {
+    await seedPlainNotificationTemplate(
+      JSON.stringify({
+        header: "Template header",
+        sections: [{ text: "Template body" }],
+      }),
+    );
+
+    const res = await adaptToFoundation(
+      {
+        kind: "notification",
+        payload: {
+          template: "welcome-mail",
+          locale: "de",
+          variables: { header: "Runtime override" },
+        },
+      },
+      rendererCtx(),
+    );
+
+    expect(res.kind).toBe("notification");
+    if (res.kind === "notification") {
+      expect(res.html).toContain("Runtime override");
+      expect(res.html).toContain("Template body");
+      expect(res.html).not.toContain("Template header");
+    }
+  });
+
+  test("falls back to variables when slug is unknown in template-resolver", async () => {
+    const res = await adaptToFoundation(
+      {
+        kind: "notification",
+        payload: {
+          template: "password-reset",
+          variables: { title: "Reset", body: "Click the link" },
+        },
+      },
+      rendererCtx(),
+    );
+
+    expect(res.kind).toBe("notification");
+    if (res.kind === "notification") {
+      expect(res.html).toContain("Reset");
+      expect(res.html).toContain("Click the link");
+    }
+  });
+});

package/src/renderer-simple/feature.ts

@@ -1,5 +1,11 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { RendererError, type RenderRequest, type RenderResponse } from "../renderer-foundation";
+import {
+  type RendererContext,
+  RendererError,
+  type RenderRequest,
+  type RenderResponse,
+} from "../renderer-foundation";
+import { resolveNotificationVariables } from "./resolve-variables";
 import { simpleRenderer } from "./simple-renderer";
 
 // Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
@@ -9,7 +15,10 @@ import { simpleRenderer } from "./simple-renderer";
 // 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> {
+export async function adaptToFoundation(
+  req: RenderRequest,
+  ctx: RendererContext,
+): 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.
@@ -18,9 +27,10 @@ export async function adaptToFoundation(req: RenderRequest): Promise<RenderRespo
       "invalid_payload",
     );
   }
+  const variables = await resolveNotificationVariables(req, ctx);
   const html = await simpleRenderer.render({
     template: req.payload.template ?? "",
-    variables: req.payload.variables ?? {},
+    variables,
   });
   return { kind: "notification", html };
 }
@@ -36,6 +46,7 @@ export function createRendererSimpleFeature(): FeatureDefinition {
       recommended: false,
     });
     r.requires("renderer-foundation");
+    r.optionalRequires("template-resolver");
 
     r.useExtension("renderer", "simple", {
       kinds: ["notification"] as const,

package/src/renderer-simple/resolve-variables.ts

@@ -0,0 +1,55 @@
+import type { RendererContext, RenderRequest } from "../renderer-foundation";
+import {
+  createTemplateResolverApi,
+  FALLBACK_LOCALE,
+  TemplateNotFoundError,
+} from "../template-resolver";
+
+type NotificationRequest = Extract<RenderRequest, { kind: "notification" }>;
+
+/** Merge template-resolver content (plain JSON EmailTemplateData) with runtime variables. */
+export async function resolveNotificationVariables(
+  req: NotificationRequest,
+  ctx: RendererContext,
+): Promise<Readonly<Record<string, unknown>>> {
+  const variables = req.payload.variables ?? {};
+  const slug = req.payload.template?.trim();
+  if (!slug || req.payload.content || !ctx.db) {
+    return variables;
+  }
+
+  try {
+    const api = createTemplateResolverApi(ctx.db);
+    const locale = req.payload.locale ?? FALLBACK_LOCALE;
+    const resolved = await api.resolveTemplate({
+      tenantId: ctx.tenantId,
+      slug,
+      kind: "notification",
+      locale,
+    });
+    if (resolved.contentFormat === "plain") {
+      const base = parsePlainTemplateContent(resolved.content);
+      return { ...base, ...variables };
+    }
+    return { ...variables, body: resolved.content };
+  } catch (err) {
+    if (err instanceof TemplateNotFoundError) {
+      return variables;
+    }
+    throw err;
+  }
+}
+
+function parsePlainTemplateContent(content: string): Record<string, unknown> {
+  const trimmed = content.trim();
+  if (!trimmed) return {};
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // ponytail: non-JSON plain content becomes a single body section downstream
+  }
+  return { body: content };
+}

package/src/template-resolver/README.md

@@ -55,6 +55,23 @@ async function someHandler(ctx) {
 
 Wenn nichts gefunden → `TemplateNotFoundError`.
 
+## Boot-Seeding (System-Templates)
+
+```typescript
+import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+
+// runProdApp seeds — idempotent, default skip if slug exists
+await seedSystemTemplate(db, {
+  slug: "welcome-email",
+  kind: "notification",
+  locale: "de",
+  content: JSON.stringify({ header: "Willkommen", sections: [{ text: "…" }] }),
+  contentFormat: "plain",
+});
+```
+
+`ifExists: "update"` für autoritative Re-Seeds (z.B. nach Template-Content-Release).
+
 ## Admin-Workflows (Write-Handlers + Queries)
 
 | Handler | QN | Wer | Was |
@@ -66,7 +83,7 @@ Wenn nichts gefunden → `TemplateNotFoundError`.
 | `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.
+**SystemAdmin-Cross-Tenant für publish/archive/findById:** deferred (Task 8) — `upsertTenant` hat `tenantIdOverride` bereits; publish/archive brauchen das erst wenn ein Sysadmin-Panel fremde Tenant-Templates kuratiert. `ctx.db` ist tenant-scoped, fremde IDs → NotFound ohne Override.
 
 ## Status-Lifecycle
 
@@ -109,3 +126,5 @@ The harness checks `TemplateNotFoundError` propagation, locale-fallback, and (wh
 - 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__/seeding.integration.test.ts

@@ -0,0 +1,107 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTemplateResolverApi } from "../api";
+import { SYSTEM_TENANT_ID } from "../constants";
+import { createTemplateResolverFeature } from "../feature";
+import { seedSystemTemplate } from "../seeding";
+import { type TemplateResourceRow, templateResourceEntity, templateResourcesTable } from "../table";
+
+let stack: TestStack;
+
+const TENANT_ID = testTenantId(710) as TenantId;
+
+const feature = createTemplateResolverFeature();
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await unsafeCreateEntityTable(stack.db, templateResourceEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("seedSystemTemplate", () => {
+  test("legt System-Template an, resolveTemplate findet es für beliebigen Tenant", async () => {
+    const slug = `welcome-${crypto.randomUUID()}`;
+    await seedSystemTemplate(stack.db, {
+      slug,
+      kind: "notification",
+      locale: "de",
+      content: JSON.stringify({ header: "Willkommen", sections: [{ text: "Hallo" }] }),
+      contentFormat: "plain",
+    });
+
+    const api = createTemplateResolverApi(stack.db);
+    const resolved = await api.resolveTemplate({
+      tenantId: TENANT_ID,
+      slug,
+      kind: "notification",
+      locale: "de",
+    });
+    expect(resolved.content).toContain("Willkommen");
+    expect(resolved.scope).toBe("system");
+  });
+
+  test('ifExists="update" überschreibt content', async () => {
+    const slug = `incident-${crypto.randomUUID()}`;
+    await seedSystemTemplate(stack.db, {
+      slug,
+      kind: "notification",
+      locale: "en",
+      content: "v1",
+      contentFormat: "plain",
+    });
+    await seedSystemTemplate(stack.db, {
+      slug,
+      kind: "notification",
+      locale: "en",
+      content: "v2",
+      contentFormat: "plain",
+      ifExists: "update",
+    });
+
+    const row = await fetchOne<TemplateResourceRow>(stack.db, templateResourcesTable, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug,
+      kind: "notification",
+      locale: "en",
+    });
+    expect(row?.content).toBe("v2");
+    expect(row?.version).toBe(2);
+  });
+
+  test("default skip: zweiter Boot-Call ohne update ändert nichts", async () => {
+    const slug = `status-${crypto.randomUUID()}`;
+    await seedSystemTemplate(stack.db, {
+      slug,
+      kind: "notification",
+      locale: "de",
+      content: "original",
+      contentFormat: "plain",
+    });
+    await seedSystemTemplate(stack.db, {
+      slug,
+      kind: "notification",
+      locale: "de",
+      content: "would-overwrite",
+      contentFormat: "plain",
+    });
+
+    const row = await fetchOne<TemplateResourceRow>(stack.db, templateResourcesTable, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug,
+      kind: "notification",
+      locale: "de",
+    });
+    expect(row?.content).toBe("original");
+    expect(row?.version).toBe(1);
+  });
+});

package/src/template-resolver/seeding.ts

@@ -0,0 +1,96 @@
+// Boot-/Seed-Helper für App-Authors. Schreibt System-Templates (tenantId=
+// SYSTEM_TENANT_ID, scope=system, status=active) idempotent in die DB —
+// gleicher Projection-Pfad wie upsertSystem-Handler, ohne Access-Check.
+//
+// **Wann nutzen?** runProdApp-seeds / TenantCreated-Hooks die Welcome-,
+// Incident- oder Feature-Mail-Slugs installieren, damit renderer-simple
+// (oder mail-html) sie per template-resolver auflösen kann.
+//
+// Default ifExists="skip". `createSystemUser(SYSTEM_TENANT_ID)` als Actor —
+// bewusst nicht TestUsers (Prod-Seeds ≠ Test-Utilities).
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
+import type { ContentFormat, RenderKind } from "./constants";
+import { executor } from "./handlers/shared";
+import { type TemplateResourceRow, templateResourcesTable } from "./table";
+
+export type SeedSystemTemplateOptions = {
+  readonly slug: string;
+  readonly kind: RenderKind;
+  readonly locale: string;
+  readonly content: string;
+  readonly contentFormat: ContentFormat;
+  readonly variableSchema?: Record<string, unknown>;
+  readonly linkedResources?: Record<string, string>;
+  readonly parentTemplateId?: string | null;
+  readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
+};
+
+export async function seedSystemTemplate(
+  db: DbConnection,
+  opts: SeedSystemTemplateOptions,
+): Promise<{ id: string }> {
+  const tenantId = SYSTEM_TENANT_ID as TenantId;
+  const by = opts.by ?? createSystemUser(tenantId);
+  const tdb = createTenantDb(db, tenantId, "system");
+
+  const existing = (await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+    tenantId,
+    slug: opts.slug,
+    kind: opts.kind,
+    locale: opts.locale,
+  })) as { id: string; version: number } | null;
+
+  const variableSchema = JSON.stringify(opts.variableSchema ?? {});
+  const linkedResources = JSON.stringify(opts.linkedResources ?? {});
+  const parentTemplateId = opts.parentTemplateId ?? null;
+
+  const rowFields = {
+    slug: opts.slug,
+    kind: opts.kind,
+    locale: opts.locale,
+    content: opts.content,
+    contentFormat: opts.contentFormat,
+    variableSchema,
+    linkedResources,
+    scope: "system" as const,
+    parentTemplateId,
+    status: "active" as const,
+  };
+
+  return runEventStoreSeed({
+    existing,
+    ifExists: opts.ifExists,
+    create: async () => {
+      const result = await executor.create({ ...rowFields, tenantId }, by, tdb);
+      if (!result.isSuccess) {
+        throw new Error(`seedSystemTemplate create failed: ${JSON.stringify(result)}`);
+      }
+      const data = result.data as Partial<TemplateResourceRow>;
+      if (data.id === undefined) {
+        throw new Error("seedSystemTemplate: executor.create did not return an id");
+      }
+      return { id: String(data.id) };
+    },
+    update: async (row) => {
+      const result = await executor.update(
+        { id: row.id, version: row.version, changes: rowFields },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedSystemTemplate update failed: ${JSON.stringify(result)}`);
+      }
+      return { id: String(row.id) };
+    },
+  });
+}