@aifabrix/builder 2.43.0 → 2.44.0

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);

package/lib/cli/setup-infra.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI infrastructure command setup (up-infra, up-platform, up-miso, up-dataplane, down-infra, doctor, status, restart).
  *
@@ -18,6 +19,22 @@ const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
 const { cleanBuilderAppDirs } = require('../commands/up-common');
+const {
+  loadInfraStatusSummary,
+  formatInfraStatusTitleLine,
+  logInfraStatusConfigurationSummary,
+  logPaddedFieldRow
+} = require('../utils/infra-status-display');
+
+const UP_INFRA_HELP_AFTER = `
+Typical sequence:
+  $ aifabrix up-infra
+  $ aifabrix up-platform
+  Or: aifabrix up-miso, then aifabrix up-dataplane (login required for dataplane)
+
+Full bootstrap example (Traefik, TLS flag, pgAdmin, catalog overrides — matches shipped defaults in infra.parameter.yaml):
+  $ aifabrix up-infra --traefik --tls --adminPassword admin123 --adminEmail admin@aifabrix.dev --userPassword user123 --pgAdmin
+`;
 
 /**
  * Persists optional service flag to config when explicitly set.
@@ -29,7 +46,29 @@ const { cleanBuilderAppDirs } = require('../commands/up-common');
 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`));
+  logger.log(formatSuccessLine(`${label} ${value ? 'enabled' : 'disabled'} and saved to config`));
+}
+
+/**
+ * Persists TLS mode for ${TLS_ENABLED} / ${HTTP_ENABLED} in application.yaml / deployment manifest interpolation.
+ * @param {Object} cfg - Config object (mutated)
+ * @param {boolean} value - Whether TLS mode is on
+ */
+async function persistTlsEnabledFlag(cfg, value) {
+  cfg.tlsEnabled = value;
+  await config.saveConfig(cfg);
+  const tlsStr = value ? 'true' : 'false';
+  const httpStr = value ? 'false' : 'true';
+  logger.log(
+    chalk.green(
+      `✔ TLS mode ${value ? 'enabled' : 'disabled'} and saved to config (` +
+        '${TLS_ENABLED}=' +
+        tlsStr +
+        ', ${HTTP_ENABLED}=' +
+        httpStr +
+        ' when generating deployment JSON)'
+    )
+  );
 }
 
 /**
@@ -46,24 +85,26 @@ function resolveFlag(optValue, cfgValue, defaultWhenUndef = true) {
 }
 
 /**
- * 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>}
+ * @param {Object} options - Commander options
+ * @returns {Promise<number|null>} Developer ID or null
  */
-async function runUpInfraCommand(options) {
-  await config.ensureSecretsEncryptionKey();
-  let developerId = null;
-  if (options.developer) {
-    const id = parseInt(options.developer, 10);
-    if (isNaN(id) || id < 0) {
-      throw new Error('Developer ID must be a non-negative number (0 = default infra, > 0 = developer-specific)');
-    }
-    await config.setDeveloperId(id);
-    process.env.AIFABRIX_DEVELOPERID = id.toString();
-    developerId = id;
-    logger.log(chalk.green(`✓ Developer ID set to ${id}`));
+async function applyDeveloperIdFromUpInfra(options) {
+  if (!options.developer) return null;
+  const id = parseInt(options.developer, 10);
+  if (isNaN(id) || id < 0) {
+    throw new Error('Developer ID must be a non-negative number (0 = default infra, > 0 = developer-specific)');
   }
-  const cfg = await config.getConfig();
+  await config.setDeveloperId(id);
+  process.env.AIFABRIX_DEVELOPERID = id.toString();
+  logger.log(formatSuccessLine(`Developer ID set to ${id}`));
+  return id;
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} cfg - Mutable config from getConfig()
+ */
+async function persistOptionalInfraFlagsFromCli(options, cfg) {
   const flagSpecs = [
     { opt: options.traefik, key: 'traefik', label: 'Traefik' },
     { opt: options.pgAdmin, key: 'pgadmin', label: 'pgAdmin' },
@@ -74,25 +115,59 @@ async function runUpInfraCommand(options) {
       await persistOptionalServiceFlag(cfg, key, opt, label);
     }
   }
+}
+
+/**
+ * @param {Object} options
+ * @param {Object} cfg
+ */
+async function maybePersistTlsFromUpInfra(options, cfg) {
+  // Commander maps --no-tls to options.tls === false (not a separate notls flag).
+  if (options.tls === true) await persistTlsEnabledFlag(cfg, true);
+  else if (options.tls === false) await persistTlsEnabledFlag(cfg, false);
+}
+
+/**
+ * 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) {
+  await config.ensureSecretsEncryptionKey();
+  const developerId = await applyDeveloperIdFromUpInfra(options);
+  const cfg = await config.getConfig();
+  await persistOptionalInfraFlagsFromCli(options, cfg);
+  await maybePersistTlsFromUpInfra(options, cfg);
+  const adminPass = options.adminPassword || options.adminPwd;
+  const tlsEnabledEffective = cfg.tlsEnabled === true;
   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
+    adminPassword: adminPass,
+    adminPwd: adminPass,
+    adminEmail: options.adminEmail,
+    userPassword: options.userPassword,
+    tlsEnabled: tlsEnabledEffective
   });
 }
 
 function setupUpInfraCommand(program) {
   program.command('up-infra')
-    .description('Start local infrastructure: Postgres, Redis, optional pgAdmin, Redis Commander, Traefik')
+    .description('Start Postgres, Redis; optional pgAdmin, Redis Commander, Traefik')
+    .addHelpText('after', UP_INFRA_HELP_AFTER)
     .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('--adminPassword <password>', 'Override {{adminPassword}} defaults (Postgres, pgAdmin, Redis Commander, catalog literals)')
+    .option('--adminEmail <email>', 'Override {{adminEmail}} default (e.g. pgAdmin login email)')
+    .option('--userPassword <password>', 'Override {{userPassword}} default (e.g. Keycloak default user password)')
     .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')
+    .option('--tls', 'Enable TLS mode; save tlsEnabled (${TLS_ENABLED}=true, ${HTTP_ENABLED}=false in application.yaml)')
+    .option('--no-tls', 'Disable TLS mode (${TLS_ENABLED}=false, ${HTTP_ENABLED}=true)')
     .action(async(options) => {
       try {
         await runUpInfraCommand(options);
@@ -105,7 +180,7 @@ function setupUpInfraCommand(program) {
 
 function setupUpPlatformCommand(program) {
   program.command('up-platform')
-    .description('Start platform (Keycloak, Miso Controller, Dataplane) from community images; infra must be up')
+    .description('Start Keycloak, Miso Controller, dataplane from images (needs up-infra)')
     .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1, dataplane=myreg/d:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
@@ -138,7 +213,7 @@ function setupUpPlatformCommand(program) {
 
 function setupUpMisoCommand(program) {
   program.command('up-miso')
-    .description('Install keycloak and miso-controller from images (no build). Infra must be up. For dataplane use up-dataplane. Uses auto-generated secrets for testing.')
+    .description('Start Keycloak + Miso Controller from images only (no dataplane; needs up-infra)')
     .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
@@ -158,7 +233,7 @@ function setupUpMisoCommand(program) {
 
 function setupUpDataplaneCommand(program) {
   program.command('up-dataplane')
-    .description('Register, deploy, then run dataplane app locally in dev (always local deployment; requires login, environment must be dev)')
+    .description('Register, deploy, run dataplane locally (dev env; login required)')
     .option('-r, --registry <url>', 'Override registry for dataplane image')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <ref>', 'Override dataplane image reference (e.g. myreg/dataplane:latest)')
@@ -189,8 +264,8 @@ function setupUpDataplaneCommand(program) {
 }
 
 function setupDownInfraCommand(program) {
-  program.command('down-infra [app]')
-    .description('Stop and remove local infrastructure services or a specific application')
+  program.command('down-infra [service|app]')
+    .description('Stop all infra, or stop one app; use -v to remove volumes')
     .option('-v, --volumes', 'Remove volumes (deletes all data)')
     .action(async(appName, options) => {
       try {
@@ -209,14 +284,14 @@ function setupDownInfraCommand(program) {
 
 function setupDoctorCommand(program) {
   program.command('doctor')
-    .description('Check environment and configuration')
+    .description('Check Docker, ports, secrets, and infra health')
     .action(async() => {
       try {
         const result = await validator.checkEnvironment();
         logger.log('\n🔍 AI Fabrix Environment Check\n');
-        logger.log(`Docker: ${result.docker === 'ok' ? '✅ Running' : '❌ Not available'}`);
-        logger.log(`Ports: ${result.ports === 'ok' ? '✅ Available' : '⚠️  Some ports in use'}`);
-        logger.log(`Secrets: ${result.secrets === 'ok' ? '✅ Configured' : '❌ Missing'}`);
+        logger.log(`Docker: ${result.docker === 'ok' ? '✔ Running' : '✖ Not available'}`);
+        logger.log(`Ports: ${result.ports === 'ok' ? '✔ Available' : '⚠  Some ports in use'}`);
+        logger.log(`Secrets: ${result.secrets === 'ok' ? '✔ Configured' : '✖ Missing'}`);
         if (result.recommendations.length > 0) {
           logger.log('\n📋 Recommendations:');
           result.recommendations.forEach(rec => logger.log(`  • ${rec}`));
@@ -231,7 +306,7 @@ function setupDoctorCommand(program) {
             });
             logger.log('\n🏥 Infrastructure Health:');
             Object.entries(health).forEach(([service, status]) => {
-              const icon = status === 'healthy' ? '✅' : status === 'unknown' ? '❓' : '❌';
+              const icon = status === 'healthy' ? '✔' : status === 'unknown' ? '❓' : '✖';
               logger.log(`  ${icon} ${service}: ${status}`);
             });
           } catch (error) {
@@ -248,17 +323,21 @@ function setupDoctorCommand(program) {
 
 function setupStatusCommand(program) {
   program.command('status')
-    .description('Show detailed infrastructure service status and running applications')
+    .description('Show infra services and running apps (ports, URLs)')
     .action(async() => {
       try {
+        const summary = await loadInfraStatusSummary();
         const status = await infra.getInfraStatus();
-        logger.log('\n📊 Infrastructure Status\n');
+        logger.log('');
+        logger.log(formatInfraStatusTitleLine(summary.devIdStr, summary.remoteServer));
+        logger.log('');
+        logInfraStatusConfigurationSummary(summary);
         Object.entries(status).forEach(([service, info]) => {
-          const icon = String(info.status).trim().toLowerCase() === 'running' ? '✅' : '❌';
-          logger.log(`${icon} ${service}:`);
-          logger.log(`   Status: ${info.status}`);
-          logger.log(`   Port: ${info.port}`);
-          logger.log(`   URL: ${info.url}`);
+          const icon = String(info.status).trim().toLowerCase() === 'running' ? '✔' : '✖';
+          logger.log(`${icon} ${service}`);
+          logPaddedFieldRow('Status', info.status);
+          logPaddedFieldRow('Port', info.port);
+          logPaddedFieldRow('URL', info.url);
           logger.log('');
         });
         const apps = await infra.getAppStatus();
@@ -266,12 +345,12 @@ function setupStatusCommand(program) {
           logger.log('📱 Running Applications\n');
           apps.forEach((appInfo) => {
             const s = String(appInfo.status).trim().toLowerCase();
-            const icon = s.includes('running') || s.includes('up') ? '✅' : '❌';
-            logger.log(`${icon} ${appInfo.name}:`);
-            logger.log(`   Container: ${appInfo.container}`);
-            logger.log(`   Port: ${appInfo.port}`);
-            logger.log(`   Status: ${appInfo.status}`);
-            logger.log(`   URL: ${appInfo.url}`);
+            const icon = s.includes('running') || s.includes('up') ? '✔' : '✖';
+            logger.log(`${icon} ${appInfo.name}`);
+            logPaddedFieldRow('Container', appInfo.container);
+            logPaddedFieldRow('Port', appInfo.port);
+            logPaddedFieldRow('Status', appInfo.status);
+            logPaddedFieldRow('URL', appInfo.url);
             logger.log('');
           });
         }
@@ -285,16 +364,16 @@ function setupStatusCommand(program) {
 const INFRA_SERVICES = ['postgres', 'redis', 'pgadmin', 'redis-commander', 'traefik'];
 
 function setupRestartCommand(program) {
-  program.command('restart <service>')
-    .description('Restart an infrastructure service or a Docker application (builder/<app>)')
+  program.command('restart <service|app>')
+    .description('Restart infra service (postgres, redis, …) or a builder/<app> container')
     .action(async(service) => {
       try {
         if (INFRA_SERVICES.includes(service)) {
           await infra.restartService(service);
-          logger.log(`✅ ${service} service restarted successfully`);
+          logger.log(`✔ ${service} service restarted successfully`);
         } else {
           await appLib.restartApp(service);
-          logger.log(`✅ ${service} restarted successfully`);
+          logger.log(`✔ ${service} restarted successfully`);
         }
       } catch (error) {
         handleCommandError(error, 'restart');

package/lib/cli/setup-parameters.js

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview parameters subcommand (validate kv:// catalog coverage)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { handleCommandError } = require('../utils/cli-utils');
+const { handleParametersValidate } = require('../commands/parameters-validate');
+
+/**
+ * @param {import('commander').Command} program - Commander program
+ */
+function setupParametersCommands(program) {
+  const parameters = program
+    .command('parameters')
+    .description('Infra parameter catalog (kv:// keys, generators, Azure naming hints)');
+
+  parameters
+    .command('validate')
+    .description('Check env.template kv:// references against lib/schema/infra.parameter.yaml')
+    .option('--catalog <path>', 'Override path to infra.parameter.yaml')
+    .action(async(opts) => {
+      try {
+        const result = await handleParametersValidate({ catalogPath: opts.catalog });
+        if (!result.valid) process.exit(1);
+      } catch (error) {
+        handleCommandError(error, 'parameters validate');
+      }
+    });
+}
+
+module.exports = { setupParametersCommands };

package/lib/cli/setup-secrets.js

@@ -6,7 +6,7 @@
  * @version 2.0.0
  */
 
-const chalk = require('chalk');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const { handleCommandError } = require('../utils/cli-utils');
 const { handleSecretsSet } = require('../commands/secrets-set');
 const { handleSecretsList } = require('../commands/secrets-list');
@@ -16,10 +16,101 @@ const { handleSecure } = require('../commands/secure');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 
+const SECRET_GROUP_HELP_AFTER = `
+Subcommands:
+  list, set, remove, remove-all   User secrets.local.yaml (add --shared for shared/remote)
+  set-secrets-file      Point config at a shared secrets file or https URL
+  validate              YAML structure (+ optional --naming)
+
+Also: aifabrix secure   Encrypt secrets.local.yaml (ISO 27001)
+
+Examples:
+  $ aifabrix secret list
+  $ aifabrix secret set myapp/clientSecret "your-value"
+  $ aifabrix secret remove old-key
+  $ aifabrix secret remove-all
+  $ aifabrix secret validate
+
+Shared over https: key BASH_NPM_TOKEN --shared → NPM_TOKEN available in terminal (exported).
+`;
+
+const SECRET_LIST_HELP_AFTER = `
+Examples:
+  $ aifabrix secret list
+  $ aifabrix secret list --shared
+`;
+
+const SECRET_SET_HELP_AFTER = `
+Examples:
+  $ aifabrix secret set myapp/clientSecret "your-secret"
+  $ aifabrix secret set hubspot/apiKey "$HUBSPOT_KEY"
+  $ aifabrix secret set team/shared-token "value" --shared
+  $ aifabrix secret set BASH_NPM_TOKEN "$NPM_TOKEN" --shared
+
+With https aifabrix-secrets: keys named BASH_<NAME> --shared expose <NAME> in your
+  terminal as an exported env var (e.g. BASH_NPM_TOKEN → NPM_TOKEN).
+`;
+
+const SECRET_REMOVE_HELP_AFTER = `
+Examples:
+  $ aifabrix secret remove deprecated-key
+  $ aifabrix secret remove shared-key --shared
+`;
+
+const SECRET_REMOVE_ALL_HELP_AFTER = `
+You will be asked to type "yes" to confirm unless you pass --yes.
+
+Examples:
+  $ aifabrix secret remove-all
+  $ aifabrix secret remove-all --yes
+  $ aifabrix secret remove-all --shared
+  $ aifabrix secret remove-all --shared --yes
+`;
+
+const SECRET_SET_SECRETS_FILE_HELP_AFTER = `
+Examples:
+  $ aifabrix secret set-secrets-file ./shared-secrets.yaml
+  $ aifabrix secret set-secrets-file https://dev.example.com/api/secrets
+  $ aifabrix secret set-secrets-file ""
+`;
+
+const SECRET_VALIDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix secret validate
+  $ aifabrix secret validate ./secrets.local.yaml
+  $ aifabrix secret validate --naming
+`;
+
+const SECURE_HELP_AFTER = `
+Examples:
+  $ aifabrix secure
+  $ aifabrix secure --secrets-encryption <32-byte-hex-or-base64>
+`;
+
+function setupSecretRemoveAllCommand(secretCmd) {
+  const { handleSecretsRemoveAll } = require('../commands/secrets-remove-all');
+  secretCmd
+    .command('remove-all')
+    .description('Remove all secret keys (requires typing "yes" unless --yes)')
+    .addHelpText('after', SECRET_REMOVE_ALL_HELP_AFTER)
+    .option('--shared', 'Remove all from shared secrets (file or remote API)')
+    .option('-y, --yes', 'Skip confirmation prompt (non-interactive / scripts)')
+    .action(async options => {
+      try {
+        await config.ensureSecretsEncryptionKey();
+        await handleSecretsRemoveAll(options);
+      } catch (error) {
+        handleCommandError(error, 'secret remove-all');
+        process.exit(1);
+      }
+    });
+}
+
 function setupSecretValidateCommand(secretCmd) {
   secretCmd
     .command('validate [path]')
     .description('Validate secrets file (YAML structure and optional naming convention)')
+    .addHelpText('after', SECRET_VALIDATE_HELP_AFTER)
     .option('--naming', 'Check key names against *KeyVault convention')
     .action(async(pathArg, options) => {
       try {
@@ -39,7 +130,8 @@ function setupSecretValidateCommand(secretCmd) {
  */
 function setupSecureCommand(program) {
   program.command('secure')
-    .description('Encrypt secrets in secrets.local.yaml files for ISO 27001 compliance')
+    .description('Encrypt secrets.local.yaml at rest (ISO 27001)')
+    .addHelpText('after', SECURE_HELP_AFTER)
     .option('--secrets-encryption <key>', 'Encryption key (32 bytes, hex or base64)')
     .action(async(options) => {
       try {
@@ -59,11 +151,13 @@ function setupSecureCommand(program) {
 function setupSecretsCommands(program) {
   const secretCmd = program
     .command('secret')
-    .description('Manage secrets in secrets files');
+    .description('User and shared secrets (list, set, remove, remove-all, validate)')
+    .addHelpText('after', SECRET_GROUP_HELP_AFTER);
 
   secretCmd
     .command('list')
-    .description('List secret keys (user or shared; use --shared for shared)')
+    .description('List secret keys (--shared for shared/remote)')
+    .addHelpText('after', SECRET_LIST_HELP_AFTER)
     .option('--shared', 'List shared secrets (from config aifabrix-secrets or remote API)')
     .action(async(options) => {
       try {
@@ -77,7 +171,8 @@ function setupSecretsCommands(program) {
 
   secretCmd
     .command('set <key> <value>')
-    .description('Set a secret value in secrets file')
+    .description('Set a secret value')
+    .addHelpText('after', SECRET_SET_HELP_AFTER)
     .option('--shared', 'Save to general secrets file (from config.yaml aifabrix-secrets) instead of user secrets')
     .action(async(key, value, options) => {
       try {
@@ -91,7 +186,8 @@ function setupSecretsCommands(program) {
 
   secretCmd
     .command('remove <key>')
-    .description('Remove a secret by key')
+    .description('Remove a secret key')
+    .addHelpText('after', SECRET_REMOVE_HELP_AFTER)
     .option('--shared', 'Remove from shared secrets (file or remote API)')
     .action(async(key, options) => {
       try {
@@ -103,6 +199,7 @@ function setupSecretsCommands(program) {
       }
     });
 
+  setupSecretRemoveAllCommand(secretCmd);
   setupSecretSetSecretsFileCommand(secretCmd);
   setupSecretValidateCommand(secretCmd);
   setupSecureCommand(program);
@@ -115,7 +212,8 @@ function setupSecretsCommands(program) {
 function setupSecretSetSecretsFileCommand(secretCmd) {
   secretCmd
     .command('set-secrets-file <path>')
-    .description('Set aifabrix-secrets path in config (local file or https URL; pass empty to clear; path/URL is not checked for existence)')
+    .description('Set shared secrets path in config (file or https; empty clears; not validated)')
+    .addHelpText('after', SECRET_SET_SECRETS_FILE_HELP_AFTER)
     .action(async(secretsPath) => {
       try {
         const trimmed = (secretsPath || '').trim();
@@ -123,7 +221,7 @@ function setupSecretSetSecretsFileCommand(secretCmd) {
           throw new Error('Only https URLs are allowed for remote secrets');
         }
         await config.setSecretsPath(trimmed);
-        logger.log(trimmed === '' ? chalk.green('✓ Secrets file path cleared') : chalk.green(`✓ Secrets file path set to ${trimmed}`));
+        logger.log(trimmed === '' ? formatSuccessLine('Secrets file path cleared') : formatSuccessLine(`Secrets file path set to ${trimmed}`));
       } catch (error) {
         handleCommandError(error, 'secret set-secrets-file');
         process.exit(1);