# 📑 PRODUCT REQUIREMENTS DOCUMENT (PRD)## 1. Цели проекта

- Основная цель: Создать легковесную CLI-утилиту на Rust для централизованного деплоя хобби-проектов (Node.js, Rust) с локального ПК на слабую VPS по SSH.
- Зачем это нужно: Избежать дублирования скриптов деплоя в репозиториях, полностью разгрузить CPU слабой VPS (сборка только на ПК) и получить удовольствие от разработки пет-проекта.

## 2. Ключевые функции (Scope)

- Центральный конфиг: Все настройки всех проектов хранятся в одном локальном файле (deploy.toml).
- Локальное выполнение: Запуск команд сборки, тестов или линтеров на машине разработчика.
- Синхронизация файлов: Передача скомпилированных артефактов (папок dist, бинарников) на VPS.
- Удаленное выполнение: Запуск команд управления сервисами (pm2 restart, systemctl restart) на VPS через SSH.
- Безопасность: Использование существующего SSH-агента или приватного ключа (~/.ssh/id_rsa), никаких паролей в конфигах.
- Аварийная остановка (Fail-Fast): Если любой шаг (локальный или удаленный) падает с ошибкой, деплой немедленно прекращается.

## 3. Пользовательский сценарий (UX)

1. Разработчик находится в любой папке терминала.
2. Вводит команду: xboctploy my-node-app.
3. Утилита красиво (с логами и цветом) показывает прогресс:

- 🟢 [Local] running: npm run build... Success!
  - 🔵 [SFTP] transferring dist/ to /var/www/node-app... Done!
  - 🟡 [Remote] running: pm2 restart node-app... Success!
  - 🎉 Deploy successful!

### Разрешение конфигурации

Утилита ищет deploy.toml по цепочке: сначала `./deploy.toml` в текущей папке,
если не найден — глобальный `~/.config/xboctploy/deploy.toml`. Локальный файл
приоритетен для простоты тестирования на конкретном проекте.

---

## 🏗️ ARCHITECTURE DECISION RECORD (ADR)## ADR-001: Выбор языка и формата конфигурации

- Решение: Разработка на Rust, формат конфигурации — TOML.
- Обоснование: Rust обеспечивает максимальную скорость запуска CLI и безопасность работы с памятью. TOML выбран как «родной» для экосистемы Rust формат (аналогично Cargo.toml), который проще читать и писать вручную, чем YAML, и он строго типизирован в отличие от JSON.

## ADR-002: Управление зависимостями (Крейты)

Для минимизации кодовой базы и сохранения легковесности утверждается следующий стек библиотек:

- clap (с feature-флагом derive) — для парсинга аргументов командной строки.
- serde + toml — для парсинга файла конфигурации в структуры Rust.
- ssh2-config + ssh2 (или async-ssh2-lite, если потребуется асинхронность) — для чтения системных настроек SSH (~/.ssh/config) и создания SSH/SFTP сессий.
- anyhow — для простой и понятной обработки ошибок без написания кастомных перечислений (enums).

## ADR-003: Модель выполнения (Синхронная vs Асинхронная)

- Решение: Использовать синхронную (блокирующую) модель выполнения.
- Обоснование: Деплой одного проекта происходит строго последовательно (Шаг 1 -> Шаг 2 -> Шаг 3). Асинхронность (tokio) усложнит код, увеличит размер бинарника и не даст преимуществ, так как параллельное выполнение шагов внутри одного деплоя не требуется.

## ADR-004: Механизм передачи файлов

- Решение: Использование протокола SFTP/SCP через встроенные возможности крейта ssh2.
- Обоснование: Отказ от вызова системного rsync через std::process::Command делает утилиту самодостаточной и независимой от того, установлен ли rsync на конкретной ОС (например, на Windows утилита отработает так же успешно, как на Linux).

## ADR-005: Стратегия обработки ошибок и идемпотентность

- Решение: Реализовать стратегию Fail-Fast с выводом stderr упавшей команды. Идемпотентность (как в Ansible) на первом этапе не реализуется.
- Обоснование: Для хобби-проекта проверка состояния системы перед каждым шагом (идемпотентность) избыточна и сильно усложнит архитектуру. Если команда упала, пользователь просто фиксит ошибку и запускает деплой заново.

## ADR-006: Замена ssh2 (libssh2) на russh в качестве SSH-транспорта

- Решение: Вместо крейта ssh2 (обёртка над libssh2) используется чисто Rust-овый russh (0.62.x, crypto-backend ring). Парсер ~/.ssh/config остаётся на ssh2-config (он не зависит от libssh2). Публичный API утилиты синхронный (ADR-003); tokio-runtime живёт внутри модуля ssh и наружу не торчит.
- Обоснование: libssh2 не поддерживает шифр `chacha20-poly1305@openssh.com`, а свежие OpenSSH-серверы (9.x/10.x, в т.ч. дефолтные Ubuntu) часто предлагают только его — подключение падает с Session(-5). Утилита обязана работать с любым стоковым сервером без правки sshd_config. russh умеет chacha20-poly1305, aes-gcm и современные KEX (включая post-quantum гибриды).
- Следствия: проверка host key реализована через TOFU поверх ~/.ssh/known_hosts средствами russh; ssh-agent (этап 6) доступен через встроенные agent-возможности russh; сборка не требует NASM/CMake (в отличие от aws-lc-rs дефолта russh 0.63, поэтому зафиксирован backend ring).

---

## 📈 План развития проекта (Roadmap)

- MVP: Парсинг TOML, последовательный запуск локальных std::process::Command, SSH-коннект по ключу, запуск удаленных команд.
- Files: Реализация копирования одиночных файлов и рекурсивного копирования папок по SFTP.
- UX: Добавление красивого вывода (библиотека indicatif для progress-bar или colored для цветных логов).
- Advanced: Поддержка переменных окружения (.env), интеграция с системным ssh-agent.