@aifabrix/builder 2.44.5 → 2.45.0

package/lib/utils/postgres-wipe.js

@@ -0,0 +1,212 @@
+/**
+ * Postgres data wipe helper for `aifabrix setup` Mode 2 (Wipe data).
+ *
+ * Drops every non-template database and every non-superuser role in the
+ * developer's running Postgres container, while preserving the volume,
+ * the `postgres` superuser, and the admin password (so the post-wipe
+ * `up-infra` and platform bootstrap recreate schemas + service users).
+ *
+ * Uses `docker exec` with the admin password passed via the container's
+ * environment (PGPASSWORD) so it is not visible in `ps`.
+ *
+ * @fileoverview Drop all DBs and roles in dev Postgres for setup Mode 2
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const adminSecrets = require('../core/admin-secrets');
+const dockerExec = require('./docker-exec');
+const logger = require('./logger');
+const chalk = require('chalk');
+const { successGlyph } = require('./cli-test-layout-chalk');
+
+/** Roles that must never be dropped (Postgres-managed predefined roles). */
+const PROTECTED_ROLES = new Set([
+  // In this project, infra starts Postgres with POSTGRES_USER=pgadmin (see templates/infra/compose.yaml.hbs),
+  // so that role is the superuser we must preserve.
+  'pgadmin',
+  // Legacy / default superuser name for official Postgres images.
+  'postgres',
+  'pg_signal_backend',
+  'pg_read_server_files',
+  'pg_write_server_files',
+  'pg_execute_server_program',
+  'pg_monitor',
+  'pg_read_all_settings',
+  'pg_read_all_stats',
+  'pg_stat_scan_tables',
+  'pg_database_owner',
+  'pg_read_all_data',
+  'pg_write_all_data',
+  'pg_checkpoint',
+  'pg_use_reserved_connections',
+  'pg_create_subscription'
+]);
+
+/** Databases that must never be dropped. */
+const PROTECTED_DATABASES = new Set(['postgres', 'template0', 'template1']);
+
+/** Superuser role used inside the infra Postgres container. */
+const SUPERUSER_ROLE = 'pgadmin';
+
+/**
+ * Compute the developer-scoped Postgres container name.
+ * Mirrors `getInfraContainerNames` in `lib/utils/infra-status.js`.
+ * @param {number|string} devId - Developer ID
+ * @returns {string}
+ */
+function getPostgresContainerName(devId) {
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  if (idNum === 0) return 'aifabrix-postgres';
+  return `aifabrix-dev${devId}-postgres`;
+}
+
+/**
+ * Run `psql -t -A -c <sql>` inside the Postgres container with PGPASSWORD set
+ * via `-e PGPASSWORD=...` so the secret never appears on the command line.
+ *
+ * @async
+ * @param {string} container - Container name
+ * @param {string} sql - Single SQL statement (no shell metacharacters)
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string>} stdout (trimmed)
+ * @throws {Error} If the docker exec invocation fails
+ */
+async function runPsql(container, sql, adminPassword) {
+  if (!container || typeof container !== 'string') {
+    throw new Error('Postgres container name is required');
+  }
+  if (!sql || typeof sql !== 'string') {
+    throw new Error('SQL statement is required');
+  }
+  if (!adminPassword || typeof adminPassword !== 'string') {
+    throw new Error('Admin password is required');
+  }
+  const escapedSql = sql.replace(/"/g, '\\"');
+  const cmd = `docker exec -e PGPASSWORD -i ${container} psql -U ${SUPERUSER_ROLE} -d postgres -tAc "${escapedSql}"`;
+  const env = { PGPASSWORD: adminPassword };
+  const result = (await dockerExec.execWithDockerEnv(cmd, { env })) || {};
+  return String(result.stdout || '').trim();
+}
+
+/**
+ * List user databases (non-template, not in PROTECTED_DATABASES).
+ * @async
+ * @param {string} container - Container name
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string[]>} database names
+ */
+async function listUserDatabases(container, adminPassword) {
+  const out = await runPsql(
+    container,
+    'SELECT datname FROM pg_database WHERE datistemplate = false;',
+    adminPassword
+  );
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(name => name && !PROTECTED_DATABASES.has(name));
+}
+
+/**
+ * List dropable roles (non-superuser, not in PROTECTED_ROLES).
+ * @async
+ * @param {string} container - Container name
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string[]>} role names
+ */
+async function listDropableRoles(container, adminPassword) {
+  const out = await runPsql(
+    container,
+    'SELECT rolname FROM pg_roles WHERE rolsuper = false;',
+    adminPassword
+  );
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(name => name && !PROTECTED_ROLES.has(name) && !name.startsWith('pg_'));
+}
+
+/**
+ * Drop a single database (forces disconnection of active sessions).
+ * @async
+ * @param {string} container
+ * @param {string} dbName
+ * @param {string} adminPassword
+ * @returns {Promise<void>}
+ */
+async function dropDatabase(container, dbName, adminPassword) {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(dbName)) {
+    throw new Error(`Refusing to drop database with unsafe name: ${dbName}`);
+  }
+  await runPsql(
+    container,
+    `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${dbName}' AND pid <> pg_backend_pid();`,
+    adminPassword
+  );
+  await runPsql(container, `DROP DATABASE IF EXISTS "${dbName}";`, adminPassword);
+}
+
+/**
+ * Drop a single role (REASSIGN OWNED + DROP OWNED first to clear dependencies).
+ * @async
+ * @param {string} container
+ * @param {string} role
+ * @param {string} adminPassword
+ * @returns {Promise<void>}
+ */
+async function dropRole(container, role, adminPassword) {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(role)) {
+    throw new Error(`Refusing to drop role with unsafe name: ${role}`);
+  }
+  await runPsql(
+    container,
+    `REASSIGN OWNED BY "${role}" TO ${SUPERUSER_ROLE};`,
+    adminPassword
+  ).catch(() => undefined);
+  await runPsql(container, `DROP OWNED BY "${role}" CASCADE;`, adminPassword).catch(() => undefined);
+  await runPsql(container, `DROP ROLE IF EXISTS "${role}";`, adminPassword);
+}
+
+/**
+ * Drop every non-template database and every non-superuser role in the
+ * developer's running Postgres container. Caller must ensure infra is up.
+ *
+ * @async
+ * @function wipePostgresData
+ * @returns {Promise<{ databases: string[], roles: string[] }>} dropped names
+ * @throws {Error} If admin secrets are missing or psql calls fail
+ */
+async function wipePostgresData() {
+  const devId = await config.getDeveloperId();
+  const container = getPostgresContainerName(devId);
+  const admin = await adminSecrets.readAndDecryptAdminSecrets();
+  const password = admin && admin.POSTGRES_PASSWORD;
+  if (!password) {
+    throw new Error('POSTGRES_PASSWORD not found in admin-secrets.env. Run "aifabrix up-infra" first.');
+  }
+
+  const databases = await listUserDatabases(container, password);
+  for (const dbName of databases) {
+    await dropDatabase(container, dbName, password);
+    logger.log(chalk.gray(` ${successGlyph()} Dropped database ${dbName}`));
+  }
+
+  const roles = await listDropableRoles(container, password);
+  for (const role of roles) {
+    await dropRole(container, role, password);
+    logger.log(chalk.gray(` ${successGlyph()} Dropped role ${role}`));
+  }
+
+  return { databases, roles };
+}
+
+module.exports = {
+  wipePostgresData,
+  getPostgresContainerName,
+  PROTECTED_DATABASES,
+  PROTECTED_ROLES
+};

package/lib/utils/register-aifabrix-shell-env.js

@@ -191,8 +191,23 @@ async function registerAifabrixShellEnvFromConfig(getConfigFn, overrides = {}) {
   await applyPosixShellEnv(homeAbs, workAbs, overrides);
 }
 
+/**
+ * Build sh export lines for AIFABRIX_HOME / AIFABRIX_WORK from current config (stdout for eval).
+ *
+ * @async
+ * @param {function(): Promise<object>} getConfigFn - Same as config.getConfig
+ * @returns {Promise<string>} Lines suitable for `eval "$(aifabrix dev shell-env)"` on bash/zsh
+ */
+async function buildShellEnvExportsFromConfig(getConfigFn) {
+  const config = await getConfigFn();
+  const homeAbs = absFromConfigRaw(config['aifabrix-home']);
+  const workAbs = absFromConfigRaw(config['aifabrix-work']);
+  return buildPosixShellEnvBody(homeAbs, workAbs);
+}
+
 module.exports = {
   registerAifabrixShellEnvFromConfig,
+  buildShellEnvExportsFromConfig,
   buildPosixShellEnvBody,
   buildProfileBlock,
   shSingleQuoted,

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

@@ -5,10 +5,25 @@
  */
 
 const path = require('path');
+const os = require('os');
 const config = require('../core/config');
 const { getCertDir, readClientCertPem, readServerCaPem } = require('./dev-cert-helper');
 const { getConfigDirForPaths, getAifabrixHome, getAifabrixWork } = require('./paths');
 
+/**
+ * Same rules as {@link module:lib/core/config.expandTilde} / {@link module:lib/core/config.getSecretsPath}.
+ * Inline here so `resolveSharedSecretsEndpoint` stays aligned with `getSecretsPath()` even when `getAifabrixSecretsPath()`
+ * returns the raw config string (tilde not expanded).
+ */
+function expandConfiguredSecretsTilde(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;
+}
+
 /**
  * Single API object so resolveSharedSecretsEndpoint and callers share one getRemoteDevAuth
  * (Jest spies and partial mocks work reliably).
@@ -54,16 +69,17 @@ const remoteDevAuth = {
     const trimmed = configuredPath.trim();
     if (!trimmed) return configuredPath;
     if (remoteDevAuth.isRemoteSecretsUrl(trimmed)) return trimmed.replace(/\/+$/, '');
+    const expanded = expandConfiguredSecretsTilde(trimmed);
     const auth = await remoteDevAuth.getRemoteDevAuth();
-    if (!auth) return configuredPath;
-    const abs = normalizeSharedSecretsFilePath(trimmed);
-    if (!abs) return configuredPath;
+    if (!auth) return expanded;
+    const abs = normalizeSharedSecretsFilePath(expanded);
+    if (!abs) return expanded;
     const home = path.normalize(getAifabrixHome());
-    if (isPathUnderDir(abs, home)) return configuredPath;
+    if (isPathUnderDir(abs, home)) return expanded;
     const work = getAifabrixWork();
     if (work) {
       const w = path.normalize(work);
-      if (isPathUnderDir(abs, w)) return configuredPath;
+      if (isPathUnderDir(abs, w)) return expanded;
     }
     const base = String(auth.serverUrl).replace(/\/+$/, '');
     return `${base}/api/dev/secrets`;

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

@@ -89,7 +89,15 @@ async function getDockerExecEnv() {
   if (overlay.DOCKER_HOST && !Object.prototype.hasOwnProperty.call(overlay, 'DOCKER_CERT_PATH')) {
     delete merged.DOCKER_CERT_PATH;
   }
-  return { ...merged, ...overlay };
+  let out = { ...merged, ...overlay };
+  try {
+    const { getBashPrefixedProcessEnvOverlay } = require('./bash-secret-env');
+    const bash = await getBashPrefixedProcessEnvOverlay();
+    out = { ...out, ...bash };
+  } catch {
+    /* ignore secrets load failures; Docker CLI still runs with process + remote env */
+  }
+  return out;
 }
 
 module.exports = { getRemoteDockerEnv, getDockerExecEnv };

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

@@ -1,13 +1,17 @@
 /**
- * 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.
+ * Load shared secrets from Builder Server when aifabrix-secrets is an http(s) URL,
+ * or from the configured shared YAML path when it targets a local file.
  *
  * @fileoverview Remote shared secrets loader for .env generation
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
+const fs = require('fs');
+const path = require('path');
 const config = require('../core/config');
+const { readYamlAtPath } = require('./secrets-canonical');
+const { ensureSecureFilePermissions } = require('./secure-file-permissions');
 
 /**
  * Fetches shared secrets from Builder Server when aifabrix-secrets is an http(s) URL.
@@ -50,20 +54,61 @@ async function loadRemoteSharedSecrets() {
  * 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)
+ * @param {Record<string, string>} [keySources] - Mutated: winning file/API label per key (decrypt hints)
+ * @param {string} [remoteSourceLabel] - Human-readable source for keys taken from remote
  * @returns {Object} Merged object
  */
-function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets) {
+function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets, keySources, remoteSourceLabel) {
   const merged = { ...userSecrets };
   if (!remoteSecrets || typeof remoteSecrets !== 'object') return merged;
+  const label = remoteSourceLabel || 'shared secrets API';
   for (const key of Object.keys(remoteSecrets)) {
     if (!(key in merged) || merged[key] === undefined || merged[key] === null || merged[key] === '') {
       merged[key] = remoteSecrets[key];
+      if (keySources) {
+        keySources[key] = label;
+      }
     }
   }
   return merged;
 }
 
+/**
+ * Raw secrets from the configured shared store only (`aifabrix-secrets`): remote Builder API or shared YAML file.
+ * Does not include primary user secrets or builder merges. Used to avoid duplicating shared keys into ~/.aifabrix.
+ *
+ * @returns {Promise<Object|null>} Key-value map or null when unavailable / not configured
+ */
+async function loadConfiguredSharedSecretsStore() {
+  const remoteDevAuth = require('./remote-dev-auth');
+  const configSecretsPath = await config.getSecretsPath();
+  if (!configSecretsPath) {
+    return null;
+  }
+  const endpoint = await remoteDevAuth.resolveSharedSecretsEndpoint(configSecretsPath);
+  if (remoteDevAuth.isRemoteSecretsUrl(endpoint)) {
+    return loadRemoteSharedSecrets();
+  }
+  const resolvedFile = path.isAbsolute(endpoint)
+    ? endpoint
+    : path.resolve(process.cwd(), endpoint);
+  if (!fs.existsSync(resolvedFile)) {
+    return null;
+  }
+  try {
+    ensureSecureFilePermissions(resolvedFile);
+    const data = readYamlAtPath(resolvedFile);
+    if (!data || typeof data !== 'object') {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
 module.exports = {
   loadRemoteSharedSecrets,
-  mergeUserWithRemoteSecrets
+  mergeUserWithRemoteSecrets,
+  loadConfiguredSharedSecretsStore
 };

package/lib/utils/resolve-docker-image-ref.js

@@ -73,16 +73,21 @@ function normalizeDockerRegistryPrefix(registry) {
  */
 function resolveDockerImageRef(appName, appConfig, runOptions = {}) {
   const opts = runOptions || {};
+  const tagFromOpts =
+    opts.tag !== undefined && opts.tag !== null && String(opts.tag).trim() !== ''
+      ? String(opts.tag).trim()
+      : null;
+
   if (opts.image) {
     const parsed = parseImageOverride(opts.image);
     return {
       imageName: parsed ? parsed.name : getRepositoryPathFromConfig(appConfig, appName),
-      imageTag: parsed ? parsed.tag : imageTagFromConfig(appConfig)
+      imageTag: parsed ? parsed.tag : tagFromOpts || imageTagFromConfig(appConfig)
     };
   }
 
   const baseRepo = getRepositoryPathFromConfig(appConfig, appName);
-  const imageTag = imageTagFromConfig(appConfig);
+  const imageTag = tagFromOpts || imageTagFromConfig(appConfig);
   const prefix =
     normalizeDockerRegistryPrefix(opts.registry) ||
     normalizeDockerRegistryPrefix(appConfig?.image?.registry ?? '');
@@ -120,5 +125,6 @@ module.exports = {
   resolveDockerImageRef,
   resolveComposeImageOverrideString,
   normalizeDockerRegistryPrefix,
-  getRepositoryPathFromConfig
+  getRepositoryPathFromConfig,
+  imageTagFromConfig
 };

package/lib/utils/run-cli-flags.js

@@ -0,0 +1,29 @@
+/**
+ * Normalize Commander flags for `aifabrix run`.
+ *
+ * @fileoverview Commander v11 pairs `--no-proxy` with a default-true `--proxy` flag as `options.proxy === false`.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * True when the user disabled proxy hints: explicit `--no-proxy` or `proxy === false` when supported.
+ *
+ * @param {Object} [options] - Commander action options
+ * @returns {boolean}
+ */
+function isRunCliNoProxy(options) {
+  if (!options || typeof options !== 'object') {
+    return false;
+  }
+  if (options.proxy === false) {
+    return true;
+  }
+  return options.noProxy === true;
+}
+
+module.exports = {
+  isRunCliNoProxy
+};

package/lib/utils/secrets-ancestor-paths.js

@@ -0,0 +1,47 @@
+/**
+ * Collect `secrets.local.yaml` paths along the cwd → root walk so parent workspace
+ * secrets (e.g. `/workspace/.aifabrix/`) merge when the active config is nested
+ * (e.g. `repo/.aifabrix/` from cwd).
+ *
+ * @fileoverview Ancestor secrets.local.yaml discovery for loadSecrets cascade
+ */
+
+'use strict';
+
+const path = require('path');
+
+const MAX_ANCESTOR_STEPS = 64;
+
+/**
+ * @param {string} startDir - Directory to start from (typically process.cwd())
+ * @param {(p: string) => boolean} existsSyncFn - Sync existence check
+ * @returns {string[]} Absolute paths, nearest ancestor first (cwd-side), then parents
+ */
+function collectAncestorAifabrixSecretsLocalYamlPaths(startDir, existsSyncFn) {
+  if (!startDir || typeof startDir !== 'string' || typeof existsSyncFn !== 'function') {
+    return [];
+  }
+  const out = [];
+  const seen = new Set();
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < MAX_ANCESTOR_STEPS; i += 1) {
+    const secretsPath = path.join(dir, '.aifabrix', 'secrets.local.yaml');
+    if (existsSyncFn(secretsPath)) {
+      const abs = path.resolve(secretsPath);
+      if (!seen.has(abs)) {
+        seen.add(abs);
+        out.push(abs);
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return out;
+}
+
+module.exports = {
+  collectAncestorAifabrixSecretsLocalYamlPaths
+};

package/lib/utils/secrets-canonical.js

@@ -31,11 +31,14 @@ function readYamlAtPath(filePath) {
  * @param {string} key - Secret key
  * @param {*} canonicalValue - Value from canonical secrets
  */
-function mergeSecretValue(result, key, canonicalValue) {
+function mergeSecretValue(result, key, canonicalValue, keySources, canonicalSourcePath) {
   const currentValue = result[key];
   // Fill missing, empty, or undefined values
   if (!(key in result) || currentValue === undefined || currentValue === null || currentValue === '') {
     result[key] = canonicalValue;
+    if (keySources && canonicalSourcePath) {
+      keySources[key] = canonicalSourcePath;
+    }
     return;
   }
   // Only replace values that are encrypted (have secure:// prefix)
@@ -43,6 +46,9 @@ function mergeSecretValue(result, key, canonicalValue) {
   if (typeof currentValue === 'string' && typeof canonicalValue === 'string') {
     if (currentValue.startsWith('secure://')) {
       result[key] = canonicalValue;
+      if (keySources && canonicalSourcePath) {
+        keySources[key] = canonicalSourcePath;
+      }
     }
   }
 }
@@ -52,9 +58,10 @@ function mergeSecretValue(result, key, canonicalValue) {
  * @async
  * @function applyCanonicalSecretsOverride
  * @param {Object} currentSecrets - Current secrets map
+ * @param {Record<string, string>} [keySources] - Mutated: per-key source path when a value is taken from canonical YAML
  * @returns {Promise<Object>} Possibly overridden secrets
  */
-async function applyCanonicalSecretsOverride(currentSecrets) {
+async function applyCanonicalSecretsOverride(currentSecrets, keySources) {
   let mergedSecrets = currentSecrets || {};
   try {
     const canonicalPath = await config.getSecretsPath();
@@ -78,7 +85,7 @@ async function applyCanonicalSecretsOverride(currentSecrets) {
     // - Replace encrypted values (secure://) with canonical plaintext
     const result = { ...mergedSecrets };
     for (const [key, canonicalValue] of Object.entries(configSecrets)) {
-      mergeSecretValue(result, key, canonicalValue);
+      mergeSecretValue(result, key, canonicalValue, keySources, resolvedCanonical);
     }
     mergedSecrets = result;
   } catch {

package/lib/utils/secrets-helpers.js

@@ -19,6 +19,7 @@ const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
 const { getLocalPortFromPath } = require('./port-resolver');
 const { readYamlAtPath, applyCanonicalSecretsOverride } = require('./secrets-canonical');
+const { collectUniqueKvPathStrings } = require('./secrets-kv-refs');
 
 /**
  * Interpolate ${VAR} occurrences with values from envVars map
@@ -51,9 +52,13 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 /**
  * Last-resort when infra.parameter.yaml cannot be read (e.g. Jest suites that mock `fs`;
  * catalog uses `node:fs`, which is often the same mocked instance). Must stay in sync with
- * `generator.type: emptyAllowed` keys in lib/schema/infra.parameter.yaml.
+ * `generator.type: emptyAllowed` keys in lib/schema/infra.parameter.yaml; plus optional Azure/OpenAI kv names.
  */
-const EMPTY_ALLOWED_KV_FALLBACK = new Set(['redis-passwordKeyVault']);
+const EMPTY_ALLOWED_KV_FALLBACK = new Set([
+  'redis-passwordKeyVault',
+  'azure-openaiapi-urlKeyVault',
+  'secrets-azureOpenaiApiKeyVault'
+]);
 
 /**
  * Infra catalog keys with generator `emptyAllowed` may be absent from the secrets file;
@@ -191,7 +196,12 @@ function formatMissingSecretsFileInfo(secretsFilePaths) {
     if (secretsFilePaths.buildPath) {
       paths.push(secretsFilePaths.buildPath);
     }
-    return `\n\nSecrets file location: ${paths.join(' and ')}`;
+    let msg = `\n\nSecrets file location: ${paths.join(' and ')}`;
+    if (secretsFilePaths.sharedSecretsApiUrl && typeof secretsFilePaths.sharedSecretsApiUrl === 'string') {
+      msg +=
+        `\n(Shared secrets API: ${secretsFilePaths.sharedSecretsApiUrl.trim()}. Keys from that API are merged when resolving secrets; if a key is still missing, add it via "aifabrix secret set" / shared store or check "aifabrix secret list --shared".)`;
+    }
+    return msg;
   }
   return '';
 }
@@ -459,13 +469,7 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   return updated;
 }
 
-/**
- * Validate secrets against the env template (skips commented and empty lines)
- * @function validateSecrets
- * @param {string} envTemplate - Environment template content
- * @param {Object} secrets - Available secrets
- * @returns {Object} Validation result
- */
+/** Validate secrets vs env template (commented/empty lines skipped). */
 function validateSecrets(envTemplate, secrets) {
   const missing = collectMissingSecrets(envTemplate, secrets);
   return { valid: missing.length === 0, missing };
@@ -475,6 +479,9 @@ module.exports = {
   loadEnvConfig,
   interpolateEnvVars,
   collectMissingSecrets,
+  collectUniqueKvPathStrings,
+  resolveKvRefValue,
+  isKvKeyAllowedEmptyWhenAbsent,
   resolveBashKvFromProcessEnv,
   mergeSecretsWithPrefixedCopies,
   formatMissingSecretsFileInfo,

package/lib/utils/secrets-kv-refs.js

@@ -0,0 +1,42 @@
+/**
+ * Scan env-style content for unique kv:// path segments (comments skipped).
+ * @fileoverview Keeps secrets-helpers under max-lines
+ */
+
+'use strict';
+
+const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
+
+function isCommentOrEmptyLine(line) {
+  const t = line.trim();
+  return t === '' || t.startsWith('#');
+}
+
+/**
+ * @param {string} content
+ * @returns {string[]}
+ */
+function collectUniqueKvPathStrings(content) {
+  const seen = new Set();
+  const out = [];
+  if (!content || typeof content !== 'string') {
+    return out;
+  }
+  for (const line of content.split('\n')) {
+    if (isCommentOrEmptyLine(line)) continue;
+    let match;
+    KV_REF_PATTERN.lastIndex = 0;
+    while ((match = KV_REF_PATTERN.exec(line)) !== null) {
+      const pathStr = match[1];
+      if (!seen.has(pathStr)) {
+        seen.add(pathStr);
+        out.push(pathStr);
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  collectUniqueKvPathStrings
+};