@aifabrix/builder 2.39.3 → 2.40.2

package/lib/generator/wizard.js

@@ -2,14 +2,19 @@
  * @fileoverview Wizard file generator - saves dataplane-generated configurations to files
  * @author AI Fabrix Team
  * @version 2.0.0
+ *
+ * Standard credential-backed variable names (supplied at runtime from the selected credential;
+ * do not list in configuration array): CLIENTID, CLIENTSECRET, TOKENURL, APIKEY, USERNAME,
+ * PASSWORD, BASEURL. See docs/external-systems.md and docs/wizard.md.
  */
 
 const fs = require('fs').promises;
 const path = require('path');
-const yaml = require('js-yaml');
 const Handlebars = require('handlebars');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
 /**
@@ -39,30 +44,30 @@ function toKeySegment(str) {
 /**
  * Writes system JSON file
  * @async
- * @function writeSystemJsonFile
+ * @function writeSystemYamlFile
  * @param {string} appPath - Application path
  * @param {string} finalSystemKey - Final system key
  * @param {Object} systemConfig - System configuration
  * @returns {Promise<string>} System file path
  */
-async function writeSystemJsonFile(appPath, finalSystemKey, systemConfig) {
-  const systemFileName = `${finalSystemKey}-system.json`;
+async function writeSystemYamlFile(appPath, finalSystemKey, systemConfig) {
+  const systemFileName = `${finalSystemKey}-system.yaml`;
   const systemFilePath = path.join(appPath, systemFileName);
-  await fs.writeFile(systemFilePath, JSON.stringify(systemConfig, null, 2), 'utf8');
+  writeConfigFile(systemFilePath, systemConfig);
   logger.log(chalk.green(`✓ Generated system file: ${systemFileName}`));
   return systemFilePath;
 }
 
 /**
- * Writes datasource JSON files
+ * Writes datasource YAML files
  * @async
- * @function writeDatasourceJsonFiles
+ * @function writeDatasourceYamlFiles
  * @param {string} appPath - Application path
  * @param {string} finalSystemKey - Final system key
  * @param {Object[]} datasourceConfigs - Array of datasource configurations
  * @returns {Promise<string[]>} Array of datasource file names
  */
-async function writeDatasourceJsonFiles(appPath, finalSystemKey, datasourceConfigs) {
+async function writeDatasourceYamlFiles(appPath, finalSystemKey, datasourceConfigs) {
   const datasourceFileNames = [];
   for (const datasourceConfig of datasourceConfigs) {
     const entityType = datasourceConfig.entityType || datasourceConfig.entityKey || datasourceConfig.key?.split('-').pop() || 'default';
@@ -72,9 +77,9 @@ async function writeDatasourceJsonFiles(appPath, finalSystemKey, datasourceConfi
     const datasourceKeyOnly = datasourceKey.includes('-') && datasourceKey.startsWith(`${finalSystemKey}-`)
       ? datasourceKey.substring(finalSystemKey.length + 1)
       : keySegment;
-    const datasourceFileName = `${finalSystemKey}-datasource-${datasourceKeyOnly}.json`;
+    const datasourceFileName = `${finalSystemKey}-datasource-${datasourceKeyOnly}.yaml`;
     const datasourceFilePath = path.join(appPath, datasourceFileName);
-    await fs.writeFile(datasourceFilePath, JSON.stringify(datasourceConfig, null, 2), 'utf8');
+    writeConfigFile(datasourceFilePath, datasourceConfig);
     datasourceFileNames.push(datasourceFileName);
     logger.log(chalk.green(`✓ Generated datasource file: ${datasourceFileName}`));
   }
@@ -99,8 +104,8 @@ async function writeDatasourceJsonFiles(appPath, finalSystemKey, datasourceConfi
 async function generateConfigFilesForWizard(params) {
   const { appPath, appName, finalSystemKey, systemFileName, datasourceFileNames, systemConfig, datasourceConfigs, aiGeneratedReadme } = params;
 
-  // Generate or update variables.yaml with externalIntegration block
-  await generateOrUpdateVariablesYaml({
+  // Generate or update application.yaml with externalIntegration block
+  const configPath = await generateOrUpdateVariablesYaml({
     appPath,
     appName,
     systemKey: finalSystemKey,
@@ -126,7 +131,7 @@ async function generateConfigFilesForWizard(params) {
   logger.log(chalk.green(`✓ Generated deployment manifest: ${finalSystemKey}-deploy.json`));
 
   return {
-    variablesPath: path.join(appPath, 'variables.yaml'),
+    variablesPath: configPath,
     envTemplatePath: path.join(appPath, 'env.template'),
     readmePath: path.join(appPath, 'README.md'),
     applicationSchemaPath: deployManifestPath,
@@ -134,48 +139,28 @@ async function generateConfigFilesForWizard(params) {
   };
 }
 
+async function prepareWizardContext(appName, systemConfig, datasourceConfigs) {
+  const appPath = path.join(process.cwd(), 'integration', appName);
+  await fs.mkdir(appPath, { recursive: true });
+  const finalSystemKey = appName;
+  const appDisplayName = appName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+  const updatedSystemConfig = { ...systemConfig, key: finalSystemKey, displayName: appDisplayName };
+  const updatedDatasourceConfigs = datasourceConfigs.map(ds => {
+    const entityType = ds.entityType || ds.entityKey || ds.key?.split('-').pop() || 'default';
+    const keySegment = toKeySegment(entityType);
+    const entityDisplayName = entityType.charAt(0).toUpperCase() + entityType.slice(1).replace(/-/g, ' ');
+    return { ...ds, key: `${finalSystemKey}-${keySegment}`, systemKey: finalSystemKey, displayName: `${appDisplayName} ${entityDisplayName}` };
+  });
+  return { appPath, finalSystemKey, updatedSystemConfig, updatedDatasourceConfigs, appDisplayName };
+}
+
 async function generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, options = {}) {
   try {
     const { aiGeneratedReadme } = options || {};
-    // Determine app path (integration directory for external systems)
-    const appPath = path.join(process.cwd(), 'integration', appName);
-
-    // Create directory if it doesn't exist
-    await fs.mkdir(appPath, { recursive: true });
-
-    // Use appName as the system key to ensure consistent naming
-    // Priority: appName > systemKey parameter > systemConfig.key
-    const finalSystemKey = appName;
-
-    // Generate displayName from appName (e.g., "my-hubspot" -> "My Hubspot")
-    const appDisplayName = appName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
-
-    // Update system config to use the appName as key and displayName
-    const updatedSystemConfig = {
-      ...systemConfig,
-      key: finalSystemKey,
-      displayName: appDisplayName
-    };
-
-    // Update datasource configs to use appName-based keys and systemKey (key must match ^[a-z0-9-]+$)
-    const updatedDatasourceConfigs = datasourceConfigs.map(ds => {
-      const entityType = ds.entityType || ds.entityKey || ds.key?.split('-').pop() || 'default';
-      const keySegment = toKeySegment(entityType);
-      const entityDisplayName = entityType.charAt(0).toUpperCase() + entityType.slice(1).replace(/-/g, ' ');
-      return {
-        ...ds,
-        key: `${finalSystemKey}-${keySegment}`,
-        systemKey: finalSystemKey,
-        displayName: `${appDisplayName} ${entityDisplayName}`
-      };
-    });
-
-    // Write system and datasource JSON files
-    const systemFilePath = await writeSystemJsonFile(appPath, finalSystemKey, updatedSystemConfig);
-    const datasourceFileNames = await writeDatasourceJsonFiles(appPath, finalSystemKey, updatedDatasourceConfigs);
-
-    // Generate configuration files
-    const systemFileName = `${finalSystemKey}-system.json`;
+    const { appPath, finalSystemKey, updatedSystemConfig, updatedDatasourceConfigs } = await prepareWizardContext(appName, systemConfig, datasourceConfigs);
+    const systemFilePath = await writeSystemYamlFile(appPath, finalSystemKey, updatedSystemConfig);
+    const datasourceFileNames = await writeDatasourceYamlFiles(appPath, finalSystemKey, updatedDatasourceConfigs);
+    const systemFileName = `${finalSystemKey}-system.yaml`;
     const configFiles = await generateConfigFilesForWizard({
       appPath,
       appName,
@@ -186,7 +171,6 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
       datasourceConfigs: updatedDatasourceConfigs,
       aiGeneratedReadme
     });
-
     return {
       appPath,
       systemFilePath,
@@ -199,7 +183,7 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
 }
 
 /**
- * Generate or update variables.yaml with externalIntegration block
+ * Generate or update application.yaml with externalIntegration block
  * @async
  * @function generateOrUpdateVariablesYaml
  * @param {Object} params - Parameters object
@@ -209,23 +193,19 @@ async function generateWizardFiles(appName, systemConfig, datasourceConfigs, sys
  * @param {string} params.systemFileName - System file name
  * @param {string[]} params.datasourceFileNames - Array of datasource file names
  * @param {Object} params.systemConfig - System configuration
+ * @returns {Promise<string>} Path to application config file
  * @throws {Error} If generation fails
  */
 async function generateOrUpdateVariablesYaml(params) {
   const { appPath, appName, systemFileName, datasourceFileNames, systemConfig } = params;
+  let configPath;
+  let variables = {};
   try {
-    const variablesPath = path.join(appPath, 'variables.yaml');
-    let variables = {};
-
-    // Try to read existing variables.yaml
     try {
-      const existingContent = await fs.readFile(variablesPath, 'utf8');
-      variables = yaml.load(existingContent) || {};
-    } catch (error) {
-      // File doesn't exist, create new one
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
+      configPath = resolveApplicationConfigPath(appPath);
+      variables = loadConfigFile(configPath) || {};
+    } catch {
+      configPath = path.join(appPath, 'application.yaml');
     }
 
     // Set basic app info if not present
@@ -258,10 +238,11 @@ async function generateOrUpdateVariablesYaml(params) {
       version: systemConfig.version || '1.0.0'
     };
 
-    await fs.writeFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: 120, noRefs: true }), 'utf8');
-    logger.log(chalk.green('✓ Generated/updated variables.yaml'));
+    writeConfigFile(configPath, variables);
+    logger.log(chalk.green('✓ Generated/updated application.yaml'));
+    return configPath;
   } catch (error) {
-    throw new Error(`Failed to generate variables.yaml: ${error.message}`);
+    throw new Error(`Failed to generate application config: ${error.message}`);
   }
 }
 
@@ -345,7 +326,7 @@ function addAuthenticationLines(lines, auth, authType) {
 function addBaseUrlLines(lines, systemConfig) {
   if (systemConfig.baseUrl || systemConfig.baseURL) {
     lines.push('# API Base URL');
-    lines.push(`BASE_URL=${systemConfig.baseUrl || systemConfig.baseURL}`);
+    lines.push(`BASEURL=${systemConfig.baseUrl || systemConfig.baseURL}`);
     lines.push('');
   }
 }
@@ -445,7 +426,7 @@ async function generateReadme(appPath, appName, systemKey, systemConfig, datasou
       return {
         entityType,
         displayName: ds.displayName || ds.name || ds.key || `Datasource ${index + 1}`,
-        fileName: `${systemKey}-datasource-${datasourceKeyOnly}.json`
+        fileName: `${systemKey}-datasource-${datasourceKeyOnly}.yaml`
       };
     });
 

package/lib/schema/application-schema.json

@@ -799,19 +799,19 @@
         },
         "systems": {
           "type": "array",
-          "description": "List of external-system JSON files to deploy via pipeline.",
+          "description": "List of external-system files to deploy via pipeline (.json, .yaml, or .yml).",
           "items": {
             "type": "string",
-            "pattern": "^[^ ].+\\.json$"
+            "pattern": "^[^ ].+\\.(json|yaml|yml)$"
           },
           "uniqueItems": true
         },
         "dataSources": {
           "type": "array",
-          "description": "List of external-datasource JSON files belonging to this app.",
+          "description": "List of external-datasource files belonging to this app (.json, .yaml, or .yml).",
           "items": {
             "type": "string",
-            "pattern": "^[^ ].+\\.json$"
+            "pattern": "^[^ ].+\\.(json|yaml|yml)$"
           },
           "uniqueItems": true
         },

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

@@ -1587,6 +1587,11 @@
            }
         },
         "additionalProperties":false
+     },
+     "triggerPathsHash":{
+        "type":"string",
+        "description":"SHA256 hash of triggerPaths payload (64-char hex). Used to detect structural changes. Optional; Dataplane computes when absent.",
+        "pattern":"^[a-f0-9]{64}$"
      }
   },
   "additionalProperties":false

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

@@ -102,6 +102,11 @@
       "type": "boolean",
       "default": true
     },
+    "internal": {
+      "type": "boolean",
+      "description": "When true, this integration is deployed on dataplane startup (internal integration). When false or absent, deployed via pipeline only.",
+      "default": false
+    },
     "authentication": {
       "type": "object",
       "description": "Authentication configuration for external system",
@@ -414,6 +419,11 @@
       "type": "boolean",
       "description": "Reserved: whether to generate or expose OpenAPI contract on publish. Not yet implemented.",
       "default": true
+    },
+    "triggerPathsHash": {
+      "type": "string",
+      "description": "SHA256 hash of triggerPaths payload (64-char hex). Used to detect structural changes. Optional; Dataplane computes when absent.",
+      "pattern": "^[a-f0-9]{64}$"
     }
   },
   "additionalProperties": false

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
 };