@aifabrix/builder 2.37.0 → 2.37.9

package/lib/deployment/deployer-status.js

@@ -0,0 +1,101 @@
+/**
+ * Deployment status and polling helpers for deployer.
+ *
+ * @fileoverview Deployment status checks and polling utilities
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+
+/**
+ * Checks if deployment status is terminal
+ * @param {string} status - Deployment status
+ * @returns {boolean} True if status is terminal
+ */
+function isTerminalStatus(status) {
+  return status === 'completed' || status === 'failed' || status === 'cancelled';
+}
+
+/**
+ * Convert authConfig to pipeline auth config format
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Object} Pipeline auth config
+ */
+function convertToPipelineAuthConfig(authConfig) {
+  return authConfig.type === 'bearer'
+    ? { type: 'bearer', token: authConfig.token }
+    : { type: 'client-credentials', clientId: authConfig.clientId, clientSecret: authConfig.clientSecret };
+}
+
+/**
+ * Handles error response from deployment status check
+ * @param {Object} response - API response
+ * @param {string} deploymentId - Deployment ID
+ * @throws {Error} Appropriate error message
+ */
+function handleDeploymentStatusError(response, deploymentId) {
+  if (response.status === 404) {
+    throw new Error(`Deployment ${deploymentId || response.deploymentId || 'unknown'} not found`);
+  }
+  throw new Error(`Status check failed: ${response.formattedError || response.error || 'Unknown error'}`);
+}
+
+/**
+ * Extracts deployment data from response
+ * @param {Object} response - API response
+ * @returns {Object} Deployment data
+ */
+function extractDeploymentData(response) {
+  const responseData = response.data;
+  return responseData.data || responseData;
+}
+
+/**
+ * Logs deployment progress
+ * @param {Object} deploymentData - Deployment data
+ * @param {number} attempt - Current attempt
+ * @param {number} maxAttempts - Maximum attempts
+ */
+function logDeploymentProgress(deploymentData, attempt, maxAttempts) {
+  const status = deploymentData.status;
+  const progress = deploymentData.progress || 0;
+  logger.log(chalk.blue(`   Status: ${status} (${progress}%) (attempt ${attempt + 1}/${maxAttempts})`));
+}
+
+/**
+ * Process deployment status response
+ * @param {Object} response - API response
+ * @param {number} attempt - Current attempt number
+ * @param {number} maxAttempts - Maximum attempts
+ * @param {number} interval - Polling interval
+ * @param {string} deploymentId - Deployment ID for error messages
+ * @returns {Promise<Object|null>} Deployment data if terminal, null if needs to continue polling
+ */
+async function processDeploymentStatusResponse(response, attempt, maxAttempts, interval, deploymentId) {
+  if (!response.success || !response.data) {
+    handleDeploymentStatusError(response, deploymentId);
+  }
+
+  const deploymentData = extractDeploymentData(response);
+  if (isTerminalStatus(deploymentData.status)) {
+    return deploymentData;
+  }
+
+  logDeploymentProgress(deploymentData, attempt, maxAttempts);
+  if (attempt < maxAttempts - 1) {
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+
+  return null;
+}
+
+module.exports = {
+  isTerminalStatus,
+  convertToPipelineAuthConfig,
+  handleDeploymentStatusError,
+  extractDeploymentData,
+  logDeploymentProgress,
+  processDeploymentStatusResponse
+};

package/lib/deployment/deployer.js

@@ -16,6 +16,23 @@ const { validateControllerUrl, validateEnvironmentKey } = require('../utils/depl
 const { handleDeploymentError, handleDeploymentErrors } = require('../utils/deployment-errors');
 const { validatePipeline, deployPipeline, getPipelineDeployment } = require('../api/pipeline.api');
 const { handleValidationResponse } = require('../utils/deployment-validation-helpers');
+const {
+  convertToPipelineAuthConfig,
+  processDeploymentStatusResponse
+} = require('./deployer-status');
+
+/**
+ * For external systems, send full manifest (application + inline system + full dataSources).
+ * No transform - controller receives complete application, external system, and data sources.
+ * @param {Object} manifest - Full manifest (type 'external', system, dataSources as full objects)
+ * @returns {Object} Manifest to send to pipeline (external sent as-is)
+ */
+function transformExternalManifestForPipeline(manifest) {
+  if (!manifest) {
+    return manifest;
+  }
+  return manifest;
+}
 
 /**
  * Build validation data for deployment
@@ -28,27 +45,42 @@ const { handleValidationResponse } = require('../utils/deployment-validation-hel
  */
 async function buildValidationData(manifest, validatedEnvKey, authConfig, options) {
   const tokenManager = require('../utils/token-manager');
-  const { clientId, clientSecret } = await tokenManager.extractClientCredentials(
-    authConfig,
-    manifest.key,
-    validatedEnvKey,
-    options
-  );
+  let clientId;
+  let clientSecret;
+  let pipelineAuthConfig;
+
+  try {
+    const credentials = await tokenManager.extractClientCredentials(
+      authConfig,
+      manifest.key,
+      validatedEnvKey,
+      options
+    );
+    clientId = credentials.clientId;
+    clientSecret = credentials.clientSecret;
+    pipelineAuthConfig = {
+      type: 'client-credentials',
+      clientId,
+      clientSecret
+    };
+  } catch (credError) {
+    if (authConfig.type === 'bearer' && authConfig.token) {
+      pipelineAuthConfig = { type: 'bearer', token: authConfig.token };
+      clientId = manifest.key;
+      clientSecret = '';
+    } else {
+      throw credError;
+    }
+  }
 
   const repositoryUrl = options.repositoryUrl || `https://github.com/aifabrix/${manifest.key}`;
   const validationData = {
-    clientId: clientId,
-    clientSecret: clientSecret,
+    clientId: clientId || '',
+    clientSecret: clientSecret || '',
     repositoryUrl: repositoryUrl,
     applicationConfig: manifest
   };
 
-  const pipelineAuthConfig = {
-    type: 'client-credentials',
-    clientId: clientId,
-    clientSecret: clientSecret
-  };
-
   return { validationData, pipelineAuthConfig };
 }
 
@@ -130,7 +162,7 @@ function validateDeploymentCredentials(authConfig) {
 }
 
 /**
- * Build deployment data and auth config
+ * Build deployment data and auth config (supports bearer-only when no client credentials)
  * @param {string} validateToken - Validation token
  * @param {Object} authConfig - Authentication configuration
  * @param {Object} options - Deployment options
@@ -143,11 +175,13 @@ function buildDeploymentData(validateToken, authConfig, options) {
     imageTag: imageTag
   };
 
-  const pipelineAuthConfig = {
-    type: 'client-credentials',
-    clientId: authConfig.clientId,
-    clientSecret: authConfig.clientSecret
-  };
+  const pipelineAuthConfig = authConfig.type === 'bearer' && authConfig.token && !authConfig.clientId
+    ? { type: 'bearer', token: authConfig.token }
+    : {
+      type: 'client-credentials',
+      clientId: authConfig.clientId,
+      clientSecret: authConfig.clientSecret
+    };
 
   return { deployData, pipelineAuthConfig };
 }
@@ -212,10 +246,12 @@ async function sendDeploymentRequest(url, envKey, validateToken, authConfig, opt
   const validatedEnvKey = validateEnvironmentKey(envKey);
   const maxRetries = options.maxRetries || 3;
 
-  // Validate credentials
-  validateDeploymentCredentials(authConfig);
+  const useBearerOnly = authConfig.type === 'bearer' && authConfig.token && !authConfig.clientId;
+  if (!useBearerOnly) {
+    validateDeploymentCredentials(authConfig);
+  }
 
-  // Build deployment data
+  // Build deployment data (supports bearer-only when no client credentials)
   const { deployData, pipelineAuthConfig } = buildDeploymentData(validateToken, authConfig, options);
 
   // Wrap API call with retry logic
@@ -237,92 +273,6 @@ async function sendDeploymentRequest(url, envKey, validateToken, authConfig, opt
   throwDeploymentError(lastError, maxRetries);
 }
 
-/**
- * Checks if deployment status is terminal
- * @function isTerminalStatus
- * @param {string} status - Deployment status
- * @returns {boolean} True if status is terminal
- */
-function isTerminalStatus(status) {
-  return status === 'completed' || status === 'failed' || status === 'cancelled';
-}
-
-/**
- * Convert authConfig to pipeline auth config format
- * @param {Object} authConfig - Authentication configuration
- * @returns {Object} Pipeline auth config
- */
-function convertToPipelineAuthConfig(authConfig) {
-  return authConfig.type === 'bearer'
-    ? { type: 'bearer', token: authConfig.token }
-    : { type: 'client-credentials', clientId: authConfig.clientId, clientSecret: authConfig.clientSecret };
-}
-
-/**
- * Process deployment status response
- * @param {Object} response - API response
- * @param {number} attempt - Current attempt number
- * @param {number} maxAttempts - Maximum attempts
- * @param {number} interval - Polling interval
- * @param {string} deploymentId - Deployment ID for error messages
- * @returns {Object|null} Deployment data if terminal, null if needs to continue polling
- */
-/**
- * Handles error response from deployment status check
- * @function handleDeploymentStatusError
- * @param {Object} response - API response
- * @param {string} deploymentId - Deployment ID
- * @throws {Error} Appropriate error message
- */
-function handleDeploymentStatusError(response, deploymentId) {
-  if (response.status === 404) {
-    throw new Error(`Deployment ${deploymentId || response.deploymentId || 'unknown'} not found`);
-  }
-  throw new Error(`Status check failed: ${response.formattedError || response.error || 'Unknown error'}`);
-}
-
-/**
- * Extracts deployment data from response
- * @function extractDeploymentData
- * @param {Object} response - API response
- * @returns {Object} Deployment data
- */
-function extractDeploymentData(response) {
-  const responseData = response.data;
-  return responseData.data || responseData;
-}
-
-/**
- * Logs deployment progress
- * @function logDeploymentProgress
- * @param {Object} deploymentData - Deployment data
- * @param {number} attempt - Current attempt
- * @param {number} maxAttempts - Maximum attempts
- */
-function logDeploymentProgress(deploymentData, attempt, maxAttempts) {
-  const status = deploymentData.status;
-  const progress = deploymentData.progress || 0;
-  logger.log(chalk.blue(`   Status: ${status} (${progress}%) (attempt ${attempt + 1}/${maxAttempts})`));
-}
-
-async function processDeploymentStatusResponse(response, attempt, maxAttempts, interval, deploymentId) {
-  if (!response.success || !response.data) {
-    handleDeploymentStatusError(response, deploymentId);
-  }
-
-  const deploymentData = extractDeploymentData(response);
-  if (isTerminalStatus(deploymentData.status)) {
-    return deploymentData;
-  }
-
-  logDeploymentProgress(deploymentData, attempt, maxAttempts);
-  if (attempt < maxAttempts - 1) {
-    await new Promise(resolve => setTimeout(resolve, interval));
-  }
-
-  return null;
-}
-
 /**
  * Polls deployment status from controller
  * Uses pipeline endpoint for CI/CD monitoring with minimal deployment info
@@ -470,9 +420,11 @@ async function deployToController(manifest, controllerUrl, envKey, authConfig, o
   // Log deployment attempt for audit
   await auditLogger.logDeploymentAttempt(manifest.key, url, options);
 
+  const pipelineManifest = transformExternalManifestForPipeline(manifest);
+
   try {
     // Send deployment request
-    const result = await sendDeployment(url, validatedEnvKey, manifest, authConfig, options);
+    const result = await sendDeployment(url, validatedEnvKey, pipelineManifest, authConfig, options);
 
     // Poll for deployment status if enabled
     return await pollDeployment(result, url, validatedEnvKey, authConfig, options);

package/lib/deployment/environment.js

@@ -9,16 +9,21 @@
  * @version 2.0.0
  */
 
+const fs = require('fs');
+const path = require('path');
 const chalk = require('chalk');
+const Ajv = require('ajv');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { validateControllerUrl, validateEnvironmentKey } = require('../utils/deployment-validation');
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
-const { getEnvironmentStatus } = require('../api/environments.api');
-const { deployEnvironment: deployEnvironmentInfra } = require('../api/deployments.api');
+const { getPipelineDeployment } = require('../api/pipeline.api');
+const { deployEnvironment: deployEnvironmentInfra, getDeployment } = require('../api/deployments.api');
 const { handleDeploymentErrors } = require('../utils/deployment-errors');
+const { formatValidationErrors } = require('../utils/error-formatter');
 const auditLogger = require('../core/audit-logger');
+const environmentDeployRequestSchema = require('../schema/environment-deploy-request.schema.json');
 
 /**
  * Validates environment deployment prerequisites
@@ -77,26 +82,102 @@ async function getEnvironmentAuth(controllerUrl) {
  * @returns {Promise<Object>} Deployment result
  * @throws {Error} If deployment fails
  */
+/** Reads and parses config file; throws if missing, unreadable, or invalid structure. */
+function parseEnvironmentConfigFile(resolvedPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(resolvedPath, 'utf8');
+  } catch (e) {
+    throw new Error(`Cannot read config file: ${resolvedPath}. ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `Invalid JSON in config file: ${resolvedPath}\n${e.message}\n` +
+      'Expected format: { "environmentConfig": { "key", "environment", "preset", "serviceName", "location" }, "dryRun": false }'
+    );
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(
+      `Config file must be a JSON object with "environmentConfig". File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" }, "dryRun": false }'
+    );
+  }
+  if (parsed.environmentConfig === undefined) {
+    throw new Error(
+      `Config file must contain "environmentConfig" (object). File: ${resolvedPath}\n` +
+      'Example: { "environmentConfig": { "key": "dev", "environment": "dev", "preset": "s", "serviceName": "aifabrix", "location": "swedencentral" } }'
+    );
+  }
+  if (typeof parsed.environmentConfig !== 'object' || parsed.environmentConfig === null) {
+    throw new Error(`"environmentConfig" must be an object. File: ${resolvedPath}`);
+  }
+  return parsed;
+}
+
 /**
- * Builds environment deployment request
- * @function buildEnvironmentDeploymentRequest
- * @param {string} validatedEnvKey - Validated environment key
- * @param {Object} options - Deployment options
- * @returns {Object} Deployment request object
+ * Validates parsed config against schema and returns deploy request.
+ * @param {Object} parsed - Parsed config object
+ * @param {string} resolvedPath - Path for error messages
+ * @returns {Object} { environmentConfig, dryRun? }
  */
-function buildEnvironmentDeploymentRequest(validatedEnvKey, options) {
-  const capitalized = validatedEnvKey.charAt(0).toUpperCase() + validatedEnvKey.slice(1);
-  const request = {
-    key: validatedEnvKey,
-    displayName: `${capitalized} Environment`,
-    description: `${capitalized} environment for application deployments`
+function validateEnvironmentDeployParsed(parsed, resolvedPath) {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(environmentDeployRequestSchema);
+  if (!validate(parsed)) {
+    const messages = formatValidationErrors(validate.errors);
+    throw new Error(
+      `Environment config validation failed (${resolvedPath}):\n  • ${messages.join('\n  • ')}\n` +
+      'Fix the config file and run the command again. See templates/infra/environment-dev.json for a valid example.'
+    );
+  }
+  return {
+    environmentConfig: parsed.environmentConfig,
+    dryRun: Boolean(parsed.dryRun)
   };
+}
 
-  if (options.config) {
-    request.description += ` (config: ${options.config})`;
+/**
+ * Loads and validates environment deploy config from a JSON file
+ * @param {string} configPath - Absolute or relative path to config JSON
+ * @returns {Object} Valid deploy request { environmentConfig, dryRun? }
+ * @throws {Error} If file missing, invalid JSON, or validation fails
+ */
+function loadAndValidateEnvironmentDeployConfig(configPath) {
+  const resolvedPath = path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Environment config file not found: ${resolvedPath}\n` +
+      'Use --config <file> with a JSON file containing "environmentConfig" (e.g. templates/infra/environment-dev.json).'
+    );
   }
+  const parsed = parseEnvironmentConfigFile(resolvedPath);
+  return validateEnvironmentDeployParsed(parsed, resolvedPath);
+}
 
-  return request;
+/**
+ * Builds environment deployment request from options (config file required)
+ * @function buildEnvironmentDeploymentRequest
+ * @param {string} validatedEnvKey - Validated environment key
+ * @param {Object} options - Deployment options (must include options.config)
+ * @returns {Object} Deployment request object for API
+ */
+function buildEnvironmentDeploymentRequest(validatedEnvKey, options) {
+  if (!options.config || typeof options.config !== 'string') {
+    throw new Error(
+      'Environment deploy requires a config file with "environmentConfig". Use --config <file>.\n' +
+      'Example: aifabrix environment deploy dev --config templates/infra/environment-dev.json'
+    );
+  }
+  const deployRequest = loadAndValidateEnvironmentDeployConfig(options.config);
+  if (deployRequest.environmentConfig.key && deployRequest.environmentConfig.key !== validatedEnvKey) {
+    logger.log(chalk.yellow(
+      `⚠ Config key "${deployRequest.environmentConfig.key}" does not match deploy target "${validatedEnvKey}"; using target "${validatedEnvKey}".`
+    ));
+  }
+  return deployRequest;
 }
 
 /**
@@ -155,22 +236,47 @@ async function sendEnvironmentDeployment(controllerUrl, envKey, authConfig, opti
 }
 
 /**
- * Process environment status response
- * @param {Object} response - API response
+ * Fetches deployment status by ID (pipeline endpoint first, then environments)
+ * Mirrors miso-controller manual test: GET pipeline/deployments/:id then GET environments/deployments/:id
+ * @async
+ * @param {string} controllerUrl - Controller URL
+ * @param {string} envKey - Environment key
+ * @param {string} deploymentId - Deployment ID
+ * @param {Object} apiAuthConfig - Auth config { type: 'bearer', token }
+ * @returns {Promise<Object|null>} Deployment record (status, progress, etc.) or null
+ */
+async function getDeploymentStatusById(controllerUrl, envKey, deploymentId, apiAuthConfig) {
+  try {
+    const pipelineRes = await getPipelineDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    if (pipelineRes?.data?.data) return pipelineRes.data.data;
+    if (pipelineRes?.data && typeof pipelineRes.data === 'object' && pipelineRes.data.status) return pipelineRes.data;
+  } catch {
+    // Fallback to environments endpoint
+  }
+  try {
+    const envRes = await getDeployment(controllerUrl, envKey, deploymentId, apiAuthConfig);
+    if (envRes?.data?.data) return envRes.data.data;
+    if (envRes?.data && typeof envRes.data === 'object' && envRes.data.status) return envRes.data;
+  } catch {
+    // Ignore
+  }
+  return null;
+}
+
+/**
+ * Process deployment record from GET .../deployments/:deploymentId
+ * @param {Object|null} deployment - Deployment record (status, progress, message, error)
  * @param {string} validatedEnvKey - Validated environment key
- * @returns {Object|null} Status result if ready, null if needs to continue polling
+ * @returns {Object|null} Status result if completed, null if still in progress
  * @throws {Error} If deployment failed
  */
-function processEnvironmentStatusResponse(response, validatedEnvKey) {
-  if (!response.success || !response.data) {
+function processDeploymentStatusResponse(deployment, validatedEnvKey) {
+  if (!deployment || typeof deployment !== 'object') {
     return null;
   }
 
-  const responseData = response.data.data || response.data;
-  const status = responseData.status || responseData.ready;
-  const isReady = status === 'ready' || status === 'completed' || responseData.ready === true;
-
-  if (isReady) {
+  const status = deployment.status;
+  if (status === 'completed') {
     return {
       success: true,
       environment: validatedEnvKey,
@@ -179,9 +285,9 @@ function processEnvironmentStatusResponse(response, validatedEnvKey) {
     };
   }
 
-  // Check for terminal failure states
   if (status === 'failed' || status === 'error') {
-    throw new Error(`Environment deployment failed: ${responseData.message || 'Unknown error'}`);
+    const msg = deployment.message || deployment.error || 'Unknown error';
+    throw new Error(`Environment deployment failed: ${msg}`);
   }
 
   return null;
@@ -213,8 +319,18 @@ async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authCo
     try {
       await new Promise(resolve => setTimeout(resolve, pollInterval));
 
-      const response = await getEnvironmentStatus(validatedUrl, validatedEnvKey, apiAuthConfig);
-      const statusResult = processEnvironmentStatusResponse(response, validatedEnvKey);
+      const deployment = await getDeploymentStatusById(
+        validatedUrl,
+        validatedEnvKey,
+        deploymentId,
+        apiAuthConfig
+      );
+      const progress = deployment?.progress ?? 0;
+      const statusLabel = deployment?.status ?? 'pending';
+      if (attempt <= maxAttempts) {
+        logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}... Status: ${statusLabel} (${progress}%)`));
+      }
+      const statusResult = processDeploymentStatusResponse(deployment, validatedEnvKey);
       if (statusResult) {
         return statusResult;
       }
@@ -225,10 +341,6 @@ async function pollEnvironmentStatus(deploymentId, controllerUrl, envKey, authCo
       }
       // Otherwise, continue polling
     }
-
-    if (attempt < maxAttempts) {
-      logger.log(chalk.gray(`   Attempt ${attempt}/${maxAttempts}...`));
-    }
   }
 
   // Timeout
@@ -380,8 +492,6 @@ async function deployEnvironment(envKey, options = {}) {
     throw error;
   }
 }
-
 module.exports = {
   deployEnvironment
 };
-

package/lib/external-system/deploy.js

@@ -97,7 +97,11 @@ async function deployExternalSystem(appName, options = {}) {
 
     return result;
   } catch (error) {
-    throw new Error(`Failed to deploy external system: ${error.message}`);
+    let message = `Failed to deploy external system: ${error.message}`;
+    if (error.message && error.message.includes('Application not found')) {
+      message += `\n\n💡 Register the app in the controller first: aifabrix app register ${appName}`;
+    }
+    throw new Error(message);
   }
 }
 

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

@@ -1,7 +1,9 @@
 /**
  * External System Test Authentication Helpers
  *
- * Authentication setup for integration tests
+ * Authentication setup for integration tests. Uses the dataplane service URL
+ * (discovered from the controller), not the external system app's config—external
+ * apps do not store a dataplane URL.
  *
  * @fileoverview Authentication helpers for external system testing
  * @author AI Fabrix Team
@@ -9,19 +11,19 @@
  */
 
 const { getDeploymentAuth } = require('../utils/token-manager');
-const { getDataplaneUrl } = require('../datasource/deploy');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
 const { resolveControllerUrl } = require('../utils/controller-url');
 
 /**
  * Setup authentication and get dataplane URL for integration tests
  * @async
- * @param {string} appName - Application name
- * @param {Object} options - Test options
- * @param {Object} config - Configuration object
+ * @param {string} appName - Application name (used for auth scope; dataplane URL is discovered from controller)
+ * @param {Object} options - Test options; options.dataplane overrides discovered URL
+ * @param {Object} _config - Configuration object
  * @returns {Promise<Object>} Object with authConfig and dataplaneUrl
  * @throws {Error} If authentication fails
  */
-async function setupIntegrationTestAuth(appName, _options, _config) {
+async function setupIntegrationTestAuth(appName, options, _config) {
   const { resolveEnvironment } = require('../core/config');
   const environment = await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
@@ -31,7 +33,12 @@ async function setupIntegrationTestAuth(appName, _options, _config) {
     throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register" first.');
   }
 
-  const dataplaneUrl = await getDataplaneUrl(controllerUrl, appName, environment, authConfig);
+  let dataplaneUrl;
+  if (options && options.dataplane && typeof options.dataplane === 'string' && options.dataplane.trim()) {
+    dataplaneUrl = options.dataplane.trim();
+  } else {
+    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+  }
 
   return { authConfig, dataplaneUrl };
 }