@cosmicdrift/kumiko-server-runtime 0.1.0

package/src/__tests__/compose-features.test.ts

@@ -0,0 +1,128 @@
+// Unit-Tests für composeFeatures.authOptions — pinst dass die
+// passwordReset / emailVerification options an
+// createAuthEmailPasswordFeature durchgereicht werden, sodass die
+// request- und confirm-Handler im resultierenden Feature registriert
+// sind. Bug-Pattern: ohne diesen Wiring würde runProdApp.options.auth.
+// passwordReset = {sendResetEmail, appResetUrl} die routes mounten,
+// aber die Handler fehlen → POST /api/auth/request-password-reset
+// dispatched ins Leere → 500.
+
+import { describe, expect, spyOn, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { composeFeatures } from "../compose-features";
+
+const noopFeature = defineFeature("noop-app", () => {});
+
+// Mirrors what the create-kumiko-app picker hands back when the user
+// ticks an auto-mounted feature: a stub with the same name as a bundled
+// one. The dedupe path drops it and warns.
+const pickerAuthDupe = defineFeature("auth-email-password", () => {});
+
+const HMAC_SECRET = "test-secret-with-at-least-32-bytes-aaa";
+
+describe("composeFeatures", () => {
+  test("includeBundled=false → nur App-Features", () => {
+    const features = composeFeatures([noopFeature], { includeBundled: false });
+    expect(features.map((f) => f.name)).toEqual(["noop-app"]);
+  });
+
+  test("includeBundled=true → 4 bundled Features davor", () => {
+    const features = composeFeatures([noopFeature], { includeBundled: true });
+    expect(features.map((f) => f.name)).toEqual([
+      "config",
+      "user",
+      "tenant",
+      "auth-email-password",
+      "noop-app",
+    ]);
+  });
+
+  test("authOptions.passwordReset → request-password-reset + reset-password handlers registriert", () => {
+    const features = composeFeatures([noopFeature], {
+      includeBundled: true,
+      authOptions: { passwordReset: { hmacSecret: HMAC_SECRET, appUrl: "https://app/reset" } },
+    });
+    const auth = features.find((f) => f.name === "auth-email-password");
+    expect(auth).toBeDefined();
+    if (!auth) return;
+    const handlerNames = Array.from(Object.keys(auth.writeHandlers));
+    expect(handlerNames).toContain("request-password-reset");
+    expect(handlerNames).toContain("reset-password");
+  });
+
+  test("authOptions.emailVerification → request-email-verification + verify-email handlers registriert", () => {
+    const features = composeFeatures([noopFeature], {
+      includeBundled: true,
+      authOptions: { emailVerification: { hmacSecret: HMAC_SECRET, appUrl: "https://app/verify" } },
+    });
+    const auth = features.find((f) => f.name === "auth-email-password");
+    expect(auth).toBeDefined();
+    if (!auth) return;
+    const handlerNames = Array.from(Object.keys(auth.writeHandlers));
+    expect(handlerNames).toContain("request-email-verification");
+    expect(handlerNames).toContain("verify-email");
+  });
+
+  test("authOptions.signup → signup-request + signup-confirm handlers registriert", () => {
+    const features = composeFeatures([noopFeature], {
+      includeBundled: true,
+      authOptions: { signup: { appUrl: "https://app/signup/complete" } },
+    });
+    const auth = features.find((f) => f.name === "auth-email-password");
+    expect(auth).toBeDefined();
+    if (!auth) return;
+    const handlerNames = Array.from(Object.keys(auth.writeHandlers));
+    expect(handlerNames).toContain("signup-request");
+    expect(handlerNames).toContain("signup-confirm");
+  });
+
+  test("OHNE authOptions → KEINE reset/verify-handlers (anti-default-deploy-bug)", () => {
+    // Genau der Bug der vom Review-Agent gefangen wurde: composeFeatures
+    // ohne authOptions registriert die handler nicht. Wenn jemand das
+    // versehentlich vergisst und nur die routes (auth-routes-config)
+    // wired, schlagen die requests auf prod fehl. Der Test pinst dass
+    // dieser default-deny-Pfad bewusst leer ist.
+    const features = composeFeatures([noopFeature], { includeBundled: true });
+    const auth = features.find((f) => f.name === "auth-email-password");
+    expect(auth).toBeDefined();
+    if (!auth) return;
+    const handlerNames = Array.from(Object.keys(auth.writeHandlers));
+    expect(handlerNames).not.toContain("request-password-reset");
+    expect(handlerNames).not.toContain("reset-password");
+    expect(handlerNames).not.toContain("request-email-verification");
+    expect(handlerNames).not.toContain("verify-email");
+    // Die regulären auth-handlers (login/logout/change-password) MÜSSEN
+    // aber immer da sein — das ist der core-flow.
+    expect(handlerNames).toContain("login");
+    expect(handlerNames).toContain("logout");
+  });
+
+  test("app feature duplicating a bundled name is dropped (no createRegistry crash)", () => {
+    // create-kumiko-app's picker hands back createAuthEmailPasswordFeature()
+    // because the user ticked it in the recommended set; runDevApp then adds
+    // its OWN bundled copy via includeBundled:true, and createRegistry throws
+    // "Duplicate feature: auth-email-password". The dedupe path keeps the
+    // bundled instance (it carries authOptions wiring) and drops the app stub.
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const features = composeFeatures([pickerAuthDupe, noopFeature], {
+      includeBundled: true,
+    });
+    // The warn is part of the fix contract (changeset: "warn so the user can
+    // remove the line") — without this assertion the warn is removable with no RED.
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("auth-email-password"));
+    warnSpy.mockRestore();
+    expect(features.map((f) => f.name)).toEqual([
+      "config",
+      "user",
+      "tenant",
+      "auth-email-password",
+      "noop-app",
+    ]);
+    // The kept instance is the bundled one — confirmed by the presence of
+    // login/logout handlers (the picker stub has none).
+    const auth = features.find((f) => f.name === "auth-email-password");
+    expect(auth).toBeDefined();
+    if (!auth) return;
+    expect(Object.keys(auth.writeHandlers)).toContain("login");
+  });
+});

package/src/__tests__/config-seed-boot.integration.test.ts

@@ -0,0 +1,158 @@
+// Pins the boot-wiring contract for config-seeds. runDevApp's onAfterSetup
+// and runProdApp's seed-block both call `applyBootSeeds(...)` — this test
+// calls the SAME helper, so if someone removes the call site from
+// runDevApp / runProdApp the helper still has at least one caller (this
+// test). Code review then sees an orphaned helper, not a silently broken
+// boot. For a stricter end-to-end pin you'd start an actual runDevApp;
+// that's heavy and not done here.
+//
+// Tests:
+//   1. seed rows land in the projection after applyBootSeeds runs,
+//   2. a re-boot is a no-op (idempotent),
+//   3. an admin set on top of a seed wins the resolver cascade; coexistence
+//      vs. override semantics depend on the admin user's tenantId.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  access,
+  createSystemConfig,
+  createSystemSeed,
+  createTenantConfig,
+  createTenantSeed,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { applyBootSeeds } from "../boot/apply-boot-seeds";
+
+const bootSeedsFeature = defineFeature("boot-seeds-test", (r) => {
+  r.requires("config");
+  r.config({
+    keys: {
+      siteName: createTenantConfig("text", {
+        default: "DEFAULT_SITE",
+        read: access.all,
+        write: access.all,
+      }),
+      maintenance: createSystemConfig("boolean", {
+        default: false,
+        read: access.all,
+        write: access.systemAdmin,
+      }),
+    },
+    seeds: {
+      siteName: createTenantSeed({ value: "from-seed" }),
+      maintenance: createSystemSeed({ value: true }),
+    },
+  });
+});
+
+const SITE_KEY = "boot-seeds-test:config:site-name";
+const MAINT_KEY = "boot-seeds-test:config:maintenance";
+
+let stack: TestStack;
+const resolver = createConfigResolver();
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), bootSeedsFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config-seed boot wiring", () => {
+  test("first boot: applyBootSeeds writes one row per seed", async () => {
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const rows = await selectMany(stack.db, configValuesTable);
+    expect(rows.length).toBe(2);
+
+    const siteKeyDef = stack.registry.getConfigKey(SITE_KEY);
+    expect(siteKeyDef).toBeDefined();
+    const sitePeek = await resolver.get(
+      SITE_KEY,
+      siteKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(sitePeek).toBe("from-seed");
+
+    const maintKeyDef = stack.registry.getConfigKey(MAINT_KEY);
+    expect(maintKeyDef).toBeDefined();
+    const maintPeek = await resolver.get(
+      MAINT_KEY,
+      maintKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(maintPeek).toBe(true);
+  });
+
+  test("re-boot: idempotent — every seed already on disk → no extra rows", async () => {
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const rows = await selectMany(stack.db, configValuesTable);
+    expect(rows.length).toBe(2);
+  });
+
+  test("admin set on top of seed wins resolver — Re-Boot preserves admin", async () => {
+    // siteName is a TENANT-scope key. The seed writes a row under
+    // SYSTEM_TENANT_ID (= "for all tenants"). An admin on a real tenant
+    // writes a row under THAT tenantId — higher specificity. Both rows
+    // coexist; the resolver returns the more specific one.
+    //
+    // If the admin happens to write as SYSTEM_TENANT_ID (e.g. test user
+    // is the system-admin on the system-tenant), the admin write hits
+    // the seed-row directly and updates the same aggregate stream. Both
+    // paths end up with the admin value winning — the row-count
+    // assertion makes the path explicit.
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: SITE_KEY, value: "admin-override", scope: "tenant" },
+      TestUsers.systemAdmin,
+    );
+
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const siteKeyDef = stack.registry.getConfigKey(SITE_KEY);
+    expect(siteKeyDef).toBeDefined();
+    const peek = await resolver.get(
+      SITE_KEY,
+      siteKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(peek).toBe("admin-override");
+
+    // Row-count tells us which path was hit:
+    //   - 2 rows = override path (admin tenantId === SYSTEM_TENANT_ID,
+    //     updated the seed-stream in place).
+    //   - 3 rows = coexistence path (admin tenantId !== SYSTEM_TENANT_ID,
+    //     new specific-tenant row sits next to the seed system-row).
+    // Either is correct as long as the resolver picks the admin value.
+    const rows = await selectMany(stack.db, configValuesTable);
+    expect([2, 3]).toContain(rows.length);
+  });
+});

package/src/__tests__/inject-schema.test.ts

@@ -0,0 +1,62 @@
+// injectSchema teilt sich dev-server (every HTML response) und prod-
+// server (static-fallback index.html) Pfad. Bug hier wäre stiller
+// Production-Fail: createKumikoApp findet `window.__KUMIKO_SCHEMA__`
+// nicht und mountet leer. Tests pinnen die Idempotenz + die zwei
+// Insertion-Punkte (vor /client.js-Tag oder vor </body>).
+
+import { describe, expect, test } from "bun:test";
+import { injectSchema } from "../inject-schema";
+
+const SCHEMA = '{"features":[]}';
+const TAG = `<script>window.__KUMIKO_SCHEMA__=${SCHEMA};</script>`;
+
+describe("injectSchema", () => {
+  test("HTML mit /client.js-Tag: Schema-Tag wird DAVOR eingefügt", () => {
+    const html = '<html><body><script src="/client.js" defer></script></body></html>';
+    const out = injectSchema(html, SCHEMA);
+    expect(out).toContain(TAG);
+    // Schema MUSS vor dem Client-Bundle stehen — sonst läuft
+    // createKumikoApp() bevor window.__KUMIKO_SCHEMA__ gesetzt ist.
+    expect(out.indexOf(TAG)).toBeLessThan(out.indexOf('<script src="/client.js"'));
+  });
+
+  test("HTML ohne /client.js-Tag: Schema-Tag wird vor </body> eingefügt", () => {
+    const html = "<html><body><div id=root></div></body></html>";
+    const out = injectSchema(html, SCHEMA);
+    expect(out).toContain(TAG);
+    expect(out.indexOf(TAG)).toBeLessThan(out.indexOf("</body>"));
+  });
+
+  test("HTML ohne </body>: Schema-Tag wird angehängt (defensiver Fallback)", () => {
+    const html = "<div>fragment</div>";
+    const out = injectSchema(html, SCHEMA);
+    expect(out.endsWith(TAG)).toBe(true);
+  });
+
+  test("Idempotent: bei bereits injectem Schema kein zweiter Tag", () => {
+    const html = `<html><body>${TAG}</body></html>`;
+    const out = injectSchema(html, '{"features":[{"differentSchema":true}]}');
+    // Original-Tag bleibt, kein zweiter Tag hinzugefügt — der Marker-
+    // Check verhindert sonst stacking-Tags bei repeated reads.
+    expect(out).toBe(html);
+  });
+
+  test("Schema mit Komplex-Daten (entities + screens) bleibt valides JS", () => {
+    const complex = JSON.stringify({
+      features: [
+        {
+          featureName: "items",
+          entities: { item: { fields: { title: { type: "text" } } } },
+          screens: [{ id: "list", type: "entityList", entity: "item", columns: ["title"] }],
+        },
+      ],
+    });
+    const html = '<html><body><script src="/client.js"></script></body></html>';
+    const out = injectSchema(html, complex);
+    // Sanity: das injected Skript muss valid JS sein (Object-Literal-
+    // Syntax, keine HTML-Reserved-Chars im JSON die den <script>-Block
+    // brechen würden — JSON.stringify entkommt /, < usw. nicht, aber
+    // die Standard-Chars die wir hier nutzen sind unkritisch).
+    expect(out).toContain(`window.__KUMIKO_SCHEMA__=${complex}`);
+  });
+});

package/src/__tests__/pii-boot-gate.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { assertPiiBootInvariants } from "../pii-boot-gate";
+
+const piiFeature = defineFeature("gate-pii", (r) => {
+  r.entity(
+    "person",
+    createEntity({
+      table: "read_gate_persons",
+      fields: { email: createTextField({ required: true, pii: true, lookupable: true }) },
+    }),
+  );
+});
+const plainFeature = defineFeature("gate-plain", (r) => {
+  r.entity(
+    "thing",
+    createEntity({ table: "read_gate_things", fields: { name: createTextField() } }),
+  );
+});
+
+const kms = new InMemoryKmsAdapter();
+const KEY = Buffer.alloc(32, 7).toString("base64");
+
+describe("assertPiiBootInvariants — prod", () => {
+  test("PII without a KMS aborts boot", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "prod" })).toThrow(
+      /BOOT ABORTED.*PLAINTEXT.*allowPlaintextPii/s,
+    );
+  });
+
+  test("explicit allowPlaintextPii downgrades to a warning", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiFeature], {
+        mode: "prod",
+        allowPlaintextPii: "kms rollout pending, infra#188",
+      }),
+    ).not.toThrow();
+  });
+
+  test("KMS + blindIndexKey boots", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiFeature], { mode: "prod", kms, blindIndexKey: KEY }),
+    ).not.toThrow();
+  });
+
+  test("KMS without blindIndexKey aborts when lookupable fields exist", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "prod", kms })).toThrow(
+      /blindIndexKey/,
+    );
+  });
+
+  test("no PII entities → nothing to gate", () => {
+    expect(() => assertPiiBootInvariants([plainFeature], { mode: "prod" })).not.toThrow();
+  });
+});
+
+describe("assertPiiBootInvariants — dev", () => {
+  test("PII without a KMS only warns in dev", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "dev" })).not.toThrow();
+  });
+
+  test("KMS without blindIndexKey aborts in dev too (lookups broken in any mode)", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "dev", kms })).toThrow(
+      /blindIndexKey/,
+    );
+  });
+});

package/src/__tests__/renderer-web-css-relocation.integration.test.ts

@@ -0,0 +1,85 @@
+// Relocation-Test für den @source-Layout-Fix (#359).
+//
+// Der Bug: renderer-web/src/styles.css scannte seine eigenen Shell-Klassen
+// über einen MONOREPO-relativen @source (`../../renderer-web/src`). Im
+// Workspace löst der via Symlink auf (grün), in einem Standalone-Consumer
+// (echtes node_modules ohne Monorepo-Geschwister) findet er nichts → unstyled
+// prod (15KB statt 48KB). Der Fix macht die Zeile self-relativ (`./`), weil
+// das Paket `src` shippt.
+//
+// Am REALEN Ort der styles.css sind `./` und `../../renderer-web/src`
+// identisch — ein Test dort wäre grün mit Bug UND Fix. Der Diskriminator ist
+// RELOCATION: wir kopieren die echte styles.css an einen Ort, an dem der alte
+// Pfad tot ist und nur `./` greift. Der Ort liegt unter dem Repo-Root, damit
+// `@import "tailwindcss"` / `react-day-picker` weiter über node_modules
+// auflösen. Braucht Bun (Bun.spawn im Tailwind-One-Shot) — sonst silent skip.
+
+import { describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runTailwindOnce } from "../build-prod-bundle";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "../../../..");
+const RENDERER_WEB_STYLES = resolve(__dirname, "../../../renderer-web/src/styles.css");
+const SELF_SOURCE = '@source "./**/*.{ts,tsx}";';
+const MONOREPO_SOURCE = '@source "../../renderer-web/src/**/*.{ts,tsx}";';
+
+function bunAvailable(): boolean {
+  try {
+    execFileSync("bun", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("renderer-web styles.css @source relocation (#359)", () => {
+  // skipIf statt `if (!bunAvailable()) return;` — sonst meldet der Runner den
+  // Test grün, obwohl er nie lief (silent-pass verschleiert fehlende Coverage).
+  test.skipIf(!bunAvailable())(
+    "self-relative @source scans the shell standalone; monorepo path would not",
+    async () => {
+      // Tailwind v4 auto-scannt nur das cwd-Verzeichnis (empirisch bestätigt:
+      // das Verzeichnis der Input-CSS wird NICHT automatisch gescannt). Im echten
+      // Standalone-Consumer ist renderer-web zudem in node_modules (gitignored) →
+      // ebenfalls nicht auto-gescannt. Die Shell-Klassen erreicht also NUR der
+      // explizite @source der styles.css. Hier mirrorn wir das robust, ohne
+      // gitignore-/node_modules-Semantik: das Paket-`src` (mit der Shell-Probe)
+      // liegt AUSSERHALB des Build-cwd — nur der self-relative `@source "./**"`
+      // der relozierten styles.css erreicht es, der monorepo-Pfad ist tot.
+      // Temp unter REPO_ROOT, damit @import "tailwindcss"/react-day-picker via
+      // node_modules auflösen.
+      const dir = await mkdtemp(join(REPO_ROOT, ".reloc-rendererweb-"));
+      const buildCwd = join(dir, "app");
+      const pkgSrc = join(dir, "pkg");
+      try {
+        const realCss = await readFile(RENDERER_WEB_STYLES, "utf8");
+        // Guard: der Fix MUSS in der Quelle stehen, sonst testet die Relocation nichts.
+        expect(realCss).toContain(SELF_SOURCE);
+
+        await mkdir(buildCwd, { recursive: true });
+        await mkdir(join(pkgSrc, "layout"), { recursive: true });
+        await writeFile(
+          join(pkgSrc, "layout/probe.tsx"),
+          `export const P = () => <div className="min-h-screen" />;\n`,
+        );
+
+        await writeFile(join(pkgSrc, "styles.css"), realCss);
+        const fixed = await runTailwindOnce(join(pkgSrc, "styles.css"), buildCwd);
+        expect(fixed).toContain("min-h-screen");
+
+        // Diskriminator: mit dem ALTEN monorepo-relativen @source ist die Probe
+        // an diesem relozierten Ort unerreichbar → Sentinel fehlt. Beweist, dass
+        // der Fix kein No-op ist (der Test würde bei einem Revert rot).
+        await writeFile(join(pkgSrc, "styles.css"), realCss.replace(SELF_SOURCE, MONOREPO_SOURCE));
+        const buggy = await runTailwindOnce(join(pkgSrc, "styles.css"), buildCwd);
+        expect(buggy).not.toContain("min-h-screen");
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    },
+  );
+});

package/src/__tests__/renderer-web-shell-sentinel.test.ts

@@ -0,0 +1,35 @@
+// Unit-Test für den CSS-Completeness-Guard (#359): nach dem Tailwind-One-Shot
+// prüft der Build, ob das Output-CSS die renderer-web-Shell-Sentinel-Klasse
+// enthält — aber NUR wenn auf das gepackte renderer-web-styles.css
+// zurückgefallen wurde. Fehlt sie dort, würde prod unstyled rendern → laut
+// failen mit Hinweis auf src/styles.css.
+
+import { describe, expect, test } from "bun:test";
+import { assertRendererWebShellPresent } from "../build-prod-bundle";
+
+const fallback = {
+  path: "/app/node_modules/renderer-web/src/styles.css",
+  isRendererWebFallback: true,
+};
+const appOwned = { path: "/app/src/styles.css", isRendererWebFallback: false };
+
+describe("assertRendererWebShellPresent (#359 CSS-completeness guard)", () => {
+  test("fallback + fehlende Shell-Sentinel-Klasse → wirft mit src/styles.css-Hinweis", () => {
+    expect(() => assertRendererWebShellPresent(".some-other{display:flex}", fallback)).toThrow(
+      /min-h-screen/,
+    );
+    expect(() => assertRendererWebShellPresent(".some-other{display:flex}", fallback)).toThrow(
+      /src\/styles\.css/,
+    );
+  });
+
+  test("fallback + Shell-Sentinel vorhanden → kein Throw", () => {
+    expect(() =>
+      assertRendererWebShellPresent(".min-h-screen{min-height:100vh}", fallback),
+    ).not.toThrow();
+  });
+
+  test("app-eigenes styles.css (kein Fallback) → nie asserten, auch ohne Sentinel", () => {
+    expect(() => assertRendererWebShellPresent("", appOwned)).not.toThrow();
+  });
+});

package/src/__tests__/require-env.test.ts

@@ -0,0 +1,29 @@
+// requireEnv — the missing-var error message must match the actual caller.
+// Regression (728/2): the advice text was hardcoded to prod/container
+// wording ("Coolify secrets") regardless of the `context` param, so a
+// runDevApp caller got misleading production-deploy instructions for a
+// missing local .env var.
+
+import { describe, expect, test } from "bun:test";
+import { requireEnv } from "../run-prod-app";
+
+describe("requireEnv", () => {
+  test("default context (runProdApp) gives container/production advice", () => {
+    expect(() => requireEnv("MISSING_VAR", {})).toThrow(/container env.*Coolify secrets/);
+  });
+
+  test("runDevApp context gives local .env advice, not production advice", () => {
+    expect(() => requireEnv("MISSING_VAR", {}, "runDevApp")).toThrow(
+      /\.env \/ shell before running the dev server/,
+    );
+  });
+
+  test("runDevApp context error does NOT mention Coolify", () => {
+    try {
+      requireEnv("MISSING_VAR", {}, "runDevApp");
+      throw new Error("expected requireEnv to throw");
+    } catch (err) {
+      expect(String(err)).not.toContain("Coolify");
+    }
+  });
+});

package/src/__tests__/resolve-auth-mail.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { type RunProdAppAuthOptions, resolveAuthMail } from "../run-prod-app";
+
+// Pins the auth.mail convenience (resolveAuthMail): one mail block expands
+// into the four explicit flow setups built from DEFAULT_AUTH_PATHS, the
+// null-transport guard (no SMTP_HOST → flows stay unwired), and explicit
+// per-flow setups winning over the mail default.
+
+const admin: RunProdAppAuthOptions["admin"] = {
+  email: "admin@example.com",
+  password: "pw-long-enough",
+  displayName: "Admin",
+  memberships: [],
+};
+
+const withMail: RunProdAppAuthOptions = {
+  admin,
+  mail: { baseUrl: "https://app.example.com", appName: "Test" },
+};
+
+describe("resolveAuthMail", () => {
+  test("no mail block → auth returned unchanged", () => {
+    const noMail: RunProdAppAuthOptions = { admin };
+    const out = resolveAuthMail(noMail, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset).toBeUndefined();
+    expect(out.signup).toBeUndefined();
+  });
+
+  test("mail + SMTP_HOST → all four flows wired from DEFAULT_AUTH_PATHS", () => {
+    const out = resolveAuthMail(withMail, "secret", { SMTP_HOST: "localhost" });
+    // All four flows carry appUrl as feature options — each handler mails via
+    // delivery (ctx.notify); no callback wiring remains.
+    expect(out.passwordReset?.appUrl).toBe("https://app.example.com/reset-password");
+    expect(out.emailVerification?.appUrl).toBe("https://app.example.com/verify-email");
+    expect(out.signup?.appUrl).toBe("https://app.example.com/signup/complete");
+    expect(out.invite?.appUrl).toBe("https://app.example.com/invite/accept");
+    expect(out.passwordReset?.hmacSecret).toBe("secret");
+  });
+
+  test("mail but NO SMTP_HOST → null-transport guard, flows stay unwired", () => {
+    const out = resolveAuthMail(withMail, "secret", {});
+    expect(out.passwordReset).toBeUndefined();
+    expect(out.signup).toBeUndefined();
+  });
+
+  test("explicit per-flow setup wins over the mail default", () => {
+    const explicit: RunProdAppAuthOptions = {
+      ...withMail,
+      passwordReset: {
+        hmacSecret: "h",
+        appUrl: "https://custom.example.com/pw",
+      },
+    };
+    const out = resolveAuthMail(explicit, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset?.appUrl).toBe("https://custom.example.com/pw");
+    // other flows still come from the mail default
+    expect(out.signup?.appUrl).toBe("https://app.example.com/signup/complete");
+  });
+
+  test("paths override only affects the named path", () => {
+    const pathsOverride: RunProdAppAuthOptions = {
+      admin,
+      mail: { baseUrl: "https://app.example.com", paths: { resetPassword: "/pw" } },
+    };
+    const out = resolveAuthMail(pathsOverride, "secret", { SMTP_HOST: "localhost" });
+    expect(out.passwordReset?.appUrl).toBe("https://app.example.com/pw");
+    expect(out.emailVerification?.appUrl).toBe("https://app.example.com/verify-email");
+  });
+});