docs: initial prd

docs/pdr-adr.md

@@ -0,0 +1,70 @@
+# 📑 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) на первом этапе не реализуется.
+- Обоснование: Для хобби-проекта проверка состояния системы перед каждым шагом (идемпотентность) избыточна и сильно усложнит архитектуру. Если команда упала, пользователь просто фиксит ошибку и запускает деплой заново.
+
+---
+
+## 📈 План развития проекта (Roadmap)
+
+- MVP: Парсинг TOML, последовательный запуск локальных std::process::Command, SSH-коннект по ключу, запуск удаленных команд.
+- Files: Реализация копирования одиночных файлов и рекурсивного копирования папок по SFTP.
+- UX: Добавление красивого вывода (библиотека indicatif для progress-bar или colored для цветных логов).
+- Advanced: Поддержка переменных окружения (.env), интеграция с системным ssh-agent.