gennady 0.6.0 → 0.7.0

package/dist/ai/fw-draft/rules/dev/base/file-structure-rules.xml

@@ -0,0 +1,89 @@
+<!-- ai/framework/architecture/file_structure_rules.xml -->
+<File_Structure_Protocol id="CleanArchitecture_v1.1">
+    <Preamble>
+        Этот протокол определяет стандарт для организации файловой структуры любого проекта. Он основан на принципах Чистой Архитектуры (Ports & Adapters), что обеспечивает низкую связанность, высокую тестируемость и понятность кодовой базы.
+    </Preamble>
+    <Core_Philosophy>
+        <Rationale>
+            Код должен быть организован по бизнес-назначению, а не по техническому типу. Это позволяет любому разработчику (или другому AI-агенту) быстро понять, за что отвечает каждый компонент системы, и вносить изменения в одном месте, не затрагивая другие. Мы разделяем "что" делает система (домен, сервисы) от "как" она это делает (базы данных, фреймворки).
+        </Rationale>
+        <Directive>
+            Твоя задача — проектировать файловую структуру как набор независимых слоев с явными границами. Каждый файл и директория должны иметь единственную, четко определенную ответственность.
+        </Directive>
+    </Core_Philosophy>
+    <Layer_Definitions>
+        <Layer id="entities" directory_name="entities">
+            <Objective>Изолировать чистые, независимые сущности домена, типы данных и бизнес-ошибки.</Objective>
+            <Directive>
+                Каждый файл должен содержать одну логическую сущность или тесно связанную группу (например, `user_entity.py`, `order_errors.py`). Этот слой не должен иметь никаких зависимостей от других слоев.
+            </Directive>
+        </Layer>
+        <Layer id="ports" directory_name="ports">
+            <Objective>Определить контракты (интерфейсы) для взаимодействия с внешним миром без указания реализации.</Objective>
+            <Directive>
+                Здесь находятся только абстракции: интерфейсы репозиториев (`i_user_repository.py`), клиентов внешних API, систем уведомлений. Этот слой содержит только объявления, без кода реализации.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Ports)</Note>
+        </Layer>
+        <Layer id="services" directory_name="services">
+            <Objective>Реализовать сценарии использования (use cases) и оркестрировать бизнес-логику.</Objective>
+            <Directive>
+                Сервисы зависят от абстракций (`ports`), а не от конкретных реализаций. Они оперируют доменными сущностями (`entities`). Имена файлов должны отражать бизнес-сценарий (`create_order_service.py`).
+            </Directive>
+        </Layer>
+        
+        <Layer id="infrastructure" directory_name="infrastructure">
+            <Objective>Предоставить конкретные реализации для исходящих портов и инкапсулировать все взаимодействия с внешним миром (сеть, файловая система, БД).</Objective>
+            <Directive>
+                Здесь находятся HTTP-клиенты, коннекторы к базам данных, реализации репозиториев (`gitlab_api_client.py`, `postgres_user_repository.py`). Этот код реализует интерфейсы из слоя `ports`.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Driven Adapters)</Note>
+        </Layer>
+
+        <Layer id="interfaces" directory_name="interfaces">
+            <Objective>Определить точки входа в приложение (API-хендлеры, CLI-команды, обработчики событий).</Objective>
+            <Directive>
+                Этот слой является "переводчиком" внешних запросов в вызовы внутренних сервисов. Он отвечает за парсинг входящих данных, вызов соответствующего сервиса и форматирование ответа. Бизнес-логика здесь запрещена.
+            </Directive>
+            <Note>(Role in Ports & Adapters: Driving Adapters)</Note>
+        </Layer>
+        <Layer id="config" directory_name="config">
+            <Objective>Управлять конфигурацией приложения: сборка, валидация и предоставление доступа к настройкам.</Objective>
+            <Directive>
+                Этот слой использует `infrastructure` для чтения настроек из окружения или файлов и предоставляет типизированный, валидированный объект конфигурации для остальных частей приложения.
+            </Directive>
+        </Layer>
+    </Layer_Definitions>
+    <Scalability_And_Adoption>
+        <Rule id="MINIMAL_SET">
+            Для простых проектов обязательными являются только три слоя: `entities`, `services`, `infrastructure`. В этом случае сервисы могут напрямую зависеть от инфраструктуры.
+        </Rule>
+        <Rule id="WHEN_TO_ADD_PORTS">
+            Слой `ports` вводится тогда, когда появляется необходимость иметь несколько реализаций для одного контракта (например, для тестов (`in_memory_repository`) и для прода (`postgres_repository`)) или когда нужно строго отделить бизнес-логику от деталей реализации.
+        </Rule>
+    </Scalability_And_Adoption>
+    <Anti_Patterns_To_Avoid>
+        <Pattern id="MONOLITHIC_TYPES">
+            <Description>Создание общих файлов `types.py`, `models.py` или `schemas.py`, содержащих все типы данных проекта.</Description>
+            <Rationale>Это приводит к высокой связанности. Изменение одного типа требует модификации общего файла, затрагивая всю систему. Типы должны находиться в слое `entities` или рядом с модулем, который их использует.</Rationale>
+            <Directive>Распределяй определения данных по доменной принадлежности.</Directive>
+        </Pattern>
+        <Pattern id="DUMP_DIRECTORY">
+            <Description>Создание директории `utils` или `helpers` как "свалки" для всего, что не подошло в другие места.</Description>
+            <Rationale>Со временем такие директории становятся непредсказуемыми и сложными для навигации. Функция без побочных эффектов может остаться в `utils`, но если она работает с сетью или ФС, ее место — в `infrastructure`.</Rationale>
+            <Directive>Всегда классифицируй функцию по ее назначению и помещай в соответствующий слой.</Directive>
+        </Pattern>
+    </Anti_Patterns_To_Avoid>
+    <Testing_Strategy>
+        <Objective>Обеспечить четкое разделение исходного кода и тестов, сохраняя при этом понятную навигацию.</Objective>
+        <Directive>
+            Создай директорию для тестов (например, `tests/` или `__tests__/`) на том же уровне, что и директория с исходным кодом. Внутри этой директории **полностью воспроизведи (отзеркаль)** структуру исходников.
+        </Directive>
+        <Example>
+            Если есть файл `services/user/create_user.py`, то его тест должен находиться в `tests/services/user/test_create_user.py`.
+        </Example>
+        <Rationale>
+            Такой подход позволяет мгновенно находить тесты для любого модуля и сразу понимать, какой слой и компонент системы проверяется.
+        </Rationale>
+    </Testing_Strategy>
+</File_Structure_Protocol>

package/dist/ai/fw-draft/rules/dev/typescript/contacts.xml

@@ -0,0 +1,194 @@
+<JSDOC_AS_CONTACTS hint="Правила оформления контактов в коде через JSDoc">
+  <Tag_Order>Строгий порядок в JSDoc: @purpose → @consumer → @invariant → @pre → @param → @throws → @returns → @post → @sideEffect</Tag_Order>
+  <TypeScript_Rules>
+    <Rule id="type_vs_interface">Для структур данных (объекты, DTO, ответы API, нормализованные модели) использовать type. interface — только для сущностей, которые наследуют или расширяют (несколько классов реализуют один контракт). Классы ошибок (extends Error) остаются class.</Rule>
+    <Rule id="naming_domain">Типы, относящиеся к внешней системе или домену (API, сервис), должны иметь префикс в имени (напр. ApiResource, ExternalServiceDto, VendorOrder). Внутренние утилитные типы без внешнего домена — без префикса.</Rule>
+  </TypeScript_Rules>
+  <TypeScript_Conventions hint="Node 22+, совместимость с декораторами">
+    <Convention id="no_enum">Не использовать enum. Вместо: const + as const или union type.</Convention>
+    <Convention id="no_constructor_modifiers">Не использовать модификаторы в конструкторе (public, private). Явное объявление полей в теле класса.</Convention>
+    <Convention id="no_private">Не использовать private / #private field. Вместо: protected _field с префиксом _.</Convention>
+    <Convention id="no_readonly_param">readonly — в объявлении поля, не в параметре конструктора.</Convention>
+  </TypeScript_Conventions>
+  <Tag_Dictionary hint="Полный реестр допустимых JSDoc-тегов для контрактов">
+    <Tag name="@purpose" type="mandatory">
+      <Definition>Телеологическое назначение. Зачем эта сущность существует в бизнес-логике?</Definition>
+      <Condition_Use>ВСЕГДА для любых экспортируемых (export) сущностей (классы, методы, типы, интерфейсы, константы).</Condition_Use>
+      <Format>@purpose {Глагол} {Объект} {Контекст}.</Format>
+    </Tag>
+    <Tag name="@consumer" type="contextual">
+      <Definition>Кто является клиентом этого API? (Другие модули, UI, внешние системы).</Definition>
+      <Condition_Use>Для корневых сущностей (классы, модули) и публичных методов API.</Condition_Use>
+      <Condition_Skip>Для внутренних утилитных типов или методов.</Condition_Skip>
+      <Format>@consumer {ModuleName}, {SystemName}</Format>
+    </Tag>
+    <Tag name="@param" type="functional">
+      <Definition>Описание входящего аргумента: одно связное описание бизнес-роли и границ валидности. Для параметров-объектов описывается их общая роль, без дублирования описания внутренних полей.</Definition>
+      <Condition_Use>ВСЕГДА, если у функции есть аргументы.</Condition_Use>
+      <Condition_Skip>Если функция не принимает аргументов.</Condition_Skip>
+      <Format mode="required">@param {name} {Одно связное описание: что это и допустимые границы}.</Format>
+      <Format mode="optional">@param [{name}] {Одно связное описание}.</Format>
+    </Tag>
+    <Tag name="@returns" type="functional">
+      <Definition>Бизнес-цель результата: зачем вызывающему нужен результат. Для асинхронных функций описывает значение, которым успешно разрешается Promise.</Definition>
+      <Condition_Use>ВСЕГДА, если функция возвращает значение (не void/never).</Condition_Use>
+      <Condition_Skip>Если функция возвращает void.</Condition_Skip>
+      <Format>@returns {Цель результата для вызывающего}.</Format>
+    </Tag>
+    <Tag name="@pre" type="logic">
+      <Definition>Предпословие. Состояние системы или окружения (не связанное с простой валидацией аргументов), которое ДОЛЖНО быть истинным ДО вызова.</Definition>
+      <Condition_Use>Если есть скрытые требования к окружению или состоянию системы, не дублирующие @param.</Condition_Use>
+      <Condition_Skip>Если дублирует @param или требования только из типов TypeScript.</Condition_Skip>
+      <Format>@pre {Состояние системы/окружения}.</Format>
+    </Tag>
+    <Tag name="@post" type="logic">
+      <Definition>Постусловие. Гарантированное состояние системы ПОСЛЕ успешного выполнения.</Definition>
+      <Condition_Use>Если метод меняет стейт или даёт гарантию, не выраженную в @returns (напр. неизменность аргумента, порядок элементов).</Condition_Use>
+      <Condition_Skip>Если дублирует @returns или @param; для чистых функций без дополнительных гарантий.</Condition_Skip>
+      <Format>@post {Факт об изменении состояния или гарантия}.</Format>
+    </Tag>
+    <Tag name="@invariant" type="logic">
+      <Definition>Условие, которое всегда остается истинным для жизни сущности. Для внешних сервисов описывает SLA, политику обработки ошибок (Error Policy) и стратегию повторных запросов (Retry Policy).</Definition>
+      <Condition_Use>Для Классов/Интерфейсов с состоянием или клиентов внешних систем.</Condition_Use>
+      <Condition_Skip>Для функций-утилит (stateless).</Condition_Skip>
+      <Format>@invariant {Условие целостности или Политика}.</Format>
+    </Tag>
+    <Tag name="@sideEffect" type="critical">
+      <Definition>Любое взаимодействие с внешним миром (IO, Network, Logs, Events , etc).</Definition>
+      <Condition_Use>ВСЕГДА, если метод не является чистой функцией.</Condition_Use>
+      <Condition_Skip>Если метод только вычисляет и возвращает данные.</Condition_Skip>
+      <Format>@sideEffect {Тип действия}: {Описание}.</Format>
+    </Tag>
+    <Tag name="@throws" type="critical">
+      <Definition>Описание исключительной ситуации. Для асинхронных функций описывает причину отклонения (reject) Promise.</Definition>
+      <Condition_Use>Если метод может выбросить ошибку (throw) или вернуть Rejected Promise.</Condition_Use>
+      <Condition_Skip>Если метод гарантированно безопасен (never throws).</Condition_Skip>
+      <Format>@throws {ErrorType | RejectedPromiseReason} {Условие возникновения}.</Format>
+    </Tag>
+    <Tag name="@see" type="linking">
+      <Definition>Ссылка на определение контракта (Interface/Spec/Type), который реализует этот код.</Definition>
+      <Condition_Use>При реализации интерфейса или наследовании, чтобы не дублировать описание.</Condition_Use>
+      <Condition_Skip>Если это первичное определение контракта.</Condition_Skip>
+      <Format>@see {TypeName#method} in path/from/project/root</Format>
+    </Tag>
+    <Tag name="@example" type="optional">
+      <Definition>Пример использования кода.</Definition>
+      <Condition_Use>Если логика вызова неочевидна или требует сложной подготовки данных.</Condition_Use>
+      <Condition_Skip>Для тривиальных методов (get/set).</Condition_Skip>
+      <Format>@example {Code block}</Format>
+    </Tag>
+    <Tag name="@deprecated" type="lifecycle">
+      <Definition>Маркер устаревшего кода.</Definition>
+      <Condition_Use>Если метод планируется к удалению. Обязательно указать альтернативу.</Condition_Use>
+      <Condition_Skip>Для актуального кода.</Condition_Skip>
+      <Format>@deprecated Используй {NewMethod} вместо этого.</Format>
+    </Tag>
+  </Tag_Dictionary>
+  <Usage_Patterns hint="Как применять теги к разным сущностям">
+    <Pattern id="PATTERN_SPECIFICATION_TYPE" appliesTo="type, interface (data)">
+      <Context>Определение типа данных (type) или контракта данных (interface).</Context>
+      <Rule>Данные: type с @purpose; при принадлежности к домену/API — префикс в имени. Логика: pre/post только если не дублируют param/returns.</Rule>
+      <Example>
+        /**
+         * @purpose Описывает элемент каталога внешнего сервиса — идентификатор и дочерние элементы.
+         * @consumer catalog-service, export-module.
+         */
+        export type ApiCatalogItem = { id: string; children: ApiCatalogItem[]; };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_SYSTEM_INTERFACE" appliesTo="interface (service), class (client)">
+      <Context>Интерфейс или Клиент к внешней системе (API, DB, IO). Ненадежная среда.</Context>
+      <Rule>Обязательно: 1. Иерархия ошибок (Base → Network/Auth/Domain). 2. @invariant с описанием Resilience Policy (Retry, Rate Limits, Timeout).</Rule>
+      <Example>
+        /**
+         * @purpose Клиент для работы с платежным шлюзом.
+         * @consumer billing-service
+         * @invariant Error Policy: Все сетевые ошибки оборачиваются в PaymentNetworkError.
+         * @invariant Retry Policy: Идемпотентные методы (GET) повторяются 3 раза с экспоненциальной задержкой.
+         * @invariant Rate Limit: Не более 100 rps (контролируется клиентом).
+         */
+        export interface PaymentGateway { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_IMPLEMENTATION_LINK" appliesTo="const, class, method">
+      <Context>Реализация сущности, которая уже описана во внешнем контракте (implements Interface).</Context>
+      <Rule>Не дублируй логику. Используй @purpose (кратко), @consumer и @see.</Rule>
+      <Example>
+        /**
+         * @purpose Реализация трансформации для мобильных устройств.
+         * @consumer MobileApp
+         * @see {UserTransformer} in features/users/contracts.ts
+         */
+        export const mobileUserTransformer: UserTransformer = (u) => { ... };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_CLASS_METHOD" appliesTo="method">
+      <Context>Метод класса. Если реализует интерфейс — @see. Иначе — полный контракт.</Context>
+      <Example>
+        /**
+         * @purpose Списание средств.
+         * @pre Система должна быть в режиме read-write (не maintenance).
+         * @param amount Сумма к списанию (положительное число).
+         * @throws {NoFundsError} Если баланс недостаточен.
+         */
+        public pay(amount: number): void { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_FUNCTION_PARAM_RETURNS" appliesTo="function">
+      <Context>Стандартная функция. @param не дублирует поля типа.</Context>
+      <Example good="@param id Идентификатор сущности (непустая строка или положительное число). @returns Данные для отображения в UI или передачи в следующий слой."/>
+      <Example bad="@param id Смысл: идентификатор. Валидность: непустая строка. @returns UserDto с заполненными полями."/>
+    </Pattern>
+    <Pattern id="PATTERN_EXPORTED_CONSTANT" appliesTo="const">
+      <Context>Публичные константы, особенно объекты конфигурации.</Context>
+      <Rule>Опиши @purpose (зачем этот конфиг) и @invariant (ограничения значений).</Rule>
+      <Example>
+        /**
+         * @purpose Глобальные настройки ретраев для HTTP.
+         * @invariant maxRetries должно быть меньше 5.
+         */
+        export const RETRY_CONFIG = { ... };
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_ASYNC_FUNCTION" appliesTo="function, method">
+      <Context>Асинхронная функция, возвращающая Promise.</Context>
+      <Rule>@returns описывает значение при успешном resolve. @throws описывает причину (Error) при reject.</Rule>
+      <Example>
+        /**
+         * @purpose Загружает данные пользователя с сервера.
+         * @param userId ID пользователя для загрузки (UUIDv4).
+         * @throws {UserNotFoundError} Если пользователь с таким ID не найден.
+         * @returns {Promise<ApiUser>} Данные пользователя для внутреннего использования в системе.
+         * @sideEffect Network: GET-запрос к /api/users/{userId}
+         */
+        export async function fetchUser(userId: string): Promise<ApiUser> { ... }
+      </Example>
+    </Pattern>
+    <Pattern id="PATTERN_GENERIC_FUNCTION" appliesTo="function, method">
+      <Context>Обобщенная (generic) функция с параметризованными типами.</Context>
+      <Rule>В @param и @returns следует описать роль обобщенного типа T.</Rule>
+      <Example>
+        /**
+         * @purpose Оборачивает любые входные данные в стандартизированный объект ответа.
+         * @param data Данные любого типа {T}, которые будут помещены в поле `payload`.
+         * @returns {ApiResponse<T>} Стандартизированный объект ответа, содержащий исходные данные.
+         */
+        export function wrapInApiResponse<T>(data: T): ApiResponse<T> { ... }
+      </Example>
+    </Pattern>
+  </Usage_Patterns>
+  <Validation_Checklist hint="Критерии качества контракта">
+    <Check>Экспортируемая сущность: есть @purpose; для корневых типов и публичного API — @consumer при необходимости.</Check>
+    <Check>Класс/модуль с состоянием: есть @invariant.</Check>
+    <Check>Внешний сервис (Client/Interface): определен @invariant с иерархией ошибок и Retry Policy.</Check>
+    <Check>@param — одно связное описание. Для объектов описание полей не дублируется из типа.</Check>
+    <Check>@returns — бизнес-цель результата для вызывающего, а не перечисление типа.</Check>
+    <Check>Порядок тегов соблюдён: purpose → consumer → invariant → pre → param → throws → returns → post → sideEffect.</Check>
+    <Check>@pre и @post не дублируют @param/@returns; только если добавляют новую информацию.</Check>
+    <Check>Метод с побочными эффектами: есть @post или @sideEffect.</Check>
+    <Check>Реализация внешнего типа: есть @see с путем от корня.</Check>
+    <Check>Структуры данных объявлены через type; interface только при наследовании/реализации.</Check>
+    <Check>Типы внешнего домена/API имеют префикс в имени.</Check>
+    <Check>Асинхронность: @returns описывает успех, @throws — ошибку (reject).</Check>
+  </Validation_Checklist>
+</JSDOC_AS_CONTACTS>

package/dist/chunks/devtools-B-7ugZhF.js

@@ -0,0 +1,79 @@
+import { g as l } from "./services-CaLOhuLV.js";
+var n, s;
+function u() {
+  return s || (s = 1, n = function() {
+    throw new Error(
+      "ws does not work in the browser. Browser clients must use the native WebSocket object"
+    );
+  }), n;
+}
+var c = u();
+const i = /* @__PURE__ */ l(c), t = globalThis;
+t.WebSocket ||= i;
+t.window ||= globalThis;
+t.self ||= globalThis;
+t.window.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = [
+  {
+    // ComponentFilterElementType
+    type: 1,
+    // ElementTypeHostComponent
+    value: 7,
+    isEnabled: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalApp",
+    isEnabled: !0,
+    isValid: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalAppContext",
+    isEnabled: !0,
+    isValid: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStdoutContext",
+    isEnabled: !0,
+    isValid: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStderrContext",
+    isEnabled: !0,
+    isValid: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalStdinContext",
+    isEnabled: !0,
+    isValid: !0
+  },
+  {
+    // ComponentFilterDisplayName
+    type: 2,
+    value: "InternalFocusContext",
+    isEnabled: !0,
+    isValid: !0
+  }
+];
+const a = {}, d = async () => new Promise((r) => {
+  const e = new i("ws://localhost:8097"), o = setTimeout(() => {
+    e.terminate(), r(!1);
+  }, 2e3);
+  o.unref(), e.on("open", () => {
+    clearTimeout(o), e.terminate(), r(!0);
+  }), e.on("error", () => {
+    clearTimeout(o), e.terminate(), r(!1);
+  });
+});
+await d() ? (a.initialize(), a.connectToDevTools()) : console.warn(`DEV is set to true, but the React DevTools server is not running. Start it with:
+
+$ npx react-devtools
+`);

package/dist/chunks/{help.cmd-CWasx25o.js → help.cmd-B_G7EWzF.js}

@@ -5,7 +5,6 @@ console.info("  npx gennady [command] [options]");
 console.info("");
 console.info("Commands:");
 console.info("  commit            Generate commit message from staged changes");
-console.info("  review            Review staged changes for critical issues");
 console.info("  cat               Display file contents as XML or Markdown");
 console.info("  agent             Run AI agent request");
 console.info("  vcs-reply         Post replies to GitLab MR discussions from stdin");
@@ -16,9 +15,17 @@ console.info(
 console.info(
   "  resolve-conflicts Build confidence-aware merge-conflict resolution prompt from active git merge"
 );
+console.info("  remote-console    Mirror browser console output into local stdout");
+console.info("  lint              Validate TypeScript files: file header, DBC contracts, anchors");
+console.info("  alt-opinion       Get alternative opinions from AI models with optional synthesis");
+console.info(
+  "  sync              Synchronize ai/directives/ from npm package into current project"
+);
+console.info(
+  "  agent-mon         Interactive terminal dashboard for monitoring active AI agent sessions"
+);
 console.info("");
 console.info("Examples:");
 console.info("  npx gennady");
 console.info("  npx gennady commit");
-console.info("  npx gennady review --branch=develop");
 console.info('  npx gennady cat "./src/**/*.js" --output=md');

package/dist/chunks/{index-B63fYXL2.js → index-BeL1Zcbg.js}

@@ -1,4 +1,4 @@
-import { p as s, r as e } from "./run-review-command.logic-a_M3CkeZ.js";
+import { p as s, r as e } from "./run-review-command.logic-DpkRoEi8.js";
 const r = s(process.argv), o = await e({
   mode: "issues",
   args: r