@aifabrix/builder 2.39.2 → 2.40.0

package/lib/external-system/deploy-helpers.js

@@ -11,11 +11,10 @@
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const { detectAppType, getDeployJsonPath } = require('../utils/paths');
 
 /**
- * Loads variables.yaml for an application
+ * Loads application config for an application
  * @async
  * @function loadVariablesYaml
  * @param {string} appName - Application name
@@ -23,11 +22,11 @@ const { detectAppType, getDeployJsonPath } = require('../utils/paths');
  * @throws {Error} If file cannot be loaded
  */
 async function loadVariablesYaml(appName) {
-  // Detect app type and get correct path (integration or builder)
   const { appPath } = await detectAppType(appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const content = await fs.readFile(variablesPath, 'utf8');
-  return yaml.load(content);
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+  const { loadConfigFile } = require('../utils/config-format');
+  const configPath = resolveApplicationConfigPath(appPath);
+  return loadConfigFile(configPath);
 }
 
 /**

package/lib/external-system/deploy.js

@@ -13,6 +13,8 @@ const chalk = require('chalk');
 const { getDeploymentAuth } = require('../utils/token-manager');
 const logger = require('../utils/logger');
 const { resolveControllerUrl } = require('../utils/controller-url');
+const { detectAppType } = require('../utils/paths');
+const { logOfflinePathWhenType } = require('../utils/cli-utils');
 const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
 const { getExternalSystem } = require('../api/external-systems.api');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
@@ -132,11 +134,14 @@ async function prepareDeploymentConfig(appName, _options) {
  */
 async function deployExternalSystem(appName, options = {}) {
   try {
+    const { appPath } = await detectAppType(appName);
+    logOfflinePathWhenType(appPath);
+
     logger.log(chalk.blue(`\n🚀 Deploying external system: ${appName}`));
 
     // Step 0: Validate before deployment (same as validate command)
     logger.log(chalk.blue('🔍 Validating external system before deployment...'));
-    const validationResult = await validateExternalSystemComplete(appName);
+    const validationResult = await validateExternalSystemComplete(appName, options);
 
     if (!validationResult.valid) {
       displayValidationResults(validationResult);
@@ -146,7 +151,7 @@ async function deployExternalSystem(appName, options = {}) {
     logger.log(chalk.green('✓ Validation passed, proceeding with deployment...'));
 
     // Step 1: Generate controller manifest (validated, ready for deployment)
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
 
     // Step 2: Get deployment configuration (auth, controller URL, etc.)
     const { environment, controllerUrl, authConfig } = await prepareDeploymentConfig(appName, options);

package/lib/external-system/download-helpers.js

@@ -11,14 +11,14 @@
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
 /**
- * Generates variables.yaml content for downloaded system
+ * Generates application.yaml content for downloaded system
  * @param {string} systemKey - System key
  * @param {Object} application - External system configuration
  * @param {Array} dataSources - Array of datasource configurations
  * @returns {Object} Variables YAML object
  */
 function generateVariablesYaml(systemKey, application, dataSources) {
-  const systemFileName = `${systemKey}-system.json`;
+  const systemFileName = `${systemKey}-system.yaml`;
   const datasourceFiles = dataSources.map(ds => {
     // Extract datasource key (remove system key prefix if present)
     const datasourceKey = ds.key || '';
@@ -29,7 +29,7 @@ function generateVariablesYaml(systemKey, application, dataSources) {
       const entityType = ds.entityType || ds.entityKey || datasourceKey.split('-').pop();
       datasourceKeyOnly = entityType;
     }
-    return `${systemKey}-datasource-${datasourceKeyOnly}.json`;
+    return `${systemKey}-datasource-${datasourceKeyOnly}.yaml`;
   });
 
   return {
@@ -73,7 +73,7 @@ function generateReadme(systemKey, application, dataSources) {
     return {
       entityType: datasourceKeyOnly,
       displayName: ds.displayName || ds.name || ds.key || `Datasource ${index + 1}`,
-      fileName: `${systemKey}-datasource-${datasourceKeyOnly}.json`
+      fileName: `${systemKey}-datasource-${datasourceKeyOnly}.yaml`
     };
   });
 

package/lib/external-system/download.js

@@ -19,6 +19,7 @@ const { getDeploymentAuth } = require('../utils/token-manager');
 const { getConfig } = require('../core/config');
 const { detectAppType } = require('../utils/paths');
 const logger = require('../utils/logger');
+const { writeConfigFile } = require('../utils/config-format');
 const { generateEnvTemplate } = require('../utils/external-system-env-helpers');
 const { generateVariablesYaml, generateReadme } = require('./download-helpers');
 const { resolveControllerUrl } = require('../utils/controller-url');
@@ -201,9 +202,9 @@ async function downloadSystemConfiguration(dataplaneUrl, systemKey, authConfig)
  * @returns {Promise<string>} System file path
  */
 async function generateSystemFile(tempDir, systemKey, application) {
-  const systemFileName = `${systemKey}-system.json`;
+  const systemFileName = `${systemKey}-system.yaml`;
   const systemFilePath = path.join(tempDir, systemFileName);
-  await fs.writeFile(systemFilePath, JSON.stringify(application, null, 2), 'utf8');
+  writeConfigFile(systemFilePath, application);
   return systemFilePath;
 }
 
@@ -230,9 +231,9 @@ async function generateDatasourceFiles(tempDir, systemKey, dataSources) {
         const entityType = datasource.entityType || datasource.entityKey || datasourceKey.split('-').pop();
         datasourceKeyOnly = entityType;
       }
-      const datasourceFileName = `${systemKey}-datasource-${datasourceKeyOnly}.json`;
+      const datasourceFileName = `${systemKey}-datasource-${datasourceKeyOnly}.yaml`;
       const datasourceFilePath = path.join(tempDir, datasourceFileName);
-      await fs.writeFile(datasourceFilePath, JSON.stringify(datasource, null, 2), 'utf8');
+      writeConfigFile(datasourceFilePath, datasource);
       datasourceFiles.push(datasourceFilePath);
     } catch (error) {
       datasourceErrors.push(new Error(`Failed to write datasource ${datasource.key}: ${error.message}`));
@@ -242,7 +243,7 @@ async function generateDatasourceFiles(tempDir, systemKey, dataSources) {
 }
 
 /**
- * Generates configuration files (variables.yaml, env.template, README.md)
+ * Generates configuration files (application.yaml, env.template, README.md)
  * @async
  * @function generateConfigFiles
  * @param {string} tempDir - Temporary directory
@@ -252,9 +253,9 @@ async function generateDatasourceFiles(tempDir, systemKey, dataSources) {
  * @returns {Promise<Object>} Object with file paths
  */
 async function generateConfigFiles(tempDir, systemKey, application, dataSources) {
-  // Generate variables.yaml
+  // Generate application.yaml
   const variables = generateVariablesYaml(systemKey, application, dataSources);
-  const variablesPath = path.join(tempDir, 'variables.yaml');
+  const variablesPath = path.join(tempDir, 'application.yaml');
   await fs.writeFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: 120, noRefs: true }), 'utf8');
 
   // Generate env.template
@@ -307,7 +308,7 @@ async function moveFilesToFinalLocation(tempDir, finalPath, systemKey, filePaths
   const systemFileName = `${systemKey}-system.json`;
   const filesToMove = [
     { from: filePaths.systemFilePath, to: path.join(finalPath, systemFileName) },
-    { from: filePaths.variablesPath, to: path.join(finalPath, 'variables.yaml') },
+    { from: filePaths.variablesPath, to: path.join(finalPath, 'application.yaml') },
     { from: filePaths.envTemplatePath, to: path.join(finalPath, 'env.template') },
     { from: filePaths.readmePath, to: path.join(finalPath, 'README.md') }
   ];
@@ -347,8 +348,8 @@ function handleDryRun(systemKey, dataplaneUrl) {
   logger.log(chalk.gray(`  ${dataplaneUrl}/api/v1/external/systems/${systemKey}/config`));
   logger.log(chalk.yellow('\nWould create:'));
   logger.log(chalk.gray(`  integration/${systemKey}/`));
-  logger.log(chalk.gray(`  integration/${systemKey}/variables.yaml`));
-  logger.log(chalk.gray(`  integration/${systemKey}/${systemKey}-system.json`));
+  logger.log(chalk.gray(`  integration/${systemKey}/application.yaml`));
+  logger.log(chalk.gray(`  integration/${systemKey}/${systemKey}-system.yaml`));
   logger.log(chalk.gray(`  integration/${systemKey}/env.template`));
   logger.log(chalk.gray(`  integration/${systemKey}/README.md`));
 }

package/lib/external-system/generator.js

@@ -12,9 +12,10 @@
 const fs = require('fs').promises;
 const path = require('path');
 const handlebars = require('handlebars');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
 
 // Register Handlebars helper for equality check
 handlebars.registerHelper('eq', (a, b) => a === b);
@@ -52,11 +53,12 @@ async function generateExternalSystemTemplate(appPath, systemKey, config) {
     };
 
     const rendered = template(context);
+    const parsed = JSON.parse(rendered);
 
-    // Generate in same folder as variables.yaml (new structure)
-    // Use naming: <app-name>-system.json
-    const outputPath = path.join(appPath, `${systemKey}-system.json`);
-    await fs.writeFile(outputPath, rendered, 'utf8');
+    // Generate in same folder as application.yaml (new structure)
+    // Use naming: <app-name>-system.yaml
+    const outputPath = path.join(appPath, `${systemKey}-system.yaml`);
+    writeConfigFile(outputPath, parsed);
 
     return outputPath;
   } catch (error) {
@@ -98,15 +100,16 @@ async function generateExternalDataSourceTemplate(appPath, datasourceKey, config
     };
 
     const rendered = template(context);
+    const datasourceConfig = JSON.parse(rendered);
 
-    // Generate in same folder as variables.yaml (new structure)
-    // Use naming: <app-name>-datasource-<datasource-key>.json
+    // Generate in same folder as application.yaml (new structure)
+    // Use naming: <app-name>-datasource-<datasource-key>.yaml
     // Extract datasource key (remove system key prefix if present)
     const datasourceKeyOnly = datasourceKey.includes('-') && datasourceKey.startsWith(`${config.systemKey}-`)
       ? datasourceKey.substring(config.systemKey.length + 1)
       : datasourceKey;
-    const outputPath = path.join(appPath, `${config.systemKey}-datasource-${datasourceKeyOnly}.json`);
-    await fs.writeFile(outputPath, rendered, 'utf8');
+    const outputPath = path.join(appPath, `${config.systemKey}-datasource-${datasourceKeyOnly}.yaml`);
+    writeConfigFile(outputPath, datasourceConfig);
 
     return outputPath;
   } catch (error) {
@@ -160,7 +163,7 @@ async function generateExternalSystemFiles(appPath, appName, config) {
       logger.log(chalk.green(`✓ Generated datasource: ${path.basename(datasourcePath)}`));
     }
 
-    // Update variables.yaml with externalIntegration block
+    // Update application.yaml with externalIntegration block
     await updateVariablesYamlWithExternalIntegration(appPath, systemKey, datasourcePaths);
 
     return {
@@ -173,7 +176,7 @@ async function generateExternalSystemFiles(appPath, appName, config) {
 }
 
 /**
- * Updates variables.yaml with externalIntegration block
+ * Updates application.yaml with externalIntegration block
  * @async
  * @function updateVariablesYamlWithExternalIntegration
  * @param {string} appPath - Application directory path
@@ -183,23 +186,22 @@ async function generateExternalSystemFiles(appPath, appName, config) {
  */
 async function updateVariablesYamlWithExternalIntegration(appPath, systemKey, datasourcePaths) {
   try {
-    const variablesPath = path.join(appPath, 'variables.yaml');
-    const variablesContent = await fs.readFile(variablesPath, 'utf8');
-    const variables = yaml.load(variablesContent);
+    const configPath = resolveApplicationConfigPath(appPath);
+    const variables = loadConfigFile(configPath);
 
     // Add externalIntegration block
     // Files are in same folder, so schemaBasePath is './'
     variables.externalIntegration = {
       schemaBasePath: './',
-      systems: [`${systemKey}-system.json`],
+      systems: [`${systemKey}-system.yaml`],
       dataSources: datasourcePaths.map(p => path.basename(p)),
       autopublish: true,
       version: '1.0.0'
     };
 
-    await fs.writeFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: 120, noRefs: true }), 'utf8');
+    writeConfigFile(configPath, variables);
   } catch (error) {
-    throw new Error(`Failed to update variables.yaml: ${error.message}`);
+    throw new Error(`Failed to update application config: ${error.message}`);
   }
 }
 

package/lib/external-system/test.js

@@ -12,7 +12,6 @@
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const chalk = require('chalk');
 const testHelpers = require('../utils/external-system-test-helpers');
 const { retryApiCall } = require('../utils/external-system-test-helpers');
@@ -39,30 +38,26 @@ const {
 } = require('./test-execution');
 
 /**
- * Loads and parses variables.yaml file
+ * Loads and parses application config file
  * @async
  * @function loadVariablesYamlFile
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {Promise<Object>} Parsed variables
- * @throws {Error} If file not found or invalid YAML
+ * @throws {Error} If file not found or invalid
  */
 async function loadVariablesYamlFile(variablesPath) {
-  if (!fsSync.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const variablesContent = await fs.readFile(variablesPath, 'utf8');
+  const { loadConfigFile } = require('../utils/config-format');
   try {
-    const variables = yaml.load(variablesContent);
+    const variables = loadConfigFile(variablesPath);
     if (!variables.externalIntegration) {
-      throw new Error('externalIntegration block not found in variables.yaml');
+      throw new Error('externalIntegration block not found in application config');
     }
     return variables;
   } catch (error) {
     if (error.message.includes('externalIntegration')) {
       throw error;
     }
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
+    throw new Error(`Application config: ${error.message}`);
   }
 }
 
@@ -152,9 +147,9 @@ async function loadDatasourceFiles(datasourceFiles, schemaBasePath, appPath) {
  */
 async function loadExternalSystemFiles(appName) {
   const { appPath } = await detectAppType(appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
-  const variables = await loadVariablesYamlFile(variablesPath);
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+  const configPath = resolveApplicationConfigPath(appPath);
+  const variables = await loadVariablesYamlFile(configPath);
 
   const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
   const systemFiles = variables.externalIntegration.systems || [];

package/lib/generator/builders.js

@@ -290,7 +290,7 @@ function addHealthCheckToDeployment(deployment, variables) {
  * @param {Object|null} rbac - RBAC configuration
  */
 function addRolesAndPermissions(deployment, variables, rbac) {
-  // Priority: variables.yaml > rbac.yaml
+  // Priority: application.yaml > rbac.yaml
   if (variables.roles) {
     deployment.roles = variables.roles;
   } else if (rbac && rbac.roles) {

package/lib/generator/external-controller-manifest.js

@@ -11,6 +11,7 @@
 
 const path = require('path');
 const { detectAppType } = require('../utils/paths');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadSystemFile, loadDatasourceFiles } = require('./external');
 const { loadVariables, loadRbac } = require('./helpers');
 
@@ -42,18 +43,18 @@ function mergeRbacIntoSystemJson(systemJson, rbac) {
  * @param {Object} options - Options with optional appPath
  * @returns {Promise<string>} Application path
  */
-async function resolveAppPath(appName, options) {
-  if (options.appPath) {
+async function resolveAppPath(appName, options = {}) {
+  if (options && options.appPath) {
     return options.appPath;
   }
-  const detected = await detectAppType(appName, { type: 'external' });
+  const detected = await detectAppType(appName);
   return detected.appPath;
 }
 
 /**
  * Extracts app metadata from variables
  * @function extractAppMetadata
- * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} variables - Parsed application config
  * @param {string} appName - Application name
  * @returns {Object} App metadata { appKey, displayName, description }
  */
@@ -98,59 +99,55 @@ async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
  * const manifest = await generateControllerManifest('my-hubspot');
  * // Returns: { key, displayName, description, type: "external", system: {...}, dataSources: [...] }
  */
+function normalizeSchemaBasePath(schemaBasePath, appPath, appName) {
+  const base = path.normalize(schemaBasePath || './').replace(/[/\\]+$/, '');
+  return base === path.join('integration', appName) ? './' : (schemaBasePath || './');
+}
+
 async function generateControllerManifest(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-
   const appPath = await resolveAppPath(appName, options);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
-
+  const { parsed: variables } = loadVariables(resolveApplicationConfigPath(appPath));
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
-
   const metadata = extractAppMetadata(variables, appName);
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  const schemaBasePath = normalizeSchemaBasePath(
+    variables.externalIntegration.schemaBasePath,
+    appPath,
+    appName
+  );
   const systemFiles = variables.externalIntegration.systems || [];
-
   if (systemFiles.length === 0) {
     throw new Error('No system files specified in externalIntegration.systems');
   }
-
-  const systemJson = await loadSystemWithRbac(appPath, schemaBasePath, systemFiles[0]);
-  const datasourceFiles = variables.externalIntegration.dataSources || [];
-  const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
-
+  const [systemJson, datasourceJsons] = await Promise.all([
+    loadSystemWithRbac(appPath, schemaBasePath, systemFiles[0]),
+    loadDatasourceFiles(appPath, schemaBasePath, variables.externalIntegration.dataSources || [])
+  ]);
   const appVersion = variables.app?.version || variables.externalIntegration?.version || '1.0.0';
-
-  // Build externalIntegration block (required by application schema for type: "external")
   const externalIntegration = {
-    schemaBasePath: schemaBasePath,
+    schemaBasePath,
     systems: systemFiles,
-    dataSources: datasourceFiles,
-    autopublish: variables.externalIntegration.autopublish !== false, // default true
+    dataSources: variables.externalIntegration.dataSources || [],
+    autopublish: variables.externalIntegration.autopublish !== false,
     version: appVersion
   };
-
-  const manifest = {
+  return {
     key: metadata.appKey,
     displayName: metadata.displayName,
     description: metadata.description,
     type: 'external',
     version: appVersion,
-    externalIntegration: externalIntegration,
-    // Inline system and dataSources for atomic deployment (optional but recommended)
+    externalIntegration,
     system: systemJson,
     dataSources: datasourceJsons,
-    // Explicitly set to false to satisfy conditional schema requirements
     requiresDatabase: false,
     requiresRedis: false,
     requiresStorage: false
   };
-
-  return manifest;
 }
 
 module.exports = {

package/lib/generator/external-schema-utils.js

@@ -56,18 +56,6 @@ function getSystemKey(application) {
   return systemKey;
 }
 
-/**
- * Writes JSON file with formatting
- * @async
- * @function writeJsonFile
- * @param {string} filePath - File path
- * @param {Object} data - JSON data
- * @returns {Promise<void>} Resolves when file is written
- */
-async function writeJsonFile(filePath, data) {
-  await fs.promises.writeFile(filePath, JSON.stringify(data, null, 2), 'utf8');
-}
-
 /**
  * Resolves datasource entity type
  * @function getDatasourceEntityType
@@ -104,7 +92,7 @@ function getDatasourceFileName(systemKey, datasource, index) {
   } else {
     datasourceKeyOnly = getDatasourceEntityType(datasource, index);
   }
-  return `${systemKey}-datasource-${datasourceKeyOnly}.json`;
+  return `${systemKey}-datasource-${datasourceKeyOnly}.yaml`;
 }
 
 /**
@@ -122,14 +110,14 @@ async function writeDatasourceFiles(outputDir, systemKey, dataSources) {
     const datasource = dataSources[i];
     const datasourceFileName = getDatasourceFileName(systemKey, datasource, i);
     const datasourceFilePath = path.join(outputDir, datasourceFileName);
-    await writeJsonFile(datasourceFilePath, datasource);
+    await writeYamlFile(datasourceFilePath, datasource, { indent: 2, lineWidth: 120, noRefs: true });
     datasourceFileNames.push(datasourceFileName);
   }
   return datasourceFileNames;
 }
 
 /**
- * Builds variables.yaml content for external integrations
+ * Builds application config content for external integrations
  * @function buildExternalVariables
  * @param {string} systemKey - System key
  * @param {Object} application - Application schema
@@ -187,14 +175,14 @@ async function writeYamlFile(filePath, data, options) {
  * @returns {Promise<Object>} Paths to generated files
  */
 async function writeSplitExternalSchemaFiles({ outputDir, systemKey, application, dataSources, version }) {
-  const systemFileName = `${systemKey}-system.json`;
+  const systemFileName = `${systemKey}-system.yaml`;
   const systemFilePath = path.join(outputDir, systemFileName);
-  await writeJsonFile(systemFilePath, application);
+  await writeYamlFile(systemFilePath, application, { indent: 2, lineWidth: 120, noRefs: true });
 
   const datasourceFileNames = await writeDatasourceFiles(outputDir, systemKey, dataSources);
   const variables = buildExternalVariables(systemKey, application, systemFileName, datasourceFileNames, version);
 
-  const variablesPath = path.join(outputDir, 'variables.yaml');
+  const variablesPath = path.join(outputDir, 'application.yaml');
   await writeYamlFile(variablesPath, variables, { indent: 2, lineWidth: 120, noRefs: true });
 
   const envTemplatePath = path.join(outputDir, 'env.template');

package/lib/generator/external.js

@@ -12,6 +12,8 @@ const fs = require('fs');
 const path = require('path');
 const Ajv = require('ajv');
 const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { loadConfigFile } = require('../utils/config-format');
 const { loadVariables, loadRbac } = require('./helpers');
 const {
   parseApplicationSchema,
@@ -41,26 +43,29 @@ const {
 function resolveSystemFilePath(variables, appPath, appName) {
   const systemFileName = variables.externalIntegration.systems && variables.externalIntegration.systems.length > 0
     ? variables.externalIntegration.systems[0]
-    : `${appName}-system.json`;
+    : `${appName}-system.yaml`;
 
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  let schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  const normalizedBase = path.normalize(schemaBasePath).replace(/[/\\]+$/, '');
+  if (normalizedBase === path.join('integration', appName)) {
+    schemaBasePath = './';
+  }
   const systemFilePath = path.isAbsolute(schemaBasePath)
     ? path.join(schemaBasePath, systemFileName)
     : path.join(appPath, schemaBasePath, systemFileName);
 
-  // Support both old and new naming for backward compatibility
+  // Support both .yaml and legacy .json for backward compatibility
   if (!fs.existsSync(systemFilePath)) {
-    // Try old naming format
-    const oldSystemFileName = systemFileName.replace(/-system\.json$/, '-deploy.json');
-    const oldSystemFilePath = path.isAbsolute(schemaBasePath)
-      ? path.join(schemaBasePath, oldSystemFileName)
-      : path.join(appPath, schemaBasePath, oldSystemFileName);
-
-    if (fs.existsSync(oldSystemFilePath)) {
-      return oldSystemFilePath;
+    const altFileName = systemFileName.replace(/-system\.yaml$/, '-system.json').replace(/-system\.yml$/, '-system.json');
+    const altSystemFilePath = path.isAbsolute(schemaBasePath)
+      ? path.join(schemaBasePath, altFileName)
+      : path.join(appPath, schemaBasePath, altFileName);
+
+    if (fs.existsSync(altSystemFilePath)) {
+      return altSystemFilePath;
     }
 
-    throw new Error(`External system file not found: ${systemFilePath} (also checked: ${oldSystemFilePath}). Please create it first.`);
+    throw new Error(`External system file not found: ${systemFilePath} (also checked: ${altSystemFilePath}). Please create it first.`);
   }
 
   return systemFilePath;
@@ -87,15 +92,14 @@ function mergeRbacIntoSystemJson(systemJson, rbac) {
 }
 
 /**
- * Loads and parses system file
+ * Loads and parses system file (YAML or JSON)
  * @async
  * @function loadSystemFileContent
  * @param {string} systemFilePath - System file path
- * @returns {Promise<Object>} Parsed system JSON
+ * @returns {Promise<Object>} Parsed system config object
  */
 async function loadSystemFileContent(systemFilePath) {
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  return JSON.parse(systemContent);
+  return loadConfigFile(systemFilePath);
 }
 
 async function generateExternalSystemDeployJson(appName, appPath) {
@@ -103,11 +107,11 @@ async function generateExternalSystemDeployJson(appName, appPath) {
     throw new Error('App name is required and must be a string');
   }
 
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
+  const configPath = resolveApplicationConfigPath(appPath);
+  const { parsed: variables } = loadVariables(configPath);
 
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
 
   const systemFilePath = resolveSystemFilePath(variables, appPath, appName);
@@ -141,11 +145,13 @@ async function loadSystemFile(appPath, schemaBasePath, systemFileName) {
     : path.join(appPath, schemaBasePath, systemFileName);
 
   if (!fs.existsSync(systemFilePath)) {
-    throw new Error(`System file not found: ${systemFilePath}`);
+    const hint = systemFileName.endsWith('-deploy.json')
+      ? ' Use the system definition file (e.g. <app>-system.yaml) in externalIntegration.systems, not the deploy manifest (-deploy.json).'
+      : '';
+    throw new Error(`System file not found: ${systemFilePath}.${hint}`);
   }
 
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  const systemJson = JSON.parse(systemContent);
+  const systemJson = loadConfigFile(systemFilePath);
 
   // Load rbac.yaml from app directory and merge if present
   const rbacPath = path.join(appPath, 'rbac.yaml');
@@ -183,8 +189,7 @@ async function loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles) {
       throw new Error(`Datasource file not found: ${datasourcePath}`);
     }
 
-    const datasourceContent = await fs.promises.readFile(datasourcePath, 'utf8');
-    const datasourceJson = JSON.parse(datasourceContent);
+    const datasourceJson = loadConfigFile(datasourcePath);
     datasourceJsons.push(datasourceJson);
   }
 
@@ -297,11 +302,11 @@ function validateDatasourceSchemas(datasourceJsons, externalDatasourceSchema, aj
  * @throws {Error} If configuration is invalid
  */
 async function loadExternalIntegrationConfig(appPath) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
+  const configPath = resolveApplicationConfigPath(appPath);
+  const { parsed: variables } = loadVariables(configPath);
 
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
 
   const schemaBasePath = variables.externalIntegration.schemaBasePath || './';

package/lib/generator/github.js

@@ -45,7 +45,7 @@ async function loadStepTemplates(stepNames = []) {
 /**
  * Generate GitHub Actions workflow files from templates
  * @param {string} appPath - Path to application directory
- * @param {Object} config - Configuration from variables.yaml
+ * @param {Object} config - Configuration from application.yaml
  * @param {Object} options - Generation options
  * @returns {Promise<string[]>} Array of generated file paths
  */