@besales/mcp 0.46.0 → 0.47.0

package/docs/task-state.md

@@ -0,0 +1,58 @@
+# Состояние длительной задачи
+
+## Решение
+
+Состоянием владеет локальный `besales-mcp`. Оно хранится в
+`~/.besales-mcp/tasks-v1.json` с правами `0600`; каталог создаётся с `0700`.
+Claude Desktop, Claude Code и Codex на одной машине и под одним OS-аккаунтом видят один набор
+задач. Между компьютерами файл автоматически не переносится. API Besales не получает это
+состояние, а перенос между аккаунтами не поддерживается.
+
+Для изолированных проверок путь можно переопределить через
+`BESALES_MCP_TASK_STATE_PATH`. В обычной установке переменная не нужна.
+
+## Контракт
+
+Каждая задача имеет `task_id`, `workspace_id`, статус, `version`, время создания/изменения и
+истечения. Payload ограничен целью, кратким контекстом, согласованными ограничениями, ссылками на
+объекты, checkpoints, ожидающими операциями и следующим действием человека. Credentials,
+browser setup state и исходные диалоги сюда не сохраняются.
+
+Статусы:
+
+- `ACTIVE` — можно продолжать и обновлять;
+- `COMPLETED` — работа закрыта;
+- `CANCELLED` — продолжение запрещено;
+- `EXPIRED` — TTL истёк, продолжение запрещено.
+
+По умолчанию задача живёт 30 дней, допустимо 1–180. Истёкшая задача остаётся видимой до явного
+удаления, чтобы причина остановки не исчезала.
+
+## Инструменты
+
+1. `besales_task_create` возвращает `task_id` и `version=1`.
+2. `besales_task_list` показывает только выбранный workspace. При нескольких результатах задача
+   выбирается человеком явно; «самая свежая» не становится текущей автоматически.
+3. `besales_task_get` читает полный сохранённый payload.
+4. `besales_task_update` требует `expected_version`. Конфликт возвращает
+   `TASK_VERSION_CONFLICT`; сначала надо перечитать задачу и согласовать изменения.
+5. `besales_task_close` переводит ACTIVE в COMPLETED/CANCELLED.
+6. `besales_task_delete` удаляет только локальную запись и требует точную версию плюс
+   `explicit_confirmation=true`.
+
+Запись сериализуется межпроцессной файловой блокировкой и атомарным rename. Поэтому две MCP-сессии
+не могут одновременно принять одну старую версию. Stale lock старше 10 секунд подбирается; обычное
+ожидание ограничено двумя секундами.
+
+## Возобновление
+
+Сохранённое состояние — контекст, а не доказательство. После `besales_task_get` сначала вызови
+`besales_workspace_current`, затем перечитай каждый объект из `object_refs` и status каждой
+`pending_operation`. Только после этого обновляй checkpoints или выполняй новую мутацию.
+
+Для `OUTCOME_UNKNOWN` используй сохранённые `idempotency_key`, `object_ref` и `verify_with`.
+Автоматический повтор мутации запрещён. Если status-tool или нужный scope недоступен, исход остаётся
+неразрешённым и это фиксируется в задаче.
+
+Setup URL, OAuth ticket и состояние отдельного async job остаются своими сущностями. Они не
+заменяют общую задачу и не копируются в неё вместе с секретами.

package/docs/tool-effects.md

@@ -0,0 +1,46 @@
+# Эффекты и аннотации инструментов
+
+## Источник истины
+
+Каждое определение в `src/tools/definitions/` обязано явно задать `sideEffect`:
+
+- `none` — только чтение и локальные вычисления без изменения состояния;
+- `write` — изменение состояния Besales, внешней CRM или локальной MCP-сессии;
+- `spend` — операция может отправить сообщение, вызвать модель, индексацию или потратить квоту.
+
+На 11 сентября 2026 года активный каталог из 231 инструмента содержит 96 `none`, 116 `write`
+и 19 `spend`. Эти числа проверяются по живым definitions, а не поддерживаются отдельным списком.
+
+HTTP-метод не является источником эффекта. Например, `besales_prompt_diff`,
+`besales_prompt_lint` и `besales_knowledge_qa_search` читают через POST. В то же время
+`besales_crm_operator_list`, `besales_crm_pipeline_list` и `besales_datasource_health` делают
+запись при GET. Операции `*_get_instructions` создают долговечную запись внешней операции.
+
+## MCP-аннотации
+
+`src/tools/annotations.ts` переводит эффект и дополнительные доказанные свойства определения
+в четыре стандартные подсказки MCP:
+
+- `readOnlyHint=true` только для `sideEffect=none`;
+- `destructiveHint=false` для чтения и доказуемо обратимых записей;
+- `idempotentHint=true` только при безусловной идемпотентности с теми же аргументами;
+- `openWorldHint=false` только если операция гарантированно не выходит за Besales.
+
+Неизвестное свойство трактуется консервативно. Аннотации помогают хосту показать характер
+операции, но не заменяют API scopes, tenant/workspace проверки и обязательный
+`explicit_confirmation` у опасных действий.
+
+`explicit_confirmation` является гейтом самого MCP и не передаётся в API DTO, если endpoint
+его не принимает. Опубликованная JSON Schema использует `const: true`, а runtime-схема —
+`z.literal(true)`: вызывающий видит ровно то условие, которое затем проверяется.
+
+Поле `Tool.title` строится из первой русской фразы локализованного описания, ограничено 80
+символами и передаётся через `tools/list`. Это подпись для интерфейса; стабильным API-ключом
+операции остаётся `name`.
+
+## Проверка
+
+`src/tools/annotations.spec.ts` требует эффект у каждого определения, полный набор четырёх
+аннотаций в `tools/list`, фиксирует POST-чтения и GET-записи, а также запрещает объявлять
+удаление обратимым или тратящую операцию безусловно идемпотентной.
+`src/tools/description-localization.spec.ts` дополнительно проверяет русский `title` и его длину.

package/docs/tool-surface.md

@@ -0,0 +1,91 @@
+# Поверхность инструментов: группы, а не укрупнение
+
+## Решение
+
+**Инструменты не укрупняются. Их число не сокращается. Появляются профили — набор имён,
+которым сессия ограничивает себя сама.**
+
+Развилка стояла так: либо схлопнуть родственные инструменты в один с аргументом-действием
+(двенадцать инструментов знаний → один `knowledge` с полем `action`), либо оставить состав
+как есть и дать сессии выбирать группы.
+
+Укрупнение отвергнуто по трём причинам, и первая из них решающая:
+
+1. **Оно уничтожает признак «только чтение».** У каждого инструмента объявлен `sideEffect`, из
+   которого выводятся четыре подсказки хосту. Слитый инструмент и читает, и удаляет — значит он
+   разрушительный ВСЕГДА, и хост больше никогда не сможет считать безопасной ни одну его ветку.
+   Работа по аннотациям была бы обесценена ровно в тот момент, когда она начала приносить пользу.
+2. **Имена — это контракт отгруженной линии.** Пакет стоит у пользователей и вызывается по
+   именам; переименование требует совместимого выпуска и синхронной правки инструкций,
+   ресурсов, скиллов и README.
+3. **Слитый инструмент хуже выбирается моделью.** Вместо ста имён с собственными схемами
+   появляется десяток имён с перечислением действий, где ошибка в поле `action` неотличима от
+   ошибки в аргументах, а схема каждого «действия» вырождается в необязательные поля.
+
+Профили решают ту задачу, ради которой укрупнение и предлагалось — **вес и досягаемость**, — и
+не платят ничем из перечисленного.
+
+## Как это работает
+
+Объявление — переменная окружения `BESALES_MCP_TOOLSETS`, перечисление через запятую.
+
+```
+BESALES_MCP_TOOLSETS=readonly            # аудит: ни один меняющий инструмент недоступен
+BESALES_MCP_TOOLSETS=knowledge,crm       # только база знаний и CRM
+BESALES_MCP_TOOLSETS=readonly,knowledge  # профили складываются
+```
+
+- **Умолчание — вся поверхность.** Пустое или отсутствующее объявление НЕ сужает ничего: молча
+  урезать доступ настройкой, которую забыли задать, нельзя.
+- **Доменная группа выводится из имени** (`besales_<группа>_…`), рукописного реестра нет. Реестр
+  пришлось бы пополнять при каждом добавлении, и забытая строка тихо выкидывала бы новый
+  инструмент из всех профилей — он просто перестал бы существовать для тех, кто выбрал группу.
+- **`readonly` — не группа, а срез**: состав выводится из уже объявленного `sideEffect === 'none'`.
+- **Отбор действует и на перечисление, и на вызов.** Профиль, который только прячет, — декорация:
+  хост, знающий имя, всё равно позовёт скрытое, а ровно от такого вызова профиль и заводится.
+  Отбор идёт до сборки набора, поэтому у перечисления и у вызова он один по построению.
+- **Опечатка — громкий отказ** с перечнем доступных имён. Иначе `knowlege` дал бы пустую
+  поверхность, и это выглядело бы поломкой моста, а не опиской в настройке.
+- `besales_help_search` ранжирует только вызываемые в текущем профиле операции. Совпадения,
+  скрытые профилем, приходят отдельно в `profile.hiddenOperationMatches` вместе с точным способом
+  перезапуска; модель не получает мёртвое имя как исполнимый следующий шаг.
+- Server instructions запрещают повторять успешное полное чтение с теми же аргументами. Повтор
+  оправдан после мутации, для следующей страницы/курсора, при новом фильтре или когда ответ явно
+  помечен неполным; иначе модель использует уже полученный снимок.
+- Для аналитики, follow-up и проверки границы покрытия discovery начинается со справки: в этих
+  областях соседние метрики и инструменты похожи по названию, но отвечают на разные вопросы.
+
+## Чем это отличается от аннотаций
+
+Аннотация — **подсказка**: автоодобряющий хост вправе ей не поверить, и сессия аудита
+по-прежнему ВИДИТ и может ПОЗВАТЬ около сотни меняющих инструментов. Профиль — **запрет**:
+инструмента вне профиля для сессии не существует. Слои дополняют друг друга и не заменяют:
+аннотации помогают хосту решать, профиль — не даёт ошибиться.
+
+---
+
+# Составной инструмент правки промпта: строить не нужно
+
+Предполагалось завести `besales_prompt_edit`, который сам проходит цепочку
+«создать черновик → применить правки → закоммитить», потому что мост умеет один запрос на
+вызов, а нужно три. Развилка формулировалась как «выносливый метод на сервере против нового
+типа обработчика в мосту».
+
+**Ни то, ни другое: нужный метод на сервере уже есть.** Пакетная раскатка
+(`besales_prompt_batch_start`) — это ровно та же цепочка, только по списку агентов, и список из
+одного агента ничем не хуже. Она даёт всё, чего требовала постановка:
+
+- **Отказ при непопавших якорях.** Режим «всё или ничего» не коммитит никого, если хоть один
+  агент не прошёл подготовку; причина пропуска приходит структурным кодом
+  (`NO_OPERATIONS_APPLIED`, `PROMPT_UNCHANGED`, `DRAFT_CONFLICT_OTHER_USER`, …), а не строкой,
+  которую надо разбирать.
+- **Безопасный повтор.** Ключ идемпотентности возвращает тот же прогон, а не применяет правки
+  к уже пропатченному тексту — именно та ошибка, ради которой у очереди одна попытка.
+- **Долговечность.** Прогон живёт в базе; падение на любом шаге оставляет читаемое состояние,
+  тогда как обработчик в мосту хранил бы состояние в процессе, умирающем вместе с сессией.
+
+Что остаётся неизменным: **сначала прочитать промпт целиком** (`besales_prompt_patch_get`), иначе
+неоткуда взять точные якоря. Это не обходится ни одним из вариантов.
+
+Итог: правильное количество кода здесь — ноль. Работа сводится к тому, чтобы описание
+`besales_prompt_batch_start` называло одиночный случай явно.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/mcp",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Model Context Protocol server for Animaly / Besales",
   "license": "MIT",
   "homepage": "https://github.com/be-sales/mcp#readme",
@@ -37,6 +37,7 @@
     "bin",
     "scripts",
     "docs",
+    "!docs/evidence",
     "README.md"
   ],
   "bin": {
@@ -48,6 +49,9 @@
     "dev:mock": "node scripts/mock-api-server.js",
     "dev:mock:seed": "node scripts/mock-credentials.js seed",
     "dev:mock:clear": "node scripts/mock-credentials.js clear",
+    "host:probe": "node scripts/probe-mcp-protocol.js",
+    "model:eval:server": "node scripts/model-eval-server.js",
+    "model:eval": "node scripts/run-model-eval.js",
     "install:claude-desktop": "node scripts/install-claude-desktop.js",
     "prepack": "yarn build",
     "prepublishOnly": "yarn lint:errors && yarn test && yarn build",
@@ -55,7 +59,7 @@
     "lint:fix": "eslint src bin scripts eslint.config.js --fix",
     "lint:errors": "eslint src bin scripts eslint.config.js",
     "types:gen:api": "mkdir -p src/types && openapi-typescript ../docs/specs/v2/contracts/openapi-besales-api.yaml -o src/types/api-contract.gen.ts",
-    "types:gen:mcp": "mkdir -p src/schemas && cp ../docs/specs/v2/contracts/mcp-tools.json src/schemas/mcp-tools.json"
+    "types:check:mcp": "node -e \"const s=require('./src/schemas/mcp-tools.json');if(s.summary.total_tools!==s.tools.length)process.exit(1)\""
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/model-eval-server.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+import { appendFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const buildRoot = resolve(
+  process.env.BESALES_MCP_EVAL_BUILD ?? resolve(scriptDirectory, '../dist'),
+);
+const logPath = process.env.BESALES_MCP_EVAL_LOG
+  ? resolve(process.env.BESALES_MCP_EVAL_LOG)
+  : null;
+
+const { startMcpServer } = await import(pathToFileURL(resolve(buildRoot, 'server.js')).href);
+const { tools } = await import(pathToFileURL(resolve(buildRoot, 'tools/registry.js')).href);
+const { toolDefinitions } = await import(
+  pathToFileURL(resolve(buildRoot, 'tools/definitions.js')).href
+);
+const { helpTools = [] } = await import(
+  pathToFileURL(resolve(buildRoot, 'tools/definitions/help.js')).href
+).catch(() => ({ helpTools: [] }));
+const helpHandlers = new Map(
+  helpTools
+    .filter((tool) => typeof tool.localHandler === 'function')
+    .map((tool) => [tool.name, tool.localHandler]),
+);
+const sideEffects = new Map(
+  toolDefinitions.map((definition) => [definition.name, definition.sideEffect ?? 'unknown']),
+);
+
+const fixtureTools = tools.map((tool) => ({
+  ...tool,
+  async handler(args) {
+    const mutating = sideEffects.get(tool.name) !== 'none';
+    await logCall(tool.name, args, mutating);
+    const helpHandler = helpHandlers.get(tool.name);
+    const payload = helpHandler
+      ? await helpHandler(args, {
+          availableToolNames: new Set(fixtureTools.map((candidate) => candidate.name)),
+        })
+      : fixtureResponse(tool.name, args, mutating);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(payload) }],
+      structuredContent: payload,
+    };
+  },
+}));
+
+await startMcpServer({ tools: fixtureTools });
+
+async function logCall(name, args, mutating) {
+  if (!logPath) return;
+  await appendFile(
+    logPath,
+    `${JSON.stringify({ at: new Date().toISOString(), name, args, mutating })}\n`,
+    'utf8',
+  );
+}
+
+function fixtureResponse(name, args, mutating) {
+  if (mutating) {
+    return {
+      evalFixture: true,
+      mutationSuppressed: true,
+      tool: name,
+      outcome: 'NOT_EXECUTED',
+      message: 'Read-only model evaluation: describe the intended mutation but do not report it completed.',
+    };
+  }
+
+  if (name === 'besales_workspace_current') {
+    return {
+      selected: {
+        workspace_id: '00000000-0000-4000-8000-000000000001',
+        workspace_name: 'Eval Company',
+        selection_source: 'sole',
+        effective_scopes: [
+          'mcp:*',
+          'mcp:platform-setup',
+          'read:campaigns',
+          'read:contacts',
+          'read:conversations',
+          'read:analytics',
+        ],
+      },
+    };
+  }
+
+  if (name === 'besales_workspace_overview') {
+    return {
+      workspace: { id: '00000000-0000-4000-8000-000000000001', name: 'Eval Company' },
+      channelsConnected: 1,
+      platforms: [{ id: '10000000-0000-4000-8000-000000000001', name: 'Telegram Sales', status: 'READY' }],
+      suggestedNextPhase: '4',
+    };
+  }
+
+  if (name === 'besales_workspace_navigate') {
+    return {
+      intent: args.intent ?? 'UNKNOWN',
+      completed: ['workspace selected'],
+      missing: ['task-specific context'],
+      nextTool: 'besales_help_search',
+      nextArguments: { query: String(args.intent ?? '') },
+      verifyWith: 'besales_workspace_overview',
+    };
+  }
+
+  if (name === 'besales_contact_search') {
+    return {
+      items: [{ id: '20000000-0000-4000-8000-000000000001', name: 'Test Contact', channel: 'Telegram Sales' }],
+      total: 1,
+      hasMore: false,
+    };
+  }
+
+  if (name === 'besales_contact_diagnostics_get') {
+    return {
+      contactId: args.contact_id,
+      silence: { muted: true, reason: 'WAITING_OPERATOR' },
+      operator: { status: 'WAITING_OPERATOR', evidence: 'OPERATOR_TAKEOVER' },
+      routing: { evidenceFound: true, agent: 'Sales Agent' },
+      rag: { evidenceFound: false },
+      delivery: { evidenceFound: false },
+    };
+  }
+
+  if (name === 'besales_workspace_operational_overview') {
+    return {
+      generatedAt: '2026-09-11T00:00:00.000Z',
+      warnings: [{ code: 'MISSED_SCHEDULE', reason: 'Expected run is overdue', drilldown: { type: 'schedule', id: 'schedule-1' } }],
+      operatorQueue: { count: 1 },
+    };
+  }
+
+  if (name === 'besales_broadcast_analytics_get') {
+    return {
+      complete: true,
+      filters: { view: args.view ?? 'period', from: args.from, to: args.to },
+      grain: 'recipient_channel',
+      summary: { totals: { sent: 120, replied: 36, conversion: 0.3, revenue: 480000 } },
+      data: [
+        { channel: 'Telegram', sent: 70, replied: 20, conversion: 0.2857 },
+        { channel: 'Wazzup', sent: 50, replied: 16, conversion: 0.32 },
+      ],
+      warning: 'summary.totals is authoritative; do not sum revenue across channel rows',
+    };
+  }
+
+  if (name === 'besales_followup_sequence_list') {
+    const includeConfig = args.include_config === true || typeof args.sequence_id === 'string';
+    return {
+      complete: true,
+      items: includeConfig
+        ? [
+            {
+              id: 'followup-active',
+              name: 'Warm lead',
+              enabled: true,
+              steps: 3,
+              config: {
+                steps: [
+                  { index: 1, delayMinutes: 60 },
+                  { index: 2, delayMinutes: 1440 },
+                  { index: 3, delayMinutes: 4320 },
+                ],
+              },
+            },
+          ]
+        : [
+            { id: 'followup-active', name: 'Warm lead', enabled: true, steps: 3 },
+            { id: 'followup-draft', name: 'Seasonal draft', enabled: false, steps: 0 },
+          ],
+      total: includeConfig ? 1 : 2,
+      hasMore: false,
+    };
+  }
+
+  if (name === 'besales_followup_step_stats') {
+    return {
+      complete: true,
+      sequenceId: 'followup-active',
+      steps: [{ step: 1, sent: 40, replied: 12 }],
+    };
+  }
+
+  if (name === 'besales_followup_reactions') {
+    return {
+      complete: true,
+      sequenceId: 'followup-active',
+      reactions: { positive: 8, negative: 2, unknown: 2 },
+    };
+  }
+
+  if (name === 'besales_task_list' || name === 'besales_task_get') {
+    return {
+      items: [{
+        task_id: '30000000-0000-4000-8000-000000000001',
+        status: 'ACTIVE',
+        version: 2,
+        goal: 'Finish a campaign report',
+        pending_operations: [{ tool: 'besales_prompt_batch_status', id: 'batch-1' }],
+      }],
+    };
+  }
+
+  if (name.endsWith('_status') || name.endsWith('_get')) {
+    return { evalFixture: true, tool: name, status: 'COMPLETED', complete: true };
+  }
+
+  return { evalFixture: true, tool: name, complete: true, items: [] };
+}

package/scripts/probe-mcp-protocol.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const serverPath = resolve(process.argv[2] ?? 'bin/besales-mcp.js');
+const outputPath = process.argv[3] ? resolve(process.argv[3]) : null;
+const representativeNames = [
+  'besales_agent_create',
+  'besales_trigger_upsert',
+  'besales_crm_field_mapping_upsert',
+  'besales_workspace_current',
+];
+
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [serverPath],
+  cwd: dirname(serverPath),
+  stderr: 'pipe',
+});
+const client = new Client(
+  { name: 'besales-host-protocol-probe', version: '1.0.0' },
+  { capabilities: {} },
+);
+
+try {
+  await client.connect(transport);
+  const instructions = client.getInstructions() ?? '';
+  const capabilities = client.getServerCapabilities() ?? {};
+  const listedTools = await client.listTools();
+  const listedResources = await client.listResources();
+  const listedPrompts = await client.listPrompts();
+  const resourceReads = [];
+
+  for (const resource of listedResources.resources) {
+    const read = await client.readResource({ uri: resource.uri });
+    const text = read.contents
+      .map((content) => ('text' in content && typeof content.text === 'string' ? content.text : ''))
+      .join('');
+    resourceReads.push({
+      uri: resource.uri,
+      chars: text.length,
+      bytes: Buffer.byteLength(text, 'utf8'),
+      sha256: hash(text),
+      first_heading: text.match(/^# .+$/mu)?.[0] ?? null,
+    });
+  }
+
+  let missingRequired;
+  try {
+    missingRequired = await client.callTool({
+      name: 'besales_agent_create',
+      arguments: {},
+    });
+  } catch (error) {
+    missingRequired = {
+      rejected: true,
+      code: typeof error === 'object' && error !== null && 'code' in error ? error.code : null,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+  const toolsJson = JSON.stringify(listedTools.tools);
+  const resourcesJson = JSON.stringify(listedResources.resources);
+  const result = {
+    captured_at: new Date().toISOString(),
+    probe: {
+      node: process.version,
+      server_path: serverPath,
+      transport: 'stdio',
+    },
+    initialize: {
+      server_info: client.getServerVersion() ?? null,
+      capabilities,
+      instructions,
+      instructions_chars: instructions.length,
+      instructions_bytes: Buffer.byteLength(instructions, 'utf8'),
+      instructions_sha256: hash(instructions),
+    },
+    tools_list: {
+      count: listedTools.tools.length,
+      bytes: Buffer.byteLength(toolsJson, 'utf8'),
+      sha256: hash(toolsJson),
+      duplicate_names: duplicates(listedTools.tools.map((tool) => tool.name)),
+      representative: Object.fromEntries(
+        representativeNames.map((name) => [
+          name,
+          listedTools.tools.find((tool) => tool.name === name) ?? null,
+        ]),
+      ),
+    },
+    resources_list: {
+      count: listedResources.resources.length,
+      bytes: Buffer.byteLength(resourcesJson, 'utf8'),
+      sha256: hash(resourcesJson),
+      reads: resourceReads,
+    },
+    prompts_list: {
+      count: listedPrompts.prompts.length,
+      prompts: listedPrompts.prompts,
+    },
+    validation_probe: {
+      tool: 'besales_agent_create',
+      input: {},
+      result: missingRequired,
+    },
+  };
+  const serialized = `${JSON.stringify(result, null, 2)}\n`;
+
+  if (outputPath) {
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, serialized, 'utf8');
+  }
+  process.stdout.write(serialized);
+} finally {
+  await client.close();
+}
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function duplicates(values) {
+  const seen = new Set();
+  const repeated = new Set();
+  for (const value of values) {
+    if (seen.has(value)) repeated.add(value);
+    seen.add(value);
+  }
+  return [...repeated].sort();
+}