@aifabrix/builder 2.32.3 → 2.33.1

package/lib/utils/error-formatter.js

@@ -58,6 +58,32 @@ function formatPatternError(field, error) {
   return `${field}: Invalid value ${invalidValue} - ${patternDesc}`;
 }
 
+/**
+ * Formats additionalProperties validation errors
+ * @function formatAdditionalPropertiesError
+ * @param {string} field - Field name
+ * @param {Object} error - Validation error object
+ * @returns {string} Formatted error message
+ */
+function formatAdditionalPropertiesError(field, error) {
+  const invalidProperty = error.params?.additionalProperty;
+  const parentSchema = error.parentSchema || {};
+  const allowedProps = parentSchema.properties ? Object.keys(parentSchema.properties) : [];
+  const lines = [`${field}: must NOT have additional properties`];
+
+  if (invalidProperty) {
+    lines.push(`  Invalid property: "${invalidProperty}" (not allowed)`);
+  }
+  if (allowedProps.length > 0) {
+    lines.push(`  Allowed properties: ${allowedProps.join(', ')}`);
+  }
+  if ((error.instancePath || '').includes('/portalInput/validation')) {
+    lines.push('  Example: { "minLength": 1, "maxLength": 1000, "pattern": "^[0-9]+$", "required": false }');
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Creates error message formatters for each validation keyword
  * @function createKeywordFormatters
@@ -113,6 +139,9 @@ function formatSingleError(error) {
   if (error.keyword === 'pattern') {
     return formatPatternError(field, error);
   }
+  if (error.keyword === 'additionalProperties') {
+    return formatAdditionalPropertiesError(field, error);
+  }
 
   // Use object lookup for keyword-specific messages
   const formatters = createKeywordFormatters(field, error);
@@ -142,9 +171,29 @@ function formatValidationErrors(errors) {
   return errors.map(formatSingleError);
 }
 
+/**
+ * Formats the error when a required DB password variable is missing.
+ * Supports single-db (DB_0_PASSWORD or DB_PASSWORD) and multi-db (DB_0_PASSWORD, DB_1_PASSWORD, ...).
+ * @param {string} appKey - Application key
+ * @param {Object} opts - Options
+ * @param {boolean} [opts.multiDb] - True when multiple databases; required passwordKey is used, no hardcoded index
+ * @param {string} [opts.passwordKey] - The missing variable name (e.g. 'DB_1_PASSWORD'); required when multiDb is true
+ * @returns {string} Error message with next steps
+ */
+function formatMissingDbPasswordError(appKey, opts = {}) {
+  const { multiDb, passwordKey } = opts;
+  if (multiDb && passwordKey) {
+    return 'Missing required password variable ' + passwordKey + ' in .env file for application \'' + appKey + '\'. ' +
+      'Add ' + passwordKey + '=your_secret to your .env file. For multiple databases you need DB_0_PASSWORD, DB_1_PASSWORD, etc.';
+  }
+  return 'Missing required password variable DB_0_PASSWORD or DB_PASSWORD in .env file for application \'' + appKey + '\'. ' +
+    'This app has requires.database or databases in variables.yaml. Add DB_0_PASSWORD=your_secret or DB_PASSWORD=your_secret to builder/' + appKey + '/.env (or run \'aifabrix resolve ' + appKey + '\'), or set requires.database: false in variables.yaml if not needed.';
+}
+
 module.exports = {
   formatSingleError,
   formatValidationErrors,
+  formatMissingDbPasswordError,
   getPatternDescription,
   PATTERN_DESCRIPTIONS
 };

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

@@ -40,7 +40,10 @@ function addControllerUrlHeader(lines, errorData) {
  * @param {Object} errorData - Error response data
  */
 function addControllerUrlToMessage(lines, errorData) {
-  if (errorData && errorData.controllerUrl) {
+  // Prefer showing full endpoint URL if available
+  if (errorData && errorData.endpointUrl) {
+    lines.push(chalk.gray(`Endpoint URL: ${errorData.endpointUrl}`));
+  } else if (errorData && errorData.controllerUrl) {
     lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
   }
 }
@@ -77,8 +80,15 @@ function formatHostnameNotFoundError(lines, errorData) {
  */
 function formatTimeoutError(lines, errorData) {
   lines.push(chalk.yellow('Request timed out.'));
-  addControllerUrlToMessage(lines, errorData);
-  lines.push(chalk.gray('The controller may be overloaded.'));
+
+  // Show full endpoint URL if available, otherwise show controller URL
+  if (errorData && errorData.endpointUrl) {
+    lines.push(chalk.gray(`Endpoint URL: ${errorData.endpointUrl}`));
+  } else if (errorData && errorData.controllerUrl) {
+    lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
+  }
+
+  lines.push(chalk.gray('The endpoint may not exist, the controller may be overloaded, or there may be a network issue.'));
 }
 
 /**

package/lib/utils/external-readme.js

@@ -0,0 +1,125 @@
+/**
+ * External System README Generation
+ *
+ * Provides a shared Handlebars-based README generator for external systems.
+ *
+ * @fileoverview External system README generation utilities
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const handlebars = require('handlebars');
+const { getProjectRoot } = require('./paths');
+
+/**
+ * Formats a display name from a key
+ * @param {string} key - System or app key
+ * @returns {string} Display name
+ */
+function formatDisplayName(key) {
+  if (!key || typeof key !== 'string') {
+    return 'External System';
+  }
+  return key
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Normalizes datasource entries for template use
+ * @param {Array} datasources - Datasource objects
+ * @param {string} systemKey - System key for filename generation
+ * @returns {Array<{entityType: string, displayName: string, fileName: string}>} Normalized entries
+ */
+function normalizeDatasources(datasources, systemKey) {
+  if (!Array.isArray(datasources)) {
+    return [];
+  }
+  return datasources.map((datasource, index) => {
+    const entityType = datasource.entityType ||
+      datasource.entityKey ||
+      datasource.key?.split('-').pop() ||
+      `entity${index + 1}`;
+    const displayName = datasource.displayName ||
+      datasource.name ||
+      `Datasource ${index + 1}`;
+    let fileName = datasource.fileName || datasource.file;
+    if (!fileName) {
+      const key = datasource.key || '';
+      // Extract entity from keys like "hubspot-deploy-company" -> "company"
+      const entity = (systemKey && key.startsWith(`${systemKey}-deploy-`))
+        ? key.slice(`${systemKey}-deploy-`.length)
+        : entityType;
+      fileName = systemKey ? `${systemKey}-datasource-${entity}.json` : `${entity}.json`;
+    }
+    return { entityType, displayName, fileName };
+  });
+}
+
+/**
+ * Builds the external system README template context
+ * @function buildExternalReadmeContext
+ * @param {Object} params - Context parameters
+ * @param {string} [params.appName] - Application name
+ * @param {string} [params.systemKey] - System key
+ * @param {string} [params.systemType] - System type
+ * @param {string} [params.displayName] - Display name
+ * @param {string} [params.description] - Description
+ * @param {Array} [params.datasources] - Datasource objects
+ * @returns {Object} Template context
+ */
+function buildExternalReadmeContext(params = {}) {
+  const appName = params.appName || params.systemKey || 'external-system';
+  const systemKey = params.systemKey || appName;
+  const displayName = params.displayName || formatDisplayName(systemKey);
+  const description = params.description || `External system integration for ${systemKey}`;
+  const systemType = params.systemType || 'openapi';
+  const datasources = normalizeDatasources(params.datasources, systemKey);
+
+  return {
+    appName,
+    systemKey,
+    displayName,
+    description,
+    systemType,
+    datasourceCount: datasources.length,
+    datasources
+  };
+}
+
+/**
+ * Loads and compiles the external system README template
+ * @returns {Function} Compiled template
+ * @throws {Error} If template is missing
+ */
+function loadExternalReadmeTemplate() {
+  const projectRoot = getProjectRoot();
+  const templatePath = path.join(projectRoot, 'templates', 'external-system', 'README.md.hbs');
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`External system README template not found at ${templatePath}`);
+  }
+  const content = fs.readFileSync(templatePath, 'utf8');
+  return handlebars.compile(content);
+}
+
+/**
+ * Generates README content for an external system
+ * @function generateExternalReadmeContent
+ * @param {Object} params - Context parameters
+ * @returns {string} README content
+ */
+function generateExternalReadmeContent(params = {}) {
+  const template = loadExternalReadmeTemplate();
+  const context = buildExternalReadmeContext(params);
+  return template(context);
+}
+
+module.exports = {
+  buildExternalReadmeContext,
+  generateExternalReadmeContent
+};

package/lib/utils/help-builder.js

@@ -0,0 +1,190 @@
+/**
+ * Categorized help builder for AI Fabrix Builder CLI
+ *
+ * Groups commands into logical categories and outputs a user-friendly help.
+ *
+ * @fileoverview Categorized CLI help
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { Help } = require('commander');
+
+/**
+ * Command categories and order. Each command can have an optional `term` override
+ * for the help line (e.g. "down [app]"); otherwise the command name is used.
+ *
+ * @type {Array<{ name: string, commands: Array<{ name: string, term?: string }> }>}
+ */
+const CATEGORIES = [
+  {
+    name: 'Infrastructure (Local Development)',
+    commands: [
+      { name: 'up' },
+      { name: 'down', term: 'down [app]' },
+      { name: 'doctor' },
+      { name: 'status' },
+      { name: 'restart', term: 'restart <service>' }
+    ]
+  },
+  {
+    name: 'Authentication',
+    commands: [
+      { name: 'login' },
+      { name: 'logout' },
+      { name: 'auth' }
+    ]
+  },
+  {
+    name: 'Applications (Create & Develop)',
+    commands: [
+      { name: 'create', term: 'create <app>' },
+      { name: 'wizard' },
+      { name: 'build', term: 'build <app>' },
+      { name: 'run', term: 'run <app>' },
+      { name: 'dockerfile', term: 'dockerfile <app>' }
+    ]
+  },
+  {
+    name: 'Deployment',
+    commands: [
+      { name: 'push', term: 'push <app>' },
+      { name: 'deploy', term: 'deploy <app>' }
+    ]
+  },
+  {
+    name: 'Environments',
+    commands: [
+      { name: 'environment' },
+      { name: 'env' }
+    ]
+  },
+  {
+    name: 'Application & Datasource Management',
+    commands: [
+      { name: 'app' },
+      { name: 'datasource' }
+    ]
+  },
+  {
+    name: 'Configuration & Validation',
+    commands: [
+      { name: 'resolve', term: 'resolve <app>' },
+      { name: 'json', term: 'json <app>' },
+      { name: 'split-json', term: 'split-json <app>' },
+      { name: 'genkey', term: 'genkey <app>' },
+      { name: 'validate', term: 'validate <appOrFile>' },
+      { name: 'diff', term: 'diff <file1> <file2>' }
+    ]
+  },
+  {
+    name: 'External Systems',
+    commands: [
+      { name: 'download', term: 'download <system-key>' },
+      { name: 'delete', term: 'delete <system-key>' },
+      { name: 'test', term: 'test <app>' },
+      { name: 'test-integration', term: 'test-integration <app>' }
+    ]
+  },
+  {
+    name: 'Developer & Secrets',
+    commands: [
+      { name: 'dev' },
+      { name: 'secrets' },
+      { name: 'secure' }
+    ]
+  }
+];
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatHeader(helper, program) {
+  const out = [`Usage: ${helper.commandUsage(program)}`, ''];
+  const desc = helper.commandDescription(program);
+  if (desc && String(desc).length > 0) {
+    out.push(helper.wrap(String(desc), helper.helpWidth || 80, 0), '');
+  }
+  return out;
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatOptions(helper, program) {
+  const options = helper.visibleOptions(program);
+  if (options.length === 0) return [];
+  const optTermWidth = options.reduce((max, o) => Math.max(max, helper.optionTerm(o).length), 0);
+  const out = ['Options:'];
+  for (const opt of options) {
+    out.push(`  ${helper.optionTerm(opt).padEnd(optTermWidth + 2)}${helper.optionDescription(opt)}`);
+  }
+  out.push('');
+  return out;
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {{ categorized: Array<{ name: string, lines: Array<{ term: string, desc: string }> }>, pad: number }}
+ */
+function buildCategorizedWithPad(helper, program) {
+  const nameToCmd = new Map(program.commands.map((c) => [c.name(), c]));
+  const categorized = [];
+  let maxTermLen = 'help [command]'.length;
+
+  for (const cat of CATEGORIES) {
+    const lines = [];
+    for (const spec of cat.commands) {
+      const cmd = nameToCmd.get(spec.name);
+      if (!cmd) continue;
+      const term = spec.term || cmd.name();
+      maxTermLen = Math.max(maxTermLen, term.length);
+      const descText = helper.subcommandDescription(cmd) || cmd.description() || '';
+      lines.push({ term, desc: descText });
+    }
+    if (lines.length > 0) categorized.push({ name: cat.name, lines });
+  }
+  return { categorized, pad: maxTermLen + 2 };
+}
+
+/**
+ * @param {object} helper - Commander Help instance
+ * @param {import('commander').Command} program
+ * @returns {string[]}
+ */
+function formatCommandCategories(helper, program) {
+  const { categorized, pad } = buildCategorizedWithPad(helper, program);
+  const out = [];
+  for (const { name, lines } of categorized) {
+    out.push(name + ':');
+    for (const { term, desc: d } of lines) out.push(`  ${term.padEnd(pad)}${d}`);
+    out.push('');
+  }
+  out.push('Help:');
+  out.push(`  ${'help [command]'.padEnd(pad)}display help for command`);
+  out.push('');
+  return out;
+}
+
+/**
+ * Build the full categorized help string for the program.
+ *
+ * @param {import('commander').Command} program - Commander program
+ * @returns {string} Formatted help text
+ */
+function buildCategorizedHelp(program) {
+  const helper = new Help();
+  const output = [
+    ...formatHeader(helper, program),
+    ...formatOptions(helper, program),
+    ...formatCommandCategories(helper, program)
+  ];
+  return output.join('\n');
+}
+
+module.exports = { buildCategorizedHelp, CATEGORIES };

package/lib/utils/infra-status.js

@@ -38,7 +38,11 @@ async function getInfraStatus() {
     postgres: { port: ports.postgres, url: `localhost:${ports.postgres}` },
     redis: { port: ports.redis, url: `localhost:${ports.redis}` },
     pgadmin: { port: ports.pgadmin, url: `http://localhost:${ports.pgadmin}` },
-    'redis-commander': { port: ports.redisCommander, url: `http://localhost:${ports.redisCommander}` }
+    'redis-commander': { port: ports.redisCommander, url: `http://localhost:${ports.redisCommander}` },
+    traefik: {
+      port: `${ports.traefikHttp}/${ports.traefikHttps}`,
+      url: `http://localhost:${ports.traefikHttp}, https://localhost:${ports.traefikHttps}`
+    }
   };
 
   const status = {};
@@ -82,9 +86,15 @@ async function getInfraStatus() {
  */
 function getInfraContainerNames(devIdNum, devId) {
   if (devIdNum === 0) {
-    return ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander'];
+    return ['aifabrix-postgres', 'aifabrix-redis', 'aifabrix-pgadmin', 'aifabrix-redis-commander', 'aifabrix-traefik'];
   }
-  return [`aifabrix-dev${devId}-postgres`, `aifabrix-dev${devId}-redis`, `aifabrix-dev${devId}-pgadmin`, `aifabrix-dev${devId}-redis-commander`];
+  return [
+    `aifabrix-dev${devId}-postgres`,
+    `aifabrix-dev${devId}-redis`,
+    `aifabrix-dev${devId}-pgadmin`,
+    `aifabrix-dev${devId}-redis-commander`,
+    `aifabrix-dev${devId}-traefik`
+  ];
 }
 
 /**

package/lib/utils/paths.js

@@ -408,13 +408,28 @@ function checkBuilderFolder(appName) {
  * Checks both integration/ and builder/ folders for backward compatibility
  *
  * @param {string} appName - Application name
- * @returns {Promise<{isExternal: boolean, appPath: string, appType: string}>}
+ * @param {Object} [options] - Detection options
+ * @param {string} [options.type] - Forced application type (external)
+ * @returns {Promise<{isExternal: boolean, appPath: string, appType: string, baseDir?: string}>}
  */
-async function detectAppType(appName) {
+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) {

package/lib/utils/port-resolver.js

@@ -0,0 +1,111 @@
+/**
+ * AI Fabrix Builder - Centralized Port Resolution
+ *
+ * Single source of truth for resolving application port from variables.yaml.
+ * Use getContainerPort for container/Docker/deployment/registration; use getLocalPort
+ * for local .env and dev-id–adjusted host port.
+ *
+ * @fileoverview Port resolution from variables (port, build.containerPort, build.localPort)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+/**
+ * Resolve container port from variables object.
+ * 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 {number} [defaultPort=3000] - Default when neither build.containerPort nor port is set
+ * @returns {number} Resolved container port
+ */
+function getContainerPort(variables, defaultPort = 3000) {
+  const v = variables || {};
+  return v.build?.containerPort ?? v.port ?? defaultPort;
+}
+
+/**
+ * Resolve local (development) port from variables object.
+ * 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 {number} [defaultPort=3000] - Default when neither build.localPort nor port is set
+ * @returns {number} Resolved local port
+ */
+function getLocalPort(variables, defaultPort = 3000) {
+  const v = variables || {};
+  const local = v.build?.localPort;
+  if (typeof local === 'number' && local > 0) {
+    return local;
+  }
+  return v.port ?? defaultPort;
+}
+
+/**
+ * Load variables from path. Returns null if path missing, not found, or parse error.
+ *
+ * @param {string} variablesPath - Path to variables.yaml
+ * @returns {Object|null} Parsed variables or null
+ */
+function loadVariablesFromPath(variablesPath) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(variablesPath, 'utf8');
+    return yaml.load(content) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve container port from variables.yaml 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
+ * @returns {number|null} Container port or null
+ */
+function getContainerPortFromPath(variablesPath) {
+  const v = loadVariablesFromPath(variablesPath);
+  if (!v) {
+    return null;
+  }
+  const p = v.build?.containerPort ?? v.port;
+  return (p !== undefined && p !== null) ? p : null;
+}
+
+/**
+ * Resolve local port from variables.yaml 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
+ * @returns {number|null} Local port or null
+ */
+function getLocalPortFromPath(variablesPath) {
+  const v = loadVariablesFromPath(variablesPath);
+  if (!v) {
+    return null;
+  }
+  const local = v.build?.localPort;
+  if (typeof local === 'number' && local > 0) {
+    return local;
+  }
+  const p = v.port;
+  return (p !== undefined && p !== null) ? p : null;
+}
+
+module.exports = {
+  getContainerPort,
+  getLocalPort,
+  getContainerPortFromPath,
+  getLocalPortFromPath,
+  loadVariablesFromPath
+};

package/lib/utils/secrets-helpers.js

@@ -17,6 +17,7 @@ const { rewriteInfraEndpoints, getEnvHosts, getServicePort, getServiceHost, getL
 const { loadEnvConfig } = require('./env-config-loader');
 const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
+const { getLocalPortFromPath } = require('./port-resolver');
 
 /**
  * Interpolate ${VAR} occurrences with values from envVars map
@@ -145,26 +146,13 @@ function getPortFromLocalEnv(localEnv) {
 }
 
 /**
- * Gets port from variables.yaml file
+ * Gets port from variables.yaml file (build.localPort if positive, else port). Uses port-resolver.
  * @function getPortFromVariablesFile
  * @param {string} variablesPath - Path to variables.yaml
  * @returns {number|null} Port value or null
  */
 function getPortFromVariablesFile(variablesPath) {
-  if (!variablesPath || !fs.existsSync(variablesPath)) {
-    return null;
-  }
-  try {
-    const variablesContent = fs.readFileSync(variablesPath, 'utf8');
-    const variables = yaml.load(variablesContent);
-    const localPort = variables?.build?.localPort;
-    if (typeof localPort === 'number' && localPort > 0) {
-      return localPort;
-    }
-    return variables?.port || null;
-  } catch {
-    return null;
-  }
+  return getLocalPortFromPath(variablesPath);
 }
 
 /**

package/lib/utils/secrets-utils.js

@@ -14,6 +14,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
+const { getContainerPort } = require('./port-resolver');
 
 /**
  * Loads secrets from file with cascading lookup support
@@ -145,8 +146,7 @@ function resolveUrlPort(protocol, hostname, port, urlPath, hostnameToService) {
     const variablesContent = fs.readFileSync(serviceVariablesPath, 'utf8');
     const variables = yaml.load(variablesContent);
 
-    // Get containerPort or fall back to port
-    const containerPort = variables?.build?.containerPort || variables?.port || port;
+    const containerPort = getContainerPort(variables, port);
 
     // Replace port in URL
     return `${protocol}${hostname}:${containerPort}${urlPath}`;

package/lib/utils/token-manager.js

@@ -321,7 +321,7 @@ async function getDeploymentAuth(controllerUrl, environment, appName) {
 async function extractClientCredentials(authConfig, appKey, envKey, _options = {}) {
   if (authConfig.type === 'client-credentials') {
     if (!authConfig.clientId || !authConfig.clientSecret) {
-      throw new Error('Client ID and Client Secret are required');
+      throw new Error('Client ID and Client Secret are required for client-credentials authentication');
     }
     return {
       clientId: authConfig.clientId,
@@ -349,9 +349,14 @@ async function extractClientCredentials(authConfig, appKey, envKey, _options = {
       };
     }
 
-    // Construct clientId from controller, environment, and application key
-    // (not used, but shown in error message for reference)
-    throw new Error(`Client ID and Client Secret are required. Add credentials to ~/.aifabrix/secrets.local.yaml as '${appKey}-client-idKeyVault' and '${appKey}-client-secretKeyVault', or use credentials authentication.`);
+    // No credentials found - provide helpful error message
+    throw new Error(
+      'Client ID and Client Secret are required for deployment.\n' +
+      'Add credentials to ~/.aifabrix/secrets.local.yaml as:\n' +
+      `  '${appKey}-client-idKeyVault': <client-id>\n` +
+      `  '${appKey}-client-secretKeyVault': <client-secret>\n\n` +
+      'Or use credentials authentication with --client-id and --client-secret flags.'
+    );
   }
 
   throw new Error('Invalid authentication type');