Fix theming bug (#722)

- Adds full interaction with Hardcover lists, including adding and
removing from lists + want to read status
- List selection exposed in search results, details modal and release
modal
- Added automatic list dropdown when selecting "list" search
- Added auto-removal of books from a list when downloading from that
specific list page
- Changed search selector to hover-activated

.github/workflows/build-and-publish-docker-image.yml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 env:
   REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
+  IMAGE_NAME: ${{ github.repository_owner }}/shelfmark
 jobs:
   build-and-push-images:
     runs-on: ubuntu-latest
@@ -20,15 +20,9 @@ jobs:
     strategy:
       matrix:
         include:
-          - suffix: ""
-            target: cwa-bd
-            image_name_suffix: ""
-          - suffix: "-tor"
-            target: cwa-bd-tor
-            image_name_suffix: "-tor"
-          - suffix: "-extbp"
-            target: cwa-bd-extbp
-            image_name_suffix: "-extbp"
+          - target: shelfmark
+          - target: shelfmark-lite
+            image_name_suffix: "-lite"
     steps:
       - name: Get current date
         id: date
@@ -80,4 +74,71 @@ jobs:
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}${{ matrix.image_name_suffix }}
           subject-digest: ${{ steps.push.outputs.digest }}
-          push-to-registry: true
+          push-to-registry: true
+
+  # Create aliases for backwards compatibility
+  create-aliases:
+    needs: build-and-push-images
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: write
+    env:
+      # Legacy name for backwards compatibility (hardcoded so it works after rename)
+      LEGACY_NAME: calibre-web-automated-book-downloader
+    steps:
+      - name: Log in to registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Create legacy aliases
+        run: |
+          # Current image names (follows repo name)
+          STANDARD="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          LITE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-lite"
+
+          # Legacy image names (hardcoded for backwards compatibility)
+          LEGACY="${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.LEGACY_NAME }}"
+          LEGACY_TOR="${LEGACY}-tor"
+          LEGACY_EXTBP="${LEGACY}-extbp"
+
+          SHA_SHORT=$(echo "${{ github.sha }}" | cut -c1-7)
+
+          # Helper function to create alias with all standard tags
+          create_alias() {
+            local SOURCE=$1
+            local ALIAS=$2
+
+            # Always create SHA tag
+            docker buildx imagetools create -t "${ALIAS}:sha-${SHA_SHORT}" "${SOURCE}:sha-${SHA_SHORT}"
+
+            if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+              VERSION="${{ github.ref_name }}"
+              VERSION_NUM="${VERSION#v}"
+              MINOR="${VERSION_NUM%.*}"
+
+              docker buildx imagetools create -t "${ALIAS}:latest" "${SOURCE}:latest"
+              docker buildx imagetools create -t "${ALIAS}:${VERSION_NUM}" "${SOURCE}:${VERSION_NUM}"
+              docker buildx imagetools create -t "${ALIAS}:${MINOR}" "${SOURCE}:${MINOR}"
+              docker buildx imagetools create -t "${ALIAS}:${VERSION}" "${SOURCE}:${VERSION}"
+            else
+              docker buildx imagetools create -t "${ALIAS}:dev" "${SOURCE}:dev"
+            fi
+          }
+
+          # Create legacy aliases pointing to current images
+          # calibre-web-automated-book-downloader → standard image
+          create_alias "${STANDARD}" "${LEGACY}"
+
+          # calibre-web-automated-book-downloader-tor → standard image
+          create_alias "${STANDARD}" "${LEGACY_TOR}"
+
+          # calibre-web-automated-book-downloader-extbp → lite image
+          create_alias "${LITE}" "${LEGACY_EXTBP}"

.gitignore

@@ -228,3 +228,9 @@ pyrightconfig.json
 # End of https://www.toptal.com/developers/gitignore/api/macos,visualstudiocode,python
 /downloaded_files
 /.local/
+*.local.*
+AGENTS.md
+.claude/
+.playwright-mcp/
+frontend-dist/
+node_modules/

.vscode/launch.json

@@ -2,17 +2,17 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Python Debugger: Current CWABD File",
+      "name": "Python Debugger: Current Shelfmark File",
       "type": "debugpy",
       "request": "launch",
       "program": "${file}",
       "console": "integratedTerminal",
       "justMyCode": false,
       "env": {
-        "INGEST_DIR": "/tmp/cwa-book-downloader",
-        "TEMP_DIR": "/tmp/cwa-book-downloader",
+        "INGEST_DIR": "/tmp/shelfmark",
+        "TEMP_DIR": "/tmp/shelfmark",
         "LOG_LEVEL": "DEBUG",
-        "LOG_ROOT": "/tmp/cwa-book-downloader",
+        "LOG_ROOT": "/tmp/shelfmark",
         "ENABLE_LOGGING": "true",
         "DOCKERMODE": "false",
         "DEBUG": "true",
@@ -27,7 +27,7 @@
       "preLaunchTask": "docker-compose up (dev)", // Spin up dev containers
       "postDebugTask": "docker-compose down (dev)", // Optional: tear them down
       "env": {
-        "INGEST_DIR": "/tmp/cwa-book-downloader"
+        "INGEST_DIR": "/tmp/shelfmark"
       },
     },
     {
@@ -38,7 +38,7 @@
       "preLaunchTask": "docker-compose up (prod)",
       "postDebugTask": "docker-compose down (prod)",
       "env": {
-        "INGEST_DIR": "/tmp/cwa-book-downloader"
+        "INGEST_DIR": "/tmp/shelfmark"
       },
     },
     {
@@ -54,9 +54,9 @@
   ],
   "compounds": [
     {
-      "name": "Launch CWA-BD",
+      "name": "Launch Shelfmark",
       "configurations": [
-        "Launch cwa-bd app.py",
+        "Launch Shelfmark app.py",
         "Launch Browser"
       ]
     }

Dockerfile

@@ -14,8 +14,9 @@ WORKDIR /frontend
 # Copy frontend package files
 COPY src/frontend/package*.json ./
 
-# Install dependencies
-RUN npm ci
+# Install dependencies (cache mount for faster rebuilds)
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci
 
 # Copy frontend source
 COPY src/frontend/ ./
@@ -44,9 +45,9 @@ ENV DEBIAN_FRONTEND=noninteractive \
     PIP_NO_CACHE_DIR=1 \
     PIP_DISABLE_PIP_VERSION_CHECK=1 \
     PIP_DEFAULT_TIMEOUT=100 \
-    NAME=Calibre-Web-Automated-Book-Downloader \
+    NAME=Shelfmark \
     PYTHONPATH=/app \
-    # UID/GID will be handled by entrypoint script, but TZ/Locale are still needed
+    # PUID/PGID will be handled by entrypoint script, but TZ/Locale are still needed
     LANG=en_US.UTF-8 \
     LANGUAGE=en_US:en \
     LC_ALL=en_US.UTF-8
@@ -67,7 +68,14 @@ RUN apt-get update && \
     # For debug
     zip iputils-ping \
     # For user switching
-    sudo && \
+    gosu \
+    # --- Tor support (activated via USING_TOR=true) ---
+    tor \
+    supervisor \
+    iptables && \
+    # Configure iptables alternatives for tor.sh compatibility
+    update-alternatives --set iptables /usr/sbin/iptables-legacy && \
+    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy && \
     # Cleanup APT cache *after* all installs in this layer
     apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false && \
     apt-get clean && \
@@ -84,12 +92,11 @@ RUN apt-get update && \
 WORKDIR /app
 
 # Install Python dependencies using pip
-# Upgrade pip first, then copy requirements and install
-# Copying requirements-base.txt separately leverages build cache
-COPY requirements-base.txt .
-RUN pip install --no-cache-dir -r requirements-base.txt && \
-    # Clean root's pip cache
-    rm -rf /root/.cache
+# Copying requirements files separately leverages build cache
+# Cache mount persists pip cache between builds for faster installs
+COPY requirements-base.txt requirements-shelfmark.txt ./
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r requirements-base.txt
 
 # Copy application code *after* dependencies are installed
 COPY . .
@@ -100,7 +107,7 @@ COPY --from=frontend-builder /frontend/dist /app/frontend-dist
 # Final setup: permissions and directories in one layer
 # Only creating directories and setting executable bits.
 # Ownership will be handled by the entrypoint script.
-RUN mkdir -p /var/log/cwa-book-downloader /cwa-book-ingest && \
+RUN mkdir -p /var/log/shelfmark /books && \
     chmod +x /app/entrypoint.sh /app/tor.sh /app/genDebug.sh
 
 # Expose the application port
@@ -115,7 +122,7 @@ HEALTHCHECK --interval=60s --timeout=60s --start-period=60s --retries=3 \
 ENTRYPOINT ["/usr/bin/dumb-init", "--"]
 
 
-FROM base AS cwa-bd
+FROM base AS shelfmark
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
@@ -123,55 +130,33 @@ RUN apt-get update && \
     xvfb \
     # For screen recording
     ffmpeg \
-    # --- Chromium ---
+    # --- Chromium (unpinned - uses latest from Debian repos) ---
+    # Chrome 144+ requires --enable-unsafe-swiftshader for WebGL in Docker.
+    # This flag is set in internal_bypasser.py _get_browser_args()
     chromium \
-    # --- ChromeDriver ---
-    chromium-driver \
+    chromium-common \
     # For tkinter (pyautogui)
     python3-tk \
     # For RAR extraction
     unrar-free && \
     # Create symlink so rarfile library can find unrar
-    ln -sf /usr/bin/unrar-free /usr/bin/unrar
-
-# install additional dependencies
-COPY requirements-cwa-bd.txt ./
-RUN pip install --no-cache-dir -r requirements-cwa-bd.txt && \
-    # Clean root's pip cache
-    rm -rf /root/.cache
-
-# Add this line to grant read/execute permissions to others
-RUN chmod -R o+rx /usr/bin/chromium && \
-    chmod -R o+rx /usr/bin/chromedriver && \
-    chmod -R o+w /usr/local/lib/python3.10/site-packages/seleniumbase/drivers/
-
-# Default command to run the application entrypoint script
-CMD ["/app/entrypoint.sh"]
-
-FROM cwa-bd AS cwa-bd-tor
-
-ENV USING_TOR=true
-
-# Install Tor and dependencies
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends \
-    # --- Tor ---
-    tor \
-    # --- Supervisor ---
-    supervisor \
-    # --- iptables ---
-    iptables && \
-    update-alternatives --set iptables /usr/sbin/iptables-legacy && \
-    update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy && \
-    # Cleanup APT cache *after* all installs in this layer
+    ln -sf /usr/bin/unrar-free /usr/bin/unrar && \
+    # Cleanup APT cache
     apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
 
-# Override the default command to run Tor
+# Install additional dependencies (requirements file already copied in base stage)
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r requirements-shelfmark.txt
+
+# Grant read/execute permissions to others
+RUN chmod -R o+rx /usr/bin/chromium
+
+# Default command to run the application entrypoint script
 CMD ["/app/entrypoint.sh"]
 
-FROM base AS cwa-bd-extbp
+FROM base AS shelfmark-lite
 
 ENV USING_EXTERNAL_BYPASSER=true
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install dev build preview typecheck clean up down docker-build refresh
+.PHONY: help install dev build preview typecheck frontend-test clean up down docker-build refresh restart
 
 # Frontend directory
 FRONTEND_DIR := src/frontend
@@ -16,11 +16,13 @@ help:
 	@echo "  build      - Build frontend for production"
 	@echo "  preview    - Preview production build"
 	@echo "  typecheck  - Run TypeScript type checking"
+	@echo "  frontend-test - Run frontend unit tests"
 	@echo "  clean      - Remove node_modules and build artifacts"
 	@echo ""
 	@echo "Backend (Docker):"
 	@echo "  up         - Start backend services"
 	@echo "  down       - Stop backend services"
+	@echo "  restart    - Restart backend services (no rebuild)"
 	@echo "  docker-build - Build Docker image"
 	@echo "  refresh    - Rebuild and restart backend services"
 
@@ -49,6 +51,11 @@ typecheck:
 	@echo "Running TypeScript type checking..."
 	cd $(FRONTEND_DIR) && npm run typecheck
 
+# Run frontend unit tests
+frontend-test:
+	@echo "Running frontend unit tests..."
+	cd $(FRONTEND_DIR) && npm run test:unit
+
 # Clean build artifacts and dependencies
 clean:
 	@echo "Cleaning build artifacts and dependencies..."
@@ -70,6 +77,11 @@ docker-build:
 	@echo "Building Docker image..."
 	docker compose -f $(COMPOSE_FILE) build
 
+# Restart backend services (no rebuild)
+restart:
+	@echo "Restarting backend services..."
+	docker compose -f $(COMPOSE_FILE) restart
+
 # Rebuild and restart backend services
 refresh:
 	@echo "Rebuilding and restarting backend services..."

README.v2.md

@@ -1,240 +0,0 @@
-# 📚 Book Downloader
-*calibre-web-automated-book-downloader*
-
-<img src="src/frontend/public/logo.png" alt="Book Downloader" width="200">
-
-A unified web interface for searching and downloading books from multiple sources — all in one place. Works out of the box with popular web sources, no configuration required. Add metadata providers, additional release sources, and download clients to create a single hub for building your digital library.
-
-**Fully standalone** — no external dependencies required. Works great alongside library tools like [Calibre-Web-Automated](https://github.com/crocodilestick/Calibre-Web-Automated) or [Booklore](https://github.com/booklore-app/booklore) for automatic import.
-
-## ✨ Features
-
-- **One-Stop Interface** - A clean, modern UI to search, browse, and download from multiple sources in one place
-- **Real-Time Progress** - Unified download queue with live status updates across all sources
-- **Two Search Modes**:
-  - **Direct Download** - Search and download from popular web sources
-  - **Universal Mode** - Search metadata providers (Hardcover, Open Library) for richer book discovery and multi-source downloads *(additional sources in development - coming soon!)*
-- **Format Support** - EPUB, MOBI, AZW3, FB2, DJVU, CBZ, CBR and more
-- **Cloudflare Bypass** - Built-in bypasser for reliable access to protected sources
-- **PWA Support** - Install as a mobile app for quick access
-- **Docker Deployment** - Up and running in minutes
-
-## 🖼️ Screenshots
-
-**Home screen**
-![Home screen](README_images/homescreen.png 'Home screen')
-
-**Search results**
-![Search results](README_images/search-results.png 'Search results')
-
-**Multi-source downloads**
-![Multi-source downloads](README_images/multi-source.png 'Multi-source downloads')
-
-**Download queue**
-![Download queue](README_images/downloads.png 'Download queue')
-
-## 🚀 Quick Start
-
-### Prerequisites
-
-- Docker & Docker Compose
-
-### Installation
-
-1. Download the docker-compose file:
-   ```bash
-   curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/main/docker-compose.yml
-   ```
-
-2. Start the service:
-   ```bash
-   docker compose up -d
-   ```
-
-3. Open `http://localhost:8084`
-
-That's it! Configure settings through the web interface as needed.
-
-### Volume Setup
-
-```yaml
-volumes:
-  - /your/config/path:/config             # Config, database, and artwork cache directory
-  - /your/download/path:/cwa-book-ingest  # Downloaded books
-```
-
-> **Tip**: Point the download volume to your CWA or Booklore ingest folder for automatic import.
-
-> **Note**: CIFS shares require `nobrl` mount option to avoid database lock errors.
-
-## ⚙️ Configuration
-
-### Search Modes
-
-**Direct Download Mode** (default)
-- Works out of the box, no setup required
-- Searches a huge library of books directly
-- Returns downloadable releases immediately
-
-**Universal Mode**
-- Cleaner search results via metadata providers (Hardcover, Open Library)
-- Aggregates releases from multiple configured sources
-- Requires manual setup (API keys, additional sources)
-
-Set the mode via Settings or `SEARCH_MODE` environment variable.
-
-### Environment Variables
-
-Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `FLASK_PORT` | Web interface port | `8084` |
-| `INGEST_DIR` | Book download directory | `/cwa-book-ingest` |
-| `TZ` | Container timezone | `UTC` |
-| `UID` / `GID` | Runtime user/group ID | `1000` / `100` |
-| `SEARCH_MODE` | `direct` or `universal` | `direct` |
-
-Some of the additional options available in Settings:
-- **AA Donator Key** - Use your paid account to skip Cloudflare challenges entirely and use faster, direct downloads
-- **Library Link** - Add a link to your Calibre-Web or Booklore instance in the UI header
-- **Content Folders** - Route fiction, non-fiction, comics, etc. to separate directories
-- **Network Resilience** - Auto DNS rotation and mirror fallback when sources are unreachable
-- **Format & Language** - Filter downloads by preferred formats and languages
-- **Metadata Providers** - Configure API keys for Hardcover, Open Library, etc.
-
-## 🐳 Docker Variants
-
-### Standard
-```bash
-docker compose up -d
-```
-
-### Tor Variant
-Routes all traffic through Tor for enhanced privacy:
-```bash
-curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/main/docker-compose.tor.yml
-docker compose -f docker-compose.tor.yml up -d
-```
-
-**Notes:**
-- Requires `NET_ADMIN` and `NET_RAW` capabilities
-- Timezone is auto-detected from Tor exit node
-- Custom DNS/proxy settings are ignored
-
-### External Cloudflare Resolver
-Use FlareSolverr or ByParr instead of the built-in bypasser:
-```bash
-curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/main/docker-compose.extbp.yml
-docker compose -f docker-compose.extbp.yml up -d
-```
-
-Configure the resolver URL in Settings under the Cloudflare tab.
-
-**When to use external vs internal bypasser:**
-- **External** is useful if you already run FlareSolverr for other services (saves resources) or if you rarely need bypassing
-- **Internal** (default) is faster and more reliable for most users - it's optimized specifically for this application
-
-## 🔐 Authentication
-
-Authentication is optional but recommended for shared or exposed instances. Enable in Settings.
-
-**Alternative**: If you're running Calibre-Web, you can reuse its user database by mounting it:
-
-```yaml
-volumes:
-  - /path/to/calibre-web/app.db:/auth/app.db:ro
-```
-
-## Health Monitoring
-
-The application exposes a health endpoint at `/api/status`. Add a health check to your compose:
-
-```yaml
-healthcheck:
-  test: ["CMD", "curl", "-sf", "http://localhost:8084/api/status"]
-  interval: 30s
-  timeout: 30s
-  retries: 3
-```
-
-## Logging
-
-Logs are available via:
-- `docker logs <container-name>`
-- `/var/log/cwa-book-downloader/` inside the container (when `ENABLE_LOGGING=true`)
-
-Log level is configurable via Settings or `LOG_LEVEL` environment variable.
-
-## Development
-
-```bash
-# Frontend development
-make install     # Install dependencies
-make dev         # Start Vite dev server (localhost:5173)
-make build       # Production build
-make typecheck   # TypeScript checks
-
-# Backend (Docker)
-make up          # Start backend via docker-compose.dev.yml
-make down        # Stop services
-make refresh     # Rebuild and restart
-```
-
-The frontend dev server proxies to the backend on port 8084.
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Web Interface                          │
-│                 (React + TypeScript + Vite)                 │
-├─────────────────────────────────────────────────────────────┤
-│                      Flask Backend                          │
-│                   (REST API + WebSocket)                    │
-├───────────────────┬─────────────────────┬───────────────────┤
-│ Metadata Providers│   Download Queue    │  Cloudflare       │
-│                   │   & Orchestrator    │  Bypass           │
-├───────────────────┼─────────────────────┼───────────────────┤
-│ • Hardcover       │ • Task scheduling   │ • Internal        │
-│ • Open Library    │ • Progress tracking │ • External        │
-│                   │ • Retry logic       │   (FlareSolverr)  │
-├───────────────────┴─────────────────────┴───────────────────┤
-│                     Release Sources                         │
-├─────────────────────────────────────────────────────────────┤
-│ • Direct Download (Anna's Archive → Libgen → Welib)         │
-├─────────────────────────────────────────────────────────────┤
-│                     Network Layer                           │
-├─────────────────────────────────────────────────────────────┤
-│ • Auto DNS rotation  • Mirror failover  • Resume support    │
-└─────────────────────────────────────────────────────────────┘
-```
-
-The backend uses a plugin architecture. Metadata providers and release sources register via decorators and are automatically discovered.
-
-## Contributing
-
-Contributions are welcome! Please file issues or submit pull requests on GitHub.
-
-> **Note**: Additional release sources and download clients are under active development. Want to add support for your favorite source? Check out the plugin architecture above and submit a PR!
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.
-
-## ⚠️ Disclaimers
-
-### Copyright Notice
-
-This tool can access various sources including those that might contain copyrighted material. Users are responsible for:
-- Ensuring they have the right to download requested materials
-- Respecting copyright laws and intellectual property rights
-- Using the tool in compliance with their local regulations
-
-### Library Integration
-
-Downloads are written atomically (via intermediate `.crdownload` files) to prevent partial files from being ingested. However, if your library tool (CWA, Booklore, Calibre) is actively scanning or importing, there's a small chance of race conditions. If you experience database errors or import failures, try pausing your library's auto-import during bulk downloads.
-
-## Support
-
-For issues or questions, please [file an issue](https://github.com/calibrain/calibre-web-automated-book-downloader/issues) on GitHub.

compose/docker-compose.lite.yml

@@ -0,0 +1,16 @@
+services:
+  shelfmark-lite:
+    image: ghcr.io/calibrain/shelfmark-lite:latest
+    container_name: shelfmark-lite
+    environment:
+      # EXT_BYPASSER_URL: http://flaresolverr:8191 #If using Flaresolverr
+      PUID: 1000
+      PGID: 1000
+    ports:
+      - 8084:8084
+    restart: unless-stopped
+    volumes:
+      - /path/to/books:/books # Default destination for book downloads
+      - /path/to/config:/config # App configuration
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

compose/docker-compose.tor.yml

@@ -0,0 +1,20 @@
+# Routes all traffic through Tor - requires NET_ADMIN capability
+services:
+  shelfmark-tor:
+    image: ghcr.io/calibrain/shelfmark:latest
+    environment:
+      FLASK_PORT: 8084
+      USING_TOR: true
+      PUID: 1000
+      PGID: 1000
+    cap_add:
+      - NET_ADMIN
+      - NET_RAW
+    ports:
+      - 8084:8084
+    restart: unless-stopped
+    volumes:
+      - /path/to/books:/books # Default destination for book downloads
+      - /path/to/config:/config # App configuration
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

compose/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  shelfmark:
+    image: ghcr.io/calibrain/shelfmark:latest
+    container_name: shelfmark
+    environment:
+      PUID: 1000
+      PGID: 1000
+    ports:
+      - 8084:8084
+    restart: unless-stopped
+    volumes:
+      - /path/to/books:/books # Default destination for book downloads
+      - /path/to/config:/config # App configuration
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

cwa_book_downloader/__init__.py

@@ -1 +0,0 @@
-"""CWA Book Downloader - book search and download service."""

cwa_book_downloader/__main__.py

@@ -1,8 +0,0 @@
-"""Package entry point for `python -m cwa_book_downloader`."""
-
-from cwa_book_downloader.main import app, socketio
-from cwa_book_downloader.config.env import FLASK_HOST, FLASK_PORT
-from cwa_book_downloader.core.config import config
-
-if __name__ == "__main__":
-    socketio.run(app, host=FLASK_HOST, port=FLASK_PORT, debug=config.get("DEBUG", False))

cwa_book_downloader/bypass/__init__.py

@@ -1 +0,0 @@
-"""Cloudflare bypass utilities."""

cwa_book_downloader/bypass/external_bypasser.py

@@ -1,162 +0,0 @@
-"""External Cloudflare bypasser using FlareSolverr."""
-
-from threading import Event
-from typing import Optional, TYPE_CHECKING
-import requests
-import time
-import random
-
-from cwa_book_downloader.core.config import config
-from cwa_book_downloader.core.logger import setup_logger
-
-if TYPE_CHECKING:
-    from cwa_book_downloader.download import network
-
-
-class BypassCancelledException(Exception):
-    """Raised when a bypass operation is cancelled."""
-    pass
-
-logger = setup_logger(__name__)
-
-# Connection timeout (seconds) - how long to wait for external bypasser to accept connection
-CONNECT_TIMEOUT = 10
-# Maximum read timeout cap (seconds) - hard limit regardless of EXT_BYPASSER_TIMEOUT
-MAX_READ_TIMEOUT = 120
-# Buffer added to bypasser's configured timeout (seconds) - accounts for processing overhead
-READ_TIMEOUT_BUFFER = 15
-# Retry settings for bypasser failures
-MAX_RETRY = 5
-BACKOFF_BASE = 1.0
-BACKOFF_CAP = 10.0
-
-
-def _fetch_via_bypasser(target_url: str) -> Optional[str]:
-    """Make a single request to the external bypasser service.
-
-    Args:
-        target_url: The URL to fetch through the bypasser
-
-    Returns:
-        HTML content if successful, None otherwise
-    """
-    bypasser_url = config.get("EXT_BYPASSER_URL", "http://flaresolverr:8191")
-    bypasser_path = config.get("EXT_BYPASSER_PATH", "/v1")
-    bypasser_timeout = config.get("EXT_BYPASSER_TIMEOUT", 60000)
-
-    if not bypasser_url or not bypasser_path:
-        logger.error("External bypasser not configured. Check EXT_BYPASSER_URL and EXT_BYPASSER_PATH.")
-        return None
-
-    bypasser_endpoint = f"{bypasser_url}{bypasser_path}"
-    headers = {"Content-Type": "application/json"}
-    payload = {
-        "cmd": "request.get",
-        "url": target_url,
-        "maxTimeout": bypasser_timeout
-    }
-
-    # Calculate read timeout: bypasser timeout (ms -> s) + buffer, capped at max
-    read_timeout = min((bypasser_timeout / 1000) + READ_TIMEOUT_BUFFER, MAX_READ_TIMEOUT)
-
-    try:
-        response = requests.post(
-            bypasser_endpoint,
-            headers=headers,
-            json=payload,
-            timeout=(CONNECT_TIMEOUT, read_timeout)
-        )
-        response.raise_for_status()
-        result = response.json()
-
-        status = result.get('status', 'unknown')
-        message = result.get('message', '')
-        logger.debug(f"External bypasser response for '{target_url}': {status} - {message}")
-
-        # Check for error status (bypasser returns status="error" with solution=null on failure)
-        if status != 'ok':
-            logger.warning(f"External bypasser failed for '{target_url}': {status} - {message}")
-            return None
-
-        solution = result.get('solution')
-        if not solution:
-            logger.warning(f"External bypasser returned empty solution for '{target_url}'")
-            return None
-
-        html = solution.get('response', '')
-        if not html:
-            logger.warning(f"External bypasser returned empty response for '{target_url}'")
-            return None
-
-        return html
-
-    except requests.exceptions.Timeout:
-        logger.warning(f"External bypasser timed out for '{target_url}' (connect: {CONNECT_TIMEOUT}s, read: {read_timeout:.0f}s)")
-        return None
-    except requests.exceptions.RequestException as e:
-        logger.warning(f"External bypasser request failed for '{target_url}': {e}")
-        return None
-    except (KeyError, TypeError, ValueError) as e:
-        logger.warning(f"External bypasser returned malformed response for '{target_url}': {e}")
-        return None
-
-
-def get_bypassed_page(url: str, selector: Optional["network.AAMirrorSelector"] = None, cancel_flag: Optional[Event] = None) -> Optional[str]:
-    """Fetch HTML content from a URL using an external Cloudflare bypasser service.
-
-    Retries with exponential backoff and mirror/DNS rotation on failure.
-
-    Args:
-        url: Target URL to fetch
-        selector: Mirror selector for AA URL rewriting and rotation
-        cancel_flag: Optional threading Event to signal cancellation
-
-    Returns:
-        HTML content if successful, None otherwise
-
-    Raises:
-        BypassCancelledException: If cancel_flag is set during operation
-    """
-    from cwa_book_downloader.download import network as network_module
-    sel = selector or network_module.AAMirrorSelector()
-
-    for attempt in range(1, MAX_RETRY + 1):
-        # Check for cancellation before each attempt
-        if cancel_flag and cancel_flag.is_set():
-            logger.info("External bypasser cancelled by user")
-            raise BypassCancelledException("Bypass cancelled")
-
-        attempt_url = sel.rewrite(url)
-        result = _fetch_via_bypasser(attempt_url)
-        if result:
-            return result
-
-        if attempt == MAX_RETRY:
-            break
-
-        # Check for cancellation before backoff wait
-        if cancel_flag and cancel_flag.is_set():
-            logger.info("External bypasser cancelled during retry")
-            raise BypassCancelledException("Bypass cancelled")
-
-        # Backoff with jitter before retry, checking cancellation during wait
-        delay = min(BACKOFF_CAP, BACKOFF_BASE * (2 ** (attempt - 1))) + random.random()
-        logger.info(f"External bypasser attempt {attempt}/{MAX_RETRY} failed, retrying in {delay:.1f}s")
-
-        # Check cancellation during delay (check every second)
-        for _ in range(int(delay)):
-            if cancel_flag and cancel_flag.is_set():
-                logger.info("External bypasser cancelled during backoff")
-                raise BypassCancelledException("Bypass cancelled")
-            time.sleep(1)
-        # Sleep remaining fraction
-        remaining = delay - int(delay)
-        if remaining > 0:
-            time.sleep(remaining)
-
-        # Rotate mirror/DNS for next attempt
-        new_base, action = sel.next_mirror_or_rotate_dns()
-        if action in ("mirror", "dns") and new_base:
-            logger.info(f"Rotated {action} for retry")
-
-    return None

cwa_book_downloader/config/env.py

@@ -1,151 +0,0 @@
-"""Environment variable parsing. No local dependencies - import first."""
-
-import os
-import shutil
-from pathlib import Path
-
-
-def string_to_bool(s: str) -> bool:
-    return s.lower() in ["true", "yes", "1", "y"]
-
-
-# Authentication and session settings
-SESSION_COOKIE_SECURE_ENV = os.getenv("SESSION_COOKIE_SECURE", "false")
-
-CWA_DB = os.getenv("CWA_DB_PATH")
-CWA_DB_PATH = Path(CWA_DB) if CWA_DB else None
-CONFIG_DIR = Path(os.getenv("CONFIG_DIR", "/config"))
-LOG_ROOT = Path(os.getenv("LOG_ROOT", "/var/log/"))
-LOG_DIR = LOG_ROOT / "cwa-book-downloader"
-TMP_DIR = Path(os.getenv("TMP_DIR", "/tmp/cwa-book-downloader"))
-INGEST_DIR = Path(os.getenv("INGEST_DIR", "/cwa-book-ingest"))
-INGEST_DIR_BOOK_FICTION = os.getenv("INGEST_DIR_BOOK_FICTION", "")
-INGEST_DIR_BOOK_NON_FICTION = os.getenv("INGEST_DIR_BOOK_NON_FICTION", "")
-INGEST_DIR_BOOK_UNKNOWN = os.getenv("INGEST_DIR_BOOK_UNKNOWN", "")
-INGEST_DIR_MAGAZINE = os.getenv("INGEST_DIR_MAGAZINE", "")
-INGEST_DIR_COMIC_BOOK = os.getenv("INGEST_DIR_COMIC_BOOK", "")
-INGEST_DIR_AUDIOBOOK = os.getenv("INGEST_DIR_AUDIOBOOK", "")
-INGEST_DIR_STANDARDS_DOCUMENT = os.getenv("INGEST_DIR_STANDARDS_DOCUMENT", "")
-INGEST_DIR_MUSICAL_SCORE = os.getenv("INGEST_DIR_MUSICAL_SCORE", "")
-INGEST_DIR_OTHER = os.getenv("INGEST_DIR_OTHER", "")
-DOWNLOAD_PATHS = {
-    "book (fiction)": Path(INGEST_DIR_BOOK_FICTION) if INGEST_DIR_BOOK_FICTION else INGEST_DIR,
-    "book (non-fiction)": Path(INGEST_DIR_BOOK_NON_FICTION) if INGEST_DIR_BOOK_NON_FICTION else INGEST_DIR,
-    "book (unknown)": Path(INGEST_DIR_BOOK_UNKNOWN) if INGEST_DIR_BOOK_UNKNOWN else INGEST_DIR,
-    "magazine": Path(INGEST_DIR_MAGAZINE) if INGEST_DIR_MAGAZINE else INGEST_DIR,
-    "comic book": Path(INGEST_DIR_COMIC_BOOK) if INGEST_DIR_COMIC_BOOK else INGEST_DIR,
-    "audiobook": Path(INGEST_DIR_AUDIOBOOK) if INGEST_DIR_AUDIOBOOK else INGEST_DIR,
-    "standards document": Path(INGEST_DIR_STANDARDS_DOCUMENT) if INGEST_DIR_STANDARDS_DOCUMENT else INGEST_DIR,
-    "musical score": Path(INGEST_DIR_MUSICAL_SCORE) if INGEST_DIR_MUSICAL_SCORE else INGEST_DIR,
-    "other": Path(INGEST_DIR_OTHER) if INGEST_DIR_OTHER else INGEST_DIR,
-}
-
-STATUS_TIMEOUT = int(os.getenv("STATUS_TIMEOUT", "3600"))
-USE_BOOK_TITLE = string_to_bool(os.getenv("USE_BOOK_TITLE", "false"))
-MAX_RETRY = int(os.getenv("MAX_RETRY", "10"))
-DEFAULT_SLEEP = int(os.getenv("DEFAULT_SLEEP", "5"))
-USE_CF_BYPASS = string_to_bool(os.getenv("USE_CF_BYPASS", "true"))
-HTTP_PROXY = os.getenv("HTTP_PROXY", "").strip()
-HTTPS_PROXY = os.getenv("HTTPS_PROXY", "").strip()
-AA_DONATOR_KEY = os.getenv("AA_DONATOR_KEY", "").strip()
-_AA_BASE_URL = os.getenv("AA_BASE_URL", "auto").strip()
-_AA_ADDITIONAL_URLS = os.getenv("AA_ADDITIONAL_URLS", "").strip()
-_SUPPORTED_FORMATS = os.getenv("SUPPORTED_FORMATS", "epub,mobi,azw3,fb2,djvu,cbz,cbr").lower()
-_BOOK_LANGUAGE = os.getenv("BOOK_LANGUAGE", "en").lower()
-_CUSTOM_SCRIPT = os.getenv("CUSTOM_SCRIPT", "").strip()
-FLASK_HOST = os.getenv("FLASK_HOST", "0.0.0.0")
-FLASK_PORT = int(os.getenv("FLASK_PORT", "8084"))
-DEBUG = string_to_bool(os.getenv("DEBUG", "false"))
-# Debug: skip specific download sources for testing fallback chains
-# Comma-separated values: aa-fast, aa-slow-nowait, aa-slow-wait, libgen, zlib, welib
-_DEBUG_SKIP_SOURCES_RAW = os.getenv("DEBUG_SKIP_SOURCES", "").strip().lower()
-DEBUG_SKIP_SOURCES = set(s.strip() for s in _DEBUG_SKIP_SOURCES_RAW.split(",") if s.strip())
-
-# Legacy welib settings - replaced by SOURCE_PRIORITY OrderableListField
-# Kept for migration: if set, used to build initial SOURCE_PRIORITY config
-_LEGACY_PRIORITIZE_WELIB = string_to_bool(os.getenv("PRIORITIZE_WELIB", "false"))
-_LEGACY_ALLOW_USE_WELIB = string_to_bool(os.getenv("ALLOW_USE_WELIB", "true"))
-
-# Version information from Docker build
-BUILD_VERSION = os.getenv("BUILD_VERSION", "N/A")
-RELEASE_VERSION = os.getenv("RELEASE_VERSION", "N/A")
-
-# If debug is true, we want to log everything
-if DEBUG:
-    LOG_LEVEL = "DEBUG"
-else:
-    LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
-ENABLE_LOGGING = string_to_bool(os.getenv("ENABLE_LOGGING", "true"))
-MAIN_LOOP_SLEEP_TIME = int(os.getenv("MAIN_LOOP_SLEEP_TIME", "5"))
-MAX_CONCURRENT_DOWNLOADS = int(os.getenv("MAX_CONCURRENT_DOWNLOADS", "3"))
-DOWNLOAD_PROGRESS_UPDATE_INTERVAL = int(os.getenv("DOWNLOAD_PROGRESS_UPDATE_INTERVAL", "1"))
-DOCKERMODE = string_to_bool(os.getenv("DOCKERMODE", "false"))
-_CUSTOM_DNS = os.getenv("CUSTOM_DNS", "auto").strip()
-USE_DOH = string_to_bool(os.getenv("USE_DOH", "true"))
-BYPASS_RELEASE_INACTIVE_MIN = int(os.getenv("BYPASS_RELEASE_INACTIVE_MIN", "5"))
-BYPASS_WARMUP_ON_CONNECT = string_to_bool(os.getenv("BYPASS_WARMUP_ON_CONNECT", "true"))
-
-# Logging settings
-LOG_FILE = LOG_DIR / "cwa-book-downloader.log"
-
-USING_EXTERNAL_BYPASSER = string_to_bool(os.getenv("USING_EXTERNAL_BYPASSER", "false"))
-if USING_EXTERNAL_BYPASSER:
-    EXT_BYPASSER_URL = os.getenv("EXT_BYPASSER_URL", "http://flaresolverr:8191").strip()
-    EXT_BYPASSER_PATH = os.getenv("EXT_BYPASSER_PATH", "/v1").strip()
-    EXT_BYPASSER_TIMEOUT = int(os.getenv("EXT_BYPASSER_TIMEOUT", "60000"))
-
-USING_TOR = string_to_bool(os.getenv("USING_TOR", "false"))
-# If using Tor, we don't need to set custom DNS, use DOH, or proxy
-if USING_TOR:
-    _CUSTOM_DNS = ""
-    USE_DOH = False
-    HTTP_PROXY = ""
-    HTTPS_PROXY = ""
-
-# Detect Tor variant (has tor binary installed)
-TOR_VARIANT_AVAILABLE = shutil.which("tor") is not None
-
-# Calibre-Web URL for navigation button
-CALIBRE_WEB_URL = os.getenv("CALIBRE_WEB_URL", "").strip()
-
-# Metadata provider settings (Stage 2)
-# Set to "hardcover" or "openlibrary" to enable metadata-first search mode
-METADATA_PROVIDER = os.getenv("METADATA_PROVIDER", "").strip().lower()
-HARDCOVER_API_KEY = os.getenv("HARDCOVER_API_KEY", "").strip()
-
-# Cache TTL settings (in seconds)
-METADATA_CACHE_SEARCH_TTL = int(os.getenv("METADATA_CACHE_SEARCH_TTL", "300"))  # 5 minutes
-METADATA_CACHE_BOOK_TTL = int(os.getenv("METADATA_CACHE_BOOK_TTL", "600"))  # 10 minutes
-
-# Cover image cache settings
-def _is_config_dir_writable() -> bool:
-    """Check if the config directory exists and is writable."""
-    try:
-        if not CONFIG_DIR.exists() or not CONFIG_DIR.is_dir():
-            return False
-        test_file = CONFIG_DIR / ".write_test"
-        test_file.touch()
-        test_file.unlink()
-        return True
-    except (OSError, PermissionError):
-        return False
-
-
-def is_covers_cache_enabled() -> bool:
-    """Check if cover caching is enabled (dynamic, respects settings changes).
-
-    Cache is only enabled if:
-    1. The COVERS_CACHE_ENABLED setting is true
-    2. The config directory is writable
-    """
-    from cwa_book_downloader.core.config import config
-    setting_enabled = config.get("COVERS_CACHE_ENABLED", True)
-    return setting_enabled and _is_config_dir_writable()
-
-
-# Legacy static value - use is_covers_cache_enabled() for dynamic checks
-_COVERS_CACHE_ENABLED_ENV = string_to_bool(os.getenv("COVERS_CACHE_ENABLED", "true"))
-COVERS_CACHE_ENABLED = _COVERS_CACHE_ENABLED_ENV and _is_config_dir_writable()
-COVERS_CACHE_DIR = CONFIG_DIR / "covers"
-COVERS_CACHE_TTL = int(os.getenv("COVERS_CACHE_TTL", "0"))  # 0 = forever (covers are static)
-COVERS_CACHE_MAX_SIZE_MB = int(os.getenv("COVERS_CACHE_MAX_SIZE_MB", "500"))

cwa_book_downloader/config/security.py

@@ -1,152 +0,0 @@
-"""Authentication settings registration."""
-
-from typing import Any, Dict
-
-from werkzeug.security import generate_password_hash
-
-from cwa_book_downloader.core.logger import setup_logger
-from cwa_book_downloader.core.settings_registry import (
-    register_settings,
-    register_on_save,
-    load_config_file,
-    TextField,
-    PasswordField,
-    CheckboxField,
-    ActionButton,
-)
-
-logger = setup_logger(__name__)
-
-
-def _clear_builtin_credentials() -> Dict[str, Any]:
-    """Clear built-in credentials to allow public access."""
-    try:
-        config = load_config_file("security")
-        config.pop("BUILTIN_USERNAME", None)
-        config.pop("BUILTIN_PASSWORD_HASH", None)
-
-        # Save the cleared config
-        from cwa_book_downloader.core.settings_registry import _get_config_file_path, _ensure_config_dir
-        import json
-
-        _ensure_config_dir("security")
-        config_path = _get_config_file_path("security")
-        with open(config_path, 'w') as f:
-            json.dump(config, f, indent=2)
-
-        logger.info("Cleared credentials")
-        return {"success": True, "message": "Credentials cleared. The app is now publicly accessible."}
-
-    except Exception as e:
-        logger.error(f"Failed to clear credentials: {e}")
-        return {"success": False, "message": f"Failed to clear credentials: {str(e)}"}
-
-
-def _on_save_security(values: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Custom save handler for security settings.
-
-    Handles password validation and hashing:
-    - If new password is provided, validate confirmation and hash it
-    - If password fields are empty, preserve existing hash
-    - Never store raw passwords
-
-    Returns:
-        Dict with processed values to save and any validation errors.
-    """
-    password = values.get("BUILTIN_PASSWORD", "")
-    password_confirm = values.get("BUILTIN_PASSWORD_CONFIRM", "")
-
-    # Remove raw password fields - they should never be persisted
-    values.pop("BUILTIN_PASSWORD", None)
-    values.pop("BUILTIN_PASSWORD_CONFIRM", None)
-
-    # If password is provided, validate and hash it
-    if password:
-        if password != password_confirm:
-            return {
-                "error": True,
-                "message": "Passwords do not match",
-                "values": values
-            }
-
-        if len(password) < 4:
-            return {
-                "error": True,
-                "message": "Password must be at least 4 characters",
-                "values": values
-            }
-
-        # Hash the password
-        values["BUILTIN_PASSWORD_HASH"] = generate_password_hash(password)
-        logger.info("Password hash updated")
-
-    # If no password provided but username is being set, preserve existing hash
-    elif "BUILTIN_USERNAME" in values:
-        existing = load_config_file("security")
-        if "BUILTIN_PASSWORD_HASH" in existing:
-            values["BUILTIN_PASSWORD_HASH"] = existing["BUILTIN_PASSWORD_HASH"]
-
-    return {"error": False, "values": values}
-
-
-@register_settings("security", "Security", icon="shield", order=5)
-def security_settings():
-    """Security and authentication settings."""
-    from cwa_book_downloader.config.env import CWA_DB_PATH
-    import os
-
-    cwa_db_available = CWA_DB_PATH and os.path.exists(CWA_DB_PATH)
-
-    fields = [
-        TextField(
-            key="BUILTIN_USERNAME",
-            label="Username",
-            description="Set a username and password to require login. Leave both empty for public access.",
-            placeholder="Enter username",
-            env_supported=False,
-            disabled_when={"field": "USE_CWA_AUTH", "value": True, "reason": "Using Calibre-Web database for authentication."},
-        ),
-        PasswordField(
-            key="BUILTIN_PASSWORD",
-            label="Set Password",
-            description="Fill in to set or change the password.",
-            placeholder="Enter new password",
-            env_supported=False,
-            disabled_when={"field": "USE_CWA_AUTH", "value": True, "reason": "Using Calibre-Web database for authentication."},
-        ),
-        PasswordField(
-            key="BUILTIN_PASSWORD_CONFIRM",
-            label="Confirm Password",
-            placeholder="Confirm new password",
-            env_supported=False,
-            disabled_when={"field": "USE_CWA_AUTH", "value": True, "reason": "Using Calibre-Web database for authentication."},
-        ),
-        ActionButton(
-            key="clear_credentials",
-            label="Clear Credentials",
-            description="Remove login requirement and make the app publicly accessible.",
-            style="danger",
-            callback=_clear_builtin_credentials,
-            disabled_when={"field": "USE_CWA_AUTH", "value": True, "reason": "Using Calibre-Web database for authentication."},
-        ),
-        CheckboxField(
-            key="USE_CWA_AUTH",
-            label="Use Calibre-Web Database",
-            description=(
-                "Authenticate using your existing Calibre-Web users instead of the credentials above."
-                if cwa_db_available
-                else "Authenticate using your existing Calibre-Web users. Set the CWA_DB_PATH environment variable to your Calibre-Web app.db file to enable this option."
-            ),
-            default=False,
-            env_supported=False,
-            disabled=not cwa_db_available,
-            disabled_reason="Set the CWA_DB_PATH environment variable to your Calibre-Web app.db file path to enable this option.",
-        ),
-    ]
-
-    return fields
-
-
-# Register the on_save handler for this tab
-register_on_save("security", _on_save_security)

cwa_book_downloader/config/settings.py

@@ -1,871 +0,0 @@
-"""Core settings registration and derived configuration values."""
-
-import os
-from pathlib import Path
-import json
-
-from cwa_book_downloader.config import env
-from cwa_book_downloader.core.logger import setup_logger
-
-logger = setup_logger(__name__)
-
-# Log configuration values at DEBUG level, filtering out module imports and functions
-logger.debug("Environment configuration:")
-for key, value in env.__dict__.items():
-    # Skip private attributes, modules, types, and callables (functions)
-    if key.startswith('_'):
-        continue
-    if isinstance(value, type) or callable(value):
-        continue
-    # Don't log module objects (they have __name__ attribute)
-    if hasattr(value, '__name__') and hasattr(value, '__file__'):
-        continue
-    # Redact sensitive values
-    if key == "AA_DONATOR_KEY" and isinstance(value, str) and value.strip():
-        value = "REDACTED"
-    if key == "HARDCOVER_API_KEY" and isinstance(value, str) and value.strip():
-        value = "REDACTED"
-    logger.debug(f"  {key}: {value}")
-
-# Load supported book languages from data file
-# Path is relative to the package root, not this file
-_DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
-with open(_DATA_DIR / "book-languages.json") as file:
-    _SUPPORTED_BOOK_LANGUAGE = json.load(file)
-
-# Directory settings
-BASE_DIR = Path(__file__).resolve().parent.parent.parent
-logger.debug(f"BASE_DIR: {BASE_DIR}")
-if env.ENABLE_LOGGING:
-    env.LOG_DIR.mkdir(exist_ok=True)
-
-# Create necessary directories
-env.TMP_DIR.mkdir(exist_ok=True)
-env.INGEST_DIR.mkdir(exist_ok=True)
-
-CROSS_FILE_SYSTEM = os.stat(env.TMP_DIR).st_dev != os.stat(env.INGEST_DIR).st_dev
-logger.debug(f"STAT TMP_DIR: {os.stat(env.TMP_DIR)}")
-logger.debug(f"STAT INGEST_DIR: {os.stat(env.INGEST_DIR)}")
-logger.debug(f"CROSS_FILE_SYSTEM: {CROSS_FILE_SYSTEM}")
-
-# DNS placeholders - actual values set by network.init() from config/ENV
-CUSTOM_DNS: list[str] = []
-DOH_SERVER: str = ""
-
-# Warn about external bypasser DNS limitations
-if env.USING_EXTERNAL_BYPASSER and env.USE_CF_BYPASS:
-    logger.warning(
-        "Using external bypasser (FlareSolverr). Note: FlareSolverr uses its own DNS resolution, "
-        "not this application's custom DNS settings. If you experience DNS-related blocks, "
-        "configure DNS at the Docker/system level for your FlareSolverr container, "
-        "or consider using the internal bypasser which integrates with the app's DNS system."
-    )
-
-# Proxy settings
-PROXIES = {}
-if env.HTTP_PROXY:
-    PROXIES["http"] = env.HTTP_PROXY
-if env.HTTPS_PROXY:
-    PROXIES["https"] = env.HTTPS_PROXY
-logger.debug(f"PROXIES: {PROXIES}")
-
-# Anna's Archive settings
-AA_BASE_URL = env._AA_BASE_URL
-AA_AVAILABLE_URLS = ["https://annas-archive.org", "https://annas-archive.se", "https://annas-archive.li"]
-AA_AVAILABLE_URLS.extend(env._AA_ADDITIONAL_URLS.split(","))
-AA_AVAILABLE_URLS = [url.strip() for url in AA_AVAILABLE_URLS if url.strip()]
-
-# File format settings
-SUPPORTED_FORMATS = env._SUPPORTED_FORMATS.split(",")
-logger.debug(f"SUPPORTED_FORMATS: {SUPPORTED_FORMATS}")
-
-# Complex language processing logic kept in config.py
-BOOK_LANGUAGE = env._BOOK_LANGUAGE.split(',')
-BOOK_LANGUAGE = [l for l in BOOK_LANGUAGE if l in [lang['code'] for lang in _SUPPORTED_BOOK_LANGUAGE]]
-if len(BOOK_LANGUAGE) == 0:
-    BOOK_LANGUAGE = ['en']
-
-# Custom script settings with validation logic
-CUSTOM_SCRIPT = env._CUSTOM_SCRIPT
-if CUSTOM_SCRIPT:
-    if not os.path.exists(CUSTOM_SCRIPT):
-        logger.warn(f"CUSTOM_SCRIPT {CUSTOM_SCRIPT} does not exist")
-        CUSTOM_SCRIPT = ""
-    elif not os.access(CUSTOM_SCRIPT, os.X_OK):
-        logger.warn(f"CUSTOM_SCRIPT {CUSTOM_SCRIPT} is not executable")
-        CUSTOM_SCRIPT = ""
-
-# Debugging settings
-if not env.USING_EXTERNAL_BYPASSER:
-    # Virtual display settings for debugging internal cloudflare bypasser
-    VIRTUAL_SCREEN_SIZE = (1024, 768)
-    RECORDING_DIR = env.LOG_DIR / "recording"
-
-
-from cwa_book_downloader.core.settings_registry import (
-    register_settings,
-    register_group,
-    TextField,
-    PasswordField,
-    NumberField,
-    CheckboxField,
-    SelectField,
-    MultiSelectField,
-    OrderableListField,
-    HeadingField,
-    ActionButton,
-)
-
-
-register_group(
-    "direct_download",
-    "Anna's Archive",
-    icon="download",
-    order=20
-)
-
-register_group(
-    "metadata_providers",
-    "Metadata Providers",
-    icon="book",
-    order=12  # Between Network (10) and Advanced (15)
-)
-
-
-# Anna's Archive sort options (for Direct mode)
-_AA_SORT_OPTIONS = [
-    {"value": "relevance", "label": "Most relevant"},
-    {"value": "newest", "label": "Newest (publication year)"},
-    {"value": "oldest", "label": "Oldest (publication year)"},
-    {"value": "largest", "label": "Largest (filesize)"},
-    {"value": "smallest", "label": "Smallest (filesize)"},
-    {"value": "newest_added", "label": "Newest (open sourced)"},
-    {"value": "oldest_added", "label": "Oldest (open sourced)"},
-]
-
-_FORMAT_OPTIONS = [
-    {"value": "epub", "label": "EPUB"},
-    {"value": "mobi", "label": "MOBI"},
-    {"value": "azw3", "label": "AZW3"},
-    {"value": "pdf", "label": "PDF"},
-    {"value": "fb2", "label": "FB2"},
-    {"value": "djvu", "label": "DJVU"},
-    {"value": "cbz", "label": "CBZ"},
-    {"value": "cbr", "label": "CBR"},
-    {"value": "txt", "label": "TXT"},
-    {"value": "rtf", "label": "RTF"},
-    {"value": "doc", "label": "DOC"},
-    {"value": "docx", "label": "DOCX"},
-    {"value": "zip", "label": "ZIP"},
-    {"value": "rar", "label": "RAR"},
-]
-
-
-def _get_metadata_provider_options():
-    """Build metadata provider options dynamically from enabled providers only."""
-    from cwa_book_downloader.metadata_providers import list_providers, is_provider_enabled
-
-    options = []
-    for provider in list_providers():
-        # Only show providers that are enabled
-        if is_provider_enabled(provider["name"]):
-            options.append({"value": provider["name"], "label": provider["display_name"]})
-
-    # If no providers enabled, show a placeholder option
-    if not options:
-        options = [
-            {"value": "", "label": "No providers enabled"},
-        ]
-
-    return options
-
-
-def _get_release_source_options():
-    """Build release source options dynamically from registered sources."""
-    from cwa_book_downloader.release_sources import list_available_sources
-
-    return [
-        {"value": source["name"], "label": source["display_name"]}
-        for source in list_available_sources()
-    ]
-
-_LANGUAGE_OPTIONS = [{"value": lang["code"], "label": lang["language"]} for lang in _SUPPORTED_BOOK_LANGUAGE]
-
-
-def _clear_covers_cache(current_values: dict) -> dict:
-    """Clear the cover image cache."""
-    try:
-        from cwa_book_downloader.core.image_cache import get_image_cache, reset_image_cache
-
-        cache = get_image_cache()
-        count = cache.clear()
-
-        # Reset the singleton so it reinitializes with fresh state
-        reset_image_cache()
-
-        return {
-            "success": True,
-            "message": f"Cleared {count} cached cover images.",
-        }
-    except Exception as e:
-        logger.error(f"Failed to clear cover cache: {e}")
-        return {
-            "success": False,
-            "message": f"Failed to clear cache: {str(e)}",
-        }
-
-
-def _clear_metadata_cache(current_values: dict) -> dict:
-    """Clear the in-memory metadata cache."""
-    try:
-        from cwa_book_downloader.core.cache import get_metadata_cache
-
-        cache = get_metadata_cache()
-        stats_before = cache.stats()
-        cache.clear()
-
-        return {
-            "success": True,
-            "message": f"Cleared {stats_before['size']} cached entries.",
-        }
-    except Exception as e:
-        logger.error(f"Failed to clear metadata cache: {e}")
-        return {
-            "success": False,
-            "message": f"Failed to clear cache: {str(e)}",
-        }
-
-
-@register_settings("general", "General", icon="settings", order=0)
-def general_settings():
-    """Core application settings."""
-    return [
-        TextField(
-            key="CALIBRE_WEB_URL",
-            label="Book Management App URL",
-            description="Adds a navigation button to your book manager instance (Calibre-Web Automated, Booklore, etc).",
-            placeholder="http://calibre-web:8083",
-        ),
-        HeadingField(
-            key="search_mode_heading",
-            title="Search Mode",
-            description="Direct searches Anna's Archive and downloads immediately. Universal searches book metadata first, letting you choose from multiple release sources including Anna's Archive and Prowlarr.",
-        ),
-        SelectField(
-            key="SEARCH_MODE",
-            label="Search Mode",
-            description="How you want to search for and download books.",
-            options=[
-                {
-                    "value": "direct",
-                    "label": "Direct (Anna's Archive)",
-                    "description": "Search Anna's Archive and download directly. Works out of the box.",
-                },
-                {
-                    "value": "universal",
-                    "label": "Universal",
-                    "description": "Metadata-based search with downloads from all sources.",
-                },
-            ],
-            default="direct",
-        ),
-        SelectField(
-            key="AA_DEFAULT_SORT",
-            label="Default Sort Order",
-            description="Default sort order for Anna's Archive search results.",
-            options=_AA_SORT_OPTIONS,
-            default="relevance",
-            env_supported=False,  # UI-only setting
-            show_when={"field": "SEARCH_MODE", "value": "direct"},
-        ),
-        SelectField(
-            key="METADATA_PROVIDER",
-            label="Metadata Provider",
-            description="Choose which metadata provider to use for book searches.",
-            options=_get_metadata_provider_options,  # Callable - evaluated lazily to avoid circular imports
-            default="openlibrary",
-            show_when={"field": "SEARCH_MODE", "value": "universal"},
-        ),
-        SelectField(
-            key="DEFAULT_RELEASE_SOURCE",
-            label="Default Release Source",
-            description="The release source tab to open by default in the release modal.",
-            options=_get_release_source_options,  # Callable - evaluated lazily to avoid circular imports
-            default="direct_download",
-            env_supported=False,  # UI-only setting, not configurable via ENV
-            show_when={"field": "SEARCH_MODE", "value": "universal"},
-        ),
-        HeadingField(
-            key="search_defaults_heading",
-            title="Default Search Options",
-            description="Default filters applied to searches. Can be overridden using advanced search options.",
-        ),
-        MultiSelectField(
-            key="SUPPORTED_FORMATS",
-            label="Supported Formats",
-            description="Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found.",
-            options=_FORMAT_OPTIONS,
-            default=["epub", "mobi", "azw3", "fb2", "djvu", "cbz", "cbr"],
-        ),
-        MultiSelectField(
-            key="BOOK_LANGUAGE",
-            label="Default Book Languages",
-            description="Default language filter for searches.",
-            options=_LANGUAGE_OPTIONS,
-            default=["en"],
-        ),
-    ]
-
-
-@register_settings("network", "Network", icon="globe", order=10)
-def network_settings():
-    """Network and connectivity settings."""
-    # Check if Tor variant is available and if Tor is currently enabled
-    tor_available = env.TOR_VARIANT_AVAILABLE
-    tor_enabled = env.USING_TOR
-
-    # When Tor is enabled (only possible in Tor variant), DNS/proxy settings are overridden
-    # The Tor variant uses iptables to force ALL traffic through Tor - it cannot be disabled
-    tor_overrides_network = tor_available  # If Tor variant, network settings are always managed by Tor
-
-    return [
-        SelectField(
-            key="CUSTOM_DNS",
-            label="DNS Provider",
-            description=(
-                "Managed by Tor when Tor routing is enabled."
-                if tor_overrides_network
-                else "DNS provider for domain resolution. 'Auto' rotates through providers on failure."
-            ),
-            options=[
-                {"value": "auto", "label": "Auto (Recommended)"},
-                {"value": "system", "label": "System"},
-                {"value": "google", "label": "Google"},
-                {"value": "cloudflare", "label": "Cloudflare"},
-                {"value": "quad9", "label": "Quad9"},
-                {"value": "opendns", "label": "OpenDNS"},
-                {"value": "manual", "label": "Manual"},
-            ],
-            default="auto",
-            disabled=tor_overrides_network,
-            disabled_reason="DNS is managed by Tor when Tor routing is enabled.",
-        ),
-        TextField(
-            key="CUSTOM_DNS_MANUAL",
-            label="Manual DNS Servers",
-            description="Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1).",
-            placeholder="8.8.8.8, 1.1.1.1",
-            disabled=tor_overrides_network,
-            disabled_reason="DNS is managed by Tor when Tor routing is enabled.",
-            show_when={"field": "CUSTOM_DNS", "value": "manual"},
-        ),
-        CheckboxField(
-            key="USE_DOH",
-            label="Use DNS over HTTPS",
-            description=(
-                "Not applicable when Tor routing is enabled."
-                if tor_overrides_network
-                else "Use encrypted DNS queries for improved reliability and privacy."
-            ),
-            default=True,
-            disabled=tor_overrides_network,
-            disabled_reason="DNS over HTTPS is not used when Tor routing is enabled.",
-            # Hide for manual and system (no DoH endpoint available for custom IPs or system DNS)
-            show_when={"field": "CUSTOM_DNS", "value": ["auto", "google", "cloudflare", "quad9", "opendns"]},
-            # Disable for auto (always uses DoH)
-            disabled_when={
-                "field": "CUSTOM_DNS",
-                "value": "auto",
-                "reason": "Auto mode always uses DNS over HTTPS for reliable provider rotation.",
-            },
-        ),
-        CheckboxField(
-            key="USING_TOR",
-            label="Tor Routing",
-            description=(
-                "All traffic is routed through Tor in this container variant. This cannot be changed."
-                if tor_available
-                else "Tor routing is not available in this container variant."
-            ),
-            default=tor_available,  # Reflects actual state: True if Tor variant, False otherwise
-            disabled=True,  # Always disabled - Tor state is determined by container variant
-            disabled_reason=(
-                "Tor routing is always active in the Tor container variant."
-                if tor_available
-                else "Requires the Tor container variant (calibre-web-automated-book-downloader-tor)."
-            ),
-        ),
-        SelectField(
-            key="PROXY_MODE",
-            label="Proxy Mode",
-            description=(
-                "Not applicable when Tor routing is enabled."
-                if tor_overrides_network
-                else "Choose proxy type. SOCKS5 handles all traffic through a single proxy."
-            ),
-            options=[
-                {"value": "none", "label": "None (Direct Connection)"},
-                {"value": "http", "label": "HTTP/HTTPS Proxy"},
-                {"value": "socks5", "label": "SOCKS5 Proxy"},
-            ],
-            default="none",
-            disabled=tor_overrides_network,
-            disabled_reason="Proxy settings are not used when Tor routing is enabled.",
-        ),
-        TextField(
-            key="HTTP_PROXY",
-            label="HTTP Proxy",
-            description="HTTP proxy URL (e.g., http://proxy:8080)",
-            placeholder="http://proxy:8080",
-            disabled=tor_overrides_network,
-            disabled_reason="Proxy settings are not used when Tor routing is enabled.",
-            show_when={"field": "PROXY_MODE", "value": "http"},
-        ),
-        TextField(
-            key="HTTPS_PROXY",
-            label="HTTPS Proxy",
-            description="HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS)",
-            placeholder="http://proxy:8080",
-            disabled=tor_overrides_network,
-            disabled_reason="Proxy settings are not used when Tor routing is enabled.",
-            show_when={"field": "PROXY_MODE", "value": "http"},
-        ),
-        TextField(
-            key="SOCKS5_PROXY",
-            label="SOCKS5 Proxy",
-            description="SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port",
-            placeholder="socks5://localhost:1080",
-            disabled=tor_overrides_network,
-            disabled_reason="Proxy settings are not used when Tor routing is enabled.",
-            show_when={"field": "PROXY_MODE", "value": "socks5"},
-        ),
-    ]
-
-
-@register_settings("downloads", "Downloads", icon="folder", order=5)
-def download_settings():
-    """Configure download behavior and file locations."""
-    return [
-        TextField(
-            key="INGEST_DIR",
-            label="Download Directory",
-            description="Directory where downloaded files are saved.",
-            default="/cwa-book-ingest",
-            required=True,
-        ),
-        CheckboxField(
-            key="USE_BOOK_TITLE",
-            label="Use Book Info as Filename",
-            description="Save files using Author, Title and Year instead of ID. May cause issues with special characters.",
-            default=True,
-        ),
-        CheckboxField(
-            key="AUTO_OPEN_DOWNLOADS_SIDEBAR",
-            label="Auto-Open Downloads Sidebar",
-            description="Automatically open the downloads sidebar when a new download is queued.",
-            default=False,
-            env_supported=False,  # UI-only setting
-        ),
-        CheckboxField(
-            key="DOWNLOAD_TO_BROWSER",
-            label="Download to Browser",
-            description="Automatically download completed files to your browser.",
-            default=False,
-            env_supported=False,  # UI-only setting
-        ),
-        NumberField(
-            key="MAX_CONCURRENT_DOWNLOADS",
-            label="Max Concurrent Downloads",
-            description="Maximum number of simultaneous downloads.",
-            default=3,
-            min_value=1,
-            max_value=10,
-            requires_restart=True,
-        ),
-        NumberField(
-            key="STATUS_TIMEOUT",
-            label="Status Timeout (seconds)",
-            description="How long to keep completed/failed downloads in the queue display.",
-            default=3600,
-            min_value=60,
-            max_value=86400,
-        ),
-        CheckboxField(
-            key="USE_CONTENT_TYPE_DIRECTORIES",
-            label="Configure Content-Type Directories",
-            description="Show options to specify custom directories for each content type (fiction, non-fiction, comics, etc.). If a directory is set, that content type will be saved there instead of the default download directory.",
-            default=False,
-            env_supported=False,  # UI-only toggle to show/hide directory fields
-        ),
-        HeadingField(
-            key="content_type_directories_heading",
-            title="Content-Type Directories",
-            description="Specify custom directories for each content type. Leave empty to use the default download directory.",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_BOOK_FICTION",
-            label="Fiction Books",
-            placeholder="/cwa-book-ingest/fiction",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_BOOK_NON_FICTION",
-            label="Non-Fiction Books",
-            placeholder="/cwa-book-ingest/non-fiction",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_BOOK_UNKNOWN",
-            label="Unknown Books",
-            placeholder="/cwa-book-ingest/unknown",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_MAGAZINE",
-            label="Magazines",
-            placeholder="/cwa-book-ingest/magazines",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_COMIC_BOOK",
-            label="Comic Books",
-            placeholder="/cwa-book-ingest/comics",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_AUDIOBOOK",
-            label="Audiobooks",
-            placeholder="/cwa-book-ingest/audiobooks",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_STANDARDS_DOCUMENT",
-            label="Standards Documents",
-            placeholder="/cwa-book-ingest/standards",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_MUSICAL_SCORE",
-            label="Musical Scores",
-            placeholder="/cwa-book-ingest/scores",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-        TextField(
-            key="INGEST_DIR_OTHER",
-            label="Other",
-            placeholder="/cwa-book-ingest/other",
-            show_when={"field": "USE_CONTENT_TYPE_DIRECTORIES", "value": True},
-        ),
-    ]
-
-
-def _get_source_priority_options():
-    """Build source priority options with dynamic disabled states."""
-    from cwa_book_downloader.core.config import config
-
-    has_donator_key = bool(config.get("AA_DONATOR_KEY", ""))
-    use_cf_bypass = config.get("USE_CF_BYPASS", True)
-    using_external_bypasser = config.get("USING_EXTERNAL_BYPASSER", False)
-    has_internal_bypasser = use_cf_bypass and not using_external_bypasser
-
-    return [
-        {
-            "id": "aa-fast",
-            "label": "Anna's Archive (Fast)",
-            "description": "Fast downloads for donators",
-            "isLocked": not has_donator_key,
-            "disabledReason": "Requires AA Donator Key" if not has_donator_key else None,
-        },
-        {
-            "id": "welib",
-            "label": "Welib",
-            "description": "Alternative mirror with good availability",
-            "isLocked": not has_internal_bypasser,
-            "disabledReason": "Requires internal bypasser" if not has_internal_bypasser else None,
-        },
-        {
-            "id": "aa-slow-nowait",
-            "label": "Anna's Archive (Slowest, No Waitlist)",
-            "description": "Partner servers without countdown",
-        },
-        {
-            "id": "aa-slow-wait",
-            "label": "Anna's Archive (Slow, Waitlist)",
-            "description": "Partner servers with countdown timer",
-        },
-        {
-            "id": "libgen",
-            "label": "Libgen",
-            "description": "Library Genesis mirrors",
-        },
-        {
-            "id": "zlib",
-            "label": "Z-Library",
-            "description": "Z-Library mirrors (requires Cloudflare bypass)",
-            "isLocked": not has_internal_bypasser,
-            "disabledReason": "Requires internal bypasser" if not has_internal_bypasser else None,
-        },
-    ]
-
-
-def _get_default_source_priority():
-    """Default source priority order, respecting legacy env vars.
-
-    ALLOW_USE_WELIB (default true) controls whether welib is enabled.
-    PRIORITIZE_WELIB (default false) controls whether welib is moved to position 1.
-    """
-    from cwa_book_downloader.config.env import _LEGACY_PRIORITIZE_WELIB, _LEGACY_ALLOW_USE_WELIB
-
-    welib_entry = {"id": "welib", "enabled": _LEGACY_ALLOW_USE_WELIB}
-
-    priority = [
-        {"id": "aa-fast", "enabled": True},
-        {"id": "aa-slow-nowait", "enabled": True},
-        {"id": "aa-slow-wait", "enabled": True},
-        {"id": "libgen", "enabled": True},
-    ]
-
-    if _LEGACY_PRIORITIZE_WELIB:
-        priority.insert(1, welib_entry)  # After aa-fast
-    else:
-        priority.append(welib_entry)  # Before zlib
-
-    # Z-Library last - it's quite brittle
-    priority.append({"id": "zlib", "enabled": True})
-
-    return priority
-
-
-@register_settings("download_sources", "Download Sources", icon="download", order=21, group="direct_download")
-def download_source_settings():
-    """Settings for download source behavior."""
-    return [
-        HeadingField(
-            key="source_priority_heading",
-            title="Source Priority",
-            description="Configure which download sources to use and in what order.",
-        ),
-        OrderableListField(
-            key="SOURCE_PRIORITY",
-            label="Download Source Order",
-            description="Drag to reorder. Sources are tried from top to bottom until a download succeeds.",
-            options=_get_source_priority_options,
-            default=_get_default_source_priority(),
-        ),
-        NumberField(
-            key="MAX_RETRY",
-            label="Max Retries",
-            description="Maximum retry attempts for failed downloads.",
-            default=10,
-            min_value=1,
-            max_value=50,
-        ),
-        NumberField(
-            key="DEFAULT_SLEEP",
-            label="Retry Delay (seconds)",
-            description="Wait time between download retry attempts.",
-            default=5,
-            min_value=1,
-            max_value=60,
-        ),
-        HeadingField(
-            key="aa_settings_heading",
-            title="Anna's Archive",
-            description="Configure Anna's Archive mirror and donator settings.",
-        ),
-        SelectField(
-            key="AA_BASE_URL",
-            label="Anna's Archive URL",
-            description="Primary Anna's Archive mirror to use. 'auto' selects automatically.",
-            options=[
-                {"value": "auto", "label": "Auto (Recommended)"},
-                {"value": "https://annas-archive.org", "label": "annas-archive.org"},
-                {"value": "https://annas-archive.se", "label": "annas-archive.se"},
-                {"value": "https://annas-archive.li", "label": "annas-archive.li"},
-            ],
-            default="auto",
-        ),
-        TextField(
-            key="AA_ADDITIONAL_URLS",
-            label="Additional AA Mirrors",
-            description="Comma-separated list of additional Anna's Archive mirror URLs.",
-            placeholder="https://example.com,https://another.com",
-        ),
-        PasswordField(
-            key="AA_DONATOR_KEY",
-            label="Anna's Archive Donator Key",
-            description="Optional donator key for faster downloads from Anna's Archive.",
-        ),
-    ]
-
-
-@register_settings("cloudflare_bypass", "Cloudflare Bypass", icon="shield", order=22, group="direct_download")
-def cloudflare_bypass_settings():
-    """Settings for Cloudflare bypass behavior."""
-    return [
-        CheckboxField(
-            key="USE_CF_BYPASS",
-            label="Enable Cloudflare Bypass",
-            description="Attempt to bypass Cloudflare protection on download sites.",
-            default=True,
-            requires_restart=True,
-        ),
-        CheckboxField(
-            key="BYPASS_WARMUP_ON_CONNECT",
-            label="Warmup on Connect",
-            description="Pre-warm the bypasser when user connects to Web App UI",
-            default=True,
-        ),
-        NumberField(
-            key="BYPASS_RELEASE_INACTIVE_MIN",
-            label="Release Inactive (minutes)",
-            description="Release bypasser resources after this many minutes of inactivity.",
-            default=5,
-            min_value=1,
-            max_value=60,
-        ),
-        CheckboxField(
-            key="USING_EXTERNAL_BYPASSER",
-            label="Use External Bypasser",
-            description="Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser.",
-            default=False,
-            requires_restart=True,
-        ),
-        TextField(
-            key="EXT_BYPASSER_URL",
-            label="External Bypasser URL",
-            description="URL of the external bypasser service (e.g., FlareSolverr).",
-            default="http://flaresolverr:8191",
-            placeholder="http://flaresolverr:8191",
-            requires_restart=True,
-            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": True},
-        ),
-        TextField(
-            key="EXT_BYPASSER_PATH",
-            label="External Bypasser Path",
-            description="API path for the external bypasser.",
-            default="/v1",
-            placeholder="/v1",
-            requires_restart=True,
-            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": True},
-        ),
-        NumberField(
-            key="EXT_BYPASSER_TIMEOUT",
-            label="External Bypasser Timeout (ms)",
-            description="Timeout for external bypasser requests in milliseconds.",
-            default=60000,
-            min_value=10000,
-            max_value=300000,
-            requires_restart=True,
-            show_when={"field": "USING_EXTERNAL_BYPASSER", "value": True},
-        ),
-    ]
-
-
-@register_settings("advanced", "Advanced", icon="cog", order=15)
-def advanced_settings():
-    """Advanced settings for power users."""
-    return [
-        TextField(
-            key="CUSTOM_SCRIPT",
-            label="Custom Script Path",
-            description="Path to a script to run after each successful download. Must be executable.",
-            placeholder="/path/to/script.sh",
-        ),
-        CheckboxField(
-            key="DEBUG",
-            label="Debug Mode",
-            description="Enable verbose logging to console and file. Not recommended for normal use.",
-            default=False,
-            requires_restart=True,
-        ),
-        NumberField(
-            key="MAIN_LOOP_SLEEP_TIME",
-            label="Queue Check Interval (seconds)",
-            description="How often the download queue is checked for new items.",
-            default=5,
-            min_value=1,
-            max_value=60,
-            requires_restart=True,
-        ),
-        NumberField(
-            key="DOWNLOAD_PROGRESS_UPDATE_INTERVAL",
-            label="Progress Update Interval (seconds)",
-            description="How often download progress is broadcast to the UI.",
-            default=1,
-            min_value=1,
-            max_value=10,
-            requires_restart=True,
-        ),
-        HeadingField(
-            key="covers_cache_heading",
-            title="Cover Image Cache",
-            description="Cache book cover images locally for faster loading. Works for both Direct Download and Universal mode.",
-        ),
-        CheckboxField(
-            key="COVERS_CACHE_ENABLED",
-            label="Enable Cover Cache",
-            description="Cache book covers on the server for faster loading.",
-            default=True,
-        ),
-        NumberField(
-            key="COVERS_CACHE_TTL",
-            label="Cache TTL (days)",
-            description="How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork).",
-            default=0,
-            min_value=0,
-            max_value=365,
-        ),
-        NumberField(
-            key="COVERS_CACHE_MAX_SIZE_MB",
-            label="Max Cache Size (MB)",
-            description="Maximum disk space for cached covers. Oldest images are removed when limit is reached.",
-            default=500,
-            min_value=50,
-            max_value=5000,
-        ),
-        ActionButton(
-            key="clear_covers_cache",
-            label="Clear Cover Cache",
-            description="Delete all cached cover images.",
-            style="danger",
-            callback=_clear_covers_cache,
-        ),
-        HeadingField(
-            key="metadata_cache_heading",
-            title="Metadata Cache",
-            description="Cache book metadata from providers (Hardcover, Open Library) to reduce API calls and speed up repeated searches.",
-        ),
-        CheckboxField(
-            key="METADATA_CACHE_ENABLED",
-            label="Enable Metadata Caching",
-            description="When disabled, all metadata searches hit the provider API directly.",
-            default=True,
-        ),
-        NumberField(
-            key="METADATA_CACHE_SEARCH_TTL",
-            label="Search Results Cache (seconds)",
-            description="How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days).",
-            default=300,
-            min_value=60,
-            max_value=604800,
-            show_when={"field": "METADATA_CACHE_ENABLED", "value": True},
-        ),
-        NumberField(
-            key="METADATA_CACHE_BOOK_TTL",
-            label="Book Details Cache (seconds)",
-            description="How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days).",
-            default=600,
-            min_value=60,
-            max_value=604800,
-            show_when={"field": "METADATA_CACHE_ENABLED", "value": True},
-        ),
-        ActionButton(
-            key="clear_metadata_cache",
-            label="Clear Metadata Cache",
-            description="Clear all cached search results and book details.",
-            style="danger",
-            callback=_clear_metadata_cache,
-        ),
-    ]

cwa_book_downloader/core/__init__.py

@@ -1,5 +0,0 @@
-"""Core module - shared models, queue, and utilities."""
-
-from cwa_book_downloader.core.models import BookInfo, QueueItem, SearchFilters, QueueStatus
-from cwa_book_downloader.core.queue import BookQueue, book_queue
-from cwa_book_downloader.core.logger import setup_logger

cwa_book_downloader/core/settings_registry.py

@@ -1,784 +0,0 @@
-"""Plugin settings registry with config file persistence."""
-
-import json
-import os
-from dataclasses import dataclass, field, asdict
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Type, Union
-from threading import Lock
-
-from cwa_book_downloader.core.logger import setup_logger
-
-logger = setup_logger(__name__)
-
-
-@dataclass
-class FieldBase:
-    """Base class for all settings fields."""
-    key: str                              # Environment variable / config key
-    label: str                            # Display label in UI
-    description: str = ""                 # Help text
-    default: Any = None                   # Default value if not set
-    required: bool = False                # Whether field must have a value
-    env_var: Optional[str] = None         # Override env var name (defaults to key)
-    env_supported: bool = True            # Whether this setting can be set via ENV var (False = UI-only)
-    disabled: bool = False                # Whether field is disabled/greyed out
-    disabled_reason: str = ""             # Explanation shown when disabled
-    show_when: Optional[Dict[str, Any]] = None  # Conditional visibility: {"field": "key", "value": "expected"}
-    disabled_when: Optional[Dict[str, Any]] = None  # Conditional disable: {"field": "key", "value": "expected", "reason": "..."}
-    requires_restart: bool = False        # Whether changing this setting requires a container restart
-
-    def get_env_var_name(self) -> str:
-        """Get the environment variable name for this field."""
-        return self.env_var or self.key
-
-    def get_field_type(self) -> str:
-        """Get the field type name for serialization."""
-        return self.__class__.__name__
-
-
-@dataclass
-class TextField(FieldBase):
-    """Single-line text input."""
-    placeholder: str = ""
-    max_length: Optional[int] = None
-
-
-@dataclass
-class PasswordField(FieldBase):
-    """Password input (masked in UI, not returned in API responses)."""
-    placeholder: str = ""
-
-
-@dataclass
-class NumberField(FieldBase):
-    """Numeric input."""
-    min_value: Optional[float] = None
-    max_value: Optional[float] = None
-    step: float = 1
-    default: float = 0
-
-
-@dataclass
-class CheckboxField(FieldBase):
-    """Boolean checkbox."""
-    default: bool = False
-
-
-@dataclass
-class SelectField(FieldBase):
-    """Single-choice dropdown."""
-    # Options can be a list or a callable that returns a list (for lazy evaluation)
-    options: Any = field(default_factory=list)  # [{value: "", label: ""}] or callable
-
-
-@dataclass
-class MultiSelectField(FieldBase):
-    """Multiple-choice selection."""
-    # Options can be a list or a callable that returns a list (for lazy evaluation)
-    options: Any = field(default_factory=list)  # [{value: "", label: ""}] or callable
-    default: List[str] = field(default_factory=list)
-
-
-@dataclass
-class OrderableListField(FieldBase):
-    """
-    Drag-and-drop reorderable list with enable/disable toggles.
-
-    A generic field for any ordered list of items where each item can be
-    enabled or disabled. Used for source priority, format preference, etc.
-
-    Options define the available items:
-        [{"id": "item1", "label": "Item 1", "description": "...",
-          "disabledReason": "...", "isLocked": False}, ...]
-
-    Value is stored as:
-        [{"id": "item1", "enabled": True}, {"id": "item2", "enabled": False}, ...]
-    """
-    # Options can be a list or a callable that returns a list (for lazy evaluation)
-    # Each option: {id, label, description?, disabledReason?, isLocked?}
-    options: Any = field(default_factory=list)
-    # Default value: [{id, enabled}, ...] in priority order
-    default: List[Dict[str, Any]] = field(default_factory=list)
-
-
-@dataclass
-class ActionButton:
-    """
-    Button that triggers a callback function.
-
-    Used for actions like "Test Connection" that execute code
-    and return success/error status.
-    """
-    key: str                              # Action identifier
-    label: str                            # Button text
-    description: str = ""                 # Help text
-    style: str = "default"                # "default", "primary", "danger"
-    callback: Optional[Callable[[], Dict[str, Any]]] = None  # Returns {"success": bool, "message": str}
-    disabled: bool = False                # Whether button is disabled/greyed out
-    disabled_reason: str = ""             # Explanation shown when disabled
-    show_when: Optional[Dict[str, Any]] = None  # Conditional visibility: {"field": "key", "value": "expected"}
-    disabled_when: Optional[Dict[str, Any]] = None  # Conditional disable: {"field": "key", "value": "expected", "reason": "..."}
-
-    def get_field_type(self) -> str:
-        return "ActionButton"
-
-
-@dataclass
-class HeadingField:
-    """
-    Display-only heading with title and description.
-
-    Used to add section titles and descriptive text to settings pages.
-    Not an input field - purely for display.
-    """
-    key: str                              # Unique identifier
-    title: str                            # Heading title
-    description: str = ""                 # Description text (supports markdown-style links)
-    link_url: str = ""                    # Optional URL for a link
-    link_text: str = ""                   # Text for the link (defaults to URL if not provided)
-    show_when: Optional[Dict[str, Any]] = None  # Conditional visibility: {"field": "key", "value": "expected"}
-
-    def get_field_type(self) -> str:
-        return "HeadingField"
-
-
-# Type alias for all field types
-SettingsField = Union[TextField, PasswordField, NumberField, CheckboxField, SelectField, MultiSelectField, OrderableListField, ActionButton, HeadingField]
-
-
-@dataclass
-class SettingsTab:
-    """A tab/section in the settings UI."""
-    name: str                             # Internal name (used in URLs)
-    display_name: str                     # Display name in UI
-    fields: List[SettingsField] = field(default_factory=list)
-    icon: Optional[str] = None            # Icon name for UI
-    order: int = 100                      # Sort order (lower = earlier)
-    group: Optional[str] = None           # Group name this tab belongs to
-
-
-@dataclass
-class SettingsGroup:
-    """A collapsible group of settings tabs in the UI."""
-    name: str                             # Internal name
-    display_name: str                     # Display name in UI
-    icon: Optional[str] = None            # Icon name for UI
-    order: int = 100                      # Sort order (lower = earlier)
-
-
-_SETTINGS_REGISTRY: Dict[str, SettingsTab] = {}
-_GROUPS_REGISTRY: Dict[str, SettingsGroup] = {}
-_ON_SAVE_HANDLERS: Dict[str, Callable[[Dict[str, Any]], Dict[str, Any]]] = {}
-_REGISTRY_LOCK = Lock()
-
-
-def register_group(
-    name: str,
-    display_name: str,
-    icon: Optional[str] = None,
-    order: int = 100
-) -> None:
-    """
-    Register a settings group.
-
-    Groups are collapsible containers for related settings tabs.
-
-    Args:
-        name: Internal name for the group (e.g., "direct_download")
-        display_name: Display name in UI (e.g., "Direct Download")
-        icon: Optional icon name for the UI
-        order: Sort order (lower numbers appear first)
-
-    Example:
-        register_group("direct_download", "Direct Download", icon="download", order=20)
-    """
-    with _REGISTRY_LOCK:
-        group = SettingsGroup(
-            name=name,
-            display_name=display_name,
-            icon=icon,
-            order=order,
-        )
-        _GROUPS_REGISTRY[name] = group
-        logger.debug(f"Registered settings group: {name}")
-
-
-def register_settings(
-    name: str,
-    display_name: str,
-    icon: Optional[str] = None,
-    order: int = 100,
-    group: Optional[str] = None
-):
-    """
-    Decorator to register settings for a plugin/module.
-
-    The decorated function should return a list of SettingsField objects.
-
-    Args:
-        name: Internal name for the settings tab (e.g., "hardcover")
-        display_name: Display name in UI (e.g., "Hardcover")
-        icon: Optional icon name for the UI
-        order: Sort order (lower numbers appear first)
-        group: Optional group name this tab belongs to
-
-    Example:
-        @register_settings("hardcover", "Hardcover", icon="book", order=20, group="metadata_providers")
-        def hardcover_settings():
-            return [
-                PasswordField(key="HARDCOVER_API_KEY", label="API Key", required=True),
-            ]
-    """
-    def decorator(func: Callable[[], List[SettingsField]]):
-        with _REGISTRY_LOCK:
-            fields = func()
-            tab = SettingsTab(
-                name=name,
-                display_name=display_name,
-                fields=fields,
-                icon=icon,
-                order=order,
-                group=group,
-            )
-            _SETTINGS_REGISTRY[name] = tab
-            logger.debug(f"Registered settings tab: {name} ({len(fields)} fields)" +
-                        (f" in group {group}" if group else ""))
-        return func
-    return decorator
-
-
-def register_on_save(
-    tab_name: str,
-    handler: Callable[[Dict[str, Any]], Dict[str, Any]]
-) -> None:
-    """
-    Register a custom on_save handler for a settings tab.
-
-    The handler is called before saving settings and can:
-    - Validate values (return {"error": True, "message": "..."})
-    - Transform values (e.g., hash passwords)
-    - Add computed values
-
-    Args:
-        tab_name: The settings tab name to register the handler for.
-        handler: Callable that takes values dict and returns:
-                 {"error": bool, "message": str (if error), "values": dict}
-
-    Example:
-        def _on_save_security(values: Dict[str, Any]) -> Dict[str, Any]:
-            password = values.pop("password", "")
-            if password:
-                values["password_hash"] = hash_password(password)
-            return {"error": False, "values": values}
-
-        register_on_save("security", _on_save_security)
-    """
-    with _REGISTRY_LOCK:
-        _ON_SAVE_HANDLERS[tab_name] = handler
-        logger.debug(f"Registered on_save handler for tab: {tab_name}")
-
-
-def get_on_save_handler(tab_name: str) -> Optional[Callable[[Dict[str, Any]], Dict[str, Any]]]:
-    """Get the on_save handler for a settings tab, if any."""
-    return _ON_SAVE_HANDLERS.get(tab_name)
-
-
-def get_settings_tab(name: str) -> Optional[SettingsTab]:
-    """Get a specific settings tab by name."""
-    return _SETTINGS_REGISTRY.get(name)
-
-
-def get_all_settings_tabs() -> List[SettingsTab]:
-    """Get all registered settings tabs, sorted by order."""
-    return sorted(_SETTINGS_REGISTRY.values(), key=lambda t: (t.order, t.name))
-
-
-def list_registered_settings() -> List[str]:
-    """List all registered settings tab names."""
-    return list(_SETTINGS_REGISTRY.keys())
-
-
-def _get_config_dir() -> Path:
-    """Get the config directory path."""
-    from cwa_book_downloader.config.env import CONFIG_DIR
-    return Path(CONFIG_DIR)
-
-
-def _get_config_file_path(tab_name: str) -> Path:
-    """Get the config file path for a settings tab."""
-    config_dir = _get_config_dir()
-    if tab_name == "general":
-        return config_dir / "settings.json"
-    else:
-        plugins_dir = config_dir / "plugins"
-        return plugins_dir / f"{tab_name}.json"
-
-
-def _ensure_config_dir(tab_name: str) -> None:
-    """Ensure the config directory exists."""
-    config_path = _get_config_file_path(tab_name)
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-
-
-def load_config_file(tab_name: str) -> Dict[str, Any]:
-    """
-    Load settings from a config file.
-
-    Args:
-        tab_name: The settings tab name.
-
-    Returns:
-        Dict of setting key -> value from config file.
-    """
-    config_path = _get_config_file_path(tab_name)
-
-    if not config_path.exists():
-        return {}
-
-    try:
-        with open(config_path, 'r') as f:
-            return json.load(f)
-    except json.JSONDecodeError as e:
-        logger.error(f"Invalid JSON in config file {config_path}: {e}")
-        return {}
-
-
-def save_config_file(tab_name: str, values: Dict[str, Any]) -> bool:
-    """
-    Save settings to a config file.
-
-    Args:
-        tab_name: The settings tab name.
-        values: Dict of setting key -> value to save.
-
-    Returns:
-        True if save succeeded, False otherwise.
-    """
-    try:
-        _ensure_config_dir(tab_name)
-        config_path = _get_config_file_path(tab_name)
-
-        # Load existing config and merge
-        existing = load_config_file(tab_name)
-        existing.update(values)
-
-        with open(config_path, 'w') as f:
-            json.dump(existing, f, indent=2)
-
-        logger.info(f"Saved settings to {config_path}")
-        return True
-    except Exception as e:
-        logger.error(f"Error saving config file for {tab_name}: {e}")
-        return False
-
-
-def sync_env_to_config() -> None:
-    """
-    Sync environment variable values to config files.
-
-    This ensures that when ENV vars are set, their values are persisted to config.
-    When ENV vars are later removed, the config file retains the last known values.
-
-    Called once during application startup.
-    """
-    for tab in get_all_settings_tabs():
-        values_to_sync = {}
-
-        for field in tab.fields:
-            # Skip non-value fields
-            if isinstance(field, (ActionButton, HeadingField)):
-                continue
-
-            # Skip fields that don't support ENV vars
-            if not getattr(field, 'env_supported', True):
-                continue
-
-            # Check if ENV var is set
-            env_var_name = field.get_env_var_name()
-            env_value = os.environ.get(env_var_name)
-
-            if env_value is not None:
-                # Parse the ENV value to the appropriate type
-                parsed_value = _parse_env_value(env_value, field)
-                values_to_sync[field.key] = parsed_value
-
-        # Save synced values to config file (merge with existing)
-        if values_to_sync:
-            save_config_file(tab.name, values_to_sync)
-            logger.debug(f"Synced {len(values_to_sync)} ENV values to {tab.name} config: {list(values_to_sync.keys())}")
-
-
-def get_setting_value(field: SettingsField, tab_name: str) -> Any:
-    """
-    Get the current value for a settings field.
-
-    Priority: env var > config file > default
-
-    Args:
-        field: The settings field.
-        tab_name: The settings tab name (for config file lookup).
-
-    Returns:
-        The resolved value.
-    """
-    if isinstance(field, (ActionButton, HeadingField)):
-        return None  # Actions and headings don't have values
-
-    # 1. Check environment variable (if supported for this field)
-    if field.env_supported:
-        env_var_name = field.get_env_var_name()
-        env_value = os.environ.get(env_var_name)
-        if env_value is not None:
-            return _parse_env_value(env_value, field)
-
-    # 2. Check config file
-    config = load_config_file(tab_name)
-    if field.key in config:
-        return config[field.key]
-
-    # 3. Return default
-    return field.default
-
-
-def _parse_env_value(value: str, field: SettingsField) -> Any:
-    """Parse an environment variable value to the appropriate type."""
-    if isinstance(field, CheckboxField):
-        return value.lower() in ('true', '1', 'yes', 'on')
-    elif isinstance(field, NumberField):
-        try:
-            if '.' in value:
-                return float(value)
-            return int(value)
-        except ValueError:
-            return field.default
-    elif isinstance(field, MultiSelectField):
-        return [v.strip() for v in value.split(',') if v.strip()]
-    elif isinstance(field, OrderableListField):
-        # Parse JSON array: [{"id": "...", "enabled": true}, ...]
-        try:
-            return json.loads(value)
-        except json.JSONDecodeError:
-            logger.warning(f"Invalid JSON for {field.key}, using default")
-            return field.default
-    else:
-        return value
-
-
-def is_value_from_env(field: SettingsField) -> bool:
-    """Check if a field's value comes from an environment variable."""
-    if isinstance(field, (ActionButton, HeadingField)):
-        return False
-    # UI-only settings never come from ENV (env_supported=False)
-    # Default to True for backwards compatibility
-    env_supported = getattr(field, 'env_supported', True)
-    if env_supported is False:
-        return False
-    env_var_name = field.get_env_var_name()
-    return env_var_name in os.environ
-
-
-def serialize_field(field: SettingsField, tab_name: str, include_value: bool = True) -> Dict[str, Any]:
-    """
-    Serialize a field for API response.
-
-    Args:
-        field: The settings field.
-        tab_name: The settings tab name.
-        include_value: Whether to include the current value.
-
-    Returns:
-        Dict representation of the field.
-    """
-    # HeadingField has a different structure - handle separately
-    if isinstance(field, HeadingField):
-        result = {
-            "key": field.key,
-            "type": field.get_field_type(),
-            "title": field.title,
-            "description": field.description,
-        }
-        if field.link_url:
-            result["linkUrl"] = field.link_url
-            result["linkText"] = field.link_text or field.link_url
-        if field.show_when:
-            result["showWhen"] = field.show_when
-        return result
-
-    result = {
-        "key": field.key,
-        "label": field.label,
-        "type": field.get_field_type(),
-        "description": getattr(field, 'description', ''),
-        "required": getattr(field, 'required', False),
-        "disabled": getattr(field, 'disabled', False),
-        "disabledReason": getattr(field, 'disabled_reason', ''),
-        "requiresRestart": getattr(field, 'requires_restart', False),
-    }
-
-    # Add conditional visibility if specified
-    show_when = getattr(field, 'show_when', None)
-    if show_when:
-        result["showWhen"] = show_when
-
-    # Add conditional disable if specified
-    disabled_when = getattr(field, 'disabled_when', None)
-    if disabled_when:
-        result["disabledWhen"] = disabled_when
-
-    # Add type-specific properties
-    if isinstance(field, TextField):
-        result["placeholder"] = field.placeholder
-        if field.max_length:
-            result["maxLength"] = field.max_length
-    elif isinstance(field, PasswordField):
-        result["placeholder"] = field.placeholder
-    elif isinstance(field, NumberField):
-        result["min"] = field.min_value
-        result["max"] = field.max_value
-        result["step"] = field.step
-    elif isinstance(field, (SelectField, MultiSelectField)):
-        # Support callable options for lazy evaluation (avoids circular imports)
-        options = field.options() if callable(field.options) else field.options
-        result["options"] = options
-    elif isinstance(field, OrderableListField):
-        # Support callable options for lazy evaluation (avoids circular imports)
-        options = field.options() if callable(field.options) else field.options
-        result["options"] = options
-    elif isinstance(field, ActionButton):
-        result["style"] = field.style
-        result["description"] = field.description
-
-    if include_value and not isinstance(field, (ActionButton, HeadingField)):
-        value = get_setting_value(field, tab_name)
-        result["value"] = value if value is not None else ""
-        result["fromEnv"] = is_value_from_env(field)
-
-    return result
-
-
-def serialize_tab(tab: SettingsTab, include_values: bool = True) -> Dict[str, Any]:
-    """Serialize a settings tab for API response."""
-    return {
-        "name": tab.name,
-        "displayName": tab.display_name,
-        "icon": tab.icon,
-        "order": tab.order,
-        "group": tab.group,
-        "fields": [serialize_field(f, tab.name, include_values) for f in tab.fields],
-    }
-
-
-def serialize_group(group: SettingsGroup) -> Dict[str, Any]:
-    """Serialize a settings group for API response."""
-    return {
-        "name": group.name,
-        "displayName": group.display_name,
-        "icon": group.icon,
-        "order": group.order,
-    }
-
-
-def get_all_groups() -> List[SettingsGroup]:
-    """Get all registered settings groups, sorted by order."""
-    return sorted(_GROUPS_REGISTRY.values(), key=lambda g: (g.order, g.name))
-
-
-def serialize_all_settings(include_values: bool = True) -> Dict[str, Any]:
-    """Serialize all settings for API response."""
-    tabs = get_all_settings_tabs()
-    groups = get_all_groups()
-    return {
-        "tabs": [serialize_tab(t, include_values) for t in tabs],
-        "groups": [serialize_group(g) for g in groups],
-    }
-
-
-def execute_action(tab_name: str, action_key: str, current_values: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-    """
-    Execute an action button's callback.
-
-    Args:
-        tab_name: The settings tab name.
-        action_key: The action key to execute.
-        current_values: Optional dict of current form values (unsaved).
-                       Passed to callbacks that accept it.
-
-    Returns:
-        Dict with "success" (bool) and "message" (str).
-    """
-    import inspect
-
-    tab = get_settings_tab(tab_name)
-    if not tab:
-        return {"success": False, "message": f"Unknown settings tab: {tab_name}"}
-
-    for field in tab.fields:
-        if isinstance(field, ActionButton) and field.key == action_key:
-            if field.callback:
-                try:
-                    # Check if callback accepts current_values parameter
-                    sig = inspect.signature(field.callback)
-                    if 'current_values' in sig.parameters:
-                        return field.callback(current_values=current_values or {})
-                    else:
-                        return field.callback()
-                except Exception as e:
-                    logger.error(f"Action {action_key} failed: {e}")
-                    return {"success": False, "message": str(e)}
-            else:
-                return {"success": False, "message": "Action has no callback defined"}
-
-    return {"success": False, "message": f"Unknown action: {action_key}"}
-
-
-def _sync_metadata_provider_selection() -> None:
-    """
-    Sync the METADATA_PROVIDER setting based on enabled providers.
-
-    Called after saving metadata provider settings to auto-select
-    the first enabled provider if the current selection is invalid.
-    """
-    try:
-        from cwa_book_downloader.metadata_providers import sync_metadata_provider_selection
-        sync_metadata_provider_selection()
-    except ImportError:
-        pass  # Metadata providers module not available
-
-
-def _apply_dns_settings(config) -> None:
-    """
-    Apply DNS settings changes to the network module.
-
-    This ensures DNS changes take effect immediately without requiring
-    a container restart.
-    """
-    try:
-        from cwa_book_downloader.download import network
-
-        provider = config.get("CUSTOM_DNS", "auto")
-        use_doh = config.get("USE_DOH", False)
-        manual_servers = None
-
-        if provider == "manual":
-            manual_dns = config.get("CUSTOM_DNS_MANUAL", "")
-            if manual_dns:
-                # Parse comma-separated server list
-                manual_servers = [s.strip() for s in manual_dns.split(",") if s.strip()]
-
-        network.set_dns_provider(provider, manual_servers, use_doh=use_doh)
-    except ImportError:
-        pass  # Network module not available
-    except Exception as e:
-        logger.warning(f"Failed to apply DNS settings: {e}")
-
-
-def update_settings(tab_name: str, values: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Update settings for a tab.
-
-    Only updates values that are not set via environment variables.
-
-    Args:
-        tab_name: The settings tab name.
-        values: Dict of key -> value to update.
-
-    Returns:
-        Dict with "success" (bool), "message" (str), "updated" (list of keys),
-        and "requiresRestart" (bool) indicating if any changed setting requires restart.
-    """
-    tab = get_settings_tab(tab_name)
-    if not tab:
-        return {"success": False, "message": f"Unknown settings tab: {tab_name}", "updated": [], "requiresRestart": False}
-
-    # Build a map of field keys to fields (exclude non-value fields)
-    field_map = {f.key: f for f in tab.fields if not isinstance(f, (ActionButton, HeadingField))}
-
-    # Filter out values that are set via env vars or unknown
-    values_to_save = {}
-    skipped_env = []
-    skipped_unknown = []
-    restart_required_keys = []
-
-    for key, value in values.items():
-        if key not in field_map:
-            skipped_unknown.append(key)
-            continue
-
-        field = field_map[key]
-        if is_value_from_env(field):
-            skipped_env.append(key)
-            continue
-
-        # Handle password fields - only update if a new value is provided
-        if isinstance(field, PasswordField) and not value:
-            continue
-
-        values_to_save[key] = value
-
-        # Track if this field requires restart
-        if getattr(field, 'requires_restart', False):
-            restart_required_keys.append(key)
-
-    if not values_to_save:
-        message = "No settings to update"
-        if skipped_env:
-            message += f". Skipped (set via env): {', '.join(skipped_env)}"
-        return {"success": True, "message": message, "updated": [], "requiresRestart": False}
-
-    # Call on_save handler if registered (for custom validation/transformation)
-    on_save_handler = get_on_save_handler(tab_name)
-    if on_save_handler:
-        try:
-            result = on_save_handler(values_to_save.copy())
-            if result.get("error"):
-                return {
-                    "success": False,
-                    "message": result.get("message", "Validation failed"),
-                    "updated": [],
-                    "requiresRestart": False
-                }
-            # Use the transformed values
-            values_to_save = result.get("values", values_to_save)
-        except Exception as e:
-            logger.error(f"on_save handler for {tab_name} failed: {e}")
-            return {
-                "success": False,
-                "message": f"Save handler error: {str(e)}",
-                "updated": [],
-                "requiresRestart": False
-            }
-
-    # Save to config file
-    if save_config_file(tab_name, values_to_save):
-        # Refresh the config singleton so live settings take effect immediately
-        try:
-            from cwa_book_downloader.core.config import config
-            config.refresh()
-        except ImportError:
-            pass  # Config module not yet available during initial setup
-
-        # Apply DNS settings changes live (network tab)
-        dns_keys = {"CUSTOM_DNS", "CUSTOM_DNS_MANUAL", "USE_DOH"}
-        if tab_name == "network" and dns_keys.intersection(values_to_save.keys()):
-            _apply_dns_settings(config)
-
-        # Sync metadata provider selection when a provider's enabled state changes
-        tab = get_settings_tab(tab_name)
-        if tab and tab.group == "metadata_providers":
-            _sync_metadata_provider_selection()
-
-        message = f"Updated {len(values_to_save)} setting(s)"
-        if skipped_env:
-            message += f". Skipped (set via env): {', '.join(skipped_env)}"
-
-        requires_restart = len(restart_required_keys) > 0
-        return {
-            "success": True,
-            "message": message,
-            "updated": list(values_to_save.keys()),
-            "requiresRestart": requires_restart,
-            "restartRequiredFor": restart_required_keys,
-        }
-    else:
-        return {"success": False, "message": "Failed to save settings", "updated": [], "requiresRestart": False}

cwa_book_downloader/download/archive.py

@@ -1,354 +0,0 @@
-"""Archive extraction utilities for downloaded book archives."""
-
-import os
-import shutil
-import zipfile
-from dataclasses import dataclass
-from pathlib import Path
-from typing import List, Optional, Tuple
-
-from cwa_book_downloader.core.logger import setup_logger
-
-logger = setup_logger(__name__)
-
-# Check for rarfile availability at module load
-try:
-    import rarfile
-
-    RAR_AVAILABLE = True
-except ImportError:
-    RAR_AVAILABLE = False
-    logger.warning("rarfile not installed - RAR extraction disabled")
-
-# Book file extensions that should be kept after extraction
-BOOK_EXTENSIONS = frozenset({
-    "epub", "mobi", "azw", "azw3", "pdf", "fb2", "djvu",
-    "cbz", "cbr", "txt", "rtf", "doc", "docx", "lit", "pdb",
-})
-
-
-class ArchiveExtractionError(Exception):
-    """Raised when archive extraction fails."""
-
-    pass
-
-
-class PasswordProtectedError(ArchiveExtractionError):
-    """Raised when archive requires a password."""
-
-    pass
-
-
-class CorruptedArchiveError(ArchiveExtractionError):
-    """Raised when archive is corrupted."""
-
-    pass
-
-
-def is_archive(file_path: Path) -> bool:
-    """Check if file is a supported archive format."""
-    suffix = file_path.suffix.lower().lstrip(".")
-    return suffix in ("zip", "rar")
-
-
-def _is_book_file(file_path: Path) -> bool:
-    """Check if file is a recognized book format."""
-    ext = file_path.suffix.lower().lstrip(".")
-    return ext in BOOK_EXTENSIONS
-
-
-def _filter_book_files(extracted_files: List[Path]) -> Tuple[List[Path], List[Path]]:
-    """
-    Filter extracted files to only book formats.
-
-    Returns:
-        Tuple of (book_files, non_book_files)
-    """
-    book_files = []
-    non_book_files = []
-
-    for file_path in extracted_files:
-        if _is_book_file(file_path):
-            book_files.append(file_path)
-        else:
-            non_book_files.append(file_path)
-
-    return book_files, non_book_files
-
-
-def extract_archive(
-    archive_path: Path,
-    output_dir: Path,
-) -> Tuple[List[Path], List[str]]:
-    """
-    Extract book files from an archive.
-
-    Extracts all files, then filters to only keep recognized book formats.
-    Non-book files (HTML, images, etc.) are deleted.
-
-    Args:
-        archive_path: Path to the archive file
-        output_dir: Directory to extract files to
-
-    Returns:
-        Tuple of (extracted_book_file_paths, warnings)
-
-    Raises:
-        ArchiveExtractionError: If extraction fails
-        PasswordProtectedError: If archive requires password
-        CorruptedArchiveError: If archive is corrupted
-    """
-    suffix = archive_path.suffix.lower().lstrip(".")
-
-    if suffix == "zip":
-        extracted_files, warnings = _extract_zip(archive_path, output_dir)
-    elif suffix == "rar":
-        extracted_files, warnings = _extract_rar(archive_path, output_dir)
-    else:
-        raise ArchiveExtractionError(f"Unsupported archive format: {suffix}")
-
-    # Filter to only book files, delete non-book files
-    book_files, non_book_files = _filter_book_files(extracted_files)
-
-    for non_book_file in non_book_files:
-        try:
-            non_book_file.unlink()
-            logger.debug(f"Deleted non-book file: {non_book_file.name}")
-        except OSError as e:
-            logger.warning(f"Failed to delete non-book file {non_book_file}: {e}")
-
-    if non_book_files:
-        warnings.append(f"Skipped {len(non_book_files)} non-book file(s)")
-
-    return book_files, warnings
-
-
-def _extract_zip(
-    archive_path: Path,
-    output_dir: Path,
-) -> Tuple[List[Path], List[str]]:
-    """Extract files from a ZIP archive."""
-    extracted_files = []
-    warnings = []
-
-    try:
-        with zipfile.ZipFile(archive_path, "r") as zf:
-            # Check for password protection
-            for info in zf.infolist():
-                if info.flag_bits & 0x1:  # Encrypted flag
-                    raise PasswordProtectedError("ZIP archive is password protected")
-
-            # Test archive integrity
-            bad_file = zf.testzip()
-            if bad_file:
-                raise CorruptedArchiveError(f"Corrupted file in archive: {bad_file}")
-
-            # Extract all files
-            for info in zf.infolist():
-                if info.is_dir():
-                    continue
-
-                # Use only filename, strip directory path (security: prevent path traversal)
-                filename = Path(info.filename).name
-                if not filename:
-                    continue
-
-                # Extract to output_dir with flat structure
-                target_path = output_dir / filename
-                target_path = _handle_duplicate_filename(target_path)
-
-                with zf.open(info) as src, open(target_path, "wb") as dst:
-                    dst.write(src.read())
-
-                extracted_files.append(target_path)
-                logger.debug(f"Extracted: {filename}")
-
-    except zipfile.BadZipFile as e:
-        raise CorruptedArchiveError(f"Invalid or corrupted ZIP: {e}")
-    except PermissionError as e:
-        raise ArchiveExtractionError(f"Permission denied: {e}")
-
-    return extracted_files, warnings
-
-
-def _extract_rar(
-    archive_path: Path,
-    output_dir: Path,
-) -> Tuple[List[Path], List[str]]:
-    """Extract files from a RAR archive."""
-    if not RAR_AVAILABLE:
-        raise ArchiveExtractionError("RAR extraction not available - rarfile library not installed")
-
-    extracted_files = []
-    warnings = []
-
-    try:
-        with rarfile.RarFile(archive_path, "r") as rf:
-            # Check for password protection
-            if rf.needs_password():
-                raise PasswordProtectedError("RAR archive is password protected")
-
-            # Test archive integrity
-            rf.testrar()
-
-            # Extract all files
-            for info in rf.infolist():
-                if info.is_dir():
-                    continue
-
-                # Use only filename, strip directory path (security: prevent path traversal)
-                filename = Path(info.filename).name
-                if not filename:
-                    continue
-
-                # Extract to output_dir with flat structure
-                target_path = output_dir / filename
-                target_path = _handle_duplicate_filename(target_path)
-
-                with rf.open(info) as src, open(target_path, "wb") as dst:
-                    dst.write(src.read())
-
-                extracted_files.append(target_path)
-                logger.debug(f"Extracted: {filename}")
-
-    except rarfile.BadRarFile as e:
-        raise CorruptedArchiveError(f"Invalid or corrupted RAR: {e}")
-    except rarfile.RarCannotExec:
-        raise ArchiveExtractionError("unrar binary not found - install unrar package")
-    except PermissionError as e:
-        raise ArchiveExtractionError(f"Permission denied: {e}")
-
-    return extracted_files, warnings
-
-
-def _handle_duplicate_filename(target_path: Path) -> Path:
-    """Handle duplicate filenames by appending counter."""
-    if not target_path.exists():
-        return target_path
-
-    base = target_path.stem
-    ext = target_path.suffix
-    parent = target_path.parent
-    counter = 1
-
-    while target_path.exists():
-        target_path = parent / f"{base}_{counter}{ext}"
-        counter += 1
-
-    return target_path
-
-
-@dataclass
-class ArchiveResult:
-    """Result of archive processing."""
-
-    success: bool
-    final_paths: List[Path]
-    message: str
-    error: Optional[str] = None
-
-
-def process_archive(
-    archive_path: Path,
-    temp_dir: Path,
-    ingest_dir: Path,
-    archive_id: str,
-) -> ArchiveResult:
-    """
-    Process an archive file: extract, filter to book files, move to ingest.
-
-    This is the main entry point for archive handling, usable by any download handler.
-
-    Args:
-        archive_path: Path to the downloaded archive file
-        temp_dir: Base temp directory for extraction (e.g., TMP_DIR)
-        ingest_dir: Final destination directory for book files
-        archive_id: Unique identifier for temp directory naming
-
-    Returns:
-        ArchiveResult with success status, final paths, and status message
-    """
-    extract_dir = temp_dir / f"extract_{archive_id}"
-
-    try:
-        # Create temp extraction directory
-        os.makedirs(extract_dir, exist_ok=True)
-        os.makedirs(ingest_dir, exist_ok=True)
-
-        # Extract to temp directory (filters to book files only)
-        extracted_files, warnings = extract_archive(archive_path, extract_dir)
-
-        if not extracted_files:
-            # Clean up and return error
-            shutil.rmtree(extract_dir, ignore_errors=True)
-            archive_path.unlink(missing_ok=True)
-            return ArchiveResult(
-                success=False,
-                final_paths=[],
-                message="",
-                error="No book files found in archive",
-            )
-
-        for warning in warnings:
-            logger.debug(warning)
-
-        logger.info(f"Extracted {len(extracted_files)} book file(s) from archive")
-
-        # Move book files to ingest folder
-        final_paths = []
-        for extracted_file in extracted_files:
-            final_path = ingest_dir / extracted_file.name
-            final_path = _handle_duplicate_filename(final_path)
-            shutil.move(str(extracted_file), str(final_path))
-            final_paths.append(final_path)
-            logger.debug(f"Moved to ingest: {final_path.name}")
-
-        # Clean up temp extraction directory and archive
-        shutil.rmtree(extract_dir, ignore_errors=True)
-        archive_path.unlink(missing_ok=True)
-
-        # Build success message with extracted formats
-        formats = [p.suffix.lstrip(".").upper() for p in final_paths]
-        if len(formats) == 1:
-            message = f"Extracted: {formats[0]}"
-        else:
-            message = f"Extracted: {len(formats)} files ({', '.join(formats)})"
-
-        return ArchiveResult(
-            success=True,
-            final_paths=final_paths,
-            message=message,
-        )
-
-    except PasswordProtectedError:
-        logger.error(f"Password-protected archive: {archive_path.name}")
-        shutil.rmtree(extract_dir, ignore_errors=True)
-        archive_path.unlink(missing_ok=True)
-        return ArchiveResult(
-            success=False,
-            final_paths=[],
-            message="",
-            error="Archive is password protected",
-        )
-
-    except CorruptedArchiveError as e:
-        logger.error(f"Corrupted archive: {e}")
-        shutil.rmtree(extract_dir, ignore_errors=True)
-        archive_path.unlink(missing_ok=True)
-        return ArchiveResult(
-            success=False,
-            final_paths=[],
-            message="",
-            error=f"Corrupted archive: {e}",
-        )
-
-    except ArchiveExtractionError as e:
-        logger.error(f"Archive extraction failed: {e}")
-        shutil.rmtree(extract_dir, ignore_errors=True)
-        archive_path.unlink(missing_ok=True)
-        return ArchiveResult(
-            success=False,
-            final_paths=[],
-            message="",
-            error=f"Extraction failed: {e}",
-        )

cwa_book_downloader/download/orchestrator.py

@@ -1,798 +0,0 @@
-"""Download queue orchestration and worker management.
-
-## Download Architecture
-
-All downloads follow a two-stage process:
-
-1. **Staging (TMP_DIR)**: Handlers download/copy files to a temp staging area.
-   - Direct downloads: Downloaded directly to staging
-   - Torrent downloads: Copied from torrent client's completed folder to staging
-   - NZB downloads: Moved from NZB client's completed folder to staging
-
-2. **Ingest (INGEST_DIR)**: Orchestrator moves staged files to the final location.
-   - Archive extraction (RAR/ZIP) happens here
-   - Custom scripts run here
-   - Final move to ingest folder
-
-This ensures:
-- Handlers don't need to know about ingest folder logic
-- Archive handling works uniformly for all sources
-- Single point of control for what enters the ingest folder
-"""
-
-import os
-import random
-import shutil
-import subprocess
-import threading
-import time
-from concurrent.futures import Future, ThreadPoolExecutor
-from pathlib import Path
-from threading import Event, Lock
-from typing import Any, Dict, List, Optional, Tuple
-
-from cwa_book_downloader.release_sources import direct_download
-from cwa_book_downloader.release_sources.direct_download import SearchUnavailable
-from cwa_book_downloader.core.config import config
-from cwa_book_downloader.config.env import TMP_DIR, DOWNLOAD_PATHS, INGEST_DIR
-from cwa_book_downloader.download.archive import is_archive, process_archive
-from cwa_book_downloader.release_sources import get_handler, get_source_display_name
-from cwa_book_downloader.core.logger import setup_logger
-from cwa_book_downloader.core.models import BookInfo, DownloadTask, QueueStatus, SearchFilters
-from cwa_book_downloader.core.queue import book_queue
-
-logger = setup_logger(__name__)
-
-
-# =============================================================================
-# Staging Directory Helpers
-# =============================================================================
-# Handlers should use these to get paths in the staging area.
-# The orchestrator handles moving staged files to the ingest folder.
-
-def get_staging_dir() -> Path:
-    """Get the staging directory for downloads.
-
-    All handlers should stage their downloads here. The orchestrator
-    handles moving staged files to the final ingest location.
-    """
-    TMP_DIR.mkdir(parents=True, exist_ok=True)
-    return TMP_DIR
-
-
-def get_staging_path(task_id: str, extension: str) -> Path:
-    """Get a staging path for a download.
-
-    Args:
-        task_id: Unique task identifier
-        extension: File extension (e.g., 'epub', 'zip')
-
-    Returns:
-        Path in staging directory for this download
-    """
-    staging_dir = get_staging_dir()
-    return staging_dir / f"{task_id}.{extension.lstrip('.')}"
-
-
-def stage_file(source_path: Path, task_id: str, copy: bool = False) -> Path:
-    """Stage a file for ingest processing.
-
-    Use this when a download client has completed a download and the file
-    needs to be staged for orchestrator processing.
-
-    Args:
-        source_path: Path to the completed download
-        task_id: Unique task identifier
-        copy: If True, copy the file (for torrents). If False, move it.
-
-    Returns:
-        Path to the staged file
-    """
-    staging_dir = get_staging_dir()
-    staged_path = staging_dir / f"{task_id}{source_path.suffix}"
-
-    if copy:
-        shutil.copy2(str(source_path), str(staged_path))
-        logger.debug(f"Copied to staging: {source_path} -> {staged_path}")
-    else:
-        shutil.move(str(source_path), str(staged_path))
-        logger.debug(f"Moved to staging: {source_path} -> {staged_path}")
-
-    return staged_path
-
-# WebSocket manager (initialized by app.py)
-try:
-    from cwa_book_downloader.api.websocket import ws_manager
-except ImportError:
-    ws_manager = None
-
-# Progress update throttling - track last broadcast time per book
-_progress_last_broadcast: Dict[str, float] = {}
-_progress_lock = Lock()
-
-# Stall detection - track last activity time per download
-_last_activity: Dict[str, float] = {}
-STALL_TIMEOUT = 300  # 5 minutes without progress/status update = stalled
-
-def search_books(query: str, filters: SearchFilters) -> List[Dict[str, Any]]:
-    """Search for books matching the query.
-    
-    Args:
-        query: Search term
-        filters: Search filters object
-        
-    Returns:
-        List[Dict]: List of book information dictionaries
-    """
-    try:
-        books = direct_download.search_books(query, filters)
-        return [_book_info_to_dict(book) for book in books]
-    except SearchUnavailable:
-        raise
-    except Exception as e:
-        logger.error_trace(f"Error searching books: {e}")
-        raise
-
-def get_book_info(book_id: str) -> Optional[Dict[str, Any]]:
-    """Get detailed information for a specific book.
-
-    Args:
-        book_id: Book identifier
-
-    Returns:
-        Optional[Dict]: Book information dictionary if found, None if not found
-
-    Raises:
-        Exception: If there's an error fetching the book info
-    """
-    try:
-        book = direct_download.get_book_info(book_id)
-        return _book_info_to_dict(book)
-    except Exception as e:
-        logger.error_trace(f"Error getting book info: {e}")
-        raise
-
-def queue_book(book_id: str, priority: int = 0, source: str = "direct_download") -> bool:
-    """Add a book to the download queue with specified priority.
-
-    Fetches display info and creates a DownloadTask. The handler will fetch
-    the full book details (including download URLs) when processing.
-
-    Args:
-        book_id: Book identifier (e.g., AA MD5 hash)
-        priority: Priority level (lower number = higher priority)
-        source: Release source handler to use (default: direct_download)
-
-    Returns:
-        bool: True if book was successfully queued
-    """
-    try:
-        # Fetch book info for display purposes
-        book_info = direct_download.get_book_info(book_id)
-        if not book_info:
-            logger.warning(f"Could not fetch book info for {book_id}")
-            return False
-
-        # Create a source-agnostic download task
-        task = DownloadTask(
-            task_id=book_id,
-            source=source,
-            title=book_info.title,
-            author=book_info.author,
-            format=book_info.format,
-            size=book_info.size,
-            preview=book_info.preview,
-            content_type=book_info.content,
-            priority=priority,
-        )
-
-        if not book_queue.add(task):
-            logger.info(f"Book already in queue: {book_info.title}")
-            return False
-
-        logger.info(f"Book queued with priority {priority}: {book_info.title}")
-
-        # Broadcast status update via WebSocket
-        if ws_manager:
-            ws_manager.broadcast_status_update(queue_status())
-
-        return True
-    except Exception as e:
-        logger.error_trace(f"Error queueing book: {e}")
-        return False
-
-
-def queue_release(release_data: dict, priority: int = 0) -> bool:
-    """Add a release to the download queue.
-
-    This is used when downloading from the ReleaseModal where we already have
-    all the release data from the search - no need to re-fetch.
-
-    Creates a DownloadTask directly from the release data. The handler will
-    fetch full details when processing.
-
-    Args:
-        release_data: Release dictionary with source, source_id, title, format, etc.
-        priority: Priority level (lower number = higher priority)
-
-    Returns:
-        bool: True if release was successfully queued
-    """
-    try:
-        source = release_data.get('source', 'direct_download')
-        extra = release_data.get('extra', {})
-
-        # Get author, preview, and content_type from top-level (preferred) or extra (fallback)
-        author = release_data.get('author') or extra.get('author')
-        preview = release_data.get('preview') or extra.get('preview')
-        content_type = release_data.get('content_type') or extra.get('content_type')
-
-        # Create a source-agnostic download task from release data
-        task = DownloadTask(
-            task_id=release_data['source_id'],
-            source=source,
-            title=release_data.get('title', 'Unknown'),
-            author=author,
-            format=release_data.get('format'),
-            size=release_data.get('size'),
-            preview=preview,
-            content_type=content_type,
-            priority=priority,
-        )
-
-        if not book_queue.add(task):
-            logger.info(f"Release already in queue: {task.title}")
-            return False
-
-        logger.info(f"Release queued with priority {priority}: {task.title}")
-
-        # Broadcast status update via WebSocket
-        if ws_manager:
-            ws_manager.broadcast_status_update(queue_status())
-
-        return True
-
-    except ValueError as e:
-        # Handler not found for this source
-        logger.warning(f"Unknown release source: {e}")
-        return False
-    except Exception as e:
-        logger.error_trace(f"Error queueing release: {e}")
-        return False
-
-def queue_status() -> Dict[str, Dict[str, Any]]:
-    """Get current status of the download queue.
-
-    Returns:
-        Dict: Queue status organized by status type with serialized task data
-    """
-    status = book_queue.get_status()
-    for _, tasks in status.items():
-        for _, task in tasks.items():
-            if task.download_path:
-                if not os.path.exists(task.download_path):
-                    task.download_path = None
-
-    # Convert Enum keys to strings and DownloadTask objects to dicts for JSON serialization
-    return {
-        status_type.value: {
-            task_id: _task_to_dict(task)
-            for task_id, task in tasks.items()
-        }
-        for status_type, tasks in status.items()
-    }
-
-def get_book_data(task_id: str) -> Tuple[Optional[bytes], Optional[DownloadTask]]:
-    """Get downloaded file data for a specific task.
-
-    Args:
-        task_id: Task identifier
-
-    Returns:
-        Tuple[Optional[bytes], Optional[DownloadTask]]: File data if available, and the task
-    """
-    task = None
-    try:
-        task = book_queue.get_task(task_id)
-        if not task:
-            return None, None
-
-        path = task.download_path
-        if not path:
-            return None, task
-
-        with open(path, "rb") as f:
-            return f.read(), task
-    except Exception as e:
-        logger.error_trace(f"Error getting book data: {e}")
-        if task:
-            task.download_path = None
-        return None, task
-
-def _book_info_to_dict(book: BookInfo) -> Dict[str, Any]:
-    """Convert BookInfo object to dictionary representation.
-
-    Transforms external preview URLs to local proxy URLs when cover caching is enabled.
-    """
-    import base64
-    from cwa_book_downloader.config.env import is_covers_cache_enabled
-
-    result = {
-        key: value for key, value in book.__dict__.items()
-        if value is not None
-    }
-
-    # Transform external preview URLs to local proxy URLs
-    # Skip if already a local URL (starts with /)
-    if result.get('preview') and is_covers_cache_enabled() and not result['preview'].startswith('/'):
-        original_url = result['preview']
-        encoded_url = base64.urlsafe_b64encode(original_url.encode()).decode()
-        result['preview'] = f"/api/covers/{book.id}?url={encoded_url}"
-
-    return result
-
-
-def _task_to_dict(task: DownloadTask) -> Dict[str, Any]:
-    """Convert DownloadTask object to dictionary representation.
-
-    Maps DownloadTask fields to the format expected by the frontend,
-    maintaining compatibility with the previous BookInfo-based format.
-    Transforms external preview URLs to local proxy URLs when cover caching is enabled.
-    """
-    import base64
-    from cwa_book_downloader.config.env import is_covers_cache_enabled
-
-    preview = task.preview
-
-    # Transform external preview URLs to local proxy URLs
-    # Skip if already a local URL (starts with /)
-    if preview and is_covers_cache_enabled() and not preview.startswith('/'):
-        encoded_url = base64.urlsafe_b64encode(preview.encode()).decode()
-        preview = f"/api/covers/{task.task_id}?url={encoded_url}"
-
-    return {
-        'id': task.task_id,
-        'title': task.title,
-        'author': task.author,
-        'format': task.format,
-        'size': task.size,
-        'preview': preview,
-        'content_type': task.content_type,
-        'source': task.source,
-        'source_display_name': get_source_display_name(task.source),
-        'priority': task.priority,
-        'added_time': task.added_time,
-        'progress': task.progress,
-        'status': task.status,
-        'status_message': task.status_message,
-        'download_path': task.download_path,
-    }
-
-
-def _download_task(task_id: str, cancel_flag: Event) -> Optional[str]:
-    """Download a task with cancellation support.
-
-    Delegates to the appropriate handler based on the task's source.
-    Handlers return a temp file path, orchestrator handles post-processing
-    (archive extraction, moving to ingest) uniformly for all sources.
-
-    Args:
-        task_id: Task identifier
-        cancel_flag: Threading event to signal cancellation
-
-    Returns:
-        str: Path to the downloaded file if successful, None otherwise
-    """
-    try:
-        # Check for cancellation before starting
-        if cancel_flag.is_set():
-            logger.info(f"Download cancelled before starting: {task_id}")
-            return None
-
-        task = book_queue.get_task(task_id)
-        if not task:
-            logger.error(f"Task not found in queue: {task_id}")
-            return None
-
-        # Create callbacks that update the orchestrator's tracking
-        progress_callback = lambda progress: update_download_progress(task_id, progress)
-        status_callback = lambda status, message=None: update_download_status(task_id, status, message)
-
-        # Get the download handler based on the task's source
-        handler = get_handler(task.source)
-        temp_path = handler.download(
-            task,
-            cancel_flag,
-            progress_callback,
-            status_callback
-        )
-
-        # Handler returns temp path - orchestrator handles post-processing
-        if not temp_path:
-            return None
-
-        temp_file = Path(temp_path)
-        if not temp_file.exists():
-            logger.error(f"Handler returned non-existent path: {temp_path}")
-            return None
-
-        # Check cancellation before post-processing
-        if cancel_flag.is_set():
-            logger.info(f"Download cancelled before post-processing: {task_id}")
-            temp_file.unlink(missing_ok=True)
-            return None
-
-        # Post-processing: archive extraction or direct move to ingest
-        return _post_process_download(
-            temp_file, task, cancel_flag, status_callback
-        )
-
-    except Exception as e:
-        if cancel_flag.is_set():
-            logger.info(f"Download cancelled during error handling: {task_id}")
-        else:
-            logger.error_trace(f"Error downloading: {e}")
-        return None
-
-
-def _post_process_download(
-    temp_file: Path,
-    task: DownloadTask,
-    cancel_flag: Event,
-    status_callback,
-) -> Optional[str]:
-    """Post-process a downloaded file: handle archives and move to ingest.
-
-    This runs uniformly for all download sources, ensuring consistent behavior.
-
-    Args:
-        temp_file: Path to downloaded file in temp directory
-        task: Download task with metadata
-        cancel_flag: Cancellation event
-        status_callback: Callback for status updates
-
-    Returns:
-        Final path in ingest directory, or None on failure
-    """
-    # Route to content-type-specific ingest directory if configured
-    content_type = task.content_type.lower() if task.content_type else None
-    ingest_dir = DOWNLOAD_PATHS.get(content_type, INGEST_DIR)
-    if content_type and ingest_dir != INGEST_DIR:
-        logger.debug(f"Routing content type '{content_type}' to {ingest_dir}")
-    os.makedirs(ingest_dir, exist_ok=True)
-
-    # Handle archive extraction (RAR/ZIP)
-    if is_archive(temp_file):
-        logger.info(f"Archive detected, extracting: {temp_file.name}")
-        status_callback("resolving", "Extracting archive...")
-
-        result = process_archive(
-            archive_path=temp_file,
-            temp_dir=TMP_DIR,
-            ingest_dir=ingest_dir,
-            archive_id=task.task_id,
-        )
-
-        if result.success:
-            status_callback("complete", result.message)
-            return str(result.final_paths[0])
-        else:
-            status_callback("error", result.error)
-            return None
-
-    # Non-archive: run custom script if configured, then move to ingest
-    if config.CUSTOM_SCRIPT:
-        logger.info(f"Running custom script: {config.CUSTOM_SCRIPT}")
-        subprocess.run([config.CUSTOM_SCRIPT, str(temp_file)])
-
-    # Check cancellation before final move
-    if cancel_flag.is_set():
-        logger.info(f"Download cancelled before ingest: {task.task_id}")
-        temp_file.unlink(missing_ok=True)
-        return None
-
-    # Generate filename and move to ingest
-    filename = task.get_filename()
-    if not filename:
-        filename = f"{task.task_id}.{task.format or 'bin'}"
-
-    final_path = ingest_dir / filename
-
-    # Handle duplicate filenames
-    if final_path.exists():
-        base = final_path.stem
-        ext = final_path.suffix
-        counter = 1
-        while final_path.exists():
-            final_path = ingest_dir / f"{base}_{counter}{ext}"
-            counter += 1
-        logger.info(f"File already exists, saving as: {final_path.name}")
-
-    # Use intermediate .crdownload file for atomic move
-    intermediate_path = ingest_dir / f"{task.task_id}.crdownload"
-
-    try:
-        shutil.move(str(temp_file), str(intermediate_path))
-    except Exception as e:
-        logger.debug(f"Error moving file: {e}, trying copy instead")
-        try:
-            shutil.copyfile(str(temp_file), str(intermediate_path))
-            temp_file.unlink(missing_ok=True)
-        except Exception as e2:
-            logger.error(f"Failed to move/copy file to ingest: {e2}")
-            return None
-
-    # Final cancellation check
-    if cancel_flag.is_set():
-        logger.info(f"Download cancelled before final rename: {task.task_id}")
-        intermediate_path.unlink(missing_ok=True)
-        return None
-
-    os.rename(str(intermediate_path), str(final_path))
-    logger.info(f"Download completed: {final_path.name}")
-
-    return str(final_path)
-
-def update_download_progress(book_id: str, progress: float) -> None:
-    """Update download progress with throttled WebSocket broadcasts.
-
-    Progress is always stored in the queue, but WebSocket broadcasts are
-    throttled to avoid flooding clients with updates. Broadcasts occur:
-    - At most once per DOWNLOAD_PROGRESS_UPDATE_INTERVAL seconds
-    - Always at 0% (start) and 100% (complete)
-    - On significant progress jumps (>10%)
-    """
-    book_queue.update_progress(book_id, progress)
-
-    # Track activity for stall detection
-    with _progress_lock:
-        _last_activity[book_id] = time.time()
-    
-    # Broadcast progress via WebSocket with throttling
-    if ws_manager:
-        current_time = time.time()
-        should_broadcast = False
-        
-        with _progress_lock:
-            last_broadcast = _progress_last_broadcast.get(book_id, 0)
-            last_progress = _progress_last_broadcast.get(f"{book_id}_progress", 0)
-            time_elapsed = current_time - last_broadcast
-            
-            # Always broadcast at start (0%) or completion (>=99%)
-            if progress <= 1 or progress >= 99:
-                should_broadcast = True
-            # Broadcast if enough time has passed (convert interval from seconds)
-            elif time_elapsed >= config.DOWNLOAD_PROGRESS_UPDATE_INTERVAL:
-                should_broadcast = True
-            # Broadcast on significant progress jumps (>10%)
-            elif progress - last_progress >= 10:
-                should_broadcast = True
-            
-            if should_broadcast:
-                _progress_last_broadcast[book_id] = current_time
-                _progress_last_broadcast[f"{book_id}_progress"] = progress
-        
-        if should_broadcast:
-            ws_manager.broadcast_download_progress(book_id, progress, 'downloading')
-
-def update_download_status(book_id: str, status: str, message: Optional[str] = None) -> None:
-    """Update download status with optional detailed message.
-    
-    Args:
-        book_id: Book identifier
-        status: Status string (e.g., 'resolving', 'downloading')
-        message: Optional detailed status message for UI display
-    """
-    # Map string status to QueueStatus enum
-    status_map = {
-        'queued': QueueStatus.QUEUED,
-        'resolving': QueueStatus.RESOLVING,
-        'downloading': QueueStatus.DOWNLOADING,
-        'complete': QueueStatus.COMPLETE,
-        'available': QueueStatus.AVAILABLE,
-        'error': QueueStatus.ERROR,
-        'done': QueueStatus.DONE,
-        'cancelled': QueueStatus.CANCELLED,
-    }
-    
-    queue_status_enum = status_map.get(status.lower())
-    if queue_status_enum:
-        book_queue.update_status(book_id, queue_status_enum)
-
-        # Track activity for stall detection
-        with _progress_lock:
-            _last_activity[book_id] = time.time()
-
-        # Update status message if provided (empty string clears the message)
-        if message is not None:
-            book_queue.update_status_message(book_id, message)
-
-        # Broadcast status update via WebSocket
-        if ws_manager:
-            ws_manager.broadcast_status_update(queue_status())
-
-def cancel_download(book_id: str) -> bool:
-    """Cancel a download.
-    
-    Args:
-        book_id: Book identifier to cancel
-        
-    Returns:
-        bool: True if cancellation was successful
-    """
-    result = book_queue.cancel_download(book_id)
-    
-    # Broadcast status update via WebSocket
-    if result and ws_manager and ws_manager.is_enabled():
-        ws_manager.broadcast_status_update(queue_status())
-    
-    return result
-
-def set_book_priority(book_id: str, priority: int) -> bool:
-    """Set priority for a queued book.
-    
-    Args:
-        book_id: Book identifier
-        priority: New priority level (lower = higher priority)
-        
-    Returns:
-        bool: True if priority was successfully changed
-    """
-    return book_queue.set_priority(book_id, priority)
-
-def reorder_queue(book_priorities: Dict[str, int]) -> bool:
-    """Bulk reorder queue.
-    
-    Args:
-        book_priorities: Dict mapping book_id to new priority
-        
-    Returns:
-        bool: True if reordering was successful
-    """
-    return book_queue.reorder_queue(book_priorities)
-
-def get_queue_order() -> List[Dict[str, any]]:
-    """Get current queue order for display."""
-    return book_queue.get_queue_order()
-
-def get_active_downloads() -> List[str]:
-    """Get list of currently active downloads."""
-    return book_queue.get_active_downloads()
-
-def clear_completed() -> int:
-    """Clear all completed downloads from tracking."""
-    return book_queue.clear_completed()
-
-def _cleanup_progress_tracking(task_id: str) -> None:
-    """Clean up progress tracking data for a completed/cancelled download."""
-    with _progress_lock:
-        _progress_last_broadcast.pop(task_id, None)
-        _progress_last_broadcast.pop(f"{task_id}_progress", None)
-        _last_activity.pop(task_id, None)
-
-
-def _process_single_download(task_id: str, cancel_flag: Event) -> None:
-    """Process a single download job."""
-    try:
-        # Status will be updated through callbacks during download process
-        # (resolving -> downloading -> complete)
-        download_path = _download_task(task_id, cancel_flag)
-
-        # Clean up progress tracking
-        _cleanup_progress_tracking(task_id)
-
-        if cancel_flag.is_set():
-            book_queue.update_status(task_id, QueueStatus.CANCELLED)
-            # Broadcast cancellation
-            if ws_manager:
-                ws_manager.broadcast_status_update(queue_status())
-            return
-
-        if download_path:
-            book_queue.update_download_path(task_id, download_path)
-            # Only update status if not already set (e.g., by archive extraction callback)
-            task = book_queue.get_task(task_id)
-            if not task or task.status != QueueStatus.COMPLETE:
-                book_queue.update_status(task_id, QueueStatus.COMPLETE)
-        else:
-            book_queue.update_status(task_id, QueueStatus.ERROR)
-
-        # Broadcast final status (completed or error)
-        if ws_manager:
-            ws_manager.broadcast_status_update(queue_status())
-
-    except Exception as e:
-        # Clean up progress tracking even on error
-        _cleanup_progress_tracking(task_id)
-
-        if not cancel_flag.is_set():
-            logger.error_trace(f"Error in download processing: {e}")
-            book_queue.update_status(task_id, QueueStatus.ERROR)
-            # Set error message if not already set by handler
-            task = book_queue.get_task(task_id)
-            if task and not task.status_message:
-                book_queue.update_status_message(task_id, f"Download failed: {type(e).__name__}: {str(e)}")
-        else:
-            logger.info(f"Download cancelled: {task_id}")
-            book_queue.update_status(task_id, QueueStatus.CANCELLED)
-
-        # Broadcast error/cancelled status
-        if ws_manager:
-            ws_manager.broadcast_status_update(queue_status())
-
-def concurrent_download_loop() -> None:
-    """Main download coordinator using ThreadPoolExecutor for concurrent downloads."""
-    max_workers = config.MAX_CONCURRENT_DOWNLOADS
-    logger.info(f"Starting concurrent download loop with {max_workers} workers")
-
-    with ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="Download") as executor:
-        active_futures: Dict[Future, str] = {}  # Track active download futures
-
-        while True:
-            # Clean up completed futures
-            completed_futures = [f for f in active_futures if f.done()]
-            for future in completed_futures:
-                task_id = active_futures.pop(future)
-                try:
-                    future.result()  # This will raise any exceptions from the worker
-                except Exception as e:
-                    logger.error_trace(f"Future exception for {task_id}: {e}")
-
-            # Check for stalled downloads (no activity in STALL_TIMEOUT seconds)
-            current_time = time.time()
-            with _progress_lock:
-                for future, task_id in list(active_futures.items()):
-                    last_active = _last_activity.get(task_id, current_time)
-                    if current_time - last_active > STALL_TIMEOUT:
-                        logger.warning(f"Download stalled for {task_id}, cancelling")
-                        book_queue.cancel_download(task_id)
-                        book_queue.update_status_message(task_id, f"Download stalled (no activity for {STALL_TIMEOUT}s)")
-
-            # Start new downloads if we have capacity
-            while len(active_futures) < max_workers:
-                next_download = book_queue.get_next()
-                if not next_download:
-                    break
-
-                # Stagger concurrent downloads to avoid rate limiting on shared download servers
-                # Only delay if other downloads are already active
-                if active_futures:
-                    stagger_delay = random.uniform(2, 5)
-                    logger.debug(f"Staggering download start by {stagger_delay:.1f}s")
-                    time.sleep(stagger_delay)
-
-                task_id, cancel_flag = next_download
-
-                # Submit download job to thread pool
-                future = executor.submit(_process_single_download, task_id, cancel_flag)
-                active_futures[future] = task_id
-
-            # Brief sleep to prevent busy waiting
-            time.sleep(config.MAIN_LOOP_SLEEP_TIME)
-
-# Download coordinator thread (started explicitly via start())
-_coordinator_thread: Optional[threading.Thread] = None
-_started = False
-
-
-def start() -> None:
-    """Start the download coordinator thread.
-
-    This should be called once during application startup.
-    Calling multiple times is safe - subsequent calls are no-ops.
-    """
-    global _coordinator_thread, _started
-
-    if _started:
-        logger.debug("Download coordinator already started")
-        return
-
-    _coordinator_thread = threading.Thread(
-        target=concurrent_download_loop,
-        daemon=True,
-        name="DownloadCoordinator"
-    )
-    _coordinator_thread.start()
-    _started = True
-
-    logger.info(f"Download coordinator started with {config.MAX_CONCURRENT_DOWNLOADS} concurrent workers")

cwa_book_downloader/download_clients/__init__.py

@@ -1,55 +0,0 @@
-"""External download client integrations (qBittorrent, SABnzbd, etc.)."""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import List, Optional, Tuple
-from enum import Enum
-
-
-class DownloadStatus(Enum):
-    """Status of a download in an external client."""
-    QUEUED = "queued"
-    DOWNLOADING = "downloading"
-    PAUSED = "paused"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    SEEDING = "seeding"  # Torrents only
-
-
-@dataclass
-class ClientDownloadProgress:
-    """Progress info from external download client."""
-    status: DownloadStatus
-    progress: float                  # 0-100
-    download_speed: Optional[int]    # bytes/sec
-    eta: Optional[int]               # seconds remaining
-    save_path: Optional[str]         # Where the file will be/is
-
-
-class DownloadClient(ABC):
-    """Abstract base class for download clients."""
-
-    @abstractmethod
-    def add_download(self, url: str, title: str) -> str:
-        """Add a download (torrent/magnet or NZB URL). Returns download ID for tracking."""
-        pass
-
-    @abstractmethod
-    def get_download(self, download_id: str) -> Optional[ClientDownloadProgress]:
-        """Get progress of a specific download."""
-        pass
-
-    @abstractmethod
-    def list_downloads(self) -> List[Tuple[str, ClientDownloadProgress]]:
-        """List all downloads with their progress."""
-        pass
-
-    @abstractmethod
-    def get_completed_path(self, download_id: str) -> Optional[str]:
-        """Get the path to completed download."""
-        pass
-
-    @abstractmethod
-    def test_connection(self) -> bool:
-        """Test if the client is reachable and credentials are valid."""
-        pass

cwa_book_downloader/metadata_providers/__init__.py

@@ -1,481 +0,0 @@
-"""Metadata provider plugin system - base classes and registry."""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field, asdict
-from enum import Enum
-from typing import List, Optional, Dict, Type, Literal, Any, Union
-
-
-class SearchType(str, Enum):
-    """Type of search to perform."""
-    GENERAL = "general"  # Search all fields (title, author, ISBN, etc.)
-    TITLE = "title"      # Search by title only
-    AUTHOR = "author"    # Search by author only
-    ISBN = "isbn"        # Search by ISBN
-
-
-class SortOrder(str, Enum):
-    """Sort order for search results."""
-    RELEVANCE = "relevance"    # Best match first (default)
-    POPULARITY = "popularity"  # Most popular first
-    RATING = "rating"          # Highest rated first
-    NEWEST = "newest"          # Most recently published first
-    OLDEST = "oldest"          # Oldest published first
-
-
-# Display labels for sort options
-SORT_LABELS: Dict[SortOrder, str] = {
-    SortOrder.RELEVANCE: "Most relevant",
-    SortOrder.POPULARITY: "Most popular",
-    SortOrder.RATING: "Highest rated",
-    SortOrder.NEWEST: "Newest",
-    SortOrder.OLDEST: "Oldest",
-}
-
-
-@dataclass
-class TextSearchField:
-    """Text input search field."""
-    key: str                              # Field identifier (e.g., "author", "publisher")
-    label: str                            # Display label in UI
-    placeholder: str = ""                 # Placeholder text
-    description: str = ""                 # Help text
-
-
-@dataclass
-class NumberSearchField:
-    """Numeric input search field."""
-    key: str
-    label: str
-    placeholder: str = ""
-    description: str = ""
-    min_value: Optional[int] = None
-    max_value: Optional[int] = None
-    step: int = 1
-
-
-@dataclass
-class SelectSearchField:
-    """Single-choice dropdown search field."""
-    key: str
-    label: str
-    options: List[Dict[str, str]] = field(default_factory=list)  # [{value: "", label: ""}]
-    placeholder: str = ""
-    description: str = ""
-
-
-@dataclass
-class CheckboxSearchField:
-    """Boolean checkbox search field."""
-    key: str
-    label: str
-    description: str = ""
-    default: bool = False
-
-
-# Type alias for all search field types
-SearchField = Union[TextSearchField, NumberSearchField, SelectSearchField, CheckboxSearchField]
-
-
-def _get_field_type_name(search_field: SearchField) -> str:
-    """Get the type name for a search field."""
-    return search_field.__class__.__name__
-
-
-def serialize_search_field(search_field: SearchField) -> Dict[str, Any]:
-    """Serialize a search field for API response.
-
-    Args:
-        search_field: The search field definition.
-
-    Returns:
-        Dict representation for frontend.
-    """
-    result: Dict[str, Any] = {
-        "key": search_field.key,
-        "label": search_field.label,
-        "type": _get_field_type_name(search_field),
-        "placeholder": search_field.placeholder if hasattr(search_field, 'placeholder') else "",
-        "description": search_field.description if hasattr(search_field, 'description') else "",
-    }
-
-    # Add type-specific properties
-    if isinstance(search_field, NumberSearchField):
-        result["min"] = search_field.min_value
-        result["max"] = search_field.max_value
-        result["step"] = search_field.step
-    elif isinstance(search_field, SelectSearchField):
-        result["options"] = search_field.options
-    elif isinstance(search_field, CheckboxSearchField):
-        result["default"] = search_field.default
-
-    return result
-
-
-@dataclass
-class MetadataSearchOptions:
-    """Options for metadata search queries.
-
-    Provides an abstracted interface that works across all metadata providers.
-    Providers map these options to their specific API parameters.
-    """
-    query: str
-    search_type: SearchType = SearchType.GENERAL
-    language: Optional[str] = None  # ISO 639-1 code (e.g., "en", "fr")
-    sort: SortOrder = SortOrder.RELEVANCE
-    limit: int = 20
-    page: int = 1
-    fields: Dict[str, Any] = field(default_factory=dict)  # Custom search field values
-
-
-@dataclass
-class DisplayField:
-    """A display field for metadata cards.
-
-    Providers can populate these to show provider-specific metadata
-    like ratings, page counts, reader counts, etc.
-    """
-    label: str                       # e.g., "Rating", "Pages", "Readers"
-    value: str                       # e.g., "4.5", "496", "8,041"
-    icon: Optional[str] = None       # Icon name: "star", "book", "users", "editions"
-
-
-@dataclass
-class BookMetadata:
-    """Book from metadata provider (not a specific release)."""
-    provider: str                    # Which provider this came from (internal name)
-    provider_id: str                 # ID in that provider's system
-    title: str
-
-    # Provider display name for UI (e.g., "Open Library" instead of "openlibrary")
-    provider_display_name: Optional[str] = None
-
-    # Optional - not all providers have all fields
-    authors: List[str] = field(default_factory=list)
-    isbn_10: Optional[str] = None
-    isbn_13: Optional[str] = None
-    cover_url: Optional[str] = None
-    description: Optional[str] = None
-    publisher: Optional[str] = None
-    publish_year: Optional[int] = None
-    language: Optional[str] = None
-    genres: List[str] = field(default_factory=list)
-    source_url: Optional[str] = None  # Link to book on provider's site
-
-    # Provider-specific display fields for cards/lists
-    display_fields: List[DisplayField] = field(default_factory=list)
-
-
-class MetadataProvider(ABC):
-    """Interface for metadata providers.
-
-    All metadata providers must implement this interface. The search method
-    accepts MetadataSearchOptions for unified search across providers.
-
-    Attributes:
-        name: Internal identifier (e.g., "hardcover")
-        display_name: Human-readable name (e.g., "Hardcover")
-        requires_auth: True if API key/authentication is required
-        supported_sorts: List of SortOrder values this provider supports
-        search_fields: List of provider-specific search fields
-    """
-    name: str
-    display_name: str
-    requires_auth: bool
-    supported_sorts: List[SortOrder] = [SortOrder.RELEVANCE]
-    search_fields: List[SearchField] = []
-
-    @abstractmethod
-    def search(self, options: MetadataSearchOptions) -> List[BookMetadata]:
-        """Search for books using the provided options.
-
-        Args:
-            options: Search options including query, type, language, sort, pagination.
-
-        Returns:
-            List of BookMetadata matching the search criteria.
-
-        Note:
-            - If search_type is ISBN, this delegates to search_by_isbn()
-            - Unsupported sort orders fall back to RELEVANCE
-            - Language filtering is best-effort (not all providers support it)
-        """
-        pass
-
-    @abstractmethod
-    def get_book(self, book_id: str) -> Optional[BookMetadata]:
-        """Get a specific book by provider ID."""
-        pass
-
-    @abstractmethod
-    def search_by_isbn(self, isbn: str) -> Optional[BookMetadata]:
-        """Search for a book by ISBN."""
-        pass
-
-    @abstractmethod
-    def is_available(self) -> bool:
-        """Check if this provider is configured and available."""
-        pass
-
-
-# Provider registry
-_PROVIDERS: Dict[str, Type[MetadataProvider]] = {}
-_PROVIDER_KWARGS_FACTORIES: Dict[str, Any] = {}  # Callable[[], Dict]
-
-
-def register_provider(name: str):
-    """Decorator to register a metadata provider."""
-    def decorator(cls):
-        _PROVIDERS[name] = cls
-        return cls
-    return decorator
-
-
-def register_provider_kwargs(name: str):
-    """Decorator to register a provider's kwargs factory.
-
-    The decorated function should return a Dict of kwargs to pass to the
-    provider constructor. This allows each provider to define its own
-    configuration requirements without polluting the core module.
-
-    Example:
-        @register_provider_kwargs("hardcover")
-        def _hardcover_kwargs() -> Dict:
-            from cwa_book_downloader.core.config import config
-            return {"api_key": config.get("HARDCOVER_API_KEY", "")}
-    """
-    def decorator(fn):
-        _PROVIDER_KWARGS_FACTORIES[name] = fn
-        return fn
-    return decorator
-
-
-def get_provider(name: str, **kwargs) -> MetadataProvider:
-    """Factory - instantiate any registered provider."""
-    if name not in _PROVIDERS:
-        raise ValueError(f"Unknown metadata provider: {name}")
-    return _PROVIDERS[name](**kwargs)
-
-
-def list_providers() -> List[dict]:
-    """For settings UI - list available providers with their requirements."""
-    return [
-        {"name": n, "display_name": c.display_name, "requires_auth": c.requires_auth}
-        for n, c in _PROVIDERS.items()
-    ]
-
-
-def get_provider_kwargs(provider_name: str) -> Dict:
-    """Get provider-specific initialization kwargs based on configuration.
-
-    Looks up the provider's registered kwargs factory and calls it to get
-    the configuration. Each provider registers its own factory via
-    @register_provider_kwargs decorator.
-
-    Args:
-        provider_name: Name of the provider.
-
-    Returns:
-        Dict of kwargs to pass to provider constructor.
-    """
-    factory = _PROVIDER_KWARGS_FACTORIES.get(provider_name)
-    if factory:
-        return factory()
-    return {}
-
-
-def is_provider_registered(provider_name: str) -> bool:
-    """Check if a provider is registered.
-
-    Args:
-        provider_name: Name of the provider.
-
-    Returns:
-        True if provider is registered, False otherwise.
-    """
-    return provider_name in _PROVIDERS
-
-
-def is_provider_enabled(provider_name: str) -> bool:
-    """Check if a provider is enabled in settings.
-
-    Each provider has an enabled flag (e.g., HARDCOVER_ENABLED, OPENLIBRARY_ENABLED)
-    that must be explicitly set to True for the provider to be used.
-
-    Args:
-        provider_name: Name of the provider.
-
-    Returns:
-        True if provider is enabled, False otherwise.
-    """
-    from cwa_book_downloader.core.config import config as app_config
-
-    # Refresh config to get latest settings
-    app_config.refresh()
-
-    # Check the provider-specific enabled flag
-    enabled_key = f"{provider_name.upper()}_ENABLED"
-    return app_config.get(enabled_key, False) is True
-
-
-def get_enabled_providers() -> List[str]:
-    """Get list of all enabled provider names.
-
-    Returns:
-        List of enabled provider names.
-    """
-    enabled = []
-    for name in _PROVIDERS:
-        if is_provider_enabled(name):
-            enabled.append(name)
-    return enabled
-
-
-def get_configured_provider() -> Optional[MetadataProvider]:
-    """Get the currently configured metadata provider, if any.
-
-    Uses the METADATA_PROVIDER config setting to determine which provider
-    to instantiate. Returns None if no provider is configured or not enabled.
-
-    Returns:
-        MetadataProvider instance or None.
-    """
-    from cwa_book_downloader.core.config import config as app_config
-
-    # Refresh config to ensure we have the latest saved settings
-    app_config.refresh()
-
-    metadata_provider = app_config.get("METADATA_PROVIDER", "")
-    if not metadata_provider:
-        return None
-
-    if metadata_provider not in _PROVIDERS:
-        return None
-
-    # Check if the provider is enabled
-    if not is_provider_enabled(metadata_provider):
-        return None
-
-    kwargs = get_provider_kwargs(metadata_provider)
-    return get_provider(metadata_provider, **kwargs)
-
-
-def get_provider_sort_options(provider_name: Optional[str] = None) -> List[Dict[str, str]]:
-    """Get sort options for a metadata provider.
-
-    Returns a list of {value, label} dicts suitable for frontend dropdowns.
-
-    Args:
-        provider_name: Provider name. If None, uses configured provider.
-
-    Returns:
-        List of sort option dicts, or default [relevance] if provider not found.
-    """
-    if provider_name is None:
-        from cwa_book_downloader.core.config import config as app_config
-        app_config.refresh()
-        provider_name = app_config.get("METADATA_PROVIDER", "")
-
-    if provider_name and provider_name in _PROVIDERS:
-        provider_class = _PROVIDERS[provider_name]
-        supported = getattr(provider_class, 'supported_sorts', [SortOrder.RELEVANCE])
-    else:
-        supported = [SortOrder.RELEVANCE]
-
-    return [
-        {"value": sort.value, "label": SORT_LABELS.get(sort, sort.value.title())}
-        for sort in supported
-    ]
-
-
-def get_provider_search_fields(provider_name: Optional[str] = None) -> List[Dict[str, Any]]:
-    """Get search fields for a metadata provider.
-
-    Returns a list of serialized search field dicts suitable for frontend rendering.
-
-    Args:
-        provider_name: Provider name. If None, uses configured provider.
-
-    Returns:
-        List of search field dicts, or empty list if provider not found.
-    """
-    if provider_name is None:
-        from cwa_book_downloader.core.config import config as app_config
-        app_config.refresh()
-        provider_name = app_config.get("METADATA_PROVIDER", "")
-
-    if provider_name and provider_name in _PROVIDERS:
-        provider_class = _PROVIDERS[provider_name]
-        fields = getattr(provider_class, 'search_fields', [])
-    else:
-        fields = []
-
-    return [serialize_search_field(f) for f in fields]
-
-
-def get_provider_default_sort(provider_name: Optional[str] = None) -> str:
-    """Get the default sort order for a metadata provider.
-
-    Reads from the provider-specific config setting (e.g., HARDCOVER_DEFAULT_SORT).
-
-    Args:
-        provider_name: Provider name. If None, uses configured provider.
-
-    Returns:
-        Default sort value string, or "relevance" if not configured.
-    """
-    from cwa_book_downloader.core.config import config as app_config
-
-    if provider_name is None:
-        app_config.refresh()
-        provider_name = app_config.get("METADATA_PROVIDER", "")
-
-    if not provider_name:
-        return "relevance"
-
-    # Look up provider-specific default sort setting
-    setting_key = f"{provider_name.upper()}_DEFAULT_SORT"
-    return app_config.get(setting_key, "relevance")
-
-
-def sync_metadata_provider_selection() -> None:
-    """Sync the METADATA_PROVIDER setting based on enabled providers.
-
-    If the currently selected provider is not enabled (or nothing is selected),
-    auto-select the first enabled provider. This should be called after
-    enabling/disabling a provider.
-    """
-    from cwa_book_downloader.core.config import config as app_config
-    from cwa_book_downloader.core.settings_registry import save_config_file, load_config_file
-
-    app_config.refresh()
-
-    current_provider = app_config.get("METADATA_PROVIDER", "")
-    enabled = get_enabled_providers()
-
-    # If current provider is valid and enabled, nothing to do
-    if current_provider and current_provider in enabled:
-        return
-
-    # Auto-select first enabled provider (or clear if none)
-    new_provider = enabled[0] if enabled else ""
-
-    if new_provider != current_provider:
-        # Update the general settings config
-        general_config = load_config_file("general")
-        general_config["METADATA_PROVIDER"] = new_provider
-        save_config_file("general", general_config)
-        app_config.refresh()
-
-
-# Import provider implementations to trigger registration
-# These must be imported AFTER the base classes and registry are defined
-try:
-    from cwa_book_downloader.metadata_providers import hardcover  # noqa: F401, E402
-except ImportError:
-    pass  # Hardcover provider is optional
-
-try:
-    from cwa_book_downloader.metadata_providers import openlibrary  # noqa: F401, E402
-except ImportError:
-    pass  # Open Library provider is optional

cwa_book_downloader/metadata_providers/hardcover.py

@@ -1,752 +0,0 @@
-"""Hardcover.app metadata provider. Requires API key."""
-
-import requests
-from typing import Any, Dict, List, Optional
-
-from cwa_book_downloader.core.cache import cacheable
-from cwa_book_downloader.core.logger import setup_logger
-from cwa_book_downloader.core.settings_registry import (
-    register_settings,
-    CheckboxField,
-    PasswordField,
-    SelectField,
-    ActionButton,
-    HeadingField,
-)
-from cwa_book_downloader.core.config import config as app_config
-from cwa_book_downloader.metadata_providers import (
-    BookMetadata,
-    DisplayField,
-    MetadataProvider,
-    MetadataSearchOptions,
-    SearchType,
-    SortOrder,
-    register_provider,
-    register_provider_kwargs,
-    TextSearchField,
-)
-
-logger = setup_logger(__name__)
-
-HARDCOVER_API_URL = "https://api.hardcover.app/v1/graphql"
-
-
-# Mapping from abstract sort order to Hardcover sort parameter
-# Note: release_year is more consistently populated than release_date_i
-SORT_MAPPING: Dict[SortOrder, str] = {
-    SortOrder.RELEVANCE: "_text_match:desc,users_count:desc",
-    SortOrder.POPULARITY: "users_count:desc",
-    SortOrder.RATING: "rating:desc",
-    SortOrder.NEWEST: "release_year:desc",
-    SortOrder.OLDEST: "release_year:asc",
-}
-
-# Mapping from abstract search type to Hardcover fields parameter
-SEARCH_TYPE_FIELDS: Dict[SearchType, str] = {
-    SearchType.GENERAL: "title,isbns,series_names,author_names,alternative_titles",
-    SearchType.TITLE: "title,alternative_titles",
-    SearchType.AUTHOR: "author_names",
-    # ISBN is handled separately via search_by_isbn()
-}
-
-
-def _combine_headline_description(headline: Optional[str], description: Optional[str]) -> Optional[str]:
-    """Combine headline (tagline) and description into a single description.
-
-    Hardcover stores a short 'headline' (tagline/promotional text) separately
-    from the main description. This combines them for display.
-
-    Args:
-        headline: Short promotional text or tagline.
-        description: Full book synopsis/description.
-
-    Returns:
-        Combined description with headline as the first line, or just one if only one exists.
-    """
-    if headline and description:
-        # Add headline as first paragraph, followed by description
-        return f"{headline}\n\n{description}"
-    elif headline:
-        return headline
-    elif description:
-        return description
-    return None
-
-
-@register_provider_kwargs("hardcover")
-def _hardcover_kwargs() -> Dict[str, Any]:
-    """Provide Hardcover-specific constructor kwargs."""
-    return {"api_key": app_config.get("HARDCOVER_API_KEY", "")}
-
-
-@register_provider("hardcover")
-class HardcoverProvider(MetadataProvider):
-    """Hardcover.app metadata provider using GraphQL API."""
-
-    name = "hardcover"
-    display_name = "Hardcover"
-    requires_auth = True
-    supported_sorts = [
-        SortOrder.RELEVANCE,
-        SortOrder.POPULARITY,
-        SortOrder.RATING,
-        SortOrder.NEWEST,
-        SortOrder.OLDEST,
-    ]
-    search_fields = [
-        TextSearchField(
-            key="author",
-            label="Author",
-            description="Search by author name",
-        ),
-        TextSearchField(
-            key="title",
-            label="Title",
-            description="Search by book title",
-        ),
-    ]
-
-    def __init__(self, api_key: Optional[str] = None):
-        """Initialize provider with API key.
-
-        Args:
-            api_key: Hardcover API key. If not provided, uses config singleton.
-        """
-        self.api_key = api_key or app_config.get("HARDCOVER_API_KEY", "")
-        self.session = requests.Session()
-        if self.api_key:
-            self.session.headers.update({
-                "Authorization": f"Bearer {self.api_key}",
-                "Content-Type": "application/json",
-            })
-
-    def is_available(self) -> bool:
-        """Check if provider is configured with an API key."""
-        return bool(self.api_key)
-
-    def search(self, options: MetadataSearchOptions) -> List[BookMetadata]:
-        """Search for books using Hardcover's search API.
-
-        Args:
-            options: Search options (query, type, sort, pagination, fields).
-
-        Returns:
-            List of BookMetadata objects.
-        """
-        if not self.api_key:
-            logger.warning("Hardcover API key not configured")
-            return []
-
-        # Handle ISBN search separately
-        if options.search_type == SearchType.ISBN:
-            result = self.search_by_isbn(options.query)
-            return [result] if result else []
-
-        # Build cache key from options (include fields for cache differentiation)
-        fields_key = ":".join(f"{k}={v}" for k, v in sorted(options.fields.items()))
-        cache_key = f"{options.query}:{options.search_type.value}:{options.sort.value}:{options.limit}:{options.page}:{fields_key}"
-        return self._search_cached(cache_key, options)
-
-    @cacheable(ttl_key="METADATA_CACHE_SEARCH_TTL", ttl_default=300, key_prefix="hardcover:search")
-    def _search_cached(self, cache_key: str, options: MetadataSearchOptions) -> List[BookMetadata]:
-        """Cached search implementation.
-
-        Args:
-            cache_key: Cache key (used by decorator).
-            options: Search options.
-
-        Returns:
-            List of BookMetadata objects.
-        """
-        # Determine query and fields based on custom search fields
-        # Field-first search: when a specific field has a value, search that field
-        author_value = options.fields.get("author", "").strip()
-        title_value = options.fields.get("title", "").strip()
-
-        logger.debug(f"Field-first search check: author_value='{author_value}', title_value='{title_value}'")
-
-        # Determine what to search and which fields to target
-        # Note: Hardcover API requires 'weights' when using 'fields' parameter
-        if author_value and not title_value:
-            # Author-only search: search author_names field with author query
-            query = author_value
-            search_fields = "author_names"
-            search_weights = "1"
-            logger.debug(f"Author-only search: query='{query}', fields='{search_fields}'")
-        elif title_value and not author_value:
-            # Title-only search: search title fields with title query
-            query = title_value
-            search_fields = "title,alternative_titles"
-            search_weights = "5,1"
-            logger.debug(f"Title-only search: query='{query}', fields='{search_fields}'")
-        elif author_value and title_value:
-            # Both provided: combine into query, search both fields
-            query = f"{title_value} {author_value}"
-            search_fields = "title,alternative_titles,author_names"
-            search_weights = "5,1,3"
-            logger.debug(f"Combined search: query='{query}', fields='{search_fields}'")
-        else:
-            # No custom fields: use general query with all default fields
-            query = options.query
-            search_fields = None
-            search_weights = None
-            logger.debug(f"General search: query='{query}', no field restriction")
-
-        # Build GraphQL query with optional fields/weights parameters
-        if search_fields:
-            graphql_query = """
-            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String, $fields: String, $weights: String) {
-                search(
-                    query: $query,
-                    query_type: "Book",
-                    per_page: $limit,
-                    page: $page,
-                    sort: $sort,
-                    fields: $fields,
-                    weights: $weights
-                ) {
-                    results
-                }
-            }
-            """
-        else:
-            graphql_query = """
-            query SearchBooks($query: String!, $limit: Int!, $page: Int!, $sort: String) {
-                search(
-                    query: $query,
-                    query_type: "Book",
-                    per_page: $limit,
-                    page: $page,
-                    sort: $sort
-                ) {
-                    results
-                }
-            }
-            """
-
-        # Map abstract sort order to Hardcover's sort parameter
-        sort_param = SORT_MAPPING.get(options.sort, SORT_MAPPING[SortOrder.RELEVANCE])
-
-        variables = {
-            "query": query,
-            "limit": options.limit,
-            "page": options.page,
-            "sort": sort_param,
-        }
-
-        if search_fields:
-            variables["fields"] = search_fields
-            variables["weights"] = search_weights
-
-        logger.debug(f"GraphQL variables: {variables}")
-
-        try:
-            result = self._execute_query(graphql_query, variables)
-            if not result:
-                logger.debug("Hardcover search: No result from API")
-                return []
-
-            search_data = result.get("search", {})
-
-            # Results is a Typesense response object with hits array
-            results_obj = search_data.get("results", {})
-            if isinstance(results_obj, dict):
-                hits = results_obj.get("hits", [])
-            else:
-                hits = results_obj if isinstance(results_obj, list) else []
-
-            # Parse the search results - each hit has a 'document' field
-            books = []
-            for hit in hits:
-                # Get the document from the hit
-                item = hit.get("document", hit) if isinstance(hit, dict) else hit
-                if isinstance(item, dict):
-                    book = self._parse_search_result(item)
-                    if book:
-                        books.append(book)
-
-            logger.info(f"Hardcover search '{query}' (fields={search_fields}) returned {len(books)} results")
-            return books
-
-        except Exception as e:
-            logger.error(f"Hardcover search error: {e}")
-            return []
-
-    @cacheable(ttl_key="METADATA_CACHE_BOOK_TTL", ttl_default=600, key_prefix="hardcover:book")
-    def get_book(self, book_id: str) -> Optional[BookMetadata]:
-        """Get book details by Hardcover ID.
-
-        Args:
-            book_id: Hardcover book ID.
-
-        Returns:
-            BookMetadata or None if not found.
-        """
-        if not self.api_key:
-            logger.warning("Hardcover API key not configured")
-            return None
-
-        # Query for specific book by ID
-        # Note: API has max depth of 3, so use cached_* fields instead of nested relationships
-        graphql_query = """
-        query GetBook($id: Int!) {
-            books(where: {id: {_eq: $id}}, limit: 1) {
-                id
-                title
-                slug
-                release_date
-                headline
-                description
-                pages
-                cached_image
-                cached_contributors
-                cached_tags
-                default_physical_edition {
-                    isbn_10
-                    isbn_13
-                }
-            }
-        }
-        """
-
-        try:
-            book_id_int = int(book_id)
-            result = self._execute_query(graphql_query, {"id": book_id_int})
-            if not result:
-                return None
-
-            books = result.get("books", [])
-            if not books:
-                return None
-
-            return self._parse_book(books[0])
-
-        except ValueError:
-            logger.error(f"Invalid book ID: {book_id}")
-            return None
-        except Exception as e:
-            logger.error(f"Hardcover get_book error: {e}")
-            return None
-
-    @cacheable(ttl_key="METADATA_CACHE_BOOK_TTL", ttl_default=600, key_prefix="hardcover:isbn")
-    def search_by_isbn(self, isbn: str) -> Optional[BookMetadata]:
-        """Search for a book by ISBN.
-
-        Args:
-            isbn: ISBN-10 or ISBN-13.
-
-        Returns:
-            BookMetadata or None if not found.
-        """
-        if not self.api_key:
-            logger.warning("Hardcover API key not configured")
-            return None
-
-        # Clean ISBN (remove hyphens)
-        clean_isbn = isbn.replace("-", "").strip()
-
-        # Search for editions with matching ISBN
-        # Note: API has max depth of 3, so use cached_* fields instead of nested relationships
-        graphql_query = """
-        query SearchByISBN($isbn: String!) {
-            editions(
-                where: {
-                    _or: [
-                        {isbn_10: {_eq: $isbn}},
-                        {isbn_13: {_eq: $isbn}}
-                    ]
-                },
-                limit: 1
-            ) {
-                isbn_10
-                isbn_13
-                book {
-                    id
-                    title
-                    slug
-                    release_date
-                    headline
-                    description
-                    pages
-                    cached_image
-                    cached_contributors
-                    cached_tags
-                }
-            }
-        }
-        """
-
-        try:
-            result = self._execute_query(graphql_query, {"isbn": clean_isbn})
-            if not result:
-                return None
-
-            editions = result.get("editions", [])
-            if not editions:
-                logger.debug(f"No Hardcover book found for ISBN: {isbn}")
-                return None
-
-            edition = editions[0]
-            book_data = edition.get("book", {})
-            if not book_data:
-                return None
-
-            # Add ISBN data from edition to book data
-            book_data["isbn_10"] = edition.get("isbn_10")
-            book_data["isbn_13"] = edition.get("isbn_13")
-
-            return self._parse_book(book_data)
-
-        except Exception as e:
-            logger.error(f"Hardcover ISBN search error: {e}")
-            return None
-
-    def _execute_query(self, query: str, variables: Dict[str, Any]) -> Optional[Dict]:
-        """Execute a GraphQL query.
-
-        Args:
-            query: GraphQL query string.
-            variables: Query variables.
-
-        Returns:
-            Response data dict or None on error.
-        """
-        try:
-            response = self.session.post(
-                HARDCOVER_API_URL,
-                json={"query": query, "variables": variables},
-                timeout=15
-            )
-            response.raise_for_status()
-
-            data = response.json()
-
-            if "errors" in data:
-                logger.error(f"GraphQL errors: {data['errors']}")
-                return None
-
-            return data.get("data")
-
-        except requests.Timeout:
-            logger.warning("Hardcover API request timed out")
-            return None
-        except requests.HTTPError as e:
-            if e.response.status_code == 401:
-                logger.error("Hardcover API key is invalid")
-            else:
-                logger.error(f"Hardcover API HTTP error: {e}")
-            return None
-        except Exception as e:
-            logger.error(f"Hardcover API request failed: {e}")
-            return None
-
-    def _parse_search_result(self, item: Dict) -> Optional[BookMetadata]:
-        """Parse a search result item into BookMetadata.
-
-        Args:
-            item: Search result item dict.
-
-        Returns:
-            BookMetadata or None if parsing fails.
-        """
-        try:
-            book_id = item.get("id") or item.get("document", {}).get("id")
-            title = item.get("title") or item.get("document", {}).get("title")
-
-            if not book_id or not title:
-                return None
-
-            # Extract authors from various possible fields
-            authors = []
-            if "author_names" in item:
-                authors = item["author_names"] if isinstance(item["author_names"], list) else [item["author_names"]]
-            elif "cached_contributors" in item:
-                for contrib in item.get("cached_contributors", []):
-                    if isinstance(contrib, dict) and contrib.get("name"):
-                        authors.append(contrib["name"])
-                    elif isinstance(contrib, str):
-                        authors.append(contrib)
-
-            # Get cover URL
-            cover_url = None
-            if "image" in item and item["image"]:
-                cover_url = item["image"] if isinstance(item["image"], str) else item["image"].get("url")
-
-            # Extract year - prefer release_year if available, fall back to release_date
-            publish_year = None
-            if "release_year" in item and item["release_year"]:
-                try:
-                    publish_year = int(item["release_year"])
-                except (ValueError, TypeError):
-                    pass
-            elif "release_date" in item and item["release_date"]:
-                try:
-                    publish_year = int(str(item["release_date"])[:4])
-                except (ValueError, TypeError):
-                    pass
-
-            slug = item.get("slug", "")
-            source_url = f"https://hardcover.app/books/{slug}" if slug else None
-
-            # Build display fields from Hardcover-specific data
-            display_fields = []
-
-            # Rating (e.g., "4.5 (3,764)")
-            rating = item.get("rating")
-            ratings_count = item.get("ratings_count")
-            if rating is not None:
-                rating_str = f"{rating:.1f}"
-                if ratings_count:
-                    rating_str += f" ({ratings_count:,})"
-                display_fields.append(DisplayField(label="Rating", value=rating_str, icon="star"))
-
-            # Readers (users who have this book)
-            users_count = item.get("users_count")
-            if users_count:
-                display_fields.append(DisplayField(label="Readers", value=f"{users_count:,}", icon="users"))
-
-            # Combine headline and description if both present
-            headline = item.get("headline")
-            description = item.get("description")
-            full_description = _combine_headline_description(headline, description)
-
-            return BookMetadata(
-                provider="hardcover",
-                provider_id=str(book_id),
-                title=title,
-                provider_display_name="Hardcover",
-                authors=authors,
-                cover_url=cover_url,
-                description=full_description,
-                publish_year=publish_year,
-                source_url=source_url,
-                display_fields=display_fields,
-            )
-
-        except Exception as e:
-            logger.debug(f"Failed to parse Hardcover search result: {e}")
-            return None
-
-    def _parse_book(self, book: Dict) -> BookMetadata:
-        """Parse a book object into BookMetadata.
-
-        Args:
-            book: Book data dict from GraphQL response.
-
-        Returns:
-            BookMetadata object.
-        """
-        # Extract authors from cached_contributors (json array) or contributions relationship
-        authors = []
-        if book.get("cached_contributors"):
-            for contrib in book["cached_contributors"]:
-                if isinstance(contrib, dict) and contrib.get("name"):
-                    authors.append(contrib["name"])
-                elif isinstance(contrib, str):
-                    authors.append(contrib)
-        elif book.get("contributions"):
-            # Fallback for contributions relationship (if used)
-            for contrib in book["contributions"]:
-                author = contrib.get("author", {})
-                if author and author.get("name"):
-                    authors.append(author["name"])
-
-        # Get cover URL from cached_image (jsonb) or image relationship
-        cover_url = None
-        if book.get("cached_image"):
-            cached = book["cached_image"]
-            if isinstance(cached, dict):
-                cover_url = cached.get("url")
-            elif isinstance(cached, str):
-                cover_url = cached
-        elif book.get("image"):
-            img = book["image"]
-            cover_url = img if isinstance(img, str) else img.get("url")
-
-        # Extract year from release_date
-        publish_year = None
-        if book.get("release_date"):
-            try:
-                publish_year = int(str(book["release_date"])[:4])
-            except (ValueError, TypeError):
-                pass
-
-        # Extract genres from cached_tags
-        genres = []
-        for tag in book.get("cached_tags", []):
-            if isinstance(tag, dict) and tag.get("tag"):
-                genres.append(tag["tag"])
-            elif isinstance(tag, str):
-                genres.append(tag)
-
-        # Get ISBN from direct fields, default_physical_edition, or editions
-        isbn_10 = book.get("isbn_10")
-        isbn_13 = book.get("isbn_13")
-
-        if not isbn_10 and not isbn_13:
-            # Try default_physical_edition first
-            edition = book.get("default_physical_edition")
-            if edition:
-                isbn_10 = edition.get("isbn_10")
-                isbn_13 = edition.get("isbn_13")
-
-            # Fallback to editions array
-            if not isbn_10 and not isbn_13 and book.get("editions"):
-                for ed in book["editions"]:
-                    if not isbn_10 and ed.get("isbn_10"):
-                        isbn_10 = ed["isbn_10"]
-                    if not isbn_13 and ed.get("isbn_13"):
-                        isbn_13 = ed["isbn_13"]
-                    if isbn_10 and isbn_13:
-                        break
-
-        slug = book.get("slug", "")
-        source_url = f"https://hardcover.app/books/{slug}" if slug else None
-
-        # Combine headline and description if both present
-        headline = book.get("headline")
-        description = book.get("description")
-        full_description = _combine_headline_description(headline, description)
-
-        return BookMetadata(
-            provider="hardcover",
-            provider_id=str(book["id"]),
-            title=book["title"],
-            provider_display_name="Hardcover",
-            authors=authors,
-            isbn_10=isbn_10,
-            isbn_13=isbn_13,
-            cover_url=cover_url,
-            description=full_description,
-            publish_year=publish_year,
-            genres=genres,
-            source_url=source_url,
-        )
-
-
-def _test_hardcover_connection() -> Dict[str, Any]:
-    """Test the Hardcover API connection."""
-    from cwa_book_downloader.core.config import config as app_config
-    from cwa_book_downloader.core.settings_registry import save_config_file, load_config_file
-    from cwa_book_downloader.metadata_providers import get_provider_kwargs
-
-    # Refresh config to pick up any recently saved settings
-    app_config.refresh()
-
-    kwargs = get_provider_kwargs("hardcover")
-    api_key = kwargs.get("api_key")
-
-    # Debug: log key info
-    key_len = len(api_key) if api_key else 0
-    key_preview = f"{api_key[:10]}...{api_key[-10:]}" if key_len > 20 else "(too short)"
-    logger.info(f"Hardcover test: key length={key_len}, preview={key_preview}")
-
-    if not api_key:
-        # Clear any stored username since there's no key
-        _save_connected_username(None)
-        return {"success": False, "message": "No API key configured. Save your key and try again."}
-
-    if key_len < 100:
-        return {"success": False, "message": f"API key seems too short ({key_len} chars). Expected 500+ chars."}
-
-    try:
-        provider = HardcoverProvider(api_key=api_key)
-        # Use the 'me' query to test connection (recommended by API docs)
-        result = provider._execute_query(
-            "query { me { id, username } }",
-            {}
-        )
-        if result is not None:
-            # Handle both single object and array response formats
-            me_data = result.get("me", {})
-            if isinstance(me_data, list) and me_data:
-                me_data = me_data[0]
-            username = me_data.get("username", "Unknown") if isinstance(me_data, dict) else "Unknown"
-
-            # Save the username for persistent display
-            _save_connected_username(username)
-
-            return {"success": True, "message": f"Connected as: {username}"}
-        else:
-            _save_connected_username(None)
-            return {"success": False, "message": "API request failed - check your API key"}
-    except Exception as e:
-        logger.exception("Hardcover connection test failed")
-        _save_connected_username(None)
-        return {"success": False, "message": f"Connection failed: {str(e)}"}
-
-
-def _save_connected_username(username: Optional[str]) -> None:
-    """Save or clear the connected username in config."""
-    from cwa_book_downloader.core.settings_registry import save_config_file, load_config_file
-
-    config = load_config_file("hardcover")
-    if username:
-        config["_connected_username"] = username
-    else:
-        config.pop("_connected_username", None)
-    save_config_file("hardcover", config)
-
-
-def _get_connected_username() -> Optional[str]:
-    """Get the stored connected username."""
-    from cwa_book_downloader.core.settings_registry import load_config_file
-
-    config = load_config_file("hardcover")
-    return config.get("_connected_username")
-
-
-# Hardcover sort options for settings UI
-_HARDCOVER_SORT_OPTIONS = [
-    {"value": "relevance", "label": "Most relevant"},
-    {"value": "popularity", "label": "Most popular"},
-    {"value": "rating", "label": "Highest rated"},
-    {"value": "newest", "label": "Newest"},
-    {"value": "oldest", "label": "Oldest"},
-]
-
-
-@register_settings("hardcover", "Hardcover", icon="book", order=51, group="metadata_providers")
-def hardcover_settings():
-    """Hardcover metadata provider settings."""
-    # Check for connected username to show status
-    connected_user = _get_connected_username()
-    test_button_description = f"Connected as: {connected_user}" if connected_user else "Verify your API key works"
-
-    return [
-        HeadingField(
-            key="hardcover_heading",
-            title="Hardcover",
-            description="A modern book tracking and discovery platform with a comprehensive API.",
-            link_url="https://hardcover.app",
-            link_text="hardcover.app",
-        ),
-        CheckboxField(
-            key="HARDCOVER_ENABLED",
-            label="Enable Hardcover",
-            description="Enable Hardcover as a metadata provider for book searches",
-            default=False,
-        ),
-        PasswordField(
-            key="HARDCOVER_API_KEY",
-            label="API Key",
-            description="Get your API key from hardcover.app/account/api",
-            required=True,
-            env_supported=False,  # UI-only setting, no ENV var support
-        ),
-        ActionButton(
-            key="test_connection",
-            label="Test Connection",
-            description=test_button_description,
-            style="primary",
-            callback=_test_hardcover_connection,
-        ),
-        SelectField(
-            key="HARDCOVER_DEFAULT_SORT",
-            label="Default Sort Order",
-            description="Default sort order for Hardcover search results.",
-            options=_HARDCOVER_SORT_OPTIONS,
-            default="relevance",
-            env_supported=False,  # UI-only setting
-        ),
-    ]

cwa_book_downloader/release_sources/__init__.py

@@ -1,340 +0,0 @@
-"""Release source plugin system - base classes and registry."""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field, asdict
-from enum import Enum
-from threading import Event
-from typing import List, Optional, Dict, Type, Callable, Literal, Any
-
-from cwa_book_downloader.core.models import DownloadTask
-from cwa_book_downloader.metadata_providers import BookMetadata
-
-
-class ReleaseProtocol(str, Enum):
-    """Protocol for downloading a release."""
-    HTTP = "http"       # Direct HTTP download
-    TORRENT = "torrent" # BitTorrent
-    NZB = "nzb"         # Usenet NZB
-    DCC = "dcc"         # IRC DCC
-
-
-@dataclass
-class Release:
-    """A downloadable release - all sources return this same structure."""
-    source: str                      # "direct", "prowlarr", "irc", etc.
-    source_id: str                   # ID within that source
-    title: str
-    format: Optional[str] = None
-    language: Optional[str] = None   # ISO 639-1 code (e.g., "en", "de", "fr")
-    size: Optional[str] = None
-    size_bytes: Optional[int] = None
-    download_url: Optional[str] = None
-    info_url: Optional[str] = None   # Link to release info page (e.g., tracker) - makes title clickable
-    protocol: Optional[ReleaseProtocol] = None
-    indexer: Optional[str] = None    # Source name for display
-    seeders: Optional[int] = None    # For torrents
-    peers: Optional[str] = None      # For torrents: "seeders/leechers" display string
-    extra: Dict = field(default_factory=dict)  # Source-specific metadata
-
-
-@dataclass
-class DownloadProgress:
-    """Progress update structure.
-
-    DEPRECATED: This class is deprecated and will be removed.
-    The new DownloadHandler.download() uses simpler callbacks:
-    - progress_callback(float) for progress percentage
-    - status_callback(str, Optional[str]) for status and message
-    """
-    status: str                      # "queued", "resolving", "downloading", "complete", "failed"
-    progress: float                  # 0-100
-    status_message: Optional[str] = None
-    download_speed: Optional[int] = None
-    eta: Optional[int] = None
-    save_path: Optional[str] = None
-
-
-# --- Column Schema for Plugin-Driven UI ---
-
-class ColumnRenderType(str, Enum):
-    """How the frontend should render the column value."""
-    TEXT = "text"           # Plain text
-    BADGE = "badge"         # Colored badge (format, language)
-    SIZE = "size"           # File size formatting
-    NUMBER = "number"       # Numeric value
-    PEERS = "peers"         # Peers display: "S/L" with color based on seeder count
-
-
-class ColumnAlign(str, Enum):
-    """Column alignment options."""
-    LEFT = "left"
-    CENTER = "center"
-    RIGHT = "right"
-
-
-@dataclass
-class ColumnColorHint:
-    """Color hint for badge-type columns."""
-    type: Literal["map", "static"]   # "map" uses frontend colorMaps, "static" is fixed class
-    value: str                        # Map name ("format", "language") or Tailwind class
-
-
-@dataclass
-class ColumnSchema:
-    """Definition for a single column in the release list."""
-    key: str                                      # Data path (e.g., "format", "extra.language")
-    label: str                                    # Accessibility label
-    render_type: ColumnRenderType = ColumnRenderType.TEXT
-    align: ColumnAlign = ColumnAlign.LEFT
-    width: str = "auto"                           # CSS width (e.g., "80px", "minmax(0,2fr)")
-    hide_mobile: bool = False                     # Hide on small screens
-    color_hint: Optional[ColumnColorHint] = None  # For BADGE render type
-    fallback: str = "-"                           # Value to show when data is missing
-    uppercase: bool = False                       # Force uppercase display
-
-
-class LeadingCellType(str, Enum):
-    """Type of leading cell to display in release rows."""
-    THUMBNAIL = "thumbnail"  # Show book cover image
-    BADGE = "badge"          # Show colored badge (e.g., "Torrent", "Usenet")
-    NONE = "none"            # No leading cell
-
-
-@dataclass
-class LeadingCellConfig:
-    """Configuration for the leading cell in release rows."""
-    type: LeadingCellType = LeadingCellType.THUMBNAIL
-    key: Optional[str] = None                     # Field path for data (e.g., "extra.preview" or "extra.download_type")
-    color_hint: Optional[ColumnColorHint] = None  # For badge type - maps values to colors
-    uppercase: bool = False                       # Force uppercase for badge text
-
-
-@dataclass
-class ReleaseColumnConfig:
-    """Complete column configuration for a release source."""
-    columns: List[ColumnSchema]
-    grid_template: str = "minmax(0,2fr) 60px 80px 80px"  # CSS grid-template-columns
-    leading_cell: Optional[LeadingCellConfig] = None     # Defaults to thumbnail mode if None
-
-
-def serialize_column_config(config: ReleaseColumnConfig) -> Dict[str, Any]:
-    """Serialize column configuration for API response."""
-    result: Dict[str, Any] = {
-        "columns": [
-            {
-                "key": col.key,
-                "label": col.label,
-                "render_type": col.render_type.value,
-                "align": col.align.value,
-                "width": col.width,
-                "hide_mobile": col.hide_mobile,
-                "color_hint": {
-                    "type": col.color_hint.type,
-                    "value": col.color_hint.value
-                } if col.color_hint else None,
-                "fallback": col.fallback,
-                "uppercase": col.uppercase,
-            }
-            for col in config.columns
-        ],
-        "grid_template": config.grid_template,
-    }
-
-    # Include leading_cell config if specified
-    if config.leading_cell:
-        result["leading_cell"] = {
-            "type": config.leading_cell.type.value,
-            "key": config.leading_cell.key,
-            "color_hint": {
-                "type": config.leading_cell.color_hint.type,
-                "value": config.leading_cell.color_hint.value
-            } if config.leading_cell.color_hint else None,
-            "uppercase": config.leading_cell.uppercase,
-        }
-
-    return result
-
-
-def _default_column_config() -> ReleaseColumnConfig:
-    """Default column configuration used when source doesn't define its own."""
-    return ReleaseColumnConfig(
-        columns=[
-            ColumnSchema(
-                key="extra.language",
-                label="Language",
-                render_type=ColumnRenderType.BADGE,
-                align=ColumnAlign.CENTER,
-                width="60px",
-                hide_mobile=False,  # Language shown on mobile
-                color_hint=ColumnColorHint(type="map", value="language"),
-                uppercase=True,
-            ),
-            ColumnSchema(
-                key="format",
-                label="Format",
-                render_type=ColumnRenderType.BADGE,
-                align=ColumnAlign.CENTER,
-                width="80px",
-                hide_mobile=False,  # Format shown on mobile
-                color_hint=ColumnColorHint(type="map", value="format"),
-                uppercase=True,
-            ),
-            ColumnSchema(
-                key="size",
-                label="Size",
-                render_type=ColumnRenderType.SIZE,
-                align=ColumnAlign.CENTER,
-                width="80px",
-                hide_mobile=False,  # Size shown on mobile
-            ),
-        ],
-        grid_template="minmax(0,2fr) 60px 80px 80px"
-    )
-
-
-class ReleaseSource(ABC):
-    """Interface for searching a release source."""
-    name: str                        # "direct", "prowlarr"
-    display_name: str                # "Direct Download", "Prowlarr"
-
-    @abstractmethod
-    def search(self, book: BookMetadata) -> List[Release]:
-        """Search for releases of a book."""
-        pass
-
-    @abstractmethod
-    def is_available(self) -> bool:
-        """Check if this source is configured and reachable."""
-        pass
-
-    @classmethod
-    def get_column_config(cls) -> ReleaseColumnConfig:
-        """Get the column configuration for this source's release list UI.
-
-        Override this method in subclasses to provide custom columns.
-        Default implementation returns standard columns (language, format, size).
-        """
-        return _default_column_config()
-
-
-class DownloadHandler(ABC):
-    """Interface for executing downloads from a source.
-
-    ## Staging Architecture
-
-    Handlers are responsible for getting files into the STAGING directory (TMP_DIR).
-    The orchestrator handles all post-processing and moving to the INGEST directory.
-
-    This means handlers should:
-    1. Download/retrieve the file to the staging directory
-    2. Return the path to the staged file
-    3. NOT move files to the ingest folder (orchestrator does this)
-
-    Examples by source type:
-    - **Direct downloads**: Download directly to staging dir
-    - **Torrents**: Copy completed file from torrent client to staging (keep seeding)
-    - **Usenet**: Move completed file from NZB client to staging
-
-    Use the staging helpers from orchestrator:
-    - `get_staging_dir()` - Get the staging directory path
-    - `get_staging_path(task_id, ext)` - Get a staging path for a task
-    - `stage_file(source, task_id, copy=False)` - Stage a file (copy or move)
-
-    The orchestrator then handles:
-    - Archive extraction (RAR/ZIP)
-    - Custom script execution
-    - Moving to the final ingest folder
-    """
-
-    @abstractmethod
-    def download(
-        self,
-        task: DownloadTask,
-        cancel_flag: Event,
-        progress_callback: Callable[[float], None],
-        status_callback: Callable[[str, Optional[str]], None]
-    ) -> Optional[str]:
-        """
-        Execute download and return path to STAGED file.
-
-        Handlers should download/copy files to the staging directory (TMP_DIR),
-        NOT directly to the ingest folder. The orchestrator handles post-processing
-        (archive extraction, custom scripts) and final move to ingest.
-
-        Args:
-            task: The download task with task_id and display info
-            cancel_flag: Event to check for cancellation
-            progress_callback: Called with progress percentage (0-100)
-            status_callback: Called with (status, message) for status updates
-
-        Returns:
-            Path to staged file (in TMP_DIR) if successful, None otherwise
-        """
-        pass
-
-    @abstractmethod
-    def cancel(self, task_id: str) -> bool:
-        """Cancel an in-progress download."""
-        pass
-
-
-# --- Registry ---
-
-_SOURCES: Dict[str, Type[ReleaseSource]] = {}
-_HANDLERS: Dict[str, Type[DownloadHandler]] = {}
-
-
-def register_source(name: str):
-    """Decorator to register a release source."""
-    def decorator(cls):
-        _SOURCES[name] = cls
-        return cls
-    return decorator
-
-
-def register_handler(name: str):
-    """Decorator to register a download handler."""
-    def decorator(cls):
-        _HANDLERS[name] = cls
-        return cls
-    return decorator
-
-
-def get_source(name: str) -> ReleaseSource:
-    """Get a release source instance by name."""
-    if name not in _SOURCES:
-        raise ValueError(f"Unknown release source: {name}")
-    return _SOURCES[name]()
-
-
-def get_handler(name: str) -> DownloadHandler:
-    """Get a download handler instance by name."""
-    if name not in _HANDLERS:
-        raise ValueError(f"Unknown download handler: {name}")
-    return _HANDLERS[name]()
-
-
-def list_available_sources() -> List[dict]:
-    """For frontend - list sources that are configured."""
-    return [
-        {"name": name, "display_name": src().display_name}
-        for name, src in _SOURCES.items()
-        if src().is_available()
-    ]
-
-
-def get_source_display_name(name: str) -> str:
-    """Get display name for a source by its identifier.
-
-    Falls back to title-cased name if source not found.
-    """
-    if name in _SOURCES:
-        return _SOURCES[name]().display_name
-    # Fallback: convert snake_case to Title Case
-    return name.replace('_', ' ').title()
-
-
-# Import source implementations to trigger registration
-# These must be imported AFTER the base classes and registry are defined
-from cwa_book_downloader.release_sources import direct_download  # noqa: F401, E402
-# from cwa_book_downloader.release_sources import prowlarr  # noqa: F401, E402

docker-compose.bypass-test.yml

@@ -0,0 +1,39 @@
+# Bypass testing - switch between dev build and v1.0.1
+# Usage:
+#   Test dev build:  docker compose -f docker-compose.bypass-test.yml up shelfmark-dev
+#   Test v1.0.1:     docker compose -f docker-compose.bypass-test.yml up shelfmark-stable
+#   Pull latest dev: docker compose -f docker-compose.bypass-test.yml build shelfmark-dev
+#   Pull v1.0.1:     docker compose -f docker-compose.bypass-test.yml pull shelfmark-stable
+
+services:
+  # Dev image from registry
+  shelfmark-dev:
+    image: ghcr.io/calibrain/shelfmark:dev
+    container_name: shelfmark-bypass-dev
+    environment:
+      PUID: 1000
+      PGID: 1000
+      DEBUG: true
+    ports:
+      - 8084:8084
+    volumes:
+      - ./.local/bypass-test/config-dev:/config
+      - ./.local/bypass-test/books:/books
+      - ./.local/bypass-test/log-dev:/var/log/shelfmark
+      - ./.local/bypass-test/tmp:/tmp/shelfmark
+
+  # Stable v1.0.1 for comparison
+  shelfmark-stable:
+    image: ghcr.io/calibrain/shelfmark:1.0.1
+    container_name: shelfmark-bypass-stable
+    environment:
+      PUID: 1000
+      PGID: 1000
+      DEBUG: true
+    ports:
+      - 8085:8084
+    volumes:
+      - ./.local/bypass-test/config-stable:/config
+      - ./.local/bypass-test/books:/books
+      - ./.local/bypass-test/log-stable:/var/log/shelfmark
+      - ./.local/bypass-test/tmp:/tmp/shelfmark

docker-compose.dev.extbp.yml

@@ -0,0 +1,25 @@
+# Local development - External bypasser variant (lite)
+services:
+  shelfmark-lite-dev:
+    extends:
+      file: ./compose/docker-compose.lite.yml
+      service: shelfmark-lite
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: shelfmark-lite
+    environment:
+      DEBUG: true
+      EXT_BYPASSER_URL: http://flaresolverr:8191
+      EXT_BYPASSER_PATH: /v1
+      EXT_BYPASSER_TIMEOUT: 60000
+    volumes:
+      - ./.local/config:/config
+      - ./.local/books:/books
+      - ./.local/log:/var/log/shelfmark
+      - ./.local/tmp:/tmp/shelfmark
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads
+
+  flaresolverr:
+    image: ghcr.io/flaresolverr/flaresolverr:latest

docker-compose.dev.tor.yml

@@ -0,0 +1,20 @@
+# Local development - Tor variant
+services:
+  shelfmark-tor-dev:
+    extends:
+      file: ./compose/docker-compose.tor.yml
+      service: shelfmark-tor
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: shelfmark
+    environment:
+      DEBUG: true
+      USING_TOR: true
+    volumes:
+      - ./.local/config:/config
+      - ./.local/books:/books
+      - ./.local/log:/var/log/shelfmark
+      - ./.local/tmp:/tmp/shelfmark
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

docker-compose.dev.yml

@@ -1,17 +1,24 @@
 # Local development - builds from source with debug enabled
 services:
-  calibre-web-automated-book-downloader-dev:
+  shelfmark-dev:
     extends:
-      file: ./docker-compose.yml
-      service: calibre-web-automated-book-downloader
+      file: ./compose/docker-compose.yml
+      service: shelfmark
     build:
       context: .
       dockerfile: Dockerfile
-      target: cwa-bd
+      target: shelfmark
+    cap_add:
+      - SYS_PTRACE
     environment:
       DEBUG: true
+      # HIDE_LOCAL_AUTH: true
+      OIDC_AUTO_REDIRECT: true
     volumes:
       - ./.local/config:/config
-      - ./.local/ingest:/cwa-book-ingest
-      - ./.local/log:/var/log/cwa-book-downloader
-      - ./.local/tmp:/tmp/cwa-book-downloader
+      - ./.local/books:/books
+      - ./.local/log:/var/log/shelfmark
+      - ./.local/tmp:/tmp/shelfmark
+      - ./shelfmark:/app/shelfmark:ro
+      # Required for torrent / usenet - path must match your download client's volume exactly
+      # - /path/to/downloads:/path/to/downloads

docker-compose.extbp.dev.yml

@@ -1,23 +0,0 @@
-# Local development - External bypasser variant
-services:
-  calibre-web-automated-book-downloader-extbp-dev:
-    extends:
-      file: ./docker-compose.extbp.yml
-      service: calibre-web-automated-book-downloader-extbp
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: cwa-bd-extbp
-    environment:
-      DEBUG: true
-      EXT_BYPASSER_URL: http://flaresolverr:8191
-      EXT_BYPASSER_PATH: /v1
-      EXT_BYPASSER_TIMEOUT: 60000
-    volumes:
-      - ./.local/config:/config
-      - ./.local/ingest:/cwa-book-ingest
-      - ./.local/log:/var/log/cwa-book-downloader
-      - ./.local/tmp:/tmp/cwa-book-downloader
-
-  flaresolverr:
-    image: ghcr.io/flaresolverr/flaresolverr:latest

docker-compose.extbp.yml

@@ -1,20 +0,0 @@
-# Uses external Cloudflare bypasser (FlareSolverr/ByParr) instead of built-in Selenium
-services:
-  calibre-web-automated-book-downloader-extbp:
-    image: ghcr.io/calibrain/calibre-web-automated-book-downloader-extbp:latest
-    environment:
-      TZ: America/New_York
-      EXT_BYPASSER_URL: http://flaresolverr:8191
-      # UID: 1000
-      # GID: 100
-      # CWA_DB_PATH: /auth/app.db
-    ports:
-      - 8084:8084
-    restart: unless-stopped
-    volumes:
-      - /tmp/data/calibre-web/ingest:/cwa-book-ingest
-      - /path/to/config:/config
-      # - /cwa/config/path/app.db:/auth/app.db:ro
-
-  flaresolverr:
-    image: ghcr.io/flaresolverr/flaresolverr:latest

docker-compose.test-clients.yml

@@ -0,0 +1,181 @@
+# Test stack for download client development
+# Includes shelfmark + all download clients on same network with shared volumes
+#
+# Usage:
+#   docker compose -f docker-compose.test-clients.yml up -d
+#   # Access shelfmark at http://localhost:8084
+#   # Configure clients in Settings > Prowlarr > Download Clients
+#
+# Web UIs:
+#   - shelfmark:    http://localhost:8084
+#   - Prowlarr:     http://localhost:9696 (no auth by default)
+#   - qBittorrent:  http://localhost:8080 (check container logs for temp password)
+#   - Transmission: http://localhost:9091 (admin / admin)
+#   - Deluge:       http://localhost:8112 (password: deluge)
+#   - NZBGet:       http://localhost:6789 (nzbget / tegbzn6789)
+#   - SABnzbd:      http://localhost:8085 (complete setup wizard for API key)
+#   - rTorrent:     http://localhost:8000 (admin / admin - if auth enabled)
+#
+
+services:
+  shelfmark:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: shelfmark
+    container_name: test-shelfmark
+    cap_add:
+      - SYS_PTRACE
+    environment:
+      TZ: UTC
+      DEBUG: "true"
+      # All client configuration is done via Settings UI
+      # Use Docker service names for URLs:
+      #   - qBittorrent: http://qbittorrent:8080
+      #   - Transmission: http://transmission:9091
+      #   - Deluge Web UI: http://deluge:8112
+      #   - NZBGet: http://nzbget:6789
+      #   - SABnzbd: http://sabnzbd:8080
+      #   - rTorrent: http://rtorrent:80 (XMLRPC via HTTP) or rtorrent (port 5000 for SCGI)
+    ports:
+      - "8084:8084"
+    volumes:
+      # Config and state
+      - ./.local/test-clients/shelfmark/config:/config
+      - ./.local/test-clients/shelfmark/log:/var/log/shelfmark
+      # Book destination directory (where completed books go)
+      - ./.local/test-clients/books:/books
+      # Staging directory
+      - ./.local/test-clients/tmp:/tmp/shelfmark
+      # CRITICAL: Mount client download directories so shelfmark can access completed files
+      - ./.local/test-clients/downloads:/downloads
+      # Mount source code for hot-reload (no rebuild needed for Python changes)
+      - ./shelfmark:/app/shelfmark:ro
+      # Mount tests for running pytest in container
+      - ./tests:/app/tests:ro
+      - ./pyproject.toml:/app/pyproject.toml:ro
+      # Mount client configs for integration tests to read credentials
+      - ./.local/test-clients/qbittorrent/config:/qbittorrent-config:ro
+      - ./.local/test-clients/sabnzbd/config:/sabnzbd-config:ro
+    depends_on:
+      - nzbget
+      - sabnzbd
+      - qbittorrent
+      - transmission
+      - deluge
+      - rtorrent
+    restart: unless-stopped
+
+  prowlarr:
+    image: lscr.io/linuxserver/prowlarr:latest
+    container_name: test-prowlarr
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+    volumes:
+      - ./.local/test-clients/prowlarr/config:/config
+    ports:
+      - "9696:9696"
+    restart: unless-stopped
+
+  nzbget:
+    image: lscr.io/linuxserver/nzbget:latest
+    container_name: test-nzbget
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+    volumes:
+      - ./.local/test-clients/nzbget/config:/config
+      - ./.local/test-clients/downloads:/downloads
+      - ./.local/test-clients/nzbget/custom-cont-init.d:/custom-cont-init.d:ro
+    ports:
+      - "6789:6789"  # Web UI / JSON-RPC
+    restart: unless-stopped
+
+  sabnzbd:
+    image: lscr.io/linuxserver/sabnzbd:latest
+    container_name: test-sabnzbd
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+    volumes:
+      - ./.local/test-clients/sabnzbd/config:/config
+      - ./.local/test-clients/downloads:/downloads
+    ports:
+      - "8085:8080"  # Web UI (external:internal)
+    restart: unless-stopped
+
+  qbittorrent:
+    image: lscr.io/linuxserver/qbittorrent:latest
+    container_name: test-qbittorrent
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+      - WEBUI_PORT=8080
+    volumes:
+      - ./.local/test-clients/qbittorrent/config:/config
+      - ./.local/test-clients/downloads:/downloads
+      - ./.local/test-clients/qbittorrent/custom-cont-init.d:/custom-cont-init.d:ro
+    ports:
+      - "8080:8080"  # Web UI / API
+      - "6882:6881"
+      - "6882:6881/udp"
+    restart: unless-stopped
+
+  transmission:
+    image: lscr.io/linuxserver/transmission:latest
+    container_name: test-transmission
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+      - USER=admin
+      - PASS=admin
+    volumes:
+      - ./.local/test-clients/transmission/config:/config
+      - ./.local/test-clients/downloads:/downloads
+    ports:
+      - "9091:9091"  # Web UI / RPC
+      - "51413:51413"
+      - "51413:51413/udp"
+    restart: unless-stopped
+
+  deluge:
+    image: lscr.io/linuxserver/deluge:latest
+    container_name: test-deluge
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+      - DELUGE_LOGLEVEL=error
+    volumes:
+      - ./.local/test-clients/deluge/config:/config
+      - ./.local/test-clients/downloads:/downloads
+    ports:
+      - "8112:8112"  # Web UI
+      - "58846:58846"  # Daemon RPC
+      - "6881:6881"
+      - "6881:6881/udp"
+    restart: unless-stopped
+
+  rtorrent:
+    image: crazymax/rtorrent-rutorrent:latest # linuxserver has deprecated their rtorrent image
+    container_name: test-rtorrent
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+    volumes:
+      - ./.local/test-clients/rtorrent/config:/config
+      - ./.local/test-clients/downloads:/downloads
+    ports:
+      - "8000:8000"  # XMLRPC
+      - "8089:8080"  # ruTorrent Web UI
+      - "9000:9000"  # SCGI port
+      - "50000:50000"  # Incoming connections
+      - "6881:6881/udp"
+    restart: unless-stopped

docker-compose.tor.dev.yml

@@ -1,17 +0,0 @@
-# Local development - Tor variant
-services:
-  calibre-web-automated-book-downloader-tor-dev:
-    extends:
-      file: ./docker-compose.tor.yml
-      service: calibre-web-automated-book-downloader-tor
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: cwa-bd-tor
-    environment:
-      DEBUG: true
-    volumes:
-      - ./.local/config:/config
-      - ./.local/ingest:/cwa-book-ingest
-      - ./.local/log:/var/log/cwa-book-downloader
-      - ./.local/tmp:/tmp/cwa-book-downloader

docker-compose.tor.yml

@@ -1,19 +0,0 @@
-# Routes all traffic through Tor - requires NET_ADMIN capability
-services:
-  calibre-web-automated-book-downloader-tor:
-    image: ghcr.io/calibrain/calibre-web-automated-book-downloader-tor:latest
-    environment:
-      FLASK_PORT: 8084
-      TZ: America/New_York
-      USING_TOR: true
-      # CWA_DB_PATH: /auth/app.db
-    cap_add:
-      - NET_ADMIN
-      - NET_RAW
-    ports:
-      - 8084:8084
-    restart: unless-stopped
-    volumes:
-      - /tmp/data/calibre-web/ingest:/cwa-book-ingest
-      - /path/to/config:/config
-      # - /cwa/config/path/app.db:/auth/app.db:ro

docker-compose.yml

@@ -1,15 +0,0 @@
-services:
-  calibre-web-automated-book-downloader:
-    image: ghcr.io/calibrain/calibre-web-automated-book-downloader:latest
-    container_name: calibre-web-automated-book-downloader
-    environment:
-      TZ: America/New_York
-      # UID: 1000
-      # GID: 100
-      # CWA_DB_PATH: /auth/app.db
-    ports:
-      - 8084:8084
-    restart: unless-stopped
-    volumes:
-      - /tmp/data/calibre-web/ingest:/cwa-book-ingest # This is where the books will be downloaded and ingested by your book management application
-      - /path/to/config:/config # Configuration files and database

docs/configuration.md

@@ -0,0 +1,125 @@
+# Directory and Volume Setup
+
+This guide explains how to configure directories and Docker volumes for Shelfmark. It focuses on the difference between the destination folder and your download client paths, and how to make those paths line up inside containers.
+
+## Conceptual Overview
+
+```
+DIRECT DOWNLOADS
+
+Shelfmark downloads directly -> destination
+
+TORRENT / USENET
+
+Prowlarr -> Download client saves to <client path>
+         -> Shelfmark reads from <client path>
+         -> Shelfmark processes to destination
+```
+
+Key point: For torrent and usenet downloads, Shelfmark must see the same file path that your download client reports. The container path must match in both containers.
+
+## Direct Download Setup
+
+Direct downloads do not use an external download client. A simple two-folder setup is enough.
+
+Required volumes:
+
+| Container path | Purpose | Notes |
+| --- | --- | --- |
+| `/config` | Settings, database, cover cache | Configurable via `CONFIG_DIR` |
+| `/books` | Destination folder for completed files | Configurable via `INGEST_DIR` and Settings -> Downloads -> Destination |
+
+Example `docker-compose`:
+
+```yaml
+services:
+  shelfmark:
+    image: ghcr.io/calibrain/shelfmark:latest
+    volumes:
+      - /path/to/config:/config
+      - /path/to/books:/books
+```
+
+Notes:
+- Point `/books` to your library ingest folder (Calibre-Web, Booklore, Audiobookshelf, etc) for automatic import.
+- If you set Books Output Mode to Booklore (API), books are uploaded via API instead of written to `/books`. Audiobooks still use a destination folder.
+- Ensure `PUID`/`PGID` (or legacy `UID`/`GID`) match the owner of the host directories to avoid permission errors.
+
+## Torrent / Usenet Setup
+
+For torrents and usenet, your download client reports a path (for example `/data/torrents/books/MyBook.epub`). Shelfmark must be able to read that exact path inside its own container.
+
+Required volumes:
+
+| Container path | Purpose | Notes |
+| --- | --- | --- |
+| `/config` | Settings, database, cover cache | Configurable via `CONFIG_DIR` |
+| `/books` | Destination folder for processed files | Configurable via `INGEST_DIR` |
+| `<client path>` | Download client path | Must match the download client container path exactly |
+
+Side-by-side example with qBittorrent:
+
+```yaml
+services:
+  shelfmark:
+    volumes:
+      - /path/to/config:/config
+      - /path/to/books:/books
+      - /path/to/downloads:/data/torrents  # Must match client
+
+  qbittorrent:
+    volumes:
+      - /path/to/downloads:/data/torrents  # Same container path
+```
+
+Host paths can be anything. The container path (for example `/data/torrents`) must be identical in both containers.
+
+### Remote Path Mappings
+
+If paths cannot match (different machines or a fixed setup), use Remote Path Mappings.
+
+Where to configure:
+- Settings -> Advanced -> Remote Path Mappings
+
+Example:
+- Client reports `/data/torrents/books/...`
+- Shelfmark can see the same files at `/downloads/books/...`
+- Add a mapping from Remote Path `/data/torrents` to Local Path `/downloads`
+
+## File Processing Options
+
+### Transfer Method (Torrent / Usenet Only)
+
+Available methods:
+- Copy (default). Works everywhere.
+- Hardlink. Preserves seeding without duplicating files.
+
+Hardlink requirements and behavior:
+- Source and destination must be on the same filesystem.
+- If hardlinking is enabled but not possible, Shelfmark falls back to copying.
+- Archive extraction is disabled while hardlinking is enabled.
+- Do not use hardlinking if your destination is a library ingest folder.
+
+### File Organization
+
+Shelfmark supports three organization modes for the destination:
+- None. Keep original filenames from the source.
+- Rename Only. Rename files using a template.
+- Rename and Organize. Create folders and rename using templates. Do not use with ingest folders.
+
+Configure templates in Settings -> Downloads. Template syntax details are documented separately.
+
+## Common Mistakes
+
+- "Download failed - file not found": Path mismatch between Shelfmark and the download client. Ensure container paths match or use Remote Path Mappings.
+- "Permission denied": `PUID`/`PGID` do not match the host directories. Ensure Shelfmark can read the client path and write to the destination.
+- "Hardlinks not working" or "Files being copied instead": Source and destination are on different filesystems. Move the destination or accept copy fallback.
+- "Downloads work but library does not see them": Destination does not point to the library ingest folder. Check Settings -> Downloads -> Destination.
+- CIFS/SMB shares: Use the `nobrl` mount option to avoid database lock errors. Example: `//server/share /mnt/share cifs nobrl,... 0 0`
+
+## Related Documentation
+
+- Environment Variables Reference: `docs/environment-variables.md`
+- Custom Scripts: `docs/custom-scripts.md`
+- Installation: `docs/installation.md`
+- Troubleshooting: `docs/troubleshooting.md`

docs/custom-scripts.md

@@ -0,0 +1,184 @@
+# Custom Scripts
+
+Shelfmark can run an executable you provide after a download task completes successfully. The script runs after the selected output has finished (for example: transfer to the folder destination, or upload to Booklore).
+
+
+## Quick Start (Recommended)
+
+1. Put your script on the machine that runs Shelfmark.
+1. Make it executable.
+1. Set it in Shelfmark (Settings -> Advanced -> Custom Script Path).
+
+Example:
+
+```bash
+chmod +x /path/to/your/scripts/post_process.sh
+```
+
+### Docker Users
+
+If you run Shelfmark in Docker, the script must exist inside the container. The easiest way is to mount a folder of scripts, then point Shelfmark at the container path in the UI.
+
+```yaml
+services:
+  shelfmark:
+    image: ghcr.io/calibrain/shelfmark:latest
+    volumes:
+      - /path/to/your/scripts:/scripts:ro
+```
+
+Then set:
+
+- Settings -> Advanced -> Custom Script Path: `/scripts/post_process.sh`
+
+<details>
+<summary>Docker Compose: Configure Via Environment Variables (Optional)</summary>
+
+```yaml
+services:
+  shelfmark:
+    environment:
+      - CUSTOM_SCRIPT=/scripts/post_process.sh
+      - CUSTOM_SCRIPT_PATH_MODE=absolute
+      - CUSTOM_SCRIPT_JSON_PAYLOAD=true
+```
+
+</details>
+
+## Script Behaviour
+
+When enabled, Shelfmark runs your script once per successful task:
+
+```bash
+<custom_script_path> "<target_path>"
+```
+
+- `$1` is always set to the target path.
+- If **Custom Script JSON Payload** is enabled, Shelfmark writes a JSON document to stdin (UTF-8).
+- If JSON payload is disabled, stdin is empty (EOF).
+- Timeout: 300 seconds (5 minutes)
+- Exit code: `0` = success; anything else = the task is marked as **Error**
+- Concurrency: downloads can run in parallel, so your script may be invoked concurrently for different tasks.
+- Runtime: the script runs inside the Shelfmark container (if you use Docker) under the same user as Shelfmark.
+
+## The Target Path (`$1`)
+
+Shelfmark chooses a "best single path" for the task:
+
+- If the output produced exactly one local file: that file path.
+- If the output produced multiple local files: a directory path (the common parent directory of those files).
+
+What the target path refers to depends on the output mode:
+
+- Folder output (`output.mode=folder`, `phase=post_transfer`): the final imported file or folder inside your destination.
+- Booklore output (`output.mode=booklore`, `phase=post_upload`): the local file or folder that was uploaded (the destination is remote).
+
+By default, `$1` is an absolute path inside the Shelfmark container (or on your host, if you are not using Docker).
+
+## JSON Payload (stdin)
+
+Configure in: Settings -> Advanced -> Custom Script JSON Payload
+
+When enabled, Shelfmark sends a versioned JSON payload to your script via stdin (and still passes `$1`). This is the recommended way to write robust scripts, especially for multi-file imports (audiobooks) and output-specific context (like Booklore).
+
+- The JSON payload always includes absolute paths in `paths.*`, even if you set Custom Script Path Mode to `relative` for `$1`.
+- `output.mode` tells you which output ran.
+- `output.details` is output-specific. For Booklore output, `output.details.booklore` includes connection details such as `base_url`, `library_id`, and `path_id`.
+- `phase` indicates when the script is running. Current values: `post_transfer` (folder output), `post_upload` (Booklore output).
+- `transfer` is only included for outputs that do a local transfer (for example the folder output).
+
+If JSON payload is disabled, stdin is empty (EOF). Don't `cat` stdin unless you've enabled the payload.
+
+Example payload shape:
+
+```json
+{
+  "version": 1,
+  "phase": "post_transfer",
+  "task": {
+    "task_id": "abc123",
+    "source": "direct",
+    "title": "Foundation",
+    "author": "Isaac Asimov"
+  },
+  "output": {
+    "mode": "folder",
+    "organization_mode": "organize"
+  },
+  "paths": {
+    "destination": "/data/library/books",
+    "target": "/data/library/books/Isaac Asimov/Foundation/Foundation.epub",
+    "final_paths": [
+      "/data/library/books/Isaac Asimov/Foundation/Foundation.epub"
+    ]
+  },
+  "transfer": {
+    "op_counts": {"copy": 1, "move": 0, "hardlink": 0},
+    "use_hardlink": false,
+    "is_torrent": false,
+    "preserve_source": false
+  }
+}
+```
+
+Example (bash + jq) (JSON payload must be enabled):
+
+```bash
+payload="$(cat)"
+mode="$(echo "$payload" | jq -r '.output.mode')"
+title="$(echo "$payload" | jq -r '.task.title')"
+final_paths="$(echo "$payload" | jq -r '.paths.final_paths[]')"
+echo "mode=$mode title=$title" >&2
+echo "$final_paths" >&2
+```
+
+Example (Python) (works whether JSON payload is enabled or not):
+
+```python
+#!/usr/bin/env python3
+import json
+import sys
+
+target = sys.argv[1]
+raw = sys.stdin.read()
+payload = json.loads(raw) if raw.strip() else None
+
+print(f"target={target}", file=sys.stderr)
+if payload:
+    print(f"mode={payload['output']['mode']} phase={payload['phase']}", file=sys.stderr)
+```
+
+<details>
+<summary>Advanced Options</summary>
+
+### Absolute vs Relative Target Paths
+
+Configure in: Settings -> Advanced -> Custom Script Path Mode
+
+This setting controls what gets passed as `$1`:
+
+- `absolute` (default): pass an absolute path.
+- `relative`: pass a path relative to the output's "destination root", and run the script with `$PWD` set to that root.
+
+For folder output, the destination root is your configured destination folder. For Booklore output, it's the local upload folder.
+
+Example (folder destination is `/data/library/books`, and the imported file ended up in `Isaac Asimov/Foundation/Foundation.epub`):
+
+```bash
+# Absolute mode:
+$PWD is unchanged
+$1 = /data/library/books/Isaac Asimov/Foundation/Foundation.epub
+
+# Relative mode:
+$PWD = /data/library/books
+$1 = Isaac Asimov/Foundation/Foundation.epub
+```
+
+Note: if the target is the destination folder itself, `relative` mode may pass `.`.
+
+</details>
+
+## Notes And Caveats
+
+- **Hardlinks and torrents:** if you use hardlinking to keep seeding, avoid scripts that modify file contents, since hardlinked files share data with the seeding copy.
+- **Booklore output mode:** scripts run after upload. `$1` will point at the local uploaded file (or staging folder).

docs/dev/index.md

@@ -0,0 +1,3 @@
+# Developer Documentation
+
+TODO

docs/dev/plugin-settings.md

@@ -16,7 +16,7 @@ The settings system uses a decorator-based registration pattern. Plugins registe
 Add settings to your plugin in 3 steps:
 
 ```python
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.core.settings_registry import (
     register_settings,
     TextField,
     PasswordField,
@@ -190,6 +190,31 @@ HeadingField(
 )
 ```
 
+### CustomComponentField
+
+Render a frontend-registered custom settings component while still using the
+decorator-based schema.
+
+```python
+from shelfmark.core.settings_registry import CustomComponentField
+
+CustomComponentField(
+    key="request_policy_editor",
+    component="request_policy_grid",  # frontend registry key
+    label="Request Policy Rules",
+    description="Custom editor for policy defaults and matrix rules.",
+    value_fields=[
+        SelectField(key="REQUEST_POLICY_DEFAULT_EBOOK", label="Default Ebook Mode", default="download"),
+        SelectField(key="REQUEST_POLICY_DEFAULT_AUDIOBOOK", label="Default Audiobook Mode", default="download"),
+        TableField(key="REQUEST_POLICY_RULES", label="Rules", columns=_rule_columns, default=[]),
+    ],
+    wrap_in_field_wrapper=True,  # use standard FieldWrapper label/description layout
+)
+```
+
+When `value_fields` is provided, those backing fields are included in
+serialization/save/validation automatically and are hidden from the default renderer.
+
 ## Common Field Properties
 
 All field types support these common properties:
@@ -206,6 +231,7 @@ All field types support these common properties:
 | `requires_restart` | `bool` | `False` | Whether changes require container restart |
 | `show_when` | `dict` | `None` | Conditional visibility (see below) |
 | `disabled_when` | `dict` | `None` | Conditional disable (see below) |
+| `hidden_in_ui` | `bool` | `False` | Hide from default renderer but keep in schema/save path |
 
 ## Conditional Visibility
 
@@ -249,7 +275,7 @@ The field will be greyed out with the specified reason when the condition is met
 Register a group to organize related settings tabs in the sidebar:
 
 ```python
-from cwa_book_downloader.core.settings_registry import register_group
+from shelfmark.core.settings_registry import register_group
 
 # Register a group (do this once, usually in a central config file)
 register_group(
@@ -289,7 +315,7 @@ The `general` tab uses `CONFIG_DIR/settings.json` instead of the plugins subdire
 Use the `config` singleton to read setting values in your plugin code:
 
 ```python
-from cwa_book_downloader.core.config import config
+from shelfmark.core.config import config
 
 # Get a setting value with default fallback
 api_key = config.get("MY_PLUGIN_API_KEY", "")
@@ -312,13 +338,13 @@ The config singleton:
 Here's a complete example for a metadata provider plugin:
 
 ```python
-# cwa_book_downloader/metadata_providers/my_provider.py
+# shelfmark/metadata_providers/my_provider.py
 
-from cwa_book_downloader.metadata_providers.base import (
+from shelfmark.metadata_providers.base import (
     MetadataProvider,
     register_provider,
 )
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.core.settings_registry import (
     register_settings,
     HeadingField,
     TextField,
@@ -326,7 +352,7 @@ from cwa_book_downloader.core.settings_registry import (
     CheckboxField,
     ActionButton,
 )
-from cwa_book_downloader.core.config import config
+from shelfmark.core.config import config
 
 
 def _test_connection():
@@ -422,15 +448,15 @@ class MyProvider(MetadataProvider):
 Here's a complete example for a release source plugin:
 
 ```python
-# cwa_book_downloader/release_sources/my_source.py
+# shelfmark/release_sources/my_source.py
 
-from cwa_book_downloader.release_sources.base import (
+from shelfmark.release_sources.base import (
     ReleaseSource,
     DownloadHandler,
     register_source,
     register_handler,
 )
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.core.settings_registry import (
     register_settings,
     HeadingField,
     TextField,
@@ -439,7 +465,7 @@ from cwa_book_downloader.core.settings_registry import (
     SelectField,
     ActionButton,
 )
-from cwa_book_downloader.core.config import config
+from shelfmark.core.config import config
 
 
 def _test_source():

docs/dev/release-sources-plugin-guide.md

@@ -1,6 +1,6 @@
 # Release Sources Plugin Development Guide
 
-This guide explains how to create custom release source plugins for the CWA Book Downloader. The plugin system allows you to add new sources for searching and downloading books while integrating seamlessly with the existing queue, progress reporting, and settings infrastructure.
+This guide explains how to create custom release source plugins for the Shelfmark. The plugin system allows you to add new sources for searching and downloading books while integrating seamlessly with the existing queue, progress reporting, and settings infrastructure.
 
 ## Table of Contents
 
@@ -43,7 +43,7 @@ The release sources system is built around two core interfaces:
 - **DownloadHandler**: Executes the actual download with progress reporting
 
 This separation allows:
-- Different search sources (Anna's Archive, Prowlarr, IRC, etc.)
+- Different search sources (Direct Download, Prowlarr, IRC, etc.)
 - Different download protocols (HTTP, torrent, usenet, etc.)
 - Shared queue and progress infrastructure
 
@@ -77,21 +77,21 @@ class MyHandler(DownloadHandler): ...
 
 ## Quick Start
 
-Create a new file at `cwa_book_downloader/release_sources/my_source.py`:
+Create a new file at `shelfmark/release_sources/my_source.py`:
 
 ```python
 from typing import Callable, List, Optional
 from threading import Event
 
-from cwa_book_downloader.release_sources import (
+from shelfmark.release_sources import (
     Release,
     ReleaseSource,
     DownloadHandler,
     register_source,
     register_handler,
 )
-from cwa_book_downloader.metadata_providers import BookMetadata
-from cwa_book_downloader.core.models import DownloadTask
+from shelfmark.metadata_providers import BookMetadata
+from shelfmark.core.models import DownloadTask
 
 
 @register_source("my_source")
@@ -123,11 +123,11 @@ class MyHandler(DownloadHandler):
         return False  # Cancellation via cancel_flag
 ```
 
-Register the import in `cwa_book_downloader/release_sources/__init__.py`:
+Register the import in `shelfmark/release_sources/__init__.py`:
 
 ```python
 # At the bottom of the file
-from cwa_book_downloader.release_sources import my_source  # noqa: F401, E402
+from shelfmark.release_sources import my_source  # noqa: F401, E402
 ```
 
 ---
@@ -139,8 +139,8 @@ The `ReleaseSource` abstract base class defines the search interface:
 ```python
 from abc import ABC, abstractmethod
 from typing import List
-from cwa_book_downloader.metadata_providers import BookMetadata
-from cwa_book_downloader.release_sources import Release, ReleaseColumnConfig
+from shelfmark.metadata_providers import BookMetadata
+from shelfmark.release_sources import Release, ReleaseColumnConfig
 
 class ReleaseSource(ABC):
     """Interface for searching a release source."""
@@ -237,7 +237,7 @@ The `DownloadHandler` abstract base class defines the download interface:
 from abc import ABC, abstractmethod
 from typing import Callable, Optional
 from threading import Event
-from cwa_book_downloader.core.models import DownloadTask
+from shelfmark.core.models import DownloadTask
 
 class DownloadHandler(ABC):
     """Interface for executing downloads from a source."""
@@ -371,7 +371,7 @@ class Release:
     info_url: Optional[str] = None      # Link to tracker/info page
 
     protocol: Optional[str] = None   # "http", "torrent", "usenet"
-    indexer: Optional[str] = None    # Display name: "Anna's Archive", "MyAnonamouse"
+    indexer: Optional[str] = None    # Display name: "Direct Download", "My Indexer"
     seeders: Optional[int] = None    # For torrents
 
     extra: Dict = field(default_factory=dict)  # Source-specific metadata
@@ -458,7 +458,7 @@ class BookMetadata:
 ### Decorators
 
 ```python
-from cwa_book_downloader.release_sources import register_source, register_handler
+from shelfmark.release_sources import register_source, register_handler
 
 @register_source("my_source")
 class MySource(ReleaseSource):
@@ -472,7 +472,7 @@ class MyHandler(DownloadHandler):
 ### Registry Functions
 
 ```python
-from cwa_book_downloader.release_sources import (
+from shelfmark.release_sources import (
     get_source,
     get_handler,
     list_available_sources,
@@ -497,8 +497,8 @@ available = list_available_sources()
 
 ```python
 # At the bottom of __init__.py
-from cwa_book_downloader.release_sources import direct_download  # noqa: F401, E402
-from cwa_book_downloader.release_sources import my_source  # noqa: F401, E402
+from shelfmark.release_sources import direct_download  # noqa: F401, E402
+from shelfmark.release_sources import my_source  # noqa: F401, E402
 ```
 
 The `noqa` comments suppress linter warnings about unused imports.
@@ -510,7 +510,7 @@ The `noqa` comments suppress linter warnings about unused imports.
 Register plugin settings using the settings registry decorator:
 
 ```python
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.core.settings_registry import (
     register_settings,
     HeadingField,
     TextField,
@@ -621,7 +621,7 @@ def test_my_source_connection():
 ### Reading Settings
 
 ```python
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.core.settings_registry import (
     get_setting_value,
     is_value_from_env,
     load_config_file,
@@ -658,7 +658,7 @@ When a value comes from an ENV var, the UI shows a "locked" badge and the field
 Customize how releases are displayed in the release modal by overriding `get_column_config()`:
 
 ```python
-from cwa_book_downloader.release_sources import (
+from shelfmark.release_sources import (
     ReleaseColumnConfig,
     ColumnSchema,
     ColumnRenderType,
@@ -907,7 +907,7 @@ from pathlib import Path
 from typing import Callable, Dict, List, Optional
 from threading import Event
 
-from cwa_book_downloader.release_sources import (
+from shelfmark.release_sources import (
     Release,
     ReleaseSource,
     DownloadHandler,
@@ -921,10 +921,10 @@ from cwa_book_downloader.release_sources import (
     LeadingCellConfig,
     LeadingCellType,
 )
-from cwa_book_downloader.metadata_providers import BookMetadata
-from cwa_book_downloader.core.models import DownloadTask
-from cwa_book_downloader.core.logger import setup_logger
-from cwa_book_downloader.core.settings_registry import (
+from shelfmark.metadata_providers import BookMetadata
+from shelfmark.core.models import DownloadTask
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.settings_registry import (
     register_settings,
     HeadingField,
     TextField,
@@ -934,7 +934,7 @@ from cwa_book_downloader.core.settings_registry import (
     ActionButton,
     load_config_file,
 )
-from cwa_book_downloader.config.env import INGEST_DIR
+from shelfmark.config.env import INGEST_DIR
 
 logger = setup_logger(__name__)
 
@@ -1421,7 +1421,7 @@ PasswordField(
 Use the project's logger for consistent output:
 
 ```python
-from cwa_book_downloader.core.logger import setup_logger
+from shelfmark.core.logger import setup_logger
 
 logger = setup_logger(__name__)
 
@@ -1437,13 +1437,13 @@ logger.error("Failures")                 # Unrecoverable errors
 
 When creating a new plugin:
 
-1. Create `cwa_book_downloader/release_sources/my_plugin.py`
+1. Create `shelfmark/release_sources/my_plugin.py`
 2. Implement `ReleaseSource` subclass with `@register_source("my_plugin")`
 3. Implement `DownloadHandler` subclass with `@register_handler("my_plugin")`
 4. Add settings with `@register_settings("my_plugin", ...)`
-5. Add import to `cwa_book_downloader/release_sources/__init__.py`:
+5. Add import to `shelfmark/release_sources/__init__.py`:
    ```python
-   from cwa_book_downloader.release_sources import my_plugin  # noqa: F401, E402
+   from shelfmark.release_sources import my_plugin  # noqa: F401, E402
    ```
 6. Test `is_available()` returns `True` when configured
 7. Test search returns valid `Release` objects

docs/index.md

@@ -0,0 +1,3 @@
+# Shelfmark Documentation
+
+TODO

docs/installation.md

@@ -0,0 +1,3 @@
+# Installation
+
+TODO

docs/oidc.md

@@ -0,0 +1,50 @@
+# OpenID Connect (OIDC) Authentication
+
+## Callback URL
+
+```
+https://<your-shelfmark-domain>/api/auth/oidc/callback
+```
+
+With a subpath (`URL_BASE=/shelfmark/`):
+
+```
+https://<your-shelfmark-domain>/shelfmark/api/auth/oidc/callback
+```
+
+The callback URL is constructed from the incoming request, so your reverse proxy must forward `X-Forwarded-Proto` and `X-Forwarded-Host` correctly. PKCE (S256) is used automatically.
+
+## Settings
+
+Configure in **Settings → Security → Authentication Method → OIDC**.
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Discovery URL | `/.well-known/openid-configuration` endpoint | — |
+| Client ID | OAuth2 client ID | — |
+| Client Secret | OAuth2 client secret | — |
+| Scopes | Scopes to request. The group claim is added automatically when admin group authorization is enabled | `openid email profile` |
+| Group Claim Name | Claim containing user groups | `groups` |
+| Admin Group Name | Group granted admin access. Leave empty for database-only roles | — |
+| Use Admin Group for Authorization | Toggle group-based admin detection | `true` |
+| Auto-Provision Users | Create accounts on first login | `true` |
+| Login Button Label | Custom text for the sign-in button | — |
+
+Use **Test Connection** to verify discovery and client configuration before attempting login.
+
+## Environment Variables
+
+These optional environment variables control login page behavior when OIDC is enabled.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HIDE_LOCAL_AUTH` | Hide the username/password login option, so only the OIDC button is shown | `false` |
+| `OIDC_AUTO_REDIRECT` | Automatically redirect to the OIDC provider instead of showing the login page | `false` |
+
+If both are enabled, users are redirected straight to the OIDC provider. On failure they return to the login page with an error message but no password fallback.
+
+## Troubleshooting
+
+- **Issuer validation failed** — The issuer in the token doesn't match the discovery document. Check your provider's external URL / issuer configuration.
+- **Callback URL mismatch** — Reverse proxy isn't forwarding `X-Forwarded-Proto` or `X-Forwarded-Host`, so the constructed callback URL doesn't match what's registered in the provider.
+- **Account not found** — Auto-provision is disabled and the user hasn't been pre-created by an admin.

docs/reverse-proxy.md

@@ -0,0 +1,147 @@
+# Reverse Proxy & Subpath Hosting
+
+Shelfmark can run behind a reverse proxy at the root path (recommended) or under a subpath like `/shelfmark`.
+
+## Root path setup (Recommended)
+
+If you can serve Shelfmark at the root path (`https://shelfmark.example.com/`), leave `URL_BASE` empty. This is the simplest option and avoids extra subpath configuration.
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name shelfmark.example.com;
+
+    location / {
+        proxy_pass http://shelfmark:8084;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+## Subpath setup
+
+Running Shelfmark under a subpath like `/shelfmark` is supported without extra rewrite rules.
+
+### 1. Set the base path in Shelfmark
+
+- **UI**: Settings → Advanced → Base Path → `/shelfmark/`
+- **Environment variable**: `URL_BASE=/shelfmark/`
+
+### 2. Configure your reverse proxy
+
+All Shelfmark paths (UI, API, assets, Socket.IO) are served under the base path. A single location block is enough.
+
+---
+
+### Without Authentication Proxy
+
+**Complete Nginx configuration for subpath deployment:**
+
+```nginx
+location /shelfmark/ {
+    proxy_pass http://shelfmark:8084/shelfmark/;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 86400;
+    proxy_send_timeout 86400;
+    proxy_buffering off;
+}
+```
+
+---
+
+### With Authentication Proxy (Authelia, Authentik, etc.)
+
+Shelfmark supports Proxy Authentication. When enabled, Shelfmark trusts the authenticated user from headers set by your auth proxy.
+
+#### Shelfmark Settings
+
+Configure in Settings → Security:
+
+| Setting | Value |
+|---------|-------|
+| Authentication Method | Proxy Authentication |
+| Proxy Auth User Header | `Remote-User` |
+| Proxy Auth Logout URL | `https://auth.example.com/logout` |
+| Proxy Auth Admin Group Header | `Remote-Groups` |
+| Proxy Auth Admin Group Name | `admins` (or your admin group) |
+
+#### Nginx Configuration with Authelia
+
+This example uses Authelia snippets. Adapt for your auth proxy.
+
+**Authelia auth request snippet** (`/etc/nginx/snippets/authelia-authrequest.conf`):
+
+```nginx
+location /authelia {
+    internal;
+    proxy_pass http://authelia:9091/api/authz/auth-request;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    proxy_set_header Host $host;
+    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
+    proxy_set_header X-Original-Method $request_method;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+**Authelia location snippet** (`/etc/nginx/snippets/authelia-location.conf`):
+
+```nginx
+auth_request /authelia;
+auth_request_set $target_url $scheme://$http_host$request_uri;
+auth_request_set $user $upstream_http_remote_user;
+auth_request_set $groups $upstream_http_remote_groups;
+auth_request_set $name $upstream_http_remote_name;
+auth_request_set $email $upstream_http_remote_email;
+proxy_set_header Remote-User $user;
+proxy_set_header Remote-Groups $groups;
+proxy_set_header Remote-Name $name;
+proxy_set_header Remote-Email $email;
+error_page 401 =302 https://auth.example.com/?rd=$target_url;
+```
+
+**Complete Nginx configuration with Authelia:**
+
+```nginx
+# Include Authelia auth endpoint in your server block
+include /etc/nginx/snippets/authelia-authrequest.conf;
+
+# Main shelfmark location
+location /shelfmark/ {
+    include /etc/nginx/snippets/authelia-location.conf;
+
+    proxy_pass http://shelfmark:8084/shelfmark/;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 86400;
+    proxy_send_timeout 86400;
+    proxy_buffering off;
+}
+```
+
+---
+
+## Health checks
+
+Health checks work at `/shelfmark/api/health` when using a subpath configuration.

docs/troubleshooting.md

@@ -0,0 +1,3 @@
+# Troubleshooting
+
+TODO

docs/url-search-parameters.md

@@ -19,6 +19,7 @@ http://your-server:8084/?q=harry+potter
 | `lang` | Filter by language (ISO 639-1 code) | `/?lang=en` |
 | `format` | Filter by file format | `/?format=epub` |
 | `content` | Filter by content type | `/?content=fiction` |
+| `content_type` | Select media type (`ebook` or `audiobook`) in Universal mode only | `/?q=dune&content_type=audiobook` |
 | `sort` | Sort order for results | `/?sort=newest` |
 
 ## Multiple Values
@@ -57,15 +58,21 @@ Some parameters support multiple values by repeating the parameter:
 /?q=science+fiction&sort=newest
 ```
 
+**Universal search as audiobook:**
+```
+/?q=dune&content_type=audiobook
+```
+
 ## Search Mode Behavior
 
 ### Direct Download Mode (default)
 
-All parameters are used to filter results from Anna's Archive.
+All parameters are used to filter results from the direct download source.
+`content_type` is ignored in Direct mode.
 
 ### Universal Mode
 
-Only `q` and `sort` are used. Other parameters (author, title, format, etc.) are silently ignored since metadata providers have their own search capabilities.
+`q`, `sort`, and `content_type` are used. Other parameters (author, title, format, etc.) are silently ignored since metadata providers have their own search capabilities.
 
 ## Notes
 

docs/users-and-requests.md

@@ -0,0 +1,98 @@
+# Users & Requests
+
+Configure in **Settings → Users & Requests**.
+
+## Authentication Methods
+
+Shelfmark supports four authentication methods, configured in **Settings → Security**.
+
+### Local
+
+You create user accounts directly in Shelfmark with a username and password. At least one local admin account must exist before this mode can be enabled.
+
+### Proxy Authentication
+
+Your reverse proxy handles authentication and passes the username to Shelfmark via a header (e.g. `Remote-User`). Accounts are created automatically on first sign-in. If a local user with the same username already exists, the proxy identity will be linked to that account rather than creating a duplicate. Admin status can optionally be derived from a groups header.
+
+### OIDC (OpenID Connect)
+
+Users sign in through your identity provider. Accounts are created automatically on first login (unless auto-provisioning is disabled, in which case you need to pre-create them). If a local user with a matching verified email already exists, the OIDC identity will be linked to that account on first sign-in. Admin status can optionally be derived from a group claim.
+
+A local admin account is required as a fallback. See [OIDC](oidc.md) for provider setup.
+
+### Calibre-Web Database
+
+User accounts are synced from your Calibre-Web `app.db`. If a local user with a matching email already exists, the CWA identity will be linked to that account. Roles are kept in sync with CWA. Users removed from CWA are cleaned up on the next sync.
+
+Requires mounting your Calibre-Web `app.db` to `/auth/app.db`.
+
+## Per-User Settings
+
+Admins can configure per-user settings by editing a user in the user management panel. Non-admin users can also edit their own settings through **My Account** (accessible from the user menu). Admins control which sections are visible in My Account via the **Visible Self-Settings Sections** option.
+
+There are three categories of per-user settings:
+
+### Delivery Preferences
+
+Override where a user's downloads are sent. Options depend on the global output mode configuration:
+
+- **Output mode** — Folder, Email (SMTP), or BookLore (API)
+- **Destination** — A custom folder path for this user's ebook downloads
+- **Audiobook destination** — A custom folder path for audiobook downloads
+- **BookLore library/path** — Per-user BookLore target (when using BookLore output mode)
+- **Email recipient** — Per-user email address (when using Email output mode)
+
+### Notifications
+
+Users can configure personal notification routes, separate from the global notification settings. Each route targets a URL (e.g. an Apprise-compatible endpoint) and can be scoped to specific event types or all events.
+
+### Request Policy (admin-only)
+
+Admins can override the default ebook/audiobook modes and request rules for individual users. See [Per-User Overrides](#per-user-overrides) below.
+
+---
+
+## Requests
+
+The request system controls whether users can download directly or need admin approval first.
+
+### Policy Modes
+
+Each content type (ebook, audiobook) has a default mode that sets the baseline:
+
+| Mode | Behaviour |
+|------|-----------|
+| **Download** | Users download directly, no approval needed |
+| **Request Release** | Users pick a specific release, then submit it for admin approval |
+| **Request Book** | Users request the book itself — an admin picks the release and fulfils it |
+| **Blocked** | No downloads or requests allowed |
+
+### Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Enable Requests | Master toggle. When off, everyone downloads directly | Off |
+| Default Ebook Mode | Baseline mode for all ebook sources | Download |
+| Default Audiobook Mode | Baseline mode for all audiobook sources | Download |
+| Request Rules | Per-source overrides (see below) | None |
+| Max Pending Requests Per User | Open request limit per user | 20 |
+| Allow Notes on Requests | Let users attach a note when submitting | On |
+
+### Request Rules
+
+The rules matrix lets you override the mode for specific source + content type combinations. Rules can only be **equal to or more restrictive** than the content-type default — they cannot grant more access than the baseline.
+
+For example, if the default ebook mode is "Download", a rule can restrict a specific source to "Request Release" or "Blocked", but not the other way around. If no rule matches, the content-type default applies.
+
+### Per-User Overrides
+
+Admins can override the default ebook/audiobook modes and request rules for individual users. Per-user rules are overlaid on the global rules, not replacing them.
+
+### Request Lifecycle
+
+1. User submits a request (book or release level, depending on the resolved policy mode)
+2. Request appears in the admin request queue as **pending**
+3. Admin either **fulfils** (queues a download) or **rejects** the request
+4. For fulfilled requests, delivery state is tracked through the download pipeline
+5. If delivery fails, an admin can reopen the request to try a different release
+6. Users can cancel their own pending requests

entrypoint.sh

@@ -1,10 +1,54 @@
 #!/bin/bash
-LOG_DIR=${LOG_ROOT:-/var/log/}/cwa-book-downloader
-mkdir -p $LOG_DIR
-LOG_FILE=${LOG_DIR}/cwa-bd_entrypoint.log
 
-# Cleanup any existing files or folders in the log directory
-rm -rf $LOG_DIR/*
+is_truthy() {
+    case "${1,,}" in
+        true|yes|1|y) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+ENABLE_LOGGING_VALUE="${ENABLE_LOGGING:-true}"
+LOG_PIPE_DIR=""
+LOG_PIPE=""
+TEE_PID=""
+
+start_file_logging() {
+    local logfile="$1"
+
+    LOG_PIPE_DIR="$(mktemp -d)"
+    LOG_PIPE="${LOG_PIPE_DIR}/shelfmark-log.pipe"
+    mkfifo "$LOG_PIPE"
+
+    tee -a "$logfile" < "$LOG_PIPE" &
+    TEE_PID=$!
+
+    exec 3>&1 4>&2
+    exec > "$LOG_PIPE" 2>&1
+}
+
+stop_file_logging() {
+    if [ -z "${TEE_PID:-}" ]; then
+        return 0
+    fi
+
+    exec 1>&3 2>&4
+    exec 3>&- 4>&-
+
+    rm -f "$LOG_PIPE"
+    rmdir "$LOG_PIPE_DIR" 2>/dev/null || true
+
+    wait "$TEE_PID" 2>/dev/null || true
+    TEE_PID=""
+}
+
+if is_truthy "$ENABLE_LOGGING_VALUE"; then
+    LOG_DIR=${LOG_ROOT:-/var/log/}/shelfmark
+    mkdir -p "$LOG_DIR"
+    LOG_FILE="${LOG_DIR}/shelfmark_entrypoint.log"
+    # Keep the previous entrypoint log instead of deleting all history on boot.
+    [ -f "${LOG_FILE}.prev" ] && rm -f "${LOG_FILE}.prev"
+    [ -f "$LOG_FILE" ] && mv "$LOG_FILE" "${LOG_FILE}.prev"
+fi
 
 (
     if [ "$USING_TOR" = "true" ]; then
@@ -12,10 +56,16 @@ rm -rf $LOG_DIR/*
     fi
 )
 
-exec 3>&1 4>&2
-exec > >(tee -a $LOG_FILE) 2>&1
+if is_truthy "$ENABLE_LOGGING_VALUE"; then
+    start_file_logging "$LOG_FILE"
+fi
+
 echo "Starting entrypoint script"
-echo "Log file: $LOG_FILE"
+if is_truthy "$ENABLE_LOGGING_VALUE"; then
+    echo "Log file: $LOG_FILE"
+else
+    echo "File logging disabled (ENABLE_LOGGING=$ENABLE_LOGGING_VALUE)"
+fi
 set -e
 
 # Print build version
@@ -28,40 +78,75 @@ if [ "$TZ" ]; then
     ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
 fi
 
-# Set UID if not set
-if [ -z "$UID" ]; then
-    UID=1000
+# Determine user ID with proper precedence:
+# 1. PUID (LinuxServer.io standard - recommended)
+# 2. UID (legacy, for backward compatibility with existing installs)
+# 3. Default to 1000
+#
+# Note: $UID is a bash builtin that's always set. We use `printenv` to detect
+# if UID was explicitly set as an environment variable (e.g., via docker-compose).
+if [ -n "$PUID" ]; then
+    RUN_UID="$PUID"
+    echo "Using PUID=$RUN_UID"
+elif printenv UID >/dev/null 2>&1; then
+    RUN_UID="$(printenv UID)"
+    echo "Using UID=$RUN_UID (legacy - consider migrating to PUID)"
+else
+    RUN_UID=1000
+    echo "Using default UID=$RUN_UID"
 fi
 
-# Set GID if not set
-if [ -z "$GID" ]; then
-    GID=100
+# Determine group ID with proper precedence:
+# 1. PGID (LinuxServer.io standard - recommended)
+# 2. GID (legacy, for backward compatibility with existing installs)
+# 3. Default to 1000
+if [ -n "$PGID" ]; then
+    RUN_GID="$PGID"
+    echo "Using PGID=$RUN_GID"
+elif [ -n "$GID" ]; then
+    RUN_GID="$GID"
+    echo "Using GID=$RUN_GID (legacy - consider migrating to PGID)"
+else
+    RUN_GID=1000
+    echo "Using default GID=$RUN_GID"
 fi
 
-if ! getent group "$GID" >/dev/null; then
-    echo "Adding group $GID with name appuser"
-    groupadd -g "$GID" appuser
+if ! getent group "$RUN_GID" >/dev/null; then
+    echo "Adding group $RUN_GID with name appuser"
+    groupadd -g "$RUN_GID" appuser
 fi
 
 # Create user if it doesn't exist
-if ! id -u "$UID" >/dev/null 2>&1; then
-    echo "Adding user $UID with name appuser"
-    useradd -u "$UID" -g "$GID" -d /app -s /sbin/nologin appuser
+if ! id -u "$RUN_UID" >/dev/null 2>&1; then
+    echo "Adding user $RUN_UID with name appuser"
+    useradd -u "$RUN_UID" -g "$RUN_GID" -d /app -s /sbin/nologin appuser
 fi
 
 # Get username for the UID (whether we just created it or it existed)
-USERNAME=$(getent passwd "$UID" | cut -d: -f1)
-echo "Username for UID $UID is $USERNAME"
+USERNAME=$(getent passwd "$RUN_UID" | cut -d: -f1)
+echo "Username for UID $RUN_UID is $USERNAME"
 
 test_write() {
-    folder=$1
-    test_file=$folder/calibre-web-automated-book-downloader_TEST_WRITE
-    mkdir -p $folder
-    (
-        echo 0123456789_TEST | sudo -E -u "$USERNAME" HOME=/app tee $test_file > /dev/null
-    )
-    FILE_CONTENT=$(cat $test_file || echo "")
-    rm -f $test_file
+    local folder=$1
+    local test_file="$folder/shelfmark_TEST_WRITE"
+    local FILE_CONTENT
+    local result
+    local result_text
+
+    if ! mkdir -p "$folder"; then
+        echo "Failed to create directory for write test: $folder"
+        return 1
+    fi
+
+    if ! (
+        echo 0123456789_TEST | gosu "$USERNAME" env HOME=/app tee "$test_file" > /dev/null
+    ); then
+        echo "Failed to write test file in $folder as $USERNAME"
+        return 1
+    fi
+
+    FILE_CONTENT=$(cat "$test_file" 2>/dev/null || echo "")
+    rm -f "$test_file"
     [ "$FILE_CONTENT" = "0123456789_TEST" ]
     result=$?
     if [ $result -eq 0 ]; then
@@ -75,6 +160,7 @@ test_write() {
 
 make_writable() {
     folder=$1
+    did_full_chown=0
     set +e
     test_write $folder
     is_writable=$?
@@ -84,32 +170,115 @@ make_writable() {
     else
         echo "Folder $folder is not writable, changing ownership"
         change_ownership $folder
-        chmod g+r,g+w $folder || echo "Failed to change group permissions for ${folder}, continuing..."
+        chmod -R g+r,g+w $folder || echo "Failed to change group permissions for ${folder}, continuing..."
+        did_full_chown=1
+    fi
+    # Fix any misowned subdirectories/files (e.g., from previous runs as root)
+    if [ "$did_full_chown" -eq 0 ] && [ -d "$folder" ]; then
+        echo "Checking for misowned files/directories in $folder"
+        # Stay on the same filesystem to avoid traversing mounted subpaths
+        # (for example read-only bind mounts under /app in dev setups).
+        find "$folder" -xdev -mindepth 1 \( ! -user "$RUN_UID" -o ! -group "$RUN_GID" \) \
+            -exec chown "$RUN_UID:$RUN_GID" {} + 2>/dev/null || true
     fi
     test_write $folder || echo "Failed to test write to ${folder}, continuing..."
 }
 
+fix_misowned() {
+    folder=$1
+    mkdir -p $folder
+    echo "Checking for misowned files/directories in $folder"
+    # Stay on the same filesystem to avoid traversing mounted subpaths
+    # (for example read-only bind mounts under /app in dev setups).
+    find "$folder" -xdev \( ! -user "$RUN_UID" -o ! -group "$RUN_GID" \) \
+        -exec chown "$RUN_UID:$RUN_GID" {} + 2>/dev/null || true
+}
+
 # Ensure proper ownership of application directories
 change_ownership() {
   folder=$1
   mkdir -p $folder
-  echo "Changing ownership of $folder to $USERNAME:$GID"
-  chown -R "${UID}" "${folder}" || echo "Failed to change user ownership for ${folder}, continuing..."
-  chown -R ":${GID}" "${folder}" || echo "Failed to change group ownership for ${folder}, continuing..."
+  echo "Changing ownership of $folder to $USERNAME:$RUN_GID"
+  chown -R "${RUN_UID}:${RUN_GID}" "${folder}" || echo "Failed to change ownership for ${folder}, continuing..."
 }
 
-change_ownership /app
-change_ownership /var/log/cwa-book-downloader
-change_ownership /tmp/cwa-book-downloader
+fix_misowned /app
+fix_misowned /var/log/shelfmark
+fix_misowned /tmp/shelfmark
+
+# SeleniumBase (internal bypasser) writes a patched chromedriver binary (uc_driver)
+# into its own drivers directory. Some NAS/docker setups can apply restrictive ACLs
+# to extracted image layers that block non-root writes; ensure the runtime UID owns it.
+if [ "${USING_EXTERNAL_BYPASSER}" != "true" ]; then
+    set +e
+    SELENIUMBASE_DRIVERS_DIR=$(python3 -c "import pathlib, seleniumbase; print(pathlib.Path(seleniumbase.__file__).resolve().parent / 'drivers')" 2>/dev/null)
+    set -e
+
+    if [ -n "$SELENIUMBASE_DRIVERS_DIR" ] && [ -d "$SELENIUMBASE_DRIVERS_DIR" ]; then
+        change_ownership "$SELENIUMBASE_DRIVERS_DIR"
+
+        # If the driver already exists, ensure it's executable for the runtime user.
+        if [ -f "${SELENIUMBASE_DRIVERS_DIR}/uc_driver" ]; then
+            chmod +x "${SELENIUMBASE_DRIVERS_DIR}/uc_driver" || echo "Failed to chmod uc_driver, continuing..."
+        fi
+    fi
+fi
 
 # Test write to all folders
-make_writable /cwa-book-ingest
+make_writable ${CONFIG_DIR:-/config}
+make_writable ${INGEST_DIR:-/books}
+
+# Fix permissions on directories configured in settings
+echo "Checking for additional configured directories..."
+if [ -f /app/scripts/fix_permissions.py ]; then
+    configured_dirs=$(python3 /app/scripts/fix_permissions.py 2>/dev/null || echo "")
+    if [ -n "$configured_dirs" ]; then
+        echo "$configured_dirs" | while read -r dir; do
+            if [ -n "$dir" ] && [ -d "$dir" ]; then
+                echo "Checking configured directory: $dir"
+                make_writable "$dir"
+            fi
+        done
+    fi
+fi
+
+# Fallback to root if config dir is still not writable (common on NAS/Unraid after upgrade from v0.4.0)
+CONFIG_PATH=${CONFIG_DIR:-/config}
+set +e
+test_write "$CONFIG_PATH" >/dev/null 2>&1
+config_ok=$?
+set -e
+
+if [ $config_ok -ne 0 ] && [ "$RUN_UID" != "0" ]; then
+    config_owner=$(stat -c '%u' "$CONFIG_PATH" 2>/dev/null || echo "unknown")
+    if [ "$config_owner" = "0" ]; then
+        echo ""
+        echo "========================================================"
+        echo "WARNING: Permission issue detected!"
+        echo ""
+        echo "Config directory is owned by root but PUID=$RUN_UID."
+        echo "This typically happens after upgrading from v0.4.0 where"
+        echo "PUID/PGID settings were not respected."
+        echo ""
+        echo "Falling back to running as root to prevent data loss."
+        echo ""
+        echo "To fix this permanently, run on your HOST machine:"
+        echo "  chown -R $RUN_UID:$RUN_GID /path/to/config"
+        echo ""
+        echo "Then restart the container."
+        echo "========================================================"
+        echo ""
+        RUN_UID=0
+        RUN_GID=0
+        USERNAME=root
+    fi
+fi
 
 # Always run Gunicorn (even when DEBUG=true) to ensure Socket.IO WebSocket
 # upgrades work reliably on customer machines.
 # Map app LOG_LEVEL (often DEBUG/INFO/...) to gunicorn's --log-level (lowercase).
 gunicorn_loglevel=$([ "$DEBUG" = "true" ] && echo debug || echo "${LOG_LEVEL:-info}" | tr '[:upper:]' '[:lower:]')
-command="gunicorn --log-level ${gunicorn_loglevel} --access-logfile - --error-logfile - --worker-class geventwebsocket.gunicorn.workers.GeventWebSocketWorker --workers 1 -t 300 -b ${FLASK_HOST:-0.0.0.0}:${FLASK_PORT:-8084} cwa_book_downloader.main:app"
+command="gunicorn --log-level ${gunicorn_loglevel} --access-logfile - --error-logfile - --worker-class geventwebsocket.gunicorn.workers.GeventWebSocketWorker --workers 1 -t 300 -b ${FLASK_HOST:-0.0.0.0}:${FLASK_PORT:-8084} shelfmark.main:app"
 
 # If DEBUG and not using an external bypass
 if [ "$DEBUG" = "true" ] && [ "$USING_EXTERNAL_BYPASSER" != "true" ]; then
@@ -165,18 +334,24 @@ if [ "$DEBUG" = "true" ] && [ "$USING_EXTERNAL_BYPASSER" != "true" ]; then
     echo "^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^"
 fi
 
-# Hacky way to verify /tmp has at least 1MB of space and is writable/readable
+# Verify /tmp has at least 1MB of space and is writable/readable
 echo "Verifying /tmp has enough space"
-rm -f /tmp/test.cwa-bd
-for i in {1..150000}; do printf "%04d\n" $i; done > /tmp/test.cwa-bd
-sum=$(python3 -c "print(sum(int(l.strip()) for l in open('/tmp/test.cwa-bd').readlines()))")
-[ "$sum" == 11250075000 ] && echo "Success: /tmp is writable" || (echo "Failure: /tmp is not writable" && exit 1)
-rm /tmp/test.cwa-bd
+rm -f /tmp/test.shelfmark
+if dd if=/dev/zero of=/tmp/test.shelfmark bs=1M count=1 2>/dev/null && \
+   [ "$(wc -c < /tmp/test.shelfmark)" -eq 1048576 ]; then
+    rm -f /tmp/test.shelfmark
+    echo "Success: /tmp is writable and readable"
+else
+    echo "Failure: /tmp is not writable or has insufficient space"
+    exit 1
+fi
 
 echo "Running command: '$command' as '$USERNAME' (debug=$is_debug)"
 
-# Stop logging
-exec 1>&3 2>&4
-exec 3>&- 4>&-
+# Set umask for file permissions (default: 0022 = files 644, dirs 755)
+UMASK_VALUE=${UMASK:-0022}
+echo "Setting umask to $UMASK_VALUE"
+umask $UMASK_VALUE
 
-exec sudo -E -u "$USERNAME" HOME=/app $command
+stop_file_logging
+exec gosu "$USERNAME" env HOME=/app $command

genDebug.sh

@@ -2,8 +2,8 @@
 
 # Set up log paths
 LOG_ROOT=${LOG_ROOT:-"/var/log"}
-LOG_DIR="$LOG_ROOT/cwa-book-downloader"
-OUTPUT_FILE_NAME="cwa-book-downloader-debug_BUILD-${BUILD_VERSION:-local}_RELEASE-${RELEASE_VERSION:-NA}_$(date +%Y%m%d-%H%M%S)"
+LOG_DIR="$LOG_ROOT/shelfmark"
+OUTPUT_FILE_NAME="shelfmark-debug_BUILD-${BUILD_VERSION:-local}_RELEASE-${RELEASE_VERSION:-NA}_$(date +%Y%m%d-%H%M%S)"
 OUTPUT_FILE="/tmp/$OUTPUT_FILE_NAME.zip"
 
 # Create LOG_DIR if it doesn't exist
@@ -100,14 +100,14 @@ echo "=== Permissions ===" > "$LOG_DIR/permissions.txt"
 echo "ls -all /app" >> "$LOG_DIR/permissions.txt"
 ls -all /app >> "$LOG_DIR/permissions.txt" 2>&1
 echo "" >> "$LOG_DIR/permissions.txt"
-echo "ls -all /cwa-book-ingest" >> "$LOG_DIR/permissions.txt"
-ls -all /cwa-book-ingest >> "$LOG_DIR/permissions.txt" 2>&1
+echo "ls -all ${INGEST_DIR:-/books}" >> "$LOG_DIR/permissions.txt"
+ls -all ${INGEST_DIR:-/books} >> "$LOG_DIR/permissions.txt" 2>&1
 echo "" >> "$LOG_DIR/permissions.txt"
-echo "ls -all /var/log/cwa-book-downloader" >> "$LOG_DIR/permissions.txt"
-ls -all /var/log/cwa-book-downloader >> "$LOG_DIR/permissions.txt" 2>&1
+echo "ls -all /var/log/shelfmark" >> "$LOG_DIR/permissions.txt"
+ls -all /var/log/shelfmark >> "$LOG_DIR/permissions.txt" 2>&1
 echo "" >> "$LOG_DIR/permissions.txt"
-echo "ls -all /tmp/cwa-book-downloader" >> "$LOG_DIR/permissions.txt"
-ls -all /tmp/cwa-book-downloader >> "$LOG_DIR/permissions.txt" 2>&1
+echo "ls -all /tmp/shelfmark" >> "$LOG_DIR/permissions.txt"
+ls -all /tmp/shelfmark >> "$LOG_DIR/permissions.txt" 2>&1
 echo "" >> "$LOG_DIR/permissions.txt"
 
 # Check Iptables (NAT)

package-lock.json

@@ -0,0 +1,22 @@
+{
+  "name": "shelfmark",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "devDependencies": {
+        "baseline-browser-mapping": "^2.9.19"
+      }
+    },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.9.19",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.9.19.tgz",
+      "integrity": "sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.js"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "baseline-browser-mapping": "^2.9.19"
+  }
+}

pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "shelfmark"
+version = "0.1.0"
+description = "Shelfmark - Book Downloader"
+requires-python = ">=3.10"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+]
+markers = [
+    "integration: marks tests that require running services (deselect with '-m \"not integration\"')",
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "e2e: marks end-to-end tests that require the full application stack",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true

readme.md

@@ -1,365 +1,256 @@
-# 📚 Calibre-Web-Automated-Book-Downloader
+# 📚 Shelfmark: Book Downloader
 
-<img src="src/frontend/public/logo.png" alt="Calibre-Web Automated Book Downloader" width="200">
+Formerly *Calibre Web Automated Book Downloader (CWABD)*
 
-An intuitive web interface for searching and requesting book downloads, designed to work seamlessly with [Calibre-Web-Automated](https://github.com/crocodilestick/Calibre-Web-Automated). This project streamlines the process of downloading books and preparing them for integration into your Calibre library.
+<img src="src/frontend/public/logo.png" alt="Shelfmark" width="200">
+
+Shelfmark is a self-hosted web interface for searching and downloading books and audiobooks from multiple sources. Works out of the box with popular web sources, no configuration required. Add metadata providers, additional release sources, and download clients to build a single hub for your digital library. Supports multiple users with a built-in request system, so you can share your instance with others and let them browse and request books on their own.
+
+**Fully standalone** - no external dependencies required. Works great alongside the following library tools, with support for automatic imports:
+- [Calibre](https://calibre-ebook.com/)
+- [Calibre-Web](https://github.com/janeczku/calibre-web)
+- [Calibre-Web-Automated](https://github.com/crocodilestick/Calibre-Web-Automated)
+- [Booklore](https://github.com/booklore-app/booklore)
+- [Audiobookshelf](https://github.com/advplyr/audiobookshelf)
 
 ## ✨ Features
 
-- 🌐 User-friendly web interface for book search and download
-- 🔄 Automated download to your specified ingest folder
-- 🔌 Seamless integration with Calibre-Web-Automated
-- 📖 Support for multiple book formats (epub, mobi, azw3, fb2, djvu, cbz, cbr)
-- 🛡️ Cloudflare bypass capability for reliable downloads
-- 🐳 Docker-based deployment for quick setup
+- **One-Stop Interface** - A clean, modern UI to search, browse, and download from multiple sources in one place
+- **Multiple Sources** - Popular archive websites, Torrent, Usenet, and IRC download support
+- **Audiobook Support** - Full audiobook search and download with dedicated processing
+- **Two Search Modes**:
+  - **Direct** - Search popular web sources
+  - **Universal** - Search metadata providers (Hardcover, Open Library) for richer book and audiobook discovery, with multi-source downloads
+- **Multi-User & Requests** - Share your instance with others, let users browse and request books, and manage approvals with configurable notifications
+- **Authentication** - Built-in login, OIDC single sign-on, proxy auth, and Calibre-Web database support
+- **Real-Time Progress** - Unified download queue with live status updates across all sources
+- **Cloudflare Bypass** - Built-in bypasser for reliable access to protected sources
 
 ## 🖼️ Screenshots
 
-![Homescreen](README_images/homescreen.png 'Homescreen')
+**Home screen**
+![Home screen](README_images/homescreen.png 'Home screen')
 
+**Search results**
 ![Search results](README_images/search-results.png 'Search results')
 
-![Active downloads](README_images/downloads.png 'Active downloads')
+**Multi-source downloads**
+![Multi-source downloads](README_images/multi-source.png 'Multi-source downloads')
+
+**Download queue**
+![Download queue](README_images/downloads.png 'Download queue')
 
 ## 🚀 Quick Start
 
 ### Prerequisites
 
-- Docker
-- Docker Compose
-- A running instance of [Calibre-Web-Automated](https://github.com/crocodilestick/Calibre-Web-Automated) (recommended)
+- Docker & Docker Compose
 
-### Installation Steps
-
-1. Get the docker-compose.yml:
+### Installation
 
+1. Download the [docker-compose file](compose/docker-compose.yml):
    ```bash
-   curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/refs/heads/main/docker-compose.yml
+   curl -O https://raw.githubusercontent.com/calibrain/shelfmark/main/compose/docker-compose.yml
    ```
 
 2. Start the service:
-
    ```bash
    docker compose up -d
    ```
 
-3. Access the web interface at `http://localhost:8084`
+3. Open `http://localhost:8084`
 
-## ⚙️ Configuration
+That's it! Configure settings through the web interface as needed.
 
-### Environment Variables
-
-#### Application Settings
-
-| Variable          | Description             | Default Value      |
-| ----------------- | ----------------------- | ------------------ |
-| `FLASK_PORT`      | Web interface port      | `8084`             |
-| `FLASK_HOST`      | Web interface binding   | `0.0.0.0`          |
-| `DEBUG`           | Debug mode toggle       | `false`            |
-| `INGEST_DIR`      | Book download directory | `/cwa-book-ingest` |
-| `TZ`              | Container timezone      | `UTC`              |
-| `UID`             | Runtime user ID         | `1000`             |
-| `GID`             | Runtime group ID        | `100`              |
-| `CWA_DB_PATH`     | Calibre-Web's database  | None               |
-| `ENABLE_LOGGING`  | Enable log file         | `true`             |
-| `LOG_LEVEL`       | Log level to use        | `info`             |
-| `SESSION_COOKIE_SECURE` | Secure cookie enforcement - Use for HTTPS connections only | `false` |
-| `CALIBRE_WEB_URL` | Custom WebUI library link | None |
-| `BYPASS_WARMUP_ON_CONNECT` | Warm up Cloudflare bypasser when first client connects | `true` |
-
-If you wish to enable authentication, you must set `CWA_DB_PATH` to point to Calibre-Web's `app.db`, in order to match the username and password.
-
-Set `CALIBRE_WEB_URL` to your Calibre-Web / Booklore base URL. A ‘Go to library’ button will appear in the Web UI for quick access while downloading, and it also provides library access when CWA-BD is installed as a mobile PWA.
-
-If logging is enabled, log folder default location is `/var/log/cwa-book-downloader`
-Available log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Higher levels show fewer messages.
-
-Note that if using TOR, the TZ will be calculated automatically based on IP.
-
-#### Download Settings
-
-| Variable               | Description                                               | Default Value                     |
-| ---------------------- | --------------------------------------------------------- | --------------------------------- |
-| `MAX_RETRY`            | Maximum retry attempts                                    | `3`                               |
-| `DEFAULT_SLEEP`        | Retry delay (seconds)                                     | `5`                               |
-| `MAIN_LOOP_SLEEP_TIME` | Processing loop delay (seconds)                           | `5`                               |
-| `SUPPORTED_FORMATS`    | Supported book formats                                    | `epub,mobi,azw3,fb2,djvu,cbz,cbr` |
-| `BOOK_LANGUAGE`        | Preferred language for books                              | `en`                              |
-| `AA_DONATOR_KEY`       | Optional Donator key for Anna's Archive fast download API | ``                                |
-| `USE_BOOK_TITLE`       | Use book title as filename instead of ID                  | `false`                           |
-| `PRIORITIZE_WELIB`     | When downloading, download from WELIB first instead of AA | `false`                           |
-| `ALLOW_USE_WELIB`       | Allow usage of welib for downloading books if found there | `true`                            |
-
-If you change `BOOK_LANGUAGE`, you can add multiple comma separated languages, such as `en,fr,ru` etc.  
-
-Use the following environment variables to set specific folders in which to download 
-different content types (Book, Magazine, Comic, etc.):
-
-| Variable                        | Description                    | Default Value |
-|---------------------------------|--------------------------------|---------------|
-| `INGEST_DIR_BOOK_FICTION`       | Book (fiction) folder name     | ``            |
-| `INGEST_DIR_BOOK_NON_FICTION`   | Book (non-fiction) folder name | ``            |
-| `INGEST_DIR_BOOK_UNKNOWN`       | Book (unknown) folder name     | ``            |
-| `INGEST_DIR_MAGAZINE`           | Magazine folder name           | ``            |
-| `INGEST_DIR_COMIC_BOOK`         | Comic book folder name         | ``            |
-| `INGEST_DIR_AUDIOBOOK`          | Audiobook folder name          | ``            |
-| `INGEST_DIR_STANDARDS_DOCUMENT` | Standards document folder name | ``            |
-| `INGEST_DIR_MUSICAL_SCORE`      | Musical score folder name      | ``            |
-
-If no specific path is set for a content type the default is `INGEST_DIR`.  
-Remember to map the specified paths to where your instance of Calibre-Web-Automated (CWA) will find them, e.g.:  
-```
-volumes:
-    - /tmp/data/calibre-web/comicbook-ingest:/cwa-comicbook-ingest
-```
-if `INGEST_DIR_COMIC_BOOK=/cwa-comicbook-ingest` and your CWA is configured to use `/tmp/data/calibre-web/comicbook-ingest` 
-for comic books.
-
-
-#### AA 
-
-| Variable               | Description                                               | Default Value                     |
-| ---------------------- | --------------------------------------------------------- | --------------------------------- |
-| `AA_BASE_URL`          | Base URL of Annas-Archive (could be changed for a proxy)  | `https://annas-archive.org`       |
-| `USE_CF_BYPASS`        | Disable CF bypass and use alternative links instead       | `true`                            |
-
-If you are a donator on AA, you can use your Key in `AA_DONATOR_KEY` to speed up downloads and bypass the wait times.
-If disabling the cloudflare bypass, you will be using alternative download hosts, such as libgen or z-lib, but they usually have a delay before getting the more recent books and their collection is not as big as aa's. But this setting should work for the majority of books.
-
-#### Network Settings
-
-| Variable               | Description                     | Default Value           |
-| ---------------------- | ------------------------------- | ----------------------- |
-| `AA_ADDITIONAL_URLS`   | Proxy URLs for AA (, separated) | ``                      |
-| `HTTP_PROXY`           | HTTP proxy URL                  | ``                      |
-| `HTTPS_PROXY`          | HTTPS proxy URL                 | ``                      |
-| `CUSTOM_DNS`           | DNS configuration               | `auto`                  |
-| `USE_DOH`              | Use DNS over HTTPS              | `false`                 |
-
-**Proxy Configuration**
-
-For proxy configuration, you can specify URLs in the following format:
-```bash
-# Basic proxy
-HTTP_PROXY=http://proxy.example.com:8080
-HTTPS_PROXY=http://proxy.example.com:8080
-
-# Proxy with authentication
-HTTP_PROXY=http://username:password@proxy.example.com:8080
-HTTPS_PROXY=http://username:password@proxy.example.com:8080
-```
-
-**DNS Configuration**
-
-The `CUSTOM_DNS` setting controls how DNS resolution works. By default, it is set to `auto` which provides automatic failover for reliable connectivity.
-
-**Auto Mode (Default)**
-
-When `CUSTOM_DNS=auto`, the application starts with your system's default DNS. If DNS resolution fails, it automatically rotates through alternative providers using DNS over HTTPS (DoH):
-
-1. System DNS (initial)
-2. Cloudflare (1.1.1.1)
-3. Google (8.8.8.8)
-4. Quad9 (9.9.9.9)
-5. OpenDNS (208.67.222.222)
-
-This automatic rotation helps bypass ISP-level blocks and DNS issues without any manual configuration.
-
-**Manual DNS Configuration**
-
-If you prefer to use a specific DNS configuration, you can override the auto behavior:
-
-1. **Preset DNS Providers**: Use one of these predefined options:
-   - `google` - Google DNS (8.8.8.8, 8.8.4.4)
-   - `quad9` - Quad9 DNS (9.9.9.9, 149.112.112.112)
-   - `cloudflare` - Cloudflare DNS (1.1.1.1, 1.0.0.1)
-   - `opendns` - OpenDNS (208.67.222.222, 208.67.220.220)
-
-2. **Custom DNS Servers**: A comma-separated list of DNS server IP addresses
-   - Example: `127.0.0.53,127.0.1.53` (useful for PiHole)
-   - Supports both IPv4 and IPv6 addresses
-
-When using preset providers, you can optionally enable DNS over HTTPS with `USE_DOH=true`:
-```bash
-CUSTOM_DNS=cloudflare
-USE_DOH=true
-```
-
-Note: When using custom IP addresses, the `USE_DOH` flag is ignored since DoH requires a known provider endpoint.
-
-#### Custom configuration
-
-| Variable               | Description                                                 | Default Value           |
-| ---------------------- | ----------------------------------------------------------- | ----------------------- |
-| `CUSTOM_SCRIPT`        | Path to an executable script that tuns after each download  | ``                      |
-
-If `CUSTOM_SCRIPT` is set, it will be executed after each successful download but before the file is moved to the ingest directory. This allows for custom processing like format conversion or validation.
-
-The script is called with the full path of the downloaded file as its argument. Important notes:
-- The script must preserve the original filename for proper processing
-- The file can be modified or even deleted if needed
-- The file will be moved to `/cwa-book-ingest` after the script execution (if not deleted)
-
-You can specify these configuration in this format :
-```
-environment:
-  - CUSTOM_SCRIPT=/scripts/process-book.sh
-
-volumes:
-  - local/scripts/custom_script.sh:/scripts/process-book.sh
-```
-
-### Volume Configuration
+### Volume Setup
 
 ```yaml
 volumes:
-  - /your/local/path:/cwa-book-ingest
-  - /cwa/config/path/app.db:/auth/app.db:ro
+  - /your/config/path:/config # Config, database, and artwork cache directory
+  - /your/download/path:/books # Downloaded books
+  - /client/path:/client/path # Optional: For Torrent/Usenet downloads, match your client directory exactly. 
 ```
-**Note** - If your library volume is on a cifs share, you will get a "database locked" error until you add **nobrl** to your mount line in your fstab file. e.g. //192.168.1.1/Books /media/books cifs credentials=.smbcredentials,uid=1000,gid=1000,iocharset=utf8,**nobrl** - See https://github.com/crocodilestick/Calibre-Web-Automated/issues/64#issuecomment-2712769777
 
-Mount should align with your Calibre-Web-Automated ingest folder.
+> **Tip**: Point the download volume to your CWA or Booklore ingest folder for automatic import.
 
-## Variants:
+> **Note**: CIFS shares require `nobrl` mount option to avoid database lock errors.
 
-### 🧅 Tor Variant
+## ⚙️ Configuration
 
-This application also offers a variant that routes all its traffic through the Tor network. This can be useful for enhanced privacy or bypassing network restrictions.
+### Search Modes
 
-To use the Tor variant:
+**Direct** (default)
+- Works out of the box, no setup required
+- Searches a huge library of books directly
+- Returns downloadable releases immediately
 
-1.  Get the Tor-specific docker-compose file:
-    ```bash
-    curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/refs/heads/main/docker-compose.tor.yml
-    ```
-2.  Start the service using this file:
-    ```bash
-    docker compose -f docker-compose.tor.yml up -d
-    ```
+**Universal**
+- Cleaner search results via metadata providers (Hardcover is recommended)
+- Aggregates releases from multiple configured sources
+- Full Audiobook support
+- Requires manual setup (API keys, additional sources)
 
-**Important Considerations for Tor:**
+### Environment Variables
 
-*   **Capabilities:** This variant requires the `NET_ADMIN` and `NET_RAW` Docker capabilities to configure `iptables` for transparent Tor proxying.
-*   **Timezone:** When running in Tor mode, the container will attempt to determine the timezone based on the Tor exit node's IP address and set it automatically. This will override the `TZ` environment variable if it is set.
-*   **Network Settings:** Custom DNS, DoH, and HTTP(S) proxy settings (`CUSTOM_DNS`, `USE_DOH`, `HTTP_PROXY`, `HTTPS_PROXY`) are ignored when using the Tor variant, as all traffic goes through Tor.
+Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.
 
-### External Cloudflare resolver variant
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FLASK_PORT` | Web interface port | `8084` |
+| `INGEST_DIR` | Book download directory | `/books` |
+| `TZ` | Container timezone | `UTC` |
+| `PUID` / `PGID` | Runtime user/group ID (also supports legacy `UID`/`GID`) | `1000` / `1000` |
+| `SEARCH_MODE` | `direct` or `universal` | `direct` |
+| `USING_TOR` | Enable Tor routing (requires `NET_ADMIN` capability) | `false` |
 
-This variant allows the application to use an external service to bypass Cloudflare protection, instead of relying on the built-in bypasser. This is useful if you already have a dedicated Cloudflare resolver (such as [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) or compatible services like [ByParr](https://github.com/ThePhaseless/Byparr)) running elsewhere.
+See the full [Environment Variables Reference](docs/environment-variables.md) for all available options.
 
-#### How it works:
+Some of the additional options available in Settings:
+- **Fast Download Key** - Use your paid account to skip Cloudflare challenges entirely and use faster, direct downloads
+- **Prowlarr** - Configure indexers and download clients to download books and audiobooks
+- **AudiobookBay** - Web scraping source for audiobook torrents (audiobooks only)
+- **IRC** - Add details for IRC book sources and download directly from the UI
+- **Library Link** - Add a link to your Calibre-Web or Booklore instance in the UI header
+- **File processing** - Customiseable download paths, file renaming and directory creation with template-based renaming
+- **Network Resilience** - Auto DNS rotation and mirror fallback when sources are unreachable. Custom proxy support (SOCK5 + HTTP/S), Tor routing.
+- **Format & Language** - Filter downloads by preferred formats, languages and sorting order
+- **Metadata Providers** - Configure API keys for Hardcover, Open Library, etc.
 
-- When enabled, all requests that require Cloudflare bypass are sent to your external resolver service.
-- The application communicates with the resolver using its API.
+## 🐳 Docker Variants
 
-#### Configuration
-
-| Variable               | Description                                                 | Default Value           |
-| ---------------------- | ----------------------------------------------------------- | ----------------------- |
-| `EXT_BYPASSER_URL`     | The full URL of your external resolver (required)           |                         |
-| `EXT_BYPASSER_PATH`    | API path for the resolver (usually `/v1`)                   | `/v1`                   |
-| `EXT_BYPASSER_TIMEOUT` | Timeout for page loading (in milliseconds)                  | `60000`                 |
-
-#### Important
-
-This feature follows the same configuration of the built-in Cloudflare bypasser, so you should turn on the `USE_CF_BYPASS` configuration to enable it.
-
-#### To use the External Cloudflare resolver variant:
-
-1.  Get the extbp-specific docker-compose file:
-    ```bash
-    curl -O https://raw.githubusercontent.com/calibrain/calibre-web-automated-book-downloader/refs/heads/main/docker-compose.extbp.yml
-    ```
-2.  Start the service using this file:
-    ```bash
-    docker compose -f docker-compose.extbp.yml up -d
-    ```
-
-#### Compatibility:
-This feature is designed to work with any resolver that implements the `FlareSolverr` API schema, including `ByParr` and similar projects.
-
-#### Internal vs External Bypasser
-
-The **internal bypasser** (default) is custom-designed for this application's specific needs. It handles session management, cookie persistence, and retry logic optimized for book downloading workflows. For most users, this provides the most reliable experience out of the box.
-
-The **external bypasser** is better suited if you:
-- Already run FlareSolverr/ByParr for other services and want to consolidate
-- Need to share bypass infrastructure across multiple applications
-- Want to offload browser automation to a dedicated, more powerful container
-
-If you're unsure which to use, start with the default internal bypasser.
-
-## 🏗️ Architecture
-
-The application consists of a Flask backend with a React-based frontend:
-
-### Backend
-- **Flask Application**: Python-based backend (`app.py`, `backend.py`) providing REST API and WebSocket support
-- **Download Manager**: Handles book search, download requests, and queue management (`downloader.py`, `book_manager.py`)
-- **Network Layer**: Cloudflare bypass and proxy support (`cloudflare_bypasser.py`, `network.py`)
-
-### Frontend
-- **React + TypeScript**: Modern web interface built with Vite (`src/frontend`)
-- **Real-time Updates**: WebSocket integration for live download status
-- **Responsive UI**: TailwindCSS-based design for mobile and desktop
-
-For frontend development, use the provided Makefile:
+### Standard
 ```bash
-make install  # Install dependencies
-make dev      # Start development server
-make build    # Build for production
-```
-If you run the docker compose file, the frontend will be built and served automatically. But if you run the frontend dev server it will supercede the docker compose frontend.
-
-## 🏥 Health Monitoring
-
-Built-in health checks monitor:
-
-- Web interface availability
-- Download service status
-- Cloudflare bypass service connection
-
-Checks run every 30 seconds with a 30-second timeout and 3 retries.
-You can enable by adding this to your compose :
-```
-HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
-    CMD curl -s http://localhost:8084/api/status || exit 1
+docker compose up -d
 ```
 
-## 📝 Logging
+The full-featured image with built-in Cloudflare bypass.
 
-Logs are available in:
+#### Enable Tor Routing
+Routes all traffic through Tor for enhanced privacy:
+```bash
+curl -O https://raw.githubusercontent.com/calibrain/shelfmark/main/compose/docker-compose.tor.yml
+docker compose -f docker-compose.tor.yml up -d
+```
 
-- Container: `/var/logs/cwa-book-downloader.log`
-- Docker logs: Access via `docker logs`
+**Notes:**
+- Requires `NET_ADMIN` and `NET_RAW` capabilities
+- Timezone is auto-detected from Tor exit node
+- Custom DNS/proxy settings are ignored when Tor is active
 
-## 🤝 Contributing
+### Lite
+A smaller image without the built-in Cloudflare bypasser. Ideal for:
 
-Contributions are welcome! Feel free to submit a Pull Request.
+- **External bypassers** - Already running FlareSolverr or ByParr for other services
+- **Fast downloads** - Using fast download sources
+- **Alternative sources only** - Exclusively using Prowlarr, AudiobookBay, IRC, or other sources
+- **Audiobooks** - Using Shelfmark exclusively for audiobooks
 
-## 📄 License
+```bash
+curl -O https://raw.githubusercontent.com/calibrain/shelfmark/main/compose/docker-compose.lite.yml
+docker compose -f docker-compose.lite.yml up -d
+```
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+If you need Cloudflare bypass with the Lite image, configure an external resolver (FlareSolverr/ByParr) in Settings under the Cloudflare tab.
 
-## ⚠️ Important Disclaimers
+## 🔐 Authentication
 
-### Copyright Notice
+Authentication is optional but recommended for shared or exposed instances. Multiple authentication methods are available in Settings:
 
-While this tool can access various sources including those that might contain copyrighted material (e.g., Anna's Archive), it is designed for legitimate use only. Users are responsible for:
+**1. Single Username/Password**
 
-- Ensuring they have the right to download requested materials
-- Respecting copyright laws and intellectual property rights
-- Using the tool in compliance with their local regulations
+**2. Proxy (Forward) Authentication**
 
-### Duplicate Downloads Warning
+Proxy auth trusts headers set by your reverse proxy (e.g. `X-Auth-User`). Ensure Shelfmark is not directly exposed, and configure your proxy to strip/overwrite these headers for all inbound requests.
 
-Please note that the current version:
+**3. OIDC (OpenID Connect)**
 
-- Does not check for existing files in the download directory
-- Does not verify if books already exist in your Calibre database
-- Exercise caution when requesting multiple books to avoid duplicates
+Integrate with your identity provider (Authelia, Authentik, Keycloak, etc.) for single sign-on. Supports PKCE flow, auto-discovery, group-based admin mapping, and auto-provisioning of new users.
 
-## 💬 Support
+**4. Calibre-Web Database**
 
-For issues or questions, please file an issue on the GitHub repository.
+If you're running Calibre-Web, you can reuse its user database by mounting it:
 
+```yaml
+volumes:
+  - /path/to/calibre-web/app.db:/auth/app.db:ro
+```
+
+### Multi-User Support
+
+With any authentication method enabled, Shelfmark supports multi-user management with admin/user roles. Users can have per-user settings for download destinations, email recipients, and notification preferences. Non-admin users only see their own downloads and can submit book requests for admin review. Admins can configure request policies per source to control whether users can download directly, must submit a request, or are blocked entirely.
+
+## Project Scope
+
+Shelfmark is a manual search and download tool, the entry point to your book library, not a library manager. It finds books, downloads them, and sends them to a configured destination. That's the full scope.
+
+Shelfmark intentionally does not:
+
+- **Track or manage your library** - it doesn't know or care what you already own
+- **Integrate with library software** - what happens after delivery is up to your library tool
+- **Monitor authors, series, or new releases** - there is no background automation
+- **Queue future downloads** - if a book isn't available now, Shelfmark won't watch for it
+
+These are non-goals, not missing features.
+
+## Contributing
+
+Shelfmark's core feature set is complete. Development focuses on stability, bug fixes, quality-of-life improvements, and refining the search experience. Contributions in these areas are welcome, please file issues or submit pull requests on GitHub.
+
+Feature requests that fall outside the project scope (library integration, automation, collection management) will be closed. If you're unsure whether something fits, open a discussion first.
+
+## Health Monitoring
+
+The application exposes a health endpoint at `/api/health` (no authentication required). Add a health check to your compose:
+
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-sf", "http://localhost:8084/api/health"]
+  interval: 30s
+  timeout: 30s
+  retries: 3
+```
+
+## Logging
+
+Logs are available via:
+- `docker logs <container-name>`
+- `/var/log/shelfmark/` inside the container (when `ENABLE_LOGGING=true`)
+
+Log level is configurable via Settings or `LOG_LEVEL` environment variable.
+
+## Development
+
+```bash
+# Frontend development
+make install     # Install dependencies
+make dev         # Start Vite dev server (localhost:5173)
+make build       # Production build
+make typecheck   # TypeScript checks
+
+# Backend (Docker)
+make up          # Start backend via docker-compose.dev.yml
+make down        # Stop services
+make refresh     # Rebuild and restart
+make restart     # Restart container
+```
+
+The frontend dev server proxies to the backend on port 8084.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## ⚠️ Disclaimer
+
+Shelfmark is a search interface that displays results from external metadata providers and sources. It does not host, store, or distribute any content. The developers are not responsible for how the tool is used or what is accessed through it.
+
+Users are solely responsible for:
+- Ensuring they have the legal right to download any material they access
+- Complying with copyright laws and intellectual property rights in their jurisdiction
+- Understanding and accepting the terms of any sources they configure
+
+Use of this tool is entirely at your own risk.
+
+## Support
+
+For issues or questions, please [file an issue](https://github.com/calibrain/shelfmark/issues) on GitHub.

requirements-base.txt

@@ -3,6 +3,7 @@ flask-cors
 flask-socketio
 python-socketio
 requests[socks]
+defusedxml
 beautifulsoup4
 tqdm
 dnspython
@@ -12,3 +13,7 @@ gevent-websocket
 psutil
 emoji
 rarfile
+qbittorrent-api
+transmission-rpc
+authlib>=1.6.6,<1.7
+apprise>=1.9.0

requirements-shelfmark.txt

@@ -1,4 +1,4 @@
 pyvirtualdisplay
 pyautogui
-seleniumbase>=4.41.1
+seleniumbase==4.45.10
 python-xlib

scripts/fix_permissions.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Fix permissions on all configured directories.
+
+This script is called by the entrypoint to ensure all user-configured
+directories have correct ownership. It reads directory paths from:
+- CONFIG_DIR environment variable
+- Config files in CONFIG_DIR/plugins/
+
+Outputs directory paths that need permission fixing (one per line).
+The entrypoint handles the actual chown operations.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def get_directories_from_config() -> set[str]:
+    """Extract all directory paths from config files."""
+    directories = set()
+
+    config_dir = Path(os.getenv("CONFIG_DIR", "/config"))
+    plugins_dir = config_dir / "plugins"
+
+    if not plugins_dir.exists():
+        return directories
+
+    # Keys that contain directory paths
+    directory_keys = {
+        # Main destinations
+        "DESTINATION",
+        "DESTINATION_AUDIOBOOK",
+        # Content type routing directories
+        "AA_CONTENT_TYPE_DIR_FICTION",
+        "AA_CONTENT_TYPE_DIR_NON_FICTION",
+        "AA_CONTENT_TYPE_DIR_UNKNOWN",
+        "AA_CONTENT_TYPE_DIR_MAGAZINE",
+        "AA_CONTENT_TYPE_DIR_COMIC",
+        "AA_CONTENT_TYPE_DIR_STANDARDS",
+        "AA_CONTENT_TYPE_DIR_MUSICAL_SCORE",
+        "AA_CONTENT_TYPE_DIR_OTHER",
+        # Legacy keys (in case of old configs)
+        "INGEST_DIR",
+        "INGEST_DIR_AUDIOBOOK",
+        "INGEST_DIR_BOOK_FICTION",
+        "INGEST_DIR_BOOK_NON_FICTION",
+        "INGEST_DIR_BOOK_UNKNOWN",
+        "INGEST_DIR_MAGAZINE",
+        "INGEST_DIR_COMIC_BOOK",
+        "INGEST_DIR_STANDARDS_DOCUMENT",
+        "INGEST_DIR_MUSICAL_SCORE",
+        "INGEST_DIR_OTHER",
+        "LIBRARY_PATH",
+        "LIBRARY_PATH_AUDIOBOOK",
+    }
+
+    # Read all JSON config files
+    for config_file in plugins_dir.glob("*.json"):
+        try:
+            with open(config_file, "r") as f:
+                config = json.load(f)
+
+            for key in directory_keys:
+                if key in config:
+                    value = config[key]
+                    if value and isinstance(value, str) and value.startswith("/"):
+                        directories.add(value)
+        except (json.JSONDecodeError, OSError):
+            continue
+
+    return directories
+
+
+def main():
+    """Output all configured directories that exist."""
+    directories = get_directories_from_config()
+
+    # Filter to directories that actually exist
+    existing = []
+    for dir_path in directories:
+        path = Path(dir_path)
+        if path.exists() and path.is_dir():
+            existing.append(dir_path)
+
+    # Output one directory per line
+    for dir_path in sorted(existing):
+        print(dir_path)
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_env_docs.py

@@ -0,0 +1,440 @@
+#!/usr/bin/env python3
+"""Generate markdown documentation for environment variables from the settings registry.
+
+This script extracts all settings that support environment variable configuration
+and generates a comprehensive markdown file documenting each option.
+
+Usage:
+    python scripts/generate_env_docs.py [--output path/to/output.md]
+
+The generated documentation includes:
+- Environment variable name
+- Description
+- Type (string, number, boolean, etc.)
+- Default value
+- Organizational grouping by settings tab/group
+"""
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Add project root to path
+project_root = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(project_root))
+
+
+def get_field_type_name(field) -> str:
+    """Get a human-readable type name for a field."""
+    from shelfmark.core.settings_registry import (
+        CheckboxField,
+        MultiSelectField,
+        NumberField,
+        OrderableListField,
+        PasswordField,
+        SelectField,
+        TextField,
+    )
+
+    if isinstance(field, CheckboxField):
+        return "boolean"
+    elif isinstance(field, NumberField):
+        return "number"
+    elif isinstance(field, SelectField):
+        return "string (choice)"
+    elif isinstance(field, MultiSelectField):
+        return "string (comma-separated)"
+    elif isinstance(field, OrderableListField):
+        return "JSON array"
+    elif isinstance(field, PasswordField):
+        return "string (secret)"
+    elif isinstance(field, TextField):
+        return "string"
+    else:
+        return "string"
+
+
+def format_default_value(field) -> str:
+    """Format the default value for display."""
+    default = field.default
+
+    if default is None:
+        return "_none_"
+    elif isinstance(default, bool):
+        return f"`{str(default).lower()}`"
+    elif isinstance(default, (int, float)):
+        return f"`{default}`"
+    elif isinstance(default, str):
+        if default == "":
+            return "_empty string_"
+        return f"`{default}`"
+    elif isinstance(default, list):
+        if not default:
+            return "_empty list_"
+        # For simple lists, show comma-separated values
+        if all(isinstance(item, str) for item in default):
+            return f"`{','.join(default)}`"
+        # For complex lists (e.g., OrderableListField defaults), summarize
+        return f"_see UI for defaults_"
+    else:
+        return f"`{default}`"
+
+
+def get_select_options(field) -> Optional[List[str]]:
+    """Get the available options for a SelectField.
+
+    Returns options formatted as 'value (label)' or just 'value' if they match,
+    so users know the actual values to use in environment variables.
+    """
+    from shelfmark.core.settings_registry import SelectField
+
+    if not isinstance(field, SelectField):
+        return None
+
+    options = field.options
+    if callable(options):
+        try:
+            options = options()
+        except Exception:
+            return None
+
+    if not options:
+        return None
+
+    result = []
+    for opt in options:
+        value = opt.get("value", "")
+        label = opt.get("label", "")
+
+        # Format as "value (label)" unless they're the same or value is empty
+        if value == "":
+            result.append(f'`""` ({label})')
+        elif value == label or not label:
+            result.append(f"`{value}`")
+        else:
+            result.append(f"`{value}` ({label})")
+
+    return result
+
+
+def _generate_bootstrap_env_docs() -> List[str]:
+    """Generate documentation for bootstrap environment variables from env.py."""
+    # These are environment variables defined in env.py that are used before
+    # the settings registry is available
+    bootstrap_vars = [
+        {
+            "name": "CONFIG_DIR",
+            "description": "Directory for storing configuration files and plugin settings.",
+            "type": "string (path)",
+            "default": "/config",
+        },
+        {
+            "name": "LOG_ROOT",
+            "description": "Root directory for log files.",
+            "type": "string (path)",
+            "default": "/var/log/",
+        },
+        {
+            "name": "TMP_DIR",
+            "description": "Staging directory for downloads before moving to destination.",
+            "type": "string (path)",
+            "default": "/tmp/shelfmark",
+        },
+        {
+            "name": "ENABLE_LOGGING",
+            "description": "Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs).",
+            "type": "boolean",
+            "default": "true",
+        },
+        {
+            "name": "FLASK_HOST",
+            "description": "Host address for the Flask web server.",
+            "type": "string",
+            "default": "0.0.0.0",
+        },
+        {
+            "name": "FLASK_PORT",
+            "description": "Port number for the Flask web server.",
+            "type": "number",
+            "default": "8084",
+        },
+        {
+            "name": "SESSION_COOKIE_SECURE",
+            "description": "Enable secure cookies (requires HTTPS).",
+            "type": "boolean",
+            "default": "false",
+        },
+        {
+            "name": "CWA_DB_PATH",
+            "description": "Path to the Calibre-Web database for authentication integration.",
+            "type": "string (path)",
+            "default": "/auth/app.db",
+        },
+        {
+            "name": "DOCKERMODE",
+            "description": "Indicates the application is running inside a Docker container.",
+            "type": "boolean",
+            "default": "false",
+        },
+        {
+            "name": "ONBOARDING",
+            "description": "Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage).",
+            "type": "boolean",
+            "default": "true",
+        },
+    ]
+
+    lines = [
+        "## Bootstrap Configuration",
+        "",
+        "These environment variables are used at startup before the settings system loads. They typically configure paths and server settings.",
+        "",
+        "| Variable | Description | Type | Default |",
+        "|----------|-------------|------|---------|",
+    ]
+
+    for var in bootstrap_vars:
+        lines.append(f"| `{var['name']}` | {var['description']} | {var['type']} | `{var['default']}` |")
+
+    lines.append("")
+    lines.append("<details>")
+    lines.append("<summary>Detailed descriptions</summary>")
+    lines.append("")
+
+    for var in bootstrap_vars:
+        lines.append(f"#### `{var['name']}`")
+        lines.append("")
+        lines.append(var["description"])
+        lines.append("")
+        lines.append(f"- **Type:** {var['type']}")
+        lines.append(f"- **Default:** `{var['default']}`")
+        lines.append("")
+
+    lines.append("</details>")
+    lines.append("")
+
+    return lines
+
+
+def generate_env_docs() -> str:
+    """Generate markdown documentation for all environment variables."""
+    # Import settings modules to ensure all settings are registered
+    import shelfmark.config.settings  # noqa: F401
+    import shelfmark.config.security  # noqa: F401
+    import shelfmark.release_sources.irc.settings  # noqa: F401
+    import shelfmark.release_sources.prowlarr.settings  # noqa: F401
+    import shelfmark.metadata_providers.hardcover  # noqa: F401
+    import shelfmark.metadata_providers.openlibrary  # noqa: F401
+    import shelfmark.metadata_providers.googlebooks  # noqa: F401
+
+    from shelfmark.core.settings_registry import (
+        ActionButton,
+        HeadingField,
+        get_all_groups,
+        get_all_settings_tabs,
+    )
+
+    tabs = get_all_settings_tabs()
+    groups = {g.name: g for g in get_all_groups()}
+
+    # Organize tabs by group
+    grouped_tabs: Dict[Optional[str], List] = {None: []}
+    for group_name in groups:
+        grouped_tabs[group_name] = []
+
+    for tab in tabs:
+        group_name = tab.group
+        if group_name not in grouped_tabs:
+            grouped_tabs[group_name] = []
+        grouped_tabs[group_name].append(tab)
+
+    # Build markdown output
+    lines = [
+        "# Environment Variables",
+        "",
+        "This document lists all configuration options that can be set via environment variables.",
+        "",
+        "> **Auto-generated** - Do not edit manually. Run `python scripts/generate_env_docs.py` to regenerate.",
+        "",
+        "## Table of Contents",
+        "",
+    ]
+
+    # Generate TOC
+    toc_entries = [
+        "- [Bootstrap Configuration](#bootstrap-configuration)",
+    ]
+
+    # Ungrouped tabs first
+    for tab in grouped_tabs.get(None, []):
+        anchor = tab.display_name.lower().replace(" ", "-")
+        toc_entries.append(f"- [{tab.display_name}](#{anchor})")
+
+    # Then grouped tabs
+    for group_name, group in groups.items():
+        group_tabs = grouped_tabs.get(group_name, [])
+        if group_tabs:
+            anchor = group.display_name.lower().replace(" ", "-")
+            toc_entries.append(f"- [{group.display_name}](#{anchor})")
+            for tab in group_tabs:
+                sub_anchor = f"{group.display_name}-{tab.display_name}".lower().replace(" ", "-")
+                toc_entries.append(f"  - [{tab.display_name}](#{sub_anchor})")
+
+    lines.extend(toc_entries)
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    # Add bootstrap environment variables documentation
+    lines.extend(_generate_bootstrap_env_docs())
+
+    # Generate documentation for ungrouped tabs
+    for tab in grouped_tabs.get(None, []):
+        lines.extend(_generate_tab_docs(tab))
+
+    # Generate documentation for grouped tabs
+    for group_name, group in groups.items():
+        group_tabs = grouped_tabs.get(group_name, [])
+        if not group_tabs:
+            continue
+
+        lines.append(f"## {group.display_name}")
+        lines.append("")
+
+        for tab in group_tabs:
+            lines.extend(_generate_tab_docs(tab, group_prefix=group.display_name))
+
+    return "\n".join(lines)
+
+
+def _generate_tab_docs(tab, group_prefix: Optional[str] = None) -> List[str]:
+    """Generate documentation for a single settings tab."""
+    from shelfmark.core.settings_registry import ActionButton, CustomComponentField, HeadingField
+
+    lines = []
+
+    # Section header
+    if group_prefix:
+        lines.append(f"### {group_prefix}: {tab.display_name}")
+        anchor_id = f"{group_prefix}-{tab.display_name}".lower().replace(" ", "-")
+    else:
+        lines.append(f"## {tab.display_name}")
+
+    lines.append("")
+
+    # Collect env-supported fields
+    env_fields = []
+    for field in tab.fields:
+        # Skip non-value fields
+        if isinstance(field, (ActionButton, CustomComponentField, HeadingField)):
+            continue
+
+        # Skip fields that don't support ENV vars
+        if not getattr(field, "env_supported", True):
+            continue
+
+        env_fields.append(field)
+
+    if not env_fields:
+        lines.append("_No environment variables for this section._")
+        lines.append("")
+        return lines
+
+    # Generate table
+    lines.append("| Variable | Description | Type | Default |")
+    lines.append("|----------|-------------|------|---------|")
+
+    for field in env_fields:
+        env_var = field.get_env_var_name()
+        description = field.description or field.label
+        # Clean up description for table (remove newlines, escape pipes)
+        description = description.replace("\n", " ").replace("|", "\\|").strip()
+
+        field_type = get_field_type_name(field)
+        default = format_default_value(field)
+
+        lines.append(f"| `{env_var}` | {description} | {field_type} | {default} |")
+
+    lines.append("")
+
+    # Add detailed documentation for each field
+    lines.append("<details>")
+    lines.append("<summary>Detailed descriptions</summary>")
+    lines.append("")
+
+    for field in env_fields:
+        env_var = field.get_env_var_name()
+        lines.append(f"#### `{env_var}`")
+        lines.append("")
+        lines.append(f"**{field.label}**")
+        lines.append("")
+
+        if field.description:
+            lines.append(field.description)
+            lines.append("")
+
+        lines.append(f"- **Type:** {get_field_type_name(field)}")
+        lines.append(f"- **Default:** {format_default_value(field)}")
+
+        if getattr(field, "required", False):
+            lines.append("- **Required:** Yes")
+
+        if getattr(field, "requires_restart", False):
+            lines.append("- **Requires restart:** Yes")
+
+        # Show options for SelectField
+        options = get_select_options(field)
+        if options:
+            lines.append(f"- **Options:** {', '.join(options)}")
+
+        # Show constraints for NumberField
+        from shelfmark.core.settings_registry import NumberField
+        if isinstance(field, NumberField):
+            constraints = []
+            if field.min_value is not None:
+                constraints.append(f"min: {field.min_value}")
+            if field.max_value is not None:
+                constraints.append(f"max: {field.max_value}")
+            if constraints:
+                lines.append(f"- **Constraints:** {', '.join(constraints)}")
+
+        lines.append("")
+
+    lines.append("</details>")
+    lines.append("")
+
+    return lines
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate markdown documentation for environment variables"
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        default=project_root / "docs" / "environment-variables.md",
+        help="Output file path (default: docs/environment-variables.md)",
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Print to stdout instead of file",
+    )
+    args = parser.parse_args()
+
+    docs = generate_env_docs()
+
+    if args.stdout:
+        print(docs)
+    else:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(docs)
+        print(f"Generated: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/test_clients.py

@@ -0,0 +1,555 @@
+#!/usr/bin/env python3
+"""
+Test script for download client implementations.
+
+Usage:
+    1. Start the test stack:
+       docker compose -f docker-compose.test-clients.yml up -d
+
+    2. Wait for containers to initialize (first run takes ~30s)
+
+    3. Run this script to verify clients are accessible:
+       python scripts/test_clients.py
+
+    4. Access cwabd at http://localhost:8084
+       - Go to Settings > Prowlarr > Download Clients
+       - Select a client from the dropdown
+       - Click "Test Connection" to verify
+
+Web UIs:
+    - cwabd:        http://localhost:8084
+    - qBittorrent:  http://localhost:8080
+    - Transmission: http://localhost:9091
+    - Deluge:       http://localhost:8112
+    - NZBGet:       http://localhost:6789
+    - SABnzbd:      http://localhost:8085
+    - rTorrent:     http://localhost:8000 (web ui http://localhost:8089 via ruTorrent)
+
+Prerequisites (for running this script locally):
+    pip install requests transmission-rpc qbittorrent-api
+
+First-Time Setup:
+    qBittorrent:
+        - Check container logs for temporary password: docker logs test-qbittorrent
+        - Login at http://localhost:8080, change password to something known
+        - Default username is 'admin'
+
+    Transmission:
+        - No setup needed, credentials pre-configured (admin/admin)
+
+    Deluge:
+        - Access Web UI at http://localhost:8112 (default password: deluge)
+
+    NZBGet:
+        - No setup needed, credentials pre-configured (admin/admin)
+
+    SABnzbd:
+        - Complete the setup wizard at http://localhost:8085
+        - API key will be auto-detected by this script
+        - In cwabd, copy API key from SABnzbd Config > General
+"""
+
+import sys
+import time
+from xmlrpc import client
+
+# Test configuration - matches docker-compose.test-clients.yml
+CONFIG = {
+    # Usenet clients
+    "nzbget": {
+        "url": "http://localhost:6789",
+        "username": "admin",
+        "password": "admin",
+    },
+    "sabnzbd": {
+        "url": "http://localhost:8085",
+        "api_key": None,  # Will be read from config on first run
+    },
+    # Torrent clients
+    "qbittorrent": {
+        "url": "http://localhost:8080",
+        "username": "admin",
+        "password": "5NCngsHXm",  # Temp password from: docker logs test-qbittorrent | grep password
+    },
+    "transmission": {
+        "url": "http://localhost:9091",
+        "username": "admin",
+        "password": "admin",
+    },
+    "deluge": {
+        "url": "http://localhost:8112",
+        "password": "deluge",
+    },
+    "rtorrent": {
+        "url": "http://localhost:8000/RPC2",
+    },
+}
+
+# Test magnet link (Ubuntu ISO - legal, small metadata)
+TEST_MAGNET = "magnet:?xt=urn:btih:3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0&dn=ubuntu-22.04.3-live-server-amd64.iso"
+
+
+def test_nzbget():
+    """Test NZBGet connection."""
+    import requests
+
+    print("\n" + "=" * 50)
+    print("Testing NZBGet")
+    print("=" * 50)
+
+    url = CONFIG["nzbget"]["url"]
+    username = CONFIG["nzbget"]["username"]
+    password = CONFIG["nzbget"]["password"]
+
+    try:
+        # Test connection via JSON-RPC
+        rpc_url = f"{url}/jsonrpc"
+        response = requests.post(
+            rpc_url,
+            json={"method": "version", "params": []},
+            auth=(username, password),
+            timeout=10,
+        )
+        response.raise_for_status()
+        result = response.json()
+        version = result.get("result", "unknown")
+        print(f"  Connected to NZBGet {version}")
+
+        # Test status
+        response = requests.post(
+            rpc_url,
+            json={"method": "status", "params": []},
+            auth=(username, password),
+            timeout=10,
+        )
+        status = response.json().get("result", {})
+        print(f"  Server state: {'Paused' if status.get('ServerPaused') else 'Running'}")
+        print(f"  Downloads in queue: {status.get('DownloadedSizeMB', 0)} MB downloaded")
+
+        print("  SUCCESS: NZBGet is working!")
+        return True
+
+    except requests.exceptions.ConnectionError:
+        print("  ERROR: Could not connect to NZBGet")
+        print("  Is the container running? docker ps | grep nzbget")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        return False
+
+
+def test_sabnzbd():
+    """Test SABnzbd connection."""
+    import requests
+
+    print("\n" + "=" * 50)
+    print("Testing SABnzbd")
+    print("=" * 50)
+
+    url = CONFIG["sabnzbd"]["url"]
+    api_key = CONFIG["sabnzbd"]["api_key"]
+
+    # Try to get API key from config if not set
+    if not api_key:
+        try:
+            import os
+            ini_path = ".local/test-clients/sabnzbd/config/sabnzbd.ini"
+            if os.path.exists(ini_path):
+                with open(ini_path) as f:
+                    for line in f:
+                        if line.startswith("api_key"):
+                            api_key = line.split("=")[1].strip()
+                            print(f"  Found API key in config: {api_key[:8]}...")
+                            break
+        except Exception as e:
+            print(f"  Could not read API key from config: {e}")
+
+    if not api_key:
+        print("  ERROR: No API key configured")
+        print("  Please access http://localhost:8085 and complete initial setup")
+        print("  Then copy the API key from Config > General")
+        return False
+
+    try:
+        # Test connection
+        response = requests.get(
+            f"{url}/api",
+            params={"apikey": api_key, "mode": "version", "output": "json"},
+            timeout=10,
+        )
+        response.raise_for_status()
+        result = response.json()
+        version = result.get("version", "unknown")
+        print(f"  Connected to SABnzbd {version}")
+
+        # Test queue status
+        response = requests.get(
+            f"{url}/api",
+            params={"apikey": api_key, "mode": "queue", "output": "json"},
+            timeout=10,
+        )
+        queue = response.json().get("queue", {})
+        print(f"  Queue status: {queue.get('status', 'unknown')}")
+        print(f"  Items in queue: {len(queue.get('slots', []))}")
+
+        print("  SUCCESS: SABnzbd is working!")
+        return True
+
+    except requests.exceptions.ConnectionError:
+        print("  ERROR: Could not connect to SABnzbd")
+        print("  Is the container running? docker ps | grep sabnzbd")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        return False
+
+
+def test_qbittorrent():
+    """Test qBittorrent connection."""
+    print("\n" + "=" * 50)
+    print("Testing qBittorrent")
+    print("=" * 50)
+
+    try:
+        import qbittorrentapi
+
+        url = CONFIG["qbittorrent"]["url"]
+        username = CONFIG["qbittorrent"]["username"]
+        password = CONFIG["qbittorrent"]["password"]
+
+        # Parse URL for host/port
+        from urllib.parse import urlparse
+        parsed = urlparse(url)
+
+        client = qbittorrentapi.Client(
+            host=parsed.hostname,
+            port=parsed.port or 8080,
+            username=username,
+            password=password,
+        )
+
+        # Test connection
+        client.auth_log_in()
+        version = client.app.version
+        print(f"  Connected to qBittorrent {version}")
+
+        # Get torrent list
+        torrents = client.torrents_info()
+        print(f"  Active torrents: {len(torrents)}")
+
+        # Test adding a torrent (then remove it)
+        print("  Testing add/remove torrent...")
+        result = client.torrents_add(urls=TEST_MAGNET, is_paused=True)
+        if result == "Ok.":
+            # Wait a moment for it to be added
+            time.sleep(1)
+            torrents = client.torrents_info()
+            if torrents:
+                test_torrent = torrents[-1]  # Most recently added
+                print(f"  Added test torrent: {test_torrent.name[:50]}...")
+                print(f"  Status: {test_torrent.state}")
+
+                # Remove it
+                client.torrents_delete(torrent_hashes=test_torrent.hash, delete_files=True)
+                print("  Removed test torrent")
+        else:
+            print(f"  Add result: {result}")
+
+        print("  SUCCESS: qBittorrent is working!")
+        return True
+
+    except ImportError:
+        print("  ERROR: qbittorrent-api not installed")
+        print("  Run: pip install qbittorrent-api")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        if "Forbidden" in str(e) or "401" in str(e):
+            print("\n  Authentication failed. Check password:")
+            print("  1. docker logs test-qbittorrent | grep password")
+            print("  2. Login to http://localhost:8080 and set a known password")
+        return False
+
+
+def test_transmission():
+    """Test Transmission connection."""
+    print("\n" + "=" * 50)
+    print("Testing Transmission")
+    print("=" * 50)
+
+    try:
+        from transmission_rpc import Client
+        from urllib.parse import urlparse
+
+        url = CONFIG["transmission"]["url"]
+        parsed = urlparse(url)
+
+        client = Client(
+            host=parsed.hostname,
+            port=parsed.port or 9091,
+            username=CONFIG["transmission"]["username"],
+            password=CONFIG["transmission"]["password"],
+        )
+
+        # Test connection
+        session = client.get_session()
+        print(f"  Connected to Transmission {session.version}")
+
+        # Get torrent list
+        torrents = client.get_torrents()
+        print(f"  Active torrents: {len(torrents)}")
+
+        # Test adding a torrent (then remove it)
+        print("  Testing add/remove torrent...")
+        torrent = client.add_torrent(TEST_MAGNET, paused=True)
+        print(f"  Added test torrent: {torrent.name[:50]}...")
+
+        # Get status
+        status = client.get_torrent(torrent.id)
+        print(f"  Status: {status.status} ({status.percent_done * 100:.1f}%)")
+
+        # Remove it
+        client.remove_torrent(torrent.id, delete_data=True)
+        print("  Removed test torrent")
+
+        print("  SUCCESS: Transmission is working!")
+        return True
+
+    except ImportError:
+        print("  ERROR: transmission-rpc not installed")
+        print("  Run: pip install transmission-rpc")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        return False
+
+
+def test_deluge():
+    """Test Deluge Web UI (JSON-RPC) connection."""
+    import requests
+
+    print("\n" + "=" * 50)
+    print("Testing Deluge")
+    print("=" * 50)
+
+    base_url = CONFIG["deluge"]["url"].rstrip("/")
+    password = CONFIG["deluge"]["password"]
+    rpc_url = f"{base_url}/json"
+
+    def rpc_call(session: requests.Session, rpc_id: int, method: str, *params):
+        payload = {"id": rpc_id, "method": method, "params": list(params)}
+        resp = session.post(rpc_url, json=payload, timeout=10)
+        resp.raise_for_status()
+        data = resp.json()
+        if data.get("error"):
+            err = data["error"]
+            if isinstance(err, dict):
+                raise Exception(err.get("message") or str(err))
+            raise Exception(str(err))
+        return data.get("result")
+
+    try:
+        session = requests.Session()
+
+        # Authenticate to Deluge Web
+        if rpc_call(session, 1, "auth.login", password) is not True:
+            raise Exception("Authentication failed (check Deluge Web UI password)")
+
+        # Ensure Deluge Web is connected to a daemon
+        if rpc_call(session, 2, "web.connected") is not True:
+            hosts = rpc_call(session, 3, "web.get_hosts") or []
+            if not hosts:
+                raise Exception(
+                    "Deluge Web UI isn't connected to Deluge core (no hosts configured). "
+                    "Add/connect a daemon in Deluge Web UI → Connection Manager."
+                )
+
+            host_id = hosts[0][0]
+            for entry in hosts:
+                if isinstance(entry, list) and len(entry) >= 2 and entry[1] in {"127.0.0.1", "localhost"}:
+                    host_id = entry[0]
+                    break
+
+            rpc_call(session, 4, "web.connect", host_id)
+
+            if rpc_call(session, 5, "web.connected") is not True:
+                raise Exception(
+                    "Deluge Web UI couldn't connect to Deluge core. "
+                    "Check Deluge Web UI → Connection Manager."
+                )
+
+        version = rpc_call(session, 6, "daemon.info")
+        print(f"  Connected to Deluge {version}")
+
+        torrents = rpc_call(session, 7, "core.get_torrents_status", {}, ["name"]) or {}
+        print(f"  Active torrents: {len(torrents)}")
+
+        # Test adding a torrent (then remove it)
+        print("  Testing add/remove torrent...")
+        torrent_id = rpc_call(session, 8, "core.add_torrent_magnet", TEST_MAGNET, {"add_paused": True})
+
+        if torrent_id:
+            torrent_id = str(torrent_id)
+            print(f"  Added test torrent: {torrent_id[:20]}...")
+
+            status = rpc_call(session, 9, "core.get_torrent_status", torrent_id, ["state", "progress"]) or {}
+            state = status.get("state", "unknown") if isinstance(status, dict) else "unknown"
+            progress = status.get("progress", 0) if isinstance(status, dict) else 0
+            print(f"  Status: {state} ({progress:.1f}%)")
+
+            rpc_call(session, 10, "core.remove_torrent", torrent_id, True)
+            print("  Removed test torrent")
+        else:
+            print("  WARNING: Could not add test torrent")
+
+        print("  SUCCESS: Deluge is working!")
+        return True
+
+    except requests.exceptions.ConnectionError:
+        print("  ERROR: Could not connect to Deluge Web UI")
+        print("  Is the container running? docker ps | grep deluge")
+        return False
+    except requests.exceptions.Timeout:
+        print("  ERROR: Deluge Web UI connection timed out")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        if "auth" in str(e).lower() or "login" in str(e).lower():
+            print("  Check Deluge Web UI password (default: deluge)")
+        return False
+
+def test_rtorrent():
+    """Test rTorrent connection."""
+    print("\n" + "=" * 50)
+    print("Testing rTorrent")
+    print("=" * 50)
+
+    try:
+        import xmlrpc.client
+
+        url = "http://localhost:8000/RPC2"
+        client = xmlrpc.client.ServerProxy(url)
+
+        # Test connection
+        version = client.system.library_version()
+        print(f"  Connected to rTorrent {version}")
+
+        # default download directory test
+        default_dir = client.directory.default()
+        print(f"  Default download directory: {default_dir}")
+
+        # Get torrent list
+        torrents = client.download_list()
+        print(f"  Active torrents: {len(torrents)}")
+
+        # Test adding a torrent (then remove it)
+        print("  Testing add/remove torrent...")
+
+        label = "automated"
+
+        commands = []
+        if label:
+            commands.append(f"d.custom1.set={label}")
+
+        download_dir = "/downloads"
+        if download_dir:
+            commands.append(f"d.directory_base.set={download_dir}")
+
+        # rtorrent is weird in that it doesn't return the torrent ID/hash on add
+        client.load.start("", TEST_MAGNET, ";".join(commands))
+        
+        # but we know that it is 3b245504cf5f11bbdbe1201cea6a6bf45aee1bc0 from the magnet link
+        torrent_id = "3B245504CF5F11BBDBE1201CEA6A6BF45AEE1BC0" # rtorrent uses uppercase hashes
+        print(f"  Added test torrent: {torrent_id}")
+
+        torrents = client.download_list()
+        print(f"  Active torrents: {len(torrents)}")        
+
+        torrent_list = client.d.multicall.filtered(
+            "",
+            "default",
+            f"equal={{d.hash=,cat={torrent_id}}}"
+            "d.hash=",
+            "d.state=",
+            "d.completed_bytes=",
+            "d.size_bytes=",
+            "d.down.rate=",
+            "d.up.rate=",
+            "d.custom1=",
+            "d.complete=",
+        )
+        torrent = torrent_list[0]
+
+        if not torrent:
+            print("  ERROR: Could not find added torrent in list")
+            return False
+        
+        # let's test the base path call
+        details = client.d.multicall.filtered(
+            "",
+            "default",
+            f"equal=d.hash=,cat={torrent_id}",
+            "d.base_path=",
+        )
+
+        base_path = details[0][0] if details else None
+
+        print(f"  Base path: {base_path}")
+        client.d.erase(torrent_id)
+        print("  Removed test torrent")
+
+        print("  SUCCESS: rTorrent is working!")
+        return True
+
+    except ImportError:
+        print("  ERROR: xmlrpc.client not available")
+        return False
+    except Exception as e:
+        print(f"  ERROR: {e}")
+        if "Connection refused" in str(e):
+            print("  Is the container running? docker ps | grep rtorrent")
+        return False
+
+
+def main():
+    print("Download Client Test Suite")
+    print("=" * 50)
+    print("Make sure containers are running:")
+    print("  docker compose -f docker-compose.test-clients.yml up -d")
+
+    results = {}
+
+    # Test usenet clients
+    print("\n" + "=" * 50)
+    print("USENET CLIENTS")
+    print("=" * 50)
+    results["nzbget"] = test_nzbget()
+    results["sabnzbd"] = test_sabnzbd()
+
+    # Test torrent clients
+    print("\n" + "=" * 50)
+    print("TORRENT CLIENTS")
+    print("=" * 50)
+    results["qbittorrent"] = test_qbittorrent()
+    results["transmission"] = test_transmission()
+    results["deluge"] = test_deluge()
+    results["rtorrent"] = test_rtorrent()
+
+    # Summary
+    print("\n" + "=" * 50)
+    print("SUMMARY")
+    print("=" * 50)
+
+    for client, success in results.items():
+        status = "PASS" if success else "FAIL"
+        print(f"  {client}: {status}")
+
+    passed = sum(results.values())
+    total = len(results)
+    print(f"\n  Total: {passed}/{total} passed")
+
+    return 0 if passed == total else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shelfmark/__init__.py

@@ -0,0 +1 @@
+"""Shelfmark - book search and download service."""

shelfmark/__main__.py

@@ -0,0 +1,8 @@
+"""Package entry point for `python -m shelfmark`."""
+
+from shelfmark.main import app, socketio
+from shelfmark.config.env import FLASK_HOST, FLASK_PORT
+from shelfmark.core.config import config
+
+if __name__ == "__main__":
+    socketio.run(app, host=FLASK_HOST, port=FLASK_PORT, debug=config.get("DEBUG", False))

shelfmark/api/websocket.py

@@ -4,7 +4,7 @@ import logging
 import threading
 from typing import Optional, Dict, Any, Callable, List
 
-from flask_socketio import SocketIO
+from flask_socketio import SocketIO, join_room, leave_room
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +20,10 @@ class WebSocketManager:
         self._on_first_connect_callbacks: List[Callable[[], None]] = []
         self._on_all_disconnect_callbacks: List[Callable[[], None]] = []
         self._needs_rewarm = False  # Flag to trigger warmup callbacks on next connect
+        self._user_rooms: Dict[str, int] = {}  # room_name -> ref count
+        self._sid_rooms: Dict[str, str] = {}  # sid -> room_name
+        self._rooms_lock = threading.Lock()
+        self._queue_status_fn: Optional[Callable] = None  # Reference to queue_status()
 
     def init_app(self, app, socketio: SocketIO):
         """Initialize the WebSocket manager with Flask-SocketIO instance."""
@@ -28,29 +32,17 @@ class WebSocketManager:
         logger.info("WebSocket manager initialized")
 
     def register_on_first_connect(self, callback: Callable[[], None]):
-        """Register a callback to be called when the first client connects.
-
-        This is useful for warming up resources (like the Cloudflare bypasser)
-        when a user starts using the web UI.
-        """
+        """Register a callback for when the first client connects."""
         self._on_first_connect_callbacks.append(callback)
         logger.debug(f"Registered on_first_connect callback: {callback.__name__}")
 
     def register_on_all_disconnect(self, callback: Callable[[], None]):
-        """Register a callback to be called when all clients disconnect.
-
-        This can be used to trigger cleanup or resource release.
-        """
+        """Register a callback for when all clients disconnect."""
         self._on_all_disconnect_callbacks.append(callback)
         logger.debug(f"Registered on_all_disconnect callback: {callback.__name__}")
 
     def request_warmup_on_next_connect(self):
-        """Request that warmup callbacks be triggered on the next client connect.
-
-        This is used when resources (like the Cloudflare bypasser) shut down due to
-        inactivity while clients are still connected. The next connect event should
-        trigger warmup even though it's not technically the "first" connection.
-        """
+        """Request warmup callbacks on the next client connect (e.g., after idle shutdown)."""
         with self._connection_lock:
             self._needs_rewarm = True
             logger.debug("Warmup requested for next client connect")
@@ -112,19 +104,86 @@ class WebSocketManager:
         """Check if WebSocket is enabled and ready."""
         return self._enabled and self.socketio is not None
 
+    def set_queue_status_fn(self, fn: Callable):
+        """Set the queue_status function reference for per-room filtering."""
+        self._queue_status_fn = fn
+
+    def _increment_user_room_locked(self, room: str):
+        self._user_rooms[room] = self._user_rooms.get(room, 0) + 1
+
+    def _decrement_user_room_locked(self, room: str):
+        count = self._user_rooms.get(room, 1) - 1
+        if count <= 0:
+            self._user_rooms.pop(room, None)
+        else:
+            self._user_rooms[room] = count
+
+    def _set_sid_room_locked(self, sid: str, room: Optional[str]):
+        current_room = self._sid_rooms.get(sid)
+        if current_room == room:
+            return
+
+        if current_room is not None:
+            leave_room(current_room, sid=sid)
+            if current_room.startswith("user_"):
+                self._decrement_user_room_locked(current_room)
+            self._sid_rooms.pop(sid, None)
+
+        if room is not None:
+            join_room(room, sid=sid)
+            self._sid_rooms[sid] = room
+            if room.startswith("user_"):
+                self._increment_user_room_locked(room)
+
+    def sync_user_room(self, sid: str, is_admin: bool, db_user_id: Optional[int] = None):
+        """Ensure a SID is in exactly one room matching the current session scope."""
+        room: Optional[str] = None
+        if is_admin:
+            room = "admins"
+        elif db_user_id is not None:
+            room = f"user_{db_user_id}"
+
+        with self._rooms_lock:
+            self._set_sid_room_locked(sid, room)
+
+    def join_user_room(self, sid: str, is_admin: bool, db_user_id: Optional[int] = None):
+        """Join the appropriate room based on user role."""
+        self.sync_user_room(sid, is_admin, db_user_id)
+
+    def leave_user_room(self, sid: str, is_admin: bool = False, db_user_id: Optional[int] = None):
+        """Leave whichever room the SID currently belongs to."""
+        del is_admin, db_user_id  # Backward-compatible signature; routing is SID-based.
+        with self._rooms_lock:
+            self._set_sid_room_locked(sid, None)
+
     def broadcast_status_update(self, status_data: Dict[str, Any]):
-        """Broadcast status update to all connected clients."""
+        """Broadcast status update to all connected clients, filtered by user room."""
         if not self.is_enabled():
             return
 
         try:
-            # When calling socketio.emit() outside event handlers, it broadcasts by default
-            self.socketio.emit('status_update', status_data)
-            logger.debug(f"Broadcasted status update to all clients")
+            # Admins (and no-auth users) get full status
+            self.socketio.emit('status_update', status_data, to="admins")
+
+            # Each user room gets filtered status
+            with self._rooms_lock:
+                active_rooms = list(self._user_rooms.keys())
+
+            if active_rooms and self._queue_status_fn:
+                for room in active_rooms:
+                    try:
+                        # Extract user_id from room name "user_123"
+                        uid = int(room.split("_", 1)[1])
+                        filtered = self._queue_status_fn(user_id=uid)
+                        self.socketio.emit('status_update', filtered, to=room)
+                    except Exception as e:
+                        logger.error(f"Failed to send status update for room {room}: {e}")
+
+            logger.debug("Broadcasted status update to all rooms")
         except Exception as e:
             logger.error(f"Error broadcasting status update: {e}")
 
-    def broadcast_download_progress(self, book_id: str, progress: float, status: str):
+    def broadcast_download_progress(self, book_id: str, progress: float, status: str, user_id: Optional[int] = None):
         """Broadcast download progress update for a specific book."""
         if not self.is_enabled():
             return
@@ -135,8 +194,14 @@ class WebSocketManager:
                 'progress': progress,
                 'status': status
             }
-            # When calling socketio.emit() outside event handlers, it broadcasts by default
-            self.socketio.emit('download_progress', data)
+            # Admins always see all progress
+            self.socketio.emit('download_progress', data, to="admins")
+            # If task belongs to a specific user, send to their room too
+            if user_id is not None:
+                room = f"user_{user_id}"
+                with self._rooms_lock:
+                    if room in self._user_rooms:
+                        self.socketio.emit('download_progress', data, to=room)
             logger.debug(f"Broadcasted progress for book {book_id}: {progress}%")
         except Exception as e:
             logger.error(f"Error broadcasting download progress: {e}")
@@ -157,6 +222,30 @@ class WebSocketManager:
         except Exception as e:
             logger.error(f"Error broadcasting notification: {e}")
 
+    def broadcast_search_status(
+        self,
+        source: str,
+        provider: str,
+        book_id: str,
+        message: str,
+        phase: str = 'searching'
+    ):
+        """Broadcast search status update for a release source search."""
+        if not self.is_enabled():
+            return
+
+        try:
+            data = {
+                'source': source,
+                'provider': provider,
+                'book_id': book_id,
+                'message': message,
+                'phase': phase,
+            }
+            self.socketio.emit('search_status', data)
+        except Exception as e:
+            logger.error(f"Error broadcasting search status: {e}")
+
 
 # Global WebSocket manager instance
 ws_manager = WebSocketManager()

shelfmark/bypass/__init__.py

@@ -0,0 +1,5 @@
+"""Cloudflare bypass utilities."""
+
+
+class BypassCancelledException(Exception):
+    """Raised when a bypass operation is cancelled."""

shelfmark/bypass/external_bypasser.py

@@ -0,0 +1,130 @@
+"""External Cloudflare bypasser using FlareSolverr."""
+
+import random
+import time
+from threading import Event
+from typing import TYPE_CHECKING, Optional
+
+import requests
+
+from shelfmark.bypass import BypassCancelledException
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.utils import normalize_http_url
+from shelfmark.download.network import get_ssl_verify
+
+if TYPE_CHECKING:
+    from shelfmark.download import network
+
+logger = setup_logger(__name__)
+
+# Timeout constants (seconds)
+CONNECT_TIMEOUT = 10
+MAX_READ_TIMEOUT = 120
+READ_TIMEOUT_BUFFER = 15
+
+# Retry settings
+MAX_RETRY = 5
+BACKOFF_BASE = 1.0
+BACKOFF_CAP = 10.0
+
+
+def _fetch_via_bypasser(target_url: str) -> Optional[str]:
+    """Make a single request to the external bypasser service. Returns HTML or None."""
+    raw_bypasser_url = config.get("EXT_BYPASSER_URL", "http://flaresolverr:8191")
+    bypasser_path = config.get("EXT_BYPASSER_PATH", "/v1")
+    bypasser_timeout = config.get("EXT_BYPASSER_TIMEOUT", 60000)
+
+    bypasser_url = normalize_http_url(raw_bypasser_url)
+    if not bypasser_url or not bypasser_path:
+        logger.error("External bypasser not configured. Check EXT_BYPASSER_URL and EXT_BYPASSER_PATH.")
+        return None
+
+    read_timeout = min((bypasser_timeout / 1000) + READ_TIMEOUT_BUFFER, MAX_READ_TIMEOUT)
+
+    try:
+        response = requests.post(
+            f"{bypasser_url}{bypasser_path}",
+            headers={"Content-Type": "application/json"},
+            json={"cmd": "request.get", "url": target_url, "maxTimeout": bypasser_timeout},
+            timeout=(CONNECT_TIMEOUT, read_timeout),
+            verify=get_ssl_verify(bypasser_url),
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        status = result.get('status', 'unknown')
+        message = result.get('message', '')
+        logger.debug(f"External bypasser response for '{target_url}': {status} - {message}")
+
+        if status != 'ok':
+            logger.warning(f"External bypasser failed for '{target_url}': {status} - {message}")
+            return None
+
+        solution = result.get('solution')
+        html = solution.get('response', '') if solution else ''
+
+        if not html:
+            logger.warning(f"External bypasser returned empty response for '{target_url}'")
+            return None
+
+        return html
+
+    except requests.exceptions.Timeout:
+        logger.warning(f"External bypasser timed out for '{target_url}' (connect: {CONNECT_TIMEOUT}s, read: {read_timeout:.0f}s)")
+    except requests.exceptions.RequestException as e:
+        logger.warning(f"External bypasser request failed for '{target_url}': {e}")
+    except (KeyError, TypeError, ValueError) as e:
+        logger.warning(f"External bypasser returned malformed response for '{target_url}': {e}")
+
+    return None
+
+
+def _check_cancelled(cancel_flag: Optional[Event], context: str) -> None:
+    """Check if operation was cancelled and raise exception if so."""
+    if cancel_flag and cancel_flag.is_set():
+        logger.info(f"External bypasser cancelled {context}")
+        raise BypassCancelledException("Bypass cancelled")
+
+
+def _sleep_with_cancellation(seconds: float, cancel_flag: Optional[Event]) -> None:
+    """Sleep for the specified duration, checking for cancellation each second."""
+    for _ in range(int(seconds)):
+        _check_cancelled(cancel_flag, "during backoff")
+        time.sleep(1)
+    remaining = seconds - int(seconds)
+    if remaining > 0:
+        time.sleep(remaining)
+
+
+def get_bypassed_page(
+    url: str,
+    selector: Optional["network.AAMirrorSelector"] = None,
+    cancel_flag: Optional[Event] = None
+) -> Optional[str]:
+    """Fetch HTML via external bypasser with retries and mirror rotation."""
+    from shelfmark.download import network as network_module
+
+    sel = selector or network_module.AAMirrorSelector()
+
+    for attempt in range(1, MAX_RETRY + 1):
+        _check_cancelled(cancel_flag, "by user")
+
+        attempt_url = sel.rewrite(url)
+        result = _fetch_via_bypasser(attempt_url)
+        if result:
+            return result
+
+        if attempt == MAX_RETRY:
+            break
+
+        delay = min(BACKOFF_CAP, BACKOFF_BASE * (2 ** (attempt - 1))) + random.random()
+        logger.info(f"External bypasser attempt {attempt}/{MAX_RETRY} failed, retrying in {delay:.1f}s")
+
+        _sleep_with_cancellation(delay, cancel_flag)
+
+        new_base, action = sel.next_mirror_or_rotate_dns()
+        if action in ("mirror", "dns") and new_base:
+            logger.info(f"Rotated {action} for retry")
+
+    return None

shelfmark/bypass/fingerprint.py

@@ -0,0 +1,57 @@
+"""Browser fingerprint profile management for bypass stealth."""
+
+import random
+from typing import Optional
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+COMMON_RESOLUTIONS = [
+    (1920, 1080, 0.35),  
+    (1366, 768, 0.18),   
+    (1536, 864, 0.10),   
+    (1440, 900, 0.08),   
+    (1280, 720, 0.07),   
+    (1600, 900, 0.06),   
+    (1280, 800, 0.05),   
+    (2560, 1440, 0.04),  
+    (1680, 1050, 0.04),  
+    (1920, 1200, 0.03),  
+]
+
+# Current screen size (module-level singleton)
+_current_screen_size: Optional[tuple[int, int]] = None
+
+
+def get_screen_size() -> tuple[int, int]:
+    global _current_screen_size
+    if _current_screen_size is None:
+        _current_screen_size = _generate_screen_size()
+        logger.debug(f"Generated initial screen size: {_current_screen_size[0]}x{_current_screen_size[1]}")
+    return _current_screen_size
+
+
+def rotate_screen_size() -> tuple[int, int]:
+    global _current_screen_size
+    old_size = _current_screen_size
+    _current_screen_size = _generate_screen_size()
+    width, height = _current_screen_size
+
+    if old_size:
+        logger.info(f"Rotated screen size: {old_size[0]}x{old_size[1]} -> {width}x{height}")
+    else:
+        logger.info(f"Generated screen size: {width}x{height}")
+
+    return _current_screen_size
+
+
+def clear_screen_size() -> None:
+    global _current_screen_size
+    _current_screen_size = None
+
+
+def _generate_screen_size() -> tuple[int, int]:
+    resolutions = [(w, h) for w, h, _ in COMMON_RESOLUTIONS]
+    weights = [weight for _, _, weight in COMMON_RESOLUTIONS]
+    return random.choices(resolutions, weights=weights)[0]

shelfmark/bypass/internal_bypasser.py

@@ -0,0 +1,974 @@
+import asyncio
+import os
+import random
+import signal
+import socket
+import subprocess
+import threading
+import time
+import traceback
+from datetime import datetime
+from threading import Event
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+import requests
+from seleniumbase import cdp_driver
+
+from shelfmark.bypass import BypassCancelledException
+from shelfmark.bypass.fingerprint import get_screen_size
+from shelfmark.config import env
+from shelfmark.config.env import LOG_DIR
+from shelfmark.config.settings import RECORDING_DIR
+from shelfmark.core.config import config as app_config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download import network
+from shelfmark.download.network import get_proxies, get_ssl_verify
+
+logger = setup_logger(__name__)
+
+# Challenge detection indicators
+CLOUDFLARE_INDICATORS = [
+    "just a moment",
+    "verify you are human",
+    "verifying you are human",
+    "cloudflare.com/products/turnstile",
+]
+
+DDOS_GUARD_INDICATORS = [
+    "ddos-guard",
+    "ddos guard",
+    "checking your browser before accessing",
+    "complete the manual check to continue",
+    "could not verify your browser automatically",
+]
+
+DISPLAY = {
+    "ffmpeg": None,
+    "ffmpeg_output": None,
+}
+LOCKED = threading.Lock()
+
+
+class _CdpWorker:
+    def __init__(self) -> None:
+        self._thread: Optional[threading.Thread] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._ready = threading.Event()
+        self._lock = threading.Lock()
+
+    def _run(self) -> None:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+        self._ready.set()
+        loop.run_forever()
+        try:
+            pending = asyncio.all_tasks(loop)
+            for task in pending:
+                task.cancel()
+            if pending:
+                loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+        except Exception:
+            pass
+        finally:
+            loop.close()
+
+    def start(self) -> None:
+        with self._lock:
+            if self._thread and self._thread.is_alive():
+                return
+            self._ready.clear()
+            self._thread = threading.Thread(
+                target=self._run,
+                name="cdp-worker",
+                daemon=True,
+            )
+            self._thread.start()
+        if not self._ready.wait(timeout=10):
+            raise RuntimeError("CDP worker loop failed to start")
+
+    def run(self, coro: Any, timeout: Optional[float] = None) -> Any:
+        self.start()
+        if not self._loop or self._loop.is_closed():
+            raise RuntimeError("CDP worker loop not available")
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result(timeout=timeout)
+
+
+_CDP_WORKER = _CdpWorker()
+
+# Cookie storage - shared with requests library for Cloudflare bypass
+# Structure: {domain: {cookie_name: {value, expiry, ...}}}
+_cf_cookies: dict[str, dict] = {}
+_cf_cookies_lock = threading.Lock()
+
+# User-Agent storage - Cloudflare ties cf_clearance to the UA that solved the challenge
+_cf_user_agents: dict[str, str] = {}
+
+# Protection cookie names we care about (Cloudflare and DDoS-Guard)
+CF_COOKIE_NAMES = {'cf_clearance', '__cf_bm', 'cf_chl_2', 'cf_chl_prog'}
+DDG_COOKIE_NAMES = {'__ddg1_', '__ddg2_', '__ddg5_', '__ddg8_', '__ddg9_', '__ddg10_', '__ddgid_', '__ddgmark_', 'ddg_last_challenge'}
+
+# Domains requiring full session cookies (not just protection cookies)
+FULL_COOKIE_DOMAINS = {'z-lib.fm', 'z-lib.gs', 'z-lib.id', 'z-library.sk', 'zlibrary-global.se'}
+
+
+def _get_base_domain(domain: str) -> str:
+    """Extract base domain from hostname (e.g., 'www.example.com' -> 'example.com')."""
+    return '.'.join(domain.split('.')[-2:]) if '.' in domain else domain
+
+
+def _should_extract_cookie(name: str, extract_all: bool) -> bool:
+    """Determine if a cookie should be extracted based on its name."""
+    if extract_all:
+        return True
+    is_cf = name in CF_COOKIE_NAMES or name.startswith('cf_')
+    is_ddg = name in DDG_COOKIE_NAMES or name.startswith('__ddg')
+    return is_cf or is_ddg
+
+
+def _store_extracted_cookies(
+    *,
+    url: str,
+    cookies: list[Any],
+    user_agent: Optional[str] = None,
+) -> None:
+    """Store filtered bypass cookies (and optional UA) for a URL domain."""
+    parsed = urlparse(url)
+    domain = parsed.hostname or ""
+    if not domain:
+        return
+
+    base_domain = _get_base_domain(domain)
+    extract_all = base_domain in FULL_COOKIE_DOMAINS
+
+    cookies_found: dict[str, dict[str, Any]] = {}
+    for cookie in cookies:
+        name = getattr(cookie, "name", "") or ""
+        if not _should_extract_cookie(name, extract_all):
+            continue
+        expires = getattr(cookie, "expires", None)
+        if expires is not None and expires <= 0:
+            expires = None
+        cookies_found[name] = {
+            "value": getattr(cookie, "value", ""),
+            "domain": getattr(cookie, "domain", None) or domain,
+            "path": getattr(cookie, "path", None) or "/",
+            "expiry": expires,
+            "secure": bool(getattr(cookie, "secure", True)),
+            "httpOnly": True,
+        }
+
+    if not cookies_found:
+        return
+
+    with _cf_cookies_lock:
+        _cf_cookies[base_domain] = cookies_found
+        if user_agent:
+            _cf_user_agents[base_domain] = user_agent
+            logger.debug(f"Stored UA for {base_domain}: {str(user_agent)[:60]}...")
+        else:
+            logger.debug(f"No UA captured for {base_domain}")
+
+    cookie_type = "all" if extract_all else "protection"
+    logger.debug(f"Extracted {len(cookies_found)} {cookie_type} cookies for {base_domain}")
+
+
+async def _extract_cookies_from_cdp(driver, page, url: str) -> None:
+    """Extract cookies from a CDP browser after successful bypass."""
+    try:
+        try:
+            all_cookies = await driver.cookies.get_all(requests_cookie_format=True)
+        except Exception as e:
+            logger.debug(f"Failed to get cookies via CDP: {e}")
+            return
+
+        try:
+            user_agent = await page.evaluate("navigator.userAgent")
+        except Exception:
+            user_agent = None
+
+        _store_extracted_cookies(url=url, cookies=all_cookies, user_agent=user_agent)
+
+    except Exception as e:
+        logger.debug(f"Failed to extract cookies: {e}")
+
+def get_cf_cookies_for_domain(domain: str) -> dict[str, str]:
+    """Get stored cookies for a domain. Returns empty dict if none available."""
+    if not domain:
+        return {}
+
+    base_domain = _get_base_domain(domain)
+
+    with _cf_cookies_lock:
+        cookies = _cf_cookies.get(base_domain, {})
+        if not cookies:
+            return {}
+
+        cf_clearance = cookies.get('cf_clearance', {})
+        if cf_clearance:
+            expiry = cf_clearance.get('expiry')
+            if expiry is None:
+                expiry = cf_clearance.get('expires')
+            if expiry and expiry > 0 and time.time() > expiry:
+                logger.debug(f"CF cookies expired for {base_domain}")
+                _cf_cookies.pop(base_domain, None)
+                return {}
+
+        return {name: c['value'] for name, c in cookies.items()}
+
+
+def has_valid_cf_cookies(domain: str) -> bool:
+    """Check if we have valid Cloudflare cookies for a domain."""
+    return bool(get_cf_cookies_for_domain(domain))
+
+
+def get_cf_user_agent_for_domain(domain: str) -> Optional[str]:
+    """Get the User-Agent that was used during bypass for a domain."""
+    if not domain:
+        return None
+    with _cf_cookies_lock:
+        return _cf_user_agents.get(_get_base_domain(domain))
+
+
+def clear_cf_cookies(domain: str = None) -> None:
+    """Clear stored Cloudflare cookies and User-Agent. If domain is None, clear all."""
+    with _cf_cookies_lock:
+        if domain:
+            base_domain = _get_base_domain(domain)
+            _cf_cookies.pop(base_domain, None)
+            _cf_user_agents.pop(base_domain, None)
+        else:
+            _cf_cookies.clear()
+            _cf_user_agents.clear()
+
+
+def _cleanup_orphan_processes() -> int:
+    """Kill orphan Chrome/Xvfb/ffmpeg processes. Only runs in Docker mode."""
+    if not env.DOCKERMODE:
+        return 0
+
+    _stop_ffmpeg_recording()
+
+    processes_to_kill = ["chrome", "chromium", "Xvfb", "ffmpeg"]
+    total_killed = 0
+
+    logger.debug("Checking for orphan processes...")
+    logger.log_resource_usage()
+
+    for proc_name in processes_to_kill:
+        try:
+            result = subprocess.run(
+                ["pgrep", "-f", proc_name],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode != 0 or not result.stdout.strip():
+                continue
+
+            pids = result.stdout.strip().split('\n')
+            count = len(pids)
+            logger.info(f"Found {count} orphan {proc_name} process(es), killing...")
+
+            kill_result = subprocess.run(
+                ["pkill", "-9", "-f", proc_name],
+                capture_output=True,
+                timeout=5
+            )
+            if kill_result.returncode == 0:
+                total_killed += count
+            else:
+                logger.warning(f"pkill for {proc_name} returned {kill_result.returncode}")
+
+        except subprocess.TimeoutExpired:
+            logger.warning(f"Timeout while checking for {proc_name} processes")
+        except Exception as e:
+            logger.debug(f"Error checking for {proc_name} processes: {e}")
+
+    if total_killed > 0:
+        time.sleep(1)
+        logger.info(f"Cleaned up {total_killed} orphan process(es)")
+        logger.log_resource_usage()
+    else:
+        logger.debug("No orphan processes found")
+
+    return total_killed
+
+async def _get_page_info(page) -> tuple[str, str, str]:
+    """Extract page title, body text, and current URL safely."""
+    try:
+        title = (await page.get_title() or "").lower()
+    except Exception:
+        title = ""
+    try:
+        body = await page.evaluate("document.body ? document.body.innerText : ''")
+        body = (body or "").lower()
+    except Exception:
+        body = ""
+    try:
+        current_url = await page.get_current_url() or ""
+    except Exception:
+        current_url = ""
+    return title, body, current_url
+
+
+def _check_indicators(title: str, body: str, indicators: list[str]) -> Optional[str]:
+    """Check if any indicator is present in title or body. Returns the found indicator or None."""
+    for indicator in indicators:
+        if indicator in title or indicator in body:
+            return indicator
+    return None
+
+def _has_cloudflare_patterns(body: str, url: str) -> bool:
+    """Check for Cloudflare-specific patterns in body or URL."""
+    return "cf-" in body or "cloudflare" in url.lower() or "/cdn-cgi/" in url
+
+async def _detect_challenge_type(page) -> str:
+    """Detect challenge type: 'cloudflare', 'ddos_guard', or 'none'."""
+    try:
+        title, body, current_url = await _get_page_info(page)
+
+        # DDOS-Guard indicators
+        if found := _check_indicators(title, body, DDOS_GUARD_INDICATORS):
+            logger.debug(f"DDOS-Guard indicator found: '{found}'")
+            return "ddos_guard"
+
+        # Cloudflare indicators
+        if found := _check_indicators(title, body, CLOUDFLARE_INDICATORS):
+            logger.debug(f"Cloudflare indicator found: '{found}'")
+            return "cloudflare"
+
+        # Check URL patterns
+        if _has_cloudflare_patterns(body, current_url):
+            return "cloudflare"
+
+        return "none"
+    except Exception as e:
+        logger.warning(f"Error detecting challenge type: {e}")
+        return "none"
+
+async def _is_bypassed(page, escape_emojis: bool = True) -> bool:
+    """Check if the protection has been bypassed."""
+    try:
+        title, body, current_url = await _get_page_info(page)
+        body_len = len(body.strip())
+
+        # Long page content = probably bypassed
+        if body_len > 100000:
+            logger.debug(f"Page content too long, probably bypassed (len: {body_len})")
+            return True
+
+        # Multiple emojis = probably real content
+        if escape_emojis:
+            import emoji
+            if len(emoji.emoji_list(body)) >= 3:
+                logger.debug("Detected emojis in page, probably bypassed")
+                return True
+
+        # Check for protection indicators (means NOT bypassed)
+        if _check_indicators(title, body, CLOUDFLARE_INDICATORS + DDOS_GUARD_INDICATORS):
+            return False
+
+        # Cloudflare URL patterns
+        if _has_cloudflare_patterns(body, current_url):
+            logger.debug("Cloudflare patterns detected in page")
+            return False
+
+        # Page too short = still loading
+        if body_len < 50:
+            logger.debug("Page content too short, might still be loading")
+            return False
+
+        logger.debug(f"Bypass check passed - Title: '{title[:100]}', Body length: {body_len}")
+        return True
+
+    except Exception as e:
+        logger.warning(f"Error checking bypass status: {e}")
+        return False
+
+async def _bypass_method_humanlike(page) -> bool:
+    """Human-like behavior with scroll, wait, and reload."""
+    try:
+        logger.debug("Attempting bypass: human-like interaction")
+        await asyncio.sleep(random.uniform(6, 10))
+
+        try:
+            await page.evaluate("window.scrollTo(0, 10000);")
+            await page.wait()
+            await asyncio.sleep(random.uniform(1, 2))
+            await page.evaluate("window.scrollTo(0, 0);")
+            await page.wait()
+            await asyncio.sleep(random.uniform(2, 3))
+        except Exception as e:
+            logger.debug(f"Scroll behavior failed: {e}")
+
+        if await _is_bypassed(page):
+            return True
+
+        logger.debug("Trying page refresh...")
+        await page.reload(ignore_cache=True)
+        await asyncio.sleep(random.uniform(5, 8))
+
+        if await _is_bypassed(page):
+            return True
+
+        try:
+            await page.solve_captcha()
+            await asyncio.sleep(random.uniform(3, 5))
+        except Exception as e:
+            logger.debug(f"Final captcha click failed: {e}")
+
+        return await _is_bypassed(page)
+    except Exception as e:
+        logger.debug(f"Human-like method failed: {e}")
+        return False
+
+
+async def _bypass_method_cdp_solve(page) -> bool:
+    """CDP Mode with solve_captcha() - auto-detects challenge type."""
+    try:
+        logger.debug("Attempting bypass: CDP solve_captcha")
+        await page.solve_captcha()
+        await asyncio.sleep(random.uniform(3, 5))
+        return await _is_bypassed(page)
+    except Exception as e:
+        logger.debug(f"CDP solve_captcha failed: {e}")
+        return False
+
+
+CDP_CLICK_SELECTORS = [
+    "#turnstile-widget div",      # Cloudflare Turnstile
+    "#cf-turnstile div",          # Alternative CF Turnstile
+    "iframe[src*='challenges']",  # CF challenge iframe
+    "input[type='checkbox']",     # Generic checkbox (DDOS-Guard)
+    "[class*='checkbox']",        # Class-based checkbox
+    "#challenge-running",         # CF challenge indicator
+]
+
+
+async def _bypass_method_cdp_click(page) -> bool:
+    """CDP Mode with native clicking - no PyAutoGUI dependency."""
+    try:
+        logger.debug("Attempting bypass: CDP native click")
+
+        for selector in CDP_CLICK_SELECTORS:
+            try:
+                if not await page.is_element_visible(selector):
+                    continue
+
+                logger.debug(f"CDP clicking: {selector}")
+                await page.click(selector)
+                await asyncio.sleep(random.uniform(2, 4))
+
+                if await _is_bypassed(page):
+                    return True
+            except Exception as e:
+                logger.debug(f"CDP click on '{selector}' failed: {e}")
+
+        return await _is_bypassed(page)
+    except Exception as e:
+        logger.debug(f"CDP Mode click failed: {e}")
+        return False
+
+
+CDP_GUI_CLICK_SELECTORS = [
+    "#turnstile-widget div",      # Cloudflare Turnstile
+    "#cf-turnstile div",          # Alternative CF Turnstile
+    "#challenge-stage div",       # CF challenge stage
+    "input[type='checkbox']",     # Generic checkbox
+    "[class*='cb-i']",            # DDOS-Guard checkbox
+]
+
+
+async def _bypass_method_cdp_gui_click(page) -> bool:
+    """CDP Mode with gui_click-style behavior."""
+    try:
+        logger.debug("Attempting bypass: CDP gui_click (mouse-based)")
+
+        try:
+            logger.debug("Trying solve_captcha()")
+            await page.solve_captcha()
+            await asyncio.sleep(random.uniform(3, 5))
+
+            if await _is_bypassed(page):
+                return True
+        except Exception as e:
+            logger.debug(f"solve_captcha() failed: {e}")
+
+        for selector in CDP_GUI_CLICK_SELECTORS:
+            try:
+                if not await page.is_element_visible(selector):
+                    continue
+
+                logger.debug(f"CDP click_with_offset: {selector}")
+                await page.click_with_offset(selector, 0, 0, center=True)
+                await asyncio.sleep(random.uniform(3, 5))
+
+                if await _is_bypassed(page):
+                    return True
+            except Exception as e:
+                logger.debug(f"CDP gui_click on '{selector}' failed: {e}")
+
+        return await _is_bypassed(page)
+    except Exception as e:
+        logger.debug(f"CDP Mode gui_click failed: {e}")
+        return False
+
+
+BYPASS_METHODS = [
+    _bypass_method_cdp_solve,
+    _bypass_method_cdp_gui_click,
+    _bypass_method_cdp_click,
+    _bypass_method_humanlike,
+]
+
+MAX_CONSECUTIVE_SAME_CHALLENGE = 3
+
+
+def _check_cancellation(cancel_flag: Optional[Event], message: str) -> None:
+    """Check if cancellation was requested and raise if so."""
+    if cancel_flag and cancel_flag.is_set():
+        logger.info(message)
+        raise BypassCancelledException("Bypass cancelled")
+
+
+async def _bypass(page, max_retries: Optional[int] = None, cancel_flag: Optional[Event] = None) -> bool:
+    """Attempt to bypass Cloudflare/DDOS-Guard protection using multiple methods."""
+    max_retries = max_retries if max_retries is not None else app_config.MAX_RETRY
+
+    last_challenge_type = None
+    consecutive_same_challenge = 0
+    # Allow at least one full pass through all bypass methods before aborting due to a "stuck" challenge.
+    min_same_challenge_before_abort = max(MAX_CONSECUTIVE_SAME_CHALLENGE, len(BYPASS_METHODS) + 1)
+
+    for try_count in range(max_retries):
+        _check_cancellation(cancel_flag, "Bypass cancelled by user")
+
+        if await _is_bypassed(page):
+            if try_count == 0:
+                logger.info("Page already bypassed")
+            return True
+
+        challenge_type = await _detect_challenge_type(page)
+        logger.debug(f"Challenge detected: {challenge_type}")
+
+        # No challenge detected but page doesn't look bypassed - wait and retry
+        if challenge_type == "none":
+            logger.info("No challenge detected, waiting for page to settle...")
+            await asyncio.sleep(random.uniform(2, 3))
+            if await _is_bypassed(page):
+                return True
+            # Try a simple refresh instead of captcha methods
+            try:
+                await page.reload(ignore_cache=True)
+                await asyncio.sleep(random.uniform(1, 2))
+                if await _is_bypassed(page):
+                    logger.info("Bypass successful after refresh")
+                    return True
+            except Exception as e:
+                logger.debug(f"Refresh during no-challenge wait failed: {e}")
+            continue
+
+        if challenge_type == last_challenge_type:
+            consecutive_same_challenge += 1
+            if consecutive_same_challenge >= min_same_challenge_before_abort:
+                logger.warning(
+                    f"Same challenge ({challenge_type}) detected {consecutive_same_challenge} times - aborting"
+                )
+                return False
+        else:
+            consecutive_same_challenge = 1
+        last_challenge_type = challenge_type
+
+        method = BYPASS_METHODS[try_count % len(BYPASS_METHODS)]
+        logger.info(f"Bypass attempt {try_count + 1}/{max_retries} using {method.__name__}")
+
+        if try_count > 0:
+            wait_time = min(random.uniform(2, 4) * try_count, 12)
+            logger.info(f"Waiting {wait_time:.1f}s before trying...")
+            for _ in range(int(wait_time)):
+                _check_cancellation(cancel_flag, "Bypass cancelled during wait")
+                await asyncio.sleep(1)
+            await asyncio.sleep(wait_time - int(wait_time))
+
+        try:
+            if await method(page):
+                logger.info(f"Bypass successful using {method.__name__}")
+                return True
+        except BypassCancelledException:
+            raise
+        except Exception as e:
+            logger.warning(f"Exception in {method.__name__}: {e}")
+
+        logger.info(f"Bypass method {method.__name__} failed.")
+
+    logger.warning("Exceeded maximum retries. Bypass failed.")
+    return False
+
+def _get_browser_args() -> list[str]:
+    """Build extra Chrome arguments, pre-resolving hostnames via patched DNS.
+
+    Pre-resolves AA hostnames and passes IPs to Chrome via --host-resolver-rules,
+    bypassing Chrome's DNS entirely for those hosts.
+    """
+    arguments = [
+        "--ignore-certificate-errors",
+        "--ignore-ssl-errors",
+        "--allow-running-insecure-content",
+        "--ignore-certificate-errors-spki-list",
+        "--ignore-certificate-errors-skip-list",
+        # Chrome 144+ disabled automatic SwiftShader fallback for WebGL (security reasons).
+        # Without this flag, WebGL is broken in headless/Docker which triggers bot detection.
+        # See: https://issues.chromium.org/issues/40277080
+        "--enable-unsafe-swiftshader",
+    ]
+
+    if app_config.get("DEBUG", False):
+        arguments.extend([
+            "--enable-logging",
+            "--v=1",
+            "--log-file=" + str(LOG_DIR / "chrome_browser.log")
+        ])
+
+    host_rules = _build_host_resolver_rules()
+    if host_rules:
+        arguments.append(f'--host-resolver-rules={", ".join(host_rules)}')
+        logger.debug(f"Chrome: Using host resolver rules for {len(host_rules)} hosts")
+    else:
+        logger.warning("Chrome: No hosts could be pre-resolved")
+
+    return arguments
+
+
+def _build_host_resolver_rules() -> list[str]:
+    """Pre-resolve AA hostnames and build Chrome host resolver rules."""
+    host_rules = []
+
+    try:
+        for url in network.get_available_aa_urls():
+            hostname = urlparse(url).hostname
+            if not hostname:
+                continue
+
+            try:
+                results = socket.getaddrinfo(hostname, 443, socket.AF_INET)
+                if results:
+                    ip = results[0][4][0]
+                    host_rules.append(f"MAP {hostname} {ip}")
+                    logger.debug(f"Chrome: Pre-resolved {hostname} -> {ip}")
+                else:
+                    logger.warning(f"Chrome: No addresses returned for {hostname}")
+            except socket.gaierror as e:
+                logger.warning(f"Chrome: Could not pre-resolve {hostname}: {e}")
+    except Exception as e:
+        logger.error_trace(f"Error pre-resolving hostnames for Chrome: {e}")
+
+    return host_rules
+
+DRIVER_RESET_ERRORS = {"ProtocolException", "RuntimeError", "TimeoutError"}
+
+
+async def _get(url: str, driver, cancel_flag: Optional[Event] = None) -> str:
+    """Fetch URL with Cloudflare bypass using a CDP browser."""
+    _check_cancellation(cancel_flag, "Bypass cancelled before starting")
+
+    logger.debug(f"CDP_GET: {url}")
+
+    logger.debug("Opening URL with SeleniumBase CDP...")
+    page = await driver.get(url)
+    try:
+        await page.wait()
+    except Exception:
+        pass
+
+    _check_cancellation(cancel_flag, "Bypass cancelled after page load")
+
+    try:
+        current_url = await page.get_current_url()
+        title = await page.get_title()
+        logger.debug(f"Page loaded - URL: {current_url}, Title: {title}")
+    except Exception as e:
+        logger.debug(f"Could not get page info: {e}")
+
+    logger.debug("Starting bypass process...")
+    if await _bypass(page, cancel_flag=cancel_flag):
+        await _extract_cookies_from_cdp(driver, page, url)
+        return await page.get_page_source()
+
+    logger.warning("Bypass completed but page still shows protection")
+    try:
+        body = await page.evaluate("document.body ? document.body.innerText : ''")
+        if body:
+            logger.debug(f"Page content: {body[:500]}..." if len(body) > 500 else body)
+    except Exception:
+        pass
+
+    return ""
+
+
+def get(url: str, retry: Optional[int] = None, cancel_flag: Optional[Event] = None) -> str:
+    """Fetch a URL with protection bypass. Creates fresh Chrome instance for each bypass."""
+    retry = retry if retry is not None else app_config.MAX_RETRY
+
+    with LOCKED:
+        # Try cookies first - another request may have completed bypass while waiting
+        cached_result = _try_with_cached_cookies(url, urlparse(url).hostname or "")
+        if cached_result:
+            return cached_result
+
+        async def _run_bypass() -> str:
+            driver = None
+            try:
+                driver = await _create_cdp_browser(url)
+
+                for attempt in range(retry):
+                    _check_cancellation(cancel_flag, "Bypass cancelled before attempt")
+
+                    try:
+                        result = await _get(url, driver, cancel_flag)
+                        if result:
+                            return result
+                    except BypassCancelledException:
+                        raise
+                    except Exception as e:
+                        error_details = f"{type(e).__name__}: {e}"
+                        logger.warning(f"Bypass failed (attempt {attempt + 1}/{retry}): {error_details}")
+                        logger.debug(f"Stack trace: {traceback.format_exc()}")
+
+                        # On CDP errors, quit and create a fresh browser
+                        if type(e).__name__ in DRIVER_RESET_ERRORS:
+                            logger.info("Restarting Chrome due to browser error...")
+                            await _close_cdp_driver(driver)
+                            driver = await _create_cdp_browser(url)
+
+                logger.error(f"Bypass failed after {retry} attempts")
+                return ""
+            finally:
+                if driver:
+                    await _close_cdp_driver(driver)
+
+        return _CDP_WORKER.run(_run_bypass())
+
+def _get_proxy_string(url: str) -> Optional[str]:
+    """Return a single proxy string for CDP, honoring NO_PROXY."""
+    proxies = get_proxies(url)
+    if not proxies:
+        return None
+    proxy_url = proxies.get("https") or proxies.get("http")
+    return proxy_url or None
+
+
+async def _create_cdp_browser(url: str) -> Any:
+    """Create a fresh CDP browser instance."""
+    browser_args = _get_browser_args()
+    screen_width, screen_height = get_screen_size()
+    display_width = screen_width + 100
+    display_height = screen_height + 150
+    proxy = _get_proxy_string(url)
+
+    logger.debug(f"Creating Pure CDP browser with args: {browser_args}")
+    logger.debug(f"Browser screen size: {screen_width}x{screen_height}")
+
+    driver = await cdp_driver.start_async(
+        headless=False,
+        headed=False,
+        xvfb=True,
+        xvfb_metrics=f"{display_width},{display_height}",
+        sandbox=False,
+        lang="en",
+        incognito=True,
+        ad_block=True,
+        proxy=proxy,
+        browser_args=browser_args,
+    )
+
+    try:
+        await driver.page.set_window_rect(0, 0, screen_width, screen_height)
+    except Exception as e:
+        logger.debug(f"Failed to set window size: {e}")
+
+    # Start FFmpeg recording if debug mode (record each bypass session)
+    if app_config.get("DEBUG", False) and not DISPLAY.get("ffmpeg"):
+        _start_ffmpeg_recording(display=os.environ.get("DISPLAY", ":0"))
+
+    await asyncio.sleep(app_config.DEFAULT_SLEEP)
+    logger.info("Chrome browser ready (Pure CDP)")
+    logger.log_resource_usage()
+    return driver
+
+
+async def _close_cdp_driver(driver) -> None:
+    """Close CDP connections and stop the browser."""
+    if not driver:
+        return
+
+    logger.debug("Quitting Chrome browser (CDP)...")
+
+    _stop_ffmpeg_recording()
+
+    try:
+        connections = []
+        if hasattr(driver, "connection") and driver.connection:
+            connections.append(driver.connection)
+        if hasattr(driver, "targets") and driver.targets:
+            connections.extend(driver.targets)
+        for conn in connections:
+            try:
+                await conn.aclose()
+            except Exception as e:
+                logger.debug(f"Failed to close websocket connection: {e}")
+    except Exception as e:
+        logger.debug(f"Error during connection cleanup: {e}")
+
+    try:
+        driver.stop()
+        logger.debug("Stopped CDP browser")
+    except Exception as e:
+        logger.debug(f"CDP stop: {e}")
+
+    if env.DOCKERMODE:
+        await asyncio.sleep(0.3)
+        try:
+            pid = getattr(driver, "_process_pid", None)
+
+            def _pid_alive(check_pid: int) -> bool:
+                try:
+                    os.kill(check_pid, 0)
+                except ProcessLookupError:
+                    return False
+                except PermissionError:
+                    return True
+                return True
+
+            if pid and _pid_alive(pid):
+                try:
+                    os.kill(pid, signal.SIGTERM)
+                    await asyncio.sleep(0.1)
+                    if _pid_alive(pid):
+                        os.kill(pid, signal.SIGKILL)
+                    logger.debug(f"Killed Chrome pid {pid}")
+                except Exception as e:
+                    logger.debug(f"Failed to kill Chrome pid {pid}: {e}")
+        except Exception as e:
+            logger.debug(f"Process cleanup failed: {e}")
+
+    logger.log_resource_usage()
+
+
+def _start_ffmpeg_recording(display: str) -> None:
+    """Start FFmpeg screen recording for debug mode."""
+    global DISPLAY
+    RECORDING_DIR.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now().strftime("%y%m%d-%H%M%S")
+    output_file = RECORDING_DIR / f"screen_recording_{timestamp}.mp4"
+
+    screen_width, screen_height = get_screen_size()
+    display_width = screen_width + 100
+    display_height = screen_height + 150
+
+    ffmpeg_cmd = [
+        "ffmpeg", "-y", "-f", "x11grab",
+        "-video_size", f"{display_width}x{display_height}",
+        "-i", display,
+        "-c:v", "libx264", "-preset", "ultrafast",
+        "-maxrate", "700k", "-bufsize", "1400k", "-crf", "36",
+        "-pix_fmt", "yuv420p", "-tune", "animation",
+        "-x264-params", "bframes=0:deblock=-1,-1",
+        "-r", "15", "-an",
+        output_file.as_posix(),
+        "-nostats", "-loglevel", "0"
+    ]
+    logger.debug("Starting FFmpeg recording to %s", output_file)
+    logger.debug_trace(f"FFmpeg command: {' '.join(ffmpeg_cmd)}")
+    DISPLAY["ffmpeg"] = subprocess.Popen(ffmpeg_cmd)
+    DISPLAY["ffmpeg_output"] = output_file
+
+
+def _stop_ffmpeg_recording() -> None:
+    """Stop FFmpeg screen recording if running."""
+    import signal
+    global DISPLAY
+    proc = DISPLAY.get("ffmpeg")
+    output_file = DISPLAY.get("ffmpeg_output")
+    if not proc:
+        return
+    if proc.poll() is not None:
+        logger.debug("FFmpeg already stopped")
+        DISPLAY["ffmpeg"] = None
+        DISPLAY["ffmpeg_output"] = None
+        return
+    try:
+        proc.send_signal(signal.SIGINT)
+        proc.wait(timeout=5)
+        logger.debug("Stopped ffmpeg recording")
+    except Exception as e:
+        logger.debug(f"ffmpeg stop: {e}")
+        try:
+            proc.terminate()
+            proc.wait(timeout=2)
+        except Exception:
+            pass
+        try:
+            proc.kill()
+        except Exception:
+            pass
+    DISPLAY["ffmpeg"] = None
+    DISPLAY["ffmpeg_output"] = None
+
+
+def _try_with_cached_cookies(url: str, hostname: str) -> Optional[str]:
+    """Attempt request with cached cookies before using Chrome."""
+    cookies = get_cf_cookies_for_domain(hostname)
+    if not cookies:
+        return None
+
+    try:
+        headers = {}
+        stored_ua = get_cf_user_agent_for_domain(hostname)
+        if stored_ua:
+            headers['User-Agent'] = stored_ua
+
+        logger.debug(f"Trying request with cached cookies: {url}")
+        response = requests.get(url, cookies=cookies, headers=headers, proxies=get_proxies(url), timeout=(5, 10), verify=get_ssl_verify(url))
+        if response.status_code == 200:
+            logger.debug("Cached cookies worked, skipped Chrome bypass")
+            return response.text
+    except Exception:
+        pass
+
+    return None
+
+
+def get_bypassed_page(
+    url: str,
+    selector: Optional[network.AAMirrorSelector] = None,
+    cancel_flag: Optional[Event] = None
+) -> Optional[str]:
+    """Fetch HTML content from a URL using the internal Cloudflare Bypasser."""
+    sel = selector or network.AAMirrorSelector()
+    attempt_url = sel.rewrite(url)
+    hostname = urlparse(attempt_url).hostname or ""
+
+    cached_result = _try_with_cached_cookies(attempt_url, hostname)
+    if cached_result:
+        return cached_result
+
+    try:
+        response_html = get(attempt_url, cancel_flag=cancel_flag)
+    except BypassCancelledException:
+        raise
+    except Exception:
+        _check_cancellation(cancel_flag, "Bypass cancelled")
+        new_base, action = sel.next_mirror_or_rotate_dns()
+        if action in ("mirror", "dns") and new_base:
+            attempt_url = sel.rewrite(url)
+            response_html = get(attempt_url, cancel_flag=cancel_flag)
+        else:
+            raise
+
+    if not response_html.strip():
+        raise requests.exceptions.RequestException("Failed to bypass Cloudflare")
+
+    return response_html

shelfmark/config/booklore_settings.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from typing import Any
+
+from shelfmark.core.config import config
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.outputs.booklore import (
+    BookloreConfig,
+    BookloreError,
+    booklore_list_libraries,
+    booklore_login,
+)
+
+logger = setup_logger(__name__)
+
+_BOOKLORE_OPTIONS_CACHE: dict[str, Any] = {
+    "key": None,
+    "library_options": [],
+    "path_options": [],
+}
+
+
+def _get_booklore_cache_key(base_url: str, username: str, password: str) -> str:
+    return f"{base_url}|{username}|{hash(password)}"
+
+
+def _get_booklore_select_options(
+    base_url: str,
+    username: str,
+    password: str,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    # library_id/path_id are not used for login/library listing
+    booklore_config = BookloreConfig(
+        base_url=base_url.rstrip("/"),
+        username=username,
+        password=password,
+        library_id=1,
+        path_id=1,
+        verify_tls=True,
+        refresh_after_upload=True,
+    )
+
+    token = booklore_login(booklore_config)
+    libraries = booklore_list_libraries(booklore_config, token) or []
+    logger.debug("Booklore libraries response: %s", libraries)
+
+    library_options: list[dict[str, Any]] = []
+    path_options: list[dict[str, Any]] = []
+
+    for library in libraries:
+        if not isinstance(library, dict):
+            continue
+
+        library_id = library.get("id")
+        if library_id is None:
+            continue
+
+        library_name = str(library.get("name") or f"Library {library_id}")
+        library_id_str = str(library_id)
+
+        library_options.append({"value": library_id_str, "label": library_name})
+
+        paths = library.get("paths") or []
+        if not isinstance(paths, list):
+            continue
+
+        for path in paths:
+            if not isinstance(path, dict):
+                continue
+
+            path_id = path.get("id")
+            if path_id is None:
+                continue
+
+            path_label = str(path.get("path") or f"Path {path_id}")
+            path_options.append(
+                {
+                    "value": str(path_id),
+                    "label": f"{library_name}: {path_label}",
+                    "childOf": library_id_str,
+                }
+            )
+
+    logger.debug(
+        "Booklore options built: libraries=%d paths=%d",
+        len(library_options),
+        len(path_options),
+    )
+
+    cache_key = _get_booklore_cache_key(base_url, username, password)
+    _BOOKLORE_OPTIONS_CACHE.update(
+        {
+            "key": cache_key,
+            "library_options": library_options,
+            "path_options": path_options,
+        }
+    )
+
+    return library_options, path_options
+
+
+def _get_booklore_cached_options(
+    base_url: str,
+    username: str,
+    password: str,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    cache_key = _get_booklore_cache_key(base_url, username, password)
+    if _BOOKLORE_OPTIONS_CACHE.get("key") == cache_key:
+        return (
+            _BOOKLORE_OPTIONS_CACHE.get("library_options", []),
+            _BOOKLORE_OPTIONS_CACHE.get("path_options", []),
+        )
+
+    return _get_booklore_select_options(base_url, username, password)
+
+
+def get_booklore_library_options() -> list[dict[str, Any]]:
+    """Build Booklore library options dynamically from config."""
+    if config.get("BOOKS_OUTPUT_MODE", "folder") != "booklore":
+        return []
+
+    base_url = str(config.get("BOOKLORE_HOST", "") or "").strip().rstrip("/")
+    username = str(config.get("BOOKLORE_USERNAME", "") or "").strip()
+    password = config.get("BOOKLORE_PASSWORD", "") or ""
+
+    if not base_url or not username or not password:
+        return []
+
+    cache_key = _get_booklore_cache_key(base_url, username, password)
+
+    try:
+        library_options, _ = _get_booklore_cached_options(base_url, username, password)
+        return library_options
+    except Exception as exc:
+        logger.error(f"Failed to fetch Booklore libraries: {exc}")
+        if _BOOKLORE_OPTIONS_CACHE.get("key") == cache_key:
+            return _BOOKLORE_OPTIONS_CACHE.get("library_options", [])
+        return []
+
+
+def get_booklore_path_options() -> list[dict[str, Any]]:
+    """Build Booklore path options dynamically from config."""
+    if config.get("BOOKS_OUTPUT_MODE", "folder") != "booklore":
+        return []
+
+    base_url = str(config.get("BOOKLORE_HOST", "") or "").strip().rstrip("/")
+    username = str(config.get("BOOKLORE_USERNAME", "") or "").strip()
+    password = config.get("BOOKLORE_PASSWORD", "") or ""
+
+    if not base_url or not username or not password:
+        return []
+
+    cache_key = _get_booklore_cache_key(base_url, username, password)
+
+    try:
+        _, path_options = _get_booklore_cached_options(base_url, username, password)
+        return path_options
+    except Exception as exc:
+        logger.error(f"Failed to fetch Booklore paths: {exc}")
+        if _BOOKLORE_OPTIONS_CACHE.get("key") == cache_key:
+            return _BOOKLORE_OPTIONS_CACHE.get("path_options", [])
+        return []
+
+
+def test_booklore_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test the Booklore connection using current form values."""
+    current_values = current_values or {}
+
+    def _get_value(key: str, default: Any = None) -> Any:
+        value = current_values.get(key)
+        if value not in (None, ""):
+            return value
+        if default is None:
+            return config.get(key)
+        return config.get(key, default)
+
+    base_url = str(_get_value("BOOKLORE_HOST", "") or "").strip().rstrip("/")
+    username = str(_get_value("BOOKLORE_USERNAME", "") or "").strip()
+    password = _get_value("BOOKLORE_PASSWORD", "") or ""
+
+    if not base_url:
+        return {"success": False, "message": "Booklore URL is required"}
+    if not username:
+        return {"success": False, "message": "Booklore username is required"}
+    if not password:
+        return {"success": False, "message": "Booklore password is required"}
+
+    try:
+        library_options, _ = _get_booklore_select_options(base_url, username, password)
+
+        message = "Connected to Booklore"
+        if library_options:
+            message = f"Connected to Booklore ({len(library_options)} libraries)"
+
+        return {"success": True, "message": message}
+    except BookloreError as exc:
+        return {"success": False, "message": str(exc)}

shelfmark/config/email_settings.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from shelfmark.core.config import config
+from shelfmark.download.outputs.email import EmailOutputError, build_email_smtp_config, test_smtp_connection
+
+
+def test_email_connection(current_values: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Test SMTP connectivity using current form values (including unsaved changes)."""
+
+    current_values = current_values or {}
+
+    def _get_value(key: str, default: Any = None) -> Any:
+        value = current_values.get(key)
+        if value not in (None, ""):
+            return value
+        if default is None:
+            return config.get(key)
+        return config.get(key, default)
+
+    settings = {
+        "EMAIL_SMTP_HOST": _get_value("EMAIL_SMTP_HOST", ""),
+        "EMAIL_SMTP_PORT": _get_value("EMAIL_SMTP_PORT", 587),
+        "EMAIL_SMTP_SECURITY": _get_value("EMAIL_SMTP_SECURITY", "starttls"),
+        "EMAIL_SMTP_USERNAME": _get_value("EMAIL_SMTP_USERNAME", ""),
+        "EMAIL_SMTP_PASSWORD": _get_value("EMAIL_SMTP_PASSWORD", ""),
+        "EMAIL_FROM": _get_value("EMAIL_FROM", ""),
+        "EMAIL_SUBJECT_TEMPLATE": _get_value("EMAIL_SUBJECT_TEMPLATE", "{Title}"),
+        "EMAIL_SMTP_TIMEOUT_SECONDS": _get_value("EMAIL_SMTP_TIMEOUT_SECONDS", 60),
+        "EMAIL_ALLOW_UNVERIFIED_TLS": _get_value("EMAIL_ALLOW_UNVERIFIED_TLS", False),
+    }
+
+    try:
+        smtp_config = build_email_smtp_config(settings)
+        test_smtp_connection(smtp_config)
+        return {"success": True, "message": "Connected to SMTP server"}
+    except EmailOutputError as exc:
+        return {"success": False, "message": str(exc)}
+    except Exception as exc:
+        return {"success": False, "message": f"SMTP test failed: {exc}"}
+

shelfmark/config/env.py

@@ -0,0 +1,164 @@
+"""Bootstrap environment variables. No local dependencies - import first."""
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+
+def string_to_bool(s: str) -> bool:
+    """Convert string to boolean."""
+    return s.lower() in ["true", "yes", "1", "y"]
+
+
+def _read_debug_from_config() -> bool:
+    """Read DEBUG from env var or config file (import-time safe)."""
+    env_debug = os.environ.get("DEBUG")
+    if env_debug is not None:
+        return string_to_bool(env_debug)
+
+    # Try to read from config file
+    config_dir = Path(os.getenv("CONFIG_DIR", "/config"))
+    config_file = config_dir / "plugins" / "advanced.json"
+
+    if config_file.exists():
+        try:
+            with open(config_file, "r") as f:
+                config = json.load(f)
+                if "DEBUG" in config:
+                    return bool(config["DEBUG"])
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return False
+
+
+def _is_sqlite_file(path: Path) -> bool:
+    """Check if a file is a valid SQLite database by reading magic bytes."""
+    try:
+        with open(path, "rb") as f:
+            header = f.read(16)
+            return header[:16] == b"SQLite format 3\x00"
+    except (OSError, PermissionError):
+        return False
+
+
+def _resolve_cwa_db_path() -> Path | None:
+    """Resolve CWA database path from env var or default location."""
+    env_path = os.getenv("CWA_DB_PATH")
+    if env_path:
+        path = Path(env_path)
+        if path.exists() and path.is_file() and _is_sqlite_file(path):
+            return path
+
+    # Check default mount path
+    default_path = Path("/auth/app.db")
+    if default_path.exists() and default_path.is_file() and _is_sqlite_file(default_path):
+        return default_path
+
+    return None
+
+
+def _is_config_dir_writable() -> bool:
+    """Check if the config directory exists and is writable."""
+    try:
+        if not CONFIG_DIR.exists() or not CONFIG_DIR.is_dir():
+            return False
+        test_file = CONFIG_DIR / ".write_test"
+        test_file.touch()
+        test_file.unlink()
+        return True
+    except (OSError, PermissionError):
+        return False
+
+
+def is_covers_cache_enabled() -> bool:
+    """Check if cover caching is enabled (requires setting + writable config dir)."""
+    from shelfmark.core.config import config
+    setting_enabled = config.get("COVERS_CACHE_ENABLED", True)
+    return setting_enabled and _is_config_dir_writable()
+
+
+# =============================================================================
+# Bootstrap paths - needed before settings registry is available
+# =============================================================================
+
+CONFIG_DIR = Path(os.getenv("CONFIG_DIR", "/config"))
+LOG_ROOT = Path(os.getenv("LOG_ROOT", "/var/log/"))
+LOG_DIR = LOG_ROOT / "shelfmark"
+LOG_FILE = LOG_DIR / "shelfmark.log"
+TMP_DIR = Path(os.getenv("TMP_DIR", "/tmp/shelfmark"))
+INGEST_DIR = Path(os.getenv("INGEST_DIR", "/books"))
+
+
+# =============================================================================
+# Logger configuration - needed before settings registry is available
+# =============================================================================
+
+DEBUG = _read_debug_from_config()
+LOG_LEVEL = "DEBUG" if DEBUG else "INFO"
+ENABLE_LOGGING = string_to_bool(os.getenv("ENABLE_LOGGING", "true"))
+
+
+# =============================================================================
+# Flask configuration - needed before app starts
+# =============================================================================
+
+FLASK_HOST = os.getenv("FLASK_HOST", "0.0.0.0")
+FLASK_PORT = int(os.getenv("FLASK_PORT", "8084"))
+
+
+# =============================================================================
+# Authentication
+# =============================================================================
+
+SESSION_COOKIE_SECURE_ENV = os.getenv("SESSION_COOKIE_SECURE", "false")
+SESSION_COOKIE_NAME = "shelfmark_session"
+CWA_DB_PATH = _resolve_cwa_db_path()
+HIDE_LOCAL_AUTH = string_to_bool(os.getenv("HIDE_LOCAL_AUTH", "false"))
+OIDC_AUTO_REDIRECT = string_to_bool(os.getenv("OIDC_AUTO_REDIRECT", "false"))
+
+
+# =============================================================================
+# Version information from Docker build
+# =============================================================================
+
+BUILD_VERSION = os.getenv("BUILD_VERSION", "N/A")
+RELEASE_VERSION = os.getenv("RELEASE_VERSION", "N/A")
+
+
+# =============================================================================
+# Capability detection - runtime checks, not user-configurable
+# =============================================================================
+
+DOCKERMODE = string_to_bool(os.getenv("DOCKERMODE", "false"))
+TOR_VARIANT_AVAILABLE = shutil.which("tor") is not None
+USING_TOR = string_to_bool(os.getenv("USING_TOR", "false"))
+
+
+# =============================================================================
+# Onboarding
+# =============================================================================
+
+# Set to false to skip the onboarding wizard entirely (useful for ephemeral storage)
+ONBOARDING = string_to_bool(os.getenv("ONBOARDING", "true"))
+
+
+# =============================================================================
+# Debug/development settings
+# =============================================================================
+
+# Debug: skip specific download sources for testing fallback chains
+# Comma-separated values: aa-fast, aa-slow-nowait, aa-slow-wait, libgen, zlib, welib
+_DEBUG_SKIP_SOURCES_RAW = os.getenv("DEBUG_SKIP_SOURCES", "").strip().lower()
+DEBUG_SKIP_SOURCES = set(s.strip() for s in _DEBUG_SKIP_SOURCES_RAW.split(",") if s.strip())
+
+
+# =============================================================================
+# Legacy migration support - will be removed in future version
+# =============================================================================
+
+# Legacy welib settings - replaced by SOURCE_PRIORITY OrderableListField
+# Kept for migration: if set, used to build initial SOURCE_PRIORITY config
+_LEGACY_PRIORITIZE_WELIB = string_to_bool(os.getenv("PRIORITIZE_WELIB", "false"))
+_LEGACY_ALLOW_USE_WELIB = string_to_bool(os.getenv("ALLOW_USE_WELIB", "true"))

shelfmark/config/migrations.py

@@ -0,0 +1,135 @@
+"""Configuration migration helpers."""
+
+import json
+from typing import Any, Callable
+
+
+_DEPRECATED_SETTINGS_RESTRICTION_KEYS = (
+    "PROXY_AUTH_RESTRICT_SETTINGS_TO_ADMIN",
+    "CWA_RESTRICT_SETTINGS_TO_ADMIN",
+    "RESTRICT_SETTINGS_TO_ADMIN",
+)
+
+
+def _as_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def _pick_legacy_settings_restriction(config: dict[str, Any]) -> bool | None:
+    """Pick the best legacy admin-restriction value to migrate."""
+    auth_method = str(config.get("AUTH_METHOD", "")).strip().lower()
+
+    if (
+        auth_method == "proxy"
+        and "PROXY_AUTH_RESTRICT_SETTINGS_TO_ADMIN" in config
+    ):
+        return _as_bool(config.get("PROXY_AUTH_RESTRICT_SETTINGS_TO_ADMIN"))
+
+    if auth_method == "cwa" and "CWA_RESTRICT_SETTINGS_TO_ADMIN" in config:
+        return _as_bool(config.get("CWA_RESTRICT_SETTINGS_TO_ADMIN"))
+
+    if "RESTRICT_SETTINGS_TO_ADMIN" in config:
+        return _as_bool(config.get("RESTRICT_SETTINGS_TO_ADMIN"))
+
+    if "PROXY_AUTH_RESTRICT_SETTINGS_TO_ADMIN" in config:
+        return _as_bool(config.get("PROXY_AUTH_RESTRICT_SETTINGS_TO_ADMIN"))
+
+    if "CWA_RESTRICT_SETTINGS_TO_ADMIN" in config:
+        return _as_bool(config.get("CWA_RESTRICT_SETTINGS_TO_ADMIN"))
+
+    return None
+
+
+def migrate_security_settings(
+    *,
+    load_security_config: Callable[[], dict[str, Any]],
+    load_users_config: Callable[[], dict[str, Any]],
+    save_users_config: Callable[[dict[str, Any]], None],
+    ensure_config_dir: Callable[[], None],
+    get_config_path: Callable[[], Any],
+    sync_builtin_admin_user: Callable[[str, str], None],
+    logger: Any,
+) -> None:
+    """Migrate legacy security keys and sync builtin admin credentials."""
+    try:
+        config = load_security_config()
+        users_config = load_users_config()
+        migrated_security = False
+        migrated_users = False
+
+        if "USE_CWA_AUTH" in config:
+            old_value = config.pop("USE_CWA_AUTH")
+            if "AUTH_METHOD" not in config:
+                if old_value:
+                    config["AUTH_METHOD"] = "cwa"
+                    logger.info("Migrated USE_CWA_AUTH=True to AUTH_METHOD='cwa'")
+                else:
+                    if config.get("BUILTIN_USERNAME") and config.get("BUILTIN_PASSWORD_HASH"):
+                        config["AUTH_METHOD"] = "builtin"
+                        logger.info("Migrated USE_CWA_AUTH=False to AUTH_METHOD='builtin'")
+                    else:
+                        config["AUTH_METHOD"] = "none"
+                        logger.info("Migrated USE_CWA_AUTH=False to AUTH_METHOD='none'")
+                migrated_security = True
+            else:
+                logger.info("Removed deprecated USE_CWA_AUTH setting (AUTH_METHOD already exists)")
+                migrated_security = True
+
+        # Backfill AUTH_METHOD for configs that have builtin credentials but
+        # were never migrated from USE_CWA_AUTH (e.g. dev builds that predated
+        # the AUTH_METHOD field).
+        if "AUTH_METHOD" not in config:
+            if config.get("BUILTIN_USERNAME") and config.get("BUILTIN_PASSWORD_HASH"):
+                config["AUTH_METHOD"] = "builtin"
+                migrated_security = True
+                logger.info(
+                    "Backfilled AUTH_METHOD='builtin' from legacy "
+                    "BUILTIN_USERNAME/BUILTIN_PASSWORD_HASH credentials"
+                )
+
+        if "RESTRICT_SETTINGS_TO_ADMIN" not in users_config:
+            legacy_restrict = _pick_legacy_settings_restriction(config)
+            if legacy_restrict is not None:
+                save_users_config({"RESTRICT_SETTINGS_TO_ADMIN": legacy_restrict})
+                migrated_users = True
+                logger.info(
+                    "Migrated legacy settings-admin restriction to users.RESTRICT_SETTINGS_TO_ADMIN="
+                    f"{legacy_restrict}"
+                )
+
+        for deprecated_key in _DEPRECATED_SETTINGS_RESTRICTION_KEYS:
+            if deprecated_key in config:
+                config.pop(deprecated_key, None)
+                migrated_security = True
+                logger.info(f"Removed deprecated security setting: {deprecated_key}")
+
+        try:
+            sync_builtin_admin_user(
+                config.get("BUILTIN_USERNAME", ""),
+                config.get("BUILTIN_PASSWORD_HASH", ""),
+            )
+        except Exception as exc:
+            logger.error(
+                "Failed to sync builtin credentials to users database during migration: "
+                f"{exc}"
+            )
+
+        if migrated_security:
+            ensure_config_dir()
+            config_path = get_config_path()
+            with open(config_path, "w") as f:
+                json.dump(config, f, indent=2)
+            logger.info("Security settings migration completed successfully")
+        elif migrated_users:
+            logger.info("Users settings migration completed successfully")
+        else:
+            logger.debug("No security settings migration needed")
+
+    except FileNotFoundError:
+        logger.debug("No existing security config file found - nothing to migrate")
+    except Exception as exc:
+        logger.error(f"Failed to migrate security settings: {exc}")

shelfmark/config/notifications_settings.py

@@ -0,0 +1,337 @@
+"""Notifications settings tab registration."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+from shelfmark.core.notifications import NotificationEvent, send_test_notification
+from shelfmark.core.settings_registry import (
+    ActionButton,
+    HeadingField,
+    TableField,
+    load_config_file,
+    register_on_save,
+    register_settings,
+)
+
+_URL_SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.-]*$")
+
+_ROUTE_EVENT_ALL = "all"
+_ADMIN_EVENT_OPTIONS = [
+    {"value": NotificationEvent.REQUEST_CREATED.value, "label": "New request submitted"},
+    {"value": NotificationEvent.REQUEST_FULFILLED.value, "label": "Request approved"},
+    {"value": NotificationEvent.REQUEST_REJECTED.value, "label": "Request rejected"},
+    {"value": NotificationEvent.DOWNLOAD_COMPLETE.value, "label": "Download complete"},
+    {"value": NotificationEvent.DOWNLOAD_FAILED.value, "label": "Download failed"},
+]
+_ROUTE_EVENT_OPTIONS = [
+    {"value": _ROUTE_EVENT_ALL, "label": "All"},
+    *_ADMIN_EVENT_OPTIONS,
+]
+_ROUTE_EVENT_ORDER = [option["value"] for option in _ROUTE_EVENT_OPTIONS]
+_ROUTE_EVENT_INDEX = {event: index for index, event in enumerate(_ROUTE_EVENT_ORDER)}
+_ALLOWED_ROUTE_EVENTS = set(_ROUTE_EVENT_ORDER)
+
+_DEFAULT_ROUTE_ROWS = [{"event": [_ROUTE_EVENT_ALL], "url": ""}]
+
+
+def _looks_like_apprise_url(url: str) -> bool:
+    split = urlsplit(url)
+    if not split.scheme:
+        return False
+    if not _URL_SCHEME_RE.match(split.scheme):
+        return False
+    return " " not in url
+
+
+def _coerce_route_rows(value: Any) -> list[dict[str, Any]]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [row for row in value if isinstance(row, dict)]
+    if isinstance(value, dict):
+        return [value]
+    return []
+
+
+def _coerce_route_event_values(value: Any) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, (tuple, set)):
+        return list(value)
+    return [value]
+
+
+def _normalize_route_events(value: Any) -> list[str]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+
+    for raw_event in _coerce_route_event_values(value):
+        event = str(raw_event or "").strip().lower()
+        if not event or event not in _ALLOWED_ROUTE_EVENTS:
+            continue
+        if event in seen:
+            continue
+        seen.add(event)
+        normalized.append(event)
+
+    if _ROUTE_EVENT_ALL in seen:
+        return [_ROUTE_EVENT_ALL]
+
+    return sorted(normalized, key=lambda event: _ROUTE_EVENT_INDEX[event])
+
+
+def _normalize_routes(value: Any) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    seen: set[tuple[tuple[str, ...], str]] = set()
+
+    for row in _coerce_route_rows(value):
+        events = _normalize_route_events(row.get("event"))
+        if not events:
+            continue
+
+        url = str(row.get("url") or "").strip()
+        key = (tuple(events), url)
+        if key in seen:
+            continue
+        seen.add(key)
+
+        normalized.append({"event": events, "url": url})
+
+    return normalized
+
+
+def _count_invalid_route_events(value: Any) -> int:
+    invalid = 0
+    for row in _coerce_route_rows(value):
+        raw_events = _coerce_route_event_values(row.get("event"))
+        if not raw_events:
+            invalid += 1
+            continue
+
+        for raw_event in raw_events:
+            event = str(raw_event or "").strip().lower()
+            if not event or event not in _ALLOWED_ROUTE_EVENTS:
+                invalid += 1
+    return invalid
+
+
+def _count_invalid_route_urls(routes: list[dict[str, Any]]) -> int:
+    return sum(1 for row in routes if row["url"] and not _looks_like_apprise_url(row["url"]))
+
+
+def _ensure_default_route_row(routes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return routes if routes else [dict(row) for row in _DEFAULT_ROUTE_ROWS]
+
+
+def _extract_unique_route_urls(routes: list[dict[str, Any]]) -> list[str]:
+    urls: list[str] = []
+    seen: set[str] = set()
+    for row in routes:
+        url = row.get("url", "")
+        if not url:
+            continue
+        if url in seen:
+            continue
+        seen.add(url)
+        urls.append(url)
+    return urls
+
+
+def build_notification_test_result(routes_input: Any, *, scope_label: str) -> dict[str, Any]:
+    invalid_event_count = _count_invalid_route_events(routes_input)
+    if invalid_event_count:
+        return {
+            "success": False,
+            "message": (
+                f"Found {invalid_event_count} invalid {scope_label} notification route event value(s). "
+                "Fix route events before running a test."
+            ),
+        }
+
+    normalized_routes = _normalize_routes(routes_input)
+    invalid_url_count = _count_invalid_route_urls(normalized_routes)
+    if invalid_url_count:
+        return {
+            "success": False,
+            "message": (
+                f"Found {invalid_url_count} invalid {scope_label} notification URL(s). "
+                "Fix route URLs before running a test."
+            ),
+        }
+
+    urls = _extract_unique_route_urls(normalized_routes)
+    if not urls:
+        return {
+            "success": False,
+            "message": f"Add at least one {scope_label} notification URL route first.",
+        }
+
+    return send_test_notification(urls)
+
+
+def normalize_notification_routes(value: Any) -> list[dict[str, Any]]:
+    """Normalize route table rows for notification preferences."""
+    return _normalize_routes(value)
+
+
+def is_valid_notification_url(url: str) -> bool:
+    """Shared URL validation for notifications preferences."""
+    return _looks_like_apprise_url(url)
+
+
+def _on_save_notifications(values: dict[str, Any]) -> dict[str, Any]:
+    existing = load_config_file("notifications")
+    effective: dict[str, Any] = dict(existing)
+    effective.update(values)
+
+    admin_routes_input = effective.get("ADMIN_NOTIFICATION_ROUTES", [])
+    invalid_admin_event_count = _count_invalid_route_events(admin_routes_input)
+    if invalid_admin_event_count:
+        return {
+            "error": True,
+            "message": (
+                f"Found {invalid_admin_event_count} invalid global notification route event value(s)."
+            ),
+            "values": values,
+        }
+
+    normalized_admin_routes = _normalize_routes(admin_routes_input)
+    invalid_admin_url_count = _count_invalid_route_urls(normalized_admin_routes)
+    if invalid_admin_url_count:
+        return {
+            "error": True,
+            "message": (
+                f"Found {invalid_admin_url_count} invalid global notification URL(s). "
+                "Use URL values with a valid scheme, e.g. discord://... or ntfys://..."
+            ),
+            "values": values,
+        }
+
+    user_routes_input = effective.get("USER_NOTIFICATION_ROUTES", [])
+    invalid_user_event_count = _count_invalid_route_events(user_routes_input)
+    if invalid_user_event_count:
+        return {
+            "error": True,
+            "message": (
+                f"Found {invalid_user_event_count} invalid personal notification route event value(s)."
+            ),
+            "values": values,
+        }
+
+    normalized_user_routes = _normalize_routes(user_routes_input)
+    invalid_user_url_count = _count_invalid_route_urls(normalized_user_routes)
+    if invalid_user_url_count:
+        return {
+            "error": True,
+            "message": (
+                f"Found {invalid_user_url_count} invalid personal notification URL(s). "
+                "Use URL values with a valid scheme, e.g. discord://... or ntfys://..."
+            ),
+            "values": values,
+        }
+
+    admin_routes_touched = "ADMIN_NOTIFICATION_ROUTES" in values
+    if admin_routes_touched:
+        values["ADMIN_NOTIFICATION_ROUTES"] = _ensure_default_route_row(normalized_admin_routes)
+
+    user_routes_touched = "USER_NOTIFICATION_ROUTES" in values
+    if user_routes_touched:
+        values["USER_NOTIFICATION_ROUTES"] = _ensure_default_route_row(normalized_user_routes)
+
+    return {"error": False, "values": values}
+
+
+def _test_admin_notification_action(current_values: dict[str, Any]) -> dict[str, Any]:
+    persisted = load_config_file("notifications")
+    effective: dict[str, Any] = dict(persisted)
+    if isinstance(current_values, dict):
+        effective.update(current_values)
+
+    routes_input = effective.get("ADMIN_NOTIFICATION_ROUTES", [])
+    return build_notification_test_result(routes_input, scope_label="global")
+
+
+register_on_save("notifications", _on_save_notifications)
+
+
+@register_settings("notifications", "Notifications", icon="bell", order=7)
+def notifications_settings():
+    """Global notifications settings."""
+    return [
+        HeadingField(
+            key="notifications_heading",
+            title="Global Notifications",
+            description=(
+                "Global notifications send selected events for all users to configured routes. "
+                "Users can manage personal notifications in User Preferences."
+            ),
+        ),
+        TableField(
+            key="ADMIN_NOTIFICATION_ROUTES",
+            label="",
+            description=(
+                "Create one route per URL. Start with All, then add event-specific routes "
+                "for targeted delivery. Need format examples? "
+                "[View Apprise URL formats](https://appriseit.com/services/)."
+            ),
+            columns=[
+                {
+                    "key": "event",
+                    "label": "Event",
+                    "type": "multiselect",
+                    "options": _ROUTE_EVENT_OPTIONS,
+                    "defaultValue": [_ROUTE_EVENT_ALL],
+                    "placeholder": "Select events...",
+                },
+                {
+                    "key": "url",
+                    "label": "Notification URL",
+                    "type": "text",
+                    "placeholder": "e.g. ntfys://ntfy.sh/shelfmark",
+                },
+            ],
+            default=[dict(row) for row in _DEFAULT_ROUTE_ROWS],
+            add_label="Add Route",
+            empty_message="No routes configured.",
+        ),
+        ActionButton(
+            key="test_admin_notification",
+            label="Test Notification",
+            description="Send a test notification to all configured global route URLs.",
+            style="primary",
+            callback=_test_admin_notification_action,
+        ),
+        TableField(
+            key="USER_NOTIFICATION_ROUTES",
+            label="",
+            description=(
+                "Create one route per URL. Start with All, then add event-specific routes "
+                "for targeted delivery. Need format examples? "
+                "[View Apprise URL formats](https://appriseit.com/services/)."
+            ),
+            columns=[
+                {
+                    "key": "event",
+                    "label": "Event",
+                    "type": "multiselect",
+                    "options": _ROUTE_EVENT_OPTIONS,
+                    "defaultValue": [_ROUTE_EVENT_ALL],
+                    "placeholder": "Select events...",
+                },
+                {
+                    "key": "url",
+                    "label": "Notification URL",
+                    "type": "text",
+                    "placeholder": "e.g. ntfys://ntfy.sh/username-topic",
+                },
+            ],
+            default=[dict(row) for row in _DEFAULT_ROUTE_ROWS],
+            add_label="Add Route",
+            empty_message="No routes configured.",
+            user_overridable=True,
+            hidden_in_ui=True,
+        ),
+    ]

shelfmark/config/security.py

@@ -0,0 +1,284 @@
+"""Authentication settings registration."""
+
+from typing import Any, Dict, Callable
+
+from shelfmark.config.migrations import migrate_security_settings
+from shelfmark.config.security_handlers import (
+    on_save_security,
+    test_oidc_connection,
+)
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.settings_registry import (
+    register_settings,
+    register_on_save,
+    load_config_file,
+    TextField,
+    SelectField,
+    PasswordField,
+    CheckboxField,
+    ActionButton,
+    TagListField,
+    CustomComponentField,
+)
+from shelfmark.core.user_db import sync_builtin_admin_user
+
+logger = setup_logger(__name__)
+
+
+def _auth_condition(auth_method: str) -> dict[str, str]:
+    return {"field": "AUTH_METHOD", "value": auth_method}
+
+
+def _auth_field(factory: Callable[..., Any], auth_method: str, **kwargs: Any) -> Any:
+    return factory(show_when=_auth_condition(auth_method), **kwargs)
+
+
+def _migrate_security_settings() -> None:
+    from shelfmark.core.settings_registry import (
+        _get_config_file_path,
+        _ensure_config_dir,
+        save_config_file,
+    )
+
+    migrate_security_settings(
+        load_security_config=lambda: load_config_file("security"),
+        load_users_config=lambda: load_config_file("users"),
+        save_users_config=lambda values: save_config_file("users", values),
+        ensure_config_dir=lambda: _ensure_config_dir("security"),
+        get_config_path=lambda: _get_config_file_path("security"),
+        sync_builtin_admin_user=sync_builtin_admin_user,
+        logger=logger,
+    )
+
+
+
+def _on_save_security(values: Dict[str, Any]) -> Dict[str, Any]:
+    return on_save_security(values)
+
+
+def _test_oidc_connection(current_values: Dict[str, Any] = None) -> Dict[str, Any]:
+    return test_oidc_connection(
+        load_security_config=lambda: load_config_file("security"),
+        current_values=current_values or {},
+        logger=logger,
+    )
+
+
+@register_settings("security", "Security", icon="shield", order=5)
+def security_settings():
+    """Security and authentication settings."""
+    from shelfmark.config.env import CWA_DB_PATH
+
+    cwa_db_available = CWA_DB_PATH is not None and CWA_DB_PATH.exists()
+
+    auth_method_options = [
+        {"label": "No Authentication", "value": "none"},
+        {"label": "Local", "value": "builtin"},
+        {"label": "Proxy Authentication", "value": "proxy"},
+        {"label": "OIDC (OpenID Connect)", "value": "oidc"},
+        {"label": "Calibre-Web Database", "value": "cwa"},
+    ]
+
+    fields = [
+        SelectField(
+            key="AUTH_METHOD",
+            label="Authentication Method",
+            description="Select the authentication method for accessing Shelfmark.",
+            options=auth_method_options,
+            default="none",
+        ),
+        CustomComponentField(
+            key="builtin_admin_requirement",
+            component="oidc_admin_hint",
+            label=(
+                "Local authentication is inactive until a local admin account with a "
+                "password is created."
+            ),
+            show_when=_auth_condition("builtin"),
+        ),
+        CustomComponentField(
+            key="oidc_admin_requirement",
+            component="oidc_admin_hint",
+            label="A local admin account is required before OIDC can be enabled.",
+            show_when=_auth_condition("oidc"),
+        ),
+        *([] if cwa_db_available else [
+            CustomComponentField(
+                key="cwa_db_missing",
+                component="oidc_admin_hint",
+                label=(
+                    "Calibre-Web database not detected. Mount your app.db to "
+                    "/auth/app.db to enable this method. Authentication will fall "
+                    "back to none until the database is available."
+                ),
+                show_when=_auth_condition("cwa"),
+            ),
+        ]),
+        ActionButton(
+            key="open_users_tab",
+            label="Go to Users",
+            description="Configure local users and admin access in the Users tab.",
+            style="primary",
+            show_when={"field": "AUTH_METHOD", "value": ["builtin", "oidc"]},
+        ),
+        _auth_field(
+            TextField,
+            "proxy",
+            key="PROXY_AUTH_USER_HEADER",
+            label="Proxy Auth User Header",
+            description="The HTTP header your proxy uses to pass the authenticated username.",
+            placeholder="e.g. X-Auth-User",
+            default="X-Auth-User",
+        ),
+        _auth_field(
+            TextField,
+            "proxy",
+            key="PROXY_AUTH_LOGOUT_URL",
+            label="Proxy Auth Logout URL",
+            description="The URL to redirect users to for logging out. Leave empty to disable logout functionality.",
+            placeholder="https://myauth.example.com/logout",
+            default="",
+        ),
+        _auth_field(
+            TextField,
+            "proxy",
+            key="PROXY_AUTH_ADMIN_GROUP_HEADER",
+            label="Proxy Auth Admin Group Header",
+            description="Optional: header your proxy uses to pass user groups/roles.",
+            placeholder="e.g. X-Auth-Groups",
+            default="X-Auth-Groups",
+        ),
+        _auth_field(
+            TextField,
+            "proxy",
+            key="PROXY_AUTH_ADMIN_GROUP_NAME",
+            label="Proxy Auth Admin Group",
+            description="Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection.",
+            placeholder="e.g. admins",
+            default="",
+        ),
+    ]
+
+    fields.append(
+        CustomComponentField(
+            key="oidc_callback_url",
+            component="settings_label",
+            label="Callback URL",
+            description="{origin}/api/auth/oidc/callback",
+            show_when=_auth_condition("oidc"),
+        )
+    )
+
+    oidc_specs = [
+        (
+            TextField,
+            {
+                "key": "OIDC_DISCOVERY_URL",
+                "label": "Discovery URL",
+                "description": "OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration.",
+                "placeholder": "https://auth.example.com/.well-known/openid-configuration",
+                "required": True,
+            },
+        ),
+        (
+            TextField,
+            {
+                "key": "OIDC_CLIENT_ID",
+                "label": "Client ID",
+                "description": "OAuth2 client ID from your identity provider.",
+                "placeholder": "shelfmark",
+                "required": True,
+            },
+        ),
+        (
+            PasswordField,
+            {
+                "key": "OIDC_CLIENT_SECRET",
+                "label": "Client Secret",
+                "description": "OAuth2 client secret from your identity provider.",
+                "required": True,
+            },
+        ),
+        (
+            TagListField,
+            {
+                "key": "OIDC_SCOPES",
+                "label": "Scopes",
+                "description": "OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization.",
+                "default": ["openid", "email", "profile"],
+            },
+        ),
+        (
+            TextField,
+            {
+                "key": "OIDC_GROUP_CLAIM",
+                "label": "Group Claim Name",
+                "description": "The name of the claim in the ID token that contains user groups.",
+                "placeholder": "groups",
+                "default": "groups",
+            },
+        ),
+        (
+            TextField,
+            {
+                "key": "OIDC_ADMIN_GROUP",
+                "label": "Admin Group Name",
+                "description": "Users in this group will be given admin access (if enabled below). Leave empty to use database roles only.",
+                "placeholder": "shelfmark-admins",
+                "default": "",
+            },
+        ),
+        (
+            CheckboxField,
+            {
+                "key": "OIDC_USE_ADMIN_GROUP",
+                "label": "Use Admin Group for Authorization",
+                "description": "When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles.",
+                "default": True,
+            },
+        ),
+        (
+            CheckboxField,
+            {
+                "key": "OIDC_AUTO_PROVISION",
+                "label": "Auto-Provision Users",
+                "description": "Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin.",
+                "default": True,
+            },
+        ),
+        (
+            TextField,
+            {
+                "key": "OIDC_BUTTON_LABEL",
+                "label": "Login Button Label",
+                "description": "Custom label for the OIDC sign-in button on the login page.",
+                "placeholder": "Sign in with OIDC",
+                "default": "",
+            },
+        ),
+    ]
+    fields.extend(_auth_field(factory, "oidc", **spec) for factory, spec in oidc_specs)
+    fields.append(
+        ActionButton(
+            key="test_oidc",
+            label="Test Connection",
+            description="Fetch the OIDC discovery document and validate configuration.",
+            style="primary",
+            callback=_test_oidc_connection,
+            show_when=_auth_condition("oidc"),
+        )
+    )
+    fields.append(
+        CustomComponentField(
+            key="oidc_env_info",
+            component="oidc_env_info",
+            label="Environment-Only Options",
+            description="These options can only be set via environment variables because changing them through the UI could lock you out of the application.",
+            wrap_in_field_wrapper=True,
+            show_when=_auth_condition("oidc"),
+        )
+    )
+    return fields
+
+
+register_on_save("security", _on_save_security)

shelfmark/config/security_handlers.py

@@ -0,0 +1,75 @@
+"""Operational handlers for security settings (save/actions)."""
+
+import os
+from typing import Any, Callable
+
+from shelfmark.core.utils import normalize_http_url
+from shelfmark.core.user_db import UserDB
+from shelfmark.download.network import get_ssl_verify
+
+
+_OIDC_LOCKOUT_MESSAGE = "A local admin account with a password is required before enabling OIDC. Use the 'Go to Users' button above to create one. This ensures you can still sign in if your identity provider is unavailable."
+
+
+def _has_local_password_admin() -> bool:
+    root = os.environ.get("CONFIG_DIR", "/config")
+    user_db = UserDB(os.path.join(root, "users.db"))
+    user_db.initialize()
+    return any(user.get("password_hash") and user.get("role") == "admin" for user in user_db.list_users())
+
+
+def on_save_security(
+    values: dict[str, Any],
+) -> dict[str, Any]:
+    """Validate security values before persistence."""
+    normalized_values = values.copy()
+
+    discovery_url = normalized_values.get("OIDC_DISCOVERY_URL")
+    if discovery_url is not None:
+        normalized_values["OIDC_DISCOVERY_URL"] = normalize_http_url(
+            str(discovery_url),
+            default_scheme="https",
+        )
+
+    proxy_logout_url = normalized_values.get("PROXY_AUTH_LOGOUT_URL")
+    if proxy_logout_url is not None:
+        normalized_values["PROXY_AUTH_LOGOUT_URL"] = normalize_http_url(
+            str(proxy_logout_url),
+            default_scheme="https",
+            strip_trailing_slash=False,
+        )
+
+    if normalized_values.get("AUTH_METHOD") == "oidc" and not _has_local_password_admin():
+        return {"error": True, "message": _OIDC_LOCKOUT_MESSAGE, "values": normalized_values}
+
+    return {"error": False, "values": normalized_values}
+
+
+def test_oidc_connection(
+    *,
+    load_security_config: Callable[[], dict[str, Any]],
+    current_values: dict[str, Any] | None = None,
+    logger: Any,
+) -> dict[str, Any]:
+    """Fetch and validate the configured OIDC discovery document."""
+    import requests
+
+    try:
+        # Prefer the current (unsaved) form value over the saved config
+        discovery_url = (current_values or {}).get("OIDC_DISCOVERY_URL") or load_security_config().get("OIDC_DISCOVERY_URL", "")
+        if not discovery_url:
+            return {"success": False, "message": "Discovery URL is not configured."}
+
+        response = requests.get(discovery_url, timeout=10, verify=get_ssl_verify(discovery_url))
+        response.raise_for_status()
+        document = response.json()
+
+        required_fields = ["issuer", "authorization_endpoint", "token_endpoint"]
+        missing_fields = [field for field in required_fields if field not in document]
+        if missing_fields:
+            return {"success": False, "message": f"Discovery document missing fields: {', '.join(missing_fields)}"}
+
+        return {"success": True, "message": f"Connected to {document['issuer']}"}
+    except Exception as exc:
+        logger.error(f"OIDC connection test failed: {exc}")
+        return {"success": False, "message": f"Connection failed: {str(exc)}"}

shelfmark/config/users_settings.py

@@ -0,0 +1,390 @@
+"""Users settings tab registration.
+
+This registers a 'users' tab in the settings sidebar.
+The actual user management is handled by a custom frontend component
+that talks to /api/admin/users endpoints.
+"""
+
+from typing import Any
+
+from shelfmark.core.settings_registry import (
+    CheckboxField,
+    CustomComponentField,
+    HeadingField,
+    MultiSelectField,
+    NumberField,
+    SelectField,
+    TableField,
+    register_on_save,
+    register_settings,
+)
+from shelfmark.core.request_policy import (
+    get_source_content_type_capabilities,
+    parse_policy_mode,
+    validate_policy_rules,
+)
+
+
+_REQUEST_DEFAULT_MODE_OPTIONS = [
+    {
+        "value": "download",
+        "label": "Download",
+        "description": "Everything can be downloaded directly.",
+    },
+    {
+        "value": "request_release",
+        "label": "Request Release",
+        "description": "Users must request a specific release.",
+    },
+    {
+        "value": "request_book",
+        "label": "Request Book",
+        "description": "Users request a book, admin picks the release.",
+    },
+    {
+        "value": "blocked",
+        "label": "Blocked",
+        "description": "No downloads or requests allowed.",
+    },
+]
+
+_REQUEST_MATRIX_MODE_OPTIONS = [
+    option for option in _REQUEST_DEFAULT_MODE_OPTIONS if option["value"] != "request_book"
+]
+
+_SELF_SETTINGS_SECTION_OPTIONS = [
+    {
+        "value": "delivery",
+        "label": "Delivery Preferences",
+        "description": "Show personal delivery output and destination settings.",
+    },
+    {
+        "value": "search",
+        "label": "Search Preferences",
+        "description": "Show personal search mode and provider settings.",
+    },
+    {
+        "value": "notifications",
+        "label": "Notifications",
+        "description": "Show personal notification route settings.",
+    },
+]
+_SELF_SETTINGS_SECTION_VALUES = {option["value"] for option in _SELF_SETTINGS_SECTION_OPTIONS}
+_SELF_SETTINGS_SECTION_DEFAULTS = [option["value"] for option in _SELF_SETTINGS_SECTION_OPTIONS]
+_SEARCH_MODE_VALUES = {"direct", "universal"}
+_SEARCH_PREFERENCE_PROVIDER_KEYS = {"METADATA_PROVIDER", "METADATA_PROVIDER_AUDIOBOOK"}
+_SEARCH_PREFERENCE_VALIDATABLE_KEYS = {
+    "SEARCH_MODE",
+    "DEFAULT_RELEASE_SOURCE",
+    *_SEARCH_PREFERENCE_PROVIDER_KEYS,
+}
+
+_USERS_HEADING_DESCRIPTION_BY_AUTH_MODE = {
+    "builtin": (
+        "Create and manage user accounts directly. Passwords are stored locally and users sign in "
+        "with their username and password."
+    ),
+    "oidc": (
+        "Users sign in through your identity provider. New accounts can be created automatically on "
+        "first login when auto-provisioning is enabled, or you can pre-create users here and they\u2019ll "
+        "be linked by email on first sign-in."
+    ),
+    "proxy": (
+        "Users are authenticated by your reverse proxy. Accounts are automatically created on first "
+        "sign-in. If a local user with a matching username already exists, it will be linked instead."
+    ),
+    "cwa": (
+        "User accounts are synced from your Calibre-Web database. Users are matched by email, and new "
+        "accounts are created here when new CWA users are found."
+    ),
+    "none": "Authentication is disabled. Anyone can access Shelfmark without signing in.",
+    "default": "Authentication is disabled. Anyone can access Shelfmark without signing in.",
+}
+
+
+def _get_request_source_options():
+    """Build request-policy source options from registered release sources."""
+    from shelfmark.release_sources import list_available_sources
+
+    options = []
+    for source in list_available_sources():
+        options.append(
+            {
+                "value": source["name"],
+                "label": source["display_name"],
+            }
+        )
+    return options
+
+
+def _get_request_policy_rule_columns():
+    source_capabilities = get_source_content_type_capabilities()
+    content_type_options = []
+
+    for source_name, supported_types in source_capabilities.items():
+        normalized_types = [t for t in ("ebook", "audiobook") if t in supported_types]
+        for content_type in normalized_types:
+            content_type_options.append(
+                {
+                    "value": content_type,
+                    "label": "Ebook" if content_type == "ebook" else "Audiobook",
+                    "childOf": source_name,
+                }
+            )
+
+    return [
+        {
+            "key": "source",
+            "label": "Source",
+            "type": "select",
+            "options": _get_request_source_options(),
+            "defaultValue": "",
+            "placeholder": "Select source...",
+        },
+        {
+            "key": "content_type",
+            "label": "Content Type",
+            "type": "select",
+            "options": content_type_options,
+            "defaultValue": "",
+            "placeholder": "Select content type...",
+            "filterByField": "source",
+        },
+        {
+            "key": "mode",
+            "label": "Mode",
+            "type": "select",
+            "options": _REQUEST_MATRIX_MODE_OPTIONS,
+            "defaultValue": "",
+            "placeholder": "Select mode...",
+        },
+    ]
+
+
+def validate_search_preference_value(key: str, value: Any) -> tuple[Any, str | None]:
+    """Validate and normalize a search preference value for user overrides."""
+    if key not in _SEARCH_PREFERENCE_VALIDATABLE_KEYS:
+        return value, None
+
+    if value is None:
+        return None, None
+
+    normalized_value = str(value).strip()
+
+    if key == "SEARCH_MODE":
+        normalized_mode = normalized_value.lower()
+        if normalized_mode not in _SEARCH_MODE_VALUES:
+            return value, "SEARCH_MODE must be 'direct' or 'universal'"
+        return normalized_mode, None
+
+    if key in _SEARCH_PREFERENCE_PROVIDER_KEYS:
+        if normalized_value == "":
+            return "", None
+        from shelfmark.metadata_providers import is_provider_registered
+
+        if not is_provider_registered(normalized_value):
+            return (
+                value,
+                f"{key} must be a valid metadata provider name or empty",
+            )
+        return normalized_value, None
+
+    if key == "DEFAULT_RELEASE_SOURCE":
+        if normalized_value == "":
+            return "", None
+        from shelfmark.release_sources import list_available_sources
+
+        valid_sources = {source["name"] for source in list_available_sources()}
+        if normalized_value not in valid_sources:
+            return (
+                value,
+                "DEFAULT_RELEASE_SOURCE must be a valid release source name or empty",
+            )
+        return normalized_value, None
+
+    return value, None
+
+
+def _on_save_users(values):
+    """Validate users/request-policy settings before persistence."""
+    if "VISIBLE_SELF_SETTINGS_SECTIONS" in values:
+        raw_sections = values["VISIBLE_SELF_SETTINGS_SECTIONS"]
+        if raw_sections is None:
+            candidate_sections: list[str] = []
+        elif isinstance(raw_sections, str):
+            candidate_sections = [s.strip() for s in raw_sections.split(",") if s.strip()]
+        elif isinstance(raw_sections, (list, tuple, set)):
+            candidate_sections = [str(section).strip() for section in raw_sections if str(section).strip()]
+        else:
+            return {
+                "error": True,
+                "message": "VISIBLE_SELF_SETTINGS_SECTIONS must be a list of section identifiers",
+                "values": values,
+            }
+
+        normalized_sections: list[str] = []
+        for section in candidate_sections:
+            if section not in _SELF_SETTINGS_SECTION_VALUES:
+                allowed = ", ".join(sorted(_SELF_SETTINGS_SECTION_VALUES))
+                return {
+                    "error": True,
+                    "message": (
+                        "VISIBLE_SELF_SETTINGS_SECTIONS contains an unsupported section "
+                        f"'{section}'. Supported values: {allowed}"
+                    ),
+                    "values": values,
+                }
+            if section not in normalized_sections:
+                normalized_sections.append(section)
+
+        values["VISIBLE_SELF_SETTINGS_SECTIONS"] = normalized_sections
+
+    if "REQUEST_POLICY_DEFAULT_EBOOK" in values:
+        if parse_policy_mode(values["REQUEST_POLICY_DEFAULT_EBOOK"]) is None:
+            return {
+                "error": True,
+                "message": "REQUEST_POLICY_DEFAULT_EBOOK must be a valid policy mode",
+                "values": values,
+            }
+
+    if "REQUEST_POLICY_DEFAULT_AUDIOBOOK" in values:
+        if parse_policy_mode(values["REQUEST_POLICY_DEFAULT_AUDIOBOOK"]) is None:
+            return {
+                "error": True,
+                "message": "REQUEST_POLICY_DEFAULT_AUDIOBOOK must be a valid policy mode",
+                "values": values,
+            }
+
+    if "REQUEST_POLICY_RULES" in values:
+        normalized_rules, errors = validate_policy_rules(values["REQUEST_POLICY_RULES"])
+        if errors:
+            return {
+                "error": True,
+                "message": "; ".join(errors),
+                "values": values,
+            }
+        values["REQUEST_POLICY_RULES"] = normalized_rules
+
+    for key in _SEARCH_PREFERENCE_VALIDATABLE_KEYS:
+        if key not in values:
+            continue
+        normalized_value, validation_error = validate_search_preference_value(key, values[key])
+        if validation_error:
+            return {
+                "error": True,
+                "message": validation_error,
+                "values": values,
+            }
+        values[key] = normalized_value
+
+    return {"error": False, "values": values}
+
+
+register_on_save("users", _on_save_users)
+
+
+@register_settings("users", "Users & Requests", icon="users", order=6)
+def users_settings():
+    """User management tab - rendered as a custom component on the frontend."""
+    return [
+        HeadingField(
+            key="users_heading",
+            title="Users",
+            description=_USERS_HEADING_DESCRIPTION_BY_AUTH_MODE["default"],
+            description_by_auth_mode=_USERS_HEADING_DESCRIPTION_BY_AUTH_MODE,
+        ),
+        CustomComponentField(
+            key="users_management",
+            component="users_management",
+        ),
+        MultiSelectField(
+            key="VISIBLE_SELF_SETTINGS_SECTIONS",
+            label="Visible Self-Settings Sections",
+            description=(
+                "Choose which personal settings sections are shown in My Account for non-admin users."
+            ),
+            options=_SELF_SETTINGS_SECTION_OPTIONS,
+            default=_SELF_SETTINGS_SECTION_DEFAULTS,
+            variant="dropdown",
+            env_supported=False,
+        ),
+        HeadingField(
+            key="requests_heading",
+            title="Requests",
+            description=(
+                "Choose what users can download directly and what needs approval first."
+            ),
+        ),
+        CheckboxField(
+            key="REQUESTS_ENABLED",
+            label="Enable Requests",
+            description=(
+                "Turn this off to let everyone download directly without needing approval."
+            ),
+            default=False,
+            user_overridable=True,
+        ),
+        CustomComponentField(
+            key="request_policy_editor",
+            component="request_policy_grid",
+            label="Request Rules",
+            description=(
+                "Fine-tune access per source. Source rules can only be the same or more restrictive than the default above."
+            ),
+            show_when={"field": "REQUESTS_ENABLED", "value": True},
+            wrap_in_field_wrapper=True,
+            value_fields=[
+                SelectField(
+                    key="REQUEST_POLICY_DEFAULT_EBOOK",
+                    label="Default Ebook Mode",
+                    description=(
+                        "Sets the baseline for all ebook sources."
+                    ),
+                    options=_REQUEST_DEFAULT_MODE_OPTIONS,
+                    default="download",
+                    user_overridable=True,
+                ),
+                SelectField(
+                    key="REQUEST_POLICY_DEFAULT_AUDIOBOOK",
+                    label="Default Audiobook Mode",
+                    description=(
+                        "Sets the baseline for all audiobook sources."
+                    ),
+                    options=_REQUEST_DEFAULT_MODE_OPTIONS,
+                    default="download",
+                    user_overridable=True,
+                ),
+                TableField(
+                    key="REQUEST_POLICY_RULES",
+                    label="Request Rules",
+                    description=(
+                        "Fine-tune access per source. Source rules can only be the same or more restrictive than the default above."
+                    ),
+                    columns=_get_request_policy_rule_columns,
+                    default=[],
+                    add_label="Add Rule",
+                    empty_message="No request policy rules configured.",
+                    env_supported=False,
+                    user_overridable=True,
+                ),
+            ],
+        ),
+        NumberField(
+            key="MAX_PENDING_REQUESTS_PER_USER",
+            label="Max pending requests per user",
+            description="How many open requests a user can have at a time.",
+            default=20,
+            min_value=1,
+            max_value=1000,
+            user_overridable=True,
+            show_when={"field": "REQUESTS_ENABLED", "value": True},
+        ),
+        CheckboxField(
+            key="REQUESTS_ALLOW_NOTES",
+            label="Allow notes on requests",
+            description="Let users add a note when they submit a request.",
+            default=True,
+            user_overridable=True,
+            show_when={"field": "REQUESTS_ENABLED", "value": True},
+        ),
+    ]

shelfmark/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core module - shared models, queue, and utilities."""
+
+from shelfmark.core.models import QueueItem, SearchFilters, QueueStatus
+from shelfmark.core.queue import BookQueue, book_queue
+from shelfmark.core.logger import setup_logger

shelfmark/core/activity_routes.py

@@ -0,0 +1,700 @@
+"""Activity API routes (snapshot, dismiss, history)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, NamedTuple
+
+from flask import Flask, jsonify, request, session
+
+from shelfmark.core.activity_view_state_service import (
+    ADMIN_VIEWER_SCOPE,
+    NOAUTH_VIEWER_SCOPE,
+    ActivityViewStateService,
+    user_viewer_scope,
+)
+from shelfmark.core.download_history_service import ACTIVE_DOWNLOAD_STATUS, DownloadHistoryService, VALID_TERMINAL_STATUSES
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.models import ACTIVE_QUEUE_STATUSES, QueueStatus, TERMINAL_QUEUE_STATUSES
+from shelfmark.core.request_validation import RequestStatus
+from shelfmark.core.request_helpers import (
+    emit_ws_event,
+    extract_release_source_id,
+    normalize_positive_int,
+    populate_request_usernames,
+)
+from shelfmark.core.user_db import UserDB
+
+logger = setup_logger(__name__)
+
+
+def _require_authenticated(resolve_auth_mode: Callable[[], str]):
+    auth_mode = resolve_auth_mode()
+    if auth_mode == "none":
+        return None
+    if "user_id" not in session:
+        return jsonify({"error": "Unauthorized"}), 401
+    return None
+
+
+def _resolve_db_user_id(
+    require_in_auth_mode: bool = True,
+    *,
+    user_db: UserDB | None = None,
+):
+    raw_db_user_id = session.get("db_user_id")
+    if raw_db_user_id is None:
+        if not require_in_auth_mode:
+            return None, None
+        return None, (
+            jsonify(
+                {
+                    "error": "User identity unavailable for activity workflow",
+                    "code": "user_identity_unavailable",
+                }
+            ),
+            403,
+        )
+    try:
+        parsed_db_user_id = int(raw_db_user_id)
+    except (TypeError, ValueError):
+        if not require_in_auth_mode:
+            return None, None
+        return None, (
+            jsonify(
+                {
+                    "error": "User identity unavailable for activity workflow",
+                    "code": "user_identity_unavailable",
+                }
+            ),
+            403,
+        )
+
+    if parsed_db_user_id < 1:
+        if not require_in_auth_mode:
+            return None, None
+        return None, (
+            jsonify(
+                {
+                    "error": "User identity unavailable for activity workflow",
+                    "code": "user_identity_unavailable",
+                }
+            ),
+            403,
+        )
+
+    if user_db is not None:
+        try:
+            db_user = user_db.get_user(user_id=parsed_db_user_id)
+        except Exception as exc:
+            logger.warning("Failed to validate activity db identity %s: %s", parsed_db_user_id, exc)
+            db_user = None
+        if db_user is None:
+            if not require_in_auth_mode:
+                return None, None
+            return None, (
+                jsonify(
+                    {
+                        "error": "User identity unavailable for activity workflow",
+                        "code": "user_identity_unavailable",
+                    }
+                ),
+                403,
+            )
+
+    return parsed_db_user_id, None
+
+
+class _ActorContext(NamedTuple):
+    db_user_id: int | None
+    is_no_auth: bool
+    is_admin: bool
+    owner_scope: int | None
+    viewer_scope: str
+
+
+def _resolve_activity_actor(
+    *,
+    user_db: UserDB,
+    resolve_auth_mode: Callable[[], str],
+) -> tuple[_ActorContext | None, Any | None]:
+    """Resolve acting user identity for activity mutations.
+
+    Returns (actor, error_response). On success actor is non-None.
+    """
+    if resolve_auth_mode() == "none":
+        return _ActorContext(
+            db_user_id=None,
+            is_no_auth=True,
+            is_admin=True,
+            owner_scope=None,
+            viewer_scope=NOAUTH_VIEWER_SCOPE,
+        ), None
+
+    db_user_id, db_gate = _resolve_db_user_id(user_db=user_db)
+    if db_user_id is None:
+        return None, db_gate
+
+    is_admin = bool(session.get("is_admin"))
+    viewer_scope = ADMIN_VIEWER_SCOPE if is_admin else user_viewer_scope(db_user_id)
+    return _ActorContext(
+        db_user_id=db_user_id,
+        is_no_auth=False,
+        is_admin=is_admin,
+        owner_scope=None if is_admin else db_user_id,
+        viewer_scope=viewer_scope,
+    ), None
+
+
+def _activity_ws_room(actor: _ActorContext) -> str:
+    """Resolve the WebSocket room for activity events."""
+    if actor.is_no_auth or actor.is_admin:
+        return "admins"
+    if actor.db_user_id is not None:
+        return f"user_{actor.db_user_id}"
+    return "admins"
+
+
+def _check_item_ownership(actor: _ActorContext, row: dict[str, Any]) -> Any | None:
+    """Return a 403 response if the actor doesn't own the item, else None."""
+    if actor.is_admin:
+        return None
+    owner_user_id = normalize_positive_int(row.get("user_id"))
+    if owner_user_id != actor.db_user_id:
+        return jsonify({"error": "Forbidden"}), 403
+    return None
+
+
+def _check_terminal_download(row: dict[str, Any]) -> Any | None:
+    final_status = str(row.get("final_status") or "").strip().lower()
+    if final_status not in VALID_TERMINAL_STATUSES:
+        return jsonify({"error": "Only terminal downloads can be dismissed"}), 409
+    return None
+
+
+def _check_terminal_request(row: dict[str, Any]) -> Any | None:
+    if _request_terminal_status(row) is None:
+        return jsonify({"error": "Only terminal requests can be dismissed"}), 409
+    return None
+
+
+def _list_visible_requests(user_db: UserDB, *, is_admin: bool, db_user_id: int | None) -> list[dict[str, Any]]:
+    if is_admin:
+        request_rows = user_db.list_requests()
+        populate_request_usernames(request_rows, user_db)
+        return request_rows
+
+    if db_user_id is None:
+        return []
+    return user_db.list_requests(user_id=db_user_id)
+
+
+def _parse_item_key(item_key: Any, prefix: str) -> str | None:
+    """Extract the value after 'prefix:' from an item_key string."""
+    if not isinstance(item_key, str) or not item_key.startswith(f"{prefix}:"):
+        return None
+    value = item_key.split(":", 1)[1].strip()
+    return value or None
+
+
+_ALL_BUCKET_KEYS = (*ACTIVE_QUEUE_STATUSES, *TERMINAL_QUEUE_STATUSES)
+
+
+def _build_download_status_from_db(
+    *,
+    db_rows: list[dict[str, Any]],
+    queue_status: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    """Build the download status dict from DB rows, overlaying live queue data.
+
+    Active DB rows are matched against the queue for live progress.
+    Terminal DB rows go directly into their final bucket.
+    Stale active rows (no queue entry) are treated as interrupted errors.
+    """
+    status: dict[str, dict[str, Any]] = {key: {} for key in _ALL_BUCKET_KEYS}
+
+    # Index queue items by task_id for fast lookup: task_id -> (bucket_key, payload)
+    queue_index: dict[str, tuple[str, dict[str, Any]]] = {}
+    for bucket_key in _ALL_BUCKET_KEYS:
+        bucket = queue_status.get(bucket_key)
+        if not isinstance(bucket, dict):
+            continue
+        for task_id, payload in bucket.items():
+            queue_index[str(task_id)] = (bucket_key, payload)
+
+    for row in db_rows:
+        task_id = str(row.get("task_id") or "").strip()
+        if not task_id:
+            continue
+
+        final_status = row.get("final_status")
+
+        if final_status == ACTIVE_DOWNLOAD_STATUS:
+            queue_entry = queue_index.pop(task_id, None)
+            if queue_entry is not None:
+                bucket_key, queue_payload = queue_entry
+                status[bucket_key][task_id] = queue_payload
+            else:
+                # Stale active row — no queue entry means it was interrupted
+                download_payload = DownloadHistoryService.to_download_payload(row)
+                download_payload["status_message"] = "Interrupted"
+                status[QueueStatus.ERROR][task_id] = download_payload
+        elif final_status in VALID_TERMINAL_STATUSES:
+            download_payload = DownloadHistoryService.to_download_payload(row)
+            # For complete/cancelled the saved status_message is a stale
+            # progress string (e.g. "Fetching download sources") — clear it
+            # so the frontend only shows its own status label.  Error rows
+            # keep theirs since the message describes the failure.
+            if final_status in ("complete", "cancelled"):
+                download_payload["status_message"] = None
+            status[final_status][task_id] = download_payload
+
+    return status
+
+
+def _request_terminal_status(row: dict[str, Any]) -> str | None:
+    request_status = row.get("status")
+    if request_status == RequestStatus.PENDING:
+        return None
+    if request_status == RequestStatus.REJECTED:
+        return RequestStatus.REJECTED
+    if request_status == RequestStatus.CANCELLED:
+        return RequestStatus.CANCELLED
+    if request_status != RequestStatus.FULFILLED:
+        return None
+
+    delivery_state = str(row.get("delivery_state") or "").strip().lower()
+    if delivery_state in {QueueStatus.ERROR, QueueStatus.CANCELLED}:
+        return delivery_state
+    return QueueStatus.COMPLETE
+
+
+def _minimal_request_snapshot(request_row: dict[str, Any], request_id: int) -> dict[str, Any]:
+    book_data = request_row.get("book_data")
+    release_data = request_row.get("release_data")
+    if not isinstance(book_data, dict):
+        book_data = {}
+    if not isinstance(release_data, dict):
+        release_data = {}
+
+    minimal_request = {
+        "id": request_id,
+        "user_id": request_row.get("user_id"),
+        "status": request_row.get("status"),
+        "request_level": request_row.get("request_level"),
+        "delivery_state": request_row.get("delivery_state"),
+        "book_data": book_data,
+        "release_data": release_data,
+        "note": request_row.get("note"),
+        "admin_note": request_row.get("admin_note"),
+        "created_at": request_row.get("created_at"),
+        "updated_at": request_row.get("reviewed_at") or request_row.get("created_at"),
+    }
+    username = request_row.get("username")
+    if isinstance(username, str):
+        minimal_request["username"] = username
+    return {"kind": "request", "request": minimal_request}
+
+
+def _request_history_entry(
+    request_row: dict[str, Any],
+    *,
+    dismissed_at: str | None,
+) -> dict[str, Any] | None:
+    request_id = normalize_positive_int(request_row.get("id"))
+    if request_id is None:
+        return None
+    final_status = _request_terminal_status(request_row)
+    item_key = f"request:{request_id}"
+    return {
+        "id": item_key,
+        "user_id": request_row.get("user_id"),
+        "item_type": "request",
+        "item_key": item_key,
+        "dismissed_at": dismissed_at,
+        "snapshot": _minimal_request_snapshot(request_row, request_id),
+        "origin": "request",
+        "final_status": final_status,
+        "terminal_at": request_row.get("reviewed_at") or request_row.get("created_at"),
+        "request_id": request_id,
+        "source_id": extract_release_source_id(request_row.get("release_data")),
+    }
+
+
+def register_activity_routes(
+    app: Flask,
+    user_db: UserDB,
+    *,
+    activity_view_state_service: ActivityViewStateService,
+    download_history_service: DownloadHistoryService,
+    resolve_auth_mode: Callable[[], str],
+    queue_status: Callable[..., dict[str, dict[str, Any]]],
+    sync_request_delivery_states: Callable[..., list[dict[str, Any]]],
+    emit_request_updates: Callable[[list[dict[str, Any]]], None],
+    ws_manager: Any | None = None,
+) -> None:
+    """Register activity routes."""
+
+    @app.route("/api/activity/snapshot", methods=["GET"])
+    def api_activity_snapshot():
+        auth_gate = _require_authenticated(resolve_auth_mode)
+        if auth_gate is not None:
+            return auth_gate
+
+        actor, actor_error = _resolve_activity_actor(
+            user_db=user_db,
+            resolve_auth_mode=resolve_auth_mode,
+        )
+        if actor_error is not None:
+            return actor_error
+
+        hidden_rows = activity_view_state_service.list_hidden(viewer_scope=actor.viewer_scope)
+        hidden_item_keys = {str(row.get("item_key") or "").strip() for row in hidden_rows}
+        dismissed_entries = [
+            {
+                "item_type": str(row.get("item_type") or "").strip().lower(),
+                "item_key": str(row.get("item_key") or "").strip(),
+            }
+            for row in hidden_rows
+            if str(row.get("item_type") or "").strip().lower() in {"download", "request"}
+            and str(row.get("item_key") or "").strip()
+        ]
+        live_queue = queue_status(user_id=actor.owner_scope)
+        db_rows = download_history_service.list_recent(
+            user_id=actor.owner_scope,
+            limit=200,
+        )
+        visible_db_rows = [
+            row
+            for row in db_rows
+            if f"download:{str(row.get('task_id') or '').strip()}" not in hidden_item_keys
+        ]
+
+        status = _build_download_status_from_db(
+            db_rows=visible_db_rows,
+            queue_status=live_queue,
+        )
+
+        updated_requests = sync_request_delivery_states(
+            user_db,
+            queue_status=status,
+            user_id=actor.owner_scope,
+        )
+        emit_request_updates(updated_requests)
+        request_rows = _list_visible_requests(
+            user_db,
+            is_admin=actor.is_admin,
+            db_user_id=actor.db_user_id,
+        )
+        visible_request_rows: list[dict[str, Any]] = []
+        for row in request_rows:
+            request_id = normalize_positive_int(row.get("id"))
+            if request_id is None:
+                continue
+            if f"request:{request_id}" in hidden_item_keys:
+                continue
+            visible_request_rows.append(row)
+
+        return jsonify(
+            {
+                "status": status,
+                "requests": visible_request_rows,
+                "dismissed": dismissed_entries,
+            }
+        )
+
+    @app.route("/api/activity/dismiss", methods=["POST"])
+    def api_activity_dismiss():
+        auth_gate = _require_authenticated(resolve_auth_mode)
+        if auth_gate is not None:
+            return auth_gate
+
+        actor, actor_error = _resolve_activity_actor(
+            user_db=user_db,
+            resolve_auth_mode=resolve_auth_mode,
+        )
+        if actor_error is not None:
+            return actor_error
+
+        data = request.get_json(silent=True)
+        if not isinstance(data, dict):
+            return jsonify({"error": "Invalid payload"}), 400
+
+        item_type = str(data.get("item_type") or "").strip().lower()
+        item_key = data.get("item_key")
+
+        dismissal_item: dict[str, str] | None = None
+
+        if item_type == "download":
+            task_id = _parse_item_key(item_key, "download")
+            if task_id is None:
+                return jsonify({"error": "item_key must be in the format download:<task_id>"}), 400
+
+            existing = download_history_service.get_by_task_id(task_id)
+            if existing is None:
+                return jsonify({"error": "Download not found"}), 404
+
+            ownership_gate = _check_item_ownership(actor, existing)
+            if ownership_gate is not None:
+                return ownership_gate
+            terminal_gate = _check_terminal_download(existing)
+            if terminal_gate is not None:
+                return terminal_gate
+
+            activity_view_state_service.dismiss(
+                viewer_scope=actor.viewer_scope,
+                item_type="download",
+                item_key=f"download:{task_id}",
+            )
+            dismissal_item = {"item_type": "download", "item_key": f"download:{task_id}"}
+
+        elif item_type == "request":
+            request_id = normalize_positive_int(_parse_item_key(item_key, "request"))
+            if request_id is None:
+                return jsonify({"error": "item_key must be in the format request:<id>"}), 400
+
+            request_row = user_db.get_request(request_id)
+            if request_row is None:
+                return jsonify({"error": "Request not found"}), 404
+
+            ownership_gate = _check_item_ownership(actor, request_row)
+            if ownership_gate is not None:
+                return ownership_gate
+            terminal_gate = _check_terminal_request(request_row)
+            if terminal_gate is not None:
+                return terminal_gate
+
+            activity_view_state_service.dismiss(
+                viewer_scope=actor.viewer_scope,
+                item_type="request",
+                item_key=f"request:{request_id}",
+            )
+            dismissal_item = {"item_type": "request", "item_key": f"request:{request_id}"}
+        else:
+            return jsonify({"error": "item_type must be one of: download, request"}), 400
+
+        room = _activity_ws_room(actor)
+        emit_ws_event(
+            ws_manager,
+            event_name="activity_update",
+            room=room,
+            payload={
+                "kind": "dismiss",
+                "item_type": dismissal_item["item_type"],
+                "item_key": dismissal_item["item_key"],
+            },
+        )
+
+        return jsonify({"status": "dismissed", "item": dismissal_item})
+
+    @app.route("/api/activity/dismiss-many", methods=["POST"])
+    def api_activity_dismiss_many():
+        auth_gate = _require_authenticated(resolve_auth_mode)
+        if auth_gate is not None:
+            return auth_gate
+
+        actor, actor_error = _resolve_activity_actor(
+            user_db=user_db,
+            resolve_auth_mode=resolve_auth_mode,
+        )
+        if actor_error is not None:
+            return actor_error
+
+        data = request.get_json(silent=True)
+        if not isinstance(data, dict):
+            return jsonify({"error": "Invalid payload"}), 400
+        items = data.get("items")
+        if not isinstance(items, list):
+            return jsonify({"error": "items must be an array"}), 400
+
+        dismissal_items: list[dict[str, str]] = []
+        missing_item_keys: list[str] = []
+
+        for item in items:
+            if not isinstance(item, dict):
+                return jsonify({"error": "items must contain objects"}), 400
+
+            item_type = str(item.get("item_type") or "").strip().lower()
+            item_key = item.get("item_key")
+
+            if item_type == "download":
+                task_id = _parse_item_key(item_key, "download")
+                if task_id is None:
+                    return jsonify({"error": "download item_key must be in the format download:<task_id>"}), 400
+                existing = download_history_service.get_by_task_id(task_id)
+                if existing is None:
+                    missing_item_keys.append(f"download:{task_id}")
+                    continue
+                ownership_gate = _check_item_ownership(actor, existing)
+                if ownership_gate is not None:
+                    return ownership_gate
+                terminal_gate = _check_terminal_download(existing)
+                if terminal_gate is not None:
+                    return terminal_gate
+                dismissal_items.append({"item_type": "download", "item_key": f"download:{task_id}"})
+                continue
+
+            if item_type == "request":
+                request_id = normalize_positive_int(_parse_item_key(item_key, "request"))
+                if request_id is None:
+                    return jsonify({"error": "request item_key must be in the format request:<id>"}), 400
+                request_row = user_db.get_request(request_id)
+                if request_row is None:
+                    missing_item_keys.append(f"request:{request_id}")
+                    continue
+                ownership_gate = _check_item_ownership(actor, request_row)
+                if ownership_gate is not None:
+                    return ownership_gate
+                terminal_gate = _check_terminal_request(request_row)
+                if terminal_gate is not None:
+                    return terminal_gate
+                dismissal_items.append({"item_type": "request", "item_key": f"request:{request_id}"})
+                continue
+
+            return jsonify({"error": "item_type must be one of: download, request"}), 400
+
+        if missing_item_keys:
+            return (
+                jsonify(
+                    {
+                        "error": "One or more activity items were not found",
+                        "missing_item_keys": missing_item_keys,
+                    }
+                ),
+                404,
+            )
+
+        dismissed_count = activity_view_state_service.dismiss_many(
+            viewer_scope=actor.viewer_scope,
+            items=dismissal_items,
+        )
+
+        room = _activity_ws_room(actor)
+        emit_ws_event(
+            ws_manager,
+            event_name="activity_update",
+            room=room,
+            payload={
+                "kind": "dismiss_many",
+                "count": dismissed_count,
+            },
+        )
+
+        return jsonify({"status": "dismissed", "count": dismissed_count})
+
+    @app.route("/api/activity/history", methods=["GET"])
+    def api_activity_history():
+        auth_gate = _require_authenticated(resolve_auth_mode)
+        if auth_gate is not None:
+            return auth_gate
+
+        actor, actor_error = _resolve_activity_actor(
+            user_db=user_db,
+            resolve_auth_mode=resolve_auth_mode,
+        )
+        if actor_error is not None:
+            return actor_error
+
+        limit = request.args.get("limit", type=int, default=50)
+        offset = request.args.get("offset", type=int, default=0)
+        if limit is None:
+            limit = 50
+        if offset is None:
+            offset = 0
+        if limit < 1:
+            return jsonify({"error": "limit must be a positive integer"}), 400
+        if offset < 0:
+            return jsonify({"error": "offset must be a non-negative integer"}), 400
+
+        history_rows = activity_view_state_service.list_history(
+            viewer_scope=actor.viewer_scope,
+            limit=limit,
+            offset=offset,
+        )
+        payload: list[dict[str, Any]] = []
+
+        for history_row in history_rows:
+            item_type = str(history_row.get("item_type") or "").strip().lower()
+            item_key = str(history_row.get("item_key") or "").strip()
+            dismissed_at = history_row.get("dismissed_at")
+
+            if not isinstance(dismissed_at, str) or not dismissed_at.strip():
+                raise RuntimeError(f"Activity history state missing dismissed_at for {item_key}")
+
+            if item_type == "download":
+                task_id = _parse_item_key(item_key, "download")
+                if task_id is None:
+                    raise RuntimeError(f"Invalid activity history item_key: {item_key}")
+
+                download_row = download_history_service.get_by_task_id(task_id)
+                if download_row is None:
+                    raise RuntimeError(f"Download history row not found for {item_key}")
+
+                if not actor.is_admin:
+                    owner_user_id = normalize_positive_int(download_row.get("user_id"))
+                    if owner_user_id != actor.db_user_id:
+                        raise RuntimeError(f"Viewer state out of scope for {item_key}")
+
+                payload.append(
+                    DownloadHistoryService.to_history_row(
+                        download_row,
+                        dismissed_at=dismissed_at,
+                    )
+                )
+                continue
+
+            if item_type == "request":
+                request_id = normalize_positive_int(_parse_item_key(item_key, "request"))
+                if request_id is None:
+                    raise RuntimeError(f"Invalid activity history item_key: {item_key}")
+
+                request_row = user_db.get_request(request_id)
+                if request_row is None:
+                    raise RuntimeError(f"Request row not found for {item_key}")
+
+                if not actor.is_admin:
+                    owner_user_id = normalize_positive_int(request_row.get("user_id"))
+                    if owner_user_id != actor.db_user_id:
+                        raise RuntimeError(f"Viewer state out of scope for {item_key}")
+
+                populate_request_usernames([request_row], user_db)
+                entry = _request_history_entry(
+                    request_row,
+                    dismissed_at=dismissed_at,
+                )
+                if entry is None:
+                    raise RuntimeError(f"Failed to build request history entry for {item_key}")
+                payload.append(entry)
+                continue
+
+            raise RuntimeError(f"Unknown activity history item_type: {item_type}")
+
+        return jsonify(payload)
+
+    @app.route("/api/activity/history", methods=["DELETE"])
+    def api_activity_history_clear():
+        auth_gate = _require_authenticated(resolve_auth_mode)
+        if auth_gate is not None:
+            return auth_gate
+
+        actor, actor_error = _resolve_activity_actor(
+            user_db=user_db,
+            resolve_auth_mode=resolve_auth_mode,
+        )
+        if actor_error is not None:
+            return actor_error
+
+        cleared_count = activity_view_state_service.clear_history(
+            viewer_scope=actor.viewer_scope,
+        )
+
+        room = _activity_ws_room(actor)
+        emit_ws_event(
+            ws_manager,
+            event_name="activity_update",
+            room=room,
+            payload={
+                "kind": "history_cleared",
+                "count": cleared_count,
+            },
+        )
+        return jsonify({"status": "cleared", "cleared_count": cleared_count})

shelfmark/core/activity_view_state_service.py

@@ -0,0 +1,310 @@
+"""Persistence helpers for per-viewer activity visibility state."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from typing import Any
+
+from shelfmark.core.request_helpers import now_utc_iso
+
+
+VALID_ACTIVITY_ITEM_TYPES = frozenset({"download", "request"})
+ADMIN_VIEWER_SCOPE = "admin:shared"
+NOAUTH_VIEWER_SCOPE = "noauth:shared"
+USER_VIEWER_SCOPE_PREFIX = "user:"
+
+
+def user_viewer_scope(user_id: int) -> str:
+    if not isinstance(user_id, int) or user_id < 1:
+        raise ValueError("user_id must be a positive integer")
+    return f"{USER_VIEWER_SCOPE_PREFIX}{user_id}"
+
+
+def normalize_viewer_scope(viewer_scope: Any) -> str:
+    if not isinstance(viewer_scope, str) or not viewer_scope.strip():
+        raise ValueError("viewer_scope must be a non-empty string")
+
+    normalized = viewer_scope.strip()
+    if normalized in {ADMIN_VIEWER_SCOPE, NOAUTH_VIEWER_SCOPE}:
+        return normalized
+
+    if not normalized.startswith(USER_VIEWER_SCOPE_PREFIX):
+        raise ValueError(
+            "viewer_scope must be one of: admin:shared, noauth:shared, or user:<id>"
+        )
+
+    raw_user_id = normalized[len(USER_VIEWER_SCOPE_PREFIX):].strip()
+    try:
+        parsed_user_id = int(raw_user_id)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("viewer_scope user id must be a positive integer") from exc
+
+    return user_viewer_scope(parsed_user_id)
+
+
+def _normalize_item_type(item_type: Any) -> str:
+    if not isinstance(item_type, str) or not item_type.strip():
+        raise ValueError("item_type must be a non-empty string")
+    normalized = item_type.strip().lower()
+    if normalized not in VALID_ACTIVITY_ITEM_TYPES:
+        raise ValueError("item_type must be one of: download, request")
+    return normalized
+
+
+def _normalize_item_key(item_key: Any, *, item_type: str) -> str:
+    if not isinstance(item_key, str) or not item_key.strip():
+        raise ValueError("item_key must be a non-empty string")
+
+    normalized = item_key.strip()
+    expected_prefix = f"{item_type}:"
+    if not normalized.startswith(expected_prefix):
+        raise ValueError(f"item_key must be in the format {expected_prefix}<id>")
+    if not normalized.split(":", 1)[1].strip():
+        raise ValueError(f"item_key must be in the format {expected_prefix}<id>")
+    return normalized
+
+
+class ActivityViewStateService:
+    """Service for per-viewer activity dismissal and history visibility."""
+
+    def __init__(self, db_path: str):
+        self._db_path = db_path
+        self._lock = threading.Lock()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    def list_hidden(
+        self,
+        *,
+        viewer_scope: str,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+        normalized_limit = None if limit is None else max(1, int(limit))
+        query = """
+            SELECT item_type, item_key, dismissed_at, cleared_at
+            FROM activity_view_state
+            WHERE viewer_scope = ?
+              AND dismissed_at IS NOT NULL
+            ORDER BY COALESCE(cleared_at, dismissed_at) DESC, id DESC
+        """
+        params: list[Any] = [normalized_scope]
+        if normalized_limit is not None:
+            query += "\nLIMIT ?"
+            params.append(normalized_limit)
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(query, params).fetchall()
+            return [dict(row) for row in rows]
+        finally:
+            conn.close()
+
+    def list_history(
+        self,
+        *,
+        viewer_scope: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+        normalized_limit = max(1, min(int(limit), 5000))
+        normalized_offset = max(0, int(offset))
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(
+                """
+                SELECT item_type, item_key, dismissed_at
+                FROM activity_view_state
+                WHERE viewer_scope = ?
+                  AND dismissed_at IS NOT NULL
+                  AND cleared_at IS NULL
+                ORDER BY dismissed_at DESC, id DESC
+                LIMIT ? OFFSET ?
+                """,
+                (normalized_scope, normalized_limit, normalized_offset),
+            ).fetchall()
+            return [dict(row) for row in rows]
+        finally:
+            conn.close()
+
+    def dismiss(
+        self,
+        *,
+        viewer_scope: str,
+        item_type: str,
+        item_key: str,
+    ) -> int:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+        normalized_type = _normalize_item_type(item_type)
+        normalized_key = _normalize_item_key(item_key, item_type=normalized_type)
+        dismissed_at = now_utc_iso()
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    """
+                    INSERT INTO activity_view_state (
+                        viewer_scope,
+                        item_type,
+                        item_key,
+                        dismissed_at,
+                        cleared_at
+                    )
+                    VALUES (?, ?, ?, ?, NULL)
+                    ON CONFLICT(viewer_scope, item_type, item_key) DO UPDATE SET
+                        dismissed_at = excluded.dismissed_at,
+                        cleared_at = NULL
+                    """,
+                    (normalized_scope, normalized_type, normalized_key, dismissed_at),
+                )
+                conn.commit()
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                return max(rowcount, 0)
+            finally:
+                conn.close()
+
+    def dismiss_many(
+        self,
+        *,
+        viewer_scope: str,
+        items: list[dict[str, str]],
+    ) -> int:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+        if not items:
+            return 0
+
+        seen: set[tuple[str, str]] = set()
+        normalized_items: list[tuple[str, str]] = []
+        for item in items:
+            normalized_type = _normalize_item_type(item.get("item_type"))
+            normalized_key = _normalize_item_key(item.get("item_key"), item_type=normalized_type)
+            marker = (normalized_type, normalized_key)
+            if marker in seen:
+                continue
+            seen.add(marker)
+            normalized_items.append(marker)
+
+        if not normalized_items:
+            return 0
+
+        dismissed_at = now_utc_iso()
+        with self._lock:
+            conn = self._connect()
+            try:
+                total = 0
+                for normalized_type, normalized_key in normalized_items:
+                    cursor = conn.execute(
+                        """
+                        INSERT INTO activity_view_state (
+                            viewer_scope,
+                            item_type,
+                            item_key,
+                            dismissed_at,
+                            cleared_at
+                        )
+                        VALUES (?, ?, ?, ?, NULL)
+                        ON CONFLICT(viewer_scope, item_type, item_key) DO UPDATE SET
+                            dismissed_at = excluded.dismissed_at,
+                            cleared_at = NULL
+                        """,
+                        (normalized_scope, normalized_type, normalized_key, dismissed_at),
+                    )
+                    rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                    total += max(rowcount, 0)
+                conn.commit()
+                return total
+            finally:
+                conn.close()
+
+    def clear_history(self, *, viewer_scope: str) -> int:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+        cleared_at = now_utc_iso()
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    """
+                    UPDATE activity_view_state
+                    SET cleared_at = ?
+                    WHERE viewer_scope = ?
+                      AND dismissed_at IS NOT NULL
+                      AND cleared_at IS NULL
+                    """,
+                    (cleared_at, normalized_scope),
+                )
+                conn.commit()
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                return max(rowcount, 0)
+            finally:
+                conn.close()
+
+    def clear_item_for_all_viewers(self, *, item_type: str, item_key: str) -> int:
+        normalized_type = _normalize_item_type(item_type)
+        normalized_key = _normalize_item_key(item_key, item_type=normalized_type)
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    """
+                    DELETE FROM activity_view_state
+                    WHERE item_type = ? AND item_key = ?
+                    """,
+                    (normalized_type, normalized_key),
+                )
+                conn.commit()
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                return max(rowcount, 0)
+            finally:
+                conn.close()
+
+    def delete_viewer_scope(self, *, viewer_scope: str) -> int:
+        normalized_scope = normalize_viewer_scope(viewer_scope)
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    "DELETE FROM activity_view_state WHERE viewer_scope = ?",
+                    (normalized_scope,),
+                )
+                conn.commit()
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                return max(rowcount, 0)
+            finally:
+                conn.close()
+
+    def delete_items(self, *, item_type: str, item_keys: list[str]) -> int:
+        normalized_type = _normalize_item_type(item_type)
+        normalized_keys = [
+            _normalize_item_key(item_key, item_type=normalized_type)
+            for item_key in item_keys
+        ]
+        if not normalized_keys:
+            return 0
+
+        placeholders = ",".join("?" for _ in normalized_keys)
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    f"""
+                    DELETE FROM activity_view_state
+                    WHERE item_type = ? AND item_key IN ({placeholders})
+                    """,
+                    (normalized_type, *normalized_keys),
+                )
+                conn.commit()
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                return max(rowcount, 0)
+            finally:
+                conn.close()

shelfmark/core/admin_routes.py

@@ -0,0 +1,420 @@
+"""Admin user management API routes.
+
+Registers /api/admin/users CRUD endpoints for managing users.
+All endpoints require admin session.
+"""
+
+from functools import wraps
+import os
+import sqlite3
+from typing import Any
+
+from flask import Flask, g, jsonify, request, session
+from werkzeug.security import generate_password_hash
+
+from shelfmark.config.booklore_settings import (
+    get_booklore_library_options,
+    get_booklore_path_options,
+)
+from shelfmark.config.env import CWA_DB_PATH
+from shelfmark.core.admin_settings_routes import (
+    register_admin_settings_routes,
+    validate_user_settings,
+)
+from shelfmark.core.auth_modes import (
+    AUTH_SOURCE_BUILTIN,
+    AUTH_SOURCE_CWA,
+    AUTH_SOURCE_OIDC,
+    AUTH_SOURCE_PROXY,
+    is_user_active_for_auth_mode,
+    load_active_auth_mode,
+    normalize_auth_source,
+)
+from shelfmark.core.cwa_user_sync import sync_cwa_users_from_rows
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.settings_registry import load_config_file
+from shelfmark.core.user_db import UserDB
+
+logger = setup_logger(__name__)
+
+
+def _get_user_edit_capabilities(
+    user: dict[str, Any],
+    security_config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return backend-authored capability flags for the user edit form."""
+    auth_source = normalize_auth_source(
+        user.get("auth_source"),
+        user.get("oidc_subject"),
+    )
+    if security_config is None and auth_source == AUTH_SOURCE_OIDC:
+        security_config = load_config_file("security")
+
+    oidc_use_admin_group = bool((security_config or {}).get("OIDC_USE_ADMIN_GROUP", True))
+    role_managed_by_oidc_group = auth_source == AUTH_SOURCE_OIDC and oidc_use_admin_group
+    can_edit_role = auth_source == AUTH_SOURCE_BUILTIN or (
+        auth_source == AUTH_SOURCE_OIDC and not role_managed_by_oidc_group
+    )
+
+    return {
+        "authSource": auth_source,
+        "canSetPassword": auth_source == AUTH_SOURCE_BUILTIN,
+        "canEditRole": can_edit_role,
+        "canEditEmail": auth_source in {AUTH_SOURCE_BUILTIN, AUTH_SOURCE_PROXY},
+        "canEditDisplayName": auth_source != AUTH_SOURCE_OIDC,
+    }
+
+
+def _sanitize_user(user: dict) -> dict:
+    """Remove sensitive fields from user dict before returning to client."""
+    sanitized = dict(user)
+    sanitized.pop("password_hash", None)
+    return sanitized
+
+
+def _oidc_role_management_message(security_config: dict[str, Any]) -> str:
+    admin_group = security_config.get("OIDC_ADMIN_GROUP", "")
+    if admin_group:
+        return (
+            "Admin roles for OIDC users are managed by the "
+            f"'{admin_group}' group in your identity provider"
+        )
+    return (
+        "Disable 'Use Admin Group for Authorization' in security settings "
+        "to manage roles manually"
+    )
+
+
+def _serialize_user(
+    user: dict[str, Any],
+    auth_method: str,
+    security_config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Sanitize and enrich a user payload for API responses."""
+    payload = _sanitize_user(user)
+    payload["auth_source"] = normalize_auth_source(
+        payload.get("auth_source"),
+        payload.get("oidc_subject"),
+    )
+    payload["is_active"] = is_user_active_for_auth_mode(payload, auth_method)
+    payload["edit_capabilities"] = _get_user_edit_capabilities(
+        payload,
+        security_config=security_config,
+    )
+    return payload
+
+
+
+
+def _sync_all_cwa_users(user_db: UserDB) -> dict[str, int]:
+    """Sync all users from the Calibre-Web database into users.db."""
+    if not CWA_DB_PATH or not CWA_DB_PATH.exists():
+        raise FileNotFoundError("Calibre-Web database is not available")
+
+    db_path = os.fspath(CWA_DB_PATH)
+    db_uri = f"file:{db_path}?mode=ro&immutable=1"
+    conn = sqlite3.connect(db_uri, uri=True)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT name, role, email FROM user")
+        rows = cur.fetchall()
+    finally:
+        conn.close()
+
+    return sync_cwa_users_from_rows(user_db, rows)
+
+
+def register_admin_routes(app: Flask, user_db: UserDB) -> None:
+    """Register admin user management routes on the Flask app."""
+
+    def _require_admin(f):
+        """Decorator to require admin session for admin routes.
+
+        In no-auth mode, everyone has access (is_admin defaults True).
+        In auth-required modes, requires an authenticated session with admin role.
+        Caches the resolved auth_mode in ``g.auth_mode`` for the request.
+        """
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            auth_mode = load_active_auth_mode(CWA_DB_PATH, user_db=user_db)
+            g.auth_mode = auth_mode
+            if auth_mode != "none":
+                if "user_id" not in session:
+                    return jsonify({"error": "Authentication required"}), 401
+                if not session.get("is_admin", False):
+                    return jsonify({"error": "Admin access required"}), 403
+            return f(*args, **kwargs)
+        return decorated
+
+    @app.route("/api/admin/users", methods=["GET"])
+    @_require_admin
+    def admin_list_users():
+        """List all users."""
+        users = user_db.list_users()
+        auth_mode = g.auth_mode
+        security_config = load_config_file("security")
+        return jsonify([
+            _serialize_user(u, auth_mode, security_config=security_config)
+            for u in users
+        ])
+
+    @app.route("/api/admin/users", methods=["POST"])
+    @_require_admin
+    def admin_create_user():
+        """Create a new user with password authentication."""
+        data = request.get_json() or {}
+        auth_mode = g.auth_mode
+
+        username = (data.get("username") or "").strip()
+        password = data.get("password", "")
+        email = (data.get("email") or "").strip() or None
+        display_name = (data.get("display_name") or "").strip() or None
+        role = data.get("role", "user")
+
+        if auth_mode in {AUTH_SOURCE_PROXY, AUTH_SOURCE_CWA}:
+            return jsonify({
+                "error": "Local user creation is disabled in this authentication mode",
+                "message": (
+                    "Users are provisioned by your external authentication source. "
+                    "Switch to builtin or OIDC mode to create local users."
+                ),
+            }), 400
+
+        if not username:
+            return jsonify({"error": "Username is required"}), 400
+        if not password or len(password) < 4:
+            return jsonify({"error": "Password must be at least 4 characters"}), 400
+        if role not in ("admin", "user"):
+            return jsonify({"error": "Role must be 'admin' or 'user'"}), 400
+
+        # First user is always admin
+        existing_users = user_db.list_users()
+        if not existing_users:
+            role = "admin"
+
+        # Check if username already exists
+        if user_db.get_user(username=username):
+            return jsonify({"error": "Username already exists"}), 409
+
+        password_hash = generate_password_hash(password)
+        try:
+            user = user_db.create_user(
+                username=username,
+                password_hash=password_hash,
+                email=email,
+                display_name=display_name,
+                auth_source=AUTH_SOURCE_BUILTIN,
+                role=role,
+            )
+        except ValueError:
+            return jsonify({"error": "Username already exists"}), 409
+        logger.info(
+            "Shelfmark user created "
+            f"(source=manual_admin_create, created_by={session.get('user_id', 'unknown')}, "
+            f"username={username}, role={role}, auth_source={AUTH_SOURCE_BUILTIN})"
+        )
+        return jsonify(
+            _serialize_user(
+                user,
+                g.auth_mode,
+                security_config=load_config_file("security"),
+            )
+        ), 201
+
+    @app.route("/api/admin/users/<int:user_id>", methods=["GET"])
+    @_require_admin
+    def admin_get_user(user_id):
+        """Get a user by ID with their settings."""
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        result = _serialize_user(
+            user,
+            g.auth_mode,
+            security_config=load_config_file("security"),
+        )
+        result["settings"] = user_db.get_user_settings(user_id)
+        return jsonify(result)
+
+    @app.route("/api/admin/users/<int:user_id>", methods=["PUT"])
+    @_require_admin
+    def admin_update_user(user_id):
+        """Update user fields and/or settings."""
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        data = request.get_json() or {}
+        security_config = load_config_file("security")
+        auth_source = normalize_auth_source(
+            user.get("auth_source"),
+            user.get("oidc_subject"),
+        )
+        capabilities = _get_user_edit_capabilities(user, security_config=security_config)
+
+        # Handle optional password update
+        password = data.get("password", "")
+        if password:
+            if not capabilities["canSetPassword"]:
+                return jsonify({
+                    "error": f"Cannot set password for {auth_source.upper()} users",
+                    "message": "Password authentication is only available for local users.",
+                }), 400
+            if len(password) < 4:
+                return jsonify({"error": "Password must be at least 4 characters"}), 400
+            user_db.update_user(user_id, password_hash=generate_password_hash(password))
+
+        # Update user fields
+        user_fields = {}
+        for field in ("role", "email", "display_name"):
+            if field in data:
+                user_fields[field] = data[field]
+
+        if "role" in user_fields and user_fields["role"] not in ("admin", "user"):
+            return jsonify({"error": "Role must be 'admin' or 'user'"}), 400
+
+        role_changed = "role" in user_fields and user_fields["role"] != user.get("role")
+        email_changed = "email" in user_fields and user_fields["email"] != user.get("email")
+        display_name_changed = (
+            "display_name" in user_fields
+            and user_fields["display_name"] != user.get("display_name")
+        )
+
+        if role_changed and not capabilities["canEditRole"]:
+            if auth_source == AUTH_SOURCE_OIDC:
+                return jsonify({
+                    "error": "Cannot change role for OIDC user when group-based authorization is enabled",
+                    "message": _oidc_role_management_message(security_config),
+                }), 400
+
+            return jsonify({
+                "error": f"Cannot change role for {auth_source.upper()} users",
+                "message": "Role is managed by the external authentication source.",
+            }), 400
+
+        if email_changed and not capabilities["canEditEmail"]:
+            if auth_source == AUTH_SOURCE_CWA:
+                return jsonify({
+                    "error": "Cannot change email for CWA users",
+                    "message": "Email is synced from Calibre-Web.",
+                }), 400
+
+            return jsonify({
+                "error": "Cannot change email for OIDC users",
+                "message": "Email is managed by your identity provider.",
+            }), 400
+
+        if display_name_changed and not capabilities["canEditDisplayName"]:
+            return jsonify({
+                "error": "Cannot change display name for OIDC users",
+                "message": "Display name is managed by your identity provider.",
+            }), 400
+
+        # Allow demoting the last admin account.
+        # Auth mode resolution automatically falls back to "none" when no
+        # local password admin remains.
+
+        # Avoid unnecessary writes for no-op field updates.
+        for field in ("role", "email", "display_name"):
+            if field in user_fields and user_fields[field] == user.get(field):
+                user_fields.pop(field)
+
+        if user_fields:
+            user_db.update_user(user_id, **user_fields)
+
+        # Update per-user settings
+        if "settings" in data:
+            if not isinstance(data["settings"], dict):
+                return jsonify({"error": "Settings must be an object"}), 400
+
+            validated_settings, validation_errors = validate_user_settings(data["settings"])
+            if validation_errors:
+                return jsonify({
+                    "error": "Invalid settings payload",
+                    "details": validation_errors,
+                }), 400
+
+            user_db.set_user_settings(user_id, validated_settings)
+            # Ensure runtime reads see updated per-user overrides immediately.
+            try:
+                from shelfmark.core.config import config as app_config
+                app_config.refresh(force=True)
+            except Exception:
+                pass
+
+        updated = user_db.get_user(user_id=user_id)
+        result = _serialize_user(
+            updated,
+            g.auth_mode,
+            security_config=security_config,
+        )
+        result["settings"] = user_db.get_user_settings(user_id)
+        logger.info(f"Admin updated user {user_id}")
+        return jsonify(result)
+
+    @app.route("/api/admin/users/sync-cwa", methods=["POST"])
+    @_require_admin
+    def admin_sync_cwa_users():
+        """Manually sync users from Calibre-Web into users.db."""
+        if g.auth_mode != AUTH_SOURCE_CWA:
+            return jsonify({
+                "error": "CWA sync is only available when CWA authentication is enabled",
+            }), 400
+
+        try:
+            summary = _sync_all_cwa_users(user_db)
+        except FileNotFoundError:
+            return jsonify({
+                "error": "Calibre-Web database is not available",
+                "message": "Verify app.db is mounted and readable at /auth/app.db.",
+            }), 503
+        except Exception as exc:
+            logger.error(f"Failed to sync CWA users: {exc}")
+            return jsonify({
+                "error": "Failed to sync users from Calibre-Web",
+            }), 500
+
+        message = (
+            f"Synced {summary['total']} CWA users "
+            f"({summary['created']} created, {summary['updated']} updated, "
+            f"{summary.get('deleted', 0)} deleted)."
+        )
+        logger.info(message)
+        return jsonify({
+            "success": True,
+            "message": message,
+            **summary,
+        })
+
+    register_admin_settings_routes(app, user_db, _require_admin)
+
+    @app.route("/api/admin/users/<int:user_id>", methods=["DELETE"])
+    @_require_admin
+    def admin_delete_user(user_id):
+        """Delete a user."""
+        # Prevent self-deletion
+        if session.get("db_user_id") == user_id:
+            return jsonify({"error": "Cannot delete your own account"}), 400
+
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        auth_source = normalize_auth_source(
+            user.get("auth_source"),
+            user.get("oidc_subject"),
+        )
+        if auth_source == AUTH_SOURCE_CWA and auth_source == g.auth_mode:
+            return jsonify({
+                "error": f"Cannot delete active {auth_source.upper()} users",
+                "message": f"{auth_source.upper()} users are automatically re-provisioned on login.",
+            }), 400
+
+        # Allow deleting the last local admin account.
+        # Auth mode resolution automatically falls back to "none" when no
+        # local password admin remains.
+
+        user_db.delete_user(user_id)
+        logger.info(f"Admin deleted user {user_id}: {user['username']}")
+        return jsonify({"success": True})

shelfmark/core/admin_settings_routes.py

@@ -0,0 +1,258 @@
+"""Admin settings-introspection routes and settings validation helpers."""
+
+from typing import Any, Callable
+
+from flask import Flask, jsonify, request
+
+from shelfmark.config.notifications_settings import (
+    build_notification_test_result,
+    is_valid_notification_url,
+    normalize_notification_routes,
+)
+from shelfmark.config.users_settings import validate_search_preference_value
+from shelfmark.core.settings_registry import load_config_file
+from shelfmark.core.user_settings_overrides import (
+    build_user_preferences_payload as _build_user_preferences_payload,
+    get_ordered_user_overridable_fields as _get_ordered_user_overridable_fields,
+    get_settings_registry as _get_settings_registry,
+)
+from shelfmark.core.user_db import UserDB
+from shelfmark.core.request_policy import parse_policy_mode, validate_policy_rules
+
+
+def validate_user_settings(settings: dict[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    settings_registry = _get_settings_registry()
+    field_map = settings_registry.get_settings_field_map()
+    overridable_map = settings_registry.get_user_overridable_fields()
+
+    valid: dict[str, Any] = {}
+    errors: list[str] = []
+    for key, value in settings.items():
+        if key not in field_map:
+            errors.append(f"Unknown setting: {key}")
+        elif key not in overridable_map:
+            errors.append(f"Setting not user-overridable: {key}")
+        else:
+            # null means "clear the per-user override; use global default"
+            if value is None:
+                valid[key] = None
+                continue
+
+            if key in {"REQUEST_POLICY_DEFAULT_EBOOK", "REQUEST_POLICY_DEFAULT_AUDIOBOOK"}:
+                if parse_policy_mode(value) is None:
+                    errors.append(f"Invalid policy mode for {key}: {value}")
+                    continue
+
+            if key == "REQUEST_POLICY_RULES":
+                normalized_rules, rule_errors = validate_policy_rules(value)
+                if rule_errors:
+                    errors.extend(rule_errors)
+                    continue
+                valid[key] = normalized_rules
+                continue
+
+            if key == "USER_NOTIFICATION_ROUTES":
+                normalized_routes = normalize_notification_routes(value)
+                invalid_count = sum(
+                    1
+                    for row in normalized_routes
+                    if row.get("url") and not is_valid_notification_url(str(row.get("url")))
+                )
+                if invalid_count:
+                    errors.append(
+                        (
+                            f"Invalid value for {key}: found {invalid_count} invalid URL(s). "
+                            "Use URL values with a valid scheme, e.g. discord://... or ntfys://..."
+                        )
+                    )
+                    continue
+                valid[key] = normalized_routes
+                continue
+
+            normalized_search_value, search_validation_error = validate_search_preference_value(key, value)
+            if search_validation_error:
+                errors.append(search_validation_error)
+                continue
+            if key in {
+                "SEARCH_MODE",
+                "METADATA_PROVIDER",
+                "METADATA_PROVIDER_AUDIOBOOK",
+                "DEFAULT_RELEASE_SOURCE",
+            }:
+                valid[key] = normalized_search_value
+                continue
+
+            valid[key] = value
+
+    return valid, errors
+
+
+def build_user_notification_test_response(
+    *,
+    user_id: int,
+    payload: Any,
+) -> tuple[dict[str, Any], int]:
+    from shelfmark.core.config import config as app_config
+
+    routes_input = app_config.get("USER_NOTIFICATION_ROUTES", [], user_id=user_id)
+    if isinstance(payload, dict):
+        if "USER_NOTIFICATION_ROUTES" in payload:
+            routes_input = payload.get("USER_NOTIFICATION_ROUTES")
+        elif "routes" in payload:
+            routes_input = payload.get("routes")
+
+    result = build_notification_test_result(routes_input, scope_label="personal")
+    status_code = 200 if result.get("success", False) else 400
+    return result, status_code
+
+
+def register_admin_settings_routes(
+    app: Flask,
+    user_db: UserDB,
+    require_admin: Callable[[Callable[..., Any]], Callable[..., Any]],
+) -> None:
+    @app.route("/api/admin/download-defaults", methods=["GET"])
+    @require_admin
+    def admin_download_defaults():
+        config = load_config_file("downloads")
+        defaults = {
+            key: ("" if (value := config.get(key, field.default)) is None else value)
+            for key, field in _get_ordered_user_overridable_fields("downloads")
+        }
+
+        security_config = load_config_file("security")
+        defaults["OIDC_ADMIN_GROUP"] = security_config.get("OIDC_ADMIN_GROUP", "")
+        defaults["OIDC_USE_ADMIN_GROUP"] = security_config.get("OIDC_USE_ADMIN_GROUP", True)
+        defaults["OIDC_AUTO_PROVISION"] = security_config.get("OIDC_AUTO_PROVISION", True)
+        return jsonify(defaults)
+
+    @app.route("/api/admin/booklore-options", methods=["GET"])
+    @require_admin
+    def admin_booklore_options():
+        from shelfmark.core import admin_routes
+
+        return jsonify({
+            "libraries": admin_routes.get_booklore_library_options(),
+            "paths": admin_routes.get_booklore_path_options(),
+        })
+
+    @app.route("/api/admin/users/<int:user_id>/delivery-preferences", methods=["GET"])
+    @require_admin
+    def admin_get_delivery_preferences(user_id):
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        try:
+            payload = _build_user_preferences_payload(user_db, user_id, "downloads")
+        except ValueError:
+            return jsonify({"error": "Downloads settings tab not found"}), 500
+
+        return jsonify(payload)
+
+    @app.route("/api/admin/users/<int:user_id>/search-preferences", methods=["GET"])
+    @require_admin
+    def admin_get_search_preferences(user_id):
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        try:
+            payload = _build_user_preferences_payload(user_db, user_id, "search_mode")
+        except ValueError:
+            return jsonify({"error": "Search mode settings tab not found"}), 500
+
+        return jsonify(payload)
+
+    @app.route("/api/admin/users/<int:user_id>/notification-preferences", methods=["GET"])
+    @require_admin
+    def admin_get_notification_preferences(user_id):
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        try:
+            payload = _build_user_preferences_payload(user_db, user_id, "notifications")
+        except ValueError:
+            return jsonify({"error": "Notifications settings tab not found"}), 500
+
+        return jsonify(payload)
+
+    @app.route("/api/admin/users/<int:user_id>/notification-preferences/test", methods=["POST"])
+    @require_admin
+    def admin_test_notification_preferences(user_id):
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        payload = request.get_json(silent=True)
+        result, status_code = build_user_notification_test_response(
+            user_id=user_id,
+            payload=payload,
+        )
+        return jsonify(result), status_code
+
+    @app.route("/api/admin/settings/overrides-summary", methods=["GET"])
+    @require_admin
+    def admin_settings_overrides_summary():
+        settings_registry = _get_settings_registry()
+
+        tab_name = (request.args.get("tab") or "downloads").strip()
+        if not settings_registry.get_settings_tab(tab_name):
+            return jsonify({"error": f"Unknown settings tab: {tab_name}"}), 404
+
+        overridable_keys = list(settings_registry.get_user_overridable_fields(tab_name=tab_name))
+        keys_payload: dict[str, dict[str, Any]] = {}
+
+        for user_record in user_db.list_users():
+            user_settings = user_db.get_user_settings(user_record["id"])
+            if not isinstance(user_settings, dict):
+                continue
+
+            for key in overridable_keys:
+                if key not in user_settings or user_settings[key] is None:
+                    continue
+                entry = keys_payload.setdefault(key, {"count": 0, "users": []})
+                entry["users"].append({
+                    "userId": user_record["id"],
+                    "username": user_record["username"],
+                    "value": user_settings[key],
+                })
+
+        for summary in keys_payload.values():
+            summary["count"] = len(summary["users"])
+
+        return jsonify({"tab": tab_name, "keys": keys_payload})
+
+    @app.route("/api/admin/users/<int:user_id>/effective-settings", methods=["GET"])
+    @require_admin
+    def admin_get_effective_settings(user_id):
+        user = user_db.get_user(user_id=user_id)
+        if not user:
+            return jsonify({"error": "User not found"}), 404
+
+        from shelfmark.core.config import config as app_config
+        from shelfmark.core.settings_registry import is_value_from_env
+
+        field_map = _get_settings_registry().get_user_overridable_fields()
+        user_settings = user_db.get_user_settings(user_id)
+        tab_config_cache: dict[str, dict[str, Any]] = {}
+        effective: dict[str, dict[str, Any]] = {}
+
+        for key, (field, tab_name) in sorted(field_map.items()):
+            value = app_config.get(key, field.default, user_id=user_id)
+            source = "default"
+
+            if field.env_supported and is_value_from_env(field):
+                source = "env_var"
+            elif key in user_settings and user_settings[key] is not None:
+                source = "user_override"
+                value = user_settings[key]
+            else:
+                tab_config = tab_config_cache.setdefault(tab_name, load_config_file(tab_name))
+                if key in tab_config:
+                    source = "global_config"
+
+            effective[key] = {"value": value, "source": source}
+
+        return jsonify(effective)

shelfmark/core/auth_modes.py

@@ -0,0 +1,150 @@
+"""Authentication mode, auth-source normalization, and admin access policy helpers."""
+
+import os
+from typing import Any, Mapping
+
+AUTH_SOURCE_BUILTIN = "builtin"
+AUTH_SOURCE_OIDC = "oidc"
+AUTH_SOURCE_PROXY = "proxy"
+AUTH_SOURCE_CWA = "cwa"
+AUTH_SOURCES = (
+    AUTH_SOURCE_BUILTIN,
+    AUTH_SOURCE_OIDC,
+    AUTH_SOURCE_PROXY,
+    AUTH_SOURCE_CWA,
+)
+AUTH_SOURCE_SET = frozenset(AUTH_SOURCES)
+_ALWAYS_ADMIN_SETTINGS_TABS = frozenset({"security", "users"})
+
+
+def has_local_password_admin(user_db: Any | None = None) -> bool:
+    """Return True when at least one local admin with a password exists."""
+    try:
+        db = user_db
+        if db is None:
+            from shelfmark.core.user_db import UserDB
+
+            config_root = os.environ.get("CONFIG_DIR", "/config")
+            db = UserDB(os.path.join(config_root, "users.db"))
+            db.initialize()
+
+        return db.has_admin_with_password()
+    except Exception:
+        return False
+
+
+def normalize_auth_source(
+    source: Any,
+    oidc_subject: Any = None,
+) -> str:
+    """Resolve a stable auth source value from persisted fields."""
+    normalized = str(source or "").strip().lower()
+    if normalized in AUTH_SOURCE_SET:
+        return normalized
+    if oidc_subject:
+        return AUTH_SOURCE_OIDC
+    return AUTH_SOURCE_BUILTIN
+
+
+def determine_auth_mode(
+    security_config: Mapping[str, Any],
+    cwa_db_path: Any | None,
+    *,
+    has_local_admin: bool = True,
+) -> str:
+    """Determine active auth mode from security config and runtime prerequisites."""
+    auth_mode = security_config.get("AUTH_METHOD", "none")
+
+    if auth_mode == AUTH_SOURCE_CWA and cwa_db_path:
+        return AUTH_SOURCE_CWA
+
+    if auth_mode == AUTH_SOURCE_BUILTIN and has_local_admin:
+        return AUTH_SOURCE_BUILTIN
+
+    if auth_mode == AUTH_SOURCE_PROXY and security_config.get("PROXY_AUTH_USER_HEADER"):
+        return AUTH_SOURCE_PROXY
+
+    if (
+        auth_mode == AUTH_SOURCE_OIDC
+        and has_local_admin
+        and security_config.get("OIDC_DISCOVERY_URL")
+        and security_config.get("OIDC_CLIENT_ID")
+    ):
+        return AUTH_SOURCE_OIDC
+
+    return "none"
+
+
+def load_active_auth_mode(
+    cwa_db_path: Any | None,
+    *,
+    user_db: Any | None = None,
+) -> str:
+    """Resolve active auth mode using current security config and runtime prerequisites."""
+    try:
+        from shelfmark.core.settings_registry import load_config_file
+
+        security_config = load_config_file("security")
+        return determine_auth_mode(
+            security_config,
+            cwa_db_path,
+            has_local_admin=has_local_password_admin(user_db),
+        )
+    except Exception:
+        return "none"
+
+
+def is_user_active_for_auth_mode(user: Mapping[str, Any], auth_mode: str) -> bool:
+    """Return whether a user can authenticate under the current auth mode."""
+    source = normalize_auth_source(user.get("auth_source"), user.get("oidc_subject"))
+    if source == AUTH_SOURCE_BUILTIN:
+        return auth_mode in (AUTH_SOURCE_BUILTIN, AUTH_SOURCE_OIDC)
+    return source == auth_mode
+
+
+def is_settings_or_onboarding_path(path: str) -> bool:
+    """Return True when request path targets protected admin settings routes."""
+    return path.startswith("/api/settings") or path.startswith("/api/onboarding")
+
+
+def get_settings_tab_from_path(path: str) -> str | None:
+    """Extract tab name from /api/settings/<tab>[...] paths."""
+    if not path.startswith("/api/settings/"):
+        return None
+
+    suffix = path[len("/api/settings/"):]
+    if not suffix:
+        return None
+
+    return suffix.split("/", 1)[0] or None
+
+
+def should_restrict_settings_to_admin(
+    _users_config: Mapping[str, Any],
+) -> bool:
+    """Settings/onboarding is always admin-only."""
+    return True
+
+
+def requires_admin_for_settings_access(
+    path: str,
+    users_config: Mapping[str, Any],
+) -> bool:
+    """Return whether this settings/onboarding request requires admin privileges."""
+    tab_name = get_settings_tab_from_path(path)
+    if tab_name in _ALWAYS_ADMIN_SETTINGS_TABS:
+        return True
+
+    return should_restrict_settings_to_admin(users_config)
+
+
+def get_auth_check_admin_status(
+    _auth_mode: str,
+    _users_config: Mapping[str, Any],
+    session_data: Mapping[str, Any],
+) -> bool:
+    """Resolve /api/auth/check `is_admin` as the session's real admin role."""
+    if "user_id" not in session_data:
+        return False
+
+    return bool(session_data.get("is_admin", False))

shelfmark/core/cache.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from functools import wraps
 from typing import Any, Callable, Dict, Optional, TypeVar
 
-from cwa_book_downloader.core.logger import setup_logger
+from shelfmark.core.logger import setup_logger
 
 logger = setup_logger(__name__)
 
@@ -24,24 +24,13 @@ class CacheService:
     """Thread-safe in-memory cache with TTL support."""
 
     def __init__(self, max_size: int = 1000):
-        """Initialize cache service.
-
-        Args:
-            max_size: Maximum number of entries before oldest are evicted.
-        """
+        """Initialize cache with max_size entries before eviction."""
         self._cache: Dict[str, CacheEntry] = {}
         self._lock = threading.Lock()
         self._max_size = max_size
 
     def get(self, key: str) -> Optional[Any]:
-        """Get cached value if not expired.
-
-        Args:
-            key: Cache key to retrieve.
-
-        Returns:
-            Cached value or None if not found/expired.
-        """
+        """Get cached value if not expired."""
         with self._lock:
             entry = self._cache.get(key)
             if entry is None:
@@ -54,13 +43,7 @@ class CacheService:
             return entry.value
 
     def set(self, key: str, value: Any, ttl: int) -> None:
-        """Cache value with TTL.
-
-        Args:
-            key: Cache key.
-            value: Value to cache.
-            ttl: Time to live in seconds.
-        """
+        """Cache value with TTL in seconds."""
         with self._lock:
             # Evict oldest entries if at capacity
             if len(self._cache) >= self._max_size:
@@ -72,31 +55,28 @@ class CacheService:
             )
 
     def invalidate(self, key: str) -> bool:
-        """Remove specific cache entry.
-
-        Args:
-            key: Cache key to remove.
-
-        Returns:
-            True if entry was removed, False if not found.
-        """
+        """Remove specific cache entry. Returns True if found."""
         with self._lock:
             if key in self._cache:
                 del self._cache[key]
                 return True
             return False
 
+    def invalidate_prefix(self, prefix: str) -> int:
+        """Remove all cache entries whose keys start with prefix."""
+        with self._lock:
+            matching_keys = [key for key in self._cache if key.startswith(prefix)]
+            for key in matching_keys:
+                del self._cache[key]
+            return len(matching_keys)
+
     def clear(self) -> None:
         """Clear all cache entries."""
         with self._lock:
             self._cache.clear()
 
     def cleanup_expired(self) -> int:
-        """Remove all expired entries.
-
-        Returns:
-            Number of entries removed.
-        """
+        """Remove all expired entries. Returns count removed."""
         with self._lock:
             now = time.time()
             expired_keys = [
@@ -108,10 +88,7 @@ class CacheService:
             return len(expired_keys)
 
     def _evict_oldest(self) -> None:
-        """Evict oldest entries (by expiration time) to make room.
-
-        Called with lock held.
-        """
+        """Evict ~10% of oldest entries. Called with lock held."""
         if not self._cache:
             return
 
@@ -126,11 +103,7 @@ class CacheService:
             del self._cache[key]
 
     def stats(self) -> Dict[str, int]:
-        """Get cache statistics.
-
-        Returns:
-            Dict with size and max_size.
-        """
+        """Get cache statistics (size, max_size)."""
         with self._lock:
             return {
                 "size": len(self._cache),
@@ -148,15 +121,7 @@ def get_metadata_cache() -> CacheService:
 
 
 def cache_key(*args, **kwargs) -> str:
-    """Generate cache key from arguments.
-
-    Args:
-        *args: Positional arguments to include in key.
-        **kwargs: Keyword arguments to include in key.
-
-    Returns:
-        String cache key.
-    """
+    """Generate cache key from arguments."""
     parts = [str(arg) for arg in args]
     parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
     return ":".join(parts)
@@ -168,23 +133,12 @@ def cacheable(
     ttl_default: int = 300,
     key_prefix: str = ""
 ):
-    """Decorator for caching function results.
-
-    Args:
-        ttl: Static time to live in seconds (use this OR ttl_key, not both).
-        ttl_key: Config key to read TTL from (e.g., "METADATA_CACHE_SEARCH_TTL").
-        ttl_default: Default TTL if ttl_key not found in config.
-        key_prefix: Optional prefix for cache keys.
-
-    Examples:
-        @cacheable(ttl=300, key_prefix="hardcover:search")  # Static TTL
-        @cacheable(ttl_key="METADATA_CACHE_SEARCH_TTL", key_prefix="hardcover:search")  # Dynamic TTL
-    """
+    """Decorator for caching function results. Use ttl (static) or ttl_key (from config)."""
     def decorator(func: Callable[..., T]) -> Callable[..., T]:
         @wraps(func)
         def wrapper(*args, **kwargs) -> T:
             # Check if metadata caching is enabled
-            from cwa_book_downloader.core.config import config
+            from shelfmark.core.config import config
 
             if not config.get("METADATA_CACHE_ENABLED", True):
                 # Caching disabled, execute function directly
@@ -211,11 +165,9 @@ def cacheable(
             # Check cache
             cached = _metadata_cache.get(key)
             if cached is not None:
-                logger.debug(f"Cache hit: {key}")
                 return cached
 
             # Execute function and cache result
-            logger.debug(f"Cache miss: {key}")
             result = func(*args, **kwargs)
 
             # Only cache non-None results

shelfmark/core/config.py

@@ -1,18 +1,22 @@
 """Configuration singleton with ENV > config file > default resolution."""
 
+import os
+import sqlite3
+import time
 from threading import Lock
 from typing import Any, Dict, Optional
 
 # Import lazily to avoid circular imports
 _registry_module = None
 _env_module = None
+_user_db_module = None
 
 
 def _get_registry():
     """Lazy import of settings registry to avoid circular imports."""
     global _registry_module
     if _registry_module is None:
-        from cwa_book_downloader.core import settings_registry
+        from shelfmark.core import settings_registry
         _registry_module = settings_registry
     return _registry_module
 
@@ -21,11 +25,20 @@ def _get_env():
     """Lazy import of env module for fallback values."""
     global _env_module
     if _env_module is None:
-        from cwa_book_downloader.config import env
+        from shelfmark.config import env
         _env_module = env
     return _env_module
 
 
+def _get_user_db_module():
+    """Lazy import of user DB module to avoid optional dependency loops."""
+    global _user_db_module
+    if _user_db_module is None:
+        from shelfmark.core.user_db import UserDB
+        _user_db_module = UserDB
+    return _user_db_module
+
+
 class Config:
     """
     Dynamic configuration singleton that provides live settings access.
@@ -36,7 +49,6 @@ class Config:
 
     _instance: Optional['Config'] = None
     _lock = Lock()
-
     def __new__(cls) -> 'Config':
         if cls._instance is None:
             with cls._lock:
@@ -51,8 +63,13 @@ class Config:
         self._cache: Dict[str, Any] = {}
         self._field_map: Dict[str, tuple] = {}  # key -> (field, tab_name)
         self._cache_lock = Lock()
+        self._user_settings_cache: Dict[int, Dict[str, Any]] = {}
+        self._user_settings_cache_lock = Lock()
+        self._user_db = None
+        self._user_db_load_attempted = False
         self._initialized = True
         self._loaded = False
+        self._last_refresh_time: float = 0.0
 
     def _ensure_loaded(self) -> None:
         """Ensure settings are loaded from the registry."""
@@ -65,11 +82,13 @@ class Config:
 
     def _load_settings(self) -> None:
         """Load all settings from the registry."""
-        # Ensure all plugin settings are registered before loading
-        # This handles cases where config is accessed before plugins are imported
+        # Ensure all settings modules are imported before loading
+        # This handles cases where config is accessed before settings are registered
         try:
-            import cwa_book_downloader.release_sources  # noqa: F401
-            import cwa_book_downloader.metadata_providers  # noqa: F401
+            import shelfmark.config.settings  # noqa: F401 - main app settings
+            import shelfmark.config.notifications_settings  # noqa: F401 - notifications settings
+            import shelfmark.release_sources  # noqa: F401 - plugin settings
+            import shelfmark.metadata_providers  # noqa: F401 - plugin settings
         except ImportError:
             pass
 
@@ -100,29 +119,105 @@ class Config:
 
         self._loaded = True
 
-    def refresh(self) -> None:
+    def refresh(self, force: bool = False) -> None:
         """
         Refresh all cached settings from config files.
 
         Call this after settings are updated via the UI to ensure
         the config singleton reflects the new values.
+
+        Multiple calls within a short window (50 ms) are coalesced to
+        avoid redundant disk I/O when several helpers each call refresh()
+        during the same request.  Pass ``force=True`` to bypass the guard
+        (e.g. after a settings write).
         """
+        now = time.monotonic()
+        if not force and (now - self._last_refresh_time) < 0.05:
+            return
+
         with self._cache_lock:
             self._loaded = False
             self._load_settings()
+        with self._user_settings_cache_lock:
+            self._user_settings_cache.clear()
+        self._user_db = None
+        self._user_db_load_attempted = False
+        self._last_refresh_time = time.monotonic()
 
-    def get(self, key: str, default: Any = None) -> Any:
+    def _get_user_db(self):
+        """Get or initialize a UserDB handle if available."""
+        if self._user_db is not None:
+            return self._user_db
+        if self._user_db_load_attempted:
+            return None
+
+        self._user_db_load_attempted = True
+        try:
+            user_db_cls = _get_user_db_module()
+            db_path = os.path.join(os.environ.get("CONFIG_DIR", "/config"), "users.db")
+            user_db = user_db_cls(db_path)
+            user_db.initialize()
+            self._user_db = user_db
+            return self._user_db
+        except Exception:
+            # Multi-user support is optional; fall back to global config when unavailable.
+            return None
+
+    def _get_user_settings(self, user_id: int) -> Dict[str, Any]:
+        """Get cached per-user settings from user DB."""
+        with self._user_settings_cache_lock:
+            if user_id in self._user_settings_cache:
+                return self._user_settings_cache[user_id]
+
+        user_db = self._get_user_db()
+        if user_db is None:
+            return {}
+
+        try:
+            settings = user_db.get_user_settings(user_id)
+        except (sqlite3.OperationalError, OSError, ValueError, TypeError):
+            return {}
+
+        if not isinstance(settings, dict):
+            settings = {}
+
+        with self._user_settings_cache_lock:
+            self._user_settings_cache[user_id] = settings
+        return settings
+
+    def _get_user_override(self, user_id: int, key: str) -> Any:
+        """Get a user override for a specific key."""
+        user_settings = self._get_user_settings(user_id)
+        return user_settings.get(key)
+
+    def get(self, key: str, default: Any = None, user_id: Optional[int] = None) -> Any:
         """
         Get a setting value by key.
 
         Args:
             key: The setting key (e.g., 'MAX_RETRY')
             default: Default value if setting not found
+            user_id: Optional DB user ID for per-user setting overrides
 
         Returns:
             The setting value, or default if not found
         """
         self._ensure_loaded()
+
+        if key in self._field_map:
+            field, _ = self._field_map[key]
+            registry = _get_registry()
+
+            # Deployment-level ENV values always win.
+            if field.env_supported and registry.is_value_from_env(field):
+                return self._cache.get(key, default)
+
+            # User overrides are only available for explicitly overridable fields.
+            if user_id is not None and getattr(field, "user_overridable", False):
+                user_value = self._get_user_override(user_id, key)
+                if user_value is not None:
+                    return user_value
+
         return self._cache.get(key, default)
 
     def __getattr__(self, name: str) -> Any:

shelfmark/core/cwa_user_sync.py

@@ -0,0 +1,94 @@
+"""Helpers for provisioning and syncing Calibre-Web users into users.db."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from shelfmark.core.auth_modes import AUTH_SOURCE_CWA, normalize_auth_source
+from shelfmark.core.external_user_linking import upsert_external_user
+from shelfmark.core.user_db import UserDB
+
+_CWA_ALIAS_SUFFIX = "__cwa"
+
+
+def _normalize_email(value: Any) -> str | None:
+    if value is None:
+        return None
+    email = str(value).strip()
+    return email or None
+
+
+def upsert_cwa_user(
+    user_db: UserDB,
+    cwa_username: str,
+    cwa_email: str | None,
+    role: str,
+    context: str | None = None,
+) -> tuple[dict[str, Any], str]:
+    """Create/update a CWA-backed user with collision-safe matching."""
+    normalized_email = _normalize_email(cwa_email)
+    collision_strategy = "alias" if normalized_email else "takeover"
+    user, action = upsert_external_user(
+        user_db,
+        auth_source="cwa",
+        username=cwa_username,
+        email=normalized_email,
+        role=role,
+        allow_email_link=True,
+        collision_strategy=collision_strategy,
+        alias_suffix=_CWA_ALIAS_SUFFIX,
+        context=context,
+    )
+    if user is None:
+        raise RuntimeError("Unexpected CWA user sync result: no user returned")
+    return user, action
+
+
+def sync_cwa_users_from_rows(
+    user_db: UserDB,
+    rows: Iterable[tuple[Any, Any, Any]],
+) -> dict[str, int]:
+    """Sync CWA users from raw `(name, role_flags, email)` rows."""
+    created = 0
+    updated = 0
+    active_cwa_user_ids: set[int] = set()
+    for username, role_flags, email in rows:
+        normalized_username = str(username or "").strip()
+        if not normalized_username:
+            continue
+
+        role = "admin" if (int(role_flags or 0) & 1) == 1 else "user"
+        user, action = upsert_cwa_user(
+            user_db,
+            cwa_username=normalized_username,
+            cwa_email=_normalize_email(email),
+            role=role,
+            context="cwa_manual_sync",
+        )
+        active_cwa_user_ids.add(int(user["id"]))
+        if action == "created":
+            created += 1
+        else:
+            updated += 1
+
+    deleted = 0
+    for existing_user in user_db.list_users():
+        if normalize_auth_source(
+            existing_user.get("auth_source"),
+            existing_user.get("oidc_subject"),
+        ) != AUTH_SOURCE_CWA:
+            continue
+
+        existing_id = int(existing_user.get("id") or 0)
+        if existing_id in active_cwa_user_ids:
+            continue
+
+        user_db.delete_user(existing_id)
+        deleted += 1
+
+    return {
+        "created": created,
+        "updated": updated,
+        "deleted": deleted,
+        "total": created + updated,
+    }

shelfmark/core/download_history_service.py

@@ -0,0 +1,306 @@
+"""Persistence helpers for canonical download activity rows."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from typing import Any
+
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.models import TERMINAL_QUEUE_STATUSES
+from shelfmark.core.request_helpers import normalize_optional_positive_int, normalize_optional_text, now_utc_iso
+
+logger = setup_logger(__name__)
+
+
+VALID_TERMINAL_STATUSES = frozenset(s.value for s in TERMINAL_QUEUE_STATUSES)
+ACTIVE_DOWNLOAD_STATUS = "active"
+VALID_ORIGINS = frozenset({"direct", "requested"})
+
+
+def _normalize_task_id(task_id: Any) -> str:
+    normalized = normalize_optional_text(task_id)
+    if normalized is None:
+        raise ValueError("task_id must be a non-empty string")
+    return normalized
+
+
+def _normalize_origin(origin: Any) -> str:
+    normalized = normalize_optional_text(origin)
+    if normalized is None:
+        return "direct"
+    lowered = normalized.lower()
+    if lowered not in VALID_ORIGINS:
+        raise ValueError("origin must be one of: direct, requested")
+    return lowered
+
+
+def _normalize_final_status(final_status: Any) -> str:
+    normalized = normalize_optional_text(final_status)
+    if normalized is None:
+        raise ValueError("final_status must be a non-empty string")
+    lowered = normalized.lower()
+    if lowered not in VALID_TERMINAL_STATUSES:
+        raise ValueError("final_status must be one of: complete, error, cancelled")
+    return lowered
+
+
+def _normalize_limit(value: Any, *, default: int, minimum: int, maximum: int) -> int:
+    if value is None:
+        return default
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("limit must be an integer") from exc
+    if parsed < minimum:
+        return minimum
+    if parsed > maximum:
+        return maximum
+    return parsed
+
+
+class DownloadHistoryService:
+    """Service for persisted canonical download activity rows."""
+
+    def __init__(self, db_path: str):
+        self._db_path = db_path
+        self._lock = threading.Lock()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    @staticmethod
+    def _row_to_dict(row: sqlite3.Row | None) -> dict[str, Any] | None:
+        return dict(row) if row is not None else None
+
+    @staticmethod
+    def _to_item_key(task_id: str) -> str:
+        return f"download:{task_id}"
+
+    @staticmethod
+    def _resolve_existing_download_path(value: Any) -> str | None:
+        normalized = normalize_optional_text(value)
+        if normalized is None:
+            return None
+        return normalized if os.path.exists(normalized) else None
+
+    @staticmethod
+    def to_download_payload(row: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": row.get("task_id"),
+            "title": row.get("title"),
+            "author": row.get("author"),
+            "format": row.get("format"),
+            "size": row.get("size"),
+            "preview": row.get("preview"),
+            "content_type": row.get("content_type"),
+            "source": row.get("source"),
+            "source_display_name": row.get("source_display_name"),
+            "status_message": row.get("status_message"),
+            "download_path": DownloadHistoryService._resolve_existing_download_path(row.get("download_path")),
+            "added_time": DownloadHistoryService._iso_to_epoch(row.get("queued_at")),
+            "user_id": row.get("user_id"),
+            "username": row.get("username"),
+            "request_id": row.get("request_id"),
+        }
+
+    @staticmethod
+    def _iso_to_epoch(value: Any) -> float | None:
+        if not isinstance(value, str) or not value.strip():
+            return None
+        normalized = value.strip().replace("Z", "+00:00")
+        try:
+            parsed = datetime.fromisoformat(normalized)
+        except ValueError:
+            return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.timestamp()
+
+    @classmethod
+    def to_history_row(cls, row: dict[str, Any], *, dismissed_at: str) -> dict[str, Any]:
+        task_id = str(row.get("task_id") or "").strip()
+        item_key = cls._to_item_key(task_id)
+        download_payload = cls.to_download_payload(row)
+        # Clear stale progress messages for non-error terminal states.
+        if row.get("final_status") in ("complete", "cancelled"):
+            download_payload["status_message"] = None
+        return {
+            "id": item_key,
+            "user_id": row.get("user_id"),
+            "item_type": "download",
+            "item_key": item_key,
+            "dismissed_at": dismissed_at,
+            "snapshot": {
+                "kind": "download",
+                "download": download_payload,
+            },
+            "origin": row.get("origin"),
+            "final_status": row.get("final_status"),
+            "terminal_at": row.get("terminal_at"),
+            "request_id": row.get("request_id"),
+            "source_id": task_id or None,
+        }
+
+    def record_download(
+        self,
+        *,
+        task_id: str,
+        user_id: int | None,
+        username: str | None,
+        request_id: int | None,
+        source: str,
+        source_display_name: str | None,
+        title: str,
+        author: str | None,
+        format: str | None,
+        size: str | None,
+        preview: str | None,
+        content_type: str | None,
+        origin: str,
+    ) -> None:
+        """Record a download at queue time with final_status='active'.
+
+        On first queue: inserts a new row.
+        On retry (row already exists): resets the row back to 'active'
+        so the normal finalize path works when the retry completes.
+        """
+        normalized_task_id = _normalize_task_id(task_id)
+        normalized_user_id = normalize_optional_positive_int(user_id, "user_id")
+        normalized_request_id = normalize_optional_positive_int(request_id, "request_id")
+        normalized_source = normalize_optional_text(source)
+        if normalized_source is None:
+            raise ValueError("source must be a non-empty string")
+        normalized_title = normalize_optional_text(title)
+        if normalized_title is None:
+            raise ValueError("title must be a non-empty string")
+        normalized_origin = _normalize_origin(origin)
+        recorded_at = now_utc_iso()
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                INSERT INTO download_history (
+                    task_id, user_id, username, request_id,
+                    source, source_display_name,
+                    title, author, format, size, preview, content_type,
+                    origin, final_status,
+                    status_message, download_path,
+                    queued_at, terminal_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, ?)
+                ON CONFLICT(task_id) DO UPDATE SET
+                    final_status = 'active',
+                    status_message = NULL,
+                    download_path = NULL,
+                    terminal_at = ?
+                """,
+                    (
+                        normalized_task_id,
+                        normalized_user_id,
+                        normalize_optional_text(username),
+                        normalized_request_id,
+                        normalized_source,
+                        normalize_optional_text(source_display_name),
+                        normalized_title,
+                        normalize_optional_text(author),
+                        normalize_optional_text(format),
+                        normalize_optional_text(size),
+                        normalize_optional_text(preview),
+                        normalize_optional_text(content_type),
+                        normalized_origin,
+                        recorded_at,
+                        recorded_at,
+                        recorded_at,
+                    ),
+                )
+                conn.commit()
+            finally:
+                conn.close()
+
+    def finalize_download(
+        self,
+        *,
+        task_id: str,
+        final_status: str,
+        status_message: str | None = None,
+        download_path: str | None = None,
+    ) -> None:
+        """Update an existing download row to its terminal state."""
+        normalized_task_id = _normalize_task_id(task_id)
+        normalized_final_status = _normalize_final_status(final_status)
+        normalized_status_message = normalize_optional_text(status_message)
+        normalized_download_path = normalize_optional_text(download_path)
+        effective_terminal_at = now_utc_iso()
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cursor = conn.execute(
+                    """
+                    UPDATE download_history
+                    SET final_status = ?,
+                        status_message = ?,
+                        download_path = ?,
+                        terminal_at = ?
+                    WHERE task_id = ? AND final_status = 'active'
+                    """,
+                    (
+                        normalized_final_status,
+                        normalized_status_message,
+                        normalized_download_path,
+                        effective_terminal_at,
+                        normalized_task_id,
+                    ),
+                )
+                rowcount = int(cursor.rowcount) if cursor.rowcount is not None else 0
+                if rowcount < 1:
+                    logger.warning(
+                        "finalize_download: no active row found for task_id=%s (may have been missed at queue time)",
+                        normalized_task_id,
+                    )
+                conn.commit()
+            finally:
+                conn.close()
+
+    def get_by_task_id(self, task_id: str) -> dict[str, Any] | None:
+        normalized_task_id = _normalize_task_id(task_id)
+        conn = self._connect()
+        try:
+            row = conn.execute(
+                "SELECT * FROM download_history WHERE task_id = ?",
+                (normalized_task_id,),
+            ).fetchone()
+            return self._row_to_dict(row)
+        finally:
+            conn.close()
+
+    def list_recent(
+        self,
+        *,
+        user_id: int | None,
+        limit: int = 200,
+    ) -> list[dict[str, Any]]:
+        normalized_user_id = normalize_optional_positive_int(user_id, "user_id")
+        normalized_limit = _normalize_limit(limit, default=200, minimum=1, maximum=1000)
+        query = "SELECT * FROM download_history"
+        params: list[Any] = []
+        if normalized_user_id is not None:
+            query += " WHERE user_id = ?"
+            params.append(normalized_user_id)
+        query += " ORDER BY terminal_at DESC, id DESC LIMIT ?"
+        params.append(normalized_limit)
+
+        conn = self._connect()
+        try:
+            rows = conn.execute(query, params).fetchall()
+            return [dict(row) for row in rows]
+        finally:
+            conn.close()

shelfmark/core/external_user_linking.py

@@ -0,0 +1,283 @@
+"""Shared external identity matching and provisioning helpers."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from shelfmark.core.auth_modes import normalize_auth_source
+from shelfmark.core.logger import setup_logger
+from shelfmark.core.user_db import UserDB
+
+UNSET = object()
+
+CollisionStrategy = Literal["takeover", "suffix", "alias"]
+MatchReason = Literal[
+    "subject_match",
+    "existing_source_username_match",
+    "unique_email_match",
+]
+
+logger = setup_logger(__name__)
+
+
+def _normalize_username(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _normalize_email(value: Any) -> str | None:
+    if value is None:
+        return None
+    email = str(value).strip()
+    return email or None
+
+
+def _normalize_display_name(value: Any) -> str | None:
+    if value is None:
+        return None
+    name = str(value).strip()
+    return name or None
+
+
+def _email_key(value: str | None) -> str:
+    return (value or "").strip().lower()
+
+
+def _normalize_role(value: Any) -> str:
+    return "admin" if str(value or "").strip().lower() == "admin" else "user"
+
+
+def _get_by_subject(user_db: UserDB, subject_field: str | None, subject: str | None) -> dict[str, Any] | None:
+    if not subject_field or not subject:
+        return None
+    if subject_field == "oidc_subject":
+        return user_db.get_user(oidc_subject=subject)
+    return None
+
+
+def find_unique_user_by_email(user_db: UserDB, email: str | None) -> dict[str, Any] | None:
+    key = _email_key(_normalize_email(email))
+    if not key:
+        return None
+
+    matches = [u for u in user_db.list_users() if _email_key(u.get("email")) == key]
+    return matches[0] if len(matches) == 1 else None
+
+
+def find_external_user_match(
+    user_db: UserDB,
+    *,
+    auth_source: str,
+    username: str,
+    email: str | None,
+    subject_field: str | None = None,
+    subject: str | None = None,
+    allow_email_link: bool = False,
+) -> tuple[dict[str, Any] | None, MatchReason | None]:
+    """Find an existing local user that should be linked to an external identity."""
+    normalized_username = _normalize_username(username)
+    normalized_email = _normalize_email(email)
+
+    by_subject = _get_by_subject(user_db, subject_field, subject)
+    if by_subject is not None:
+        return by_subject, "subject_match"
+
+    by_username = user_db.get_user(username=normalized_username)
+    if by_username and normalize_auth_source(
+        by_username.get("auth_source"),
+        by_username.get("oidc_subject"),
+    ) == auth_source:
+        return by_username, "existing_source_username_match"
+
+    if allow_email_link:
+        return find_unique_user_by_email(user_db, normalized_email), "unique_email_match"
+    return None, None
+
+
+def _build_updates(
+    *,
+    auth_source: str,
+    role: str,
+    sync_role: bool,
+    email: str | None | object,
+    display_name: str | None | object,
+    subject_field: str | None,
+    subject: str | None,
+) -> dict[str, Any]:
+    updates: dict[str, Any] = {"auth_source": auth_source}
+    if sync_role:
+        updates["role"] = _normalize_role(role)
+    if email is not UNSET:
+        updates["email"] = _normalize_email(email)
+    if display_name is not UNSET:
+        updates["display_name"] = _normalize_display_name(display_name)
+    if subject_field == "oidc_subject" and subject:
+        updates["oidc_subject"] = subject
+    return updates
+
+
+def _next_suffix_username(user_db: UserDB, base_username: str) -> str:
+    candidate = base_username
+    suffix = 1
+    while user_db.get_user(username=candidate):
+        candidate = f"{base_username}_{suffix}"
+        suffix += 1
+    return candidate
+
+
+def _find_existing_alias_user(
+    user_db: UserDB,
+    *,
+    auth_source: str,
+    alias_base: str,
+) -> dict[str, Any] | None:
+    pattern = re.compile(rf"^{re.escape(alias_base)}(?:_\d+)?$")
+    candidates = [
+        user for user in user_db.list_users()
+        if pattern.match(str(user.get("username") or ""))
+        and normalize_auth_source(user.get("auth_source"), user.get("oidc_subject")) == auth_source
+    ]
+    if not candidates:
+        return None
+    return sorted(candidates, key=lambda user: int(user.get("id") or 0))[0]
+
+
+def _resolve_create_username(
+    user_db: UserDB,
+    *,
+    auth_source: str,
+    requested_username: str,
+    strategy: CollisionStrategy,
+    alias_suffix: str,
+) -> tuple[str | None, dict[str, Any] | None, str]:
+    existing = user_db.get_user(username=requested_username)
+    if not existing:
+        return requested_username, None, "new_username_available"
+
+    if strategy == "takeover":
+        return None, existing, "username_collision_takeover"
+
+    if strategy == "suffix":
+        return _next_suffix_username(user_db, requested_username), None, "username_collision_suffix"
+
+    alias_base = f"{requested_username}{alias_suffix}"
+    alias_existing = _find_existing_alias_user(
+        user_db,
+        auth_source=auth_source,
+        alias_base=alias_base,
+    )
+    if alias_existing is not None:
+        return None, alias_existing, "reuse_existing_alias"
+    return _next_suffix_username(user_db, alias_base), None, "username_collision_alias"
+
+
+def upsert_external_user(
+    user_db: UserDB,
+    *,
+    auth_source: str,
+    username: str,
+    role: str,
+    email: str | None | object = UNSET,
+    display_name: str | None | object = UNSET,
+    subject_field: str | None = None,
+    subject: str | None = None,
+    allow_email_link: bool = False,
+    sync_role: bool = True,
+    allow_create: bool = True,
+    collision_strategy: CollisionStrategy = "takeover",
+    alias_suffix: str | None = None,
+    context: str | None = None,
+) -> tuple[dict[str, Any] | None, str]:
+    """Create/update a user from an external auth identity.
+
+    Returns `(user, action)` where action is one of:
+    - `"updated"`
+    - `"created"`
+    - `"not_found"` (when `allow_create=False` and no link target exists)
+    """
+    normalized_username = _normalize_username(username)
+    if not normalized_username:
+        raise ValueError("External username is required")
+
+    normalized_email = _normalize_email(email) if email is not UNSET else None
+    normalized_display_name = (
+        _normalize_display_name(display_name) if display_name is not UNSET else None
+    )
+    normalized_role = _normalize_role(role)
+
+    matched, match_reason = find_external_user_match(
+        user_db,
+        auth_source=auth_source,
+        username=normalized_username,
+        email=normalized_email,
+        subject_field=subject_field,
+        subject=subject,
+        allow_email_link=allow_email_link,
+    )
+    updates = _build_updates(
+        auth_source=auth_source,
+        role=normalized_role,
+        sync_role=sync_role,
+        email=normalized_email if email is not UNSET else UNSET,
+        display_name=normalized_display_name if display_name is not UNSET else UNSET,
+        subject_field=subject_field,
+        subject=subject,
+    )
+    if matched is not None:
+        user_db.update_user(matched["id"], **updates)
+        mapped = user_db.get_user(user_id=matched["id"]) or matched
+        logger.info(
+            "External user mapped to existing Shelfmark user "
+            f"(source={auth_source}, context={context or 'unspecified'}, reason={match_reason}, "
+            f"external_username={normalized_username}, shelfmark_user_id={mapped['id']}, "
+            f"shelfmark_username={mapped['username']})"
+        )
+        return mapped, "updated"
+
+    if not allow_create:
+        logger.info(
+            "External user could not be mapped and creation is disabled "
+            f"(source={auth_source}, context={context or 'unspecified'}, "
+            f"external_username={normalized_username})"
+        )
+        return None, "not_found"
+
+    resolved_alias_suffix = alias_suffix or f"__{auth_source}"
+    create_username, takeover_target, create_reason = _resolve_create_username(
+        user_db,
+        auth_source=auth_source,
+        requested_username=normalized_username,
+        strategy=collision_strategy,
+        alias_suffix=resolved_alias_suffix,
+    )
+    if takeover_target is not None:
+        user_db.update_user(takeover_target["id"], **updates)
+        mapped = user_db.get_user(user_id=takeover_target["id"]) or takeover_target
+        logger.info(
+            "External user mapped to existing Shelfmark user "
+            f"(source={auth_source}, context={context or 'unspecified'}, reason={create_reason}, "
+            f"external_username={normalized_username}, shelfmark_user_id={mapped['id']}, "
+            f"shelfmark_username={mapped['username']})"
+        )
+        return mapped, "updated"
+
+    create_kwargs: dict[str, Any] = {
+        "username": create_username,
+        "auth_source": auth_source,
+        "role": normalized_role,
+    }
+    if email is not UNSET:
+        create_kwargs["email"] = normalized_email
+    if display_name is not UNSET:
+        create_kwargs["display_name"] = normalized_display_name
+    if subject_field == "oidc_subject" and subject:
+        create_kwargs["oidc_subject"] = subject
+
+    created = user_db.create_user(**create_kwargs)
+    logger.info(
+        "External user created Shelfmark user "
+        f"(source={auth_source}, context={context or 'unspecified'}, reason={create_reason}, "
+        f"external_username={normalized_username}, shelfmark_user_id={created['id']}, "
+        f"shelfmark_username={created['username']})"
+    )
+    return created, "created"

shelfmark/core/image_cache.py

@@ -10,7 +10,8 @@ from typing import Any, Dict, Optional, Tuple
 
 import requests
 
-from cwa_book_downloader.core.logger import setup_logger
+from shelfmark.core.logger import setup_logger
+from shelfmark.download.network import get_ssl_verify
 
 logger = setup_logger(__name__)
 
@@ -92,10 +93,13 @@ class ImageCacheService:
 
     def _load_index(self) -> None:
         """Load cache index from disk."""
+        if not self.index_path.exists():
+            self._index = {}
+            return
+
         try:
-            if self.index_path.exists():
-                with open(self.index_path, 'r') as f:
-                    self._index = json.load(f)
+            with open(self.index_path, 'r') as f:
+                self._index = json.load(f)
         except (json.JSONDecodeError, IOError):
             self._index = {}
 
@@ -179,9 +183,7 @@ class ImageCacheService:
         """Check if a cache entry is expired."""
         if self.ttl_seconds == 0:
             return False
-
-        cached_at = entry.get('cached_at', 0)
-        return (time.time() - cached_at) > self.ttl_seconds
+        return (time.time() - entry.get('cached_at', 0)) > self.ttl_seconds
 
     def _is_negative_expired(self, entry: Dict[str, Any]) -> bool:
         """Check if a negative cache entry is expired.
@@ -193,12 +195,8 @@ class ImageCacheService:
             return False
 
         cached_at = entry.get('cached_at', 0)
-
-        # Transient failures (timeouts, connection errors) use shorter TTL
-        if entry.get('transient', False):
-            return (time.time() - cached_at) > TRANSIENT_CACHE_TTL
-
-        return (time.time() - cached_at) > NEGATIVE_CACHE_TTL
+        ttl = TRANSIENT_CACHE_TTL if entry.get('transient', False) else NEGATIVE_CACHE_TTL
+        return (time.time() - cached_at) > ttl
 
     def _calculate_total_size(self) -> int:
         """Calculate total size of cached images."""
@@ -255,14 +253,13 @@ class ImageCacheService:
         with self._lock:
             entry = self._index.get(cache_id)
 
+            # Try reloading from disk if not found (handles multiprocess case)
             if not entry:
-                # Try reloading from disk (handles multiprocess case)
                 self._load_index()
                 entry = self._index.get(cache_id)
-
-            if not entry:
-                self._misses += 1
-                return None
+                if not entry:
+                    self._misses += 1
+                    return None
 
             # Check for negative cache (failed fetch)
             if entry.get('negative', False):
@@ -486,6 +483,7 @@ class ImageCacheService:
                 timeout=(5, 10),
                 headers=FETCH_HEADERS,
                 stream=True,
+                verify=get_ssl_verify(url),
             )
             response.raise_for_status()
 
@@ -526,10 +524,8 @@ class ImageCacheService:
             self.put_negative(cache_id, transient=True)
             return None
         except requests.exceptions.HTTPError as e:
-            if e.response is not None and e.response.status_code == 404:
-                self.put_negative(cache_id)
-            else:
-                self.put_negative(cache_id, transient=True)
+            is_404 = e.response is not None and e.response.status_code == 404
+            self.put_negative(cache_id, transient=not is_404)
             return None
         except Exception:
             return None
@@ -550,8 +546,8 @@ def get_image_cache() -> ImageCacheService:
     if _instance is None:
         with _instance_lock:
             if _instance is None:
-                from cwa_book_downloader.core.config import config
-                from cwa_book_downloader.config.env import CONFIG_DIR
+                from shelfmark.core.config import config
+                from shelfmark.config.env import CONFIG_DIR
 
                 cache_dir = CONFIG_DIR / "covers"
                 max_size_mb = config.get("COVERS_CACHE_MAX_SIZE_MB", 500)
@@ -563,7 +559,7 @@ def get_image_cache() -> ImageCacheService:
                     max_size_mb=max_size_mb,
                     ttl_seconds=ttl_seconds,
                 )
-                logger.info(f"Initialized image cache: {cache_dir} (max {max_size_mb}MB, TTL {ttl_days} days)")
+                logger.debug(f"Initialized image cache: {cache_dir} (max {max_size_mb}MB, TTL {ttl_days} days)")
 
     return _instance
 

shelfmark/core/logger.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from logging.handlers import RotatingFileHandler
 from typing import Any
 
-from cwa_book_downloader.config.env import LOG_FILE, ENABLE_LOGGING, LOG_LEVEL
+from shelfmark.config.env import LOG_FILE, ENABLE_LOGGING, LOG_LEVEL
 
 
 class CustomLogger(logging.Logger):
@@ -39,12 +39,38 @@ class CustomLogger(logging.Logger):
         self.debug(msg, *args, exc_info=has_exception, **kwargs)
 
     def log_resource_usage(self):
-        import psutil
-        memory = psutil.virtual_memory()
-        available_mb = memory.available / (1024 * 1024)
-        memory_used_mb = memory.used / (1024 * 1024)
-        cpu_percent = psutil.cpu_percent()
-        self.debug(f"Container Memory: Available={available_mb:.2f} MB, Used={memory_used_mb:.2f} MB, CPU: {cpu_percent:.2f}%")
+        # Best-effort only; this should never raise during exception logging.
+        try:
+            import psutil
+
+            # Sum RSS of all processes for actual app memory (container-friendly),
+            # but fall back gracefully on platforms that restrict process enumeration.
+            app_memory_mb = 0.0
+            try:
+                for proc in psutil.process_iter(['memory_info']):
+                    try:
+                        mem = proc.info.get('memory_info')
+                        if mem:
+                            app_memory_mb += mem.rss / (1024 * 1024)
+                    except (psutil.NoSuchProcess, psutil.AccessDenied, KeyError, AttributeError):
+                        continue
+            except (PermissionError, psutil.AccessDenied, OSError):
+                try:
+                    app_memory_mb = psutil.Process().memory_info().rss / (1024 * 1024)
+                except Exception:
+                    app_memory_mb = 0.0
+
+            memory = psutil.virtual_memory()
+            system_used_mb = memory.used / (1024 * 1024)
+            available_mb = memory.available / (1024 * 1024)
+            cpu_percent = psutil.cpu_percent()
+            self.debug(
+                f"Container Memory: App={app_memory_mb:.2f} MB, System={system_used_mb:.2f} MB, "
+                f"Available={available_mb:.2f} MB, CPU: {cpu_percent:.2f}%"
+            )
+        except Exception:
+            # Avoid breaking the original log call if psutil is missing or restricted.
+            return
 
 
 def setup_logger(name: str, log_file: Path = LOG_FILE) -> CustomLogger:
@@ -62,17 +88,7 @@ def setup_logger(name: str, log_file: Path = LOG_FILE) -> CustomLogger:
 
     # Create logger as CustomLogger instance
     logger = CustomLogger(name)
-    log_level = logging.INFO
-    if LOG_LEVEL == "DEBUG":
-        log_level = logging.DEBUG
-    elif LOG_LEVEL == "INFO":
-        log_level = logging.INFO
-    elif LOG_LEVEL == "WARNING":
-        log_level = logging.WARNING
-    elif LOG_LEVEL == "ERROR":
-        log_level = logging.ERROR
-    elif LOG_LEVEL == "CRITICAL":
-        log_level = logging.CRITICAL
+    log_level = getattr(logging, LOG_LEVEL, logging.INFO)
     logger.setLevel(log_level)
 
     formatter = logging.Formatter(

shelfmark/core/mirrors.py

@@ -0,0 +1,256 @@
+"""Centralized mirror configuration for all download sources."""
+
+from typing import List
+
+from shelfmark.core.utils import normalize_http_url
+
+# Lazy import to avoid circular imports
+_config_module = None
+
+
+def _get_config():
+    """Lazy import of config module to avoid circular imports."""
+    global _config_module
+    if _config_module is None:
+        from shelfmark.core.config import config
+        _config_module = config
+    return _config_module
+
+
+# Default mirror lists (hardcoded fallbacks)
+DEFAULT_AA_MIRRORS = [
+    "https://annas-archive.gl",
+    "https://annas-archive.pk",
+    "https://annas-archive.vg",
+    "https://annas-archive.gd",
+]
+
+DEFAULT_LIBGEN_MIRRORS = [
+    "https://libgen.gl",
+    "https://libgen.li",
+    "https://libgen.bz",
+    "https://libgen.la",
+    "https://libgen.vg",
+]
+
+DEFAULT_ZLIB_MIRRORS = [
+    "https://z-lib.fm",
+    "https://z-lib.gs",
+    "https://z-lib.id",
+    "https://z-library.sk",
+    "https://zlibrary-global.se",
+]
+
+DEFAULT_WELIB_MIRRORS = [
+    "https://welib.org",
+]
+
+
+def _normalize_mirror_url(url: str) -> str:
+    return normalize_http_url(url, default_scheme="https")
+
+
+def get_aa_mirrors() -> List[str]:
+    """
+    Get Anna's Archive mirrors.
+
+    Returns:
+        Ordered list of AA mirror URLs.
+
+        If AA_MIRROR_URLS is configured, it is treated as the full list.
+        Otherwise, defaults are used and AA_ADDITIONAL_URLS (legacy) is appended.
+
+        Notes:
+        - The list is used to populate the AA mirror dropdown in Settings.
+        - When AA_BASE_URL is set to 'auto', mirrors are tried in the order listed.
+    """
+    config = _get_config()
+
+    mirrors: list[str] = []
+
+    configured_list = config.get("AA_MIRROR_URLS", None)
+    if isinstance(configured_list, list):
+        for url in configured_list:
+            normalized = _normalize_mirror_url(str(url))
+            if normalized and normalized not in mirrors:
+                mirrors.append(normalized)
+    elif isinstance(configured_list, str) and configured_list.strip():
+        # Allow comma-separated env/manual configs.
+        for url in configured_list.split(","):
+            normalized = _normalize_mirror_url(url)
+            if normalized and normalized not in mirrors:
+                mirrors.append(normalized)
+
+    if not mirrors:
+        mirrors = [_normalize_mirror_url(url) for url in DEFAULT_AA_MIRRORS]
+        mirrors = [url for url in mirrors if url]
+
+        # Backwards-compatible append-only behavior for legacy configs/env.
+        additional = config.get("AA_ADDITIONAL_URLS", "")
+        if additional:
+            for url in additional.split(","):
+                normalized = _normalize_mirror_url(url)
+                if normalized and normalized not in mirrors:
+                    mirrors.append(normalized)
+
+    return mirrors
+
+
+def get_libgen_mirrors() -> List[str]:
+    """
+    Get LibGen mirrors: defaults + any additional from config.
+
+    Returns:
+        List of LibGen mirror URLs (defaults first, then custom additions).
+    """
+    mirrors = [_normalize_mirror_url(url) for url in DEFAULT_LIBGEN_MIRRORS]
+    mirrors = [url for url in mirrors if url]
+    config = _get_config()
+
+    additional = config.get("LIBGEN_ADDITIONAL_URLS", "")
+    if additional:
+        for url in additional.split(","):
+            normalized = _normalize_mirror_url(url)
+            if normalized and normalized not in mirrors:
+                mirrors.append(normalized)
+
+    return mirrors
+
+
+def get_zlib_mirrors() -> List[str]:
+    """
+    Get Z-Library mirrors, with primary first.
+
+    Returns:
+        List of Z-Library mirror URLs, primary first.
+    """
+    config = _get_config()
+
+    primary = _normalize_mirror_url(config.get("ZLIB_PRIMARY_URL", DEFAULT_ZLIB_MIRRORS[0]))
+    if not primary:
+        primary = _normalize_mirror_url(DEFAULT_ZLIB_MIRRORS[0])
+    mirrors = [primary]
+
+    # Add other defaults (excluding primary)
+    for url in DEFAULT_ZLIB_MIRRORS:
+        normalized = _normalize_mirror_url(url)
+        if normalized and normalized != primary:
+            mirrors.append(normalized)
+
+    # Add custom mirrors
+    additional = config.get("ZLIB_ADDITIONAL_URLS", "")
+    if additional:
+        for url in additional.split(","):
+            normalized = _normalize_mirror_url(url)
+            if normalized and normalized not in mirrors:
+                mirrors.append(normalized)
+
+    return mirrors
+
+
+def get_zlib_primary_url() -> str:
+    """
+    Get the primary Z-Library mirror URL.
+
+    Returns:
+        Primary Z-Library mirror URL.
+    """
+    config = _get_config()
+    primary = _normalize_mirror_url(config.get("ZLIB_PRIMARY_URL", DEFAULT_ZLIB_MIRRORS[0]))
+    return primary or _normalize_mirror_url(DEFAULT_ZLIB_MIRRORS[0])
+
+
+def get_zlib_url_template() -> str:
+    """
+    Get Z-Library URL template using configured primary mirror.
+
+    Returns:
+        URL template with {md5} placeholder.
+    """
+    primary = get_zlib_primary_url()
+    return f"{primary}/md5/{{md5}}"
+
+
+def get_welib_mirrors() -> List[str]:
+    """
+    Get Welib mirrors, with primary first.
+
+    Returns:
+        List of Welib mirror URLs, primary first.
+    """
+    config = _get_config()
+
+    primary = _normalize_mirror_url(config.get("WELIB_PRIMARY_URL", DEFAULT_WELIB_MIRRORS[0]))
+    if not primary:
+        primary = _normalize_mirror_url(DEFAULT_WELIB_MIRRORS[0])
+    mirrors = [primary]
+
+    # Add other defaults (excluding primary)
+    for url in DEFAULT_WELIB_MIRRORS:
+        normalized = _normalize_mirror_url(url)
+        if normalized and normalized != primary:
+            mirrors.append(normalized)
+
+    # Add custom mirrors
+    additional = config.get("WELIB_ADDITIONAL_URLS", "")
+    if additional:
+        for url in additional.split(","):
+            normalized = _normalize_mirror_url(url)
+            if normalized and normalized not in mirrors:
+                mirrors.append(normalized)
+
+    return mirrors
+
+
+def get_welib_primary_url() -> str:
+    """
+    Get the primary Welib mirror URL.
+
+    Returns:
+        Primary Welib mirror URL.
+    """
+    config = _get_config()
+    primary = _normalize_mirror_url(config.get("WELIB_PRIMARY_URL", DEFAULT_WELIB_MIRRORS[0]))
+    return primary or _normalize_mirror_url(DEFAULT_WELIB_MIRRORS[0])
+
+
+def get_welib_url_template() -> str:
+    """
+    Get Welib URL template using configured primary mirror.
+
+    Returns:
+        URL template with {md5} placeholder.
+    """
+    primary = get_welib_primary_url()
+    return f"{primary}/md5/{{md5}}"
+
+
+def get_zlib_cookie_domains() -> set:
+    """
+    Get set of Z-Library domains that need full cookie handling.
+
+    Used by internal_bypasser for CF bypass cookie management.
+
+    Returns:
+        Set of domain strings (without protocol).
+    """
+    domains = set()
+
+    # Add all default domains
+    for url in DEFAULT_ZLIB_MIRRORS:
+        normalized = _normalize_mirror_url(url)
+        if normalized:
+            domain = normalized.replace("https://", "").replace("http://", "").split("/")[0]
+            domains.add(domain)
+
+    # Add custom domains
+    config = _get_config()
+    additional = config.get("ZLIB_ADDITIONAL_URLS", "")
+    if additional:
+        for url in additional.split(","):
+            normalized = _normalize_mirror_url(url)
+            if normalized:
+                domain = normalized.replace("https://", "").replace("http://", "").split("/")[0]
+                domains.add(domain)
+
+    return domains

shelfmark/core/models.py

@@ -2,7 +2,7 @@
 
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
 from enum import Enum
 import re
 import time
@@ -14,17 +14,6 @@ def build_filename(
     year: Optional[str] = None,
     fmt: Optional[str] = None,
 ) -> str:
-    """Build sanitized filename: 'Author - Title (Year).format'
-
-    Args:
-        title: Book title (required)
-        author: Book author
-        year: Publication year
-        fmt: File format/extension
-
-    Returns:
-        Sanitized filename safe for filesystem use
-    """
     parts = []
     if author:
         parts.append(author)
@@ -46,14 +35,27 @@ class QueueStatus(str, Enum):
     """Enum for possible book queue statuses."""
     QUEUED = "queued"
     RESOLVING = "resolving"
+    LOCATING = "locating"
     DOWNLOADING = "downloading"
     COMPLETE = "complete"
-    AVAILABLE = "available"
     ERROR = "error"
-    DONE = "done"
     CANCELLED = "cancelled"
 
 
+TERMINAL_QUEUE_STATUSES: frozenset[QueueStatus] = frozenset({
+    QueueStatus.COMPLETE, QueueStatus.ERROR, QueueStatus.CANCELLED,
+})
+
+ACTIVE_QUEUE_STATUSES: frozenset[QueueStatus] = frozenset({
+    QueueStatus.QUEUED, QueueStatus.RESOLVING, QueueStatus.LOCATING, QueueStatus.DOWNLOADING,
+})
+
+
+class SearchMode(str, Enum):
+    DIRECT = "direct"
+    UNIVERSAL = "universal"
+
+
 @dataclass
 class QueueItem:
     """Queue item with priority and metadata."""
@@ -70,22 +72,40 @@ class QueueItem:
 
 @dataclass
 class DownloadTask:
-    """Source-agnostic download task for the queue.
-
-    This replaces BookInfo in the queue, providing a unified interface
-    for both Direct Download and Universal modes. The handler uses task_id
-    to fetch whatever source-specific data it needs internally.
-    """
     task_id: str                                # Unique ID (e.g., AA MD5 hash, Prowlarr GUID)
     source: str                                 # Handler name ("direct_download", "prowlarr")
     title: str                                  # Display title for queue sidebar
 
     # Display info for queue sidebar
     author: Optional[str] = None
+    year: Optional[str] = None
     format: Optional[str] = None
     size: Optional[str] = None
     preview: Optional[str] = None
     content_type: Optional[str] = None  # "book (fiction)", "audiobook", "magazine", etc.
+    source_url: Optional[str] = None  # Original release URL used by source-specific handlers
+
+    # Series info (for library naming templates)
+    series_name: Optional[str] = None
+    series_position: Optional[float] = None  # Float for novellas (e.g., 1.5)
+    subtitle: Optional[str] = None  # Book subtitle for naming templates
+
+    # Hardlinking support
+    original_download_path: Optional[str] = None  # Path in download client (for hardlinking)
+
+    # Search mode - determines post-download processing behavior
+    # See SearchMode enum for behavioral differences
+    search_mode: Optional[SearchMode] = None
+
+    # Output selection for post-processing.
+    # This is captured at queue time so in-flight tasks are not affected if the user changes settings later.
+    output_mode: Optional[str] = None  # e.g. "folder", "booklore", "email"
+    output_args: Dict[str, Any] = field(default_factory=dict)  # Per-output parameters (e.g. email recipient)
+
+    # User association (multi-user support)
+    user_id: Optional[int] = None  # DB user ID who queued this download
+    username: Optional[str] = None  # Username for {User} template variable
+    request_id: Optional[int] = None  # Origin request ID when queued from request fulfilment
 
     # Runtime state
     priority: int = 0
@@ -94,6 +114,9 @@ class DownloadTask:
     status: QueueStatus = QueueStatus.QUEUED
     status_message: Optional[str] = None
     download_path: Optional[str] = None
+    last_error_message: Optional[str] = None
+    last_error_type: Optional[str] = None
+    staged_path: Optional[str] = None
 
     def __lt__(self, other):
         """Compare tasks for priority queue (lower priority number = higher precedence)."""
@@ -105,52 +128,6 @@ class DownloadTask:
         """Build sanitized filename from task metadata."""
         if self.download_path:
             return Path(self.download_path).name
-        return build_filename(self.title, self.author, fmt=self.format)
-
-
-@dataclass
-class BookInfo:
-    """Data class representing book information."""
-    id: str
-    title: str
-    preview: Optional[str] = None
-    author: Optional[str] = None
-    publisher: Optional[str] = None
-    year: Optional[str] = None
-    language: Optional[str] = None
-    content: Optional[str] = None
-    format: Optional[str] = None
-    size: Optional[str] = None
-    info: Optional[Dict[str, List[str]]] = None
-    description: Optional[str] = None
-    download_urls: List[str] = field(default_factory=list)
-    download_path: Optional[str] = None
-    priority: int = 0
-    progress: Optional[float] = None
-    status_message: Optional[str] = None  # Detailed status message for UI display
-    added_time: Optional[float] = None  # Timestamp when added to queue
-    source: str = "direct_download"  # Release source handler to use for downloads
-
-    def get_filename(self, fallback_url: Optional[str] = None) -> str:
-        """Build sanitized filename: 'Author - Title (Year).format'
-
-        Resolves format from self.format, download_urls, or fallback_url.
-
-        Args:
-            fallback_url: URL to extract format from if not already known
-
-        Returns:
-            Sanitized filename safe for filesystem use
-        """
-        # Resolve format if needed
-        if not self.format:
-            for url in (self.download_urls[0] if self.download_urls else None, fallback_url):
-                if url:
-                    ext = url.split(".")[-1].lower()
-                    if ext and len(ext) <= 5 and ext.isalnum():
-                        self.format = ext
-                        break
-
         return build_filename(self.title, self.author, self.year, self.format)
 
 

shelfmark/core/naming.py

@@ -0,0 +1,249 @@
+"""Template-based naming for library organization."""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, Optional, Union, Mapping
+
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+# Known variable tokens, sorted longest-first to avoid partial matches
+# e.g., "SeriesPosition" must match before "Series"
+KNOWN_TOKENS = [
+    'seriesposition',
+    'originalname',
+    'partnumber',
+    'subtitle',
+    'author',
+    'series',
+    'title',
+    'year',
+    'user',
+]
+
+# Match any {...} block for template parsing
+BRACE_PATTERN = re.compile(r'\{([^}]+)\}')
+
+# Characters that are invalid in filenames on various filesystems
+INVALID_CHARS = re.compile(r'[\\/:*?"<>|]')
+
+
+def _sanitize(name: Optional[str], max_length: int = 245) -> str:
+    """Sanitize a string for filesystem use."""
+    if not name:
+        return ""
+
+    sanitized = INVALID_CHARS.sub('_', name)
+    sanitized = re.sub(r'^[\s.]+|[\s.]+$', '', sanitized)  # Strip whitespace and dots
+    sanitized = re.sub(r'_+', '_', sanitized)  # Collapse underscores
+    return sanitized[:max_length]
+
+
+def sanitize_filename(name: Optional[str], max_length: int = 245) -> str:
+    """Sanitize a string for use as a filename or path component."""
+    return _sanitize(name, max_length)
+
+
+# Alias for backwards compatibility
+sanitize_path_component = sanitize_filename
+
+
+def format_series_position(position: Optional[Union[str, int, float]]) -> str:
+    if position is None:
+        return ""
+
+    # Display as integer if whole number
+    if isinstance(position, float) and position.is_integer():
+        return str(int(position))
+
+    return str(position)
+
+
+# Pads numbers to 9 digits for natural sorting (e.g., "Part 2" -> "Part 000000002")
+PAD_NUMBERS_PATTERN = re.compile(r'\d+')
+
+
+def natural_sort_key(path: Union[str, Path]) -> str:
+    """Generate a sort key with padded numbers for natural sorting."""
+    filename = Path(path).name.lower()
+    return PAD_NUMBERS_PATTERN.sub(lambda m: m.group().zfill(9), filename)
+
+
+def assign_part_numbers(
+    files: list[Path],
+    zero_pad_width: int = 2,
+) -> list[tuple[Path, str]]:
+    """Sort files naturally and assign sequential part numbers (1, 2, 3...)."""
+    if not files:
+        return []
+
+    sorted_files = sorted(files, key=natural_sort_key)
+    return [
+        (file_path, str(part_num).zfill(zero_pad_width))
+        for part_num, file_path in enumerate(sorted_files, start=1)
+    ]
+
+
+def parse_naming_template(
+    template: str,
+    metadata: Mapping[str, Optional[Union[str, int, float]]],
+    *,
+    allow_path_separators: bool = True,
+) -> str:
+    if not template:
+        return ""
+
+    # Normalize metadata keys to lowercase for case-insensitive matching
+    normalized = {k.lower(): v for k, v in metadata.items()}
+
+    def find_token(content: str) -> tuple[Optional[str], int]:
+        content_lower = content.lower()
+        for token in KNOWN_TOKENS:
+            idx = content_lower.find(token)
+            if idx != -1:
+                return token, idx
+        return None, -1
+
+    def token_value(token: str) -> str:
+        value = normalized.get(token)
+        if token == 'seriesposition':
+            value = format_series_position(value)
+        if value is None:
+            return ""
+        return str(value).strip()
+
+    def render_block(content: str) -> Optional[str]:
+        token, idx = find_token(content)
+        if token is None:
+            return None
+
+        prefix = content[:idx]
+        suffix = content[idx + len(token):]
+        value = token_value(token)
+        if not value:
+            return ""
+
+        if not allow_path_separators:
+            value = value.replace("/", "_")
+        value = sanitize_filename(value)
+        return f"{prefix}{value}{suffix}"
+
+    # Process brace blocks in order so we can support conditional literal blocks like:
+    # { - Part }{PartNumber}
+    matches = list(BRACE_PATTERN.finditer(template))
+    if not matches:
+        result = template
+    else:
+        parts: list[str] = []
+        cursor = 0
+        for idx, match in enumerate(matches):
+            parts.append(template[cursor:match.start()])
+            content = match.group(1)
+            rendered = render_block(content)
+
+            if rendered is not None:
+                parts.append(rendered)
+            else:
+                conditional_literal = False
+                include_literal = False
+                if idx + 1 < len(matches) and match.end() == matches[idx + 1].start():
+                    next_content = matches[idx + 1].group(1)
+                    next_token, _next_idx = find_token(next_content)
+                    if next_token is not None:
+                        conditional_literal = True
+                        include_literal = bool(token_value(next_token))
+                if include_literal:
+                    parts.append(content)
+                elif not conditional_literal:
+                    # Preserve blocks that look like literal text, but treat bare unknown
+                    # placeholders as missing variables.
+                    if re.search(r"\s", content):
+                        parts.append(match.group(0))
+
+            cursor = match.end()
+
+        parts.append(template[cursor:])
+        result = "".join(parts)
+
+    # Clean up any double slashes that might result from empty tokens
+    result = re.sub(r'/+', '/', result)
+
+    # Remove leading/trailing slashes
+    result = result.strip('/')
+
+    # Clean up any orphaned separators (e.g., " - " at start/end, or " -  - ")
+    result = re.sub(r'^[\s\-_.]+', '', result)
+    result = re.sub(r'[\s\-_.]+$', '', result)
+    result = re.sub(r'(\s*-\s*){2,}', ' - ', result)
+
+    # Clean up empty parentheses/brackets
+    result = re.sub(r'\(\s*\)', '', result)
+    result = re.sub(r'\[\s*\]', '', result)
+
+    # Final trim of any trailing separators left after cleanup
+    result = re.sub(r'[\s\-_.]+$', '', result)
+
+    return result
+
+
+def build_library_path(
+    base_path: str,
+    template: str,
+    metadata: Mapping[str, Optional[Union[str, int, float]]],
+    extension: Optional[str] = None,
+) -> Path:
+    relative = parse_naming_template(template, metadata, allow_path_separators=True)
+
+    if not relative:
+        # Fallback to title if template produces empty result
+        title = metadata.get('Title') or metadata.get('title') or 'Unknown'
+        relative = sanitize_filename(str(title))
+
+    # Remove any path traversal attempts
+    relative = relative.replace('..', '')
+
+    base = Path(base_path).resolve()
+    full_path = (base / relative).resolve()
+
+    # Verify the path is within the base directory
+    try:
+        full_path.relative_to(base)
+    except ValueError:
+        raise ValueError(f"Path traversal detected: template would escape library directory")
+
+    if extension:
+        ext = extension.lstrip('.')
+        # Don't use with_suffix() - it replaces everything after the first dot
+        # e.g., "2.5 - Title" would become "2.epub" instead of "2.5 - Title.epub"
+        full_path = Path(f"{full_path}.{ext}")
+
+    return full_path
+
+
+def same_filesystem(path1: Union[str, Path], path2: Union[str, Path]) -> bool:
+    """Check if two paths are on the same filesystem."""
+    path1 = Path(path1)
+    path2 = Path(path2)
+
+    def get_device(p: Path) -> Optional[int]:
+        try:
+            while not p.exists():
+                p = p.parent
+                if p == p.parent:
+                    break
+            return os.stat(p).st_dev
+        except (OSError, PermissionError) as e:
+            logger.debug(f"Cannot stat {p}: {e}")
+            return None
+
+    dev1 = get_device(path1)
+    dev2 = get_device(path2)
+
+    if dev1 is None or dev2 is None:
+        logger.warning(f"Cannot determine filesystem for hardlink check, falling back to copy")
+        return False
+
+    return dev1 == dev2

shelfmark/core/notifications.py

@@ -0,0 +1,613 @@
+"""Apprise notification dispatch for global and per-user events."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Iterable, Iterator
+from urllib.parse import urlsplit
+
+try:
+    import apprise
+except Exception:  # pragma: no cover - exercised in tests via monkeypatch
+    apprise = None  # type: ignore[assignment]
+
+from shelfmark.core.config import config as app_config
+from shelfmark.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Small pool for non-blocking dispatch. Notification sends are I/O bound and infrequent.
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="Notify")
+_ROUTE_EVENT_ALL = "all"
+_APPRISE_APP_ID = "Shelfmark"
+_APPRISE_APP_DESC = "Shelfmark notifications"
+_APPRISE_LOGO_URL = (
+    "https://raw.githubusercontent.com/calibrain/shelfmark/main/src/frontend/public/logo.png"
+)
+_APPRISE_LOGGER_NAME = "apprise"
+
+
+class NotificationEvent(str, Enum):
+    """Global notification event identifiers."""
+
+    REQUEST_CREATED = "request_created"
+    REQUEST_FULFILLED = "request_fulfilled"
+    REQUEST_REJECTED = "request_rejected"
+    DOWNLOAD_COMPLETE = "download_complete"
+    DOWNLOAD_FAILED = "download_failed"
+
+
+@dataclass
+class NotificationContext:
+    """Context used to render notification templates."""
+
+    event: NotificationEvent
+    title: str
+    author: str
+    username: str | None = None
+    content_type: str | None = None
+    format: str | None = None
+    source: str | None = None
+    admin_note: str | None = None
+    error_message: str | None = None
+
+
+def _normalize_urls(value: Any) -> list[str]:
+    if value is None:
+        return []
+
+    raw_values: list[Any]
+    if isinstance(value, list):
+        raw_values = value
+    elif isinstance(value, str):
+        # Support legacy/manual configs.
+        raw_values = [segment for part in value.splitlines() for segment in part.split(",")]
+    else:
+        raw_values = [value]
+
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for raw_url in raw_values:
+        url = str(raw_url or "").strip()
+        if not url:
+            continue
+        # Strip invisible/non-ASCII characters that can sneak in via copy-paste
+        # (zero-width spaces, smart quotes, non-breaking spaces, etc.).
+        # These pass Apprise URL validation but cause UnicodeEncodeError when
+        # requests tries to latin-1 encode credentials for Basic Auth headers.
+        url = url.encode("ascii", errors="ignore").decode("ascii").strip()
+        if not url:
+            continue
+        if url in seen:
+            continue
+        seen.add(url)
+        normalized.append(url)
+    return normalized
+
+
+def _extract_url_schemes(urls: Iterable[str]) -> list[str]:
+    schemes: list[str] = []
+    seen: set[str] = set()
+    for raw_url in urls:
+        scheme = urlsplit(str(raw_url or "")).scheme.lower()
+        if not scheme or scheme in seen:
+            continue
+        seen.add(scheme)
+        schemes.append(scheme)
+    return schemes
+
+
+class _AppriseLogCapture(logging.Handler):
+    def __init__(self, *, thread_id: int):
+        super().__init__(level=logging.INFO)
+        self.records: list[tuple[int, str, str, str]] = []
+        self._thread_id = thread_id
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.thread != self._thread_id:
+            return
+
+        message = record.getMessage()
+        if message:
+            exception_summary = ""
+            if record.exc_info and record.exc_info[0]:
+                exc_type = getattr(record.exc_info[0], "__name__", "Exception")
+                exc = record.exc_info[1]
+                exception_summary = f"{exc_type}: {exc}"
+            elif record.exc_text:
+                exception_summary = str(record.exc_text).strip()
+
+            self.records.append((record.levelno, record.name, str(message), exception_summary))
+
+
+@contextmanager
+def _capture_apprise_logs(*, min_level: int = logging.INFO) -> Iterator[list[tuple[int, str, str, str]]]:
+    apprise_logger = logging.getLogger(_APPRISE_LOGGER_NAME)
+    previous_level = apprise_logger.level
+    handler = _AppriseLogCapture(thread_id=threading.get_ident())
+    apprise_logger.addHandler(handler)
+
+    if previous_level == logging.NOTSET or previous_level > min_level:
+        apprise_logger.setLevel(min_level)
+
+    try:
+        yield handler.records
+    finally:
+        apprise_logger.removeHandler(handler)
+        apprise_logger.setLevel(previous_level)
+
+
+def _log_apprise_records(records: Iterable[tuple[int, str, str, str]]) -> None:
+    seen: set[tuple[int, str, str, str]] = set()
+    for level, source, raw_message, raw_exception_summary in records:
+        message = str(raw_message or "").strip()
+        source_name = str(source or "").strip() or _APPRISE_LOGGER_NAME
+        exception_summary = str(raw_exception_summary or "").strip()
+        key = (int(level), source_name, message, exception_summary)
+        if not message or key in seen:
+            continue
+        seen.add(key)
+
+        full_message = message if not exception_summary else f"{message} ({exception_summary})"
+
+        if level >= logging.ERROR:
+            logger.error("Apprise source [%s]: %s", source_name, full_message)
+        elif level >= logging.WARNING:
+            logger.warning("Apprise source [%s]: %s", source_name, full_message)
+        else:
+            logger.info("Apprise source [%s]: %s", source_name, full_message)
+
+
+def _log_apprise_exception_debug(*, action: str, scheme: str, exc: Exception) -> None:
+    logger.debug(
+        "Apprise %s raised %s for scheme '%s': %s",
+        action,
+        type(exc).__name__,
+        scheme,
+        exc,
+        exc_info=True,
+    )
+
+
+def _build_apprise_warning_detail(
+    records: Iterable[tuple[int, str, str, str]],
+    *,
+    scheme: str,
+) -> str | None:
+    for level, source, raw_message, raw_exception_summary in records:
+        if level < logging.WARNING:
+            continue
+
+        message = str(raw_message or "").strip()
+        if not message:
+            continue
+
+        source_name = str(source or "").strip()
+        exception_summary = str(raw_exception_summary or "").strip()
+        full_message = message if not exception_summary else f"{message} ({exception_summary})"
+
+        if source_name and source_name != _APPRISE_LOGGER_NAME:
+            return f"{scheme}: {source_name}: {full_message}"
+        return f"{scheme}: {full_message}"
+    return None
+
+
+def _normalize_routes(value: Any) -> list[dict[str, str]]:
+    if not isinstance(value, list):
+        return []
+
+    allowed_events = {_ROUTE_EVENT_ALL, *(event.value for event in NotificationEvent)}
+    normalized: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+
+    for row in value:
+        if not isinstance(row, dict):
+            continue
+
+        raw_events = row.get("event")
+        if isinstance(raw_events, list):
+            event_values = raw_events
+        elif isinstance(raw_events, (tuple, set)):
+            event_values = list(raw_events)
+        else:
+            event_values = [raw_events]
+
+        url = str(row.get("url") or "").strip()
+        if not url:
+            continue
+
+        row_events: list[str] = []
+        for raw_event in event_values:
+            event = str(raw_event or "").strip().lower()
+            if event not in allowed_events:
+                continue
+            if event in row_events:
+                continue
+            row_events.append(event)
+
+        if _ROUTE_EVENT_ALL in row_events:
+            row_events = [_ROUTE_EVENT_ALL]
+
+        for event in row_events:
+            key = (event, url)
+            if key in seen:
+                continue
+            seen.add(key)
+
+            normalized.append({"event": event, "url": url})
+
+    return normalized
+
+
+def _resolve_admin_routes() -> list[dict[str, str]]:
+    return _normalize_routes(app_config.get("ADMIN_NOTIFICATION_ROUTES", []))
+
+
+def _normalize_user_id(value: Any) -> int | None:
+    try:
+        user_id = int(value)
+    except (TypeError, ValueError):
+        return None
+    if user_id < 1:
+        return None
+    return user_id
+
+
+def _resolve_user_routes(user_id: int | None) -> list[dict[str, str]]:
+    normalized_user_id = _normalize_user_id(user_id)
+    if normalized_user_id is None:
+        return []
+
+    return _normalize_routes(
+        app_config.get("USER_NOTIFICATION_ROUTES", [], user_id=normalized_user_id)
+    )
+
+
+def _resolve_route_urls_for_event(
+    routes: list[dict[str, str]],
+    event: NotificationEvent,
+) -> list[str]:
+    selected: list[str] = []
+    seen: set[str] = set()
+    event_value = event.value
+
+    for row in routes:
+        row_event = row.get("event", "")
+        if row_event not in {_ROUTE_EVENT_ALL, event_value}:
+            continue
+
+        url = row.get("url", "")
+        if not url or url in seen:
+            continue
+
+        seen.add(url)
+        selected.append(url)
+
+    return selected
+
+
+def _resolve_notify_type(event: NotificationEvent) -> Any:
+    if apprise is None:
+        fallback = {
+            NotificationEvent.REQUEST_CREATED: "info",
+            NotificationEvent.REQUEST_FULFILLED: "success",
+            NotificationEvent.REQUEST_REJECTED: "warning",
+            NotificationEvent.DOWNLOAD_COMPLETE: "success",
+            NotificationEvent.DOWNLOAD_FAILED: "failure",
+        }
+        return fallback[event]
+
+    mapping = {
+        NotificationEvent.REQUEST_CREATED: apprise.NotifyType.INFO,
+        NotificationEvent.REQUEST_FULFILLED: apprise.NotifyType.SUCCESS,
+        NotificationEvent.REQUEST_REJECTED: apprise.NotifyType.WARNING,
+        NotificationEvent.DOWNLOAD_COMPLETE: apprise.NotifyType.SUCCESS,
+        NotificationEvent.DOWNLOAD_FAILED: apprise.NotifyType.FAILURE,
+    }
+    return mapping[event]
+
+
+def _clean_text(value: Any, fallback: str) -> str:
+    text = str(value or "").strip()
+    return text or fallback
+
+
+def _render_message(context: NotificationContext) -> tuple[str, str]:
+    event = context.event
+    title = _clean_text(context.title, "Unknown title")
+    author = _clean_text(context.author, "Unknown author")
+    username = _clean_text(context.username, "A user")
+
+    if event == NotificationEvent.REQUEST_CREATED:
+        return "New Request", f'{username} requested "{title}" by {author}'
+    if event == NotificationEvent.REQUEST_FULFILLED:
+        return "Request Approved", f'Request for "{title}" by {author} was approved.'
+    if event == NotificationEvent.REQUEST_REJECTED:
+        note = _clean_text(context.admin_note, "")
+        note_line = f"\nNote: {note}" if note else ""
+        return "Request Rejected", f'Request for "{title}" by {author} was rejected.{note_line}'
+    if event == NotificationEvent.DOWNLOAD_COMPLETE:
+        return "Download Complete", f'"{title}" by {author} downloaded successfully.'
+
+    error_message = _clean_text(context.error_message, "")
+    error_line = f"\nError: {error_message}" if error_message else ""
+    return "Download Failed", f'Failed to download "{title}" by {author}.{error_line}'
+
+
+def _plugin_label(plugin: Any, fallback_scheme: str) -> str:
+    """Build a human-readable label from a validated Apprise plugin.
+
+    Combines the URL scheme with the plugin's service name (app_id) and
+    privacy-safe URL for richer diagnostics, e.g.
+    ``"slack (Slack - slack://TokenA/To...n/To...n/)"``
+    """
+    parts: list[str] = [fallback_scheme]
+
+    app_id = getattr(plugin, "app_id", None)
+    if app_id and str(app_id) != fallback_scheme:
+        privacy_url: str | None = None
+        try:
+            privacy_url = plugin.url(privacy=True)
+        except Exception:
+            pass
+
+        suffix = str(app_id)
+        if privacy_url:
+            suffix = f"{suffix} - {privacy_url}"
+        parts.append(f"({suffix})")
+
+    return " ".join(parts)
+
+
+def _dispatch_to_apprise(
+    urls: Iterable[str],
+    *,
+    title: str,
+    body: str,
+    notify_type: Any,
+) -> dict[str, Any]:
+    normalized_urls = _normalize_urls(list(urls))
+    url_schemes = _extract_url_schemes(normalized_urls)
+    if not normalized_urls:
+        return {"success": False, "message": "No notification URLs configured"}
+
+    if apprise is None:
+        return {"success": False, "message": "Apprise is not installed"}
+
+    valid_urls = 0
+    invalid_urls = 0
+    delivered_urls = 0
+    failed_delivery_urls = 0
+    failure_details: list[str] = []
+
+    for url in normalized_urls:
+        scheme = urlsplit(url).scheme or "unknown"
+        apobj = _create_apprise_client()
+        if apobj is None:
+            return {"success": False, "message": "Apprise is not installed"}
+
+        registration_failure_detail: str | None = None
+        with _capture_apprise_logs(min_level=logging.INFO) as apprise_records:
+            try:
+                plugin = apprise.Apprise.instantiate(url, asset=getattr(apobj, "asset", None))
+            except Exception as exc:
+                logger.warning(
+                    "Failed to register notification route URL for scheme '%s': %s",
+                    scheme,
+                    exc,
+                )
+                _log_apprise_exception_debug(
+                    action="route registration",
+                    scheme=scheme,
+                    exc=exc,
+                )
+                registration_failure_detail = (
+                    f"{scheme}: route registration failed ({type(exc).__name__}: {exc})"
+                )
+                failure_details.append(registration_failure_detail)
+                plugin = None
+
+            if plugin is None:
+                invalid_urls += 1
+                logger.warning("Apprise rejected notification route URL for scheme '%s'", scheme)
+                _log_apprise_records(apprise_records)
+                warning_detail = _build_apprise_warning_detail(apprise_records, scheme=scheme)
+                if warning_detail:
+                    failure_details.append(warning_detail)
+                elif registration_failure_detail is None:
+                    failure_details.append(f"{scheme}: route URL rejected by Apprise")
+                continue
+
+            plugin_label = _plugin_label(plugin, scheme)
+            apobj.add(plugin)
+            valid_urls += 1
+
+            try:
+                delivered = bool(apobj.notify(title=title, body=body, notify_type=notify_type))
+            except Exception as exc:
+                _log_apprise_records(apprise_records)
+                failed_delivery_urls += 1
+                logger.warning(
+                    "Apprise notify raised %s for %s: %s",
+                    type(exc).__name__,
+                    plugin_label,
+                    exc,
+                )
+                _log_apprise_exception_debug(action="notify", scheme=scheme, exc=exc)
+                warning_detail = _build_apprise_warning_detail(apprise_records, scheme=scheme)
+                if warning_detail:
+                    failure_details.append(warning_detail)
+                else:
+                    failure_details.append(
+                        f"{scheme}: notify raised {type(exc).__name__}: {exc}"
+                    )
+                continue
+
+        _log_apprise_records(apprise_records)
+        if delivered:
+            delivered_urls += 1
+            logger.debug("Notification delivered via %s", plugin_label)
+            continue
+
+        failed_delivery_urls += 1
+        logger.warning("Apprise notify returned False for %s", plugin_label)
+        warning_detail = _build_apprise_warning_detail(apprise_records, scheme=scheme)
+        if warning_detail:
+            failure_details.append(warning_detail)
+        else:
+            failure_details.append(f"{scheme}: delivery failed")
+
+    scheme_summary = ", ".join(url_schemes) if url_schemes else "unknown"
+    if valid_urls == 0:
+        logger.warning(
+            "No valid Apprise notification routes after registration for scheme(s): %s",
+            scheme_summary,
+        )
+        result: dict[str, Any] = {
+            "success": False,
+            "message": "No valid notification URLs configured",
+        }
+        if failure_details:
+            result["details"] = failure_details
+        return result
+
+    if delivered_urls == 0:
+        logger.warning(
+            (
+                "Apprise notify returned False for scheme(s): %s "
+                "(valid_urls=%s invalid_urls=%s failed_deliveries=%s)"
+            ),
+            scheme_summary,
+            valid_urls,
+            invalid_urls,
+            failed_delivery_urls,
+        )
+        result = {"success": False, "message": "Notification delivery failed"}
+        if failure_details:
+            result["details"] = failure_details
+        return result
+
+    message = f"Notification sent to {delivered_urls} URL(s)"
+    failed_urls = invalid_urls + failed_delivery_urls
+    if failed_urls:
+        message += f" ({failed_urls} URL(s) failed)"
+    result = {"success": True, "message": message}
+    if failure_details:
+        result["details"] = failure_details
+    return result
+
+
+def _create_apprise_client() -> Any:
+    if apprise is None:
+        return None
+
+    apprise_cls = getattr(apprise, "Apprise", None)
+    if apprise_cls is None:
+        return None
+
+    apprise_asset_cls = getattr(apprise, "AppriseAsset", None)
+    if apprise_asset_cls is None:
+        return apprise_cls()
+
+    try:
+        asset = apprise_asset_cls(
+            app_id=_APPRISE_APP_ID,
+            app_desc=_APPRISE_APP_DESC,
+            image_url_logo=_APPRISE_LOGO_URL,
+        )
+    except TypeError:
+        # Support older Apprise versions that do not expose image_url_logo.
+        asset = apprise_asset_cls(
+            app_id=_APPRISE_APP_ID,
+            app_desc=_APPRISE_APP_DESC,
+        )
+    except Exception:
+        return apprise_cls()
+
+    try:
+        return apprise_cls(asset=asset)
+    except Exception:
+        return apprise_cls()
+
+
+def _send_admin_event(event: NotificationEvent, context: NotificationContext, urls: list[str]) -> dict[str, Any]:
+    title, body = _render_message(context)
+    notify_type = _resolve_notify_type(event)
+    return _dispatch_to_apprise(urls, title=title, body=body, notify_type=notify_type)
+
+
+def notify_admin(event: NotificationEvent, context: NotificationContext) -> None:
+    """Send a global admin notification for an event if subscribed."""
+    routes = _resolve_admin_routes()
+    urls = _resolve_route_urls_for_event(routes, event)
+    if not urls:
+        return
+
+    try:
+        _executor.submit(_dispatch_admin_async, event, context, urls)
+    except Exception as exc:
+        logger.warning("Failed to queue admin notification '%s': %s", event.value, exc)
+
+
+def notify_user(user_id: int | None, event: NotificationEvent, context: NotificationContext) -> None:
+    """Send a per-user notification for an event if subscribed."""
+    normalized_user_id = _normalize_user_id(user_id)
+    if normalized_user_id is None:
+        return
+
+    routes = _resolve_user_routes(normalized_user_id)
+    urls = _resolve_route_urls_for_event(routes, event)
+    if not urls:
+        return
+
+    try:
+        _executor.submit(_dispatch_user_async, normalized_user_id, event, context, urls)
+    except Exception as exc:
+        logger.warning(
+            "Failed to queue user notification '%s' for user_id=%s: %s",
+            event.value,
+            normalized_user_id,
+            exc,
+        )
+
+
+def _dispatch_admin_async(event: NotificationEvent, context: NotificationContext, urls: list[str]) -> None:
+    result = _send_admin_event(event, context, urls)
+    if not result.get("success", False):
+        logger.warning("Admin notification failed for event '%s': %s", event.value, result.get("message"))
+
+
+def _dispatch_user_async(
+    user_id: int,
+    event: NotificationEvent,
+    context: NotificationContext,
+    urls: list[str],
+) -> None:
+    result = _send_admin_event(event, context, urls)
+    if not result.get("success", False):
+        logger.warning(
+            "User notification failed for event '%s' (user_id=%s): %s",
+            event.value,
+            user_id,
+            result.get("message"),
+        )
+
+
+def send_test_notification(urls: list[str]) -> dict[str, Any]:
+    """Send a synchronous test notification to the provided URLs."""
+    normalized_urls = _normalize_urls(urls)
+    if not normalized_urls:
+        return {"success": False, "message": "No notification URLs configured"}
+
+    test_context = NotificationContext(
+        event=NotificationEvent.REQUEST_CREATED,
+        title="Shelfmark Test Notification",
+        author="Shelfmark",
+        username="Shelfmark",
+    )
+    return _send_admin_event(NotificationEvent.REQUEST_CREATED, test_context, normalized_urls)

shelfmark/core/oidc_auth.py

@@ -0,0 +1,80 @@
+"""OIDC authentication helpers.
+
+Handles group claim parsing, user info extraction, and user provisioning.
+Flask route handlers are registered separately in main.py.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from shelfmark.core.external_user_linking import upsert_external_user
+from shelfmark.core.user_db import UserDB
+
+def parse_group_claims(id_token: Dict[str, Any], group_claim: str) -> List[str]:
+    """Extract group list from an ID token claim.
+
+    Supports list, comma-separated string, or pipe-separated string.
+    Returns empty list if claim is missing.
+    """
+    raw = id_token.get(group_claim)
+    if raw is None:
+        return []
+    if isinstance(raw, list):
+        return [str(g).strip() for g in raw if str(g).strip()]
+    if isinstance(raw, str):
+        delimiter = "," if "," in raw else "|"
+        return [g.strip() for g in raw.split(delimiter) if g.strip()]
+    return []
+
+
+def extract_user_info(id_token: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract user info from OIDC ID token claims.
+
+    Returns a dict with keys: oidc_subject, username, email, display_name.
+    Falls back through preferred_username -> email -> sub for username.
+    """
+    sub = id_token.get("sub", "")
+    email = id_token.get("email")
+    display_name = id_token.get("name")
+    username = id_token.get("preferred_username") or email or sub
+
+    return {
+        "oidc_subject": sub,
+        "username": username,
+        "email": email,
+        "display_name": display_name,
+    }
+
+
+def provision_oidc_user(
+    db: UserDB,
+    user_info: Dict[str, Any],
+    is_admin: Optional[bool] = None,
+    allow_email_link: bool = False,
+    allow_create: bool = True,
+) -> Optional[Dict[str, Any]]:
+    """Create or update a user from OIDC claims.
+
+    Matching and collision handling use the shared external user linker:
+    - OIDC subject first
+    - optionally unique email linking (when `allow_email_link=True`)
+    - username conflict resolution via numeric suffix.
+
+    Returns None when no existing user is matchable and `allow_create=False`.
+    """
+    oidc_subject = user_info["oidc_subject"]
+    user, _ = upsert_external_user(
+        db,
+        auth_source="oidc",
+        username=user_info["username"] or oidc_subject,
+        role="admin" if is_admin else "user",
+        email=user_info.get("email"),
+        display_name=user_info.get("display_name"),
+        subject_field="oidc_subject",
+        subject=oidc_subject,
+        allow_email_link=allow_email_link,
+        sync_role=is_admin is not None,
+        allow_create=allow_create,
+        collision_strategy="suffix",
+        context="oidc_login",
+    )
+    return user