@aifabrix/builder 2.44.4 → 2.44.6

package/lib/cli/setup-infra.js

@@ -1,4 +1,9 @@
-const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatProgress,
+  formatSuccessLine,
+  sectionTitle,
+  headerKeyValue
+} = require('../utils/cli-test-layout-chalk');
 /**
  * CLI infrastructure command setup (up-infra, up-platform, up-miso, up-dataplane, down-infra, doctor, status, restart).
  *
@@ -10,7 +15,6 @@ const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const chalk = require('chalk');
 const infra = require('../infrastructure');
 const appLib = require('../app');
-const validator = require('../validation/validator');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 const { handleCommandError, isAuthenticationError } = require('../utils/cli-utils');
@@ -18,19 +22,29 @@ const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
-const { cleanBuilderAppDirs } = require('../commands/up-common');
+const {
+  applyUpPlatformForceConfig,
+  cleanBuilderAppDirs,
+  prepareUrlsLocalRegistryForUpPlatform
+} = require('../commands/up-common');
+const { runGuidedUpInfra, runGuidedUpMiso, runGuidedUpDataplane, runGuidedUpPlatform, runGuidedDownInfra } = require('./infra-guided');
 const {
   loadInfraStatusSummary,
   formatInfraStatusTitleLine,
   logInfraStatusConfigurationSummary,
   logPaddedFieldRow
 } = require('../utils/infra-status-display');
+const { runDoctorCheck } = require('./doctor-check');
+const {
+  getRestartableInfraServiceNames,
+  buildRestartInfraHelpLines
+} = require('../constants/infra-compose-service-names');
 
 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)
+  Or: aifabrix up-infra, 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
@@ -59,16 +73,14 @@ async function persistTlsEnabledFlag(cfg, 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)'
-    )
-  );
+  logger.log(formatSuccessLine(
+    `TLS mode ${value ? 'enabled' : 'disabled'} and saved to config (` +
+      '${TLS_ENABLED}=' +
+      tlsStr +
+      ', ${HTTP_ENABLED}=' +
+      httpStr +
+      ' when generating deployment JSON)'
+  ));
 }
 
 /**
@@ -152,11 +164,27 @@ async function runUpInfraCommand(options) {
   });
 }
 
+async function maybeHandleUpPlatformAuthRetry(error, options) {
+  if (!isAuthenticationError(error)) {
+    return false;
+  }
+  const controllerUrl = error.controllerUrl || await resolveControllerUrl();
+  if (!options.verbose) {
+    logger.log(formatProgress('Authenticating...'));
+  } else {
+    logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
+  }
+  await handleLogin({ method: 'device', controller: controllerUrl, compact: !options.verbose });
+  await handleUpDataplane(options);
+  return true;
+}
+
 function setupUpInfraCommand(program) {
   program.command('up-infra')
     .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('--verbose', 'Show full orchestration output (default is guided summary)')
     .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)')
@@ -170,6 +198,11 @@ function setupUpInfraCommand(program) {
     .option('--no-tls', 'Disable TLS mode (${TLS_ENABLED}=false, ${HTTP_ENABLED}=true)')
     .action(async(options) => {
       try {
+        if (!options.verbose) {
+          await runGuidedUpInfra(options, runUpInfraCommand);
+          return;
+        }
+
         await runUpInfraCommand(options);
       } catch (error) {
         handleCommandError(error, 'up-infra');
@@ -184,26 +217,47 @@ function setupUpPlatformCommand(program) {
     .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]))
-    .option('-f, --force', 'Clean builder/keycloak, builder/miso-controller, builder/dataplane and re-fetch from templates')
+    .option('--base', 'Resolve platform images from manifest only (default: true)', true)
+    .option('--verbose', 'Show full orchestration output (default is guided installer)')
+    .option(
+      '-f, --force',
+      'Reset CLI auth (clear all device/client tokens, set environment to dev, set default controller URL from developer-id), clean builder/keycloak, builder/miso-controller, builder/dataplane, then re-fetch from templates'
+    )
     .action(async(options) => {
       try {
+        let platformForceCleanSummary = null;
         if (options.force) {
-          await cleanBuilderAppDirs(['keycloak', 'miso-controller', 'dataplane']);
+          const forceSummary = await applyUpPlatformForceConfig({ silent: !options.verbose });
+          const cleanedApps = await cleanBuilderAppDirs(['keycloak', 'miso-controller', 'dataplane'], {
+            silent: !options.verbose
+          });
+          if (!options.verbose) {
+            platformForceCleanSummary = { forceSummary, cleanedApps };
+          }
         }
+
+        if (!options.verbose) {
+          await runGuidedUpPlatform(
+            options,
+            handleUpMiso,
+            handleUpDataplane,
+            handleLogin,
+            platformForceCleanSummary
+          );
+          return;
+        }
+
+        await prepareUrlsLocalRegistryForUpPlatform();
         await handleUpMiso(options);
         await handleUpDataplane(options);
       } catch (error) {
-        if (isAuthenticationError(error)) {
-          const controllerUrl = error.controllerUrl || await resolveControllerUrl();
-          logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
-          try {
-            await handleLogin({ method: 'device', controller: controllerUrl });
-            await handleUpDataplane(options);
+        try {
+          if (await maybeHandleUpPlatformAuthRetry(error, options)) {
             return;
-          } catch (loginOrRetryError) {
-            handleCommandError(loginOrRetryError, 'up-platform');
-            process.exit(1);
           }
+        } catch (loginOrRetryError) {
+          handleCommandError(loginOrRetryError, 'up-platform');
+          process.exit(1);
         }
         handleCommandError(error, 'up-platform');
         process.exit(1);
@@ -217,12 +271,19 @@ function setupUpMisoCommand(program) {
     .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]))
+    .option('--base', 'Resolve platform images from manifest only (default: true)', true)
     .option('-f, --force', 'Clean builder/keycloak and builder/miso-controller and re-fetch from templates')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .action(async(options) => {
       try {
         if (options.force) {
           await cleanBuilderAppDirs(['keycloak', 'miso-controller']);
         }
+        if (!options.verbose) {
+          await runGuidedUpMiso(options, handleUpMiso);
+          return;
+        }
+
         await handleUpMiso(options);
       } catch (error) {
         handleCommandError(error, 'up-miso');
@@ -233,23 +294,34 @@ function setupUpMisoCommand(program) {
 
 function setupUpDataplaneCommand(program) {
   program.command('up-dataplane')
-    .description('Register, deploy, run dataplane locally (dev env; login required)')
+    .description('Register, deploy, run dataplane locally (dev env; needs up-infra; 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)')
+    .option('--base', 'Resolve dataplane image from manifest only when running locally (default: true)', true)
     .option('-f, --force', 'Clean builder/dataplane and re-fetch from templates')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .action(async(options) => {
       try {
         if (options.force) {
           await cleanBuilderAppDirs(['dataplane']);
         }
+        if (!options.verbose) {
+          await runGuidedUpDataplane(options, handleUpDataplane);
+          return;
+        }
+
         await handleUpDataplane(options);
       } catch (error) {
         if (isAuthenticationError(error)) {
           const controllerUrl = error.controllerUrl || await resolveControllerUrl();
-          logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
+          if (!options.verbose) {
+            logger.log(formatProgress('Authenticating...'));
+          } else {
+            logger.log(chalk.blue('\nAuthentication required. Running aifabrix login...\n'));
+          }
           try {
-            await handleLogin({ method: 'device', controller: controllerUrl });
+            await handleLogin({ method: 'device', controller: controllerUrl, compact: !options.verbose });
             await handleUpDataplane(options);
             return;
           } catch (loginOrRetryError) {
@@ -267,8 +339,14 @@ function setupDownInfraCommand(program) {
   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)')
+    .option('--verbose', 'Show full orchestration output (default is guided summary)')
     .action(async(appName, options) => {
       try {
+        if (!options.verbose) {
+          await runGuidedDownInfra(appName, options, infra, appLib);
+          return;
+        }
+
         if (typeof appName === 'string' && appName.trim().length > 0) {
           await appLib.downApp(appName, { volumes: !!options.volumes });
         } else {
@@ -287,33 +365,7 @@ function setupDoctorCommand(program) {
     .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'}`);
-        if (result.recommendations.length > 0) {
-          logger.log('\n📋 Recommendations:');
-          result.recommendations.forEach(rec => logger.log(`  • ${rec}`));
-        }
-        if (result.docker === 'ok') {
-          try {
-            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' ? '❓' : '✖';
-              logger.log(`  ${icon} ${service}: ${status}`);
-            });
-          } catch (error) {
-            logger.log('\n🏥 Infrastructure: Not running');
-          }
-        }
-        logger.log('');
+        await runDoctorCheck();
       } catch (error) {
         handleCommandError(error, 'doctor');
         process.exit(1);
@@ -361,19 +413,44 @@ function setupStatusCommand(program) {
     });
 }
 
-const INFRA_SERVICES = ['postgres', 'redis', 'pgadmin', 'redis-commander', 'traefik'];
+const RESTART_INFRA_SERVICE_NAMES = getRestartableInfraServiceNames();
+
+const RESTART_COMMAND_HELP_AFTER = `
+Infra — use these exact Docker Compose service names:
+${buildRestartInfraHelpLines()}
+
+Optional services (pgadmin, redis-commander, traefik) only exist if you enabled them when running up-infra.
+
+Builder apps (examples):
+  keycloak, miso-controller, dataplane
+
+Examples:
+  $ aifabrix restart postgres
+  $ aifabrix restart traefik
+  $ aifabrix restart miso-controller
+`;
 
 function setupRestartCommand(program) {
   program.command('restart <service|app>')
-    .description('Restart infra service (postgres, redis, …) or a builder/<app> container')
+    .description(
+      'Restart one infra compose service (postgres, redis, pgadmin, redis-commander, traefik) or a builder app container'
+    )
+    .addHelpText('after', RESTART_COMMAND_HELP_AFTER)
     .action(async(service) => {
       try {
-        if (INFRA_SERVICES.includes(service)) {
-          await infra.restartService(service);
-          logger.log(`✔ ${service} service restarted successfully`);
+        if (RESTART_INFRA_SERVICE_NAMES.includes(service)) {
+          logger.log('');
+          logger.log(sectionTitle('Restart'));
+          logger.log(headerKeyValue('Infra service:', service));
+          logger.log(formatProgress(`Restarting ${service}…`));
+          await infra.restartService(service, { suppressProgressLog: true });
+          logger.log(formatSuccessLine(`${service} restarted successfully`));
         } else {
+          logger.log('');
+          logger.log(sectionTitle('Restart'));
+          logger.log(headerKeyValue('Application:', service));
           await appLib.restartApp(service);
-          logger.log(`✔ ${service} restarted successfully`);
+          logger.log(formatSuccessLine(`${service} restarted successfully`));
         }
       } catch (error) {
         handleCommandError(error, 'restart');

package/lib/cli/setup-integration-client.js

@@ -0,0 +1,182 @@
+/**
+ * CLI integration-client command setup (Controller OAuth / API clients).
+ *
+ * @fileoverview Integration client CLI definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  runIntegrationClientCreate,
+  runIntegrationClientList,
+  runIntegrationClientRotateSecret,
+  runIntegrationClientDelete,
+  runIntegrationClientUpdateGroups,
+  runIntegrationClientUpdateRedirectUris
+} = require('../commands/integration-client');
+
+const HELP_AFTER = `
+Integration clients are machine identities for integrations, CI, Postman OAuth2, or API access.
+Use: list (integration-client:read), create (integration-client:create), rotate-secret,
+update-groups, update-redirect-uris (integration-client:update), delete (integration-client:delete).
+The controller returns a one-time clientSecret on create and rotate-secret—save it immediately;
+it cannot be retrieved again.
+
+Examples:
+  $ aifabrix integration-client create --key postman --display-name "Postman client" \\
+      --redirect-uris https://oauth.pstmn.io/v1/callback --group-names AI-Fabrix-Platform-Admins
+  $ aifabrix integration-client list
+  $ aifabrix integration-client rotate-secret --id <uuid>
+  $ aifabrix integration-client delete --id <uuid>
+  $ aifabrix integration-client update-groups --id <uuid> --group-names Group1,Group2
+  $ aifabrix integration-client update-redirect-uris --id <uuid> --redirect-uris https://app.example.com/callback
+
+Run "aifabrix login" first.`;
+
+function parseOptionalInt(val) {
+  return (val !== undefined && val !== null) ? parseInt(val, 10) : undefined;
+}
+
+function addCreateCommand(integrationClient) {
+  integrationClient.command('create')
+    .description('Create an integration client and receive a one-time clientSecret (save it now; it will not be shown again)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('-k, --key <key>', 'Stable key (lowercase alphanumeric and hyphens; required)')
+    .option('-n, --display-name <name>', 'Display name (required)')
+    .option('--keycloak-client-id <id>', 'Optional fixed Keycloak client id (when omitted, the server assigns one)')
+    .option('--redirect-uris <uris>', 'Comma-separated OAuth2 redirect URIs (required)')
+    .option('--group-names <names>', 'Comma-separated group names (optional; omit for OAuth-only clients)')
+    .option('-d, --description <description>', 'Optional description')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientCreate({
+          controller: options.controller,
+          key: options.key,
+          displayName: options.displayName,
+          keycloakClientId: options.keycloakClientId,
+          redirectUris: options.redirectUris,
+          groupNames: options.groupNames,
+          description: options.description
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client create');
+        process.exit(1);
+      }
+    });
+}
+
+function addListCommand(integrationClient) {
+  integrationClient.command('list')
+    .description('List integration clients (supports pagination and search)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--page <n>', 'Page number')
+    .option('--page-size <n>', 'Items per page')
+    .option('--search <term>', 'Search term')
+    .option('--sort <field>', 'Sort field/direction')
+    .option('--filter <expr>', 'Filter expression')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientList({
+          controller: options.controller,
+          page: parseOptionalInt(options.page),
+          pageSize: parseOptionalInt(options.pageSize),
+          search: options.search,
+          sort: options.sort,
+          filter: options.filter
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client list');
+        process.exit(1);
+      }
+    });
+}
+
+function addRotateSecretCommand(integrationClient) {
+  integrationClient.command('rotate-secret')
+    .description('Rotate (regenerate) secret for an integration client; new secret shown once only')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientRotateSecret({ controller: options.controller, id: options.id });
+      } catch (error) {
+        handleCommandError(error, 'integration-client rotate-secret');
+        process.exit(1);
+      }
+    });
+}
+
+function addDeleteCommand(integrationClient) {
+  integrationClient.command('delete')
+    .description('Delete (deactivate) an integration client')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientDelete({ controller: options.controller, id: options.id });
+      } catch (error) {
+        handleCommandError(error, 'integration-client delete');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateGroupsCommand(integrationClient) {
+  integrationClient.command('update-groups')
+    .description('Update group assignments for an integration client')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .option('--group-names <names>', 'Comma-separated group names (required)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientUpdateGroups({
+          controller: options.controller,
+          id: options.id,
+          groupNames: options.groupNames
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client update-groups');
+        process.exit(1);
+      }
+    });
+}
+
+function addUpdateRedirectUrisCommand(integrationClient) {
+  integrationClient.command('update-redirect-uris')
+    .description('Update redirect URIs for an integration client (min 1)')
+    .option('--controller <url>', 'Controller base URL (default: from config)')
+    .option('--id <uuid>', 'Integration client ID (required)')
+    .option('--redirect-uris <uris>', 'Comma-separated redirect URIs (required, min 1)')
+    .action(async(options) => {
+      try {
+        await runIntegrationClientUpdateRedirectUris({
+          controller: options.controller,
+          id: options.id,
+          redirectUris: options.redirectUris
+        });
+      } catch (error) {
+        handleCommandError(error, 'integration-client update-redirect-uris');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Registers integration-client commands
+ * @param {Command} program - Commander program instance
+ */
+function setupIntegrationClientCommands(program) {
+  const integrationClient = program
+    .command('integration-client')
+    .description('OAuth integration clients on Controller (integrations, CI, API access)')
+    .addHelpText('after', HELP_AFTER);
+  addCreateCommand(integrationClient);
+  addListCommand(integrationClient);
+  addRotateSecretCommand(integrationClient);
+  addDeleteCommand(integrationClient);
+  addUpdateGroupsCommand(integrationClient);
+  addUpdateRedirectUrisCommand(integrationClient);
+}
+
+module.exports = { setupIntegrationClientCommands };

package/lib/cli/setup-parameters.js

@@ -17,11 +17,30 @@ function setupParametersCommands(program) {
 
   parameters
     .command('validate')
-    .description('Check env.template kv:// references against lib/schema/infra.parameter.yaml')
+    .description(
+      'Validate builder/*/env.template kv:// references against infra.parameter.yaml'
+    )
     .option('--catalog <path>', 'Override path to infra.parameter.yaml')
+    .option('--verbose', 'Print scanned files and scan summary')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  aifabrix parameters validate
+  aifabrix parameters validate --verbose
+  aifabrix parameters validate --catalog ./lib/schema/infra.parameter.yaml
+
+Notes:
+  - Scans builder/* apps only (integration/* is intentionally skipped).
+  - Extracts kv://KEY references from env.template and checks KEY coverage in the catalog.
+`
+    )
     .action(async(opts) => {
       try {
-        const result = await handleParametersValidate({ catalogPath: opts.catalog });
+        const result = await handleParametersValidate({
+          catalogPath: opts.catalog,
+          verbose: Boolean(opts.verbose)
+        });
         if (!result.valid) process.exit(1);
       } catch (error) {
         handleCommandError(error, 'parameters validate');

package/lib/cli/setup-platform.js

@@ -0,0 +1,102 @@
+/**
+ * CLI registration for `aifabrix setup` and `aifabrix teardown`.
+ *
+ * `setup` is the one-shot platform installer. When no infrastructure is
+ * detected it runs a small wizard (admin email/password, AI tool keys) and
+ * then `up-infra` + `up-platform`. When infra is already up, it offers a
+ * mode menu (re-install, wipe data, clean install files, update images).
+ *
+ * `teardown` is the symmetrical inverse of `setup`: `down-infra -v` plus a
+ * full clean of the AI Fabrix system directory (everything except
+ * `config.yaml`).
+ *
+ * @fileoverview CLI command setup for setup/teardown
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { handleCommandError } = require('../utils/cli-utils');
+const { handleSetup } = require('../commands/setup');
+const { handleTeardown } = require('../commands/teardown');
+
+const SETUP_HELP_AFTER = `
+What this command does:
+  - With no infra running: prompts for admin email/password (used for Postgres, pgAdmin, Keycloak), prompts for an AI tool (OpenAI or Azure OpenAI) only when keys are not already set, then runs up-infra and up-platform.
+  - With infra running: shows a mode menu:
+      1) Re-install — stop infra and remove all volumes, then up-infra + up-platform --force.
+      2) Wipe data — drop every database and DB user, then up-infra + up-platform --force.
+      3) Clean installation files — remove user-local secrets, then up-infra + up-platform --force.
+      4) Update images — pull the latest infra and platform images, then up-infra + up-platform.
+
+AI tool keys are read from the user-local file (~/.aifabrix/secrets.local.yaml) merged with the shared aifabrix-secrets file. If either source already provides keys, the AI tool prompt is skipped.
+
+Use 'aifabrix teardown' to fully remove the local installation.
+`;
+
+const TEARDOWN_HELP_AFTER = `
+What this command does:
+  - Runs down-infra -v (stops all infra + apps, removes every Docker volume).
+  - Removes every file and subfolder inside ~/.aifabrix/ EXCEPT config.yaml.
+    This includes secrets.local.yaml, admin-secrets.env, auth/token files,
+    and infra-dev*/ directories.
+
+This is the symmetrical inverse of 'aifabrix setup'. Use --yes / -y to skip the confirmation prompt in CI.
+`;
+
+/**
+ * Register the setup command on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerSetup(program) {
+  program
+    .command('setup')
+    .description('Install or refresh the full AI Fabrix platform (infra + miso + dataplane)')
+    .option('-d, --developer <id>', 'Pin developer ID before fresh install (fresh path only; ignored when infra is already up)')
+    .option('-y, --yes', 'Skip destructive confirmation prompts (re-install, wipe data, teardown)')
+    .addHelpText('after', SETUP_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        await handleSetup(options || {});
+      } catch (error) {
+        handleCommandError(error, 'setup');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register the teardown command on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerTeardown(program) {
+  program
+    .command('teardown')
+    .description('Tear down local AI Fabrix infra and clean ~/.aifabrix/ except config.yaml')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .addHelpText('after', TEARDOWN_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        await handleTeardown(options || {});
+      } catch (error) {
+        handleCommandError(error, 'teardown');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register all setup-platform commands on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function setupPlatformCommands(program) {
+  registerSetup(program);
+  registerTeardown(program);
+}
+
+module.exports = {
+  setupPlatformCommands,
+  registerSetup,
+  registerTeardown
+};