@cosmicdrift/kumiko-dev-server 0.328.1 → 0.330.0

package/dist/compose-stacks.js

@@ -0,0 +1,127 @@
+// @runtime runtime
+// Despite living in this "dev"-marked package, every preset here composes
+// @cosmicdrift/kumiko-bundled-features factories, and run-config.ts in every
+// app repo feeds it into the runProdApp boot path, not just runDevApp
+// (kumiko-framework#2337).
+//
+// Composable SaaS stack presets — explicit opt-in blocks for run-config.ts.
+// Presets export feature instances only; no implicit PAT scopes, anonymousAccess,
+// or tier maps (those stay in bin/server.ts / app run-config).
+import { createAuditFeature } from "@cosmicdrift/kumiko-bundled-features/audit";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createAuthMfaFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { fileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import { fileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
+import { fileProviderS3Feature } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import { fileProviderS3EnvFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3-env";
+import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
+import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
+import { createLegalPagesFeature, } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import { mailFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import { mailTransportInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
+import { mailTransportSmtpFeature } from "@cosmicdrift/kumiko-bundled-features/mail-transport-smtp";
+import { createRateLimitingFeature } from "@cosmicdrift/kumiko-bundled-features/rate-limiting";
+import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import { createRendererSimpleFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-simple";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createTenantLifecycleFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
+import { createUserDataRightsFeature, } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";
+export function stackFeatureNames(features) {
+    return features.map((f) => f.name);
+}
+export function composePagesStack(options = {}) {
+    // Pages content lives in template-resolver (kind text-block), which the
+    // renderer stack already mounts — an app composing pages WITHOUT the renderer
+    // stack has to add createTemplateResolverFeature() itself, or legal-pages'
+    // r.requires fails the boot. Mounting it here instead would collide with
+    // composeRendererStack (createRegistry rejects duplicate features).
+    return [
+        createLegalPagesFeature(options.wrapLayout !== undefined ? { wrapLayout: options.wrapLayout } : {}),
+    ];
+}
+export function composeRendererStack() {
+    return [
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createRendererSimpleFeature(),
+    ];
+}
+export function composeMailStack(options) {
+    const out = [mailFoundationFeature];
+    for (const transport of options.transports) {
+        if (transport === "inmemory")
+            out.push(mailTransportInMemoryFeature);
+        if (transport === "smtp")
+            out.push(mailTransportSmtpFeature);
+    }
+    return out;
+}
+export function composeFileStack(options) {
+    const out = [fileFoundationFeature];
+    for (const provider of options.providers) {
+        if (provider === "inmemory")
+            out.push(fileProviderInMemoryFeature);
+        if (provider === "s3")
+            out.push(fileProviderS3Feature);
+        if (provider === "s3-env")
+            out.push(fileProviderS3EnvFeature);
+    }
+    if (options.includeFilesFeature ?? true)
+        out.push(createFilesFeature());
+    return out;
+}
+/** Retention + compliance (+ optional lifecycle/sessions). UDR/files mount separately — order varies per app. */
+export function composeGdprStack(options = {}) {
+    const order = options.order ?? "retention-first";
+    const retention = createDataRetentionFeature();
+    const compliance = createComplianceProfilesFeature();
+    const out = order === "compliance-first" ? [compliance, retention] : [retention, compliance];
+    if (options.tenantLifecycle)
+        out.push(createTenantLifecycleFeature());
+    if (options.sessions) {
+        out.push(authFoundationFeature, createSessionsFeature());
+        if (options.providers)
+            out.push(...options.providers);
+    }
+    return out;
+}
+export function composeUserDataRightsStack(options = {}) {
+    const includeDefaults = options.includeDefaults ?? true;
+    const out = [createUserDataRightsFeature(options.userDataRights ?? {})];
+    if (includeDefaults)
+        out.push(createUserDataRightsDefaultsFeature());
+    return out;
+}
+export function composeOpsStack(options = {}) {
+    const delivery = options.delivery ?? true;
+    const audit = options.audit ?? true;
+    const jobs = options.jobs ?? true;
+    const rateLimiting = options.rateLimiting ?? false;
+    const out = [];
+    if (delivery)
+        out.push(createDeliveryFeature());
+    if (audit)
+        out.push(createAuditFeature());
+    if (jobs)
+        out.push(createJobsFeature());
+    if (rateLimiting)
+        out.push(createRateLimitingFeature());
+    return out;
+}
+/** Identity opt-ins: sessions by default; auth-mfa when `mfa` options given.
+ *  Do not also pass `sessions: true` to composeGdprStack — duplicate feature. */
+export function composeIdentityStack(options = {}) {
+    const sessions = options.sessions ?? true;
+    const out = [];
+    if (sessions) {
+        out.push(authFoundationFeature, createSessionsFeature());
+    }
+    if (options.mfa !== undefined)
+        out.push(createAuthMfaFeature(options.mfa));
+    return out;
+}

package/dist/crash-tracker.d.ts

@@ -0,0 +1,17 @@
+export type CrashTrackerOptions = {
+    readonly maxCrashes: number;
+    readonly windowMs: number;
+};
+export type CrashTracker = {
+    /** Crash bei `now` registrieren. Returns `true` wenn der Wrapper
+     *  noch respawnen darf, `false` wenn das Limit überschritten ist.
+     *
+     *  Der Crash wird IMMER aufgenommen, auch wenn `false` zurückkommt —
+     *  der Caller terminiert in dem Fall normalerweise eh. Reuse mit
+     *  "rejected → state unchanged"-Semantik wird nicht unterstützt. */
+    readonly noteCrash: (now: number) => boolean;
+    /** Anzahl Crashes im Fenster relativ zu `now` — prunt lazy, damit
+     *  der Aufruf auch ohne vorheriges noteCrash konsistent ist. */
+    readonly crashCountInWindow: (now: number) => number;
+};
+export declare function createCrashTracker(options: CrashTrackerOptions): CrashTracker;

package/dist/crash-tracker.js

@@ -0,0 +1,37 @@
+// Tracks server-Crashes in einem rollenden Zeitfenster und entscheidet,
+// ob der dev-wrapper noch respawnen darf oder den Crash-Loop aufgeben
+// muss. Liegt als eigener File, damit `kumiko-dev.ts` (bin-Script ohne
+// Test-Setup) eine pure, injizierbare API bekommt — die Logik ist
+// testbar via createCrashTracker, ohne den Wrapper-Prozess fahren zu
+// müssen.
+//
+// Semantik: ein Crash "zählt im Fenster", wenn er innerhalb der letzten
+// `windowMs` ms vor `now` registriert wurde. Wenn nach Aufnahme des
+// neuen Crashes mehr als `maxCrashes` im Fenster liegen, gibt der
+// Tracker `false` zurück → Wrapper soll aufgeben.
+export function createCrashTracker(options) {
+    const timestamps = [];
+    const pruneBefore = (cutoff) => {
+        // Crashes älter als `cutoff` raus. Gleicher Timestamp wie cutoff
+        // bleibt drin (`<` statt `<=`) — symmetrisch zur Fenster-Definition
+        // "innerhalb der letzten windowMs", also Endpoint inklusive.
+        while (timestamps.length > 0) {
+            const head = timestamps[0];
+            if (head !== undefined && head < cutoff)
+                timestamps.shift();
+            else
+                break;
+        }
+    };
+    return {
+        noteCrash: (now) => {
+            pruneBefore(now - options.windowMs);
+            timestamps.push(now);
+            return timestamps.length <= options.maxCrashes;
+        },
+        crashCountInWindow: (now) => {
+            pruneBefore(now - options.windowMs);
+            return timestamps.length;
+        },
+    };
+}

package/dist/create-kumiko-server.d.ts

@@ -0,0 +1,195 @@
+/// <reference types="bun-types" preserve="true" />
+import { type AuthRoutesConfig, type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type TestStack, type TestStackOptions } from "@cosmicdrift/kumiko-framework/stack";
+import { type PageHeadResolver, type PageHeadSystemQuery } from "@cosmicdrift/kumiko-headless/apex";
+import { type SystemWireDeps } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+type BunServer = typeof Bun extends undefined ? unknown : ReturnType<typeof Bun.serve>;
+/** Multi-entry mode for apps that ship several separate bundles (e.g.
+ *  publicstatus: `admin.<base>` loads the admin UI, otherwise the public
+ *  page).
+ *
+ *  kumiko-build reads the same entry list from package.json
+ *  `kumiko.clientEntries` and serves `/client-<name>.js` per HTTP — the
+ *  dev server and the prod build stay in sync via that shared declaration,
+ *  not a filename convention. Mutually exclusive with `clientEntry`.
+ *  Multi-entry apps MUST also set `hostDispatch` — otherwise the server
+ *  has no way to know which HTML to serve. */
+export type DevClientEntry = {
+    /** Logical name. Should match the corresponding package.json
+     *  `kumiko.clientEntries[].name` so dev and prod produce identical
+     *  asset URLs (`/client-<name>.js`). */
+    readonly name: string;
+    /** Absoluter Pfad zur Browser-Entry-Datei. */
+    readonly sourceFile: string;
+    /** Optional eigenes HTML-Template für diesen Entry. Wenn nicht gesetzt,
+     *  wird `htmlPath` (das default-Template) für alle Entries genutzt. */
+    readonly htmlPath?: string;
+};
+/** Discriminated union, identical in shape to `runProdApp.hostDispatch`, so
+ *  dev/prod routing mirrors 1:1 — an apex 404 in prod is an apex 404 in dev
+ *  (with an `/etc/hosts` entry for the affected domain). HTML never carries
+ *  a schema, in dev or prod — createKumikoApp fetches it itself from the
+ *  authenticated GET /api/schema. */
+export type DevHostDispatchResult = {
+    readonly kind: "html";
+    readonly entryName: string;
+    /** @deprecated Ignored — HTML never carries the schema; createKumikoApp
+     *  fetches it from the authenticated GET /api/schema. */
+    readonly injectSchema?: boolean;
+} | {
+    /** Static HTML: serves a file verbatim, no bundle injection. Mirrors
+     *  prod's `{ kind: "html", file: ... }` for marketing/apex pages that
+     *  don't need React. Path relative to the server CWD. */
+    readonly kind: "static-html";
+    readonly file: string;
+} | {
+    readonly kind: "redirect";
+    readonly to: string;
+    readonly status?: 301 | 302;
+} | {
+    readonly kind: "not-found";
+};
+/** Picks an entry by inspecting the incoming request. Wird von
+ *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
+export type DevHostDispatch = (req: Request, deps: {
+    readonly systemQuery: PageHeadSystemQuery;
+}) => DevHostDispatchResult | Promise<DevHostDispatchResult>;
+export type CreateKumikoServerOptions = {
+    /** Features whose entities, handlers, and screens get wired into the
+     *  dev stack. Pass every feature the app is supposed to run. */
+    readonly features: readonly FeatureDefinition[];
+    /** Absolute path to the browser entry module. The dev-server runs
+     *  `Bun.build` on it and serves the output at `/client.js`. Omit to
+     *  run a headless API-only dev-stack (rare — every sample has one).
+     *  Mutually exclusive mit `clientEntries`. */
+    readonly clientEntry?: string;
+    /** Multi-Entry-Mode: mehrere getrennte Bundles, jeweils unter
+     *  `/client-<name>.js`. Mutually exclusive mit `clientEntry`. Setze
+     *  `hostDispatch` mit, sonst bleibt unklar welches Template zurück-
+     *  geht. */
+    readonly clientEntries?: readonly DevClientEntry[];
+    /** Multi-Entry-Mode: Routing pro Request. Inspiziert `Host` (oder
+     *  was auch immer) und liefert eine Discriminated-Union zurück
+     *  (html → entry-bundle, redirect → 30x, not-found → 404).
+     *  Symmetric zu `runProdApp.hostDispatch` damit dev/prod-Drift
+     *  beim Routing unmöglich ist. */
+    readonly hostDispatch?: DevHostDispatch;
+    /** @internal — ersetzt `Bun.build` für Tests. Default ruft die echte
+     *  Bun-Toolchain. Tests unter Node injizieren einen Stub damit der
+     *  Routing-Pfad treibbar bleibt ohne Bun.build aufzurufen.
+     *  KEIN Public-API-Surface — präfixiert mit `_` damit Konsumenten
+     *  wissen dass das ein Test-Seam ist. */
+    readonly _buildBundle?: (sourceFile: string) => Promise<{
+        readonly js: string;
+        readonly map: string;
+    }>;
+    /** Absolute path to the CSS entry (typically styles.css with
+     *  @import "tailwindcss"). The dev-server builds it with the Tailwind
+     *  CLI and serves the result at /styles.css; `stylesheetWatch` decides
+     *  whether the CLI keeps running with `--watch` afterwards.
+     *
+     *  When `undefined` and a client entry is set, the app's own
+     *  src/styles.css wins, otherwise `@cosmicdrift/kumiko-renderer-web/styles.css`
+     *  resolves via package exports, so no sample hardcodes a monorepo-relative path.
+     *
+     *  `stylesheet: false` disables the CSS pipeline. */
+    readonly stylesheet?: string | false;
+    /** `true`: the Tailwind CLI keeps running with `--watch` after the
+     *  initial build. `false`: CSS is built once at boot, no watcher.
+     *  When `undefined`, env `KUMIKO_DEV_STYLESHEET_WATCH=0` means `false`,
+     *  anything else `true`. `defineAppE2eConfig` sets that env: Tailwind v4
+     *  subscribes to the whole app cwd without a gitignore filter, so every
+     *  Playwright artifact write under test-results/ would trigger a rebuild. */
+    readonly stylesheetWatch?: boolean;
+    /** Optional HTML template served at `GET /`. The dev-server injects
+     *  a `<script type="module" src="/client.js">` and a reload-listener
+     *  snippet into `</body>` if those aren't already there. Defaults to a
+     *  minimal empty-body document — enough to boot the client. */
+    readonly htmlPath?: string;
+    /** Port to listen on. Default 4173. Overridable via `PORT` env. */
+    readonly port?: number;
+    /** Extra directories to watch for reload triggers. The entry's
+     *  directory is watched automatically. */
+    readonly watchDirs?: readonly string[];
+    /** When false, no SIGINT/SIGTERM handlers are installed. Tests set
+     *  this so repeated `createKumikoServer` calls don't accumulate
+     *  listeners on the process. Default true (dev-server behaviour). */
+    readonly installSignalHandlers?: boolean;
+    /** Auth-Route-Config (login, tenants, switch-tenant, logout). Wenn
+     *  gesetzt wird die Auto-JWT-Mint auf GET / abgeschaltet — der
+     *  Client ist dann selbst fürs Login zuständig. Zur echten Wirkung
+     *  brauchen die dazugehörigen Features (user/tenant/auth-email-
+     *  password) via `features` drin sein. */
+    readonly auth?: AuthRoutesConfig;
+    /** Extra-AppContext-Keys (z.B. configResolver für config-feature).
+     *  Wird an setupTestStack weitergereicht. Siehe TestStackOptions
+     *  für die erlaubten Shapes (object oder factory-function). */
+    readonly extraContext?: TestStackOptions["extraContext"];
+    /** Anonymous-Access aktivieren — Requests ohne JWT werden als
+     *  Pseudo-User mit Rolle `anonymous` durchgelassen, sofern der
+     *  Handler `roles: ["anonymous"]` deklariert. Tenant-Resolution per
+     *  Header/Cookie/Default; siehe AnonymousAccessConfig. */
+    readonly anonymousAccess?: TestStackOptions["anonymousAccess"];
+    /** File-Storage-Provider — durchgereicht an setupTestStack. Wenn gesetzt,
+     *  mountet der Stack die Upload-Routes (POST/GET/DELETE /api/files) +
+     *  `ctx.files` und legt die file_refs-Tabelle an. Für Demos:
+     *  `{ storageProvider: createInMemoryFileProvider() }`. */
+    readonly files?: TestStackOptions["files"];
+    /** Feature-toggle resolver — durchgereicht an setupTestStack. Wenn
+     *  gesetzt, konsultiert der dispatcher-feature-gate, hook-filter, MSP-
+     *  filter den callback; absent = alle features always-on. Erforderlich
+     *  für Tier-Composition (Sprint 8) wo per-Tenant unterschiedliche
+     *  features aktiv sein sollen. Die typische produktive Implementierung
+     *  ist `() => globalFeatureToggleRuntime.effectiveFeatures` post-boot
+     *  (createLateBoundHolder-pattern, weil runtime stack.db braucht). */
+    readonly effectiveFeatures?: TestStackOptions["effectiveFeatures"];
+    /** Wird nach dem Aufsetzen der Entity-Tabellen aufgerufen. Hook für
+     *  non-entity-tables (unsafePushTables) und Seeding (admin user, initial
+     *  tenant, …). Muss idempotent sein — im persistent-DB-Modus läuft
+     *  es bei jedem Boot. */
+    readonly onAfterSetup?: (stack: TestStack) => Promise<void>;
+    /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
+     *  symmetric to runProdApp.extraRoutes (kumiko-framework#3050). Mounted
+     *  inside buildServer (setupTestStack), before the Static/HTML-fallback,
+     *  so an own GET (/feed.xml, /og-image, …) wins over the dev-asset path. */
+    readonly extraRoutes?: readonly ExtraRouteDefinition[];
+    /** Forwarded to setupTestStack → buildServer's top-level
+     *  `ServerOptions.trustedProxyHops`. Dev usually runs unproxied, so this
+     *  is normally left unset (default 0). */
+    readonly trustedProxyHops?: number;
+    /** Hook for app-wired co-running components that need the system-write
+     *  dispatcher — runs after buildServer, before onAfterSetup (seeds), with
+     *  NO `app` (routes are declared via `extraRoutes`, not wired here). */
+    readonly wire?: (deps: SystemWireDeps) => void | Promise<void>;
+    /** Per-request head-metadata resolver (Open-Graph/title/description) —
+     *  same option, same `PageHeadResolver` signature, and same shared
+     *  resolve+inject call (`resolveAndInjectPageHead`) as `runProdApp`'s
+     *  `resolvePageHead`, so dev and e2e exercise the exact code prod does
+     *  (kumiko-framework#3026). Consulted for every templated HTML response
+     *  (the default single-entry shell and a host-dispatched `"html"` entry),
+     *  right before it's served. On error, `null`, or a timeout, the shell
+     *  ships unchanged with status 200 — never a 500. `systemQuery` inside
+     *  the resolver runs as the anonymous role, same as prod. */
+    readonly resolvePageHead?: PageHeadResolver;
+};
+export type KumikoServerHandle = {
+    /** The fetch handler that routes a Request through the dev-server
+     *  layer (HTML, /client.js, /_reload, SSE) and falls back to the
+     *  underlying Kumiko stack. Tests call this directly to exercise
+     *  the routing without going through real sockets. */
+    readonly fetch: (req: Request) => Promise<Response>;
+    /** Bun.serve instance. `undefined` when running outside Bun (e.g.
+     *  in vitest under Node) — the handle still works via `.fetch`. */
+    readonly server: BunServer | undefined;
+    readonly stack: TestStack;
+    /** Stops the server and tears down the stack (DB + redis). */
+    readonly stop: () => Promise<void>;
+};
+export declare const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
+export declare const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
+export declare function classifyChange(filename: string): "restart" | "hot-reload" | "ignore";
+export declare function resolveStylesheet(options: CreateKumikoServerOptions): string | undefined;
+export declare function resolveStylesheetWatch(options: Pick<CreateKumikoServerOptions, "stylesheetWatch">, env?: Readonly<Record<string, string | undefined>>): boolean;
+export declare function createKumikoServer(options: CreateKumikoServerOptions): Promise<KumikoServerHandle>;
+export {};