@cosmicdrift/kumiko-testing 0.297.0 → 0.304.0

package/README.md

@@ -47,3 +47,31 @@ test("member sees the note", async ({ seedTenant, page }) => {
 - App roles: `createE2eSeedRoutes({ extraRoles: ["TenantMember"] })` lets `tenant.addUser(["TenantMember"])` seed them;
   `SystemAdmin` is never seedable and makes the route builder throw.
 - A `SeedPart` receives `{ tenant }` and works against the in-process `seedTenant` and the HTTP tenant alike.
+- Already have a custom server entry (mail transport, KMS, boot seeds, ...) that also runs in prod?
+  Point `serverEntry` at it instead of duplicating `e2e/server.ts`, and mount the seed routes only
+  when the seed condition holds: `...(isE2eSeedingEnabled() ? createE2eSeedRoutes() : [])` in its own
+  `extraRoutes` — prod then never registers the routes at all, not just a per-request 404.
+  `isE2eSeedingEnabled` is exported from `@cosmicdrift/kumiko-testing/e2e/seed-route`.
+- App-wide defaults for tests (e.g. a completed onboarding) belong in a `SeedPart` passed to
+  `seedTenant({ with: [defaults] })` — never in a `postSave` hook on the `"tenant"` entity, since that
+  hook also fires on every real signup in prod.
+
+## Screenshots (`./e2e`)
+
+`runScreenshots`/`runMatrix` register their tests on the same `test` as above, so a scenario's `flow`
+receives the seeded-tenant fixture too:
+
+```ts
+{ name: "dispatch", flow: async (page, { seedTenant }) => {
+    const tenant = await seedTenant({ users: 1 });
+    await tenant.loginAs(page, tenant.members[0]!);
+    await page.goto("/dispatch");
+  },
+  beforeCapture: async (page) => page.addStyleTag({ content: ".live-clock { visibility: hidden }" }),
+}
+```
+
+`beforeCapture?: (page) => Promise<void>` runs after the viewport is set and the page has settled,
+right before the screenshot. `runMatrix` calls it once per theme × viewport for the same scenario, so
+it must be idempotent — hide or mask an element rather than a one-shot action like clicking a button,
+which would only succeed on the first capture and time out on every one after.

package/bin/__tests__/kumiko-testing-bunfig.test.ts

@@ -0,0 +1,76 @@
+// kumiko-framework#3120: `kumiko-testing bunfig` used to overwrite an
+// existing bunfig.toml unconditionally, silently dropping app-owned sections
+// (e.g. `[install.scopes]` with a private-registry token) and unmanaged keys
+// (e.g. `concurrency`) alike. Foreign sections now merge back in verbatim;
+// only an unmanaged key inside a *managed* section still blocks the write.
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLI_PATH = join(import.meta.dir, "..", "kumiko-testing.ts");
+
+async function runCli(args: string[], cwd: string) {
+  const proc = Bun.spawn(["bun", CLI_PATH, ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+}
+
+describe("kumiko-testing bunfig — existing file with a foreign section", () => {
+  test("merges [install.scopes] back in instead of dropping it", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "kumiko-testing-bunfig-"));
+    try {
+      const existing =
+        '[install.scopes]\n"@cosmicdriftgamestudio" = { token = "$GITHUB_TOKEN" }\n\n[test]\npreload = []\n';
+      writeFileSync(join(dir, "bunfig.toml"), existing);
+
+      const { exitCode } = await runCli(["bunfig"], dir);
+
+      expect(exitCode).toBe(0);
+      const written = readFileSync(join(dir, "bunfig.toml"), "utf-8");
+      expect(written).toContain("Generated by kumiko-testing");
+      expect(written).toContain(
+        '[install.scopes]\n"@cosmicdriftgamestudio" = { token = "$GITHUB_TOKEN" }',
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("aborts and names an unmanaged key inside [test], leaves the file untouched", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "kumiko-testing-bunfig-"));
+    try {
+      const existing = "[test]\nconcurrency = 8\npreload = []\n";
+      writeFileSync(join(dir, "bunfig.toml"), existing);
+
+      const { exitCode, stderr } = await runCli(["bunfig"], dir);
+
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain("test.concurrency");
+      expect(readFileSync(join(dir, "bunfig.toml"), "utf-8")).toBe(existing);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("regenerates a file with no foreign sections and no unmanaged keys", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "kumiko-testing-bunfig-"));
+    try {
+      writeFileSync(join(dir, "bunfig.toml"), "[test]\npreload = []\n");
+
+      const { exitCode } = await runCli(["bunfig"], dir);
+
+      expect(exitCode).toBe(0);
+      expect(readFileSync(join(dir, "bunfig.toml"), "utf-8")).toContain(
+        "Generated by kumiko-testing",
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/bin/kumiko-testing.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 // biome-ignore-all lint/suspicious/noConsole: CLI script, console is the interface.
 
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { Glob } from "bun";
-import { BUNFIG_FILES, renderBunfigFiles } from "../src/bunfig";
+import { BUNFIG_FILES, mergeBunfig, renderBunfigFiles } from "../src/bunfig";
 import { buildIntegrationTestArgs, selectIntegrationFiles } from "../src/integration-runner";
 
 const USAGE = `kumiko-testing <command>
@@ -31,11 +31,25 @@ function runBunfig(args: readonly string[]): number {
     coverage: values.coverage === true,
     ...(values.hoisted === true && { install: { linker: "hoisted" } }),
   });
+  let blocked = false;
   for (const [name, content] of Object.entries(files)) {
-    writeFileSync(name, content);
+    let toWrite = content;
+    if (existsSync(name)) {
+      const merged = mergeBunfig(content, readFileSync(name, "utf-8"));
+      if (!merged.ok) {
+        const keys = merged.unknownKeys.map((k) => `${k.section}.${k.key}`).join(", ");
+        console.error(
+          `${name} has key(s) kumiko-testing does not manage: ${keys}. Regenerating would drop them silently — remove them from ${name} or move them out of [install]/[test], then rerun.`,
+        );
+        blocked = true;
+        continue;
+      }
+      toWrite = merged.content;
+    }
+    writeFileSync(name, toWrite);
     console.log(`wrote ${name}`);
   }
-  return 0;
+  return blocked ? 1 : 0;
 }
 
 async function runIntegration(args: readonly string[]): Promise<number> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.297.0",
+  "version": "0.304.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,9 +63,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.297.0",
-    "@cosmicdrift/kumiko-dev-server": "0.297.0",
-    "@cosmicdrift/kumiko-framework": "0.297.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.304.0",
+    "@cosmicdrift/kumiko-dev-server": "0.304.0",
+    "@cosmicdrift/kumiko-framework": "0.304.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/bunfig.ts

@@ -83,6 +83,81 @@ export function renderBunfig(variant: BunfigVariant, opts: BunfigOptions = {}):
   return `${lines.join("\n")}\n`;
 }
 
+type BunfigBlock = { readonly header: string; readonly lines: readonly string[] };
+
+// Splits on un-indented `[header]` lines only — real bunfig files never
+// indent a table header, and TOML array/inline-table values that happen to
+// contain "[" are never alone on their own line. Anything before the first
+// header (top-level keys like `preload`/`telemetry`/`smol`/`logLevel`, plus
+// the header comments) is its own block under the synthetic header "" —
+// dropping it silently lost those keys (kumiko-framework#3120).
+function splitBunfigBlocks(content: string): readonly BunfigBlock[] {
+  const blocks: { header: string; lines: string[] }[] = [];
+  let current: { header: string; lines: string[] } = { header: "", lines: [] };
+  for (const line of content.split("\n")) {
+    const match = /^\[([^\]]+)\]\s*$/.exec(line);
+    if (match?.[1] !== undefined) {
+      blocks.push(current);
+      current = { header: match[1], lines: [] };
+      continue;
+    }
+    current.lines.push(line);
+  }
+  blocks.push(current);
+  return blocks;
+}
+
+function keysIn(lines: readonly string[]): readonly string[] {
+  const keys: string[] = [];
+  for (const line of lines) {
+    const match = /^([A-Za-z_][\w-]*)\s*=/.exec(line.trim());
+    if (match?.[1] !== undefined) keys.push(match[1]);
+  }
+  return keys;
+}
+
+export type UnknownBunfigKey = { readonly section: string; readonly key: string };
+
+export type BunfigMergeResult =
+  | { readonly ok: true; readonly content: string }
+  | { readonly ok: false; readonly unknownKeys: readonly UnknownBunfigKey[] };
+
+/**
+ * Merges freshly generated bunfig content with whatever an app already has
+ * on disk. A section this run's `generated` output doesn't touch at all
+ * (e.g. `[install]` when `--install` wasn't passed, or `[install.scopes]`
+ * for a private-registry token, which renderBunfig never emits) is kept
+ * verbatim, appended after the generated content — so a section the
+ * template doesn't own this run is never silently dropped. A key inside a
+ * section the template DOES emit that isn't in this run's own version of
+ * that section (e.g. `concurrency`, `timeout`, kumiko-framework#3120) fails
+ * the merge instead of silently disappearing.
+ */
+export function mergeBunfig(generated: string, existingContent: string): BunfigMergeResult {
+  const generatedKeysBySection = new Map(
+    splitBunfigBlocks(generated).map((block) => [block.header, new Set(keysIn(block.lines))]),
+  );
+  const blocks = splitBunfigBlocks(existingContent);
+  const unknownKeys: UnknownBunfigKey[] = [];
+  const foreignBlocks: BunfigBlock[] = [];
+  for (const block of blocks) {
+    const allowed = generatedKeysBySection.get(block.header);
+    if (allowed === undefined) {
+      foreignBlocks.push(block);
+      continue;
+    }
+    for (const key of keysIn(block.lines)) {
+      if (!allowed.has(key)) unknownKeys.push({ section: block.header, key });
+    }
+  }
+  if (unknownKeys.length > 0) return { ok: false, unknownKeys };
+  if (foreignBlocks.length === 0) return { ok: true, content: generated };
+  const foreignText = foreignBlocks
+    .map((block) => `[${block.header}]\n${block.lines.join("\n").replace(/\n+$/, "")}\n`)
+    .join("\n");
+  return { ok: true, content: `${generated}\n${foreignText}` };
+}
+
 export function renderBunfigFiles(opts: BunfigOptions = {}): Readonly<Record<string, string>> {
   const { dom, ...shared } = opts;
   return {

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.304.0",
+    "type": "improvement",
+    "title": "Screenshot scenarios get { seedTenant } in flow and a beforeCapture hook; the README no longer recommends a postSave hook on tenant for test defaults",
+    "detail": "`runScreenshots`/`runMatrix` register their tests on the same `test` as `@cosmicdrift/kumiko-testing/e2e`'s seeded-tenant fixture, so `Scenario.flow` now receives `(page, { seedTenant })` — existing single-parameter `flow(page)` scenarios keep working unchanged. `Scenario.beforeCapture?: (page) => Promise<void>` runs after the viewport is set and the page has settled, right before each screenshot. `seedTenant()`'s \"no baseURL\" error now only fires when a scenario actually calls it, not for every screenshot spec's fixture setup."
+  },
+  {
+    "version": "0.299.0",
+    "type": "fix",
+    "title": "kumiko-testing bunfig merges app-owned sections (e.g. install.scopes) back in and only aborts, naming the key, when a managed [install]/[test] section has a key the template doesn't emit; e2e seed routes gain an isE2eSeedingEnabled() export so a custom server entry can skip mounting them in prod",
+    "migration": "If `kumiko-testing bunfig` exits 1 naming a section.key (e.g. test.concurrency), remove or rename that key, or move it out of [install]/[test], then rerun. If your server entry mounts createE2eSeedRoutes() directly instead of using e2e/server.ts, guard the mount with isE2eSeedingEnabled() so prod never registers the seed routes."
+  },
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "createE2eSeedRoutes() returns ExtraRouteDefinition[] instead of an extraRoutes callback",
+    "migration": "createE2eSeedRoutes() now returns readonly ExtraRouteDefinition[] instead of an (app, deps) => void callback. The call site extraRoutes: createE2eSeedRoutes() in setupTestStack is unchanged, but any code that imported createE2eSeedRoutes() to invoke it directly against app (rather than passing it through extraRoutes) must instead treat the result as a route list, e.g. register each entry through the framework's ExtraRouteDefinition handling."
+  },
   {
     "version": "0.295.0",
     "type": "improvement",

package/src/e2e/define-app-e2e-config.ts

@@ -76,7 +76,7 @@ function assertTemplateOwnedKeysUnset(project: E2eProject): void {
   ];
   if (offending.length > 0) {
     throw new Error(
-      `defineAppE2eConfig: project "${name}" sets ${offending.join(", ")}; timeouts, retries and workers belong to the template. Diagnose per docs/guides/test-failures.md instead of raising them.`,
+      `defineAppE2eConfig: project "${name}" sets ${offending.join(", ")}; timeouts, retries and workers belong to the template. Diagnose per https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/test-failures.md instead of raising them.`,
     );
   }
 }

package/src/e2e/index.ts

@@ -51,6 +51,7 @@ export type { CapturedMail } from "./seed-contract";
 export {
   type E2eSeededTenant,
   type E2eSeedTenantOptions,
+  type SeedTenantFixture,
   test,
 } from "./seeded-tenant-fixture";
 export { E2E_TIMEOUT_MS } from "./timeouts";

package/src/e2e/screenshots.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
-import { expect, type Page, type Request, test } from "@playwright/test";
+import { expect, type Page, type Request } from "@playwright/test";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir } from "./screenshot-dir";
+import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
 
 // runScreenshots: one image per scenario → $SCREENSHOT_DIR/<name>.png.
 // runMatrix: every scenario × locale × theme × viewport in ONE run →
@@ -30,10 +31,16 @@ export interface Scenario {
   readonly name: string;
   readonly description?: string;
   readonly url?: string;
-  readonly flow?: (page: Page) => Promise<void>;
+  readonly flow?: (page: Page, fixtures: { seedTenant: SeedTenantFixture }) => Promise<void>;
   readonly waitFor?: string;
   readonly fullPage?: boolean;
   readonly viewport?: { readonly width: number; readonly height: number };
+  // Runs after the viewport is set and the page has settled, right before the
+  // screenshot. runMatrix calls this once per theme × viewport combination for
+  // the scenario — it must be idempotent (e.g. hide/mask an element) rather
+  // than a one-shot action like clicking a dismiss button, which would only
+  // succeed on the first capture and time out on every one after.
+  readonly beforeCapture?: (page: Page) => Promise<void>;
   // runMatrix only: opt out of the identical-theme-screenshot check for
   // scenarios that legitimately render the same pixels across themes — e.g.
   // a plain server-rendered content page with no client-side theme wiring.
@@ -93,8 +100,9 @@ async function openScenario(
   page: Page,
   s: Scenario,
   inFlightDataRequests: () => number,
+  fixtures: { seedTenant: SeedTenantFixture },
 ): Promise<void> {
-  if (s.flow) await s.flow(page);
+  if (s.flow) await s.flow(page, fixtures);
   else if (s.url) await page.goto(s.url);
   else throw new Error(`Scenario "${s.name}" needs either url or flow`);
 
@@ -140,15 +148,19 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
     // unreachable from Playwright (context.locale and --lang both no-op there). #1851
     if (opts.pinLocale) test.use({ locale: "en-US" });
     for (const s of scenarios) {
-      test(s.description ? `${s.name} — ${s.description}` : s.name, async ({ page }) => {
-        if (opts.pinLocale) await pinEnglishLocale(page);
-        const inFlightDataRequests = countInFlightDataRequests(page);
-        if (s.viewport) await page.setViewportSize(s.viewport);
-        await openScenario(page, s, inFlightDataRequests);
-        const path = `${outDir}/${s.name}.png`;
-        await page.screenshot({ path, fullPage: s.fullPage ?? false });
-        expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
-      });
+      test(
+        s.description ? `${s.name} — ${s.description}` : s.name,
+        async ({ page, seedTenant }) => {
+          if (opts.pinLocale) await pinEnglishLocale(page);
+          const inFlightDataRequests = countInFlightDataRequests(page);
+          if (s.viewport) await page.setViewportSize(s.viewport);
+          await openScenario(page, s, inFlightDataRequests, { seedTenant });
+          if (s.beforeCapture) await s.beforeCapture(page);
+          const path = `${outDir}/${s.name}.png`;
+          await page.screenshot({ path, fullPage: s.fullPage ?? false });
+          expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
+        },
+      );
     }
   });
 }
@@ -260,7 +272,7 @@ export function runMatrix<T extends string>(
 
       for (const s of scenarios) {
         if (only !== undefined && only !== s.name) continue;
-        test(s.name, async ({ page }) => {
+        test(s.name, async ({ page, seedTenant }) => {
           // kumiko:locale drives the boot-time language (before goto); kumiko:theme
           // is cleared so the mode is decided solely by applyTheme.
           await page.addInitScript((lng) => {
@@ -268,7 +280,7 @@ export function runMatrix<T extends string>(
             localStorage.removeItem("kumiko:theme");
           }, locale);
           const inFlightDataRequests = countInFlightDataRequests(page);
-          await openScenario(page, s, inFlightDataRequests);
+          await openScenario(page, s, inFlightDataRequests, { seedTenant });
 
           const digests: ThemeScreenshotDigest<T>[] = [];
 
@@ -277,6 +289,7 @@ export function runMatrix<T extends string>(
             for (const vp of viewports) {
               await page.setViewportSize(VIEWPORTS[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
+              if (s.beforeCapture) await s.beforeCapture(page);
               const dir = `${baseDir}/${s.name}/${locale}/${theme}`;
               mkdirSync(dir, { recursive: true });
               const path = `${dir}/${vp}.png`;

package/src/e2e/seed-route.ts

@@ -3,9 +3,13 @@ import {
   getInbox,
   mailTransportInMemoryFeature,
 } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
-import { tenantTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import type { CreateKumikoServerOptions } from "@cosmicdrift/kumiko-dev-server";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import {
+  type ExtraRouteDefinition,
+  ExtraRouteRejection,
+  type SignatureExtraRouteVerifyRequest,
+  signatureRoute,
+} from "@cosmicdrift/kumiko-framework/api";
 import type { z } from "zod";
 import {
   persistTenantRows,
@@ -13,21 +17,13 @@ import {
   type SeedWriter,
   unwrapSavedRow,
 } from "../seed-tenant";
-import {
-  SEED_ENABLE_ENV,
-  SEED_ROUTE_PREFIX,
-  SEED_ROUTES,
-  SEED_TOKEN_ENV,
-  SEED_TOKEN_HEADER,
-} from "./constants";
+import { SEED_ENABLE_ENV, SEED_ROUTES, SEED_TOKEN_ENV, SEED_TOKEN_HEADER } from "./constants";
 import {
   createSeedUserRequestSchema,
   inboxQuerySchema,
   seedTenantRequestSchema,
 } from "./seed-contract";
 
-type ExtraRoutes = NonNullable<CreateKumikoServerOptions["extraRoutes"]>;
-
 type ParsedBody<T> =
   | { readonly success: true; readonly data: T }
   | { readonly success: false; readonly error: string };
@@ -50,7 +46,18 @@ function parseJsonBody<S extends z.ZodType>(schema: S, raw: string): ParsedBody<
   }
 }
 
-function seedingEnabled(): boolean {
+// Shared by every verify() below — a failed parse becomes a 400 the same way
+// the pre-#3050 handler-level parseJsonBody/parseWith checks did.
+function parseOrReject<T>(value: ParsedBody<T>): T {
+  if (value.success) return value.data;
+  throw new ExtraRouteRejection(400, { error: value.error });
+}
+
+// Exported so a server entry that already mounts its own extraRoutes (instead
+// of duplicating e2e/server.ts) can gate the *registration* itself — prod
+// then never carries the seed routes at all, rather than relying solely on
+// each route's own per-request assertGateOpen() check.
+export function isE2eSeedingEnabled(): boolean {
   return process.env[SEED_ENABLE_ENV] === "1" && process.env["NODE_ENV"] !== "production";
 }
 
@@ -62,74 +69,118 @@ function tokenMatches(expected: string, provided: string | undefined): boolean {
   return provided !== undefined && timingSafeEqual(digest(expected), digest(provided));
 }
 
+// Runs first in every verify() below — replaces the old `app.use(prefix/*)`
+// guard middleware now that entry:"signature" owns its own access control.
+function assertGateOpen(request: SignatureExtraRouteVerifyRequest): void {
+  // ExtraRouteRejection(status, body) always renders via c.json(body, status)
+  // (buildExtraRouteHonoHandler) — the plain-text "Not Found" from the old
+  // middleware becomes a JSON body; no test asserts the 404 body shape.
+  if (!isE2eSeedingEnabled()) throw new ExtraRouteRejection(404, { error: "Not Found" });
+  const expected = process.env[SEED_TOKEN_ENV];
+  if (expected === undefined || expected === "") {
+    throw new ExtraRouteRejection(500, {
+      error: `${SEED_TOKEN_ENV} is not set; refusing to serve seed routes`,
+    });
+  }
+  if (!tokenMatches(expected, request.headers[SEED_TOKEN_HEADER])) {
+    throw new ExtraRouteRejection(401, { error: "invalid seed token" });
+  }
+}
+
 export type E2eSeedRoutesOptions = {
   readonly extraRoles?: readonly string[];
 };
 
-export function createE2eSeedRoutes(options: E2eSeedRoutesOptions = {}): ExtraRoutes {
+// Builds the route definitions unconditionally (extraRoles validation must
+// still throw in every environment) — the *mounting* decision is the
+// caller's: use isE2eSeedingEnabled() to keep prod from ever registering
+// these route objects at all, e.g. `...(isE2eSeedingEnabled() ?
+// createE2eSeedRoutes() : [])` in a server entry that also runs in prod
+// (kumiko-framework#3120). Each route's own assertGateOpen() 404s outside
+// the seed condition regardless — this is belt-and-suspenders, not the only gate.
+export function createE2eSeedRoutes(
+  options: E2eSeedRoutesOptions = {},
+): readonly ExtraRouteDefinition[] {
   const seedUserRequestSchema = createSeedUserRequestSchema(options.extraRoles);
-  return (app, deps) => {
-    const write: SeedWriter = async (handlerQn, payload, tenantId) =>
-      unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
 
-    app.use(`${SEED_ROUTE_PREFIX}/*`, async (c, next) => {
-      // c.notFound() would let the dev server answer unmatched GETs with its HTML shell (200).
-      if (!seedingEnabled()) return c.text("Not Found", 404);
-      const expected = process.env[SEED_TOKEN_ENV];
-      if (expected === undefined || expected === "") {
-        return c.json(
-          { error: `${SEED_TOKEN_ENV} is not set; refusing to serve seed routes` },
-          500,
-        );
-      }
-      if (!tokenMatches(expected, c.req.header(SEED_TOKEN_HEADER))) {
-        return c.json({ error: "invalid seed token" }, 401);
-      }
-      await next();
-    });
-
-    app.post(SEED_ROUTES.seedTenant, async (c) => {
-      const body = parseJsonBody(seedTenantRequestSchema, await c.req.text());
-      if (!body.success) return c.json({ error: body.error }, 400);
+  const seedTenantRoute = signatureRoute<z.infer<typeof seedTenantRequestSchema>>({
+    method: "POST",
+    path: SEED_ROUTES.seedTenant,
+    entry: "signature",
+    verify: async (request) => {
+      assertGateOpen(request);
+      return parseOrReject(parseJsonBody(seedTenantRequestSchema, request.rawBody));
+    },
+    handler: async (c, verified, deps) => {
+      const write: SeedWriter = async (handlerQn, payload, tenantId) =>
+        unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
       try {
         return c.json(
-          await persistTenantRows(write, { name: body.data.name, users: body.data.members }),
+          await persistTenantRows(write, { name: verified.name, users: verified.members }),
         );
       } catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
       }
-    });
+    },
+  });
 
-    app.post(SEED_ROUTES.seedUser, async (c) => {
-      const body = parseJsonBody(seedUserRequestSchema, await c.req.text());
-      if (!body.success) return c.json({ error: body.error }, 400);
-      if ((await fetchOne(deps.db, tenantTable, { id: body.data.tenantId })) === undefined) {
-        return c.json({ error: `unknown tenant ${body.data.tenantId}` }, 404);
+  const seedUserRoute = signatureRoute<z.infer<typeof seedUserRequestSchema>>({
+    method: "POST",
+    path: SEED_ROUTES.seedUser,
+    entry: "signature",
+    verify: async (request) => {
+      assertGateOpen(request);
+      return parseOrReject(parseJsonBody(seedUserRequestSchema, request.rawBody));
+    },
+    handler: async (c, verified, deps) => {
+      // No raw db in signature-route deps (fw#3050) — tenant:query:me, run as
+      // a SystemAdmin scoped to verified.tenantId, is the existing
+      // fetchOne(tenantTable, {id: tenantId}) lookup, just behind the dispatcher.
+      const tenantRow = await deps.dispatchSystemQuery({
+        handlerQn: TenantQueries.me,
+        payload: {},
+        tenantId: verified.tenantId,
+      });
+      if (tenantRow === null) {
+        return c.json({ error: `unknown tenant ${verified.tenantId}` }, 404);
       }
+      const write: SeedWriter = async (handlerQn, payload, tenantId) =>
+        unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
       try {
-        return c.json(await persistUserRows(write, body.data.tenantId, body.data.roles));
+        return c.json(await persistUserRows(write, verified.tenantId, verified.roles));
       } catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);
       }
-    });
+    },
+  });
 
-    app.get(SEED_ROUTES.inbox, (c) => {
+  const inboxRoute = signatureRoute<z.infer<typeof inboxQuerySchema>>({
+    method: "GET",
+    path: SEED_ROUTES.inbox,
+    entry: "signature",
+    verify: async (request) => {
+      assertGateOpen(request);
+      return parseOrReject(
+        parseWith(inboxQuerySchema, {
+          tenantId: request.query["tenantId"],
+          to: request.query["to"],
+        }),
+      );
+    },
+    handler: async (c, verified, deps) => {
       if (!deps.registry.features.has(mailTransportInMemoryFeature.name)) {
         return c.json(
           { error: `${mailTransportInMemoryFeature.name} is not mounted; no inbox to read` },
           501,
         );
       }
-      const query = parseWith(inboxQuerySchema, {
-        tenantId: c.req.query("tenantId"),
-        to: c.req.query("to"),
-      });
-      if (!query.success) return c.json({ error: query.error }, 400);
-      const recipient = query.data.to.toLowerCase();
-      const messages = getInbox(query.data.tenantId).filter(
+      const recipient = verified.to.toLowerCase();
+      const messages = getInbox(verified.tenantId).filter(
         (message) => message.to.toLowerCase() === recipient,
       );
       return c.json({ messages });
-    });
-  };
+    },
+  });
+
+  return [seedTenantRoute, seedUserRoute, inboxRoute];
 }

package/src/e2e/seeded-tenant-fixture.ts

@@ -1,5 +1,12 @@
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import { type APIRequestContext, test as base, type Page } from "@playwright/test";
+import {
+  type APIRequestContext,
+  test as base,
+  type Page,
+  type PlaywrightTestArgs,
+  type PlaywrightTestOptions,
+  type PlaywrightWorkerArgs,
+} from "@playwright/test";
 import type { z } from "zod";
 import {
   type BoundApi,
@@ -24,10 +31,20 @@ export type E2eSeededTenant = SeededTenant & {
   readonly loginAs: (page: Page, user: SeededUser) => Promise<void>;
 };
 
+export type SeedTenantFixture = (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
+
 type E2eFixtures = {
-  seedTenant: (opts?: E2eSeedTenantOptions) => Promise<E2eSeededTenant>;
+  seedTenant: SeedTenantFixture;
 };
 
+// Narrowed to the four fixtures the body below actually reads, so a unit
+// test can drive it with plain stubs instead of a full Playwright run.
+export type ProvideSeedTenantDeps = Pick<
+  PlaywrightTestArgs & PlaywrightWorkerArgs,
+  "request" | "context" | "playwright"
+> &
+  Pick<PlaywrightTestOptions, "baseURL">;
+
 async function postSeedRoute<S extends z.ZodType>(
   request: APIRequestContext,
   path: string,
@@ -41,83 +58,90 @@ async function postSeedRoute<S extends z.ZodType>(
   return schema.parse(await response.json());
 }
 
-export const test = base.extend<E2eFixtures>({
-  seedTenant: async ({ request, context, playwright, baseURL }, use) => {
-    if (baseURL === undefined) throw new Error("seedTenant: the Playwright config has no baseURL");
-    const openedContexts: APIRequestContext[] = [];
-    const apiByUserId = new Map<string, BoundApi>();
-
-    // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
-    const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
-      const ctx = await playwright.request.newContext({ baseURL });
-      openedContexts.push(ctx);
-      await loginViaApi(ctx, user);
-      return createHttpApi(ctx);
-    };
+export async function provideSeedTenant(
+  { request, context, playwright, baseURL }: ProvideSeedTenantDeps,
+  use: (fixture: SeedTenantFixture) => Promise<void>,
+): Promise<void> {
+  const openedContexts: APIRequestContext[] = [];
+  const apiByUserId = new Map<string, BoundApi>();
 
-    const httpApiFor = (user: SeededUser): BoundApi => {
-      const cached = apiByUserId.get(user.id);
-      if (cached !== undefined) return cached;
-      let opened: Promise<BoundApi> | undefined;
-      const bound = (): Promise<BoundApi> => {
-        opened ??= openLoggedInApi(user);
-        return opened;
-      };
-      const api: BoundApi = {
-        writeOk: async (type, payload, requestId) =>
-          (await bound()).writeOk(type, payload, requestId),
-        writeErr: async (type, payload) => (await bound()).writeErr(type, payload),
-        queryOk: async (type, payload) => (await bound()).queryOk(type, payload),
-        queryErr: async (type, payload) => (await bound()).queryErr(type, payload),
-      };
-      apiByUserId.set(user.id, api);
-      return api;
-    };
+  // One cookie jar per user: two tenants (or admin + member) in one test must not clobber each other's session.
+  const openLoggedInApi = async (user: SeededUser): Promise<BoundApi> => {
+    const ctx = await playwright.request.newContext({ baseURL });
+    openedContexts.push(ctx);
+    await loginViaApi(ctx, user);
+    return createHttpApi(ctx);
+  };
 
-    const loginAs = async (page: Page, user: SeededUser): Promise<void> => {
-      await page.context().clearCookies();
-      await loginViaApi(page.context().request, user);
+  const httpApiFor = (user: SeededUser): BoundApi => {
+    const cached = apiByUserId.get(user.id);
+    if (cached !== undefined) return cached;
+    let opened: Promise<BoundApi> | undefined;
+    const bound = (): Promise<BoundApi> => {
+      opened ??= openLoggedInApi(user);
+      return opened;
+    };
+    const api: BoundApi = {
+      writeOk: async (type, payload, requestId) =>
+        (await bound()).writeOk(type, payload, requestId),
+      writeErr: async (type, payload) => (await bound()).writeErr(type, payload),
+      queryOk: async (type, payload) => (await bound()).queryOk(type, payload),
+      queryErr: async (type, payload) => (await bound()).queryErr(type, payload),
     };
+    apiByUserId.set(user.id, api);
+    return api;
+  };
 
-    await use(async (opts = {}) => {
-      const seeded = await postSeedRoute(
-        request,
-        SEED_ROUTES.seedTenant,
-        { name: opts.name, members: opts.users },
-        seedTenantResponseSchema,
-      );
-      const tenantId = seeded.id;
-      const toUser = (credentials: SeededCredentials, roles: readonly string[]): SeededUser =>
-        withSession(credentials, tenantId, roles);
-
-      const admin = toUser(seeded.admin, [ROLES.TenantAdmin]);
-      await loginViaApi(context.request, admin);
-
-      const tenant: E2eSeededTenant = {
-        id: tenantId,
-        key: seeded.key,
-        name: seeded.name,
-        admin,
-        members: seeded.members.map((member) => toUser(member, [ROLES.Member])),
-        addUser: async (roles = [ROLES.Member]) =>
-          toUser(
-            await postSeedRoute(
-              request,
-              SEED_ROUTES.seedUser,
-              { tenantId, roles: [...roles] } satisfies SeedUserRequest,
-              seedUserResponseSchema,
-            ),
-            roles,
+  const loginAs = async (page: Page, user: SeededUser): Promise<void> => {
+    await page.context().clearCookies();
+    await loginViaApi(page.context().request, user);
+  };
+
+  await use(async (opts = {}) => {
+    if (baseURL === undefined) {
+      throw new Error("seedTenant: the Playwright config has no baseURL");
+    }
+    const seeded = await postSeedRoute(
+      request,
+      SEED_ROUTES.seedTenant,
+      { name: opts.name, members: opts.users },
+      seedTenantResponseSchema,
+    );
+    const tenantId = seeded.id;
+    const toUser = (credentials: SeededCredentials, roles: readonly string[]): SeededUser =>
+      withSession(credentials, tenantId, roles);
+
+    const admin = toUser(seeded.admin, [ROLES.TenantAdmin]);
+    await loginViaApi(context.request, admin);
+
+    const tenant: E2eSeededTenant = {
+      id: tenantId,
+      key: seeded.key,
+      name: seeded.name,
+      admin,
+      members: seeded.members.map((member) => toUser(member, [ROLES.Member])),
+      addUser: async (roles = [ROLES.Member]) =>
+        toUser(
+          await postSeedRoute(
+            request,
+            SEED_ROUTES.seedUser,
+            { tenantId, roles: [...roles] } satisfies SeedUserRequest,
+            seedUserResponseSchema,
           ),
-        api: httpApiFor(admin),
-        apiAs: httpApiFor,
-        loginAs,
-      };
+          roles,
+        ),
+      api: httpApiFor(admin),
+      apiAs: httpApiFor,
+      loginAs,
+    };
 
-      for (const part of opts.with ?? []) await part({ tenant });
-      return tenant;
-    });
+    for (const part of opts.with ?? []) await part({ tenant });
+    return tenant;
+  });
 
-    await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
-  },
+  await Promise.all(openedContexts.map((ctx) => ctx.dispose()));
+}
+
+export const test = base.extend<E2eFixtures>({
+  seedTenant: provideSeedTenant,
 });

package/src/preload/ci-log.ts

@@ -1,2 +1,2 @@
 // biome-ignore-all lint/suspicious/noConsole: the preload exists to print this line.
-console.log("[kumiko-test] CI profile active — config=bunfig.ci.toml concurrency=1");
+console.log("[kumiko-test] CI profile active — config=bunfig.ci.toml");

package/src/scaffold.ts

@@ -35,7 +35,7 @@ const RULES_MARKDOWN = [
   `- Real-provider tests only run with \`${REAL_PROVIDERS_ENV}=1\`, via \`bun run test:real\` / \`bun run e2e:real\`, locally and never in CI.`,
   "- Tests run in parallel by default. Timeouts, retries and workers live in the scripts, the bunfig files and `playwright.config.ts`; never raise them inside a test. The only exception carries a marker: `// @timeout-exception: #<issue> <reason>`.",
   "- Every flow seeds its own tenant: `seedTenant(stack)` in integration tests, the `seedTenant` fixture in e2e. No shared tenant, no widened seed helper.",
-  "- Red or flaky? Diagnose the cause first (`docs/guides/test-failures.md` in the kumiko-framework repo). A longer timeout, a retry or `serial` is not a fix.",
+  "- Red or flaky? Diagnose the cause first (https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/docs/guides/test-failures.md). A longer timeout, a retry or `serial` is not a fix.",
   "- Run Playwright as `bunx --bun playwright`, as the scripts do.",
   `- Playwright configs and e2e files start with \`${TEST_RUNTIME_DIRECTIVE}\`; without it the runtime-isolation guard flags their import of the test package.`,
   "",