@aifabrix/builder 2.49.2 → 2.50.0

package/lib/commands/datasource-sync-policy.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Bootstrap vs explicit datasource data sync policy for upload/deploy.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getDatasource, getDatasourceStatus } = require('../api/datasources-core.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const { assertDatasourceExistsOnDataplane } = require('../protection/preflight-datasource-ready');
+const { syncDatasourceAfterProtectionUpload } = require('../protection/sync-after-upload');
+
+/**
+ * @param {Object|null|undefined} row
+ * @returns {number|null}
+ */
+function readRecordCountFromRow(row) {
+  if (!row || typeof row !== 'object') {
+    return null;
+  }
+  const candidates = [
+    row.recordCount,
+    row.totalRecords,
+    row.activeRecords,
+    row.data?.recordCount,
+    row.data?.totalRecords,
+    row.data?.activeRecords,
+    row.stats?.recordCount,
+    row.stats?.totalRecords
+  ];
+  for (const value of candidates) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @param {Map<string, number|null>} [cache]
+ * @returns {Promise<number|null>}
+ */
+async function resolveDatasourceRecordCount(dataplaneUrl, authConfig, datasourceKey, cache) {
+  const key = String(datasourceKey || '').trim();
+  if (!key) {
+    return null;
+  }
+  if (cache && cache.has(key)) {
+    return cache.get(key);
+  }
+
+  let count = null;
+  try {
+    const statusRes = await getDatasourceStatus(dataplaneUrl, key, authConfig);
+    count = readRecordCountFromRow(unwrapApiData(statusRes));
+  } catch {
+    count = null;
+  }
+
+  if (count === null) {
+    try {
+      const dsRes = await getDatasource(dataplaneUrl, key, authConfig);
+      count = readRecordCountFromRow(unwrapApiData(dsRes));
+    } catch {
+      count = null;
+    }
+  }
+
+  if (cache) {
+    cache.set(key, count);
+  }
+  return count;
+}
+
+/**
+ * Bootstrap preflight: datasource is deployed and readable on the dataplane.
+ * Does not call legacy POST /external/{key}/test (removed from dataplane OpenAPI).
+ *
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @returns {Promise<boolean>}
+ */
+async function checkDatasourceConnectivity(dataplaneUrl, authConfig, datasourceKey) {
+  try {
+    await assertDatasourceExistsOnDataplane(dataplaneUrl, authConfig, datasourceKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} params
+ * @param {Map<string, number|null>} cache
+ * @returns {Promise<{ datasourceKey: string, bucket: string, reason: string }>}
+ */
+async function evaluateBootstrapSyncCandidate(datasourceKey, params, cache) {
+  const count = await resolveDatasourceRecordCount(
+    params.dataplaneUrl,
+    params.authConfig,
+    datasourceKey,
+    cache
+  );
+  if (typeof count === 'number' && count > 0) {
+    return { datasourceKey, bucket: 'skipped', reason: 'has_data' };
+  }
+  const connected = await checkDatasourceConnectivity(
+    params.dataplaneUrl,
+    params.authConfig,
+    datasourceKey
+  );
+  if (!connected) {
+    return { datasourceKey, bucket: 'skipped', reason: 'no_connectivity' };
+  }
+  return { datasourceKey, bucket: 'run', reason: 'bootstrap' };
+}
+
+/**
+ * @param {Object} params
+ * @param {boolean} [params.syncExplicit]
+ * @param {boolean} [params.skipSync]
+ * @param {string[]} params.datasourceKeys
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @returns {Promise<{ run: Object[], skipped: Object[] }>}
+ */
+async function resolveSyncPlan(params) {
+  const keys = [
+    ...new Set((params.datasourceKeys || []).map((k) => String(k || '').trim()).filter(Boolean))
+  ];
+  const skipped = [];
+  const run = [];
+  const cache = new Map();
+
+  if (params.skipSync === true) {
+    keys.forEach((datasourceKey) => skipped.push({ datasourceKey, reason: 'skipped' }));
+    return { run, skipped };
+  }
+
+  if (params.syncExplicit === true) {
+    keys.forEach((datasourceKey) => run.push({ datasourceKey, reason: 'explicit' }));
+    return { run, skipped };
+  }
+
+  for (const datasourceKey of keys) {
+    const decision = await evaluateBootstrapSyncCandidate(datasourceKey, params, cache);
+    if (decision.bucket === 'skipped') {
+      skipped.push({ datasourceKey: decision.datasourceKey, reason: decision.reason });
+      continue;
+    }
+    run.push({ datasourceKey: decision.datasourceKey, reason: decision.reason });
+  }
+  return { run, skipped };
+}
+
+/**
+ * @param {{ run: Object[] }} plan
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @returns {Promise<{ executed: Object[], skipped: Object[] }>}
+ */
+async function executeSyncPlan(plan, dataplaneUrl, authConfig) {
+  const executed = [];
+  for (const item of plan.run) {
+    const syncResult = await syncDatasourceAfterProtectionUpload(
+      dataplaneUrl,
+      authConfig,
+      item.datasourceKey
+    );
+    executed.push({ ...item, ...syncResult });
+  }
+  return { executed, skipped: plan.skipped || [] };
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string[]} datasourceKeys
+ * @returns {Promise<'never'|'auto'>}
+ */
+async function resolveE2eSyncModeWhenPopulated(dataplaneUrl, authConfig, datasourceKeys) {
+  const keys = [
+    ...new Set((datasourceKeys || []).map((k) => String(k || '').trim()).filter(Boolean))
+  ];
+  if (keys.length === 0) {
+    return 'auto';
+  }
+  const cache = new Map();
+  for (const key of keys) {
+    const count = await resolveDatasourceRecordCount(dataplaneUrl, authConfig, key, cache);
+    if (count === null || count === 0) {
+      return 'auto';
+    }
+  }
+  return 'never';
+}
+
+module.exports = {
+  readRecordCountFromRow,
+  resolveDatasourceRecordCount,
+  resolveSyncPlan,
+  executeSyncPlan,
+  resolveE2eSyncModeWhenPopulated
+};

package/lib/commands/datasource-test-trust-cli.js

@@ -13,7 +13,7 @@ const { writeTrustDebugLogAndPrint } = require('../datasource/agent-trust-debug-
 const { displayAgentTrustRunTTY } = require('../utils/agent-trust-run-display');
 const { computeExitCodeFromTrustRun } = require('../utils/agent-trust-run-exit');
 const { attachDatasourceTestCommonOptions } = require('./datasource-unified-test-cli.options');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 function datasourceVerifyTrustHelpAfter() {
   return `
@@ -25,7 +25,7 @@ Examples:
 
 Notes:
   - Semantic trust only (agent metadata validation). For live API proof use test-e2e.
-  - Local files are published before run unless --no-sync.
+  - Local files are published before run unless --no-publish.
   - With --debug, JSON is saved under integration/<app>/logs/ (verify-trust-<key>-*.json). View with: aifabrix datasource log-trust <key>
 `;
 }
@@ -34,7 +34,7 @@ async function runDatasourceVerifyTrustOnce(datasourceKey, options) {
   const { trustRun, apiError } = await runDatasourceAgentTrust(datasourceKey, {
     app: options.app,
     environment: options.env,
-    noSync: options.noSync === true,
+    noPublish: options.noPublish === true,
     force: options.force === true,
     revalidate: options.revalidate === true,
     summary: options.summary === true,
@@ -48,7 +48,7 @@ async function finalizeDatasourceVerifyTrust(datasourceKey, options, result) {
     json: options.json,
     verbose: options.verbose,
     environment: options.env,
-    noSync: options.noSync === true,
+    noPublish: options.noPublish === true,
     strict: options.strict === true
   };
   if (options.json) {
@@ -70,7 +70,7 @@ async function finalizeDatasourceVerifyTrust(datasourceKey, options, result) {
 
 async function datasourceVerifyTrustAction(datasourceKey, options, cmd) {
   try {
-    const merged = { ...options, noSync: cliOptsSkipSync(options, cmd) };
+    const merged = { ...options, noPublish: cliOptsSkipPublish(options, cmd) };
     const result = await runDatasourceVerifyTrustOnce(datasourceKey, merged);
     const { resolveAppKeyForDatasource } = require('../datasource/resolve-app');
     const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
@@ -97,7 +97,7 @@ function attachDatasourceTrustOptions(cmd) {
     timeoutDefault: '120000'
   });
   cmd
-    .option('--no-sync', 'Skip publishing local integration files before validate')
+    .option('--no-publish', 'Skip publishing local integration files before validate')
     .option('--revalidate', 'Force new validation (ignore inputHash cache)')
     .option('--strict', 'Exit 1 unless trustDecision is trusted');
 }

package/lib/commands/datasource-unified-test-cli.js

@@ -47,7 +47,8 @@ async function writeDatasourceTestDebugLogIfRequested(appKey, datasourceKey, res
   const requestMeta = {
     datasourceKey,
     runType: 'test',
-    includeDebug: includeDebugForRequest(options.debug)
+    includeDebug: includeDebugForRequest(options.debug),
+    explainCertification: includeDebugForRequest(options.debug)
   };
   const envelope = result && typeof result === 'object' ? result.envelope : null;
   const apiError = result && typeof result === 'object' ? result.apiError : null;

package/lib/commands/datasource-unified-test-cli.options.js

@@ -79,6 +79,37 @@ function attachDatasourceWatchOptions(cmd) {
     .option('--watch-full-diff', 'Print full before/after fingerprint lines when the result changes');
 }
 
+function attachDatasourceTestSyncAndOutputOptions(cmd, opts) {
+  cmd
+    .option(
+      '--timeout <ms>',
+      opts.timeoutHelp || 'Aggregate timeout for POST + polls (ms)',
+      opts.timeoutDefault || '60000'
+    )
+    .option(
+      '--version <target>',
+      'Manifest version for test (latest, running, or explicit version id)',
+      'latest'
+    )
+    .option(
+      '--sync-mode <mode>',
+      'Sync policy during test: auto (default), never, or force. Distinct from --sync (publish local files).',
+      'auto'
+    )
+    .option(
+      '--sync',
+      'Publish local integration config to the dataplane before running the test (same as aifabrix upload <systemKey>; requires login)'
+    )
+    .option(
+      '--force',
+      'With --sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
+    )
+    .option('--json', 'Print raw DatasourceTestRun JSON to stdout')
+    .option('--summary', 'Print compact summary line')
+    .option('--warnings-as-errors', 'Exit 1 when root status is warn')
+    .option('--require-cert', 'Exit 2 when certificate missing or not_passed');
+}
+
 /**
  * Shared options for datasource-level `test`, `test-integration`, and `test-e2e`.
  *
@@ -112,35 +143,14 @@ function attachDatasourceTestCommonOptions(cmd, opts) {
     .option(
       '-d, --debug [level]',
       opts.debugHelp ||
-        'includeDebug on request; TTY appendix: summary (default), full, or raw (not with --json)'
+        'includeDebug + explainCertification on request; TTY appendix includes certification debug (summary default, full, or raw; not with --json)'
     );
 
   if (includePayload) {
     cmd.option('-p, --payload <file>', 'Optional custom payload file (sets payloadTemplate on request)');
   }
 
-  cmd
-    .option(
-      '--timeout <ms>',
-      opts.timeoutHelp || 'Aggregate timeout for POST + polls (ms)',
-      opts.timeoutDefault || '30000'
-    )
-    .option(
-      '--sync',
-      'Publish local integration config to the dataplane before running the test (same as aifabrix upload <systemKey>; requires login)'
-    )
-    .option(
-      '--force',
-      'With --sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
-    )
-    .option('--json', 'Print raw DatasourceTestRun JSON to stdout')
-    .option('--summary', 'Print compact summary line')
-    .option('--warnings-as-errors', 'Exit 1 when root status is warn')
-    .option('--require-cert', 'Exit 2 when certificate missing or not_passed')
-    .option(
-      '--no-cert-sync',
-      'Skip updating system file certification from the dataplane after a successful run'
-    );
+  attachDatasourceTestSyncAndOutputOptions(cmd, opts);
 
   if (includeNoAsync) {
     cmd.option('--no-async', 'Do not poll; fail if report is not complete in first response');

package/lib/commands/deploy-gate-failure-details.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Actionable deploy --gate failure messages (opaque "step failed" remediation).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { VERDICT } = require('../lifecycle/product-model');
+
+/**
+ * @param {Object|undefined} scenario
+ * @returns {boolean}
+ */
+function scenarioFailed(scenario) {
+  if (!scenario || typeof scenario !== 'object') {
+    return false;
+  }
+  if (scenario.passed === false) {
+    return true;
+  }
+  if (scenario.status === 'fail') {
+    return true;
+  }
+  const verdict = scenario.verdict ? String(scenario.verdict).toLowerCase() : '';
+  return verdict === 'failed' || verdict === 'fail';
+}
+
+/**
+ * @param {Object|undefined} row
+ * @returns {string|null}
+ */
+function firstFailedScenarioHint(row) {
+  if (!row || typeof row !== 'object') {
+    return null;
+  }
+  const scenarios = row.result?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return null;
+  }
+  const bad = scenarios.find((scenario) => scenarioFailed(scenario));
+  if (!bad) {
+    return null;
+  }
+  const id = bad.scenarioId || bad.id || bad.key;
+  const reason = bad.failureReason || bad.code || bad.message;
+  if (id && reason) {
+    return `${id}: ${reason}`;
+  }
+  return reason || id || null;
+}
+
+/**
+ * @param {Object} result
+ * @returns {string}
+ */
+function formatGovernanceGateFailure(result) {
+  const rows = Array.isArray(result?.datasourceRows) ? result.datasourceRows : [];
+  const failedRows = rows.filter((row) => row.verdict !== VERDICT.VERIFIED);
+  if (failedRows.length === 0) {
+    const enforcement = result?.enforcementScenarios;
+    if (enforcement && typeof enforcement.total === 'number') {
+      return `governance verdict ${result?.verdict || 'not VERIFIED'} (${enforcement.passed || 0}/${enforcement.total} scenarios)`;
+    }
+    return `governance verdict ${result?.verdict || 'not VERIFIED'}`;
+  }
+  return failedRows
+    .map((row) => {
+      const scenarios = row.scenarios || {};
+      let line = `${row.datasourceKey} ${scenarios.passed ?? 0}/${scenarios.total ?? 0} scenarios`;
+      if (row.error) {
+        line += ` (${row.error})`;
+      }
+      const hint = firstFailedScenarioHint(row);
+      if (hint) {
+        line += ` — ${hint}`;
+      }
+      return line;
+    })
+    .join('; ');
+}
+
+/**
+ * @param {Object} result
+ * @returns {string}
+ */
+function formatTrustGateFailure(result) {
+  const findings = Array.isArray(result?.findings) ? result.findings : [];
+  const failed = findings.filter((item) => item && item.severity === 'fail');
+  if (failed.length > 0) {
+    const first = failed[0];
+    const code = first.code ? `${first.code}: ` : '';
+    return `${code}${first.message || 'trust check failed'}`;
+  }
+  return `trust verdict ${result?.verdict || 'not VERIFIED'}`;
+}
+
+/**
+ * @param {Object} result
+ * @returns {string}
+ */
+function formatOperationsGateFailure(result) {
+  const datasources = Array.isArray(result?.datasources) ? result.datasources : [];
+  const failed = datasources.filter((row) => row && row.success === false);
+  if (failed.length > 0) {
+    return failed
+      .map((row) => `${row.key || row.datasourceKey || 'datasource'}: ${row.error || 'E2E failed'}`)
+      .join('; ');
+  }
+  if (result?.error) {
+    return String(result.error);
+  }
+  return 'E2E validation did not succeed for one or more datasources';
+}
+
+/**
+ * @param {Object} result
+ * @returns {string}
+ */
+function formatIntegrationGateFailure(result) {
+  if (result?.error) {
+    return String(result.error);
+  }
+  if (result?.message) {
+    return String(result.message);
+  }
+  return 'integration test did not succeed';
+}
+
+/**
+ * @param {string} stepLabel
+ * @param {Object} outcome
+ * @returns {string}
+ */
+function formatDeployGateFailure(stepLabel, outcome) {
+  const label = String(stepLabel || '').toLowerCase();
+  if (label.includes('governance')) {
+    return formatGovernanceGateFailure(outcome);
+  }
+  if (label.includes('trust')) {
+    return formatTrustGateFailure(outcome);
+  }
+  if (label.includes('operations') || label.includes('e2e')) {
+    return formatOperationsGateFailure(outcome);
+  }
+  if (label.includes('integration')) {
+    return formatIntegrationGateFailure(outcome);
+  }
+  if (label.includes('unit')) {
+    return outcome?.errors?.[0]?.message || 'unit validation failed';
+  }
+  return 'step did not pass';
+}
+
+module.exports = {
+  firstFailedScenarioHint,
+  formatDeployGateFailure,
+  formatGovernanceGateFailure,
+  formatIntegrationGateFailure,
+  formatOperationsGateFailure,
+  formatTrustGateFailure,
+  scenarioFailed
+};