@aifabrix/builder 2.51.0 → 2.52.0

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

@@ -11,12 +11,45 @@
 const {
   formatSuccessLine,
   formatSuccessParagraph,
+  formatWarningLine,
   sectionTitle,
   headerKeyValue
 } = require('../utils/cli-test-layout-chalk');
 const logger = require('../utils/logger');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 const { getAuthCredentialTemplate } = require('../utils/authentication-shape');
+const {
+  getCwdIntegrationRoot,
+  getCwdBuilderRoot,
+  getAppsMaterializationParent
+} = require('../utils/paths');
+const {
+  SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  getCwdEnterpriseKnowledgeRoot,
+  getEnterpriseKnowledgeRoot
+} = require('../utils/enterprise-knowledge-paths');
+const {
+  SYSTEM_KIND_DIGITAL_WORKER,
+  getCwdRoleAssistantRoot,
+  getRoleAssistantRoot
+} = require('../utils/role-assistant-paths');
+const path = require('path');
+
+/** Runtime/API fields that must not appear on external-system manifests. */
+const NON_MANIFEST_SYSTEM_KEYS = ['showOpenApiDocs'];
+
+/**
+ * True when cwd looks like a product/workspace repo (integration, builder, or EK tree).
+ * @returns {boolean}
+ */
+function cwdHasWorkspaceTree() {
+  return Boolean(
+    getCwdIntegrationRoot() ||
+    getCwdBuilderRoot() ||
+    getCwdEnterpriseKnowledgeRoot() ||
+    getCwdRoleAssistantRoot()
+  );
+}
 
 /**
  * Validates system type from downloaded application
@@ -68,6 +101,61 @@ function validateDownloadedData(application, dataSources) {
   }
 }
 
+/**
+ * Strip dataplane runtime fields that are not part of external-system.schema.json.
+ * @param {Object} application
+ * @returns {Object}
+ */
+function sanitizeDownloadedApplication(application) {
+  if (!application || typeof application !== 'object') {
+    return application;
+  }
+  const cleaned = { ...application };
+  for (const key of NON_MANIFEST_SYSTEM_KEYS) {
+    delete cleaned[key];
+  }
+  return cleaned;
+}
+
+/**
+ * Download destination:
+ * - If cwd has `integration/`, `builder/`, or `enterprise-knowledge/` → write under cwd
+ * - Else → `aifabrix-work` / materialization parent
+ * Ignores materialization orphans when cwd has a workspace tree so re-download lands in-repo.
+ * @param {string} systemKey
+ * @param {Object} application
+ * @returns {string}
+ */
+function resolveDownloadDestinationPath(systemKey, application) {
+  const kind =
+    application && typeof application.systemKind === 'string'
+      ? application.systemKind.trim()
+      : '';
+  const useCwd = cwdHasWorkspaceTree();
+  if (kind === SYSTEM_KIND_DIGITAL_WORKER) {
+    if (useCwd) {
+      const cwdRoleAssistant = getCwdRoleAssistantRoot();
+      const roleAssistantRoot = cwdRoleAssistant || path.join(path.resolve(process.cwd()), 'role-assistant');
+      return path.join(roleAssistantRoot, systemKey);
+    }
+    return path.join(getRoleAssistantRoot(), systemKey);
+  }
+  if (kind === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE) {
+    if (useCwd) {
+      const cwdEk = getCwdEnterpriseKnowledgeRoot();
+      const ekRoot = cwdEk || path.join(path.resolve(process.cwd()), 'enterprise-knowledge');
+      return path.join(ekRoot, systemKey);
+    }
+    return path.join(getEnterpriseKnowledgeRoot(), systemKey);
+  }
+  if (useCwd) {
+    const cwdInt = getCwdIntegrationRoot();
+    const intRoot = cwdInt || path.join(path.resolve(process.cwd()), 'integration');
+    return path.join(intRoot, systemKey);
+  }
+  return path.join(getAppsMaterializationParent(), 'integration', systemKey);
+}
+
 function logDownloadCommandHeader(systemKey) {
   logger.log('');
   logger.log(sectionTitle('Download'));
@@ -83,13 +171,31 @@ function displayDownloadSuccess(systemKey, finalPath, datasourceCount) {
   logger.log(headerKeyValue('Location:', finalPath));
 }
 
+/**
+ * Convert YAML components to JSON after download. On validation failure, keep takeout
+ * and warn — do not discard downloaded files.
+ * @param {string} systemKey
+ * @returns {Promise<{converted: boolean, error?: string}>}
+ */
 async function runConvertToJsonIfRequested(systemKey) {
   const { runConvert } = require('../commands/convert');
   try {
     await runConvert(systemKey, { format: 'json', force: true });
     logger.log(formatSuccessLine('Converted component files to JSON'));
+    return { converted: true };
   } catch (convertErr) {
-    throw new Error(`Download succeeded but convert to JSON failed: ${convertErr.message}`);
+    const message = convertErr && convertErr.message ? convertErr.message : String(convertErr);
+    logger.log(
+      formatWarningLine(
+        `Download saved files, but convert to JSON failed: ${message}`
+      )
+    );
+    logger.log(
+      formatWarningLine(
+        'Fix schema errors in the downloaded files, then run: aifabrix convert <systemKey> --format json'
+      )
+    );
+    return { converted: false, error: message };
   }
 }
 
@@ -183,10 +289,13 @@ function generateReadme(systemKey, application, dataSources) {
 module.exports = {
   validateSystemType,
   validateDownloadedData,
+  sanitizeDownloadedApplication,
+  resolveDownloadDestinationPath,
   logDownloadCommandHeader,
   displayDownloadSuccess,
   runConvertToJsonIfRequested,
   generateVariablesYaml,
-  generateReadme
+  generateReadme,
+  NON_MANIFEST_SYSTEM_KEYS
 };
 

package/lib/external-system/download-role-assistant.js

@@ -0,0 +1,55 @@
+/**
+ * Role Assistant sidecar handling during external-system download.
+ *
+ * @fileoverview Post-download evidence/knowledge/workflow actions for digitalWorker systems
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { exportRoleAssistantKnowledge, logKnowledgeExportSummary } = require('../role-assistant/knowledge-sync');
+const { exportRoleAssistantEvidence, logRoleAssistantEvidenceExportSummary } = require('../role-assistant/evidence-sync');
+
+async function maybeExportRoleAssistantEvidenceArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options) {
+  try {
+    const evidenceResult = await exportRoleAssistantEvidence({
+      systemKey,
+      dataplaneUrl,
+      authConfig,
+      manifest,
+      pathOptions: options.pathOptions || {}
+    });
+    logRoleAssistantEvidenceExportSummary(systemKey, evidenceResult, { verbose: options.verbose === true });
+  } catch (evidenceErr) {
+    logger.log(formatWarningLine(`Role assistant evidence export skipped: ${evidenceErr.message}`));
+  }
+}
+
+async function maybeExportRoleAssistantKnowledgeArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options) {
+  try {
+    const knowledgeResult = await exportRoleAssistantKnowledge({
+      systemKey,
+      dataplaneUrl,
+      authConfig,
+      manifest,
+      environment: options.env || options.environment || 'dev',
+      pathOptions: options.pathOptions || {}
+    });
+    logKnowledgeExportSummary(systemKey, knowledgeResult, { verbose: options.verbose === true });
+  } catch (knowledgeErr) {
+    logger.log(formatWarningLine(`Role assistant knowledge export skipped: ${knowledgeErr.message}`));
+  }
+}
+
+async function runRoleAssistantDownloadSidecars(params) {
+  const { systemKey, manifest, dataplaneUrl, authConfig, options = {} } = params;
+  await maybeExportRoleAssistantEvidenceArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options);
+  await maybeExportRoleAssistantKnowledgeArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options);
+}
+
+module.exports = {
+  runRoleAssistantDownloadSidecars
+};

package/lib/external-system/download.js

@@ -32,7 +32,6 @@ const yaml = require('js-yaml');
 const { getExternalSystemConfig } = require('../api/external-systems.api');
 const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { getConfig } = require('../core/config');
-const { getIntegrationPath } = require('../utils/paths');
 const { retemplateConfigurationForDownload, retemplateAllVariableDefinitions } = require('../utils/configuration-env-resolver');
 const { syncRuntimeConfigurationFromDataplane } = require('../utils/runtime-configuration-download');
 const logger = require('../utils/logger');
@@ -41,10 +40,13 @@ const generator = require('../generator');
 const {
   validateSystemType,
   validateDownloadedData,
+  sanitizeDownloadedApplication,
+  resolveDownloadDestinationPath,
   logDownloadCommandHeader,
   displayDownloadSuccess,
   runConvertToJsonIfRequested
 } = require('./download-helpers');
+const { runRoleAssistantDownloadSidecars } = require('./download-role-assistant');
 
 /**
  * Setup authentication and get dataplane URL
@@ -117,7 +119,11 @@ async function downloadFullManifest(dataplaneUrl, systemKey, authConfig, options
     throw new Error('Application configuration not found in download response');
   }
 
-  return { application, dataSources, version };
+  return {
+    application: sanitizeDownloadedApplication(application),
+    dataSources,
+    version
+  };
 }
 
 /**
@@ -304,9 +310,8 @@ async function applyRetemplateToSystemFile(systemKey, systemFilePath) {
  * @returns {Promise<string>} Final destination path
  * @throws {Error} If processing fails
  */
-async function processDownloadedSystem(systemKey, manifest, splitOptions = {}) {
+async function processDownloadedSystem(systemKey, manifest, finalPath, splitOptions = {}) {
   const { application, dataSources, version } = manifest;
-  const finalPath = getIntegrationPath(systemKey);
 
   logger.log(formatProgress('Creating integration directory…'));
   logger.log(metadata(finalPath));
@@ -331,6 +336,28 @@ async function processDownloadedSystem(systemKey, manifest, splitOptions = {}) {
   return finalPath;
 }
 
+async function maybeSyncRuntimeConfigurationForDownload(systemKey, manifest, finalPath, dataplaneUrl, authConfig) {
+  try {
+    const configSync = await syncRuntimeConfigurationFromDataplane({
+      dataplaneUrl,
+      authConfig,
+      systemKey,
+      integrationPath: finalPath,
+      dataSources: manifest.dataSources
+    });
+    if (configSync.merged > 0) {
+      const nameList = configSync.names.length ? ` (${configSync.names.join(', ')})` : '';
+      logger.log(
+        formatSuccessLine(
+          `Merged ${configSync.merged} runtime configuration variable(s) into env.template${nameList}.`
+        )
+      );
+    }
+  } catch (syncErr) {
+    logger.log(formatWarningLine(`Runtime configuration sync skipped: ${syncErr.message}`));
+  }
+}
+
 /**
  * Post-split download steps: governance packs, optional JSON convert, runtime config sync.
  * @param {Object} params
@@ -348,7 +375,8 @@ async function finalizeDownloadArtifacts({
   finalPath,
   dataplaneUrl,
   authConfig,
-  format
+  format,
+  options = {}
 }) {
   const { downloadGovernanceScenarioPacksFromManifest } = require('../lifecycle/scenario-upload');
   await downloadGovernanceScenarioPacksFromManifest(
@@ -360,25 +388,14 @@ async function finalizeDownloadArtifacts({
   if (format === 'json') {
     await runConvertToJsonIfRequested(systemKey);
   }
-  try {
-    const configSync = await syncRuntimeConfigurationFromDataplane({
-      dataplaneUrl,
-      authConfig,
-      systemKey,
-      integrationPath: finalPath,
-      dataSources: manifest.dataSources
-    });
-    if (configSync.merged > 0) {
-      const nameList = configSync.names.length ? ` (${configSync.names.join(', ')})` : '';
-      logger.log(
-        formatSuccessLine(
-          `Merged ${configSync.merged} runtime configuration variable(s) into env.template${nameList}.`
-        )
-      );
-    }
-  } catch (syncErr) {
-    logger.log(formatWarningLine(`Runtime configuration sync skipped: ${syncErr.message}`));
-  }
+  await maybeSyncRuntimeConfigurationForDownload(systemKey, manifest, finalPath, dataplaneUrl, authConfig);
+  await runRoleAssistantDownloadSidecars({
+    systemKey,
+    manifest,
+    dataplaneUrl,
+    authConfig,
+    options
+  });
   displayDownloadSuccess(systemKey, finalPath, manifest.dataSources.length);
 }
 
@@ -408,10 +425,11 @@ async function downloadExternalSystem(systemKey, options = {}) {
 
     const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig, options);
     validateAndLogDownloadedData(manifest.application, manifest.dataSources);
-    const finalPath = getIntegrationPath(systemKey);
+    const finalPath = resolveDownloadDestinationPath(systemKey, manifest.application);
     await processDownloadedSystem(
       systemKey,
       manifest,
+      finalPath,
       await resolveDownloadSplitOptions(finalPath, options)
     );
     await finalizeDownloadArtifacts({
@@ -420,7 +438,8 @@ async function downloadExternalSystem(systemKey, options = {}) {
       finalPath,
       dataplaneUrl,
       authConfig,
-      format
+      format,
+      options
     });
   } catch (error) {
     throw new Error(`Failed to download external system: ${error.message}`);

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

@@ -78,7 +78,7 @@ function validateSystemFilesForTest(systemFiles, results) {
  * @param {Function} determineDatasourcesToTest - Function to determine datasources to test
  */
 function validateDatasourceFilesForTest(datasourceFiles, systemFiles, results, options, validateSingleDatasource, determineDatasourcesToTest) {
-  const datasourcesToTest = determineDatasourcesToTest(datasourceFiles, options.datasource);
+  const datasourcesToTest = determineDatasourcesToTest(datasourceFiles, options.datasource, options);
   const systemKey = systemFiles.length > 0 ? systemFiles[0].data.key : null;
 
   for (const datasourceFile of datasourcesToTest) {

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

@@ -12,7 +12,7 @@ const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { writeTestLog } = require('../utils/test-log-writer');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { runUnifiedDatasourceValidation } = require('../datasource/unified-validation-run');
 
 async function runOneDatasourceKey(appName, datasourceKey, opts) {
@@ -61,16 +61,34 @@ async function runOneDatasourceKey(appName, datasourceKey, opts) {
       };
     }
     const env = uni.envelope;
-    const ok = env && typeof env.status === 'string' ? env.status !== 'fail' : false;
+    const ok = isDatasourceRunSuccessful(env);
     return { key: datasourceKey, success: ok, skipped: false, datasourceTestRun: env };
   } catch (err) {
     return { key: datasourceKey, success: false, skipped: false, error: err.message };
   }
 }
 
+/**
+ * Prefer explicit envelope status; soft-pass when validation+certificate succeeded
+ * (documentStorage packs may report overall fail only for missing live evidence).
+ * @param {Object|null|undefined} env
+ * @returns {boolean}
+ */
+function isDatasourceRunSuccessful(env) {
+  if (!env || typeof env.status !== 'string') {
+    return false;
+  }
+  if (env.status !== 'fail') {
+    return true;
+  }
+  const validationOk = env.validation && env.validation.status === 'ok';
+  const certPassed = env.certificate && env.certificate.status === 'passed';
+  return Boolean(validationOk && certPassed);
+}
+
 async function maybeWriteSystemRunLog(appName, systemKey, datasourceKeys, runType, debug, payload) {
   if (!debug) return;
-  const appPath = getIntegrationPath(appName);
+  const appPath = resolveExternalSystemPath(appName);
   const integrationDir = path.dirname(appPath);
   const logPath = await writeTestLog(
     appName,

package/lib/external-system/test.js

@@ -39,6 +39,20 @@ const { runSystemLevelTest } = require('./test-system-level');
 const { shouldUseSystemLevelIntegrationCall } = require('./integration-test-dispatch');
 const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
+const EMPTY_DATASOURCE_ALLOWED_KINDS = new Set(['enterpriseKnowledge', 'digitalWorker']);
+
+function resolvePrimarySystemKind(systemFiles) {
+  if (!Array.isArray(systemFiles) || systemFiles.length === 0) {
+    return '';
+  }
+  const kind = systemFiles[0] && systemFiles[0].data ? systemFiles[0].data.systemKind : '';
+  return typeof kind === 'string' ? kind.trim() : '';
+}
+
+function allowEmptyDatasourcesForKind(systemKind) {
+  return EMPTY_DATASOURCE_ALLOWED_KINDS.has(String(systemKind || '').trim());
+}
+
 /**
  * Loads and parses application config file
  * @async
@@ -320,11 +334,25 @@ async function testExternalSystem(appName, options = {}) {
 
     // Load files
     const { variables: _variables, systemFiles, datasourceFiles } = await loadExternalSystemFiles(appName);
+    const systemKind = resolvePrimarySystemKind(systemFiles);
+    const allowEmptyDatasources = allowEmptyDatasourcesForKind(systemKind);
 
     const results = initializeTestResults();
 
     validateSystemFilesForTest(systemFiles, results);
-    validateDatasourceFilesForTest(datasourceFiles, systemFiles, results, options, validateSingleDatasource, determineDatasourcesToTest);
+    validateDatasourceFilesForTest(
+      datasourceFiles,
+      systemFiles,
+      results,
+      { ...options, allowEmptyDatasources, systemKindForEmptyDatasources: systemKind },
+      validateSingleDatasource,
+      determineDatasourcesToTest
+    );
+    if (allowEmptyDatasources && results.datasourceResults.length === 0) {
+      results.warnings.push(
+        `No datasources defined; integration validation is N/A for systemKind "${systemKind}".`
+      );
+    }
 
     results.systemKey = systemFiles.length > 0 ? systemFiles[0].data.key : appName;
     results.appName = appName;
@@ -383,12 +411,15 @@ async function testExternalSystem(appName, options = {}) {
  * @returns {Array} Filtered datasource files
  * @throws {Error} If no datasources found
  */
-function determineDatasourcesToTest(datasourceFiles, datasourceFilter) {
+function determineDatasourcesToTest(datasourceFiles, datasourceFilter, options = {}) {
   const datasourcesToTest = datasourceFilter
     ? datasourceFiles.filter(ds => ds.data.key === datasourceFilter || path.basename(ds.path).includes(datasourceFilter))
     : datasourceFiles;
 
   if (datasourcesToTest.length === 0) {
+    if (options.allowEmptyDatasources === true) {
+      return [];
+    }
     throw new Error('No datasources found to test');
   }
 
@@ -429,13 +460,18 @@ async function prepareIntegrationTestEnvironment(appName, options) {
   }
 
   const systemKey = systemFiles[0].data.key;
+  const systemKind = resolvePrimarySystemKind(systemFiles);
+  const allowEmptyDatasources = allowEmptyDatasourcesForKind(systemKind);
 
   // Setup authentication and dataplane URL
   const config = await getConfig();
   const { authConfig, dataplaneUrl } = await setupIntegrationTestAuth(appName, options, config);
 
   // Determine datasources to test
-  const datasourcesToTest = determineDatasourcesToTest(datasourceFiles, options.datasource);
+  const datasourcesToTest = determineDatasourcesToTest(datasourceFiles, options.datasource, {
+    allowEmptyDatasources,
+    systemKindForEmptyDatasources: systemKind
+  });
 
   // Load custom payload if provided
   const customPayload = await testHelpers.loadCustomPayload(options.payload);
@@ -497,8 +533,8 @@ async function testExternalSystemIntegration(appName, options = {}) {
         if (options.debug) {
           try {
             const { writeTestLog } = require('../utils/test-log-writer');
-            const { getIntegrationPath } = require('../utils/paths');
-            const appPath = getIntegrationPath(appName);
+            const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+            const appPath = resolveExternalSystemPath(appName);
             await writeTestLog(appName, { request: { systemKey }, error: err.message }, 'test-integration', path.dirname(appPath));
           } catch (_) { /* ignore */ }
         }
@@ -525,8 +561,8 @@ async function testExternalSystemIntegration(appName, options = {}) {
       if (options.debug && results.datasourceResults.length > 0) {
         try {
           const { writeTestLog } = require('../utils/test-log-writer');
-          const { getIntegrationPath } = require('../utils/paths');
-          const appPath = getIntegrationPath(appName);
+          const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+          const appPath = resolveExternalSystemPath(appName);
           await writeTestLog(appName, {
             request: { systemKey, datasource: options.datasource, includeDebug: true },
             response: results

package/lib/generator/builders.js

@@ -27,24 +27,18 @@ function sanitizeAuthType(authType) {
 }
 
 /**
- * Filters configuration based on registry mode
- * When registryMode is "external", only DOCKER_REGISTRY_SERVER_* variables are allowed
+ * Historically (incorrectly) stripped all non-DOCKER_REGISTRY_* vars when
+ * registryMode was "external", which wiped platform app env/portal config on
+ * `aifabrix json`. External only means image pull source — keep full configuration.
+ * DOCKER_REGISTRY_SERVER_* may still appear when present in env.template.
+ *
  * @function filterConfigurationByRegistryMode
  * @param {Array} configuration - Environment configuration
- * @param {string} registryMode - Registry mode ('external' or 'internal')
- * @returns {Array} Filtered configuration
+ * @param {string} _registryMode - Registry mode ('external' or 'acr'); unused
+ * @returns {Array} Configuration unchanged
  */
-function filterConfigurationByRegistryMode(configuration, registryMode) {
-  if (registryMode !== 'external') {
-    return configuration;
-  }
-
-  const allowedDockerRegistryVars = [
-    'DOCKER_REGISTRY_SERVER_URL',
-    'DOCKER_REGISTRY_SERVER_USERNAME',
-    'DOCKER_REGISTRY_SERVER_PASSWORD'
-  ];
-  return configuration.filter(config => allowedDockerRegistryVars.includes(config.name));
+function filterConfigurationByRegistryMode(configuration, _registryMode) {
+  return Array.isArray(configuration) ? configuration : [];
 }
 
 function buildImageReference(variables) {
@@ -276,6 +270,9 @@ function validateBuildFields(build) {
   if (typeof build.imageRunBeat === 'string' && build.imageRunBeat.trim()) {
     buildConfig.imageRunBeat = build.imageRunBeat.trim();
   }
+  if (typeof build.deployJob === 'string' && build.deployJob.trim()) {
+    buildConfig.deployJob = build.deployJob.trim();
+  }
 
   return Object.keys(buildConfig).length > 0 ? buildConfig : null;
 }

package/lib/generator/wizard.js

@@ -213,12 +213,21 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
     const fmt = format === 'json' ? 'json' : 'yaml';
     const ext = FORMAT_EXT[fmt] || '.yaml';
     const { appPath, finalSystemKey, updatedSystemConfig, updatedDatasourceConfigs } = await prepareWizardContext(appName, systemConfig, datasourceConfigs);
+    const newDatasourceFileNames = await writeDatasourceYamlFiles(appPath, finalSystemKey, updatedDatasourceConfigs, fmt);
+    const existingDatasourceFileNames = listExistingDatasourceFileNames(appPath, finalSystemKey, ext);
+    const datasourceFileNames = [...new Set([...existingDatasourceFileNames, ...newDatasourceFileNames])];
+    const existingDatasourceKeys = datasourceFileNames
+      .map((name) => datasourceFileNameToKey(name, finalSystemKey, ext))
+      .filter(Boolean);
     const systemConfigWithDataSourcesKeys = {
       ...updatedSystemConfig,
-      dataSources: updatedDatasourceConfigs.map(ds => ds.key)
+      dataSources: [...new Set([
+        ...(Array.isArray(updatedSystemConfig.dataSources) ? updatedSystemConfig.dataSources : []),
+        ...existingDatasourceKeys,
+        ...updatedDatasourceConfigs.map((ds) => ds.key).filter(Boolean)
+      ])]
     };
     const systemFilePath = await writeSystemYamlFile(appPath, finalSystemKey, systemConfigWithDataSourcesKeys, fmt);
-    const datasourceFileNames = await writeDatasourceYamlFiles(appPath, finalSystemKey, updatedDatasourceConfigs, fmt);
     const systemFileName = `${finalSystemKey}-system${ext}`;
     const configFiles = await generateConfigFilesForWizard({
       appPath,
@@ -234,7 +243,7 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
     return {
       appPath,
       systemFilePath,
-      datasourceFilePaths: datasourceFileNames.map(name => path.join(appPath, name)),
+      datasourceFilePaths: newDatasourceFileNames.map(name => path.join(appPath, name)),
       ...configFiles
     };
   } catch (error) {
@@ -242,6 +251,40 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
   }
 }
 
+/**
+ * List existing datasource files so add-datasource merges instead of replacing.
+ * @param {string} appPath
+ * @param {string} finalSystemKey
+ * @param {string} ext
+ * @returns {string[]}
+ */
+function listExistingDatasourceFileNames(appPath, finalSystemKey, ext) {
+  const fsSync = require('fs');
+  if (!fsSync.existsSync(appPath)) {
+    return [];
+  }
+  const prefix = `${finalSystemKey}-datasource-`;
+  return fsSync
+    .readdirSync(appPath)
+    .filter((name) => name.startsWith(prefix) && name.endsWith(ext));
+}
+
+/**
+ * Map `systemKey-datasource-companies.json` → `systemKey-companies`.
+ * @param {string} fileName
+ * @param {string} finalSystemKey
+ * @param {string} ext
+ * @returns {string|null}
+ */
+function datasourceFileNameToKey(fileName, finalSystemKey, ext) {
+  const prefix = `${finalSystemKey}-datasource-`;
+  if (!fileName.startsWith(prefix) || !fileName.endsWith(ext)) {
+    return null;
+  }
+  const segment = fileName.slice(prefix.length, fileName.length - ext.length);
+  return segment ? `${finalSystemKey}-${segment}` : null;
+}
+
 function mergeAppAndExternalIntegration(variables, appName, systemFileName, datasourceFileNames, systemConfig) {
   if (!variables.app) {
     variables.app = {
@@ -257,10 +300,14 @@ function mergeAppAndExternalIntegration(variables, appName, systemFileName, data
   if (!variables.deployment) {
     variables.deployment = { controllerUrl: '', environment: 'dev' };
   }
+  const existingDs = Array.isArray(variables.externalIntegration?.dataSources)
+    ? variables.externalIntegration.dataSources
+    : [];
+  const mergedDataSources = [...new Set([...existingDs, ...datasourceFileNames])];
   variables.externalIntegration = {
     schemaBasePath: './',
     systems: [systemFileName],
-    dataSources: datasourceFileNames,
+    dataSources: mergedDataSources,
     autopublish: true,
     version: systemConfig.version || '1.0.0'
   };