@cosmicdrift/kumiko-framework 0.225.0 → 0.226.0

package/src/engine/boot-validator/query-output-columns.ts

@@ -0,0 +1,236 @@
+import type { ZodType } from "zod";
+import { isPagedQueryHandler } from "../define-handler";
+import { normalizeListColumn } from "../screen-helpers";
+import type {
+  DashboardScreenDefinition,
+  DashboardStatPanel,
+  EditLayout,
+  FeatureDefinition,
+  ListColumnSpec,
+  ProjectionDetailScreenDefinition,
+  ProjectionListScreenDefinition,
+  QueryHandlerDef,
+  ScreenDefinition,
+} from "../types";
+import { buildQueryHandlerMap } from "./projection-list-screens";
+import { getZodObjectShape, getZodRowShape } from "./zod-shape";
+
+// fw#2493: query handlers can now declare `outputSchema` (the Zod shape of
+// their actual return value). This validator is entirely opt-in and
+// additive — a handler without `outputSchema`, or one whose declared shape
+// this can't introspect (e.g. a z.union), leaves every check below a no-op,
+// same "capability absent, no throw" policy as the input-schema checks in
+// projection-list-screens.ts. Must run after validateQueryRefs (fw#2178):
+// an unresolvable query QN is that validator's job to report — by the time
+// this runs every `query` string here already resolves.
+
+type ShapeLookup = Record<string, ZodType>;
+
+function checkFieldExists(
+  shape: ShapeLookup | undefined,
+  field: string,
+  buildMessage: () => string,
+): void {
+  // skip: capability absent (no introspectable shape) or field already present — nothing to validate
+  if (shape === undefined || field in shape) return;
+  throw new Error(buildMessage());
+}
+
+// Mirrors entity-list-screens.ts's "unlabeled unknown column" convention: a
+// column with its own `label` is a virtual/computed cell drawn by a
+// renderer, not a row field — exempt from the shape check.
+function checkColumnField(
+  rowShape: ShapeLookup | undefined,
+  column: ListColumnSpec,
+  buildMessage: (field: string) => string,
+): void {
+  const normalized = normalizeListColumn(column);
+  // skip: labeled column is a virtual/computed cell drawn by a renderer, not a row field
+  if (normalized.label !== undefined) return;
+  checkFieldExists(rowShape, normalized.field, () => buildMessage(normalized.field));
+}
+
+// A paged handler (definePagedQueryHandler) whose outputSchema describes the
+// row shape directly instead of the `{ rows, nextCursor, total? }` envelope
+// would otherwise fail silently: getZodRowShape finds no "rows" key and every
+// column check above just no-ops, so the author believes columns are checked
+// when none are. Catches only the realistic mistake (envelope has no "rows"
+// field at all) — an introspectable schema that isn't even a ZodObject is
+// still "capability absent" per the module policy above.
+function checkPagedHandlerOutputSchemaShape(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+): void {
+  for (const [qn, handler] of queryHandlers) {
+    if (!isPagedQueryHandler(handler) || handler.outputSchema === undefined) continue;
+    const shape = getZodObjectShape(handler.outputSchema);
+    if (shape === undefined || "rows" in shape) continue;
+    throw new Error(
+      `Query handler "${qn}" is a paged handler (definePagedQueryHandler) but its outputSchema does not describe the paged envelope { rows: [...], nextCursor, total? } — it has no "rows" field. Did you pass the row schema instead of wrapping it in the envelope?`,
+    );
+  }
+}
+
+function checkProjectionListOutputColumns(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: ProjectionListScreenDefinition,
+): void {
+  const rowShape = getZodRowShape(queryHandlers.get(screen.query)?.outputSchema);
+  for (const column of screen.columns) {
+    checkColumnField(
+      rowShape,
+      column,
+      (field) =>
+        `[Feature ${featureName}] Screen "${screenId}" (projectionList) column "${field}" is not present in query "${screen.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`,
+    );
+  }
+}
+
+function checkEditLayoutOutputColumns(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  layout: EditLayout,
+): void {
+  for (const section of layout.sections) {
+    if (section.kind !== "relatedList") continue;
+    const rowShape = getZodRowShape(queryHandlers.get(section.query)?.outputSchema);
+    for (const column of section.columns) {
+      checkColumnField(
+        rowShape,
+        column,
+        (field) =>
+          `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" column "${field}" is not present in query "${section.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`,
+      );
+    }
+  }
+}
+
+function checkProjectionDetailOutputFields(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: ProjectionDetailScreenDefinition,
+): void {
+  const recordShape = getZodObjectShape(queryHandlers.get(screen.query)?.outputSchema);
+  const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
+  const checkHeaderField = (part: "title" | "subtitle" | "status", field: string): void => {
+    checkFieldExists(
+      recordShape,
+      field,
+      () =>
+        `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`,
+    );
+  };
+  if (screen.header !== undefined) {
+    checkHeaderField("title", screen.header.title);
+    if (screen.header.subtitle !== undefined) checkHeaderField("subtitle", screen.header.subtitle);
+    if (screen.header.status !== undefined) checkHeaderField("status", screen.header.status);
+  }
+  for (const metric of screen.metrics ?? []) {
+    checkFieldExists(
+      recordShape,
+      metric,
+      () =>
+        `${prefix} metrics references field "${metric}" which is not present in query "${screen.query}"'s outputSchema.`,
+    );
+  }
+}
+
+// Stat panels' query contract is a flat record (not the paged `{ rows }`
+// envelope) — see DashboardStatPanel's doc in screen.ts — so this checks
+// the handler's outputSchema shape directly, not its row shape.
+function checkDashboardStatPanelFields(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  panel: DashboardStatPanel,
+): void {
+  const recordShape = getZodObjectShape(queryHandlers.get(panel.query)?.outputSchema);
+  const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`;
+  const checkPanelField = (part: string, field: string | undefined): void => {
+    // skip: this stat-panel field slot is optional and wasn't declared — nothing to validate
+    if (field === undefined) return;
+    checkFieldExists(
+      recordShape,
+      field,
+      () =>
+        `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema.`,
+    );
+  };
+  checkPanelField("valueField", panel.valueField);
+  checkPanelField("subField", panel.subField);
+  checkPanelField("toneField", panel.toneField);
+  checkPanelField("deltaField", panel.deltaField);
+  checkPanelField("deltaDirectionField", panel.deltaDirectionField);
+  checkPanelField("deltaToneField", panel.deltaToneField);
+}
+
+function checkDashboardOutputFields(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: DashboardScreenDefinition,
+): void {
+  for (const panel of screen.panels) {
+    if (panel.kind === "stat") {
+      checkDashboardStatPanelFields(queryHandlers, featureName, screenId, panel);
+    } else if (panel.kind === "stat-group") {
+      for (const stat of panel.stats) {
+        checkDashboardStatPanelFields(queryHandlers, featureName, screenId, stat);
+      }
+    } else if (panel.kind === "list") {
+      const rowShape = getZodRowShape(queryHandlers.get(panel.query)?.outputSchema);
+      for (const column of panel.columns) {
+        checkColumnField(
+          rowShape,
+          column,
+          (field) =>
+            `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" column "${field}" is not present in query "${panel.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`,
+        );
+      }
+    }
+    // chart/feed/progress-list/custom panels have a fixed query-result
+    // contract with no author-declared field names to check.
+  }
+}
+
+function checkScreenOutputColumns(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: ScreenDefinition,
+): void {
+  if (screen.type === "projectionList") {
+    checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen);
+  } else if (screen.type === "projectionDetail") {
+    checkProjectionDetailOutputFields(queryHandlers, featureName, screenId, screen);
+    checkEditLayoutOutputColumns(
+      queryHandlers,
+      featureName,
+      screenId,
+      "projectionDetail",
+      screen.layout,
+    );
+  } else if (
+    screen.type === "entityEdit" ||
+    screen.type === "actionForm" ||
+    screen.type === "configEdit"
+  ) {
+    checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screen.type, screen.layout);
+  } else if (screen.type === "dashboard") {
+    checkDashboardOutputFields(queryHandlers, featureName, screenId, screen);
+  }
+}
+
+export function validateQueryOutputColumns(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  checkPagedHandlerOutputSchemaShape(queryHandlers);
+  for (const feature of features) {
+    for (const [screenId, screen] of Object.entries(feature.screens)) {
+      checkScreenOutputColumns(queryHandlers, feature.name, screenId, screen);
+    }
+  }
+}

package/src/engine/boot-validator/zod-shape.ts

@@ -0,0 +1,51 @@
+import { ZodArray, ZodDefault, ZodNullable, ZodObject, ZodOptional, type ZodType } from "zod";
+
+// Drills through wrapper types (.nullable(), .optional(), .default()) a
+// handler's schema may use around its actual object/array shape — e.g. a
+// detail query returning `Row | null` when the record doesn't exist.
+// Bounded to avoid looping on a pathological schema.
+function unwrapZodType(schema: ZodType): ZodType {
+  let current: ZodType = schema;
+  for (let i = 0; i < 8; i++) {
+    if (
+      current instanceof ZodOptional ||
+      current instanceof ZodNullable ||
+      current instanceof ZodDefault
+    ) {
+      // @cast-boundary schema-walk — Zod v4's .unwrap() types its result as
+      // the core $ZodType, not the z.ZodType wrapper; same runtime instance
+      // (see env/_zod-introspect.ts for the same drill on ZodDefault/Optional).
+      current = current.unwrap() as ZodType;
+      continue;
+    }
+    break;
+  }
+  return current;
+}
+
+// Non-ZodObject schemas (e.g. a z.union across payload shapes) and an
+// absent schema both fall through to "shape unknown" — callers treat that
+// as "capability absent" and skip the check rather than throwing, the same
+// policy projection-list-screens.ts already uses for input-schema checks.
+export function getZodObjectShape(
+  schema: ZodType | undefined,
+): Record<string, ZodType> | undefined {
+  if (schema === undefined) return undefined;
+  const unwrapped = unwrapZodType(schema);
+  return unwrapped instanceof ZodObject ? unwrapped.shape : undefined;
+}
+
+// The shape of one row for a query whose result follows the paged-list
+// contract `{ rows: T[], nextCursor, total? }` (projectionList/relatedList/
+// dashboard-list `query`) — unwraps `rows` (a ZodArray) to its element
+// schema, then that element's own shape.
+export function getZodRowShape(schema: ZodType | undefined): Record<string, ZodType> | undefined {
+  const objectShape = getZodObjectShape(schema);
+  const rowsField = objectShape?.["rows"];
+  if (rowsField === undefined) return undefined;
+  const rowsArray = unwrapZodType(rowsField);
+  // @cast-boundary schema-walk — same core-vs-wrapper gap as .unwrap() above.
+  return rowsArray instanceof ZodArray
+    ? getZodObjectShape(rowsArray.element as ZodType)
+    : undefined;
+}

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

@@ -397,17 +397,21 @@ function projectDerivedField(derivedDef: DerivedFieldDef): ClientDerivedFieldDef
   return { valueType: derivedDef.valueType };
 }
 
-// Whitelist pro Field. `default` darf nur durch wenn Literal (string/
-// number/boolean/null) — auch wenn die FieldDefinition-Types „default"
-// nur als Literal typisieren, hat das Sample-Pattern
-// `as unknown as EntityDefinition` Authorinnen schon Function-Defaults
-// reinschmuggeln lassen. Diese Defense-in-Depth fängt sie ab BEVOR
-// JSON.stringify sie in der Browser-Injection-Pipeline droppt.
+// Per-field whitelist. Every forwarded value must be JSON-safe (literal, or
+// an array/plain-object built only from JSON-safe values) — even though the
+// FieldDefinition types only type `default` as a literal, the sample-authoring
+// pattern `as unknown as EntityDefinition` has already let function-valued
+// defaults slip through. This whitelist is defense-in-depth that catches them
+// BEFORE JSON.stringify silently drops them in the browser-injection pipeline.
+// The same check gates the structured properties below (`multiline`,
+// `derived`, `totals`, `totalsMatch`) — a top-level `Array.isArray`/plain-
+// object check alone would let a function survive one level deep.
 //
-// Cast am Exit `as FieldDefinition`: type-system-wise erfüllt unsere
-// Out-Map die Discriminated-Union nur mit unverengtem `type`-String —
-// der Cast bridged die Variant-Inferenz, die TS aus einem Generic
-// Record nicht zurückrechnet.
+// Cast at the exit `as FieldDefinition`: type-system-wise our out-map only
+// satisfies the discriminated union with an unnarrowed `type` string — the
+// cast bridges the variant inference TS can't recompute from a generic
+// Record.
+// kumiko-lint-ignore complexity-budget flat per-property whitelist walk, one independent `if` per FieldDefinition property — same shape as schema-builder.ts's field→zod switch
 function projectField(fieldDef: FieldDefinition): FieldDefinition {
   const def = fieldDef as Record<string, unknown>; // @cast-boundary schema-walk
   const out: Record<string, unknown> = {};
@@ -418,7 +422,7 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   // boolean) — muss daher ins Client-Schema.
   if (typeof def["filterable"] === "boolean") out["filterable"] = def["filterable"];
   if (typeof def["searchable"] === "boolean") out["searchable"] = def["searchable"];
-  if (isLiteral(def["default"])) out["default"] = def["default"];
+  if (isJsonSafeValue(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];
   // Reference: entity-Target + labelField + multiple müssen zum Renderer.
@@ -434,11 +438,44 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (typeof def["display"] === "string") out["display"] = def["display"];
   if (typeof def["columns"] === "number") out["columns"] = def["columns"];
   if (typeof def["maxRows"] === "number") out["maxRows"] = def["maxRows"];
+  // text/longText: textarea row count — DefaultInput renders a single-line
+  // input otherwise (fw#2497).
+  if (
+    typeof def["multiline"] === "boolean" ||
+    (isPlainObject(def["multiline"]) && isJsonSafeValue(def["multiline"]))
+  )
+    out["multiline"] = def["multiline"];
+  // number: Zod write-boundary bounds. date/timestamp/locatedTimestamp:
+  // ISO-string picker bounds — same keys, different literal type (fw#2497).
+  if (typeof def["min"] === "number" || typeof def["min"] === "string") out["min"] = def["min"];
+  if (typeof def["max"] === "number" || typeof def["max"] === "string") out["max"] = def["max"];
+  // date/timestamp/locatedTimestamp: display/parsing locale override (fw#2497).
+  if (typeof def["locale"] === "string") out["locale"] = def["locale"];
+  // image: which camera a mobile capture opens (fw#2497).
+  if (typeof def["capture"] === "string") out["capture"] = def["capture"];
+  // embedded lists: row-count bounds, computed cells, totals row, and the
+  // sibling-money-field totals check (fw#2497).
+  if (typeof def["minItems"] === "number") out["minItems"] = def["minItems"];
+  if (typeof def["maxItems"] === "number") out["maxItems"] = def["maxItems"];
+  if (isPlainObject(def["derived"]) && isJsonSafeValue(def["derived"]))
+    out["derived"] = def["derived"];
+  if (Array.isArray(def["totals"]) && isJsonSafeValue(def["totals"])) out["totals"] = def["totals"];
+  if (isPlainObject(def["totalsMatch"]) && isJsonSafeValue(def["totalsMatch"]))
+    out["totalsMatch"] = def["totalsMatch"];
   return out as FieldDefinition; // @cast-boundary schema-walk
 }
 
-function isLiteral(value: unknown): boolean {
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function isJsonSafeValue(value: unknown): boolean {
   if (value === null) return true;
   const t = typeof value;
-  return t === "string" || t === "number" || t === "boolean";
+  if (t === "string" || t === "number" || t === "boolean") return true;
+  if (Array.isArray(value)) return value.every(isJsonSafeValue);
+  if (isPlainObject(value)) return Object.values(value).every(isJsonSafeValue);
+  return false;
 }

package/src/engine/feature-entity-handlers.ts

@@ -144,7 +144,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | QueryHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: QueryHandlerFn<z.infer<TSchema>>,
-      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+      options?: { access?: AccessRule; rateLimit?: RateLimitOption; outputSchema?: ZodType },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -155,6 +155,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
           ...(def.access && { access: def.access }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          ...(def.outputSchema && { outputSchema: def.outputSchema }),
           // Carry the definePagedQueryHandler brand through — this rebuild
           // drops any field not explicitly listed.
           ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
@@ -170,6 +171,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         handler: handler as QueryHandlerFn, // @cast-boundary engine-bridge
         ...(options?.access && { access: options.access }),
         ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+        ...(options?.outputSchema && { outputSchema: options.outputSchema }),
       };
       tryMapEntity(state, name, nameOrDef);
       return { name: nameOrDef };