@aifabrix/builder 2.41.0 → 2.42.1

package/lib/commands/wizard.js

@@ -3,12 +3,13 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines */
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const {
   promptForMode,
-  promptForSystemIdOrKey,
+  promptForExistingSystem,
   promptForSourceType,
   promptForOpenApiFile,
   promptForOpenApiUrl,
@@ -24,45 +25,30 @@ const {
 const {
   validateAndCheckAppDirectory,
   formatDataplaneRejectedTokenMessage,
+  extractSessionId,
   handleOpenApiParsing,
   handleCredentialSelection,
   handleTypeDetection,
+  handleEntitySelection,
   handleConfigurationGeneration,
   validateWizardConfiguration,
   handleFileSaving,
-  setupDataplaneAndAuth
+  setupDataplaneAndAuth,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 } = require('./wizard-core');
 const { handleWizardHeadless } = require('./wizard-headless');
-const { createWizardSession, updateWizardSession, getWizardPlatforms } = require('../api/wizard.api');
-const { getExternalSystem } = require('../api/external-systems.api');
+const { createWizardSession, updateWizardSession, getWizardPlatforms, getPreview } = require('../api/wizard.api');
 const { writeWizardConfig, wizardConfigExists, validateWizardConfig } = require('../validation/wizard-config-validator');
 const { appendWizardError } = require('../utils/cli-utils');
 const {
   buildPreferencesForSave,
   buildWizardStateForSave,
   showWizardConfigSummary,
-  ensureIntegrationDir,
-  isExternalSystemForAddDatasource
+  ensureIntegrationDir
 } = require('./wizard-helpers');
-
-/**
- * Extract session ID from response data
- * @function extractSessionId
- * @param {Object} responseData - Response data from API
- * @returns {string} Session ID
- * @throws {Error} If session ID not found or invalid
- */
-function extractSessionId(responseData) {
-  let sessionId = responseData?.data?.sessionId || responseData?.sessionId ||
-                  responseData?.data?.session_id || responseData?.session_id;
-  if (sessionId && typeof sessionId === 'object') {
-    sessionId = sessionId.id || sessionId.sessionId || sessionId.session_id;
-  }
-  if (!sessionId || typeof sessionId !== 'string') {
-    throw new Error(`Session ID not found: ${JSON.stringify(responseData, null, 2)}`);
-  }
-  return sessionId;
-}
+const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
 
 /**
  * Create wizard session with given mode and optional systemIdOrKey (no prompts)
@@ -151,7 +137,8 @@ async function handleInteractiveConfigGeneration(options) {
     fieldOnboardingLevel: preferences.fieldOnboardingLevel || 'full',
     enableMCP: preferences.mcp,
     enableABAC: preferences.abac,
-    enableRBAC: preferences.rbac
+    enableRBAC: preferences.rbac,
+    debug: options.debug === true
   };
 
   const result = await handleConfigurationGeneration(options.dataplaneUrl, options.authConfig, {
@@ -160,28 +147,52 @@ async function handleInteractiveConfigGeneration(options) {
     detectedType: options.detectedType,
     configPrefs,
     credentialIdOrKey: options.credentialIdOrKey,
-    systemIdOrKey: options.systemIdOrKey
+    systemIdOrKey: options.systemIdOrKey,
+    sourceType: options.sourceType,
+    platformKey: options.sourceType === 'known-platform' ? options.sourceData : undefined,
+    entityName: options.entityName,
+    appName: options.appName,
+    systemDisplayName: options.systemDisplayName
   });
 
   return {
     ...result,
-    preferences: buildPreferencesForSave(userIntent, preferences)
+    preferences: buildPreferencesForSave(userIntent, preferences, { debug: options.debug })
   };
 }
 
 /**
  * Handle configuration review and validation step (interactive mode only)
+ * Fetches preview summary from dataplane; falls back to YAML dump if preview unavailable.
  * @async
  * @function handleConfigurationReview
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
+ * @param {string} sessionId - Wizard session ID
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Datasource configurations
- * @returns {Promise<Object>} Final configurations
+ * @param {Object} [opts] - Optional options
+ * @param {string} [opts.appKey] - App key for debug manifest path
+ * @param {boolean} [opts.debug] - When true, save debug manifest on validation failure
+ * @returns {Promise<Object|null>} Final configurations or null if cancelled
  */
-async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
+async function handleConfigurationReview(dataplaneUrl, authConfig, sessionId, systemConfig, datasourceConfigs, opts = {}) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 6-7: Review & Validate'));
-  const reviewResult = await promptForConfigReview(systemConfig, datasourceConfigs);
+
+  let preview = null;
+  try {
+    const previewResponse = await getPreview(dataplaneUrl, sessionId, authConfig);
+    if (previewResponse?.success && previewResponse?.data) {
+      preview = previewResponse.data;
+    }
+  } catch {
+    // Fall back to YAML display
+  }
+  if (!preview) {
+    logger.warn('Preview unavailable, showing full configuration.');
+  }
+
+  const reviewResult = await promptForConfigReview({ preview, systemConfig, datasourceConfigs, appKey: opts.appKey });
 
   if (reviewResult.action === 'cancel') {
     logger.log(chalk.yellow('Wizard cancelled.'));
@@ -191,7 +202,10 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig,
   const finalSystemConfig = reviewResult.systemConfig || systemConfig;
   const finalDatasourceConfigs = reviewResult.datasourceConfigs || datasourceConfigs;
 
-  await validateWizardConfiguration(dataplaneUrl, authConfig, finalSystemConfig, finalDatasourceConfigs);
+  await validateWizardConfiguration(dataplaneUrl, authConfig, finalSystemConfig, finalDatasourceConfigs, {
+    debug: opts.debug,
+    appName: opts.appKey
+  });
 
   return { systemConfig: finalSystemConfig, datasourceConfigs: finalDatasourceConfigs };
 }
@@ -208,7 +222,7 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig,
  * @returns {Promise<Object>} Collected state (source, credential, preferences) for wizard.yaml save
  */
 async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOpts, state) {
-  const { mode, systemIdOrKey, platforms } = flowOpts;
+  const { mode, systemIdOrKey, platforms, debug } = flowOpts;
   const { sourceType, sourceData } = await handleInteractiveSourceSelection(
     dataplaneUrl, sessionId, authConfig, platforms
   );
@@ -220,13 +234,13 @@ async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOp
 
   const openapiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
   const credentialAction = await promptForCredentialAction();
-  const configCredential = credentialAction.action === 'skip'
-    ? { action: 'skip' }
-    : { action: credentialAction.action, credentialIdOrKey: credentialAction.credentialIdOrKey };
+  const configCredential = await resolveCredentialConfig(dataplaneUrl, authConfig, credentialAction);
   state.credential = configCredential;
   const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig, configCredential);
 
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
+  const entityName = openapiSpec && sourceType !== 'known-platform'
+    ? await handleEntitySelection(dataplaneUrl, authConfig, openapiSpec) : null;
   const genResult = await handleInteractiveConfigGeneration({
     dataplaneUrl,
     authConfig,
@@ -234,12 +248,25 @@ async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOp
     openapiSpec,
     detectedType,
     credentialIdOrKey,
-    systemIdOrKey
+    systemIdOrKey,
+    sourceType,
+    sourceData,
+    entityName: entityName || undefined,
+    appName: appKey,
+    debug,
+    systemDisplayName: flowOpts.systemDisplayName
   });
   const { systemConfig, datasourceConfigs, systemKey, preferences: savedPrefs } = genResult;
   state.preferences = savedPrefs || {};
 
-  const finalConfigs = await handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
+  const finalConfigs = await handleConfigurationReview(
+    dataplaneUrl,
+    authConfig,
+    sessionId,
+    systemConfig,
+    datasourceConfigs,
+    { appKey, debug }
+  );
   if (!finalConfigs) return null;
 
   await handleFileSaving(
@@ -290,18 +317,23 @@ async function runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sess
  * @returns {Promise<void>} Resolves when wizard flow completes
  */
 async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}) {
-  const { mode, systemIdOrKey, configPath } = flowOpts;
+  const { mode, systemIdOrKey, configPath, debug, systemDisplayName } = flowOpts;
 
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Wizard debug mode enabled for app: ${appKey}`));
+  }
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 1: Create Session'));
   const sessionId = await createSessionFromParams(dataplaneUrl, authConfig, mode, systemIdOrKey, appKey);
   logger.log(chalk.green('\u2713 Session created'));
 
-  const platforms = await getWizardPlatforms(dataplaneUrl, authConfig);
+  const platforms = mode === 'add-datasource' ? [] : await getWizardPlatforms(dataplaneUrl, authConfig);
   const state = await runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sessionId, {
     mode,
     systemIdOrKey,
     platforms,
-    configPath
+    configPath,
+    debug: flowOpts.debug,
+    systemDisplayName
   });
   if (!state) return;
 
@@ -362,26 +394,15 @@ async function resolveCreateNewPath(options, loadedConfig) {
  * @returns {Promise<Object>} { appKey, configPath, dataplaneUrl, authConfig, systemIdOrKey }
  */
 async function resolveAddDatasourcePath(options, loadedConfig) {
-  let systemIdOrKey = loadedConfig?.systemIdOrKey || (await promptForSystemIdOrKey(loadedConfig?.systemIdOrKey));
-  const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(options, systemIdOrKey || 'wizard');
-  let systemResponse;
-  for (;;) {
-    try {
-      systemResponse = await getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig);
-      const sys = systemResponse?.data || systemResponse;
-      if (sys && (systemResponse?.data || systemResponse?.success)) {
-        if (!isExternalSystemForAddDatasource(sys)) {
-          logger.log(chalk.red('Cannot add datasource to a webapp. Please enter an external system ID or key.'));
-          systemIdOrKey = await promptForSystemIdOrKey(systemIdOrKey);
-          continue;
-        }
-        break;
-      }
-    } catch (err) {
-      logger.log(chalk.red(`System not found or error: ${err.message}`));
-    }
-    systemIdOrKey = await promptForSystemIdOrKey(systemIdOrKey);
-  }
+  const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(
+    options,
+    loadedConfig?.systemIdOrKey || loadedConfig?.appKey || 'wizard'
+  );
+  const systemsList = await fetchSystemsListForAddDatasource(dataplaneUrl, authConfig);
+  const initialSystemIdOrKey = loadedConfig?.systemIdOrKey || (await promptForExistingSystem(systemsList, loadedConfig?.systemIdOrKey));
+  const { systemResponse, systemIdOrKey } = await resolveExternalSystemForAddDatasource(
+    dataplaneUrl, authConfig, systemsList, initialSystemIdOrKey
+  );
   const sys = systemResponse?.data || systemResponse;
   const appKey = sys?.key || sys?.systemKey || systemIdOrKey;
   const configPath = await ensureIntegrationDir(appKey);
@@ -449,15 +470,24 @@ async function handleWizardWithSavedConfig(options, loadedConfig, displayPath) {
 }
 
 async function handleWizardInteractive(options) {
-  const mode = await promptForMode();
+  const allowAddDatasource = !options.app;
+  const mode = allowAddDatasource ? await promptForMode(undefined, true) : 'create-system';
   const resolved = mode === 'create-system'
     ? await resolveCreateNewPath(options, null)
     : await resolveAddDatasourcePath(options, null);
   if (!resolved) return;
   const { appKey, configPath, dataplaneUrl, authConfig } = resolved;
   const systemIdOrKey = mode === 'add-datasource' ? resolved.systemIdOrKey : undefined;
+  const systemDisplayName = options.systemDisplayName || options.displayName ||
+    (mode === 'create-system' ? humanizeAppKey(appKey) : undefined);
   try {
-    await executeWizardFlow(appKey, dataplaneUrl, authConfig, { mode, systemIdOrKey, configPath });
+    await executeWizardFlow(appKey, dataplaneUrl, authConfig, {
+      mode,
+      systemIdOrKey,
+      configPath,
+      debug: options.debug,
+      systemDisplayName
+    });
     logger.log(chalk.gray(`To change settings, edit integration/${appKey}/wizard.yaml and run: aifabrix wizard ${appKey}`));
   } catch (error) {
     await handleWizardError(appKey, configPath, mode, systemIdOrKey, error);
@@ -480,5 +510,4 @@ async function handleWizard(options = {}) {
   }
   return await handleWizardInteractive(options);
 }
-
 module.exports = { handleWizard, handleWizardHeadless };

package/lib/core/config.js

@@ -126,7 +126,8 @@ function getDefaultConfig() {
     environment: 'dev',
     controller: undefined,
     environments: {},
-    device: {}
+    device: {},
+    format: undefined
   };
 }
 
@@ -489,4 +490,9 @@ const { createPathConfigFunctions } = require('../utils/config-paths');
 const pathConfigFunctions = createPathConfigFunctions(getConfig, saveConfig);
 Object.assign(exportsObj, pathConfigFunctions);
 
+// Format preference functions
+const { createFormatFunctions } = require('../utils/config-format-preference');
+const formatFunctions = createFormatFunctions(getConfig, saveConfig);
+Object.assign(exportsObj, formatFunctions);
+
 module.exports = exportsObj;

package/lib/core/secrets.js

@@ -206,6 +206,38 @@ async function loadMergedConfigAndUserSecrets() {
   }
 }
 
+/**
+ * Loads merged secrets using config/user cascade, builder file merge, and default fallback.
+ * @async
+ * @returns {Promise<Object>} Merged secrets object (not decrypted)
+ */
+async function loadSecretsWithFallbacks() {
+  let merged = await loadMergedConfigAndUserSecrets();
+  if (!merged || Object.keys(merged).length === 0) {
+    merged = loadPrimaryUserSecrets();
+    if (Object.keys(merged).length === 0) {
+      merged = loadUserSecrets();
+    }
+    merged = await applyCanonicalSecretsOverride(merged);
+  }
+  try {
+    const projectRoot = pathsUtil.getProjectRoot();
+    if (projectRoot) {
+      const builderPath = path.join(projectRoot, 'builder', 'secrets.local.yaml');
+      if (fs.existsSync(builderPath)) {
+        const builderSecrets = mergeUserWithConfigFile(merged || {}, builderPath);
+        if (builderSecrets) merged = builderSecrets;
+      }
+    }
+  } catch {
+    // Ignore (e.g. no project root or read error)
+  }
+  if (Object.keys(merged).length === 0) {
+    merged = loadDefaultSecrets();
+  }
+  return merged;
+}
+
 async function loadSecrets(secretsPath, _appName) {
   if (secretsPath) {
     const resolvedPath = resolveSecretsPath(secretsPath);
@@ -218,18 +250,7 @@ async function loadSecrets(secretsPath, _appName) {
     }
     return await decryptSecretsObject(explicitSecrets);
   }
-
-  let mergedSecrets = await loadMergedConfigAndUserSecrets();
-  if (!mergedSecrets || Object.keys(mergedSecrets).length === 0) {
-    mergedSecrets = loadPrimaryUserSecrets();
-    if (Object.keys(mergedSecrets).length === 0) {
-      mergedSecrets = loadUserSecrets();
-    }
-    mergedSecrets = await applyCanonicalSecretsOverride(mergedSecrets);
-  }
-  if (Object.keys(mergedSecrets).length === 0) {
-    mergedSecrets = loadDefaultSecrets();
-  }
+  const mergedSecrets = await loadSecretsWithFallbacks();
   ensureNonEmptySecrets(mergedSecrets);
   return await decryptSecretsObject(mergedSecrets);
 }

package/lib/datasource/deploy.js

@@ -16,6 +16,11 @@ const { getEnvironmentApplication } = require('../api/environments.api');
 const { publishDatasourceViaPipeline } = require('../api/pipeline.api');
 const { formatApiError } = require('../utils/api-error-handler');
 const logger = require('../utils/logger');
+const { logDataplanePipelineWarning } = require('../utils/dataplane-pipeline-warning');
+const {
+  buildResolvedEnvMapForIntegration,
+  resolveConfigurationValues
+} = require('../utils/configuration-env-resolver');
 const { validateDatasourceFile } = require('./validate');
 
 /**
@@ -50,7 +55,7 @@ async function getDataplaneUrl(controllerUrl, appKey, environment, authConfig) {
   if (!dataplaneUrl) {
     const appType = application.configuration?.type || application.type;
     if (appType === 'external') {
-      throw new Error('Dataplane URL not found for external system. Provide --dataplane <url>.');
+      throw new Error('Dataplane URL not found for external system in application configuration.');
     }
     throw new Error('Dataplane URL not found in application configuration');
   }
@@ -107,8 +112,6 @@ async function validateAndLoadDatasourceFile(filePath) {
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment key
  * @param {string} appKey - Application key
- * @param {Object} [options] - Options
- * @param {string} [options.dataplane] - Dataplane URL override
  * @returns {Promise<Object>} Object with authConfig and dataplaneUrl
  */
 async function setupDeploymentAuth(controllerUrl, environment, appKey) {
@@ -154,6 +157,7 @@ async function setupDeploymentAuth(controllerUrl, environment, appKey) {
 async function publishDatasourceToDataplane(dataplaneUrl, systemKey, authConfig, datasourceConfig) {
   requireBearerForDataplanePipeline(authConfig);
   logger.log(chalk.blue('\n🚀 Publishing datasource to dataplane...'));
+  logDataplanePipelineWarning();
 
   const publishResponse = await publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig, datasourceConfig);
 
@@ -228,6 +232,11 @@ async function deployDatasource(appKey, filePath, _options) {
     throw new Error('systemKey is required in datasource configuration');
   }
 
+  if (Array.isArray(datasourceConfig.configuration) && datasourceConfig.configuration.length > 0) {
+    const { envMap, secrets } = await buildResolvedEnvMapForIntegration(systemKey);
+    resolveConfigurationValues(datasourceConfig.configuration, envMap, secrets, systemKey);
+  }
+
   // Setup authentication and get dataplane URL
   const { authConfig, dataplaneUrl } = await setupDeploymentAuth(controllerUrl, environment, appKey);
 

package/lib/datasource/test-e2e.js

@@ -0,0 +1,219 @@
+/**
+ * Datasource E2E test - run full E2E test via dataplane external API
+ * @fileoverview Datasource E2E test logic (config, credential, sync, data, CIP)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+/* eslint-disable max-statements -- Auth setup, API call, polling, debug log */
+
+const path = require('path');
+const fs = require('fs').promises;
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { getIntegrationPath, resolveIntegrationAppKeyFromCwd } = require('../utils/paths');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getDeviceOnlyAuth } = require('../utils/token-manager');
+const { testDatasourceE2E, getE2ETestRun } = require('../api/external-test.api');
+const { writeTestLog } = require('../utils/test-log-writer');
+
+const DEFAULT_POLL_INTERVAL_MS = 2500;
+const DEFAULT_POLL_TIMEOUT_MS = 15 * 60 * 1000;
+
+/**
+ * Resolve appKey for datasource test-e2e
+ * @param {string} [appKey] - Explicit app key from --app
+ * @returns {string}
+ */
+function resolveAppKey(appKey) {
+  if (appKey) return appKey;
+  const fromCwd = resolveIntegrationAppKeyFromCwd();
+  if (fromCwd) return fromCwd;
+  throw new Error(
+    'Could not determine app context. Use --app <appKey> or run from integration/<appKey>/ directory.'
+  );
+}
+
+/**
+ * Resolve primaryKeyValue for request body: string as-is, or read and parse JSON from @path
+ * @param {string} [value] - Literal value or path prefixed with @ (e.g. @pk.json)
+ * @returns {Promise<string|Object|null>} Resolved value for body.primaryKeyValue, or null if absent
+ */
+async function resolvePrimaryKeyValue(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const str = String(value).trim();
+  if (str.startsWith('@')) {
+    const filePath = path.resolve(str.slice(1).trim());
+    const content = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(content);
+  }
+  return str;
+}
+
+/**
+ * Build E2E request body from options
+ * @param {Object} options - Command options
+ * @returns {Promise<Object>} Request body
+ */
+async function buildE2EBody(options) {
+  const body = {};
+  if (options.debug) body.includeDebug = true;
+  if (options.testCrud === true) body.testCrud = true;
+  if (options.recordId !== undefined && options.recordId !== null && options.recordId !== '') body.recordId = String(options.recordId);
+  if (options.cleanup === false) body.cleanup = false;
+  else if (options.cleanup === true) body.cleanup = true;
+  const pk = await resolvePrimaryKeyValue(options.primaryKeyValue);
+  if (pk !== null && pk !== undefined) body.primaryKeyValue = pk;
+  return body;
+}
+
+/**
+ * Poll E2E test run until completed or failed
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {string} sourceIdOrKey - Source ID or key
+ * @param {string} testRunId - Test run ID
+ * @param {Object} authConfig - Auth config
+ * @param {Object} opts - Poll options
+ * @param {number} [opts.intervalMs] - Poll interval (ms)
+ * @param {number} [opts.timeoutMs] - Max wait (ms)
+ * @param {boolean} [opts.verbose] - Log each poll
+ * @returns {Promise<Object>} Final poll result (status completed or failed)
+ */
+async function pollE2ETestRun(dataplaneUrl, sourceIdOrKey, testRunId, authConfig, opts = {}) {
+  const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  const verbose = opts.verbose === true;
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    last = await getE2ETestRun(dataplaneUrl, sourceIdOrKey, testRunId, authConfig);
+    if (last.status === 'completed' || last.status === 'failed') {
+      return last;
+    }
+    if (verbose) {
+      const steps = last.completedActions || [];
+      logger.log(chalk.gray(`  Polling… status: ${last.status}, ${steps.length} step(s) completed`));
+    }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  throw new Error(
+    `E2E test run did not complete within ${timeoutMs / 1000}s (run ID: ${testRunId})`
+  );
+}
+
+/**
+ * Run E2E test for one datasource (Bearer token or API key required; no client credentials).
+ * Default: async start + polling until completed/failed. Use options.async === false for sync.
+ *
+ * @async
+ * @param {string} datasourceKey - Datasource key (used as sourceIdOrKey)
+ * @param {Object} options - Options
+ * @param {string} [options.app] - App key (or resolve from cwd)
+ * @param {string} [options.environment] - Environment (dev, tst, pro)
+ * @param {boolean} [options.debug] - Include debug, write log file
+ * @param {boolean} [options.verbose] - Verbose output (e.g. poll progress)
+ * @param {boolean} [options.async] - If false, use sync mode (no polling). Default true.
+ * @param {boolean} [options.testCrud] - Set body testCrud true
+ * @param {string} [options.recordId] - Set body recordId
+ * @param {boolean} [options.cleanup] - Set body cleanup (default true)
+ * @param {string} [options.primaryKeyValue] - Set body primaryKeyValue (string or @path to JSON)
+ * @param {number} [options.pollIntervalMs] - Poll interval in ms (default 2500)
+ * @param {number} [options.pollTimeoutMs] - Poll timeout in ms (default 15 min)
+ * @returns {Promise<Object>} E2E test result (steps, success, error, etc.)
+ */
+async function runDatasourceTestE2E(datasourceKey, options = {}) {
+  if (!datasourceKey || typeof datasourceKey !== 'string') {
+    throw new Error('Datasource key is required');
+  }
+  const appKey = resolveAppKey(options.app);
+  const controllerUrl = await resolveControllerUrl();
+  const { resolveEnvironment } = require('../core/config');
+  const environment = options.environment || await resolveEnvironment();
+  const authConfig = await getDeviceOnlyAuth(controllerUrl);
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+
+  logger.log(chalk.blue(`\n🧪 Running E2E test for datasource: ${datasourceKey}`));
+
+  const body = await buildE2EBody(options);
+  const useAsync = options.async !== false;
+  const requestMeta = {
+    sourceIdOrKey: datasourceKey,
+    includeDebug: options.debug,
+    testCrud: options.testCrud,
+    recordId: options.recordId,
+    cleanup: options.cleanup,
+    primaryKeyValue: options.primaryKeyValue !== undefined && options.primaryKeyValue !== null
+  };
+
+  const execOpts = {
+    dataplaneUrl,
+    datasourceKey,
+    authConfig,
+    body,
+    useAsync,
+    verbose: options.verbose,
+    pollIntervalMs: options.pollIntervalMs,
+    pollTimeoutMs: options.pollTimeoutMs
+  };
+  let data;
+  try {
+    data = await executeE2EWithOptionalPoll(execOpts);
+  } catch (error) {
+    if (options.debug) {
+      const appPath = getIntegrationPath(appKey);
+      const integrationDir = path.dirname(appPath);
+      await writeTestLog(appKey, { request: requestMeta, error: error.message }, 'test-e2e', integrationDir);
+    }
+    throw error;
+  }
+
+  if (options.debug) {
+    const appPath = getIntegrationPath(appKey);
+    const integrationDir = path.dirname(appPath);
+    const logPath = await writeTestLog(appKey, { request: requestMeta, response: data }, 'test-e2e', integrationDir);
+    logger.log(chalk.gray(`  Debug log: ${logPath}`));
+  }
+
+  return data;
+}
+
+/**
+ * Call E2E API and optionally poll until completed. On throw, caller should log if debug.
+ * @param {Object} opts - Options
+ * @param {string} opts.dataplaneUrl - Dataplane URL
+ * @param {string} opts.datasourceKey - Source key
+ * @param {Object} opts.authConfig - Auth config
+ * @param {Object} opts.body - Request body
+ * @param {boolean} opts.useAsync - Whether to use async + poll
+ * @param {boolean} opts.verbose - Verbose poll progress
+ * @param {number} [opts.pollIntervalMs] - Override poll interval (ms)
+ * @param {number} [opts.pollTimeoutMs] - Override poll timeout (ms)
+ * @returns {Promise<Object>} Final result data
+ */
+/* eslint-disable-next-line max-params -- single opts object; destructuring in body */
+async function executeE2EWithOptionalPoll(opts) {
+  const { dataplaneUrl, datasourceKey, authConfig, body, useAsync, verbose, pollIntervalMs, pollTimeoutMs } = opts;
+  const response = await testDatasourceE2E(dataplaneUrl, datasourceKey, authConfig, body, {
+    asyncRun: useAsync
+  });
+  let data = response.data || response;
+  if (useAsync && data !== null && data !== undefined && data.testRunId) {
+    data = await pollE2ETestRun(
+      dataplaneUrl,
+      datasourceKey,
+      data.testRunId,
+      authConfig,
+      {
+        intervalMs: pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        timeoutMs: pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS,
+        verbose
+      }
+    );
+  }
+  return data;
+}
+
+module.exports = {
+  runDatasourceTestE2E,
+  resolveAppKey
+};