@aifabrix/builder 2.44.5 → 2.45.0

package/lib/commands/upload.js

@@ -1,6 +1,14 @@
-const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatSuccessLine,
+  formatWarningLine,
+  formatProgress,
+  sectionTitle,
+  headerKeyValue,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
 /**
- * Upload external system to dataplane (single pipeline upload: validate → publish → controller register).
+ * Upload external system to dataplane (sync local `integration/<systemKey>/openapi/*.json` when present,
+ * then single pipeline upload: validate → publish → controller register).
  *
  * @fileoverview Upload command handler for aifabrix upload <systemKey>
  * @author AI Fabrix Team
@@ -10,6 +18,8 @@ const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+
+const SEP = chalk.gray('────────────────────────────────────────');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
@@ -38,6 +48,7 @@ const {
 } = require('../utils/external-system-readiness-display');
 const { maybeSyncSystemCertificationFromDataplane } = require('../certification/sync-system-certification');
 const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
+const { maybeSyncOpenApiFilesForMcp } = require('./repair-openapi-sync');
 
 /**
  * Validates system-key format (same as download).
@@ -86,7 +97,7 @@ async function resolveDataplaneAndAuth(systemKey, opts = {}) {
   }
 
   if (!silent) {
-    logger.log(chalk.gray('Resolving dataplane URL...'));
+    logger.log(metadata('Resolving dataplane URL...'));
   }
   const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, { silent });
   return { dataplaneUrl, authConfig, environment };
@@ -168,7 +179,9 @@ async function pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey,
   });
   if (pushResult.pushed > 0) {
     const keyList = pushResult.keys?.length ? ` (${pushResult.keys.join(', ')})` : '';
-    logger.log(chalk.green(`Pushed ${pushResult.pushed} credential secret(s) to dataplane${keyList}.`));
+    logger.log(
+      formatSuccessLine(`Pushed ${pushResult.pushed} credential secret(s) to dataplane${keyList}.`)
+    );
   } else {
     logger.log(chalk.yellow('Secret push skipped'));
   }
@@ -223,7 +236,10 @@ const UPLOAD_PROBE_TEST_DATA = {};
  * @param {number|undefined} probeTimeoutMs
  */
 async function maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, probeTimeoutMs) {
-  logger.log(chalk.blue('\nRunning runtime checks (--probe)...'));
+  logger.log('');
+  logger.log(sectionTitle('Runtime checks (--probe)'));
+  logger.log(SEP);
+  logger.log(formatProgress('Running runtime checks...'));
   const timeoutMs = probeTimeoutMs === undefined || probeTimeoutMs === null ? 120000 : probeTimeoutMs;
   try {
     const pr = await testSystemViaPipeline(
@@ -246,10 +262,13 @@ async function maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, probeTim
 
 /**
  * Local validation, manifest, payload, and configuration resolution.
+ * Does not write *-deploy.json; run `aifabrix json <systemKey>` to regenerate the deployment manifest from sources.
+ *
  * @param {string} systemKey
+ * @param {{ dryRun?: boolean }} [_opts] - Reserved for callers (e.g. dry-run); manifest is always built from current disk files
  * @returns {Promise<{ manifest: Object, payload: Object }>}
  */
-async function buildValidatedUploadManifestPayload(systemKey) {
+async function buildValidatedUploadManifestPayload(systemKey, _opts = {}) {
   const validationResult = await validateExternalSystemComplete(systemKey, { type: 'external' });
   throwIfValidationFailed(validationResult);
   logger.log(formatSuccessLine('Local validation passed'));
@@ -260,24 +279,54 @@ async function buildValidatedUploadManifestPayload(systemKey) {
 }
 
 /**
- * Upload path after dry-run check.
+ * Upload local `integration/<systemKey>/openapi/*.json` specs when present so dataplane can store
+ * vendor OpenAPI keyed by each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ * Call this **after** a successful pipeline publish: list/upload endpoints require the external system row.
+ * First publish still succeeds because pipeline materializes internal specs from `openapi.operations` when needed.
+ *
  * @param {string} systemKey
- * @param {Object} options
  * @param {Object} manifest
- * @param {Object} payload
+ * @returns {Promise<void>}
  */
-async function runUploadPublishAndSummary(systemKey, options, manifest, payload) {
-  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey);
-  requireBearerForDataplanePipeline(authConfig);
-  logger.log(chalk.gray('Target:'));
-  logger.log(chalk.gray(`Environment: ${environment}`));
-  logger.log(chalk.gray(`Dataplane: ${dataplaneUrl}`));
-  logDataplanePipelineWarning();
-  if (options.verbose) {
-    await maybeRunVerboseServerValidation(dataplaneUrl, authConfig, payload);
+async function logAndSyncLocalOpenApiForUpload(systemKey, manifest) {
+  const appPath = getIntegrationPath(systemKey);
+  const ei = manifest && manifest.externalIntegration;
+  const datasourceFiles = ei && Array.isArray(ei.dataSources) ? ei.dataSources : [];
+  const openapiSyncLines = await maybeSyncOpenApiFilesForMcp({
+    enabled: true,
+    dryRun: false,
+    appPath,
+    systemKey,
+    datasourceFiles
+  });
+  for (const line of openapiSyncLines) {
+    logger.log(line.startsWith('Skipped') ? formatWarningLine(line) : formatSuccessLine(line));
   }
-  await pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload);
-  const rawRes = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} ctx.systemKey
+ * @param {Object} ctx.options
+ * @param {Object} ctx.manifest
+ * @param {Object} ctx.payload
+ * @param {string} ctx.environment
+ * @param {string} ctx.dataplaneUrl
+ * @param {Object} ctx.authConfig
+ * @param {Object} ctx.rawRes
+ * @returns {Promise<void>}
+ */
+async function handlePublicationAndFollowups(ctx) {
+  const {
+    systemKey,
+    options,
+    manifest,
+    payload,
+    environment,
+    dataplaneUrl,
+    authConfig,
+    rawRes
+  } = ctx;
   const publication = unwrapPublicationResult(rawRes);
   if (!publication) {
     throw new Error(
@@ -296,7 +345,6 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
   if (options.probe) {
     await maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, options.probeTimeout);
   }
-
   const dsKeys = (payload.dataSources || []).map((ds) => ds && ds.key).filter(Boolean);
   await maybeSyncSystemCertificationFromDataplane({
     label: 'upload',
@@ -308,6 +356,41 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
   });
 }
 
+/**
+ * Upload path after dry-run check.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {Object} manifest
+ * @param {Object} payload
+ */
+async function runUploadPublishAndSummary(systemKey, options, manifest, payload) {
+  const { dataplaneUrl, authConfig, environment } = await resolveDataplaneAndAuth(systemKey);
+  requireBearerForDataplanePipeline(authConfig);
+  logger.log('');
+  logger.log(sectionTitle('Target'));
+  logger.log(SEP);
+  logger.log(headerKeyValue('Environment:', environment));
+  logger.log(headerKeyValue('Dataplane:', dataplaneUrl));
+  logDataplanePipelineWarning();
+  if (options.verbose) {
+    await maybeRunVerboseServerValidation(dataplaneUrl, authConfig, payload);
+  }
+  await pushAndLogCredentialSecrets(dataplaneUrl, authConfig, systemKey, payload);
+
+  const rawRes = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+  await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+  await handlePublicationAndFollowups({
+    systemKey,
+    options,
+    manifest,
+    payload,
+    environment,
+    dataplaneUrl,
+    authConfig,
+    rawRes
+  });
+}
+
 /**
  * Uploads external system: publishes to dataplane and registers with controller (draft).
  * @param {string} systemKey - External system key (integration/<systemKey>/)
@@ -322,8 +405,13 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
  */
 async function uploadExternalSystem(systemKey, options = {}) {
   validateSystemKeyFormat(systemKey);
-  logger.log(chalk.blue(`\nUploading external system: ${chalk.bold(systemKey)}`));
-  const { manifest, payload } = await buildValidatedUploadManifestPayload(systemKey);
+  logger.log('');
+  logger.log(sectionTitle('Upload external system'));
+  logger.log(SEP);
+  logger.log(headerKeyValue('System:', systemKey));
+  const { manifest, payload } = await buildValidatedUploadManifestPayload(systemKey, {
+    dryRun: !!options.dryRun
+  });
   if (options.dryRun) {
     logger.log(chalk.yellow('Dry run: would upload payload (no API calls).'));
     logger.log(

package/lib/commands/wizard-core-helpers.js

@@ -15,6 +15,7 @@ const { getIntegrationPath } = require('../utils/paths');
 const { parseOpenApi, testMcpConnection, credentialSelection } = require('../api/wizard.api');
 const { listCredentials } = require('../api/credentials.api');
 const { listExternalSystems, getExternalSystem } = require('../api/external-systems.api');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
 
 /**
  * Parse OpenAPI file or URL
@@ -35,7 +36,7 @@ async function parseOpenApiSource(dataplaneUrl, authConfig, sourceType, sourceDa
     if (!parseResponse.success) {
       throw new Error(`OpenAPI parsing failed: ${parseResponse.error || parseResponse.formattedError}`);
     }
-    logger.log(chalk.green(`\u2713 OpenAPI ${isUrl ? 'URL' : 'file'} parsed successfully`));
+    logger.log(formatSuccessLine(`OpenAPI ${isUrl ? 'URL' : 'file'} parsed successfully`));
     return parseResponse.data?.spec;
   } catch (error) {
     spinner.stop();
@@ -61,7 +62,7 @@ async function testMcpServerConnection(dataplaneUrl, authConfig, sourceData) {
     if (!testResponse.success || !testResponse.data?.connected) {
       throw new Error(`MCP connection failed: ${testResponse.data?.error || 'Unable to connect'}`);
     }
-    logger.log(chalk.green('\u2713 MCP server connection successful'));
+    logger.log(formatSuccessLine('MCP server connection successful'));
   } catch (error) {
     spinner.stop();
     throw error;
@@ -145,7 +146,7 @@ async function runCredentialSelectionLoop(dataplaneUrl, authConfig, selectionDat
     }
     if (response.success) {
       const actionText = selectionData.action === 'create' ? 'created' : 'selected';
-      logger.log(chalk.green(`\u2713 Credential ${actionText}`));
+      logger.log(formatSuccessLine(`Credential ${actionText}`));
       return response.data?.credentialIdOrKey || null;
     }
     const errorMsg = response.error || response.formattedError || response.message || 'Unknown error';
@@ -308,18 +309,19 @@ function throwConfigGenerationError(generateResponse, options = {}) {
 }
 
 /**
- * Write debug log to integration/<systemKey>/debug.log
+ * Write debug log to integration/<systemKey>/logs/debug.log
  * @async
  * @param {string} appName - Application name
  * @param {string} content - Debug log content
  */
 async function writeDebugLog(appName, content) {
   try {
-    const dir = getIntegrationPath(appName);
+    const appDir = getIntegrationPath(appName);
+    const dir = path.join(appDir, 'logs');
     await fs.mkdir(dir, { recursive: true });
     const debugPath = path.join(dir, 'debug.log');
     await fs.writeFile(debugPath, content, 'utf8');
-    logger.log(chalk.gray(`  Debug log saved to integration/${appName}/debug.log`));
+    logger.log(chalk.gray(`  Debug log saved to integration/${appName}/logs/debug.log`));
   } catch (e) {
     logger.warn(`Could not save debug.log: ${e.message}`);
   }
@@ -336,13 +338,14 @@ async function writeDebugLog(appName, content) {
 async function writeDebugManifest(appName, systemConfig, datasourceConfig) {
   const saved = [];
   try {
-    const dir = getIntegrationPath(appName);
+    const appDir = getIntegrationPath(appName);
+    const dir = path.join(appDir, 'logs');
     await fs.mkdir(dir, { recursive: true });
     if (systemConfig && typeof systemConfig === 'object') {
       const systemPath = path.join(dir, 'debug-system.yaml');
       await fs.writeFile(systemPath, yaml.dump(systemConfig, { lineWidth: -1 }), 'utf8');
       saved.push('debug-system.yaml');
-      logger.log(chalk.gray(`  Debug manifest saved to integration/${appName}/debug-system.yaml`));
+      logger.log(chalk.gray(`  Debug manifest saved to integration/${appName}/logs/debug-system.yaml`));
     }
     if (datasourceConfig !== undefined && datasourceConfig !== null) {
       const configs = Array.isArray(datasourceConfig) ? datasourceConfig : [datasourceConfig];
@@ -351,7 +354,7 @@ async function writeDebugManifest(appName, systemConfig, datasourceConfig) {
         const toWrite = configs.length === 1 ? configs[0] : configs;
         await fs.writeFile(datasourcePath, yaml.dump(toWrite, { lineWidth: -1 }), 'utf8');
         saved.push('debug-datasource.yaml');
-        logger.log(chalk.gray(`  Debug manifest saved to integration/${appName}/debug-datasource.yaml`));
+        logger.log(chalk.gray(`  Debug manifest saved to integration/${appName}/logs/debug-datasource.yaml`));
       }
     }
   } catch (e) {
@@ -381,7 +384,7 @@ async function saveDebugManifestOnErrorAndThrow(generateResponse, opts) {
     const savedManifest = await writeDebugManifest(appName, systemConfig, datasourceConfig);
     if (debugLog || savedManifest.length > 0) {
       const files = [debugLog && 'debug.log', ...savedManifest].filter(Boolean).join(', ');
-      debugManifestHint = `Debug manifest saved to integration/${appName}/ (${files}). Review the log and fix the manifest manually, then run: aifabrix wizard ${appName}`;
+      debugManifestHint = `Debug manifest saved to integration/${appName}/logs/ (${files}). Review the log and fix the manifest manually, then run: aifabrix wizard ${appName}`;
     }
   }
   throwConfigGenerationError(generateResponse, { debugManifestHint });
@@ -398,7 +401,7 @@ async function throwValidationFailureWithDebug(validateResponse, systemConfig, c
   );
   if (!debugLog && savedManifest.length === 0) throw new Error(`Configuration validation failed: ${errorMsg}`);
   const files = [debugLog && 'debug.log', ...savedManifest].filter(Boolean).join(', ');
-  throw new Error(`Configuration validation failed: ${errorMsg}\n\nDebug manifest saved to integration/${options.appName}/ (${files}). Review the log and fix the manifest manually, then run: aifabrix wizard ${options.appName}`);
+  throw new Error(`Configuration validation failed: ${errorMsg}\n\nDebug manifest saved to integration/${options.appName}/logs/ (${files}). Review the log and fix the manifest manually, then run: aifabrix wizard ${options.appName}`);
 }
 
 /**

package/lib/commands/wizard-core.js

@@ -13,6 +13,7 @@ const logger = require('../utils/logger');
 const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { normalizeWizardConfigs } = require('./wizard-config-normalizer');
+const { formatSuccessLine, formatSuccessParagraph } = require('../utils/cli-layout-chalk');
 const {
   createWizardSession,
   updateWizardSession,
@@ -143,7 +144,7 @@ async function handleModeSelection(dataplaneUrl, authConfig, configMode = null,
     throw new Error(fullMsg);
   }
   const sessionId = extractSessionId(sessionResponse.data);
-  logger.log(chalk.green(`\u2713 Session created: ${sessionId}`));
+  logger.log(formatSuccessLine(`Session created: ${sessionId}`));
   return { mode, sessionId };
 }
 
@@ -250,7 +251,7 @@ async function handleTypeDetection(dataplaneUrl, authConfig, openapiSpec) {
     if (detectResponse.success && detectResponse.data) {
       const detectedType = detectResponse.data;
       const recommendedType = detectedType.recommendedType || detectedType.apiType || 'unknown';
-      logger.log(chalk.green(`\u2713 API type detected: ${recommendedType}`));
+      logger.log(formatSuccessLine(`API type detected: ${recommendedType}`));
       return detectedType;
     }
   } catch (error) {
@@ -329,7 +330,7 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
         await writeDebugLog(options.appName, debugLog);
       }
     }
-    logger.log(chalk.green('\u2713 Configuration generated successfully'));
+    logger.log(formatSuccessLine('Configuration generated successfully'));
     return { systemConfig: normalized.systemConfig, datasourceConfigs: normalized.datasourceConfigs, systemKey: result.systemKey };
   } catch (error) {
     spinner.stop();
@@ -368,7 +369,7 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
       if (validateResponse.data?.warnings?.length > 0) warnings.push(...validateResponse.data.warnings);
     }
     spinner.stop();
-    logger.log(chalk.green('\u2713 Configuration validated successfully'));
+    logger.log(formatSuccessLine('Configuration validated successfully'));
     if (warnings.length > 0) logger.log(chalk.yellow('\n\u26A0 Warnings:\n' + warnings.map(w => `  - ${w.message || w}`).join('\n')));
   } catch (error) {
     spinner.stop();
@@ -423,7 +424,7 @@ async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl,
  * @param {string} format - Project format: yaml | json
  */
 function logWizardFileSaveFooter(appName, generatedFiles) {
-  logger.log(chalk.green('\n\u2713 Wizard completed successfully!'));
+  logger.log(formatSuccessParagraph('Wizard completed successfully!'));
   logger.log(chalk.green(`\nFiles created in: ${generatedFiles.appPath}`));
   logger.log(chalk.blue('\nNext steps:'));
   logger.log(chalk.gray(`  1. Review the generated files in integration/${appName}/`));

package/lib/commands/wizard-dataplane.js

@@ -6,7 +6,7 @@
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { infoLine, formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { formatProgress, formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const { getDataplaneUrl } = require('../datasource/deploy');
 const { listEnvironmentApplications } = require('../api/environments.api');
 
@@ -102,7 +102,7 @@ async function tryFallbackDataplaneUrl(controllerUrl, environment, authConfig, s
 async function discoverDataplaneUrl(controllerUrl, environment, authConfig, opts = {}) {
   const silent = opts.silent === true;
   if (!silent) {
-    logger.log(infoLine('🌐 Getting dataplane URL from controller...'));
+    logger.log(formatProgress('Getting dataplane URL from controller...'));
   }
   try {
     const dataplaneAppKey = await findDataplaneServiceAppKey(controllerUrl, environment, authConfig);

package/lib/commands/wizard-entity-selection.js

@@ -9,6 +9,7 @@ const logger = require('../utils/logger');
 const { discoverEntities } = require('../api/wizard.api');
 const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
 const { promptForEntitySelection } = require('../generator/wizard-prompts');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
 
 /**
  * If wizard.yaml entity name matches discover-entities list, use it; else warn.
@@ -22,7 +23,7 @@ function resolvePrefillEntityName(trimmed, entities) {
     logger.log(chalk.gray(
       `Using entity from wizard.yaml (${trimmed}). Skipping entity prompts.`
     ));
-    logger.log(chalk.green(`\u2713 Selected entity: ${trimmed}`));
+    logger.log(formatSuccessLine(`Selected entity: ${trimmed}`));
     return trimmed;
   }
   logger.log(chalk.yellow(
@@ -42,7 +43,7 @@ async function promptForValidatedEntity(entities) {
   if (!validation.valid) {
     throw new Error(`Invalid entity '${entityName}'. Available: ${entities.map(e => e.name).join(', ')}`);
   }
-  logger.log(chalk.green(`\u2713 Selected entity: ${entityName}`));
+  logger.log(formatSuccessLine(`Selected entity: ${entityName}`));
   return entityName;
 }
 
@@ -63,7 +64,7 @@ async function discoverAndSelectEntity(dataplaneUrl, authConfig, openapiSpec, pr
 
   if (entities.length === 1) {
     const only = entities[0].name;
-    logger.log(chalk.green(`\u2713 Only one entity discovered; using: ${only}`));
+    logger.log(formatSuccessLine(`Only one entity discovered; using: ${only}`));
     return only;
   }
 

package/lib/commands/wizard-headless.js

@@ -6,6 +6,7 @@
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
 const {
   validateWizardConfig: validateWizardConfigFile,
   displayValidationResults
@@ -141,7 +142,7 @@ async function handleWizardHeadless(options) {
     displayValidationResults(validationResult);
     throw new Error('Wizard configuration validation failed');
   }
-  logger.log(chalk.green('\u2713 Configuration file validated'));
+  logger.log(formatSuccessLine('Configuration file validated'));
 
   const wizardConfig = validationResult.config;
   const appName = wizardConfig.appName;

package/lib/commands/wizard.js

@@ -50,6 +50,7 @@ const {
   ensureIntegrationDir
 } = require('./wizard-helpers');
 const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
 
 /**
  * Map resolved source type/data onto wizard state.source.
@@ -455,7 +456,7 @@ async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}
   }
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 1: Create Session'));
   const sessionId = await createSessionFromParams(dataplaneUrl, authConfig, mode, systemIdOrKey, appKey);
-  logger.log(chalk.green('\u2713 Session created'));
+  logger.log(formatSuccessLine('Session created'));
 
   const platforms = mode === 'add-datasource' ? [] : await getWizardPlatforms(dataplaneUrl, authConfig);
   const state = await runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sessionId, {

package/lib/constants/infra-compose-service-names.js

@@ -0,0 +1,40 @@
+/**
+ * Infra compose service names accepted by `aifabrix restart` and {@link restartService}.
+ *
+ * @fileoverview Single source of truth for CLI help + validation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/** @type {ReadonlyArray<{ name: string, description: string }>} */
+const RESTARTABLE_INFRA_SERVICES = Object.freeze([
+  { name: 'postgres', description: 'PostgreSQL database' },
+  { name: 'redis', description: 'Redis' },
+  { name: 'pgadmin', description: 'pgAdmin 4 web UI (only if enabled when you ran up-infra)' },
+  { name: 'redis-commander', description: 'Redis Commander web UI (only if enabled when you ran up-infra)' },
+  { name: 'traefik', description: 'Traefik reverse proxy (only if enabled when you ran up-infra)' }
+]);
+
+/**
+ * @returns {string[]} service names in compose order
+ */
+function getRestartableInfraServiceNames() {
+  return RESTARTABLE_INFRA_SERVICES.map((s) => s.name);
+}
+
+/**
+ * Aligned lines for Commander `addHelpText('after', …)`.
+ * @returns {string}
+ */
+function buildRestartInfraHelpLines() {
+  const col = 22;
+  return RESTARTABLE_INFRA_SERVICES.map((s) => `  ${s.name.padEnd(col)}${s.description}`).join('\n');
+}
+
+module.exports = {
+  RESTARTABLE_INFRA_SERVICES,
+  getRestartableInfraServiceNames,
+  buildRestartInfraHelpLines
+};

package/lib/core/audit-logger.js

@@ -15,6 +15,7 @@ const fs = require('fs').promises;
 const path = require('path');
 const os = require('os');
 const paths = require('../utils/paths');
+const { maskSensitiveData } = require('../utils/log-redaction');
 
 // Audit log file path (beside config.yaml / CLI system dir for compliance)
 let auditLogPath = null;
@@ -51,40 +52,6 @@ async function getAuditLogPath() {
   return auditLogPath;
 }
 
-/**
- * Masks sensitive data in strings
- * Prevents secrets, keys, and passwords from appearing in logs
- *
- * @param {string} value - Value to mask
- * @returns {string} Masked value
- */
-function maskSensitiveData(value) {
-  if (!value || typeof value !== 'string') {
-    return value;
-  }
-
-  // Mask patterns: passwords, secrets, keys, tokens
-  const sensitivePatterns = [
-    { pattern: /password[=:]\s*([^\s]+)/gi, replacement: 'password=***' },
-    { pattern: /secret[=:]\s*([^\s]+)/gi, replacement: 'secret=***' },
-    { pattern: /key[=:]\s*([^\s]+)/gi, replacement: 'key=***' },
-    { pattern: /token[=:]\s*([^\s]+)/gi, replacement: 'token=***' },
-    { pattern: /api[_-]?key[=:]\s*([^\s]+)/gi, replacement: 'api_key=***' }
-  ];
-
-  let masked = value;
-  for (const { pattern, replacement } of sensitivePatterns) {
-    masked = masked.replace(pattern, replacement);
-  }
-
-  // If value looks like a hash/key (long hex string), mask it
-  if (/^[a-f0-9]{32,}$/i.test(masked.trim())) {
-    return '***';
-  }
-
-  return masked;
-}
-
 /**
  * Creates an audit log entry with ISO 27001 compliance
  *

package/lib/core/config-admin-email.js

@@ -0,0 +1,56 @@
+/**
+ * Admin email field in `config.yaml` (Keycloak / pgAdmin), written by `aifabrix setup`.
+ *
+ * @fileoverview config.yaml adminEmail helpers (keeps config.js under max-lines)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {unknown} email
+ * @returns {string} Trimmed valid email
+ * @throws {Error} When empty or not a plausible email
+ */
+function validateAdminEmailForConfig(email) {
+  const value = String(email ?? '').trim();
+  if (!value) {
+    throw new Error('Admin email must be a non-empty string');
+  }
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+    throw new Error('Admin email must be a valid email address');
+  }
+  return value;
+}
+
+/**
+ * @param {() => Promise<Object>} getConfig
+ * @returns {Promise<string>}
+ */
+async function getAdminEmailFromConfig(getConfig) {
+  const cfg = await getConfig();
+  if (cfg && typeof cfg.adminEmail === 'string' && cfg.adminEmail.trim()) {
+    return cfg.adminEmail.trim();
+  }
+  return '';
+}
+
+/**
+ * @param {() => Promise<Object>} getConfig
+ * @param {(data: Object) => Promise<void>} saveConfig
+ * @param {string} email
+ * @returns {Promise<void>}
+ */
+async function setAdminEmailInConfig(getConfig, saveConfig, email) {
+  const trimmed = validateAdminEmailForConfig(email);
+  const cfg = await getConfig();
+  cfg.adminEmail = trimmed;
+  await saveConfig(cfg);
+}
+
+module.exports = {
+  validateAdminEmailForConfig,
+  getAdminEmailFromConfig,
+  setAdminEmailInConfig
+};

package/lib/core/config-normalize.js

@@ -0,0 +1,60 @@
+/**
+ * URL and developer-id normalization for runtime config.
+ *
+ * @fileoverview Shared normalizers used by lib/core/config.js
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/**
+ * Normalize controller URL for consistent storage and lookup
+ * @param {string} url - Controller URL to normalize
+ * @returns {string|undefined|null} Normalized URL or original falsy
+ */
+function normalizeControllerUrl(url) {
+  if (!url || typeof url !== 'string') {
+    return url;
+  }
+  let normalized = url.trim().replace(/\/+$/, '');
+  if (!normalized.match(/^https?:\/\//)) {
+    normalized = `http://${normalized}`;
+  }
+  return normalized;
+}
+
+/**
+ * Validate and normalize developer ID
+ * @param {*} developerId - Developer ID value (can be string, number, undefined, or null)
+ * @returns {string} Normalized developer ID as string
+ * @throws {Error} If developer ID is invalid
+ */
+function validateAndNormalizeDeveloperId(developerId) {
+  const DEV_ID_DIGITS_REGEX = /^[0-9]+$/;
+
+  if (typeof developerId === 'undefined' || developerId === null) {
+    return '0';
+  }
+
+  if (typeof developerId === 'number') {
+    if (developerId < 0 || !Number.isFinite(developerId)) {
+      throw new Error('Developer ID must be a non-negative digit string or number');
+    }
+    return String(developerId);
+  }
+
+  if (typeof developerId === 'string') {
+    if (!DEV_ID_DIGITS_REGEX.test(developerId)) {
+      throw new Error('Developer ID must be a non-negative digit string or number');
+    }
+    return developerId;
+  }
+
+  throw new Error('Developer ID must be a non-negative digit string or number');
+}
+
+module.exports = {
+  normalizeControllerUrl,
+  validateAndNormalizeDeveloperId
+};