@aifabrix/builder 2.45.5 → 2.46.0

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

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview governance generate — dataplane POST generate per datasource (424.0).
+ */
+
+'use strict';
+
+const { generateDatasourceGovernancePack } = require('../api/governance-scenario-pack.api');
+const {
+  buildSubjectsFromOptions,
+  resolveGovernanceIntegrationContext
+} = require('./governance-cli-shared');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceGenerateForExternalSystem(systemKey, options = {}) {
+  const subjects = buildSubjectsFromOptions(options);
+  if (subjects.length === 0) {
+    throw new Error(
+      'At least one --subject-user-id or --subject-email is required for governance generate'
+    );
+  }
+
+  const { resolvedKey, keys, authConfig, dataplaneUrl } =
+    await resolveGovernanceIntegrationContext(systemKey, options);
+
+  const profile = (options.certificationProfile || 'bronze').trim().toLowerCase();
+  const maxSamples = Number(options.maxSamplesPerPartition) || 25;
+
+  const results = await runWithVerifyStepProgress(
+    'Generating governance scenario packs',
+    async progress => {
+      const rows = [];
+      for (let index = 0; index < keys.length; index += 1) {
+        const dsKey = keys[index];
+        if (typeof progress.setLabel === 'function') {
+          progress.setLabel(`Generating pack: ${dsKey} (${index + 1}/${keys.length})`);
+        }
+        const row = await generateDatasourceGovernancePack(
+          dataplaneUrl,
+          authConfig,
+          dsKey,
+          {
+            certificationProfile: profile,
+            subjects,
+            systemKey: resolvedKey,
+            maxSamplesPerPartition: maxSamples
+          }
+        );
+        rows.push({ datasourceKey: dsKey, ...row });
+      }
+      return rows;
+    },
+    options
+  );
+
+  return {
+    systemKey: resolvedKey,
+    command: 'governance generate',
+    generated: results.length,
+    results
+  };
+}
+
+module.exports = {
+  runGovernanceGenerateForExternalSystem
+};

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

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview governance upload — push integration/<systemKey>/scenarios/*.yaml (424.0).
+ */
+
+'use strict';
+
+const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+const { resolveGovernanceIntegrationContext } = require('./governance-cli-shared');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceUploadForExternalSystem(systemKey, options = {}) {
+  const { resolvedKey, authConfig, dataplaneUrl } = await resolveGovernanceIntegrationContext(
+    systemKey,
+    options
+  );
+  const uploaded = await uploadGovernanceScenarioPacks(
+    resolvedKey,
+    dataplaneUrl,
+    authConfig,
+    { silent: options.json === true }
+  );
+  return {
+    systemKey: resolvedKey,
+    command: 'governance upload',
+    uploaded
+  };
+}
+
+module.exports = {
+  runGovernanceUploadForExternalSystem
+};

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

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

package/lib/commands/governance.js

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Integration validation scenario packs — governance command family (424.0).
+ */
+
+'use strict';
+
+const {
+  collectString,
+  governanceGenerateHandler,
+  governanceVerifyHandler,
+  governanceUploadHandler,
+  governanceDownloadHandler
+} = require('./governance-command-action');
+const {
+  GOVERNANCE_GENERATE_HELP_AFTER,
+  GOVERNANCE_VERIFY_HELP_AFTER,
+  GOVERNANCE_UPLOAD_HELP_AFTER,
+  GOVERNANCE_DOWNLOAD_HELP_AFTER,
+  GOVERNANCE_PARENT_HELP_AFTER
+} = require('../cli/setup-certification.help');
+
+const SHARED_OPTS = [
+  ['-e, --env <env>', 'Environment: dev, tst, or pro', 'dev'],
+  ['--no-sync', 'Skip publishing local integration files before dataplane calls'],
+  [
+    '--force',
+    'With default sync, pass force to upload (same as aifabrix upload --force)'
+  ]
+];
+
+/**
+ * @param {import('commander').Command} cmd
+ */
+function applySharedGovernanceOpts(cmd) {
+  for (const [flags, desc, defaultValue] of SHARED_OPTS) {
+    cmd.option(flags, desc, defaultValue);
+  }
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceGenerate(governance) {
+  const cmd = governance
+    .command('generate <systemKey>')
+    .description('Generate integration validation scenario packs on the dataplane')
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile (bronze, silver, gold, …)',
+      'bronze'
+    )
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for generated scenarios (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--max-samples-per-partition <n>',
+      'Max keys per mustInclude/mustExclude partition',
+      '25'
+    )
+    .option('-v, --verbose', 'Verbose output')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_GENERATE_HELP_AFTER)
+    .action(governanceGenerateHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceVerify(governance) {
+  const cmd = governance
+    .command('verify <systemKey>')
+    .description('Run persisted scenario packs (governance:evaluate)')
+    .option(
+      '--pack <path>',
+      'Authoring override: local scenario pack YAML instead of dataplane active pack'
+    )
+    .option('-a, --app <path>', 'Integration folder override (with --pack)')
+    .option('--scenario <id>', 'Scenario subset when using --pack (repeatable)', collectString, [])
+    .option('-v, --verbose', 'Per-datasource breakdown')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_VERIFY_HELP_AFTER)
+    .action(governanceVerifyHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceUpload(governance) {
+  const cmd = governance
+    .command('upload <systemKey>')
+    .description('Upload integration/<systemKey>/scenarios/*.yaml to the dataplane')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_UPLOAD_HELP_AFTER)
+    .action(governanceUploadHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} governance
+ */
+function registerGovernanceDownload(governance) {
+  const cmd = governance
+    .command('download <systemKey>')
+    .description('Download active packs to integration/<systemKey>/scenarios/')
+    .option('--json', 'Machine-readable envelope')
+    .addHelpText('after', GOVERNANCE_DOWNLOAD_HELP_AFTER)
+    .action(governanceDownloadHandler);
+  applySharedGovernanceOpts(cmd);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupGovernanceCommands(program) {
+  const governance = program
+    .command('governance')
+    .description(
+      'Integration validation scenario packs (generate, verify, download, upload)'
+    )
+    .addHelpText('after', GOVERNANCE_PARENT_HELP_AFTER);
+
+  applySharedGovernanceOpts(governance);
+
+  registerGovernanceGenerate(governance);
+  registerGovernanceVerify(governance);
+  registerGovernanceUpload(governance);
+  registerGovernanceDownload(governance);
+}
+
+module.exports = {
+  setupGovernanceCommands,
+  collectString
+};

package/lib/commands/lifecycle-command-action.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview CLI action for `aifabrix lifecycle` certification report (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 { runLifecycleForExternalSystem } = require('./lifecycle-external');
+const { displayLifecycleReportTTY } = require('../lifecycle/report-display');
+const { VERDICT } = require('../lifecycle/product-model');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const { lifecycleHasGovernanceSubjects } = require('../lifecycle/lifecycle-governance-options');
+
+/**
+ * @param {Object} options
+ * @param {import('commander').Command} [cmd]
+ * @returns {Object}
+ */
+function normalizeLifecycleCliOptions(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'),
+    run: options.run === true || has('--run'),
+    noSync: cliOptsSkipSync(options, cmd),
+    force: options.force === true || has('--force'),
+    subjectUserId: options.subjectUserId || [],
+    subjectEmail: options.subjectEmail || [],
+    certificationProfile: options.certificationProfile || 'bronze'
+  };
+}
+
+/**
+ * @param {Object} report
+ * @returns {string}
+ */
+function lifecycleVerdictFromReport(report) {
+  const ops = report.operations?.verdict;
+  const trust = report.trust?.verdict;
+  const gov = report.governance?.verdict;
+  if (ops === VERDICT.FAILED || trust === VERDICT.FAILED || gov === VERDICT.FAILED) {
+    return VERDICT.FAILED;
+  }
+  if (
+    ops === VERDICT.VERIFIED &&
+    trust === VERDICT.VERIFIED &&
+    gov === VERDICT.VERIFIED
+  ) {
+    return VERDICT.VERIFIED;
+  }
+  return VERDICT.NOT_VERIFIED;
+}
+
+async function runLifecycleCommandAction(appName, options, cmd) {
+  const opts = normalizeLifecycleCliOptions(options, cmd);
+  if (lifecycleHasGovernanceSubjects(opts) && !opts.run) {
+    throw new Error(
+      '--subject-user-id and --subject-email require --run on lifecycle (use verify-governance for governance-only)'
+    );
+  }
+  const result = await runLifecycleForExternalSystem(appName, opts);
+  const report = result.report;
+
+  if (opts.json) {
+    const envelope = {
+      systemKey: result.systemKey,
+      command: 'lifecycle',
+      certification: report.certification,
+      operations: report.operations,
+      trust: report.trust,
+      governance: report.governance,
+      recommendations: report.recommendations,
+      warnings: report.warnings,
+      openApiPublished: result.openApiPublished === true,
+      certificationProgress: result.certificationProgress ?? null,
+      stepsRun: result.stepsRun
+    };
+    if (opts.verbose) {
+      envelope.datasources = report.datasources;
+    }
+    logger.log(JSON.stringify(envelope, null, 2));
+  } else {
+    displayLifecycleReportTTY(result.systemKey, report, {
+      details: opts.verbose,
+      openApiPublished: result.openApiPublished === true,
+      certificationProgress: result.certificationProgress ?? null,
+      dataplaneUrl: result.dataplaneUrl ?? null,
+      dataplaneUiBaseUrl: result.dataplaneUiBaseUrl ?? null
+    });
+  }
+
+  const pillarVerdict = lifecycleVerdictFromReport(report);
+  const exitCode =
+    pillarVerdict === VERDICT.VERIFIED
+      ? 0
+      : exitCodeFromVerdict(pillarVerdict, { partial: pillarVerdict === VERDICT.NOT_VERIFIED });
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+async function lifecycleCommandHandler(appName, options, cmd) {
+  try {
+    await runLifecycleCommandAction(appName, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'lifecycle');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  normalizeLifecycleCliOptions,
+  runLifecycleCommandAction,
+  lifecycleCommandHandler,
+  lifecycleVerdictFromReport
+};

package/lib/commands/lifecycle-external.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview lifecycle certification report — GET default, --run optional (plan 150.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getSystemLifecycleReport, runSystemLifecycle } = require('../api/lifecycle.api');
+const { setupIntegrationTestAuth } = require('../external-system/test-auth');
+const { getConfig } = require('../core/config');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { syncLocalIfRequested } = require('./test-e2e-external');
+const { runVerifyOperationsForExternalSystem } = require('./verify-operations-external');
+const { runVerifyTrustForExternalSystem } = require('./verify-trust-external');
+const { runGovernanceVerifyForExternalSystem } = require('./governance-verify-external');
+const { VERDICT } = require('../lifecycle/product-model');
+const { buildCertificationProgress } = require('../lifecycle/certification-progress');
+const { resolveOpenApiPublished } = require('../lifecycle/open-api-published');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+const { resolveDataplaneUiBaseUrl } = require('../lifecycle/dataplane-ui-url');
+const {
+  lifecycleHasGovernanceSubjects,
+  lifecycleGovernanceNeedsWork,
+  buildGovernanceOptsFromLifecycle
+} = require('../lifecycle/lifecycle-governance-options');
+
+/**
+ * @async
+ * @param {string|null|undefined} dataplaneUrl
+ * @returns {Promise<string|null>}
+ */
+async function resolveLifecycleDataplaneUiBaseUrl(dataplaneUrl) {
+  try {
+    return await resolveDataplaneUiBaseUrl(dataplaneUrl);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveLifecycleAuth(systemKey, options) {
+  if (!cliOptsSkipSync(options) && options.run === true) {
+    options.lifecycleProgress?.setLabel?.('Checking config on dataplane');
+    const uploadCtx = await syncLocalIfRequested(systemKey, {
+      ...options,
+      suppressPipelineSpinner: true
+    });
+    if (uploadCtx) {
+      options.lifecycleProgress?.setLabel?.('Processing');
+      return { authConfig: uploadCtx.authConfig, dataplaneUrl: uploadCtx.dataplaneUrl };
+    }
+  }
+  const configObj = await getConfig();
+  return setupIntegrationTestAuth(systemKey, { environment: options.env }, configObj);
+}
+
+/**
+ * Generate + verify governance when lifecycle --run includes subject selectors.
+ * @async
+ * @param {string} systemKey
+ * @param {Object} report
+ * @param {Object} authConfig
+ * @param {string} dataplaneUrl
+ * @param {Object} options
+ */
+async function runLifecycleGovernanceCombinedIfNeeded(
+  systemKey,
+  report,
+  authConfig,
+  dataplaneUrl,
+  options
+) {
+  if (!lifecycleHasGovernanceSubjects(options)) {
+    return;
+  }
+  if (!lifecycleGovernanceNeedsWork(report)) {
+    return;
+  }
+  const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
+  await runVerifyGovernanceCombined(
+    systemKey,
+    buildGovernanceOptsFromLifecycle(options, { authConfig, dataplaneUrl })
+  );
+}
+
+/**
+ * Run missing verify pillars locally when lifecycle/run API unavailable.
+ * @async
+ * @param {string} systemKey
+ * @param {Object} report
+ * @param {Object} options
+ */
+async function runMissingVerifyStepsLocally(systemKey, report, options) {
+  const runOpts = { ...options, noSync: true };
+  if (report.operations?.verdict !== VERDICT.VERIFIED) {
+    await runVerifyOperationsForExternalSystem(systemKey, runOpts);
+  }
+  if (report.trust?.verdict !== VERDICT.VERIFIED) {
+    await runVerifyTrustForExternalSystem(systemKey, runOpts);
+  }
+  if (report.governance?.verdict !== VERDICT.VERIFIED) {
+    if (lifecycleHasGovernanceSubjects(options)) {
+      const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
+      await runVerifyGovernanceCombined(
+        systemKey,
+        buildGovernanceOptsFromLifecycle(options, {
+          authConfig: options.authConfig,
+          dataplaneUrl: options.dataplaneUrl
+        })
+      );
+    } else {
+      await runGovernanceVerifyForExternalSystem(systemKey, runOpts);
+    }
+  }
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} report
+ * @param {string} dataplaneUrl
+ * @param {string|null} dataplaneUiBaseUrl
+ * @param {Object} authConfig
+ * @param {Object} [extra]
+ * @returns {Promise<Object>}
+ */
+async function buildLifecycleResult(
+  systemKey,
+  report,
+  dataplaneUrl,
+  dataplaneUiBaseUrl,
+  authConfig,
+  extra = {}
+) {
+  const openApiPublished = await resolveOpenApiPublished(dataplaneUrl, authConfig, systemKey);
+  return {
+    systemKey,
+    command: 'lifecycle',
+    report,
+    dataplaneUrl,
+    dataplaneUiBaseUrl,
+    openApiPublished,
+    certificationProgress: buildCertificationProgress(report, { openApiPublished }),
+    ...extra
+  };
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} authConfig
+ * @param {string} dataplaneUrl
+ * @param {string|null} dataplaneUiBaseUrl
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runLifecycleViaDataplaneApi(
+  systemKey,
+  authConfig,
+  dataplaneUrl,
+  dataplaneUiBaseUrl,
+  options
+) {
+  if (lifecycleHasGovernanceSubjects(options)) {
+    const preReport = await getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, {
+      details: options.verbose === true
+    });
+    await runLifecycleGovernanceCombinedIfNeeded(
+      systemKey,
+      preReport,
+      authConfig,
+      dataplaneUrl,
+      options
+    );
+  }
+  const runRes = await runSystemLifecycle(dataplaneUrl, authConfig, systemKey, {});
+  return buildLifecycleResult(
+    systemKey,
+    runRes.report,
+    dataplaneUrl,
+    dataplaneUiBaseUrl,
+    authConfig,
+    { stepsRun: runRes.stepsRun || [], source: 'api' }
+  );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function executeLifecycleWork(systemKey, options = {}) {
+  const { authConfig, dataplaneUrl } = await resolveLifecycleAuth(systemKey, options);
+  const dataplaneUiBaseUrl = await resolveLifecycleDataplaneUiBaseUrl(dataplaneUrl);
+
+  if (options.run === true) {
+    try {
+      return await runLifecycleViaDataplaneApi(
+        systemKey,
+        authConfig,
+        dataplaneUrl,
+        dataplaneUiBaseUrl,
+        options
+      );
+    } catch {
+      const preReport = await getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, {
+        details: options.verbose === true
+      });
+      await runMissingVerifyStepsLocally(systemKey, preReport, {
+        ...options,
+        authConfig,
+        dataplaneUrl
+      });
+    }
+  }
+
+  const report = await getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, {
+    details: options.verbose === true
+  });
+  return buildLifecycleResult(
+    systemKey,
+    report,
+    dataplaneUrl,
+    dataplaneUiBaseUrl,
+    authConfig,
+    { source: options.run ? 'local-fallback' : 'api' }
+  );
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runLifecycleForExternalSystem(systemKey, options = {}) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(systemKey).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'lifecycle applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+
+  if (options.run === true) {
+    return runWithVerifyStepProgress(
+      'Processing',
+      async(progress) => executeLifecycleWork(systemKey, { ...options, lifecycleProgress: progress }),
+      { json: options.json === true }
+    );
+  }
+
+  return executeLifecycleWork(systemKey, options);
+}
+
+module.exports = {
+  runLifecycleForExternalSystem,
+  runMissingVerifyStepsLocally,
+  runLifecycleGovernanceCombinedIfNeeded,
+  resolveLifecycleAuth
+};