@aifabrix/builder 2.40.0 → 2.41.0

package/lib/utils/device-code.js

@@ -9,6 +9,13 @@
  * @version 2.0.0
  */
 
+const {
+  parseDeviceCodeResponse,
+  parseTokenResponse,
+  checkTokenExpiration,
+  processPollingResponse
+} = require('./device-code-helpers');
+
 // Lazy require to avoid circular dependency
 let makeApiCall;
 function getMakeApiCall() {
@@ -19,40 +26,6 @@ function getMakeApiCall() {
   return makeApiCall;
 }
 
-/**
- * Parses device code response from API
- * Matches OpenAPI DeviceCodeResponse schema (camelCase)
- * @function parseDeviceCodeResponse
- * @param {Object} response - API response object
- * @returns {Object} Parsed device code response
- * @throws {Error} If response is invalid
- */
-function parseDeviceCodeResponse(response) {
-  // OpenAPI spec: { success: boolean, data: DeviceCodeResponse, timestamp: string }
-  const apiResponse = response.data;
-  const responseData = apiResponse.data || apiResponse;
-
-  // OpenAPI spec uses camelCase: deviceCode, userCode, verificationUri, expiresIn, interval
-  const deviceCode = responseData.deviceCode;
-  const userCode = responseData.userCode;
-  const verificationUri = responseData.verificationUri;
-  const expiresIn = responseData.expiresIn || 600;
-  const interval = responseData.interval || 5;
-
-  if (!deviceCode || !userCode || !verificationUri) {
-    throw new Error('Invalid device code response: missing required fields');
-  }
-
-  // Return in snake_case for internal consistency (used by existing code)
-  return {
-    device_code: deviceCode,
-    user_code: userCode,
-    verification_uri: verificationUri,
-    expires_in: expiresIn,
-    interval: interval
-  };
-}
-
 /**
  * Initiates OAuth2 Device Code Flow
  * Calls the device code endpoint to get device_code and user_code
@@ -70,7 +43,6 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
     throw new Error('Environment key is required');
   }
 
-  // Default scope for backward compatibility
   const defaultScope = 'openid profile email';
   const requestScope = scope || defaultScope;
 
@@ -92,298 +64,6 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
   return parseDeviceCodeResponse(response);
 }
 
-/**
- * Checks if token has expired based on elapsed time
- * @function checkTokenExpiration
- * @param {number} startTime - Start time in milliseconds
- * @param {number} expiresIn - Expiration time in seconds
- * @throws {Error} If token has expired
- */
-function checkTokenExpiration(startTime, expiresIn) {
-  const maxWaitTime = (expiresIn + 30) * 1000;
-  if (Date.now() - startTime > maxWaitTime) {
-    throw new Error('Device code expired: Maximum polling time exceeded');
-  }
-}
-
-/**
- * Parses token response from API
- * Matches OpenAPI DeviceCodeTokenResponse schema (camelCase)
- * @function parseTokenResponse
- * @param {Object} response - API response object
- * @returns {Object|null} Parsed token response or null if pending
- */
-function parseTokenResponse(response) {
-  // OpenAPI spec: { success: boolean, data: DeviceCodeTokenResponse, timestamp: string }
-  const apiResponse = response.data;
-  const responseData = apiResponse.data || apiResponse;
-
-  const error = responseData.error || apiResponse.error;
-  if (error === 'authorization_pending' || error === 'slow_down') {
-    return null;
-  }
-
-  // OpenAPI spec uses camelCase: accessToken, refreshToken, expiresIn
-  const accessToken = responseData.accessToken;
-  const refreshToken = responseData.refreshToken;
-  const expiresIn = responseData.expiresIn || 3600;
-
-  if (!accessToken) {
-    throw new Error('Invalid token response: missing accessToken');
-  }
-
-  // Return in snake_case for internal consistency (used by existing code)
-  return {
-    access_token: accessToken,
-    refresh_token: refreshToken,
-    expires_in: expiresIn
-  };
-}
-
-/**
- * Creates a validation error with detailed information
- * @function createValidationError
- * @param {Object} response - Full API response object
- * @returns {Error} Validation error with formattedError and errorData attached
- */
-/**
- * Attaches formatted error to validation error
- * @function attachFormattedError
- * @param {Error} validationError - Validation error object
- * @param {Object} response - API response
- */
-function attachFormattedError(validationError, response) {
-  if (response && response.formattedError) {
-    validationError.formattedError = response.formattedError;
-    validationError.message = `Token polling failed:\n${response.formattedError}`;
-  }
-}
-
-/**
- * Builds detailed error message from error data
- * @function buildDetailedErrorMessage
- * @param {Object} errorData - Error data object
- * @returns {string} Detailed error message
- */
-function buildDetailedErrorMessage(errorData) {
-  const detail = errorData.detail || errorData.title || errorData.message || 'Validation error';
-  let errorMsg = `Token polling failed: ${detail}`;
-
-  if (errorData.errors && Array.isArray(errorData.errors) && errorData.errors.length > 0) {
-    errorMsg += '\n\nValidation errors:';
-    errorData.errors.forEach(err => {
-      const field = err.field || err.path || 'validation';
-      const message = err.message || 'Invalid value';
-      if (field === 'validation' || field === 'unknown') {
-        errorMsg += `\n  • ${message}`;
-      } else {
-        errorMsg += `\n  • ${field}: ${message}`;
-      }
-    });
-  }
-
-  return errorMsg;
-}
-
-/**
- * Attaches error data to validation error
- * @function attachErrorData
- * @param {Error} validationError - Validation error object
- * @param {Object} response - API response
- */
-function attachErrorData(validationError, response) {
-  if (response && response.errorData) {
-    validationError.errorData = response.errorData;
-    validationError.errorType = response.errorType || 'validation';
-
-    if (!validationError.formattedError) {
-      validationError.message = buildDetailedErrorMessage(response.errorData);
-    }
-  }
-}
-
-function createValidationError(response) {
-  const validationError = new Error('Token polling failed: Validation error');
-
-  attachFormattedError(validationError, response);
-  attachErrorData(validationError, response);
-
-  return validationError;
-}
-
-/**
- * Handles polling errors
- * @function handlePollingErrors
- * @param {string} error - Error code
- * @param {number} status - HTTP status code
- * @param {Object} response - Full API response object (for accessing formattedError and errorData)
- * @throws {Error} For fatal errors
- * @returns {boolean} True if should continue polling
- */
-function handlePollingErrors(error, status, response) {
-  if (error === 'authorization_pending' || status === 202) {
-    return true;
-  }
-
-  // Check error field first, then status code
-  if (error === 'authorization_declined') {
-    throw new Error('Authorization declined: User denied the request');
-  }
-
-  if (error === 'expired_token' || status === 410) {
-    throw new Error('Device code expired: Please restart the authentication process');
-  }
-
-  if (error === 'slow_down') {
-    return true;
-  }
-
-  // Handle validation errors with detailed message
-  // Check for validation_error, status 400, or specific validation error codes
-  if (error === 'validation_error' || status === 400 ||
-      error === 'INVALID_TOKEN' || error === 'INVALID_ACCESS_TOKEN') {
-    throw createValidationError(response);
-  }
-
-  throw new Error(`Token polling failed: ${error}`);
-}
-
-/**
- * Waits for next polling interval
- * @async
- * @function waitForNextPoll
- * @param {number} interval - Polling interval in seconds
- * @param {boolean} slowDown - Whether to slow down
- */
-async function waitForNextPoll(interval, slowDown) {
-  const waitInterval = slowDown ? interval * 2 : interval;
-  await new Promise(resolve => setTimeout(resolve, waitInterval * 1000));
-}
-
-/**
- * Extracts error from API response
- * @param {Object} response - API response object
- * @returns {string} Error code or 'Unknown error'
- */
-/**
- * Checks if error code indicates validation error
- * @function isValidationErrorCode
- * @param {string} errorCode - Error code to check
- * @returns {boolean} True if validation error
- */
-function isValidationErrorCode(errorCode) {
-  return errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN';
-}
-
-/**
- * Extracts error from structured error data
- * @function extractStructuredError
- * @param {Object} response - API response with errorData
- * @returns {string} Error message or code
- */
-function extractStructuredError(response) {
-  const errorData = response.errorData;
-
-  // For validation errors, return the error type so we can handle it specially
-  if (response.errorType === 'validation') {
-    return 'validation_error';
-  }
-
-  // Check if error code indicates validation error (e.g., INVALID_TOKEN)
-  const errorCode = errorData.error || errorData.code || response.error;
-  if (isValidationErrorCode(errorCode)) {
-    return 'validation_error';
-  }
-
-  // Return the error message from structured error
-  return errorData.detail || errorData.title || errorData.message || errorCode || response.error || 'Unknown error';
-}
-
-/**
- * Extracts error from fallback response structure
- * @function extractFallbackError
- * @param {Object} response - API response
- * @returns {string} Error code
- */
-function extractFallbackError(response) {
-  const apiResponse = response.data || {};
-  const errorData = typeof apiResponse === 'object' ? apiResponse : {};
-  const errorCode = errorData.error || response.error || 'Unknown error';
-
-  // Check if error code indicates validation error (e.g., INVALID_TOKEN)
-  if (isValidationErrorCode(errorCode)) {
-    return 'validation_error';
-  }
-
-  return errorCode;
-}
-
-function extractPollingError(response) {
-  // Check for structured error data first (from api-error-handler)
-  if (response.errorData) {
-    return extractStructuredError(response);
-  }
-
-  // Fallback to original extraction logic
-  return extractFallbackError(response);
-}
-
-/**
- * Handles successful polling response
- * @param {Object} response - API response object
- * @returns {Object|null} Token response or null if pending
- */
-function handleSuccessfulPoll(response) {
-  const tokenResponse = parseTokenResponse(response);
-  if (tokenResponse) {
-    return tokenResponse;
-  }
-  return null;
-}
-
-/**
- * Processes polling response and determines next action
- * @async
- * @function processPollingResponse
- * @param {Object} response - API response object
- * @param {number} interval - Polling interval in seconds
- * @returns {Promise<Object|null>} Token response if complete, null if should continue
- */
-async function processPollingResponse(response, interval) {
-  if (response.success) {
-    // Check if response contains an error code even though success is true
-    const apiResponse = response.data || {};
-    const responseData = apiResponse.data || apiResponse;
-    const errorCode = responseData.error || apiResponse.error || response.error;
-
-    // If there's an error code like INVALID_TOKEN, treat it as a validation error
-    if (errorCode && (errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN')) {
-      throw createValidationError(response);
-    }
-
-    const tokenResponse = handleSuccessfulPoll(response);
-    if (tokenResponse) {
-      return tokenResponse;
-    }
-
-    const error = errorCode;
-    const slowDown = error === 'slow_down';
-    await waitForNextPoll(interval, slowDown);
-    return null;
-  }
-
-  const error = extractPollingError(response);
-  const shouldContinue = handlePollingErrors(error, response.status, response);
-
-  if (shouldContinue) {
-    const slowDown = error === 'slow_down';
-    await waitForNextPoll(interval, slowDown);
-    return null;
-  }
-
-  return null;
-}
-
 /**
  * Polls for token during Device Code Flow
  * Continuously polls the token endpoint until user approves or flow expires
@@ -431,27 +111,47 @@ async function pollDeviceCodeToken(controllerUrl, deviceCode, interval, expiresI
   }
 }
 
+/**
+ * Builds verification URL with user_code query parameter so the device page can pre-fill the code.
+ *
+ * @function buildVerificationUrlWithUserCode
+ * @param {string} verificationUri - Base verification URL (e.g. http://localhost:8182/realms/aifabrix/device)
+ * @param {string} userCode - User code to append as user_code query param
+ * @returns {string} Full URL with ?user_code=<code> or &user_code=<code>
+ */
+function buildVerificationUrlWithUserCode(verificationUri, userCode) {
+  if (!verificationUri || !userCode) {
+    return verificationUri || '';
+  }
+  const separator = verificationUri.includes('?') ? '&' : '?';
+  return `${verificationUri}${separator}user_code=${encodeURIComponent(userCode)}`;
+}
+
 /**
  * Displays device code information to the user
- * Formats user code and verification URL for easy reading
+ * Formats user code and verification URL for easy reading. Uses a URL with user_code in the query
+ * so the device page can pre-fill the code and the user does not need to type it.
  *
  * @function displayDeviceCodeInfo
  * @param {string} userCode - User code to display
- * @param {string} verificationUri - Verification URL
+ * @param {string} verificationUri - Verification URL (base, without user_code)
  * @param {Object} logger - Logger instance with log method
  * @param {Object} chalk - Chalk instance for colored output
  */
 function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk) {
+  const visitUrl = buildVerificationUrlWithUserCode(verificationUri, userCode);
   logger.log(chalk.cyan('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
   logger.log(chalk.cyan('  Device Code Flow Authentication'));
   logger.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
   logger.log(chalk.yellow('To complete authentication:'));
-  logger.log(chalk.gray('  1. Visit: ') + chalk.blue.underline(verificationUri));
-  logger.log(chalk.gray('  2. Enter code: ') + chalk.bold.cyan(userCode));
-  logger.log(chalk.gray('  3. Approve the request\n'));
+  logger.log(chalk.gray('  1. Visit (code is in the URL): ') + chalk.blue.underline(visitUrl));
+  logger.log(chalk.gray('  2. Approve the request\n'));
   logger.log(chalk.gray('Waiting for approval...'));
 }
 
+/** Timeout for token refresh request (ms). Longer than default to allow for slow controller/Keycloak. */
+const REFRESH_TOKEN_TIMEOUT_MS = 60000;
+
 /**
  * Refresh device code access token using refresh token
  * Uses OpenAPI /api/v1/auth/login/device/refresh endpoint
@@ -469,13 +169,13 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
   }
 
   const url = `${controllerUrl}/api/v1/auth/login/device/refresh`;
-  // Send both refresh_token (OAuth2 RFC 6749 / Keycloak) and refreshToken (camelCase) so controller accepts either
   const response = await getMakeApiCall()(url, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
-    body: JSON.stringify({ refresh_token: refreshToken, refreshToken })
+    body: JSON.stringify({ refresh_token: refreshToken, refreshToken }),
+    signal: AbortSignal.timeout(REFRESH_TOKEN_TIMEOUT_MS)
   });
 
   if (!response.success) {
@@ -483,7 +183,6 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
     throw new Error(`Failed to refresh token: ${errorMsg}`);
   }
 
-  // Parse response using existing parseTokenResponse function
   const tokenResponse = parseTokenResponse(response);
   if (!tokenResponse) {
     throw new Error('Invalid refresh token response');
@@ -491,10 +190,12 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
 
   return tokenResponse;
 }
+
 module.exports = {
   initiateDeviceCodeFlow,
   pollDeviceCodeToken,
   displayDeviceCodeInfo,
   refreshDeviceToken,
-  parseTokenResponse
+  parseTokenResponse,
+  buildVerificationUrlWithUserCode
 };

package/lib/utils/docker-build.js

@@ -95,9 +95,19 @@ function handleDockerClose(code, ctx) {
 }
 
 function runDockerBuildProcess(buildOpts) {
-  const { imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject } = buildOpts;
-  const dockerProcess = spawn('docker', ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath, contextPath], {
-    shell: process.platform === 'win32'
+  const { imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject, env = {}, buildArgs = {} } = buildOpts;
+  const spawnEnv = { ...process.env, ...env };
+  const args = ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath];
+  // Pass NPM_TOKEN/PYPI_TOKEN etc. so private registry auth works during RUN npm install / pip install
+  for (const [key, value] of Object.entries(buildArgs)) {
+    if (value !== null && value !== undefined && String(value).length > 0) {
+      args.push('--build-arg', `${key}=${String(value)}`);
+    }
+  }
+  args.push(contextPath);
+  const dockerProcess = spawn('docker', args, {
+    shell: process.platform === 'win32',
+    env: spawnEnv
   });
   let stdoutBuffer = '';
   let stderrBuffer = '';
@@ -138,13 +148,15 @@ function runDockerBuildProcess(buildOpts) {
  * @param {string} dockerfilePath - Path to Dockerfile
  * @param {string} contextPath - Build context path
  * @param {string} tag - Image tag
+ * @param {Object} [buildArgs={}] - Optional build args (e.g. NPM_TOKEN, PYPI_TOKEN) for private registries
  * @returns {Promise<void>} Resolves when build completes
  * @throws {Error} If build fails
  */
-async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
+async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}) {
   const spinner = ora({ text: 'Starting Docker build...', spinner: 'dots' }).start();
   const fsSync = require('fs');
   const path = require('path');
+  const { getRemoteDockerEnv } = require('./remote-docker-env');
   dockerfilePath = path.resolve(dockerfilePath);
   contextPath = path.resolve(contextPath);
 
@@ -162,8 +174,21 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
     }
   }
 
+  const isTest = process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined;
+  const remoteEnv = isTest ? {} : await getRemoteDockerEnv();
+  const resolvedBuildArgs = buildArgs && typeof buildArgs === 'object' ? buildArgs : {};
   return new Promise((resolve, reject) => {
-    runDockerBuildProcess({ imageName, tag, dockerfilePath, contextPath, spinner, resolve, reject });
+    runDockerBuildProcess({
+      imageName,
+      tag,
+      dockerfilePath,
+      contextPath,
+      spinner,
+      resolve,
+      reject,
+      env: remoteEnv,
+      buildArgs: resolvedBuildArgs
+    });
   });
 }
 
@@ -179,14 +204,18 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
  * @throws {Error} If build fails
  */
 async function executeBuild(imageName, dockerfilePath, contextPath, tag, options) {
-  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag);
+  const buildArgs = (options && options.buildArgs) || {};
+  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs);
 
   // Tag image if additional tag provided
   if (options && options.tag && options.tag !== 'latest') {
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    await run(`docker tag ${imageName}:${tag} ${imageName}:latest`);
+    const { getRemoteDockerEnv } = require('./remote-docker-env');
+    const remoteEnv = await getRemoteDockerEnv();
+    const env = { ...process.env, ...remoteEnv };
+    await run(`docker tag ${imageName}:${tag} ${imageName}:latest`, { env });
   }
 }
 
@@ -215,7 +244,10 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
     const { promisify } = require('util');
     const { exec } = require('child_process');
     const run = promisify(exec);
-    await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`);
+    const { getRemoteDockerEnv } = require('./remote-docker-env');
+    const remoteEnv = await getRemoteDockerEnv();
+    const env = { ...process.env, ...remoteEnv };
+    await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`, { env });
     logger.log(chalk.green(`✓ Tagged image: ${imageName}:${tag}`));
   } catch (err) {
     logger.log(chalk.yellow(`⚠️  Warning: Could not create compatibility tag ${imageName}:${tag} - ${err.message}`));

package/lib/utils/env-copy.js

@@ -9,6 +9,7 @@
 'use strict';
 
 const fs = require('fs');
+const fsp = require('fs').promises;
 const path = require('path');
 const yaml = require('js-yaml');
 const chalk = require('chalk');
@@ -72,6 +73,44 @@ function resolveEnvOutputPath(rawOutputPath, variablesPath) {
   return outputPath;
 }
 
+/**
+ * Writes .env to envOutputPath for reload path: merge run .env into existing file.
+ * @async
+ * @param {string} outputPath - Resolved output path
+ * @param {string} runEnvPath - Path to .env.run
+ */
+async function writeEnvOutputForReload(outputPath, runEnvPath) {
+  const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const runContent = await fsp.readFile(runEnvPath, 'utf8');
+  const runMap = parseEnvContentToMap(runContent);
+  let toWrite = runContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = await fsp.readFile(outputPath, 'utf8');
+    toWrite = mergeEnvMapIntoContent(existingContent, runMap);
+  }
+  await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Wrote .env to envOutputPath (same as container, for --reload): ${outputPath}`));
+}
+
+/**
+ * Writes local .env to envOutputPath (no reload).
+ * @async
+ * @param {string} appName - Application name
+ * @param {string} outputPath - Resolved output path
+ */
+async function writeEnvOutputForLocal(appName, outputPath) {
+  const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const localContent = await generateEnvContent(appName, null, 'local', false);
+  let toWrite = localContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = await fsp.readFile(outputPath, 'utf8');
+    const localMap = parseEnvContentToMap(localContent);
+    toWrite = mergeEnvMapIntoContent(existingContent, localMap);
+  }
+  await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Wrote .env to envOutputPath (localPort): ${outputPath}`));
+}
+
 /**
  * Calculate developer-specific app port
  * @param {number} baseAppPort - Base application port
@@ -180,6 +219,42 @@ async function patchEnvContentForLocal(envContent, variables) {
   return envContent;
 }
 
+/**
+ * Write regenerated local .env to output path (merge with existing if present).
+ * @async
+ * @param {string} outputPath - Resolved output path
+ * @param {string} appName - Application name
+ * @param {string} [secretsPath] - Path to secrets file (optional)
+ * @param {string} envOutputPathLabel - Label for log message (e.g. variables.build.envOutputPath)
+ */
+async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOutputPathLabel) {
+  const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
+  const localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
+  let toWrite = localEnvContent;
+  if (fs.existsSync(outputPath)) {
+    const existingContent = fs.readFileSync(outputPath, 'utf8');
+    const localMap = parseEnvContentToMap(localEnvContent);
+    toWrite = mergeEnvMapIntoContent(existingContent, localMap);
+  }
+  fs.writeFileSync(outputPath, toWrite, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Generated local .env at: ${envOutputPathLabel}`));
+}
+
+/**
+ * Write patched .env to output path (fallback when appName not provided).
+ * @async
+ * @param {string} envPath - Path to generated .env file
+ * @param {string} outputPath - Resolved output path
+ * @param {Object} variables - Loaded variables config
+ * @param {string} envOutputPathLabel - Label for log message
+ */
+async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOutputPathLabel) {
+  const envContent = fs.readFileSync(envPath, 'utf8');
+  const patchedContent = await patchEnvContentForLocal(envContent, variables);
+  fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
+  logger.log(chalk.green(`✓ Copied .env to: ${envOutputPathLabel}`));
+}
+
 /**
  * Process and optionally copy env file to envOutputPath if configured
  * Regenerates .env file with env=local for local development (apps/.env)
@@ -191,7 +266,7 @@ async function patchEnvContentForLocal(envContent, variables) {
  * @param {string} [secretsPath] - Path to secrets file (optional, for regenerating)
  */
 async function processEnvVariables(envPath, variablesPath, appName, secretsPath) {
-  if (!fs.existsSync(variablesPath)) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) {
     return;
   }
   const variablesContent = fs.readFileSync(variablesPath, 'utf8');
@@ -200,29 +275,24 @@ async function processEnvVariables(envPath, variablesPath, appName, secretsPath)
     return;
   }
 
-  // Resolve output path
   const outputPath = resolveEnvOutputPath(variables.build.envOutputPath, variablesPath);
   const outputDir = path.dirname(outputPath);
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
 
-  // Regenerate .env file with env=local instead of copying docker-generated file
+  const label = variables.build.envOutputPath;
   if (appName) {
-    const { generateEnvContent } = require('../core/secrets');
-    const localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false);
-    fs.writeFileSync(outputPath, localEnvContent, { mode: 0o600 });
-    logger.log(chalk.green(`✓ Generated local .env at: ${variables.build.envOutputPath}`));
+    await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label);
   } else {
-    // Fallback: if appName not provided, use old patching approach
-    const envContent = fs.readFileSync(envPath, 'utf8');
-    const patchedContent = await patchEnvContentForLocal(envContent, variables);
-    fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
-    logger.log(chalk.green(`✓ Copied .env to: ${variables.build.envOutputPath}`));
+    await writePatchedEnvToOutputPath(envPath, outputPath, variables, label);
   }
 }
 
 module.exports = {
-  processEnvVariables
+  processEnvVariables,
+  resolveEnvOutputPath,
+  writeEnvOutputForReload,
+  writeEnvOutputForLocal
 };