keysloth 0.1.1

data/lib/keysloth.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative 'keysloth/version'
+require_relative 'keysloth/crypto'
+require_relative 'keysloth/git_manager'
+require_relative 'keysloth/file_manager'
+require_relative 'keysloth/config'
+require_relative 'keysloth/logger'
+require_relative 'keysloth/errors'
+
+# Основной модуль KeySloth - Ruby gem для управления зашифрованными секретами
+#
+# KeySloth предоставляет инструменты для безопасного хранения и управления
+# секретами (сертификаты, ключи, конфигурационные файлы) в зашифрованном виде
+# в Git репозиториях.
+#
+# @example Базовое использование
+#   # Получение секретов из репозитория
+#   KeySloth.pull(repo_url: 'git@github.com:company/secrets.git',
+#                 branch: 'main',
+#                 password: 'secret_password',
+#                 local_path: './secrets')
+#
+#   # Отправка секретов в репозиторий
+#   KeySloth.push(repo_url: 'git@github.com:company/secrets.git',
+#                 branch: 'main',
+#                 password: 'secret_password',
+#                 local_path: './secrets')
+#
+# @example Использование с конфигурационным файлом
+#   # Создайте файл .keyslothrc:
+#   # repo_url: "git@github.com:company/secrets.git"
+#   # branch: "main"
+#   # local_path: "./secrets"
+#
+#   # Теперь достаточно указать только пароль:
+#   KeySloth.pull(password: 'secret_password', config_file: '.keyslothrc')
+#
+# @example Обработка ошибок
+#   begin
+#     KeySloth.pull(repo_url: repo_url, password: password, local_path: './secrets')
+#   rescue KeySloth::CryptoError => e
+#     puts "Ошибка расшифровки: #{e.message}"
+#   rescue KeySloth::RepositoryError => e
+#     puts "Ошибка репозитория: #{e.message}"
+#   rescue KeySloth::FileSystemError => e
+#     puts "Ошибка файловой системы: #{e.message}"
+#   end
+#
+# @example Использование в CI/CD с переменными окружения
+#   # Установите переменные окружения:
+#   # export SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa)"
+#   # export SECRET_PASSWORD="your_password"
+#   # export GIT_AUTHOR_NAME="CI Bot"
+#   # export GIT_AUTHOR_EMAIL="ci@company.com"
+#
+#   KeySloth.pull(
+#     repo_url: 'git@github.com:company/secrets.git',
+#     password: ENV['SECRET_PASSWORD'],
+#     local_path: './secrets'
+#   )
+#
+# @author KeySloth Team
+# @since 0.1.0
+module KeySloth
+  class << self
+    # Получает и расшифровывает секреты из удаленного Git репозитория
+    #
+    # @param repo_url [String] URL Git репозитория (SSH)
+    # @param branch [String] Ветка для получения секретов (по умолчанию 'main')
+    # @param password [String] Пароль для расшифровки секретов
+    # @param local_path [String] Локальный путь для сохранения расшифрованных секретов
+    # @param config_file [String, nil] Путь к файлу конфигурации (опционально)
+    # @return [Boolean] true при успешном выполнении
+    # @raise [KeySloth::RepositoryError] при ошибках работы с репозиторием
+    # @raise [KeySloth::CryptoError] при ошибках расшифровки
+    # @raise [KeySloth::FileSystemError] при ошибках файловой системы
+    def pull(repo_url:, password:, local_path:, branch: 'main', config_file: nil)
+      start_time = Time.now
+      logger = Logger.new
+      config = Config.load(config_file)
+
+      # Аудит логирование начала операции
+      logger.audit('pull_start', {
+                     repo_url: repo_url,
+                     branch: branch,
+                     local_path: local_path,
+                     config_file: config_file
+                   })
+
+      # Объединяем параметры с конфигурацией (параметры имеют приоритет, nil не перетирает)
+      merged_config = config.merge({
+        repo_url: repo_url,
+        branch: branch,
+        local_path: local_path
+      }.compact)
+
+      logger.info("Начинаем получение секретов из репозитория: #{repo_url}")
+
+      git_manager = GitManager.new(merged_config[:repo_url], logger)
+      file_manager = FileManager.new(logger)
+      crypto = Crypto.new(password, logger)
+
+      # Создаем backup перед операцией
+      if File.exist?(merged_config[:local_path])
+        file_manager.create_backup(merged_config[:local_path])
+      end
+
+      # Клонируем/обновляем репозиторий и получаем зашифрованные файлы
+      encrypted_files = git_manager.pull_encrypted_files(merged_config[:branch])
+
+      # Создаем локальную директорию если не существует
+      file_manager.ensure_directory(merged_config[:local_path])
+
+      # Расшифровываем и сохраняем файлы с проверкой целостности
+      integrity_failures = []
+
+      encrypted_files.each do |encrypted_file|
+        original_filename = encrypted_file[:name].gsub(/\.enc$/, '')
+
+        # Проверяем целостность зашифрованного файла
+        integrity_check = crypto.verify_integrity_detailed(encrypted_file[:content])
+
+        unless integrity_check[:valid]
+          error_msg = "Ошибка целостности для #{original_filename}: #{integrity_check[:error] || 'структура данных повреждена'}"
+          logger.error(error_msg)
+          integrity_failures << { file: original_filename, error: integrity_check[:error] }
+          next
+        end
+
+        logger.debug("Проверка целостности пройдена для: #{original_filename}")
+
+        # Расшифровываем файл
+        decrypted_content = crypto.decrypt_file(encrypted_file[:content])
+        local_file_path = File.join(merged_config[:local_path], original_filename)
+
+        # Проверяем целостность расшифрованного файла
+        if decrypted_content.nil? || decrypted_content.empty?
+          logger.warn("Расшифрованный файл пустой: #{original_filename}")
+        end
+
+        file_manager.write_file(local_file_path, decrypted_content)
+        logger.info("Расшифрован файл: #{original_filename} (размер: #{decrypted_content.length} байт)")
+      end
+
+      # Проверяем наличие ошибок целостности
+      unless integrity_failures.empty?
+        failure_details = integrity_failures.map { |f| "#{f[:file]}: #{f[:error]}" }.join('; ')
+        raise CryptoError, "Обнаружены ошибки целостности файлов: #{failure_details}"
+      end
+
+      duration = Time.now - start_time
+      logger.info("Успешно получено и расшифровано #{encrypted_files.size} файлов")
+
+      # Аудит логирование успешного завершения
+      logger.security_log('pull', :success, duration: duration, details: {
+                            files_count: encrypted_files.size,
+                            repo_url: repo_url,
+                            branch: merged_config[:branch]
+                          })
+
+      true
+    rescue StandardError => e
+      duration = Time.now - start_time
+      logger.security_log('pull', :failure, duration: duration, details: {
+                            error: e.class.name,
+                            repo_url: repo_url,
+                            branch: branch
+                          })
+      raise
+    ensure
+      git_manager&.cleanup
+    end
+
+    # Шифрует и отправляет секреты в удаленный Git репозиторий
+    #
+    # @param repo_url [String] URL Git репозитория (SSH)
+    # @param branch [String] Ветка для отправки секретов (по умолчанию 'main')
+    # @param password [String] Пароль для шифрования секретов
+    # @param local_path [String] Локальный путь с секретами для шифрования
+    # @param config_file [String, nil] Путь к файлу конфигурации (опционально)
+    # @param commit_message [String] Сообщение коммита (опционально)
+    # @return [Boolean] true при успешном выполнении
+    # @raise [KeySloth::RepositoryError] при ошибках работы с репозиторием
+    # @raise [KeySloth::CryptoError] при ошибках шифрования
+    # @raise [KeySloth::FileSystemError] при ошибках файловой системы
+    def push(repo_url:, password:, local_path:, branch: 'main',
+             config_file: nil, commit_message: nil)
+      start_time = Time.now
+      logger = Logger.new
+      config = Config.load(config_file)
+
+      # Аудит логирование начала операции
+      logger.audit('push_start', {
+                     repo_url: repo_url,
+                     branch: branch,
+                     local_path: local_path,
+                     config_file: config_file,
+                     commit_message: commit_message
+                   })
+
+      # Объединяем параметры с конфигурацией (параметры имеют приоритет, nil не перетирает)
+      merged_config = config.merge({
+        repo_url: repo_url,
+        branch: branch,
+        local_path: local_path
+      }.compact)
+
+      logger.info("Начинаем отправку секретов в репозиторий: #{repo_url}")
+
+      git_manager = GitManager.new(merged_config[:repo_url], logger)
+      file_manager = FileManager.new(logger)
+      crypto = Crypto.new(password, logger)
+
+      # Проверяем существование локальной директории
+      unless file_manager.directory_exists?(merged_config[:local_path])
+        raise FileSystemError, "Локальная директория не существует: #{merged_config[:local_path]}"
+      end
+
+      # Получаем список файлов для шифрования
+      local_files = file_manager.collect_secret_files(merged_config[:local_path])
+
+      if local_files.empty?
+        logger.warn('Не найдено файлов секретов для отправки')
+        return true
+      end
+
+      # Клонируем репозиторий и переключаемся на нужную ветку
+      git_manager.prepare_repository(merged_config[:branch])
+
+      # Шифруем и подготавливаем файлы
+      encrypted_files = local_files.map do |file_path|
+        content = file_manager.read_file(file_path)
+        encrypted_content = crypto.encrypt_file(content)
+        relative_path = file_manager.get_relative_path(file_path, merged_config[:local_path])
+        encrypted_filename = "#{relative_path}.enc"
+
+        {
+          path: encrypted_filename,
+          content: encrypted_content
+        }
+      end
+
+      # Записываем зашифрованные файлы в репозиторий
+      git_manager.write_encrypted_files(encrypted_files)
+
+      # Создаем коммит и отправляем
+      commit_msg = commit_message || "Update secrets: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      git_manager.commit_and_push(commit_msg, merged_config[:branch])
+
+      duration = Time.now - start_time
+      logger.info("Успешно зашифровано и отправлено #{encrypted_files.size} файлов")
+
+      # Аудит логирование успешного завершения
+      logger.security_log('push', :success, duration: duration, details: {
+                            files_count: encrypted_files.size,
+                            repo_url: repo_url,
+                            branch: merged_config[:branch],
+                            commit_message: commit_msg
+                          })
+
+      true
+    rescue StandardError => e
+      duration = Time.now - start_time
+      logger.security_log('push', :failure, duration: duration, details: {
+                            error: e.class.name,
+                            repo_url: repo_url,
+                            branch: branch
+                          })
+      raise
+    ensure
+      git_manager&.cleanup
+    end
+  end
+end

data/task/cr.md

@@ -0,0 +1,59 @@
+# Change Request: Поддержка SSH ключей id_ed25519 и улучшение UX
+
+## Контекст проблемы
+При запуске команды (например, `keysloth pull`) возникла ошибка:
+
+```
+Ошибка выполнения операции: SSH ключ не найден: /Users/<user>/.ssh/id_rsa
+```
+
+Причина: в `KeySloth::GitManager#create_ssh_credentials` по умолчанию ожидаются ключи формата RSA (`~/.ssh/id_rsa` и `~/.ssh/id_rsa.pub`). На машине пользователя используются ключи Ed25519 (`id_ed25519`, `id_ed25519.pub`).
+
+## Временные решения (workarounds)
+1. Использовать ключи из переменных окружения (подходит для локали и CI/CD):
+```bash
+export SSH_PRIVATE_KEY="$(cat ~/.ssh/id_ed25519)"
+export SSH_PUBLIC_KEY="$(cat ~/.ssh/id_ed25519.pub)"
+keysloth pull -r git@github.com:USER/REPO.git -p "PASSWORD"
+```
+
+2. Создать симлинки под ожидаемые имена (быстро, локально):
+```bash
+ln -s ~/.ssh/id_ed25519 ~/.ssh/id_rsa
+ln -s ~/.ssh/id_ed25519.pub ~/.ssh/id_rsa.pub
+```
+
+3. Сгенерировать отдельный RSA‑ключ (если принципиально):
+```bash
+ssh-keygen -t rsa -b 4096 -C "you@example.com" -f ~/.ssh/id_rsa
+# добавить ~/.ssh/id_rsa.pub в GitHub/GitLab
+```
+
+## Предложения по доработке
+1. Поддержать Ed25519 «из коробки» в `create_ssh_credentials`:
+   - Приоритет: переменные окружения `SSH_PRIVATE_KEY`/`SSH_PUBLIC_KEY` (как сейчас).
+   - Fallback: искать пары ключей по стандартным путям в порядке:
+     - `~/.ssh/id_rsa(.pub)`
+     - `~/.ssh/id_ed25519(.pub)`
+   - Если пара найдена — использовать; иначе выбрасывать `AuthenticationError` с подсказками.
+
+2. Добавить конфигурируемый путь к ключу:
+   - Env: `KEYSLOTH_SSH_KEY_PATH` (если задан — использовать `<path>` и `<path>.pub`).
+   - Опция CLI: `--ssh-key PATH` (пробрасывать в `GitManager`).
+
+3. Рассмотреть поддержку ssh-agent:
+   - Использовать `Rugged::Credentials::SshKeyFromAgent` при отсутствии файлов и env.
+
+4. Улучшить сообщение об ошибке:
+   - Печатать проверённые пути, быстрые шаги: env, симлинк, `--ssh-key`.
+
+## Тестирование
+- Добавить тесты в `spec/keysloth/git_manager_spec.rb`:
+  - только `id_rsa`
+  - только `id_ed25519`
+  - ключи через ENV
+  - путь через `KEYSLOTH_SSH_KEY_PATH`
+  - отсутствие ключей → `AuthenticationError`
+
+## Документация
+- Обновить README (раздел «Настройка SSH ключей») и `task/test_plan.md` (раздел про SSH) с примерами для Ed25519 и `--ssh-key`/env.

data/task/plan.md

@@ -0,0 +1,169 @@
+# План реализации KeySloth - Ruby Gem для управления зашифрованными секретами
+
+## 1. Подготовка проекта
+
+### 1.1 Структура gem'а
+- [x] Создать основную структуру ruby gem'а
+- [x] Настроить gemspec файл с описанием и зависимостями
+- [x] Создать базовую структуру директорий (lib/, bin/, spec/, etc.)
+- [x] Настроить Gemfile с необходимыми зависимостями
+
+### 1.2 Инфраструктура
+- [x] Настроить RSpec для тестирования
+- [x] Настроить RuboCop для линтинга кода
+- [x] Создать базовый Rakefile
+- [ ] Настроить CI/CD (GitHub Actions)
+
+## 2. Основная функциональность
+
+### 2.1 Криптографический модуль
+- [x] Реализовать модуль шифрования/дешифрования файлов
+- [x] Выбрать алгоритм шифрования (AES-256-GCM)
+- [x] Реализовать генерацию ключей из паролей (PBKDF2)
+- [x] Добавить обработку различных типов файлов (.cer, .p12, .mobileprovisioning, .json)
+
+### 2.2 Работа с Git репозиториями
+- [x] Реализовать клонирование удаленного репозитория (через системные команды)
+- [x] Реализовать переключение на нужную ветку
+- [x] Реализовать получение файлов из репозитория
+- [x] Реализовать коммит и push изменений обратно в репозиторий
+- [x] Добавить очистку временных файлов после работы
+
+### 2.3 Управление файловой системой
+- [x] Реализовать создание локальной директории для секретов
+- [x] Реализовать извлечение зашифрованных файлов в локальную директорию
+- [x] Реализовать упаковку измененных файлов для отправки в репозиторий
+- [x] Добавить валидацию путей и проверку прав доступа
+
+## 3. Интерфейс командной строки
+
+### 3.1 Команда получения секретов
+- [x] Реализовать команду `pull` для получения и дешифровки секретов
+- [x] Параметры: URL репозитория, ветка, пароль, путь к локальной директории
+- [x] Добавить валидацию входных параметров
+- [x] Реализовать подробное логирование процесса
+- [x] Добавить обработку ошибок (неверный пароль, недоступный репозиторий, etc.)
+
+### 3.2 Команда отправки секретов
+- [x] Реализовать команду `push` для шифровки и отправки секретов
+- [x] Те же параметры что и для pull
+- [x] Добавить проверку изменений перед отправкой
+- [x] Реализовать создание коммита с описанием изменений
+- [x] Добавить подтверждение действия перед отправкой
+
+### 3.3 Help команда
+- [x] Реализовать команду `help` с описанием всех команд
+- [x] Добавить примеры использования
+- [x] Добавить описание параметров и опций
+- [x] Создать man-страницу или подробную документацию
+
+### 3.4 Дополнительные команды
+- [x] Реализовать команду `init` для первичной настройки
+- [x] Добавить команду `status` для проверки состояния локальных секретов
+- [x] Реализовать команду `validate` для проверки целостности файлов
+- [x] Добавить команду `restore` для восстановления из backup'а
+- [x] Добавить команду `version` для отображения версии
+
+## 4. Безопасность и обработка ошибок
+
+### 4.1 Безопасность
+- [x] Добавить проверку целостности зашифрованных файлов
+
+### 4.2 Обработка ошибок
+- [x] Добавить логирование ошибок и отладочной информации
+
+## 5. Тестирование
+
+### 5.1 Unit тесты
+- [x] Написать тесты для криптографического модуля
+- [x] Написать тесты для работы с файловой системой
+- [x] Написать тесты для Git операций
+- [x] Написать тесты для CLI интерфейса
+
+## 6. Документация и комментарии
+
+### 6.1 Код документация
+- [x] Добавить подробные комментарии ко всем публичным методам
+- [x] Создать YARD документацию
+- [x] Добавить примеры использования в комментариях
+- [x] Документировать все исключения и edge cases
+
+### 6.2 Пользовательская документация
+- [x] Создать README.md с инструкциями по установке и использованию
+- [x] Написать CHANGELOG.md
+- [x] Создать примеры использования в Makefile
+- [x] Добавить troubleshooting guide
+
+## 7. Публикация и развертывание
+
+### 7.1 Подготовка к публикации
+- [x] Финальная проверка всех тестов
+- [x] Код-ревью и рефакторинг
+- [x] Проверка безопасности и соответствия best practices
+- [x] Финализация версии и тегирование
+
+### 7.2 Публикация
+- [ ] Публикация gem'а в RubyGems.org
+- [ ] Создание GitHub release с описанием изменений
+- [ ] Обновление документации на публичных ресурсах
+- [ ] Создание примеров интеграции с популярными CI/CD системами
+
+## 8. Поддержка и развитие
+
+### 8.1 Мониторинг
+- [ ] Настроить мониторинг использования gem'а
+- [ ] Создать систему сбора обратной связи
+- [ ] Настроить автоматические уведомления о проблемах
+
+### 8.2 Развитие
+- [ ] Планирование будущих фич (GUI интерфейс, интеграции)
+- [ ] Поддержка обратной совместимости
+- [ ] Регулярные обновления зависимостей
+- [ ] Поддержка сообщества пользователей
+
+
+
+
+
+## Вопросы для уточнения
+
+### 9.1 Технические детали
+- [x] Какой алгоритм шифрования использовать? (AES-256-GCM, ChaCha20-Poly1305, другой?)
+  **Ответ:** AES-256-GCM - наиболее подходящий выбор, так как обеспечивает защиту целостности данных и аутентификацию, широко поддерживается, имеет хорошую производительность и является стандартом индустрии.
+
+- [x] В каком формате хранить зашифрованные файлы в репозитории? (один архив или отдельные файлы?)
+  **Ответ:** Отдельные зашифрованные файлы с сохранением исходных имен + расширение .enc. Это обеспечивает гранулярность изменений в Git, позволяет отслеживать изменения конкретных файлов и упрощает парциальное обновление секретов.
+
+- [x] Как именно будет называться gem? (KeySloth или другое имя?)
+  **Ответ:** KeySloth - подходящее название, отражает суть инструмента (ключи + медленная и осторожная работа с секретами). Альтернатива: SecretSloth.
+
+### 9.2 Git и аутентификация
+- [x] Поддерживать только HTTPS или также SSH ключи для доступа к репозиторию?
+  **Ответ:** Только SSH ключи. Это обеспечивает более высокий уровень безопасности и исключает необходимость передачи паролей/токенов. В CI/CD системах также можно настроить SSH ключи через deploy keys или service accounts.
+
+- [x] Как передавать учетные данные Git? (параметры команды, переменные окружения, git credential helper?)
+  **Ответ:** Использование SSH ключей. Для локальной работы - стандартные SSH ключи из ~/.ssh/. Для CI/CD - настройка SSH ключей через переменные окружения (SSH_PRIVATE_KEY) или секреты системы CI/CD. Автоматическое добавление хостов в known_hosts при необходимости.
+
+### 9.3 CLI интерфейс
+- [x] Нужен ли namespace для команд? (например `keysloth pull` vs отдельные исполняемые файлы?)
+  **Ответ:** Да, использовать namespace `keysloth <command>`. Это современный подход, обеспечивает чистоту пространства имен системы и упрощает добавление новых команд. Основные команды: `keysloth pull`, `keysloth push`, `keysloth help`.
+
+- [x] Нужна ли поддержка конфигурационных файлов для хранения URL репозитория и других параметров?
+  **Ответ:** Да, опциональная поддержка `.keyslothrc` (YAML формат) для хранения URL репозитория, ветки по умолчанию, путей. Параметры командной строки должны иметь приоритет над конфигом для гибкости в CI/CD.
+
+### 9.4 Обработка конфликтов
+- [x] Как обрабатывать ситуацию, когда несколько разработчиков одновременно изменяют секреты?
+  **Ответ:** Использовать стратегию "fail-fast": перед push выполнять pull и проверять изменения. При обнаружении конфликтов - прекращать операцию с подробным сообщением об ошибке и рекомендациями по разрешению. Добавить команду `keysloth status` для проверки состояния.
+
+- [x] Как разрешать конфликты при слиянии изменений в Git?
+  **Ответ:** Не автоматически. Инструмент должен обнаруживать конфликты и требовать ручного разрешения администратором проекта. Предоставлять детальную информацию о конфликтующих файлах и временных метках изменений.
+
+### 9.5 Дополнительные требования
+- [x] Какие версии Ruby должны поддерживаться? (2.7+, 3.0+ и т.д.)
+  **Ответ:** Ruby 2.7+ для совместимости с современными CI/CD системами и не слишком устаревшими проектами. Активно тестировать на Ruby 2.7, 3.0, 3.1, 3.2. Указать minimum_ruby_version = "2.7.0" в gemspec.
+
+- [x] Нужны ли подробные логи работы? В какой формат? (stdout, файлы?)
+  **Ответ:** Да, многоуровневое логирование. По умолчанию INFO в stdout. Параметр `--verbose` для DEBUG уровня. Параметр `--quiet` для только ERROR. Логи в простом текстовом формате с timestamp для удобства отладки в CI/CD.
+
+- [x] Нужна ли возможность создания резервных копий перед изменениями?
+  **Ответ:** Да, автоматическое создание backup'ов локальной директории с секретами перед выполнением pull операций. Хранить последние 3 копии с временными метками. Команда `keysloth restore` для восстановления из backup'а. 

data/task/ragged_removing.md

@@ -0,0 +1,103 @@
+# План отказа от Rugged/libgit2 и переход на системный git
+
+## Текущая проблема
+- Использование `Rugged` (libgit2) приводит к частым проблемам:
+  - Нужна сборка нативного гема: `cmake`, `libgit2`, `libssh2`, `openssl`, корректный `PKG_CONFIG_PATH`.
+  - Неполная сборка без SSH → ошибка `unsupported URL protocol` при `git@...`.
+  - Предзагрузка `RUBYOPT=-r rugged` ломает другие ruby-команды до установки гема (`gem install` и т.п.).
+- Для пользователей и CI это поднимает порог входа и вызывает нестабильность.
+
+Вывод: переходим на системный `git` (через `Open3`), убираем зависимость от `rugged`.
+
+## Цели
+- Исключить `rugged`/`libgit2` и любые шаги по их установке.
+- Сохранить поведение `pull`/`push`/ветки/коммиты/cleanup.
+- Улучшить DX: всё работает там, где есть стандартный `git` и SSH.
+
+## Таск‑лист миграции
+1) Подготовка
+- Убедиться, что `keysloth.gemspec` не тянет `rugged` (оставляем как есть, rugged не в зависимостях).
+- Создать ветку `feat/system-git`.
+
+2) Реализация системного Git в `KeySloth::GitManager`
+- Заменить логику на вызовы системного `git`:
+  - clone: `git clone --depth 1 <repo_url> <tmp>` (если ветка не `main`, затем checkout).
+  - checkout: `git checkout <branch>` или `git checkout -b <branch> --track origin/<branch>`.
+  - ensure up-to-date: `git fetch origin <branch>` + сравнить `git rev-parse HEAD` и `git rev-parse origin/<branch>`; при расхождении — `git pull --ff-only` или ошибка.
+  - list .enc: `Dir.glob("**/*.enc", base: tmp)` + `File.read`.
+  - clear .enc: `Dir.glob("**/*.enc", base: tmp)` + `File.delete`.
+  - write .enc: создать директории, `File.write`.
+  - add & commit: `git add -A`, `git commit -m "msg"` (автор из ENV: `GIT_AUTHOR_*`/`GIT_COMMITTER_*` или `-c user.name=... -c user.email=...`).
+  - push: `git push origin <branch>`.
+- Инкапсулировать выполнение команд в метод: `run_git(cmd, env: {})` с возвратом `[stdout, stderr, status]`, логированием и конвертацией ошибок в `RepositoryError`.
+- Сохранить `cleanup` (удаление временной директории).
+
+3) Аутентификация SSH
+- По умолчанию использовать стандартный SSH (ssh-agent, `~/.ssh/config`).
+- Если заданы `SSH_PRIVATE_KEY`/`SSH_PUBLIC_KEY` (CI):
+  - создать временную директорию ключей, записать файлы, `chmod 600`.
+  - выставить `GIT_SSH_COMMAND="ssh -i <path> -o StrictHostKeyChecking=no"` для всех git‑команд.
+- Опционально поддержать `KEYSLOTH_SSH_KEY_PATH` (если указан — использовать его в `GIT_SSH_COMMAND`).
+- Позже: можно добавить поддержку `id_ed25519` в явном виде, но системный `ssh` уже это умеет.
+
+4) Обработка ошибок и логирование
+- Для каждой git‑команды логировать: краткое описание, команду, код выхода; при ошибке показывать stderr.
+- Генерировать `RepositoryError` с понятным сообщением и советом (проверить доступ/ветку/SSH).
+
+5) Тесты
+- Переписать `spec/keysloth/git_manager_spec.rb`:
+  - мокать `Open3.capture3` и проверять последовательность вызовов.
+  - кейсы: clone/checkout/fetch/pull ok, нет ветки, нет изменений для коммита, запись файлов, push ok, ошибка SSH/доступа, ошибка git.
+  - кейсы с `GIT_SSH_COMMAND` и env‑ключами.
+
+6) Документация и примеры
+- Обновить `task/test_plan.md`:
+  - удалить блок «Важно про Rugged» и шаги `gem install rugged`, `RUBYOPT=-r rugged`.
+  - уточнить, что требуется установленный `git` и корректный SSH.
+  - поправить пример для push: использовать `git@github.com:...`, а не `ssh@github.com:...`.
+- Обновить `README.md`:
+  - удалить упоминания rugged и предзагрузки.
+  - добавить раздел «Зависимости»: нужен только `git`.
+  - в CI‑примере убрать установку rugged и шаг с RUBYOPT, при необходимости показать `GIT_SSH_COMMAND`.
+- Добавить запись в `CHANGELOG.md` (0.1.x → 0.1.(x+1)): «Переведён на системный git; удалены инструкции про rugged».
+
+7) Релиз
+- Прогнать тесты и линтинг.
+- Обновить версию (`lib/keysloth/version.rb`).
+- Сформировать gem, smoke‑тест: `pull/push` на чистой машине с только `git`.
+- Создать GitHub release.
+
+## Критерии готовности
+- `keysloth pull/push` работают без установки rugged/libgit2.
+- Все тесты зелёные; покрыт основной happy‑path и ошибки SSH.
+- `README.md`/`task/test_plan.md` не содержат упоминаний rugged, примеры актуальны.
+- Ошибки `git` отображаются с понятными причинами и советами.
+
+## Согласованные решения
+1) Поведение pull
+- Выполняем `git fetch origin <branch>` и затем `git pull --ff-only`. При невозможности fast-forward — завершаем с ошибкой с понятным сообщением.
+
+2) Автор коммита
+- Требуются глобальные настройки Git: `user.name` и `user.email`. Перед коммитом проверяем их наличие, при отсутствии — ошибка с подсказкой настроить `git config --global`.
+
+3) Приоритет и способ SSH-аутентификации
+- Приоритет источников ключей: `KEYSLOTH_SSH_KEY_PATH` → `SSH_PRIVATE_KEY`/`SSH_PUBLIC_KEY` (создаём временные файлы, `chmod 600`) → системные ключи/агент (`~/.ssh`, `ssh-agent`).
+- При использовании нестандартных ключей выставляем `GIT_SSH_COMMAND` с вызовом системного `ssh`.
+
+4) Passphrase-ключи
+- Поддержка passphrase-ключей не входит в объём. Возможна работа через `ssh-agent` или безфразные ключи.
+
+5) Стратегия клонирования
+- По умолчанию используем `git clone --depth 1` (shallow). Если для `pull --ff-only` потребуется история, выполняем однократно `git fetch --unshallow` и повторяем `pull`.
+- Предусматриваем переключатель окружения `KEYSLOTH_FULL_CLONE=true` для полного клона при необходимости.
+
+6) Очистка `.enc`
+- Очищаем глобально все `**/*.enc` в рабочем дереве перед записью новых файлов. Риски (удаление «чужих» `.enc`, гонки) осознанно принимаются; перед очисткой выполняем `fetch` + `pull --ff-only` для минимизации расхождений.
+
+7) Зависимости и SSH
+- Используются стандартные системные инструменты: Git CLI и системный SSH (обычно OpenSSH). Дополнительные нативные библиотеки не требуются.
+- В CI при использовании ключей из ENV формируем `GIT_SSH_COMMAND`, например: `ssh -i <path> -o IdentitiesOnly=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null`.
+- В локальной разработке проверку хостов не отключаем.
+
+8) Версионирование
+- Увеличиваем patch-версию.