@aifabrix/builder 2.41.0 → 2.42.1

package/lib/commands/wizard-core.js

@@ -3,19 +3,21 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines */
 
 const chalk = require('chalk');
 const ora = require('ora');
 const path = require('path');
 const fs = require('fs').promises;
 const logger = require('../utils/logger');
-const { getDeploymentAuth } = require('../utils/token-manager');
+const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { normalizeWizardConfigs } = require('./wizard-config-normalizer');
 const {
   createWizardSession,
   updateWizardSession,
   detectType,
+  getPlatformConfig,
   generateConfig,
   validateWizardConfig,
   getDeploymentDocs,
@@ -29,9 +31,17 @@ const {
   runCredentialSelectionLoop,
   buildConfigPreferences,
   buildConfigPayload,
+  buildPlatformConfigPayload,
   extractConfigurationFromResponse,
-  throwConfigGenerationError
+  writeDebugLog,
+  saveDebugManifestOnErrorAndThrow,
+  throwValidationFailureWithDebug,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 } = require('./wizard-core-helpers');
+const { validateDatasourceKeysBeforePlatformConfig } = require('../validation/validate-datasource-keys-api');
+const { handleEntitySelection } = require('./wizard-entity-selection');
 
 /**
  * Validate app name and check if directory exists
@@ -263,35 +273,57 @@ async function handleTypeDetection(dataplaneUrl, authConfig, openapiSpec) {
  * @param {Object} [options.configPrefs] - Preferences from wizard.yaml
  * @param {string} [options.credentialIdOrKey] - Credential ID or key (optional)
  * @param {string} [options.systemIdOrKey] - System ID or key (optional)
+ * @param {string} [options.sourceType] - Source type (use 'known-platform' to call platforms config endpoint)
+ * @param {string} [options.platformKey] - Platform key for known-platform (e.g. 'hubspot')
+ * @param {string} [options.appName] - App name for writing debug.log when debug=true
  * @returns {Promise<Object>} Generated configuration
  */
+async function callGenerateApi(dataplaneUrl, authConfig, options, prefs) {
+  if (options.sourceType === 'known-platform' && options.platformKey) {
+    await validateDatasourceKeysBeforePlatformConfig(
+      dataplaneUrl, authConfig, options.platformKey, options.datasourceKeys
+    );
+    const platformPayload = buildPlatformConfigPayload({
+      credentialIdOrKey: options.credentialIdOrKey,
+      datasourceKeys: options.datasourceKeys,
+      configurationValues: options.configurationValues,
+      debug: prefs.debug
+    });
+    return await getPlatformConfig(dataplaneUrl, authConfig, options.platformKey, platformPayload);
+  }
+  const configPayload = buildConfigPayload({
+    openapiSpec: options.openapiSpec,
+    detectedType: options.detectedType,
+    mode: options.mode,
+    prefs,
+    credentialIdOrKey: options.credentialIdOrKey,
+    systemIdOrKey: options.systemIdOrKey,
+    entityName: options.entityName,
+    systemDisplayName: options.systemDisplayName
+  });
+  return await generateConfig(dataplaneUrl, authConfig, configPayload);
+}
 
 async function handleConfigurationGeneration(dataplaneUrl, authConfig, options) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: Generate Configuration'));
   const prefs = buildConfigPreferences(options.configPrefs);
   const spinner = ora('Generating configuration via AI (10-30 seconds)...').start();
   try {
-    const configPayload = buildConfigPayload({
-      openapiSpec: options.openapiSpec,
-      detectedType: options.detectedType,
-      mode: options.mode,
-      prefs,
-      credentialIdOrKey: options.credentialIdOrKey,
-      systemIdOrKey: options.systemIdOrKey
-    });
-    const generateResponse = await generateConfig(dataplaneUrl, authConfig, configPayload);
+    const generateResponse = await callGenerateApi(dataplaneUrl, authConfig, options, prefs);
     spinner.stop();
     if (!generateResponse.success) {
-      throwConfigGenerationError(generateResponse);
+      await saveDebugManifestOnErrorAndThrow(generateResponse, { enableDebug: prefs.debug, appName: options.appName });
     }
     const result = extractConfigurationFromResponse(generateResponse);
     const normalized = normalizeWizardConfigs(result.systemConfig, result.datasourceConfigs);
+    if (prefs.debug && options.appName) {
+      const debugLog = generateResponse.data?.debugLog;
+      if (debugLog && typeof debugLog === 'string') {
+        await writeDebugLog(options.appName, debugLog);
+      }
+    }
     logger.log(chalk.green('\u2713 Configuration generated successfully'));
-    return {
-      systemConfig: normalized.systemConfig,
-      datasourceConfigs: normalized.datasourceConfigs,
-      systemKey: result.systemKey
-    };
+    return { systemConfig: normalized.systemConfig, datasourceConfigs: normalized.datasourceConfigs, systemKey: result.systemKey };
   } catch (error) {
     spinner.stop();
     throw error;
@@ -306,9 +338,11 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
  * @param {Object} authConfig - Authentication configuration
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Datasource configurations
+ * @param {Object} [options] - Optional options
+ * @param {boolean} [options.debug] - When true, save debug manifest on validation failure
+ * @param {string} [options.appName] - App name for writing debug files
  */
-// eslint-disable-next-line max-statements
-async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
+async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs, options = {}) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 6: Validate Configuration'));
   const spinner = ora('Validating configuration...').start();
   try {
@@ -322,16 +356,13 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
         const errorDetail = validateResponse.errorData?.detail || validateResponse.errorData?.message;
         const errorMsg = errors.length > 0 ? errors.map(e => e.message || e).join(', ') : errorDetail || validateResponse.error || 'Validation failed';
         spinner.stop();
-        throw new Error(`Configuration validation failed: ${errorMsg}`);
+        await throwValidationFailureWithDebug(validateResponse, systemConfig, configs, errorMsg, options);
       }
       if (validateResponse.data?.warnings?.length > 0) warnings.push(...validateResponse.data.warnings);
     }
     spinner.stop();
     logger.log(chalk.green('\u2713 Configuration validated successfully'));
-    if (warnings.length > 0) {
-      logger.log(chalk.yellow('\n\u26A0 Warnings:'));
-      warnings.forEach(w => logger.log(chalk.yellow(`  - ${w.message || w}`)));
-    }
+    if (warnings.length > 0) logger.log(chalk.yellow('\n\u26A0 Warnings:\n' + warnings.map(w => `  - ${w.message || w}`).join('\n')));
   } catch (error) {
     spinner.stop();
     throw error;
@@ -370,7 +401,9 @@ async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl,
     ? await postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body)
     : await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
   const content = docsResponse?.data?.content ?? docsResponse?.content;
-  if (content && typeof content === 'string') {
+  // Only overwrite README when the API returns substantial content; otherwise keep the template README
+  const MIN_README_LENGTH = 400;
+  if (content && typeof content === 'string' && content.trim().length >= MIN_README_LENGTH) {
     const readmePath = path.join(appPath, 'README.md');
     await fs.writeFile(readmePath, content, 'utf8');
     logger.log(chalk.gray('  Updated README.md from deployment-docs API (application config + deploy JSON).'));
@@ -393,7 +426,9 @@ async function handleFileSaving(appName, systemConfig, datasourceConfigs, system
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 7: Save Files'));
   const spinner = ora('Saving files...').start();
   try {
-    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null });
+    const config = require('../core/config');
+    const format = (await config.getFormat()) || 'yaml';
+    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null, format });
     if (systemKey && dataplaneUrl && authConfig && generatedFiles.appPath) {
       try {
         await tryUpdateReadmeFromDeploymentDocs(generatedFiles.appPath, appName, dataplaneUrl, authConfig, systemKey);
@@ -427,14 +462,14 @@ async function setupDataplaneAndAuth(options, appName) {
   const { resolveEnvironment } = require('../core/config');
   const environment = await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
-  // Prefer device token; use client token or client credentials when available.
-  // Some dataplanes accept only client credentials; getDeploymentAuth tries all.
+  // getDeploymentAuth returns token-based auth only (Bearer); never client-credentials for app endpoints.
   let authConfig;
   try {
     authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
   } catch (error) {
     throw new Error(`Authentication failed: ${error.message}`);
   }
+  requireBearerForDataplanePipeline(authConfig);
   const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
   let dataplaneUrl;
   try {
@@ -459,8 +494,12 @@ module.exports = {
   handleOpenApiParsing,
   handleCredentialSelection,
   handleTypeDetection,
+  handleEntitySelection,
   handleConfigurationGeneration,
   validateWizardConfiguration,
   handleFileSaving,
-  setupDataplaneAndAuth
+  setupDataplaneAndAuth,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 };

package/lib/commands/wizard-dataplane.js

@@ -59,7 +59,7 @@ function isNotFoundError(error) {
 function createDataplaneNotFoundError() {
   return new Error(
     'Could not discover dataplane URL from controller. No dataplane service application found in this environment. ' +
-    'Please provide the dataplane URL using --dataplane <url> flag.'
+    'Ensure the dataplane service is registered in the controller.'
   );
 }
 

package/lib/commands/wizard-entity-selection.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Entity selection step for OpenAPI multi-entity wizard flow
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { discoverEntities } = require('../api/wizard.api');
+const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
+const { promptForEntitySelection } = require('../generator/wizard-prompts');
+
+/**
+ * Handle entity selection step (OpenAPI multi-entity).
+ * Calls discover-entities; if entities found, prompts user to select one.
+ * @async
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} openapiSpec - OpenAPI specification
+ * @returns {Promise<string|null>} Selected entity name or null (skip)
+ */
+async function handleEntitySelection(dataplaneUrl, authConfig, openapiSpec) {
+  if (!openapiSpec || typeof openapiSpec !== 'object') return null;
+  try {
+    const response = await discoverEntities(dataplaneUrl, authConfig, openapiSpec);
+    const entities = response?.data?.entities;
+    if (!Array.isArray(entities) || entities.length === 0) return null;
+
+    logger.log(chalk.blue('\n\uD83D\uDCCB Step 4.5: Select Entity'));
+    const entityName = await promptForEntitySelection(entities);
+    const validation = validateEntityNameForOpenApi(entityName, entities);
+    if (!validation.valid) {
+      throw new Error(`Invalid entity '${entityName}'. Available: ${entities.map(e => e.name).join(', ')}`);
+    }
+    logger.log(chalk.green(`\u2713 Selected entity: ${entityName}`));
+    return entityName;
+  } catch (error) {
+    logger.log(chalk.yellow(`Warning: Entity discovery failed, using default: ${error.message}`));
+    return null;
+  }
+}
+
+module.exports = { handleEntitySelection };

package/lib/commands/wizard-headless.js

@@ -22,6 +22,30 @@ const {
   handleFileSaving,
   setupDataplaneAndAuth
 } = require('./wizard-core');
+const { discoverEntities } = require('../api/wizard.api');
+const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
+const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
+
+/**
+ * Validate entityName for headless config (throws if invalid)
+ * @async
+ * @param {string} entityName - Entity from source
+ * @param {Object} openapiSpec - OpenAPI spec
+ * @param {string} sourceType - Source type
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Auth config
+ * @throws {Error} If entityName invalid
+ */
+async function validateHeadlessEntityName(entityName, openapiSpec, sourceType, dataplaneUrl, authConfig) {
+  if (!entityName || !openapiSpec || sourceType === 'known-platform') return;
+  const discoverResponse = await discoverEntities(dataplaneUrl, authConfig, openapiSpec);
+  const entities = discoverResponse?.data?.entities || [];
+  const validation = validateEntityNameForOpenApi(entityName, entities);
+  if (!validation.valid) {
+    const available = entities.map(e => e.name).join(', ');
+    throw new Error(`Invalid entityName '${entityName}'. Available from discover-entities: ${available || 'none'}`);
+  }
+}
 
 /**
  * Execute wizard flow from config file (headless mode)
@@ -30,11 +54,15 @@ const {
  * @param {Object} wizardConfig - Validated wizard configuration
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [opts] - Optional overrides
+ * @param {boolean} [opts.debug] - Enable debug (CLI --debug); overrides wizard.yaml preferences.debug
  * @returns {Promise<void>} Resolves when wizard flow completes
  * @throws {Error} If wizard flow fails
  */
-async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
+async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, opts = {}) {
   const { appName, mode, systemIdOrKey, source, credential, preferences } = wizardConfig;
+  const configPrefs = { ...preferences };
+  if (opts.debug === true) configPrefs.debug = true;
 
   // Step 1: Create Session
   const { sessionId } = await handleModeSelection(dataplaneUrl, authConfig, mode, systemIdOrKey);
@@ -51,18 +79,31 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
   // Step 4: Detect Type
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
 
+  await validateHeadlessEntityName(source?.entityName, openapiSpec, sourceType, dataplaneUrl, authConfig);
+
+  const systemDisplayName = wizardConfig.systemDisplayName ||
+    (mode === 'create-system' ? humanizeAppKey(appName) : undefined);
+
   // Step 5: Generate Configuration
   const { systemConfig, datasourceConfigs, systemKey } = await handleConfigurationGeneration(dataplaneUrl, authConfig, {
     mode,
     openapiSpec,
     detectedType,
-    configPrefs: preferences,
+    configPrefs,
     credentialIdOrKey,
-    systemIdOrKey
+    systemIdOrKey,
+    sourceType,
+    platformKey: sourceType === 'known-platform' ? sourceData : undefined,
+    datasourceKeys: source?.datasourceKeys,
+    configurationValues: source?.configurationValues,
+    entityName: source?.entityName,
+    appName,
+    systemDisplayName
   });
 
   // Step 6: Validate Configuration
-  await validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
+  const debugOpts = opts.debug ? { debug: true, appName } : {};
+  await validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs, debugOpts);
 
   // Step 7: Save Files
   await handleFileSaving(
@@ -87,6 +128,9 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
 async function handleWizardHeadless(options) {
   logger.log(chalk.blue('\n\uD83E\uDDD9 AI Fabrix External System Wizard (Headless Mode)\n'));
   logger.log(chalk.gray(`Reading configuration from: ${options.config}`));
+  if (options.debug) {
+    logger.log(chalk.gray('[DEBUG] Wizard debug mode enabled'));
+  }
 
   // Validate wizard config file
   const validationResult = await validateWizardConfigFile(options.config);
@@ -109,7 +153,7 @@ async function handleWizardHeadless(options) {
   const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(options, appName);
 
   // Execute wizard flow from config
-  await executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig);
+  await executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, { debug: options.debug });
 }
 
 module.exports = { handleWizardHeadless, executeWizardFromConfig };

package/lib/commands/wizard-helpers.js

@@ -10,15 +10,17 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 
 /**
- * Build preferences object for wizard.yaml (schema shape: intent, fieldOnboardingLevel, enableOpenAPIGeneration, enableMCP, enableABAC, enableRBAC)
+ * Build preferences object for wizard.yaml (schema shape: intent, fieldOnboardingLevel, enableOpenAPIGeneration, enableMCP, enableABAC, enableRBAC, debug)
  * @param {string} intent - User intent
  * @param {Object} preferences - From promptForUserPreferences (fieldOnboardingLevel, mcp, abac, rbac)
+ * @param {Object} [opts] - Optional overrides
+ * @param {boolean} [opts.debug] - Enable debug (CLI --debug); saved to wizard.yaml for headless runs
  * @returns {Object} Preferences for wizard-config schema
  */
-function buildPreferencesForSave(intent, preferences) {
+function buildPreferencesForSave(intent, preferences, opts = {}) {
   const level = preferences?.fieldOnboardingLevel;
   const validLevel = level === 'standard' || level === 'minimal' ? level : 'full';
-  return {
+  const result = {
     intent: intent || 'general integration',
     fieldOnboardingLevel: validLevel,
     enableOpenAPIGeneration: true,
@@ -26,6 +28,8 @@ function buildPreferencesForSave(intent, preferences) {
     enableABAC: Boolean(preferences?.abac),
     enableRBAC: Boolean(preferences?.rbac)
   };
+  if (opts.debug === true || preferences?.debug === true) result.debug = true;
+  return result;
 }
 
 /**