server-manager/CLAUDE.md

CLAUDE.md

Проект

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

КРОССПЛАТФОРМЕННОСТЬ — ОБЯЗАТЕЛЬНО

Приложение собирается и работает на Windows и Linux. При любых правках кода:

• Никогда не использовать хардкод Linux-путей (/home, /tmp, /root) без проверки sys.platform
• Никогда не вызывать Linux-only команды (ps, xhost, xdpyinfo, xauth) без if sys.platform != "win32"
• Пути строить через os.path.join() / os.path.expanduser(), не через строковую конкатенацию с /
• Subprocess-вызовы, специфичные для ОС — оборачивать в проверку платформы
• os.scandir("/home") → сломает Windows (FileNotFoundError). Такой код допустим только внутри if sys.platform != "win32"
• Тестировать билд на Windows (python build.py) после каждого изменения

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

Тип	Клиент	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
s3	s3_client.py (boto3)	Objects, Info, Setup	--s3-buckets, --s3-ls, --s3-upload, --s3-download, --s3-delete, --s3-url
rdp/vnc	remote_desktop.py	Launch, Info, Setup	— (запуск внешнего клиента)

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

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

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

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

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. Коммит + пуш:

   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)
├── s3_client.py               # S3/MinIO (boto3)
├── 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         # Дашборды + алерты
│   ├── s3_tab.py              # S3 браузер объектов
│   ├── 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, автоотправка пароля
• Windows sanitize — ssh.py автоматически транслирует Linux-команды (ls, cat, grep, ps, etc.) в Windows-эквиваленты (cmd.exe/PowerShell) при подключении к Windows SSH серверам. Pipe-цепочки и && корректно обрабатываются. Кодировка принудительно UTF-8 через chcp 65001
• i18n — все строки через t(key), 3 языка

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

# 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 ключей
# S3 / MinIO
/ssh --s3-buckets ALIAS                 # Список бакетов
/ssh --s3-ls ALIAS bucket[/prefix]      # Список объектов
/ssh --s3-upload ALIAS local bucket/key # Upload файла
/ssh --s3-download ALIAS bucket/key local # Download файла
/ssh --s3-delete ALIAS bucket/key       # Удалить объект
/ssh --s3-url ALIAS bucket/key [SEC]    # Presigned URL (по умолчанию 1 час)
# 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
/ssh --add ALIAS IP PORT USER PASS      # Добавить сервер
/ssh --remove ALIAS                     # Удалить сервер
/ssh --set-note ALIAS "desc"            # Обновить заметки

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

• Серверы: ~/.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.