@aifabrix/builder 2.32.1 → 2.32.3

package/lib/external-system/download.js

@@ -22,6 +22,7 @@ const { detectAppType } = require('../utils/paths');
 const logger = require('../utils/logger');
 const { generateEnvTemplate } = require('../utils/external-system-env-helpers');
 const { generateVariablesYaml, generateReadme } = require('./download-helpers');
+const { resolveControllerUrl } = require('../utils/controller-url');
 
 /**
  * Validates system type from downloaded application
@@ -126,7 +127,7 @@ function handlePartialDownload(systemKey, systemData, datasourceErrors) {
  */
 async function setupAuthenticationAndDataplane(systemKey, options, config) {
   const environment = options.environment || 'dev';
-  const controllerUrl = options.controller || config.deployment?.controllerUrl || 'http://localhost:3000';
+  const controllerUrl = await resolveControllerUrl(options, config);
   const authConfig = await getDeploymentAuth(controllerUrl, environment, systemKey);
 
   if (!authConfig.token && !authConfig.clientId) {

package/lib/external-system/test-auth.js

@@ -10,6 +10,7 @@
 
 const { getDeploymentAuth } = require('../utils/token-manager');
 const { getDataplaneUrl } = require('../datasource/deploy');
+const { resolveControllerUrl } = require('../utils/controller-url');
 
 /**
  * Setup authentication and get dataplane URL for integration tests
@@ -22,7 +23,7 @@ const { getDataplaneUrl } = require('../datasource/deploy');
  */
 async function setupIntegrationTestAuth(appName, options, config) {
   const environment = options.environment || 'dev';
-  const controllerUrl = options.controller || config.deployment?.controllerUrl || 'http://localhost:3000';
+  const controllerUrl = await resolveControllerUrl(options, config);
   const authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
 
   if (!authConfig.token && !authConfig.clientId) {

package/lib/schema/application-schema.json

@@ -583,7 +583,7 @@
             "minLength": 1,
             "maxLength": 500
           },
-          "Groups": {
+          "groups": {
             "type": "array",
             "description": "Azure AD groups mapped to this role",
             "items": {

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

@@ -3,21 +3,21 @@
    "$id":"https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-datasource.schema.json",
    "title":"External Data Source",
    "description":"Configuration for AI Fabrix ExternalDataSource entities. Includes metadata schema, data dimensions, transformation mappings, OpenAPI/MCP exposure, execution logic, and sync behavior.",
-   "metadata":{
-      "key":"external-datasource-schema",
-      "name":"External Data Source Configuration Schema",
-      "description":"JSON schema for validating ExternalDataSource configuration files",
-      "version":"2.0.0",
-      "type":"schema",
-      "category":"integration",
-      "author":"AI Fabrix Team",
-      "createdAt":"2024-01-01T00:00:00Z",
-      "updatedAt":"2025-01-01T00:00:00Z",
-      "compatibility":{
-         "minVersion":"1.0.0",
-         "maxVersion":"3.0.0",
-         "deprecated":false
-      },
+      "metadata":{
+         "key":"external-datasource-schema",
+         "name":"External Data Source Configuration Schema",
+         "description":"JSON schema for validating ExternalDataSource configuration files",
+         "version":"2.1.0",
+         "type":"schema",
+         "category":"integration",
+         "author":"AI Fabrix Team",
+         "createdAt":"2024-01-01T00:00:00Z",
+         "updatedAt":"2026-01-19T00:00:00Z",
+         "compatibility":{
+            "minVersion":"1.0.0",
+            "maxVersion":"3.0.0",
+            "deprecated":false
+         },
       "tags":[
          "schema",
          "external-datasource",
@@ -70,7 +70,7 @@
          },
          {
             "version":"2.0.0",
-            "date":"2026-01-12T00:00:00Z",
+            "date":"2026-01-18T00:00:00Z",
             "changes":[
                "BREAKING: Renamed fieldMappings.accessFields (array) to fieldMappings.dimensions (object)",
                "BREAKING: Renamed fieldMappings.fields to fieldMappings.attributes",
@@ -80,6 +80,17 @@
                "Updated descriptions to reflect dimension-first data model approach"
             ],
             "breaking":true
+         },
+         {
+            "version":"2.1.0",
+            "date":"2026-01-19T00:00:00Z",
+            "changes":[
+               "Added error semantics (onError object) to all CIP step types with error classification, retry, compensation, and failPipeline",
+               "Added idempotency configuration to CIP definition for execution-level replay guarantees",
+               "Added lineage configuration to field mappings for field-level explainability and compliance",
+               "Added contract versioning configuration to datasource root for CI/CD safety and agent stability"
+            ],
+            "breaking":false
          }
       ]
    },
@@ -223,6 +234,9 @@
                            }
                         },
                         "additionalProperties":false
+                     },
+                     "lineage":{
+                        "$ref":"#/$defs/fieldMappingLineage"
                      }
                   }
                }
@@ -846,6 +860,9 @@
             }
          },
          "additionalProperties":true
+      },
+      "contract":{
+         "$ref":"#/$defs/contractConfig"
       }
    },
    "$defs":{
@@ -931,6 +948,9 @@
                   }
                },
                "additionalProperties":false
+            },
+            "idempotency":{
+               "$ref":"#/$defs/idempotencyConfig"
             }
          },
          "additionalProperties":false
@@ -1024,7 +1044,10 @@
                      "type":"string",
                      "enum":[
                         "GET",
-                        "POST"
+                        "POST",
+                        "PUT",
+                        "PATCH",
+                        "DELETE"
                      ],
                      "description":"Explicit HTTP method when source='http'."
                   },
@@ -1045,8 +1068,15 @@
                      }
                   },
                   "bodyTemplate":{
-                     "description":"Optional static request body or template for POST/PUT fetches.",
+                     "description":"Optional static request body or template for POST/PUT/PATCH fetches.",
                      "type":["object","string","null"]
+                  },
+                  "headers":{
+                     "type":"object",
+                     "description":"Optional HTTP headers for the request.",
+                     "additionalProperties":{
+                        "type":"string"
+                     }
                   }
                },
                "allOf":[
@@ -1093,6 +1123,14 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
             }
          },
          "additionalProperties":false
@@ -1150,6 +1188,14 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
             }
          },
          "additionalProperties":false
@@ -1187,6 +1233,14 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
             }
          },
          "additionalProperties":false
@@ -1226,6 +1280,14 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
             }
          },
          "additionalProperties":false
@@ -1262,6 +1324,14 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
             }
          },
          "additionalProperties":false
@@ -1288,6 +1358,232 @@
             },
             "lineage":{
                "$ref":"#/$defs/cipLineage"
+            },
+            "stepId":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Unique identifier for this step within the operation"
+            },
+            "onError":{
+               "$ref":"#/$defs/cipOnErrorConfig"
+            }
+         },
+         "additionalProperties":false
+      },
+      "cipRetryConfig":{
+         "type":"object",
+         "description":"Retry configuration for error handling.",
+         "properties":{
+            "attempts":{
+               "type":"integer",
+               "minimum":1,
+               "maximum":10,
+               "default":3,
+               "description":"Maximum number of retry attempts"
+            },
+            "backoff":{
+               "type":"string",
+               "enum":["exponential","linear","fixed"],
+               "default":"exponential",
+               "description":"Backoff strategy: exponential (2^attempt), linear (attempt * base), fixed (constant)"
+            },
+            "maxDelaySeconds":{
+               "type":"number",
+               "minimum":1.0,
+               "maximum":300.0,
+               "default":60.0,
+               "description":"Maximum delay between retries in seconds"
+            }
+         },
+         "additionalProperties":false
+      },
+      "cipCompensationConfig":{
+         "type":"object",
+         "description":"Compensation (rollback) configuration for error handling.",
+         "properties":{
+            "enabled":{
+               "type":"boolean",
+               "default":false,
+               "description":"Whether compensation is enabled"
+            },
+            "stepRef":{
+               "type":"string",
+               "pattern":"^[a-z0-9-_]+$",
+               "description":"Reference to a previously executed step by stepId to execute as compensation"
+            }
+         },
+         "additionalProperties":false
+      },
+      "cipOnErrorConfig":{
+         "type":"object",
+         "description":"Enhanced error handling configuration for CIP steps.",
+         "required":["class"],
+         "properties":{
+            "class":{
+               "type":"string",
+               "enum":["transient","permanent","validation","auth"],
+               "description":"Error classification: transient (retryable), permanent (non-retryable), validation (data validation failure), auth (authentication/authorization failure)"
+            },
+            "retry":{
+               "$ref":"#/$defs/cipRetryConfig",
+               "description":"Retry configuration (only applies when class='transient')"
+            },
+            "compensate":{
+               "$ref":"#/$defs/cipCompensationConfig",
+               "description":"Compensation (rollback) configuration"
+            },
+            "failPipeline":{
+               "type":"boolean",
+               "default":true,
+               "description":"Whether step failure should fail the entire pipeline (false allows partial success)"
+            }
+         },
+         "additionalProperties":false
+      },
+      "idempotencyConfig":{
+         "type":"object",
+         "description":"Idempotency configuration for CIP execution.",
+         "required":["key"],
+         "properties":{
+            "key":{
+               "type":"string",
+               "description":"Idempotency key template. Supports variables: {{actor.userId}}, {{raw.requestId}}, {{correlationId}}, {{execution.operation}}, {{execution.datasourceId}}"
+            },
+            "scope":{
+               "type":"string",
+               "enum":["datasource","system"],
+               "default":"datasource",
+               "description":"Idempotency scope: datasource (same key within datasource) or system (same key across all datasources)"
+            },
+            "ttlSeconds":{
+               "type":"integer",
+               "minimum":1,
+               "maximum":604800,
+               "default":86400,
+               "description":"Time to live for idempotency records in seconds (default: 86400 = 24 hours)"
+            },
+            "enforcement":{
+               "type":"string",
+               "enum":["strict","best-effort"],
+               "default":"strict",
+               "description":"Enforcement mode: strict (return previous result, no execution) or best-effort (warn + continue)"
+            }
+         },
+         "additionalProperties":false
+      },
+      "transformationRule":{
+         "type":"object",
+         "description":"Transformation rule applied to a field.",
+         "required":["type"],
+         "properties":{
+            "type":{
+               "type":"string",
+               "description":"Type of transformation: 'mapping', 'function', 'filter', 'aggregate'"
+            },
+            "function":{
+               "type":"string",
+               "description":"Function name (e.g., 'mapStatus', 'toLower', 'trim')"
+            },
+            "rule":{
+               "type":"string",
+               "description":"Human-readable rule description (e.g., 'open → OPEN, closed → CLOSED')"
+            }
+         },
+         "additionalProperties":false
+      },
+      "fieldMappingLineage":{
+         "type":"object",
+         "description":"Lineage metadata for a field mapping.",
+         "required":["sourceFields"],
+         "properties":{
+            "sourceFields":{
+               "type":"array",
+               "minItems":1,
+               "items":{
+                  "type":"string"
+               },
+               "description":"Source field paths that contribute to this mapped field (e.g., ['raw.fields.state'])"
+            },
+            "transformations":{
+               "type":"array",
+               "items":{
+                  "$ref":"#/$defs/transformationRule"
+               },
+               "description":"List of transformations applied to source fields"
+            },
+            "confidence":{
+               "type":"number",
+               "minimum":0.0,
+               "maximum":1.0,
+               "default":1.0,
+               "description":"Confidence score for this mapping (0.0-1.0). Default: 1.0 for deterministic transformations."
+            }
+         },
+         "additionalProperties":false
+      },
+      "compatibilityConfig":{
+         "type":"object",
+         "description":"Compatibility configuration for contract versioning.",
+         "properties":{
+            "backwardCompatible":{
+               "type":"boolean",
+               "default":true,
+               "description":"Whether this version is backward compatible with previous versions"
+            },
+            "breakingChanges":{
+               "type":"array",
+               "items":{
+                  "type":"string"
+               },
+               "description":"List of breaking change types: removeField, changeType, changeSemantics"
+            }
+         },
+         "additionalProperties":false
+      },
+      "deprecationConfig":{
+         "type":"object",
+         "description":"Deprecation configuration for contract versioning.",
+         "properties":{
+            "sunsetDate":{
+               "type":"string",
+               "pattern":"^\\d{4}-\\d{2}-\\d{2}$",
+               "description":"Date when this contract version will be sunset (YYYY-MM-DD)"
+            },
+            "replacedBy":{
+               "type":"string",
+               "description":"Contract name/version that replaces this deprecated version"
+            }
+         },
+         "additionalProperties":false
+      },
+      "contractConfig":{
+         "type":"object",
+         "description":"Contract versioning configuration for datasource.",
+         "required":["name","version"],
+         "properties":{
+            "name":{
+               "type":"string",
+               "pattern":"^[a-z0-9.-]+$",
+               "description":"Contract identifier (e.g., 'jira.issue', separate from datasource key)"
+            },
+            "version":{
+               "type":"string",
+               "pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+$",
+               "description":"Semantic version of the contract (e.g., '2.1.0')"
+            },
+            "status":{
+               "type":"string",
+               "enum":["stable","deprecated","experimental"],
+               "default":"stable",
+               "description":"Contract status: stable (production-ready), deprecated (being phased out), experimental (testing)"
+            },
+            "compatibility":{
+               "$ref":"#/$defs/compatibilityConfig",
+               "description":"Compatibility information for this contract version"
+            },
+            "deprecation":{
+               "$ref":"#/$defs/deprecationConfig",
+               "description":"Deprecation information if status is 'deprecated'"
             }
          },
          "additionalProperties":false

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

@@ -12,7 +12,7 @@
     "category": "integration",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2024-01-01T00:00:00Z",
+    "updatedAt": "2025-12-01T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -314,7 +314,7 @@
             "minLength": 1,
             "maxLength": 500
           },
-          "Groups": {
+          "groups": {
             "type": "array",
             "description": "Azure AD groups mapped to this role",
             "items": {

package/lib/utils/api.js

@@ -209,10 +209,20 @@ function extractControllerUrl(url) {
  * Automatically refreshes device token on 401 errors if refresh token is available
  * @param {string} url - API endpoint URL
  * @param {Object} options - Fetch options
- * @param {string} token - Bearer token
+ * @param {string|Object} tokenOrAuthConfig - Bearer token string or authConfig object
+ * @param {string} [tokenOrAuthConfig.token] - Bearer token (if object)
+ * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
-async function authenticatedApiCall(url, options = {}, token) {
+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
@@ -230,12 +240,15 @@ async function authenticatedApiCall(url, options = {}, token) {
   // Handle 401 errors with automatic token refresh for device tokens
   if (!response.success && response.status === 401) {
     try {
-      // Extract controller URL from request URL
-      const controllerUrl = extractControllerUrl(url);
+      // 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 get and refresh device token
-      const { getOrRefreshDeviceToken } = require('./token-manager');
-      const refreshedToken = await getOrRefreshDeviceToken(controllerUrl);
+      // 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

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

@@ -48,7 +48,8 @@ function displayRegistrationResults(data, apiUrl, environment) {
   logger.log(chalk.bold('📋 Application Details:'));
   logger.log(`   ID:           ${data.application.id}`);
   logger.log(`   Key:          ${data.application.key}`);
-  logger.log(`   Display Name: ${data.application.displayName}\n`);
+  logger.log(`   Display Name: ${data.application.displayName}`);
+  logger.log(`   Controller:   ${apiUrl}\n`);
 
   logger.log(chalk.bold.yellow('🔑 CREDENTIALS (save these immediately):'));
   logger.log(chalk.yellow(`   Client ID:     ${data.credentials.clientId}`));

package/lib/utils/cli-utils.js

@@ -135,7 +135,9 @@ function formatAzureError(errorMsg) {
       '   Use format: *.azurecr.io (e.g., myacr.azurecr.io)'
     ];
   }
-  if (errorMsg.includes('authenticate') || errorMsg.includes('ACR') || errorMsg.includes('Authentication required')) {
+  // Only match ACR-specific authentication errors, not general authentication failures
+  if (errorMsg.includes('ACR') || errorMsg.includes('azurecr.io') ||
+      (errorMsg.includes('authenticate') && (errorMsg.includes('registry') || errorMsg.includes('container')))) {
     return [
       '   Azure Container Registry authentication failed.',
       '   Run: az acr login --name <registry-name>',

package/lib/utils/controller-url.js

@@ -0,0 +1,67 @@
+/**
+ * Controller URL Resolution Utilities
+ *
+ * Provides utilities for resolving controller URLs with developer ID-based defaults
+ * and fallback chain support.
+ *
+ * @fileoverview Controller URL resolution utilities
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { getDeveloperIdNumber } = require('./env-map');
+const devConfig = require('./dev-config');
+
+/**
+ * Calculate default controller URL based on developer ID
+ * Uses getDevPorts to get the app port which is adjusted by developer ID
+ * Developer ID 0 = http://localhost:3000
+ * Developer ID 1 = http://localhost:3100
+ * Developer ID 2 = http://localhost:3200
+ * @async
+ * @function getDefaultControllerUrl
+ * @returns {Promise<string>} Default controller URL
+ */
+async function getDefaultControllerUrl() {
+  const developerId = await getDeveloperIdNumber(null);
+  const ports = devConfig.getDevPorts(developerId);
+  return `http://localhost:${ports.app}`;
+}
+
+/**
+ * Resolve controller URL with fallback chain
+ * Priority:
+ * 1. options.controller (explicit option)
+ * 2. config.deployment?.controllerUrl (from config)
+ * 3. getDefaultControllerUrl() (developer ID-based default)
+ * @async
+ * @function resolveControllerUrl
+ * @param {Object} options - Command options
+ * @param {string} [options.controller] - Explicit controller URL option
+ * @param {Object} config - Configuration object
+ * @param {Object} [config.deployment] - Deployment configuration
+ * @param {string} [config.deployment.controllerUrl] - Controller URL from config
+ * @returns {Promise<string>} Resolved controller URL
+ */
+async function resolveControllerUrl(options, config) {
+  // Priority 1: Explicit option
+  if (options && (options.controller || options.url)) {
+    const explicitUrl = options.controller || options.url;
+    if (explicitUrl) {
+      return explicitUrl.replace(/\/$/, '');
+    }
+  }
+
+  // Priority 2: Config file
+  if (config?.deployment?.controllerUrl) {
+    return config.deployment.controllerUrl.replace(/\/$/, '');
+  }
+
+  // Priority 3: Developer ID-based default
+  return await getDefaultControllerUrl();
+}
+
+module.exports = {
+  getDefaultControllerUrl,
+  resolveControllerUrl
+};

package/lib/utils/env-map.js

@@ -297,6 +297,7 @@ async function buildEnvVarMap(context, osModule = null, developerId = null) {
 }
 
 module.exports = {
-  buildEnvVarMap
+  buildEnvVarMap,
+  getDeveloperIdNumber
 };