@aifabrix/builder 2.53.1 → 2.55.0

package/lib/utils/credential-display.js

@@ -8,6 +8,7 @@
  */
 
 const chalk = require('chalk');
+const { formatCredentialShowLine } = require('./authentication-slot-show');
 
 /** @type {{ verified: string, pending: string, failed: string, expired: string }} */
 const STATUS_ICONS = {
@@ -74,10 +75,51 @@ function formatCredentialWithStatus(credential) {
   return { key, name, statusFormatted, statusLabel };
 }
 
+/**
+ * @param {unknown[]} values
+ * @returns {string|null}
+ */
+function firstNonEmptyScalar(values) {
+  for (const value of values) {
+    if (typeof value === 'number') return String(value);
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+/**
+ * Identity from a dataplane credential id or ForeignKeyReference. Never `[object Object]`.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function formatCredentialIdentity(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value !== 'object') return String(value);
+  return firstNonEmptyScalar([
+    value.name,
+    value.displayName,
+    value.key,
+    value.id,
+    value.credentialKey,
+    value.credentialId
+  ]);
+}
+
+/**
+ * Scalar credential id/key for show output. Objects must not print as [object Object].
+ * @param {unknown} value
+ * @returns {string}
+ */
+function formatCredentialIdValue(value) {
+  return formatCredentialIdentity(value) || '—';
+}
+
 module.exports = {
   STATUS_ICONS,
   STATUS_LABELS,
   STATUS_CHALK,
   formatCredentialStatus,
-  formatCredentialWithStatus
+  formatCredentialWithStatus,
+  formatCredentialIdValue,
+  formatCredentialShowLine
 };

package/lib/utils/credential-secrets-env.js

@@ -262,8 +262,13 @@ async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
   buildItemsFromPayload(payload, secrets, itemsByKey);
   reconcileBearerTokenSecretPaths(itemsByKey, appName, authConfig);
 
+  const excluded = new Set(
+    Array.isArray(options.excludeKeys)
+      ? options.excludeKeys.map((key) => String(key).trim()).filter(Boolean)
+      : []
+  );
   const items = Array.from(itemsByKey.entries())
-    .filter(([k]) => isValidKvPath(k))
+    .filter(([k]) => isValidKvPath(k) && !excluded.has(k))
     .map(([key, value]) => ({ key, value }));
 
   if (items.length === 0) return { pushed: 0, skipped: true };

package/lib/utils/env-copy.js

@@ -20,7 +20,7 @@ const devConfig = require('../utils/dev-config');
 const { rewriteInfraEndpoints } = require('./env-endpoints');
 const { buildEnvVarMap } = require('./env-map');
 const { interpolateEnvVars } = require('./secrets-helpers');
-const { getLocalPort } = require('./port-resolver');
+const { getLocalPort, isExternalAppDoc } = require('./port-resolver');
 const { applyHostLocalKeycloakInternalUrl } = require('./env-copy-keycloak');
 
 /**
@@ -263,6 +263,21 @@ function extractEnvVarsFromContent(envContent, envVars) {
   return envVars;
 }
 
+/**
+ * Patch Connected System env for local resolve (infra hosts only; no listen PORT).
+ * @async
+ * @param {string} envContent - Original env content
+ * @returns {Promise<string>} Patched env content
+ */
+async function patchExternalEnvContentForLocal(envContent) {
+  const devIdNum = readDeveloperIdFromConfig(config) || 0;
+  const infraPorts = devConfig.getDevPorts(devIdNum);
+  const updated = await rewriteInfraEndpoints(envContent, 'local', infraPorts);
+  const envVars = await buildEnvVarMap('local', null, devIdNum);
+  const updatedEnvVars = extractEnvVarsFromContent(updated, envVars);
+  return interpolateEnvVars(updated, updatedEnvVars);
+}
+
 /**
  * Patch env content for local development
  * @async
@@ -271,21 +286,18 @@ function extractEnvVarsFromContent(envContent, envVars) {
  * @returns {Promise<string>} Patched env content
  */
 async function patchEnvContentForLocal(envContent, variables) {
+  if (isExternalAppDoc(variables)) {
+    return patchExternalEnvContentForLocal(envContent);
+  }
   const baseAppPort = getLocalPort(variables, 3000);
   const appPort = calculateDevAppPort(baseAppPort);
   const devIdNum = readDeveloperIdFromConfig(config) || 0;
   const infraPorts = devConfig.getDevPorts(devIdNum);
 
-  // Update PORT
   envContent = updatePortInEnv(envContent, appPort);
-
-  // Update localhost URLs
   envContent = updateLocalhostUrls(envContent, baseAppPort, appPort);
-
-  // Rewrite infra endpoints
   envContent = await rewriteInfraEndpoints(envContent, 'local', infraPorts);
 
-  // Interpolate ${VAR} references
   const envVars = await buildEnvVarMap('local', null, devIdNum);
   const updatedEnvVars = extractEnvVarsFromContent(envContent, envVars);
   envContent = interpolateEnvVars(envContent, updatedEnvVars);

package/lib/utils/external-env-template.js

@@ -52,9 +52,17 @@ const FALLBACK_SECURITY_BY_AUTH = {
   hmac: ['signingSecret'],
   bearer: ['bearerToken'],
   token: ['bearerToken'],
-  none: []
+  none: [],
+  system: []
 };
 
+const NO_SECRET_AUTH_TYPES = new Set(['none', 'apiProvider', 'system']);
+
+function isNoSecretAuthType(authBlock) {
+  const authType = authBlock && typeof authBlock.authType === 'string' ? authBlock.authType.trim() : '';
+  return NO_SECRET_AUTH_TYPES.has(authType);
+}
+
 /**
  * @param {Array<{name: string, value: string}>} authSecureVars
  * @param {Record<string, unknown>} security
@@ -96,7 +104,7 @@ function buildAuthSecureVarsFromSystem(system) {
   const prefix = systemKeyToKvPrefix(systemKey);
   if (!prefix) return authSecureVars;
   const authBlock = system?.authentication || system?.auth;
-  if (authBlock?.authType === 'apiProvider' || authBlock?.authType === 'none') {
+  if (isNoSecretAuthType(authBlock)) {
     return authSecureVars;
   }
   const credential = getAuthCredentialTemplate(authBlock);
@@ -147,6 +155,8 @@ function buildExternalEnvTemplateContext(system) {
     authMethod = 'apiprovider';
   } else if (authBlock?.authType === 'none') {
     authMethod = 'none';
+  } else if (authBlock?.authType === 'system') {
+    authMethod = 'system';
   } else {
     authMethod = (
       credential?.method ||
@@ -155,6 +165,14 @@ function buildExternalEnvTemplateContext(system) {
       'apikey'
     ).toLowerCase();
   }
+  if (isNoSecretAuthType(authBlock)) {
+    return {
+      authMethod,
+      authSecureVars: [],
+      authNonSecureVarNames: [],
+      configuration: buildConfigurationEntries(system)
+    };
+  }
   const slotSecureVars = buildAuthSecureVarsFromAllSlots(system);
   const authSecureVars =
     slotSecureVars.length > 0 ? slotSecureVars : buildAuthSecureVarsFromSystem(system);

package/lib/utils/external-system-readiness-compact-blocks.js

@@ -75,7 +75,11 @@ function logUploadReadinessSummaryCompact(ctx) {
   const genMcp = publication?.generateMcpContract !== false;
   const tierA = summarizeDatasourceTiersA(publication?.datasources || [], genMcp);
   const systemCfg = manifest?.system || {};
-  const statusLabel = resolveConnectedSystemStatus({ publication });
+  const statusLabel = resolveConnectedSystemStatus({
+    command: 'upload',
+    publication,
+    systemFromDataplane: ctx.systemFromDataplane
+  });
 
   logCompactHeader({ command: 'upload', systemKey, environment, dataplaneUrl });
   if (forcePublish) {

package/lib/utils/external-system-readiness-compact-display.js

@@ -29,12 +29,33 @@ const PILLAR_LABELS = Object.freeze({
   governance: 'Governance'
 });
 
+/** Connected System lifecycle labels — same Draft / Published / Archived as the web. */
+const CONNECTED_SYSTEM_LIFECYCLE_LABELS = Object.freeze({
+  draft: 'Draft',
+  published: 'Published',
+  archived: 'Archived',
+  deployed: 'Published'
+});
+
+/**
+ * Product lifecycle label, or null when the value is not Draft/Published/Archived
+ * (controller `active` is not Published).
+ * @param {string|null|undefined} status
+ * @returns {string|null}
+ */
+function formatConnectedSystemLifecycleLabel(status) {
+  const raw = String(status || '').trim().toLowerCase();
+  return CONNECTED_SYSTEM_LIFECYCLE_LABELS[raw] || null;
+}
+
 /**
  * @param {string|null|undefined} status
  * @returns {string}
  */
 function formatLifecycleLabel(status) {
   const raw = String(status || 'unknown').trim().toLowerCase();
+  const lifecycle = formatConnectedSystemLifecycleLabel(raw);
+  if (lifecycle) return lifecycle;
   if (!raw || raw === 'unknown') return 'Unknown';
   return raw.charAt(0).toUpperCase() + raw.slice(1);
 }
@@ -159,8 +180,14 @@ function resolveManifestAuthMethod(systemCfg) {
  * @returns {string}
  */
 function resolveConnectedSystemStatus(opts = {}) {
-  const fromPub = opts.publication?.system?.status;
   const fromGet = opts.systemFromDataplane?.status;
+  if (fromGet) {
+    return formatLifecycleLabel(fromGet);
+  }
+  if (opts.command === 'upload') {
+    return formatLifecycleLabel('draft');
+  }
+  const fromPub = opts.publication?.system?.status;
   return formatLifecycleLabel(fromGet || fromPub || opts.status);
 }
 
@@ -307,6 +334,8 @@ function logCompactTip(opts) {
 
 module.exports = {
   PILLAR_LABELS,
+  CONNECTED_SYSTEM_LIFECYCLE_LABELS,
+  formatConnectedSystemLifecycleLabel,
   formatLifecycleLabel,
   truncateKeyList,
   formatCredentialPushLine,

package/lib/utils/external-system-validators.js

@@ -52,7 +52,8 @@ function validateFieldMappingExpression(expression) {
     'replace',
     'join',
     'split',
-    'normalizeWhitespace'
+    'normalizeWhitespace',
+    'index'
   ];
   for (const trans of transformations) {
     const transName = trans.split('(')[0].trim();

package/lib/utils/help-builder.js

@@ -80,6 +80,7 @@ const CATEGORIES = [
       { name: 'resource-type' },
       { name: 'role' },
       { name: 'role-assistant' },
+      { name: 'search' },
       { name: 'evidence-kind' },
       { name: 'enterprise-knowledge' },
       { name: 'identity' },
@@ -133,7 +134,8 @@ const CATEGORIES = [
       { name: 'dev' },
       { name: 'secret' },
       { name: 'npm', term: 'npm config' },
-      { name: 'secure' }
+      { name: 'secure' },
+      { name: 'agent-kit' }
     ]
   }
 ];

package/lib/utils/paths.js

@@ -842,12 +842,25 @@ function resolveExistingWorkspacePath(appName, options) {
   return null;
 }
 
+function platformShellWorkspaceWithoutConfig(appPath, baseDir) {
+  if (!isExistingAppDirectory(appPath)) {
+    return null;
+  }
+  if (baseDir === 'role-assistant' || baseDir === 'enterprise-knowledge') {
+    return externalIntegrationFolderResult(appPath, baseDir);
+  }
+  return null;
+}
+
 function externalWorkspaceFolderFromConfig(appPath, baseDir, scopedWorkspace) {
   try {
     const configPath = resolveApplicationConfigPath(appPath);
     const variables = loadConfigFile(configPath);
     if (!variables) {
-      return null;
+      return platformShellWorkspaceWithoutConfig(appPath, baseDir);
+    }
+    if (baseDir === 'role-assistant' || baseDir === 'enterprise-knowledge') {
+      return externalIntegrationFolderResult(appPath, baseDir);
     }
     const isExternal = isExternalAppType(variables);
     return {
@@ -857,6 +870,10 @@ function externalWorkspaceFolderFromConfig(appPath, baseDir, scopedWorkspace) {
       baseDir
     };
   } catch {
+    const platformShell = platformShellWorkspaceWithoutConfig(appPath, baseDir);
+    if (platformShell) {
+      return platformShell;
+    }
     if (scopedWorkspace && isExistingAppDirectory(appPath)) {
       return externalIntegrationFolderResult(appPath, baseDir);
     }

package/lib/utils/platform-shell-package.js

@@ -0,0 +1,69 @@
+/**
+ * digitalWorker / enterpriseKnowledge packages are platform shells, not Connected Systems.
+ *
+ * @fileoverview Kind and workspace helpers for Role Assistant and Enterprise Knowledge
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { SYSTEM_KIND_DIGITAL_WORKER, WORKSPACE_ROLE_ASSISTANT } = require('./role-assistant-paths');
+const {
+  SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  WORKSPACE_ENTERPRISE_KNOWLEDGE
+} = require('./enterprise-knowledge-paths');
+
+function readSystemKind(application) {
+  if (!application || typeof application !== 'object') {
+    return '';
+  }
+  const kind = application.systemKind || application.systemKindKey;
+  return typeof kind === 'string' ? kind.trim() : '';
+}
+
+function isDigitalWorkerKind(application) {
+  return readSystemKind(application) === SYSTEM_KIND_DIGITAL_WORKER;
+}
+
+function isEnterpriseKnowledgeKind(application) {
+  return readSystemKind(application) === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE;
+}
+
+function isPlatformShellKind(application) {
+  return isDigitalWorkerKind(application) || isEnterpriseKnowledgeKind(application);
+}
+
+function isRoleAssistantWorkspace(baseDir) {
+  return String(baseDir || '').trim() === WORKSPACE_ROLE_ASSISTANT;
+}
+
+function isEnterpriseKnowledgeWorkspace(baseDir) {
+  return String(baseDir || '').trim() === WORKSPACE_ENTERPRISE_KNOWLEDGE;
+}
+
+function isPlatformShellWorkspace(baseDir) {
+  return isRoleAssistantWorkspace(baseDir) || isEnterpriseKnowledgeWorkspace(baseDir);
+}
+
+function throwIfPlatformShellHasNoDeployJson(appName, baseDir) {
+  if (!isPlatformShellWorkspace(baseDir)) {
+    return;
+  }
+  throw new Error(
+    `'${appName}' is a Role Assistant or Enterprise Knowledge package and does not use ` +
+      'application.yaml or deployment JSON. Publish settings and Evidence with: ' +
+      `aifabrix upload ${appName} --env <dev|tst|pro>`
+  );
+}
+
+module.exports = {
+  readSystemKind,
+  isDigitalWorkerKind,
+  isEnterpriseKnowledgeKind,
+  isPlatformShellKind,
+  isRoleAssistantWorkspace,
+  isEnterpriseKnowledgeWorkspace,
+  isPlatformShellWorkspace,
+  throwIfPlatformShellHasNoDeployJson
+};

package/lib/utils/port-resolver.js

@@ -101,10 +101,59 @@ function getLocalPortFromPath(variablesPath) {
   return (p !== undefined && p !== null) ? p : null;
 }
 
+/**
+ * Connected Systems (`app.type: external`) have no HTTP listen port.
+ * @param {Object|null|undefined} variables - Parsed application config
+ * @returns {boolean}
+ */
+function isExternalAppDoc(variables) {
+  return Boolean(variables && variables.app && variables.app.type === 'external');
+}
+
+/**
+ * @param {string|null|undefined} variablesPath - Path to application config
+ * @returns {boolean}
+ */
+function isExternalAppPath(variablesPath) {
+  return isExternalAppDoc(loadVariablesFromPath(variablesPath));
+}
+
+/**
+ * Drop PORT assignments from resolved .env content (Connected Systems).
+ * @param {string} envContent
+ * @returns {string}
+ */
+function stripListenPortEnvLines(envContent) {
+  if (!envContent || typeof envContent !== 'string') {
+    return envContent;
+  }
+  return envContent
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*PORT\s*=/.test(line))
+    .join('\n');
+}
+
+/**
+ * Set or append PORT for builder apps that listen on HTTP.
+ * @param {string} envContent
+ * @param {number} appPort
+ * @returns {string}
+ */
+function assignListenPortEnvLine(envContent, appPort) {
+  if (/^PORT\s*=.*$/m.test(envContent)) {
+    return envContent.replace(/^PORT\s*=\s*.*$/m, `PORT=${appPort}`);
+  }
+  return `${envContent}\nPORT=${appPort}\n`;
+}
+
 module.exports = {
   getContainerPort,
   getLocalPort,
   getContainerPortFromPath,
   getLocalPortFromPath,
-  loadVariablesFromPath
+  loadVariablesFromPath,
+  isExternalAppDoc,
+  isExternalAppPath,
+  stripListenPortEnvLines,
+  assignListenPortEnvLine
 };

package/lib/utils/rewrite-name-flag.js

@@ -0,0 +1,20 @@
+/**
+ * Treat clustered -name as the long --name option so quoted names with spaces work.
+ *
+ * @fileoverview Commander parses -name as -n plus leftover letters
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function rewriteClusteredNameFlag(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  return args.map((arg) => (arg === '-name' ? '--name' : arg));
+}
+
+module.exports = { rewriteClusteredNameFlag };

package/lib/utils/role-assistant-paths.js

@@ -121,30 +121,33 @@ function firstExistingUnderRoot(disk, root, folderNames) {
 }
 
 /**
- * Resolves role-assistant/ra-{roleKey} (preferred) or legacy bare folder.
- * @param {string} roleKey
+ * Resolves role-assistant/<systemKey> by exact folder name.
+ * Does not map a connected-system key onto an ra- package.
+ * @param {string} systemKey
  * @returns {string}
  */
-function getRoleAssistantPath(roleKey) {
-  if (!roleKey || typeof roleKey !== 'string') {
+function getRoleAssistantPath(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('Role key is required and must be a string');
+  }
+  const folderName = systemKey.trim();
+  if (!folderName) {
     throw new Error('Role key is required and must be a string');
   }
   const disk = nodeFs();
-  const folders = roleAssistantFolderCandidates(roleKey);
-  const preferred = roleAssistantSystemKey(roleKey);
   const cwdRoot = getCwdRoleAssistantRoot();
   const matRoot = path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT);
 
   const existing =
-    firstExistingUnderRoot(disk, cwdRoot, folders) ||
-    firstExistingUnderRoot(disk, matRoot, folders);
+    firstExistingUnderRoot(disk, cwdRoot, [folderName]) ||
+    firstExistingUnderRoot(disk, matRoot, [folderName]);
   if (existing) {
     return existing;
   }
   if (cwdRoot) {
-    return path.join(cwdRoot, preferred);
+    return path.join(cwdRoot, folderName);
   }
-  return path.join(matRoot, preferred);
+  return path.join(matRoot, folderName);
 }
 
 module.exports = {

package/lib/utils/schema-loader.js

@@ -19,6 +19,7 @@ const addFormats = require('ajv-formats');
 let externalSystemValidator = null;
 let externalDataSourceValidator = null;
 let roleAssistantSettingsValidator = null;
+let roleAssistantTestCaseValidator = null;
 
 /**
  * Reset validators cache (for testing)
@@ -28,6 +29,7 @@ function resetValidators() {
   externalSystemValidator = null;
   externalDataSourceValidator = null;
   roleAssistantSettingsValidator = null;
+  roleAssistantTestCaseValidator = null;
 }
 
 /**
@@ -172,6 +174,37 @@ function loadRoleAssistantSettingsSchema() {
   return roleAssistantSettingsValidator;
 }
 
+/**
+ * Loads and compiles role-assistant test-case schema.
+ * @function loadRoleAssistantTestCaseSchema
+ * @returns {Function}
+ */
+function loadRoleAssistantTestCaseSchema() {
+  if (roleAssistantTestCaseValidator) {
+    return roleAssistantTestCaseValidator;
+  }
+
+  const schemaPath = path.join(__dirname, '..', 'schema', 'role-assistant-test-case.schema.json');
+  let schema;
+  try {
+    schema = JSON.parse(fsRealSync.readFileSync(schemaPath, 'utf8'));
+  } catch (error) {
+    try {
+      schema = require('../schema/role-assistant-test-case.schema.json');
+    } catch {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`Role assistant test-case schema not found: ${schemaPath}`);
+      }
+      throw new Error(`Invalid JSON in role-assistant-test-case.schema.json: ${error.message}`);
+    }
+  }
+
+  const ajv = new Ajv({ allErrors: true, verbose: true, strict: false, strictSchema: false });
+  addFormats(ajv);
+  roleAssistantTestCaseValidator = ajv.compile(schema);
+  return roleAssistantTestCaseValidator;
+}
+
 /**
  * Detect schema type from $id field
  * @param {Object} parsed - Parsed JSON object
@@ -194,6 +227,9 @@ function detectFromId(parsed) {
   if (parsed.$id.includes('role-assistant-settings')) {
     return 'role-assistant-settings';
   }
+  if (parsed.$id.includes('role-assistant-test-case')) {
+    return 'role-assistant-test-case';
+  }
 
   return null;
 }
@@ -388,6 +424,7 @@ module.exports = {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
   loadRoleAssistantSettingsSchema,
+  loadRoleAssistantTestCaseSchema,
   registerExternalDatasourceAjvDependencies,
   detectSchemaType,
   detectSchemaTypeFromParsed,

package/lib/utils/schema-resolver.js

@@ -14,6 +14,10 @@ const path = require('path');
 const { detectAppType } = require('./paths');
 const { resolveApplicationConfigPath } = require('./app-config-resolver');
 const { loadConfigFile } = require('./config-format');
+const {
+  isRoleAssistantWorkspace,
+  isEnterpriseKnowledgeWorkspace
+} = require('./platform-shell-package');
 
 /**
  * Resolves schemaBasePath from application config
@@ -314,7 +318,13 @@ async function resolveExternalFiles(appName, options = {}) {
     throw new Error('App name is required and must be a string');
   }
 
-  const { appPath } = await detectAppType(appName, options);
+  const { appPath, baseDir } = await detectAppType(appName, options);
+  if (isEnterpriseKnowledgeWorkspace(baseDir)) {
+    return [];
+  }
+  if (isRoleAssistantWorkspace(baseDir)) {
+    return [resolveRoleAssistantSettingsFile(appPath)];
+  }
   const variables = await loadAndValidateVariables(appPath);
 
   if (!variables.externalIntegration) {

package/lib/utils/secrets-helpers.js

@@ -17,7 +17,7 @@ const { rewriteInfraEndpoints, getEnvHosts, getServicePort, getServiceHost, getL
 const { loadEnvConfig } = require('./env-config-loader');
 const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
-const { getLocalPortFromPath } = require('./port-resolver');
+const { getLocalPortFromPath, isExternalAppPath, assignListenPortEnvLine } = require('./port-resolver');
 const { readYamlAtPath, applyCanonicalSecretsOverride } = require('./secrets-canonical');
 const { collectUniqueKvPathStrings, isCommentOrEmptyLine, activeEnvLineForKvScan, envLineWithoutInlineComment } = require('./secrets-kv-refs');
 
@@ -407,20 +407,6 @@ async function getLocalEnvWithOverrides() {
   return localEnv;
 }
 
-/**
- * Updates PORT variable in content
- * @function updatePortVariable
- * @param {string} envContent - Environment content
- * @param {number} appPort - Application port
- * @returns {string} Updated content
- */
-function updatePortVariable(envContent, appPort) {
-  if (/^PORT\s*=.*$/m.test(envContent)) {
-    return envContent.replace(/^PORT\s*=\s*.*$/m, `PORT=${appPort}`);
-  }
-  return `${envContent}\nPORT=${appPort}\n`;
-}
-
 /**
  * Builds environment variables for interpolation
  * @async
@@ -446,6 +432,7 @@ async function buildEnvVarsForInterpolation(devIdNum) {
 }
 
 async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
+  const skipListenPort = isExternalAppPath(variablesPath);
   const devIdNum = await getDeveloperIdNumber();
   const localEnv = await getLocalEnvWithOverrides();
   const { localHostPort } = require('./declarative-url-ports');
@@ -453,15 +440,19 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   const baseListen = await resolveManifestListenPort(variablesPath, localEnv, envContent);
   const appPort = localHostPort(baseListen, devIdNum);
 
-  let updated = updatePortVariable(envContent, appPort);
-  updated = updateLocalhostUrls(updated, baseListen, appPort);
+  let updated = skipListenPort ? envContent : assignListenPortEnvLine(envContent, appPort);
+  if (!skipListenPort) {
+    updated = updateLocalhostUrls(updated, baseListen, appPort);
+  }
   updated = await rewriteInfraEndpoints(updated, 'local');
 
   const envVars = await buildEnvVarsForInterpolation(devIdNum);
-  envVars.PORT = String(appPort);
-  const portVar = getPortVarFromEnvTemplatePath(variablesPath);
-  if (portVar) {
-    envVars[portVar] = String(appPort);
+  if (!skipListenPort) {
+    envVars.PORT = String(appPort);
+    const portVar = getPortVarFromEnvTemplatePath(variablesPath);
+    if (portVar) {
+      envVars[portVar] = String(appPort);
+    }
   }
   updated = interpolateEnvVars(updated, envVars);