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

Добро пожаловать в документацию Criage - высокопроизводительного пакетного менеджера, написанного на Go!

Установка

Из исходного кода

Самый простой способ установить Criage - собрать из исходного кода:

git clone https://github.com/criage-oss/criage-client.git
cd criage-client
go build -o criage
sudo mv criage /usr/local/bin/

Требования

  • Go 1.24 или выше
  • Git для клонирования репозитория
  • Права администратора для установки в системные пути

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

criage --version
Примечание: После установки перезапустите терминал или обновите переменную PATH.

Основы использования

Первые шаги

После установки Criage готов к использованию. Основные команды:

# Показать справку
criage --help

# Показать версию
criage --version

# Показать список установленных пакетов
criage list

Структура команд

Criage использует структуру команд вида: criage [команда] [параметры] [флаги]

Пример: criage install my-package --version 1.2.3 --global

Управление пакетами

Установка пакетов

# Установить пакет
criage install package-name

# Установить конкретную версию
criage install package-name --version 1.2.3

# Глобальная установка
criage install package-name --global

# Установить с dev зависимостями
criage install package-name --dev

# Установить локальный файл .criage
criage install ./my-package-1.0.0.criage

Удаление пакетов

# Удалить пакет
criage uninstall package-name

# Полное удаление с конфигурацией
criage uninstall package-name --purge

# Удалить глобальный пакет
criage uninstall package-name --global

Обновление пакетов

# Обновить пакет
criage update package-name

# Обновить все пакеты
criage update --all

# Обновить глобальные пакеты
criage update --global

Поиск и информация

# Поиск пакетов
criage search keyword

# Показать информацию о пакете
criage info package-name

# Показать установленные пакеты
criage list

# Показать устаревшие пакеты
criage list --outdated

Разработка пакетов

Создание нового пакета

# Создать пакет с базовыми настройками
criage create my-package

# Создать с дополнительными параметрами
criage create my-package --author "Your Name" --description "Package description"

Структура пакета

Созданный пакет имеет следующую структуру:

my-package/
├── criage.yaml          # Манифест пакета
├── src/                 # Исходные файлы
├── build.json          # Конфигурация сборки
└── README.md           # Документация

Сборка пакета

# Сборка с настройками по умолчанию
criage build

# Указать формат и уровень сжатия
criage build --format tar.zst --compression 6

# Указать выходной файл
criage build --output my-package-1.0.0.criage

Публикация пакета

# Опубликовать в репозитории используя обновленный API
criage publish --registry https://packages.example.com --token YOUR_TOKEN

# Или загрузить напрямую через API v1
curl -X POST https://packages.example.com/api/v1/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Управление репозиториями

Добавление репозиториев

# Добавить репозиторий
criage repo add myrepo https://packages.example.com

# Добавить с токеном авторизации
criage repo add private-repo https://private.example.com --token YOUR_TOKEN

# Добавить с приоритетом
criage repo add priority-repo https://priority.example.com --priority 10

Управление репозиториями

# Показать список репозиториев
criage repo list

# Показать информацию о репозитории
criage repo info myrepo

# Удалить репозиторий
criage repo remove myrepo

# Обновить индексы всех репозиториев
criage repo update

# Получить статистику репозитория
criage repo stats myrepo

# Обновить индекс репозитория (требует админ токен)
curl -X POST https://packages.example.com/api/v1/refresh \
  -H "Authorization: Bearer ADMIN_TOKEN"
Приоритет репозиториев: Высокий приоритет (большое число) означает, что пакеты из этого репозитория будут предпочтительны при поиске.

🤖 MCP Server

Criage MCP Server предоставляет полный функционал пакетного менеджера через протокол MCP (Model Context Protocol) для интеграции с AI инструментами.

Что такое MCP Server?

MCP Server позволяет AI ассистентам напрямую взаимодействовать с Criage для:

  • 🔍 Поиска и установки пакетов
  • 📦 Управления зависимостями
  • 🆕 Создания новых пакетов
  • 🔨 Сборки и публикации пакетов
  • 📊 Получения информации о пакетах и репозиториях

Установка MCP Server

# Перейти в директорию mcp-server
cd mcp-server

# Установить зависимости
go mod tidy

# Собрать сервер
go build -o criage-mcp-server .

Интеграция с Claude Desktop

Добавьте MCP Server в конфигурацию Claude Desktop (%APPDATA%\Claude\config.json на Windows):

{
  "mcpServers": {
    "criage": {
      "command": "C:\\путь\\к\\criage-mcp-server.exe",
      "args": [],
      "env": {}
    }
  }
}

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

📦 Управление пакетами

  • install_package - Установка пакета
  • uninstall_package - Удаление пакета
  • update_package - Обновление пакета
  • list_packages - Список пакетов

🔍 Поиск и исследование

  • search_packages - Поиск пакетов
  • package_info - Информация о пакете
  • repository_info - Информация о репозитории
  • get_repository_stats - Статистика репозитория

🛠️ Разработка

  • create_package - Создание пакета
  • build_package - Сборка пакета
  • publish_package - Публикация пакета
  • refresh_repository_index - Обновление индекса (админ)

Примеры использования через AI

Поиск и установка веб-фреймворка:
"Найди пакет веб-фреймворка и установи его"

AI автоматически выполнит:
1. Поиск пакетов с ключевым словом "web framework"
2. Предложит подходящие варианты
3. Установит выбранный пакет
Создание нового проекта:
"Создай новый пакет для работы с API"

AI выполнит:
1. Создание структуры пакета
2. Настройка манифеста
3. Добавление базовых файлов

Конфигурация сервера

MCP Server использует стандартную конфигурацию Criage из ~/.criage/config.json. При первом запуске автоматически создается конфигурация по умолчанию с обновленными эндпоинтами API v1.

Обновление API v1: Все взаимодействия с репозиториями теперь используют эндпоинты /api/v1/* для улучшенной совместимости и новых функций, таких как статистика репозитория и админ операции.

Логирование и отладка

# Включить подробное логирование
set CRIAGE_DEBUG=1

# Запустить сервер
./criage-mcp-server
Совместимость: MCP Server полностью совместим с основным клиентом Criage и поддерживает все форматы архивов и операции.
Безопасность: MCP Server работает с полными правами пользователя. Убедитесь, что вы доверяете AI системе перед предоставлением доступа к управлению пакетами.

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

Просмотр настроек

# Показать все настройки
criage config list

# Показать конкретную настройку
criage config get cache.path

Изменение настроек

# Установить значение
criage config set cache.path /custom/cache/path

# Установить логический параметр
criage config set parallel.enabled true

Основные параметры конфигурации

  • cache.path - путь к кэшу пакетов
  • parallel.enabled - включить параллельную обработку
  • compression.default - алгоритм сжатия по умолчанию
  • repository.timeout - таймаут для запросов к репозиториям

Форматы сжатия

Criage поддерживает несколько алгоритмов сжатия для оптимизации размера и скорости:

Доступные форматы

  • tar.zst - Zstandard (рекомендуется) - хороший баланс скорости и сжатия
  • tar.lz4 - LZ4 - максимальная скорость, среднее сжатие
  • tar.xz - XZ/LZMA - максимальное сжатие, низкая скорость
  • tar.gz - Gzip - универсальная совместимость
  • zip - ZIP - совместимость с Windows

Выбор формата при сборке

# Использовать Zstandard с уровнем сжатия 3
criage build --format tar.zst --compression 3

# Использовать LZ4 для максимальной скорости
criage build --format tar.lz4

# Использовать XZ для минимального размера
criage build --format tar.xz --compression 9
Внимание: Высокие уровни сжатия (7-9) значительно увеличивают время сборки.

🌍 Локализация

Criage оснащен динамической системой локализации, которая поддерживает несколько языков без необходимости изменения кода. Система автоматически определяет доступные языки и предоставляет простой способ добавления новых локализаций.

Поддерживаемые языки

  • 🇬🇧 Английский (en) - По умолчанию
  • 🇷🇺 Русский (ru)
  • 🇩🇪 Немецкий (de)
  • 🇪🇸 Испанский (es)

Установка языка

Criage автоматически определяет язык вашей системы. Вы также можете установить его вручную с помощью переменных окружения:

# Установить язык для текущей сессии
export LANG=de_DE.UTF-8
criage --help

# Или использовать переменную LANGUAGE
export LANGUAGE=es
criage install package-name

Добавление новых языков

Добавление поддержки нового языка простое:

Пример: Добавление поддержки французского языка
  1. Создать locale/translations_fr.json
  2. Создать repository/locale/translations_fr.json
  3. Перезапустить приложение
# Пример файла французских переводов
{
  "app_description": "Gestionnaire de paquets haute performance",
  "cmd_install": "Installer un paquet",
  "cmd_search": "Rechercher des paquets",
  "installing_package": "Installation du paquet %s...",
  "packages_found": "%d paquets trouvés:"
}

Покрытие языков

Язык Код Основное приложение Репозиторий Статус
Английский en Завершено
Русский ru Завершено
Немецкий de Завершено
Испанский es ⚠️ Частично
Вклад в проект: Помогите нам улучшить локализацию Criage! Смотрите наше подробное руководство по локализации для получения полных инструкций по добавлению новых языков или улучшению существующих переводов.

📡 Справочник API

Criage Repository Server предоставляет RESTful API для операций управления пакетами. Все эндпоинты используют префикс /api/v1/*.

Базовые эндпоинты

Информация о репозитории

  • GET /api/v1/ - Информация о репозитории
  • GET /api/v1/stats - Статистика репозитория
  • POST /api/v1/refresh - Обновление индекса (админ)

Операции с пакетами

  • GET /api/v1/packages/{name} - Информация о пакете
  • GET /api/v1/search?q={query} - Поиск пакетов
  • POST /api/v1/upload - Загрузка пакета (админ)
  • GET /api/v1/download/{name}/{version}/{file} - Скачивание файла

Формат ответов API

Все ответы API следуют единой структуре:

{
  "success": true,
  "message": "Операция успешно завершена",
  "data": { /* Данные ответа */ }
}

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

Админ операции требуют аутентификации через Bearer токен:

Authorization: Bearer ваш-админ-токен

Структуры данных

PackageEntry

{
  "name": "package-name",
  "description": "Описание пакета", 
  "author": "Имя Автора",
  "license": "MIT",
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "keywords": ["тег1", "тег2"],
  "latestVersion": "1.2.3",
  "versions": [/* объекты VersionEntry */],
  "downloads": 12345,
  "updated": "2024-12-13T10:30:00Z"
}

VersionEntry

{
  "version": "1.2.3",
  "description": "Описание версии",
  "dependencies": {"dep1": "^1.0.0"},
  "devDependencies": {"devdep1": "^2.0.0"},
  "files": [/* объекты FileEntry */],
  "size": 1048576,
  "checksum": "sha256:abc123...",
  "uploaded": "2024-12-13T10:30:00Z",
  "downloads": 456
}

FileEntry

{
  "os": "windows",
  "arch": "amd64", 
  "format": "zip",
  "filename": "package-1.2.3-windows-amd64.zip",
  "size": 524288,
  "checksum": "sha256:def456..."
}

Решение проблем

Частые проблемы

Ошибка "command not found"

Убедитесь, что Criage установлен в PATH:

# Проверить PATH
echo $PATH

# Добавить в ~/.bashrc или ~/.zshrc
export PATH=$PATH:/usr/local/bin

Проблемы с правами доступа

# Установить права на исполнение
chmod +x /usr/local/bin/criage

# Или установить в домашнюю директорию
mkdir -p ~/bin
mv criage ~/bin/
export PATH=$PATH:~/bin

Ошибки сети при работе с репозиториями

# Проверить доступность репозитория
criage repo check

# Увеличить таймаут
criage config set repository.timeout 30

Отладка

Для получения подробной информации используйте флаг verbose:

criage install package-name --verbose

Получение помощи

  • Используйте criage --help для общей справки
  • Используйте criage [command] --help для справки по конкретной команде
  • Создайте issue на GitHub