@cosmicdrift/kumiko-framework 0.317.0 → 0.318.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.317.0",
+  "version": "0.318.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.317.0",
-    "@cosmicdrift/kumiko-types": "0.317.0",
+    "@cosmicdrift/kumiko-http": "0.318.0",
+    "@cosmicdrift/kumiko-types": "0.318.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.317.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.318.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.318.0",
+    "type": "improvement",
+    "title": "Generic create/update entity handlers can exclude individual fields",
+    "detail": "`excludeFields` on defineEntityCreateHandler/defineEntityUpdateHandler, and `excludeFields: { create?, update? }` on registerEntityCrud/r.crud. A payload that still carries an excluded field fails validation instead of being stripped silently, so an app no longer needs a hand-written handler just to make one field read-only (e.g. a VIN after creation)."
+  },
   {
     "version": "0.317.0",
     "type": "fix",

package/src/engine/__tests__/entity-exclude-fields.integration.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { defineEntityUpdateHandler, defineEntityWriteHandler } from "../entity-handlers";
+import { createEntity, createTextField } from "../factories";
+
+const carEntity = createEntity({
+  table: "exclude_fields_cars",
+  fields: {
+    vin: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    model: createTextField({ personal: false, reason: "test_fixture" }),
+    internalNote: createTextField({ personal: false, reason: "test_fixture" }),
+  },
+});
+
+const carFeature = defineFeature("exclude-fields", (r) => {
+  r.crud("car", carEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    excludeFields: { create: ["internalNote"], update: ["vin"] },
+  });
+});
+
+const CREATE = "exclude-fields:write:car:create";
+const UPDATE = "exclude-fields:write:car:update";
+
+type WriteBody = {
+  readonly isSuccess: boolean;
+  readonly data?: { readonly data: Record<string, unknown> & { id: string; version: number } };
+  readonly error?: {
+    readonly code: string;
+    readonly details?: { readonly fields?: readonly { readonly path: string }[] };
+  };
+};
+
+describe("excludeFields on the generic create/update handlers", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [carFeature] });
+    await unsafeCreateEntityTable(stack.db, carEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "exclude_fields_cars"');
+  });
+
+  async function createCar(): Promise<{ id: string; version: number }> {
+    const res = await stack.http.write(CREATE, { vin: "WVW123", model: "Golf" }, TestUsers.user);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as WriteBody;
+    if (!body.data) throw new Error("create returned no data");
+    return body.data.data;
+  }
+
+  test("update rejects a payload that still carries an excluded field and keeps the row unchanged", async () => {
+    const car = await createCar();
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: car.id, version: car.version, changes: { vin: "HACKED", model: "Polo" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as WriteBody;
+    expect(body.error?.code).toBe("validation_error");
+    expect(body.error?.details?.fields?.map((field) => field.path)).toEqual(["changes.vin"]);
+
+    const rows = await asRawClient(stack.db).unsafe(
+      'SELECT vin, model FROM "exclude_fields_cars" WHERE id = $1',
+      [car.id],
+    );
+    expect(rows[0]).toMatchObject({ vin: "WVW123", model: "Golf" });
+  });
+
+  test("update without the excluded field writes the other fields", async () => {
+    const car = await createCar();
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: car.id, version: car.version, changes: { model: "Polo" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as WriteBody;
+    expect(body.data?.data).toMatchObject({ vin: "WVW123", model: "Polo" });
+  });
+
+  test("create honors its own exclusion list independently of update's", async () => {
+    const rejected = await stack.http.write(
+      CREATE,
+      { vin: "WVW999", internalNote: "set by client" },
+      TestUsers.user,
+    );
+    expect(rejected.status).toBe(400);
+    const body = (await rejected.json()) as WriteBody;
+    expect(body.error?.details?.fields?.map((field) => field.path)).toEqual(["internalNote"]);
+  });
+});
+
+describe("excludeFields definition-time checks", () => {
+  test("rejects an unknown field name", () => {
+    expect(() =>
+      defineEntityUpdateHandler("car", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["colour"],
+      }),
+    ).toThrow(/unknown field "colour"/);
+  });
+
+  test("rejects excluding a required field without default on create", () => {
+    expect(() =>
+      defineEntityWriteHandler("car:create", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["vin"],
+      }),
+    ).toThrow(/required without a default/);
+  });
+
+  test("rejects excludeFields on delete", () => {
+    expect(() =>
+      defineEntityWriteHandler("car:delete", carEntity, {
+        access: { roles: ["User"] },
+        excludeFields: ["model"],
+      }),
+    ).toThrow(/only applies to create and update/);
+  });
+});

package/src/engine/entity-handlers.ts

@@ -29,6 +29,7 @@ import type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "./types/entity-handlers";
 
@@ -38,6 +39,7 @@ export type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "./types/entity-handlers";
 
@@ -202,10 +204,48 @@ function parseHandlerName<TVerb extends string>(
   return { entityName, verb: verbCandidate as TVerb }; // @cast-boundary engine-bridge
 }
 
+function isInTotalsMatchPair(entity: EntityDefinition, fieldName: string): boolean {
+  return Object.entries(entity.fields).some(
+    ([name, field]) =>
+      field.type === "embedded" &&
+      field.totalsMatch !== undefined &&
+      (name === fieldName || Object.values(field.totalsMatch).includes(fieldName)),
+  );
+}
+
+function assertExcludableFields(
+  name: string,
+  verb: (typeof WRITE_VERBS)[number],
+  entity: EntityDefinition,
+  excludedFields: readonly string[],
+): void {
+  if (excludedFields.length > 0 && verb !== "create" && verb !== "update") {
+    throw new Error(`"${name}": excludeFields only applies to create and update handlers.`);
+  }
+  for (const fieldName of excludedFields) {
+    const field = entity.fields[fieldName];
+    if (!field) {
+      throw new Error(`"${name}": excludeFields names unknown field "${fieldName}".`);
+    }
+    if (isInTotalsMatchPair(entity, fieldName)) {
+      throw new Error(
+        `"${name}": excludeFields cannot name "${fieldName}" — it is part of a totalsMatch pair, which must be written together.`,
+      );
+    }
+    const isRequired = "required" in field && field.required === true;
+    const hasDefault = "default" in field && field.default !== undefined;
+    if (verb === "create" && isRequired && !hasDefault) {
+      throw new Error(
+        `"${name}": excludeFields cannot name "${fieldName}" — it is required without a default, so no row could ever be created.`,
+      );
+    }
+  }
+}
+
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -213,6 +253,8 @@ export function defineEntityWriteHandler(
       `"${name}": restore is only valid for entities declared with softDelete: true.`,
     );
   }
+  const excludedFields = options.excludeFields ?? [];
+  assertExcludableFields(name, verb, entity, excludedFields);
 
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
@@ -263,7 +305,7 @@ export function defineEntityWriteHandler(
 
   switch (verb) {
     case "create":
-      schema = buildInsertSchema(entity);
+      schema = buildInsertSchema(entity, undefined, excludedFields);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
         // A caller-chosen id (deterministic-id idempotent creates) is only
@@ -284,7 +326,7 @@ export function defineEntityWriteHandler(
       schema = z.object({
         id: z.uuid(),
         version: z.number(),
-        changes: buildUpdateSchema(entity),
+        changes: buildUpdateSchema(entity, undefined, excludedFields),
       });
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
@@ -507,7 +549,7 @@ export function defineEntityQueryHandler(
 export function defineEntityCreateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:create`, entity, options);
 }
@@ -516,7 +558,7 @@ export function defineEntityCreateHandler(
 export function defineEntityUpdateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options: EntityHandlerOptions,
+  options: EntityWriteHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:update`, entity, options);
 }
@@ -651,11 +693,16 @@ export function registerEntityCrud(
     }
     return access;
   };
-  const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
-    ...writeOpts,
-    access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
-    description: options?.descriptions?.[verb] ?? writeOpts?.description,
-  });
+  const resolveWriteOpts = (verb: EntityCrudVerb): EntityWriteHandlerOptions => {
+    const excludeFields =
+      verb === "create" || verb === "update" ? options?.excludeFields?.[verb] : undefined;
+    return {
+      ...writeOpts,
+      access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
+      description: options?.descriptions?.[verb] ?? writeOpts?.description,
+      ...(excludeFields !== undefined && { excludeFields }),
+    };
+  };
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
     access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),

package/src/engine/schema-builder.ts

@@ -367,13 +367,25 @@ function applyTotalsMatchRefinements(
   return result;
 }
 
+// An excluded field stays in the shape as "must be absent" instead of being
+// dropped: zod strips unknown keys silently, so a client still sending it
+// would otherwise get a success without the write happening.
+function notWritableField(): z.ZodTypeAny {
+  return z.never().optional();
+}
+
 export function buildInsertSchema(
   entity: EntityDefinition,
   currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+  excludedFields: readonly string[] = [],
 ): z.ZodObject<Record<string, z.ZodTypeAny>> {
   const shape: Record<string, z.ZodTypeAny> = {};
 
   for (const [name, field] of Object.entries(entity.fields)) {
+    if (excludedFields.includes(name)) {
+      shape[name] = notWritableField();
+      continue;
+    }
     const zodField = fieldToZod(field, currencies);
     const hasDefault = "default" in field && field.default !== undefined;
     const isRequired = "required" in field && field.required === true;
@@ -392,10 +404,15 @@ export function buildInsertSchema(
 export function buildUpdateSchema(
   entity: EntityDefinition,
   currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+  excludedFields: readonly string[] = [],
 ): z.ZodObject<Record<string, z.ZodTypeAny>> {
   const shape: Record<string, z.ZodTypeAny> = {};
 
   for (const [name, field] of Object.entries(entity.fields)) {
+    if (excludedFields.includes(name)) {
+      shape[name] = notWritableField();
+      continue;
+    }
     // Update schemas never apply defaults for OMITTED fields — a user that
     // sends only `{ title }` means "only change title"; zod defaults would
     // silently inject default values for every omitted field and clobber

package/src/engine/types/index.ts

@@ -63,6 +63,7 @@ export type {
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
+  EntityWriteHandlerOptions,
   RegisterEntityCrudOptions,
 } from "@cosmicdrift/kumiko-types/entity-handlers";
 // Cross-Feature Compile-Time-Type-Map — features extend per declare-module.

package/src/ui-types/formality.ts

@@ -0,0 +1,7 @@
+export type Formality = "formal" | "informal";
+
+// BCP-47 private-use subtag: a translation bundle keyed "de-x-formal" holds the
+// formal ("Sie") wording and only needs the keys that differ from plain "de".
+export function formalLocaleTag<Locale extends string>(locale: Locale): `${Locale}-x-formal` {
+  return `${locale}-x-formal`;
+}

package/src/ui-types/index.ts

@@ -137,6 +137,7 @@ export type {
   QualifiedContentCollection,
   WorkspaceSchema,
 } from "./app-schema";
+export { type Formality, formalLocaleTag } from "./formality";
 export type {
   ListRowMetaColumnType,
   ListRowMetaReference,