From 7dec819a3bb56cc05a9d1b673fb7263addc58c59 Mon Sep 17 00:00:00 2001 From: Space-Banane Date: Fri, 22 May 2026 19:34:52 +0200 Subject: [PATCH] docs: add AGENTS.md contributor guide --- AGENTS.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..88c499d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,172 @@ +# AGENTS.md + +Guidance for autonomous/code-assist agents working in this repository. + +## Mission + +Build and maintain a webhook-driven Gitea PR review bot that: + +1. verifies webhook authenticity, +2. parses `@codex` commands, +3. queues and executes review jobs, +4. posts/updates PR comments with structured findings. + +Primary implementation lives under `src/gitea_codex_bot`. + +## Tech Stack + +- Python `>=3.11` +- FastAPI + Uvicorn +- SQLAlchemy + Alembic +- MariaDB (default), SQLite possible via `DATABASE_URL` +- Pytest for tests +- Docker-based review runner with host fallback + +## Repository Map + +- `src/gitea_codex_bot/main.py` + - FastAPI app, `/healthz`, `/webhook/gitea`, lifespan worker boot. +- `src/gitea_codex_bot/config.py` + - Environment-backed settings and DB URL composition. +- `src/gitea_codex_bot/db.py` + - Engine/session factory and dependency session provider. +- `src/gitea_codex_bot/models.py` + - ORM models: `WebhookEvent`, `ReviewJob`, `ReviewRun`, `BotComment`. +- `src/gitea_codex_bot/services/commands.py` + - `@codex` command parsing. +- `src/gitea_codex_bot/services/jobs.py` + - Event dedupe, queue transitions, cooldown logic. +- `src/gitea_codex_bot/services/security.py` + - HMAC signature verification and payload digest. +- `src/gitea_codex_bot/services/gitea.py` + - Gitea API client wrapper. +- `src/gitea_codex_bot/services/reviewer.py` + - PR checkout/diff collection/prompt build/OpenAI call/fallback/fix helpers. +- `src/gitea_codex_bot/services/review_format.py` + - Outbound comment formatting. +- `src/gitea_codex_bot/services/comments.py` + - Persistent summary comment id tracking. +- `src/gitea_codex_bot/workers/dispatcher.py` + - Job polling and orchestration. +- `src/gitea_codex_bot/workers/container_runner.py` + - Docker review execution + fallback. +- `alembic/` + `alembic.ini` + - Database migrations. +- `tests/` + - Unit/integration-ish tests across config/security/jobs/webhook/migrations. +- `.gitea/workflows/ci.yml` + - CI test + publish workflow. + +## Runtime Flow + +1. Gitea sends webhook to `POST /webhook/gitea`. +2. Signature is validated (`X-Gitea-Signature`, sha256 HMAC). +3. Non-supported events are ignored. +4. PR context and command are extracted. +5. Repo allowlist and dedupe checks run. +6. Job is enqueued (`review_jobs`). +7. Background worker claims queued jobs. +8. For review/rerun: + - fetch PR context, + - run review in ephemeral container if possible, + - fallback to host execution on failure, + - post or edit persistent PR summary comment. +9. Job/run status transitions are persisted. + +## Supported Commands + +- `@codex review [security|performance|tests] [--full]` +- `@codex rerun` +- `@codex explain` +- `@codex fix [--branch ...]` (gated by `ENABLE_FIX_COMMANDS`) +- `@codex ignore` + +## Local Development + +Install and run: + +```bash +python -m pip install -e .[dev] +alembic upgrade head +uvicorn gitea_codex_bot.main:app --host 0.0.0.0 --port 8000 +``` + +Run tests: + +```bash +pytest +``` + +Docker compose: + +```bash +docker compose up --build +``` + +## Environment Contract + +Required: + +- `GITEA_BASE_URL` +- `GITEA_TOKEN` +- `GITEA_BOT_USERNAME` +- `GITEA_WEBHOOK_SECRET` +- `OPENAI_API_KEY` +- `ALLOWED_REPOS` +- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` + +Common optional: + +- `DATABASE_URL` (overrides DB parts) +- `OPENAI_PROJECT_ID`, `OPENAI_ORG_ID` +- `OPENAI_REVIEW_MODEL` +- `OPENAI_REASONING_EFFORT` +- `WORKDIR`, `MAX_DIFF_BYTES`, `MAX_REVIEW_MINUTES`, `CONCURRENCY` +- `REVIEW_RUNNER_IMAGE` +- `ENABLE_FIX_COMMANDS` +- `ALLOW_UNTRUSTED_FORKS` + +## Database and Migrations + +- SQLAlchemy models are authoritative for runtime behavior. +- Alembic migrations in `alembic/versions` must track schema changes. +- If model schema changes, add a migration and keep migration tests passing. +- CI runs `alembic upgrade head` before pytest. + +## Testing Expectations + +Before opening/merging changes: + +1. run `pytest`, +2. if DB/model changes were made, ensure migration test still passes, +3. for webhook/queue logic, add or update focused tests in `tests/`. + +Current tests rely on `tests/conftest.py` to inject default env and DB URL behavior. + +## Change Guardrails + +- Preserve webhook security checks and allowlist semantics. +- Preserve dedupe constraints (`delivery_id`, `repo+comment_id`, `repo+trigger_comment_id`). +- Keep bot self-comment ignore behavior. +- Keep persistent comment update behavior (avoid comment spam regressions). +- Be explicit when changing runner isolation/fallback behavior; this is a security-sensitive area. +- Keep response payloads and command parsing backward compatible unless intentionally versioned. + +## Known Risks / Active Gaps + +See `TODO.md` for priority backlog, especially: + +- stronger isolated runner flow, +- stricter host fallback controls, +- end-to-end integration coverage. + +Treat these as high-sensitivity areas when modifying worker/runner paths. + +## Recommended Workflow for Agents + +1. Read touched service + corresponding tests first. +2. Make minimal cohesive changes. +3. Add/update tests with behavior changes. +4. Run `pytest`. +5. Summarize impact, risks, and follow-ups in PR/commit notes. +