@aifabrix/builder 2.40.2 → 2.42.0

package/lib/generator/external.js

@@ -174,11 +174,14 @@ async function loadSystemFile(appPath, schemaBasePath, systemFileName) {
  * @param {string} appPath - Application path
  * @param {string} schemaBasePath - Schema base path
  * @param {Array<string>} datasourceFiles - Array of datasource file names
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipMissingDatasourceFiles] - If true, skip missing files (e.g. when generating deploy JSON) instead of throwing
  * @returns {Promise<Array<Object>>} Array of datasource JSON objects
- * @throws {Error} If files cannot be loaded
+ * @throws {Error} If a file is missing and skipMissingDatasourceFiles is not set
  */
-async function loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles) {
+async function loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles, options = {}) {
   const datasourceJsons = [];
+  const { skipMissingDatasourceFiles } = options;
 
   for (const datasourceFile of datasourceFiles) {
     const datasourcePath = path.isAbsolute(schemaBasePath)
@@ -186,6 +189,9 @@ async function loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles) {
       : path.join(appPath, schemaBasePath, datasourceFile);
 
     if (!fs.existsSync(datasourcePath)) {
+      if (skipMissingDatasourceFiles) {
+        continue;
+      }
       throw new Error(`Datasource file not found: ${datasourcePath}`);
     }
 
@@ -417,6 +423,7 @@ module.exports = {
   generateExternalSystemApplicationSchema,
   splitExternalApplicationSchema,
   loadSystemFile,
-  loadDatasourceFiles
+  loadDatasourceFiles,
+  loadExternalIntegrationConfig
 };
 

package/lib/generator/index.js

@@ -20,6 +20,8 @@ const { loadVariables, loadEnvTemplate, loadRbac, parseEnvironmentVariables } =
 const { generateExternalSystemApplicationSchema, splitExternalApplicationSchema } = require('./external');
 const { generateControllerManifest } = require('./external-controller-manifest');
 const { resolveVersionForApp } = require('../utils/image-version');
+const { getContainerPort } = require('../utils/port-resolver');
+const { buildEnvVarMap } = require('../utils/env-map');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -59,6 +61,96 @@ function loadDeploymentConfigFiles(appPath, appType, appName) {
   return { variables, envTemplate, rbac, jsonPath };
 }
 
+/** Placeholder replaced with application port from application.yaml */
+const PORT_PLACEHOLDER = '${PORT}';
+
+/**
+ * Returns the numeric port to use when substituting ${PORT} in the manifest.
+ * When application.yaml has port: "${PORT}", uses defaultPort (e.g. 3000).
+ *
+ * @param {Object} variables - Parsed application config
+ * @param {number} [defaultPort=3000] - Default when port is "${PORT}" or invalid
+ * @returns {number} Port number for substitution
+ */
+function getEffectivePortForSubstitution(variables, defaultPort = 3000) {
+  const raw = getContainerPort(variables, defaultPort);
+  if (raw === PORT_PLACEHOLDER || (typeof raw === 'string' && raw.trim() === PORT_PLACEHOLDER)) {
+    return defaultPort;
+  }
+  if (typeof raw === 'number' && raw > 0) {
+    return raw;
+  }
+  const num = Number(raw);
+  return Number.isFinite(num) && num > 0 ? num : defaultPort;
+}
+
+/**
+ * Recursively replaces ${PORT} with the given port number in all string values of obj (in-place).
+ *
+ * @param {Object} obj - Deployment manifest or any nested object
+ * @param {number} portNumber - Port to substitute (e.g. from application.yaml)
+ */
+function substitutePortInDeployment(obj, portNumber) {
+  if (obj === null || obj === undefined) return;
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      if (typeof obj[i] === 'string' && obj[i].includes(PORT_PLACEHOLDER)) {
+        obj[i] = obj[i].split(PORT_PLACEHOLDER).join(String(portNumber));
+      } else if (typeof obj[i] === 'object' && obj[i] !== null) {
+        substitutePortInDeployment(obj[i], portNumber);
+      }
+    }
+    return;
+  }
+  if (typeof obj === 'object') {
+    for (const key of Object.keys(obj)) {
+      const value = obj[key];
+      if (typeof value === 'string' && value.includes(PORT_PLACEHOLDER)) {
+        obj[key] = value.split(PORT_PLACEHOLDER).join(String(portNumber));
+      } else if (typeof value === 'object' && value !== null) {
+        substitutePortInDeployment(value, portNumber);
+      }
+    }
+  }
+}
+
+/** Regex to find ${VAR} placeholders for env substitution */
+const ENV_VAR_PLACEHOLDER_REGEX = /\$\{([^}]+)\}/g;
+
+/**
+ * Recursively replaces ${VAR} with envVarMap[VAR] in all string values of obj (in-place).
+ * Only substitutes when VAR is a key in envVarMap (from env-config.yaml / config).
+ *
+ * @param {Object} obj - Deployment manifest or any nested object
+ * @param {Object} envVarMap - Flat map of variable names to values (e.g. from buildEnvVarMap('docker'))
+ */
+function substituteEnvVarsInDeployment(obj, envVarMap) {
+  if (!envVarMap || typeof envVarMap !== 'object') return;
+  if (obj === null || obj === undefined) return;
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      if (typeof obj[i] === 'string') {
+        obj[i] = obj[i].replace(ENV_VAR_PLACEHOLDER_REGEX, (match, varName) =>
+          Object.prototype.hasOwnProperty.call(envVarMap, varName) ? String(envVarMap[varName]) : match);
+      } else if (typeof obj[i] === 'object' && obj[i] !== null) {
+        substituteEnvVarsInDeployment(obj[i], envVarMap);
+      }
+    }
+    return;
+  }
+  if (typeof obj === 'object') {
+    for (const key of Object.keys(obj)) {
+      const value = obj[key];
+      if (typeof value === 'string') {
+        obj[key] = value.replace(ENV_VAR_PLACEHOLDER_REGEX, (match, varName) =>
+          Object.prototype.hasOwnProperty.call(envVarMap, varName) ? String(envVarMap[varName]) : match);
+      } else if (typeof value === 'object' && value !== null) {
+        substituteEnvVarsInDeployment(value, envVarMap);
+      }
+    }
+  }
+}
+
 /**
  * Builds and validates deployment manifest
  * @function buildAndValidateDeployment
@@ -66,10 +158,12 @@ function loadDeploymentConfigFiles(appPath, appType, appName) {
  * @param {Object} variables - Variables configuration
  * @param {Object} envTemplate - Environment template
  * @param {Object} rbac - RBAC configuration
+ * @param {Object} [options] - Optional options
+ * @param {Object} [options.envVarMap] - Env vars from env-config (e.g. REDIS_HOST, DB_HOST) to resolve ${VAR} in manifest
  * @returns {Object} Deployment manifest
  * @throws {Error} If validation fails
  */
-function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
+function buildAndValidateDeployment(appName, variables, envTemplate, rbac, options = null) {
   // Parse environment variables from template and merge portalInput from application config
   const configuration = parseEnvironmentVariables(envTemplate, variables);
 
@@ -83,6 +177,23 @@ function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
     throw new Error(`Generated deployment JSON does not match schema:\n${errorMessages}`);
   }
 
+  // Replace ${PORT} with port from application.yaml so manifest deploys correctly
+  const effectivePort = getEffectivePortForSubstitution(variables, 3000);
+  substitutePortInDeployment(deployment, effectivePort);
+  if (deployment.port !== undefined) {
+    deployment.port = typeof deployment.port === 'string' && /^\d+$/.test(deployment.port)
+      ? parseInt(deployment.port, 10) : (typeof deployment.port === 'number' ? deployment.port : effectivePort);
+  }
+
+  // Resolve ${REDIS_HOST}, ${DB_HOST}, etc. from env-config.yaml so manifest has no unresolved vars
+  const envVarMap = options && options.envVarMap;
+  if (envVarMap) {
+    substituteEnvVarsInDeployment(deployment, envVarMap);
+  }
+
+  // Ensure no other ${...} placeholders remain in manifest
+  _validator.validateNoUnresolvedVariablesInDeployment(deployment);
+
   return deployment;
 }
 
@@ -117,46 +228,84 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
   const configuration = parseEnvironmentVariables(envTemplate, variables);
   const deployment = builders.buildManifestStructure(appName, variablesWithVersion, configuration, rbac);
 
+  const effectivePort = getEffectivePortForSubstitution(variablesWithVersion, 3000);
+  substitutePortInDeployment(deployment, effectivePort);
+  if (deployment.port !== undefined) {
+    deployment.port = typeof deployment.port === 'string' && /^\d+$/.test(deployment.port)
+      ? parseInt(deployment.port, 10) : (typeof deployment.port === 'number' ? deployment.port : effectivePort);
+  }
+  const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  substituteEnvVarsInDeployment(deployment, envVarMap);
+  _validator.validateNoUnresolvedVariablesInDeployment(deployment);
   return { deployment, appPath };
 }
 
-async function generateDeployJson(appName, options = {}) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-
-  // 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) {
-    const manifest = await generateControllerManifest(appName, options);
-
-    // Determine system key for file naming
-    const systemKey = manifest.key || appName;
-    const deployJsonPath = path.join(appPath, `${systemKey}-deploy.json`);
-
-    await fs.promises.writeFile(deployJsonPath, JSON.stringify(manifest, null, 2), { mode: 0o644, encoding: 'utf8' });
-    return deployJsonPath;
+/**
+ * Writes external system deploy JSON (manifest + ${PORT} substitution + validation).
+ * @async
+ * @param {string} appName - Application name
+ * @param {string} appPath - Application path
+ * @param {Object} options - Generation options
+ * @returns {Promise<string>} Path to written deploy JSON
+ */
+async function writeExternalDeployJson(appName, appPath, options) {
+  const manifest = await generateControllerManifest(appName, {
+    ...options,
+    skipMissingDatasourceFiles: true
+  });
+  let effectivePort = 3000;
+  try {
+    const variablesPath = resolveApplicationConfigPath(appPath);
+    const { parsed: variables } = loadVariables(variablesPath);
+    effectivePort = getEffectivePortForSubstitution(variables, 3000);
+    substitutePortInDeployment(manifest, effectivePort);
+  } catch {
+    substitutePortInDeployment(manifest, 3000);
   }
+  const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  substituteEnvVarsInDeployment(manifest, envVarMap);
+  _validator.validateNoUnresolvedVariablesInDeployment(manifest);
+  const systemKey = manifest.key || appName;
+  const deployJsonPath = path.join(appPath, `${systemKey}-deploy.json`);
+  await fs.promises.writeFile(deployJsonPath, JSON.stringify(manifest, null, 2), { mode: 0o644, encoding: 'utf8' });
+  return deployJsonPath;
+}
 
-  // Regular app: generate deployment manifest
+/**
+ * Writes regular app deploy JSON (build + validate + write).
+ * @async
+ * @param {string} appName - Application name
+ * @param {string} appPath - Application path
+ * @param {string} appType - Application type
+ * @returns {Promise<string>} Path to written deploy JSON
+ */
+async function writeRegularDeployJson(appName, appPath, appType) {
   const { variables, envTemplate, rbac, jsonPath } = loadDeploymentConfigFiles(appPath, appType, appName);
   const resolved = await resolveVersionForApp(appName, variables, { updateBuilder: false });
   const variablesWithVersion = {
     ...variables,
     app: { ...variables.app, version: resolved.version }
   };
-  const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac);
-
-  // Write deployment JSON
+  const effectivePort = getEffectivePortForSubstitution(variablesWithVersion, 3000);
+  const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac, { envVarMap });
   const jsonContent = JSON.stringify(deployment, null, 2);
   fs.writeFileSync(jsonPath, jsonContent, { mode: 0o644 });
-
   return jsonPath;
 }
 
+async function generateDeployJson(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);
+  logOfflinePathWhenType(appPath);
+  if (isExternal) {
+    return writeExternalDeployJson(appName, appPath, options);
+  }
+  return await writeRegularDeployJson(appName, appPath, appType);
+}
+
 async function generateDeployJsonWithValidation(appName, options = {}) {
   const jsonPath = await generateDeployJson(appName, options);
   const jsonContent = fs.readFileSync(jsonPath, 'utf8');
@@ -187,6 +336,9 @@ module.exports = {
   generateDeployJson,
   generateDeployJsonWithValidation,
   buildDeploymentManifestInMemory,
+  getEffectivePortForSubstitution,
+  substitutePortInDeployment,
+  substituteEnvVarsInDeployment,
   generateExternalSystemApplicationSchema,
   splitExternalApplicationSchema,
   parseEnvironmentVariables,

package/lib/generator/split-readme.js

@@ -25,6 +25,7 @@ function buildReadmeConfigForExternal(deployment) {
       systemType: system.type || 'openapi',
       systemDisplayName: system.displayName || appName,
       systemDescription: system.description || `External system integration for ${appName}`,
+      fileExt: '.yaml',
       datasourceCount: dataSources.length,
       datasources: dataSources
     }

package/lib/generator/split-variables.js

@@ -78,10 +78,12 @@ function extractPortalInputConfiguration(configuration) {
 
 /**
  * Datasource filename for externalIntegration.dataSources.
+ * Avoids duplicate "datasource" in name (e.g. hubspot-users-datasource -> hubspot-datasource-users).
+ *
  * @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
+ * @returns {string} Filename e.g. hubspot-datasource-users.yaml
  */
 function getExternalDatasourceFileName(systemKey, datasource, index) {
   const key = datasource.key || '';
@@ -90,6 +92,10 @@ function getExternalDatasourceFileName(systemKey, datasource, index) {
   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}`;
+  // Strip trailing -datasource so we get hubspot-datasource-users not hubspot-datasource-users-datasource
+  if (suffix.endsWith('-datasource')) {
+    suffix = suffix.slice(0, -'-datasource'.length);
+  }
   return `${systemKey}-datasource-${suffix}.yaml`;
 }
 

package/lib/generator/split.js

@@ -139,6 +139,125 @@ async function writeComponentFile(filePath, content) {
   await fs.writeFile(filePath, content, { mode: 0o644, encoding: 'utf8' });
 }
 
+/**
+ * Builds key -> line map from configuration array (for env.template merge).
+ * @param {Array} configuration - Configuration array from deployment
+ * @returns {Map<string, string>} Key to full line map
+ */
+function buildEnvTemplateExpectedByKey(configuration) {
+  const expectedByKey = new Map();
+  if (!Array.isArray(configuration)) return expectedByKey;
+  const lines = extractEnvTemplate(configuration).split('\n').filter(Boolean);
+  for (const line of lines) {
+    const eq = line.indexOf('=');
+    if (eq > 0) {
+      const key = line.substring(0, eq).trim();
+      expectedByKey.set(key, `${key}=${line.substring(eq + 1)}`);
+    }
+  }
+  return expectedByKey;
+}
+
+/**
+ * Pushes the appropriate line for a key that exists in expectedByKey (preserves MISO_CONTROLLER_URL).
+ * @param {string} line - Existing line
+ * @param {string} key - Parsed key
+ * @param {Map<string, string>} expectedByKey - Expected key -> line
+ * @param {string[]} updatedLines - Output lines
+ * @param {Set<string>} keysWritten - Keys already written
+ */
+function pushMergedKeyValueLine(line, key, expectedByKey, updatedLines, keysWritten) {
+  const valueToPush = key === 'MISO_CONTROLLER_URL' ? line : expectedByKey.get(key);
+  updatedLines.push(valueToPush);
+  keysWritten.add(key);
+}
+
+/**
+ * Merges existing env.template with new lines from configuration; preserves comments and unknown keys.
+ * When MISO_CONTROLLER_URL already exists in the file, its value is preserved (only add when missing).
+ * @param {string} existingContent - Current env.template content
+ * @param {Map<string, string>} expectedByKey - New key -> line from download
+ * @returns {string} Merged content
+ */
+function mergeEnvTemplateWithExisting(existingContent, expectedByKey) {
+  const lines = existingContent.split(/\r?\n/);
+  const updatedLines = [];
+  const keysWritten = new Set();
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      updatedLines.push(line);
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq <= 0) {
+      updatedLines.push(line);
+      continue;
+    }
+    const key = line.substring(0, eq).trim();
+    if (expectedByKey.has(key)) {
+      pushMergedKeyValueLine(line, key, expectedByKey, updatedLines, keysWritten);
+    } else {
+      updatedLines.push(line);
+    }
+  }
+  for (const key of expectedByKey.keys()) {
+    if (!keysWritten.has(key)) updatedLines.push(expectedByKey.get(key));
+  }
+  return updatedLines.join('\n') + (updatedLines.length > 0 ? '\n' : '');
+}
+
+/**
+ * Writes env.template (merge or overwrite).
+ * @param {string} outputDir - Output directory
+ * @param {string} envTemplate - Default env.template content
+ * @param {Object} options - Options (mergeEnvTemplate, configuration)
+ * @returns {Promise<string>} Path to env.template
+ */
+async function writeEnvTemplateToDir(outputDir, envTemplate, options) {
+  const envTemplatePath = path.join(outputDir, 'env.template');
+  const fsSync = require('fs');
+  if (options.mergeEnvTemplate && options.configuration && fsSync.existsSync(envTemplatePath)) {
+    const expectedByKey = buildEnvTemplateExpectedByKey(options.configuration);
+    const existingContent = await fs.readFile(envTemplatePath, 'utf8');
+    const merged = mergeEnvTemplateWithExisting(existingContent, expectedByKey);
+    await writeComponentFile(envTemplatePath, merged);
+  } else {
+    await writeComponentFile(envTemplatePath, envTemplate);
+  }
+  return envTemplatePath;
+}
+
+/**
+ * Writes application.yaml, rbac.yaml, and README.md.
+ * @param {string} outputDir - Output directory
+ * @param {Object} variables - Variables object
+ * @param {Object|null} rbac - RBAC object or null
+ * @param {string} readme - README content
+ * @param {Object} options - Options (overwriteReadme)
+ * @returns {Promise<Object>} Results with variables, rbac?, readme? paths
+ */
+async function writeVariablesRbacReadme(outputDir, variables, rbac, readme, options) {
+  const out = {};
+  const variablesPath = path.join(outputDir, 'application.yaml');
+  await writeComponentFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: -1 }));
+  out.variables = variablesPath;
+  if (rbac) {
+    const rbacPath = path.join(outputDir, 'rbac.yaml');
+    await writeComponentFile(rbacPath, yaml.dump(rbac, { indent: 2, lineWidth: -1 }));
+    out.rbac = rbacPath;
+  }
+  const readmePath = path.join(outputDir, 'README.md');
+  const fsSync = require('fs');
+  if (options.overwriteReadme === false && fsSync.existsSync(readmePath)) {
+    out.readmeSkipped = readmePath;
+  } else {
+    await writeComponentFile(readmePath, readme);
+    out.readme = readmePath;
+  }
+  return out;
+}
+
 /**
  * Writes all component files
  * @async
@@ -148,36 +267,36 @@ async function writeComponentFile(filePath, content) {
  * @param {Object} variables - Variables object
  * @param {Object|null} rbac - RBAC object or null
  * @param {string} readme - README content
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.mergeEnvTemplate] - If true and env.template exists, merge instead of overwrite
+ * @param {Array} [options.configuration] - Configuration array for merge (required when mergeEnvTemplate)
+ * @param {boolean} [options.overwriteReadme] - If false and README.md exists, skip writing README
  * @returns {Promise<Object>} Results object with file paths
  */
-async function writeComponentFiles(outputDir, envTemplate, variables, rbac, readme) {
+async function writeComponentFiles(outputDir, envTemplate, variables, rbac, readme, options = {}) {
   const results = {};
+  results.envTemplate = await writeEnvTemplateToDir(outputDir, envTemplate, options);
+  Object.assign(results, await writeVariablesRbacReadme(outputDir, variables, rbac, readme, options));
+  return results;
+}
 
-  // Write env.template
-  const envTemplatePath = path.join(outputDir, 'env.template');
-  await writeComponentFile(envTemplatePath, envTemplate);
-  results.envTemplate = envTemplatePath;
-
-  // Write application.yaml
-  const variablesPath = path.join(outputDir, 'application.yaml');
-  const variablesYaml = yaml.dump(variables, { indent: 2, lineWidth: -1 });
-  await writeComponentFile(variablesPath, variablesYaml);
-  results.variables = variablesPath;
-
-  // Write rbac.yml (only if roles/permissions exist)
-  if (rbac) {
-    const rbacPath = path.join(outputDir, 'rbac.yml');
-    const rbacYaml = yaml.dump(rbac, { indent: 2, lineWidth: -1 });
-    await writeComponentFile(rbacPath, rbacYaml);
-    results.rbac = rbacPath;
+/**
+ * Writes datasource YAML files for external system.
+ * @param {string} outputDir - Output directory
+ * @param {string} systemKey - System key
+ * @param {Array} dataSourcesList - DataSources array
+ * @returns {Promise<string[]>} Paths to written datasource files
+ */
+async function writeDatasourceFiles(outputDir, systemKey, dataSourcesList) {
+  const paths = [];
+  for (let i = 0; i < dataSourcesList.length; i++) {
+    const ds = dataSourcesList[i];
+    const fileName = getExternalDatasourceFileName(systemKey, ds, i);
+    const dsPath = path.join(outputDir, fileName);
+    await writeComponentFile(dsPath, yaml.dump(ds, { indent: 2, lineWidth: -1 }));
+    paths.push(dsPath);
   }
-
-  // Write README.md
-  const readmePath = path.join(outputDir, 'README.md');
-  await writeComponentFile(readmePath, readme);
-  results.readme = readmePath;
-
-  return results;
+  return paths;
 }
 
 /**
@@ -194,25 +313,11 @@ async function writeExternalSystemAndDatasourceFiles(outputDir, deployment) {
   const system = deployment.system;
   const systemKey = system.key || 'external-system';
   const dataSourcesList = deployment.dataSources || deployment.datasources || [];
-  const results = {};
-
+  const { roles: _roles, permissions: _permissions, ...systemWithoutRbac } = system;
   const systemPath = path.join(outputDir, `${systemKey}-system.yaml`);
-  const systemYaml = yaml.dump(system, { indent: 2, lineWidth: -1 });
-  await writeComponentFile(systemPath, systemYaml);
-  results.systemFile = systemPath;
-
-  const datasourcePaths = [];
-  for (let i = 0; i < dataSourcesList.length; i++) {
-    const ds = dataSourcesList[i];
-    const fileName = getExternalDatasourceFileName(systemKey, ds, i);
-    const dsPath = path.join(outputDir, fileName);
-    const dsYaml = yaml.dump(ds, { indent: 2, lineWidth: -1 });
-    await writeComponentFile(dsPath, dsYaml);
-    datasourcePaths.push(dsPath);
-  }
-  results.datasourceFiles = datasourcePaths;
-
-  return results;
+  await writeComponentFile(systemPath, yaml.dump(systemWithoutRbac, { indent: 2, lineWidth: -1 }));
+  const datasourcePaths = await writeDatasourceFiles(outputDir, systemKey, dataSourcesList);
+  return { systemFile: systemPath, datasourceFiles: datasourcePaths };
 }
 
 /**
@@ -247,7 +352,49 @@ function normalizeDeploymentForSplit(deployment) {
  * @returns {Promise<Object>} Object with paths to generated files
  * @throws {Error} If JSON file not found or invalid
  */
-async function splitDeployJson(deployJsonPath, outputDir = null) {
+/**
+ * Builds write options for split from splitOptions and config array.
+ * @param {Object} splitOptions - Split options
+ * @param {Array} configArray - Deployment configuration array
+ * @returns {Object} Write options for writeComponentFiles
+ */
+function buildSplitWriteOptions(splitOptions, configArray) {
+  const writeOptions = {};
+  if (splitOptions.mergeEnvTemplate) {
+    writeOptions.mergeEnvTemplate = true;
+    writeOptions.configuration = configArray;
+  }
+  if (splitOptions.overwriteReadme === false) {
+    writeOptions.overwriteReadme = false;
+  }
+  return writeOptions;
+}
+
+/**
+ * Writes external system/datasource files if deployment has system and assigns to result.
+ * @param {string} finalOutputDir - Output directory
+ * @param {Object} deployment - Deployment object
+ * @param {Object} result - Result object to mutate
+ */
+async function applyExternalSystemFilesToResult(finalOutputDir, deployment, result) {
+  if (!deployment.system || typeof deployment.system !== 'object') {
+    return;
+  }
+  const externalFiles = await writeExternalSystemAndDatasourceFiles(finalOutputDir, deployment);
+  if (externalFiles.systemFile) result.systemFile = externalFiles.systemFile;
+  if (externalFiles.datasourceFiles && externalFiles.datasourceFiles.length > 0) {
+    result.datasourceFiles = externalFiles.datasourceFiles;
+  }
+}
+
+/**
+ * @param {string} deployJsonPath - Path to deployment JSON file
+ * @param {string} [outputDir] - Directory to write component files
+ * @param {Object} [splitOptions] - Options for split behavior
+ * @param {boolean} [splitOptions.mergeEnvTemplate] - If true and env.template exists, merge download config into it
+ * @param {boolean} [splitOptions.overwriteReadme] - If false and README.md exists, do not overwrite
+ */
+async function splitDeployJson(deployJsonPath, outputDir = null, splitOptions = {}) {
   validateDeployJsonPath(deployJsonPath);
   const finalOutputDir = await prepareOutputDirectory(deployJsonPath, outputDir);
   const deployment = await loadDeploymentJson(deployJsonPath);
@@ -259,16 +406,9 @@ async function splitDeployJson(deployJsonPath, outputDir = null) {
   const rbac = extractRbacYaml(deployment);
   const readme = generateReadmeFromDeployJson(deployment);
 
-  const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme);
-
-  if (deployment.system && typeof deployment.system === 'object') {
-    const externalFiles = await writeExternalSystemAndDatasourceFiles(finalOutputDir, deployment);
-    if (externalFiles.systemFile) result.systemFile = externalFiles.systemFile;
-    if (externalFiles.datasourceFiles && externalFiles.datasourceFiles.length > 0) {
-      result.datasourceFiles = externalFiles.datasourceFiles;
-    }
-  }
-
+  const writeOptions = buildSplitWriteOptions(splitOptions, configArray);
+  const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme, writeOptions);
+  await applyExternalSystemFilesToResult(finalOutputDir, deployment, result);
   return result;
 }