@cosmicdrift/kumiko-dev-server 0.387.0 → 0.389.0

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

@@ -0,0 +1,206 @@
+/// <reference types="bun-types" preserve="true" />
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_URL_PREFIX, resolveRendererWebFontsDir, } from "@cosmicdrift/kumiko-server-runtime/renderer-web-fonts";
+import { stripNoRouteMatchHeader, tryHonoFirst, } from "@cosmicdrift/kumiko-server-runtime/try-hono-first";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { indexBundlesByAssetPath, } from "./create-kumiko-server-client-bundles.js";
+import { createDevSystemQueryBuilder, respondWithHtmlShell, respondWithStaticHtmlFile, } from "./create-kumiko-server-html.js";
+import { isRoutableGetOrHead, resolveDevPublicDir, servePublicFile, } from "./create-kumiko-server-public-files.js";
+import { openReloadStream } from "./create-kumiko-server-reload.js";
+const JAVASCRIPT_HEADERS = { "Content-Type": "application/javascript; charset=utf-8" };
+function serveClientBundle({ req, url }, deps) {
+    if (req.method !== "GET")
+        return undefined;
+    const bundleName = deps.bundleByAssetPath.get(url.pathname);
+    if (bundleName === undefined)
+        return undefined;
+    const bundle = deps.clientBundles.get(bundleName);
+    if (bundle === undefined)
+        return new Response("no bundle", { status: 404 });
+    return new Response(bundle.js, { headers: JAVASCRIPT_HEADERS });
+}
+// Looked up in the live bundles instead of a separate index, which a
+// hot-reload rebuild would leave stale.
+function serveBundleChunk({ req, url }, deps) {
+    if (req.method !== "GET")
+        return undefined;
+    for (const bundle of deps.clientBundles.values()) {
+        const chunk = bundle.chunks?.get(url.pathname);
+        if (chunk !== undefined)
+            return new Response(chunk, { headers: JAVASCRIPT_HEADERS });
+    }
+    return undefined;
+}
+function serveBundleSourceMap({ req, url }, deps) {
+    if (req.method !== "GET" || !url.pathname.endsWith(".js.map"))
+        return undefined;
+    const mapName = deps.bundleByAssetPath.get(url.pathname.slice(0, -".map".length));
+    if (mapName === undefined)
+        return undefined;
+    const bundle = deps.clientBundles.get(mapName);
+    if (bundle === undefined || !bundle.map)
+        return new Response("no map", { status: 404 });
+    return new Response(bundle.map, {
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+}
+async function serveRendererWebFont({ req, url }, deps) {
+    if (!url.pathname.startsWith(RENDERER_WEB_FONTS_URL_PREFIX) || req.method !== "GET") {
+        return undefined;
+    }
+    const fontFile = url.pathname.slice(RENDERER_WEB_FONTS_URL_PREFIX.length);
+    // The allowlist pattern excludes "/", "." segments and encoded traversal.
+    if (deps.rendererWebFontsDir === undefined || !RENDERER_WEB_FONT_FILE_PATTERN.test(fontFile)) {
+        return new Response("not found", { status: 404 });
+    }
+    try {
+        const bytes = await readFile(join(deps.rendererWebFontsDir, fontFile));
+        // @cast-boundary Buffer satisfies BodyInit at runtime, bun-types just doesn't say so.
+        return new Response(bytes, {
+            headers: { "Content-Type": "font/woff2", "Cache-Control": "public, max-age=86400" },
+        });
+    }
+    catch (err) {
+        if (errorCodeOf(err) === "ENOENT") {
+            return new Response("not found", { status: 404 });
+        }
+        throw err;
+    }
+}
+async function serveStylesheet({ req, url }, deps) {
+    if (url.pathname !== "/styles.css" || req.method !== "GET")
+        return undefined;
+    const { stylesheetPath } = deps.html;
+    if (stylesheetPath === undefined)
+        return new Response("no stylesheet", { status: 404 });
+    const css = await readFile(stylesheetPath, "utf-8");
+    return new Response(css, { headers: { "Content-Type": "text/css; charset=utf-8" } });
+}
+function serveReloadStream({ req, url }, deps) {
+    if (url.pathname !== "/_reload" || req.method !== "GET")
+        return undefined;
+    return openReloadStream(deps.reloadHub);
+}
+function respondToNotFoundDispatch(dispatch, { req, socketAddress }, html) {
+    if (dispatch.file !== undefined)
+        return respondWithStaticHtmlFile(dispatch.file, 404);
+    if (dispatch.entryName !== undefined) {
+        return respondWithHtmlShell(html, dispatch.entryName, req, socketAddress, 404);
+    }
+    return new Response("Not Found", { status: 404 });
+}
+// Discriminated dispatch mirrors production; anything that is not a
+// redirect, not-found or static-html result serves its entry's shell.
+function respondToHostDispatch(dispatch, request, html) {
+    switch (dispatch.kind) {
+        case "redirect":
+            return new Response(null, {
+                status: dispatch.status ?? 302,
+                headers: { Location: dispatch.to },
+            });
+        case "not-found":
+            return respondToNotFoundDispatch(dispatch, request, html);
+        case "static-html":
+            return respondWithStaticHtmlFile(dispatch.file, 200);
+        default:
+            return respondWithHtmlShell(html, dispatch.entryName, request.req, request.socketAddress);
+    }
+}
+// SPA catch-all: GET or HEAD requests to non-API, non-asset paths return
+// the HTML shell so the client-side router can mount the screen for
+// location.pathname. Paths containing a dot are left to the public/ lookup.
+//
+// HEAD is included because runProdApp falls back to the SPA for both GET and
+// HEAD. Backend routes outside /api (currently /sse) are excluded, and an
+// r.httpRoute outside /api is tried first, so only a Hono router miss falls
+// back to the shell, matching production.
+async function serveSpaShell(request, deps) {
+    const { req, url, socketAddress } = request;
+    if (!isRoutableGetOrHead(req, url.pathname) || url.pathname.includes("."))
+        return undefined;
+    const honoTry = await tryHonoFirst(deps.app, req, socketAddress);
+    if (honoTry.matched) {
+        return honoTry.response;
+    }
+    if (deps.hostDispatch === undefined) {
+        return respondWithHtmlShell(deps.html, "client", req, socketAddress);
+    }
+    const dispatch = await deps.hostDispatch(req, {
+        systemQuery: deps.html.buildSystemQuery(req, socketAddress),
+        cspScriptHashes: [],
+    });
+    return respondToHostDispatch(dispatch, request, deps.html);
+}
+// Static assets under public/ — prod serves these via buildStaticFallback's
+// disk lookup (run-prod-app-static-files.ts). Hono still goes first (an
+// r.httpRoute could itself own a dotted path), then the file on disk, then
+// the router-miss 404, mirroring the SPA branch.
+async function servePublicAsset({ req, url, socketAddress }, deps) {
+    if (!isRoutableGetOrHead(req, url.pathname) || !url.pathname.includes("."))
+        return undefined;
+    const honoTry = await tryHonoFirst(deps.app, req, socketAddress);
+    if (honoTry.matched) {
+        return honoTry.response;
+    }
+    const file = await servePublicFile(url.pathname, deps.publicDir);
+    if (file !== undefined) {
+        // @cast-boundary Buffer satisfies BodyInit at runtime, bun-types
+        // just doesn't say so — same cast run-prod-app-static-files.ts uses.
+        return new Response(file.bytes, {
+            headers: { "Content-Type": file.mime },
+        });
+    }
+    return honoTry.response;
+}
+// Specific routes first (assets, reload SSE), then the SPA shell and
+// public/ files; whatever is left goes to the Kumiko stack.
+const DEV_ROUTES = [
+    serveClientBundle,
+    serveBundleChunk,
+    serveBundleSourceMap,
+    serveRendererWebFont,
+    serveStylesheet,
+    serveReloadStream,
+    serveSpaShell,
+    servePublicAsset,
+];
+function createDevRouteFetch(deps) {
+    return async (req, socketAddress) => {
+        const request = { req, url: new URL(req.url), socketAddress };
+        for (const route of DEV_ROUTES) {
+            const response = await route(request, deps);
+            if (response !== undefined)
+                return response;
+        }
+        // Bypasses tryHonoFirst entirely (API paths, /sse, non-GET/HEAD), so the
+        // router-miss marker must be stripped here too — otherwise an unmatched
+        // path would leak it straight to the client (see try-hono-first.ts's
+        // header-hygiene note).
+        return stripNoRouteMatchHeader(await deps.app.fetch(req, socketAddress));
+    };
+}
+export function createDevFetchHandler(input) {
+    const { options, stack } = input;
+    const buildSystemQuery = createDevSystemQueryBuilder(stack.dispatcher, options.trustedProxyHops);
+    const routeFetch = createDevRouteFetch({
+        app: stack.app,
+        clientBundles: input.clientBundles,
+        bundleByAssetPath: indexBundlesByAssetPath(input.entries),
+        publicDir: resolveDevPublicDir(),
+        // The app's cwd first, this package's own location as fallback (the cwd
+        // may not have renderer/web installed, e.g. a fixture dir).
+        rendererWebFontsDir: resolveRendererWebFontsDir([process.cwd(), import.meta.dir]),
+        reloadHub: input.reloadHub,
+        hostDispatch: options.hostDispatch,
+        html: {
+            templates: input.templates,
+            jwt: stack.jwt,
+            autoMintJwt: options.auth === undefined,
+            stylesheetPath: input.stylesheetPath,
+            resolvePageHead: options.resolvePageHead,
+            buildSystemQuery,
+        },
+    });
+    return options.wrapFetch ? options.wrapFetch(routeFetch) : routeFetch;
+}

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

@@ -0,0 +1,14 @@
+/// <reference types="bun-types" preserve="true" />
+import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import type { DevDbMode, DevJobRunners } from "./create-kumiko-server-stack.ts";
+import { type BunServer } from "./dev-server-runtime.ts";
+export type DevServerStopDeps = {
+    readonly watcherAbort: AbortController;
+    readonly killTailwind: (() => void) | undefined;
+    readonly server: BunServer | undefined;
+    readonly stack: TestStack;
+    readonly devJobRunners: DevJobRunners;
+    readonly dbMode: DevDbMode;
+};
+export declare function createDevServerStop(deps: DevServerStopDeps): () => Promise<void>;
+export declare function installDevSignalHandlers(stop: () => Promise<void>): void;

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

@@ -0,0 +1,72 @@
+import { logError, logInfo } from "./dev-server-runtime.js";
+// The per-boot prefix is never reused, so its BullMQ keys (queues,
+// repeatables, delayed jobs) would pile up in the shared Redis forever.
+// Takes a prefix-less duplicate connection: SCAN returns full key names,
+// which the stack client's keyPrefix would otherwise prepend a second time.
+// The connection must be opened before stack.cleanup() closes the stack
+// client, yet used only after it, because closing the stack's enqueuer
+// queues re-writes their `meta` keys.
+async function deleteEphemeralJobQueues(raw, jobQueueNamePrefix) {
+    try {
+        const keys = [];
+        for await (const batch of raw.scanStream({
+            match: `bull:${jobQueueNamePrefix}-*`,
+            count: 500,
+        })) {
+            keys.push(...batch);
+        }
+        if (keys.length > 0)
+            await raw.del(...keys);
+    }
+    finally {
+        raw.disconnect();
+    }
+}
+export function createDevServerStop(deps) {
+    const { watcherAbort, killTailwind, server, stack, devJobRunners, dbMode } = deps;
+    return async () => {
+        // Stop the watcher first so no onChange callback runs during teardown;
+        // otherwise removing the temporary directory could trigger process.exit(75).
+        watcherAbort.abort();
+        if (killTailwind)
+            killTailwind();
+        if (server !== undefined) {
+            server.stop(true);
+        }
+        if (stack.eventDispatcher) {
+            await stack.eventDispatcher.stop();
+        }
+        await devJobRunners.stop();
+        const rawRedis = dbMode.persistentDb
+            ? undefined
+            : stack.redis.redis.duplicate({ keyPrefix: "" });
+        await stack.cleanup();
+        if (rawRedis)
+            await deleteEphemeralJobQueues(rawRedis, dbMode.jobQueueNamePrefix);
+    };
+}
+function stopAndExitOnCrash(event, stop) {
+    return async (err) => {
+        logError(`[kumiko-server] ${event} — cleaning up…`, err);
+        try {
+            await stop();
+        }
+        finally {
+            process.exit(1);
+        }
+    };
+}
+// Without these handlers, repeated dev restarts leak Postgres pools, leave
+// the Tailwind watcher as an orphan, and leave temporary clients behind in
+// persistent mode; a crash cleans up the same way before exiting nonzero.
+export function installDevSignalHandlers(stop) {
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, async () => {
+            logInfo(`[kumiko-server] ${sig} — cleaning up…`);
+            await stop();
+            process.exit(0);
+        });
+    }
+    process.on("uncaughtException", stopAndExitOnCrash("uncaughtException", stop));
+    process.on("unhandledRejection", stopAndExitOnCrash("unhandledRejection", stop));
+}

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

@@ -0,0 +1,12 @@
+import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
+import { type TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import type { CreateKumikoServerOptions } from "./create-kumiko-server.ts";
+export type DevDbMode = {
+    readonly devDbName: string | undefined;
+    readonly persistentDb: boolean;
+    readonly jobQueueNamePrefix: string;
+};
+export type DevJobRunners = Awaited<ReturnType<typeof startDevJobRunners>>;
+export declare function resolveDevDbMode(processEnv: Record<string, string | undefined>): DevDbMode;
+export declare function bootDevStack(options: CreateKumikoServerOptions, dbMode: DevDbMode): Promise<TestStack>;
+export declare function startDevBackgroundRunners(stack: TestStack, jobQueueNamePrefix: string): Promise<DevJobRunners>;

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

@@ -0,0 +1,102 @@
+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, makeFilesForTenant, } 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,
+            filesForTenant: makeFilesForTenant(stack.context),
+            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,135 @@
+/// <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 { resolveInstalledSync } from "@cosmicdrift/kumiko-server-runtime/resolve-installed-package";
+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;
+    }
+    const resolved = resolveInstalledSync("@cosmicdrift/kumiko-renderer/web/styles.css", process.cwd());
+    if (resolved === undefined) {
+        logError("[kumiko-server] couldn't auto-resolve @cosmicdrift/kumiko-renderer/web/styles.css — " +
+            "pass `stylesheet: <path>` or `stylesheet: false` explicitly.");
+        return undefined;
+    }
+    return canResolveTailwindStylesheet(resolved, { bun: Bun, cwd: process.cwd() })
+        ? resolved
+        : 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;