Session 5: Dockerfile, config example, README rewrite

Multi-stage alpine Dockerfile builds with -tags goolm so libolm isn't needed at runtime. Annotated config.example.yaml documents every field and shows ${ENV_VAR} usage for secrets. README is rewritten for the Go bot — Python-era web-portal docs are gone.
Session 4: command dispatcher and main entrypoint
2026-05-24 20:29:13 -07:00 · 2026-05-24 20:27:17 -07:00
7 changed files with 548 additions and 229 deletions
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1
+
+FROM golang:1.25-alpine AS build
+RUN apk add --no-cache build-base
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+# goolm = pure-Go olm; sqlite needs cgo for the device/crypto stores.
+ENV CGO_ENABLED=1
+RUN go build -tags goolm -trimpath -ldflags="-s -w" -o /out/bellhop ./
+
+FROM alpine:3.21
+RUN apk add --no-cache ca-certificates tzdata
+RUN addgroup -S bellhop && adduser -S -G bellhop bellhop
+WORKDIR /app
+COPY --from=build /out/bellhop /usr/local/bin/bellhop
+USER bellhop
+VOLUME ["/app/data"]
+ENTRYPOINT ["/usr/local/bin/bellhop"]
+CMD ["-config", "/app/config.yaml"]
--- a/README.md
+++ b/README.md
@@ -1,267 +1,81 @@
 # Bellhop

-A Matrix-authenticated web portal for submitting media requests to Radarr, Sonarr, and Lidarr. Users sign in with their Matrix homeserver credentials, search for movies, TV shows, or music, and submit requests — all through a clean single-page interface. Every request is logged to a Matrix room for auditing.
+A Matrix bot that adds movies, TV, and music to Radarr/Sonarr/Lidarr from chat. Invite the bot to a room, allowlist the room ID, and any member can type `!movie dune` to add the top search hit.

-## Architecture
+## Command UX

 ```
-Browser ──► FastAPI app ──► Matrix homeserver (authentication)
-                        ──► Radarr / Sonarr / Lidarr (search + add)
-                        ──► Matrix room (audit log)
-                        ──► SQLite (session storage)
+!movie <query>   — add the top Radarr hit
+!tv <query>      — add the top Sonarr hit
+!music <query>   — add the top Lidarr hit
+!help            — show the command list
 ```

-All *arr communication happens server-side. API keys and service URLs are never exposed to the browser.
+The bot replies in a thread under the request so a busy room stays readable. No numbered picker, no reaction selector — the top search result is what gets added. If you want something other than the top hit, narrow the query.

-## Requirements
+## Authorization

- Python 3.12+
- A Matrix homeserver (Synapse, Dendrite, Conduit, etc.)
- At least one of: Radarr, Sonarr, or Lidarr accessible over HTTPS
- (Optional) A Matrix bot account for audit logging
+Any member of an allowlisted room may issue commands. The bot auto-joins on invite, but the room ID must appear under `matrix.allowed_rooms` in the config before commands are honored.

-## Quick Start
+## Configuration

-### 1. Clone and configure
+Copy `config.example.yaml` to `config.yaml` and edit. The loader expands `${ENV_VAR}` references at load time, so secrets can come from the environment.

-```bash
-git clone https://github.com/prosolis/Bellhop.git
-cd Bellhop
-cp .env.example .env
-```
+Required:

-Edit `.env` with your actual values (see [Environment Variables](#environment-variables) below).
+- `matrix.homeserver`, `matrix.user_id`, `matrix.password`
+- `matrix.allowed_rooms` (at least one room ID)
+- At least one of `services.radarr` / `services.sonarr` / `services.lidarr`

-### 2. Run locally
+Per-service: `url`, `api_key`, `quality_profile_id`, `root_folder`. Lidarr also needs `metadata_profile_id`.

-```bash
-pip install -r requirements.txt
-uvicorn app.main:app --host 0.0.0.0 --port 8000
-```
+Omit a service block to disable its command — `!movie` with no `radarr` block replies "Radarr is not configured".

-Open `http://localhost:8000` in your browser.
-
-### 3. Run with Docker
-
-```bash
-docker build -t bellhop .
-docker run -d \
-  --name bellhop \
-  --env-file .env \
-  -p 8000:8000 \
-  -v bellhop-data:/app \
-  bellhop
-```
-
-The SQLite database file is created at the path specified by `DATABASE_PATH` (default: `bellhop.db` in the working directory). Mount a volume if you want persistence across container recreations.
-
-## Environment Variables
-
-Create a `.env` file in the project root (or pass variables via Docker `--env-file`). See `.env.example` for a template.
-
-### Required
-
-| Variable | Description |
-|---|---|
-| `MATRIX_HOMESERVER_URL` | Base URL of your Matrix homeserver (e.g. `https://matrix.example.com`) |
-
-### *arr Services
-
-Configure one or more. If a service's URL or API key is left empty, that media type will return a "not configured" error when used.
-
-| Variable | Default | Description |
-|---|---|---|
-| `RADARR_URL` | _(empty)_ | Radarr instance URL (e.g. `https://radarr.example.com`) |
-| `RADARR_API_KEY` | _(empty)_ | Radarr API key (Settings > General in Radarr) |
-| `RADARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID to assign to new movies |
-| `RADARR_ROOT_FOLDER` | `/movies` | Root folder path for movie storage |
-| `SONARR_URL` | _(empty)_ | Sonarr instance URL |
-| `SONARR_API_KEY` | _(empty)_ | Sonarr API key |
-| `SONARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID for new series |
-| `SONARR_ROOT_FOLDER` | `/tv` | Root folder path for TV storage |
-| `LIDARR_URL` | _(empty)_ | Lidarr instance URL |
-| `LIDARR_API_KEY` | _(empty)_ | Lidarr API key |
-| `LIDARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID for new artists |
-| `LIDARR_ROOT_FOLDER` | `/music` | Root folder path for music storage |
-
-**Finding quality profile IDs:** Open your *arr instance, go to Settings > Profiles. The ID is visible in the URL when you click a profile, or query the API directly:
+**Finding quality profile IDs:**

 ```bash
 curl -H "X-Api-Key: YOUR_KEY" https://radarr.example.com/api/v3/qualityprofile
 ```

-### Audit Bot (optional)
+## Running

-| Variable | Default | Description |
-|---|---|---|
-| `MATRIX_AUDIT_ROOM_ID` | _(empty)_ | Room ID for audit messages (e.g. `!abc123:example.com`) |
-| `MATRIX_BOT_USER_ID` | _(empty)_ | Bot's Matrix user ID (e.g. `@bellhop-bot:example.com`) |
-| `MATRIX_BOT_ACCESS_TOKEN` | _(empty)_ | Pre-authenticated access token for the bot |
-
-If any of these are left empty, audit logging is silently disabled. The room must be **unencrypted** and the bot must already be joined to it.
-
-**Getting a bot access token:**
+### Local

 ```bash
-curl -X POST https://matrix.example.com/_matrix/client/v3/login \
-  -H "Content-Type: application/json" \
-  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"@bellhop-bot:example.com"},"password":"bot-password"}'
+go build -tags goolm -o bellhop ./
+./bellhop -config config.yaml
 ```

-Copy the `access_token` from the response.
+The `goolm` tag uses the pure-Go olm implementation so libolm isn't needed.

-### Other
+### Docker

-| Variable | Default | Description |
-|---|---|---|
-| `SESSION_SECRET_KEY` | _(auto-generated)_ | Secret for signing session cookies. Auto-generated at startup if not set. A new key is generated on every restart, which invalidates all existing sessions. |
-| `DATABASE_PATH` | `bellhop.db` | Path to the SQLite database file |
-
-## API Reference
-
-### Authentication
-
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/auth/login` | Authenticate with Matrix credentials. Rate-limited to 5 requests/minute per IP. |
-| `POST` | `/auth/logout` | Destroy the current session. |
-| `GET` | `/auth/me` | Return the current user's Matrix ID, or 401 if not authenticated. |
-
-**Login request body:**
-
-```json
-{
-  "username": "@user:example.com",
-  "password": "your-password"
-}
+```bash
+docker build -t bellhop .
+docker run -d \
+  --name bellhop \
+  -v "$PWD/config.yaml:/app/config.yaml:ro" \
+  -v bellhop-data:/app/data \
+  bellhop
 ```

-The username can be a full Matrix ID (`@user:example.com`) or a localpart (`user`) — the homeserver resolves it.
+The `data` volume holds the Matrix device file and the E2EE crypto store. Losing it forces a re-login and re-verification on next start.

-**Login response (200):**
+## E2EE notes

-```json
-{
-  "user_id": "@user:example.com"
-}
-```
+The bot bootstraps cross-signing on first run and persists Olm/Megolm sessions in `data/crypto.db`. If you rotate the bot's password or wipe `data/`, the bot logs in as a new device — existing rooms will need to re-share keys, which mautrix handles automatically on the next message.

-A `bellhop_session` cookie is set automatically.
-
-### Search
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/search/movie?term=...` | Search Radarr for movies |
-| `GET` | `/search/tv?term=...` | Search Sonarr for TV shows |
-| `GET` | `/search/music?term=...` | Search Lidarr for artists |
-
-All search endpoints require an active session (cookie). Results are capped at 25 items. Response fields are sanitized — only safe metadata (title, year, poster URL, IDs) is returned.
-
-### Request
-
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/request/movie` | Add a movie to Radarr |
-| `POST` | `/request/tv` | Add a series to Sonarr |
-| `POST` | `/request/music` | Add an artist to Lidarr |
-
-**Movie request body:**
-
-```json
-{
-  "title": "Movie Title",
-  "tmdbId": 12345,
-  "year": 2024
-}
-```
-
-**TV request body:**
-
-```json
-{
-  "title": "Show Title",
-  "tvdbId": 67890,
-  "year": 2024
-}
-```
-
-**Music request body:**
-
-```json
-{
-  "artistName": "Artist Name",
-  "foreignArtistId": "mbid-uuid-here"
-}
-```
-
-All items are added as monitored with "search on add" enabled. Quality profile and root folder are set from the corresponding environment variables.
-
-**Success response (200):**
-
-```json
-{
-  "ok": true,
-  "message": "Movie added successfully"
-}
-```
-
-### Frontend
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/` | Serves the single-page Alpine.js frontend |
-
-## Project Structure
+## Project layout

 ```
-Bellhop/
-├── app/
-│   ├── __init__.py
-│   ├── main.py          # FastAPI app, lifespan, rate limiter, route mounting
-│   ├── config.py         # Environment variable loading
-│   ├── database.py       # Async SQLite session CRUD
-│   ├── auth.py           # /auth/* routes, session cookie management
-│   ├── arr.py            # /search/* and /request/* routes, *arr API proxying
-│   ├── audit.py          # Fire-and-forget Matrix room messaging
-│   ├── static/           # Static assets (served at /static)
-│   └── templates/
-│       └── index.html    # Alpine.js single-page frontend
-├── Dockerfile
-├── requirements.txt
-├── .env.example
-└── README.md
+main.go
+internal/
+  config/   — YAML loader with ${ENV_VAR} expansion
+  matrix/   — mautrix client: login, device persistence, E2EE, sync loop
+  arr/      — Radarr/Sonarr/Lidarr HTTP clients
+  bot/      — command parser + dispatch + threaded replies
 ```

-## Security
-
- **Session cookies** are set with `httponly`, `samesite=strict`, and `secure` flags. The `secure` flag means cookies are only sent over HTTPS — use a reverse proxy with TLS in production.
- **Login rate limiting** — 5 attempts per minute per IP address via slowapi.
- **Token validation** — every protected route verifies the Matrix access token against the homeserver's `/_matrix/client/v3/account/whoami` endpoint. If the token has been revoked, the session is deleted immediately. If the homeserver is unreachable, the local session is trusted as a fallback.
- **No credential leakage** — *arr API keys, URLs, and internal IDs are never included in any response to the browser. Search results are mapped to a safe subset of fields before returning.
- **Sessions expire** after 7 days (cookie `max_age`).
-
-### Production Recommendations
-
- Run behind a reverse proxy (nginx, Caddy, Traefik) with TLS termination so the `secure` cookie flag works.
- If you want sessions to persist across restarts, set `SESSION_SECRET_KEY` explicitly. Otherwise, all users are logged out on restart.
- Restrict network access to your *arr instances — only the Bellhop container needs to reach them.
- Use a dedicated Matrix bot account for audit logging rather than a personal account.
-
-## How It Works
-
-1. **User signs in** — the frontend POSTs Matrix credentials to `/auth/login`. The backend authenticates against the Matrix homeserver's Client-Server API (`m.login.password`), stores the resulting access token in SQLite, and returns a session cookie.
-
-2. **User searches** — the frontend sends a search query to `/search/{type}`. The backend proxies the request to the appropriate *arr instance, strips internal fields, and returns sanitized results with poster URLs.
-
-3. **User requests** — clicking "Request" on a result POSTs it to `/request/{type}`. The backend sends the add command to the *arr API with preconfigured quality profile and root folder. On success, an audit message is fired asynchronously to the configured Matrix room.
-
-4. **Audit trail** — every successful request posts a message like `[REQUEST] @user:example.com → [Movie] "Title" (2024)` to the Matrix audit room. This is fire-and-forget — failures are logged but never block the user's request.
-
-## Lidarr Notes
-
-Lidarr uses MusicBrainz IDs (`foreignArtistId`) rather than TMDB/TVDB IDs. The lookup response includes this field and it is passed through directly to the add call. No independent MBID resolution is needed.
-
 ## License

 See repository for license details.
--- a/SESSION_PLAN.md
+++ b/SESSION_PLAN.md
@@ -35,14 +35,14 @@ Rewriting Bellhop from a Python FastAPI web portal into a Go-based Matrix comman
  - All adds: monitored=true, search-on-add=true, quality profile + root folder from config
  - Unit tests with httptest

- [ ] **Session 4 — Command dispatch + main** (`internal/bot/`, `main.go`)
+- [x] **Session 4 — Command dispatch + main** (`internal/bot/`, `main.go`)
  - Parse `<prefix><cmd> <query>` (default prefix `!`)
  - Commands: `movie`, `tv`, `music`, `help`
  - On match: search → take `[0]` → add → reply with title/year (or error)
  - "Service not configured" reply if the corresponding *arr block is absent
  - `main.go`: load config, init matrix, wire handler, SIGINT/SIGTERM shutdown

- [ ] **Session 5 — Ship polish**
+- [x] **Session 5 — Ship polish**
  - Multi-stage Dockerfile (`golang:1.25-alpine` → `alpine:3.21`, build with `-tags goolm`)
  - `config.example.yaml`
  - Rewrite `README.md`: command UX, install, config reference, Docker
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -0,0 +1,42 @@
+# Bellhop config. Values like ${ENV_VAR} are expanded from the environment
+# at load time so secrets can stay out of this file.
+
+matrix:
+  homeserver: https://matrix.example.com
+  user_id: "@bellhop:example.com"
+  password: ${BELLHOP_MATRIX_PASSWORD}
+
+  # Optional. Defaults shown.
+  display_name: Bellhop
+  data_dir: ./data            # device.json + crypto.db live here
+  pickle_key: ${BELLHOP_PICKLE_KEY}  # encrypts the crypto store; pick something stable
+  command_prefix: "!"
+
+  # Rooms the bot will respond to commands in. Messages anywhere else are
+  # ignored. The bot auto-joins on invite, but joining alone does not grant
+  # command access — the room ID must appear here.
+  allowed_rooms:
+    - "!room-id-one:example.com"
+    - "!room-id-two:example.com"
+
+# Configure any subset. Omit a block to disable that command:
+# leaving out `radarr` makes `!movie` reply "Radarr is not configured".
+services:
+  radarr:
+    url: https://radarr.example.com
+    api_key: ${RADARR_API_KEY}
+    quality_profile_id: 1
+    root_folder: /movies
+
+  sonarr:
+    url: https://sonarr.example.com
+    api_key: ${SONARR_API_KEY}
+    quality_profile_id: 1
+    root_folder: /tv
+
+  lidarr:
+    url: https://lidarr.example.com
+    api_key: ${LIDARR_API_KEY}
+    quality_profile_id: 1
+    metadata_profile_id: 1   # required for Lidarr only
+    root_folder: /music
--- a/internal/bot/bot.go
+++ b/internal/bot/bot.go
@@ -0,0 +1,162 @@
+// Package bot wires Matrix command messages to the *arr clients.
+//
+// Commands take the form "<prefix><cmd> <query>" (e.g. "!movie dune"). The
+// dispatcher parses the message, picks the *arr client by command name,
+// performs a lookup, and adds the top hit. The reply is posted back into a
+// thread rooted at the request event so a busy room stays readable.
+package bot
+
+import (
+	"context"
+	"fmt"
+	"html"
+	"log/slog"
+	"strings"
+	"time"
+
+	"bellhop/internal/arr"
+
+	"maunium.net/go/mautrix/id"
+)
+
+// Replier sends a threaded reply into roomID under rootEventID.
+type Replier interface {
+	PostThreadedReply(roomID id.RoomID, rootEventID id.EventID, plain, htmlBody string) error
+}
+
+// Services holds the configured *arr clients. Any field may be nil; commands
+// that target an unconfigured service reply with "not configured".
+type Services struct {
+	Radarr arr.Client
+	Sonarr arr.Client
+	Lidarr arr.Client
+}
+
+// Dispatcher routes parsed commands to services and posts replies.
+type Dispatcher struct {
+	prefix   string
+	services Services
+	replier  Replier
+	timeout  time.Duration
+}
+
+// New builds a Dispatcher. prefix is the leading character(s) on a command
+// (e.g. "!"); a zero value defaults to "!".
+func New(prefix string, services Services, replier Replier) *Dispatcher {
+	if prefix == "" {
+		prefix = "!"
+	}
+	return &Dispatcher{
+		prefix:   prefix,
+		services: services,
+		replier:  replier,
+		timeout:  60 * time.Second,
+	}
+}
+
+// Handle is the matrix.MessageHandler entry point. It parses body, dispatches
+// the command, and posts a reply. Non-command messages are ignored silently.
+func (d *Dispatcher) Handle(roomID id.RoomID, eventID id.EventID, sender id.UserID, body string) {
+	cmd, query, ok := parseCommand(d.prefix, body)
+	if !ok {
+		return
+	}
+
+	slog.Info("bot: command received", "room", roomID, "sender", sender, "cmd", cmd, "query", query)
+
+	ctx, cancel := context.WithTimeout(context.Background(), d.timeout)
+	defer cancel()
+
+	plain, htmlBody := d.dispatch(ctx, cmd, query)
+	if err := d.replier.PostThreadedReply(roomID, eventID, plain, htmlBody); err != nil {
+		slog.Error("bot: reply failed", "room", roomID, "err", err)
+	}
+}
+
+// parseCommand pulls (cmd, query) out of a body like "!movie dune". Returns
+// ok=false when the message is not a command for us.
+func parseCommand(prefix, body string) (cmd, query string, ok bool) {
+	body = strings.TrimSpace(body)
+	if !strings.HasPrefix(body, prefix) {
+		return "", "", false
+	}
+	rest := strings.TrimSpace(body[len(prefix):])
+	if rest == "" {
+		return "", "", false
+	}
+	parts := strings.SplitN(rest, " ", 2)
+	cmd = strings.ToLower(parts[0])
+	if len(parts) == 2 {
+		query = strings.TrimSpace(parts[1])
+	}
+	return cmd, query, true
+}
+
+func (d *Dispatcher) dispatch(ctx context.Context, cmd, query string) (plain, htmlBody string) {
+	switch cmd {
+	case "help":
+		return d.help()
+	case "movie":
+		return d.run(ctx, "movie", "Radarr", d.services.Radarr, query)
+	case "tv":
+		return d.run(ctx, "tv", "Sonarr", d.services.Sonarr, query)
+	case "music":
+		return d.run(ctx, "music", "Lidarr", d.services.Lidarr, query)
+	default:
+		msg := fmt.Sprintf("Unknown command %q. Try %shelp.", cmd, d.prefix)
+		return msg, html.EscapeString(msg)
+	}
+}
+
+func (d *Dispatcher) run(ctx context.Context, cmd, service string, client arr.Client, query string) (plain, htmlBody string) {
+	if client == nil {
+		msg := fmt.Sprintf("%s is not configured.", service)
+		return msg, html.EscapeString(msg)
+	}
+	if query == "" {
+		msg := fmt.Sprintf("Usage: %s%s <query>", d.prefix, cmd)
+		return msg, html.EscapeString(msg)
+	}
+
+	results, err := client.Search(ctx, query)
+	if err != nil {
+		slog.Error("bot: search failed", "service", service, "query", query, "err", err)
+		msg := fmt.Sprintf("%s search failed: %v", service, err)
+		return msg, html.EscapeString(msg)
+	}
+	if len(results) == 0 {
+		msg := fmt.Sprintf("No %s results for %q.", service, query)
+		return msg, html.EscapeString(msg)
+	}
+
+	top := results[0]
+	if err := client.Add(ctx, top); err != nil {
+		slog.Error("bot: add failed", "service", service, "title", top.Title, "err", err)
+		msg := fmt.Sprintf("%s: failed to add %s: %v", service, formatTitle(top), err)
+		return msg, html.EscapeString(msg)
+	}
+
+	plain = fmt.Sprintf("Added to %s: %s", service, formatTitle(top))
+	htmlBody = fmt.Sprintf("Added to <b>%s</b>: %s", html.EscapeString(service), html.EscapeString(formatTitle(top)))
+	return plain, htmlBody
+}
+
+func (d *Dispatcher) help() (string, string) {
+	lines := []string{
+		"Bellhop commands:",
+		fmt.Sprintf("  %smovie <query>  — add the top Radarr hit", d.prefix),
+		fmt.Sprintf("  %stv <query>     — add the top Sonarr hit", d.prefix),
+		fmt.Sprintf("  %smusic <query>  — add the top Lidarr hit", d.prefix),
+		fmt.Sprintf("  %shelp           — show this message", d.prefix),
+	}
+	plain := strings.Join(lines, "\n")
+	htmlBody := "<pre>" + html.EscapeString(plain) + "</pre>"
+	return plain, htmlBody
+}
+
+func formatTitle(r arr.Result) string {
+	if r.Year > 0 {
+		return fmt.Sprintf("%s (%d)", r.Title, r.Year)
+	}
+	return r.Title
+}
--- a/internal/bot/bot_test.go
+++ b/internal/bot/bot_test.go
@@ -0,0 +1,218 @@
+package bot
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+
+	"bellhop/internal/arr"
+
+	"maunium.net/go/mautrix/id"
+)
+
+type stubClient struct {
+	results []arr.Result
+	addErr  error
+	srchErr error
+
+	searched string
+	added    []arr.Result
+}
+
+func (s *stubClient) Search(_ context.Context, term string) ([]arr.Result, error) {
+	s.searched = term
+	if s.srchErr != nil {
+		return nil, s.srchErr
+	}
+	return s.results, nil
+}
+
+func (s *stubClient) Add(_ context.Context, r arr.Result) error {
+	if s.addErr != nil {
+		return s.addErr
+	}
+	s.added = append(s.added, r)
+	return nil
+}
+
+type stubReplier struct {
+	mu       sync.Mutex
+	plain    string
+	htmlBody string
+	calls    int
+}
+
+func (r *stubReplier) PostThreadedReply(_ id.RoomID, _ id.EventID, plain, htmlBody string) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.calls++
+	r.plain = plain
+	r.htmlBody = htmlBody
+	return nil
+}
+
+const (
+	room   = id.RoomID("!room:example.org")
+	event  = id.EventID("$evt")
+	sender = id.UserID("@alice:example.org")
+)
+
+func TestParseCommand(t *testing.T) {
+	cases := []struct {
+		body            string
+		wantCmd, wantQ  string
+		wantOk          bool
+	}{
+		{"!movie dune", "movie", "dune", true},
+		{"  !movie  dune part two  ", "movie", "dune part two", true},
+		{"!HELP", "help", "", true},
+		{"hello world", "", "", false},
+		{"!", "", "", false},
+		{"!  ", "", "", false},
+	}
+	for _, c := range cases {
+		cmd, q, ok := parseCommand("!", c.body)
+		if cmd != c.wantCmd || q != c.wantQ || ok != c.wantOk {
+			t.Errorf("parseCommand(%q) = (%q,%q,%v); want (%q,%q,%v)",
+				c.body, cmd, q, ok, c.wantCmd, c.wantQ, c.wantOk)
+		}
+	}
+}
+
+func TestDispatchMovieTopHit(t *testing.T) {
+	radarr := &stubClient{results: []arr.Result{
+		{Title: "Dune", Year: 2021},
+		{Title: "Dune", Year: 1984},
+	}}
+	rep := &stubReplier{}
+	d := New("!", Services{Radarr: radarr}, rep)
+
+	d.Handle(room, event, sender, "!movie dune")
+
+	if radarr.searched != "dune" {
+		t.Fatalf("search term = %q", radarr.searched)
+	}
+	if len(radarr.added) != 1 || radarr.added[0].Year != 2021 {
+		t.Fatalf("expected top hit added, got %+v", radarr.added)
+	}
+	if !strings.Contains(rep.plain, "Dune (2021)") || !strings.Contains(rep.plain, "Radarr") {
+		t.Fatalf("reply missing expected content: %q", rep.plain)
+	}
+}
+
+func TestDispatchNoResults(t *testing.T) {
+	sonarr := &stubClient{}
+	rep := &stubReplier{}
+	d := New("!", Services{Sonarr: sonarr}, rep)
+
+	d.Handle(room, event, sender, "!tv obscure show")
+
+	if len(sonarr.added) != 0 {
+		t.Fatal("should not add when no results")
+	}
+	if !strings.Contains(rep.plain, "No Sonarr results") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestDispatchUnconfigured(t *testing.T) {
+	rep := &stubReplier{}
+	d := New("!", Services{}, rep)
+
+	d.Handle(room, event, sender, "!music radiohead")
+
+	if !strings.Contains(rep.plain, "Lidarr is not configured") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestDispatchEmptyQuery(t *testing.T) {
+	radarr := &stubClient{}
+	rep := &stubReplier{}
+	d := New("!", Services{Radarr: radarr}, rep)
+
+	d.Handle(room, event, sender, "!movie")
+
+	if radarr.searched != "" {
+		t.Fatal("should not search with empty query")
+	}
+	if !strings.Contains(rep.plain, "Usage:") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestDispatchAddError(t *testing.T) {
+	radarr := &stubClient{
+		results: []arr.Result{{Title: "Dune", Year: 2021}},
+		addErr:  errors.New("boom"),
+	}
+	rep := &stubReplier{}
+	d := New("!", Services{Radarr: radarr}, rep)
+
+	d.Handle(room, event, sender, "!movie dune")
+
+	if !strings.Contains(rep.plain, "failed to add") || !strings.Contains(rep.plain, "boom") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestDispatchSearchError(t *testing.T) {
+	radarr := &stubClient{srchErr: errors.New("network down")}
+	rep := &stubReplier{}
+	d := New("!", Services{Radarr: radarr}, rep)
+
+	d.Handle(room, event, sender, "!movie dune")
+
+	if !strings.Contains(rep.plain, "search failed") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestDispatchHelp(t *testing.T) {
+	rep := &stubReplier{}
+	d := New("!", Services{}, rep)
+
+	d.Handle(room, event, sender, "!help")
+
+	for _, want := range []string{"!movie", "!tv", "!music", "!help"} {
+		if !strings.Contains(rep.plain, want) {
+			t.Errorf("help missing %q: %q", want, rep.plain)
+		}
+	}
+}
+
+func TestDispatchUnknown(t *testing.T) {
+	rep := &stubReplier{}
+	d := New("!", Services{}, rep)
+
+	d.Handle(room, event, sender, "!frobnicate stuff")
+
+	if !strings.Contains(rep.plain, "Unknown command") {
+		t.Fatalf("unexpected reply: %q", rep.plain)
+	}
+}
+
+func TestNonCommandIgnored(t *testing.T) {
+	rep := &stubReplier{}
+	d := New("!", Services{}, rep)
+
+	d.Handle(room, event, sender, "just chatting")
+
+	if rep.calls != 0 {
+		t.Fatalf("expected no reply, got %d", rep.calls)
+	}
+}
+
+func TestCustomPrefix(t *testing.T) {
+	radarr := &stubClient{results: []arr.Result{{Title: "Dune", Year: 2021}}}
+	rep := &stubReplier{}
+	d := New(".bh ", Services{Radarr: radarr}, rep)
+
+	d.Handle(room, event, sender, ".bh movie dune")
+
+	if len(radarr.added) != 1 {
+		t.Fatalf("expected add, got %d", len(radarr.added))
+	}
+}
--- a/main.go
+++ b/main.go
@@ -0,0 +1,62 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"bellhop/internal/arr"
+	"bellhop/internal/bot"
+	"bellhop/internal/config"
+	"bellhop/internal/matrix"
+)
+
+func main() {
+	configPath := flag.String("config", "config.yaml", "path to config file")
+	flag.Parse()
+
+	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelInfo})))
+
+	cfg, err := config.Load(*configPath)
+	if err != nil {
+		slog.Error("config load failed", "err", err)
+		os.Exit(1)
+	}
+
+	services := bot.Services{}
+	if cfg.Services.Radarr != nil {
+		services.Radarr = arr.NewRadarr(cfg.Services.Radarr)
+	}
+	if cfg.Services.Sonarr != nil {
+		services.Sonarr = arr.NewSonarr(cfg.Services.Sonarr)
+	}
+	if cfg.Services.Lidarr != nil {
+		services.Lidarr = arr.NewLidarr(cfg.Services.Lidarr)
+	}
+
+	mx, err := matrix.New(cfg.Matrix)
+	if err != nil {
+		slog.Error("matrix init failed", "err", err)
+		os.Exit(1)
+	}
+
+	dispatcher := bot.New(cfg.Matrix.CommandPrefix, services, mx)
+	mx.SetMessageHandler(dispatcher.Handle)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	mx.Start(ctx)
+	slog.Info("bellhop started", "allowed_rooms", len(cfg.Matrix.AllowedRooms))
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	<-sig
+
+	slog.Info("shutting down")
+	cancel()
+	mx.Stop()
+}