cf7-spam-to-telegram/docs/superpowers/specs/2026-04-21-cf7stg-self-hosted-updates-design.md

# CF7 Spam → Telegram — Self-Hosted Updates from Gitea (1.2.0)

**Статус:** FINAL — дизайн подтверждён пользователем (в т.ч. схема release.sh с пост-upload bump `download_url`, changelog-to-HTML конвертация, PUC версия v5.6). Open questions закрыты:
- PUC pinned to **v5.6** (GitHub latest на 2026-04-21).
- Gitea репо `bryzgalov/cf7-spam-to-telegram` — публичный, raw URL отдаёт корректные `ETag` / `Last-Modified` / `Cache-Control: public, max-age=21600` → 304 поддерживается.
- `download_url` в `wp-plugin-info.json` не угадывается — `release.sh` берёт точный `browser_download_url` из ответа Gitea API после upload asset, затем делает финальный commit + tag + push.
- Changelog преобразуется из `readme.txt` блока `== Changelog ==` в HTML (`= 1.2.0 =` → `<h4>`, `* item` → `<li>`) внутри `release.sh`.
- Минификация vendored PUC — не делаем в 1.2.0 (nit, откладываем до фактической необходимости).

## Контекст

**Trigger:** только что выпустили v1.1.0 (silent drop). Деплой 1.1.0 на домработница.рус сделан вручную через `rsync`. Этот же плагин будет деплоиться на другие сайты (washanyanya.ru, потенциально другие). Хочется, чтобы WP-сайты сами получали обновления через стандартный «Плагины → Обновления», без `rsync` и без знания внутренностей.

**Решено в брейнсторме и пост-брейнсторме:**
- Gitea репо `bryzgalov/cf7-spam-to-telegram` — публичный (подтверждено через `GET /api/v1/repos/...` → `"visibility":"public"`). В коде нет секретов.
- Используем **Plugin Update Checker v5.6** от YahnisElsts (https://github.com/YahnisElsts/plugin-update-checker/releases/tag/v5.6), vendored в `includes/lib/plugin-update-checker/`.
- В режиме «Generic JSON server»: PUC ходит в статичный `wp-plugin-info.json` в корне репо (через Gitea raw URL).
- Raw URL отдаёт `ETag` / `Last-Modified` / `Cache-Control: public, max-age=21600` → PUC с conditional GET получает 304 на неизменный JSON.
- Zip-релизы хранятся как Gitea Release assets (создаются вручную через скрипт `release.sh`, чистые благодаря `.gitattributes export-ignore`).
- `download_url` в JSON — не захардкожен, а берётся из `browser_download_url` ответа Gitea API после asset upload (см. раздел «release.sh» ниже).

## Scope

**В scope:**
- Vendored PUC **v5.6** в `includes/lib/plugin-update-checker/`.
- Файл `wp-plugin-info.json` в корне репо (Generic JSON для PUC).
- Инициализация PUC в `Plugin::boot()` через `register_update_checker()`.
- `.gitattributes` с `export-ignore` для всех dev-файлов; `.gitignore` с `dist/`.
- Bash-скрипт `release.sh` (bump → release-commit → push → archive → Gitea release → asset upload → regenerate JSON → json-commit → push → tag → push tag).
- Минимальные тесты на инвариант (PUC файл существует, JSON валидный, version в JSON совпадает с константой плагина, `download_url` ссылается на ожидаемый asset).
- Версия 1.2.0 + changelog в `readme.txt` и в `wp-plugin-info.json` (HTML).

**Вне scope:**
- Кастомный `GiteaApi extends Api` (не нужен — публичный JSON).
- Update-сервер / прокси (не нужен — статичный JSON через raw URL).
- CI/Gitea Actions для авто-сборки релизов (вручную через release.sh достаточно).
- License key management.
- Авто-rollback на старую версию.
- Уведомления о доступном обновлении куда-либо кроме стандартной WP-админки.

## Архитектура

```
Локальная разработка
  ↓ ./release.sh 1.2.0
  1. bump cf7-spam-to-telegram.php + readme.txt
  2. commit "release: 1.2.0" (tmp — без обновлённого JSON)
  3. git push origin main          ← чтобы sha был доступен Gitea для target_commitish
  4. build zip: git archive HEAD --worktree-attributes → dist/cf7-spam-to-telegram-1.2.0.zip
     (zip содержит bumped cf7-spam-to-telegram.php и old wp-plugin-info.json — это ок,
      WP не использует JSON из zip, только live raw URL)
  5. POST Gitea /releases { tag_name: v1.2.0, target_commitish: HEAD sha } → release_id (Gitea создаёт тег на sha)
  6. POST Gitea /releases/{id}/assets (zip) → browser_download_url
  7. регенерировать wp-plugin-info.json (version + download_url + last_updated + changelog HTML)
  8. commit "wp-plugin-info.json: update for 1.2.0" + git push origin main
     (второй коммит — содержит финальный JSON с реальным download_url.
      ⚠ Тег v1.2.0 указывает на ПЕРВЫЙ коммит (release commit из step 2-3) —
      на него же ссылается release entry и собран zip asset. Это корректно:
      zip и tag согласованы; JSON на main живёт «рядом с тегом», обновлён на второй коммит.)

WP-сайт (плагин 1.2.x уже установлен)
  ↓ Plugin::boot() → register_update_checker()
  ↓ PUC раз в 12 часов (WP cron / transient)
GET https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/raw/branch/main/wp-plugin-info.json
  (conditional: If-None-Match / If-Modified-Since → 304 если не менялся)
  ↓ парсит, сравнивает version с CF7STG_VERSION
  ↓ если новее → WP «Плагины → Обновления» показывает кнопку «Обновить»
WP качает zip по download_url (Gitea release asset, public, без auth)
  ↓ распаковывает в wp-content/plugins/cf7-spam-to-telegram/
Плагин обновлён.
```

**Почему два коммита, а не один:** `git archive` читает из commit/tree, не из working dir. Чтобы zip содержал правильный `Version:` — bumps должны быть в коммите. После upload мы знаем `download_url` и добавляем его в JSON — это второй коммит. Альтернатива `git commit --amend --force-push` работает, но делает force-push на `main` — нежелательно. Два fast-forward коммита проще и безопаснее.

**Инвариант (после step 8, на ветке `main`):**
- `wp-plugin-info.json::version` == `cf7-spam-to-telegram.php::CF7STG_VERSION` == `1.2.0`
- tag `v1.2.0` существует (указывает на release commit, в котором `cf7-spam-to-telegram.php` = 1.2.0)
- `download_url` в JSON = реальный Gitea asset для 1.2.0 (проверяемо HEAD-запросом)

Тест `test_wp_plugin_info_json_version_matches_plugin_constant` + проверка `download_url` ловят регрессию «release.sh упал между steps 3 и 8» (zip + tag уже запушены, JSON ещё не обновлён, локальный state рассогласован с remote).

## Изменяемые файлы

| Файл | Что |
|---|---|
| `includes/lib/plugin-update-checker/` (новая папка, ~50 файлов) | PUC v5.6, распакованный из https://github.com/YahnisElsts/plugin-update-checker/archive/refs/tags/v5.6.zip. Закоммичен целиком, без минификации. |
| `wp-plugin-info.json` (новый, корень репо) | Metadata для PUC (Generic JSON format). Регенерируется `release.sh` — в git попадает каждый раз с актуальными `version`/`download_url`/`last_updated`/`sections.changelog`. |
| `includes/class-plugin.php` | В `boot()` добавляется `self::register_update_checker()`. Новый private method. |
| `.gitattributes` (изменяется) | `export-ignore` правила для всех dev-файлов. |
| `release.sh` (новый, корень, `chmod +x`) | Bash-скрипт релиза. |
| `cf7-spam-to-telegram.php` | Bump до `1.2.0` (header `Version:` + константа `CF7STG_VERSION`). |
| `readme.txt` | Bump `Stable tag: 1.2.0` + Changelog `= 1.2.0 =`. |
| `.gitignore` | Добавляется `dist/`. |

## `wp-plugin-info.json` — структура

Пример финального файла (значения иллюстративные — `download_url`, `last_updated`, `sections.changelog` регенерируются `release.sh`):

```json
{
    "name": "CF7 Spam → Telegram",
    "slug": "cf7-spam-to-telegram",
    "version": "1.2.0",
    "download_url": "<browser_download_url из Gitea API — формат определяется Gitea, не угадывается>",
    "homepage": "https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram",
    "requires": "6.0",
    "tested": "6.9",
    "requires_php": "7.4",
    "last_updated": "2026-04-21 17:00:00",
    "author": "Vladimir Bryzgalov",
    "sections": {
        "description": "Forwards CF7 spam submissions to Telegram with heuristic classification (client/unclear/spam/drop labels).",
        "changelog": "<h4>1.2.0</h4><ul><li>New: Self-hosted updates from Gitea ...</li></ul><h4>1.1.0</h4>..."
    }
}
```

Поля `name`, `slug`, `homepage`, `requires`, `tested`, `requires_php`, `author`, `sections.description` — статичные (правим только при реальном изменении, не при каждом релизе). Поля `version`, `download_url`, `last_updated`, `sections.changelog` — генерируются `release.sh`.

## `Plugin::boot()` изменение

```php
public function boot(): void
{
    Settings::register_classifier_filters();
    Dispatcher::register_hooks();
    (new CF7Source())->register();
    self::register_update_checker();   // ← новый

    if (is_admin()) {
        (new Settings_Page())->register();
        (new Dashboard_Widget())->register();
    }
}

private static function register_update_checker(): void
{
    $loader = CF7STG_PLUGIN_DIR . 'includes/lib/plugin-update-checker/plugin-update-checker.php';
    if (!is_file($loader)) return;          // не падаем, если папка отсутствует
    require_once $loader;
    if (!class_exists('YahnisElsts\\PluginUpdateChecker\\v5\\PucFactory')) return;

    \YahnisElsts\PluginUpdateChecker\v5\PucFactory::buildUpdateChecker(
        'https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/raw/branch/main/wp-plugin-info.json',
        CF7STG_PLUGIN_FILE,
        'cf7-spam-to-telegram'
    );
}
```

## `release.sh` (главные шаги)

```
release.sh 1.2.0  →
  1. validate:
     - аргумент валиден как semver (regex ^[0-9]+\.[0-9]+\.[0-9]+$)
     - git tree чистый: `git status --porcelain` пусто (gitignored файлы не считаются)
     - текущая ветка = main
     - remote main in sync (git fetch origin; локальный main ≡ origin/main)
     - ~/.gitea-token существует и читается (chmod 600)
     - тег v1.2.0 ещё не существует локально и на origin
     - команды в PATH: git, curl, jq, unzip, awk, sed
     - readme.txt содержит секцию `= 1.2.0 =` (пользователь написал тело changelog ДО запуска)

  2. bump version (files-only, в working tree, ещё НЕ commit):
     - cf7-spam-to-telegram.php: header `Version:` и define `CF7STG_VERSION`
     - readme.txt: `Stable tag: 1.2.0`
     (wp-plugin-info.json на этом этапе НЕ трогаем — download_url ещё не известен)

  3. release commit + push:
     - git add cf7-spam-to-telegram.php readme.txt
     - git commit -m "release: 1.2.0"
     - git push origin main
     (sha этого коммита нужен Gitea на step 5 как target_commitish)

  4. build zip:
     - mkdir -p dist
     - git archive HEAD --worktree-attributes --format=zip \
         --prefix=cf7-spam-to-telegram/ \
         -o dist/cf7-spam-to-telegram-1.2.0.zip
     - sanity-check: unzip -p dist/...zip cf7-spam-to-telegram/cf7-spam-to-telegram.php \
         | grep -q "Version: 1.2.0" || fail
     - sanity-check: unzip -l dist/...zip | grep -q "includes/lib/plugin-update-checker/" || fail
     - sanity-check: ! unzip -l dist/...zip | grep -q "tests/\|docs/\|composer.json" || fail

  5. Gitea API: create release
     POST /api/v1/repos/bryzgalov/cf7-spam-to-telegram/releases
     headers: Authorization: token $(cat ~/.gitea-token)
     body: {
       "tag_name": "v1.2.0",
       "name": "1.2.0",
       "body": "<changelog entry text>",
       "target_commitish": "<sha HEAD из step 3>"
     }
     → сохранить release_id (Gitea создаёт тег v1.2.0 на target_commitish sha)

  6. Gitea API: upload asset
     POST /api/v1/repos/.../releases/{release_id}/assets?name=cf7-spam-to-telegram-1.2.0.zip
     multipart: file=@dist/cf7-spam-to-telegram-1.2.0.zip
     → JSON ответ, поле browser_download_url → DOWNLOAD_URL

  7. regenerate wp-plugin-info.json:
     - version = 1.2.0
     - download_url = DOWNLOAD_URL
     - last_updated = UTC timestamp (YYYY-MM-DD HH:MM:SS, GMT)
     - sections.changelog = HTML из блока `== Changelog ==` readme.txt:
         `= X.Y.Z =` (строка)              → закрыть открытый `<ul>` если есть, `<h4>X.Y.Z</h4><ul>`
         `* item text` (список)            → `<li>ESCAPE(item text)</li>`
         `** sub item` (вложенный)         → `<li>ESCAPE(sub item)</li>` (плоско в том же <ul>, nit)
         пустая строка или конец блока     → закрыть `</ul>`
         ESCAPE = htmlspecialchars-эквивалент (& < > → &amp; &lt; &gt;)
     (реализация: awk/sed над блоком + jq для embedding строки в JSON с escape)

  8. JSON commit + push:
     - git add wp-plugin-info.json
     - git commit -m "wp-plugin-info.json: update for 1.2.0"
     - git push origin main

  9. echo:
     - Release page URL
     - browser_download_url
     - raw URL wp-plugin-info.json
     - tag на Gitea
     - напоминание: «Проверь в WP: Плагины → Проверить обновления»
```

**Rollback/cleanup в случае failure:** если шаги 5/6 упали — release remote не создан, локальный state = release commit уже в origin. Пользователь может откатить (`git reset --hard HEAD^ && git push -f`, осознанно). В release.sh при ошибке шагов 5-8 — печатается гайд по откату, но скрипт не пытается откатывать сам (слишком рискованно).

**Локальный tag:** Gitea создаёт тег `v1.2.0` на сервере (через API step 5), локально тег отсутствует до явного `git fetch --tags`. Это не блокер — release.sh показывает link на release page, а локальный tag не критичен для работы PUC.

**Token:** хранится в `~/.gitea-token` (chmod 600), не в репо. Создаётся единожды в Gitea UI: `user/settings/applications` → scope **`write:repository`** (этого достаточно для releases и asset upload).

## `.gitattributes` правила

```
# Исключаем dev-файлы из git archive (release zip)
tests/                 export-ignore
docs/                  export-ignore
composer.json          export-ignore
composer.lock          export-ignore
phpunit.xml            export-ignore
.phpunit.result.cache  export-ignore
.beads/                export-ignore
.claude/               export-ignore
CLAUDE.md              export-ignore
AGENTS.md              export-ignore
release.sh             export-ignore
dist/                  export-ignore
.gitignore             export-ignore
.gitattributes         export-ignore
.DS_Store              export-ignore
```

**ВАЖНО:** `includes/lib/plugin-update-checker/` НЕ исключаем — она нужна в zip!

## `.gitignore` изменения

```
dist/
```

Без этого release.sh validation step «git tree чистый» не проходит (untracked `dist/`).

## Тесты

`tests/UpdateCheckerIntegrationTest.php` (extends `Cf7stgTestCase`):

- `test_puc_loader_file_exists()` — `includes/lib/plugin-update-checker/plugin-update-checker.php` существует.
- `test_puc_factory_class_loadable_after_require()` — после `require_once` лоадера класс `YahnisElsts\PluginUpdateChecker\v5\PucFactory` доступен.
- `test_wp_plugin_info_json_is_valid()` — `wp-plugin-info.json` парсится, содержит обязательные ключи `name, slug, version, download_url, sections`.
- `test_wp_plugin_info_json_version_matches_plugin_constant()` — `wp-plugin-info.json::version` совпадает с `CF7STG_VERSION` из `cf7-spam-to-telegram.php` (regex extract). Защита: release.sh забыл обновить JSON — тест поймает.
- `test_wp_plugin_info_json_download_url_matches_version()` — `download_url` содержит подстроку `cf7-spam-to-telegram-{version}.zip` (не угадываем формат Gitea — asset URL может быть `/releases/download/v{v}/{name}` или `/attachments/<uuid>/{name}`, но имя asset'а в URL присутствует по любому). Защита: release.sh забыл обновить `download_url` после bump — тест поймает.

`tests/ZipArchiveBuildTest.php` (опционально, требует git в `$PATH`):
- `test_git_archive_includes_runtime_dirs()` — `git archive HEAD --worktree-attributes -o /tmp/test.zip` распаковывается, содержит `cf7-spam-to-telegram.php`, `includes/`, `admin/`, `includes/lib/plugin-update-checker/plugin-update-checker.php`.
- `test_git_archive_excludes_dev_dirs()` — НЕТ `tests/`, `docs/`, `composer.json`, `release.sh`.

## Error handling

- Отсутствие PUC папки на сайте: `register_update_checker` делает `is_file` + `class_exists` → плагин не падает, обновлений просто нет (как до 1.2.0).
- Недоступность Gitea (network/down/4xx): PUC сам логирует через `error_log`, ничего не показывает в админке. Следующая итерация (12ч) повторит. Юзер не видит «обновлений» — всё.
- Bad JSON в `wp-plugin-info.json`: PUC скипает, error_log.
- Версия в JSON совпадает с локальной → no update notice. Норм.

## Rollout

1. Локально: создать токен в Gitea (один раз, scope `write:repository`), сохранить в `~/.gitea-token` (chmod 600).
2. Локально: подготовить v1.2.0 (vendor PUC v5.6, добавить `wp-plugin-info.json` skeleton, `register_update_checker()` в `class-plugin.php`, `release.sh`, `.gitattributes`, `.gitignore`, тесты, changelog-entry в readme.txt).
3. PHPUnit зелёный → `./release.sh 1.2.0` выполняет всю последовательность из секции «release.sh» выше → получаем Gitea release v1.2.0 + asset + `wp-plugin-info.json` на `main` с реальным `download_url`.
4. На домработница.рус (где сейчас 1.1.0) — один последний раз через `rsync` обновить до 1.2.0. Активация плагина идемпотентная (auto-seed настроек ок). После активации PUC начинает чекать `main` раз в 12ч.
5. Все будущие версии — `./release.sh 1.x.y`; через 12ч (или вручную «Проверить обновления» в WP-админке) сайты сами обновятся.

## Версионирование

- `1.1.0` → `1.2.0` (semver minor: новая фича, обратная совместимость).
- Changelog в `readme.txt`:
  ```
  = 1.2.0 =
  * New: Self-hosted plugin updates from Gitea via plugin-update-checker (Yahnis Elsts v5.6).
    WP «Плагины → Обновления» теперь показывает обновления автоматически (раз в 12ч),
    скачивая чистый zip из Gitea Releases. Источник:
    https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/raw/branch/main/wp-plugin-info.json.
  * Dev: release.sh — релизный bash-скрипт (bump → release-commit → push → archive →
    Gitea release + asset upload → regenerate wp-plugin-info.json с реальным download_url →
    json-commit → push → tag). Два fast-forward коммита на релиз, без force-push.
  * Dev: .gitattributes export-ignore для tests/, docs/, composer.*, phpunit.xml,
    .beads/, .claude/, CLAUDE.md, AGENTS.md, release.sh, dist/ — git archive собирает
    чистый zip без dev-файлов.
  * Dev: .gitignore добавляет dist/ для сборочного артефакта.
  ```

## Future epics (вне scope 1.2.0)

1. **Gitea Actions**: авто-сборка release на push tag (`./release.sh` вручную заменяется на CI). +1 эпик после 1.2.0.
2. **Минификация vendored PUC**: если zip в Gitea asset растёт некомфортно — добавить `includes/lib/plugin-update-checker/{tests,examples,docs}` в `.gitattributes` как `export-ignore`. Чисто cosmetic, nit.
3. **Multi-site update broadcast**: сейчас каждый WP-сайт чекает раз в 12ч. Если будет много сайтов — рассмотреть webhook-push. Пока не актуально.