@cosmicdrift/kumiko-testing 0.367.0 → 0.368.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.367.0",
+  "version": "0.368.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>",
@@ -22,6 +22,22 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./stack": {
+      "types": "./src/stack/index.ts",
+      "default": "./src/stack/index.ts"
+    },
+    "./helpers": {
+      "types": "./src/helpers/index.ts",
+      "default": "./src/helpers/index.ts"
+    },
+    "./helpers/real-providers": {
+      "types": "./src/helpers/real-providers.ts",
+      "default": "./src/helpers/real-providers.ts"
+    },
+    "./helpers/e2e-generator": {
+      "types": "./src/helpers/e2e-generator.ts",
+      "default": "./src/helpers/e2e-generator.ts"
+    },
     "./bunfig": {
       "types": "./src/bunfig.ts",
       "default": "./src/bunfig.ts"
@@ -79,19 +95,25 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.367.0",
-    "@cosmicdrift/kumiko-dev-server": "0.367.0",
-    "@cosmicdrift/kumiko-framework": "0.367.0",
-    "@cosmicdrift/kumiko-types": "0.367.0",
+    "@cosmicdrift/kumiko-framework": "0.368.0",
+    "@cosmicdrift/kumiko-types": "0.368.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
+    "@cosmicdrift/kumiko-bundled-features": ">=0.366.0 <1.0.0",
+    "@cosmicdrift/kumiko-dev-server": ">=0.366.0 <1.0.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2"
   },
   "peerDependenciesMeta": {
+    "@cosmicdrift/kumiko-bundled-features": {
+      "optional": true
+    },
+    "@cosmicdrift/kumiko-dev-server": {
+      "optional": true
+    },
     "@happy-dom/global-registrator": {
       "optional": true
     },
@@ -106,10 +128,13 @@
     }
   },
   "devDependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "0.368.0",
+    "@cosmicdrift/kumiko-dev-server": "0.368.0",
     "@happy-dom/global-registrator": "^20.11.2",
     "@playwright/test": "^1.62.1",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/react": "^16.3.2"
+    "@testing-library/react": "^16.3.2",
+    "ts-morph": "^28.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/bunfig.ts

@@ -1,5 +1,5 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { E2E_TIMEOUT_MS } from "./e2e/timeouts";
+import { E2E_TIMEOUT_MS } from "./e2e-timeouts";
 
 export const TEST_TIMEOUT_MS = {
   unit: 5000,

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

@@ -3,7 +3,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join } from "node:path";
 import { parseEnv } from "node:util";
-import { isRealProviderRun } from "@cosmicdrift/kumiko-framework/testing/real-providers";
 import {
   defineConfig,
   devices,
@@ -13,6 +12,8 @@ import {
   type PlaywrightWorkerOptions,
   type Project,
 } from "@playwright/test";
+import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
+import { isRealProviderRun } from "../helpers/real-providers.js";
 import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
   DESKTOP_VIEWPORT,
@@ -26,7 +27,6 @@ import {
   TRUSTED_PROXY_HOPS_ENV,
 } from "./constants";
 import { isScreenshotRun, requireScreenshotDir, screenshotSpecsIgnore } from "./screenshot-dir";
-import { E2E_TIMEOUT_MS } from "./timeouts";
 
 // Apps pick Meilisearch over their in-memory search adapter just because
 // MEILI_URL is set, so a default here would point every consumer without a

package/src/e2e/index.ts

@@ -1,9 +1,10 @@
+export { expect } from "@playwright/test";
+export { E2E_TIMEOUT_MS } from "../e2e-timeouts";
 export {
   isRealProviderRun,
   REAL_PROVIDERS_ENV,
   requireRealProviders,
-} from "@cosmicdrift/kumiko-framework/testing/real-providers";
-export { expect } from "@playwright/test";
+} from "../helpers/real-providers.js";
 export {
   apiCommand,
   apiQuery,
@@ -77,4 +78,3 @@ export {
   type SeedTenantFixture,
   test,
 } from "./seeded-tenant-fixture";
-export { E2E_TIMEOUT_MS } from "./timeouts";

package/src/e2e/poll.ts

@@ -1,6 +1,6 @@
 import { expect } from "@playwright/test";
+import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
 import type { BoundApi } from "../seed-types";
-import { E2E_TIMEOUT_MS } from "./timeouts";
 
 export async function waitForProjection<T>(
   read: () => Promise<T>,

package/src/e2e/screenshots.ts

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
-import { isRealProviderRun } from "@cosmicdrift/kumiko-framework/testing/real-providers";
 import { expect, type Page, errors as playwrightErrors, type Request } from "@playwright/test";
+import { E2E_TIMEOUT_MS } from "../e2e-timeouts";
+import { isRealProviderRun } from "../helpers/real-providers.js";
 import { DESKTOP_VIEWPORT } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
 import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
-import { E2E_TIMEOUT_MS } from "./timeouts";
 
 export const DEFAULT_REDUCED_MOTION = "reduce" as const;
 

package/src/e2e/seed-route.ts

@@ -1,8 +1,8 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import type { EmailMessage } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
+  createMailTransportInMemoryFeature,
   getInbox,
-  mailTransportInMemoryFeature,
 } from "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
@@ -137,7 +137,7 @@ export type E2eSeedRoutesOptions = {
   // Apps that send tenantless mail (signup/forgot-password/magic-link) via
   // their own raw createInMemoryTransport() pass its `sent` array here so
   // the inbox route can read it without a tenantId. Independent of
-  // mailTransportInMemoryFeature — both sources may be present at once.
+  // createMailTransportInMemoryFeature() — both sources may be present at once.
   readonly mailOutbox?: { readonly sent: readonly EmailMessage[] };
 };
 
@@ -252,12 +252,13 @@ export function createE2eSeedRoutes(
       const tenantId = verified.tenantId;
       const mailOutbox = options.mailOutbox;
       const hasTenantSource =
-        tenantId !== undefined && deps.registry.features.has(mailTransportInMemoryFeature.name);
+        tenantId !== undefined &&
+        deps.registry.features.has(createMailTransportInMemoryFeature().name);
       if (!hasTenantSource && mailOutbox === undefined) {
         return c.json(
           {
             error:
-              `no inbox to read: neither ${mailTransportInMemoryFeature.name} is mounted with a ` +
+              `no inbox to read: neither ${createMailTransportInMemoryFeature().name} is mounted with a ` +
               "tenantId nor was mailOutbox passed to createE2eSeedRoutes()",
           },
           501,

package/src/helpers/access-assertions.ts

@@ -0,0 +1,15 @@
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+// Test-only helper: extracts the role list from a role-based AccessRule,
+// narrowing the union safely. Throws when the rule is openToAll or missing —
+// the tests that call this always expect roles, and a clear error beats a
+// cryptic undefined assertion downstream.
+export function rolesOf(access: AccessRule | undefined): readonly string[] {
+  if (!access) {
+    throw new Error("expected role-based access rule, got undefined");
+  }
+  if (!("roles" in access)) {
+    throw new Error("expected role-based access rule, got openToAll");
+  }
+  return access.roles;
+}

package/src/helpers/assertions.ts

@@ -0,0 +1,35 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
+
+export function expectSuccess<T>(
+  result: WriteResult<T>,
+): asserts result is { isSuccess: true; data: T } {
+  if (!result.isSuccess) {
+    throw new Error(
+      `Expected success but got error: ${result.error.code} (${result.error.message})`,
+    );
+  }
+}
+
+// `matcher` checks either the error code (e.g. "not_found") or looks for a
+// substring in the message. Both are useful: code matches are stable across
+// i18n changes, substrings catch feature-specific detail text.
+export function expectError(
+  result: WriteResult,
+  matcher?: string,
+): asserts result is { isSuccess: false; error: WriteErrorInfo } {
+  if (result.isSuccess) {
+    throw new Error("Expected error but got success");
+  }
+  if (matcher === undefined) {
+    // skip: caller only asked for the type narrowing; nothing else to check.
+    return;
+  }
+  const err = result.error;
+  const hit = err.code === matcher || err.message.includes(matcher);
+  if (!hit) {
+    throw new Error(
+      `Expected error code or message to match "${matcher}" but got code="${err.code}", message="${err.message}"`,
+    );
+  }
+}

package/src/helpers/boot-validator-fixture.ts

@@ -0,0 +1,127 @@
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  FeatureDefinition,
+  TranslationEntry,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  featureHasI18nSurface,
+  requiredKeysFromFeature,
+  SEARCHABLE_FALSE_WHITELIST,
+} from "@cosmicdrift/kumiko-framework/internal/stack-support";
+
+function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {
+  if (!feature.entities) return feature;
+  const entities: Record<string, EntityDefinition> = { ...feature.entities };
+
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type !== "entityList") continue;
+    const entity = entities[screen.entity];
+    if (!entity) continue;
+
+    const hasSortable = Object.values(entity.fields).some(
+      (field) => "sortable" in field && field.sortable === true,
+    );
+    if (hasSortable) continue;
+
+    const firstCol = screen.columns[0];
+    if (firstCol === undefined) continue;
+    const fieldName = normalizeListColumn(firstCol).field;
+    const fieldDef = entity.fields[fieldName];
+    if (fieldDef === undefined) continue;
+
+    if (fieldDef.type !== "text" && fieldDef.type !== "number") continue;
+
+    entities[screen.entity] = {
+      ...entity,
+      fields: {
+        ...entity.fields,
+        [fieldName]: { ...fieldDef, sortable: true },
+      },
+    };
+  }
+
+  return { ...feature, entities };
+}
+
+function ensureEntityListRowNavigation(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  const hasEdit = Object.values(feature.screens).some(
+    (s) => s.type === "entityEdit" && s.entity === screen.entity,
+  );
+  if (!hasEdit) return screen;
+  const hasNavigate = (screen.rowActions ?? []).some(
+    (a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"),
+  );
+  if (hasNavigate) return screen;
+  const editScreen = Object.values(feature.screens).find(
+    (s) => s.type === "entityEdit" && s.entity === screen.entity,
+  );
+  if (editScreen === undefined) return screen;
+  return {
+    ...screen,
+    rowActions: [
+      ...(screen.rowActions ?? []),
+      // No `params` here: this same-entity target always resolves to
+      // UPDATE mode (the renderer auto-fills entityId from row["id"]),
+      // and entityEdit-update never reads search-params as initial
+      // values — the boot-validator now rejects that combination (#1680).
+      {
+        kind: "navigate",
+        id: "edit",
+        label: "stub:edit",
+        screen: editScreen.id,
+      },
+    ],
+  };
+}
+
+function defaultSortForEntityList(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  if (screen.defaultSort !== undefined || screen.searchable === false) return screen;
+  if (SEARCHABLE_FALSE_WHITELIST.has(screen.id)) return screen;
+
+  const entity = feature.entities?.[screen.entity];
+  const sortableColumn = screen.columns.map(normalizeListColumn).find((col) => {
+    const fieldDef = entity?.fields[col.field];
+    return fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+  });
+  if (sortableColumn === undefined) return screen;
+
+  return { ...screen, defaultSort: { field: sortableColumn.field, dir: "asc" as const } };
+}
+
+function stubTranslations(feature: FeatureDefinition): FeatureDefinition {
+  if (!featureHasI18nSurface(feature)) return feature;
+  const keys: Record<string, TranslationEntry> = {
+    ...Object.fromEntries(
+      Object.entries(feature.translations ?? {}).map(([key, value]) => [key, { ...value }]),
+    ),
+  };
+  for (const key of requiredKeysFromFeature(feature)) {
+    if (keys[key] === undefined) keys[key] = { de: "stub", en: "stub" };
+  }
+  return { ...feature, translations: keys };
+}
+
+/** Test-fixture helper: satisfy entityList + i18n boot rules without bloating every makeFeature. */
+export function withBootValidatorFixture(
+  features: readonly FeatureDefinition[],
+): FeatureDefinition[] {
+  return features.map((feature) => {
+    const sortable = ensureEntityListSortable(feature);
+    const screens = Object.fromEntries(
+      Object.entries(sortable.screens).map(([id, screen]) => {
+        if (screen.type !== "entityList") return [id, screen];
+        const withDefaults = defaultSortForEntityList(sortable, screen);
+        return [id, ensureEntityListRowNavigation(sortable, withDefaults)];
+      }),
+    );
+    return stubTranslations({ ...sortable, screens });
+  });
+}

package/src/helpers/closed-connection-error.ts

@@ -0,0 +1,59 @@
+// Captures a real closed-connection error instead of a hand-built fake —
+// the production matcher checks driver-specific codes a fake can't reproduce.
+
+import { isClosedConnectionError } from "@cosmicdrift/kumiko-framework/internal/stack-support";
+import postgres from "postgres";
+import { requireEnv } from "../stack/db.js";
+
+export function testDatabaseUrl(): string {
+  return requireEnv("TEST_DATABASE_URL");
+}
+
+const MAX_WARMUP_ROUNDS = 10;
+const READS_PER_ROUND = 5;
+
+type AdminClient = { unsafe(sql: string, params?: readonly unknown[]): Promise<unknown> };
+
+// A per-round admin client hits a postgres-js reconnect timing bug (the first
+// retry after terminate hangs); a single long-lived admin client avoids it.
+export async function terminateBackendsByApplicationName(
+  admin: AdminClient,
+  applicationName: string,
+): Promise<void> {
+  await admin.unsafe(
+    "select pg_terminate_backend(pid) from pg_stat_activity where application_name = $1",
+    [applicationName],
+  );
+}
+
+// Terminates a throwaway pool's backends and races reads right after — the
+// dead-connection window is only a few ms wide, so this retries rounds until one lands.
+export async function captureClosedConnectionError(
+  url: string = testDatabaseUrl(),
+): Promise<unknown> {
+  const admin = postgres(url, { max: 1 });
+  try {
+    for (let round = 0; round < MAX_WARMUP_ROUNDS; round++) {
+      const applicationName = `kumiko-closed-conn-test-${crypto.randomUUID()}`;
+      const pool = postgres(url, { max: 1, connection: { application_name: applicationName } });
+      try {
+        await pool.unsafe("select 1");
+        await terminateBackendsByApplicationName(admin, applicationName);
+        for (let read = 0; read < READS_PER_ROUND; read++) {
+          try {
+            await pool.unsafe("select 1");
+          } catch (err) {
+            if (isClosedConnectionError(err)) return err;
+          }
+        }
+      } finally {
+        await pool.end({ timeout: 0 });
+      }
+    }
+    throw new Error(
+      `captureClosedConnectionError: no closed-connection error observed after ${MAX_WARMUP_ROUNDS} rounds.`,
+    );
+  } finally {
+    await admin.end({ timeout: 0 });
+  }
+}

package/src/helpers/db-cleanup.ts

@@ -0,0 +1,41 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { deleteMany } from "@cosmicdrift/kumiko-framework/db";
+import type { AnyDb } from "@cosmicdrift/kumiko-framework/internal/stack-support";
+
+/** EntityTableMeta, a built table, or a plain table name string. */
+export type ClearableTable = string | { readonly tableName?: string } | unknown;
+
+// A full-table wipe (empty where) only needs the table name — give deleteMany
+// a minimal-but-canonical EntityTableMeta so extractTableInfo accepts it
+// without inferring columns.
+function tableFromName(name: string): EntityTableMeta {
+  return { tableName: name, columns: [], indexes: [], source: "unmanaged" };
+}
+
+function resolveClearableTable(table: ClearableTable): unknown {
+  if (typeof table === "string") return tableFromName(table);
+  if (
+    typeof table === "object" &&
+    table !== null &&
+    "tableName" in table &&
+    typeof table.tableName === "string"
+  ) {
+    return table;
+  }
+  return table;
+}
+
+/** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
+export async function clearTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
+  for (const table of tables) {
+    // Test-teardown truncate: resolveClearableTable returns `unknown` (string
+    // name or table object). The brand-strip cast is the sanctioned bypass —
+    // clearing a managed projection between tests is not a production write.
+    await deleteMany(db, resolveClearableTable(table) as EntityTableMeta, {});
+  }
+}
+
+/** Alias — same as clearTables, reads better in beforeEach. */
+export async function resetTestTables(db: AnyDb, tables: readonly ClearableTable[]): Promise<void> {
+  await clearTables(db, tables);
+}