@cosmicdrift/kumiko-framework 0.225.0 → 0.227.0

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

@@ -354,16 +354,15 @@ describe("buildAppSchema", () => {
     // Bounded completeness check, scoped to MultiSelectFieldDef's own key set
     // (packages/types/src/fields.ts) — NOT a general FieldDefinition lockstep.
     // A full-union version would have to classify every property of all 20
-    // FieldDefinition variants as forwarded or server-only, and several are
-    // known-forwarded-but-missing today (e.g. image's `capture`, embedded's
-    // `schema`/`derived`/`totals`/`minItems`/`maxItems`, date's
-    // `min`/`max`/`locale`, longText's `multiline`) — declaring those
-    // "server-only" here would be a false claim, and fixing them is out of
-    // scope for fw#2494 (see report for the full gap list). This check only
-    // covers the type this fix actually touches.
+    // FieldDefinition variants as forwarded or server-only. fw#2497 closed the
+    // gaps fw#2494 flagged for other variants (image's `capture`, embedded's
+    // `derived`/`totals`/`totalsMatch`/`minItems`/`maxItems`, date's
+    // `min`/`max`/`locale`, longText's `multiline`, array/object `default`) —
+    // see the dedicated tests below. This check only covers the type this fix
+    // actually touches.
     //
     // The `_allKeysClassified` assignment below is the actual guard: if
-    // MultiSelectFieldDef ever gains a key that isn't in one of the three
+    // MultiSelectFieldDef ever gains a key that isn't in one of the two
     // lists, `Exclude<keyof MultiSelectFieldDef, Classified>` stops being
     // `never` and the assignment fails to typecheck — `bun run typecheck`
     // (part of `bun run kumiko check`) catches it even without touching this
@@ -376,6 +375,9 @@ describe("buildAppSchema", () => {
       "display",
       "columns",
       "maxRows",
+      "default", // array-valued for multiSelect — projectField's
+      // isJsonSafeValue() (fw#2497) now recurses into arrays/plain
+      // objects instead of only string/number/boolean/null.
     ] as const;
 
     const SERVER_ONLY_KEYS = [
@@ -390,20 +392,7 @@ describe("buildAppSchema", () => {
       "subjectRef", // GDPR-hook-coverage marker, not a renderer concern
     ] as const;
 
-    // Keys that ARE client-relevant in principle but aren't forwarded today —
-    // pre-existing gaps, each with its own reason, none introduced by fw#2494.
-    const KNOWN_GAP_KEYS = [
-      "default", // array-valued for multiSelect, but projectField's isLiteral()
-      // only accepts string/number/boolean/null — so array defaults are
-      // silently dropped, never a real server-only property. Verified
-      // empirically: a multiSelect field with `default: ["a"]` projects to
-      // no `default` key at all. Separate pre-existing bug, out of scope here.
-    ] as const;
-
-    type Classified =
-      | (typeof FORWARDED_KEYS)[number]
-      | (typeof SERVER_ONLY_KEYS)[number]
-      | (typeof KNOWN_GAP_KEYS)[number];
+    type Classified = (typeof FORWARDED_KEYS)[number] | (typeof SERVER_ONLY_KEYS)[number];
     const _allKeysClassified: Exclude<keyof MultiSelectFieldDef, Classified> extends never
       ? true
       : never = true;
@@ -415,6 +404,7 @@ describe("buildAppSchema", () => {
           required: true,
           filterable: true,
           options: ["a", "b"],
+          default: ["a"],
           display: "checkboxes",
           columns: 2,
           maxRows: 4,
@@ -449,6 +439,209 @@ describe("buildAppSchema", () => {
     }
   });
 
+  test("text/longText: multiline überlebt die Projection (fw#2497)", () => {
+    // Regression: without `multiline` in the client schema, DefaultInput
+    // always renders a single-line <input> — the textarea row count never
+    // arrives.
+    const entity = {
+      fields: {
+        notes: { type: "text", multiline: { rows: 6 } },
+        bio: { type: "text", multiline: true },
+        title: { type: "text" },
+        body: { type: "longText", multiline: true },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["notes"]?.["multiline"]).toEqual({ rows: 6 });
+    expect(fields["bio"]?.["multiline"]).toBe(true);
+    expect(fields["body"]?.["multiline"]).toBe(true);
+    // Fields without multiline don't carry the key (no false-litter).
+    expect(fields["title"]?.["multiline"]).toBeUndefined();
+  });
+
+  test("number/date/timestamp/locatedTimestamp: min/max/locale überleben die Projection (fw#2497)", () => {
+    // Regression: input bounds and locale overrides never arrived at the
+    // renderer, so the browser's own range validation and date-picker
+    // formatting were always off.
+    const entity = {
+      fields: {
+        quantity: { type: "number", min: 0, max: 100 },
+        birthday: { type: "date", min: "1900-01-01", max: "2026-08-28", locale: "de-DE" },
+        startedAt: {
+          type: "timestamp",
+          min: "2020-01-01T00:00:00Z",
+          max: "2030-01-01T00:00:00Z",
+          locale: "de-DE",
+        },
+        pickupAt: {
+          type: "locatedTimestamp",
+          min: "2020-01-01T00:00:00",
+          max: "2030-01-01T00:00:00",
+          locale: "de-DE",
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["quantity"]?.["min"]).toBe(0);
+    expect(fields["quantity"]?.["max"]).toBe(100);
+    expect(fields["birthday"]?.["min"]).toBe("1900-01-01");
+    expect(fields["birthday"]?.["max"]).toBe("2026-08-28");
+    expect(fields["birthday"]?.["locale"]).toBe("de-DE");
+    expect(fields["startedAt"]?.["min"]).toBe("2020-01-01T00:00:00Z");
+    expect(fields["startedAt"]?.["locale"]).toBe("de-DE");
+    expect(fields["pickupAt"]?.["max"]).toBe("2030-01-01T00:00:00");
+    expect(fields["pickupAt"]?.["locale"]).toBe("de-DE");
+  });
+
+  test("image: capture überlebt die Projection (fw#2497)", () => {
+    // Regression: `capture` decides whether a mobile file picker opens the
+    // rear or front camera — never arrived, so it never applied.
+    const entity = {
+      fields: {
+        idPhoto: { type: "image", capture: "environment" },
+        avatar: { type: "image" },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["idPhoto"]?.["capture"]).toBe("environment");
+    expect(fields["avatar"]?.["capture"]).toBeUndefined();
+  });
+
+  test("embedded: minItems/maxItems/derived/totals/totalsMatch überleben die Projection (fw#2497)", () => {
+    // Regression: `totals` carries "Renderer metadata: numeric sub-field
+    // names to sum in a totals row" in its own doc-comment but was never
+    // forwarded — same for the other embedded-list renderer hints.
+    const entity = {
+      fields: {
+        lines: {
+          type: "embedded",
+          multiple: true,
+          schema: {
+            qty: { type: "number" },
+            amount: { type: "money" },
+          },
+          minItems: 1,
+          maxItems: 20,
+          derived: { amount: { op: "multiply", from: ["qty", "unitPrice"] } },
+          totals: ["amount"],
+          totalsMatch: { amount: "invoiceTotal" },
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["lines"]?.["minItems"]).toBe(1);
+    expect(fields["lines"]?.["maxItems"]).toBe(20);
+    expect(fields["lines"]?.["derived"]).toEqual({
+      amount: { op: "multiply", from: ["qty", "unitPrice"] },
+    });
+    expect(fields["lines"]?.["totals"]).toEqual(["amount"]);
+    expect(fields["lines"]?.["totalsMatch"]).toEqual({ amount: "invoiceTotal" });
+  });
+
+  test("embedded: derived/totalsMatch mit Function eine Ebene tief bleiben blockiert (fw#2497)", () => {
+    // Regression: a shallow `isPlainObject`/`Array.isArray` check alone
+    // would let a function survive one level deep — `derived`/`totals`/
+    // `totalsMatch`/`multiline` must go through isJsonSafeValue() too, not
+    // just `default`.
+    const entity = {
+      fields: {
+        lines: {
+          type: "embedded",
+          multiple: true,
+          schema: { qty: { type: "number" } },
+          derived: { amount: { op: "multiply", from: () => ["qty"] } },
+          totals: [() => "amount"],
+          totalsMatch: { amount: () => "invoiceTotal" },
+        },
+        multi: { type: "text", multiline: { rows: () => 4 } },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["lines"]?.["derived"]).toBeUndefined();
+    expect(fields["lines"]?.["totals"]).toBeUndefined();
+    expect(fields["lines"]?.["totalsMatch"]).toBeUndefined();
+    expect(fields["multi"]?.["multiline"]).toBeUndefined();
+  });
+
+  test("default: JSON-safe Arrays/Objects überleben die Projection, Nicht-JSON-Werte bleiben blockiert (fw#2497)", () => {
+    // isJsonSafeValue() now recurses into arrays/plain objects instead of
+    // only accepting string/number/boolean/null — but the defense-in-depth
+    // against smuggled function/class-instance defaults must still hold.
+    const entity = {
+      fields: {
+        tags: { type: "multiSelect", options: ["a", "b"], default: ["a"] },
+        nested: { type: "text", default: { rows: [1, "x"], flag: true } },
+        brokenFn: { type: "text", default: () => "x" },
+        brokenClass: { type: "text", default: new Date() },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["tags"]?.["default"]).toEqual(["a"]);
+    expect(fields["nested"]?.["default"]).toEqual({ rows: [1, "x"], flag: true });
+    expect(fields["brokenFn"]?.["default"]).toBeUndefined();
+    expect(fields["brokenClass"]?.["default"]).toBeUndefined();
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

package/src/engine/__tests__/multiselect-filter.integration.test.ts

@@ -0,0 +1,141 @@
+// fw#2490: `multiSelect` fields accept `filterable: true` at boot but the
+// executor's screen-filter WHERE builder only ever emitted scalar equality
+// (`col = $1`) against the jsonb-array column — Postgres rejects that as
+// "operator does not exist: jsonb = text" the first time a filter actually
+// runs. This proves the fix over real HTTP: eq/ne/in on a filterable
+// multiSelect field must use jsonb containment (`@>`), not scalar equality.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { deriveEntityTableMeta } from "../../db/entity-table-meta";
+import { asRawClient, selectMany } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { createEntity, createMultiSelectField, createTextField } from "../factories";
+
+const equipmentEntity = createEntity({
+  table: "ms_filter_equipment",
+  fields: {
+    name: createTextField({ required: true }),
+    tags: createMultiSelectField({
+      options: ["vip", "urgent", "loaner"] as const,
+      filterable: true,
+    }),
+  },
+});
+
+const LIST_QN = "checklist:query:equipment:list";
+
+const checklistFeature = defineFeature("checklist", (r) => {
+  r.crud("equipment", equipmentEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { openToAll: true } },
+  });
+});
+
+describe("multiSelect filterable — jsonb containment, not scalar equality (fw#2490)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [checklistFeature] });
+    await unsafeCreateEntityTable(stack.db, equipmentEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "ms_filter_equipment"');
+  });
+
+  async function seed(): Promise<void> {
+    const CREATE = "checklist:write:equipment:create";
+    await stack.http.write(CREATE, { name: "Drill", tags: ["vip", "urgent"] }, TestUsers.admin);
+    await stack.http.write(CREATE, { name: "Ladder", tags: ["loaner"] }, TestUsers.admin);
+    await stack.http.write(CREATE, { name: "Saw", tags: [] }, TestUsers.admin);
+  }
+
+  test("op:eq on a multiSelect field returns rows whose array contains the value", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string; readonly tags: readonly string[] }[];
+    }>(LIST_QN, { limit: 50, filter: { field: "tags", op: "eq", value: "vip" } }, TestUsers.admin);
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]?.name).toBe("Drill");
+  });
+
+  test("op:eq with an array value returns rows whose array contains all listed values", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string }[];
+    }>(
+      LIST_QN,
+      { limit: 50, filter: { field: "tags", op: "eq", value: ["vip", "urgent"] } },
+      TestUsers.admin,
+    );
+
+    expect(result.rows.map((r) => r.name)).toEqual(["Drill"]);
+  });
+
+  test("op:ne on a multiSelect field returns rows whose array does not contain the value", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string }[];
+    }>(LIST_QN, { limit: 50, filter: { field: "tags", op: "ne", value: "vip" } }, TestUsers.admin);
+
+    expect(result.rows.map((r) => r.name).sort()).toEqual(["Ladder", "Saw"]);
+  });
+
+  test("op:in on a multiSelect field returns rows whose array contains any listed value", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string }[];
+    }>(
+      LIST_QN,
+      { limit: 50, filters: [{ field: "tags", op: "in", value: ["urgent", "loaner"] }] },
+      TestUsers.admin,
+    );
+
+    expect(result.rows.map((r) => r.name).sort()).toEqual(["Drill", "Ladder"]);
+  });
+
+  test("op:lt on a multiSelect field is unsatisfiable — empty result, no crash", async () => {
+    await seed();
+    const result = await stack.http.queryOk<{
+      readonly rows: readonly { readonly name: string }[];
+    }>(LIST_QN, { limit: 50, filter: { field: "tags", op: "lt", value: "vip" } }, TestUsers.admin);
+
+    expect(result.rows).toHaveLength(0);
+  });
+
+  // The issue's own diagnosis (fw#2490) points at buildWhereClause in
+  // bun-db/query.ts, not the screen-filter path above — that generic query
+  // API is what direct app/handler code hits when it filters a multiSelect
+  // column without going through a screen filter. Same jsonb-array bug,
+  // separate WHERE-builder, must be covered independently.
+  describe("generic selectMany() query API (bun-db/query.ts buildWhereClause)", () => {
+    const meta = deriveEntityTableMeta("equipment", equipmentEntity);
+
+    test("scalar equality uses jsonb containment, not `=`", async () => {
+      await seed();
+      const rows = await selectMany<{ name: string }>(stack.db, meta, { tags: "vip" });
+      expect(rows.map((r) => r.name).sort()).toEqual(["Drill"]);
+    });
+
+    test("`ne` returns rows whose array does not contain the value", async () => {
+      await seed();
+      const rows = await selectMany<{ name: string }>(stack.db, meta, { tags: { ne: "vip" } });
+      expect(rows.map((r) => r.name).sort()).toEqual(["Ladder", "Saw"]);
+    });
+
+    test("`in` returns rows whose array contains any listed value", async () => {
+      await seed();
+      const rows = await selectMany<{ name: string }>(stack.db, meta, {
+        tags: { in: ["urgent", "loaner"] },
+      });
+      expect(rows.map((r) => r.name).sort()).toEqual(["Drill", "Ladder"]);
+    });
+  });
+});

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

@@ -149,7 +149,31 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).toThrow(/zero fields/i);
   });
 
-  test("validateBoot rejects a projectionDetail with an extension section (no entity to persist against)", () => {
+  test("validateBoot rejects a projectionDetail extension section with contributesToFormSubmit: true (read-only screen, solon#264)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "extension",
+                title: "s",
+                component: { react: { __component: "c" } },
+                entityName: "lease",
+                contributesToFormSubmit: true,
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/no form submit to contribute to/i);
+  });
+
+  test("validateBoot rejects a projectionDetail extension section without entityName", () => {
     const features = [
       defineFeature("app", (r) => {
         r.screen({
@@ -164,7 +188,49 @@ describe("r.screen() — registration", () => {
         });
       }),
     ];
-    expect(() => validateBoot(features)).toThrow(/extension section/i);
+    expect(() => validateBoot(features)).toThrow(/has no entityName/i);
+  });
+
+  test("validateBoot rejects a projectionDetail extension section with no component", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [{ kind: "extension", title: "s", component: {}, entityName: "lease" }],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/has no component/i);
+  });
+
+  test("validateBoot boots a projectionDetail extension section without contributesToFormSubmit (self-persisting, solon#264)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "extension",
+                title: "s",
+                component: { react: { __component: "c" } },
+                entityName: "lease",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
   });
 
   test("validateBoot rejects a projectionDetail relatedList section with an empty query (fw#2166)", () => {

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

@@ -46,6 +46,7 @@ import {
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import { validateProjectionListScreens } from "./projection-list-screens";
+import { validateQueryOutputColumns } from "./query-output-columns";
 import { validateQueryRefs } from "./query-refs";
 import {
   collectScreenQns,
@@ -222,6 +223,9 @@ export function validateBoot(
   // misleading "no search parameter in its Zod schema" error instead of
   // the clear typo message below.
   validateQueryRefs(features);
+  // Must also run after validateQueryRefs — column/field checks below
+  // assume every `query` string already resolves to a registered handler.
+  validateQueryOutputColumns(features);
   validateProjectionListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);

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

@@ -1,7 +1,7 @@
-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";
+import { getZodObjectShape } from "./zod-shape";
 
 // Sibling to entity-list-screens.ts rather than an extension of it:
 // validateOneEntityListScreen is typed to EntityListScreenDefinition and
@@ -27,7 +27,7 @@ export function buildQueryHandlerMap(
 // 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;
+  const shape = getZodObjectShape(schema);
   return shape !== undefined && key in shape;
 }