59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# Transmission Manager - Agent Guide
|
|
|
|
## First Rule
|
|
Always read `project-context.md` before making code or documentation changes. If a change alters project purpose, architecture, APIs, file roles, workflows, constraints, or implementation patterns, update `project-context.md` in the same change.
|
|
|
|
## Quick Summary
|
|
Transmission Manager is a lightweight single-binary Go web app for managing and viewing torrents in a Transmission RPC client. It serves a dark-mode vanilla HTML/CSS/JS SPA and proxies Transmission RPC calls through a minimal Go backend.
|
|
|
|
## Stack
|
|
- Backend: Go 1.24, standard library only.
|
|
- Frontend: Vanilla HTML, CSS, and JavaScript. No framework or build step.
|
|
- Static assets: embedded with Go `embed` from `web/`.
|
|
- Runtime port: `8080`.
|
|
- Container: multi-stage Docker build from `golang:1.24-alpine` to `alpine:latest`.
|
|
|
|
## Current Files
|
|
- `project-context.md` - canonical project context and implementation rules for agents.
|
|
- `main.go` - HTTP server, embedded static file serving, environment-driven Transmission RPC client, connection warning page, API routes.
|
|
- `web/index.html` - SPA shell and toolbar controls.
|
|
- `web/app.js` - frontend state, polling, in-place rendering, sorting, pause/resume actions.
|
|
- `web/styles.css` - dark-only UI theme and responsive layout.
|
|
- `go.mod` - module `transmission-manager`, Go 1.24.
|
|
- `Dockerfile` - production container build.
|
|
|
|
## Core API Surface
|
|
- `GET /` serves a Transmission connection warning page when setup fails; otherwise it serves the embedded frontend.
|
|
- `GET /api/torrents` returns Transmission torrent data.
|
|
- `GET /api/stats` returns global session stats.
|
|
- `POST /api/torrents/{id}/pause` maps to Transmission `torrent-stop`.
|
|
- `POST /api/torrents/{id}/resume` maps to queue-respecting Transmission `torrent-start`.
|
|
|
|
## Implementation Guidelines
|
|
- Keep the backend stdlib-only. Do not add Gin, Fiber, Chi, Gorilla, or other Go web frameworks.
|
|
- Keep the frontend dependency-free. Do not add React, Vue, Svelte, bundlers, package managers, or transpilers.
|
|
- Preserve the single-binary model: static frontend files should remain embedded via `embed`.
|
|
- Format display numbers in the frontend unless there is a clear backend reason.
|
|
- Preserve in-place frontend updates during polling. Do not replace the whole torrent list on each refresh.
|
|
- Keep polling lightweight and avoid overlapping refresh requests.
|
|
- Keep UI dark-only, modern, compact, responsive, and based on CSS variables.
|
|
|
|
## Transmission RPC Notes
|
|
- Default RPC URL: `http://192.168.20.22:3210/transmission/rpc`.
|
|
- Override the RPC URL with `TRANSMISSION_URL`.
|
|
- Optional HTTP Basic Auth credentials come from `TRANSMISSION_RPC_USERNAME` and `TRANSMISSION_RPC_PASSWORD`; unset, empty, or literal `null` values mean no credential value.
|
|
- Handle the Transmission session-ID handshake:
|
|
1. POST to the RPC URL.
|
|
2. If the response is `409`, read `X-Transmission-Session-Id`.
|
|
3. Retry the same request with that header.
|
|
4. Cache the session ID behind a mutex.
|
|
- "Peers at 100%" means count `peers[]` entries where `progress === 1.0`.
|
|
- `doneDate` is a Unix timestamp; `0` means unfinished.
|
|
|
|
## Do Not
|
|
- Do not add authentication unless explicitly requested.
|
|
- Do not add CI/CD or GitHub Actions.
|
|
- Do not create a GitHub repository.
|
|
- Do not vendor dependencies.
|
|
- Do not add broad tests or infrastructure for small changes; keep verification proportional.
|