@cosmicdrift/kumiko-framework 0.318.0 → 0.320.0

package/src/stack/__tests__/push-entity-projection-tables-column-sync.integration.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import { pushEntityProjectionTables } from "../push-entity-projection-tables";
+import { setupTestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+function freshDbName(tag: string): string {
+  return `kumiko_test_${tag}_${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+
+describe("pushEntityProjectionTables — persistent dev DB column sync", () => {
+  test("a nullable field added after the first boot is backfilled without manual DDL", async () => {
+    const dbName = freshDbName("colsync_nullable");
+    const widgetV1 = createEntity({
+      table: "colsync_nullable_widgets",
+      fields: {
+        name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+      },
+    });
+    const v1 = defineFeature("colsync-nullable", (r) => {
+      r.entity("widget", widgetV1);
+    });
+    // Owns the actual DROP DATABASE on cleanup.
+    const firstBoot = await setupTestStack({ features: [v1], dbName });
+    try {
+      await pushEntityProjectionTables(firstBoot, firstBoot.registry);
+
+      const widgetV2 = createEntity({
+        table: "colsync_nullable_widgets",
+        fields: {
+          name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+          note: createTextField({ personal: false, reason: "test_fixture" }),
+        },
+      });
+      const v2 = defineFeature("colsync-nullable", (r) => {
+        r.entity("widget", widgetV2);
+        r.writeHandler(
+          defineEntityCreateHandler("widget", widgetV2, { access: { roles: ["Admin"] } }),
+        );
+      });
+      const secondBoot = await setupTestStack({ features: [v2], dbName, persistentDb: true });
+      try {
+        await pushEntityProjectionTables(secondBoot, secondBoot.registry);
+        const created = await secondBoot.http.writeOk<{ data: { note: string } }>(
+          "colsync-nullable:write:widget:create",
+          { name: "backfilled widget", note: "backfilled via HTTP write" },
+          TestUsers.admin,
+        );
+        expect(created.data.note).toBe("backfilled via HTTP write");
+      } finally {
+        await secondBoot.cleanup();
+      }
+    } finally {
+      await firstBoot.cleanup();
+    }
+  });
+
+  test("a required field with no default added after the first boot fails with a clear, actionable error", async () => {
+    const dbName = freshDbName("colsync_required");
+    const v1 = defineFeature("colsync-required", (r) => {
+      r.entity(
+        "gadget",
+        createEntity({
+          table: "colsync_required_gadgets",
+          fields: {
+            name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+          },
+        }),
+      );
+    });
+    const firstBoot = await setupTestStack({ features: [v1], dbName });
+    try {
+      await pushEntityProjectionTables(firstBoot, firstBoot.registry);
+
+      const v2 = defineFeature("colsync-required", (r) => {
+        r.entity(
+          "gadget",
+          createEntity({
+            table: "colsync_required_gadgets",
+            fields: {
+              name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+              serial: createTextField({ personal: false, reason: "test_fixture", required: true }),
+            },
+          }),
+        );
+      });
+      const secondBoot = await setupTestStack({ features: [v2], dbName, persistentDb: true });
+      try {
+        await expect(pushEntityProjectionTables(secondBoot, secondBoot.registry)).rejects.toThrow(
+          /serial.*no default/i,
+        );
+        await expect(pushEntityProjectionTables(secondBoot, secondBoot.registry)).rejects.toThrow(
+          /dropdb/,
+        );
+      } finally {
+        await secondBoot.cleanup();
+      }
+    } finally {
+      await firstBoot.cleanup();
+    }
+  });
+});

package/src/stack/push-entity-projection-tables.ts

@@ -1,8 +1,11 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
-import { tableExists } from "../db/schema-inspection";
+import type { DbConnection } from "../db/connection";
+import type { ColumnMeta } from "../db/entity-table-meta";
+import { columnNamesOf, tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
-import { unsafePushTables } from "./table-helpers";
-import type { TestStack } from "./test-stack";
+import { addMissingColumns, tableToMeta, unsafePushTables } from "./table-helpers";
+
+type DbHolder = { readonly db: DbConnection };
 
 // biome-ignore lint/suspicious/noConsole: stack-internal status logging
 const logInfo = (msg: string): void => console.log(msg);
@@ -25,7 +28,7 @@ const logInfo = (msg: string): void => console.log(msg);
  * never call this directly.
  */
 export async function pushEntityProjectionTables(
-  stack: TestStack,
+  stack: DbHolder,
   registry: Registry,
 ): Promise<void> {
   const seen = new Set<unknown>();
@@ -37,14 +40,56 @@ export async function pushEntityProjectionTables(
     seen.add(proj.table);
     const tableRec = proj.table as unknown as Record<symbol, unknown>;
     const physical = tableRec[KUMIKO_NAME_SYMBOL] as string;
-    if (await tableExists(stack.db, `public.${physical}`)) {
-      logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+    if (!(await tableExists(stack.db, `public.${physical}`))) {
+      missing[projName] = proj.table;
       continue;
     }
-    missing[projName] = proj.table;
+    await syncExistingProjectionTable(stack, physical, proj.table);
   }
 
   if (Object.keys(missing).length > 0) {
     await unsafePushTables(stack.db, missing);
   }
 }
+
+function isUnsafeToAutoAdd(col: ColumnMeta): boolean {
+  return col.notNull && !col.primaryKey && col.defaultSql === undefined;
+}
+
+// Backfills columns a persistent dev DB predates; a required column with no
+// default can't be added safely on a table that may hold rows, so that
+// stays a boot error instead.
+async function syncExistingProjectionTable(
+  stack: DbHolder,
+  physical: string,
+  table: unknown,
+): Promise<void> {
+  const meta = tableToMeta(table);
+  const liveColumns = await columnNamesOf(stack.db, physical);
+  const missingColumns = meta.columns.filter((c) => !liveColumns.has(c.name));
+  if (missingColumns.length === 0) {
+    logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+    // skip: live table already has every declared column
+    return;
+  }
+
+  const unsafeColumns = missingColumns.filter(isUnsafeToAutoAdd);
+  if (unsafeColumns.length > 0) {
+    const devDbName = process.env["KUMIKO_DEV_DB_NAME"] ?? "<KUMIKO_DEV_DB_NAME>";
+    throw new Error(
+      `[kumiko-stack] table "${physical}" is missing required column(s) ` +
+        `${unsafeColumns.map((c) => `"${c.name}"`).join(", ")} with no default. ` +
+        "Auto-sync only backfills nullable columns or columns with a default on an " +
+        "existing dev DB — a required column with no default can't be added safely " +
+        `once the table may hold rows. Drop the persistent dev database "${devDbName}" ` +
+        `(e.g. \`dropdb ${devDbName}\`, adjusted for your local Postgres host/port/user) ` +
+        "so the next boot recreates it from scratch.",
+    );
+  }
+
+  logInfo(
+    `[kumiko-stack] table ${physical} is missing column(s) ` +
+      `${missingColumns.map((c) => `"${c.name}"`).join(", ")} — adding`,
+  );
+  await addMissingColumns(stack.db, physical, missingColumns);
+}

package/src/stack/table-helpers.ts

@@ -67,7 +67,7 @@ function isMetaShape(v: unknown): v is EntityTableMeta {
   );
 }
 
-function tableToMeta(table: unknown): EntityTableMeta {
+export function tableToMeta(table: unknown): EntityTableMeta {
   // table() spreads column handles as enumerable props, so a field named
   // `columns`/`tableName`/`source`/… shadows the matching meta key — read the
   // canonical meta from the unshadowable symbol when present.
@@ -79,6 +79,20 @@ function tableToMeta(table: unknown): EntityTableMeta {
   throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
 }
 
+/** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
+export async function addMissingColumns(
+  db: DbConnection,
+  tableName: string,
+  columns: readonly ColumnMeta[],
+): Promise<void> {
+  for (const col of columns) {
+    const type = renderColumnType(col);
+    const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
+    const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
+    await alterTableAddColumn(db, tableName, col.name, type, defaultClause, notNull);
+  }
+}
+
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
@@ -106,14 +120,8 @@ export async function unsafePushTables(
 
     if (prev) {
       const prevCols = new Set(prev.columns.map((c) => c.name));
-      for (const col of meta.columns) {
-        if (!prevCols.has(col.name)) {
-          const type = renderColumnType(col);
-          const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
-          const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
-          await alterTableAddColumn(db, meta.tableName, col.name, type, defaultClause, notNull);
-        }
-      }
+      const newCols = meta.columns.filter((c) => !prevCols.has(c.name));
+      await addMissingColumns(db, meta.tableName, newCols);
       const prevIdxNames = new Set(prev.indexes.map((i) => i.name));
       for (const idx of meta.indexes) {
         if (!prevIdxNames.has(idx.name)) {

package/src/stack/test-stack.ts

@@ -18,6 +18,7 @@ import {
   createIdempotencyGuard,
   dispatcherToWriteRef,
 } from "../pipeline";
+import { createRateLimitResolver } from "../rate-limit";
 import { createInMemorySearchAdapter } from "../search";
 import type { SearchAdapter } from "../search/types";
 import { createTestDb } from "./db";
@@ -187,6 +188,9 @@ export type TestStackOptions = {
    *  them themselves. Default true — false pushes only projection/MSP/
    *  storeTable sources, same as before fw#3102. */
   entityTables?: boolean;
+  /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
+   *  — see there. Default 0. */
+  trustedProxyHops?: number;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -417,9 +421,31 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
     const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
 
+    // buildServer only auto-wires an L3 RateLimitResolver from
+    // `context.redis` — a degradation test that nulls `redis` via
+    // extraContext (to exercise a handler's own ctx.redis-down guard) also
+    // silently strips rate-limiting, even though every handler with a
+    // `rateLimit` declaration still requires a resolver at dispatch time.
+    // Since e7bf543ad, an IP-keyed bucket key is built unconditionally
+    // (falls back to a shared "unknown" IP rather than skipping), so the
+    // missing resolver now throws instead of merely skipping enforcement.
+    // Mirrors idempotency/eventDedup above: built from the test-stack's own
+    // always-real `testRedis.redis`, independent of whatever extraContext
+    // did to `appContext.redis` — an explicit `context.rateLimit` from
+    // extraContext still wins (same precedence buildServer documents).
+    // @cast-boundary extraContext is declared Record<string, unknown> (late,
+    // dynamic extension point) — appContext's inferred type doesn't carry a
+    // `rateLimit` key, so reading it back needs the same relaxed boundary
+    // extraContext itself is typed with.
+    const explicitRateLimit = (appContext as { rateLimit?: unknown }).rateLimit;
+    const rateLimitFallback =
+      appContext.redis === undefined && explicitRateLimit === undefined
+        ? createRateLimitResolver({ redis: testRedis.redis })
+        : undefined;
+
     const server = buildServer({
       registry,
-      context: appContext,
+      context: rateLimitFallback ? { ...appContext, rateLimit: rateLimitFallback } : appContext,
       jwtSecret,
       ...(options.observability ? { observability: options.observability } : {}),
       dispatcherOptions: {
@@ -429,6 +455,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       },
       eventDedup,
       sseBroker,
+      ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
       ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
       ...(options.metrics && { metrics: options.metrics }),
       // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for

package/src/testing/real-providers.ts

@@ -1,3 +1,5 @@
+// Playwright configs load this module under plain Node via
+// @cosmicdrift/kumiko-testing/e2e, so it must stay import-free.
 export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
 const CI_FLAG = "CI";
 

package/src/ui-types/index.ts

@@ -64,7 +64,7 @@ export type {
   RoleAccessPersonalData,
   RoleAccessRule,
 } from "../engine/types/handlers";
-export { isOpenToAllGranted } from "../engine/types/handlers";
+export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";
 export type {
   ActionFormRedirect,