@aifabrix/builder 2.44.5 → 2.44.6

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,52 @@ async function buildValidatedUploadManifestPayload(systemKey) {
 }
 
 /**
- * Upload path after dry-run check.
+ * Upload local `integration/<systemKey>/openapi/*.json` specs when present so pipeline can resolve
+ * each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ *
  * @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 +343,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 +354,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);
+  await logAndSyncLocalOpenApiForUpload(systemKey, manifest);
+
+  const rawRes = await runUploadValidatePublish(dataplaneUrl, authConfig, payload);
+  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 +403,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/env-reader.js

@@ -115,6 +115,19 @@ function detectSensitiveValue(key, value) {
   return false;
 }
 
+/**
+ * Path segment after `kv://` for sensitive env vars; must match infra.parameter.yaml keys.
+ * API_KEY uses the shared miso-controller/dataplane catalog entry (not a flat `api-key` slug).
+ * @param {string} key - Environment variable name
+ * @returns {string}
+ */
+function sensitiveKvPathSegmentFromEnvKey(key) {
+  if (key === 'API_KEY') {
+    return 'miso-controller-secrets-apiKeyVault';
+  }
+  return key.toLowerCase().replace(/[^a-z0-9]/g, '-');
+}
+
 /**
  * Convert existing .env variables to env.template format
  * @param {Object} existingEnv - Existing environment variables
@@ -128,7 +141,7 @@ function convertToEnvTemplate(existingEnv, requiredVars) {
   Object.entries(existingEnv).forEach(([key, value]) => {
     if (detectSensitiveValue(key, value)) {
       // Convert sensitive values to kv:// references
-      convertedEnv[key] = `kv://${key.toLowerCase().replace(/[^a-z0-9]/g, '-')}`;
+      convertedEnv[key] = `kv://${sensitiveKvPathSegmentFromEnvKey(key)}`;
     } else {
       // Keep non-sensitive values as-is
       convertedEnv[key] = value;
@@ -148,8 +161,8 @@ function generateSecretsFromEnv(envVars) {
 
   Object.entries(envVars).forEach(([key, value]) => {
     if (detectSensitiveValue(key, value)) {
-      // Use centralized resolver for canonical secret names
-      const secretName = getCanonicalSecretName(key);
+      const secretName =
+        key === 'API_KEY' ? sensitiveKvPathSegmentFromEnvKey(key) : getCanonicalSecretName(key);
       secrets[secretName] = value;
     }
   });

package/lib/core/secrets-admin-env.js

@@ -0,0 +1,101 @@
+/**
+ * Infrastructure admin-secrets.env generation (PG/Redis Commander defaults).
+ *
+ * @fileoverview Split from secrets.js for module size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../utils/logger');
+const config = require('./config');
+const {
+  mergeInfraParameterDefaultsForCli,
+  getInfraParameterCatalog,
+  readRelaxedCatalogDefaults
+} = require('../parameters/infra-parameter-catalog');
+const { createDefaultSecrets } = require('../utils/secrets-generator');
+const pathsUtil = require('../utils/paths');
+const { loadSecrets } = require('./secrets-load');
+
+/**
+ * Writes admin env key-value pairs to content; encrypts values when encryption key is set.
+ * @async
+ * @param {Object.<string, string>} adminObj - Key-value object (e.g. POSTGRES_PASSWORD, ...)
+ * @returns {Promise<string>} .env-style content (plaintext or secure:// for secrets)
+ */
+async function formatAdminSecretsContent(adminObj) {
+  const encryptionKey = await config.getSecretsEncryptionKey();
+  const { encryptSecret } = require('../utils/secrets-encryption');
+  const lines = ['# Infrastructure Admin Credentials'];
+  for (const [k, v] of Object.entries(adminObj)) {
+    const value = (v === null || v === undefined) ? '' : String(v).replace(/\n/g, ' ').trim();
+    const valueToWrite = encryptionKey ? encryptSecret(value, encryptionKey) : value;
+    lines.push(`${k}=${valueToWrite}`);
+  }
+  return lines.join('\n');
+}
+
+async function loadSecretsOrBootstrapForAdmin(secretsPath) {
+  try {
+    return await loadSecrets(secretsPath);
+  } catch (error) {
+    const defaultSecretsPath = secretsPath || path.join(pathsUtil.getAifabrixHome(), 'secrets.yaml');
+    if (!fs.existsSync(defaultSecretsPath)) {
+      logger.log('Creating default secrets file...');
+      await createDefaultSecrets(defaultSecretsPath);
+      return await loadSecrets(secretsPath);
+    }
+    throw error;
+  }
+}
+
+function getInfraDefaultsMergedForAdmin() {
+  try {
+    return mergeInfraParameterDefaultsForCli(getInfraParameterCatalog().data, {});
+  } catch {
+    return {};
+  }
+}
+
+function buildLocalAdminSecretsObject(secrets, infraDefaults) {
+  const raw = secrets['postgres-passwordKeyVault'];
+  const relaxed = readRelaxedCatalogDefaults();
+  const postgresPassword =
+    (raw && String(raw).trim()) ||
+    infraDefaults.adminPassword ||
+    relaxed.adminPassword ||
+    '';
+  const pgAdminEmail = infraDefaults.adminEmail || relaxed.adminEmail || '';
+  return {
+    POSTGRES_PASSWORD: postgresPassword,
+    PGADMIN_DEFAULT_EMAIL: pgAdminEmail,
+    PGADMIN_DEFAULT_PASSWORD: postgresPassword,
+    REDIS_HOST: 'local:redis:6379:0:',
+    REDIS_COMMANDER_USER: 'admin',
+    REDIS_COMMANDER_PASSWORD: postgresPassword
+  };
+}
+
+/** Generates admin secrets for infrastructure (beside config.yaml, typically ~/.aifabrix/admin-secrets.env). Defaults from infra.parameter.yaml `defaults`. */
+async function generateAdminSecretsEnv(secretsPath) {
+  const secrets = await loadSecretsOrBootstrapForAdmin(secretsPath);
+  const infraDefaults = getInfraDefaultsMergedForAdmin();
+  const adminObj = buildLocalAdminSecretsObject(secrets, infraDefaults);
+  const aifabrixDir = pathsUtil.getAifabrixSystemDir();
+  const adminEnvPath = path.join(aifabrixDir, 'admin-secrets.env');
+  if (!fs.existsSync(aifabrixDir)) {
+    fs.mkdirSync(aifabrixDir, { recursive: true, mode: 0o700 });
+  }
+  const adminSecrets = await formatAdminSecretsContent(adminObj);
+  fs.writeFileSync(adminEnvPath, adminSecrets, { mode: 0o600 });
+  return adminEnvPath;
+}
+
+module.exports = {
+  formatAdminSecretsContent,
+  generateAdminSecretsEnv
+};