github_release_monitor/AGENTS.md

AGENTS.md

Project Structure

• src/ — All application code (no subpackages)
  • cli.py — Entry point, argparse CLI with subcommands: add, remove, update, list, check, serve, daemon
  • github.py — GitHub REST API client (httpx), rate-limit aware, exponential backoff
  • db.py — SQLite layer with 0600 file permissions, upsert with UNIQUE(repo_id, tag_name)
  • rss.py — RSS 2.0 generation via xml.etree, markdown→plain text via markdown+bleach, 300-char truncation, 50-item cap
  • server.py — ThreadingHTTPServer with /feed.xml, /, /health endpoints
  • config.py — Centralized config (db_path, gh_token, defaults)
• tests/ — pytest test suite, 72 tests total

Commands

# Install for development
pip install -e ".[test]"

# Run all tests (use timeout to avoid server test hangs)
timeout 30 python3 -m pytest tests/ -q

# Run single test file
python3 -m pytest tests/test_db.py -v

# Run single test
python3 -m pytest tests/test_db.py::TestCreateTables::test_tables_exist -v

Testing Quirks

• respx is used to mock GitHub API calls in test_github.py
• Integration tests in test_integration.py use urllib for localhost requests to avoid respx interception
• Server tests spawn ThreadingHTTPServer — use timeout 30 for full test suite to avoid hangs

Key Gotchas

• --base-url flag on serve command auto-appends port from --port (user only specifies hostname)
• Tag date resolution uses commit SHA from tags API + commits/{sha} endpoint (works without auth for public repos)
• Database uses ON DELETE CASCADE — removing a repo deletes its entries
• src package requires [tool.setuptools.packages.find] in pyproject.toml for proper installation

Environment

• GH_TOKEN — GitHub token for API access (validate on startup if provided)
• GDB_REL_DB — Override database path (default: ~/.local/share/ghrel/ghrel.db)