diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d341bd7 --- /dev/null +++ b/AGENTS.md @@ -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-шаги. diff --git a/CI-DEPLOY.md b/CI-DEPLOY.md deleted file mode 100644 index 30a608e..0000000 --- a/CI-DEPLOY.md +++ /dev/null @@ -1,105 +0,0 @@ -# Инструкция: настроить CI-деплой проекта на боксе (для агента-исполнителя) - -## Твоя задача -Сделать так, чтобы push в ветку `main` репозитория в Gitea автоматически: -1) собирал фронт (pnpm + vite), 2) собирал Go-бинарь, 3) раскладывал их на боксе и перезапускал сервис. - -Раннер и инструменты УЖЕ стоят и работают. Ты только добавляешь workflow-файл в репо, -регистрируешь юнит сервиса и проверяешь деплой. - ---- - -## Факты окружения (проверять не нужно — верны) - -- **Раннер:** `box-runner` (Gitea Runner v3.3.1), user-юнит `act-runner.service`, метка `ubuntu-latest` = host-режим. -- **Джобы CI выполняются на хосте бокса от пользователя `homelab`** (не в docker!). Имеют доступ к `~/apps`, `systemctl --user`, локальному docker. -- **PATH внутри джоб:** `~/.local/bin` (node 22, npm, pnpm 11) + `~/apps/go/bin` (go 1.27) + стандартный. -- **Цели деплоя:** - - статика SPA → `~/apps/hub/dist/` (Caddy `hub.alexey-homelab.duckdns.org` отдаёт её по `/`, SPA-fallback на `/index.html`) - - Go-бинарь → `~/apps/hub/hub-api`, должен слушать **`127.0.0.1:8484`** (Caddy проксирует `/api/*` туда) -- **Юнит сервиса:** файл `~/srv/hub-api.service` уже создан, но НЕ зарегистрирован (бинарника ещё нет). - ---- - -## Шаги - -### Шаг 1. Узнай структуру проекта -Выясни у пользователя (или посмотри в репо): -- где `package.json` (фронт) — ожидается `frontend/` -- где `main.go` (бэк) — ожидается `api/` -Если структура другая — поправь пути в шаблоне workflow (шаг 2). - -### Шаг 2. Добавь workflow в репо -Скопируй блок ниже в репо как `.gitea/workflows/deploy.yml`: - -```yaml -name: Deploy -on: - push: - branches: [main] - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Build frontend (pnpm + vite) - run: | - cd frontend - pnpm install --frozen-lockfile - pnpm build - - - name: Build API (Go) - run: | - cd api - CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o hub-api . - - - name: Deploy to box - run: | - mkdir -p ~/apps/hub/dist - cp -r frontend/dist/* ~/apps/hub/dist/ - cp api/hub-api ~/apps/hub/hub-api - chmod +x ~/apps/hub/hub-api - systemctl --user restart hub-api -``` - -ВАЖНО: -- `pnpm install --frozen-lockfile` требует `pnpm-lock.yaml` в репо — убедись, что он закоммичен. -- Если юнит ещё не зарегистрирован (шаг 3 не сделан), последняя строка упадёт — добавь `|| true` временно, пока не сделаешь шаг 3. - -### Шаг 3. Зарегистрируй юнит сервиса (один раз, на боксе) -```bash -ln -sf /home/homelab/srv/hub-api.service ~/.config/systemd/user/hub-api.service -systemctl --user daemon-reload -systemctl --user enable hub-api -``` -НЕ запускай (`start`) — бинарника ещё нет, юнит упадёт. Он поднимется сам после первого деплоя -(`systemctl --user restart hub-api` в workflow). - -### Шаг 4. Проверь джобу -- Сделай push в `main` → открой Gitea UI → репо → вкладка **Actions** → смотри лог джобы. -- Джоба должна пройти зелёной: build → deploy. - -### Шаг 5. Проверь деплой -```bash -ls -la ~/apps/hub/ # dist/ + hub-api на месте -curl -s http://127.0.0.1:8484/api/health # ответ API (если бинарник жив) -curl -s -o /dev/null -w '%{http_code}\n' https://hub.alexey-homelab.duckdns.org/ \ - --resolve hub.alexey-homelab.duckdns.org:443:127.0.0.1 # 200 = статика отдаётся -``` -Если бинарник падает: `journalctl --user -u hub-api -n 30` — смотри ошибку (чаще всего: не тот порт/адрес, отсутствие флага). - ---- - -## Питфоллы - -1. **Джобы без docker** (host-метка). Не используй `docker:`-шаги в CI. Если понадобится docker — - менять метку в `~/apps/act_runner/config.yaml` (`ubuntu-latest:docker://...`) + `systemctl --user restart act-runner` — но это отдельное решение. -2. **Go-бинарь должен слушать `127.0.0.1:8484`** — проверь дефолт/флаг в коде (`:8484`), Caddy уже смотрит туда. -3. **`actions/checkout@v4` скачивается с GitHub** — с бокса работает (не менять на самописный клон без нужды). -4. **pnpm store** кэшируется в `~/.local/share/pnpm` — холодная сборка только первый раз. -5. **Не удаляй и не двигай** `~/apps/act_runner/` (там `.runner` — регистрация раннера) и `~/srv/act-runner.service`. -6. **`systemctl --user restart hub-api` в CI** — юнит должен существовать (шаг 3), иначе джоба упадёт на деплое. -