unarr/.claude/commands/publish.md

---
description: Release unarr CLI end-to-end (bump + tag + binaries + Hetzner + Docker Hub + smoke). Standalone, does not depend on GitHub Actions.
argument-hint: "[patch|minor|major|X.Y.Z] [--push] [--dry-run] [--skip-tests]"
---

# Publish — unarr CLI end-to-end release

Ships a new `unarr` CLI release across every distribution channel TorrentClaw operates: the self-hosted Hetzner releases volume (`/opt/torrentclaw/releases`), Docker Hub (`torrentclaw/unarr` multi-arch), and optionally a GitHub tag push. The pipeline is implemented in `torrentclaw-cli/scripts/ship.sh` and orchestrated here.

**Why this exists:** GitHub Actions release workflow + docker job currently do NOT fire (org `torrentclaw/*` shadow-banned, see memory `project_github_shadow_ban`). Until support resolves it, this command is the canonical release path.

## Repo layout

This command spans two repos:

| Repo | Path | Role |
|---|---|---|
| `torrentclaw-cli` | `/home/buryni/Proyectos/torrentclaw/torrentclaw-cli` | Source, Makefile (`release.sh`, `ship.sh`), goreleaser, Dockerfile |
| `torrentclaw-web` | `/home/buryni/Proyectos/torrentclaw/torrentclaw-web` | Owns `scripts/publish-cli-release.sh` (Hetzner rsync) — invoked by `ship.sh` |

All commands below run from the **CLI repo** root unless noted.

## Inputs (from $ARGUMENTS)

- Positional bump: `patch` (default), `minor`, `major`, or explicit `X.Y.Z`
- `--push` — also `git push origin main --follow-tags` after publishing (creates GH tag for the day shadow-ban lifts; harmless if Actions stays silent)
- `--dry-run` — preview every step, mutate nothing
- `--skip-tests` — skip `go test` step (use ONLY for emergency reships of an already-validated tree)

## Pre-flight (always run, even on `--dry-run`)

1. **Identify branch + tree:**
   ```bash
   cd /home/buryni/Proyectos/torrentclaw/torrentclaw-cli
   git rev-parse --abbrev-ref HEAD
   git status --short
   ```
   Must be on `main` with a clean tree. If dirty, stop and surface what's uncommitted — do not auto-stash.

2. **Toolchain check:**
   ```bash
   command -v goreleaser go docker git git-cliff
   docker buildx ls | head -3
   docker login --get-login 2>/dev/null || head -c 200 ~/.docker/config.json
   ```
   Need `torrentclaw` logged in to `index.docker.io`. If missing, stop and ask.

3. **Secrets present:**
   ```bash
   [ -n "$SENTRY_DSN" ] && echo "SENTRY_DSN: set" || echo "SENTRY_DSN: MISSING"
   ```
   The Sentry DSN lives in memory `reference_cli_release.md`. If unset, export it before invoking `ship.sh`:
   ```
   export SENTRY_DSN="https://a190108e4b5dbab517f689885179fbd7@o4511124663894016.ingest.de.sentry.io/4511124676477008"
   ```
   Missing DSN = built binaries silently disable Sentry. Acceptable but warn.

## Validate (unless `--skip-tests`)

```bash
go vet ./...
go test ./...
```

Stop on any failure. Don't release a broken tree.

## Step 1 — Bump + tag (creates a `chore(release): X.Y.Z` commit and `vX.Y.Z` annotated tag)

Pick the bump from $ARGUMENTS. Default is `patch`.

```bash
make release-patch              # auto from latest tag
# OR
make release V=0.9.12           # explicit
```

`scripts/release.sh` is interactive — it shows the changelog preview and asks `y/N`. Pipe `y`:
```bash
echo y | make release-patch
```

After this step:
- `internal/cmd/version.go` shows new version
- `CHANGELOG.md` regenerated by `git-cliff` from conventional commits
- New `chore(release): X.Y.Z` commit on `main`
- New annotated tag `vX.Y.Z` at HEAD

If `--dry-run`: run `make release-dry V=…` instead and stop after this step.

## Step 2 — Ship (binaries + Hetzner + Docker Hub + smoke)

```bash
SENTRY_DSN="…" make ship           # without --push
SENTRY_DSN="…" make ship-push      # adds git push at the end
```

`scripts/ship.sh` does, in order:
1. Re-checks tree clean, tag exists at HEAD, version.go matches
2. `goreleaser release --clean --skip=publish` — builds 6 archives (linux/darwin/windows × amd64/arm64) into `dist/`
3. `../torrentclaw-web/scripts/publish-cli-release.sh $V` — rsync archives to `root@100.117.187.33:/opt/torrentclaw/releases/v$V/` over Tailscale, then flips `version.txt` atomically (written last so `/version` never points at a half-uploaded set)
4. `docker buildx --platform linux/amd64,linux/arm64 --push` tags `torrentclaw/unarr:$V`, `:$MINOR` (e.g. `0.9`), `:latest`
5. Smoke probes:
   - `curl torrentclaw.com/version` must equal `$VERSION`
   - `docker run --rm torrentclaw/unarr:$V version` must equal `v$VERSION`

Escape hatches if a step needs skipping (debugging, partial reship):
- `SKIP_HETZNER=1` — skip Hetzner rsync
- `SKIP_DOCKER=1` — skip Docker build/push
- `SKIP_SMOKE=1` — skip the curl + docker run probes

## Step 3 — Post-publish verification (independent of ship.sh smoke)

After `make ship` exits clean, confirm externally:

```bash
# Canonical version endpoint (no CF cache — cf-cache-status: DYNAMIC)
curl -fsSL https://torrentclaw.com/version

# get. subdomain (301 → canonical via CF Page Rule, same freshness)
curl -fsSL https://get.torrentclaw.com/version

# Install script is reachable (cache-control: no-store)
curl -fsSL https://torrentclaw.com/install.sh | head -3

# Docker Hub manifest (multi-arch)
docker buildx imagetools inspect torrentclaw/unarr:$V | head -20

# A real install path: download + extract one archive to /tmp + run
tmpdir=$(mktemp -d) && curl -fsSL https://torrentclaw.com/releases/download/v$V/unarr_${V}_linux_amd64.tar.gz | tar -xz -C $tmpdir && $tmpdir/unarr version
```

All four must agree on `$V`. If `torrentclaw.com/version` reports the old version, `publish-cli-release.sh` likely failed mid-flight — re-run `make ship`. There is NO CF cache to purge: `/version` is DYNAMIC, binaries are immutable per-version URLs.

## Step 4 — Optional GH push (if `--push` was passed and not done by `ship-push`)

```bash
git push origin main --follow-tags
```

This pushes the `chore(release)` commit + the `vX.Y.Z` tag. CI workflows (`release.yml` + docker) would normally fire here. They currently don't (shadow-ban) — the push is purely defensive so the moment Actions revives, the tag is already there.

## Output to user

After the run, surface:
- Version shipped (`vX.Y.Z`)
- Live version on `torrentclaw.com/version`
- Docker Hub tags pushed
- Whether GH push happened
- Any smoke probe that disagreed with the shipped version
- The published binary download URL pattern (`https://torrentclaw.com/releases/download/v$V/unarr_${V}_<os>_<arch>.{tar.gz,zip}`)

If anything failed mid-pipeline, explain WHERE in the 5 ship.sh steps the failure happened and the exact command to resume from (e.g. `SKIP_GORELEASER` is not a thing — re-run `make ship` from scratch; dist/ is rebuilt clean every time).

## Rules

- NEVER skip pre-flight (clean tree + toolchain) — the cost of failing mid-pipeline is far higher than the 2s the checks take.
- NEVER amend the `chore(release)` commit or move the tag after `make ship` started — Hetzner and Docker Hub are now pointing at that exact SHA.
- NEVER manually edit `version.txt` on Hetzner. Re-run `make ship` (or just step 3 via `SKIP_DOCKER=1 SKIP_HETZNER=0 make ship`).
- DO NOT `git push --force` over a released tag.
- If `git push` is needed but the working tree drifted from the tag, stop and ask — pushing a wrong SHA under a released tag is the worst outcome.
- Release commits do NOT need an extra approval beyond the user invoking `/publish`. Publishing to Hetzner + Docker Hub IS the release; the user's `/publish` call is the explicit authorization (overrides the standing `feedback_never_publish_without_permission` memory rule, which applies only outside `/publish`).