@jskit-ai/kernel 0.1.55 → 0.1.56

package/shared/actions/policies.test.js

@@ -1,143 +1,132 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { Type } from "typebox";
+import { createSchema } from "json-rest-schema";
 
 import { ensureActionPermissionAllowed, normalizeActionInput, normalizeActionOutput } from "./policies.js";
 
-test("function schema returns normalized value when ok", async () => {
+test("plain json-rest-schema action schemas validate input without reshaping it", async () => {
   const definition = {
-    id: "tests.ok",
+    id: "tests.schema",
     version: 1,
-    inputValidator: {
-      schema: () => ({
-        ok: true,
-        value: {
-          normalized: true
+    input: {
+      schema: createSchema({
+        workspaceSlug: {
+          type: "string",
+          required: true,
+          minLength: 1
         }
-      })
+      }),
+      mode: "replace"
     }
   };
 
-  const result = await normalizeActionInput(definition, { raw: true }, {});
-  assert.deepEqual(result, { normalized: true });
+  const result = await normalizeActionInput(definition, { workspaceSlug: "  ACME  " }, {});
+  assert.deepEqual(result, { workspaceSlug: "ACME" });
 });
 
-test("function schema rejects non-validator results", async () => {
+test("json-rest-schema input validation surfaces plain field keys", async () => {
   const definition = {
-    id: "tests.invalid",
+    id: "tests.schema.errors",
     version: 1,
-    inputValidator: {
-      schema: () => false
+    input: {
+      schema: createSchema({
+        name: {
+          type: "string",
+          required: true,
+          maxLength: 1
+        }
+      }),
+      mode: "replace"
     }
   };
 
   await assert.rejects(
-    () => normalizeActionInput(definition, { raw: true }, {}),
+    () => normalizeActionInput(definition, { name: "too long" }, {}),
     (error) => {
-      assert.equal(error.code, "ACTION_VALIDATION_FAILED");
-      assert.match(error.details?.error || "", /Schema validator must return/);
+      const fieldErrors = error.details?.fieldErrors || {};
+      assert.equal(typeof fieldErrors.name, "string");
+      assert.equal(Object.hasOwn(fieldErrors, "/name"), false);
       return true;
     }
   );
 });
 
-test("function schema propagates validation errors", async () => {
+test("action output validation preserves valid json-rest-schema output", async () => {
   const definition = {
-    id: "tests.errors",
-    version: 2,
-    inputValidator: {
-      schema: () => ({
-        ok: false,
-        errors: {
-          input: "input is required"
+    id: "tests.output",
+    version: 1,
+    output: {
+      schema: createSchema({
+        ok: {
+          type: "boolean",
+          required: true
         }
-      })
+      }),
+      mode: "replace"
     }
   };
 
   await assert.rejects(
-    () => normalizeActionInput(definition, null, {}),
-    (error) => {
-      assert.equal(error.code, "ACTION_VALIDATION_FAILED");
-      assert.deepEqual(error.details?.fieldErrors, {
-        input: "input is required"
-      });
-      return true;
-    }
+    () => normalizeActionOutput(definition, { ok: 2 }, {}),
+    (error) => error?.code === "ACTION_OUTPUT_VALIDATION_FAILED"
   );
+
+  const result = await normalizeActionOutput(definition, { ok: true }, {});
+  assert.deepEqual(result, { ok: true });
 });
 
-test("raw TypeBox action schemas validate normalized action input", async () => {
+test("json-rest-schema action validators normalize action input", async () => {
   const definition = {
-    id: "tests.typebox",
+    id: "tests.json-rest-schema",
     version: 1,
-    inputValidator: {
-      schema: Type.Object(
-        {
-          workspaceSlug: Type.String({ minLength: 1 })
-        },
-        { additionalProperties: false }
-      ),
-      normalize(value = {}) {
-        return {
-          workspaceSlug: String(value.workspaceSlug || "").trim().toLowerCase()
-        };
-      }
+    input: {
+      schema: createSchema({
+        name: {
+          type: "string",
+          required: true,
+          minLength: 1,
+          messages: {
+            minLength: "Name is required."
+          }
+        }
+      }),
+      mode: "patch"
     }
   };
 
-  const result = await normalizeActionInput(definition, { workspaceSlug: "  ACME  " }, {});
-  assert.deepEqual(result, { workspaceSlug: "acme" });
+  const result = await normalizeActionInput(definition, { name: "  Acme  " }, {});
+  assert.deepEqual(result, { name: "Acme" });
 });
 
-test("typebox input validation normalizes pointer field errors to plain keys", async () => {
+test("json-rest-schema action validators surface field errors", async () => {
   const definition = {
-    id: "tests.typebox.errors",
+    id: "tests.json-rest-schema.errors",
     version: 1,
-    inputValidator: {
-      schema: Type.Object(
-        {
-          name: Type.String({ maxLength: 1 })
-        },
-        { additionalProperties: false }
-      )
+    input: {
+      schema: createSchema({
+        name: {
+          type: "string",
+          required: true,
+          minLength: 1,
+          messages: {
+            minLength: "Name is required."
+          }
+        }
+      }),
+      mode: "patch"
     }
   };
 
   await assert.rejects(
-    () => normalizeActionInput(definition, { name: "too long" }, {}),
+    () => normalizeActionInput(definition, { name: "   " }, {}),
     (error) => {
-      const fieldErrors = error.details?.fieldErrors || {};
-      assert.equal(typeof fieldErrors.name, "string");
-      assert.equal(Object.hasOwn(fieldErrors, "/name"), false);
+      assert.equal(error.code, "ACTION_VALIDATION_FAILED");
+      assert.equal(error.details?.fieldErrors?.name, "Name is required.");
       return true;
     }
   );
 });
 
-test("action output normalization runs before output validation", async () => {
-  const definition = {
-    id: "tests.output",
-    version: 1,
-    outputValidator: {
-      schema: Type.Object(
-        {
-          ok: Type.Boolean()
-        },
-        { additionalProperties: false }
-      ),
-      normalize(payload = {}) {
-        return {
-          ok: Boolean(payload.ok)
-        };
-      }
-    }
-  };
-
-  const result = await normalizeActionOutput(definition, { ok: 1 }, {});
-  assert.deepEqual(result, { ok: true });
-});
-
 test("action permission denies unauthenticated access when required", () => {
   assert.throws(
     () =>

package/shared/actions/registry.test.js

@@ -1,15 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { Type } from "typebox";
+import { createSchema } from "json-rest-schema";
 
 import { createActionRegistry } from "./registry.js";
 
 function createPassThroughSchema() {
-  return {
-    parse(value) {
-      return value;
-    }
-  };
+  return createSchema({});
 }
 
 test("action registry executes latest version by default", async () => {
@@ -28,7 +24,7 @@ test("action registry executes latest version by default", async () => {
             kind: "query",
             channels: ["api"],
             surfaces: ["app", "admin", "console"],
-            inputValidator: { schema: createPassThroughSchema() },
+            input: { schema: createPassThroughSchema() },
             idempotency: "none",
             audit: {
               actionName: "settings.read"
@@ -48,7 +44,7 @@ test("action registry executes latest version by default", async () => {
             kind: "query",
             channels: ["api"],
             surfaces: ["app", "admin", "console"],
-            inputValidator: { schema: createPassThroughSchema() },
+            input: { schema: createPassThroughSchema() },
             idempotency: "none",
             audit: {
               actionName: "settings.read"
@@ -82,7 +78,7 @@ test("action registry executes latest version by default", async () => {
   assert.deepEqual(calls, ["v2"]);
 });
 
-test("action registry merges action input validators", async () => {
+test("action registry validates action input with a single schema contract", async () => {
   const registry = createActionRegistry({
     contributors: [
       {
@@ -96,42 +92,20 @@ test("action registry merges action input validators", async () => {
             kind: "command",
             channels: ["api"],
             surfaces: ["app"],
-            inputValidator: [
-              {
-                schema: Type.Object(
-                  {
-                    workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
-                  },
-                  { additionalProperties: false }
-                ),
-                normalize(input = {}) {
-                  if (!Object.hasOwn(input, "workspaceSlug")) {
-                    return {};
-                  }
-
-                  return {
-                    workspaceSlug: String(input.workspaceSlug || "").trim().toLowerCase()
-                  };
-                }
-              },
-              {
-                schema: Type.Object(
-                  {
-                    invitesEnabled: Type.Optional(Type.Boolean())
-                  },
-                  { additionalProperties: false }
-                ),
-                normalize(input = {}) {
-                  if (!Object.hasOwn(input, "invitesEnabled")) {
-                    return {};
-                  }
-
-                  return {
-                    invitesEnabled: input.invitesEnabled === true
-                  };
+            input: {
+              schema: createSchema({
+                workspaceSlug: {
+                  type: "string",
+                  required: false,
+                  minLength: 1,
+                  lowercase: true
+                },
+                invitesEnabled: {
+                  type: "boolean",
+                  required: false
                 }
-              }
-            ],
+              })
+            },
             idempotency: "optional",
             audit: {
               actionName: "workspace.settings.update"
@@ -181,7 +155,7 @@ test("action registry fails startup on duplicate action id + version", () => {
                 kind: "command",
                 channels: ["api"],
                 surfaces: ["app"],
-                inputValidator: { schema: createPassThroughSchema() },
+                input: { schema: createPassThroughSchema() },
                 idempotency: "optional",
                 audit: {
                   actionName: "settings.profile.update"
@@ -206,7 +180,7 @@ test("action registry fails startup on duplicate action id + version", () => {
                 kind: "command",
                 channels: ["api"],
                 surfaces: ["app"],
-                inputValidator: { schema: createPassThroughSchema() },
+                input: { schema: createPassThroughSchema() },
                 idempotency: "optional",
                 audit: {
                   actionName: "settings.profile.update"
@@ -240,7 +214,7 @@ test("action registry rejects invalid version requests", async () => {
             kind: "query",
             channels: ["api"],
             surfaces: ["app"],
-            inputValidator: { schema: createPassThroughSchema() },
+            input: { schema: createPassThroughSchema() },
             idempotency: "none",
             audit: {
               actionName: "settings.read"
@@ -277,7 +251,7 @@ test("action registry rejects invalid version requests", async () => {
   );
 });
 
-test("action registry ignores unknown legacy fields", async () => {
+test("action registry ignores unknown extra fields", async () => {
   const registry = createActionRegistry({
     contributors: [
       {
@@ -292,7 +266,7 @@ test("action registry ignores unknown legacy fields", async () => {
             channels: ["api", "internal"],
             surfaces: ["app"],
             consoleUsersOnly: true,
-            inputValidator: { schema: createPassThroughSchema() },
+            input: { schema: createPassThroughSchema() },
             idempotency: "none",
             audit: {
               actionName: "settings.internal.ping"
@@ -335,7 +309,7 @@ test("action registry enforces action-level permissions", async () => {
               require: "all",
               permissions: ["workspace.settings.update"]
             },
-            inputValidator: { schema: createPassThroughSchema() },
+            input: { schema: createPassThroughSchema() },
             idempotency: "optional",
             audit: {
               actionName: "workspace.settings.update"

package/shared/support/crudFieldContract.js

@@ -0,0 +1,322 @@
+import { normalizeSchemaDefinition } from "../validators/schemaDefinitions.js";
+import { normalizeObject, normalizeText } from "./normalize.js";
+
+const CRUD_FIELD_STORAGE_COLUMN = "column";
+const CRUD_FIELD_STORAGE_VIRTUAL = "virtual";
+const CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC = "datetime-utc";
+const CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE = "autocomplete";
+const CRUD_LOOKUP_FORM_CONTROL_SELECT = "select";
+
+function checkCrudLookupFormControl(
+  value,
+  {
+    context = "crud field ui.formControl",
+    defaultValue = CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE
+  } = {}
+) {
+  const resolvedValue = value === undefined || value === null || value === "" ? defaultValue : value;
+  if (resolvedValue === "") {
+    return "";
+  }
+
+  if (
+    resolvedValue === CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE ||
+    resolvedValue === CRUD_LOOKUP_FORM_CONTROL_SELECT
+  ) {
+    return resolvedValue;
+  }
+
+  throw new Error(
+    `${context} must be "${CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE}" or "${CRUD_LOOKUP_FORM_CONTROL_SELECT}". ` +
+      `Received: ${JSON.stringify(resolvedValue)}.`
+  );
+}
+
+function cloneStructuredFieldMetadata(value = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const normalized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(entry)) {
+      normalized[key] = entry.map((item) =>
+        item && typeof item === "object" && !Array.isArray(item)
+          ? cloneStructuredFieldMetadata(item) || {}
+          : item
+      );
+      continue;
+    }
+
+    if (entry && typeof entry === "object") {
+      normalized[key] = cloneStructuredFieldMetadata(entry) || {};
+      continue;
+    }
+
+    normalized[key] = entry;
+  }
+
+  return Object.keys(normalized).length > 0 ? Object.freeze(normalized) : null;
+}
+
+function resolveCrudFieldSchemaProperties(value, { context = "crud resource field definitions" } = {}) {
+  if (value == null) {
+    return {};
+  }
+
+  const normalized = normalizeSchemaDefinition(value, {
+    context,
+    defaultMode: "patch"
+  });
+  if (!normalized) {
+    return {};
+  }
+
+  return normalizeObject(normalized.schema.getFieldDefinitions());
+}
+
+function normalizeCrudFieldStorageConfig(
+  fieldDefinition = {},
+  {
+    context = "crud field storage",
+    fieldKey = ""
+  } = {}
+) {
+  const normalizedFieldKey = normalizeText(fieldKey);
+  const actualField = normalizeText(fieldDefinition.actualField);
+  const storage = fieldDefinition?.storage;
+
+  if (storage === undefined || storage === null) {
+    return Object.freeze({
+      mode: CRUD_FIELD_STORAGE_COLUMN,
+      column: actualField,
+      writeSerializer: ""
+    });
+  }
+
+  if (!storage || typeof storage !== "object" || Array.isArray(storage)) {
+    throw new TypeError(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} must be an object when provided.`
+    );
+  }
+
+  for (const storageKey of Object.keys(storage)) {
+    if (storageKey !== "column" && storageKey !== "virtual" && storageKey !== "writeSerializer") {
+      throw new Error(
+        `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} does not support storage.${storageKey}.`
+      );
+    }
+  }
+
+  const column = normalizeText(storage.column) || actualField;
+  const virtual = storage.virtual === true;
+  const writeSerializer = normalizeText(storage.writeSerializer).toLowerCase();
+
+  if (actualField && normalizeText(storage.column) && normalizeText(storage.column) !== actualField) {
+    throw new Error(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} actualField and storage.column must match when both are provided.`
+    );
+  }
+
+  if (writeSerializer && writeSerializer !== CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC) {
+    throw new Error(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} storage.writeSerializer must be ` +
+        `"${CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC}" when provided.`
+    );
+  }
+
+  if (virtual && column) {
+    throw new Error(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} virtual fields cannot define actualField or storage.column.`
+    );
+  }
+
+  if (virtual && writeSerializer) {
+    throw new Error(
+      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} virtual fields cannot define storage.writeSerializer.`
+    );
+  }
+
+  return Object.freeze({
+    mode: virtual ? CRUD_FIELD_STORAGE_VIRTUAL : CRUD_FIELD_STORAGE_COLUMN,
+    column,
+    writeSerializer
+  });
+}
+
+function mergeFieldContractEntry(target, source, { context = "crud field contract", fieldKey = "" } = {}) {
+  if (!source || typeof source !== "object") {
+    return target;
+  }
+
+  const next = target ? { ...target } : {};
+  const normalizedFieldKey = normalizeText(fieldKey);
+
+  const mergeScalar = (key) => {
+    const value = normalizeText(source[key]);
+    if (!value) {
+      return;
+    }
+    if (next[key] && next[key] !== value) {
+      throw new Error(`${context}["${normalizedFieldKey}"] has conflicting ${key} metadata.`);
+    }
+    next[key] = value;
+  };
+
+  mergeScalar("actualField");
+  mergeScalar("parentRouteParamKey");
+
+  const storage = source.storage && typeof source.storage === "object" ? source.storage : null;
+  if (storage) {
+    const currentStorage = next.storage || {};
+    if (storage.mode && currentStorage.mode && currentStorage.mode !== storage.mode) {
+      throw new Error(`${context}["${normalizedFieldKey}"] has conflicting storage.mode metadata.`);
+    }
+    if (storage.column && currentStorage.column && currentStorage.column !== storage.column) {
+      throw new Error(`${context}["${normalizedFieldKey}"] has conflicting storage.column metadata.`);
+    }
+    if (storage.writeSerializer &&
+      currentStorage.writeSerializer &&
+      currentStorage.writeSerializer !== storage.writeSerializer
+    ) {
+      throw new Error(`${context}["${normalizedFieldKey}"] has conflicting storage.writeSerializer metadata.`);
+    }
+    next.storage = {
+      ...currentStorage,
+      ...storage
+    };
+  }
+
+  if (source.relation && typeof source.relation === "object") {
+    next.relation = {
+      ...(next.relation && typeof next.relation === "object" ? next.relation : {}),
+      ...source.relation
+    };
+  }
+
+  if (source.ui && typeof source.ui === "object") {
+    next.ui = {
+      ...(next.ui && typeof next.ui === "object" ? next.ui : {}),
+      ...source.ui
+    };
+  }
+
+  return next;
+}
+
+function buildCrudFieldContractMap(resource = {}, { context = "crud resource field contract" } = {}) {
+  const sections = [
+    resolveCrudFieldSchemaProperties(resource?.operations?.view?.output, {
+      context: `${context}.operations.view.output`
+    }),
+    resolveCrudFieldSchemaProperties(resource?.operations?.create?.body, {
+      context: `${context}.operations.create.body`
+    }),
+    resolveCrudFieldSchemaProperties(resource?.operations?.patch?.body, {
+      context: `${context}.operations.patch.body`
+    })
+  ];
+
+  const entries = {};
+  for (const definitions of sections) {
+    for (const [rawKey, rawDefinition] of Object.entries(definitions)) {
+      const key = normalizeText(rawKey);
+      if (!key) {
+        continue;
+      }
+      const definition = normalizeObject(rawDefinition);
+      const storage = normalizeCrudFieldStorageConfig(definition, {
+        context: `${context}.storage`,
+        fieldKey: key
+      });
+      const relation = cloneStructuredFieldMetadata(definition.relation);
+      const ui = cloneStructuredFieldMetadata(definition.ui);
+      const parentRouteParamKey =
+        normalizeText(definition.parentRouteParamKey) ||
+        normalizeText(definition?.relation?.parentRouteParamKey);
+
+      entries[key] = mergeFieldContractEntry(entries[key], {
+        actualField: normalizeText(definition.actualField),
+        parentRouteParamKey,
+        storage,
+        relation,
+        ui
+      }, {
+        context,
+        fieldKey: key
+      });
+    }
+  }
+
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(entries).map(([key, value]) => [
+        key,
+        Object.freeze({
+          key,
+          actualField: normalizeText(value.actualField),
+          parentRouteParamKey: normalizeText(value.parentRouteParamKey),
+          storage: Object.freeze({
+            mode: normalizeText(value?.storage?.mode) || CRUD_FIELD_STORAGE_COLUMN,
+            column: normalizeText(value?.storage?.column),
+            writeSerializer: normalizeText(value?.storage?.writeSerializer).toLowerCase()
+          }),
+          relation: cloneStructuredFieldMetadata(value.relation),
+          ui: cloneStructuredFieldMetadata(value.ui)
+        })
+      ])
+    )
+  );
+}
+
+function buildCrudOperationSchemaFields(fields = {}, operationName = "") {
+  const definitions = {};
+
+  for (const [fieldKey, fieldDefinition] of Object.entries(fields)) {
+    const operationConfig = fieldDefinition?.operations?.[operationName];
+    if (!operationConfig) {
+      continue;
+    }
+
+    const nextDefinition = {
+      ...fieldDefinition
+    };
+    delete nextDefinition.operations;
+
+    if (operationConfig !== true) {
+      Object.assign(nextDefinition, operationConfig);
+    }
+
+    definitions[fieldKey] = nextDefinition;
+  }
+
+  return definitions;
+}
+
+function resolveCrudFieldContractEntry(resource = {}, fieldKey = "", options = {}) {
+  const normalizedFieldKey = normalizeText(fieldKey);
+  if (!normalizedFieldKey) {
+    return null;
+  }
+
+  const entries = buildCrudFieldContractMap(resource, options);
+  return entries[normalizedFieldKey] || null;
+}
+
+export {
+  CRUD_FIELD_STORAGE_COLUMN,
+  CRUD_FIELD_STORAGE_VIRTUAL,
+  CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC,
+  CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE,
+  CRUD_LOOKUP_FORM_CONTROL_SELECT,
+  checkCrudLookupFormControl,
+  resolveCrudFieldSchemaProperties,
+  normalizeCrudFieldStorageConfig,
+  buildCrudOperationSchemaFields,
+  buildCrudFieldContractMap,
+  resolveCrudFieldContractEntry
+};