server-manager/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Основная цель проекта

ServerManager — Desktop GUI (CustomTkinter + Paramiko) для управления удалёнными серверами. Создан чтобы Claude Code мог управлять серверами через глобальный скилл /ssh, зная только алиасы.

Claude Code  →  /ssh investor "uptime"  →  ssh.py  →  servers.json (encrypted)  →  SSH
     ↑                                                                               ↓
  Видит только alias + команду              Пароли остаются локально            Результат

БЕЗОПАСНОСТЬ — ГЛАВНЫЙ ПРИНЦИП

Claude НИКОГДА не видит и не должен видеть:

• IP-адреса серверов
• Логины (user)
• Пароли
• Порты
• TOTP-секреты

Всё это остаётся в зашифрованном servers.json. Скрипт ssh.py сам читает credentials и подключается. Claude работает только через алиасы.

ЗАПРЕЩЕНО:

• Читать файлы в ~/.server-connections/ напрямую
• Использовать ssh.py --list-full (выводит IP/логины) — имеет WARNING
• Добавлять IP/логины/пароли в memory bank, контекст, логи
• Использовать ssh.py --add — не показывает user@ip:port, но всё равно безопасность важна
• Для получения информации о сервере использовать ssh.py --info ALIAS — безопасно, без credentials

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

# Запуск приложения
python main.py

# Сборка exe (автоматически бампит patch-версию)
python build.py

# Сборка без бампа версии
python build.py --no-bump

# Очистка артефактов + сборка
python build.py --clean

# Установка зависимостей
pip install -r requirements.txt

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

/ssh investor "uptime"                           # Выполнить команду
/ssh main-ovh "systemctl status nginx"           # Команда на другом сервере
/ssh --list                                      # Список серверов (без паролей) + колонка Notes
/ssh --status                                    # Статус всех серверов
/ssh investor --upload /local/file /remote/      # Загрузить файл (прогресс >=1MB)
/ssh investor --download /remote/file /local/    # Скачать файл (прогресс >=1MB)
/ssh investor --ping                             # Проверить доступность
/ssh --info investor                             # Безопасная информация о сервере (без creds)
/ssh --set-note investor "описание сервера"      # Обновить заметки сервера
/ssh --info tor                                  # Поиск по ключевому слову (fuzzy search)
/ssh investor --no-sudo "whoami"                 # Выполнить без sudo
/ssh investor --install-key                      # Установить SSH-ключ на сервер
/ssh --remove investor                           # Удалить сервер (спросит подтверждение)

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

Автоматическое. build.py инкрементирует patch в version.py → __version__ при каждой сборке.

Semver: MAJOR (ломающие) | MINOR (новая фича) | PATCH (автобамп при сборке)

Для minor/major бампа — вручную изменить version.py перед python build.py --no-bump.

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

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

1. Билд — собрать exe:

   python build.py
   

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/ вместе с кодом. Старые exe периодически чистить — оставлять первый + последние 5.

• Remote: sensey (https://git.sensey24.ru/aibot777/server-manager.git)
• Ветка: master

Архитектура

ServerManager/
├── main.py              # Entry point → gui/app.py
├── version.py           # __version__ (auto-bumped by build.py)
├── build.py             # PyInstaller + auto version bump
├── core/                # Business logic
│   ├── server_store.py  # CRUD + encrypted JSON + observer pattern + backups
│   ├── encryption.py    # Fernet symmetric encryption
│   ├── ssh_client.py    # Paramiko: ShellSession + SFTPSession
│   ├── session_pool.py  # LRU session pool (max 5 concurrent)
│   ├── claude_setup.py  # Claude Code integration installer
│   ├── status_checker.py # Background monitoring (every 60s)
│   ├── totp.py          # TOTP/2FA (pyotp)
│   ├── i18n.py          # EN/RU/ZH translations, t(key) API
│   ├── logger.py        # Rotating file logger
│   └── connection_factory.py # Connection factory for different protocols
├── gui/                 # CustomTkinter UI
│   ├── app.py           # Main window: sidebar + tabview
│   ├── sidebar.py       # Server list + session indicators + search
│   ├── tabs/            # Terminal, Files, Info, Keys, TOTP, Setup
│   └── widgets/         # TerminalWidget (pyte), FileList, StatusBadge
├── tools/               # CLI tools (installed to ~/.server-connections/)
│   ├── ssh.py           # SSH utility for Claude Code
│   └── skill-ssh.md     # /ssh skill template
└── releases/            # Built executables

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

• Терминал использует pyte для эмуляции VT-терминала поверх tkinter Text виджета
• Session pool — сессии живут при переключении серверов, буфер сохраняется через pickle
• Auto-sudo — детекция [sudo] password for в выводе, автоматическая отправка пароля через stdin
• Keyboard layout independent — Ctrl+C/V/D/L/Z работают через keycode, не зависят от раскладки
• GUI общается с ServerStore через observer pattern — изменения в хранилище автоматически обновляют UI

Настройка на новой машине

1. git clone https://git.sensey24.ru/aibot777/server-manager.git
2. pip install -r requirements.txt
3. python main.py → вкладка Setup → "Install Everything"
4. Добавить серверы через GUI → Claude Code видит их через /ssh --list

Setup устанавливает: ssh.py + encryption.py → ~/.server-connections/, скилл /ssh → ~/.claude/commands/ssh.md, SSH-ключ ed25519.

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

• Серверы: ~/.server-connections/servers.json (Fernet-encrypted)
• Настройки: ~/.server-connections/settings.json
• Бэкапы: ~/.server-connections/backups/
• Путь конфига можно сменить через GUI: Setup → Configuration → "Change Path"

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

Читай эти файлы по необходимости, а не заранее:

• README.md — полное описание фич, установка, использование (EN/RU/ZH)
• CHANGELOG.md — история изменений по версиям
• TERMINAL_AUDIT.md — аудит терминала: что сделано/не сделано для TUI-совместимости (pyte, 256-color, alternate screen и т.д.)
• plans/ — планы реализации конкретных фич (шифрование, TOTP, undo и др.)
• tools/skill-ssh.md — шаблон скилла /ssh (устанавливается в ~/.claude/commands/)