Design System Builder

Монорепозиторий DS Builder объединяет текущую JavaScript/TypeScript реализацию и новую Kotlin-архитектуру.

Структура

• backend-kt/ — Kotlin backend services, Gateway, build/deploy tooling и component preview contract.
• frontend-kt/ — Kotlin Multiplatform frontend tooling и CLI dsbuilder.
• js/ — существующие React-приложения и Node.js-сервисы.
• openspec/ — архитектурные ADR, спецификации и история изменений.

Agent skills и команды OpenSpec находятся в корневых .agents/, .claude/, .cursor/ и .gigacode/.

Инструменты агентской разработки

Процесс разработки использует OpenSpec, репозиторный agent skill и Strictacode. Репозиторий проверен со следующими версиями:

• OpenSpec 1.6.0;
• Strictacode 0.0.12.

Установите OpenSpec глобально через npm:

npm install --global @fission-ai/openspec@1.6.0

Strictacode устанавливается изолированно через pipx:

brew install pipx
pipx ensurepath
pipx install strictacode==0.0.12

Версия Strictacode также записана в tools/strictacode-requirements.txt. Проверьте установку:

openspec --version
strictacode --help
openspec validate --all --strict --no-interactive

Agent workflow

Главный агент Codex или Claude Code работает непосредственно в checkout разработчика: реализует утверждённый OpenSpec Change, запускает проверки и создаёт свежего read-only reviewer через нативный механизм своей среды.

Полный процесс описан в .agents/workflows/dsbuilder-development.md. Codex использует репозиторный skill dsbuilder-task-workflow, для Claude Code доступен тонкий адаптер в .claude/skills.

Git branch и OpenSpec Change имеют независимые имена. Для веток и worktree используйте:

tools/task create <branch-name> [--worktree] [--base <ref>]
tools/task list
tools/task cleanup <branch-name>

Реализация остаётся незакоммиченной до human review. Основные gate:

tools/verify fast --change <change-name>
tools/verify full --change <change-name>
tools/verify audit --all

Конфигурация контуров и protected paths находится в .verification/config, а версионированные Strictacode baseline — в .verification/strictacode-baseline. Локальное состояние длинной задачи можно хранить в игнорируемом .agent-workflow/<change-name>/state.md; Git diff и OpenSpec всегда имеют над ним приоритет.

Gradle в sandbox Codex

Gradle записывает wrapper distributions, зависимости, metadata и lock-файлы в GRADLE_USER_HOME. Sandbox Codex не разрешает запись в стандартный ~/.gradle, поэтому можно использовать отдельный общий cache для всех checkout и worktree:

mkdir -p "$HOME/.cache/codex-gradle"

Добавьте абсолютный путь в пользовательский ~/.codex/config.toml. TOML не подставляет $HOME или ~, поэтому замените <username> своим именем:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/Users/<username>/.cache/codex-gradle"]

[shell_environment_policy]
set = { GRADLE_USER_HOME = "/Users/<username>/.cache/codex-gradle" }

Перезапустите Codex после изменения конфигурации. В cache хранится одна скачанная Gradle distribution на версию и общие зависимости; проектные .gradle и build остаются отдельными в каждом worktree.

Основные команды

cd js && npm run build
cd backend-kt && ./gradlew build
cd frontend-kt && ./gradlew build

Production

Backend production stack описан в docker-compose.prod.yml. GitHub Actions вручную собирает десять Kotlin, JavaScript и infrastructure образов, публикует их в GitHub Container Registry (GHCR) и вызывает deploy webhook DEV или PROD resource в Coolify. Compose использует только готовые registry images; исходники на deployment server не собираются.

js/apps/client и js/apps/admin не входят в Docker Compose: их environment-specific статика продолжает публиковаться существующими frontend workflow в S3. Снаружи Coolify публикует только gateway, а внутренние сервисы используют service-name DNS внутри compose network.

cp .env.prod.example .env.prod
./deploy.sh --check
./deploy.sh

DEV resource использует IMAGE_TAG=dev, PROD — mutable alias IMAGE_TAG=release. Настройка GHCR permissions, GitHub Variables/Secrets, tag policy и Coolify resource описана в backend-kt/DEPLOY.md.

Локальный запуск

Для первоначальной настройки и запуска общего локального контура выполните из корня репозитория:

./setup-local.sh

Скрипт сначала поднимает JavaScript-контур без схемы БД, затем запускает Kotlin backend в detached-режиме, а потом наполняет базу и привязывает дизайн-систему base к проекту пользователя. Схему общей базы ds_registry создаёт Flyway в ds-service (V1–V3), Drizzle-миграции в этом контуре не запускаются: иначе схема не совпадёт с baseline Flyway и ds-service остановится с Schema fingerprint mismatch. Порядок нужен ещё и потому, что documentation-service использует JS db-service по адресу host.docker.internal:3008.

По умолчанию локальные данные сохраняются. Чтобы удалить данные обоих контуров (все Docker volumes) и начать с чистой базы, запустите с явной опцией:

./setup-local.sh --reset

Если в ds_registry лежит схема, созданная Drizzle (например, после запуска js/setup-docker.sh без Flyway), скрипт остановится с подсказкой выполнить ./setup-local.sh --reset.

Для сборки Kotlin backend нужен JDK 17. backend-kt/start-local.sh автоматически использует JDK 17 из DSBUILDER_JAVA_HOME, JAVA_HOME, PATH или стандартных системных установок. JetBrains IDE для запуска не требуется. Если JDK установлен в нестандартной директории, укажите её явно:

DSBUILDER_JAVA_HOME=/path/to/jdk-17 ./setup-local.sh

Проверить, какой JDK будет использован, без запуска Docker:

./backend-kt/start-local.sh --check-java

Остановить оба контура:

./setup-local.sh --down

Перед первым запуском при необходимости создайте js/.env:

cp js/.env.example js/.env

Для локального запуска NPM_PACKAGE_SCOPE по умолчанию равен @sddsjs, а NPM_TOKEN не требуется. Токен нужен только для legacy-сценария публикации npm-пакета.

Контуры можно запускать и отдельно:

./js/setup-docker.sh
./backend-kt/start-local.sh --detach

Проверка API через Scalar

Локальный API Reference на базе Scalar объединяет публичные контракты Authentication, Projects, Design systems и Documentation. Он отправляет запросы через Gateway, поэтому пути и авторизация соответствуют реальному клиентскому API, а не внутренним адресам микросервисов.

Сначала поднимите локальный контур, затем в отдельном терминале выполните:

./backend-kt/scripts/start-api-reference.sh

Откройте http://127.0.0.1:8090. Для другого порта передайте --port <port>. При необходимости Dev и Production gateway добавляются только при явной передаче DS_API_REFERENCE_DEV_GATEWAY и DS_API_REFERENCE_PROD_GATEWAY перед запуском скрипта.

Базовый сценарий проверки project-scoped API:

1. В источнике Projects откройте List available projects for the actor и нажмите Test Request.
2. В блоке Authentication выберите GatewayOAuth, укажите учётные данные локального пользователя и нажмите Authorize. Затем отправьте запрос и сохраните id нужного проекта из ответа.
3. В верхней панели самой страницы API Reference укажите этот идентификатор в поле Project ID и нажмите Apply. Значение сохраняется только в local storage браузера и подставляется во все Design systems и Documentation запросы.
4. Откройте требуемую операцию в Design systems или Documentation, при необходимости авторизуйте этот источник через его GatewayOAuth, и выполните Test Request.

Не используйте кнопку внешнего Scalar API Client: локальная страница уже содержит Project ID и отправляет запросы через настроенный gateway. Нажмите Clear рядом с Project ID, чтобы удалить выбранный проект из браузера.

Backend E2E

Сквозные backend-сценарии используют обычный общий локальный контур из setup-local.sh, обращаются к нему через публичный Gateway с реальной авторизацией и при необходимости вызывают JVM CLI dsbuilder:

./tools/e2e all
./tools/e2e api-project-access
./tools/e2e cli-auth-session

E2E запускает разработчик, CI или главный агент как внешнюю проверку до архивирования OpenSpec Change. Структура сценариев и правила тестовых данных описаны в e2e/README.md.

js/setup-docker.sh выполняет полную подготовку JS dev-контура: пересоздаёт его Docker volumes (отключается DSBUILDER_RESET_VOLUMES=0), собирает контейнеры, запускает миграции и seed базы, а затем поднимает Node.js-сервисы, client и admin. Поэтому при таком запуске по умолчанию локальные данные JS-базы будут сброшены. Автономный запуск подходит только для JS-контура: общий контур поднимайте через ./setup-local.sh, где схему создаёт ds-service (DS_SCHEMA_MIGRATION_OWNER=flyway, затем ./setup-docker.sh --seed-only).