@aifabrix/builder 2.44.6 → 2.45.0

package/lib/utils/compose-generate-docker-compose.js

@@ -15,6 +15,99 @@ const paths = require('./paths');
 const { getInfraDirName } = require('../infrastructure/helpers');
 const { resolveMisoEnvironment } = require('./compose-miso-env');
 
+/**
+ * When running a pulled Python image (no bind-mounted source), the image CMD may invoke the
+ * `uvicorn` console script, which is not always on PATH. Derive a `python -m uvicorn` command from
+ * `build.reloadStart` so generated compose matches the same app entrypoint as hot-reload runs.
+ *
+ * @param {string|undefined} reloadStart - Value from application.yaml `build.reloadStart`
+ * @returns {string|null} Shell command fragment (no `cd`, no `exec`; image compose prepends `exec ` in JS)
+ */
+function derivePythonImageStartFromReload(reloadStart) {
+  if (typeof reloadStart !== 'string' || !reloadStart.trim()) {
+    return null;
+  }
+  const trimmed = reloadStart.trim().replace(/\s+--reload\b/g, '').trim();
+  if (/^python3?\s+-m\s+uvicorn\s+/i.test(trimmed)) {
+    return normalizeComposeShellPortRef(trimmed);
+  }
+  if (trimmed.startsWith('uvicorn ')) {
+    const rest = trimmed.slice('uvicorn '.length);
+    return normalizeComposeShellPortRef(`python -m uvicorn ${rest}`);
+  }
+  return null;
+}
+
+/**
+ * Compose sets `PORT` in the service environment; replace `${PORT:-...}` with `$$PORT` in the
+ * fragment so the compose file avoids ambiguous `:` parsing in flow scalars and Compose expands
+ * `$$` to `$` for the container shell (which then expands `PORT` from the service environment).
+ *
+ * @param {string} cmd - Shell command fragment
+ * @returns {string} Same fragment with `${PORT:-...}` replaced by `$$PORT` (Compose escapes `$$` → `$` for the shell)
+ */
+function normalizeComposeShellPortRef(cmd) {
+  return cmd.replace(/\$\{PORT:-[^}]+\}/g, () => '$$PORT');
+}
+
+/**
+ * Normalizes `build.reloadStart` for Python when using a bind-mounted source in compose.
+ *
+ * @param {string} raw - Trimmed reload command
+ * @returns {string} Command suitable for `cd /app && …` in compose
+ */
+function normalizePythonReloadForComposeMounted(raw) {
+  const s = normalizeComposeShellPortRef(raw);
+  if (/^python3?\s+-m\s+uvicorn\s+/i.test(s)) {
+    return s;
+  }
+  if (s.startsWith('uvicorn ')) {
+    return `python -m uvicorn ${s.slice('uvicorn '.length)}`;
+  }
+  return s;
+}
+
+/**
+ * Builds the single `reloadStartCommand` passed to compose templates (`command: …` when set).
+ *
+ * `applications.<app>.reload` in config.yaml (and `aifabrix run --reload`) only controls **bind-mount +
+ * `--reload`** via `devMountPath`. For pulled images without a mount, use optional `build.imageRun` in
+ * application.yaml, or (Python only) derive from `build.reloadStart` when `imageRun` is unset.
+ *
+ * @param {string} language - `application.yaml` build.language
+ * @param {string|null} devMountPath - Bind mount path when reload sync is active
+ * @param {string|undefined} reloadRaw - `build.reloadStart`
+ * @param {Object} [build] - `application.yaml` `build` object (`imageRun`, etc.)
+ * @returns {string|null}
+ */
+function buildReloadStartCommandForCompose(language, devMountPath, reloadRaw, build = {}) {
+  const buildObj = build && typeof build === 'object' ? build : {};
+  const imageRunRaw = typeof buildObj.imageRun === 'string' ? buildObj.imageRun.trim() : '';
+  const reloadTrimmed = typeof reloadRaw === 'string' ? reloadRaw.trim() : '';
+
+  if (devMountPath) {
+    if (!reloadTrimmed) {
+      return null;
+    }
+    return language === 'python' ? normalizePythonReloadForComposeMounted(reloadTrimmed) : reloadTrimmed;
+  }
+
+  if (imageRunRaw) {
+    return normalizeComposeShellPortRef(imageRunRaw);
+  }
+
+  if (!reloadTrimmed) {
+    return null;
+  }
+
+  if (language === 'python') {
+    const imageCmd = derivePythonImageStartFromReload(reloadTrimmed);
+    return imageCmd ? `exec ${imageCmd}` : null;
+  }
+
+  return null;
+}
+
 /**
  * Resolve infra `pgpass` path: prefer system config dir; when home differs, allow legacy layout.
  * @param {string|number} devId - Developer id (infra vs infra-dev{n})
@@ -119,14 +212,15 @@ async function loadComposeHead(deps, appName, appConfig, options) {
  * @param {object} head - From loadComposeHead
  * @returns {object}
  */
-function buildComposeLayouts(deps, appName, appConfig, head) {
+function buildComposeLayouts(deps, appName, appConfig, head, options) {
   const { buildNetworkAndContainerNames, buildServiceConfig, buildVolumesConfig, buildNetworksConfig } = deps;
   const { port, imageOverride, devId, idNum, scoped, remoteServer } = head;
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum, scoped);
   const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, {
     imageOverride,
     scopeOpts: scoped,
-    remoteServer
+    remoteServer,
+    omitAppTraefikLabels: options && options.omitAppTraefikLabels === true
   });
   const volumesConfig = buildVolumesConfig(appName);
   const networksConfig = buildNetworksConfig(appConfig);
@@ -161,8 +255,13 @@ async function resolveComposePathsAndSecrets(ctx) {
   );
   const devMountPath = resolveDevMountPath(options);
   const reloadRaw = appConfig.build?.reloadStart;
-  const reloadStartCommand =
-    devMountPath && typeof reloadRaw === 'string' && reloadRaw.trim().length > 0 ? reloadRaw.trim() : null;
+  const language = appConfig.build?.language || appConfig.language || 'typescript';
+  const reloadStartCommand = buildReloadStartCommandForCompose(
+    language,
+    devMountPath,
+    reloadRaw,
+    appConfig.build
+  );
   const infraPgpassPath = resolveInfraPgpassPath(devId, paths, fsSync.existsSync);
   const useInfraPgpass = serviceCf.requiresDatabase && fsSync.existsSync(infraPgpassPath);
   return {
@@ -185,7 +284,7 @@ async function resolveComposePathsAndSecrets(ctx) {
  */
 async function generateDockerComposeImpl(deps, appName, appConfig, options) {
   const head = await loadComposeHead(deps, appName, appConfig, options);
-  const layouts = buildComposeLayouts(deps, appName, appConfig, head);
+  const layouts = buildComposeLayouts(deps, appName, appConfig, head, options);
   const side = await resolveComposePathsAndSecrets({
     options,
     appName,
@@ -213,4 +312,10 @@ function createGenerateDockerCompose(deps) {
   return (appName, appConfig, options) => generateDockerComposeImpl(deps, appName, appConfig, options);
 }
 
-module.exports = { createGenerateDockerCompose, resolveInfraPgpassPath };
+module.exports = {
+  createGenerateDockerCompose,
+  resolveInfraPgpassPath,
+  derivePythonImageStartFromReload,
+  buildReloadStartCommandForCompose,
+  normalizePythonReloadForComposeMounted
+};

package/lib/utils/compose-generator.js

@@ -282,10 +282,16 @@ function buildRequiresConfig(config) {
  * @param {string} [runExtras.imageOverride] - Full image reference for run (e.g. from --image)
  * @param {Object|null} [runExtras.scopeOpts] - Traefik / scoped compose options
  * @param {string|null|undefined} [runExtras.remoteServer] - For ${REMOTE_HOST} in frontDoorRouting.host
+ * @param {boolean} [runExtras.omitAppTraefikLabels] - When true (user config `traefik: false`), omit Traefik labels and BASE_PATH env from compose even if application.yaml enables frontDoorRouting
  * @returns {Object} Service configuration
  */
 function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
-  const { imageOverride = null, scopeOpts = null, remoteServer = null } = runExtras;
+  const {
+    imageOverride = null,
+    scopeOpts = null,
+    remoteServer = null,
+    omitAppTraefikLabels = false
+  } = runExtras;
   const containerPortValue = getContainerPort(config, 3000);
   const hostPort = port;
   const useTraefikScope =
@@ -305,13 +311,16 @@ function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
     containerPort: containerPortValue, // Container port (always set, equals containerPort if exists, else port)
     hostPort: hostPort, // Host port (options.port if provided, else config.port)
     healthCheck,
-    traefik: buildTraefikConfig(
-      config,
-      devId,
-      scopeForHealthAndTraefik,
-      remoteServer,
-      healthCheck.path
-    ),
+    traefik:
+      omitAppTraefikLabels === true
+        ? { enabled: false }
+        : buildTraefikConfig(
+          config,
+          devId,
+          scopeForHealthAndTraefik,
+          remoteServer,
+          healthCheck.path
+        ),
     ...buildRequiresConfig(config)
   };
 }

package/lib/utils/controller-url.js

@@ -42,8 +42,38 @@ function normalizeUrl(url) {
 }
 
 /**
- * Get controller URL from logged-in user's device tokens
- * Returns the first available controller URL from device tokens stored in config
+ * True when `config.yaml` has a non-expired-looking device entry for this controller URL
+ * (normalized host/path comparison).
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function hasStoredDeviceTokenForController(controllerUrl) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    return false;
+  }
+  const want = normalizeUrl(controllerUrl);
+  if (!want) {
+    return false;
+  }
+  try {
+    const userConfig = await config.getConfig();
+    if (!userConfig.device || typeof userConfig.device !== 'object') {
+      return false;
+    }
+    return Object.keys(userConfig.device).some((key) => normalizeUrl(key) === want);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get controller URL from logged-in user's device tokens.
+ * Prefers the entry under {@link config.controller} when it matches a `device` key; otherwise a
+ * single `device` entry; with multiple unrelated entries and no matching default, returns **null**
+ * (callers must not treat arbitrary key order as the active controller).
+ *
  * @async
  * @function getControllerUrlFromLoggedInUser
  * @returns {Promise<string|null>} Controller URL from logged-in user, or null if not found
@@ -60,11 +90,23 @@ async function getControllerUrlFromLoggedInUser() {
       return null;
     }
 
-    // Return the first available controller URL (normalized)
-    const firstControllerUrl = deviceUrls[0];
-    return normalizeUrl(firstControllerUrl);
-  } catch (error) {
-    // If config doesn't exist or can't be read, return null
+    const cfgController =
+      userConfig.controller && typeof userConfig.controller === 'string'
+        ? normalizeUrl(userConfig.controller)
+        : '';
+    if (cfgController) {
+      const match = deviceUrls.find((u) => normalizeUrl(u) === cfgController);
+      if (match) {
+        return normalizeUrl(match);
+      }
+    }
+
+    if (deviceUrls.length === 1) {
+      return normalizeUrl(deviceUrls[0]);
+    }
+
+    return null;
+  } catch {
     return null;
   }
 }
@@ -109,6 +151,7 @@ async function resolveControllerUrl() {
 
 module.exports = {
   getDefaultControllerUrl,
+  hasStoredDeviceTokenForController,
   getControllerUrlFromLoggedInUser,
   getControllerFromConfig,
   resolveControllerUrl

package/lib/utils/env-copy.js

@@ -11,6 +11,7 @@ const { formatSuccessLine } = require('./cli-test-layout-chalk');
 
 const fs = require('fs');
 const fsp = require('fs').promises;
+const fsRealSync = require('../internal/fs-real-sync');
 const path = require('path');
 const yaml = require('js-yaml');
 const logger = require('./logger');
@@ -98,22 +99,37 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
 }
 
 /**
- * Writes .env to envOutputPath for reload path: merge run .env into existing file.
+ * Writes .env to envOutputPath for `--reload`: merge container `.env.run` into the host file.
+ * Preserves comments when a file already exists (e.g. after `aifabrix resolve`). Keys present only
+ * in `.env.run` (compose-only such as DB_0_NAME) are **not** appended unless they already exist as
+ * `KEY=` lines in the base file. If the output file is missing, seeds from `generateEnvContent`
+ * (`local`) so the host file keeps template comments and localhost-oriented URLs.
+ *
  * @async
  * @param {string} outputPath - Resolved output path
  * @param {string} runEnvPath - Path to .env.run
+ * @param {string} appName - Application name (for template seed when output is absent)
  */
-async function writeEnvOutputForReload(outputPath, runEnvPath) {
-  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent, generateEnvContent } = require('../core/secrets');
   const runContent = await fsp.readFile(runEnvPath, 'utf8');
   const runMap = parseEnvContentToMap(runContent);
-  let toWrite = runContent;
-  if (fs.existsSync(outputPath)) {
-    const existingContent = await fsp.readFile(outputPath, 'utf8');
-    toWrite = mergeEnvMapIntoContent(existingContent, runMap);
+  let baseContent;
+  if (fsRealSync.existsSync(outputPath)) {
+    baseContent = await fsp.readFile(outputPath, 'utf8');
+  } else if (appName) {
+    baseContent = await generateEnvContent(appName, null, 'local', false);
+    baseContent = substituteMntDataForLocal(baseContent, outputPath);
+  } else {
+    baseContent = runContent;
   }
+  const toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
-  logger.log(formatSuccessLine(`Wrote .env to envOutputPath (same as container, for --reload): ${outputPath}`));
+  logger.log(
+    formatSuccessLine(
+      `Wrote .env to envOutputPath (--reload: merged container env; no extra keys): ${outputPath}`
+    )
+  );
 }
 
 /**
@@ -245,6 +261,30 @@ async function patchEnvContentForLocal(envContent, variables) {
   return envContent;
 }
 
+/**
+ * Copy the just-written builder `<appPath>/.env` to `build.envOutputPath` so both files
+ * share the same resolution pass (no second `generateEnvContent` with a different environment).
+ * Applies {@link substituteMntDataForLocal} for host paths; merges into an existing output file
+ * when present (preserves comments).
+ *
+ * @async
+ * @param {string} envPath - Path to `<appPath>/.env` (already written)
+ * @param {string} outputPath - Resolved `build.envOutputPath`
+ * @param {string} envOutputPathLabel - Label for log (e.g. raw `build.envOutputPath` value)
+ */
+async function syncWrittenBuilderEnvToOutputPath(envPath, outputPath, envOutputPathLabel) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const raw = fs.readFileSync(envPath, 'utf8');
+  const synced = substituteMntDataForLocal(raw, outputPath);
+  let toWrite = synced;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = fs.readFileSync(outputPath, 'utf8');
+    toWrite = mergeEnvMapIntoContent(existingContent, parseEnvContentToMap(synced));
+  }
+  fs.writeFileSync(outputPath, toWrite, { mode: 0o600 });
+  logger.log(formatSuccessLine(`Copied resolved .env to envOutputPath (${envOutputPathLabel})`));
+}
+
 /**
  * Write regenerated local .env to output path (merge with existing if present).
  * @async
@@ -252,10 +292,12 @@ async function patchEnvContentForLocal(envContent, variables) {
  * @param {string} appName - Application name
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @param {string} envOutputPathLabel - Label for log message (e.g. variables.build.envOutputPath)
+ * @param {Object} [extraOpts] - Optional: `appPath` for {@link module:lib/core/secrets-env-content.generateEnvContent}
  */
-async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel) {
+async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel, extraOpts = {}) {
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
-  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
+  const genOpts = extraOpts.appPath ? { appPath: extraOpts.appPath } : {};
+  let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false, genOpts);
   localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
   let toWrite = localEnvContent;
   if (fs.existsSync(outputPath)) {
@@ -284,16 +326,45 @@ async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOu
 }
 
 /**
- * Process and optionally copy env file to envOutputPath if configured
- * Regenerates .env file with env=local for local development (apps/.env)
+ * Process and optionally copy env file to envOutputPath if configured.
+ * When `appName` is set and `preferLocalEnvOutputPath` is true, regenerates **local**-flavored env at
+ * `build.envOutputPath` (IDE/host). **False** only when `remote-server` and `applications.<app>.reload` are both set
+ * (docker flavor at env output). Otherwise, when `appName`
+ * is set and `envPath` exists, copies the same resolved `<appPath>/.env` content to the output path.
+ * Falls back to local regeneration when `envPath` is missing, or patched copy when `appName` is omitted.
+ *
  * @async
  * @function processEnvVariables
  * @param {string} envPath - Path to generated .env file
  * @param {string} variablesPath - Path to application config
  * @param {string} appName - Application name (for regenerating with local env)
  * @param {string} [secretsPath] - Path to secrets file (optional, for regenerating)
+ * @param {Object} [copyOptions] - Optional: `preferLocalEnvOutputPath` (IDE/host file gets **local** flavor
+ *   while `<appPath>/.env` may be docker); `appPath` overrides app root for local regeneration
  */
-async function processEnvVariables(envPath, variablesPath, appName, secretsPath) {
+async function copyOrRegenerateEnvForNamedApp(opts) {
+  const {
+    envPath,
+    outputPath,
+    appName,
+    secretsPath,
+    label,
+    preferLocal,
+    appPathForLocal
+  } = opts;
+  const localOpts = { appPath: appPathForLocal || undefined };
+  if (preferLocal) {
+    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+    return;
+  }
+  if (fs.existsSync(envPath)) {
+    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label);
+    return;
+  }
+  await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);
+}
+
+async function processEnvVariables(envPath, variablesPath, appName, secretsPath, copyOptions = {}) {
   if (!variablesPath || !fs.existsSync(variablesPath)) {
     return;
   }
@@ -310,8 +381,21 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
   }
 
   const label = variables.build.envOutputPath;
+  const appPathForLocal =
+    (copyOptions && copyOptions.appPath) ||
+    (variablesPath ? path.dirname(variablesPath) : null);
+  const preferLocal =
+    copyOptions && typeof copyOptions === 'object' && copyOptions.preferLocalEnvOutputPath === true;
   if (appName) {
-    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label);
+    await copyOrRegenerateEnvForNamedApp({
+      envPath,
+      outputPath,
+      appName,
+      secretsPath,
+      label,
+      preferLocal,
+      appPathForLocal
+    });
   } else {
     await writePatchedEnvToOutputPath(envPath, outputPath, variables, label);
   }
@@ -321,6 +405,7 @@ module.exports = {
   processEnvVariables,
   resolveEnvOutputPath,
   substituteMntDataForLocal,
+  syncWrittenBuilderEnvToOutputPath,
   writeEnvOutputForReload,
   writeEnvOutputForLocal
 };

package/lib/utils/env-template.js

@@ -13,6 +13,7 @@ const fsSync = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const pathsUtil = require('./paths');
 
 /**
  * Updates env.template to add MISO_CLIENTID, MISO_CLIENTSECRET, and optionally MISO_CONTROLLER_URL.
@@ -105,7 +106,10 @@ ${missingEntries.join('\n')}
 }
 
 async function updateEnvTemplate(appKey, clientIdKey, clientSecretKey, _controllerUrl) {
-  const envTemplatePath = path.join(process.cwd(), 'builder', appKey, 'env.template');
+  // Use paths.getBuilderPath so the system builder root (e.g. ~/.aifabrix/builder/<app>) and
+  // AIFABRIX_BUILDER_DIR are respected. Falling back to process.cwd() previously made the binary
+  // CLI skip env.template updates whenever cwd was a non-builder repo (e.g. aifabrix-training).
+  const envTemplatePath = path.join(pathsUtil.getBuilderPath(appKey), 'env.template');
 
   if (!fsSync.existsSync(envTemplatePath)) {
     logger.warn(chalk.yellow(`⚠  env.template not found for ${appKey}, skipping update`));

package/lib/utils/health-check-url.js

@@ -62,19 +62,9 @@ function frontDoorPattern(appConfig) {
   return (typeof p === 'string' && p.trim()) ? p.trim() : null;
 }
 
-/**
- * Compute the Traefik front-door health check URL when applicable.
- *
- * Returns null when Traefik/frontDoorRouting isn't active or cannot be resolved.
- *
- * @async
- * @param {string} appName
- * @param {number} healthCheckPort
- * @param {Object|null} appConfig
- * @returns {Promise<string|null>}
- */
 /**
  * Public app URL (Traefik + frontDoor mount path), without the health path — for CLI summaries.
+ * Requires infra Traefik on, `frontDoorRouting.enabled`, host, and pattern.
  *
  * @async
  * @param {string} appName
@@ -83,7 +73,7 @@ function frontDoorPattern(appConfig) {
  * @returns {Promise<string|null>}
  */
 async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig) {
-  if (!frontDoorEnabled(appConfig)) return null;
+  if (!appConfig || !frontDoorEnabled(appConfig)) return null;
   const pattern = frontDoorPattern(appConfig);
   if (!pattern) return null;
 
@@ -91,6 +81,13 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
   const userCfg = await coreConfig.getConfig();
   if (!(userCfg && userCfg.traefik)) return null;
 
+  const fd = appConfig.frontDoorRouting;
+  if (!fd || typeof fd !== 'object') return null;
+  const hostTemplate = typeof fd.host === 'string' ? fd.host.trim() : '';
+  if (!hostTemplate) return null;
+
+  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+
   const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
   const remoteServer = await coreConfig.getRemoteServer();
   const developerIdRaw = await coreConfig.getDeveloperId();
@@ -98,7 +95,6 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
 
   // URLs are resolved for the CLI on the host, not from inside a container.
   const profile = 'local';
-  const fd = appConfig.frontDoorRouting;
   const listenPort = Number(appConfig?.port || 3000);
 
   const publicBase = computePublicUrlBaseString({
@@ -114,10 +110,18 @@ async function computeTraefikPublicAppUrl(_appName, _healthCheckPort, appConfig)
     infraTlsEnabled
   });
 
-  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
   return joinUrlPath(publicBase, mountPath);
 }
 
+/**
+ * Traefik public URL including health path.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
 async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
   const baseWithFrontDoor = await computeTraefikPublicAppUrl(appName, healthCheckPort, appConfig);
   if (!baseWithFrontDoor) return null;
@@ -131,4 +135,3 @@ module.exports = {
   computeTraefikPublicAppUrl,
   computeTraefikHealthCheckUrl
 };
-

package/lib/utils/health-check.js

@@ -16,7 +16,8 @@ const dns = require('dns');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { execWithDockerEnv } = require('./docker-exec');
-const { computeTraefikHealthCheckUrl } = require('./health-check-url');
+/** Namespace require so tests can `jest.spyOn` on `./health-check-url` exports. */
+const healthCheckUrl = require('./health-check-url');
 const { computePathActive } = require('./url-declarative-url-flags');
 const { isFrontDoorRoutingEnabledInDoc } = require('./url-declarative-vdir-inactive-env');
 const { waitForDbInit } = require('./health-check-db-init');
@@ -69,10 +70,11 @@ async function computeHealthCheckUrl(appName, healthCheckPort, appConfig, _opts
     const runOptions = (_opts && typeof _opts === 'object') ? _opts.runOptions : null;
     const wantsTraefik =
       Boolean(runOptions) &&
-      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true);
+      (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true) &&
+      isFrontDoorRoutingEnabledInDoc(appConfig);
     if (!wantsTraefik) return '';
     try {
-      return await computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
+      return await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig);
     } catch {
       return '';
     }
@@ -380,10 +382,10 @@ async function computePreferredHealthCheckUrls(appName, healthCheckPort, config,
   let skippedPublicHealthUrl = '';
   const wantsTraefikFirst = Boolean(
     runOptions && (runOptions.probeViaTraefik === true || runOptions.traefikEnabled === true)
-  );
+  ) && isFrontDoorRoutingEnabledInDoc(config);
   if (wantsTraefikFirst) {
     try {
-      traefikUrl = await computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
+      traefikUrl = await healthCheckUrl.computeTraefikHealthCheckUrl(appName, healthCheckPort, config);
     } catch {
       traefikUrl = '';
     }

package/lib/utils/infra-optional-service-flags.js

@@ -0,0 +1,69 @@
+/**
+ * Optional infra compose flags (Traefik, pgAdmin, Redis Commander) for config.yaml ↔ startInfra.
+ *
+ * @fileoverview Effective flag resolution + backfill missing keys after up-infra / setup
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+
+/**
+ * Resolves effective boolean from CLI option vs config.
+ * @param {*} optValue - options.traefik | options.pgAdmin | options.redisAdmin
+ * @param {*} cfgValue - cfg.traefik | cfg.pgadmin | cfg.redisCommander
+ * @param {boolean} defaultWhenUndef - Default when config value is undefined
+ * @returns {boolean}
+ */
+function resolveInfraOptionalFlag(optValue, cfgValue, defaultWhenUndef = true) {
+  if (optValue === true) return true;
+  if (optValue === false) return false;
+  return cfgValue !== false && (cfgValue === true || defaultWhenUndef);
+}
+
+/**
+ * Effective optional infra service flags (same resolution as up-infra → startInfra).
+ *
+ * @param {Object} cfg - Config from {@link config.getConfig}
+ * @param {Object} [options] - Commander options (omit for setup-modes)
+ * @returns {{ traefik: boolean, pgadmin: boolean, redisCommander: boolean }}
+ */
+function computeEffectiveInfraOptionalFlags(cfg, options = {}) {
+  return {
+    traefik: resolveInfraOptionalFlag(options.traefik, cfg.traefik, false),
+    pgadmin: resolveInfraOptionalFlag(options.pgAdmin, cfg.pgadmin, true),
+    redisCommander: resolveInfraOptionalFlag(options.redisAdmin, cfg.redisCommander, true)
+  };
+}
+
+/**
+ * Writes `traefik` / `pgadmin` / `redisCommander` when missing so config matches compose defaults.
+ *
+ * @param {Object} cfg - Mutable config (updated when save runs)
+ * @param {{ traefik: boolean, pgadmin: boolean, redisCommander: boolean }} effective
+ * @returns {Promise<void>}
+ */
+async function persistMissingInfraOptionalServiceFlags(cfg, effective) {
+  const keys = ['traefik', 'pgadmin', 'redisCommander'];
+  const merged = { ...cfg };
+  let dirty = false;
+  for (const k of keys) {
+    if (typeof merged[k] === 'undefined') {
+      merged[k] = effective[k];
+      dirty = true;
+    }
+  }
+  if (!dirty) {
+    return;
+  }
+  await config.saveConfig(merged);
+  Object.assign(cfg, merged);
+}
+
+module.exports = {
+  resolveInfraOptionalFlag,
+  computeEffectiveInfraOptionalFlags,
+  persistMissingInfraOptionalServiceFlags
+};