@cosmicdrift/kumiko-dev-server 0.371.1 → 0.372.0

package/bin/kumiko-build.ts

@@ -1,20 +1,24 @@
 #!/usr/bin/env bun
-// kumiko-build — Production-Build für Kumiko-Apps. Convention-driven:
+// kumiko-build — production build for Kumiko apps. Convention-driven:
 //
 //   package.json "kumiko.clientEntries"/"kumiko.clientEntry",
-//     or src/client.tsx | src/styles.css | public/   →  Client-Bundle (dist/)
-//   bin/main.ts                                       →  Server-Bundle (dist-server/)
+//     or 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.
+// Both are built when their conventions match, otherwise skipped. A workspace
+// with only bin/main.ts gets just the server bundle, a browser-only sample
+// just the client.
 //
 //   {
 //     "scripts": { "build": "kumiko-build" }
 //   }
 //
-// Optionaler Pfad-Parameter überschreibt cwd:
+// An optional path argument overrides cwd:
 //   kumiko-build samples/apps/showcase
+//
+// Extra server entry points (repeatable, paths relative to the app dir), each
+// emitted as dist-server/<basename>.js:
+//   kumiko-build --entry bin/remote-probe.ts
 
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -24,6 +28,7 @@ import {
   discoverServerEntry,
   formatBuildResult,
   formatServerBuildResult,
+  parseKumikoBuildArgs,
   readClientEntriesConfig,
   readExtraRuntimeExternals,
   resolveClientEntries,
@@ -31,19 +36,19 @@ import {
 
 if (process.argv.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
   process.stdout.write(
-    "Usage: kumiko-build [app-dir]   build client (dist/) and server (dist-server/) bundles\n",
+    "Usage: kumiko-build [app-dir] [--entry <path>]...   build client (dist/) and server (dist-server/) bundles; --entry adds a server entry point (dist-server/<basename>.js)\n",
   );
   process.exit(0);
 }
 
-const explicit = process.argv.slice(2).find((arg) => !arg.startsWith("-"));
-const cwd = explicit ? resolve(process.cwd(), explicit) : process.cwd();
-
 const red = "\x1b[31m";
 const yellow = "\x1b[33m";
 const reset = "\x1b[0m";
 
 try {
+  const buildArgs = parseKumikoBuildArgs(process.argv.slice(2));
+  const cwd = buildArgs.appDir ? resolve(process.cwd(), buildArgs.appDir) : process.cwd();
+
   // Read once up front — resolveClientEntries can throw (mutual exclusion,
   // malformed declaration, unmigrated legacy client-*.tsx files) and that
   // must surface through the same ✗/exit(1) path as every other build error.
@@ -77,6 +82,7 @@ try {
     const result = await buildServerBundle({
       cwd,
       ...(extraRuntimeExternals.length > 0 && { extraRuntimeExternals }),
+      ...(buildArgs.extraEntries.length > 0 && { extraEntries: buildArgs.extraEntries }),
     });
     const ms = Math.round(performance.now() - t0);
     // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg

package/dist/build-server-bundle.d.ts

@@ -8,6 +8,11 @@ export type BuildServerBundleOptions = {
     readonly extraRuntimeExternals?: readonly string[];
     /** Zusätzliche Build-only-Externals. App-spezifisch — Default leer. */
     readonly extraBuildOnlyExternals?: readonly string[];
+    /** Additional entry points (paths relative to cwd, e.g. "bin/remote-probe.ts"),
+     *  each emitted as `<basename>.js` next to server.js and sharing its chunks.
+     *  A missing file or a basename that collides with a built-in entry or another
+     *  extra entry throws. */
+    readonly extraEntries?: readonly string[];
 };
 export type BuildServerBundleEntry = {
     readonly file: string;
@@ -15,7 +20,7 @@ export type BuildServerBundleEntry = {
 };
 export type BuildServerBundleResult = {
     readonly outDir: string;
-    /** Named entry files (server.js, plus kumiko.js, worker.js and bootstrap.js when present). */
+    /** Named entry files (server.js, plus kumiko.js, worker.js, bootstrap.js and extra entries when present). */
     readonly entries: readonly BuildServerBundleEntry[];
     /** Geteilte Framework-Chunks (von splitting). */
     readonly chunks: readonly BuildServerBundleEntry[];
@@ -25,6 +30,13 @@ export type BuildServerBundleResult = {
 };
 export declare function buildServerBundle(options?: BuildServerBundleOptions): Promise<BuildServerBundleResult>;
 export declare function discoverServerEntry(cwd: string): string | undefined;
+export type KumikoBuildArgs = {
+    readonly appDir: string | undefined;
+    readonly extraEntries: readonly string[];
+};
+/** Parse `kumiko-build [app-dir] [--entry <path>]...` (also `--entry=<path>`).
+ *  Unknown flags and a missing `--entry` value throw instead of being ignored. */
+export declare function parseKumikoBuildArgs(args: readonly string[]): KumikoBuildArgs;
 /** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build (#1484).
  *  Invalid / missing shapes → empty list (CLI stays convention-driven). */
 export declare function readExtraRuntimeExternals(cwd: string): readonly string[];

package/dist/build-server-bundle.js

@@ -12,11 +12,14 @@
 //                             background worker as its own process from the same image)
 //   bin/bootstrap.ts       →  dist-server/bootstrap.js (optional, next to bin/main.ts:
 //                             one-shot runBootstrap provisioning, run as a k8s Job)
+//   extraEntries[i]        →  dist-server/<basename>.js (opt-in, e.g. a probe script
+//                             `bin/remote-probe.ts`; CLI: repeatable `--entry <path>`)
 //   dist-server/package.json → runtime-deps mit gepinnten Versionen
 //
 // All entries are built in ONE Bun.build call with `splitting`: the framework
-// lands once as shared chunk-*.js and server.js, kumiko.js, worker.js and
-// bootstrap.js are thin entries importing it. Separate bundles would inline ~14 MB per entry.
+// lands once as shared chunk-*.js and server.js, kumiko.js, worker.js,
+// bootstrap.js and the extra entries are thin entries importing it. Separate
+// bundles would inline ~14 MB per entry.
 //
 // Output:
 //
@@ -25,6 +28,7 @@
 //     kumiko.js            ← Migrate-CLI-Entry (wenn bin/kumiko.ts gefunden)
 //     worker.js            ← worker entry (if bin/worker.ts sits next to main.ts)
 //     bootstrap.js         ← provisioning entry (if bin/bootstrap.ts sits next to main.ts)
+//     <basename>.js        ← one per extraEntries path
 //     chunk-*.js           ← geteilte Framework-Chunks
 //     package.json         ← runtime-deps mit gepinnten Versionen
 //
@@ -41,7 +45,7 @@
 //                          resolution-during-build ab. NICHT in runtime-deps.
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseJsonOrThrow, parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 const hasBun = typeof Bun !== "undefined";
 // Pakete die das Bundle zur Laufzeit weiter referenziert (`from "<pkg>"` nach
@@ -85,6 +89,33 @@ const BUILD_ONLY_EXTERNALS = [
 // ist die Runtime-Convention; der Entry wird von nichts importiert (nur die
 // chunks werden referenziert, per relativem Pfad), darum ist der Rename sicher.
 const ENTRY_RENAMES = { "main.js": "server.js" };
+const OPTIONAL_SIBLING_ENTRY_NAMES = ["worker", "bootstrap"];
+// Output names the built-in entries occupy ("main" is renamed to server.js).
+const RESERVED_ENTRY_OUTPUT_NAMES = new Set([
+    "server.js",
+    "main.js",
+    "kumiko.js",
+    ...OPTIONAL_SIBLING_ENTRY_NAMES.map((name) => `${name}.js`),
+]);
+function resolveExtraEntries(cwd, extraEntries) {
+    const claimedOutputNames = new Map();
+    return extraEntries.map((entry) => {
+        const absolute = resolve(cwd, entry);
+        if (!existsSync(absolute) || !statSync(absolute).isFile()) {
+            throw new Error(`[buildServerBundle] extra entry "${entry}" does not exist (resolved to ${absolute}).`);
+        }
+        const outputName = `${basename(absolute, extname(absolute))}.js`;
+        if (RESERVED_ENTRY_OUTPUT_NAMES.has(outputName)) {
+            throw new Error(`[buildServerBundle] extra entry "${entry}" would emit ${outputName}, which a built-in entry already uses. Rename the file.`);
+        }
+        const previous = claimedOutputNames.get(outputName);
+        if (previous !== undefined) {
+            throw new Error(`[buildServerBundle] extra entries "${previous}" and "${entry}" both emit ${outputName}. Rename one of the files.`);
+        }
+        claimedOutputNames.set(outputName, entry);
+        return absolute;
+    });
+}
 export async function buildServerBundle(options = {}) {
     if (!hasBun) {
         throw new Error("buildServerBundle requires Bun runtime (Bun.build is missing).");
@@ -100,6 +131,7 @@ export async function buildServerBundle(options = {}) {
     if (kumikoCli && !existsSync(kumikoCli)) {
         throw new Error(`[buildServerBundle] Repo-Root erkannt (${repoRoot}), aber bin/kumiko.ts fehlt — kann Migrate-CLI nicht bündeln.`);
     }
+    const extraEntryPaths = resolveExtraEntries(cwd, options.extraEntries ?? []);
     const externals = [
         ...RUNTIME_EXTERNALS,
         ...BUILD_ONLY_EXTERNALS,
@@ -110,10 +142,13 @@ export async function buildServerBundle(options = {}) {
     await mkdir(outDir, { recursive: true });
     // Ein Bun.build-Call mit allen Entries + splitting → das Framework wird
     // einmal als shared chunk abgelegt statt pro Entry inlined.
-    const optionalSiblingEntries = ["worker", "bootstrap"]
-        .map((baseName) => discoverSiblingEntry(dirname(serverEntry), baseName))
-        .filter((path) => path !== undefined);
-    const entrypoints = [serverEntry, ...(kumikoCli ? [kumikoCli] : []), ...optionalSiblingEntries];
+    const optionalSiblingEntries = OPTIONAL_SIBLING_ENTRY_NAMES.map((baseName) => discoverSiblingEntry(dirname(serverEntry), baseName)).filter((path) => path !== undefined);
+    const entrypoints = [
+        serverEntry,
+        ...(kumikoCli ? [kumikoCli] : []),
+        ...optionalSiblingEntries,
+        ...extraEntryPaths,
+    ];
     const result = await Bun.build({
         entrypoints,
         outdir: outDir,
@@ -188,6 +223,34 @@ function findRepoRoot(start) {
     }
     return undefined;
 }
+/** Parse `kumiko-build [app-dir] [--entry <path>]...` (also `--entry=<path>`).
+ *  Unknown flags and a missing `--entry` value throw instead of being ignored. */
+export function parseKumikoBuildArgs(args) {
+    let appDir;
+    const extraEntries = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            break;
+        if (arg === "--entry" || arg.startsWith("--entry=")) {
+            const value = arg === "--entry" ? args[++i] : arg.slice("--entry=".length);
+            if (value === undefined || value === "") {
+                throw new Error("kumiko-build: --entry needs a path, e.g. --entry bin/remote-probe.ts");
+            }
+            extraEntries.push(value);
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`kumiko-build: unknown option ${arg}`);
+        }
+        else if (appDir === undefined) {
+            appDir = arg;
+        }
+        else {
+            throw new Error(`kumiko-build: unexpected argument ${arg}`);
+        }
+    }
+    return { appDir, extraEntries };
+}
 /** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build (#1484).
  *  Invalid / missing shapes → empty list (CLI stays convention-driven). */
 export function readExtraRuntimeExternals(cwd) {

package/dist/build.d.ts

@@ -1,2 +1,2 @@
 export { ASSETS_DIR, type BuildManifest, type BuildProdBundleOptions, type BuildResult, buildProdBundle, type ClientEntry, type ClientEntryDeclaration, discoverHtmlTemplate, formatBuildResult, injectAssetTags, readClientEntriesConfig, resolveClientEntries, } from "@cosmicdrift/kumiko-server-runtime/build-prod-bundle";
-export { type BuildServerBundleEntry, type BuildServerBundleOptions, type BuildServerBundleResult, buildServerBundle, discoverServerEntry, formatServerBuildResult, readExtraRuntimeExternals, } from "./build-server-bundle.ts";
+export { type BuildServerBundleEntry, type BuildServerBundleOptions, type BuildServerBundleResult, buildServerBundle, discoverServerEntry, formatServerBuildResult, type KumikoBuildArgs, parseKumikoBuildArgs, readExtraRuntimeExternals, } from "./build-server-bundle.ts";

package/dist/build.js

@@ -2,4 +2,4 @@
 // damit der Main-Barrel kein Bun-Toolchain-Bundle in Production-Reads zieht
 // (z.B. wenn drizzle-kit die App-Config unter Node lädt).
 export { ASSETS_DIR, buildProdBundle, discoverHtmlTemplate, formatBuildResult, injectAssetTags, readClientEntriesConfig, resolveClientEntries, } from "@cosmicdrift/kumiko-server-runtime/build-prod-bundle";
-export { buildServerBundle, discoverServerEntry, formatServerBuildResult, readExtraRuntimeExternals, } from "./build-server-bundle.js";
+export { buildServerBundle, discoverServerEntry, formatServerBuildResult, parseKumikoBuildArgs, readExtraRuntimeExternals, } from "./build-server-bundle.js";

package/dist/cli.d.ts

@@ -1,3 +1,3 @@
-export { buildProdBundle, buildServerBundle, discoverServerEntry, formatBuildResult, formatServerBuildResult, readClientEntriesConfig, readExtraRuntimeExternals, resolveClientEntries, } from "./build.ts";
+export { buildProdBundle, buildServerBundle, discoverServerEntry, formatBuildResult, formatServerBuildResult, parseKumikoBuildArgs, readClientEntriesConfig, readExtraRuntimeExternals, resolveClientEntries, } from "./build.ts";
 export { createCrashTracker } from "./crash-tracker.ts";
 export { runInitDeployCli } from "./init-deploy-cli.ts";

package/dist/cli.js

@@ -2,6 +2,6 @@
 // the package self-reference (`@cosmicdrift/kumiko-dev-server/cli`) so they
 // resolve to src in the workspace and to dist once installed from the
 // tarball, where `src` is not shipped.
-export { buildProdBundle, buildServerBundle, discoverServerEntry, formatBuildResult, formatServerBuildResult, readClientEntriesConfig, readExtraRuntimeExternals, resolveClientEntries, } from "./build.js";
+export { buildProdBundle, buildServerBundle, discoverServerEntry, formatBuildResult, formatServerBuildResult, parseKumikoBuildArgs, readClientEntriesConfig, readExtraRuntimeExternals, resolveClientEntries, } from "./build.js";
 export { createCrashTracker } from "./crash-tracker.js";
 export { runInitDeployCli } from "./init-deploy-cli.js";

package/dist/create-kumiko-server.js

@@ -23,12 +23,13 @@ import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-
 import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, createClientIpResolver, generateToken, sessionCookieName, } from "@cosmicdrift/kumiko-framework/api";
 import { buildAppSchema } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { rankPreferredLocales } from "@cosmicdrift/kumiko-framework/i18n";
 import { createMetricsForFactory } from "@cosmicdrift/kumiko-framework/observability";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { resolveAndInjectPageHead, } from "@cosmicdrift/kumiko-headless/apex";
 import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize, } from "@cosmicdrift/kumiko-server-runtime/bun-serve-options";
-import { makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+import { makeDispatchSystemQuery, makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
 import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_URL_PREFIX, resolveRendererWebFontsDir, } from "@cosmicdrift/kumiko-server-runtime/renderer-web-fonts";
 import { buildRequestBoundSystemQuery } from "@cosmicdrift/kumiko-server-runtime/request-bound-system-query";
 import { canResolveTailwindStylesheet, resolveTailwindCli, } from "@cosmicdrift/kumiko-server-runtime/resolve-tailwind-cli";
@@ -633,6 +634,7 @@ export async function createKumikoServer(options) {
             registry: stack.registry,
             metricsFor: createMetricsForFactory(stack.observability.meter),
             dispatchSystemWrite: makeDispatchSystemWrite(stack.dispatcher),
+            dispatchSystemQuery: makeDispatchSystemQuery(stack.dispatcher),
         });
     }
     // Hook für Caller-spezifische Tables + Seed. Läuft nach den Entity-
@@ -755,6 +757,10 @@ export async function createKumikoServer(options) {
             html = await resolveAndInjectPageHead(html, options.resolvePageHead, {
                 path: url.pathname,
                 host,
+                preferredLocales: rankPreferredLocales({
+                    queryLang: url.searchParams.get("lang"),
+                    acceptLanguage: req.headers.get("accept-language"),
+                }),
                 systemQuery: buildDevSystemQuery(req, socketAddress),
                 requestSignal: req.signal,
             });

package/dist/scaffold-app.js

@@ -211,7 +211,9 @@ function compareImportKeys(a, b) {
 function isRelativeSpecifier(specifier) {
     return specifier.startsWith("./") || specifier.startsWith("../");
 }
-function renderImportLine({ specifier, names, typeOnly }) {
+function renderImportLine({ specifier, names, typeOnly, defaultName }) {
+    if (defaultName !== undefined)
+        return `import ${defaultName} from "${specifier}";`;
     const sorted = [...names].sort(compareImportKeys);
     const keyword = typeOnly === true ? "import type" : "import";
     const oneLine = `${keyword} { ${sorted.join(", ")} } from "${specifier}";`;
@@ -355,6 +357,7 @@ function renderMain(appName) {
             names: ["requireKmsWiring", "resolveKmsWiring"],
         },
         { specifier: "../src/run-config", names: ["APP_FEATURES"] },
+        { specifier: "../kumiko.config", names: [], defaultName: "appConfig" },
         { specifier: "./env-schema", names: ["envSchema"] },
     ]);
     const authBlock = renderAdminAuthBlock(appName, [
@@ -385,6 +388,7 @@ const kmsWiring =
 
 await runProdApp({
   features: APP_FEATURES,
+  ...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions }),
   envSchema,
   staticDir: "./dist",
   ...kmsWiring,
@@ -398,6 +402,7 @@ function renderServer(appName) {
         { specifier: "@cosmicdrift/kumiko-dev-server", names: ["runDevApp"] },
         { specifier: "@cosmicdrift/kumiko-framework/engine", names: ["TenantId"], typeOnly: true },
         { specifier: "../src/run-config", names: ["APP_FEATURES"] },
+        { specifier: "../kumiko.config", names: [], defaultName: "appConfig" },
         { specifier: "../src/seed", names: ["seedDemoTasks"] },
     ]);
     // Dev-only emailVerified skips the login verify gate for the seeded admin;
@@ -420,6 +425,7 @@ const DEFAULT_TENANT_ID = "${tenantId}" as TenantId;
 
 await runDevApp({
   features: APP_FEATURES,
+  ...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions }),
   welcomeBanner: true,
   clientEntry: "./src/client.tsx",
   seeds: [seedDemoTasks],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.371.1",
+  "version": "0.372.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding. 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>",
@@ -72,14 +72,14 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.371.1",
-    "@cosmicdrift/kumiko-framework": "0.371.1",
-    "@cosmicdrift/kumiko-headless": "0.371.1",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.371.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.371.1",
-    "@cosmicdrift/kumiko-server-runtime": "0.371.1",
-    "@cosmicdrift/kumiko-testing": "0.371.1",
-    "@cosmicdrift/kumiko-types": "0.371.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.372.0",
+    "@cosmicdrift/kumiko-framework": "0.372.0",
+    "@cosmicdrift/kumiko-headless": "0.372.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.372.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.372.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.372.0",
+    "@cosmicdrift/kumiko-testing": "0.372.0",
+    "@cosmicdrift/kumiko-types": "0.372.0",
     "bun-types": "^1.3.13",
     "ts-morph": "^28.0.0",
     "zod": "^4.4.3"

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.372.0",
+    "type": "improvement",
+    "title": "kumiko-build --entry and buildServerBundle extraEntries bundle additional server entry points as dist-server/<basename>.js",
+    "detail": "Opt-in per file, not every bin/ helper module; the output shares the chunk files with server.js. Unknown kumiko-build options now fail the build."
+  },
   {
     "version": "0.371.0",
     "type": "improvement",

package/templates/managed/kumiko-schema.ts.template

@@ -9,4 +9,7 @@ import appConfig from "../kumiko.config";
 
 export const FEATURES: readonly FeatureDefinition[] = allAppFeatures(appConfig);
 
+// `kumiko check` validates the boot with the options kumiko.config.ts declares.
+export const VALIDATE_BOOT_OPTIONS = appConfig.validateBootOptions;
+
 export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);