@aifabrix/builder 2.44.6 → 2.45.5

package/lib/datasource/unified-validation-run-resolve.js

@@ -4,40 +4,73 @@
  * @version 2.0.0
  */
 
-const path = require('path');
 const { getIntegrationPath } = require('../utils/paths');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
+const {
+  datasourceIdentifierMatchesFile,
+  resolveDatasourceFilePath
+} = require('./datasource-identifier');
+
+/**
+ * @param {string} appPath
+ * @param {string} schemaBasePath
+ * @param {string[]} datasourceFiles
+ * @param {string} identifier
+ * @returns {string|null}
+ */
+function findDatasourceFileByIdentifier(appPath, schemaBasePath, datasourceFiles, identifier) {
+  const fsSync = require('fs');
+  for (const fileRef of datasourceFiles) {
+    if (!fileRef || typeof fileRef !== 'string') {
+      continue;
+    }
+    const fullPath = resolveDatasourceFilePath(appPath, schemaBasePath, fileRef);
+    if (!fsSync.existsSync(fullPath)) {
+      continue;
+    }
+    try {
+      const parsed = loadConfigFile(fullPath);
+      if (datasourceIdentifierMatchesFile(identifier, fileRef, parsed)) {
+        return fileRef;
+      }
+    } catch {
+      // skip unreadable or invalid files
+    }
+  }
+  return null;
+}
 
 /**
  * @param {string} appKey
  * @param {string} datasourceKey
  * @param {Function} findDatasourceFileByKey - From integration-context
- * @returns {{ datasource: Object, datasourcePath: string }}
+ * @returns {{ datasource: Object, datasourcePath: string, datasourceKey: string }}
  */
 function loadDatasourceForApp(appKey, datasourceKey, findDatasourceFileByKey) {
   const appPath = getIntegrationPath(appKey);
   const config = loadConfigFile(resolveApplicationConfigPath(appPath));
   const schemaBasePath = config.externalIntegration?.schemaBasePath || './';
   const datasourceFiles = config.externalIntegration?.dataSources || [];
-  let datasourceFile = datasourceFiles.find(f => {
-    const base = path.basename(f, path.extname(f));
-    return base === datasourceKey || base.includes(datasourceKey);
-  });
+  let datasourceFile = findDatasourceFileByIdentifier(
+    appPath,
+    schemaBasePath,
+    datasourceFiles,
+    datasourceKey
+  );
   if (!datasourceFile) {
     datasourceFile = findDatasourceFileByKey(appPath, schemaBasePath, datasourceFiles, datasourceKey);
   }
   if (!datasourceFile) {
     throw new Error(`Datasource '${datasourceKey}' not found in application config`);
   }
-  const datasourcePath = path.isAbsolute(schemaBasePath)
-    ? path.join(schemaBasePath, datasourceFile)
-    : path.join(appPath, schemaBasePath, datasourceFile);
+  const datasourcePath = resolveDatasourceFilePath(appPath, schemaBasePath, datasourceFile);
   const datasource = loadConfigFile(datasourcePath);
-  if (datasource.key !== datasourceKey) {
-    throw new Error(`Datasource key mismatch: file has '${datasource.key}', expected '${datasourceKey}'`);
+  const canonicalKey = datasource.key;
+  if (!canonicalKey || typeof canonicalKey !== 'string') {
+    throw new Error(`Datasource file is missing a valid key: ${datasourcePath}`);
   }
-  return { datasource, datasourcePath };
+  return { datasource, datasourcePath, datasourceKey: canonicalKey };
 }
 
 module.exports = { loadDatasourceForApp };

package/lib/datasource/unified-validation-run.js

@@ -71,6 +71,40 @@ function loadDatasourceForAppExport(appKey, datasourceKey) {
   return loadDatasourceForApp(appKey, datasourceKey, findDatasourceFileByKey);
 }
 
+/**
+ * @async
+ * @param {string} appKey
+ * @param {Object} options
+ * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
+ */
+async function resolveValidationAuth(appKey, options) {
+  if (options.authConfig && (options.dataplaneUrl || options.dataplane)) {
+    return {
+      authConfig: options.authConfig,
+      dataplaneUrl: options.dataplaneUrl || options.dataplane
+    };
+  }
+  const configObj = await getConfig();
+  const auth = await setupIntegrationTestAuth(appKey, options, configObj);
+  return { authConfig: auth.authConfig, dataplaneUrl: auth.dataplaneUrl };
+}
+
+/**
+ * @async
+ * @param {string} datasourceKey
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function prepareValidationRunContext(datasourceKey, options) {
+  const runType = options.runType || 'test';
+  const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
+  const systemKey = await getSystemKeyFromAppKey(appKey);
+  const { datasource } = loadDatasourceForAppExport(appKey, datasourceKey);
+  const { authConfig, dataplaneUrl } = await resolveValidationAuth(appKey, options);
+  await maybeSyncDatasourceToDataplane({ options, authConfig, systemKey });
+  return { runType, systemKey, datasource, authConfig, dataplaneUrl };
+}
+
 /**
  * Run unified validation for one persisted datasource.
  * @async
@@ -83,41 +117,33 @@ async function runUnifiedDatasourceValidation(datasourceKey, options) {
   if (!datasourceKey || typeof datasourceKey !== 'string') {
     throw new Error('Datasource key is required');
   }
-  const runType = options.runType || 'test';
-  const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
-  const systemKey = await getSystemKeyFromAppKey(appKey);
-  const { datasource } = loadDatasourceForAppExport(appKey, datasourceKey);
-
-  const configObj = await getConfig();
-  const { authConfig, dataplaneUrl } = await setupIntegrationTestAuth(appKey, options, configObj);
-
-  await maybeSyncDatasourceToDataplane({ options, authConfig, systemKey });
 
+  const ctx = await prepareValidationRunContext(datasourceKey, options);
   const useAsync = options.noAsync ? false : options.async !== false;
   const timeoutMs = parseInt(String(options.timeout || '30000'), 10) || 30000;
-
   const body = await buildUnifiedValidationBody({
-    systemKey,
+    systemKey: ctx.systemKey,
     datasourceKey,
-    runType,
-    datasource,
+    runType: ctx.runType,
+    datasource: ctx.datasource,
     payloadPath: options.payload,
     useAsync,
     options
   });
 
   const result = await postValidationRunAndOptionalPoll({
-    dataplaneUrl,
-    authConfig,
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: ctx.authConfig,
     body,
     timeoutMs,
     useAsync,
     noAsync: options.noAsync === true || options.async === false,
-    verbosePoll: options.verbose === true
+    verbosePoll: options.verbose === true,
+    pollSubject: datasourceKey
   });
 
   if (result && result.envelope) {
-    annotateMissingAutoRbacPermissions(result.envelope, datasourceKey, datasource);
+    annotateMissingAutoRbacPermissions(result.envelope, datasourceKey, ctx.datasource);
   }
   return result;
 }

package/lib/datasource/validate.js

@@ -11,6 +11,11 @@
 const path = require('path');
 const fs = require('fs');
 const pathsUtil = require('../utils/paths');
+const {
+  datasourceIdentifierMatchesFile,
+  pickIntegrationAppForDatasourceIdentifier,
+  collectDatasourceFileRefsMatchingIdentifier
+} = require('./datasource-identifier');
 const { loadExternalDataSourceSchema } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('./field-reference-validator');
@@ -46,16 +51,13 @@ function tryResolveAsExistingFile(identifier) {
 }
 
 /**
- * Pick integration app folder for a datasource `key` (longest matching prefix wins).
+ * Pick integration app folder for a datasource identifier (longest matching prefix wins).
  * @param {string} datasourceKey
  * @param {string[]} appNames
  * @returns {string|null}
  */
 function pickIntegrationAppForDatasourceKey(datasourceKey, appNames) {
-  const matches = appNames.filter((app) => datasourceKey === app || datasourceKey.startsWith(`${app}-`));
-  if (matches.length === 0) return null;
-  matches.sort((a, b) => b.length - a.length);
-  return matches[0];
+  return pickIntegrationAppForDatasourceIdentifier(datasourceKey, appNames);
 }
 
 /**
@@ -94,7 +96,7 @@ function collectJsonPathsMatchingDatasourceKey(dir, scanOrder, datasourceKey) {
     } catch {
       continue;
     }
-    if (parsed && typeof parsed === 'object' && parsed.key === datasourceKey) {
+    if (datasourceIdentifierMatchesFile(datasourceKey, name, parsed)) {
       hits.push(full);
     }
   }
@@ -102,21 +104,12 @@ function collectJsonPathsMatchingDatasourceKey(dir, scanOrder, datasourceKey) {
 }
 
 /**
- * Find integration JSON whose parsed `key` equals datasourceKey.
+ * @param {string} appName
  * @param {string} datasourceKey
- * @returns {string} Absolute file path
+ * @returns {string}
  * @throws {Error}
  */
-function resolvePathFromIntegrationDatasourceKey(datasourceKey) {
-  const appNames = pathsUtil.listIntegrationAppNames();
-  const appName = pickIntegrationAppForDatasourceKey(datasourceKey, appNames);
-  if (!appName) {
-    throw new Error(
-      `No integration/<app>/ folder matches datasource key "${datasourceKey}". ` +
-        'Pass a path to the JSON file, or use a key whose prefix matches an app under integration/ ' +
-        '(e.g. app test-e2e-hubspot for key test-e2e-hubspot-users).'
-    );
-  }
+function resolvePathFromIntegrationFolderScan(appName, datasourceKey) {
   const dir = pathsUtil.getIntegrationPath(appName);
   if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
     throw new Error(`Integration folder not found: ${dir}`);
@@ -128,16 +121,40 @@ function resolvePathFromIntegrationDatasourceKey(datasourceKey) {
   const hits = collectJsonPathsMatchingDatasourceKey(dir, scanOrder, datasourceKey);
   if (hits.length === 0) {
     throw new Error(
-      `No datasource JSON with key "${datasourceKey}" under integration/${appName}/. ` +
+      `No datasource JSON matching "${datasourceKey}" under integration/${appName}/. ` +
         `Checked: ${scanOrder.length ? scanOrder.join(', ') : '(no JSON candidates)'}`
     );
   }
   if (hits.length > 1) {
-    throw new Error(`Ambiguous: multiple files declare key "${datasourceKey}": ${hits.join(', ')}`);
+    throw new Error(`Ambiguous: multiple files match "${datasourceKey}": ${hits.join(', ')}`);
   }
   return hits[0];
 }
 
+/**
+ * Find integration JSON whose parsed `key` equals datasourceKey.
+ * @param {string} datasourceKey
+ * @returns {string} Absolute file path
+ * @throws {Error}
+ */
+function resolvePathFromIntegrationDatasourceKey(datasourceKey) {
+  const appNames = pathsUtil.listIntegrationAppNames();
+  const appName = pickIntegrationAppForDatasourceKey(datasourceKey, appNames);
+  if (!appName) {
+    throw new Error(
+      `No integration/<app>/ folder matches datasource identifier "${datasourceKey}". ` +
+        'Pass a path to the JSON file, or use a datasource key or filename whose prefix matches an app under integration/ ' +
+        '(e.g. test-e2e-hubspot-companies or test-e2e-hubspot-datasource-companies for app test-e2e-hubspot).'
+    );
+  }
+  const manifestHits = collectDatasourceFileRefsMatchingIdentifier(appName, datasourceKey);
+  if (manifestHits.length === 1) {
+    const dir = pathsUtil.getIntegrationPath(appName);
+    return path.join(dir, manifestHits[0]);
+  }
+  return resolvePathFromIntegrationFolderScan(appName, datasourceKey);
+}
+
 /**
  * @param {string} identifier - File path or datasource `key`
  * @returns {string} Absolute path to JSON file

package/lib/external-system/deploy.js

@@ -169,7 +169,7 @@ function logImmediateControllerDeploymentOutcome(deploymentOutcome) {
     );
     return;
   }
-  logger.log(chalk.gray('   See Deployment section below for details.'));
+  logger.log(chalk.gray('   Check the controller deployment job or logs for details.'));
 }
 
 async function executeDeployAndDisplay(manifest, controllerUrl, environment, authConfig, options) {
@@ -192,6 +192,10 @@ async function executeDeployAndDisplay(manifest, controllerUrl, environment, aut
   const deploymentOutcome = parseControllerDeploymentOutcome(result);
   logImmediateControllerDeploymentOutcome(deploymentOutcome);
 
+  if (!deploymentOutcome.ok) {
+    return result;
+  }
+
   const ctx = await fetchDataplaneDeployReadiness(
     controllerUrl,
     environment,

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

@@ -16,7 +16,7 @@ const { getIntegrationPath } = require('../utils/paths');
 const { runUnifiedDatasourceValidation } = require('../datasource/unified-validation-run');
 
 async function runOneDatasourceKey(appName, datasourceKey, opts) {
-  const { environment, runType, debug, timeoutMs } = opts;
+  const { environment, runType, debug, timeoutMs, authConfig, dataplaneUrl } = opts;
   try {
     const uni = await runUnifiedDatasourceValidation(datasourceKey, {
       app: appName,
@@ -26,7 +26,9 @@ async function runOneDatasourceKey(appName, datasourceKey, opts) {
       verbose: false,
       timeout: timeoutMs,
       async: true,
-      noAsync: false
+      noAsync: false,
+      authConfig,
+      dataplaneUrl
     });
 
     if (uni.apiError) {
@@ -89,7 +91,17 @@ async function maybeWriteSystemRunLog(appName, systemKey, datasourceKeys, runTyp
  * @param {number} [params.timeout] - Request timeout
  * @returns {Promise<{success: boolean, datasourceResults: Object[]}>}
  */
-async function runSystemLevelTest({ appName, systemKey, datasourceKeys, environment, runType, debug, timeout }) {
+async function runSystemLevelTest({
+  appName,
+  systemKey,
+  datasourceKeys,
+  environment,
+  runType,
+  debug,
+  timeout,
+  authConfig,
+  dataplaneUrl
+}) {
   if (!Array.isArray(datasourceKeys) || datasourceKeys.length === 0) {
     return { success: true, datasourceResults: [] };
   }
@@ -100,7 +112,16 @@ async function runSystemLevelTest({ appName, systemKey, datasourceKeys, environm
     // Keep sequential to avoid spiking external APIs / dataplane concurrency in CLI runs.
     // (Plan allows parallel later, but UX needs stable logs first.)
     // eslint-disable-next-line no-await-in-loop -- intentional sequential execution
-    results.push(await runOneDatasourceKey(appName, key, { environment, runType, debug, timeoutMs }));
+    results.push(
+      await runOneDatasourceKey(appName, key, {
+        environment,
+        runType,
+        debug,
+        timeoutMs,
+        authConfig,
+        dataplaneUrl
+      })
+    );
   }
 
   const success = results.every(r => r.success);

package/lib/external-system/test.js

@@ -486,7 +486,9 @@ async function testExternalSystemIntegration(appName, options = {}) {
           environment: options.environment,
           runType: 'integration',
           debug: options.debug,
-          timeout
+          timeout,
+          authConfig,
+          dataplaneUrl
         });
         results.success = systemResult.success;
         results.datasourceResults = systemResult.datasourceResults;

package/lib/governance/governance-pack-loader.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Load governance scenario pack YAML from integration folder
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { getIntegrationPath } = require('../utils/paths');
+
+/**
+ * Resolve pack file path for test-governance.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {string} [options.pack] - Explicit path (absolute or relative to integration root)
+ * @param {string} [options.app] - Integration folder override
+ * @returns {string}
+ */
+function resolveGovernancePackPath(systemKey, options = {}) {
+  const integrationPath = options.app
+    ? path.isAbsolute(options.app)
+      ? options.app
+      : path.resolve(process.cwd(), options.app)
+    : getIntegrationPath(systemKey);
+
+  if (options.pack) {
+    const packPath = path.isAbsolute(options.pack)
+      ? options.pack
+      : path.join(integrationPath, options.pack);
+    if (!fs.existsSync(packPath)) {
+      throw new Error(`Scenario pack not found: ${packPath}`);
+    }
+    return packPath;
+  }
+
+  const candidates = [
+    path.join(integrationPath, 'scenarios', 'default.yaml'),
+    path.join(integrationPath, 'scenarios', `${systemKey}-v1.yaml`)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `No scenario pack found under ${path.join(integrationPath, 'scenarios')}. ` +
+      'Use --pack <path> (e.g. scenarios/test-protection-v1.yaml).'
+  );
+}
+
+/**
+ * @param {string} packPath
+ * @returns {Object}
+ */
+function loadGovernancePackYaml(packPath) {
+  const raw = fs.readFileSync(packPath, 'utf8');
+  const doc = yaml.load(raw);
+  if (!doc || typeof doc !== 'object') {
+    throw new Error(`Invalid scenario pack YAML: ${packPath}`);
+  }
+  return doc;
+}
+
+module.exports = {
+  resolveGovernancePackPath,
+  loadGovernancePackYaml
+};

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

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview TTY display for governance scenario acceptance runs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  sectionTitle,
+  headerKeyValue,
+  metadata: metaGray,
+  formatSuccessParagraph,
+  formatBlockingError
+} = require('../utils/cli-test-layout-chalk');
+
+const SEP = '────────────────────────────────';
+
+/**
+ * @param {'pass'|'fail'} status
+ * @returns {string}
+ */
+function scenarioGlyph(status) {
+  return status === 'pass' ? chalk.green('✔') : chalk.red('✖');
+}
+
+/**
+ * @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(', ')}`));
+  }
+  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(`      Unexpected: ${scenario.unexpectedVisibleKeys.join(', ')}`)
+    );
+  }
+  if (scenario.missingRequiredKeys && scenario.missingRequiredKeys.length > 0) {
+    logger.log(metaGray(`      Missing: ${scenario.missingRequiredKeys.join(', ')}`));
+  }
+  if (scenario.fixHint) {
+    logger.log(metaGray(`      Fix: ${scenario.fixHint}`));
+  }
+}
+
+/**
+ * @param {string} systemKey
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
+ * @param {{ verbose?: boolean, packPath?: string }} opts
+ */
+function displayGovernanceRunTTY(systemKey, result, opts = {}) {
+  const agg = result.summary.failed > 0 ? 'fail' : 'ok';
+  logger.log(SEP);
+  logger.log(sectionTitle('Governed search acceptance (key sets only — no record payload)'));
+  logger.log(headerKeyValue('System:', systemKey));
+  logger.log(headerKeyValue('Pack:', result.packKey));
+  if (opts.packPath) {
+    logger.log(metaGray(`  File: ${opts.packPath}`));
+  }
+  logger.log(
+    headerKeyValue(
+      'Summary:',
+      `${result.summary.passed}/${result.summary.total} passed`
+    )
+  );
+  logger.log(metaGray('  Does not call vendor APIs (use test-e2e for connectivity).'));
+  logger.log('');
+  for (const scenario of result.scenarios || []) {
+    logScenarioVerdict(scenario, opts.verbose === true);
+  }
+  logger.log('');
+  if (agg === 'ok') {
+    logger.log(formatSuccessParagraph('All governance scenarios passed'));
+  } else {
+    logger.log(formatBlockingError(`${result.summary.failed} scenario(s) failed`));
+  }
+  logger.log(SEP);
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
+ */
+function printGovernanceRunJson(result) {
+  logger.log(JSON.stringify(result, null, 2));
+}
+
+/**
+ * @param {{ total: number, passed: number, failed: number }} summary
+ * @returns {number}
+ */
+function exitCodeFromGovernanceSummary(summary) {
+  if (!summary || summary.failed > 0) {
+    return 1;
+  }
+  return 0;
+}
+
+module.exports = {
+  displayGovernanceRunTTY,
+  printGovernanceRunJson,
+  exitCodeFromGovernanceSummary
+};

package/lib/identity/identity-apply-core.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Shared helpers for identity apply
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getUser, listUsers } = require('../api/users.api');
+
+/**
+ * @param {Object} response
+ * @returns {any}
+ */
+function unwrapControllerData(response) {
+  if (!response || response.success === false) {
+    return null;
+  }
+  return response?.data?.data ?? response?.data ?? response;
+}
+
+/**
+ * @param {Object} response
+ * @returns {string}
+ */
+function apiErrorMessage(response) {
+  if (!response) {
+    return 'Request failed';
+  }
+  const err = response.error;
+  if (typeof err === 'string') {
+    return err;
+  }
+  if (err && typeof err === 'object') {
+    return err.formattedError || err.message || err.error || 'Request failed';
+  }
+  return response.formattedError || response.message || 'Request failed';
+}
+
+/**
+ * @param {Object} response
+ * @throws {Error}
+ */
+function throwIfApiFailed(response) {
+  if (!response || response.success === false) {
+    throw new Error(apiErrorMessage(response));
+  }
+}
+
+/**
+ * @param {Object|null|undefined} stats
+ * @param {{ allowEmptySync?: boolean }} [opts]
+ * @throws {Error}
+ */
+function assertSyncStatsOk(stats, opts = {}) {
+  const syncErrors = Number(stats?.errors ?? 0);
+  if (syncErrors > 0) {
+    throw new Error(
+      `Dataplane full sync reported ${syncErrors} error(s). ` +
+        `usersProcessed=${stats?.usersProcessed ?? 0} groupsProcessed=${stats?.groupsProcessed ?? 0}. ` +
+        'Check miso-controller logs for the sync request.'
+    );
+  }
+  const processed = Number(stats?.usersProcessed ?? 0);
+  if (processed === 0 && !opts.allowEmptySync) {
+    throw new Error(
+      'Dataplane full sync completed with usersProcessed=0. Use --allow-empty-sync to accept, or fix identity on the controller.'
+    );
+  }
+}
+
+/**
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {{ csvId?: string, email: string }} userSpec
+ * @returns {Promise<Object|null>}
+ */
+async function findExistingUser(controllerUrl, authConfig, userSpec) {
+  const csvId = String(userSpec.csvId || '').trim();
+  if (csvId) {
+    const byId = await getUser(controllerUrl, authConfig, csvId);
+    const row = unwrapControllerData(byId);
+    if (row && row.id) {
+      return row;
+    }
+  }
+  const email = String(userSpec.email || '').trim();
+  const listed = await listUsers(controllerUrl, authConfig, {
+    search: email,
+    pageSize: 10,
+    page: 1
+  });
+  const items = unwrapControllerData(listed);
+  const list = Array.isArray(items) ? items : items?.data;
+  if (!Array.isArray(list)) {
+    return null;
+  }
+  return list.find((u) => String(u.email || '').toLowerCase() === email.toLowerCase()) || null;
+}
+
+module.exports = {
+  unwrapControllerData,
+  apiErrorMessage,
+  throwIfApiFailed,
+  assertSyncStatsOk,
+  findExistingUser
+};