@cosmicdrift/kumiko-server-runtime 0.386.0 → 0.387.0

package/dist/build-prod-bundle.js

@@ -1,9 +1,8 @@
-// buildProdBundle — Production-Build für Kumiko-Apps. Ein generischer
-// Build-Step ohne App-spezifisches Wissen: Convention-Discovery liest
-// die App-Struktur, Bun.build + Tailwind + Public-Folder-Copy
-// produzieren ein deploybares dist/.
+// buildProdBundle — Production build for Kumiko apps. A generic build step
+// with no app-specific knowledge: convention discovery reads the app structure;
+// Bun.build + Tailwind + public-folder copying produce a deployable dist/.
 //
-// Client entries (fw#2320 — explicit, no filename inference):
+// Client entries (explicit, no filename inference):
 //
 //   package.json "kumiko.clientEntries": [{ name, sourceFile, htmlPath? }]
 //                                     →  one Bun.build bundle per declared entry
@@ -14,23 +13,22 @@
 // Convention for everything else (all optional, missing → skipped):
 //
 //   src/styles.css                   →  Tailwind one-shot
-//                                       (oder fallback auf @cosmicdrift/kumiko-renderer/web/styles.css
-//                                        wenn nur clientEntry da ist und kein eigenes CSS)
-//   public/                          →  rsync 1:1 (kein Hash — User-bewusste URLs)
-//   public/index.html | index.html   →  Template, Placeholder-Tags ersetzt:
+//                                       (or fallback to @cosmicdrift/kumiko-renderer/web/styles.css
+//                                        when only clientEntry exists and no custom CSS)
+//   public/                          →  rsync 1:1 (no hash — URLs are user-facing)
+//   public/index.html | index.html   →  template with placeholder tags replaced:
 //                                         <script type="module" src="/client.js"> → /assets/client-<hash>.js
 //                                         <link href="/styles.css"> → /assets/styles-<hash>.css
-//   (kein HTML, vanilla)             →  Default-HTML ohne Asset-Tags
+//   (no HTML, vanilla)               →  default HTML without asset tags
 //
-// Fehler-Modus: hat client.tsx oder Tailwind etwas produziert, aber das HTML
-// hat keinen passenden Placeholder, wirft der Build mit dem exakten Snippet
-// zum Reinkopieren. Keine silent-injection — das HTML soll lesen wie's
-// auch im Dev-Server liefert.
+// Failure mode: if client.tsx or Tailwind produced output but the HTML has no
+// matching placeholder, the build throws with the exact snippet to copy in.
+// No silent injection — the HTML should behave as it does in the dev server.
 //
 // Output:
 //
 //   dist/
-//     index.html              ← Tags mit gehashten URLs
+//     index.html              ← tags with hashed URLs
 //     assets/
 //       client-<hash>.js      ← entry
 //       <chunk>-<hash>.js     ← split chunks
@@ -41,12 +39,12 @@
 //     csp-hashes.json         ← sha256 of every inline <script> in the HTML above
 //     <public/* 1:1>          ← favicon.ico, robots.txt, og-image.png, …
 //
-// Cache-Header (von runProdApp gesetzt, nicht hier):
+// Cache headers (set by runProdApp, not here):
 //
 //   /assets/*               →  public, max-age=31536000, immutable
 //   /index.html, /sw.js     →  no-cache, must-revalidate
 //   /manifest.json          →  no-cache
-//   alles andere (public/)  →  default (auto-cache)
+//   everything else (public/) → default (auto-cache)
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -66,18 +64,18 @@ import { BUNDLED_ASSETS_DIST_DIR, readBundledAssetDeclarations, resolveBundledAs
 import { CSP_HASHES_FILE, inlineScriptHashes } from "./csp-hashes.js";
 import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_DIST_DIR, resolveRendererWebFontsDir, } from "./renderer-web-fonts.js";
 import { canResolveTailwindStylesheet, resolveTailwindCli } from "./resolve-tailwind-cli.js";
-// Bun-Runtime-Check als module-level Konstante: alle Build-Schritte
-// (Tailwind via Bun.spawn, Client-Bundle via Bun.build, Stylesheet-
-// Resolution via Bun.resolveSync) sind Bun-only. Pro-Funktions-Inline-
-// Checks driften sonst — eine Konstante hier hält das konsistent.
+// Bun runtime check as a module-level constant: every build step (Tailwind via
+// Bun.spawn, client bundling via Bun.build, and stylesheet resolution via
+// Bun.resolveSync) is Bun-only. Per-function inline checks could diverge; one
+// constant keeps the checks consistent.
 const hasBun = typeof Bun !== "undefined";
-// Default-HTML wird nur genutzt wenn der App-Author KEIN index.html liefert.
-// Hat keine Asset-Placeholder, weil der Default-Pfad für vanilla apps
-// (nur public/) gedacht ist — wer JS/CSS will, schreibt ein eigenes
-// index.html mit den richtigen Placeholder-Tags.
-// interactive-widget=resizes-content (fw#1918): keeps `position: fixed`
-// bottom bars anchored above a mobile keyboard instead of behind it. iOS Safari
-// ignores the key; renderer-web's useKeyboardInset covers it via window.visualViewport.
+// The default HTML is used only when the app author provides no index.html.
+// It has no asset placeholders because this path is intended for vanilla apps
+// (public/ only); apps that need JS/CSS must provide an index.html with the
+// appropriate placeholder tags.
+// interactive-widget=resizes-content: keeps `position: fixed` bottom bars
+// anchored above a mobile keyboard instead of behind it. iOS Safari ignores
+// the key; renderer-web's useKeyboardInset covers it via window.visualViewport.
 export const DEFAULT_HTML = `<!doctype html>
 <html lang="en">
   <head>
@@ -91,8 +89,8 @@ export const DEFAULT_HTML = `<!doctype html>
 </html>
 `;
 /** Folder name relative to dist/ for hashed assets (JS, CSS, file-loader
- *  outputs). Exported damit runProdApp dieselbe Konvention für Cache-
- *  Header nutzt — Drift verhindern. */
+ *  outputs). Exported so runProdApp uses the same convention for cache headers
+ *  and cannot drift. */
 export const ASSETS_DIR = "assets";
 const ASSET_LOADERS = {
     ".png": "file",
@@ -111,7 +109,7 @@ export async function buildProdBundle(options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     const outDir = resolve(cwd, options.outDir ?? "dist");
     const assetsDir = join(outDir, ASSETS_DIR);
-    // 1. Discovery: was ist da?
+    // 1. Discovery
     const clientEntries = resolveClientEntries(cwd, options);
     const firstClientSource = clientEntries[0]?.sourceFile;
     const stylesheet = resolveStylesheetEntry(cwd, firstClientSource, options.stylesheet);
@@ -128,9 +126,9 @@ export async function buildProdBundle(options = {}) {
     await mkdir(outDir, { recursive: true });
     await mkdir(assetsDir, { recursive: true });
     const manifest = {};
-    // 3. Tailwind one-shot (vor JS, weil JS' loader auf .css trifft falls
-    //    der client.tsx ein "import './foo.css'" macht — den Fall lassen
-    //    wir hier raus, Tailwind ist die einzige CSS-Quelle).
+    // 3. Tailwind one-shot (before JS, because the JS loader would encounter .css
+    //    if client.tsx imports "./foo.css" — that case is not supported here;
+    //    Tailwind is the only CSS source).
     if (stylesheet) {
         const css = await runTailwindOnce(stylesheet.path, cwd);
         assertRendererWebShellPresent(css, stylesheet);
@@ -140,19 +138,19 @@ export async function buildProdBundle(options = {}) {
         manifest["styles.css"] = `/${ASSETS_DIR}/${filename}`;
         await copyRendererWebFonts(cwd, outDir);
     }
-    // 4. Bun.build pro Entry (multi-entry produces N bundles + shared chunks).
-    //    Ein einzelner Bun.build-Call mit allen entrypoints würde shared
-    //    chunks deduplizieren, hashes deterministisch halten — passt zu
-    //    dem split-tree-Pattern von publicstatus (admin + public teilen
-    //    sich den renderer-web-core).
+    // 4. Bun.build per entry (multi-entry produces N bundles + shared chunks).
+    //    A single Bun.build call with all entrypoints deduplicates shared chunks
+    //    and keeps hashes deterministic, matching publicstatus's split-tree
+    //    pattern (admin + public share renderer-web-core).
     if (clientEntries.length > 0) {
         const built = await buildClientBundles(clientEntries, assetsDir);
         for (const [manifestKey, filename] of Object.entries(built)) {
             manifest[manifestKey] = `/${ASSETS_DIR}/${filename}`;
         }
     }
-    // 5. Public-Folder rsync (ohne index.html / *.html-templates — werden
-    //    separat gerendert). Filter-list = template-basenames der entries.
+    // 5. Public-folder rsync (excluding index.html / *.html templates, which are
+    //    rendered separately). The filter list contains the entries' template
+    //    basenames.
     const templateBasenames = new Set(clientEntries.map((e) => basenameOf(e.htmlPath)));
     if (hasPublicDir) {
         await copyPublicFolder(publicDir, outDir, templateBasenames);
@@ -160,21 +158,21 @@ export async function buildProdBundle(options = {}) {
     // 5a. Declared read-only assets (package.json "kumiko.assets"), copied after
     //     public/ so a same-named public file cannot shadow them.
     await copyBundledAssets(cwd, outDir, bundledAssets);
-    // 5b. Build-Identität: Hash über die content-gehashten Asset-URLs +
-    //     lesbarer Zeitstempel. Wird in index.html gebacken und als
-    //     build-info.json geschrieben (Update-Awareness, default an).
-    //     ponytail: id hängt nur an Assets — ein reiner Server-Deploy ohne
-    //     Client-Bundle-Change behält die id → kein Banner (die UI ist dann
-    //     nicht stale). Bei Bedarf an Server-Versionierung koppeln.
+    // 5b. Build identity: hash of the content-hashed asset URLs plus a readable
+    //     timestamp. Baked into index.html and written to build-info.json
+    //     (update awareness, enabled by default).
+    //     ponytail: id depends only on assets — a server-only deploy with no
+    //     client-bundle change keeps the id, so no banner appears (the UI is not
+    //     stale). Couple it to the server version when needed.
     const buildInfo = Object.keys(manifest).length > 0
         ? { id: computeBuildId(manifest), builtAt: Temporal.Now.instant().toString() }
         : undefined;
-    // 6. HTML pro Entry rendern. Convention: ein HTML-File pro Client-Entry,
-    //    jede mit ihrem eigenen Script-Tag. Server (runProdApp.hostDispatch)
-    //    serviert je nach Host das passende File.
+    // 6. Render HTML for each entry. Convention: one HTML file per client entry,
+    //    each with its own script tag. The server (runProdApp.hostDispatch)
+    //    serves the matching file for each host.
     if (clientEntries.length === 0) {
-        // Vanilla-public-only-app: keine HTML-Files zu rendern, public-Folder
-        // wurde schon kopiert.
+        // Vanilla public-only app: no HTML files need rendering; the public folder
+        // was already copied.
     }
     else {
         for (const entry of clientEntries) {
@@ -204,7 +202,7 @@ const SOURCE_EXTENSION_PATTERN = /\.(?:tsx?|jsx?)$/;
  *  `kumiko-build`/`kumiko build` via `@cosmicdrift/kumiko-dev-server/build`,
  *  not just from unit tests.
  *
- * Precedence (fw#2320 — explicit declaration, no filename inference):
+ * Precedence (explicit declaration, no filename inference):
  *   1. `declared.clientEntry` and `declared.clientEntries` both set → throw.
  *   2. `declared.clientEntries` (non-empty) → one entry per declaration.
  *   3. `declared.clientEntry` → single entry, name "client".
@@ -320,7 +318,7 @@ function resolveConventionEntries(cwd) {
     }
     return [];
 }
-// Pre-fw#2320 multi-entry convention: any src/client-<suffix>.tsx(x) became
+// Legacy multi-entry convention: any src/client-<suffix>.tsx(x) became
 // its own bundle. Detecting these without a declaration means an unmigrated
 // app would silently ship without their bundles — throw instead.
 function findLegacyClientFiles(cwd) {
@@ -436,9 +434,10 @@ function discoverHtmlTemplateFor(cwd, basename) {
     }
     return undefined;
 }
-// Äußerster Wrapper von DefaultAppShell/WorkspaceShell trägt diese Utility
-// (app-layout.tsx: "flex min-h-screen …"). Echtes Tailwind-Utility (landet
-// also im kompilierten Output) ohne CSS-Escaping → stabiler Substring-Sentinel.
+// The outer wrapper of DefaultAppShell/WorkspaceShell carries this utility
+// (app-layout.tsx: "flex min-h-screen …"). It is a real Tailwind utility in
+// the compiled output, so it provides a stable substring sentinel without CSS
+// escaping.
 const RENDERER_WEB_SHELL_SENTINEL = "min-h-screen";
 function resolveStylesheetEntry(cwd, clientEntry, override) {
     if (override === false)
@@ -446,13 +445,13 @@ function resolveStylesheetEntry(cwd, clientEntry, override) {
     if (typeof override === "string") {
         return { path: resolve(cwd, override), isRendererWebFallback: false };
     }
-    // App-eigenes styles.css schlägt den Default.
+    // An app's own styles.css takes precedence over the default.
     const local = resolve(cwd, "src/styles.css");
     if (existsSync(local))
         return { path: local, isRendererWebFallback: false };
-    // Sonst: nur wenn ein client da ist, fallback auf renderer-web/styles.css.
-    // Sample-Apps und Showcases nutzen das alle — gleiche Logik wie der dev-
-    // server, damit lokal/prod identisch bauen.
+    // Otherwise, fall back to renderer-web/styles.css only when a client exists.
+    // Sample apps and showcases all use this, matching the dev server so local
+    // and production builds behave identically.
     if (!clientEntry)
         return undefined;
     if (!hasBun)
@@ -468,12 +467,12 @@ function resolveStylesheetEntry(cwd, clientEntry, override) {
         return undefined;
     }
 }
-// Build-Zeit-Guard gegen unstyled prod (#359): fällt der Build auf renderer-
-// web/styles.css zurück und fehlt im kompilierten CSS die Shell-Sentinel-
-// Klasse, wurden die DefaultAppShell-Styles nicht gescannt (renderer-web
-// nicht dort installiert wo Tailwind scannt, oder ein @source-Regress).
-// Laut failen statt ein 15KB-Image zu liefern, das in prod nackt rendert.
-// @internal — exportiert nur für Unit-Tests.
+// Build-time guard against unstyled production output: when the build falls
+// back to renderer-web/styles.css but the compiled CSS lacks the shell sentinel,
+// DefaultAppShell styles were not scanned (renderer-web is not installed where
+// Tailwind scans, or an @source regression occurred).
+// Fail rather than shipping a 15KB image that renders unstyled in production.
+// @internal — exported only for unit tests.
 export function assertRendererWebShellPresent(css, stylesheet) {
     // skip: not the renderer-web fallback stylesheet, invariant doesn't apply
     if (!stylesheet.isRendererWebFallback)
@@ -517,7 +516,7 @@ async function copyBundledAssets(cwd, outDir, declarations) {
         await cp(source, join(target, declaration.name));
     }
 }
-// @internal — exported nur für Unit-Tests.
+// @internal — exported only for unit tests.
 export function discoverHtmlTemplate(cwd) {
     for (const candidate of ["index.html", "public/index.html"]) {
         const path = resolve(cwd, candidate);
@@ -529,7 +528,7 @@ export function discoverHtmlTemplate(cwd) {
 // ---------------------------------------------------------------------------
 // Build steps
 // ---------------------------------------------------------------------------
-// @internal — exportiert nur für Unit-Tests (Relocation-Test des @source-Layouts).
+// @internal — exported only for unit tests (relocation test for the @source layout).
 export async function runTailwindOnce(entry, cwd) {
     if (!hasBun) {
         throw new Error("[kumiko build] Tailwind one-shot requires Bun (Bun.spawn) — run via `bun run …` or `bun kumiko build`.");
@@ -602,9 +601,9 @@ export function isEntryOutputFor(outName, baseName) {
         return false;
     return /^[A-Za-z0-9]+$/.test(outName.slice(prefix.length, -".js".length));
 }
-/** Multi-entry-build: ein Bun.build-Call mit allen entrypoints — shared
- *  chunks werden dedupliziert, hashes deterministisch. Returns map
- *  manifestKey → hashed-filename (basename, ohne /assets/-Prefix). */
+/** Multi-entry build: one Bun.build call with all entrypoints, so shared
+ *  chunks are deduplicated and hashes remain deterministic. Returns a map of
+ *  manifestKey → hashed filename (basename, without the /assets/ prefix). */
 async function buildClientBundles(entries, outDir) {
     if (!hasBun) {
         throw new Error("[kumiko build] requires Bun — run via `bun run …` or `bun kumiko build`.");
@@ -615,9 +614,9 @@ async function buildClientBundles(entries, outDir) {
         target: "browser",
         splitting: true,
         minify: true,
-        // Keine Source-Maps in Prod: 1.6 MB+ Müll im Container, plus
-        // exposed Source-Code reverse-engineerable. Dev hat seine eigenen
-        // sourcemaps via create-kumiko-server.ts.
+        // No source maps in production: 1.6 MB+ of container waste, plus exposed
+        // reverse-engineerable source code. Development has its own sourcemaps via
+        // create-kumiko-server.ts.
         sourcemap: "none",
         naming: {
             entry: "[name]-[hash].[ext]",
@@ -637,9 +636,9 @@ async function buildClientBundles(entries, outDir) {
     if (entryOutputs.length !== entries.length) {
         throw new Error(`[kumiko build] expected ${entries.length} entry-point outputs, got ${entryOutputs.length}`);
     }
-    // Bun.build benennt entry-files nach Source-Basename (ohne extension):
-    // `src/client-admin.tsx` → `client-admin-<hash>.js`. Wir mappen jedes
-    // entry-output zurück auf seinen ClientEntry via Basename-match.
+    // Bun.build names entry files after the source basename (without the extension):
+    // `src/client-admin.tsx` → `client-admin-<hash>.js`. Map each entry output
+    // back to its ClientEntry by matching the basename.
     const result = {};
     for (const entry of entries) {
         const baseName = (entry.sourceFile.split("/").pop() ?? "").replace(SOURCE_EXTENSION_PATTERN, "");
@@ -655,9 +654,9 @@ function basenameOf(p) {
     return p.split("/").pop() ?? p;
 }
 async function copyPublicFolder(src, dst, templateBasenames) {
-    // HTML-templates werden separat gerendert — nicht blind kopieren, sonst
-    // überschreibt das die injizierte Version. (z.B. index.html, admin.html
-    // bei multi-entry).
+    // HTML templates are rendered separately rather than copied blindly, because
+    // copying them would overwrite the injected version (for example index.html
+    // or admin.html in a multi-entry build).
     await cp(src, dst, {
         recursive: true,
         filter: (source) => {
@@ -674,10 +673,10 @@ async function copyPublicFolder(src, dst, templateBasenames) {
 // HTML render
 // ---------------------------------------------------------------------------
 async function renderHtml(templatePath, manifest, entry, buildInfo) {
-    // Edge-Case: kein eigenes HTML-Template + Bun.build oder Tailwind hat
-    // Output produziert. DEFAULT_HTML hat keine Placeholder (vanilla
-    // template), also würde injectAssetTags eh fehlschlagen. Klarer Fehler
-    // mit Vorschlag-Snippet zum Reinkopieren.
+    // Edge case: no custom HTML template exists, but Bun.build or Tailwind produced
+    // output. DEFAULT_HTML has no placeholders (it is a vanilla template), so
+    // injectAssetTags would fail anyway. Report a clear error with a snippet to
+    // copy in.
     if (!templatePath && Object.keys(manifest).length > 0) {
         throw new Error(buildMissingTemplateError(manifest, entry));
     }
@@ -691,7 +690,7 @@ function buildMissingTemplateError(manifest, entry) {
         ? `    <link rel="stylesheet" href="/styles.css" />\n`
         : "";
     const jsLine = manifest[entry.manifestKey]
-        ? // html-ok: Error-Hilfetext (Tag-Snippet als Text), wird nie gerendert.
+        ? // html-ok: Error-help text (tag snippet as text), never rendered.
             `    <script type="module" src="/${entry.manifestKey}"></script>\n`
         : "";
     const sourceBasename = basenameOf(entry.sourceFile);
@@ -723,18 +722,17 @@ function buildMissingTemplateError(manifest, entry) {
         `Der Build ersetzt /styles.css und /${entry.manifestKey} durch die gehashten URLs.`);
 }
 const BUILD_META_NAME = "kumiko-build";
-// @internal — exported nur für Unit-Tests.
+// @internal — exported only for unit tests.
 //
-// Convention: das HTML-Template MUSS Placeholder-Tags für jedes Asset
-// dieses Entries enthalten:
-//   - `<script type="module" src="/client.js">` für single-mode entry "client"
-//   - `<script type="module" src="/client-<name>.js">` für multi-mode entry "<name>"
-//   - `<link href="/styles.css">` für styles (gemeinsam über alle entries)
-// Der Build ersetzt sie durch die gehashten URLs.
+// The HTML template MUST contain placeholder tags for every asset of this entry:
+//   - `<script type="module" src="/client.js">` for single-mode entry "client"
+//   - `<script type="module" src="/client-<name>.js">` for multi-mode entry "<name>"
+//   - `<link href="/styles.css">` for styles shared by all entries
+// The build replaces them with hashed URLs.
 //
-// Fehlt ein erwarteter Tag, wirft der Build einen Fehler mit dem exakten
-// Snippet zum Reinkopieren — kein silent injection mehr, weil das den
-// Diff zwischen Dev- und Prod-HTML unsichtbar macht.
+// If an expected tag is missing, the build throws an error with the exact
+// snippet to copy in — no silent injection, which would hide differences
+// between development and production HTML.
 export function injectAssetTags(html, manifest, entry, buildInfo) {
     let result = html;
     // Meta tag instead of an inline script: strict CSPs (script-src 'self') block inline scripts.
@@ -755,12 +753,12 @@ export function injectAssetTags(html, manifest, entry, buildInfo) {
                 hashedAssetHint: "/assets/styles-<hash>.css",
             }));
         }
-        // html-ok: cssUrl ist ein selbst-generierter Manifest-Asset-Pfad (Hash-Name).
+        // html-ok: cssUrl is a self-generated manifest asset path (hashed name).
         result = result.replace(placeholder[0], `<link rel="stylesheet" href="${cssUrl}" />`);
     }
     const jsUrl = manifest[entry.manifestKey];
     if (jsUrl && !result.includes(jsUrl)) {
-        // Placeholder-pattern: src="/client.js" oder src="/client-<name>.js"
+        // Placeholder pattern: src="/client.js" or src="/client-<name>.js"
         const placeholderRx = new RegExp(`<script\\b[^>]*src="\\/${entry.manifestKey.replace(/\./g, "\\.")}"[^>]*><\\/script>`);
         const placeholder = placeholderRx.exec(result);
         if (!placeholder) {
@@ -773,13 +771,13 @@ export function injectAssetTags(html, manifest, entry, buildInfo) {
                 hashedAssetHint: `/assets/${baseAssetName}-<hash>.js`,
             }));
         }
-        // html-ok: jsUrl ist ein selbst-generierter Manifest-Asset-Pfad (Hash-Name).
+        // html-ok: jsUrl is a self-generated manifest asset path (hashed name).
         result = result.replace(placeholder[0], `<script type="module" src="${jsUrl}"></script>`);
     }
     return result;
 }
-/** Einheitliche Error-Form für fehlende Asset-Tags im HTML-Template
- *  (script-tag fürs JS-Bundle ODER stylesheet-link für Tailwind). */
+/** Consistent error format for missing asset tags in the HTML template
+ *  (the script tag for the JS bundle or the stylesheet link for Tailwind). */
 function buildMissingTagError(args) {
     const tpl = basenameOf(args.htmlPath);
     return (`[kumiko build] ${tpl} hat keinen Entry-Tag für /${args.assetKey} — füg ${args.insertHint} ein:\n` +
@@ -794,10 +792,10 @@ function buildMissingTagError(args) {
 function shortHash(content) {
     return createHash("sha256").update(content).digest("hex").slice(0, 8);
 }
-// Build-Identität aus den content-gehashten Asset-URLs. Sortiert →
-// deterministisch (Manifest-Key-Reihenfolge egal). Identischer Source →
-// gleiche id, geändertes Asset → andere id.
-// @internal — exported nur für Unit-Tests.
+// Build identity from the content-hashed asset URLs. Sorted for determinism
+// (manifest-key order does not matter). Identical source produces the same id;
+// a changed asset produces a different id.
+// @internal — exported only for unit tests.
 export function computeBuildId(manifest) {
     return createHash("sha256")
         .update(Object.values(manifest).sort().join("\n"))
@@ -807,9 +805,9 @@ export function computeBuildId(manifest) {
 // ---------------------------------------------------------------------------
 // CLI output
 // ---------------------------------------------------------------------------
-/** Formatiert ein BuildResult als CLI-freundliche Mehrzeilen-Zusammenfassung
- *  mit ANSI-Farben. Wird sowohl von `kumiko build` als auch von dem
- *  hoisted `kumiko-build`-Bin verwendet, damit das Output konsistent ist. */
+/** Formats a BuildResult as a CLI-friendly, multi-line summary with ANSI
+ *  colors. Used by both `kumiko build` and the hoisted `kumiko-build` binary
+ *  so their output remains consistent. */
 export function formatBuildResult(result, durationMs) {
     const dim = "\x1b[2m";
     const green = "\x1b[32m";

package/dist/extra-routes-deps.d.ts

@@ -7,7 +7,7 @@ import type { Redis } from "ioredis";
 export type { SystemDispatchArgs } from "@cosmicdrift/kumiko-framework/api";
 export { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-framework/api";
 /** Deps for the `wire` hook (runProdApp/createKumikoServer, after
- *  buildServer has mounted `extraRoutes` — see kumiko-framework#3050) and
+ *  buildServer has mounted `extraRoutes`) and
  *  for `runWorkerApp.wireComponents`. Naming: `deps` not `ctx` because
  *  `ctx` is the framework's HandlerContext (user/tenant/registry) — this
  *  scope is deliberately smaller and has NO `app` (routes are declared via

package/dist/index.js

@@ -1,7 +1,7 @@
-// Public API für den Kumiko-Production-Server-Boot. Symmetrisch zu
-// runDevApp (kumiko-dev-server), aber ohne Dev-/Scaffold-/Codegen-
-// Tooling (ts-morph) als Dependency — Prod-Apps ziehen so kein
-// Dev-Tooling mehr in ihre node_modules.
+// Public API for Kumiko's production-server boot. Symmetric with
+// runDevApp (kumiko-dev-server), but without Dev/Scaffold/Codegen
+// tooling (ts-morph) as a dependency, so production apps do not pull
+// development tooling into their node_modules.
 export { resolveBillingOption } from "./boot-options/billing-option.js";
 export { buildDemoModeRoute, withDemoReadOnlyFetch, } from "./boot-options/demo-mode.js";
 export { resolveFeatureTogglesOption, } from "./boot-options/feature-toggles-option.js";

package/dist/pii-boot-gate.js

@@ -13,7 +13,7 @@ export function assertPiiBootInvariants(features, opts) {
     const piiEntities = features.flatMap((feature) => Object.entries(feature.entities ?? {})
         .filter(([, entity]) => collectPiiSubjectFields(entity).length > 0)
         .map(([name]) => name));
-    // fw#2776: a declared event stance is worth as much as an entity annotation —
+    // A declared event stance is worth as much as an entity annotation —
     // encryptEventPayloadPii no-ops without a KMS, so a catalogued event writes
     // plaintext PII into kumiko_events with nothing to crypto-shred later.
     const piiEvents = features.flatMap((feature) => Object.values(feature.events ?? {})

package/dist/resolve-tailwind-cli.js

@@ -1,11 +1,9 @@
-// Resolved den lokal installierten @tailwindcss/cli-Bin auf seinen
-// absoluten Dateipfad. Wir vermeiden `bunx`, weil das auch bei lokal
-// installiertem Package noch das Registry-Manifest fragt und ohne Netz
-// mit `FailedToOpenSocket` stirbt.
+// Resolves the locally installed @tailwindcss/cli binary to its absolute path.
+// We avoid `bunx` because it still requests the registry manifest for a locally
+// installed package and fails with `FailedToOpenSocket` when offline.
 //
-// Ausgelagert aus create-kumiko-server.ts, damit unter vitest/Node
-// testbar (Bun-Branch + Resolve-Fail-Branch) ohne den Server zu
-// booten.
+// Kept separate from create-kumiko-server.ts so the Bun and resolution-failure
+// branches can be tested under Vitest/Node without booting the server.
 import { dirname, resolve } from "node:path";
 export function resolveTailwindCli(deps) {
     if (deps.bun === undefined)

package/dist/run-prod-app-boot-context.d.ts

@@ -39,8 +39,8 @@ type BootExtraContextOptions = {
     readonly appOverrides?: ConfigOverridesInput;
 };
 export declare function buildBootExtraContext(opts: BootExtraContextOptions): Record<string, unknown>;
-/** Die Auth-Felder die resolveAuthMail liest/normalisiert — beide
- *  App-Auth-Typen (prod + dev) erfüllen das strukturell. */
+/** The auth fields read and normalized by resolveAuthMail; both
+ *  app auth types (prod + dev) satisfy this structurally. */
 type AuthMailNormalizable = {
     readonly mail?: AuthMailOptions;
     readonly passwordReset?: PasswordResetSetup;

package/dist/run-prod-app-boot-context.js

@@ -17,14 +17,14 @@ import { resolveBootCrypto } from "./boot/boot-crypto.js";
 // Boot-time context helpers for runProdApp: ctx-extra-context wiring
 // (templateResolver/delivery/secrets/config-resolver), auth-mail convenience
 // normalization, and prod session-auth wiring. Split out of run-prod-app.ts
-// (#1005, Welle 2) — mechanical relocation, these are self-contained pure
+// — mechanical relocation, these are self-contained pure
 // functions, no closure over runProdApp's local boot state.
 // Shared with runDevApp (mergeConfigResolverDefault) for dev/prod parity.
 export function addConfigAccessorFactory(resolved, registry) {
     if (!resolved.configResolver)
         return resolved;
     // Both keys, always overriding an app-supplied value: the factory must derive from the
-    // effective resolver (fw#3313); the underscore alias stays until the next major.
+    // effective resolver; the underscore alias stays until the next major.
     const configAccessorFactory = createConfigAccessorFactory(registry, resolved.configResolver);
     return {
         ...resolved,
@@ -32,20 +32,19 @@ export function addConfigAccessorFactory(resolved, registry) {
         _configAccessorFactory: configAccessorFactory,
     };
 }
-// Framework-Default-Provider für den AppContext — gleicher Mechanismus wie
-// der tenantTierResolver-Autowire (findTierResolverUsage): deklarierter
-// Bedarf (Feature gemountet) → Default aus db/env, App überschreibt nur die
-// Ausnahme. templateResolver ist unbedingt (createTemplateResolverApi wirft nie, baut
-// nur einen db-gebundenen Accessor). secrets wird nur auto-verdrahtet wenn
-// das secrets-Feature gemountet ist UND ein KEK tatsächlich verfügbar ist
-// (masterKey-Override ODER env-KEK present) — sonst skip, damit der eager
-// KEK-Detection + Provider/Cipher-Aufbau leben in boot/boot-crypto.ts
-// (envHasMasterKek, resolveBootCrypto) — gemeinsam mit runDevApp.
-// Prod-Misconfig (secrets gemountet, kein KEK) fängt schon secretsEnvSchema
-// beim Boot; fehlt der env-Schema-Pfad, wirft requireSecretsContext beim
-// ersten ctx.secrets-Zugriff mit Wiring-Hinweis. configResolver nur im
-// Auth-Mode. Exportiert + pure für Unit-Tests; der merge mit App-Werten
-// passiert beim Caller (App gewinnt).
+// Framework-default providers for AppContext, using the same mechanism as
+// tenantTierResolver auto-wiring (findTierResolverUsage): a mounted feature declares
+// the need, the default comes from db/env, and the app can override the exception.
+// templateResolver is always wired (createTemplateResolverApi never throws; it only
+// creates a db-bound accessor). secrets is auto-wired only when the secrets feature is
+// mounted AND a KEK is available (masterKey override OR env KEK present); otherwise it
+// is skipped so eager KEK detection and provider/cipher construction remain in
+// boot/boot-crypto.ts (envHasMasterKek, resolveBootCrypto), shared with runDevApp.
+// A production misconfiguration (secrets mounted without a KEK) is caught by
+// secretsEnvSchema during boot; without the env-schema path, requireSecretsContext
+// throws with a wiring hint on the first ctx.secrets access. configResolver is only
+// wired in auth mode. Exported and pure for unit tests; the caller merges it with
+// app values (the app wins).
 // Prod/dev parity for ctx.notify: without this `_notifyFactory` is only wired
 // in tests (createDeliveryTestContext), so ctx.notify is undefined at runtime
 // and every notification silently skips. sseBroker optional (email/push don't
@@ -219,17 +218,17 @@ export function resolveAuthMail(auth, hmacSecret, envSource, mailWiring = {}) {
     const withResolvedSecrets = backfillTokenSecrets(auth, tokenSecret);
     if (!auth.mail)
         return withResolvedSecrets;
-    // SMTP-presence gate: ohne SMTP_HOST-env wird KEIN Flow verdrahtet (Routes
-    // blieben sonst 500). Der eigentliche Mail-Versand läuft über delivery
-    // (channel-email), nicht über diesen Transport — er ist nur der Detektor
-    // "ist Mail konfiguriert?".
+    // SMTP-presence gate: without SMTP_HOST in the environment, no flow is wired
+    // (the routes would otherwise return 500). Mail delivery itself runs through
+    // delivery (channel-email), not this transport; it only detects whether mail is
+    // configured.
     // An app transport from runProdApp's `mail` option replaces the probe.
     if (mailWiring.mailConfigured !== true &&
         !createSmtpTransportFromEnv(envSource, { fallbackFrom: auth.mail.from ?? "noreply@localhost" })) {
         return withResolvedSecrets;
     }
     const paths = makeAuthPaths(auth.mail.paths);
-    // appName/locale fließen in alle vier Flow-Options (alle mailen via delivery).
+    // appName/locale flow into all four flow options because they all send through delivery.
     const mailPresentation = {
         ...(auth.mail.appName !== undefined && { appName: auth.mail.appName }),
         ...(auth.mail.locale !== undefined && { locale: auth.mail.locale }),
@@ -266,7 +265,7 @@ export function resolveAuthMail(auth, hmacSecret, envSource, mailWiring = {}) {
     };
 }
 export async function buildProdSessionAuth(db, registry, sessionsFeature, mfaFeature, patFeature) {
-    // Resolve the sessions feature sessionStore provider (#1372).
+    // Resolve the sessions feature sessionStore provider.
     const store = await resolveSessionStore({ db, registry });
     if (sessionsFeature) {
         bindAutoRevokeFromFeature(sessionsFeature)?.(store.massRevoker);