@aifabrix/builder 2.39.3 → 2.40.2

package/lib/utils/health-check.js

@@ -231,6 +231,60 @@ function parseHealthResponse(data, statusCode) {
   }
 }
 
+function handleHealthResponse(res, data, debug, resolve) {
+  const isHealthy = parseHealthResponse(data, res.statusCode);
+  if (debug) {
+    const truncatedData = data.length > 200 ? data.substring(0, 200) + '...' : data;
+    logger.log(chalk.gray(`[DEBUG] Response body: ${truncatedData}`));
+    logger.log(chalk.gray(`[DEBUG] Health check result: ${isHealthy ? 'healthy' : 'unhealthy'}`));
+  }
+  resolve(isHealthy);
+}
+
+function doHealthCheckRequest(healthCheckUrl, debug, resolve, reject) {
+  try {
+    const urlObj = new URL(healthCheckUrl);
+    const options = {
+      hostname: urlObj.hostname,
+      port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+      path: urlObj.pathname + urlObj.search,
+      method: 'GET'
+    };
+    if (debug) {
+      logger.log(chalk.gray(`[DEBUG] Health check request: ${healthCheckUrl}`));
+      logger.log(chalk.gray(`[DEBUG] Request options: ${JSON.stringify(options, null, 2)}`));
+    }
+    // eslint-disable-next-line prefer-const
+    let timeoutId;
+    const req = http.request(options, (res) => {
+      clearTimeout(timeoutId);
+      let data = '';
+      if (debug) {
+        logger.log(chalk.gray(`[DEBUG] Response status code: ${res.statusCode}`));
+        logger.log(chalk.gray(`[DEBUG] Response headers: ${JSON.stringify(res.headers, null, 2)}`));
+      }
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => handleHealthResponse(res, data, debug, resolve));
+    });
+    timeoutId = setTimeout(() => {
+      if (debug) logger.log(chalk.gray('[DEBUG] Health check request timeout after 5 seconds'));
+      req.destroy();
+      resolve(false);
+    }, 5000);
+    req.on('error', (error) => {
+      clearTimeout(timeoutId);
+      if (debug) logger.log(chalk.gray(`[DEBUG] Health check request error: ${error.message}`));
+      resolve(false);
+    });
+    req.end();
+  } catch (error) {
+    if (debug) logger.log(chalk.gray(`[DEBUG] Health check exception: ${error.message}`));
+    reject(error);
+  }
+}
+
 /**
  * Checks health endpoint
  * @async
@@ -242,72 +296,7 @@ function parseHealthResponse(data, statusCode) {
  */
 async function checkHealthEndpoint(healthCheckUrl, debug = false) {
   return new Promise((resolve, reject) => {
-    try {
-      const urlObj = new URL(healthCheckUrl);
-      const options = {
-        hostname: urlObj.hostname,
-        port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
-        path: urlObj.pathname + urlObj.search,
-        method: 'GET'
-      };
-
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Health check request: ${healthCheckUrl}`));
-        logger.log(chalk.gray(`[DEBUG] Request options: ${JSON.stringify(options, null, 2)}`));
-      }
-
-      // Declare timeoutId before creating req so it can be used in callbacks
-      // eslint-disable-next-line prefer-const
-      let timeoutId;
-
-      const req = http.request(options, (res) => {
-        clearTimeout(timeoutId);
-        let data = '';
-        if (debug) {
-          logger.log(chalk.gray(`[DEBUG] Response status code: ${res.statusCode}`));
-          logger.log(chalk.gray(`[DEBUG] Response headers: ${JSON.stringify(res.headers, null, 2)}`));
-        }
-        res.on('data', (chunk) => {
-          data += chunk;
-        });
-        res.on('end', () => {
-          if (debug) {
-            const truncatedData = data.length > 200 ? data.substring(0, 200) + '...' : data;
-            logger.log(chalk.gray(`[DEBUG] Response body: ${truncatedData}`));
-          }
-          const isHealthy = parseHealthResponse(data, res.statusCode);
-          if (debug) {
-            logger.log(chalk.gray(`[DEBUG] Health check result: ${isHealthy ? 'healthy' : 'unhealthy'}`));
-          }
-          resolve(isHealthy);
-        });
-      });
-
-      // Set timeout for the request using setTimeout
-      timeoutId = setTimeout(() => {
-        if (debug) {
-          logger.log(chalk.gray('[DEBUG] Health check request timeout after 5 seconds'));
-        }
-        req.destroy();
-        resolve(false);
-      }, 5000);
-
-      req.on('error', (error) => {
-        clearTimeout(timeoutId);
-        if (debug) {
-          logger.log(chalk.gray(`[DEBUG] Health check request error: ${error.message}`));
-        }
-        resolve(false);
-      });
-
-      req.end();
-    } catch (error) {
-      if (debug) {
-        logger.log(chalk.gray(`[DEBUG] Health check exception: ${error.message}`));
-      }
-      // Re-throw exceptions (not just network errors)
-      reject(error);
-    }
+    doHealthCheckRequest(healthCheckUrl, debug, resolve, reject);
   });
 }
 

package/lib/utils/image-version.js

@@ -11,11 +11,9 @@
 
 const { exec } = require('child_process');
 const { promisify } = require('util');
-const fs = require('fs').promises;
-const fsSync = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
 const { getBuilderPath } = require('./paths');
+const { resolveApplicationConfigPath } = require('./app-config-resolver');
+const { loadConfigFile, writeConfigFile } = require('./config-format');
 const composeGenerator = require('./compose-generator');
 const containerHelpers = require('./app-run-containers');
 
@@ -86,7 +84,7 @@ function compareSemver(a, b) {
 
 /**
  * Resolves version for external app (app.version or externalIntegration.version)
- * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} variables - Parsed application config
  * @returns {string}
  */
 function resolveExternalVersion(variables) {
@@ -125,9 +123,9 @@ async function resolveRegularVersion(imageName, imageTag, templateVersion) {
  * Resolves version for an app: from image when image exists and template empty or smaller
  * @async
  * @param {string} appName - Application name
- * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} variables - Parsed application config
  * @param {Object} [options] - Options
- * @param {boolean} [options.updateBuilder] - When true, update builder/variables.yaml if fromImage
+ * @param {boolean} [options.updateBuilder] - When true, update builder application config if fromImage
  * @param {string} [options.builderPath] - Builder path (defaults to getBuilderPath(appName))
  * @returns {Promise<{ version: string, fromImage: boolean, updated: boolean }>}
  */
@@ -164,37 +162,30 @@ async function resolveVersionForApp(appName, variables, options = {}) {
   let updated = false;
   if (fromImage && options.updateBuilder) {
     const builderPath = options.builderPath || getBuilderPath(appName);
-    updated = await updateAppVersionInVariablesYaml(builderPath, version);
+    updated = updateAppVersionInVariablesYaml(builderPath, version);
   }
 
   return { version, fromImage, updated };
 }
 
 /**
- * Updates app.version in builder variables.yaml
- * @async
+ * Updates app.version in builder application config
  * @param {string} builderPath - Path to builder app directory
  * @param {string} version - Version to set
- * @returns {Promise<boolean>} True if file was updated
+ * @returns {boolean} True if file was updated
  */
-async function updateAppVersionInVariablesYaml(builderPath, version) {
+function updateAppVersionInVariablesYaml(builderPath, version) {
   if (!builderPath || !version || typeof version !== 'string') {
     return false;
   }
-  const variablesPath = path.join(builderPath, 'variables.yaml');
-  if (!fsSync.existsSync(variablesPath)) {
-    return false;
-  }
-
   try {
-    const content = await fs.readFile(variablesPath, 'utf8');
-    const parsed = yaml.load(content) || {};
+    const configPath = resolveApplicationConfigPath(builderPath);
+    const parsed = loadConfigFile(configPath) || {};
     if (!parsed.app) {
       parsed.app = {};
     }
     parsed.app.version = version;
-    const dumped = yaml.dump(parsed, { lineWidth: -1 });
-    await fs.writeFile(variablesPath, dumped, { mode: 0o644, encoding: 'utf8' });
+    writeConfigFile(configPath, parsed);
     return true;
   } catch {
     return false;

package/lib/utils/paths.js

@@ -178,6 +178,12 @@ function checkGlobalProjectRoot() {
     return null;
   }
 
+  // In test environment, allow temp dir as project root (Jest sets NODE_ENV=test / JEST_WORKER_ID)
+  const isTestEnv = process.env.NODE_ENV === 'test' || typeof process.env.JEST_WORKER_ID !== 'undefined';
+  if (isTestEnv) {
+    return globalRoot;
+  }
+
   // Verify that __dirname is actually within globalRoot
   const dirnameNormalized = path.resolve(__dirname);
   const globalRootNormalized = path.resolve(globalRoot);
@@ -371,27 +377,11 @@ function getDeployJsonPath(appName, appType, preferNew = false) {
   // If neither exists, return new naming (for generation)
   return newPath;
 }
-
-/**
- * Reads and parses variables.yaml file
- * @param {string} variablesPath - Path to variables.yaml file
- * @returns {Object|null} Parsed variables object or null if error
- */
-function readVariablesFile(variablesPath) {
-  try {
-    if (!fs.existsSync(variablesPath)) {
-      return null;
-    }
-    const content = fs.readFileSync(variablesPath, 'utf8');
-    return yaml.load(content);
-  } catch {
-    return null;
-  }
-}
-
+const { resolveApplicationConfigPath } = require('./app-config-resolver');
+const { loadConfigFile } = require('./config-format');
 /**
  * Checks if app type is external from variables object
- * @param {Object} variables - Parsed variables.yaml object
+ * @param {Object} variables - Parsed application config object
  * @returns {boolean} True if app type is external
  */
 function isExternalAppType(variables) {
@@ -399,20 +389,25 @@ function isExternalAppType(variables) {
 }
 
 /**
- * Checks integration folder for external app type
+ * Checks integration folder for any valid application config
  * @param {string} appName - Application name
- * @returns {Object|null} App type info or null if not found
+ * @returns {Object|null} App type info or null if no config found
  */
 function checkIntegrationFolder(appName) {
   const integrationPath = getIntegrationPath(appName);
-  const variablesPath = path.join(integrationPath, 'variables.yaml');
-  const variables = readVariablesFile(variablesPath);
-
-  if (variables && isExternalAppType(variables)) {
+  let variables;
+  try {
+    const configPath = resolveApplicationConfigPath(integrationPath);
+    variables = loadConfigFile(configPath);
+  } catch {
+    return null;
+  }
+  if (variables) {
+    const isExternal = isExternalAppType(variables);
     return {
-      isExternal: true,
+      isExternal,
       appPath: integrationPath,
-      appType: 'external',
+      appType: isExternal ? 'external' : 'regular',
       baseDir: 'integration'
     };
   }
@@ -422,13 +417,20 @@ function checkIntegrationFolder(appName) {
 /**
  * Checks builder folder for app type
  * @param {string} appName - Application name
- * @returns {Object} App type info
+ * @returns {Object|null} App type info or null if no config found
  */
 function checkBuilderFolder(appName) {
   const builderPath = getBuilderPath(appName);
-  const variablesPath = path.join(builderPath, 'variables.yaml');
-  const variables = readVariablesFile(variablesPath);
-
+  if (!fs.existsSync(builderPath)) {
+    return null;
+  }
+  let variables;
+  try {
+    const configPath = resolveApplicationConfigPath(builderPath);
+    variables = loadConfigFile(configPath);
+  } catch {
+    return null;
+  }
   if (variables) {
     const isExternal = isExternalAppType(variables);
     return {
@@ -438,51 +440,27 @@ function checkBuilderFolder(appName) {
       baseDir: 'builder'
     };
   }
-
-  // Default to regular app in builder folder
-  return {
-    isExternal: false,
-    appPath: builderPath,
-    appType: 'regular',
-    baseDir: 'builder'
-  };
+  return null;
 }
-
 /**
- * Detects if an app is external type by checking variables.yaml
- * Checks both integration/ and builder/ folders for backward compatibility
+ * Detects if an app is external type by checking application config.
+ * Resolution order: integration/ first, then builder/; if neither exists, throws.
+ * No CLI flag overrides this order.
  *
  * @param {string} appName - Application name
- * @param {Object} [options] - Detection options
- * @param {string} [options.type] - Forced application type (external)
+ * @param {Object} [options] - Detection options (reserved; options.type is ignored)
  * @returns {Promise<{isExternal: boolean, appPath: string, appType: string, baseDir?: string}>}
+ * @throws {Error} When app not found in integration/ or builder/
  */
-async function detectAppType(appName, options = {}) {
+async function detectAppType(appName, _options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-
-  if (options.type === 'external') {
-    const integrationPath = getIntegrationPath(appName);
-    if (!fs.existsSync(integrationPath)) {
-      throw new Error(`External system not found in integration/${appName}`);
-    }
-    return {
-      isExternal: true,
-      appPath: integrationPath,
-      appType: 'external',
-      baseDir: 'integration'
-    };
-  }
-
-  // Check integration folder first (new structure)
   const integrationResult = checkIntegrationFolder(appName);
-  if (integrationResult) {
-    return integrationResult;
-  }
-
-  // Check builder folder (backward compatibility)
-  return checkBuilderFolder(appName);
+  if (integrationResult) return integrationResult;
+  const builderResult = checkBuilderFolder(appName);
+  if (builderResult) return builderResult;
+  throw new Error(`App '${appName}' not found in integration/${appName} or builder/${appName}`);
 }
 module.exports = {
   getAifabrixHome,
@@ -494,6 +472,7 @@ module.exports = {
   getIntegrationPath,
   getBuilderPath,
   getDeployJsonPath,
+  resolveApplicationConfigPath,
   detectAppType,
   clearProjectRootCache
 };

package/lib/utils/port-resolver.js

@@ -1,7 +1,7 @@
 /**
  * AI Fabrix Builder - Centralized Port Resolution
  *
- * Single source of truth for resolving application port from variables.yaml.
+ * Single source of truth for resolving application port from application config.
  * Use getContainerPort for container/Docker/deployment/registration; use getLocalPort
  * for local .env and dev-id–adjusted host port.
  *
@@ -20,7 +20,7 @@ const yaml = require('js-yaml');
  * Precedence: build.containerPort → port → defaultPort.
  * Used for: Dockerfile, container .env PORT, compose, deployment, app register, variable-transformer, builders, secrets-utils.
  *
- * @param {Object} variables - Parsed variables.yaml (or subset with build, port)
+ * @param {Object} variables - Parsed application config (or subset with build, port)
  * @param {number} [defaultPort=3000] - Default when neither build.containerPort nor port is set
  * @returns {number} Resolved container port
  */
@@ -34,7 +34,7 @@ function getContainerPort(variables, defaultPort = 3000) {
  * Precedence: build.localPort (if number and > 0) → port → defaultPort.
  * Used for: env-copy, env-ports, and as base for getLocalPortFromPath (secrets-helpers).
  *
- * @param {Object} variables - Parsed variables.yaml
+ * @param {Object} variables - Parsed application config
  * @param {number} [defaultPort=3000] - Default when neither build.localPort nor port is set
  * @returns {number} Resolved local port
  */
@@ -50,7 +50,7 @@ function getLocalPort(variables, defaultPort = 3000) {
 /**
  * Load variables from path. Returns null if path missing, not found, or parse error.
  *
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {Object|null} Parsed variables or null
  */
 function loadVariablesFromPath(variablesPath) {
@@ -66,10 +66,10 @@ function loadVariablesFromPath(variablesPath) {
 }
 
 /**
- * Resolve container port from variables.yaml path.
+ * Resolve container port from application config path.
  * Returns null when file is missing or neither build.containerPort nor port is set (for chaining with other sources).
  *
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {number|null} Container port or null
  */
 function getContainerPortFromPath(variablesPath) {
@@ -82,11 +82,11 @@ function getContainerPortFromPath(variablesPath) {
 }
 
 /**
- * Resolve local port from variables.yaml path.
+ * Resolve local port from application config path.
  * Matches legacy getPortFromVariablesFile: build.localPort (if number and > 0) else variables.port or null.
  * Returns null when file is missing or neither is set (for calculateAppPort chain).
  *
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {number|null} Local port or null
  */
 function getLocalPortFromPath(variablesPath) {

package/lib/utils/schema-loader.js

@@ -290,6 +290,27 @@ function tryDetectionMethods(parsed, filePath) {
   return null;
 }
 
+/**
+ * Detects schema type from already-parsed content (works with YAML or JSON).
+ * Use this when the file was parsed via loadConfigFile or similar.
+ *
+ * @function detectSchemaTypeFromParsed
+ * @param {Object} parsed - Parsed config object (from YAML or JSON)
+ * @param {string} filePath - File path (used for filename-based detection)
+ * @returns {string} 'application' | 'external-system' | 'external-datasource'
+ *
+ * @example
+ * const parsed = yaml.load(content);
+ * const type = detectSchemaTypeFromParsed(parsed, '/path/to/application.yaml');
+ */
+function detectSchemaTypeFromParsed(parsed, filePath) {
+  if (!parsed || typeof parsed !== 'object') {
+    return 'application';
+  }
+  const detected = tryDetectionMethods(parsed, filePath);
+  return detected || 'application';
+}
+
 function detectSchemaType(filePath, content) {
   const parsed = readAndParseFileContent(filePath, content);
   const detectedType = tryDetectionMethods(parsed, filePath);
@@ -300,6 +321,7 @@ module.exports = {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
   detectSchemaType,
+  detectSchemaTypeFromParsed,
   resetValidators
 };
 

package/lib/utils/schema-resolver.js

@@ -11,43 +11,40 @@
 
 const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const { detectAppType } = require('./paths');
+const { resolveApplicationConfigPath } = require('./app-config-resolver');
+const { loadConfigFile } = require('./config-format');
 
 /**
- * Resolves schemaBasePath from application variables.yaml
+ * Resolves schemaBasePath from application config
  * Supports both absolute and relative paths
  *
  * @async
  * @function resolveSchemaBasePath
  * @param {string} appName - Application name
  * @returns {Promise<string>} Resolved absolute path to schema base directory
- * @throws {Error} If variables.yaml not found, externalIntegration missing, or path invalid
+ * @throws {Error} If application config not found, externalIntegration missing, or path invalid
  *
  * @example
  * const basePath = await resolveSchemaBasePath('myapp');
  * // Returns: '/path/to/builder/myapp/schemas'
  */
 /**
- * Loads and validates variables.yaml
+ * Loads and validates application config for schema resolution
  * @async
  * @function loadAndValidateVariablesForSchema
  * @param {string} appName - Application name
  * @param {string} appPath - Application path
- * @returns {Promise<Object>} Variables object
+ * @returns {Promise<{ variables: Object, configPath: string }>} Variables object and config path
  * @throws {Error} If file not found or invalid
  */
 async function loadAndValidateVariablesForSchema(appName, appPath) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const content = fs.readFileSync(variablesPath, 'utf8');
+  const configPath = resolveApplicationConfigPath(appPath);
   try {
-    return yaml.load(content);
+    const variables = loadConfigFile(configPath);
+    return { variables, configPath };
   } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
+    throw new Error(`Application config error: ${error.message}`);
   }
 }
 
@@ -61,7 +58,7 @@ async function loadAndValidateVariablesForSchema(appName, appPath) {
  */
 function validateExternalIntegrationBlock(variables, appName) {
   if (!variables.externalIntegration) {
-    throw new Error(`externalIntegration block not found in variables.yaml for app: ${appName}`);
+    throw new Error(`externalIntegration block not found in application config for app: ${appName}`);
   }
   if (!variables.externalIntegration.schemaBasePath) {
     throw new Error(`schemaBasePath not found in externalIntegration block for app: ${appName}`);
@@ -73,7 +70,7 @@ function validateExternalIntegrationBlock(variables, appName) {
  * Resolves and validates schema base path
  * @function resolveAndValidateSchemaPath
  * @param {string} schemaBasePath - Schema base path from config
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {string} Resolved and validated path
  * @throws {Error} If path is invalid
  */
@@ -95,17 +92,16 @@ function resolveAndValidateSchemaPath(schemaBasePath, variablesPath) {
   return resolvedPath;
 }
 
-async function resolveSchemaBasePath(appName) {
+async function resolveSchemaBasePath(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const { appPath } = await detectAppType(appName);
-  const variables = await loadAndValidateVariablesForSchema(appName, appPath);
+  const { appPath } = await detectAppType(appName, options);
+  const { variables, configPath } = await loadAndValidateVariablesForSchema(appName, appPath);
   const schemaBasePath = validateExternalIntegrationBlock(variables, appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
 
-  return resolveAndValidateSchemaPath(schemaBasePath, variablesPath);
+  return resolveAndValidateSchemaPath(schemaBasePath, configPath);
 }
 
 /**
@@ -180,7 +176,7 @@ function resolveDatasourceFiles(schemaBasePath, datasourceFiles) {
 }
 
 /**
- * Loads and validates variables.yaml
+ * Loads and validates application config
  * @async
  * @function loadAndValidateVariables
  * @param {string} appPath - Application path
@@ -188,33 +184,27 @@ function resolveDatasourceFiles(schemaBasePath, datasourceFiles) {
  * @throws {Error} If file not found or invalid
  */
 async function loadAndValidateVariables(appPath) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const content = fs.readFileSync(variablesPath, 'utf8');
+  const configPath = resolveApplicationConfigPath(appPath);
   try {
-    return yaml.load(content);
+    return loadConfigFile(configPath);
   } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
+    throw new Error(`Application config: ${error.message}`);
   }
 }
 
-async function resolveExternalFiles(appName) {
+async function resolveExternalFiles(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const { appPath } = await detectAppType(appName);
+  const { appPath } = await detectAppType(appName, options);
   const variables = await loadAndValidateVariables(appPath);
 
   if (!variables.externalIntegration) {
     return [];
   }
 
-  const schemaBasePath = await resolveSchemaBasePath(appName);
+  const schemaBasePath = await resolveSchemaBasePath(appName, options);
   const systemFiles = resolveSystemFiles(schemaBasePath, variables.externalIntegration.systems);
   const datasourceFiles = resolveDatasourceFiles(schemaBasePath, variables.externalIntegration.dataSources);
 

package/lib/utils/secrets-helpers.js

@@ -166,9 +166,9 @@ function getPortFromLocalEnv(localEnv) {
 }
 
 /**
- * Gets port from variables.yaml file (build.localPort if positive, else port). Uses port-resolver.
+ * Gets port from application config file (build.localPort if positive, else port). Uses port-resolver.
  * @function getPortFromVariablesFile
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @returns {number|null} Port value or null
  */
 function getPortFromVariablesFile(variablesPath) {
@@ -199,10 +199,10 @@ function applyDeveloperIdAdjustment(baseAppPort, devIdNum) {
 
 /**
  * Calculate application port following override chain and developer-id adjustment
- * Override chain: env-config.yaml → config.yaml → variables.yaml build.localPort → variables.yaml port
+ * Override chain: env-config.yaml → config.yaml → application.yaml build.localPort → application.yaml port
  * @async
  * @function calculateAppPort
- * @param {string} [variablesPath] - Path to variables.yaml
+ * @param {string} [variablesPath] - Path to application config
  * @param {Object} localEnv - Local environment config from env-config.yaml and config.yaml
  * @param {string} envContent - Environment content for fallback
  * @param {number} devIdNum - Developer ID number
@@ -212,7 +212,7 @@ async function calculateAppPort(variablesPath, localEnv, envContent, devIdNum) {
   // Start with env-config value
   let baseAppPort = getPortFromLocalEnv(localEnv);
 
-  // Override with variables.yaml → build.localPort (strongest)
+  // Override with application config → build.localPort (strongest)
   const variablesPort = getPortFromVariablesFile(variablesPath);
   if (variablesPort !== null) {
     baseAppPort = variablesPort;
@@ -249,11 +249,11 @@ function updateLocalhostUrls(content, baseAppPort, appPort) {
 /**
  * Adjust infra-related ports in resolved .env content for local environment
  * Only handles PORT variable (other ports handled by interpolation)
- * Follows flow: getEnvHosts() → config.yaml override → variables.yaml override → developer-id adjustment
+ * Follows flow: getEnvHosts() → config.yaml override → application config override → developer-id adjustment
  * @async
  * @function adjustLocalEnvPortsInContent
  * @param {string} envContent - Resolved .env content
- * @param {string} [variablesPath] - Path to variables.yaml (to read build.localPort)
+ * @param {string} [variablesPath] - Path to application config (to read build.localPort)
  * @returns {Promise<string>} Updated content with local ports
  */
 /**