@aifabrix/builder 2.45.0 → 2.46.0

package/lib/commands/verify-governance-db.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview verify-governance DB pack path (plan 150.0).
+ */
+
+'use strict';
+
+const {
+  resolveExternalIntegrationContext,
+  syncLocalIfRequested
+} = require('./test-e2e-external');
+const { runDatasourceGovernanceScenarios, getDatasourceGovernancePack } = require('../api/governance-scenario-pack.api');
+const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { VERDICT } = require('../lifecycle/product-model');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+
+/**
+ * @param {Object} options
+ * @param {Object|null} uploadCtx
+ */
+function attachUploadAuthToOptions(options, uploadCtx) {
+  if (!uploadCtx?.authConfig || !uploadCtx?.dataplaneUrl) {
+    return;
+  }
+  options.authConfig = uploadCtx.authConfig;
+  options.dataplaneUrl = uploadCtx.dataplaneUrl;
+  options.silentResolve = true;
+}
+
+/**
+ * @async
+ * @param {string[]} keys
+ * @param {Object} ctx
+ * @param {{ setLabel?: (label: string) => void }} [progress]
+ * @returns {Promise<Array>}
+ */
+async function runGovernanceForDatasourceKeys(keys, ctx, progress = {}) {
+  const rows = [];
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+    if (typeof progress.setLabel === 'function') {
+      progress.setLabel(`Running governance scenarios: ${key} (${index + 1}/${keys.length})`);
+    }
+    try {
+      const packRow = await getDatasourceGovernancePack(ctx.dataplaneUrl, ctx.authConfig, key);
+      if (!packRow || !packRow.pack) {
+        continue;
+      }
+      const result = await runDatasourceGovernanceScenarios(ctx.dataplaneUrl, ctx.authConfig, key);
+      const summary = result.summary || {};
+      rows.push({
+        datasourceKey: key,
+        verdict: summary.failed > 0 ? VERDICT.FAILED : VERDICT.VERIFIED,
+        scenarios: { passed: summary.passed || 0, total: summary.total || 0 },
+        policyCoveragePercent: result.policyCoveragePercent ?? 100,
+        dimensionCoveragePercent: result.dimensionCoveragePercent ?? 100,
+        packDocument: packRow.pack,
+        result
+      });
+    } catch (err) {
+      rows.push({
+        datasourceKey: key,
+        verdict: VERDICT.FAILED,
+        error: err.message,
+        scenarios: { passed: 0, total: 0 }
+      });
+    }
+  }
+  return rows;
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runVerifyGovernanceFromDbPacks(systemKey, options) {
+  const { systemKey: resolvedKey, keys } = resolveExternalIntegrationContext(systemKey);
+  if (keys.length === 0) {
+    return { resolvedKey, datasourceRows: [] };
+  }
+
+  if (!cliOptsSkipSync(options)) {
+    const uploadCtx = await syncLocalIfRequested(resolvedKey, options);
+    attachUploadAuthToOptions(options, uploadCtx);
+  }
+
+  const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(resolvedKey, options);
+  const datasourceRows = await runWithVerifyStepProgress(
+    'Running governance scenarios',
+    async(progress) =>
+      runGovernanceForDatasourceKeys(keys, { authConfig, dataplaneUrl }, progress),
+    options
+  );
+  return { resolvedKey, datasourceRows };
+}
+
+module.exports = {
+  runGovernanceForDatasourceKeys,
+  runVerifyGovernanceFromDbPacks
+};

package/lib/commands/verify-governance-external.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview verify-governance orchestration — DB scenario packs per datasource (plan 150.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runTestGovernanceForExternalSystem } = require('./test-governance-external');
+const { runVerifyGovernanceFromDbPacks } = require('./verify-governance-db');
+const { VERDICT, verdictFromPassed } = require('../lifecycle/product-model');
+const {
+  sumEnforcementScenarios,
+  aggregateCoverage,
+  buildPackOverrideResult
+} = require('./verify-governance-result-builders');
+
+/**
+ * @param {Array<Object>} rows
+ * @returns {{ passed: number, total: number }}
+ */
+function buildDbPackResult(resolvedKey, datasourceRows) {
+  const allVerified = datasourceRows.every(r => r.verdict === VERDICT.VERIFIED);
+  const coverage = aggregateCoverage(datasourceRows);
+  return {
+    systemKey: resolvedKey,
+    command: 'verify-governance',
+    verdict: verdictFromPassed(allVerified),
+    policyCoveragePercent: coverage.policy ?? (allVerified ? 100 : 0),
+    dimensionCoveragePercent: coverage.dimension ?? (allVerified ? 100 : 0),
+    enforcementScenarios: sumEnforcementScenarios(datasourceRows),
+    datasourceRows
+  };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runVerifyGovernanceForExternalSystem(systemKey, options = {}) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'verify-governance applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+
+  if (options.pack) {
+    const runPayload = await runTestGovernanceForExternalSystem(systemKey, options);
+    return buildPackOverrideResult(systemKey, runPayload);
+  }
+
+  const { resolvedKey, datasourceRows } = await runVerifyGovernanceFromDbPacks(systemKey, options);
+  if (datasourceRows.length === 0) {
+    return {
+      systemKey: resolvedKey,
+      command: 'verify-governance',
+      verdict: VERDICT.FAILED,
+      policyCoveragePercent: 0,
+      dimensionCoveragePercent: 0,
+      enforcementScenarios: { passed: 0, total: 0 },
+      datasourceRows: []
+    };
+  }
+
+  return buildDbPackResult(resolvedKey, datasourceRows);
+}
+
+module.exports = {
+  runVerifyGovernanceForExternalSystem,
+  buildPackOverrideResult,
+  sumEnforcementScenarios,
+  aggregateCoverage
+};

package/lib/commands/verify-governance-result-builders.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Shared verify-governance result builders (breaks governance-verify circular require).
+ */
+
+'use strict';
+
+const { verdictFromPassed } = require('../lifecycle/product-model');
+const { primaryDatasourceFromPack } = require('../governance/governance-run-display');
+
+/**
+ * @param {Array<Object>} rows
+ * @returns {{ passed: number, total: number }}
+ */
+function sumEnforcementScenarios(rows) {
+  let passed = 0;
+  let total = 0;
+  for (const row of rows) {
+    if (row.scenarios) {
+      passed += row.scenarios.passed || 0;
+      total += row.scenarios.total || 0;
+    }
+  }
+  return { passed, total };
+}
+
+/**
+ * @param {Array<Object>} rows
+ * @returns {{ policy: number|null, dimension: number|null }}
+ */
+function aggregateCoverage(rows) {
+  const policyVals = rows.map(r => r.policyCoveragePercent).filter(v => typeof v === 'number');
+  const dimVals = rows.map(r => r.dimensionCoveragePercent).filter(v => typeof v === 'number');
+  const minOr100 = vals => (vals.length === 0 ? null : Math.min(...vals));
+  return {
+    policy: minOr100(policyVals),
+    dimension: minOr100(dimVals)
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @param {{ result: Object, packPath: string, packDocument?: Object }} runPayload
+ * @param {string} [commandName]
+ * @returns {Object}
+ */
+function buildPackOverrideResult(systemKey, runPayload, commandName = 'verify-governance') {
+  const { result, packPath, packDocument } = runPayload;
+  const summary = result.summary || {};
+  return {
+    systemKey,
+    command: commandName,
+    verdict: verdictFromPassed(summary.failed === 0),
+    policyCoveragePercent: 100,
+    dimensionCoveragePercent: 100,
+    enforcementScenarios: {
+      passed: summary.passed || 0,
+      total: summary.total || 0
+    },
+    packPath,
+    packDocument,
+    packDatasourceKey: primaryDatasourceFromPack(packDocument),
+    legacyResult: result,
+    datasourceRows: []
+  };
+}
+
+module.exports = {
+  sumEnforcementScenarios,
+  aggregateCoverage,
+  buildPackOverrideResult
+};

package/lib/commands/verify-operations-command-action.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview CLI action for `aifabrix verify-operations` (plan 150.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { runVerifyOperationsForExternalSystem } = require('./verify-operations-external');
+const { displayVerifyOperationsTTY } = require('../lifecycle/report-display');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
+
+/**
+ * @param {Object} options
+ * @param {import('commander').Command} [cmd]
+ * @returns {Object}
+ */
+function normalizeVerifyOperationsCliOptions(options, cmd) {
+  const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
+  const has = flag => raw.includes(flag);
+  return {
+    env: options.env || 'dev',
+    verbose: options.verbose === true || has('-v') || has('--verbose'),
+    debug: options.debug === true || has('-d') || has('--debug'),
+    json: options.json === true || has('--json'),
+    noSync: cliOptsSkipSync(options, cmd),
+    continue: options.continue === true || has('--continue'),
+    async: options.async !== false
+  };
+}
+
+async function runVerifyOperationsCommandAction(appName, options, cmd) {
+  const opts = normalizeVerifyOperationsCliOptions(options, cmd);
+  const result = await runVerifyOperationsForExternalSystem(appName, opts);
+
+  if (opts.json) {
+    logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+  } else {
+    displayVerifyOperationsTTY(appName, result, {
+      details: opts.verbose,
+      warnings: result.warnings
+    });
+  }
+
+  const exitCode = exitCodeFromVerdict(result.verdict);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+async function verifyOperationsCommandHandler(appName, options, cmd) {
+  try {
+    await runVerifyOperationsCommandAction(appName, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'verify-operations');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  normalizeVerifyOperationsCliOptions,
+  runVerifyOperationsCommandAction,
+  verifyOperationsCommandHandler
+};

package/lib/commands/verify-operations-external.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview verify-operations orchestration for external systems (plan 150.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runOperationsVerifySteps } = require('./verify-operations-steps');
+const { persistOperationsForSystem } = require('./verify-operations-persist');
+const {
+  VERDICT,
+  WARNING_CODES,
+  actionHint,
+  verdictFromPassed,
+  computeOperationalReadinessPercent,
+  buildOperationsChecksFromSteps
+} = require('../lifecycle/product-model');
+const { getSystemLifecycleReport } = require('../api/lifecycle.api');
+const {
+  extractReadinessMetricsFromLifecycleReport
+} = require('../lifecycle/operations-readiness-metrics');
+const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+
+/**
+ * Build grouped details for verbose (-v) output.
+ * @param {Record<string, boolean>} checks
+ * @returns {Object}
+ */
+function groupOperationsDetails(checks) {
+  return {
+    connectivity: {
+      credentials: checks.credentials,
+      authentication: checks.authentication,
+      authorization: checks.authorization
+    },
+    contracts: {
+      openApi: checks.openApi,
+      mappings: checks.mappings
+    },
+    runtime: {
+      sync: checks.sync,
+      crud: checks.crud,
+      execution: checks.execution
+    },
+    reliability: {
+      validation: checks.validation,
+      unitTests: checks.unitTests,
+      integrationTests: checks.integrationTests,
+      e2eTests: checks.e2eTests
+    }
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} authConfig
+ * @param {string} dataplaneUrl
+ * @returns {Promise<Array>}
+ */
+async function fetchCrossPillarWarnings(systemKey, authConfig, dataplaneUrl) {
+  try {
+    const report = await getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, {
+      summary: true
+    });
+    const warnings = [];
+    if (report.trust?.verdict !== VERDICT.VERIFIED) {
+      warnings.push({
+        code: WARNING_CODES.TRUST_NOT_VERIFIED,
+        message: 'AI trust not verified',
+        action: actionHint(systemKey, 'verify-trust'),
+        suggestedCommand: 'verify-trust'
+      });
+    }
+    if (report.governance?.verdict !== VERDICT.VERIFIED) {
+      warnings.push({
+        code: WARNING_CODES.GOVERNANCE_NOT_VERIFIED,
+        message: 'Governance not verified',
+        action: actionHint(systemKey, 'governance verify'),
+        suggestedCommand: 'governance verify'
+      });
+    }
+    return warnings;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.systemKey
+ * @param {Object} params.stepResults
+ * @param {Record<string, boolean>} params.checks
+ * @param {boolean} params.hardFailure
+ * @param {Object} params.options
+ * @param {number|null} [params.persistedReadinessPercent]
+ * @param {Object|null} [params.readinessMetrics]
+ */
+async function buildOperationsResult({
+  systemKey,
+  stepResults,
+  checks,
+  hardFailure,
+  options,
+  persistedReadinessPercent = null,
+  persistedOperationsVerdict = null,
+  readinessMetrics = null,
+  lifecycleCertification = null
+}) {
+  const localPercent = computeOperationalReadinessPercent(checks);
+  const localVerdict = verdictFromPassed(!hardFailure);
+  // When CLI E2E (or post-sync steps) failed, show step-derived readiness — persisted
+  // slices can report 100% ICC/PDS/DTS while runtime verdict is FAILED (422.0-v1).
+  const operationalReadinessPercent = hardFailure
+    ? localPercent
+    : typeof persistedReadinessPercent === 'number'
+      ? persistedReadinessPercent
+      : localPercent;
+  const verdict = hardFailure
+    ? localVerdict
+    : typeof persistedOperationsVerdict === 'string' && persistedOperationsVerdict.trim()
+      ? persistedOperationsVerdict.trim()
+      : localVerdict;
+  const details = groupOperationsDetails(checks);
+
+  let warnings = [];
+  try {
+    const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(systemKey, options);
+    warnings = await fetchCrossPillarWarnings(systemKey, authConfig, dataplaneUrl);
+  } catch {
+    warnings = [];
+  }
+
+  const certification =
+    lifecycleCertification && lifecycleCertification.level
+      ? {
+        level: lifecycleCertification.level,
+        status: lifecycleCertification.status || 'NOT_CERTIFIED'
+      }
+      : {
+        level: verdict === VERDICT.VERIFIED ? 'BRONZE' : 'NONE',
+        status: verdict === VERDICT.VERIFIED ? 'TECHNICALLY_READY' : 'NOT_CERTIFIED'
+      };
+
+  return {
+    systemKey,
+    command: 'verify-operations',
+    verdict,
+    operationalReadinessPercent,
+    readinessMetrics: readinessMetrics || null,
+    certification,
+    warnings,
+    details,
+    stepResults
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {Promise<void>}
+ */
+async function assertIntegrationExternalSystem(systemKey) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'verify-operations applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {Object} stepResults
+ * @param {boolean} hardFailure
+ * @returns {Promise<Object>}
+ */
+async function loadPersistedOperationsMetrics(
+  systemKey,
+  options,
+  stepResults,
+  hardFailure,
+  stoppedEarly
+) {
+  const empty = {
+    persistedReadinessPercent: null,
+    persistedOperationsVerdict: null,
+    readinessMetrics: null,
+    lifecycleCertification: null
+  };
+  if (options.persist === false) {
+    return empty;
+  }
+  // Persist after upload/sync when integration or E2E ran — partial evidence for Overview (425.9).
+  // Skip only when we stopped before post-sync steps (validate/unit hard fail without --continue).
+  if (stoppedEarly) {
+    return empty;
+  }
+
+  return runWithVerifyStepProgress(
+    'Saving operations results',
+    async() => {
+      await persistOperationsForSystem(systemKey, options, stepResults);
+      try {
+        const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(systemKey, options);
+        const report = await getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, {
+          details: true
+        });
+        return {
+          persistedReadinessPercent:
+            typeof report?.operations?.operationalReadinessPercent === 'number'
+              ? report.operations.operationalReadinessPercent
+              : null,
+          persistedOperationsVerdict:
+            typeof report?.operations?.verdict === 'string' ? report.operations.verdict : null,
+          readinessMetrics: extractReadinessMetricsFromLifecycleReport(report),
+          lifecycleCertification: report?.certification || null
+        };
+      } catch {
+        return empty;
+      }
+    },
+    options
+  );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runVerifyOperationsForExternalSystem(systemKey, options = {}) {
+  await assertIntegrationExternalSystem(systemKey);
+
+  const { stepResults, hardFailure, stoppedEarly } = await runOperationsVerifySteps(
+    systemKey,
+    options
+  );
+  const checks = buildOperationsChecksFromSteps(stepResults);
+  const persisted = await loadPersistedOperationsMetrics(
+    systemKey,
+    options,
+    stepResults,
+    hardFailure,
+    stoppedEarly
+  );
+
+  return buildOperationsResult({
+    systemKey,
+    stepResults,
+    checks,
+    hardFailure,
+    options,
+    ...persisted
+  });
+}
+
+module.exports = {
+  runVerifyOperationsForExternalSystem,
+  groupOperationsDetails,
+  fetchCrossPillarWarnings,
+  buildOperationsResult,
+  assertIntegrationExternalSystem,
+  loadPersistedOperationsMetrics
+};

package/lib/commands/verify-operations-persist.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Persist operations pillar to dataplane lifecycle (plan 150.0 / 419.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveExternalIntegrationContext } = require('./test-e2e-external');
+const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
+const { postValidationRun } = require('../api/validation-run.api');
+const { buildExternalDataSourceValidationRequest } = require('../utils/validation-run-request');
+
+/**
+ * Optional unit rollup stored in operations.details.reliability.unit.
+ * @param {Object} stepResults
+ * @returns {Object|undefined}
+ */
+function buildUnitTestSummary(stepResults) {
+  if (!stepResults || stepResults.unit !== true) {
+    return undefined;
+  }
+  return { passed: 1, failed: 0, skipped: 0 };
+}
+
+/**
+ * POST validation/run runType=operations for each active datasource (persists resultOperations).
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {Object} stepResults
+ * @returns {Promise<{ persisted: number }>}
+ */
+async function persistOperationsForSystem(systemKey, options, stepResults) {
+  const { systemKey: resolvedKey, keys } = resolveExternalIntegrationContext(systemKey);
+  if (keys.length === 0) {
+    return { persisted: 0 };
+  }
+
+  const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(systemKey, options);
+
+  const timeoutMs = parseInt(String(options.timeout || '120000'), 10) || 120000;
+  const unitTestSummary = buildUnitTestSummary(stepResults);
+  let persisted = 0;
+
+  for (const dsKey of keys) {
+    const body = buildExternalDataSourceValidationRequest({
+      systemKey: resolvedKey,
+      datasourceKey: dsKey,
+      runType: 'operations'
+    });
+    if (unitTestSummary) {
+      body.unitTestSummary = unitTestSummary;
+    }
+
+    const res = await postValidationRun(dataplaneUrl, authConfig, body, { timeoutMs });
+    if (!res || res.success === false) {
+      const msg =
+        (res &&
+          res.error &&
+          (res.error.formattedError || res.error.error || res.error.message)) ||
+        res?.formattedError ||
+        'Operations lifecycle persist failed';
+      throw new Error(`${dsKey}: ${msg}`);
+    }
+    persisted += 1;
+  }
+
+  return { persisted };
+}
+
+module.exports = {
+  persistOperationsForSystem,
+  buildUnitTestSummary
+};