@aifabrix/builder 2.49.1 → 2.50.0

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
+};

package/lib/commands/deploy-gate-orchestrator.js

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview Deploy pre-promote baseline tests and optional --gate steps (456.9).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { sectionTitle } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+const { formatDeployGateFailure } = require('./deploy-gate-failure-details');
+const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+const { runTestE2EForExternalSystem, syncLocalIfRequested, resolveExternalIntegrationContext } = require('./test-e2e-external');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
+const { resolveE2eSyncModeWhenPopulated } = require('./datasource-sync-policy');
+const { runVerifyTrustForExternalSystem } = require('./verify-trust-external');
+const { runVerifyGovernanceForExternalSystem } = require('./verify-governance-external');
+const { runGovernanceGenerateForExternalSystem } = require('./governance-generate-external');
+const { resolveGovernanceFixtureSubjectEmails } = require('./governance-fixture-subjects');
+const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
+const { VERDICT } = require('../lifecycle/product-model');
+
+const KNOWN_GATES = ['operations', 'trust', 'governance'];
+
+/**
+ * @param {string|undefined} gateRaw
+ * @returns {string[]}
+ */
+function parseDeployGateTokens(gateRaw) {
+  if (!gateRaw || typeof gateRaw !== 'string') {
+    return [];
+  }
+  const tokens = gateRaw
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  if (tokens.includes('full')) {
+    return [...KNOWN_GATES];
+  }
+  return tokens.filter((token) => KNOWN_GATES.includes(token));
+}
+
+/**
+ * Strict promote posture suggests full optional gates when caller requests profile resolution.
+ * @returns {string[]}
+ */
+function resolveStrictPromoteGateProfile() {
+  const level = (process.env.TRUST_CUSTOMER_POLICY_LEVEL || 'standard').trim().toLowerCase();
+  if (level === 'strict') {
+    return [...KNOWN_GATES];
+  }
+  return [];
+}
+
+/**
+ * @param {string|undefined} gateRaw
+ * @param {Object} [options]
+ * @returns {Set<string>}
+ */
+function resolveDeployGateSet(gateRaw, options = {}) {
+  const explicit = parseDeployGateTokens(gateRaw);
+  if (explicit.length > 0) {
+    return new Set(explicit);
+  }
+  if (options.useStrictPromoteProfile === true) {
+    return new Set(resolveStrictPromoteGateProfile());
+  }
+  return new Set();
+}
+
+/**
+ * @param {Object} options
+ * @param {Object|null|undefined} uploadCtx
+ * @returns {Object}
+ */
+function mergeUploadAuthOptions(options, uploadCtx) {
+  if (!uploadCtx?.authConfig || !uploadCtx?.dataplaneUrl) {
+    return { ...options, noPublish: true, verbose: false };
+  }
+  return {
+    ...options,
+    noPublish: true,
+    verbose: false,
+    authConfig: uploadCtx.authConfig,
+    dataplaneUrl: uploadCtx.dataplaneUrl,
+    silentResolve: true
+  };
+}
+
+/**
+ * @async
+ * @param {string} label
+ * @param {Function} runner
+ * @param {Function} isOk
+ * @param {Object} [stepOptions]
+ */
+async function runRequiredDeployStep(label, runner, isOk, stepOptions = {}) {
+  return runWithVerifyStepProgress(
+    label,
+    async() => {
+      const outcome = await runner();
+      if (!isOk(outcome)) {
+        const detail = formatDeployGateFailure(label, outcome);
+        logger.log(chalk.red(`✖ ${detail}`));
+        const err = new Error(`${label} failed: ${detail}`);
+        err.gateFailure = true;
+        throw err;
+      }
+      return outcome;
+    },
+    { json: false, quietProgress: stepOptions.quietDeployUi === true }
+  );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ unitPassed: boolean, integrationPassed: boolean }>}
+ */
+async function runDeployBaselineSteps(systemKey, options) {
+  await runRequiredDeployStep(
+    'Running unit tests',
+    () => testExternalSystem(systemKey, { verbose: false }),
+    (result) => result.valid === true,
+    options
+  );
+
+  let stepOptions = { ...options, noPublish: true, verbose: false, uploadStatus: 'published' };
+  if (!cliOptsSkipPublish(options)) {
+    const uploadCtx = await syncLocalIfRequested(systemKey, {
+      ...options,
+      uploadStatus: 'published',
+      minimal: true,
+      suppressSummary: true
+    });
+    stepOptions = mergeUploadAuthOptions({ ...options, uploadStatus: 'published' }, uploadCtx);
+  }
+
+  await runRequiredDeployStep(
+    'Running integration tests',
+    () => testExternalSystemIntegration(systemKey, stepOptions),
+    (result) => result.success === true,
+    options
+  );
+
+  return { unitPassed: true, integrationPassed: true };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runOperationsGate(systemKey, options) {
+  let stepOptions = mergeUploadAuthOptions(options, null);
+  if (!stepOptions.dataplaneUrl || !stepOptions.authConfig) {
+    try {
+      const uploadCtx = await syncLocalIfRequested(systemKey, { ...options, noPublish: true });
+      stepOptions = mergeUploadAuthOptions(options, uploadCtx);
+    } catch {
+      stepOptions = mergeUploadAuthOptions(options, null);
+    }
+  }
+
+  let e2eSyncMode = options.syncMode;
+  if (!e2eSyncMode && stepOptions.dataplaneUrl && stepOptions.authConfig) {
+    try {
+      const { keys } = resolveExternalIntegrationContext(systemKey);
+      e2eSyncMode = await resolveE2eSyncModeWhenPopulated(
+        stepOptions.dataplaneUrl,
+        stepOptions.authConfig,
+        keys
+      );
+    } catch {
+      e2eSyncMode = 'auto';
+    }
+  }
+
+  await runRequiredDeployStep(
+    'Running operations gate (E2E)',
+    () =>
+      runTestE2EForExternalSystem(systemKey, {
+        ...stepOptions,
+        env: options.env,
+        async: options.async !== false,
+        quietPollUi: true,
+        syncMode: e2eSyncMode || stepOptions.syncMode
+      }),
+    (result) => result.success === true,
+    options
+  );
+
+  return { pillar: 'operations', verdict: VERDICT.VERIFIED };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runTrustGate(systemKey, options) {
+  const result = await runRequiredDeployStep(
+    'Running trust gate',
+    () => runVerifyTrustForExternalSystem(systemKey, { ...options, noPublish: true }),
+    (outcome) => outcome.verdict === VERDICT.VERIFIED,
+    options
+  );
+  return {
+    pillar: 'trust',
+    verdict: result.verdict,
+    percent: result.aiTrustPercent ?? undefined
+  };
+}
+
+/**
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function governanceSubjectsProvided(options) {
+  return Boolean(options.subjectEmail);
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceGate(systemKey, options) {
+  const gateOptions = { ...options, noPublish: true };
+  let runner;
+  if (governanceSubjectsProvided(gateOptions)) {
+    runner = () => runVerifyGovernanceCombined(systemKey, gateOptions);
+  } else {
+    const fixtureEmails = resolveGovernanceFixtureSubjectEmails(systemKey);
+    if (fixtureEmails.length > 0) {
+      runner = async() => {
+        await runGovernanceGenerateForExternalSystem(systemKey, {
+          ...gateOptions,
+          subjectEmails: fixtureEmails
+        });
+        return runVerifyGovernanceForExternalSystem(systemKey, gateOptions);
+      };
+    } else {
+      runner = () => runVerifyGovernanceForExternalSystem(systemKey, gateOptions);
+    }
+  }
+  const result = await runRequiredDeployStep(
+    'Running governance gate',
+    runner,
+    (outcome) => outcome.verdict === VERDICT.VERIFIED,
+    options
+  );
+  const scenarios = result.enforcementScenarios || {};
+  return {
+    pillar: 'governance',
+    verdict: result.verdict,
+    scenariosPassed: scenarios.passed,
+    scenariosTotal: scenarios.total
+  };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Set<string>} gates
+ * @param {Object} options
+ * @returns {Promise<Object[]>}
+ */
+async function runDeployOptionalGates(systemKey, gates, options) {
+  const outcomes = [];
+  if (gates.has('operations')) {
+    outcomes.push(await runOperationsGate(systemKey, options));
+  }
+  if (gates.has('trust')) {
+    outcomes.push(await runTrustGate(systemKey, options));
+  }
+  if (gates.has('governance')) {
+    outcomes.push(await runGovernanceGate(systemKey, options));
+  }
+  return outcomes;
+}
+
+/**
+ * Baseline validate + test + test-integration, then optional --gate steps before controller deploy.
+ * @async
+ * @param {string} systemKey
+ * @param {Object} [options]
+ * @returns {Promise<{ baseline: { unitPassed: boolean, integrationPassed: boolean }, gates: Object[] }>}
+ */
+async function runDeployGateOrchestrator(systemKey, options = {}) {
+  const quiet = options.quietDeployUi === true || options.verbose !== true;
+  if (!quiet) {
+    logger.log('');
+    logger.log(sectionTitle('Deploy preflight'));
+  }
+  const baseline = await runDeployBaselineSteps(systemKey, { ...options, quietDeployUi: quiet });
+  const gates = resolveDeployGateSet(options.gate, options);
+  if (gates.size === 0) {
+    return { baseline, gates: [] };
+  }
+  const gateOutcomes = await runDeployOptionalGates(systemKey, gates, {
+    ...options,
+    quietDeployUi: quiet
+  });
+  return { baseline, gates: gateOutcomes };
+}
+
+module.exports = {
+  KNOWN_GATES,
+  parseDeployGateTokens,
+  resolveStrictPromoteGateProfile,
+  resolveDeployGateSet,
+  runDeployBaselineSteps,
+  runDeployOptionalGates,
+  runDeployGateOrchestrator
+};