# forcad-local

Автоматизированный локальный оркестратор для запуска ForcAD + игровых сервисов + чекеров в контейнерах.

Инструмент делает:
- auto-discovery сервисов в переданной папке;
- preflight-проверки структуры сервисов и чекеров;
- containerized сборку checker-артефактов (например `make` для `archive`) без хостовых dev-пакетов;
- auto-cleanup хвостов прошлых запусков перед новым `up`;
- prewarm k3d/k3s образов перед деплоем k3d-сервисов;
- retry для k3d-деплоя и rollback при ошибке (настраивается);
- генерацию runtime-конфига ForcAD без правок исходников борды/сервисов;
- запуск `light` smoke-check `check` для каждого сервиса без полного ForcAD стека;
- опциональный `full` режим с полным ForcAD стеком;
- команды `up`, `down`, `status`, `validate`.

## Требования

- `docker` + `docker compose`
- Python 3.10+
- Для Helm/k3d-профилей сервисов: `helm`, `kubectl`, `k3d` (если требуется конкретному сервису)

## Базовый запуск

```bash
python3 infra/forcad-local/forcad_local.py validate \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers
```

```bash
python3 infra/forcad-local/forcad_local.py up \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers \
  --mode light
```

```bash
python3 infra/forcad-local/forcad_local.py status
```

```bash
python3 infra/forcad-local/forcad_local.py down
```

После `up` борда доступна по `http://127.0.0.1:8080/` (или через `--board-port`).
Это относится только к `--mode full`. В `--mode light` борда не запускается.

## Какие структуры поддерживаются

Для сервиса в `services-root/<service_name>/`:

1. **Compose-профиль**
   - должен быть `docker-compose.yml`
2. **Script/Helm-профиль**
   - `deploy.sh`, либо
   - `redeploy.sh`, либо
   - `deploy/chart/values.yaml` (с возможным `build-docker.sh`)

Для чекера в `checkers-root/<service_name>/`:
- должен быть `checker.py` **или** `*.checker.py`
- если есть `requirements.txt` (или `requirments.txt`) — зависимости автоматически объединяются
- если есть `Makefile` — сборка выполняется внутри builder-контейнера (`cpp-make` профиль по умолчанию)

## Автопроверки (preflight)

Команда `validate` проверяет:
- обнаружены ли сервисы;
- есть ли deploy-профиль;
- есть ли checker entrypoint;
- определён ли host-порт для сервиса;
- нет ли конфликтов портов между сервисами и портом борды;
- наличие системных команд (`docker`, а для helm/k3d-профиля — предупреждения про `helm`, `kubectl`, `k3d`).
- валидность конфигурации containerized checker-build профиля.

## Поведение `up` по умолчанию

- сервисы сортируются в детерминированном порядке (k3d-сервисы сначала);
- перед запуском выполняется auto-cleanup по обнаруженным сервисам;
- для k3d-сервисов заранее выполняется pull базовых образов;
- если k3d-деплой падает, делается retry (`--k3d-retries`);
- в `strict` режиме падение одного сервиса прерывает запуск и откатывает уже поднятые;
- в `best-effort` режимe проблемные сервисы пропускаются.

## Runtime-файлы

Все временные файлы создаются в:
- `infra/forcad-local/.runtime/`

Кэш сборки checker-артефактов:
- `infra/forcad-local/.cache/checker-builds/`

Там же сохраняется `state.json`, который используется командами `status` и `down`.

## Переопределения через manifest

Если auto-discovery не хватает, в `services-root` можно положить файл `forcad-local.json`:

```json
{
  "services": {
    "warehouse": {
      "checker_dir": "warehouse",
      "port": 31443,
      "checker_timeout": 40,
      "checker_type": "pfr",
      "places": 2,
      "profile": "helm_chart",
      "start_cmd": "bash redeploy.sh",
      "stop_cmd": "helm uninstall warehouse -n warehouse",
      "checker_build": {
        "enabled": false
      }
    },
    "archive": {
      "checker_build": {
        "enabled": true,
        "profile": "cpp-make",
        "command": "make",
        "artifacts": ["libgen"]
      }
    }
  }
}
```

Поля опциональны. Используй их, если сервис нестандартный или порт не удаётся вывести автоматически.

## Полезные параметры

- `--service <name>` — выбрать конкретные сервисы (можно повторять)
- `--board-port 8080` — порт борды
- `--mode light|full` — режим работы (`light` по умолчанию)
- `--failure-policy strict|best-effort` — остановиться при первой ошибке или пропускать упавшие сервисы
- `--rollback-on-failure / --no-rollback-on-failure` — откат уже поднятых сервисов при ошибке в strict режиме
- `--auto-cleanup / --no-auto-cleanup` — очистка прошлых запусков перед новым `up`
- `--prewarm-k3d / --no-prewarm-k3d` — предварительный pull k3d/k3s образов
- `--k3d-retries` — число повторов деплоя для k3d-сервисов
- `--k3d-retry-delay` — задержка между retry для k3d
- `--image-pull-retries` — число дополнительных retry на pull docker-образов
- `--image-pull-retry-delay` — задержка между retry pull
- `--team-count 2` — число команд в runtime-конфиге
- `--workers 2` — число celery worker'ов
- `--cache-dir` — путь к кэшу сборки checker-артефактов
- `--no-fast` — не использовать `docker-compose-fast.yml`