@aifabrix/builder 2.43.0 → 2.44.1

package/lib/cli/setup-dev.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI developer configuration command setup (dev config, dev set-id, dev init, dev add/update/pin/delete/list).
  *
@@ -8,10 +9,11 @@
 
 const chalk = require('chalk');
 const config = require('../core/config');
-const devConfig = require('../utils/dev-config');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
+const { setupDevPathAndFormatCommands } = require('./setup-dev-path-commands');
 const { runDevInit, runDevRefresh } = require('../commands/dev-init');
+const { displayDevConfig } = require('../commands/dev-show-display');
 const {
   handleDevList,
   handleDevAdd,
@@ -20,45 +22,78 @@ const {
   handleDevDelete
 } = require('../commands/dev-cli-handlers');
 
-/**
- * Display developer configuration (local ports and config; remote/settings keys always shown).
- * Always shows environment, controller, and remote keys (value or "(not set)").
- * @param {string} devId - Developer ID
- * @returns {Promise<void>}
- */
-async function displayDevConfig(devId) {
-  const devIdNum = parseInt(devId, 10);
-  const ports = devConfig.getDevPorts(devIdNum);
-  const environment = await config.getCurrentEnvironment();
-  const controller = await config.getControllerUrl();
-
-  const optionalConfigVars = [
-    { key: 'format', value: (await config.getFormat()) ?? '(not set)' },
-    { key: 'aifabrix-home', value: await config.getAifabrixHomeOverride() },
-    { key: 'aifabrix-secrets', value: await config.getAifabrixSecretsPath() },
-    { key: 'aifabrix-env-config', value: await config.getAifabrixEnvConfigPath() },
-    { key: 'remote-server', value: await config.getRemoteServer() },
-    { key: 'docker-endpoint', value: await config.getDockerEndpoint() },
-    { key: 'user-mutagen-folder', value: await config.getUserMutagenFolder() },
-    { key: 'sync-ssh-user', value: await config.getSyncSshUser() },
-    { key: 'sync-ssh-host', value: await config.getSyncSshHost() }
-  ];
-
-  logger.log('\n🔧 Developer Configuration\n');
-  logger.log(`Developer ID: ${devId}`);
-  logger.log('\nPorts:');
-  logger.log(`  App: ${ports.app}`);
-  logger.log(`  Postgres: ${ports.postgres}`);
-  logger.log(`  Redis: ${ports.redis}`);
-  logger.log(`  pgAdmin: ${ports.pgadmin}`);
-  logger.log(`  Redis Commander: ${ports.redisCommander}`);
-
-  logger.log('\nConfiguration:');
-  logger.log(`  environment: '${environment}'`);
-  logger.log(controller ? `  controller: '${controller}'` : '  controller: (not set)');
-  optionalConfigVars.forEach(v => logger.log(`  ${v.key}: ${v.value || '(not set)'}`));
-  logger.log('');
-}
+/** Appended to `dev update --help` (examples + partial-update behaviour). */
+const DEV_UPDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix dev update 02 --name "Jane Doe"
+  $ aifabrix dev update --developer-id 02 --email jane@example.com
+  $ aifabrix dev update 01 --name "Admin" --groups admin,developer
+  $ aifabrix dev update 02 --groups admin,developer,docker
+
+Partial update: only flags you pass are sent to the server. Omitted name, email, and groups are left unchanged.
+`;
+
+/** Appended to `dev add --help` (examples + workflow). */
+const DEV_ADD_HELP_AFTER = `
+Examples:
+  $ aifabrix dev add --developer-id 02 --name "Jane Doe" --email jane@example.com
+  $ aifabrix dev add --developer-id 03 --name "Build admin" --email admin@example.com --groups admin,developer
+  $ aifabrix dev add --developer-id 04 --name "CI user" --email ci@example.com --groups secret-manager,developer
+
+Requires a configured remote Builder Server and an admin client certificate (same machine setup as dev list / dev pin). After add, run dev pin <id> once to create a PIN for aifabrix dev init.
+`;
+
+/** Appended to `aifabrix dev --help` (overview; keep subcommand .description lines short). */
+const DEV_GROUP_HELP_AFTER = `
+Categories:
+  Local config   show, set-id, set-scoped-resources, set-env-config, set-home, set-work, set-format, print-home, print-work
+  Onboarding     init (PIN onboarding), refresh (sync settings / renew cert)
+  Remote admin   list, add, update, pin, delete  (need remote-server + client cert in ~/.aifabrix)
+  Sync / stop    down  (Mutagen; optional --apps for containers)
+
+Use: aifabrix dev <command> --help
+`;
+
+/** Appended to `dev init --help`. */
+const DEV_INIT_HELP_AFTER = `
+Examples:
+  Full (first machine or no config yet):
+  $ aifabrix dev init --developer-id 01 --server https://builder01.local --pin <one-time-pin>
+
+  When remote-server and developer-id are already in ~/.aifabrix/config.yaml (from settings or dev show):
+  $ aifabrix dev init --pin <one-time-pin>
+
+Admin issues the PIN with: aifabrix dev pin <developer-id>
+`;
+
+/** Appended to `dev refresh --help`. */
+const DEV_REFRESH_HELP_AFTER = `
+Requires remote-server and saved client certificate (after dev init). Use --cert to force a new cert before expiry.
+`;
+
+/** Appended to `dev pin --help`. */
+const DEV_PIN_HELP_AFTER = `
+Examples:
+  $ aifabrix dev pin 02
+  $ aifabrix dev pin 02 --hosts-ip 192.168.1.25
+  $ aifabrix dev pin   (uses developer-id from config)
+
+Prints copy-paste commands for the developer: full dev init, hosts-file variant, and dev init --pin
+when their config already has remote-server + developer-id.
+`;
+
+/** Appended to `dev delete --help`. */
+const DEV_DELETE_HELP_AFTER = `
+Example:
+  $ aifabrix dev delete 02
+`;
+
+/** Appended to `dev down --help`. */
+const DEV_DOWN_HELP_AFTER = `
+Examples:
+  $ aifabrix dev down
+  $ aifabrix dev down --apps
+`;
 
 /**
  * Handle dev set-format command
@@ -67,7 +102,34 @@ async function displayDevConfig(devId) {
  */
 async function handleSetFormat(format) {
   await config.setFormat(format);
-  logger.log(chalk.green(`✓ Format set to ${format.toLowerCase()}`));
+  logger.log(formatSuccessLine(`Format set to ${format.toLowerCase()}`));
+  const devId = await config.getDeveloperId();
+  await displayDevConfig(devId);
+}
+
+/**
+ * Set useEnvironmentScopedResources in ~/.aifabrix/config.yaml
+ * @param {string} value - "true" or "false"
+ * @returns {Promise<void>}
+ */
+async function handleSetScopedResources(value) {
+  const b = String(value || '').trim().toLowerCase();
+  if (b !== 'true' && b !== 'false') {
+    throw new Error('Value must be true or false (example: aifabrix dev set-scoped-resources true)');
+  }
+  await config.setUseEnvironmentScopedResources(b === 'true');
+  if (b === 'true') {
+    logger.log(
+      formatSuccessLine('Environment-scoped resources activated in ~/.aifabrix/config.yaml')
+    );
+  } else {
+    logger.log(formatSuccessLine('Environment-scoped resources passivated (default local naming)'));
+  }
+  logger.log(
+    chalk.gray(
+      '  Apps still need environmentScopedResources: true in application.yaml for prefixing when you run with --env dev or tst.'
+    )
+  );
   const devId = await config.getDeveloperId();
   await displayDevConfig(devId);
 }
@@ -79,7 +141,7 @@ async function handleSetFormat(format) {
 function setupDevShowAndSetId(dev) {
   dev
     .command('show')
-    .description('Show developer configuration (ports and config vars)')
+    .description('Show dev ports and ~/.aifabrix config')
     .action(async() => {
       try {
         const devId = await config.getDeveloperId();
@@ -92,7 +154,7 @@ function setupDevShowAndSetId(dev) {
 
   dev
     .command('set-id <id>')
-    .description('Set developer ID (0 = default infra, > 0 = developer-specific)')
+    .description('Set developer ID (0 = default infra, >0 = dev-specific ports)')
     .action(async(id) => {
       try {
         const digitsOnly = /^[0-9]+$/.test(id);
@@ -101,56 +163,22 @@ function setupDevShowAndSetId(dev) {
         }
         await config.setDeveloperId(id);
         process.env.AIFABRIX_DEVELOPERID = id;
-        logger.log(chalk.green(`✓ Developer ID set to ${id}`));
+        logger.log(formatSuccessLine(`Developer ID set to ${id}`));
         await displayDevConfig(id);
       } catch (error) {
         handleCommandError(error, 'dev set-id');
         process.exit(1);
       }
     });
-}
-
-/**
- * Register dev set-env-config, set-home and set-format commands.
- * @param {Command} dev - dev subcommand group
- */
-function setupDevPathAndFormatCommands(dev) {
-  dev
-    .command('set-env-config <filePath>')
-    .description('Set aifabrix-env-config path in config.yaml (pass empty to clear; path is not checked for existence)')
-    .action(async(filePath) => {
-      try {
-        const trimmed = (filePath || '').trim();
-        await config.setAifabrixEnvConfigPath(trimmed);
-        logger.log(trimmed === '' ? chalk.green('✓ Env config path cleared') : chalk.green(`✓ Env config path set to ${trimmed}`));
-      } catch (error) {
-        handleCommandError(error, 'dev set-env-config');
-        process.exit(1);
-      }
-    });
 
   dev
-    .command('set-home <path>')
-    .description('Set aifabrix-home path in config.yaml (pass empty string to clear)')
-    .action(async(homePath) => {
+    .command('set-scoped-resources <value>')
+    .description('Set useEnvironmentScopedResources to true|false in ~/.aifabrix/config.yaml')
+    .action(async(value) => {
       try {
-        const trimmed = (homePath || '').trim();
-        await config.setAifabrixHomeOverride(trimmed);
-        logger.log(trimmed === '' ? chalk.green('✓ Home path cleared') : chalk.green(`✓ Home path set to ${trimmed}`));
+        await handleSetScopedResources(value);
       } catch (error) {
-        handleCommandError(error, 'dev set-home');
-        process.exit(1);
-      }
-    });
-
-  dev
-    .command('set-format <format>')
-    .description('Set default output format for download/convert (json | yaml); used when --format not passed')
-    .action(async(format) => {
-      try {
-        await handleSetFormat(format);
-      } catch (error) {
-        handleCommandError(error, 'dev set-format');
+        handleCommandError(error, 'dev set-scoped-resources');
         process.exit(1);
       }
     });
@@ -162,7 +190,29 @@ function setupDevPathAndFormatCommands(dev) {
  */
 function setupDevConfigCommands(dev) {
   setupDevShowAndSetId(dev);
-  setupDevPathAndFormatCommands(dev);
+  setupDevPathAndFormatCommands(dev, handleSetFormat);
+}
+
+/**
+ * Shared Commander options for dev init (PIN onboarding).
+ * @param {object} cmd - Commander command to attach options to
+ * @returns {object} Same command for chaining
+ */
+function addDevOnboardingOptions(cmd) {
+  return cmd
+    .requiredOption('--pin <pin>', 'One-time PIN from your admin (see aifabrix dev pin)')
+    .option(
+      '--developer-id <id>',
+      'Developer ID (optional if set in ~/.aifabrix/config.yaml and not 0; e.g. 01)'
+    )
+    .option('--server <url>', 'Builder Server base URL (optional if remote-server is in config)')
+    .option('-y, --yes', 'Auto-install development CA without prompt when certificate is untrusted; with --add-hosts, skip hosts-file confirmation')
+    .option('--no-install-ca', 'Do not offer CA install; fail with manual instructions on untrusted certificate')
+    .option(
+      '--add-hosts',
+      'Offer to add the server hostname to this machine\'s hosts file (wildcard DNS must be configured separately; may require admin)'
+    )
+    .option('--hosts-ip <ip>', 'IPv4 for the hosts entry when using --add-hosts (skips lookup / IP prompt)');
 }
 
 /**
@@ -170,26 +220,26 @@ function setupDevConfigCommands(dev) {
  * @param {Command} dev - dev subcommand group
  */
 function setupDevInitCommand(dev) {
-  dev
-    .command('init')
-    .description('Onboard with Builder Server (issue certificate, fetch settings, register SSH key for Mutagen)')
-    .requiredOption('--developer-id <id>', 'Developer ID (same as dev add; e.g. 01)')
-    .requiredOption('--server <url>', 'Builder Server base URL (e.g. https://dev.aifabrix.dev)')
-    .requiredOption('--pin <pin>', 'One-time PIN from your admin')
-    .option('-y, --yes', 'Auto-install development CA without prompt when certificate is untrusted')
-    .option('--no-install-ca', 'Do not offer CA install; fail with manual instructions on untrusted certificate')
-    .action(async(options) => {
-      try {
-        await runDevInit(options);
-      } catch (error) {
-        handleCommandError(error, 'dev init');
-        process.exit(1);
-      }
-    });
+  const runOnboarding = async(options, label) => {
+    try {
+      await runDevInit(options);
+    } catch (error) {
+      handleCommandError(error, label);
+      process.exit(1);
+    }
+  };
+
+  addDevOnboardingOptions(
+    dev
+      .command('init')
+      .description('Onboard with Builder Server (cert, settings, SSH for Mutagen)')
+      .addHelpText('after', DEV_INIT_HELP_AFTER)
+  ).action(async(options) => runOnboarding(options, 'dev init'));
 
   dev
     .command('refresh')
-    .description('Fetch settings from Builder Server and update config; refresh certificate if expiring within 14 days or --cert')
+    .description('Pull server settings into config; renew cert if due or --cert')
+    .addHelpText('after', DEV_REFRESH_HELP_AFTER)
     .option('--cert', 'Force certificate refresh (create PIN + issue-cert) even when cert is still valid')
     .action(async(options) => {
       try {
@@ -208,7 +258,7 @@ function setupDevInitCommand(dev) {
 function setupDevListAddCommands(dev) {
   dev
     .command('list')
-    .description('List developer users (remote Builder Server only)')
+    .description('List developers (remote Builder Server)')
     .action(async() => {
       try {
         await handleDevList();
@@ -220,11 +270,12 @@ function setupDevListAddCommands(dev) {
 
   dev
     .command('add')
-    .description('Register a new developer (remote Builder Server only; admin)')
-    .requiredOption('--developer-id <id>', 'Developer ID (unique, e.g. 01)')
+    .description('Create developer on server (admin); then dev pin for onboarding')
+    .requiredOption('--developer-id <id>', 'Unique id, digits only (e.g. 02); used with dev init --developer-id')
     .requiredOption('--name <name>', 'Display name')
     .requiredOption('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer)', 'developer')
+    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, developer, docker', 'developer')
+    .addHelpText('after', DEV_ADD_HELP_AFTER)
     .action(async(options) => {
       try {
         await handleDevAdd(options);
@@ -242,11 +293,12 @@ function setupDevListAddCommands(dev) {
 function setupDevUpdatePinDeleteCommands(dev) {
   dev
     .command('update [developerId]')
-    .description('Update a developer (name, email, groups); use --developer-id like dev add')
+    .description('Patch name/email/groups (admin); only given flags change')
     .option('--developer-id <id>', 'Developer ID (same as dev add)')
     .option('--name <name>', 'Display name')
     .option('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer)')
+    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer, docker)')
+    .addHelpText('after', DEV_UPDATE_HELP_AFTER)
     .action(async(developerId, options) => {
       try {
         await handleDevUpdate(developerId, options);
@@ -258,10 +310,12 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('pin [developerId]')
-    .description('Create or regenerate one-time PIN for onboarding (admin; show once to developer)')
-    .action(async(developerId) => {
+    .description('One-time onboarding PIN for dev init (admin)')
+    .option('--hosts-ip <ip>', 'Builder Server LAN IPv4 to embed in the hosts-file init command (optional)')
+    .addHelpText('after', DEV_PIN_HELP_AFTER)
+    .action(async(developerId, options) => {
       try {
-        await handleDevPin(developerId);
+        await handleDevPin(developerId, options);
       } catch (error) {
         handleCommandError(error, 'dev pin');
         process.exit(1);
@@ -270,7 +324,8 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('delete <developerId>')
-    .description('Remove a developer (remote Builder Server only; admin)')
+    .description('Remove developer from server (admin)')
+    .addHelpText('after', DEV_DELETE_HELP_AFTER)
     .action(async(developerId) => {
       try {
         await handleDevDelete(developerId);
@@ -282,7 +337,8 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('down')
-    .description('Stop Mutagen sync sessions for this developer (and optionally app containers)')
+    .description('Stop Mutagen sync; --apps also stops app containers')
+    .addHelpText('after', DEV_DOWN_HELP_AFTER)
     .option('--apps', 'Also stop running app containers for this developer')
     .action(async(options) => {
       try {
@@ -311,7 +367,8 @@ function setupDevUserCommands(dev) {
 function setupDevCommands(program) {
   const dev = program
     .command('dev')
-    .description('Developer configuration and isolation');
+    .description('Local dev config, Builder onboarding, remote admin, Mutagen/sync')
+    .addHelpText('after', DEV_GROUP_HELP_AFTER);
 
   setupDevConfigCommands(dev);
   setupDevInitCommand(dev);

package/lib/cli/setup-environment.js

@@ -29,9 +29,15 @@ Examples:
   $ aifabrix env deploy tst --preset m
   $ aifabrix env deploy dev --config ./env-config.json --no-poll`;
 
+  const ENV_GROUP_HELP_AFTER = `
+Subcommands:
+  deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
+`;
+
   const env = program
     .command('env')
-    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
+    .description('Miso Controller environments (primary: env deploy <env>)')
+    .addHelpText('after', ENV_GROUP_HELP_AFTER);
 
   env
     .command('deploy <env>')

package/lib/cli/setup-external-system.js

@@ -2,9 +2,9 @@
  * CLI external system command setup (download, upload, delete, test-integration).
  *
  * Registers these commands on the Commander program:
- * - download <system-key> – Download external system from dataplane to integration/<system-key>/
- * - upload <system-key> – Upload to dataplane (validate → publish; no controller deploy)
- * - delete <system-key> – Delete external system and associated datasources from dataplane
+ * - download <systemKey> – Download external system from dataplane to integration/<systemKey>/
+ * - upload <systemKey> – Upload publishes to dataplane and registers the app with the controller (draft)
+ * - delete <systemKey> – Delete external system and associated datasources from dataplane
  * - test-integration <app> – Run integration tests (builder: in container; external: via dataplane pipeline)
  *
  * @fileoverview External system command definitions for AI Fabrix Builder CLI
@@ -15,10 +15,12 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
+const { TEST_INTEGRATION_HELP_AFTER } = require('./setup-app.help');
 
 function setupDownloadCommand(program) {
-  program.command('download <system-key>')
-    .description('Download external system from dataplane to local development structure')
+  program.command('download <systemKey>')
+    .description('Pull external system from dataplane into integration/<key>/')
     .option('--format <format>', 'Output format: json | yaml (default: yaml or config format)')
     .option('--dry-run', 'Show what would be downloaded without actually downloading')
     .option('--force', 'Overwrite existing README.md without prompting')
@@ -39,13 +41,29 @@ function setupDownloadCommand(program) {
 }
 
 function setupUploadCommand(program) {
-  program.command('upload <system-key>')
-    .description('Upload external system to dataplane (upload → validate → publish; no controller deploy)')
+  program.command('upload <systemKey>')
+    .description('Validate, publish to dataplane, and register with controller (draft application)')
     .option('--dry-run', 'Validate and build payload only; no API calls')
+    .option('-v, --verbose', 'Run server-side pipeline validate and print warnings before publish')
+    .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
+    .option('--minimal', 'Print only a short readiness summary after upload')
+    .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
+    .option(
+      '--no-cert-sync',
+      'Skip updating the system file certification block from the dataplane active certificate after publish'
+    )
     .action(async(systemKey, options) => {
       try {
         const upload = require('../commands/upload');
-        await upload.uploadExternalSystem(systemKey, options);
+        const probeTimeout =
+          options.probeTimeout === undefined || options.probeTimeout === null
+            ? 120000
+            : Number(options.probeTimeout);
+        await upload.uploadExternalSystem(systemKey, {
+          ...options,
+          noCertSync: cliOptsSkipCertSync(options),
+          probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000
+        });
       } catch (error) {
         handleCommandError(error, 'upload');
         process.exit(1);
@@ -54,9 +72,9 @@ function setupUploadCommand(program) {
 }
 
 function setupDeleteCommand(program) {
-  program.command('delete <system-key>')
-    .description('Delete external system from dataplane (also deletes all associated datasources)')
-    .option('--type <type>', 'Application type (default: external; use "external" to target integration/<app>)')
+  program.command('delete <systemKey>')
+    .description('Remove external system and its datasources from dataplane')
+    .option('--type <type>', 'Application type (default: external; use "external" to target integration/<systemKey>)')
     .option('--yes', 'Skip confirmation prompt')
     .option('--force', 'Skip confirmation prompt (alias for --yes)')
     .action(async(systemKey, options) => {
@@ -111,10 +129,25 @@ async function tryBuilderTestIntegration(appName, options) {
  */
 async function runExternalSystemTestIntegration(appName, options) {
   const test = require('../external-system/test');
-  const opts = { ...options, environment: options.env || options.environment, debug: options.debug };
+  const opts = {
+    ...options,
+    environment: options.env || options.environment,
+    debug: options.debug,
+    perDatasource: options.perDatasource,
+    sync: options.sync === true
+  };
   const results = await test.testExternalSystemIntegration(appName, opts);
-  test.displayIntegrationTestResults(results, options.verbose);
-  if (!results.success) process.exit(1);
+  test.displayIntegrationTestResults(results, options.verbose, { debug: options.debug, runType: 'integration' });
+  const { computeSystemExitCodeFromDatasourceRows } = require('../utils/datasource-test-run-exit');
+  const rows = Array.isArray(results.datasourceResults) ? results.datasourceResults : [];
+  const exitCode = computeSystemExitCodeFromDatasourceRows(rows, {
+    warningsAsErrors: options.warningsAsErrors === true,
+    requireCert: options.requireCert === true
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+  if (cliOptsSkipCertSync(options)) return;
+  const { trySyncCertificationFromDataplaneForExternalApp } = require('../certification/sync-after-external-command');
+  await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-integration');
 }
 
 /**
@@ -126,6 +159,12 @@ async function runExternalSystemTestIntegration(appName, options) {
 async function runTestIntegrationCommand(appName, options) {
   const pathsUtil = require('../utils/paths');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true && appType && appType.baseDir === 'builder') {
+    throw new Error(
+      'Option --sync applies only to external integration tests (integration/<systemKey>/). ' +
+        'For a builder app use aifabrix upload <systemKey> from the integration folder, or run test-integration without --sync.'
+    );
+  }
   if (appType && appType.baseDir === 'builder') {
     const { runAppTestIntegration } = require('../commands/app-test');
     const opts = { env: options.env || options.environment || 'dev' };
@@ -133,23 +172,45 @@ async function runTestIntegrationCommand(appName, options) {
     return;
   }
   const ranBuilder = await tryBuilderTestIntegration(appName, options);
-  if (ranBuilder) return;
+  if (ranBuilder) {
+    if (options.sync === true) {
+      throw new Error(
+        'Option --sync applies only when test-integration runs against an external integration folder on the dataplane. ' +
+          'This run used a builder-style path instead. Remove --sync or use an integration/<systemKey>/ app.'
+      );
+    }
+    return;
+  }
   await runExternalSystemTestIntegration(appName, options);
 }
 
 function setupExternalSystemTestCommands(program) {
   // 'test <app>' is registered in setup-app.js and dispatches by app type (builder vs external)
   program.command('test-integration <app>')
-    .description('Run integration tests (builder/docker app: in container; external system: via dataplane pipeline API)')
-    .option('-d, --datasource <key>', 'Test specific datasource only')
-    .option('-p, --payload <file>', 'Path to custom test payload file')
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro (default: from aifabrix auth config)')
+    .description('Integration tests: builder in container; external via dataplane')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
     .option('-v, --verbose', 'Show detailed test output')
-    .option('--debug', 'Include debug output and write log to integration/<app>/logs/')
-    .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
-    .action(async(appName, options) => {
+    .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
+    .option(
+      '--sync',
+      'Publish local system and datasource files to the dataplane before running tests (same as aifabrix upload <systemKey>)'
+    )
+    .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
+    .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
+    .option(
+      '--no-cert-sync',
+      'Skip updating the system file certification block from the dataplane after a successful run'
+    )
+    .addHelpText('after', TEST_INTEGRATION_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
       try {
-        await runTestIntegrationCommand(appName, options);
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const opts = {
+          ...options,
+          env: envExplicit ? options.env : undefined
+        };
+        await runTestIntegrationCommand(appName, opts);
       } catch (error) {
         handleCommandError(error, 'test-integration');
         process.exit(1);