@aifabrix/builder 2.22.2 → 2.31.1

package/lib/utils/env-copy.js

@@ -19,6 +19,163 @@ const { rewriteInfraEndpoints } = require('./env-endpoints');
 const { buildEnvVarMap } = require('./env-map');
 const { interpolateEnvVars } = require('./secrets-helpers');
 
+/**
+ * Read developer ID from config file synchronously
+ * @param {Object} config - Config object
+ * @returns {number|null} Developer ID or null if not found
+ */
+function readDeveloperIdFromConfig(config) {
+  const configPath = config && config.CONFIG_FILE ? config.CONFIG_FILE : null;
+  if (!configPath || !fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const cfgContent = fs.readFileSync(configPath, 'utf8');
+    const cfg = yaml.load(cfgContent) || {};
+    const raw = cfg['developer-id'];
+    if (typeof raw === 'number') {
+      return raw;
+    }
+    if (typeof raw === 'string' && /^[0-9]+$/.test(raw)) {
+      return parseInt(raw, 10);
+    }
+  } catch {
+    // ignore, will fallback to 0
+  }
+
+  return null;
+}
+
+/**
+ * Resolve output path for env file
+ * @param {string} rawOutputPath - Raw output path from variables.yaml
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {string} Resolved output path
+ */
+function resolveEnvOutputPath(rawOutputPath, variablesPath) {
+  let outputPath;
+  if (path.isAbsolute(rawOutputPath)) {
+    outputPath = rawOutputPath;
+  } else {
+    const variablesDir = path.dirname(variablesPath);
+    outputPath = path.resolve(variablesDir, rawOutputPath);
+  }
+  if (!outputPath.endsWith('.env')) {
+    if (fs.existsSync(outputPath) && fs.statSync(outputPath).isDirectory()) {
+      outputPath = path.join(outputPath, '.env');
+    } else {
+      outputPath = path.join(outputPath, '.env');
+    }
+  }
+  return outputPath;
+}
+
+/**
+ * Calculate developer-specific app port
+ * @param {number} baseAppPort - Base application port
+ * @returns {number} Developer-specific app port
+ */
+function calculateDevAppPort(baseAppPort) {
+  const devIdRaw = process.env.AIFABRIX_DEVELOPERID;
+  let devIdNum = Number.isFinite(parseInt(devIdRaw, 10)) ? parseInt(devIdRaw, 10) : null;
+  try {
+    if (devIdNum === null) {
+      devIdNum = readDeveloperIdFromConfig(config) || 0;
+    }
+  } catch {
+    devIdNum = 0;
+  }
+  return devIdNum === 0 ? baseAppPort : (baseAppPort + (devIdNum * 100));
+}
+
+/**
+ * Update PORT in env content
+ * @param {string} envContent - Environment file content
+ * @param {number} appPort - Application port
+ * @returns {string} Updated env content
+ */
+function updatePortInEnv(envContent, appPort) {
+  if (/^PORT\s*=.*$/m.test(envContent)) {
+    return envContent.replace(/^PORT\s*=\s*.*$/m, `PORT=${appPort}`);
+  }
+  return `${envContent}\nPORT=${appPort}\n`;
+}
+
+/**
+ * Update localhost URLs in env content
+ * @param {string} envContent - Environment file content
+ * @param {number} baseAppPort - Base application port
+ * @param {number} appPort - Developer-specific application port
+ * @returns {string} Updated env content
+ */
+function updateLocalhostUrls(envContent, baseAppPort, appPort) {
+  const localhostUrlPattern = /(https?:\/\/localhost:)(\d+)(\b[^ \n]*)?/g;
+  return envContent.replace(localhostUrlPattern, (match, prefix, portNum, rest = '') => {
+    const num = parseInt(portNum, 10);
+    if (num === baseAppPort) {
+      return `${prefix}${appPort}${rest || ''}`;
+    }
+    return match;
+  });
+}
+
+/**
+ * Extract env vars from content for interpolation
+ * @param {string} envContent - Environment file content
+ * @param {Object} envVars - Existing env vars map
+ * @returns {Object} Updated env vars map
+ */
+function extractEnvVarsFromContent(envContent, envVars) {
+  const redisHostMatch = envContent.match(/^REDIS_HOST\s*=\s*([^\r\n$]+)/m);
+  const redisPortMatch = envContent.match(/^REDIS_PORT\s*=\s*([^\r\n$]+)/m);
+  const dbHostMatch = envContent.match(/^DB_HOST\s*=\s*([^\r\n$]+)/m);
+  const dbPortMatch = envContent.match(/^DB_PORT\s*=\s*([^\r\n$]+)/m);
+  if (redisHostMatch && redisHostMatch[1] && !redisHostMatch[1].includes('${')) {
+    envVars.REDIS_HOST = redisHostMatch[1].trim();
+  }
+  if (redisPortMatch && redisPortMatch[1] && !redisPortMatch[1].includes('${')) {
+    envVars.REDIS_PORT = redisPortMatch[1].trim();
+  }
+  if (dbHostMatch && dbHostMatch[1] && !dbHostMatch[1].includes('${')) {
+    envVars.DB_HOST = dbHostMatch[1].trim();
+  }
+  if (dbPortMatch && dbPortMatch[1] && !dbPortMatch[1].includes('${')) {
+    envVars.DB_PORT = dbPortMatch[1].trim();
+  }
+  return envVars;
+}
+
+/**
+ * Patch env content for local development
+ * @async
+ * @param {string} envContent - Original env content
+ * @param {Object} variables - Variables from variables.yaml
+ * @returns {Promise<string>} Patched env content
+ */
+async function patchEnvContentForLocal(envContent, variables) {
+  const baseAppPort = variables.build?.localPort || variables.port || 3000;
+  const appPort = calculateDevAppPort(baseAppPort);
+  const devIdNum = readDeveloperIdFromConfig(config) || 0;
+  const infraPorts = devConfig.getDevPorts(devIdNum);
+
+  // Update PORT
+  envContent = updatePortInEnv(envContent, appPort);
+
+  // Update localhost URLs
+  envContent = updateLocalhostUrls(envContent, baseAppPort, appPort);
+
+  // Rewrite infra endpoints
+  envContent = await rewriteInfraEndpoints(envContent, 'local', infraPorts);
+
+  // Interpolate ${VAR} references
+  const envVars = await buildEnvVarMap('local', null, devIdNum);
+  const updatedEnvVars = extractEnvVarsFromContent(envContent, envVars);
+  envContent = interpolateEnvVars(envContent, updatedEnvVars);
+
+  return envContent;
+}
+
 /**
  * Process and optionally copy env file to envOutputPath if configured
  * Regenerates .env file with env=local for local development (apps/.env)
@@ -38,113 +195,25 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
   if (!variables?.build?.envOutputPath || variables.build.envOutputPath === null) {
     return;
   }
-  // Resolve output path: absolute stays as-is; relative is resolved against variables.yaml directory
-  const rawOutputPath = variables.build.envOutputPath;
-  let outputPath;
-  if (path.isAbsolute(rawOutputPath)) {
-    outputPath = rawOutputPath;
-  } else {
-    const variablesDir = path.dirname(variablesPath);
-    outputPath = path.resolve(variablesDir, rawOutputPath);
-  }
-  if (!outputPath.endsWith('.env')) {
-    if (fs.existsSync(outputPath) && fs.statSync(outputPath).isDirectory()) {
-      outputPath = path.join(outputPath, '.env');
-    } else {
-      outputPath = path.join(outputPath, '.env');
-    }
-  }
+
+  // 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
-  // This ensures all variables use localhost instead of docker service names
   if (appName) {
     const { generateEnvContent } = require('../secrets');
-    // Generate local .env content (without writing to builder/.env to avoid overwriting docker version)
     const localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
-    // Write to output path
     fs.writeFileSync(outputPath, localEnvContent, { mode: 0o600 });
     logger.log(chalk.green(`✓ Generated local .env at: ${variables.build.envOutputPath}`));
   } else {
     // Fallback: if appName not provided, use old patching approach
-    let envContent = fs.readFileSync(envPath, 'utf8');
-    // Determine base app port and compute developer-specific app port
-    const baseAppPort = variables.build?.localPort || variables.port || 3000;
-    const devIdRaw = process.env.AIFABRIX_DEVELOPERID;
-    // Best effort: parse from env first, otherwise rely on config (may throw if async, so guarded below)
-    let devIdNum = Number.isFinite(parseInt(devIdRaw, 10)) ? parseInt(devIdRaw, 10) : null;
-    try {
-      if (devIdNum === null) {
-        // Try to read developer-id from config file synchronously if present
-        const configPath = config && config.CONFIG_FILE ? config.CONFIG_FILE : null;
-        if (configPath && fs.existsSync(configPath)) {
-          try {
-            const cfgContent = fs.readFileSync(configPath, 'utf8');
-            const cfg = yaml.load(cfgContent) || {};
-            const raw = cfg['developer-id'];
-            if (typeof raw === 'number') {
-              devIdNum = raw;
-            } else if (typeof raw === 'string' && /^[0-9]+$/.test(raw)) {
-              devIdNum = parseInt(raw, 10);
-            }
-          } catch {
-            // ignore, will fallback to 0
-          }
-        }
-        if (devIdNum === null || Number.isNaN(devIdNum)) {
-          devIdNum = 0;
-        }
-      }
-    } catch {
-      devIdNum = 0;
-    }
-    const appPort = devIdNum === 0 ? baseAppPort : (baseAppPort + (devIdNum * 100));
-    const infraPorts = devConfig.getDevPorts(devIdNum);
-
-    // Update PORT (replace or append)
-    if (/^PORT\s*=.*$/m.test(envContent)) {
-      envContent = envContent.replace(/^PORT\s*=\s*.*$/m, `PORT=${appPort}`);
-    } else {
-      envContent = `${envContent}\nPORT=${appPort}\n`;
-    }
-
-    // Update localhost URLs that point to the base app port to the dev-specific app port
-    const localhostUrlPattern = /(https?:\/\/localhost:)(\d+)(\b[^ \n]*)?/g;
-    envContent = envContent.replace(localhostUrlPattern, (match, prefix, portNum, rest = '') => {
-      const num = parseInt(portNum, 10);
-      if (num === baseAppPort) {
-        return `${prefix}${appPort}${rest || ''}`;
-      }
-      return match;
-    });
-    // Rewrite infra endpoints using env-config mapping for local context
-    envContent = await rewriteInfraEndpoints(envContent, 'local', infraPorts);
-    // Interpolate ${VAR} references created by rewriteInfraEndpoints
-    // Extract actual values from updated content to use for interpolation
-    const envVars = await buildEnvVarMap('local', null, devIdNum);
-    // Extract REDIS_HOST, REDIS_PORT, DB_HOST, DB_PORT from updated content if present
-    // Only extract if the value doesn't contain ${VAR} references (to avoid circular interpolation)
-    const redisHostMatch = envContent.match(/^REDIS_HOST\s*=\s*([^\r\n$]+)/m);
-    const redisPortMatch = envContent.match(/^REDIS_PORT\s*=\s*([^\r\n$]+)/m);
-    const dbHostMatch = envContent.match(/^DB_HOST\s*=\s*([^\r\n$]+)/m);
-    const dbPortMatch = envContent.match(/^DB_PORT\s*=\s*([^\r\n$]+)/m);
-    if (redisHostMatch && redisHostMatch[1] && !redisHostMatch[1].includes('${')) {
-      envVars.REDIS_HOST = redisHostMatch[1].trim();
-    }
-    if (redisPortMatch && redisPortMatch[1] && !redisPortMatch[1].includes('${')) {
-      envVars.REDIS_PORT = redisPortMatch[1].trim();
-    }
-    if (dbHostMatch && dbHostMatch[1] && !dbHostMatch[1].includes('${')) {
-      envVars.DB_HOST = dbHostMatch[1].trim();
-    }
-    if (dbPortMatch && dbPortMatch[1] && !dbPortMatch[1].includes('${')) {
-      envVars.DB_PORT = dbPortMatch[1].trim();
-    }
-    envContent = interpolateEnvVars(envContent, envVars);
-    fs.writeFileSync(outputPath, envContent, { mode: 0o600 });
+    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}`));
   }
 }

package/lib/utils/env-map.js

@@ -15,70 +15,147 @@ const { loadEnvConfig } = require('./env-config-loader');
 const config = require('../config');
 
 /**
- * Build environment variable map for interpolation based on env-config.yaml
- * - Supports values like "host:port" by splitting into *_HOST (host) and *_PORT (port)
- * - 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
+ * Load base environment variables from env-config.yaml
  * @async
- * @function buildEnvVarMap
+ * @function loadBaseVars
  * @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.
- * @returns {Promise<Object>} Map of variables for interpolation
+ * @returns {Promise<Object>} Base environment variables
  */
-async function buildEnvVarMap(context, osModule = null, developerId = null) {
-  // Load env-config (base + user override if configured)
-  let baseVars = {};
+async function loadBaseVars(context) {
   try {
     const envCfg = await loadEnvConfig();
     const envs = envCfg && envCfg.environments ? envCfg.environments : {};
-    baseVars = { ...(envs[context] || {}) };
+    return { ...(envs[context] || {}) };
   } catch {
-    baseVars = {};
+    return {};
   }
+}
 
-  // Get os module - use provided one or require it
-  const os = osModule || require('os');
-
-  // Merge overrides from ~/.aifabrix/config.yaml
-  let overrideVars = {};
+/**
+ * Load override variables from ~/.aifabrix/config.yaml
+ * @function loadOverrideVars
+ * @param {'docker'|'local'} context - Environment context
+ * @param {Object} os - OS module instance
+ * @returns {Object} Override environment variables
+ */
+function loadOverrideVars(context, os) {
   try {
     const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
     if (fs.existsSync(cfgPath)) {
       const cfgContent = fs.readFileSync(cfgPath, 'utf8');
       const cfg = yaml.load(cfgContent) || {};
       if (cfg && cfg.environments && cfg.environments[context]) {
-        overrideVars = { ...cfg.environments[context] };
+        return { ...cfg.environments[context] };
       }
     }
   } catch {
     // ignore overrides on error
   }
+  return {};
+}
 
-  // Apply aifabrix-localhost override for local hostnames
-  let localhostOverride = null;
-  if (context === 'local') {
-    try {
-      const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
-      if (fs.existsSync(cfgPath)) {
-        const cfgContent = fs.readFileSync(cfgPath, 'utf8');
-        const cfg = yaml.load(cfgContent) || {};
-        if (typeof cfg['aifabrix-localhost'] === 'string' && cfg['aifabrix-localhost'].trim().length > 0) {
-          localhostOverride = cfg['aifabrix-localhost'].trim();
-        }
+/**
+ * Get localhost override value from config
+ * @function getLocalhostOverride
+ * @param {Object} os - OS module instance
+ * @returns {string|null} Localhost override value or null
+ */
+function getLocalhostOverride(os) {
+  try {
+    const cfgPath = path.join(os.homedir(), '.aifabrix', 'config.yaml');
+    if (fs.existsSync(cfgPath)) {
+      const cfgContent = fs.readFileSync(cfgPath, 'utf8');
+      const cfg = yaml.load(cfgContent) || {};
+      if (typeof cfg['aifabrix-localhost'] === 'string' && cfg['aifabrix-localhost'].trim().length > 0) {
+        return cfg['aifabrix-localhost'].trim();
       }
-    } catch {
-      // ignore
     }
+  } catch {
+    // ignore
   }
+  return null;
+}
 
-  const merged = { ...baseVars, ...overrideVars };
+/**
+ * Get host value with localhost override applied if needed
+ * @function getHostValue
+ * @param {string} host - Original host value
+ * @param {'docker'|'local'} context - Environment context
+ * @param {string|null} localhostOverride - Localhost override value
+ * @returns {string} Host value with override applied
+ */
+function getHostValue(host, context, localhostOverride) {
+  if (context === 'local' && host === 'localhost' && localhostOverride) {
+    return localhostOverride;
+  }
+  return host;
+}
+
+/**
+ * Handle host:port value for key ending with _HOST
+ * @function handleHostPortWithHostSuffix
+ * @param {Object} result - Result object to update
+ * @param {string} key - Environment variable key
+ * @param {string} host - Host value
+ * @param {string} port - Port value
+ * @param {Object} options - Normalization options
+ * @param {'docker'|'local'} options.context - Environment context
+ * @param {string|null} options.localhostOverride - Localhost override value
+ */
+function handleHostPortWithHostSuffix(result, key, host, port, options) {
+  const root = key.replace(/_HOST$/, '');
+  const hostValue = getHostValue(host, options.context, options.localhostOverride);
+  result[key] = hostValue;
+  result[`${root}_PORT`] = port;
+}
 
-  // Normalize map: if VAR value is "host:port" and VAR ends with "_HOST",
-  // expose VAR as host only and also provide "<ROOT>_PORT"
-  // If VAR value is "host:port" but VAR doesn't end with "_HOST", still split to VAR_HOST/VAR_PORT
+/**
+ * Handle host:port value for generic key
+ * @function handleHostPortGeneric
+ * @param {Object} result - Result object to update
+ * @param {string} key - Environment variable key
+ * @param {string} host - Host value
+ * @param {string} port - Port value
+ * @param {Object} options - Normalization options
+ * @param {'docker'|'local'} options.context - Environment context
+ * @param {string|null} options.localhostOverride - Localhost override value
+ */
+function handleHostPortGeneric(result, key, host, port, options) {
+  const hostValue = getHostValue(host, options.context, options.localhostOverride);
+  result[`${key}_HOST`] = hostValue;
+  result[`${key}_PORT`] = port;
+  result[key] = hostValue;
+}
+
+/**
+ * Handle plain value (non-host:port)
+ * @function handlePlainValue
+ * @param {Object} result - Result object to update
+ * @param {string} key - Environment variable key
+ * @param {string} rawVal - Raw value
+ * @param {Object} options - Normalization options
+ * @param {'docker'|'local'} options.context - Environment context
+ * @param {string|null} options.localhostOverride - Localhost override value
+ */
+function handlePlainValue(result, key, rawVal, options) {
+  let val = rawVal;
+  if (options.context === 'local' && /_HOST$/.test(key) && rawVal === 'localhost' && options.localhostOverride) {
+    val = options.localhostOverride;
+  }
+  result[key] = val;
+}
+
+/**
+ * Normalize environment variable map by splitting host:port values
+ * @function normalizeEnvVars
+ * @param {Object} merged - Merged environment variables
+ * @param {'docker'|'local'} context - Environment context
+ * @param {string|null} localhostOverride - Localhost override value
+ * @returns {Object} Normalized environment variables
+ */
+function normalizeEnvVars(merged, context, localhostOverride) {
   const result = {};
+  const options = { context, localhostOverride };
   for (const [key, rawVal] of Object.entries(merged)) {
     if (typeof rawVal !== 'string') {
       result[key] = rawVal;
@@ -89,70 +166,133 @@ async function buildEnvVarMap(context, osModule = null, developerId = null) {
       const host = hostPortMatch[1];
       const port = hostPortMatch[2];
       if (/_HOST$/.test(key)) {
-        // Example: DB_HOST: "postgres:5432" -> DB_HOST="postgres", DB_PORT="5432"
-        const root = key.replace(/_HOST$/, '');
-        const hostValue = context === 'local' && host === 'localhost' && localhostOverride ? localhostOverride : host;
-        result[key] = hostValue;
-        result[`${root}_PORT`] = port;
+        handleHostPortWithHostSuffix(result, key, host, port, options);
       } else {
-        // Generic key with host:port -> expose KEY_HOST and KEY_PORT, and keep KEY as host
-        const hostValue = context === 'local' && host === 'localhost' && localhostOverride ? localhostOverride : host;
-        result[`${key}_HOST`] = hostValue;
-        result[`${key}_PORT`] = port;
-        result[key] = hostValue;
+        handleHostPortGeneric(result, key, host, port, options);
       }
     } else {
-      // Plain value
-      let val = rawVal;
-      if (context === 'local' && /_HOST$/.test(key) && rawVal === 'localhost' && localhostOverride) {
-        val = localhostOverride;
-      }
-      result[key] = val;
+      handlePlainValue(result, key, rawVal, options);
     }
   }
+  return result;
+}
 
-  // Apply developer-id adjustment to port variables for local context
-  if (context === 'local') {
-    let devIdNum = 0;
-    if (developerId !== null && developerId !== undefined) {
-      const parsed = typeof developerId === 'number' ? developerId : parseInt(developerId, 10);
+/**
+ * Get developer ID number from parameter or config
+ * @async
+ * @function getDeveloperIdNumber
+ * @param {number|null} developerId - Optional developer ID parameter
+ * @returns {Promise<number>} Developer ID number (0 if not available)
+ */
+async function getDeveloperIdNumber(developerId) {
+  if (developerId !== null && developerId !== undefined) {
+    const parsed = typeof developerId === 'number' ? developerId : parseInt(developerId, 10);
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+  try {
+    const devId = await config.getDeveloperId();
+    if (devId !== null && devId !== undefined) {
+      const parsed = parseInt(devId, 10);
       if (!Number.isNaN(parsed)) {
-        devIdNum = parsed;
+        return parsed;
       }
-    } else {
-      // Get developer-id from config if not provided
-      try {
-        const devId = await config.getDeveloperId();
-        if (devId !== null && devId !== undefined) {
-          const parsed = parseInt(devId, 10);
-          if (!Number.isNaN(parsed)) {
-            devIdNum = parsed;
-          }
-        }
-      } catch {
-        // ignore, will use 0
+    }
+  } catch {
+    // ignore, will use 0
+  }
+  return 0;
+}
+
+/**
+ * Apply developer-id adjustment to port variables for local context
+ * @function applyLocalPortAdjustment
+ * @param {Object} result - Environment variable map
+ * @param {number} devIdNum - Developer ID number
+ */
+function applyLocalPortAdjustment(result, devIdNum) {
+  if (devIdNum === 0) {
+    return;
+  }
+  for (const [key, value] of Object.entries(result)) {
+    if (/_PORT$/.test(key)) {
+      let portVal;
+      if (typeof value === 'string') {
+        portVal = parseInt(value, 10);
+      } else if (typeof value === 'number') {
+        portVal = value;
+      } else {
+        continue;
+      }
+      if (!Number.isNaN(portVal)) {
+        result[key] = String(portVal + (devIdNum * 100));
       }
     }
+  }
+}
 
-    // Apply adjustment to all *_PORT variables
-    if (devIdNum !== 0) {
-      for (const [key, value] of Object.entries(result)) {
-        if (/_PORT$/.test(key)) {
-          let portVal;
-          if (typeof value === 'string') {
-            portVal = parseInt(value, 10);
-          } else if (typeof value === 'number') {
-            portVal = value;
-          } else {
-            continue;
-          }
-          if (!Number.isNaN(portVal)) {
-            result[key] = String(portVal + (devIdNum * 100));
-          }
+/**
+ * Calculate public ports for docker context
+ * @function calculateDockerPublicPorts
+ * @param {Object} result - Environment variable map
+ * @param {number} devIdNum - Developer ID number
+ */
+function calculateDockerPublicPorts(result, devIdNum) {
+  if (devIdNum <= 0) {
+    return;
+  }
+  for (const [key, value] of Object.entries(result)) {
+    // 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');
+      // Skip if public port already exists (allow manual override)
+      if (result[publicPortKey] === undefined) {
+        let portVal;
+        if (typeof value === 'string') {
+          portVal = parseInt(value, 10);
+        } else if (typeof value === 'number') {
+          portVal = value;
+        } else {
+          continue;
+        }
+        if (!Number.isNaN(portVal)) {
+          result[publicPortKey] = String(portVal + (devIdNum * 100));
         }
       }
     }
   }
+}
+
+/**
+ * Build environment variable map for interpolation based on env-config.yaml
+ * - Supports values like "host:port" by splitting into *_HOST (host) and *_PORT (port)
+ * - 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)
+ * @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.
+ * @returns {Promise<Object>} Map of variables for interpolation
+ */
+async function buildEnvVarMap(context, osModule = null, developerId = 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 result = normalizeEnvVars(merged, context, localhostOverride);
+
+  if (context === 'local') {
+    const devIdNum = await getDeveloperIdNumber(developerId);
+    applyLocalPortAdjustment(result, devIdNum);
+  } else if (context === 'docker') {
+    const devIdNum = await getDeveloperIdNumber(developerId);
+    calculateDockerPublicPorts(result, devIdNum);
+  }
 
   return result;
 }

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

@@ -63,4 +63,3 @@ function formatNetworkError(errorMessage, errorData) {
 module.exports = {
   formatNetworkError
 };
-