@cosmicdrift/kumiko-dev-server 0.1.0

package/bin/kumiko-build.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env bun
+// kumiko-build — Production-Build für Kumiko-Apps. Convention-driven:
+//
+//   src/client.tsx | src/styles.css | public/   →  Client-Bundle (dist/)
+//   bin/main.ts                                  →  Server-Bundle (dist-server/)
+//
+// Beide werden gebaut wenn die jeweiligen Conventions getroffen sind, sonst
+// übersprungen. Ein Workspace mit nur bin/main.ts kriegt nur den Server-
+// Bundle, ein Browser-only-Sample nur den Client.
+//
+//   {
+//     "scripts": { "build": "kumiko-build" }
+//   }
+//
+// Optionaler Pfad-Parameter überschreibt cwd:
+//   kumiko-build samples/apps/showcase
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  buildProdBundle,
+  buildServerBundle,
+  discoverClientEntries,
+  discoverServerEntry,
+  formatBuildResult,
+  formatServerBuildResult,
+} from "../src/build";
+import { runCodegen } from "../src/codegen";
+
+const explicit = process.argv[2];
+const cwd = explicit ? resolve(process.cwd(), explicit) : process.cwd();
+
+const red = "\x1b[31m";
+const yellow = "\x1b[33m";
+const reset = "\x1b[0m";
+
+const hasClient =
+  discoverClientEntries(cwd).length > 0 ||
+  existsSync(join(cwd, "src/styles.css")) ||
+  existsSync(join(cwd, "public")) ||
+  existsSync(join(cwd, "index.html"));
+const hasServer = discoverServerEntry(cwd) !== undefined;
+
+if (!hasClient && !hasServer) {
+  // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
+  console.error(
+    `\n  ${yellow}!${reset} Nichts zu bauen in ${cwd}.\n` +
+      `    Convention: src/client.tsx oder bin/main.ts erwartet.\n`,
+  );
+  process.exit(1);
+}
+
+try {
+  // Codegen-Pass vor dem Build — sicherstellt dass `.kumiko/define.ts`
+  // und `types.generated.d.ts` synchron mit den r.defineEvent-Aufrufen
+  // sind. Ohne diesen Pass würde ein veraltetes Wrapper-File ein
+  // Build-Error oder schlimmer: einen Build mit stale Augmentation
+  // erzeugen, der zur Laufzeit die falschen Events erlaubt.
+  const cgResult = runCodegen({ appRoot: cwd });
+  if (cgResult.warnings.length > 0) {
+    for (const w of cgResult.warnings) {
+      // biome-ignore lint/suspicious/noConsole: CLI-Output
+      console.warn(`${yellow}!${reset} [codegen] ${w.file}:${w.line} — ${w.reason}`);
+    }
+  }
+
+  if (hasClient) {
+    const t0 = performance.now();
+    const result = await buildProdBundle({ cwd });
+    const ms = Math.round(performance.now() - t0);
+    // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
+    console.log(formatBuildResult(result, ms));
+  }
+  if (hasServer) {
+    const t0 = performance.now();
+    const result = await buildServerBundle({ cwd });
+    const ms = Math.round(performance.now() - t0);
+    // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
+    console.log(formatServerBuildResult(result, ms));
+  }
+} catch (err) {
+  // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
+  console.error(`\n  ${red}✗${reset} ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}

package/bin/kumiko-dev.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+// kumiko-dev — Wrapper-Skript für sample dev-scripts. Spawnt den
+// übergebenen Server-Entry und respawnt automatisch.
+//
+// Restart-Policy:
+//   - exit 75 (EX_TEMPFAIL, vom dev-server beim Schema-Change ausgelöst,
+//     weil Bun's Module-Cache einen Process-Restart erzwingt): sofortiger
+//     respawn ohne Crash-Loop-Anrechnung — das ist erwartetes Verhalten.
+//   - jeder andere non-zero exit: respawn mit kurzem Backoff, aber
+//     Crash-Loop-Schutz via createCrashTracker. Verhindert Endlos-Loop
+//     bei syntaktisch totem bin/main.ts und gibt dem User trotzdem
+//     "Live-Edit"-Feeling: ein Code-Fehler in einem Feature killt nicht
+//     die ganze yarn-dev-Session.
+//   - Signal-killed (SIGINT/SIGTERM): wir folgen dem Caller, exit 0.
+//
+// Nutzung: `kumiko-dev src/app/server.ts` in package.json:
+//
+//   "scripts": { "dev": "kumiko-dev src/app/server.ts" }
+
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { createCrashTracker } from "../src/crash-tracker";
+
+const SCHEMA_RESTART_EXIT_CODE = 75;
+const MAX_CRASHES = 5;
+const CRASH_WINDOW_MS = 10_000;
+const CRASH_BACKOFF_MS = 500;
+
+const entry = process.argv[2];
+if (entry === undefined || entry === "") {
+  process.stderr.write("Usage: kumiko-dev <server-entry.ts>\n");
+  process.exit(2);
+}
+
+// Restliche Args (z.B. --port 4175) reichen wir an den Server durch.
+const passthroughArgs = process.argv.slice(3);
+
+// Bun's eigener Pfad steht in process.argv[0] — den nutzen wir, damit
+// `bun --env-file=...` Flags vom Caller nicht verloren gehen. Wir
+// reichen NICHT alle Bun-Flags durch (kompliziert mit shell-Escaping);
+// dev-scripts in samples setzen Env-Vars direkt im Aufruf wenn nötig.
+const bunPath = process.argv[0] ?? "bun";
+
+const crashTracker = createCrashTracker({
+  maxCrashes: MAX_CRASHES,
+  windowMs: CRASH_WINDOW_MS,
+});
+
+const spawnServer = (): void => {
+  const child = spawn(bunPath, ["run", entry, ...passthroughArgs], {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal !== null) {
+      // Signal-killed (z.B. SIGINT): Caller wollte raus → wir auch.
+      process.exit(0);
+      return;
+    }
+    if (code === SCHEMA_RESTART_EXIT_CODE) {
+      process.stdout.write("[kumiko-dev] respawn after schema change…\n");
+      spawnServer();
+      return;
+    }
+    if (code === 0) {
+      process.exit(0);
+      return;
+    }
+    // Non-zero exit ohne Schema-Change: Code-Fehler oder transienter
+    // Crash. Respawn mit Backoff + Crash-Loop-Schutz.
+    const now = Date.now();
+    const allowed = crashTracker.noteCrash(now);
+    if (!allowed) {
+      process.stderr.write(
+        `[kumiko-dev] ${MAX_CRASHES} Crashes in ${CRASH_WINDOW_MS / 1000}s — aufgeben (exit ${code}). ` +
+          "Fehler oben fixen und yarn dev erneut starten.\n",
+      );
+      process.exit(code);
+      return;
+    }
+    process.stderr.write(
+      `[kumiko-dev] server exited with code ${code} — respawn in ${CRASH_BACKOFF_MS}ms ` +
+        `(${crashTracker.crashCountInWindow(now)}/${MAX_CRASHES} in window)\n`,
+    );
+    setTimeout(spawnServer, CRASH_BACKOFF_MS);
+  });
+};
+
+spawnServer();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cosmicdrift/kumiko-dev-server",
+  "version": "0.1.0",
+  "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/dev-server"
+  },
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "type": "module",
+  "kumiko": {
+    "runtime": "dev"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./build": "./src/build.ts",
+    "./compose-features": "./src/compose-features.ts",
+    "./drizzle-config": "./src/drizzle-config.ts",
+    "./drizzle-tables-auth-mode": "./src/drizzle-tables-auth-mode.ts",
+    "./drizzle-tables-minimal": "./src/drizzle-tables-minimal.ts"
+  },
+  "bin": {
+    "kumiko-build": "./bin/kumiko-build.ts",
+    "kumiko-dev": "./bin/kumiko-dev.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/build-prod-bundle.integration.ts

@@ -0,0 +1,265 @@
+// Integration-Tests für buildProdBundle — End-to-End-Pfad gegen das
+// echte Filesystem.
+//
+// Zwei Szenarien:
+//
+//   1. Vanilla-Pipeline (kein client.tsx, nur public/ + html-template):
+//      läuft unter Node-Vitest direkt — kein Bun.build, keine
+//      Subprocess-Akrobatik. Beweist Discovery + html-rendering +
+//      public-copy + manifest-format.
+//
+//   2. Volle Pipeline (client.tsx + Bun.build + Hash + Manifest):
+//      braucht Bun. Spawnen kumiko-build als subprocess via PATH.
+//      Skipped wenn `bun` nicht erreichbar — selten, aber sauber.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { buildProdBundle } from "../build-prod-bundle";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const KUMIKO_BUILD_BIN = resolve(__dirname, "../../bin/kumiko-build.ts");
+
+function bunAvailable(): boolean {
+  try {
+    execFileSync("bun", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("buildProdBundle (vanilla pipeline)", () => {
+  let tmp = "";
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-build-it-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("kopiert public/ 1:1 nach dist/", async () => {
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(join(tmp, "public/favicon.txt"), "fav-content");
+    await writeFile(join(tmp, "public/robots.txt"), "User-agent: *\nDisallow:\n");
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><body>Hello</body></html>`,
+    );
+
+    const result = await buildProdBundle({ cwd: tmp });
+
+    expect(result.manifest).toEqual({});
+    expect(await readFile(join(tmp, "dist/favicon.txt"), "utf8")).toBe("fav-content");
+    expect(await readFile(join(tmp, "dist/robots.txt"), "utf8")).toContain("User-agent");
+  });
+
+  test("rendert public/index.html als Template (Inhalt erhalten)", async () => {
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><head><title>Custom Title</title></head><body>Custom Body</body></html>`,
+    );
+
+    await buildProdBundle({ cwd: tmp });
+
+    const html = await readFile(join(tmp, "dist/index.html"), "utf8");
+    expect(html).toContain("Custom Title");
+    expect(html).toContain("Custom Body");
+  });
+
+  test("schreibt manifest.json auch wenn leer", async () => {
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(join(tmp, "public/index.html"), `<html></html>`);
+
+    await buildProdBundle({ cwd: tmp });
+
+    const manifest = JSON.parse(await readFile(join(tmp, "dist/manifest.json"), "utf8"));
+    expect(manifest).toEqual({});
+  });
+
+  test("public/index.html landet NICHT als rohes File in dist/ (wird als Template behandelt)", async () => {
+    await mkdir(join(tmp, "public"), { recursive: true });
+    const original = `<!doctype html><html><body>SOURCE</body></html>`;
+    await writeFile(join(tmp, "public/index.html"), original);
+    await writeFile(join(tmp, "public/other.txt"), "ABC");
+
+    await buildProdBundle({ cwd: tmp });
+
+    // dist/index.html existiert (gerendert), public/other.txt wurde kopiert
+    expect(existsSync(join(tmp, "dist/index.html"))).toBe(true);
+    expect(existsSync(join(tmp, "dist/other.txt"))).toBe(true);
+    // Inhalt: was im Template stand, kommt im Output an (kein Doppel-Pfad
+    // wo public/index.html und dist/index.html sich gegenseitig überschreiben).
+    expect(await readFile(join(tmp, "dist/index.html"), "utf8")).toContain("SOURCE");
+  });
+
+  test("clean wipe: vorhandenes dist/-Junk wird entfernt", async () => {
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(join(tmp, "public/index.html"), `<html></html>`);
+    // Junk-File aus altem Build
+    await mkdir(join(tmp, "dist/old"), { recursive: true });
+    await writeFile(join(tmp, "dist/old/stale.js"), "old content");
+
+    await buildProdBundle({ cwd: tmp });
+
+    expect(existsSync(join(tmp, "dist/old/stale.js"))).toBe(false);
+  });
+
+  test("wirft mit klarer Message wenn weder public/ noch index.html noch client da", async () => {
+    // tmp ist leer
+    await expect(buildProdBundle({ cwd: tmp })).rejects.toThrow(/nothing to build/);
+  });
+
+  test("wirft mit Anweisung wenn HTML-Template ohne /client.js Placeholder vorliegt", async () => {
+    // Simuliert: User hat bereits manifest-entry (faken über option, in
+    // realer Pipeline kommt's aus Bun.build). Wir testen renderHtml /
+    // injectAssetTags-Verhalten via lower-level Pfad: HTML ohne Tag,
+    // public-folder simuliert dass Build was zu tun hat. Erwartete
+    // Error-Message zitiert das exakte Snippet.
+    //
+    // Dieser Pfad wird im realen Build durch buildClientBundle ausgelöst
+    // und im Vanilla-Test können wir ihn nicht direkt triggern (kein
+    // Bun.build). Der CLI-Subprocess-Test deckt das ab.
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><body>no script tag here</body></html>`,
+    );
+    // Ohne client.tsx läuft Bun.build nicht, manifest bleibt {} →
+    // injectAssetTags wirft NICHT. Das ist gewollt: wenn nichts zu
+    // injizieren da ist, ist's auch kein Fehler.
+    const result = await buildProdBundle({ cwd: tmp });
+    expect(result.manifest).toEqual({});
+  });
+});
+
+// Voller Pipeline-Test gegen das echte CLI-bin via subprocess. Bringt
+// echtes Bun.build + Tailwind ins Spiel — der Pfad den die anderen
+// Tests bewusst nicht laufen können (Vitest unter Node).
+describe.skipIf(!bunAvailable())("kumiko-build CLI (full pipeline with bun)", () => {
+  let tmp = "";
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-build-cli-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("client.ts → hashed bundle, manifest, html mit injected script-tag", async () => {
+    // Minimal client ohne externe Deps — Bun.build resolvt nichts.
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(
+      join(tmp, "src/client.ts"),
+      `const root = document.getElementById("root"); if (root) root.textContent = "hi";`,
+    );
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><head></head><body><div id="root"></div><script type="module" src="/client.js"></script></body></html>`,
+    );
+    // package.json mit stylesheet:false äquivalent — wir setzen kein
+    // src/styles.css und sind außerhalb des monorepos, sodass der
+    // renderer-web-Fallback fehlschlägt und gracefully undefined liefert.
+    await writeFile(join(tmp, "package.json"), `{"name":"build-it-fixture","private":true}`);
+
+    execFileSync("bun", [KUMIKO_BUILD_BIN, tmp], { stdio: "pipe" });
+
+    const manifest = JSON.parse(await readFile(join(tmp, "dist/manifest.json"), "utf8")) as Record<
+      string,
+      string
+    >;
+    expect(manifest["client.js"]).toMatch(/^\/assets\/client-[a-z0-9]+\.js$/);
+
+    const html = await readFile(join(tmp, "dist/index.html"), "utf8");
+    expect(html).toContain(`src="${manifest["client.js"]}"`);
+    expect(html).toContain('id="root"');
+
+    // Hashed asset existiert im dist/
+    const assetPath = join(tmp, "dist", manifest["client.js"] ?? "");
+    expect(existsSync(assetPath)).toBe(true);
+
+    // Bundle enthält den User-Code (minified — also Identifier-Namen
+    // mangled, aber der String-Literal "hi" überlebt).
+    expect(await readFile(assetPath, "utf8")).toContain('"hi"');
+  });
+
+  test("client.ts ohne index.html → klarer Error mit Template-Vorschlag", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client.ts"), `console.log("hi");`);
+    await writeFile(join(tmp, "package.json"), `{"name":"no-html","private":true}`);
+
+    let stderr = "";
+    expect(() => {
+      try {
+        execFileSync("bun", [KUMIKO_BUILD_BIN, tmp], { stdio: "pipe" });
+      } catch (err) {
+        const e = err as { stderr?: Buffer };
+        stderr = e.stderr?.toString() ?? "";
+        throw err;
+      }
+    }).toThrow();
+
+    expect(stderr).toContain("kein index.html gefunden");
+    expect(stderr).toContain(`<script type="module" src="/client.js"></script>`);
+  });
+
+  test("client.ts + index.html ohne /client.js Placeholder → klarer Error", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client.ts"), `console.log("hi");`);
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><body>no script</body></html>`,
+    );
+    await writeFile(join(tmp, "package.json"), `{"name":"no-placeholder","private":true}`);
+
+    let stderr = "";
+    expect(() => {
+      try {
+        execFileSync("bun", [KUMIKO_BUILD_BIN, tmp], { stdio: "pipe" });
+      } catch (err) {
+        const e = err as { stderr?: Buffer };
+        stderr = e.stderr?.toString() ?? "";
+        throw err;
+      }
+    }).toThrow();
+
+    expect(stderr).toContain("keinen Entry-Tag für /client.js");
+    expect(stderr).toContain(`<script type="module" src="/client.js"></script>`);
+  });
+
+  test("Re-Build mit unverändertem Source produziert identischen Hash (reproducibility)", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client.ts"), `console.log("stable");`);
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><body><script type="module" src="/client.js"></script></body></html>`,
+    );
+    await writeFile(join(tmp, "package.json"), `{"name":"hash-stability","private":true}`);
+
+    execFileSync("bun", [KUMIKO_BUILD_BIN, tmp], { stdio: "pipe" });
+    const manifest1 = JSON.parse(await readFile(join(tmp, "dist/manifest.json"), "utf8")) as Record<
+      string,
+      string
+    >;
+
+    execFileSync("bun", [KUMIKO_BUILD_BIN, tmp], { stdio: "pipe" });
+    const manifest2 = JSON.parse(await readFile(join(tmp, "dist/manifest.json"), "utf8")) as Record<
+      string,
+      string
+    >;
+
+    expect(manifest2["client.js"]).toBe(manifest1["client.js"]);
+  });
+});