@aifabrix/builder 2.41.0 → 2.42.1

package/lib/generator/index.js

@@ -249,7 +249,10 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
  * @returns {Promise<string>} Path to written deploy JSON
  */
 async function writeExternalDeployJson(appName, appPath, options) {
-  const manifest = await generateControllerManifest(appName, options);
+  const manifest = await generateControllerManifest(appName, {
+    ...options,
+    skipMissingDatasourceFiles: true
+  });
   let effectivePort = 3000;
   try {
     const variablesPath = resolveApplicationConfigPath(appPath);

package/lib/generator/split-readme.js

@@ -25,6 +25,7 @@ function buildReadmeConfigForExternal(deployment) {
       systemType: system.type || 'openapi',
       systemDisplayName: system.displayName || appName,
       systemDescription: system.description || `External system integration for ${appName}`,
+      fileExt: '.yaml',
       datasourceCount: dataSources.length,
       datasources: dataSources
     }

package/lib/generator/split-variables.js

@@ -78,10 +78,12 @@ function extractPortalInputConfiguration(configuration) {
 
 /**
  * Datasource filename for externalIntegration.dataSources.
+ * Avoids duplicate "datasource" in name (e.g. hubspot-users-datasource -> hubspot-datasource-users).
+ *
  * @param {string} systemKey - System key
  * @param {Object} datasource - Datasource from deployment.dataSources
  * @param {number} index - Index
- * @returns {string} Filename e.g. test-hubspot-datasource-companies-data.yaml
+ * @returns {string} Filename e.g. hubspot-datasource-users.yaml
  */
 function getExternalDatasourceFileName(systemKey, datasource, index) {
   const key = datasource.key || '';
@@ -90,6 +92,10 @@ function getExternalDatasourceFileName(systemKey, datasource, index) {
   else if (key.startsWith(`${systemKey}-`)) suffix = key.slice(systemKey.length + 1);
   else if (key) suffix = key;
   else suffix = datasource.entityType || datasource.entityKey || `entity${index + 1}`;
+  // Strip trailing -datasource so we get hubspot-datasource-users not hubspot-datasource-users-datasource
+  if (suffix.endsWith('-datasource')) {
+    suffix = suffix.slice(0, -'-datasource'.length);
+  }
   return `${systemKey}-datasource-${suffix}.yaml`;
 }
 

package/lib/generator/split.js

@@ -139,6 +139,125 @@ async function writeComponentFile(filePath, content) {
   await fs.writeFile(filePath, content, { mode: 0o644, encoding: 'utf8' });
 }
 
+/**
+ * Builds key -> line map from configuration array (for env.template merge).
+ * @param {Array} configuration - Configuration array from deployment
+ * @returns {Map<string, string>} Key to full line map
+ */
+function buildEnvTemplateExpectedByKey(configuration) {
+  const expectedByKey = new Map();
+  if (!Array.isArray(configuration)) return expectedByKey;
+  const lines = extractEnvTemplate(configuration).split('\n').filter(Boolean);
+  for (const line of lines) {
+    const eq = line.indexOf('=');
+    if (eq > 0) {
+      const key = line.substring(0, eq).trim();
+      expectedByKey.set(key, `${key}=${line.substring(eq + 1)}`);
+    }
+  }
+  return expectedByKey;
+}
+
+/**
+ * Pushes the appropriate line for a key that exists in expectedByKey (preserves MISO_CONTROLLER_URL).
+ * @param {string} line - Existing line
+ * @param {string} key - Parsed key
+ * @param {Map<string, string>} expectedByKey - Expected key -> line
+ * @param {string[]} updatedLines - Output lines
+ * @param {Set<string>} keysWritten - Keys already written
+ */
+function pushMergedKeyValueLine(line, key, expectedByKey, updatedLines, keysWritten) {
+  const valueToPush = key === 'MISO_CONTROLLER_URL' ? line : expectedByKey.get(key);
+  updatedLines.push(valueToPush);
+  keysWritten.add(key);
+}
+
+/**
+ * Merges existing env.template with new lines from configuration; preserves comments and unknown keys.
+ * When MISO_CONTROLLER_URL already exists in the file, its value is preserved (only add when missing).
+ * @param {string} existingContent - Current env.template content
+ * @param {Map<string, string>} expectedByKey - New key -> line from download
+ * @returns {string} Merged content
+ */
+function mergeEnvTemplateWithExisting(existingContent, expectedByKey) {
+  const lines = existingContent.split(/\r?\n/);
+  const updatedLines = [];
+  const keysWritten = new Set();
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      updatedLines.push(line);
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (eq <= 0) {
+      updatedLines.push(line);
+      continue;
+    }
+    const key = line.substring(0, eq).trim();
+    if (expectedByKey.has(key)) {
+      pushMergedKeyValueLine(line, key, expectedByKey, updatedLines, keysWritten);
+    } else {
+      updatedLines.push(line);
+    }
+  }
+  for (const key of expectedByKey.keys()) {
+    if (!keysWritten.has(key)) updatedLines.push(expectedByKey.get(key));
+  }
+  return updatedLines.join('\n') + (updatedLines.length > 0 ? '\n' : '');
+}
+
+/**
+ * Writes env.template (merge or overwrite).
+ * @param {string} outputDir - Output directory
+ * @param {string} envTemplate - Default env.template content
+ * @param {Object} options - Options (mergeEnvTemplate, configuration)
+ * @returns {Promise<string>} Path to env.template
+ */
+async function writeEnvTemplateToDir(outputDir, envTemplate, options) {
+  const envTemplatePath = path.join(outputDir, 'env.template');
+  const fsSync = require('fs');
+  if (options.mergeEnvTemplate && options.configuration && fsSync.existsSync(envTemplatePath)) {
+    const expectedByKey = buildEnvTemplateExpectedByKey(options.configuration);
+    const existingContent = await fs.readFile(envTemplatePath, 'utf8');
+    const merged = mergeEnvTemplateWithExisting(existingContent, expectedByKey);
+    await writeComponentFile(envTemplatePath, merged);
+  } else {
+    await writeComponentFile(envTemplatePath, envTemplate);
+  }
+  return envTemplatePath;
+}
+
+/**
+ * Writes application.yaml, rbac.yaml, and README.md.
+ * @param {string} outputDir - Output directory
+ * @param {Object} variables - Variables object
+ * @param {Object|null} rbac - RBAC object or null
+ * @param {string} readme - README content
+ * @param {Object} options - Options (overwriteReadme)
+ * @returns {Promise<Object>} Results with variables, rbac?, readme? paths
+ */
+async function writeVariablesRbacReadme(outputDir, variables, rbac, readme, options) {
+  const out = {};
+  const variablesPath = path.join(outputDir, 'application.yaml');
+  await writeComponentFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: -1 }));
+  out.variables = variablesPath;
+  if (rbac) {
+    const rbacPath = path.join(outputDir, 'rbac.yaml');
+    await writeComponentFile(rbacPath, yaml.dump(rbac, { indent: 2, lineWidth: -1 }));
+    out.rbac = rbacPath;
+  }
+  const readmePath = path.join(outputDir, 'README.md');
+  const fsSync = require('fs');
+  if (options.overwriteReadme === false && fsSync.existsSync(readmePath)) {
+    out.readmeSkipped = readmePath;
+  } else {
+    await writeComponentFile(readmePath, readme);
+    out.readme = readmePath;
+  }
+  return out;
+}
+
 /**
  * Writes all component files
  * @async
@@ -148,36 +267,36 @@ async function writeComponentFile(filePath, content) {
  * @param {Object} variables - Variables object
  * @param {Object|null} rbac - RBAC object or null
  * @param {string} readme - README content
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.mergeEnvTemplate] - If true and env.template exists, merge instead of overwrite
+ * @param {Array} [options.configuration] - Configuration array for merge (required when mergeEnvTemplate)
+ * @param {boolean} [options.overwriteReadme] - If false and README.md exists, skip writing README
  * @returns {Promise<Object>} Results object with file paths
  */
-async function writeComponentFiles(outputDir, envTemplate, variables, rbac, readme) {
+async function writeComponentFiles(outputDir, envTemplate, variables, rbac, readme, options = {}) {
   const results = {};
+  results.envTemplate = await writeEnvTemplateToDir(outputDir, envTemplate, options);
+  Object.assign(results, await writeVariablesRbacReadme(outputDir, variables, rbac, readme, options));
+  return results;
+}
 
-  // Write env.template
-  const envTemplatePath = path.join(outputDir, 'env.template');
-  await writeComponentFile(envTemplatePath, envTemplate);
-  results.envTemplate = envTemplatePath;
-
-  // Write application.yaml
-  const variablesPath = path.join(outputDir, 'application.yaml');
-  const variablesYaml = yaml.dump(variables, { indent: 2, lineWidth: -1 });
-  await writeComponentFile(variablesPath, variablesYaml);
-  results.variables = variablesPath;
-
-  // Write rbac.yml (only if roles/permissions exist)
-  if (rbac) {
-    const rbacPath = path.join(outputDir, 'rbac.yml');
-    const rbacYaml = yaml.dump(rbac, { indent: 2, lineWidth: -1 });
-    await writeComponentFile(rbacPath, rbacYaml);
-    results.rbac = rbacPath;
+/**
+ * Writes datasource YAML files for external system.
+ * @param {string} outputDir - Output directory
+ * @param {string} systemKey - System key
+ * @param {Array} dataSourcesList - DataSources array
+ * @returns {Promise<string[]>} Paths to written datasource files
+ */
+async function writeDatasourceFiles(outputDir, systemKey, dataSourcesList) {
+  const paths = [];
+  for (let i = 0; i < dataSourcesList.length; i++) {
+    const ds = dataSourcesList[i];
+    const fileName = getExternalDatasourceFileName(systemKey, ds, i);
+    const dsPath = path.join(outputDir, fileName);
+    await writeComponentFile(dsPath, yaml.dump(ds, { indent: 2, lineWidth: -1 }));
+    paths.push(dsPath);
   }
-
-  // Write README.md
-  const readmePath = path.join(outputDir, 'README.md');
-  await writeComponentFile(readmePath, readme);
-  results.readme = readmePath;
-
-  return results;
+  return paths;
 }
 
 /**
@@ -194,25 +313,11 @@ async function writeExternalSystemAndDatasourceFiles(outputDir, deployment) {
   const system = deployment.system;
   const systemKey = system.key || 'external-system';
   const dataSourcesList = deployment.dataSources || deployment.datasources || [];
-  const results = {};
-
+  const { roles: _roles, permissions: _permissions, ...systemWithoutRbac } = system;
   const systemPath = path.join(outputDir, `${systemKey}-system.yaml`);
-  const systemYaml = yaml.dump(system, { indent: 2, lineWidth: -1 });
-  await writeComponentFile(systemPath, systemYaml);
-  results.systemFile = systemPath;
-
-  const datasourcePaths = [];
-  for (let i = 0; i < dataSourcesList.length; i++) {
-    const ds = dataSourcesList[i];
-    const fileName = getExternalDatasourceFileName(systemKey, ds, i);
-    const dsPath = path.join(outputDir, fileName);
-    const dsYaml = yaml.dump(ds, { indent: 2, lineWidth: -1 });
-    await writeComponentFile(dsPath, dsYaml);
-    datasourcePaths.push(dsPath);
-  }
-  results.datasourceFiles = datasourcePaths;
-
-  return results;
+  await writeComponentFile(systemPath, yaml.dump(systemWithoutRbac, { indent: 2, lineWidth: -1 }));
+  const datasourcePaths = await writeDatasourceFiles(outputDir, systemKey, dataSourcesList);
+  return { systemFile: systemPath, datasourceFiles: datasourcePaths };
 }
 
 /**
@@ -247,7 +352,49 @@ function normalizeDeploymentForSplit(deployment) {
  * @returns {Promise<Object>} Object with paths to generated files
  * @throws {Error} If JSON file not found or invalid
  */
-async function splitDeployJson(deployJsonPath, outputDir = null) {
+/**
+ * Builds write options for split from splitOptions and config array.
+ * @param {Object} splitOptions - Split options
+ * @param {Array} configArray - Deployment configuration array
+ * @returns {Object} Write options for writeComponentFiles
+ */
+function buildSplitWriteOptions(splitOptions, configArray) {
+  const writeOptions = {};
+  if (splitOptions.mergeEnvTemplate) {
+    writeOptions.mergeEnvTemplate = true;
+    writeOptions.configuration = configArray;
+  }
+  if (splitOptions.overwriteReadme === false) {
+    writeOptions.overwriteReadme = false;
+  }
+  return writeOptions;
+}
+
+/**
+ * Writes external system/datasource files if deployment has system and assigns to result.
+ * @param {string} finalOutputDir - Output directory
+ * @param {Object} deployment - Deployment object
+ * @param {Object} result - Result object to mutate
+ */
+async function applyExternalSystemFilesToResult(finalOutputDir, deployment, result) {
+  if (!deployment.system || typeof deployment.system !== 'object') {
+    return;
+  }
+  const externalFiles = await writeExternalSystemAndDatasourceFiles(finalOutputDir, deployment);
+  if (externalFiles.systemFile) result.systemFile = externalFiles.systemFile;
+  if (externalFiles.datasourceFiles && externalFiles.datasourceFiles.length > 0) {
+    result.datasourceFiles = externalFiles.datasourceFiles;
+  }
+}
+
+/**
+ * @param {string} deployJsonPath - Path to deployment JSON file
+ * @param {string} [outputDir] - Directory to write component files
+ * @param {Object} [splitOptions] - Options for split behavior
+ * @param {boolean} [splitOptions.mergeEnvTemplate] - If true and env.template exists, merge download config into it
+ * @param {boolean} [splitOptions.overwriteReadme] - If false and README.md exists, do not overwrite
+ */
+async function splitDeployJson(deployJsonPath, outputDir = null, splitOptions = {}) {
   validateDeployJsonPath(deployJsonPath);
   const finalOutputDir = await prepareOutputDirectory(deployJsonPath, outputDir);
   const deployment = await loadDeploymentJson(deployJsonPath);
@@ -259,16 +406,9 @@ async function splitDeployJson(deployJsonPath, outputDir = null) {
   const rbac = extractRbacYaml(deployment);
   const readme = generateReadmeFromDeployJson(deployment);
 
-  const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme);
-
-  if (deployment.system && typeof deployment.system === 'object') {
-    const externalFiles = await writeExternalSystemAndDatasourceFiles(finalOutputDir, deployment);
-    if (externalFiles.systemFile) result.systemFile = externalFiles.systemFile;
-    if (externalFiles.datasourceFiles && externalFiles.datasourceFiles.length > 0) {
-      result.datasourceFiles = externalFiles.datasourceFiles;
-    }
-  }
-
+  const writeOptions = buildSplitWriteOptions(splitOptions, configArray);
+  const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme, writeOptions);
+  await applyExternalSystemFilesToResult(finalOutputDir, deployment, result);
   return result;
 }
 

package/lib/generator/wizard-prompts-secondary.js

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview Secondary wizard prompts (credential retry, platform, config review)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const inquirer = require('inquirer');
+const yaml = require('js-yaml');
+
+let hasAutocompletePrompt = false;
+try {
+  const AutocompletePrompt = require('inquirer-autocomplete-prompt');
+  inquirer.registerPrompt('autocomplete', AutocompletePrompt);
+  hasAutocompletePrompt = true;
+} catch {
+  // Fallback: use 'list' if plugin not installed (no search, pageSize 10)
+}
+
+/**
+ * Re-prompt for credential ID/key when validation failed (e.g. not found on dataplane).
+ * Empty input means skip.
+ * @async
+ * @param {string} [previousError] - Error message from dataplane (e.g. "Credential not found")
+ * @returns {Promise<Object>} { credentialIdOrKey: string } or { skip: true } if user leaves empty
+ */
+async function promptForCredentialIdOrKeyRetry(previousError) {
+  const msg = previousError
+    ? `Credential not found or invalid (${String(previousError).slice(0, 60)}). Enter ID/key or leave empty to skip:`
+    : 'Enter credential ID or key (or leave empty to skip):';
+  const { credentialIdOrKey } = await inquirer.prompt([
+    { type: 'input', name: 'credentialIdOrKey', message: msg, default: '' }
+  ]);
+  const trimmed = (credentialIdOrKey && credentialIdOrKey.trim()) || '';
+  return trimmed ? { credentialIdOrKey: trimmed } : { skip: true };
+}
+
+/**
+ * Prompt for known platform selection
+ * @async
+ * @param {Array<{key: string, displayName?: string}>} [platforms] - List of available platforms
+ * @returns {Promise<string>} Selected platform key
+ */
+async function promptForKnownPlatform(platforms = []) {
+  const defaultPlatforms = [
+    { name: 'HubSpot', value: 'hubspot' },
+    { name: 'Salesforce', value: 'salesforce' },
+    { name: 'Zendesk', value: 'zendesk' },
+    { name: 'Slack', value: 'slack' },
+    { name: 'Microsoft 365', value: 'microsoft365' }
+  ];
+  const choices = platforms.length > 0
+    ? platforms.map(p => ({ name: p.displayName || p.key, value: p.key }))
+    : defaultPlatforms;
+  const { platform } = await inquirer.prompt([
+    { type: 'list', name: 'platform', message: 'Select a platform:', choices, pageSize: 10 }
+  ]);
+  return platform;
+}
+
+/**
+ * Format entity for display in list
+ * @param {Object} e - Entity { name, pathCount? }
+ * @returns {string} Display string
+ */
+function _formatEntityChoice(e) {
+  if (!e || typeof e.name !== 'string') return 'unknown';
+  return e.pathCount !== undefined && e.pathCount !== null ? `${e.name} (${e.pathCount} paths)` : e.name;
+}
+
+/**
+ * Prompt to select an entity from discover-entities list (searchable when plugin available)
+ * @async
+ * @param {Array<{name: string, pathCount?: number, schemaMatch?: boolean}>} entities - From discover-entities
+ * @returns {Promise<string>} Selected entity name
+ */
+async function promptForEntitySelection(entities = []) {
+  if (!Array.isArray(entities) || entities.length === 0) {
+    throw new Error('At least one entity is required');
+  }
+  const choices = entities.map(e => ({
+    name: _formatEntityChoice(e),
+    value: e.name
+  }));
+
+  const promptConfig = {
+    type: hasAutocompletePrompt ? 'autocomplete' : 'list',
+    name: 'entityName',
+    message: 'Select entity for datasource generation:',
+    choices,
+    pageSize: 10
+  };
+
+  if (hasAutocompletePrompt) {
+    promptConfig.source = (answers, input) => {
+      const q = (input || '').toLowerCase();
+      const filtered = entities.filter(e => (e.name || '').toLowerCase().includes(q));
+      return Promise.resolve(
+        filtered.map(e => ({ name: _formatEntityChoice(e), value: e.name }))
+      );
+    };
+  }
+
+  const { entityName } = await inquirer.prompt([promptConfig]);
+  return entityName;
+}
+
+/** @param {*} o - Value to stringify */
+const _s = (o) => (o === null || o === undefined || o === '' ? '—' : String(o));
+
+/**
+ * Humanize app key for display name (must stay in sync with prepareWizardContext in lib/generator/wizard.js).
+ * @param {string} appKey - Application key (e.g. hubspot-demo)
+ * @returns {string} Display name (e.g. Hubspot Demo)
+ */
+function humanizeAppKey(appKey) {
+  if (!appKey || typeof appKey !== 'string') return appKey || '';
+  return appKey.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+}
+
+/** @param {Object} sys - systemSummary */
+function _formatSystem(sys) {
+  return [
+    '\nSystem',
+    `  Key:            ${_s(sys.key)}`,
+    `  Display name:   ${_s(sys.displayName)}`,
+    `  Type:           ${_s(sys.type)}`,
+    `  Base URL:       ${_s(sys.baseUrl)}`,
+    `  Auth:           ${_s(sys.authenticationType)}`,
+    `  Endpoints:      ${_s(sys.endpointCount)}`
+  ];
+}
+
+/** @param {Object} ds - datasourceSummary */
+function _formatDatasource(ds) {
+  return [
+    '\nDatasource',
+    `  Key:            ${_s(ds.key)}`,
+    `  Entity:         ${_s(ds.entity)}`,
+    `  Resource type:  ${_s(ds.resourceType)}`,
+    `  CIP steps:      ${_s(ds.cipStepCount)}`,
+    `  Field mappings: ${_s(ds.fieldMappingCount)}`,
+    `  Exposed:        ${_s(ds.exposedProfileCount)} profiles`
+  ];
+}
+
+/** @param {Object} fm - fieldMappingsSummary */
+function _formatFieldMappings(fm) {
+  const mapped = Array.isArray(fm.mappedFields) ? fm.mappedFields : [];
+  const unmapped = Array.isArray(fm.unmappedFields) ? fm.unmappedFields : [];
+  const mappedStr = mapped.length > 0
+    ? `${mapped.length} (${mapped.slice(0, 5).join(', ')}${mapped.length > 5 ? ', ...' : ''})`
+    : _s(fm.mappingCount);
+  const unmappedStr = unmapped.length > 0
+    ? `${unmapped.length} (${unmapped.slice(0, 3).join(', ')}${unmapped.length > 3 ? ', ...' : ''})`
+    : '0';
+  return ['\nField Mappings', `  Mapped:   ${mappedStr}`, `  Unmapped: ${unmappedStr}`];
+}
+
+/**
+ * Derive a preview summary from systemConfig and datasourceConfigs when the dataplane
+ * preview API does not return summaries. Ensures a compact summary is always shown.
+ * When appKey is provided, system key/displayName and datasource keys are overridden
+ * to match what prepareWizardContext will write (so the preview matches saved files).
+ * @param {Object} systemConfig - System configuration
+ * @param {Object[]} datasourceConfigs - Array of datasource configurations
+ * @param {string} [appKey] - Optional app key; when set, overrides system key/displayName and rewrites datasource keys
+ * @returns {Object} Preview object compatible with formatPreviewSummary
+ */
+function _buildDatasourceSummary(ds) {
+  let fieldMappingCount = 0;
+  const attrs = ds.fieldMappings?.attributes ?? ds.attributes ?? {};
+  if (typeof attrs === 'object' && !Array.isArray(attrs)) {
+    fieldMappingCount = Object.keys(attrs).length;
+  }
+  const exposedCount = ds.exposed?.attributes?.length ?? 0;
+  return {
+    key: ds.key,
+    entity: ds.entityType ?? ds.entity ?? ds.resourceType ?? ds.key?.split('-').pop(),
+    resourceType: ds.resourceType,
+    cipStepCount: null,
+    fieldMappingCount: fieldMappingCount || null,
+    exposedProfileCount: exposedCount || null
+  };
+}
+
+function _buildSystemSummary(sys) {
+  const baseUrl = sys.openapi?.servers?.[0]?.url ?? sys.baseUrl ?? sys.openapi?.baseUrl ??
+    sys.authentication?.variables?.baseUrl ?? null;
+  const authType = sys.authentication?.type ?? sys.authentication?.method ?? sys.authenticationType ?? null;
+  const endpointCount = sys.openapi?.endpoints?.length ??
+    (sys.openapi?.operations ? Object.keys(sys.openapi.operations || {}).length : null);
+  return {
+    key: sys.key,
+    displayName: sys.displayName,
+    type: sys.type,
+    baseUrl,
+    authenticationType: authType,
+    endpointCount
+  };
+}
+
+function _buildFieldMappingsSummary(ds0) {
+  const attrs0 = ds0.fieldMappings?.attributes ?? ds0.attributes ?? {};
+  const mappedFields = (typeof attrs0 === 'object' && !Array.isArray(attrs0)) ? Object.keys(attrs0) : [];
+  return mappedFields.length > 0 ? { mappingCount: mappedFields.length, mappedFields, unmappedFields: [] } : null;
+}
+
+function derivePreviewFromConfig(systemConfig, datasourceConfigs, appKey) {
+  const sys = systemConfig || {};
+  const dsList = Array.isArray(datasourceConfigs) ? datasourceConfigs : (datasourceConfigs ? [datasourceConfigs] : []);
+
+  const result = {
+    systemSummary: _buildSystemSummary(sys),
+    fieldMappingsSummary: _buildFieldMappingsSummary(dsList[0] || {})
+  };
+  let datasourceSummaries = dsList.map(_buildDatasourceSummary);
+
+  if (appKey && typeof appKey === 'string') {
+    result.systemSummary.key = appKey;
+    result.systemSummary.displayName = humanizeAppKey(appKey);
+    const originalSystemKey = sys.key || appKey;
+    const originalPrefix = `${originalSystemKey}-`;
+    datasourceSummaries = datasourceSummaries.map((summary, i) => {
+      const ds = dsList[i] || {};
+      const dsKey = ds.key || '';
+      const newKey = dsKey && dsKey.startsWith(originalPrefix)
+        ? `${appKey}-${dsKey.substring(originalPrefix.length)}`
+        : `${appKey}-${ds.entityType || ds.entityKey || (dsKey && dsKey.split('-').pop()) || 'default'}`;
+      return { ...summary, key: newKey };
+    });
+  }
+
+  if (datasourceSummaries.length === 1) {
+    result.datasourceSummary = datasourceSummaries[0];
+  } else if (datasourceSummaries.length > 1) {
+    result.datasourceSummaries = datasourceSummaries;
+  }
+  return result;
+}
+
+/**
+ * Format a preview summary for display (WizardPreviewResponse from dataplane)
+ * @param {Object} preview - Preview data from GET /api/v1/wizard/preview/{sessionId}
+ * @returns {string} Formatted summary text
+ */
+function formatPreviewSummary(preview) {
+  const hasVal = (v) => v !== null && v !== undefined;
+  const parts = ['\n📋 Configuration Preview (what will be created)', '─'.repeat(60)];
+
+  if (preview.systemSummary) parts.push(..._formatSystem(preview.systemSummary));
+  if (preview.datasourceSummaries && preview.datasourceSummaries.length > 0) {
+    preview.datasourceSummaries.forEach((ds, i) => {
+      const lines = _formatDatasource(ds);
+      const label = preview.datasourceSummaries.length > 1 ? `Datasource ${i + 1}` : 'Datasource';
+      parts.push(...lines.map((line, j) => (j === 0 ? line.replace('Datasource', label) : line)));
+    });
+  } else if (preview.datasourceSummary) {
+    parts.push(..._formatDatasource(preview.datasourceSummary));
+  }
+  if (preview.cipPipelineSummary) {
+    const cip = preview.cipPipelineSummary;
+    parts.push('\nCIP Pipeline', `  Steps:          ${_s(cip.stepCount)}`, `  Est. execution: ${_s(cip.estimatedExecutionTime) || '—'}`);
+  }
+  if (preview.fieldMappingsSummary) parts.push(..._formatFieldMappings(preview.fieldMappingsSummary));
+  if (hasVal(preview.estimatedRecords) || hasVal(preview.estimatedSyncTime)) {
+    parts.push('\nEstimates', `  Records:  ${_s(preview.estimatedRecords)}`, `  Sync:     ${_s(preview.estimatedSyncTime)}`);
+  }
+  parts.push('\n' + '─'.repeat(60));
+  return parts.join('\n');
+}
+
+/**
+ * Prompt for configuration review and editing
+ * When preview is provided, displays a compact summary; otherwise dumps full YAML.
+ * @async
+ * @param {Object} opts - Options
+ * @param {Object|null} [opts.preview] - Preview data from getPreview (null = fallback to YAML)
+ * @param {Object} opts.systemConfig - System configuration
+ * @param {Object[]} opts.datasourceConfigs - Array of datasource configurations
+ * @param {string} [opts.appKey] - App key; when set and using fallback preview, overrides system key/displayName and datasource keys
+ * @returns {Promise<Object>} Object with action ('accept'|'cancel') and optionally edited configs
+ */
+async function promptForConfigReview({ preview, systemConfig, datasourceConfigs, appKey }) {
+  const hasSummary = preview && (preview.systemSummary || preview.datasourceSummary || (preview.datasourceSummaries && preview.datasourceSummaries.length > 0));
+  const summaryToShow = hasSummary ? preview : derivePreviewFromConfig(systemConfig, datasourceConfigs, appKey);
+  const canShowSummary = summaryToShow.systemSummary || summaryToShow.datasourceSummary ||
+    (summaryToShow.datasourceSummaries && summaryToShow.datasourceSummaries.length > 0);
+
+  if (canShowSummary) {
+    // eslint-disable-next-line no-console
+    console.log(formatPreviewSummary(summaryToShow));
+  } else {
+    // eslint-disable-next-line no-console
+    console.log('\n📋 Generated Configuration:\nSystem Configuration:');
+    // eslint-disable-next-line no-console
+    console.log(yaml.dump(systemConfig, { lineWidth: -1 }));
+    // eslint-disable-next-line no-console
+    console.log('Datasource Configurations:');
+    (datasourceConfigs || []).forEach((ds, index) => {
+      // eslint-disable-next-line no-console
+      console.log(`\nDatasource ${index + 1}:\n${yaml.dump(ds, { lineWidth: -1 })}`);
+    });
+  }
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'What would you like to do?',
+      choices: [
+        { name: 'Accept and save', value: 'accept' },
+        { name: 'Cancel', value: 'cancel' }
+      ]
+    }
+  ]);
+  return action === 'cancel' ? { action: 'cancel' } : { action: 'accept' };
+}
+
+module.exports = {
+  promptForCredentialIdOrKeyRetry,
+  promptForKnownPlatform,
+  promptForEntitySelection,
+  promptForConfigReview,
+  derivePreviewFromConfig,
+  formatPreviewSummary,
+  humanizeAppKey
+};