Expand AGENTS.md with current repo and reporting rules

AGENTS.md

@@ -1,72 +1,198 @@
-# Инструкции для агентов
+# AGENTS.md
 
-## Контекст проекта
+## Назначение
 
-ProxyWarden - standalone Windows desktop client в корне репозитория. Это Tauri 2 + React/TypeScript UI + Rust backend для маршрутизации выбранных Windows-приложений через внешний SOCKS5-прокси или опциональный Local sing-box.
+ProxyWarden — standalone Windows desktop-приложение для удобного per-app proxy routing. Стек: Tauri 2, Rust backend, React/TypeScript frontend, Vite, PowerShell installer/control scripts. Приложение управляет выбранными Windows-приложениями через ProxiFyre и, опционально, через локальный sing-box runtime.
 
-Не возвращать старую идею `APP_MODE=windows` и не подключать Windows-клиент к отдельному Node gateway/server. Текущий рабочий путь - `src`, `src-tauri`, `scripts` в корне репозитория.
+Этот файл — главный контракт для кодового агента. Любой агент, который меняет репозиторий, обязан соблюдать эти правила. Да, даже если ему очень хочется «быстренько поправить одну кнопочку» и случайно переписать половину сетевого стека. Особенно тогда.
 
-## Основные инварианты
+## Продуктовая рамка
 
-- Три компонента должны оставаться разделенными: Control App, ProxiFyre, Local sing-box.
-- ProxiFyre - обязательный слой для per-app routing; Local sing-box - необязательный runtime.
-- Внешний SOCKS5 flow должен работать без установленного Local sing-box.
-- Profile apply не должен скрыто устанавливать, удалять, запускать или чинить компоненты. Install/start/stop/uninstall - только явные действия пользователя.
-- Source of truth - JSON под `C:\ProgramData\ProxyWarden\config` и `state`.
-- `C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json` и `sing-box-config.json` - derived artifacts, их можно пересоздать.
-- Subscription URL и другие секреты нельзя показывать полностью в UI, diagnostics или логах.
-- Summary panel должен оставаться read-only: без apply/install/start/stop/delete/input/subscription mutations.
+Проект не должен превращаться в коммерческий SaaS, Node gateway, VPN-провайдер, proxy server или облачный control plane. Это локальная Windows-утилита для себя и друзей.
+
+Цель: надежно и понятно конфигурировать маршрутизацию выбранных приложений через внешний SOCKS5 proxy или через локальный sing-box, не ломая системную сеть и не пряча опасные действия за безобидными кнопками.
+
+## Архитектурные инварианты
+
+- Control App, ProxiFyre и Local sing-box — разные компоненты. Не смешивать их ответственность.
+- ProxiFyre — обязательный слой для per-app routing.
+- Local sing-box — optional runtime. Внешний SOCKS5 flow обязан работать без sing-box.
+- React UI не пишет generated config напрямую. UI вызывает typed Tauri commands.
+- `src/api/tauriCommands.ts` — единственная TypeScript-обертка над `invoke(...)`.
+- Rust backend отвечает за storage, validation, config generation, component detection, service/install orchestration и structured errors.
+- `C:\ProgramData\ProxyWarden\config` и `C:\ProgramData\ProxyWarden\state` — source of truth.
+- `C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json` и `sing-box-config.json` — derived artifacts. Их можно пересоздавать.
+- Install/start/stop/uninstall — только явные действия пользователя. `apply` не должен скрыто устанавливать, удалять или «чинить» компоненты.
+- Subscription URL, credentials, proxy passwords и userinfo нельзя выводить полностью в UI, logs, diagnostics, crash text или activity.
+- Summary panel должен оставаться read-only: без install/start/stop/apply/delete/input/subscription mutations.
+- Любые elevated операции должны быть максимально явными и проверяемыми.
+
+## Основная структура
+
+```text
+src/
+  api/tauriCommands.ts       # typed invoke facade
+  app/App.tsx                # текущая UI orchestration зона, слишком крупная
+  app/readiness.ts           # apply gating logic
+  app/viewModel.ts           # display/view helpers
+  domain/types.ts            # TypeScript DTO mirror
+  ui/*                       # reusable presentational components
+  styles/app.css             # основной CSS
+
+src-tauri/
+  tauri.conf.json            # Tauri config, security, window config
+  capabilities/default.json  # Tauri permissions/capabilities
+  src/models.rs              # Rust domain models/defaults
+  src/validation.rs          # normalization/validation
+  src/storage.rs             # JSON storage, tmp/bak writes
+  src/activity.rs            # activity log
+  src/subscription.rs        # subscription fetch/parse
+  src/component_detection.rs # ProxiFyre/sing-box detection
+  src/singbox_service.rs     # sing-box Windows service logic
+  src/process.rs             # process/system helpers
+  src/helper.rs              # helper/elevation boundary
+  src/adapters/*             # ProxiFyre/sing-box/proxy-router adapters
+  src/commands.rs            # Tauri command handlers; currently too large
+  tests/*                    # Rust integration/domain tests
+
+scripts/
+  install-control-app.ps1
+  install-proxyfier.ps1
+  install-singbox.ps1
+  prepare-release.ps1
+```
+
+## Агентские skill-модули
+
+Подробные инструкции лежат в `.agent/skills`:
+
+- `.agent/skills/repository-orientation/SKILL.md` — как быстро понять репозиторий.
+- `.agent/skills/rust-tauri-backend/SKILL.md` — Rust/Tauri backend changes.
+- `.agent/skills/react-typescript-ui/SKILL.md` — frontend/UI changes.
+- `.agent/skills/security-hardening/SKILL.md` — CSP, секреты, temp files, storage, SSRF, elevated boundary.
+- `.agent/skills/windows-services-powershell/SKILL.md` — Windows service/install/PowerShell изменения.
+- `.agent/skills/subscriptions-routing/SKILL.md` — subscription, sing-box, ProxiFyre routing.
+- `.agent/skills/testing-ci-release/SKILL.md` — проверки, CI, release hygiene.
+- `.agent/skills/communication-reporting/SKILL.md` — короткие понятные планы, ревью и отчеты с таблицами файлов.
+
+Перед сложным изменением прочитать релевантный skill. Перед любым нетривиальным ответом владельцу проекта — прочитать `communication-reporting`. Да, инструкция про то, как не писать кашу, теперь тоже инструкция. Так мы и живем.
+
+## Стиль общения агента
+
+Пользователь — разработчик, но ему не нужен роман о каждом `match`, `useState` и переименованном импорте. Писать надо как для человека, которому нужно быстро принять решение: что изменилось, где изменилось, зачем и что проверить.
+
+Перед любым нетривиальным ответом прочитать `.agent/skills/communication-reporting/SKILL.md` и перед финальным сообщением пройти `.agent/checklists/communication.md`.
+
+### Обязательные правила
+
+- Сначала результат, потом детали.
+- Короткие абзацы, списки и таблицы вместо полотна текста.
+- Для нетривиальных изменений использовать таблицу `Файл / Что изменилось / Зачем`.
+- Не объяснять каждую строку. Объяснять важные места, решения, риски и поведение.
+- Технические термины использовать только когда они помогают. Сложный термин объяснять одной простой фразой.
+- Проверки делить на выполненные, не выполненные и требующие Windows/manual check.
+- Для ревью группировать находки по приоритетам: `Критично`, `Важно`, `Можно потом`, `Косметика`.
+- Не писать корпоративный туман вроде «улучшена архитектура» без указания, что именно стало проще, безопаснее или понятнее.
+- Не заявлять “всё проверено”, если Rust tests, Windows service flow, Tauri build или UAC сценарии не запускались.
+
+### Минимальный формат финального ответа
+
+```md
+## Коротко
+
+- 1-3 главных результата.
+
+## Файлы
+
+| Файл | Что изменилось | Зачем |
+|---|---|---|
+| `path/file` | простое описание | практическая причина |
+
+## Проверки
+
+| Проверка | Статус | Комментарий |
+|---|---|---|
+| `command` | выполнено / не выполнено | почему |
+
+## Риски
+
+- Что осталось проверить или почему риска нет.
+```
+
+Если задача маленькая, формат можно сжать до нескольких строк. Если задача security/service/storage/routing-sensitive, детали обязательны, потому что «ну вроде работает» — это не инженерный метод, а жанр народного фольклора.
 
-## Структура
 
-- `src/app/App.tsx` - основная React-оркестрация, вкладки `Сводка`, `ProxiFyre`, `VPN / Прокси`, вызовы Tauri-команд и transient UI state.
-- `src/app/readiness.ts` - gating применимости маршрута. Не обходить его локальными проверками в JSX.
-- `src/app/viewModel.ts` - маленькие display/view-model helpers.
-- `src/ui/*` - общие presentational-компоненты. Для новых кнопок, вкладок, service rows, pills, полей и лог-дока сначала расширять эти компоненты.
-- `src/api/tauriCommands.ts` - единственная TypeScript-обертка над `invoke(...)`; держать DTO в синхронизации с Rust.
-- `src/domain/types.ts` - TypeScript-зеркало доменных DTO.
-- `src-tauri/src/models.rs` - Rust-модели и default values.
-- `src-tauri/src/validation.rs` - нормализация входов.
-- `src-tauri/src/storage.rs` и `activity.rs` - JSON storage, backup/tmp writes, activity cap/sort.
-- `src-tauri/src/adapters/proxy_router.rs` - adapter boundary для proxy-router.
-- `src-tauri/src/adapters/proxifyre.rs` - первый adapter, генерирует ProxiFyre `app-config.json`.
-- `src-tauri/src/adapters/singbox.rs` - генерация локального `sing-box` конфига из subscription cache и выбранного сервера.
-- `src-tauri/src/component_detection.rs` - detection ProxiFyre/Proxifier/Local sing-box.
-- `src-tauri/src/commands.rs` - Tauri command handlers, installer/service orchestration, structured errors.
-- `src-tauri/src/main.rs` - реальная Tauri entrypoint-регистрация команд.
-- `src-tauri/src/lib.rs` сейчас scaffold/stale; не считать его источником регистрации команд без отдельной cleanup-задачи.
-- `scripts/*.ps1` - явные installer entrypoints. `-PlanOnly` должен возвращать structured JSON без side effects.
 
 ## Правила изменений
 
-- Не создавать второй источник правды для профилей, targets, components, subscription или activity.
-- Не писать generated config напрямую из React.
-- Не парсить raw PowerShell/stdout в UI. Backend/helper boundary должен возвращать structured JSON/error DTO.
-- Не привязывать UI напрямую к деталям ProxiFyre, если изменение относится к общему proxy-router поведению.
-- Не делать Local sing-box обязательным для external target.
-- Для service/install операций сохранять UAC/admin boundary и человекочитаемые ошибки.
-- При удалении install folders сохранять safe-path checks; не ослаблять рекурсивное удаление.
-- В UI держать стиль компактной Windows-утилиты, а не landing/dashboard. Использовать existing `Button`, `Tabs`, `ServiceControlRow`, `StatusPill`, `Field`, `ActionMenu`, `LogDock`.
-- Всплывающие подсказки при наведении делать быстрыми, кастомными и читаемыми: темная compact-плашка с мягкой рамкой/тенью, появление ~120ms, без нативного browser `title` как основного UI. Для иконок расширять общий `IconButton`/tooltip-паттерн, а не дублировать JSX/CSS локально.
-- Apply actions должны быть disabled с объяснением, когда нет приложений, ProxiFyre отсутствует, proxy input неверный или local route не готов.
-- Не оставлять dev-серверы (`npm run dev`, `npm run tauri -- dev`, preview-серверы) запущенными после проверки. Если сервер был поднят агентом, остановить его перед финальным ответом.
+### Backend
 
-## Проверка
+- Не добавлять новую Tauri command без typed wrapper в `src/api/tauriCommands.ts` и соответствующего TypeScript DTO в `src/domain/types.ts`, если command используется UI.
+- Не возвращать raw strings для сложных ошибок. Использовать structured error DTO: `code`, `message`, `details`.
+- Тяжелые или блокирующие операции должны быть `async` command + `tauri::async_runtime::spawn_blocking`.
+- Не вызывать network/process/service/file-heavy logic прямо из async runtime thread.
+- Не использовать `unwrap()`/`expect()` в production path, кроме очевидно невозможных bootstrap cases с комментарием.
+- Не писать generated configs неатомарно. Использовать temp + backup + rename where practical.
+- Не расширять `commands.rs` без необходимости. Для новой логики предпочитать отдельные модули и thin command wrapper.
 
-Минимум для frontend/UI:
+### Frontend
+
+- Не увеличивать `App.tsx`, если можно вынести hook/helper/component.
+- Не вызывать `invoke(...)` напрямую вне `src/api/tauriCommands.ts`.
+- Не дублировать apply-readiness проверки в JSX. Расширять `src/app/readiness.ts`.
+- Для UI использовать существующие компоненты из `src/ui`.
+- Apply/start/install/delete buttons должны иметь disabled state и понятную причину.
+- Не показывать secrets. Для subscription/proxy URL использовать redacted display values.
+- UI должен оставаться compact Windows utility, а не SaaS dashboard с иллюзией корпоративной важности.
+
+### Security
+
+- Не отключать CSP. Если CSP мешает, исправлять source policy, а не ставить `csp: null`.
+- Не добавлять Tauri shell permissions без жесткого scope и отдельного обоснования.
+- Не запускать произвольные команды из UI input.
+- Runtime-generated elevated scripts должны использовать непредсказуемые имена, safe directory/ACL и cleanup best-effort.
+- Удаление директорий допускается только после safe-path/marker/service-path checks.
+- Subscription fetch должен иметь timeout и защиту от очевидно опасных/local metadata адресов либо explicit allow-mode.
+
+### Windows/service boundary
+
+- `-PlanOnly` у PowerShell scripts должен оставаться side-effect-free и возвращать structured JSON.
+- Install/start/stop/uninstall должны быть явными user actions.
+- Fuzzy-detected service не считать managed service без проверки `PathName`/metadata.
+- В Linux/macOS CI не пытаться «проверить» Windows service operations как реальные. Тестировать pure logic/mocks.
+
+## Известный технический долг
+
+- `src-tauri/src/commands.rs` слишком большой. Главная цель рефакторинга: разрезать на модули по use-case.
+- `src/app/App.tsx` слишком большой. Главная цель frontend-рефакторинга: hooks/components/view-model helpers.
+- `tauri.conf.json` сейчас требует security review, особенно CSP и window resize settings.
+- JSON storage молча возвращает default при invalid JSON. Нужен corruption recovery через `.bak` и user-visible warning.
+- ProxiFyre config apply должен стать atomic.
+- Subscription URL redaction должен исключать userinfo/password.
+- Link subscription parser сейчас ориентирован на VLESS; не обещать больше, чем реально поддерживается.
+- Ping/select по server tag может ломаться при duplicate tags. Нужен stable server id.
+
+## Минимальная проверка перед ответом
+
+Для docs-only изменений достаточно проверить структуру файлов и отсутствие очевидных Markdown/JSON ошибок.
+
+Для frontend изменений:
 
 ```powershell
+npm ci
 npm run build
 ```
 
-Rust/backend:
+Для Rust/backend изменений:
 
 ```powershell
-cd D:\repos\ProxyWarden\src-tauri
-cargo test
+cd src-tauri
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-targets
 ```
 
-Tauri/toolchain:
+Для Tauri/toolchain:
 
 ```powershell
 npm run tauri -- info
@@ -74,7 +200,7 @@ npm run tauri -- dev
 npm run tauri -- build
 ```
 
-Installer boundaries:
+Для installer boundaries:
 
 ```powershell
 & .\scripts\install-control-app.ps1 -PlanOnly
@@ -82,10 +208,25 @@ Installer boundaries:
 & .\scripts\install-singbox.ps1 -PlanOnly
 ```
 
-Для UI-изменений проверять browser-preview на desktop и narrow viewport. Browser-preview не доказывает native Tauri commands или elevated service lane.
+Не оставлять dev/preview/Tauri dev servers запущенными после проверки.
 
-## Известные риски
+## Формат отчета агента
 
-- Реальные elevated install/start/stop/uninstall операции для ProxiFyre и Local sing-box считаются `implemented but unproven`, пока они не проверены на Windows с UAC/admin confirmation.
-- Исторические planning/evidence файлы лежат в ignored `docs`-папках и не должны попадать в коммиты.
-- Старые документы могут ссылаться на `apps/windows-client`; текущая структура репозитория - standalone client в корне.
+Использовать один из шаблонов:
+
+- `.agent/templates/work-plan.md` — короткий план перед работой.
+- `.agent/templates/change-report.md` — отчет после изменения кода.
+- `.agent/templates/investigation-report.md` — аудит, расследование, разбор проблемы.
+- `.agent/templates/user-facing-summary.md` — краткая сводка для владельца проекта.
+- `.agent/templates/pr-description.md` — описание PR.
+
+Каждый нетривиальный ответ должен отвечать на вопросы:
+
+1. Что поменялось или найдено?
+2. В каких файлах?
+3. Зачем это нужно?
+4. Что проверено?
+5. Что не проверено?
+6. Где остался риск?
+
+Не писать «всё готово», если Windows/elevated/service flow не проверялся на Windows. Эта фраза и так слишком много навредила миру.