Один репозиторий объединяет React-интерфейс, Express API, durable snapshots,
immutable-релизы и многоуровневый desktop/mobile/security quality gate.
Зачем этот проект
Manacost Arena превращает разрозненные игровые данные в один быстрый рабочий
экран: перед драфтом можно проверить лидирующие классы и карты, во время игры —
открыть нужный тир-лист, а для Полей Сражений — перейти к героям, библиотеке или
конструктору стратегии. Редакционные мета-отчёты находятся рядом со статистикой,
поэтому контекст не теряется между несколькими сервисами.
- Актуальные данные: классы, карты и легендарные группы, источник и время
обновления, durable snapshots при сбое upstream.
- Игровые инструменты: герои, BG-библиотека, конструкторы, поиск, фильтры,
mobile lightbox, профиль, статьи, гайды и конкурсы.
- Production-контур: immutable releases, автоматический rollback, security
contracts, encrypted backup, desktop/mobile E2E и zero-axe gate.
О проекте
Manacost Arena объединяет актуальную статистику, редакционные материалы и
инструменты подготовки к игре. На одном сайте доступны тир-листы карт и
классов Арены, группы легендарок, герои и библиотека Полей Сражений,
конструкторы стратегий, статьи, гайды и персональный профиль.
Интерфейс построен вокруг визуального языка Hearthstone: пергамент, дерево,
красные тавернные поверхности и аккуратный фиолетовый акцент #4A2F66.
Desktop и mobile проходят один и тот же набор функциональных, адаптивных и
accessibility-проверок перед каждым релизом.
Интерфейс в деталях
Скриншоты снимаются прямо с production в desktop и mobile viewport. Их можно
воспроизвести одной командой:
npm run docs:screenshots
Что внутри
| Арена | Поля Сражений | Платформа |
|---|
| Винрейты классов | Герои и их профили | Статьи и мета-отчёты |
| Тир-листы карт | Библиотека и архив | Архив гайдов и галерея |
| Группы легендарок | Тир-листы меты | Telegram/Boosty-профиль |
| Матчапы и аналитика | Конструкторы стратегий | Редакционная admin-панель |
| Скины, монеты и питомцы | Галереи и игровые медиа | Storybook + MCP |
Интерфейс работает от 320 px, проходит 200% reflow и forced-colors
проверку. Клавиатурная навигация, scroll lock модальных окон и
axe-аудит входят в обязательный release gate.
Архитектура
Инженерное имя репозитория — HearthPulse, канонический production-домен —
hearthpulse.net; Manacost Arena остаётся названием публичного интерфейса.
AI-агентам и новым участникам следует начинать с компактной
карты проекта, а затем переходить к
указанному в ней владельцу модуля и источнику истины.
Browser
│
├── Next.js 16 App Router (apps/public-web) + React 19 + TypeScript
│ ├── server-rendered metadata and public data
│ ├── client pages from src/modules and legacy src/features
│ └── responsive Hearthstone UI
│
└── /api/*
├── Express API (compiled TypeScript)
├── signed authentication and CSRF boundary
├── Redis-assisted caches and durable snapshots
├── isolated scraper publication
└── health, readiness, freshness and metrics contracts
Nginx → immutable release → systemd service
│
├── atomic switch and automatic rollback
└── encrypted backup and restore drills
Основные каталоги:
apps/public-web/ Next.js-приложение: все публичные HTML-страницы
src/components/ общие UI-компоненты
src/modules/ новые доменные модули с узкими public-контрактами
src/features/ legacy-страницы на поэтапной миграции, не целевая граница
src/styles/ общие токены и ограниченные shared-стили
server/app/ application wiring и lifecycle-композиция
server/modules/ каталогизированные backend-домены
server/index.ts текущая server-композиция и legacy-регистрации
scripts/ QA, бюджеты, релизы, мониторинг и recovery
tests/ unit, contract, security и deployment tests
deploy/ systemd units и инфраструктурные шаблоны
public/ локальные игровые и декоративные ассеты
docs/screenshots/ актуальные изображения для GitHub
Качество и безопасность
Каждое изменение проходит единый обязательный gate:
npm run verify:ci
Он включает:
- TypeScript typecheck и архитектурные ограничения;
- пять автоматически обнаруживаемых suite: unit, integration, contract,
browser и production-smoke;
- HTTP contract, auth, CSRF, backup и deployment tests внутри этих suite;
- production-сборку frontend и server;
- бюджеты JavaScript/CSS и контроль роста
!important;
- desktop/mobile E2E с mocked-подпиской;
- axe accessibility audit, 200% reflow, keyboard и modal scroll-lock;
- проверку документации и дизайн-системы.
Отдельные GitHub-проверки защищают цепочку поставки и репозиторий:
- CodeQL и Semgrep ищут уязвимые потоки данных и небезопасные конструкции;
- Gitleaks проверяет полную Git-историю и рабочее дерево на секреты;
- Dependabot, OSV-Scanner и Dependency Review контролируют lockfile,
новые зависимости, известные уязвимости, лицензии и здоровье пакетов;
- Trivy блокирует
HIGH/CRITICAL уязвимости и ошибки конфигурации;
- OpenSSF Scorecard оценивает security posture репозитория;
- Sentry опционально собирает очищенные от PII frontend/server ошибки.
После выкладки production дополнительно проверяется командами:
node scripts/production-monitor.mjs
npm run observe:production
npm run qa:e2e
observe:production открывает все зарегистрированные публичные страницы и
проверяет в реальном Chromium, что ключевые страницы действительно показывают
данные, форму входа или ожидаемый paywall. Структурированные отчёты и безопасный
авторизованный профиль описаны в
production observer runbook.
Подробные SLO, stop-the-line правила и текущий прогресс находятся в
STABILIZATION.md.
Стек и инструменты
| Контур | Используемые инструменты |
|---|
| Интерфейс | Next.js 16 (App Router), React 19, TypeScript с измеряемым долгом и strict islands, Tailwind CSS 4, Lucide, responsive CSS |
| API и данные | Node.js 22, Express, Redis, SQLite, Sharp, Puppeteer Core, node-cron, Hearthstone deckstrings |
| Тестирование | Node test runner, tsx, fast-check, Storybook 10 + MCP, Puppeteer E2E, axe-core, browser contract tests |
| Качество кода | TypeScript, React Doctor, Knip, markdownlint, design.md, архитектурные и bundle-budget проверки |
| AppSec | CodeQL, Semgrep CE, Gitleaks, Trivy, GitHub Private Vulnerability Reporting |
| Supply chain | Dependabot, OSV-Scanner, Dependency Review, npm audit, OpenSSF Scorecard |
| Наблюдаемость | Sentry React/Node SDK, Sentry MCP, Chrome DevTools MCP, readiness/metrics, production monitor и browser observer |
| Delivery | GitHub Actions, immutable artifacts, Nginx, systemd, atomic symlink switch, rollback и encrypted backups |
| Контекст команды | Задание пользователя, документация и визуальные референсы в репозитории, Codex/Claude post-push review |
Все security Actions закреплены полными commit SHA, а чувствительные интеграции
остаются выключенными без явной серверной конфигурации. Подробности и команды
для AI-агентов собраны в docs/agent-tooling.md.
Production scraper импортирует puppeteer-core из dependencies и запускает
явно найденный системный Chromium 151. Полный puppeteer остаётся в
devDependencies только для browser QA. Оба пакета закреплены на одной версии,
а release smoke выполняет настоящий npm ci --omit=dev, импортирует собранный
scraper и открывает локальную страницу в headless Chrome. Такой split сохраняет
production runtime без повторного скачивания браузера при каждом новом lockfile.
Быстрый старт
Требуются Node.js 22.12+, npm и Chromium/Google Chrome для browser QA и scraper.
git clone https://github.com/Manacost-Labs/HeartPulse.git
cd HeartPulse
npm ci
cp .env.example .env
npm run dev
Сайт доступен на http://localhost:3000: команда запускает API (порт 3001),
Next.js в dev-режиме (порт 4320) и локальный шлюз, который раздаёт страницы,
/api и статику из public/ так же, как Nginx в продакшене. Без внешних
ключей используются локальные snapshots; интеграции и публикация свежих данных
требуют соответствующих переменных из .env.example.
Для разработки и AI-проверки компонентов отдельно запустите:
npm run storybook
Storybook доступен на http://127.0.0.1:6006, а его локальный MCP endpoint —
на http://127.0.0.1:6006/mcp. Статическая проверка всех stories:
npm run test:storybook
npm run build-storybook
Полезные команды:
| Команда | Назначение |
|---|
npm run dev | API, Next.js и локальный шлюз на http://localhost:3000 в watch-режиме |
npm run dev:next | Только Next.js-приложение в dev-режиме (см. apps/public-web/README.md) |
npm run build | Статический корень dist/ и серверная сборка build/ |
npm run build:next | Production-сборка Next.js |
npm test | Все пять автоматически обнаруживаемых suite без ручного списка |
npm run test:discovery | Полнота классификации всех test/spec-файлов |
npm run architecture:baseline | Детерминированный архитектурный baseline |
npm run architecture:map | Карта модулей, legacy-зон и владельцев |
npm run architecture:impact -- <file> | Контракт, зависимости и тесты файла |
npm run architecture:owner -- <method> <route> | Владелец frontend/API route |
npm run test:module -- <module> | Минимальный проверенный набор тестов модуля |
npm run architecture:http-manifest | Проверка Express routes и middleware |
npm run qa:e2e | Полный desktop/mobile browser QA |
npm run qa:ci | Сборка и browser QA против Next.js с QA-бэкендом (деплой-гейт) |
npm run budget:next | Контроль размеров JS и CSS каждой публичной страницы Next.js (бюджеты) |
npm run agent:integrate | READY → PR → auto-merge через merge queue (runbook) |
npm run ci:flake-report | Красные прогоны ci.yml, flaky-тесты и длительность по событиям () |
Production-релиз
Production использует immutable-артефакты, атомарное переключение symlink,
readiness gate и автоматический rollback. Краткий ручной сценарий:
sudo -u koloda npm run verify:ci
sha=$(git rev-parse HEAD)
artifact="/tmp/hs-arena-release-$sha"
npm run release:create -- --output="$artifact" --sha="$sha"
sudo scripts/deploy-release.sh "$artifact"
Полная инструкция, включая recovery, encrypted backup и off-site replication,
находится в DEPLOYMENT.md.
Участие в проекте
Ошибки и идеи принимаются через
структурированные GitHub Issues.
Перед pull request прочитайте CONTRIBUTING.md и выполните
npm run verify:ci. Уязвимости нужно отправлять только через
приватный security advisory.
История пользовательских изменений ведётся в CHANGELOG.md; новые
записи — по одному файлу в changelog.d/, они
собираются в журнал при релизе.
Дизайн-система
assets.md содержит цветовые токены, типографику, CSS-рецепты рам,
правила mobile-декора и полный каталог production URL всех ассетов. Документ
можно использовать как переносимый контракт при интеграции дизайна в другой
проект.
Источники и права
Статистика агрегируется из игровых и аналитических источников, указанных в
интерфейсе рядом с соответствующими наборами данных. Hearthstone и связанные
изображения принадлежат Blizzard Entertainment. Репозиторий не является
официальным продуктом Blizzard.
Исходный код является проприетарным. Копирование, публикация, модификация,
использование в другом продукте и создание производных работ запрещены без
предварительного письменного разрешения Manacost. Полные условия находятся в
LICENSE. По вопросам проекта:
Manacost в Telegram.
Сделано командой Manacost для русскоязычного сообщества Hearthstone.
