@cosmicdrift/kumiko-framework 0.1.0

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

@@ -0,0 +1,408 @@
+import { describe, expect, test } from "vitest";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+import { createRegistry } from "../registry";
+import type { ScreenDefinition } from "../types/screen";
+
+function productEntity() {
+  return createEntity({
+    table: "products",
+    fields: {
+      name: createTextField(),
+      sku: createTextField(),
+    },
+  });
+}
+
+describe("r.screen() — registration", () => {
+  test("stores an entityList screen on the FeatureDefinition", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "sku"],
+      });
+    });
+    expect(feature.screens["product-list"]).toBeDefined();
+    expect(feature.screens["product-list"]?.type).toBe("entityList");
+  });
+
+  test("stores an entityEdit screen with sections + conditional fields", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              title: "shop:section.basics",
+              columns: 2,
+              fields: [
+                "name",
+                { field: "sku", readOnly: (data) => Boolean((data as { sku?: string }).sku) },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    const screen = feature.screens["product-edit"];
+    expect(screen?.type).toBe("entityEdit");
+    if (screen?.type !== "entityEdit") throw new Error("type-narrow failed");
+    expect(screen.layout.sections).toHaveLength(1);
+  });
+
+  test("stores a custom screen with a renderer + routes", () => {
+    const feature = defineFeature("dashboard", (r) => {
+      r.screen({
+        id: "overview",
+        type: "custom",
+        renderer: { react: { __component: "dashboard-overview" } },
+        routes: [{ path: "/revenue", component: { react: { __component: "revenue" } } }],
+      });
+    });
+    const screen = feature.screens["overview"];
+    expect(screen?.type).toBe("custom");
+    if (screen?.type !== "custom") throw new Error("type-narrow failed");
+    expect(screen.routes).toHaveLength(1);
+  });
+
+  test("rejects duplicate screen ids within the same feature", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+        });
+        r.screen({
+          id: "product-list",
+          type: "entityEdit",
+          entity: "product",
+          layout: { sections: [] },
+        });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects non-kebab-case screen ids", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "productList",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+        });
+      }),
+    ).toThrow(/kebab-case/);
+  });
+
+  test("accepts kebab-case screen ids", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+        });
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("createRegistry — screen indexing", () => {
+  test("indexes screens by qualified name", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const registry = createRegistry([feature]);
+    expect(registry.getAllScreens().size).toBe(1);
+    expect(registry.getScreen("shop:screen:product-list")).toBeDefined();
+  });
+
+  test("returns undefined for unknown qualified names", () => {
+    const registry = createRegistry([]);
+    expect(registry.getScreen("ghost:screen:nope")).toBeUndefined();
+  });
+
+  test("getScreenFeature maps a screen back to its owning feature", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const registry = createRegistry([feature]);
+    expect(registry.getScreenFeature("shop:screen:product-list")).toBe("shop");
+    expect(registry.getScreenFeature("shop:screen:does-not-exist")).toBeUndefined();
+  });
+
+  test("same screen id from two features qualifies to different names", () => {
+    const shop = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const warehouse = defineFeature("warehouse", (r) => {
+      r.entity("item", productEntity());
+      r.screen({ id: "list", type: "entityList", entity: "item", columns: ["name"] });
+    });
+    const registry = createRegistry([shop, warehouse]);
+    expect(registry.getAllScreens().size).toBe(2);
+    expect(registry.getScreen("shop:screen:list")).toBeDefined();
+    expect(registry.getScreen("warehouse:screen:list")).toBeDefined();
+  });
+
+  test("getScreensByEntity groups entity-bound screens", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: { sections: [{ title: "t", fields: ["name"] }] },
+      });
+      // custom screens have no entity; they must not show up in the index.
+      r.screen({ id: "overview", type: "custom", renderer: { react: { __c: true } } });
+    });
+    const registry = createRegistry([feature]);
+    const byProduct = registry.getScreensByEntity("product");
+    expect(byProduct).toHaveLength(2);
+    // Stored screens carry the qualified id — same contract as
+    // getScreen(qn).id / getAllScreens() values. Saves ui-core the reverse
+    // index when recursing through slots / field renderers by QN.
+    expect(byProduct.map((s) => s.id).sort()).toEqual([
+      "shop:screen:product-edit",
+      "shop:screen:product-list",
+    ]);
+  });
+
+  test("getScreen / getScreensByEntity return stored screens with qualified id", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const registry = createRegistry([feature]);
+    // Input-side (unregistered FeatureDefinition) keeps the short form.
+    expect(feature.screens["product-list"]?.id).toBe("product-list");
+    // Registry-side always exposes the qualified form.
+    expect(registry.getScreen("shop:screen:product-list")?.id).toBe("shop:screen:product-list");
+  });
+
+  test("getScreensByEntity returns empty for unknown entities", () => {
+    const registry = createRegistry([]);
+    expect(registry.getScreensByEntity("ghost")).toHaveLength(0);
+  });
+});
+
+describe("validateBoot — screen validation", () => {
+  test("entityList with unknown entity fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "ghost",
+        columns: ["name"],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/references entity "ghost"/);
+  });
+
+  test("cross-feature entity-ref hint points at the real owner", () => {
+    // Entity exists, but in another feature. The hint helps the feature
+    // author realise cross-feature screen ownership isn't supported.
+    const shop = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+    });
+    const ui = defineFeature("ui", (r) => {
+      r.screen({ id: "list", type: "entityList", entity: "product", columns: ["name"] });
+    });
+    expect(() => validateBoot([shop, ui])).toThrow(/owned by feature "shop"/);
+  });
+
+  test("entityList with unknown field (string form) fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name", "mistake"],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "mistake"/);
+  });
+
+  test("entityList with unknown field (object form) fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "product",
+        columns: [{ field: "nonexistent" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "nonexistent"/);
+  });
+
+  test("entityEdit with unknown field (string form in sections) fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [{ title: "s", fields: ["name", "oops"] }],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "oops"/);
+  });
+
+  test("entityEdit with unknown field (object form in sections) fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [{ title: "s", fields: [{ field: "ghost" }] }],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "ghost"/);
+  });
+
+  test("custom screen without a renderer-component (neither react nor native) fails", () => {
+    const feature = defineFeature("dashboard", (r) => {
+      const screen: ScreenDefinition = {
+        id: "empty",
+        type: "custom",
+        renderer: {},
+      };
+      r.screen(screen);
+    });
+    expect(() => validateBoot([feature])).toThrow(/neither a react nor a native component/);
+  });
+
+  test("custom screen with just react passes", () => {
+    const feature = defineFeature("dashboard", (r) => {
+      r.screen({
+        id: "ok",
+        type: "custom",
+        renderer: { react: { __component: true } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("custom screen with just native passes (mobile-only feature)", () => {
+    const feature = defineFeature("dashboard", (r) => {
+      r.screen({
+        id: "ok",
+        type: "custom",
+        renderer: { native: { __component: true } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("fully-populated entityEdit with sections + slots + conditionals passes boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              title: "shop:section.basics",
+              columns: 2,
+              fields: ["name", { field: "sku", visible: () => true, required: () => true }],
+            },
+          ],
+        },
+        slots: { header: { react: { __component: "h" } } },
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("entityList with empty columns fails boot", () => {
+    // Blank columns list renders as a blank table — almost always an author
+    // oversight. Locked down at boot rather than silently producing an empty
+    // UI surface.
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({ id: "list", type: "entityList", entity: "product", columns: [] });
+    });
+    expect(() => validateBoot([feature])).toThrow(/empty columns list/);
+  });
+
+  test("entityEdit with empty sections fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: { sections: [] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/empty sections list/);
+  });
+
+  test("entityEdit with a section that has zero fields fails boot", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: { sections: [{ title: "shop:section.empty", fields: [] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/zero fields/);
+  });
+});

package/src/engine/__tests__/state-machine.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "vitest";
+import { UnprocessableError } from "../../errors";
+import { defineTransitions, guardTransition } from "../state-machine";
+
+describe("defineTransitions — TransitionGraph API", () => {
+  const transitions = defineTransitions({
+    draft: ["sent"],
+    sent: ["paid", "cancelled"],
+    paid: [],
+    cancelled: [],
+  });
+
+  test("canTransition: erlaubte Übergänge", () => {
+    expect(transitions.canTransition("draft", "sent")).toBe(true);
+    expect(transitions.canTransition("sent", "paid")).toBe(true);
+    expect(transitions.canTransition("sent", "cancelled")).toBe(true);
+  });
+
+  test("canTransition: verbotene Übergänge", () => {
+    expect(transitions.canTransition("draft", "paid")).toBe(false);
+    expect(transitions.canTransition("paid", "draft")).toBe(false);
+  });
+
+  test("canTransition: unbekannter from-State liefert false (kein Throw)", () => {
+    expect(transitions.canTransition("unknown" as "draft", "sent")).toBe(false);
+  });
+
+  test("allowedFrom: liefert die erlaubten Targets", () => {
+    expect(transitions.allowedFrom("sent")).toEqual(["paid", "cancelled"]);
+    expect(transitions.allowedFrom("draft")).toEqual(["sent"]);
+  });
+
+  test("allowedFrom: terminaler State → leeres Array", () => {
+    expect(transitions.allowedFrom("paid")).toEqual([]);
+  });
+
+  test("allowedFrom: unbekannter State → leeres Array", () => {
+    expect(transitions.allowedFrom("unknown" as "draft")).toEqual([]);
+  });
+
+  test("supports non-linear transitions (backtrack)", () => {
+    const t = defineTransitions({
+      draft: ["in_progress"],
+      in_progress: ["review"],
+      review: ["finalized", "in_progress"],
+      finalized: ["sent"],
+      sent: [],
+    });
+    expect(t.canTransition("review", "in_progress")).toBe(true);
+    expect(t.canTransition("review", "finalized")).toBe(true);
+  });
+});
+
+describe("assertTransition / guardTransition", () => {
+  const transitions = defineTransitions({
+    draft: ["sent"],
+    sent: ["paid", "cancelled"],
+    paid: [],
+    cancelled: [],
+  });
+
+  // assertTransition wirft UnprocessableError mit reason="invalid_transition"
+  // (HTTP 422). guardTransition ist Convenience-Wrapper mit derselben Logik —
+  // beide müssen identisch verhalten.
+
+  test("method-form: erlaubter Übergang läuft durch", () => {
+    expect(() => transitions.assertTransition("draft", "sent")).not.toThrow();
+  });
+
+  test("function-form (guardTransition): identisches Verhalten", () => {
+    expect(() => guardTransition(transitions, "draft", "sent")).not.toThrow();
+    expect(() => guardTransition(transitions, "draft", "paid")).toThrow(UnprocessableError);
+  });
+
+  test("rejects invalid transition mit details + i18nKey", () => {
+    try {
+      transitions.assertTransition("draft", "paid");
+    } catch (e) {
+      const err = e as UnprocessableError;
+      expect(err.code).toBe("unprocessable");
+      expect(err.httpStatus).toBe(422);
+      expect(err.details).toMatchObject({
+        reason: "invalid_transition",
+        from: "draft",
+        to: "paid",
+        allowed: ["sent"],
+      });
+      expect((err.details as { message: string }).message).toContain('"draft" → "paid"');
+    }
+  });
+
+  test("error details: allowed-array aus der State-Machine", () => {
+    try {
+      transitions.assertTransition("sent", "draft");
+    } catch (e) {
+      expect((e as UnprocessableError).details).toMatchObject({
+        allowed: ["paid", "cancelled"],
+      });
+    }
+  });
+
+  test("rejects transition from unknown state mit allowed=[] (leeres Array)", () => {
+    try {
+      transitions.assertTransition("unknown" as "draft", "sent");
+    } catch (e) {
+      const err = e as UnprocessableError;
+      expect(err.details).toMatchObject({ from: "unknown", allowed: [] });
+    }
+  });
+
+  test("identische details-shape zwischen assertTransition + failTransition", async () => {
+    // Beide Pfade müssen den gleichen Detail-Block bauen — Clients
+    // parsen den 422-Body uniform und dürfen kein "validTargets vs.
+    // allowed"-Branch fühlen.
+    const { failTransition } = await import("../../errors");
+    type TransitionDetails = {
+      from?: string;
+      to?: string;
+      allowed?: readonly string[];
+      message?: string;
+      reason?: string;
+    };
+    let assertDetails: TransitionDetails | undefined;
+    try {
+      transitions.assertTransition("draft", "paid");
+    } catch (e) {
+      assertDetails = (e as UnprocessableError).details as TransitionDetails;
+    }
+    // Wenn assertTransition nicht wirft (zukünftiger Bug), bleibt
+    // assertDetails undefined → Diagnose unklar. Frühzeitiger Check macht
+    // den Fehlerpfad eindeutig.
+    expect(assertDetails).toBeDefined();
+    const failResult = failTransition("draft", "paid", ["sent"]);
+    const failDetails = failResult.error.details as TransitionDetails;
+    // assertTransition wirft via UnprocessableError → details bekommt
+    // automatisch `reason` injiziert; failTransition geht denselben
+    // Pfad. Strukturelle Felder müssen 1:1 matchen.
+    expect(assertDetails?.from).toEqual(failDetails.from);
+    expect(assertDetails?.to).toEqual(failDetails.to);
+    expect(assertDetails?.allowed).toEqual(failDetails.allowed);
+    expect(assertDetails?.message).toEqual(failDetails.message);
+    expect(assertDetails?.reason).toEqual(failDetails.reason);
+  });
+
+  test("rejects transition from terminal state", () => {
+    expect(() => transitions.assertTransition("paid", "draft")).toThrow(UnprocessableError);
+  });
+});

package/src/engine/__tests__/system-user.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "vitest";
+import { hasAccess } from "../access";
+import { createApp } from "../create-app";
+import { defineFeature } from "../define-feature";
+import { createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID } from "../system-user";
+
+describe("SYSTEM_USER", () => {
+  test("createSystemUser returns user with system role", () => {
+    const user = createSystemUser("00000000-0000-4000-8000-000000000042");
+    expect(user.id).toBe(SYSTEM_USER_ID);
+    expect(user.tenantId).toBe("00000000-0000-4000-8000-000000000042");
+    expect(user.roles).toEqual([SYSTEM_ROLE]);
+  });
+
+  test("SYSTEM_USER has access to handlers with roles: ['system']", () => {
+    const user = createSystemUser("00000000-0000-4000-8000-000000000001");
+    expect(hasAccess(user, { roles: ["system"] })).toBe(true);
+  });
+
+  test("SYSTEM_USER does NOT have access to Admin-only handlers", () => {
+    const user = createSystemUser("00000000-0000-4000-8000-000000000001");
+    expect(hasAccess(user, { roles: ["Admin"] })).toBe(false);
+  });
+
+  test("normal user does NOT have access to system-only handlers", () => {
+    const admin = {
+      id: "11111111-0000-4000-8000-000000000001",
+      tenantId: "00000000-0000-4000-8000-000000000001",
+      roles: ["Admin"] as readonly string[],
+    };
+    expect(hasAccess(admin, { roles: ["system"] })).toBe(false);
+  });
+
+  test("createApp rejects 'system' as an app role", () => {
+    const feature = defineFeature("test", () => {});
+    expect(() => createApp({ roles: ["Admin", "system"] as const, features: [feature] })).toThrow(
+      /reserved.*SYSTEM_USER/i,
+    );
+  });
+
+  test("createApp allows features with write: ['system'] config keys", () => {
+    const feature = defineFeature("billing", (r) => {
+      r.config({
+        keys: {
+          monthlyTotal: {
+            type: "number",
+            default: 0,
+            scope: "tenant",
+            access: { write: ["system"], read: ["Admin"] },
+          },
+        },
+      });
+    });
+
+    expect(() => createApp({ roles: ["Admin"] as const, features: [feature] })).not.toThrow();
+  });
+});

package/src/engine/__tests__/validation-hooks.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../index";
+import type { ValidationError } from "../validation";
+import { runValidation } from "../validation";
+
+describe("validation hooks", () => {
+  test("r.hook registers validation hook", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.hook("validation", "user:create", (data) => {
+        const errors: ValidationError[] = [];
+        if (!data["email"]) errors.push({ field: "email", error: "required" });
+        return errors.length > 0 ? errors : null;
+      });
+    });
+
+    expect(feature.hooks["validation"]).toBeDefined();
+    expect(feature.hooks["validation"]?.["user:create"]).toBeDefined();
+  });
+
+  test("runValidation returns null when valid", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("validation", "user:create", () => null);
+    });
+
+    const registry = createRegistry([feature]);
+    const result = runValidation(registry, "test:write:user:create", { email: "a@b.de" });
+    expect(result).toBeNull();
+  });
+
+  test("runValidation returns errors when invalid", () => {
+    const feature = defineFeature("test", (r) => {
+      r.hook("validation", "user:create", (data) => {
+        if (!data["email"]) return [{ field: "email", error: "required" }];
+        return null;
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const result = runValidation(registry, "test:write:user:create", {});
+    expect(result).toEqual([{ field: "email", error: "required" }]);
+  });
+
+  test("runValidation scoped to feature", () => {
+    const f1 = defineFeature("a", (r) => {
+      r.hook("validation", "task:create", (data) => {
+        if (!data["name"]) return [{ field: "name", error: "required" }];
+        return null;
+      });
+    });
+    const f2 = defineFeature("b", (r) => {
+      r.hook("validation", "task:create", (data) => {
+        if (!data["age"]) return [{ field: "age", error: "required" }];
+        return null;
+      });
+    });
+
+    const registry = createRegistry([f1, f2]);
+    const resultA = runValidation(registry, "a:write:task:create", {});
+    expect(resultA).toEqual([{ field: "name", error: "required" }]);
+
+    const resultB = runValidation(registry, "b:write:task:create", {});
+    expect(resultB).toEqual([{ field: "age", error: "required" }]);
+  });
+
+  test("runValidation returns null for unknown hook", () => {
+    const feature = defineFeature("test", () => {});
+    const registry = createRegistry([feature]);
+    expect(runValidation(registry, "test:write:nonexistent", {})).toBeNull();
+  });
+});