refactor: split monolithic doctor.py into a package

.env.example

@@ -3,3 +3,7 @@ SONARR_API_KEY=
 RADARR_API_KEY=
 SONARR4K_API_KEY=
 RADARR4K_API_KEY=
+PROWLARR_API_KEY=
+BAZARR_API_KEY=
+SEERR_API_KEY=
+PLEX_TOKEN=

.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  # ── 1. Unit tests ────────────────────────────────────────────────────────
+  test:
+    name: Unit tests (Python 3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run test suite
+        run: python3 -m unittest discover -s tests -v
+
+  # ── 2. Syntax / lint gate ────────────────────────────────────────────────
+  lint:
+    name: Syntax + lint (compileall + ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Compile check (syntax errors)
+        run: python3 -m compileall -q doctor/
+
+      - name: Install ruff
+        run: pip install --quiet ruff
+
+      - name: Ruff — undefined names and unused imports (F-only)
+        run: ruff check doctor/ tests/ --output-format=github
+
+  # ── 3. Startup + /healthz smoke ─────────────────────────────────────────
+  smoke:
+    name: Startup smoke + /healthz
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Start daemon (no checks, UI enabled)
+        run: |
+          ENABLE_QUEUE=false \
+          ENABLE_MULTIPACK=false \
+          ENABLE_UI=true \
+          DOCTOR_UI_PORT=12345 \
+          DOCTOR_STATE_FILE=/tmp/doctor_state.json \
+          python3 -m doctor &
+          echo $! > /tmp/doctor.pid
+
+      - name: Wait for HTTP server to be ready
+        run: |
+          for i in $(seq 1 10); do
+            if curl -sf http://127.0.0.1:12345/healthz; then
+              echo " — /healthz OK"
+              exit 0
+            fi
+            sleep 0.5
+          done
+          echo "ERROR: /healthz did not respond within 5s"
+          exit 1
+
+      - name: Tear down daemon
+        if: always()
+        run: kill $(cat /tmp/doctor.pid) 2>/dev/null || true
+
+  # ── 4. Docker publish (main + tags only, gated on test + lint + smoke) ──
+  publish:
+    name: Build and push image
+    runs-on: ubuntu-latest
+    needs: [test, lint, smoke]
+    if: |
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=tag
+            type=sha,format=short
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/docker-publish.yml

@@ -1,45 +1,17 @@
-name: publish image
+# This workflow has been superseded by ci.yml which runs tests, lint, and smoke
+# before publishing. The publish job now lives in ci.yml as the final gated step.
+# This file is retained for reference only and has no triggers.
+name: publish image (retired)
 
 on:
-  push:
-    branches: [ main ]
-    tags: [ 'v*' ]
   workflow_dispatch:
+    inputs:
+      reason:
+        description: "Reason (this workflow is retired — use ci.yml)"
+        required: false
 
 jobs:
-  build-and-push:
+  notice:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
     steps:
-      - uses: actions/checkout@v4
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Docker metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository }}
-          tags: |
-            type=raw,value=latest,enable={{is_default_branch}}
-            type=ref,event=tag
-            type=sha,format=short
-
-      - name: Set up Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Build and push
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+      - run: echo "This workflow is retired. Publishing is handled by ci.yml."

AGENTS.md

@@ -0,0 +1,26 @@
+# Agent Notes
+
+This project is a pure-Python package (no third-party dependencies).
+
+## How to run
+
+```bash
+python3 -m doctor
+```
+
+## How to run tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Quick smoke test
+
+```bash
+ENABLE_QUEUE=false ENABLE_UI=true DOCTOR_UI_PORT=12345 DOCTOR_STATE_FILE=/tmp/doctor_state.json timeout 3 python3 -m doctor
+```
+
+## How to deploy
+
+- Docker: `COPY doctor /app/doctor` and `ENTRYPOINT ["python3", "-m", "doctor"]`.
+- Host systemd: copy the `doctor/` package directory, set `WorkingDirectory` to that directory, and run `python3 -m doctor`.

DEPLOY.md

@@ -1,6 +1,6 @@
 # Deployment guide
 
-stack-doctor is one small file (`doctor.py`, pure Python standard library, no dependencies).
+stack-doctor is a small pure-Python package (standard library only, no third-party dependencies).
 Pick the path that matches your setup:
 
 - **Docker** is easiest. It runs the `queue` / `providers` / `plex` / `resources` checks and the
@@ -69,8 +69,9 @@ Run this on the machine that runs decypharr.
 
 ```bash
 mkdir -p /opt/stack-doctor
-curl -fsSL https://raw.githubusercontent.com/Neoo-Blue/stack-doctor/main/doctor.py \
-  -o /opt/stack-doctor/doctor.py
+cd /opt/stack-doctor
+curl -fsSL https://github.com/Neoo-Blue/stack-doctor/archive/refs/heads/main.tar.gz \
+  | tar -xz --strip-components=1 stack-doctor-main/doctor
 ```
 
 2. Install the service template and edit the values (URLs, API keys, paths):
@@ -115,6 +116,6 @@ and open `http://<host>:12345/?token=something`.
 ## Updating
 
 - **Docker**: `docker compose pull && docker compose up -d`
-- **Host**: re-download `doctor.py` (step 1 above) and `systemctl restart stack-doctor`
+- **Host**: re-download/extract the `doctor` package (step 1 above) and `systemctl restart stack-doctor`
 
 Your saved settings live in `DOCTOR_CONFIG_FILE` (`/data/config.json` by default) and survive updates.

Dockerfile

@@ -9,19 +9,26 @@ ENV PYTHONUNBUFFERED=1 \
     DOCTOR_STATE_FILE=/data/state.json
 
 WORKDIR /app
-COPY doctor.py /app/doctor.py
+COPY doctor /app/doctor
 
-# No Python dependencies (standard library only). openssh-client lets a restart
-# hook reach a *host* service (e.g. DECYPHARR_RESTART_CMD="ssh root@host systemctl restart decypharr").
+# The doctor package uses only the Python standard library. openssh-client lets a
+# restart hook reach a *host* service (e.g. DECYPHARR_RESTART_CMD="ssh root@host systemctl restart decypharr").
+# docker-ce-cli lets a restart hook control local containers via a bind-mounted /var/run/docker.sock.
 # Runs as root so a bind-mounted /data (and an optional rw /mnt/library for the
 # janitor) is always writable regardless of host ownership.
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends openssh-client \
-    && rm -rf /var/lib/apt/lists/* \
+    && apt-get install -y --no-install-recommends openssh-client ca-certificates curl gnupg \
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc \
+    && chmod a+r /etc/apt/keyrings/docker.asc \
+    && echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable" > /etc/apt/sources.list.d/docker.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends docker-ce-cli \
+    && rm -rf /var/lib/apt/lists/* /etc/apt/keyrings /etc/apt/sources.list.d/docker.list \
     && mkdir -p /data
 VOLUME /data
 
 # webhook port (event mode) + web dashboard (ENABLE_UI)
 EXPOSE 8088 12345
 
-ENTRYPOINT ["python3", "/app/doctor.py"]
+ENTRYPOINT ["python3", "-m", "doctor"]