# 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/логины)
- Добавлять IP/логины/пароли в memory bank, контекст, логи

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

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

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

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

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

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

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

```bash
/ssh investor "uptime"                        # Выполнить команду
/ssh main-ovh "systemctl status nginx"        # Команда на другом сервере
/ssh --list                                   # Список серверов (без паролей)
/ssh --status                                 # Статус всех серверов
/ssh investor --upload /local/file /remote/    # Загрузить файл
/ssh investor --download /remote/file /local/  # Скачать файл
/ssh investor --ping                          # Проверить доступность
```

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

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

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

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

## Git — коммит и пуш

**ОБЯЗАТЕЛЬНО:** После завершения изменений — коммить и пуши:
```bash
git add <изменённые файлы>
git commit -m "vX.Y.Z: описание"
git push sensey master
```

- 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
├── 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/`)