@aifabrix/builder 2.45.5 → 2.47.0

package/lib/app/down.js

@@ -18,6 +18,13 @@ const logger = require('../utils/logger');
 const config = require('../core/config');
 const helpers = require('./run-helpers');
 const { validateAppName } = require('./push');
+const buildCopy = require('../utils/build-copy');
+const {
+  getCeleryCompanionAppKeys,
+  loadBuilderApplicationConfig
+} = require('../utils/celery-companion-apps');
+const fsSync = require('fs');
+const path = require('path');
 
 /**
  * Executes a shell command asynchronously.
@@ -48,6 +55,8 @@ function execAsync(command, options = {}) {
  * @param {number|string} developerId - Developer ID
  * @returns {string} Docker volume name
  */
+const { collectDeveloperVolumeIdSuffixes } = require('../utils/developer-volume-id');
+
 function getAppVolumeName(appName, developerId) {
   const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   if (idNum === 0) {
@@ -56,6 +65,69 @@ function getAppVolumeName(appName, developerId) {
   return `aifabrix_dev${developerId}_${appName}_data`;
 }
 
+/**
+ * Docker volume name candidates for an app (handles dev6 vs dev06 naming drift).
+ *
+ * @param {string} appName
+ * @param {string|number} developerId
+ * @returns {string[]}
+ */
+function getAppVolumeNameCandidates(appName, developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (idNum === 0) {
+    return [`aifabrix_${appName}_data`, `aifabrix_dev0_${appName}_data`];
+  }
+  const suffixes = collectDeveloperVolumeIdSuffixes(developerId);
+  return suffixes.map((suffix) => `aifabrix_dev${suffix}_${appName}_data`);
+}
+
+function buildVolumeRemovalCandidates(appName, developerId) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const primaryName = getAppVolumeName(appName, developerId);
+  const legacyDev0Name = idNum === 0 ? `aifabrix_dev0_${appName}_data` : null;
+  return Array.from(new Set([primaryName, legacyDev0Name].filter(Boolean)));
+}
+
+async function removeVolumeIfPresent(volumeName) {
+  logger.log(chalk.yellow(`Removing volume ${volumeName}...`));
+  try {
+    await execAsync(`docker volume rm -f ${volumeName}`);
+    logger.log(formatSuccessLine(`Volume ${volumeName} removed`));
+  } catch (volErr) {
+    logger.log(chalk.gray(`Volume ${volumeName} not found or already removed`));
+  }
+}
+
+async function removeAppVolumes(appName, developerId) {
+  for (const volumeName of buildVolumeRemovalCandidates(appName, developerId)) {
+    await removeVolumeIfPresent(volumeName);
+  }
+}
+
+async function stopAppContainers(appName, companionKeys, developerId) {
+  const devDir = buildCopy.getDevDirectory(appName, developerId);
+  const composePath = path.join(devDir, 'docker-compose.yaml');
+
+  if (companionKeys.length > 0 && fsSync.existsSync(composePath)) {
+    try {
+      await execAsync(`docker compose -f "${composePath}" down`);
+      return;
+    } catch (composeErr) {
+      logger.log(chalk.gray(`Compose down: ${composeErr.message}; stopping containers individually`));
+      for (const companionKey of companionKeys) {
+        await helpers.stopAndRemoveContainer(companionKey, developerId, false);
+      }
+      await helpers.stopAndRemoveContainer(appName, developerId, false);
+      return;
+    }
+  }
+
+  await helpers.stopAndRemoveContainer(appName, developerId, false);
+  for (const companionKey of companionKeys) {
+    await helpers.stopAndRemoveContainer(companionKey, developerId, false);
+  }
+}
+
 /**
  * Stops and removes a specific application's container.
  * If --volumes is passed, attempts to remove the app's named Docker volume.
@@ -75,42 +147,20 @@ function getAppVolumeName(appName, developerId) {
  */
 async function downApp(appName, options = {}) {
   try {
-    // Input validation
     if (!appName || typeof appName !== 'string') {
       throw new Error('Application name is required and must be a string');
     }
     validateAppName(appName);
 
     const volumes = !!options.volumes;
-
-    // Load developer ID
     const developerId = await config.getDeveloperId();
+    const appConfig = loadBuilderApplicationConfig(appName);
+    const companionKeys = getCeleryCompanionAppKeys(appName, appConfig);
 
-    // Stop and remove container (idempotent handling in helper logs when not running)
-    await helpers.stopAndRemoveContainer(appName, developerId, false);
+    await stopAppContainers(appName, companionKeys, developerId);
 
-    // Optionally remove named Docker volume (ignore if it doesn't exist)
     if (volumes) {
-      const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
-      // Primary expected name
-      const primaryName = getAppVolumeName(appName, developerId);
-      // Legacy name used when devId \"0\" was treated as string in templates
-      const legacyDev0Name = idNum === 0 ? `aifabrix_dev0_${appName}_data` : null;
-      // Build list of candidates, unique and non-empty
-      const candidates = Array.from(
-        new Set([primaryName, legacyDev0Name].filter(Boolean))
-      );
-
-      for (const volumeName of candidates) {
-        logger.log(chalk.yellow(`Removing volume ${volumeName}...`));
-        try {
-          await execAsync(`docker volume rm -f ${volumeName}`);
-          logger.log(formatSuccessLine(`Volume ${volumeName} removed`));
-        } catch (volErr) {
-          // Swallow errors for missing volume; provide neutral message
-          logger.log(chalk.gray(`Volume ${volumeName} not found or already removed`));
-        }
-      }
+      await removeAppVolumes(appName, developerId);
     }
   } catch (error) {
     // Provide meaningful error while avoiding sensitive info
@@ -120,6 +170,7 @@ async function downApp(appName, options = {}) {
 
 module.exports = {
   downApp,
-  getAppVolumeName
+  getAppVolumeName,
+  getAppVolumeNameCandidates
 };
 

package/lib/app/index.js

@@ -93,7 +93,7 @@ function validateAppNameAndSetup(appName, options) {
 
   const initialType = options.type || 'external';
   const baseDir = getBaseDirForAppType(initialType);
-  const appPath = paths.getAppPath(appName, initialType);
+  const appPath = paths.getAppCreatePath(appName, initialType);
 
   return { initialType, baseDir, appPath };
 }
@@ -124,7 +124,7 @@ async function handleTemplateSetup(options) {
  */
 async function prepareFinalAppPath(appName, config, initialAppPath) {
   const finalBaseDir = getBaseDirForAppType(config.type);
-  const finalAppPath = paths.getAppPath(appName, config.type);
+  const finalAppPath = paths.getAppCreatePath(appName, config.type);
 
   // If path changed, validate the new path
   if (finalAppPath !== initialAppPath) {

package/lib/app/push.js

@@ -19,7 +19,7 @@ const {
 
 const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
-const { detectAppType } = require('../utils/paths');
+const paths = require('../utils/paths');
 
 /**
  * Validate application name format
@@ -92,11 +92,10 @@ function extractImageName(config, appName) {
  * @throws {Error} If configuration cannot be loaded
  */
 async function loadPushConfig(appName, options) {
-  const { detectAppType, resolveApplicationConfigPath } = require('../utils/paths');
   const { loadConfigFile } = require('../utils/config-format');
-  const { appPath } = await detectAppType(appName);
   try {
-    const configPath = resolveApplicationConfigPath(appPath);
+    const { appPath } = await paths.detectAppType(appName);
+    const configPath = paths.resolveApplicationConfigPath(appPath);
     const config = loadConfigFile(configPath);
     const effective = getEffectiveConfig(config);
     const registry = options.registry || effective.image?.registry;
@@ -242,7 +241,7 @@ function displayPushResults(registry, imageName, tags) {
  */
 async function pushApp(appName, options = {}) {
   try {
-    const { isExternal } = await detectAppType(appName);
+    const { isExternal } = await paths.detectAppType(appName);
     if (isExternal) {
       logExternalIntegrationPushNotice(appName);
       return;

package/lib/app/register.js

@@ -25,6 +25,8 @@ const { callRegisterApi } = require('../utils/app-register-api');
 const { displayRegistrationResults, getEnvironmentPrefix } = require('../utils/app-register-display');
 const pathsUtil = require('../utils/paths');
 const { refreshUrlsLocalRegistryFromBuilder } = require('../utils/urls-local-registry');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const config = require('../core/config');
 
 /**
  * Build registration data payload from app configuration
@@ -152,9 +154,6 @@ async function applyLocalhostPortAdjustment(appConfig, apiUrl, options) {
  */
 async function registerApplication(appKey, options = {}) {
   logger.log(chalk.blue('📋 Registering application...\n'));
-
-  const { resolveControllerUrl } = require('../utils/controller-url');
-  const config = require('../core/config');
   await config.ensureSecretsEncryptionKey();
   const { resolveEnvironment } = config;
 
@@ -168,7 +167,11 @@ async function registerApplication(appKey, options = {}) {
   const appConfig = await extractAppConfiguration(finalVariables, appKey, options);
   await validateAppRegistrationData(appConfig, appKey);
 
-  const [controllerUrl, environmentKey] = await Promise.all([resolveControllerUrl(), resolveEnvironment()]);
+  const controllerUrl = await resolveControllerUrl();
+  const environmentKey =
+    options && options.envKey
+      ? String(options.envKey).trim().toLowerCase()
+      : await resolveEnvironment();
   const authConfig = await checkAuthentication(controllerUrl, environmentKey);
   const environment = registerApplicationSchema.environmentId(environmentKey);
 

package/lib/app/run-env-compose.js

@@ -14,9 +14,28 @@ const fs = require('fs').promises;
 const fsSync = require('fs');
 const pathsUtil = require('../utils/paths');
 const adminSecrets = require('../core/admin-secrets');
+const config = require('../core/config');
 const secretsEnsure = require('../core/secrets-ensure');
 const secretsEnvWrite = require('../core/secrets-env-write');
 const { getContainerPort } = require('../utils/port-resolver');
+const { applyAdminSecretsPlatformOverlay } = require('../core/admin-secrets-env-overlay');
+
+/**
+ * Merge app env with admin-secrets; overlay ensures platform keys come from admin file.
+ * @param {Object.<string, string>} merged
+ * @param {Object.<string, string>} adminObj
+ */
+function mergeRunEnvWithAdminOverlay(merged, adminObj) {
+  applyAdminSecretsPlatformOverlay(merged, adminObj);
+}
+
+async function applyOnboardingPlatformModeIfNeeded(appName, merged) {
+  if (appName !== 'miso-controller') {
+    return;
+  }
+  const mode = await config.getSetupPlatformMode();
+  merged.ONBOARDING_FULL_PLATFORM = mode === 'full' ? 'true' : 'false';
+}
 
 /**
  * Backfill only secrets needed for `aifabrix run <app>`: kv:// keys from that app's env.template
@@ -194,31 +213,72 @@ async function readPasswordFromPgpassFile(pgpassPath) {
 }
 
 /**
- * Read POSTGRES_PASSWORD from `pgpass` next to the active infra compose (same as `resolveInfraStatePaths()`).
- * Does not use `getAifabrixHome()` alone, so a stale pgpass under the wrong base directory (e.g. when
- * `aifabrix-home` points at $HOME but compose lives under the config dir) cannot override admin-secrets.
+ * Read POSTGRES_PASSWORD from pgpass-style files beside the active infra compose
+ * (`resolveInfraStatePaths()`). Tries legacy `pgpass`, then `.pgpass.bootstrap` written at `up-infra`
+ * so db-init matches the password Postgres was started with when admin-secrets later drifted.
  * @param {number|string} developerId - Developer ID
  * @returns {Promise<string|undefined>} Password or undefined
  */
 async function readPostgresPasswordFromPgpass(developerId) {
-  const { resolveInfraStatePaths } = require('../infrastructure/helpers');
+  const { resolveInfraStatePaths, PGPASS_BOOTSTRAP_BASENAME } = require('../infrastructure/helpers');
   const { infraDir } = resolveInfraStatePaths(developerId);
-  const pgpassPath = path.join(infraDir, 'pgpass');
-  if (!fsSync.existsSync(pgpassPath)) {
-    return undefined;
-  }
-  try {
-    const pwd = await readPasswordFromPgpassFile(pgpassPath);
-    return pwd;
-  } catch {
-    return undefined;
+  const candidates = ['pgpass', PGPASS_BOOTSTRAP_BASENAME];
+  for (const name of candidates) {
+    const pgpassPath = path.join(infraDir, name);
+    if (!fsSync.existsSync(pgpassPath)) {
+      continue;
+    }
+    try {
+      const pwd = await readPasswordFromPgpassFile(pgpassPath);
+      if (pwd !== undefined && pwd !== '') {
+        return pwd;
+      }
+    } catch {
+      // try next candidate
+    }
   }
+  return undefined;
+}
+
+/**
+ * @returns {Function}
+ */
+function resolveEnsureAdminSecretsFn() {
+  const infra = require('../infrastructure');
+  return typeof infra.ensureAdminSecrets === 'function'
+    ? infra.ensureAdminSecrets
+    : require('../infrastructure/helpers').ensureAdminSecrets;
+}
+
+/**
+ * @param {Object} merged
+ * @param {number|string|undefined} developerId
+ * @returns {Promise<void>}
+ */
+async function applyPostgresPasswordFromPgpass(merged, developerId) {
+  if (developerId === undefined) return;
+  const pgpassPwd = await readPostgresPasswordFromPgpass(developerId);
+  if (pgpassPwd !== undefined) merged.POSTGRES_PASSWORD = pgpassPwd;
+}
+
+/**
+ * @param {string} runEnvPath
+ * @param {string} runEnvAdminPath
+ * @param {Object} appOnly
+ * @param {Object} dbInitOnly
+ * @returns {Promise<void>}
+ */
+async function writeRunEnvFiles(runEnvPath, runEnvAdminPath, appOnly, dbInitOnly) {
+  const toContent = adminSecrets.envObjectToContent;
+  await fs.writeFile(runEnvPath, toContent(appOnly), { mode: 0o600 });
+  await fs.writeFile(runEnvAdminPath, toContent(dbInitOnly), { mode: 0o600 });
 }
 
 /**
  * Build two run env files: .env.run (app-only, no admin secrets) and .env.run.admin (start-only, for db-init).
  * Admin password is never set in the app container; .env.run.admin is used only for start and then deleted.
- * When `pgpass` exists beside the active infra compose, POSTGRES_PASSWORD is taken from it so db-init matches Postgres.
+ * When `pgpass` or `.pgpass.bootstrap` exists beside the active infra compose, POSTGRES_PASSWORD is taken
+ * from it so db-init matches Postgres.
  * @async
  * @param {string} appName - Application name
  * @param {Object} appConfig - Application configuration
@@ -227,12 +287,8 @@ async function readPostgresPasswordFromPgpass(developerId) {
  * @returns {Promise<{ runEnvPath: string, runEnvAdminPath: string }>} Paths to .env.run and .env.run.admin
  */
 async function buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId, scopeOpts = null) {
-  const infra = require('../infrastructure');
-  const ensureAdminSecretsFn = typeof infra.ensureAdminSecrets === 'function'
-    ? infra.ensureAdminSecrets
-    : require('../infrastructure/helpers').ensureAdminSecrets;
   await ensureRunSecretsForApp(appName);
-  await ensureAdminSecretsFn();
+  await resolveEnsureAdminSecretsFn()();
   const adminObj = await adminSecrets.readAndDecryptAdminSecrets();
   const runEnvKey = scopeOpts && scopeOpts.runEnvKey ? String(scopeOpts.runEnvKey).toLowerCase() : 'dev';
   const appObj = await secretsEnvWrite.resolveAndGetEnvMap(appName, {
@@ -242,22 +298,20 @@ async function buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId
     runEnvKey
   });
   const merged = { ...adminObj, ...appObj };
-  if (developerId !== undefined) {
-    const pgpassPwd = await readPostgresPasswordFromPgpass(developerId);
-    if (pgpassPwd !== undefined) merged.POSTGRES_PASSWORD = pgpassPwd;
-  }
+  mergeRunEnvWithAdminOverlay(merged, adminObj);
+  await applyOnboardingPlatformModeIfNeeded(appName, merged);
+  await applyPostgresPasswordFromPgpass(merged, developerId);
   injectDatabaseNamesAndUsers(merged, appConfig, scopeOpts);
   injectContainerPortForRun(merged, appConfig, appName);
 
   const runEnvPath = path.join(devDir, '.env.run');
   const runEnvAdminPath = path.join(devDir, '.env.run.admin');
-
-  const appOnly = buildAppOnlyEnv(merged);
-  const dbInitOnly = buildDbInitOnlyEnv(merged);
-
-  await fs.writeFile(runEnvPath, adminSecrets.envObjectToContent(appOnly), { mode: 0o600 });
-  await fs.writeFile(runEnvAdminPath, adminSecrets.envObjectToContent(dbInitOnly), { mode: 0o600 });
-
+  await writeRunEnvFiles(
+    runEnvPath,
+    runEnvAdminPath,
+    buildAppOnlyEnv(merged),
+    buildDbInitOnlyEnv(merged)
+  );
   return { runEnvPath, runEnvAdminPath };
 }
 

package/lib/app/run-resolve-image.js

@@ -10,6 +10,7 @@ const config = require('../core/config');
 const { resolveDockerImageRef } = require('../utils/resolve-docker-image-ref');
 const { checkImageExists } = require('../utils/app-run-containers');
 const { buildDevImageRepositoryPath } = require('../utils/image-name');
+const { wantsLocalDockerImageDiscovery } = require('../utils/build-resolve-image');
 
 /**
  * @param {string} appName
@@ -41,7 +42,7 @@ async function resolveRunImageWithLocalFallback(appName, appConfig, runOptions =
 
   const baseRef = resolveDockerImageRef(appName, appConfig, opts);
 
-  if (opts.base === true) {
+  if (opts.base === true || !wantsLocalDockerImageDiscovery(appConfig)) {
     return baseRef;
   }
 

package/lib/app/run-stop-containers.js

@@ -0,0 +1,113 @@
+/**
+ * Stop running app containers (and celery companions) before `aifabrix run`.
+ *
+ * @fileoverview Pre-run container teardown for port reuse
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const containerHelpers = require('../utils/app-run-containers');
+const helpers = require('./run-helpers');
+const { computeEffectiveEnvironmentScopedResources } = require('../utils/environment-scoped-resources');
+const { getCeleryCompanionAppKeys } = require('../utils/celery-companion-apps');
+
+/**
+ * @param {Object} appConfig
+ * @param {Object} options
+ * @returns {Promise<{ effectiveEnvironmentScopedResources: true, env: string }|null>}
+ */
+async function resolveRunScopeOpts(appConfig, options) {
+  const runEnvKey = (options.env || 'dev').toLowerCase();
+  const userCfg = await config.getConfig();
+  const effectiveEnvironmentScopedResources = computeEffectiveEnvironmentScopedResources(
+    Boolean(userCfg.useEnvironmentScopedResources),
+    appConfig.environmentScopedResources === true,
+    runEnvKey
+  );
+  if (!effectiveEnvironmentScopedResources) {
+    return null;
+  }
+  return { effectiveEnvironmentScopedResources: true, env: runEnvKey };
+}
+
+/**
+ * @param {string[]} companionKeys
+ * @param {string|number} developerId
+ * @param {boolean} debug
+ * @param {Object|null} scopeOpts
+ * @returns {Promise<string[]>}
+ */
+async function findRunningCompanionKeys(companionKeys, developerId, debug, scopeOpts) {
+  const running = [];
+  for (const companionKey of companionKeys) {
+    if (await helpers.checkContainerRunning(companionKey, developerId, debug, scopeOpts)) {
+      running.push(companionKey);
+    }
+  }
+  return running;
+}
+
+/**
+ * @param {string[]} companionKeys
+ * @param {string|number} developerId
+ * @param {boolean} debug
+ * @param {Object|null} scopeOpts
+ * @returns {Promise<void>}
+ */
+async function stopCompanionContainers(companionKeys, developerId, debug, scopeOpts) {
+  for (const companionKey of companionKeys) {
+    const companionName = containerHelpers.getContainerName(companionKey, developerId, scopeOpts);
+    logger.log(formatWarningLine(`Stopping companion container ${companionName}`));
+    await helpers.stopAndRemoveContainer(companionKey, developerId, debug, scopeOpts);
+  }
+}
+
+/**
+ * Check if container is running and stop it (and celery companions) if needed.
+ *
+ * @async
+ * @param {string} appName
+ * @param {Object} appConfig
+ * @param {Object} options
+ * @param {boolean} debug
+ * @returns {Promise<void>}
+ */
+async function checkAndStopContainer(appName, appConfig, options, debug) {
+  const developerId = appConfig.developerId;
+  const scopeOpts = await resolveRunScopeOpts(appConfig, options);
+  const companionKeys = getCeleryCompanionAppKeys(appName, appConfig);
+  const companionsToStop = await findRunningCompanionKeys(
+    companionKeys,
+    developerId,
+    debug,
+    scopeOpts
+  );
+  const containerRunning = await helpers.checkContainerRunning(
+    appName,
+    developerId,
+    debug,
+    scopeOpts
+  );
+  if (!containerRunning && companionsToStop.length === 0) {
+    return;
+  }
+  await stopCompanionContainers(companionsToStop, developerId, debug, scopeOpts);
+  if (!containerRunning) {
+    return;
+  }
+  const containerName = containerHelpers.getContainerName(appName, developerId, scopeOpts);
+  logger.log(formatWarningLine(`Container ${containerName} is already running`));
+  await helpers.stopAndRemoveContainer(appName, developerId, debug, scopeOpts);
+}
+
+module.exports = {
+  checkAndStopContainer,
+  resolveRunScopeOpts,
+  findRunningCompanionKeys,
+  stopCompanionContainers
+};

package/lib/app/run.js

@@ -27,6 +27,7 @@ const containerHelpers = require('../utils/app-run-containers');
 const helpers = require('./run-helpers');
 const { ensureReloadSync, logReloadDevSummary } = require('./run-reload-sync');
 const { logRestartDevMountSummary } = require('./restart-display');
+const { checkAndStopContainer } = require('./run-stop-containers');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { isRunCliNoProxy } = require('../utils/run-cli-flags');
 
@@ -111,37 +112,6 @@ async function validateAppForRun(appName, _debug) {
   return true;
 }
 
-/**
- * Check if container is running and stop it if needed
- * @async
- * @param {string} appName - Application name
- * @param {number|string} developerId - Developer ID
- * @param {boolean} debug - Debug flag
- * @returns {Promise<void>}
- */
-async function checkAndStopContainer(appName, appConfig, options, debug) {
-  const developerId = appConfig.developerId;
-  const runEnvKey = (options.env || 'dev').toLowerCase();
-  const userCfg = await config.getConfig();
-  const { computeEffectiveEnvironmentScopedResources } = require('../utils/environment-scoped-resources');
-  const effectiveEnvironmentScopedResources = computeEffectiveEnvironmentScopedResources(
-    Boolean(userCfg.useEnvironmentScopedResources),
-    appConfig.environmentScopedResources === true,
-    runEnvKey
-  );
-  const scopeOpts = effectiveEnvironmentScopedResources
-    ? { effectiveEnvironmentScopedResources: true, env: runEnvKey }
-    : null;
-  const containerRunning = await helpers.checkContainerRunning(appName, developerId, debug, scopeOpts);
-  if (!containerRunning) {
-    return;
-  }
-
-  const containerName = containerHelpers.getContainerName(appName, developerId, scopeOpts);
-  logger.log(formatWarningLine(`Container ${containerName} is already running`));
-  await helpers.stopAndRemoveContainer(appName, developerId, debug, scopeOpts);
-}
-
 /**
  * Calculate host port and validate it's available
  * @async

package/lib/app/show-display.js

@@ -49,6 +49,40 @@ function logApplicationOptional(a) {
   });
 }
 
+function localRunProfileDiffers(application, localRunProfile) {
+  if (!localRunProfile || !application) return false;
+  if (localRunProfile.url && localRunProfile.url !== application.url) return true;
+  if (localRunProfile.internalUrl && localRunProfile.internalUrl !== application.internalUrl) {
+    return true;
+  }
+  return (
+    localRunProfile.port !== undefined &&
+    localRunProfile.port !== null &&
+    localRunProfile.port !== application.port
+  );
+}
+
+function logLocalRunProfileSection(summary) {
+  const local = summary.localRunProfile;
+  if (!local || summary.source !== 'online' || !localRunProfileDiffers(summary.application, local)) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.gray('  Local run profile (docker manifest url://):'));
+  if (local.url && local.url !== summary.application.url) {
+    logger.log(chalk.gray(`    URL:           ${local.url}`));
+  }
+  if (local.internalUrl && local.internalUrl !== summary.application.internalUrl) {
+    logger.log(chalk.gray(`    Internal URL:  ${local.internalUrl}`));
+  }
+  if (local.port !== undefined && local.port !== summary.application.port) {
+    logger.log(chalk.gray(`    Port:          ${local.port}`));
+  }
+  logger.log(
+    chalk.gray('    Controller registry values above are what identity sync and pipeline use.')
+  );
+}
+
 function logApplicationFields(a) {
   logApplicationRequired(a);
   logApplicationOptional(a);
@@ -96,6 +130,7 @@ function logApplicationSection(a, summary) {
   } else {
     logApplicationFields(a);
   }
+  logLocalRunProfileSection(summary);
   if (summary.runReloadDefault && !summary.isExternal) {
     logger.log(`  ${'Run default:'.padEnd(16)} reload on (config)`);
   }

package/lib/app/show.js

@@ -54,10 +54,22 @@ function attachRunDefaultsFromUserConfig(summary, appKey, userCfg) {
 
 /**
  * Overlay `application.url` / `application.internalUrl` from declarative url:// rules (same profile as run `.env`, default `docker`).
- * Used for offline and **online** show so controller metadata does not stale local proxy/TLS hints.
+ * Offline: replaces URL fields for local run hints. Online: keeps controller registry on `application` and adds `localRunProfile` when it differs.
  * @param {Object} summary
  * @param {string} appKey
  */
+function portFromShowUrl(url) {
+  if (!url || typeof url !== 'string') return undefined;
+  try {
+    const parsed = new URL(url);
+    if (!parsed.port) return undefined;
+    const port = Number(parsed.port);
+    return Number.isFinite(port) ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 async function attachDeclarativeUrlsToShowApplication(summary, appKey) {
   if (!summary || summary.isExternal) return;
   const t = summary.application && summary.application.type;
@@ -68,8 +80,24 @@ async function attachDeclarativeUrlsToShowApplication(summary, appKey) {
     const variablesPath = resolveApplicationConfigPath(appPath);
     const urls = await resolveDeclarativeShowUrlsForApp(appKey, appPath, variablesPath, 'docker');
     if (!urls) return;
+
+    const localPort = portFromShowUrl(urls.publicUrl);
+    const localRunProfile = {
+      url: urls.publicUrl,
+      internalUrl: urls.internalUrl,
+      port: localPort ?? summary.application.port
+    };
+
+    if (summary.source === 'online') {
+      summary.localRunProfile = localRunProfile;
+      return;
+    }
+
     summary.application.url = urls.publicUrl;
     summary.application.internalUrl = urls.internalUrl;
+    if (localPort !== undefined) {
+      summary.application.port = localPort;
+    }
   } catch {
     /* display-only */
   }
@@ -830,6 +858,9 @@ function outputOnlineJson(summary, permissionsOnly, manifestSource) {
     out.runReloadDefault = true;
   }
   out.runProxyDefault = Boolean(summary.runProxyDefault);
+  if (summary.localRunProfile) {
+    out.localRunProfile = summary.localRunProfile;
+  }
   if (summary.externalSystem !== undefined && summary.externalSystem !== null) {
     out.externalSystem = summary.externalSystem && summary.externalSystem.error
       ? { error: summary.externalSystem.error }