@aifabrix/builder 2.44.6 → 2.45.0

package/lib/utils/url-declarative-resolve-build.js

@@ -8,18 +8,16 @@
 
 'use strict';
 
-const { getRegistryEntryForApp } = require('./urls-local-registry');
+const { getRegistryEntryForApp, readRegistryInternalDockerUseOriginOnly } = require('./urls-local-registry');
 const { DECLARATIVE_URL_INFRA_DEFAULTS } = require('./infra-env-defaults');
 const { getContainerPort, getLocalPort } = require('./port-resolver');
 const pathsUtil = require('./paths');
-const {
-  computePublicUrlBaseString,
-  resolveHostPortForDeclarativePublic
-} = require('./url-declarative-public-base');
-const { computePathActive } = require('./url-declarative-url-flags');
+const { resolveDeclarativeUrlSurfaceState } = require('./url-declarative-resolve-surface-state');
 const { loadApplicationYamlDocForUrlResolve } = require('./url-declarative-resolve-load-doc');
 const { parseUrlToken } = require('./url-declarative-token-parse');
-const runtimeBasePath = require('./url-declarative-runtime-base-path');
+const { readFrontDoorHostTlsFromDoc } = require('./url-declarative-runtime-base-path');
+const buildUrls = require('./url-declarative-resolve-build-urls');
+const expandToken = require('./url-declarative-resolve-expand-token');
 
 /**
  * Plan 122: **Developer subdomain `devNN` + remote hostname is not derived from envKey `tst`.** It comes only from
@@ -41,228 +39,6 @@ function applyTstRemoteDeveloperHostToOrigin(origin) {
   return origin;
 }
 
-/**
- * Join base URL origin with path segments (no duplicate slashes).
- * @param {string} originOrBase - https://host or https://host:port
- * @param {string} suffixPath - /dev/data
- * @returns {string}
- */
-function joinUrlPath(originOrBase, suffixPath) {
-  const base = String(originOrBase || '').replace(/\/+$/, '');
-  let suf = suffixPath || '';
-  if (!suf.startsWith('/')) {
-    suf = `/${suf}`;
-  }
-  return `${base}${suf}`.replace(/([^:]\/)\/+/g, '$1');
-}
-
-/**
- * @param {Object} opts
- * @returns {string}
- */
-function buildPublicUrlString(opts) {
-  const {
-    profile,
-    listenPort,
-    developerIdNum,
-    remoteServer,
-    pathPrefix,
-    patternPath,
-    traefik,
-    hostTemplate,
-    tls,
-    developerIdRaw,
-    infraTlsEnabled,
-    frontDoorIngressActive,
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  } = opts;
-  const base = computePublicUrlBaseString({
-    traefik: Boolean(traefik),
-    pathActive: Boolean(frontDoorIngressActive),
-    hostTemplate: hostTemplate || null,
-    tls: tls !== false,
-    developerIdRaw,
-    remoteServer,
-    profile,
-    listenPort,
-    developerIdNum,
-    infraTlsEnabled: Boolean(infraTlsEnabled),
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  });
-  const patternSegment =
-    frontDoorIngressActive === false
-      ? ''
-      : patternPath === '/' || patternPath === ''
-        ? ''
-        : patternPath;
-  const rawSuffix = `${pathPrefix}${patternSegment}`.replace(/\/{2,}/g, '/');
-  if (!rawSuffix || rawSuffix === '/') {
-    return String(base).replace(/\/+$/, '');
-  }
-  const normalizedSuffix = rawSuffix.startsWith('/') ? rawSuffix : `/${rawSuffix}`;
-  return joinUrlPath(base, normalizedSuffix);
-}
-
-/**
- * Public reachability origin only (no env path prefix, no front-door pattern path).
- * @param {Object} opts
- * @returns {string}
- */
-function buildPublicHostOriginString(opts) {
-  const {
-    profile,
-    listenPort,
-    developerIdNum,
-    remoteServer,
-    traefik,
-    hostTemplate,
-    tls,
-    developerIdRaw,
-    infraTlsEnabled,
-    frontDoorIngressActive,
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  } = opts;
-  const base = computePublicUrlBaseString({
-    traefik: Boolean(traefik),
-    pathActive: Boolean(frontDoorIngressActive),
-    hostTemplate: hostTemplate || null,
-    tls: tls !== false,
-    developerIdRaw,
-    remoteServer,
-    profile,
-    listenPort,
-    developerIdNum,
-    infraTlsEnabled: Boolean(infraTlsEnabled),
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  });
-  try {
-    return new URL(base).origin;
-  } catch {
-    const hostPort = resolveHostPortForDeclarativePublic({
-      profile,
-      listenPort,
-      developerIdNum,
-      declarativeTargetAppKey,
-      declarativeCurrentAppKey
-    });
-    return `http://localhost:${hostPort}`;
-  }
-}
-
-/**
- * Internal service origin only (scheme + host + port), no path suffix.
- * @param {Object} opts
- * @returns {string}
- */
-function buildInternalHostOriginString(opts) {
-  const {
-    profile,
-    listenPort,
-    targetAppKey,
-    remoteServer,
-    pathPrefix,
-    patternPath,
-    developerIdNum,
-    traefik,
-    hostTemplate,
-    tls,
-    developerIdRaw,
-    infraTlsEnabled,
-    frontDoorIngressActive,
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  } = opts;
-  if (profile === 'docker') {
-    return `http://${targetAppKey}:${listenPort}`;
-  }
-  if (remoteServer && String(remoteServer).trim()) {
-    const pub = buildPublicUrlString({
-      profile: 'local',
-      listenPort,
-      developerIdNum,
-      remoteServer,
-      pathPrefix,
-      patternPath,
-      traefik,
-      hostTemplate,
-      tls,
-      developerIdRaw,
-      infraTlsEnabled,
-      frontDoorIngressActive,
-      declarativeTargetAppKey: declarativeTargetAppKey || targetAppKey,
-      declarativeCurrentAppKey: declarativeCurrentAppKey
-    });
-    try {
-      return new URL(pub).origin;
-    } catch {
-      return `http://${targetAppKey}:${listenPort}`;
-    }
-  }
-  return `http://${targetAppKey}:${listenPort}`;
-}
-
-function buildInternalUrlString(opts) {
-  const {
-    profile,
-    listenPort,
-    targetAppKey,
-    runtimeBasePath,
-    remoteServer,
-    pathPrefix,
-    patternPath,
-    developerIdNum,
-    traefik,
-    hostTemplate,
-    tls,
-    developerIdRaw,
-    infraTlsEnabled,
-    frontDoorIngressActive,
-    declarativeTargetAppKey,
-    declarativeCurrentAppKey
-  } = opts;
-  if (profile === 'docker') {
-    const origin = `http://${targetAppKey}:${listenPort}`;
-    return runtimeBasePath ? joinUrlPath(origin, runtimeBasePath) : origin;
-  }
-  if (remoteServer && String(remoteServer).trim()) {
-    return buildPublicUrlString({
-      profile: 'local',
-      listenPort,
-      developerIdNum,
-      remoteServer,
-      pathPrefix,
-      patternPath,
-      traefik,
-      hostTemplate,
-      tls,
-      developerIdRaw,
-      infraTlsEnabled,
-      frontDoorIngressActive,
-      declarativeTargetAppKey: declarativeTargetAppKey || targetAppKey,
-      declarativeCurrentAppKey: declarativeCurrentAppKey
-    });
-  }
-  return `http://${targetAppKey}:${listenPort}`;
-}
-
-/**
- * @param {object|null|undefined} doc
- * @returns {{ hostTemplate: string|null, tls: boolean }}
- */
-function readFrontDoorHostTlsFromDoc(doc) {
-  if (!doc || !doc.frontDoorRouting) {
-    return { hostTemplate: null, tls: true };
-  }
-  const fd = doc.frontDoorRouting;
-  const hostTemplate =
-    typeof fd.host === 'string' && fd.host.trim() ? fd.host.trim() : null;
-  return { hostTemplate, tls: fd.tls !== false };
-}
-
 /**
  * Ports from application.yaml: `listenPort` = container/process listen ({@link getContainerPort});
  * `publicPortBasis` = manifest root `port` ({@link getLocalPort}) for browser-published host URLs
@@ -296,10 +72,11 @@ function resolveListenPortAndPatternFromDoc(doc, entry) {
 
 /**
  * Port + pattern + optional Traefik host template for a url:// token.
+ * `frontDoorIngressActive` and `perTokenTraefik` come from {@link resolveDeclarativeUrlSurfaceState}.
  * @param {string} token
  * @param {Object} ctx
  * @param {Object} registry
- * @returns {{ appKey: string, listenPort: number, publicPortBasis: number, patternStr: string, hostTemplate: string|null, tls: boolean, frontDoorIngressActive: boolean }|null}
+ * @returns {{ appKey: string, listenPort: number, publicPortBasis: number, patternStr: string, hostTemplate: string|null, tls: boolean, frontDoorIngressActive: boolean, perTokenTraefik: boolean, declarativeUrlSurfacePhase: string, internalDockerUseOriginOnly: boolean }|null}
  */
 function resolveListenPortPatternForToken(token, ctx, registry) {
   const { targetKey } = parseUrlToken(token);
@@ -316,10 +93,18 @@ function resolveListenPortPatternForToken(token, ctx, registry) {
   }
   const { listenPort, publicPortBasis, patternStr } = portPattern;
   const meta = readFrontDoorHostTlsFromDoc(doc);
-  const frontDoorIngressActive = computePathActive(
-    Boolean(ctx.traefik),
-    Boolean(doc && doc.frontDoorRouting && doc.frontDoorRouting.enabled === true)
+  const fromRegistry = readRegistryInternalDockerUseOriginOnly(appKey, registry);
+  const internalDockerUseOriginOnly =
+    fromRegistry !== undefined ? fromRegistry : meta.internalDockerUseOriginOnly;
+  const frontDoorRoutingEnabled = Boolean(
+    doc && doc.frontDoorRouting && doc.frontDoorRouting.enabled === true
   );
+  const { phase, perTokenTraefik, frontDoorIngressActive } = resolveDeclarativeUrlSurfaceState({
+    userCfg: ctx.userCfg,
+    appKey,
+    ctxTraefik: ctx.traefik,
+    frontDoorRoutingEnabled
+  });
   return {
     appKey,
     listenPort,
@@ -327,172 +112,18 @@ function resolveListenPortPatternForToken(token, ctx, registry) {
     patternStr,
     hostTemplate: meta.hostTemplate,
     tls: meta.tls,
-    frontDoorIngressActive
+    frontDoorIngressActive,
+    perTokenTraefik,
+    declarativeUrlSurfacePhase: phase,
+    internalDockerUseOriginOnly
   };
 }
 
-/**
- * Published/browser origin port basis for url:// public surfaces (manifest `port`), not container listen.
- * @param {Object} r
- * @returns {number}
- */
-function publishedOriginPortBasis(r) {
-  const b = r.publicPortBasis;
-  if (b !== undefined && b !== null && Number.isFinite(Number(b))) {
-    return Number(b);
-  }
-  return r.listenPort;
-}
-
-/**
- * @param {Object} r - resolved app + patternPath + pathPrefix + remoteServer + profile + devNum + derivedEnvKey
- * @returns {string}
- */
-function expandHostSurfacePublic(r) {
-  return buildPublicHostOriginString({
-    profile: r.profile,
-    listenPort: publishedOriginPortBasis(r),
-    developerIdNum: r.devNum,
-    remoteServer: r.remoteServer,
-    traefik: r.traefik,
-    hostTemplate: r.hostTemplate,
-    tls: r.tls,
-    developerIdRaw: r.developerIdRaw,
-    infraTlsEnabled: r.infraTlsEnabled,
-    frontDoorIngressActive: r.frontDoorIngressActive,
-    declarativeTargetAppKey: r.appKey,
-    declarativeCurrentAppKey: r.currentAppKey
-  });
-}
-
-/**
- * Local workstation `.env` (no remote-server): browser-reachable URLs only — internal tokens match public.
- * Remote dev keeps internal = public mirroring via {@link buildInternalUrlString} when `remoteServer` is set.
- *
- * @param {Object} r
- * @returns {boolean}
- */
-function isLocalProfileWithoutRemoteServer(r) {
-  return r.profile === 'local' && !String(r.remoteServer || '').trim();
-}
-
-/**
- * @param {Object} r
- * @returns {string}
- */
-function expandHostSurfaceInternal(r) {
-  if (isLocalProfileWithoutRemoteServer(r)) {
-    return expandHostSurfacePublic(r);
-  }
-  return buildInternalHostOriginString({
-    profile: r.profile,
-    listenPort: r.listenPort,
-    targetAppKey: r.appKey,
-    remoteServer: r.remoteServer,
-    pathPrefix: r.pathPrefix,
-    patternPath: r.patternPath,
-    developerIdNum: r.devNum,
-    derivedEnvKey: r.derivedEnvKey,
-    traefik: r.traefik,
-    hostTemplate: r.hostTemplate,
-    tls: r.tls,
-    developerIdRaw: r.developerIdRaw,
-    infraTlsEnabled: r.infraTlsEnabled,
-    frontDoorIngressActive: r.frontDoorIngressActive,
-    declarativeTargetAppKey: r.appKey,
-    declarativeCurrentAppKey: r.currentAppKey
-  });
-}
-
-/**
- * @param {Object} r
- * @returns {string}
- */
-function expandFullSurfacePublic(r) {
-  return buildPublicUrlString({
-    profile: r.profile,
-    listenPort: publishedOriginPortBasis(r),
-    developerIdNum: r.devNum,
-    remoteServer: r.remoteServer,
-    pathPrefix: r.pathPrefix,
-    patternPath: r.patternPath,
-    traefik: r.traefik,
-    hostTemplate: r.hostTemplate,
-    tls: r.tls,
-    developerIdRaw: r.developerIdRaw,
-    infraTlsEnabled: r.infraTlsEnabled,
-    frontDoorIngressActive: r.frontDoorIngressActive,
-    declarativeTargetAppKey: r.appKey,
-    declarativeCurrentAppKey: r.currentAppKey
-  });
-}
-
-/**
- * @param {Object} r
- * @returns {string}
- */
-function expandFullSurfaceInternal(r) {
-  if (isLocalProfileWithoutRemoteServer(r)) {
-    return expandFullSurfacePublic(r);
-  }
-  const runtimePath = runtimeBasePath.normalizeRuntimeBasePath(r.patternPath, r);
-  return buildInternalUrlString({
-    profile: r.profile,
-    listenPort: r.listenPort,
-    targetAppKey: r.appKey,
-    runtimeBasePath: runtimePath,
-    remoteServer: r.remoteServer,
-    pathPrefix: r.pathPrefix,
-    patternPath: r.patternPath,
-    developerIdNum: r.devNum,
-    derivedEnvKey: r.derivedEnvKey,
-    traefik: r.traefik,
-    hostTemplate: r.hostTemplate,
-    tls: r.tls,
-    developerIdRaw: r.developerIdRaw,
-    infraTlsEnabled: r.infraTlsEnabled,
-    frontDoorIngressActive: r.frontDoorIngressActive,
-    declarativeTargetAppKey: r.appKey,
-    declarativeCurrentAppKey: r.currentAppKey
-  });
-}
-
-/**
- * @param {{ kind: string, surface: string }} parsed
- * @param {Object} r
- * @returns {string}
- */
-function expandResolvedUrlToken(parsed, r) {
-  if (parsed.surface === 'vdir') {
-    if (!r.frontDoorIngressActive) {
-      return '';
-    }
-    // Plan 124: docker PRIVATEVDIR is always empty; public vdir still carries pattern
-    if (parsed.kind === 'internal' && r.profile === 'docker') {
-      return '';
-    }
-    const prefix = String(r.pathPrefix || '');
-    const pat = r.patternPath || '/';
-    if (!pat || pat === '/') {
-      return prefix || '';
-    }
-    const joined = `${prefix}${pat}`.replace(/\/{2,}/g, '/');
-    return joined.startsWith('/') ? joined : `/${joined}`;
-  }
-  if (parsed.surface === 'host') {
-    return parsed.kind === 'public' ? expandHostSurfacePublic(r) : expandHostSurfaceInternal(r);
-  }
-  return parsed.kind === 'public' ? expandFullSurfacePublic(r) : expandFullSurfaceInternal(r);
-}
-
 module.exports = {
   applyTstRemoteDeveloperHost,
   applyTstRemoteDeveloperHostToOrigin,
-  buildPublicUrlString,
-  buildPublicHostOriginString,
-  buildInternalUrlString,
-  buildInternalHostOriginString,
+  ...buildUrls,
+  ...expandToken,
   parseUrlToken,
-  expandResolvedUrlToken,
   resolveListenPortPatternForToken
 };

package/lib/utils/url-declarative-resolve-expand-token.js

@@ -0,0 +1,189 @@
+/**
+ * Surface expansion + {@link expandResolvedUrlToken} for declarative url:// tokens.
+ *
+ * @fileoverview Split from url-declarative-resolve-build.js for ESLint max-lines
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  buildPublicUrlString,
+  buildPublicHostOriginString,
+  buildInternalHostOriginString,
+  buildInternalUrlString
+} = require('./url-declarative-resolve-build-urls');
+const { normalizeRuntimeBasePath } = require('./url-declarative-runtime-base-path');
+
+/**
+ * Published/browser origin port basis for url:// public surfaces (manifest `port`), not container listen.
+ * @param {Object} r
+ * @returns {number}
+ */
+function publishedOriginPortBasis(r) {
+  const b = r.publicPortBasis;
+  if (b !== undefined && b !== null && Number.isFinite(Number(b))) {
+    return Number(b);
+  }
+  return r.listenPort;
+}
+
+/**
+ * @param {Object} r - resolved app + patternPath + pathPrefix + remoteServer + profile + devNum + derivedEnvKey
+ * @returns {string}
+ */
+function expandHostSurfacePublic(r) {
+  return buildPublicHostOriginString({
+    profile: r.profile,
+    listenPort: publishedOriginPortBasis(r),
+    developerIdNum: r.devNum,
+    remoteServer: r.remoteServer,
+    traefik: r.traefik,
+    hostTemplate: r.hostTemplate,
+    tls: r.tls,
+    developerIdRaw: r.developerIdRaw,
+    infraTlsEnabled: r.infraTlsEnabled,
+    frontDoorIngressActive: r.frontDoorIngressActive,
+    declarativeTargetAppKey: r.appKey,
+    declarativeCurrentAppKey: r.currentAppKey,
+    declarativePublicUrlsUseLocalhost: r.declarativePublicUrlsUseLocalhost
+  });
+}
+
+/**
+ * Local workstation `.env` (no remote-server): browser-reachable URLs only — internal tokens match public.
+ * **Docker** profile must keep Docker DNS / service hostnames so resolved `.env` works **inside** containers.
+ *
+ * @param {Object} r
+ * @returns {boolean}
+ */
+function isLocalProfileWithoutRemoteServer(r) {
+  return r.profile === 'local' && !String(r.remoteServer || '').trim();
+}
+
+/**
+ * @param {Object} r
+ * @returns {string}
+ */
+function expandHostSurfaceInternal(r) {
+  if (isLocalProfileWithoutRemoteServer(r)) {
+    return expandHostSurfacePublic(r);
+  }
+  return buildInternalHostOriginString({
+    profile: r.profile,
+    listenPort: r.listenPort,
+    targetAppKey: r.appKey,
+    remoteServer: r.remoteServer,
+    pathPrefix: r.pathPrefix,
+    patternPath: r.patternPath,
+    developerIdNum: r.devNum,
+    derivedEnvKey: r.derivedEnvKey,
+    traefik: r.traefik,
+    hostTemplate: r.hostTemplate,
+    tls: r.tls,
+    developerIdRaw: r.developerIdRaw,
+    infraTlsEnabled: r.infraTlsEnabled,
+    frontDoorIngressActive: r.frontDoorIngressActive,
+    declarativeTargetAppKey: r.appKey,
+    declarativeCurrentAppKey: r.currentAppKey,
+    declarativePublicUrlsUseLocalhost: r.declarativePublicUrlsUseLocalhost
+  });
+}
+
+/**
+ * @param {Object} r
+ * @returns {string}
+ */
+function expandFullSurfacePublic(r) {
+  return buildPublicUrlString({
+    profile: r.profile,
+    listenPort: publishedOriginPortBasis(r),
+    developerIdNum: r.devNum,
+    remoteServer: r.remoteServer,
+    pathPrefix: r.pathPrefix,
+    patternPath: r.patternPath,
+    traefik: r.traefik,
+    hostTemplate: r.hostTemplate,
+    tls: r.tls,
+    developerIdRaw: r.developerIdRaw,
+    infraTlsEnabled: r.infraTlsEnabled,
+    frontDoorIngressActive: r.frontDoorIngressActive,
+    declarativeTargetAppKey: r.appKey,
+    declarativeCurrentAppKey: r.currentAppKey,
+    declarativePublicUrlsUseLocalhost: r.declarativePublicUrlsUseLocalhost
+  });
+}
+
+/**
+ * @param {Object} r
+ * @returns {string}
+ */
+function expandFullSurfaceInternal(r) {
+  if (isLocalProfileWithoutRemoteServer(r)) {
+    return expandFullSurfacePublic(r);
+  }
+  const useOriginOnly =
+    r.profile === 'docker' && Boolean(r.internalDockerUseOriginOnly);
+  const runtimePath = useOriginOnly
+    ? ''
+    : normalizeRuntimeBasePath(r.patternPath, r);
+  return buildInternalUrlString({
+    profile: r.profile,
+    listenPort: r.listenPort,
+    targetAppKey: r.appKey,
+    runtimeBasePath: runtimePath,
+    remoteServer: r.remoteServer,
+    pathPrefix: r.pathPrefix,
+    patternPath: r.patternPath,
+    developerIdNum: r.devNum,
+    derivedEnvKey: r.derivedEnvKey,
+    traefik: r.traefik,
+    hostTemplate: r.hostTemplate,
+    tls: r.tls,
+    developerIdRaw: r.developerIdRaw,
+    infraTlsEnabled: r.infraTlsEnabled,
+    frontDoorIngressActive: r.frontDoorIngressActive,
+    declarativeTargetAppKey: r.appKey,
+    declarativeCurrentAppKey: r.currentAppKey,
+    declarativePublicUrlsUseLocalhost: r.declarativePublicUrlsUseLocalhost
+  });
+}
+
+/**
+ * @param {{ kind: string, surface: string }} parsed
+ * @param {Object} r
+ * @returns {string}
+ */
+function expandResolvedUrlToken(parsed, r) {
+  if (parsed.surface === 'vdir') {
+    if (!r.frontDoorIngressActive) {
+      return '';
+    }
+    // Plan 124: docker PRIVATEVDIR is always empty; public vdir still carries pattern
+    if (parsed.kind === 'internal' && r.profile === 'docker') {
+      return '';
+    }
+    const prefix = String(r.pathPrefix || '');
+    const pat = r.patternPath || '/';
+    if (!pat || pat === '/') {
+      return prefix || '';
+    }
+    const joined = `${prefix}${pat}`.replace(/\/{2,}/g, '/');
+    return joined.startsWith('/') ? joined : `/${joined}`;
+  }
+  if (parsed.surface === 'host') {
+    return parsed.kind === 'public' ? expandHostSurfacePublic(r) : expandHostSurfaceInternal(r);
+  }
+  return parsed.kind === 'public' ? expandFullSurfacePublic(r) : expandFullSurfaceInternal(r);
+}
+
+module.exports = {
+  publishedOriginPortBasis,
+  isLocalProfileWithoutRemoteServer,
+  expandHostSurfacePublic,
+  expandHostSurfaceInternal,
+  expandFullSurfacePublic,
+  expandFullSurfaceInternal,
+  expandResolvedUrlToken
+};

package/lib/utils/url-declarative-resolve-load-doc.js

@@ -29,11 +29,16 @@ function tryReadApplicationYamlAt(cfgPath) {
  * Prefer projectRoot/builder (fixtures, tests); then {@link pathsUtil.getBuilderPath} (global npm).
  * @param {string} appKey
  * @param {object} pathsUtil
+ * @param {string|null|undefined} [projectRootOverride] - When set (e.g. `ctx.projectRoot`), used instead of {@link pathsUtil.getProjectRoot} for the first candidate path (avoids flaky cross-test `paths` mocks).
  * @returns {string[]}
  */
-function collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil) {
+function collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil, projectRootOverride) {
   const list = [];
-  const root = pathsUtil.getProjectRoot();
+  const trimmed =
+    projectRootOverride !== undefined && projectRootOverride !== null
+      ? String(projectRootOverride).trim()
+      : '';
+  const root = trimmed || pathsUtil.getProjectRoot();
   if (root) {
     list.push(path.resolve(path.join(root, 'builder', appKey, 'application.yaml')));
   }
@@ -64,7 +69,11 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
         return fromVars;
       }
     }
-    for (const cfgPath of collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil)) {
+    const pr =
+      ctx && ctx.projectRoot !== undefined && ctx.projectRoot !== null
+        ? String(ctx.projectRoot).trim()
+        : '';
+    for (const cfgPath of collectApplicationYamlPathsForUrlResolve(appKey, pathsUtil, pr || undefined)) {
       const doc = tryReadApplicationYamlAt(cfgPath);
       if (doc) {
         return doc;