vvzvlad/gitmost

refactor(tools): генерировать инвентарь SERVER_INSTRUCTIONS из реестра + guard имён тулов (#448) #460

Open

agent_coder wants to merge 5 commits from refactor/448-generate-inventory into develop

Author	SHA1	Message	Date
agent_coder	4cb762b039	docs(mcp): обновить AGENTS.md + коммент под генерируемый инвентарь (ревью #460 ) Две доковые правки по ревью: (1) AGENTS.md-буллет описывал ДО-#448 мир (ручная правка SERVER_INSTRUCTIONS, enforced server-instructions.test.mjs, EXCEPTIONS) — переписан: shared-спеки авто-обновляют генерируемый <tool_inventory>, только inline-тул требует строки в INLINE_MCP_INVENTORY, enforced tool-inventory.test.mjs, EXCEPTIONS больше нет; (2) коммент в server-instructions.ts называл гард окольно ('tool-specs.test.mjs's sibling test') → назван tool-inventory.test.mjs напрямую. Единственная оставшаяся ссылка на удалённый тест устранена. Только доки/комменты. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-10 09:55:30 +03:00
agent_coder	d0f99052cf	refactor(tools): генерировать инвентарь SERVER_INSTRUCTIONS из реестра + guard имён тулов в промпте (#448 ) Финальный линк Фазы 1б. Инвентарь тулов жил в 4 рукописных прозаических копиях (SERVER_INSTRUCTIONS под regex-тестом; <tool_catalog>; имена в ai-chat.prompt.ts без гарда; README) — роадмап #416 планировал 4 последовательных ручных правки этого текста (#411/#412/#413/#415). - SERVER_INSTRUCTIONS разбит (новый модуль server-instructions.ts): ROUTING_ PROSE (рукописные intent-подсказки «когда что» — осмысленно ручные, перенесены ДОСЛОВНО со всеми предостережениями: <=250 у create_comment, soft-delete у delete_page, baseHash у drawio_update, PUBLIC у share_page) + buildToolInventory() — генерирует <tool_inventory> из реестра (mcpName + purpose из catalogLine, группировка по TOOL_FAMILY, бакет OTHER ловит незамаппленное → тул нельзя тихо потерять) + 5 inline MCP-only (INLINE_MCP_INVENTORY). Детерминирован (семейства FAMILY_ORDER, имена localeCompare). regex-тест server-instructions удалён; структурные гарантии — в новом tool-inventory.test.mjs (точное членство множества сильнее старого \b-скрейпа). - Имена тулов в ai-chat.prompt.ts → через экспорт PROMPT_TOOL_NAMES; новый гард ai-chat.prompt.tool-names.spec.ts: каждое имя — реальный тул реестра, скан guidance-нот на camelCase-токены падает на несуществующем (escape- нейтрализация против ложных nThe-токенов). - INLINE_TOOL_TIERS уже содержал ровно 8 genuinely-inline тулов (после #445) — сжатие не потребовалось. Критерий: добавление/переименование спека меняет инвентарь БЕЗ правки прозы. Внутреннее ревью: APPROVE — фактическим прогоном подтверждено, что НИ ОДИН тул из старого SERVER_INSTRUCTIONS не выпал (диф старый-vs-новый пуст; добавился get_workspace, раньше прятавшийся в EXCEPTIONS); проза дословна; инвентарь полон/детерминирован/без фантомов; гард краснеет на обеих ветках провала. 613 node + 289 jest зелёные. Стоит на #445 — мержить последним в стопке 1б. README-каталоги вне обязательного скоупа (docs-скрипт) — в чек-лист #412. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-10 09:21:28 +03:00
agent_coder	8c74659d91	refactor(tools): execute-маппинг в SHARED_TOOL_SPECS + автопроводка обоих хостов (#445 ) Ядро Фазы 1б. Реестр (#294) шарил только метаданные (имя/схема/описание/tier), но НЕ execute-логику — у каждого shared-тула было ДВА рукописных execute-тела с копией маппинга аргументов (MCP registerShared в index.ts; in-app sharedTool в ai-chat-tools.service, зеркалящий MCP-транспорт вручную). Корень повторяющихся parity-багов (`f46d89ea` drawio, `f8d26420` stashPage, `fc9088b7` node-args): добавление одного тула = 7-9 согласованных ручных правок в двух пакетах. - SharedToolSpec расширен: канонический execute(client, args) (чистый JS — свободно пересекает zod-мажорную границу v3/v4) + оверрайды mcpExecute/inAppExecute/mcpOnly/inAppOnly для ОСОЗНАННЫХ per-layer различий. client: DocmostClientLike (Pick из #446). Канон возвращает СЫРЬЁ, каждый хост накладывает свой конверт (MCP jsonContent, in-app как есть); override владеет результатом хоста целиком. - Оба хоста → циклы по Object.values(SHARED_TOOL_SPECS): index.ts registerShared 39→0 (цикл), ai-chat-tools.service sharedTool ~40→1 (цикл). Добавление спека автоматически регистрирует тул в ОБОИХ хостах — сценарий PR #434 невозможен по построению. - Осознанные различия через overrides (ни одно не сплющено к одному хосту): оба mcpExecute+inAppExecute — createPage/movePage/deletePage/ exportPageMarkdown/createComment (guardrails, конверты, проекции, тексты ошибок); execute+inAppExecute — getPage/renamePage/resolveComment; execute+mcpExecute — stashPage (resource_link+structuredContent), checkNewComments (since-guard только на MCP). - Оставлены inline (по делу): update_comment/delete_comment (MCP-only, in-app не даёт хард-правку/удаление комментов), search/transformPage (per-transport дивергенция — hybrid RRF / без deleteComments), table_get (noun-vs-verb naming clash — уедет после camelCase #412), getCurrentPage/updatePageContent/ listSidebarPages/getComment/getPageHistory (in-app-only, per-request state). - Guard-тесты (contract-parity, phantom-catalog) сохранены — теперь инварианты, не «последняя линия». Внутреннее ревью: APPROVE, построчная BEFORE/AFTER-сверка по каждому shared-тулу на обоих хостах — ни одного изменённого per-host поведения (порядок/дефолты аргументов, guard'ы, конверты, проекции сохранены), множества тулов побайтово совпадают (48 in-app, 45 MCP), кросс-zod-граница чистая (нет z. в execute), 611 mcp + 260 server тестов зелёные. Ядро Фазы 1б, стоит на #446 — мержить после. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-10 08:59:40 +03:00
agent_coder	fe5b6ecd8c	refactor(mcp): вывести DocmostClientLike/SharedToolSpec из реального типа клиента — убить ручные зеркала (#446 ) Восстановленный отложенный долг #294: @docmost/mcp не отдавал .d.ts, поэтому в сервере жили ТРИ дрейфующие ручные копии одних и тех же имён/сигнатур (DocmostClientLike ~230 строк, копия SharedToolSpec, name-only HOST_CONTRACT_ METHODS-тест). In-app execute-тела зовут клиент ПОЗИЦИОННО, так что перестановка параметра в client.ts доезжала до прода рантайм-ошибкой без сигнала на компиляции. - declaration:true (+declarationMap) в packages/mcp/tsconfig.json; types-экспорт в package.json (exports → conditional {types, default} для . и ./http; require.resolve/dynamic-import резолвят default → build/index.js, рантайм не тронут). build/index.d.ts эмитится, реэкспортит DocmostClient + SharedToolSpec. Правок исходников пакета для эмита НЕ потребовалось. - DocmostClientLike → Pick<DocmostClient, 48 методов> из type-only import (стёрт на компиляции, ESM/CJS-границу не задевает); ручное зеркало удалено. - SharedToolSpec → type-only реэкспорт из пакета; ручная копия удалена. - client-host-contract.test.mjs удалён целиком — имена И сигнатуры теперь проверяет tsc. - Позиционная безопасность: never-called __assertClientCallContract(client: DocmostClientLike) воспроизводит каждый позиционный вызов с типизированными плейсхолдерами (AI-SDK стирает вход execute-замыканий в any, иначе позиционные вызовы не проверялись). Перестановка параметров client.ts → ошибка компиляции сервера ровно тут. Loose as-касты в ai-chat-tools.service не потребовали правок; as any не добавлялся. Внутреннее ревью: APPROVE. Runtime resolution через conditional exports не сломан (разобрано для прод-инсталляции, не только symlink); покрытие __assertClientCallContract полное (48 call-sites == union == assert, сверено программно); Pick полон; демонстрация reorder → TS2345 в assert. Единственная находка (Promise<any> в части возвратов) предсуществующая в client.ts, вне цели PR. Стоит на #447 (закрытие skew build/vs/src) — мержить после него. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-10 08:29:46 +03:00
agent_coder	2e6f1c3de5	fix(ci,mcp): REGISTRY_STAMP в билд-артефакте + кросс-пакетный CI — закрыть skew build/ vs src/ (#447 ) Два структурных слепых пятна: (1) сервер грузит СКОМПИЛИРОВАННЫЙ packages/mcp/build/index.js, а серверные guard-тесты читают src/tool-specs.ts — правка src без пересборки оставляет тесты зелёными, но рантайм расходится со спеками; (2) спеки добавляют в packages/mcp, а parity-тесты живут в jest-сьюте apps/server — PR, трогающий только пакет, проходит зелёным, сломанная in-app- проводка всплывает уже на develop (кейс `f46d89ea`). - REGISTRY_STAMP: codegen (scripts/gen-registry-stamp.mjs) считает sha256 от нормализованного (CRLF→LF, один хвостовой \n снят) сырого текста src/tool-specs.ts, пишет src/registry-stamp.generated.ts (gitignored), index.ts реэкспортит → попадает в build/. Вшит в build/pretest/watch ДО tsc. - Loader (dev/test): computeSrcRegistryStamp пересчитывает стамп из src рядом с build/index.js (dev-vs-prod по existsSync, любая ошибка → null), сверяет с build-стампом → при рассинхроне бросает «build is stale — rebuild». В prod (src нет) и на pre-#447 билдах (нет REGISTRY_STAMP) — чистый no-op. - CI: job mcp-server-parity собирает shared-deps+mcp (регенерит стамп) и гоняет ОБА сьюта вместе (mcp node:test + server guard-спеки) — именованный гейт, его нельзя случайно расщепить. - AGENTS.md: правка спеков требует ребилда @docmost/mcp. Тесты (20): mcp-сайд (детерминизм, нормализация, desync-гард стамп-vs-билд) + server-сайд (null при отсутствии src = prod no-op; mismatch → throw точного сообщения; pre-#447 no-op). Кросс-импл equality-гард: один фиксированный вход → один хэш на ОБЕИХ сторонах, ловит рассинхрон двух нормализаций. Внутреннее ревью: APPROVE WITH SUGGESTIONS (обе — покрытие guard'а — закрыты этим тестом). Мутационно: любой из двух normalize-имплов расходится → equality-тест краснеет. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-10 07:58:37 +03:00