@aifabrix/builder 2.44.5 → 2.44.6

package/lib/utils/bash-secret-env.js

@@ -0,0 +1,59 @@
+/**
+ * Map secrets keys `BASH_<NAME>` to process-style env `{ [NAME]: value }` for child_process env.
+ * Same naming rule as kv://BASH_* resolution (see secrets-bash-kv.js).
+ *
+ * @fileoverview BASH-prefixed secret → exported-style env for Docker/subprocess
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const secretsLoad = require('../core/secrets-load');
+
+/**
+ * @param {string} suffix - Part after BASH_
+ * @returns {boolean}
+ */
+function isValidExportedName(suffix) {
+  return Boolean(suffix && /^[A-Za-z_][A-Za-z0-9_]*$/.test(suffix));
+}
+
+/**
+ * Collect `BASH_*` entries from a flat or shallow secrets object.
+ *
+ * @param {Record<string, unknown>|null|undefined} secrets - Merged secrets map (decrypted)
+ * @returns {Record<string, string>} e.g. { NPM_TOKEN: '...' } from BASH_NPM_TOKEN
+ */
+function collectBashPrefixedEnv(secrets) {
+  const out = {};
+  if (!secrets || typeof secrets !== 'object') return out;
+  for (const [k, v] of Object.entries(secrets)) {
+    if (typeof k !== 'string' || !k.startsWith('BASH_')) continue;
+    if (v === undefined || v === null) continue;
+    const str = typeof v === 'string' ? v.trim() : String(v).trim();
+    if (!str) continue;
+    const suffix = k.slice(5);
+    if (!isValidExportedName(suffix)) continue;
+    out[suffix] = str;
+  }
+  return out;
+}
+
+/**
+ * Overlay for `child_process` `env`: values from user + shared + ancestor `secrets.local.yaml`
+ * for every `BASH_*` key (merged via {@link secretsLoad.loadSecrets}).
+ *
+ * @param {string|null} [secretsPath] - Optional explicit secrets file (same as resolve)
+ * @param {string|null} [appName] - Optional app name for loadSecrets second arg
+ * @returns {Promise<Record<string, string>>}
+ */
+async function getBashPrefixedProcessEnvOverlay(secretsPath = null, appName = null) {
+  const secrets = await secretsLoad.loadSecrets(secretsPath, appName);
+  return collectBashPrefixedEnv(secrets);
+}
+
+module.exports = {
+  collectBashPrefixedEnv,
+  getBashPrefixedProcessEnvOverlay
+};

package/lib/utils/cli-secrets-error-format.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Missing-secrets CLI error lines (layout colors via cli-layout-chalk).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { metadata, sectionTitle } = require('./cli-layout-chalk');
+
+/**
+ * @param {string[]} messages - Output lines
+ * @param {RegExpMatchArray|null} missingSecretsMatch - Missing secrets capture
+ */
+function pushMissingSecretsBodyLines(messages, missingSecretsMatch) {
+  if (missingSecretsMatch) {
+    const parts = missingSecretsMatch[1]
+      .trim()
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (parts.length > 1) {
+      messages.push(`   ${sectionTitle('Missing secrets:')}`);
+      for (const ref of parts) {
+        messages.push(`   ${chalk.cyan('-')} ${chalk.white(ref)}`);
+      }
+      return;
+    }
+    if (parts.length === 1) {
+      messages.push(`   ${sectionTitle('Missing secrets:')} ${chalk.white(parts[0])}`);
+      return;
+    }
+    messages.push(`   ${sectionTitle('Missing secrets:')}`);
+    return;
+  }
+  messages.push(`   ${chalk.white('Missing secrets in secrets file.')}`);
+}
+
+/**
+ * @param {string[]} messages - Output lines
+ * @param {RegExpMatchArray|null} fileInfoMatch - File location capture
+ * @param {RegExpMatchArray|null} resolveMatch - Resolve command capture
+ */
+function pushSecretsResolutionHintLines(messages, fileInfoMatch, resolveMatch) {
+  if (fileInfoMatch) {
+    messages.push(`   ${metadata('Secrets file location:')} ${chalk.white(fileInfoMatch[1])}`);
+  }
+  if (resolveMatch) {
+    messages.push(
+      `   ${metadata('Run:')} ${chalk.yellow(`aifabrix resolve ${resolveMatch[1]} to generate missing secrets.`)}`
+    );
+    return;
+  }
+  messages.push(`   ${metadata('Run:')} ${chalk.yellow('aifabrix resolve <app-name> to generate missing secrets.')}`);
+}
+
+/**
+ * Format secrets-related errors
+ * @param {string} errorMsg - Error message
+ * @returns {string[]|null} Array of error message lines or null if not a secrets error
+ */
+function formatSecretsError(errorMsg) {
+  if (!errorMsg.includes('Missing secrets')) {
+    return null;
+  }
+
+  const messages = [];
+  pushMissingSecretsBodyLines(messages, errorMsg.match(/Missing secrets: ([^\n]+)/));
+  pushSecretsResolutionHintLines(
+    messages,
+    errorMsg.match(/Secrets file location: ([^\n]+)/),
+    errorMsg.match(/Run "aifabrix resolve ([^"]+)"/)
+  );
+  return messages;
+}
+
+module.exports = { formatSecretsError };

package/lib/utils/cli-test-layout-chalk.js

@@ -7,6 +7,18 @@
 
 const chalk = require('chalk');
 
+/**
+ * Invoke chalk[method](text) when the mock/real chalk exposes that method; otherwise return text.
+ * Keeps layout helpers working in Jest suites that only stub a subset of chalk.
+ * @param {string} method - chalk method name (e.g. 'white', 'bold', 'gray')
+ * @param {string} text
+ * @returns {string}
+ */
+function chalkStyle(method, text) {
+  const fn = chalk[method];
+  return typeof fn === 'function' ? fn(text) : text;
+}
+
 /** Canonical success glyph (green), layout §CORE / §3. */
 function successGlyph() {
   return chalk.green('✔');
@@ -35,6 +47,15 @@ function formatSuccessParagraph(message) {
   return chalk.green(`\n✔ ${message}`);
 }
 
+/**
+ * Non-blocking warning (layout §CORE): yellow ⚠ + white detail.
+ * @param {string} message - text after the glyph (do not prefix with ⚠)
+ * @returns {string}
+ */
+function formatWarningLine(message) {
+  return `${chalkStyle('yellow', '⚠')} ${chalkStyle('white', message)}`;
+}
+
 /**
  * Blocking error line: red ✖ + red message (layout §18).
  * @param {string} message
@@ -65,7 +86,7 @@ function formatIssue(title, hint) {
  */
 function formatNextActions(lines) {
   const body = (lines || [])
-    .map(line => `${chalk.cyan('-')} ${chalk.white(line)}`)
+    .map(line => `${chalkStyle('cyan', '-')} ${chalkStyle('white', line)}`)
     .join('\n');
   return `${sectionTitle('Next actions:')}\n${body}`;
 }
@@ -87,7 +108,7 @@ function formatDocsLine(label, url) {
  * @returns {string}
  */
 function formatProgress(message) {
-  return `${chalk.yellow('⏳')} ${chalk.white(message)}`;
+  return `${chalkStyle('yellow', '⏳')} ${chalkStyle('white', message)}`;
 }
 
 /**
@@ -99,7 +120,7 @@ function formatProgress(message) {
  */
 function formatBulletSection(title, items, opts) {
   const bulletColor = opts && opts.bullet === 'red' ? chalk.red : chalk.cyan;
-  const body = (items || []).map(line => `${bulletColor('-')} ${chalk.white(line)}`).join('\n');
+  const body = (items || []).map(line => `${bulletColor('-')} ${chalkStyle('white', line)}`).join('\n');
   return `${sectionTitle(title)}\n${body}`;
 }
 
@@ -109,7 +130,7 @@ function formatBulletSection(title, items, opts) {
  * @returns {string}
  */
 function sectionTitle(text) {
-  return chalk.white.bold(text);
+  return chalkStyle('bold', chalkStyle('white', text));
 }
 
 /**
@@ -119,7 +140,7 @@ function sectionTitle(text) {
  * @returns {string}
  */
 function headerKeyValue(label, value) {
-  return `${chalk.gray(label)} ${chalk.white.bold(value)}`;
+  return `${chalkStyle('gray', label)} ${chalkStyle('bold', chalkStyle('white', value))}`;
 }
 
 /**
@@ -201,7 +222,7 @@ function formatDatasourceListRow(rowStatus, name, statusHint) {
           ? chalk.red('✖')
           : chalk.gray('⏭');
   const hint = statusHint ? ` ${chalk.gray(`(${statusHint})`)}` : '';
-  return `  ${sym} ${chalk.white(name)}${hint}`;
+  return `  ${sym} ${chalkStyle('white', name)}${hint}`;
 }
 
 /**
@@ -232,13 +253,13 @@ function colorRollupPrefixedLine(line) {
   const trimmed = line.trimStart();
   const first = trimmed[0];
   if (first === '✔') {
-    return chalk.green('✔') + chalk.white(trimmed.slice(1));
+    return chalk.green('✔') + chalkStyle('white', trimmed.slice(1));
   }
   if (first === '⚠') {
-    return chalk.yellow('⚠') + chalk.white(trimmed.slice(1));
+    return chalk.yellow('⚠') + chalkStyle('white', trimmed.slice(1));
   }
   if (first === '✖') {
-    return chalk.red('✖') + chalk.white(trimmed.slice(1));
+    return chalk.red('✖') + chalkStyle('white', trimmed.slice(1));
   }
   return line;
 }
@@ -258,6 +279,7 @@ module.exports = {
   failureGlyph,
   formatSuccessLine,
   formatSuccessParagraph,
+  formatWarningLine,
   formatBlockingError,
   formatIssue,
   formatNextActions,

package/lib/utils/cli-utils.js

@@ -11,6 +11,8 @@
 const path = require('path');
 const chalk = require('chalk');
 const logger = require('./logger');
+const { formatBlockingError, infoLine } = require('./cli-layout-chalk');
+const { formatSecretsError } = require('./cli-secrets-error-format');
 const { getDockerDaemonStartHintSentence, getDockerApiOverTcpHintLines } = require('./docker-not-running-hint');
 
 /**
@@ -231,40 +233,6 @@ function formatAzureError(errorMsg) {
   return null;
 }
 
-/**
- * Format secrets-related errors
- * @param {string} errorMsg - Error message
- * @returns {string[]|null} Array of error message lines or null if not a secrets error
- */
-function formatSecretsError(errorMsg) {
-  if (!errorMsg.includes('Missing secrets')) {
-    return null;
-  }
-
-  const messages = [];
-  const missingSecretsMatch = errorMsg.match(/Missing secrets: ([^\n]+)/);
-  const fileInfoMatch = errorMsg.match(/Secrets file location: ([^\n]+)/);
-  const resolveMatch = errorMsg.match(/Run "aifabrix resolve ([^"]+)"/);
-
-  if (missingSecretsMatch) {
-    messages.push(`   Missing secrets: ${missingSecretsMatch[1]}`);
-  } else {
-    messages.push('   Missing secrets in secrets file.');
-  }
-
-  if (fileInfoMatch) {
-    messages.push(`   Secrets file location: ${fileInfoMatch[1]}`);
-  }
-
-  if (resolveMatch) {
-    messages.push(`   Run: aifabrix resolve ${resolveMatch[1]} to generate missing secrets.`);
-  } else {
-    messages.push('   Run: aifabrix resolve <app-name> to generate missing secrets.');
-  }
-
-  return messages;
-}
-
 /**
  * Format deployment-related errors
  * @param {string} errorMsg - Error message
@@ -388,9 +356,9 @@ function formatError(error) {
  * @param {string[]} errorMessages - Error message lines
  */
 function logError(command, errorMessages) {
-  logger.error(`\n✖ Error in ${command} command:`);
+  logger.error(`\n${formatBlockingError(`Error in ${command} command:`)}`);
   errorMessages.forEach(msg => logger.error(msg));
-  logger.error('\n💡 Run "aifabrix doctor" for environment diagnostics.\n');
+  logger.log(`\n${infoLine('ℹ Run "aifabrix doctor" for environment diagnostics.')}\n`);
 }
 
 /**

package/lib/utils/datasource-test-run-display.js

@@ -300,12 +300,20 @@ function appendValidationIssueLines(lines, envelope, maxIssues = 5) {
     const code = iss && iss.code ? chalk.red(`[${iss.code}] `) : '';
     const msg = iss && iss.message ? String(iss.message) : JSON.stringify(iss);
     lines.push(`  ${code}${chalk.yellow(msg)}`);
+    appendDpSec013Details(lines, iss);
   }
   if (issues.length > cap) {
     lines.push(chalk.gray(`  … and ${issues.length - cap} more (see --json or debug full/raw)`));
   }
 }
 
+function appendDpSec013Details(lines, iss) {
+  if (!iss || iss.code !== 'DP-SEC-013') return;
+  const perm = iss.details && iss.details.resolvedPermission ? String(iss.details.resolvedPermission) : '';
+  if (!perm) return;
+  lines.push(`    ${chalk.gray('Missing permission:')} ${chalk.white(perm)}`);
+}
+
 /**
  * @param {string[]} lines
  * @param {Object} envelope

package/lib/utils/dev-hosts-helper.js

@@ -12,6 +12,7 @@ const path = require('path');
 const readline = require('readline');
 const chalk = require('chalk');
 const { nodeFs } = require('../internal/node-fs');
+const { formatSuccessLine } = require('./cli-layout-chalk');
 
 const IPV4_RE = /^(25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)){3}$/;
 
@@ -238,7 +239,7 @@ async function resolveHostsIpForInit(hostname, hostsIp, logger) {
 async function appendHostsBlockOrPrintManual(hostsPath, block, line, logger) {
   try {
     await nodeFs().promises.appendFile(hostsPath, block, { encoding: 'utf8' });
-    logger.log(chalk.green(`  ✔ Updated ${hostsPath}\n`));
+    logger.log(chalk.green('  ') + formatSuccessLine(`Updated ${hostsPath}`) + '\n');
   } catch (e) {
     if (e.code === 'EACCES' || e.code === 'EPERM') {
       logger.log(chalk.yellow(`  ✖ Could not write ${hostsPath} (permission denied).`));
@@ -261,7 +262,7 @@ async function appendHostsBlockOrPrintManual(hostsPath, block, line, logger) {
 async function tryWriteHostsEntry(hostsPath, hostnames, ip, skipConfirm, logger) {
   const missing = hostnames.filter((h) => !hostsFileHasHostname(hostsPath, h));
   if (missing.length === 0) {
-    logger.log(chalk.green(`  ✔ Required hostnames are already listed in ${hostsPath}. Nothing to do.\n`));
+    logger.log(chalk.green('  ') + formatSuccessLine(`Required hostnames are already listed in ${hostsPath}. Nothing to do.`) + '\n');
     return;
   }
   const line = `${ip} ${missing.join(' ')}`;

package/lib/utils/dev-init-ssh-merge.js

@@ -6,6 +6,7 @@ const chalk = require('chalk');
 const config = require('../core/config');
 const logger = require('./logger');
 const { ensureDevSshConfigBlock } = require('./dev-ssh-config-helper');
+const { successGlyph } = require('./cli-layout-chalk');
 
 /**
  * Hostname from Builder Server URL (for sync-ssh-host fallback).
@@ -46,7 +47,7 @@ async function mergeDevSshConfigAfterInit(baseUrl, devId) {
         );
       } else {
         logger.log(
-          chalk.green('  ✔ SSH config updated: ') +
+          `${chalk.green('  ')}${successGlyph()}${chalk.green(' SSH config updated: ')}` +
             chalk.cyan(`Host ${res.hostAlias}`) +
             chalk.gray(` → ${res.configPath}`)
         );

package/lib/utils/docker-build.js

@@ -1,4 +1,4 @@
-const { formatSuccessLine } = require('./cli-test-layout-chalk');
+const { formatSuccessLine, headerKeyValue, formatWarningLine } = require('./cli-test-layout-chalk');
 /**
  * Docker Build Utilities
  *
@@ -177,7 +177,6 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
   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);
 
@@ -196,7 +195,8 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
   }
 
   const isTest = process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined;
-  const remoteEnv = isTest ? {} : await getRemoteDockerEnv();
+  const { getDockerExecEnv } = require('./remote-docker-env');
+  const dockerCliEnv = isTest ? { ...process.env } : await getDockerExecEnv();
   const resolvedBuildArgs = buildArgs && typeof buildArgs === 'object' ? buildArgs : {};
   return new Promise((resolve, reject) => {
     runDockerBuildProcess({
@@ -207,7 +207,7 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
       spinner,
       resolve,
       reject,
-      env: remoteEnv,
+      env: dockerCliEnv,
       buildArgs: resolvedBuildArgs,
       noCache
     });
@@ -258,14 +258,20 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
  */
 async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfilePath, contextPath, tag, options) {
   const logger = require('../utils/logger');
-  const chalk = require('chalk');
 
-  logger.log(chalk.blue(`Using Dockerfile: ${dockerfilePath}`));
-  logger.log(chalk.blue(`Using build context: ${contextPath}`));
+  logger.log(headerKeyValue('Dockerfile:', dockerfilePath));
+  logger.log(headerKeyValue('Build context:', contextPath));
 
   await executeBuild(effectiveImageName, dockerfilePath, contextPath, tag, options);
 
-  // Back-compat: also tag the built dev image as the base image name
+  const wantCompatTag =
+    effectiveImageName !== imageName &&
+    options &&
+    options.base === true;
+  if (!wantCompatTag) {
+    return;
+  }
+
   try {
     const { promisify } = require('util');
     const { exec } = require('child_process');
@@ -275,7 +281,9 @@ async function executeDockerBuildWithTag(effectiveImageName, imageName, dockerfi
     await run(`docker tag ${effectiveImageName}:${tag} ${imageName}:${tag}`, { env });
     logger.log(formatSuccessLine(`Tagged image: ${imageName}:${tag}`));
   } catch (err) {
-    logger.log(chalk.yellow(`⚠  Warning: Could not create compatibility tag ${imageName}:${tag} - ${err.message}`));
+    logger.log(
+      formatWarningLine(`Could not create compatibility tag ${imageName}:${tag} - ${err.message}`)
+    );
   }
 }
 

package/lib/utils/docker-reload-mount.js

@@ -0,0 +1,127 @@
+/**
+ * Decide whether `aifabrix run --reload` can bind-mount workspace without Mutagen.
+ * Mutagen is only needed when the CLI filesystem and the Docker engine host differ.
+ *
+ * @fileoverview Co-located Docker detection for reload mounts
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const os = require('os');
+
+/**
+ * @param {string} host
+ * @returns {string}
+ */
+function normalizeHost(host) {
+  return String(host || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '');
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLocalLoopbackHost(host) {
+  const h = normalizeHost(host);
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '0:0:0:0:0:0:0:1';
+}
+
+/**
+ * @param {string} rest - after "tcp://"
+ * @returns {string|null}
+ */
+function tcpHostFromRest(rest) {
+  if (rest.startsWith('[')) {
+    const end = rest.indexOf(']');
+    if (end === -1) return null;
+    return normalizeHost(rest.slice(1, end));
+  }
+  const hostPort = rest.split('/')[0];
+  const colonIdx = hostPort.lastIndexOf(':');
+  if (colonIdx === -1) {
+    return normalizeHost(hostPort);
+  }
+  const maybePort = hostPort.slice(colonIdx + 1);
+  if (/^\d+$/.test(maybePort)) {
+    return normalizeHost(hostPort.slice(0, colonIdx));
+  }
+  return normalizeHost(hostPort);
+}
+
+/**
+ * Extract host from docker-endpoint (tcp, optional URL form).
+ * @param {string} endpoint
+ * @returns {string|null} normalized host, or null for unix socket paths / empty
+ */
+function extractHostFromDockerEndpoint(endpoint) {
+  const s = String(endpoint || '').trim();
+  if (!s) return null;
+  const lower = s.toLowerCase();
+  if (lower.startsWith('unix:')) {
+    return null;
+  }
+  if (lower.startsWith('tcp://')) {
+    return tcpHostFromRest(s.slice(6));
+  }
+  try {
+    const u = new URL(s.includes('://') ? s : `tcp://${s}`);
+    return normalizeHost(u.hostname);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * sync-ssh-host localhost check (same rules as run.js isLocalhostHost for reload gate).
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLocalhostSyncSshHost(host) {
+  if (!host || typeof host !== 'string') return false;
+  const h = host.trim().toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1';
+}
+
+/**
+ * True when docker API host is this machine (first label or FQDN match).
+ * @param {string} dockerHost - from extractHostFromDockerEndpoint
+ * @returns {boolean}
+ */
+function hostnameMatchesDockerHost(dockerHost) {
+  const h = normalizeHost(dockerHost);
+  if (!h) return true;
+  if (isLocalLoopbackHost(h)) return true;
+  const hn = normalizeHost(os.hostname());
+  if (h === hn) return true;
+  const hnShort = hn.split('.')[0];
+  const hShort = h.split('.')[0];
+  if (h === hnShort || hn === hShort) return true;
+  return false;
+}
+
+/**
+ * When true, use a direct bind mount for --reload; Mutagen is not required.
+ * @param {string|null|undefined} dockerEndpoint - config `docker-endpoint`
+ * @returns {boolean}
+ */
+function isReloadBindMountOnEngineHost(dockerEndpoint) {
+  const e = String(dockerEndpoint || '').trim();
+  if (!e) return true;
+  if (e.toLowerCase().startsWith('unix:')) return true;
+  const host = extractHostFromDockerEndpoint(e);
+  if (host === null) {
+    return false;
+  }
+  return hostnameMatchesDockerHost(host);
+}
+
+module.exports = {
+  extractHostFromDockerEndpoint,
+  isReloadBindMountOnEngineHost,
+  isLocalhostSyncSshHost
+};

package/lib/utils/external-readme.js

@@ -15,6 +15,72 @@ const path = require('path');
 const handlebars = require('handlebars');
 const { getProjectRoot } = require('./paths');
 
+/**
+ * Extracts secret keys from integration/<appName>/env.template when present.
+ * Looks for values like `kv://systemKey/apiKey` and returns that key for
+ * `aifabrix secret set <key> <value>`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.appName
+ * @returns {Array<{path: string, description: string}>}
+ */
+function extractSecretPathsFromEnvTemplate({ projectRoot, appName }) {
+  if (!projectRoot || !appName) return [];
+
+  const envTemplatePath = path.join(projectRoot, 'integration', appName, 'env.template');
+  if (!fs.existsSync(envTemplatePath)) return [];
+
+  const raw = _tryReadTextOrNull(envTemplatePath);
+  if (raw === null) return [];
+  if (typeof raw !== 'string') return [];
+
+  function parseSecretKey(value) {
+    if (!value || typeof value !== 'string') return null;
+    const kvIdx = value.indexOf('kv://');
+    if (kvIdx === -1) return null;
+    const after = value.slice(kvIdx + 'kv://'.length);
+    const key = after.split(/[ \t#]/)[0]?.trim();
+    return key || null;
+  }
+
+  function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return null;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx <= 0) return null;
+    const varName = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    const key = parseSecretKey(value);
+    if (!key) return null;
+    return { varName: varName || 'Secret', key };
+  }
+
+  const out = [];
+  const seen = new Set();
+
+  for (const line of raw.split('\n')) {
+    const parsed = parseLine(line);
+    if (!parsed) continue;
+    const dedupeKey = `${parsed.varName}::${parsed.key}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    out.push({ path: parsed.key, description: parsed.varName });
+  }
+
+  return out;
+}
+
+function _tryReadTextOrNull(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    // Some Jest suites partially mock fs.existsSync; treat missing files as absent templates.
+    if (e && e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
 /**
  * Formats a display name from a key
  * @param {string} key - System or app key
@@ -179,7 +245,9 @@ function buildExternalReadmeContext(params = {}) {
   const normalizedExt = fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`;
   const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
   const authType = params.authType || params.authentication?.type || params.authentication?.method || params.authentication?.authType;
-  const secretPaths = buildSecretPaths(systemKey, authType);
+  const projectRoot = getProjectRoot();
+  const secretPathsFromEnv = extractSecretPathsFromEnvTemplate({ projectRoot, appName });
+  const secretPaths = secretPathsFromEnv.length > 0 ? secretPathsFromEnv : buildSecretPaths(systemKey, authType);
   const rbacOptionalFile = rbacOptionalFilename(normalizedExt);
 
   return {
@@ -238,5 +306,6 @@ module.exports = {
   buildExternalReadmeContext,
   generateExternalReadmeContent,
   wrapPlainTextForMarkdown,
-  collapseConsecutiveBlankLines
+  collapseConsecutiveBlankLines,
+  extractSecretPathsFromEnvTemplate
 };