# TOOLS — Генераторы Terraform-провайдера Nubes

Каждый инструмент — независимый Go-модуль.

## Канонический пайплайн (порядок шагов)

```bash
# 1) YAML-спеки сервисов из API (per-stand!)
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev

# 2) Go-ресурсы + документация из этих YAML
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev

# 3) (релиз) сборка 3 платформ + публикация в реестр
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev
```

`--profile` обязателен: без него скрипты выходят с кодом 2 (никаких дефолтов).

### Шаг 1 — безопасная генерация YAML

`01_generate_yamls.sh` работает по принципу «сначала во временное, потом атомарная замена»:

- генерация идёт в staging-каталог `generated/<stand>/resources_yaml.staging.<pid>/`;
- рабочий `generated/<stand>/resources_yaml/` **не** удаляется и **не** модифицируется до полного успеха;
- при полном успехе старый каталог уезжает в бэкап `resources_yaml.bak-<UTC>`,
  а staging встаёт на его место (атомарный `mv` в пределах одного FS),
  хранятся последние `KEEP_BACKUPS` (по умолчанию 5);
- при любой ошибке замена **отменяется**: старый каталог цел, частичный результат лежит в staging для разбора, скрипт выходит с кодом 1;
- в каталоге лежит маркер `.stand`, защищающий от генерации не в тот стенд.

Перегенерировать все стенды подряд:

```bash
for s in dev test prod; do
  ./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/$s || break
done
```

> Примечание: часть параметров API отдаёт со случайным `default`-суффиксом
> (`db-ievgpdvu` → `db-ujama5rb` и т.п.), поэтому побайтовое сравнение двух
> прогонов даёт различия в этих строках — это не регрессия.

## yaml-generator

API Nubes → `resources_yaml/*.yaml`

```bash
cd yaml-generator && go build -o ../bin/yaml-generator .
./bin/yaml-generator
```

Структура: `main.go` + `internal/{client,config,normalize,spec,types}`.

## resource-generator

`resources_yaml/*.yaml` → `internal/resources_gen/*.go` + `registry.go`

```bash
cd resource-generator && go build -o ../bin/resource-generator .
./bin/resource-generator
```

Структура: `main.go` + `internal/{helpers,loader,params,templates,types,writers}`.

### Как запускать правильно

Не запускайте `TOOLS/resource-generator/bin/resource-generator` вручную и не полагайтесь на старый бинарник из `TOOLS/resource-generator/bin/`.

Используйте канонический скрипт из корня репозитория, он **всегда** пересобирает генераторы из текущих исходников перед запуском:

```bash
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
```

Для других стендов подставляйте нужный профиль:

```bash
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/prod
```

Это устраняет случайный запуск устаревшего бинаря и гарантирует, что новые `kind` из YAML, включая `modifier`, будут обработаны текущим кодом генератора.

## docs-generator

`resources_yaml/*.yaml` → Markdown-документация в `docs/30_registry/resources/`

```bash
cd docs-generator && go build -o ../bin/docs-generator .

# Документация ресурсов
./bin/docs-generator

# Operations-документация  
./bin/docs-generator --ops
```

Структура: `main.go` + `internal/{types,writers,ops}`.