@aifabrix/builder 2.45.0 → 2.45.5

package/lib/commands/test-trust-command-action.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview CLI action for `aifabrix test-trust` (plan 143).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { runTestTrustForExternalSystem } = require('./test-trust-external');
+const {
+  displaySystemTrustRollupTTY,
+  displayAgentTrustRunTTY
+} = require('../utils/agent-trust-run-display');
+const { computeSystemExitCodeFromTrustRows } = require('../utils/agent-trust-run-exit');
+const { writeTrustDebugLogAndPrint } = require('../datasource/agent-trust-debug-log');
+const { normalizeTestTrustCliOptions } = require('./test-trust-cli-options');
+
+/**
+ * @async
+ * @param {string} appName
+ * @param {Object} options
+ */
+async function writeSystemTrustDebugLogs(appName, results, options) {
+  if (!options.debug) return;
+  logger.log('');
+  logger.log(chalk.gray('Debug logs:'));
+  for (const row of results) {
+    await writeTrustDebugLogAndPrint(appName, row.key, {
+      request: {
+        datasourceKey: row.key,
+        revalidate: options.revalidate === true,
+        noSync: options.noSync === true
+      },
+      response: row.trustRun,
+      error: row.error || null
+    });
+  }
+}
+
+function displaySystemTrustResults(systemKey, appName, results, options) {
+  if (options.json) {
+    logger.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (options.summary) {
+    for (const row of results) {
+      const tr = row.trustRun;
+      const line = tr
+        ? `${row.key}: ${tr.trustDecision} (${tr.validationStatus})`
+        : `${row.key}: fail (${row.error || 'error'})`;
+      logger.log(line);
+    }
+    return;
+  }
+
+  const displayOpts = {
+    strict: options.strict === true,
+    showCache: options.verbose === true || options.revalidate === true
+  };
+  displaySystemTrustRollupTTY(systemKey || appName, results, displayOpts);
+
+  if (!options.verbose) return;
+
+  for (const row of results) {
+    if (!row.trustRun) continue;
+    displayAgentTrustRunTTY(row.trustRun, {
+      environment: options.env,
+      verbose: true,
+      noSync: options.noSync === true,
+      strict: options.strict === true
+    });
+  }
+}
+
+async function runTestTrustCommandAction(appName, options, cmd) {
+  const opts = normalizeTestTrustCliOptions(options, cmd);
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'test-trust applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+  const { success, results, systemKey } = await runTestTrustForExternalSystem(appName, {
+    env: opts.env,
+    verbose: opts.verbose,
+    debug: opts.debug,
+    noSync: opts.noSync === true,
+    revalidate: opts.revalidate === true,
+    summary: opts.summary === true,
+    timeout: opts.timeout
+  });
+  displaySystemTrustResults(systemKey, appName, results, opts);
+  await writeSystemTrustDebugLogs(appName, results, opts);
+  const exitCode = computeSystemExitCodeFromTrustRows(results, {
+    warningsAsErrors: opts.warningsAsErrors === true,
+    strict: opts.strict === true
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+  if (!success) process.exit(1);
+}
+
+async function testTrustCommandHandler(appName, options, cmd) {
+  try {
+    await runTestTrustCommandAction(appName, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'test-trust');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  runTestTrustCommandAction,
+  testTrustCommandHandler
+};

package/lib/commands/test-trust-external.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview test-trust <systemKey> — semantic agent metadata validation for all datasources.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { getConfig } = require('../core/config');
+const { setupIntegrationTestAuth } = require('../external-system/test-auth');
+const { runDatasourceAgentTrust } = require('../datasource/agent-trust-run');
+const { resolveExternalIntegrationContext } = require('./test-e2e-external');
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }|null>}
+ */
+async function syncLocalIfRequested(systemKey, options) {
+  if (cliOptsSkipSync(options)) return null;
+  const { uploadExternalSystem } = require('./upload');
+  logger.log(chalk.cyan('Syncing local config to dataplane…'));
+  const uploadCtx = await uploadExternalSystem(systemKey, {
+    minimal: true,
+    verbose: !!options.verbose
+  });
+  logger.log(chalk.green('✔ Sync complete'));
+  return uploadCtx && uploadCtx.dataplaneUrl && uploadCtx.authConfig ? uploadCtx : null;
+}
+
+function pushTrustResult(results, key, trustRun, apiError) {
+  const failed =
+    apiError ||
+    !trustRun ||
+    trustRun.trustDecision === 'notTrusted' ||
+    trustRun.validationStatus === 'failed';
+  results.push({
+    key,
+    success: !failed,
+    error: failed
+      ? apiError
+        ? apiError.message || String(apiError)
+        : trustRun.summary || 'Trust validation failed'
+      : undefined,
+    trustRun
+  });
+}
+
+/**
+ * @async
+ * @param {Object|null} uploadCtx
+ * @param {string} externalSystem
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveTrustAuthContext(uploadCtx, externalSystem, options) {
+  if (uploadCtx) {
+    return { authConfig: uploadCtx.authConfig, dataplaneUrl: uploadCtx.dataplaneUrl };
+  }
+  const configObj = await getConfig();
+  return setupIntegrationTestAuth(externalSystem, { environment: options.env }, configObj);
+}
+
+/**
+ * @async
+ * @param {string[]} keys
+ * @param {Object} runOpts
+ * @param {Array<Object>} results
+ */
+async function runTrustForDatasourceKeys(keys, runOpts, results) {
+  for (const key of keys) {
+    try {
+      const { trustRun, apiError } = await runDatasourceAgentTrust(key, runOpts);
+      pushTrustResult(results, key, trustRun, apiError);
+    } catch (err) {
+      results.push({ key, success: false, error: err.message, trustRun: null });
+    }
+  }
+}
+
+/**
+ * @async
+ * @param {string} externalSystem
+ * @param {Object} options
+ * @returns {Promise<{ success: boolean, results: Array<Object>, systemKey: string }>}
+ */
+async function runTestTrustForExternalSystem(externalSystem, options = {}) {
+  const { systemKey, keys } = resolveExternalIntegrationContext(externalSystem);
+  if (keys.length === 0) {
+    logger.log(chalk.yellow(`No datasources found for ${externalSystem}.`));
+    return { success: true, results: [], systemKey };
+  }
+
+  const uploadCtx = await syncLocalIfRequested(systemKey, options);
+  if (options.revalidate === true) {
+    logger.log(chalk.cyan('Forcing revalidation (cache bypass) for each datasource…'));
+  }
+
+  const { authConfig, dataplaneUrl } = await resolveTrustAuthContext(
+    uploadCtx,
+    externalSystem,
+    options
+  );
+  const results = [];
+  await runTrustForDatasourceKeys(
+    keys,
+    {
+      app: externalSystem,
+      environment: options.env,
+      noSync: true,
+      revalidate: options.revalidate === true,
+      summary: options.summary === true,
+      timeout: options.timeout,
+      authConfig,
+      dataplaneUrl
+    },
+    results
+  );
+  return { success: results.every(r => r.success), results, systemKey };
+}
+
+module.exports = {
+  runTestTrustForExternalSystem
+};

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(
@@ -364,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);
@@ -375,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 pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload, {
+    json: options.json === true
+  });
 
-  const rawRes = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
-  await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+  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,
@@ -389,6 +409,7 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
     authConfig,
     rawRes
   });
+  return { dataplaneUrl, authConfig, environment };
 }
 
 /**
@@ -400,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 = {}) {
@@ -417,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/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
+};

package/lib/datasource/agent-trust-debug-log.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Debug log writer for agent trust CLI runs (plan 143).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const logger = require('../utils/logger');
+const { getIntegrationPath } = require('../utils/paths');
+const { writeTestLog } = require('../utils/test-log-writer');
+
+/**
+ * @async
+ * @param {string} appKey - Integration folder key
+ * @param {string} datasourceKey
+ * @param {Object} payload
+ * @returns {Promise<string|null>} Log path or null when skipped
+ */
+async function writeTrustDebugLog(appKey, datasourceKey, payload) {
+  const logPath = await writeTestLog(
+    appKey,
+    payload,
+    `test-trust-${datasourceKey}`,
+    path.dirname(getIntegrationPath(appKey))
+  );
+  return logPath;
+}
+
+/**
+ * @async
+ * @param {string} appKey
+ * @param {string} datasourceKey
+ * @param {Object} payload
+ */
+async function writeTrustDebugLogAndPrint(appKey, datasourceKey, payload) {
+  const logPath = await writeTrustDebugLog(appKey, datasourceKey, payload);
+  logger.log(chalk.gray(`  Debug log: ${logPath}`));
+  return logPath;
+}
+
+module.exports = {
+  writeTrustDebugLog,
+  writeTrustDebugLogAndPrint
+};