legado-hub: Instructions file for Codex

AGENTS.md

Repo-specific guidance for OpenCode sessions working in legado-hub. Keep the root clean; see docs/architecture/repository-layout.md for the boundary rules.

Stack

• backend/: FastAPI runtime with a public/reader entrypoint on 8765 and an admin entrypoint on 8766. The deployment entrypoint is python -m app.server; app.main:app is the combined compatibility/test app. Run commands from backend/.
• frontend/: React 19 + Vite + shadcn/ui console. The same built dist is served on both ports, while /api/auth/entrypoint selects the reader-only or administrator login/UI surface. Vite proxies to 8765 by default; set VITE_LEGADOHUB_ENTRYPOINT=admin to proxy to 8766.
• plugins/: source plugins loaded at runtime by app/source_plugins/loader.py, which recursively scans plugins/sources/**/metadata.yaml.

First-time setup / dev run

Docker Compose with the published xzixmn/legado-hub:latest image is the recommended deployment path. start.bat is the Windows source-development bootstrap: it creates .venv, installs backend/requirements.txt, runs python -m playwright install chromium, builds the frontend, then starts uvicorn. Manual equivalent:

python -m venv .venv
.venv/Scripts/python.exe -m pip install -r backend/requirements.txt
.venv/Scripts/python.exe -m playwright install chromium
cd frontend && npm install && npm run build
cd ../backend && ../.venv/Scripts/python.exe -m app.server --host 0.0.0.0 --public-port 8765 --admin-port 8766

On first startup the lifespan handler initializes the SQLite DB at backend/data/app.db, creates admin, and prints a generated high-entropy password once when no password was configured. Explicit passwords are never echoed. The product supports only local or trusted-LAN operation; external tunneling and its network security are operator-owned and do not select an application mode.

Commands

Backend (run from backend/):

• Run server: python -m app.server --host 0.0.0.0 --public-port 8765 --admin-port 8766
• Tests: pytest (config lives in backend/pytest.ini; asyncio_mode = auto)
• Single test: pytest ../dev-assets/tests/test_shared_book_storage.py
• Maintenance scripts: python scripts/create_source_plugin.py, python scripts/validate_source_plugin.py (these are the only scripts that belong in backend/scripts/; put probes/benchmarks in dev-assets/)