@aifabrix/builder 2.33.5 → 2.36.0

package/lib/cli.js

@@ -155,10 +155,10 @@ function setupInfraCommands(program) {
     });
 
   program.command('up-miso')
-    .description('Install keycloak and miso-controller from images (no build). Infra must be up. Uses auto-generated secrets for testing.')
-    .option('-r, --registry <url>', 'Override registry for both apps (e.g. myacr.azurecr.io)')
+    .description('Install keycloak, miso-controller, and dataplane from images (no build). Infra must be up. Uses auto-generated secrets for testing.')
+    .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
-    .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/keycloak:v1, miso-controller=myreg/m:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
+    .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1, dataplane=myreg/d:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
     .action(async(options) => {
       try {
         await handleUpMiso(options);
@@ -409,14 +409,29 @@ function setupAppCommands(program) {
       }
     });
 
-  program.command('wizard')
-    .description('Interactive wizard for creating external systems (or headless with --config)')
-    .option('-a, --app <app>', 'Application name (if not provided, will prompt)')
-    .option('--config <file>', 'Path to wizard.yaml config file for headless mode')
-    .action(async(options) => {
+  program.command('wizard [appName]')
+    .description('Create or extend external systems (OpenAPI, MCP, or known platforms like HubSpot) via guided steps or a config file')
+    .option('-a, --app <app>', 'Application name (synonym for positional appName)')
+    .option('--config <file>', 'Run headless using a wizard.yaml file (appName, mode, source, credential, preferences)')
+    .option('--silent', 'Run with saved integration/<app>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
+    .addHelpText('after', `
+Examples:
+  $ aifabrix wizard                    Run interactively (mode first, then prompts)
+  $ aifabrix wizard my-integration      Load wizard.yaml if present → show summary → "Run with saved config?" or start from step 1
+  $ aifabrix wizard my-integration --silent  Run headless with integration/my-integration/wizard.yaml (no prompts)
+  $ aifabrix wizard -a my-integration   Same as above (app name set)
+  $ aifabrix wizard --config wizard.yaml  Run headless from a wizard config file
+
+Config path: When appName is provided, integration/<appName>/wizard.yaml is used for load/save and error.log.
+To change settings after a run, edit that file and run "aifabrix wizard <app>" again.
+Headless config must include: appName, mode (create-system|add-datasource), source (type + filePath/url/platform).
+See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`)
+    .action(async(positionalAppName, options) => {
       try {
+        const appName = positionalAppName || options.app;
+        const configPath = appName ? path.join(process.cwd(), 'integration', appName, 'wizard.yaml') : null;
         const { handleWizard } = require('./commands/wizard');
-        await handleWizard(options);
+        await handleWizard({ ...options, app: appName, config: options.config, configPath });
       } catch (error) {
         handleCommandError(error, 'wizard');
         process.exit(1);
@@ -685,6 +700,20 @@ function setupUtilityCommands(program) {
       }
     });
 
+  program.command('show <appKey>')
+    .description('Show application info from local builder/ or integration/ (offline) or from controller (--online)')
+    .option('--online', 'Fetch application data from the controller')
+    .option('--json', 'Output as JSON')
+    .action(async(appKey, options) => {
+      try {
+        const { showApp } = require('./app/show');
+        await showApp(appKey, { online: options.online, json: options.json });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
   program.command('validate <appOrFile>')
     .description('Validate application or external integration file')
     .option('--type <type>', 'Application type (external) - if set, only checks integration folder')

package/lib/commands/auth-status.js

@@ -15,6 +15,9 @@ const { getConfig } = config;
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
 const { getAuthUser } = require('../api/auth.api');
 const { resolveControllerUrl } = require('../utils/controller-url');
+const { findDataplaneServiceAppKey } = require('./wizard-dataplane');
+const { getDataplaneUrl } = require('../datasource/deploy');
+const { checkDataplaneHealth } = require('../utils/dataplane-health');
 
 /**
  * Format expiration date for display
@@ -212,13 +215,53 @@ function displayTokenInfo(tokenInfo) {
   displayUserInfo(tokenInfo.user);
 }
 
+/**
+ * Resolve dataplane URL from controller without progress logs (for auth status display)
+ * @async
+ * @param {string} controllerUrl - Controller URL
+ * @param {string} environment - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<string|null>} Dataplane URL or null if not discoverable
+ */
+async function resolveDataplaneUrlSilent(controllerUrl, environment, authConfig) {
+  try {
+    const dataplaneAppKey = await findDataplaneServiceAppKey(controllerUrl, environment, authConfig);
+    if (dataplaneAppKey) {
+      return await getDataplaneUrl(controllerUrl, dataplaneAppKey, environment, authConfig);
+    }
+    return await getDataplaneUrl(controllerUrl, 'dataplane', environment, authConfig);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Display dataplane section when authenticated
+ * @param {string|null} dataplaneUrl - Dataplane URL or null
+ * @param {boolean} dataplaneConnected - Whether dataplane health check passed
+ */
+function displayDataplaneSection(dataplaneUrl, dataplaneConnected) {
+  if (dataplaneUrl) {
+    logger.log(`Dataplane: ${chalk.cyan(dataplaneUrl)}`);
+    const statusIcon = dataplaneConnected ? chalk.green('✓') : chalk.red('✗');
+    const statusText = dataplaneConnected ? 'Connected' : 'Not reachable';
+    logger.log(`Status: ${statusIcon} ${statusText}`);
+  } else {
+    logger.log(`Dataplane: ${chalk.gray('—')}`);
+    logger.log(`Status: ${chalk.gray('Not discovered')}`);
+  }
+}
+
 /**
  * Display authentication status
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment key
  * @param {Object|null} tokenInfo - Token information
+ * @param {Object} [dataplaneInfo] - Optional dataplane URL and health
+ * @param {string|null} [dataplaneInfo.url] - Dataplane URL
+ * @param {boolean} [dataplaneInfo.connected] - Whether dataplane is reachable
  */
-function displayStatus(controllerUrl, environment, tokenInfo) {
+function displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo) {
   logger.log(chalk.bold('\n🔐 Authentication Status\n'));
   logger.log(`Controller: ${chalk.cyan(controllerUrl)}`);
   logger.log(`Environment: ${chalk.cyan(environment || 'Not specified')}\n`);
@@ -231,6 +274,11 @@ function displayStatus(controllerUrl, environment, tokenInfo) {
   }
 
   displayTokenInfo(tokenInfo);
+
+  if (tokenInfo.authenticated && dataplaneInfo) {
+    displayDataplaneSection(dataplaneInfo.url, dataplaneInfo.connected);
+  }
+
   logger.log('');
 }
 
@@ -255,7 +303,15 @@ async function handleAuthStatus(_options) {
     tokenInfo = await checkClientToken(controllerUrl, environment);
   }
 
-  displayStatus(controllerUrl, environment, tokenInfo);
+  let dataplaneInfo = null;
+  if (tokenInfo && tokenInfo.authenticated && tokenInfo.token) {
+    const authConfig = { type: 'bearer', token: tokenInfo.token };
+    const dataplaneUrl = await resolveDataplaneUrlSilent(controllerUrl, environment, authConfig);
+    const connected = dataplaneUrl ? await checkDataplaneHealth(dataplaneUrl, 5000) : false;
+    dataplaneInfo = { url: dataplaneUrl, connected };
+  }
+
+  displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo);
 }
 
 module.exports = { handleAuthStatus };

package/lib/commands/up-miso.js

@@ -1,7 +1,7 @@
 /**
  * AI Fabrix Builder - Up Miso Command
  *
- * Installs miso-controller and keycloak from images (no build).
+ * Installs keycloak, miso-controller, and dataplane from images (no build).
  * Assumes infra is up; sets dev secrets and resolves (no force; existing .env values preserved).
  *
  * @fileoverview up-miso command implementation
@@ -25,11 +25,13 @@ const { ensureAppFromTemplate } = require('./up-common');
 const KEYCLOAK_BASE_PORT = 8082;
 /** Miso controller base port (dev-config app base) */
 const MISO_BASE_PORT = 3000;
+/** Dataplane base port (from templates/applications/dataplane/variables.yaml) */
+const _DATAPLANE_BASE_PORT = 3001;
 
 /**
- * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string }
- * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1']
- * @returns {{ keycloak?: string, 'miso-controller'?: string }}
+ * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string, dataplane?: string }
+ * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1', 'dataplane=reg/d:v1']
+ * @returns {{ keycloak?: string, 'miso-controller'?: string, dataplane?: string }}
  */
 function parseImageOptions(imageOpts) {
   const map = {};
@@ -48,7 +50,7 @@ function parseImageOptions(imageOpts) {
 
 /**
  * Build full image ref from registry and app variables (registry/name:tag)
- * @param {string} appName - keycloak or miso-controller
+ * @param {string} appName - keycloak, miso-controller, or dataplane
  * @param {string} registry - Registry URL
  * @returns {string} Full image reference
  */
@@ -65,7 +67,7 @@ function buildImageRefFromRegistry(appName, registry) {
 }
 
 /**
- * Set URL secrets and resolve keycloak + miso-controller (no force; existing .env preserved)
+ * Set URL secrets and resolve keycloak + miso-controller + dataplane (no force; existing .env preserved)
  * @async
  * @param {number} devIdNum - Developer ID number
  */
@@ -77,11 +79,12 @@ async function setMisoSecretsAndResolve(devIdNum) {
   logger.log(chalk.green('✓ Set keycloak and miso-controller URL secrets'));
   await secrets.generateEnvFile('keycloak', undefined, 'docker', false, true);
   await secrets.generateEnvFile('miso-controller', undefined, 'docker', false, true);
-  logger.log(chalk.green('✓ Resolved keycloak and miso-controller'));
+  await secrets.generateEnvFile('dataplane', undefined, 'docker', false, true);
+  logger.log(chalk.green('✓ Resolved keycloak, miso-controller, and dataplane'));
 }
 
 /**
- * Build run options and run keycloak then miso-controller
+ * Build run options and run keycloak, miso-controller, then dataplane
  * @async
  * @param {Object} options - Commander options (image, registry, registryMode)
  */
@@ -89,23 +92,27 @@ async function runMisoApps(options) {
   const imageMap = parseImageOptions(options.image);
   const keycloakImage = imageMap.keycloak || (options.registry ? buildImageRefFromRegistry('keycloak', options.registry) : undefined);
   const misoImage = imageMap['miso-controller'] || (options.registry ? buildImageRefFromRegistry('miso-controller', options.registry) : undefined);
-  const keycloakRunOpts = { image: keycloakImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true };
-  const misoRunOpts = { image: misoImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true };
+  const dataplaneImage = imageMap.dataplane || (options.registry ? buildImageRefFromRegistry('dataplane', options.registry) : undefined);
+  const keycloakRunOpts = { image: keycloakImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
+  const misoRunOpts = { image: misoImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
+  const dataplaneRunOpts = { image: dataplaneImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
   logger.log(chalk.blue('Starting keycloak...'));
   await app.runApp('keycloak', keycloakRunOpts);
   logger.log(chalk.blue('Starting miso-controller...'));
   await app.runApp('miso-controller', misoRunOpts);
+  logger.log(chalk.blue('Starting dataplane...'));
+  await app.runApp('dataplane', dataplaneRunOpts);
 }
 
 /**
- * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak then miso-controller.
+ * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak, miso-controller, then dataplane.
  *
  * @async
  * @function handleUpMiso
  * @param {Object} options - Commander options
- * @param {string} [options.registry] - Override registry for both apps
+ * @param {string} [options.registry] - Override registry for all apps
  * @param {string} [options.registryMode] - Override registry mode (acr|external)
- * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1 or miso-controller=reg/m:v1
+ * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1, miso-controller=reg/m:v1, dataplane=reg/d:v1
  * @returns {Promise<void>}
  * @throws {Error} If infra not up or any step fails
  */
@@ -114,8 +121,9 @@ async function handleUpMiso(options = {}) {
   if (builderDir) {
     process.env.AIFABRIX_BUILDER_DIR = builderDir;
   }
-  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
-  const health = await infra.checkInfraHealth();
+  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller + dataplane from images)...\n'));
+  // Strict: only this developer's infra (same as status), so up-miso and status agree
+  const health = await infra.checkInfraHealth(undefined, { strict: true });
   const allHealthy = Object.values(health).every(status => status === 'healthy');
   if (!allHealthy) {
     throw new Error('Infrastructure is not up. Run \'aifabrix up\' first.');
@@ -123,11 +131,12 @@ async function handleUpMiso(options = {}) {
   logger.log(chalk.green('✓ Infrastructure is up'));
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
+  await ensureAppFromTemplate('dataplane');
   const developerId = await config.getDeveloperId();
   const devIdNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   await setMisoSecretsAndResolve(devIdNum);
   await runMisoApps(options);
-  logger.log(chalk.green('\n✓ up-miso complete. Keycloak and miso-controller are running.'));
+  logger.log(chalk.green('\n✓ up-miso complete. Keycloak, miso-controller, and dataplane are running.'));
   logger.log(chalk.gray('  Run onboarding and register Keycloak from the miso-controller repo if needed.'));
 }
 

package/lib/commands/wizard-core-helpers.js

@@ -0,0 +1,278 @@
+/**
+ * @fileoverview Wizard core helpers - OpenAPI/MCP parsing, credential loop, config build/error formatting
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+const logger = require('../utils/logger');
+const { parseOpenApi, testMcpConnection, credentialSelection } = require('../api/wizard.api');
+
+/**
+ * Parse OpenAPI file or URL
+ * @async
+ * @function parseOpenApiSource
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} sourceType - Source type (openapi-file or openapi-url)
+ * @param {string} sourceData - Source data (file path or URL)
+ * @returns {Promise<Object|null>} OpenAPI spec or null
+ */
+async function parseOpenApiSource(dataplaneUrl, authConfig, sourceType, sourceData) {
+  const isUrl = sourceType === 'openapi-url';
+  const spinner = ora(`Parsing OpenAPI ${isUrl ? 'URL' : 'file'}...`).start();
+  try {
+    const parseResponse = await parseOpenApi(dataplaneUrl, authConfig, sourceData, isUrl);
+    spinner.stop();
+    if (!parseResponse.success) {
+      throw new Error(`OpenAPI parsing failed: ${parseResponse.error || parseResponse.formattedError}`);
+    }
+    logger.log(chalk.green(`\u2713 OpenAPI ${isUrl ? 'URL' : 'file'} parsed successfully`));
+    return parseResponse.data?.spec;
+  } catch (error) {
+    spinner.stop();
+    throw error;
+  }
+}
+
+/**
+ * Test MCP server connection
+ * @async
+ * @function testMcpServerConnection
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} sourceData - MCP server details JSON string
+ * @returns {Promise<null>} Always returns null
+ */
+async function testMcpServerConnection(dataplaneUrl, authConfig, sourceData) {
+  const mcpDetails = JSON.parse(sourceData);
+  const spinner = ora('Testing MCP server connection...').start();
+  try {
+    const testResponse = await testMcpConnection(dataplaneUrl, authConfig, mcpDetails.serverUrl, mcpDetails.token);
+    spinner.stop();
+    if (!testResponse.success || !testResponse.data?.connected) {
+      throw new Error(`MCP connection failed: ${testResponse.data?.error || 'Unable to connect'}`);
+    }
+    logger.log(chalk.green('\u2713 MCP server connection successful'));
+  } catch (error) {
+    spinner.stop();
+    throw error;
+  }
+  return null;
+}
+
+/**
+ * Normalize credential config to selection data
+ * @param {Object} [configCredential] - Credential config from wizard.yaml or prompt
+ * @returns {Object} Selection data for API
+ */
+function normalizeCredentialSelectionInput(configCredential) {
+  if (!configCredential) return { action: 'skip' };
+  return {
+    action: configCredential.action,
+    credentialConfig: configCredential.config,
+    credentialIdOrKey: configCredential.credentialIdOrKey
+  };
+}
+
+/**
+ * Run a single credential selection API call
+ * @async
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} selectionData - Selection data
+ * @returns {Promise<{response: Object|null, error: string|null}>}
+ */
+async function runCredentialAttempt(dataplaneUrl, authConfig, selectionData) {
+  const spinner = ora('Processing credential selection...').start();
+  try {
+    const response = await credentialSelection(dataplaneUrl, authConfig, selectionData);
+    spinner.stop();
+    return { response, error: null };
+  } catch (err) {
+    spinner.stop();
+    return { response: null, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Handle credential retry prompt or fail
+ * @async
+ * @param {string} errorMsg - Error message
+ * @param {boolean} allowRetry - Whether to allow retry (interactive)
+ * @param {Object} selectionData - Current selection data
+ * @returns {Promise<{done: boolean, value: null}|{done: boolean, selectionData: Object}>}
+ */
+async function handleCredentialRetryOrFail(errorMsg, allowRetry, selectionData) {
+  const { promptForCredentialIdOrKeyRetry } = require('../generator/wizard-prompts');
+  if (selectionData.action === 'select' && allowRetry) {
+    const retryResult = await promptForCredentialIdOrKeyRetry(errorMsg);
+    if (retryResult.skip) {
+      logger.log(chalk.gray('  Skipping credential selection'));
+      return { done: true, value: null };
+    }
+    return { done: false, selectionData: { action: 'select', credentialIdOrKey: retryResult.credentialIdOrKey } };
+  }
+  logger.log(chalk.yellow(`Warning: Credential selection failed: ${errorMsg}`));
+  return { done: true, value: null };
+}
+
+/**
+ * Run credential selection loop until success or skip
+ * @async
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} selectionData - Initial selection data
+ * @param {boolean} allowRetry - Whether to re-prompt on failure
+ * @returns {Promise<string|null>} Credential ID/key or null
+ */
+async function runCredentialSelectionLoop(dataplaneUrl, authConfig, selectionData, allowRetry) {
+  for (;;) {
+    const { response, error: attemptError } = await runCredentialAttempt(dataplaneUrl, authConfig, selectionData);
+    if (attemptError) {
+      const ret = await handleCredentialRetryOrFail(attemptError, allowRetry, selectionData);
+      if (ret.done) return ret.value;
+      selectionData = ret.selectionData;
+      continue;
+    }
+    if (response.success) {
+      const actionText = selectionData.action === 'create' ? 'created' : 'selected';
+      logger.log(chalk.green(`\u2713 Credential ${actionText}`));
+      return response.data?.credentialIdOrKey || null;
+    }
+    const errorMsg = response.error || response.formattedError || response.message || 'Unknown error';
+    const ret = await handleCredentialRetryOrFail(errorMsg, allowRetry, selectionData);
+    if (ret.done) return ret.value;
+    selectionData = ret.selectionData;
+  }
+}
+
+/**
+ * Build configuration preferences from configPrefs object
+ * @param {Object} [configPrefs] - Preferences from wizard.yaml
+ * @returns {Object} Configuration preferences object
+ */
+function buildConfigPreferences(configPrefs) {
+  return {
+    intent: configPrefs?.intent || 'general integration',
+    fieldOnboardingLevel: configPrefs?.fieldOnboardingLevel || 'full',
+    enableOpenAPIGeneration: configPrefs?.enableOpenAPIGeneration !== false,
+    userPreferences: {
+      enableMCP: configPrefs?.enableMCP || false,
+      enableABAC: configPrefs?.enableABAC || false,
+      enableRBAC: configPrefs?.enableRBAC || false
+    }
+  };
+}
+
+/**
+ * Build configuration payload for API call
+ * @param {Object} params - Parameters object
+ * @param {Object} params.openapiSpec - OpenAPI specification
+ * @param {Object} params.detectedType - Detected type info
+ * @param {string} params.mode - Selected mode
+ * @param {Object} params.prefs - Configuration preferences
+ * @param {string} [params.credentialIdOrKey] - Credential ID or key
+ * @param {string} [params.systemIdOrKey] - System ID or key
+ * @returns {Object} Configuration payload
+ */
+function buildConfigPayload({ openapiSpec, detectedType, mode, prefs, credentialIdOrKey, systemIdOrKey }) {
+  const detectedTypeValue = detectedType?.recommendedType || detectedType?.apiType || detectedType?.selectedType || 'record-based';
+  const payload = {
+    openapiSpec,
+    detectedType: detectedTypeValue,
+    intent: prefs.intent,
+    mode,
+    fieldOnboardingLevel: prefs.fieldOnboardingLevel,
+    enableOpenAPIGeneration: prefs.enableOpenAPIGeneration,
+    userPreferences: prefs.userPreferences
+  };
+  if (credentialIdOrKey) payload.credentialIdOrKey = credentialIdOrKey;
+  if (systemIdOrKey) payload.systemIdOrKey = systemIdOrKey;
+  return payload;
+}
+
+/**
+ * Extract configuration from API response
+ * @param {Object} generateResponse - API response
+ * @returns {Object} Extracted configuration
+ */
+function extractConfigurationFromResponse(generateResponse) {
+  const systemConfig = generateResponse.data?.systemConfig;
+  const datasourceConfigs = generateResponse.data?.datasourceConfigs ||
+    (generateResponse.data?.datasourceConfig ? [generateResponse.data.datasourceConfig] : []);
+  if (!systemConfig) throw new Error('System configuration not found');
+  return { systemConfig, datasourceConfigs, systemKey: generateResponse.data?.systemKey };
+}
+
+/**
+ * Format API errorData as plain text (no chalk) for logging and error.message
+ * @param {Object} [errorData] - API error response errorData
+ * @returns {string} Plain-text validation details
+ */
+function formatValidationDetailsPlain(errorData) {
+  if (!errorData || typeof errorData !== 'object') {
+    return '';
+  }
+  const lines = [];
+  const main = errorData.detail || errorData.title || errorData.errorDescription || errorData.message || errorData.error;
+  if (main) {
+    lines.push(String(main));
+  }
+  if (Array.isArray(errorData.errors) && errorData.errors.length > 0) {
+    lines.push('Validation errors:');
+    errorData.errors.forEach(err => {
+      const field = err.field || err.path || (err.loc && Array.isArray(err.loc) ? err.loc.join('.') : 'validation');
+      const message = err.msg || err.message || 'Invalid value';
+      const value = err.value !== undefined ? ` (value: ${JSON.stringify(err.value)})` : '';
+      lines.push(`  • ${field}: ${message}${value}`);
+    });
+  }
+  if (errorData.configuration && errorData.configuration.errors) {
+    const configErrs = errorData.configuration.errors;
+    lines.push('Configuration errors:');
+    if (Array.isArray(configErrs)) {
+      configErrs.forEach(err => {
+        const field = err.field || err.path || 'configuration';
+        const message = err.message || 'Invalid value';
+        lines.push(`  • ${field}: ${message}`);
+      });
+    } else if (typeof configErrs === 'object') {
+      Object.keys(configErrs).forEach(key => {
+        lines.push(`  • configuration.${key}: ${configErrs[key]}`);
+      });
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Create and throw config generation error with optional formatted message
+ * @param {Object} generateResponse - API response (error)
+ * @throws {Error}
+ */
+function throwConfigGenerationError(generateResponse) {
+  const summary = generateResponse.error || generateResponse.formattedError || 'Unknown error';
+  const detailsPlain = formatValidationDetailsPlain(generateResponse.errorData);
+  const message = detailsPlain
+    ? `Configuration generation failed: ${summary}\n${detailsPlain}`
+    : `Configuration generation failed: ${summary}`;
+  const err = new Error(message);
+  if (generateResponse.formattedError) {
+    err.formatted = generateResponse.formattedError;
+  }
+  throw err;
+}
+
+module.exports = {
+  parseOpenApiSource,
+  testMcpServerConnection,
+  normalizeCredentialSelectionInput,
+  runCredentialSelectionLoop,
+  buildConfigPreferences,
+  buildConfigPayload,
+  extractConfigurationFromResponse,
+  formatValidationDetailsPlain,
+  throwConfigGenerationError
+};