@aifabrix/builder 2.21.0 → 2.22.0

package/lib/generator.js

@@ -11,116 +11,13 @@
 
 const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
-const Ajv = require('ajv');
-const _secrets = require('./secrets');
 const _keyGenerator = require('./key-generator');
 const _validator = require('./validator');
 const builders = require('./generator-builders');
 const { detectAppType, getDeployJsonPath } = require('./utils/paths');
 const splitFunctions = require('./generator-split');
-
-/**
- * Loads variables.yaml file
- * @param {string} variablesPath - Path to variables.yaml
- * @returns {Object} Parsed variables
- * @throws {Error} If file not found or invalid YAML
- */
-function loadVariables(variablesPath) {
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const variablesContent = fs.readFileSync(variablesPath, 'utf8');
-  try {
-    return { content: variablesContent, parsed: yaml.load(variablesContent) };
-  } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
-  }
-}
-
-/**
- * Loads env.template file
- * @param {string} templatePath - Path to env.template
- * @returns {string} Template content
- * @throws {Error} If file not found
- */
-function loadEnvTemplate(templatePath) {
-  if (!fs.existsSync(templatePath)) {
-    throw new Error(`env.template not found: ${templatePath}`);
-  }
-  return fs.readFileSync(templatePath, 'utf8');
-}
-
-/**
- * Loads rbac.yaml file if it exists
- * @param {string} rbacPath - Path to rbac.yaml
- * @returns {Object|null} Parsed RBAC configuration or null
- * @throws {Error} If file exists but has invalid YAML
- */
-function loadRbac(rbacPath) {
-  if (!fs.existsSync(rbacPath)) {
-    return null;
-  }
-
-  const rbacContent = fs.readFileSync(rbacPath, 'utf8');
-  try {
-    return yaml.load(rbacContent);
-  } catch (error) {
-    throw new Error(`Invalid YAML syntax in rbac.yaml: ${error.message}`);
-  }
-}
-
-/**
- * Generates external system <app-name>-deploy.json by loading the system JSON file
- * For external systems, the system JSON file is already created and we just need to reference it
- * @async
- * @function generateExternalSystemDeployJson
- * @param {string} appName - Name of the application
- * @param {string} appPath - Path to application directory (integration or builder)
- * @returns {Promise<string>} Path to generated <app-name>-deploy.json file
- * @throws {Error} If generation fails
- */
-async function generateExternalSystemDeployJson(appName, appPath) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
-
-  if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
-  }
-
-  // For external systems, the system JSON file should be in the same folder
-  // Check if it already exists (should be <app-name>-deploy.json)
-  const deployJsonPath = getDeployJsonPath(appName, 'external', true);
-  const systemFileName = variables.externalIntegration.systems && variables.externalIntegration.systems.length > 0
-    ? variables.externalIntegration.systems[0]
-    : `${appName}-deploy.json`;
-
-  // Resolve system file path (schemaBasePath is usually './' for same folder)
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
-  const systemFilePath = path.isAbsolute(schemaBasePath)
-    ? path.join(schemaBasePath, systemFileName)
-    : path.join(appPath, schemaBasePath, systemFileName);
-
-  // If system file doesn't exist, throw error (it should be created manually or via external-system-generator)
-  if (!fs.existsSync(systemFilePath)) {
-    throw new Error(`External system file not found: ${systemFilePath}. Please create it first.`);
-  }
-
-  // Read the system JSON file
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  const systemJson = JSON.parse(systemContent);
-
-  // Write it as <app-name>-deploy.json (consistent naming)
-  const jsonContent = JSON.stringify(systemJson, null, 2);
-  await fs.promises.writeFile(deployJsonPath, jsonContent, { mode: 0o644, encoding: 'utf8' });
-
-  return deployJsonPath;
-}
+const { loadVariables, loadEnvTemplate, loadRbac, parseEnvironmentVariables } = require('./generator-helpers');
+const { generateExternalSystemDeployJson, generateExternalSystemApplicationSchema } = require('./generator-external');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -188,139 +85,6 @@ async function generateDeployJson(appName) {
   return jsonPath;
 }
 
-/**
- * Validates portalInput structure against schema requirements
- * @param {Object} portalInput - Portal input configuration to validate
- * @param {string} variableName - Variable name for error messages
- * @throws {Error} If portalInput structure is invalid
- */
-function validatePortalInput(portalInput, variableName) {
-  if (!portalInput || typeof portalInput !== 'object') {
-    throw new Error(`Invalid portalInput for variable '${variableName}': must be an object`);
-  }
-
-  // Check required fields
-  if (!portalInput.field || typeof portalInput.field !== 'string') {
-    throw new Error(`Invalid portalInput for variable '${variableName}': field is required and must be a string`);
-  }
-
-  if (!portalInput.label || typeof portalInput.label !== 'string') {
-    throw new Error(`Invalid portalInput for variable '${variableName}': label is required and must be a string`);
-  }
-
-  // Validate field type
-  const validFieldTypes = ['password', 'text', 'textarea', 'select'];
-  if (!validFieldTypes.includes(portalInput.field)) {
-    throw new Error(`Invalid portalInput for variable '${variableName}': field must be one of: ${validFieldTypes.join(', ')}`);
-  }
-
-  // Validate select field requires options
-  if (portalInput.field === 'select') {
-    if (!portalInput.options || !Array.isArray(portalInput.options) || portalInput.options.length === 0) {
-      throw new Error(`Invalid portalInput for variable '${variableName}': select field requires a non-empty options array`);
-    }
-  }
-
-  // Validate optional fields
-  if (portalInput.placeholder !== undefined && typeof portalInput.placeholder !== 'string') {
-    throw new Error(`Invalid portalInput for variable '${variableName}': placeholder must be a string`);
-  }
-
-  if (portalInput.masked !== undefined && typeof portalInput.masked !== 'boolean') {
-    throw new Error(`Invalid portalInput for variable '${variableName}': masked must be a boolean`);
-  }
-
-  if (portalInput.validation !== undefined) {
-    if (typeof portalInput.validation !== 'object' || Array.isArray(portalInput.validation)) {
-      throw new Error(`Invalid portalInput for variable '${variableName}': validation must be an object`);
-    }
-  }
-
-  if (portalInput.options !== undefined && portalInput.field !== 'select') {
-    // Options should only be present for select fields
-    if (Array.isArray(portalInput.options) && portalInput.options.length > 0) {
-      throw new Error(`Invalid portalInput for variable '${variableName}': options can only be used with select field type`);
-    }
-  }
-}
-
-/**
- * Parses environment variables from env.template and merges portalInput from variables.yaml
- * @param {string} envTemplate - Content of env.template file
- * @param {Object|null} [variablesConfig=null] - Optional configuration from variables.yaml
- * @returns {Array<Object>} Configuration array with merged portalInput
- * @throws {Error} If portalInput structure is invalid
- */
-function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
-  const configuration = [];
-  const lines = envTemplate.split('\n');
-
-  // Create a map of portalInput configurations by variable name
-  const portalInputMap = new Map();
-  if (variablesConfig && variablesConfig.configuration && Array.isArray(variablesConfig.configuration)) {
-    for (const configItem of variablesConfig.configuration) {
-      if (configItem.name && configItem.portalInput) {
-        // Validate portalInput before adding to map
-        validatePortalInput(configItem.portalInput, configItem.name);
-        portalInputMap.set(configItem.name, configItem.portalInput);
-      }
-    }
-  }
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) {
-      continue;
-    }
-
-    // Parse KEY=VALUE format
-    const equalIndex = trimmed.indexOf('=');
-    if (equalIndex === -1) {
-      continue;
-    }
-
-    const key = trimmed.substring(0, equalIndex).trim();
-    const value = trimmed.substring(equalIndex + 1).trim();
-
-    if (!key || !value) {
-      continue;
-    }
-
-    // Determine location and required status
-    let location = 'variable';
-    let required = false;
-
-    if (value.startsWith('kv://')) {
-      location = 'keyvault';
-      required = true;
-    }
-
-    // Check if it's a sensitive variable
-    const sensitiveKeys = ['password', 'secret', 'key', 'token', 'auth'];
-    if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) {
-      required = true;
-    }
-
-    const configItem = {
-      name: key,
-      value: value.replace('kv://', ''), // Remove kv:// prefix for KeyVault
-      location,
-      required
-    };
-
-    // Merge portalInput if it exists in variables.yaml
-    if (portalInputMap.has(key)) {
-      configItem.portalInput = portalInputMap.get(key);
-    }
-
-    configuration.push(configItem);
-  }
-
-  return configuration;
-}
-
 async function generateDeployJsonWithValidation(appName) {
   const jsonPath = await generateDeployJson(appName);
   const jsonContent = fs.readFileSync(jsonPath, 'utf8');
@@ -348,135 +112,6 @@ async function generateDeployJsonWithValidation(appName) {
   };
 }
 
-/**
- * Generates application-schema.json structure for external systems
- * Combines system and datasource JSONs into application-level deployment format
- * @async
- * @function generateExternalSystemApplicationSchema
- * @param {string} appName - Application name
- * @returns {Promise<Object>} Application schema object
- * @throws {Error} If generation fails
- */
-async function generateExternalSystemApplicationSchema(appName) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-
-  const { appPath } = await detectAppType(appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
-  // Load variables.yaml
-  const { parsed: variables } = loadVariables(variablesPath);
-
-  if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
-  }
-
-  // Load system file
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
-  const systemFiles = variables.externalIntegration.systems || [];
-
-  if (systemFiles.length === 0) {
-    throw new Error('No system files specified in externalIntegration.systems');
-  }
-
-  const systemFileName = systemFiles[0];
-  const systemFilePath = path.isAbsolute(schemaBasePath)
-    ? path.join(schemaBasePath, systemFileName)
-    : path.join(appPath, schemaBasePath, systemFileName);
-
-  if (!fs.existsSync(systemFilePath)) {
-    throw new Error(`System file not found: ${systemFilePath}`);
-  }
-
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  const systemJson = JSON.parse(systemContent);
-
-  // Load datasource files
-  const datasourceFiles = variables.externalIntegration.dataSources || [];
-  const datasourceJsons = [];
-
-  for (const datasourceFile of datasourceFiles) {
-    const datasourcePath = path.isAbsolute(schemaBasePath)
-      ? path.join(schemaBasePath, datasourceFile)
-      : path.join(appPath, schemaBasePath, datasourceFile);
-
-    if (!fs.existsSync(datasourcePath)) {
-      throw new Error(`Datasource file not found: ${datasourcePath}`);
-    }
-
-    const datasourceContent = await fs.promises.readFile(datasourcePath, 'utf8');
-    const datasourceJson = JSON.parse(datasourceContent);
-    datasourceJsons.push(datasourceJson);
-  }
-
-  // Build application-schema.json structure
-  const applicationSchema = {
-    version: variables.externalIntegration.version || '1.0.0',
-    application: systemJson,
-    dataSources: datasourceJsons
-  };
-
-  // Validate individual components against their schemas
-  const externalSystemSchema = require('./schema/external-system.schema.json');
-  const externalDatasourceSchema = require('./schema/external-datasource.schema.json');
-
-  // For draft-2020-12 schemas, remove $schema to avoid AJV issues (similar to schema-loader.js)
-  const datasourceSchemaToAdd = { ...externalDatasourceSchema };
-  if (datasourceSchemaToAdd.$schema && datasourceSchemaToAdd.$schema.includes('2020-12')) {
-    delete datasourceSchemaToAdd.$schema;
-  }
-
-  const ajv = new Ajv({ allErrors: true, strict: false, removeAdditional: false });
-
-  // Validate application (system) against external-system schema
-  const externalSystemSchemaId = externalSystemSchema.$id || 'https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json';
-  ajv.addSchema(externalSystemSchema, externalSystemSchemaId);
-  const validateSystem = ajv.compile(externalSystemSchema);
-  const systemValid = validateSystem(systemJson);
-
-  if (!systemValid) {
-    // Filter out additionalProperties errors for required properties that aren't defined in schema
-    // This handles schema inconsistencies where authentication is required but not defined in properties
-    const filteredErrors = validateSystem.errors.filter(err => {
-      if (err.keyword === 'additionalProperties' && err.params?.additionalProperty === 'authentication') {
-        // Check if authentication is in required array
-        const required = externalSystemSchema.required || [];
-        if (required.includes('authentication')) {
-          return false; // Ignore this error since authentication is required but not defined
-        }
-      }
-      return true;
-    });
-
-    if (filteredErrors.length > 0) {
-      const errors = filteredErrors.map(err => {
-        const path = err.instancePath || err.schemaPath;
-        return `${path} ${err.message}`;
-      }).join(', ');
-      throw new Error(`System JSON does not match external-system schema: ${errors}`);
-    }
-  }
-
-  // Validate each datasource against external-datasource schema
-  const externalDatasourceSchemaId = datasourceSchemaToAdd.$id || 'https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-datasource.schema.json';
-  ajv.addSchema(datasourceSchemaToAdd, externalDatasourceSchemaId);
-  const validateDatasource = ajv.compile(datasourceSchemaToAdd);
-
-  for (let i = 0; i < datasourceJsons.length; i++) {
-    const datasourceValid = validateDatasource(datasourceJsons[i]);
-    if (!datasourceValid) {
-      const errors = validateDatasource.errors.map(err => {
-        const path = err.instancePath || err.schemaPath;
-        return `${path} ${err.message}`;
-      }).join(', ');
-      throw new Error(`Datasource ${i + 1} (${datasourceJsons[i].key || 'unknown'}) does not match external-datasource schema: ${errors}`);
-    }
-  }
-
-  return applicationSchema;
-}
-
 module.exports = {
   generateDeployJson,
   generateDeployJsonWithValidation,

package/lib/schema/external-system.schema.json

@@ -7,7 +7,7 @@
     "key": "external-system-schema",
     "name": "External System Configuration Schema",
     "description": "JSON schema for validating ExternalSystem configuration files",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "type": "schema",
     "category": "integration",
     "author": "AI Fabrix Team",
@@ -27,6 +27,17 @@
     ],
     "dependencies": [],
     "changelog": [
+      {
+        "version": "1.1.0",
+        "date": "2025-12-01T00:00:00Z",
+        "changes": [
+          "Added RBAC roles and permissions support",
+          "RBAC roles/permissions are registered with miso-controller during deployment",
+          "Roles support Azure AD group mapping via Groups property",
+          "Permissions reference roles and are used for access control"
+        ],
+        "breaking": false
+      },
       {
         "version": "1.0.0",
         "date": "2024-01-01T00:00:00Z",
@@ -274,6 +285,86 @@
       "items": {
         "type": "string"
       }
+    },
+    "roles": {
+      "type": "array",
+      "description": "External system roles for Azure AD group mapping",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "value",
+          "description"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable role name",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "value": {
+            "type": "string",
+            "description": "Role identifier (used in JWT and ACL)",
+            "pattern": "^[a-z-]+$"
+          },
+          "description": {
+            "type": "string",
+            "description": "Role description",
+            "minLength": 1,
+            "maxLength": 500
+          },
+          "Groups": {
+            "type": "array",
+            "description": "Azure AD groups mapped to this role",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "permissions": {
+      "type": "array",
+      "description": "External system permissions with role mappings for access control",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "roles",
+          "description"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Permission identifier (e.g., 'documentstore:read', 'flowise:dev:access')",
+            "pattern": "^[a-z0-9-:]+$",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "roles": {
+            "type": "array",
+            "description": "Roles that have this permission",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z-]+$",
+              "minLength": 1,
+              "maxLength": 50
+            },
+            "minItems": 1
+          },
+          "description": {
+            "type": "string",
+            "description": "Permission description",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "additionalProperties": false
+      }
     }
   },
   "additionalProperties": false

package/lib/utils/api-error-handler.js

@@ -25,9 +25,10 @@ const { formatNetworkError } = require('./error-formatters/network-errors');
 /**
  * Formats error for display in CLI
  * @param {Object} apiResponse - API response object from makeApiCall
+ * @param {string} [controllerUrl] - Controller URL (optional)
  * @returns {string} Formatted error message
  */
-function formatApiError(apiResponse) {
+function formatApiError(apiResponse, controllerUrl = null) {
   if (!apiResponse || apiResponse.success !== false) {
     return chalk.red('❌ Unknown error occurred');
   }
@@ -41,7 +42,13 @@ function formatApiError(apiResponse) {
   const statusCode = apiResponse.status || 0;
   const isNetworkError = apiResponse.network === true;
 
-  const parsed = parseErrorResponse(errorResponse, statusCode, isNetworkError);
+  // Add controller URL to error data
+  // Handle both object and string error responses
+  const errorData = typeof errorResponse === 'object' && errorResponse !== null
+    ? { ...errorResponse, controllerUrl: controllerUrl }
+    : { message: String(errorResponse || ''), controllerUrl: controllerUrl };
+
+  const parsed = parseErrorResponse(errorData, statusCode, isNetworkError);
   return parsed.formatted;
 }
 

package/lib/utils/app-register-api.js

@@ -25,41 +25,51 @@ const { formatApiError } = require('./api-error-handler');
 async function callRegisterApi(apiUrl, token, environment, registrationData) {
   // Use centralized API client
   const authConfig = { type: 'bearer', token: token };
-  const response = await registerApplication(apiUrl, environment, authConfig, registrationData);
+  try {
+    const response = await registerApplication(apiUrl, environment, authConfig, registrationData);
 
-  if (!response.success) {
-    const formattedError = response.formattedError || formatApiError(response);
-    logger.error(formattedError);
+    if (!response.success) {
+      const formattedError = response.formattedError || formatApiError(response, apiUrl);
+      logger.error(formattedError);
+      logger.error(chalk.gray(`\nController URL: ${apiUrl}`));
 
-    // For validation errors (400, 422), show the request payload for debugging
-    if (response.status === 400 || response.status === 422) {
-      logger.error(chalk.gray('\nRequest payload:'));
-      logger.error(chalk.gray(JSON.stringify(registrationData, null, 2)));
-      logger.error('');
-      logger.error(chalk.gray('Check your variables.yaml file and ensure all required fields are correctly set.'));
+      // For validation errors (400, 422), show the request payload for debugging
+      if (response.status === 400 || response.status === 422) {
+        logger.error(chalk.gray('\nRequest payload:'));
+        logger.error(chalk.gray(JSON.stringify(registrationData, null, 2)));
+        logger.error('');
+        logger.error(chalk.gray('Check your variables.yaml file and ensure all required fields are correctly set.'));
+      }
+
+      process.exit(1);
     }
 
+    // Handle API response structure:
+    // registerApplication returns: { success: true, data: <API response> }
+    // API response can be:
+    // 1. Direct format: { application: {...}, credentials: {...} }
+    // 2. Wrapped format: { success: true, data: { application: {...}, credentials: {...} } }
+    const apiResponse = response.data;
+    if (apiResponse && apiResponse.data && apiResponse.data.application) {
+      // Wrapped format: use apiResponse.data
+      return apiResponse.data;
+    } else if (apiResponse && apiResponse.application) {
+      // Direct format: use apiResponse directly
+      return apiResponse;
+    }
+    // Fallback: return apiResponse as-is (shouldn't happen, but handle gracefully)
+    logger.error(chalk.red('❌ Invalid response: missing application data'));
+    logger.error(chalk.gray(`\nController URL: ${apiUrl}`));
+    logger.error(chalk.gray('\nFull response for debugging:'));
+    logger.error(chalk.gray(JSON.stringify(response, null, 2)));
     process.exit(1);
+  } catch (error) {
+    // Include controller URL in error context
+    logger.error(chalk.red('❌ Registration API call failed'));
+    logger.error(chalk.gray(`Controller URL: ${apiUrl}`));
+    logger.error(chalk.gray(`Error: ${error.message}`));
+    throw error;
   }
-
-  // Handle API response structure:
-  // registerApplication returns: { success: true, data: <API response> }
-  // API response can be:
-  // 1. Direct format: { application: {...}, credentials: {...} }
-  // 2. Wrapped format: { success: true, data: { application: {...}, credentials: {...} } }
-  const apiResponse = response.data;
-  if (apiResponse && apiResponse.data && apiResponse.data.application) {
-    // Wrapped format: use apiResponse.data
-    return apiResponse.data;
-  } else if (apiResponse && apiResponse.application) {
-    // Direct format: use apiResponse directly
-    return apiResponse;
-  }
-  // Fallback: return apiResponse as-is (shouldn't happen, but handle gracefully)
-  logger.error(chalk.red('❌ Invalid response: missing application data'));
-  logger.error(chalk.gray('\nFull response for debugging:'));
-  logger.error(chalk.gray(JSON.stringify(response, null, 2)));
-  process.exit(1);
 }
 
 module.exports = { callRegisterApi };