cut-stable

name	cut-stable
description	Promote a rolling -rN candidate to stable vX.Y.Z (no suffix). Bumps AppVersion, creates fresh tag without suffix, full rebuild + Mac/Linux CI, restores Latest, deletes -rN.
when	Latest -rN passed full verification gate (build + tests + Mac/Linux CI green + 12 assets + MCP-verify + **mandatory pre-cut live update gate**) AND user gave explicit "cut" / "ok" / "promote" command (rule 6 в `CLAUDE.md`, lessons v2.31.2 / v2.31.7). Cut НЕ autonomous.

Cut a stable release

Promotes vX.Y.Z-rN to stable vX.Y.Z (без суффикса). Per CLAUDE.local.md "Build / push steps" — обязательно НОВЫЙ тэг без -rN, а не просто переброс prerelease flag.

Pre-flight (verification gate, autonomous)

Все 6 чек-боксов должны быть зелёные:

1. dotnet build -c Release → 0 errors
2. Regression tests зелёные (VlessServersResolverTests, ConfigGeneratorEmptyServersGuardTests, FreeConfigAggregatorPreserveTests)
3. Mac CI на последнем -rN — success
4. Linux CI на последнем -rN — success
5. gh release view vX.Y.Z-rN --json assets --jq '.assets|length' → 12
6. Live update gate PASS (см. секцию ниже) — обязательная mandatory.
7. (soft) No user-reported regressions за ~24h после shipping последнего -rN

Если все зелёные — ждём explicit user команду "cut" / "ok" / "promote" (rule 6 в CLAUDE.md). Cut НЕ autonomous. User паузит явной командой "hold stable".

Mandatory pre-cut live update gate

Why this exists: green CI + green tests + MCP-verify of the change itself do NOT cover the auto-update path. v2.31.2 cut'нулся на all-green и оказался partial-fix (UI regression поймали только хотфиксом v2.31.3). v2.31.7 cut'нулся на all-green и его helper.cmd parser bug сломал 100% upgrades — поймали через ~7 дней по user-reports. Conclusion: тот же binary который user скачает со stable должен в чистой среде успешно auto-update'нуться к ТЕКУЩЕМУ кандидату ПЕРЕД cut'ом. Иначе stable shipping = выпуск broken update path в production.

When to run: после verification gate (5 первых чекбоксов) PASS, перед тем как просить user'а "cut" / "ok" / "promote". Если этот gate упал — НЕ просим cut, а ship'аем -r(N+1) с фиксом и крутим cycle заново.

Steps (выполнять в том же VM/host где работаем над release; не трогать prod-инсталляцию VPNRouter):

a) Identify previous stable release tag:

gh release list --repo PavelLizunov/VPNRouter --exclude-pre-releases --limit 1

Запомни tag (e.g. v2.31.7). Это baseline для теста.

b) Download install ZIP в чистый temp dir:

rm -rf /c/Temp/stable-test && mkdir -p /c/Temp/stable-test
gh release download <previous-stable-tag> --repo PavelLizunov/VPNRouter \
  --pattern 'VPNRouter-*-windows-x64.zip' --dir /c/Temp/stable-test

c) Extract + launch + initial settle:

cd /c/Temp/stable-test
powershell -Command "Expand-Archive -Path 'VPNRouter-*-windows-x64.zip' -DestinationPath ./extracted -Force"
powershell -Command "Start-Process -FilePath './extracted/VPNRouter.App.exe'"

Wait 30s для App init (settings load, update check spin-up).

d) Trigger update к ТЕКУЩЕМУ кандидату -rN. Два пути:

• UI path (preferred — exercises full user flow): MCP click Settings → "Проверить обновления" / "Check for updates" → дождаться detection -rN кандидата (ensure Experimental channel is on, иначе -rN неvidible) → нажать "Установить" / "Install".
• Programmatic (fallback если UI broken): дёрнуть update helper напрямую через CLI если такая команда есть. Если нет — UI path mandatory.

e) Wait for update flow to complete. Helper .cmd должен:

1. Stop running App + Service (если установлен)
2. xcopy new files over old install
3. Relaunch App Ожидаемое время: 30-90s. Tail update.log:

tail -f "$LOCALAPPDATA/VPNRouter/Logs/update.log"   # или %ProgramData%/VPNRouter/logs/update.log

f) Verify new version installed cleanly:

powershell -Command "(Get-Item /c/Temp/stable-test/extracted/VPNRouter.App.exe).VersionInfo.ProductVersion"

Должна быть <candidate-rN-version> (e.g. 2.31.8-r10). Также:

powershell -Command "(Get-Item /c/Temp/stable-test/extracted/VPNRouter.Core.dll).VersionInfo.FileVersion"

AppVersion должна совпадать с candidate (правило #5 — string Version ВКЛЮЧАЯ -rN суффикс).

g) 30-second smoke: убедись App работает после update.

• Если есть test профиль (free configs / saved subscription) — connect → status «Подключено» → disconnect.
• Если нет — минимум: главное окно открывается, нет crash dialog'а, status показывает «Готов» / «Ready», нет красных error toast'ов. MCP screenshot для визуальной фиксации PASS.

h) Cleanup:

powershell -Command "Get-Process VPNRouter.App,VPNRouter.Service,sing-box -ErrorAction SilentlyContinue | Stop-Process -Force"
rm -rf /c/Temp/stable-test

i) IF ANY STEP FAILS (download error, install hang, helper crash, version mismatch, App не запускается после update, smoke fails):

• DO NOT CUT. Stable cut откладывается.
• Diagnose root cause (logs: update.log, vpnrouter.log, Event Viewer для Service, helper.cmd output).
• Fix в коде / helper.cmd / install.ps1.
• Ship -r(N+1) через ship-rolling-candidate skill.
• Run этот gate заново на новом -r(N+1).
• Repeat until PASS.

Detailed report для user'а (часть "request cut" сообщения):

• Previous stable tag downloaded: vX.Y.(Z-1) (or same Z, prior -rN cut)
• Update path triggered: UI / programmatic
• Helper.cmd exit code + log tail
• ProductVersion + FileVersion после update (proof of successful flip)
• Smoke result: connect/disconnect outcome + screenshot
• PASS / FAIL per step (a..h)

Только после PASS — просим user'а "cut" / "ok" / "promote".

Step 1 — bump AppVersion (drop -rN suffix)

VPNRouter.Core/AppVersion.cs:

public const string Version = "X.Y.Z";   // no suffix

Step 2 — commit + push

git add VPNRouter.Core/AppVersion.cs
git commit -m "release: cut vX.Y.Z stable (drop -rN suffix)

User confirmed <r-version> fixes work. Promoting per CLAUDE.local.md
§Release Process step 6.

No code changes since <last-rN-commit-hash>.

Co-Authored-By: Claude Opus 4.7 (1M context) <[e-mail]>"

git push github HEAD:main
git push origin HEAD:main   # retry если VPN down

Step 3 — Windows build (создаст НОВЫЙ tag vX.Y.Z + новый release)

powershell -ExecutionPolicy Bypass -File build.ps1 -Version "X.Y.Z" -Upload

build.ps1 сделает:

• gh release create vX.Y.Z --latest (без --prerelease)
• Уплоад Windows ZIPs

Tag vX.Y.Z создаётся build.ps1 на текущем commit. Stable tag — finalный, force-update НЕЛЬЗЯ.

Step 4 — fetch tag локально + push в Forgejo

git fetch github --tags         # fetches vX.Y.Z
git push origin vX.Y.Z          # mirror в Forgejo

Step 5 — Mac + Linux CI (auto-triggered tag push)

Wait for both runs. Verify 12 assets:

gh release view vX.Y.Z --repo PavelLizunov/VPNRouter --json assets --jq '.assets | length'

Должно быть 12.

Step 6 — write proper stable notes

plans/release-notes-vX.Y.Z.md — собирает фиксы со всех -r1..-rN:

• Headline P0/P1 fixes
• 4 layers of defense / 9 tests / etc
• Test coverage stats
• Cross-refs к плану

gh release edit vX.Y.Z --repo PavelLizunov/VPNRouter \
  --title "VPNRouter vX.Y.Z — <one-line headline>" \
  --notes-file "plans/release-notes-vX.Y.Z.md"

Step 7 — delete all -rN prereleases per rolling policy

gh release delete vX.Y.Z-r1 --yes --repo PavelLizunov/VPNRouter
gh release delete vX.Y.Z-r2 --yes --repo PavelLizunov/VPNRouter
# ... etc для всех -rN

Тэги НЕ удаляем — vX.Y.Z-r1, vX.Y.Z-r2 остаются в git history.

Step 8 — verify Homebrew Cask auto-bump

После tag push на stable, build-mac.yml Trigger Homebrew Cask step должен дисптачить repository_dispatch к PavelLizunov/homebrew-vpnrouter. Tap'овский update-cask.yml должен обновить Casks/vpnrouter.rb к новой версии:

gh api "repos/PavelLizunov/homebrew-vpnrouter/contents/Casks/vpnrouter.rb" \
  --jq '.content' | base64 -d | head -5

Должна быть version "X.Y.Z" + новый sha256.

Если не обновился — проверить gh run list --repo PavelLizunov/homebrew-vpnrouter для последнего dispatch'а.

Step 9 — verify APT repo

curl -sI "https://vpn.ninitux.com/apt/dists/stable/main/binary-amd64/Packages"

HTTP/1.1 200 OK ожидается. publish-apt.yml workflow должен был добавить новую .deb в reprepro index.

Step 10 — update MEMORY.md

В ~/.claude/projects/.../memory/MEMORY.md:

• "Current stable: vX.Y.Z (DD-MM-YYYY — short summary)"
• "Previous stable: "
• "Next planned: "
• One-liner install commands если они изменились

Known gotchas

• build.ps1 создаёт tag НА ТЕКУЩЕМ commit — убедись что commit это AppVersion bump (no suffix), иначе тэг укажет на не то.
• --latest moves automatically — когда build.ps1 делает gh release create --latest, GitHub сам забирает --latest у предыдущего release. Не нужно руками снимать.
• Forgejo может быть недоступен — git push origin retry'ить; github canonical для release process.
• AppVersion mismatch с tag — критическая ошибка. Тэг v2.28.3 + AppVersion 2.28.3-r6 → SemVer считает stable новее prerelease same-core, но на коде r6 это враньё. Всегда совпадать.

NOT to do

• Force-update stable tag (git tag -f vX.Y.Z) после публикации release.
• Skip Homebrew Cask verify — пользователи на macOS застревают на старом cask.
• Удалить тэг vX.Y.Z-rN из git — мы только release удаляем.