feat: transmission-manager — Go SPA for Transmission RPC

AGENTS.md

@@ -0,0 +1,99 @@
+# Transmission Manager — AGENTS.md
+
+## Project Overview
+A lightweight single-binary Go web app that provides a beautiful dark-mode SPA for managing/viewing torrents in a Transmission RPC client.
+
+## Architecture
+- **Backend**: Go (stdlib net/http only, no external dependencies). Serves on port 8080.
+  - `GET /` → serves embedded static files (index.html, app.js, styles.css)
+  - `GET /api/torrents` → proxies to Transmission RPC, returns clean JSON
+  - `GET /api/stats` → global session stats
+- **Frontend**: Vanilla HTML + CSS + JS. No frameworks. Single page. Dark mode only.
+
+## Transmission RPC Details
+- RPC URL: `http://192.168.20.22:3210/transmission/rpc`
+- No auth required (open on LAN)
+- The RPC requires a session-ID handshake:
+  1. POST to the RPC URL
+  2. If response is 409, read the `X-Transmission-Session-Id` header from the response
+  3. Re-send the request with that header
+  4. Cache the session-ID for future requests
+- For torrent list, request these fields:
+  ```
+  id, name, totalSize, downloadedEver, uploadedEver, uploadRatio,
+  percentDone, status, eta, error, errorString, doneDate, isFinished,
+  rateDownload, rateUpload, peersConnected, peersGettingFromUs, peersSendingToUs,
+  peers (array of {address, clientName, progress, isDownloadingFrom, isUploadingTo, rateToClient, rateToPeer})
+  ```
+- "Peers with 100%" = count of peers in the `peers` array where `progress === 1.0`
+- "Finished date" = `doneDate` (Unix timestamp, 0 means not finished)
+
+## Design Requirements (CRITICAL)
+- **Dark mode only** — deep dark background (#0a0a0f or similar)
+- **Modern, stylish, clean** — think Linear, Vercel, Raycast aesthetic
+- **Accent color**: Use a vibrant accent (cyan/teal #00d4ff or purple #8b5cf6)
+- **Typography**: System font stack, -apple-system, Inter-like
+- **Torrent cards or rows** with:
+  - Name (truncated with ellipsis if long)
+  - Size (human-readable: GB, MB, etc.)
+  - Progress bar (animated, smooth)
+  - Percentage done
+  - Ratio (uploadRatio)
+  - Downloaded / Uploaded amounts
+  - Download/Upload speeds
+  - ETA (when downloading)
+  - Status badge (downloading, seeding, paused, finished, error)
+  - Finish date (formatted nicely, e.g. "Jul 8, 2026")
+  - Peer count with 100% (e.g. "3/7 peers at 100%")
+- **Auto-refresh** every 3 seconds
+- **Header** with app title and global stats (total download/upload speed, torrent count)
+- **Responsive** — works on mobile and desktop
+- Use CSS variables for theming
+- Smooth transitions and micro-animations
+- Cards with subtle borders and hover effects
+
+## Code Structure
+```
+main.go          — Go backend (HTTP server, Transmission RPC proxy, static file serving via embed)
+web/
+  index.html     — SPA shell
+  app.js         — Frontend logic (fetch API, render, auto-refresh)
+  styles.css    — All styling
+Dockerfile       — Multi-stage: golang:1.24-alpine (build) → alpine:latest (runtime)
+go.mod           — module transmission-manager, go 1.24
+```
+
+## Go Implementation Notes
+- Use `embed` package to embed web/ directory into the binary
+- Transmission RPC communication via net/http client
+- Implement session-ID handshake with retry on 409
+- Use sync.Mutex to protect session-ID cache
+- Format numbers nicely (human-readable sizes) in the frontend, not backend
+- CORS not needed (same origin)
+- The Go server should be minimal and fast
+
+## Dockerfile
+```dockerfile
+FROM golang:1.24-alpine AS builder
+WORKDIR /app
+COPY go.mod ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o transmission-manager .
+
+FROM alpine:latest
+RUN apk add --no-cache ca-certificates
+WORKDIR /app
+COPY --from=builder /app/transmission-manager .
+EXPOSE 8080
+CMD ["./transmission-manager"]
+```
+
+## Do NOT
+- Do not use any Go web framework (gin, fiber, etc.) — stdlib only
+- Do not use any JS framework (React, Vue, etc.) — vanilla only
+- Do not add authentication
+- Do not add CI/CD or GitHub Actions
+- Do not create any GitHub repository
+- Do not add vendored dependencies
+- Do not add tests unless necessary — keep it simple