@aifabrix/builder 2.45.5 → 2.46.0

package/lib/api/api-response-errors.js

@@ -0,0 +1,124 @@
+/**
+ * Throw CLI errors from ApiClient responses with formatted output preserved.
+ *
+ * @fileoverview Dataplane/controller API failure helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { formatApiError } = require('../utils/api-error-handler');
+const {
+  enrichUnresolvableGovernanceSubjectsError
+} = require('../governance/governance-cli-errors');
+const { inferServiceLabelFromUrl } = require('../utils/service-url-label');
+
+/**
+ * @param {Object|undefined} res - ApiClient response
+ * @param {string} fallbackMessage
+ * @returns {string}
+ */
+function resolveApiErrorMessage(res, fallbackMessage) {
+  if (!res) {
+    return fallbackMessage;
+  }
+  const fromError =
+    res.error &&
+    (res.error.formattedError || res.error.error || res.error.message);
+  return (
+    res.formattedError ||
+    fromError ||
+    (typeof res.error === 'string' ? res.error : null) ||
+    fallbackMessage
+  );
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpointUrl
+ * @returns {{ endpoint: string, serviceLabel: string }}
+ */
+function resolveApiFailureEndpointContext(res, endpointUrl) {
+  const endpoint =
+    (res && res.errorData && res.errorData.endpointUrl) || endpointUrl || '';
+  const serviceLabel =
+    (res && res.errorData && res.errorData.serviceLabel) ||
+    inferServiceLabelFromUrl(endpoint);
+  return { endpoint, serviceLabel };
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpoint
+ * @param {string} serviceLabel
+ * @returns {Object}
+ */
+function buildEnrichedApiFailureResponse(res, endpoint, serviceLabel) {
+  return {
+    ...res,
+    errorData: {
+      ...(res && res.errorData),
+      endpointUrl: endpoint,
+      serviceLabel
+    }
+  };
+}
+
+/**
+ * @param {Error} err
+ * @param {Object|undefined} res
+ * @param {string} endpoint
+ * @param {string} serviceLabel
+ * @param {Object} enriched
+ */
+function assignApiFailureErrorFields(err, res, endpoint, serviceLabel, enriched) {
+  err.formatted =
+    res && res.formattedError ? res.formattedError : formatApiError(enriched, null);
+  err.network = Boolean(res && res.network === true);
+  err.status = res && typeof res.status === 'number' ? res.status : 0;
+  err.endpointUrl = endpoint;
+  err.serviceLabel = serviceLabel;
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpointUrl
+ * @returns {Error}
+ */
+function buildApiFailureError(res, endpointUrl, context = {}) {
+  const message = resolveApiErrorMessage(res, 'Request failed');
+  const err = new Error(message);
+  const { endpoint, serviceLabel } = resolveApiFailureEndpointContext(res, endpointUrl);
+  const enriched = buildEnrichedApiFailureResponse(res, endpoint, serviceLabel);
+  assignApiFailureErrorFields(err, res, endpoint, serviceLabel, enriched);
+  if (
+    typeof endpoint === 'string' &&
+    endpoint.includes('/governance-scenarios/generate')
+  ) {
+    enrichUnresolvableGovernanceSubjectsError(err, context);
+  }
+  return err;
+}
+
+/**
+ * @param {Object} res - ApiClient response (`success: false`)
+ * @param {{ fallbackMessage?: string, endpointUrl?: string }} [context]
+ * @throws {Error}
+ */
+function throwIfApiFailed(res, context = {}) {
+  if (!res || res.success !== false) {
+    return;
+  }
+  const endpointUrl =
+    context.endpointUrl ||
+    (res.errorData && res.errorData.endpointUrl) ||
+    '';
+  throw buildApiFailureError(res, endpointUrl || context.endpointUrl || '', context);
+}
+
+module.exports = {
+  throwIfApiFailed,
+  buildApiFailureError,
+  resolveApiErrorMessage
+};

package/lib/api/governance-scenario-pack.api.js

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Dataplane governance scenario pack CRUD + run API (419.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const {
+  governanceUploadSchemaHint,
+  isGovernanceCoverageSchemaError
+} = require('../governance/governance-cli-errors');
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {string} datasourceKey
+ * @param {string} suffix
+ * @returns {string}
+ */
+function governanceScenarioEndpoint(dataplaneUrl, datasourceKey, suffix) {
+  const base = String(dataplaneUrl || '').replace(/\/$/, '');
+  return `${base}/api/v1/external/${encodeURIComponent(datasourceKey)}${suffix}`;
+}
+
+/**
+ * PUT /api/v1/external/{datasourceKey}/governance-scenarios
+ * @requiresPermission {Dataplane} external-data-source:update
+ * @async
+ */
+async function upsertDatasourceGovernancePack(dataplaneUrl, authConfig, datasourceKey, pack) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.put(
+    `/api/v1/external/${encodeURIComponent(datasourceKey)}/governance-scenarios`,
+    { body: { pack } }
+  );
+  if (res && res.success === false) {
+    try {
+      throwIfApiFailed(res, {
+        endpointUrl: governanceScenarioEndpoint(
+          dataplaneUrl,
+          datasourceKey,
+          '/governance-scenarios'
+        )
+      });
+    } catch (err) {
+      if (isGovernanceCoverageSchemaError(err)) {
+        err.friendlyHint = governanceUploadSchemaHint(
+          (pack && pack.spec && pack.spec.systemKey) || datasourceKey
+        );
+      }
+      throw err;
+    }
+  }
+  return unwrapApiData(res);
+}
+
+/**
+ * GET /api/v1/external/{datasourceKey}/governance-scenarios
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ */
+async function getDatasourceGovernancePack(dataplaneUrl, authConfig, datasourceKey) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(
+    `/api/v1/external/${encodeURIComponent(datasourceKey)}/governance-scenarios`
+  );
+  throwIfApiFailed(res, {
+    endpointUrl: governanceScenarioEndpoint(dataplaneUrl, datasourceKey, '/governance-scenarios')
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * POST /api/v1/external/{datasourceKey}/governance-scenarios/run
+ * @requiresPermission {Dataplane} governance:evaluate
+ * @async
+ */
+async function runDatasourceGovernanceScenarios(dataplaneUrl, authConfig, datasourceKey) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/external/${encodeURIComponent(datasourceKey)}/governance-scenarios/run`,
+    { body: {} }
+  );
+  throwIfApiFailed(res, {
+    endpointUrl: governanceScenarioEndpoint(
+      dataplaneUrl,
+      datasourceKey,
+      '/governance-scenarios/run'
+    )
+  });
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.summary) {
+    throw new Error('Governance scenario run returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/external/{datasourceKey}/governance-scenarios/generate
+ * @requiresPermission {Dataplane} external-data-source:update
+ * @async
+ */
+async function generateDatasourceGovernancePack(
+  dataplaneUrl,
+  authConfig,
+  datasourceKey,
+  body
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/external/${encodeURIComponent(datasourceKey)}/governance-scenarios/generate`,
+    { body }
+  );
+  const subjectEmails = Array.isArray(body.subjects)
+    ? body.subjects
+      .map(entry => entry && entry.subjectEmail)
+      .filter(email => typeof email === 'string' && email.trim())
+    : [];
+  throwIfApiFailed(res, {
+    endpointUrl: governanceScenarioEndpoint(
+      dataplaneUrl,
+      datasourceKey,
+      '/governance-scenarios/generate'
+    ),
+    subjectEmails
+  });
+  return unwrapApiData(res);
+}
+
+/**
+ * GET /api/v1/external/{datasourceKey}/governance-scenarios/versions
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ */
+async function listDatasourceGovernancePackVersions(dataplaneUrl, authConfig, datasourceKey) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(
+    `/api/v1/external/${encodeURIComponent(datasourceKey)}/governance-scenarios/versions`
+  );
+  throwIfApiFailed(res, {
+    endpointUrl: governanceScenarioEndpoint(
+      dataplaneUrl,
+      datasourceKey,
+      '/governance-scenarios/versions'
+    )
+  });
+  return unwrapApiData(res);
+}
+
+module.exports = {
+  upsertDatasourceGovernancePack,
+  getDatasourceGovernancePack,
+  runDatasourceGovernanceScenarios,
+  generateDatasourceGovernancePack,
+  listDatasourceGovernancePackVersions
+};

package/lib/api/index.js

@@ -14,11 +14,13 @@ const { makeApiCall, authenticatedApiCall } = require('../utils/api');
 class ApiClient {
   /**
    * Create an API client instance.
-   * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are not sent to app endpoints.
+   * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are used only for the controller token endpoint.
    * @param {string} baseUrl - Base URL for the API (controller URL)
    * @param {Object} [authConfig] - Authentication configuration
-   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token')
+   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token' | 'client-credentials')
    * @param {string} [authConfig.token] - Bearer token
+   * @param {string} [authConfig.clientId] - Client ID (client-credentials)
+   * @param {string} [authConfig.clientSecret] - Client secret (client-credentials)
    */
   constructor(baseUrl, authConfig = {}, clientOptions = {}) {
     if (baseUrl === null || baseUrl === undefined || typeof baseUrl !== 'string') {
@@ -87,6 +89,41 @@ class ApiClient {
     return headers;
   }
 
+  /**
+   * True when endpoint is the controller client-credentials token exchange.
+   * @private
+   * @param {string} endpoint - API endpoint path
+   * @returns {boolean}
+   */
+  _isClientCredentialsTokenEndpoint(endpoint) {
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    return path === '/api/v1/auth/token';
+  }
+
+  /**
+   * Add x-client-id/x-client-secret only for POST /api/v1/auth/token (never for app endpoints).
+   * @private
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} headers - Request headers built by _buildHeaders
+   * @returns {Object}
+   */
+  _applyClientCredentialHeadersForTokenEndpoint(endpoint, headers) {
+    if (this.authConfig.type !== 'client-credentials') {
+      return headers;
+    }
+    if (!this._isClientCredentialsTokenEndpoint(endpoint)) {
+      return headers;
+    }
+    const out = { ...headers };
+    if (this.authConfig.clientId) {
+      out['x-client-id'] = String(this.authConfig.clientId);
+    }
+    if (this.authConfig.clientSecret) {
+      out['x-client-secret'] = String(this.authConfig.clientSecret);
+    }
+    return out;
+  }
+
   /**
    * Make a GET request
    * @async
@@ -141,7 +178,10 @@ class ApiClient {
   async post(endpoint, options = {}) {
     await this._ensureDataplaneCliVersionGate();
     let url = this._buildUrl(endpoint);
-    const headers = this._buildHeaders(options.headers);
+    const headers = this._applyClientCredentialHeadersForTokenEndpoint(
+      endpoint,
+      this._buildHeaders(options.headers)
+    );
 
     // Add query parameters if provided
     if (options.params) {

package/lib/api/lifecycle.api.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Dataplane Enterprise AI Certification lifecycle API client (419.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * GET /api/v1/external/systems/{systemKey}/lifecycle
+ * @requiresPermission {Dataplane} external-system:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} systemKey
+ * @param {{ details?: boolean, summary?: boolean }} [opts]
+ * @returns {Promise<Object>}
+ */
+async function getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.details === true) params.details = true;
+  if (opts.summary === true) params.summary = true;
+  const res = await client.get(`/api/v1/external/systems/${encodeURIComponent(systemKey)}/lifecycle`, {
+    params
+  });
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Lifecycle report request failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.systemKey) {
+    throw new Error('Lifecycle report returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/external/systems/{systemKey}/lifecycle/run
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} systemKey
+ * @param {Object} [body]
+ * @returns {Promise<Object>}
+ */
+async function runSystemLifecycle(dataplaneUrl, authConfig, systemKey, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/external/systems/${encodeURIComponent(systemKey)}/lifecycle/run`,
+    { body }
+  );
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Lifecycle run request failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.report) {
+    throw new Error('Lifecycle run returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+module.exports = {
+  getSystemLifecycleReport,
+  runSystemLifecycle
+};

package/lib/api/pipeline.api.js

@@ -6,6 +6,7 @@
 
 const { ApiClient, createDataplaneApiClient } = require('./index');
 const { postValidationRunAndOptionalPoll } = require('./validation-runner');
+const { withStageOnValidationRunBody } = require('../utils/validation-run-stage');
 
 /**
  * @param {Object} opts
@@ -30,7 +31,7 @@ function buildValidationRunPayloadTestBody({ validationScope, systemKey, datasou
   if (validationScope === 'externalDataSource') {
     body.datasourceKey = datasourceKey;
   }
-  return body;
+  return withStageOnValidationRunBody(body, body.runType);
 }
 
 /**
@@ -242,6 +243,7 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
  * @param {Object} payload - { version, application, dataSources }; optional status (default "draft")
  * @param {string} [payload.status="draft"] - "draft" or "published"; Builder uses "draft"
+ * @param {boolean} [payload.force=false] - When true, bypass guards on active datasource publish
  * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is PublicationResult (uploadId, system, datasources, generateMcpContract, …)
  * @throws {Error} If upload fails
  */

package/lib/api/records-bulk.api.js

@@ -5,6 +5,7 @@
  */
 
 const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
 
 /**
  * Bulk sync external records for a datasource.
@@ -19,10 +20,22 @@ const { createDataplaneApiClient } = require('./index');
  */
 async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.post(
+  const res = await client.post(
     `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
     { body }
   );
+  if (res && res.success === false) {
+    const msg =
+      res.formattedError ||
+      res.error ||
+      `Bulk sync failed (HTTP ${res.status || 0})`;
+    throw new Error(msg);
+  }
+  const payload = unwrapApiData(res);
+  if (!payload || typeof payload !== 'object') {
+    throw new Error('Bulk sync returned an unexpected response shape');
+  }
+  return payload;
 }
 
 module.exports = {

package/lib/api/validation-runner.js

@@ -22,6 +22,7 @@ const { createValidationPollHandlers } = require('../utils/validation-poll-ui');
  * @param {boolean} opts.useAsync
  * @param {boolean} opts.noAsync
  * @param {boolean} [opts.verbosePoll] - Throttled poll lines when no TTY poll UI (see validation-run-poll)
+ * @param {boolean} [opts.quietPollUi] - Suppress poll spinner/lines (orchestrated verify-* owns progress)
  * @param {Function} [opts.onPollProgress] - Extra hook: `(envelope, attemptIndex, meta)` during poll
  * @returns {Promise<{ envelope: Object|null, apiError: Object|null, pollTimedOut: boolean, incompleteNoAsync: boolean }>}
  */
@@ -60,7 +61,8 @@ async function postValidationRunAndOptionalPoll(opts) {
     const deadlineMs = Date.now() + remaining;
 
     const pollUi = createValidationPollHandlers(deadlineMs, {
-      subject: opts.pollSubject
+      subject: opts.pollSubject,
+      quiet: opts.quietPollUi === true
     });
     const mergeOnPollProgress =
       typeof opts.onPollProgress === 'function'

package/lib/app/deploy-config.js

@@ -60,7 +60,10 @@ async function extractDeploymentConfig(options, _variables) {
   const { resolveEnvironment } = require('../core/config');
 
   const controllerUrl = await resolveControllerUrl();
-  const envKey = await resolveEnvironment();
+  const envKey =
+    options && options.envKey
+      ? String(options.envKey).trim().toLowerCase()
+      : await resolveEnvironment();
 
   const pollIntervalExplicit =
     options.pollInterval !== undefined && options.pollInterval !== null

package/lib/app/down.js

@@ -48,6 +48,8 @@ function execAsync(command, options = {}) {
  * @param {number|string} developerId - Developer ID
  * @returns {string} Docker volume name
  */
+const { collectDeveloperVolumeIdSuffixes } = require('../utils/developer-volume-id');
+
 function getAppVolumeName(appName, developerId) {
   const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   if (idNum === 0) {
@@ -56,6 +58,22 @@ function getAppVolumeName(appName, developerId) {
   return `aifabrix_dev${developerId}_${appName}_data`;
 }
 
+/**
+ * Docker volume name candidates for an app (handles dev6 vs dev06 naming drift).
+ *
+ * @param {string} appName
+ * @param {string|number} developerId
+ * @returns {string[]}
+ */
+function getAppVolumeNameCandidates(appName, developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (idNum === 0) {
+    return [`aifabrix_${appName}_data`, `aifabrix_dev0_${appName}_data`];
+  }
+  const suffixes = collectDeveloperVolumeIdSuffixes(developerId);
+  return suffixes.map((suffix) => `aifabrix_dev${suffix}_${appName}_data`);
+}
+
 /**
  * Stops and removes a specific application's container.
  * If --volumes is passed, attempts to remove the app's named Docker volume.
@@ -120,6 +138,7 @@ async function downApp(appName, options = {}) {
 
 module.exports = {
   downApp,
-  getAppVolumeName
+  getAppVolumeName,
+  getAppVolumeNameCandidates
 };
 

package/lib/app/push.js

@@ -19,7 +19,7 @@ const {
 
 const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
-const { detectAppType } = require('../utils/paths');
+const paths = require('../utils/paths');
 
 /**
  * Validate application name format
@@ -92,11 +92,10 @@ function extractImageName(config, appName) {
  * @throws {Error} If configuration cannot be loaded
  */
 async function loadPushConfig(appName, options) {
-  const { detectAppType, resolveApplicationConfigPath } = require('../utils/paths');
   const { loadConfigFile } = require('../utils/config-format');
-  const { appPath } = await detectAppType(appName);
   try {
-    const configPath = resolveApplicationConfigPath(appPath);
+    const { appPath } = await paths.detectAppType(appName);
+    const configPath = paths.resolveApplicationConfigPath(appPath);
     const config = loadConfigFile(configPath);
     const effective = getEffectiveConfig(config);
     const registry = options.registry || effective.image?.registry;
@@ -242,7 +241,7 @@ function displayPushResults(registry, imageName, tags) {
  */
 async function pushApp(appName, options = {}) {
   try {
-    const { isExternal } = await detectAppType(appName);
+    const { isExternal } = await paths.detectAppType(appName);
     if (isExternal) {
       logExternalIntegrationPushNotice(appName);
       return;

package/lib/app/register.js

@@ -25,6 +25,8 @@ const { callRegisterApi } = require('../utils/app-register-api');
 const { displayRegistrationResults, getEnvironmentPrefix } = require('../utils/app-register-display');
 const pathsUtil = require('../utils/paths');
 const { refreshUrlsLocalRegistryFromBuilder } = require('../utils/urls-local-registry');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const config = require('../core/config');
 
 /**
  * Build registration data payload from app configuration
@@ -152,9 +154,6 @@ async function applyLocalhostPortAdjustment(appConfig, apiUrl, options) {
  */
 async function registerApplication(appKey, options = {}) {
   logger.log(chalk.blue('📋 Registering application...\n'));
-
-  const { resolveControllerUrl } = require('../utils/controller-url');
-  const config = require('../core/config');
   await config.ensureSecretsEncryptionKey();
   const { resolveEnvironment } = config;
 
@@ -168,7 +167,11 @@ async function registerApplication(appKey, options = {}) {
   const appConfig = await extractAppConfiguration(finalVariables, appKey, options);
   await validateAppRegistrationData(appConfig, appKey);
 
-  const [controllerUrl, environmentKey] = await Promise.all([resolveControllerUrl(), resolveEnvironment()]);
+  const controllerUrl = await resolveControllerUrl();
+  const environmentKey =
+    options && options.envKey
+      ? String(options.envKey).trim().toLowerCase()
+      : await resolveEnvironment();
   const authConfig = await checkAuthentication(controllerUrl, environmentKey);
   const environment = registerApplicationSchema.environmentId(environmentKey);