gitverse-release 3.5.0 → 3.7.0

package/README.md

@@ -17,6 +17,7 @@
 - ⚙️ **Гибкая конфигурация** через `.gitversereleaserc.json`
 - 🔧 **Автогенерация commitlint конфига** из release конфигурации
 - 🪝 **Хуки beforeCommit** для автоматической подготовки файлов перед релизом
+- 📤 **Бинарная дистрибуция** — публикация платформенных npm-пакетов (по паттерну esbuild/biome)
 
 ## Установка
 
@@ -308,6 +309,250 @@ npx gitverse-release generate-commitlint --scope-required
 ✅ **Меньше ошибок** - нет риска рассинхронизации конфигов
 ✅ **CI-friendly** - легко интегрируется в pipelines для проверки актуальности конфига
 
+## Бинарная дистрибуция
+
+Инструмент поддерживает создание и публикацию платформенных npm-пакетов по паттерну, используемому esbuild, biome, bun и другими инструментами.
+
+### Как это работает
+
+1. **Платформенные пакеты** (`@scope/name-linux-x64`, `@scope/name-darwin-arm64`, ...) содержат только бинарник для конкретной платформы с фильтрами `os`/`cpu` в package.json
+2. **Основной пакет** объявляет их в `optionalDependencies` и содержит JS wrapper, который находит и запускает нужный бинарник
+3. npm автоматически устанавливает только подходящий платформенный пакет
+
+### Быстрый старт
+
+```bash
+# Preview без публикации
+npx gitverse-release publish-binaries --dry-run
+
+# Только генерация пакетов (без публикации)
+npx gitverse-release generate-binary-packages
+
+# Генерация и публикация
+npx gitverse-release publish-binaries
+```
+
+### Конфигурация
+
+Добавьте секцию `binaries` в `.gitversereleaserc.jsonc`:
+
+```jsonc
+{
+  "binaries": {
+    "enabled": true,
+    "scope": "@rainypixel",           // npm scope (опционально)
+    "name": "yougile",                 // базовое имя пакетов
+    "binName": "yougile",              // имя бинарника в $PATH (опционально)
+    "distDir": "./dist",               // директория с бинарниками
+    "outDir": "./npm",                 // куда генерировать пакеты
+    "platforms": [
+      "linux-x64",
+      "linux-arm64",
+      "darwin-x64",
+      "darwin-arm64",
+      "win32-x64"
+    ],
+    "publishCommand": "npm publish --access public",
+    "mainPackage": "./package.json",   // основной package.json
+    "continueOnError": false,          // продолжать при ошибке
+    "retryAttempts": 3                 // retry для публикации
+  }
+}
+```
+
+### Пакеты без scope
+
+`scope` опционален. Без него пакеты публикуются как `myapp-linux-x64` вместо `@org/myapp-linux-x64`:
+
+```jsonc
+{
+  "binaries": {
+    "enabled": true,
+    "name": "myapp",                   // без scope!
+    "distDir": "./dist",
+    "platforms": ["linux-x64", "darwin-arm64"]
+  }
+}
+// Результат: myapp-linux-x64, myapp-darwin-arm64
+```
+
+### Кастомный шаблон имени пакета
+
+Используйте `packageNameTemplate` для гибкой настройки имён:
+
+```jsonc
+{
+  "binaries": {
+    "name": "myapp",
+    "packageNameTemplate": "{{name}}-bin-{{platform}}"
+  }
+}
+// Результат: myapp-bin-linux-x64
+```
+
+```jsonc
+{
+  "binaries": {
+    "name": "myapp",
+    "scope": "@org",
+    "packageNameTemplate": "@{{scope}}/{{name}}-cli-{{platform}}"
+  }
+}
+// Результат: @org/myapp-cli-linux-x64
+```
+
+**Плейсхолдеры:** `{{scope}}`, `{{name}}`, `{{platform}}`
+
+**Дефолтные шаблоны:**
+- Без scope: `{{name}}-{{platform}}`
+- Со scope: `@{{scope}}/{{name}}-{{platform}}`
+
+### Структура бинарников
+
+#### Формат "directory" (по умолчанию)
+
+Бинарники в директориях:
+
+```
+dist/
+  yougile-linux-x64/
+    yougile            # бинарник для linux x64
+  yougile-darwin-arm64/
+    yougile            # бинарник для macOS ARM
+  yougile-win32-x64/
+    yougile.exe        # бинарник для Windows
+```
+
+#### Формат "tar.gz"
+
+Бинарники в tar.gz архивах (удобно для CI артефактов):
+
+```jsonc
+{
+  "binaries": {
+    "inputFormat": "tar.gz",
+    "sourceBinName": "cli",            // имя бинарника внутри архива
+    "platformMap": {                    // маппинг имён архивов на платформы
+      "linux-amd64": "linux-x64",
+      "darwin-arm64": "darwin-arm64",
+      "windows-x64": "win32-x64"
+    }
+  }
+}
+```
+
+Структура архивов:
+```
+dist/
+  myapp-linux-amd64.tar.gz    # содержит cli (или cli внутри поддиректории)
+  myapp-darwin-arm64.tar.gz
+  myapp-windows-x64.tar.gz
+```
+
+**Опции для tar.gz:**
+- `inputFormat: "tar.gz"` — включает режим архивов
+- `sourceBinName` — имя бинарника внутри архива (если отличается от `name`)
+- `platformMap` — маппинг ключей в именах архивов на npm платформы
+
+### Генерируемая структура
+
+```
+npm/
+  @rainypixel/
+    yougile-linux-x64/
+      package.json     # { "os": ["linux"], "cpu": ["x64"], "bin": {...} }
+      bin/yougile      # скопированный бинарник
+      README.md
+    yougile-darwin-arm64/
+      ...
+```
+
+### CLI опции
+
+```bash
+# Publish binaries
+npx gitverse-release publish-binaries [options]
+
+# Generate only (без публикации)
+npx gitverse-release generate-binary-packages [options]
+
+Опции:
+  --dry-run              Preview без изменений
+  --version <ver>        Override версии
+  --platforms <list>     Конкретные платформы (comma-separated)
+  --generate-only        Только генерация (для publish-binaries)
+  --skip-main-package    Не обновлять основной package.json
+  --verbose              Подробный вывод
+```
+
+### Кастомная команда публикации
+
+Команда публикации поддерживает плейсхолдеры:
+
+```jsonc
+{
+  "binaries": {
+    "publishCommand": "npm publish --access public --registry https://registry.npmjs.org"
+    // Доступные плейсхолдеры:
+    // {{packageDir}} - путь к пакету
+    // {{version}} - версия
+    // {{platform}} - платформа (linux-x64, etc.)
+    // {{scope}} - npm scope
+    // {{name}} - имя пакета
+  }
+}
+```
+
+### Пример dry-run вывода
+
+```
+🔍 DRY RUN MODE
+
+📦 Binary Distribution:
+  Scope: @rainypixel
+  Name: yougile
+  Version: 1.2.3
+  Platforms: linux-x64, darwin-arm64
+
+📁 Packages to generate:
+  npm/@rainypixel/yougile-linux-x64/
+  npm/@rainypixel/yougile-darwin-arm64/
+
+📝 Main package updates:
+  optionalDependencies:
+    "@rainypixel/yougile-linux-x64": "1.2.3"
+    "@rainypixel/yougile-darwin-arm64": "1.2.3"
+  bin:
+    "yougile": "bin/yougile.js"
+
+🚀 Publish command: npm publish --access public
+```
+
+### Интеграция с CI/CD
+
+```yaml
+jobs:
+  publish-binaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Скачать бинарники из других jobs или артефактов
+      - name: Download binaries
+        uses: actions/download-artifact@v4
+        with:
+          name: binaries
+          path: dist/
+
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+
+      - name: Publish platform packages
+        run: npx gitverse-release publish-binaries
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
 ## Конфигурация
 
 ### Полный пример
@@ -358,6 +603,17 @@ npx gitverse-release generate-commitlint --scope-required
     "scopeRequired": false,
     "headerMaxLength": 100,
     "comments": true
+  },
+  "binaries": {
+    "enabled": false,
+    "scope": "@myorg",
+    "name": "myapp",
+    "distDir": "./dist",
+    "outDir": "./npm",
+    "platforms": ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"],
+    "publishCommand": "npm publish --access public",
+    "continueOnError": false,
+    "retryAttempts": 3
   }
 }
 ```
@@ -467,11 +723,20 @@ env:
 # Создать релиз
 npx gitverse-release [package] [options]
 
+# Инициализировать конфигурацию
+npx gitverse-release init [options]
+
 # Генерировать commitlint конфиг
 npx gitverse-release generate-commitlint [options]
 
 # Создать только GitVerse Release для существующего тега (recovery mode)
 npx gitverse-release create-only --tag <tag> [--package <name>]
+
+# Публикация бинарных пакетов
+npx gitverse-release publish-binaries [options]
+
+# Генерация бинарных пакетов (без публикации)
+npx gitverse-release generate-binary-packages [options]
 ```
 
 ### Опции для релиза
@@ -508,6 +773,18 @@ npx gitverse-release create-only --tag <tag> [--package <name>]
   --verbose                  Подробный вывод
 ```
 
+### Опции для publish-binaries / generate-binary-packages
+
+```
+Опции:
+  --dry-run                  Preview без изменений
+  --version <ver>            Override версии (default: из package.json)
+  --platforms <list>         Конкретные платформы (comma-separated)
+  --generate-only            Только генерация, без публикации
+  --skip-main-package        Не обновлять основной package.json
+  --verbose                  Подробный вывод
+```
+
 ## CI/CD интеграция
 
 ### GitVerse Actions

package/dist/binaries.d.ts

@@ -0,0 +1,74 @@
+import type { BinaryCliOptions, BinaryDistributionResult } from "./types";
+/**
+ * Генерирует бинарные пакеты без публикации.
+ *
+ * Эта функция создаёт платформенные npm-пакеты с бинарниками,
+ * но не публикует их. Используйте для подготовки пакетов перед публикацией.
+ *
+ * Процесс:
+ * 1. Загружает и валидирует конфигурацию
+ * 2. Проверяет наличие бинарников для каждой платформы
+ * 3. Генерирует package.json, README.md для каждого платформенного пакета
+ * 4. Копирует бинарники в соответствующие директории
+ * 5. Генерирует JS wrapper для основного пакета (если не skipMainPackage)
+ *
+ * @param options - Опции генерации
+ * @param options.config - Путь к конфиг-файлу
+ * @param options.version - Версия (по умолчанию из git tags)
+ * @param options.platforms - Конкретные платформы для генерации
+ * @param options.dryRun - Режим предпросмотра без записи файлов
+ * @param options.skipMainPackage - Не генерировать JS wrapper
+ * @returns Результат генерации с информацией об успешных и неудачных пакетах
+ *
+ * @example
+ * ```typescript
+ * const result = await generateBinaryPackages({
+ *   dryRun: true,
+ *   platforms: ["linux-x64", "darwin-arm64"],
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Generated ${result.packages.length} packages`);
+ * }
+ * ```
+ */
+export declare function generateBinaryPackages(options?: BinaryCliOptions): Promise<BinaryDistributionResult>;
+/**
+ * Генерирует и публикует бинарные пакеты в npm registry.
+ *
+ * Выполняет полный цикл бинарной дистрибуции:
+ * 1. Загружает и валидирует конфигурацию
+ * 2. Проверяет наличие бинарников для каждой платформы
+ * 3. Генерирует платформенные npm-пакеты (package.json, README.md, бинарник)
+ * 4. Публикует платформенные пакеты с retry при временных ошибках
+ * 5. Обновляет основной package.json с optionalDependencies
+ * 6. Генерирует JS wrapper для автоматического выбора бинарника
+ *
+ * Поведение при ошибках контролируется параметром `continueOnError` в конфиге:
+ * - `false` (default): останавливается при первой ошибке
+ * - `true`: продолжает, собирая ошибки в warnings
+ *
+ * @param options - Опции публикации
+ * @param options.config - Путь к конфиг-файлу
+ * @param options.version - Версия (по умолчанию из git tags)
+ * @param options.platforms - Конкретные платформы для публикации
+ * @param options.dryRun - Режим предпросмотра без записи файлов и публикации
+ * @param options.generateOnly - Только генерация, без публикации
+ * @param options.skipMainPackage - Не обновлять основной package.json
+ * @param options.verbose - Подробный вывод
+ * @returns Результат с информацией о сгенерированных и опубликованных пакетах
+ *
+ * @example
+ * ```typescript
+ * // Dry-run для проверки
+ * const preview = await publishBinaries({ dryRun: true });
+ *
+ * // Реальная публикация
+ * const result = await publishBinaries({ verbose: true });
+ *
+ * if (!result.success) {
+ *   console.error("Errors:", result.errors);
+ * }
+ * ```
+ */
+export declare function publishBinaries(options?: BinaryCliOptions): Promise<BinaryDistributionResult>;