@cosmicdrift/kumiko-server-runtime 0.329.0 → 0.330.2

package/README.md

@@ -0,0 +1,15 @@
+# @cosmicdrift/kumiko-server-runtime
+
+Production server boot for Kumiko apps: connections, schema drift gate, seeds, lifecycle and graceful shutdown. The prod counterpart to `runDevApp` in `@cosmicdrift/kumiko-dev-server`, without dev, scaffold or codegen tooling.
+
+## Install
+
+```bash
+bun add @cosmicdrift/kumiko-server-runtime
+```
+
+```ts
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
+```
+
+Documentation: https://kumiko.rocks

package/dist/boot/apply-boot-seeds.d.ts

@@ -0,0 +1,8 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+export declare function applyBootSeeds(deps: {
+    registry: Registry;
+    db: DbConnection;
+    cipher?: EnvelopeCipher;
+}): Promise<void>;

package/{src/boot/apply-boot-seeds.ts → dist/boot/apply-boot-seeds.js}

@@ -1,8 +1,4 @@
 import { seedAllConfigValues } from "@cosmicdrift/kumiko-bundled-features/config";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
-
 // Single boot-seed entry-point. runDevApp + runProdApp both call this
 // from their post-stack hook, so the wiring lives in exactly one place
 // — config-seed-boot.integration.ts pins this helper, which means a
@@ -10,10 +6,6 @@ import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 // surfaces as a missing-helper-use in code review rather than silently
 // shipping a server that never seeds.
 // @wrapper-known semantic-alias
-export async function applyBootSeeds(deps: {
-  registry: Registry;
-  db: DbConnection;
-  cipher?: EnvelopeCipher;
-}): Promise<void> {
-  await seedAllConfigValues(deps.registry, deps.db, deps.cipher);
+export async function applyBootSeeds(deps) {
+    await seedAllConfigValues(deps.registry, deps.db, deps.cipher);
 }

package/dist/boot/boot-crypto.d.ts

@@ -0,0 +1,9 @@
+import { type DekCache, type EnvelopeCipher, type MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+export declare function envHasMasterKek(env: Record<string, string | undefined>): boolean;
+export type BootCrypto = {
+    readonly masterKeyProvider?: MasterKeyProvider;
+    readonly configCipher?: EnvelopeCipher;
+    readonly entityFieldCipher?: EnvelopeCipher;
+    readonly dekCache: DekCache;
+};
+export declare function resolveBootCrypto(envSource: Record<string, string | undefined>, masterKeyOverride?: MasterKeyProvider): BootCrypto;

package/dist/boot/boot-crypto.js

@@ -0,0 +1,39 @@
+// One place that turns env/options into the app-wide crypto objects:
+// the MasterKeyProvider (KUMIKO_SECRETS_MASTER_KEY_V<n> keyring) and the
+// EnvelopeCipher for `encrypted: true` config keys. runProdApp and
+// runDevApp both resolve this once and thread it into
+// buildBootExtraContext + applyBootSeeds so resolver, set-handler and
+// seeds share the same cipher instance (and DEK cache).
+import { createDekCache, createEnvelopeCipher, createEnvMasterKeyProvider, } from "@cosmicdrift/kumiko-framework/secrets";
+// Keyring detection without throwing: only build the env provider when at
+// least one versioned KEK is actually set. Covers (a) apps without any
+// encryption — no KEK requirement, and (b) dev with an app-supplied
+// provider in options.masterKey — env stays irrelevant.
+const MASTER_KEK_VAR = /^KUMIKO_SECRETS_MASTER_KEY_V\d+$/;
+export function envHasMasterKek(env) {
+    return Object.entries(env).some(([k, v]) => MASTER_KEK_VAR.test(k) && !!v);
+}
+export function resolveBootCrypto(envSource, masterKeyOverride) {
+    const masterKeyProvider = masterKeyOverride ??
+        (envHasMasterKek(envSource)
+            ? createEnvMasterKeyProvider({
+                // CURRENT_VERSION default "1" spiegelt secretsEnvSchema — ohne
+                // ihn wirft der raw-env-Provider, obwohl V1 gesetzt ist.
+                env: {
+                    ...envSource,
+                    KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: envSource["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+                },
+            })
+            : undefined);
+    const dekCache = createDekCache();
+    const configCipher = masterKeyProvider
+        ? createEnvelopeCipher(masterKeyProvider, { dekCache })
+        : undefined;
+    const entityFieldCipher = configCipher;
+    return {
+        ...(masterKeyProvider && { masterKeyProvider }),
+        ...(configCipher && { configCipher }),
+        ...(entityFieldCipher && { entityFieldCipher }),
+        dekCache,
+    };
+}

package/dist/boot/job-run-logger.d.ts

@@ -0,0 +1,19 @@
+import { createJobRunLogger } from "@cosmicdrift/kumiko-bundled-features/jobs";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { AppContext } from "@cosmicdrift/kumiko-framework/engine/types";
+import { type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { type Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
+export declare function jobRunLoggerCallbacks(registry: Registry, db: DbConnection): ReturnType<typeof createJobRunLogger> | undefined;
+/** Dev-server parity: consume api + worker lanes when jobs are registered. */
+export declare function startDevJobRunners(opts: {
+    readonly registry: Registry;
+    readonly db: DbConnection;
+    readonly context: AppContext;
+    readonly redisUrl: string;
+    readonly dispatcher: Dispatcher;
+    readonly queueNamePrefix: string;
+}): Promise<{
+    readonly runners: readonly JobRunner[];
+    readonly stop: () => Promise<void>;
+}>;

package/dist/boot/job-run-logger.js

@@ -0,0 +1,44 @@
+import { createJobRunLogger } from "@cosmicdrift/kumiko-bundled-features/jobs";
+import { createJobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { dispatcherToWriteRef } from "@cosmicdrift/kumiko-framework/pipeline";
+export function jobRunLoggerCallbacks(registry, db) {
+    if (registry.getFeature("jobs") === undefined)
+        return undefined;
+    return createJobRunLogger({ db, registry });
+}
+/** Dev-server parity: consume api + worker lanes when jobs are registered. */
+export async function startDevJobRunners(opts) {
+    const jobs = [...opts.registry.getAllJobs().values()];
+    if (opts.registry.getFeature("jobs") === undefined || jobs.length === 0) {
+        return { runners: [], stop: async () => { } };
+    }
+    const logger = createJobRunLogger({ db: opts.db, registry: opts.registry });
+    const runners = [];
+    // `?? "worker"` mirrors job-runner's laneForJob: a job without an explicit
+    // runIn is enqueued onto the worker lane, so filtering those out would leave
+    // its queue without a consumer whenever no other job named the lane.
+    const lanes = new Set(jobs.map((j) => j.runIn ?? "worker"));
+    for (const lane of lanes) {
+        const jr = createJobRunner({
+            registry: opts.registry,
+            context: { ...opts.context, db: opts.db },
+            redisUrl: opts.redisUrl,
+            queueNamePrefix: opts.queueNamePrefix,
+            consumerLane: lane,
+            ...logger,
+        });
+        // Without this, ctx.write/ctx.queryAs inside a dev-run job throw
+        // "dispatcher attached — call attachDispatcher() first" on their first
+        // call — the prod entrypoints attach automatically, dev boot must too.
+        jr.attachDispatcher(dispatcherToWriteRef(opts.dispatcher));
+        await jr.start();
+        runners.push(jr);
+    }
+    return {
+        runners,
+        stop: async () => {
+            for (const runner of runners)
+                await runner.stop();
+        },
+    };
+}

package/dist/boot/pii-event-backfill-on-boot.d.ts

@@ -0,0 +1,13 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+export declare const SKIP_PII_BACKFILL_ENV = "KUMIKO_SKIP_PII_BACKFILL";
+type ShutdownRegistry = {
+    registerShutdownHook(name: string, fn: () => Promise<void>): void;
+};
+export declare function startPiiEventBackfillOnBoot(opts: {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+    readonly lifecycle: ShutdownRegistry;
+    readonly envSource: Readonly<Record<string, string | undefined>>;
+}): void;
+export {};

package/dist/boot/pii-event-backfill-on-boot.js

@@ -0,0 +1,25 @@
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { runPiiEventBackfill } from "@cosmicdrift/kumiko-framework/migrations";
+export const SKIP_PII_BACKFILL_ENV = "KUMIKO_SKIP_PII_BACKFILL";
+// Runs in the background instead of blocking boot: the first run after a bump
+// scans the whole store and would delay readiness in proportion to its size.
+// Every batch is its own transaction, so an abort at any point is safe.
+export function startPiiEventBackfillOnBoot(opts) {
+    if (opts.envSource[SKIP_PII_BACKFILL_ENV] === "1") {
+        // skip: operator opted out via KUMIKO_SKIP_PII_BACKFILL
+        return;
+    }
+    const log = createFallbackLogger("pii-event-backfill");
+    const abortController = new AbortController();
+    const run = runPiiEventBackfill(opts.db, opts.registry, {
+        signal: abortController.signal,
+    }).then(() => undefined, (e) => {
+        log.error("PII event backfill crashed; it will be retried on the next boot", {
+            error: e instanceof Error ? e.message : String(e),
+        });
+    });
+    opts.lifecycle.registerShutdownHook("piiEventBackfill", async () => {
+        abortController.abort();
+        await run;
+    });
+}

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

@@ -0,0 +1,103 @@
+export type BuildProdBundleOptions = {
+    /** App-Root. Default: process.cwd(). */
+    readonly cwd?: string;
+    /** Output-Folder relativ zu cwd. Default: "dist". */
+    readonly outDir?: string;
+    /** Stylesheet-Override. Default: erst src/styles.css, dann
+     *  @cosmicdrift/kumiko-renderer-web/styles.css wenn clientEntry da ist.
+     *  `false` deaktiviert die CSS-Pipeline explizit. */
+    readonly stylesheet?: string | false;
+} & ClientEntriesConfig;
+/** One declared client entry, read from package.json `kumiko.clientEntries`.
+ *  `name` becomes the output filename (`client-<name>.js` / `<name>.html`
+ *  unless `htmlPath` overrides it). */
+export type ClientEntryDeclaration = {
+    readonly name: string;
+    readonly sourceFile: string;
+    readonly htmlPath?: string;
+};
+/** The two mutually exclusive shapes read from package.json `kumiko.*`.
+ *  Neither set → convention mode (src/client.tsx | src/client.ts). */
+export type ClientEntriesConfig = {
+    readonly clientEntry?: string;
+    readonly clientEntries?: readonly ClientEntryDeclaration[];
+};
+export type BuildManifest = Readonly<Record<string, string>>;
+export type BuildResult = {
+    readonly outDir: string;
+    /** Logical → hashed-URL mapping. Beispiel:
+     *    { "client.js": "/assets/client-a3f2.js",
+     *      "styles.css": "/assets/styles-9b4c.css" } */
+    readonly manifest: BuildManifest;
+    /** Build-Identität (Hash über die Asset-URLs) + lesbarer Zeitstempel.
+     *  undefined bei vanilla public-only-Builds (kein Bundle). */
+    readonly buildInfo?: BuildInfo;
+};
+/** In index.html gebacken (`window.__KUMIKO_BUILD__`) UND als
+ *  dist/build-info.json geschrieben. Der UpdateChecker pollt build-info.json
+ *  und vergleicht `id` gegen den geladenen Stand → Reload-Banner bei Drift. */
+export type BuildInfo = {
+    /** Hash über die sortierten (content-gehashten) Asset-URLs. Ändert sich
+     *  gdw. sich ein Asset ändert — selbsttragend, kein Env-Var/Dockerfile. */
+    readonly id: string;
+    /** ISO-Zeitstempel des Builds, lesbare Anzeige-Version (ersetzt den rohen sha). */
+    readonly builtAt: string;
+};
+/** 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. */
+export declare const ASSETS_DIR = "assets";
+export declare function buildProdBundle(options?: BuildProdBundleOptions): Promise<BuildResult>;
+export type ClientEntry = {
+    /** Logical name. "client" for single-entry mode (package.json
+     *  `kumiko.clientEntry` or the src/client.tsx convention); otherwise the
+     *  `name` declared in package.json `kumiko.clientEntries[]`. */
+    readonly name: string;
+    /** Absolute path to the TypeScript entry module. */
+    readonly sourceFile: string;
+    /** Manifest key & logical asset path. "client.js" for single-entry mode,
+     *  otherwise "client-<name>.js". */
+    readonly manifestKey: string;
+    /** HTML template path — absolute when declared or discovered on disk,
+     *  otherwise a bare default filename ("index.html", "<name>.html")
+     *  resolved against cwd by the caller. Naming is deliberately symmetric
+     *  to `runDevApp.clientEntries[].htmlPath` so build and dev server agree
+     *  on the same convention. */
+    readonly htmlPath: string;
+};
+/** Resolves the client entries to build. Public — also called from
+ *  `kumiko-build`/`kumiko build` via `@cosmicdrift/kumiko-dev-server/build`,
+ *  not just from unit tests.
+ *
+ * Precedence (fw#2320 — 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".
+ *   4. Neither → convention: src/client.tsx | src/client.ts (name "client").
+ *      If that convention finds nothing but src/ still has legacy
+ *      `client-<suffix>.tsx` files, throws a migration error instead of
+ *      silently shipping a build without their bundles. */
+export declare function resolveClientEntries(cwd: string, declared: ClientEntriesConfig): readonly ClientEntry[];
+/** Reads package.json → `kumiko.clientEntry` / `kumiko.clientEntries`.
+ *  Missing file or missing keys → `{}` (falls back to convention mode). A
+ *  malformed value under either key throws — a typo here must fail the
+ *  build loudly instead of silently dropping declared entries. */
+export declare function readClientEntriesConfig(cwd: string): ClientEntriesConfig;
+type ResolvedStylesheet = {
+    readonly path: string;
+    /** True nur wenn wir auf das gepackte renderer-web-styles.css zurückfallen
+     *  (App hat clientEntry + renderer-web-Dep, aber kein eigenes src/styles.css).
+     *  Steuert den Shell-Klassen-Sentinel im Build. */
+    readonly isRendererWebFallback: boolean;
+};
+export declare function assertRendererWebShellPresent(css: string, stylesheet: ResolvedStylesheet): void;
+export declare function discoverHtmlTemplate(cwd: string): string | undefined;
+export declare function runTailwindOnce(entry: string, cwd: string): Promise<string>;
+export declare function buildMissingTemplateError(manifest: BuildManifest, entry: ClientEntry): string;
+export declare function injectAssetTags(html: string, manifest: BuildManifest, entry: ClientEntry, buildInfo?: BuildInfo): string;
+export declare function computeBuildId(manifest: BuildManifest): string;
+/** 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. */
+export declare function formatBuildResult(result: BuildResult, durationMs: number): string;
+export {};