@aifabrix/builder 2.45.0 → 2.46.0

package/lib/utils/credential-secrets-env.js

@@ -280,21 +280,146 @@ function storedCountFromResponse(res, fallback) {
  * @param {Array<{ key: string, value: string }>} items - Items to send
  * @returns {Promise<{ pushed: number, warning?: string }>}
  */
+/**
+ * For bearerToken auth, credential template resolves security.token only.
+ * Legacy .env keys KV_*_APIKEY with a plain token wrongly map to kv://.../apiKey.
+ * Prefer token path; drop duplicate apiKey when both would be pushed.
+ *
+ * @param {Map<string, string>} itemsByKey
+ * @param {string} [systemKey]
+ * @param {Object} [authConfig]
+ */
+function reconcileBearerTokenSecretPaths(itemsByKey, systemKey, authConfig) {
+  const method = (
+    authConfig?.method ||
+    authConfig?.type ||
+    ''
+  )
+    .toString()
+    .toLowerCase()
+    .replace(/_/g, '');
+  if (method !== 'bearertoken' || !systemKey) return;
+  const tokenPath = `kv://${systemKey}/token`;
+  const apiKeyPath = `kv://${systemKey}/apiKey`;
+  if (!itemsByKey.has(apiKeyPath)) return;
+  if (!itemsByKey.has(tokenPath)) {
+    itemsByKey.set(tokenPath, itemsByKey.get(apiKeyPath));
+  }
+  itemsByKey.delete(apiKeyPath);
+}
+
+/**
+ * Optional dev/lab dataplane API key (Bearer bypass) for credential secret push only.
+ * Does not alter pipeline publish auth when AIFABRIX_DEPLOYMENT_AUTH=client-credentials.
+ * @returns {string|null}
+ */
+function resolveLabDataplaneApiKey() {
+  const candidates = [
+    process.env.AIFABRIX_DATAPLANE_API_KEY,
+    process.env.DATAPLANE_API_KEY,
+    process.env.API_KEY
+  ];
+  for (const raw of candidates) {
+    const trimmed = typeof raw === 'string' ? raw.trim() : '';
+    if (trimmed) return trimmed;
+  }
+  return null;
+}
+
+/**
+ * @param {string} token
+ * @returns {{ type: string, token: string }}
+ */
+function apiKeyAuthConfig(token) {
+  return { type: 'bearer', token };
+}
+
+const PERMISSION_DENIED_WARNING =
+  'Could not push credential secrets (permission denied or unauthenticated). Ensure dataplane role has credential:create if you use KV_* in .env, or set AIFABRIX_DATAPLANE_API_KEY for local lab bypass.';
+
+/**
+ * @param {Object} res
+ * @returns {boolean}
+ */
+function isStoreResponseFailed(res) {
+  return Boolean(res && (res.success === false || res.data?.success === false));
+}
+
+/**
+ * @param {Object} res
+ * @returns {number|undefined}
+ */
+function storeResponseStatus(res) {
+  return res?.status ?? res?.statusCode;
+}
+
+/**
+ * @param {Object} res
+ * @returns {{ pushed: number, warning: string }}
+ */
+function storeErrorWarning(res) {
+  const errMsg =
+    res.formattedError ||
+    res.data?.formattedError ||
+    res.error ||
+    res.data?.error ||
+    'Failed to push credential secrets to dataplane.';
+  return { pushed: 0, warning: errMsg };
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Array<{ key: string, value: string }>} items
+ * @returns {Promise<{ pushed: number }|null>}
+ */
+async function tryLabApiKeyRetry(dataplaneUrl, authConfig, items) {
+  const labKey = resolveLabDataplaneApiKey();
+  if (!labKey || authConfig?.token === labKey) {
+    return null;
+  }
+  const retry = await storeCredentialSecrets(
+    dataplaneUrl,
+    apiKeyAuthConfig(labKey),
+    items
+  );
+  if (isStoreResponseFailed(retry)) {
+    return null;
+  }
+  return { pushed: storedCountFromResponse(retry, items.length) };
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Array<{ key: string, value: string }>} items
+ * @param {Object} res
+ * @returns {Promise<{ pushed: number, warning?: string }>}
+ */
+async function handleFailedStoreResponse(dataplaneUrl, authConfig, items, res) {
+  const status = storeResponseStatus(res);
+  if (status === 403 || status === 401) {
+    const retryResult = await tryLabApiKeyRetry(dataplaneUrl, authConfig, items);
+    if (retryResult) {
+      return retryResult;
+    }
+    return { pushed: 0, warning: PERMISSION_DENIED_WARNING };
+  }
+  return storeErrorWarning(res);
+}
+
 async function sendCredentialSecrets(dataplaneUrl, authConfig, items) {
   try {
     const res = await storeCredentialSecrets(dataplaneUrl, authConfig, items);
-    const failed = res && (res.success === false || res.data?.success === false);
-    if (failed) {
-      const status = res.status ?? res.statusCode;
-      if (status === 403 || status === 401) {
-        return { pushed: 0, warning: 'Could not push credential secrets (permission denied or unauthenticated). Ensure dataplane role has credential:create if you use KV_* in .env.' };
-      }
-      const errMsg = res.formattedError || res.data?.formattedError || res.error || res.data?.error || 'Failed to push credential secrets to dataplane.';
-      return { pushed: 0, warning: errMsg };
+    if (isStoreResponseFailed(res)) {
+      return handleFailedStoreResponse(dataplaneUrl, authConfig, items, res);
     }
     return { pushed: storedCountFromResponse(res, items.length) };
   } catch (err) {
-    return { pushed: 0, warning: err.message || 'Failed to push credential secrets to dataplane.' };
+    return {
+      pushed: 0,
+      warning: err.message || 'Failed to push credential secrets to dataplane.'
+    };
   }
 }
 
@@ -322,6 +447,7 @@ async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
   const itemsByKey = new Map();
   buildItemsFromEnv(envFilePath, secrets, itemsByKey, appName);
   buildItemsFromPayload(payload, secrets, itemsByKey);
+  reconcileBearerTokenSecretPaths(itemsByKey, appName, authConfig);
 
   const items = Array.from(itemsByKey.entries())
     .filter(([k]) => isValidKvPath(k))
@@ -362,6 +488,8 @@ module.exports = {
   collectKvEnvVarsAsSecretItems,
   collectKvRefsFromPayload,
   pushCredentialSecrets,
+  reconcileBearerTokenSecretPaths,
+  resolveLabDataplaneApiKey,
   kvEnvKeyToPath,
   getKvPathSegmentForSecurityKey,
   systemKeyToKvPrefix,

package/lib/utils/dataplane-cli-version-gate.js

@@ -0,0 +1,202 @@
+/**
+ * Builder CLI ↔ dataplane version gate (plan 142.0).
+ *
+ * Resolves the dataplane-advertised `minBuilderCliVersion` (from cache or a
+ * fresh health probe) and compares it against the installed Builder CLI
+ * version. Used at the top of dataplane API entrypoints so an outdated CLI
+ * cannot mutate dataplane state silently.
+ *
+ * Local-only commands (validate, run, up-infra, file generation) do **not**
+ * call into this module; the gate is intentionally per-call, not global.
+ *
+ * @fileoverview Compatibility gate for dataplane API entrypoints
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+const {
+  getDeviceDataplaneVersions,
+  updateDeviceDataplaneVersions,
+  isCacheStale
+} = require('../core/config-device-dataplane');
+const { compareSemver, isValidSemver } = require('./semver-compare');
+const { formatCliVersionGateError } = require('./dataplane-cli-version-help');
+
+/**
+ * Get the installed Builder CLI version from `package.json`.
+ * Centralized so tests can stub it via Jest module mocks.
+ * @returns {string}
+ */
+function getInstalledCliVersion() {
+  return require('../../package.json').version;
+}
+
+/**
+ * Internal sentinel error code so callers can distinguish gate failures from
+ * generic dataplane errors when needed.
+ * @type {string}
+ */
+const ERROR_CODE = 'CLI_VERSION_INCOMPATIBLE';
+
+/**
+ * True when `err` was thrown by this gate.
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isCliVersionIncompatibleError(err) {
+  return Boolean(err && err.code === ERROR_CODE);
+}
+
+/**
+ * Resolve the dataplane minimum Builder CLI version, preferring cached value
+ * when fresh; otherwise probe health and persist a new snapshot under
+ * `device.<controllerUrl>`.
+ *
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} dataplaneUrl
+ * @param {{ forceRefresh?: boolean }} [options]
+ * @returns {Promise<{ minBuilderCliVersion?: string, dataplaneVersion?: string }>}
+ */
+async function resolveMinBuilderCliVersion(controllerUrl, dataplaneUrl, options = {}) {
+  const forceRefresh = Boolean(options.forceRefresh);
+  if (!forceRefresh) {
+    const cached = await safeReadCache(controllerUrl);
+    if (cached && !isCacheStale(cached)) {
+      return {
+        minBuilderCliVersion: cached.minBuilderCliVersion,
+        dataplaneVersion: cached.version
+      };
+    }
+  }
+
+  const snapshot = await safeFetch(dataplaneUrl);
+  if (!snapshot) {
+    // Cannot reach dataplane → do not gate (offline / pre-rollout). Reuse
+    // any cached value we may have.
+    const cached = await safeReadCache(controllerUrl);
+    return {
+      minBuilderCliVersion: cached ? cached.minBuilderCliVersion : undefined,
+      dataplaneVersion: cached ? cached.version : undefined
+    };
+  }
+
+  await safeWriteCache(controllerUrl, {
+    version: snapshot.version,
+    minBuilderCliVersion: snapshot.minBuilderCliVersion || null
+  });
+  return {
+    minBuilderCliVersion: snapshot.minBuilderCliVersion,
+    dataplaneVersion: snapshot.version
+  };
+}
+
+/**
+ * Read cached versions without throwing — gate failures should not mask real
+ * dataplane errors caused by config corruption.
+ * @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;
+  }
+}
+
+/**
+ * Fetch health swallowing transport errors so callers can decide what to do
+ * when the dataplane is unreachable.
+ * @private
+ * @async
+ * @param {string} dataplaneUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeFetch(dataplaneUrl) {
+  try {
+    return await fetchDataplaneGeneralHealth(dataplaneUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Write the cache without throwing — best-effort persistence.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} versions
+ * @returns {Promise<void>}
+ */
+async function safeWriteCache(controllerUrl, versions) {
+  if (!controllerUrl) return;
+  try {
+    await updateDeviceDataplaneVersions(controllerUrl, versions);
+  } catch (_error) {
+    // intentionally swallowed — cache write failure must not block the call
+  }
+}
+
+/**
+ * Throw when the installed CLI is older than the dataplane minimum.
+ *
+ * No-op when:
+ *   - `dataplaneUrl` is empty (no dataplane in play)
+ *   - Dataplane omits `minBuilderCliVersion` (no enforcement)
+ *   - Dataplane is unreachable and no cached minimum is known
+ *   - Cached/advertised minimum is not valid semver (warn-only contract per plan)
+ *
+ * @async
+ * @param {string} dataplaneUrl - Dataplane base URL (e.g. `http://localhost:3201`)
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl] - Controller URL for cache lookup/write
+ * @param {boolean} [options.forceRefresh] - Skip cache and probe health now
+ * @returns {Promise<void>}
+ * @throws {Error & { code: 'CLI_VERSION_INCOMPATIBLE', required: string, installed: string, formatted: string }}
+ */
+async function assertDataplaneCliVersionCompatible(dataplaneUrl, options = {}) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    return;
+  }
+  const { minBuilderCliVersion } = await resolveMinBuilderCliVersion(
+    options.controllerUrl || null,
+    dataplaneUrl,
+    { forceRefresh: Boolean(options.forceRefresh) }
+  );
+  if (!minBuilderCliVersion) return;
+  if (!isValidSemver(minBuilderCliVersion)) return;
+
+  // Go through module.exports so tests can stub `getInstalledCliVersion`.
+  const installed = module.exports.getInstalledCliVersion();
+  if (!isValidSemver(installed)) return;
+
+  if (compareSemver(installed, minBuilderCliVersion) >= 0) {
+    return;
+  }
+
+  const formatted = formatCliVersionGateError(minBuilderCliVersion, installed);
+  const error = new Error(
+    `Builder CLI ${installed} is below the dataplane minimum (${minBuilderCliVersion}). ` +
+    'Upgrade with: npm install -g @aifabrix/builder@latest'
+  );
+  error.code = ERROR_CODE;
+  error.required = minBuilderCliVersion;
+  error.installed = installed;
+  error.formatted = formatted;
+  throw error;
+}
+
+module.exports = {
+  assertDataplaneCliVersionCompatible,
+  isCliVersionIncompatibleError,
+  getInstalledCliVersion,
+  ERROR_CODE
+};

package/lib/utils/dataplane-cli-version-help.js

@@ -0,0 +1,74 @@
+/**
+ * Shared "Next actions" + blocking error formatter for the Builder CLI ↔
+ * dataplane version gate (plan 142.0). Used by `auth status` display and by
+ * the gate thrown from dataplane API entrypoints so users see the same bullets
+ * wherever the incompatibility surfaces.
+ *
+ * @fileoverview Shared CLI version-gate UX helpers (next actions + blocking)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const {
+  formatBlockingError,
+  formatNextActions
+} = require('./cli-test-layout-chalk');
+
+/**
+ * Build the canonical Next actions bullets for a CLI ↔ dataplane mismatch.
+ *
+ * @param {string} required - Minimum Builder CLI semver advertised by dataplane
+ * @param {string} installed - Current Builder CLI semver (from package.json)
+ * @returns {string[]} Bullet lines (no prefix)
+ */
+function buildCliVersionUpgradeNextActions(required, installed) {
+  const req = (required || '').trim() || 'the dataplane minimum';
+  const inst = (installed || '').trim() || 'this CLI';
+  return [
+    `Upgrade Builder CLI: npm install -g @aifabrix/builder@${req} (or @latest)`,
+    'Confirm after upgrade: aifabrix auth status',
+    'CI / scripts: aifabrix auth status --validate (exit 3 until upgraded)',
+    `Local work (validate, run, up-infra) still works on ${inst}`
+  ];
+}
+
+/**
+ * Build the blocking line shown before the Next actions block when the CLI is
+ * older than the dataplane minimum.
+ *
+ * @param {string} required - Required minimum semver
+ * @param {string} installed - Currently installed semver
+ * @returns {string}
+ */
+function buildCliVersionBlockingLine(required, installed) {
+  const req = (required || '').trim() || '(unknown)';
+  const inst = (installed || '').trim() || '(unknown)';
+  return formatBlockingError(
+    `Builder CLI ${inst} is below the dataplane minimum (${req}). Upgrade before running dataplane commands.`
+  );
+}
+
+/**
+ * Format the full version-gate error block (blocking line + Next actions).
+ * Suitable for `handleCommandError` output and the `auth status` incompatible
+ * branch.
+ *
+ * @param {string} required - Required minimum semver
+ * @param {string} installed - Currently installed semver
+ * @returns {string} Multi-line, chalk-colored block
+ */
+function formatCliVersionGateError(required, installed) {
+  return [
+    buildCliVersionBlockingLine(required, installed),
+    '',
+    formatNextActions(buildCliVersionUpgradeNextActions(required, installed))
+  ].join('\n');
+}
+
+module.exports = {
+  buildCliVersionUpgradeNextActions,
+  buildCliVersionBlockingLine,
+  formatCliVersionGateError
+};

package/lib/utils/dataplane-resolver.js

@@ -8,7 +8,127 @@
  * @version 2.0.0
  */
 
+const fs = require('fs');
+const path = require('path');
+
+const config = require('../core/config');
 const { discoverDataplaneUrl } = require('../commands/wizard-dataplane');
+const pathsUtil = require('./paths');
+const { loadConfigFile } = require('./config-format');
+
+/** Matches `templates/applications/dataplane/application.yaml` and `calculateComposePort`. */
+const DEFAULT_DATAPLANE_MANIFEST_PORT = 3001;
+
+/**
+ * @param {string} url
+ * @returns {number|null}
+ */
+function localhostPortFromUrl(url) {
+  if (!url || typeof url !== 'string') return null;
+  const normalized = url.replace(/127\.0\.0\.1/g, 'localhost');
+  const match = normalized.match(/localhost:(\d+)/);
+  if (!match) return null;
+  const port = parseInt(match[1], 10);
+  return Number.isFinite(port) ? port : null;
+}
+
+/**
+ * Read dataplane `port` from materialized builder config or bundled template.
+ *
+ * @returns {number}
+ */
+function loadDataplaneManifestListenPort() {
+  const tryLoad = (configPath) => {
+    if (!fs.existsSync(configPath)) {
+      return null;
+    }
+    const variables = loadConfigFile(configPath);
+    const port = variables && variables.port !== undefined ? Number(variables.port) : NaN;
+    return Number.isFinite(port) && port > 0 ? port : null;
+  };
+
+  try {
+    const builderPath = pathsUtil.getBuilderPath('dataplane');
+    if (fs.existsSync(builderPath)) {
+      try {
+        const fromBuilder = tryLoad(pathsUtil.resolveApplicationConfigPath(builderPath));
+        if (fromBuilder) {
+          return fromBuilder;
+        }
+      } catch {
+        // Fall through to bundled template when builder dir exists but config is missing.
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  const templatePath = path.join(
+    pathsUtil.getProjectRoot(),
+    'templates',
+    'applications',
+    'dataplane',
+    'application.yaml'
+  );
+  const fromTemplate = tryLoad(templatePath);
+  return fromTemplate || DEFAULT_DATAPLANE_MANIFEST_PORT;
+}
+
+/**
+ * Local Docker host port: `application.yaml` `port` (default 3001) + developerId×100.
+ * Same rule as {@link calculateComposePort} / `aifabrix up-platform` — not
+ * `APP_SERVICE_ENV_DEFAULTS_LOCAL.DATAPLANE_PUBLIC_PORT` (3011), which is for other local profiles.
+ *
+ * @returns {Promise<string>}
+ */
+async function expectedLocalDataplaneBaseUrl() {
+  const developerIdRaw = await config.getDeveloperId();
+  const idNum =
+    typeof developerIdRaw === 'string'
+      ? parseInt(developerIdRaw, 10)
+      : Number(developerIdRaw);
+  const devId = Number.isFinite(idNum) && idNum >= 0 ? idNum : 0;
+  const basePort = loadDataplaneManifestListenPort();
+  const hostPort = devId === 0 ? basePort : basePort + devId * 100;
+  return `http://localhost:${hostPort}`;
+}
+
+/**
+ * Controller application.url can lag after dev-id changes; prefer builder host port formula for localhost.
+ * @param {string} discoveredUrl
+ * @returns {Promise<string>}
+ */
+async function alignDiscoveredDataplaneUrl(discoveredUrl) {
+  if (!discoveredUrl || !/localhost|127\.0\.0\.1/i.test(discoveredUrl)) {
+    return discoveredUrl;
+  }
+  try {
+    const expectedUrl = await expectedLocalDataplaneBaseUrl();
+    const discoveredPort = localhostPortFromUrl(discoveredUrl);
+    const expectedPort = localhostPortFromUrl(expectedUrl);
+    if (
+      discoveredPort !== null &&
+      expectedPort !== null &&
+      discoveredPort !== expectedPort
+    ) {
+      return expectedUrl;
+    }
+  } catch {
+    // Keep controller-discovered URL when developer config is unavailable.
+  }
+  return discoveredUrl;
+}
+
+/**
+ * @returns {string|null}
+ */
+function dataplaneUrlFromProcessEnv() {
+  const raw = process.env.DP || process.env.DATAPLANE_URL;
+  if (!raw || typeof raw !== 'string') {
+    return null;
+  }
+  return raw.trim().replace(/\/$/, '');
+}
 
 /**
  * Resolve dataplane URL by discovering from controller
@@ -22,9 +142,16 @@ const { discoverDataplaneUrl } = require('../commands/wizard-dataplane');
  * @throws {Error} If dataplane URL cannot be resolved
  */
 async function resolveDataplaneUrl(controllerUrl, environment, authConfig, opts = {}) {
-  return await discoverDataplaneUrl(controllerUrl, environment, authConfig, opts);
+  const envUrl = dataplaneUrlFromProcessEnv();
+  if (envUrl) {
+    return envUrl;
+  }
+  const discovered = await discoverDataplaneUrl(controllerUrl, environment, authConfig, opts);
+  return alignDiscoveredDataplaneUrl(discovered);
 }
 
 module.exports = {
-  resolveDataplaneUrl
+  resolveDataplaneUrl,
+  expectedLocalDataplaneBaseUrl,
+  alignDiscoveredDataplaneUrl
 };