@aifabrix/builder 2.43.0 → 2.44.0

package/lib/generator/split-readme.js

@@ -13,10 +13,15 @@ const { parseImageReference } = require('./parse-image');
  * @param {Object} deployment - Deployment JSON object
  * @returns {{ appName: string, config: Object }}
  */
-function buildReadmeConfigForExternal(deployment) {
+function buildReadmeConfigForExternal(deployment, options = {}) {
   const system = deployment.system;
   const appName = system.key || deployment.key || 'external-system';
   const dataSources = deployment.dataSources || deployment.datasources || [];
+  const rawExt = options.fileExt;
+  const fileExt =
+    rawExt !== undefined && rawExt !== null && String(rawExt).trim() !== ''
+      ? (String(rawExt).startsWith('.') ? String(rawExt) : `.${String(rawExt)}`)
+      : '.json';
   return {
     appName,
     config: {
@@ -25,7 +30,7 @@ function buildReadmeConfigForExternal(deployment) {
       systemType: system.type || 'openapi',
       systemDisplayName: system.displayName || appName,
       systemDescription: system.description || `External system integration for ${appName}`,
-      fileExt: '.yaml',
+      fileExt,
       datasourceCount: dataSources.length,
       datasources: dataSources
     }
@@ -49,7 +54,7 @@ function buildReadmeConfigForApp(deployment) {
     displayName: deployment.displayName,
     description: deployment.description,
     port,
-    build: { localPort: port },
+    build: {},
     image: { name: imageName, registry },
     registry,
     database: deployment.requiresDatabase,
@@ -80,9 +85,9 @@ function buildReadmeConfigForApp(deployment) {
  * @param {Object} deployment - Deployment JSON object
  * @returns {{ appName: string, config: Object }}
  */
-function buildReadmeConfigFromDeployment(deployment) {
+function buildReadmeConfigFromDeployment(deployment, options = {}) {
   if (deployment.system && typeof deployment.system === 'object') {
-    return buildReadmeConfigForExternal(deployment);
+    return buildReadmeConfigForExternal(deployment, options);
   }
   return buildReadmeConfigForApp(deployment);
 }
@@ -92,11 +97,11 @@ function buildReadmeConfigFromDeployment(deployment) {
  * @param {Object} deployment - Deployment JSON object
  * @returns {string} README.md content
  */
-function generateReadmeFromDeployJson(deployment) {
+function generateReadmeFromDeployJson(deployment, options = {}) {
   if (!deployment || typeof deployment !== 'object') {
     throw new Error('Deployment object is required');
   }
-  const { appName, config } = buildReadmeConfigFromDeployment(deployment);
+  const { appName, config } = buildReadmeConfigFromDeployment(deployment, options);
   return generateReadmeMd(appName, config);
 }
 

package/lib/generator/split-variables.js

@@ -56,7 +56,8 @@ function extractOptionalSections(deployment) {
   const optional = {};
   const names = [
     'healthCheck', 'authentication', 'build', 'repository', 'deployment',
-    'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting'
+    'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting',
+    'environmentScopedResources'
   ];
   for (const sectionName of names) {
     extractOptionalSection(deployment, sectionName, optional);

package/lib/generator/split.js

@@ -440,7 +440,7 @@ async function splitDeployJson(deployJsonPath, outputDir = null, splitOptions =
 
   const variables = extractVariablesYaml(deployment);
   const rbac = extractRbacYaml(deployment);
-  const readme = generateReadmeFromDeployJson(deployment);
+  const readme = generateReadmeFromDeployJson(deployment, { fileExt: '.yaml' });
 
   const result = await writeComponentFiles(finalOutputDir, envTemplate, variables, rbac, readme, writeOptions);
   await applyExternalSystemFilesToResult(finalOutputDir, deployment, result);

package/lib/generator/wizard-readme.js

@@ -6,10 +6,10 @@
  */
 
 'use strict';
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 
 const fs = require('fs').promises;
 const path = require('path');
-const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { generateExternalReadmeContent } = require('../utils/external-readme');
 
@@ -48,7 +48,7 @@ async function generateReadme(options) {
 
     if (aiGeneratedContent) {
       await fs.writeFile(readmePath, aiGeneratedContent, 'utf8');
-      logger.log(chalk.green('✓ Generated README.md (AI-generated from dataplane)'));
+      logger.log(formatSuccessLine('Generated README.md (AI-generated from dataplane)'));
       return;
     }
 
@@ -82,7 +82,7 @@ async function generateReadme(options) {
     });
 
     await fs.writeFile(readmePath, readmeContent, 'utf8');
-    logger.log(chalk.green('✓ Generated README.md (template)'));
+    logger.log(formatSuccessLine('Generated README.md (template)'));
   } catch (error) {
     throw new Error(`Failed to generate README.md: ${error.message}`);
   }

package/lib/generator/wizard.js

@@ -8,10 +8,10 @@
  * PASSWORD, BASEURL. See docs/external-systems.md and docs/wizard.md.
  */
 
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const fs = require('fs').promises;
 const path = require('path');
 const Handlebars = require('handlebars');
-const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
@@ -61,7 +61,7 @@ async function writeSystemYamlFile(appPath, finalSystemKey, systemConfig, format
   const systemFileName = `${finalSystemKey}-system${ext}`;
   const systemFilePath = path.join(appPath, systemFileName);
   writeConfigFile(systemFilePath, systemConfig, format === 'json' ? 'json' : 'yaml');
-  logger.log(chalk.green(`✓ Generated system file: ${systemFileName}`));
+  logger.log(formatSuccessLine(`Generated system file: ${systemFileName}`));
   return systemFilePath;
 }
 
@@ -97,7 +97,7 @@ async function writeDatasourceYamlFiles(appPath, finalSystemKey, datasourceConfi
     const datasourceFilePath = path.join(appPath, datasourceFileName);
     writeConfigFile(datasourceFilePath, datasourceConfig, fmt);
     datasourceFileNames.push(datasourceFileName);
-    logger.log(chalk.green(`✓ Generated datasource file: ${datasourceFileName}`));
+    logger.log(formatSuccessLine(`Generated datasource file: ${datasourceFileName}`));
   }
   return datasourceFileNames;
 }
@@ -135,7 +135,7 @@ async function generateConfigFilesForWizard(params) {
   const envTemplatePath = path.join(appPath, 'env.template');
   const envTemplateContent = generateExternalEnvTemplateContent(systemConfig);
   await fs.writeFile(envTemplatePath, envTemplateContent, 'utf8');
-  logger.log(chalk.green('✓ Generated env.template'));
+  logger.log(formatSuccessLine('Generated env.template'));
 
   try {
     const secretsEnsure = require('../core/secrets-ensure');
@@ -164,7 +164,7 @@ async function generateConfigFilesForWizard(params) {
   const deployJson = toDeployJsonShape(manifest);
   const deployManifestPath = path.join(appPath, `${finalSystemKey}-deploy.json`);
   await fs.writeFile(deployManifestPath, JSON.stringify(deployJson, null, 2), 'utf8');
-  logger.log(chalk.green(`✓ Generated deployment manifest: ${finalSystemKey}-deploy.json`));
+  logger.log(formatSuccessLine(`Generated deployment manifest: ${finalSystemKey}-deploy.json`));
 
   return {
     variablesPath: configPath,
@@ -293,7 +293,7 @@ async function generateOrUpdateVariablesYaml(params) {
       const fsSync = require('fs');
       if (fsSync.existsSync(configPath)) fsSync.unlinkSync(configPath);
     }
-    logger.log(chalk.green(`✓ Generated/updated application${ext}`));
+    logger.log(formatSuccessLine(`Generated/updated application${ext}`));
     return targetPath;
   } catch (error) {
     throw new Error(`Failed to generate application config: ${error.message}`);
@@ -417,7 +417,7 @@ async function _generateEnvTemplate(appPath, systemConfig, finalSystemKey) {
     addBaseUrlLines(lines, systemConfig);
 
     await fs.writeFile(envTemplatePath, lines.join('\n'), 'utf8');
-    logger.log(chalk.green('✓ Generated env.template'));
+    logger.log(formatSuccessLine('Generated env.template'));
   } catch (error) {
     throw new Error(`Failed to generate env.template: ${error.message}`);
   }
@@ -440,7 +440,7 @@ async function writeDeployScriptFromTemplate(templateName, outputPath, context)
   const templatePath = path.join(templatesExternalDir, templateName);
   const content = Handlebars.compile(await fs.readFile(templatePath, 'utf8'))(context);
   await fs.writeFile(outputPath, content, 'utf8');
-  logger.log(chalk.green(`✓ Generated ${path.basename(outputPath)}`));
+  logger.log(formatSuccessLine(`Generated ${path.basename(outputPath)}`));
 }
 
 async function generateDeployScripts(appPath, systemKey, systemFileName, datasourceFileNames) {

package/lib/infrastructure/compose.js

@@ -12,6 +12,32 @@ const fs = require('fs');
 const handlebars = require('handlebars');
 const path = require('path');
 
+/**
+ * Normalize a host path for Docker Compose bind mounts. Docker Desktop sends
+ * mounts to a Linux VM; backslashes in Windows paths yield "invalid volume
+ * specification" from the daemon.
+ *
+ * On Windows, Compose often forwards binds as "SOURCE:TARGET:rw". A SOURCE
+ * like "C:/Users/..." is split at the first colon, so the engine must receive
+ * paths in Linux-VM form (e.g. "/c/Users/...") instead.
+ *
+ * @param {string} fsPath - Host path (absolute or relative)
+ * @returns {string} Path with forward slashes, resolved when relative
+ */
+function toDockerBindMountSource(fsPath) {
+  if (!fsPath || typeof fsPath !== 'string') {
+    return fsPath;
+  }
+  let resolved = path.resolve(fsPath).split(path.sep).join('/');
+  if (process.platform === 'win32') {
+    const drive = /^([a-zA-Z]):(\/.*)$/.exec(resolved);
+    if (drive) {
+      resolved = `/${drive[1].toLowerCase()}${drive[2]}`;
+    }
+  }
+  return resolved;
+}
+
 /**
  * Builds Traefik configuration from environment variables
  * @param {boolean} enabled - Whether Traefik should be included
@@ -22,7 +48,8 @@ function buildTraefikConfig(enabled) {
     enabled: !!enabled,
     certStore: process.env.TRAEFIK_CERT_STORE || null,
     certFile: process.env.TRAEFIK_CERT_FILE || null,
-    keyFile: process.env.TRAEFIK_KEY_FILE || null
+    keyFile: process.env.TRAEFIK_KEY_FILE || null,
+    trustForwardedHeaders: false
   };
 }
 
@@ -40,13 +67,23 @@ function validateTraefikConfig(traefikConfig) {
 
   if (traefikConfig.certStore) {
     if (!traefikConfig.certFile || !traefikConfig.keyFile) {
-      errors.push('TRAEFIK_CERT_FILE and TRAEFIK_KEY_FILE are required when TRAEFIK_CERT_STORE is set');
+      errors.push(
+        'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+          'Set TRAEFIK_CERT_FILE and TRAEFIK_KEY_FILE (and TRAEFIK_CERT_STORE if used) to your local cert and key, ' +
+          'or disable TLS in application/frontDoorRouting for local development.'
+      );
     } else {
       if (!fs.existsSync(traefikConfig.certFile)) {
-        errors.push(`Certificate file not found: ${traefikConfig.certFile}`);
+        errors.push(
+          'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+            `Certificate file not found: ${traefikConfig.certFile}`
+        );
       }
       if (!fs.existsSync(traefikConfig.keyFile)) {
-        errors.push(`Private key file not found: ${traefikConfig.keyFile}`);
+        errors.push(
+          'TLS is enabled for Traefik but certificate files are missing or invalid. ' +
+            `Private key file not found: ${traefikConfig.keyFile}`
+        );
       }
     }
   }
@@ -82,6 +119,20 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
   const redisCommanderConfig = options.redisCommander && typeof options.redisCommander.enabled === 'boolean'
     ? options.redisCommander
     : { enabled: true };
+  const traefikForCompose = traefikConfig && typeof traefikConfig === 'object'
+    ? {
+      ...traefikConfig,
+      trustForwardedHeaders: !!traefikConfig.trustForwardedHeaders,
+      ...(traefikConfig.certFile
+        ? { certFile: toDockerBindMountSource(traefikConfig.certFile) }
+        : {}),
+      ...(traefikConfig.keyFile
+        ? { keyFile: toDockerBindMountSource(traefikConfig.keyFile) }
+        : {})
+    }
+    : traefikConfig;
+  const initScriptsBind = toDockerBindMountSource(path.join(infraDir, 'init-scripts'));
+  const infraDirBind = toDockerBindMountSource(infraDir);
   const composeContent = template({
     devId: devId,
     postgresPort: ports.postgres,
@@ -94,7 +145,9 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
     serversJsonPath: serversJsonPath,
     pgpassPath: pgpassPath,
     infraDir: infraDir,
-    traefik: traefikConfig,
+    initScriptsBind: initScriptsBind,
+    infraDirBind: infraDirBind,
+    traefik: traefikForCompose,
     pgadmin: pgadminConfig,
     redisCommander: redisCommanderConfig
   });
@@ -106,5 +159,6 @@ function generateComposeFile(templatePath, devId, idNum, ports, infraDir, option
 module.exports = {
   buildTraefikConfig,
   validateTraefikConfig,
-  generateComposeFile
+  generateComposeFile,
+  toDockerBindMountSource
 };

package/lib/infrastructure/helpers.js

@@ -11,14 +11,31 @@
 
 const path = require('path');
 const fs = require('fs');
+const fsRealSync = require('../internal/fs-real-sync');
+const { nodeFs } = require('../internal/node-fs');
 const chalk = require('chalk');
 const handlebars = require('handlebars');
-const secrets = require('../core/secrets');
 const adminSecrets = require('../core/admin-secrets');
 const logger = require('../utils/logger');
 const dockerUtils = require('../utils/docker');
 const paths = require('../utils/paths');
 const secretsEnsure = require('../core/secrets-ensure');
+const {
+  mergeInfraParameterDefaultsForCli,
+  getInfraParameterCatalog,
+  readRelaxedCatalogDefaults
+} = require('../parameters/infra-parameter-catalog');
+const { ensureDevCertsIfNeededForRemoteDocker } = require('../utils/ensure-dev-certs-for-remote-docker');
+
+/**
+ * Lazy-load core/secrets at call time. A top-level require creates a circular dependency:
+ * secrets → url-declarative-resolve → compose-generator → compose-generate-docker-compose → this module,
+ * which left `generateAdminSecretsEnv` / `formatAdminSecretsContent` undefined on the captured export.
+ * @returns {Object} core/secrets module exports (loadSecrets, generateAdminSecretsEnv, …)
+ */
+function getCoreSecrets() {
+  return require('../core/secrets');
+}
 
 /**
  * Gets infrastructure directory name based on developer ID
@@ -43,21 +60,64 @@ function getInfraProjectName(devId) {
 }
 
 /**
- * Check Docker availability
+ * User-facing error when Docker/Compose checks fail (tailored by underlying message).
+ * @param {string} detail - Error message from ensureDockerAndCompose / Docker CLI
+ * @returns {string}
+ */
+function formatDockerInfrastructureFailure(detail) {
+  const cause = (detail || '').trim() || 'unknown error';
+
+  if (/Docker Compose is not available/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: Docker Compose check failed (see Cause below).\n\n' +
+      `Cause: ${cause}\n\n` +
+      'If Cause mentions TLS, certificate, or handshake, fix client TLS for docker-endpoint (cert.pem, key.pem, ca.pem under ~/.aifabrix/certs/<developer-id>/) or docker-tls-skip-verify when appropriate. ' +
+      'If Cause suggests a missing plugin, install Docker Compose v2 for your user (docker CLI + plugin; no unix socket needed when using tcp:// docker-endpoint). ' +
+      'Or set AIFABRIX_COMPOSE_CMD. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  if (/AIFABRIX_COMPOSE_CMD/i.test(cause) && /is set but failed/i.test(cause)) {
+    return (
+      'Cannot use Docker for infrastructure: AIFABRIX_COMPOSE_CMD failed.\n\n' +
+      `Cause: ${cause}\n\n` +
+      'Unset or fix AIFABRIX_COMPOSE_CMD, or install a working Compose. Run `aifabrix doctor` for diagnostics.'
+    );
+  }
+
+  return (
+    'Cannot use Docker for infrastructure (Docker CLI missing, Compose missing, or remote Docker misconfigured).\n\n' +
+      `Cause: ${cause}\n\n` +
+      'Install Docker Engine and Compose on this machine (or set AIFABRIX_COMPOSE_CMD). ' +
+      'If you use docker-endpoint in dev config: install cert.pem, key.pem, and ca.pem for full TLS verify; use `aifabrix dev pin` / ' +
+      '`dev init --pin` as needed; or enable TLS skip-verify (config or AIFABRIX_DOCKER_TLS_SKIP_VERIFY) when appropriate. ' +
+      'Run `aifabrix doctor` for diagnostics.'
+  );
+}
+
+/**
+ * Check Docker availability (local daemon or remote via docker-endpoint + TLS).
  * @async
  * @returns {Promise<void>}
- * @throws {Error} If Docker is not available
+ * @throws {Error} If Docker/Compose cannot be used (includes underlying cause)
  */
 async function checkDockerAvailability() {
+  await ensureDevCertsIfNeededForRemoteDocker();
   try {
     await dockerUtils.ensureDockerAndCompose();
   } catch (error) {
-    throw new Error('Docker or Docker Compose is not available. Please install and start Docker.');
+    const detail = (error && error.message) || String(error);
+    throw new Error(formatDockerInfrastructureFailure(detail));
   }
 }
 
-/** Default admin password for new local installations when admin-secrets.env is empty */
-const DEFAULT_ADMIN_PASSWORD = 'admin123';
+/**
+ * Fallback for admin password/email when validated catalog load failed but YAML is still readable.
+ * @returns {Record<string, string>}
+ */
+function readInfraDefaultScalars() {
+  return readRelaxedCatalogDefaults();
+}
 
 /**
  * Log hint to reset Postgres volume when admin password was changed after first init.
@@ -66,7 +126,7 @@ const DEFAULT_ADMIN_PASSWORD = 'admin123';
 function logVolumeResetHint(infraDir) {
   logger.log(chalk.yellow(
     'If Postgres was already started with a different password, login will fail until you reset the volume. ' +
-    `Run: cd ${infraDir} && docker compose -f compose.yaml -p aifabrix down -v , then run 'aifabrix up-infra --adminPwd <password>' again.`
+    `Run: cd ${infraDir} && docker compose -f compose.yaml -p aifabrix down -v , then run 'aifabrix up-infra --adminPassword <password>' again.`
   ));
 }
 
@@ -82,9 +142,8 @@ async function syncPostgresPasswordToStore(password) {
   }
 }
 
-/** Default admin env keys and values when missing. */
+/** Non-email defaults for admin-secrets.env merge (email default comes from infra.parameter.yaml `defaults`). */
 const DEFAULT_ADMIN_OBJ = {
-  PGADMIN_DEFAULT_EMAIL: 'admin@aifabrix.dev',
   REDIS_HOST: 'local:redis:6379:0:',
   REDIS_COMMANDER_USER: 'admin'
 };
@@ -96,23 +155,87 @@ const DEFAULT_ADMIN_OBJ = {
  * @param {Object} adminObj - Decrypted admin secrets object
  * @param {string} passwordToUse - Password to set for Postgres, pgAdmin, Redis Commander
  * @param {boolean} shouldOverwriteWithAdminPwd - Whether this was an explicit admin password update
+ * @param {{ updateEmail?: boolean, emailToUse?: string }} [emailOpts]
  */
-async function applyAdminSecretsUpdate(adminSecretsPath, adminObj, passwordToUse, shouldOverwriteWithAdminPwd) {
+async function applyAdminSecretsUpdate(
+  adminSecretsPath,
+  adminObj,
+  passwordToUse,
+  shouldOverwriteWithAdminPwd,
+  emailOpts
+) {
   const merged = { ...DEFAULT_ADMIN_OBJ, ...adminObj };
   merged.POSTGRES_PASSWORD = passwordToUse;
   merged.PGADMIN_DEFAULT_PASSWORD = passwordToUse;
   merged.REDIS_COMMANDER_PASSWORD = passwordToUse;
-  const content = await secrets.formatAdminSecretsContent(merged);
-  fs.writeFileSync(adminSecretsPath, content, { mode: 0o600 });
+  if (emailOpts && emailOpts.updateEmail && emailOpts.emailToUse) {
+    merged.PGADMIN_DEFAULT_EMAIL = emailOpts.emailToUse;
+  }
+  const content = await getCoreSecrets().formatAdminSecretsContent(merged);
+  fsRealSync.writeFileSync(adminSecretsPath, content, { mode: 0o600 });
   if (shouldOverwriteWithAdminPwd) {
     logger.log('Updated admin password in admin-secrets.env.');
     await syncPostgresPasswordToStore(passwordToUse);
-    logVolumeResetHint(path.join(paths.getAifabrixHome(), getInfraDirName(0)));
+    logVolumeResetHint(path.join(paths.getAifabrixSystemDir(), getInfraDirName(0)));
+  } else if (emailOpts && emailOpts.updateEmail) {
+    logger.log('Updated admin email in admin-secrets.env.');
   } else {
     logger.log('Set default admin password in admin-secrets.env for local use.');
   }
 }
 
+function loadAdminMergedDefaultsForInfra(options) {
+  try {
+    return mergeInfraParameterDefaultsForCli(getInfraParameterCatalog().data, options);
+  } catch {
+    return mergeInfraParameterDefaultsForCli({}, options);
+  }
+}
+
+function resolveAdminPasswordAndEmailCli(options, mergedDefaults) {
+  const infraDefaults = readInfraDefaultScalars();
+  const adminPwdCli = String(options.adminPassword || options.adminPwd || '').trim();
+  const adminPwdOverride = adminPwdCli !== '' ? adminPwdCli : null;
+  const passwordToUse =
+    adminPwdOverride !== null
+      ? adminPwdOverride
+      : mergedDefaults.adminPassword || infraDefaults.adminPassword || '';
+  const emailCli = String(options.adminEmail || '').trim();
+  const emailOverride = emailCli !== '' ? emailCli : null;
+  const emailToUse =
+    emailOverride !== null
+      ? emailOverride
+      : mergedDefaults.adminEmail || infraDefaults.adminEmail || '';
+  return { adminPwdOverride, passwordToUse, emailOverride, emailToUse };
+}
+
+function computeAdminSecretsBackfillFlags(adminObj) {
+  const needsPasswordBackfill =
+    !(adminObj.POSTGRES_PASSWORD && adminObj.POSTGRES_PASSWORD.trim()) ||
+    !(adminObj.PGADMIN_DEFAULT_PASSWORD && adminObj.PGADMIN_DEFAULT_PASSWORD.trim()) ||
+    !(adminObj.REDIS_COMMANDER_PASSWORD && adminObj.REDIS_COMMANDER_PASSWORD.trim());
+  const needsEmailBackfill = !(adminObj.PGADMIN_DEFAULT_EMAIL && adminObj.PGADMIN_DEFAULT_EMAIL.trim());
+  return { needsPasswordBackfill, needsEmailBackfill };
+}
+
+function resolvePasswordForAdminFile(
+  shouldOverwriteWithAdminPwd,
+  needsPasswordBackfill,
+  passwordToUse,
+  adminObj,
+  mergedDefaults
+) {
+  if (shouldOverwriteWithAdminPwd || needsPasswordBackfill) {
+    return passwordToUse;
+  }
+  return (
+    String(adminObj.POSTGRES_PASSWORD || '').trim() ||
+    mergedDefaults.adminPassword ||
+    readInfraDefaultScalars().adminPassword ||
+    ''
+  );
+}
+
 /**
  * Ensure admin secrets file exists and set admin password.
  * When adminPwd is provided, update POSTGRES_PASSWORD, PGADMIN_DEFAULT_PASSWORD, REDIS_COMMANDER_PASSWORD
@@ -121,33 +244,48 @@ async function applyAdminSecretsUpdate(adminSecretsPath, adminObj, passwordToUse
  *
  * @async
  * @param {Object} [options] - Options
- * @param {string} [options.adminPwd] - Override admin password for Postgres, pgAdmin, Redis Commander (updates file when provided)
+ * @param {string} [options.adminPassword] - Override admin password (alias: adminPwd)
+ * @param {string} [options.adminPwd] - Override admin password for Postgres, pgAdmin, Redis Commander
+ * @param {string} [options.adminEmail] - Override pgAdmin default email (matches {{adminEmail}} defaults)
+ * @param {string} [options.userPassword] - Reserved for Keycloak user template (secrets use ensureInfraSecrets)
  * @returns {Promise<string>} Path to admin secrets file
  */
 async function ensureAdminSecrets(options = {}) {
-  const adminPwdOverride = options.adminPwd && typeof options.adminPwd === 'string' && options.adminPwd.trim() !== ''
-    ? options.adminPwd.trim()
-    : null;
-  const passwordToUse = adminPwdOverride || DEFAULT_ADMIN_PASSWORD;
-  const adminSecretsPath = path.join(paths.getAifabrixHome(), 'admin-secrets.env');
+  const mergedDefaults = loadAdminMergedDefaultsForInfra(options);
+  const { adminPwdOverride, passwordToUse, emailOverride, emailToUse } = resolveAdminPasswordAndEmailCli(
+    options,
+    mergedDefaults
+  );
+  const adminSecretsPath = path.join(paths.getAifabrixSystemDir(), 'admin-secrets.env');
 
-  if (!fs.existsSync(adminSecretsPath)) {
+  if (!fsRealSync.existsSync(adminSecretsPath)) {
     logger.log('Generating admin-secrets.env...');
-    await secrets.generateAdminSecretsEnv(undefined);
+    await getCoreSecrets().generateAdminSecretsEnv(undefined);
     return adminSecretsPath;
   }
 
   const adminObj = await adminSecrets.readAndDecryptAdminSecrets(adminSecretsPath);
-  const needsBackfill = !(adminObj.POSTGRES_PASSWORD && adminObj.POSTGRES_PASSWORD.trim()) ||
-    !(adminObj.PGADMIN_DEFAULT_PASSWORD && adminObj.PGADMIN_DEFAULT_PASSWORD.trim()) ||
-    !(adminObj.REDIS_COMMANDER_PASSWORD && adminObj.REDIS_COMMANDER_PASSWORD.trim());
+  const { needsPasswordBackfill, needsEmailBackfill } = computeAdminSecretsBackfillFlags(adminObj);
   const shouldOverwriteWithAdminPwd = adminPwdOverride !== null;
+  const shouldOverwriteEmail = emailOverride !== null;
+  const updateEmail = shouldOverwriteEmail || needsEmailBackfill;
 
-  if (!shouldOverwriteWithAdminPwd && !needsBackfill) {
+  if (!shouldOverwriteWithAdminPwd && !needsPasswordBackfill && !updateEmail) {
     return adminSecretsPath;
   }
 
-  await applyAdminSecretsUpdate(adminSecretsPath, adminObj, passwordToUse, shouldOverwriteWithAdminPwd);
+  const passwordForFile = resolvePasswordForAdminFile(
+    shouldOverwriteWithAdminPwd,
+    needsPasswordBackfill,
+    passwordToUse,
+    adminObj,
+    mergedDefaults
+  );
+
+  await applyAdminSecretsUpdate(adminSecretsPath, adminObj, passwordForFile, shouldOverwriteWithAdminPwd, {
+    updateEmail,
+    emailToUse
+  });
   return adminSecretsPath;
 }
 
@@ -215,7 +353,7 @@ async function ensureMisoInitScript(infraDir) {
   const secretKey = 'databases-miso-controller-0-passwordKeyVault';
   let password;
   try {
-    const loaded = await secrets.loadSecrets(undefined);
+    const loaded = await getCoreSecrets().loadSecrets(undefined);
     const urlOrPassword = loaded[secretKey] || loaded['databases-miso-controller-0-urlKeyVault'];
     const extracted = extractPasswordFromUrlOrValue(urlOrPassword);
     if (extracted !== null && extracted.trim() !== '') {
@@ -266,7 +404,7 @@ psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "miso" -c "GRANT AL
  * @returns {Promise<Object>} Object with infraDir and postgresPassword
  */
 async function prepareInfraDirectory(devId, adminSecretsPath) {
-  const aifabrixDir = paths.getAifabrixHome();
+  const aifabrixDir = paths.getAifabrixSystemDir();
   const infraDirName = getInfraDirName(devId);
   const infraDir = path.join(aifabrixDir, infraDirName);
   if (!fs.existsSync(infraDir)) {
@@ -283,12 +421,45 @@ async function prepareInfraDirectory(devId, adminSecretsPath) {
   }
 
   const adminObj = await adminSecrets.readAndDecryptAdminSecrets(adminSecretsPath);
-  const postgresPassword = (adminObj.POSTGRES_PASSWORD && adminObj.POSTGRES_PASSWORD.trim()) || DEFAULT_ADMIN_PASSWORD;
+  const postgresPassword =
+    (adminObj.POSTGRES_PASSWORD && adminObj.POSTGRES_PASSWORD.trim()) ||
+    readInfraDefaultScalars().adminPassword ||
+    '';
   generatePgAdminConfig(infraDir, postgresPassword);
 
   return { infraDir, postgresPassword };
 }
 
+/**
+ * Resolve infra working directory and admin-secrets path for stop/restart.
+ * Infra dir: prefer system dir compose; if missing, use legacy home when compose exists there.
+ * Admin secrets: prefer `admin-secrets.env` under system dir; if missing, use legacy home (covers mixed layouts).
+ *
+ * @param {string|number} devId - Developer ID
+ * @returns {{ infraDir: string, adminSecretsPath: string }}
+ */
+function resolveInfraStatePaths(devId) {
+  const syncFs = nodeFs();
+  const name = getInfraDirName(devId);
+  const systemBase = paths.getAifabrixSystemDir();
+  const legacyBase = paths.getAifabrixHome();
+  const sysInfra = path.join(systemBase, name);
+  const legInfra = path.join(legacyBase, name);
+  const sysCompose = path.join(sysInfra, 'compose.yaml');
+  const legCompose = path.join(legInfra, 'compose.yaml');
+  let infraDir = sysInfra;
+  if (!syncFs.existsSync(sysCompose) && syncFs.existsSync(legCompose) && legacyBase !== systemBase) {
+    infraDir = legInfra;
+  }
+  const sysAdmin = path.join(systemBase, 'admin-secrets.env');
+  const legAdmin = path.join(legacyBase, 'admin-secrets.env');
+  let adminSecretsPath = sysAdmin;
+  if (!syncFs.existsSync(sysAdmin) && syncFs.existsSync(legAdmin) && legacyBase !== systemBase) {
+    adminSecretsPath = legAdmin;
+  }
+  return { infraDir, adminSecretsPath };
+}
+
 /**
  * Register Handlebars helper for equality comparison
  */
@@ -313,6 +484,7 @@ module.exports = {
   ensureAdminSecrets,
   generatePgAdminConfig,
   prepareInfraDirectory,
+  resolveInfraStatePaths,
   ensureMisoInitScript,
   registerHandlebarsHelper
 };