@aifabrix/builder 2.37.0 → 2.37.5

package/lib/deployment/deployer.js

@@ -16,6 +16,23 @@ const { validateControllerUrl, validateEnvironmentKey } = require('../utils/depl
 const { handleDeploymentError, handleDeploymentErrors } = require('../utils/deployment-errors');
 const { validatePipeline, deployPipeline, getPipelineDeployment } = require('../api/pipeline.api');
 const { handleValidationResponse } = require('../utils/deployment-validation-helpers');
+const {
+  convertToPipelineAuthConfig,
+  processDeploymentStatusResponse
+} = require('./deployer-status');
+
+/**
+ * For external systems, send full manifest (application + inline system + full dataSources).
+ * No transform - controller receives complete application, external system, and data sources.
+ * @param {Object} manifest - Full manifest (type 'external', system, dataSources as full objects)
+ * @returns {Object} Manifest to send to pipeline (external sent as-is)
+ */
+function transformExternalManifestForPipeline(manifest) {
+  if (!manifest) {
+    return manifest;
+  }
+  return manifest;
+}
 
 /**
  * Build validation data for deployment
@@ -28,27 +45,42 @@ const { handleValidationResponse } = require('../utils/deployment-validation-hel
  */
 async function buildValidationData(manifest, validatedEnvKey, authConfig, options) {
   const tokenManager = require('../utils/token-manager');
-  const { clientId, clientSecret } = await tokenManager.extractClientCredentials(
-    authConfig,
-    manifest.key,
-    validatedEnvKey,
-    options
-  );
+  let clientId;
+  let clientSecret;
+  let pipelineAuthConfig;
+
+  try {
+    const credentials = await tokenManager.extractClientCredentials(
+      authConfig,
+      manifest.key,
+      validatedEnvKey,
+      options
+    );
+    clientId = credentials.clientId;
+    clientSecret = credentials.clientSecret;
+    pipelineAuthConfig = {
+      type: 'client-credentials',
+      clientId,
+      clientSecret
+    };
+  } catch (credError) {
+    if (authConfig.type === 'bearer' && authConfig.token) {
+      pipelineAuthConfig = { type: 'bearer', token: authConfig.token };
+      clientId = manifest.key;
+      clientSecret = '';
+    } else {
+      throw credError;
+    }
+  }
 
   const repositoryUrl = options.repositoryUrl || `https://github.com/aifabrix/${manifest.key}`;
   const validationData = {
-    clientId: clientId,
-    clientSecret: clientSecret,
+    clientId: clientId || '',
+    clientSecret: clientSecret || '',
     repositoryUrl: repositoryUrl,
     applicationConfig: manifest
   };
 
-  const pipelineAuthConfig = {
-    type: 'client-credentials',
-    clientId: clientId,
-    clientSecret: clientSecret
-  };
-
   return { validationData, pipelineAuthConfig };
 }
 
@@ -130,7 +162,7 @@ function validateDeploymentCredentials(authConfig) {
 }
 
 /**
- * Build deployment data and auth config
+ * Build deployment data and auth config (supports bearer-only when no client credentials)
  * @param {string} validateToken - Validation token
  * @param {Object} authConfig - Authentication configuration
  * @param {Object} options - Deployment options
@@ -143,11 +175,13 @@ function buildDeploymentData(validateToken, authConfig, options) {
     imageTag: imageTag
   };
 
-  const pipelineAuthConfig = {
-    type: 'client-credentials',
-    clientId: authConfig.clientId,
-    clientSecret: authConfig.clientSecret
-  };
+  const pipelineAuthConfig = authConfig.type === 'bearer' && authConfig.token && !authConfig.clientId
+    ? { type: 'bearer', token: authConfig.token }
+    : {
+      type: 'client-credentials',
+      clientId: authConfig.clientId,
+      clientSecret: authConfig.clientSecret
+    };
 
   return { deployData, pipelineAuthConfig };
 }
@@ -212,10 +246,12 @@ async function sendDeploymentRequest(url, envKey, validateToken, authConfig, opt
   const validatedEnvKey = validateEnvironmentKey(envKey);
   const maxRetries = options.maxRetries || 3;
 
-  // Validate credentials
-  validateDeploymentCredentials(authConfig);
+  const useBearerOnly = authConfig.type === 'bearer' && authConfig.token && !authConfig.clientId;
+  if (!useBearerOnly) {
+    validateDeploymentCredentials(authConfig);
+  }
 
-  // Build deployment data
+  // Build deployment data (supports bearer-only when no client credentials)
   const { deployData, pipelineAuthConfig } = buildDeploymentData(validateToken, authConfig, options);
 
   // Wrap API call with retry logic
@@ -237,92 +273,6 @@ async function sendDeploymentRequest(url, envKey, validateToken, authConfig, opt
   throwDeploymentError(lastError, maxRetries);
 }
 
-/**
- * Checks if deployment status is terminal
- * @function isTerminalStatus
- * @param {string} status - Deployment status
- * @returns {boolean} True if status is terminal
- */
-function isTerminalStatus(status) {
-  return status === 'completed' || status === 'failed' || status === 'cancelled';
-}
-
-/**
- * Convert authConfig to pipeline auth config format
- * @param {Object} authConfig - Authentication configuration
- * @returns {Object} Pipeline auth config
- */
-function convertToPipelineAuthConfig(authConfig) {
-  return authConfig.type === 'bearer'
-    ? { type: 'bearer', token: authConfig.token }
-    : { type: 'client-credentials', clientId: authConfig.clientId, clientSecret: authConfig.clientSecret };
-}
-
-/**
- * Process deployment status response
- * @param {Object} response - API response
- * @param {number} attempt - Current attempt number
- * @param {number} maxAttempts - Maximum attempts
- * @param {number} interval - Polling interval
- * @param {string} deploymentId - Deployment ID for error messages
- * @returns {Object|null} Deployment data if terminal, null if needs to continue polling
- */
-/**
- * Handles error response from deployment status check
- * @function handleDeploymentStatusError
- * @param {Object} response - API response
- * @param {string} deploymentId - Deployment ID
- * @throws {Error} Appropriate error message
- */
-function handleDeploymentStatusError(response, deploymentId) {
-  if (response.status === 404) {
-    throw new Error(`Deployment ${deploymentId || response.deploymentId || 'unknown'} not found`);
-  }
-  throw new Error(`Status check failed: ${response.formattedError || response.error || 'Unknown error'}`);
-}
-
-/**
- * Extracts deployment data from response
- * @function extractDeploymentData
- * @param {Object} response - API response
- * @returns {Object} Deployment data
- */
-function extractDeploymentData(response) {
-  const responseData = response.data;
-  return responseData.data || responseData;
-}
-
-/**
- * Logs deployment progress
- * @function logDeploymentProgress
- * @param {Object} deploymentData - Deployment data
- * @param {number} attempt - Current attempt
- * @param {number} maxAttempts - Maximum attempts
- */
-function logDeploymentProgress(deploymentData, attempt, maxAttempts) {
-  const status = deploymentData.status;
-  const progress = deploymentData.progress || 0;
-  logger.log(chalk.blue(`   Status: ${status} (${progress}%) (attempt ${attempt + 1}/${maxAttempts})`));
-}
-
-async function processDeploymentStatusResponse(response, attempt, maxAttempts, interval, deploymentId) {
-  if (!response.success || !response.data) {
-    handleDeploymentStatusError(response, deploymentId);
-  }
-
-  const deploymentData = extractDeploymentData(response);
-  if (isTerminalStatus(deploymentData.status)) {
-    return deploymentData;
-  }
-
-  logDeploymentProgress(deploymentData, attempt, maxAttempts);
-  if (attempt < maxAttempts - 1) {
-    await new Promise(resolve => setTimeout(resolve, interval));
-  }
-
-  return null;
-}
-
 /**
  * Polls deployment status from controller
  * Uses pipeline endpoint for CI/CD monitoring with minimal deployment info
@@ -470,9 +420,11 @@ async function deployToController(manifest, controllerUrl, envKey, authConfig, o
   // Log deployment attempt for audit
   await auditLogger.logDeploymentAttempt(manifest.key, url, options);
 
+  const pipelineManifest = transformExternalManifestForPipeline(manifest);
+
   try {
     // Send deployment request
-    const result = await sendDeployment(url, validatedEnvKey, manifest, authConfig, options);
+    const result = await sendDeployment(url, validatedEnvKey, pipelineManifest, authConfig, options);
 
     // Poll for deployment status if enabled
     return await pollDeployment(result, url, validatedEnvKey, authConfig, options);

package/lib/deployment/environment.js

@@ -9,16 +9,21 @@
  * @version 2.0.0
  */
 
+const fs = require('fs');
+const path = require('path');
 const chalk = require('chalk');
+const Ajv = require('ajv');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { validateControllerUrl, validateEnvironmentKey } = require('../utils/deployment-validation');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
-const { getEnvironmentStatus } = require('../api/environments.api');
-const { deployEnvironment: deployEnvironmentInfra } = require('../api/deployments.api');
+const { getPipelineDeployment } = require('../api/pipeline.api');
+const { deployEnvironment: deployEnvironmentInfra, getDeployment } = require('../api/deployments.api');
 const { handleDeploymentErrors } = require('../utils/deployment-errors');
+const { formatValidationErrors } = require('../utils/error-formatter');
 const auditLogger = require('../core/audit-logger');
+const environmentDeployRequestSchema = require('../schema/environment-deploy-request.schema.json');
 
 /**
  * Validates environment deployment prerequisites
@@ -78,25 +83,88 @@ async function getEnvironmentAuth(controllerUrl) {
  * @throws {Error} If deployment fails
  */
 /**
- * Builds environment deployment request
+ * Loads and validates environment deploy config from a JSON file
+ * @param {string} configPath - Absolute or relative path to config JSON
+ * @returns {Object} Valid deploy request { environmentConfig, dryRun? }
+ * @throws {Error} If file missing, invalid JSON, or validation fails
+ */
+function loadAndValidateEnvironmentDeployConfig(configPath) {
+  const resolvedPath = path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Environment config file not found: ${resolvedPath}\n` +
+      'Use --config <file> with a JSON file containing "environmentConfig" (e.g. templates/infra/environment-dev.json).'
+    );
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(resolvedPath, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read config file: ${resolvedPath}. ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `Invalid JSON in config file: ${resolvedPath}\n${e.message}\n` +
+      'Expected format: { "environmentConfig": { "key", "environment", "preset", "serviceName", "location" }, "dryRun": false }'
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(
+      `Config file must be a JSON object with "environmentConfig". File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" }, "dryRun": false }'
+    );
+  }
+  if (parsed.environmentConfig === undefined) {
+    throw new Error(
+      `Config file must contain "environmentConfig" (object). File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" } }'
+    );
+  }
+  if (typeof parsed.environmentConfig !== 'object' || parsed.environmentConfig === null) {
+    throw new Error(
+      `"environmentConfig" must be an object. File: ${resolvedPath}`
+    );
+  }
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(environmentDeployRequestSchema);
+  const valid = validate(parsed);
+  if (!valid) {
+    const messages = formatValidationErrors(validate.errors);
+    throw new Error(
+      `Environment config validation failed (${resolvedPath}):\n  • ${messages.join('\n  • ')}\n` +
+      'Fix the config file and run the command again. See templates/infra/environment-dev.json for a valid example.'
+    );
+  }
+  return {
+    environmentConfig: parsed.environmentConfig,
+    dryRun: Boolean(parsed.dryRun)
+  };
+}
+
+/**
+ * Builds environment deployment request from options (config file required)
  * @function buildEnvironmentDeploymentRequest
  * @param {string} validatedEnvKey - Validated environment key
- * @param {Object} options - Deployment options
- * @returns {Object} Deployment request object
+ * @param {Object} options - Deployment options (must include options.config)
+ * @returns {Object} Deployment request object for API
  */
 function buildEnvironmentDeploymentRequest(validatedEnvKey, options) {
-  const capitalized = validatedEnvKey.charAt(0).toUpperCase() + validatedEnvKey.slice(1);
-  const request = {
-    key: validatedEnvKey,
-    displayName: `${capitalized} Environment`,
-    description: `${capitalized} environment for application deployments`
-  };
-
-  if (options.config) {
-    request.description += ` (config: ${options.config})`;
+  if (!options.config || typeof options.config !== 'string') {
+    throw new Error(
+      'Environment deploy requires a config file with "environmentConfig". Use --config <file>.\n' +
+      'Example: aifabrix environment deploy dev --config templates/infra/environment-dev.json'
+    );
   }
-
-  return request;
+  const deployRequest = loadAndValidateEnvironmentDeployConfig(options.config);
+  if (deployRequest.environmentConfig.key && deployRequest.environmentConfig.key !== validatedEnvKey) {
+    logger.log(chalk.yellow(
+      `⚠ Config key "${deployRequest.environmentConfig.key}" does not match deploy target "${validatedEnvKey}"; using target "${validatedEnvKey}".`
+    ));
+  }
+  return deployRequest;
 }
 
 /**
@@ -155,22 +223,47 @@ async function sendEnvironmentDeployment(controllerUrl, envKey, authConfig, opti
 }
 
 /**
- * Process environment status response
- * @param {Object} response - API response
+ * Fetches deployment status by ID (pipeline endpoint first, then environments)
+ * Mirrors miso-controller manual test: GET pipeline/deployments/:id then GET environments/deployments/:id
+ * @async
+ * @param {string} controllerUrl - Controller URL
+ * @param {string} envKey - Environment key
+ * @param {string} deploymentId - Deployment ID
+ * @param {Object} apiAuthConfig - Auth config { type: 'bearer', token }
+ * @returns {Promise<Object|null>} Deployment record (status, progress, etc.) or null
+ */
+async function getDeploymentStatusById(controllerUrl, envKey, deploymentId, apiAuthConfig) {
+  try {
+    const pipelineRes = await getPipelineDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    if (pipelineRes?.data?.data) return pipelineRes.data.data;
+    if (pipelineRes?.data && typeof pipelineRes.data === 'object' && pipelineRes.data.status) return pipelineRes.data;
+  } catch {
+    // Fallback to environments endpoint
+  }
+  try {
+    const envRes = await getDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    if (envRes?.data?.data) return envRes.data.data;
+    if (envRes?.data && typeof envRes.data === 'object' && envRes.data.status) return envRes.data;
+  } catch {
+    // Ignore
+  }
+  return null;
+}
+
+/**
+ * Process deployment record from GET .../deployments/:deploymentId
+ * @param {Object|null} deployment - Deployment record (status, progress, message, error)
  * @param {string} validatedEnvKey - Validated environment key
- * @returns {Object|null} Status result if ready, null if needs to continue polling
+ * @returns {Object|null} Status result if completed, null if still in progress
  * @throws {Error} If deployment failed
  */
-function processEnvironmentStatusResponse(response, validatedEnvKey) {
-  if (!response.success || !response.data) {
+function processDeploymentStatusResponse(deployment, validatedEnvKey) {
+  if (!deployment || typeof deployment !== 'object') {
     return null;
   }
 
-  const responseData = response.data.data || response.data;
-  const status = responseData.status || responseData.ready;
-  const isReady = status === 'ready' || status === 'completed' || responseData.ready === true;
-
-  if (isReady) {
+  const status = deployment.status;
+  if (status === 'completed') {
     return {
       success: true,
       environment: validatedEnvKey,
@@ -179,9 +272,9 @@ function processEnvironmentStatusResponse(response, validatedEnvKey) {
     };
   }
 
-  // Check for terminal failure states
   if (status === 'failed' || status === 'error') {
-    throw new Error(`Environment deployment failed: ${responseData.message || 'Unknown error'}`);
+    const msg = deployment.message || deployment.error || 'Unknown error';
+    throw new Error(`Environment deployment failed: ${msg}`);
   }
 
   return null;
@@ -213,8 +306,18 @@ async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authCo
     try {
       await new Promise(resolve => setTimeout(resolve, pollInterval));
 
-      const response = await getEnvironmentStatus(validatedUrl, validatedEnvKey, apiAuthConfig);
-      const statusResult = processEnvironmentStatusResponse(response, validatedEnvKey);
+      const deployment = await getDeploymentStatusById(
+        validatedUrl,
+        validatedEnvKey,
+        deploymentId,
+        apiAuthConfig
+      );
+      const progress = deployment?.progress ?? 0;
+      const statusLabel = deployment?.status ?? 'pending';
+      if (attempt <= maxAttempts) {
+        logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}... Status: ${statusLabel} (${progress}%)`));
+      }
+      const statusResult = processDeploymentStatusResponse(deployment, validatedEnvKey);
       if (statusResult) {
         return statusResult;
       }
@@ -225,10 +328,6 @@ async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authCo
       }
       // Otherwise, continue polling
     }
-
-    if (attempt < maxAttempts) {
-      logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}...`));
-    }
   }
 
   // Timeout

package/lib/external-system/deploy.js

@@ -97,7 +97,11 @@ async function deployExternalSystem(appName, options = {}) {
 
     return result;
   } catch (error) {
-    throw new Error(`Failed to deploy external system: ${error.message}`);
+    let message = `Failed to deploy external system: ${error.message}`;
+    if (error.message && error.message.includes('Application not found')) {
+      message += `\n\n💡 Register the app in the controller first: aifabrix app register ${appName}`;
+    }
+    throw new Error(message);
   }
 }
 

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

@@ -1,7 +1,9 @@
 /**
  * External System Test Authentication Helpers
  *
- * Authentication setup for integration tests
+ * Authentication setup for integration tests. Uses the dataplane service URL
+ * (discovered from the controller), not the external system app's config—external
+ * apps do not store a dataplane URL.
  *
  * @fileoverview Authentication helpers for external system testing
  * @author AI Fabrix Team
@@ -9,19 +11,19 @@
  */
 
 const { getDeploymentAuth } = require('../utils/token-manager');
-const { getDataplaneUrl } = require('../datasource/deploy');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
 const { resolveControllerUrl } = require('../utils/controller-url');
 
 /**
  * Setup authentication and get dataplane URL for integration tests
  * @async
- * @param {string} appName - Application name
- * @param {Object} options - Test options
- * @param {Object} config - Configuration object
+ * @param {string} appName - Application name (used for auth scope; dataplane URL is discovered from controller)
+ * @param {Object} options - Test options; options.dataplane overrides discovered URL
+ * @param {Object} _config - Configuration object
  * @returns {Promise<Object>} Object with authConfig and dataplaneUrl
  * @throws {Error} If authentication fails
  */
-async function setupIntegrationTestAuth(appName, _options, _config) {
+async function setupIntegrationTestAuth(appName, options, _config) {
   const { resolveEnvironment } = require('../core/config');
   const environment = await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
@@ -31,7 +33,12 @@ async function setupIntegrationTestAuth(appName, _options, _config) {
     throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register" first.');
   }
 
-  const dataplaneUrl = await getDataplaneUrl(controllerUrl, appName, environment, authConfig);
+  let dataplaneUrl;
+  if (options && options.dataplane && typeof options.dataplane === 'string' && options.dataplane.trim()) {
+    dataplaneUrl = options.dataplane.trim();
+  } else {
+    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+  }
 
   return { authConfig, dataplaneUrl };
 }

package/lib/generator/wizard.js

@@ -12,6 +12,19 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { generateExternalReadmeContent } = require('../utils/external-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';
+}
+
 /**
  * Generate files from dataplane-generated wizard configurations
  * @async
@@ -53,11 +66,12 @@ async function writeDatasourceJsonFiles(appPath, finalSystemKey, datasourceConfi
   const datasourceFileNames = [];
   for (const datasourceConfig of datasourceConfigs) {
     const entityType = datasourceConfig.entityType || datasourceConfig.entityKey || datasourceConfig.key?.split('-').pop() || 'default';
-    const datasourceKey = datasourceConfig.key || `${finalSystemKey}-${entityType}`;
-    // Extract datasource key (remove system key prefix if present)
+    const keySegment = toKeySegment(entityType);
+    const datasourceKey = datasourceConfig.key || `${finalSystemKey}-${keySegment}`;
+    // Extract datasource key (remove system key prefix if present); use normalized segment for filename
     const datasourceKeyOnly = datasourceKey.includes('-') && datasourceKey.startsWith(`${finalSystemKey}-`)
       ? datasourceKey.substring(finalSystemKey.length + 1)
-      : entityType;
+      : keySegment;
     const datasourceFileName = `${finalSystemKey}-datasource-${datasourceKeyOnly}.json`;
     const datasourceFilePath = path.join(appPath, datasourceFileName);
     await fs.writeFile(datasourceFilePath, JSON.stringify(datasourceConfig, null, 2), 'utf8');
@@ -143,13 +157,14 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
       displayName: appDisplayName
     };
 
-    // Update datasource configs to use appName-based keys and systemKey
+    // Update datasource configs to use appName-based keys and systemKey (key must match ^[a-z0-9-]+$)
     const updatedDatasourceConfigs = datasourceConfigs.map(ds => {
       const entityType = ds.entityType || ds.entityKey || ds.key?.split('-').pop() || 'default';
+      const keySegment = toKeySegment(entityType);
       const entityDisplayName = entityType.charAt(0).toUpperCase() + entityType.slice(1).replace(/-/g, ' ');
       return {
         ...ds,
-        key: `${finalSystemKey}-${entityType}`,
+        key: `${finalSystemKey}-${keySegment}`,
         systemKey: finalSystemKey,
         displayName: `${appDisplayName} ${entityDisplayName}`
       };
@@ -360,23 +375,22 @@ async function generateEnvTemplate(appPath, systemConfig) {
 }
 
 /**
- * Generate deployment scripts (deploy.sh, deploy.ps1, deploy.js) from templates
+ * Generate deployment script (deploy.js) from template
  * @async
  * @function generateDeployScripts
  * @param {string} appPath - Application directory path
  * @param {string} systemKey - System key
  * @param {string} systemFileName - System file name
  * @param {string[]} datasourceFileNames - Array of datasource file names
- * @returns {Promise<Object>} Object with deployShPath, deployPs1Path, deployJsPath
+ * @returns {Promise<Object>} Object with deployJsPath
  * @throws {Error} If generation fails
  */
 const templatesExternalDir = path.join(__dirname, '..', '..', 'templates', 'external-system');
 
-async function writeDeployScriptFromTemplate(templateName, outputPath, context, executable) {
+async function writeDeployScriptFromTemplate(templateName, outputPath, context) {
   const templatePath = path.join(templatesExternalDir, templateName);
   const content = Handlebars.compile(await fs.readFile(templatePath, 'utf8'))(context);
   await fs.writeFile(outputPath, content, 'utf8');
-  if (executable) await fs.chmod(outputPath, 0o755);
   logger.log(chalk.green(`✓ Generated ${path.basename(outputPath)}`));
 }
 
@@ -385,13 +399,9 @@ async function generateDeployScripts(appPath, systemKey, systemFileName, datasou
     const allJsonFiles = [systemFileName, ...datasourceFileNames];
     const context = { systemKey, allJsonFiles, datasourceFileNames };
 
-    await writeDeployScriptFromTemplate('deploy.sh.hbs', path.join(appPath, 'deploy.sh'), context, true);
-    await writeDeployScriptFromTemplate('deploy.ps1.hbs', path.join(appPath, 'deploy.ps1'), context, false);
-    await writeDeployScriptFromTemplate('deploy.js.hbs', path.join(appPath, 'deploy.js'), context, false);
+    await writeDeployScriptFromTemplate('deploy.js.hbs', path.join(appPath, 'deploy.js'), context);
 
     return {
-      deployShPath: path.join(appPath, 'deploy.sh'),
-      deployPs1Path: path.join(appPath, 'deploy.ps1'),
       deployJsPath: path.join(appPath, 'deploy.js')
     };
   } catch (error) {
@@ -424,10 +434,11 @@ async function generateReadme(appPath, appName, systemKey, systemConfig, datasou
 
     const datasources = (Array.isArray(datasourceConfigs) ? datasourceConfigs : []).map((ds, index) => {
       const entityType = ds.entityType || ds.entityKey || ds.key?.split('-').pop() || `datasource${index + 1}`;
-      const datasourceKey = ds.key || `${systemKey}-${entityType}`;
+      const keySegment = toKeySegment(entityType);
+      const datasourceKey = ds.key || `${systemKey}-${keySegment}`;
       const datasourceKeyOnly = datasourceKey.includes('-') && datasourceKey.startsWith(`${systemKey}-`)
         ? datasourceKey.substring(systemKey.length + 1)
-        : entityType;
+        : keySegment;
       return {
         entityType,
         displayName: ds.displayName || ds.name || ds.key || `Datasource ${index + 1}`,