From 33ac1696992c20a70a6c88be86959a2e51351917 Mon Sep 17 00:00:00 2001 From: Alexey Bagno Date: Mon, 31 Aug 2026 17:25:30 +0500 Subject: [PATCH] AGENTS --- AGENTS.md | 26 +++++++++++++++----- web/src/App.tsx | 65 ++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 74 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4188665..585eb9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,9 +15,9 @@ PWA для менеджмента homelab: монорепозиторий Go-с ``` proto/homelab/v1/ контракт (единственный источник правды) gen/ сгенерённый Go-код (коммитим) -server/main.go весь сервер: конфиг, мониторы, RPC, статика, docs API -web/src/App.tsx layout, топбар + hamburger-drawer, 4 хардкод-таба, поллинг ListContent (3s) -web/src/components/ MonitorCard, ScriptCard, Docs (ридер + textarea-редактор) +server/main.go весь сервер: конфиг, мониторы, RPC, статика, docs API, services API (systemd + docker) +web/src/App.tsx layout, топбар (desktop) + dock (mobile), 5 хардкод-табов, поллинг ListContent (3s) +web/src/components/ MonitorCard, ScriptCard, ServiceCard, Docs (ридер + textarea-редактор) web/src/docsStore.ts localStorage доков (hub:doc:*), dirty-флаги, syncDocs: pull по хэшам + flush раз в 5s web/src/gen/ сгенерированный TS-клиент web/public/ PWA-обвязка: manifest, sw.js, иконки @@ -27,7 +27,17 @@ docs/ markdown-доки, НЕ в репо — живут толь ## Категории -Хардкод в бандле (App.tsx CATEGORIES): Links (из config links), Monitor (config monitor), Exec (config exec), Docs (папка docs/, API ListDocs/GetDoc/SaveDoc). Оффлайн: контент-стейт держит последний ответ, доки — localStorage; правки в оффлайне помечаются dirty и флашатся на сервер каждые 5s (client authority — последняя запись побеждает, без base-hash check). +Хардкод в бандле (App.tsx CATEGORIES): Links (из config links), Monitor (config monitor), Exec (config exec), Docs (папка docs/, API ListDocs/GetDoc/SaveDoc), Services. Оффлайн: контент-стейт держит последний ответ, доки — localStorage; правки в оффлайне помечаются dirty и флашатся на сервер каждые 5s (client authority — последняя запись побеждает, без base-hash check). + +## Services (systemd + docker) + +Единый список карточек, едет в ответе `ListContent` (repeated Service, поле services) — своего RPC-поллинга нет. + +- **systemd** (`kind: SYSTEMD`): юниты из `srvDir` — `*.service`, имя валидируется regex `^[a-z0-9_.-]+$`. Путь: env `SRV_DIR`, иначе `~/srv` (на боксе юниты НЕ рядом с WorkingDirectory). Статус: `systemctl --user show -p ActiveState,SubState,LoadState,UnitFileState` — парсить ТОЛЬКО по ключам `Key=Value` (вывод не в порядке -p!). `LoadState=not-found` = юнит выключен юзером намеренно, не ошибка. +- **docker** (`kind: DOCKER`): `docker ps -aq` + `docker inspect -f` (labels проекта, status, restart policy). Группировка по `com.docker.compose.project`, без лейбла — своя карточка по имени контейнера. Агрегат: все running → active, ни одного → inactive, иначе partial «up/total». One-shot хелперы (`policy=no` + не running: init/migrations) исключаются из агрегата и из кнопок. +- **Кнопки**: RPC `ServiceAction(name, kind, op)` — systemd → `systemctl --user start|stop|restart`; docker → `docker start|stop|restart` над нужными контейнерами проекта (start — только остановленные, stop/restart — только запущенные). +- **Status-вывод**: RPC `ServiceInfo(name, kind)` → `systemctl status --no-pager -n 0` (exit 3 у остановленного — валидный вывод!) или `docker ps -a` по label проекта (пусто → fallback по имени). Показывается в модалке по кнопке ⓘ (ServiceCard). +- Десктоп: секция Services рендерится шире остальных (`max-w-5xl`), карточки в grid 2–3 колонки. ## Команды (всё через make) @@ -44,7 +54,7 @@ docs/ markdown-доки, НЕ в репо — живут толь `.gitea/workflows/deploy.yml`: push в `master` → checkout → `make web server` → cp на бокс → `systemctl --user restart hub-api`. -На боксе юнит должен иметь `WorkingDirectory=~/apps/hub` — сервер ищет `dist/`, `config.yaml`, `scripts/` относительно cwd. Локально всё то же самое из корня репо. +На боксе юнит должен иметь `WorkingDirectory=~/apps/hub` — сервер ищет `dist/`, `config.yaml`, `scripts/` относительно cwd, юниты сервисов — в `~/srv` (env `SRV_DIR` переопределяет). Локально всё то же самое из корня репо. ## Конвенции @@ -55,12 +65,16 @@ docs/ markdown-доки, НЕ в репо — живут толь - Иконки: хардкод в компонентах из lucide-preact поимённо (не тянуть весь lucide через `icons` — раздувает бандл в 5 раз). - Маркдаун: `marked` (~10KB gzip) + dangerouslySetInnerHTML без санитайзера (контент свой). Если редактор перестанет нравиться — **переход на MDXEditor** ( agreed upgrade path, изолирован в компоненте Docs). - index.html и sw.js отдаются с `Cache-Control: no-cache` — иначе iOS не подхватит новый бандл. -- Логи сервера: monitors и RunScript пишут в stdout; `ListSections` (поллинг-шум) исключён из HTTP-лога echo. +- Логи сервера: monitors, RunScript и ServiceAction/ServiceInfo пишут в stdout; ошибки проб сервисов (`probe : ...`) логируются один раз на изменение (появление/восстановление), не на каждый 3s тик; `ListContent` (поллинг-шум) исключён из HTTP-лога echo. - SW: `web/public/sw.js`, версия кэша `homelab-shell-vN` — **бампить при изменении** офлайн-логики, иначе iOS не обновит. - Тесты: `make test` (smoke RPC) + `tsc --noEmit` внутри `make web`. Не плодить фреймворки. ## Подводные камни +- `systemctl show` выводит свойства в порядке внутренней таблицы systemd, а НЕ в порядке `-p` — позиционный парс ломает статики незаметно (все карточки «остановлен»). Только парсинг `Key=Value` по ключу. +- `systemctl status` возвращет exit 3 для неактивного юнита и 4 для отсутствующего — непустой вывод = валидный результат, err игнорировать. +- Docker-кнопки бьют по контейнерам выборочно (start → не-running, stop/restart → running), т.к. `docker stop` остановленного возвращает ошибку у некоторых версий, а рестарт one-shot init-контейнеров повторяет миграции. + - iOS PWA требует https (или localhost). Через Caddy-домен бокса — ок. - SW на iOS у установленной PWA обновляется неохотно: правки SW → удалить иконку, открыть в Safari, добавить заново. Bump версии кэша в sw.js обязателен. - Connect JSON: `int64` сериализуется строкой — в smoke-тестах grep'ать с кавычками. diff --git a/web/src/App.tsx b/web/src/App.tsx index afa49d9..6565a79 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -10,7 +10,10 @@ import { ServiceCard } from "./components/ServiceCard"; import { DocsView, DocView, localDocs } from "./components/Docs"; import { syncDocs } from "./docsStore"; -const client = createClient(HomelabService, createConnectTransport({ baseUrl: "" })); +const client = createClient( + HomelabService, + createConnectTransport({ baseUrl: "" }), +); const CATEGORIES = [ { id: "links", label: "Links", icon: LinkIcon }, @@ -23,15 +26,23 @@ const CATEGORIES = [ type Category = (typeof CATEGORIES)[number]["id"]; function LinkList({ links }: { links: Link[] }) { - if (links.length === 0) return
No links in config
; + if (links.length === 0) + return
No links in config
; return (
{links.map((l) => ( - +
{l.name} - {l.url} + + {l.url} +
))} @@ -40,7 +51,12 @@ function LinkList({ links }: { links: Link[] }) { } export function App() { - const [content, setContent] = useState<{ links: Link[]; monitors: Item[]; exec: Item[]; services: Service[] }>({ + const [content, setContent] = useState<{ + links: Link[]; + monitors: Item[]; + exec: Item[]; + services: Service[]; + }>({ links: [], monitors: [], exec: [], @@ -54,7 +70,14 @@ export function App() { () => client .listContent({}) - .then((r) => setContent({ links: r.links, monitors: r.monitors, exec: r.exec, services: r.services })) + .then((r) => + setContent({ + links: r.links, + monitors: r.monitors, + exec: r.exec, + services: r.services, + }), + ) .catch(() => {}), // offline: keep last state [], ); @@ -66,7 +89,10 @@ export function App() { // Docs sync + offline dirty flush, every 5s. useEffect(() => { - const tick = () => syncDocs().then(() => setDocs(localDocs())).catch(() => {}); + const tick = () => + syncDocs() + .then(() => setDocs(localDocs())) + .catch(() => {}); tick(); const id = setInterval(tick, 5000); return () => clearInterval(id); @@ -102,13 +128,20 @@ export function App() { {category === "links" && } {category === "monitor" && (
- {content.monitors.map((it) => )} + {content.monitors.map((it) => ( + + ))}
)} {category === "exec" && content.exec.map((it) => )} {category === "services" && ( -
- {content.services.map((s) => )} +
+ +
+ {content.services.map((s) => ( + + ))} +
)} {category === "docs" && @@ -122,7 +155,17 @@ export function App() { {/* Mobile footer nav: daisyUI dock (v5 btm-nav removed), equal quarters */}
{CATEGORIES.map((c) => ( -