@cosmicdrift/kumiko-dev-server 0.328.1 → 0.330.0

package/dist/codegen/scan-events.js

@@ -0,0 +1,447 @@
+// scanEvents — finds every `r.defineEvent(...)` call across the app's
+// feature files and resolves both the event-name (string literal) AND
+// the schema source needed to derive a TS-Type. The codegen pipeline
+// turns these into a `KumikoEventTypeMap` augmentation, the "single
+// source of truth" the local defineWriteHandler-wrapper binds against
+// for cross-package strict-checking.
+//
+// Output is a flat list of "event entries" — qualified-name + everything
+// needed to emit a `z.infer<typeof Schema>` line in the augmentation.
+//
+// Patterns we resolve to a strict-checked type:
+//   1. r.defineEvent("name", schemaIdentifier)
+//      Position-form, named import. The cleanest case — Schema lives
+//      in events.ts, gets re-imported by the augmentation as `import
+//      type` and threaded through `z.infer<typeof Schema>`.
+//
+//   2. r.defineEvent({ name, schema })
+//      Object-form, otherwise identical to (1).
+//
+//   3. r.defineEvent(NAME_CONST.member, schema...)
+//      Computed name via `as const` object. We follow the property-
+//      access through ts-morph's symbol-resolver, find the literal
+//      member, treat it as the string from (1)/(2). Keeps recipes that
+//      centralise event-names in a constants module strict-able.
+//
+//   4. r.defineEvent(name..., z.object({ ... }))
+//      Inline schema (call-expression instead of an identifier). We
+//      extract the call-source-text and emit it into a co-generated
+//      `schemas.generated.ts` as a named `export const`, then point
+//      the augmentation at that named export. The original feature
+//      file keeps its inline schema for runtime validation; the
+//      generated schemas-file exists ONLY for type-inference (consumed
+//      via `import type`, erased at build).
+//
+// What we still skip with a warning:
+//   - Default- or namespace-imports of the schema identifier
+//     (`import S from "..."`, `import * as M from "..."`). Rare in
+//     real apps; signal-to-noise of supporting them isn't worth it.
+//   - Computed names whose const cannot be statically resolved
+//     (cross-package re-exports, dynamic property access).
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { toKebab } from "@cosmicdrift/kumiko-framework/engine";
+import { Project, SyntaxKind, } from "ts-morph";
+/** Renders a `ScanWarning` for terminal output; omits the location prefix when the warning has no source line. */
+export function formatScanWarning(warning) {
+    return warning.file !== undefined
+        ? `${warning.file}:${warning.line} — ${warning.message}`
+        : warning.message;
+}
+/**
+ * Scant `appRoot/src/**` nach `r.defineEvent(...)`-Aufrufen und liefert
+ * eine deduplizierte Liste aus ScannedEvent. Doppelte qualifiedName
+ * landen mit einer Warnung in der Result — Codegen schreibt nur den
+ * ERSTEN, sodass das generated File compile-stabil bleibt.
+ */
+export function scanEvents(opts) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+    });
+    const filesToScan = [];
+    collectTsFiles(join(opts.appRoot, "src"), filesToScan);
+    // Add ALL files to the project up-front. ts-morph's symbol-resolver
+    // needs to see the file that declares the const-object before it can
+    // follow `INVOICE_EVENTS.sent` to its string literal.
+    for (const filePath of filesToScan) {
+        project.addSourceFileAtPath(filePath);
+    }
+    const events = [];
+    const warnings = [];
+    for (const filePath of filesToScan) {
+        const sourceFile = project.getSourceFile(filePath);
+        if (!sourceFile)
+            continue;
+        scanFile(sourceFile, filePath, events, warnings);
+    }
+    return { events: dedupe(events, warnings), warnings };
+}
+// ============================================================================
+// Internal — directory walk
+// ============================================================================
+const SKIP_SEGMENTS = new Set(["node_modules", ".kumiko", "dist", "dist-server", "__tests__"]);
+function collectTsFiles(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // skip: directory unreadable, nothing to scan there
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith("."))
+            continue;
+        if (SKIP_SEGMENTS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            collectTsFiles(full, out);
+        }
+        else if (stat.isFile() &&
+            (entry.endsWith(".ts") || entry.endsWith(".tsx")) &&
+            !entry.endsWith(".d.ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".test.tsx")) {
+            out.push(full);
+        }
+    }
+}
+// ============================================================================
+// Internal — per-file scan
+// ============================================================================
+function scanFile(sourceFile, filePath, events, warnings) {
+    // Find every defineFeature(...) — there may be multiple in factory-style
+    // packages (one factory function per feature). Each carries its own
+    // featureName (1st arg) + setup-arrow-function (2nd arg).
+    for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (call.getExpression().getText() !== "defineFeature")
+            continue;
+        const featureName = readStringLiteral(call.getArguments()[0]);
+        if (!featureName)
+            continue;
+        const setup = call.getArguments()[1]?.asKind(SyntaxKind.ArrowFunction);
+        if (!setup)
+            continue;
+        const registrarParam = setup.getParameters()[0]?.getName();
+        if (!registrarParam)
+            continue;
+        for (const defCall of setup.getBody().getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            const expr = defCall.getExpression().asKind(SyntaxKind.PropertyAccessExpression);
+            if (!expr)
+                continue;
+            if (expr.getExpression().getText() !== registrarParam)
+                continue;
+            if (expr.getName() !== "defineEvent")
+                continue;
+            collectFromDefineEvent(defCall, sourceFile, featureName, filePath, events, warnings);
+        }
+    }
+}
+function collectFromDefineEvent(call, sourceFile, featureName, filePath, events, warnings) {
+    const parsed = parseDefineEventCall(call);
+    if (!parsed) {
+        warnings.push({
+            file: filePath,
+            line: call.getStartLineNumber(),
+            message: "r.defineEvent: cannot read event-name + schema statically",
+        });
+        // skip: defineEvent call shape not statically parseable, already recorded as warning
+        return;
+    }
+    // Mirror the framework's `qn(toKebab(feature), "event", toKebab(name))`
+    // — the augmentation key MUST match what `r.defineEvent` writes at
+    // runtime. Without the kebab-step, `defineFeature("driverOrders")`
+    // would augment `driverOrders:event:*` while the runtime stream
+    // carries `driver-orders:event:*`, and strict-mode would reject every
+    // correct call.
+    const qualifiedName = `${toKebab(featureName)}:event:${toKebab(parsed.eventName)}`;
+    const schema = resolveSchemaSource(parsed.schemaNode, sourceFile, qualifiedName);
+    if (!schema) {
+        warnings.push({
+            file: filePath,
+            line: call.getStartLineNumber(),
+            message: `r.defineEvent("${parsed.eventName}"): schema "${parsed.schemaNode.getText()}" — not a named import nor an inline z.* call, skipped`,
+        });
+        // skip: schema source not resolvable, already recorded as warning
+        return;
+    }
+    events.push({
+        qualifiedName,
+        schemaSource: schema,
+        featureFilePath: filePath,
+        source: { file: filePath, line: call.getStartLineNumber() },
+    });
+}
+function parseDefineEventCall(call) {
+    const args = call.getArguments();
+    const first = args[0];
+    if (!first)
+        return undefined;
+    // Object-form: r.defineEvent({ name, schema, version? })
+    const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (obj && args.length === 1) {
+        const nameProp = obj
+            .getProperty("name")
+            ?.asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer();
+        const eventName = nameProp ? resolveStringLiteralOrConst(nameProp) : undefined;
+        if (!eventName)
+            return undefined;
+        const schemaNode = obj
+            .getProperty("schema")
+            ?.asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer();
+        if (!schemaNode)
+            return undefined;
+        return { eventName, schemaNode };
+    }
+    // Position-form: r.defineEvent(<name-source>, <schema-node>, ...)
+    const eventName = resolveStringLiteralOrConst(first);
+    const schemaNode = args[1];
+    if (!eventName || !schemaNode)
+        return undefined;
+    return { eventName, schemaNode };
+}
+/**
+ * Resolves a node to a string literal — either it IS a string-literal,
+ * or it's a property-access on a `const X = { ... } as const` object
+ * whose member resolves to one. Returns undefined for anything else
+ * (template literals, dynamic property access, function calls).
+ *
+ * Cross-file resolution: we follow the named import that brings the
+ * receiver-identifier into scope, load the target file from the same
+ * ts-morph project, and look up the const-declaration there. This
+ * works WITHOUT a TypeChecker — the import-graph + AST is enough for
+ * the patterns the recipes/showcases use (`as const` objects with
+ * string-literal members).
+ */
+function resolveStringLiteralOrConst(node) {
+    // Direct string-literal — fast path.
+    const direct = node.asKind(SyntaxKind.StringLiteral);
+    if (direct)
+        return direct.getLiteralValue();
+    // PropertyAccessExpression: `INVOICE_EVENTS.sent` form.
+    const propAccess = node.asKind(SyntaxKind.PropertyAccessExpression);
+    if (propAccess)
+        return resolvePropertyAccessLiteral(propAccess);
+    return undefined;
+}
+function resolvePropertyAccessLiteral(propAccess) {
+    const receiver = propAccess.getExpression().asKind(SyntaxKind.Identifier);
+    if (!receiver)
+        return undefined;
+    const memberName = propAccess.getName();
+    const callerFile = propAccess.getSourceFile();
+    // Two paths to find the const-declaration:
+    //   1. Local: declared in the same file before the call.
+    //   2. Imported: a named import points at another file in the project;
+    //      the const lives there as an `export const`.
+    const local = findConstObject(callerFile, receiver.getText());
+    if (local)
+        return readMemberLiteral(local, memberName);
+    for (const importDecl of callerFile.getImportDeclarations()) {
+        if (!matchesNamedImport(importDecl, receiver.getText()))
+            continue;
+        const targetFile = resolveImportedSourceFile(importDecl, callerFile);
+        if (!targetFile)
+            continue;
+        const remote = findConstObject(targetFile, receiver.getText());
+        if (remote) {
+            const literal = readMemberLiteral(remote, memberName);
+            if (literal !== undefined)
+                return literal;
+        }
+    }
+    return undefined;
+}
+/**
+ * Walk top-level statements for `const RECEIVER = { ... } [as const]`.
+ * Returns the inner object-literal if found.
+ */
+function findConstObject(sourceFile, receiverName) {
+    for (const stmt of sourceFile.getVariableStatements()) {
+        for (const decl of stmt.getDeclarations()) {
+            if (decl.getName() !== receiverName)
+                continue;
+            const init = unwrapAsConst(decl.getInitializer());
+            const objLit = init?.asKind(SyntaxKind.ObjectLiteralExpression);
+            if (objLit)
+                return objLit;
+        }
+    }
+    return undefined;
+}
+function readMemberLiteral(objLitNode, memberName) {
+    const objLit = objLitNode.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (!objLit)
+        return undefined;
+    const prop = objLit.getProperty(memberName)?.asKind(SyntaxKind.PropertyAssignment);
+    const initLit = prop?.getInitializer()?.asKind(SyntaxKind.StringLiteral);
+    return initLit?.getLiteralValue();
+}
+/**
+ * Resolve a relative import-specifier to a SourceFile already loaded
+ * in the project. Tries `<base>.ts` and `<base>/index.ts`. Returns
+ * undefined for npm-package specifiers (no local resolution needed —
+ * we don't follow anything beyond the app's own files).
+ */
+function resolveImportedSourceFile(importDecl, fromFile) {
+    const spec = importDecl.getModuleSpecifierValue();
+    if (!spec.startsWith("."))
+        return undefined;
+    const fromDir = fromFile.getDirectoryPath();
+    const project = fromFile.getProject();
+    const candidates = [`${spec}.ts`, `${spec}.tsx`, `${spec}/index.ts`, `${spec}/index.tsx`];
+    for (const cand of candidates) {
+        const abs = resolve(fromDir, cand);
+        const sf = project.getSourceFile(abs);
+        if (sf)
+            return sf;
+    }
+    return undefined;
+}
+/**
+ * `{ x: 1 } as const` parses as `AsExpression > ObjectLiteralExpression`.
+ * Strip the AsExpression so the caller can hit the inner literal directly.
+ */
+function unwrapAsConst(node) {
+    if (!node)
+        return undefined;
+    const asExpr = node.asKind(SyntaxKind.AsExpression);
+    return asExpr ? asExpr.getExpression() : node;
+}
+function readStringLiteral(node) {
+    return node?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
+}
+// ============================================================================
+// Internal — resolve schema node to its source kind
+// ============================================================================
+function resolveSchemaSource(schemaNode, sourceFile, qualifiedName) {
+    // Named identifier: schema lives in another file as a named export.
+    const ident = schemaNode.asKind(SyntaxKind.Identifier);
+    if (ident) {
+        const importInfo = resolveSchemaImport(sourceFile, ident.getText());
+        if (!importInfo)
+            return undefined;
+        return {
+            kind: "imported",
+            schemaIdentifier: ident.getText(),
+            schemaModulePath: importInfo.moduleSpecifier,
+        };
+    }
+    // Inline call: r.defineEvent("name", z.object({...})).
+    // We accept any call-expression that LOOKS like a zod schema (cheap
+    // structural check on the `z.*` head). The exact ".object/.string/etc"
+    // doesn't matter — the codegen will replay the source text in the
+    // schemas-file, where TS resolves z.infer correctly.
+    const callExpr = schemaNode.asKind(SyntaxKind.CallExpression);
+    if (callExpr && looksLikeZodCall(callExpr)) {
+        return {
+            kind: "inline",
+            schemaSource: callExpr.getText(),
+            generatedConstName: qualifiedNameToConstName(qualifiedName),
+        };
+    }
+    return undefined;
+}
+function looksLikeZodCall(call) {
+    // Walk the callee head — `z.something(...)` or `z.something.foo(...)`,
+    // anything that traces back to an Identifier `z`. Conservative: we
+    // don't try to verify it's the actual zod-import (the runtime check
+    // happens through the schemas-file's `import { z } from "zod"` anyway,
+    // which fails loudly if the user's `z` is something else).
+    let cur = call.getExpression();
+    while (cur.asKind(SyntaxKind.PropertyAccessExpression) || cur.asKind(SyntaxKind.CallExpression)) {
+        const prop = cur.asKind(SyntaxKind.PropertyAccessExpression);
+        if (prop) {
+            cur = prop.getExpression();
+            continue;
+        }
+        const innerCall = cur.asKind(SyntaxKind.CallExpression);
+        if (innerCall) {
+            cur = innerCall.getExpression();
+        }
+    }
+    return cur.asKind(SyntaxKind.Identifier)?.getText() === "z";
+}
+function resolveSchemaImport(sourceFile, identifier) {
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        if (matchesNamedImport(importDecl, identifier)) {
+            return { moduleSpecifier: importDecl.getModuleSpecifierValue() };
+        }
+    }
+    return undefined;
+}
+function matchesNamedImport(importDecl, identifier) {
+    for (const named of importDecl.getNamedImports()) {
+        // Handles both `import { x }` and `import { x as y }` — we want the
+        // LOCAL alias (what's used in the call site), which matches the
+        // identifier the scanner extracted.
+        const localName = named.getAliasNode()?.getText() ?? named.getNameNode().getText();
+        if (localName === identifier)
+            return true;
+    }
+    return false;
+}
+/**
+ * Stable identifier-safe rewrite of a qualifiedName like
+ * `pubsubOrders:event:order-placed` → `_kg_pubsubOrders__orderPlaced`.
+ * Used for the `export const` name in `schemas.generated.ts`. Same
+ * transform in scan + render keeps the two sides in sync.
+ */
+export function qualifiedNameToConstName(qualifiedName) {
+    // Drop the ":event:" infix — every entry has it, no information.
+    const withoutEventInfix = qualifiedName.replace(/:event:/g, "__");
+    // Replace remaining colons + dashes with `_` and camel-case after `_`
+    // so the output is identifier-legal AND visually parseable.
+    const sanitised = withoutEventInfix.replace(/[^A-Za-z0-9_]+(.?)/g, (_match, next) => next.toUpperCase());
+    return `_kg_${sanitised}`;
+}
+// ============================================================================
+// Internal — module-specifier rewriting + dedup
+// ============================================================================
+/**
+ * Resolves the relative schema-import path from the feature-file's
+ * point-of-view to a path relative to `.kumiko/` (which is where the
+ * generated d.ts file lives). Workspace-package specifiers
+ * (`@cosmicdrift/kumiko-...`) are returned as-is.
+ */
+export function rewriteImportPath(schemaModulePath, featureFilePath, outputDirAbs) {
+    // Workspace / npm specifiers — pass through. Codegen output imports
+    // them by name.
+    if (!schemaModulePath.startsWith("."))
+        return schemaModulePath;
+    const featureDir = featureFilePath.substring(0, featureFilePath.lastIndexOf(sep));
+    const absoluteSchemaPath = resolve(featureDir, schemaModulePath);
+    const fromOutput = relative(outputDirAbs, absoluteSchemaPath);
+    // POSIX-Slash für TS-imports (auch auf Windows).
+    const normalised = fromOutput.split(sep).join("/");
+    // Strip .ts/.tsx — TS module specifiers don't carry the extension;
+    // resolve() didn't add one but a hand-written ".ts" should be removed.
+    return normalised.replace(/\.tsx?$/, "");
+}
+function dedupe(events, warnings) {
+    const seen = new Map();
+    for (const ev of events) {
+        const existing = seen.get(ev.qualifiedName);
+        if (existing) {
+            warnings.push({
+                file: ev.source.file,
+                line: ev.source.line,
+                message: `duplicate r.defineEvent("${ev.qualifiedName}") — first declared at ${existing.source.file}:${existing.source.line}, ignored here`,
+            });
+            continue;
+        }
+        seen.set(ev.qualifiedName, ev);
+    }
+    return [...seen.values()];
+}

package/dist/codegen/watch.d.ts

@@ -0,0 +1,33 @@
+import { runCodegen } from "./run-codegen.js";
+export type WatchOptions = {
+    /** App-Wurzel — gleiche Bedeutung wie für `runCodegen`. */
+    readonly appRoot: string;
+    /** Optional: alle registrierten Write-Handler-QNs. Durchgereicht an
+     *  `runCodegen` für die Generierung der `WriteHandlerQn`-Union.
+     *  Der Dev-Server extrahiert sie beim Boot aus den Features und
+     *  reicht sie hier rein — der Watcher reicht sie bei jedem Re-Run
+     *  an `runCodegen` weiter, damit der generated-Type nicht verschwindet. */
+    readonly handlerQns?: readonly string[];
+    /** Wartet diese Millisekunden zusätzliche Events ab, bevor codegen
+     *  einmal fährt. 50ms catched typische save-bursts (Editor-Saves
+     *  feuern oft 2-3 Events: temp-file → rename → cleanup), bleibt aber
+     *  unmerklich für den User. */
+    readonly debounceMs?: number;
+    /** Callback nach jedem erfolgreichen Codegen-Pass. Default: stderr-
+     *  Log mit event-count + warnings. Wer den Output strukturiert
+     *  konsumieren will (Dev-Server-UI, IDE-Plugin), gibt einen eigenen
+     *  Handler. */
+    readonly onResult?: (result: ReturnType<typeof runCodegen>) => void;
+    /** Callback bei runCodegen-Fehlern. Default: stderr-Warning. */
+    readonly onError?: (err: unknown) => void;
+};
+export type WatchHandle = {
+    /** Beendet den Watcher. Idempotent — mehrfacher Aufruf ist no-op. */
+    readonly close: () => void;
+};
+/**
+ * Startet den Watcher. Beim Boot fährt einmalig `runCodegen` (sodass
+ * die generated Files sofort frisch sind), dann hängt sich an `fs.watch`
+ * und re-runs bei file-changes mit Debounce.
+ */
+export declare function watchAndRegenerate(opts: WatchOptions): WatchHandle;

package/dist/codegen/watch.js

@@ -0,0 +1,112 @@
+// watchAndRegenerate — file-watcher der bei jeder TS-Änderung unter
+// `<appRoot>/src/**` `runCodegen` neu fährt. Lebendige IDE-DX: User
+// editiert ein r.defineEvent, drückt save, das `.kumiko/types.generated.d.ts`
+// ist innerhalb von ~50ms aktualisiert, der TS-Sprachserver merkt es,
+// neue Auto-Complete-Vorschläge erscheinen ohne Server-Restart.
+//
+// Implementation: node:fs.watch (recursive) auf `<appRoot>/src/`.
+// Debounced damit ein batch-edit (z.B. find+replace via sed) nicht
+// 50× hintereinander feuert. Idempotent — runCodegen schreibt nur bei
+// echter Änderung, der Watcher kann ohne Schaden über-ruft werden.
+//
+// Nicht-Ziele: kein Watcher auf `node_modules`, `.kumiko`, `dist*`,
+// `__tests__` (gleicher SKIP-Set wie scan-events). fs.watch's
+// recursive-Mode liefert events für jede Subdir; wir filtern im
+// Callback.
+import { watch } from "node:fs";
+import { join } from "node:path";
+import { runCodegen } from "./run-codegen.js";
+import { formatScanWarning } from "./scan-events.js";
+const SKIP_SUBSTRINGS = ["/node_modules/", "/.kumiko/", "/dist/", "/dist-server/", "/__tests__/"];
+const DEFAULT_DEBOUNCE_MS = 50;
+/**
+ * Startet den Watcher. Beim Boot fährt einmalig `runCodegen` (sodass
+ * die generated Files sofort frisch sind), dann hängt sich an `fs.watch`
+ * und re-runs bei file-changes mit Debounce.
+ */
+export function watchAndRegenerate(opts) {
+    const debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const srcDir = join(opts.appRoot, "src");
+    let timer;
+    let watcher;
+    let closed = false;
+    const fire = () => {
+        try {
+            const result = runCodegen({
+                appRoot: opts.appRoot,
+                ...(opts.handlerQns !== undefined && { handlerQns: opts.handlerQns }),
+            });
+            if (opts.onResult) {
+                opts.onResult(result);
+            }
+            else {
+                if (result.warnings.length > 0) {
+                    for (const w of result.warnings) {
+                        // biome-ignore lint/suspicious/noConsole: codegen-watcher logs to terminal
+                        console.warn(`[codegen] ${formatScanWarning(w)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (opts.onError)
+                opts.onError(err);
+            else {
+                // biome-ignore lint/suspicious/noConsole: codegen-watcher logs to terminal
+                console.warn(`[codegen] regenerate failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    // Initial run — gleiches Verhalten wie wenn ein file-change kam, aber
+    // ohne Debounce (User wartet auf den ersten codegen).
+    fire();
+    try {
+        watcher = watch(srcDir, { recursive: true }, (_eventType, filename) => {
+            // skip: watcher closed or no filename reported, nothing to act on
+            if (closed || !filename)
+                return;
+            // node liefert filename relativ zu srcDir, kann aber posix oder
+            // windows-style separators haben. Wir prüfen substring-tolerant.
+            const normalised = `/${filename.toString().replace(/\\/g, "/")}`;
+            // skip: path matches an excluded segment (node_modules/dist/etc.)
+            if (SKIP_SUBSTRINGS.some((seg) => normalised.includes(seg)))
+                return;
+            // skip: Nur .ts/.tsx interessieren — alles andere (CSS, MD, JSON) hat
+            // keinen Einfluss auf r.defineEvent-Calls.
+            if (!normalised.endsWith(".ts") && !normalised.endsWith(".tsx"))
+                return;
+            // skip: .d.ts ausgenommen — die kommen meistens vom codegen selbst.
+            if (normalised.endsWith(".d.ts"))
+                return;
+            // skip: .test.ts/.test.tsx ausgenommen — Tests definieren keine
+            // Production-Features.
+            if (normalised.endsWith(".test.ts") || normalised.endsWith(".test.tsx"))
+                return;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(fire, debounceMs);
+        });
+    }
+    catch (err) {
+        // Watch failed (z.B. fs nicht recursive-fähig auf Linux ohne
+        // patches) — degraded mode: codegen läuft nur beim initial-call.
+        // User kriegt keine live-updates, aber das ist nicht fatal.
+        if (opts.onError)
+            opts.onError(err);
+        else {
+            // biome-ignore lint/suspicious/noConsole: codegen-watcher logs to terminal
+            console.warn(`[codegen] watcher failed to start (live-updates disabled): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        close: () => {
+            // skip: already closed, avoid double-close
+            if (closed)
+                return;
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            watcher?.close();
+        },
+    };
+}

package/dist/compose-stacks.d.ts

@@ -0,0 +1,60 @@
+import { type AuthMfaFeatureOptions } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { type LegalPagesOptions } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import { type UserDataRightsOptions } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export type FileProviderKind = "inmemory" | "s3" | "s3-env";
+export type MailTransportKind = "inmemory" | "smtp";
+export type GdprStackOrder = "retention-first" | "compliance-first";
+export type FileStackOptions = {
+    readonly providers: readonly FileProviderKind[];
+    readonly includeFilesFeature?: boolean;
+};
+export type MailStackOptions = {
+    readonly transports: readonly MailTransportKind[];
+};
+export type PagesStackOptions = {
+    readonly wrapLayout?: LegalPagesOptions["wrapLayout"];
+};
+export type GdprStackOptions = {
+    readonly order?: GdprStackOrder;
+    readonly sessions?: boolean;
+    readonly tenantLifecycle?: boolean;
+    /** Optional tokenVerifier provider(s) (e.g. PAT) when `sessions` is on.
+     *  Session-only stacks need none — sessions registers sessionStore, which
+     *  satisfies auth-foundation's boot check (#1570). Pass providers when the
+     *  app also wants Bearer/PAT auth. */
+    readonly providers?: readonly FeatureDefinition[];
+};
+export type UserDataRightsStackOptions = {
+    readonly userDataRights?: UserDataRightsOptions;
+    readonly includeDefaults?: boolean;
+};
+export type OpsStackOptions = {
+    readonly delivery?: boolean;
+    readonly audit?: boolean;
+    readonly jobs?: boolean;
+    readonly rateLimiting?: boolean;
+};
+/** sessions (+ optional auth-mfa). config/user/tenant/auth-email-password stay
+ *  on composeFeatures(includeBundled). Pass `mfa` options to mount TOTP.
+ *  When `sessions` is on (the default), auth-foundation is mounted alongside it —
+ *  the framework's registry now hard-requires it (sessions.requires("auth-foundation")).
+ *  Session-only is enough for boot (#1570); optional Bearer/PAT still needs a
+ *  tokenVerifier provider from the caller (e.g. createPersonalAccessTokensFeature
+ *  ({ scopes })) — PAT scopes are app-specific, so they stay caller-owned. */
+export type IdentityStackOptions = {
+    readonly sessions?: boolean;
+    readonly mfa?: AuthMfaFeatureOptions;
+};
+export declare function stackFeatureNames(features: readonly FeatureDefinition[]): string[];
+export declare function composePagesStack(options?: PagesStackOptions): FeatureDefinition[];
+export declare function composeRendererStack(): FeatureDefinition[];
+export declare function composeMailStack(options: MailStackOptions): FeatureDefinition[];
+export declare function composeFileStack(options: FileStackOptions): FeatureDefinition[];
+/** Retention + compliance (+ optional lifecycle/sessions). UDR/files mount separately — order varies per app. */
+export declare function composeGdprStack(options?: GdprStackOptions): FeatureDefinition[];
+export declare function composeUserDataRightsStack(options?: UserDataRightsStackOptions): FeatureDefinition[];
+export declare function composeOpsStack(options?: OpsStackOptions): FeatureDefinition[];
+/** Identity opt-ins: sessions by default; auth-mfa when `mfa` options given.
+ *  Do not also pass `sessions: true` to composeGdprStack — duplicate feature. */
+export declare function composeIdentityStack(options?: IdentityStackOptions): FeatureDefinition[];