@cosmicdrift/kumiko-framework 0.290.0 → 0.292.0

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

@@ -2506,6 +2506,116 @@ describe("boot-validator", () => {
       );
     });
 
+    // fw#2839: an actionForm has no entity, so a money field there can't
+    // inherit entity.defaultCurrency — undeclared, the renderer seeds a bare
+    // `0` and the handler's zod schema rejects the submit.
+    describe("money field currency source (fw#2839)", () => {
+      const moneyForm = (currency?: unknown) =>
+        makeFeature({
+          fields: { amount: { type: "money", ...(currency !== undefined && { currency }) } },
+          sections: [{ title: "Payment", fields: ["amount"] }],
+        });
+
+      test("money field ohne currency → Throw, nennt Screen und Feld", () => {
+        expect(() => validateBoot([moneyForm()])).toThrow(
+          /Screen "approve-invoice" \(actionForm\) money field "amount" must declare where its currency comes from/,
+        );
+      });
+
+      test("Fehlermeldung nennt beide gültigen Formen wörtlich", () => {
+        expect(() => validateBoot([moneyForm()])).toThrow(
+          /currency: \{ kind: "literal", code: "EUR" \}[\s\S]*currency: \{ kind: "tenant" \}/,
+        );
+      });
+
+      test("currency: { kind: 'literal', code } → kein Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "literal", code: "EUR" })])).not.toThrow();
+      });
+
+      test("currency: { kind: 'tenant' } → kein Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "tenant" })])).not.toThrow();
+      });
+
+      test("literal mit leerem code → Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "literal", code: "  " })])).toThrow(
+          /empty or non-string `code`/,
+        );
+      });
+
+      test("unbekannter kind → Throw", () => {
+        expect(() => validateBoot([moneyForm({ kind: "entityDefault" })])).toThrow(
+          /unknown currency kind "entityDefault"/,
+        );
+      });
+
+      test("non-money Felder bleiben unberührt", () => {
+        expect(() => validateBoot([makeFeature()])).not.toThrow();
+      });
+
+      // The check sits in validateFormFieldsMap, the walk actionForm,
+      // secretMint and secretMint's confirm step all share.
+      function mintFeature(
+        fields: Record<string, unknown>,
+        confirmFields?: Record<string, unknown>,
+      ) {
+        return defineFeature("shop", (r) => {
+          r.writeHandler({
+            name: "token:mint",
+            schema: { _type: "stub" } as never,
+            handler: async () => ({ isSuccess: true, data: {} }) as never,
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.screen({
+            id: "mint-token",
+            type: "secretMint",
+            handler: "shop:write:token:mint",
+            fields: fields as never,
+            layout: { sections: [{ title: "Mint", fields: Object.keys(fields) }] as never },
+            reveal: { fields: [{ field: "token", label: "Token" }] },
+            ...(confirmFields !== undefined && {
+              confirm: {
+                handler: "shop:write:token:mint",
+                fields: confirmFields as never,
+                layout: {
+                  sections: [{ title: "Confirm", fields: Object.keys(confirmFields) }] as never,
+                },
+              },
+            }),
+          });
+        });
+      }
+
+      test("secretMint money field ohne currency → Throw", () => {
+        expect(() => validateBoot([mintFeature({ fee: { type: "money" } })])).toThrow(
+          /Screen "mint-token" \(secretMint\) money field "fee" must declare where its currency comes from/,
+        );
+      });
+
+      test("secretMint confirm-Step money field ohne currency → Throw", () => {
+        expect(() =>
+          validateBoot([
+            mintFeature(
+              { fee: { type: "money", currency: { kind: "literal", code: "EUR" } } },
+              { topUp: { type: "money" } },
+            ),
+          ]),
+        ).toThrow(
+          /Screen "mint-token" \(secretMint confirm\) money field "topUp" must declare where its currency comes from/,
+        );
+      });
+
+      test("secretMint mit deklarierten Quellen in beiden Steps → kein Throw", () => {
+        expect(() =>
+          validateBoot([
+            mintFeature(
+              { fee: { type: "money", currency: { kind: "literal", code: "EUR" } } },
+              { topUp: { type: "money", currency: { kind: "tenant" } } },
+            ),
+          ]),
+        ).not.toThrow();
+      });
+    });
+
     test("layout.sections leer → Throw", () => {
       expect(() => validateBoot([makeFeature({ sections: [] })])).toThrow(
         /has an empty sections list/,
@@ -3846,6 +3956,122 @@ describe("boot-validator", () => {
       );
     });
 
+    test("reference optionsQuery naming a registered handler → kein Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.queryHandler({
+            name: "customer:options",
+            schema: z.object({}),
+            handler: async () => ({ rows: [] }) as never,
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: {
+                  type: "reference",
+                  entity: "customer",
+                  optionsQuery: "shop:query:customer:options",
+                },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("reference optionsQuery auf unregistrierten Handler → Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: {
+                  type: "reference",
+                  entity: "customer",
+                  optionsQuery: "shop:query:customer:typo",
+                },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "customerId" on entity "order" declares optionsQuery "shop:query:customer:typo" which is not a registered query-handler/,
+      );
+    });
+
+    test("leerer optionsQuery → Throw (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "customer",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "customer");
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                customerId: { type: "reference", entity: "customer", optionsQuery: "" },
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/has an empty optionsQuery/);
+    });
+
+    test("reference sub-field optionsQuery auf unregistrierten Handler → Throw mit parent.child-Pfad (fw#2780)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "product",
+            createEntity({
+              fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+            }),
+          );
+          stubListHandler(r, "product");
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({
+                  productId: {
+                    type: "reference",
+                    entity: "product",
+                    optionsQuery: "shop:query:product:typo",
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /Reference field "lines\.productId" on entity "invoice" declares optionsQuery "shop:query:product:typo"/,
+      );
+    });
+
     test("reference sub-field labelField referencing an unknown field → Throw with the parent.child field path", () => {
       const features = [
         defineFeature("shop", (r) => {

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

@@ -644,6 +644,24 @@ describe("buildAppSchema", () => {
     expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
   });
 
+  test("money field's `currency: { kind: 'literal', code }` declaration survives the projection (fw#2839)", () => {
+    const entity = {
+      defaultCurrency: "USD",
+      fields: { price: { type: "money", currency: { kind: "literal", code: "USD" } } },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projected = app.features[0]!.entities["thing"] as unknown as {
+      fields: Record<string, Record<string, unknown>>;
+    };
+
+    expect(projected.fields["price"]?.["currency"]).toEqual({ kind: "literal", code: "USD" });
+    expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
+  });
+
   test("text format, timestamp locatedBy, file accept/maxSize, image variants and decimal scale survive the projection", () => {
     // Regression: all of these are read by the edit view-model (password
     // masking, wall-clock input, upload constraints, preview variant, derived

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

@@ -909,6 +909,45 @@ describe("createRegistry", () => {
     ]);
   });
 
+  test("optionsQuery leaves searchable/sortable on the labelField column (fw#2780)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "Customers",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.queryHandler("customer:options", z.object({}), async () => [], {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              optionsQuery: "crm:query:customer:options",
+              searchable: true,
+              sortable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getSortableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+    expect(registry.getSearchableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+  });
+
   test("throws at boot when a sortable reference field has no explicit labelField (fw#2741)", () => {
     const feature = defineFeature("crm", (r) => {
       r.entity(
@@ -1204,6 +1243,54 @@ describe("createApp", () => {
     );
   });
 
+  // fw#2839: a literal currency source is only meaningful for a code the app
+  // knows — a typo would otherwise render and submit an unformattable amount.
+  function literalCurrencyFeature(code: string) {
+    return defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          defaultCurrency: "EUR",
+          fields: { total: { type: "money", currency: { kind: "literal", code } } },
+        } as never),
+      );
+    });
+  }
+
+  test("rejects currency: { kind: 'literal' } with a code outside the currencies list", () => {
+    expect(() =>
+      createApp({ roles: ["Admin"], features: [literalCurrencyFeature("EURO")] }),
+    ).toThrow(/code: "EURO" \} which is not in the currencies list/);
+  });
+
+  test("accepts currency: { kind: 'literal' } with a code from the currencies list", () => {
+    expect(() =>
+      createApp({ roles: ["Admin"], features: [literalCurrencyFeature("EUR")] }),
+    ).not.toThrow();
+  });
+
+  test("rejects an unknown literal code on an actionForm screen field too", () => {
+    const feature = defineFeature("test", (r) => {
+      r.writeHandler({
+        name: "invoice:pay",
+        schema: { _type: "stub" } as never,
+        handler: async () => ({ isSuccess: true, data: {} }) as never,
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "invoice-pay",
+        type: "actionForm",
+        handler: "test:write:invoice:pay",
+        fields: { amount: { type: "money", currency: { kind: "literal", code: "EURO" } } } as never,
+        layout: { sections: [{ title: "Pay", fields: ["amount"] }] } as never,
+      });
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      /Screen "invoice-pay" in feature "test", money field "amount"/,
+    );
+  });
+
   // hasMoneyField used to only look at top-level fields, so an entity whose
   // only money lives inside an embedded-list sub-schema (e.g. invoice lines
   // with no top-level money field) slipped past this check — its cells and

package/src/engine/__tests__/form-money-currency-types.test.ts

@@ -0,0 +1,90 @@
+// fw#2839: the type half of the fail-closed currency-source gate. This PR
+// ships the break in one release instead of the #2810 warn-then-throw ladder,
+// on the premise that a consumer sees it from the COMPILER at bump time, not
+// only from a boot error in production. These `@ts-expect-error`s are that
+// premise: each turns into a test failure the moment the narrowing stops
+// catching an undeclared money field in one of the three forms an author
+// writes a screen in.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  ActionFormScreenDefinition,
+  ScreenDefinition,
+  SecretMintScreenDefinition,
+} from "@cosmicdrift/kumiko-types/screen";
+
+const layout = { sections: [{ title: "Payment", fields: ["amount"] }] };
+
+describe("money field on an entity-less form screen is a compile error without `currency`", () => {
+  test("annotated as the ScreenDefinition union", () => {
+    const screen: ScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      // @ts-expect-error — money needs a declared currency source on an
+      // entity-less form; if this compiles, FormFieldDefinition stopped
+      // narrowing and the break would only surface at boot.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+    };
+    expect(screen.type).toBe("actionForm");
+  });
+
+  test("annotated as ActionFormScreenDefinition", () => {
+    const screen: ActionFormScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      // @ts-expect-error — see above.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+    };
+    expect(screen.id).toBe("pay");
+  });
+
+  test("contextually typed through an r.screen(...)-shaped parameter", () => {
+    const register = (def: ScreenDefinition): string => def.id;
+    expect(
+      register({
+        id: "pay",
+        type: "actionForm",
+        handler: "billing:write:pay",
+        // @ts-expect-error — see above.
+        fields: { amount: { type: "money", required: true } },
+        layout,
+      }),
+    ).toBe("pay");
+  });
+
+  test("secretMint's own fields are narrowed the same way", () => {
+    const screen: SecretMintScreenDefinition = {
+      id: "mint",
+      type: "secretMint",
+      handler: "billing:write:mint",
+      // @ts-expect-error — see above.
+      fields: { amount: { type: "money", required: true } },
+      layout,
+      reveal: { fields: [{ field: "token", label: "Token" }] },
+    };
+    expect(screen.type).toBe("secretMint");
+  });
+});
+
+describe("declared currency sources compile", () => {
+  test("literal and tenant are both accepted", () => {
+    const screen: ScreenDefinition = {
+      id: "pay",
+      type: "actionForm",
+      handler: "billing:write:pay",
+      fields: {
+        amount: { type: "money", required: true, currency: { kind: "literal", code: "EUR" } },
+        fee: { type: "money", currency: { kind: "tenant" } },
+      },
+      layout: { sections: [{ title: "Payment", fields: ["amount", "fee"] }] },
+    };
+    expect(Object.keys(screen.type === "actionForm" ? screen.fields : {})).toEqual([
+      "amount",
+      "fee",
+    ]);
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -7,6 +7,7 @@ import type {
   EntityDefinition,
   FeatureDefinition,
   MultiSelectFieldDef,
+  QueryHandlerDef,
 } from "../types";
 
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
@@ -429,13 +430,16 @@ function isValidEmbeddedDecimalScale(scale: number): boolean {
 //   3) Query handler `<feature>:query:<entity>:list` is registered — the
 //      renderer fires it on Combobox open, so a missing handler crashes the
 //      Combobox at runtime.
+//   4) optionsQuery (if set) names a registered query handler.
 function validateReferenceTarget(
   entityName: string,
   fieldPath: string,
   refString: string,
   labelField: string | undefined,
+  optionsQuery: string | undefined,
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   const target = parseRefTarget(refString, feature.name);
   const targetFeature = featureMap.get(target.featureName);
@@ -489,6 +493,40 @@ function validateReferenceTarget(
         `different label/entity.`,
     );
   }
+  // The check above still applies when optionsQuery is set: optionsQuery only
+  // replaces the picker's option list, while list cells keep resolving the
+  // UUID through `<targetFeature>:query:<targetEntity>:list`
+  // (use-reference-lookup).
+  validateReferenceOptionsQuery(entityName, fieldPath, optionsQuery, feature, queryHandlers);
+}
+
+// fw#2780: the picker may source its options from a query handler instead of
+// the referenced entity's table. A typo'd QN would only surface as a 404 on
+// first Combobox open, so it is pinned at boot — same treatment as
+// `DashboardFilterDefinition.optionsQuery` (boot-validator/query-refs.ts).
+function validateReferenceOptionsQuery(
+  entityName: string,
+  fieldPath: string,
+  optionsQuery: string | undefined,
+  feature: FeatureDefinition,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+): void {
+  // skip: a field without optionsQuery keeps the entity-table option source.
+  if (optionsQuery === undefined) return;
+  if (optionsQuery.length === 0) {
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `has an empty optionsQuery. Drop the property or name a query handler.`,
+    );
+  }
+  if (!queryHandlers.has(optionsQuery)) {
+    throw new Error(
+      `[Feature ${feature.name}] Reference field "${fieldPath}" on entity "${entityName}" ` +
+        `declares optionsQuery "${optionsQuery}" which is not a registered query-handler. ` +
+        `Check the QN spelling (expected "<feature>:query:<short>") and that the handler ` +
+        `is declared via r.queryHandler(...).`,
+    );
+  }
 }
 
 // Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation for top-level
@@ -498,6 +536,7 @@ function validateReferenceTarget(
 export function validateReferenceFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -507,8 +546,10 @@ export function validateReferenceFields(
         fieldName,
         field.entity,
         field.labelField,
+        field.optionsQuery,
         feature,
         featureMap,
+        queryHandlers,
       );
     }
   }
@@ -517,6 +558,7 @@ export function validateReferenceFields(
 export function validateEmbeddedFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
 ): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
@@ -554,8 +596,10 @@ export function validateEmbeddedFields(
             `${fieldName}.${subName}`,
             subField.entity,
             subField.labelField,
+            subField.optionsQuery,
             feature,
             featureMap,
+            queryHandlers,
           );
         }
       }

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

@@ -1,5 +1,6 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { dedupeFeatures } from "../dedupe-features";
+import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
 import { validateAccessDeclarations } from "./access-declarations";
@@ -52,6 +53,7 @@ import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validateParentRefs } from "./parent-ref";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
+  buildQueryHandlerMap,
   validateProjectionListScreens,
   validateRelatedListSectionQueries,
 } from "./projection-list-screens";
@@ -187,6 +189,10 @@ export function validateBoot(
     }
   }
 
+  // Registered query-handler QNs, built once for the per-feature reference
+  // checks below (a reference field's `optionsQuery` may target any feature).
+  const queryHandlerQns = buildQueryHandlerMap(features);
+
   let hasEncryptedFields = false;
   let hasFileFields = false;
 
@@ -197,10 +203,10 @@ export function validateBoot(
     validatePiiAndRetention(feature);
     validateRecordOwnedSubjects(feature);
     validateApiExposureMatching(feature, allExposedApis, featureMap);
-    validateEmbeddedFields(feature, featureMap);
+    validateEmbeddedFields(feature, featureMap, queryHandlerQns);
     validateMultiSelectFields(feature);
     validateImageVariants(feature);
-    validateReferenceFields(feature, featureMap);
+    validateReferenceFields(feature, featureMap, queryHandlerQns);
     validateTransitions(feature);
     validateExtensionUsages(feature, extensionProviders);
     validateExtendSchemaCollisions(feature);
@@ -273,9 +279,9 @@ export function validateBoot(
     validateEntityFieldEncryptionAvailable();
   }
 
-  if (hasFileFields && !process.env["FILE_STORAGE_PROVIDER"]) {
+  if (hasFileFields && !process.env[FILE_STORAGE_PROVIDER_ENV]) {
     throw new Error(
-      "FILE_STORAGE_PROVIDER environment variable is required (file/image fields in use)",
+      `${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`,
     );
   }
 

package/src/engine/boot-validator/pii-retention.ts

@@ -197,6 +197,14 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
           );
+        } else if (!annot.subjectRef && (field.type === "text" || field.type === "longText")) {
+          // Deprecation step towards #2810, where a text field without a
+          // stance becomes a boot error. Only text/longText: the other field
+          // types keep `personal` optional.
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Text fields will require one — this warning becomes a boot error in a future release (#2810). Declare { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false }; "false" additionally needs { reason: "..." } stating why the value is not personal data.`,
+          );
         }
       }
     }