@aifabrix/builder 2.21.1 → 2.22.1

package/lib/utils/error-formatters/http-status-errors.js

@@ -13,33 +13,85 @@ const chalk = require('chalk');
 /**
  * Formats authentication error
  * @param {Object} errorData - Error response data
+ * @param {string} [errorData.controllerUrl] - Controller URL for example command
+ * @param {string[]} [errorData.attemptedUrls] - Array of attempted controller URLs
+ * @param {string} [errorData.message] - Error message
+ * @param {string} [errorData.error] - Error text
+ * @param {string} [errorData.detail] - Error detail
+ * @param {string} [errorData.correlationId] - Correlation ID
  * @returns {string} Formatted authentication error message
  */
 function formatAuthenticationError(errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Authentication Failed\n'));
-  if (errorData.message) {
-    lines.push(chalk.yellow(errorData.message));
-  } else {
-    lines.push(chalk.yellow('Invalid credentials or token expired.'));
+
+  // Show controller URL prominently if available
+  if (errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
+  // Show attempted URLs if multiple were tried
+  if (errorData.attemptedUrls && errorData.attemptedUrls.length > 1) {
+    lines.push(chalk.gray('Attempted controller URLs:'));
+    errorData.attemptedUrls.forEach(url => {
+      lines.push(chalk.gray(`  • ${url}`));
+    });
+    lines.push('');
+  }
+
+  // Check if error message contains specific information
+  const errorMessage = errorData.message || errorData.error || errorData.detail || '';
+  const lowerMessage = errorMessage.toLowerCase();
+
+  // Only show error message if it provides useful information beyond generic messages
+  const isGenericMessage = lowerMessage.includes('authentication required') ||
+                          lowerMessage.includes('unauthorized') ||
+                          lowerMessage === '';
+
+  if (errorMessage && !isGenericMessage) {
+    // Show specific error message if it provides useful details
+    lines.push(chalk.yellow(errorMessage));
+    lines.push('');
   }
+
+  // Always show general, actionable guidance
+  lines.push(chalk.gray('Your authentication token is invalid or has expired.'));
   lines.push('');
-  lines.push(chalk.gray('Run: aifabrix login'));
+  lines.push(chalk.gray('To authenticate, run:'));
+
+  // Use real controller URL if provided, otherwise show placeholder
+  const controllerUrl = errorData.controllerUrl;
+  if (controllerUrl && controllerUrl.trim()) {
+    lines.push(chalk.gray(`  aifabrix login --method device --controller ${controllerUrl}`));
+  } else {
+    lines.push(chalk.gray('  aifabrix login --method device --controller <url>'));
+  }
+
   if (errorData.correlationId) {
+    lines.push('');
     lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
   }
+
   return lines.join('\n');
 }
 
 /**
  * Formats server error (500+)
  * @param {Object} errorData - Error response data
+ * @param {string} [errorData.controllerUrl] - Controller URL
  * @returns {string} Formatted server error message
  */
 function formatServerError(errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Server Error\n'));
 
+  // Show controller URL if available
+  if (errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
   // Check for RFC 7807 Problem Details format (detail field)
   if (errorData.detail) {
     lines.push(chalk.yellow(errorData.detail));
@@ -62,12 +114,19 @@ function formatServerError(errorData) {
 /**
  * Formats conflict error (409)
  * @param {Object} errorData - Error response data
+ * @param {string} [errorData.controllerUrl] - Controller URL
  * @returns {string} Formatted conflict error message
  */
 function formatConflictError(errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Conflict\n'));
 
+  // Show controller URL if available
+  if (errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
   // Check if it's an application already exists error
   const detail = errorData.detail || errorData.message || '';
   if (detail.toLowerCase().includes('application already exists')) {
@@ -124,12 +183,19 @@ function getNotFoundGuidance(detail) {
 /**
  * Formats not found error (404)
  * @param {Object} errorData - Error response data
+ * @param {string} [errorData.controllerUrl] - Controller URL
  * @returns {string} Formatted not found error message
  */
 function formatNotFoundError(errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Not Found\n'));
 
+  // Show controller URL if available
+  if (errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
   const detail = errorData.detail || errorData.message || '';
   if (detail) {
     lines.push(chalk.yellow(detail));
@@ -154,12 +220,19 @@ function formatNotFoundError(errorData) {
  * Formats generic error
  * @param {Object} errorData - Error response data
  * @param {number} statusCode - HTTP status code
+ * @param {string} [errorData.controllerUrl] - Controller URL
  * @returns {string} Formatted error message
  */
 function formatGenericError(errorData, statusCode) {
   const lines = [];
   lines.push(chalk.red(`❌ Error (HTTP ${statusCode})\n`));
 
+  // Show controller URL if available
+  if (errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
   // Check for RFC 7807 Problem Details format (detail field)
   if (errorData.detail) {
     lines.push(chalk.yellow(errorData.detail));

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

@@ -14,26 +14,46 @@ const chalk = require('chalk');
  * Formats network error
  * @param {string} errorMessage - Error message
  * @param {Object} errorData - Error response data (optional)
+ * @param {string} [errorData.controllerUrl] - Controller URL
  * @returns {string} Formatted network error message
  */
 function formatNetworkError(errorMessage, errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Network Error\n'));
 
-  if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Cannot connect')) {
+  // Show controller URL prominently if available
+  if (errorData && errorData.controllerUrl) {
+    lines.push(chalk.yellow(`Controller URL: ${errorData.controllerUrl}`));
+    lines.push('');
+  }
+
+  // Ensure errorMessage is a string
+  const message = typeof errorMessage === 'string' ? errorMessage : String(errorMessage || 'Network error');
+
+  if (message.includes('ECONNREFUSED') || message.includes('Cannot connect')) {
     lines.push(chalk.yellow('Cannot connect to controller.'));
+    if (errorData && errorData.controllerUrl) {
+      lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
+    }
     lines.push(chalk.gray('Check if the controller is running.'));
-  } else if (errorMessage.includes('ENOTFOUND') || errorMessage.includes('hostname not found')) {
+  } else if (message.includes('ENOTFOUND') || message.includes('hostname not found')) {
     lines.push(chalk.yellow('Controller hostname not found.'));
+    if (errorData && errorData.controllerUrl) {
+      lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
+    }
     lines.push(chalk.gray('Check your controller URL.'));
-  } else if (errorMessage.includes('timeout') || errorMessage.includes('timed out')) {
+  } else if (message.includes('timeout') || message.includes('timed out')) {
     lines.push(chalk.yellow('Request timed out.'));
+    if (errorData && errorData.controllerUrl) {
+      lines.push(chalk.gray(`Controller URL: ${errorData.controllerUrl}`));
+    }
     lines.push(chalk.gray('The controller may be overloaded.'));
   } else {
-    lines.push(chalk.yellow(errorMessage));
+    lines.push(chalk.yellow(message));
   }
 
   if (errorData && errorData.correlationId) {
+    lines.push('');
     lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
   }
 

package/lib/utils/secrets-generator.js

@@ -11,10 +11,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
 const os = require('os');
+const yaml = require('js-yaml');
 const crypto = require('crypto');
 const logger = require('./logger');
+const pathsUtil = require('./paths');
 
 /**
  * Finds missing secret keys from template
@@ -123,11 +124,12 @@ function saveSecretsFile(resolvedPath, secrets) {
 /**
  * Generates missing secret keys in secrets file
  * Scans env.template for kv:// references and adds missing keys with secure defaults
+ * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override when path not provided
  *
  * @async
  * @function generateMissingSecrets
  * @param {string} envTemplate - Environment template content
- * @param {string} secretsPath - Path to secrets file
+ * @param {string} [secretsPath] - Path to secrets file (optional)
  * @returns {Promise<string[]>} Array of newly generated secret keys
  * @throws {Error} If generation fails
  *
@@ -136,7 +138,7 @@ function saveSecretsFile(resolvedPath, secrets) {
  * // Returns: ['new-secret-key', 'another-secret']
  */
 async function generateMissingSecrets(envTemplate, secretsPath) {
-  const resolvedPath = secretsPath || path.join(os.homedir(), '.aifabrix', 'secrets.yaml');
+  const resolvedPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
   const existingSecrets = loadExistingSecrets(resolvedPath);
   const missingKeys = findMissingSecretKeys(envTemplate, existingSecrets);
 

package/lib/utils/secrets-utils.js

@@ -12,8 +12,8 @@
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
-const os = require('os');
 const logger = require('./logger');
+const pathsUtil = require('./paths');
 
 /**
  * Loads secrets from file with cascading lookup support
@@ -46,11 +46,12 @@ async function loadSecretsFromFile(filePath) {
 
 /**
  * Loads user secrets from ~/.aifabrix/secrets.local.yaml
+ * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
  * @function loadUserSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
 function loadUserSecrets() {
-  const userSecretsPath = path.join(os.homedir(), '.aifabrix', 'secrets.local.yaml');
+  const userSecretsPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
   if (!fs.existsSync(userSecretsPath)) {
     return {};
   }
@@ -73,11 +74,12 @@ function loadUserSecrets() {
 
 /**
  * Loads default secrets from ~/.aifabrix/secrets.yaml
+ * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
  * @function loadDefaultSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
 function loadDefaultSecrets() {
-  const defaultPath = path.join(os.homedir(), '.aifabrix', 'secrets.yaml');
+  const defaultPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
   if (!fs.existsSync(defaultPath)) {
     return {};
   }

package/lib/validate.js

@@ -16,6 +16,7 @@ const validator = require('./validator');
 const { resolveExternalFiles } = require('./utils/schema-resolver');
 const { loadExternalSystemSchema, loadExternalDataSourceSchema, detectSchemaType } = require('./utils/schema-loader');
 const { formatValidationErrors } = require('./utils/error-formatter');
+const { detectAppType } = require('./utils/paths');
 const logger = require('./utils/logger');
 
 /**
@@ -56,10 +57,29 @@ async function validateExternalFile(filePath, type) {
 
   const valid = validate(parsed);
 
+  const errors = valid ? [] : formatValidationErrors(validate.errors);
+  const warnings = [];
+
+  // Additional validation for external system files: check role references in permissions
+  if (type === 'system' && parsed.permissions && Array.isArray(parsed.permissions)) {
+    const roles = parsed.roles || [];
+    const roleValues = new Set(roles.map(r => r.value));
+
+    parsed.permissions.forEach((permission, index) => {
+      if (permission.roles && Array.isArray(permission.roles)) {
+        permission.roles.forEach(roleValue => {
+          if (!roleValues.has(roleValue)) {
+            errors.push(`Permission "${permission.name}" (index ${index}) references role "${roleValue}" which does not exist in roles array`);
+          }
+        });
+      }
+    });
+  }
+
   return {
-    valid,
-    errors: valid ? [] : formatValidationErrors(validate.errors),
-    warnings: []
+    valid: errors.length === 0,
+    errors,
+    warnings
   };
 }
 
@@ -130,11 +150,28 @@ async function validateAppOrFile(appOrFile) {
   // Treat as app name
   const appName = appOrFile;
 
+  // Detect app type to support both builder/ and integration/ directories
+  const { appPath, isExternal } = await detectAppType(appName);
+
   // Validate application
   const appValidation = await validator.validateApplication(appName);
 
+  // Validate rbac.yaml for external systems
+  let rbacValidation = null;
+  if (isExternal) {
+    try {
+      rbacValidation = await validator.validateRbac(appName);
+    } catch (error) {
+      rbacValidation = {
+        valid: false,
+        errors: [error.message],
+        warnings: []
+      };
+    }
+  }
+
   // Check for externalIntegration block
-  const variablesPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+  const variablesPath = path.join(appPath, 'variables.yaml');
   if (!fs.existsSync(variablesPath)) {
     return {
       valid: appValidation.valid,
@@ -193,20 +230,25 @@ async function validateAppOrFile(appOrFile) {
   }
 
   // Aggregate results
-  const allValid = appValidation.valid && externalValidations.every(v => v.valid);
+  const rbacErrors = rbacValidation ? rbacValidation.errors : [];
+  const rbacWarnings = rbacValidation ? rbacValidation.warnings : [];
+  const allValid = appValidation.valid && externalValidations.every(v => v.valid) && (!rbacValidation || rbacValidation.valid);
   const allErrors = [
     ...appValidation.errors,
-    ...externalValidations.flatMap(v => v.errors.map(e => `${v.file}: ${e}`))
+    ...externalValidations.flatMap(v => v.errors.map(e => `${v.file}: ${e}`)),
+    ...rbacErrors.map(e => `rbac.yaml: ${e}`)
   ];
   const allWarnings = [
     ...appValidation.warnings,
-    ...externalValidations.flatMap(v => v.warnings)
+    ...externalValidations.flatMap(v => v.warnings),
+    ...rbacWarnings
   ];
 
   return {
     valid: allValid,
     application: appValidation,
     externalFiles: externalValidations,
+    rbac: rbacValidation,
     errors: allErrors,
     warnings: allWarnings
   };
@@ -263,6 +305,24 @@ function displayValidationResults(result) {
     });
   }
 
+  // Display rbac validation (for external systems)
+  if (result.rbac) {
+    logger.log(chalk.blue('\nRBAC Configuration:'));
+    if (result.rbac.valid) {
+      logger.log(chalk.green('  ✓ RBAC configuration is valid'));
+    } else {
+      logger.log(chalk.red('  ✗ RBAC configuration has errors:'));
+      result.rbac.errors.forEach(error => {
+        logger.log(chalk.red(`    • ${error}`));
+      });
+    }
+    if (result.rbac.warnings && result.rbac.warnings.length > 0) {
+      result.rbac.warnings.forEach(warning => {
+        logger.log(chalk.yellow(`    ⚠ ${warning}`));
+      });
+    }
+  }
+
   // Display file validation (for direct file validation)
   if (result.file) {
     logger.log(chalk.blue(`\nFile: ${result.file}`));

package/lib/validator.js

@@ -162,7 +162,9 @@ async function validateRbac(appName) {
     throw new Error('App name is required and must be a string');
   }
 
-  const rbacPath = path.join(process.cwd(), 'builder', appName, 'rbac.yaml');
+  // Support both builder/ and integration/ directories using detectAppType
+  const { appPath } = await detectAppType(appName);
+  const rbacPath = path.join(appPath, 'rbac.yaml');
 
   if (!fs.existsSync(rbacPath)) {
     return { valid: true, errors: [], warnings: ['rbac.yaml not found - authentication disabled'] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.21.1",
+  "version": "2.22.1",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/external-system/external-system.json.hbs

@@ -32,6 +32,25 @@
     "serverUrl": "https://mcp.example.com",
     "toolPrefix": "{{systemKey}}"
   }{{/if}},
-  "tags": []
+  "tags": []{{#if roles}},
+  "roles": [
+    {{#each roles}}
+    {
+      "name": "{{name}}",
+      "value": "{{value}}",
+      "description": "{{description}}"{{#if Groups}},
+      "Groups": [{{#each Groups}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]{{/if}}
+    }{{#unless @last}},{{/unless}}
+    {{/each}}
+  ]{{/if}}{{#if permissions}},
+  "permissions": [
+    {{#each permissions}}
+    {
+      "name": "{{name}}",
+      "roles": [{{#each roles}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}],
+      "description": "{{description}}"
+    }{{#unless @last}},{{/unless}}
+    {{/each}}
+  ]{{/if}}
 }