@aifabrix/builder 2.45.5 → 2.46.0

package/lib/external-system/integration-auth-context.js

@@ -0,0 +1,45 @@
+/**
+ * Reuse dataplane auth resolved during sync/upload across verify and test commands.
+ *
+ * @fileoverview Integration auth context helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { setupIntegrationTestAuth } = require('./test-auth');
+const { getConfig } = require('../core/config');
+
+/**
+ * @param {Object} options
+ * @returns {Object}
+ */
+function integrationAuthOptions(options) {
+  const base = {
+    environment: options.env,
+    silentResolve: options.silentResolve === true
+  };
+  if (options.authConfig && options.dataplaneUrl) {
+    return { ...base, authConfig: options.authConfig, dataplaneUrl: options.dataplaneUrl };
+  }
+  return base;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveIntegrationAuth(systemKey, options) {
+  if (options.authConfig && options.dataplaneUrl) {
+    return { authConfig: options.authConfig, dataplaneUrl: options.dataplaneUrl };
+  }
+  const configObj = await getConfig();
+  return setupIntegrationTestAuth(systemKey, integrationAuthOptions(options), configObj);
+}
+
+module.exports = {
+  integrationAuthOptions,
+  resolveIntegrationAuth
+};

package/lib/external-system/test-auth.js

@@ -26,9 +26,14 @@ const { resolveControllerUrl } = require('../utils/controller-url');
  * @throws {Error} If authentication fails
  */
 async function setupIntegrationTestAuth(appName, options, _config) {
+  const opts = options && typeof options === 'object' ? options : {};
+  if (opts.authConfig && opts.dataplaneUrl) {
+    return { authConfig: opts.authConfig, dataplaneUrl: opts.dataplaneUrl };
+  }
+
   const { resolveEnvironment } = require('../core/config');
-  const environment = (options && options.environment && typeof options.environment === 'string' && options.environment.trim())
-    ? options.environment.trim()
+  const environment = (opts.environment && typeof opts.environment === 'string' && opts.environment.trim())
+    ? opts.environment.trim()
     : await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
   const authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
@@ -38,10 +43,12 @@ async function setupIntegrationTestAuth(appName, options, _config) {
   }
 
   let dataplaneUrl;
-  if (options && options.dataplane && typeof options.dataplane === 'string' && options.dataplane.trim()) {
-    dataplaneUrl = options.dataplane.trim();
+  if (opts.dataplane && typeof opts.dataplane === 'string' && opts.dataplane.trim()) {
+    dataplaneUrl = opts.dataplane.trim();
   } else {
-    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+    dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig, {
+      silent: opts.silentResolve === true
+    });
   }
 
   return { authConfig, dataplaneUrl };

package/lib/external-system/test.js

@@ -38,6 +38,7 @@ const {
 } = require('./test-execution');
 const { runSystemLevelTest } = require('./test-system-level');
 const { shouldUseSystemLevelIntegrationCall } = require('./integration-test-dispatch');
+const { cliOptsSkipSync } = require('../utils/cli-sync-options');
 
 /**
  * Loads and parses application config file
@@ -412,7 +413,8 @@ function determineDatasourcesToTest(datasourceFiles, datasourceFilter) {
  * @param {string} [options.controller] - Controller URL
  * @param {boolean} [options.verbose] - Show detailed test output
  * @param {number} [options.timeout] - Request timeout in milliseconds
- * @param {boolean} [options.sync] - When true, run full `aifabrix upload`-equivalent publish before tests
+ * @param {boolean} [options.noSync] - When true, skip publish (exercise dataplane config already deployed)
+ * @param {boolean} [options.sync] - Legacy explicit sync; ignored when `noSync` / `--no-sync` is set
  * @returns {Promise<Object>} Integration test results
  * @throws {Error} If testing fails
  */
@@ -457,13 +459,11 @@ async function testExternalSystemIntegration(appName, options = {}) {
 
     const { systemKey, authConfig, dataplaneUrl, datasourcesToTest, customPayload } = await prepareIntegrationTestEnvironment(appName, options);
 
-    if (options.sync === true) {
+    if (!cliOptsSkipSync(options)) {
       logger.log(chalk.cyan('Syncing local config to dataplane…'));
       const { uploadExternalSystem } = require('../commands/upload');
-      await uploadExternalSystem(systemKey, {
-        verbose: !!options.verbose,
-        minimal: true
-      });
+      const { buildMinimalUploadSyncOptions } = require('../utils/upload-sync-options');
+      await uploadExternalSystem(systemKey, buildMinimalUploadSyncOptions(options));
       logger.log(formatSuccessLine('Sync complete'));
     }
 

package/lib/generator/external-controller-manifest.js

@@ -22,6 +22,19 @@ const { loadVariables, loadRbac } = require('./helpers');
  * @param {Object} systemJson - System JSON object
  * @param {Object|null} rbac - RBAC configuration
  */
+/**
+ * Maps legacy integration auth method names to schema 1.3.0 values before upload/deploy.
+ * @param {Object} systemJson - System JSON object (mutated in place)
+ */
+function normalizeLegacyAuthMethod(systemJson) {
+  const auth = systemJson && systemJson.authentication;
+  if (!auth || typeof auth !== 'object') return;
+  const method = String(auth.method || '').trim().toLowerCase();
+  if (method === 'bearerkey') {
+    auth.method = 'bearerToken';
+  }
+}
+
 function mergeRbacIntoSystemJson(systemJson, rbac) {
   if (!rbac) {
     return;
@@ -78,6 +91,7 @@ function extractAppMetadata(variables, appName) {
  */
 async function loadSystemWithRbac(appPath, schemaBasePath, systemFile) {
   const systemJson = await loadSystemFile(appPath, schemaBasePath, systemFile);
+  normalizeLegacyAuthMethod(systemJson);
   const rbacPath = resolveRbacPath(appPath);
   const rbac = rbacPath ? loadRbac(rbacPath) : null;
   mergeRbacIntoSystemJson(systemJson, rbac);
@@ -187,6 +201,7 @@ function toDeployJsonShape(manifest) {
 }
 
 module.exports = {
+  normalizeLegacyAuthMethod,
   generateControllerManifest,
   toDeployJsonShape
 };

package/lib/governance/governance-cli-errors.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Governance CLI error messages (424.0).
+ */
+
+'use strict';
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernancePackNotFoundError(err) {
+  const raw = (err && err.message) || String(err);
+  return /not found/i.test(raw) || /\b404\b/.test(raw);
+}
+
+/**
+ * @param {Error|string} err
+ * @returns {boolean}
+ */
+function isGovernanceCoverageSchemaError(err) {
+  const raw = (err && err.message) || String(err);
+  return (
+    raw.includes('\'coverage\' is a required property') || /spec\.coverage/i.test(raw)
+  );
+}
+
+/**
+ * Short, non-duplicative CLI message from a dataplane governance API error.
+ * @param {Error|string} err
+ * @returns {string}
+ */
+function shortGovernanceApiError(err) {
+  const raw = ((err && err.message) || String(err)).trim();
+  if (isGovernancePackNotFoundError(err)) {
+    return 'No active pack on dataplane';
+  }
+  if (isGovernanceCoverageSchemaError(err)) {
+    return 'Pack missing spec.coverage (424.0 schema)';
+  }
+  const firstLine = raw.split('\n').find(line => line.trim()) || raw;
+  if (/^Governance scenario pack not found/i.test(firstLine)) {
+    return 'No active pack on dataplane';
+  }
+  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
+}
+
+/**
+ * User-facing hint after a failed governance pack upload (validation).
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function governanceUploadSchemaHint(systemKey) {
+  return (
+    'Scenario pack does not meet the 424.0 schema. Use dataplane-first generation:\n' +
+    `  aifabrix governance generate ${systemKey} --subject-email <email>\n` +
+    'Or: aifabrix verify-governance ' +
+    `${systemKey} --subject-email <email>`
+  );
+}
+
+/**
+ * Clarify subject-resolution 400s (dataplane reachable; User row missing).
+ * @param {Error} err
+ * @param {{ subjectEmails?: string[] }} [context]
+ * @returns {Error}
+ */
+function enrichUnresolvableGovernanceSubjectsError(err, context = {}) {
+  const hay = `${err.message || ''} ${err.formatted || ''}`;
+  if (!hay.includes('No resolvable subjects')) {
+    return err;
+  }
+  const emails = Array.isArray(context.subjectEmails)
+    ? context.subjectEmails.filter(Boolean)
+    : [];
+  const lines = [
+    '',
+    'The dataplane is reachable. This is not a network or controller error.',
+    'Pack generation needs --subject-email values that match existing dataplane User rows.',
+    emails.length > 0 ? `Subject email(s) you passed: ${emails.join(', ')}` : null,
+    'Check:',
+    '  aifabrix identity user list --search <email>',
+    'If the user is missing, apply your identity CSV first:',
+    '  aifabrix identity apply --file integration/<systemKey>/fixtures/<users>.csv --filter-prefix <systemKey>',
+    '  aifabrix identity sync -e dev --purge-cache'
+  ].filter(line => line !== null);
+  err.formatted = `${err.formatted || err.message}${lines.join('\n')}`;
+  return err;
+}
+
+module.exports = {
+  isGovernancePackNotFoundError,
+  isGovernanceCoverageSchemaError,
+  shortGovernanceApiError,
+  governanceUploadSchemaHint,
+  enrichUnresolvableGovernanceSubjectsError
+};

package/lib/governance/governance-download-display.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview TTY summary when governance download finds no active packs.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { failureGlyph } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+
+/**
+ * @param {Array<{ datasourceKey: string, reason: string }>} missing
+ */
+function printGovernanceDownloadMisses(missing) {
+  if (!missing || missing.length === 0) {
+    return;
+  }
+  for (const row of missing) {
+    logger.log(
+      chalk.white(`${row.datasourceKey}: ${failureGlyph()} ${row.reason}`)
+    );
+  }
+  logger.log('');
+  logger.log(chalk.gray('Next steps:'));
+  logger.log(
+    chalk.gray(
+      '  • Run: aifabrix governance generate <systemKey> --subject-email <email>'
+    )
+  );
+  logger.log(
+    chalk.gray('  • Or use: aifabrix verify-governance <systemKey> --subject-email <email>')
+  );
+  logger.log(chalk.gray('  • Ensure protection is published and identity sync has run'));
+}
+
+module.exports = {
+  printGovernanceDownloadMisses
+};

package/lib/governance/governance-run-display.js

@@ -16,7 +16,45 @@ const {
   formatBlockingError
 } = require('../utils/cli-test-layout-chalk');
 
-const SEP = '────────────────────────────────';
+const SEP = '────────────────────────';
+const MAX_SAMPLE_KEYS = 5;
+
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>}
+ */
+function buildScenarioExpectMap(packDocument) {
+  const map = new Map();
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return map;
+  }
+  for (const scenario of scenarios) {
+    if (!scenario || typeof scenario.id !== 'string') {
+      continue;
+    }
+    const expect = scenario.expect || {};
+    map.set(scenario.id, {
+      mustIncludeKeys: Array.isArray(expect.mustIncludeKeys) ? expect.mustIncludeKeys : [],
+      mustExcludeKeys: Array.isArray(expect.mustExcludeKeys) ? expect.mustExcludeKeys : []
+    });
+  }
+  return map;
+}
+
+/**
+ * @param {string[]} keys
+ * @param {number} [maxKeys]
+ * @returns {string}
+ */
+function formatKeySample(keys, maxKeys = MAX_SAMPLE_KEYS) {
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return '—';
+  }
+  const slice = keys.slice(0, maxKeys);
+  const suffix = keys.length > maxKeys ? ` (+${keys.length - maxKeys} more)` : '';
+  return `${slice.join(', ')}${suffix}`;
+}
 
 /**
  * @param {'pass'|'fail'} status
@@ -28,38 +66,162 @@ function scenarioGlyph(status) {
 
 /**
  * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
- * @param {boolean} verbose
  */
-function logScenarioVerdict(scenario, verbose) {
-  logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.verdict}`);
-  if (!verbose) return;
-  logger.log(
-    metaGray(
-      `      Subject: ${scenario.subjectDisplayName} (${scenario.subjectUserId})`
-    )
-  );
-  if (scenario.subjectGroups && scenario.subjectGroups.length > 0) {
-    logger.log(metaGray(`      Groups: ${scenario.subjectGroups.join(', ')}`));
+function logGovernanceScenarioSubjectLines(scenario) {
+  logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.id}`);
+  logger.log(metaGray(`      Subject email:  ${scenario.subjectEmail || '—'}`));
+  if (scenario.subjectDisplayName) {
+    logger.log(
+      metaGray(
+        `      Subject:        ${scenario.subjectDisplayName} (${scenario.subjectUserId || '—'})`
+      )
+    );
   }
-  logger.log(
-    metaGray(
-      `      Visible keys: ${scenario.visibleKeyCount} · excluded ABAC: ${scenario.excludedAbac}` +
-        (scenario.auditRef ? ` · audit: ${scenario.auditRef}` : '')
-    )
-  );
-  if (scenario.unexpectedVisibleKeys && scenario.unexpectedVisibleKeys.length > 0) {
+  logger.log(metaGray(`      Verdict:        ${scenario.verdict || '—'}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioCounts(scenario) {
+  const visible = typeof scenario.visibleKeyCount === 'number' ? scenario.visibleKeyCount : 0;
+  const abac = typeof scenario.excludedAbac === 'number' ? scenario.excludedAbac : 0;
+  const filter = typeof scenario.excludedFilter === 'number' ? scenario.excludedFilter : 0;
+  logger.log(metaGray(`      Visible keys:   ${visible} allowed`));
+  logger.log(metaGray(`      Declined:       ${abac} by ABAC · ${filter} by filter`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {{ mustIncludeKeys: string[], mustExcludeKeys: string[] }} expect
+ */
+function logGovernanceScenarioPassSamples(expect) {
+  const allowed =
+    expect.mustIncludeKeys.length > 0 ? formatKeySample(expect.mustIncludeKeys) : '—';
+  const blocked =
+    expect.mustExcludeKeys.length > 0 ? formatKeySample(expect.mustExcludeKeys) : '—';
+  logger.log(metaGray(`      Sample allowed: ${allowed}`));
+  logger.log(metaGray(`      Sample blocked: ${blocked}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioFailSamples(scenario) {
+  if (scenario.missingRequiredKeys?.length) {
     logger.log(
-      metaGray(`      Unexpected: ${scenario.unexpectedVisibleKeys.join(', ')}`)
+      metaGray(`      Missing keys:   ${formatKeySample(scenario.missingRequiredKeys)}`)
     );
   }
-  if (scenario.missingRequiredKeys && scenario.missingRequiredKeys.length > 0) {
-    logger.log(metaGray(`      Missing: ${scenario.missingRequiredKeys.join(', ')}`));
+  if (scenario.unexpectedVisibleKeys?.length) {
+    logger.log(
+      metaGray(`      Unexpected:     ${formatKeySample(scenario.unexpectedVisibleKeys)}`)
+    );
   }
   if (scenario.fixHint) {
-    logger.log(metaGray(`      Fix: ${scenario.fixHint}`));
+    logger.log(metaGray(`      Fix:            ${scenario.fixHint}`));
   }
 }
 
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>} expectMap
+ */
+function logGovernanceScenarioDetail(scenario, expectMap) {
+  const expect = expectMap.get(scenario.id) || {
+    mustIncludeKeys: [],
+    mustExcludeKeys: []
+  };
+  logGovernanceScenarioSubjectLines(scenario);
+  logGovernanceScenarioCounts(scenario);
+  if (scenario.status === 'pass') {
+    logGovernanceScenarioPassSamples(expect);
+  } else {
+    logGovernanceScenarioFailSamples(scenario);
+  }
+  if (scenario.subjectGroups?.length) {
+    logger.log(metaGray(`      Groups:         ${scenario.subjectGroups.join(', ')}`));
+  }
+  if (scenario.auditRef) {
+    logger.log(metaGray(`      Audit:          ${scenario.auditRef}`));
+  }
+}
+
+/**
+ * One datasource block for verify-governance -v.
+ * @param {Object} row
+ * @param {string} row.datasourceKey
+ * @param {Object} [row.result]
+ * @param {Object} [row.packDocument]
+ * @param {string} [row.packPath]
+ * @param {string} [row.error]
+ */
+function displayGovernanceDatasourceVerbose(row) {
+  logger.log('');
+  logger.log(chalk.white(`Datasource: ${row.datasourceKey}`));
+  if (row.error) {
+    logger.log(formatBlockingError(row.error));
+    return;
+  }
+  const run = row.result;
+  if (!run || !run.summary) {
+    logger.log(metaGray('  No scenario run result (pack missing or run skipped).'));
+    return;
+  }
+  logger.log(headerKeyValue('Pack:', run.packKey || '—'));
+  if (row.packPath) {
+    logger.log(metaGray(`  File: ${row.packPath}`));
+  }
+  const summary = run.summary;
+  logger.log(
+    headerKeyValue('Scenarios:', `${summary.passed || 0}/${summary.total || 0} passed`)
+  );
+  const expectMap = buildScenarioExpectMap(row.packDocument);
+  for (const scenario of run.scenarios || []) {
+    logGovernanceScenarioDetail(scenario, expectMap);
+  }
+}
+
+/**
+ * Verbose (-v) scenario breakdown for verify-governance / governance verify.
+ * @param {Object} result
+ */
+function displayGovernanceVerboseDetails(result) {
+  if (!result) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.white('Scenario results'));
+  logger.log(metaGray(SEP));
+  logger.log(metaGray('Key sets only — no record payloads.'));
+
+  if (result.legacyResult && result.legacyResult.summary) {
+    const dsKey =
+      result.packDatasourceKey ||
+      primaryDatasourceFromPack(result.packDocument) ||
+      'scenario pack';
+    displayGovernanceDatasourceVerbose({
+      datasourceKey: dsKey,
+      result: result.legacyResult,
+      packDocument: result.packDocument,
+      packPath: result.packPath
+    });
+    logger.log('');
+    return;
+  }
+
+  const rows = result.datasourceRows || [];
+  if (rows.length === 0) {
+    logger.log(metaGray('  No datasource scenario packs were run.'));
+    logger.log('');
+    return;
+  }
+  for (const row of rows) {
+    displayGovernanceDatasourceVerbose(row);
+  }
+  logger.log('');
+}
+
 /**
  * @param {string} systemKey
  * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
@@ -82,8 +244,13 @@ function displayGovernanceRunTTY(systemKey, result, opts = {}) {
   );
   logger.log(metaGray('  Does not call vendor APIs (use test-e2e for connectivity).'));
   logger.log('');
+  const expectMap = buildScenarioExpectMap(opts.packDocument);
   for (const scenario of result.scenarios || []) {
-    logScenarioVerdict(scenario, opts.verbose === true);
+    if (opts.verbose === true) {
+      logGovernanceScenarioDetail(scenario, expectMap);
+    } else {
+      logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.verdict}`);
+    }
   }
   logger.log('');
   if (agg === 'ok') {
@@ -112,8 +279,31 @@ function exitCodeFromGovernanceSummary(summary) {
   return 0;
 }
 
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {string|null}
+ */
+function primaryDatasourceFromPack(packDocument) {
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return null;
+  }
+  for (const scenario of scenarios) {
+    const keys = scenario?.search?.datasourceKeys;
+    if (Array.isArray(keys) && keys.length > 0 && typeof keys[0] === 'string') {
+      return keys[0];
+    }
+  }
+  return null;
+}
+
 module.exports = {
+  buildScenarioExpectMap,
+  formatKeySample,
+  displayGovernanceDatasourceVerbose,
+  displayGovernanceVerboseDetails,
   displayGovernanceRunTTY,
   printGovernanceRunJson,
-  exitCodeFromGovernanceSummary
+  exitCodeFromGovernanceSummary,
+  primaryDatasourceFromPack
 };

package/lib/infrastructure/admin-secrets-apply.js

@@ -0,0 +1,84 @@
+/**
+ * Write admin-secrets.env from setup password bundles.
+ *
+ * @fileoverview Apply dev/pro bundles to admin-secrets.env
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fsRealSync = require('../internal/fs-real-sync');
+const logger = require('../utils/logger');
+const { applyPasswordBundleToAdminObj } = require('../core/admin-secrets-bundle');
+
+const DEFAULT_ADMIN_OBJ = {
+  REDIS_HOST: 'local:redis:6379:0:',
+  REDIS_COMMANDER_USER: 'admin'
+};
+
+/**
+ * @param {() => object} getCoreSecrets
+ * @param {string} adminSecretsPath
+ * @param {Object.<string, string>} merged
+ * @param {string|null} logMessage
+ */
+async function writeAdminSecretsFile(getCoreSecrets, adminSecretsPath, merged, logMessage) {
+  const { assertWritableSecretsPathForTests } = require('../utils/aifabrix-test-runtime-guard');
+  assertWritableSecretsPathForTests(adminSecretsPath);
+  const content = await getCoreSecrets().formatAdminSecretsContent(merged);
+  fsRealSync.writeFileSync(adminSecretsPath, content, { mode: 0o600 });
+  if (logMessage) {
+    logger.log(logMessage);
+  }
+}
+
+/**
+ * @param {Object} ctx
+ * @param {() => object} ctx.getCoreSecrets
+ * @param {(bundle: object) => Promise<void>} [ctx.syncAdminKvFromPasswordBundle]
+ * @param {(bundle: object) => Promise<void>} [ctx.syncRequiredKvFromPasswordBundle]
+ * @param {boolean} [ctx.syncAdminKv]
+ * @param {(dir: string) => void} ctx.logVolumeResetHint
+ * @param {string} ctx.infraDirForHint
+ * @param {string} ctx.adminSecretsPath
+ * @param {Object} ctx.adminObj
+ * @param {Object} ctx.bundle
+ * @param {string} [ctx.email]
+ */
+async function applyAdminSecretsFromBundle(ctx) {
+  const {
+    getCoreSecrets,
+    syncAdminKvFromPasswordBundle,
+    syncRequiredKvFromPasswordBundle,
+    syncAdminKv,
+    logVolumeResetHint,
+    infraDirForHint,
+    adminSecretsPath,
+    adminObj,
+    bundle,
+    email
+  } = ctx;
+  let merged = applyPasswordBundleToAdminObj({ ...DEFAULT_ADMIN_OBJ, ...adminObj }, bundle);
+  if (email && String(email).trim()) {
+    merged = { ...merged, PGADMIN_DEFAULT_EMAIL: String(email).trim() };
+  }
+  await writeAdminSecretsFile(
+    getCoreSecrets,
+    adminSecretsPath,
+    merged,
+    'Updated admin credentials in admin-secrets.env.'
+  );
+  if (syncAdminKv && typeof syncAdminKvFromPasswordBundle === 'function') {
+    await syncAdminKvFromPasswordBundle(bundle);
+  } else if (typeof syncRequiredKvFromPasswordBundle === 'function') {
+    await syncRequiredKvFromPasswordBundle(bundle);
+  }
+  logVolumeResetHint(infraDirForHint);
+}
+
+module.exports = {
+  DEFAULT_ADMIN_OBJ,
+  writeAdminSecretsFile,
+  applyAdminSecretsFromBundle
+};