@aifabrix/builder 2.45.5 → 2.46.0

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

package/lib/commands/verify-operations-step-plan.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Step plan for verify-operations (plan 150.0).
+ */
+
+'use strict';
+
+const { validateExternalSystemComplete } = require('../validation/validate');
+const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
+const { runTestE2EForExternalSystem } = require('./test-e2e-external');
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {{ beforeSync: Array, afterSync: Array, e2e: Object }}
+ */
+function buildOperationsVerifyStepPlan(systemKey, options) {
+  return {
+    beforeSync: [
+      {
+        key: 'validation',
+        run: () => validateExternalSystemComplete(systemKey, { type: 'external' }),
+        ok: (result) => result.valid === true
+      },
+      {
+        key: 'unit',
+        run: () => testExternalSystem(systemKey, { verbose: false }),
+        ok: (result) => result.valid === true
+      }
+    ],
+    afterSync: [
+      {
+        key: 'integration',
+        run: () =>
+          testExternalSystemIntegration(systemKey, {
+            environment: options.env,
+            noSync: true,
+            verbose: false,
+            debug: options.debug === true
+          }),
+        ok: (result) => result.success === true
+      }
+    ],
+    e2e: {
+      key: 'e2e',
+      run: (progress) =>
+        runTestE2EForExternalSystem(systemKey, {
+          env: options.env,
+          noSync: true,
+          verbose: false,
+          debug: options.debug === true,
+          async: options.async !== false,
+          authConfig: options.authConfig,
+          dataplaneUrl: options.dataplaneUrl,
+          silentResolve: options.silentResolve === true,
+          quietPollUi: true,
+          onDatasourceProgress: progress?.setLabel
+            ? ({ key, index, total }) =>
+              progress.setLabel(`Running E2E: ${key} (${index + 1}/${total})`)
+            : undefined
+        }),
+      ok: (result) => result.success === true
+    }
+  };
+}
+
+module.exports = {
+  buildOperationsVerifyStepPlan
+};

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

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview verify-operations step runners (plan 150.0).
+ */
+
+'use strict';
+
+const { syncLocalIfRequested } = require('./test-e2e-external');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { buildOperationsVerifyStepPlan } = require('./verify-operations-step-plan');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+
+const STEP_PROGRESS = {
+  validation: 'Validating local integration',
+  unit: 'Running unit tests',
+  integration: 'Running integration tests on dataplane',
+  e2e: 'Running E2E tests'
+};
+
+/**
+ * @param {Object} options
+ * @param {Object} uploadCtx
+ */
+function attachUploadAuthToOptions(options, uploadCtx) {
+  if (!uploadCtx?.authConfig || !uploadCtx?.dataplaneUrl) {
+    return;
+  }
+  options.authConfig = uploadCtx.authConfig;
+  options.dataplaneUrl = uploadCtx.dataplaneUrl;
+  options.silentResolve = true;
+}
+
+/**
+ * @param {Function} runner
+ * @param {Function} isSuccess
+ * @param {Object} options
+ * @returns {Promise<boolean>}
+ */
+async function runVerifyStep(runner, isSuccess) {
+  const outcome = await runner();
+  return isSuccess(outcome);
+}
+
+/**
+ * @param {Object} stepResults
+ * @param {string} key
+ * @param {boolean} passed
+ * @param {boolean} continueOnFail
+ * @returns {boolean} false when the verify flow should stop early
+ */
+function recordVerifyStep(stepResults, key, passed, continueOnFail) {
+  stepResults[key] = passed;
+  return passed || continueOnFail;
+}
+
+/**
+ * @param {Object} stepResults
+ * @param {Object} step
+ * @param {boolean} continueOnFail
+ * @param {Object} options
+ * @returns {Promise<boolean>}
+ */
+async function runTrackedVerifyStep(stepResults, step, continueOnFail, options) {
+  const label = STEP_PROGRESS[step.key] || step.key;
+  const passed = await runWithVerifyStepProgress(
+    label,
+    async(progress) => runVerifyStep(() => step.run(progress), step.ok),
+    options
+  );
+  return recordVerifyStep(stepResults, step.key, passed, continueOnFail);
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ stepResults: Object, hardFailure: boolean, stoppedEarly: boolean }>}
+ */
+async function runOperationsVerifySteps(systemKey, options) {
+  const stepResults = { validation: false, unit: false, integration: false, e2e: false };
+  const continueOnFail = options.continue === true;
+  const plan = buildOperationsVerifyStepPlan(systemKey, options);
+
+  for (const step of plan.beforeSync) {
+    if (!(await runTrackedVerifyStep(stepResults, step, continueOnFail, options))) {
+      return { stepResults, hardFailure: true, stoppedEarly: true };
+    }
+  }
+
+  if (!cliOptsSkipSync(options)) {
+    const uploadCtx = await syncLocalIfRequested(systemKey, options);
+    attachUploadAuthToOptions(options, uploadCtx);
+  }
+
+  for (const step of plan.afterSync) {
+    if (!(await runTrackedVerifyStep(stepResults, step, continueOnFail, options))) {
+      return { stepResults, hardFailure: true, stoppedEarly: true };
+    }
+  }
+
+  const e2eLabel = STEP_PROGRESS.e2e;
+  stepResults.e2e = await runWithVerifyStepProgress(
+    e2eLabel,
+    async(progress) => runVerifyStep(() => plan.e2e.run(progress), plan.e2e.ok),
+    options
+  );
+  return { stepResults, hardFailure: !stepResults.e2e, stoppedEarly: false };
+}
+
+module.exports = {
+  runOperationsVerifySteps
+};