@aifabrix/builder 2.45.5 → 2.46.0

package/lib/utils/token-manager-client-credentials.js

@@ -0,0 +1,201 @@
+/**
+ * Client credential loading from secrets.local.yaml and environment.
+ *
+ * @fileoverview Client credentials helpers for token-manager
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+const logger = require('./logger');
+const pathsUtil = require('./paths');
+
+/** App key used for dataplane client credentials in secrets.local.yaml */
+const DATAPLANE_APP_KEY = 'dataplane';
+
+/**
+ * @returns {string}
+ */
+function getSecretsFilePath() {
+  return pathsUtil.getPrimaryUserSecretsLocalPath();
+}
+
+/**
+ * Validate that secrets.local.yaml contains dataplane client credentials.
+ * @param {string} [secretsFilePath] - Path to secrets file; defaults to ~/.aifabrix/secrets.local.yaml
+ * @returns {{ valid: boolean, hint?: string }}
+ */
+function validateDataplaneSecrets(secretsFilePath) {
+  const filePath = secretsFilePath || getSecretsFilePath();
+  const hint = 'Dataplane credentials are missing. Run: aifabrix app rotate-secret dataplane';
+  try {
+    if (!fs.existsSync(filePath)) {
+      return { valid: false, hint };
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const secrets = yaml.load(content) || {};
+    const clientIdKey = `${DATAPLANE_APP_KEY}-client-idKeyVault`;
+    const clientSecretKey = `${DATAPLANE_APP_KEY}-client-secretKeyVault`;
+    const hasId =
+      secrets[clientIdKey] !== null &&
+      secrets[clientIdKey] !== undefined &&
+      String(secrets[clientIdKey]).trim() !== '';
+    const hasSecret =
+      secrets[clientSecretKey] !== null &&
+      secrets[clientSecretKey] !== undefined &&
+      String(secrets[clientSecretKey]).trim() !== '';
+    if (hasId && hasSecret) {
+      return { valid: true };
+    }
+    return { valid: false, hint };
+  } catch {
+    return { valid: false, hint };
+  }
+}
+
+/**
+ * Read client id/secret for one app key from secrets.local.yaml.
+ * @param {string} appName - Application key
+ * @returns {{ clientId: string, clientSecret: string }|null}
+ */
+function readClientCredentialsFromSecretsFile(appName) {
+  try {
+    const secretsFile = getSecretsFilePath();
+    if (!fs.existsSync(secretsFile)) {
+      return null;
+    }
+    const content = fs.readFileSync(secretsFile, 'utf8');
+    const secrets = yaml.load(content) || {};
+    const clientId = secrets[`${appName}-client-idKeyVault`];
+    const clientSecret = secrets[`${appName}-client-secretKeyVault`];
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId),
+        clientSecret: String(clientSecret)
+      };
+    }
+  } catch (error) {
+    logger.warn(`Failed to load credentials from secrets.local.yaml: ${error.message}`);
+  }
+  return null;
+}
+
+/**
+ * App keys to try when resolving client credentials (integration app, then dataplane).
+ * @param {string} appName
+ * @returns {string[]}
+ */
+function credentialAppKeysToTry(appName) {
+  const keys = [appName];
+  if (appName !== DATAPLANE_APP_KEY) {
+    keys.push(DATAPLANE_APP_KEY);
+  }
+  return keys;
+}
+
+/**
+ * @returns {{ clientId: string, clientSecret: string }|null}
+ */
+function readClientCredentialsFromEnv() {
+  const pairs = [
+    [process.env.CLIENTID || process.env.CLIENT_ID, process.env.CLIENTSECRET || process.env.CLIENT_SECRET],
+    [
+      process.env.MISO_CLIENTID || process.env.MISO_CLIENT_ID,
+      process.env.MISO_CLIENTSECRET || process.env.MISO_CLIENT_SECRET
+    ]
+  ];
+  for (const [clientId, clientSecret] of pairs) {
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId).trim(),
+        clientSecret: String(clientSecret).trim()
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Decrypt secure:// client credential entries from secrets.local.yaml when needed.
+ * @param {string} appName
+ * @param {{ clientId: string, clientSecret: string }} raw
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function decryptClientCredentialsFromSecrets(appName, raw) {
+  const { isEncrypted } = require('./secrets-encryption');
+  if (!isEncrypted(raw.clientId) && !isEncrypted(raw.clientSecret)) {
+    return raw;
+  }
+  try {
+    const { decryptSecretsObject } = require('../core/secrets-load');
+    const idKey = `${appName}-client-idKeyVault`;
+    const secretKey = `${appName}-client-secretKeyVault`;
+    const decrypted = await decryptSecretsObject({
+      [idKey]: raw.clientId,
+      [secretKey]: raw.clientSecret
+    });
+    const clientId = decrypted[idKey];
+    const clientSecret = decrypted[secretKey];
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId),
+        clientSecret: String(clientSecret)
+      };
+    }
+  } catch (error) {
+    logger.warn(`Failed to decrypt client credentials for ${appName}: ${error.message}`);
+  }
+  return null;
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function readClientCredentialsFromSecretsFileDecrypted(appName) {
+  const raw = readClientCredentialsFromSecretsFile(appName);
+  if (!raw) {
+    return null;
+  }
+  return decryptClientCredentialsFromSecrets(appName, raw);
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ credentialApp: string, credentials: { clientId: string, clientSecret: string }|null }>}
+ */
+async function resolveCredentialAppForDeployment(appName) {
+  const fromEnv = readClientCredentialsFromEnv();
+  if (fromEnv) {
+    return { credentialApp: appName, credentials: fromEnv };
+  }
+  for (const key of credentialAppKeysToTry(appName)) {
+    const fromFile = await readClientCredentialsFromSecretsFileDecrypted(key);
+    if (fromFile) {
+      return { credentialApp: key, credentials: fromFile };
+    }
+  }
+  return { credentialApp: appName, credentials: null };
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function loadClientCredentials(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  const resolved = await resolveCredentialAppForDeployment(appName);
+  return resolved.credentials;
+}
+
+module.exports = {
+  DATAPLANE_APP_KEY,
+  validateDataplaneSecrets,
+  loadClientCredentials,
+  resolveCredentialAppForDeployment
+};

package/lib/utils/token-manager-messages.js

@@ -39,6 +39,10 @@ function resetRefreshWarnedUrlsForTesting() {
  * @param {string} errorMessage - Full error message to log
  */
 function warnRefreshTokenExpiredOnce(controllerUrl, errorMessage) {
+  const { isSetupPlatformFlow } = require('../commands/setup-run-context');
+  if (isSetupPlatformFlow()) {
+    return;
+  }
   const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
     ? config.normalizeControllerUrl(controllerUrl)
     : '__no_url__';
@@ -72,6 +76,10 @@ function formatRefreshFailureMessage(errorMessage, controllerUrl) {
  * @param {string} errorMessage - Raw error message
  */
 function warnRefreshFailureOnce(controllerUrl, errorMessage) {
+  const { isSetupPlatformFlow } = require('../commands/setup-run-context');
+  if (isSetupPlatformFlow()) {
+    return;
+  }
   const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
     ? config.normalizeControllerUrl(controllerUrl)
     : '__no_url__';

package/lib/utils/token-manager-refresh.js

@@ -79,11 +79,21 @@ async function callTokenApi(controllerUrl, credentials) {
   }
 
   const responseData = response.data;
-  if (!responseData || !responseData.token) {
+  const token =
+    responseData?.token ||
+    responseData?.data?.token ||
+    responseData?.data?.data?.token ||
+    responseData?.accessToken;
+  if (!token) {
     throw new Error('Invalid response: missing token');
   }
 
-  return responseData;
+  return {
+    ...responseData,
+    token,
+    expiresIn: responseData.expiresIn ?? responseData.data?.expiresIn,
+    expiresAt: responseData.expiresAt ?? responseData.data?.expiresAt
+  };
 }
 
 /**

package/lib/utils/token-manager.js

@@ -9,99 +9,19 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
-const yaml = require('js-yaml');
 const config = require('../core/config');
 const logger = require('./logger');
-const pathsUtil = require('./paths');
 const {
   refreshClientToken,
   refreshDeviceToken
 } = require('./token-manager-refresh');
 const { warnRefreshFailureOnce, warnRefreshTokenExpiredOnce } = require('./token-manager-messages');
-
-/** App key used for dataplane client credentials in secrets.local.yaml */
-const DATAPLANE_APP_KEY = 'dataplane';
-
-function getSecretsFilePath() {
-  return pathsUtil.getPrimaryUserSecretsLocalPath();
-}
-
-/**
- * Validate that secrets.local.yaml contains dataplane client credentials.
- * If missing, the developer should run: aifabrix app rotate-secret dataplane
- * @param {string} [secretsFilePath] - Path to secrets file; defaults to ~/.aifabrix/secrets.local.yaml
- * @returns {{ valid: boolean, hint?: string }}
- */
-function validateDataplaneSecrets(secretsFilePath) {
-  const filePath = secretsFilePath || getSecretsFilePath();
-  const hint = 'Dataplane credentials are missing. Run: aifabrix app rotate-secret dataplane';
-  try {
-    if (!fs.existsSync(filePath)) {
-      return { valid: false, hint };
-    }
-    const content = fs.readFileSync(filePath, 'utf8');
-    const secrets = yaml.load(content) || {};
-    const clientIdKey = `${DATAPLANE_APP_KEY}-client-idKeyVault`;
-    const clientSecretKey = `${DATAPLANE_APP_KEY}-client-secretKeyVault`;
-    const hasId = secrets[clientIdKey] !== null && secrets[clientIdKey] !== undefined && String(secrets[clientIdKey]).trim() !== '';
-    const hasSecret = secrets[clientSecretKey] !== null && secrets[clientSecretKey] !== undefined && String(secrets[clientSecretKey]).trim() !== '';
-    if (hasId && hasSecret) {
-      return { valid: true };
-    }
-    return { valid: false, hint };
-  } catch {
-    return { valid: false, hint };
-  }
-}
-
-/**
- * Load client credentials from secrets.local.yaml or process.env (e.g. integration/hubspot-test/.env).
- * Reads secrets file using pattern: <app-name>-client-idKeyVault and <app-name>-client-secretKeyVault.
- * If not found, checks process.env.CLIENTID and process.env.CLIENTSECRET (set when .env is loaded).
- * @param {string} appName - Application name
- * @returns {Promise<{clientId: string, clientSecret: string}|null>} Credentials or null if not found
- */
-async function loadClientCredentials(appName) {
-  if (!appName || typeof appName !== 'string') {
-    throw new Error('App name is required and must be a string');
-  }
-
-  try {
-    const secretsFile = getSecretsFilePath();
-    if (fs.existsSync(secretsFile)) {
-      const content = fs.readFileSync(secretsFile, 'utf8');
-      const secrets = yaml.load(content) || {};
-
-      const clientIdKey = `${appName}-client-idKeyVault`;
-      const clientSecretKey = `${appName}-client-secretKeyVault`;
-
-      const clientId = secrets[clientIdKey];
-      const clientSecret = secrets[clientSecretKey];
-
-      if (clientId && clientSecret) {
-        return {
-          clientId: String(clientId),
-          clientSecret: String(clientSecret)
-        };
-      }
-    }
-  } catch (error) {
-    logger.warn(`Failed to load credentials from secrets.local.yaml: ${error.message}`);
-  }
-
-  // Fallback: use CLIENTID/CLIENTSECRET from process.env (e.g. from integration/hubspot-test/.env)
-  const envClientId = process.env.CLIENTID || process.env.CLIENT_ID;
-  const envClientSecret = process.env.CLIENTSECRET || process.env.CLIENT_SECRET;
-  if (envClientId && envClientSecret) {
-    return {
-      clientId: String(envClientId).trim(),
-      clientSecret: String(envClientSecret).trim()
-    };
-  }
-
-  return null;
-}
+const {
+  DATAPLANE_APP_KEY,
+  validateDataplaneSecrets,
+  loadClientCredentials,
+  resolveCredentialAppForDeployment
+} = require('./token-manager-client-credentials');
 
 /**
  * Get device token for controller
@@ -201,8 +121,12 @@ async function getOrRefreshDeviceToken(controllerUrl) {
   // Token needs refresh (expired or within 15 minutes of expiry)
   // Try to refresh if refresh token exists
   if (!tokenInfo.refreshToken) {
-    // No refresh token available
-    logger.warn('Access token expired and no refresh token available. Please login again using: aifabrix login');
+    const { isSetupPlatformFlow } = require('../commands/setup-run-context');
+    if (!isSetupPlatformFlow()) {
+      logger.warn(
+        'Access token expired and no refresh token available. Please login again using: aifabrix login'
+      );
+    }
     return null;
   }
 
@@ -302,27 +226,34 @@ async function tryClientTokenAuth(environment, appName, controllerUrl) {
  * @returns {Promise<{type: 'bearer'|'client-token', token: string, controller: string}>} Auth config: bearer = user token, client-token = app token (x-client-token header)
  * @throws {Error} If no authentication method is available
  */
-async function getDeploymentAuth(controllerUrl, environment, appName) {
+async function getDeploymentAuth(controllerUrl, environment, appName, options = {}) {
+  const { getDeploymentAuthMode, shouldUseDeviceTokenForDeployment } = require('./deployment-auth-mode');
   validateDeploymentAuthParams(controllerUrl, environment, appName);
+  const mode = getDeploymentAuthMode(options);
 
-  // Priority 1: Try device token (for user-level audit)
-  const deviceAuth = await tryDeviceTokenAuth(controllerUrl);
-  if (deviceAuth) {
-    return deviceAuth;
+  if (shouldUseDeviceTokenForDeployment(mode)) {
+    const deviceAuth = await tryDeviceTokenAuth(controllerUrl);
+    if (deviceAuth) {
+      return deviceAuth;
+    }
+    if (mode === 'device') {
+      throw new Error(
+        'Device token required (AIFABRIX_DEPLOYMENT_AUTH=device). Run: aifabrix login'
+      );
+    }
   }
 
-  // Priority 2: Try client token (application-level)
-  const clientTokenAuth = await tryClientTokenAuth(environment, appName, controllerUrl);
+  const { credentialApp, credentials } = await resolveCredentialAppForDeployment(appName);
+
+  const clientTokenAuth = await tryClientTokenAuth(environment, credentialApp, controllerUrl);
   if (clientTokenAuth) {
     return clientTokenAuth;
   }
 
-  // Priority 3: Exchange client credentials for a token (never return client-credentials for app endpoints)
-  const credentials = await loadClientCredentials(appName);
-  if (credentials && credentials.clientId && credentials.clientSecret) {
+  if (credentials?.clientId && credentials?.clientSecret) {
     try {
-      const refreshed = await refreshClientToken(environment, appName, controllerUrl);
-      if (refreshed && refreshed.token) {
+      const refreshed = await refreshClientToken(environment, credentialApp, controllerUrl);
+      if (refreshed?.token) {
         return {
           type: 'client-token',
           token: refreshed.token,
@@ -334,7 +265,11 @@ async function getDeploymentAuth(controllerUrl, environment, appName) {
     }
   }
 
-  throw new Error(`No authentication method available. Run 'aifabrix login' for device token, or add credentials to ~/.aifabrix/secrets.local.yaml as '${appName}-client-idKeyVault' and '${appName}-client-secretKeyVault'`);
+  throw new Error(
+    'No authentication method available. For CI: set AIFABRIX_DEPLOYMENT_AUTH=client-credentials and ' +
+      `MISO_CLIENTID/MISO_CLIENTSECRET in .env or '${credentialApp}-client-idKeyVault' in secrets.local.yaml. ` +
+      'For interactive use: aifabrix login'
+  );
 }
 
 /**
@@ -451,19 +386,63 @@ async function getDeviceOnlyAuth(controllerUrl) {
 }
 
 /**
- * Ensures auth config has a Bearer token for Dataplane pipeline endpoints.
- * Dataplane pipeline (upload, validate, publish, test) accepts OAuth2 (Bearer) or API_KEY only;
- * client id/secret are rejected. Call this before invoking pipeline API functions.
+ * Ensures auth config has a token Dataplane pipeline endpoints accept (Bearer or x-client-token).
+ * Dataplane pipeline rejects raw client id/secret; use POST /api/v1/auth/token first.
+ * When {@link process.env.AIFABRIX_DEPLOYMENT_AUTH} is `client-credentials`, keep application
+ * `x-client-token` auth (do not substitute API_KEY).
  * @param {Object} authConfig - Authentication configuration (may have token, clientId, clientSecret)
  * @throws {Error} If authConfig has only client id/secret (no token)
  */
+/**
+ * Lab bypass: records/search accepts Bearer API_KEY but rejects x-client-token on some stacks.
+ * @param {Object} authConfig
+ * @returns {Object}
+ */
+function applyLabDataplaneApiKeyBearer(authConfig) {
+  const labKey = process.env.AIFABRIX_DATAPLANE_API_KEY || '';
+  if (!labKey) {
+    return authConfig;
+  }
+  authConfig.type = 'bearer';
+  authConfig.token = String(labKey);
+  return authConfig;
+}
+
 function requireBearerForDataplanePipeline(authConfig) {
+  if (authConfig.type === 'client-token' && authConfig.token) {
+    return;
+  }
+
+  const preferAppClientToken =
+    String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
+
+  if (!preferAppClientToken && process.env.API_KEY) {
+    const apiKey = String(process.env.API_KEY);
+    if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {
+      authConfig.token = apiKey;
+      return;
+    }
+    if (authConfig.type === 'client-token') {
+      authConfig.type = 'bearer';
+      authConfig.token = apiKey;
+      return;
+    }
+  }
+
   if (authConfig.token) {
     return;
   }
+
+  if (!preferAppClientToken && process.env.API_KEY) {
+    authConfig.type = 'bearer';
+    authConfig.token = String(process.env.API_KEY);
+    return;
+  }
+
   if (authConfig.clientId || authConfig.clientSecret) {
     throw new Error(
-      'Dataplane pipeline endpoints require OAuth2 (Bearer token). Client id/secret are not accepted. Run "aifabrix login" to authenticate, then retry.'
+      'Dataplane pipeline endpoints require OAuth2 (Bearer token) or x-client-token. ' +
+        'Client id/secret are not accepted. Run "aifabrix login" to authenticate, then retry.'
     );
   }
 }
@@ -477,6 +456,7 @@ module.exports = {
   refreshClientToken,
   refreshDeviceToken,
   loadClientCredentials,
+  resolveCredentialAppForDeployment,
   getOrRefreshClientToken,
   getOrRefreshDeviceToken,
   forceRefreshDeviceToken,
@@ -484,5 +464,6 @@ module.exports = {
   getDeviceOnlyAuth,
   extractClientCredentials,
   requireBearerForDataplanePipeline,
+  applyLabDataplaneApiKeyBearer,
   validateDataplaneSecrets
 };

package/lib/utils/upload-pipeline-ui.js

@@ -16,6 +16,9 @@ const { formatProgress } = require('./cli-test-layout-chalk');
  * @returns {boolean}
  */
 function shouldShowUploadPipelineProgress(options = {}) {
+  if (options.suppressPipelineSpinner === true) {
+    return false;
+  }
   return options.json !== true;
 }
 
@@ -35,17 +38,21 @@ function shouldUseUploadPipelineSpinner(options = {}) {
  * @param {string} systemKey
  * @returns {string}
  */
-function buildUploadPipelineSpinnerLabel(systemKey) {
+function buildUploadPipelineSpinnerLabel(systemKey, opts = {}) {
+  if (opts.syncMode === true) {
+    return 'Checking config on dataplane…';
+  }
   const key = systemKey && String(systemKey).trim() ? String(systemKey).trim() : 'integration';
   return `Publishing ${key} to dataplane…`;
 }
 
 /**
  * @param {string} systemKey
+ * @param {Object} [opts]
  * @returns {string}
  */
-function buildUploadPipelineProgressText(systemKey) {
-  return formatProgress(buildUploadPipelineSpinnerLabel(systemKey));
+function buildUploadPipelineProgressText(systemKey, opts = {}) {
+  return formatProgress(buildUploadPipelineSpinnerLabel(systemKey, opts));
 }
 
 /**
@@ -64,12 +71,12 @@ async function runWithUploadPipelineSpinner(work, opts = {}) {
   }
 
   if (!shouldUseUploadPipelineSpinner(opts)) {
-    logger.log(buildUploadPipelineProgressText(opts.systemKey));
+    logger.log(buildUploadPipelineProgressText(opts.systemKey, opts));
     return work();
   }
 
   const ora = require('ora');
-  const label = buildUploadPipelineSpinnerLabel(opts.systemKey);
+  const label = buildUploadPipelineSpinnerLabel(opts.systemKey, opts);
   const spinner = ora({
     text: chalk.white(label),
     spinner: 'dots'

package/lib/utils/upload-sync-options.js

@@ -0,0 +1,42 @@
+/**
+ * Build options for `uploadExternalSystem` on test-command --sync paths.
+ *
+ * @fileoverview Minimal upload sync options (force, verbose)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} [options] - CLI options from test / sync callers
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true }}
+ */
+function buildMinimalUploadSyncOptions(options = {}) {
+  const out = {
+    minimal: true,
+    // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
+    verbose: false,
+    silentResolve: true,
+    syncMode: true,
+    suppressPipelineSpinner: options.suppressPipelineSpinner === true
+  };
+  if (options.force === true) {
+    out.force = true;
+  }
+  return out;
+}
+
+/**
+ * Minimal sync paths (verify-*, test --sync) always suppress upload sidecar chatter.
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function isQuietMinimalSync(options = {}) {
+  return options.minimal === true || options.syncMode === true;
+}
+
+module.exports = {
+  buildMinimalUploadSyncOptions,
+  isQuietMinimalSync
+};

package/lib/utils/url-declarative-public-base.js

@@ -51,6 +51,12 @@ function hostPortForProfile(profile, listenPort, developerIdNum) {
     : localHostPort(listenPort, developerIdNum);
 }
 
+function localhostFrontDoorBaseForMissingRemote(opts) {
+  const { profile, developerIdNum } = opts || {};
+  const port = hostPortForProfile(profile, 3000, developerIdNum);
+  return `http://localhost:${port}`.replace(/\/+$/, '');
+}
+
 /**
  * Scheme for `declarativePublicUrlsUseLocalhost` bases: always **http** for loopback reachability
  * (ignore `tlsEnabled` / `remote-server` https — localhost URLs are not served with TLS in dev).
@@ -155,14 +161,26 @@ function templateUsesRemoteHostPlaceholder(hostTemplate) {
  * @returns {string|null}
  */
 function buildTraefikPublicBaseIfApplicable(opts) {
-  const { traefik, pathActive, hostTemplate, developerIdRaw, remoteServer, infraTlsEnabled } =
-    opts;
+  const {
+    traefik,
+    pathActive,
+    hostTemplate,
+    developerIdRaw,
+    remoteServer,
+    infraTlsEnabled,
+    profile,
+    developerIdNum
+  } = opts;
   // Plan 124: Traefik host authority only when pathActive (traefik ∧ frontDoorRouting.enabled)
   if (!traefik || !pathActive || !hostTemplate || !String(hostTemplate).trim()) {
     return null;
   }
   if (templateUsesRemoteHostPlaceholder(hostTemplate) && !String(remoteServer || '').trim()) {
-    return null;
+    // Local full-platform (no remote domain): use the single localhost front door port (3000 + devId×100).
+    return localhostFrontDoorBaseForMissingRemote({
+      profile,
+      developerIdNum
+    });
   }
   const expanded = expandFrontDoorHostTemplateForUrls(hostTemplate, {
     developerIdRaw,