@cosmicdrift/kumiko-dev-server 1.0.0 → 2.0.0

package/src/run-dev-app.ts

@@ -18,16 +18,43 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import {
+  EXT_SESSION_STORE,
+  resolveSessionStore,
+  resolveTokenVerifier,
+  type SessionStore,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import {
+  AUTH_MFA_FEATURE,
+  AuthMfaHandlers,
+  bindMfaRevokeAllOtherSessionsFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import {
   buildEnvConfigOverrides,
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
 import {
-  createSessionCallbacks,
-  type SessionCallbacks,
+  PAT_FEATURE,
+  patRateLimitFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import {
+  bindAutoRevokeFromFeature,
+  SESSIONS_FEATURE,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import {
+  resolveTenantLifecycleGate,
+  TENANT_LIFECYCLE_FEATURE,
+} from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
+import type { SessionMetadata, TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
+import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import {
   collectWriteHandlerQns,
   createRegistry,
@@ -41,13 +68,17 @@ import {
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import { applyBootSeeds } from "./boot/apply-boot-seeds";
-
+import { applyBootSeeds } from "@cosmicdrift/kumiko-server-runtime/boot/apply-boot-seeds";
+import { resolveBootCrypto } from "@cosmicdrift/kumiko-server-runtime/boot/boot-crypto";
+import {
+  buildComposeAuthOptions,
+  composeFeatures,
+} from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import { assertPiiBootInvariants } from "@cosmicdrift/kumiko-server-runtime/pii-boot-gate";
 import { watchAndRegenerate } from "./codegen";
-import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import {
   type CreateKumikoServerOptions,
   createKumikoServer,
@@ -57,28 +88,31 @@ import { renderWelcomeBanner } from "./welcome-banner";
 
 // Re-export der shared Auth-Setup-Types damit Apps nur einen Import-Pfad
 // brauchen. PasswordResetSetup / EmailVerificationSetup leben in
-// run-prod-app.ts (single source of truth) — hier nur durchgereicht.
+// @cosmicdrift/kumiko-server-runtime (single source of truth) — hier nur
+// durchgereicht.
 export type {
+  AccountUnlockSetup,
   AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
   PasswordResetSetup,
   SignupSetup,
-} from "./run-prod-app";
+} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 
 import type {
+  AccountUnlockSetup,
   AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
   PasswordResetSetup,
   SignupSetup,
-} from "./run-prod-app";
+} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 import {
   addConfigAccessorFactory,
   buildBootExtraContext,
   requireEnv,
   resolveAuthMail,
-} from "./run-prod-app";
+} from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 
 export type RunDevAppAuthOptions = {
   /** Admin user to seed at boot. Idempotent — re-runs in persistent-DB
@@ -87,17 +121,6 @@ export type RunDevAppAuthOptions = {
   /** Optional override of the login error → HTTP status map. Default
    *  maps invalidCredentials → 401, noMembership → 403. */
   readonly loginErrorStatusMap?: Readonly<Record<string, number>>;
-  /** Opt-in: revocable server-side sessions. Caller MUSS
-   *  `createSessionsFeature()` zu `features` adden — runDevApp wired
-   *  hier nur die Auth-Callbacks (creator/revoker/checker) gegen
-   *  stack.db, plus sessionStrictMode=true.
-   *
-   *  Standardverhalten ohne diese Option: stateless JWTs ohne sid,
-   *  Logout ist client-side cookie-clear, Karten­haus existing-Apps
-   *  bleibt unangefasst. */
-  readonly sessions?: {
-    readonly expiresInMs?: number;
-  };
   /** Auth-Mail-Convenience — symmetrisch zu RunProdAppAuthOptions.mail.
    *  Verdrahtet alle 4 Mail-Flows aus env-SMTP + Standard-Templates;
    *  hmacSecret = `JWT_SECRET`-env (Dev-Fallback wenn ungesetzt). Ohne
@@ -109,21 +132,28 @@ export type RunDevAppAuthOptions = {
    *  der request/confirm-Handler im auth-email-password-Feature wird
    *  registriert. Symmetrisch zu RunProdAppAuthOptions.passwordReset. */
   readonly passwordReset?: PasswordResetSetup;
-  /** Email-verification flow. Symmetric zu passwordReset. */
+  /** Email-verification flow. Symmetric to passwordReset. */
   readonly emailVerification?: EmailVerificationSetup;
-  /** Self-Signup flow (Magic-Link). Symmetric zu RunProdAppAuthOptions. */
+  /** Self-signup flow (magic link). Symmetric to RunProdAppAuthOptions. */
   readonly signup?: SignupSetup;
-  /** Tenant-Invite flow (Magic-Link). Symmetric. */
+  /** Tenant-invite flow (magic link). Symmetric. */
   readonly invite?: InviteSetup;
+  /** Account-unlock flow (#1266). Symmetric to RunProdAppAuthOptions. */
+  readonly accountUnlock?: AccountUnlockSetup;
   /** Domain attribute for both auth cookies (see
-   *  AuthRoutesConfig.cookieDomain). Symmetric zu RunProdAppAuthOptions. */
+   *  AuthRoutesConfig.cookieDomain). Symmetric to RunProdAppAuthOptions. */
   readonly cookieDomain?: string;
   /** Server-side Origin allowlist for the CSRF guard (see
-   *  AuthRoutesConfig.allowedOrigins). Symmetric zu RunProdAppAuthOptions —
+   *  AuthRoutesConfig.allowedOrigins). Symmetric to RunProdAppAuthOptions —
    *  required once `cookieDomain` is set. */
   readonly allowedOrigins?: readonly string[];
-  /** Opt out of the Origin guard. Symmetric zu RunProdAppAuthOptions. */
+  /** Opt out of the Origin guard. Symmetric to RunProdAppAuthOptions. */
   readonly unsafeSkipOriginCheck?: boolean;
+  /** Number of trusted reverse-proxy hops for client-IP derivation (see
+   *  AuthRoutesConfig.trustedProxyHops, kumiko-framework#1539). Symmetric to
+   *  RunProdAppAuthOptions — dev usually runs unproxied, so this is normally
+   *  left unset (default 0). */
+  readonly trustedProxyHops?: number;
 };
 
 /** Hook for app-specific seeding (demo data, fixtures). Runs after the
@@ -176,6 +206,16 @@ export type RunDevAppOptions = {
    *  `createEnvMasterKeyProvider`. Override für KMS-Backends. Nur relevant
    *  wenn das secrets-Feature gemountet ist. Symmetrisch zu runProdApp. */
   readonly masterKey?: MasterKeyProvider;
+  /** Subject-Key-KMS für pii-annotierte Felder (Crypto-Shredding) — dev-
+   *  Pendant zu runProdApp({ kms }). Ephemere DB: InMemoryKmsAdapter reicht.
+   *  Persistente Dev-DB: createPgKmsAdapter gegen dieselbe DB, sonst sind
+   *  alte Rows nach dem Restart unlesbar (DEKs weg). Ohne Adapter: Klartext
+   *  + Boot-Warnung. */
+  readonly kms?: KmsAdapter;
+  /** 32-Byte-Key (base64) für Blind-Index-HMACs — Pflicht sobald `kms`
+   *  gesetzt ist und lookupable-Felder gemountet sind (sonst Boot-Abbruch,
+   *  symmetrisch zu runProdApp). */
+  readonly blindIndexKey?: string;
   /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
    *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
    *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
@@ -226,10 +266,14 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
-  // Ein explizit gewireter File-Provider (options.files) erfüllt das
-  // FILE_STORAGE_PROVIDER-Boot-Gate — der Provider IST konfiguriert, nur
-  // nicht über die env-Bridge. Setzen bevor validateBoot greift.
-  if (options.files !== undefined && process.env["FILE_STORAGE_PROVIDER"] === undefined) {
+  // An explicitly wired file provider (options.files) satisfies the
+  // FILE_STORAGE_PROVIDER boot gate — set it before validateBoot runs. Only
+  // if WE set it (532/2): deleting it after use instead of leaving a
+  // permanent process.env mutation, so a second runDevApp call in the same
+  // process (no files this time) doesn't fall through the gate falsely.
+  const setFileStorageProviderEnv =
+    options.files !== undefined && process.env["FILE_STORAGE_PROVIDER"] === undefined;
+  if (setFileStorageProviderEnv) {
     process.env["FILE_STORAGE_PROVIDER"] = "configured";
   }
 
@@ -238,7 +282,11 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // die früher nur runProdApp fing und sonst erst den Prod-Pod im
   // CrashLoopBackOff sterben ließ (#359). Wirft synchron, bevor ein
   // Socket oder Watcher (codegen-Write) aufgeht.
-  validateBoot(features);
+  try {
+    validateBoot(features);
+  } finally {
+    if (setFileStorageProviderEnv) delete process.env["FILE_STORAGE_PROVIDER"];
+  }
   warnIfNonUtcServerTimeZone();
   validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
 
@@ -303,8 +351,27 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // throwaway-Registry hier extrahiert nur die config-Keys, weil der
   // configResolver vor dem Server-Boot konstruiert wird (stack.registry
   // gibt's erst onAfterSetup) — createKumikoServer baut intern seine eigene.
+  const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+  // App-wide cipher for `encrypted: true` entity fields (symmetrisch zu
+  // runProdApp) — executors resolve it lazily.
+  configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+  // Subject-KMS + Blind-Index (symmetrisch zu runProdApp). Dev warnt bei
+  // Klartext-PII statt zu failen; kms+lookupable ohne blindIndexKey bricht
+  // auch hier (Lookups wären in jedem Modus kaputt).
+  configurePiiSubjectKms(options.kms);
+  configureBlindIndexKey(options.blindIndexKey);
+  assertPiiBootInvariants(features, {
+    kms: options.kms,
+    blindIndexKey: options.blindIndexKey,
+    mode: "dev",
+  });
   const cfgExtra = effectiveAuth
-    ? mergeConfigResolverDefault(options.extraContext, createRegistry(features), envSource)
+    ? mergeConfigResolverDefault(
+        options.extraContext,
+        createRegistry(features),
+        envSource,
+        bootCrypto.configCipher,
+      )
     : options.extraContext;
   // Auto-wire textContent (immer) + secrets (feature-gated), symmetrisch zu
   // runProdApp. Anders als prod existiert die db hier erst im Factory-deps
@@ -319,39 +386,70 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       registry: deps.registry,
       hasAuth: false,
       sseBroker: deps.sseBroker,
-      ...(options.masterKey && { masterKey: options.masterKey }),
+      crypto: bootCrypto,
     });
     const base = typeof cfgExtra === "function" ? cfgExtra(deps) : (cfgExtra ?? {});
     return { ...boot, ...base };
   };
 
-  // Sessions opt-in: Holder lebt im closure, `createSessionCallbacks`
-  // kennt erst nach setupTestStack die echte db-connection. Inline
-  // statt @cosmicdrift/kumiko-framework/testing's createLateBoundHolder zu reusen,
-  // weil dev-server (dev-runtime) keine Tooling aus framework/testing
-  // (test-runtime) importieren darf — Runtime-Isolation Guard.
-  // Server-Start passiert NACH onAfterSetup (siehe create-kumiko-server.ts),
-  // daher ist `sessionCallbacks` zur ersten Login-Request konkret.
-  let sessionCallbacks: SessionCallbacks | undefined;
-  const requireSessions = (): SessionCallbacks => {
-    if (!sessionCallbacks) {
-      throw new Error("[runDevApp] session-callbacks accessed before onAfterSetup");
+  // Sessions: late-bound holder — resolveSessionStore needs concrete db+
+  // registry (only after setupTestStack). Wired when sessions feature is
+  // mounted (#1372); no auth.sessions opt-in anymore.
+  let sessionStore: SessionStore | undefined;
+  const requireSessionStore = (): SessionStore => {
+    if (!sessionStore) {
+      throw new Error("[runDevApp] sessionStore accessed before onAfterSetup");
     }
-    return sessionCallbacks;
+    return sessionStore;
   };
+  // Token-verifier opt-in: same late-bound holder pattern — resolveTokenVerifier
+  // needs the real db+registry (only concrete after setupTestStack). Wired
+  // whenever a provider feature (personal-access-tokens today) is mounted.
+  let tokenVerifier: TokenVerifier | undefined;
+  let lifecycleDb: DbConnection | undefined;
+  const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+  const tenantLifecycleFeature = features.find((f) => f.name === TENANT_LIFECYCLE_FEATURE);
+  const patAuthFragment = patFeature
+    ? {
+        tokenVerifier: (rawToken: string) => {
+          if (!tokenVerifier) {
+            throw new Error("[runDevApp] token-verifier accessed before onAfterSetup");
+          }
+          return tokenVerifier(rawToken);
+        },
+        patRateLimiter: (() => {
+          const rl = patRateLimitFromFeature(patFeature);
+          return createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs);
+        })(),
+      }
+    : {};
+
+  const tenantLifecycleAuthFragment = tenantLifecycleFeature
+    ? {
+        resolveTenantLifecycleStatus: async (tenantId: string) => {
+          if (!lifecycleDb) {
+            throw new Error("[runDevApp] tenant-lifecycle gate accessed before onAfterSetup");
+          }
+          const gate = await resolveTenantLifecycleGate(lifecycleDb, tenantId);
+          return gate ? { status: gate.status } : null;
+        },
+      }
+    : {};
+
+  // Parity with runProdApp (#1372 review): gate on sessionStore provider, not
+  // the sessions feature name — a custom provider must also wire auth callbacks.
+  const sessionStoreProviderMounted = features.some((f) =>
+    f.extensionUsages.some((u) => u.extensionName === EXT_SESSION_STORE),
+  );
   const sessionAuthFragment =
-    effectiveAuth?.sessions !== undefined
+    effectiveAuth && sessionStoreProviderMounted
       ? {
           sessionCreator: (user: SessionUser, meta: SessionMetadata) =>
-            requireSessions().sessionCreator(user, meta),
-          sessionRevoker: (sid: string) => requireSessions().sessionRevoker(sid),
+            requireSessionStore().creator(user, meta),
+          sessionRevoker: (sid: string) => requireSessionStore().revoker(sid),
           sessionChecker: (sid: string, userId: string) =>
-            requireSessions().sessionChecker(sid, userId),
-          // strict-mode: jede neue Plattform-App startet ohne legacy-
-          // JWTs ohne sid, daher safe als Default. Wer Sessions opt-in
-          // wählt, will explizite Server-side Revocation — strict-mode
-          // ist der einzige Modus der das tatsächlich erzwingt.
-          sessionStrictMode: true,
+            requireSessionStore().checker(sid, userId),
         }
       : {};
 
@@ -391,7 +489,17 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
+        ...(effectiveAuth.trustedProxyHops !== undefined && {
+          trustedProxyHops: effectiveAuth.trustedProxyHops,
+        }),
         ...sessionAuthFragment,
+        ...patAuthFragment,
+        ...tenantLifecycleAuthFragment,
+        ...(mfaFeature && {
+          mfaVerifyHandler: AuthMfaHandlers.verify,
+          mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
+          mfaPreauthConfirmHandler: AuthMfaHandlers.enableConfirmPreauth,
+        }),
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
@@ -404,6 +512,12 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
             confirmHandler: AuthHandlers.verifyEmail,
           },
         }),
+        ...(effectiveAuth.accountUnlock && {
+          accountUnlock: {
+            requestHandler: AuthHandlers.requestAccountUnlock,
+            confirmHandler: AuthHandlers.confirmAccountUnlock,
+          },
+        }),
         ...(effectiveAuth.signup && {
           signup: {
             requestHandler: AuthHandlers.signupRequest,
@@ -420,6 +534,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       },
     }),
     onAfterSetup: async (stack) => {
+      lifecycleDb = stack.db;
       // Sprint-8a: build tier-resolver BEFORE any seeds so seeds can rely
       // on the resolver being live (e.g. seed that writes a SystemAdmin's
       // tier-assignment can immediately read tier-cuts).
@@ -430,12 +545,25 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           registry: stack.registry,
         });
       }
-      if (effectiveAuth?.sessions !== undefined) {
-        const expiresInMs = effectiveAuth.sessions.expiresInMs;
-        sessionCallbacks = createSessionCallbacks({
+      if (effectiveAuth && stack.registry.getExtensionUsages(EXT_SESSION_STORE).length > 0) {
+        // Secure-by-default (#1372): resolve sessionStore provider; bind
+        // password-change mass-revoke + MFA revokeAllOthers.
+        const store = await resolveSessionStore({
           db: stack.db,
-          ...(expiresInMs !== undefined && { expiresInMs }),
+          registry: stack.registry,
         });
+        const sessionsFeature = features.find((f) => f.name === SESSIONS_FEATURE);
+        if (sessionsFeature) {
+          bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);
+        }
+        if (mfaFeature) {
+          bindMfaRevokeAllOtherSessionsFromFeature(mfaFeature)?.(store.revokeAllOthers);
+        }
+        sessionStore = store;
+      }
+      if (patFeature) {
+        tokenVerifier = (rawToken) =>
+          resolveTokenVerifier({ db: stack.db, registry: stack.registry }, rawToken);
       }
       if (effectiveAuth) {
         await seedAdmin(stack.db, effectiveAuth.admin);
@@ -444,7 +572,11 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       // Runs before user-supplied seed callbacks so those can read /
       // override the deploy-defaults. The helper indirection is what
       // config-seed-boot.integration.ts pins — keep it as a single call.
-      await applyBootSeeds({ registry: stack.registry, db: stack.db });
+      await applyBootSeeds({
+        registry: stack.registry,
+        db: stack.db,
+        ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
+      });
       for (const seed of options.seeds ?? []) {
         await seed(stack);
       }
@@ -480,10 +612,12 @@ export function mergeConfigResolverDefault(
   ctx: CreateKumikoServerOptions["extraContext"],
   registry: Registry,
   envSource: Record<string, string | undefined>,
+  cipher?: EnvelopeCipher,
 ): CreateKumikoServerOptions["extraContext"] {
   const defaults = {
     configResolver: createConfigResolver({
       appOverrides: buildEnvConfigOverrides(registry, envSource),
+      ...(cipher && { cipher }),
     }),
   };
   // ctx.config wird per-Request aus _configAccessorFactory geminted (siehe

package/src/scaffold-app-feature.ts

@@ -47,14 +47,27 @@ export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): Scaffold
   }
   mkdirSync(featureDir, { recursive: true });
 
-  const files: string[] = [];
-  const featureFile = join(featureDir, "feature.ts");
-  writeFileSync(featureFile, renderFeature(options.name));
-  files.push(`src/features/${options.name}/feature.ts`);
+  // Volle App-Feature-Konvention (Referenz: bundled-features/tenant):
+  // feature.ts = nur Registrierung, schema/ für Entities, i18n.ts für
+  // Server-Keys, web/ für die Client-Seite, __tests__/ mit Boot-Test.
+  // handlers/ + lib/ entstehen beim ersten echten Handler/Logik-Modul.
+  mkdirSync(join(featureDir, "schema"), { recursive: true });
+  mkdirSync(join(featureDir, "web"), { recursive: true });
+  mkdirSync(join(featureDir, "__tests__"), { recursive: true });
 
-  const indexFile = join(featureDir, "index.ts");
-  writeFileSync(indexFile, renderIndex(options.name));
-  files.push(`src/features/${options.name}/index.ts`);
+  const files: string[] = [];
+  const write = (relative: string, content: string): void => {
+    writeFileSync(join(featureDir, relative), content);
+    files.push(`src/features/${options.name}/${relative}`);
+  };
+  write("feature.ts", renderFeature(options.name));
+  write("index.ts", renderIndex(options.name));
+  write("constants.ts", renderConstants(options.name));
+  write("i18n.ts", renderI18n(options.name));
+  write(join("schema", `${options.name}-item.ts`), renderEntity(options.name));
+  write(join("schema", "index.ts"), renderSchemaIndex(options.name));
+  write(join("web", "index.ts"), renderWebIndex(options.name));
+  write(join("__tests__", "feature.boot.test.ts"), renderBootTest(options.name));
 
   const runConfigPath = join(appRoot, "src", "run-config.ts");
   let autoMounted = false;
@@ -83,18 +96,38 @@ function renderFeature(name: string): string {
   const camel = kebabToCamel(name);
   return `// ${name} feature — scaffolded by \`kumiko add feature\`. Edit freely.
 //
-// Doc-Pointer: https://docs.kumiko.rocks/en/patterns/ for the \`r.*\` API
-// (r.entity, r.writeHandler, r.queryHandler, hooks, …).
+// Konvention (Referenz: bundled-features, z.B. tenant/):
+//   feature.ts  — NUR Registrierung (r.entity / r.screen / r.queryHandler / …)
+//   schema/     — Entity-Definitionen
+//   handlers/   — eine Datei pro Handler (defineQueryHandler / defineWriteHandler)
+//   lib/        — reine Domain-Logik
+//   web/        — Client-Seite (index.ts, ein Screen pro Datei)
+//   i18n.ts     — Server-Translation-Keys
+//
+// Doc-Pointer: https://docs.kumiko.rocks/en/patterns/ for the \`r.*\` API.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { ${constName(name)} } from "./constants";
+import { ${camel}TranslationKeys } from "./i18n";
+import { ${camel}ItemEntity } from "./schema";
+
+export const ${camel}Feature = defineFeature(${constName(name)}, (r) => {
+  r.entity("${name}-item", ${camel}ItemEntity);
 
-export const ${camel}Feature = defineFeature("${name}", (r) => {
-  // Starter: declare an entity. Drop and replace with your domain.
-  r.entity("${name}-item", {
-    fields: {
-      title: { type: "text", required: true },
-    },
+  // Deklarativer List-Screen — CRUD-Query kommt aus der Entity.
+  // Für query-getriebene Tabellen: type "projectionList"; für
+  // Kennzahlen-Grids: type "dashboard".
+  r.screen({
+    id: "items",
+    type: "entityList",
+    entity: "${name}-item",
+    columns: ["title"],
+    defaultSort: { field: "title", dir: "asc" },
   });
+
+  r.translations({ keys: ${camel}TranslationKeys });
+
+  r.nav({ id: "items", label: "screen:items.title", screen: "${name}:screen:items" });
 });
 `;
 }
@@ -104,10 +137,80 @@ function renderIndex(name: string): string {
   return `export { ${camel}Feature } from "./feature";\n`;
 }
 
+function renderConstants(name: string): string {
+  return `export const ${constName(name)} = "${name}" as const;\n`;
+}
+
+function renderI18n(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// Server-seitige Translation-Keys (r.translations). Screen-Titel und
+// Field-Labels folgen den Framework-Konventionen — der Boot-Validator
+// prüft die Abdeckung.
+
+export const ${camel}TranslationKeys = {
+  "screen:items.title": { de: "Einträge", en: "Items" },
+  "${name}:entity:${name}-item:field:title": { de: "Titel", en: "Title" },
+};
+`;
+}
+
+function renderEntity(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// Entity-Definition — Felder, Annotationen, Transitions.
+// Starter: eine Text-Spalte. Ersetze sie durch deine Domain.
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+export const ${camel}ItemEntity = createEntity({
+  fields: {
+    title: createTextField({ required: true, sortable: true }),
+  },
+});
+`;
+}
+
+function renderSchemaIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `export { ${camel}ItemEntity } from "./${name}-item";\n`;
+}
+
+function renderWebIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// @runtime client
+// Client-Seite des Features: translations, components (custom-Screens),
+// columnRenderers. In src/app/client.tsx bei
+// createKumikoApp({ clientFeatures: [...] }) einhängen — das passiert
+// NICHT automatisch. Screens: eine Datei pro Screen in diesem Ordner.
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+
+export const ${camel}Client: ClientFeatureDefinition = {
+  name: "${name}",
+};
+`;
+}
+
+function renderBootTest(name: string): string {
+  const camel = kebabToCamel(name);
+  return `import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { ${camel}Feature } from "../feature";
+
+describe("${name} feature", () => {
+  test("boots: Entity, Screens und i18n-Coverage validieren", () => {
+    expect(() => validateBoot([${camel}Feature])).not.toThrow();
+  });
+});
+`;
+}
+
 function kebabToCamel(name: string): string {
   return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 }
 
+function constName(name: string): string {
+  return `${name.replace(/-/g, "_").toUpperCase()}_FEATURE`;
+}
+
 // ts-morph: open run-config, prepend import, append APP_FEATURES entry.
 // Returns true on success, throws on shape-mismatch — the caller rolls back
 // the scaffolded feature dir and re-throws so a re-run isn't blocked.