@aifabrix/builder 2.45.0 → 2.46.0

package/lib/commands/governance-cli-shared.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Shared helpers for governance * CLI commands (424.0).
+ */
+
+'use strict';
+
+const {
+  resolveExternalIntegrationContext,
+  syncLocalIfRequested
+} = require('./test-e2e-external');
+const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+const { formatNetworkError } = require('../utils/api-error-handler');
+
+/**
+ * @param {Object} options
+ * @param {string[]} [options.subjectUserIds]
+ * @param {string[]} [options.subjectEmails]
+ * @returns {Array<{ subjectUserId?: string, subjectEmail?: string }>}
+ */
+function buildSubjectsFromOptions(options) {
+  const subjects = [];
+  const userIds = options.subjectUserIds || [];
+  const emails = options.subjectEmails || [];
+  for (const subjectUserId of userIds) {
+    const id = String(subjectUserId || '').trim();
+    if (id) subjects.push({ subjectUserId: id });
+  }
+  for (const subjectEmail of emails) {
+    const email = String(subjectEmail || '').trim();
+    if (email) subjects.push({ subjectEmail: email });
+  }
+  return subjects;
+}
+
+/**
+ * Fail fast when dataplane health is unreachable (avoids misleading API validation errors).
+ * @async
+ * @param {string} dataplaneUrl
+ * @returns {Promise<void>}
+ */
+async function assertDataplaneReachable(dataplaneUrl) {
+  const base = String(dataplaneUrl || '').replace(/\/$/, '');
+  const snapshot = await fetchDataplaneGeneralHealth(base, { timeoutMs: 8000 });
+  if (snapshot) {
+    return;
+  }
+  const endpointUrl = `${base}/api/v1/health`;
+  const err = new Error(`Cannot reach dataplane at ${base}`);
+  err.network = true;
+  err.serviceLabel = 'dataplane';
+  err.endpointUrl = endpointUrl;
+  err.formatted = formatNetworkError(err.message, {
+    endpointUrl,
+    serviceLabel: 'dataplane'
+  });
+  throw err;
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ resolvedKey: string, keys: string[], authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveGovernanceIntegrationContext(systemKey, options) {
+  const { systemKey: resolvedKey, keys } = resolveExternalIntegrationContext(systemKey);
+  if (options.authConfig && options.dataplaneUrl) {
+    return {
+      resolvedKey,
+      keys,
+      authConfig: options.authConfig,
+      dataplaneUrl: options.dataplaneUrl
+    };
+  }
+  if (!cliOptsSkipSync(options)) {
+    const uploadCtx = await syncLocalIfRequested(resolvedKey, options);
+    if (uploadCtx?.authConfig && uploadCtx?.dataplaneUrl) {
+      options.authConfig = uploadCtx.authConfig;
+      options.dataplaneUrl = uploadCtx.dataplaneUrl;
+      options.silentResolve = true;
+    }
+  }
+  const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(resolvedKey, options);
+  await assertDataplaneReachable(dataplaneUrl);
+  return { resolvedKey, keys, authConfig, dataplaneUrl };
+}
+
+module.exports = {
+  buildSubjectsFromOptions,
+  assertDataplaneReachable,
+  resolveGovernanceIntegrationContext
+};

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

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview CLI actions for `aifabrix governance *` (424.0).
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { runGovernanceGenerateForExternalSystem } = require('./governance-generate-external');
+const { runGovernanceVerifyForExternalSystem } = require('./governance-verify-external');
+const { runGovernanceUploadForExternalSystem } = require('./governance-upload-external');
+const { runGovernanceDownloadForExternalSystem } = require('./governance-download-external');
+const { displayVerifyGovernanceTTY } = require('../lifecycle/report-display');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+
+/**
+ * Commander repeatable-option collector. Splits comma-separated values so both
+ * `--flag a --flag b` and `--flag a,b` work.
+ * @param {string} value
+ * @param {string[]} previous
+ * @returns {string[]}
+ */
+function collectString(value, previous) {
+  const parts = String(value)
+    .split(',')
+    .map(entry => entry.trim())
+    .filter(Boolean);
+  return previous.concat(parts.length > 0 ? parts : [String(value).trim()].filter(Boolean));
+}
+
+function normalizeGovernanceOptions(options, cmd) {
+  const parent = cmd && cmd.parent ? cmd.parent.opts() : {};
+  return {
+    env: options.env || parent.env || 'dev',
+    verbose: options.verbose === true || parent.verbose === true,
+    noSync: options.noSync === true || parent.noSync === true,
+    force: options.force === true || parent.force === true,
+    json: options.json === true || parent.json === true,
+    pack: options.pack,
+    app: options.app,
+    scenarioIds: options.scenario || [],
+    certificationProfile: options.certificationProfile || 'bronze',
+    subjectUserIds: options.subjectUserId || [],
+    subjectEmails: options.subjectEmail || [],
+    maxSamplesPerPartition: options.maxSamplesPerPartition
+  };
+}
+
+async function governanceGenerateHandler(systemKey, options, cmd) {
+  try {
+    const opts = normalizeGovernanceOptions(options, cmd);
+    const result = await runGovernanceGenerateForExternalSystem(systemKey, opts);
+    if (opts.json) {
+      logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+      return;
+    }
+    for (const row of result.results || []) {
+      logger.log(
+        formatSuccessLine(
+          `${row.datasourceKey}: pack v${row.packVersion} (${row.scenarioCount} scenarios)`
+        )
+      );
+    }
+  } catch (error) {
+    handleCommandError(error, 'governance generate');
+    process.exit(3);
+  }
+}
+
+async function governanceVerifyHandler(systemKey, options, cmd) {
+  try {
+    const opts = normalizeGovernanceOptions(options, cmd);
+    const result = await runGovernanceVerifyForExternalSystem(systemKey, opts);
+    if (opts.json) {
+      logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+    } else {
+      displayVerifyGovernanceTTY(result.systemKey, result, { details: opts.verbose });
+    }
+    const exitCode = exitCodeFromVerdict(result.verdict);
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  } catch (error) {
+    handleCommandError(error, 'governance verify');
+    process.exit(3);
+  }
+}
+
+async function governanceUploadHandler(systemKey, options, cmd) {
+  try {
+    const opts = normalizeGovernanceOptions(options, cmd);
+    const result = await runGovernanceUploadForExternalSystem(systemKey, opts);
+    if (opts.json) {
+      logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+      return;
+    }
+    logger.log(formatSuccessLine(`Uploaded ${result.uploaded} scenario pack(s)`));
+  } catch (error) {
+    if (error.friendlyHint) {
+      logger.log(error.friendlyHint);
+    }
+    handleCommandError(error, 'governance upload');
+    process.exit(3);
+  }
+}
+
+async function governanceDownloadHandler(systemKey, options, cmd) {
+  try {
+    const opts = normalizeGovernanceOptions(options, cmd);
+    opts.noSync = true;
+    const result = await runGovernanceDownloadForExternalSystem(systemKey, opts);
+    if (opts.json) {
+      logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+      return;
+    }
+    logger.log(formatSuccessLine(`Downloaded ${result.written} scenario pack(s)`));
+  } catch (error) {
+    handleCommandError(error, 'governance download');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  collectString,
+  normalizeGovernanceOptions,
+  governanceGenerateHandler,
+  governanceVerifyHandler,
+  governanceUploadHandler,
+  governanceDownloadHandler
+};

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

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview governance download — pull packs to integration/<systemKey>/scenarios/ (424.0).
+ */
+
+'use strict';
+
+const { downloadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+const { resolveGovernanceIntegrationContext } = require('./governance-cli-shared');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runGovernanceDownloadForExternalSystem(systemKey, options = {}) {
+  const { resolvedKey, keys, authConfig, dataplaneUrl } =
+    await resolveGovernanceIntegrationContext(systemKey, options);
+  const written = await downloadGovernanceScenarioPacks(
+    resolvedKey,
+    keys,
+    dataplaneUrl,
+    authConfig
+  );
+  return {
+    systemKey: resolvedKey,
+    command: 'governance download',
+    written
+  };
+}
+
+module.exports = {
+  runGovernanceDownloadForExternalSystem
+};

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