Skip to content

Latest commit

 

History

History
166 lines (148 loc) · 8.71 KB

AGENTS.md

File metadata and controls

166 lines (148 loc) · 8.71 KB

AGENTS.md

Instructions for AI agents (and humans) working in this repository.

BookFlow is a small self-hosted OPDS server: read-only filesystem → SQLite index → OPDS catalogs, plus on-demand X3/X4 EPUB optimization and multi-user reading progression. The plan is complete (milestones M1–M8 + optional items); expect maintenance, bug fixes, and small features rather than greenfield work.

Commands

uv sync                                   # install deps
uv run ruff check .                       # lint (gate before every commit)
uv run pytest -q                          # full suite: 366 tests
uv run pytest -q tests/test_opds.py       # single file (seconds)
uv run flask --app bookflow.app run --port 8000  # dev server (flask defaults to :5000)
uv run alembic upgrade head               # apply migrations
uv run alembic revision --autogenerate -m "..."
uv run gunicorn --bind 0.0.0.0:8000 bookflow.wsgi:app
docker compose up -d --build          # containerized run (Dockerfile)
# prebuilt image: docker pull ghcr.io/syfq91/bookflow:latest && docker compose up -d
# publish image: Actions → "Publish Docker image to GHCR" (manual, workflow_dispatch)

Verify before committing: uv run ruff check . && uv run pytest -q. Both must pass. Do not commit unless explicitly asked.

Smoke-testing a live server

Tests cover behavior; for end-to-end checks run a detached instance on a scratch data dir:

export OPDS_DATA_DIR=/tmp/bf-smoke OPDS_ADMIN_PASSWORD=smokepass \
       OPDS_DATABASE_URL="sqlite+pysqlite:////tmp/bf-smoke/live.db"
setsid nohup uv run flask --app bookflow.app run --host 127.0.0.1 --port 8767 \
  > /tmp/bf-smoke.log 2>&1 < /dev/null &
# kill later with the regex-bracket trick (plain pkill kills your own shell line):
pkill -f "[f]lask --app bookflow.app run"
  • uv run alembic upgrade head first if the scratch DB is new.
  • Login for admin pages: scrape csrf_token with grep -o 'name="csrf_token" value="[^"]*"' | head -1 (it appears twice per page — forms + meta), then POST /admin/login with a cookie jar.
  • OPDS uses Basic auth: -u admin:<password>.

Code conventions

  • Toolchain: Python ≥3.14, uv, Flask 3, SQLAlchemy 2, Alembic, SQLite. Ruff rules E,F,I,UP,B,C4,SIM,RUF059 (ARG deliberately off — see pyproject.toml), line length 88, target-version = "py314".
  • Style: from __future__ import annotations at the top of every module; type-hint public functions; docstrings on modules/classes/public functions; inline comments are rare — prefer clear code over narration.
  • Config: a frozen Settings dataclass (config.py); never read os.environ outside it. Everything is reachable as current_app.config["SETTINGS"].
  • Database: open sessions only via session_scope() (commit/rollback/ close handled). SQLAlchemy 2 style: Mapped[...]/mapped_column, select() — no legacy Query. Keep sessions short; never hold one across I/O or renders.
  • Web: blueprints only (auth, admin, opds, progression); register new ones in create_app. OPDS errors must be blueprint-scoped (@bp.errorhandler) so admin pages keep HTML error pages — the single app-level HTTPException handler in create_app exists only for routing failures (a failed URL match has no blueprint to dispatch to) and must return every other request unchanged. Every state-changing admin route is automatically CSRF-checked by the blueprint's before_request — views just read the form.
  • Templates: server-rendered Jinja extending layout.html; CSRF token via the global csrf_token(); existing badge/detail/grid CSS classes in static/style.css (add badge-warn-style variants there if needed).
  • Tests: mirror existing files. Fixture chain is settings (conftest, temp dir + DB) → build_app(settings) (conftest factory: runs alembic upgrade head unless migrate=False, resets the engine around each test) → per-suite app → client. A suite that needs another password, browse_root, or an unmigrated app defines its own *_settings / app fixture on top of build_app. Reuse tests/factories.py (make_epub, make_pdf, csrf_token, login_admin, insert_books, alembic_config, feed-parsing helpers) instead of hand-rolling files; seed rows with insert_books(...) when no real file is needed.

Invariants — never break these

  1. The library is read-only. No code may write, rename, or delete anything under a registered folder. All writes go to SQLite and data/cache/.
  2. Optimization is on-demand only. epubkit and cbz2xtc run exclusively inside optimize_book(), reached only from /opdsx3|/opdsx4/download/<id>. Never call them from scanning, startup, routes, or background tasks.
  3. Paths come from the DB, not the URL. book_file() in library/paths.py is the single source of book paths and enforces root containment via resolve() + is_relative_to. Don't construct filesystem paths from user input anywhere else.
  4. Cache is disposable, index must agree. Cache files live at data/cache/optimized/{x3,x4}/<book_id>.{epub,xtc}, written through .tmp/<uuid>.<ext> + Path.replace(), and validated against the optimized_books row (source_mtime, source_size, optimized_size). Writes to file and row happen together; readers treat any mismatch as a miss.
  5. Progression is per (user, book), one row per user per book, shared across original and X3/X4 downloads. Timestamps: accept naive as UTC, serialize with Z and microsecond precision (replays must compare equal).
  6. User credentials stored in DB. Argon2id in SQLite, session auth for /admin (admins only), HTTP Basic for /opds (all users), OPDS 401 body is the Authentication Document. Never log passwords, cookies, or auth headers.
  7. Vendored epubkit & cbz2xtc are third-party code (optimizer/epubkit/ and optimizer/cbz2xtc/, MIT — keep NOTICE, keep the ruff per-file-ignores). Avoid editing them; upstream them separately if the pipelines themselves must change.
  8. Non-goals: no uploads, book delete/rename/move or metadata/cover editing, cloud storage, Calibre/Elasticsearch/Redis/Celery/K8s/ microservices, a separate epubkit HTTP server, background or scheduled optimization, pre-generated X3/X4 files, and no separate progression per device or per optimization profile. Keep the application small.

Known gotchas

  • optimizer/epubkit/ (package) shadows nothing now — do not recreate a sibling optimizer/epubkit.py; Python would silently prefer the package.
  • An app is built only through create_app() (build_app in tests, bookflow.wsgi in production) — never at import time, so no test can write into the repo by importing the package. Don't build one outside the fixture chain: its engine would leak (that's what reset_engine() is for).
  • OPDS feeds paginate at 50; device feeds (/opdsx3, /opdsx4) list the whole library with EPUB acquisitions rewritten per profile and other formats falling back to /opds/download/<id> — keep that fallback when adding formats.
  • Search uses SQL ilike with escaped % _ \ — reuse the existing escaping helper if you touch queries.
  • Flask's default error pages are intentional for /admin; only the OPDS and progression blueprints render structured errors.
  • The session secret is auto-generated and persisted to data/.session_secret when OPDS_SESSION_SECRET is unset (see resolve_session_secret()); the old shared dev literal no longer exists. Never log the file's contents.
  • The only background job is the rescan thread (bookflow/auto_scan.py): one daemon thread per process when OPDS_AUTO_SCAN_INTERVAL > 0 (default 3600, 0/off disables), which just calls scan_folder() for every folder and then prune_orphaned_cache() — never epubkit or cbz2xtc. A cycle takes a non-blocking flock on data/.auto_scan.lock, so gunicorn workers do not scan twice. The shared settings fixture sets the interval to 0, so no test app spawns a thread; suites that want one (tests/test_auto_scan.py) build an auto_app and must stop the scanner in teardown, or it outlives the test and races reset_engine().

Git

  • Direct commits to main, pushed to github.com:syfq91/bookflow.
  • Message style: short imperative summary, optionally scoped (Milestone 6: epubkit integration, Add gunicorn dependency and .env.example).
  • Stage only intended files; run the verify command above first; never commit secrets (test passwords in fixtures are fine — they aren't real).