gramax-sync

CLI инструмент для синхронизации и управления множеством Git-репозиториев проекта РИТМ (Gramax).

Описание

gramax-sync — консольный инструмент для работы с множеством Git-репозиториев, определённых в конфигурационном файле workspace.yaml. Инструмент позволяет выполнять массовые операции clone, pull, commit, push для всех репозиториев проекта.

Требования

• Python: 3.10 или выше
• Git: установленный и настроенный
• macOS/Linux/Windows: поддерживаются все платформы

Проверка требований

# Проверка версии Python
python3 --version  # Должно быть 3.10+

# Проверка Git
git --version

Установка

Вариант 1: Установка через uv (рекомендуется)

uv — современный, быстрый менеджер пакетов Python.

Шаг 1: Установка uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Или через Homebrew (macOS)
brew install uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

После установки перезапустите терминал или выполните:

source ~/.bashrc  # или ~/.zshrc для zsh

Шаг 2: Клонирование и установка проекта

# Клонировать репозиторий
git clone https://github.com/your-org/gramax-sync.git
cd gramax-sync

# Создать виртуальное окружение и установить зависимости
uv venv
source .venv/bin/activate  # macOS/Linux
# или .venv\Scripts\activate  # Windows

# Установить проект
uv pip install -e .

Шаг 3: Проверка установки

# Проверить, что команда доступна
gramax-sync --version

# Проверить справку
gramax-sync --help

Вариант 2: Установка через pip

# Клонировать репозиторий
git clone https://github.com/your-org/gramax-sync.git
cd gramax-sync

# Создать виртуальное окружение
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# или .venv\Scripts\activate  # Windows

# Установить проект
pip install -e .

Вариант 3: Установка для разработки

# Автоматическая настройка (рекомендуется)
make setup
source .venv/bin/activate

# Или вручную через uv:
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install

# Или вручную через pip:
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
pre-commit install

Подробнее см. DEVELOPMENT.md

Проверка установки

После установки выполните следующие команды для проверки:

# 1. Проверка версии
gramax-sync --version
# Ожидаемый вывод: gramax-sync, version 0.1.0

# 2. Проверка справки
gramax-sync --help
# Должен отобразиться список команд

# 3. Проверка доступности всех команд
gramax-sync auth --help
gramax-sync clone --help
gramax-sync status --help

Устранение проблем установки

Команда не найдена после установки

# Убедитесь, что виртуальное окружение активировано
source .venv/bin/activate

# Проверьте, что пакет установлен
pip list | grep gramax-sync

# Переустановите если нужно
pip install -e .

Ошибка "Python version not supported"

# Проверьте версию Python
python3 --version

# Если версия < 3.10, установите новую версию:
# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3.11

Проблемы с keyring на Linux

# Установите необходимые библиотеки
sudo apt install libsecret-1-dev  # Ubuntu/Debian
sudo dnf install libsecret-devel  # Fedora

Использование

Первоначальная настройка

Перед использованием необходимо выполнить первоначальную настройку:

# Интерактивная настройка
gramax-sync init

# Или с параметрами
gramax-sync init \
  --repo-url https://itsmf.gitlab.yandexcloud.net/ritm-authors/gramax-yaml-manager \
  --branch master \
  --catalog-branch private

Команда init выполняет:

1. Подключение к репозиторию с конфигурациями
2. Проверку доступа и наличия workspace.yaml
3. Авторизацию в GitLab при необходимости
4. Загрузку и отображение структуры секций и каталогов
5. Интерактивный выбор секций/каталогов для работы

Важно: Для репозитория конфигураций используется ветка master (по умолчанию), а для каталогов (репозиториев с кодом) — ветка private.

Работа с репозиториями

# Клонирование всех репозиториев
gramax-sync clone

# Статус всех репозиториев
gramax-sync status

# Обновление всех репозиториев
gramax-sync pull

# Коммит изменений (с автогенерацией сообщения)
gramax-sync commit

# Коммит с кастомным сообщением
gramax-sync commit -m "Update documentation"

# Отправка изменений
gramax-sync push

# Полная синхронизация (pull + commit + push)
gramax-sync sync

# Синхронизация с предварительным просмотром
gramax-sync sync --dry-run

Фильтрация по секциям и каталогам

Все команды поддерживают glob-паттерны для фильтрации:

# Работа только с секциями, начинающимися на "1-"
gramax-sync status --section "1-*"
gramax-sync clone --section "1-методология"

# Работа только с определёнными каталогами
gramax-sync commit --catalog "ritm-*" -m "Fix typos"

# Комбинация фильтров
gramax-sync pull --section "1-*" --catalog "ritm-methodology"

Управление конфигурацией

# Просмотр текущей конфигурации
gramax-sync edit show

# Изменение директории для репозиториев
gramax-sync edit set-workspace-dir --workspace-dir ~/my-workspace
# или интерактивно
gramax-sync edit set-workspace-dir

# Добавление секции или каталога
gramax-sync edit add --section "1-методология" --catalog "ritm-methodology"
# или интерактивно
gramax-sync edit add

# Удаление секции или каталога
gramax-sync edit remove --section "1-методология" --catalog "ritm-methodology"

# Обновление конфигурации с сервера
gramax-sync update

Аутентификация

📖 Подробная информация о правах токена: TOKEN_PERMISSIONS.md

OAuth (рекомендуется)

⚠️ Перед использованием OAuth необходимо создать OAuth Application в GitLab!

1. Создайте OAuth Application:

   • Откройте: https://itsmf.gitlab.yandexcloud.net/-/profile/applications
   • Нажмите "Add new application"
   • Name: gramax-sync
   • Redirect URI: http://localhost:8765/callback
   • Scopes: read_api, read_repository, read_user
   • Скопируйте Application ID

2. Установите Application ID:

   export GRAMAX_OAUTH_APPLICATION_ID="ваш_application_id"
   

   Или используйте автоматическую настройку: ./scripts/setup_oauth.sh

3. Выполните аутентификацию:

   gramax-sync auth login --oauth --url https://itsmf.gitlab.yandexcloud.net
   

Подробная инструкция: OAUTH_SETUP.md

Personal Access Token (альтернатива)

Необходимые права токена:

• read_api - чтение данных через API
• read_repository - чтение содержимого репозиториев
• read_user - получение информации о пользователе

# Войти через Personal Access Token
gramax-sync auth login --pat --url https://itsmf.gitlab.yandexcloud.net

💡 Подробнее: См. TOKEN_PERMISSIONS.md для полной информации о настройке прав токена.

Управление аутентификацией

# Показать статус аутентификации
gramax-sync auth status

# Обновить токен
gramax-sync auth refresh

# Выйти из системы
gramax-sync auth logout --url https://itsmf.gitlab.yandexcloud.net

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

Конфигурация хранится в ~/.config/gramax-sync/config.yaml и создаётся автоматически при выполнении команды init.

Репозиторий с конфигурациями должен содержать файл workspace.yaml:

workspace_dir: ~/ritm-workspace

sections:
  - name: "1-методология"
    catalogs:
      - name: "ritm-methodology"
        source:
          url: "https://gitlab.example.com"

Ветки:

• Репозиторий конфигураций: ветка master (по умолчанию)
• Каталоги (репозитории с кодом): ветка private (по умолчанию)

Директория для репозиториев:

• По умолчанию: ~/{name}-workspace (где name — имя проекта из workspace.yaml)
• Можно изменить: gramax-sync edit set-workspace-dir
• Структура: {workspace_dir}/{section}/{catalog}/

Разработка

Быстрый старт

# Настроить окружение
make setup
source .venv/bin/activate

# Запустить тесты
make test

# Проверить код
make check

# Отформатировать код
make format

Полезные команды

make help          # Показать все команды
make test          # Запустить тесты
make test-cov      # Тесты с покрытием
make lint          # Проверить линтерами
make format        # Отформатировать код
make type-check    # Проверить типы
make check         # Проверить всё
make clean         # Очистить временные файлы

Документация

• DEVELOPMENT.md — Руководство по разработке
• ARCHITECTURE_PRINCIPLES.md — Принципы архитектуры
• ROADMAP.md — Дорожная карта развития
• OAUTH_SETUP.md — Настройка OAuth
• MCP_SETUP.md — MCP Server для Claude Desktop
• TOKEN_PERMISSIONS.md — Права токенов GitLab
• CLAUDE.md — Контекст для Claude Code

MCP Server для Claude Desktop

gramax-sync включает MCP Server для интеграции с Claude Desktop.

Доступные инструменты:

• list_repositories — список секций и каталогов
• get_repository_status — статус репозиториев
• clone_repositories — клонирование
• pull_repositories — обновление
• commit_changes — коммит изменений
• push_changes — отправка изменений
• sync_repositories — полная синхронизация

Подробнее см. MCP_SETUP.md

Лицензия

MIT