@makehq/forman-schema 1.4.0 → 1.5.0

package/dist/index.cjs

@@ -29,6 +29,22 @@ module.exports = __toCommonJS(index_exports);
 
 // src/utils.ts
 var FORMAN_VISUAL_TYPES = ["banner", "markdown", "html", "separator"];
+function isVisualType(type) {
+  return FORMAN_VISUAL_TYPES.includes(type);
+}
+var FORMAN_REFERENCE_TYPES = [
+  "account",
+  "hook",
+  "device",
+  "keychain",
+  "datastore",
+  "aiagent",
+  "udt",
+  "scenario"
+];
+function isReferenceType(type) {
+  return FORMAN_REFERENCE_TYPES.includes(type);
+}
 function noEmpty(text) {
   return text?.trim() || void 0;
 }
@@ -42,13 +58,19 @@ function containsIMLExpression(value) {
   if (typeof value !== "string") return false;
   return value.indexOf("{{") > -1 && value.indexOf("}}") > -1;
 }
+function isPrimitiveIMLExpression(value) {
+  if (typeof value !== "string") return false;
+  return value.lastIndexOf("{{") === 0 && value.indexOf("}}") === value.length - 2;
+}
 var API_ENDPOINTS = {
   account: "api://connections/{{kind}}",
   aiagent: "api://ai-agents/v1/agents",
   datastore: "api://data-stores",
   hook: "api://hooks/{{kind}}",
+  device: "api://devices",
   keychain: "api://keys/{{kind}}",
-  udt: "api://data-structures"
+  udt: "api://data-structures",
+  scenario: "api://scenario-list"
 };
 function normalizeFormanFieldType(field) {
   const [type, kind] = field.type.split(":");
@@ -67,6 +89,69 @@ function normalizeFormanFieldType(field) {
     }
   };
 }
+function buildRestoreStructure(items) {
+  const result = {};
+  for (const item of items) {
+    const { domain, path, state } = item;
+    if (!result[domain]) {
+      result[domain] = {};
+    }
+    let current = result[domain];
+    for (const [index, key] of path.entries()) {
+      const nextKey = path[index + 1];
+      const isLastElement = index === path.length - 1;
+      const nextIsNumber = typeof nextKey === "number";
+      if (Array.isArray(current)) {
+        if (typeof key !== "number") {
+          throw new Error("Invalid path");
+        }
+        if (!current[key]) {
+          current[key] = {};
+        }
+        if (nextIsNumber) {
+          if (!current[key].value) {
+            current[key].value = {
+              mode: "chose",
+              items: []
+            };
+          }
+          if (!current[key].value.items) {
+            current[key].value.items = [];
+          }
+          current = current[key].value.items;
+        } else if (isLastElement) {
+          Object.assign(current[key], state);
+        } else {
+          current = current[key];
+        }
+      } else {
+        if (typeof key !== "string") {
+          throw new Error("Invalid path");
+        }
+        if (!current[key]) {
+          current[key] = {};
+        }
+        if (isLastElement) {
+          Object.assign(current[key], state);
+        } else {
+          if (nextIsNumber) {
+            if (!current[key].items) {
+              current[key].items = [];
+              current[key].mode = "chose";
+            }
+            current = current[key].items;
+          } else {
+            if (!current[key].nested) {
+              current[key].nested = {};
+            }
+            current = current[key].nested;
+          }
+        }
+      }
+    }
+  }
+  return result;
+}
 
 // src/forman.ts
 var SchemaConversionError = class extends Error {
@@ -178,7 +263,7 @@ function handleCollectionType(field, result, context) {
     required: []
   });
   function addField(subField, tail) {
-    if (FORMAN_VISUAL_TYPES.includes(subField.type)) {
+    if (isVisualType(subField.type)) {
       return;
     }
     if (!subField.name) return;
@@ -423,6 +508,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
     (acc, domain) => {
       acc[domain] = {
         seenFields: /* @__PURE__ */ new Set(),
+        fieldStates: [],
         validateFields: (fields, context) => {
           return validateFormanValue(
             domains[domain].values,
@@ -480,11 +566,14 @@ async function validateFormanWithDomainsInternal(domains, options) {
   }
   return {
     valid: errors.length === 0,
-    errors
+    errors,
+    states: errors.length === 0 && options?.states ? buildRestoreStructure(
+      Object.keys(domains).map((domain) => roots[domain].fieldStates.map((state) => ({ domain, ...state }))).flat()
+    ) : void 0
   };
 }
 async function validateFormanValue(value, field, context) {
-  if (FORMAN_VISUAL_TYPES.includes(field.type)) {
+  if (isVisualType(field.type)) {
     return {
       valid: true,
       errors: []
@@ -512,7 +601,7 @@ async function validateFormanValue(value, field, context) {
   const expectedType = FORMAN_TYPE_MAP2[normalizedField.type];
   let actualType = typeof value;
   if (actualType === "object" && Array.isArray(value)) actualType = "array";
-  if (expectedType && expectedType !== actualType) {
+  if (expectedType && expectedType !== actualType && !isPrimitiveIMLExpression(value)) {
     return {
       valid: false,
       errors: [
@@ -524,6 +613,24 @@ async function validateFormanValue(value, field, context) {
       ]
     };
   }
+  if (containsIMLExpression(value)) {
+    if (normalizedField.mappable === false) {
+      return {
+        valid: false,
+        errors: [
+          {
+            domain: context.domain,
+            path: context.path.join("."),
+            message: "Value contains prohibited IML expression."
+          }
+        ]
+      };
+    }
+    return {
+      valid: true,
+      errors: []
+    };
+  }
   switch (normalizedField.type) {
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
@@ -532,10 +639,12 @@ async function validateFormanValue(value, field, context) {
     case "select":
     case "account":
     case "hook":
+    case "device":
     case "keychain":
     case "datastore":
     case "aiagent":
     case "udt":
+    case "scenario":
     case "file":
     case "folder":
       return handleSelectType2(value, normalizedField, context);
@@ -575,7 +684,7 @@ async function handleCollectionType2(value, field, context) {
           };
         }
       }
-      if (FORMAN_VISUAL_TYPES.includes(subField.type)) {
+      if (isVisualType(subField.type)) {
         continue;
       }
       if (!subField.name) {
@@ -592,7 +701,7 @@ async function handleCollectionType2(value, field, context) {
         path: [...path, subField.name],
         validateNestedFields: async (fields, context2) => {
           for (const subField2 of fields) {
-            if (FORMAN_VISUAL_TYPES.includes(subField2.type)) {
+            if (isVisualType(subField2.type)) {
               continue;
             }
             if (!subField2.name) {
@@ -639,7 +748,7 @@ async function handleArrayType2(value, field, context) {
       const result = await validateFormanValue(
         item,
         Array.isArray(field.spec) ? { name: index.toString(), type: "collection", spec: field.spec } : Object.assign({}, field.spec, { name: index.toString() }),
-        { ...context, path: [...context.path, index.toString()] }
+        { ...context, path: [...context.path, index] }
       );
       errors.push(...result.errors);
     }
@@ -743,6 +852,15 @@ async function handleSelectType2(value, field, context) {
         ]
       };
     }
+    if (item.label) {
+      context.roots[context.domain].fieldStates.push({
+        path: context.path,
+        state: {
+          mode: isReferenceType(field.type) ? void 0 : "chose",
+          label: item.label
+        }
+      });
+    }
     if (item.nested) nested = item.nested;
   }
   if (nested) {
@@ -811,18 +929,6 @@ async function handleNestedFields(nested, value, field, context) {
 }
 async function handlePrimitiveType2(value, field, context) {
   const errors = [];
-  if (containsIMLExpression(value)) {
-    return {
-      valid: true,
-      errors
-    };
-  }
-  if (errors.length > 0) {
-    return {
-      valid: false,
-      errors
-    };
-  }
   if (field.validate) {
     if (typeof value === "string") {
       if (field.validate.pattern && !new RegExp(

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { JSONSchema7 } from 'json-schema';
 /**
  * Valid Forman Schema field types
  */
-type FormanSchemaFieldType = 'aiagent' | 'account' | 'hook' | 'keychain' | 'datastore' | 'udt' | 'array' | 'collection' | 'text' | 'number' | 'boolean' | 'date' | 'json' | 'buffer' | 'cert' | 'color' | 'email' | 'filename' | 'file' | 'folder' | 'hidden' | 'integer' | 'uinteger' | 'path' | 'pkey' | 'port' | 'select' | 'time' | 'timestamp' | 'timezone' | 'url' | 'uuid' | `account:${string}` | `hook:${string}` | `keychain:${string}` | 'banner' | 'markdown' | 'html' | 'separator' | string;
+type FormanSchemaFieldType = 'aiagent' | 'account' | 'hook' | 'device' | 'keychain' | 'datastore' | 'udt' | 'scenario' | 'array' | 'collection' | 'text' | 'number' | 'boolean' | 'date' | 'json' | 'buffer' | 'cert' | 'color' | 'email' | 'filename' | 'file' | 'folder' | 'hidden' | 'integer' | 'uinteger' | 'path' | 'pkey' | 'port' | 'select' | 'time' | 'timestamp' | 'timezone' | 'url' | 'uuid' | `account:${string}` | `hook:${string}` | `keychain:${string}` | 'banner' | 'markdown' | 'html' | 'separator' | string;
 /**
  * Validation configuration for Forman Schema fields
  */
@@ -163,10 +163,21 @@ type FormanValidationResult = {
         /** Error message */
         message: string;
     }[];
+    /** States of fields grouped by domain */
+    states?: Record<string, FormanSchemaFieldState>;
+};
+type FormanSchemaFieldState = {
+    mode?: 'chose' | 'edit';
+    label?: string;
+    data?: Record<string, unknown>;
+    nested?: Record<string, FormanSchemaFieldState>;
+    items?: Record<string, FormanSchemaFieldState>[];
 };
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
+    /** Whether to generate states for fields */
+    states?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
 };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { JSONSchema7 } from 'json-schema';
 /**
  * Valid Forman Schema field types
  */
-type FormanSchemaFieldType = 'aiagent' | 'account' | 'hook' | 'keychain' | 'datastore' | 'udt' | 'array' | 'collection' | 'text' | 'number' | 'boolean' | 'date' | 'json' | 'buffer' | 'cert' | 'color' | 'email' | 'filename' | 'file' | 'folder' | 'hidden' | 'integer' | 'uinteger' | 'path' | 'pkey' | 'port' | 'select' | 'time' | 'timestamp' | 'timezone' | 'url' | 'uuid' | `account:${string}` | `hook:${string}` | `keychain:${string}` | 'banner' | 'markdown' | 'html' | 'separator' | string;
+type FormanSchemaFieldType = 'aiagent' | 'account' | 'hook' | 'device' | 'keychain' | 'datastore' | 'udt' | 'scenario' | 'array' | 'collection' | 'text' | 'number' | 'boolean' | 'date' | 'json' | 'buffer' | 'cert' | 'color' | 'email' | 'filename' | 'file' | 'folder' | 'hidden' | 'integer' | 'uinteger' | 'path' | 'pkey' | 'port' | 'select' | 'time' | 'timestamp' | 'timezone' | 'url' | 'uuid' | `account:${string}` | `hook:${string}` | `keychain:${string}` | 'banner' | 'markdown' | 'html' | 'separator' | string;
 /**
  * Validation configuration for Forman Schema fields
  */
@@ -163,10 +163,21 @@ type FormanValidationResult = {
         /** Error message */
         message: string;
     }[];
+    /** States of fields grouped by domain */
+    states?: Record<string, FormanSchemaFieldState>;
+};
+type FormanSchemaFieldState = {
+    mode?: 'chose' | 'edit';
+    label?: string;
+    data?: Record<string, unknown>;
+    nested?: Record<string, FormanSchemaFieldState>;
+    items?: Record<string, FormanSchemaFieldState>[];
 };
 type FormanValidationOptions = {
     /** Unknown fields are not allowed when strict is true */
     strict?: boolean;
+    /** Whether to generate states for fields */
+    states?: boolean;
     /** Remote resource resolver */
     resolveRemote?(path: string, data: Record<string, unknown>): Promise<unknown>;
 };

package/dist/index.js

@@ -1,5 +1,21 @@
 // src/utils.ts
 var FORMAN_VISUAL_TYPES = ["banner", "markdown", "html", "separator"];
+function isVisualType(type) {
+  return FORMAN_VISUAL_TYPES.includes(type);
+}
+var FORMAN_REFERENCE_TYPES = [
+  "account",
+  "hook",
+  "device",
+  "keychain",
+  "datastore",
+  "aiagent",
+  "udt",
+  "scenario"
+];
+function isReferenceType(type) {
+  return FORMAN_REFERENCE_TYPES.includes(type);
+}
 function noEmpty(text) {
   return text?.trim() || void 0;
 }
@@ -13,13 +29,19 @@ function containsIMLExpression(value) {
   if (typeof value !== "string") return false;
   return value.indexOf("{{") > -1 && value.indexOf("}}") > -1;
 }
+function isPrimitiveIMLExpression(value) {
+  if (typeof value !== "string") return false;
+  return value.lastIndexOf("{{") === 0 && value.indexOf("}}") === value.length - 2;
+}
 var API_ENDPOINTS = {
   account: "api://connections/{{kind}}",
   aiagent: "api://ai-agents/v1/agents",
   datastore: "api://data-stores",
   hook: "api://hooks/{{kind}}",
+  device: "api://devices",
   keychain: "api://keys/{{kind}}",
-  udt: "api://data-structures"
+  udt: "api://data-structures",
+  scenario: "api://scenario-list"
 };
 function normalizeFormanFieldType(field) {
   const [type, kind] = field.type.split(":");
@@ -38,6 +60,69 @@ function normalizeFormanFieldType(field) {
     }
   };
 }
+function buildRestoreStructure(items) {
+  const result = {};
+  for (const item of items) {
+    const { domain, path, state } = item;
+    if (!result[domain]) {
+      result[domain] = {};
+    }
+    let current = result[domain];
+    for (const [index, key] of path.entries()) {
+      const nextKey = path[index + 1];
+      const isLastElement = index === path.length - 1;
+      const nextIsNumber = typeof nextKey === "number";
+      if (Array.isArray(current)) {
+        if (typeof key !== "number") {
+          throw new Error("Invalid path");
+        }
+        if (!current[key]) {
+          current[key] = {};
+        }
+        if (nextIsNumber) {
+          if (!current[key].value) {
+            current[key].value = {
+              mode: "chose",
+              items: []
+            };
+          }
+          if (!current[key].value.items) {
+            current[key].value.items = [];
+          }
+          current = current[key].value.items;
+        } else if (isLastElement) {
+          Object.assign(current[key], state);
+        } else {
+          current = current[key];
+        }
+      } else {
+        if (typeof key !== "string") {
+          throw new Error("Invalid path");
+        }
+        if (!current[key]) {
+          current[key] = {};
+        }
+        if (isLastElement) {
+          Object.assign(current[key], state);
+        } else {
+          if (nextIsNumber) {
+            if (!current[key].items) {
+              current[key].items = [];
+              current[key].mode = "chose";
+            }
+            current = current[key].items;
+          } else {
+            if (!current[key].nested) {
+              current[key].nested = {};
+            }
+            current = current[key].nested;
+          }
+        }
+      }
+    }
+  }
+  return result;
+}
 
 // src/forman.ts
 var SchemaConversionError = class extends Error {
@@ -149,7 +234,7 @@ function handleCollectionType(field, result, context) {
     required: []
   });
   function addField(subField, tail) {
-    if (FORMAN_VISUAL_TYPES.includes(subField.type)) {
+    if (isVisualType(subField.type)) {
       return;
     }
     if (!subField.name) return;
@@ -394,6 +479,7 @@ async function validateFormanWithDomainsInternal(domains, options) {
     (acc, domain) => {
       acc[domain] = {
         seenFields: /* @__PURE__ */ new Set(),
+        fieldStates: [],
         validateFields: (fields, context) => {
           return validateFormanValue(
             domains[domain].values,
@@ -451,11 +537,14 @@ async function validateFormanWithDomainsInternal(domains, options) {
   }
   return {
     valid: errors.length === 0,
-    errors
+    errors,
+    states: errors.length === 0 && options?.states ? buildRestoreStructure(
+      Object.keys(domains).map((domain) => roots[domain].fieldStates.map((state) => ({ domain, ...state }))).flat()
+    ) : void 0
   };
 }
 async function validateFormanValue(value, field, context) {
-  if (FORMAN_VISUAL_TYPES.includes(field.type)) {
+  if (isVisualType(field.type)) {
     return {
       valid: true,
       errors: []
@@ -483,7 +572,7 @@ async function validateFormanValue(value, field, context) {
   const expectedType = FORMAN_TYPE_MAP2[normalizedField.type];
   let actualType = typeof value;
   if (actualType === "object" && Array.isArray(value)) actualType = "array";
-  if (expectedType && expectedType !== actualType) {
+  if (expectedType && expectedType !== actualType && !isPrimitiveIMLExpression(value)) {
     return {
       valid: false,
       errors: [
@@ -495,6 +584,24 @@ async function validateFormanValue(value, field, context) {
       ]
     };
   }
+  if (containsIMLExpression(value)) {
+    if (normalizedField.mappable === false) {
+      return {
+        valid: false,
+        errors: [
+          {
+            domain: context.domain,
+            path: context.path.join("."),
+            message: "Value contains prohibited IML expression."
+          }
+        ]
+      };
+    }
+    return {
+      valid: true,
+      errors: []
+    };
+  }
   switch (normalizedField.type) {
     case "collection":
       return handleCollectionType2(value, normalizedField, context);
@@ -503,10 +610,12 @@ async function validateFormanValue(value, field, context) {
     case "select":
     case "account":
     case "hook":
+    case "device":
     case "keychain":
     case "datastore":
     case "aiagent":
     case "udt":
+    case "scenario":
     case "file":
     case "folder":
       return handleSelectType2(value, normalizedField, context);
@@ -546,7 +655,7 @@ async function handleCollectionType2(value, field, context) {
           };
         }
       }
-      if (FORMAN_VISUAL_TYPES.includes(subField.type)) {
+      if (isVisualType(subField.type)) {
         continue;
       }
       if (!subField.name) {
@@ -563,7 +672,7 @@ async function handleCollectionType2(value, field, context) {
         path: [...path, subField.name],
         validateNestedFields: async (fields, context2) => {
           for (const subField2 of fields) {
-            if (FORMAN_VISUAL_TYPES.includes(subField2.type)) {
+            if (isVisualType(subField2.type)) {
               continue;
             }
             if (!subField2.name) {
@@ -610,7 +719,7 @@ async function handleArrayType2(value, field, context) {
       const result = await validateFormanValue(
         item,
         Array.isArray(field.spec) ? { name: index.toString(), type: "collection", spec: field.spec } : Object.assign({}, field.spec, { name: index.toString() }),
-        { ...context, path: [...context.path, index.toString()] }
+        { ...context, path: [...context.path, index] }
       );
       errors.push(...result.errors);
     }
@@ -714,6 +823,15 @@ async function handleSelectType2(value, field, context) {
         ]
       };
     }
+    if (item.label) {
+      context.roots[context.domain].fieldStates.push({
+        path: context.path,
+        state: {
+          mode: isReferenceType(field.type) ? void 0 : "chose",
+          label: item.label
+        }
+      });
+    }
     if (item.nested) nested = item.nested;
   }
   if (nested) {
@@ -782,18 +900,6 @@ async function handleNestedFields(nested, value, field, context) {
 }
 async function handlePrimitiveType2(value, field, context) {
   const errors = [];
-  if (containsIMLExpression(value)) {
-    return {
-      valid: true,
-      errors
-    };
-  }
-  if (errors.length > 0) {
-    return {
-      valid: false,
-      errors
-    };
-  }
   if (field.validate) {
     if (typeof value === "string") {
       if (field.validate.pattern && !new RegExp(

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/forman-schema",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",