@aifabrix/builder 2.40.2 → 2.41.0

package/lib/utils/paths.js

@@ -158,14 +158,8 @@ function getFallbackProjectRoot() {
   return path.resolve(__dirname, '..', '..');
 }
 
-/**
- * Gets the project root directory by finding package.json
- * Works reliably in all environments including Jest tests and CI
- * @returns {string} Absolute path to project root
- */
 /**
  * Checks if global PROJECT_ROOT is valid
- * @function checkGlobalProjectRoot
  * @returns {string|null} Valid global root or null
  */
 function checkGlobalProjectRoot() {
@@ -195,39 +189,29 @@ function checkGlobalProjectRoot() {
 
 /**
  * Tries different strategies to find project root
- * @function tryFindProjectRoot
  * @returns {string} Found project root
  */
 function tryFindProjectRoot() {
-  // Strategy 1: Check global.PROJECT_ROOT
   const globalRoot = checkGlobalProjectRoot();
   if (globalRoot) {
     cachedProjectRoot = globalRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 2: Walk up from __dirname
   const foundRoot = findProjectRootByWalkingUp(__dirname);
   if (foundRoot && hasPackageJson(foundRoot)) {
     cachedProjectRoot = foundRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 3: Try process.cwd()
   const cwdRoot = findProjectRootFromCwd();
   if (cwdRoot && hasPackageJson(cwdRoot)) {
     cachedProjectRoot = cwdRoot;
     return cachedProjectRoot;
   }
-
-  // Strategy 4: Fallback
   const fallbackRoot = getFallbackProjectRoot();
   if (hasPackageJson(fallbackRoot)) {
     cachedProjectRoot = fallbackRoot;
     return cachedProjectRoot;
   }
-
-  // Last resort
   cachedProjectRoot = fallbackRoot;
   return cachedProjectRoot;
 }
@@ -242,10 +226,7 @@ function getProjectRoot() {
 }
 
 /**
- * Returns the applications base directory for a developer.
- * Dev 0: <home>/applications
- * Dev > 0: <home>/applications-dev-{id}
- *
+ * Returns the applications base directory. Dev 0: <home>/applications; Dev > 0: <home>/applications-dev-{id}
  * @param {number|string} developerId - Developer ID
  * @returns {string} Absolute path to applications base directory
  */
@@ -259,19 +240,13 @@ function getApplicationsBaseDir(developerId) {
 }
 
 /**
- * Returns the developer-specific application directory.
- * Dev 0: points to applications/ (root)
- * Dev > 0: <home>/applications-dev-{id} (root)
- *
+ * Returns the developer-specific application directory. Dev 0: applications/; Dev > 0: applications-dev-{id}
  * @param {string} appName - Application name
  * @param {number|string} developerId - Developer ID
- * @returns {string} Absolute path to developer-specific app directory
+ * @returns {string} Developer-specific app directory (root)
  */
 function getDevDirectory(appName, developerId) {
   const baseDir = getApplicationsBaseDir(developerId);
-  // All files should be generated at the root of the applications folder
-  // Dev 0: <home>/applications
-  // Dev > 0: <home>/applications-dev-{id}
   return baseDir;
 }
 
@@ -292,7 +267,6 @@ function getAppPath(appName, appType) {
 
 /**
  * Base directory for integration/builder: project root when cwd is inside project, else cwd.
- * So deploy works when run from integration/<app> (e.g. node deploy.js), and tests using temp dirs still work.
  * @returns {string} Directory to resolve integration/ and builder/ from
  */
 function getIntegrationBuilderBaseDir() {
@@ -307,7 +281,6 @@ function getIntegrationBuilderBaseDir() {
 
 /**
  * Gets the integration folder path for external systems.
- * Uses project root when cwd is inside project so deploy works when run from integration/<app> (e.g. node deploy.js).
  * @param {string} appName - Application name
  * @returns {string} Absolute path to integration directory
  */
@@ -320,9 +293,21 @@ function getIntegrationPath(appName) {
 }
 
 /**
- * Gets the builder folder path for regular applications.
- * When AIFABRIX_BUILDER_DIR is set (e.g. by up-miso/up-dataplane from config aifabrix-env-config),
- * uses that as builder root; otherwise uses project root so deploy works when run from integration/<app>.
+ * Resolves build.context from application.yaml to an absolute path.
+ * Used as the canonical app code directory for local mount and (when remote) Mutagen local path.
+ *
+ * @param {string} configDir - Directory containing the application config (e.g. builder/<appKey>/)
+ * @param {string} [buildContext='.'] - build.context value (relative to configDir)
+ * @returns {string} Absolute path to the app code directory
+ */
+function resolveBuildContext(configDir, buildContext) {
+  const dir = (configDir && typeof configDir === 'string') ? configDir : '';
+  const ctx = (buildContext && typeof buildContext === 'string') ? buildContext : '.';
+  return path.resolve(dir, ctx);
+}
+
+/**
+ * Gets the builder folder path. Uses AIFABRIX_BUILDER_DIR when set, else project root.
  * @param {string} appName - Application name
  * @returns {string} Absolute path to builder directory
  */
@@ -462,6 +447,29 @@ async function detectAppType(appName, _options = {}) {
   if (builderResult) return builderResult;
   throw new Error(`App '${appName}' not found in integration/${appName} or builder/${appName}`);
 }
+
+/**
+ * Resolve-specific app path: prefer integration + env.template only (env-only mode).
+ * If integration/<appName>/env.template exists, use that directory without requiring application.yaml.
+ * Otherwise fall back to detectAppType (integration or builder with full config).
+ *
+ * @param {string} appName - Application name
+ * @returns {Promise<{appPath: string, envOnly: boolean}>} appPath and envOnly (true when only env.template is used)
+ * @throws {Error} When app not found in integration or builder
+ */
+async function getResolveAppPath(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  const integrationPath = getIntegrationPath(appName);
+  const envTemplatePath = path.join(integrationPath, 'env.template');
+  if (fs.existsSync(integrationPath) && fs.existsSync(envTemplatePath)) {
+    return { appPath: integrationPath, envOnly: true };
+  }
+  const result = await detectAppType(appName);
+  return { appPath: result.appPath, envOnly: false };
+}
+
 module.exports = {
   getAifabrixHome,
   getConfigDirForPaths,
@@ -471,9 +479,11 @@ module.exports = {
   getProjectRoot,
   getIntegrationPath,
   getBuilderPath,
+  resolveBuildContext,
   getDeployJsonPath,
   resolveApplicationConfigPath,
   detectAppType,
+  getResolveAppPath,
   clearProjectRootCache
 };
 

package/lib/utils/port-resolver.js

@@ -5,7 +5,7 @@
  * Use getContainerPort for container/Docker/deployment/registration; use getLocalPort
  * for local .env and dev-id–adjusted host port.
  *
- * @fileoverview Port resolution from variables (port, build.containerPort, build.localPort)
+ * @fileoverview Port resolution from variables (port, build.containerPort)
  * @author AI Fabrix Team
  * @version 2.0.0
  */
@@ -17,8 +17,8 @@ const yaml = require('js-yaml');
 
 /**
  * Resolve container port from variables object.
- * Precedence: build.containerPort → port → defaultPort.
- * Used for: Dockerfile, container .env PORT, compose, deployment, app register, variable-transformer, builders, secrets-utils.
+ * Precedence: build.containerPort (if set and non-empty) → port (main port) → defaultPort.
+ * When containerPort is empty or missing, main port is used (e.g. keycloak 8082:8080 vs miso 3000:3000).
  *
  * @param {Object} variables - Parsed application config (or subset with build, port)
  * @param {number} [defaultPort=3000] - Default when neither build.containerPort nor port is set
@@ -26,13 +26,19 @@ const yaml = require('js-yaml');
  */
 function getContainerPort(variables, defaultPort = 3000) {
   const v = variables || {};
-  return v.build?.containerPort ?? v.port ?? defaultPort;
+  const containerPort = v.build?.containerPort;
+  const useMain = containerPort === undefined || containerPort === null ||
+    (typeof containerPort === 'string' && containerPort.trim() === '');
+  if (!useMain && typeof containerPort === 'number' && containerPort > 0) {
+    return containerPort;
+  }
+  return v.port ?? defaultPort;
 }
 
 /**
  * Resolve local (development) port from variables object.
- * Precedence: build.localPort (if number and > 0) → port → defaultPort.
- * Used for: env-copy, env-ports, and as base for getLocalPortFromPath (secrets-helpers).
+ * Precedence: build.localPort (when positive integer) → port → defaultPort.
+ * Used for env-copy, env-ports, getLocalPortFromPath, run compose host port.
  *
  * @param {Object} variables - Parsed application config
  * @param {number} [defaultPort=3000] - Default when neither build.localPort nor port is set
@@ -40,9 +46,9 @@ function getContainerPort(variables, defaultPort = 3000) {
  */
 function getLocalPort(variables, defaultPort = 3000) {
   const v = variables || {};
-  const local = v.build?.localPort;
-  if (typeof local === 'number' && local > 0) {
-    return local;
+  const localPort = v.build?.localPort;
+  if (typeof localPort === 'number' && localPort > 0) {
+    return localPort;
   }
   return v.port ?? defaultPort;
 }
@@ -67,7 +73,7 @@ function loadVariablesFromPath(variablesPath) {
 
 /**
  * Resolve container port from application config path.
- * Returns null when file is missing or neither build.containerPort nor port is set (for chaining with other sources).
+ * When containerPort is empty or missing, returns main port. Null only when file missing or no port set.
  *
  * @param {string} variablesPath - Path to application config
  * @returns {number|null} Container port or null
@@ -77,14 +83,20 @@ function getContainerPortFromPath(variablesPath) {
   if (!v) {
     return null;
   }
-  const p = v.build?.containerPort ?? v.port;
+  const containerPort = v.build?.containerPort;
+  const useMain = containerPort === undefined || containerPort === null ||
+    (typeof containerPort === 'string' && containerPort.trim() === '');
+  if (!useMain && typeof containerPort === 'number' && containerPort > 0) {
+    return containerPort;
+  }
+  const p = v.port;
   return (p !== undefined && p !== null) ? p : null;
 }
 
 /**
  * Resolve local port from application config path.
- * Matches legacy getPortFromVariablesFile: build.localPort (if number and > 0) else variables.port or null.
- * Returns null when file is missing or neither is set (for calculateAppPort chain).
+ * Same rule as getLocalPort: build.localPort (when positive integer) → port.
+ * Returns null when file is missing or neither localPort nor port is set.
  *
  * @param {string} variablesPath - Path to application config
  * @returns {number|null} Local port or null
@@ -94,9 +106,9 @@ function getLocalPortFromPath(variablesPath) {
   if (!v) {
     return null;
   }
-  const local = v.build?.localPort;
-  if (typeof local === 'number' && local > 0) {
-    return local;
+  const localPort = v.build?.localPort;
+  if (typeof localPort === 'number' && localPort > 0) {
+    return localPort;
   }
   const p = v.port;
   return (p !== undefined && p !== null) ? p : null;

package/lib/utils/remote-dev-auth.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Resolve Builder Server URL and client cert for cert-authenticated dev API calls
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const config = require('../core/config');
+const { getCertDir, readClientCertPem } = require('./dev-cert-helper');
+const { getConfigDirForPaths } = require('./paths');
+
+/**
+ * Check if a string is an http(s) URL (for aifabrix-secrets remote mode).
+ * @param {string} value - Config value
+ * @returns {boolean}
+ */
+function isRemoteSecretsUrl(value) {
+  return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+}
+
+/**
+ * Get Builder Server URL and client cert PEM when remote is configured; otherwise null.
+ * Use for cert-authenticated dev API calls (settings, users, ssh-keys, secrets).
+ * @returns {Promise<{ serverUrl: string, clientCertPem: string }|null>}
+ */
+async function getRemoteDevAuth() {
+  const serverUrl = await config.getRemoteServer();
+  if (!serverUrl) return null;
+  const devId = await config.getDeveloperId();
+  const certDir = getCertDir(getConfigDirForPaths(), devId);
+  const clientCertPem = readClientCertPem(certDir);
+  if (!clientCertPem) return null;
+  return { serverUrl, clientCertPem };
+}
+
+module.exports = {
+  isRemoteSecretsUrl,
+  getRemoteDevAuth
+};

package/lib/utils/remote-docker-env.js

@@ -0,0 +1,43 @@
+/**
+ * Remote Docker environment – DOCKER_HOST and TLS cert path when docker-endpoint is set.
+ *
+ * @fileoverview Env overlay for Docker CLI when using remote Builder Server
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const config = require('../core/config');
+const { getCertDir } = require('./dev-cert-helper');
+const { getConfigDirForPaths } = require('./paths');
+
+/**
+ * If remote Docker is configured (docker-endpoint + cert.pem, key.pem, and ca.pem present),
+ * returns env vars for Docker CLI: DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.
+ * Docker requires ca.pem in DOCKER_CERT_PATH for TLS; if it is missing we return {} so
+ * the CLI uses local Docker and avoids "open ca.pem: no such file or directory".
+ *
+ * @returns {Promise<Object>} Env overlay (may be empty)
+ */
+async function getRemoteDockerEnv() {
+  const endpoint = await config.getDockerEndpoint();
+  if (!endpoint || typeof endpoint !== 'string' || !endpoint.trim()) {
+    return {};
+  }
+  const devId = await config.getDeveloperId();
+  const certDir = getCertDir(getConfigDirForPaths(), devId);
+  const certPath = path.join(certDir, 'cert.pem');
+  const keyPath = path.join(certDir, 'key.pem');
+  const caPath = path.join(certDir, 'ca.pem');
+  const fs = require('fs');
+  if (!fs.existsSync(certPath) || !fs.existsSync(keyPath) || !fs.existsSync(caPath)) {
+    return {};
+  }
+  return {
+    DOCKER_HOST: endpoint.trim(),
+    DOCKER_TLS_VERIFY: '1',
+    DOCKER_CERT_PATH: certDir
+  };
+}
+
+module.exports = { getRemoteDockerEnv };

package/lib/utils/remote-secrets-loader.js

@@ -0,0 +1,60 @@
+/**
+ * Load shared secrets from Builder Server when aifabrix-secrets is an http(s) URL.
+ * Used for .env resolution only; values are never persisted to disk.
+ *
+ * @fileoverview Remote shared secrets loader for .env generation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const config = require('../core/config');
+
+/**
+ * Fetches shared secrets from Builder Server when aifabrix-secrets is an http(s) URL.
+ * @returns {Promise<Object|null>} Key-value secrets from API or null
+ */
+async function loadRemoteSharedSecrets() {
+  const { isRemoteSecretsUrl, getRemoteDevAuth } = require('./remote-dev-auth');
+  const devApi = require('../api/dev.api');
+  const configSecretsPath = await config.getSecretsPath();
+  if (!configSecretsPath || !isRemoteSecretsUrl(configSecretsPath)) {
+    return null;
+  }
+  const auth = await getRemoteDevAuth();
+  if (!auth) return null;
+  try {
+    const items = await devApi.listSecrets(auth.serverUrl, auth.clientCertPem);
+    if (!Array.isArray(items)) return null;
+    const obj = {};
+    for (const item of items) {
+      if (item && typeof item.name === 'string' && item.value !== undefined) {
+        obj[item.name] = String(item.value);
+      }
+    }
+    return obj;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merges remote shared secrets with user secrets. User wins on same key.
+ * @param {Object} userSecrets - User secrets object
+ * @param {Object} remoteSecrets - Remote API secrets (key-value)
+ * @returns {Object} Merged object
+ */
+function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets) {
+  const merged = { ...userSecrets };
+  if (!remoteSecrets || typeof remoteSecrets !== 'object') return merged;
+  for (const key of Object.keys(remoteSecrets)) {
+    if (!(key in merged) || merged[key] === undefined || merged[key] === null || merged[key] === '') {
+      merged[key] = remoteSecrets[key];
+    }
+  }
+  return merged;
+}
+
+module.exports = {
+  loadRemoteSharedSecrets,
+  mergeUserWithRemoteSecrets
+};

package/lib/utils/secrets-generator.js

@@ -17,6 +17,54 @@ const crypto = require('crypto');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
 
+/**
+ * Parse key-value pairs from YAML-like lines (last occurrence wins per key).
+ * @param {string} content - Raw YAML content
+ * @returns {Object} Parsed object
+ */
+function parseYamlKeyValueLines(content) {
+  const result = {};
+  const keyValueRe = /^\s*([^#:]+):\s*(.*)$/;
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const m = line.match(keyValueRe);
+    if (!m) continue;
+    const key = m[1].trim();
+    let value = m[2].trim();
+    if ((value.startsWith('\'') && value.endsWith('\'')) || (value.startsWith('"') && value.endsWith('"'))) {
+      value = value.slice(1, -1).replace(/\\'/g, '\'').replace(/\\"/g, '"');
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Parse YAML content tolerating duplicate keys (last occurrence wins).
+ * Use for secrets files that may have been appended to repeatedly.
+ * Tries yaml.load first; on "duplicate key" error falls back to line-by-line parse.
+ *
+ * @param {string} content - Raw YAML content
+ * @returns {Object} Parsed object (last value wins for duplicate keys)
+ */
+function loadYamlTolerantOfDuplicateKeys(content) {
+  if (!content || typeof content !== 'string') {
+    return {};
+  }
+  try {
+    const parsed = yaml.load(content);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    const msg = err.message || '';
+    if (!msg.includes('duplicate') && !msg.includes('duplicated mapping')) {
+      throw err;
+    }
+  }
+  return parseYamlKeyValueLines(content);
+}
+
 /**
  * Skips commented or empty lines when scanning env.template
  * @param {string} line - Single line
@@ -127,7 +175,7 @@ function loadExistingSecrets(resolvedPath) {
 
   try {
     const content = fs.readFileSync(resolvedPath, 'utf8');
-    const secrets = yaml.load(content) || {};
+    const secrets = loadYamlTolerantOfDuplicateKeys(content);
     return typeof secrets === 'object' ? secrets : {};
   } catch (error) {
     logger.warn(`Warning: Could not read existing secrets file: ${error.message}`);
@@ -136,7 +184,7 @@ function loadExistingSecrets(resolvedPath) {
 }
 
 /**
- * Saves secrets file
+ * Saves secrets file (full overwrite). Use appendSecretsToFile to add keys without changing existing content.
  * @function saveSecretsFile
  * @param {string} resolvedPath - Path to secrets file
  * @param {Object} secrets - Secrets object to save
@@ -158,6 +206,45 @@ function saveSecretsFile(resolvedPath, secrets) {
   fs.writeFileSync(resolvedPath, yamlContent, { mode: 0o600 });
 }
 
+const YAML_DUMP_OPTS = { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false };
+
+/**
+ * Appends secret keys to the end of the secrets file without modifying existing content (preserves comments and structure).
+ * Creates the file if it does not exist. For existing files, new keys are appended.
+ * When the file has duplicate keys, use loadExistingSecrets (tolerant parse) to read; last occurrence wins.
+ *
+ * @function appendSecretsToFile
+ * @param {string} resolvedPath - Path to secrets file
+ * @param {Object} secrets - Key-value object to append (only these keys are written)
+ * @throws {Error} If write fails
+ */
+function appendSecretsToFile(resolvedPath, secrets) {
+  if (!secrets || typeof secrets !== 'object' || Object.keys(secrets).length === 0) {
+    return;
+  }
+  const dir = path.dirname(resolvedPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  const appendContent = yaml.dump(secrets, YAML_DUMP_OPTS);
+
+  if (!fs.existsSync(resolvedPath)) {
+    fs.writeFileSync(resolvedPath, appendContent, { mode: 0o600 });
+    return;
+  }
+
+  let existing = '';
+  try {
+    const raw = fs.readFileSync(resolvedPath, 'utf8');
+    existing = typeof raw === 'string' ? raw : '';
+  } catch (err) {
+    logger.warn(`Could not read existing secrets file: ${err.message}; appending new keys only.`);
+  }
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  fs.writeFileSync(resolvedPath, existing + separator + appendContent, { mode: 0o600 });
+}
+
 /**
  * Generates missing secret keys in secrets file
  * Scans env.template for kv:// references and adds missing keys with secure defaults
@@ -188,8 +275,7 @@ async function generateMissingSecrets(envTemplate, secretsPath) {
     newSecrets[key] = generateSecretValue(key);
   }
 
-  const updatedSecrets = { ...existingSecrets, ...newSecrets };
-  saveSecretsFile(resolvedPath, updatedSecrets);
+  appendSecretsToFile(resolvedPath, newSecrets);
 
   logger.log(`✓ Generated ${missingKeys.length} missing secret key(s): ${missingKeys.join(', ')}`);
   return missingKeys;
@@ -227,11 +313,11 @@ postgres-passwordKeyVault: "admin123"
 
 # Redis Secrets
 redis-passwordKeyVault: ""
-redis-urlKeyVault: "redis://\${REDIS_HOST}:\${REDIS_PORT}"
+redis-url: "redis://\${REDIS_HOST}:\${REDIS_PORT}"
 
 # Keycloak Secrets
 keycloak-admin-passwordKeyVault: "admin123"
-keycloak-auth-server-urlKeyVault: "http://\${KEYCLOAK_HOST}:\${KEYCLOAK_PORT}"
+keycloak-server-url: "http://\${KEYCLOAK_HOST}:\${KEYCLOAK_PORT}"
 `;
 
   fs.writeFileSync(resolvedPath, defaultSecrets, { mode: 0o600 });
@@ -240,8 +326,10 @@ keycloak-auth-server-urlKeyVault: "http://\${KEYCLOAK_HOST}:\${KEYCLOAK_PORT}"
 module.exports = {
   findMissingSecretKeys,
   generateSecretValue,
+  loadYamlTolerantOfDuplicateKeys,
   loadExistingSecrets,
   saveSecretsFile,
+  appendSecretsToFile,
   generateMissingSecrets,
   createDefaultSecrets
 };

package/lib/utils/secrets-helpers.js

@@ -166,7 +166,7 @@ function getPortFromLocalEnv(localEnv) {
 }
 
 /**
- * Gets port from application config file (build.localPort if positive, else port). Uses port-resolver.
+ * Gets port from application config file (port only). Uses port-resolver.
  * @function getPortFromVariablesFile
  * @param {string} variablesPath - Path to application config
  * @returns {number|null} Port value or null
@@ -199,7 +199,7 @@ function applyDeveloperIdAdjustment(baseAppPort, devIdNum) {
 
 /**
  * Calculate application port following override chain and developer-id adjustment
- * Override chain: env-config.yaml → config.yaml → application.yaml build.localPort → application.yaml port
+ * Override chain: env-config.yaml → config.yaml → application.yaml port
  * @async
  * @function calculateAppPort
  * @param {string} [variablesPath] - Path to application config
@@ -212,7 +212,7 @@ async function calculateAppPort(variablesPath, localEnv, envContent, devIdNum) {
   // Start with env-config value
   let baseAppPort = getPortFromLocalEnv(localEnv);
 
-  // Override with application config → build.localPort (strongest)
+  // Override with application config port (strongest)
   const variablesPort = getPortFromVariablesFile(variablesPath);
   if (variablesPort !== null) {
     baseAppPort = variablesPort;
@@ -247,13 +247,32 @@ function updateLocalhostUrls(content, baseAppPort, appPort) {
 }
 
 /**
- * Adjust infra-related ports in resolved .env content for local environment
- * Only handles PORT variable (other ports handled by interpolation)
- * Follows flow: getEnvHosts() → config.yaml override → application config override → developer-id adjustment
+ * Get the env var name used for PORT in env.template (e.g. PORT=${MISO_PORT} -> MISO_PORT).
+ * Used when generating .env for envOutputPath (local, not reload) so we set that var to localPort.
+ * @param {string} [variablesPath] - Path to application config (env.template lives in same dir)
+ * @returns {string|null} Variable name or null
+ */
+function getPortVarFromEnvTemplatePath(variablesPath) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) return null;
+  const templatePath = path.join(path.dirname(variablesPath), 'env.template');
+  if (!fs.existsSync(templatePath)) return null;
+  try {
+    const content = fs.readFileSync(templatePath, 'utf8');
+    const m = content.match(/^PORT\s*=\s*\$\{([A-Za-z0-9_]+)\}/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Adjust infra-related ports in resolved .env content for local environment.
+ * Own case: when we generate .env for envOutputPath (not reload), we use localPort (application.yaml build.localPort or port).
+ * Sets PORT and the template port var (e.g. MISO_PORT) to localPort so the generated .env is correct for local use.
  * @async
  * @function adjustLocalEnvPortsInContent
  * @param {string} envContent - Resolved .env content
- * @param {string} [variablesPath] - Path to application config (to read build.localPort)
+ * @param {string} [variablesPath] - Path to application config (to read port and template port var)
  * @returns {Promise<string>} Updated content with local ports
  */
 /**
@@ -348,6 +367,11 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   updated = await rewriteInfraEndpoints(updated, 'local');
 
   const envVars = await buildEnvVarsForInterpolation(devIdNum);
+  envVars.PORT = String(appPort);
+  const portVar = getPortVarFromEnvTemplatePath(variablesPath);
+  if (portVar) {
+    envVars[portVar] = String(appPort);
+  }
   updated = interpolateEnvVars(updated, envVars);
 
   return updated;
@@ -447,24 +471,8 @@ function ensureNonEmptySecrets(secrets) {
  * @returns {Object} Validation result
  */
 function validateSecrets(envTemplate, secrets) {
-  const kvPattern = /kv:\/\/([a-zA-Z0-9-_]+)/g;
-  const missing = [];
-  const lines = envTemplate.split('\n');
-  for (const line of lines) {
-    if (isCommentOrEmptyLine(line)) continue;
-    let match;
-    kvPattern.lastIndex = 0;
-    while ((match = kvPattern.exec(line)) !== null) {
-      const secretKey = match[1];
-      if (!(secretKey in secrets)) {
-        missing.push(`kv://${secretKey}`);
-      }
-    }
-  }
-  return {
-    valid: missing.length === 0,
-    missing
-  };
+  const missing = collectMissingSecrets(envTemplate, secrets);
+  return { valid: missing.length === 0, missing };
 }
 
 module.exports = {

package/lib/utils/secrets-path.js

@@ -54,8 +54,8 @@ async function getActualSecretsPath(secretsPath, _appName) {
     };
   }
 
-  // Cascading lookup: user's file first (under configured home)
-  const userSecretsPath = path.join(paths.getAifabrixHome(), 'secrets.local.yaml');
+  // Cascading lookup: user's file first (primary home: AIFABRIX_HOME or ~/.aifabrix)
+  const userSecretsPath = path.join(paths.getConfigDirForPaths(), 'secrets.local.yaml');
 
   // Check config.yaml for canonical secrets path
   let buildSecretsPath = null;