@aifabrix/builder 2.32.3 → 2.33.0

package/lib/external-system/download.js

@@ -16,7 +16,6 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 const { getExternalSystemConfig } = require('../api/external-systems.api');
 const { getDeploymentAuth } = require('../utils/token-manager');
-const { getDataplaneUrl } = require('../datasource/deploy');
 const { getConfig } = require('../core/config');
 const { detectAppType } = require('../utils/paths');
 const logger = require('../utils/logger');
@@ -125,17 +124,19 @@ function handlePartialDownload(systemKey, systemData, datasourceErrors) {
  * @returns {Promise<Object>} Object with authConfig and dataplaneUrl
  * @throws {Error} If authentication fails
  */
-async function setupAuthenticationAndDataplane(systemKey, options, config) {
-  const environment = options.environment || 'dev';
-  const controllerUrl = await resolveControllerUrl(options, config);
+async function setupAuthenticationAndDataplane(systemKey, _options, _config) {
+  const { resolveEnvironment } = require('../core/config');
+  const environment = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
   const authConfig = await getDeploymentAuth(controllerUrl, environment, systemKey);
 
   if (!authConfig.token && !authConfig.clientId) {
     throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register" first.');
   }
 
-  logger.log(chalk.blue('🌐 Getting dataplane URL from controller...'));
-  const dataplaneUrl = await getDataplaneUrl(controllerUrl, systemKey, environment, authConfig);
+  const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+  logger.log(chalk.blue('🌐 Resolving dataplane URL...'));
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
   logger.log(chalk.green(`✓ Dataplane URL: ${dataplaneUrl}`));
 
   return { authConfig, dataplaneUrl };
@@ -159,8 +160,19 @@ async function downloadSystemConfiguration(dataplaneUrl, systemKey, authConfig)
   }
 
   const downloadData = response.data.data || response.data;
-  const application = downloadData.application;
-  const dataSources = downloadData.dataSources || [];
+  let application = downloadData.application;
+  let dataSources = downloadData.dataSources || [];
+
+  // Handle case where datasources are inline in application.configuration.dataSources
+  if (!application && downloadData.configuration) {
+    application = downloadData;
+  }
+  if (application && application.configuration && Array.isArray(application.configuration.dataSources)) {
+    dataSources = [...dataSources, ...application.configuration.dataSources];
+    // Remove inline datasources from application to avoid duplication
+    const { dataSources: _inlineDataSources, ...configWithoutDataSources } = application.configuration;
+    application = { ...application, configuration: configWithoutDataSources };
+  }
 
   if (!application) {
     throw new Error('Application configuration not found in download response');
@@ -189,7 +201,7 @@ async function downloadSystemConfiguration(dataplaneUrl, systemKey, authConfig)
  * @returns {Promise<string>} System file path
  */
 async function generateSystemFile(tempDir, systemKey, application) {
-  const systemFileName = `${systemKey}-deploy.json`;
+  const systemFileName = `${systemKey}-system.json`;
   const systemFilePath = path.join(tempDir, systemFileName);
   await fs.writeFile(systemFilePath, JSON.stringify(application, null, 2), 'utf8');
   return systemFilePath;
@@ -209,8 +221,16 @@ async function generateDatasourceFiles(tempDir, systemKey, dataSources) {
   const datasourceFiles = [];
   for (const datasource of dataSources) {
     try {
-      const entityType = datasource.entityType || datasource.entityKey || datasource.key.split('-').pop();
-      const datasourceFileName = `${systemKey}-deploy-${entityType}.json`;
+      const datasourceKey = datasource.key || '';
+      // Extract datasource key (remove system key prefix if present)
+      let datasourceKeyOnly;
+      if (datasourceKey.startsWith(`${systemKey}-`)) {
+        datasourceKeyOnly = datasourceKey.substring(systemKey.length + 1);
+      } else {
+        const entityType = datasource.entityType || datasource.entityKey || datasourceKey.split('-').pop();
+        datasourceKeyOnly = entityType;
+      }
+      const datasourceFileName = `${systemKey}-datasource-${datasourceKeyOnly}.json`;
       const datasourceFilePath = path.join(tempDir, datasourceFileName);
       await fs.writeFile(datasourceFilePath, JSON.stringify(datasource, null, 2), 'utf8');
       datasourceFiles.push(datasourceFilePath);
@@ -284,7 +304,7 @@ async function moveFilesToFinalLocation(tempDir, finalPath, systemKey, filePaths
   logger.log(chalk.blue(`📁 Creating directory: ${finalPath}`));
   await fs.mkdir(finalPath, { recursive: true });
 
-  const systemFileName = `${systemKey}-deploy.json`;
+  const systemFileName = `${systemKey}-system.json`;
   const filesToMove = [
     { from: filePaths.systemFilePath, to: path.join(finalPath, systemFileName) },
     { from: filePaths.variablesPath, to: path.join(finalPath, 'variables.yaml') },
@@ -328,7 +348,7 @@ function handleDryRun(systemKey, dataplaneUrl) {
   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}-deploy.json`));
+  logger.log(chalk.gray(`  integration/${systemKey}/${systemKey}-system.json`));
   logger.log(chalk.gray(`  integration/${systemKey}/env.template`));
   logger.log(chalk.gray(`  integration/${systemKey}/README.md`));
 }

package/lib/external-system/generator.js

@@ -48,8 +48,8 @@ async function generateExternalSystemTemplate(appPath, systemKey, config) {
     const rendered = template(context);
 
     // Generate in same folder as variables.yaml (new structure)
-    // Use naming: <app-name>-deploy.json
-    const outputPath = path.join(appPath, `${systemKey}-deploy.json`);
+    // Use naming: <app-name>-system.json
+    const outputPath = path.join(appPath, `${systemKey}-system.json`);
     await fs.writeFile(outputPath, rendered, 'utf8');
 
     return outputPath;
@@ -89,8 +89,12 @@ async function generateExternalDataSourceTemplate(appPath, datasourceKey, config
     const rendered = template(context);
 
     // Generate in same folder as variables.yaml (new structure)
-    // Use naming: <app-name>-deploy-<datasource-key>.json
-    const outputPath = path.join(appPath, `${datasourceKey}-deploy.json`);
+    // Use naming: <app-name>-datasource-<datasource-key>.json
+    // 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');
 
     return outputPath;
@@ -139,8 +143,8 @@ async function generateExternalSystemFiles(appPath, appName, config) {
         attributes: config.attributes || {}
       };
 
-      // Generate with full naming: <app-name>-deploy-<entity-key>.json
-      const datasourcePath = await generateExternalDataSourceTemplate(appPath, `${systemKey}-deploy-${datasourceKey}`, datasourceConfig);
+      // Generate with new naming: <app-name>-datasource-<entity-key>.json
+      const datasourcePath = await generateExternalDataSourceTemplate(appPath, datasourceKey, datasourceConfig);
       datasourcePaths.push(datasourcePath);
       logger.log(chalk.green(`✓ Generated datasource: ${path.basename(datasourcePath)}`));
     }
@@ -176,7 +180,7 @@ async function updateVariablesYamlWithExternalIntegration(appPath, systemKey, da
     // Files are in same folder, so schemaBasePath is './'
     variables.externalIntegration = {
       schemaBasePath: './',
-      systems: [`${systemKey}-deploy.json`],
+      systems: [`${systemKey}-system.json`],
       dataSources: datasourcePaths.map(p => path.basename(p)),
       autopublish: true,
       version: '1.0.0'

package/lib/external-system/test-auth.js

@@ -21,9 +21,10 @@ const { resolveControllerUrl } = require('../utils/controller-url');
  * @returns {Promise<Object>} Object with authConfig and dataplaneUrl
  * @throws {Error} If authentication fails
  */
-async function setupIntegrationTestAuth(appName, options, config) {
-  const environment = options.environment || 'dev';
-  const controllerUrl = await resolveControllerUrl(options, config);
+async function setupIntegrationTestAuth(appName, _options, _config) {
+  const { resolveEnvironment } = require('../core/config');
+  const environment = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
   const authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
 
   if (!authConfig.token && !authConfig.clientId) {

package/lib/generator/builders.js

@@ -8,6 +8,8 @@
  * @version 2.0.0
  */
 
+const { getContainerPort } = require('../utils/port-resolver');
+
 /**
  * Sanitizes authentication type - map keycloak to azure (schema allows: azure, local, none)
  * @function sanitizeAuthType
@@ -169,7 +171,7 @@ function buildBaseDeployment(appName, variables, filteredConfiguration) {
   return {
     ...appMetadata,
     ...imageConfig,
-    port: variables.port || 3000,
+    port: getContainerPort(variables, 3000),
     ...requirementsConfig,
     configuration: filteredConfiguration
   };

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

@@ -0,0 +1,157 @@
+/**
+ * External System Controller Manifest Generator
+ *
+ * Generates controller-compatible deployment manifest for external systems.
+ * Creates manifest with inline system + dataSources in controller format.
+ *
+ * @fileoverview Controller manifest generation for external systems
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const { detectAppType } = require('../utils/paths');
+const { generateDeploymentKeyFromJson } = require('../core/key-generator');
+const { loadSystemFile, loadDatasourceFiles } = require('./external');
+const { loadVariables, loadRbac } = require('./helpers');
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Resolves application path from options or detection
+ * @async
+ * @function resolveAppPath
+ * @param {string} appName - Application name
+ * @param {Object} options - Options with optional appPath
+ * @returns {Promise<string>} Application path
+ */
+async function resolveAppPath(appName, options) {
+  if (options.appPath) {
+    return options.appPath;
+  }
+  const detected = await detectAppType(appName, { type: 'external' });
+  return detected.appPath;
+}
+
+/**
+ * Extracts app metadata from variables
+ * @function extractAppMetadata
+ * @param {Object} variables - Parsed variables.yaml
+ * @param {string} appName - Application name
+ * @returns {Object} App metadata { appKey, displayName, description }
+ */
+function extractAppMetadata(variables, appName) {
+  return {
+    appKey: variables.app?.key || appName,
+    displayName: variables.app?.displayName || appName,
+    description: variables.app?.description || `External system integration for ${appName}`
+  };
+}
+
+/**
+ * Loads and merges system with RBAC
+ * @async
+ * @function loadSystemWithRbac
+ * @param {string} appPath - Application path
+ * @param {string} schemaBasePath - Schema base path
+ * @param {string} systemFile - System file path
+ * @returns {Promise<Object>} System JSON with RBAC merged
+ */
+async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
+  const systemJson = await loadSystemFile(appPath, schemaBasePath, systemFile);
+  const rbacPath = path.join(appPath, 'rbac.yaml');
+  const rbac = loadRbac(rbacPath);
+  mergeRbacIntoSystemJson(systemJson, rbac);
+  return systemJson;
+}
+
+/**
+ * Generates controller-compatible deployment manifest for external systems
+ * Creates manifest with inline system + dataSources in controller format
+ *
+ * @async
+ * @function generateControllerManifest
+ * @param {string} appName - Application name
+ * @param {Object} [options] - Optional parameters
+ * @param {string} [options.appPath] - Application path (if provided, skips detection)
+ * @returns {Promise<Object>} Controller manifest object
+ * @throws {Error} If generation fails
+ *
+ * @example
+ * const manifest = await generateControllerManifest('my-hubspot');
+ * // Returns: { key, displayName, description, type: "external", system: {...}, dataSources: [...], deploymentKey }
+ */
+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);
+
+  if (!variables.externalIntegration) {
+    throw new Error('externalIntegration block not found in variables.yaml');
+  }
+
+  const metadata = extractAppMetadata(variables, appName);
+  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  const systemFiles = variables.externalIntegration.systems || [];
+
+  if (systemFiles.length === 0) {
+    throw new Error('No system files specified in externalIntegration.systems');
+  }
+
+  const systemJson = await loadSystemWithRbac(appPath, schemaBasePath, systemFiles[0]);
+  const datasourceFiles = variables.externalIntegration.dataSources || [];
+  const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
+
+  // Build externalIntegration block (required by application schema for type: "external")
+  const externalIntegration = {
+    schemaBasePath: schemaBasePath,
+    systems: systemFiles,
+    dataSources: datasourceFiles,
+    autopublish: variables.externalIntegration.autopublish !== false, // default true
+    version: variables.externalIntegration.version || '1.0.0'
+  };
+
+  const manifest = {
+    key: metadata.appKey,
+    displayName: metadata.displayName,
+    description: metadata.description,
+    type: 'external',
+    externalIntegration: externalIntegration,
+    // Inline system and dataSources for atomic deployment (optional but recommended)
+    system: systemJson,
+    dataSources: datasourceJsons,
+    // Explicitly set to false to satisfy conditional schema requirements
+    requiresDatabase: false,
+    requiresRedis: false,
+    requiresStorage: false
+  };
+
+  manifest.deploymentKey = generateDeploymentKeyFromJson(manifest);
+  return manifest;
+}
+
+module.exports = {
+  generateControllerManifest
+};

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

@@ -0,0 +1,236 @@
+/**
+ * External Schema Split Utilities
+ *
+ * Helpers for splitting application-schema.json into component files.
+ *
+ * @fileoverview External schema split utilities for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { generateEnvTemplate } = require('../utils/external-system-env-helpers');
+const { extractRbacYaml } = require('./split');
+const { generateExternalReadmeContent } = require('../utils/external-readme');
+
+/**
+ * Parses application-schema.json content
+ * @function parseApplicationSchema
+ * @param {string} schemaPath - Schema file path
+ * @param {string} content - Raw JSON content
+ * @returns {Object} Parsed schema details
+ * @throws {Error} If JSON or schema structure is invalid
+ */
+function parseApplicationSchema(schemaPath, content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON syntax in ${schemaPath}: ${error.message}`);
+  }
+
+  const application = parsed.application;
+  const dataSources = Array.isArray(parsed.dataSources) ? parsed.dataSources : [];
+  if (!application || typeof application !== 'object') {
+    throw new Error('application-schema.json must include an "application" object');
+  }
+
+  return { application, dataSources, version: parsed.version };
+}
+
+/**
+ * Extracts system key from application schema
+ * @function getSystemKey
+ * @param {Object} application - Application schema object
+ * @returns {string} System key
+ * @throws {Error} If system key is missing
+ */
+function getSystemKey(application) {
+  const systemKey = application.key;
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('application.key is required to split external system files');
+  }
+  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
+ * @param {Object} datasource - Datasource schema
+ * @param {number} index - Datasource index
+ * @returns {string} Entity type
+ */
+function getDatasourceEntityType(datasource, index) {
+  return (
+    datasource.entityType ||
+    datasource.entityKey ||
+    datasource.key?.split('-').pop() ||
+    `entity${index + 1}`
+  );
+}
+
+/**
+ * Builds datasource file name
+ * @function getDatasourceFileName
+ * @param {string} systemKey - System key
+ * @param {Object} datasource - Datasource schema
+ * @param {number} index - Datasource index
+ * @returns {string} Datasource file name
+ */
+function getDatasourceFileName(systemKey, datasource, index) {
+  const datasourceKey = datasource.key || '';
+  // Extract datasource key (remove system key prefix if present)
+  let datasourceKeyOnly;
+  if (datasourceKey.startsWith(`${systemKey}-`)) {
+    datasourceKeyOnly = datasourceKey.substring(systemKey.length + 1);
+  } else if (datasourceKey.startsWith(`${systemKey}-deploy-`)) {
+    // Support old naming format during migration
+    datasourceKeyOnly = datasourceKey.substring(`${systemKey}-deploy-`.length);
+  } else {
+    datasourceKeyOnly = getDatasourceEntityType(datasource, index);
+  }
+  return `${systemKey}-datasource-${datasourceKeyOnly}.json`;
+}
+
+/**
+ * Writes datasource files and returns file names
+ * @async
+ * @function writeDatasourceFiles
+ * @param {string} outputDir - Output directory
+ * @param {string} systemKey - System key
+ * @param {Object[]} dataSources - Datasource schemas
+ * @returns {Promise<string[]>} Datasource file names
+ */
+async function writeDatasourceFiles(outputDir, systemKey, dataSources) {
+  const datasourceFileNames = [];
+  for (let i = 0; i < dataSources.length; i += 1) {
+    const datasource = dataSources[i];
+    const datasourceFileName = getDatasourceFileName(systemKey, datasource, i);
+    const datasourceFilePath = path.join(outputDir, datasourceFileName);
+    await writeJsonFile(datasourceFilePath, datasource);
+    datasourceFileNames.push(datasourceFileName);
+  }
+  return datasourceFileNames;
+}
+
+/**
+ * Builds variables.yaml content for external integrations
+ * @function buildExternalVariables
+ * @param {string} systemKey - System key
+ * @param {Object} application - Application schema
+ * @param {string} systemFileName - System file name
+ * @param {string[]} datasourceFileNames - Datasource file names
+ * @param {string} version - Schema version
+ * @returns {Object} Variables content
+ */
+function buildExternalVariables(systemKey, application, systemFileName, datasourceFileNames, version) {
+  return {
+    app: {
+      key: systemKey,
+      displayName: application.displayName || systemKey,
+      description: application.description || `External system integration for ${systemKey}`,
+      type: 'external'
+    },
+    deployment: {
+      controllerUrl: '',
+      environment: 'dev'
+    },
+    externalIntegration: {
+      schemaBasePath: './',
+      systems: [systemFileName],
+      dataSources: datasourceFileNames,
+      autopublish: true,
+      version
+    }
+  };
+}
+
+/**
+ * Writes YAML file
+ * @async
+ * @function writeYamlFile
+ * @param {string} filePath - File path
+ * @param {Object} data - YAML data
+ * @param {Object} options - YAML options
+ * @returns {Promise<void>} Resolves when file is written
+ */
+async function writeYamlFile(filePath, data, options) {
+  const yamlContent = yaml.dump(data, options);
+  await fs.promises.writeFile(filePath, yamlContent, 'utf8');
+}
+
+/**
+ * Writes split files for external application schemas
+ * @async
+ * @function writeSplitExternalSchemaFiles
+ * @param {Object} params - Split parameters
+ * @param {string} params.outputDir - Output directory
+ * @param {string} params.systemKey - System key
+ * @param {Object} params.application - Application schema
+ * @param {Object[]} params.dataSources - Datasource schemas
+ * @param {string} params.version - Schema version
+ * @returns {Promise<Object>} Paths to generated files
+ */
+async function writeSplitExternalSchemaFiles({ outputDir, systemKey, application, dataSources, version }) {
+  const systemFileName = `${systemKey}-system.json`;
+  const systemFilePath = path.join(outputDir, systemFileName);
+  await writeJsonFile(systemFilePath, application);
+
+  const datasourceFileNames = await writeDatasourceFiles(outputDir, systemKey, dataSources);
+  const variables = buildExternalVariables(systemKey, application, systemFileName, datasourceFileNames, version);
+
+  const variablesPath = path.join(outputDir, 'variables.yaml');
+  await writeYamlFile(variablesPath, variables, { indent: 2, lineWidth: 120, noRefs: true });
+
+  const envTemplatePath = path.join(outputDir, 'env.template');
+  const envTemplate = generateEnvTemplate(application);
+  await fs.promises.writeFile(envTemplatePath, envTemplate, 'utf8');
+
+  const rbac = extractRbacYaml(application);
+  let rbacPath = null;
+  if (rbac) {
+    rbacPath = path.join(outputDir, 'rbac.yml');
+    await writeYamlFile(rbacPath, rbac, { indent: 2, lineWidth: -1 });
+  }
+
+  const readmeContent = generateExternalReadmeContent({
+    appName: systemKey,
+    systemKey,
+    systemType: application.type,
+    displayName: application.displayName,
+    description: application.description,
+    datasources: dataSources
+  });
+  const readmePath = path.join(outputDir, 'README.md');
+  await fs.promises.writeFile(readmePath, readmeContent, 'utf8');
+
+  return {
+    systemFile: systemFilePath,
+    datasourceFiles: datasourceFileNames.map(name => path.join(outputDir, name)),
+    variables: variablesPath,
+    envTemplate: envTemplatePath,
+    rbac: rbacPath,
+    readme: readmePath
+  };
+}
+
+module.exports = {
+  parseApplicationSchema,
+  getSystemKey,
+  writeSplitExternalSchemaFiles
+};

package/lib/generator/external.js

@@ -13,6 +13,11 @@ const path = require('path');
 const Ajv = require('ajv');
 const { detectAppType, getDeployJsonPath } = require('../utils/paths');
 const { loadVariables, loadRbac } = require('./helpers');
+const {
+  parseApplicationSchema,
+  getSystemKey,
+  writeSplitExternalSchemaFiles
+} = require('./external-schema-utils');
 
 /**
  * Generates external system <app-name>-deploy.json by loading the system JSON file
@@ -36,15 +41,26 @@ const { loadVariables, loadRbac } = require('./helpers');
 function resolveSystemFilePath(variables, appPath, appName) {
   const systemFileName = variables.externalIntegration.systems && variables.externalIntegration.systems.length > 0
     ? variables.externalIntegration.systems[0]
-    : `${appName}-deploy.json`;
+    : `${appName}-system.json`;
 
   const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
   const systemFilePath = path.isAbsolute(schemaBasePath)
     ? path.join(schemaBasePath, systemFileName)
     : path.join(appPath, schemaBasePath, systemFileName);
 
+  // Support both old and new naming for backward compatibility
   if (!fs.existsSync(systemFilePath)) {
-    throw new Error(`External system file not found: ${systemFilePath}. Please create it first.`);
+    // 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;
+    }
+
+    throw new Error(`External system file not found: ${systemFilePath} (also checked: ${oldSystemFilePath}). Please create it first.`);
   }
 
   return systemFilePath;
@@ -358,8 +374,44 @@ async function generateExternalSystemApplicationSchema(appName) {
   return applicationSchema;
 }
 
+/**
+ * Splits application-schema.json into component files for external systems
+ * @async
+ * @function splitExternalApplicationSchema
+ * @param {string} schemaPath - Path to application-schema.json
+ * @param {string} outputDir - Output directory for split files
+ * @returns {Promise<Object>} Paths to generated files
+ * @throws {Error} If schema is invalid or files cannot be written
+ */
+async function splitExternalApplicationSchema(schemaPath, outputDir) {
+  if (!schemaPath || typeof schemaPath !== 'string') {
+    throw new Error('Schema path is required and must be a string');
+  }
+  if (!outputDir || typeof outputDir !== 'string') {
+    throw new Error('Output directory is required and must be a string');
+  }
+
+  const content = await fs.promises.readFile(schemaPath, 'utf8');
+  const { application, dataSources, version } = parseApplicationSchema(schemaPath, content);
+  const systemKey = getSystemKey(application);
+
+  await fs.promises.mkdir(outputDir, { recursive: true });
+
+  const schemaVersion = version || application.version || '1.0.0';
+  return writeSplitExternalSchemaFiles({
+    outputDir,
+    systemKey,
+    application,
+    dataSources,
+    version: schemaVersion
+  });
+}
+
 module.exports = {
   generateExternalSystemDeployJson,
-  generateExternalSystemApplicationSchema
+  generateExternalSystemApplicationSchema,
+  splitExternalApplicationSchema,
+  loadSystemFile,
+  loadDatasourceFiles
 };