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-шаги.
@@ -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), иначе джоба упадёт на деплое.