DndGamePlayer/docs/MANUAL_MAC_UPDATE_UPLOAD.md

# Ручная выкладка macOS-обновлений в публичный feed

Инструкция для случая, когда **сборка делается на вашем Mac вручную**, а файлы для `electron-updater` нужно **вручную** положить в публичный репозиторий обновлений.

Общая схема проекта: приватный репозиторий с кодом, публичный **`DndGamePlayerUpdates`**, ветка **`updates`**, URL feed как в `package.json`:

`https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/`

---

## 1. Что собрать на Mac

В каталоге проекта `dnd_player`:

```bash
cd /путь/к/dnd_player
npm ci
npm run build
```

Сборка установщиков только под macOS (без публикации в сеть, только файлы в `release/`):

```bash
npx electron-builder --mac --publish never \
  --config.publish.provider=generic \
  --config.publish.url="https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/"
```

**Важно:** значение `--config.publish.url=...` должно совпадать с `package.json` → `build.publish.url` (**со слэшем в конце**). Так внутри приложения и в `latest-mac.yml` будет корректный базовый URL для скачивания.

После сборки откройте папку **`release/`** в корне проекта. Там должны быть, среди прочего:

- **`latest-mac.yml`** — обязателен для `electron-updater` на Mac;
- **`.dmg`** и/или **`.zip`** — то, на что ссылается `latest-mac.yml`;
- при необходимости **`.blockmap`** (если electron-builder их создал) — заливайте с теми же именами, что указаны в `latest-mac.yml`.

Имена файлов зависят от версии и архитектур (в конфиге dmg и zip для **x64** и **arm64**). На Apple Silicon без дополнительных шагов часто получается только **arm64**; для отдельного Intel-сборщика нужна своя машина или параметры arch — ориентируйтесь на фактический список файлов в `release/`.

---

## 2. Куда заливать

Файлы должны оказаться в **публичном** репозитории:

| Параметр     | Значение                                                                  |
| ------------ | ------------------------------------------------------------------------- |
| Репозиторий  | `ifontosh/DndGamePlayerUpdates` (подставьте свой owner/repo, если другой) |
| Ветка        | `updates`                                                                 |
| Расположение | **корень ветки** (не подпапка)                                            |

Проверка: в браузере должен открываться, например:

`https://git.mailib.ru/ifontosh/DndGamePlayerUpdates/raw/branch/updates/latest-mac.yml`

Файлы Windows (`latest.yml`, `.exe`, …), которые кладёт CI, должны **остаться** в том же корне. Вы **добавляете или обновляете** только macOS-артефакты и **`latest-mac.yml`**, не удаляя артефакты Windows (если не делаете осознанную зачистку старых версий).

---

## 3. Способ A — через `git` (удобно для больших dmg)

### 3.1. Клон и ветка `updates`

```bash
cd ~/где-удобно
git clone https://git.mailib.ru/ifontosh/DndGamePlayerUpdates.git
cd DndGamePlayerUpdates
git fetch origin
git checkout updates
```

Если ветки `updates` ещё нет:

```bash
git checkout main
git pull
git checkout -b updates
git push -u origin updates
```

Дальше для каждой выкладки работайте в ветке **`updates`**.

### 3.2. Актуализировать локальную копию

```bash
git checkout updates
git pull origin updates
```

### 3.3. Скопировать файлы из `release/` в корень клона

```bash
cp /путь/к/dnd_player/release/latest-mac.yml .
cp /путь/к/dnd_player/release/*.dmg .
cp /путь/к/dnd_player/release/*.zip .
# blockmap, если есть:
cp /путь/к/dnd_player/release/*.blockmap . 2>/dev/null || true
```

Проверка, что Windows-файлы на месте:

```bash
ls -la
```

### 3.4. Коммит и push

```bash
git add latest-mac.yml *.dmg *.zip
git add *.blockmap 2>/dev/null || true
git status
git commit -m "mac: DNDGamePlayer vX.Y.Z (ручная выкладка)"
git push origin updates
```

Для HTTPS обычно используют **персональный токен (PAT)** Gitea вместо пароля, либо настроенный **SSH** (`git@git.mailib.ru:ifontosh/DndGamePlayerUpdates.git`).

### 3.5. Проверка

- Откройте `latest-mac.yml` по raw-URL (см. выше).
- Откройте в браузере прямую ссылку на один из `.dmg` из этого YAML — не должно быть 404.

---

## 4. Способ B — через веб-интерфейс Gitea

Подходит для редких правок; для больших **dmg** удобнее git.

1. Репозиторий `DndGamePlayerUpdates` → ветка **`updates`**.
2. Загрузить или изменить **`latest-mac.yml`** и бинарники (**имена как в `release/`**).
3. Не удалять при этом файлы Windows в корне, если они нужны для PC-обновлений.

---

## 5. Версии и Windows

- В **`latest-mac.yml`** и в именах файлов должна быть та **версия приложения**, которую вы отдаёте пользователям Mac (как в `package.json` на момент сборки).
- **`latest.yml`** (Windows) и **`latest-mac.yml`** (Mac) — разные файлы; версии на платформах могут совпадать или нет. Каждая ОС читает свой YAML.

---

## 6. Подпись кода (кратко)

Без **Developer ID** и при необходимости **нотаризации** macOS может ограничивать запуск после скачивания. На процедуру «залить файлы в репо» это не влияет, но влияет на UX после автообновления. Для продакшена имеет смысл позже настроить `CSC_LINK`, `CSC_KEY_PASSWORD` и нотаризацию по [документации electron-builder](https://www.electron.build/).

---

## 7. Чеклист

1. Локально собрали Mac с `--publish never` и верным `publish.url`.
2. В `release/` есть **`latest-mac.yml`** и все объекты, на которые он ссылается.
3. В ветке **`updates`** в корне репозитория обновили/добавили эти файлы, не снеся Windows-артефакты без необходимости.
4. Проверили raw-URL **`latest-mac.yml`** и ссылку на dmg.
5. В **упакованном** приложении с **активной лицензией** сработает существующий `electron-updater` (задержка первой проверки и cooldown — см. `app/main/update/installAutoUpdater.ts`).

---

## Связанные документы

- Общая схема Gitea, секреты, раннер: [GITEA_AUTO_UPDATE.md](./GITEA_AUTO_UPDATE.md).