Module dev 

Супервизор light dev: горячая перезагрузка приложения с восстановлением состояния. Горячая перезагрузка приложения Light: супервизор light dev.

Запускает приложение (копию из target/hot-run/) как дочерний процесс, следит за исходниками (src/, templates/, Cargo.toml). Две реакции:

• HTML (файлы *.html) → команда RELOAD_TEMPLATE через TCP-сервер DevTools на порту 9229: приложение перечитывает HTML-шаблон с диска и перерисовывает UI без пересборки. При неудачной отправки (app умер, порт недоступен — os error 10061) не триггерим полную пересборку: ждём до 3 с (poll каждые 200 мс), пока TCP снова станет доступен, и повторяем RELOAD_TEMPLATE.
• Source (файлы *.rs / Cargo.toml) → полная пересборка + рестарт: сохраняем состояние (SAVE_STATE), убиваем процесс, перезапускаем.

Race-защита: во время initial build (окно is_starting) изменения не приводят к немедленным действиям — они накапливаются в pending_html / pending_source. После закрытия окна (порт 9229 открылся либо прошёл дедлайн STARTUP_IGNORE) накопленное применяется с приоритетом Source > Html (пересборка важнее reload). HTML-чнейдж во время initial build не приводит к пустому restart — это ReloadHtml после старта.

Надёжный мониторинг файлов использует notify::PollWatcher — периодическое опросование файловой системы, которое работает на любых ФС, включая UNC и сетевые диски, где нативный watcher (recommended_watcher) события не ловит. Дебаунс (100 мс для HTML, 500 мс для Source) координирует отдельный поток, чтобы кратковременные серии событий не запускали много перезагрузок.

Structs

DevArgs

Разобранные параметры команды light dev.

RebuildStateMachine

State-machine: решение о реакции на результат фоновой сборки.

WatchState

Живое состояние наблюдателя: окно игнорирования при сборке/старте (is_starting) и накопленные изменения, которые нужно применить сразу после сброса окна. HTML (runtime-reload) и Source (пересборка) разделяются отдельными флагами: HTML-чнейдж во время initial build не должен приводить к полному рестарту приложения.

Enums

ChangeKind

Тип изменения файла для классификации hot-reload.

RebuildOutcome

Результат одной фоновой сборки.

WatchAction

Результат обработки одного события наблюдателя: тип реакции (или её отсутствие), либо сигнал, что накопленное изменение требует применения.

Functions

bin_name

Имя бинарника пакета: имя пакета без изменений (cargo не заменяет -).

build_info_path

Путь файла информации о версии фреймворка, от которой зависит hot-build.

check_cli_version_mismatch

Предупреждение при рассинхроне между установленным CLI и версией light-fw-core в проекте (сравнение по major.minor).

classify_change

Классифицирует путь изменённого файла в ChangeKind.

clean_dev_cache

Удаляет всё, что нужно для полного сброса кэша dev-сборки (ТЗ 0.14.4): target/hot-build, target/hot-run, .light/state.json, .light/build-info.json и артефакты зависимостей текущего пакета из target/debug/deps/ (только <package>*). Возвращает список удаляемых путей (для логирования и теста).

cleanup_run_dir

Удаляет все .exe в run_dir, кроме активного (keep). Ошибки молча игнорируются: файл мог быть ещё жив в AV-кэше.

copy_fresh_to_run

Копирует свежий бинарник из <build_target>/debug/ в <run_dir>/<bin>-<ts>.exe. Создаёт run_dir, если её нет. Возвращает путь к копии.

detect_package_from_cwd

Определяет имя пакета, в котором находится пользователь: поднимается вверх от cwd, ищет ближайший Cargo.toml с [package].name; если не найден — использует cargo metadata --no-deps (одиночный пакет → его имя, workspace-член → член, чей manifest_path ближе всего к cwd).

file_hash

Хэш содержимого файла (u64) для дедупликации событий notify.

fresh_bin_path

Свежий артефакт после cargo build --target-dir <build_target>: <build_target>/debug/<package>.exe (Windows) / .exec-без (unix).

handle_watch_event

Логика обработки одного события наблюдателя с учётом состояния WatchState. Отделена от потоков, чтобы юнит-тестить без запуска процесса и файлового watcher’а.

kill_child

Убивает дочерний процесс и дожидается его завершения.

parse_dev_command

Чистый разбор сырых аргументов командной строки в DevArgs.

prune_stale_run_exes

Убирает из run_dir устаревшие копии исполняемых файлов:

read_fw_core_version_from_lock

Текущая версия light-fw-core в Cargo.lock проекта. Читаем Cargo.lock напрямую (без запуска cargo metadata): файл маленький, а cargo metadata иногда долго и может не сработать без сети.

read_fw_core_version_from_workspace_toml

Текущая версия фреймворка в проекте. Порядок:

request_reload_template

Отправляет команду RELOAD_TEMPLATE\n в TCP-сервер DevTools на 127.0.0.1:<port> и закрывает соединение. Приложение перечитывает HTML-шаблон с диска и перерисовывает UI без пересборки. Ошибки не являются фатальными — просто проигнорируются.

request_reload_template_with_retry

Пытается отправить RELOAD_TEMPLATE; при неудаче (app умер, порт недоступен) ждёт до [RELOAD_WAIT_MAX], пока TCP снова станет доступен (poll каждые [RELOAD_POLL_INTERVAL]), и повторяет отправку. Не триггерит полную пересборку: HTML-чнейдж — это runtime-reload, не rebuild.

request_save_state

Отправляет команду SAVE_STATE\n в TCP-сервер DevTools на 127.0.0.1:<port> и закрывает соединение. Ошибки (сервер не запущен, порт занят) не являются фатальными — просто проигнорируются.

resolve_package_root

Определяет корень пакета, который запускает light dev.

resolve_startup_completion

Решает, какое действие применить при закрытии окна is_starting (порт DevTools открылся либо прошёл дедлайн STARTUP_IGNORE). Приоритет: Source (полная пересборка) > Html (runtime-reload) > None.

resolve_workspace_root

Определяет корень воркспейса через cargo metadata --no-deps.

run

Точка входа команды light dev: запускает дочерний процесс и цикл наблюдения. Возвращает код завершения приложения (не anyhow, чтобы ядро CLI не тягло зависимость, которой нет в его манифесте).

run_exe_path

Копия свежего бинарника в target/hot-run/, от которой и запускается приложение: <run_dir>/<bin>-<ts>.exe. Timestamp (as_millis) делает имя уникальным на каждый swap; старые копии чистятся cleanup_run_dir.

save_build_info

Читает и парсит build-info.json. Повреждённый файл — None (перезапишется), отсутствующий файл — None (первая сборка: кэш не инвалидируется, просто фиксируем текущую версию). Ошибки записи игнорируются: при неудаче запись кэш не сломает, но следующая сборка будет повторять попытку записи.

state_file_path

Путь файла состояния относительно root (по умолчанию .light/state.json; переопределяется переменной окружения LIGHT_STATE_FILE).

wait_port_available

Ожидает восстановления TCP-доступа к порту port в течение max (poll каждые interval). Возвращает true, если порт принял соединение, иначе false. Используется для повторной отправки RELOAD_TEMPLATE после неудачного (например, app умер) — без полной пересборки.

watch_paths

Строит список путей для наблюдения: src/ и templates/ (только если существуют) плюс Cargo.toml (если есть).

window_file_path

Путь файла геометрии окна относительно root (по умолчанию .light/window.json; переопределяется LIGHT_WINDOW_FILE). Совпадает с путём, который читает/пишет окно приложения (light-fw-core::window).