Added AGENTS.md

2026-08-29 11:19:28 +05:00
parent 9b477ae5c3
commit dfa70e96e3
2 changed files with 59 additions and 105 deletions
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+PWA для менеджмента homelab: монорепозиторий Go-сервер + SPA-фронт, общаются через ConnectRPC.
+Таргет — iPhone «На экран Домой» (standalone PWA).
+
+## Стек
+
+- **Сервер**: Go + echo + `connectrpc.com/connect`. Отдаёт RPC на `/homelab.v1.HomelabService/*` и статику из `dist/` (SPA-fallback включён). Порт из env `PORT` (дефолт `:8080`).
+- **Фронт**: Preact + Vite + TypeScript, daisyUI v5 (tailwind v4), lucide-preact. Клиент — `@connectrpc/connect-web`, same-origin transport, в dev — прокси на :8080.
+- **Контракт**: `proto/homelab/v1/homelab.proto` → кодоген в `gen/` (Go) и `web/src/gen/` (TS). Сгенерённый код **коммитится**, buf CLI не используется — только protoc.
+- **Конфиг**: `config.yaml` (секции → items → bash-скрипты). Мониторы гоняются по таймеру на сервере, response-скрипты запускаются по кнопке с аргументами.
+
+## Структура
+
+```
+proto/homelab/v1/   контракт (единственный источник правды)
+gen/                сгенерённый Go-код (коммитим)
+server/main.go      весь сервер: конфиг, мониторы, RPC, статика
+web/src/App.tsx     layout, сайдбар секций, поллинг ListSections (3s)
+web/src/components/ MonitorCard (мониторы), ScriptCard (response-форма + модалка результата)
+web/src/gen/        сгенерированный TS-клиент
+web/public/         PWA-обвязка: manifest, sw.js, иконки
+scripts/            bash-скрипты, пути из config.yaml
+```
+
+## Команды (всё через make)
+
+- `make dev` — сервер :8080 + vite :5173 (работать на http://localhost:5173)
+- `make dev-srv` / `make dev-web` — по отдельности в два терминала
+- `make proto` — кодоген Go+TS из proto
+- `make web` — сборка фронта в `dist/` (tsc --noEmit + vite build; `tsc` — линтер, падение = ошибка типов)
+- `make server` — Go-бинарь `bin/hub-api`
+- `make test` — smoke-тест RPC (поднимает сервер на :8080, дергает curl'ом)
+
+Никаких других способов сборки нет: CI делает ровно `make web server`.
+
+## Деплой (CI)
+
+`.gitea/workflows/deploy.yml`: push в `master` → checkout → `make web server` → cp на бокс → `systemctl --user restart hub-api`. 
+
+На боксе юнит должен иметь `WorkingDirectory=~/apps/hub` — сервер ищет `dist/`, `config.yaml`, `scripts/` относительно cwd. Локально всё то же самое из корня репо.
+
+## Конвенции
+
+- Один корень статики: `dist/`. Не вводить fallback-ов (`web/dist` не существует после `make web` — vite собирает в `web/dist`, make копирует в `./dist`).
+- `int64` в proto → `bigint` в TS (не `number`!).
+- Поля protobuf в TS — camelCase (`arg_types` → `argTypes`).
+- Новый item-тип или поле в yaml = обновить proto + валидацию в `loadConfig` + компонент на фронте.
+- Иконки секций: строка из конфига → ручной маппинг `ICONS` в `App.tsx` (не тянуть весь lucide через `icons` — раздувает бандл в 5 раз).
+- Логи сервера: monitors и RunScript пишут в stdout; `ListSections` (поллинг-шум) исключён из HTTP-лога echo.
+- SW: `web/public/sw.js`, версия кэша `homelab-shell-vN` — **бампить при изменении** офлайн-логики, иначе iOS не обновит.
+- Тесты: `make test` (smoke RPC) + `tsc --noEmit` внутри `make web`. Не плодить фреймворки.
+
+## Подводные камни
+
+- iOS PWA требует https (или localhost). Через Caddy-домен бокса — ок.
+- SW на iOS у установленной PWA обновляется неохотно: правки SW → удалить иконку, открыть в Safari, добавить заново. Bump версии кэша в sw.js обязателен.
+- Connect JSON: `int64` сериализуется строкой — в smoke-тестах grep'ать с кавычками.
+- Джобы CI — host (не docker), user `homelab`; не добавлять docker-шаги.