@aifabrix/builder 2.45.5 → 2.47.0

package/lib/commands/verify-operations-persist.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Persist operations pillar to dataplane lifecycle (plan 150.0 / 419.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveExternalIntegrationContext } = require('./test-e2e-external');
+const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
+const { postValidationRun } = require('../api/validation-run.api');
+const { buildExternalDataSourceValidationRequest } = require('../utils/validation-run-request');
+
+/**
+ * Optional unit rollup stored in operations.details.reliability.unit.
+ * @param {Object} stepResults
+ * @returns {Object|undefined}
+ */
+function buildUnitTestSummary(stepResults) {
+  if (!stepResults || stepResults.unit !== true) {
+    return undefined;
+  }
+  return { passed: 1, failed: 0, skipped: 0 };
+}
+
+/**
+ * POST validation/run runType=operations for each active datasource (persists resultOperations).
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {Object} stepResults
+ * @returns {Promise<{ persisted: number }>}
+ */
+async function persistOperationsForSystem(systemKey, options, stepResults) {
+  const { systemKey: resolvedKey, keys } = resolveExternalIntegrationContext(systemKey);
+  if (keys.length === 0) {
+    return { persisted: 0 };
+  }
+
+  const { authConfig, dataplaneUrl } = await resolveIntegrationAuth(systemKey, options);
+
+  const timeoutMs = parseInt(String(options.timeout || '120000'), 10) || 120000;
+  const unitTestSummary = buildUnitTestSummary(stepResults);
+  let persisted = 0;
+
+  for (const dsKey of keys) {
+    const body = buildExternalDataSourceValidationRequest({
+      systemKey: resolvedKey,
+      datasourceKey: dsKey,
+      runType: 'operations'
+    });
+    if (unitTestSummary) {
+      body.unitTestSummary = unitTestSummary;
+    }
+
+    const res = await postValidationRun(dataplaneUrl, authConfig, body, { timeoutMs });
+    if (!res || res.success === false) {
+      const msg =
+        (res &&
+          res.error &&
+          (res.error.formattedError || res.error.error || res.error.message)) ||
+        res?.formattedError ||
+        'Operations lifecycle persist failed';
+      throw new Error(`${dsKey}: ${msg}`);
+    }
+    persisted += 1;
+  }
+
+  return { persisted };
+}
+
+module.exports = {
+  persistOperationsForSystem,
+  buildUnitTestSummary
+};

package/lib/commands/verify-operations-step-plan.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Step plan for verify-operations (plan 150.0).
+ */
+
+'use strict';
+
+const { validateExternalSystemComplete } = require('../validation/validate');
+const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
+const { runTestE2EForExternalSystem } = require('./test-e2e-external');
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {{ beforeSync: Array, afterSync: Array, e2e: Object }}
+ */
+function buildOperationsVerifyStepPlan(systemKey, options) {
+  return {
+    beforeSync: [
+      {
+        key: 'validation',
+        run: () => validateExternalSystemComplete(systemKey, { type: 'external' }),
+        ok: (result) => result.valid === true
+      },
+      {
+        key: 'unit',
+        run: () => testExternalSystem(systemKey, { verbose: false }),
+        ok: (result) => result.valid === true
+      }
+    ],
+    afterSync: [
+      {
+        key: 'integration',
+        run: () =>
+          testExternalSystemIntegration(systemKey, {
+            environment: options.env,
+            noSync: true,
+            verbose: false,
+            debug: options.debug === true
+          }),
+        ok: (result) => result.success === true
+      }
+    ],
+    e2e: {
+      key: 'e2e',
+      run: (progress) =>
+        runTestE2EForExternalSystem(systemKey, {
+          env: options.env,
+          noSync: true,
+          verbose: false,
+          debug: options.debug === true,
+          async: options.async !== false,
+          authConfig: options.authConfig,
+          dataplaneUrl: options.dataplaneUrl,
+          silentResolve: options.silentResolve === true,
+          quietPollUi: true,
+          onDatasourceProgress: progress?.setLabel
+            ? ({ key, index, total }) =>
+              progress.setLabel(`Running E2E: ${key} (${index + 1}/${total})`)
+            : undefined
+        }),
+      ok: (result) => result.success === true
+    }
+  };
+}
+
+module.exports = {
+  buildOperationsVerifyStepPlan
+};

package/lib/commands/verify-operations-steps.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview verify-operations step runners (plan 150.0).
+ */
+
+'use strict';
+
+const { syncLocalIfRequested } = require('./test-e2e-external');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { buildOperationsVerifyStepPlan } = require('./verify-operations-step-plan');
+const { runWithVerifyStepProgress } = require('../lifecycle/verify-step-progress');
+
+const STEP_PROGRESS = {
+  validation: 'Validating local integration',
+  unit: 'Running unit tests',
+  integration: 'Running integration tests on dataplane',
+  e2e: 'Running E2E tests'
+};
+
+/**
+ * @param {Object} options
+ * @param {Object} uploadCtx
+ */
+function attachUploadAuthToOptions(options, uploadCtx) {
+  if (!uploadCtx?.authConfig || !uploadCtx?.dataplaneUrl) {
+    return;
+  }
+  options.authConfig = uploadCtx.authConfig;
+  options.dataplaneUrl = uploadCtx.dataplaneUrl;
+  options.silentResolve = true;
+}
+
+/**
+ * @param {Function} runner
+ * @param {Function} isSuccess
+ * @param {Object} options
+ * @returns {Promise<boolean>}
+ */
+async function runVerifyStep(runner, isSuccess) {
+  const outcome = await runner();
+  return isSuccess(outcome);
+}
+
+/**
+ * @param {Object} stepResults
+ * @param {string} key
+ * @param {boolean} passed
+ * @param {boolean} continueOnFail
+ * @returns {boolean} false when the verify flow should stop early
+ */
+function recordVerifyStep(stepResults, key, passed, continueOnFail) {
+  stepResults[key] = passed;
+  return passed || continueOnFail;
+}
+
+/**
+ * @param {Object} stepResults
+ * @param {Object} step
+ * @param {boolean} continueOnFail
+ * @param {Object} options
+ * @returns {Promise<boolean>}
+ */
+async function runTrackedVerifyStep(stepResults, step, continueOnFail, options) {
+  const label = STEP_PROGRESS[step.key] || step.key;
+  const passed = await runWithVerifyStepProgress(
+    label,
+    async(progress) => runVerifyStep(() => step.run(progress), step.ok),
+    options
+  );
+  return recordVerifyStep(stepResults, step.key, passed, continueOnFail);
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ stepResults: Object, hardFailure: boolean, stoppedEarly: boolean }>}
+ */
+async function runOperationsVerifySteps(systemKey, options) {
+  const stepResults = { validation: false, unit: false, integration: false, e2e: false };
+  const continueOnFail = options.continue === true;
+  const plan = buildOperationsVerifyStepPlan(systemKey, options);
+
+  for (const step of plan.beforeSync) {
+    if (!(await runTrackedVerifyStep(stepResults, step, continueOnFail, options))) {
+      return { stepResults, hardFailure: true, stoppedEarly: true };
+    }
+  }
+
+  if (!cliOptsSkipSync(options)) {
+    const uploadCtx = await syncLocalIfRequested(systemKey, options);
+    attachUploadAuthToOptions(options, uploadCtx);
+  }
+
+  for (const step of plan.afterSync) {
+    if (!(await runTrackedVerifyStep(stepResults, step, continueOnFail, options))) {
+      return { stepResults, hardFailure: true, stoppedEarly: true };
+    }
+  }
+
+  const e2eLabel = STEP_PROGRESS.e2e;
+  stepResults.e2e = await runWithVerifyStepProgress(
+    e2eLabel,
+    async(progress) => runVerifyStep(() => plan.e2e.run(progress), plan.e2e.ok),
+    options
+  );
+  return { stepResults, hardFailure: !stepResults.e2e, stoppedEarly: false };
+}
+
+module.exports = {
+  runOperationsVerifySteps
+};

package/lib/commands/verify-trust-command-action.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview CLI action for `aifabrix verify-trust` (plan 150.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { runVerifyTrustForExternalSystem } = require('./verify-trust-external');
+const { normalizeTestTrustCliOptions } = require('./test-trust-cli-options');
+const { displayVerifyTrustTTY } = require('../lifecycle/report-display');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
+
+async function runVerifyTrustCommandAction(appName, options, cmd) {
+  const opts = normalizeTestTrustCliOptions(options, cmd);
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (!appType || appType.baseDir !== 'integration') {
+    throw new Error(
+      'verify-trust applies to external integration folders only (integration/<systemKey>/).'
+    );
+  }
+
+  const result = await runVerifyTrustForExternalSystem(appName, {
+    env: opts.env,
+    verbose: opts.verbose,
+    debug: opts.debug,
+    noSync: opts.noSync === true,
+    revalidate: opts.revalidate === true,
+    timeout: opts.timeout
+  });
+
+  if (opts.json) {
+    const envelope = buildJsonEnvelope(
+      {
+        systemKey: result.systemKey,
+        command: result.command,
+        verdict: result.verdict,
+        aiTrustPercent: result.aiTrustPercent,
+        accessConfidencePercent: result.accessConfidencePercent,
+        businessConfidencePercent: result.businessConfidencePercent,
+        findings: result.findings,
+        datasourceRows: opts.details ? result.datasourceRows : undefined
+      },
+      opts.details || opts.verbose
+    );
+    logger.log(JSON.stringify(envelope, null, 2));
+  } else {
+    displayVerifyTrustTTY(result.systemKey, result, { details: opts.verbose || opts.details });
+  }
+
+  const exitCode = exitCodeFromVerdict(result.verdict);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+async function verifyTrustCommandHandler(appName, options, cmd) {
+  try {
+    await runVerifyTrustCommandAction(appName, options, cmd);
+  } catch (error) {
+    handleCommandError(error, 'verify-trust');
+    process.exit(3);
+  }
+}
+
+module.exports = {
+  runVerifyTrustCommandAction,
+  verifyTrustCommandHandler
+};

package/lib/commands/verify-trust-external.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview verify-trust orchestration with dual-confidence report (433.0).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { runTestTrustForExternalSystem } = require('./test-trust-external');
+const { VERDICT, verdictFromPassed } = require('../lifecycle/product-model');
+
+/**
+ * @param {Array<Object>} rows
+ * @returns {Array<Object>}
+ */
+function mapTrustDatasourceRows(rows) {
+  return (rows || []).map(row => {
+    const tr = row.trustRun;
+    const verdict = row.success ? VERDICT.VERIFIED : VERDICT.FAILED;
+    return {
+      datasourceKey: row.key,
+      verdict,
+      trustDecision: tr?.trustDecision,
+      validationStatus: tr?.validationStatus,
+      error: row.error
+    };
+  });
+}
+
+/**
+ * @async
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function runVerifyTrustForExternalSystem(systemKey, options = {}) {
+  const { success, results, systemKey: resolvedKey, trustReport } =
+    await runTestTrustForExternalSystem(systemKey, options);
+  const datasourceRows = mapTrustDatasourceRows(results);
+  const report = trustReport || {};
+  const verdict = report.verdict ? report.verdict : verdictFromPassed(success);
+
+  return {
+    systemKey: resolvedKey || systemKey,
+    command: 'verify-trust',
+    verdict,
+    aiTrustPercent: report.aiTrustPercent ?? null,
+    accessConfidencePercent: report.accessConfidencePercent ?? null,
+    businessConfidencePercent: report.businessConfidencePercent ?? null,
+    findings: Array.isArray(report.findings) ? report.findings : [],
+    datasourceRows,
+    results
+  };
+}
+
+module.exports = {
+  runVerifyTrustForExternalSystem,
+  mapTrustDatasourceRows
+};

package/lib/commands/wizard-config-normalizer.js

@@ -17,6 +17,7 @@ const VALID_ENTITY_TYPES = new Set([
   'none'
 ]);
 const VALID_PORTAL_FIELDS = new Set(['text', 'textarea', 'select', 'json', 'boolean', 'number']);
+const { repairTestPayload } = require('./repair-datasource-test-payload');
 
 /**
  * Normalize system config fields to schema constraints
@@ -34,6 +35,45 @@ function normalizeSystemConfig(systemConfig) {
   return systemConfig;
 }
 
+/**
+ * @param {Object} datasourceConfig - Datasource config (mutated)
+ */
+function normalizePortalInput(datasourceConfig) {
+  if (!Array.isArray(datasourceConfig.portalInput)) return;
+  datasourceConfig.portalInput = datasourceConfig.portalInput.filter(item => {
+    if (!item || typeof item !== 'object') return false;
+    if (!item.name || !item.field || !item.label) return false;
+    return VALID_PORTAL_FIELDS.has(item.field);
+  });
+}
+
+/**
+ * @param {Object} datasourceConfig - Datasource config (mutated)
+ */
+function normalizeCipOutputModes(datasourceConfig) {
+  const operations = datasourceConfig.execution?.cip?.operations;
+  if (!operations) return;
+  for (const operation of Object.values(operations)) {
+    if (!operation || !Array.isArray(operation.steps)) continue;
+    for (const step of operation.steps) {
+      if (step?.output?.mode && step.output.mode !== 'records') {
+        step.output.mode = 'records';
+      }
+    }
+  }
+}
+
+/**
+ * @param {Object} datasourceConfig - Datasource config (mutated)
+ */
+function normalizeWizardTestPayload(datasourceConfig) {
+  const attrs = datasourceConfig.fieldMappings?.attributes;
+  if (!datasourceConfig.metadataSchema || !attrs || Object.keys(attrs).length === 0) {
+    return;
+  }
+  repairTestPayload(datasourceConfig, []);
+}
+
 /**
  * Normalize datasource config fields to schema constraints
  * @function normalizeDatasourceConfig
@@ -47,29 +87,9 @@ function normalizeDatasourceConfig(datasourceConfig) {
   if (datasourceConfig.entityType && !VALID_ENTITY_TYPES.has(datasourceConfig.entityType)) {
     datasourceConfig.entityType = ENTITY_TYPE_FALLBACK;
   }
-  if (Array.isArray(datasourceConfig.portalInput)) {
-    datasourceConfig.portalInput = datasourceConfig.portalInput.filter(item => {
-      if (!item || typeof item !== 'object') {
-        return false;
-      }
-      if (!item.name || !item.field || !item.label) {
-        return false;
-      }
-      return VALID_PORTAL_FIELDS.has(item.field);
-    });
-  }
-  if (datasourceConfig.execution?.cip?.operations) {
-    for (const operation of Object.values(datasourceConfig.execution.cip.operations)) {
-      if (!operation || !Array.isArray(operation.steps)) {
-        continue;
-      }
-      for (const step of operation.steps) {
-        if (step?.output?.mode && step.output.mode !== 'records') {
-          step.output.mode = 'records';
-        }
-      }
-    }
-  }
+  normalizePortalInput(datasourceConfig);
+  normalizeCipOutputModes(datasourceConfig);
+  normalizeWizardTestPayload(datasourceConfig);
   return datasourceConfig;
 }
 

package/lib/commands/wizard-core.js

@@ -512,7 +512,9 @@ async function setupDataplaneAndAuth(options, appName) {
   } catch (error) {
     throw new Error(`Authentication failed: ${error.message}`);
   }
+  const { applyLabDataplaneApiKeyBearer } = require('../utils/token-manager');
   requireBearerForDataplanePipeline(authConfig);
+  applyLabDataplaneApiKeyBearer(authConfig);
   const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
   let dataplaneUrl;
   try {

package/lib/core/admin-password-generator.js

@@ -0,0 +1,38 @@
+/**
+ * Cryptographically strong passwords for pro setup autogenerate.
+ *
+ * @fileoverview Pro installation password generation (show-once in setup wizard)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const PRO_PASSWORD_BYTE_LENGTH = 18;
+
+/**
+ * One random password suitable for admin roles (URL-safe, no quotes).
+ * @returns {string}
+ */
+function generateRandomAdminPassword() {
+  return crypto.randomBytes(PRO_PASSWORD_BYTE_LENGTH).toString('base64url');
+}
+
+/**
+ * Distinct passwords for infra, Keycloak install, and platform UI login.
+ * @returns {{ infra: string, keycloak: string, platform: string }}
+ */
+function generateProAdminPasswords() {
+  return {
+    infra: generateRandomAdminPassword(),
+    keycloak: generateRandomAdminPassword(),
+    platform: generateRandomAdminPassword()
+  };
+}
+
+module.exports = {
+  generateRandomAdminPassword,
+  generateProAdminPasswords
+};

package/lib/core/admin-secrets-bundle.js

@@ -0,0 +1,111 @@
+/**
+ * Map setup password bundles onto admin-secrets.env keys.
+ *
+ * @fileoverview Single (dev) vs split (pro) admin credential bundles
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const DEFAULT_REDIS_HOST = 'local:redis:6379:0:';
+const DEFAULT_REDIS_COMMANDER_USER = 'admin';
+const DEFAULT_KEYCLOAK_ADMIN_USERNAME = 'admin';
+
+/**
+ * @typedef {'single'|'split'} AdminPasswordBundleMode
+ */
+
+/**
+ * @typedef {Object} AdminPasswordBundleSingle
+ * @property {'single'} mode
+ * @property {string} password
+ */
+
+/**
+ * @typedef {Object} AdminPasswordBundleSplit
+ * @property {'split'} mode
+ * @property {string} infra
+ * @property {string} keycloak
+ * @property {string} platform
+ */
+
+/**
+ * @param {string} password
+ * @returns {AdminPasswordBundleSingle}
+ */
+function singlePasswordBundle(password) {
+  return { mode: 'single', password: String(password) };
+}
+
+/**
+ * @param {{ infra: string, keycloak: string, platform: string }} parts
+ * @returns {AdminPasswordBundleSplit}
+ */
+function splitPasswordBundle(parts) {
+  return {
+    mode: 'split',
+    infra: String(parts.infra),
+    keycloak: String(parts.keycloak),
+    platform: String(parts.platform)
+  };
+}
+
+/**
+ * Apply bundle onto a decrypted admin-secrets object (mutates copy).
+ * @param {Object.<string, string>} adminObj
+ * @param {AdminPasswordBundleSingle|AdminPasswordBundleSplit} bundle
+ * @returns {Object.<string, string>}
+ */
+function applyPasswordBundleToAdminObj(adminObj, bundle) {
+  const merged = { ...(adminObj || {}) };
+  merged.REDIS_HOST = merged.REDIS_HOST || DEFAULT_REDIS_HOST;
+  merged.REDIS_COMMANDER_USER = merged.REDIS_COMMANDER_USER || DEFAULT_REDIS_COMMANDER_USER;
+  merged.KEYCLOAK_ADMIN_USERNAME = DEFAULT_KEYCLOAK_ADMIN_USERNAME;
+
+  if (bundle.mode === 'single') {
+    const p = bundle.password;
+    merged.POSTGRES_PASSWORD = p;
+    merged.PGADMIN_DEFAULT_PASSWORD = p;
+    merged.REDIS_COMMANDER_PASSWORD = p;
+    merged.KEYCLOAK_ADMIN_PASSWORD = p;
+    merged.PLATFORM_ADMIN_PASSWORD = p;
+    return merged;
+  }
+
+  merged.POSTGRES_PASSWORD = bundle.infra;
+  merged.PGADMIN_DEFAULT_PASSWORD = bundle.infra;
+  merged.REDIS_COMMANDER_PASSWORD = bundle.infra;
+  merged.KEYCLOAK_ADMIN_PASSWORD = bundle.keycloak;
+  merged.PLATFORM_ADMIN_PASSWORD = bundle.platform;
+  return merged;
+}
+
+/**
+ * Build bundle from setup / up-infra CLI options.
+ * @param {Object} [options]
+ * @returns {AdminPasswordBundleSingle|AdminPasswordBundleSplit|null}
+ */
+function passwordBundleFromCliOptions(options = {}) {
+  if (options.passwordBundle && options.passwordBundle.mode) {
+    return options.passwordBundle;
+  }
+  const infra = String(options.infraAdminPassword || '').trim();
+  const keycloak = String(options.keycloakAdminPassword || '').trim();
+  const platform = String(options.platformAdminPassword || '').trim();
+  if (infra && keycloak && platform) {
+    return splitPasswordBundle({ infra, keycloak, platform });
+  }
+  const single = String(options.adminPassword || options.adminPwd || '').trim();
+  if (single) {
+    return singlePasswordBundle(single);
+  }
+  return null;
+}
+
+module.exports = {
+  singlePasswordBundle,
+  splitPasswordBundle,
+  applyPasswordBundleToAdminObj,
+  passwordBundleFromCliOptions
+};

package/lib/core/admin-secrets-env-overlay.js

@@ -0,0 +1,62 @@
+/**
+ * Map decrypted admin-secrets.env into platform container env keys.
+ *
+ * @fileoverview Overlay KEYCLOAK_* / ONBOARDING_* from admin-secrets (plan 185 Phase 2)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object.<string, string>} adminObj
+ * @returns {Object.<string, string>}
+ */
+function buildPlatformEnvOverlayFromAdminSecrets(adminObj) {
+  if (!adminObj || typeof adminObj !== 'object') return {};
+  const platformPwd =
+    adminObj.PLATFORM_ADMIN_PASSWORD ||
+    adminObj.ONBOARDING_ADMIN_PASSWORD ||
+    adminObj.MISO_ADMIN_PASSWORD ||
+    '';
+  const overlay = {};
+  if (adminObj.KEYCLOAK_ADMIN_USERNAME) {
+    overlay.KEYCLOAK_ADMIN_USERNAME = adminObj.KEYCLOAK_ADMIN_USERNAME;
+  }
+  if (adminObj.KEYCLOAK_ADMIN_PASSWORD) {
+    overlay.KEYCLOAK_ADMIN_PASSWORD = adminObj.KEYCLOAK_ADMIN_PASSWORD;
+    // Keycloak image reads KC_BOOTSTRAP_* on first start; keep in sync with admin-secrets (pro split bundles).
+    overlay.KC_BOOTSTRAP_ADMIN_PASSWORD = adminObj.KEYCLOAK_ADMIN_PASSWORD;
+    overlay.KC_BOOTSTRAP_ADMIN_USERNAME =
+      adminObj.KEYCLOAK_ADMIN_USERNAME || adminObj.KC_BOOTSTRAP_ADMIN_USERNAME || 'admin';
+  }
+  if (platformPwd) {
+    overlay.PLATFORM_ADMIN_PASSWORD = platformPwd;
+    overlay.ONBOARDING_ADMIN_PASSWORD = platformPwd;
+    overlay.MISO_ADMIN_PASSWORD = platformPwd;
+  }
+  const email = adminObj.PGADMIN_DEFAULT_EMAIL || adminObj.ONBOARDING_ADMIN_EMAIL;
+  if (email) {
+    overlay.ONBOARDING_ADMIN_EMAIL = email;
+  }
+  return overlay;
+}
+
+/**
+ * Apply admin-secrets values over resolved app env (admin-secrets wins for platform keys).
+ * @param {Object.<string, string>} envMap
+ * @param {Object.<string, string>} adminObj
+ */
+function applyAdminSecretsPlatformOverlay(envMap, adminObj) {
+  const overlay = buildPlatformEnvOverlayFromAdminSecrets(adminObj);
+  for (const [key, value] of Object.entries(overlay)) {
+    if (value !== undefined && value !== null && String(value).trim() !== '') {
+      envMap[key] = String(value);
+    }
+  }
+}
+
+module.exports = {
+  buildPlatformEnvOverlayFromAdminSecrets,
+  applyAdminSecretsPlatformOverlay
+};