@roastcodes/ttdash 6.1.8 → 6.2.0

package/server/report/utils.js

@@ -1,323 +1,24 @@
 const { version: APP_VERSION } = require('../../package.json');
 const { getLanguage, getLocale, translate } = require('./i18n');
-const modelNormalizationSpec = require('../model-normalization.json');
-
-const DISPLAY_ALIASES = modelNormalizationSpec.displayAliases.map((alias) => ({
-  ...alias,
-  matcher: new RegExp(alias.pattern, 'i'),
-}));
-const PROVIDER_MATCHERS = modelNormalizationSpec.providerMatchers.map((matcher) => ({
-  ...matcher,
-  matcher: new RegExp(matcher.pattern, 'i'),
-}));
-
-const MODEL_COLORS = {
-  'Opus 4.6': 'rgb(175, 92, 224)',
-  'Opus 4.5': 'rgb(200, 66, 111)',
-  'Sonnet 4.6': 'rgb(71, 134, 221)',
-  'Sonnet 4.5': 'rgb(66, 161, 130)',
-  'Haiku 4.5': 'rgb(231, 146, 34)',
-  'GPT-5.4': 'rgb(230, 98, 56)',
-  'GPT-5': 'rgb(230, 98, 56)',
-  'Gemini 3 Flash Preview': 'rgb(237, 188, 8)',
-  Gemini: 'rgb(237, 188, 8)',
-  OpenCode: 'rgb(51, 181, 193)',
-};
+const { truncateTopModelChartLabel } = require('./chart-labels');
+const {
+  aggregateToDailyFormat,
+  computeMetrics,
+  computeMovingAverage,
+  filterByDateRange,
+  filterByModels,
+  filterByMonth,
+  filterByProviders,
+  getModelProvider,
+  normalizeModelName,
+  sortByDate,
+} = require('../../shared/dashboard-domain');
+const { getModelColorRgb } = require('../../shared/model-colors.js');
 
 const WEEKDAYS = ['Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa', 'So'];
 
-function titleCaseSegment(segment) {
-  if (!segment) return segment;
-  if (/^\d+([.-]\d+)*$/.test(segment)) return segment.replace(/-/g, '.');
-  if (/^[a-z]{1,4}\d+$/i.test(segment)) return segment.toUpperCase();
-  return segment.charAt(0).toUpperCase() + segment.slice(1);
-}
-
-function capitalize(segment) {
-  if (!segment) return '';
-  return segment.charAt(0).toUpperCase() + segment.slice(1);
-}
-
-function formatVersion(version) {
-  return version.replace(/-/g, '.');
-}
-
-function canonicalizeModelName(raw) {
-  const normalized = String(raw || '')
-    .trim()
-    .toLowerCase()
-    .replace(/^model[:/ -]*/i, '')
-    .replace(/^(anthropic|openai|google|vertex|models)[/-]/i, '')
-    .replace(/\./g, '-')
-    .replace(/[_/]+/g, '-')
-    .replace(/\s+/g, '-')
-    .replace(/-{2,}/g, '-')
-    .replace(/^-|-$/g, '');
-
-  const suffixStart = normalized.lastIndexOf('-');
-  if (suffixStart > 0) {
-    const suffix = normalized.slice(suffixStart + 1);
-    if (suffix.length === 8 && suffix.startsWith('20') && /^\d+$/.test(suffix)) {
-      return normalized.slice(0, suffixStart);
-    }
-  }
-
-  return normalized;
-}
-
-function parseClaudeName(rest) {
-  const parts = rest.split('-', 2);
-  if (parts.length < 2) {
-    return `Claude ${capitalize(rest)}`;
-  }
-
-  return `${capitalize(parts[0] || '')} ${formatVersion(parts[1] || '')}`.trim();
-}
-
-function parseGptName(rest) {
-  const parts = rest.split('-');
-  const variant = parts[0] || '';
-  const minor = parts[1] || '';
-
-  if (minor && minor.length <= 2 && /^\d+$/.test(minor)) {
-    const version = `${variant}.${minor}`;
-    if (parts.length > 2) {
-      const suffix = parts.slice(2).map(capitalize).join(' ');
-      return `GPT-${version}${suffix ? ` ${suffix}` : ''}`;
-    }
-    return `GPT-${version}`;
-  }
-
-  if (parts.length > 1) {
-    const suffix = parts.slice(1).map(capitalize).join(' ');
-    return `GPT-${variant}${suffix ? ` ${suffix}` : ''}`;
-  }
-
-  return `GPT-${rest}`;
-}
-
-function parseGeminiName(rest) {
-  const parts = rest.split('-');
-  if (parts.length < 2) {
-    return `Gemini ${rest}`;
-  }
-
-  const versionParts = [];
-  const tierParts = [];
-
-  for (const part of parts) {
-    if (/^\d+$/.test(part) && tierParts.length === 0) {
-      versionParts.push(part);
-    } else {
-      tierParts.push(capitalize(part));
-    }
-  }
-
-  const version = versionParts.join('.');
-  const tier = tierParts.join(' ');
-
-  return tier ? `Gemini ${version} ${tier}` : `Gemini ${version}`;
-}
-
-function parseCodexName(rest) {
-  const normalized = rest.replace(/-latest$/i, '');
-  if (!normalized) {
-    return 'Codex';
-  }
-  return `Codex ${normalized.split('-').map(capitalize).join(' ')}`;
-}
-
-function parseOSeries(name) {
-  const separatorIndex = name.indexOf('-');
-  if (separatorIndex === -1) {
-    return name;
-  }
-  return `${name.slice(0, separatorIndex)} ${capitalize(name.slice(separatorIndex + 1))}`;
-}
-
-function normalizeModelName(raw) {
-  const canonical = canonicalizeModelName(raw);
-
-  for (const alias of DISPLAY_ALIASES) {
-    if (alias.matcher.test(canonical)) return alias.name;
-  }
-
-  if (canonical.startsWith('claude-')) {
-    return parseClaudeName(canonical.slice('claude-'.length));
-  }
-
-  if (canonical.startsWith('gpt-')) {
-    return parseGptName(canonical.slice('gpt-'.length));
-  }
-
-  if (canonical.startsWith('gemini-')) {
-    return parseGeminiName(canonical.slice('gemini-'.length));
-  }
-
-  if (canonical.startsWith('codex-')) {
-    return parseCodexName(canonical.slice('codex-'.length));
-  }
-
-  if (/^o\d/i.test(canonical)) {
-    return parseOSeries(canonical);
-  }
-
-  const familyMatch = canonical.match(
-    /^(gpt|opus|sonnet|haiku|gemini|codex|o\d|oai|grok|llama|mistral|command|deepseek|qwen)(?:-([a-z0-9-]+))?$/i,
-  );
-  if (familyMatch) {
-    const family = familyMatch[1];
-    if (/^codex$/i.test(family)) {
-      return parseCodexName(familyMatch[2] || '');
-    }
-    if (/^(o\d)$/i.test(family)) return parseOSeries(canonical);
-
-    const suffix = familyMatch[2] ? formatVersion(familyMatch[2]) : '';
-    if (/^gpt$/i.test(family) && suffix) return `GPT-${suffix.toUpperCase()}`;
-    return `${titleCaseSegment(family)}${suffix ? ` ${suffix}` : ''}`.trim();
-  }
-
-  return canonical.split('-').filter(Boolean).map(titleCaseSegment).join(' ') || String(raw || '');
-}
-
-function getModelProvider(raw) {
-  const canonical = canonicalizeModelName(raw);
-  for (const matcher of PROVIDER_MATCHERS) {
-    if (matcher.matcher.test(canonical)) return matcher.provider;
-  }
-  return 'Other';
-}
-
 function getModelColor(name) {
-  return MODEL_COLORS[name] || 'rgb(113, 128, 150)';
-}
-
-function sortByDate(data) {
-  return [...data].sort((a, b) => a.date.localeCompare(b.date));
-}
-
-function filterByDateRange(data, start, end) {
-  return data.filter((day) => {
-    if (start && day.date < start) return false;
-    if (end && day.date > end) return false;
-    return true;
-  });
-}
-
-function filterByMonth(data, month) {
-  if (!month) return data;
-  return data.filter((day) => day.date.startsWith(month));
-}
-
-function recalculateDayFromBreakdowns(day, modelBreakdowns) {
-  let inputTokens = 0;
-  let outputTokens = 0;
-  let cacheCreationTokens = 0;
-  let cacheReadTokens = 0;
-  let thinkingTokens = 0;
-  let totalCost = 0;
-  let requestCount = 0;
-
-  for (const breakdown of modelBreakdowns) {
-    inputTokens += breakdown.inputTokens;
-    outputTokens += breakdown.outputTokens;
-    cacheCreationTokens += breakdown.cacheCreationTokens;
-    cacheReadTokens += breakdown.cacheReadTokens;
-    thinkingTokens += breakdown.thinkingTokens;
-    totalCost += breakdown.cost;
-    requestCount += breakdown.requestCount;
-  }
-
-  return {
-    ...day,
-    inputTokens,
-    outputTokens,
-    cacheCreationTokens,
-    cacheReadTokens,
-    thinkingTokens,
-    totalCost,
-    requestCount,
-    totalTokens:
-      inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens + thinkingTokens,
-    modelsUsed: modelBreakdowns.map((item) => item.modelName),
-    modelBreakdowns,
-  };
-}
-
-function filterByProviders(data, selectedProviders) {
-  if (!selectedProviders || selectedProviders.length === 0) return data;
-  const selected = new Set(selectedProviders);
-  return data
-    .map((day) => {
-      const filteredBreakdowns = day.modelBreakdowns.filter((entry) =>
-        selected.has(getModelProvider(entry.modelName)),
-      );
-      return filteredBreakdowns.length > 0
-        ? recalculateDayFromBreakdowns(day, filteredBreakdowns)
-        : null;
-    })
-    .filter(Boolean);
-}
-
-function filterByModels(data, selectedModels) {
-  if (!selectedModels || selectedModels.length === 0) return data;
-  const selected = new Set(selectedModels);
-  return data
-    .map((day) => {
-      const filteredBreakdowns = day.modelBreakdowns.filter((entry) =>
-        selected.has(normalizeModelName(entry.modelName)),
-      );
-      return filteredBreakdowns.length > 0
-        ? recalculateDayFromBreakdowns(day, filteredBreakdowns)
-        : null;
-    })
-    .filter(Boolean);
-}
-
-function aggregateToDailyFormat(data, viewMode) {
-  if (viewMode === 'daily') return data;
-  const groupKey = viewMode === 'monthly' ? (date) => date.slice(0, 7) : (date) => date.slice(0, 4);
-  const groups = new Map();
-
-  for (const day of data) {
-    const key = groupKey(day.date);
-    const existing = groups.get(key);
-    const days = day._aggregatedDays || 1;
-
-    if (!existing) {
-      groups.set(key, {
-        ...day,
-        date: key,
-        _aggregatedDays: days,
-      });
-      continue;
-    }
-
-    existing.totalCost += day.totalCost;
-    existing.totalTokens += day.totalTokens;
-    existing.inputTokens += day.inputTokens;
-    existing.outputTokens += day.outputTokens;
-    existing.cacheCreationTokens += day.cacheCreationTokens;
-    existing.cacheReadTokens += day.cacheReadTokens;
-    existing.thinkingTokens += day.thinkingTokens;
-    existing.requestCount += day.requestCount;
-    existing._aggregatedDays += days;
-    existing.modelBreakdowns = existing.modelBreakdowns.concat(day.modelBreakdowns);
-    existing.modelsUsed = Array.from(new Set(existing.modelsUsed.concat(day.modelsUsed)));
-  }
-
-  return Array.from(groups.values()).sort((a, b) => a.date.localeCompare(b.date));
-}
-
-function computeMovingAverage(values, window = 7) {
-  const result = new Array(values.length);
-  let sum = 0;
-  for (let index = 0; index < values.length; index += 1) {
-    sum += values[index];
-    if (index >= window) sum -= values[index - window];
-    result[index] = index < window - 1 ? null : sum / window;
-  }
-  return result;
+  return getModelColorRgb(name, { theme: 'light' });
 }
 
 function toCostChartData(data) {
@@ -362,163 +63,6 @@ function toWeekdayData(data) {
   });
 }
 
-function stdDev(values) {
-  if (!values.length) return 0;
-  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
-  const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
-  return Math.sqrt(variance);
-}
-
-function computeWeekOverWeekChange(data) {
-  if (data.some((entry) => !/^\d{4}-\d{2}-\d{2}$/.test(entry.date))) return null;
-  if (data.length < 14) return null;
-  const sorted = sortByDate(data);
-  const last7 = sorted.slice(-7);
-  const prev7 = sorted.slice(-14, -7);
-  const lastSum = last7.reduce((sum, day) => sum + day.totalCost, 0);
-  const prevSum = prev7.reduce((sum, day) => sum + day.totalCost, 0);
-  if (prevSum === 0) return null;
-  return ((lastSum - prevSum) / prevSum) * 100;
-}
-
-function computeBusiestWeek(data) {
-  const sorted = sortByDate(data).filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry.date));
-  if (sorted.length < 3) return null;
-  let best = null;
-  for (let start = 0; start < sorted.length; start += 1) {
-    const startDate = new Date(`${sorted[start].date}T00:00:00`);
-    const endLimit = new Date(startDate);
-    endLimit.setDate(endLimit.getDate() + 6);
-    let cost = 0;
-    let end = start;
-    while (end < sorted.length && new Date(`${sorted[end].date}T00:00:00`) <= endLimit) {
-      cost += sorted[end].totalCost;
-      end += 1;
-    }
-    if (!best || cost > best.cost) {
-      best = { start: sorted[start].date, end: sorted[end - 1].date, cost };
-    }
-  }
-  return best;
-}
-
-function computeMetrics(data) {
-  if (data.length === 0) {
-    return {
-      totalCost: 0,
-      totalTokens: 0,
-      activeDays: 0,
-      totalRequests: 0,
-      hasRequestData: false,
-      avgDailyCost: 0,
-      avgRequestsPerDay: 0,
-      avgTokensPerRequest: 0,
-      avgCostPerRequest: 0,
-      cacheHitRate: 0,
-      costPerMillion: 0,
-      topModel: null,
-      topModelShare: 0,
-      topProvider: null,
-      topDay: null,
-      cheapestDay: null,
-      busiestWeek: null,
-      weekendCostShare: null,
-      weekOverWeekChange: null,
-      requestVolatility: 0,
-      providerCount: 0,
-    };
-  }
-
-  const modelCosts = new Map();
-  const providerCosts = new Map();
-  let totalCost = 0;
-  let totalTokens = 0;
-  let totalRequests = 0;
-  let totalInput = 0;
-  let totalOutput = 0;
-  let totalCacheRead = 0;
-  let totalCacheCreate = 0;
-  let totalThinking = 0;
-  let activeDays = 0;
-  let hasRequestData = false;
-  let weekendCost = 0;
-  let weekendEligible = 0;
-  let topDay = { date: data[0].date, cost: data[0].totalCost };
-  let cheapestDay = { date: data[0].date, cost: data[0].totalCost };
-
-  for (const day of data) {
-    totalCost += day.totalCost;
-    totalTokens += day.totalTokens;
-    totalRequests += day.requestCount;
-    totalInput += day.inputTokens;
-    totalOutput += day.outputTokens;
-    totalCacheRead += day.cacheReadTokens;
-    totalCacheCreate += day.cacheCreationTokens;
-    totalThinking += day.thinkingTokens;
-    activeDays += day._aggregatedDays || 1;
-    if (day.requestCount > 0 || day.modelBreakdowns.some((entry) => entry.requestCount > 0))
-      hasRequestData = true;
-    if (day.totalCost > topDay.cost) topDay = { date: day.date, cost: day.totalCost };
-    if (day.totalCost < cheapestDay.cost) cheapestDay = { date: day.date, cost: day.totalCost };
-
-    if (/^\d{4}-\d{2}-\d{2}$/.test(day.date)) {
-      const weekday = new Date(`${day.date}T00:00:00`).getDay();
-      if (weekday === 0 || weekday === 6) weekendCost += day.totalCost;
-      weekendEligible += day.totalCost;
-    }
-
-    for (const breakdown of day.modelBreakdowns) {
-      const model = normalizeModelName(breakdown.modelName);
-      const provider = getModelProvider(breakdown.modelName);
-      modelCosts.set(model, (modelCosts.get(model) || 0) + breakdown.cost);
-      providerCosts.set(provider, (providerCosts.get(provider) || 0) + breakdown.cost);
-    }
-  }
-
-  let topModel = null;
-  for (const [name, cost] of modelCosts) {
-    if (!topModel || cost > topModel.cost) topModel = { name, cost };
-  }
-
-  let topProvider = null;
-  for (const [name, cost] of providerCosts) {
-    if (!topProvider || cost > topProvider.cost) {
-      topProvider = { name, cost, share: totalCost > 0 ? (cost / totalCost) * 100 : 0 };
-    }
-  }
-
-  const cacheBase = totalCacheRead + totalCacheCreate + totalInput + totalOutput + totalThinking;
-
-  return {
-    totalCost,
-    totalTokens,
-    activeDays,
-    totalRequests,
-    totalInput,
-    totalOutput,
-    totalCacheRead,
-    totalCacheCreate,
-    totalThinking,
-    hasRequestData,
-    avgDailyCost: activeDays > 0 ? totalCost / activeDays : 0,
-    avgRequestsPerDay: hasRequestData && activeDays > 0 ? totalRequests / activeDays : 0,
-    avgTokensPerRequest: hasRequestData && totalRequests > 0 ? totalTokens / totalRequests : 0,
-    avgCostPerRequest: hasRequestData && totalRequests > 0 ? totalCost / totalRequests : 0,
-    cacheHitRate: cacheBase > 0 ? (totalCacheRead / cacheBase) * 100 : 0,
-    costPerMillion: totalTokens > 0 ? totalCost / (totalTokens / 1000000) : 0,
-    topModel,
-    topModelShare: topModel && totalCost > 0 ? (topModel.cost / totalCost) * 100 : 0,
-    topProvider,
-    topDay,
-    cheapestDay,
-    busiestWeek: computeBusiestWeek(data),
-    weekendCostShare: weekendEligible > 0 ? (weekendCost / weekendEligible) * 100 : null,
-    weekOverWeekChange: computeWeekOverWeekChange(data),
-    requestVolatility: stdDev(data.map((item) => item.requestCount)),
-    providerCount: providerCosts.size,
-  };
-}
-
 function computeModelRows(data) {
   const rows = new Map();
   for (const day of data) {
@@ -677,6 +221,16 @@ function formatPercent(value, language = 'de') {
   })}%`;
 }
 
+function findPeakEntry(data, getValue) {
+  let best = null;
+  for (const entry of data) {
+    if (!best || getValue(entry) > getValue(best)) {
+      best = entry;
+    }
+  }
+  return best;
+}
+
 function formatCompactNumber(value, language = 'de') {
   if (!Number.isFinite(value)) return '0';
 
@@ -737,12 +291,6 @@ function summarizeSelection(
   return `${visible.join(', ')}${suffix}`;
 }
 
-function truncateLabel(value, maxLength = 28) {
-  const stringValue = String(value || '');
-  if (stringValue.length <= maxLength) return stringValue;
-  return `${stringValue.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
-}
-
 function buildInsights(metrics, { filteredDaily, filtered, language }) {
   const insights = [];
 
@@ -854,6 +402,9 @@ function buildReportData(allDailyData, options = {}) {
   const topProviderValue = metrics.topProvider ? metrics.topProvider.name : notAvailable;
   const insights = buildInsights(metrics, { filteredDaily, filtered, language });
   const avgPeriodCost = filtered.length > 0 ? metrics.totalCost / filtered.length : 0;
+  const latestPeriod = filtered[filtered.length - 1] || null;
+  const peakCostPeriod = findPeakEntry(filtered, (entry) => entry.totalCost);
+  const peakTokenPeriod = findPeakEntry(filtered, (entry) => entry.totalTokens);
   const recentRows = sortByDate(filtered)
     .slice(-12)
     .reverse()
@@ -911,6 +462,34 @@ function buildReportData(allDailyData, options = {}) {
     },
   ];
 
+  const topChartModels = modelRows.slice(0, 8);
+  const truncatedTopModelNames = topChartModels
+    .filter((entry) => truncateTopModelChartLabel(entry.name) !== entry.name)
+    .map((entry) => entry.name);
+  const topModelSummary = metrics.topModel
+    ? translate(language, 'report.charts.topModelsSummary', {
+        model: metrics.topModel.name,
+        cost: formatCurrency(metrics.topModel.cost, language),
+        share: formatPercent(metrics.topModelShare, language),
+      })
+    : translate(language, 'report.charts.noDataSummary');
+  const costTrendSummary =
+    latestPeriod && peakCostPeriod
+      ? translate(language, 'report.charts.costTrendSummary', {
+          latest: formatCurrency(latestPeriod.totalCost, language),
+          peak: formatCurrency(peakCostPeriod.totalCost, language),
+          date: formatDate(peakCostPeriod.date, 'long', language),
+        })
+      : translate(language, 'report.charts.noDataSummary');
+  const tokenTrendSummary =
+    peakTokenPeriod && metrics.totalTokens > 0
+      ? translate(language, 'report.charts.tokenTrendSummary', {
+          total: formatCompact(metrics.totalTokens, language),
+          peak: formatCompact(peakTokenPeriod.totalTokens, language),
+          date: formatDate(peakTokenPeriod.date, 'long', language),
+        })
+      : translate(language, 'report.charts.noDataSummary');
+
   const interpretationSummary = translate(language, 'report.interpretation.summary', {
     days: formatInteger(filteredDaily.length, language),
     periods: formatInteger(filtered.length, language),
@@ -975,6 +554,26 @@ function buildReportData(allDailyData, options = {}) {
       tokensLabel: formatCompact(entry.tokens, language),
     })),
     recentPeriods: recentRows,
+    chartDescriptions: {
+      costTrend: {
+        alt: translate(language, 'report.charts.costTrendAlt'),
+        summary: costTrendSummary,
+      },
+      topModels: {
+        alt: translate(language, 'report.charts.topModelsAlt'),
+        summary: topModelSummary,
+        fullNamesNote:
+          truncatedTopModelNames.length > 0
+            ? translate(language, 'report.charts.topModelsFullNames', {
+                names: truncatedTopModelNames.join(', '),
+              })
+            : null,
+      },
+      tokenTrend: {
+        alt: translate(language, 'report.charts.tokenTrendAlt'),
+        summary: tokenTrendSummary,
+      },
+    },
     labels: {
       dateRangeText: dateRange
         ? `${formatDate(dateRange.start, 'long', language)} - ${formatDate(dateRange.end, 'long', language)}`
@@ -1063,7 +662,6 @@ module.exports = {
   formatDate,
   formatDateAxis,
   getModelColor,
-  truncateLabel,
   __test__: {
     getModelProvider,
     normalizeModelName,

package/server/runtime.js

@@ -0,0 +1,78 @@
+function isLoopbackHost(host) {
+  const normalized = String(host || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '');
+  const ipv4Loopback = /^127(?:\.\d{1,3}){3}$/.test(normalized);
+  const ipv4MappedLoopback = /^::ffff:127(?:\.\d{1,3}){3}$/.test(normalized);
+  return ipv4Loopback || normalized === 'localhost' || normalized === '::1' || ipv4MappedLoopback;
+}
+
+function ensureBindHostAllowed(bindHost, allowRemoteBind) {
+  if (isLoopbackHost(bindHost) || allowRemoteBind) {
+    return;
+  }
+
+  const error = new Error(
+    `Refusing to bind TTDash to non-loopback host "${bindHost}" without TTDASH_ALLOW_REMOTE=1.`,
+  );
+  error.code = 'REMOTE_BIND_REQUIRES_OPT_IN';
+  throw error;
+}
+
+function createNoFreePortError(rangeStartPort, maxPort) {
+  return new Error(`No free port found (${rangeStartPort}-${maxPort})`);
+}
+
+async function listenOnAvailablePort(
+  serverInstance,
+  port,
+  maxPort,
+  bindHost,
+  log = console.log,
+  rangeStartPort = port,
+) {
+  if (port > maxPort) {
+    throw createNoFreePortError(rangeStartPort, maxPort);
+  }
+
+  for (let currentPort = port; currentPort <= maxPort; currentPort += 1) {
+    try {
+      await new Promise((resolve, reject) => {
+        const onError = (error) => {
+          serverInstance.off('listening', onListening);
+          reject(error);
+        };
+
+        const onListening = () => {
+          serverInstance.off('error', onError);
+          resolve();
+        };
+
+        serverInstance.once('error', onError);
+        serverInstance.once('listening', onListening);
+        serverInstance.listen(currentPort, bindHost);
+      });
+
+      return currentPort;
+    } catch (error) {
+      if (error && error.code === 'EADDRINUSE') {
+        if (currentPort >= maxPort) {
+          throw createNoFreePortError(rangeStartPort, maxPort);
+        }
+        log(`Port ${currentPort} is in use, trying ${currentPort + 1}...`);
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw createNoFreePortError(rangeStartPort, maxPort);
+}
+
+module.exports = {
+  createNoFreePortError,
+  ensureBindHostAllowed,
+  isLoopbackHost,
+  listenOnAvailablePort,
+};