@cosmicdrift/kumiko-framework 0.202.0 → 0.204.0

package/src/engine/__tests__/projection-detail-actions.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2166: projectionDetail screens can declare header `actions`, reusing
+// RowAction (the displayed record stands in for the row). `rowClick` has no
+// row to target on a detail screen and is rejected outright; navigate/
+// writeHandler actions get the same existence checks as entityList/
+// projectionList rowActions/toolbarActions.
+describe("validateBoot — projectionDetail actions (fw#2166)", () => {
+  test("navigate action with rowClick: true throws, naming the screen and action", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            rowClick: true,
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "app:screen:rent-detail" \(projectionDetail\) action "edit" sets rowClick: true/,
+    );
+  });
+
+  test("valid navigate + writeHandler actions boot cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.writeHandler(
+        "archive",
+        z.object({ id: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          { kind: "navigate", id: "edit", label: "actions.edit", screen: "rent-edit" },
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:archive",
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate action to an unregistered screen throws, via the same existence check as entityList/projectionList", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [{ kind: "navigate", id: "edit", label: "actions.edit", screen: "ghost-screen" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "edit" navigate-target "ghost-screen" does not resolve to a registered screen/,
+    );
+  });
+
+  test("navigate action with params targeting an entityEdit of the SAME entity (via detailFor) throws — params are a no-op on an update target (review finding 3b)", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("rent", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        detailFor: "rent",
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /rowAction "edit" sets params on navigate-target "rent-edit" which resolves to UPDATE mode \(same entity "rent" auto-fills row\["id"\]\)/,
+    );
+  });
+
+  test("writeHandler action referencing an unregistered handler QN throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:ghost",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "archive" handler "app:write:ghost" is not a registered write-handler/,
+    );
+  });
+});

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

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
+import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
 import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
@@ -165,6 +167,196 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).toThrow(/extension section/i);
   });
 
+  test("validateBoot rejects a projectionDetail relatedList section with an empty query (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [{ kind: "relatedList", title: "s", query: "", columns: ["name"] }],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /Screen "x".*relatedList.*empty or non-string query/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList rowClick with no matching detailFor screen (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /Add detailFor: "invoice" to the screen that shows it\./,
+    );
+  });
+
+  test("validateBoot accepts a relatedList rowClick with a detailFor screen in another feature (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+              },
+            ],
+          },
+        });
+      }),
+      defineFeature("billing", (r) => {
+        r.entity(
+          "invoice",
+          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+        );
+        r.screen({
+          id: "invoice-detail",
+          type: "custom",
+          renderer: { react: { __component: "stub" } },
+          detailFor: "invoice",
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section in a wizard layout (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            mode: "wizard",
+            sections: [
+              { kind: "relatedList", title: "s", query: "app:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/relatedList.*wizard layout/);
+  });
+
+  test("validateBoot accepts a valid relatedList section without rowClick (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "app:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(entityEdit\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList section on configEdit (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.config({
+          keys: { "site-name": createTenantConfig("text", { default: "" }) },
+        });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { siteName: "shop:config:site-name" },
+          fields: { siteName: { type: "text" } } as never,
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(configEdit\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList section on actionForm (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(actionForm\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/action-wiring.ts

@@ -1,4 +1,4 @@
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import { isFieldsEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type {
   EditFieldSpec,
   EditLayout,
@@ -29,7 +29,7 @@ const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as c
 function validateActionNoFunctions(
   featureName: string,
   screenId: string,
-  actionKind: "rowAction" | "toolbarAction",
+  actionKind: "rowAction" | "toolbarAction" | "action",
   action: RowAction | ToolbarAction,
 ): void {
   const record = action as unknown as Record<string, unknown>;
@@ -45,6 +45,12 @@ function validateActionNoFunctions(
 
 export function validateActionWiring(feature: FeatureDefinition): void {
   for (const screen of Object.values(feature.screens)) {
+    if (screen.type === "projectionDetail") {
+      for (const action of screen.actions ?? []) {
+        validateActionNoFunctions(feature.name, screen.id, "action", action);
+      }
+      continue;
+    }
     if (screen.type !== "entityList" && screen.type !== "projectionList") continue;
     for (const action of screen.rowActions ?? []) {
       validateActionNoFunctions(feature.name, screen.id, "rowAction", action);
@@ -106,7 +112,13 @@ function validateEditLayoutNoFunctions(
   layout: EditLayout,
 ): void {
   for (const section of layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    // relatedList carries `columns` instead of `fields` — route it through
+    // the same column check entityList/projectionList top-level columns use.
+    if (section.kind === "relatedList") {
+      validateColumnsNoFunctions(featureName, screenId, screenType, section.columns);
+      continue;
+    }
+    if (!isFieldsEditSection(section)) continue;
     for (const fieldSpec of section.fields) {
       validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
     }

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

@@ -45,6 +45,7 @@ import {
 } from "./nav";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
+import { validateProjectionListScreens } from "./projection-list-screens";
 import {
   collectScreenQns,
   collectScreensByShortId,
@@ -210,6 +211,7 @@ export function validateBoot(
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
   validateDetailForScreens(features, featureMap);
+  validateProjectionListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);

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

@@ -0,0 +1,82 @@
+import { ZodObject } from "zod";
+import { QnTypes, qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, ProjectionListScreenDefinition, QueryHandlerDef } from "../types";
+import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
+
+// Sibling to entity-list-screens.ts rather than an extension of it:
+// validateOneEntityListScreen is typed to EntityListScreenDefinition and
+// reaches into feature.entities[screen.entity] — a projectionList has no
+// entity, so sharing the function would mean threading a discriminated
+// union through every entity-bound helper it calls.
+
+function buildQueryHandlerMap(
+  features: readonly FeatureDefinition[],
+): ReadonlyMap<string, QueryHandlerDef> {
+  const out = new Map<string, QueryHandlerDef>();
+  for (const feature of features) {
+    for (const [name, handler] of Object.entries(feature.queryHandlers ?? {})) {
+      out.set(qualifyEntityName(feature.name, QnTypes.query, name), handler);
+    }
+  }
+  return out;
+}
+
+// Non-ZodObject schemas (e.g. a z.union across payload shapes) and
+// unresolved query handlers both fall through to "capability absent" —
+// consistent with buildAppSchema's derivation, no throw either way.
+function schemaAccepts(schema: QueryHandlerDef["schema"] | undefined, key: string): boolean {
+  const shape = schema instanceof ZodObject ? schema.shape : undefined;
+  return shape !== undefined && key in shape;
+}
+
+function validateOneProjectionListScreen(
+  feature: FeatureDefinition,
+  screen: ProjectionListScreenDefinition,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+): void {
+  const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
+  const schema = queryHandlers.get(screen.query)?.schema;
+
+  if (screen.searchable === true && !schemaAccepts(schema, "search")) {
+    throw new Error(
+      `${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema`,
+    );
+  }
+
+  if (
+    screen.searchable === false &&
+    schemaAccepts(schema, "search") &&
+    !SEARCHABLE_FALSE_WHITELIST.has(screen.id)
+  ) {
+    throw new Error(
+      `${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`,
+    );
+  }
+
+  // sortable/paginated are derived by buildAppSchema from the query's Zod
+  // schema (fw#2165) — there is no separate wire type from the author-facing
+  // ProjectionListScreenDefinition, so hand-authoring them would otherwise be
+  // silently overwritten with no signal to the author. Reject outright.
+  if (screen.sortable !== undefined) {
+    throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
+  }
+  if (screen.paginated !== undefined) {
+    throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
+  }
+
+  const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
+  const sortActive = schemaAccepts(schema, "sort");
+  if ((searchActive || sortActive) && screen.defaultSort === undefined) {
+    throw new Error(`${prefix}: defaultSort required when search or sort is active`);
+  }
+}
+
+export function validateProjectionListScreens(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      if (screen.type !== "projectionList") continue;
+      validateOneProjectionListScreen(feature, screen, queryHandlers);
+    }
+  }
+}

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

@@ -67,7 +67,7 @@ function validateNoWidgetRequiredField(
 function validateRowActionNavigateParams(
   featureName: string,
   screenId: string,
-  screenType: "entityList" | "projectionList",
+  screenType: "entityList" | "projectionList" | "projectionDetail",
   screenEntity: string | undefined,
   action: RowAction,
   target: { readonly featureName: string; readonly screen: ScreenDefinition } | undefined,
@@ -381,6 +381,35 @@ export function validateScreens(
               `section to persist against.`,
           );
         }
+        if (section.kind === "relatedList") {
+          if (!section.query || typeof section.query !== "string") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(relatedList) has empty or non-string query.`,
+            );
+          }
+          if (screen.layout.mode === "wizard") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `is kind "relatedList" in a wizard layout — a read-only list is not supported in a ` +
+                `stepped form. Remove mode: "wizard" or drop the relatedList section.`,
+            );
+          }
+          if (section.rowClick !== undefined) {
+            const targetEntity = section.rowClick.entity;
+            const hasDetailScreen = [...featureMap.values()].some((f) =>
+              Object.values(f.screens).some((s) => s.detailFor === targetEntity),
+            );
+            if (!hasDetailScreen) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) rowClick targets entity "${targetEntity}", but no screen declares ` +
+                  `detailFor: "${targetEntity}". Add detailFor: "${targetEntity}" to the screen that shows it.`,
+              );
+            }
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has a section "${section.title}" ` +
@@ -388,6 +417,47 @@ export function validateScreens(
           );
         }
       }
+      // Header actions reuse RowAction (the displayed record stands in for
+      // the row), so the same navigate/writeHandler existence checks as
+      // entityList/projectionList apply. `rowClick` is rejected outright —
+      // a detail screen has no row to click.
+      if (screen.actions !== undefined) {
+        for (const action of screen.actions) {
+          if (action.kind === "navigate" && action.rowClick === true) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
+                `(projectionDetail) action "${action.id}" sets rowClick: true — there is no row to ` +
+                `click on a detail screen. Remove rowClick.`,
+            );
+          }
+          if (action.kind === "navigate") {
+            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
+            if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
+                  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
+              );
+            }
+            const target = screensByShortId.get(action.screen)?.[0];
+            validateRowActionNavigateParams(
+              feature.name,
+              screenId,
+              "projectionDetail",
+              screen.detailFor,
+              action,
+              target,
+            );
+          } else {
+            if (!allWriteHandlerQns.has(action.handler)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
+                  `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                  `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+              );
+            }
+          }
+        }
+      }
       continue;
     }
 
@@ -433,6 +503,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -541,6 +618,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -868,6 +952,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +