@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/guides/commits.md

@@ -0,0 +1,166 @@
+# Коммиты и ветки — Triplex-Next
+
+---
+
+## Именование веток
+
+**Формат:** `TRIPLEX-XXX-короткое-описание`
+
+- Строчные буквы, слова через дефис.
+- Всегда начинается с номера тикета.
+
+```text
+TRIPLEX-844-ai-ready-design-system
+TRIPLEX-901-add-badge-component
+TRIPLEX-912-fix-button-focus-style
+```
+
+**Исключения:**
+- Релизная ветка: `prepare-release-XX` (например, `prepare-release-2`)
+- Перелитие main → release-0: выполняется мейнтейнерами, формат произвольный
+
+---
+
+## Структура веток и релизов
+
+| Ветка | React | Версии пакета | Описание |
+|---|---|---|---|
+| `main` | React 18 | `1.xx` | Основная ветка разработки |
+| `release-0` | React 17 | `0.xx` | Поддержка React 17, синхронизируется с main |
+
+**Правило:** все фича-ветки создаются от `main`. Изменения попадают в `release-0` через перелитие — вручную мейнтейнерами. Агент не должен создавать ветки от `release-0` и не должен мерджить в неё напрямую.
+
+---
+
+## Формат коммитов
+
+**Формат:** `TRIPLEX-XXX Краткое описание`
+
+```text
+TRIPLEX-844 Добавить AI-Ready документацию для компонентов
+TRIPLEX-901 Добавить компонент Badge с темами и размерами
+TRIPLEX-912 Исправить стиль фокуса для Button в теме Link
+```
+
+Если нужно уточнение — добавляй через двоеточие:
+
+```text
+TRIPLEX-844 AI-Ready Design System: фундамент и пилот Button
+TRIPLEX-901 Badge: добавить тему DANGER и размер SM
+```
+
+**Правила:**
+- Все коммиты в ветке начинаются с одного номера тикета.
+- Первая строка — не длиннее 72 символов.
+- Тело коммита опционально (для сложных изменений).
+- Язык: русский или английский — не смешивать в одном коммите.
+
+---
+
+## Когда запускать линтер
+
+**Вручную запускать не нужно.** Линтер запускается автоматически при `git commit`:
+
+1. `husky` перехватывает коммит.
+2. `lint-staged` запускает на staged-файлах:
+   - `eslint --fix` — автоисправление ESLint-ошибок
+   - `prettier --write` — форматирование кода
+3. Исправленные файлы добавляются обратно в staging.
+
+**Если `lint-staged` упал:**
+- Прочитай ошибку — это ESLint-нарушение, которое нельзя автофиксировать.
+- Исправь вручную.
+- Пере-stage: `git add <files>`.
+- Повтори коммит.
+
+**Ручной запуск (если нужно проверить до коммита):**
+```bash
+npx eslint --fix src/components/Button/Button.tsx
+npx prettier --write src/components/Button/Button.tsx
+```
+
+---
+
+## Что не коммитить
+
+| Файл/папка | Причина |
+|---|---|
+| `__screenshots__/` | Только из Docker/CI. Если нужно — подтвердить в pre-commit hook |
+| `.mcp.json` | Персональный токен Figma — в `.gitignore` |
+| `.env.local` | Секреты — в `.gitignore` |
+| `node_modules/`, `dist/`, `storybook-static/` | В `.gitignore` |
+
+Если в ходе работы появились новые локальные, временные, генерируемые или
+машино-специфичные файлы:
+- проверь `git status`, не попали ли они в untracked/staged
+- если такие файлы не должны храниться в репозитории, добавь подходящее правило в `.gitignore`
+- не коммить подобные файлы "на всякий случай"
+
+---
+
+## Когда коммитить и пушить
+
+**Агент не создаёт коммиты самостоятельно.** После завершения задачи — остановиться и показать результат разработчику. Коммит делается только по явной просьбе.
+
+**Агент не пушит ветку самостоятельно.** Пуш — только по явной просьбе разработчика.
+
+---
+
+## PR-воркфлоу
+
+**Агент пушит ветку — разработчик создаёт PR.**
+
+```bash
+git push -u origin TRIPLEX-XXX-feature-name
+```
+
+После пуша разработчик сам открывает PR через GitHub UI или `gh pr create`.
+
+**Исключение:** если разработчик явно просит агента создать PR, используй:
+
+```bash
+gh pr create \
+  --title "TRIPLEX-XXX Краткое описание" \
+  --body "## Что сделано\n- ...\n\n## Как проверить\n- ..."
+```
+
+---
+
+## Release notes
+
+При добавлении или изменении публичного поведения компонента — обнови файл release notes текущей версии:
+
+```
+stories/release-notes/v1/<текущая версия>.mdx
+```
+
+**Что писать:**
+
+- Новый prop: «Добавлено свойство `X` для ...»
+- Изменение поведения: «Изменён/Исправлен ...»
+- Удалённый prop (breaking change): выноси в секцию `<Heading>Ломающие изменения</Heading>`
+
+**Формат записи:**
+
+```mdx
+**ComponentName**
+
+- Добавлено свойство `propName` для описания.
+```
+
+Компоненты внутри секции — в алфавитном порядке.
+
+Не нужно добавлять release notes для:
+- изменений только в stories/тестах/документации
+- рефакторинга без изменения публичного API
+
+---
+
+## Чек-лист перед пушем
+
+- [ ] Линтер проходит (автоматически при коммите)
+- [ ] Unit-тесты проходят: `npm run test-unit`
+- [ ] Нет случайно добавленных файлов (`git status`)
+- [ ] Для новых локальных/временных/генерируемых файлов проверено, не нужно ли добавить правило в `.gitignore`
+- [ ] Нет скриншотов из macOS в `__screenshots__/`
+- [ ] Release notes обновлены (если изменился публичный API компонента)

package/bundle/guides/context.md

@@ -0,0 +1,277 @@
+# Triplex-Next: Контекст для AI-агентов
+
+Этот файл — главная точка входа в контекст дизайн-системы для любого AI-агента.
+Читай его полностью перед тем, как вносить изменения в компоненты.
+
+---
+
+## Что такое Triplex-Next
+
+React-библиотека компонентов дизайн-системы.
+Пакет: `@sberbusiness/triplex-next`.
+Основная линия разработки: `main` → v1.x на React 18 + TypeScript strict.
+Поддерживаемая legacy-линия: `release-0` → v0.x на React 17, синхронизируется мейнтейнерами.
+
+**Основной сценарий работы агента:** добавить новый prop или вариант к существующему компоненту по описанию и/или макету из Figma.
+
+---
+
+## Стек
+
+| Слой | Технология |
+|---|---|
+| Компоненты | React 18/17, TypeScript 5 (strict) |
+| Стили | LESS CSS Modules (`.module.less`) |
+| Дизайн-токены | CSS-переменные, генерируются в `src/generated/` |
+| Сборка | Vite, ES-модули only |
+| Документация | Storybook 9 |
+| Unit-тесты | Vitest + Testing Library |
+| Visual regression | Storybook test-runner + jest-image-snapshot |
+| E2E | Playwright |
+
+---
+
+## Структура компонента
+
+Каждый компонент живёт в `src/components/{ComponentName}/` и обычно содержит:
+
+```
+src/components/Button/
+├── Button.tsx                 # Основной компонент
+├── ButtonBase.tsx             # Базовый элемент (опционально)
+├── ButtonIcon.tsx             # Субкомпонент (опционально)
+├── enums.ts                   # Enum'ы, специфичные для компонента
+├── index.ts                   # Barrel export — ОБЯЗАТЕЛЕН
+├── types.ts                   # Часто есть, если типы вынесены отдельно
+├── styles/
+│   ├── Button.module.less     # Базовые стили
+│   └── ButtonGeneral.module.less  # Стили по теме/варианту
+├── __tests__/
+│   └── Button.test.tsx        # Unit-тесты
+└── Button-AI.md               # Документация для AI-агентов (если компонент уже задокументирован)
+```
+
+Истории (stories) хранятся отдельно. В репозитории встречаются как flat-path файлы
+(`stories/Badge.stories.tsx`), так и сгруппированные (`stories/Buttons/Button.stories.tsx`).
+Для новых или существенно переписанных stories используй modern pattern из
+`docs/ai/stories-guide.md`.
+
+---
+
+## Соглашения по именованию
+
+| Сущность | Префикс | Пример |
+|---|---|---|
+| Интерфейс | `I` | `IButtonGeneralProps` |
+| Union type | `T` | `TButtonProps` |
+| Enum | `E` | `EButtonTheme` |
+| Enum в файле | `enums.ts` в папке компонента | `Button/enums.ts` |
+| LESS класс | camelCase | `styles.secondaryLight` |
+
+---
+
+## Дизайн-токены (CSS-переменные)
+
+Паттерн именования:
+```
+--triplex-next-{Component}-{Variant}_{Property}_{State}
+```
+
+Примеры:
+```
+--triplex-next-Button-General_Background_Default
+--triplex-next-Button-General_Color_Hover
+--triplex-next-Button-Secondary_Shadow_Focus
+--triplex-next-Button-Danger_Background_Disabled
+```
+
+**Состояния:** `Default`, `Hover`, `Active`, `Focus`, `Disabled`
+**Свойства:** `Background`, `Color`, `Shadow`, `Border`
+
+Токены генерируются в `src/generated/themesCssVariables.css`. Не редактируй этот файл вручную.
+
+Если добавляешь новое визуальное состояние — нужен новый токен. Имя токена согласуй с дизайнером в Figma.
+
+---
+
+## Документация конвенций
+
+Детальные правила вынесены в отдельные файлы:
+
+| Тема | Файл |
+|---|---|
+| Codestyle (TypeScript, React, LESS, принципы) | `docs/ai/codestyle.md` |
+| Тестирование (unit, visual, e2e) | `docs/ai/tests.md` |
+| Stories (структура, примеры, чек-лист) | `docs/ai/stories-guide.md` |
+| Коммиты, ветки, PR-воркфлоу | `docs/ai/commits.md` |
+
+`docs/ai/codestyle.md` — краткий канонический список обязательных правил.
+Если формулировки в entrypoint-файлах расходятся, ориентируйся на него и на
+профильный подробный гайд.
+
+---
+
+## Приоритет источников
+
+Если инструкции расходятся, ориентируйся на них в таком порядке:
+
+1. `src/components/{ComponentName}/{ComponentName}-AI.md` для конкретного компонента, если файл существует
+2. `docs/ai/codestyle.md`
+3. Профильный подробный гайд по зоне изменений (`codestyle.md`, `tests.md`, `stories-guide.md`, `commits.md`)
+4. Этот файл (`docs/ai/CONTEXT.md`)
+5. Локальный паттерн исходников компонента, stories и тестов
+
+Не предполагай, что у каждого компонента уже есть AI-документация. Если файла
+`{ComponentName}-AI.md` нет, ориентируйся на код, stories, тесты и общие правила
+репозитория.
+
+---
+
+## Как добавить новый prop к существующему компоненту
+
+### 1. Определи, в каком интерфейсе добавлять
+
+- Если prop нужен только для одной темы — добавь в соответствующий интерфейс (`IButtonGeneralProps`)
+- Если для всех тем — добавь в каждый интерфейс темы и в базовый интерфейс
+- Обнови union type (`TButtonProps`) при необходимости
+
+### 2. Добавь prop в TypeScript-интерфейс
+
+```typescript
+export interface IButtonGeneralProps extends IButtonBaseProps {
+    theme: EButtonTheme.GENERAL;
+    size: EComponentSize;
+    // ... existing props
+    newProp?: string; // добавь JSDoc если поведение нетривиально
+}
+```
+
+### 3. Используй prop в компоненте
+
+```typescript
+// Деструктурируй из пропсов:
+const { theme, size, newProp, className, ...rest } = props;
+
+// Применяй через clsx:
+<button
+    className={clsx(styles.button, styles[size], { [styles.newVariant]: newProp === 'variant' }, className)}
+    {...rest}
+>
+```
+
+### 4. Добавь стили в LESS-модуль
+
+```less
+// В Button.module.less или в новый файл для варианта:
+.button {
+    &.newVariant {
+        // используй существующие CSS-переменные или новые токены
+        background: var(--triplex-next-Button-General_Background_NewVariant);
+    }
+}
+```
+
+### 5. Обнови Storybook story
+
+В существующем story-файле компонента:
+- Добавь prop в `args` и `argTypes` Playground-стори
+- Если prop имеет визуальные варианты — добавь named story (`Sizes`, `Themes` и т.д.)
+- Если story уже использует `examples/` + `?raw`, сохрани этот modern pattern
+- Если story legacy, не рефакторь весь файл только ради миграции структуры без отдельной задачи
+- Подробно: `docs/ai/stories-guide.md` → раздел "Что обновлять при добавлении нового prop"
+
+### 6. Обнови тесты
+
+В `src/components/{ComponentName}/__tests__/{ComponentName}.test.tsx`:
+- Добавь тест-кейс на рендеринг нового prop
+- Проверь CSS-класс, атрибут или текст
+- Следуй существующему паттерну тестов в файле
+
+---
+
+## Инварианты — что НЕЛЬЗЯ менять без обсуждения
+
+1. **`forwardRef`** — обязателен на всех компонентах. Не убирай.
+2. **Публичный API** — имена props, их типы, enum-значения. Это breaking change → мажорная версия.
+3. **`index.ts` barrel exports** — всё, что было экспортировано, должно остаться экспортированным.
+4. **CSS-переменные токенов** — переименование ломает темизацию у потребителей библиотеки.
+5. **Имена LESS-классов**, которые могут использоваться снаружи — согласуй перед изменением.
+6. **Корневой DOM-элемент, ref-target и accessibility-контракт** публичного компонента — не менять без причины и проверки.
+7. **Story ids**, на которые опираются e2e/visual тесты, не переименовывать без синхронного обновления тестов.
+
+---
+
+## Как читать существующий код
+
+**Стили:** LESS-классы импортируются как объект `styles`:
+```typescript
+import styles from './styles/Button.module.less';
+// Использование:
+className={styles.button}
+className={clsx(styles.button, styles.general, { [styles.loading]: loading })}
+```
+
+**Утилиты:**
+- `clsx` — объединение className с условиями
+- `React.useId()` — уникальные ID для aria-атрибутов (предпочтительно в React 18, корректно работает с SSR)
+- `lodash-es/uniqueId` — генерация уникальных ID вне компонентного контекста (когда `useId` недоступен)
+
+**Паттерн миграции:**
+- В репозитории сосуществуют legacy и modern stories/tests.
+- Для небольших правок следуй локальному паттерну файла.
+- Для новых компонентов и больших переписок используй modern conventions из `stories-guide.md` и `tests.md`.
+
+**Стандартные зависимости компонентов:**
+- `src/enums/EComponentSize` — размеры SM | MD | LG (общий для всех компонентов)
+- `src/components/Loader` — спиннер загрузки
+
+---
+
+## Figma и MCP
+
+Не у каждого компонента уже есть `{ComponentName}-AI.md`. Если компонент
+задокументирован, Figma-метаданные лежат в frontmatter этого файла.
+
+Формат frontmatter:
+- `figma-node` — значение параметра `node-id` из URL Figma (например, `1-328`)
+- `figma-file` — URL файла / design-ссылка на Figma-файл
+
+Если в вашем окружении настроен Figma MCP или другой интеграционный инструмент:
+1. Возьми `figma-node` из frontmatter компонента
+2. Возьми `figma-file` из frontmatter компонента, если инструменту нужен file key или URL
+3. Используй их для получения дизайн-спецификации
+4. Сравни с текущим кодом и внеси нужные изменения
+
+Если Figma-метаданные для компонента отсутствуют, не выдумывай их: попроси
+ссылку у разработчика или работай по текстовому описанию/скриншоту.
+
+Настройка MCP: см. `docs/ai/ROADMAP.md` → секция "Figma MCP Setup".
+
+---
+
+## Минимальная проверка перед завершением задачи
+
+- Правки документации и конфигов: проверь ссылки, команды, примеры кода и согласованность между файлами.
+- Правки компонентов и логики: запусти `npx tsc --noEmit` для проверки типов затронутых файлов и по возможности запусти focused unit test, если затронуто публичное поведение.
+- Правки stories с визуальным эффектом: проверь, что состояние покрыто существующей story или новой `Visual tests` story.
+- Правки accessibility, focus management, keyboard navigation и overlay-поведения: добавь или обнови точечный автотест, если это уместно.
+- Если релевантная проверка не запускалась, явно сообщи об этом в финальном отчёте.
+
+---
+
+## Навигация по документации компонентов
+
+Если компонент уже задокументирован, его AI-документация лежит в:
+`src/components/{ComponentName}/{ComponentName}-AI.md`
+
+Пример: `src/components/Button/Button-AI.md`
+
+Шаблон для новых компонентов: `docs/ai/template-AI.md`
+
+---
+
+## Внешние ресурсы
+
+- Документация для разработчиков и дизайнеров: https://triplex-design.ru/next/ru/Web/Components
+- Storybook (локально): `npm run storybook` → http://localhost:6006
+- Истории: `stories/` в корне репозитория