@aifabrix/builder 2.42.0 → 2.43.0

package/lib/infrastructure/index.js

@@ -37,8 +37,34 @@ const {
   startDockerServicesAndConfigure,
   checkInfraHealth
 } = require('./services');
+const adminSecrets = require('../core/admin-secrets');
 // Lazy require to avoid circular dependency: infra -> app/down -> run-helpers -> infra
 
+/**
+ * Runs a callback with a temporary .env.run file in infraDir (created from admin-secrets).
+ * Removes the file in a finally block.
+ * @async
+ * @param {string} infraDir - Infrastructure directory path
+ * @param {string} adminSecretsPath - Path to admin-secrets.env
+ * @param {function(string): Promise<void>} fn - Callback receiving runEnvPath
+ * @returns {Promise<void>}
+ */
+async function withRunEnv(infraDir, adminSecretsPath, fn) {
+  const runEnvPath = path.join(infraDir, '.env.run');
+  try {
+    const adminObj = await adminSecrets.readAndDecryptAdminSecrets(adminSecretsPath);
+    const content = adminSecrets.envObjectToContent(adminObj);
+    fs.writeFileSync(runEnvPath, content, { mode: 0o600 });
+    await fn(runEnvPath);
+  } finally {
+    try {
+      if (fs.existsSync(runEnvPath)) fs.unlinkSync(runEnvPath);
+    } catch {
+      // Ignore unlink errors
+    }
+  }
+}
+
 /**
  * Prepares infrastructure environment
  * Ensures infra secrets exist, then admin-secrets.env, then miso init script.
@@ -65,7 +91,7 @@ async function prepareInfrastructureEnvironment(developerId, options = {}) {
   }
 
   // Prepare infrastructure directory
-  const { infraDir } = prepareInfraDirectory(devId, adminSecretsPath);
+  const { infraDir } = await prepareInfraDirectory(devId, adminSecretsPath);
   await ensureMisoInitScript(infraDir);
 
   return { devId, idNum, ports, templatePath, infraDir, adminSecretsPath };
@@ -174,8 +200,7 @@ async function removeAppVolumes(appNames, devId) {
 async function stopInfra() {
   const devId = await config.getDeveloperId();
   const aifabrixDir = paths.getAifabrixHome();
-  const infraDirName = getInfraDirName(devId);
-  const infraDir = path.join(aifabrixDir, infraDirName);
+  const infraDir = path.join(aifabrixDir, getInfraDirName(devId));
   const composePath = path.join(infraDir, 'compose.yaml');
   const adminSecretsPath = path.join(aifabrixDir, 'admin-secrets.env');
 
@@ -184,17 +209,15 @@ async function stopInfra() {
     return;
   }
 
-  try {
+  await withRunEnv(infraDir, adminSecretsPath, async(runEnvPath) => {
     logger.log('Stopping application containers on the same network...');
     await stopAllAppContainers(devId);
     logger.log('Stopping infrastructure services...');
     const projectName = getInfraProjectName(devId);
     const composeCmd = await dockerUtils.getComposeCommand();
-    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down`, { cwd: infraDir });
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${runEnvPath}" down`, { cwd: infraDir });
     logger.log('Infrastructure services stopped');
-  } finally {
-    // Keep the compose file for future use
-  }
+  });
 }
 
 /**
@@ -240,8 +263,7 @@ async function stopAllAppContainersAndVolumes(devId) {
 async function stopInfraWithVolumes() {
   const devId = await config.getDeveloperId();
   const aifabrixDir = paths.getAifabrixHome();
-  const infraDirName = getInfraDirName(devId);
-  const infraDir = path.join(aifabrixDir, infraDirName);
+  const infraDir = path.join(aifabrixDir, getInfraDirName(devId));
   const composePath = path.join(infraDir, 'compose.yaml');
   const adminSecretsPath = path.join(aifabrixDir, 'admin-secrets.env');
 
@@ -250,17 +272,15 @@ async function stopInfraWithVolumes() {
     return;
   }
 
-  try {
+  await withRunEnv(infraDir, adminSecretsPath, async(runEnvPath) => {
     logger.log('Stopping application containers on the same network...');
     await stopAllAppContainersAndVolumes(devId);
     logger.log('Stopping infrastructure services and removing all data...');
     const projectName = getInfraProjectName(devId);
     const composeCmd = await dockerUtils.getComposeCommand();
-    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" down -v`, { cwd: infraDir });
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${runEnvPath}" down -v`, { cwd: infraDir });
     logger.log('Infrastructure services stopped and all data removed');
-  } finally {
-    // Keep the compose file for future use
-  }
+  });
 }
 
 /**
@@ -281,7 +301,6 @@ async function restartService(serviceName) {
   if (!serviceName || typeof serviceName !== 'string') {
     throw new Error('Service name is required and must be a string');
   }
-
   const validServices = ['postgres', 'redis', 'pgadmin', 'redis-commander', 'traefik'];
   if (!validServices.includes(serviceName)) {
     throw new Error(`Invalid service name. Must be one of: ${validServices.join(', ')}`);
@@ -289,8 +308,7 @@ async function restartService(serviceName) {
 
   const devId = await config.getDeveloperId();
   const aifabrixDir = paths.getAifabrixHome();
-  const infraDirName = getInfraDirName(devId);
-  const infraDir = path.join(aifabrixDir, infraDirName);
+  const infraDir = path.join(aifabrixDir, getInfraDirName(devId));
   const composePath = path.join(infraDir, 'compose.yaml');
   const adminSecretsPath = path.join(aifabrixDir, 'admin-secrets.env');
 
@@ -298,15 +316,13 @@ async function restartService(serviceName) {
     throw new Error('Infrastructure not properly configured');
   }
 
-  try {
+  await withRunEnv(infraDir, adminSecretsPath, async(runEnvPath) => {
     logger.log(`Restarting ${serviceName} service...`);
     const projectName = getInfraProjectName(devId);
     const composeCmd = await dockerUtils.getComposeCommand();
-    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${adminSecretsPath}" restart ${serviceName}`, { cwd: infraDir });
+    await execAsyncWithCwd(`${composeCmd} -f "${composePath}" -p ${projectName} --env-file "${runEnvPath}" restart ${serviceName}`, { cwd: infraDir });
     logger.log(`${serviceName} service restarted successfully`);
-  } finally {
-    // Keep the compose file for future use
-  }
+  });
 }
 
 // Re-export status helper functions

package/lib/schema/env-config.yaml

@@ -16,11 +16,19 @@ environments:
     REDIS_PORT: 6379  # Internal port (container-to-container). REDIS_PUBLIC_PORT calculated automatically.
     MISO_HOST: miso-controller
     MISO_PORT: 3000  # Internal port (container-to-container). MISO_PUBLIC_PORT calculated automatically.
+    MISO_PUBLIC_PORT: 3000
     KEYCLOAK_HOST: keycloak
-    KEYCLOAK_PORT: 8082  # Internal port (container-to-container). KEYCLOAK_PUBLIC_PORT calculated automatically.
+    KEYCLOAK_PORT: 8080  # Internal port (container-to-container). KEYCLOAK_PUBLIC_PORT calculated automatically.
     KEYCLOAK_PUBLIC_PORT: 8082
+    MORI_HOST: mori-controller
+    MORI_PORT: 3004
+    OPENWEBUI_HOST: openwebui
+    OPENWEBUI_PORT: 3003
+    FLOWISE_HOST: flowise
+    FLOWISE_PORT: 3002
     DATAPLANE_HOST: dataplane
-    DATAPLANE_PORT: 3001 # Internal port (container-to-container). DATAPLANE_PUBLIC_PORT calculated automatically.
+    DATAPLANE_PORT: 3001  # Internal port (container-to-container). DATAPLANE_PUBLIC_PORT calculated automatically.
+    DATAPLANE_PUBLIC_PORT: 3001
     NODE_ENV: production
     PYTHONUNBUFFERED: 1
     PYTHONDONTWRITEBYTECODE: 1
@@ -33,10 +41,19 @@ environments:
     REDIS_PORT: 6379
     MISO_HOST: localhost
     MISO_PORT: 3010
+    MISO_PUBLIC_PORT: 3010
     KEYCLOAK_HOST: localhost
     KEYCLOAK_PORT: 8082
+    KEYCLOAK_PUBLIC_PORT: 8082
+    MORI_HOST: localhost
+    MORI_PORT: 3014
+    OPENWEBUI_HOST: localhost
+    OPENWEBUI_PORT: 3013
+    FLOWISE_HOST: localhost
+    FLOWISE_PORT: 3012
     DATAPLANE_HOST: localhost
     DATAPLANE_PORT: 3011
+    DATAPLANE_PUBLIC_PORT: 3011
     NODE_ENV: development
     PYTHONUNBUFFERED: 1
     PYTHONDONTWRITEBYTECODE: 1

package/lib/schema/external-datasource.schema.json

@@ -544,7 +544,7 @@
         "properties":{
            "rejectIf":{
               "type":"array",
-              "description":"List of conditions that cause a record to be rejected.",
+              "description":"List of conditions that cause a record to be rejected. For lessThan: missing field is treated as reject. For greaterThan: missing field is not rejected. See quality docs for operator semantics.",
               "items":{
                  "type":"object",
                  "required":[
@@ -659,6 +659,11 @@
               "default":true,
               "description":"Enable two-phase sync pattern. When true: validates metadata first (quality rules, comparison with DocumentRecords), then fetches binaries via CIP for changed/new documents. When false: fetches binaries directly without metadata validation phase (single-phase sync). Note: Files are never synced back to external systems (one-way sync only: external → dataplane)."
            },
+           "ingestAfterSync":{
+              "type":"boolean",
+              "default":false,
+              "description":"When true, chunk and embed each document after store during sync so vector search returns hits immediately. When false, ingestion runs later (e.g. Celery task or on approval). Set true for E2E tests that validate vector step."
+           },
            "binaryOperationRef":{
               "type":"string",
               "default":"get",
@@ -700,6 +705,11 @@
                  },
                  "notifications":{
                     "type":"object"
+                 },
+                 "ingestAfterSync":{
+                    "type":"boolean",
+                    "default":false,
+                    "description":"When true, chunk and embed each document after store during sync so vector search returns hits."
                  }
               },
               "additionalProperties":false

package/lib/schema/wizard-config.schema.json

@@ -20,11 +20,17 @@
     },
     "systemIdOrKey": {
       "type": "string",
-      "description": "Existing system ID or key (required when mode='add-datasource')",
+      "description": "Application/system key (e.g. hubspot-demo), not a datasource or entity key. Required when mode='add-datasource'. Must be the system key from the dataplane, not an entity key (e.g. 'companies').",
       "pattern": "^[a-z0-9-]+$",
       "minLength": 1,
       "maxLength": 50
     },
+    "systemDisplayName": {
+      "type": ["string", "null"],
+      "title": "Systemdisplayname",
+      "description": "System-level display name for the credential (e.g. 'Hubspot Demo'). When the OpenAPI title is entity-specific (e.g. 'Companies'), pass the system name here so authentication.displayName is system-level.",
+      "maxLength": 200
+    },
     "source": {
       "type": "object",
       "description": "Source configuration for the wizard",

package/lib/utils/app-config-resolver.js

@@ -49,4 +49,26 @@ function resolveApplicationConfigPath(appPath) {
   );
 }
 
-module.exports = { resolveApplicationConfigPath };
+const RBAC_NAMES = ['rbac.yaml', 'rbac.yml', 'rbac.json'];
+
+/**
+ * Resolves path to RBAC config file (rbac.yaml, rbac.yml, or rbac.json).
+ * Returns the first path that exists; no renames or migrations.
+ *
+ * @param {string} appPath - Absolute path to application directory
+ * @returns {string|null} Absolute path to RBAC file, or null if none exist
+ */
+function resolveRbacPath(appPath) {
+  if (!appPath || typeof appPath !== 'string') {
+    throw new Error('App path is required and must be a string');
+  }
+  for (const name of RBAC_NAMES) {
+    const candidate = path.join(appPath, name);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+module.exports = { resolveApplicationConfigPath, resolveRbacPath };

package/lib/utils/config-paths.js

@@ -56,30 +56,73 @@ async function setPathConfig(getConfigFn, saveConfigFn, key, value, errorMsg) {
   await saveConfigFn(config);
 }
 
+/**
+ * Clear a path config key (set to undefined so getPathConfig returns null).
+ * @param {Function} getConfigFn - Function to get config
+ * @param {Function} saveConfigFn - Function to save config
+ * @param {string} key - Configuration key
+ * @returns {Promise<void>}
+ */
+async function clearPathConfig(getConfigFn, saveConfigFn, key) {
+  const config = await getConfigFn();
+  config[key] = undefined;
+  await saveConfigFn(config);
+}
+
 function createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn) {
   return {
     async getAifabrixHomeOverride() {
       return getPathConfig(getConfigFn, 'aifabrix-home');
     },
     async setAifabrixHomeOverride(homePath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home', homePath, 'Home path is required and must be a string');
+      if (typeof homePath !== 'string') {
+        throw new Error('Home path is required and must be a string');
+      }
+      const trimmed = homePath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home', trimmed, 'Home path must be a non-empty string');
     },
     async getAifabrixSecretsPath() {
       return getPathConfig(getConfigFn, 'aifabrix-secrets');
     },
     async setAifabrixSecretsPath(secretsPath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets', secretsPath, 'Secrets path is required and must be a string');
+      if (typeof secretsPath !== 'string') {
+        throw new Error('Secrets path is required and must be a string');
+      }
+      const trimmed = secretsPath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets', trimmed, 'Secrets path must be a non-empty string');
     }
   };
 }
 
+/** Default env-config path when aifabrix-env-config is not set (builder schema). */
+function getDefaultEnvConfigPath() {
+  return path.join(__dirname, '..', 'schema', 'env-config.yaml');
+}
+
 function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
   return {
     async getAifabrixEnvConfigPath() {
-      return getPathConfig(getConfigFn, 'aifabrix-env-config');
+      const value = await getPathConfig(getConfigFn, 'aifabrix-env-config');
+      return value || getDefaultEnvConfigPath();
     },
     async setAifabrixEnvConfigPath(envConfigPath) {
-      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', envConfigPath, 'Env config path is required and must be a string');
+      if (typeof envConfigPath !== 'string') {
+        throw new Error('Env config path is required and must be a string');
+      }
+      const trimmed = envConfigPath.trim();
+      if (trimmed === '') {
+        await clearPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config');
+        return;
+      }
+      await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', trimmed, 'Env config path must be a non-empty string');
     },
     async getAifabrixBuilderDir() {
       const envConfigPath = await getPathConfig(getConfigFn, 'aifabrix-env-config');
@@ -214,6 +257,7 @@ module.exports = {
   getPathConfig,
   setPathConfig,
   createPathConfigFunctions,
+  getDefaultEnvConfigPath,
   SETTINGS_RESPONSE_KEYS
 };
 

package/lib/utils/credential-secrets-env.js

@@ -92,6 +92,17 @@ function kvPathInferred(segments) {
   return (namespace && pathVar) ? `kv://${namespace}/${pathVar}` : null;
 }
 
+/**
+ * Returns the path segment used in kv://<systemKey>/<segment> for a given security key.
+ * Uses the same derivation as env key → path (securityKeyToVar + varSegmentsToCamelCase).
+ * @param {string} securityKey - Security key (e.g. 'apiKey', 'clientId', 'clientSecret')
+ * @returns {string} Canonical path segment (e.g. 'apiKey', 'clientId')
+ */
+function getKvPathSegmentForSecurityKey(securityKey) {
+  if (!securityKey || typeof securityKey !== 'string') return '';
+  return varSegmentsToCamelCase([securityKeyToVar(securityKey)]);
+}
+
 /**
  * Converts KV_* env key to kv:// path in format kv://<system-key>/<variable>.
  * System-key uses hyphens (e.g. microsoft-teams); variable is camelCase (e.g. clientId).
@@ -220,7 +231,10 @@ function buildItemsFromEnv(envFilePath, secrets, itemsByKey) {
     const fromEnv = collectKvEnvVarsAsSecretItems(envMap);
     for (const { key, value } of fromEnv) {
       const resolved = resolveKvValue(secrets, value);
-      if (resolved !== null && resolved !== undefined && isValidKvPath(key)) itemsByKey.set(key, resolved);
+      // Skip placeholder: value that equals the kv path (e.g. from env.template) must not be pushed as the secret
+      if (resolved !== null && resolved !== undefined && isValidKvPath(key) && resolved.trim() !== key.trim()) {
+        itemsByKey.set(key, resolved);
+      }
     }
   } catch {
     // Best-effort: continue without .env items
@@ -349,6 +363,7 @@ module.exports = {
   collectKvRefsFromPayload,
   pushCredentialSecrets,
   kvEnvKeyToPath,
+  getKvPathSegmentForSecurityKey,
   systemKeyToKvPrefix,
   securityKeyToVar,
   isValidKvPath,

package/lib/utils/env-map.js

@@ -270,9 +270,13 @@ function calculateDockerPublicPorts(result, devIdNum, schemaBaseVars = {}) {
     // Match any variable ending with _PORT (e.g., MISO_PORT, KEYCLOAK_PORT, DB_PORT)
     if (/_PORT$/.test(key) && !/_PUBLIC_PORT$/.test(key)) {
       const publicPortKey = key.replace(/_PORT$/, '_PUBLIC_PORT');
-      // Use schema port when available so PUBLIC_PORT is canonical (e.g. 8082), not overridden (e.g. 8080)
-      const schemaPort = schemaBaseVars[key];
-      const sourceVal = schemaPort !== undefined && schemaPort !== null ? schemaPort : value;
+      // Prefer schema *_PUBLIC_PORT (e.g. KEYCLOAK_PUBLIC_PORT: 8082) so public port is canonical;
+      // fall back to schema *_PORT (e.g. KEYCLOAK_PORT: 8080) then merged value
+      const schemaPublic = schemaBaseVars[publicPortKey];
+      const schemaInternal = schemaBaseVars[key];
+      const sourceVal = schemaPublic !== undefined && schemaPublic !== null
+        ? schemaPublic
+        : (schemaInternal !== undefined && schemaInternal !== null ? schemaInternal : value);
       let portVal;
       if (typeof sourceVal === 'string') {
         portVal = parseInt(sourceVal, 10);

package/lib/utils/error-formatter.js

@@ -19,6 +19,8 @@ const PATTERN_DESCRIPTIONS = {
   '^[a-z-]+$': 'lowercase letters and hyphens only',
   '^[A-Z_][A-Z0-9_]*$': 'uppercase letters, numbers, and underscores (must start with letter or underscore)',
   '^[a-zA-Z0-9_-]+$': 'letters, numbers, hyphens, and underscores only',
+  '^[a-zA-Z0-9_]+$': 'letters, numbers, and underscores only',
+  '^[a-zA-Z0-9_.]+$': 'letters, numbers, underscores, and dots only',
   '^(http|https)://.*$': 'valid HTTP or HTTPS URL',
   '^/[a-z0-9/-]*$': 'URL path starting with / (lowercase letters, numbers, hyphens, slashes)'
 };
@@ -132,6 +134,35 @@ function createKeywordFormatters(field, error) {
  * @param {Object} error - Raw validation error from Ajv
  * @returns {string} Formatted error message
  */
+/**
+ * Formats oneOf/anyOf validation errors with actionable message
+ * @param {string} field - Field name
+ * @param {Object} error - AJV error (keyword oneOf or anyOf)
+ * @returns {string} Formatted error message
+ */
+function formatOneOfAnyOfError(field, error) {
+  const instancePath = (error.instancePath || '').replace(/^\//, '');
+  if (instancePath === 'capabilities') {
+    return `${field}: must be either an array of operation names (e.g. ["list","get"]) or an object with boolean flags (e.g. { "list": true }).`;
+  }
+  return `${field}: value does not match any allowed shape. Check type and required fields.`;
+}
+
+/**
+ * Formats const validation errors
+ * @param {string} field - Field name
+ * @param {Object} error - AJV error (keyword const)
+ * @returns {string} Formatted error message
+ */
+function formatConstError(field, error) {
+  const allowed = error.params?.allowedValue;
+  if (allowed !== undefined) {
+    const display = typeof allowed === 'string' ? `"${allowed}"` : String(allowed);
+    return `${field}: must be exactly ${display}`;
+  }
+  return `${field}: invalid value (constraint violation)`;
+}
+
 function formatSingleError(error) {
   const field = getFieldName(error);
 
@@ -142,6 +173,12 @@ function formatSingleError(error) {
   if (error.keyword === 'additionalProperties') {
     return formatAdditionalPropertiesError(field, error);
   }
+  if (error.keyword === 'oneOf' || error.keyword === 'anyOf') {
+    return formatOneOfAnyOfError(field, error);
+  }
+  if (error.keyword === 'const') {
+    return formatConstError(field, error);
+  }
 
   // Use object lookup for keyword-specific messages
   const formatters = createKeywordFormatters(field, error);

package/lib/utils/external-env-template.js

@@ -0,0 +1,180 @@
+/**
+ * Builds Handlebars context and generates env.template content for external systems.
+ * Single source for create, download, split, and repair so env.template structure is consistent.
+ *
+ * @fileoverview External system env.template generation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const Handlebars = require('handlebars');
+const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('./credential-secrets-env');
+
+/**
+ * Builds hint string from portalInput (options → enum, validation → min-max or pattern).
+ * @param {Object} portalInput - Portal input config (label, options, validation)
+ * @returns {string} Hint suffix for comment
+ */
+function buildPortalInputHint(portalInput) {
+  if (!portalInput || typeof portalInput !== 'object') return '';
+  const parts = [];
+  if (Array.isArray(portalInput.options) && portalInput.options.length > 0) {
+    parts.push(`enum ${portalInput.options.join(',')}`);
+  }
+  const v = portalInput.validation;
+  if (v && typeof v === 'object') {
+    if (typeof v.minLength === 'number' || typeof v.maxLength === 'number') {
+      parts.push('min-max');
+    } else if (typeof v.pattern === 'string' && v.pattern) {
+      parts.push('pattern');
+    }
+  }
+  return parts.length ? ` - ${parts.join(', ')}` : '';
+}
+
+/** Fallback security keys by auth method when authentication.security is absent. */
+const FALLBACK_SECURITY_BY_AUTH = {
+  oauth2: ['clientId', 'clientSecret'],
+  oauth: ['clientId', 'clientSecret'],
+  aad: ['clientId', 'clientSecret'],
+  apikey: ['apiKey'],
+  apiKey: ['apiKey'],
+  basic: ['username', 'password'],
+  queryParam: ['paramValue'],
+  oidc: [],
+  hmac: ['signingSecret'],
+  bearer: ['bearerToken'],
+  token: ['bearerToken'],
+  none: []
+};
+
+/**
+ * Builds authSecureVars array from system authentication.security (or fallback by auth type).
+ * @param {Object} system - System object with key and authentication
+ * @returns {Array<{name: string, value: string}>}
+ */
+function buildAuthSecureVarsFromSystem(system) {
+  const authSecureVars = [];
+  const systemKey = system?.key || 'external-system';
+  const prefix = systemKeyToKvPrefix(systemKey);
+  if (!prefix) return authSecureVars;
+  const security = system?.authentication?.security || system?.auth?.security;
+  const authMethod = (system?.authentication?.method || system?.authentication?.type ||
+    system?.auth?.method || system?.auth?.type || 'apikey').toLowerCase();
+  if (security && typeof security === 'object' && Object.keys(security).length > 0) {
+    for (const key of Object.keys(security)) {
+      const envName = `KV_${prefix}_${securityKeyToVar(key)}`;
+      const pathVal = kvEnvKeyToPath(envName, systemKey);
+      authSecureVars.push({ name: envName, value: pathVal || `kv://${systemKey}/${key}` });
+    }
+  } else {
+    const keys = FALLBACK_SECURITY_BY_AUTH[authMethod] || FALLBACK_SECURITY_BY_AUTH.apikey;
+    for (const key of keys) {
+      authSecureVars.push({
+        name: `KV_${prefix}_${securityKeyToVar(key)}`,
+        value: `kv://${systemKey}/${key}`
+      });
+    }
+  }
+  return authSecureVars;
+}
+
+/**
+ * Builds configuration array with name, value, comment from system.configuration.
+ * @param {Object} system - System object with configuration array
+ * @returns {Array<{name: string, value: string, comment: string}>}
+ */
+function buildConfigurationEntries(system) {
+  const configuration = [];
+  const configList = Array.isArray(system?.configuration) ? system.configuration : [];
+  for (const entry of configList) {
+    if (!entry || !entry.name) continue;
+    const label = entry.portalInput?.label || entry.name;
+    const hint = buildPortalInputHint(entry.portalInput || {});
+    let value = entry.value !== undefined && entry.value !== null ? String(entry.value) : '';
+    if (entry.location === 'keyvault' && value && !value.startsWith('kv://')) value = `kv://${value}`;
+    configuration.push({ name: entry.name, value, comment: `${label}${hint}` });
+  }
+  return configuration;
+}
+
+/**
+ * Builds template context from system object for env.template.hbs.
+ * @param {Object} system - Full system object (e.g. deployment.system or parsed system file)
+ * @returns {{ authMethod: string, authSecureVars: Array<{name: string, value: string}>, authNonSecureVarNames: string[], configuration: Array<{name: string, value: string, comment: string}> }}
+ */
+function buildExternalEnvTemplateContext(system) {
+  const authMethod = (system?.authentication?.method ||
+    system?.authentication?.type ||
+    system?.auth?.method ||
+    system?.auth?.type ||
+    'apikey').toLowerCase();
+  const authSecureVars = buildAuthSecureVarsFromSystem(system);
+  const authVars = system?.authentication?.variables || system?.auth?.variables || {};
+  const authNonSecureVarNames = Object.keys(authVars);
+  const configuration = buildConfigurationEntries(system);
+  return {
+    authMethod,
+    authSecureVars,
+    authNonSecureVarNames,
+    configuration
+  };
+}
+
+/** Inline fallback when env.template.hbs is missing or unreadable (e.g. CI path or bundled). */
+const DEFAULT_ENV_TEMPLATE_HBS = `# Environment variables for external system integration
+# Use kv:// (or aifabrix secret set) for sensitive values; plain values for non-sensitive configuration.
+#
+
+{{#if authMethod}}
+# Authentication
+# Type: {{authMethod}}
+{{#each authSecureVars}}
+{{name}}={{value}}
+{{/each}}
+{{#if authNonSecureVarNames}}
+# Non-secure (e.g. URLs): {{#each authNonSecureVarNames}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+
+{{/if}}
+{{#if configuration.length}}
+# Configuration
+{{#each configuration}}
+# {{comment}}
+{{name}}={{value}}
+{{/each}}
+{{/if}}
+`;
+
+/**
+ * Generates env.template content from system using the Handlebars template.
+ * @param {Object} system - Full system object (e.g. deployment.system or parsed system file)
+ * @returns {string} Rendered env.template content
+ */
+function generateExternalEnvTemplateContent(system) {
+  if (!system || typeof system !== 'object') {
+    return '# Environment variables for external system integration\n# Use kv:// (or aifabrix secret set) for sensitive values.\n\n';
+  }
+  let templateContent;
+  try {
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'external-system', 'env.template.hbs');
+    templateContent = fs.readFileSync(templatePath, 'utf8');
+  } catch (_) {
+    templateContent = undefined;
+  }
+  if (typeof templateContent !== 'string' || !templateContent.trim()) {
+    templateContent = DEFAULT_ENV_TEMPLATE_HBS;
+  }
+  const template = Handlebars.compile(templateContent);
+  const context = buildExternalEnvTemplateContext(system);
+  return template(context);
+}
+
+module.exports = {
+  buildExternalEnvTemplateContext,
+  generateExternalEnvTemplateContent
+};