ss-tools/AGENTS.md

ss-tools

Development Environment

• Рабочий виртуальный окружение (.venv) находится внутри backend/: backend/.venv.

Тестовый стенд и запуск

Прямой локальный стенд: run.sh

Основной способ запуска тестового стенда для разработки — из корня репозитория:

./run.sh --skip-install

run.sh запускает три процесса и завершает их по Ctrl+C:

Сервис	Порт по умолчанию	URL
Backend / FastAPI	8000	http://127.0.0.1:8000
Frontend / Vite	5173	http://127.0.0.1:5173
Gradio agent	7860	http://127.0.0.1:7860

После запуска backend готовность можно проверить через http://127.0.0.1:8000/api/ready, а API-документация доступна на http://127.0.0.1:8000/docs. run.sh сам не ждет frontend или agent healthcheck после запуска, поэтому первое открытие UI может потребовать несколько секунд.

При старте скрипт:

1. Проверяет python3 >= 3.9 и npm.
2. Загружает backend/.env до database preflight.
3. Берет URL БД из DATABASE_URL либо использует локальный PostgreSQL: postgresql+psycopg2://postgres:postgres@localhost:5432/ss_tools.
4. Для недоступного локального PostgreSQL пытается выполнить docker compose up -d db и ждет доступность порта до 20 секунд.
5. Генерирует и сохраняет отсутствующие или некорректные ENCRYPTION_KEY и AUTH_SECRET_KEY в backend/.env.
6. Перед запуском Uvicorn выполняет alembic upgrade head; существующую схему без alembic_version схема создаётся единственным alembic upgrade head.
7. Загружает backend/.env также в backend и agent. SERVICE_JWT, если не задан, получает случайное значение на текущий запуск; при запуске сервисов в отдельных терминалах его нужно задать одинаковым явно.

Опции и переменные run.sh:

./run.sh --help
./run.sh --skip-install
DEV_MODE=true ./run.sh --skip-install
BACKEND_PORT=8001 FRONTEND_PORT=5174 AGENT_PORT=7861 ./run.sh --skip-install

• DEV_MODE=true включает uvicorn --reload --reload-dir src и watchfiles для agent.
• Без --skip-install скрипт создает backend/.venv, устанавливает backend/requirements.txt, shared и frontend dependencies.
• AGENT_CONFIRM_TOOLS по умолчанию true.
• Backend и agent читают LLM-конфигурацию через /api/agent/llm-config; провайдеры обычно настраиваются в Admin -> LLM Settings.

Docker Compose стенд

Для полного контейнерного стенда использовать build.sh, а не смешивать его с прямым run.sh:

./build.sh up current
./build.sh status
./build.sh logs current
./build.sh down current

Профили build.sh:

• current (по умолчанию): docker-compose.yml, project superset-tools-current;
• master: docker-compose.yml, project superset-tools-master;
• enterprise-clean: docker-compose.enterprise-clean.yml, внешний PostgreSQL и корпоративные сертификаты.

Для профилей current/master переменные берутся из .env.current/.env.master. Ключевые host ports профиля current: PostgreSQL 5433, backend 8101, frontend 8100, agent 7860; для master: PostgreSQL 5432, backend 8001, frontend 8000, agent 7860. Секреты AUTH_SECRET_KEY, ENCRYPTION_KEY и SERVICE_JWT должны быть заданы явно в Docker-профиле. Не использовать публичные значения из example-файлов.

Изолированный Playwright E2E стенд

E2E запускается отдельным compose-файлом и не должен использовать тот же проект/порты, что и текущий локальный стенд:

docker compose --env-file .env.e2e -f docker-compose.e2e.yml up -d --build
cd frontend && npm run test:e2e
docker compose --env-file .env.e2e -f docker-compose.e2e.yml down -v

Профиль по умолчанию использует PostgreSQL 5435, backend 8103, frontend 8102 и Playwright runner на образе mcr.microsoft.com/playwright:v1.52.0-noble. Для E2E нужны AUTH_SECRET_KEY, E2E_USERNAME, E2E_PASSWORD; GITEA_TOKEN нужен только тестам, которые обращаются к Gitea.

Тестовые команды

Перед backend-командами:

cd backend
source .venv/bin/activate

Основные проверки:

python -m pytest -v                         # unit/service tests; integration skipped
python -m pytest -v --run-integration       # включая Docker/Testcontainers integration
python -m ruff check .
python -m compileall -q src
alembic heads
alembic upgrade head

Для спеки 044:

python -m pytest -q \
  tests/services/dashboard_testing/registry/test_scenario_*.py \
  tests/api/test_scenario_runs_api.py \
  tests/api/test_scenario_automation_api.py \
  tests/api/test_scenario_analytics_api.py
python -m ruff check \
  src/services/dashboard_testing/execution \
  src/api/routes/dashboard_testing/scenario_runs.py
cd ..
source backend/.venv/bin/activate
python specs/044-dashboard-scenario-execution/prototype/validate_static.py

Frontend:

cd frontend
npm run test -- --run
npm run lint
npm run build

Важные ограничения:

• Integration tests пропускаются без --run-integration.
• Реальные alembic check/upgrade требуют доступный PostgreSQL и корректный DATABASE_URL; SQLite не заменяет проверку production migration chain.
• run.sh может автоматически создать локальный backend/.env и секреты; не коммитить этот файл и не переносить его секреты в Docker/E2E конфигурацию.
• Если используется docker compose, переменная SERVICE_JWT обязательна для backend и agent; Compose намеренно завершается без нее.

AXIOM doc-gen

Генерация документации (Doxygen/JSDoc) из семантических контрактов выполняется CLI-бинарём doc-gen из Rust-проекта axiom-mcp (соседняя директория ../axiom-mcp).

# 1. Собрать бинарник (один раз)
cargo build --release --bin doc-gen --manifest-path ../axiom-mcp/Cargo.toml

# 2. Фрактальный граф: модули → функции (карты + Doxygen HTML)
make docs-nav
# эквивалент:
../axiom-mcp/target/release/doc-gen \
  --workspace-root /home/busya/dev/ss-tools \
  --nav docs/api/nav \
  --html docs/api/html

Как ходить по графу:

1. Модули — docs/api/nav/root.map (или HTML mainpage). Не читать функции с корня.
2. Функции — docs/api/nav/<Module>.map секция @FUNCTIONS, либо Doxygen group → \ingroup страница функции.

Примечания:

• --workspace-root передавать абсолютным путём (относительный путь ломает проверку safe_join при записи в DuckDB).
• make docs-doxygen — отдельный XML/HTML extract из исходных комментариев в docs/api/build.
• Навигационный граф агента — doc-gen --nav/--html, не плоский список axiom_*.html.
• Остальные опции: doc-gen --help (--filter, --group-cap, --body-lines).

Agent prompts and skills

.agents/skills/ is the canonical source for semantic skills. The Kilo runtime loads the generated copy from .kilo/skills/; after changing a skill, run:

./scripts/sync-skills.sh

Do not edit .kilo/skills/ directly. Agent prompts follow the same source/runtime split: canonical prompts are in .agents/agents/ and the Kilo-loaded copies are in .kilo/agents/.