@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/lane-routing/src/feature.ts

@@ -0,0 +1,106 @@
+// Lane-Routing Sample
+//
+// Shows `r.job({ runIn: "worker" })` end-to-end: an HTTP write emits an
+// event, the event fans out to two worker-lane jobs via BullMQ, and the
+// jobs actually execute on the worker lane (kumiko-jobs-worker queue).
+//
+// Deploy-shape: any of the three entrypoints. The test uses
+// createAllInOneEntrypoint so the Single Integration-Test covers the full
+// path without having to coordinate two processes.
+
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// In-memory collectors so the integration-test can assert both jobs ran
+// and got the right payload. A real app would do DB writes, HTTP calls,
+// PDF rendering, mail sending — whatever the side-effect is, it's
+// opaque to the framework.
+export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
+export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
+
+// Entity-Dekl sichert den qualified-name-Prefix "orders:write:order:create"
+// für den Write-Handler unten und damit den Job-Trigger auf diesem Event.
+// Persistenz passiert im Custom-Handler nicht (id ist hardcoded für den
+// Sample-Test) — in einer echten App würde ein entityWriteHandler in die DB
+// schreiben.
+const orderEntity = createEntity({
+  table: "read_orders",
+  fields: {
+    customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    amount: createNumberField({ required: true }),
+  },
+});
+
+export function createLaneRoutingFeature(): FeatureDefinition {
+  return defineFeature("orders", (r) => {
+    r.entity("order", orderEntity);
+
+    // Write handler — runs in the API process (or wherever the command
+    // lands). Event "orders:write:order:create" is the auto-generated
+    // write-event both jobs trigger on.
+    r.writeHandler(
+      "order:create",
+      z.object({
+        customerName: z.string().min(1),
+        amount: z.number().positive(),
+      }),
+      async (event) => ({
+        isSuccess: true as const,
+        data: {
+          id: 1,
+          customerName: event.payload.customerName,
+          amount: event.payload.amount,
+        },
+      }),
+      {
+        access: {
+          openToAll: {
+            reason:
+              "demo recipe: any signed-in user may place an order; the handler is a stub with no persistence",
+          },
+        },
+      },
+    );
+
+    // Receipt-rendering: heavy CPU work. Pinned to `worker` so the
+    // BullMQ consumer on the API process never picks it up — even if the
+    // API happens to run runLocalJobs for something else. `runIn` is the
+    // Welle-2.6 contract that makes this stable across deploy shapes.
+    r.job(
+      "render-receipt",
+      {
+        trigger: { on: "orders:write:order:create" },
+        runIn: "worker",
+      },
+      async (payload) => {
+        renderedReceipts.push({
+          customerName: payload["customerName"] as string,
+          amount: payload["amount"] as number,
+        });
+      },
+    );
+
+    // Confirmation-mail: external I/O. Also worker-lane. Both jobs fan
+    // out from the same event in parallel — BullMQ handles their order
+    // independently.
+    r.job(
+      "send-confirmation",
+      {
+        trigger: { on: "orders:write:order:create" },
+        runIn: "worker",
+      },
+      async (payload) => {
+        sentConfirmations.push({
+          customerName: payload["customerName"] as string,
+          amount: payload["amount"] as number,
+        });
+      },
+    );
+  });
+}

package/samples/recipes/ledger-banking/README.md

@@ -0,0 +1,47 @@
+# Ledger Banking
+
+Model bank accounts and transfers on the `ledger` primitive. This is the
+simplest double-entry case: every account is an `asset`, a transfer is **one
+balanced transaction**, and a balance is a **pure query** over the postings —
+never a stored field you keep in sync.
+
+## What it shows
+
+A transfer moves money between two bank accounts as a single balanced transaction, and every balance is a pure query over the postings rather than a stored field you keep in sync.
+
+- **A transfer is one transaction, not two updates** — moving €200 from
+  checking to savings is a single `ledger:write:create-transaction` that debits
+  savings (`+20000`) and credits checking (`−20000`). The two lines sum to 0,
+  which is what makes the entry _balanced_; the framework rejects anything else.
+- **Balances are derived, never stored** — there is no `balance` column on an
+  account. `ledger:query:report:balances` sums the postings on the fly and
+  applies each account's natural sign (asset = debit-normal).
+- **The trial balance is the safety net** — because every entry sums to 0, the
+  sum of _all_ postings is always 0. The flow asserts it after the transfers:
+  if it ever drifts, the books are inconsistent.
+- **Cents are signed integers** — amounts are integer minor units; `+` is a
+  debit, `−` is a credit. No floats, no rounding drift.
+
+## The banking flow
+
+The flow below is embedded from `usage.ts` and is run end-to-end against the
+real dispatcher + DB by this recipe's integration test (`the documented
+bankingFlow …`):
+
+```ts file=<rootDir>/_samples/recipes-ledger-banking/src/usage.ts
+```
+
+## Why no `feature.ts`?
+
+Unlike most recipes, banking mounts no host feature — the `ledger` bundle _is_
+the host. Accounts and transactions are its own entities, so the recipe just
+dispatches `ledger:*` handlers. Mount it once with `createLedgerFeature()` and
+the whole chart of accounts + journal is available.
+
+## Run
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```

package/samples/recipes/ledger-banking/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-ledger-banking",
+  "description": "Bank accounts + transfers on the ledger primitive — balances are pure queries, never stored.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/ledger-banking/src/usage.ts

@@ -0,0 +1,86 @@
+// Ledger Banking — money on accounts, moved by balanced transactions.
+//
+// Banking is the simplest double-entry case: each bank account is an `asset`,
+// and a transfer is ONE transaction that debits the receiving account (+) and
+// credits the sending one (−). The two lines sum to 0 — that is what makes the
+// entry "balanced". No balance is ever stored; it's a pure query over the
+// postings (ledger:query:report:balances).
+//
+// This recipe's integration test runs `bankingFlow` below against the real
+// dispatcher + DB.
+
+// The bundle exports its qualified handler/query names — use them instead of
+// hardcoding the wire strings.
+import {
+  type AccountType,
+  LedgerHandlers,
+  LedgerQueries,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+
+// The minimal surface the flow needs from a host dispatcher. An app's client
+// satisfies this; the integration test adapts the test stack to it.
+export type LedgerClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+type BalancesReport = {
+  accounts: Array<{ id: string; name: string; balance: number }>;
+  trialBalance: number;
+};
+
+// Open an account in the tenant's chart of accounts → returns its id.
+async function openAccount(client: LedgerClient, name: string, type: AccountType): Promise<string> {
+  const { id } = await client.write<{ id: string }>(LedgerHandlers.createAccount, { name, type });
+  return id;
+}
+
+// A transfer is one balanced transaction: debit the receiver (+amount), credit
+// the sender (−amount). Amounts are signed integer minor units (cents).
+async function transfer(
+  client: LedgerClient,
+  opts: { from: string; to: string; amount: number; description: string; date: string },
+): Promise<void> {
+  await client.write(LedgerHandlers.createTransaction, {
+    date: opts.date,
+    description: opts.description,
+    lines: [
+      { accountId: opts.to, amount: opts.amount },
+      { accountId: opts.from, amount: -opts.amount },
+    ],
+  });
+}
+
+// Fund a checking account from equity, move €200 of it to savings, then read
+// the closing balances back. Returns the balances + the trial balance (Σ of all
+// raw postings — 0 on a consistent ledger).
+export async function bankingFlow(client: LedgerClient) {
+  const opening = await openAccount(client, "Anfangsbestand", "equity");
+  const checking = await openAccount(client, "Girokonto", "asset");
+  const savings = await openAccount(client, "Sparkonto", "asset");
+
+  await transfer(client, {
+    from: opening,
+    to: checking,
+    amount: 100000,
+    description: "Anfangsbestand Girokonto",
+    date: "2026-01-01",
+  });
+
+  await transfer(client, {
+    from: checking,
+    to: savings,
+    amount: 20000,
+    description: "Sparrate Januar",
+    date: "2026-01-05",
+  });
+
+  const report = await client.query<BalancesReport>(LedgerQueries.reportBalances, {});
+  const balanceOf = (id: string) => report.accounts.find((a) => a.id === id)?.balance ?? 0;
+
+  return {
+    checking: balanceOf(checking), // 80000 — €1,000 funded − €200 moved out
+    savings: balanceOf(savings), // 20000 — €200 moved in
+    trialBalance: report.trialBalance, // 0 — the books are consistent
+  };
+}

package/samples/recipes/ledger-invoicing/README.md

@@ -0,0 +1,54 @@
+# Ledger Invoicing
+
+Model accrual invoicing (Rechnungswesen) on the `ledger` primitive. Issuing an
+invoice and receiving its payment are **two separate transactions**, and
+revenue is recognised when the invoice is **issued** — not when the cash
+arrives. This is the difference between banking (cash moves) and accounting
+(obligations are recorded as they arise).
+
+## What it shows
+
+Accrual accounting recognises revenue when an invoice is issued, not when the cash arrives: the invoice and its payment are two separate transactions, VAT is held as a liability, and the receivable clears to zero once paid.
+
+- **Accrual: revenue at invoice time** — issuing the invoice debits Forderungen
+  (accounts receivable) and credits Erlöse (income). The revenue is on the P&L
+  immediately; the flow asserts it via `report:income-statement` _before_ any
+  payment exists.
+- **VAT is a liability, not income** — the gross €1,190 splits into €1,000 net
+  revenue and €190 Umsatzsteuer. The VAT is money you owe the tax office, so it
+  lands on a `liability` account, never inflating revenue.
+- **The receivable has a lifecycle** — it's raised at the gross amount on
+  invoice and cleared to 0 on payment (debit Bank / credit Forderungen). An open
+  receivable balance _is_ your "unpaid invoices" total, with no extra bookkeeping.
+- **Reports re-derive, payment doesn't double-count income** — booking the
+  payment moves cash and settles the receivable; it touches no income account,
+  so revenue stays €1,000.
+
+## The invoicing flow
+
+The flow below is embedded from `usage.ts` and is run end-to-end against the
+real dispatcher + DB by this recipe's integration test (`the documented
+invoicingFlow …`):
+
+```ts file=<rootDir>/_samples/recipes-ledger-invoicing/src/usage.ts
+```
+
+## Banking vs. invoicing
+
+Both recipes use the same primitive — accounts + balanced transactions — but
+record different things:
+
+| | [ledger-banking](../ledger-banking/) | ledger-invoicing |
+|---|---|---|
+| Accounts | all `asset` (bank accounts) | `asset` + `income` + `liability` |
+| A transaction is… | a transfer (cash moves) | an obligation (invoice) or its settlement |
+| Revenue recognised | n/a | at invoice time (accrual) |
+| Reports surfaced | balances | balances + P&L |
+
+## Run
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```

package/samples/recipes/ledger-invoicing/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-ledger-invoicing",
+  "description": "Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/ledger-invoicing/src/usage.ts

@@ -0,0 +1,93 @@
+// Ledger Invoicing — accrual accounting (Rechnungswesen).
+//
+// Issuing an invoice and receiving its payment are TWO separate transactions,
+// and revenue is recognised when the invoice is ISSUED (accrual), not when the
+// cash arrives:
+//
+//   1. Issue:   debit Forderungen (asset, accounts receivable) for the GROSS
+//               amount, credit Erlöse (income) for the NET and Umsatzsteuer
+//               (liability) for the VAT. Revenue hits the P&L now.
+//   2. Payment: debit Bank (asset), credit Forderungen — the receivable nets
+//               back to 0 once the customer has paid.
+//
+// This recipe's integration test runs `invoicingFlow` below against the real
+// dispatcher + DB.
+
+import {
+  type AccountType,
+  LedgerHandlers,
+  LedgerQueries,
+} from "@cosmicdrift/kumiko-bundled-features/ledger";
+
+export type LedgerClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+type BalancesReport = {
+  accounts: Array<{ id: string; name: string; balance: number }>;
+  trialBalance: number;
+};
+
+async function openAccount(client: LedgerClient, name: string, type: AccountType): Promise<string> {
+  const { id } = await client.write<{ id: string }>(LedgerHandlers.createAccount, { name, type });
+  return id;
+}
+
+// Issue an invoice, observe that the revenue is already on the P&L before any
+// cash moves, then book the incoming payment. Returns the figures the test
+// asserts: accrual revenue, the cleared receivable, cash in, VAT owed.
+export async function invoicingFlow(client: LedgerClient) {
+  const receivables = await openAccount(client, "Forderungen", "asset");
+  const revenue = await openAccount(client, "Erlöse", "income");
+  const vat = await openAccount(client, "Umsatzsteuer", "liability");
+  const bank = await openAccount(client, "Bank", "asset");
+
+  // Invoice: net €1,000 + 19% VAT = €1,190 gross. One balanced 3-line entry.
+  await client.write(LedgerHandlers.createTransaction, {
+    date: "2026-02-01",
+    description: "Rechnung 2026-001",
+    reference: "INV-2026-001",
+    lines: [
+      { accountId: receivables, amount: 119000 }, // gross owed to us
+      { accountId: revenue, amount: -100000 }, // net revenue → income
+      { accountId: vat, amount: -19000 }, // VAT collected → liability
+    ],
+  });
+
+  // Revenue is recognised at invoice time — it's on the P&L before any payment.
+  const beforePayment = await client.query<{ income: number; netIncome: number }>(
+    LedgerQueries.reportIncomeStatement,
+    {},
+  );
+
+  // Payment arrives → Bank up, receivable cleared. Income does NOT change here.
+  await client.write(LedgerHandlers.createTransaction, {
+    date: "2026-02-20",
+    description: "Zahlung Rechnung 2026-001",
+    reference: "INV-2026-001",
+    lines: [
+      { accountId: bank, amount: 119000 },
+      { accountId: receivables, amount: -119000 },
+    ],
+  });
+
+  // The payment moved cash and cleared the receivable — it touched no income
+  // account, so the recognised revenue is unchanged.
+  const afterPayment = await client.query<{ income: number }>(
+    LedgerQueries.reportIncomeStatement,
+    {},
+  );
+
+  const balances = await client.query<BalancesReport>(LedgerQueries.reportBalances, {});
+  const balanceOf = (id: string) => balances.accounts.find((a) => a.id === id)?.balance ?? 0;
+
+  return {
+    revenueBeforePayment: beforePayment.income, // 100000 — accrual, cash-independent
+    revenueAfterPayment: afterPayment.income, // 100000 — payment doesn't double-count
+    receivablesAfterPayment: balanceOf(receivables), // 0 — invoice settled
+    bank: balanceOf(bank), // 119000 — gross cash received
+    vatOwed: balanceOf(vat), // 19000 — liability to the tax office
+    trialBalance: balances.trialBalance, // 0
+  };
+}

package/samples/recipes/legal-pages/README.md

@@ -0,0 +1,204 @@
+# 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:
+bun kumiko migrate generate    # detects text-block entity → SQL migration
+bun kumiko migrate 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. Follow your deployment team's
+private legal-template documentation for the approved source process.
+
+### 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

package/samples/recipes/legal-pages/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-legal-pages",
+  "description": "Auto-rendered Impressum + Datenschutzerklärung pages — template-resolver + legal-pages bundled features wired up with anonymousAccess for DACH-compliance.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/legal-pages/src/feature.ts

@@ -0,0 +1,50 @@
+// 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 };