@aifabrix/builder 2.41.0 → 2.42.1

package/lib/cli/setup-app.js

@@ -17,12 +17,20 @@ const { handleCommandError } = require('../utils/cli-utils');
  * @param {Object} options - Raw CLI options
  * @returns {Object} Normalized options
  */
+const VALID_ENTITY_TYPES = ['recordStorage', 'documentStorage', 'vectorStore', 'messageService', 'none'];
+
 function normalizeExternalOptions(options) {
   const normalized = { ...options };
   if (options.displayName) normalized.systemDisplayName = options.displayName;
   if (options.description) normalized.systemDescription = options.description;
   if (options.systemType) normalized.systemType = options.systemType;
   if (options.authType) normalized.authType = options.authType;
+  if (options.entityType) {
+    if (!VALID_ENTITY_TYPES.includes(options.entityType)) {
+      throw new Error(`Invalid --entity-type. Must be one of: ${VALID_ENTITY_TYPES.join(', ')}`);
+    }
+    normalized.entityType = options.entityType;
+  }
   if (options.datasources !== undefined) {
     const parsedCount = parseInt(options.datasources, 10);
     if (Number.isNaN(parsedCount) || parsedCount < 1 || parsedCount > 10) {
@@ -48,6 +56,7 @@ function validateNonInteractiveExternalOptions(normalizedOptions) {
   if (!normalizedOptions.systemDescription) missing.push('--description');
   if (!normalizedOptions.systemType) missing.push('--system-type');
   if (!normalizedOptions.authType) missing.push('--auth-type');
+  if (!normalizedOptions.entityType) missing.push('--entity-type');
   if (!normalizedOptions.datasourceCount) missing.push('--datasources');
   if (missing.length > 0) {
     throw new Error(`Missing required options for non-interactive external create: ${missing.join(', ')}`);
@@ -75,14 +84,14 @@ async function handleCreateCommand(appName, options) {
   const wizardOptions = { app: appName, ...options };
   const normalizedOptions = normalizeExternalOptions(options);
 
-  const isExternalType = options.type === 'external';
+  const isExternalType = options.type === 'external' || !options.type;
   const isNonInteractive = process.stdin && process.stdin.isTTY === false;
 
   if (isExternalType && !options.wizard && isNonInteractive) {
     validateNonInteractiveExternalOptions(normalizedOptions);
   }
 
-  const shouldUseWizard = options.wizard && (options.type === 'external' || (!options.type && validTypes.includes('external')));
+  const shouldUseWizard = options.wizard && (options.type === 'external' || !options.type);
   if (shouldUseWizard) {
     const { handleWizard } = require('../commands/wizard');
     await handleWizard(wizardOptions);
@@ -101,7 +110,7 @@ function setupCreateCommand(program) {
     .option('-a, --authentication', 'Requires authentication/RBAC')
     .option('-l, --language <lang>', 'Runtime language (typescript/python)')
     .option('-t, --template <name>', 'Template to use (e.g., miso-controller, keycloak)')
-    .option('--type <type>', 'Application type (webapp, api, service, functionapp, external)', 'webapp')
+    .option('--type <type>', 'Application type (webapp, api, service, functionapp, external)', 'external')
     .option('--app', 'Generate minimal application files (package.json, index.ts or requirements.txt, main.py)')
     .option('-g, --github', 'Generate GitHub Actions workflows')
     .option('--github-steps <steps>', 'Extra GitHub workflow steps (comma-separated, e.g., npm,test)')
@@ -110,7 +119,8 @@ function setupCreateCommand(program) {
     .option('--display-name <name>', 'External system display name')
     .option('--description <desc>', 'External system description')
     .option('--system-type <type>', 'External system type (openapi, mcp, custom)')
-    .option('--auth-type <type>', 'External system auth type (oauth2, apikey, basic)')
+    .option('--auth-type <type>', 'External system auth type (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none)')
+    .option('--entity-type <type>', 'Entity type for datasources (recordStorage, documentStorage, vectorStore, messageService, none)')
     .option('--datasources <count>', 'Number of datasources to create')
     .action(async(appName, options) => {
       try {
@@ -130,6 +140,7 @@ Examples:
   $ aifabrix wizard my-integration --silent  Run headless with integration/my-integration/wizard.yaml (no prompts)
   $ aifabrix wizard -a my-integration   Same as above (app name set)
   $ aifabrix wizard --config wizard.yaml  Run headless from a wizard config file
+  $ aifabrix wizard hubspot-test-v2 --debug  Enable debug output and save debug manifests on validation failure
 
 Config path: When appName is provided, integration/<appName>/wizard.yaml is used for load/save and error.log.
 To change settings after a run, edit that file and run "aifabrix wizard <app>" again.
@@ -140,6 +151,7 @@ See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`;
     .option('-a, --app <app>', 'Application name (synonym for positional appName)')
     .option('--config <file>', 'Run headless using a wizard.yaml file (appName, mode, source, credential, preferences)')
     .option('--silent', 'Run with saved integration/<app>/wizard.yaml only; no prompts (requires app name and existing wizard.yaml)')
+    .option('--debug', 'Enable debug output and save debug manifests on validation failure')
     .addHelpText('after', wizardHelp)
     .action(async(positionalAppName, options) => {
       try {
@@ -280,6 +292,29 @@ function setupShellTestStopCommands(program) {
     });
 }
 
+async function runTestE2ECommand(appName, options) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (appType && appType.baseDir === 'integration') {
+    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+    const { success, results } = await runTestE2EForExternalSystem(appName, {
+      env: options.env,
+      debug: options.debug,
+      verbose: options.verbose,
+      async: options.async !== false
+    });
+    results.forEach(r => {
+      const icon = r.success ? chalk.green('✓') : chalk.red('✗');
+      const msg = r.error ? `${r.key}: ${r.error}` : r.key;
+      logger.log(`  ${icon} ${msg}`);
+    });
+    if (!success) process.exit(1);
+    return;
+  }
+  const { runAppTestE2e } = require('../commands/app-test');
+  await runAppTestE2e(appName, { env: options.env });
+}
+
 function setupInstallTestE2eLintCommands(program) {
   program.command('install <app>')
     .description('Install dependencies in container (builder apps only)')
@@ -301,18 +336,14 @@ function setupInstallTestE2eLintCommands(program) {
     });
 
   program.command('test-e2e <app>')
-    .description('Run e2e tests in container (builder apps only)')
-    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .description('Run e2e tests (builder: in container; external system: all datasources via dataplane)')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)')
+    .option('-v, --verbose', 'Show detailed step output and poll progress')
+    .option('--debug', 'Include debug output and write log to integration/<app>/logs/')
+    .option('--no-async', 'Use sync mode (no polling); single POST per datasource')
     .action(async(appName, options) => {
       try {
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
-          logger.log(chalk.gray('test-e2e is for builder applications only. Use aifabrix shell <app> then make test:e2e or pnpm test:e2e.'));
-          return;
-        }
-        const { runAppTestE2e } = require('../commands/app-test');
-        await runAppTestE2e(appName, { env: options.env });
+        await runTestE2ECommand(appName, options);
       } catch (error) {
         handleCommandError(error, 'test-e2e');
         process.exit(1);

package/lib/cli/setup-credential-deployment.js

@@ -11,8 +11,37 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const { runCredentialList } = require('../commands/credential-list');
+const { runCredentialEnv } = require('../commands/credential-env');
+const { runCredentialPush } = require('../commands/credential-push');
 const { runDeploymentList } = require('../commands/deployment-list');
 
+function setupCredentialEnvAndPush(credential) {
+  credential
+    .command('env <system-key>')
+    .description('Prompt for KV_* credential values and write integration/<system-key>/.env')
+    .action(async(systemKey, _options) => {
+      try {
+        await runCredentialEnv(systemKey);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'credential env');
+        process.exit(1);
+      }
+    });
+  credential
+    .command('push <system-key>')
+    .description('Push credential secrets from .env to Dataplane (KV_* vars)')
+    .action(async(systemKey, _options) => {
+      try {
+        await runCredentialPush(systemKey);
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        handleCommandError(error, 'credential push');
+        process.exit(1);
+      }
+    });
+}
+
 /**
  * Sets up credential and deployment list commands
  * @param {Command} program - Commander program instance
@@ -21,19 +50,15 @@ function setupCredentialDeploymentCommands(program) {
   const credential = program
     .command('credential')
     .description('Manage credentials');
-
+  setupCredentialEnvAndPush(credential);
   credential
     .command('list')
-    .description('List credentials from Dataplane (GET /api/v1/credential). Controller does not expose this endpoint.')
-    .option('--controller <url>', 'Controller URL (default: from config)')
-    .option('--dataplane <url>', 'Dataplane URL (default: resolved from controller + environment)')
+    .description('Get credentials from Dataplane')
     .option('--active-only', 'List only active credentials')
     .option('--page-size <n>', 'Items per page', '50')
     .action(async(options) => {
       try {
         const opts = {
-          controller: options.controller,
-          dataplane: options.dataplane,
           activeOnly: options.activeOnly,
           pageSize: parseInt(options.pageSize, 10) || 50
         };

package/lib/cli/setup-dev.js

@@ -33,6 +33,7 @@ async function displayDevConfig(devId) {
   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() },
@@ -59,6 +60,18 @@ async function displayDevConfig(devId) {
   logger.log('');
 }
 
+/**
+ * Handle dev set-format command
+ * @param {string} format - Format value (json | yaml)
+ * @returns {Promise<void>}
+ */
+async function handleSetFormat(format) {
+  await config.setFormat(format);
+  logger.log(chalk.green(`✓ Format set to ${format.toLowerCase()}`));
+  const devId = await config.getDeveloperId();
+  await displayDevConfig(devId);
+}
+
 /**
  * Register dev config and set-id commands.
  * @param {Command} dev - dev subcommand group
@@ -90,6 +103,18 @@ function setupDevConfigCommands(dev) {
       }
     });
 
+  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');
+        process.exit(1);
+      }
+    });
+
   dev
     .command('set-id <id>')
     .description('Set developer ID (convenience alias for "dev config --set-id")')
@@ -121,6 +146,8 @@ function setupDevInitCommand(dev) {
     .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);

package/lib/cli/setup-environment.js

@@ -25,30 +25,38 @@ function setupEnvironmentCommands(program) {
 
   const environment = program
     .command('environment')
-    .description('Manage environments');
+    .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`;
 
   environment
     .command('deploy <env>')
-    .description('Deploy/setup environment in Miso Controller')
+    .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 = program
     .command('env')
-    .description('Environment management (alias for environment)');
+    .description('Deploy and manage Miso Controller environments (alias for environment)');
 
   env
     .command('deploy <env>')
-    .description('Deploy/setup environment in Miso Controller')
+    .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);
 }
 

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

@@ -1,9 +1,17 @@
 /**
- * CLI external system command setup (download, delete, test, test-integration).
+ * 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
+ * - test-integration <app> – Run integration tests (builder: in container; external: via dataplane pipeline)
  *
  * @fileoverview External system command definitions for AI Fabrix Builder CLI
  * @author AI Fabrix Team
  * @version 2.0.0
+ * @see docs/commands/external-integration.md - User-facing command reference
+ * @see docs/external-systems.md - External systems guide and workflow
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
@@ -11,11 +19,18 @@ const { handleCommandError } = require('../utils/cli-utils');
 function setupDownloadCommand(program) {
   program.command('download <system-key>')
     .description('Download external system from dataplane to local development structure')
+    .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')
     .action(async(systemKey, options) => {
       try {
+        const config = require('../core/config');
+        const effectiveFormat = (options.format || (await config.getFormat()) || 'yaml').trim().toLowerCase();
+        if (effectiveFormat !== 'json' && effectiveFormat !== 'yaml') {
+          throw new Error('Option --format must be \'json\' or \'yaml\'');
+        }
         const download = require('../external-system/download');
-        await download.downloadExternalSystem(systemKey, options);
+        await download.downloadExternalSystem(systemKey, { ...options, format: effectiveFormat });
       } catch (error) {
         handleCommandError(error, 'download');
         process.exit(1);
@@ -27,7 +42,6 @@ function setupUploadCommand(program) {
   program.command('upload <system-key>')
     .description('Upload external system to dataplane (upload → validate → publish; no controller deploy)')
     .option('--dry-run', 'Validate and build payload only; no API calls')
-    .option('--dataplane <url>', 'Dataplane URL (default: discovered from controller)')
     .action(async(systemKey, options) => {
       try {
         const upload = require('../commands/upload');
@@ -97,7 +111,7 @@ async function tryBuilderTestIntegration(appName, options) {
  */
 async function runExternalSystemTestIntegration(appName, options) {
   const test = require('../external-system/test');
-  const opts = { ...options, environment: options.env || options.environment };
+  const opts = { ...options, environment: options.env || options.environment, debug: options.debug };
   const results = await test.testExternalSystemIntegration(appName, opts);
   test.displayIntegrationTestResults(results, options.verbose);
   if (!results.success) process.exit(1);
@@ -131,6 +145,7 @@ function setupExternalSystemTestCommands(program) {
     .option('-p, --payload <file>', 'Path to custom test payload file')
     .option('-e, --env <env>', 'Environment: dev, tst, or pro (default: from aifabrix auth config)')
     .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) => {
       try {

package/lib/cli/setup-infra.js

@@ -19,8 +19,34 @@ const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
 
 /**
- * Runs the up-infra command: resolves developer ID, traefik, and starts infra.
- * @param {Object} options - Commander options (developer, traefik)
+ * Persists optional service flag to config when explicitly set.
+ * @param {Object} cfg - Config object (mutated)
+ * @param {string} key - Config key (traefik, pgadmin, redisCommander)
+ * @param {boolean} value - Value to set
+ * @param {string} label - Label for log message
+ */
+async function persistOptionalServiceFlag(cfg, key, value, label) {
+  cfg[key] = value;
+  await config.saveConfig(cfg);
+  logger.log(chalk.green(`✓ ${label} ${value ? 'enabled' : 'disabled'} and saved to config`));
+}
+
+/**
+ * Resolves effective boolean from option vs config.
+ * @param {*} optValue - options.traefik | options.pgAdmin | options.redisAdmin
+ * @param {*} cfgValue - cfg.traefik | cfg.pgadmin | cfg.redisCommander
+ * @param {boolean} defaultWhenUndef - Default when config value is undefined
+ * @returns {boolean}
+ */
+function resolveFlag(optValue, cfgValue, defaultWhenUndef = true) {
+  if (optValue === true) return true;
+  if (optValue === false) return false;
+  return cfgValue !== false && (cfgValue === true || defaultWhenUndef);
+}
+
+/**
+ * Runs the up-infra command: resolves developer ID, traefik, pgAdmin, redisAdmin, and starts infra.
+ * @param {Object} options - Commander options (developer, traefik, pgAdmin, redisAdmin)
  * @returns {Promise<void>}
  */
 async function runUpInfraCommand(options) {
@@ -37,24 +63,33 @@ async function runUpInfraCommand(options) {
     logger.log(chalk.green(`✓ Developer ID set to ${id}`));
   }
   const cfg = await config.getConfig();
-  if (options.traefik === true) {
-    cfg.traefik = true;
-    await config.saveConfig(cfg);
-    logger.log(chalk.green('✓ Traefik enabled and saved to config'));
-  } else if (options.traefik === false) {
-    cfg.traefik = false;
-    await config.saveConfig(cfg);
-    logger.log(chalk.green('✓ Traefik disabled and saved to config'));
+  const flagSpecs = [
+    { opt: options.traefik, key: 'traefik', label: 'Traefik' },
+    { opt: options.pgAdmin, key: 'pgadmin', label: 'pgAdmin' },
+    { opt: options.redisAdmin, key: 'redisCommander', label: 'Redis Commander' }
+  ];
+  for (const { opt, key, label } of flagSpecs) {
+    if (opt === true || opt === false) {
+      await persistOptionalServiceFlag(cfg, key, opt, label);
+    }
   }
-  const useTraefik = options.traefik === true ? true : (options.traefik === false ? false : !!(cfg.traefik));
-  await infra.startInfra(developerId, { traefik: useTraefik, adminPwd: options.adminPwd });
+  await infra.startInfra(developerId, {
+    traefik: resolveFlag(options.traefik, cfg.traefik, false),
+    pgadmin: resolveFlag(options.pgAdmin, cfg.pgadmin, true),
+    redisCommander: resolveFlag(options.redisAdmin, cfg.redisCommander, true),
+    adminPwd: options.adminPwd
+  });
 }
 
 function setupUpInfraCommand(program) {
   program.command('up-infra')
-    .description('Start local infrastructure: Postgres, Redis, optional Traefik')
+    .description('Start local infrastructure: Postgres, Redis, optional pgAdmin, Redis Commander, Traefik')
     .option('-d, --developer <id>', 'Set developer ID and start infrastructure')
     .option('--adminPwd <password>', 'Override default admin password for new install (Postgres, pgAdmin, Redis Commander)')
+    .option('--pgAdmin', 'Include pgAdmin web UI and save to config')
+    .option('--no-pgAdmin', 'Exclude pgAdmin and save to config')
+    .option('--redisAdmin', 'Include Redis Commander web UI and save to config')
+    .option('--no-redisAdmin', 'Exclude Redis Commander and save to config')
     .option('--traefik', 'Include Traefik reverse proxy and save to config')
     .option('--no-traefik', 'Exclude Traefik and save to config')
     .action(async(options) => {
@@ -175,7 +210,12 @@ function setupDoctorCommand(program) {
         }
         if (result.docker === 'ok') {
           try {
-            const health = await infra.checkInfraHealth();
+            const cfg = await config.getConfig();
+            const health = await infra.checkInfraHealth(null, {
+              pgadmin: cfg.pgadmin !== false,
+              redisCommander: cfg.redisCommander !== false,
+              traefik: !!cfg.traefik
+            });
             logger.log('\n🏥 Infrastructure Health:');
             Object.entries(health).forEach(([service, status]) => {
               const icon = status === 'healthy' ? '✅' : status === 'unknown' ? '❓' : '❌';

package/lib/cli/setup-utility.js

@@ -77,9 +77,13 @@ function logSplitJsonResult(result) {
     result.datasourceFiles.forEach(filePath => logger.log(`  • datasource: ${filePath}`));
   }
   if (result.rbac) {
-    logger.log(`  • rbac.yml: ${result.rbac}`);
+    logger.log(`  • rbac.yaml: ${result.rbac}`);
+  }
+  if (result.readmeSkipped) {
+    logger.log(`  • README.md: (kept existing) ${result.readmeSkipped}`);
+  } else if (result.readme) {
+    logger.log(`  • README.md: ${result.readme}`);
   }
-  logger.log(`  • README.md: ${result.readme}`);
 }
 
 function setupResolveCommand(program) {
@@ -141,7 +145,7 @@ function setupJsonCommand(program) {
     });
 }
 
-function setupSplitJsonConvertShowCommands(program) {
+function setupSplitJsonCommand(program) {
   program.command('split-json <app>')
     .description('Split deployment JSON into component files (env.template, application.yaml, rbac.yml, README.md)')
     .option('-o, --output <dir>', 'Output directory for component files (defaults to same directory as JSON)')
@@ -153,15 +157,66 @@ function setupSplitJsonConvertShowCommands(program) {
         process.exit(1);
       }
     });
+}
 
+function setupRepairCommand(program) {
+  program.command('repair <app>')
+    .description('Repair external integration config: fix drift (file lists, app key, datasource alignment, rbac, manifest)')
+    .option('--auth <method>', 'Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template')
+    .option('--dry-run', 'Report changes only; do not write')
+    .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
+    .option('--expose', 'Set exposed.attributes on each datasource to all fieldMappings.attributes keys')
+    .option('--sync', 'Add default sync section to datasources that lack it')
+    .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
+    .action(async(appName, options) => {
+      try {
+        const { repairExternalIntegration } = require('../commands/repair');
+        const { detectAppType } = require('../utils/paths');
+        const { appPath } = await detectAppType(appName);
+        logOfflinePathWhenType(appPath);
+        const result = await repairExternalIntegration(appName, {
+          auth: options.auth,
+          dryRun: options.dryRun,
+          rbac: options.rbac,
+          expose: options.expose,
+          sync: options.sync,
+          test: options.test
+        });
+        if (options.dryRun && result.updated && result.changes.length > 0) {
+          logger.log(chalk.yellow('\nWould apply:'));
+          result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
+        } else if (result.updated) {
+          logger.log(chalk.green('\n✓ Repaired external integration config.'));
+        } else {
+          logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
+        }
+      } catch (error) {
+        handleCommandError(error, 'repair');
+        process.exit(1);
+      }
+    });
+}
+
+function setupConvertCommand(program) {
   program.command('convert <app>')
     .description('Convert integration/external system and datasource config files between JSON and YAML')
-    .option('--format <format>', 'Target format: json | yaml (required)')
+    .option('--format <format>', 'Target format: json | yaml (required unless config format is set)')
     .option('-f, --force', 'Skip confirmation prompt')
     .action(async(appName, options) => {
       try {
+        const config = require('../core/config');
+        const effectiveFormat = options.format || (await config.getFormat());
+        if (!effectiveFormat) {
+          throw new Error(
+            'Option --format is required and must be \'json\' or \'yaml\' (or set default with aifabrix dev set-format)'
+          );
+        }
+        const normalized = effectiveFormat.trim().toLowerCase();
+        if (normalized !== 'json' && normalized !== 'yaml') {
+          throw new Error('Option --format must be \'json\' or \'yaml\'');
+        }
         const { runConvert } = require('../commands/convert');
-        const { converted, deleted } = await runConvert(appName, { format: options.format, force: options.force });
+        const { converted, deleted } = await runConvert(appName, { format: normalized, force: options.force });
         logger.log(chalk.green('\n✓ Convert complete.'));
         converted.forEach(p => logger.log(`  • ${p}`));
         if (deleted.length > 0) {
@@ -173,7 +228,9 @@ function setupSplitJsonConvertShowCommands(program) {
         process.exit(1);
       }
     });
+}
 
+function setupShowCommand(program) {
   program.command('show <appKey>')
     .description('Show application info from local builder/ or integration/ (offline) or from controller (--online)')
     .option('--online', 'Fetch application data from the controller')
@@ -189,25 +246,60 @@ function setupSplitJsonConvertShowCommands(program) {
     });
 }
 
+function setupSplitJsonConvertShowCommands(program) {
+  setupSplitJsonCommand(program);
+  setupRepairCommand(program);
+  setupConvertCommand(program);
+  setupShowCommand(program);
+}
+
+async function runValidateCommand(appOrFile, options) {
+  const validate = require('../validation/validate');
+  const opts = options.opts ? options.opts() : options;
+  const integration = opts.integration === true;
+  const builder = opts.builder === true;
+  const outFormat = (opts.format || 'default').toLowerCase();
+
+  if (integration || builder) {
+    const batchResult = integration && builder
+      ? await validate.validateAll(opts)
+      : integration
+        ? await validate.validateAllIntegrations(opts)
+        : await validate.validateAllBuilderApps(opts);
+    if (outFormat === 'json') {
+      logger.log(JSON.stringify(batchResult, null, 2));
+    } else {
+      validate.displayBatchValidationResults(batchResult);
+    }
+    if (!batchResult.valid) process.exit(1);
+    return;
+  }
+
+  if (!appOrFile || typeof appOrFile !== 'string') {
+    logger.log(chalk.red('App name or file path is required, or use --integration / --builder'));
+    process.exit(1);
+  }
+
+  const result = await validate.validateAppOrFile(appOrFile, opts);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify(result, null, 2));
+  } else {
+    validate.displayValidationResults(result);
+  }
+  if (!result.valid) process.exit(1);
+}
+
 function setupValidateDiffCommands(program) {
-  program.command('validate <appOrFile>')
-    .description('Validate application or external integration file')
+  program.command('validate [appOrFile]')
+    .description('Validate application or external integration file; use --integration or --builder to validate all apps')
     .option('--format <format>', 'Output format: json | default (human-readable)')
-    .action(async(appOrFile, options) => {
-      try {
-        const validate = require('../validation/validate');
-        const result = await validate.validateAppOrFile(appOrFile, options);
-        const outFormat = (options.format || 'default').toLowerCase();
-        if (outFormat === 'json') {
-          logger.log(JSON.stringify(result, null, 2));
-        } else {
-          validate.displayValidationResults(result);
-        }
-        if (!result.valid) process.exit(1);
-      } catch (error) {
+    .option('--integration', 'Validate all applications under integration/')
+    .option('--builder', 'Validate all applications under builder/')
+    .action((appOrFile, options) => {
+      runValidateCommand(appOrFile, options).catch((error) => {
         handleCommandError(error, 'validate');
         process.exit(1);
-      }
+      });
     });
 
   program.command('diff <file1> <file2>')
@@ -238,4 +330,8 @@ function setupUtilityCommands(program) {
   setupValidateDiffCommands(program);
 }
 
-module.exports = { setupUtilityCommands };
+module.exports = {
+  setupUtilityCommands,
+  resolveSplitJsonApp,
+  handleSplitJsonCommand
+};