@aifabrix/builder 2.43.0 → 2.44.1

package/lib/schema/type/message-service.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "aifabrix://schema/type/message-service.json",
+  "title": "Message Service Configuration Schema",
+  "description": "Internal schema for validating message service configurations in ExternalDataSource. Supports Slack, Teams, and Email message services for notifications.",
+  "metadata": {
+    "key": "message-service-schema",
+    "name": "Message Service Configuration Schema",
+    "description": "JSON schema for validating message service configurations",
+    "version": "1.0.0",
+    "type": "schema",
+    "category": "message-service",
+    "author": "AI Fabrix Team",
+    "createdAt": "2026-01-15T00:00:00Z",
+    "updatedAt": "2026-01-15T00:00:00Z",
+    "compatibility": {
+      "minVersion": "1.0.0",
+      "maxVersion": "2.0.0",
+      "deprecated": false
+    },
+    "tags": [
+      "schema",
+      "message-service",
+      "dataplane",
+      "validation",
+      "notifications"
+    ],
+    "dependencies": [],
+    "changelog": [
+      {
+        "version": "1.0.0",
+        "date": "2026-01-15T00:00:00Z",
+        "changes": [
+          "Initial schema for message service validation",
+          "Support for Slack, Teams, and Email message services",
+          "CIP-based configuration for Slack and Teams",
+          "Provider-based configuration for Email (SendGrid, SES, SMTP)"
+        ],
+        "breaking": false
+      }
+    ]
+  },
+  "type": "object",
+  "required": ["enabled", "messageServiceType"],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether message service is enabled"
+    },
+    "messageServiceType": {
+      "type": "string",
+      "enum": ["slack", "teams", "email"],
+      "description": "Type of message service: 'slack' for Slack notifications, 'teams' for Microsoft Teams notifications, 'email' for email notifications"
+    },
+    "datasourceKey": {
+      "type": "string",
+      "description": "ExternalDataSource key for CIP-based services (Slack, Teams). Required when messageServiceType is 'slack' or 'teams'."
+    },
+    "email": {
+      "type": "object",
+      "description": "Email service configuration (required when messageServiceType is 'email')",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["sendgrid", "ses", "smtp"],
+          "description": "Email provider: 'sendgrid' for SendGrid API, 'ses' for AWS SES, 'smtp' for SMTP server"
+        },
+        "apiKey": {
+          "type": "string",
+          "description": "API key for SendGrid (required when provider is 'sendgrid')"
+        },
+        "accessKey": {
+          "type": "string",
+          "description": "AWS access key for SES (required when provider is 'ses')"
+        },
+        "secretKey": {
+          "type": "string",
+          "description": "AWS secret key for SES (required when provider is 'ses')"
+        },
+        "region": {
+          "type": "string",
+          "description": "AWS region for SES (required when provider is 'ses')"
+        },
+        "host": {
+          "type": "string",
+          "description": "SMTP server host (required when provider is 'smtp')"
+        },
+        "port": {
+          "type": "integer",
+          "description": "SMTP server port (required when provider is 'smtp')"
+        },
+        "useTls": {
+          "type": "boolean",
+          "default": true,
+          "description": "Use TLS for SMTP (when provider is 'smtp')"
+        },
+        "username": {
+          "type": "string",
+          "description": "SMTP username (optional when provider is 'smtp')"
+        },
+        "password": {
+          "type": "string",
+          "description": "SMTP password (optional when provider is 'smtp')"
+        },
+        "fromEmail": {
+          "type": "string",
+          "description": "From email address (required when messageServiceType is 'email')"
+        },
+        "recipients": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Default recipient email addresses (optional)"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}
+

package/lib/schema/type/vector-store.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "aifabrix://schema/type/vector-store.json",
+  "title": "Vector Store Configuration Schema",
+  "description": "Internal schema for validating vector-store type ExternalSystem configurations. Enforces semantic constraints: no filtering, no hybrid search, ID-constrained scoring only.",
+  "metadata": {
+    "key": "vector-store-schema",
+    "name": "Vector Store Configuration Schema",
+    "description": "JSON schema for validating vector-store type ExternalSystem configurations",
+    "version": "1.0.0",
+    "type": "schema",
+    "category": "vector-store",
+    "author": "AI Fabrix Team",
+    "createdAt": "2026-01-02T00:00:00Z",
+    "updatedAt": "2026-01-02T00:00:00Z",
+    "compatibility": {
+      "minVersion": "1.0.0",
+      "maxVersion": "2.0.0",
+      "deprecated": false
+    },
+    "tags": [
+      "schema",
+      "vector-store",
+      "dataplane",
+      "validation"
+    ],
+    "dependencies": [],
+    "changelog": [
+      {
+        "version": "1.0.0",
+        "date": "2026-01-02T00:00:00Z",
+        "changes": [
+          "Initial schema for vector-store type validation",
+          "Enforces no filtering and no hybrid search constraints",
+          "Defines required capabilities: score, upsert, delete"
+        ],
+        "breaking": false
+      }
+    ]
+  },
+  "type": "object",
+  "required": ["dimensions", "distanceMetric", "capabilities"],
+  "properties": {
+    "dimensions": {
+      "type": "integer",
+      "minimum": 128,
+      "description": "Embedding vector dimensions (e.g., 1536 for OpenAI text-embedding-ada-002)"
+    },
+    "distanceMetric": {
+      "type": "string",
+      "enum": ["cosine", "dot"],
+      "description": "Distance metric for similarity scoring. 'cosine' uses cosine similarity, 'dot' uses dot product."
+    },
+    "capabilities": {
+      "type": "object",
+      "required": ["score", "upsert", "delete"],
+      "properties": {
+        "score": {
+          "type": "boolean",
+          "description": "Supports similarity scoring operation. Must be true for vector stores."
+        },
+        "upsert": {
+          "type": "boolean",
+          "description": "Supports vector upsert operation. Must be true for vector stores."
+        },
+        "delete": {
+          "type": "boolean",
+          "description": "Supports vector deletion operation. Must be true for vector stores."
+        },
+        "stats": {
+          "type": "boolean",
+          "description": "Supports index statistics/health check operation. Optional capability."
+        },
+        "filter": {
+          "const": false,
+          "description": "Filtering is explicitly forbidden - vector stores do not filter. This must be false or absent."
+        },
+        "hybridSearch": {
+          "const": false,
+          "description": "Hybrid search is explicitly forbidden - vector stores only score pre-authorized IDs. This must be false or absent."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}
+

package/lib/utils/aifabrix-runtime-config-dir.js

@@ -0,0 +1,132 @@
+/**
+ * Resolves the directory that contains `config.yaml` for CLI runtime.
+ * Shared by `paths.getConfigDirForPaths` and `config.getConfigDir` (no circular imports).
+ *
+ * When `AIFABRIX_HOME` is set to the POSIX home (builder-server pattern) but the real
+ * config file is under `~/.aifabrix/config.yaml`, use that nested directory so
+ * `secrets.local.yaml` and auth config stay beside `config.yaml`.
+ *
+ * Relative `AIFABRIX_HOME` / `AIFABRIX_CONFIG` values are anchored to the user home
+ * directory (not `process.cwd()`), so a mistaken `aifabrix-training` does not become
+ * `/aifabrix-training` when the shell cwd is `/` (EACCES on mkdir).
+ * Paths starting with `./` or `../` still resolve from cwd for project-local overrides.
+ *
+ * @fileoverview AIFABRIX_CONFIG / AIFABRIX_HOME → config directory
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { existsSync } = require('../internal/fs-real-sync');
+const path = require('path');
+const os = require('os');
+
+/**
+ * @returns {string}
+ */
+function safeHomedir() {
+  try {
+    const h = os.homedir();
+    if (typeof h === 'string' && h.length > 0) {
+      return h;
+    }
+  } catch {
+    // ignore
+  }
+  return process.env.HOME || process.env.USERPROFILE || '/';
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function expandLeadingTilde(raw) {
+  const t = typeof raw === 'string' ? raw.trim() : '';
+  if (!t) {
+    return t;
+  }
+  if (t === '~') {
+    return safeHomedir();
+  }
+  if (t.startsWith('~/') || t.startsWith('~\\')) {
+    return path.join(safeHomedir(), t.slice(2));
+  }
+  return t;
+}
+
+/**
+ * True when the path is explicitly relative to cwd (project-local).
+ * @param {string} t
+ * @returns {boolean}
+ */
+function isExplicitRelativeToCwd(t) {
+  if (t === '.' || t === '..') {
+    return true;
+  }
+  return (
+    t.startsWith('./') ||
+    t.startsWith('../') ||
+    t.startsWith('.\\') ||
+    t.startsWith('..\\')
+  );
+}
+
+/**
+ * Resolve `AIFABRIX_HOME` and config `aifabrix-home`: bare relative segments live under user home.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function resolveAifabrixHomeLikePath(raw) {
+  const expanded = expandLeadingTilde(raw);
+  if (!expanded) {
+    return expanded;
+  }
+  if (path.isAbsolute(expanded)) {
+    return path.normalize(expanded);
+  }
+  if (isExplicitRelativeToCwd(expanded)) {
+    return path.resolve(expanded);
+  }
+  return path.resolve(safeHomedir(), expanded);
+}
+
+/**
+ * Resolve `AIFABRIX_CONFIG`: same rules as home-like (bare `foo/bar.yaml` → under ~).
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function resolveAifabrixConfigEnvPath(raw) {
+  return resolveAifabrixHomeLikePath(raw);
+}
+
+/**
+ * @returns {string} Absolute directory containing `config.yaml`
+ */
+function getAifabrixRuntimeConfigDir() {
+  if (process.env.AIFABRIX_CONFIG && typeof process.env.AIFABRIX_CONFIG === 'string') {
+    const resolved = resolveAifabrixConfigEnvPath(process.env.AIFABRIX_CONFIG.trim());
+    return path.dirname(resolved);
+  }
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    const homeDir = resolveAifabrixHomeLikePath(process.env.AIFABRIX_HOME.trim());
+    const directConfig = path.join(homeDir, 'config.yaml');
+    if (existsSync(directConfig)) {
+      return homeDir;
+    }
+    const nestedConfig = path.join(homeDir, '.aifabrix', 'config.yaml');
+    if (existsSync(nestedConfig)) {
+      return path.join(homeDir, '.aifabrix');
+    }
+    return homeDir;
+  }
+  return path.join(safeHomedir(), '.aifabrix');
+}
+
+module.exports = {
+  getAifabrixRuntimeConfigDir,
+  resolveAifabrixHomeLikePath,
+  resolveAifabrixConfigEnvPath
+};

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

@@ -10,7 +10,7 @@
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
+const { formatBlockingError } = require('./cli-test-layout-chalk');
 const { parseErrorResponse } = require('./error-formatters/error-parser');
 const { formatPermissionError } = require('./error-formatters/permission-errors');
 const { formatValidationError } = require('./error-formatters/validation-errors');
@@ -30,7 +30,7 @@ const { formatNetworkError } = require('./error-formatters/network-errors');
  */
 function formatApiError(apiResponse, controllerUrl = null) {
   if (!apiResponse || apiResponse.success !== false) {
-    return chalk.red('❌ Unknown error occurred');
+    return formatBlockingError('Unknown error occurred');
   }
 
   // Use formattedError if already available

package/lib/utils/api.js

@@ -16,6 +16,26 @@ const auditLogger = require('../core/audit-logger');
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 
+/** Cap for optional per-request ``timeoutMs`` (validation run E2E can block on one POST). */
+const MAX_SINGLE_REQUEST_TIMEOUT_MS = 45 * 60 * 1000;
+
+/**
+ * Resolve per-request AbortSignal timeout from fetch options.
+ * @param {Object} options - Same object passed to fetch (may include timeoutMs / requestTimeoutMs)
+ * @returns {number}
+ */
+function resolveSingleRequestTimeoutMs(options) {
+  const raw = options?.requestTimeoutMs ?? options?.timeoutMs;
+  if (raw === undefined || raw === null || raw === '') {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+  return Math.min(n, MAX_SINGLE_REQUEST_TIMEOUT_MS);
+}
+
 /**
  * Logs API request performance metrics and errors to audit log
  * @param {Object} params - Performance logging parameters
@@ -169,6 +189,51 @@ function validateUrl(url, urlType = 'URL') {
   }
 }
 
+/**
+ * Flattens Error.message and nested error.cause (Node fetch/undici wraps TLS errors under cause).
+ * @param {Error} error - Network error
+ * @returns {string} Combined detail for parsing and SSL detection
+ */
+function flattenNetworkErrorDetail(error) {
+  if (!error) return '';
+  const parts = [];
+  let e = error;
+  let depth = 0;
+  const maxDepth = 12;
+  while (e && depth < maxDepth) {
+    if (typeof e === 'string') {
+      parts.push(e);
+      break;
+    }
+    if (e.message) parts.push(e.message);
+    if (e.code !== undefined && e.code !== null && String(e.code) !== e.message) {
+      parts.push(String(e.code));
+    }
+    e = e.cause;
+    depth++;
+  }
+  return parts.filter(Boolean).join(' ');
+}
+
+/**
+ * Adds URL context to validation / empty-URL network errors.
+ * @param {string} errorMessage - Base message
+ * @param {string} url - Request URL
+ * @returns {string}
+ */
+function withUrlContextForNetworkError(errorMessage, url) {
+  if (errorMessage && (errorMessage.includes('cannot be empty') || errorMessage.includes('is required'))) {
+    if (!url || !url.trim()) {
+      return `${errorMessage} (URL was: ${JSON.stringify(url)})`;
+    }
+    return `${errorMessage} (URL was: ${url})`;
+  }
+  if (!url || !url.trim()) {
+    return `Invalid or missing URL. ${errorMessage} (URL was: ${JSON.stringify(url)})`;
+  }
+  return errorMessage;
+}
+
 /**
  * Handles network error from API call
  * @async
@@ -180,19 +245,8 @@ function validateUrl(url, urlType = 'URL') {
  * @returns {Promise<Object>} Error response object
  */
 async function handleNetworkError(error, url, options, duration) {
-  // 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 flat = flattenNetworkErrorDetail(error);
+  const errorMessage = withUrlContextForNetworkError(flat || error.message, url);
 
   const parsedError = parseErrorResponse(errorMessage, 0, true);
 
@@ -235,15 +289,18 @@ async function handleNetworkError(error, url, options, duration) {
     errorData: errorData,
     errorType: parsedError.type,
     formattedError: parsedError.formatted,
-    network: true
+    network: true,
+    originalError: error
   };
 }
 
 /**
  * Make an API call with proper error handling
- * Uses a 30s timeout to avoid hanging when the controller is unreachable (Azure cold start can exceed 5s).
+ * Uses a 30s timeout by default. Pass ``options.timeoutMs`` or ``options.requestTimeoutMs`` for
+ * longer single requests (e.g. dataplane validation run E2E POST); capped at 45 minutes.
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options (signal, method, headers, body, etc.)
+ * @param {number} [options.timeoutMs] - Optional per-request timeout (ms) when ``signal`` omitted
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
@@ -257,9 +314,12 @@ async function makeApiCall(url, options = {}) {
 
   const startTime = Date.now();
   const fetchOptions = { ...options };
+  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
   if (!fetchOptions.signal) {
-    fetchOptions.signal = AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
   }
+  delete fetchOptions.timeoutMs;
+  delete fetchOptions.requestTimeoutMs;
 
   try {
     const response = await fetch(url, fetchOptions);
@@ -274,7 +334,7 @@ async function makeApiCall(url, options = {}) {
     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.`
+        `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The controller may be unreachable. Check the URL and network.`
       )
       : err;
     return await handleNetworkError(error, url, options, duration);

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

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('./cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App Register API Utilities
  *
@@ -72,7 +73,7 @@ function extractApplicationData(response, apiUrl) {
   }
 
   // Fallback: return apiResponse as-is (shouldn't happen, but handle gracefully)
-  logger.error(chalk.red('❌ Invalid response: missing application data'));
+  logger.error(formatBlockingError('Invalid response: missing application data'));
   logger.error(chalk.gray(`\nController URL: ${apiUrl}`));
   logger.error(chalk.gray('\nFull response for debugging:'));
   logger.error(chalk.gray(JSON.stringify(response, null, 2)));
@@ -93,7 +94,7 @@ async function callRegisterApi(apiUrl, token, environment, registrationData) {
     return extractApplicationData(response, apiUrl);
   } catch (error) {
     // Include controller URL in error context
-    logger.error(chalk.red('❌ Registration API call failed'));
+    logger.error(formatBlockingError('Registration API call failed'));
     logger.error(chalk.gray(`Controller URL: ${apiUrl}`));
     logger.error(chalk.gray(`Error: ${error.message}`));
     throw error;

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

@@ -108,7 +108,7 @@ async function tryGetDeviceTokenForController(controllerUrl, attemptedUrls) {
       };
     }
   } catch (error) {
-    logger.warn(chalk.yellow(`⚠️  Failed to get token for controller ${controllerUrl}: ${error.message}`));
+    logger.warn(chalk.yellow(`⚠  Failed to get token for controller ${controllerUrl}: ${error.message}`));
     return { error };
   }
   return null;

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

@@ -13,7 +13,7 @@ const chalk = require('chalk');
 const logger = require('./logger');
 const { detectAppType, resolveApplicationConfigPath } = require('./paths');
 const { loadConfigFile } = require('./config-format');
-const { getContainerPort, getLocalPort } = require('./port-resolver');
+const { getContainerPort } = require('./port-resolver');
 
 // createApp is imported dynamically in createMinimalAppIfNeeded to handle test mocking
 
@@ -32,7 +32,7 @@ async function loadVariablesYaml(appKey) {
   } catch (error) {
     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(`⚠  Application config not found for ${appKey}`));
       logger.log(chalk.yellow('📝 Creating minimal configuration...\n'));
       return { variables: null, created: true };
     }
@@ -230,8 +230,8 @@ 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 = options.port ?? getContainerPort(variables, 3000);
-  const localPort = getLocalPort(variables, port);
+  const port = options.port ?? getContainerPort(variables);
+  const localPort = port;
   const language = variables.build?.language || 'typescript';
   const image = buildImageReference(variables, appKeyFromFile);
   const url = variables.app?.url || variables.deployment?.dataplaneUrl || variables.deployment?.appUrl || null;

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

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App Register Display Utilities
  *
@@ -63,7 +64,7 @@ function resolveDisplayName(application, requestedDisplayName) {
  */
 function displayRegistrationResults(data, apiUrl, environment, requestedDisplayName) {
   const displayName = resolveDisplayName(data.application, requestedDisplayName);
-  logger.log(chalk.green('✅ Application registered successfully!\n'));
+  logger.log(formatSuccessLine('Application registered successfully!\n'));
   logger.log(chalk.bold('📋 Application Details:'));
   logger.log(`   ID:           ${data.application.id}`);
   logger.log(`   Key:          ${data.application.key}`);
@@ -74,7 +75,7 @@ function displayRegistrationResults(data, apiUrl, environment, requestedDisplayN
   logger.log(chalk.yellow(`   Client ID:     ${data.credentials.clientId}`));
   logger.log(chalk.yellow(`   Client Secret: ${data.credentials.clientSecret}\n`));
 
-  logger.log(chalk.red('⚠️  IMPORTANT: Client Secret will not be shown again!\n'));
+  logger.log(chalk.red('⚠  IMPORTANT: Client Secret will not be shown again!\n'));
 
   const envPrefix = getEnvironmentPrefix(environment);
   logger.log(chalk.bold('📝 Add to GitHub Secrets:'));

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

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('./cli-test-layout-chalk');
 /**
  * AI Fabrix Builder - App Register Validation Utilities
  *
@@ -114,7 +115,7 @@ async function validateAppRegistrationData(config, originalAppKey) {
   if (!config.displayName) missingFields.push('app.name');
 
   if (missingFields.length > 0) {
-    logger.error(chalk.red('❌ Missing required fields in application.yaml:'));
+    logger.error(formatBlockingError('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);
@@ -134,7 +135,7 @@ async function validateAppRegistrationData(config, originalAppKey) {
       externalIntegration: config.externalIntegration
     });
   } catch (error) {
-    logger.error(chalk.red(`❌ Invalid configuration: ${error.message}`));
+    logger.error(formatBlockingError(`Invalid configuration: ${error.message}`));
     process.exit(1);
   }
 }