@aifabrix/builder 2.44.6 → 2.45.5

package/lib/commands/up-common.js

@@ -22,6 +22,23 @@ const { copyTemplateFiles } = require('../validation/template');
 const { ensureReadmeForAppPath, ensureReadmeForApp } = require('../app/readme');
 const { refreshUrlsLocalRegistryFromBuilder } = require('../utils/urls-local-registry');
 
+/**
+ * @param {string[]} entries
+ * @returns {string[]}
+ */
+function uniqueResolvedRoots(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of entries) {
+    const r = path.resolve(e);
+    if (!seen.has(r)) {
+      seen.add(r);
+      out.push(r);
+    }
+  }
+  return out;
+}
+
 /**
  * Copy template to a target path if application config is missing there.
  * After copy, generates README.md from templates/applications/README.md.hbs.
@@ -226,7 +243,11 @@ function isUnderAllowedBuilderRoot(resolvedAppPath, allowedRoots) {
 async function cleanBuilderAppDirs(appNames, opts = {}) {
   const silent = Boolean(opts.silent);
   if (!Array.isArray(appNames) || appNames.length === 0) return;
-  const allowedRoots = [path.resolve(pathsUtil.getBuilderRoot()), path.resolve(pathsUtil.getSystemBuilderRoot())];
+  const allowedRoots = uniqueResolvedRoots([
+    path.join(process.cwd(), 'builder'),
+    pathsUtil.getBuilderRoot(),
+    pathsUtil.getSystemBuilderRoot()
+  ]);
   const cleaned = [];
   for (const appName of appNames) {
     if (!appName || typeof appName !== 'string') continue;
@@ -253,8 +274,9 @@ async function cleanBuilderAppDirs(appNames, opts = {}) {
  * Uses AIFABRIX_BUILDER_DIR when set (e.g. by up-miso/up-dataplane from config aifabrix-env-config).
  * When `process.env.AIFABRIX_BUILDER_DIR` is set and the primary app path differs from
  * `cwd/builder/<appName>`, also copies into `cwd/builder/<appName>` so the repo tree is not empty
- * while using a custom builder root. Skips that extra copy when no custom dir is in use (e.g.
- * platform apps materialized only under the system builder root).
+ * while using a custom builder root. Skips that extra copy for platform apps (`keycloak`,
+ * `miso-controller`, `dataplane`) so they materialize only under the system builder root, and when
+ * no custom dir is in use.
  *
  * @async
  * @function ensureAppFromTemplate
@@ -281,7 +303,8 @@ async function ensureAppFromTemplate(appName) {
   const cwdBuilderPath = path.join(process.cwd(), 'builder', appName);
   if (
     envBuilderRoot &&
-    path.resolve(cwdBuilderPath) !== path.resolve(appPath)
+    path.resolve(cwdBuilderPath) !== path.resolve(appPath) &&
+    !pathsUtil.isSystemBuilderAppName(appName)
   ) {
     const cwdCopied = await ensureTemplateAtPath(appName, cwdBuilderPath);
     if (cwdCopied) {
@@ -295,22 +318,32 @@ async function ensureAppFromTemplate(appName) {
 }
 
 /**
- * For `aifabrix up-platform` only: align builder dir env with up-miso/up-dataplane, materialize all three
- * platform apps from templates if missing, then refresh `~/.aifabrix/urls.local.yaml` so declarative
- * `url://` expansion (e.g. cross-references between miso-controller, dataplane, keycloak) sees every
- * app's port and pattern before Keycloak or Miso resolve their `.env` files.
+ * Merge builder/packages `application.yaml` into `~/.aifabrix/urls.local.yaml`.
+ * Same scan as the end of {@link prepareUrlsLocalRegistryForUpPlatform}; call after platform app
+ * templates exist (e.g. `up-miso`, `up-dataplane`) so declarative `url://` and tooling see ports/patterns.
+ */
+function refreshUrlsLocalRegistryForCurrentProject() {
+  try {
+    refreshUrlsLocalRegistryFromBuilder(pathsUtil.getProjectRoot());
+  } catch (error) {
+    logger.warn(chalk.yellow(`⚠  Could not refresh URLs registry: ${error.message}`));
+  }
+}
+
+/**
+ * For `aifabrix up-platform` only: materialize all three platform apps from templates if missing
+ * (paths follow cwd / material `builder/` only — no `AIFABRIX_BUILDER_DIR` override), then refresh
+ * `~/.aifabrix/urls.local.yaml` so declarative `url://` expansion (e.g. cross-references between
+ * miso-controller, dataplane, keycloak) sees every app's port and pattern before Keycloak or Miso
+ * resolve their `.env` files.
  *
  * @returns {Promise<void>}
  */
 async function prepareUrlsLocalRegistryForUpPlatform() {
-  const builderDir = await config.getAifabrixBuilderDir();
-  if (builderDir) {
-    process.env.AIFABRIX_BUILDER_DIR = path.resolve(builderDir);
-  }
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
   await ensureAppFromTemplate('dataplane');
-  refreshUrlsLocalRegistryFromBuilder(pathsUtil.getProjectRoot());
+  refreshUrlsLocalRegistryForCurrentProject();
 }
 
 module.exports = {
@@ -320,5 +353,6 @@ module.exports = {
   patchEnvOutputPathForDeployOnly,
   validateEnvOutputPathFolderOrNull,
   getEnvOutputPathFolder,
-  prepareUrlsLocalRegistryForUpPlatform
+  prepareUrlsLocalRegistryForUpPlatform,
+  refreshUrlsLocalRegistryForCurrentProject
 };

package/lib/commands/up-dataplane.js

@@ -12,7 +12,6 @@ const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-test
  * @version 2.0.0
  */
 
-const path = require('path');
 const readline = require('readline');
 const chalk = require('chalk');
 const pathsUtil = require('../utils/paths');
@@ -30,7 +29,7 @@ const { checkHealthEndpoint } = require('../utils/health-check');
 const { validateControllerUrl } = require('../utils/auth-config-validator');
 const app = require('../app');
 const { assertDevInfraUp } = require('./dev-infra-gate');
-const { ensureAppFromTemplate, validateEnvOutputPathFolderOrNull } = require('./up-common');
+const { ensureAppFromTemplate, validateEnvOutputPathFolderOrNull, refreshUrlsLocalRegistryForCurrentProject } = require('./up-common');
 
 const CONTROLLER_HEALTH_PATH = '/health';
 
@@ -168,14 +167,17 @@ function buildDataplaneImageRef(options = {}) {
   }
 }
 
-/**
- * Sets `AIFABRIX_BUILDER_DIR` when configured (shared by deploy/run paths).
- * @returns {Promise<void>}
- */
-async function applyAifabrixBuilderDirEnv() {
-  const builderDir = await config.getAifabrixBuilderDir();
-  if (builderDir) {
-    process.env.AIFABRIX_BUILDER_DIR = path.resolve(builderDir);
+function emitDataplaneManifestLineFromBuilder() {
+  const { emitSystemBuilderAppManifestLineIfTTY } = require('../utils/manifest-source-emit');
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
+}
+
+function assertDevEnvironmentForDataplane(cfg) {
+  const environment = (cfg && cfg.environment) ? cfg.environment : 'dev';
+  if (environment !== 'dev') {
+    throw new Error(
+      'Dataplane is only supported in dev environment. Set with: aifabrix auth --set-environment dev.'
+    );
   }
 }
 
@@ -195,7 +197,6 @@ async function applyAifabrixBuilderDirEnv() {
  * @throws {Error} If infra not up, controller unavailable, not logged in, environment not dev, or any step fails
  */
 async function handleUpDataplane(options = {}) {
-  await applyAifabrixBuilderDirEnv();
   logger.log(chalk.blue('Starting up-dataplane (register/rotate, deploy, then run dataplane locally)...\n'));
 
   if (options.skipInfraCheck !== true) {
@@ -207,18 +208,19 @@ async function handleUpDataplane(options = {}) {
   const authConfig = await checkAuthentication(controllerUrl, environmentKey, { throwOnFailure: true });
 
   const cfg = await config.getConfig();
-  const environment = (cfg && cfg.environment) ? cfg.environment : 'dev';
-  if (environment !== 'dev') {
-    throw new Error(
-      'Dataplane is only supported in dev environment. Set with: aifabrix auth --set-environment dev.'
-    );
-  }
+  assertDevEnvironmentForDataplane(cfg);
   logger.log(formatSuccessLine('Logged in and environment is dev'));
 
   await ensureAppFromTemplate('dataplane');
   // If envOutputPath target folder does not exist, set envOutputPath to null
   validateEnvOutputPathFolderOrNull('dataplane');
 
+  refreshUrlsLocalRegistryForCurrentProject();
+
+  if (options.platformInstall !== true) {
+    emitDataplaneManifestLineFromBuilder();
+  }
+
   await registerOrRotateDataplane(options, controllerUrl, environmentKey, authConfig);
 
   await deployDataplaneToController(options);
@@ -226,7 +228,8 @@ async function handleUpDataplane(options = {}) {
   await app.runApp('dataplane', {
     skipEnvOutputPath: true,
     registry: options.registry || undefined,
-    base: options.base !== false
+    base: options.base !== false,
+    skipManifestMetadataLine: true
   });
 
   logger.log(formatSuccessParagraph('up-dataplane complete. Dataplane is registered, deployed in dev, and running locally.'));

package/lib/commands/up-miso.js

@@ -10,13 +10,16 @@ const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
  * @version 2.0.0
  */
 
-const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const config = require('../core/config');
 const app = require('../app');
 const { assertDevInfraUp } = require('./dev-infra-gate');
-const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly, validateEnvOutputPathFolderOrNull } = require('./up-common');
+const {
+  ensureAppFromTemplate,
+  patchEnvOutputPathForDeployOnly,
+  validateEnvOutputPathFolderOrNull,
+  refreshUrlsLocalRegistryForCurrentProject
+} = require('./up-common');
 
 /**
  * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string }
@@ -51,7 +54,8 @@ async function runMisoApps(options) {
     registryMode: options.registryMode,
     skipEnvOutputPath: true,
     skipInfraCheck: true,
-    base: useBaseImage
+    base: useBaseImage,
+    skipManifestMetadataLine: true
   };
   const keycloakRunOpts = { ...common };
   if (imageMap.keycloak) {
@@ -61,9 +65,12 @@ async function runMisoApps(options) {
   if (imageMap['miso-controller']) {
     misoRunOpts.image = imageMap['miso-controller'];
   }
+  const { emitSystemBuilderAppManifestLineIfTTY } = require('../utils/manifest-source-emit');
   logger.log(chalk.blue('Starting keycloak...'));
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
   await app.runApp('keycloak', keycloakRunOpts);
   logger.log(chalk.blue('Starting miso-controller...'));
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
   await app.runApp('miso-controller', misoRunOpts);
 }
 
@@ -80,10 +87,6 @@ async function runMisoApps(options) {
  * @throws {Error} If infra not up or any step fails
  */
 async function handleUpMiso(options = {}) {
-  const builderDir = await config.getAifabrixBuilderDir();
-  if (builderDir) {
-    process.env.AIFABRIX_BUILDER_DIR = path.resolve(builderDir);
-  }
   logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
   await assertDevInfraUp();
   await ensureAppFromTemplate('keycloak');
@@ -94,6 +97,7 @@ async function handleUpMiso(options = {}) {
   // Deploy-only: do not copy .env to repo paths; patch variables so envOutputPath is null
   patchEnvOutputPathForDeployOnly('keycloak');
   patchEnvOutputPathForDeployOnly('miso-controller');
+  refreshUrlsLocalRegistryForCurrentProject();
   await runMisoApps(options);
   logger.log(formatSuccessParagraph('up-miso complete. Keycloak and miso-controller are running.') +
     chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));

package/lib/commands/upload.js

@@ -25,6 +25,8 @@ const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../uti
 const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
 const { getIntegrationPath } = require('../utils/paths');
 const { pushCredentialSecrets } = require('../utils/credential-secrets-env');
+const { runWithCredentialPushSpinner } = require('../utils/credential-push-ui');
+const { runWithUploadPipelineSpinner } = require('../utils/upload-pipeline-ui');
 const {
   buildResolvedEnvMapForIntegration,
   resolveConfigurationValues,
@@ -49,6 +51,7 @@ const {
 const { maybeSyncSystemCertificationFromDataplane } = require('../certification/sync-system-certification');
 const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
 const { maybeSyncOpenApiFilesForMcp } = require('./repair-openapi-sync');
+const { assertDataplaneCliVersionCompatible } = require('../utils/dataplane-cli-version-gate');
 
 /**
  * Validates system-key format (same as download).
@@ -170,13 +173,17 @@ async function resolvePayloadConfiguration(systemKey, payload) {
  * @param {string} systemKey - System key
  * @param {Object} payload - Upload payload
  */
-async function pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload) {
+async function pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload, uiOpts = {}) {
   const envFilePath = path.join(getIntegrationPath(systemKey), '.env');
-  const pushResult = await pushCredentialSecrets(dataplaneUrl, authConfig, {
-    envFilePath,
-    appName: systemKey,
-    payload
-  });
+  const pushResult = await runWithCredentialPushSpinner(
+    () =>
+      pushCredentialSecrets(dataplaneUrl, authConfig, {
+        envFilePath,
+        appName: systemKey,
+        payload
+      }),
+    { systemKey, json: uiOpts.json === true }
+  );
   if (pushResult.pushed > 0) {
     const keyList = pushResult.keys?.length ? ` (${pushResult.keys.join(', ')})` : '';
     logger.log(
@@ -279,8 +286,10 @@ async function buildValidatedUploadManifestPayload(systemKey, _opts = {}) {
 }
 
 /**
- * Upload local `integration/<systemKey>/openapi/*.json` specs when present so pipeline can resolve
- * each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ * Upload local `integration/<systemKey>/openapi/*.json` specs when present so dataplane can store
+ * vendor OpenAPI keyed by each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ * Call this **after** a successful pipeline publish: list/upload endpoints require the external system row.
+ * First publish still succeeds because pipeline materializes internal specs from `openapi.operations` when needed.
  *
  * @param {string} systemKey
  * @param {Object} manifest
@@ -362,8 +371,13 @@ async function handlePublicationAndFollowups(ctx) {
  * @param {Object} payload
  */
 async function runUploadPublishAndSummary(systemKey, options, manifest, payload) {
-  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey);
+  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey, {
+    silent: options.silentResolve === true
+  });
   requireBearerForDataplanePipeline(authConfig);
+  const controllerUrl = await resolveControllerUrl();
+  // Plan 142.0: gate dataplane API entrypoints by the dataplane-advertised minimum Builder CLI version.
+  await assertDataplaneCliVersionCompatible(dataplaneUrl, { controllerUrl });
   logger.log('');
   logger.log(sectionTitle('Target'));
   logger.log(SEP);
@@ -373,10 +387,18 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
   if (options.verbose) {
     await maybeRunVerboseServerValidation(dataplaneUrl, authConfig, payload);
   }
-  await pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload);
-  await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+  await pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload, {
+    json: options.json === true
+  });
 
-  const rawRes = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+  const rawRes = await runWithUploadPipelineSpinner(
+    async() => {
+      const res = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+      await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+      return res;
+    },
+    { systemKey, json: options.json === true }
+  );
   await handlePublicationAndFollowups({
     systemKey,
     options,
@@ -387,6 +409,7 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
     authConfig,
     rawRes
   });
+  return { dataplaneUrl, authConfig, environment };
 }
 
 /**
@@ -398,7 +421,7 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
  * @param {boolean} [options.probe] - POST validation/run after publish
  * @param {number} [options.probeTimeout] - Probe timeout ms (default 120000)
  * @param {boolean} [options.minimal] - Short summary only
- * @returns {Promise<void>}
+ * @returns {Promise<{ dataplaneUrl: string, authConfig: Object, environment: string }|void>}
  * @throws {Error} If validation or API calls fail
  */
 async function uploadExternalSystem(systemKey, options = {}) {
@@ -415,9 +438,9 @@ async function uploadExternalSystem(systemKey, options = {}) {
     logger.log(
       chalk.gray(`  System: ${manifest.key}, version: ${payload.version}, datasources: ${payload.dataSources.length}`)
     );
-    return;
+    return undefined;
   }
-  await runUploadPublishAndSummary(systemKey, options, manifest, payload);
+  return runUploadPublishAndSummary(systemKey, options, manifest, payload);
 }
 
 module.exports = {

package/lib/commands/wizard-core.js

@@ -525,6 +525,9 @@ async function setupDataplaneAndAuth(options, appName) {
       '   aifabrix login'
     );
   }
+  // Plan 142.0: gate wizard dataplane calls by the dataplane-advertised minimum Builder CLI version.
+  const { assertDataplaneCliVersionCompatible } = require('../utils/dataplane-cli-version-gate');
+  await assertDataplaneCliVersionCompatible(dataplaneUrl, { controllerUrl });
   return { dataplaneUrl, authConfig };
 }
 

package/lib/core/audit-logger.js

@@ -15,6 +15,7 @@ const fs = require('fs').promises;
 const path = require('path');
 const os = require('os');
 const paths = require('../utils/paths');
+const { maskSensitiveData } = require('../utils/log-redaction');
 
 // Audit log file path (beside config.yaml / CLI system dir for compliance)
 let auditLogPath = null;
@@ -51,40 +52,6 @@ async function getAuditLogPath() {
   return auditLogPath;
 }
 
-/**
- * Masks sensitive data in strings
- * Prevents secrets, keys, and passwords from appearing in logs
- *
- * @param {string} value - Value to mask
- * @returns {string} Masked value
- */
-function maskSensitiveData(value) {
-  if (!value || typeof value !== 'string') {
-    return value;
-  }
-
-  // Mask patterns: passwords, secrets, keys, tokens
-  const sensitivePatterns = [
-    { pattern: /password[=:]\s*([^\s]+)/gi, replacement: 'password=***' },
-    { pattern: /secret[=:]\s*([^\s]+)/gi, replacement: 'secret=***' },
-    { pattern: /key[=:]\s*([^\s]+)/gi, replacement: 'key=***' },
-    { pattern: /token[=:]\s*([^\s]+)/gi, replacement: 'token=***' },
-    { pattern: /api[_-]?key[=:]\s*([^\s]+)/gi, replacement: 'api_key=***' }
-  ];
-
-  let masked = value;
-  for (const { pattern, replacement } of sensitivePatterns) {
-    masked = masked.replace(pattern, replacement);
-  }
-
-  // If value looks like a hash/key (long hex string), mask it
-  if (/^[a-f0-9]{32,}$/i.test(masked.trim())) {
-    return '***';
-  }
-
-  return masked;
-}
-
 /**
  * Creates an audit log entry with ISO 27001 compliance
  *

package/lib/core/config-admin-email.js

@@ -0,0 +1,56 @@
+/**
+ * Admin email field in `config.yaml` (Keycloak / pgAdmin), written by `aifabrix setup`.
+ *
+ * @fileoverview config.yaml adminEmail helpers (keeps config.js under max-lines)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {unknown} email
+ * @returns {string} Trimmed valid email
+ * @throws {Error} When empty or not a plausible email
+ */
+function validateAdminEmailForConfig(email) {
+  const value = String(email ?? '').trim();
+  if (!value) {
+    throw new Error('Admin email must be a non-empty string');
+  }
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+    throw new Error('Admin email must be a valid email address');
+  }
+  return value;
+}
+
+/**
+ * @param {() => Promise<Object>} getConfig
+ * @returns {Promise<string>}
+ */
+async function getAdminEmailFromConfig(getConfig) {
+  const cfg = await getConfig();
+  if (cfg && typeof cfg.adminEmail === 'string' && cfg.adminEmail.trim()) {
+    return cfg.adminEmail.trim();
+  }
+  return '';
+}
+
+/**
+ * @param {() => Promise<Object>} getConfig
+ * @param {(data: Object) => Promise<void>} saveConfig
+ * @param {string} email
+ * @returns {Promise<void>}
+ */
+async function setAdminEmailInConfig(getConfig, saveConfig, email) {
+  const trimmed = validateAdminEmailForConfig(email);
+  const cfg = await getConfig();
+  cfg.adminEmail = trimmed;
+  await saveConfig(cfg);
+}
+
+module.exports = {
+  validateAdminEmailForConfig,
+  getAdminEmailFromConfig,
+  setAdminEmailInConfig
+};

package/lib/core/config-device-dataplane.js

@@ -0,0 +1,185 @@
+/**
+ * Persist dataplane version metadata under `device.<controllerUrl>` in
+ * `~/.aifabrix/config.yaml` for the Builder CLI compatibility gate (plan 142.0).
+ *
+ * Only public dataplane fields are written here. Token / refresh-token entries
+ * on the same device entry are preserved untouched.
+ *
+ * Schema additions (kebab-case, matching `developer-id` style):
+ *   - `dataplane-version`         ← health `version`
+ *   - `dataplane-min-cli-version` ← health `minBuilderCliVersion` (omitted when not enforced)
+ *   - `dataplane-checked-at`      ← ISO timestamp for cache TTL (default 5 min)
+ *
+ * @fileoverview Cache dataplane health under existing `device.<controllerUrl>` entry
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { getConfig, saveConfig, normalizeControllerUrl } = require('./config');
+
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Resolve the device entry key matching `controllerUrl`, taking URL
+ * normalization into account so callers do not need to worry about trailing
+ * slashes or scheme differences.
+ * @private
+ * @param {Object} deviceMap - `config.device` map
+ * @param {string} normalizedUrl
+ * @returns {string|null} The key under `config.device` or null when missing
+ */
+function findDeviceKey(deviceMap, normalizedUrl) {
+  if (!deviceMap || typeof deviceMap !== 'object') return null;
+  if (deviceMap[normalizedUrl]) return normalizedUrl;
+  for (const storedUrl of Object.keys(deviceMap)) {
+    if (normalizeControllerUrl(storedUrl) === normalizedUrl) {
+      return storedUrl;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the dataplane cache currently persisted under `device.<controllerUrl>`.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<{
+ *   version?: string,
+ *   minBuilderCliVersion?: string,
+ *   checkedAt?: string
+ * }|null>} The cached snapshot, or null when no entry exists
+ * @throws {Error} If controllerUrl is missing
+ */
+async function getDeviceDataplaneVersions(controllerUrl) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  const config = await getConfig();
+  const normalizedUrl = normalizeControllerUrl(controllerUrl);
+  const key = findDeviceKey(config.device, normalizedUrl);
+  if (!key) return null;
+  const entry = config.device[key];
+  if (!entry || typeof entry !== 'object') return null;
+  const snapshot = {};
+  if (typeof entry['dataplane-version'] === 'string') {
+    snapshot.version = entry['dataplane-version'];
+  }
+  if (typeof entry['dataplane-min-cli-version'] === 'string') {
+    snapshot.minBuilderCliVersion = entry['dataplane-min-cli-version'];
+  }
+  if (typeof entry['dataplane-checked-at'] === 'string') {
+    snapshot.checkedAt = entry['dataplane-checked-at'];
+  }
+  if (Object.keys(snapshot).length === 0) return null;
+  return snapshot;
+}
+
+/**
+ * Apply the `dataplane-version` field to a device entry in-place.
+ * @private
+ * @param {Object} entry
+ * @param {string|null|undefined} version
+ */
+function applyDataplaneVersionField(entry, version) {
+  if (typeof version === 'string' && version.trim()) {
+    entry['dataplane-version'] = version.trim();
+  } else if (version === null || version === '') {
+    delete entry['dataplane-version'];
+  }
+}
+
+/**
+ * Apply the `dataplane-min-cli-version` field to a device entry in-place.
+ * Treat absent / empty as "no enforcement" → clear the cached floor so an
+ * older value never lingers after the operator removes the env variable.
+ * @private
+ * @param {Object} entry
+ * @param {string|null|undefined} minCli
+ */
+function applyMinCliField(entry, minCli) {
+  if (typeof minCli === 'string' && minCli.trim()) {
+    entry['dataplane-min-cli-version'] = minCli.trim();
+    return;
+  }
+  if (minCli === null || minCli === '' || minCli === undefined) {
+    delete entry['dataplane-min-cli-version'];
+  }
+}
+
+/**
+ * Compute the timestamp persisted as `dataplane-checked-at`.
+ * @private
+ * @param {string|undefined} checkedAt
+ * @returns {string} ISO timestamp
+ */
+function resolveCheckedAt(checkedAt) {
+  if (typeof checkedAt === 'string' && checkedAt.trim()) {
+    return checkedAt.trim();
+  }
+  return new Date().toISOString();
+}
+
+/**
+ * Persist dataplane version metadata under the device entry for `controllerUrl`.
+ *
+ * Token / refresh-token entries are preserved; only the `dataplane-*` keys are
+ * written. When `versions.minBuilderCliVersion` is empty/undefined the cache
+ * key is removed (dataplane does not enforce a minimum).
+ *
+ * @async
+ * @param {string} controllerUrl - Controller URL (will be normalized)
+ * @param {{
+ *   version?: string,
+ *   minBuilderCliVersion?: string|null,
+ *   checkedAt?: string
+ * }} versions
+ * @returns {Promise<void>}
+ * @throws {Error} If controllerUrl is missing
+ */
+async function updateDeviceDataplaneVersions(controllerUrl, versions = {}) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  const config = await getConfig();
+  if (!config.device || typeof config.device !== 'object') {
+    config.device = {};
+  }
+  const normalizedUrl = normalizeControllerUrl(controllerUrl);
+  const key = findDeviceKey(config.device, normalizedUrl) || normalizedUrl;
+  if (!config.device[key] || typeof config.device[key] !== 'object') {
+    config.device[key] = {};
+  }
+  const entry = config.device[key];
+
+  applyDataplaneVersionField(entry, versions.version);
+  applyMinCliField(entry, versions.minBuilderCliVersion);
+  entry['dataplane-checked-at'] = resolveCheckedAt(versions.checkedAt);
+
+  await saveConfig(config);
+}
+
+/**
+ * True when the cached snapshot is older than the configured TTL (or missing).
+ *
+ * @param {{checkedAt?: string}|null} snapshot
+ * @param {number} [ttlMs] - TTL in milliseconds (defaults to 5 minutes)
+ * @param {Date|number} [now] - Override "now" for tests
+ * @returns {boolean}
+ */
+function isCacheStale(snapshot, ttlMs = DEFAULT_CACHE_TTL_MS, now = Date.now()) {
+  if (!snapshot || !snapshot.checkedAt) return true;
+  const checkedAtMs = Date.parse(snapshot.checkedAt);
+  if (Number.isNaN(checkedAtMs)) return true;
+  const reference = typeof now === 'number' ? now : now.getTime();
+  return reference - checkedAtMs >= ttlMs;
+}
+
+module.exports = {
+  getDeviceDataplaneVersions,
+  updateDeviceDataplaneVersions,
+  isCacheStale,
+  DEFAULT_CACHE_TTL_MS
+};