fgl-aircon/docs/RELEASE_HA.md

# Релиз и установка HA-интеграции

## 1. Внутренняя сборка и установка (Gitea, текущий режим)

Внутренний репозиторий — Gitea (`git.ratigorsk-12.ru`), поэтому:

* HACS к Gitea **не подключается** (только публичный GitHub) — для
  внутреннего использования интеграция ставится копированием
  `custom_components/fglair/` в `<config>/custom_components/`;
* зависимость `pyfglair` публикуется в **PyPI-реестр пакетов Gitea** и
  ставится оттуда.

### 1.1. Сборка и публикация wheel (Gitea Actions, ручной запуск)

Workflow: `.gitea/workflows/publish-pyfglair.yaml` (workflow объявляет
`permissions: contents: read, packages: write`).

Авторизация — любой из вариантов:

* **Встроенный job-токен** (Gitea ≥ 1.27, где `packages` поддержан у
  features): ничего настраивать не нужно, workflow возьмёт
  `${{ secrets.GITEA_TOKEN }}`;
* **Personal access token** со scope `write:package` (для версий, где
  публикация пакетов job-токеном ещё не реализована — см. HACS-док Gitea
  «Package repository authorization»): положите его в секрет
  `PYPI_TOKEN`, при необходимости задайте `PYPI_USER` (имя пользователя к
  PAT; иначе — актор запуска). **Имена секретов не могут начинаться с
  `GITEA_`** — префикс зарезервирован Gitea.

Запуск: Actions → **Publish pyfglair** → Run workflow (вход
`bundled_mbedtls`: `1` — встроить mbedtls, `0` — системный
`libmbedtls-dev`). Собираются **два** wheel одной версии:

* `py3-none-linux_x86_64` — glibc (HA Supervised/Core на Debian/Ubuntu);
* `py3-none-musllinux_1_2_x86_64` — musl (**HA OS**, Alpine-контейнер);
  job `build-musllinux` выполняется в `container: python:3.12-alpine`
  (нужен `container:` у runner'а; иначе см. §1.4).

Артефакты появятся в
`https://git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple/pyfglair/`
(`<owner>` — владелец репозитория, напр. `esphome`). C++-рантайм в .so
встроен (`-static-libstdc++ -static-libgcc`), поэтому wheel зависит только
от libc/libm соответствующей платформы.

Workflow собирает `wheel` + `sdist`, прогоняет smoke-тест установки
(запускается из `/tmp` с `python -P`, чтобы не подхватить исходники
`pyfglair/` вместо wheel) и публикует через `twine upload`. Twine 7 не
поддерживает `--skip-existing` для не-PyPI репозиториев, поэтому workflow
сам проверяет simple-индекс Gitea и пропускает загрузку, если версия уже
опубликована. Для новой версии поднимите `version` в `pyproject.toml`.

### 1.2. Установка pyfglair в Home Assistant

Выбор wheel pip делает сам по платформе: на HA OS (Alpine/musl) — из
musllinux, на HA Supervised/Core (Debian/glibc) — из linux-сборки.

Пакет обязателен (cffi-биндинги). Варианты:

* **Вручную в окружение HA** (проще всего для теста; HA увидит
  установленный дистрибутив и не будет вызывать pip для `pyfglair>=1.0.0`):

  ```sh
  # в контейнере/venv Home Assistant (Advanced SSH & Web Terminal, docker exec и т.п.)
  pip install --index-url https://<user>:<token>@git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple \
      --no-deps pyfglair
  ```

* **Через индекс pip в окружении HA** (`pip.conf`/`PIP_EXTRA_INDEX_URL`):
  тогда HA сам поставит `pyfglair` из манифеста. Учтите риск dependency
  confusion при `--extra-index-url` — для внутреннего стенда допустимо.

Если при добавлении интеграции HA пишет «Invalid handler specified» —
пакет `pyfglair` не установлен (или компонент не перезапущен). Смотрите
`grep -iE "fglair|pyfglair" /config/home-assistant.log`: при
`ModuleNotFoundError: No module named 'pyfglair'` установите пакет в
окружение HA (`docker exec homeassistant python -m pip install ...`) и
полностью перезапустите HA.

* **Публичный PyPI** — см. §2 (для распространения вне сети).

### 1.3. Если HA уже установил glibc-wheel на HA OS

Симптом: `OSError: cannot load library ... Error loading shared library
ld-linux-x86-64.so.2: No such file or directory`. Переустановите пакет с
musllinux-сборкой:

```sh
docker exec homeassistant python -m pip uninstall -y pyfglair
docker exec homeassistant python -m pip install --no-deps --index-url \
    https://<user>:<token>@git.ratigorsk-12.ru/api/packages/<owner>/pypi/simple \
    pyfglair
docker exec homeassistant python -c "import pyfglair; print(pyfglair.__version__)"
docker restart homeassistant
```

### 1.4. Ручная сборка musllinux (если runner без `container:`)

```sh
docker run --rm -v "$PWD":/src -w /src python:3.12-alpine sh -c '
  apk add --no-cache git cmake ninja g++ make curl libstdc++-dev &&
  pip install build &&
  python -m build --wheel'
# dist/pyfglair-<ver>-py3-none-musllinux_1_2_x86_64.whl

pip install twine
python -m twine upload --repository-url \
    https://git.ratigorsk-12.ru/api/packages/<owner>/pypi \
    -u <user> -p <token> dist/*musllinux*.whl
```

### 1.5. Обновление интеграции

`custom_components/fglair/` обновляется из Gitea (git pull / копирование),
затем перезапуск HA. `pyfglair` — переустановкой из пакетов Gitea.

## 2. Публикация pyfglair на PyPI (если понадобится публично)

PyPI (warehouse) принимает только `manylinux*`/`musllinux*` теги, поэтому
локальный `py3-none-linux_x86_64` нужно чинить auditwheel'ом в контейнере
со старой glibc:

```sh
pip install build auditwheel twine

# для каждой архитектуры (linux x86_64/aarch64) в manylinux-контейнере:
python -m build --wheel
auditwheel repair dist/pyfglair-*.whl --plat manylinux2014_x86_64 -w dist/manylinux/
rm -f dist/pyfglair-*-linux_*.whl
python -m build --sdist
twine upload dist/manylinux/* dist/*.tar.gz
```

Проверки: `scripts/py-ci.sh`, `scripts/ci.sh`, `readelf -d` по `.so`
(нет внешней `libmbedcrypto`), установка wheel в чистый venv.

## 3. GitHub-зеркало и Custom Repositories (HACS)

HACS устанавливает интеграции только с публичных **GitHub**-репозиториев
(GitLab/Gitea не поддерживаются:
https://hacs.xyz/docs/faq/other_git_providers/). Публикация в
default-репозиторий HACS не требуется — достаточно Custom Repositories, но
хостинг обязан быть GitHub.

```sh
git remote add github git@github.com:<owner>/fgl-aircon.git
git push --mirror github
```

После зеркала:

* заполнить на GitHub Description, Topics (`home-assistant`, `hacs`,
  `fujitsu`, `air-conditioner`), включить Issues (проверяет HACS Action);
* проверить `codeowners` в manifest (`@petr.polezhaev`; для GitHub нужен
  реальный GitHub-логин);
* обновить `version` манифеста под тег; заменить заглушки
  `screenshots/step-N.png` и `brand/*.png` реальными ассетами;
* создать тег (semver) — HACS покажет версию.

Готовые файлы HACS: `hacs.json`, `info.md`, `LICENSE` (MIT),
`custom_components/fglair/brand/` (icon/icon@2x/logo + dark-варианты),
workflows `.github/workflows/{validate-hacs,hassfest}.yaml`.

## 4. Приёмка на живом стенде

* `tests/acceptance/test_esphome_ha.py quick` — матрица изменений (HA;
  с `--esphome-host` шаги «режим/уставка» идут через ESPHome, проверка — по
  состоянию в HA), возврат к исходному.
* `long --hours 24 --interval 3600 --report acceptance.csv`.
* Сценарии: 503 (два слота), key_error + Repair, offline/восстановление,
  два устройства, options flow (копирование/смена ключа), reconfigure.

## 5. Ограничения стенда

* Реального железа/облака в CI нет: протокол проверен mock-модулем,
  облако — мок-сервером; приёмочный скрипт имеет self-test на моке HA REST.
* Суточный soak, re-key и облачный вход — только на приборе/аккаунте.
* Gitea Actions: встроенный `GITEA_TOKEN` не публикует пакеты (нужен PAT);
  `actions/checkout`/`setup-python` тянутся с github.com (для изолированного
  инстанса используйте абсолютные URL зеркал).