Самопроверяющийся скрипт первого запуска: bootstrap, doctor и smoke-тест

Цель

Новичок или агент после клонирования запускает одну команду и получает рабочую среду либо точный список того, чего не хватает и как это исправить; при повторном запуске команда сообщает, что делать нечего.

Предварительные условия

Список потребностей проекта: среды выполнения и их версии, менеджеры пакетов, системные библиотеки, сервисы (база данных, кеш), учётные данные и их источники, а для каждого пункта — проверка, доказывающая его наличие. Паттерн GitHub «Scripts To Rule Them All» задаёт разделение, которому следует методика: script/bootstrap используется только для обеспечения зависимостей проекта, script/setup приводит проект в исходное состояние после клонирования, script/update запускается после pull, а script/test выполняет набор тестов. Образец для проверяющей части — команда Homebrew doctor, описанная в руководстве как проверка системы на потенциальные проблемы с ненулевым кодом завершения при их обнаружении.

Шаги

1. Сначала напишите doctor: проверку без изменений, которая выводит по строке на требование — PASS, FAIL или WARN, найденное значение, ожидаемое значение и команду исправления. Она ничего не меняет и завершается ненулевым кодом при любом FAIL.
2. Напишите bootstrap как последовательность идемпотентных шагов, каждый под защитой соответствующей проверки doctor: устанавливайте только недостающее, берите версии из манифеста версий репозитория, пропускайте уже корректное.
3. Завершите bootstrap запуском doctor, а затем smoke-тестом: самой быстрой тестовой целью, --help собранного исполняемого файла или запросом к локальной конечной точке проверки работоспособности. Код завершения скрипта — код завершения smoke-теста.
4. Сделайте каждый шаг неинтерактивным: запросы ввода блокируют агентов и CI. Читайте учётные данные из переменных окружения или документированного файла, а об их отсутствии сообщайте FAIL со ссылкой, не запросом ввода.
5. Выведите, что сделано и сколько времени потребовалось; запишите то же в журнал, который при неудачном запуске можно приложить к отчёту об ошибке.
6. Запускайте bootstrap по расписанию в CI с чистой машины или контейнера; скрипт настройки, который запускают только новички, устаревает между их приходами.
7. Считайте каждую неудачу новичка ошибкой в doctor: если ни одна проверка её не выявила, добавьте проверку до исправления среды.

Ожидаемый результат

Ошибки настройки становятся конкретными («ожидался PostgreSQL 16, найден 14; выполните указанную команду обновления») вместо трассировки стека от первой команды, которой понадобился недостающий компонент.

Ограничения и основание проверки

Цена — охват платформ: для каждой поддерживаемой операционной системы нужно сопровождать проверки и исправления. Скрипт не может проверить то, чего не наблюдает (VPN, разрешение, выданное в другом месте), а только установить, что проба не прошла. Это предлагаемый протокол; результаты внедрения или замеры времени не заявляются.