@aifabrix/builder 2.44.6 → 2.45.0

package/lib/core/config-normalize.js

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

package/lib/core/config-registered-controller-urls.js

@@ -0,0 +1,54 @@
+/**
+ * Derive controller URLs stored in config (default + device token keys).
+ *
+ * @fileoverview Registered controller URL list for auth --set-controller pick mode
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/**
+ * Build sorted unique controller URLs from a config object.
+ * @param {Object} cfg - Parsed config.yaml object
+ * @param {(url: string) => string} normalizeControllerUrl - normalizer from config module
+ * @returns {string[]}
+ */
+function buildRegisteredControllerUrlList(cfg, normalizeControllerUrl) {
+  const seen = new Set();
+  const add = (raw) => {
+    if (!raw || typeof raw !== 'string') return;
+    const trimmed = raw.trim();
+    if (!/^https?:\/\//i.test(trimmed)) return;
+    let parsed;
+    try {
+      parsed = new URL(trimmed);
+    } catch {
+      return;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
+    seen.add(normalizeControllerUrl(trimmed));
+  };
+  if (cfg.controller) {
+    add(cfg.controller);
+  }
+  for (const key of Object.keys(cfg.device || {})) {
+    add(key);
+  }
+  return [...seen].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @param {() => Promise<Object>} getConfig - async config loader
+ * @param {(url: string) => string} normalizeControllerUrl
+ * @returns {Promise<string[]>}
+ */
+async function getRegisteredControllerUrlsWithLoader(getConfig, normalizeControllerUrl) {
+  const cfg = await getConfig();
+  return buildRegisteredControllerUrlList(cfg, normalizeControllerUrl);
+}
+
+module.exports = {
+  buildRegisteredControllerUrlList,
+  getRegisteredControllerUrlsWithLoader
+};

package/lib/core/config.js

@@ -15,62 +15,15 @@ const os = require('os');
 const { encryptToken, decryptToken, isTokenEncrypted } = require('../utils/token-encryption');
 const { ensureSecureFilePermissions, ensureSecureDirPermissions } = require('../utils/secure-file-permissions');
 const { getRuntimeConfigDir, getRuntimeConfigFile } = require('./config-runtime-paths');
+const { getAdminEmailFromConfig, setAdminEmailInConfig } = require('./config-admin-email');
+const { getRegisteredControllerUrlsWithLoader } = require('./config-registered-controller-urls');
+const { normalizeControllerUrl, validateAndNormalizeDeveloperId } = require('./config-normalize');
 // Avoid importing paths.js here to prevent circular dependency; use shared runtime config dir helper.
 // Config location: AIFABRIX_CONFIG dirname → AIFABRIX_HOME (with ~/.aifabrix fallback when config lives there) → ~/.aifabrix
 
 // Cache for developer ID - loaded when getConfig() is first called
 let cachedDeveloperId = null;
 
-/**
- * Normalize controller URL for consistent storage and lookup
- * Removes trailing slashes and normalizes the URL format
- * @param {string} url - Controller URL to normalize
- * @returns {string} Normalized controller URL
- */
-function normalizeControllerUrl(url) {
-  if (!url || typeof url !== 'string') {
-    return url;
-  }
-  // Remove trailing slashes
-  let normalized = url.trim().replace(/\/+$/, '');
-  // Ensure it starts with http:// or https://
-  if (!normalized.match(/^https?:\/\//)) {
-    // If it doesn't start with protocol, assume http://
-    normalized = `http://${normalized}`;
-  }
-  return normalized;
-}
-
-/**
- * Validate and normalize developer ID
- * @param {*} developerId - Developer ID value (can be string, number, undefined, or null)
- * @returns {string} Normalized developer ID as string
- * @throws {Error} If developer ID is invalid
- */
-function validateAndNormalizeDeveloperId(developerId) {
-  const DEV_ID_DIGITS_REGEX = /^[0-9]+$/;
-
-  if (typeof developerId === 'undefined' || developerId === null) {
-    return '0';
-  }
-
-  if (typeof developerId === 'number') {
-    if (developerId < 0 || !Number.isFinite(developerId)) {
-      throw new Error('Developer ID must be a non-negative digit string or number');
-    }
-    return String(developerId);
-  }
-
-  if (typeof developerId === 'string') {
-    if (!DEV_ID_DIGITS_REGEX.test(developerId)) {
-      throw new Error('Developer ID must be a non-negative digit string or number');
-    }
-    return developerId;
-  }
-
-  throw new Error('Developer ID must be a non-negative digit string or number');
-}
-
 /**
  * Ensure default config values exist
  * @param {Object} config - Configuration object
@@ -258,6 +211,25 @@ async function getTlsEnabled() {
   return cfg.tlsEnabled === true;
 }
 
+/**
+ * Admin email stored in `config.yaml` by `aifabrix setup` (Keycloak / pgAdmin). Empty when unset.
+ *
+ * @returns {Promise<string>}
+ */
+async function getAdminEmail() {
+  return getAdminEmailFromConfig(getConfig);
+}
+
+/**
+ * Persist admin email to `config.yaml` (used on subsequent setup runs as the prompt default).
+ *
+ * @param {string} email
+ * @returns {Promise<void>}
+ */
+async function setAdminEmail(email) {
+  return setAdminEmailInConfig(getConfig, saveConfig, email);
+}
+
 /**
  * Whether Traefik is enabled (`traefik: true` in config; infra compose includes the proxy).
  * @returns {Promise<boolean>}
@@ -316,6 +288,14 @@ async function getControllerUrl() {
   return config.controller || null;
 }
 
+/**
+ * Controller URLs from config: `controller` plus `device` token keys.
+ * @returns {Promise<string[]>}
+ */
+async function getRegisteredControllerUrls() {
+  return getRegisteredControllerUrlsWithLoader(getConfig, normalizeControllerUrl);
+}
+
 function isTokenExpired(expiresAt) {
   if (!expiresAt) return true;
   const expirationTime = new Date(expiresAt).getTime();
@@ -454,6 +434,8 @@ const exportsObj = {
   loadDeveloperId,
   getCurrentEnvironment,
   getTlsEnabled,
+  getAdminEmail,
+  setAdminEmail,
   getTraefikEnabled,
   setCurrentEnvironment,
   resolveEnvironment,
@@ -469,6 +451,7 @@ const exportsObj = {
   normalizeControllerUrl,
   setControllerUrl,
   getControllerUrl,
+  getRegisteredControllerUrls,
   get CONFIG_DIR() {
     return getRuntimeConfigDir();
   },

package/lib/core/secrets-ensure-infra.js

@@ -71,7 +71,7 @@ function getInfraSecretKeysForUpInfra() {
 }
 
 /**
- * Same merge as runtime `loadSecrets()` (user local + project path + remote shared API + defaults).
+ * Same merge as runtime `loadSecrets()` (primary `~/.aifabrix/secrets.local.yaml` plus `aifabrix-secrets` file or remote API).
  * Ensures missing-key checks treat remote `--shared` keys as already satisfied.
  *
  * @returns {Promise<Object.<string, string>>}

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

@@ -37,8 +37,7 @@ const pathsUtil = require('../utils/paths');
 const { readAppEnvironmentScopedFlagForAppPath } = require('../utils/app-scoped-config');
 const { computeEffectiveEnvironmentScopedResources, redisDbIndexForScopedRunEnv } = require('../utils/environment-scoped-resources');
 const { applyRedisDbIndexToEnvContent } = require('../utils/redis-env-scope');
-const { expandDeclarativeUrlsInEnvContent } = require('../utils/url-declarative-resolve');
-const { rewriteInactiveDeclarativeVdirPublicContent } = require('../utils/url-declarative-vdir-inactive-env');
+const { expandDeclarativeUrlsIfPresent } = require('./secrets-env-declarative-expand');
 const {
   mergeDockerManifestPublishedPort,
   rewriteDockerManifestPublicPortEnvLine
@@ -127,76 +126,6 @@ async function getDockerRedisDbEndpoints() {
   return { redisHost, redisPort, dbHost, dbPort };
 }
 
-/**
- * Config inputs for declarative url:// expansion (keeps expandDeclarativeUrlsIfPresent small).
- * @param {string} appPath
- * @returns {Promise<Object>}
- */
-async function loadDeclarativeUrlExpandInputs(appPath) {
-  const userCfg = await config.getConfig();
-  let remoteServer = null;
-  try {
-    const rs = await config.getRemoteServer();
-    if (rs && String(rs).trim()) {
-      remoteServer = String(rs).trim();
-    }
-  } catch {
-    remoteServer = null;
-  }
-  let developerIdRaw = null;
-  try {
-    developerIdRaw = await config.getDeveloperId();
-  } catch {
-    developerIdRaw = null;
-  }
-  let infraTlsEnabled = false;
-  try {
-    infraTlsEnabled = await config.getTlsEnabled();
-  } catch {
-    infraTlsEnabled = false;
-  }
-  return {
-    userCfg,
-    remoteServer,
-    developerIdRaw,
-    infraTlsEnabled,
-    appScopedFlag: readAppEnvironmentScopedFlagForAppPath(appPath)
-  };
-}
-
-/**
- * After kv:// resolution, expand url:// references when application config exists.
- * @param {string} resolved
- * @param {string} appName
- * @param {string} appPath
- * @param {string|null} variablesPath
- * @param {string} environment
- * @param {boolean} envOnly
- * @returns {Promise<string>}
- */
-async function expandDeclarativeUrlsIfPresent(resolved, appName, appPath, variablesPath, environment, envOnly) {
-  if (envOnly || !variablesPath) {
-    return resolved;
-  }
-  const { userCfg, remoteServer, developerIdRaw, infraTlsEnabled, appScopedFlag } =
-    await loadDeclarativeUrlExpandInputs(appPath);
-  resolved = rewriteInactiveDeclarativeVdirPublicContent(resolved, variablesPath, userCfg);
-  if (!resolved.includes('url://')) {
-    return resolved;
-  }
-  return expandDeclarativeUrlsInEnvContent(resolved, {
-    profile: environment === 'docker' ? 'docker' : 'local',
-    currentAppKey: appName,
-    variablesPath,
-    useEnvironmentScopedResources: Boolean(userCfg.useEnvironmentScopedResources),
-    appEnvironmentScopedResources: appScopedFlag,
-    remoteServer,
-    developerIdRaw,
-    traefik: Boolean(userCfg.traefik),
-    infraTlsEnabled
-  });
-}
-
 /** Docker env transformations: ports, infra endpoints, PORT. */
 async function applyDockerTransformations(resolved, variablesPath) {
   resolved = await resolveServicePortsInEnvContent(resolved, 'docker');
@@ -337,17 +266,17 @@ function mergeEnvContentPreservingExisting(newContent, existingMap) {
 /**
  * Merges a key-value map into existing .env file content, preserving comments and blank lines.
  * For each KEY=value line in existing content, replaces value with newMap[KEY] when the key exists
- * in newMap. Appends any keys from newMap that did not appear in the file.
+ * in newMap. By default appends keys from newMap that did not appear in the file; set
+ * `appendMissingFromNewMap: false` to only update keys already present (e.g. `--reload` into a
+ * resolve-generated file so run-only keys like DB_0_NAME are not tacked on the end).
  *
  * @param {string} existingContent - Full existing .env file content
  * @param {Object.<string, string>} newMap - New key-to-value map (e.g. from resolved or run env)
+ * @param {Object} [options] - Merge options
+ * @param {boolean} [options.appendMissingFromNewMap=true] - When false, do not append keys only in newMap
  * @returns {string} Merged content with comments preserved
  */
-function mergeEnvMapIntoContent(existingContent, newMap) {
-  if (!newMap || Object.keys(newMap).length === 0) {
-    return typeof existingContent === 'string' ? existingContent : '';
-  }
-  const lines = (existingContent || '').split(/\r?\n/);
+function collectSeenKeysAndMergeEnvLines(lines, newMap) {
   const seen = new Set();
   const out = [];
   for (const line of lines) {
@@ -365,8 +294,26 @@ function mergeEnvMapIntoContent(existingContent, newMap) {
     }
     out.push(line);
   }
+  return { out, seen };
+}
+
+function appendMissingEnvKeysFromMap(out, seen, newMap) {
   for (const key of Object.keys(newMap)) {
-    if (!seen.has(key)) out.push(`${key}=${newMap[key]}`);
+    if (!seen.has(key)) {
+      out.push(`${key}=${newMap[key]}`);
+    }
+  }
+}
+
+function mergeEnvMapIntoContent(existingContent, newMap, options = {}) {
+  if (!newMap || Object.keys(newMap).length === 0) {
+    return typeof existingContent === 'string' ? existingContent : '';
+  }
+  const appendMissing = options.appendMissingFromNewMap !== false;
+  const lines = (existingContent || '').split(/\r?\n/);
+  const { out, seen } = collectSeenKeysAndMergeEnvLines(lines, newMap);
+  if (appendMissing) {
+    appendMissingEnvKeysFromMap(out, seen, newMap);
   }
   return out.join('\n');
 }
@@ -386,19 +333,72 @@ function resolveEnvContentToWrite(resolved, pathToPreserve) {
 
 /**
  * Generates and writes .env file. Newly resolved values win over existing .env; extra vars in existing .env are kept.
- * When options.envOnly is true, only env.template is used; .env is written to options.appPath.
+ * When `options.envOnly` is true, only env.template is used; .env is written to `options.appPath`.
+ *
+ * When `options.noWrite` is true, the function resolves the .env content in memory and skips
+ * both writes — neither `<appPath>/.env` nor `build.envOutputPath` is materialized — and returns
+ * `null`. Use this from non-resolve flows (register/rotate-secret/build/up-*) so resolved secrets
+ * never land on disk except when the user runs `aifabrix resolve <app>` explicitly.
+ *
  * @async
  * @param {string} appName - Name of the application
  * @param {string} [secretsPath] - Path to secrets file (optional)
  * @param {string} [environment='local'] - Environment context ('local' or 'docker')
  * @param {boolean} [force=false] - Generate missing secret keys in secrets file
- * @param {Object} [options] - Optional: appPath, envOnly, skipOutputPath, preserveFromPath
- * @returns {Promise<string>} Path to generated .env file
+ * @param {Object} [options] - Optional: appPath, envOnly, skipOutputPath, preserveFromPath, noWrite,
+ *   preferLocalEnvOutputPath (when **true**, `build.envOutputPath` is regenerated with **local** `url://` profile; **false**
+ *   only when **both** `remote-server` is set and `applications.<app>.reload` is true — then docker flavor matches `builder/<app>/.env`)
+ * @param {boolean} [options.noWrite=false] - When true, resolve in-memory only; do not write
+ *   `<appPath>/.env` and do not call `processEnvVariables`. Returns `null` in that case.
+ * @returns {Promise<string|null>} Path to generated .env file, or `null` when `noWrite` is true
+ *
+ * @example
+ * // up-platform / up-miso / up-dataplane / register / rotate-secret / build flows:
+ * await generateEnvFile('dataplane', null, 'local', false, { noWrite: true });
+ *
+ * @example
+ * // aifabrix resolve <app> — the only legitimate writer of a persistent .env:
+ * await generateEnvFile('dataplane', undefined, 'docker', force, {
+ *   appPath, envOnly, skipOutputPath: false, preserveFromPath: null
+ * });
  */
+/**
+ * Materialize a resolved .env to `<appPath>/.env` and (optionally) copy through
+ * `build.envOutputPath`. Extracted so {@link generateEnvFile} can stay under the
+ * 20-statement limit while still expressing the in-memory vs on-disk branch clearly.
+ *
+ * @async
+ * @param {Object} params
+ * @param {string} params.appName
+ * @param {string} params.appPath
+ * @param {string} params.envPath - Resolved `<appPath>/.env` target
+ * @param {string} params.resolved - Fully resolved .env content
+ * @param {string|null} params.variablesPath - application.yaml path (or null when envOnly)
+ * @param {string} [params.secretsPath]
+ * @param {Object} params.opts - Caller options (preserveFromPath, skipOutputPath, preferLocalEnvOutputPath, appPath)
+ * @returns {Promise<string>} Path to the written .env file
+ */
+async function writeResolvedEnv({ appName, envPath, resolved, variablesPath, secretsPath, opts }) {
+  const preservePath = opts.preserveFromPath !== undefined && opts.preserveFromPath !== null ? opts.preserveFromPath : null;
+  const pathToPreserve = preservePath !== null ? preservePath : envPath;
+  const toWrite = resolveEnvContentToWrite(resolved, pathToPreserve);
+  fs.writeFileSync(envPath, toWrite, { mode: 0o600 });
+
+  if (!opts.skipOutputPath) {
+    const { processEnvVariables } = require('../utils/env-copy');
+    await processEnvVariables(envPath, variablesPath, appName, secretsPath, {
+      preferLocalEnvOutputPath: opts.preferLocalEnvOutputPath === true,
+      appPath: opts.appPath || null
+    });
+  }
+  return envPath;
+}
+
 async function generateEnvFile(appName, secretsPath, environment = 'local', force = false, options = {}) {
   const opts = options && typeof options === 'object' ? options : {};
   const appPath = opts.appPath || pathsUtil.getBuilderPath(appName);
   const envOnly = !!opts.envOnly;
+  const noWrite = opts.noWrite === true;
   const variablesPath = envOnly ? null : resolveApplicationConfigPath(appPath);
   const envPath = path.join(appPath, '.env');
 
@@ -409,18 +409,14 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
     }
   }
 
+  // Always resolve so missing-secret / kv:// errors still surface in noWrite mode.
   const resolved = await generateEnvContent(appName, secretsPath, environment, force, { appPath, envOnly });
-  const preservePath = opts.preserveFromPath !== undefined && opts.preserveFromPath !== null ? opts.preserveFromPath : null;
-  const pathToPreserve = preservePath !== null ? preservePath : envPath;
-  const toWrite = resolveEnvContentToWrite(resolved, pathToPreserve);
-  fs.writeFileSync(envPath, toWrite, { mode: 0o600 });
 
-  if (!opts.skipOutputPath) {
-    const { processEnvVariables } = require('../utils/env-copy');
-    await processEnvVariables(envPath, variablesPath, appName, secretsPath);
+  if (noWrite) {
+    return null;
   }
 
-  return envPath;
+  return writeResolvedEnv({ appName, appPath, envPath, resolved, variablesPath, secretsPath, opts });
 }
 
 module.exports = {

package/lib/core/secrets-env-declarative-expand.js

@@ -0,0 +1,170 @@
+/**
+ * Declarative url:// expansion after kv:// (keeps secrets-env-content under max-lines).
+ *
+ * @fileoverview Declarative url:// expansion after kv://; shared ctx builder; show URL helper
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('./config');
+const pathsUtil = require('../utils/paths');
+const { readAppEnvironmentScopedFlagForAppPath } = require('../utils/app-scoped-config');
+const { expandDeclarativeUrlsInEnvContent } = require('../utils/url-declarative-resolve');
+const { rewriteInactiveDeclarativeVdirPublicContent } = require('../utils/url-declarative-vdir-inactive-env');
+const { refreshUrlsLocalRegistryFromBuilder } = require('../utils/urls-local-registry');
+/**
+ * Config inputs for declarative url:// expansion.
+ * @param {string} appPath
+ * @returns {Promise<Object>}
+ */
+async function loadDeclarativeUrlExpandInputs(appPath) {
+  const userCfg = await config.getConfig();
+  let remoteServer = null;
+  try {
+    const rs = await config.getRemoteServer();
+    if (rs && String(rs).trim()) {
+      remoteServer = String(rs).trim();
+    }
+  } catch {
+    remoteServer = null;
+  }
+  let developerIdRaw = null;
+  try {
+    developerIdRaw = await config.getDeveloperId();
+  } catch {
+    developerIdRaw = null;
+  }
+  let infraTlsEnabled = false;
+  try {
+    infraTlsEnabled = await config.getTlsEnabled();
+  } catch {
+    infraTlsEnabled = false;
+  }
+  return {
+    userCfg,
+    remoteServer,
+    developerIdRaw,
+    infraTlsEnabled,
+    appScopedFlag: readAppEnvironmentScopedFlagForAppPath(appPath)
+  };
+}
+
+/**
+ * Build ctx for {@link expandDeclarativeUrlsInEnvContent} from preloaded inputs.
+ * @param {string} appName
+ * @param {string|null|undefined} variablesPath
+ * @param {string} environment
+ * @param {Object} inputs - Result of {@link loadDeclarativeUrlExpandInputs}
+ * @returns {Object}
+ */
+function buildDeclarativeUrlExpandContextFromInputs(appName, variablesPath, environment, inputs) {
+  const { userCfg, remoteServer, developerIdRaw, infraTlsEnabled, appScopedFlag } = inputs;
+  let projectRoot = null;
+  try {
+    const r = pathsUtil.getProjectRoot();
+    if (r && String(r).trim()) {
+      projectRoot = String(r).trim();
+    }
+  } catch {
+    projectRoot = null;
+  }
+  return {
+    profile: environment === 'docker' ? 'docker' : 'local',
+    currentAppKey: appName,
+    variablesPath,
+    useEnvironmentScopedResources: Boolean(userCfg.useEnvironmentScopedResources),
+    appEnvironmentScopedResources: appScopedFlag,
+    remoteServer,
+    developerIdRaw,
+    infraTlsEnabled,
+    userCfg,
+    projectRoot
+  };
+}
+
+/**
+ * Resolve `url://public` and `url://internal` for the app (same rules as run `.env`, default `docker` profile).
+ * @param {string} appKey
+ * @param {string} appPath
+ * @param {string|null|undefined} variablesPath
+ * @param {string} [environment='docker'] - Matches `secrets-env-write` default so `url://internal` uses the same service host + vdir rules as the app `.env` copied for Docker run.
+ * @returns {Promise<{ publicUrl: string, internalUrl: string }|null>}
+ */
+async function resolveDeclarativeShowUrlsForApp(appKey, appPath, variablesPath, environment = 'docker') {
+  if (!variablesPath || !appPath || !appKey) {
+    return null;
+  }
+  const inputs = await loadDeclarativeUrlExpandInputs(appPath);
+  const { parseSimpleEnvMap } = require('../utils/url-declarative-resolve');
+  let content = 'APP_SHOW_PUBLIC=url://public\nAPP_SHOW_INTERNAL=url://internal\n';
+  content = rewriteInactiveDeclarativeVdirPublicContent(content, variablesPath, inputs.userCfg);
+  if (!content.includes('url://')) {
+    return null;
+  }
+  const ctx = buildDeclarativeUrlExpandContextFromInputs(appKey, variablesPath, environment, inputs);
+  const out = await expandDeclarativeUrlsInEnvContent(content, ctx);
+  const m = parseSimpleEnvMap(out);
+  const publicUrl = m.APP_SHOW_PUBLIC;
+  const internalUrl = m.APP_SHOW_INTERNAL;
+  if (
+    !publicUrl ||
+    !internalUrl ||
+    String(publicUrl).includes('url://') ||
+    String(internalUrl).includes('url://')
+  ) {
+    return null;
+  }
+  return { publicUrl: String(publicUrl).trim(), internalUrl: String(internalUrl).trim() };
+}
+
+/**
+ * After kv:// resolution, expand url:// references when application config exists.
+ * Also refreshes {@link refreshUrlsLocalRegistryFromBuilder} whenever `variablesPath` is set so
+ * `urls.local.yaml` picks up `port` / `frontDoorRouting` changes even if `env.template` has no
+ * literal `url://` placeholders (they may already be expanded or absent).
+ * @param {string} resolved
+ * @param {string} appName
+ * @param {string} appPath
+ * @param {string|null} variablesPath
+ * @param {string} environment
+ * @param {boolean} envOnly
+ * @returns {Promise<string>}
+ */
+async function expandDeclarativeUrlsIfPresent(resolved, appName, appPath, variablesPath, environment, envOnly) {
+  if (envOnly || !variablesPath) {
+    return resolved;
+  }
+  const { userCfg, remoteServer, developerIdRaw, infraTlsEnabled, appScopedFlag } =
+    await loadDeclarativeUrlExpandInputs(appPath);
+  resolved = rewriteInactiveDeclarativeVdirPublicContent(resolved, variablesPath, userCfg);
+  const ctx = buildDeclarativeUrlExpandContextFromInputs(appName, variablesPath, environment, {
+    userCfg,
+    remoteServer,
+    developerIdRaw,
+    infraTlsEnabled,
+    appScopedFlag
+  });
+  try {
+    const pr = ctx.projectRoot && String(ctx.projectRoot).trim() ? String(ctx.projectRoot).trim() : '';
+    const registryRoot = pr || pathsUtil.getProjectRoot();
+    if (ctx.excludeCwdBuilderScan === true) {
+      refreshUrlsLocalRegistryFromBuilder(registryRoot, { excludeCwdBuilderScan: true });
+    } else {
+      refreshUrlsLocalRegistryFromBuilder(registryRoot);
+    }
+  } catch {
+    // best-effort: registry refresh must not block .env generation
+  }
+  if (!resolved.includes('url://')) {
+    return resolved;
+  }
+  return expandDeclarativeUrlsInEnvContent(resolved, ctx);
+}
+
+module.exports = {
+  expandDeclarativeUrlsIfPresent,
+  loadDeclarativeUrlExpandInputs,
+  resolveDeclarativeShowUrlsForApp
+};

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

@@ -149,6 +149,8 @@ function parseEnvContentToMap(content) {
  * Resolve .env in memory and write only to envOutputPath or temp (no builder/ or integration/).
  * Injects NPM_TOKEN and PYPI_TOKEN from secrets when missing, then from process.env, then names derived from `BASH_*` keys in the merged secrets store, so shell/install/build match private registry tooling.
  *
+ * **Ephemeral / tooling path:** Used by `app-install`, `app-shell`, and `app-test` to materialize a disposable `.env` (defaults to a temp file under `os.tmpdir()`). This is **not** the same as `aifabrix resolve <app>` (which uses `generateEnvFile` and preserves `build.envOutputPath` / comments). Prefer `aifabrix resolve` when you need a durable repo `.env` for local development.
+ *
  * @async
  * @function resolveAndWriteEnvFile
  * @param {string} appName - Application name