@aifabrix/builder 2.32.3 → 2.33.1

package/lib/schema/wizard-config.schema.json

@@ -0,0 +1,234 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/wizard-config.schema.json",
+  "title": "AI Fabrix Wizard Configuration Schema",
+  "description": "Schema for validating wizard.yaml configuration files for headless external system creation",
+  "type": "object",
+  "required": ["appName", "mode", "source"],
+  "properties": {
+    "appName": {
+      "type": "string",
+      "description": "Application name (must be lowercase alphanumeric with hyphens and underscores)",
+      "pattern": "^[a-z0-9-_]+$",
+      "minLength": 1,
+      "maxLength": 50
+    },
+    "mode": {
+      "type": "string",
+      "description": "Wizard mode",
+      "enum": ["create-system", "add-datasource"]
+    },
+    "systemIdOrKey": {
+      "type": "string",
+      "description": "Existing system ID or key (required when mode='add-datasource')",
+      "pattern": "^[a-z0-9-]+$",
+      "minLength": 1,
+      "maxLength": 50
+    },
+    "source": {
+      "type": "object",
+      "description": "Source configuration for the wizard",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Source type",
+          "enum": ["openapi-file", "openapi-url", "mcp-server", "known-platform"]
+        },
+        "filePath": {
+          "type": "string",
+          "description": "Path to OpenAPI file (for openapi-file type)",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "OpenAPI URL (for openapi-url type)",
+          "pattern": "^https?://.*$"
+        },
+        "serverUrl": {
+          "type": "string",
+          "description": "MCP server URL (for mcp-server type)",
+          "pattern": "^https?://.*$"
+        },
+        "token": {
+          "type": "string",
+          "description": "MCP server authentication token (supports ${ENV_VAR} syntax)",
+          "minLength": 1
+        },
+        "platform": {
+          "type": "string",
+          "description": "Known platform identifier (for known-platform type)",
+          "enum": ["hubspot", "salesforce", "zendesk", "slack", "microsoft365"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "openapi-file" } }
+          },
+          "then": {
+            "required": ["filePath"]
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "openapi-url" } }
+          },
+          "then": {
+            "required": ["url"]
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "mcp-server" } }
+          },
+          "then": {
+            "required": ["serverUrl", "token"]
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "known-platform" } }
+          },
+          "then": {
+            "required": ["platform"]
+          }
+        }
+      ]
+    },
+    "credential": {
+      "type": "object",
+      "description": "Credential configuration for the wizard (optional)",
+      "required": ["action"],
+      "properties": {
+        "action": {
+          "type": "string",
+          "description": "Credential action",
+          "enum": ["create", "select", "skip"]
+        },
+        "credentialIdOrKey": {
+          "type": "string",
+          "description": "Credential ID or key (required when action='select')",
+          "minLength": 1
+        },
+        "config": {
+          "type": "object",
+          "description": "Credential configuration (required when action='create')",
+          "properties": {
+            "key": {
+              "type": "string",
+              "description": "Credential key",
+              "pattern": "^[a-z0-9-]+$",
+              "minLength": 1
+            },
+            "displayName": {
+              "type": "string",
+              "description": "Credential display name",
+              "minLength": 1
+            },
+            "type": {
+              "type": "string",
+              "description": "Credential type",
+              "enum": ["OAUTH2", "API_KEY", "BASIC", "BEARER"]
+            },
+            "config": {
+              "type": "object",
+              "description": "Credential-specific configuration",
+              "additionalProperties": true
+            }
+          },
+          "required": ["key", "displayName", "type"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "action": { "const": "select" } }
+          },
+          "then": {
+            "required": ["credentialIdOrKey"]
+          }
+        },
+        {
+          "if": {
+            "properties": { "action": { "const": "create" } }
+          },
+          "then": {
+            "required": ["config"]
+          }
+        }
+      ]
+    },
+    "preferences": {
+      "type": "object",
+      "description": "Generation preferences",
+      "properties": {
+        "intent": {
+          "type": "string",
+          "description": "User intent (any descriptive text, e.g., 'sales-focused CRM integration')",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "fieldOnboardingLevel": {
+          "type": "string",
+          "description": "Field onboarding level",
+          "enum": ["full", "standard", "minimal"],
+          "default": "full"
+        },
+        "enableOpenAPIGeneration": {
+          "type": "boolean",
+          "description": "Enable OpenAPI operation generation",
+          "default": true
+        },
+        "enableMCP": {
+          "type": "boolean",
+          "description": "Enable Model Context Protocol",
+          "default": false
+        },
+        "enableABAC": {
+          "type": "boolean",
+          "description": "Enable Attribute-Based Access Control",
+          "default": false
+        },
+        "enableRBAC": {
+          "type": "boolean",
+          "description": "Enable Role-Based Access Control",
+          "default": false
+        }
+      }
+    },
+    "deployment": {
+      "type": "object",
+      "description": "Deployment settings (optional overrides)",
+      "properties": {
+        "controller": {
+          "type": "string",
+          "description": "Controller URL",
+          "pattern": "^https?://.*$"
+        },
+        "environment": {
+          "type": "string",
+          "description": "Environment key",
+          "enum": ["dev", "tst", "pro", "miso"],
+          "default": "dev"
+        },
+        "dataplane": {
+          "type": "string",
+          "description": "Dataplane URL (overrides controller lookup)",
+          "pattern": "^https?://.*$"
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "mode": { "const": "add-datasource" } }
+      },
+      "then": {
+        "required": ["systemIdOrKey"]
+      }
+    }
+  ],
+  "additionalProperties": false
+}

package/lib/utils/api.js

@@ -13,6 +13,9 @@
 const { parseErrorResponse } = require('./api-error-handler');
 const auditLogger = require('../core/audit-logger');
 
+/** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+
 /**
  * Logs API request performance metrics and errors to audit log
  * @param {Object} params - Performance logging parameters
@@ -128,6 +131,32 @@ async function handleSuccessResponse(response, url, options, duration) {
   return { success: true, data: text, status: response.status };
 }
 
+/**
+ * Validates that a URL is not empty or missing
+ * @function validateUrl
+ * @param {string} url - URL to validate
+ * @param {string} [urlType='URL'] - Type of URL for error message (e.g., 'Dataplane URL', 'Controller URL')
+ * @returns {void}
+ * @throws {Error} If URL is empty, null, undefined, whitespace-only, or malformed
+ */
+function validateUrl(url, urlType = 'URL') {
+  if (!url || typeof url !== 'string') {
+    throw new Error(`${urlType} is required and must be a string (received: ${JSON.stringify(url)})`);
+  }
+  const trimmedUrl = url.trim();
+  if (!trimmedUrl) {
+    throw new Error(`${urlType} cannot be empty. Please provide a valid URL.`);
+  }
+  // Check for common invalid URL patterns
+  if (trimmedUrl === 'undefined' || trimmedUrl === 'null' || trimmedUrl === 'NaN') {
+    throw new Error(`${urlType} is invalid: "${trimmedUrl}". Please provide a valid URL.`);
+  }
+  // Basic URL format validation - must start with http:// or https://
+  if (!trimmedUrl.match(/^https?:\/\//i)) {
+    throw new Error(`${urlType} must be a valid HTTP/HTTPS URL (received: "${trimmedUrl}")`);
+  }
+}
+
 /**
  * Handles network error from API call
  * @async
@@ -139,7 +168,34 @@ async function handleSuccessResponse(response, url, options, duration) {
  * @returns {Promise<Object>} Error response object
  */
 async function handleNetworkError(error, url, options, duration) {
-  const parsedError = parseErrorResponse(error.message, 0, true);
+  // Enhance error message with URL information if URL is missing or invalid
+  let errorMessage = error.message;
+  if (errorMessage && (errorMessage.includes('cannot be empty') || errorMessage.includes('is required'))) {
+    // Add URL context to validation errors
+    if (!url || !url.trim()) {
+      errorMessage = `${errorMessage} (URL was: ${JSON.stringify(url)})`;
+    } else {
+      errorMessage = `${errorMessage} (URL was: ${url})`;
+    }
+  } else if (!url || !url.trim()) {
+    // If URL is empty but error doesn't mention it, add context
+    errorMessage = `Invalid or missing URL. ${errorMessage} (URL was: ${JSON.stringify(url)})`;
+  }
+
+  const parsedError = parseErrorResponse(errorMessage, 0, true);
+
+  // Extract controller URL from full URL for error data
+  let controllerUrl = null;
+  const endpointUrl = url;
+  if (url && typeof url === 'string' && url.trim()) {
+    try {
+      const urlObj = new URL(url);
+      controllerUrl = `${urlObj.protocol}//${urlObj.host}`;
+    } catch {
+      // If URL parsing fails, use the full URL as endpoint
+      controllerUrl = null;
+    }
+  }
 
   await logApiPerformance({
     url,
@@ -154,10 +210,17 @@ async function handleNetworkError(error, url, options, duration) {
     }
   });
 
+  // Include both controller URL and full endpoint URL in error data
+  const errorData = {
+    ...parsedError.data,
+    controllerUrl: controllerUrl,
+    endpointUrl: endpointUrl
+  };
+
   return {
     success: false,
     error: parsedError.message,
-    errorData: parsedError.data,
+    errorData: errorData,
     errorType: parsedError.type,
     formattedError: parsedError.formatted,
     network: true
@@ -166,15 +229,28 @@ async function handleNetworkError(error, url, options, duration) {
 
 /**
  * Make an API call with proper error handling
+ * Uses a 15s timeout to avoid hanging when the controller is unreachable.
  * @param {string} url - API endpoint URL
- * @param {Object} options - Fetch options
+ * @param {Object} options - Fetch options (signal, method, headers, body, etc.)
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
+  // Validate URL before attempting request
+  try {
+    validateUrl(url, 'API endpoint URL');
+  } catch (error) {
+    const duration = 0;
+    return await handleNetworkError(error, url || '', options, duration);
+  }
+
   const startTime = Date.now();
+  const fetchOptions = { ...options };
+  if (!fetchOptions.signal) {
+    fetchOptions.signal = AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+  }
 
   try {
-    const response = await fetch(url, options);
+    const response = await fetch(url, fetchOptions);
     const duration = Date.now() - startTime;
 
     if (!response.ok) {
@@ -182,8 +258,13 @@ async function makeApiCall(url, options = {}) {
     }
 
     return await handleSuccessResponse(response, url, options, duration);
-  } catch (error) {
+  } catch (err) {
     const duration = Date.now() - startTime;
+    const error = err?.name === 'AbortError'
+      ? new Error(
+        `Request timed out after ${DEFAULT_REQUEST_TIMEOUT_MS / 1000} seconds. The controller may be unreachable. Check the URL and network.`
+      )
+      : err;
     return await handleNetworkError(error, url, options, duration);
   }
 }
@@ -214,20 +295,16 @@ function extractControllerUrl(url) {
  * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
+// eslint-disable-next-line max-statements
 async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
-  // Support both string token (backward compat) and authConfig object
-  const token = typeof tokenOrAuthConfig === 'string'
-    ? tokenOrAuthConfig
-    : tokenOrAuthConfig?.token;
-  const authControllerUrl = typeof tokenOrAuthConfig === 'object'
-    ? tokenOrAuthConfig?.controller
-    : null;
-
-  const headers = {
-    'Content-Type': 'application/json',
-    ...options.headers
-  };
-
+  const isStringToken = typeof tokenOrAuthConfig === 'string';
+  const token = isStringToken ? tokenOrAuthConfig : tokenOrAuthConfig?.token;
+  const authControllerUrl = isStringToken ? null : tokenOrAuthConfig?.controller;
+  const isFormData = typeof FormData !== 'undefined' && options.body instanceof FormData;
+  const headers = { ...options.headers };
+  if (!isFormData && !headers['Content-Type']) {
+    headers['Content-Type'] = 'application/json';
+  }
   if (token) {
     headers['Authorization'] = `Bearer ${token}`;
   }
@@ -237,46 +314,19 @@ async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
     headers
   });
 
-  // Handle 401 errors with automatic token refresh for device tokens
   if (!response.success && response.status === 401) {
     try {
-      // Use controller URL from authConfig if available, otherwise extract from request URL
-      // This is important when the request URL is a dataplane URL but the token
-      // is stored under the controller URL
-      const controllerUrl = authControllerUrl || extractControllerUrl(url);
-
-      // Try to force refresh device token on 401 (regardless of local expiry time)
-      // because the server rejected the token
       const { forceRefreshDeviceToken } = require('./token-manager');
-      const refreshedToken = await forceRefreshDeviceToken(controllerUrl);
-
-      if (refreshedToken && refreshedToken.token) {
-        // Retry request with new token
+      const refreshedToken = await forceRefreshDeviceToken(authControllerUrl || extractControllerUrl(url));
+      if (refreshedToken?.token) {
         headers['Authorization'] = `Bearer ${refreshedToken.token}`;
-        const retryResponse = await makeApiCall(url, {
-          ...options,
-          headers
-        });
-        return retryResponse;
-      }
-
-      // Token refresh failed or no refresh token available
-      // Return a more helpful error message
-      if (!refreshedToken) {
-        return {
-          ...response,
-          error: 'Authentication failed: Token expired and refresh failed. Please login again using: aifabrix login',
-          formattedError: 'Authentication failed: Token expired and refresh failed. Please login again using: aifabrix login'
-        };
+        return await makeApiCall(url, { ...options, headers });
       }
+      const authError = 'Authentication failed: Token expired and refresh failed. Please login again using: aifabrix login';
+      return { ...response, error: authError, formattedError: authError };
     } catch (refreshError) {
-      // Refresh failed, return original 401 error with additional context
-      const errorMessage = refreshError.message || String(refreshError);
-      return {
-        ...response,
-        error: `Authentication failed: ${errorMessage}. Please login again using: aifabrix login`,
-        formattedError: `Authentication failed: ${errorMessage}. Please login again using: aifabrix login`
-      };
+      const authError = `Authentication failed: ${refreshError.message || String(refreshError)}. Please login again using: aifabrix login`;
+      return { ...response, error: authError, formattedError: authError };
     }
   }
 

package/lib/utils/app-existence.js

@@ -0,0 +1,42 @@
+/**
+ * Application Existence Check Utility
+ *
+ * Checks if an application exists in an environment before deployment.
+ *
+ * @fileoverview Application existence checking for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { getEnvironmentApplication } = require('../api/environments.api');
+
+/**
+ * Check if application exists in the environment
+ * Uses device token auth to check existence (doesn't require app credentials)
+ * @async
+ * @function checkApplicationExists
+ * @param {string} appKey - Application key
+ * @param {string} controllerUrl - Controller URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Authentication configuration (device token)
+ * @returns {Promise<boolean>} True if application exists, false otherwise
+ */
+async function checkApplicationExists(appKey, controllerUrl, envKey, authConfig) {
+  try {
+    // Use device token auth (bearer token) to check if app exists
+    // This doesn't require app credentials, so it works even if credentials are wrong
+    const deviceAuthConfig = { type: 'bearer', token: authConfig.token };
+    const response = await getEnvironmentApplication(controllerUrl, envKey, appKey, deviceAuthConfig);
+    return response.success && response.data !== null && response.data !== undefined;
+  } catch (error) {
+    // If 404, application doesn't exist
+    if (error.status === 404 || (error.response && error.response.status === 404)) {
+      return false;
+    }
+    // For other errors (including 401 if device token is invalid), we can't determine existence
+    // Return false to avoid blocking deployment - the validation step will catch credential issues
+    return false;
+  }
+}
+
+module.exports = { checkApplicationExists };

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

@@ -14,6 +14,7 @@ const chalk = require('chalk');
 const yaml = require('js-yaml');
 const logger = require('./logger');
 const { detectAppType } = require('./paths');
+const { getContainerPort, getLocalPort } = require('./port-resolver');
 
 // createApp is imported dynamically in createMinimalAppIfNeeded to handle test mocking
 
@@ -238,9 +239,11 @@ async function extractExternalAppConfiguration(appKey, variables, appKeyFromFile
 function extractWebappConfiguration(variables, appKeyFromFile, displayName, description, options) {
   const appType = variables.build?.language === 'typescript' ? 'webapp' : 'service';
   const registryMode = variables.image?.registryMode || 'external';
-  const port = variables.build?.port || options.port || 3000;
+  const port = options.port ?? getContainerPort(variables, 3000);
+  const localPort = getLocalPort(variables, port);
   const language = variables.build?.language || 'typescript';
   const image = buildImageReference(variables, appKeyFromFile);
+  const url = variables.app?.url || variables.deployment?.dataplaneUrl || variables.deployment?.appUrl || null;
 
   return {
     appKey: appKeyFromFile,
@@ -249,8 +252,10 @@ function extractWebappConfiguration(variables, appKeyFromFile, displayName, desc
     appType,
     registryMode,
     port,
+    localPort,
     image,
-    language
+    language,
+    url
   };
 }
 

package/lib/utils/auth-config-validator.js

@@ -0,0 +1,92 @@
+/**
+ * Authentication Configuration Validators
+ *
+ * Provides validation functions for authentication configuration commands
+ *
+ * @fileoverview Authentication configuration validators
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { getControllerUrlFromLoggedInUser } = require('./controller-url');
+
+/**
+ * Validate controller URL format
+ * @function validateControllerUrl
+ * @param {string} url - Controller URL to validate
+ * @throws {Error} If URL format is invalid
+ */
+function validateControllerUrl(url) {
+  if (!url || typeof url !== 'string') {
+    throw new Error('Controller URL is required and must be a string');
+  }
+
+  const trimmed = url.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Controller URL cannot be empty');
+  }
+
+  // Basic URL validation - must start with http:// or https://
+  if (!trimmed.match(/^https?:\/\//)) {
+    throw new Error('Controller URL must start with http:// or https://');
+  }
+
+  try {
+    // Use URL constructor for more thorough validation
+    new URL(trimmed);
+  } catch (error) {
+    throw new Error(`Invalid controller URL format: ${error.message}`);
+  }
+}
+
+/**
+ * Validate environment key format
+ * @function validateEnvironment
+ * @param {string} env - Environment key to validate
+ * @throws {Error} If environment format is invalid
+ */
+function validateEnvironment(env) {
+  if (!env || typeof env !== 'string') {
+    throw new Error('Environment is required and must be a string');
+  }
+
+  const trimmed = env.trim();
+  if (trimmed.length === 0) {
+    throw new Error('Environment cannot be empty');
+  }
+
+  // Environment key must contain only letters, numbers, hyphens, and underscores
+  if (!/^[a-z0-9-_]+$/i.test(trimmed)) {
+    throw new Error('Environment must contain only letters, numbers, hyphens, and underscores');
+  }
+}
+
+/**
+ * Check if user is logged in to a controller
+ * @async
+ * @function checkUserLoggedIn
+ * @param {string} controllerUrl - Controller URL to check
+ * @returns {Promise<boolean>} True if user has device token for this controller
+ */
+async function checkUserLoggedIn(controllerUrl) {
+  if (!controllerUrl) {
+    return false;
+  }
+
+  const normalizedUrl = controllerUrl.trim().replace(/\/+$/, '');
+  const loggedInControllerUrl = await getControllerUrlFromLoggedInUser();
+
+  if (!loggedInControllerUrl) {
+    return false;
+  }
+
+  // Normalize both URLs for comparison
+  const normalizedLoggedIn = loggedInControllerUrl.trim().replace(/\/+$/, '');
+  return normalizedLoggedIn === normalizedUrl;
+}
+
+module.exports = {
+  validateControllerUrl,
+  validateEnvironment,
+  checkUserLoggedIn
+};

package/lib/utils/command-header.js

@@ -0,0 +1,43 @@
+/**
+ * Command Header Display Utility
+ *
+ * Displays active configuration (controller, environment, dataplane) at top of commands
+ *
+ * @fileoverview Command header display utility
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/**
+ * Display command header with active configuration
+ * @function displayCommandHeader
+ * @param {string} controllerUrl - Controller URL
+ * @param {string} environment - Environment key
+ * @param {string} [dataplaneUrl] - Dataplane URL (optional)
+ */
+function displayCommandHeader(controllerUrl, environment, dataplaneUrl) {
+  const parts = [];
+
+  if (controllerUrl) {
+    parts.push(`Controller: ${chalk.cyan(controllerUrl)}`);
+  }
+
+  if (environment) {
+    parts.push(`Environment: ${chalk.cyan(environment)}`);
+  }
+
+  if (dataplaneUrl) {
+    parts.push(`Dataplane: ${chalk.cyan(dataplaneUrl)}`);
+  }
+
+  if (parts.length > 0) {
+    logger.log(chalk.gray(`\n${parts.join(' | ')}\n`));
+  }
+}
+
+module.exports = {
+  displayCommandHeader
+};