standkit 0.6.0__tar.gz → 0.7.0__tar.gz

{standkit-0.6.0/standkit.egg-info → standkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: standkit
-Version: 0.6.0
+Version: 0.7.0
 Summary: Свободное ядро (MIT) для управления жизненным циклом локальных и удалённых стендов BPMSoft: headless start/stop/restart, health-пробы, логи, реестр стендов. Часть экосистемы BPMkit.
 Author: standkit contributors
 License-Expression: MIT
@@ -58,6 +58,7 @@ Dynamic: license-file
 - **Логи** — просмотр логов текущей сессии стенда, открытие папки логов стенда и папки BPMkit-проекта.
 - **Redis** — очистка кэша стенда (номер БД берётся из конфигурации стенда).
 - **Тёмная и светлая тема** с переключателем.
+- **Встроенная справка** — кнопка «?» в шапке открывает кукбук: установка, работа с дашбордом, удалённые агенты, траблшутинг. Один самодостаточный файл, работает офлайн.
 - **Безопасность по умолчанию** — дашборд слушает только `127.0.0.1`, сессионный токен, защита мутаций (CSRF + проверка Origin).
 - **Удалённые стенды** *(в развитии)* — через лёгкие кроссплатформенные headless-агенты с TLS/mTLS.
 
@@ -116,9 +117,12 @@ TLS, TLS 1.2+/mTLS, скоупы control/readonly, lockout по IP, аудит.
 Нужен Python 3.10+.
 
 ```bash
-pip install "git+https://github.com/thinkquattro/BPMkitStand.git"
+pip install standkit
 ```
 
+Обновление — `pip install -U standkit`. Свежий `main` до релиза (если нужна ещё не выпущенная
+правка) — `pip install --force-reinstall "git+https://github.com/thinkquattro/BPMkitStand.git"`.
+
 Запуск дашборда:
 
 ```bash
@@ -142,6 +146,7 @@ BPMkitStand использует тот же реестр, что и MCP BPMkit
 
 ## Документация проекта
 
+- [standkit_hub/web/cookbook.html](standkit_hub/web/cookbook.html) — **кукбук**: обзор, установка (отдельно Windows и Linux), обновление, дашборд, реестр стендов, виды хостинга, удалённые стенды и агент-демон, безопасность, траблшутинг. Один standalone-файл: в работающем диспетчере открывается кнопкой «?» в шапке, без него — прямо с диска в браузере.
 - [docs/ROADMAP.md](docs/ROADMAP.md) — дорожная карта приложения (что сделано / ближайшее / бэклог).
 - [docs/CHANGELOG.md](docs/CHANGELOG.md) — история изменений по версиям.
 - [docs/BACKLOG.md](docs/BACKLOG.md) — честный список «упомянуто в коде, но не реализовано» (заделы/заглушки) со ссылками на код.

{standkit-0.6.0 → standkit-0.7.0}/README.md

@@ -34,6 +34,7 @@
 - **Логи** — просмотр логов текущей сессии стенда, открытие папки логов стенда и папки BPMkit-проекта.
 - **Redis** — очистка кэша стенда (номер БД берётся из конфигурации стенда).
 - **Тёмная и светлая тема** с переключателем.
+- **Встроенная справка** — кнопка «?» в шапке открывает кукбук: установка, работа с дашбордом, удалённые агенты, траблшутинг. Один самодостаточный файл, работает офлайн.
 - **Безопасность по умолчанию** — дашборд слушает только `127.0.0.1`, сессионный токен, защита мутаций (CSRF + проверка Origin).
 - **Удалённые стенды** *(в развитии)* — через лёгкие кроссплатформенные headless-агенты с TLS/mTLS.
 
@@ -92,9 +93,12 @@ TLS, TLS 1.2+/mTLS, скоупы control/readonly, lockout по IP, аудит.
 Нужен Python 3.10+.
 
 ```bash
-pip install "git+https://github.com/thinkquattro/BPMkitStand.git"
+pip install standkit
 ```
 
+Обновление — `pip install -U standkit`. Свежий `main` до релиза (если нужна ещё не выпущенная
+правка) — `pip install --force-reinstall "git+https://github.com/thinkquattro/BPMkitStand.git"`.
+
 Запуск дашборда:
 
 ```bash
@@ -118,6 +122,7 @@ BPMkitStand использует тот же реестр, что и MCP BPMkit
 
 ## Документация проекта
 
+- [standkit_hub/web/cookbook.html](standkit_hub/web/cookbook.html) — **кукбук**: обзор, установка (отдельно Windows и Linux), обновление, дашборд, реестр стендов, виды хостинга, удалённые стенды и агент-демон, безопасность, траблшутинг. Один standalone-файл: в работающем диспетчере открывается кнопкой «?» в шапке, без него — прямо с диска в браузере.
 - [docs/ROADMAP.md](docs/ROADMAP.md) — дорожная карта приложения (что сделано / ближайшее / бэклог).
 - [docs/CHANGELOG.md](docs/CHANGELOG.md) — история изменений по версиям.
 - [docs/BACKLOG.md](docs/BACKLOG.md) — честный список «упомянуто в коде, но не реализовано» (заделы/заглушки) со ссылками на код.

{standkit-0.6.0 → standkit-0.7.0}/docs/ARCHITECTURE.md

@@ -62,6 +62,14 @@ standkit_hub     — MIT, stdlib-only локальный веб-дашборд (
   ветки для `sys.platform == "win32"` (скрытое консольное окно,
   `CREATE_NO_WINDOW` + отдельная группа процессов) и POSIX
   (`start_new_session=True`, эквивалент `setsid`).
+- Запуск ВНЕШНИХ КОНСОЛЬНЫХ УТИЛИТ (`appcmd`, `sc`, `docker`, `kubectl`,
+  `taskkill`, `tasklist`, `powershell`) — ТОЛЬКО через
+  `standkit/platform.py::run_console`, который на win32 добавляет тот же
+  `CREATE_NO_WINDOW`. Прямой `subprocess.run` в остальных модулях пакета
+  запрещён и стережётся тестом `tests/test_no_window.py`: у родителя без
+  своей консоли (`pythonw`, служба, фоновый поллер хаба) каждый такой вызов
+  рождает на экране мигающее чёрное окно, а из терминала дефект не виден
+  (GAP-138: поллер опрашивал IIS-стенд парой `appcmd` раз в ~12 с).
 - `standkit_agent` — только `stdlib` (`http.server`, `subprocess`, `socket`,
   `urllib`), потому что стенды BPMSoft на .NET штатно живут и под Linux, а
   агент должен разворачиваться на голом хосте без сборки колёс под

standkit-0.7.0/docs/BACKLOG.md

@@ -0,0 +1,112 @@
+# Бэклог standkit / BPMkitStand
+
+Честный список того, что **упомянуто в коде, но ещё не реализовано / не
+настроено** (каркас, заглушки, зарезервированные значения), с точной ссылкой на
+место в коде. Цель — чтобы пользователь пакета и разработчик не принимали
+«задел» за готовую фичу.
+
+Метка **[упомянут в коде]** = в коде есть символ/ветка/поле, но реального
+поведения за ним нет (или оно возвращает заглушку).
+
+Порядок дорожной карты — см. [ROADMAP.md](ROADMAP.md). Остаточная безопасность
+агента — `SECURITY.md` §6.
+
+## Транспорты подключения к стенду
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| Транспорт **`ssh`** | зарезервирован в enum, реализации нет → `NotImplementedError` | `standkit/models.py::Transport.SSH` («задел на будущее»); фолбэк-`raise` в `standkit_hub/client.py::FederatedClient.status/_dispatch_action/logs` |
+| Транспорт **`winrm`** | то же | `standkit/models.py::Transport.WINRM`; там же в `client.py` |
+
+Рабочие транспорты — только `local` и `agent` (оба реализованы; в UI регистрации
+предлагаются только они). `ssh`/`winrm` достижимы лишь ручной правкой
+`projects.json` и упадут с `NotImplementedError`.
+
+## Health-пробы
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| Глубокая проба БД (`SELECT 1` через psycopg2/pyodbc) | заглушка, всегда `SKIPPED`; флаг `deep_db` из хаба не передаётся | `standkit/health.py::db_deep_check`, параметр `check_stand(deep_db=…)` |
+| Глубокая проба Redis (`PING` через redis-py) | заглушка, всегда `SKIPPED` | `standkit/health.py::redis_deep_check`, `check_stand(deep_redis=…)` |
+| `stand_scheme` / `verify_tls` в форме регистрации дашборда | поля есть в реестре и в пробе, но форма регистрации построена по фиксированному белому списку полей — задать схему можно только правкой `projects.json` | `standkit_hub/server.py::_REGISTER_ALLOWED_FIELDS`, `standkit_hub/web/app.js::_REGISTER_FIELD_NAMES` |
+| `last_deploy` (состояние последнего деплоя) | всегда `UNKNOWN`, источник данных не определён, в UI не выводится | `standkit/health.py::check_stand` (комментарий `last_deploy`), `standkit/models.py::StandStatus.last_deploy` |
+
+Рабочие пробы (без заглушек): процесс (pid/бэкенд), HTTP, БД/Redis по **открытому
+TCP-порту** — их достаточно для дашборда.
+
+## Жизненный цикл (kestrel)
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| Polling готовности веб-хоста после `start()` | не реализован (возвращается pid; готовность проверяется отдельно) | `standkit/lifecycle.py` (докстринг модуля) |
+| Блокировка pidfile от гонки двух `start()` | не реализована | там же |
+| Восстановление «потерянного» pidfile | **реализовано** — поиск владельца порта, валидация (порт + allowlist образа + рабочий каталог внутри `stand_dir`) и усыновление с подтверждением | `standkit/adopt.py`, `standkit/lifecycle.py::adopt` |
+| Доп. окружение процесса (`ASPNETCORE_ENVIRONMENT` и т.п.) | «зона расширения следующей итерации» | `standkit/lifecycle.py::_kestrel_start` |
+| Graceful stop (SIGTERM→таймаут→SIGKILL / CTRL_BREAK_EVENT) | **реализовано** — эскалация мягко → таймаут → жёстко | `standkit/platform.py::stop` |
+| Рабочий каталог процесса для WOW64 (32-битный стенд под 64-битным Python) | не реализовано — усыновление таких процессов даёт честный отказ | `standkit/adopt.py::_windows_process_cwd` |
+| Windows Job Object / Linux double-fork | упрощённо (CREATE_NO_WINDOW / setsid) | `standkit/platform.py` (докстринг модуля) |
+
+## Логи
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| Обработка ротации лог-файла в `follow()` | не реализована (при пересоздании файла позиция «уезжает») | `standkit/logs.py::follow` |
+| Постраничное чтение очень больших логов | частично: `tail(max_bytes=…)` читает хвост; полноценной постраничной навигации нет | `standkit/logs.py::tail` |
+
+## Хаб / клиент
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| Параллельный опрос агентов | **реализовано** — `ThreadPoolExecutor`, порядок результатов сохраняет порядок реестра | `standkit_hub/client.py::FederatedClient.status_all` |
+| Кэш/дебаунс частых опросов | **реализовано** — фоновый поллер держит снапшот состояния, конфиг и реестр кэшируются по отпечатку файла | `standkit_hub/poller.py`, `standkit_hub/server.py::build_snapshot` |
+| CLI регистрации стенда (`standkit register …`) | не реализовано: запись в реестр возможна только из UI (`POST /api/stand/register`), правкой `projects.json` руками или `Registry.add_existing()` из Python. На headless-хосте агента UI недоступен (хаб слушает loopback) — обходной рецепт живёт в кукбуке | `standkit/registry.py::Registry.add_existing`, `standkit_hub/server.py` (маршрут регистрации) |
+| Ярлык на рабочем столе для **macOS** | осознанно не реализовано — возвращается понятный статус | `standkit_hub/shortcut.py` (докстринг) |
+| Нативный трей (иконка со сводным состоянием, баллоны при падении) | не реализовано — потребовало бы `pystray`/`Pillow` против инварианта stdlib-only. Вместо него PWA-установка и компактный режим `?view=compact` | `standkit_hub/web/manifest.webmanifest` |
+| Автозапуск хаба при входе в систему | не реализовано; механика ярлыка есть | `standkit_hub/shortcut.py` |
+| Остановка хаба, когда дашборд никто не смотрит (idle-shutdown / heartbeat от фронта) | не реализовано — запущенный ярлыком процесс живёт под `pythonw` без окна до перезагрузки или ручного снятия. Дубли при повторном клике по ярлыку закрыты single-instance проверкой, но сам «вечный» процесс остаётся | `standkit_hub/__main__.py` (`serve_forever` без таймаута), `standkit_hub/server.py::probe_hub_instance` |
+| Остановка хаба из интерфейса (кнопка «Завершить работу диспетчера») | не реализовано — единственный штатный способ Ctrl+C недоступен при запуске ярлыком (консоли нет) | `standkit_hub/__main__.py` (обработка `KeyboardInterrupt`) |
+
+## Секреты
+
+| Пункт | Статус | Упомянут в коде |
+|------|--------|-----------------|
+| CLI-обёртка `set/get/status/rotate/delete` | только программное API; CLI нет. ⚠️ У модуля нет и `__main__`-блока, поэтому `python -m standkit.secrets set <ref>` **молча завершается с rc=0**, ничего не задав (до 18.08.2026 такая команда фигурировала в `docs/REMOTE_STANDS.md` — исправлено). Рабочие пути: `standkit.secrets.set_secret()` из Python, кнопка «Задать секрет…» в дашборде, переменная `STANDKIT_SECRET__<REF>` | `standkit/secrets.py` (комментарий «Бэклог следующих итераций») |
+| Файловый фолбэк `secrets.enc` (машины без keyring) | не реализован | там же |
+
+## Приёмка
+
+| Пункт | Статус |
+|------|--------|
+| **Агент на Linux** | **первая живая установка 18.08.2026** — Ubuntu 24.04 (`BPM-docker-test`), стенд `survey9` в Docker: установка через pipx, регистрация стенда из Python (`Registry.add_existing`), секреты через `STANDKIT_SECRET__*`, служба systemd, проверка API токеном. Вскрыла: жёсткую схему `http://` в HTTP-пробе (строка выше), отсутствие CLI регистрации (строка выше) и набор типовых ошибок оператора (PEP 668, забытый префикс секрета, владелец `agent.env`, `stand_host=0.0.0.0`, чтение реестра только при старте) — всё разобрано в кукбуке |
+| **Docker** бэкенд (одиночный контейнер + compose) | **живая приёмка проведена 17.08.2026** на Docker Engine 29.6.1: 50 проверок основного цикла (start/stop/restart по фактическому `State.StartedAt`, логи, health, идемпотентность, негативы, работа без `docker` в PATH) + 6 проверок граничных состояний (paused, crash-loop, exited, подстрочные имена сервисов, кириллица в логах). Вскрыла два ложных «стенд жив» — исправлены в этой же ветке (см. CHANGELOG) |
+| **k8s** бэкенд | **живая приёмка проведена 17.08.2026** на кластере k3s 1.30 (k3d): 28 проверок — scale/rollout restart с проверкой пересоздания подов, `readyReplicas`, `k8s_replicas`, логи, NodePort-проба, негативы по деплойменту/namespace/контексту/PATH. Вскрыла ложное «жив» при нуле реплик — исправлено |
+| **IIS** бэкенд | **живая приёмка проведена 17.08.2026** на настоящем стенде BPMSoft 1.9.1.2 (.NET Framework + PostgreSQL) в IIS 10 / .NET Framework 4.8: сайт `iis19` (порт 5081) + вложенное приложение `/0` + сайт-сосед на ТОМ ЖЕ пуле; 66 живых проверок (окружение и автодетект 13, жизненный цикл site-scoped 17, `w3wp` 7, логи 4, отсутствие elevation 10 + 4 кросс-платформенных, ручки хаба 6, граничные состояния канала управления 5). Вскрыла 4 дефекта (пул при автодетекте, `state:Unknown`, ложный диагноз «нет прав», логи в подпапках-датах) — исправлены в этой же ветке, см. CHANGELOG |
+| Контур для повторной приёмки k8s | на Windows с **cgroup v1** (проверить: `docker info --format {{.CgroupVersion}}`) Kubernetes ≥1.32 не поднимается — `kind` с `kindest/node:v1.36.1` падает на `kubeadm init`, k3s 1.35 не доходит до CoreDNS. Рабочий вариант — k3d с `--image rancher/k3s:v1.30.6-k3s1`; после создания кластера поправить kubeconfig: k3d прописывает `host.docker.internal`, нужен `kubectl config set-cluster <ctx> --server=https://127.0.0.1:<порт из docker port k3d-<cluster>-serverlb>` |
+
+### Остатки после приёмки 17.08.2026 — закрыты в тот же день
+
+| Пункт | Как закрыт |
+|------|--------|
+| Контейнер в crash-loop | `describe_state` объясняет состояние словами: «контейнер в цикле перезапуска (перезапусков: N)», а у контейнера, пойманного в running-фазе, — «уже перезапускался N раз, возможен цикл падений». Причина уходит в `StandStatus.details['process_reason']`, поэтому витрина показывает диагноз вместо мигающего индикатора. Сам вердикт по-прежнему отражает мгновенное состояние — это честно, контейнер и правда попеременно жив |
+| Контракт `read_logs` при отсутствующем CLI | оба бэкенда возвращают `None`; контракт зафиксирован в докстринге протокола `HostingBackend` |
+| `KubernetesBackend.stop` | бросает `HostingError` с текстом kubectl, как `DockerBackend.stop` |
+| `read_logs` при нескольких репликах (k8s) | чтение по label-селектору (`logs -l ... --prefix`) со всех подов. Отдельно: общий вывод НЕ обрезается хвостом до `n` — `--tail` уже применён kubectl к каждому поду, а хвост принадлежит поду, писавшему последним |
+| `restart` (k8s) не ждёт готовности | после `rollout restart` выполняется `rollout status` (`K8S_ROLLOUT_WAIT_SEC`, по умолчанию 60 с; `0` возвращает прежнее поведение) |
+
+### Открытые остатки
+
+| Пункт | Статус |
+|------|--------|
+| Признак «краш-луп» в самом вердикте | сейчас различить «стенд работает» и «стенд поднялся на секунду между падениями» можно только по тексту `reason`. Возможный шаг — отдельное состояние в витрине (жёлтый вместо зелёного) при `restart_count > 0` и свежем `StartedAt` |
+| Живая приёмка на нескольких узлах | всё проверено на одноузловом кластере: поведение при подах, разъехавшихся по узлам, и при `NodePort` за внешним балансировщиком не проверялось |
+| Усыновление стенда (kestrel) | **живая приёмка проведена** на реальном стенде, поднятом мимо диспетчера: поиск владельца порта, признание своего стенда и отказ для чужого, отсутствие действий без подтверждения, остановка по подтверждению, протухший pidfile. Именно она вскрыла, что на Windows рабочий каталог процесса приходится читать из PEB — путь к стенду не встречается ни в `ExecutablePath`, ни в командной строке |
+| Усыновление стенда (IIS) | **проверено живьём 17.08.2026**: автоопределение сайта по physical path и по биндингу (в т.ч. `%SystemDrive%`-путь и игнор `net.tcp`-биндинга), снятие `w3wp` по пулу с проверкой, что соседний пул не тронут, различение «сайт остановлен / пул остановлен / порт держит http.sys / состояние не выяснено». Именно она вскрыла, что пул при автодетекте не заполнялся (атрибут `APPPOOL.NAME`) |
+| Контур для повторной приёмки IIS | на этом хосте **служба WAS падает** (System log: «Служба активации Windows была неожиданно завершена», W3SVC уходит с кодом 1067) при сценарии «создать новый App Pool + сайт и сразу дать запрос» — воспроизведено 3/3, в т.ч. с отдельным физическим каталогом. Лечится `iisreset /restart` (либо `sc start WAS` + `sc start W3SVC`). Проверки, которым нужен ВТОРОЙ пул, поэтому переиспользуют существующие пул и сайт (`set app <site>/ /applicationPool:DefaultAppPool`), а не создают новые. Побочно этот же контур дал живые примеры транзиентных RPC-сбоев `appcmd` |
+
+## Крупные направления (отдельные ADR)
+
+| Пункт | Статус | ADR |
+|------|--------|-----|
+| Браузинг/скачивание логов удалённых стендов | предложено, не реализовано | [ADR-0003](adr/0003-remote-log-browsing.md) |
+| Остаточная безопасность агента (PKI, ротация токенов, per-stand ACL, CN→scope, ротация аудита, bounded thread pool, chunked) | не реализовано | `SECURITY.md` §6 |
+| Companion (платная редакция: автоапдейт/лицензия/подпись) | вне этого репозитория | экосистема BPMkit |

standkit-0.7.0/docs/CHANGELOG.md

@@ -0,0 +1,344 @@
+# Changelog — standkit / BPMkitStand
+
+Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/); версии —
+[SemVer](https://semver.org/lang/ru/). Даты — 2026 год.
+
+## [0.7.0] — 2026-08-18
+
+### Добавлено
+- **Кукбук `standkit_hub/web/cookbook.html`.** Standalone-документ в фирменном стиле BPMkit
+  (один файл, без CDN и сборки): обзор продукта, установка и ключи запуска,
+  разбор дашборда, реестр стендов, виды хостинга (kestrel/iis/docker/k8s),
+  удалённые стенды и агент, модель безопасности, траблшутинг, границы
+  free/paid и незакрытые заделы. Есть поиск по документу, тёмная и светлая
+  тема, кнопки «копировать» на командах. Скриншоты дашборда — настоящие
+  (сняты с текущей сборки хаба, встроены в файл; меняются вместе с темой
+  документа), а не рисованные схемы. Собран по README, ARCHITECTURE,
+  HOSTING, REMOTE_STANDS, SECURITY, ROADMAP, BACKLOG и CHANGELOG.
+  Отдельно расписаны: установка **раздельно для Windows и Linux** (в Linux —
+  pipx или venv, потому что системный Python закрыт PEP 668), **обновление
+  диспетчера** (pip / pipx / venv, что при этом не трогается), три источника
+  секретов с приоритетом, и **развёртывание агента-демона на удалённом хосте**
+  — раскладка каталогов, где лежит его `projects.json`, токены через
+  `STANDKIT_SECRET__…`, systemd-юнит и служба Windows через NSSM.
+- **Документация синхронизирована с поддержкой HTTPS-пробы** (кукбук 1.2). Кукбук:
+  раздел «известное ограничение HTTPS» заменён описанием полей `stand_scheme` и
+  `verify_tls` — как настроить стенд за TLS и почему self-signed требует
+  `verify_tls: false`; поля добавлены в таблицу записи реестра; в колонке HTTP
+  сказано, что ссылка «Открыть стенд» строится по той же схеме; строка
+  траблшутинга про `http: down` теперь даёт рецепт, а не констатацию.
+  `docs/REMOTE_STANDS.md` — то же в шаге про реестр и в траблшутинге, пункт из
+  «Ограничений» убран. `docs/BACKLOG.md` — строка про HTTP-пробу за HTTPS снята:
+  реализовано.
+- **Кукбук 1.1 — по итогам первой живой установки агента на Linux** (Ubuntu 24.04,
+  стенд в Docker, 18.08.2026). Что добавлено: предупреждение про
+  `--break-system-packages` и указание, каким питоном звать скрипты
+  (`~/.local/share/pipx/venvs/standkit/bin/python` — системный `python3` модуля не
+  видит); отсутствие реестра на чистой машине как норма и полный порядок его
+  резолва; рецепт регистрации стенда через `Registry.add_existing()` — CLI для
+  этого нет; таблица «один стенд — две разные записи в двух реестрах»; отдельный
+  подраздел «Docker: какой адрес писать в реестр» (`0.0.0.0` даёт ложный
+  `http: down`, левый порт из `docker ps`, внутренний IP не писать); таблица
+  примеров имён `STANDKIT_SECRET__*` и три грабли вокруг них (забытый префикс,
+  владелец `agent.env`, лишний `_` от `echo | tr`); обязательность `--token-ref`
+  и явные `--run-dir`/`--log-dir` для службы; отсутствие эндпоинта `/health` и
+  разбор `409 adopt_required`; `curl.exe`/`Invoke-RestMethod` вместо алиаса
+  `curl` в PowerShell; рамка безопасности с `ufw`; известное ограничение
+  HTTPS-пробы. Траблшутинг вырос на десять строк — все симптомы реальные.
+- **Кнопка «Справка» (?) в шапке дашборда и ссылка в окне «О программе»** —
+  открывают кукбук, который отдаётся хабом как `/static/cookbook.html` и входит
+  в пакет (package-data `web/*`). Кукбук — обычная статика, а не страница
+  приложения: тот же файл открывается с диска, когда диспетчер остановлен.
+  Тест `test_cookbook_is_served_as_static_and_self_contained` держит и раздачу,
+  и самодостаточность (ни одной внешней ссылки, ни одного обращения к
+  `/static/*` изнутри файла).
+- **Отдельный диагноз «службы IIS остановлены».** Новый тип
+  `IisServiceUnavailableError` и подсказка «поднимите WAS/W3SVC»
+  (`sc start WAS` / `iisreset /start`). До живой приёмки IIS 17.08.2026 этот
+  случай (код 50, «Служба WAS недоступна») выдавался за нехватку прав, и
+  пользователь перезапускал диспетчер от администратора вместо запуска службы.
+- **Однократный повтор ЧИТАЮЩЕЙ команды `appcmd` при транзиентном сбое RPC**
+  (код 1726 / `hresult:800706be`, код 2147549190 / `hresult:80010006`). Живьём
+  такие ответы приходили сразу после операций над пулами, а через секунду та же
+  команда работала. Изменяющие команды автоматически НЕ повторяются — к тексту
+  ошибки добавляется подсказка про канал управления.
+- **Состояние стенда объясняется словами.** У docker- и k8s-бэкендов появился
+  `describe_state` (как у IIS): кроме вердикта «жив/не жив» он отдаёт причину,
+  которую `check_stand` кладёт в `StandStatus.details['process_reason']` —
+  «контейнер приостановлен (docker pause)», «контейнер в цикле перезапуска
+  (перезапусков: N)», «деплоймент масштабирован в 0 реплик», «готово 1 из 3
+  реплик». Вердикт, вынесенный TCP-фолбэком, помечается `status='unknown'` и
+  прямо сообщает, что состояние выяснить не удалось, — «зелёный по порту»
+  больше не выглядит как подтверждённый ответ CLI.
+- **k8s: `restart` дожидается завершения выката** (`rollout status`,
+  `K8S_ROLLOUT_WAIT_SEC`, по умолчанию 60 секунд; `0` возвращает прежнее
+  поведение). Раньше вызов возвращался за доли секунды, старые поды были ещё
+  готовы, и стенд сразу после «перезапуска» выглядел здоровым, даже если новые
+  поды не поднимались.
+
+### Изменено
+- **`docs/REMOTE_STANDS.md` — по тем же итогам:** явно сказано, что CLI регистрации
+  стенда нет (и чем её заменить), добавлено правило адреса `stand_host`/`stand_port`
+  для контейнеров, отмечено, что агент читает реестр только при старте, в примере
+  реестра `0.0.0.0` заменён на адрес обращения, к шагу запуска добавлены
+  обязательность `--token-ref` и каталоги службы, к таблице эндпоинтов — «`/health`
+  нет», в траблшутинг — десять строк живых симптомов, в «Ограничения» — HTTPS-проба.
+- **`docs/BACKLOG.md`:** добавлены строки про HTTP-пробу за HTTPS и отсутствие CLI
+  регистрации, а в раздел приёмки — первая живая установка агента на Linux.
+- **Кукбук переехал из `docs/` в `standkit_hub/web/`** — один файл вместо двух
+  копий: он и документ репозитория, и встроенная справка приложения.
+  `docs/cookbook.html` удалён, ссылка в README ведёт на новое место.
+- **Скриншоты `docs/img/*.png` пересняты** на 0.6.1: в прежних (0.5.x) не было
+  ни колонки Redis, ни кнопки «Зарегистрировать стенд».
+- **Забрана работа из ветки `docs/cookbook-and-screenshots` (28.07)**, которая
+  так и не получила PR: оттуда взяты кнопка «Справка», ссылка в «О программе»,
+  правила компактного режима и тест раздачи кукбука. Ветка удалена, чтобы не
+  висеть «потерянной работой».
+- **Установка в README — с PyPI (`pip install standkit`)**, а не из git. Пакет
+  публикуется на PyPI с 0.3.7, но README всё это время предлагал единственный
+  способ — установку из репозитория: она ставит незарелизенный `main` и не
+  обновляется командой `pip install -U`. Git-вариант остался в README как явный
+  «свежий `main` до релиза».
+- **`docs/REMOTE_STANDS.md`, установка агента — в выделенный venv** с созданием
+  сервисного аккаунта и каталогов, вместо `pip install` из git в текущее
+  окружение: агент оформляется службой, а системный Python в свежих
+  дистрибутивах закрыт PEP 668.
+- **Единый контракт `read_logs`:** при отсутствии CLI все бэкенды возвращают
+  `None`. Раньше docker отдавал `None`, а k8s бросал `HostingError`.
+- **k8s: логи читаются со всех подов деплоймента** по label-селектору с
+  префиксом имени пода. `kubectl logs deployment/X` показывает один под,
+  выбранный самим kubectl, — при нескольких репликах часть событий стенда была
+  не видна.
+- **k8s: `stop` бросает `HostingError`** с текстом kubectl вместо молчаливого
+  `False` по ненулевому коду возврата — как `DockerBackend.stop`.
+
+### Исправлено
+- **Стенд за HTTPS всегда показывался `http: down`.** Проба `check_stand`
+  строила URL жёстко как `http://<host>:<port>`, а `http_ok` шёл в `urlopen`
+  с дефолтным SSL-контекстом, проверяющим цепочку сертификатов. Живой стенд
+  BPMSoft за TLS с self-signed сертификатом (типовой дев-контур; найдено на
+  живой приёмке агента на Ubuntu 18.08.2026) давал `down` при исправных
+  `process`/`db` — индикатор врал, оператор видел «стенд лежит» на работающем
+  стенде. Появились два поля записи реестра: `stand_scheme` (`http`|`https`,
+  по умолчанию `http` — старые реестры не меняют поведения) и `verify_tls`
+  (по умолчанию `true`; `false` — не проверять цепочку, для self-signed).
+  `http_ok` принимает `verify=` и отключает проверку ТОЛЬКО для `https://`-
+  адресов, через публичный `ssl.create_default_context()`. Правка в ядре
+  чинит сразу всех потребителей пробы — агент, хаб и локальный путь. Заодно
+  ссылка «Открыть стенд» в дашборде строится по той же схеме, а не по `http`.
+  Поля НЕ добавлены в форму регистрации дашборда (её белый список полей
+  фиксирован в `standkit_hub/server.py` и `web/app.js`) — задавать их пока
+  нужно в `projects.json`; см. `docs/BACKLOG.md`.
+- **Документация предлагала несуществующую команду задания секрета.**
+  `docs/REMOTE_STANDS.md` в трёх местах советовал `python -m standkit.secrets set <ref>`,
+  но у модуля нет `__main__`-блока: команда молча завершается с rc=0 и ничего не
+  сохраняет, а администратор узнаёт об этом позже — по `401` от агента. Заменено на
+  рабочие пути (переменная `STANDKIT_SECRET__<REF>` для службы, `set_secret()` из
+  Python для машины с keyring, кнопка «Задать секрет…» в дашборде); в `docs/BACKLOG.md`
+  строка про отсутствующий CLI дополнена этим поведением.
+- **Внешние утилиты больше не мигают консольным окном** (`appcmd`, `sc`,
+  `docker`, `kubectl`, `taskkill`, `tasklist`, `powershell`). У родителя без
+  собственной консоли — `pythonw.exe`, служба, фоновый поллер хаба — Windows
+  выдавала консоль каждому такому вызову: на экране всплывало и мгновенно
+  исчезало чёрное окно. Живьём это выглядело как два мигающих окна раз в
+  ~12 секунд (поллер опрашивает IIS-стенд парой `appcmd list site|apppool`).
+  Появилась ЕДИНАЯ точка запуска `standkit.platform.run_console` с
+  `CREATE_NO_WINDOW` на win32; `hosting._run` (то есть весь путь
+  appcmd/docker/kubectl, включая пробы `standkit.adopt`), `sc query`,
+  `taskkill`, фолбэк `tasklist` и создание ярлыка через PowerShell переведены
+  на неё. Прямой `subprocess.run` в пакете теперь запрещён и стережётся
+  тестом `tests/test_no_window.py` (13 тестов, из них два — статическая
+  проверка исходников от регресса). Из обычного терминала дефект не
+  воспроизводился — дочерний процесс наследовал консоль родителя.
+- **IIS: автоопределение сайта заполняет и пул приложений.** `appcmd list apps
+  /xml` называет атрибут пула `APPPOOL.NAME`, а код читал `applicationPool` —
+  `detect_iis_site` ВСЕГДА возвращал пустой `app_pool`. Следствия: кнопка
+  «Определить автоматически» заполняла только сайт, а `kill_worker_processes`
+  (требует явного `iis_app_pool`) оставался недоступен для усыновлённого стенда.
+  Прежнее имя атрибута оставлено фолбэком. Юнит-тесты этот атрибут не мокали
+  вовсе — найдено живой приёмкой IIS 17.08.2026.
+- **IIS: `state:Unknown` больше не считается «сайт остановлен».** При
+  остановленных службах IIS `appcmd` отдаёт `Unknown` — то есть «сам не знаю».
+  Раньше вердикт был `DOWN` с причиной «сайт остановлен (state=Unknown)», то
+  есть сломанный канал управления выглядел как штатно погашенный стенд. Теперь
+  это неопределённое состояние: вердикт по TCP-порту, а причина прямо называет
+  остановленные службы («состояние не выяснено: остановлены службы IIS (WAS,
+  W3SVC)»).
+- **IIS: ошибка «объект не найден» не выдаётся за нехватку прав.** Список
+  признаков elevation был слишком широким (`error ( message:` ловил ЛЮБУЮ
+  ошибку appcmd, а код 1168 — это `ERROR_NOT_FOUND`, не отказ в доступе):
+  elevated-диспетчер на несуществующем сайте получал совет «запустите от имени
+  администратора». Теперь признаки узкие, а «любая ошибка = права» применяется
+  только когда процесс действительно НЕ elevated (`IsUserAnAdmin`).
+- **IIS: остановка пула больше не падает по таймауту.** `appcmd stop apppool`
+  ждёт завершения рабочего процесса, а IIS отводит на это `shutdownTimeLimit`
+  (по умолчанию 90 секунд) — общий таймаут внешних команд 20 секунд был мал:
+  живьём остановка пула прогретого стенда BPMSoft (.NET Framework) заняла
+  20.6 с, диспетчер рапортовал ошибку на штатной операции. У изменяющих
+  операций IIS (start/stop/recycle сайта и пула) теперь свой таймаут
+  `_IIS_LIFECYCLE_TIMEOUT` = 120 секунд; читающие пробы состояния остались
+  быстрыми (дашборд опрашивает их часто).
+- **IIS: логи стенда читаются из подпапок-дат.** BPMSoft под .NET Framework
+  пишет `Logs\<ГГГГ_ММ_ДД>\Application.log`, в корне каталога `*.log` нет вовсе —
+  `read_logs` возвращал `None`, и консоль стенда в диспетчере оставалась пустой
+  при живых файлах лога. Плоские логи (kestrel) по-прежнему в приоритете.
+- **Остановленный стенд больше не показывается работающим.** Общее правило для
+  всех бэкендов хостинга: ответ CLI авторитетнее открытого TCP-порта, фолбэк на
+  порт применяется только там, где состояние выяснить не удалось (утилита не
+  найдена, команда упала, вывод не разобран). Раньше это правило действовало
+  только для IIS; живая приёмка на настоящих Docker и Kubernetes 17.08.2026
+  показала два его нарушения:
+  - **k8s:** после `stop` (scale 0) `kubectl` честно отвечал «готовых реплик
+    нет» — пустой `status.readyReplicas`, — но вердикт перебивался открытым
+    NodePort, который слушается всё время, пока существует Service. Стенд
+    отображался живым, а сводный статус выходил противоречивым:
+    `process=ok, http=down`. Теперь пустой ответ при rc=0 трактуется как
+    определённое «не запущен»; нечисловой ответ по-прежнему считается
+    неопределённостью и уходит в фолбэк.
+  - **docker:** состояние контейнера при `rc=0` теперь окончательное, порт его
+    не переопределяет. Заодно вместо `.State.Running` спрашивается
+    `.State.Status`: у приостановленного контейнера (`docker pause`)
+    `Running=true`, хотя он не обслуживает запросы, — такой стенд показывался
+    зелёным.
+- **compose-режим больше не путает сервисы с похожими именами.** `is_running`
+  сопоставлял имя сервиса как подстроку любой строки `docker compose ps`:
+  при поднятом `webhook` неподнятый `web` считался запущенным. Теперь
+  используется машиночитаемый `docker compose ps --format json` с точным
+  сравнением поля `Service`, а на версиях compose без этого формата —
+  табличный вывод с разбором по токенам, а не по подстроке.
+
+### Прочее
+- Докстринг `HostKind.K8S` больше не утверждает, что логики k8s ещё нет — она
+  есть с 0.5.0 (ADR-0002) и прошла живую приёмку.
+- `docs/BACKLOG.md`: раздел приёмки актуализирован, добавлены остатки, найденные
+  живым прогоном, и рецепт воспроизводимого k8s-контура на Windows с cgroup v1.
+
+## [0.6.1] — 2026-07-27
+
+### Исправлено
+- **Повторный запуск по ярлыку больше не поднимает второй диспетчер.** Ярлык
+  стартует хаб через `pythonw.exe`, окна нет, а закрытие браузера процесс не
+  останавливает — idle-shutdown у хаба нет. Поэтому второй клик по ярлыку
+  запускал ещё один экземпляр: два фоновых поллера дёргали health-пробы и
+  внешние команды бэкендов хостинга над одним `projects.json`, а окно
+  открывалось на другом origin со своей копией localStorage (сбрасывалась
+  тема). На Windows было хуже, чем предполагалось: из-за `SO_REUSEADDR` bind
+  на уже слушаемый 8770 проходил успешно, и два хаба молча делили один порт.
+  Теперь перед стартом проверяется, не работает ли диспетчер уже — если да,
+  просто открывается браузер на нём. Откат на свободный порт сохранён для
+  случая, когда 8770 занял чужой сервис.
+- **Дашборд честно сообщает, что диспетчер остановлен.** Раньше вкладка с
+  умершим хабом продолжала показывать последний снапшот как живой, а
+  единственными признаками были красная точка в углу и браузерное
+  `Failed to fetch` в тостах. Теперь показывается баннер с объяснением и тем,
+  что делать, устаревшая таблица гасится, а сетевые ошибки и 401 («сессия не
+  подтверждена» после перезапуска диспетчера) переведены на понятный язык.
+
+## [0.6.0] — 2026-07-27
+
+### Добавлено
+- **Усыновление стендов, поднятых вне диспетчера.** Стенд, запущенный руками
+  (`dotnet BPMSoft.WebHost.dll` из консоли, скриптом, чужой сессией), теперь
+  можно остановить и перезапустить: диспетчер находит владельца порта,
+  проверяет, что это действительно процесс ЭТОГО стенда (порт + имя образа из
+  allowlist + рабочий каталог внутри `stand_dir`), и берёт его под управление —
+  **только с явного подтверждения**. Без подтверждения процесс не трогается.
+  В таблице стендов появился бейдж «вне диспетчера».
+- **IIS: автоопределение сайта** по physical path и биндингу для стенда,
+  развёрнутого мимо диспетчера; снятие зависшего `w3wp` по pid; различение
+  состояний «сайт остановлен» / «пул остановлен» / «порт держит http.sys».
+- **PWA.** `manifest.webmanifest` + иконки: Chrome и Edge предлагают
+  «Установить приложение» — дашборд получает отдельное окно без адресной
+  строки, свою иконку в панели задач и место в Alt+Tab. Зависимостей не
+  добавилось.
+- **Компактный режим** `?view=compact` — узкое окно-виджет: имена стендов,
+  состояния и старт/стоп. Доступен ярлыком из установленного PWA.
+- `GET /api/stands?probe=0` — слепок реестра без сетевых проб, и
+  `GET /api/events` — SSE-поток обновлений состояния.
+
+### Изменено
+- **Дашборд открывается мгновенно.** Раньше первый экран ждал полного обхода
+  всех стендов: пробы шли последовательно, до 9 секунд на стенд, а конфиг и
+  реестр перечитывались с диска на каждый запрос. Три недоступных стенда за
+  firewall давали около 27 секунд серого экрана. Теперь состояние собирает
+  фоновый поток, а страница рисуется сразу и обновляется по мере готовности.
+- **Фиксированный порт по умолчанию — 8770** (с откатом на свободный, если
+  занят). Побочный эффект прежнего эфемерного порта: браузер каждый запуск
+  считал дашборд новым сайтом, из-за чего сбрасывалась выбранная тема и
+  заново качалась статика.
+- Тема хранится в конфиге хаба и применяется до загрузки скриптов — тёмная
+  больше не мигает светлой при открытии.
+- Настройка «интервал автообновления» наконец работает: раньше значение из
+  формы ни на что не влияло, интервал был жёстко зашит.
+- **Форма настроек разгружена**: сразу видны четыре основных поля, параметры
+  федерации и демона-агента убраны под спойлеры, причём блок агента скрыт
+  целиком, пока в реестре нет удалённых стендов. У полей появились пояснения
+  и подсказки со значениями по умолчанию.
+- Остановка стенда стала мягкой: сначала штатное завершение с ожиданием и
+  только потом принудительное — стенд успевает закрыть соединения с БД и
+  Redis. Раньше на Windows сразу шёл `taskkill /T /F`.
+- Статика отдаётся с валидаторами кэша (`ETag`, `304`).
+
+## [0.5.2] — 2026-07-25
+
+### Изменено
+- **IIS: жизненный цикл по Site.** Стоп/рестарт/детект работают по **Site**
+  стенда; **App Pool не трогаем** (может быть общим с другими приложениями).
+  App Pool задействуется только когда `iis_site` не задан. Детект «жив» — по
+  состоянию сайта; открытый TCP-порт больше не маскирует остановленный сайт
+  (http.sys держит порт). См. [ADR-0004](adr/0004-iis-site-scoped-lifecycle.md).
+- **Читаемые ошибки внешних команд.** Вывод `appcmd`/`docker`/`kubectl`
+  декодируется utf-8 → OEM (cp866) → cp1251 — больше не «кракозябры».
+- **Хаб — тяжёлые логи IIS.** Панель «Текущее состояние» берёт логи только за
+  сегодня и читает лишь хвост файла (до 4 МБ) — дневной IIS-лог в сотни МБ не
+  грузится целиком.
+- Упаковка: SPDX-выражение лицензии (`license = "MIT"`, `license-files`) —
+  убран deprecation-warning setuptools.
+
+### Добавлено
+- Подсказка «запустите диспетчер от имени администратора» при ошибках `appcmd`
+  из-за нехватки прав (IIS требует elevation).
+- Кнопка «Обновить» даёт обратную связь (блокировка + «Обновление…» + время).
+- Колонка **Redis** в таблице стендов с номером базы.
+- Обратная связь и надёжность первого запуска: папка реестра создаётся при старте
+  диспетчера и при первой записи.
+
+### Исправлено
+- **Честный отказ** при остановке стенда, запущенного вне диспетчера (нет
+  pidfile): вместо мнимого «остановлено» — понятная ошибка.
+- Логи стенда ищутся в подпапках по датам (рекурсивный листинг) — раньше хаб
+  ошибочно сообщал «в каталоге нет файлов».
+- Модалки не закрываются при выделении текста мышью с отпусканием за краем окна.
+- Колонки таблицы не «прыгают» при смене статуса; HTTP-значение — кликабельная
+  ссылка; кнопки в модалках не слипаются.
+- `Ctrl+C` завершает `standkit-hub` чисто, без трейсбека `KeyboardInterrupt`.
+- Дедуп SVG-ассетов; TODO-докстринги урезаны до ссылок на документацию/бэклог.
+
+## [0.5.1] — 2026-07-24
+
+Технический релиз: агрегировал правки хаба/IIS/логов и упаковки (позже целиком
+переиздано в 0.5.2 из ветки `main`).
+
+## [0.5.0] — 2026-07-24
+
+### Добавлено
+- **Kubernetes** hosting backend (`host_kind=k8s`) через `kubectl`
+  (scale/rollout/get/logs) — [ADR-0002](adr/0002-k8s-backend.md).
+- **Регистрация стенда из UI** — модалка «Зарегистрировать стенд» в дашборде
+  (пишет в общий `projects.json`).
+- Hosting backends kestrel/iis/docker — [ADR-0001](adr/0001-hosting-backends.md)
+  (v0.4.0), k8s — v0.5.0.
+
+## [0.3.7] — 2026-07
+
+### Добавлено
+- Первый публичный релиз ядра `standkit` + агента `standkit_agent` + веб-дашборда
+  `standkit_hub` на PyPI; фронт-README, `docs/REMOTE_STANDS.md`, скриншоты.
+
+[0.7.0]: https://pypi.org/project/standkit/0.7.0/
+[0.6.1]: https://pypi.org/project/standkit/0.6.1/
+[0.6.0]: https://pypi.org/project/standkit/0.6.0/
+[0.5.2]: https://pypi.org/project/standkit/0.5.2/
+[0.5.1]: https://pypi.org/project/standkit/0.5.1/
+[0.5.0]: https://pypi.org/project/standkit/0.5.0/
+[0.3.7]: https://pypi.org/project/standkit/0.3.7/