@aifabrix/builder 2.45.5 → 2.46.0

package/lib/commands/upload-sidecar-followups.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Upload sidecar follow-ups (governance packs, certification sync).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { unwrapPublicationResult, isPublicationUnchanged } = require('../utils/external-system-readiness-core');
+const { logUploadReadinessSummary } = require('../utils/external-system-readiness-display');
+const { maybeSyncSystemCertificationFromDataplane } = require('../certification/sync-system-certification');
+const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
+const { isQuietMinimalSync } = require('../utils/upload-sync-options');
+
+/**
+ * Sidecar follow-ups that are independent of pipeline publish hash (scenario packs, cert sync).
+ * @param {Object} ctx
+ * @returns {Promise<void>}
+ */
+async function runUploadSidecarFollowups(ctx) {
+  const { systemKey, options, payload, dataplaneUrl, authConfig } = ctx;
+  const quietSidecar = isQuietMinimalSync(options);
+  const dsKeys = (payload.dataSources || []).map((ds) => ds && ds.key).filter(Boolean);
+  try {
+    const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+    await uploadGovernanceScenarioPacks(systemKey, dataplaneUrl, authConfig, { silent: quietSidecar });
+  } catch (err) {
+    if (!quietSidecar) {
+      logger.log(formatWarningLine(`Governance scenario upload skipped: ${err.message}`));
+    }
+  }
+  await maybeSyncSystemCertificationFromDataplane({
+    label: 'upload',
+    noCertSync: cliOptsSkipCertSync(options),
+    systemKey,
+    dataplaneUrl,
+    authConfig,
+    datasourceKeys: dsKeys,
+    silent: quietSidecar
+  });
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Function} maybeRunUploadProbe
+ * @returns {Promise<void>}
+ */
+async function handlePublicationAndFollowups(ctx, maybeRunUploadProbe) {
+  const {
+    systemKey,
+    options,
+    manifest,
+    payload,
+    environment,
+    dataplaneUrl,
+    authConfig,
+    rawRes
+  } = ctx;
+  const publication = unwrapPublicationResult(rawRes);
+  if (!publication) {
+    throw new Error(
+      'Unexpected response from dataplane upload: missing publication result (uploadId/system/datasources).'
+    );
+  }
+  if (isPublicationUnchanged(publication)) {
+    await runUploadSidecarFollowups({ systemKey, options, payload, dataplaneUrl, authConfig });
+    return;
+  }
+  logUploadReadinessSummary({
+    environment,
+    dataplaneUrl,
+    systemKey,
+    publication,
+    manifest,
+    minimal: !!options.minimal,
+    willProbe: !!options.probe
+  });
+  if (options.probe) {
+    await maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, options.probeTimeout);
+  }
+  await runUploadSidecarFollowups({ systemKey, options, payload, dataplaneUrl, authConfig });
+}
+
+module.exports = {
+  runUploadSidecarFollowups,
+  handlePublicationAndFollowups
+};

package/lib/commands/upload.js

@@ -21,7 +21,7 @@ const logger = require('../utils/logger');
 
 const SEP = chalk.gray('────────────────────────────────────────');
 const { resolveControllerUrl } = require('../utils/controller-url');
-const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
+const { getDeploymentAuth } = require('../utils/token-manager');
 const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
 const { getIntegrationPath } = require('../utils/paths');
 const { pushCredentialSecrets } = require('../utils/credential-secrets-env');
@@ -36,22 +36,24 @@ const { validateExternalSystemComplete } = require('../validation/validate');
 const { displayValidationResults } = require('../validation/validate-display');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const {
-  uploadApplicationViaPipeline,
   validatePipelineConfig,
   testSystemViaPipeline
 } = require('../api/pipeline.api');
+const { uploadApplicationViaPipelineWithAuthRetry } = require('../utils/pipeline-upload-auth-retry');
 const { formatApiError } = require('../utils/api-error-handler');
-const { logDataplanePipelineWarning } = require('../utils/dataplane-pipeline-warning');
-const { unwrapPublicationResult, unwrapApiData } = require('../utils/external-system-readiness-core');
+const { unwrapPublicationResult, unwrapApiData, isPublicationUnchanged } = require('../utils/external-system-readiness-core');
 const {
-  logUploadReadinessSummary,
   logServerValidationWarnings,
   logProbeRuntimeBlock
 } = require('../utils/external-system-readiness-display');
-const { maybeSyncSystemCertificationFromDataplane } = require('../certification/sync-system-certification');
-const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
 const { maybeSyncOpenApiFilesForMcp } = require('./repair-openapi-sync');
-const { assertDataplaneCliVersionCompatible } = require('../utils/dataplane-cli-version-gate');
+const { resolveUploadPublishContext } = require('./upload-publish-context');
+const { syncDeployJsonFromSources } = require('../external-system/sync-deploy-manifest');
+const { isQuietMinimalSync } = require('../utils/upload-sync-options');
+const {
+  runUploadSidecarFollowups,
+  handlePublicationAndFollowups
+} = require('./upload-sidecar-followups');
 
 /**
  * Validates system-key format (same as download).
@@ -73,13 +75,22 @@ function validateSystemKeyFormat(systemKey) {
  * @param {Object} manifest - Controller manifest from generateControllerManifest
  * @returns {Object} { version, application, dataSources, status: "draft" }
  */
-function buildUploadPayload(manifest) {
-  return {
+/**
+ * @param {Object} manifest - Controller manifest from generateControllerManifest
+ * @param {{ force?: boolean }} [opts]
+ * @returns {Object}
+ */
+function buildUploadPayload(manifest, opts = {}) {
+  const payload = {
     version: manifest.version || '1.0.0',
     application: manifest.system,
     dataSources: manifest.dataSources || [],
     status: 'draft'
   };
+  if (opts.force === true) {
+    payload.force = true;
+  }
+  return payload;
 }
 
 /**
@@ -113,11 +124,15 @@ async function resolveDataplaneAndAuth(systemKey, opts = {}) {
  * @param {Object} payload - { version, application, dataSources, status: "draft" }
  * @returns {Promise<Object>} Raw API response envelope
  */
-async function runUploadValidatePublish(dataplaneUrl, authConfig, payload) {
-  const res = await uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload);
+async function runUploadValidatePublish(dataplaneUrl, authConfig, payload, systemKey) {
+  const res = await uploadApplicationViaPipelineWithAuthRetry(
+    dataplaneUrl,
+    authConfig,
+    payload,
+    systemKey
+  );
   if (res?.success === false) {
-    const msg = formatApiError(res, dataplaneUrl);
-    throw new Error(msg);
+    throw new Error(formatApiError(res, dataplaneUrl));
   }
   return res;
 }
@@ -269,18 +284,22 @@ async function maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, probeTim
 
 /**
  * Local validation, manifest, payload, and configuration resolution.
- * Does not write *-deploy.json; run `aifabrix json <systemKey>` to regenerate the deployment manifest from sources.
+ * Regenerates integration/<systemKey>/<systemKey>-deploy.json from sources (same as `aifabrix json`).
  *
  * @param {string} systemKey
  * @param {{ dryRun?: boolean }} [_opts] - Reserved for callers (e.g. dry-run); manifest is always built from current disk files
  * @returns {Promise<{ manifest: Object, payload: Object }>}
  */
-async function buildValidatedUploadManifestPayload(systemKey, _opts = {}) {
+async function buildValidatedUploadManifestPayload(systemKey, opts = {}) {
+  const quiet = opts.minimal === true || opts.quiet === true;
   const validationResult = await validateExternalSystemComplete(systemKey, { type: 'external' });
   throwIfValidationFailed(validationResult);
-  logger.log(formatSuccessLine('Local validation passed'));
+  if (!quiet) {
+    logger.log(formatSuccessLine('Local validation passed'));
+  }
+  await syncDeployJsonFromSources(systemKey, { quiet });
   const manifest = await generateControllerManifest(systemKey, { type: 'external' });
-  const payload = buildUploadPayload(manifest);
+  const payload = buildUploadPayload(manifest, { force: opts.force === true });
   await resolvePayloadConfiguration(systemKey, payload);
   return { manifest, payload };
 }
@@ -311,58 +330,6 @@ async function logAndSyncLocalOpenApiForUpload(systemKey, manifest) {
   }
 }
 
-/**
- * @param {Object} ctx
- * @param {string} ctx.systemKey
- * @param {Object} ctx.options
- * @param {Object} ctx.manifest
- * @param {Object} ctx.payload
- * @param {string} ctx.environment
- * @param {string} ctx.dataplaneUrl
- * @param {Object} ctx.authConfig
- * @param {Object} ctx.rawRes
- * @returns {Promise<void>}
- */
-async function handlePublicationAndFollowups(ctx) {
-  const {
-    systemKey,
-    options,
-    manifest,
-    payload,
-    environment,
-    dataplaneUrl,
-    authConfig,
-    rawRes
-  } = ctx;
-  const publication = unwrapPublicationResult(rawRes);
-  if (!publication) {
-    throw new Error(
-      'Unexpected response from dataplane upload: missing publication result (uploadId/system/datasources).'
-    );
-  }
-  logUploadReadinessSummary({
-    environment,
-    dataplaneUrl,
-    systemKey,
-    publication,
-    manifest,
-    minimal: !!options.minimal,
-    willProbe: !!options.probe
-  });
-  if (options.probe) {
-    await maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, options.probeTimeout);
-  }
-  const dsKeys = (payload.dataSources || []).map((ds) => ds && ds.key).filter(Boolean);
-  await maybeSyncSystemCertificationFromDataplane({
-    label: 'upload',
-    noCertSync: cliOptsSkipCertSync(options),
-    systemKey,
-    dataplaneUrl,
-    authConfig,
-    datasourceKeys: dsKeys
-  });
-}
-
 /**
  * Upload path after dry-run check.
  * @param {string} systemKey
@@ -371,45 +338,55 @@ async function handlePublicationAndFollowups(ctx) {
  * @param {Object} payload
  */
 async function runUploadPublishAndSummary(systemKey, options, manifest, payload) {
-  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey, {
-    silent: options.silentResolve === true
-  });
-  requireBearerForDataplanePipeline(authConfig);
-  const controllerUrl = await resolveControllerUrl();
-  // Plan 142.0: gate dataplane API entrypoints by the dataplane-advertised minimum Builder CLI version.
-  await assertDataplaneCliVersionCompatible(dataplaneUrl, { controllerUrl });
-  logger.log('');
-  logger.log(sectionTitle('Target'));
-  logger.log(SEP);
-  logger.log(headerKeyValue('Environment:', environment));
-  logger.log(headerKeyValue('Dataplane:', dataplaneUrl));
-  logDataplanePipelineWarning();
-  if (options.verbose) {
-    await maybeRunVerboseServerValidation(dataplaneUrl, authConfig, payload);
+  const { dataplaneUrl, authConfig, environment } = await resolveUploadPublishContext(
+    resolveDataplaneAndAuth,
+    maybeRunVerboseServerValidation,
+    systemKey,
+    options,
+    payload
+  );
+  const rawRes = await runWithUploadPipelineSpinner(
+    async() => runUploadValidatePublish(dataplaneUrl, authConfig, payload, systemKey),
+    {
+      systemKey,
+      json: options.json === true,
+      syncMode: options.syncMode === true,
+      suppressPipelineSpinner: options.suppressPipelineSpinner === true
+    }
+  );
+  const publication = unwrapPublicationResult(rawRes);
+  if (isPublicationUnchanged(publication)) {
+    if (!isQuietMinimalSync(options)) {
+      logger.log(formatSuccessLine('Config unchanged on dataplane — upload skipped.'));
+    }
+    await runUploadSidecarFollowups({
+      systemKey,
+      options,
+      payload,
+      dataplaneUrl,
+      authConfig
+    });
+    return { dataplaneUrl, authConfig, environment, uploadSkipped: true };
   }
+
   await pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload, {
     json: options.json === true
   });
-
-  const rawRes = await runWithUploadPipelineSpinner(
-    async() => {
-      const res = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
-      await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
-      return res;
+  await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+  await handlePublicationAndFollowups(
+    {
+      systemKey,
+      options,
+      manifest,
+      payload,
+      environment,
+      dataplaneUrl,
+      authConfig,
+      rawRes
     },
-    { systemKey, json: options.json === true }
+    maybeRunUploadProbe
   );
-  await handlePublicationAndFollowups({
-    systemKey,
-    options,
-    manifest,
-    payload,
-    environment,
-    dataplaneUrl,
-    authConfig,
-    rawRes
-  });
-  return { dataplaneUrl, authConfig, environment };
+  return { dataplaneUrl, authConfig, environment, uploadSkipped: false };
 }
 
 /**
@@ -426,12 +403,17 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
  */
 async function uploadExternalSystem(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-  logger.log('');
-  logger.log(sectionTitle('Upload external system'));
-  logger.log(SEP);
-  logger.log(headerKeyValue('System:', systemKey));
+  const minimal = options.minimal === true;
+  if (!minimal) {
+    logger.log('');
+    logger.log(sectionTitle('Upload external system'));
+    logger.log(SEP);
+    logger.log(headerKeyValue('System:', systemKey));
+  }
   const { manifest, payload } = await buildValidatedUploadManifestPayload(systemKey, {
-    dryRun: !!options.dryRun
+    dryRun: !!options.dryRun,
+    force: options.force === true,
+    minimal
   });
   if (options.dryRun) {
     logger.log(chalk.yellow('Dry run: would upload payload (no API calls).'));

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

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview verify-governance — sync, generate, verify (424.0 dataplane-first).
+ */
+
+'use strict';
+
+const { runGovernanceGenerateForExternalSystem } = require('./governance-generate-external');
+const { runVerifyGovernanceForExternalSystem } = require('./verify-governance-external');
+const {
+  buildSubjectsFromOptions,
+  resolveGovernanceIntegrationContext
+} = require('./governance-cli-shared');
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runVerifyGovernanceCombined(systemKey, options = {}) {
+  if (options.pack) {
+    return runVerifyGovernanceForExternalSystem(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 verify-governance'
+    );
+  }
+
+  const { resolvedKey, authConfig, dataplaneUrl } = await resolveGovernanceIntegrationContext(
+    systemKey,
+    options
+  );
+
+  const pipelineOpts = {
+    ...options,
+    noSync: true,
+    authConfig,
+    dataplaneUrl
+  };
+
+  const generateResult = await runGovernanceGenerateForExternalSystem(
+    resolvedKey,
+    pipelineOpts
+  );
+
+  const verifyResult = await runVerifyGovernanceForExternalSystem(resolvedKey, pipelineOpts);
+
+  return {
+    ...verifyResult,
+    command: 'verify-governance',
+    generated: generateResult.generated,
+    generateResults: generateResult.results
+  };
+}
+
+module.exports = {
+  runVerifyGovernanceCombined
+};

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

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview CLI action for `aifabrix verify-governance` (plan 150.0 / 424.0).
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { runVerifyGovernanceCombined } = require('./verify-governance-combined-external');
+const { normalizeTestGovernanceCliOptions } = require('./test-governance-cli-options');
+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');
+
+/**
+ * @param {Object} options
+ * @param {import('commander').Command} [cmd]
+ * @returns {Object}
+ */
+function normalizeVerifyGovernanceCliOptions(options, cmd) {
+  const base = normalizeTestGovernanceCliOptions(options, cmd);
+  return {
+    ...base,
+    certificationProfile: options.certificationProfile || 'bronze',
+    subjectUserIds: options.subjectUserId || [],
+    subjectEmails: options.subjectEmail || [],
+    maxSamplesPerPartition: options.maxSamplesPerPartition
+  };
+}
+
+async function runVerifyGovernanceCommandAction(appName, options, cmd) {
+  const opts = normalizeVerifyGovernanceCliOptions(options, cmd);
+  const result = await runVerifyGovernanceCombined(appName, opts);
+
+  if (opts.json) {
+    logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));
+  } else {
+    if (opts.verbose && !opts.pack && typeof result.generated === 'number' && result.generated > 0) {
+      logger.log(formatSuccessLine(`Generated packs for ${result.generated} datasource(s)`));
+    }
+    displayVerifyGovernanceTTY(result.systemKey, result, { details: opts.verbose });
+  }
+
+  const exitCode = exitCodeFromVerdict(result.verdict);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+async function verifyGovernanceCommandHandler(appName, options, cmd) {
+  try {
+    await runVerifyGovernanceCommandAction(appName, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'verify-governance');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  runVerifyGovernanceCommandAction,
+  verifyGovernanceCommandHandler,
+  normalizeVerifyGovernanceCliOptions
+};

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