@aifabrix/builder 2.37.0 → 2.37.9

package/.cursor/rules/project-rules.mdc

@@ -70,6 +70,23 @@ lib/
 └── schema/             # JSON schemas
 ```
 
+### Generated Output (integration/ and builder/)
+
+Files under **integration/** and **builder/** are **auto-generated** by the CLI. When fixing bugs or changing behavior, validate **where** each file is produced so fixes go into the generator, not only into the generated artifact.
+
+- **integration/** – External system / wizard output:
+  - Path: `integration/<appName>/` (see `lib/utils/paths.js` → `getIntegrationPath`).
+  - Generated by: `lib/generator/wizard.js` (`generateWizardFiles`, `generateConfigFilesForWizard`), `lib/external-system/download.js`, wizard commands in `lib/commands/wizard-core.js` and `lib/commands/wizard.js`.
+  - Typical outputs: `variables.yaml`, `env.template`, `README.md`, `*-system.json`, `*-datasource*.json`, `*-deploy.json`, deploy script (`deploy.js`), and optionally `wizard.yaml`, `error.log`.
+- **builder/** – Application (non-external) output:
+  - Path: `builder/<appName>/` or custom root via `AIFABRIX_BUILDER_DIR` (see `lib/utils/paths.js` → `getBuilderPath`).
+  - Generated by: app create/register flow, `lib/generator/index.js`, `lib/commands/up-common.js`, `lib/core/secrets.js`, and related app/deploy logic.
+  - Typical outputs: `variables.yaml`, `env.template`, deploy JSON, `.env` (from secrets), and app-specific config.
+
+**Editable vs generated:**
+- Some generated files are **intended to be edited** (e.g. `variables.yaml`, `env.template`, `README.md`, `wizard.yaml`). Improvements to defaults or structure still belong in the generator/templates.
+- **When debugging:** First identify the **source of generation** (which module and function write the file). Fix bugs in that generator or template; avoid treating a one-off edit in integration/ or builder/ as the permanent fix unless it’s a deliberate local override.
+
 ### CLI Command Pattern
 Commands are defined in `lib/cli.js` using Commander.js:
 ```javascript
@@ -850,6 +867,7 @@ Define request/response types using JSDoc `@typedef`:
 
 ### Must Do (✅)
 - ✅ Validate all inputs (app names, file paths, URLs)
+- ✅ When fixing bugs in integration/ or builder/ output: identify the generator that produces the file and fix the source (lib/generator, lib/commands, templates), not only the generated artifact
 - ✅ Use try-catch for all async operations
 - ✅ Provide meaningful error messages with context
 - ✅ Use JSDoc for all public functions
@@ -874,6 +892,7 @@ Define request/response types using JSDoc `@typedef`:
 - ❌ Never use `eval()` or `Function()` constructor
 - ❌ Never use raw paths (always use path.join)
 - ❌ Never make direct API calls using `makeApiCall` in new code (use `lib/api/` modules)
+- ❌ Never treat one-off edits in integration/ or builder/ as the permanent fix for a bug—update the generator or template that produces the file
 - ❌ Never skip type definitions for API request/response types
 - ❌ Never log authentication tokens or secrets in API calls
 

package/integration/hubspot/test.js

@@ -511,7 +511,7 @@ async function checkAppDirectory(appPath) {
  * @throws {Error} If required files are missing
  */
 async function validateRequiredFiles(appPath, entries) {
-  const requiredFiles = ['variables.yaml', 'env.template', 'README.md', 'deploy.sh', 'deploy.ps1'];
+  const requiredFiles = ['variables.yaml', 'env.template', 'README.md', 'deploy.js'];
   const missingFiles = [];
   for (const fileName of requiredFiles) {
     const filePath = path.join(appPath, fileName);

package/lib/api/wizard.api.js

@@ -311,7 +311,7 @@ async function testMcpConnection(dataplaneUrl, authConfig, serverUrl, token) {
 }
 
 /**
- * Get deployment documentation for a system
+ * Get deployment documentation for a system (from dataplane DB only)
  * GET /api/v1/wizard/deployment-docs/{systemKey}
  * @async
  * @function getDeploymentDocs
@@ -326,6 +326,28 @@ async function getDeploymentDocs(dataplaneUrl, authConfig, systemKey) {
   return await client.get(`/api/v1/wizard/deployment-docs/${systemKey}`);
 }
 
+/**
+ * Generate deployment documentation with variables.yaml and deploy JSON for better quality
+ * POST /api/v1/wizard/deployment-docs/{systemKey}
+ * Sends deployJson and variablesYaml in the request body so the dataplane can align README with the integration folder.
+ * @async
+ * @function postDeploymentDocs
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} systemKey - System key identifier
+ * @param {Object} [body] - Optional request body (WizardDeploymentDocsRequest)
+ * @param {Object} [body.deployJson] - Deploy JSON object (e.g. *-deploy.json content)
+ * @param {string} [body.variablesYaml] - variables.yaml file content as string
+ * @returns {Promise<Object>} Deployment documentation response (content, contentType, systemKey)
+ * @throws {Error} If request fails
+ */
+async function postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body = null) {
+  const client = new ApiClient(dataplaneUrl, authConfig);
+  return await client.post(`/api/v1/wizard/deployment-docs/${systemKey}`, {
+    body: body || {}
+  });
+}
+
 /**
  * Get known wizard platforms from dataplane.
  * GET /api/v1/wizard/platforms
@@ -365,5 +387,6 @@ module.exports = {
   getPreview,
   testMcpConnection,
   getDeploymentDocs,
+  postDeploymentDocs,
   getWizardPlatforms
 };

package/lib/app/deploy.js

@@ -15,7 +15,7 @@ const yaml = require('js-yaml');
 const chalk = require('chalk');
 const pushUtils = require('../deployment/push');
 const logger = require('../utils/logger');
-const { detectAppType } = require('../utils/paths');
+const { detectAppType, getBuilderPath, getIntegrationPath } = require('../utils/paths');
 const { checkApplicationExists } = require('../utils/app-existence');
 const { loadDeploymentConfig } = require('./deploy-config');
 
@@ -219,15 +219,16 @@ function displayDeploymentResults(result) {
 }
 
 /**
- * Check if app is external and handle external deployment
+ * Check if app is external and handle external deployment.
+ * When options.type === 'external', forces deployment from integration/<app> (no app register needed).
  * @async
  * @function handleExternalDeployment
  * @param {string} appName - Application name
- * @param {Object} options - Deployment options
+ * @param {Object} options - Deployment options (type: 'external' to force integration/<app>)
  * @returns {Promise<Object|null>} Deployment result if external, null otherwise
  */
 async function handleExternalDeployment(appName, options) {
-  const { isExternal } = await detectAppType(appName);
+  const { isExternal } = await detectAppType(appName, options);
   if (isExternal) {
     const externalDeploy = require('../external-system/deploy');
     await externalDeploy.deployExternalSystem(appName, options);
@@ -317,6 +318,37 @@ async function executeStandardDeployment(appName, options) {
   }
 }
 
+/**
+ * Tries external deploy when builder/<app> does not exist but integration/<app> does.
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} options - Deployment options
+ * @returns {Promise<{usedExternalDeploy: boolean, result: Object|null}>}
+ */
+async function tryExternalDeployFallback(appName, options) {
+  const builderPath = getBuilderPath(appName);
+  const integrationPath = getIntegrationPath(appName);
+  let builderExists = false;
+  let integrationExists = false;
+  try {
+    await fs.access(builderPath);
+    builderExists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  try {
+    await fs.access(integrationPath);
+    integrationExists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (!builderExists && integrationExists) {
+    const fallbackResult = await handleExternalDeployment(appName, { ...options, type: 'external' });
+    if (fallbackResult) return { usedExternalDeploy: true, result: fallbackResult };
+  }
+  return { usedExternalDeploy: false, result: null };
+}
+
 /**
  * Deploys application to Miso Controller
  * Orchestrates manifest generation, key creation, and deployment
@@ -338,7 +370,7 @@ async function executeStandardDeployment(appName, options) {
  */
 async function deployApp(appName, options = {}) {
   let controllerUrl = null;
-  let usedExternalDeploy = false;
+  let usedExternalDeploy = options.type === 'external';
 
   try {
     if (!appName || typeof appName !== 'string' || appName.trim().length === 0) {
@@ -347,8 +379,12 @@ async function deployApp(appName, options = {}) {
     validateAppName(appName);
 
     const externalResult = await handleExternalDeployment(appName, options);
-    if (externalResult) {
-      return externalResult;
+    if (externalResult) return externalResult;
+
+    const fallback = await tryExternalDeployFallback(appName, options);
+    if (fallback.result) {
+      usedExternalDeploy = fallback.usedExternalDeploy;
+      return fallback.result;
     }
     usedExternalDeploy = false;
 

package/lib/app/list.js

@@ -164,9 +164,11 @@ function displayApplications(applications, environment, controllerUrl) {
 
   logger.log(chalk.bold(`\n📱 ${header}:\n`));
   applications.forEach((app) => {
+    const isExternal = app.configuration?.type === 'external';
+    const externalIcon = isExternal ? '🔗 ' : '';
     const hasPipeline = app.configuration?.pipeline?.isActive ? '✓' : '✗';
     const urlAndPort = formatUrlAndPort(app);
-    logger.log(`${hasPipeline} ${chalk.cyan(app.key)} - ${app.displayName} (${app.status || 'unknown'})${urlAndPort}`);
+    logger.log(`${externalIcon}${hasPipeline} ${chalk.cyan(app.key)} - ${app.displayName} (${app.status || 'unknown'})${urlAndPort}`);
   });
   logger.log(chalk.gray('  To show details for an app: aifabrix app show <appKey>\n'));
 }

package/lib/build/index.js

@@ -200,7 +200,7 @@ async function postBuildTasks(appName, buildConfig) {
 }
 
 /**
- * Check if app is external type and handle accordingly
+ * External apps have no Docker image; deploy JSON is generated by aifabrix json.
  * @async
  * @param {string} appName - Application name
  * @returns {Promise<boolean>} True if external (handled), false if should continue
@@ -208,9 +208,8 @@ async function postBuildTasks(appName, buildConfig) {
 async function checkExternalAppType(appName) {
   const variables = await loadVariablesYaml(appName);
   if (variables.app && variables.app.type === 'external') {
-    const generator = require('../generator');
-    const jsonPath = await generator.generateDeployJson(appName);
-    logger.log(chalk.green(`✓ Generated deployment JSON: ${jsonPath}`));
+    logger.log(chalk.blue(`External system: ${appName}`));
+    logger.log(chalk.gray('To regenerate deployment JSON, run: aifabrix json ' + appName));
     return true;
   }
   return false;

package/lib/cli/setup-app.js

@@ -197,6 +197,7 @@ See integration/hubspot/wizard-hubspot-e2e.yaml for an example.`)
 
   program.command('deploy <app>')
     .description('Deploy to Azure via Miso Controller')
+    .option('--type <type>', 'Application type: external to deploy from integration/<app> (no app register needed)')
     .option('--client-id <id>', 'Client ID (overrides config)')
     .option('--client-secret <secret>', 'Client Secret (overrides config)')
     .option('--poll', 'Poll for deployment status', true)

package/lib/cli/setup-external-system.js

@@ -66,6 +66,7 @@ function setupExternalSystemCommands(program) {
     .description('Run integration tests via dataplane pipeline API')
     .option('-d, --datasource <key>', 'Test specific datasource only')
     .option('-p, --payload <file>', 'Path to custom test payload file')
+    .option('--dataplane <url>', 'Dataplane URL (default: discovered from controller)')
     .option('-v, --verbose', 'Show detailed test output')
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async(appName, options) => {

package/lib/cli/setup-utility.js

@@ -87,7 +87,7 @@ function setupUtilityCommands(program) {
     });
 
   program.command('json <app>')
-    .description('Generate deployment JSON (aifabrix-deploy.json for normal apps, application-schema.json for external systems)')
+    .description('Generate deployment JSON to disk (<app>-deploy.json). Use before commit so version control has the correct file.')
     .option('--type <type>', 'Application type (external) - if set, only checks integration folder')
     .action(async(appName, options) => {
       try {

package/lib/commands/up-common.js

@@ -30,6 +30,36 @@ async function ensureTemplateAtPath(appName, targetAppPath) {
   return true;
 }
 
+/**
+ * Patches variables.yaml to set build.envOutputPath to null for deploy-only (no local code).
+ * Use when running up-miso/up-platform so we do not copy .env to repo paths or show that message.
+ * Patches both primary builder path and cwd/builder if different.
+ *
+ * @param {string} appName - Application name (e.g. miso-controller, dataplane)
+ */
+function patchEnvOutputPathForDeployOnly(appName) {
+  if (!appName || typeof appName !== 'string') return;
+  const pathsToPatch = [pathsUtil.getBuilderPath(appName)];
+  const cwdBuilderPath = path.join(process.cwd(), 'builder', appName);
+  if (path.resolve(cwdBuilderPath) !== path.resolve(pathsToPatch[0])) {
+    pathsToPatch.push(cwdBuilderPath);
+  }
+  const envOutputPathLine = /^(\s*envOutputPath:)\s*.*$/m;
+  const replacement = '$1 null  # deploy only, no copy';
+  for (const appPath of pathsToPatch) {
+    const variablesPath = path.join(appPath, 'variables.yaml');
+    if (!fs.existsSync(variablesPath)) continue;
+    try {
+      let content = fs.readFileSync(variablesPath, 'utf8');
+      if (!envOutputPathLine.test(content)) continue;
+      content = content.replace(envOutputPathLine, replacement);
+      fs.writeFileSync(variablesPath, content, 'utf8');
+    } catch (err) {
+      logger.warn(chalk.yellow(`Could not patch envOutputPath in ${variablesPath}: ${err.message}`));
+    }
+  }
+}
+
 /**
  * Ensures builder app directory exists from template if variables.yaml is missing.
  * If builder/<appName>/variables.yaml does not exist, copies from templates/applications/<appName>.
@@ -69,4 +99,4 @@ async function ensureAppFromTemplate(appName) {
   return primaryCopied;
 }
 
-module.exports = { ensureAppFromTemplate };
+module.exports = { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly };

package/lib/commands/up-miso.js

@@ -19,7 +19,7 @@ const secrets = require('../core/secrets');
 const infra = require('../infrastructure');
 const app = require('../app');
 const { saveLocalSecret } = require('../utils/local-secrets');
-const { ensureAppFromTemplate } = require('./up-common');
+const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly } = require('./up-common');
 
 /** Keycloak base port (from templates/applications/keycloak/variables.yaml) */
 const KEYCLOAK_BASE_PORT = 8082;
@@ -132,12 +132,16 @@ async function handleUpMiso(options = {}) {
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
   await ensureAppFromTemplate('dataplane');
+  // Deploy-only: do not copy .env to repo paths; patch variables so envOutputPath is null
+  patchEnvOutputPathForDeployOnly('keycloak');
+  patchEnvOutputPathForDeployOnly('miso-controller');
+  patchEnvOutputPathForDeployOnly('dataplane');
   const developerId = await config.getDeveloperId();
   const devIdNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   await setMisoSecretsAndResolve(devIdNum);
   await runMisoApps(options);
-  logger.log(chalk.green('\n✓ up-miso complete. Keycloak, miso-controller, and dataplane are running.'));
-  logger.log(chalk.gray('  Run onboarding and register Keycloak from the miso-controller repo if needed.'));
+  logger.log(chalk.green('\n✓ up-miso complete. Keycloak, miso-controller, and dataplane are running.') +
+    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed.'));
 }
 
 module.exports = { handleUpMiso, parseImageOptions };

package/lib/commands/wizard-core.js

@@ -18,7 +18,8 @@ const {
   detectType,
   generateConfig,
   validateWizardConfig,
-  getDeploymentDocs
+  getDeploymentDocs,
+  postDeploymentDocs
 } = require('../api/wizard.api');
 const { generateWizardFiles } = require('../generator/wizard');
 const {
@@ -337,6 +338,44 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
   }
 }
 
+/**
+ * Fetches deployment docs and writes README.md when variables.yaml and deploy JSON are available.
+ * @async
+ * @param {string} appPath - Application path
+ * @param {string} appName - Application name
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} systemKey - System key
+ */
+async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl, authConfig, systemKey) {
+  const variablesPath = path.join(appPath, 'variables.yaml');
+  const deployPath = path.join(appPath, `${appName}-deploy.json`);
+  let variablesYaml = null;
+  let deployJson = null;
+  try {
+    variablesYaml = await fs.readFile(variablesPath, 'utf8');
+  } catch {
+    // optional
+  }
+  try {
+    const deployContent = await fs.readFile(deployPath, 'utf8');
+    deployJson = JSON.parse(deployContent);
+  } catch {
+    // optional
+  }
+  const hasBody = variablesYaml !== null || deployJson !== null;
+  const body = hasBody ? { variablesYaml: variablesYaml || null, deployJson: deployJson || null } : null;
+  const docsResponse = body
+    ? await postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body)
+    : await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
+  const content = docsResponse?.data?.content ?? docsResponse?.content;
+  if (content && typeof content === 'string') {
+    const readmePath = path.join(appPath, 'README.md');
+    await fs.writeFile(readmePath, content, 'utf8');
+    logger.log(chalk.gray('  Updated README.md from deployment-docs API (variables.yaml + deploy JSON).'));
+  }
+}
+
 /**
  * Handle file saving step
  * @async
@@ -353,23 +392,21 @@ async function handleFileSaving(appName, systemConfig, datasourceConfigs, system
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 7: Save Files'));
   const spinner = ora('Saving files...').start();
   try {
-    let aiGeneratedReadme = null;
-    if (systemKey && dataplaneUrl && authConfig) {
+    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null });
+    if (systemKey && dataplaneUrl && authConfig && generatedFiles.appPath) {
       try {
-        const docsResponse = await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
-        if (docsResponse.success && docsResponse.data?.content) aiGeneratedReadme = docsResponse.data.content;
+        await tryUpdateReadmeFromDeploymentDocs(generatedFiles.appPath, appName, dataplaneUrl, authConfig, systemKey);
       } catch (e) {
         logger.log(chalk.gray(`  Could not fetch AI-generated README: ${e.message}`));
       }
     }
-    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme });
     spinner.stop();
     logger.log(chalk.green('\n\u2713 Wizard completed successfully!'));
     logger.log(chalk.green(`\nFiles created in: ${generatedFiles.appPath}`));
     logger.log(chalk.blue('\nNext steps:'));
     logger.log(chalk.gray(`  1. Review the generated files in integration/${appName}/`));
     logger.log(chalk.gray('  2. Update env.template with your authentication details'));
-    logger.log(chalk.gray(`  3. Deploy using: ./deploy.sh or aifabrix deploy ${appName}`));
+    logger.log(chalk.gray(`  3. Deploy using: node deploy.js or aifabrix deploy ${appName}`));
     return generatedFiles;
   } catch (error) {
     spinner.stop();

package/lib/core/config.js

@@ -405,9 +405,24 @@ async function ensureSecretsEncryptionKey() {
   await run({ getSecretsEncryptionKey, setSecretsEncryptionKey, getSecretsPath });
 }
 
+/**
+ * Expand leading ~ to home directory so config paths like ~/.aifabrix/secrets.local.yaml resolve correctly.
+ * @param {string} filePath - Path that may start with ~ or ~/
+ * @returns {string} Path with ~ expanded, or unchanged if no leading ~
+ */
+function expandTilde(filePath) {
+  if (!filePath || typeof filePath !== 'string') return filePath;
+  if (filePath === '~') return os.homedir();
+  if (filePath.startsWith('~/') || filePath.startsWith('~' + path.sep)) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
 async function getSecretsPath() {
   const config = await getConfig();
-  return config['aifabrix-secrets'] || config['secrets-path'] || null;
+  const raw = config['aifabrix-secrets'] || config['secrets-path'] || null;
+  return raw ? expandTilde(raw) : null;
 }
 
 async function setSecretsPath(secretsPath) {

package/lib/core/secrets.js

@@ -132,28 +132,57 @@ async function decryptSecretsObject(secrets) {
  * const secrets = await loadSecrets(undefined, 'myapp');
  */
 
+/**
+ * Merges config file secrets into user secrets (user wins). Returns null if path missing or config empty.
+ * @param {Object} userSecrets - User secrets object
+ * @param {string} resolvedConfigPath - Absolute path to config secrets file
+ * @returns {Object|null} Merged secrets or null
+ */
+function mergeUserWithConfigFile(userSecrets, resolvedConfigPath) {
+  if (!fs.existsSync(resolvedConfigPath)) {
+    return null;
+  }
+  let configSecrets;
+  try {
+    configSecrets = readYamlAtPath(resolvedConfigPath);
+  } catch (loadError) {
+    throw new Error(`Failed to load secrets file ${resolvedConfigPath}: ${loadError.message}`);
+  }
+  if (!configSecrets || typeof configSecrets !== 'object') {
+    return null;
+  }
+  const merged = { ...userSecrets };
+  for (const key of Object.keys(configSecrets)) {
+    if (!(key in merged) || merged[key] === undefined || merged[key] === null || merged[key] === '') {
+      merged[key] = configSecrets[key];
+    }
+  }
+  return merged;
+}
+
 /**
  * Loads config secrets path, merges with user secrets (user overrides). Used by loadSecrets cascade.
  * @async
  * @returns {Promise<Object|null>} Merged secrets object or null
  */
 async function loadMergedConfigAndUserSecrets() {
+  const userSecrets = loadUserSecrets();
+  const hasKeys = (obj) => obj && Object.keys(obj).length > 0;
+  const userOrNull = () => (hasKeys(userSecrets) ? userSecrets : null);
   try {
     const configSecretsPath = await config.getSecretsPath();
-    if (!configSecretsPath) return null;
+    if (!configSecretsPath) {
+      return userOrNull();
+    }
     const resolvedConfigPath = path.isAbsolute(configSecretsPath)
       ? configSecretsPath
       : path.resolve(process.cwd(), configSecretsPath);
-    if (!fs.existsSync(resolvedConfigPath)) return null;
-    const configSecrets = readYamlAtPath(resolvedConfigPath);
-    if (!configSecrets || typeof configSecrets !== 'object') return null;
-    const merged = { ...configSecrets };
-    const userSecrets = loadUserSecrets();
-    for (const key of Object.keys(userSecrets)) {
-      merged[key] = userSecrets[key];
+    const merged = mergeUserWithConfigFile(userSecrets, resolvedConfigPath);
+    return merged !== null ? merged : userOrNull();
+  } catch (error) {
+    if (error.message && error.message.startsWith('Failed to load secrets file')) {
+      throw error;
     }
-    return merged;
-  } catch {
     return null;
   }
 }
@@ -229,22 +258,11 @@ async function resolveKvReferences(envTemplate, secrets, environment = 'local',
   return replaceKvInContent(resolved, secrets, envVars);
 }
 
-/**
- * Applies environment-specific transformations to resolved content
- * @async
- * @function applyEnvironmentTransformations
- * @param {string} resolved - Resolved environment content
- * @param {string} environment - Environment context
- * @param {string} variablesPath - Path to variables.yaml file
- * @returns {Promise<string>} Transformed content
- */
+/** Applies environment-specific transformations to resolved content. */
 async function applyEnvironmentTransformations(resolved, environment, variablesPath) {
   if (environment === 'docker') {
     resolved = await resolveServicePortsInEnvContent(resolved, environment);
     resolved = await rewriteInfraEndpoints(resolved, 'docker');
-    // Interpolate ${VAR} references created by rewriteInfraEndpoints
-    // Get the actual host and port values from env-endpoints.js directly
-    // to ensure they are correctly populated in envVars for interpolation
     const { getEnvHosts, getServiceHost, getServicePort, getLocalhostOverride } = require('../utils/env-endpoints');
     const hosts = await getEnvHosts('docker');
     const localhostOverride = getLocalhostOverride('docker');
@@ -252,10 +270,7 @@ async function applyEnvironmentTransformations(resolved, environment, variablesP
     const redisPort = await getServicePort('REDIS_PORT', 'redis', hosts, 'docker', null);
     const dbHost = getServiceHost(hosts.DB_HOST, 'docker', 'postgres', localhostOverride);
     const dbPort = await getServicePort('DB_PORT', 'postgres', hosts, 'docker', null);
-
-    // Build envVars map and ensure it has the correct values
     const envVars = await buildEnvVarMap('docker');
-    // Override with the actual values that were just set by rewriteInfraEndpoints
     envVars.REDIS_HOST = redisHost;
     envVars.REDIS_PORT = String(redisPort);
     envVars.DB_HOST = dbHost;
@@ -269,35 +284,15 @@ async function applyEnvironmentTransformations(resolved, environment, variablesP
   return resolved;
 }
 
-/**
- * Generates .env file content from template and secrets (without writing to disk)
- * @async
- * @function generateEnvContent
- * @param {string} appName - Name of the application
- * @param {string} [secretsPath] - Path to secrets file (optional)
- * @param {string} [environment='local'] - Environment context
- * @param {boolean} [force=false] - Generate missing secret keys in secrets file
- * @returns {Promise<string>} Generated .env file content
- * @throws {Error} If generation fails
- */
+/** Generates .env file content from template and secrets (without writing to disk). */
 async function generateEnvContent(appName, secretsPath, environment = 'local', force = false) {
   const builderPath = pathsUtil.getBuilderPath(appName);
   const templatePath = path.join(builderPath, 'env.template');
   const variablesPath = path.join(builderPath, 'variables.yaml');
-
   const template = loadEnvTemplate(templatePath);
   const secretsPaths = await getActualSecretsPath(secretsPath, appName);
-
   if (force) {
-    // Use the same path resolution logic as loadSecrets
-    // If explicit path provided, use it; otherwise use the path that loadUserSecrets() would use
-    let secretsFileForGeneration;
-    if (secretsPath) {
-      secretsFileForGeneration = resolveSecretsPath(secretsPath);
-    } else {
-      // Use the same path that loadUserSecrets() would use (now uses paths.getAifabrixHome())
-      secretsFileForGeneration = secretsPaths.userPath;
-    }
+    const secretsFileForGeneration = secretsPath ? resolveSecretsPath(secretsPath) : secretsPaths.userPath;
     await generateMissingSecrets(template, secretsFileForGeneration);
   }
 
@@ -472,9 +467,6 @@ REDIS_COMMANDER_PASSWORD=${postgresPassword}
   fs.writeFileSync(adminEnvPath, adminSecrets, { mode: 0o600 });
   return adminEnvPath;
 }
-
-// validateSecrets is imported from ./utils/secrets-helpers
-
 module.exports = {
   loadSecrets,
   resolveKvReferences,