@cosmicdrift/kumiko-framework 0.187.0 → 0.188.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.187.0",
+  "version": "0.188.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,10 +182,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.187.0",
+    "@cosmicdrift/kumiko-types": "0.188.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
-    "hono": "^4.12.27",
+    "hono": "^4.13.1",
     "i18next": "^26.1.0",
     "ioredis": "^5.10.1",
     "jose": "^6.2.3",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.187.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.188.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/origin-middleware.test.ts

@@ -143,19 +143,18 @@ describe("originMiddleware", () => {
 
   // The guard runs as /api/* middleware before routing, so a disallowed-origin
   // request is rejected for every state-changing method even without a route.
-  test.each([
-    "PUT",
-    "PATCH",
-    "DELETE",
-  ])("cookie transport + %s + disallowed origin → 403 (every state-changing method)", async (method) => {
-    const { app, token } = await buildApp();
-    const res = await app.request("/api/write", {
-      method,
-      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
-    });
-    expect(res.status).toBe(403);
-    expect(await readErrorCode(res)).toBe("origin_not_allowed");
-  });
+  test.each(["PUT", "PATCH", "DELETE"])(
+    "cookie transport + %s + disallowed origin → 403 (every state-changing method)",
+    async (method) => {
+      const { app, token } = await buildApp();
+      const res = await app.request("/api/write", {
+        method,
+        headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
+      });
+      expect(res.status).toBe(403);
+      expect(await readErrorCode(res)).toBe("origin_not_allowed");
+    },
+  );
 
   test("disallowed origin is blocked even as a simple text/plain request", async () => {
     // The real vector: a `text/plain` POST skips the CORS preflight and reaches

package/src/bun-db/__tests__/extract-table-info.test.ts

@@ -29,17 +29,16 @@ describe("extractTableInfo — EntityTableMeta discriminator is shadow-proof", (
     expect(info.pgTypeOf("source")).toBe("text");
   });
 
-  test.each([
-    "columns",
-    "tableName",
-    "indexes",
-  ])("an entity field named `%s` (another meta key) also does not shadow it", (fieldName) => {
-    const table = buildEntityTable("thing", {
-      fields: { [fieldName]: { type: "text", required: true } },
-    });
-    const info = extractTableInfo(table);
-    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
-  });
+  test.each(["columns", "tableName", "indexes"])(
+    "an entity field named `%s` (another meta key) also does not shadow it",
+    (fieldName) => {
+      const table = buildEntityTable("thing", {
+        fields: { [fieldName]: { type: "text", required: true } },
+      });
+      const info = extractTableInfo(table);
+      expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+    },
+  );
 
   test("control entity without a colliding field is unaffected", () => {
     const table = buildEntityTable("note", {

package/src/engine/__tests__/boot-validator.test.ts

@@ -1742,6 +1742,8 @@ describe("boot-validator", () => {
       readonly redirect?: string;
       readonly cancelTarget?: string | false;
       readonly extraScreens?: readonly string[];
+      readonly mode?: "single" | "wizard";
+      readonly draft?: boolean;
     };
 
     // Hilfs-Schema-Setup: stamps eine Test-Entity + write-handler
@@ -1770,7 +1772,11 @@ describe("boot-validator", () => {
           type: "actionForm",
           handler,
           fields: fields as never,
-          layout: { sections: sections as never },
+          layout: {
+            sections: sections as never,
+            ...(override.mode !== undefined && { mode: override.mode }),
+            ...(override.draft !== undefined && { draft: override.draft }),
+          },
           ...(override.redirect !== undefined && { redirect: override.redirect }),
           ...(override.cancelTarget !== undefined && { cancelTarget: override.cancelTarget }),
         });
@@ -1871,6 +1877,66 @@ describe("boot-validator", () => {
       const section = { kind: "extension", title: "Custom", component: { react: "Panel" } };
       expect(() => validateBoot([makeFeature({ sections: [section] as never })])).not.toThrow();
     });
+
+    test("mode: wizard mit nur 1 Section → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            mode: "wizard",
+            sections: [{ title: "Step 1", fields: ["note"] }],
+          }),
+        ]),
+      ).toThrow(/mode: "wizard" but only 1 section\(s\)/);
+    });
+
+    test("mode: wizard mit Section ohne Titel → Throw", () => {
+      const sections = [
+        { title: "Step 1", fields: ["note"] },
+        { title: "", fields: ["priority"] },
+      ];
+      expect(() => validateBoot([makeFeature({ mode: "wizard", sections })])).toThrow(
+        /sections\[1\] has no title/,
+      );
+    });
+
+    test("mode: wizard mit >= 2 betitelten Sections → kein Throw", () => {
+      const sections = [
+        { title: "Step 1", fields: ["note"] },
+        { title: "Step 2", fields: ["priority"] },
+      ];
+      expect(() => validateBoot([makeFeature({ mode: "wizard", sections })])).not.toThrow();
+    });
+
+    test("draft: true ohne gemountetes form-draft-Feature → Throw", () => {
+      const sections = [
+        { title: "Step 1", fields: ["note"] },
+        { title: "Step 2", fields: ["priority"] },
+      ];
+      expect(() => validateBoot([makeFeature({ mode: "wizard", sections, draft: true })])).toThrow(
+        /"form-draft" is not mounted/,
+      );
+    });
+
+    test("draft: true mit gemountetem form-draft-Feature → kein Throw", () => {
+      const sections = [
+        { title: "Step 1", fields: ["note"] },
+        { title: "Step 2", fields: ["priority"] },
+      ];
+      expect(() =>
+        validateBoot([
+          makeFeature({ mode: "wizard", sections, draft: true }),
+          defineFeature("form-draft", () => {}),
+        ]),
+      ).not.toThrow();
+    });
+
+    test("draft: true ohne mode: 'wizard' → Throw", () => {
+      expect(() => validateBoot([makeFeature({ draft: true })])).toThrow(/mode is not "wizard"/);
+    });
+
+    test("mode weggelassen (Default 'single') bleibt bestehendes Layout gültig → kein Throw", () => {
+      expect(() => validateBoot([makeFeature()])).not.toThrow();
+    });
   });
 
   // --- configEdit-Screen ---
@@ -2046,6 +2112,67 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityEdit wizard mode (framework#1884) ---
+  // layout.mode: "wizard" renders one section per step instead of all
+  // sections at once — needs >= 2 sections, each with a title (the step
+  // title), or it's a boot-fail instead of a broken step UI.
+  describe("entityEdit wizard mode", () => {
+    function makeFeature(
+      sections: readonly { readonly title?: string; readonly fields: readonly string[] }[],
+      mode?: "single" | "wizard",
+    ) {
+      return defineFeature("shop", (r) => {
+        r.entity(
+          "product",
+          createEntity({ fields: { name: createTextField(), sku: createTextField() } }),
+        );
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: sections as never,
+            ...(mode !== undefined && { mode }),
+          },
+        });
+      });
+    }
+
+    test("mode: wizard mit nur 1 Section → Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature([{ title: "Step 1", fields: ["name"] }], "wizard")]),
+      ).toThrow(/mode: "wizard" but only 1 section\(s\)/);
+    });
+
+    test("mode: wizard mit Section ohne Titel → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature([{ title: "Step 1", fields: ["name"] }, { fields: ["sku"] }], "wizard"),
+        ]),
+      ).toThrow(/sections\[1\] has no title/);
+    });
+
+    test("mode: wizard mit >= 2 betitelten Sections → kein Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature(
+            [
+              { title: "Step 1", fields: ["name"] },
+              { title: "Step 2", fields: ["sku"] },
+            ],
+            "wizard",
+          ),
+        ]),
+      ).not.toThrow();
+    });
+
+    test("mode weggelassen (Default 'single') bleibt bestehendes Layout gültig → kein Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature([{ title: "Details", fields: ["name", "sku"] }])]),
+      ).not.toThrow();
+    });
+  });
+
   // --- Tier 2.7e-3: ReferenceFieldDef ---
   describe("reference field (Tier 2.7e-3)", () => {
     test("reference auf bestehende Entity → kein Throw", () => {

package/src/engine/__tests__/build-app-schema.test.ts

@@ -160,7 +160,7 @@ describe("buildAppSchema", () => {
     });
     const app = buildAppSchema(createRegistry([f]));
     const fields = (
-      app.features[0]?.entities["thing"] as unknown as {
+      app.features[0]!.entities["thing"] as unknown as {
         fields: Record<string, Record<string, unknown>>;
       }
     ).fields;
@@ -186,7 +186,7 @@ describe("buildAppSchema", () => {
     });
     const app = buildAppSchema(createRegistry([f]));
     const fields = (
-      app.features[0]?.entities["thing"] as unknown as {
+      app.features[0]!.entities["thing"] as unknown as {
         fields: Record<string, Record<string, unknown>>;
       }
     ).fields;
@@ -207,7 +207,7 @@ describe("buildAppSchema", () => {
     });
     const app = buildAppSchema(createRegistry([f]));
     const fields = (
-      app.features[0]?.entities["thing"] as unknown as {
+      app.features[0]!.entities["thing"] as unknown as {
         fields: Record<string, Record<string, unknown>>;
       }
     ).fields;
@@ -228,7 +228,7 @@ describe("buildAppSchema", () => {
     });
     const app = buildAppSchema(createRegistry([f]));
     const fields = (
-      app.features[0]?.entities["thing"] as unknown as {
+      app.features[0]!.entities["thing"] as unknown as {
         fields: Record<string, Record<string, unknown>>;
       }
     ).fields;

package/src/engine/__tests__/engine.test.ts

@@ -634,14 +634,13 @@ describe("hasAccess", () => {
     { userRoles: [], requiredRoles: ["Admin"], expected: false },
     // Empty required-roles list denies everyone under default-deny.
     { userRoles: ["Admin"], requiredRoles: [], expected: false },
-  ])("user $userRoles vs required $requiredRoles → $expected", ({
-    userRoles,
-    requiredRoles,
-    expected,
-  }) => {
-    const user = createTestUser({ roles: userRoles });
-    expect(hasAccess(user, { roles: requiredRoles })).toBe(expected);
-  });
+  ])(
+    "user $userRoles vs required $requiredRoles → $expected",
+    ({ userRoles, requiredRoles, expected }) => {
+      const user = createTestUser({ roles: userRoles });
+      expect(hasAccess(user, { roles: requiredRoles })).toBe(expected);
+    },
+  );
 
   test("missing access rule denies access (default-deny)", () => {
     const user = createTestUser({ roles: ["Employee"] });

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -120,7 +120,7 @@ describe("softDeleteCleanupJob handler", () => {
   test("cutoff defaults to DEFAULT_GRACE_DAYS when no config resolver", async () => {
     const calls: DeleteCall[] = [];
     await softDeleteCleanupJob({}, makeCtx({ calls }));
-    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const cutoff = (calls[0]!.where["deletedAt"] as { lt: Temporal.Instant }).lt;
     const expected = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
     expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
   });
@@ -128,7 +128,7 @@ describe("softDeleteCleanupJob handler", () => {
   test("honours a per-tenant grace-days value from the config resolver", async () => {
     const calls: DeleteCall[] = [];
     await softDeleteCleanupJob({}, makeCtx({ calls, graceDays: 7 }));
-    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const cutoff = (calls[0]!.where["deletedAt"] as { lt: Temporal.Instant }).lt;
     const expected = Temporal.Now.instant().subtract({ hours: 7 * 24 });
     expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
   });
@@ -155,7 +155,7 @@ describe("softDeleteCleanupSystemJob handler", () => {
   test("cutoff is DEFAULT_GRACE_DAYS — no per-tenant config to read", async () => {
     const calls: DeleteCall[] = [];
     await softDeleteCleanupSystemJob({}, makeCtx({ calls }));
-    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const cutoff = (calls[0]!.where["deletedAt"] as { lt: Temporal.Instant }).lt;
     const expected = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
     expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
   });

package/src/engine/boot-validator/screens.ts

@@ -15,6 +15,7 @@ import type {
   DashboardPanelDefinition,
   DashboardScreenDefinition,
   DashboardStatGroupPanel,
+  EditLayout,
   FieldCondition,
   RowAction,
   RowFieldExtractor,
@@ -71,6 +72,58 @@ function validateRowActionNavigateParams(
   }
 }
 
+// Wizard layouts (mode: "wizard") render one section per step — a single
+// step (or a step without a title, which would leave the progress
+// indicator blank) defeats the point, so both fail at boot rather than
+// as a broken step UI. Missing/blank titles are checked identically for
+// both section kinds — EditExtensionSection.title is required by type,
+// but that doesn't stop author code that circumvented the check from
+// passing an empty string.
+function validateWizardLayout(
+  featureName: string,
+  screenId: string,
+  screenType: "entityEdit" | "actionForm",
+  layout: EditLayout,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  // "form-draft" is hardcoded because the framework layer must not depend on
+  // @cosmicdrift/kumiko-bundled-features — same precedence as the
+  // "user-data-rights" check in gdpr-storage.ts.
+  if (layout.draft === true) {
+    if (layout.mode !== "wizard") {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but ` +
+          `mode is not "wizard" — draft persistence only applies to wizard layouts. Remove ` +
+          `draft: true or set mode: "wizard".`,
+      );
+    }
+    if (!featureMap.has("form-draft")) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but the ` +
+          `bundled feature "form-draft" is not mounted — every resume would silently lose its ` +
+          `values. Add formDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
+          `feature list.`,
+      );
+    }
+  }
+  // skip: mode omitted/"single" — no wizard constraints apply.
+  if (layout.mode !== "wizard") return;
+  if (layout.sections.length < 2) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but only ` +
+        `${layout.sections.length} section(s) — a wizard needs at least 2 sections (one per step).`,
+    );
+  }
+  layout.sections.forEach((section, index) => {
+    if (section.title === undefined || section.title.trim().length === 0) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "wizard" but ` +
+          `sections[${index}] has no title — every wizard step needs a title.`,
+      );
+    }
+  });
+}
+
 // --- Screen validation ---
 //
 // For every r.screen() declaration check what's locally knowable at boot:
@@ -441,6 +494,7 @@ export function validateScreens(
           }
         }
       }
+      validateWizardLayout(feature.name, screenId, "actionForm", screen.layout, featureMap);
       if (screen.redirect !== undefined) {
         // redirect ist die kurze Screen-ID (z.B. "item-list"); der
         // nav-Router resolved sie beim Mount gegen die Schema-Map.
@@ -772,6 +826,7 @@ export function validateScreens(
           }
         }
       }
+      validateWizardLayout(feature.name, screenId, "entityEdit", screen.layout, featureMap);
     }
   }
 }

package/src/event-store/__tests__/upcaster-dead-letter.integration.test.ts

@@ -139,7 +139,7 @@ describe("upcaster error-policy: quarantine", () => {
     expect(result).toHaveLength(1);
     expect(result[0]?.id).toBe("10");
     expect(result[0]?.eventVersion).toBe(2);
-    expect((result[0]?.payload as { migrated?: boolean }).migrated).toBe(true);
+    expect((result[0]!.payload as { migrated?: boolean }).migrated).toBe(true);
 
     const dl = await listDeadLetters(testDb.db);
     expect(dl).toHaveLength(1);

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -729,33 +729,36 @@ describe("runPostSaveBatch / runPostDeleteBatch", () => {
       (pipeline: ReturnType<typeof createLifecycleHooks>) =>
         pipeline.runPostDeleteBatch([deletectx], {}),
     ],
-  ])("one %s hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown", async (_name, buildHooks, run) => {
-    const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
-    try {
-      const calls: string[] = [];
-      const systemHooks = buildHooks([
-        {
-          name: "failing",
-          priority: 1000,
-          fn: async () => {
-            throw new Error("batch-hook-boom");
+  ])(
+    "one %s hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown",
+    async (_name, buildHooks, run) => {
+      const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const calls: string[] = [];
+        const systemHooks = buildHooks([
+          {
+            name: "failing",
+            priority: 1000,
+            fn: async () => {
+              throw new Error("batch-hook-boom");
+            },
           },
-        },
-        {
-          name: "ok",
-          priority: 1001,
-          fn: async () => {
-            calls.push("ok-ran");
+          {
+            name: "ok",
+            priority: 1001,
+            fn: async () => {
+              calls.push("ok-ran");
+            },
           },
-        },
-      ]);
-      const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
-      // Must not throw.
-      await run(pipeline);
-      expect(calls).toEqual(["ok-ran"]);
-      expect(consoleSpy).toHaveBeenCalled();
-    } finally {
-      consoleSpy.mockRestore();
-    }
-  });
+        ]);
+        const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+        // Must not throw.
+        await run(pipeline);
+        expect(calls).toEqual(["ok-ran"]);
+        expect(consoleSpy).toHaveBeenCalled();
+      } finally {
+        consoleSpy.mockRestore();
+      }
+    },
+  );
 });

package/src/pipeline/__tests__/redis-pipeline.integration.test.ts

@@ -297,7 +297,7 @@ describe("entity cache", () => {
 
     const single = await cache.get("00000000-0000-4000-8000-000000000001", "event", 42);
     expect(single?.["insertedAt"]).toBeInstanceOf(Date);
-    expect((single?.["insertedAt"] as Date).getTime()).toBe(insertedAt.getTime());
+    expect((single!["insertedAt"] as Date).getTime()).toBe(insertedAt.getTime());
     // Non-ISO strings must not be coerced
     expect(typeof single?.["title"]).toBe("string");
     expect(single?.["note"]).toBe("not a date: 2026-04");

package/src/time/__tests__/iana.test.ts

@@ -4,26 +4,19 @@ import { isValidIanaTimeZone } from "../iana";
 describe("isValidIanaTimeZone", () => {
   // Die 5 Zonen der geplanten CI-TZ-Matrix (timezones.md) müssen alle gültig
   // sein — sonst kann die Matrix sie nicht setzen.
-  test.each([
-    "UTC",
-    "Europe/Berlin",
-    "America/Los_Angeles",
-    "Asia/Tokyo",
-    "Pacific/Apia",
-  ])("akzeptiert kanonische Zone %s", (zone) => {
-    expect(isValidIanaTimeZone(zone)).toBe(true);
-  });
+  test.each(["UTC", "Europe/Berlin", "America/Los_Angeles", "Asia/Tokyo", "Pacific/Apia"])(
+    "akzeptiert kanonische Zone %s",
+    (zone) => {
+      expect(isValidIanaTimeZone(zone)).toBe(true);
+    },
+  );
 
-  test.each([
-    "",
-    "Mars/Phobos",
-    "europe/berlin",
-    "Europe/Berlin ",
-    "GMT+2",
-    "not-a-zone",
-  ])("lehnt ungültigen / nicht-kanonischen String %p ab", (value) => {
-    expect(isValidIanaTimeZone(value)).toBe(false);
-  });
+  test.each(["", "Mars/Phobos", "europe/berlin", "Europe/Berlin ", "GMT+2", "not-a-zone"])(
+    "lehnt ungültigen / nicht-kanonischen String %p ab",
+    (value) => {
+      expect(isValidIanaTimeZone(value)).toBe(false);
+    },
+  );
 
   // Intl.supportedValuesOf("timeZone") listet nur kanonische Namen — gültige
   // IANA-Aliase fehlen darin, obwohl Intl.DateTimeFormat/Temporal/ctx.tz.parse