wendkeep 0.68.6 → 0.70.0

package/packages/vault/src/validate-memory.mjs

@@ -1,6 +1,7 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { validateMemoryEvent, validateSharedMemory } from './memory-schema.mjs';
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { sanitizeMemoryText, validateMemoryEvent, validateSharedMemory } from './memory-schema.mjs';
+import { deriveMemoryProjection } from './memory-store.mjs';
 import { assertVaultPathSafe } from './vault-path-safety.mjs';
 import { validateCore } from './validate-core.mjs';
 
@@ -104,8 +105,208 @@ function validateSharedArtifact(vaultBase, eventIds) {
   return { ...validateSharedMemory(read.content, { eventIds }), path, content: read.content };
 }
 
-export function combineMemoryResults({ project, core, ledger, shared }) {
-  const components = { project, core, ledger, shared };
+const TERMINAL_CANDIDATE_STATUSES = new Set(['resolved', 'rejected', 'superseded']);
+const DECISION_LINK_RE = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+
+function readCandidateInventory(vaultBase) {
+  const path = join(vaultBase, '.brain', 'MEMORY_CANDIDATES.jsonl');
+  let checked;
+  try {
+    checked = assertVaultPathSafe(vaultBase, path, {
+      allowMissing: true, expectedType: 'file', label: 'MEMORY_CANDIDATES.jsonl',
+    });
+  } catch (error) {
+    return failedComponent(`MEMORY_CANDIDATES.jsonl inseguro: ${error?.message || error}`, {
+      count: 0, activeCount: 0, path,
+    });
+  }
+  if (!checked.exists) return { ok: true, errors: [], warnings: [], count: 0, activeCount: 0, path };
+
+  try {
+    checked = assertVaultPathSafe(vaultBase, checked.target, {
+      allowMissing: false, expectedType: 'file', label: 'MEMORY_CANDIDATES.jsonl',
+    });
+    const lines = readFileSync(checked.target, 'utf8').replace(/\r\n/g, '\n')
+      .split('\n').filter((line) => line.trim());
+    const errors = [];
+    let count = 0;
+    let activeCount = 0;
+    for (const [index, line] of lines.entries()) {
+      try {
+        const item = JSON.parse(line);
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+          errors.push(`MEMORY_CANDIDATES.jsonl linha ${index + 1} deve conter um objeto.`);
+          continue;
+        }
+        count += 1;
+        if (!TERMINAL_CANDIDATE_STATUSES.has(item.status || 'active')) activeCount += 1;
+      } catch (error) {
+        errors.push(`MEMORY_CANDIDATES.jsonl linha ${index + 1} contém JSON inválido: ${error?.message || error}`);
+      }
+    }
+    return { ok: errors.length === 0, errors, warnings: [], count, activeCount, path };
+  } catch (error) {
+    return failedComponent(`MEMORY_CANDIDATES.jsonl ilegível: ${error?.message || error}`, {
+      count: 0, activeCount: 0, path,
+    });
+  }
+}
+
+function sharedEventIds(content) {
+  const ids = new Set();
+  for (const line of String(content || '').split('\n')) {
+    const match = line.match(/^\s*-\s+\[([^\]]+)\]/);
+    if (match?.[1]) ids.add(match[1]);
+  }
+  return ids;
+}
+
+function walkDecisionFiles(root, vaultBase, output = []) {
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return output; }
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) walkDecisionFiles(path, vaultBase, output);
+    else if (entry.isFile() && /^ADR-\d+.*\.md$/i.test(entry.name)) {
+      const rel = relative(vaultBase, path).replace(/\\/g, '/').replace(/\.md$/i, '');
+      output.push(rel);
+    }
+  }
+  return output;
+}
+
+function decisionInventory(vaultBase) {
+  const paths = [];
+  for (const folder of ['04-Decisões', '04-Decisions']) {
+    walkDecisionFiles(join(vaultBase, folder), vaultBase, paths);
+  }
+  const byPath = new Set(paths);
+  const byBasename = new Set(paths.map((path) => basename(path)));
+  return { byPath, byBasename };
+}
+
+function unresolvedDecisionLinks(vaultBase, content) {
+  const inventory = decisionInventory(vaultBase);
+  const unresolved = new Set();
+  DECISION_LINK_RE.lastIndex = 0;
+  let match;
+  while ((match = DECISION_LINK_RE.exec(String(content || '')))) {
+    const target = String(match[1] || '').trim().replace(/\\/g, '/').replace(/\.md$/i, '');
+    const targetBase = basename(target);
+    const isDecision = /^ADR-\d+/i.test(targetBase)
+      || /(^|\/)(?:04-Decis(?:õ|o)es|04-Decisions)(?:\/|$)/i.test(target);
+    if (!isDecision) continue;
+    if (!target || target.includes('...') || target.includes('…')
+        || (!inventory.byPath.has(target) && !inventory.byBasename.has(targetBase))) {
+      unresolved.add(sanitizeMemoryText(target).slice(0, 180));
+    }
+  }
+  return [...unresolved].sort();
+}
+
+function semanticMemoryHealth(vaultBase, { ledger, shared, candidates }) {
+  const base = {
+    ok: true,
+    status: 'unavailable',
+    code: 'MEMORY_SEMANTIC_STRUCTURAL_UNAVAILABLE',
+    errors: [],
+    warnings: [],
+    activeKeys: [],
+    projectedKeys: [],
+    missingKeys: [],
+    unresolvedDecisionLinks: [],
+    placeholderOnly: false,
+    counts: { activeKeys: 0, projectedKeys: 0, missingKeys: 0, candidates: candidates?.activeCount || 0, placeholderSections: 0, unresolvedDecisionLinks: 0 },
+  };
+  if (!ledger?.ok || !shared?.ok) return base;
+
+  let replay;
+  try { replay = deriveMemoryProjection(vaultBase, ledger.events); }
+  catch (error) {
+    return {
+      ...base,
+      ok: false,
+      status: 'degraded',
+      code: 'MEMORY_SEMANTIC_REPLAY_UNAVAILABLE',
+      errors: ['[MEMORY_SEMANTIC_REPLAY_UNAVAILABLE] não foi possível rederivar as chaves ativas do ledger.'],
+    };
+  }
+
+  const active = Object.entries(replay.records || {}).map(([memoryKey, record]) => ({
+    memoryKey: sanitizeMemoryText(memoryKey),
+    eventId: record?.source?.event_id,
+  }));
+  const activeKeys = active.map(({ memoryKey }) => memoryKey).sort();
+  const projectedIds = sharedEventIds(shared.content);
+  const projectedKeys = active
+    .filter(({ eventId }) => projectedIds.has(eventId))
+    .map(({ memoryKey }) => memoryKey)
+    .sort();
+  const missingKeys = active
+    .filter(({ eventId }) => !projectedIds.has(eventId))
+    .map(({ memoryKey }) => memoryKey)
+    .sort();
+  const sectionValues = [...(shared.sections?.values?.() || [])].flat();
+  const placeholderSections = sectionValues.filter((line) => /^-\s*\(vazio\)\s*$/i.test(line)).length;
+  const nonPlaceholderLines = sectionValues.filter((line) => !/^-\s*\(vazio\)\s*$/i.test(line));
+  const placeholderOnly = sectionValues.length > 0 && nonPlaceholderLines.length === 0;
+  const unresolvedLinks = unresolvedDecisionLinks(vaultBase, shared.content);
+  const candidateCount = Math.max(candidates?.activeCount || 0, replay.candidates?.length || 0);
+  const errors = [];
+  const warnings = [];
+  const codes = [];
+
+  if (missingKeys.length && placeholderOnly) {
+    codes.push('MEMORY_SEMANTIC_PLACEHOLDER_ONLY');
+    errors.push(`[MEMORY_SEMANTIC_PLACEHOLDER_ONLY] SHARED contém somente placeholders para ${activeKeys.length} chave(s) ativa(s); candidates=${candidateCount}.`);
+  } else if (missingKeys.length) {
+    codes.push('MEMORY_SEMANTIC_COVERAGE_MISSING');
+    errors.push(`[MEMORY_SEMANTIC_COVERAGE_MISSING] SHARED não cobre ${missingKeys.length} chave(s) ativa(s): ${missingKeys.join(', ')}.`);
+  }
+  if (unresolvedLinks.length) {
+    codes.push('MEMORY_SEMANTIC_DECISION_LINK_UNRESOLVED');
+    errors.push(`[MEMORY_SEMANTIC_DECISION_LINK_UNRESOLVED] ${unresolvedLinks.length} link(s) de decisão não resolvido(s).`);
+  }
+
+  let status = 'healthy';
+  let code = 'MEMORY_SEMANTIC_COVERAGE_OK';
+  if (!ledger.events.length && !candidateCount) {
+    status = 'neutral';
+    code = 'MEMORY_SEMANTIC_EMPTY_NEUTRAL';
+  } else if (!activeKeys.length && candidateCount) {
+    status = 'degraded';
+    code = 'MEMORY_SEMANTIC_CANDIDATES_PENDING';
+    warnings.push(`[MEMORY_SEMANTIC_CANDIDATES_PENDING] ${candidateCount} candidate(s) preservado(s); o estado não é memória vazia.`);
+  } else if (codes.length) {
+    status = 'degraded';
+    code = codes[0];
+  }
+
+  return {
+    ok: errors.length === 0,
+    status,
+    code,
+    codes,
+    errors,
+    warnings,
+    activeKeys,
+    projectedKeys,
+    missingKeys,
+    unresolvedDecisionLinks: unresolvedLinks,
+    placeholderOnly,
+    counts: {
+      activeKeys: activeKeys.length,
+      projectedKeys: projectedKeys.length,
+      missingKeys: missingKeys.length,
+      candidates: candidateCount,
+      placeholderSections,
+      unresolvedDecisionLinks: unresolvedLinks.length,
+    },
+  };
+}
+
+export function combineMemoryResults({ project, core, ledger, shared, candidates, semantic }) {
+  const components = { project, core, ledger, shared, candidates, semantic };
   const errors = [];
   const warnings = [];
   for (const [name, result] of Object.entries(components)) {
@@ -124,5 +325,7 @@ export function validateMemoryBundle(vaultBase) {
   const core = validateCoreArtifact(vaultBase);
   const ledger = readLedgerForValidation(vaultBase, { projectId: project.projectId });
   const shared = validateSharedArtifact(vaultBase, ledger.eventIds);
-  return combineMemoryResults({ project, core, ledger, shared });
+  const candidates = readCandidateInventory(vaultBase);
+  const semantic = semanticMemoryHealth(vaultBase, { ledger, shared, candidates });
+  return combineMemoryResults({ project, core, ledger, shared, candidates, semantic });
 }

package/src/doctor.mjs

@@ -39,6 +39,10 @@ export function renderVaultHealthLines(result) {
     `[memória] ${healthStatusLabel(result.memoryStatus)} — schema: ${metricValue(memory.schemaVersion)} · revisão: ${metricValue(memory.revision)} · cursor: ${metricValue(memory.eventCursor)} · hash: ${metricValue(memory.stateHash)}`,
   );
   lines.push(`  ledger: ${metricValue(memory.ledgerEvents)} evento(s) · outbox: ${metricValue(memory.pendingOutbox)} · candidates: ${metricValue(memory.candidates)} · conflitos: ${metricValue(memory.activeConflicts)}`);
+  const semanticKeys = memory.semanticActiveKeys || [];
+  const semanticProjected = memory.semanticProjectedKeys || [];
+  const semanticMissing = memory.semanticMissingKeys || [];
+  lines.push(`  semântica: ${metricValue(memory.semanticCode)} · ativas: ${semanticKeys.length} [${semanticKeys.join(', ')}] · projetadas: ${semanticProjected.length} · ausentes: ${semanticMissing.length}`);
   for (const failure of memoryFailures) lines.push(`  ✗ ${failure}`);
   for (const warning of memoryWarnings) lines.push(`  ! ${warning}`);
   if (result.memoryStatus === 'healthy' && !memoryFailures.length && !memoryWarnings.length) {

package/src/memory.mjs

@@ -1874,13 +1874,16 @@ export function runValidateMemoryBundle(argv) {
     return;
   }
   const result = validateMemoryBundle(vault);
+  const semantic = result.semantic || {};
+  const semanticSummary = `semântica ${semantic.code || 'n/a'} · ativas: ${semantic.counts?.activeKeys ?? 0} · projetadas: ${semantic.counts?.projectedKeys ?? 0} · ausentes: ${semantic.counts?.missingKeys ?? 0}`;
   if (!result.ok) {
     process.stderr.write(`❌  bundle de memória inválido (${result.errors.length} erro(s)):\n`);
+    process.stderr.write(`   ${semanticSummary}\n`);
     for (const error of result.errors) process.stderr.write(`   - ${error}\n`);
     process.exitCode = 1;
     return;
   }
-  process.stdout.write('✅  bundle de memória v2 OK (CORE + ledger + SHARED).\n');
+  process.stdout.write(`✅  bundle de memória v2 OK (CORE + ledger + SHARED; ${semanticSummary}).\n`);
   process.exitCode = 0;
 }
 

package/src/observer-publish.mjs

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildProjectSnapshot } from './observer-snapshot.mjs';
+
+const OUTBOX_REL = join('.brain', 'observer-outbox');
+const REQUEST_TIMEOUT_MS = 500;
+
+function outboxDir(vaultBase) {
+  return join(vaultBase, OUTBOX_REL);
+}
+
+function eventPath(vaultBase, eventId) {
+  if (!/^obs-[a-f0-9]{24}$/.test(eventId)) throw new Error('event_id inválido para outbox.');
+  return join(outboxDir(vaultBase), `${eventId}.json`);
+}
+
+function atomicWrite(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(value)}\n`, 'utf8');
+  renameSync(temp, path);
+}
+
+export function listOutbox(vaultBase) {
+  const dir = outboxDir(vaultBase);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => /^obs-[a-f0-9]{24}\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      try { return [JSON.parse(readFileSync(join(dir, name), 'utf8'))]; }
+      catch { return []; }
+    });
+}
+
+function queueOutbox(vaultBase, event) {
+  const dir = outboxDir(vaultBase);
+  mkdirSync(dir, { recursive: true });
+  const path = eventPath(vaultBase, event.event_id);
+  if (!existsSync(path)) atomicWrite(path, event);
+  return path;
+}
+
+function removeOutbox(vaultBase, eventId) {
+  const path = eventPath(vaultBase, eventId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+async function postSnapshot(url, token, event) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${String(url).replace(/\/$/, '')}/v1/projects/${encodeURIComponent(event.project_id)}/snapshot`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let body = {};
+    try { body = JSON.parse(text); } catch { /* server error remains deterministic below */ }
+    if (!response.ok || !(body.accepted === true || body.duplicate === true)) {
+      throw new Error(`Observer respondeu HTTP ${response.status}.`);
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function retryObserverOutbox({ vaultBase, url, token } = {}) {
+  if (!url || !token) return { attempted: 0, confirmed: 0, pending: listOutbox(vaultBase).length };
+  let attempted = 0;
+  let confirmed = 0;
+  for (const event of listOutbox(vaultBase)) {
+    attempted += 1;
+    try {
+      await postSnapshot(url, token, event);
+      removeOutbox(vaultBase, event.event_id);
+      confirmed += 1;
+    } catch { /* preserve the event for a later retry */ }
+  }
+  return { attempted, confirmed, pending: listOutbox(vaultBase).length };
+}
+
+export async function publishObserverSnapshot({
+  vaultBase,
+  projectRoot,
+  url = process.env.WENDKEEP_OBSERVER_URL || '',
+  token = process.env.WENDKEEP_OBSERVER_TOKEN || '',
+  now = new Date(),
+} = {}) {
+  try {
+    const event = buildProjectSnapshot({ vaultBase, projectRoot, now });
+    if (!url) return { ok: true, skipped: true, queued: false, hookExitCode: 0, event_id: event.event_id };
+
+    await retryObserverOutbox({ vaultBase, url, token });
+    try {
+      const response = await postSnapshot(url, token, event);
+      return {
+        ok: true,
+        queued: false,
+        hookExitCode: 0,
+        event_id: event.event_id,
+        duplicate: response.duplicate === true,
+      };
+    } catch (error) {
+      queueOutbox(vaultBase, event);
+      return {
+        ok: false,
+        queued: true,
+        hookExitCode: 0,
+        event_id: event.event_id,
+        error: error.message,
+      };
+    }
+  } catch (error) {
+    return { ok: false, queued: false, hookExitCode: 0, error: error.message };
+  }
+}

package/src/observer-server.mjs

@@ -0,0 +1,203 @@
+import { createServer } from 'node:http';
+import { appendObserverEvent, getObserverProject, readObserverIndex, registerObserverProject } from './observer-store.mjs';
+import { MAX_SNAPSHOT_BYTES, validateObserverSnapshot } from './observer-snapshot.mjs';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+const MAX_BODY_BYTES = MAX_SNAPSHOT_BYTES + 4096;
+
+function loopbackOnly(host) {
+  return LOOPBACK_HOSTS.has(String(host || '').toLowerCase());
+}
+
+function json(res, status, body) {
+  const content = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(content),
+  });
+  res.end(content);
+}
+
+function errorResponse(res, status, code, message) {
+  json(res, status, { error: { code, message } });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    let tooLarge = false;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      if (tooLarge) return;
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        tooLarge = true;
+        const error = new Error('corpo acima do limite.');
+        error.code = 'payload_too_large';
+        reject(error);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!tooLarge) resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    req.on('error', reject);
+  });
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text || '{}'); }
+  catch {
+    const error = new Error('JSON inválido.');
+    error.code = 'invalid_json';
+    throw error;
+  }
+}
+
+function authorized(req, token) {
+  if (!token) return false;
+  const header = String(req.headers.authorization || '');
+  return header === `Bearer ${token}`
+    || req.headers['x-wendkeep-observer-token'] === token;
+}
+
+function pathParts(url) {
+  return new URL(url, 'http://127.0.0.1').pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
+}
+
+function projectIdFrom(parts) {
+  return parts[0] === 'v1' && parts[1] === 'projects' && parts[2] ? parts[2] : '';
+}
+
+export async function startObserverServer({
+  host = '127.0.0.1',
+  port = 8787,
+  dataDir,
+  token = process.env.WENDKEEP_OBSERVER_TOKEN || '',
+  allowNonLoopback = false,
+} = {}) {
+  if (!loopbackOnly(host) && !allowNonLoopback) {
+    throw new Error(`Observer HTTP aceita somente host loopback; recebido: ${host}`);
+  }
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  const server = createServer(async (req, res) => {
+    try {
+      const parts = pathParts(req.url || '/');
+      if (req.method === 'GET' && parts.length === 1 && parts[0] === 'healthz') {
+        json(res, 200, { ok: true, service: 'wendkeep-observer', schema_version: 1 });
+        return;
+      }
+      if (!authorized(req, token)) {
+        errorResponse(res, 401, 'unauthorized', 'token local ausente ou inválido.');
+        return;
+      }
+      if (parts[0] !== 'v1' || parts[1] !== 'projects') {
+        errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+        return;
+      }
+
+      if (parts.length === 2 && req.method === 'GET') {
+        const index = readObserverIndex(dataDir);
+        json(res, 200, {
+          schema_version: index.schema_version,
+          projects: index.projects.map(({ snapshot, ...summary }) => summary),
+        });
+        return;
+      }
+
+      const projectId = projectIdFrom(parts);
+      if (!projectId) {
+        errorResponse(res, 404, 'not_found', 'projeto não informado.');
+        return;
+      }
+
+      if (parts.length === 3 && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, project);
+        return;
+      }
+
+      if (parts.length === 3 && req.method === 'PUT') {
+        const body = parseJson(await readBody(req));
+        if (body.project_id !== projectId) {
+          errorResponse(res, 400, 'project_mismatch', 'project_id do corpo não corresponde à rota.');
+          return;
+        }
+        const result = registerObserverProject(dataDir, {
+          projectId,
+          projectName: body.project_name,
+          wendkeepVersion: body.wendkeep_version,
+        });
+        if (!result.registered) {
+          errorResponse(res, 400, 'invalid_project', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, result.project);
+        return;
+      }
+
+      if (parts.length === 4 && parts[3] === 'changes' && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, { project_id: projectId, changes: project.snapshot?.changes || [] });
+        return;
+      }
+
+      if (parts.length === 4 && ['snapshot', 'snapshots'].includes(parts[3]) && req.method === 'POST') {
+        const body = parseJson(await readBody(req));
+        const validation = validateObserverSnapshot(body, { projectId });
+        if (!validation.ok) {
+          errorResponse(res, 400, 'invalid_snapshot', validation.errors.join(' '));
+          return;
+        }
+        const result = appendObserverEvent(dataDir, body);
+        if (!result.accepted && result.duplicate) {
+          json(res, 200, { accepted: false, duplicate: true, event_id: body.event_id });
+          return;
+        }
+        if (!result.accepted) {
+          const unregistered = result.errors.some((item) => /não registrado/.test(item));
+          errorResponse(res, unregistered ? 409 : 400, unregistered ? 'project_not_registered' : 'invalid_event', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, { accepted: true, duplicate: false, event_id: body.event_id });
+        return;
+      }
+
+      errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+    } catch (error) {
+      if (res.headersSent) return;
+      const status = error?.code === 'payload_too_large' ? 413 : error?.code === 'invalid_json' ? 400 : 500;
+      errorResponse(res, status, error?.code || 'observer_error', error?.message || 'erro interno do Observer.');
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(Number(port), host);
+  });
+
+  return {
+    server,
+    address: () => server.address(),
+    close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+  };
+}