@aifabrix/builder 2.39.3 → 2.40.0

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
  */

package/lib/generator/helpers.js

@@ -10,24 +10,17 @@
 
 const fs = require('fs');
 const yaml = require('js-yaml');
+const { loadConfigFile } = require('../utils/config-format');
 
 /**
- * Loads variables.yaml file
- * @param {string} variablesPath - Path to variables.yaml
- * @returns {Object} Parsed variables
- * @throws {Error} If file not found or invalid YAML
+ * Loads application config file (application.yaml, application.json, or legacy path) via converter.
+ * @param {string} configPath - Path to application config file
+ * @returns {Object} Object with parsed config: { parsed }
+ * @throws {Error} If file not found or invalid YAML/JSON
  */
-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}`);
-  }
+function loadVariables(configPath) {
+  const parsed = loadConfigFile(configPath);
+  return { parsed };
 }
 
 /**
@@ -151,16 +144,16 @@ function validatePortalInput(portalInput, variableName) {
 }
 
 /**
- * Parses environment variables from env.template and merges portalInput from variables.yaml
+ * Parses environment variables from env.template and merges portalInput from application config
  * @param {string} envTemplate - Content of env.template file
- * @param {Object|null} [variablesConfig=null] - Optional configuration from variables.yaml
+ * @param {Object|null} [variablesConfig=null] - Optional configuration from application.yaml
  * @returns {Array<Object>} Configuration array with merged portalInput
  * @throws {Error} If portalInput structure is invalid
  */
 /**
  * Creates a map of portalInput configurations from variables config
  * @function createPortalInputMap
- * @param {Object|null} variablesConfig - Configuration from variables.yaml
+ * @param {Object|null} variablesConfig - Configuration from application.yaml
  * @returns {Map} Map of variable names to portalInput configurations
  */
 function createPortalInputMap(variablesConfig) {
@@ -250,7 +243,7 @@ function createConfigItem(key, value, location, required, portalInputMap) {
     required
   };
 
-  // Merge portalInput if it exists in variables.yaml
+  // Merge portalInput if it exists in application config
   if (portalInputMap.has(key)) {
     configItem.portalInput = portalInputMap.get(key);
   }

package/lib/generator/index.js

@@ -2,7 +2,7 @@
  * AI Fabrix Builder Deployment JSON Generator
  *
  * This module generates deployment JSON manifests for Miso Controller.
- * Combines variables.yaml, env.template, and rbac.yaml into deployment configuration.
+ * Combines application.yaml, env.template, and rbac.yaml into deployment configuration.
  *
  * @fileoverview Deployment JSON generation for AI Fabrix Builder
  * @author AI Fabrix Team
@@ -13,7 +13,8 @@ const fs = require('fs');
 const path = require('path');
 const _validator = require('../validation/validator');
 const builders = require('./builders');
-const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { detectAppType, getDeployJsonPath, resolveApplicationConfigPath } = require('../utils/paths');
+const { logOfflinePathWhenType } = require('../utils/cli-utils');
 const splitFunctions = require('./split');
 const { loadVariables, loadEnvTemplate, loadRbac, parseEnvironmentVariables } = require('./helpers');
 const { generateExternalSystemApplicationSchema, splitExternalApplicationSchema } = require('./external');
@@ -24,13 +25,13 @@ const { resolveVersionForApp } = require('../utils/image-version');
  * Generates deployment JSON from application configuration files
  * Creates <app-name>-deploy.json for regular apps (consistent naming)
  * For external systems, generates application-schema.json
- * For regular apps, generates deployment manifest from variables.yaml, env.template, rbac.yaml
+ * For regular apps, generates deployment manifest from application.yaml, env.template, rbac.yaml
  *
  * @async
  * @function generateDeployJson
  * @param {string} appName - Name of the application
  * @param {Object} [options] - Generation options
- * @param {string} [options.type] - Forced application type (external)
+ *
  * @returns {Promise<string>} Path to generated deployment JSON file
  * @throws {Error} If generation fails or configuration is invalid
  *
@@ -46,7 +47,7 @@ const { resolveVersionForApp } = require('../utils/image-version');
  * @returns {Object} Loaded configuration files
  */
 function loadDeploymentConfigFiles(appPath, appType, appName) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const variablesPath = resolveApplicationConfigPath(appPath);
   const templatePath = path.join(appPath, 'env.template');
   const rbacPath = path.join(appPath, 'rbac.yaml');
   const jsonPath = getDeployJsonPath(appName, appType, true); // Use new naming
@@ -69,7 +70,7 @@ function loadDeploymentConfigFiles(appPath, appType, appName) {
  * @throws {Error} If validation fails
  */
 function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
-  // Parse environment variables from template and merge portalInput from variables.yaml
+  // Parse environment variables from template and merge portalInput from application config
   const configuration = parseEnvironmentVariables(envTemplate, variables);
 
   // Build deployment manifest (Controller computes deploymentKey from schema)
@@ -93,17 +94,17 @@ function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
  * @param {string} appName - Application name
  * @param {Object} [options] - Options (e.g. type for external)
  * @returns {Promise<{ deployment: Object, appPath: string }>} Manifest and app path
- * @throws {Error} If variables.yaml/env.template missing or generation fails
+ * @throws {Error} If application config/env.template missing or generation fails
  */
 async function buildDeploymentManifestInMemory(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const { isExternal, appPath, appType } = await detectAppType(appName, options);
+  const { isExternal, appPath, appType } = await detectAppType(appName);
 
   if (isExternal) {
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
     return { deployment: manifest, appPath };
   }
 
@@ -124,13 +125,13 @@ async function generateDeployJson(appName, options = {}) {
     throw new Error('App name is required and must be a string');
   }
 
-  // Detect app type and get correct path (integration or builder)
-  const { isExternal, appPath, appType } = await detectAppType(appName, options);
+  // Detect app type and get correct path (integration first, then builder)
+  const { isExternal, appPath, appType } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
 
   // Check if app type is external
   if (isExternal) {
-    // Generate controller-compatible manifest format
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
 
     // Determine system key for file naming
     const systemKey = manifest.key || appName;
@@ -161,8 +162,7 @@ async function generateDeployJsonWithValidation(appName, options = {}) {
   const jsonContent = fs.readFileSync(jsonPath, 'utf8');
   const deployment = JSON.parse(jsonContent);
 
-  // Detect if this is an external system
-  const { isExternal } = await detectAppType(appName, options);
+  const { isExternal } = await detectAppType(appName);
 
   // For external systems, skip deployment JSON validation (they use external system JSON structure)
   if (isExternal) {

package/lib/generator/parse-image.js

@@ -0,0 +1,35 @@
+/**
+ * Parses image reference string into components.
+ * @fileoverview Image reference parser for deployment JSON
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Parses image reference string into components
+ * @function parseImageReference
+ * @param {string} imageString - Full image string (e.g., "registry/name:tag")
+ * @returns {Object} Object with registry, name, and tag
+ */
+function parseImageReference(imageString) {
+  if (!imageString || typeof imageString !== 'string') {
+    return { registry: null, name: null, tag: 'latest' };
+  }
+
+  const parts = imageString.split('/');
+  let registry = null;
+  let nameAndTag = imageString;
+
+  if (parts.length > 1 && parts[0].includes('.')) {
+    registry = parts[0];
+    nameAndTag = parts.slice(1).join('/');
+  }
+
+  const tagIndex = nameAndTag.lastIndexOf(':');
+  const name = tagIndex !== -1 ? nameAndTag.substring(0, tagIndex) : nameAndTag;
+  const tag = tagIndex !== -1 ? nameAndTag.substring(tagIndex + 1) : 'latest';
+
+  return { registry, name, tag };
+}
+
+module.exports = { parseImageReference };

package/lib/generator/split-readme.js

@@ -0,0 +1,105 @@
+/**
+ * README generation from deployment JSON for split flow.
+ * @fileoverview Builds readme config and generates README from deployment JSON
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { generateReadmeMd } = require('../app/readme');
+const { parseImageReference } = require('./parse-image');
+
+/**
+ * Builds config for external-system README from deployment
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigForExternal(deployment) {
+  const system = deployment.system;
+  const appName = system.key || deployment.key || 'external-system';
+  const dataSources = deployment.dataSources || deployment.datasources || [];
+  return {
+    appName,
+    config: {
+      type: 'external',
+      systemKey: appName,
+      systemType: system.type || 'openapi',
+      systemDisplayName: system.displayName || appName,
+      systemDescription: system.description || `External system integration for ${appName}`,
+      datasourceCount: dataSources.length,
+      datasources: dataSources
+    }
+  };
+}
+
+/**
+ * Builds config for application README from deployment
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigForApp(deployment) {
+  const appName = deployment.key || 'application';
+  const imageParts = parseImageReference(deployment.image || '');
+  const port = deployment.port !== undefined ? deployment.port : 3000;
+  const imageName = imageParts.name || appName;
+  const registry = imageParts.registry || 'myacr.azurecr.io';
+
+  const config = {
+    type: deployment.type || 'webapp',
+    displayName: deployment.displayName,
+    description: deployment.description,
+    port,
+    build: { localPort: port },
+    image: { name: imageName, registry },
+    registry,
+    database: deployment.requiresDatabase,
+    requires: {
+      database: deployment.requiresDatabase,
+      redis: deployment.requiresRedis,
+      storage: deployment.requiresStorage
+    },
+    redis: deployment.requiresRedis,
+    storage: deployment.requiresStorage,
+    authentication: !!deployment.authentication
+  };
+
+  if (config.type === 'external') {
+    config.systemKey = appName;
+    config.systemType = deployment.systemType || 'openapi';
+    config.systemDisplayName = deployment.displayName || appName;
+    config.systemDescription = deployment.description || `External system integration for ${appName}`;
+    config.datasourceCount = 0;
+    config.datasources = deployment.dataSources || deployment.datasources || [];
+  }
+
+  return { appName, config };
+}
+
+/**
+ * Builds application config shape from deployment JSON for README template context.
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigFromDeployment(deployment) {
+  if (deployment.system && typeof deployment.system === 'object') {
+    return buildReadmeConfigForExternal(deployment);
+  }
+  return buildReadmeConfigForApp(deployment);
+}
+
+/**
+ * Generates README.md content from deployment JSON.
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {string} README.md content
+ */
+function generateReadmeFromDeployJson(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    throw new Error('Deployment object is required');
+  }
+  const { appName, config } = buildReadmeConfigFromDeployment(deployment);
+  return generateReadmeMd(appName, config);
+}
+
+module.exports = {
+  buildReadmeConfigFromDeployment,
+  generateReadmeFromDeployJson
+};

package/lib/generator/split-variables.js

@@ -0,0 +1,149 @@
+/**
+ * Variables YAML extraction for deployment JSON split.
+ * Extracts application.yaml (variables) structure from deployment JSON.
+ *
+ * @fileoverview Split variables extraction for deployment JSON reverse conversion
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { parseImageReference } = require('./parse-image');
+
+function extractAppSection(deployment) {
+  if (!deployment.key && !deployment.displayName && !deployment.description && !deployment.type) {
+    return undefined;
+  }
+  const app = {};
+  if (deployment.key) app.key = deployment.key;
+  if (deployment.displayName) app.displayName = deployment.displayName;
+  if (deployment.description) app.description = deployment.description;
+  if (deployment.type) app.type = deployment.type;
+  if (deployment.version) app.version = deployment.version;
+  return app;
+}
+
+function extractImageSection(deployment) {
+  if (!deployment.image) return undefined;
+  const imageParts = parseImageReference(deployment.image);
+  const image = {};
+  if (imageParts.name) image.name = imageParts.name;
+  if (imageParts.registry) image.registry = imageParts.registry;
+  if (imageParts.tag) image.tag = imageParts.tag;
+  if (deployment.registryMode) image.registryMode = deployment.registryMode;
+  return image;
+}
+
+function extractRequirementsSection(deployment) {
+  if (!deployment.requiresDatabase && !deployment.requiresRedis && !deployment.requiresStorage && !deployment.databases) {
+    return undefined;
+  }
+  const requires = {};
+  if (deployment.requiresDatabase !== undefined) requires.database = deployment.requiresDatabase;
+  if (deployment.requiresRedis !== undefined) requires.redis = deployment.requiresRedis;
+  if (deployment.requiresStorage !== undefined) requires.storage = deployment.requiresStorage;
+  if (deployment.databases) requires.databases = deployment.databases;
+  return requires;
+}
+
+function extractOptionalSection(deployment, sectionName, optional) {
+  if (!deployment[sectionName]) return;
+  optional[sectionName] = sectionName === 'authentication'
+    ? { ...deployment[sectionName] }
+    : deployment[sectionName];
+}
+
+function extractOptionalSections(deployment) {
+  const optional = {};
+  const names = [
+    'healthCheck', 'authentication', 'build', 'repository', 'deployment',
+    'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting'
+  ];
+  for (const sectionName of names) {
+    extractOptionalSection(deployment, sectionName, optional);
+  }
+  return optional;
+}
+
+/**
+ * Portal-only configuration for application.yaml (name + portalInput per entry).
+ * @param {Array} configuration - Configuration array from deployment JSON
+ * @returns {Array<{ name: string, portalInput: Object }>}
+ */
+function extractPortalInputConfiguration(configuration) {
+  if (!Array.isArray(configuration) || configuration.length === 0) return [];
+  return configuration
+    .filter(item => item && item.portalInput && typeof item.name === 'string')
+    .map(item => ({ name: item.name, portalInput: item.portalInput }));
+}
+
+/**
+ * Datasource filename for externalIntegration.dataSources.
+ * @param {string} systemKey - System key
+ * @param {Object} datasource - Datasource from deployment.dataSources
+ * @param {number} index - Index
+ * @returns {string} Filename e.g. test-hubspot-datasource-companies-data.yaml
+ */
+function getExternalDatasourceFileName(systemKey, datasource, index) {
+  const key = datasource.key || '';
+  let suffix;
+  if (key.startsWith(`${systemKey}-deploy-`)) suffix = key.slice(`${systemKey}-deploy-`.length);
+  else if (key.startsWith(`${systemKey}-`)) suffix = key.slice(systemKey.length + 1);
+  else if (key) suffix = key;
+  else suffix = datasource.entityType || datasource.entityKey || `entity${index + 1}`;
+  return `${systemKey}-datasource-${suffix}.yaml`;
+}
+
+function extractVariablesYamlForExternal(deployment) {
+  const system = deployment.system;
+  const systemKey = system.key || 'external-system';
+  const dataSourcesList = deployment.dataSources || deployment.datasources || [];
+  const variables = {
+    app: {
+      key: systemKey,
+      displayName: system.displayName || systemKey,
+      description: system.description || `External system integration for ${systemKey}`,
+      type: 'external'
+    },
+    externalIntegration: {
+      schemaBasePath: './',
+      systems: [`${systemKey}-system.yaml`],
+      dataSources: dataSourcesList.map((ds, i) => getExternalDatasourceFileName(systemKey, ds, i)),
+      autopublish: true,
+      version: '1.0.0'
+    }
+  };
+  const portalOnlyConfig = extractPortalInputConfiguration(deployment.configuration);
+  if (portalOnlyConfig.length > 0) variables.configuration = portalOnlyConfig;
+  return variables;
+}
+
+/**
+ * Extracts deployment JSON into application config (variables) structure.
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {Object} Variables YAML structure
+ */
+function extractVariablesYaml(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    throw new Error('Deployment object is required');
+  }
+  if (deployment.system && typeof deployment.system === 'object') {
+    return extractVariablesYamlForExternal(deployment);
+  }
+  const variables = {};
+  const appSection = extractAppSection(deployment);
+  if (appSection) variables.app = appSection;
+  const imageSection = extractImageSection(deployment);
+  if (imageSection) variables.image = imageSection;
+  if (deployment.port !== undefined) variables.port = deployment.port;
+  const requirementsSection = extractRequirementsSection(deployment);
+  if (requirementsSection) variables.requires = requirementsSection;
+  Object.assign(variables, extractOptionalSections(deployment));
+  const portalOnlyConfig = extractPortalInputConfiguration(deployment.configuration);
+  if (portalOnlyConfig.length > 0) variables.configuration = portalOnlyConfig;
+  return variables;
+}
+
+module.exports = {
+  extractVariablesYaml,
+  getExternalDatasourceFileName
+};