@aifabrix/builder 2.37.9 → 2.39.0

package/lib/commands/up-common.js

@@ -10,6 +10,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const yaml = require('js-yaml');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const pathsUtil = require('../utils/paths');
@@ -30,8 +31,74 @@ async function ensureTemplateAtPath(appName, targetAppPath) {
   return true;
 }
 
+/**
+ * Resolve the directory (folder) that would contain the .env file for envOutputPath.
+ * @param {string} envOutputPath - Value from build.envOutputPath (e.g. ../../.env)
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {string} Absolute path to the folder that would contain the output .env file
+ */
+function getEnvOutputPathFolder(envOutputPath, variablesPath) {
+  const variablesDir = path.dirname(variablesPath);
+  const resolvedFile = path.resolve(variablesDir, envOutputPath);
+  return path.dirname(resolvedFile);
+}
+
+/**
+ * Validates envOutputPath: if the target folder does not exist, patches variables.yaml to set envOutputPath to null.
+ * Used by up-platform, up-miso, up-dataplane so we do not keep a path that points outside an existing tree.
+ *
+ * @param {string} appName - Application name (e.g. keycloak, miso-controller, dataplane)
+ */
+function validateEnvOutputPathFolderOrNull(appName) {
+  if (!appName || typeof appName !== 'string') return;
+  const pathsToPatch = [pathsUtil.getBuilderPath(appName)];
+  const cwdBuilderPath = path.join(process.cwd(), 'builder', appName);
+  if (path.resolve(cwdBuilderPath) !== path.resolve(pathsToPatch[0])) {
+    pathsToPatch.push(cwdBuilderPath);
+  }
+  const envOutputPathLine = /^(\s*envOutputPath:)\s*.*$/m;
+  const replacement = '$1 null  # deploy only, no copy';
+  for (const appPath of pathsToPatch) {
+    const variablesPath = path.join(appPath, 'variables.yaml');
+    if (!fs.existsSync(variablesPath)) continue;
+    try {
+      const content = fs.readFileSync(variablesPath, 'utf8');
+      const variables = yaml.load(content);
+      const value = variables?.build?.envOutputPath;
+      if (value === null || value === undefined || value === '') continue;
+      const folder = getEnvOutputPathFolder(String(value).trim(), variablesPath);
+      if (fs.existsSync(folder)) continue;
+      const newContent = content.replace(envOutputPathLine, replacement);
+      fs.writeFileSync(variablesPath, newContent, 'utf8');
+    } catch (err) {
+      logger.warn(chalk.yellow(`Could not validate envOutputPath in ${variablesPath}: ${err.message}`));
+    }
+  }
+}
+
+/**
+ * Patches a single variables.yaml to set build.envOutputPath to null for deploy-only.
+ *
+ * @param {string} variablesPath - Path to variables.yaml
+ * @param {RegExp} envOutputPathLine - Regex for envOutputPath line
+ * @param {string} replacement - Replacement string
+ */
+function patchOneVariablesFileForDeployOnly(variablesPath, envOutputPathLine, replacement) {
+  const content = fs.readFileSync(variablesPath, 'utf8');
+  if (!envOutputPathLine.test(content)) return;
+  const variables = yaml.load(content);
+  const value = variables?.build?.envOutputPath;
+  if (value !== null && value !== undefined && value !== '') {
+    const folder = getEnvOutputPathFolder(String(value).trim(), variablesPath);
+    if (fs.existsSync(folder)) return;
+  }
+  const newContent = content.replace(envOutputPathLine, replacement);
+  fs.writeFileSync(variablesPath, newContent, 'utf8');
+}
+
 /**
  * Patches variables.yaml to set build.envOutputPath to null for deploy-only (no local code).
+ * Only patches when the target folder does NOT exist; when folder exists, keeps the value.
  * Use when running up-miso/up-platform so we do not copy .env to repo paths or show that message.
  * Patches both primary builder path and cwd/builder if different.
  *
@@ -50,10 +117,7 @@ function patchEnvOutputPathForDeployOnly(appName) {
     const variablesPath = path.join(appPath, 'variables.yaml');
     if (!fs.existsSync(variablesPath)) continue;
     try {
-      let content = fs.readFileSync(variablesPath, 'utf8');
-      if (!envOutputPathLine.test(content)) continue;
-      content = content.replace(envOutputPathLine, replacement);
-      fs.writeFileSync(variablesPath, content, 'utf8');
+      patchOneVariablesFileForDeployOnly(variablesPath, envOutputPathLine, replacement);
     } catch (err) {
       logger.warn(chalk.yellow(`Could not patch envOutputPath in ${variablesPath}: ${err.message}`));
     }
@@ -99,4 +163,9 @@ async function ensureAppFromTemplate(appName) {
   return primaryCopied;
 }
 
-module.exports = { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly };
+module.exports = {
+  ensureAppFromTemplate,
+  patchEnvOutputPathForDeployOnly,
+  validateEnvOutputPathFolderOrNull,
+  getEnvOutputPathFolder
+};

package/lib/commands/up-dataplane.js

@@ -1,9 +1,10 @@
 /**
  * AI Fabrix Builder - Up Dataplane Command
  *
- * Registers or rotates dataplane app in dev, then deploys. Miso-controller runs
- * the dataplane container; this command does not run the image locally.
- * If app is already registered, uses rotate-secret; otherwise registers.
+ * Always local deployment: registers or rotates dataplane app in dev, sends
+ * deployment manifest to Miso Controller, then runs the dataplane app locally
+ * (same as aifabrix deploy dataplane --deployment=local). If app is already
+ * registered, uses rotate-secret; otherwise registers.
  *
  * @fileoverview up-dataplane command implementation
  * @author AI Fabrix Team
@@ -23,7 +24,7 @@ const { registerApplication } = require('../app/register');
 const { rotateSecret } = require('../app/rotate-secret');
 const { checkApplicationExists } = require('../utils/app-existence');
 const app = require('../app');
-const { ensureAppFromTemplate } = require('./up-common');
+const { ensureAppFromTemplate, validateEnvOutputPathFolderOrNull } = require('./up-common');
 
 /**
  * Register or rotate dataplane: if app exists in controller, rotate secret; otherwise register.
@@ -64,7 +65,8 @@ function buildDataplaneImageRef(registry) {
 
 /**
  * Handle up-dataplane command: ensure logged in, environment dev, ensure dataplane,
- * register or rotate (if already registered), then deploy (miso-controller runs the container).
+ * register or rotate (if already registered), deploy (send manifest to controller),
+ * then run dataplane app locally (always local deployment).
  *
  * @async
  * @function handleUpDataplane
@@ -80,7 +82,7 @@ async function handleUpDataplane(options = {}) {
   if (builderDir) {
     process.env.AIFABRIX_BUILDER_DIR = builderDir;
   }
-  logger.log(chalk.blue('Starting up-dataplane (register/rotate, deploy dataplane in dev)...\n'));
+  logger.log(chalk.blue('Starting up-dataplane (register/rotate, deploy, then run dataplane locally)...\n'));
 
   const [controllerUrl, environmentKey] = await Promise.all([resolveControllerUrl(), resolveEnvironment()]);
   const authConfig = await checkAuthentication(controllerUrl, environmentKey);
@@ -95,6 +97,8 @@ async function handleUpDataplane(options = {}) {
   logger.log(chalk.green('✓ Logged in and environment is dev'));
 
   await ensureAppFromTemplate('dataplane');
+  // If envOutputPath target folder does not exist, set envOutputPath to null
+  validateEnvOutputPathFolderOrNull('dataplane');
 
   await registerOrRotateDataplane(options, controllerUrl, environmentKey, authConfig);
 
@@ -102,8 +106,10 @@ async function handleUpDataplane(options = {}) {
   const deployOpts = { imageOverride, image: imageOverride, registryMode: options.registryMode };
 
   await app.deployApp('dataplane', deployOpts);
+  logger.log('');
+  await app.runApp('dataplane', {});
 
-  logger.log(chalk.green('\n✓ up-dataplane complete. Dataplane is registered and deployed in dev (miso-controller runs the container).'));
+  logger.log(chalk.green('\n✓ up-dataplane complete. Dataplane is registered, deployed in dev, and running locally.'));
 }
 
 module.exports = { handleUpDataplane, buildDataplaneImageRef };

package/lib/commands/up-miso.js

@@ -1,7 +1,7 @@
 /**
  * AI Fabrix Builder - Up Miso Command
  *
- * Installs keycloak, miso-controller, and dataplane from images (no build).
+ * Installs keycloak and miso-controller from images (no build). For dataplane, use up-dataplane.
  * Assumes infra is up; sets dev secrets and resolves (no force; existing .env values preserved).
  *
  * @fileoverview up-miso command implementation
@@ -19,19 +19,16 @@ const secrets = require('../core/secrets');
 const infra = require('../infrastructure');
 const app = require('../app');
 const { saveLocalSecret } = require('../utils/local-secrets');
-const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly } = require('./up-common');
+const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly, validateEnvOutputPathFolderOrNull } = require('./up-common');
 
 /** Keycloak base port (from templates/applications/keycloak/variables.yaml) */
 const KEYCLOAK_BASE_PORT = 8082;
 /** Miso controller base port (dev-config app base) */
 const MISO_BASE_PORT = 3000;
-/** Dataplane base port (from templates/applications/dataplane/variables.yaml) */
-const _DATAPLANE_BASE_PORT = 3001;
-
 /**
- * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string, dataplane?: string }
- * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1', 'dataplane=reg/d:v1']
- * @returns {{ keycloak?: string, 'miso-controller'?: string, dataplane?: string }}
+ * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string }
+ * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1']
+ * @returns {{ keycloak?: string, 'miso-controller'?: string }}
  */
 function parseImageOptions(imageOpts) {
   const map = {};
@@ -50,7 +47,7 @@ function parseImageOptions(imageOpts) {
 
 /**
  * Build full image ref from registry and app variables (registry/name:tag)
- * @param {string} appName - keycloak, miso-controller, or dataplane
+ * @param {string} appName - keycloak or miso-controller
  * @param {string} registry - Registry URL
  * @returns {string} Full image reference
  */
@@ -67,7 +64,7 @@ function buildImageRefFromRegistry(appName, registry) {
 }
 
 /**
- * Set URL secrets and resolve keycloak + miso-controller + dataplane (no force; existing .env preserved)
+ * Set URL secrets and resolve keycloak + miso-controller (no force; existing .env preserved)
  * @async
  * @param {number} devIdNum - Developer ID number
  */
@@ -79,12 +76,11 @@ async function setMisoSecretsAndResolve(devIdNum) {
   logger.log(chalk.green('✓ Set keycloak and miso-controller URL secrets'));
   await secrets.generateEnvFile('keycloak', undefined, 'docker', false, true);
   await secrets.generateEnvFile('miso-controller', undefined, 'docker', false, true);
-  await secrets.generateEnvFile('dataplane', undefined, 'docker', false, true);
-  logger.log(chalk.green('✓ Resolved keycloak, miso-controller, and dataplane'));
+  logger.log(chalk.green('✓ Resolved keycloak and miso-controller'));
 }
 
 /**
- * Build run options and run keycloak, miso-controller, then dataplane
+ * Build run options and run keycloak, then miso-controller
  * @async
  * @param {Object} options - Commander options (image, registry, registryMode)
  */
@@ -92,27 +88,23 @@ async function runMisoApps(options) {
   const imageMap = parseImageOptions(options.image);
   const keycloakImage = imageMap.keycloak || (options.registry ? buildImageRefFromRegistry('keycloak', options.registry) : undefined);
   const misoImage = imageMap['miso-controller'] || (options.registry ? buildImageRefFromRegistry('miso-controller', options.registry) : undefined);
-  const dataplaneImage = imageMap.dataplane || (options.registry ? buildImageRefFromRegistry('dataplane', options.registry) : undefined);
   const keycloakRunOpts = { image: keycloakImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
   const misoRunOpts = { image: misoImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
-  const dataplaneRunOpts = { image: dataplaneImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
   logger.log(chalk.blue('Starting keycloak...'));
   await app.runApp('keycloak', keycloakRunOpts);
   logger.log(chalk.blue('Starting miso-controller...'));
   await app.runApp('miso-controller', misoRunOpts);
-  logger.log(chalk.blue('Starting dataplane...'));
-  await app.runApp('dataplane', dataplaneRunOpts);
 }
 
 /**
- * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak, miso-controller, then dataplane.
+ * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak and miso-controller.
  *
  * @async
  * @function handleUpMiso
  * @param {Object} options - Commander options
  * @param {string} [options.registry] - Override registry for all apps
  * @param {string} [options.registryMode] - Override registry mode (acr|external)
- * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1, miso-controller=reg/m:v1, dataplane=reg/d:v1
+ * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1, miso-controller=reg/m:v1
  * @returns {Promise<void>}
  * @throws {Error} If infra not up or any step fails
  */
@@ -121,7 +113,7 @@ async function handleUpMiso(options = {}) {
   if (builderDir) {
     process.env.AIFABRIX_BUILDER_DIR = builderDir;
   }
-  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller + dataplane from images)...\n'));
+  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
   // Strict: only this developer's infra (same as status), so up-miso and status agree
   const health = await infra.checkInfraHealth(undefined, { strict: true });
   const allHealthy = Object.values(health).every(status => status === 'healthy');
@@ -131,17 +123,18 @@ async function handleUpMiso(options = {}) {
   logger.log(chalk.green('✓ Infrastructure is up'));
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
-  await ensureAppFromTemplate('dataplane');
+  // If envOutputPath target folder does not exist, set envOutputPath to null
+  validateEnvOutputPathFolderOrNull('keycloak');
+  validateEnvOutputPathFolderOrNull('miso-controller');
   // Deploy-only: do not copy .env to repo paths; patch variables so envOutputPath is null
   patchEnvOutputPathForDeployOnly('keycloak');
   patchEnvOutputPathForDeployOnly('miso-controller');
-  patchEnvOutputPathForDeployOnly('dataplane');
   const developerId = await config.getDeveloperId();
   const devIdNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   await setMisoSecretsAndResolve(devIdNum);
   await runMisoApps(options);
-  logger.log(chalk.green('\n✓ up-miso complete. Keycloak, miso-controller, and dataplane are running.') +
-    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed.'));
+  logger.log(chalk.green('\n✓ up-miso complete. Keycloak and miso-controller are running.') +
+    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
 }
 
 module.exports = { handleUpMiso, parseImageOptions };

package/lib/core/templates.js

@@ -35,7 +35,6 @@ function generateExternalSystemVariables(appName, displayName, config) {
       type: 'external'
     },
     deployment: {
-      controllerUrl: '',
       environment: 'dev'
     },
     externalIntegration: {
@@ -83,7 +82,8 @@ function buildWebappVariables(appName, displayName, config, imageName, imageTag)
       key: appName,
       displayName: displayName,
       description: `${appName.replace(/-/g, ' ')} application`,
-      type: appType
+      type: appType,
+      version: config.version || '1.0.0'
     },
     image: {
       name: imageName,

package/lib/external-system/deploy.js

@@ -13,10 +13,87 @@ const chalk = require('chalk');
 const { getDeploymentAuth } = require('../utils/token-manager');
 const logger = require('../utils/logger');
 const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+const { getExternalSystem } = require('../api/external-systems.api');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateExternalSystemComplete } = require('../validation/validate');
 const { displayValidationResults } = require('../validation/validate-display');
 
+/**
+ * Displays API and MCP documentation URLs from dataplane when available
+ * @async
+ * @function displayDeploymentDocs
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} environment - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} systemKey - External system key
+ */
+async function displayDeploymentDocs(controllerUrl, environment, authConfig, systemKey) {
+  try {
+    const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+    const res = await getExternalSystem(dataplaneUrl, systemKey, authConfig);
+    const sys = res?.data || res;
+    if (!sys) return;
+
+    const apiDocumentUrl = sys.apiDocumentUrl;
+    const mcpServerUrl = sys.mcpServerUrl;
+    const openApiDocsPageUrl = sys.openApiDocsPageUrl;
+
+    const urls = [];
+    if (apiDocumentUrl && typeof apiDocumentUrl === 'string') {
+      urls.push({ label: 'API Docs', url: apiDocumentUrl });
+    }
+    if (mcpServerUrl && typeof mcpServerUrl === 'string') {
+      urls.push({ label: 'MCP Server', url: mcpServerUrl });
+    }
+    if (openApiDocsPageUrl && typeof openApiDocsPageUrl === 'string') {
+      urls.push({ label: 'OpenAPI Docs Page', url: openApiDocsPageUrl });
+    }
+
+    if (urls.length > 0) {
+      logger.log(chalk.blue('\nDocumentation:'));
+      urls.forEach(({ label, url }) => {
+        logger.log(chalk.blue(`   ${label}: ${url}`));
+      });
+    }
+  } catch (_err) {
+    // Silently ignore: dataplane may be unreachable or docs not configured
+  }
+}
+
+/**
+ * Deploys via controller and displays success summary with docs
+ * @async
+ * @function executeDeployAndDisplay
+ * @param {Object} manifest - Controller manifest
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} environment - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} options - Deployment options
+ * @returns {Promise<Object>} Deployment result
+ */
+async function executeDeployAndDisplay(manifest, controllerUrl, environment, authConfig, options) {
+  const deployer = require('../deployment/deployer');
+  const pollOpts = {
+    poll: options.poll,
+    pollInterval: options.pollInterval !== undefined ? options.pollInterval : 500,
+    pollMaxAttempts: options.pollMaxAttempts,
+    ...options
+  };
+  const result = await deployer.deployToController(
+    manifest,
+    controllerUrl,
+    environment,
+    authConfig,
+    pollOpts
+  );
+  logger.log(chalk.green('\n✅ External system deployed successfully!'));
+  logger.log(chalk.blue(`System: ${manifest.key}`));
+  logger.log(chalk.blue(`Datasources: ${manifest.dataSources.length}`));
+  await displayDeploymentDocs(controllerUrl, environment, authConfig, manifest.key);
+  return result;
+}
+
 /**
  * Prepares deployment configuration (auth, controller URL, environment)
  * @async
@@ -75,26 +152,13 @@ async function deployExternalSystem(appName, options = {}) {
     const { environment, controllerUrl, authConfig } = await prepareDeploymentConfig(appName, options);
 
     // Step 3: Deploy via controller pipeline (same as regular apps)
-    // Use 500ms polling for external systems (faster than web apps which use 5000ms)
-    const deployer = require('../deployment/deployer');
-    const result = await deployer.deployToController(
+    const result = await executeDeployAndDisplay(
       manifest,
       controllerUrl,
       environment,
       authConfig,
-      {
-        poll: options.poll,
-        pollInterval: options.pollInterval !== undefined ? options.pollInterval : 500,
-        pollMaxAttempts: options.pollMaxAttempts,
-        ...options
-      }
+      options
     );
-
-    // Display success summary
-    logger.log(chalk.green('\n✅ External system deployed successfully!'));
-    logger.log(chalk.blue(`System: ${manifest.key}`));
-    logger.log(chalk.blue(`Datasources: ${manifest.dataSources.length}`));
-
     return result;
   } catch (error) {
     let message = `Failed to deploy external system: ${error.message}`;

package/lib/generator/builders.js

@@ -126,11 +126,17 @@ function buildAuthentication(rbac) {
  * @returns {Object} App metadata
  */
 function buildAppMetadata(appName, variables) {
+  const rawVersion = variables.app?.version;
+  const version =
+    rawVersion !== undefined && rawVersion !== null && String(rawVersion).trim()
+      ? String(rawVersion).trim()
+      : '1.0.0';
   return {
     key: variables.app?.key || appName,
     displayName: variables.app?.displayName || appName,
     description: variables.app?.description || '',
-    type: variables.app?.type || 'webapp'
+    type: variables.app?.type || 'webapp',
+    version
   };
 }
 
@@ -256,25 +262,6 @@ function validateBuildFields(build) {
   return Object.keys(buildConfig).length > 0 ? buildConfig : null;
 }
 
-/**
- * Validates and transforms deployment fields
- * @function validateDeploymentFields
- * @param {Object} deployment - Deployment configuration
- * @returns {Object|null} Validated deployment config or null
- */
-function validateDeploymentFields(deployment) {
-  if (!deployment) {
-    return null;
-  }
-
-  const deploymentConfig = {};
-  if (deployment.controllerUrl && deployment.controllerUrl.trim() && deployment.controllerUrl.startsWith('https://')) {
-    deploymentConfig.controllerUrl = deployment.controllerUrl;
-  }
-
-  return Object.keys(deploymentConfig).length > 0 ? deploymentConfig : null;
-}
-
 /**
  * Adds optional fields to deployment manifest
  * @function buildOptionalFields
@@ -333,11 +320,6 @@ function addValidatedConfigSections(deployment, variables) {
   if (build) {
     deployment.build = build;
   }
-
-  const deploymentConfig = validateDeploymentFields(variables.deployment);
-  if (deploymentConfig) {
-    deployment.deployment = deploymentConfig;
-  }
 }
 
 /**
@@ -375,12 +357,11 @@ function buildOptionalFields(deployment, variables, rbac) {
  * Builds deployment manifest structure
  * @param {string} appName - Application name
  * @param {Object} variables - Variables configuration
- * @param {string} deploymentKey - Deployment key
  * @param {Array} configuration - Environment configuration
  * @param {Object|null} rbac - RBAC configuration
  * @returns {Object} Deployment manifest
  */
-function buildManifestStructure(appName, variables, deploymentKey, configuration, rbac) {
+function buildManifestStructure(appName, variables, configuration, rbac) {
   const registryMode = variables.image?.registryMode || 'external';
   const filteredConfiguration = filterConfigurationByRegistryMode(configuration, registryMode);
   const deployment = buildBaseDeployment(appName, variables, filteredConfiguration);

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

@@ -11,7 +11,6 @@
 
 const path = require('path');
 const { detectAppType } = require('../utils/paths');
-const { generateDeploymentKeyFromJson } = require('../core/key-generator');
 const { loadSystemFile, loadDatasourceFiles } = require('./external');
 const { loadVariables, loadRbac } = require('./helpers');
 
@@ -97,7 +96,7 @@ async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
  *
  * @example
  * const manifest = await generateControllerManifest('my-hubspot');
- * // Returns: { key, displayName, description, type: "external", system: {...}, dataSources: [...], deploymentKey }
+ * // Returns: { key, displayName, description, type: "external", system: {...}, dataSources: [...] }
  */
 async function generateControllerManifest(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
@@ -124,13 +123,15 @@ async function generateControllerManifest(appName, options = {}) {
   const datasourceFiles = variables.externalIntegration.dataSources || [];
   const datasourceJsons = await loadDatasourceFiles(appPath, schemaBasePath, datasourceFiles);
 
+  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,
     systems: systemFiles,
     dataSources: datasourceFiles,
     autopublish: variables.externalIntegration.autopublish !== false, // default true
-    version: variables.externalIntegration.version || '1.0.0'
+    version: appVersion
   };
 
   const manifest = {
@@ -138,6 +139,7 @@ async function generateControllerManifest(appName, options = {}) {
     displayName: metadata.displayName,
     description: metadata.description,
     type: 'external',
+    version: appVersion,
     externalIntegration: externalIntegration,
     // Inline system and dataSources for atomic deployment (optional but recommended)
     system: systemJson,
@@ -148,7 +150,6 @@ async function generateControllerManifest(appName, options = {}) {
     requiresStorage: false
   };
 
-  manifest.deploymentKey = generateDeploymentKeyFromJson(manifest);
   return manifest;
 }
 

package/lib/generator/index.js

@@ -11,7 +11,6 @@
 
 const fs = require('fs');
 const path = require('path');
-const _keyGenerator = require('../core/key-generator');
 const _validator = require('../validation/validator');
 const builders = require('./builders');
 const { detectAppType, getDeployJsonPath } = require('../utils/paths');
@@ -19,6 +18,7 @@ const splitFunctions = require('./split');
 const { loadVariables, loadEnvTemplate, loadRbac, parseEnvironmentVariables } = require('./helpers');
 const { generateExternalSystemApplicationSchema, splitExternalApplicationSchema } = require('./external');
 const { generateControllerManifest } = require('./external-controller-manifest');
+const { resolveVersionForApp } = require('../utils/image-version');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -65,21 +65,15 @@ function loadDeploymentConfigFiles(appPath, appType, appName) {
  * @param {Object} variables - Variables configuration
  * @param {Object} envTemplate - Environment template
  * @param {Object} rbac - RBAC configuration
- * @returns {Object} Deployment manifest with deploymentKey
+ * @returns {Object} Deployment manifest
  * @throws {Error} If validation fails
  */
 function buildAndValidateDeployment(appName, variables, envTemplate, rbac) {
   // Parse environment variables from template and merge portalInput from variables.yaml
   const configuration = parseEnvironmentVariables(envTemplate, variables);
 
-  // Build deployment manifest WITHOUT deploymentKey initially
-  const deployment = builders.buildManifestStructure(appName, variables, null, configuration, rbac);
-
-  // Generate deploymentKey from the manifest object (excluding deploymentKey field)
-  const deploymentKey = _keyGenerator.generateDeploymentKeyFromJson(deployment);
-
-  // Add deploymentKey to manifest
-  deployment.deploymentKey = deploymentKey;
+  // Build deployment manifest (Controller computes deploymentKey from schema)
+  const deployment = builders.buildManifestStructure(appName, variables, configuration, rbac);
 
   // Validate deployment JSON against schema
   const validation = _validator.validateDeploymentJson(deployment);
@@ -114,10 +108,13 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
   }
 
   const { variables, envTemplate, rbac } = loadDeploymentConfigFiles(appPath, appType, appName);
+  const resolved = await resolveVersionForApp(appName, variables, { updateBuilder: false });
+  const variablesWithVersion = {
+    ...variables,
+    app: { ...variables.app, version: resolved.version }
+  };
   const configuration = parseEnvironmentVariables(envTemplate, variables);
-  const deployment = builders.buildManifestStructure(appName, variables, null, configuration, rbac);
-  const deploymentKey = _keyGenerator.generateDeploymentKeyFromJson(deployment);
-  deployment.deploymentKey = deploymentKey;
+  const deployment = builders.buildManifestStructure(appName, variablesWithVersion, configuration, rbac);
 
   return { deployment, appPath };
 }
@@ -145,7 +142,12 @@ async function generateDeployJson(appName, options = {}) {
 
   // Regular app: generate deployment manifest
   const { variables, envTemplate, rbac, jsonPath } = loadDeploymentConfigFiles(appPath, appType, appName);
-  const deployment = buildAndValidateDeployment(appName, variables, envTemplate, rbac);
+  const resolved = await resolveVersionForApp(appName, variables, { updateBuilder: false });
+  const variablesWithVersion = {
+    ...variables,
+    app: { ...variables.app, version: resolved.version }
+  };
+  const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac);
 
   // Write deployment JSON
   const jsonContent = JSON.stringify(deployment, null, 2);

package/lib/generator/split.js

@@ -98,6 +98,7 @@ function extractAppSection(deployment) {
   if (deployment.displayName) app.displayName = deployment.displayName;
   if (deployment.description) app.description = deployment.description;
   if (deployment.type) app.type = deployment.type;
+  if (deployment.version) app.version = deployment.version;
   return app;
 }
 

package/lib/generator/wizard.js

@@ -234,8 +234,11 @@ async function generateOrUpdateVariablesYaml(params) {
         key: appName,
         displayName: systemConfig.displayName || appName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase()),
         description: systemConfig.description || `External system integration for ${appName}`,
-        type: 'external'
+        type: 'external',
+        version: '1.0.0'
       };
+    } else {
+      variables.app.version = variables.app.version || '1.0.0';
     }
 
     // Set deployment config if not present