Node.js 24 LTS, npm 11; устанавливайте актуальный безопасный patch в этой линии. Зависимости инструментов зафиксированы точными версиями и package-lock.json. Воспроизводимая установка: npm ci. Корень — npm workspace; отдельные lock-файлы внутри пакетов не создаются.
TypeScript 5.9.3 выбран как проверяемая совместимая базовая версия с текущими инструментами lint. Обновление major TypeScript выполняется отдельно с проверкой совместимости parser, линтера и сборки, а не автоматически по latest.
npm run gate -- quick выполняется локально и в GitHub Actions на Linux и Windows. PostgreSQL, браузер и аудит зависимостей — обязательные отдельные задания CI. Основной репозиторий — ProAnima/Arkvory. Workflow: .github/workflows/check.yml; общий реестр: config/gates.json.
Проект Ian Panaev под брендом ProAnimaStudio распространяется бесплатно с открытым для чтения кодом, но без права распространять форки (LICENSE.md, модель лицензирования). Сообщения, предложения и pull request лицензиар может использовать, менять и публиковать без ограничений (раздел 5 лицензии); отправляя их, вы подтверждаете своё право на них.
Все изменения вносятся через pull request из отдельной ветки; прямые коммиты в main не допускаются. Слияние выполняется только после зелёного CI и явного подтверждения владельца проекта.
Работа начинается с небольшого вертикального сценария из roadmap. Не реализуйте все будущие интерфейсы и классы заранее. Пустой index.ts заменяется реальными публичными экспортами при появлении кода. Порты размещаются в application, предметные инварианты — в domain, I/O — в адаптерах.
Между пакетами используйте имя @proanima/arkvory-<package> и публичный экспорт. В manifests объявляйте реальные workspace-зависимости. Runtime exports указывают на dist/index.js и .d.ts; условие arkvory-source используется только tooling. npm run build собирает workspaces в порядке зависимостей. CI проверяет сборку и тесты из чистого checkout.
Для Node.js используется ESM/NodeNext; относительные импорты исходников указывают ожидаемое расширение .js. Browser SDK/UI получают отдельное DOM-окружение. Domain/application/contracts не получают Node.js globals.
- Формат:
npm run format, затемnpm run check. - Правила домена — быстрые тесты без БД и сети.
- Адаптеры — интеграционные проверки с реальными зависимостями.
- API/SDK/CLI — контрактные сценарии, включая ошибки и авторизацию.
- Передачи — проверка backpressure, отмены, повторов, памяти и частичных отказов.
- Перед merge запускайте
npm run gate -- verify, перед выпуском —npm run gate -- release. Отдельные наборы тоже запускаются через gate. Нельзя подменять их skip, only, todo или успешным выходом при отсутствии инфраструктуры. - Результаты значимых замеров записывайте с конфигурацией стенда и версией кода. Нет оснований обещать throughput по одному короткому тесту.
Готовность изменения: нужное поведение работает; ошибки обработаны; новые зависимости обоснованы; проверки проходят; документация/схемы актуальны; секретов нет; известные ограничения перечислены. Шаблон описания: CHANGE.md.
Новая библиотека должна решать конкретную задачу. Проверяйте поддержку выбранного Node.js/TypeScript, лицензию и способ обновления. Не выполняйте автоматический audit fix --force и массовые major-обновления в рамках функциональной задачи.
Переменные окружения читаются и валидируются при запуске composition root; затем передаётся типизированная конфигурация. Нельзя читать process.env посреди доменного сценария. Настройки клиента не содержат серверные ключи.
docs/PROJECT_PLAN.md — продуктовый план; docs/ARCHITECTURE.md — границы реализации; docs/adr — история важных решений. Меняйте документы согласованно. Необходимость архитектурного ADR не означает остановку обычной работы ради дополнительного подтверждения пользователя.
Лимиты 500 строк кода на файл, 300 на класс и 100 на функцию проверяются автоматически. Исключения требуют ADR, owner, срока до 90 дней, регрессионных тестов и поясняющего комментария у декларации. Полные правила, подготовка БД/браузера и расширение наборов: ENGINEERING_GATES.