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 не входит в 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

На Windows используйте PowerShell и Docker Desktop в режиме Linux-контейнеров:

.\setup-local.ps1

Для запуска Windows-контура нужны Docker Desktop и доступ к образам и зависимостям сборки. JDK, Node.js, Bash и WSL на Windows-хосте не требуются: backend собирается в Linux-контейнерах, а существующие bootstrap-base.sh, publish-compose-plugin.sh и seed-local-design-system.sh выполняются во вспомогательном Linux-контейнере. PowerShell-сценарий управляет Docker и настраивает Keycloak через HTTP API. Его опции соответствуют Bash-сценарию: -Reset, -Down, -PluginZip, -SkipPlugin, -ComponentsPackage, -ThemePackage, -SkipDesignSystem. Путь к собственному архиву плагина или пакету компонентов можно также задать через COMPOSE_PREVIEW_PLUGIN_ZIP и COMPOSE_COMPONENTS_PACKAGE.

Скрипт запускает Kotlin backend в detached-режиме, наполняет дизайн-систему base и поднимает клиент. База ds_registry живёт в стеке backend-kt (сервис ds-db, хостовый порт 5433, переопределяется DS_DB_PORT), её схему создаёт Flyway в ds-service; Drizzle-миграции не запускаются. Наполнение делает backend-kt/bootstrap-base.sh только через Gateway: находит или создаёт проект пользователя admin@example.com, заливает глобальный слой web-компонентов (dsbuilder components import-api по web-api-meta.json из js/cli), создаёт дизайн-систему base с темой base_default; версию он не публикует, base остаётся черновиком. Токены, их значения, палитру и компоненты темы ds-service заводит сам из своих ресурсов. Для bootstrap нужны JVM-дистрибутив CLI (frontend-kt/gradlew :cli:installJvmDist, собирается автоматически) и установленные зависимости js/cli (cd js/cli && npm ci) для генерации web-api-meta.json; готовый файл можно передать через DSBUILDER_WEB_API_META.

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

./setup-local.sh --reset

Для сборки Kotlin backend через setup-local.sh на macOS/Linux нужен 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 JS-контуром не используется: сервиса публикации npm-пакета в нём больше нет.

Kotlin backend можно запускать и отдельно, а наполнить базу повторным bootstrap:

./backend-kt/start-local.sh --detach
./backend-kt/bootstrap-base.sh

Клиент отдельно: docker compose -f js/docker-compose.dev.yml up -d --build client или npm run dev в js/apps/client.

Проверка 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.

JavaScript-часть репозитория — это клиент и локальный генератор (js/cli); Node.js-сервисов в ней нет. Общий контур поднимайте через ./setup-local.sh: база ds-db и наполнение base принадлежат стеку backend-kt.