AGENTS

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 <unit> -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 <key>: ...`) логируются один раз на изменение (появление/восстановление), не на каждый 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'ать с кавычками.

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 <div class="alert mt-4">No links in config</div>;
+  if (links.length === 0)
+    return <div class="alert mt-4">No links in config</div>;
   return (
     <div class="flex flex-col gap-2 mt-4">
       {links.map((l) => (
-        <a href={l.url} target="_blank" rel="noreferrer" class="card bg-base-200 shadow">
+        <a
+          href={l.url}
+          target="_blank"
+          rel="noreferrer"
+          class="card bg-base-200 shadow"
+        >
           <div class="card-body p-4 py-3 flex-row items-center gap-2">
             <LinkIcon size={14} class="text-primary" />
             <span class="flex-1 truncate">{l.name}</span>
-            <span class="text-xs text-base-content/40 truncate max-w-40">{l.url}</span>
+            <span class="text-xs text-base-content/40 truncate max-w-40">
+              {l.url}
+            </span>
           </div>
         </a>
       ))}
@@ -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" && <LinkList links={content.links} />}
         {category === "monitor" && (
           <div class="flex flex-col gap-3 mt-4">
-            {content.monitors.map((it) => <MonitorCard s={it} />)}
+            {content.monitors.map((it) => (
+              <MonitorCard s={it} />
+            ))}
           </div>
         )}
         {category === "exec" && content.exec.map((it) => <ScriptCard s={it} />)}
         {category === "services" && (
+          <div>
+            <input type="text" placeholder="Type here" className="input" />
             <div class="grid gap-3 mt-4 md:grid-cols-2 lg:grid-cols-3">
-            {content.services.map((s) => <ServiceCard s={s} refresh={refresh} />)}
+              {content.services.map((s) => (
+                <ServiceCard s={s} refresh={refresh} />
+              ))}
+            </div>
           </div>
         )}
         {category === "docs" &&
@@ -122,7 +155,17 @@ export function App() {
       {/* Mobile footer nav: daisyUI dock (v5 btm-nav removed), equal quarters */}
       <div class="dock md:hidden">
         {CATEGORIES.map((c) => (
-          <button class={c.id === category ? "dock-active text-primary" : "text-base-content/60"} onClick={() => { setCategory(c.id); setOpenDoc(null); }}>
+          <button
+            class={
+              c.id === category
+                ? "dock-active text-primary"
+                : "text-base-content/60"
+            }
+            onClick={() => {
+              setCategory(c.id);
+              setOpenDoc(null);
+            }}
+          >
             <c.icon size={26} />
             <span class="dock-label text-xs">{c.label}</span>
           </button>