@aifabrix/builder 2.31.0 → 2.32.1

package/lib/{generator-external.js → generator/external.js}

@@ -11,8 +11,8 @@
 const fs = require('fs');
 const path = require('path');
 const Ajv = require('ajv');
-const { detectAppType, getDeployJsonPath } = require('./utils/paths');
-const { loadVariables, loadRbac } = require('./generator-helpers');
+const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { loadVariables, loadRbac } = require('./helpers');
 
 /**
  * Generates external system <app-name>-deploy.json by loading the system JSON file
@@ -24,56 +24,86 @@ const { loadVariables, loadRbac } = require('./generator-helpers');
  * @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);
+/**
+ * Resolves system file path from variables
+ * @function resolveSystemFilePath
+ * @param {Object} variables - Variables configuration
+ * @param {string} appPath - Application path
+ * @param {string} appName - Application name
+ * @returns {string} System file path
+ * @throws {Error} If file not found
+ */
+function resolveSystemFilePath(variables, appPath, appName) {
   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
+  return systemFilePath;
+}
+
+/**
+ * Merges RBAC into system JSON
+ * @function mergeRbacIntoSystemJson
+ * @param {Object} systemJson - System JSON object
+ * @param {Object|null} rbac - RBAC configuration
+ */
+function mergeRbacIntoSystemJson(systemJson, rbac) {
+  if (!rbac) {
+    return;
+  }
+
+  // Priority: roles/permissions in system JSON > rbac.yaml (if both exist, prefer JSON)
+  if (rbac.roles && (!systemJson.roles || systemJson.roles.length === 0)) {
+    systemJson.roles = rbac.roles;
+  }
+  if (rbac.permissions && (!systemJson.permissions || systemJson.permissions.length === 0)) {
+    systemJson.permissions = rbac.permissions;
+  }
+}
+
+/**
+ * Loads and parses system file
+ * @async
+ * @function loadSystemFileContent
+ * @param {string} systemFilePath - System file path
+ * @returns {Promise<Object>} Parsed system JSON
+ */
+async function loadSystemFileContent(systemFilePath) {
   const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  const systemJson = JSON.parse(systemContent);
+  return JSON.parse(systemContent);
+}
+
+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');
+  }
+
+  const systemFilePath = resolveSystemFilePath(variables, appPath, appName);
+  const systemJson = await loadSystemFileContent(systemFilePath);
 
   // Load rbac.yaml from app directory (similar to regular apps)
   const rbacPath = path.join(appPath, 'rbac.yaml');
   const rbac = loadRbac(rbacPath);
-
-  // Merge rbac into systemJson if present
-  // Priority: roles/permissions in system JSON > rbac.yaml (if both exist, prefer JSON)
-  if (rbac) {
-    if (rbac.roles && (!systemJson.roles || systemJson.roles.length === 0)) {
-      systemJson.roles = rbac.roles;
-    }
-    if (rbac.permissions && (!systemJson.permissions || systemJson.permissions.length === 0)) {
-      systemJson.permissions = rbac.permissions;
-    }
-  }
+  mergeRbacIntoSystemJson(systemJson, rbac);
 
   // Write it as <app-name>-deploy.json (consistent naming)
+  const deployJsonPath = getDeployJsonPath(appName, 'external', true);
   const jsonContent = JSON.stringify(systemJson, null, 2);
   await fs.promises.writeFile(deployJsonPath, jsonContent, { mode: 0o644, encoding: 'utf8' });
 
@@ -242,22 +272,22 @@ function validateDatasourceSchemas(datasourceJsons, externalDatasourceSchema, aj
  * @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);
+/**
+ * Loads and validates external integration configuration
+ * @async
+ * @function loadExternalIntegrationConfig
+ * @param {string} appPath - Application path
+ * @returns {Promise<Object>} Variables and schema base path
+ * @throws {Error} If configuration is invalid
+ */
+async function loadExternalIntegrationConfig(appPath) {
   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 and merge RBAC
   const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
   const systemFiles = variables.externalIntegration.systems || [];
 
@@ -265,18 +295,17 @@ async function generateExternalSystemApplicationSchema(appName) {
     throw new Error('No system files specified in externalIntegration.systems');
   }
 
-  const systemJson = await loadSystemFile(appPath, schemaBasePath, systemFiles[0]);
-
-  // Load datasource files
-  const datasourceFiles = variables.externalIntegration.dataSources || [];
-  const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
-
-  // Build application-schema.json structure
-  const applicationSchema = buildBaseSchema(systemJson, datasourceJsons, variables.externalIntegration.version);
+  return { variables, schemaBasePath, systemFiles };
+}
 
-  // Validate individual components against their schemas
-  const externalSystemSchema = require('./schema/external-system.schema.json');
-  const externalDatasourceSchema = require('./schema/external-datasource.schema.json');
+/**
+ * Prepares schemas for validation
+ * @function prepareSchemasForValidation
+ * @returns {Object} Prepared schemas
+ */
+function prepareSchemasForValidation() {
+  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
   const datasourceSchemaToAdd = { ...externalDatasourceSchema };
@@ -284,6 +313,18 @@ async function generateExternalSystemApplicationSchema(appName) {
     delete datasourceSchemaToAdd.$schema;
   }
 
+  return { externalSystemSchema, datasourceSchemaToAdd };
+}
+
+/**
+ * Validates application schema components
+ * @function validateApplicationSchemaComponents
+ * @param {Object} systemJson - System JSON
+ * @param {Object[]} datasourceJsons - Array of datasource JSONs
+ * @param {Object} externalSystemSchema - External system schema
+ * @param {Object} datasourceSchemaToAdd - Datasource schema
+ */
+function validateApplicationSchemaComponents(systemJson, datasourceJsons, externalSystemSchema, datasourceSchemaToAdd) {
   const ajv = new Ajv({ allErrors: true, strict: false, removeAdditional: false });
 
   // Validate system against external-system schema
@@ -291,6 +332,28 @@ async function generateExternalSystemApplicationSchema(appName) {
 
   // Validate datasources against external-datasource schema
   validateDatasourceSchemas(datasourceJsons, datasourceSchemaToAdd, ajv);
+}
+
+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 { variables, schemaBasePath, systemFiles } = await loadExternalIntegrationConfig(appPath);
+
+  const systemJson = await loadSystemFile(appPath, schemaBasePath, systemFiles[0]);
+
+  // Load datasource files
+  const datasourceFiles = variables.externalIntegration.dataSources || [];
+  const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
+
+  // Build application-schema.json structure
+  const applicationSchema = buildBaseSchema(systemJson, datasourceJsons, variables.externalIntegration.version);
+
+  // Validate individual components against their schemas
+  const { externalSystemSchema, datasourceSchemaToAdd } = prepareSchemasForValidation();
+  validateApplicationSchemaComponents(systemJson, datasourceJsons, externalSystemSchema, datasourceSchemaToAdd);
 
   return applicationSchema;
 }

package/lib/{github-generator.js → generator/github.js}

@@ -21,7 +21,7 @@ Handlebars.registerHelper('contains', (array, value) => {
  * @returns {Promise<Object>} Object mapping step names to their compiled content
  */
 async function loadStepTemplates(stepNames = []) {
-  const stepsDir = path.join(__dirname, '..', 'templates', 'github', 'steps');
+  const stepsDir = path.join(__dirname, '..', '..', 'templates', 'github', 'steps');
   const stepTemplates = {};
 
   for (const stepName of stepNames) {
@@ -64,7 +64,7 @@ async function generateGithubWorkflows(appPath, config, options = {}) {
     const templateContext = await getTemplateContext(config, options, stepTemplates);
 
     // Load and compile templates
-    const templatesDir = path.join(__dirname, '..', 'templates', 'github');
+    const templatesDir = path.join(__dirname, '..', '..', 'templates', 'github');
     const templateFiles = await fs.readdir(templatesDir);
 
     const generatedFiles = [];
@@ -103,17 +103,48 @@ async function generateGithubWorkflows(appPath, config, options = {}) {
  * @param {Object} stepTemplates - Compiled step templates
  * @returns {Promise<Object>} Template context
  */
-async function getTemplateContext(config, options = {}, stepTemplates = {}) {
-  const githubSteps = options.githubSteps || [];
+/**
+ * Builds base context for template rendering
+ * @function buildBaseContext
+ * @param {Object} config - Application configuration
+ * @param {Object} options - Additional options
+ * @returns {Object} Base context object
+ */
+/**
+ * Determines file extension based on language
+ * @function getFileExtension
+ * @param {string} language - Programming language
+ * @returns {string} File extension
+ */
+function getFileExtension(language) {
+  return language === 'python' ? 'py' : 'js';
+}
 
-  // Render step templates with the base context
-  const renderedSteps = {};
-  const baseContext = {
+/**
+ * Determines source directory based on language
+ * @function getSourceDir
+ * @param {string} language - Programming language
+ * @returns {string} Source directory
+ */
+function getSourceDir(language) {
+  return language === 'python' ? 'src' : 'lib';
+}
+
+/**
+ * Builds base configuration values
+ * @function buildBaseConfigValues
+ * @param {Object} config - Configuration object
+ * @param {Object} options - Options object
+ * @returns {Object} Base configuration values
+ */
+function buildBaseConfigValues(config, options) {
+  const language = config.language || 'typescript';
+  return {
     appName: config.appName || 'myapp',
     mainBranch: options.mainBranch || 'main',
-    language: config.language || 'typescript',
-    fileExtension: config.language === 'python' ? 'py' : 'js',
-    sourceDir: config.language === 'python' ? 'src' : 'lib',
+    language: language,
+    fileExtension: getFileExtension(language),
+    sourceDir: getSourceDir(language),
     buildCommand: options.buildCommand || 'npm run build',
     port: config.port || 3000,
     database: config.database || false,
@@ -121,11 +152,37 @@ async function getTemplateContext(config, options = {}, stepTemplates = {}) {
     storage: config.storage || false,
     authentication: config.authentication || false
   };
+}
 
+function buildBaseContext(config, options) {
+  return buildBaseConfigValues(config, options);
+}
+
+/**
+ * Renders step templates
+ * @function renderStepTemplates
+ * @param {Object} stepTemplates - Step templates object
+ * @param {Object} baseContext - Base context for rendering
+ * @returns {Object} Rendered steps
+ */
+function renderStepTemplates(stepTemplates, baseContext) {
+  const renderedSteps = {};
   for (const [stepName, template] of Object.entries(stepTemplates)) {
     renderedSteps[stepName] = template(baseContext);
   }
+  return renderedSteps;
+}
 
+/**
+ * Builds final template context
+ * @function buildFinalTemplateContext
+ * @param {Object} baseContext - Base context
+ * @param {Object} options - Additional options
+ * @param {Object} renderedSteps - Rendered step templates
+ * @returns {Object} Final template context
+ */
+function buildFinalTemplateContext(baseContext, options, renderedSteps) {
+  const githubSteps = options.githubSteps || [];
   return {
     ...baseContext,
     uploadCoverage: options.uploadCoverage !== false,
@@ -136,6 +193,12 @@ async function getTemplateContext(config, options = {}, stepTemplates = {}) {
   };
 }
 
+async function getTemplateContext(config, options = {}, stepTemplates = {}) {
+  const baseContext = buildBaseContext(config, options);
+  const renderedSteps = renderStepTemplates(stepTemplates, baseContext);
+  return buildFinalTemplateContext(baseContext, options, renderedSteps);
+}
+
 /**
  * Generate a specific workflow file
  * @param {string} appPath - Path to application directory
@@ -151,7 +214,7 @@ async function generateWorkflowFile(appPath, templateName, config, options = {})
     await fs.mkdir(workflowsDir, { recursive: true });
 
     // Load template
-    const templatePath = path.join(__dirname, '..', 'templates', 'github', `${templateName}.hbs`);
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'github', `${templateName}.hbs`);
     const templateContent = await fs.readFile(templatePath, 'utf8');
 
     // Compile template
@@ -185,11 +248,15 @@ async function generateWorkflowFile(appPath, templateName, config, options = {})
  * @param {Object} options - Generation options
  * @returns {Object} Validation result
  */
-function validateWorkflowConfig(config, options = {}) {
+/**
+ * Validates required fields
+ * @function validateRequiredFields
+ * @param {Object} config - Application configuration
+ * @returns {string[]} Array of error messages
+ */
+function validateRequiredFields(config) {
   const errors = [];
-  const warnings = [];
 
-  // Validate required fields
   if (!config.appName) {
     errors.push('Application name is required');
   }
@@ -202,6 +269,19 @@ function validateWorkflowConfig(config, options = {}) {
     errors.push('Language must be either typescript or python');
   }
 
+  return errors;
+}
+
+/**
+ * Validates optional fields
+ * @function validateOptionalFields
+ * @param {Object} config - Application configuration
+ * @param {Object} options - Generation options
+ * @returns {string[]} Array of error messages
+ */
+function validateOptionalFields(config, options) {
+  const errors = [];
+
   // Validate port
   if (config.port && (config.port < 1 || config.port > 65535)) {
     errors.push('Port must be between 1 and 65535');
@@ -212,7 +292,18 @@ function validateWorkflowConfig(config, options = {}) {
     errors.push('Main branch name contains invalid characters');
   }
 
-  // Warnings
+  return errors;
+}
+
+/**
+ * Collects validation warnings
+ * @function collectValidationWarnings
+ * @param {Object} config - Application configuration
+ * @returns {string[]} Array of warning messages
+ */
+function collectValidationWarnings(config) {
+  const warnings = [];
+
   if (config.language === 'python' && !config.database) {
     warnings.push('Python applications typically require a database');
   }
@@ -221,6 +312,16 @@ function validateWorkflowConfig(config, options = {}) {
     warnings.push('Authentication typically requires a database for user storage');
   }
 
+  return warnings;
+}
+
+function validateWorkflowConfig(config, options = {}) {
+  const errors = [
+    ...validateRequiredFields(config),
+    ...validateOptionalFields(config, options)
+  ];
+  const warnings = collectValidationWarnings(config);
+
   return {
     valid: errors.length === 0,
     errors,

package/lib/{generator-helpers.js → generator/helpers.js}

@@ -157,11 +157,13 @@ function validatePortalInput(portalInput, variableName) {
  * @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
+/**
+ * Creates a map of portalInput configurations from variables config
+ * @function createPortalInputMap
+ * @param {Object|null} variablesConfig - Configuration from variables.yaml
+ * @returns {Map} Map of variable names to portalInput configurations
+ */
+function createPortalInputMap(variablesConfig) {
   const portalInputMap = new Map();
   if (variablesConfig && variablesConfig.configuration && Array.isArray(variablesConfig.configuration)) {
     for (const configItem of variablesConfig.configuration) {
@@ -172,55 +174,103 @@ function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
       }
     }
   }
+  return portalInputMap;
+}
 
-  for (const line of lines) {
-    const trimmed = line.trim();
+/**
+ * Parses a single environment variable line
+ * @function parseEnvironmentVariableLine
+ * @param {string} line - Line to parse
+ * @returns {Object|null} Parsed variable object or null if invalid
+ */
+function parseEnvironmentVariableLine(line) {
+  const trimmed = line.trim();
 
-    // Skip empty lines and comments
-    if (!trimmed || trimmed.startsWith('#')) {
-      continue;
-    }
+  // Skip empty lines and comments
+  if (!trimmed || trimmed.startsWith('#')) {
+    return null;
+  }
 
-    // Parse KEY=VALUE format
-    const equalIndex = trimmed.indexOf('=');
-    if (equalIndex === -1) {
-      continue;
-    }
+  // Parse KEY=VALUE format
+  const equalIndex = trimmed.indexOf('=');
+  if (equalIndex === -1) {
+    return null;
+  }
 
-    const key = trimmed.substring(0, equalIndex).trim();
-    const value = trimmed.substring(equalIndex + 1).trim();
+  const key = trimmed.substring(0, equalIndex).trim();
+  const value = trimmed.substring(equalIndex + 1).trim();
 
-    if (!key || !value) {
-      continue;
-    }
+  if (!key || !value) {
+    return null;
+  }
 
-    // Determine location and required status
-    let location = 'variable';
-    let required = false;
+  return { key, value };
+}
 
-    if (value.startsWith('kv://')) {
-      location = 'keyvault';
-      required = true;
-    }
+/**
+ * Determines location and required status for a variable
+ * @function determineVariableLocation
+ * @param {string} value - Variable value
+ * @param {string} key - Variable key
+ * @returns {Object} Object with location and required properties
+ */
+function determineVariableLocation(value, key) {
+  let location = 'variable';
+  let required = false;
 
-    // Check if it's a sensitive variable
-    const sensitiveKeys = ['password', 'secret', 'key', 'token', 'auth'];
-    if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) {
-      required = true;
-    }
+  if (value.startsWith('kv://')) {
+    location = 'keyvault';
+    required = true;
+  }
 
-    const configItem = {
-      name: key,
-      value: value.replace('kv://', ''), // Remove kv:// prefix for KeyVault
-      location,
-      required
-    };
+  // Check if it's a sensitive variable
+  const sensitiveKeys = ['password', 'secret', 'key', 'token', 'auth'];
+  if (sensitiveKeys.some(sensitive => key.toLowerCase().includes(sensitive))) {
+    required = true;
+  }
+
+  return { location, required };
+}
 
-    // Merge portalInput if it exists in variables.yaml
-    if (portalInputMap.has(key)) {
-      configItem.portalInput = portalInputMap.get(key);
+/**
+ * Creates a configuration item from parsed variable
+ * @function createConfigItem
+ * @param {string} key - Variable key
+ * @param {string} value - Variable value
+ * @param {string} location - Variable location
+ * @param {boolean} required - Whether variable is required
+ * @param {Map} portalInputMap - Map of portalInput configurations
+ * @returns {Object} Configuration item
+ */
+function createConfigItem(key, value, location, required, portalInputMap) {
+  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);
+  }
+
+  return configItem;
+}
+
+function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
+  const configuration = [];
+  const lines = envTemplate.split('\n');
+  const portalInputMap = createPortalInputMap(variablesConfig);
+
+  for (const line of lines) {
+    const parsed = parseEnvironmentVariableLine(line);
+    if (!parsed) {
+      continue;
     }
 
+    const { location, required } = determineVariableLocation(parsed.value, parsed.key);
+    const configItem = createConfigItem(parsed.key, parsed.value, location, required, portalInputMap);
     configuration.push(configItem);
   }