47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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`)
|