@aifabrix/builder 2.40.2 → 2.42.0

package/lib/utils/docker-build.js

@@ -95,9 +95,19 @@ function handleDockerClose(code, ctx) {
 }
 
 function runDockerBuildProcess(buildOpts) {
-  const { imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject } = buildOpts;
-  const dockerProcess = spawn('docker', ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath, contextPath], {
-    shell: process.platform === 'win32'
+  const { imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject, env = {}, buildArgs = {} } = buildOpts;
+  const spawnEnv = { ...process.env, ...env };
+  const args = ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath];
+  // Pass NPM_TOKEN/PYPI_TOKEN etc. so private registry auth works during RUN npm install / pip install
+  for (const [key, value] of Object.entries(buildArgs)) {
+    if (value !== null && value !== undefined && String(value).length > 0) {
+      args.push('--build-arg', `${key}=${String(value)}`);
+    }
+  }
+  args.push(contextPath);
+  const dockerProcess = spawn('docker', args, {
+    shell: process.platform === 'win32',
+    env: spawnEnv
   });
   let stdoutBuffer = '';
   let stderrBuffer = '';
@@ -138,13 +148,15 @@ function runDockerBuildProcess(buildOpts) {
  * @param {string} dockerfilePath - Path to Dockerfile
  * @param {string} contextPath - Build context path
  * @param {string} tag - Image tag
+ * @param {Object} [buildArgs={}] - Optional build args (e.g. NPM_TOKEN, PYPI_TOKEN) for private registries
  * @returns {Promise<void>} Resolves when build completes
  * @throws {Error} If build fails
  */
-async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
+async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}) {
   const spinner = ora({ text: 'Starting Docker build...', spinner: 'dots' }).start();
   const fsSync = require('fs');
   const path = require('path');
+  const { getRemoteDockerEnv } = require('./remote-docker-env');
   dockerfilePath = path.resolve(dockerfilePath);
   contextPath = path.resolve(contextPath);
 
@@ -162,8 +174,21 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
     }
   }
 
+  const isTest = process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined;
+  const remoteEnv = isTest ? {} : await getRemoteDockerEnv();
+  const resolvedBuildArgs = buildArgs && typeof buildArgs === 'object' ? buildArgs : {};
   return new Promise((resolve, reject) => {
-    runDockerBuildProcess({ imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject });
+    runDockerBuildProcess({
+      imageName,
+      tag,
+      dockerfilePath,
+      contextPath,
+      spinner,
+      resolve,
+      reject,
+      env: remoteEnv,
+      buildArgs: resolvedBuildArgs
+    });
   });
 }
 
@@ -179,14 +204,18 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
  * @throws {Error} If build fails
  */
 async function executeBuild(imageName, dockerfilePath, contextPath, tag, options) {
-  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag);
+  const buildArgs = (options && options.buildArgs) || {};
+  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs);
 
   // Tag image if additional tag provided
   if (options && options.tag && options.tag !== 'latest') {
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    await run(`docker tag ${imageName}:${tag} ${imageName}:latest`);
+    const { getRemoteDockerEnv } = require('./remote-docker-env');
+    const remoteEnv = await getRemoteDockerEnv();
+    const env = { ...process.env, ...remoteEnv };
+    await run(`docker tag ${imageName}:${tag} ${imageName}:latest`, { env });
   }
 }
 
@@ -215,7 +244,10 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`);
+    const { getRemoteDockerEnv } = require('./remote-docker-env');
+    const remoteEnv = await getRemoteDockerEnv();
+    const env = { ...process.env, ...remoteEnv };
+    await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`, { env });
     logger.log(chalk.green(`✓ Tagged image: ${imageName}:${tag}`));
   } catch (err) {
     logger.log(chalk.yellow(`⚠️  Warning: Could not create compatibility tag ${imageName}:${tag} - ${err.message}`));

package/lib/utils/env-copy.js

@@ -9,6 +9,7 @@
 'use strict';
 
 const fs = require('fs');
+const fsp = require('fs').promises;
 const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
@@ -48,6 +49,22 @@ function readDeveloperIdFromConfig(config) {
   return null;
 }
 
+/**
+ * Substitute /mnt/data with local mount path for local .env and ensure mount dir exists on disk.
+ * Creates the mount folder on the local filesystem (next to the .env file) when it does not exist.
+ * @param {string} content - Env file content
+ * @param {string} outputPath - Resolved path of the .env file being written
+ * @returns {string} Content with /mnt/data replaced by path to mount directory
+ */
+function substituteMntDataForLocal(content, outputPath) {
+  const outputDir = path.dirname(outputPath);
+  const localMountPath = path.resolve(outputDir, 'mount');
+  if (!fs.existsSync(localMountPath)) {
+    fs.mkdirSync(localMountPath, { recursive: true });
+  }
+  return content.replace(/\/mnt\/data/g, localMountPath);
+}
+
 /**
  * Resolve output path for env file
  * @param {string} rawOutputPath - Raw output path from application config
@@ -72,6 +89,45 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
   return outputPath;
 }
 
+/**
+ * Writes .env to envOutputPath for reload path: merge run .env into existing file.
+ * @async
+ * @param {string} outputPath - Resolved output path
+ * @param {string} runEnvPath - Path to .env.run
+ */
+async function writeEnvOutputForReload(outputPath, runEnvPath) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const runContent = await fsp.readFile(runEnvPath, 'utf8');
+  const runMap = parseEnvContentToMap(runContent);
+  let toWrite = runContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = await fsp.readFile(outputPath, 'utf8');
+    toWrite = mergeEnvMapIntoContent(existingContent, runMap);
+  }
+  await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Wrote .env to envOutputPath (same as container, for --reload): ${outputPath}`));
+}
+
+/**
+ * Writes local .env to envOutputPath (no reload).
+ * @async
+ * @param {string} appName - Application name
+ * @param {string} outputPath - Resolved output path
+ */
+async function writeEnvOutputForLocal(appName, outputPath) {
+  const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  let localContent = await generateEnvContent(appName, null, 'local', false);
+  localContent = substituteMntDataForLocal(localContent, outputPath);
+  let toWrite = localContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = await fsp.readFile(outputPath, 'utf8');
+    const localMap = parseEnvContentToMap(localContent);
+    toWrite = mergeEnvMapIntoContent(existingContent, localMap);
+  }
+  await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Wrote .env to envOutputPath (localPort): ${outputPath}`));
+}
+
 /**
  * Calculate developer-specific app port
  * @param {number} baseAppPort - Base application port
@@ -180,6 +236,44 @@ async function patchEnvContentForLocal(envContent, variables) {
   return envContent;
 }
 
+/**
+ * Write regenerated local .env to output path (merge with existing if present).
+ * @async
+ * @param {string} outputPath - Resolved output path
+ * @param {string} appName - Application name
+ * @param {string} [secretsPath] - Path to secrets file (optional)
+ * @param {string} envOutputPathLabel - Label for log message (e.g. variables.build.envOutputPath)
+ */
+async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel) {
+  const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
+  localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
+  let toWrite = localEnvContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = fs.readFileSync(outputPath, 'utf8');
+    const localMap = parseEnvContentToMap(localEnvContent);
+    toWrite = mergeEnvMapIntoContent(existingContent, localMap);
+  }
+  fs.writeFileSync(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Generated local .env at: ${envOutputPathLabel}`));
+}
+
+/**
+ * Write patched .env to output path (fallback when appName not provided).
+ * @async
+ * @param {string} envPath - Path to generated .env file
+ * @param {string} outputPath - Resolved output path
+ * @param {Object} variables - Loaded variables config
+ * @param {string} envOutputPathLabel - Label for log message
+ */
+async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOutputPathLabel) {
+  const envContent = fs.readFileSync(envPath, 'utf8');
+  let patchedContent = await patchEnvContentForLocal(envContent, variables);
+  patchedContent = substituteMntDataForLocal(patchedContent, outputPath);
+  fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Copied .env to: ${envOutputPathLabel}`));
+}
+
 /**
  * Process and optionally copy env file to envOutputPath if configured
  * Regenerates .env file with env=local for local development (apps/.env)
@@ -191,7 +285,7 @@ async function patchEnvContentForLocal(envContent, variables) {
  * @param {string} [secretsPath] - Path to secrets file (optional, for regenerating)
  */
 async function processEnvVariables(envPath, variablesPath, appName, secretsPath) {
-  if (!fs.existsSync(variablesPath)) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) {
     return;
   }
   const variablesContent = fs.readFileSync(variablesPath, 'utf8');
@@ -200,29 +294,25 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
     return;
   }
 
-  // Resolve output path
   const outputPath = resolveEnvOutputPath(variables.build.envOutputPath, variablesPath);
   const outputDir = path.dirname(outputPath);
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
 
-  // Regenerate .env file with env=local instead of copying docker-generated file
+  const label = variables.build.envOutputPath;
   if (appName) {
-    const { generateEnvContent } = require('../core/secrets');
-    const localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
-    fs.writeFileSync(outputPath, localEnvContent, { mode: 0o600 });
-    logger.log(chalk.green(`✓ Generated local .env at: ${variables.build.envOutputPath}`));
+    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label);
   } else {
-    // Fallback: if appName not provided, use old patching approach
-    const envContent = fs.readFileSync(envPath, 'utf8');
-    const patchedContent = await patchEnvContentForLocal(envContent, variables);
-    fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
-    logger.log(chalk.green(`✓ Copied .env to: ${variables.build.envOutputPath}`));
+    await writePatchedEnvToOutputPath(envPath, outputPath, variables, label);
   }
 }
 
 module.exports = {
-  processEnvVariables
+  processEnvVariables,
+  resolveEnvOutputPath,
+  substituteMntDataForLocal,
+  writeEnvOutputForReload,
+  writeEnvOutputForLocal
 };
 

package/lib/utils/env-map.js

@@ -144,6 +144,27 @@ function handlePlainValue(result, key, rawVal, options) {
   result[key] = val;
 }
 
+/** Placeholder in env-config values; replaced with application or default port */
+const PORT_PLACEHOLDER = '${PORT}';
+
+/**
+ * Replaces ${PORT} in all string values of env object (in-place).
+ * Used so env-config.yaml docker/local values resolve correctly (e.g. PORT: ${PORT} -> application port).
+ *
+ * @param {Object} envObj - Flat key-value object (e.g. merged env-config environments.docker)
+ * @param {number} [portNumber=3000] - Port to substitute when value contains ${PORT}
+ */
+function resolvePortInEnvValues(envObj, portNumber = 3000) {
+  if (!envObj || typeof envObj !== 'object') return;
+  const portStr = String(portNumber);
+  for (const key of Object.keys(envObj)) {
+    const val = envObj[key];
+    if (typeof val === 'string' && val.includes(PORT_PLACEHOLDER)) {
+      envObj[key] = val.split(PORT_PLACEHOLDER).join(portStr);
+    }
+  }
+}
+
 /**
  * Normalize environment variable map by splitting host:port values
  * @function normalizeEnvVars
@@ -270,30 +291,38 @@ function calculateDockerPublicPorts(result, devIdNum, schemaBaseVars = {}) {
 /**
  * Build environment variable map for interpolation based on env-config.yaml
  * - Supports values like "host:port" by splitting into *_HOST (host) and *_PORT (port)
+ * - Resolves ${PORT} in env-config values using options.appPort or default 3000 (so docker/local values are correct)
  * - Merges overrides from ~/.aifabrix/config.yaml under environments.{env}
  * - Applies aifabrix-localhost override for local context if configured
  * - Applies developer-id adjustment to port variables for local context
- * - Calculates *_PUBLIC_PORT for docker context (basePort + developer-id * 100)
+ * - Calculates *_PUBLIC_PORT for both local and docker context (basePort + developer-id * 100)
  * @async
  * @function buildEnvVarMap
  * @param {'docker'|'local'} context - Environment context
  * @param {Object} [osModule] - Optional os module (for testing). If not provided, requires 'os'
  * @param {number|null} [developerId] - Optional developer ID for port adjustment. If not provided, will be fetched from config for local context.
+ * @param {Object} [options] - Optional options
+ * @param {number} [options.appPort] - Port to use when resolving ${PORT} in env-config values (e.g. from application.yaml)
  * @returns {Promise<Object>} Map of variables for interpolation
  */
-async function buildEnvVarMap(context, osModule = null, developerId = null) {
+async function buildEnvVarMap(context, osModule = null, developerId = null, options = null) {
   const baseVars = await loadBaseVars(context);
   const os = osModule || require('os');
   const overrideVars = loadOverrideVars(context, os);
   const localhostOverride = context === 'local' ? getLocalhostOverride(os) : null;
   const merged = { ...baseVars, ...overrideVars };
+  const appPort = (options && options.appPort !== undefined && options.appPort !== null && Number.isFinite(Number(options.appPort)))
+    ? Number(options.appPort) : 3000;
+  resolvePortInEnvValues(merged, appPort);
   const result = normalizeEnvVars(merged, context, localhostOverride);
 
+  const devIdNum = await getDeveloperIdNumber(developerId);
   if (context === 'local') {
-    const devIdNum = await getDeveloperIdNumber(developerId);
     applyLocalPortAdjustment(result, devIdNum);
+    const schemaCfg = loadSchemaEnvConfig();
+    const schemaBaseVars = (schemaCfg && schemaCfg.environments && schemaCfg.environments.local) ? schemaCfg.environments.local : {};
+    calculateDockerPublicPorts(result, devIdNum, schemaBaseVars);
   } else if (context === 'docker') {
-    const devIdNum = await getDeveloperIdNumber(developerId);
     const schemaCfg = loadSchemaEnvConfig();
     const schemaBaseVars = (schemaCfg && schemaCfg.environments && schemaCfg.environments[context]) ? schemaCfg.environments[context] : {};
     calculateDockerPublicPorts(result, devIdNum, schemaBaseVars);
@@ -304,6 +333,7 @@ async function buildEnvVarMap(context, osModule = null, developerId = null) {
 
 module.exports = {
   buildEnvVarMap,
-  getDeveloperIdNumber
+  getDeveloperIdNumber,
+  resolvePortInEnvValues
 };
 

package/lib/utils/env-template.js

@@ -15,7 +15,8 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 
 /**
- * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and MISO_CONTROLLER_URL entries
+ * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and optionally MISO_CONTROLLER_URL.
+ * When MISO_CONTROLLER_URL already exists, its value is left unchanged (e.g. http://${MISO_HOST}:${MISO_PORT}).
  * @async
  * @param {string} appKey - Application key
  * @param {string} clientIdKey - Secret key for client ID (e.g., 'myapp-client-idKeyVault')
@@ -39,7 +40,9 @@ function checkMisoEntries(content) {
 }
 
 /**
- * Updates existing MISO entries
+ * Updates existing MISO entries.
+ * MISO_CONTROLLER_URL is never overwritten when present so that template form
+ * (e.g. http://${MISO_HOST}:${MISO_PORT}) or custom URLs are preserved.
  * @function updateExistingMisoEntries
  * @param {string} content - File content
  * @param {string} clientIdKey - Client ID key
@@ -54,9 +57,7 @@ function updateExistingMisoEntries(content, clientIdKey, clientSecretKey, entrie
   if (entries.hasClientSecret) {
     content = content.replace(/^MISO_CLIENTSECRET\s*=.*$/m, `MISO_CLIENTSECRET=kv://${clientSecretKey}`);
   }
-  if (entries.hasControllerUrl) {
-    content = content.replace(/^MISO_CONTROLLER_URL\s*=.*$/m, 'MISO_CONTROLLER_URL=http://${MISO_HOST}:${MISO_PORT}');
-  }
+  // Do not change existing MISO_CONTROLLER_URL (preserve template or custom value)
   return content;
 }
 

package/lib/utils/error-formatters/http-status-errors.js

@@ -79,12 +79,31 @@ function addErrorMessageIfNotGeneric(lines, errorData) {
 }
 
 /**
- * Adds authentication guidance
+ * Returns true when the error is about Builder Server client certificate (not Controller token).
+ * @param {Object} errorData - Error data
+ * @returns {boolean}
+ */
+function isBuilderServerCertError(errorData) {
+  const msg = (errorData.message || errorData.error || errorData.detail || '').toLowerCase();
+  return msg.includes('client certificate') || msg.includes('issue-cert') || msg.includes('x-client-cert');
+}
+
+/**
+ * Adds authentication guidance (Controller token login). Skipped for Builder Server cert errors.
  * @function addAuthenticationGuidance
  * @param {string[]} lines - Error message lines
  * @param {Object} errorData - Error data
  */
 function addAuthenticationGuidance(lines, errorData) {
+  if (isBuilderServerCertError(errorData)) {
+    lines.push(chalk.gray('Use a certificate from: aifabrix dev init --developer-id <id> --server <url> --pin <pin>'));
+    if (errorData.correlationId) {
+      lines.push('');
+      lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
+    }
+    return;
+  }
+
   lines.push(chalk.gray('Your authentication token is invalid or has expired.'));
   lines.push('');
   lines.push(chalk.gray('To authenticate, run:'));
@@ -304,4 +323,3 @@ module.exports = {
   formatNotFoundError,
   formatGenericError
 };
-

package/lib/utils/error-formatters/permission-errors.js

@@ -134,4 +134,3 @@ module.exports = {
   extractMissingPermissions,
   extractRequiredPermissions
 };
-

package/lib/utils/error-formatters/validation-errors.js

@@ -130,4 +130,3 @@ function formatValidationError(errorData) {
 module.exports = {
   formatValidationError
 };
-

package/lib/utils/external-readme.js

@@ -30,42 +30,65 @@ function formatDisplayName(key) {
     .join(' ');
 }
 
+/**
+ * Derives suffix from datasource key for filename generation
+ * @param {string} key - Datasource key
+ * @param {string} systemKey - System key
+ * @param {string} entityType - Fallback entity type
+ * @returns {string} Suffix segment
+ */
+function getDatasourceKeySuffix(key, systemKey, entityType) {
+  if (key.startsWith(`${systemKey}-deploy-`)) {
+    return key.slice(`${systemKey}-deploy-`.length);
+  }
+  if (systemKey && key.startsWith(`${systemKey}-`)) {
+    return key.slice(systemKey.length + 1);
+  }
+  if (key) {
+    return key;
+  }
+  return entityType;
+}
+
+/**
+ * Normalizes a single datasource entry for template use
+ * @param {Object} datasource - Datasource object
+ * @param {number} index - Index in array
+ * @param {string} systemKey - System key for filename generation
+ * @param {string} ext - File extension (e.g. '.json', '.yaml')
+ * @returns {{entityType: string, displayName: string, fileName: string, datasourceKey: string}} Normalized entry
+ */
+function normalizeOneDatasource(datasource, index, systemKey, ext) {
+  const entityType = datasource.entityType ||
+    datasource.entityKey ||
+    datasource.key?.split('-').pop() ||
+    `entity${index + 1}`;
+  const displayName = datasource.displayName ||
+    datasource.name ||
+    `Datasource ${index + 1}`;
+  const key = datasource.key || '';
+  const suffix = getDatasourceKeySuffix(key, systemKey, entityType);
+  const datasourceKey = key || (systemKey ? `${systemKey}-${suffix}` : suffix);
+  const fileName = datasource.fileName || datasource.file ||
+    (systemKey ? `${systemKey}-datasource-${suffix}${ext}` : `${suffix}${ext}`);
+  return { entityType, displayName, fileName, datasourceKey };
+}
+
 /**
  * Normalizes datasource entries for template use
  * @param {Array} datasources - Datasource objects
  * @param {string} systemKey - System key for filename generation
- * @returns {Array<{entityType: string, displayName: string, fileName: string}>} Normalized entries
+ * @param {string} [fileExt='.json'] - File extension for generated filenames (e.g. '.json', '.yaml')
+ * @returns {Array<{entityType: string, displayName: string, fileName: string, datasourceKey: string}>} Normalized entries
  */
-function normalizeDatasources(datasources, systemKey) {
+function normalizeDatasources(datasources, systemKey, fileExt = '.json') {
   if (!Array.isArray(datasources)) {
     return [];
   }
-  return datasources.map((datasource, index) => {
-    const entityType = datasource.entityType ||
-      datasource.entityKey ||
-      datasource.key?.split('-').pop() ||
-      `entity${index + 1}`;
-    const displayName = datasource.displayName ||
-      datasource.name ||
-      `Datasource ${index + 1}`;
-    let fileName = datasource.fileName || datasource.file;
-    if (!fileName) {
-      const key = datasource.key || '';
-      // Suffix matches split getExternalDatasourceFileName for consistent README and file names
-      let suffix;
-      if (key.startsWith(`${systemKey}-deploy-`)) {
-        suffix = key.slice(`${systemKey}-deploy-`.length);
-      } else if (systemKey && key.startsWith(`${systemKey}-`)) {
-        suffix = key.slice(systemKey.length + 1);
-      } else if (key) {
-        suffix = key;
-      } else {
-        suffix = entityType;
-      }
-      fileName = systemKey ? `${systemKey}-datasource-${suffix}.yaml` : `${suffix}.yaml`;
-    }
-    return { entityType, displayName, fileName };
-  });
+  const ext = fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`;
+  return datasources.map((datasource, index) =>
+    normalizeOneDatasource(datasource, index, systemKey, ext)
+  );
 }
 
 /**
@@ -78,6 +101,7 @@ function normalizeDatasources(datasources, systemKey) {
  * @param {string} [params.displayName] - Display name
  * @param {string} [params.description] - Description
  * @param {Array} [params.datasources] - Datasource objects
+ * @param {string} [params.fileExt] - File extension for config files (e.g. '.json', '.yaml'); default '.json'
  * @returns {Object} Template context
  */
 function buildExternalReadmeContext(params = {}) {
@@ -86,7 +110,8 @@ function buildExternalReadmeContext(params = {}) {
   const displayName = params.displayName || formatDisplayName(systemKey);
   const description = params.description || `External system integration for ${systemKey}`;
   const systemType = params.systemType || 'openapi';
-  const datasources = normalizeDatasources(params.datasources, systemKey);
+  const fileExt = params.fileExt !== undefined ? params.fileExt : '.json';
+  const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
 
   return {
     appName,
@@ -94,7 +119,9 @@ function buildExternalReadmeContext(params = {}) {
     displayName,
     description,
     systemType,
+    fileExt: fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`,
     datasourceCount: datasources.length,
+    hasDatasources: datasources.length > 0,
     datasources
   };
 }

package/lib/utils/external-system-display.js

@@ -241,8 +241,66 @@ function displayIntegrationTestResults(results, verbose = false) {
   }
 }
 
+/**
+ * Displays E2E test results (steps: config, credential, sync, data, cip).
+ * Supports sync response (data.steps only), final poll (data.steps + data.success), and running poll
+ * (data.completedActions, no data.steps yet). When status is present (async flow), shows it.
+ *
+ * @param {Object} data - E2E response or poll data
+ * @param {string} [data.status] - Optional status: 'running' | 'completed' | 'failed' (async flow)
+ * @param {Object[]} [data.steps] - Per-step results (final state)
+ * @param {Object[]} [data.completedActions] - Steps completed so far (running state when steps absent)
+ * @param {boolean} [data.success] - Overall success (final state)
+ * @param {string} [data.error] - Error message when failed
+ * @param {boolean} [verbose] - Show detailed output
+ */
+/* eslint-disable max-statements,complexity -- Step iteration and status display */
+function displayE2EResults(data, verbose = false) {
+  logger.log(chalk.blue('\n📊 E2E Test Results\n'));
+  if (data.status) {
+    const statusLabel = data.status === 'running'
+      ? chalk.yellow('running')
+      : data.status === 'completed'
+        ? chalk.green('completed')
+        : data.status === 'failed'
+          ? chalk.red('failed')
+          : data.status;
+    logger.log(`Status: ${statusLabel}`);
+  }
+  const steps = data.steps || data.completedActions || [];
+  if (steps.length === 0) {
+    if (data.success === false) {
+      logger.log(chalk.red('✗ E2E test failed'));
+      if (data.error) logger.log(chalk.red(`  Error: ${data.error}`));
+    } else if (data.status === 'running') {
+      logger.log(chalk.gray('  No steps completed yet'));
+    } else {
+      logger.log(chalk.yellow('No step results returned'));
+    }
+    return;
+  }
+  const isRunning = data.status === 'running' && !data.steps;
+  if (isRunning && verbose) {
+    logger.log(chalk.gray(`  (${steps.length} step(s) completed so far)`));
+  }
+  for (const step of steps) {
+    const name = step.name || step.step || 'unknown';
+    const ok = step.success !== false && !step.error;
+    logger.log(`  ${ok ? chalk.green('✓') : chalk.red('✗')} ${name}`);
+    if (!ok && (step.error || step.message)) logger.log(chalk.red(`    ${step.error || step.message}`));
+    if (verbose && step.message && ok) logger.log(chalk.gray(`    ${step.message}`));
+  }
+  if (isRunning) {
+    return;
+  }
+  const allPassed = steps.every(s => s.success !== false && !s.error);
+  logger.log(allPassed ? chalk.green('\n✅ E2E test passed!') : chalk.red('\n❌ E2E test failed'));
+}
+
 module.exports = {
   displayTestResults,
-  displayIntegrationTestResults
+  displayIntegrationTestResults,
+  displayE2EResults,
+  displayDatasourceIntegrationResult
 };