@aifabrix/builder 2.44.5 → 2.45.0

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;

package/lib/utils/url-declarative-resolve-surface-state.js

@@ -0,0 +1,102 @@
+/**
+ * Declarative url:// **surface state machine** (plan 124 + per-app `applications.<app>.proxy`).
+ *
+ * FSM inputs (per token target): `perTokenTraefik`, `frontDoorRoutingEnabled` (strict true in yaml).
+ * Output phase is the product space (see `PHASE_BY_TRAEFIK_AND_FRONT_DOOR`); `pathActive` matches
+ * {@link computePathActive}(perTokenTraefik, frontDoorRoutingEnabled).
+ *
+ * @fileoverview Single source for `perTokenTraefik` × `frontDoorRouting.enabled` → phase + `pathActive`
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { isDeclarativeTraefikUrlsEnabled } = require('./applications-config-defaults');
+const { computePathActive } = require('./url-declarative-url-flags');
+
+/**
+ * Public URL surface phase for one url:// token target app.
+ * @readonly
+ * @enum {string}
+ */
+const DeclarativeUrlSurfacePhase = {
+  /** No Traefik-style hints for this token (`perTokenTraefik` false). */
+  DIRECT: 'DIRECT',
+  /** Traefik on for Plan 117 path prefix, but `frontDoorRouting.enabled` is not true — no ingress path. */
+  TRAEFIK_SCOPED: 'TRAEFIK_SCOPED',
+  /** Traefik + front door enabled — `pathActive` / pattern + vdir-public behave as ingress. */
+  FRONT_DOOR: 'FRONT_DOOR'
+};
+
+/**
+ * @typedef {Object} DeclarativeUrlSurfaceInputs
+ * @property {Object|null|undefined} userCfg - `~/.aifabrix/config.yaml` root when resolve passes it
+ * @property {string} appKey - Target app for the url:// token
+ * @property {boolean|undefined} ctxTraefik - Legacy global flag when `userCfg` is absent
+ * @property {boolean} frontDoorRoutingEnabled - From `application.yaml` `frontDoorRouting.enabled === true`
+ */
+
+/**
+ * Bit-pair → phase lookup (explicit FSM output table).
+ * Keys: `${perTokenTraefik}:${frontDoorRoutingEnabled}` (booleans coerced to strings).
+ *
+ * @type {Object.<string, keyof typeof DeclarativeUrlSurfacePhase>}
+ */
+const PHASE_BY_TRAEFIK_AND_FRONT_DOOR = {
+  'false:false': DeclarativeUrlSurfacePhase.DIRECT,
+  'false:true': DeclarativeUrlSurfacePhase.DIRECT,
+  'true:false': DeclarativeUrlSurfacePhase.TRAEFIK_SCOPED,
+  'true:true': DeclarativeUrlSurfacePhase.FRONT_DOOR
+};
+
+/**
+ * @param {boolean} perTokenTraefik
+ * @param {boolean} frontDoorRoutingEnabled
+ * @returns {string} {@link DeclarativeUrlSurfacePhase}
+ */
+function phaseFromTraefikAndFrontDoor(perTokenTraefik, frontDoorRoutingEnabled) {
+  const k = `${Boolean(perTokenTraefik)}:${Boolean(frontDoorRoutingEnabled)}`;
+  const phase = PHASE_BY_TRAEFIK_AND_FRONT_DOOR[k];
+  return phase || DeclarativeUrlSurfacePhase.DIRECT;
+}
+
+/**
+ * Whether Traefik-style URL hints apply for this token (infra + per-app proxy, or legacy `ctx.traefik`).
+ *
+ * @param {DeclarativeUrlSurfaceInputs} input
+ * @returns {boolean}
+ */
+function resolvePerTokenTraefik(input) {
+  const { userCfg, appKey, ctxTraefik } = input;
+  if (userCfg && appKey) {
+    return isDeclarativeTraefikUrlsEnabled(userCfg, appKey);
+  }
+  return Boolean(ctxTraefik);
+}
+
+/**
+ * Resolve surface phase and derived flags for one declarative url:// target.
+ *
+ * @param {DeclarativeUrlSurfaceInputs} input
+ * @returns {{
+ *   phase: string,
+ *   perTokenTraefik: boolean,
+ *   frontDoorIngressActive: boolean
+ * }}
+ */
+function resolveDeclarativeUrlSurfaceState(input) {
+  const frontDoorRoutingEnabled = Boolean(input.frontDoorRoutingEnabled);
+  const perTokenTraefik = resolvePerTokenTraefik(input);
+  const phase = phaseFromTraefikAndFrontDoor(perTokenTraefik, frontDoorRoutingEnabled);
+  const frontDoorIngressActive = computePathActive(perTokenTraefik, frontDoorRoutingEnabled);
+  return { phase, perTokenTraefik, frontDoorIngressActive };
+}
+
+module.exports = {
+  DeclarativeUrlSurfacePhase,
+  PHASE_BY_TRAEFIK_AND_FRONT_DOOR,
+  phaseFromTraefikAndFrontDoor,
+  resolvePerTokenTraefik,
+  resolveDeclarativeUrlSurfaceState
+};

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

@@ -17,6 +17,9 @@ const { computeDeclarativePathPrefix } = require('./url-declarative-url-flags');
 const { refreshUrlsLocalRegistryFromBuilder, normalizePatternForUrl } = require('./urls-local-registry');
 const pathsUtil = require('./paths');
 const { parseUrlToken } = require('./url-declarative-token-parse');
+const {
+  getApplicationsRunProxyHint
+} = require('./applications-config-defaults');
 const {
   applyTstRemoteDeveloperHost,
   applyTstRemoteDeveloperHostToOrigin,
@@ -100,6 +103,27 @@ function readTargetAppScopedFlag(targetAppKey) {
   }
 }
 
+/**
+ * When global `traefik` is **false** in user config, public bases never use `remote-server`.
+ * Otherwise follows per-app `proxy` or legacy `ctx.declarativePublicUrlsUseLocalhost`.
+ *
+ * @param {Object} ctx
+ * @param {string} [appKey]
+ * @returns {boolean|undefined}
+ */
+function resolveDeclarativePublicLocalhostFlag(ctx, appKey) {
+  if (ctx.userCfg && ctx.userCfg.traefik === false) {
+    return true;
+  }
+  if (ctx.userCfg && appKey) {
+    return !getApplicationsRunProxyHint(ctx.userCfg, appKey);
+  }
+  if (ctx.declarativePublicUrlsUseLocalhost === undefined) {
+    return undefined;
+  }
+  return Boolean(ctx.declarativePublicUrlsUseLocalhost);
+}
+
 /**
  * Resolve one url:// token to a concrete URL string.
  * @param {string} token
@@ -123,14 +147,18 @@ function replaceUrlRefToken(token, ctx, profile, devNum, derivedEnvKey, registry
     patternStr,
     hostTemplate,
     tls,
-    frontDoorIngressActive
+    frontDoorIngressActive,
+    perTokenTraefik,
+    internalDockerUseOriginOnly
   } = resolved;
+  const traefikForToken = perTokenTraefik;
+  const declarativePublicUrlsUseLocalhostForToken = resolveDeclarativePublicLocalhostFlag(ctx, appKey);
   const patternPath = normalizePatternForUrl(patternStr);
   const appScoped = parsed.targetKey
     ? readTargetAppScopedFlag(parsed.targetKey)
     : Boolean(ctx.appEnvironmentScopedResources);
   const pathPrefix = computeDeclarativePathPrefix(
-    Boolean(ctx.traefik),
+    traefikForToken,
     ctx.useEnvironmentScopedResources,
     appScoped,
     derivedEnvKey
@@ -146,12 +174,14 @@ function replaceUrlRefToken(token, ctx, profile, devNum, derivedEnvKey, registry
     remoteServer: ctx.remoteServer,
     devNum,
     derivedEnvKey,
-    traefik: Boolean(ctx.traefik),
+    traefik: traefikForToken,
     hostTemplate,
     tls,
     frontDoorIngressActive,
     developerIdRaw: ctx.developerIdRaw,
-    infraTlsEnabled: Boolean(ctx.infraTlsEnabled)
+    infraTlsEnabled: Boolean(ctx.infraTlsEnabled),
+    internalDockerUseOriginOnly,
+    declarativePublicUrlsUseLocalhost: declarativePublicUrlsUseLocalhostForToken
   });
 }
 
@@ -168,8 +198,12 @@ function replaceUrlRefToken(token, ctx, profile, devNum, derivedEnvKey, registry
  * @param {boolean} ctx.appEnvironmentScopedResources
  * @param {string|null|undefined} ctx.remoteServer
  * @param {string|number|null|undefined} ctx.developerIdRaw
- * @param {boolean} [ctx.traefik] - Infra Traefik proxy on. Plan 117 `/dev`/`/tst` applies only when this is true. Traefik **host** authority (`frontDoorRouting.host`) applies only when this is true **and** the target app has `frontDoorRouting.enabled: true` (plan 124 `pathActive`).
- * @param {boolean} [ctx.infraTlsEnabled] - When true (`tlsEnabled` in config / `up-infra --tls`), Traefik front-door `url://public` uses https even if application.yaml has `frontDoorRouting.tls: false`
+ * @param {boolean} [ctx.traefik] - When `ctx.userCfg` is absent: global Traefik-style URL flag. When `ctx.userCfg` is set: `ctx.traefik` is ignored for per-token Traefik; see {@link resolveDeclarativeUrlSurfaceState}.
+ * @param {boolean|undefined} [ctx.declarativePublicUrlsUseLocalhost] - When `ctx.userCfg` is absent: **`undefined`** (default) skips `remote-server` when Traefik is off; **`true`** forces localhost; **`false`** allows remote authority without Traefik. When `ctx.userCfg` is set and root **`traefik` is not** `false`: ignored for public bases; derived per target app from `applications.<target>.proxy`. When **`ctx.userCfg.traefik === false`**, public bases always use localhost (per-app `proxy` does not opt into `remote-server` without infra Traefik).
+ * @param {Object} [ctx.userCfg] - `~/.aifabrix/config.yaml` root; when set, `applications.<app>.proxy` and `traefik` apply per **target** app for each `url://` token (so e.g. Keycloak URLs follow `applications.keycloak`, not only the app being resolved), except public authority stays on localhost when root `traefik` is **`false`**.
+ * @param {string|null|undefined} [ctx.projectRoot] - Optional absolute project root for `builder/<app>/application.yaml` discovery and `urls.local.yaml` refresh; when set, avoids relying on `paths.getProjectRoot()` (stable under cross-test `paths` mocks).
+ * @param {boolean} [ctx.excludeCwdBuilderScan] - When **true**, {@link refreshUrlsLocalRegistryFromBuilder} omits the cwd checkout **`builder/`** directory from the canonical scan list (tests / isolated fixtures that must not merge the ambient repo `builder/` into `urls.local.yaml`). Omit or **false** for normal CLI and `.env` expansion.
+ * @param {boolean} [ctx.infraTlsEnabled] - When true (`tlsEnabled` in config / `up-infra --tls`), Traefik front-door `url://public` uses **https**; when **false**, front-door bases use **http** (regardless of `frontDoorRouting.tls`). Loopback hosts stay **http**.
  * @returns {Promise<string>}
  */
 async function expandDeclarativeUrlsInEnvContent(content, ctx) {
@@ -182,7 +216,13 @@ async function expandDeclarativeUrlsInEnvContent(content, ctx) {
   const clientId = envMap.MISO_CLIENTID;
   const pipelineOverride = envMap.MISO_PIPELINE_ENV_KEY;
   const derivedEnvKey = deriveEnvKeyFromClientId(clientId, pipelineOverride);
-  const registry = refreshUrlsLocalRegistryFromBuilder(pathsUtil.getProjectRoot());
+  const pr =
+    ctx.projectRoot !== undefined && ctx.projectRoot !== null ? String(ctx.projectRoot).trim() : '';
+  const registryRoot = pr || pathsUtil.getProjectRoot();
+  const registry =
+    ctx.excludeCwdBuilderScan === true
+      ? refreshUrlsLocalRegistryFromBuilder(registryRoot, { excludeCwdBuilderScan: true })
+      : refreshUrlsLocalRegistryFromBuilder(registryRoot);
 
   const lines = content.split('\n');
   const outLines = lines.map((line) => {

package/lib/utils/url-declarative-runtime-base-path.js

@@ -0,0 +1,52 @@
+/**
+ * Runtime base path helpers for declarative url:// resolution.
+ *
+ * @fileoverview Keeps path-aware internal URLs out of the main resolver file.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Runtime base path is derived from the existing frontDoorRouting path only
+ * when that path is active for the target app.
+ * @param {string|null|undefined} patternPath
+ * @param {Object} r
+ * @returns {string}
+ */
+function normalizeRuntimeBasePath(patternPath, r) {
+  if (!r.frontDoorIngressActive) {
+    return '';
+  }
+  const value = String(patternPath || '').trim();
+  if (!value || value === '/') {
+    return '';
+  }
+  const pathValue = value.startsWith('/') ? value : `/${value}`;
+  return pathValue.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+}
+
+/**
+ * Read front-door host/TLS and optional internal-Docker origin-only flag from application.yaml.
+ * @param {object|null|undefined} doc
+ * @returns {{ hostTemplate: string|null, tls: boolean, internalDockerUseOriginOnly: boolean }}
+ */
+function readFrontDoorHostTlsFromDoc(doc) {
+  if (!doc || !doc.frontDoorRouting) {
+    return { hostTemplate: null, tls: true, internalDockerUseOriginOnly: false };
+  }
+  const fd = doc.frontDoorRouting;
+  const hostTemplate =
+    typeof fd.host === 'string' && fd.host.trim() ? fd.host.trim() : null;
+  return {
+    hostTemplate,
+    tls: fd.tls !== false,
+    internalDockerUseOriginOnly: fd.internalDockerUseOriginOnly === true
+  };
+}
+
+module.exports = {
+  normalizeRuntimeBasePath,
+  readFrontDoorHostTlsFromDoc
+};

package/lib/utils/url-declarative-vdir-inactive-env.js

@@ -95,5 +95,6 @@ module.exports = {
   URL_DECLARATIVE_VDIR_PUBLIC_TOKEN,
   INACTIVE_VDIR_PUBLIC_ENV_FALLBACK,
   applyInactiveVdirPublicTokenRewrite,
-  rewriteInactiveDeclarativeVdirPublicContent
+  rewriteInactiveDeclarativeVdirPublicContent,
+  isFrontDoorRoutingEnabledInDoc
 };

package/lib/utils/urls-local-registry-scan.js

@@ -0,0 +1,103 @@
+/**
+ * Builder-directory scan for {@link module:lib/utils/urls-local-registry} refresh.
+ *
+ * @fileoverview Collect application config per app key across builder roots (plan 141 P3: scan order
+ *   defines precedence; later directories override earlier ones for the same `app.key`).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fsRealSync = require('../internal/fs-real-sync');
+const { resolveApplicationConfigPath } = require('./app-config-resolver');
+const { loadConfigFile } = require('./config-format');
+
+/**
+ * @param {string} appDir - Absolute path to a builder app folder (directory containing application config)
+ * @returns {{ doc: object }|null}
+ */
+function tryGetApplicationDirConfigForRegistry(appDir) {
+  let cfgPath;
+  try {
+    cfgPath = resolveApplicationConfigPath(appDir);
+  } catch {
+    return null;
+  }
+  if (!fsRealSync.existsSync(cfgPath)) {
+    return null;
+  }
+  let doc;
+  try {
+    doc = loadConfigFile(cfgPath);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== 'object') {
+    return null;
+  }
+  return { doc };
+}
+
+/**
+ * @param {string} builderDir
+ * @param {import('fs').Dirent} ent
+ * @param {number} dirIndex
+ * @param {Map<string, { folderName: string, doc: object, dirIndex: number }>} best
+ */
+function maybeUpdateBestFromAppFolder(builderDir, ent, dirIndex, best) {
+  const appDir = path.join(builderDir, ent.name);
+  const entry = tryGetApplicationDirConfigForRegistry(appDir);
+  if (!entry) {
+    return;
+  }
+  const { doc } = entry;
+  const appKey = (doc.app && doc.app.key) || ent.name;
+  const cur = best.get(appKey);
+  if (!cur || dirIndex > cur.dirIndex) {
+    best.set(appKey, { folderName: ent.name, doc, dirIndex });
+  }
+}
+
+/**
+ * @param {string} builderDir
+ * @param {number} dirIndex
+ * @param {Map<string, { folderName: string, doc: object, dirIndex: number }>} best
+ */
+function mergeBuilderDirScanIntoBestMap(builderDir, dirIndex, best) {
+  if (!builderDir || typeof builderDir !== 'string') {
+    return;
+  }
+  if (!fsRealSync.existsSync(builderDir) || !fsRealSync.statSync(builderDir).isDirectory()) {
+    return;
+  }
+  for (const ent of fsRealSync.readdirSync(builderDir, { withFileTypes: true })) {
+    if (!ent.isDirectory()) {
+      continue;
+    }
+    maybeUpdateBestFromAppFolder(builderDir, ent, dirIndex, best);
+  }
+}
+
+/**
+ * When the same app exists under multiple builder roots, the **last** directory in `scanDirs`
+ * wins (highest `dirIndex`). Matches plan 141 canonical precedence (checkout / cwd after system materialization).
+ *
+ * @param {string[]} scanDirs - Builder or `packages` directories, low → high priority
+ * @returns {Array<{ folderName: string, doc: object }>}
+ */
+function collectLatestApplicationYamlEntriesPerApp(scanDirs) {
+  /** @type {Map<string, { folderName: string, doc: object, dirIndex: number }>} */
+  const best = new Map();
+  scanDirs.forEach((builderDir, dirIndex) => {
+    mergeBuilderDirScanIntoBestMap(builderDir, dirIndex, best);
+  });
+  return [...best.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([, v]) => ({ folderName: v.folderName, doc: v.doc }));
+}
+
+module.exports = {
+  collectLatestApplicationYamlEntriesPerApp
+};