@aifabrix/builder 2.8.0 → 2.10.0

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

@@ -3,7 +3,6 @@
   "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json",
   "title": "AI Fabrix External System Configuration Schema",
   "description": "Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, OpenAPI/MCP bindings, field mappings defaults, metadata handling and portal inputs.",
-
   "metadata": {
     "key": "external-system-schema",
     "name": "External System Configuration Schema",
@@ -19,7 +18,13 @@
       "maxVersion": "2.0.0",
       "deprecated": false
     },
-    "tags": ["schema", "external-system", "dataplane", "integration", "validation"],
+    "tags": [
+      "schema",
+      "external-system",
+      "dataplane",
+      "integration",
+      "validation"
+    ],
     "dependencies": [],
     "changelog": [
       {
@@ -36,9 +41,7 @@
       }
     ]
   },
-
   "type": "object",
-
   "required": [
     "key",
     "displayName",
@@ -46,7 +49,6 @@
     "type",
     "authentication"
   ],
-
   "properties": {
     "key": {
       "type": "string",
@@ -55,32 +57,31 @@
       "minLength": 3,
       "maxLength": 40
     },
-
     "displayName": {
       "type": "string",
       "description": "Human-readable name for the external system",
       "minLength": 1,
       "maxLength": 100
     },
-
     "description": {
       "type": "string",
       "description": "Description of this external system integration",
       "minLength": 1,
       "maxLength": 500
     },
-
     "type": {
       "type": "string",
-      "enum": ["openapi", "mcp", "custom"],
+      "enum": [
+        "openapi",
+        "mcp",
+        "custom"
+      ],
       "description": "Integration type: OpenAPI-driven, MCP-driven, or custom Python connector."
     },
-
     "enabled": {
       "type": "boolean",
       "default": true
     },
-
     "environment": {
       "type": "object",
       "description": "Environment-level configuration values used by dataplane and external data sources.",
@@ -97,95 +98,80 @@
       },
       "additionalProperties": true
     },
-
     "authentication": {
       "type": "object",
-      "description": "Authentication configuration for the external system.",
-      "required": ["type"],
+      "description": "Authentication configuration for external system",
+      "required": [
+        "type"
+      ],
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["oauth2", "apikey", "basic", "aad", "none"],
-          "description": "Authentication method used for API access."
+          "enum": [
+            "oauth2",
+            "apikey",
+            "basic",
+            "aad",
+            "none"
+          ],
+          "description": "Authentication type"
         },
-
         "oauth2": {
           "type": "object",
-          "description": "OAuth2 configuration used when type == 'oauth2'. All secrets are stored in Key Vault.",
-          "properties": {
-            "tokenUrl": {
-              "type": "string",
-              "pattern": "^(http|https)://.*$"
-            },
-            "clientId": {
-              "type": "string"
-            },
-            "clientSecret": {
-              "type": "string"
-            },
-            "scopes": {
-              "type": "array",
-              "items": { "type": "string" }
-            }
-          },
-          "additionalProperties": false
+          "description": "OAuth2 authentication configuration",
+          "additionalProperties": true
         },
-
         "apikey": {
           "type": "object",
-          "properties": {
-            "headerName": { "type": "string" },
-            "key": { "type": "string" }
-          },
-          "additionalProperties": false
+          "description": "API key authentication configuration",
+          "additionalProperties": true
         },
-
         "basic": {
           "type": "object",
-          "properties": {
-            "username": { "type": "string" },
-            "password": { "type": "string" }
-          },
-          "additionalProperties": false
+          "description": "Basic authentication configuration",
+          "additionalProperties": true
+        },
+        "aad": {
+          "type": "object",
+          "description": "Azure AD authentication configuration",
+          "additionalProperties": true
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-
     "openapi": {
       "type": "object",
-      "description": "OpenAPI integration configuration.",
+      "description": "OpenAPI integration configuration",
       "properties": {
         "documentKey": {
           "type": "string",
-          "description": "Reference to OpenAPI spec registered via builder. Example: 'hubspot-v3'."
+          "description": "Key of the OpenAPI document in the registry"
         },
-        "autoDiscoverEntities": {
-          "type": "boolean",
-          "default": false,
-          "description": "Automatically discover resources/entities from OpenAPI schema."
+        "specUrl": {
+          "type": "string",
+          "description": "URL to the OpenAPI specification",
+          "pattern": "^(http|https)://.*$"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-
     "mcp": {
       "type": "object",
-      "description": "Model Context Protocol integration config.",
+      "description": "Model Context Protocol integration configuration",
       "properties": {
         "serverUrl": {
           "type": "string",
+          "description": "MCP server URL",
           "pattern": "^(http|https)://.*$"
         },
         "toolPrefix": {
           "type": "string",
-          "pattern": "^[a-z0-9-]+$",
-          "description": "Prefix for MCP tool names generated from this system."
+          "description": "Prefix for MCP tool names",
+          "pattern": "^[a-zA-Z0-9_-]+$"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
-
     "dataSources": {
       "type": "array",
       "description": "List of data source keys belonging to this external system. Each must match external-datasource.schema.json.",
@@ -195,13 +181,17 @@
       },
       "uniqueItems": true
     },
-
     "configuration": {
       "type": "array",
       "description": "External system configuration variables (same pattern as application-schema).",
       "items": {
         "type": "object",
-        "required": ["name", "value", "location", "required"],
+        "required": [
+          "name",
+          "value",
+          "location",
+          "required"
+        ],
         "properties": {
           "name": {
             "type": "string",
@@ -213,33 +203,61 @@
           },
           "location": {
             "type": "string",
-            "enum": ["variable", "keyvault"]
+            "enum": [
+              "variable",
+              "keyvault"
+            ]
           },
           "required": {
             "type": "boolean"
           },
           "portalInput": {
             "type": "object",
-            "required": ["field", "label"],
+            "required": [
+              "field",
+              "label"
+            ],
             "properties": {
               "field": {
                 "type": "string",
-                "enum": ["password", "text", "textarea", "select", "json"]
+                "enum": [
+                  "password",
+                  "text",
+                  "textarea",
+                  "select",
+                  "json"
+                ]
+              },
+              "label": {
+                "type": "string"
+              },
+              "placeholder": {
+                "type": "string"
               },
-              "label": { "type": "string" },
-              "placeholder": { "type": "string" },
               "options": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
+              },
+              "masked": {
+                "type": "boolean"
               },
-              "masked": { "type": "boolean" },
               "validation": {
                 "type": "object",
                 "properties": {
-                  "minLength": { "type": "integer" },
-                  "maxLength": { "type": "integer" },
-                  "pattern": { "type": "string" },
-                  "required": { "type": "boolean" }
+                  "minLength": {
+                    "type": "integer"
+                  },
+                  "maxLength": {
+                    "type": "integer"
+                  },
+                  "pattern": {
+                    "type": "string"
+                  },
+                  "required": {
+                    "type": "boolean"
+                  }
                 },
                 "additionalProperties": false
               }
@@ -250,13 +268,13 @@
         "additionalProperties": false
       }
     },
-
     "tags": {
       "type": "array",
       "description": "Optional tags for search / filtering",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     }
   },
-
   "additionalProperties": false
 }

package/lib/templates.js

@@ -32,7 +32,7 @@ function generateVariablesYaml(appName, config) {
         environment: 'dev'
       },
       externalIntegration: {
-        schemaBasePath: './schemas',
+        schemaBasePath: './',
         systems: [],
         dataSources: [],
         autopublish: true,
@@ -134,13 +134,31 @@ function generateVariablesYaml(appName, config) {
  */
 function buildCoreEnv(config) {
   return {
-    'NODE_ENV': 'development',
+    'NODE_ENV': '${NODE_ENV}',
     'PORT': config.port || 3000,
     'APP_NAME': config.appName || 'myapp',
     'LOG_LEVEL': 'info'
   };
 }
 
+/**
+ * Builds Python-specific environment variables
+ * @param {Object} config - Configuration options
+ * @returns {Object} Python environment variables
+ */
+function buildPythonEnv(config) {
+  const language = config.language || 'typescript';
+  if (language !== 'python') {
+    return {};
+  }
+
+  return {
+    'PYTHONUNBUFFERED': '${PYTHONUNBUFFERED}',
+    'PYTHONDONTWRITEBYTECODE': '${PYTHONDONTWRITEBYTECODE}',
+    'PYTHONIOENCODING': '${PYTHONIOENCODING}'
+  };
+}
+
 function buildDatabaseEnv(config) {
   if (!config.database) {
     return {};
@@ -207,8 +225,9 @@ function buildMonitoringEnv(config) {
   return {
     'MISO_CONTROLLER_URL': config.controllerUrl || 'https://controller.aifabrix.ai',
     'MISO_ENVIRONMENT': 'dev',
-    'MISO_CLIENTID': 'kv://miso-clientid',
-    'MISO_CLIENTSECRET': 'kv://miso-clientsecret'
+    'MISO_CLIENTID': 'kv://miso-controller-client-idKeyVault',
+    'MISO_CLIENTSECRET': 'kv://miso-controller-client-secretKeyVault',
+    'MISO_WEB_SERVER_URL': 'kv://miso-controller-web-server-url'
   };
 }
 
@@ -220,10 +239,17 @@ function buildMonitoringEnv(config) {
 function addCoreVariables(lines, envVars) {
   Object.entries(envVars).forEach(([key, value]) => {
     if (key.startsWith('NODE_ENV') || key.startsWith('PORT') ||
-        key.startsWith('APP_NAME') || key.startsWith('LOG_LEVEL')) {
+        key.startsWith('APP_NAME') || key.startsWith('LOG_LEVEL') ||
+        key.startsWith('PYTHON')) {
       lines.push(`${key}=${value}`);
     }
   });
+
+  // Add ALLOWED_ORIGINS and WEB_SERVER_URL after PORT variable
+  // ALLOWED_ORIGINS: My application public address
+  lines.push('ALLOWED_ORIGINS=http://localhost:*,');
+  // WEB_SERVER_URL: Miso public address (uses ${PORT} template variable)
+  lines.push('WEB_SERVER_URL=http://localhost:${PORT},');
 }
 
 function addMonitoringSection(lines, envVars) {
@@ -232,6 +258,10 @@ function addMonitoringSection(lines, envVars) {
   lines.push(`MISO_ENVIRONMENT=${envVars['MISO_ENVIRONMENT']}`);
   lines.push(`MISO_CLIENTID=${envVars['MISO_CLIENTID']}`);
   lines.push(`MISO_CLIENTSECRET=${envVars['MISO_CLIENTSECRET']}`);
+  // MISO_WEB_SERVER_URL: Miso public address
+  if (envVars['MISO_WEB_SERVER_URL']) {
+    lines.push(`MISO_WEB_SERVER_URL=${envVars['MISO_WEB_SERVER_URL']}`);
+  }
 }
 
 function addDatabaseSection(lines, envVars) {
@@ -316,6 +346,7 @@ function addAuthenticationSection(lines, envVars) {
 function generateEnvTemplate(config, existingEnv = {}) {
   const envVars = {
     ...buildCoreEnv(config),
+    ...buildPythonEnv(config),
     ...buildDatabaseEnv(config),
     ...buildRedisEnv(config),
     ...buildStorageEnv(config),

package/lib/utils/api-error-handler.js

@@ -73,13 +73,11 @@ function formatPermissionError(errorData) {
 
   const requiredPerms = extractRequiredPermissions(errorData);
   addPermissionList(lines, requiredPerms, 'Required permissions');
-
   const requestUrl = errorData.instance || errorData.url;
   const method = errorData.method || 'POST';
   if (requestUrl) {
     lines.push(chalk.gray(`Request: ${method} ${requestUrl}`));
   }
-
   if (errorData.correlationId) {
     lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
   }
@@ -97,18 +95,27 @@ function formatValidationError(errorData) {
   lines.push(chalk.red('❌ Validation Error\n'));
 
   // Handle RFC 7807 Problem Details format
-  // Priority: detail > title > message
+  // Priority: detail > title > errorDescription > message > error
   if (errorData.detail) {
     lines.push(chalk.yellow(errorData.detail));
     lines.push('');
   } else if (errorData.title) {
     lines.push(chalk.yellow(errorData.title));
     lines.push('');
+  } else if (errorData.errorDescription) {
+    // Handle Keycloak-style error format
+    lines.push(chalk.yellow(errorData.errorDescription));
+    if (errorData.error) {
+      lines.push(chalk.gray(`Error code: ${errorData.error}`));
+    }
+    lines.push('');
   } else if (errorData.message) {
     lines.push(chalk.yellow(errorData.message));
     lines.push('');
+  } else if (errorData.error) {
+    lines.push(chalk.yellow(errorData.error));
+    lines.push('');
   }
-
   // Handle errors array - this is the most important part
   if (errorData.errors && Array.isArray(errorData.errors) && errorData.errors.length > 0) {
     lines.push(chalk.yellow('Validation errors:'));
@@ -124,17 +131,14 @@ function formatValidationError(errorData) {
     });
     lines.push('');
   }
-
   // Show instance (endpoint) if available (RFC 7807)
   if (errorData.instance) {
     lines.push(chalk.gray(`Endpoint: ${errorData.instance}`));
   }
-
   // Show correlation ID if available
   if (errorData.correlationId) {
     lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
   }
-
   return lines.join('\n');
 }
 /**
@@ -145,7 +149,6 @@ function formatValidationError(errorData) {
 function formatAuthenticationError(errorData) {
   const lines = [];
   lines.push(chalk.red('❌ Authentication Failed\n'));
-
   if (errorData.message) {
     lines.push(chalk.yellow(errorData.message));
   } else {
@@ -153,11 +156,9 @@ function formatAuthenticationError(errorData) {
   }
   lines.push('');
   lines.push(chalk.gray('Run: aifabrix login'));
-
   if (errorData.correlationId) {
     lines.push(chalk.gray(`Correlation ID: ${errorData.correlationId}`));
   }
-
   return lines.join('\n');
 }
 /**
@@ -379,7 +380,7 @@ function createErrorResult(type, message, formatted, data) {
  * @returns {string} Error message
  */
 function getErrorMessage(errorData, defaultMessage) {
-  return errorData.detail || errorData.title || errorData.message || defaultMessage;
+  return errorData.detail || errorData.title || errorData.errorDescription || errorData.message || errorData.error || defaultMessage;
 }
 
 /**
@@ -486,7 +487,6 @@ function formatApiError(apiResponse) {
   const parsed = parseErrorResponse(errorResponse, statusCode, isNetworkError);
   return parsed.formatted;
 }
-
 module.exports = {
   parseErrorResponse,
   formatApiError,

package/lib/utils/cli-utils.js

@@ -57,7 +57,7 @@ function formatError(error) {
   } else if (errorMsg.includes('Docker') && (errorMsg.includes('not running') || errorMsg.includes('not installed') || errorMsg.includes('Cannot connect'))) {
     messages.push('   Docker is not running or not installed.');
     messages.push('   Please start Docker Desktop and try again.');
-  } else if (errorMsg.includes('port')) {
+  } else if (errorMsg.toLowerCase().includes('port') && (errorMsg.includes('already in use') || errorMsg.includes('in use') || errorMsg.includes('conflict'))) {
     messages.push('   Port conflict detected.');
     messages.push('   Run "aifabrix doctor" to check which ports are in use.');
   } else if ((errorMsg.includes('permission denied') || errorMsg.includes('EACCES') || errorMsg.includes('Permission denied')) && !errorMsg.includes('permissions/') && !errorMsg.includes('Field "permissions')) {
@@ -69,13 +69,13 @@ function formatError(error) {
     messages.push('   Azure CLI is not installed or not working properly.');
     messages.push('   Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
     messages.push('   Run: az login');
+  } else if (errorMsg.includes('Invalid ACR URL') || errorMsg.includes('Invalid registry URL') || errorMsg.includes('Expected format')) {
+    messages.push('   Invalid registry URL format.');
+    messages.push('   Use format: *.azurecr.io (e.g., myacr.azurecr.io)');
   } else if (errorMsg.includes('authenticate') || errorMsg.includes('ACR') || errorMsg.includes('Authentication required')) {
     messages.push('   Azure Container Registry authentication failed.');
     messages.push('   Run: az acr login --name <registry-name>');
     messages.push('   Or login to Azure: az login');
-  } else if (errorMsg.includes('Invalid ACR URL') || errorMsg.includes('Expected format')) {
-    messages.push('   Invalid registry URL format.');
-    messages.push('   Use format: *.azurecr.io (e.g., myacr.azurecr.io)');
   } else if (errorMsg.includes('Registry URL is required')) {
     messages.push('   Registry URL is required.');
     messages.push('   Provide via --registry flag or configure in variables.yaml under image.registry');

package/lib/utils/device-code.js

@@ -140,15 +140,61 @@ function parseTokenResponse(response) {
   };
 }
 
+/**
+ * Creates a validation error with detailed information
+ * @function createValidationError
+ * @param {Object} response - Full API response object
+ * @returns {Error} Validation error with formattedError and errorData attached
+ */
+function createValidationError(response) {
+  const validationError = new Error('Token polling failed: Validation error');
+
+  // Attach formatted error if available (includes detailed validation info with ANSI colors)
+  if (response && response.formattedError) {
+    validationError.formattedError = response.formattedError;
+    validationError.message = `Token polling failed:\n${response.formattedError}`;
+  }
+
+  // Attach error data for programmatic access
+  if (response && response.errorData) {
+    validationError.errorData = response.errorData;
+    validationError.errorType = response.errorType || 'validation';
+
+    // Build detailed message if formattedError not available
+    if (!validationError.formattedError) {
+      const errorData = response.errorData;
+      const detail = errorData.detail || errorData.title || errorData.message || 'Validation error';
+      let errorMsg = `Token polling failed: ${detail}`;
+      // Add validation errors if available
+      if (errorData.errors && Array.isArray(errorData.errors) && errorData.errors.length > 0) {
+        errorMsg += '\n\nValidation errors:';
+        errorData.errors.forEach(err => {
+          const field = err.field || err.path || 'validation';
+          const message = err.message || 'Invalid value';
+          if (field === 'validation' || field === 'unknown') {
+            errorMsg += `\n  • ${message}`;
+          } else {
+            errorMsg += `\n  • ${field}: ${message}`;
+          }
+        });
+      }
+      validationError.message = errorMsg;
+    }
+  }
+
+  return validationError;
+}
+
 /**
  * Handles polling errors
  * @function handlePollingErrors
  * @param {string} error - Error code
  * @param {number} status - HTTP status code
+ * @param {Object} response - Full API response object (for accessing formattedError and errorData)
  * @throws {Error} For fatal errors
  * @returns {boolean} True if should continue polling
  */
-function handlePollingErrors(error, status) {
+function handlePollingErrors(error, status, response) {
   if (error === 'authorization_pending' || status === 202) {
     return true;
   }
@@ -166,6 +212,11 @@ function handlePollingErrors(error, status) {
     return true;
   }
 
+  // Handle validation errors with detailed message
+  if (error === 'validation_error' || status === 400) {
+    throw createValidationError(response);
+  }
+
   throw new Error(`Token polling failed: ${error}`);
 }
 
@@ -187,6 +238,18 @@ async function waitForNextPoll(interval, slowDown) {
  * @returns {string} Error code or 'Unknown error'
  */
 function extractPollingError(response) {
+  // Check for structured error data first (from api-error-handler)
+  if (response.errorData) {
+    const errorData = response.errorData;
+    // For validation errors, return the error type so we can handle it specially
+    if (response.errorType === 'validation') {
+      return 'validation_error';
+    }
+    // Return the error message from structured error
+    return errorData.detail || errorData.title || errorData.message || errorData.error || response.error || 'Unknown error';
+  }
+
+  // Fallback to original extraction logic
   const apiResponse = response.data || {};
   const errorData = typeof apiResponse === 'object' ? apiResponse : {};
   return errorData.error || response.error || 'Unknown error';
@@ -229,7 +292,7 @@ async function processPollingResponse(response, interval) {
   }
 
   const error = extractPollingError(response);
-  const shouldContinue = handlePollingErrors(error, response.status);
+  const shouldContinue = handlePollingErrors(error, response.status, response);
 
   if (shouldContinue) {
     const slowDown = error === 'slow_down';

package/lib/utils/env-template.js

@@ -20,10 +20,11 @@ const logger = require('../utils/logger');
  * @param {string} appKey - Application key
  * @param {string} clientIdKey - Secret key for client ID (e.g., 'myapp-client-idKeyVault')
  * @param {string} clientSecretKey - Secret key for client secret (e.g., 'myapp-client-secretKeyVault')
- * @param {string} controllerUrl - Controller URL (e.g., 'http://localhost:3010' or 'https://controller.aifabrix.ai')
+ * @param {string} _controllerUrl - Controller URL (e.g., 'http://localhost:3010' or 'https://controller.aifabrix.ai')
+ *   Note: This parameter is accepted for compatibility but the template format http://${MISO_HOST}:${MISO_PORT} is used instead
  * @returns {Promise<void>} Resolves when template is updated
  */
-async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, controllerUrl) {
+async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, _controllerUrl) {
   const envTemplatePath = path.join(process.cwd(), 'builder', appKey, 'env.template');
 
   if (!fsSync.existsSync(envTemplatePath)) {
@@ -49,7 +50,7 @@ async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, controlle
     }
 
     if (hasControllerUrl) {
-      content = content.replace(/^MISO_CONTROLLER_URL\s*=.*$/m, `MISO_CONTROLLER_URL=${controllerUrl}`);
+      content = content.replace(/^MISO_CONTROLLER_URL\s*=.*$/m, 'MISO_CONTROLLER_URL=http://${MISO_HOST}:${MISO_PORT}');
     }
 
     // Add missing entries
@@ -62,7 +63,7 @@ async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, controlle
         missingEntries.push(`MISO_CLIENTSECRET=kv://${clientSecretKey}`);
       }
       if (!hasControllerUrl) {
-        missingEntries.push(`MISO_CONTROLLER_URL=${controllerUrl}`);
+        missingEntries.push('MISO_CONTROLLER_URL=http://${MISO_HOST}:${MISO_PORT}');
       }
 
       const misoSection = `# MISO Application Client Credentials (per application)