@aifabrix/builder 2.39.3 → 2.40.0

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

@@ -0,0 +1,52 @@
+/**
+ * Application config path resolution
+ *
+ * Single entry point for resolving path to application config file
+ * (application.yaml, application.json, or legacy variables.yaml).
+ *
+ * @fileoverview Resolve application config file path with legacy migration
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolves path to application config file (application.yaml, application.json, or legacy variables.yaml).
+ * If only variables.yaml exists, renames it to application.yaml and returns the new path.
+ *
+ * @param {string} appPath - Absolute path to application directory
+ * @returns {string} Absolute path to application config file
+ * @throws {Error} If no config file found
+ */
+function resolveApplicationConfigPath(appPath) {
+  if (!appPath || typeof appPath !== 'string') {
+    throw new Error('App path is required and must be a string');
+  }
+  const applicationYaml = path.join(appPath, 'application.yaml');
+  const applicationYml = path.join(appPath, 'application.yml');
+  const applicationJson = path.join(appPath, 'application.json');
+  const variablesYaml = path.join(appPath, 'variables.yaml');
+
+  if (fs.existsSync(applicationYaml)) {
+    return applicationYaml;
+  }
+  if (fs.existsSync(applicationYml)) {
+    return applicationYml;
+  }
+  if (fs.existsSync(applicationJson)) {
+    return applicationJson;
+  }
+  if (fs.existsSync(variablesYaml)) {
+    fs.renameSync(variablesYaml, applicationYaml);
+    return applicationYaml;
+  }
+  throw new Error(
+    `Application config not found in ${appPath}. Expected application.yaml, application.yml, application.json, or variables.yaml.`
+  );
+}
+
+module.exports = { resolveApplicationConfigPath };

package/lib/utils/app-register-api.js

@@ -39,7 +39,7 @@ function handleRegistrationError(response, apiUrl, registrationData) {
     logger.error(chalk.gray('\nRequest payload:'));
     logger.error(chalk.gray(JSON.stringify(registrationData, null, 2)));
     logger.error('');
-    logger.error(chalk.gray('Check your variables.yaml file and ensure all required fields are correctly set.'));
+    logger.error(chalk.gray('Check your application.yaml file and ensure all required fields are correctly set.'));
   }
 
   process.exit(1);

package/lib/utils/app-register-auth.js

@@ -82,7 +82,7 @@ async function findDeviceTokenFromConfig(deviceConfig, attemptedUrls) {
 /**
  * Check if user is authenticated and get token
  * @async
- * @param {string} [controllerUrl] - Optional controller URL from variables.yaml or --controller flag
+ * @param {string} [controllerUrl] - Optional controller URL from application.yaml or --controller flag
  * @param {string} [environment] - Optional environment key
  * @returns {Promise<{apiUrl: string, token: string, controllerUrl: string}>} Configuration with API URL, token, and controller URL
  */

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

@@ -8,37 +8,35 @@
  * @version 2.0.0
  */
 
-const fs = require('fs').promises;
 const path = require('path');
 const chalk = require('chalk');
-const yaml = require('js-yaml');
 const logger = require('./logger');
-const { detectAppType } = require('./paths');
+const { detectAppType, resolveApplicationConfigPath } = require('./paths');
+const { loadConfigFile } = require('./config-format');
 const { getContainerPort, getLocalPort } = require('./port-resolver');
 
 // createApp is imported dynamically in createMinimalAppIfNeeded to handle test mocking
 
 /**
- * Load variables.yaml file for an application
+ * Load application config for an application (application.yaml, application.json, or legacy).
  * @async
  * @param {string} appKey - Application key
  * @returns {Promise<{variables: Object, created: boolean}>} Variables and creation flag
  */
 async function loadVariablesYaml(appKey) {
-  // Detect app type and get correct path (integration or builder)
   const { appPath } = await detectAppType(appKey);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
   try {
-    const variablesContent = await fs.readFile(variablesPath, 'utf-8');
-    return { variables: yaml.load(variablesContent), created: false };
+    const configPath = resolveApplicationConfigPath(appPath);
+    const variables = loadConfigFile(configPath);
+    return { variables, created: false };
   } catch (error) {
-    if (error.code === 'ENOENT') {
-      logger.log(chalk.yellow(`⚠️  variables.yaml not found for ${appKey}`));
+    const isNotFound = error.code === 'ENOENT' || (error.message && error.message.includes('not found'));
+    if (isNotFound) {
+      logger.log(chalk.yellow(`⚠️  Application config not found for ${appKey}`));
       logger.log(chalk.yellow('📝 Creating minimal configuration...\n'));
       return { variables: null, created: true };
     }
-    throw new Error(`Failed to read variables.yaml: ${error.message}`);
+    throw new Error(`Failed to read application config: ${error.message}`);
   }
 }
 
@@ -65,21 +63,19 @@ async function createMinimalAppIfNeeded(appKey, options) {
     authentication: false
   });
 
-  // Detect app type and get correct path (integration or builder)
   const appTypeResult = await detectAppType(appKey);
   if (!appTypeResult || !appTypeResult.appPath) {
     throw new Error('Failed to detect app type after creation');
   }
   const { appPath } = appTypeResult;
-  const variablesPath = path.join(appPath, 'variables.yaml');
-  const variablesContent = await fs.readFile(variablesPath, 'utf-8');
-  return yaml.load(variablesContent);
+  const configPath = resolveApplicationConfigPath(appPath);
+  return loadConfigFile(configPath);
 }
 
 /**
  * Builds image reference string from variables
  * Format: repository:tag (e.g., aifabrix/miso-controller:latest or myregistry.azurecr.io/miso-controller:v1.0.0)
- * @param {Object} variables - Variables from YAML file
+ * @param {Object} variables - Variables from application config
  * @param {string} appKey - Application key (fallback)
  * @returns {string} Image reference string
  */
@@ -94,7 +90,7 @@ function buildImageReference(variables, appKey) {
  * Extract URL from external system JSON file for registration
  * @async
  * @param {string} appKey - Application key
- * @param {Object} externalIntegration - External integration config from variables.yaml
+ * @param {Object} externalIntegration - External integration config from application config
  * @returns {Promise<{url: string, apiKey?: string}>} URL and optional API key
  */
 /**
@@ -171,12 +167,9 @@ async function extractExternalIntegrationUrl(appKey, externalIntegration) {
   const systemFilePath = resolveSystemFilePath(appPath, schemaBasePath, systemFileName);
 
   try {
-    const systemContent = await fs.readFile(systemFilePath, 'utf-8');
-    const systemJson = JSON.parse(systemContent);
-
+    const systemJson = loadConfigFile(systemFilePath);
     const url = extractUrlFromSystemJson(systemJson, systemFileName);
     const apiKey = extractApiKeyFromSystemJson(systemJson);
-
     return { url, apiKey };
   } catch (error) {
     handleFileReadError(error, systemFilePath);
@@ -184,7 +177,7 @@ async function extractExternalIntegrationUrl(appKey, externalIntegration) {
 }
 
 /**
- * Extract application configuration from variables.yaml
+ * Extract application configuration from application config
  * @async
  * @param {Object} variables - Variables from YAML file
  * @param {string} appKey - Application key

package/lib/utils/app-register-validator.js

@@ -114,12 +114,12 @@ async function validateAppRegistrationData(config, originalAppKey) {
   if (!config.displayName) missingFields.push('app.name');
 
   if (missingFields.length > 0) {
-    logger.error(chalk.red('❌ Missing required fields in variables.yaml:'));
+    logger.error(chalk.red('❌ Missing required fields in application.yaml:'));
     missingFields.forEach(field => logger.error(chalk.red(`   - ${field}`)));
     // Detect app type to show correct path
     const { appPath } = await detectAppType(originalAppKey);
     const relativePath = path.relative(process.cwd(), appPath);
-    logger.error(chalk.red(`\n   Please update ${relativePath}/variables.yaml and try again.`));
+    logger.error(chalk.red(`\n   Please update ${relativePath}/application.yaml and try again.`));
     process.exit(1);
   }
 

package/lib/utils/cli-utils.js

@@ -9,6 +9,7 @@
  */
 
 const path = require('path');
+const chalk = require('chalk');
 const fs = require('fs').promises;
 const logger = require('./logger');
 
@@ -85,6 +86,19 @@ function isPermissionDeniedError(errorMsg) {
     !errorMsg.includes('Field "permissions');
 }
 
+/**
+ * Checks if permission denied error is Docker-related (daemon socket / CLI), not API auth.
+ * Used to avoid showing Docker hints when the error is from Controller/Dataplane "Permission denied".
+ * @function isDockerPermissionDeniedError
+ * @param {string} errorMsg - Error message
+ * @returns {boolean} True if Docker permission denied error
+ */
+function isDockerPermissionDeniedError(errorMsg) {
+  if (!isPermissionDeniedError(errorMsg)) return false;
+  const lower = errorMsg.toLowerCase();
+  return lower.includes('docker') || lower.includes('socket') || errorMsg.includes('EACCES');
+}
+
 /**
  * Format Docker-related errors
  * @param {string} errorMsg - Error message
@@ -109,7 +123,7 @@ function formatDockerError(errorMsg) {
       '   Run "aifabrix doctor" to check which ports are in use.'
     ];
   }
-  if (isPermissionDeniedError(errorMsg)) {
+  if (isDockerPermissionDeniedError(errorMsg)) {
     return [
       '   Permission denied.',
       '   Make sure you have the necessary permissions to run Docker commands.'
@@ -149,7 +163,7 @@ function formatAzureError(errorMsg) {
   if (errorMsg.includes('Registry URL is required')) {
     return [
       '   Registry URL is required.',
-      '   Provide via --registry flag or configure in variables.yaml under image.registry'
+      '   Provide via --registry flag or configure in application.yaml under image.registry'
     ];
   }
   return null;
@@ -222,6 +236,21 @@ function formatValidationError(errorMsg) {
   return null;
 }
 
+/**
+ * Format API/Controller/Dataplane permission errors (403-style "Permission denied").
+ * Keeps the real message and adds a hint; avoids mis-classifying as Docker.
+ * @param {string} errorMsg - Error message
+ * @returns {string[]|null} Array of error message lines or null if not an API permission error
+ */
+function formatApiPermissionError(errorMsg) {
+  if (!isPermissionDeniedError(errorMsg)) return null;
+  if (isDockerPermissionDeniedError(errorMsg)) return null;
+  return [
+    `   ${errorMsg}`,
+    '   Ensure your token has the required permission (e.g. external-system:delete for delete).'
+  ];
+}
+
 /**
  * Formats error message based on error type
  * @function formatError
@@ -236,6 +265,7 @@ function formatValidationError(errorMsg) {
  */
 function tryFormatErrorWithFormatters(errorMsg) {
   const formatters = [
+    formatApiPermissionError,
     formatDockerError,
     formatAzureError,
     formatSecretsError,
@@ -283,6 +313,19 @@ function logError(command, errorMessages) {
   logger.error('\n💡 Run "aifabrix doctor" for environment diagnostics.\n');
 }
 
+/**
+ * Logs the resolved app path so the user can see which directory (integration/<app> or builder/<app>) is used.
+ * Path resolution order is always integration first, then builder; no CLI flag overrides this.
+ *
+ * @param {string} appPath - Resolved application directory path
+ * @param {Object} [_options] - Reserved for backward compatibility; ignored
+ */
+function logOfflinePathWhenType(appPath, options) {
+  if (!appPath || !options || (options.type !== 'app' && options.type !== 'external')) return;
+  const displayPath = path.relative(process.cwd(), appPath) || appPath;
+  logger.log(chalk.gray(`Using: ${displayPath}`));
+}
+
 /**
  * Handles command errors with user-friendly messages
  * @param {Error} error - The error that occurred
@@ -332,6 +375,7 @@ async function appendWizardError(appKey, error) {
 module.exports = {
   validateCommand,
   handleCommandError,
-  appendWizardError
+  appendWizardError,
+  logOfflinePathWhenType
 };
 

package/lib/utils/config-format.js

@@ -0,0 +1,154 @@
+/**
+ * Config Format Converter Layer
+ *
+ * Single place for YAML/JSON config I/O. All config loaders and writers use this
+ * layer; internal code works with plain JS objects and JSON Schema only.
+ *
+ * @fileoverview Config format conversion (YAML/JSON) at I/O boundary
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const YAML_EXTENSIONS = ['.yaml', '.yml'];
+const JSON_EXTENSIONS = ['.json'];
+
+const DEFAULT_YAML_OPTIONS = { indent: 2, lineWidth: 120, noRefs: true };
+
+/**
+ * Parses YAML string to plain JS object (same shape as JSON).
+ * Used when reading .yaml / .yml files.
+ *
+ * @param {string} content - YAML string content
+ * @returns {Object} Plain JS object
+ * @throws {Error} If YAML syntax is invalid
+ */
+function yamlToJson(content) {
+  if (typeof content !== 'string') {
+    throw new Error('yamlToJson expects a string');
+  }
+  try {
+    const parsed = yaml.load(content);
+    return parsed === undefined || parsed === null ? {} : parsed;
+  } catch (error) {
+    throw new Error(`Invalid YAML syntax: ${error.message}`);
+  }
+}
+
+/**
+ * Serializes JS object to YAML string.
+ * Used when writing human-editable config as YAML.
+ *
+ * @param {Object} object - Plain JS object (config)
+ * @param {Object} [options] - js-yaml dump options
+ * @returns {string} YAML string
+ */
+function jsonToYaml(object, options = {}) {
+  if (object === undefined || object === null) {
+    return '';
+  }
+  const opts = { ...DEFAULT_YAML_OPTIONS, ...options };
+  return yaml.dump(object, opts);
+}
+
+/**
+ * Returns whether the file path is treated as YAML by extension.
+ *
+ * @param {string} filePath - File path
+ * @returns {boolean} True if .yaml or .yml
+ */
+function isYamlPath(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return YAML_EXTENSIONS.includes(ext);
+}
+
+/**
+ * Returns whether the file path is treated as JSON by extension.
+ *
+ * @param {string} filePath - File path
+ * @returns {boolean} True if .json
+ */
+function isJsonPath(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return JSON_EXTENSIONS.includes(ext);
+}
+
+/**
+ * Reads config file at path; by extension uses yamlToJson or JSON.parse.
+ * Single entry point for "read config file regardless of format".
+ *
+ * @param {string} filePath - Absolute path to config file
+ * @returns {Object} Parsed config object
+ * @throws {Error} If file not found, unreadable, or invalid format
+ */
+function loadConfigFile(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('loadConfigFile requires a non-empty file path');
+  }
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Config file not found: ${filePath}`);
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  const ext = path.extname(filePath).toLowerCase();
+  if (YAML_EXTENSIONS.includes(ext)) {
+    return yamlToJson(content);
+  }
+  if (JSON_EXTENSIONS.includes(ext)) {
+    try {
+      const parsed = JSON.parse(content);
+      return parsed === undefined || parsed === null ? {} : parsed;
+    } catch (error) {
+      throw new Error(`Invalid JSON syntax in ${path.basename(filePath)}: ${error.message}`);
+    }
+  }
+  throw new Error(`Unsupported config file extension: ${ext}. Use .yaml, .yml, or .json`);
+}
+
+/**
+ * Writes config object to path as YAML or JSON based on format or path extension.
+ *
+ * @param {string} filePath - Absolute path to write (extension determines format if format omitted)
+ * @param {Object} object - Config object to write
+ * @param {string} [format] - 'yaml' or 'json'; if omitted, inferred from filePath extension
+ * @throws {Error} If format is invalid or write fails
+ */
+function writeConfigFile(filePath, object, format) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('writeConfigFile requires a non-empty file path');
+  }
+  let targetFormat = format;
+  if (!targetFormat) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (YAML_EXTENSIONS.includes(ext)) {
+      targetFormat = 'yaml';
+    } else if (JSON_EXTENSIONS.includes(ext)) {
+      targetFormat = 'json';
+    } else {
+      throw new Error(`Cannot infer format from path ${filePath}. Use .yaml, .yml, or .json, or pass format.`);
+    }
+  }
+  const normalized = targetFormat.toLowerCase();
+  let content;
+  if (normalized === 'yaml' || normalized === 'yml') {
+    content = jsonToYaml(object);
+  } else if (normalized === 'json') {
+    content = JSON.stringify(object, null, 2);
+  } else {
+    throw new Error(`Invalid format: ${format}. Use 'yaml' or 'json'.`);
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+module.exports = {
+  yamlToJson,
+  jsonToYaml,
+  loadConfigFile,
+  writeConfigFile,
+  isYamlPath,
+  isJsonPath
+};

package/lib/utils/config-paths.js

@@ -41,77 +41,31 @@ async function setPathConfig(getConfigFn, saveConfigFn, key, value, errorMsg) {
   await saveConfigFn(config);
 }
 
-/**
- * Create path configuration functions with config access
- * @param {Function} getConfigFn - Function to get config
- * @param {Function} saveConfigFn - Function to save config
- * @returns {Object} Path configuration functions
- */
-function createPathConfigFunctions(getConfigFn, saveConfigFn) {
+function createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn) {
   return {
-    /**
-     * Get aifabrix-home override path
-     * @async
-     * @returns {Promise<string|null>} Home path or null
-     */
     async getAifabrixHomeOverride() {
       return getPathConfig(getConfigFn, 'aifabrix-home');
     },
-
-    /**
-     * Set aifabrix-home override path
-     * @async
-     * @param {string} homePath - Home path
-     * @returns {Promise<void>}
-     */
     async setAifabrixHomeOverride(homePath) {
       await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-home', homePath, 'Home path is required and must be a string');
     },
-
-    /**
-     * Get aifabrix-secrets path
-     * @async
-     * @returns {Promise<string|null>} Secrets path or null
-     */
     async getAifabrixSecretsPath() {
       return getPathConfig(getConfigFn, 'aifabrix-secrets');
     },
-
-    /**
-     * Set aifabrix-secrets path
-     * @async
-     * @param {string} secretsPath - Secrets path
-     * @returns {Promise<void>}
-     */
     async setAifabrixSecretsPath(secretsPath) {
       await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-secrets', secretsPath, 'Secrets path is required and must be a string');
-    },
+    }
+  };
+}
 
-    /**
-     * Get aifabrix-env-config path
-     * @async
-     * @returns {Promise<string|null>} Env config path or null
-     */
+function createEnvConfigPathFunctions(getConfigFn, saveConfigFn) {
+  return {
     async getAifabrixEnvConfigPath() {
       return getPathConfig(getConfigFn, 'aifabrix-env-config');
     },
-
-    /**
-     * Set aifabrix-env-config path
-     * @async
-     * @param {string} envConfigPath - Env config path
-     * @returns {Promise<void>}
-     */
     async setAifabrixEnvConfigPath(envConfigPath) {
       await setPathConfig(getConfigFn, saveConfigFn, 'aifabrix-env-config', envConfigPath, 'Env config path is required and must be a string');
     },
-
-    /**
-     * Get builder root directory (dirname of aifabrix-env-config when set).
-     * When set, app dirs and generated .env use this instead of cwd/builder.
-     * @async
-     * @returns {Promise<string|null>} Builder root path or null to use cwd/builder
-     */
     async getAifabrixBuilderDir() {
       const envConfigPath = await getPathConfig(getConfigFn, 'aifabrix-env-config');
       return envConfigPath && typeof envConfigPath === 'string' ? path.dirname(envConfigPath) : null;
@@ -119,6 +73,19 @@ function createPathConfigFunctions(getConfigFn, saveConfigFn) {
   };
 }
 
+/**
+ * Create path configuration functions with config access
+ * @param {Function} getConfigFn - Function to get config
+ * @param {Function} saveConfigFn - Function to save config
+ * @returns {Object} Path configuration functions
+ */
+function createPathConfigFunctions(getConfigFn, saveConfigFn) {
+  return {
+    ...createHomeAndSecretsPathFunctions(getConfigFn, saveConfigFn),
+    ...createEnvConfigPathFunctions(getConfigFn, saveConfigFn)
+  };
+}
+
 module.exports = {
   getPathConfig,
   setPathConfig,

package/lib/utils/config-tokens.js

@@ -39,6 +39,7 @@ function normalizeControllerUrl(url) {
  * @param {Function} params.isTokenEncryptedFn - Function to check if token is encrypted
  * @returns {Object} Token management functions
  */
+/* eslint-disable max-lines-per-function -- factory returns many bound helpers; splitting would break encapsulation */
 function createTokenManagementFunctions({
   getConfigFn,
   saveConfigFn,