@besales/mcp 0.48.0 → 1.0.0-beta.4

package/scripts/shipped-definitions.mjs

@@ -0,0 +1,197 @@
+// Загрузчик ОТГРУЖЕННЫХ определений инструментов: исходник эталона извлекается из git в кэш внутри моста,
+// переводится в JavaScript без проверки типов и импортируется.
+//
+// ⭐ Зачем. Образец отгруженного вызова обязан пройти ФИЛЬТР отгруженного инструмента (схему zod и конструктор
+// запроса), а не только его JSON-схему: полный набор полей часто не является вызовом, который клиент вообще может
+// послать (взаимоисключающие поля), и сверка «примет ли v2 то, что шлёт клиент» на таком наборе отвечает не на тот
+// вопрос. Рукописный список взаимоисключений был бы второй копией правил и не видел бы случаев, где v2 строже.
+//
+// ⛔ Кэш лежит ВНУТРИ `node_modules` моста: голые импорты (`zod`) из извлечённого исходника разрешаются поиском вверх
+// по каталогам, и снаружи они не нашлись бы. Версии этих зависимостей сверяются с отгруженным `package.json`: фильтр,
+// исполненный на чужой версии библиотеки, отвечал бы не так, как у клиента.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import ts from 'typescript';
+
+/** Вход определений инструментов на отгружаемой линии. */
+export const SHIPPED_DEFINITIONS_ENTRY = 'src/tools/definitions.ts';
+const CACHE_SUBDIR = 'node_modules/.cache/besales-shipped-src';
+const COMPLETE_MARKER = '.complete.json';
+/** Версия способа перевода: кэш, собранный другим способом, пересобирается, а не исполняется. */
+const LOADER_VERSION = 1;
+
+/**
+ * Относительные импорты исходника (`./x.js` → `./x.ts`). Типовые импорты тоже входят: замыкание — вход СВЕЖЕСТИ
+ * выгрузки, и чувствительность к лишнему файлу безопаснее слепоты к нужному.
+ */
+function relativeImports(sourceText) {
+  return ts
+    .preProcessFile(sourceText, true, true)
+    .importedFiles.map((file) => file.fileName)
+    .filter((specifier) => specifier.startsWith('./') || specifier.startsWith('../'));
+}
+
+/** Голые импорты ИСПОЛНЯЕМОГО кода (после перевода типовые импорты исчезают). */
+function bareImports(javascriptText) {
+  return ts
+    .preProcessFile(javascriptText, true, true)
+    .importedFiles.map((file) => file.fileName)
+    .filter((specifier) => !specifier.startsWith('.') && !specifier.startsWith('node:'));
+}
+
+/** Имя пакета из спецификатора: `zod/v4` → `zod`, `@scope/pkg/sub` → `@scope/pkg`. */
+export function packageNameOf(specifier) {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+/**
+ * Замыкание относительных импортов от входа — пути от корня репозитория, по порядку.
+ *
+ * ⛔ Неразрешимый импорт роняет загрузку: пропущенный файл — это исполненный код, изменение которого не запустило бы
+ * срок несвежести выгрузки.
+ *
+ * @param {(repoPath: string) => string | undefined} readSource текст файла по пути от корня или `undefined`
+ */
+export function importClosure(entry, readSource) {
+  const seen = new Set();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (seen.has(current)) continue;
+    const text = readSource(current);
+    if (text === undefined) throw new Error(`отгруженный исходник: нет файла ${current}`);
+    seen.add(current);
+    if (!current.endsWith('.ts')) continue;
+    for (const specifier of relativeImports(text)) {
+      const target = posix.normalize(posix.join(posix.dirname(current), specifier));
+      const candidates = target.endsWith('.js')
+        ? [target.replace(/\.js$/u, '.ts'), target]
+        : target.endsWith('.json')
+          ? [target]
+          : [`${target}.ts`, `${target}/index.ts`];
+      const resolved = candidates.find((candidate) => readSource(candidate) !== undefined);
+      if (resolved === undefined) {
+        throw new Error(`отгруженный исходник: импорт ${specifier} из ${current} не разрешается`);
+      }
+      queue.push(resolved);
+    }
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Версии голых зависимостей исполняемого кода обязаны совпадать у отгруженного и у этой ветки: кэш исполняется на
+ * `node_modules` ветки. Расхождение — отказ, а не предупреждение.
+ */
+export function dependencyMismatches(bareSpecifiers, shippedPackage, localPackage) {
+  const specOf = (pkg, name) => pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+  const mismatches = [];
+  for (const name of [...new Set(bareSpecifiers.map(packageNameOf))].sort()) {
+    const shipped = specOf(shippedPackage, name);
+    const local = specOf(localPackage, name);
+    if (shipped !== local) mismatches.push(`${name}: отгружено ${shipped ?? 'нет'}, ветка ${local ?? 'нет'}`);
+  }
+  return mismatches;
+}
+
+function listFiles(root, directory, out = []) {
+  for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+    const path = posix.join(directory, entry.name);
+    if (entry.isDirectory()) listFiles(root, path, out);
+    else out.push(path);
+  }
+  return out;
+}
+
+/** Извлечение и перевод исходника коммита в кэш; повторный вызов с тем же коммитом берёт готовый кэш. */
+function materialize(packageRoot, commit) {
+  const cacheDir = join(packageRoot, CACHE_SUBDIR, commit);
+  const marker = join(cacheDir, COMPLETE_MARKER);
+  if (existsSync(marker)) {
+    const cached = JSON.parse(readFileSync(marker, 'utf8'));
+    if (cached.loaderVersion === LOADER_VERSION) return { cacheDir, meta: cached };
+  }
+  rmSync(cacheDir, { recursive: true, force: true });
+  mkdirSync(cacheDir, { recursive: true });
+  const archive = execFileSync('git', ['-C', packageRoot, 'archive', '--format=tar', commit, 'src', 'package.json'], {
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  execFileSync('tar', ['-x', '-C', cacheDir], { input: archive, stdio: ['pipe', 'ignore', 'pipe'] });
+  const readSource = (repoPath) => {
+    const absolute = join(cacheDir, repoPath);
+    return existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined;
+  };
+  const closure = importClosure(SHIPPED_DEFINITIONS_ENTRY, readSource);
+  const bare = [];
+  for (const repoPath of listFiles(cacheDir, 'src')) {
+    if (!repoPath.endsWith('.ts') || repoPath.endsWith('.d.ts') || repoPath.endsWith('.spec.ts')) continue;
+    const output = ts.transpileModule(readSource(repoPath), {
+      compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+      fileName: repoPath,
+    }).outputText;
+    writeFileSync(join(cacheDir, repoPath.replace(/\.ts$/u, '.js')), output);
+    if (closure.includes(repoPath)) bare.push(...bareImports(output));
+  }
+  const meta = { loaderVersion: LOADER_VERSION, commit, closure, bareImports: [...new Set(bare)].sort() };
+  mkdirSync(dirname(marker), { recursive: true });
+  writeFileSync(marker, `${JSON.stringify(meta, null, 2)}\n`);
+  return { cacheDir, meta };
+}
+
+/**
+ * Отгруженные определения инструментов коммита эталона.
+ *
+ * @returns {Promise<{ toolDefinitions: ReadonlyArray<any>, inputPaths: string[] }>} `inputPaths` — замыкание импортов
+ *   входа определений: по ним сервер считает свежесть выгрузки.
+ */
+export async function loadShippedDefinitions(packageRoot, commit) {
+  const { cacheDir, meta } = materialize(packageRoot, commit);
+  const mismatches = dependencyMismatches(
+    meta.bareImports,
+    JSON.parse(readFileSync(join(cacheDir, 'package.json'), 'utf8')),
+    JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')),
+  );
+  if (mismatches.length > 0) {
+    throw new Error(
+      `Отгруженный фильтр нельзя исполнить на зависимостях ветки — версии разошлись:\n  ${mismatches.join('\n  ')}`,
+    );
+  }
+  const entry = join(cacheDir, SHIPPED_DEFINITIONS_ENTRY.replace(/\.ts$/u, '.js'));
+  const module = await import(pathToFileURL(entry).href);
+  if (!Array.isArray(module.toolDefinitions)) {
+    throw new Error(`Отгруженный ${relative(packageRoot, entry)} не экспортирует toolDefinitions`);
+  }
+  return { toolDefinitions: module.toolDefinitions, inputPaths: meta.closure };
+}
+
+/**
+ * Исполняемый модуль ОТГРУЖЕННОГО пакета по пути от корня (`src/tools/result.ts`) — тот же кэш и та же сверка версий
+ * голых зависимостей, что у определений. Нужен проверкам, которым важно поведение УСТАНОВЛЕННОГО у клиентов моста, а
+ * не ветки: например, как отгруженный клиент показывает модели отказ сервера.
+ *
+ * @returns {Promise<Record<string, unknown>>} пространство имён модуля
+ */
+export async function loadShippedModule(packageRoot, commit, repoPath) {
+  const { cacheDir } = materialize(packageRoot, commit);
+  const readSource = (path) => {
+    const absolute = join(cacheDir, path);
+    return existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined;
+  };
+  const bare = importClosure(repoPath, readSource)
+    .filter((path) => path.endsWith('.ts'))
+    .flatMap((path) => bareImports(readFileSync(join(cacheDir, path.replace(/\.ts$/u, '.js')), 'utf8')));
+  const mismatches = dependencyMismatches(
+    bare,
+    JSON.parse(readFileSync(join(cacheDir, 'package.json'), 'utf8')),
+    JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')),
+  );
+  if (mismatches.length > 0) {
+    throw new Error(`Отгруженный модуль нельзя исполнить на зависимостях ветки:\n  ${mismatches.join('\n  ')}`);
+  }
+  return import(pathToFileURL(join(cacheDir, repoPath.replace(/\.ts$/u, '.js'))).href);
+}

package/scripts/shipped-definitions.spec.mjs

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import { dependencyMismatches, importClosure, packageNameOf } from './shipped-definitions.mjs';
+
+/**
+ * Загрузчик отгруженных определений: замыкание импортов — вход СВЕЖЕСТИ выгрузки, версии зависимостей — условие
+ * честного исполнения отгруженного фильтра.
+ */
+describe('замыкание импортов отгруженных определений', () => {
+  const files = new Map([
+    ['src/tools/definitions.ts', "import { a } from './definitions/a.js';\nimport type { T } from '../types.js';"],
+    ['src/tools/definitions/a.ts', "import { b } from './b.js';\nimport data from '../../schemas/data.json';"],
+    ['src/tools/definitions/b.ts', "import { z } from 'zod';\nexport const b = z.string();"],
+    ['src/types.ts', 'export type T = string;'],
+    ['src/schemas/data.json', '{}'],
+    ['src/unrelated.ts', 'export const x = 1;'],
+  ]);
+  const read = (path) => files.get(path);
+
+  it('обходит относительные импорты (и типовые, и данные), голые и чужие файлы в него не входят', () => {
+    expect(importClosure('src/tools/definitions.ts', read)).toEqual([
+      'src/schemas/data.json',
+      'src/tools/definitions.ts',
+      'src/tools/definitions/a.ts',
+      'src/tools/definitions/b.ts',
+      'src/types.ts',
+    ]);
+  });
+
+  it('⛔ неразрешимый импорт — отказ: пропущенный файл был бы исполненным кодом без срока свежести', () => {
+    const broken = new Map(files);
+    broken.set('src/tools/definitions/b.ts', "import { gone } from './gone.js';");
+
+    expect(() => importClosure('src/tools/definitions.ts', (path) => broken.get(path))).toThrow(
+      'импорт ./gone.js из src/tools/definitions/b.ts не разрешается',
+    );
+  });
+});
+
+describe('версии зависимостей', () => {
+  it('имя пакета из спецификатора', () => {
+    expect(packageNameOf('zod/v4')).toBe('zod');
+    expect(packageNameOf('@modelcontextprotocol/sdk/types.js')).toBe('@modelcontextprotocol/sdk');
+  });
+
+  it('расхождение версии исполняемой зависимости — отказ с обеими версиями', () => {
+    expect(
+      dependencyMismatches(['zod', 'zod/v4'], { dependencies: { zod: '^4.4.3' } }, { dependencies: { zod: '^4.4.3' } }),
+    ).toEqual([]);
+    expect(
+      dependencyMismatches(['zod'], { dependencies: { zod: '^4.4.3' } }, { devDependencies: { zod: '^4.5.0' } }),
+    ).toEqual(['zod: отгружено ^4.4.3, ветка ^4.5.0']);
+    expect(dependencyMismatches(['left-pad'], { dependencies: { 'left-pad': '1.0.0' } }, {})).toEqual([
+      'left-pad: отгружено 1.0.0, ветка нет',
+    ]);
+  });
+});

package/scripts/shipped-inputs.spec.mjs

@@ -0,0 +1,136 @@
+import { readFileSync, readdirSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+import { SHIPPED_INPUT_PATHS } from './shipped-registry.mjs';
+
+/**
+ * Список входов выгрузки на отгружаемой линии обязан совпадать с ФАКТИЧЕСКИМИ чтениями.
+ *
+ * ⛔ Зачем сторож. Список уезжает в выгрузку и там становится входом чужой проверки: besales-api
+ * по нему решает, менялось ли на отгружаемой линии то, из чего собран артефакт. Добавленное
+ * чтение, не попавшее в список, не даст ни ошибки, ни красного теста — оно просто перестанет
+ * запускать срок несвежести, и проверка продолжит отвечать «свежо» на устаревшей выгрузке. То
+ * есть промах тут стоит ровно той слепоты, ради которой проверка и заводилась.
+ *
+ * ⛔ Разбор fail-closed. Чтение с НЕИЗВЕСТНЫМ якорем роняет тест, а не пропускается: якорь — это
+ * ответ на вопрос «с какой стороны читаем», и молчаливый пропуск незнакомого якоря вернул бы ту
+ * же дыру под другим именем.
+ */
+
+/** Откуда читаем. Отгружаемая линия — входы выгрузки; ветка v2 — её собственное состояние. */
+const SHIPPED_ANCHORS = new Set(['ref', 'shipped.provenance.commit']);
+const V2_ANCHORS = new Set(['generatorV2Commit']);
+
+const SOURCES = ['scripts/shipped-registry.mjs', 'scripts/emit-tool-routes.mjs'];
+
+/** `const NAME = 'значение';` — чтобы разрешить `${NAME}` в шаблоне чтения. */
+function declaredConstants(source) {
+  const constants = new Map();
+  for (const match of source.matchAll(/const\s+([A-Za-z0-9_]+)\s*=\s*'([^']+)'/gu)) {
+    constants.set(match[1], match[2]);
+  }
+  return constants;
+}
+
+/**
+ * Все чтения вида `git show <якорь>:<путь>` в исходнике.
+ *
+ * ⛔ Привязка к `'show'` обязательна: без неё в разбор попадали бы ЛЮБЫЕ шаблоны с двоеточием
+ * после подстановки — например текст ошибки «Не удалось обновить ${ref}: …», — и список «входов»
+ * заполнялся бы кусками сообщений. Обратная сторона привязки закрыта счётом ниже: чтение,
+ * записанное иначе, парсер не увидит, поэтому число разобранных чтений сверяется с числом
+ * вызовов `show` в тех же файлах.
+ */
+function readsOf(source) {
+  const constants = declaredConstants(source);
+  const reads = [];
+  for (const match of source.matchAll(/'show',\s*`\$\{([A-Za-z0-9_.]+)\}:([^`]+)`/gu)) {
+    const [, anchor, rawTarget] = match;
+    const named = /^\$\{([A-Za-z0-9_]+)\}$/u.exec(rawTarget);
+    const target = named === null ? rawTarget : constants.get(named[1]);
+    expect(target, `путь чтения ${rawTarget} не разрешается в строку`).toBeDefined();
+    reads.push({ anchor, target });
+  }
+  return reads;
+}
+
+describe('входы выгрузки на отгружаемой линии', () => {
+  const reads = SOURCES.flatMap((path) => readsOf(readFileSync(path, 'utf8')));
+
+  it('разбор нашёл сами чтения — иначе проверка ниже пуста по построению', () => {
+    expect(reads.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('⛔ разобраны ВСЕ чтения: счёт совпадает с числом вызовов show в этих же файлах', () => {
+    // Половина, закрывающая слепое пятно разбора: чтение, записанное в другой форме, парсер
+    // пропустил бы молча, и список входов остался бы неполным при зелёном тесте.
+    const showCalls = SOURCES.map((path) => readFileSync(path, 'utf8'))
+      .join('\n')
+      .match(/'show'/gu);
+
+    expect(reads.length).toBe(showCalls?.length ?? 0);
+  });
+
+  it('каждое чтение якорится известной стороной', () => {
+    const unknown = reads
+      .filter((read) => !SHIPPED_ANCHORS.has(read.anchor) && !V2_ANCHORS.has(read.anchor))
+      .map((read) => `${read.anchor}:${read.target}`);
+
+    expect(unknown).toEqual([]);
+  });
+
+  it('⛔ читают отгружаемую линию ТОЛЬКО через show: иных способов чтения нет', () => {
+    // ⛔ Счёт вызовов `show` закрывает лишь иначе записанный show. Чтение, сделанное ДРУГОЙ
+    // командой (`cat-file blob`, `archive`, чтение чекаута файлом), парсер не увидит вовсе, и
+    // новый вход перестанет запускать срок несвежести при зелёном тесте.
+    const sources = SOURCES.map((path) => readFileSync(path, 'utf8')).join('\n');
+    const forbidden = ['cat-file', 'archive', 'worktree', 'checkout'].filter((verb) =>
+      sources.includes(`'${verb}'`),
+    );
+
+    expect(forbidden).toEqual([]);
+  });
+
+  it('⛔ исходник отгружаемой линии целиком читает РОВНО один модуль — загрузчик определений, и его чтения объявлены', () => {
+    // Загрузчик извлекает исходник эталона командой archive, а объявляет прочитанное замыканием импортов входа
+    // определений — выгрузка кладёт его в список входов (тест ниже). Второй модуль с таким чтением остался бы без
+    // объявления и не запускал бы срок несвежести.
+    const readers = readdirSync('scripts')
+      .filter((name) => name.endsWith('.mjs') && !name.endsWith('.spec.mjs'))
+      .filter((name) => readFileSync(`scripts/${name}`, 'utf8').includes("'archive'"));
+
+    expect(readers).toEqual(['shipped-definitions.mjs']);
+  });
+
+  it('⛔ поле выгрузки строится ИЗ ЭТИХ констант, а не из своего списка', () => {
+    // Иначе список в артефакте и список здесь разъезжаются молча: сторож зелен, а besales-api
+    // следит за другими путями, чем читает эмиттер.
+    const emitter = readFileSync('scripts/emit-tool-routes.mjs', 'utf8');
+
+    // Третья часть списка — замыкание импортов отгруженных определений: выгрузка ИСПОЛНЯЕТ отгруженный фильтр, и его
+    // исходник — такой же вход, как реестр. Замыкание считает загрузчик по коммиту эталона (`shipped-definitions.mjs`).
+    expect(emitter.replace(/\s+/gu, ' ')).toContain(
+      'shippedInputPaths: [ ...new Set([...SHIPPED_INPUT_PATHS, SHIPPED_CLIENT_SOURCE, ...shippedDefinitions.inputPaths]), ].sort()',
+    );
+  });
+
+  it('⛔ объявленный список равен фактическим чтениям отгружаемой линии', () => {
+    // Вторая, несущая половина: список не просто НЕПУСТ, он совпадает с тем, что читается.
+    // Проверка «список непуст» была бы зелена и на списке из одного файла при трёх чтениях.
+    const actual = [
+      ...new Set(reads.filter((read) => SHIPPED_ANCHORS.has(read.anchor)).map((read) => read.target)),
+    ].sort();
+
+    expect(actual).toEqual([...SHIPPED_INPUT_PATHS, 'src/auth/oauth-client.ts'].sort());
+  });
+
+  it('чтение состояния ветки v2 в список входов отгружаемой линии не попадает', () => {
+    // Разные предметы: исходник клиента ветки v2 читается с ЕЁ коммита и свежести выгрузки не
+    // касается. Смешав их, мы запускали бы срок на собственных правках моста.
+    const v2Reads = reads.filter((read) => V2_ANCHORS.has(read.anchor));
+
+    expect(v2Reads.length).toBeGreaterThan(0);
+    expect(SHIPPED_INPUT_PATHS).not.toContain('src/auth/oauth-client.ts');
+  });
+});

package/scripts/shipped-recordings.spec.mjs

@@ -0,0 +1,19 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { expect, it } from 'vitest';
+import { loadShippedDefinitions } from './shipped-definitions.mjs';
+import { shippedRef } from './shipped-ref.mjs';
+
+it('записанный плановый вызов принадлежит истории отгруженной линии и воспроизводит прежний запрос', async () => {
+  const root = fileURLToPath(new URL('..', import.meta.url));
+  const fixture = JSON.parse(readFileSync(new URL(
+    '../src/tools/definitions/__fixtures__/scheduled-task-shipped-call.json', import.meta.url,
+  ), 'utf8'));
+  expect(fixture.source.commit).toMatch(/^[a-f0-9]{40}$/u);
+  execFileSync('git', ['-C', root, 'merge-base', '--is-ancestor', fixture.source.commit, shippedRef()]);
+  const { toolDefinitions } = await loadShippedDefinitions(root, fixture.source.commit);
+  const tool = toolDefinitions.find((entry) => entry.name === 'besales_scheduled_task_update');
+  expect(tool).toBeDefined();
+  expect(tool.createRequest(tool.schema.parse(fixture.input))).toEqual(fixture.shippedRequest);
+}, 60000);

package/scripts/shipped-ref.d.mts

@@ -0,0 +1,5 @@
+export const SHIPPED_REF_ENV: 'BESALES_MCP_SHIPPED_REF';
+export const DEFAULT_SHIPPED_REF: 'origin/v1-line';
+export function shippedRef(env?: Record<string, string | undefined>): string;
+export function shippedRemoteRef(ref?: string): string;
+export function parseShippedRef(ref?: string): { remote: string; branch: string };

package/scripts/shipped-ref.mjs

@@ -0,0 +1,20 @@
+/** Единая настройка ссылки на отгруженную клиентам линию пакета. */
+export const SHIPPED_REF_ENV = 'BESALES_MCP_SHIPPED_REF';
+export const DEFAULT_SHIPPED_REF = 'origin/v1-line';
+
+export function shippedRef(env = process.env) {
+  return env[SHIPPED_REF_ENV]?.trim() || DEFAULT_SHIPPED_REF;
+}
+
+/** Полное имя локальной ссылки на удалённую ветку для show-ref. */
+export function shippedRemoteRef(ref = shippedRef()) {
+  return `refs/remotes/${ref}`;
+}
+
+/** Первый слеш отделяет удалённый репозиторий; остальные принадлежат имени ветки. */
+export function parseShippedRef(ref = shippedRef()) {
+  const slash = ref.indexOf('/');
+  return slash < 0
+    ? { remote: 'origin', branch: ref }
+    : { remote: ref.slice(0, slash), branch: ref.slice(slash + 1) };
+}

package/scripts/shipped-ref.spec.mjs

@@ -0,0 +1,59 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  DEFAULT_SHIPPED_REF,
+  SHIPPED_REF_ENV,
+  parseShippedRef,
+  shippedRef,
+  shippedRemoteRef,
+} from './shipped-ref.mjs';
+import { SHIPPED_REGISTRY_REF_ENV } from './shipped-registry.mjs';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+const HISTORICAL_REF_EXCEPTIONS = {
+  'src/schemas/shipped-lag.json': 'Проза прежних решений о долге; основания не переписываются.',
+  'src/tools/definitions/__fixtures__/scheduled-task-shipped-call.json':
+    'Историческое имя ссылки при записи вызова; проверяется коммит и исполненный запрос.',
+  'src/tools/definitions/__fixtures__/setup-init-shipped.json':
+    'Исторический источник снимка схем; проверяется коммит и содержимое Git.',
+  'scripts/shipped-ref.spec.mjs': 'Сам сторож обязан называть запрещённый литерал.',
+};
+
+describe('единая ссылка на отгруженную линию', () => {
+  it('сохраняет имя настройки; отсутствие, пустота и пробелы дают сохранённую ветку', () => {
+    expect(SHIPPED_REF_ENV).toBe('BESALES_MCP_SHIPPED_REF');
+    expect(SHIPPED_REGISTRY_REF_ENV).toBe(SHIPPED_REF_ENV);
+    expect(DEFAULT_SHIPPED_REF).toBe('origin/v1-line');
+    for (const value of [undefined, '', '  \t\n']) {
+      expect(shippedRef({ [SHIPPED_REF_ENV]: value })).toBe('origin/v1-line');
+    }
+    expect(shippedRef({ [SHIPPED_REF_ENV]: '  backup/release/v1  ' })).toBe('backup/release/v1');
+  });
+
+  it('без аргумента читает окружение; полное имя и разбор используют ту же настройку', () => {
+    vi.stubEnv(SHIPPED_REF_ENV, ' backup/release/v1 ');
+    try {
+      expect(shippedRef()).toBe('backup/release/v1');
+      expect(shippedRemoteRef()).toBe('refs/remotes/backup/release/v1');
+      expect(parseShippedRef()).toEqual({ remote: 'backup', branch: 'release/v1' });
+    } finally {
+      vi.unstubAllEnvs();
+    }
+    expect(shippedRemoteRef('upstream/v1')).toBe('refs/remotes/upstream/v1');
+    expect(parseShippedRef('v1-line')).toEqual({ remote: 'origin', branch: 'v1-line' });
+  });
+
+  it('отслеживаемые исходники не зашивают origin/main вне объявленных исторических исключений', () => {
+    const files = execFileSync('git', ['-C', root, 'ls-files', '-z', '--', 'scripts/', 'src/'], {
+      encoding: 'utf8',
+    }).split('\0').filter(Boolean);
+    expect(files.length).toBeGreaterThan(0);
+    const violations = files.filter((path) =>
+      !Object.hasOwn(HISTORICAL_REF_EXCEPTIONS, path) &&
+      readFileSync(new URL(`../${path}`, import.meta.url), 'utf8').includes('origin/main'),
+    );
+    expect(violations, 'Зашитая ссылка на отгруженную линию').toEqual([]);
+  });
+});

package/scripts/shipped-registry.mjs

@@ -0,0 +1,107 @@
+// Отгруженный реестр инструментов — ЭТАЛОН, с которым сверяется ветка v2.
+//
+// Берётся из этого же репозитория (ссылка задаётся общей настройкой отгруженной линии): отгружаемая клиентам
+// линия и ветка v2 — два состояния одного репозитория, поэтому никакой зависимости от чужой рабочей
+// копии на диске нет, достаточно доступа к ремоуту.
+//
+// Fail-closed: без эталона выгрузка не пишется вовсе. Иначе проверка полноты моста снова сравнивала
+// бы v2 сам с собой — ровно та слепота, ради которой этот модуль и появился.
+import { execFileSync } from 'node:child_process';
+import { SHIPPED_REF_ENV, parseShippedRef, shippedRef } from './shipped-ref.mjs';
+import { readFileSync } from 'node:fs';
+
+const REGISTRY_PATH = 'src/schemas/mcp-tools.json';
+const PACKAGE_PATH = 'package.json';
+
+/**
+ * Что выгрузка ЧИТАЕТ с отгружаемой линии — объявлено списком и уезжает в артефакт.
+ *
+ * ⛔ Список нужен не здесь, а на стороне besales-api: там по нему считается СВЕЖЕСТЬ выгрузки —
+ * «менялось ли с тех пор то, из чего она собрана». Своя копия списка на той стороне разошлась бы
+ * с этим модулем молча: эмиттер начал бы читать из отгружаемой линии четвёртый файл, а проверка
+ * продолжала бы следить за тремя — и правка, ради которой перевыпуск и нужен, срока бы не
+ * запускала. Поэтому список объявлен РЯДОМ с чтениями и едет вместе с выгрузкой.
+ *
+ * Тест `shipped-inputs.spec.mjs` сверяет его с фактическими чтениями обоих скриптов.
+ */
+export const SHIPPED_INPUT_PATHS = Object.freeze([REGISTRY_PATH, PACKAGE_PATH]);
+
+/** Офлайн-выход: путь к реестру. Обязан идти вместе с коммитом, иначе вход непроверяем. */
+export const SHIPPED_REGISTRY_PATH_ENV = 'BESALES_MCP_SHIPPED_REGISTRY';
+export const SHIPPED_REGISTRY_COMMIT_ENV = 'BESALES_MCP_SHIPPED_COMMIT';
+/** Ссылка на отгружаемую ветку — на случай, если линия отгрузки когда-нибудь переедет. */
+export const SHIPPED_REGISTRY_REF_ENV = SHIPPED_REF_ENV;
+
+function git(repoRoot, args) {
+  return execFileSync('git', ['-C', repoRoot, ...args], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * @param {string} repoRoot корень репозитория пакета
+ * @param {{ env?: Record<string, string | undefined> }} [options]
+ * @returns {{ tools: Array<{ name: string, inputSchema?: unknown }>, provenance: Record<string, unknown> }}
+ */
+export function loadShippedRegistry(repoRoot, options = {}) {
+  const env = options.env ?? process.env;
+  // ⚠️ Файловый вход — ТОЛЬКО для локальной диагностики без сети. Выгрузка, сделанная через него,
+  // в коммит попадать не должна: besales-api утверждает происхождение эталона отдельным тестом
+  // (`source: 'git'`, `ref: shippedRef()`, `fetched: true`), и такой артефакт покраснеет — именно
+  // затем, чтобы проверка полноты моста никогда не сравнивала ветку v2 саму с собой.
+  const explicitPath = env[SHIPPED_REGISTRY_PATH_ENV]?.trim();
+  if (explicitPath) {
+    const commit = env[SHIPPED_REGISTRY_COMMIT_ENV]?.trim();
+    if (!commit) {
+      throw new Error(
+        `${SHIPPED_REGISTRY_PATH_ENV} задан без ${SHIPPED_REGISTRY_COMMIT_ENV}: офлайн-вход обязан ` +
+          'назвать, какое состояние отгруженной линии он выдаёт за эталон.',
+      );
+    }
+    const tools = JSON.parse(readFileSync(explicitPath, 'utf8')).tools;
+    return {
+      tools,
+      provenance: {
+        source: 'file',
+        path: explicitPath,
+        commit,
+        version: null,
+        toolCount: tools.length,
+      },
+    };
+  }
+
+  const ref = shippedRef(env);
+  const { remote, branch } = parseShippedRef(ref);
+  // Сбой fetch РОНЯЕТ генерацию. Уцелевшая локальная ссылка — не эталон, а его снимок неизвестной
+  // давности: продолжив на ней, выгрузка объявила бы сверку состоявшейся, хотя сверялась со старым
+  // состоянием отгружаемой линии. Выход из fail-closed один и он ниже, в тексте ошибки.
+  try {
+    git(repoRoot, ['fetch', '--no-tags', '--quiet', remote, branch]);
+  } catch {
+    throw new Error(
+      `Не удалось обновить ${ref}: эталон нельзя считать актуальным, выгрузка остановлена. ` +
+        `Офлайн-выход: ${SHIPPED_REGISTRY_PATH_ENV}=<файл> ${SHIPPED_REGISTRY_COMMIT_ENV}=<sha>.`,
+    );
+  }
+
+  let commit;
+  try {
+    commit = git(repoRoot, ['rev-parse', ref]).trim();
+  } catch {
+    throw new Error(
+      `Отгруженный реестр недостижим: ссылка ${ref} не разрешается. ` +
+        `Дай доступ к ремоуту либо укажи реестр явно: ${SHIPPED_REGISTRY_PATH_ENV}=<файл> ` +
+        `${SHIPPED_REGISTRY_COMMIT_ENV}=<sha>.`,
+    );
+  }
+
+  const tools = JSON.parse(git(repoRoot, ['show', `${ref}:${REGISTRY_PATH}`])).tools;
+  const version = JSON.parse(git(repoRoot, ['show', `${ref}:${PACKAGE_PATH}`])).version;
+  return {
+    tools,
+    provenance: { source: 'git', ref, commit, version, toolCount: tools.length, fetched: true },
+  };
+}