@aifabrix/builder 2.45.0 → 2.45.5

package/lib/cli/setup-utility.js

@@ -15,40 +15,7 @@ const logger = require('../utils/logger');
 const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
 const { detectAppType, getDeployJsonPath, getResolveAppPath } = require('../utils/paths');
 const { setupResolveCommand } = require('./setup-utility-resolve');
-
-const JSON_HELP_AFTER = `
-Example:
-  $ aifabrix json myapp
-Generates *-deploy.json (or application-schema.json) for commit before deploy.
-`;
-
-const VALIDATE_HELP_AFTER = `
-Examples:
-  $ aifabrix validate myapp
-  $ aifabrix validate myapp --cert-sync
-  $ aifabrix validate --integration
-  $ aifabrix validate --builder
-`;
-
-const REPAIR_HELP_AFTER = `
-Examples:
-  $ aifabrix repair hubspot-demo
-    Align manifest, system/datasource files, RBAC extract, env.template, and deploy JSON under integration/<systemKey>/.
-
-  $ aifabrix repair hubspot-demo --dry-run
-    Show what would change without writing files.
-
-  $ aifabrix repair hubspot-demo --auth oauth2
-    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, basic, …).
-
-  $ aifabrix repair hubspot-demo --rbac --expose --sync --test
-    Optional datasource fixes: RBAC roles/permissions, exposed.schema from attributes, default sync block, testPayload stubs.
-
-  $ aifabrix repair hubspot-demo --doc
-    Regenerate README.md from the current deployment manifest only (other drift fixes unchanged).
-
-  Before overwriting files, repair writes timestamped backups under integration/<systemKey>/backup/ (same as datasource capability copy). Use --no-backup to skip.
-`;
+const { JSON_HELP_AFTER, VALIDATE_HELP_AFTER, REPAIR_HELP_AFTER } = require('./setup-utility-help-after');
 
 /**
  * Resolve app path and type for split-json (integration first, then builder).
@@ -122,7 +89,7 @@ function logSplitJsonResult(result) {
 }
 
 function setupJsonCommand(program) {
-  program.command('json <app>')
+  program.command('json <appKey|systemKey>')
     .description('Write deployment JSON to disk for version control')
     .addHelpText('after', JSON_HELP_AFTER)
     .action(async(appName, options) => {
@@ -156,7 +123,7 @@ function setupJsonCommand(program) {
 }
 
 function setupSplitJsonCommand(program) {
-  program.command('split-json <app>')
+  program.command('split-json <appKey|systemKey>')
     .description('Split deploy JSON into env.template, application.yaml, rbac, README, …')
     .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
     .action(async(appName, options) => {
@@ -263,32 +230,54 @@ function setupRepairCommand(program) {
     });
 }
 
+async function resolveConvertTargetFormat(options) {
+  const config = require('../core/config');
+  const effectiveFormat = options.format || (await config.getFormat());
+  if (!effectiveFormat) {
+    throw new Error(
+      'Option --format is required and must be \'json\' or \'yaml\' (or set default with aifabrix dev set-format)'
+    );
+  }
+  const normalized = effectiveFormat.trim().toLowerCase();
+  if (normalized !== 'json' && normalized !== 'yaml') {
+    throw new Error('Option --format must be \'json\' or \'yaml\'');
+  }
+  return normalized;
+}
+
+function logConvertCommandResults(converted, deleted) {
+  logger.log(formatSuccessParagraph('Convert complete.'));
+  converted.forEach((p) => logger.log(`  • ${p}`));
+  if (deleted.length > 0) {
+    logger.log(chalk.gray('  Removed old files:'));
+    deleted.forEach((p) => logger.log(chalk.gray(`    ${p}`)));
+  }
+}
+
+async function runConvertCommandForApp(appName, options) {
+  const normalized = await resolveConvertTargetFormat(options);
+  const { isProtectionScope } = require('../protection/scope');
+  if (isProtectionScope(appName)) {
+    const { runConvertProtectionBatch } = require('../protection/convert-batch');
+    const { converted, deleted } = await runConvertProtectionBatch(normalized, {
+      force: options.force
+    });
+    logConvertCommandResults(converted, deleted);
+    return;
+  }
+  const { runConvert } = require('../commands/convert');
+  const { converted, deleted } = await runConvert(appName, { format: normalized, force: options.force });
+  logConvertCommandResults(converted, deleted);
+}
+
 function setupConvertCommand(program) {
-  program.command('convert <app>')
-    .description('Convert integration config files between JSON and YAML')
+  program.command('convert <appKey|systemKey>')
+    .description('Convert config files between JSON and YAML (builder/<appKey>/ or integration/<systemKey>/)')
     .option('--format <format>', 'Target format: json | yaml (required unless config format is set)')
     .option('-f, --force', 'Skip confirmation prompt')
     .action(async(appName, options) => {
       try {
-        const config = require('../core/config');
-        const effectiveFormat = options.format || (await config.getFormat());
-        if (!effectiveFormat) {
-          throw new Error(
-            'Option --format is required and must be \'json\' or \'yaml\' (or set default with aifabrix dev set-format)'
-          );
-        }
-        const normalized = effectiveFormat.trim().toLowerCase();
-        if (normalized !== 'json' && normalized !== 'yaml') {
-          throw new Error('Option --format must be \'json\' or \'yaml\'');
-        }
-        const { runConvert } = require('../commands/convert');
-        const { converted, deleted } = await runConvert(appName, { format: normalized, force: options.force });
-        logger.log(formatSuccessParagraph('Convert complete.'));
-        converted.forEach(p => logger.log(`  • ${p}`));
-        if (deleted.length > 0) {
-          logger.log(chalk.gray('  Removed old files:'));
-          deleted.forEach(p => logger.log(chalk.gray(`    ${p}`)));
-        }
+        await runConvertCommandForApp(appName, options);
       } catch (error) {
         handleCommandError(error, 'convert');
         process.exit(1);
@@ -297,8 +286,8 @@ function setupConvertCommand(program) {
 }
 
 function setupShowCommand(program) {
-  program.command('show <app>')
-    .description('Show app from local tree (default) or controller (--online)')
+  program.command('show <appKey|systemKey>')
+    .description('Show builder app or external system from local tree (default) or controller (--online)')
     .option('--online', 'Fetch application data from the controller')
     .option('--json', 'Output as JSON')
     .option(
@@ -368,51 +357,80 @@ async function runValidateBatchBranch(validate, opts) {
   return true;
 }
 
+async function runProtectionValidateBranch(appOrFile, opts) {
+  const { validateProtectionBatchCommand } = require('../protection/validate-batch');
+  const code = await validateProtectionBatchCommand(
+    {
+      env: opts.env,
+      json: (opts.format || '').toLowerCase() === 'json',
+      warningsAsErrors: opts.warningsAsErrors === true,
+      simulate: opts.simulate === true,
+      verbose: opts.verbose === true
+    },
+    logger
+  );
+  if (code !== 0) {
+    process.exit(code);
+  }
+}
+
+function buildValidateJsonPayload(result, appOrFile) {
+  let payload = result;
+  try {
+    if (result?.appPath && appOrFile && typeof appOrFile === 'string') {
+      if (!(fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile())) {
+        const { getManifestSourcePayload } = require('../utils/manifest-source-emit');
+        payload = { ...result, manifestSource: getManifestSourcePayload(appOrFile, result.appPath) };
+      }
+    }
+  } catch {
+    /* keep plain result */
+  }
+  return payload;
+}
+
+function displaySingleValidateResult(appOrFile, result, outFormat, validate) {
+  emitManifestAfterValidateIfApplicable(appOrFile, result, outFormat);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify(buildValidateJsonPayload(result, appOrFile), null, 2));
+    return;
+  }
+  validate.displayValidationResults(result);
+}
+
 async function runValidateCommand(appOrFile, options) {
   const validate = require('../validation/validate');
   const opts = options.opts ? options.opts() : options;
+  const { isProtectionScope } = require('../protection/scope');
+  if (isProtectionScope(appOrFile)) {
+    await runProtectionValidateBranch(appOrFile, opts);
+    return;
+  }
   if (await runValidateBatchBranch(validate, opts)) {
     return;
   }
-
   const outFormat = (opts.format || 'default').toLowerCase();
-
   if (!appOrFile || typeof appOrFile !== 'string') {
     logger.log(chalk.red('App name or file path is required, or use --integration / --builder'));
     process.exit(1);
   }
-
   const result = await validate.validateAppOrFile(appOrFile, {
     ...opts,
     certSync: opts.certSync === true
   });
-  emitManifestAfterValidateIfApplicable(appOrFile, result, outFormat);
-  if (outFormat === 'json') {
-    let payload = result;
-    try {
-      if (result?.appPath && appOrFile && typeof appOrFile === 'string') {
-        if (!(fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile())) {
-          const { getManifestSourcePayload } = require('../utils/manifest-source-emit');
-          payload = { ...result, manifestSource: getManifestSourcePayload(appOrFile, result.appPath) };
-        }
-      }
-    } catch {
-      /* keep plain result */
-    }
-    logger.log(JSON.stringify(payload, null, 2));
-  } else {
-    validate.displayValidationResults(result);
-  }
+  displaySingleValidateResult(appOrFile, result, outFormat, validate);
   if (!result.valid) process.exit(1);
 }
 
 function setupValidateDiffCommands(program) {
-  program.command('validate [appOrFile]')
-    .description('Validate one app/file or all under integration/ or builder/')
+  program.command('validate [appKey|systemKey|file]')
+    .description('Validate appKey, systemKey, file path, .protection batch, or all under integration/ and builder/')
     .addHelpText('after', VALIDATE_HELP_AFTER)
     .option('--format <format>', 'Output format: json | default (human-readable)')
     .option('--integration', 'Validate all applications under integration/')
     .option('--builder', 'Validate all applications under builder/')
+    .option('--warnings-as-errors', 'For .protection: pass strict=true to dataplane validate')
+    .option('--simulate', 'For .protection: run simulate after validate')
     .option(
       '--cert-sync',
       'After successful validation of an external integration, refresh the system file certification block from the dataplane (requires login)'

package/lib/commands/auth-status-dataplane-version.js

@@ -0,0 +1,231 @@
+/**
+ * Auth-status dataplane version refresh + compatibility resolution (plan 142.0).
+ *
+ * Extracted from `auth-status.js` to keep that file under the 500-line limit
+ * (`.cursor/rules/project-rules.mdc → File and Function Size Limits`). The
+ * helpers here are pure-ish (only depend on the dataplane health API and the
+ * `device.<controllerUrl>` cache module) so they are easy to mock in unit
+ * tests.
+ *
+ * @fileoverview Resolve dataplane version + Builder CLI compatibility for auth status
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+const {
+  updateDeviceDataplaneVersions,
+  getDeviceDataplaneVersions
+} = require('../core/config-device-dataplane');
+const {
+  getInstalledCliVersion
+} = require('../utils/dataplane-cli-version-gate');
+const { isAtLeast, isValidSemver } = require('../utils/semver-compare');
+
+/**
+ * Per plan 142.0: invalid semver from the dataplane is logged but does **not**
+ * block the CLI; missing min version means no enforcement.
+ *
+ * @param {string} cliVersion
+ * @param {string|undefined} minBuilderCliVersion
+ * @returns {boolean}
+ */
+function computeCompatibility(cliVersion, minBuilderCliVersion) {
+  if (!minBuilderCliVersion) return true;
+  if (!isValidSemver(minBuilderCliVersion) || !isValidSemver(cliVersion)) {
+    return true;
+  }
+  return isAtLeast(cliVersion, minBuilderCliVersion);
+}
+
+/**
+ * Read `device.<controllerUrl>` cache without throwing.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeReadCache(controllerUrl) {
+  if (!controllerUrl) return null;
+  try {
+    return await getDeviceDataplaneVersions(controllerUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Refresh dataplane health, persist `device.<controllerUrl>` version cache,
+ * and derive the compatibility verdict against the installed Builder CLI.
+ * Falls back to the cached entry when the live probe fails so `auth status`
+ * still shows the last-known values offline.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller URL (cache key)
+ * @param {string} dataplaneUrl - Dataplane base URL for the health probe
+ * @returns {Promise<{
+ *   dataplaneVersion: string|undefined,
+ *   minBuilderCliVersion: string|undefined,
+ *   cliVersion: string,
+ *   compatible: boolean
+ * }>}
+ */
+async function refreshDataplaneVersionInfo(controllerUrl, dataplaneUrl) {
+  const cliVersion = getInstalledCliVersion();
+  let dataplaneVersion;
+  let minBuilderCliVersion;
+
+  try {
+    const snapshot = await fetchDataplaneGeneralHealth(dataplaneUrl);
+    if (snapshot) {
+      dataplaneVersion = snapshot.version;
+      minBuilderCliVersion = snapshot.minBuilderCliVersion;
+      try {
+        await updateDeviceDataplaneVersions(controllerUrl, {
+          version: dataplaneVersion,
+          minBuilderCliVersion: minBuilderCliVersion || null
+        });
+      } catch (_persistError) {
+        // cache write failure must not break the display
+      }
+    }
+  } catch (_fetchError) {
+    // ignore — fall through to cached values
+  }
+
+  if (!dataplaneVersion && !minBuilderCliVersion) {
+    const cached = await safeReadCache(controllerUrl);
+    if (cached) {
+      dataplaneVersion = cached.version;
+      minBuilderCliVersion = cached.minBuilderCliVersion;
+    }
+  }
+
+  const compatible = computeCompatibility(cliVersion, minBuilderCliVersion);
+  return { dataplaneVersion, minBuilderCliVersion, cliVersion, compatible };
+}
+
+/**
+ * Load cached versions only (no live probe). Used when the dataplane is
+ * unreachable so `auth status` can still surface a known compatibility floor.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<{
+ *   dataplaneVersion: string|undefined,
+ *   minBuilderCliVersion: string|undefined,
+ *   cliVersion: string,
+ *   compatible: boolean
+ * }>}
+ */
+async function loadCachedVersionInfo(controllerUrl) {
+  const cliVersion = getInstalledCliVersion();
+  const cached = await safeReadCache(controllerUrl);
+  const dataplaneVersion = cached ? cached.version : undefined;
+  const minBuilderCliVersion = cached ? cached.minBuilderCliVersion : undefined;
+  return {
+    dataplaneVersion,
+    minBuilderCliVersion,
+    cliVersion,
+    compatible: computeCompatibility(cliVersion, minBuilderCliVersion)
+  };
+}
+
+/**
+ * Resolve bearer auth after login (device token preferred, else client app token).
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} environment
+ * @param {Object} loginOptions
+ * @returns {Promise<Object|null>}
+ */
+async function resolveAuthConfigAfterLogin(controllerUrl, environment, loginOptions) {
+  const { getOrRefreshDeviceToken, getDeploymentAuth } = require('../utils/token-manager');
+  const device = await getOrRefreshDeviceToken(controllerUrl);
+  if (device && device.token) {
+    return { type: 'bearer', token: device.token };
+  }
+  if (!loginOptions.app) {
+    return null;
+  }
+  try {
+    return await getDeploymentAuth(controllerUrl, environment, loginOptions.app);
+  } catch (_authError) {
+    return null;
+  }
+}
+
+/**
+ * Resolve dataplane URL after login (mirrors auth-status silent resolver).
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} environment
+ * @param {Object} authConfig
+ * @returns {Promise<string|null>}
+ */
+async function resolveDataplaneUrlAfterLogin(controllerUrl, environment, authConfig) {
+  const { findDataplaneServiceAppKey } = require('./wizard-dataplane');
+  const { getDataplaneUrl } = require('../datasource/deploy');
+  try {
+    const dataplaneAppKey = await findDataplaneServiceAppKey(
+      controllerUrl,
+      environment,
+      authConfig
+    );
+    if (dataplaneAppKey) {
+      return await getDataplaneUrl(controllerUrl, dataplaneAppKey, environment, authConfig);
+    }
+    return await getDataplaneUrl(controllerUrl, 'dataplane', environment, authConfig);
+  } catch (_resolveError) {
+    return null;
+  }
+}
+
+/**
+ * Best-effort health refresh after login when dataplane URL is discoverable.
+ * Never throws — cache failures must not block login success.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller URL (device cache key)
+ * @param {Object} [loginOptions]
+ * @param {string} [loginOptions.app] - App name (credentials login) for client-token auth
+ * @returns {Promise<void>}
+ */
+async function tryRefreshDataplaneVersionAfterLogin(controllerUrl, loginOptions = {}) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    return;
+  }
+  try {
+    const { resolveEnvironment } = require('../core/config');
+    const environment = await resolveEnvironment();
+    const authConfig = await resolveAuthConfigAfterLogin(
+      controllerUrl,
+      environment,
+      loginOptions
+    );
+    if (!authConfig) {
+      return;
+    }
+    const dataplaneUrl = await resolveDataplaneUrlAfterLogin(
+      controllerUrl,
+      environment,
+      authConfig
+    );
+    if (dataplaneUrl) {
+      await refreshDataplaneVersionInfo(controllerUrl, dataplaneUrl);
+    }
+  } catch (_error) {
+    // best-effort only
+  }
+}
+
+module.exports = {
+  refreshDataplaneVersionInfo,
+  loadCachedVersionInfo,
+  computeCompatibility,
+  tryRefreshDataplaneVersionAfterLogin
+};

package/lib/commands/auth-status-display.js

@@ -0,0 +1,94 @@
+/**
+ * Auth-status dataplane version block + blocking upgrade UX (plan 142.0).
+ *
+ * Kept in a separate module so `auth-status.js` stays under the 500-line
+ * limit and so the same display helpers can be reused by future dataplane
+ * gate surfaces (`upload`, `wizard`, `deploy`, …).
+ *
+ * @fileoverview TTY rendering for dataplane / Builder CLI compatibility
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  successGlyph,
+  failureGlyph
+} = require('../utils/cli-test-layout-chalk');
+const {
+  formatCliVersionGateError
+} = require('../utils/dataplane-cli-version-help');
+
+/**
+ * Format a single key/value version line indented under the dataplane block.
+ * @private
+ * @param {string} label
+ * @param {string|undefined|null} value
+ * @returns {string}
+ */
+function versionLine(label, value) {
+  const display = value && String(value).trim() ? chalk.cyan(value) : chalk.gray('—');
+  return `  ${label}: ${display}`;
+}
+
+/**
+ * Render the dataplane version subsection on `aifabrix auth status`.
+ *
+ * Designed to be called immediately after the existing connection/status line,
+ * so the output reads as a single grouped block per layout.md §HEADER BLOCK.
+ *
+ * @param {Object} params
+ * @param {boolean} params.connected - Whether dataplane reachability probe passed
+ * @param {string|undefined} params.dataplaneVersion - From `device.<controllerUrl>.dataplane-version`
+ * @param {string|undefined} params.minBuilderCliVersion - From `device.<controllerUrl>.dataplane-min-cli-version`
+ * @param {string} params.cliVersion - Installed Builder CLI version
+ * @param {boolean} params.compatible - true when CLI ≥ minimum (or no minimum enforced)
+ * @returns {void}
+ */
+function displayDataplaneVersionSection({
+  connected,
+  dataplaneVersion,
+  minBuilderCliVersion,
+  cliVersion,
+  compatible
+}) {
+  if (!connected && !dataplaneVersion) {
+    // Nothing to add — keep auth status quiet when the dataplane probe failed
+    // and no cached version is known (the reachability line already told the user).
+    return;
+  }
+  logger.log(versionLine('Dataplane version', dataplaneVersion));
+  logger.log(versionLine('Min Builder CLI', minBuilderCliVersion));
+  logger.log(versionLine('This CLI', cliVersion));
+  if (!minBuilderCliVersion) {
+    logger.log(`  Compatibility: ${chalk.gray('Not enforced')}`);
+    return;
+  }
+  if (compatible) {
+    logger.log(`  Compatibility: ${successGlyph()} ${chalk.green('OK')}`);
+  } else {
+    logger.log(`  Compatibility: ${failureGlyph()} ${chalk.red('Upgrade required')}`);
+  }
+}
+
+/**
+ * Render the blocking upgrade block (red ✖ + Next actions) under the
+ * dataplane subsection when the CLI is incompatible.
+ *
+ * @param {Object} params
+ * @param {string} params.required - Required minimum semver
+ * @param {string} params.installed - Currently installed semver
+ * @returns {void}
+ */
+function displayCliUpgradeRequired({ required, installed }) {
+  logger.log('');
+  logger.log(formatCliVersionGateError(required, installed));
+}
+
+module.exports = {
+  displayDataplaneVersionSection,
+  displayCliUpgradeRequired
+};

package/lib/commands/auth-status.js

@@ -19,6 +19,19 @@ const { resolveControllerUrl } = require('../utils/controller-url');
 const { findDataplaneServiceAppKey } = require('./wizard-dataplane');
 const { getDataplaneUrl } = require('../datasource/deploy');
 const { checkDataplaneHealth } = require('../utils/dataplane-health');
+const {
+  displayDataplaneVersionSection,
+  displayCliUpgradeRequired
+} = require('./auth-status-display');
+const {
+  refreshDataplaneVersionInfo,
+  loadCachedVersionInfo
+} = require('./auth-status-dataplane-version');
+const {
+  EXIT_NOT_AUTHENTICATED,
+  EXIT_CLI_VERSION_INCOMPATIBLE,
+  EXIT_OK
+} = require('../utils/cli-exit-codes');
 
 /**
  * Format expiration date for display
@@ -290,6 +303,10 @@ function displayOpenApiDocs(controllerUrl, dataplaneUrl) {
  * @param {Object} [dataplaneInfo] - Optional dataplane URL and health
  * @param {string|null} [dataplaneInfo.url] - Dataplane URL
  * @param {boolean} [dataplaneInfo.connected] - Whether dataplane is reachable
+ * @param {string|undefined} [dataplaneInfo.dataplaneVersion]
+ * @param {string|undefined} [dataplaneInfo.minBuilderCliVersion]
+ * @param {string} [dataplaneInfo.cliVersion]
+ * @param {boolean} [dataplaneInfo.compatible]
  */
 function displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo) {
   logger.log(chalk.bold('\n🔐 Authentication Status\n'));
@@ -308,18 +325,61 @@ function displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo) {
 
   if (tokenInfo.authenticated && dataplaneInfo) {
     displayDataplaneSection(dataplaneInfo.url, dataplaneInfo.connected);
+    displayDataplaneVersionSection({
+      connected: dataplaneInfo.connected,
+      dataplaneVersion: dataplaneInfo.dataplaneVersion,
+      minBuilderCliVersion: dataplaneInfo.minBuilderCliVersion,
+      cliVersion: dataplaneInfo.cliVersion,
+      compatible: dataplaneInfo.compatible
+    });
+    if (dataplaneInfo.minBuilderCliVersion && dataplaneInfo.compatible === false) {
+      displayCliUpgradeRequired({
+        required: dataplaneInfo.minBuilderCliVersion,
+        installed: dataplaneInfo.cliVersion
+      });
+    }
   }
 
   logger.log('');
 }
 
+/**
+ * Resolve the dataplane block for auth status (URL, reachability, versions,
+ * compatibility). Returns null when no dataplane is discovered.
+ *
+ * @async
+ * @function buildDataplaneInfo
+ * @param {string} controllerUrl
+ * @param {string} environment
+ * @param {Object} authConfig - Bearer auth config built from a valid token
+ * @returns {Promise<Object|null>}
+ */
+async function buildDataplaneInfo(controllerUrl, environment, authConfig) {
+  const dataplaneUrl = await resolveDataplaneUrlSilent(controllerUrl, environment, authConfig);
+  if (!dataplaneUrl) {
+    return { url: null, connected: false };
+  }
+  const connected = await checkDataplaneHealth(dataplaneUrl, 5000);
+  const versionInfo = connected
+    ? await refreshDataplaneVersionInfo(controllerUrl, dataplaneUrl)
+    : await loadCachedVersionInfo(controllerUrl);
+  return {
+    url: dataplaneUrl,
+    connected,
+    dataplaneVersion: versionInfo.dataplaneVersion,
+    minBuilderCliVersion: versionInfo.minBuilderCliVersion,
+    cliVersion: versionInfo.cliVersion,
+    compatible: versionInfo.compatible
+  };
+}
+
 /**
  * Handle auth status command
  * Controller and environment come from config.yaml (set via aifabrix login or aifabrix auth config).
  * @async
  * @function handleAuthStatus
  * @param {Object} options - Command options
- * @param {boolean} [options.validate] - If true, exit with code 1 when not authenticated
+ * @param {boolean} [options.validate] - If true, exit with code 1 when not authenticated, or code 3 when CLI is older than dataplane minimum
  * @returns {Promise<void>} Resolves when status is displayed
  */
 async function handleAuthStatus(options = {}) {
@@ -338,15 +398,19 @@ async function handleAuthStatus(options = {}) {
   let dataplaneInfo = null;
   if (tokenInfo && tokenInfo.authenticated && tokenInfo.token) {
     const authConfig = { type: 'bearer', token: tokenInfo.token };
-    const dataplaneUrl = await resolveDataplaneUrlSilent(controllerUrl, environment, authConfig);
-    const connected = dataplaneUrl ? await checkDataplaneHealth(dataplaneUrl, 5000) : false;
-    dataplaneInfo = { url: dataplaneUrl, connected };
+    dataplaneInfo = await buildDataplaneInfo(controllerUrl, environment, authConfig);
   }
 
   displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo);
 
-  if (options.validate && (!tokenInfo || !tokenInfo.authenticated)) {
-    process.exit(1);
+  if (options.validate) {
+    if (!tokenInfo || !tokenInfo.authenticated) {
+      process.exit(EXIT_NOT_AUTHENTICATED);
+    }
+    if (dataplaneInfo && dataplaneInfo.minBuilderCliVersion && dataplaneInfo.compatible === false) {
+      process.exit(EXIT_CLI_VERSION_INCOMPATIBLE);
+    }
+    process.exit(EXIT_OK);
   }
 }