@cosmicdrift/kumiko-framework 0.289.0 → 0.291.0

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

@@ -62,7 +62,7 @@ describe("r.bootCheck / validateFeatureBootChecks", () => {
   });
 
   test("no PII field → boot succeeds even without the companion", () => {
-    const noPiiFields = { text: createTextField() };
+    const noPiiFields = { text: createTextField({ personal: false, reason: "test_fixture" }) };
     const noPii = defineFeature("prompt-store-no-pii", (r) => {
       r.entity("note", createEntity({ fields: noPiiFields }));
       r.bootCheck(({ features }) => {

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

@@ -40,6 +40,17 @@ import type { LongTextFieldDef, TextFieldDef } from "../types";
 const rawField = <T>(f: T) => f as unknown as TextFieldDef;
 const rawLongTextField = <T>(f: T) => f as unknown as LongTextFieldDef;
 
+// The heuristics under test only fire without a personal stance; after #2810
+// the factories can no longer produce that shape.
+const unannotatedText: TextFieldDef = {
+  type: "text",
+  maxLength: 200,
+  required: false,
+  searchable: false,
+  sortable: false,
+};
+const unannotatedLongText: LongTextFieldDef = { type: "longText", required: false };
+
 // Stubt einen leeren `<entity>:list`-Query-Handler damit der reference-
 // Field-Boot-Validator den Audit-Fix-#2-Check durchläßt. Wird gebraucht
 // wenn ein Test ein reference-Feld benutzt — sonst liefert der validator
@@ -136,7 +147,7 @@ describe("validateBoot — PII annotations", () => {
         createEntity({
           fields: {
             confused: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               pii: true,
               tenantOwned: true,
             }),
@@ -153,7 +164,7 @@ describe("validateBoot — PII annotations", () => {
         "vault",
         createEntity({
           fields: {
-            apiToken: createTextField({ sensitive: true }),
+            apiToken: { ...unannotatedText, sensitive: true },
           },
         }),
       );
@@ -188,7 +199,7 @@ describe("validateBoot — PII annotations", () => {
           "vault",
           createEntity({
             fields: {
-              apiToken: createTextField({ sensitive: true, encrypted: true }),
+              apiToken: { ...unannotatedText, sensitive: true, encrypted: true },
             },
           }),
         );
@@ -228,7 +239,7 @@ describe("validateBoot — PII annotations", () => {
               personal: { of: "authorId" },
               find: "none",
             }),
-            authorId: createTextField(),
+            authorId: { ...unannotatedText },
           },
         }),
       );
@@ -258,7 +269,7 @@ describe("validateBoot — PII annotations", () => {
 
   test("userOwned.ownerField referencing non-user entity warns", () => {
     const feature = defineFeature("test", (r) => {
-      r.entity("employee", createEntity({ fields: { name: createTextField() } }));
+      r.entity("employee", createEntity({ fields: { name: { ...unannotatedText } } }));
       stubListHandler(r, "employee");
       r.entity(
         "personalNote",
@@ -286,7 +297,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            email: createTextField(),
+            email: { ...unannotatedText },
           },
         }),
       );
@@ -304,7 +315,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            body: createLongTextField(),
+            body: { ...unannotatedLongText },
           },
         }),
       );
@@ -322,7 +333,7 @@ describe("validateBoot — PII annotations", () => {
         "thing",
         createEntity({
           fields: {
-            authorId: createTextField(),
+            authorId: { ...unannotatedText },
           },
         }),
       );
@@ -563,7 +574,7 @@ describe("validateBoot — PII annotations", () => {
         "product",
         createEntity({
           fields: {
-            name: createTextField(),
+            name: { ...unannotatedText },
           },
         }),
       );
@@ -581,7 +592,7 @@ describe("validateBoot — PII annotations", () => {
         "person",
         createEntity({
           fields: {
-            displayName: createTextField(),
+            displayName: { ...unannotatedText },
           },
         }),
       );
@@ -592,6 +603,128 @@ describe("validateBoot — PII annotations", () => {
     );
     expect(matchingWarn).toBeDefined();
   });
+
+  // --- #2918: deprecation warning for text fields without any stance ---
+
+  const NO_STANCE = "declares no personal stance";
+
+  test("text field without a personal stance warns, naming feature, entity and field", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: { ...unannotatedText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+    const message = String((matchingWarn as unknown[])[0]);
+    expect(message).toContain("[Feature test]");
+    expect(message).toContain('Field "externalRef" on entity "invoice"');
+    expect(message).toContain('{ reason: "..." }');
+  });
+
+  test("longText field without a personal stance warns", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            remarks: { ...unannotatedLongText },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("personal: false with a reason silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: false,
+              reason: "is_business_data",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: self silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            externalRef: createTextField({
+              personal: "self",
+              find: "none",
+            }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("personal: ref silences the stance warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            ownerRef: createTextField({ personal: "ref" }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("number field without a personal stance does not warn", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          fields: {
+            total: { type: "number", required: false },
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes(NO_STANCE),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
 });
 
 describe("validateBoot — retention", () => {
@@ -626,7 +759,7 @@ describe("validateBoot — retention", () => {
         "auditEvent",
         createEntity({
           fields: {
-            note: createTextField(),
+            note: { ...unannotatedText },
           },
           retention: { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
         }),
@@ -641,7 +774,7 @@ describe("validateBoot — retention", () => {
         "thing",
         createEntity({
           fields: {
-            note: createTextField(),
+            note: { ...unannotatedText },
           },
           retention: { keepFor: "30d", strategy: "hardDelete", reference: "ghostField" },
         }),
@@ -852,7 +985,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         createEntity({
           fields: {
             slug: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               lookupable: true,
             }),
           },
@@ -872,7 +1005,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
               ...createLongTextField({ personal: { of: "ownerId" }, find: "none" }),
               lookupable: true,
             }),
-            ownerId: createTextField({ required: true }),
+            ownerId: { ...unannotatedText, required: true },
           },
         }),
       );
@@ -922,7 +1055,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         createEntity({
           fields: {
             passwordHash: rawField({
-              ...createTextField(),
+              ...unannotatedText,
               pii: true,
               sensitive: true,
               searchable: true,

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__/entity-presave-wiring.integration.test.ts

@@ -20,8 +20,12 @@ const contactEntity = createEntity({
     // hook) writes it. secretNote's ownership rule checks authorId, so
     // create only succeeds if the hook ran BEFORE the field-ownership check
     // (kumiko-framework#1672 — see also event-store-executor-write.ts).
-    authorId: createTextField(),
-    secretNote: createTextField({ access: { write: { User: from("user:id", "authorId") } } }),
+    authorId: createTextField({ personal: false, reason: "test_fixture" }),
+    secretNote: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      access: { write: { User: from("user:id", "authorId") } },
+    }),
   },
 });
 

package/src/engine/__tests__/factories-long-text.test.ts

@@ -41,7 +41,12 @@ describe("createLongTextField — runtime shape", () => {
   });
 
   test("encrypted + sensitive flags type-allowed", () => {
-    const f = createLongTextField({ encrypted: true, sensitive: true });
+    const f = createLongTextField({
+      personal: false,
+      reason: "test_fixture",
+      encrypted: true,
+      sensitive: true,
+    });
     expect(f.encrypted).toBe(true);
     expect(f.sensitive).toBe(true);
   });