# CLAUDE.md

## Проект

ServerManager — Desktop GUI (CustomTkinter) для управления удалёнными серверами **любых типов**. Claude Code управляет серверами через скилл `/ssh`, зная только алиасы.

## Поддерживаемые типы серверов

| Тип | Клиент | GUI-табы | CLI-команды |
|-----|--------|----------|-------------|
| ssh | `ssh_client.py` (Paramiko) | Terminal, Files, Info, Keys, 2FA, Setup | `ALIAS "cmd"`, `--upload`, `--download` |
| telnet | `telnet_client.py` (telnetlib3) | Terminal, Info, Setup | — |
| mariadb/mssql/postgresql | `sql_client.py` (pymysql/pymssql/psycopg2) | Query, Info, Setup | `--sql`, `--sql-databases`, `--sql-tables` |
| redis | `redis_client.py` (redis-py) | Console, Info, Setup | `--redis`, `--redis-info`, `--redis-keys` |
| grafana | `grafana_client.py` (requests) | Dashboards, Info, Setup | `--grafana-dashboards`, `--grafana-alerts` |
| prometheus | `prometheus_client.py` (requests) | Metrics, Info, Setup | `--prom-query`, `--prom-targets`, `--prom-alerts` |
| winrm | `winrm_client.py` (pywinrm) | PowerShell, Info, Setup | `--ps`, `--cmd` |
| rdp/vnc | `remote_desktop.py` | Launch, Info, Setup | — (запуск внешнего клиента) |

## БЕЗОПАСНОСТЬ

**Claude НИКОГДА не видит:** IP, логины, пароли, порты, TOTP-секреты. Всё в зашифрованном `servers.json`, скрипт `ssh.py` сам читает credentials.

**ЗАПРЕЩЕНО:** читать `~/.server-connections/` напрямую, использовать `--list-full`, добавлять credentials в контекст/логи.

## Команды разработки

```bash
python main.py                  # Запуск
python build.py                 # Сборка exe (auto-bump patch)
python build.py --no-bump       # Сборка без бампа
python build.py --clean         # Очистка + сборка
pip install -r requirements.txt # Зависимости
```

## Workflow — билд → тест → коммит → пуш

**ОБЯЗАТЕЛЬНО** после каждого изменения кода:

1. `python build.py` — собрать exe
2. Запустить exe из `releases/`, убедиться что GUI работает
3. Коммит + пуш:
   ```bash
   git add <файлы> version.py releases/ServerManager-vX.Y.Z-win-x64.exe
   git commit -m "vX.Y.Z: описание"
   git push sensey master
   ```

Старые exe в `releases/` периодически чистить — оставлять первый + последние 5.

- Remote: `sensey`, ветка: `master`

## Версионирование

`build.py` автоинкрементирует patch в `version.py`. Semver: MAJOR (ломающие) | MINOR (фича) | PATCH (автобамп). Для minor/major — вручную изменить `version.py` перед `build.py --no-bump`.

## Архитектура

```
core/                          # Бизнес-логика
├── server_store.py            # CRUD + encrypted JSON + observer + backups
├── encryption.py              # Fernet
├── ssh_client.py              # ShellSession + SFTPSession (Paramiko)
├── sql_client.py              # MariaDB/MSSQL/PostgreSQL
├── redis_client.py            # Redis (SCAN, авто-тип ключей)
├── grafana_client.py          # Grafana REST API
├── prometheus_client.py       # Prometheus REST API
├── telnet_client.py           # Telnet (тот же интерфейс что ShellSession)
├── winrm_client.py            # PowerShell/CMD через WinRM
├── remote_desktop.py          # RDP/VNC (запуск внешнего клиента)
├── connection_factory.py      # Фабрика: тип → клиент (lazy imports)
├── session_pool.py            # LRU пул сессий (max 5)
├── status_checker.py          # Фоновый мониторинг всех типов
├── i18n.py                    # EN/RU/ZH, ~300 ключей, t(key) API
├── claude_setup.py            # Установщик интеграции Claude Code
├── totp.py                    # TOTP/2FA
└── logger.py                  # Rotating file logger

gui/
├── app.py                     # TAB_REGISTRY + TAB_CLASSES → условные табы по типу
├── sidebar.py                 # Список серверов + цветные бейджи типов
├── server_dialog.py           # Адаптивная форма (поля по типу сервера)
├── tabs/
│   ├── terminal_tab.py        # SSH + Telnet терминал (pyte)
│   ├── files_tab.py           # SFTP файл-менеджер
│   ├── query_tab.py           # SQL-редактор + Treeview + Export CSV
│   ├── redis_tab.py           # Redis-консоль + история
│   ├── grafana_tab.py         # Дашборды + алерты
│   ├── prometheus_tab.py      # PromQL + targets
│   ├── powershell_tab.py      # PS/CMD (WinRM)
│   ├── launch_tab.py          # RDP/VNC кнопка Connect
│   ├── info_tab.py            # Инфо (адаптивные поля по типу)
│   ├── keys_tab.py, totp_tab.py, setup_tab.py
│   └── ...
└── widgets/                   # TerminalWidget, StatusBadge, FileList

tools/
├── ssh.py                     # CLI для Claude Code (все типы серверов)
└── skill-ssh.md               # Шаблон скилла /ssh
```

## Ключевые паттерны

- **Duck typing** — все клиенты реализуют `connect/disconnect/check_connection` по соглашению, без ABC
- **Lazy imports** — отсутствие pymysql/redis/etc не ломает приложение
- **TAB_REGISTRY** — `gui/app.py` перестраивает табы при смене типа сервера
- **Observer** — `ServerStore` → UI обновляется автоматически
- **Session pool** — SSH-сессии живут при переключении серверов
- **Auto-sudo** — детекция `[sudo] password for`, автоотправка пароля
- **i18n** — все строки через `t(key)`, 3 языка

## Как пользоваться /ssh

```bash
# SSH
/ssh ALIAS "command"                    # Выполнить команду
/ssh ALIAS --upload local remote        # SFTP upload
/ssh ALIAS --download remote local      # SFTP download
# SQL
/ssh --sql ALIAS "SELECT * FROM t"      # SQL-запрос
/ssh --sql-databases ALIAS              # Список БД
/ssh --sql-tables ALIAS [db]            # Список таблиц
# Redis
/ssh --redis ALIAS "GET key"            # Redis-команда
/ssh --redis-info ALIAS                 # Redis INFO
/ssh --redis-keys ALIAS "pattern"       # SCAN ключей
# Grafana / Prometheus
/ssh --grafana-dashboards ALIAS         # Дашборды
/ssh --prom-query ALIAS "up"            # PromQL
/ssh --prom-targets ALIAS               # Targets
# WinRM
/ssh --ps ALIAS "Get-Process"           # PowerShell
/ssh --cmd ALIAS "dir"                  # CMD
# Общие
/ssh --list                             # Все серверы
/ssh --info ALIAS                       # Инфо (без creds)
/ssh --status                           # Online/offline
```

## Конфигурация

- Серверы: `~/.server-connections/servers.json` (Fernet-encrypted)
- Настройки: `~/.server-connections/settings.json`
- Бэкапы: `~/.server-connections/backups/`

## Дополнительная документация

Читай **по необходимости**: `README.md`, `CHANGELOG.md`, `TERMINAL_AUDIT.md`, `plans/`, `tools/skill-ssh.md`.