@aifabrix/builder 2.39.3 → 2.40.2

package/lib/generator/builders.js

@@ -290,7 +290,7 @@ function addHealthCheckToDeployment(deployment, variables) {
  * @param {Object|null} rbac - RBAC configuration
  */
 function addRolesAndPermissions(deployment, variables, rbac) {
-  // Priority: variables.yaml > rbac.yaml
+  // Priority: application.yaml > rbac.yaml
   if (variables.roles) {
     deployment.roles = variables.roles;
   } else if (rbac && rbac.roles) {

package/lib/generator/external-controller-manifest.js

@@ -11,6 +11,7 @@
 
 const path = require('path');
 const { detectAppType } = require('../utils/paths');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadSystemFile, loadDatasourceFiles } = require('./external');
 const { loadVariables, loadRbac } = require('./helpers');
 
@@ -42,18 +43,18 @@ function mergeRbacIntoSystemJson(systemJson, rbac) {
  * @param {Object} options - Options with optional appPath
  * @returns {Promise<string>} Application path
  */
-async function resolveAppPath(appName, options) {
-  if (options.appPath) {
+async function resolveAppPath(appName, options = {}) {
+  if (options && options.appPath) {
     return options.appPath;
   }
-  const detected = await detectAppType(appName, { type: 'external' });
+  const detected = await detectAppType(appName);
   return detected.appPath;
 }
 
 /**
  * Extracts app metadata from variables
  * @function extractAppMetadata
- * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} variables - Parsed application config
  * @param {string} appName - Application name
  * @returns {Object} App metadata { appKey, displayName, description }
  */
@@ -98,59 +99,55 @@ async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
  * const manifest = await generateControllerManifest('my-hubspot');
  * // Returns: { key, displayName, description, type: "external", system: {...}, dataSources: [...] }
  */
+function normalizeSchemaBasePath(schemaBasePath, appPath, appName) {
+  const base = path.normalize(schemaBasePath || './').replace(/[/\\]+$/, '');
+  return base === path.join('integration', appName) ? './' : (schemaBasePath || './');
+}
+
 async function generateControllerManifest(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-
   const appPath = await resolveAppPath(appName, options);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
-
+  const { parsed: variables } = loadVariables(resolveApplicationConfigPath(appPath));
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
-
   const metadata = extractAppMetadata(variables, appName);
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  const schemaBasePath = normalizeSchemaBasePath(
+    variables.externalIntegration.schemaBasePath,
+    appPath,
+    appName
+  );
   const systemFiles = variables.externalIntegration.systems || [];
-
   if (systemFiles.length === 0) {
     throw new Error('No system files specified in externalIntegration.systems');
   }
-
-  const systemJson = await loadSystemWithRbac(appPath, schemaBasePath, systemFiles[0]);
-  const datasourceFiles = variables.externalIntegration.dataSources || [];
-  const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
-
+  const [systemJson, datasourceJsons] = await Promise.all([
+    loadSystemWithRbac(appPath, schemaBasePath, systemFiles[0]),
+    loadDatasourceFiles(appPath, schemaBasePath, variables.externalIntegration.dataSources || [])
+  ]);
   const appVersion = variables.app?.version || variables.externalIntegration?.version || '1.0.0';
-
-  // Build externalIntegration block (required by application schema for type: "external")
   const externalIntegration = {
-    schemaBasePath: schemaBasePath,
+    schemaBasePath,
     systems: systemFiles,
-    dataSources: datasourceFiles,
-    autopublish: variables.externalIntegration.autopublish !== false, // default true
+    dataSources: variables.externalIntegration.dataSources || [],
+    autopublish: variables.externalIntegration.autopublish !== false,
     version: appVersion
   };
-
-  const manifest = {
+  return {
     key: metadata.appKey,
     displayName: metadata.displayName,
     description: metadata.description,
     type: 'external',
     version: appVersion,
-    externalIntegration: externalIntegration,
-    // Inline system and dataSources for atomic deployment (optional but recommended)
+    externalIntegration,
     system: systemJson,
     dataSources: datasourceJsons,
-    // Explicitly set to false to satisfy conditional schema requirements
     requiresDatabase: false,
     requiresRedis: false,
     requiresStorage: false
   };
-
-  return manifest;
 }
 
 module.exports = {

package/lib/generator/external-schema-utils.js

@@ -56,18 +56,6 @@ function getSystemKey(application) {
   return systemKey;
 }
 
-/**
- * Writes JSON file with formatting
- * @async
- * @function writeJsonFile
- * @param {string} filePath - File path
- * @param {Object} data - JSON data
- * @returns {Promise<void>} Resolves when file is written
- */
-async function writeJsonFile(filePath, data) {
-  await fs.promises.writeFile(filePath, JSON.stringify(data, null, 2), 'utf8');
-}
-
 /**
  * Resolves datasource entity type
  * @function getDatasourceEntityType
@@ -104,7 +92,7 @@ function getDatasourceFileName(systemKey, datasource, index) {
   } else {
     datasourceKeyOnly = getDatasourceEntityType(datasource, index);
   }
-  return `${systemKey}-datasource-${datasourceKeyOnly}.json`;
+  return `${systemKey}-datasource-${datasourceKeyOnly}.yaml`;
 }
 
 /**
@@ -122,14 +110,14 @@ async function writeDatasourceFiles(outputDir, systemKey, dataSources) {
     const datasource = dataSources[i];
     const datasourceFileName = getDatasourceFileName(systemKey, datasource, i);
     const datasourceFilePath = path.join(outputDir, datasourceFileName);
-    await writeJsonFile(datasourceFilePath, datasource);
+    await writeYamlFile(datasourceFilePath, datasource, { indent: 2, lineWidth: 120, noRefs: true });
     datasourceFileNames.push(datasourceFileName);
   }
   return datasourceFileNames;
 }
 
 /**
- * Builds variables.yaml content for external integrations
+ * Builds application config content for external integrations
  * @function buildExternalVariables
  * @param {string} systemKey - System key
  * @param {Object} application - Application schema
@@ -187,14 +175,14 @@ async function writeYamlFile(filePath, data, options) {
  * @returns {Promise<Object>} Paths to generated files
  */
 async function writeSplitExternalSchemaFiles({ outputDir, systemKey, application, dataSources, version }) {
-  const systemFileName = `${systemKey}-system.json`;
+  const systemFileName = `${systemKey}-system.yaml`;
   const systemFilePath = path.join(outputDir, systemFileName);
-  await writeJsonFile(systemFilePath, application);
+  await writeYamlFile(systemFilePath, application, { indent: 2, lineWidth: 120, noRefs: true });
 
   const datasourceFileNames = await writeDatasourceFiles(outputDir, systemKey, dataSources);
   const variables = buildExternalVariables(systemKey, application, systemFileName, datasourceFileNames, version);
 
-  const variablesPath = path.join(outputDir, 'variables.yaml');
+  const variablesPath = path.join(outputDir, 'application.yaml');
   await writeYamlFile(variablesPath, variables, { indent: 2, lineWidth: 120, noRefs: true });
 
   const envTemplatePath = path.join(outputDir, 'env.template');

package/lib/generator/external.js

@@ -12,6 +12,8 @@ const fs = require('fs');
 const path = require('path');
 const Ajv = require('ajv');
 const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { loadConfigFile } = require('../utils/config-format');
 const { loadVariables, loadRbac } = require('./helpers');
 const {
   parseApplicationSchema,
@@ -41,26 +43,29 @@ const {
 function resolveSystemFilePath(variables, appPath, appName) {
   const systemFileName = variables.externalIntegration.systems && variables.externalIntegration.systems.length > 0
     ? variables.externalIntegration.systems[0]
-    : `${appName}-system.json`;
+    : `${appName}-system.yaml`;
 
-  const schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  let schemaBasePath = variables.externalIntegration.schemaBasePath || './';
+  const normalizedBase = path.normalize(schemaBasePath).replace(/[/\\]+$/, '');
+  if (normalizedBase === path.join('integration', appName)) {
+    schemaBasePath = './';
+  }
   const systemFilePath = path.isAbsolute(schemaBasePath)
     ? path.join(schemaBasePath, systemFileName)
     : path.join(appPath, schemaBasePath, systemFileName);
 
-  // Support both old and new naming for backward compatibility
+  // Support both .yaml and legacy .json for backward compatibility
   if (!fs.existsSync(systemFilePath)) {
-    // Try old naming format
-    const oldSystemFileName = systemFileName.replace(/-system\.json$/, '-deploy.json');
-    const oldSystemFilePath = path.isAbsolute(schemaBasePath)
-      ? path.join(schemaBasePath, oldSystemFileName)
-      : path.join(appPath, schemaBasePath, oldSystemFileName);
-
-    if (fs.existsSync(oldSystemFilePath)) {
-      return oldSystemFilePath;
+    const altFileName = systemFileName.replace(/-system\.yaml$/, '-system.json').replace(/-system\.yml$/, '-system.json');
+    const altSystemFilePath = path.isAbsolute(schemaBasePath)
+      ? path.join(schemaBasePath, altFileName)
+      : path.join(appPath, schemaBasePath, altFileName);
+
+    if (fs.existsSync(altSystemFilePath)) {
+      return altSystemFilePath;
     }
 
-    throw new Error(`External system file not found: ${systemFilePath} (also checked: ${oldSystemFilePath}). Please create it first.`);
+    throw new Error(`External system file not found: ${systemFilePath} (also checked: ${altSystemFilePath}). Please create it first.`);
   }
 
   return systemFilePath;
@@ -87,15 +92,14 @@ function mergeRbacIntoSystemJson(systemJson, rbac) {
 }
 
 /**
- * Loads and parses system file
+ * Loads and parses system file (YAML or JSON)
  * @async
  * @function loadSystemFileContent
  * @param {string} systemFilePath - System file path
- * @returns {Promise<Object>} Parsed system JSON
+ * @returns {Promise<Object>} Parsed system config object
  */
 async function loadSystemFileContent(systemFilePath) {
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  return JSON.parse(systemContent);
+  return loadConfigFile(systemFilePath);
 }
 
 async function generateExternalSystemDeployJson(appName, appPath) {
@@ -103,11 +107,11 @@ async function generateExternalSystemDeployJson(appName, appPath) {
     throw new Error('App name is required and must be a string');
   }
 
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
+  const configPath = resolveApplicationConfigPath(appPath);
+  const { parsed: variables } = loadVariables(configPath);
 
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
 
   const systemFilePath = resolveSystemFilePath(variables, appPath, appName);
@@ -141,11 +145,13 @@ async function loadSystemFile(appPath, schemaBasePath, systemFileName) {
     : path.join(appPath, schemaBasePath, systemFileName);
 
   if (!fs.existsSync(systemFilePath)) {
-    throw new Error(`System file not found: ${systemFilePath}`);
+    const hint = systemFileName.endsWith('-deploy.json')
+      ? ' Use the system definition file (e.g. <app>-system.yaml) in externalIntegration.systems, not the deploy manifest (-deploy.json).'
+      : '';
+    throw new Error(`System file not found: ${systemFilePath}.${hint}`);
   }
 
-  const systemContent = await fs.promises.readFile(systemFilePath, 'utf8');
-  const systemJson = JSON.parse(systemContent);
+  const systemJson = loadConfigFile(systemFilePath);
 
   // Load rbac.yaml from app directory and merge if present
   const rbacPath = path.join(appPath, 'rbac.yaml');
@@ -183,8 +189,7 @@ async function loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles) {
       throw new Error(`Datasource file not found: ${datasourcePath}`);
     }
 
-    const datasourceContent = await fs.promises.readFile(datasourcePath, 'utf8');
-    const datasourceJson = JSON.parse(datasourceContent);
+    const datasourceJson = loadConfigFile(datasourcePath);
     datasourceJsons.push(datasourceJson);
   }
 
@@ -297,11 +302,11 @@ function validateDatasourceSchemas(datasourceJsons, externalDatasourceSchema, aj
  * @throws {Error} If configuration is invalid
  */
 async function loadExternalIntegrationConfig(appPath) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const { parsed: variables } = loadVariables(variablesPath);
+  const configPath = resolveApplicationConfigPath(appPath);
+  const { parsed: variables } = loadVariables(configPath);
 
   if (!variables.externalIntegration) {
-    throw new Error('externalIntegration block not found in variables.yaml');
+    throw new Error('externalIntegration block not found in application.yaml');
   }
 
   const schemaBasePath = variables.externalIntegration.schemaBasePath || './';

package/lib/generator/github.js

@@ -45,7 +45,7 @@ async function loadStepTemplates(stepNames = []) {
 /**
  * Generate GitHub Actions workflow files from templates
  * @param {string} appPath - Path to application directory
- * @param {Object} config - Configuration from variables.yaml
+ * @param {Object} config - Configuration from application.yaml
  * @param {Object} options - Generation options
  * @returns {Promise<string[]>} Array of generated file paths
  */

package/lib/generator/helpers.js

@@ -10,24 +10,17 @@
 
 const fs = require('fs');
 const yaml = require('js-yaml');
+const { loadConfigFile } = require('../utils/config-format');
 
 /**
- * Loads variables.yaml file
- * @param {string} variablesPath - Path to variables.yaml
- * @returns {Object} Parsed variables
- * @throws {Error} If file not found or invalid YAML
+ * Loads application config file (application.yaml, application.json, or legacy path) via converter.
+ * @param {string} configPath - Path to application config file
+ * @returns {Object} Object with parsed config: { parsed }
+ * @throws {Error} If file not found or invalid YAML/JSON
  */
-function loadVariables(variablesPath) {
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const variablesContent = fs.readFileSync(variablesPath, 'utf8');
-  try {
-    return { content: variablesContent, parsed: yaml.load(variablesContent) };
-  } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
-  }
+function loadVariables(configPath) {
+  const parsed = loadConfigFile(configPath);
+  return { parsed };
 }
 
 /**
@@ -151,16 +144,16 @@ function validatePortalInput(portalInput, variableName) {
 }
 
 /**
- * Parses environment variables from env.template and merges portalInput from variables.yaml
+ * Parses environment variables from env.template and merges portalInput from application config
  * @param {string} envTemplate - Content of env.template file
- * @param {Object|null} [variablesConfig=null] - Optional configuration from variables.yaml
+ * @param {Object|null} [variablesConfig=null] - Optional configuration from application.yaml
  * @returns {Array<Object>} Configuration array with merged portalInput
  * @throws {Error} If portalInput structure is invalid
  */
 /**
  * Creates a map of portalInput configurations from variables config
  * @function createPortalInputMap
- * @param {Object|null} variablesConfig - Configuration from variables.yaml
+ * @param {Object|null} variablesConfig - Configuration from application.yaml
  * @returns {Map} Map of variable names to portalInput configurations
  */
 function createPortalInputMap(variablesConfig) {
@@ -250,7 +243,7 @@ function createConfigItem(key, value, location, required, portalInputMap) {
     required
   };
 
-  // Merge portalInput if it exists in variables.yaml
+  // Merge portalInput if it exists in application config
   if (portalInputMap.has(key)) {
     configItem.portalInput = portalInputMap.get(key);
   }

package/lib/generator/index.js

@@ -2,7 +2,7 @@
  * AI Fabrix Builder Deployment JSON Generator
  *
  * This module generates deployment JSON manifests for Miso Controller.
- * Combines variables.yaml, env.template, and rbac.yaml into deployment configuration.
+ * Combines application.yaml, env.template, and rbac.yaml into deployment configuration.
  *
  * @fileoverview Deployment JSON generation for AI Fabrix Builder
  * @author AI Fabrix Team
@@ -13,7 +13,8 @@ const fs = require('fs');
 const path = require('path');
 const _validator = require('../validation/validator');
 const builders = require('./builders');
-const { detectAppType, getDeployJsonPath } = require('../utils/paths');
+const { detectAppType, getDeployJsonPath, resolveApplicationConfigPath } = require('../utils/paths');
+const { logOfflinePathWhenType } = require('../utils/cli-utils');
 const splitFunctions = require('./split');
 const { loadVariables, loadEnvTemplate, loadRbac, parseEnvironmentVariables } = require('./helpers');
 const { generateExternalSystemApplicationSchema, splitExternalApplicationSchema } = require('./external');
@@ -24,13 +25,13 @@ const { resolveVersionForApp } = require('../utils/image-version');
  * Generates deployment JSON from application configuration files
  * Creates <app-name>-deploy.json for regular apps (consistent naming)
  * For external systems, generates application-schema.json
- * For regular apps, generates deployment manifest from variables.yaml, env.template, rbac.yaml
+ * For regular apps, generates deployment manifest from application.yaml, env.template, rbac.yaml
  *
  * @async
  * @function generateDeployJson
  * @param {string} appName - Name of the application
  * @param {Object} [options] - Generation options
- * @param {string} [options.type] - Forced application type (external)
+ *
  * @returns {Promise<string>} Path to generated deployment JSON file
  * @throws {Error} If generation fails or configuration is invalid
  *
@@ -46,7 +47,7 @@ const { resolveVersionForApp } = require('../utils/image-version');
  * @returns {Object} Loaded configuration files
  */
 function loadDeploymentConfigFiles(appPath, appType, appName) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const variablesPath = resolveApplicationConfigPath(appPath);
   const templatePath = path.join(appPath, 'env.template');
   const rbacPath = path.join(appPath, 'rbac.yaml');
   const jsonPath = getDeployJsonPath(appName, appType, true); // Use new naming
@@ -69,7 +70,7 @@ function loadDeploymentConfigFiles(appPath, appType, appName) {
  * @throws {Error} If validation fails
  */
 function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
-  // Parse environment variables from template and merge portalInput from variables.yaml
+  // Parse environment variables from template and merge portalInput from application config
   const configuration = parseEnvironmentVariables(envTemplate, variables);
 
   // Build deployment manifest (Controller computes deploymentKey from schema)
@@ -93,17 +94,17 @@ function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
  * @param {string} appName - Application name
  * @param {Object} [options] - Options (e.g. type for external)
  * @returns {Promise<{ deployment: Object, appPath: string }>} Manifest and app path
- * @throws {Error} If variables.yaml/env.template missing or generation fails
+ * @throws {Error} If application config/env.template missing or generation fails
  */
 async function buildDeploymentManifestInMemory(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const { isExternal, appPath, appType } = await detectAppType(appName, options);
+  const { isExternal, appPath, appType } = await detectAppType(appName);
 
   if (isExternal) {
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
     return { deployment: manifest, appPath };
   }
 
@@ -124,13 +125,13 @@ async function generateDeployJson(appName, options = {}) {
     throw new Error('App name is required and must be a string');
   }
 
-  // Detect app type and get correct path (integration or builder)
-  const { isExternal, appPath, appType } = await detectAppType(appName, options);
+  // Detect app type and get correct path (integration first, then builder)
+  const { isExternal, appPath, appType } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
 
   // Check if app type is external
   if (isExternal) {
-    // Generate controller-compatible manifest format
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
 
     // Determine system key for file naming
     const systemKey = manifest.key || appName;
@@ -161,8 +162,7 @@ async function generateDeployJsonWithValidation(appName, options = {}) {
   const jsonContent = fs.readFileSync(jsonPath, 'utf8');
   const deployment = JSON.parse(jsonContent);
 
-  // Detect if this is an external system
-  const { isExternal } = await detectAppType(appName, options);
+  const { isExternal } = await detectAppType(appName);
 
   // For external systems, skip deployment JSON validation (they use external system JSON structure)
   if (isExternal) {

package/lib/generator/parse-image.js

@@ -0,0 +1,35 @@
+/**
+ * Parses image reference string into components.
+ * @fileoverview Image reference parser for deployment JSON
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Parses image reference string into components
+ * @function parseImageReference
+ * @param {string} imageString - Full image string (e.g., "registry/name:tag")
+ * @returns {Object} Object with registry, name, and tag
+ */
+function parseImageReference(imageString) {
+  if (!imageString || typeof imageString !== 'string') {
+    return { registry: null, name: null, tag: 'latest' };
+  }
+
+  const parts = imageString.split('/');
+  let registry = null;
+  let nameAndTag = imageString;
+
+  if (parts.length > 1 && parts[0].includes('.')) {
+    registry = parts[0];
+    nameAndTag = parts.slice(1).join('/');
+  }
+
+  const tagIndex = nameAndTag.lastIndexOf(':');
+  const name = tagIndex !== -1 ? nameAndTag.substring(0, tagIndex) : nameAndTag;
+  const tag = tagIndex !== -1 ? nameAndTag.substring(tagIndex + 1) : 'latest';
+
+  return { registry, name, tag };
+}
+
+module.exports = { parseImageReference };

package/lib/generator/split-readme.js

@@ -0,0 +1,105 @@
+/**
+ * README generation from deployment JSON for split flow.
+ * @fileoverview Builds readme config and generates README from deployment JSON
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { generateReadmeMd } = require('../app/readme');
+const { parseImageReference } = require('./parse-image');
+
+/**
+ * Builds config for external-system README from deployment
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigForExternal(deployment) {
+  const system = deployment.system;
+  const appName = system.key || deployment.key || 'external-system';
+  const dataSources = deployment.dataSources || deployment.datasources || [];
+  return {
+    appName,
+    config: {
+      type: 'external',
+      systemKey: appName,
+      systemType: system.type || 'openapi',
+      systemDisplayName: system.displayName || appName,
+      systemDescription: system.description || `External system integration for ${appName}`,
+      datasourceCount: dataSources.length,
+      datasources: dataSources
+    }
+  };
+}
+
+/**
+ * Builds config for application README from deployment
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigForApp(deployment) {
+  const appName = deployment.key || 'application';
+  const imageParts = parseImageReference(deployment.image || '');
+  const port = deployment.port !== undefined ? deployment.port : 3000;
+  const imageName = imageParts.name || appName;
+  const registry = imageParts.registry || 'myacr.azurecr.io';
+
+  const config = {
+    type: deployment.type || 'webapp',
+    displayName: deployment.displayName,
+    description: deployment.description,
+    port,
+    build: { localPort: port },
+    image: { name: imageName, registry },
+    registry,
+    database: deployment.requiresDatabase,
+    requires: {
+      database: deployment.requiresDatabase,
+      redis: deployment.requiresRedis,
+      storage: deployment.requiresStorage
+    },
+    redis: deployment.requiresRedis,
+    storage: deployment.requiresStorage,
+    authentication: !!deployment.authentication
+  };
+
+  if (config.type === 'external') {
+    config.systemKey = appName;
+    config.systemType = deployment.systemType || 'openapi';
+    config.systemDisplayName = deployment.displayName || appName;
+    config.systemDescription = deployment.description || `External system integration for ${appName}`;
+    config.datasourceCount = 0;
+    config.datasources = deployment.dataSources || deployment.datasources || [];
+  }
+
+  return { appName, config };
+}
+
+/**
+ * Builds application config shape from deployment JSON for README template context.
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {{ appName: string, config: Object }}
+ */
+function buildReadmeConfigFromDeployment(deployment) {
+  if (deployment.system && typeof deployment.system === 'object') {
+    return buildReadmeConfigForExternal(deployment);
+  }
+  return buildReadmeConfigForApp(deployment);
+}
+
+/**
+ * Generates README.md content from deployment JSON.
+ * @param {Object} deployment - Deployment JSON object
+ * @returns {string} README.md content
+ */
+function generateReadmeFromDeployJson(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    throw new Error('Deployment object is required');
+  }
+  const { appName, config } = buildReadmeConfigFromDeployment(deployment);
+  return generateReadmeMd(appName, config);
+}
+
+module.exports = {
+  buildReadmeConfigFromDeployment,
+  generateReadmeFromDeployJson
+};