@cosmicdrift/kumiko-bundled-features 0.229.0 → 0.230.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.229.0",
+  "version": "0.230.0",
   "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>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.229.0",
-    "@cosmicdrift/kumiko-framework": "0.229.0",
-    "@cosmicdrift/kumiko-headless": "0.229.0",
-    "@cosmicdrift/kumiko-renderer": "0.229.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.229.0",
-    "@cosmicdrift/kumiko-types": "0.229.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.230.0",
+    "@cosmicdrift/kumiko-framework": "0.230.0",
+    "@cosmicdrift/kumiko-headless": "0.230.0",
+    "@cosmicdrift/kumiko-renderer": "0.230.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.230.0",
+    "@cosmicdrift/kumiko-types": "0.230.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.229.0",
-    "@cosmicdrift/kumiko-locale-es": "0.229.0"
+    "@cosmicdrift/kumiko-locale-de": "0.230.0",
+    "@cosmicdrift/kumiko-locale-es": "0.230.0"
   }
 }

package/src/legal-pages/README.md

@@ -57,6 +57,8 @@ See [template-resolver/README.md](../template-resolver/README.md).
 
 ## Routes
 
+**Default** (DACH: DE required, EN optional):
+
 | Path | Slug + locale | Title fallback (when block empty) |
 |---|---|---|
 | `GET /legal/impressum` | `imprint` / `de` | "Impressum" |
@@ -75,22 +77,57 @@ directly and render themselves.
 
 ---
 
+### Non-DACH apps: custom routes + required blocks
+
+The default four routes and the two DE required blocks
+(`LEGAL_ROUTES`/`LEGAL_REQUIRED_BLOCKS`) are DACH conventions, not a
+hard constraint. An app with a different default language, or one
+that needs an additional page (terms/AGB), passes its own lists:
+
+```typescript
+createLegalPagesFeature({
+  routes: [
+    { path: "/legal/aviso-legal", slug: "imprint", lang: "es", titleFallback: "Aviso legal" },
+    { path: "/legal/privacidad", slug: "privacy", lang: "es", titleFallback: "Política de privacidad" },
+    { path: "/legal/terminos", slug: "terms", lang: "es", titleFallback: "Términos y condiciones" },
+  ],
+  requiredBlocks: [{ slug: "imprint", lang: "es" }, { slug: "privacy", lang: "es" }],
+})
+```
+
+`slug` is free-form — it only has to match the `slug` you seed the
+text-block under via `template-resolver`. `requiredBlocks` drives the
+boot check (see below); routes not listed there stay optional and
+just 404 until seeded, same as the DACH default.
+
+Validated once at feature-build time (fails app startup, not a
+request): no two routes may share a `path`, every route needs a
+non-empty `path`/`slug`/`lang`, and every `path` must start with `/`.
+An empty `routes` array is allowed — the boot check alone, no public
+routes.
+
+---
+
 ## Boot check
 
-`r.job` with `runOnBoot: true` checks at app start whether the DE
-required blocks exist in SYSTEM_TENANT:
+`r.job` with `runOnBoot: true` checks at app start whether the
+required blocks exist in SYSTEM_TENANT. **Default** (DACH):
 
 | Slug + locale | What happens when missing |
 |---|---|
 | `imprint` / `de` | **Production:** `throw new Error(...)` blocks app start. **Dev:** `ctx.log.warn(...)` |
 | `privacy` / `de` | as above |
 
-EN versions are **not** boot-fail-relevant (`LEGAL_OPTIONAL_BLOCKS`).
+EN versions are **not** boot-fail-relevant by default (`LEGAL_OPTIONAL_BLOCKS`).
 Routes return `404` if an EN block is missing.
 
-→ Apps that activate the feature must seed both DE blocks before a
-production deploy — either via a bootstrap script (`seedTextBlock`) or
-manually via the TenantAdmin API.
+→ Apps that activate the feature with the default config must seed
+both DE blocks before a production deploy — either via a bootstrap
+script (`seedTextBlock`) or manually via the TenantAdmin API.
+
+→ Apps with a `requiredBlocks` override (see above) get the same
+production-hard-fail/dev-warn behavior for their own slug/lang list
+instead — the DE blocks are not checked when `requiredBlocks` is set.
 
 ---
 

package/src/legal-pages/__tests__/legal-pages.integration.test.ts

@@ -328,6 +328,88 @@ describe("legal-pages :: wrapLayout erhält route.slug (alt-lang-switch-regressi
   });
 });
 
+describe("legal-pages :: configurable routes/requiredBlocks (non-DACH apps)", () => {
+  test("custom route (es) serves the seeded Spanish text-block", async () => {
+    const esStack = await setupTestStack({
+      features: [
+        createTemplateResolverFeature(),
+        createLegalPagesFeature({
+          routes: [
+            {
+              path: "/legal/aviso-legal",
+              slug: "imprint",
+              lang: "es",
+              titleFallback: "Aviso legal",
+            },
+          ],
+          requiredBlocks: [{ slug: "imprint", lang: "es" }],
+        }),
+      ],
+      anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+      extraContext: ({ db }) => ({
+        templateResolver: createTemplateResolverApi(db),
+      }),
+    });
+    try {
+      await unsafeCreateEntityTable(esStack.db, templateResourceEntity);
+      await createEventsTable(esStack.db);
+      await seedTextBlock(esStack.db, {
+        tenantId: SYSTEM_TENANT_ID,
+        slug: "imprint",
+        locale: "es",
+        title: "Aviso legal",
+        content: "## Datos del titular\n\n**Marc Frost**",
+      });
+
+      const res = await esStack.app.request("/legal/aviso-legal");
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toContain('lang="es"');
+      expect(body).toContain("<title>Aviso legal</title>");
+      expect(body).toContain("Datos del titular");
+
+      // Default DACH routes are gone once `routes` is overridden.
+      const dachRes = await esStack.app.request("/legal/impressum");
+      expect(dachRes.status).toBe(404);
+    } finally {
+      await esStack.cleanup();
+    }
+  });
+
+  test("createLegalPagesFeature throws on duplicate route path", () => {
+    expect(() =>
+      createLegalPagesFeature({
+        routes: [
+          { path: "/legal/aviso-legal", slug: "imprint", lang: "es", titleFallback: "Aviso" },
+          { path: "/legal/aviso-legal", slug: "privacy", lang: "es", titleFallback: "Privacidad" },
+        ],
+      }),
+    ).toThrow(/duplicate route path/);
+  });
+
+  test("createLegalPagesFeature throws on empty path/slug/lang", () => {
+    expect(() =>
+      createLegalPagesFeature({
+        routes: [{ path: "", slug: "imprint", lang: "es", titleFallback: "Aviso" }],
+      }),
+    ).toThrow(/missing a required field/);
+  });
+
+  test("createLegalPagesFeature throws when path doesn't start with /", () => {
+    expect(() =>
+      createLegalPagesFeature({
+        routes: [
+          { path: "legal/aviso-legal", slug: "imprint", lang: "es", titleFallback: "Aviso" },
+        ],
+      }),
+    ).toThrow(/must start with/);
+  });
+
+  test("empty routes array is allowed (boot-check only, no public routes)", () => {
+    expect(() => createLegalPagesFeature({ routes: [] })).not.toThrow();
+  });
+});
+
 describe("legal-pages :: runLegalPagesBootCheck (direct unit-tests)", () => {
   // Direkter Test der Boot-Check-Logik mit constructed ctx-Objects —
   // keine JobRunner-Coupling, keine Test-Stacks. Das ist die echte
@@ -471,4 +553,98 @@ describe("legal-pages :: runLegalPagesBootCheck (direct unit-tests)", () => {
       expect(call.tenantId).toBe(SYSTEM_TENANT_ID);
     }
   });
+
+  test("custom requiredBlock (es privacy) fehlt → throws in production", async () => {
+    const { api } = fakeTemplateResolver([
+      { slug: "imprint", lang: "es", title: "I", content: "x" },
+    ]);
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      await expect(
+        runLegalPagesBootCheck({ templateResolver: api }, [
+          { slug: "imprint", lang: "es" },
+          { slug: "privacy", lang: "es" },
+        ]),
+      ).rejects.toThrow(/Boot-Validation failed.*privacy\/es/s);
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
+
+  test("custom requiredBlock (es privacy) vorhanden → kein throw", async () => {
+    const { api } = fakeTemplateResolver([
+      { slug: "imprint", lang: "es", title: "I", content: "x" },
+      { slug: "privacy", lang: "es", title: "P", content: "x" },
+    ]);
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      await expect(
+        runLegalPagesBootCheck({ templateResolver: api }, [
+          { slug: "imprint", lang: "es" },
+          { slug: "privacy", lang: "es" },
+        ]),
+      ).resolves.toBeUndefined();
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
+
+  test("DE-Blocks fehlen, custom requiredBlocks (es) konfiguriert + geseedet → kein Fail", async () => {
+    // Proves the boot check only looks at the configured requiredBlocks,
+    // not hardcoded LEGAL_REQUIRED_BLOCKS (DE) — required for apps with a
+    // default language other than DE.
+    const { api } = fakeTemplateResolver([
+      { slug: "imprint", lang: "es", title: "I", content: "x" },
+      { slug: "privacy", lang: "es", title: "P", content: "x" },
+    ]);
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      await expect(
+        runLegalPagesBootCheck({ templateResolver: api }, [
+          { slug: "imprint", lang: "es" },
+          { slug: "privacy", lang: "es" },
+        ]),
+      ).resolves.toBeUndefined();
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
+
+  test("createLegalPagesFeature threads requiredBlocks into the boot-check job, not the DACH default", async () => {
+    // Goes through the actual job registered by createLegalPagesFeature
+    // (not a direct runLegalPagesBootCheck call, unlike the tests above) —
+    // proves the `requiredBlocks` option reaches the job closure. DE blocks
+    // are seeded but the feature is built with an es-only requiredBlocks
+    // list: if the job still checked the hardcoded LEGAL_REQUIRED_BLOCKS
+    // (DE), this would resolve instead of rejecting on the missing es block.
+    const { api } = fakeTemplateResolver([
+      { slug: "imprint", lang: "de", title: "I", content: "x" },
+      { slug: "privacy", lang: "de", title: "P", content: "x" },
+    ]);
+    const feature = createLegalPagesFeature({
+      requiredBlocks: [{ slug: "privacy", lang: "es" }],
+    });
+    const job = feature.jobs["legal-pages-boot-check"];
+    if (!job) throw new Error("legal-pages-boot-check job not registered");
+    // @cast-boundary test-only — job.handler is typed against the full
+    // JobContext; runLegalPagesBootCheck only reads templateResolver off it.
+    const handler = job.handler as unknown as (
+      payload: Record<string, unknown>,
+      ctx: { templateResolver: TemplateResolverApi },
+    ) => Promise<void>;
+    const originalEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      await expect(handler({}, { templateResolver: api })).rejects.toThrow(/privacy\/es/);
+    } finally {
+      if (originalEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalEnv;
+    }
+  });
 });

package/src/legal-pages/constants.ts

@@ -2,6 +2,23 @@
 // Feature name
 export const LEGAL_PAGES_FEATURE = "legal-pages" as const;
 
+// Shape of one public route entry — the type behind LEGAL_ROUTES, exported
+// so non-DACH apps can type their own `routes` option (e.g. a Spanish-
+// default app with an additional AGB/terms page).
+export type LegalPageRoute = {
+  readonly path: string;
+  readonly slug: string;
+  readonly lang: string;
+  readonly titleFallback: string;
+};
+
+// Shape of one boot-check-required block — the type behind
+// LEGAL_REQUIRED_BLOCKS, exported for the same reason as LegalPageRoute.
+export type LegalRequiredBlock = {
+  readonly slug: string;
+  readonly lang: string;
+};
+
 // Required slugs that must exist as text-blocks for production-boot.
 // Pro Sprache + Slug eine Pflicht-Kombo. Wer mehr Sprachen will, ergänzt
 // die Liste — Boot-Check wird dynamisch aus der Liste generiert.

package/src/legal-pages/feature.ts

@@ -10,7 +10,12 @@ import {
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { cachedSecurePageResponse } from "../page-render";
-import { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES } from "./constants";
+import {
+  LEGAL_REQUIRED_BLOCKS,
+  LEGAL_ROUTES,
+  type LegalPageRoute,
+  type LegalRequiredBlock,
+} from "./constants";
 import { renderMarkdownToHtml, wrapInLayout } from "./markdown";
 
 // QN-Konstante als dokumentierter Public-Contract des template-resolver-
@@ -32,11 +37,13 @@ type TextBlockQueryResult = {
 // 60s-shared-cache saves the origin-revalidate roundtrip; legal-content edits are live within 60s.
 const PUBLIC_PAGE_CACHE = { kind: "revalidate", maxAgeSeconds: 60 } as const;
 
-// legal-pages — Opt-in-Wrapper um template-resolver (kind text-block) für DACH-Compliance.
-// Liefert vier feste Public-HTML-Routes (/legal/impressum,
-// /legal/datenschutz, /legal/imprint, /legal/privacy) mit
-// Markdown→HTML-Rendering und einen Boot-Check der in Production hart
-// fehlt wenn die DE-Pflicht-Blocks nicht geseedet sind.
+// legal-pages — opt-in wrapper around template-resolver (kind text-block).
+// Default config ships four DACH public HTML routes (/legal/impressum,
+// /legal/datenschutz, /legal/imprint, /legal/privacy) with Markdown-to-HTML
+// rendering and a boot check that hard-fails in production when the DE
+// required blocks aren't seeded. `routes`/`requiredBlocks` are configurable
+// (see LegalPagesOptions) for apps with a different default language or
+// additional pages (e.g. terms/AGB).
 //
 // Cross-Feature-Decoupling:
 //   • Routes nutzen app.fetch zu "/api/query" mit dem QN-string
@@ -55,7 +62,7 @@ export type LegalPagesWrapLayout = (opts: {
   readonly title: string;
   readonly bodyHtml: string;
   readonly lang: string;
-  readonly slug?: (typeof LEGAL_ROUTES)[number]["slug"];
+  readonly slug?: string;
 }) => string;
 
 export type LegalPagesOptions = {
@@ -64,13 +71,48 @@ export type LegalPagesOptions = {
    *  Marketing-Layout (Header/Footer/Theme) auch um Legal-Body legen
    *  wollen, übergeben hier ihre Render-Function. */
   readonly wrapLayout?: LegalPagesWrapLayout;
+  /** Public HTML routes to register. Default: LEGAL_ROUTES (DACH: DE+EN
+   *  imprint/privacy). Non-DACH apps (other default language, additional
+   *  pages like terms/AGB) pass their own list instead. Validated at
+   *  feature-build time: no duplicate `path`, no empty field, every `path`
+   *  starts with "/". An empty array is allowed (boot-check only, no
+   *  public routes). */
+  readonly routes?: readonly LegalPageRoute[];
+  /** Slug+lang combos the boot check requires to be seeded in
+   *  SYSTEM_TENANT. Default: LEGAL_REQUIRED_BLOCKS (`imprint/de`,
+   *  `privacy/de`). Apps whose routes use a different slug/lang set
+   *  (e.g. Spanish-default) pass their own list here. */
+  readonly requiredBlocks?: readonly LegalRequiredBlock[];
 };
 
+// Validated once at feature-build time (not per-request) so a config typo
+// fails app startup instead of surfacing as a confusing 404 later.
+function validateRoutes(routes: readonly LegalPageRoute[]): void {
+  const seenPaths = new Set<string>();
+  for (const route of routes) {
+    if (!route.path || !route.slug || !route.lang) {
+      throw new Error(
+        `legal-pages: route is missing a required field (path/slug/lang): ${JSON.stringify(route)}`,
+      );
+    }
+    if (!route.path.startsWith("/")) {
+      throw new Error(`legal-pages: route path must start with "/", got "${route.path}"`);
+    }
+    if (seenPaths.has(route.path)) {
+      throw new Error(`legal-pages: duplicate route path "${route.path}"`);
+    }
+    seenPaths.add(route.path);
+  }
+}
+
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
+  const routes = opts.routes ?? LEGAL_ROUTES;
+  const requiredBlocks = opts.requiredBlocks ?? LEGAL_REQUIRED_BLOCKS;
+  validateRoutes(routes);
   return defineFeature("legal-pages", (r) => {
     r.describe(
-      "Opt-in wrapper around `template-resolver` text-blocks that registers four public HTML routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required DE blocks (`imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.templateResolver` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `template-resolver:query:by-slug` directly.",
+      "Opt-in wrapper around `template-resolver` text-blocks that registers public HTML routes (default: `/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required blocks (default: `imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Both are configurable via `routes`/`requiredBlocks` for apps with a different default language or additional pages. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.templateResolver` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `template-resolver:query:by-slug` directly.",
     );
     r.uiHints({
       displayLabel: "Legal Pages",
@@ -79,8 +121,8 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
     });
     r.requires("template-resolver");
 
-    // 4 Public-HTML-Routes
-    for (const route of LEGAL_ROUTES) {
+    // Public HTML routes (default: 4 DACH routes, configurable via opts.routes)
+    for (const route of routes) {
       r.httpRoute({
         method: "GET",
         path: route.path,
@@ -169,7 +211,7 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
         runOnBoot: true,
         runIn: "api",
       },
-      async (_payload, ctx) => runLegalPagesBootCheck(ctx),
+      async (_payload, ctx) => runLegalPagesBootCheck(ctx, requiredBlocks),
     );
 
     return {};
@@ -192,14 +234,17 @@ export type LegalPagesBootCheckCtx = {
 // nicht gewired ist (Hinweis auf fehlenden extraContext). Wirft Error
 // in NODE_ENV=production wenn Pflicht-Blocks fehlen, sonst log.warn.
 // Logged log.info wenn alles vorhanden ist (kein silent-skip).
-export async function runLegalPagesBootCheck(ctx: LegalPagesBootCheckCtx): Promise<void> {
+export async function runLegalPagesBootCheck(
+  ctx: LegalPagesBootCheckCtx,
+  requiredBlocks: readonly LegalRequiredBlock[] = LEGAL_REQUIRED_BLOCKS,
+): Promise<void> {
   const templateResolver: TemplateResolverApi = requireTemplateResolver(
     ctx,
     "legal-pages-boot-check",
   );
   const missing: { slug: string; lang: string }[] = [];
 
-  for (const required of LEGAL_REQUIRED_BLOCKS) {
+  for (const required of requiredBlocks) {
     const block = await templateResolver.findExact({
       tenantId: SYSTEM_TENANT_ID,
       slug: required.slug,

package/src/legal-pages/index.ts

@@ -3,7 +3,9 @@ export {
   LEGAL_PAGES_FEATURE,
   LEGAL_REQUIRED_BLOCKS,
   LEGAL_ROUTES,
+  type LegalPageRoute,
   LegalPagesErrors,
+  type LegalRequiredBlock,
 } from "./constants";
 export {
   createLegalPagesFeature,