@aifabrix/builder 2.45.5 → 2.46.0

package/lib/commands/auth-status.js

@@ -11,8 +11,6 @@
 const chalk = require('chalk');
 const { failureGlyph, successGlyph } = require('../utils/cli-test-layout-chalk');
 const logger = require('../utils/logger');
-const config = require('../core/config');
-const { getConfig } = config;
 const { getOrRefreshDeviceToken } = require('../utils/token-manager');
 const { getAuthUser } = require('../api/auth.api');
 const { resolveControllerUrl } = require('../utils/controller-url');
@@ -32,6 +30,11 @@ const {
   EXIT_CLI_VERSION_INCOMPATIBLE,
   EXIT_OK
 } = require('../utils/cli-exit-codes');
+const {
+  refreshExpiredClientTokensWherePossible,
+  displayStoredClientTokensSection,
+  tryResolveClientTokenAuth
+} = require('./auth-status-client-tokens');
 
 /**
  * Format expiration date for display
@@ -94,22 +97,6 @@ async function checkDeviceToken(controllerUrl) {
   }
 }
 
-/**
- * Decrypt token if encrypted
- * @async
- * @param {string} token - Token to decrypt
- * @returns {Promise<string>} Decrypted token
- */
-async function decryptTokenIfNeeded(token) {
-  const { decryptToken, isTokenEncrypted } = require('../utils/token-encryption');
-  const encryptionKey = await config.getSecretsEncryptionKey();
-
-  if (encryptionKey && isTokenEncrypted(token)) {
-    return await decryptToken(token, encryptionKey);
-  }
-  return token;
-}
-
 /**
  * Validate client token and return result
  * @async
@@ -156,29 +143,14 @@ async function validateClientToken(token, controllerUrl, environment, appName, e
 }
 
 /**
- * Check and validate client token
+ * Check and validate client token (refreshes when expired if client credentials exist).
  * @async
  * @param {string} controllerUrl - Controller URL
  * @param {string} environment - Environment key
  * @returns {Promise<Object|null>} Token validation result or null
  */
 async function checkClientToken(controllerUrl, environment) {
-  const configData = await getConfig();
-  const environments = configData.environments || {};
-  const envConfig = environments[environment];
-
-  if (!envConfig || !envConfig.clients) {
-    return null;
-  }
-
-  for (const [appName, tokenData] of Object.entries(envConfig.clients)) {
-    if (tokenData.controller === controllerUrl && tokenData.token) {
-      const token = await decryptTokenIfNeeded(tokenData.token);
-      return await validateClientToken(token, controllerUrl, environment, appName, tokenData.expiresAt);
-    }
-  }
-
-  return null;
+  return tryResolveClientTokenAuth(controllerUrl, environment, validateClientToken);
 }
 
 /**
@@ -382,18 +354,34 @@ async function buildDataplaneInfo(controllerUrl, environment, authConfig) {
  * @param {boolean} [options.validate] - If true, exit with code 1 when not authenticated, or code 3 when CLI is older than dataplane minimum
  * @returns {Promise<void>} Resolves when status is displayed
  */
+/**
+ * Prefer a working device token; fall back to environment client credentials when the
+ * stored device token is expired or rejected (common in long-lived dev VMs).
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} environment
+ * @returns {Promise<Object|null>}
+ */
+async function resolveAuthenticatedTokenInfo(controllerUrl, environment) {
+  const deviceResult = await checkDeviceToken(controllerUrl);
+  if (deviceResult && deviceResult.authenticated) {
+    return deviceResult;
+  }
+  const clientResult = await checkClientToken(controllerUrl, environment);
+  if (clientResult && clientResult.authenticated) {
+    return clientResult;
+  }
+  return deviceResult || clientResult || null;
+}
+
 async function handleAuthStatus(options = {}) {
   const { resolveEnvironment } = require('../core/config');
   const controllerUrl = await resolveControllerUrl();
   const environment = await resolveEnvironment();
 
-  // Check device token first (preferred)
-  let tokenInfo = await checkDeviceToken(controllerUrl);
-
-  // If no device token, check client token
-  if (!tokenInfo) {
-    tokenInfo = await checkClientToken(controllerUrl, environment);
-  }
+  const refreshedCount = await refreshExpiredClientTokensWherePossible(environment, controllerUrl);
+  const tokenInfo = await resolveAuthenticatedTokenInfo(controllerUrl, environment);
 
   let dataplaneInfo = null;
   if (tokenInfo && tokenInfo.authenticated && tokenInfo.token) {
@@ -402,6 +390,7 @@ async function handleAuthStatus(options = {}) {
   }
 
   displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo);
+  await displayStoredClientTokensSection(environment, controllerUrl, refreshedCount);
 
   if (options.validate) {
     if (!tokenInfo || !tokenInfo.authenticated) {
@@ -427,10 +416,7 @@ async function getValidatedAuthContext() {
   const controllerUrl = await resolveControllerUrl();
   const environment = await resolveEnvironment();
 
-  let tokenInfo = await checkDeviceToken(controllerUrl);
-  if (!tokenInfo) {
-    tokenInfo = await checkClientToken(controllerUrl, environment);
-  }
+  const tokenInfo = await resolveAuthenticatedTokenInfo(controllerUrl, environment);
 
   if (!tokenInfo || !tokenInfo.authenticated || !tokenInfo.token) {
     throw new Error('Not authenticated. Run "aifabrix login" or configure client credentials.');
@@ -442,4 +428,12 @@ async function getValidatedAuthContext() {
   return { controllerUrl, environment, authConfig, dataplaneUrl };
 }
 
-module.exports = { handleAuthStatus, getValidatedAuthContext };
+module.exports = {
+  handleAuthStatus,
+  getValidatedAuthContext,
+  resolveAuthenticatedTokenInfo,
+  checkDeviceToken,
+  checkClientToken,
+  refreshExpiredClientTokensWherePossible,
+  displayStoredClientTokensSection
+};

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