@aifabrix/builder 2.32.3 → 2.33.1

package/lib/validation/validate.js

@@ -11,13 +11,14 @@
 
 const fs = require('fs');
 const path = require('path');
-const chalk = require('chalk');
 const validator = require('./validator');
 const { resolveExternalFiles } = require('../utils/schema-resolver');
 const { loadExternalSystemSchema, loadExternalDataSourceSchema, detectSchemaType } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { detectAppType } = require('../utils/paths');
-const logger = require('../utils/logger');
+const { displayValidationResults } = require('./validate-display');
+const { generateControllerManifest } = require('../generator/external-controller-manifest');
+const { validateControllerManifest } = require('./external-manifest-validator');
 
 /**
  * Validates a file path (detects type and validates)
@@ -204,6 +205,8 @@ async function validateExternalFile(filePath, type) {
  * @async
  * @function validateAppOrFile
  * @param {string} appOrFile - Application name or file path
+ * @param {Object} [options] - Validation options
+ * @param {string} [options.type] - Forced application type (external)
  * @returns {Promise<Object>} Validation result with aggregated results
  * @throws {Error} If validation fails
  *
@@ -277,158 +280,191 @@ function loadVariablesAndCheckExternalIntegration(variablesPath, appValidation)
   return null;
 }
 
-async function validateAppOrFile(appOrFile) {
-  if (!appOrFile || typeof appOrFile !== 'string') {
-    throw new Error('App name or file path is required');
-  }
-
-  const isFilePath = fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile();
-  if (isFilePath) {
-    return await validateFilePath(appOrFile);
-  }
-
-  const appName = appOrFile;
-  const { appPath, isExternal } = await detectAppType(appName);
-  const appValidation = await validator.validateApplication(appName);
-  const rbacValidation = await validateRbacForExternalSystem(isExternal, appName);
-
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const earlyReturn = loadVariablesAndCheckExternalIntegration(variablesPath, appValidation);
-  if (earlyReturn) {
-    return earlyReturn;
+/**
+ * Validates application configuration step
+ * @async
+ * @function validateApplicationStep
+ * @param {string} appName - Application name
+ * @returns {Promise<Object>} Application validation result
+ */
+async function validateApplicationStep(appName) {
+  try {
+    const appValidation = await validator.validateApplication(appName);
+    return {
+      valid: appValidation.valid,
+      errors: appValidation.errors || [],
+      warnings: appValidation.warnings || []
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [error.message],
+      warnings: []
+    };
   }
-
-  const externalValidations = await validateExternalFilesForApp(appName);
-  return aggregateValidationResults(appValidation, externalValidations, rbacValidation);
 }
 
 /**
- * Displays validation results in a user-friendly format
- *
- * @function displayValidationResults
- * @param {Object} result - Validation result from validateAppOrFile
- */
-/**
- * Displays application validation results
- * @function displayApplicationValidation
- * @param {Object} application - Application validation result
+ * Validates individual component files step
+ * @async
+ * @function validateComponentsStep
+ * @param {string} appName - Application name
+ * @returns {Promise<Object>} Components validation result
  */
-function displayApplicationValidation(application) {
-  if (!application) {
-    return;
-  }
+async function validateComponentsStep(appName) {
+  try {
+    const externalValidations = await validateExternalFilesForApp(appName);
+    const componentErrors = [];
+    const componentWarnings = [];
+    const componentFiles = [];
+
+    externalValidations.forEach(validation => {
+      componentFiles.push({
+        file: validation.file,
+        type: validation.type,
+        valid: validation.valid,
+        path: validation.path
+      });
 
-  logger.log(chalk.blue('\nApplication:'));
-  if (application.valid) {
-    logger.log(chalk.green('  ✓ Application configuration is valid'));
-  } else {
-    logger.log(chalk.red('  ✗ Application configuration has errors:'));
-    application.errors.forEach(error => {
-      logger.log(chalk.red(`    • ${error}`));
-    });
-  }
-  if (application.warnings && application.warnings.length > 0) {
-    application.warnings.forEach(warning => {
-      logger.log(chalk.yellow(`    ⚠ ${warning}`));
+      if (!validation.valid) {
+        componentErrors.push(`${validation.file} (${validation.type}): ${validation.errors.join(', ')}`);
+      }
+      if (validation.warnings && validation.warnings.length > 0) {
+        componentWarnings.push(`${validation.file}: ${validation.warnings.join(', ')}`);
+      }
     });
+
+    return {
+      valid: componentErrors.length === 0,
+      errors: componentErrors,
+      warnings: componentWarnings,
+      files: componentFiles
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [error.message],
+      warnings: [],
+      files: []
+    };
   }
 }
 
 /**
- * Displays external files validation results
- * @function displayExternalFilesValidation
- * @param {Array} externalFiles - External files validation results
+ * Validates full deployment manifest step
+ * @async
+ * @function validateManifestStep
+ * @param {string} appName - Application name
+ * @returns {Promise<Object>} Manifest validation result
  */
-function displayExternalFilesValidation(externalFiles) {
-  if (!externalFiles || externalFiles.length === 0) {
-    return;
+async function validateManifestStep(appName) {
+  try {
+    const manifest = await generateControllerManifest(appName);
+    const manifestValidation = await validateControllerManifest(manifest);
+    return {
+      valid: manifestValidation.valid,
+      errors: manifestValidation.errors || [],
+      warnings: manifestValidation.warnings || []
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`Failed to validate manifest: ${error.message}`],
+      warnings: []
+    };
   }
-
-  logger.log(chalk.blue('\nExternal Integration Files:'));
-  externalFiles.forEach(file => {
-    if (file.valid) {
-      logger.log(chalk.green(`  ✓ ${file.file} (${file.type})`));
-    } else {
-      logger.log(chalk.red(`  ✗ ${file.file} (${file.type}):`));
-      file.errors.forEach(error => {
-        logger.log(chalk.red(`    • ${error}`));
-      });
-    }
-    if (file.warnings && file.warnings.length > 0) {
-      file.warnings.forEach(warning => {
-        logger.log(chalk.yellow(`    ⚠ ${warning}`));
-      });
-    }
-  });
 }
 
 /**
- * Displays RBAC validation results
- * @function displayRbacValidation
- * @param {Object} rbac - RBAC validation result
+ * Validates external system completely (components + full manifest)
+ * Performs step-by-step validation: application config → components → full manifest
+ *
+ * @async
+ * @function validateExternalSystemComplete
+ * @param {string} appName - Application name
+ * @returns {Promise<Object>} Complete validation result with step-by-step results
+ * @throws {Error} If validation fails critically
+ *
+ * @example
+ * const result = await validateExternalSystemComplete('my-hubspot');
+ * // Returns: { valid: true, errors: [], warnings: [], steps: {...} }
  */
-function displayRbacValidation(rbac) {
-  if (!rbac) {
-    return;
+async function validateExternalSystemComplete(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
   }
 
-  logger.log(chalk.blue('\nRBAC Configuration:'));
-  if (rbac.valid) {
-    logger.log(chalk.green('  ✓ RBAC configuration is valid'));
-  } else {
-    logger.log(chalk.red('  ✗ RBAC configuration has errors:'));
-    rbac.errors.forEach(error => {
-      logger.log(chalk.red(`    • ${error}`));
-    });
-  }
-  if (rbac.warnings && rbac.warnings.length > 0) {
-    rbac.warnings.forEach(warning => {
-      logger.log(chalk.yellow(`    ⚠ ${warning}`));
-    });
+  const steps = {
+    application: { valid: false, errors: [], warnings: [] },
+    components: { valid: false, errors: [], warnings: [], files: [] },
+    manifest: { valid: false, errors: [], warnings: [] }
+  };
+
+  // Step 1: Validate Application Config
+  steps.application = await validateApplicationStep(appName);
+
+  // Step 2: Validate Individual Components
+  steps.components = await validateComponentsStep(appName);
+
+  // If components have errors, return early (don't validate manifest)
+  if (!steps.components.valid) {
+    return {
+      valid: false,
+      errors: [...steps.application.errors, ...steps.components.errors],
+      warnings: [...steps.application.warnings, ...steps.components.warnings],
+      steps
+    };
   }
+
+  // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
+  steps.manifest = await validateManifestStep(appName);
+
+  // Aggregate Results
+  const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];
+  const allWarnings = [...steps.application.warnings, ...steps.components.warnings, ...steps.manifest.warnings];
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings,
+    steps
+  };
 }
 
-function displayValidationResults(result) {
-  if (result.valid) {
-    logger.log(chalk.green('\n✓ Validation passed!'));
-  } else {
-    logger.log(chalk.red('\n✗ Validation failed!'));
+async function validateAppOrFile(appOrFile, options = {}) {
+  if (!appOrFile || typeof appOrFile !== 'string') {
+    throw new Error('App name or file path is required');
   }
 
-  displayApplicationValidation(result.application);
-  displayExternalFilesValidation(result.externalFiles);
-  displayRbacValidation(result.rbac);
-
-  // Display file validation (for direct file validation)
-  if (result.file) {
-    logger.log(chalk.blue(`\nFile: ${result.file}`));
-    logger.log(chalk.blue(`Type: ${result.type}`));
-    if (result.valid) {
-      logger.log(chalk.green('  ✓ File is valid'));
-    } else {
-      logger.log(chalk.red('  ✗ File has errors:'));
-      result.errors.forEach(error => {
-        logger.log(chalk.red(`    • ${error}`));
-      });
-    }
-    if (result.warnings && result.warnings.length > 0) {
-      result.warnings.forEach(warning => {
-        logger.log(chalk.yellow(`    ⚠ ${warning}`));
-      });
-    }
+  const isFilePath = fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile();
+  if (isFilePath) {
+    return await validateFilePath(appOrFile);
   }
 
-  // Display aggregated warnings
-  if (result.warnings && result.warnings.length > 0) {
-    logger.log(chalk.yellow('\nWarnings:'));
-    result.warnings.forEach(warning => {
-      logger.log(chalk.yellow(`  • ${warning}`));
-    });
+  const appName = appOrFile;
+  const { appPath, isExternal } = await detectAppType(appName, options);
+
+  // For external systems with --type external flag, use new unified validation
+  if (isExternal && options.type === 'external') {
+    return await validateExternalSystemComplete(appName);
+  }
+
+  const appValidation = await validator.validateApplication(appName);
+  const rbacValidation = await validateRbacForExternalSystem(isExternal, appName);
+
+  const variablesPath = path.join(appPath, 'variables.yaml');
+  const earlyReturn = loadVariablesAndCheckExternalIntegration(variablesPath, appValidation);
+  if (earlyReturn) {
+    return earlyReturn;
   }
+
+  const externalValidations = await validateExternalFilesForApp(appName);
+  return aggregateValidationResults(appValidation, externalValidations, rbacValidation);
 }
 
 module.exports = {
   validateAppOrFile,
+  validateExternalSystemComplete,
   displayValidationResults,
   validateExternalFile,
   validateExternalFilesForApp,

package/lib/validation/validator.js

@@ -98,6 +98,27 @@ function validateExternalIntegrationBlock(variables, errors) {
   }
 }
 
+/**
+ * Validates frontDoorRouting configuration
+ * @function validateFrontDoorRouting
+ * @param {Object} variables - Variables object
+ * @param {string[]} errors - Errors array to append to
+ */
+function validateFrontDoorRouting(variables, errors) {
+  const frontDoor = variables.frontDoorRouting;
+  if (!frontDoor) {
+    return;
+  }
+
+  if (frontDoor.enabled === true && (!frontDoor.host || typeof frontDoor.host !== 'string')) {
+    errors.push('frontDoorRouting.host is required when frontDoorRouting.enabled is true');
+  }
+
+  if (frontDoor.pattern && !String(frontDoor.pattern).startsWith('/')) {
+    errors.push('frontDoorRouting.pattern must start with "/"');
+  }
+}
+
 async function validateVariables(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
@@ -115,6 +136,8 @@ async function validateVariables(appName) {
     validateExternalIntegrationBlock(variables, errors);
   }
 
+  validateFrontDoorRouting(variables, errors);
+
   return {
     valid: valid && errors.length === 0,
     errors,
@@ -152,6 +175,10 @@ function validateRoles(roles) {
     } else {
       roleNames.add(role.value);
     }
+    // Reject Groups (capital G) - must use groups (lowercase)
+    if (role.Groups !== undefined) {
+      errors.push(`Role at index ${index} uses 'Groups' (capital G) but must use 'groups' (lowercase) for schema compatibility`);
+    }
   });
   return errors;
 }
@@ -229,7 +256,9 @@ async function validateEnvTemplate(appName) {
     throw new Error('App name is required and must be a string');
   }
 
-  const templatePath = path.join(process.cwd(), 'builder', appName, 'env.template');
+  // Support both builder/ and integration/ directories using detectAppType
+  const { appPath } = await detectAppType(appName);
+  const templatePath = path.join(appPath, 'env.template');
 
   if (!fs.existsSync(templatePath)) {
     throw new Error(`env.template not found: ${templatePath}`);
@@ -341,15 +370,19 @@ async function validateApplication(appName) {
   const env = await validateEnvTemplate(appName);
 
   const valid = variables.valid && rbac.valid && env.valid;
+  const errors = [...(variables.errors || []), ...(rbac.errors || []), ...(env.errors || [])];
+  const warnings = [...(variables.warnings || []), ...(rbac.warnings || []), ...(env.warnings || [])];
 
   return {
     valid,
     variables,
     rbac,
     env,
+    errors,
+    warnings,
     summary: {
-      totalErrors: variables.errors.length + rbac.errors.length + env.errors.length,
-      totalWarnings: variables.warnings.length + rbac.warnings.length + env.warnings.length
+      totalErrors: errors.length,
+      totalWarnings: warnings.length
     }
   };
 }

package/lib/validation/wizard-config-validator.js

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Wizard configuration validator for wizard.yaml files
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+const Ajv = require('ajv');
+const wizardConfigSchema = require('../schema/wizard-config.schema.json');
+
+/**
+ * Resolve environment variable references in a value
+ * Supports ${VAR_NAME} syntax
+ * @function resolveEnvVar
+ * @param {string} value - Value that may contain env var references
+ * @returns {string} Resolved value
+ */
+function resolveEnvVar(value) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  return value.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+    const envValue = process.env[varName];
+    if (envValue === undefined) {
+      throw new Error(`Environment variable '${varName}' is not defined`);
+    }
+    return envValue;
+  });
+}
+
+/**
+ * Recursively resolve environment variables in an object
+ * @function resolveEnvVarsInObject
+ * @param {Object} obj - Object to process
+ * @returns {Object} Object with resolved env vars
+ */
+function resolveEnvVarsInObject(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+  if (typeof obj === 'string') {
+    return resolveEnvVar(obj);
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(item => resolveEnvVarsInObject(item));
+  }
+  if (typeof obj === 'object') {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = resolveEnvVarsInObject(value);
+    }
+    return result;
+  }
+  return obj;
+}
+
+/**
+ * Format AJV validation errors into user-friendly messages
+ * @function formatValidationErrors
+ * @param {Object[]} errors - AJV validation errors
+ * @returns {string[]} Formatted error messages
+ */
+function formatValidationErrors(errors) {
+  if (!errors || errors.length === 0) {
+    return [];
+  }
+  return errors.map(error => {
+    const path = error.instancePath || '/';
+    const message = error.message || 'Unknown validation error';
+    if (error.keyword === 'required') {
+      return `Missing required field: ${error.params.missingProperty}`;
+    }
+    if (error.keyword === 'enum') {
+      return `${path}: ${message}. Allowed values: ${error.params.allowedValues.join(', ')}`;
+    }
+    if (error.keyword === 'pattern') {
+      return `${path}: ${message}`;
+    }
+    if (error.keyword === 'additionalProperties') {
+      return `${path}: Unknown property '${error.params.additionalProperty}'`;
+    }
+    return `${path}: ${message}`;
+  });
+}
+
+/**
+ * Load and parse wizard.yaml file
+ * @async
+ * @function loadWizardConfig
+ * @param {string} configPath - Path to wizard.yaml file
+ * @returns {Promise<Object>} Parsed configuration object
+ * @throws {Error} If file cannot be read or parsed
+ */
+async function loadWizardConfig(configPath) {
+  const resolvedPath = path.resolve(configPath);
+  try {
+    await fs.access(resolvedPath);
+    const content = await fs.readFile(resolvedPath, 'utf8');
+    const config = yaml.load(content);
+    if (!config || typeof config !== 'object') {
+      throw new Error('Configuration file is empty or invalid');
+    }
+    return config;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Configuration file not found: ${resolvedPath}`);
+    }
+    if (error.name === 'YAMLException') {
+      throw new Error(`Invalid YAML syntax: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validate wizard configuration against schema
+ * @function validateWizardConfigSchema
+ * @param {Object} config - Configuration object to validate
+ * @returns {Object} Validation result with valid flag and errors
+ */
+function validateWizardConfigSchema(config) {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(wizardConfigSchema);
+  const valid = validate(config);
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validate.errors)
+  };
+}
+
+/**
+ * Validate file path exists (for openapi-file source type)
+ * @function validateFilePath
+ * @param {string} filePath - Path to validate
+ * @param {string} basePath - Base path for relative paths
+ * @returns {Promise<Object>} Validation result with valid flag and errors
+ */
+async function validateFilePath(filePath, basePath) {
+  const baseDir = path.resolve(basePath);
+  const resolvedPath = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(baseDir, filePath);
+  if (!path.isAbsolute(filePath)) {
+    const baseWithSep = baseDir.endsWith(path.sep) ? baseDir : `${baseDir}${path.sep}`;
+    if (!resolvedPath.startsWith(baseWithSep)) {
+      return {
+        valid: false,
+        errors: [`OpenAPI file path must be within: ${baseDir}`]
+      };
+    }
+  }
+  try {
+    await fs.access(resolvedPath);
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`OpenAPI file not found: ${resolvedPath}`]
+    };
+  }
+  return { valid: true, errors: [] };
+}
+
+/**
+ * Validate schema and resolve environment variables
+ * @function validateSchemaAndResolveEnvVars
+ * @param {Object} config - Configuration object
+ * @param {boolean} shouldResolveEnvVars - Whether to resolve env vars
+ * @returns {Object} Result with valid flag, errors, and config
+ */
+function validateSchemaAndResolveEnvVars(config, shouldResolveEnvVars) {
+  if (shouldResolveEnvVars) {
+    try {
+      config = resolveEnvVarsInObject(config);
+    } catch (error) {
+      return { valid: false, errors: [error.message], config };
+    }
+  }
+  const schemaResult = validateWizardConfigSchema(config);
+  if (!schemaResult.valid) {
+    return { valid: false, errors: schemaResult.errors, config };
+  }
+  return { valid: true, errors: [], config };
+}
+
+/**
+ * Perform additional semantic validations
+ * @function performSemanticValidations
+ * @param {Object} config - Configuration object
+ * @param {string} configPath - Path to config file
+ * @param {boolean} validateFilePaths - Whether to validate file paths
+ * @returns {Promise<Object>} Validation result with errors array
+ */
+async function performSemanticValidations(config, configPath, validateFilePaths) {
+  const errors = [];
+  if (validateFilePaths && config.source?.type === 'openapi-file' && config.source?.filePath) {
+    const basePath = path.dirname(path.resolve(configPath));
+    const fileResult = await validateFilePath(config.source.filePath, basePath);
+    if (!fileResult.valid) {
+      errors.push(...fileResult.errors);
+    }
+  }
+  if (config.mode === 'add-datasource' && !config.systemIdOrKey) {
+    errors.push('\'systemIdOrKey\' is required when mode is \'add-datasource\'');
+  }
+  return errors;
+}
+
+/**
+ * Validate wizard configuration with all checks
+ * @async
+ * @function validateWizardConfig
+ * @param {string} configPath - Path to wizard.yaml file
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.resolveEnvVars=true] - Whether to resolve env vars
+ * @param {boolean} [options.validateFilePaths=true] - Whether to validate file paths
+ * @returns {Promise<Object>} Validation result with valid flag, errors, and config
+ */
+async function validateWizardConfig(configPath, options = {}) {
+  const { resolveEnvVars: shouldResolveEnvVars = true, validateFilePaths = true } = options;
+  let config;
+  try {
+    config = await loadWizardConfig(configPath);
+  } catch (error) {
+    return { valid: false, errors: [error.message], config: null };
+  }
+  const schemaResult = validateSchemaAndResolveEnvVars(config, shouldResolveEnvVars);
+  if (!schemaResult.valid) {
+    return schemaResult;
+  }
+  config = schemaResult.config;
+  const errors = await performSemanticValidations(config, configPath, validateFilePaths);
+  return { valid: errors.length === 0, errors, config };
+}
+
+/**
+ * Display validation results to console
+ * @function displayValidationResults
+ * @param {Object} result - Validation result
+ * @param {boolean} result.valid - Whether validation passed
+ * @param {string[]} result.errors - Array of error messages
+ */
+function displayValidationResults(result) {
+  const chalk = require('chalk');
+  if (result.valid) {
+    // eslint-disable-next-line no-console
+    console.log(chalk.green('Wizard configuration is valid'));
+  } else {
+    // eslint-disable-next-line no-console
+    console.log(chalk.red('✗ Wizard configuration validation failed:'));
+    result.errors.forEach(error => {
+      // eslint-disable-next-line no-console
+      console.log(chalk.red(`  - ${error}`));
+    });
+  }
+}
+
+module.exports = {
+  loadWizardConfig,
+  validateWizardConfig,
+  validateWizardConfigSchema,
+  resolveEnvVar,
+  resolveEnvVarsInObject,
+  formatValidationErrors,
+  displayValidationResults
+};