@aifabrix/builder 2.33.6 → 2.36.0

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
+};

package/lib/commands/wizard-core.js

@@ -3,7 +3,7 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
-/* eslint-disable max-lines */
+
 const chalk = require('chalk');
 const ora = require('ora');
 const path = require('path');
@@ -15,15 +15,22 @@ const { normalizeWizardConfigs } = require('./wizard-config-normalizer');
 const {
   createWizardSession,
   updateWizardSession,
-  parseOpenApi,
-  credentialSelection,
   detectType,
   generateConfig,
   validateWizardConfig,
-  getDeploymentDocs,
-  testMcpConnection
+  getDeploymentDocs
 } = require('../api/wizard.api');
 const { generateWizardFiles } = require('../generator/wizard');
+const {
+  parseOpenApiSource,
+  testMcpServerConnection,
+  normalizeCredentialSelectionInput,
+  runCredentialSelectionLoop,
+  buildConfigPreferences,
+  buildConfigPayload,
+  extractConfigurationFromResponse,
+  throwConfigGenerationError
+} = require('./wizard-core-helpers');
 
 /**
  * Validate app name and check if directory exists
@@ -161,59 +168,6 @@ async function handleSourceSelection(dataplaneUrl, sessionId, authConfig, config
   return { sourceType, sourceData };
 }
 
-/**
- * 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;
-}
-
 /**
  * Handle OpenAPI parsing step
  * @async
@@ -242,41 +196,28 @@ async function handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, source
 }
 
 /**
- * Handle credential selection step
+ * Handle credential selection step.
+ * Validation is done by the dataplane (POST /api/v1/wizard/credential-selection).
+ * When action is 'select' and the API fails (e.g. credential not found), and allowRetry is true,
+ * we re-prompt for credential ID/key or allow the user to skip (empty = skip).
  * @async
  * @function handleCredentialSelection
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
- * @param {Object} [configCredential] - Credential config from wizard.yaml
- * @returns {Promise<string|null>} Credential ID/key or null if skipped
+ * @param {Object} [configCredential] - Credential config from wizard.yaml or prompt
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.allowRetry=true] - If true (interactive), re-prompt on failure for 'select'; if false (headless), do not re-prompt
+ * @returns {Promise<string|null>} Credential ID/key or null if skipped / failed
  */
-async function handleCredentialSelection(dataplaneUrl, authConfig, configCredential = null) {
+async function handleCredentialSelection(dataplaneUrl, authConfig, configCredential = null, options = {}) {
+  const allowRetry = options.allowRetry !== false;
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 3: Credential Selection (Optional)'));
-  const selectionData = configCredential ? {
-    action: configCredential.action,
-    credentialConfig: configCredential.config,
-    credentialIdOrKey: configCredential.credentialIdOrKey
-  } : { action: 'skip' };
+  const selectionData = normalizeCredentialSelectionInput(configCredential);
   if (selectionData.action === 'skip') {
     logger.log(chalk.gray('  Skipping credential selection'));
     return null;
   }
-  const spinner = ora('Processing credential selection...').start();
-  try {
-    const response = await credentialSelection(dataplaneUrl, authConfig, selectionData);
-    spinner.stop();
-    if (!response.success) {
-      logger.log(chalk.yellow(`Warning: Credential selection failed: ${response.error}`));
-      return null;
-    }
-    const actionText = selectionData.action === 'create' ? 'created' : 'selected';
-    logger.log(chalk.green(`\u2713 Credential ${actionText}`));
-    return response.data?.credentialIdOrKey || null;
-  } catch (error) {
-    spinner.stop();
-    logger.log(chalk.yellow(`Warning: Credential selection failed: ${error.message}`));
-    return null;
-  }
+  return await runCredentialSelectionLoop(dataplaneUrl, authConfig, selectionData, allowRetry);
 }
 
 /**
@@ -308,67 +249,6 @@ async function handleTypeDetection(dataplaneUrl, authConfig, openapiSpec) {
   return null;
 }
 
-/**
- * Build configuration preferences from configPrefs object
- * @function buildConfigPreferences
- * @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
- * @function buildConfigPayload
- * @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
- * @function extractConfigurationFromResponse
- * @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 };
-}
-
 /**
  * Handle configuration generation step
  * @async
@@ -384,6 +264,7 @@ function extractConfigurationFromResponse(generateResponse) {
  * @param {string} [options.systemIdOrKey] - System ID or key (optional)
  * @returns {Promise<Object>} Generated configuration
  */
+
 async function handleConfigurationGeneration(dataplaneUrl, authConfig, options) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: Generate Configuration'));
   const prefs = buildConfigPreferences(options.configPrefs);
@@ -400,7 +281,7 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
     const generateResponse = await generateConfig(dataplaneUrl, authConfig, configPayload);
     spinner.stop();
     if (!generateResponse.success) {
-      throw new Error(`Configuration generation failed: ${generateResponse.error || generateResponse.formattedError}`);
+      throwConfigGenerationError(generateResponse);
     }
     const result = extractConfigurationFromResponse(generateResponse);
     const normalized = normalizeWizardConfigs(result.systemConfig, result.datasourceConfigs);

package/lib/commands/wizard-headless.js

@@ -45,8 +45,8 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
   // Parse OpenAPI
   const openapiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
 
-  // Step 3: Credential Selection
-  const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig, credential);
+  // Step 3: Credential Selection (no retry prompt in headless)
+  const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig, credential, { allowRetry: false });
 
   // Step 4: Detect Type
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);

package/lib/commands/wizard-helpers.js

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Wizard command helpers - pure and I/O helpers for wizard flow
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+
+/**
+ * Build preferences object for wizard.yaml (schema shape: intent, fieldOnboardingLevel, enableOpenAPIGeneration, enableMCP, enableABAC, enableRBAC)
+ * @param {string} intent - User intent
+ * @param {Object} preferences - From promptForUserPreferences (mcp, abac, rbac)
+ * @returns {Object} Preferences for wizard-config schema
+ */
+function buildPreferencesForSave(intent, preferences) {
+  return {
+    intent: intent || 'general integration',
+    fieldOnboardingLevel: 'full',
+    enableOpenAPIGeneration: true,
+    enableMCP: Boolean(preferences?.mcp),
+    enableABAC: Boolean(preferences?.abac),
+    enableRBAC: Boolean(preferences?.rbac)
+  };
+}
+
+/**
+ * Build source object for wizard.yaml (no secrets)
+ * @param {Object} [source] - Source state
+ * @returns {Object|undefined}
+ */
+function buildSourceForSave(source) {
+  if (!source) return undefined;
+  const out = { type: source.type };
+  if (source.type === 'openapi-file' && source.filePath) out.filePath = source.filePath;
+  if (source.type === 'openapi-url' && source.url) out.url = source.url;
+  if (source.type === 'mcp-server' && source.serverUrl) {
+    out.serverUrl = source.serverUrl;
+    out.token = source.token ? '(set)' : undefined;
+  }
+  if (source.type === 'known-platform' && source.platform) out.platform = source.platform;
+  return out;
+}
+
+/**
+ * Build partial wizard state for saving to wizard.yaml (no secrets)
+ * @param {Object} opts - Collected state
+ * @returns {Object} Serializable wizard config shape
+ */
+function buildWizardStateForSave(opts) {
+  const state = {
+    appName: opts.appKey,
+    mode: opts.mode,
+    source: buildSourceForSave(opts.source)
+  };
+  if (opts.mode === 'add-datasource' && opts.systemIdOrKey) state.systemIdOrKey = opts.systemIdOrKey;
+  if (opts.credential) state.credential = opts.credential;
+  if (opts.preferences) state.preferences = opts.preferences;
+  return state;
+}
+
+/**
+ * Format source config as a short line for display
+ * @param {Object} [source] - Source config
+ * @returns {string|null}
+ */
+function formatSourceLine(source) {
+  if (!source) return null;
+  const s = source;
+  return s.type + (s.filePath ? ` (${s.filePath})` : s.url ? ` (${s.url})` : s.platform ? ` (${s.platform})` : '');
+}
+
+/**
+ * Format preferences config as a short line for display
+ * @param {Object} [preferences] - Preferences config
+ * @returns {string|null}
+ */
+function formatPreferencesLine(preferences) {
+  if (!preferences || (!preferences.intent && (preferences.enableMCP === undefined || preferences.enableMCP === null))) {
+    return null;
+  }
+  const p = preferences;
+  return [p.intent && `intent=${p.intent}`, p.enableMCP && 'MCP', p.enableABAC && 'ABAC', p.enableRBAC && 'RBAC'].filter(Boolean).join(', ') || '(defaults)';
+}
+
+/**
+ * Show a short summary of loaded wizard config (for resume flow)
+ * @param {Object} config - Loaded wizard config
+ * @param {string} displayPath - Path to show (e.g. integration/test/wizard.yaml)
+ */
+function showWizardConfigSummary(config, displayPath) {
+  logger.log(chalk.blue('\n📋 Saved config summary'));
+  logger.log(chalk.gray(`  From: ${displayPath}`));
+  if (config.appName) logger.log(chalk.gray(`  App: ${config.appName}`));
+  if (config.mode) logger.log(chalk.gray(`  Mode: ${config.mode}`));
+  const srcLine = formatSourceLine(config.source);
+  if (srcLine) logger.log(chalk.gray(`  Source: ${srcLine}`));
+  if (config.credential) logger.log(chalk.gray(`  Credential: ${config.credential.action || 'skip'}`));
+  const prefs = formatPreferencesLine(config.preferences);
+  if (prefs) logger.log(chalk.gray(`  Preferences: ${prefs}`));
+  logger.log('');
+}
+
+/**
+ * Ensure integration/<appKey> directory exists
+ * @param {string} appKey - Application key
+ * @returns {Promise<string>} Resolved config path (integration/<appKey>/wizard.yaml)
+ */
+async function ensureIntegrationDir(appKey) {
+  const dir = path.join(process.cwd(), 'integration', appKey);
+  await fs.mkdir(dir, { recursive: true });
+  return path.join(dir, 'wizard.yaml');
+}
+
+/** External system types that support add-datasource (excludes webapp/application) */
+const EXTERNAL_SYSTEM_TYPES = ['openapi', 'mcp', 'custom'];
+
+/**
+ * Returns true if the system is an external system that supports add-datasource (not a webapp).
+ * @param {Object} sys - System object from getExternalSystem (may have type, systemType, or kind)
+ * @returns {boolean}
+ */
+function isExternalSystemForAddDatasource(sys) {
+  const type = (sys?.type || sys?.systemType || sys?.kind || '').toLowerCase();
+  if (!type) return true;
+  if (EXTERNAL_SYSTEM_TYPES.includes(type)) return true;
+  if (['webapp', 'application', 'app'].includes(type)) return false;
+  return true;
+}
+
+module.exports = {
+  buildPreferencesForSave,
+  buildSourceForSave,
+  buildWizardStateForSave,
+  formatSourceLine,
+  formatPreferencesLine,
+  showWizardConfigSummary,
+  ensureIntegrationDir,
+  EXTERNAL_SYSTEM_TYPES,
+  isExternalSystemForAddDatasource
+};