# AGENTS.md

## Назначение

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.

Этот файл — главный контракт для кодового агента. Любой агент, который меняет репозиторий, обязан соблюдать эти правила. Да, даже если ему очень хочется «быстренько поправить одну кнопочку» и случайно переписать половину сетевого стека. Особенно тогда.

## Продуктовая рамка

Проект не должен превращаться в коммерческий 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, детали обязательны, потому что «ну вроде работает» — это не инженерный метод, а жанр народного фольклора.



## Правила изменений

### 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

- Не увеличивать `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 изменений:

```powershell
cd src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
```

Для Tauri/toolchain:

```powershell
npm run tauri -- info
npm run tauri -- dev
npm run tauri -- build
```

Для installer boundaries:

```powershell
& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly
```

Не оставлять dev/preview/Tauri dev servers запущенными после проверки.

## Формат отчета агента

Использовать один из шаблонов:

- `.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. Эта фраза и так слишком много навредила миру.