@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/legal-pages.md

@@ -0,0 +1,393 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/legal-pages. Do not edit. -->
+
+# legal-pages
+
+Auto-rendered Impressum + Datenschutzerklärung pages — template-resolver + legal-pages bundled features wired up with anonymousAccess for DACH-compliance.
+
+## README
+
+# Recipe: legal-pages + template-resolver
+
+DACH compliance stack: two opt-in bundled features wired up to
+auto-rendered Imprint + Privacy-Policy pages, with Markdown authoring
+and a boot check for required content.
+
+**What the recipe demonstrates:**
+- Activate both features in `runProdApp({ features: [...] })`
+- Required wirings: `anonymousAccess` + `extraContext.templateResolver`
+- Initial seed of the DE required blocks (Imprint + Privacy) for SYSTEM_TENANT
+- 5 integration tests proving end-to-end behavior
+
+## Layout
+
+```
+samples/recipes/legal-pages/
+├── package.json                # workspace deps
+├── README.md                   # this file
+└── src/
+    ├── feature.ts              # the two features re-exported for tests
+    └── __tests__/
+        └── feature.integration.test.ts  # 5 tests: routes + boot check
+```
+
+`feature.ts` is intentionally thin (re-export). In a real app this
+lives in `bin/main.ts` (see "Integration into a real app" below).
+
+## Run tests
+
+```bash
+# From the repo root:
+bun kumiko test all samples/recipes/legal-pages/
+```
+
+Expected output:
+```
+Test Files  1 passed (1)
+     Tests  5 passed (5)
+```
+
+When the tests are green:
+- template-resolver + legal-pages are compatible
+- Table schema is clean via `unsafeCreateEntityTable(stack.db, textBlockEntity)`
+- Routes are reachable via `stack.app.request("/legal/impressum")`
+- Markdown rendering produces valid HTML
+- Boot check correctly detects missing blocks
+
+## Integration into a real app
+
+Step-by-step for an existing Kumiko app (e.g.
+`samples/showcases/your-app/`):
+
+### 1. Activate features in `runProdApp`
+
+```typescript illustration
+// bin/main.ts
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import {
+  createTemplateResolverApi,
+  createTemplateResolverFeature,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+await runProdApp({
+  features: [
+    createTemplateResolverFeature(),
+    createLegalPagesFeature(),
+    /* ... your other features */
+  ],
+  // Required (1): routes run anonymous, need tenant resolution
+  anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+  // Required (2): boot check + internal lookup use ctx.templateResolver
+  extraContext: ({ db }) => ({
+    templateResolver: createTemplateResolverApi(db),
+  }),
+});
+```
+
+→ For host-based multi-tenant apps (like publicstatus.eu),
+`SYSTEM_TENANT_ID` always stays correct for legal-pages — the routes
+internally set `X-Tenant: SYSTEM_TENANT_ID` and override any
+host-based `tenantResolver`. This is the "1 app = X tenants = 1
+imprint" decision.
+
+### 2. Create the table
+
+```bash
+# In the app workspace:
+bunx kumiko-schema generate <name>    # detects text-block entity → SQL migration
+bunx kumiko-schema apply       # one-time (pre-deploy step in prod)
+```
+
+### 3. Initial seed of the required blocks
+
+A one-shot setup routine that runs on first boot or via the CLI:
+
+```typescript illustration
+// bin/seed-legal.ts
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createDb } from "@cosmicdrift/kumiko-framework/db";
+
+const db = createDb(process.env.DATABASE_URL!);
+
+await seedTextBlock(db, {
+  tenantId: SYSTEM_TENANT_ID,
+  slug: "imprint",
+  locale: "de",
+  title: "Impressum",
+  content: `## Angaben gemäß § 5 TMG
+
+**[Dein Name / GmbH]**
+
+[Strasse + Nr]
+[PLZ Ort]
+Deutschland
+
+## Kontakt
+
+E-Mail: [hello@example.com](mailto:hello@example.com)
+
+## Verantwortlich für den Inhalt nach § 55 Abs. 2 RStV
+
+[Dein Name, Adresse]`,
+});
+
+await seedTextBlock(db, {
+  tenantId: SYSTEM_TENANT_ID,
+  slug: "privacy",
+  locale: "de",
+  title: "Datenschutzerklärung",
+  content: `## 1. Verantwortlicher
+
+[Dein Name + Anschrift]
+
+## 2. Erhobene Daten
+
+[...]`,
+});
+```
+
+→ Templates for full legally-sound texts: e-recht24.de
+or datenschutz-generator.de by Dr. Schwenke.
+
+### 4. Visit the pages
+
+After the seed these URLs are immediately live:
+
+| URL | Content |
+|---|---|
+| `https://your-app.example/legal/impressum` | Impressum (DE) |
+| `https://your-app.example/legal/datenschutz` | Datenschutzerklärung (DE) |
+| `https://your-app.example/legal/imprint` | Imprint (EN, if seeded) |
+| `https://your-app.example/legal/privacy` | Privacy Policy (EN, if seeded) |
+
+→ Footer links are set per app (legal-pages does not ship a footer
+component — deliberately, every app has its own layout).
+
+### 5. Editing texts later (TenantAdmin maintenance)
+
+Through the standard write API:
+
+```typescript illustration
+await fetch("/api/write", {
+  method: "POST",
+  headers: { "Content-Type": "application/json", Authorization: `Bearer ${jwt}` },
+  body: JSON.stringify({
+    type: "template-resolver:write:set",
+    payload: { slug: "imprint", locale: "de", title: "Impressum", content: "..." },
+  }),
+});
+```
+
+ACL: `["TenantAdmin", "SystemAdmin"]`. Cache header `public, max-age=300`
+— visitors see updates within 5 minutes at most.
+
+## Boot-check behavior
+
+When the required blocks (`imprint/de` + `privacy/de`) are missing
+from SYSTEM_TENANT:
+
+| Mode | Behavior |
+|---|---|
+| `NODE_ENV=production` | App boot throws an error with a slug list — container exits |
+| otherwise (dev/test) | `console.warn` with a slug list, app starts anyway |
+
+→ Safety net: no production deploy without populated legal pages.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Route returns `503 legal page unavailable` | `anonymousAccess` not configured in `runProdApp` | Set `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` |
+| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db }) => ({ templateResolver: createTemplateResolverApi(db) })` |
+| Route returns `404 not configured` | Required block doesn't exist or has `content=null` | `seedTextBlock` with a content string |
+| Multi-tenant app: tenant subdomain shows an empty page | (Bug regression?) Routes should ALWAYS show SYSTEM_TENANT texts | The `legal-pages.integration.test.ts` test "SYSTEM_TENANT routing" covers this — should be green |
+| `<script>` tags in a Markdown body land 1:1 in the HTML | Deliberately accepted right now — see [legal-pages/README.md XSS section](../../../packages/bundled-features/src/legal-pages/README.md#xss--currently-not-secured-by-design) | DOMPurify is a Phase 2 once a multi-author setup arrives |
+
+## Cross-refs
+
+- [packages/bundled-features/src/template-resolver/README.md](../../../packages/bundled-features/src/template-resolver/README.md) — content store
+- [packages/bundled-features/src/legal-pages/README.md](../../../packages/bundled-features/src/legal-pages/README.md) — DACH compliance wrapper
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createTemplateResolverApi,
+  templateResourceEntity,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+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 {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { LEGAL_ROUTES, legalPagesFeature, templateResolverFeature } from "../feature";
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [templateResolverFeature, legalPagesFeature],
+    anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+    extraContext: ({ db }) => ({
+      templateResolver: createTemplateResolverApi(db),
+    }),
+  });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, templateResourceEntity);
+  await createEventsTable(db);
+
+  // Seed Pflicht-Blocks für SYSTEM_TENANT (DE Impressum + DSE)
+  await seedTextBlock(db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "imprint",
+    locale: "de",
+    title: "Impressum",
+    content: [
+      "## Angaben gemäß § 5 TMG",
+      "",
+      "**Alex Morgan**",
+      "Musterstraße 1",
+      "12345 Musterstadt",
+      "Deutschland",
+      "",
+      "## Kontakt",
+      "",
+      "E-Mail: [hello@example.com](mailto:hello@example.com)",
+    ].join("\n"),
+  });
+
+  await seedTextBlock(db, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug: "privacy",
+    locale: "de",
+    title: "Datenschutzerklärung",
+    content: [
+      "## 1. Verantwortlicher",
+      "",
+      "Alex Morgan, Musterstraße 1, 12345 Musterstadt.",
+      "",
+      "## 2. Erhobene Daten",
+      "",
+      "Diese App setzt **keine Tracking-Cookies** und kein Drittanbieter-Tracking ein.",
+      "",
+      "## 3. Deine Rechte (Art. 15-22 DSGVO)",
+      "",
+      "Auskunft, Berichtigung, Löschung, Einschränkung, Datenübertragbarkeit, Widerspruch.",
+    ].join("\n"),
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("legal-pages sample", () => {
+  test("alle LEGAL_ROUTES sind über stack.app erreichbar", async () => {
+    // Smoke-Test: jede Route gibt entweder 200 (gerendert) oder 404
+    // (Block fehlt). Nie 5xx — die Server-Pipeline läuft sauber durch.
+    for (const route of LEGAL_ROUTES) {
+      const res = await stack.app.request(route.path);
+      expect([200, 404]).toContain(res.status);
+    }
+  });
+
+  test("DE-Pflicht-Pages rendern HTML", async () => {
+    const imprint = await stack.app.request("/legal/impressum");
+    expect(imprint.status).toBe(200);
+    const imprintBody = await imprint.text();
+    expect(imprintBody).toContain("<!doctype html>");
+    expect(imprintBody).toContain("Alex Morgan");
+    expect(imprintBody).toContain("Musterstadt");
+
+    const privacy = await stack.app.request("/legal/datenschutz");
+    expect(privacy.status).toBe(200);
+    const privacyBody = await privacy.text();
+    expect(privacyBody).toContain("Tracking-Cookies");
+    expect(privacyBody).toContain("Datenschutzerklärung");
+  });
+
+  test("EN-Variante 404 (nicht geseedet) zeigt hilfreiche Meldung", async () => {
+    const res = await stack.app.request("/legal/imprint");
+    expect(res.status).toBe(404);
+    const body = await res.text();
+    expect(body).toContain("Tenant-Admin");
+  });
+
+  test("Markdown-Headings werden zu HTML-h2-Tags", async () => {
+    const res = await stack.app.request("/legal/impressum");
+    const body = await res.text();
+    expect(body).toContain("<h2>Angaben gemäß § 5 TMG</h2>");
+    expect(body).toContain("<strong>Alex Morgan</strong>");
+  });
+
+  test("Cache-Header zeigt 60s public-cache", async () => {
+    const res = await stack.app.request("/legal/impressum");
+    expect(res.headers.get("cache-control")).toBe("public, max-age=60, must-revalidate");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Legal-Pages Sample
+//
+// DACH-Apps (DE/AT/CH) sind verpflichtet ein Impressum (TMG/DDG §5) und
+// eine Datenschutzerklärung (DSGVO Art. 13) öffentlich zugänglich zu
+// haben. Das ist 1) für jede App identisch und 2) nervig manuell pro
+// App neu zu basteln.
+//
+// Lösung: zwei opt-in bundled-features kombinieren:
+//
+//  - `template-resolver` — der Content-Store (Entity `template-resource`,
+//    kind `text-block` mit slug+locale+title+content, scoped per Tenant).
+//    Auch nutzbar für FAQ, About, ToS, Marketing-Snippets — nicht
+//    legal-spezifisch.
+//
+//  - `legal-pages`   — opt-in-Wrapper darauf, der vier feste Public-
+//    Routes (`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`,
+//    `/legal/privacy`) registriert und Markdown→HTML rendered. Plus
+//    Boot-Check der in Production hart fehlt wenn die DE-Pflicht-Blocks
+//    fehlen.
+//
+// Tenant-Modell: 1 App = X Tenants = 1 Impressum. Alle Subdomains
+// teilen sich die SYSTEM_TENANT_ID-Version. Wer pro-Tenant-Impressums
+// braucht, muss sein eigenes Routing davorsetzen oder die by-slug-
+// query mit tenant-specific tenantId nutzen.
+//
+// Voraussetzungen für Production:
+//  - `anonymousAccess` muss in runProdApp/runDevApp konfiguriert sein
+//    (defaultTenantId = SYSTEM_TENANT_ID), sonst antworten die
+//    legal-pages-Routes mit 503
+//  - `extraContext.templateResolver = createTemplateResolverApi(db)` muss
+//    gewired sein, sonst wirft der Boot-Check mit Wiring-Hinweis
+//  - Beim ersten Boot müssen die TextBlocks geseedet sein —
+//    template-resolver/seeding `seedTextBlock` oder via API
+//    `template-resolver:write:set` mit TenantAdmin-Token
+
+import {
+  createLegalPagesFeature,
+  LEGAL_REQUIRED_BLOCKS,
+  LEGAL_ROUTES,
+} from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+
+// Beide Features aktivieren — template-resolver ist Foundation, legal-pages
+// requires sie. r.requires("template-resolver") greift automatisch im
+// legal-pages-Feature.
+export const templateResolverFeature = createTemplateResolverFeature();
+export const legalPagesFeature = createLegalPagesFeature();
+
+// Re-exports für Tests + andere Demos
+export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES };
+```