From 0586d67a4131cfc633a13ebfb1563e22a96abb8e Mon Sep 17 00:00:00 2001 From: mika kuns Date: Fri, 24 Apr 2026 18:53:13 +0200 Subject: [PATCH] docs(spec): gitea release flow and windows service support Co-Authored-By: Claude Opus 4.7 (1M context) --- ...itea-release-and-windows-service-design.md | 247 ++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-24-gitea-release-and-windows-service-design.md diff --git a/docs/superpowers/specs/2026-04-24-gitea-release-and-windows-service-design.md b/docs/superpowers/specs/2026-04-24-gitea-release-and-windows-service-design.md new file mode 100644 index 0000000..2584f56 --- /dev/null +++ b/docs/superpowers/specs/2026-04-24-gitea-release-and-windows-service-design.md @@ -0,0 +1,247 @@ +# Gitea Release Flow + Windows Service Support + +**Date:** 2026-04-24 +**Status:** Approved (ready for implementation plan) + +## Goal + +Two coupled capabilities for ClaudeMailbox: + +1. **Gitea Release Flow.** Tag-driven CI that publishes a self-contained `win-x64` single-file binary plus SHA256 checksums to a Gitea release. +2. **Windows Service Support.** The binary self-installs as a Windows Service via new `install-service` / `uninstall-service` / `start` / `stop` verbs, seeded from a `mailbox.json` config file. The ClaudeDo Installer can then provision ClaudeMailbox directly using this stable verb surface. + +Both are needed so that a downstream installer (ClaudeDo) can fetch, verify, and register ClaudeMailbox as a long-running service without hand-crafted `sc.exe` calls at the installer side. + +## Non-Goals + +- Linux / macOS service integration (`systemd`, `launchd`). Single-platform (`win-x64`) only in v1. +- Cross-machine / non-loopback deployment. +- Auto-update of the service binary (ClaudeDo owns update orchestration via its existing `SelfUpdater` pattern). +- Per-user service installation. Service runs as `NT AUTHORITY\LocalService`; DB lives under `%ProgramData%`. + +## Architecture Overview + +``` +tag push ──► .gitea/workflows/release.yml + │ + ├─ dotnet publish (win-x64, self-contained, single-file) + ├─ sha256 → checksums.txt + └─ POST /api/v1/repos/.../releases + + upload assets + │ + ▼ + claude-mailbox-${VERSION}-win-x64.exe + checksums.txt + │ + │ (consumed by ClaudeDo Installer) + ▼ + claude-mailbox.exe install-service [--port] [--bind] [--db-path] + │ + ├─ seed %ProgramData%\ClaudeMailbox\mailbox.json + ├─ ACL %ProgramData%\ClaudeMailbox\ for LocalService + └─ sc.exe create ClaudeMailbox + binPath= " serve --config " + start= auto obj= "NT AUTHORITY\LocalService" + │ + ▼ + ClaudeMailbox Windows Service + (reads mailbox.json, hosts MCP + REST) +``` + +## Section 1 — Gitea Release Flow + +### Trigger +- `push` on tags matching `v*`. +- Separate `ci.yml` runs `dotnet build` + `dotnet test` on every push to `main` (no release). + +### Workflow Skeleton +`.gitea/workflows/release.yml` modelled after `C:\Private\ClaudeDo\.gitea\workflows\release.yml`: + +- `runs-on: ubuntu-latest` +- `env: DOTNET_ROOT: /home/mika/.dotnet`, `GITEA_API: https://git.kuns.dev/api/v1`, `REPO: releases/ClaudeMailbox` (exact repo slug to confirm at implementation time) +- Steps: + 1. **Resolve version** — strip `v` prefix from `github.ref_name` → `$VERSION` + 2. **Prepare workspace** — `mktemp -d` + 3. **Checkout tag** — `git clone --depth 1 --branch $TAG` using `secrets.GITEA_TOKEN` + 4. **Publish** — `dotnet publish src/ClaudeMailbox/ClaudeMailbox.csproj -c Release -r win-x64 --self-contained true /p:MinVerVersionOverride=$VERSION -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o out/app` + 5. **Package assets** — rename produced exe to `claude-mailbox-${VERSION}-win-x64.exe`, write `checksums.txt` via `sha256sum` + 6. **Create Gitea Release** — `curl POST ${GITEA_API}/repos/${REPO}/releases` with `tag_name`, `name`, `draft:false`, `prerelease:false`, `target_commitish:main` + 7. **Upload assets** — `curl POST .../releases/${RELEASE_ID}/assets?name=` for each asset + 8. **Cleanup** — `rm -rf $WORK` with `if: always()` + +### Versioning +`Directory.Build.props` gains a MinVer reference so `$VERSION` from the tag is baked into `AssemblyVersion`, `FileVersion`, `InformationalVersion`. Same approach as ClaudeDo (`MinVerVersionOverride` property). Default local dev version: `0.0.0-dev`. + +Whether to pull in the `MinVer` NuGet package explicitly or use .NET SDK's built-in `Version` property with `-p:Version=$VERSION` is an implementation choice made during the plan phase — ClaudeDo uses `MinVerVersionOverride` which implies the MinVer package is present. + +### Release Assets (stable contract) +- `claude-mailbox-${VERSION}-win-x64.exe` — self-contained single-file binary +- `checksums.txt` — `sha256sum` output for the exe + +No ZIP (single artifact, simpler discovery). + +### CI Workflow +`.gitea/workflows/ci.yml`: +- Trigger: push to `main`, PRs to `main` +- Steps: checkout → setup dotnet → `dotnet build` → `dotnet test tests/ClaudeMailbox.Tests/ClaudeMailbox.Tests.csproj` +- No publish, no release. + +## Section 2 — Windows Service Support + +### Project Changes +`src/ClaudeMailbox/ClaudeMailbox.csproj` adds: + +```xml + +``` + +### Host Wiring +`ServerHost.CreateBuilder` adds (before `Build()`): + +```csharp +builder.Host.UseWindowsService(opt => opt.ServiceName = "ClaudeMailbox"); +``` + +No-op when launched as console app; enables Windows Service lifetime when SCM starts the process. + +### New CLI Verbs +Dispatch in `Program.cs` extended. New module `src/ClaudeMailbox/Cli/ServiceCommands.cs`: + +| Verb | Behavior | +|---|---| +| `install-service [--port] [--bind] [--db-path]` | Admin-only. Seed `mailbox.json` (if missing). ACL ProgramData dir. `sc.exe create`. `sc.exe description`. | +| `uninstall-service [--purge]` | Admin-only. `sc.exe stop` (best-effort), `sc.exe delete`. `--purge` removes `%ProgramData%\ClaudeMailbox`. | +| `start` | `sc.exe start ClaudeMailbox`. | +| `stop` | `sc.exe stop ClaudeMailbox`. | +| `status` | `sc.exe query ClaudeMailbox`, parse `STATE` line, print single-word status. | + +Service commands: +- Gate on `OperatingSystem.IsWindows()`. On non-Windows: exit 2, message `"Service commands are Windows-only."` +- Gate on admin privilege (WindowsIdentity + WindowsPrincipal). On missing: exit 5, message `"install-service requires Administrator."` +- Shell out to `sc.exe` via `Process.Start(new ProcessStartInfo { ... RedirectStandardOutput = true })`, capture exit code, surface stderr on failure. + +### install-service Flow (concrete) +1. Admin check. +2. `Directory.CreateDirectory(@"C:\ProgramData\ClaudeMailbox")` (idempotent). +3. Apply ACL: add `LocalService` with `Modify` rights on that directory (`DirectorySecurity` + `FileSystemAccessRule`). +4. If `mailbox.json` missing: write seeded JSON with CLI-flag-overridable values: + ```json + { "port": 47822, "bind": "127.0.0.1", "dbPath": "C:\\ProgramData\\ClaudeMailbox\\mailbox.db" } + ``` +5. Resolve current exe path via `Environment.ProcessPath`. +6. `sc.exe create ClaudeMailbox binPath= "\"\" serve --config \"C:\ProgramData\ClaudeMailbox\mailbox.json\"" start= auto DisplayName= "Claude Mailbox" obj= "NT AUTHORITY\LocalService"` +7. `sc.exe description ClaudeMailbox "MCP mailbox server for parallel Claude sessions"` + +Service name is fixed (`ClaudeMailbox`) in v1 — no multi-instance support. + +### uninstall-service Flow +1. Admin check. +2. `sc.exe stop ClaudeMailbox` (ignore failure if not running). +3. `sc.exe delete ClaudeMailbox`. +4. If `--purge`: delete `%ProgramData%\ClaudeMailbox` recursively (only if empty of non-ours files, or unconditionally — default to unconditional with explicit `--purge` opt-in). + +## Section 3 — Config File + Precedence + +### File +`src/ClaudeMailbox/Config/FileConfig.cs`: + +```csharp +public sealed class FileConfig +{ + public int? Port { get; set; } + public string? Bind { get; set; } + public string? DbPath { get; set; } +} +``` + +### Loader +`FileConfig.LoadOrDefault(string? explicitPath)`: +- If `explicitPath` given: must exist, else throw with clear message. +- Else: probe `%ProgramData%\ClaudeMailbox\mailbox.json`. If absent, return empty `FileConfig`. +- Parse via `System.Text.Json.JsonSerializer` with `PropertyNameCaseInsensitive = true`. + +### Precedence +In `Program.cs` (before building `DaemonConfig`): + +1. CLI flag (`--port`, `--bind`, `--db-path`) +2. Config file (explicit via `--config ` OR default `%ProgramData%\ClaudeMailbox\mailbox.json` if present) +3. Hardcoded defaults in `DaemonConfig` + +Extract helper `DaemonConfig BuildDaemonConfig(string[] args, FileConfig file)` for testability. + +### Backward Compatibility +When `--config` is not passed AND no ProgramData config exists, behavior is unchanged: daemon uses `%USERPROFILE%\.claude-mailbox\mailbox.db` and default port/bind. Existing interactive users are unaffected. + +### Service CmdLine +`install-service` always bakes `--config C:\ProgramData\ClaudeMailbox\mailbox.json` into the service's `binPath`, so the service has no dependency on working directory, user profile, or environment. + +## Section 4 — Tests + +### New Unit Tests +- `tests/ClaudeMailbox.Tests/Config/FileConfigTests.cs` + - Round-trip JSON with all fields. + - Missing fields deserialize to `null` (optional semantics). + - Malformed JSON throws with actionable message. +- `tests/ClaudeMailbox.Tests/Config/ConfigPrecedenceTests.cs` + - CLI flag wins over file value. + - File value wins over default. + - Default used when neither file nor CLI provides it. + - Mixed: `--port` from CLI, `dbPath` from file, `bind` from default. + +### Out of Scope +- Service install/uninstall tests. `sc.exe` requires Administrator, is Windows-only, and not runnable on `ubuntu-latest` CI. A manual smoke-test protocol is documented in README: + ``` + claude-mailbox.exe install-service + sc query ClaudeMailbox + Invoke-WebRequest http://127.0.0.1:47822/health + claude-mailbox.exe uninstall-service --purge + ``` + +### Cross-Platform Build +Service-related code must compile on Linux (CI runner). Use: +- `Microsoft.Extensions.Hosting.WindowsServices` — NuGet package is cross-platform; `UseWindowsService()` is a no-op on non-Windows. +- `sc.exe` invocations guarded by `OperatingSystem.IsWindows()`. +- `DirectorySecurity` / `FileSystemAccessRule` are in `System.Security.AccessControl` — available on non-Windows but throw on use. Guard all calls. + +## Section 5 — ClaudeDo Installer Contract + +This section is **informational** — the work is on the ClaudeDo side, not in this repo. Listed here to make the contract explicit. + +### Discovery +`GET https://git.kuns.dev/api/v1/repos/releases/ClaudeMailbox/releases/latest` returns `assets[].browser_download_url`. Reuse ClaudeDo's `ReleaseClient` + `ChecksumVerifier` + `VersionComparer`. + +### Installer Steps (new in ClaudeDo) +1. Download `claude-mailbox-${VERSION}-win-x64.exe` → `%ProgramFiles%\ClaudeMailbox\claude-mailbox.exe`. +2. Verify SHA256 against `checksums.txt`. +3. Run `claude-mailbox.exe install-service` (elevated). This seeds `mailbox.json`, ACLs ProgramData, creates the service. +4. Run `claude-mailbox.exe start` (or `sc.exe start ClaudeMailbox`). +5. Record entry in ClaudeDo's `InstallManifest` (version + path). +6. On uninstall: `claude-mailbox.exe uninstall-service --purge` → delete `%ProgramFiles%\ClaudeMailbox\`. + +### Stable Contract +- Verbs: `install-service`, `uninstall-service`, `start`, `stop`, `status`. +- Flags on `install-service`: `--port`, `--bind`, `--db-path` (all optional). +- Service name: `ClaudeMailbox`. +- Config path: `%ProgramData%\ClaudeMailbox\mailbox.json`. + +Any changes to the above require coordinated updates in the ClaudeDo installer. + +## Files Touched + +- `src/ClaudeMailbox/ClaudeMailbox.csproj` — add `Microsoft.Extensions.Hosting.WindowsServices`. +- `src/ClaudeMailbox/ServerHost.cs` — `UseWindowsService()` wiring. +- `src/ClaudeMailbox/Program.cs` — dispatch new verbs, integrate `FileConfig` precedence. +- `src/ClaudeMailbox/Cli/ServiceCommands.cs` — **new**. Verb handlers. +- `src/ClaudeMailbox/Config/FileConfig.cs` — **new**. Config file model + loader. +- `tests/ClaudeMailbox.Tests/Config/FileConfigTests.cs` — **new**. +- `tests/ClaudeMailbox.Tests/Config/ConfigPrecedenceTests.cs` — **new**. +- `.gitea/workflows/release.yml` — **new**. Tag-triggered release. +- `.gitea/workflows/ci.yml` — **new**. Build + test on main. +- `Directory.Build.props` — MinVer integration (or `Version` fallback). +- `README.md` — document `install-service` / `uninstall-service`, config file, manual smoke test. + +## Open Questions for Implementation Plan + +- Exact Gitea repo slug (confirm `releases/ClaudeMailbox` or other). +- MinVer package vs. `-p:Version=$VERSION` — align with ClaudeDo's current convention. +- Whether `status` verb should print parsed `Running | Stopped | NotInstalled` or raw `sc query` output. Recommendation: parsed + exit codes 0/1/2.