@aifabrix/builder 2.53.1 → 2.55.0

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

@@ -36,7 +36,30 @@ const {
 const path = require('path');
 
 /** Runtime/API fields that must not appear on external-system manifests. */
-const NON_MANIFEST_SYSTEM_KEYS = ['showOpenApiDocs'];
+const NON_MANIFEST_SYSTEM_KEYS = ['showOpenApiDocs', 'rbac'];
+
+/**
+ * Coerce system dataSources to unique string keys (dataplane may return objects).
+ * @param {*} dataSources
+ * @returns {string[]}
+ */
+function normalizeManifestDataSourceKeys(dataSources) {
+  if (!Array.isArray(dataSources)) {
+    return [];
+  }
+  const keys = [];
+  const seen = new Set();
+  for (const item of dataSources) {
+    const raw = typeof item === 'string' ? item : item && item.key;
+    const key = typeof raw === 'string' ? raw.trim() : '';
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    keys.push(key);
+  }
+  return keys;
+}
 
 /**
  * True when cwd looks like a product/workspace repo (integration, builder, or EK tree).
@@ -114,6 +137,9 @@ function sanitizeDownloadedApplication(application) {
   for (const key of NON_MANIFEST_SYSTEM_KEYS) {
     delete cleaned[key];
   }
+  if (Array.isArray(cleaned.dataSources)) {
+    cleaned.dataSources = normalizeManifestDataSourceKeys(cleaned.dataSources);
+  }
   return cleaned;
 }
 
@@ -296,6 +322,7 @@ module.exports = {
   runConvertToJsonIfRequested,
   generateVariablesYaml,
   generateReadme,
-  NON_MANIFEST_SYSTEM_KEYS
+  NON_MANIFEST_SYSTEM_KEYS,
+  normalizeManifestDataSourceKeys
 };
 

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

@@ -1,17 +1,46 @@
 /**
  * Role Assistant sidecar handling during external-system download.
  *
- * @fileoverview Post-download evidence/knowledge/workflow actions for digitalWorker systems
+ * @fileoverview Platform-shell download (digitalWorker / enterpriseKnowledge) plus RA sidecars
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 'use strict';
 
+const path = require('path');
 const logger = require('../utils/logger');
-const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatWarningLine,
+  formatSuccessLine,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
 const { exportRoleAssistantKnowledge, logKnowledgeExportSummary } = require('../role-assistant/knowledge-sync');
 const { exportRoleAssistantEvidence, logRoleAssistantEvidenceExportSummary } = require('../role-assistant/evidence-sync');
+const { writeOrMergeRoleAssistantSettings } = require('../role-assistant/settings');
+const {
+  isDigitalWorkerKind,
+  isEnterpriseKnowledgeKind,
+  isPlatformShellKind
+} = require('../utils/platform-shell-package');
+
+function connectedSystemDryRunFileNames(systemKey, dataSources, format) {
+  const { getExternalDatasourceFileName } = require('../generator/split-variables');
+  const ext = format === 'json' ? 'json' : 'yaml';
+  const names = [
+    `${systemKey}-deploy.json`,
+    `application.${ext}`,
+    `${systemKey}-system.${ext}`,
+    'env.template',
+    'README.md'
+  ];
+  const list = Array.isArray(dataSources) ? dataSources : [];
+  for (let i = 0; i < list.length; i += 1) {
+    const yamlName = getExternalDatasourceFileName(systemKey, list[i], i);
+    names.push(ext === 'json' ? yamlName.replace(/\.yaml$/i, '.json') : yamlName);
+  }
+  return names;
+}
 
 async function maybeExportRoleAssistantEvidenceArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options) {
   try {
@@ -28,6 +57,23 @@ async function maybeExportRoleAssistantEvidenceArtifacts(systemKey, manifest, da
   }
 }
 
+async function maybeExportRoleAssistantTestsArtifacts(systemKey, dataplaneUrl, authConfig, options) {
+  try {
+    const { exportRoleAssistantTests } = require('../role-assistant/test-pack-sync');
+    const testsResult = await exportRoleAssistantTests({
+      systemKey,
+      dataplaneUrl,
+      authConfig,
+      options
+    });
+    if (testsResult && testsResult.skipped) {
+      logger.log(formatWarningLine(`Role assistant tests export skipped: ${testsResult.reason}`));
+    }
+  } catch (testsErr) {
+    logger.log(formatWarningLine(`Role assistant tests export skipped: ${testsErr.message}`));
+  }
+}
+
 async function maybeExportRoleAssistantKnowledgeArtifacts(systemKey, manifest, dataplaneUrl, authConfig, options) {
   try {
     const knowledgeResult = await exportRoleAssistantKnowledge({
@@ -48,8 +94,67 @@ 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);
+  await maybeExportRoleAssistantTestsArtifacts(systemKey, dataplaneUrl, authConfig, options);
+}
+
+function logConnectedSystemDryRunFiles(systemKey, dataSources, format) {
+  logger.log(metadata('Would create:'));
+  connectedSystemDryRunFileNames(systemKey, dataSources, format).forEach((fileName) => {
+    logger.log(metadata(`  - integration/${systemKey}/${fileName}`));
+  });
+}
+
+function handleDownloadDryRun(systemKey, dataplaneUrl, application, dataSources, format) {
+  logger.log(formatWarningLine('Dry run mode: no files written.'));
+  logger.log(metadata(`Would fetch: ${dataplaneUrl}/api/v1/external/systems/${systemKey}/config`));
+  if (isEnterpriseKnowledgeKind(application)) {
+    logger.log(metadata('Would not write local package files.'));
+    return;
+  }
+  if (isDigitalWorkerKind(application)) {
+    logger.log(metadata('Would create:'));
+    logger.log(metadata(`  - role-assistant/${systemKey}/role-assistant.yaml`));
+    return;
+  }
+  logConnectedSystemDryRunFiles(systemKey, dataSources, format);
+}
+
+async function downloadDigitalWorkerPackage(params) {
+  const { systemKey, manifest, dataplaneUrl, authConfig, options = {} } = params;
+  const yamlPath = writeOrMergeRoleAssistantSettings(systemKey, {
+    force: options.force === true,
+    pathOptions: options.pathOptions || {}
+  });
+  logger.log(formatSuccessLine(`Wrote ${path.relative(process.cwd(), yamlPath)}`));
+  await runRoleAssistantDownloadSidecars({
+    systemKey,
+    manifest,
+    dataplaneUrl,
+    authConfig,
+    options
+  });
+  return true;
+}
+
+async function downloadPlatformShellIfNeeded(params) {
+  const application = params.manifest && params.manifest.application;
+  if (!isPlatformShellKind(application)) {
+    return false;
+  }
+  if (isEnterpriseKnowledgeKind(application)) {
+    logger.log(
+      formatSuccessLine(
+        `Enterprise Knowledge '${params.systemKey}' stays on the platform; no local package files written.`
+      )
+    );
+    return true;
+  }
+  return downloadDigitalWorkerPackage(params);
 }
 
 module.exports = {
-  runRoleAssistantDownloadSidecars
+  runRoleAssistantDownloadSidecars,
+  downloadPlatformShellIfNeeded,
+  handleDownloadDryRun,
+  connectedSystemDryRunFileNames
 };

package/lib/external-system/download.js

@@ -31,7 +31,7 @@ const readline = require('readline');
 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 { getConfig, getFormat } = require('../core/config');
 const { retemplateConfigurationForDownload, retemplateAllVariableDefinitions } = require('../utils/configuration-env-resolver');
 const { syncRuntimeConfigurationFromDataplane } = require('../utils/runtime-configuration-download');
 const logger = require('../utils/logger');
@@ -41,12 +41,17 @@ const {
   validateSystemType,
   validateDownloadedData,
   sanitizeDownloadedApplication,
+  normalizeManifestDataSourceKeys,
   resolveDownloadDestinationPath,
   logDownloadCommandHeader,
   displayDownloadSuccess,
   runConvertToJsonIfRequested
 } = require('./download-helpers');
-const { runRoleAssistantDownloadSidecars } = require('./download-role-assistant');
+const {
+  runRoleAssistantDownloadSidecars,
+  downloadPlatformShellIfNeeded,
+  handleDownloadDryRun
+} = require('./download-role-assistant');
 
 /**
  * Setup authentication and get dataplane URL
@@ -187,10 +192,14 @@ function augmentConfigurationWithAuthSecrets(system) {
  * @returns {Object} Deploy JSON object for splitDeployJson
  */
 function buildDeployJsonFromManifest(application, dataSources, version) {
-  const dataSourcesKeys = Array.isArray(dataSources)
-    ? dataSources.map(ds => (ds && ds.key) ? ds.key : ds)
-    : [];
-  const system = { ...application, dataSources: application.dataSources || dataSourcesKeys };
+  const fromApp = normalizeManifestDataSourceKeys(application.dataSources);
+  const fromInline = normalizeManifestDataSourceKeys(
+    Array.isArray(dataSources) ? dataSources.map(ds => (ds && ds.key) ? ds.key : ds) : []
+  );
+  const system = {
+    ...application,
+    dataSources: fromApp.length ? fromApp : fromInline
+  };
   augmentConfigurationWithAuthSecrets(system);
   const deploy = { system, dataSources };
   if (version) deploy.version = version;
@@ -211,26 +220,6 @@ function validateSystemKeyFormat(systemKey) {
   }
 }
 
-/**
- * Handle dry run mode
- * @param {string} systemKey - System key
- * @param {string} dataplaneUrl - Dataplane URL
- */
-function handleDryRun(systemKey, dataplaneUrl) {
-  logger.log(formatWarningLine('Dry run mode: no files written.'));
-  logger.log(metadata(`Would fetch: ${dataplaneUrl}/api/v1/external/systems/${systemKey}/config`));
-  logger.log(metadata('Would create:'));
-  [
-    `integration/${systemKey}/${systemKey}-deploy.json`,
-    `integration/${systemKey}/application.yaml`,
-    `integration/${systemKey}/${systemKey}-system.yaml`,
-    `integration/${systemKey}/env.template`,
-    `integration/${systemKey}/README.md`
-  ].forEach(rel => {
-    logger.log(metadata(`  - ${rel}`));
-  });
-}
-
 /**
  * Validate and log downloaded data
  * @param {Object} application - Application configuration
@@ -406,9 +395,21 @@ async function finalizeDownloadArtifacts({
  * @param {Object} [options]
  * @returns {Promise<void>}
  */
+async function resolveDownloadFormat(requested) {
+  const raw = typeof requested === 'string' ? requested.trim().toLowerCase() : '';
+  if (raw === 'json' || raw === 'yaml') {
+    return raw;
+  }
+  const fromConfig = await getFormat();
+  if (fromConfig === 'json' || fromConfig === 'yaml') {
+    return fromConfig;
+  }
+  return 'yaml';
+}
+
 async function downloadExternalSystem(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-  const format = (options.format || 'yaml').toLowerCase();
+  const format = await resolveDownloadFormat(options.format);
 
   try {
     logDownloadCommandHeader(systemKey);
@@ -418,12 +419,27 @@ async function downloadExternalSystem(systemKey, options = {}) {
       options,
       config
     );
+    const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig, options);
     if (options.dryRun) {
-      handleDryRun(systemKey, dataplaneUrl);
+      handleDownloadDryRun(
+        systemKey,
+        dataplaneUrl,
+        manifest.application,
+        manifest.dataSources,
+        format
+      );
+      return;
+    }
+    const platformHandled = await downloadPlatformShellIfNeeded({
+      systemKey,
+      manifest,
+      dataplaneUrl,
+      authConfig,
+      options
+    });
+    if (platformHandled) {
       return;
     }
-
-    const manifest = await downloadFullManifest(dataplaneUrl, systemKey, authConfig, options);
     validateAndLogDownloadedData(manifest.application, manifest.dataSources);
     const finalPath = resolveDownloadDestinationPath(systemKey, manifest.application);
     await processDownloadedSystem(

package/lib/external-system/sync-deploy-manifest.js

@@ -21,8 +21,9 @@ const logger = require('../utils/logger');
  * @returns {Promise<string>} Absolute path to the written deploy JSON file
  */
 async function syncDeployJsonFromSources(systemKey, opts = {}) {
-  const deployPath = await generator.generateDeployJson(systemKey, {});
-  if (!opts.quiet) {
+  const { quiet, ...generateOpts } = opts;
+  const deployPath = await generator.generateDeployJson(systemKey, generateOpts);
+  if (!quiet) {
     logger.log(formatSuccessLine(`Updated deployment manifest: ${deployPath}`));
   }
   return deployPath;

package/lib/external-system/upload-identity.js

@@ -0,0 +1,42 @@
+/**
+ * Fail closed when an upload payload's keys do not match the target system.
+ *
+ * @fileoverview Same contract as dataplane system_key_mismatch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} payload
+ * @param {string} systemKey
+ * @returns {void}
+ */
+function assertUploadPackageIdentity(payload, systemKey) {
+  if (!payload || typeof payload !== 'object') {
+    throw new Error('Upload payload is required.');
+  }
+  const applicationKey =
+    payload.application && typeof payload.application.key === 'string'
+      ? payload.application.key
+      : '';
+  if (applicationKey !== systemKey) {
+    throw new Error(
+      `systemKey '${applicationKey}' does not match expected system key '${systemKey}'`
+    );
+  }
+  const dataSources = Array.isArray(payload.dataSources) ? payload.dataSources : [];
+  for (const ds of dataSources) {
+    if (!ds || ds.systemKey === systemKey) {
+      continue;
+    }
+    throw new Error(
+      `systemKey '${ds.systemKey}' does not match expected system key '${systemKey}'`
+    );
+  }
+}
+
+module.exports = {
+  assertUploadPackageIdentity
+};

package/lib/generator/index.js

@@ -298,26 +298,30 @@ async function writeRegularDeployJson(appName, appPath, appType) {
   return jsonPath;
 }
 
-async function generateDeployJson(appName, options = {}) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-  let appPath;
-  let isExternal;
-  let appType;
+async function resolveDeployJsonAppContext(appName, options) {
   if (options.appPath) {
-    appPath = path.resolve(options.appPath);
+    const appPath = path.resolve(options.appPath);
     const configPath = resolveApplicationConfigPath(appPath);
     const { loadConfigFile } = require('../utils/config-format');
     const variables = loadConfigFile(configPath);
-    appType = variables?.app?.type || 'external';
-    isExternal = appType === 'external';
-  } else {
-    const detected = await detectAppType(appName, options);
-    appPath = detected.appPath;
-    isExternal = detected.isExternal;
-    appType = detected.appType;
+    const appType = variables?.app?.type || 'external';
+    return { appPath, appType, isExternal: appType === 'external' };
+  }
+  const detected = await detectAppType(appName, options);
+  const { throwIfPlatformShellHasNoDeployJson } = require('../utils/platform-shell-package');
+  throwIfPlatformShellHasNoDeployJson(appName, detected.baseDir);
+  return {
+    appPath: detected.appPath,
+    isExternal: detected.isExternal,
+    appType: detected.appType
+  };
+}
+
+async function generateDeployJson(appName, options = {}) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
   }
+  const { appPath, isExternal, appType } = await resolveDeployJsonAppContext(appName, options);
   logOfflinePathWhenType(appPath);
   if (isExternal) {
     return writeExternalDeployJson(appName, appPath, options);

package/lib/generator/split.js

@@ -15,6 +15,18 @@ const { parseImageReference } = require('./parse-image');
 const { generateReadmeFromDeployJson } = require('./split-readme');
 const { extractVariablesYaml, getExternalDatasourceFileName } = require('./split-variables');
 const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
+const { normalizeManifestDataSourceKeys } = require('../external-system/download-helpers');
+
+/**
+ * System YAML payload: omit runtime RBAC fields and coerce dataSources to keys.
+ * @param {Object} system
+ * @returns {Object}
+ */
+function systemYamlPayload(system) {
+  const { roles: _roles, permissions: _permissions, rbac: _rbac, ...rest } = system;
+  rest.dataSources = normalizeManifestDataSourceKeys(rest.dataSources);
+  return rest;
+}
 
 /**
  * Converts configuration array back to env.template format
@@ -339,9 +351,8 @@ async function writeExternalSystemAndDatasourceFiles(outputDir, deployment) {
   const system = deployment.system;
   const systemKey = system.key || 'external-system';
   const dataSourcesList = deployment.dataSources || deployment.datasources || [];
-  const { roles: _roles, permissions: _permissions, ...systemWithoutRbac } = system;
   const systemPath = path.join(outputDir, `${systemKey}-system.yaml`);
-  await writeComponentFile(systemPath, yaml.dump(systemWithoutRbac, { indent: 2, lineWidth: -1 }));
+  await writeComponentFile(systemPath, yaml.dump(systemYamlPayload(system), { indent: 2, lineWidth: -1 }));
   const datasourcePaths = await writeDatasourceFiles(outputDir, systemKey, dataSourcesList);
   return { systemFile: systemPath, datasourceFiles: datasourcePaths };
 }

package/lib/generator/wizard-datasource-key.js

@@ -0,0 +1,54 @@
+/**
+ * Canonical kebab datasource keys for wizard generate-config.
+ *
+ * @fileoverview Wizard datasource key segments
+ */
+
+'use strict';
+
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+function toKeySegment(str) {
+  if (!str || typeof str !== 'string') {
+    return 'default';
+  }
+  const withHyphens = str.replace(/([A-Z])/g, '-$1').toLowerCase();
+  const sanitized = withHyphens.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  return sanitized || 'default';
+}
+
+/**
+ * @param {string} finalSystemKey
+ * @param {{ key?: string, entityName?: string, entityType?: string, entityKey?: string }} ds
+ * @param {string} originalPrefix
+ * @param {Set<string>} [usedKeys]
+ * @returns {string}
+ */
+function wizardCanonicalDatasourceKey(finalSystemKey, ds, originalPrefix, usedKeys) {
+  const dsKey = String(ds.key || '').trim();
+  let segment;
+  if (dsKey && originalPrefix && dsKey.startsWith(originalPrefix)) {
+    segment = toKeySegment(dsKey.substring(originalPrefix.length));
+  } else {
+    const raw = ds.entityName || dsKey || ds.entityType || ds.entityKey || 'default';
+    segment = toKeySegment(raw);
+  }
+  let candidate = segment.includes('-') && !segment.startsWith(`${finalSystemKey}-`)
+    ? segment
+    : `${finalSystemKey}-${segment}`;
+  if (usedKeys && usedKeys.has(candidate)) {
+    let suffix = 2;
+    while (usedKeys.has(`${candidate}-${suffix}`)) {
+      suffix += 1;
+    }
+    candidate = `${candidate}-${suffix}`;
+  }
+  return candidate;
+}
+
+module.exports = {
+  toKeySegment,
+  wizardCanonicalDatasourceKey
+};

package/lib/generator/wizard.js

@@ -17,19 +17,7 @@ const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
 const { systemKeyToKvPrefix, securityKeyToVar, isValidKvPath } = require('../utils/credential-secrets-env');
 const { generateExternalEnvTemplateContent } = require('../utils/external-env-template');
 const { generateReadme } = require('./wizard-readme');
-
-/**
- * Converts a string to a schema-valid key segment (lowercase letters, numbers, hyphens only).
- * e.g. "recordStorage" -> "record-storage", "documentStorage" -> "document-storage"
- * @param {string} str - Raw entity type or key segment (may be camelCase)
- * @returns {string} Segment matching ^[a-z0-9-]+$
- */
-function toKeySegment(str) {
-  if (!str || typeof str !== 'string') return 'default';
-  const withHyphens = str.replace(/([A-Z])/g, '-$1').toLowerCase();
-  const sanitized = withHyphens.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-  return sanitized || 'default';
-}
+const { toKeySegment, wizardCanonicalDatasourceKey } = require('./wizard-datasource-key');
 
 const { normalizeAuthenticationToSystemKey } = require('../utils/authentication-shape');
 
@@ -118,10 +106,46 @@ async function writeDatasourceYamlFiles(appPath, finalSystemKey, datasourceConfi
  * @param {string} [params.aiGeneratedReadme] - Optional AI-generated README content
  * @returns {Promise<Object>} Object with file paths
  */
-async function generateConfigFilesForWizard(params) {
-  const { appPath, appName, finalSystemKey, systemFileName, datasourceFileNames, systemConfig, datasourceConfigs, aiGeneratedReadme, format } = params;
+async function writeWizardEnvTemplate(appPath, systemConfig) {
+  const envTemplatePath = path.join(appPath, 'env.template');
+  const envTemplateContent = generateExternalEnvTemplateContent(systemConfig);
+  await fs.writeFile(envTemplatePath, envTemplateContent, 'utf8');
+  logger.log(formatSuccessLine('Generated env.template'));
+  try {
+    const secretsEnsure = require('../core/secrets-ensure');
+    await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, {
+      emptyValuesForCredentials: true
+    });
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      logger.warn(`Could not ensure integration placeholder secrets: ${err.message}`);
+    }
+  }
+  return envTemplatePath;
+}
 
-  // Generate or update application config with externalIntegration block
+async function writeWizardDeployManifest(appPath, appName, finalSystemKey) {
+  const { generateControllerManifest, toDeployJsonShape } = require('./external-controller-manifest');
+  const manifest = await generateControllerManifest(appName, { appPath });
+  const deployJson = toDeployJsonShape(manifest);
+  const deployManifestPath = path.join(appPath, `${finalSystemKey}-deploy.json`);
+  await fs.writeFile(deployManifestPath, JSON.stringify(deployJson, null, 2), 'utf8');
+  logger.log(formatSuccessLine(`Generated deployment manifest: ${finalSystemKey}-deploy.json`));
+  return deployManifestPath;
+}
+
+async function generateConfigFilesForWizard(params) {
+  const {
+    appPath,
+    appName,
+    finalSystemKey,
+    systemFileName,
+    datasourceFileNames,
+    systemConfig,
+    datasourceConfigs,
+    aiGeneratedReadme,
+    format
+  } = params;
   const configPath = await generateOrUpdateVariablesYaml({
     appPath,
     appName,
@@ -131,21 +155,7 @@ async function generateConfigFilesForWizard(params) {
     systemConfig,
     format: format || 'yaml'
   });
-
-  // Generate env.template with Authentication and Configuration sections (Handlebars)
-  const envTemplatePath = path.join(appPath, 'env.template');
-  const envTemplateContent = generateExternalEnvTemplateContent(systemConfig);
-  await fs.writeFile(envTemplatePath, envTemplateContent, 'utf8');
-  logger.log(formatSuccessLine('Generated env.template'));
-
-  try {
-    const secretsEnsure = require('../core/secrets-ensure');
-    await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, { emptyValuesForCredentials: true });
-  } catch (err) {
-    if (err.code !== 'ENOENT') logger.warn(`Could not ensure integration placeholder secrets: ${err.message}`);
-  }
-
-  // Generate README.md (use AI-generated content if available)
+  const envTemplatePath = await writeWizardEnvTemplate(appPath, systemConfig);
   await generateReadme({
     appPath,
     appName,
@@ -155,21 +165,16 @@ async function generateConfigFilesForWizard(params) {
     aiGeneratedContent: aiGeneratedReadme,
     format
   });
-
-  // Generate deployment scripts
-  const deployScripts = await generateDeployScripts(appPath, finalSystemKey, systemFileName, datasourceFileNames);
-
-  // Generate deployment manifest (<systemKey>-deploy.json) using controller format
-  const { generateControllerManifest, toDeployJsonShape } = require('./external-controller-manifest');
-  const manifest = await generateControllerManifest(appName, { appPath });
-  const deployJson = toDeployJsonShape(manifest);
-  const deployManifestPath = path.join(appPath, `${finalSystemKey}-deploy.json`);
-  await fs.writeFile(deployManifestPath, JSON.stringify(deployJson, null, 2), 'utf8');
-  logger.log(formatSuccessLine(`Generated deployment manifest: ${finalSystemKey}-deploy.json`));
-
+  const deployScripts = await generateDeployScripts(
+    appPath,
+    finalSystemKey,
+    systemFileName,
+    datasourceFileNames
+  );
+  const deployManifestPath = await writeWizardDeployManifest(appPath, appName, finalSystemKey);
   return {
     variablesPath: configPath,
-    envTemplatePath: path.join(appPath, 'env.template'),
+    envTemplatePath,
     readmePath: path.join(appPath, 'README.md'),
     applicationSchemaPath: deployManifestPath,
     ...deployScripts
@@ -190,16 +195,10 @@ async function prepareWizardContext(appName, systemConfig, datasourceConfigs) {
     appDisplayName
   );
   const originalPrefix = `${originalSystemKey}-`;
+  const usedKeys = new Set();
   const updatedDatasourceConfigs = datasourceConfigs.map(ds => {
-    let newKey;
-    const dsKey = ds.key || '';
-    if (dsKey && dsKey.startsWith(originalPrefix)) {
-      newKey = `${finalSystemKey}-${dsKey.substring(originalPrefix.length)}`;
-    } else {
-      const entityType = ds.entityType || ds.entityKey || dsKey.split('-').pop() || 'default';
-      const keySegment = toKeySegment(entityType);
-      newKey = `${finalSystemKey}-${keySegment}`;
-    }
+    const newKey = wizardCanonicalDatasourceKey(finalSystemKey, ds, originalPrefix, usedKeys);
+    usedKeys.add(newKey);
     const entityType = ds.entityType || ds.entityKey || newKey.split('-').pop() || 'default';
     const entityDisplayName = String(entityType).charAt(0).toUpperCase() + String(entityType).slice(1).replace(/-/g, ' ');
     return { ...ds, key: newKey, systemKey: finalSystemKey, displayName: ds.displayName || `${appDisplayName} ${entityDisplayName}` };
@@ -481,6 +480,8 @@ const { generateDeployScripts } = require('./deploy-script');
 
 module.exports = {
   generateWizardFiles,
-  generateDeployScripts
+  generateDeployScripts,
+  wizardCanonicalDatasourceKey,
+  toKeySegment
 };