Direct source refactor

.github/workflows/ci.yml

@@ -8,8 +8,8 @@ permissions:
   contents: read
 
 jobs:
-  backend-quality:
-    name: Backend Quality
+  python-quality:
+    name: Python Quality
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -25,23 +25,17 @@ jobs:
       - name: Sync dependencies
         run: make install-python-dev
 
-      - name: Lint backend
+      - name: Lint
         run: make python-lint
 
-      - name: Check backend formatting
-        run: make python-format-check
+      - name: Check formatting
+        run: make python-format
 
-      - name: Check backend dead code
+      - name: Check dead code
         run: make python-dead-code
 
-      - name: Lint tests
-        run: make python-test-lint
-
-      - name: Check test formatting
-        run: make python-test-format-check
-
-  backend-typechecks:
-    name: Backend Typechecks
+  python-typechecks:
+    name: Python Typechecks
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -57,14 +51,11 @@ jobs:
       - name: Sync dependencies
         run: make install-python-dev
 
-      - name: Typecheck backend
+      - name: Typecheck
         run: make python-typecheck
 
-      - name: Typecheck tests
-        run: make python-test-typecheck
-
-  backend-tests:
-    name: Backend Tests
+  python-tests:
+    name: Python Tests
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -81,7 +72,7 @@ jobs:
         run: make install-python-dev
 
       - name: Run tests
-        run: uv run pytest tests/ -x --tb=short -m "not integration and not e2e"
+        run: make python-test
 
   docker-build-check:
     runs-on: ubuntu-latest
@@ -103,7 +94,8 @@ jobs:
             BUILD_VERSION=pr-${{ github.sha }}
             RELEASE_VERSION=pr-${{ github.event.pull_request.number }}
 
-  frontend-checks:
+  frontend-quality:
+    name: Frontend Quality
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -117,21 +109,50 @@ jobs:
           cache-dependency-path: src/frontend/package-lock.json
 
       - name: Install dependencies
-        working-directory: src/frontend
-        run: npm ci
+        run: make install-ci
 
       - name: Lint
-        working-directory: src/frontend
-        run: npm run lint
+        run: make frontend-lint
 
       - name: Check formatting
-        working-directory: src/frontend
-        run: npm run format:check
+        run: make frontend-format
+
+  frontend-typechecks:
+    name: Frontend Typechecks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: "npm"
+          cache-dependency-path: src/frontend/package-lock.json
+
+      - name: Install dependencies
+        run: make install-ci
 
       - name: Typecheck
-        working-directory: src/frontend
-        run: npm run typecheck
+        run: make frontend-typecheck
+
+  frontend-tests:
+    name: Frontend Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: "npm"
+          cache-dependency-path: src/frontend/package-lock.json
+
+      - name: Install dependencies
+        run: make install-ci
 
       - name: Unit tests
-        working-directory: src/frontend
-        run: npm run test:unit
+        run: make frontend-test

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-python-dev dev build preview typecheck frontend-lint frontend-format frontend-format-check frontend-checks frontend-test clean up up down docker-build refresh restart build-serve python-lint python-lint-fix python-format python-format-check python-typecheck python-dead-code python-checks python-test-lint python-test-lint-fix python-test-format python-test-format-check python-test-typecheck python-test-checks python-coverage prek-install
+.PHONY: help install install-ci install-python-dev dev build preview frontend-typecheck frontend-lint frontend-format frontend-format-fix frontend-checks frontend-test clean up down docker-build refresh restart build-serve python-lint python-lint-fix python-format python-format-fix python-typecheck python-dead-code python-checks python-test python-test-cov checks fix
 
 # Frontend directory
 FRONTEND_DIR := src/frontend
@@ -10,34 +10,34 @@ COMPOSE_FILE := docker-compose.dev.yml
 help:
 	@echo "Available targets:"
 	@echo ""
+	@echo "Quality:"
+	@echo "  checks     - Run ALL static analysis checks (frontend + Python)"
+	@echo "  fix        - Auto-fix lint + format issues (frontend + Python)"
+	@echo ""
 	@echo "Frontend:"
 	@echo "  install    - Install frontend dependencies"
 	@echo "  dev        - Start development server"
 	@echo "  build      - Build frontend for production"
 	@echo "  build-serve - Build and serve via Flask (test prod build without Docker)"
 	@echo "  preview    - Preview production build"
-	@echo "  typecheck  - Run TypeScript type checking"
+	@echo "  frontend-typecheck - Run TypeScript type checking"
 	@echo "  frontend-lint - Run Oxlint against frontend code"
-	@echo "  frontend-format - Format frontend code with Oxfmt"
-	@echo "  frontend-format-check - Check frontend formatting with Oxfmt"
+	@echo "  frontend-format - Check frontend formatting with Oxfmt"
+	@echo "  frontend-format-fix - Format frontend code with Oxfmt"
 	@echo "  frontend-checks - Run all frontend static analysis checks"
 	@echo "  frontend-test - Run frontend unit tests"
+	@echo ""
+	@echo "Python:"
 	@echo "  install-python-dev - Sync Python runtime + dev tooling with uv"
-	@echo "  python-lint - Run Ruff against Python backend code"
+	@echo "  python-lint - Run Ruff against Python code (backend + tests)"
 	@echo "  python-lint-fix - Run Ruff with safe auto-fixes"
-	@echo "  python-format - Format Python backend code with Ruff"
-	@echo "  python-format-check - Check Python backend formatting with Ruff"
-	@echo "  python-typecheck - Run BasedPyright against Python backend code"
-	@echo "  python-dead-code - Run Vulture against Python backend code"
+	@echo "  python-format - Check Python formatting with Ruff"
+	@echo "  python-format-fix - Format Python code with Ruff"
+	@echo "  python-typecheck - Run BasedPyright against backend + tests"
+	@echo "  python-dead-code - Run Vulture against backend code"
 	@echo "  python-checks - Run all Python static analysis checks"
-	@echo "  python-test-lint - Run Ruff against Python tests with the relaxed tests profile"
-	@echo "  python-test-lint-fix - Run Ruff with safe auto-fixes against Python tests"
-	@echo "  python-test-format - Format Python tests with Ruff"
-	@echo "  python-test-format-check - Check Python test formatting with Ruff"
-	@echo "  python-test-typecheck - Run lightweight BasedPyright checks against Python tests"
-	@echo "  python-test-checks - Run all relaxed Python test static analysis checks"
-	@echo "  python-coverage - Run tests with coverage report"
-	@echo "  prek-install - Install prek git hooks"
+	@echo "  python-test - Run unit tests"
+	@echo "  python-test-cov - Run unit tests with coverage report"
 	@echo "  clean      - Remove node_modules and build artifacts"
 	@echo ""
 	@echo "Backend (Docker):"
@@ -52,6 +52,10 @@ install:
 	@echo "Installing frontend dependencies..."
 	cd $(FRONTEND_DIR) && npm install
 
+install-ci:
+	@echo "Installing frontend dependencies (CI, lockfile-strict)..."
+	cd $(FRONTEND_DIR) && npm ci
+
 # Install Python development dependencies
 install-python-dev:
 	@echo "Syncing Python runtime and dev tooling with uv..."
@@ -82,89 +86,75 @@ preview:
 	cd $(FRONTEND_DIR) && npm run preview
 
 # Type checking
-typecheck:
+frontend-typecheck:
 	@echo "Running TypeScript type checking..."
 	cd $(FRONTEND_DIR) && npm run typecheck
 
-# Python linting
+# Python linting (backend + tests)
 python-lint:
 	@echo "Running Ruff..."
-	uv run ruff check shelfmark
+	uv run ruff check shelfmark tests
 
 python-lint-fix:
 	@echo "Running Ruff with safe auto-fixes..."
-	uv run ruff check shelfmark --fix
+	uv run ruff check shelfmark tests --fix
 
 python-format:
-	@echo "Formatting Python backend code with Ruff..."
-	uv run ruff format shelfmark
+	@echo "Checking Python formatting with Ruff..."
+	uv run ruff format --check shelfmark tests
 
-python-format-check:
-	@echo "Checking Python backend formatting with Ruff..."
-	uv run ruff format --check shelfmark
+python-format-fix:
+	@echo "Formatting Python code with Ruff..."
+	uv run ruff format shelfmark tests
 
 python-typecheck:
 	@echo "Running BasedPyright..."
 	uv run basedpyright
+	@echo "Running BasedPyright against tests..."
+	uv run basedpyright tests --skipunannotated
 
 python-dead-code:
 	@echo "Running Vulture..."
 	uv run vulture shelfmark
 
-python-checks: python-lint python-format-check python-typecheck python-dead-code
-
-python-test-lint:
-	@echo "Running Ruff against tests with the relaxed tests profile..."
-	uv run ruff check tests
-
-python-test-lint-fix:
-	@echo "Running Ruff with safe auto-fixes against tests..."
-	uv run ruff check tests --fix
+python-checks: python-lint python-format python-typecheck python-dead-code
 
-python-test-format:
-	@echo "Formatting Python tests with Ruff..."
-	uv run ruff format tests
+python-test:
+	@echo "Running tests..."
+	uv run pytest tests/ -x --tb=short -m "not integration and not e2e"
 
-python-test-format-check:
-	@echo "Checking Python test formatting with Ruff..."
-	uv run ruff format --check tests
-
-python-test-typecheck:
-	@echo "Running lightweight BasedPyright checks against tests..."
-	uv run basedpyright tests --skipunannotated
-
-python-test-checks: python-test-lint python-test-format-check python-test-typecheck
-
-python-coverage:
+python-test-cov:
 	@echo "Running tests with coverage..."
 	uv run pytest tests/ -x --tb=short -m "not integration and not e2e" --cov --cov-report=term-missing
 
-prek-install:
-	@echo "Installing prek git hooks..."
-	uv run prek install
-
 # Frontend linting
 frontend-lint:
 	@echo "Running Oxlint..."
 	cd $(FRONTEND_DIR) && npm run lint
 
 # Frontend formatting
 frontend-format:
-	@echo "Formatting frontend code with Oxfmt..."
-	cd $(FRONTEND_DIR) && npm run format
-
-frontend-format-check:
 	@echo "Checking frontend formatting with Oxfmt..."
 	cd $(FRONTEND_DIR) && npm run format:check
 
+frontend-format-fix:
+	@echo "Formatting frontend code with Oxfmt..."
+	cd $(FRONTEND_DIR) && npm run format
+
 # All frontend static analysis
-frontend-checks: frontend-lint frontend-format-check typecheck
+frontend-checks: frontend-lint frontend-format frontend-typecheck
 
 # Run frontend unit tests
 frontend-test:
 	@echo "Running frontend unit tests..."
 	cd $(FRONTEND_DIR) && npm run test:unit
 
+# All static analysis checks (frontend + Python)
+checks: frontend-checks python-checks
+
+# Auto-fix lint + format issues (frontend + Python)
+fix: python-lint-fix python-format-fix frontend-format-fix
+
 # Clean build artifacts and dependencies
 clean:
 	@echo "Cleaning build artifacts and dependencies..."

docs/configuration.md

@@ -18,9 +18,9 @@ Prowlarr -> Download client saves to <client path>
 
 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 Download Volume Setup
 
-Direct downloads do not use an external download client. A simple two-folder setup is enough.
+If you plan to use Direct Download, it does not use an external download client. A simple two-folder setup is enough.
 
 Required volumes: