@cosmicdrift/kumiko-dev-server 0.386.0 → 0.388.0

package/dist/create-kumiko-server-stack.js

@@ -0,0 +1,101 @@
+import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createMetricsForFactory } from "@cosmicdrift/kumiko-framework/observability";
+import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
+import { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+import { pushEntityProjectionTables, setupTestStack, } from "@cosmicdrift/kumiko-testing/stack";
+import { logInfo } from "./dev-server-runtime.js";
+import { isPersistentDevDb } from "./is-persistent-dev-db.js";
+// KUMIKO_DEV_DB_NAME switches the underlying testDb from ephemeral (fresh
+// kumiko_test_<random>, dropped on cleanup) to persistent (reuses the named
+// DB across restarts). The var is framework-scoped on purpose — every
+// dev-server pattern benefits from the same toggle, not just one sample.
+//
+// Redis is shared across boots AND across apps, so every boot needs its own
+// queue-name prefix — otherwise two dev/e2e servers running in parallel
+// drain each other's queues ("Unknown job: ..."). A persistent DB implies a
+// stable prefix so jobs survive a restart; an ephemeral DB gets a fresh
+// prefix per boot, matching the fresh DB.
+export function resolveDevDbMode(processEnv) {
+    const devDbName = processEnv["KUMIKO_DEV_DB_NAME"];
+    const persistentDb = isPersistentDevDb(processEnv);
+    const jobQueueNamePrefix = persistentDb
+        ? `kumiko-dev-${devDbName}`
+        : `kumiko-dev-${crypto.randomUUID()}`;
+    return { devDbName, persistentDb, jobQueueNamePrefix };
+}
+function buildDevStackOptions(options, dbMode) {
+    return {
+        features: options.features,
+        ...(dbMode.persistentDb && { dbName: dbMode.devDbName, persistentDb: true }),
+        ...(options.auth !== undefined && { authConfig: options.auth }),
+        ...(options.extraContext !== undefined && { extraContext: options.extraContext }),
+        ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
+        enrichAnonymousAccess: (base, deps) => resolveAnonymousAccessFromRegistry(base, deps),
+        ...(options.files !== undefined && { files: options.files }),
+        ...(options.effectiveFeatures !== undefined && {
+            effectiveFeatures: options.effectiveFeatures,
+        }),
+        ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
+        ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
+        ...(options.errorDocs && { errorDocs: options.errorDocs }),
+        // jobs.consumerLane unset = enqueuer-only; startDevJobRunners is the sole
+        // consumer/cron-scheduler per lane, so runOnBoot/cron jobs don't
+        // double-fire.
+        jobs: { queueNamePrefix: dbMode.jobQueueNamePrefix },
+    };
+}
+export async function bootDevStack(options, dbMode) {
+    logInfo(`[kumiko-server] booting Kumiko stack${dbMode.persistentDb ? ` — persistent DB "${dbMode.devDbName}"` : " — ephemeral test DB"}…`);
+    const stack = await setupTestStack(buildDevStackOptions(options, dbMode));
+    await createEventsTable(stack.db);
+    await pushEntityProjectionTables(stack, stack.registry);
+    // `extraRoutes` is already mounted by setupTestStack's buildServer();
+    // `wire` is for co-running components that need the system-write
+    // dispatcher but don't declare a route.
+    if (options.wire !== undefined) {
+        await options.wire({
+            db: stack.db,
+            // The raw ioredis client, not the TestRedis wrapper, matching runProdApp
+            // so application code sees the same interface in development and production.
+            redis: stack.redis.redis,
+            registry: stack.registry,
+            metricsFor: createMetricsForFactory(stack.observability.meter),
+            dispatchSystemWrite: makeDispatchSystemWrite(stack.dispatcher),
+            dispatchSystemQuery: makeDispatchSystemQuery(stack.dispatcher),
+        });
+    }
+    // Runs after the entity tables exist and before the server starts, so the
+    // first request sees seeded state. Persistent-DB mode runs it on every
+    // boot, so idempotence is the caller's responsibility.
+    if (options.onAfterSetup !== undefined) {
+        await options.onAfterSetup(stack);
+    }
+    return stack;
+}
+// setupTestStack configures but does not start the event dispatcher so
+// integration tests can drain it deterministically with runOnce(). The dev
+// server starts polling so SSE broadcasts reach connected clients.
+export async function startDevBackgroundRunners(stack, jobQueueNamePrefix) {
+    if (stack.eventDispatcher) {
+        await stack.eventDispatcher.start();
+    }
+    const redisUrl = `redis://${stack.redis.redis.options.host}:${stack.redis.redis.options.port}/${stack.redis.redis.options.db}`;
+    return startDevJobRunners({
+        registry: stack.registry,
+        db: stack.db,
+        // The stack's own AppContext, not a `{ db, registry }` literal: these
+        // runners consume the lanes, and a job reaching for ctx.files /
+        // ctx.notify / ctx.config would otherwise die here while the very same
+        // handler works on the request path.
+        context: stack.context,
+        redisUrl,
+        // Same dispatcher the request path writes through — without this,
+        // ctx.write/ctx.writeAs/ctx.queryAs inside a dev-run job throw on their
+        // first call.
+        dispatcher: stack.dispatcher,
+        // Must match setupTestStack's jobs.queueNamePrefix so enqueuer and
+        // consumer agree on queue names.
+        queueNamePrefix: jobQueueNamePrefix,
+    });
+}

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

@@ -0,0 +1,10 @@
+/// <reference types="bun-types" preserve="true" />
+import type { CreateKumikoServerOptions } from "./create-kumiko-server.ts";
+export declare const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
+export type TailwindPipeline = {
+    readonly outPath: string;
+    readonly kill: () => void;
+};
+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 startDevStylesheet(options: CreateKumikoServerOptions): Promise<TailwindPipeline | undefined>;

package/dist/create-kumiko-server-stylesheet.js

@@ -0,0 +1,137 @@
+/// <reference types="bun-types" preserve="true" />
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { canResolveTailwindStylesheet, resolveTailwindCli, } from "@cosmicdrift/kumiko-server-runtime/resolve-tailwind-cli";
+import { hasBun, logError, logInfo } from "./dev-server-runtime.js";
+// Duplicated in packages/testing/src/e2e/constants.ts: the Playwright config
+// runs under Node and cannot import this module.
+export const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
+// Resolves the path to the Tailwind entry CSS:
+//   - explicit string  → the resolved absolute path
+//   - false            → CSS pipeline off (undefined)
+//   - undefined + client entries:
+//       1. the app's own src/styles.css (theme override) if present
+//       2. else the default `@cosmicdrift/kumiko-renderer/web/styles.css` via package exports
+//   - undefined + no client entry: undefined (no CSS needed)
+//
+// The src/styles.css auto-detection mirrors build-prod-bundle:resolveStylesheetEntry
+// so dev and prod resolve identically. Without it every app would have to set
+// `stylesheet: "./src/styles.css"`, or dev would fall back to the default and
+// ignore the brand tokens.
+export function resolveStylesheet(options) {
+    if (options.stylesheet === false)
+        return undefined;
+    if (typeof options.stylesheet === "string")
+        return resolve(options.stylesheet);
+    const hasAnyEntry = options.clientEntry !== undefined ||
+        (options.clientEntries !== undefined && options.clientEntries.length > 0);
+    if (!hasAnyEntry)
+        return undefined;
+    // The app's own src/styles.css beats the renderer/web default, same as
+    // kumiko-build, so local and prod builds match.
+    const local = resolve(process.cwd(), "src/styles.css");
+    if (existsSync(local))
+        return local;
+    // Bun.resolveSync follows package exports: `"./styles.css"` in
+    // renderer/web's package.json resolves to the workspace file in the
+    // monorepo or the node_modules file in an installed app. Bun already
+    // returns an absolute filesystem path, so `fileURLToPath` is unnecessary.
+    if (!hasBun) {
+        // Node-based unit tests reach this branch. Without Bun, package-export
+        // resolution and a real Tailwind pipeline are unavailable, so skip
+        // silently rather than reporting an error.
+        return undefined;
+    }
+    try {
+        const resolved = Bun.resolveSync("@cosmicdrift/kumiko-renderer/web/styles.css", process.cwd());
+        if (!canResolveTailwindStylesheet(resolved, { bun: Bun, cwd: process.cwd() })) {
+            return undefined;
+        }
+        return resolved;
+    }
+    catch (err) {
+        logError("[kumiko-server] couldn't auto-resolve @cosmicdrift/kumiko-renderer/web/styles.css — " +
+            "pass `stylesheet: <path>` or `stylesheet: false` explicitly.", err);
+        return undefined;
+    }
+}
+// The E2E template can only reach an app's own server entry through its env,
+// so the env has to count whenever the option is left undefined.
+//
+// @internal — exported for unit tests only, not re-exported from the index.
+export function resolveStylesheetWatch(options, env = process.env) {
+    if (options.stylesheetWatch !== undefined)
+        return options.stylesheetWatch;
+    return env[STYLESHEET_WATCH_ENV] !== "0";
+}
+function runTailwindOneShotBuild(bunPath, cliPath, entryCss, outPath) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath], {
+            stdio: "inherit",
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`tailwind one-shot-build exit ${code}`));
+        });
+        child.on("error", rejectPromise);
+    });
+}
+// unref() so the watcher cannot outlive a crashed parent as an orphan.
+function spawnTailwindWatcher(bunPath, cliPath, entryCss, outPath) {
+    const watcher = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath, "--watch"], {
+        stdio: "inherit",
+    });
+    watcher.unref();
+    return () => {
+        try {
+            watcher.kill("SIGTERM");
+        }
+        catch {
+            // Already stopped or never started; no further action is needed.
+        }
+    };
+}
+// Non-fatal by design (returns undefined): if the CLI can't be resolved or
+// the initial build fails (flaky network, missing dependency), the server
+// boots without CSS instead of dying.
+async function startTailwindPipeline(entryCss, { watch }) {
+    const bunResolver = hasBun ? Bun : undefined;
+    const cliPath = resolveTailwindCli({ bun: bunResolver, cwd: process.cwd() });
+    if (cliPath === undefined) {
+        logError("[kumiko-server] @tailwindcss/cli nicht auflösbar — booting ohne CSS-Pipeline. " +
+            "`bun install` und Restart, um Styles zu aktivieren.");
+        return undefined;
+    }
+    const outDir = mkdtempSync(join(tmpdir(), "kumiko-tw-"));
+    const outPath = join(outDir, "styles.css");
+    logInfo(watch
+        ? `[kumiko-server] tailwind watcher → ${outPath}`
+        : `[kumiko-server] tailwind one-shot build → ${outPath}`);
+    const bunPath = process.argv[0] ?? "bun";
+    // Wait for the initial build so the first /styles.css request does not
+    // return 404; only then does the watcher take over.
+    try {
+        await runTailwindOneShotBuild(bunPath, cliPath, entryCss, outPath);
+    }
+    catch (err) {
+        logError("[kumiko-server] tailwind one-shot-build fehlgeschlagen — booting ohne CSS:", err);
+        return undefined;
+    }
+    if (!watch) {
+        return { outPath, kill: () => { } };
+    }
+    return { outPath, kill: spawnTailwindWatcher(bunPath, cliPath, entryCss, outPath) };
+}
+// The Tailwind CLI writes to a temp file that every /styles.css request reads
+// fresh: no in-memory signalling needed, and the browser only reloads after a
+// bundle rebuild anyway.
+export async function startDevStylesheet(options) {
+    const resolvedStylesheet = resolveStylesheet(options);
+    if (resolvedStylesheet === undefined)
+        return undefined;
+    return startTailwindPipeline(resolvedStylesheet, { watch: resolveStylesheetWatch(options) });
+}

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

@@ -0,0 +1,22 @@
+/// <reference types="bun-types" preserve="true" />
+import { type ClientBundle, type ClientBundleBuilder, type NormalizedEntry } from "./create-kumiko-server-client-bundles.ts";
+import { type DevReloadHub } from "./create-kumiko-server-reload.ts";
+export type DirectoryWatchEvents = (dir: string, options: {
+    readonly recursive: true;
+    readonly signal: AbortSignal;
+}) => AsyncIterable<{
+    readonly filename: string | null;
+}>;
+export declare function classifyChange(filename: string): "restart" | "hot-reload" | "ignore";
+export declare function classifyWatchedChange(watchedDir: string, filename: string, entrySourceFiles: ReadonlySet<string>): ReturnType<typeof classifyChange>;
+export type DevFileWatcherDeps = {
+    readonly entries: readonly NormalizedEntry[];
+    readonly watchDirs: readonly string[] | undefined;
+    readonly watchDirectory: DirectoryWatchEvents | undefined;
+    readonly signal: AbortSignal;
+    readonly buildBundle: ClientBundleBuilder;
+    readonly clientBundles: Map<string, ClientBundle>;
+    readonly reloadHub: DevReloadHub;
+    readonly stop: () => Promise<void>;
+};
+export declare function startDevFileWatchers(deps: DevFileWatcherDeps): void;

package/dist/create-kumiko-server-watcher.js

@@ -0,0 +1,155 @@
+/// <reference types="bun-types" preserve="true" />
+import { statSync } from "node:fs";
+import { watch } from "node:fs/promises";
+import { resolve } from "node:path";
+import { rebuildClientBundles, } from "./create-kumiko-server-client-bundles.js";
+import { broadcastReload } from "./create-kumiko-server-reload.js";
+import { logInfo } from "./dev-server-runtime.js";
+async function watchDir(dir, onChange, signal, watchEvents) {
+    // The server's stop() aborts the signal; without it, the for-await loop
+    // would continue until process exit. During test teardown, removing the
+    // temporary directory could then be classified as a restart and call
+    // process.exit(75), surfacing as an unhandled Vitest error.
+    const watcher = watchEvents(dir, { recursive: true, signal });
+    try {
+        for await (const ev of watcher) {
+            if (ev.filename)
+                onChange(ev.filename);
+        }
+    }
+    catch (err) {
+        // signal.abort() causes the async iterator to throw AbortError during
+        // expected teardown; other errors must propagate.
+        // skip: AbortSignal fired the abort, this is expected teardown not a real error
+        if (typeof err === "object" && err !== null && "name" in err && err.name === "AbortError")
+            return;
+        throw err;
+    }
+}
+const WATCHED_SOURCE_SUFFIXES = [".ts", ".tsx"];
+const TEST_ONLY_SUFFIXES = [
+    ".test.ts",
+    ".test.tsx",
+    ".integration.ts",
+    ".integration.test.ts",
+    ".e2e.ts",
+];
+const CLIENT_SUBDIRS = ["web", "admin", "public", "client"];
+const CLIENT_ENTRY_SUFFIXES = ["/client.tsx", "/client.ts"];
+function endsWithAny(filename, suffixes) {
+    return suffixes.some((suffix) => filename.endsWith(suffix));
+}
+function isTestOnlyFile(filename) {
+    return filename.includes("__tests__") || endsWithAny(filename, TEST_ONLY_SUFFIXES);
+}
+// Platform-independent: checks both POSIX and Windows separators. Matches
+// `<sep><dir><sep>` and a leading `<dir><sep>` for watcher filenames
+// supplied as relative paths.
+function isInClientSubdir(filename) {
+    return CLIENT_SUBDIRS.some((dir) => filename.includes(`/${dir}/`) ||
+        filename.includes(`\\${dir}\\`) ||
+        filename.startsWith(`${dir}/`) ||
+        filename.startsWith(`${dir}\\`));
+}
+// Classifies a changed file as `hot-reload` for client-side changes,
+// `restart` for server-side changes whose cached Bun modules must be
+// reloaded, or `ignore` when the server is unaffected.
+//
+// Tests and non-TypeScript files are ignored. TypeScript files under
+// `/web/`, `/admin/`, `/public/`, or `/client/`, as well as the client
+// entry itself, trigger hot reload; other TypeScript files trigger a
+// restart because they may contain schema or feature definitions.
+//
+// The multiple client directories are intentional: samples use different
+// layouts. Restarting for a client-only edit would be slower, drop the
+// ephemeral test database, and reseed it unnecessarily.
+export function classifyChange(filename) {
+    if (!endsWithAny(filename, WATCHED_SOURCE_SUFFIXES))
+        return "ignore";
+    if (isTestOnlyFile(filename))
+        return "ignore";
+    if (isInClientSubdir(filename) || endsWithAny(filename, CLIENT_ENTRY_SUFFIXES)) {
+        return "hot-reload";
+    }
+    return "restart";
+}
+// The watcher reports paths relative to the watched directory, so an entry arrives as a bare
+// "client.tsx" (or a custom name like "client-admin.tsx") that classifyChange alone reads as a
+// server file and answers with a restart.
+export function classifyWatchedChange(watchedDir, filename, entrySourceFiles) {
+    return entrySourceFiles.has(resolve(watchedDir, filename))
+        ? "hot-reload"
+        : classifyChange(filename);
+}
+// Expands watchDirs patterns into concrete directories. Entries without
+// `*` are resolved as ordinary paths; entries with `*` are glob-expanded
+// and only directory matches are retained, so `"../../../packages/*/src"`
+// replaces a list of hard-coded paths. Expansion runs once at boot,
+// not while the watcher is running.
+function expandWatchPatterns(patterns) {
+    const out = [];
+    for (const p of patterns) {
+        if (!p.includes("*")) {
+            out.push(resolve(p));
+            continue;
+        }
+        // Only reachable under Bun (createKumikoServer is Bun-only); without Bun the
+        // call stack fails fast in Bun.serve anyway.
+        if (typeof Bun === "undefined")
+            throw new Error("expandWatchPatterns requires Bun.Glob");
+        const glob = new Bun.Glob(p);
+        const matches = Array.from(glob.scanSync({ onlyFiles: false, cwd: process.cwd() }));
+        for (const m of matches) {
+            const abs = resolve(m);
+            try {
+                if (statSync(abs).isDirectory())
+                    out.push(abs);
+            }
+            catch {
+                // ignore unreadable matches, typically broken symlinks
+            }
+        }
+    }
+    return out;
+}
+// Because Bun caches module imports, a server-side change needs a process
+// restart: exit code 75 (EX_TEMPFAIL) lets the `kumiko-dev` wrapper respawn.
+async function handleWatchedChange(deps, dir, filename, entrySourceFiles) {
+    const action = classifyWatchedChange(dir, filename, entrySourceFiles);
+    // skip: file change classified as ignore (test/css/json), nothing to rebuild
+    if (action === "ignore")
+        return;
+    if (action === "restart") {
+        logInfo(`[kumiko-server] schema change in ${filename} — restarting (Bun caches imports, hot-reload reicht hier nicht). ` +
+            "The kumiko-dev wrapper (package.json's `dev` script) respawns automatically " +
+            "and re-syncs new r.entity() columns on the new boot; running this entry " +
+            "directly (not via kumiko-dev) exits here without restarting.");
+        await deps.stop();
+        process.exit(75);
+    }
+    try {
+        await rebuildClientBundles(deps.entries, deps.buildBundle, deps.clientBundles);
+        logInfo(`[kumiko-server] rebuilt on ${filename}, broadcasting reload`);
+        broadcastReload(deps.reloadHub, filename);
+    }
+    catch {
+        // buildClient already logged the failure; keep serving the
+        // last good bundle until the next successful rebuild.
+    }
+}
+// Watches every entry directory plus the explicit watchDirs. Multi-entry
+// setups often share one src/ directory, so the Set keeps one watcher per
+// directory.
+export function startDevFileWatchers(deps) {
+    // skip: without a client entry there is no bundle to rebuild, so watchDirs stay unwatched too
+    if (deps.entries.length === 0)
+        return;
+    const entryDirs = new Set();
+    for (const e of deps.entries)
+        entryDirs.add(resolve(e.sourceFile, ".."));
+    const entrySourceFiles = new Set(deps.entries.map((e) => resolve(e.sourceFile)));
+    const dirs = [...entryDirs, ...expandWatchPatterns(deps.watchDirs ?? [])];
+    for (const dir of dirs) {
+        void watchDir(dir, (filename) => handleWatchedChange(deps, dir, filename, entrySourceFiles), deps.signal, deps.watchDirectory ?? watch);
+    }
+}

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

@@ -1,12 +1,12 @@
 /// <reference types="bun-types" preserve="true" />
-import { type AuthRoutesConfig, type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import type { AuthRoutesConfig, ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
-import { type PageHeadResolver, type PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
-import { type SystemWireDeps } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
-import { type TestStack, type TestStackOptions } from "@cosmicdrift/kumiko-testing/stack";
-type BunServer = typeof Bun extends undefined ? unknown : ReturnType<typeof Bun.serve>;
-export declare const logInfo: (msg: string) => void;
+import type { PageHeadResolver, PageHeadSystemQuery } from "@cosmicdrift/kumiko-renderer/headless/apex";
+import type { SystemWireDeps } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+import type { TestStack, TestStackOptions } from "@cosmicdrift/kumiko-testing/stack";
+import { type DirectoryWatchEvents } from "./create-kumiko-server-watcher.ts";
+import { type BunServer } from "./dev-server-runtime.ts";
 /** Multi-entry mode for apps that ship several separate bundles (e.g.
  *  publicstatus: `admin.<base>` loads the admin UI, otherwise the public
  *  page).
@@ -22,10 +22,9 @@ export type DevClientEntry = {
      *  `kumiko.clientEntries[].name` so dev and prod produce identical
      *  asset URLs (`/client-<name>.js`). */
     readonly name: string;
-    /** Absoluter Pfad zur Browser-Entry-Datei. */
+    /** Absolute path to the browser entry file. */
     readonly sourceFile: string;
-    /** Optional eigenes HTML-Template für diesen Entry. Wenn nicht gesetzt,
-     *  wird `htmlPath` (das default-Template) für alle Entries genutzt. */
+    /** Optional HTML template for this entry. If omitted, `htmlPath` (the default template) is used for all entries. */
     readonly htmlPath?: string;
 };
 /** Dev counterpart of `runProdApp.hostDispatch`. Not the same shape: dev names
@@ -58,8 +57,7 @@ export type DevHostDispatchResult = {
     readonly entryName?: string;
     readonly file?: string;
 };
-/** Picks an entry by inspecting the incoming request. Wird von
- *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
+/** Picks an entry by inspecting the incoming request. Set by multi-entry apps; irrelevant in single-entry mode. */
 export type DevHostDispatch = (req: Request, deps: {
     readonly systemQuery: PageHeadSystemQuery;
     /** Always empty: dev serves no per-host CSP. */
@@ -69,27 +67,26 @@ 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
+    /** 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`. */
+     *  run a headless API-only dev stack. Mutually exclusive with
+     *  `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. */
+    /** Multi-entry mode: separate bundles served at
+     *  `/client-<name>.js`. Mutually exclusive with `clientEntry`. Set
+     *  `hostDispatch` as well; otherwise the server cannot determine which
+     *  template to return. */
     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. */
+    /** Multi-entry request routing. Inspects `Host` (or another request
+     *  property) and returns a discriminated union
+     *  (`html` → entry bundle, `redirect` → 30x, `not-found` → 404).
+     *  Mirrors `runProdApp.hostDispatch` so dev and production routing
+     *  remain aligned. */
     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. */
+    /** @internal — replaces `Bun.build` in tests. The default uses the real
+     *  Bun toolchain; Node-based tests inject a stub so the routing path can
+     *  run without calling Bun.build.
+     *  Not part of the public API; the `_` prefix identifies this test seam. */
     readonly _buildBundle?: (sourceFile: string) => Promise<{
         readonly js: string;
         readonly map: string;
@@ -128,41 +125,40 @@ export type CreateKumikoServerOptions = {
      *  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. */
+    /** Auth route configuration (login, tenants, switch-tenant, logout). When
+     *  set, disables automatic JWT minting on GET /; the client is responsible
+     *  for login. The corresponding features (user/tenant/auth-email-password)
+     *  must also be included through `features` for these routes to work. */
     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). */
+    /** Additional AppContext keys, such as `configResolver` for the config
+     *  feature. Forwarded to `setupTestStack`; see `TestStackOptions` for
+     *  the accepted shapes (object or 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. */
+    /** Enables anonymous access: requests without a JWT proceed as a
+     *  pseudo-user with the `anonymous` role when the handler declares
+     *  `roles: ["anonymous"]`. Tenant resolution uses a header, cookie, or
+     *  default; see `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:
+    /** File-storage provider forwarded to `setupTestStack`. When set, the
+     *  stack mounts the upload routes (POST/GET/DELETE /api/files), exposes
+     *  `ctx.files`, and creates the `file_refs` table. Example:
      *  `{ 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). */
+    /** Feature-toggle resolver forwarded to `setupTestStack`. When set, the
+     *  dispatcher feature gate, hook filter, and MSP filter consult it;
+     *  absent means all features remain enabled. Required for per-tenant
+     *  feature composition. The typical production implementation is
+     *  `() => globalFeatureToggleRuntime.effectiveFeatures` after boot,
+     *  using the createLateBoundHolder pattern because the runtime needs
+     *  `stack.db`. */
     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. */
+    /** Called after entity tables are set up. Use this hook for non-entity
+     *  tables (`unsafePushTables`) and seeding (admin user, initial tenant,
+     *  and so on). Must be idempotent because persistent-DB mode runs it on
+     *  every 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
+     *  symmetric to runProdApp.extraRoutes. 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[];
@@ -179,8 +175,8 @@ export type CreateKumikoServerOptions = {
     /** 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
+     *  `resolvePageHead`, so dev and e2e exercise the exact code prod does.
+     *  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
@@ -205,18 +201,4 @@ export type KumikoServerHandle = {
      *  its `bull:<prefix>-*` keys belong to this server alone on a shared Redis. */
     readonly jobQueueNamePrefix: string;
 };
-export declare const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
-export declare const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
-export declare const DEFAULT_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1,interactive-widget=resizes-content\" />\n    <title>Kumiko</title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/client.js\"></script>\n  </body>\n</html>\n";
-type DirectoryWatchEvents = (dir: string, options: {
-    readonly recursive: true;
-    readonly signal: AbortSignal;
-}) => AsyncIterable<{
-    readonly filename: string | null;
-}>;
-export declare function classifyChange(filename: string): "restart" | "hot-reload" | "ignore";
-export declare function classifyWatchedChange(watchedDir: string, filename: string, entrySourceFiles: ReadonlySet<string>): ReturnType<typeof classifyChange>;
-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 {};