@aifabrix/builder 2.43.0 → 2.44.0

package/lib/commands/auth-config.js

@@ -8,7 +8,7 @@
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
+const { formatBlockingError, formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const {
   setControllerUrl,
   setCurrentEnvironment,
@@ -42,14 +42,14 @@ async function handleSetController(url) {
     if (!loggedInControllerUrl) {
       // No stored credentials: allow setting controller so "aifabrix login" opens the right place
       await setControllerUrl(url);
-      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      logger.log(formatSuccessLine(`Controller URL set to: ${url}`));
       return;
     }
 
     const normalizedLoggedIn = loggedInControllerUrl.trim().replace(/\/+$/, '');
     if (normalizedLoggedIn === normalizedUrl) {
       await setControllerUrl(url);
-      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      logger.log(formatSuccessLine(`Controller URL set to: ${url}`));
       return;
     }
 
@@ -58,7 +58,7 @@ async function handleSetController(url) {
       'To use a different controller either run "aifabrix login" with that controller, or run "aifabrix logout" first to clear credentials, then set the new controller with "aifabrix auth --set-controller <url>".'
     );
   } catch (error) {
-    logger.error(chalk.red(`✗ Failed to set controller URL: ${error.message}`));
+    logger.error(formatBlockingError(`Failed to set controller URL: ${error.message}`));
     throw error;
   }
 }
@@ -95,9 +95,9 @@ async function handleSetEnvironment(environment) {
     // Save environment
     await setCurrentEnvironment(environment);
 
-    logger.log(chalk.green(`✓ Environment set to: ${environment}`));
+    logger.log(formatSuccessLine(`Environment set to: ${environment}`));
   } catch (error) {
-    logger.error(chalk.red(`✗ Failed to set environment: ${error.message}`));
+    logger.error(formatBlockingError(`Failed to set environment: ${error.message}`));
     throw error;
   }
 }

package/lib/commands/auth-status.js

@@ -9,6 +9,7 @@
  */
 
 const chalk = require('chalk');
+const { failureGlyph, successGlyph } = require('../utils/cli-test-layout-chalk');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const { getConfig } = config;
@@ -194,7 +195,7 @@ function displayUserInfo(user) {
  * @param {Object} tokenInfo - Token information
  */
 function displayTokenInfo(tokenInfo) {
-  const statusIcon = tokenInfo.authenticated ? chalk.green('✓') : chalk.red('✗');
+  const statusIcon = tokenInfo.authenticated ? successGlyph() : failureGlyph();
   const statusText = tokenInfo.authenticated ? 'Authenticated' : 'Not authenticated';
 
   logger.log(`  Status: ${statusIcon} ${statusText}`);
@@ -244,7 +245,7 @@ function displayDataplaneSection(dataplaneUrl, dataplaneConnected) {
   logger.log('');
   if (dataplaneUrl) {
     logger.log(`Dataplane: ${chalk.cyan(dataplaneUrl)}`);
-    const statusIcon = dataplaneConnected ? chalk.green('✓') : chalk.red('✗');
+    const statusIcon = dataplaneConnected ? successGlyph() : failureGlyph();
     const statusText = dataplaneConnected ? 'Connected' : 'Not reachable';
     displayOpenApiDocs(null, dataplaneUrl);
     logger.log('');
@@ -297,7 +298,7 @@ function displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo) {
   logger.log(`  Environment: ${chalk.cyan(environment || 'Not specified')}\n`);
 
   if (!tokenInfo) {
-    logger.log(`  Status: ${chalk.red('✗ Not authenticated')}`);
+    logger.log(`  Status: ${failureGlyph()} ${chalk.red('Not authenticated')}`);
     logger.log(`  Token Type: ${chalk.gray('None')}\n`);
     logger.log(chalk.yellow('💡 Run "aifabrix login" to authenticate\n'));
     return;

package/lib/commands/credential-env.js

@@ -1,6 +1,7 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * Credential env command – prompts for KV_* values and writes .env.
- * Used by `aifabrix credential env <system-key>`.
+ * Used by `aifabrix credential env <systemKey>`.
  *
  * @fileoverview Credential env command – interactive credential capture to .env
  * @author AI Fabrix Team
@@ -120,7 +121,7 @@ function buildEnvContent(templateContent, promptValues) {
 /**
  * Runs credential env command: prompt for KV_* values and write .env.
  * @async
- * @param {string} systemKey - External system key (integration/<system-key>/)
+ * @param {string} systemKey - External system key (integration/<systemKey>/)
  * @returns {Promise<string>} Path to written .env file
  * @throws {Error} If env.template missing or write fails
  */
@@ -155,7 +156,7 @@ async function runCredentialEnv(systemKey) {
   const dir = path.dirname(envPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   fs.writeFileSync(envPath, content, { mode: 0o600 });
-  logger.log(chalk.green(`✓ Wrote ${envPath}`));
+  logger.log(formatSuccessLine(`Wrote ${envPath}`));
   return envPath;
 }
 

package/lib/commands/credential-list.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 /**
  * Credential list command – list credentials from Dataplane
  * GET /api/v1/credential. Used by `aifabrix credential list`.
@@ -78,12 +79,12 @@ function displayCredentialList(list, baseUrl) {
 async function ensureControllerAndAuth(options = {}) {
   const controllerUrl = options.controller || (await resolveControllerUrl());
   if (!controllerUrl) {
-    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" first.'));
+    logger.error(formatBlockingError('Controller URL is required. Run "aifabrix login" first.'));
     process.exit(1);
   }
   const authResult = await getCredentialListAuth(controllerUrl);
   if (!authResult || !authResult.token) {
-    logger.error(chalk.red(`❌ No authentication token for controller: ${controllerUrl}`));
+    logger.error(formatBlockingError(`No authentication token for controller: ${controllerUrl}`));
     logger.error(chalk.gray('Run: aifabrix login'));
     process.exit(1);
   }
@@ -129,7 +130,7 @@ async function resolveDataplaneUrlOrExit(controllerUrl, authConfig) {
   try {
     return await resolveCredentialListDataplaneUrl(controllerUrl, authConfig);
   } catch (err) {
-    logger.error(chalk.red(`❌ Could not resolve Dataplane URL: ${err.message}`));
+    logger.error(formatBlockingError(`Could not resolve Dataplane URL: ${err.message}`));
     process.exit(1);
   }
 }
@@ -152,7 +153,7 @@ async function runCredentialList(options = {}) {
   try {
     await fetchAndDisplayCredentials(dataplaneUrl, authConfig, listOptions);
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to list credentials: ${error.message}`));
+    logger.error(formatBlockingError(`Failed to list credentials: ${error.message}`));
     process.exit(1);
   }
 }

package/lib/commands/credential-push.js

@@ -1,6 +1,7 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * Credential push command – pushes KV_* from .env to dataplane.
- * Used by `aifabrix credential push <system-key>`.
+ * Used by `aifabrix credential push <systemKey>`.
  *
  * @fileoverview Credential push command – push credential secrets to dataplane
  * @author AI Fabrix Team
@@ -55,7 +56,7 @@ async function buildPayload(systemKey) {
 function logPushResult(pushResult) {
   if (pushResult.pushed > 0) {
     const keyList = pushResult.keys?.length ? ` (${pushResult.keys.join(', ')})` : '';
-    logger.log(chalk.green(`✓ Pushed ${pushResult.pushed} credential secret(s) to dataplane${keyList}.`));
+    logger.log(formatSuccessLine(`Pushed ${pushResult.pushed} credential secret(s) to dataplane${keyList}.`));
   } else if (pushResult.skipped) {
     logger.log(chalk.yellow('No credential secrets to push (empty .env or no KV_* vars with values).'));
   } else {
@@ -75,7 +76,7 @@ async function runCredentialPush(systemKey) {
   const authConfig = await getDeploymentAuth(controllerUrl, environment, systemKey);
 
   if (!authConfig.token && !authConfig.clientId) {
-    throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register <system-key>" first.');
+    throw new Error('Authentication required. Run "aifabrix login" or "aifabrix app register <systemKey>" first.');
   }
 
   requireBearerForDataplanePipeline(authConfig);

package/lib/commands/datasource-unified-test-cli.js

@@ -0,0 +1,495 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+/**
+ * @fileoverview CLI wiring for `datasource test`, `test-integration`, and `test-e2e` (unified validation + watch).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { runDatasourceTestIntegration } = require('../datasource/test-integration');
+const { runDatasourceTestE2E } = require('../datasource/test-e2e');
+const { runUnifiedDatasourceValidation } = require('../datasource/unified-validation-run');
+const { displayIntegrationTestResults, displayE2EResults } = require('../utils/external-system-display');
+const path = require('path');
+const { getIntegrationPath } = require('../utils/paths');
+const { writeTestLog } = require('../utils/test-log-writer');
+const { includeDebugForRequest } = require('../utils/validation-run-request');
+const {
+  exitFromUnifiedValidationResult,
+  finalizeUnifiedValidationResult,
+  unifiedCliResultFromIntegrationReturn,
+  exitAfterIntegrationDisplay,
+  finalizeAfterIntegrationDisplay,
+  emitCapabilityScopeDiagnostics
+} = require('./datasource-validation-cli');
+const { resolveAppKeyForDatasource } = require('../datasource/resolve-app');
+const { runDatasourceValidationWatchLoop } = require('../utils/datasource-validation-watch');
+const { computeExitCodeFromDatasourceTestRun } = require('../utils/datasource-test-run-exit');
+const { analyzeCapabilityScope } = require('../utils/datasource-test-run-capability-scope');
+const {
+  resolveDebugDisplayMode,
+  formatDatasourceTestRunDebugBlock
+} = require('../utils/datasource-test-run-debug-display');
+const { formatCapabilityFocusSection } = require('../utils/datasource-test-run-display');
+const {
+  datasourceTestHelpAfter,
+  datasourceTestIntegrationHelpAfter,
+  datasourceTestE2eHelpAfter,
+  attachDatasourceWatchOptions,
+  attachDatasourceTestCommonOptions
+} = require('./datasource-unified-test-cli.options');
+
+function integrationBaseDirForLogs(appKey) {
+  return path.dirname(getIntegrationPath(appKey));
+}
+
+async function writeDatasourceTestDebugLogIfRequested(appKey, datasourceKey, result, options) {
+  if (!options || !options.debug) return;
+  const requestMeta = {
+    datasourceKey,
+    runType: 'test',
+    includeDebug: includeDebugForRequest(options.debug)
+  };
+  const envelope = result && typeof result === 'object' ? result.envelope : null;
+  const apiError = result && typeof result === 'object' ? result.apiError : null;
+  const errorMessage = apiError
+    ? apiError.formattedError || apiError.error || 'Request failed'
+    : null;
+  const data = errorMessage
+    ? { request: requestMeta, error: errorMessage }
+    : { request: requestMeta, response: envelope };
+  const logPath = await writeTestLog(
+    appKey,
+    data,
+    'test',
+    integrationBaseDirForLogs(appKey)
+  );
+  logger.log(chalk.gray(`  Debug log: ${logPath}`));
+}
+
+function logDatasourceTestRunDebugAppendix(envelope, debugOpt) {
+  const mode = resolveDebugDisplayMode(debugOpt);
+  if (!mode || !envelope) return;
+  const block = formatDatasourceTestRunDebugBlock(envelope, mode, process.stdout.isTTY);
+  if (block) logger.log(block);
+}
+
+function logE2eCapabilityFocusFromEnvelope(env, capabilityOpt) {
+  if (!env) return;
+  const capKey =
+    capabilityOpt !== undefined && capabilityOpt !== null
+      ? String(capabilityOpt).trim()
+      : '';
+  if (!capKey) return;
+  const sec = formatCapabilityFocusSection(env, capKey);
+  if (sec) logger.log(sec);
+}
+
+/**
+ * Exit code from envelope only (no stderr diagnostics; use when TTY output already ran emit via logEnvelope).
+ * @param {Object|null|undefined} env
+ * @param {Object} options
+ * @returns {number|null} null if no envelope
+ */
+function exitCodeFromDatasourceTestRunEnvelope(env, options) {
+  if (!env || typeof env !== 'object') return null;
+  let code = computeExitCodeFromDatasourceTestRun(env, {
+    warningsAsErrors: false,
+    requireCert: false
+  });
+  const scope = analyzeCapabilityScope(env, options.capability);
+  if (options.strictCapabilityScope === true && scope.violated) {
+    code = Math.max(code, 1);
+  }
+  return code;
+}
+
+/**
+ * Legacy E2E display + exit code (no process.exit; watch mode).
+ * @param {Object} data
+ * @param {Object} options
+ * @returns {number}
+ */
+function finalizeDatasourceTestE2ELegacyPath(data, options) {
+  displayE2EResults(data, options.verbose);
+  logDatasourceTestRunDebugAppendix(data.datasourceTestRun, options.debug);
+  logE2eCapabilityFocusFromEnvelope(data.datasourceTestRun, options.capability);
+  const env = data.datasourceTestRun;
+  if (env) {
+    emitCapabilityScopeDiagnostics(env, { requestedCapabilityKey: options.capability });
+    const code = exitCodeFromDatasourceTestRunEnvelope(env, options);
+    return code === null ? 1 : code;
+  }
+  const steps = data.steps || data.completedActions || [];
+  const failed = data.success === false || steps.some(s => s.success === false || s.error);
+  return failed ? 1 : 0;
+}
+
+/**
+ * Human TTY for single-datasource E2E when DatasourceTestRun envelope is present.
+ * @param {string} datasourceKey
+ * @param {Object} env
+ * @param {Object} options
+ */
+function displayDatasourceTestE2EEnvelopeResults(datasourceKey, env, options) {
+  const success = env.status !== 'fail';
+  displayIntegrationTestResults(
+    {
+      systemKey: env.systemKey || 'unknown',
+      success,
+      datasourceResults: [{ key: datasourceKey, success, datasourceTestRun: env }]
+    },
+    options.verbose,
+    {
+      debug: options.debug,
+      runType: 'e2e',
+      requestedCapabilityKey: options.capability
+    }
+  );
+  logE2eCapabilityFocusFromEnvelope(env, options.capability);
+}
+
+function buildDatasourceTestRunOpts(options) {
+  return {
+    app: options.app,
+    environment: options.env,
+    runType: 'test',
+    payload: options.payload,
+    debug: options.debug,
+    verbose: options.verbose,
+    timeout: options.timeout,
+    async: options.async !== false,
+    noAsync: options.async === false,
+    sync: options.sync === true
+  };
+}
+
+function buildDatasourceTestDisplayOpts(options) {
+  return {
+    json: options.json,
+    summary: options.summary,
+    warningsAsErrors: options.warningsAsErrors,
+    requireCert: options.requireCert,
+    debug: options.debug
+  };
+}
+
+async function runDatasourceUnifiedTestOnceForWatch(datasourceKey, runOpts, displayOpts) {
+  try {
+    const result = await runUnifiedDatasourceValidation(datasourceKey, runOpts);
+    return {
+      exitCode: finalizeUnifiedValidationResult(result, displayOpts),
+      envelope: result.envelope
+    };
+  } catch (err) {
+    logger.error(formatBlockingError('Datasource test failed:'), err.message);
+    return { exitCode: 4, envelope: null };
+  }
+}
+
+async function datasourceTestCommandAction(datasourceKey, options) {
+  const runOpts = buildDatasourceTestRunOpts(options);
+  const displayOpts = buildDatasourceTestDisplayOpts(options);
+  try {
+    if (options.watch) {
+      const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
+      await runDatasourceValidationWatchLoop({
+        appKey,
+        extraPaths: options.watchPath || [],
+        includeApplicationYaml: options.watchApplicationYaml === true,
+        watchCi: options.watchCi === true,
+        watchFullDiff: options.watchFullDiff === true,
+        runOnce: async() => {
+          const result = await runUnifiedDatasourceValidation(datasourceKey, runOpts);
+          await writeDatasourceTestDebugLogIfRequested(appKey, datasourceKey, result, options);
+          return {
+            exitCode: finalizeUnifiedValidationResult(result, displayOpts),
+            envelope: result.envelope
+          };
+        }
+      });
+      return;
+    }
+    const result = await runUnifiedDatasourceValidation(datasourceKey, runOpts);
+    if (options.debug) {
+      try {
+        const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
+        await writeDatasourceTestDebugLogIfRequested(appKey, datasourceKey, result, options);
+      } catch (e) {
+        logger.warn(chalk.yellow(`⚠ Could not write debug log: ${e.message}`));
+      }
+    }
+    exitFromUnifiedValidationResult(result, displayOpts);
+  } catch (error) {
+    logger.error(formatBlockingError('Datasource test failed:'), error.message);
+    process.exit(4);
+  }
+}
+
+function chainDatasourceTestCommand(datasource) {
+  const cmd = datasource
+    .command('test <datasourceKey>')
+    .description('Structural/policy validation for one datasource (unified dataplane API, runType=test)');
+  attachDatasourceTestCommonOptions(cmd, {
+    includeNoAsync: true,
+    verboseHelp: 'Set explain=true on validation request',
+    timeoutHelp: 'Aggregate timeout for POST + polls'
+  });
+  return cmd.addHelpText('after', datasourceTestHelpAfter());
+}
+
+function setupDatasourceTestCommand(datasource) {
+  // watch flags are already attached by attachDatasourceTestCommonOptions()
+  chainDatasourceTestCommand(datasource).action(datasourceTestCommandAction);
+}
+
+function buildIntegrationTestOpts(options) {
+  return {
+    app: options.app,
+    payload: options.payload,
+    environment: options.env,
+    debug: options.debug,
+    verbose: options.verbose,
+    timeout: options.timeout,
+    sync: options.sync === true
+  };
+}
+
+function buildIntegrationUnifiedDisplayOpts(options) {
+  return {
+    json: options.json,
+    summary: options.summary,
+    warningsAsErrors: options.warningsAsErrors,
+    requireCert: options.requireCert,
+    debug: options.debug
+  };
+}
+
+async function runIntegrationOnceForWatch(datasourceKey, integOpts, options, unifiedDisplayOpts) {
+  try {
+    const result = await runDatasourceTestIntegration(datasourceKey, integOpts);
+    const unifiedModes =
+      options.json || options.summary || options.warningsAsErrors || options.requireCert;
+    if (unifiedModes) {
+      const uni = unifiedCliResultFromIntegrationReturn(result);
+      const exitCode = finalizeUnifiedValidationResult(uni, unifiedDisplayOpts);
+      return { exitCode, envelope: uni.envelope };
+    }
+    displayIntegrationTestResults(
+      {
+        systemKey: result.systemKey || 'unknown',
+        datasourceResults: [result],
+        success: result.success
+      },
+      options.verbose,
+      { debug: options.debug, runType: 'integration' }
+    );
+    const exitCode = finalizeAfterIntegrationDisplay(result, {});
+    return { exitCode, envelope: result.datasourceTestRun || null };
+  } catch (err) {
+    logger.error(formatBlockingError('Integration test failed:'), err.message);
+    return { exitCode: 4, envelope: null };
+  }
+}
+
+async function integrationTestCommandAction(datasourceKey, options) {
+  const integOpts = buildIntegrationTestOpts(options);
+  const unifiedDisplayOpts = buildIntegrationUnifiedDisplayOpts(options);
+  try {
+    if (options.watch) {
+      const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
+      await runDatasourceValidationWatchLoop({
+        appKey,
+        extraPaths: options.watchPath || [],
+        includeApplicationYaml: options.watchApplicationYaml === true,
+        watchCi: options.watchCi === true,
+        watchFullDiff: options.watchFullDiff === true,
+        runOnce: () => runIntegrationOnceForWatch(datasourceKey, integOpts, options, unifiedDisplayOpts)
+      });
+      return;
+    }
+    const result = await runDatasourceTestIntegration(datasourceKey, integOpts);
+    const unifiedModes =
+      options.json || options.summary || options.warningsAsErrors || options.requireCert;
+    if (unifiedModes) {
+      exitFromUnifiedValidationResult(unifiedCliResultFromIntegrationReturn(result), unifiedDisplayOpts);
+      return;
+    }
+    displayIntegrationTestResults(
+      {
+        systemKey: result.systemKey || 'unknown',
+        datasourceResults: [result],
+        success: result.success
+      },
+      options.verbose,
+      { debug: options.debug, runType: 'integration' }
+    );
+    exitAfterIntegrationDisplay(result, {});
+  } catch (error) {
+    logger.error(formatBlockingError('Integration test failed:'), error.message);
+    process.exit(4);
+  }
+}
+
+function chainDatasourceTestIntegrationCommand(datasource) {
+  const cmd = datasource
+    .command('test-integration <datasourceKey>')
+    .description('Integration test one datasource (unified validation API, runType=integration)');
+  attachDatasourceTestCommonOptions(cmd, {
+    includeNoAsync: false,
+    debugHelp: 'includeDebug + log under integration/<systemKey>/logs/; TTY appendix: summary, full, or raw'
+  });
+  return cmd.addHelpText('after', datasourceTestIntegrationHelpAfter());
+}
+
+function setupDatasourceTestIntegrationCommand(datasource) {
+  // watch flags are already attached by attachDatasourceTestCommonOptions()
+  chainDatasourceTestIntegrationCommand(datasource).action(integrationTestCommandAction);
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} options
+ * @returns {Promise<{ exitCode: number, envelope: Object|null }>}
+ */
+async function runDatasourceTestE2ECliOnce(datasourceKey, options) {
+  const data = await runDatasourceTestE2E(datasourceKey, {
+    app: options.app,
+    environment: options.env,
+    debug: options.debug,
+    verbose: options.verbose,
+    async: options.async !== false,
+    testCrud: options.testCrud,
+    recordId: options.recordId,
+    cleanup: options.cleanup,
+    primaryKeyValue: options.primaryKeyValue,
+    timeout: options.timeout,
+    capabilityKey: options.capability,
+    sync: options.sync === true
+  });
+  const unifiedModes =
+    options.json || options.summary || options.warningsAsErrors || options.requireCert;
+  if (unifiedModes && data.datasourceTestRun) {
+    const exitCode = finalizeUnifiedValidationResult(
+      {
+        apiError: null,
+        pollTimedOut: false,
+        incompleteNoAsync: false,
+        envelope: data.datasourceTestRun
+      },
+      {
+        json: options.json,
+        summary: options.summary,
+        warningsAsErrors: options.warningsAsErrors,
+        requireCert: options.requireCert,
+        debug: options.debug,
+        requestedCapabilityKey: options.capability,
+        strictCapabilityScope: options.strictCapabilityScope === true
+      }
+    );
+    return { exitCode, envelope: data.datasourceTestRun };
+  }
+  const env = data.datasourceTestRun;
+  if (env && !unifiedModes) {
+    displayDatasourceTestE2EEnvelopeResults(datasourceKey, env, options);
+    const exitCode = exitCodeFromDatasourceTestRunEnvelope(env, options);
+    return { exitCode: exitCode === null ? 1 : exitCode, envelope: env };
+  }
+  const exitCode = finalizeDatasourceTestE2ELegacyPath(data, options);
+  return { exitCode, envelope: data.datasourceTestRun || null };
+}
+
+async function runDatasourceTestE2ECliAction(datasourceKey, options) {
+  const { exitCode } = await runDatasourceTestE2ECliOnce(datasourceKey, options);
+  process.exit(exitCode);
+}
+
+async function e2eTestCommandAction(datasourceKey, capabilityKey, options) {
+  const optObj = options && typeof options === 'object' ? options : {};
+  const capFromArg = typeof capabilityKey === 'string' ? capabilityKey.trim() : '';
+  const capFromFlag = optObj.capability !== undefined && optObj.capability !== null
+    ? String(optObj.capability).trim()
+    : '';
+  const requestedCapability = capFromArg || capFromFlag;
+  if (capFromArg && capFromFlag && capFromArg !== capFromFlag) {
+    logger.warn(
+      chalk.yellow('⚠ Capability mismatch:'),
+      `using positional '${capFromArg}' instead of --capability '${capFromFlag}'.`
+    );
+  }
+  const mergedOptions = { ...optObj, capability: requestedCapability || undefined };
+  try {
+    if (mergedOptions.watch) {
+      const { appKey } = await resolveAppKeyForDatasource(datasourceKey, mergedOptions.app);
+      await runDatasourceValidationWatchLoop({
+        appKey,
+        extraPaths: mergedOptions.watchPath || [],
+        includeApplicationYaml: mergedOptions.watchApplicationYaml === true,
+        watchCi: mergedOptions.watchCi === true,
+        watchFullDiff: mergedOptions.watchFullDiff === true,
+        runOnce: async() => {
+          try {
+            return await runDatasourceTestE2ECliOnce(datasourceKey, mergedOptions);
+          } catch (err) {
+            logger.error(formatBlockingError('E2E test failed:'), err.message);
+            return { exitCode: 3, envelope: null };
+          }
+        }
+      });
+      return;
+    }
+    await runDatasourceTestE2ECliAction(datasourceKey, mergedOptions);
+  } catch (error) {
+    logger.error(formatBlockingError('E2E test failed:'), error.message);
+    process.exit(3);
+  }
+}
+
+function chainDatasourceTestE2ECommand(datasource) {
+  const cmd = datasource
+    .command('test-e2e <datasourceKey> [capabilityKey]')
+    .description('E2E test one datasource (unified validation API, runType=e2e)');
+  attachDatasourceTestCommonOptions(cmd, {
+    includeNoAsync: true,
+    includePayload: false,
+    appHelp: 'Integration folder name (default: resolve from cwd if inside integration/<systemKey>/)',
+    verboseHelp: 'Audit / explain-oriented request flags where applicable',
+    debugHelp: 'includeDebug + log under integration/<systemKey>/logs/; TTY appendix: summary, full, or raw',
+    timeoutHelp: 'Aggregate timeout for POST + polls (default 15m)',
+    timeoutDefault: String(15 * 60 * 1000)
+  });
+  return cmd
+    .option('--test-crud', 'Enable CRUD lifecycle test (e2eOptions.testCrud)')
+    .option('--record-id <id>', 'Record ID for test (e2eOptions.recordId)')
+    .option('--no-cleanup', 'Disable cleanup after test (e2eOptions.cleanup: false)')
+    .option(
+      '--primary-key-value <value|@path>',
+      'Primary key value or path to JSON file (e.g. @pk.json) for e2eOptions.primaryKeyValue'
+    )
+    .option('--capability <key>', 'Capability drill-down (deprecated; use positional [capabilityKey])')
+    .option(
+      '--strict-capability-scope',
+      'Exit 1 if a capability drill-down is requested but the report lists more than one capabilities[] row (plan §2.3)'
+    )
+    .addHelpText('after', datasourceTestE2eHelpAfter());
+}
+
+function setupDatasourceTestE2ECommand(datasource) {
+  // watch flags are already attached by attachDatasourceTestCommonOptions()
+  chainDatasourceTestE2ECommand(datasource).action(e2eTestCommandAction);
+}
+
+module.exports = {
+  setupDatasourceTestCommand,
+  setupDatasourceTestIntegrationCommand,
+  setupDatasourceTestE2ECommand,
+  attachDatasourceWatchOptions,
+  /** @internal Exported for Jest: CLI action coverage without Commander. */
+  runDatasourceUnifiedTestOnceForWatch,
+  datasourceTestCommandAction,
+  runIntegrationOnceForWatch,
+  integrationTestCommandAction,
+  runDatasourceTestE2ECliOnce,
+  e2eTestCommandAction
+};