@aifabrix/builder 2.42.1 → 2.44.0

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,57 +102,59 @@ 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);
 }
 
 /**
- * Register dev config and set-id commands.
+ * Register dev show and set-id commands.
  * @param {Command} dev - dev subcommand group
  */
-function setupDevConfigCommands(dev) {
+function setupDevShowAndSetId(dev) {
   dev
-    .command('config')
-    .description('Show or set developer configuration')
-    .option('--set-id <id>', 'Set developer ID')
-    .action(async(options) => {
+    .command('show')
+    .description('Show dev ports and ~/.aifabrix config')
+    .action(async() => {
       try {
-        const setIdValue = options.setId || options['set-id'];
-        if (setIdValue) {
-          const digitsOnly = /^[0-9]+$/.test(setIdValue);
-          if (!digitsOnly) {
-            throw new Error('Developer ID must be a non-negative digit string (0 = default infra, > 0 = developer-specific)');
-          }
-          await config.setDeveloperId(setIdValue);
-          process.env.AIFABRIX_DEVELOPERID = setIdValue;
-          logger.log(chalk.green(`✓ Developer ID set to ${setIdValue}`));
-          await displayDevConfig(setIdValue);
-          return;
-        }
         const devId = await config.getDeveloperId();
         await displayDevConfig(devId);
       } catch (error) {
-        handleCommandError(error, 'dev config');
-        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 show');
         process.exit(1);
       }
     });
 
   dev
     .command('set-id <id>')
-    .description('Set developer ID (convenience alias for "dev config --set-id")')
+    .description('Set developer ID (0 = default infra, >0 = dev-specific ports)')
     .action(async(id) => {
       try {
         const digitsOnly = /^[0-9]+$/.test(id);
@@ -126,40 +163,83 @@ function setupDevConfigCommands(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 init and refresh commands.
- * @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) => {
+    .command('set-scoped-resources <value>')
+    .description('Set useEnvironmentScopedResources to true|false in ~/.aifabrix/config.yaml')
+    .action(async(value) => {
       try {
-        await runDevInit(options);
+        await handleSetScopedResources(value);
       } catch (error) {
-        handleCommandError(error, 'dev init');
+        handleCommandError(error, 'dev set-scoped-resources');
         process.exit(1);
       }
     });
+}
+
+/**
+ * Register dev show, set-id, set-env-config, set-home and set-format commands.
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevConfigCommands(dev) {
+  setupDevShowAndSetId(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)');
+}
+
+/**
+ * Register dev init and refresh commands.
+ * @param {Command} dev - dev subcommand group
+ */
+function setupDevInitCommand(dev) {
+  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 {
@@ -178,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();
@@ -190,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);
@@ -212,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);
@@ -228,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);
@@ -240,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);
@@ -252,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 {
@@ -281,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

@@ -1,5 +1,5 @@
 /**
- * CLI environment deployment command setup (environment deploy, env deploy).
+ * CLI environment deployment command setup (env deploy).
  *
  * @fileoverview Environment command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
@@ -18,35 +18,26 @@ function setupEnvironmentCommands(program) {
       const environmentDeploy = require('../deployment/environment');
       await environmentDeploy.deployEnvironment(envKey, options);
     } catch (error) {
-      handleCommandError(error, 'environment deploy');
+      handleCommandError(error, 'env deploy');
       process.exit(1);
     }
   };
 
-  const environment = program
-    .command('environment')
-    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
-
   const deployExamples = `
 Examples:
-  $ aifabrix environment deploy dev
-  $ aifabrix environment deploy tst --preset m
-  $ aifabrix environment deploy dev --config ./env-config.json --no-poll`;
+  $ aifabrix env deploy dev
+  $ aifabrix env deploy tst --preset m
+  $ aifabrix env deploy dev --config ./env-config.json --no-poll`;
 
-  environment
-    .command('deploy <env>')
-    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
-    .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
-    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
-    .option('--skip-validation', 'Skip environment validation')
-    .option('--poll', 'Poll for deployment status', true)
-    .option('--no-poll', 'Do not poll for status')
-    .addHelpText('after', deployExamples)
-    .action(deployEnvHandler);
+  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 (alias for environment)');
+    .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,11 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+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 +40,24 @@ 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')
     .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,
+          probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000
+        });
       } catch (error) {
         handleCommandError(error, 'upload');
         process.exit(1);
@@ -54,9 +66,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,9 +123,15 @@ 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);
+  test.displayIntegrationTestResults(results, options.verbose, { debug: options.debug, runType: 'integration' });
   if (!results.success) process.exit(1);
 }
 
@@ -126,6 +144,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 +157,39 @@ 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>)'
+    )
+    .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);