@cosmicdrift/kumiko-dev-server 0.304.0 → 0.305.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.304.0",
+  "version": "0.305.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -59,10 +59,10 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.304.0",
-    "@cosmicdrift/kumiko-framework": "0.304.0",
-    "@cosmicdrift/kumiko-headless": "0.304.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.304.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.305.0",
+    "@cosmicdrift/kumiko-framework": "0.305.0",
+    "@cosmicdrift/kumiko-headless": "0.305.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.305.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/create-kumiko-server.integration.test.ts

@@ -17,7 +17,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
-import { createKumikoServer, type KumikoServerHandle } from "../create-kumiko-server";
+import {
+  createKumikoServer,
+  type KumikoServerHandle,
+  STYLESHEET_WATCH_ENV,
+} from "../create-kumiko-server";
 
 const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
 
@@ -471,6 +475,45 @@ describe("createKumikoServer — stylesheet tailwind failure (graceful)", () =>
   });
 });
 
+describe("createKumikoServer — stylesheet watch disabled via env", () => {
+  test("KUMIKO_DEV_STYLESHEET_WATCH=0 serves the built CSS and never spawns a --watch process", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-css-no-watch-"));
+    const entryCss = join(tmpDir, "styles.css");
+    // Plain CSS, no `@import "tailwindcss"` — the marker property survives
+    // the Tailwind CLI/lightningcss pass unchanged, unlike a color value
+    // which lightningcss may renormalize.
+    writeFileSync(entryCss, ".kumiko-probe { --probe-marker: 42; }\n");
+    const previousWatchEnv = process.env[STYLESHEET_WATCH_ENV];
+    process.env[STYLESHEET_WATCH_ENV] = "0";
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+        stylesheet: entryCss,
+      });
+
+      const cssRes = await handle.fetch(new Request("http://localhost/styles.css"));
+      expect(cssRes.status).toBe(200);
+      const css = await cssRes.text();
+      expect(css).toContain("--probe-marker: 42");
+
+      // -ww: unwrapped, full argv — a truncated args column would make the
+      // negative assert below pass vacuously. The pid check proves ps
+      // actually returned live process rows on this machine/CI runner.
+      const ps = Bun.spawnSync(["ps", "-A", "-ww", "-o", "pid=,args="]);
+      const psOutput = ps.stdout.toString();
+      const lines = psOutput.split("\n");
+      expect(lines.some((line) => line.includes(String(process.pid)))).toBe(true);
+      expect(lines.some((line) => line.includes(entryCss) && line.includes("--watch"))).toBe(false);
+    } finally {
+      if (previousWatchEnv === undefined) delete process.env[STYLESHEET_WATCH_ENV];
+      else process.env[STYLESHEET_WATCH_ENV] = previousWatchEnv;
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("createKumikoServer — real Bun.build (buildClient)", () => {
   test("clientEntry without _buildBundle produces a JS bundle via Bun.build", async () => {
     const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-real-build-"));

package/src/__tests__/resolve-stylesheet.test.ts

@@ -11,7 +11,11 @@ import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { resolveStylesheet } from "../create-kumiko-server";
+import {
+  resolveStylesheet,
+  resolveStylesheetWatch,
+  STYLESHEET_WATCH_ENV,
+} from "../create-kumiko-server";
 
 describe("resolveStylesheet", () => {
   test("string → resolved absolute path", () => {
@@ -108,3 +112,21 @@ describe("resolveStylesheet", () => {
     }
   });
 });
+
+describe("resolveStylesheetWatch", () => {
+  test("an explicit option wins over the env", () => {
+    expect(resolveStylesheetWatch({ stylesheetWatch: false }, {})).toBe(false);
+    expect(resolveStylesheetWatch({ stylesheetWatch: true }, { [STYLESHEET_WATCH_ENV]: "0" })).toBe(
+      true,
+    );
+  });
+
+  test("no option, env=0 → false", () => {
+    expect(resolveStylesheetWatch({}, { [STYLESHEET_WATCH_ENV]: "0" })).toBe(false);
+  });
+
+  test("no option, no or other env value → true", () => {
+    expect(resolveStylesheetWatch({}, {})).toBe(true);
+    expect(resolveStylesheetWatch({}, { [STYLESHEET_WATCH_ENV]: "1" })).toBe(true);
+  });
+});

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "createKumikoServer/runDevApp gain stylesheetWatch (env KUMIKO_DEV_STYLESHEET_WATCH=0) to build Tailwind CSS once without a --watch process",
+    "detail": "`defineAppE2eConfig` sets `KUMIKO_DEV_STYLESHEET_WATCH=0`, so the dev-server it boots builds CSS once and stops instead of keeping a Tailwind `--watch` process alive. Tailwind v4's watcher subscribes to the whole app cwd recursively with no gitignore filter, so every Playwright artifact write under `test-results/` previously counted as a rebuild trigger."
+  },
   {
     "version": "0.301.0",
     "type": "fix",

package/src/create-kumiko-server.ts

@@ -162,18 +162,24 @@ export type CreateKumikoServerOptions = {
     readonly js: string;
     readonly map: string;
   }>;
-  /** Absolute path to the CSS entry (typischerweise styles.css mit
-   *  @import "tailwindcss"). Der dev-server startet dann den
-   *  Tailwind-CLI als watcher und servt das kompilierte CSS unter
-   *  /styles.css.
+  /** 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.
    *
-   *  Wenn `undefined` UND `clientEntry` gesetzt: resolve die
-   *  `@cosmicdrift/kumiko-renderer-web/styles.css`-Default via Package-Exports.
-   *  So muss kein Sample mehr den monorepo-relativen Pfad
-   *  ../../packages/renderer-web/src/styles.css hardcoden.
+   *  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` → CSS-Pipeline explizit deaktivieren. */
+   *  `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
@@ -259,6 +265,10 @@ export type KumikoServerHandle = {
 const CSRF_COOKIE = "kumiko_csrf";
 const AUTH_COOKIE = "kumiko_auth";
 
+// 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";
+
 // Reload snippet injected into every page-load so the browser
 // subscribes to /_reload without the HTML needing to hard-code it.
 //
@@ -661,12 +671,24 @@ export function resolveStylesheet(options: CreateKumikoServerOptions): string |
   }
 }
 
-// Startet den Tailwind-CLI als watch-Prozess. Failure-Mode ist
-// non-fatal (return undefined): kann der CLI nicht resolved werden
-// oder failt der initial-Build (z.B. flakiges Netz, fehlende
-// Dependency), bootet der Server ohne CSS statt zu sterben.
-async function startTailwindWatcher(
+// 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: Pick<CreateKumikoServerOptions, "stylesheetWatch">,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (options.stylesheetWatch !== undefined) return options.stylesheetWatch;
+  return env[STYLESHEET_WATCH_ENV] !== "0";
+}
+
+// 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: string,
+  { watch }: { readonly watch: boolean },
 ): Promise<{ outPath: string; kill: () => void } | undefined> {
   const bunResolver = hasBun
     ? (globalThis as { Bun: { resolveSync: (id: string, from: string) => string } }).Bun
@@ -681,7 +703,11 @@ async function startTailwindWatcher(
   }
   const outDir = mkdtempSync(join(tmpdir(), "kumiko-tw-"));
   const outPath = join(outDir, "styles.css");
-  logInfo(`[kumiko-server] tailwind watcher → ${outPath}`);
+  logInfo(
+    watch
+      ? `[kumiko-server] tailwind watcher → ${outPath}`
+      : `[kumiko-server] tailwind one-shot build → ${outPath}`,
+  );
   const bunPath = process.argv[0] ?? "bun";
   // Initial-Build blockend, damit der erste /styles.css-Request kein
   // 404 bekommt. Dann den watcher im Hintergrund mit unref() — sonst
@@ -701,6 +727,9 @@ async function startTailwindWatcher(
     logError("[kumiko-server] tailwind one-shot-build fehlgeschlagen — booting ohne CSS:", err);
     return undefined;
   }
+  if (!watch) {
+    return { outPath, kill: () => {} };
+  }
   const watcher = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath, "--watch"], {
     stdio: "inherit",
   });
@@ -775,21 +804,20 @@ export async function createKumikoServer(
   }
 
   // --- Tailwind stylesheet (optional) ---
-  // Tailwind-CLI läuft im watch-mode, schreibt in ein temp-file, der
-  // dev-server liest es bei jedem /styles.css-Request frisch. Nicht
-  // Super-Performant, aber keine in-memory-Signal-Gymnastik nötig
-  // und der Browser-Reload kommt eh nur nach Bundle-Rebuild.
+  // 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.
   //
-  // Default-Resolution: wenn kein `stylesheet` übergeben und ein
-  // `clientEntry` existiert, resolve die styles.css aus
-  // `@cosmicdrift/kumiko-renderer-web` via Package-Exports. Bun.resolveSync liefert
-  // einen absoluten Pfad — funktioniert sowohl im Monorepo (Workspace-
-  // Link) als auch in einer installierten Fremd-App (node_modules).
+  // Without an explicit `stylesheet`, the default resolves through the
+  // package exports of `@cosmicdrift/kumiko-renderer-web`, which works both
+  // for a workspace link and for an installed app (node_modules).
   let stylesheetPath: string | undefined;
   let killTailwind: (() => void) | undefined;
   const resolvedStylesheet = resolveStylesheet(options);
   if (resolvedStylesheet !== undefined) {
-    const handle = await startTailwindWatcher(resolvedStylesheet);
+    const handle = await startTailwindPipeline(resolvedStylesheet, {
+      watch: resolveStylesheetWatch(options),
+    });
     if (handle !== undefined) {
       stylesheetPath = handle.outPath;
       killTailwind = handle.kill;

package/src/index.ts

@@ -55,6 +55,7 @@ export {
   createKumikoServer,
   type KumikoServerHandle,
   resolveStylesheet,
+  STYLESHEET_WATCH_ENV,
 } from "./create-kumiko-server";
 export { type FrameworkCoreEnv, frameworkCoreEnvSchema } from "./env-schema";
 export type {

package/src/run-dev-app.ts

@@ -196,6 +196,8 @@ export type RunDevAppOptions = {
   /** CSS-Entry. Default: package-export `@cosmicdrift/kumiko-renderer-web/styles.css`
    *  wenn ein client-Entry gesetzt ist. `false` deaktiviert die CSS-Pipeline. */
   readonly stylesheet?: string | false;
+  /** Tailwind `--watch` process on/off, see `CreateKumikoServerOptions.stylesheetWatch`. */
+  readonly stylesheetWatch?: boolean;
   /** Eigenes HTML-Template; sonst minimal-Default (#root + client.js).
    *  Im Multi-Entry-Mode ist es das Fallback-Template, wenn ein einzelner
    *  Entry kein eigenes htmlPath setzt. */
@@ -479,6 +481,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(options.hostDispatch !== undefined && { hostDispatch: options.hostDispatch }),
     ...(options.resolvePageHead !== undefined && { resolvePageHead: options.resolvePageHead }),
     ...(options.stylesheet !== undefined && { stylesheet: options.stylesheet }),
+    ...(options.stylesheetWatch !== undefined && { stylesheetWatch: options.stylesheetWatch }),
     ...(options.htmlPath !== undefined && { htmlPath: options.htmlPath }),
     ...(options.port !== undefined && { port: options.port }),
     ...(options.watchDirs !== undefined && { watchDirs: options.watchDirs }),