@aifabrix/builder 2.45.5 → 2.47.0

package/lib/commands/channel.js

@@ -0,0 +1,58 @@
+/**
+ * Channel CLI commands (plan 152).
+ *
+ * @fileoverview Scaffold communication external systems for channel deploy step 1
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatBlockingError, sectionTitle, metadata } = require('../utils/cli-test-layout-chalk');
+const { CHANNEL_TARGET_KEYS, isChannelTargetKey } = require('../channels/channel-targets');
+const { scaffoldChannelIntegration } = require('../channels/channel-integration-generator');
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupChannelCommands(program) {
+  const channel = program
+    .command('channel')
+    .description('Assistant channel integration scaffolds (plan 152)');
+
+  channel
+    .command('scaffold <channelTarget>')
+    .description('Generate integration/<target>/ communication external system for deploy step 1')
+    .option('--force', 'Overwrite generated scaffold files when folder exists')
+    .option('--allow-experimental', 'Allow web-embed scaffold')
+    .action(async(channelTarget, options) => {
+      try {
+        if (!isChannelTargetKey(channelTarget)) {
+          throw new Error(
+            `Unknown channel target "${channelTarget}". Expected: ${CHANNEL_TARGET_KEYS.join(', ')}`
+          );
+        }
+        const result = scaffoldChannelIntegration(channelTarget, {
+          force: options.force === true,
+          allowExperimental: options.allowExperimental === true
+        });
+        logger.log(sectionTitle(`${channelTarget} channel scaffold`));
+        logger.log('');
+        logger.log(formatSuccessLine(`Created integration at ${result.integrationDir}`));
+        for (const file of result.files) {
+          logger.log(metadata(file));
+        }
+        logger.log('');
+        logger.log(chalk.white('Next steps:'));
+        logger.log(chalk.gray(`  aifabrix deploy ${channelTarget}`));
+        logger.log(chalk.gray(`  aifabrix app add-channel ${channelTarget} --name "Your Assistant"`));
+      } catch (error) {
+        logger.error(formatBlockingError(error.message || String(error)));
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { setupChannelCommands };

package/lib/commands/datasource-test-trust-cli.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview CLI wiring for `datasource test-trust` (404.5 / plan 143).
+ * @fileoverview CLI wiring for `datasource verify-trust` (404.5 / plan 143).
  * @author AI Fabrix Team
  * @version 1.0.0
  */
@@ -15,26 +15,27 @@ const { computeExitCodeFromTrustRun } = require('../utils/agent-trust-run-exit')
 const { attachDatasourceTestCommonOptions } = require('./datasource-unified-test-cli.options');
 const { cliOptsSkipSync } = require('../utils/cli-sync-options');
 
-function datasourceTestTrustHelpAfter() {
+function datasourceVerifyTrustHelpAfter() {
   return `
 Examples:
-  $ aifabrix datasource test-trust hubspot-companies
-  $ aifabrix datasource test-trust hubspot-companies --app test-e2e-hubspot -v
-  $ aifabrix datasource test-trust hubspot-companies --revalidate --strict
-  $ aifabrix test-trust test-e2e-hubspot
+  $ aifabrix datasource verify-trust hubspot-companies
+  $ aifabrix datasource verify-trust hubspot-companies --app test-e2e-hubspot -v
+  $ aifabrix datasource verify-trust hubspot-companies --revalidate --strict
+  $ aifabrix verify-trust test-e2e-hubspot
 
 Notes:
   - Semantic trust only (agent metadata validation). For live API proof use test-e2e.
   - Local files are published before run unless --no-sync.
-  - With --debug, JSON is saved under integration/<app>/logs/ (test-trust-<key>-*.json). View with: aifabrix datasource log-trust <key>
+  - With --debug, JSON is saved under integration/<app>/logs/ (verify-trust-<key>-*.json). View with: aifabrix datasource log-trust <key>
 `;
 }
 
-async function runDatasourceTestTrustOnce(datasourceKey, options) {
+async function runDatasourceVerifyTrustOnce(datasourceKey, options) {
   const { trustRun, apiError } = await runDatasourceAgentTrust(datasourceKey, {
     app: options.app,
     environment: options.env,
     noSync: options.noSync === true,
+    force: options.force === true,
     revalidate: options.revalidate === true,
     summary: options.summary === true,
     timeout: options.timeout
@@ -42,7 +43,7 @@ async function runDatasourceTestTrustOnce(datasourceKey, options) {
   return { trustRun, apiError };
 }
 
-async function finalizeDatasourceTestTrust(datasourceKey, options, result) {
+async function finalizeDatasourceVerifyTrust(datasourceKey, options, result) {
   const displayOpts = {
     json: options.json,
     verbose: options.verbose,
@@ -67,10 +68,10 @@ async function finalizeDatasourceTestTrust(datasourceKey, options, result) {
   return computeExitCodeFromTrustRun(result.trustRun, exitOpts);
 }
 
-async function datasourceTestTrustAction(datasourceKey, options, cmd) {
+async function datasourceVerifyTrustAction(datasourceKey, options, cmd) {
   try {
     const merged = { ...options, noSync: cliOptsSkipSync(options, cmd) };
-    const result = await runDatasourceTestTrustOnce(datasourceKey, merged);
+    const result = await runDatasourceVerifyTrustOnce(datasourceKey, merged);
     const { resolveAppKeyForDatasource } = require('../datasource/resolve-app');
     const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
     if (options.debug) {
@@ -80,7 +81,7 @@ async function datasourceTestTrustAction(datasourceKey, options, cmd) {
         error: result.apiError ? result.apiError.message : null
       });
     }
-    const exitCode = await finalizeDatasourceTestTrust(datasourceKey, merged, result);
+    const exitCode = await finalizeDatasourceVerifyTrust(datasourceKey, merged, result);
     process.exit(exitCode);
   } catch (err) {
     logger.error(formatBlockingError('Agent trust validation failed:'), err.message);
@@ -88,10 +89,7 @@ async function datasourceTestTrustAction(datasourceKey, options, cmd) {
   }
 }
 
-function setupDatasourceTestTrustCommand(datasource) {
-  const cmd = datasource
-    .command('test-trust <datasourceKey>')
-    .description('Semantic agent metadata validation for one datasource (dataplane 404.5)');
+function attachDatasourceTrustOptions(cmd) {
   attachDatasourceTestCommonOptions(cmd, {
     includeNoAsync: false,
     includePayload: false,
@@ -101,14 +99,20 @@ function setupDatasourceTestTrustCommand(datasource) {
   cmd
     .option('--no-sync', 'Skip publishing local integration files before validate')
     .option('--revalidate', 'Force new validation (ignore inputHash cache)')
-    .option('--strict', 'Exit 1 unless trustDecision is trusted')
-    .addHelpText('after', datasourceTestTrustHelpAfter())
-    .action(datasourceTestTrustAction);
+    .option('--strict', 'Exit 1 unless trustDecision is trusted');
+}
+
+function setupDatasourceVerifyTrustCommand(datasource) {
+  const cmd = datasource
+    .command('verify-trust <datasourceKey>')
+    .description('Semantic agent metadata validation for one datasource');
+  attachDatasourceTrustOptions(cmd);
+  cmd.addHelpText('after', datasourceVerifyTrustHelpAfter()).action(datasourceVerifyTrustAction);
 }
 
 module.exports = {
-  setupDatasourceTestTrustCommand,
-  runDatasourceTestTrustOnce,
-  finalizeDatasourceTestTrust,
-  datasourceTestTrustAction
+  setupDatasourceVerifyTrustCommand,
+  runDatasourceVerifyTrustOnce,
+  finalizeDatasourceVerifyTrust,
+  datasourceVerifyTrustAction
 };

package/lib/commands/datasource-unified-test-cli.js

@@ -77,7 +77,8 @@ function buildDatasourceTestRunOpts(options) {
     timeout: options.timeout,
     async: options.async !== false,
     noAsync: options.async === false,
-    sync: options.sync === true
+    sync: options.sync === true,
+    force: options.force === true
   };
 }
 
@@ -174,7 +175,8 @@ function buildIntegrationTestOpts(options) {
     debug: options.debug,
     verbose: options.verbose,
     timeout: options.timeout,
-    sync: options.sync === true
+    sync: options.sync === true,
+    force: options.force === true
   };
 }
 
@@ -335,7 +337,8 @@ async function runDatasourceTestE2ECliOnce(datasourceKey, options) {
     minRecordCount: options.minRecordCount,
     timeout: options.timeout,
     capabilityKey: options.capabilityKey,
-    sync: options.sync === true
+    sync: options.sync === true,
+    force: options.force === true
   });
   const unifiedModes =
     options.json || options.summary || options.warningsAsErrors || options.requireCert;

package/lib/commands/datasource-unified-test-cli.options.js

@@ -44,7 +44,7 @@ Examples:
   $ aifabrix datasource test-e2e hubspot-users --app test-e2e-hubspot -v --debug
   $ aifabrix datasource test-e2e my-documents-ds --min-vector-hits 7 -v --debug
   $ aifabrix datasource test-e2e hubspot-users -a test-e2e-hubspot --no-async
-  $ aifabrix datasource test-e2e hubspot-users --sync --verify-audit -v
+  $ aifabrix datasource test-e2e hubspot-users --sync --force --verify-audit -v
   $ aifabrix datasource test-e2e hubspot-users read
 
 Notes:
@@ -129,6 +129,10 @@ function attachDatasourceTestCommonOptions(cmd, opts) {
       '--sync',
       'Publish local integration config to the dataplane before running the test (same as aifabrix upload <systemKey>; requires login)'
     )
+    .option(
+      '--force',
+      'With --sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
+    )
     .option('--json', 'Print raw DatasourceTestRun JSON to stdout')
     .option('--summary', 'Print compact summary line')
     .option('--warnings-as-errors', 'Exit 1 when root status is warn')

package/lib/commands/datasource.js

@@ -2,7 +2,7 @@
  * AI Fabrix Builder - Datasource Commands
  *
  * Handles datasource validation, listing, comparison, deployment, and online validation runs.
- * Subcommands `test`, `test-integration`, `test-e2e`, and `test-trust` call the dataplane; `log-*` read saved debug JSON locally; `clean-logs` removes those files. Permissions are summarized in `docs/commands/permissions.md`.
+ * Subcommands `test`, `test-integration`, `test-e2e`, and `verify-trust` call the dataplane; `log-*` read saved debug JSON locally; `clean-logs` removes those files. Permissions are summarized in `docs/commands/permissions.md`.
  *
  * @fileoverview Datasource management commands for AI Fabrix Builder
  * @author AI Fabrix Team
@@ -24,7 +24,7 @@ const {
   setupDatasourceTestIntegrationCommand,
   setupDatasourceTestE2ECommand
 } = require('./datasource-unified-test-cli');
-const { setupDatasourceTestTrustCommand } = require('./datasource-test-trust-cli');
+const { setupDatasourceVerifyTrustCommand } = require('./datasource-test-trust-cli');
 const { setupDatasourceVerifyAuditCommand } = require('./datasource-verify-audit-cli');
 const { setupDatasourceLoadExportCommands } = require('./datasource-load-export-cli');
 const { setupDatasourceCapabilityCommands } = require('./datasource-capability');
@@ -44,7 +44,7 @@ Examples:
   $ af ds test-e2e <datasourceKey> --app <integrationFolder> -v
   $ af ds test-e2e <datasourceKey> --verify-audit
   $ af ds verify-audit <datasourceKey>
-  $ af ds test-trust <datasourceKey> --app <integrationFolder> -v
+  $ af ds verify-trust <datasourceKey> --app <integrationFolder> -v
   $ af ds load <datasourceKey> --app <integrationFolder> --dry-run
   $ af ds export <datasourceKey> --app <integrationFolder> --format ndjson -v
   $ aifabrix datasource capability copy <file-or-key> --from create --as createBasicTrial --dry-run
@@ -97,7 +97,7 @@ Omit [prefix] to list all datasources for the active environment.
 
 function setupDatasourceValidateCommand(datasource) {
   datasource.command('validate <file-or-key>')
-    .description('Validate datasource JSON (file path or datasource key under integration/<app>/)')
+    .description('Validate datasource YAML/JSON (file path or datasource key under integration/<app>/)')
     .addHelpText('after', DATASOURCE_VALIDATE_HELP_AFTER)
     .action(async(fileOrKey) => {
       try {
@@ -262,18 +262,18 @@ function setupDatasourceCleanLogsCommand(datasource) {
 
 function setupDatasourceLogTrustCommand(datasource) {
   datasource.command('log-trust <datasourceKey>')
-    .description('Show agent trust log from datasource test-trust (latest test-trust-*.json or --file)')
+    .description('Show agent trust log from datasource verify-trust (latest verify-trust-*.json or --file)')
     .option(
       '-a, --app <app>',
       'Integration folder name (optional: resolve from cwd or datasource key if single match)'
     )
-    .option('-f, --file <path>', 'Path to log file (default: latest test-trust log in app logs folder)')
+    .option('-f, --file <path>', 'Path to log file (default: latest verify-trust log in app logs folder)')
     .action(async(datasourceKey, options) => {
       try {
         await runLogViewer(datasourceKey, {
           app: options.app,
           file: options.file,
-          logType: 'test-trust'
+          logType: 'verify-trust'
         });
       } catch (error) {
         logger.error(formatBlockingError('log-trust failed:'), error.message);
@@ -304,7 +304,7 @@ function setupDatasourceCommands(program) {
   setupDatasourceTestIntegrationCommand(datasource);
   setupDatasourceTestE2ECommand(datasource);
   setupDatasourceVerifyAuditCommand(datasource);
-  setupDatasourceTestTrustCommand(datasource);
+  setupDatasourceVerifyTrustCommand(datasource);
   setupDatasourceLogE2ECommand(datasource);
   setupDatasourceLogIntegrationCommand(datasource);
   setupDatasourceLogTestCommand(datasource);

package/lib/commands/dev-show-display.js

@@ -336,6 +336,8 @@ function logConfigurationSection(p) {
   logRow('Environment', p.environment);
   logRow('Controller', p.controller);
   logRow('Format', p.formatVal);
+  logRow('Platform mode', p.setupPlatformMode);
+  logRow('Traefik', p.traefikEnabled ? 'on' : 'off');
   logRow('Scoped resources', p.scopedResourcesLabel);
   logRow('URLs registry', p.urlsLocalPath);
   if (!p.hasRemote) {
@@ -386,11 +388,12 @@ async function loadDevShowData(devIdStr) {
   const devIdNum = parseInt(devIdStr, 10);
   const ports = devConfig.getDevPorts(Number.isNaN(devIdNum) ? 0 : devIdNum);
   const [
-    environment, tlsEnabled, controller, formatRaw, useScoped, secretsRaw,
+    environment, tlsEnabled, controller, formatRaw, useScoped, secretsRaw, setupPlatformMode, traefikEnabled,
     remoteServer, dockerEndpoint, dockerTlsSkipVerify, mutagenFolder, syncSshUser, syncSshHost
   ] = await Promise.all([
     config.getCurrentEnvironment(), config.getTlsEnabled(), config.getControllerUrl(),
     config.getFormat(), config.getUseEnvironmentScopedResources(), config.getAifabrixSecretsPath(),
+    config.getSetupPlatformMode(), config.getTraefikEnabled(),
     config.getRemoteServer(), config.getDockerEndpoint(), config.getDockerTlsSkipVerify(),
     config.getUserMutagenFolder(), config.getSyncSshUser(), config.getSyncSshHost()
   ]);
@@ -410,6 +413,8 @@ async function loadDevShowData(devIdStr) {
     controller,
     formatVal: formatRaw ?? null,
     scopedResourcesLabel,
+    setupPlatformMode,
+    traefikEnabled,
     workResolved,
     homeResolved,
     secretsMain,
@@ -446,6 +451,8 @@ function renderDevShow(data) {
     tlsEnabled: data.tlsEnabled,
     controller: data.controller,
     formatVal: data.formatVal,
+    setupPlatformMode: data.setupPlatformMode,
+    traefikEnabled: data.traefikEnabled,
     scopedResourcesLabel: data.scopedResourcesLabel,
     urlsLocalPath: data.urlsLocalPath,
     hasRemote: data.hasRemote,

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