@aifabrix/builder 2.43.0 → 2.44.1

package/lib/utils/external-system-system-test-tty.js

@@ -0,0 +1,417 @@
+/**
+ * @fileoverview System-level TTY renderer for DatasourceTestRun fan-out results (plan §17).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const {
+  SEP,
+  statusGlyph
+} = require('./datasource-test-run-display');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatStatusKeyValue,
+  integrationFooterLine,
+  colorRollupPrefixedLine,
+  metadata: metaGray
+} = require('./cli-test-layout-chalk');
+const {
+  formatDataQualityLines,
+  readinessLineFromDataReadiness,
+  verdictLineFromEnvelope
+} = require('./validation-report-tty-kit');
+const {
+  logCapabilitiesOverview: logCapabilitiesOverviewSection,
+  logIntegrationHealthSection: logIntegrationHealthSectionBlock
+} = require('./external-system-system-test-tty-overview');
+
+/**
+  * @param {'ok'|'warn'|'fail'|'skipped'|null} st
+  * @returns {number}
+  */
+function statusRank(st) {
+  if (st === 'fail') return 0;
+  if (st === 'warn') return 1;
+  if (st === 'ok') return 2;
+  if (st === 'skipped') return 3;
+  return 4;
+}
+
+/**
+ * Per-row status for system rollup and tables: CLI/transport failure overrides envelope-only OK.
+ * @param {{ skipped?: boolean, success?: boolean, datasourceTestRun?: { status?: string }|null }} r
+ * @returns {'ok'|'warn'|'fail'|'skipped'}
+ */
+function rollupRowStatus(r) {
+  if (r && r.skipped) return 'skipped';
+  if (r && r.success === false) return 'fail';
+  const env = r && r.datasourceTestRun;
+  return env && typeof env.status === 'string' ? env.status : 'ok';
+}
+
+/**
+  * @param {Array<{ key: string, skipped?: boolean, datasourceTestRun?: Object|null, success?: boolean }>} rows
+  * @returns {'ok'|'warn'|'fail'|'skipped'}
+  */
+function deriveSystemStatus(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return 'ok';
+  const statuses = rows.map(rollupRowStatus);
+  if (statuses.some(s => s === 'fail')) return 'fail';
+  if (statuses.some(s => s === 'warn')) return 'warn';
+  if (statuses.every(s => s === 'skipped')) return 'skipped';
+  // Mixed ok/skipped => warn per plan.
+  return statuses.every(s => s === 'ok') ? 'ok' : 'warn';
+}
+
+function bucketIssueSeverity(issue) {
+  const sev = issue && issue.severity ? String(issue.severity).toLowerCase() : '';
+  if (sev === 'error' || sev === 'critical' || sev === 'high' || sev === 'fatal') return 'fail';
+  if (sev === 'warn' || sev === 'warning' || sev === 'medium') return 'warn';
+  return null;
+}
+
+/**
+  * Minimal heuristic rollups backed by envelope fields (no engine codenames).
+  * @param {Object|null|undefined} env
+  * @returns {'ok'|'warn'|'fail'}
+  */
+function dqFromEnvelope(env) {
+  const v = env && env.validation;
+  const st = v && typeof v.status === 'string' ? String(v.status) : null;
+  if (st === 'fail') return 'fail';
+  if (st === 'warn') return 'warn';
+
+  const issues = v && Array.isArray(v.issues) ? v.issues : [];
+  if (issues.some(i => bucketIssueSeverity(i) === 'fail')) return 'fail';
+  if (issues.some(i => bucketIssueSeverity(i) === 'warn')) return 'warn';
+  return 'ok';
+}
+
+/**
+  * @param {Array} rows
+  * @returns {{ schema: 'ok'|'warn'|'fail', consistency: 'ok'|'warn'|'fail', reliability: 'ok'|'warn'|'fail' }}
+  */
+function deriveSystemDataQuality(rows) {
+  const envs = rows
+    .map(r => (r && r.datasourceTestRun && typeof r.datasourceTestRun === 'object' ? r.datasourceTestRun : null))
+    .filter(Boolean);
+  if (envs.length === 0) {
+    return { schema: 'warn', consistency: 'warn', reliability: 'warn' };
+  }
+
+  const picks = envs.map(dqFromEnvelope);
+  const agg = picks.some(x => x === 'fail') ? 'fail' : picks.some(x => x === 'warn') ? 'warn' : 'ok';
+  return { schema: agg, consistency: agg, reliability: agg };
+}
+
+/**
+  * @param {Array} rows
+  * @returns {'ready'|'partial'|'not_ready'|null}
+  */
+function deriveSystemReadiness(rows) {
+  const envs = rows
+    .map(r => (r && r.datasourceTestRun && typeof r.datasourceTestRun === 'object' ? r.datasourceTestRun : null))
+    .filter(Boolean);
+  const drs = envs
+    .map(e => e.validation && e.validation.dataReadiness)
+    .filter(Boolean);
+  if (drs.length === 0) return null;
+  if (drs.some(x => x === 'not_ready')) return 'not_ready';
+  if (drs.some(x => x === 'partial')) return 'partial';
+  return 'ready';
+}
+
+function countByStatus(rows) {
+  const counts = { ok: 0, warn: 0, fail: 0, skipped: 0 };
+  for (const r of rows) {
+    const s = rollupRowStatus(r);
+    if (counts[s] !== undefined) counts[s] += 1;
+  }
+  return counts;
+}
+
+function pickBlockingDatasourceKey(rows) {
+  const keys = rows
+    .map(r => {
+      const env = r && r.datasourceTestRun;
+      const st = rollupRowStatus(r);
+      const key =
+        env && env.datasourceKey
+          ? String(env.datasourceKey)
+          : r && r.key
+            ? String(r.key)
+            : '';
+      return { key, st };
+    })
+    .filter(x => x.key);
+  keys.sort((a, b) => {
+    const d = statusRank(a.st) - statusRank(b.st);
+    if (d !== 0) return d;
+    return a.key.localeCompare(b.key);
+  });
+  return keys.length ? keys[0].key : null;
+}
+
+function issueKey(issue) {
+  const code = issue && issue.code ? String(issue.code) : '';
+  const msg = issue && issue.message ? String(issue.message) : '';
+  return `${code}::${msg}`.toLowerCase();
+}
+
+function issueSortKey(it) {
+  return `${statusRank(it.severity)}::${it.datasourceKey}::${it.message}`.toLowerCase();
+}
+
+function extractRowIssues(row) {
+  const env = row && row.datasourceTestRun;
+  const datasourceKey = (env && env.datasourceKey) || (row && row.key) || 'datasource';
+  const issues = env && env.validation && Array.isArray(env.validation.issues) ? env.validation.issues : [];
+  const envStatus = env && typeof env.status === 'string' ? env.status : null;
+  return { datasourceKey: String(datasourceKey), issues, envStatus };
+}
+
+function toIssueItem(datasourceKey, envStatus, iss) {
+  const sev =
+    bucketIssueSeverity(iss) ||
+    (envStatus === 'fail' ? 'fail' : envStatus === 'warn' ? 'warn' : 'ok');
+  const msg = iss && iss.message ? String(iss.message) : iss && iss.code ? String(iss.code) : 'Issue';
+  return { datasourceKey, message: msg, severity: sev };
+}
+
+function collectKeyIssues(rows, cap) {
+  /** @type {{ datasourceKey: string, message: string, severity: 'fail'|'warn'|'ok' }[]} */
+  const out = [];
+  const seen = new Set();
+  for (const row of rows) {
+    const { datasourceKey, issues, envStatus } = extractRowIssues(row);
+    for (const iss of issues) {
+      const k = `${datasourceKey}::${issueKey(iss)}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      out.push(toIssueItem(datasourceKey, envStatus, iss));
+    }
+  }
+  out.sort((a, b) => issueSortKey(a).localeCompare(issueSortKey(b)));
+  return out.slice(0, Math.max(0, cap));
+}
+
+function certificateBucket(env) {
+  const cert = env && env.certificate;
+  if (!cert || typeof cert !== 'object') return { status: null, level: null };
+  return {
+    status: cert.status ? String(cert.status) : null,
+    level: cert.level ? String(cert.level) : null
+  };
+}
+
+function systemCertStatus(rows) {
+  const certs = rows
+    .map(r => (r && r.datasourceTestRun ? certificateBucket(r.datasourceTestRun) : { status: null, level: null }))
+    .filter(c => c.status !== null);
+  if (certs.length === 0) return null;
+  if (certs.some(c => c.status === 'not_passed')) return 'not_passed';
+  return 'passed';
+}
+
+function drillDownCommand(runType, datasourceKey) {
+  if (!datasourceKey) return null;
+  if (runType === 'e2e') return `aifabrix datasource test-e2e ${datasourceKey}`;
+  if (runType === 'integration') return `aifabrix datasource test-integration ${datasourceKey}`;
+  return `aifabrix datasource test ${datasourceKey}`;
+}
+
+function logSystemHeader(results, runType, systemStatus) {
+  logger.log('');
+  logger.log(sectionTitle('Server test results'));
+  logger.log('');
+  logger.log(headerKeyValue('System:', results.systemKey));
+  logger.log(
+    headerKeyValue(
+      'Run:',
+      runType === 'e2e' ? 'test-e2e (dataplane)' : 'test-integration (dataplane)'
+    )
+  );
+  logger.log(formatStatusKeyValue(systemStatus, statusGlyph(systemStatus)));
+  logger.log('');
+}
+
+function logVerdictAndSummary(runType, systemStatus, certStatus, counts) {
+  logger.log(sectionTitle('Verdict:'));
+  logger.log(chalk.white(verdictLineFromEnvelope(systemStatus, certStatus, runType)));
+  logger.log('');
+  logger.log(sectionTitle('Summary:'));
+  logger.log(
+    chalk.white(
+      `${counts.ok + counts.warn + counts.fail} datasource(s): ${counts.ok} ok, ${counts.warn} warn, ${counts.fail} fail${counts.skipped ? `, ${counts.skipped} skipped` : ''}`
+    )
+  );
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+}
+
+function logDataQualityAndReadiness(rows) {
+  logger.log(sectionTitle('Data Quality:'));
+  const dq = deriveSystemDataQuality(rows);
+  const dqLines = formatDataQualityLines(dq, {
+    schema: 'structural coverage aggregated across datasources.',
+    consistency: 'issues aggregated across datasources.',
+    reliability: 'issues aggregated across datasources.'
+  });
+  dqLines.map(colorRollupPrefixedLine).forEach(l => logger.log(l));
+
+  const readiness = deriveSystemReadiness(rows);
+  const readinessLine = readinessLineFromDataReadiness(readiness);
+  if (readinessLine) {
+    logger.log('');
+    logger.log(colorRollupPrefixedLine(readinessLine));
+  }
+
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+}
+
+function logDatasourceTable(rows, counts, verbose) {
+  logger.log(sectionTitle('Datasources:'));
+  logger.log('');
+  if (!verbose && counts.ok > 0) {
+    logger.log(chalk.gray(`✔ ${counts.ok} datasource(s) fully ready`));
+  }
+
+  function rowStatus(r) {
+    return rollupRowStatus(r);
+  }
+
+  function readinessLabel(env, st) {
+    const ready = env && env.validation ? env.validation.dataReadiness : null;
+    if (ready === 'not_ready') return 'Not ready';
+    if (ready === 'partial') return 'Partial';
+    if (ready === 'ready') return 'Ready';
+    if (st === 'fail') return 'Not ready';
+    if (st === 'warn') return 'Partial';
+    return 'Ready';
+  }
+
+  function shouldListRow(r) {
+    if (verbose) return true;
+    const st = rowStatus(r);
+    return st === 'warn' || st === 'fail';
+  }
+
+  const listRows = rows.filter(shouldListRow);
+  for (const r of listRows) {
+    const env = r && r.datasourceTestRun;
+    const key = (env && env.datasourceKey) || (r && r.key) || 'datasource';
+    const st = rowStatus(r);
+    const readyLabel = readinessLabel(env, st);
+    logger.log(`${statusGlyph(st)} ${chalk.white(String(key).padEnd(22))} (${readyLabel})`);
+  }
+}
+
+function logBlockingDatasource(blocking) {
+  if (!blocking) return;
+  logger.log('');
+  logger.log(chalk.white(`Blocking datasource: ${blocking}`));
+}
+
+function logKeyIssuesSection(rows) {
+  const issues = collectKeyIssues(rows, 5);
+  if (issues.length === 0) return false;
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Key issues:'));
+  logger.log('');
+  let cur = null;
+  for (const it of issues) {
+    if (cur !== it.datasourceKey) {
+      cur = it.datasourceKey;
+      logger.log(chalk.white(cur));
+    }
+    logger.log(chalk.white(`- ${it.message}`));
+  }
+  return true;
+}
+
+function logCertificationSection(rows) {
+  const certSt = systemCertStatus(rows);
+  if (!certSt) return;
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Certification:'));
+  logger.log('');
+  logger.log(chalk.white(`System level: ${certSt === 'passed' ? '✔ Achieved' : '✖ Not achieved'}`));
+  logger.log('');
+  logger.log(chalk.white('Breakdown:'));
+  for (const r of rows) {
+    const env = r && r.datasourceTestRun;
+    if (!env) continue;
+    const cert = certificateBucket(env);
+    if (!cert.status) continue;
+    const g = cert.status === 'passed' ? '✔' : '✖';
+    const tier = cert.level ? cert.level : '(no level)';
+    logger.log(chalk.white(`- ${env.datasourceKey}: ${g} ${tier}`));
+  }
+}
+
+function logUseAndFooter(results, runType, systemStatus, blocking) {
+  logger.log('');
+  logger.log(metaGray(SEP));
+  logger.log('');
+  logger.log(sectionTitle('Use:'));
+  const cmd = drillDownCommand(runType, blocking);
+  logger.log(chalk.white(cmd || 'aifabrix datasource test <datasourceKey>'));
+  logger.log(
+    integrationFooterLine(
+      results.success,
+      systemStatus,
+      'All server tests passed.',
+      'Server tests completed with warnings.',
+      'Some server tests failed.'
+    )
+  );
+}
+
+/**
+  * Render system-level aggregate (plan §17) for DatasourceTestRun wrapper results.
+  * @param {Object} results
+  * @param {Object} opts
+  * @param {'integration'|'e2e'} opts.runType
+  * @param {boolean} opts.verbose
+  */
+function displaySystemAggregateDatasourceTestRuns(results, opts) {
+  const rows = Array.isArray(results.datasourceResults) ? results.datasourceResults : [];
+  const runType = opts.runType === 'e2e' ? 'e2e' : 'integration';
+  const systemStatus = deriveSystemStatus(rows);
+  const counts = countByStatus(rows);
+  const blocking = pickBlockingDatasourceKey(rows);
+  logSystemHeader(results, runType, systemStatus);
+  logVerdictAndSummary(runType, systemStatus, systemCertStatus(rows), counts);
+  logDataQualityAndReadiness(rows);
+  logDatasourceTable(rows, counts, Boolean(opts.verbose));
+  logBlockingDatasource(blocking);
+  logKeyIssuesSection(rows);
+  const ttyIo = { log: logger.log.bind(logger), chalk, metaGray, sectionTitle, statusGlyph, SEP };
+  logCapabilitiesOverviewSection(rows, ttyIo);
+  logIntegrationHealthSectionBlock(rows, runType, ttyIo);
+  logCertificationSection(rows);
+  logUseAndFooter(results, runType, systemStatus, blocking);
+}
+
+module.exports = {
+  displaySystemAggregateDatasourceTestRuns,
+  deriveSystemStatus,
+  deriveSystemDataQuality,
+  deriveSystemReadiness,
+  rollupRowStatus,
+  pickBlockingDatasourceKey,
+  collectKeyIssues,
+  systemCertStatus,
+  drillDownCommand
+};
+

package/lib/utils/external-system-test-helpers.js

@@ -12,9 +12,32 @@
 const fs = require('fs').promises;
 const path = require('path');
 const { testDatasourceViaPipeline } = require('../api/pipeline.api');
+const { integrationResultFromEnvelope, firstIssueMessage } = require('./datasource-test-run-legacy-adapter');
 
 /** Pipeline test endpoints accept client credentials; do not enforce Bearer-only */
 
+/**
+ * Parse successful pipeline test body (envelope or legacy).
+ * @param {Object} body
+ * @param {string} datasourceKey
+ * @returns {Object}
+ * @throws {Error} When body indicates failure
+ */
+function parsePipelineTestResponseBody(body, datasourceKey) {
+  if (body && typeof body === 'object' && typeof body.status === 'string' && body.datasourceKey) {
+    if (body.status === 'fail') {
+      const errMsg = firstIssueMessage(body) || 'Test failed';
+      throw new Error(`Test endpoint failed: ${errMsg}`);
+    }
+    return integrationResultFromEnvelope(body, datasourceKey);
+  }
+  if (body.success === false) {
+    const errMsg = body.error || body.formattedError || 'Test failed';
+    throw new Error(`Test endpoint failed: ${errMsg}`);
+  }
+  return body.data || body;
+}
+
 /**
  * Retry API call with exponential backoff
  * @async
@@ -73,13 +96,8 @@ async function callPipelineTestEndpoint({ systemKey, datasourceKey, payloadTempl
   if (!response.success || !response.data) {
     throw new Error(`Test endpoint failed: ${response.error || response.formattedError || 'Unknown error'}`);
   }
-  // When 200 with success: false in body, pass through; caller interprets via data.success
-  if (response.data?.success === false) {
-    const errMsg = response.data?.error || response.data?.formattedError || 'Test failed';
-    throw new Error(`Test endpoint failed: ${errMsg}`);
-  }
 
-  return response.data.data || response.data;
+  return parsePipelineTestResponseBody(response.data, datasourceKey);
 }
 
 /**

package/lib/utils/external-system-validators.js

@@ -119,24 +119,38 @@ function checkPathExistsInPayload(fieldPath, payloadTemplate) {
 }
 
 /**
- * Validates dimensions object structure and content
- * @param {Object} dimensions - Dimensions object to validate
+ * Root dimensions (dimensionBinding): local bindings as dimKey → metadata path string for validateDimensions.
+ * @param {Object} datasource - Datasource config
+ * @returns {Object} Map suitable for validateDimensions
+ */
+function getDimensionsMapForValidation(datasource) {
+  const root = datasource?.dimensions;
+  if (!root || typeof root !== 'object' || Array.isArray(root)) return {};
+  const out = {};
+  for (const [dimKey, binding] of Object.entries(root)) {
+    if (binding && typeof binding === 'object' && typeof binding.field === 'string') {
+      out[dimKey] = `metadata.${binding.field}`;
+    }
+  }
+  return out;
+}
+
+/**
+ * Validates dimensions object structure and content (path strings).
+ * @param {Object} dimensions - dimKey → path (e.g. metadata.country)
  * @param {Object} results - Results object to update
  */
 function validateDimensions(dimensions, results) {
-  if (!dimensions) {
-    results.errors.push('fieldMappings.dimensions is required (dimensions-first model)');
-    results.valid = false;
+  if (!dimensions || typeof dimensions !== 'object' || Array.isArray(dimensions)) {
+    results.warnings.push('No dimensions configured (schema v2.4: use root dimensions; optional but recommended for ABAC)');
     return;
   }
 
-  if (typeof dimensions !== 'object' || Array.isArray(dimensions)) {
-    results.errors.push('fieldMappings.dimensions must be an object mapping dimension keys to attribute paths');
-    results.valid = false;
+  if (Object.keys(dimensions).length === 0) {
+    results.warnings.push('Dimensions object is empty');
     return;
   }
 
-  // Validate dimension keys and values
   for (const [dimensionKey, attributePath] of Object.entries(dimensions)) {
     if (!/^[a-zA-Z0-9_]+$/.test(dimensionKey)) {
       results.errors.push(`Invalid dimension key '${dimensionKey}': dimension key must contain only letters, numbers, and underscores`);
@@ -180,7 +194,7 @@ function validateAttributesStructure(attributes, results) {
  */
 function validateSingleAttribute(attributeName, attributeConfig, payloadTemplate, results) {
   if (!attributeConfig || typeof attributeConfig !== 'object') {
-    results.errors.push(`Attribute '${attributeName}' must be an object with expression and type`);
+    results.errors.push(`Attribute '${attributeName}' must be an object with expression`);
     results.valid = false;
     return;
   }
@@ -224,8 +238,7 @@ function validateFieldMappings(datasource, testPayload) {
     return results;
   }
 
-  // Validate dimensions (required in new schema)
-  validateDimensions(datasource.fieldMappings.dimensions, results);
+  validateDimensions(getDimensionsMapForValidation(datasource), results);
 
   // Validate attributes structure (required in new schema)
   const attributes = validateAttributesStructure(datasource.fieldMappings.attributes, results);
@@ -322,6 +335,11 @@ function validateAgainstSchema(data, schema) {
     validateSchema: false
   });
   addFormats(ajv);
+  // Some schemas (e.g. external-datasource.schema.json) reference these by $id (aifabrix://schema/type/*).
+  // Adding them up-front keeps validation offline-safe and avoids unresolved $ref failures.
+  ajv.addSchema(require('../schema/type/document-storage.json'));
+  ajv.addSchema(require('../schema/type/message-service.json'));
+  ajv.addSchema(require('../schema/type/vector-store.json'));
   // Remove $schema for draft-2020-12 to avoid AJV issues
   const schemaCopy = { ...schema };
   if (schemaCopy.$schema && schemaCopy.$schema.includes('2020-12')) {

package/lib/utils/health-check-url.js

@@ -0,0 +1,119 @@
+/**
+ * Health check URL resolution helpers.
+ *
+ * @fileoverview Compute health check URL using declarative public URL logic (Traefik/frontDoorRouting)
+ */
+
+'use strict';
+
+const { computePublicUrlBaseString } = require('./url-declarative-public-base');
+const { parseDeveloperIdNum } = require('./declarative-url-ports');
+
+/**
+ * Join URL path segments with exactly one slash between them.
+ * @param {string} a
+ * @param {string} b
+ * @returns {string}
+ */
+function joinUrlPath(a, b) {
+  const left = String(a || '').replace(/\/+$/, '');
+  const right = String(b || '').replace(/^\/+/, '');
+  if (!left) return `/${right}`;
+  if (!right) return left || '/';
+  return `${left}/${right}`;
+}
+
+/**
+ * Convert a frontDoorRouting.pattern (Traefik/Front Door wildcard route) into a concrete mount path.
+ * Example: "/auth/*" -> "/auth"
+ *
+ * @param {string} pattern
+ * @returns {string}
+ */
+function normalizeFrontDoorPatternForHealth(pattern) {
+  let p = String(pattern || '').trim();
+  if (!p) return '/';
+  if (!p.startsWith('/')) p = `/${p}`;
+  // Drop wildcard suffixes used for routing.
+  p = p.replace(/\/\*+$/, '');
+  p = p.replace(/\*+$/, '');
+  // Drop trailing path params like "/foo/{bar}" if present (health is mounted at the base).
+  p = p.replace(/\/\{[^}]+\}$/, '');
+  // Normalize slashes and trailing slash.
+  p = p.replace(/\/{2,}/g, '/');
+  p = p.replace(/\/+$/, '');
+  return p || '/';
+}
+
+/**
+ * @param {Object|null} appConfig
+ * @returns {boolean}
+ */
+function frontDoorEnabled(appConfig) {
+  return Boolean(appConfig && appConfig.frontDoorRouting && appConfig.frontDoorRouting.enabled === true);
+}
+
+/**
+ * @param {Object|null} appConfig
+ * @returns {string|null}
+ */
+function frontDoorPattern(appConfig) {
+  const p = appConfig && appConfig.frontDoorRouting ? appConfig.frontDoorRouting.pattern : null;
+  return (typeof p === 'string' && p.trim()) ? p.trim() : null;
+}
+
+/**
+ * Compute the Traefik front-door health check URL when applicable.
+ *
+ * Returns null when Traefik/frontDoorRouting isn't active or cannot be resolved.
+ *
+ * @async
+ * @param {string} appName
+ * @param {number} healthCheckPort
+ * @param {Object|null} appConfig
+ * @returns {Promise<string|null>}
+ */
+async function computeTraefikHealthCheckUrl(appName, healthCheckPort, appConfig) {
+  if (!frontDoorEnabled(appConfig)) return null;
+  const pattern = frontDoorPattern(appConfig);
+  if (!pattern) return null;
+
+  const coreConfig = require('../core/config');
+  const userCfg = await coreConfig.getConfig();
+  if (!(userCfg && userCfg.traefik)) return null;
+
+  const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
+  const remoteServer = await coreConfig.getRemoteServer();
+  const developerIdRaw = await coreConfig.getDeveloperId();
+  const developerIdNum = parseDeveloperIdNum(developerIdRaw);
+
+  // Health checks originate from the CLI on the host, not from inside a container.
+  const profile = 'local';
+  const fd = appConfig.frontDoorRouting;
+  const listenPort = Number(appConfig?.port || 3000);
+
+  const publicBase = computePublicUrlBaseString({
+    traefik: true,
+    pathActive: true,
+    hostTemplate: fd.host,
+    tls: fd.tls,
+    developerIdRaw,
+    remoteServer,
+    profile,
+    listenPort,
+    developerIdNum,
+    infraTlsEnabled
+  });
+
+  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
+  const mountPath = normalizeFrontDoorPatternForHealth(pattern);
+  const baseWithFrontDoor = joinUrlPath(publicBase, mountPath);
+  return joinUrlPath(baseWithFrontDoor, healthCheckPath);
+}
+
+module.exports = {
+  joinUrlPath,
+  normalizeFrontDoorPatternForHealth,
+  computeTraefikHealthCheckUrl
+};
+