@cosmicdrift/kumiko-samples 0.369.0 → 0.370.0

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -14,6 +14,7 @@
 // (subscription-stripe, channel-email, …). Those stubs are only for
 // boot-validation — no real transport/provider call happens.
 
+import { createAccountSecurityFeature } from "@cosmicdrift/kumiko-bundled-features/account-security";
 import { createAdminShellFeature } from "@cosmicdrift/kumiko-bundled-features/admin-shell";
 import { createAgentToolsFeature } from "@cosmicdrift/kumiko-bundled-features/agent-tools";
 import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
@@ -44,24 +45,18 @@ import { createDerivativesSharpFeature } from "@cosmicdrift/kumiko-bundled-featu
 import { createDocumentIngestFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/document-ingest-foundation";
 import { createFeatureTogglesFeature } from "@cosmicdrift/kumiko-bundled-features/feature-toggles";
 import { createFileDerivativesFeature } from "@cosmicdrift/kumiko-bundled-features/file-derivatives";
-import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
-import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
-import { createFileProviderS3Feature } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
-import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
 import { createFilesTenantDataFeature } from "@cosmicdrift/kumiko-bundled-features/files-tenant-data";
 import { createFoldersFeature } from "@cosmicdrift/kumiko-bundled-features/folders";
 import { createFoldersUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/folders-user-data";
 import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft";
 import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data";
+import { createHostRoutingFeature } from "@cosmicdrift/kumiko-bundled-features/host-routing";
 import { createInboundMailFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { createInboundProviderImapFeature } from "@cosmicdrift/kumiko-bundled-features/inbound-provider-imap";
 import { createInboundProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/inbound-provider-inmemory";
 import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
 import { createLedgerFeature } from "@cosmicdrift/kumiko-bundled-features/ledger";
 import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
-import { createMailFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
-import { createMailTransportInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
-import { createMailTransportSmtpFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-smtp";
 import { createManagedPagesFeature } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 import {
   createMetricsFeature,
@@ -71,7 +66,6 @@ import {
 import { createNotesHistoryFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history";
 import { createNotesHistoryUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history-user-data";
 import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
-import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
 import { createReadinessFeature } from "@cosmicdrift/kumiko-bundled-features/readiness";
 import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
 import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
@@ -92,6 +86,11 @@ import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled
 import { createUserProfileFeature } from "@cosmicdrift/kumiko-bundled-features/user-profile";
 import { createWaitlistFeature } from "@cosmicdrift/kumiko-bundled-features/waitlist";
 import { createWorkflowRunnerFeature } from "@cosmicdrift/kumiko-bundled-features/workflow-runner";
+import {
+  composeFileStack,
+  composeMailStack,
+  composeSecurityStack,
+} from "@cosmicdrift/kumiko-dev-server/compose-stacks";
 import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
@@ -124,8 +123,7 @@ export const APP_FEATURES = [
   localeDe(),
   // foundations not in the auto-mounted bundled-set
   createSecretsFeature(),
-  // security baseline: sessions + crypto-shredding + rate-limiting + audit
-  ...securityBaselineFeatures(),
+  ...composeSecurityStack(),
   // auth-mfa: composeFeatures auto-threads mfaStatusCheckerFromFeature into
   // the auto-mounted auth-email-password login handler when this feature is
   // present in appFeatures (see dev-server/src/compose-features.ts) — no
@@ -135,6 +133,8 @@ export const APP_FEATURES = [
     challengeTokenSecret: "smoke-mfa-challenge-secret-at-least-32-bytes-long!!",
     issuer: "Kumiko Sample",
   }),
+  // Self-service MFA + own sessions on one screen, in the sidebar.
+  createAccountSecurityFeature({ nav: {} }),
   // Owns the `tokenVerifier` extension-point personal-access-tokens
   // registers against below — required whenever a bearer-auth provider is
   // mounted (kumiko-framework#1369).
@@ -178,22 +178,14 @@ export const APP_FEATURES = [
   createChannelTeamsFeature(),
   createChannelTelegramFeature(),
 
-  // mail (foundation before transport)
-  createMailFoundationFeature(),
-  createMailTransportInMemoryFeature(),
-  createMailTransportSmtpFeature(),
+  ...composeMailStack({ transports: ["inmemory", "smtp"] }),
 
   // inbound mail (foundation before providers)
   createInboundMailFoundationFeature(),
   createInboundProviderInMemoryFeature(),
   createInboundProviderImapFeature(),
 
-  // files (foundation before provider)
-  createFileFoundationFeature(),
-  createFileProviderInMemoryFeature(),
-  createFileProviderS3Feature(),
-  createFileProviderS3Feature({ fromEnv: true }),
-  createFilesFeature(),
+  ...composeFileStack({ providers: ["inmemory", "s3", "s3-env"] }),
   // resolveApexTenant is what registers the `public-variant` query and the
   // anonymous /media route — the option-less export leaves both out and hides
   // them from `kumiko agent lint` (#2643). No entityType in this sample
@@ -277,6 +269,16 @@ export const APP_FEATURES = [
   // managed-pages/seo smoke resolvers above. grantSecret reuses the same
   // dev-only HMAC key the auth magic-links below use.
   createTenantHandoverFeature({ grantSecret: SMOKE_HMAC_SECRET }),
+  // Path mode keeps the dev host (localhost) free of a host-based resolver:
+  // anonymous calls still default to SYSTEM_TENANT, a client-named tenant
+  // must be enabled and active.
+  createHostRoutingFeature({
+    tenantBy: "path",
+    tenantPathPrefix: "/t",
+    baseDomain: "localhost",
+    apex: { file: "index.html" },
+    tenant: { file: "index.html" },
+  }),
   createDataRetentionFeature(),
   createUserDataRightsFeature(),
   createUserDataRightsDefaultsFeature(),

package/samples/recipes/apex-surface-auth/README.md

@@ -73,6 +73,7 @@ anonymous **email-verified** deletion flow from `user-data-rights`:
 
 ```ts illustration
 runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: composeApexAccountApp({
     deletionTokenSecret: process.env.DELETION_TOKEN_SECRET!,
     deletionVerifyUrl: "https://app.example.com/delete-account/confirm",

package/samples/recipes/apex-surface-auth/src/feature.ts

@@ -59,7 +59,7 @@
 // SERVER-WIRING: die App aktiviert `anonymousAccess` (defaultTenantId = der
 // Apex-Host-Tenant), damit /api/write die anonymen Deletion-Handler erreicht:
 //
-//   runProdApp({ features: composeApexAccountApp({...}),
+//   runProdApp({ features: composeApexAccountApp({...}), envSchema,
 //                anonymousAccess: { defaultTenantId: APEX_TENANT_ID } })
 
 import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";

package/samples/recipes/api-worker-split/bin/api.ts

@@ -2,11 +2,16 @@
 // HTTP + event writes + BullMQ ENQUEUE, no worker-lane consumption, no
 // multiStreamProjection application. A dedicated worker MUST run next to
 // it (bin/worker.ts) or the read-side stays empty.
+import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
 import { createApiWorkerSplitFeature } from "../src/feature";
 
+const features = [createApiWorkerSplitFeature()];
+
 await runProdApp({
-  features: [createApiWorkerSplitFeature()],
+  features,
+  envSchema: composeEnvSchema({ core: frameworkCoreEnvSchema, features }),
   runSingleInstance: false,
   // worker-lane queue prefix; must match bin/worker.ts.
   jobs: { queueNamePrefix: "api-worker-split" },

package/samples/recipes/app-config/README.md

@@ -0,0 +1,28 @@
+# App config
+
+`kumiko.config.ts` is the one place an app names its features, client entries
+and ports. `kumiko/schema.ts`, `kumiko agent lint`, `kumiko check` and
+`kumiko ports` all read it.
+
+## What it shows
+
+- **`defineAppConfig`** from `@cosmicdrift/kumiko-framework/config` validates the
+  config when the file loads: ports in range and unique within the app, client
+  entries relative and inside the app.
+- **`prodFeatures`** are mounted only in production (provider features such as
+  S3 or SMTP). `allAppFeatures(config)` returns `features` plus `prodFeatures`;
+  that is the list migrations and agent lint check.
+- **`ports`** with `dev`, `e2e` and optional `infra` (`postgres`, `redis`,
+  `meilisearch`, `s3`). Keep them number literals: `kumiko ports` reads them
+  statically across all apps of a workspace and reports collisions.
+
+## Files
+
+```
+kumiko.config.ts                  defineAppConfig with features, prodFeatures, client, ports
+src/feature.ts                    two placeholder features
+src/__tests__/app-config.test.ts  feature list, port list, validation errors
+```
+
+See [`docs/reference/app-skeleton.md`](../../../docs/reference/app-skeleton.md)
+for the files around it.

package/samples/recipes/app-config/kumiko.config.ts

@@ -0,0 +1,9 @@
+import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";
+import { auditExportFeature, notesFeature } from "./src/feature";
+
+export default defineAppConfig({
+  features: [notesFeature],
+  prodFeatures: [auditExportFeature],
+  client: { entries: ["src/client.tsx"] },
+  ports: { dev: 4510, e2e: 4511, infra: { postgres: 15510 } },
+});

package/samples/recipes/app-config/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-app-config",
+  "description": "kumiko.config.ts with defineAppConfig: the one feature list, client entries and ports the tooling reads.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/app-config/src/feature.ts

@@ -0,0 +1,6 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const notesFeature = defineFeature("notes", () => {});
+
+// Stands in for a provider feature that only production mounts (S3, SMTP).
+export const auditExportFeature = defineFeature("audit-export", () => {});

package/samples/recipes/app-config/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@cosmicdrift/kumiko-framework/*": [
+        "../../../packages/framework/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-bundled-features/*": [
+        "../../../packages/bundled-features/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server": [
+        "../../../packages/dev-server/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server/*": ["../../../packages/dev-server/src/*"]
+    },
+    "noEmit": true,
+    "rootDir": "../../..",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["bun-types"]
+  },
+  "include": ["./src", "./kumiko.config.ts"]
+}

package/samples/recipes/auth-mfa/README.md

@@ -53,6 +53,19 @@ const server = buildServer({
 
 Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `create-kumiko-app`) get all of this automatically — just add `createAuthMfaFeature(...)` to `APP_FEATURES`. `composeFeatures` threads the status-checker and the bootstrap wires the session-revoke bind and the verify route for you. This sample shows the raw contract those helpers implement.
 
+## Self-service screen
+
+`createAccountSecurityFeature({ nav?, access? })` adds one screen,
+`account-security:screen:account-security`, that embeds the MFA enable,
+regenerate and disable screens plus the own-sessions list. It owns no handlers
+and needs no `composeAuthStack`: mount it next to `auth-mfa` and `sessions`.
+Without `nav` the screen stays dormant (reachable by its route, no sidebar
+entry); `access` defaults to every signed-in user.
+
+```ts illustration
+features: [..., createSessionsFeature(), mfaFeature, createAccountSecurityFeature({ nav: { order: 90 } })]
+```
+
 ## Design rules
 
 1. **Enrollment is stateless until confirmed.** `enable-start` returns a signed setup token (QR + secret + 8 recovery codes) — nothing is persisted until `enable-confirm` proves the user scanned it with a valid TOTP code.
@@ -66,3 +79,4 @@ Apps built via `runDevApp`/`runProdApp` (the dev-server bootstrap used by `creat
 
 - **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
 - **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.
+- **Account security:** the composed screen boot-validates next to `auth-mfa` and `sessions` and shows a sidebar entry once `nav` is set.

package/samples/recipes/auth-mfa/src/feature.ts

@@ -62,6 +62,13 @@
 //     complete exactly one login challenge, then it's burned.
 //  4. Every MFA state change signs out every OTHER live session (stolen-
 //     session defense) — but never the session that made the change.
+
+// One self-service screen for MFA and own sessions. Dormant until `nav` is
+// set, so apps that mount it only for deep links get no sidebar entry.
+export {
+  ACCOUNT_SECURITY_SCREEN_QN,
+  createAccountSecurityFeature,
+} from "@cosmicdrift/kumiko-bundled-features/account-security";
 export {
   AuthMfaHandlers,
   base32Decode,

package/samples/recipes/compose-stacks/README.md

@@ -0,0 +1,60 @@
+# Compose stacks
+
+Mount the auth, security, GDPR and SaaS features through the `compose*Stack`
+helpers from `@cosmicdrift/kumiko-dev-server/compose-stacks` instead of
+listing each feature and its require order by hand. A stack that depends on a
+`runProdApp` option marks that on its features (`bootRequires`), and
+`runProdApp` refuses to boot when the option is missing, naming the stack and
+the option.
+
+## What it shows
+
+- **`composeAuthStack({ mfa, sessions })`**: `auth-foundation`, `sessions`,
+  and with `mfa` also `auth-mfa` plus `account-security`. The password login
+  itself still comes from the `auth` option or `composeFeatures`.
+- **`composeSecurityStack({ includeSessions })`**: `sessions`,
+  `crypto-shredding`, `rate-limiting` and `audit`. Needs a KMS decision
+  (`kmsMode`) and fails with `rateLimit: false`. Replaces
+  `securityBaselineFeatures()`.
+- **`composeGdprStack({ tenantLifecycle, selfService })`**: `data-retention`
+  and `compliance-profiles`, optionally `tenant-lifecycle`. `selfService` adds
+  `sessions`, `user-data-rights` and `user-profile` (needs `mail`) and
+  replaces `dsgvoSelfServiceFeatures()`.
+- **`composeSaasStack({ billing, tiers, caps, waitlist })`**:
+  `billing-foundation` and `tier-engine`, plus `cap-counter`/`cap-overview`
+  and `waitlist` when configured. `billing: "stripe"` leaves
+  `subscription-stripe` to the `billing` boot option, which also mounts the
+  tier-sync webhook route; `billing: "mollie"` mounts `subscription-mollie`
+  itself.
+
+## Boot requirements
+
+| Stack | Boot option | Also satisfied by |
+| --- | --- | --- |
+| `composeMailStack` | `mail` | a mounted `channel-email` |
+| `composeFileStack` without providers | `fileStorage` | a mounted file provider |
+| `composeGdprStack` | `kmsMode` | `kms` or `allowPlaintextPii` |
+| `composeGdprStack({ selfService })`, `composeUserDataRightsStack` | `mail` | a mounted `channel-email` |
+| `composeSecurityStack` | `kmsMode`, `rateLimit` not `false` | `kms` or `allowPlaintextPii` |
+| `composeSaasStack({ billing: "stripe" })` | `billing` | a mounted subscription provider |
+
+A missing option fails the boot with:
+
+```
+[runProdApp] stacks in `features` need boot options that are not set:
+  - composeSaasStack needs the boot option `billing`: set billing: { stripe: { priceToTier }, defaultTier }
+```
+
+## Flow
+
+1. `src/app.ts` lists the stacks and the boot options they need.
+2. The test boots with `KUMIKO_DRY_RUN_ENV=boot`, which runs the whole
+   validation and stops before any DB or Redis connection: with the options
+   the boot passes, without `billing` or `kmsMode` it fails and names the
+   stacks.
+
+## Tests
+
+```bash
+bun test samples/recipes/compose-stacks
+```

package/samples/recipes/compose-stacks/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-compose-stacks",
+  "description": "compose*Stack helpers for auth, security, GDPR and SaaS billing, and the runProdApp check that names a stack whose boot option is missing.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-server-runtime": "workspace:*"
+  }
+}

package/samples/recipes/compose-stacks/src/app.ts

@@ -0,0 +1,44 @@
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import {
+  composeAuthStack,
+  composeGdprStack,
+  composeSaasStack,
+  composeSecurityStack,
+} from "@cosmicdrift/kumiko-dev-server/compose-stacks";
+import type { RunProdAppOptions } from "@cosmicdrift/kumiko-server-runtime";
+
+export const PRO_PRICE_ID = "price_pro_monthly";
+
+export function appFeatures(): RunProdAppOptions["features"] {
+  return [
+    createConfigFeature(),
+    createSecretsFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    ...composeAuthStack(),
+    ...composeSecurityStack(),
+    ...composeGdprStack({ tenantLifecycle: true }),
+    ...composeSaasStack({
+      billing: "stripe",
+      tiers: {
+        defaultTier: "free",
+        tierMap: {
+          free: { features: [], caps: { seats: 1 } },
+          pro: { features: [], caps: { seats: 25 } },
+        },
+      },
+    }),
+  ];
+}
+
+type StackBootOptions = Pick<RunProdAppOptions, "kmsMode" | "billing">;
+
+export function bootOptions(): StackBootOptions {
+  return {
+    kmsMode: "required",
+    billing: { stripe: { priceToTier: { [PRO_PRICE_ID]: "pro" } }, defaultTier: "free" },
+  };
+}

package/samples/recipes/env-composition/README.md

@@ -0,0 +1,36 @@
+# Env composition
+
+Build the app's env schema from the blocks the mounted features register,
+instead of keeping a hand-written copy of every feature's variables.
+
+## What it shows
+
+- **Feature blocks**: `createSecretsFeature`, `createCryptoShreddingFeature`
+  and `createFileProviderS3Feature({ fromEnv: true })` register `secretsEnvSchema`,
+  `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
+  records which feature declared each variable.
+- **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
+  `stripeEnvSchema({ prices })` and `createS3EnvSchema({ prefix })` for a
+  second bucket. These belong to no mounted feature, so the app adds them.
+- **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
+  so `parsed.S3_BUCKET` is `string | undefined` and `parsed.APP_PUBLIC_URL` is
+  `string` without a cast.
+- **Error report**: a missing required variable is listed with its source
+  (`secrets`, `app`, …).
+
+## Blocks
+
+| Block | Where it lives | Registered by |
+| --- | --- | --- |
+| `kmsEnvSchema` | `crypto-shredding` | `createCryptoShreddingFeature()` |
+| `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
+| `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
+| `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
+| `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
+| `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
+| `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |
+
+## When to reach for it
+
+Every app that boots with `runProdApp`. Pass the composed schema as
+`envSchema` and read the parsed values instead of `process.env`.

package/samples/recipes/env-composition/bin/server.ts

@@ -0,0 +1,15 @@
+// Production entrypoint. The env schema covers the same feature list that
+// runProdApp mounts, so `KUMIKO_DRY_RUN_ENV=boot bun bin/server.ts` lists
+// every variable of this app without connecting anywhere.
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { composeAppEnv, createEnvCompositionFeatures } from "../src/env";
+
+const features = createEnvCompositionFeatures();
+
+await runProdApp({
+  features: [...features],
+  envSchema: composeAppEnv(features),
+  // The recipe declares no PII fields; crypto-shredding is mounted only for
+  // its env block.
+  allowPlaintextPii: "env-composition recipe has no PII fields",
+});

package/samples/recipes/env-composition/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-env-composition",
+  "description": "Typed app env from the env blocks bundled features register, plus app-level blocks in extend.",
+  "private": true,
+  "scripts": {
+    "start": "bun bin/server.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-server-runtime": "workspace:*"
+  }
+}

package/samples/recipes/env-composition/src/env.ts

@@ -0,0 +1,47 @@
+// Env Composition Sample
+// Shows: the app env schema is composed from the blocks the mounted features
+// register, plus app-level blocks in `extend`. The parsed env is typed from
+// those blocks, so no app keeps a hand-written twin of a feature's variables.
+
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding";
+import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import {
+  createFileProviderS3Feature,
+  createS3EnvSchema,
+} from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import {
+  buildInfoEnvSchema,
+  demoAdminEnvSchema,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
+import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import * as z from "zod";
+
+export function createEnvCompositionFeatures() {
+  return [
+    createConfigFeature(),
+    createSecretsFeature(),
+    createCryptoShreddingFeature(),
+    createFileFoundationFeature(),
+    createFileProviderS3Feature({ fromEnv: true }),
+  ] as const;
+}
+
+// App-level blocks: none of these belong to a mounted feature, so they go
+// into extend. A second bucket reuses the S3 block under its own prefix.
+const appEnvSchema = z.object({
+  ...buildInfoEnvSchema.shape,
+  ...demoAdminEnvSchema.shape,
+  ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
+  APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
+});
+
+export function composeAppEnv(
+  features: ReturnType<typeof createEnvCompositionFeatures> = createEnvCompositionFeatures(),
+) {
+  return composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend: appEnvSchema });
+}

package/samples/recipes/host-routing/README.md

@@ -0,0 +1,25 @@
+# Host Routing
+
+Tenant per subdomain with one options object for the API and the HTML pages.
+
+## What it shows
+
+- `createHostRoutingFeature(options)`: the Host header is the only source of the
+  anonymous tenant; a forged `X-Tenant` header answers `400 tenant_mismatch`.
+- `createHostDispatch(options)`: HTML file and CSP per host, a 404 page for
+  unknown shops, and `/de/...` redirecting to the unprefixed path.
+- The same `hostDispatch` goes into `runProdApp({ hostDispatch })`; the dev
+  server takes it through `toDevHostDispatch` from `@cosmicdrift/kumiko-dev-server`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+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
+cd samples/recipes/host-routing
+bun test
+```

package/samples/recipes/host-routing/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-host-routing",
+  "description": "createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

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

@@ -0,0 +1,35 @@
+// Host routing: one options object drives both halves. The feature makes the
+// Host header the only source of the anonymous tenant; the dispatch picks the
+// HTML file per host for runProdApp's `hostDispatch` (and, through
+// toDevHostDispatch, for the dev server).
+
+import {
+  createHostDispatch,
+  createHostRoutingFeature,
+  type HostRoutingOptions,
+} from "@cosmicdrift/kumiko-bundled-features/host-routing";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const routingOptions: HostRoutingOptions = {
+  tenantBy: "host",
+  baseDomain: "shop.test",
+  apex: { file: "index.html", localeFiles: { en: "en/index.html" } },
+  tenant: { file: "shop.html", csp: "default-src 'self'; frame-ancestors 'none'" },
+  unknownTenant: { file: "unknown-shop.html" },
+  locales: { default: "de", prefixed: ["en"] },
+};
+
+export const hostRoutingFeature = createHostRoutingFeature(routingOptions);
+export const hostDispatch = createHostDispatch(routingOptions);
+
+// A public query that reports which tenant the request landed on.
+export const storefrontFeature = defineFeature("storefront", (r) => {
+  r.queryHandler({
+    name: "whoami",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    handler: async (query) => ({ tenantId: query.user.tenantId }),
+  });
+});

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

@@ -63,6 +63,7 @@ import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/le
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: [
     createTemplateResolverFeature(),
     createLegalPagesFeature(),
@@ -143,6 +144,20 @@ await seedTextBlock(db, {
 → Templates for full legally-sound texts: e-recht24.de
 or datenschutz-generator.de by Dr. Schwenke.
 
+With `runProdApp` the same blocks can come from a JSON file on every boot.
+`legalContentSeed` updates existing blocks, so the file stays authoritative:
+
+```typescript illustration
+import legalContent from "./legal-content.json" with { type: "json" };
+import { legalContentSeed } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+
+runProdApp({ /* ... */ seeds: [legalContentSeed({ blocks: legalContent })] });
+```
+
+The recipe mounts `createLegalPagesFeature({ terms: true, wrapLayout })`, so it
+also serves `/legal/nutzungsbedingungen` and `/legal/terms`, and wraps every
+page in `createLegalPagesLayout({ siteName })`.
+
 ### 4. Visit the pages
 
 After the seed these URLs are immediately live:

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

@@ -35,8 +35,10 @@
 
 import {
   createLegalPagesFeature,
+  createLegalPagesLayout,
   LEGAL_REQUIRED_BLOCKS,
   LEGAL_ROUTES,
+  LEGAL_TERMS_ROUTES,
 } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 
@@ -44,7 +46,16 @@ import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-featu
 // requires sie. r.requires({ features: ["template-resolver"] }) greift automatisch im
 // legal-pages-Feature.
 export const templateResolverFeature = createTemplateResolverFeature();
-export const legalPagesFeature = createLegalPagesFeature();
+// `terms: true` adds the opt-in terms routes; the layout puts the app's chrome
+// around every legal page.
+export const legalPagesFeature = createLegalPagesFeature({
+  terms: true,
+  wrapLayout: createLegalPagesLayout({
+    siteName: "Sample App",
+    footerHtml: (lang) =>
+      lang === "de" ? "<footer>Sample App</footer>" : "<footer>Sample App (en)</footer>",
+  }),
+});
 
 // Re-exports für Tests + andere Demos
-export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES };
+export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, LEGAL_TERMS_ROUTES };