# AGENTS.md

Purpose: operating guide for agentic coding assistants in this repository.
Scope: setup, build/run/test commands, and code-style conventions.

## Repository Snapshot

- Stack: Python 3.11, FastAPI, SQLAlchemy async, Celery, Redis, Postgres.
- API entrypoint: `services/api_gateway/src/app/main.py`.
- Shared modules: `services/shared/`.
- Worker app: `services/orchestrator/src/app/`.
- Local API runner: `run_server.py` (Windows asyncio fix included).
- Infra orchestration: `docker-compose.yml`.
- UI folder: `webui/` (Playwright dependency present).

## Instruction Overlays (Cursor/Copilot)

Checked:

- `.cursorrules`
- `.cursor/rules/`
- `.github/copilot-instructions.md`

Current status:

- No Cursor rules or Copilot instruction files found.
- If they appear later, treat them as high-priority repo instructions.
- Update this file when rule sources change.

## Setup

### Python Environment

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

Notes:

- `requirements.txt` is UTF-16 encoded.
- Most tools handle it; convert to UTF-8 only if a tool fails.

### Infrastructure Services

```bash
docker compose up --build
docker compose down
```

Equivalent Make targets:

```bash
make up
make down
```

## Build and Run Commands

### API Gateway

```bash
python run_server.py
uvicorn services.api_gateway.src.app.main:app --reload --host 0.0.0.0 --port 8000
make run-api
```

### Celery Worker

```bash
celery -A services.orchestrator.src.app.celery_app.celery_app worker --loglevel=info
make run-celery
```

## Lint, Format, and Type Checking

No committed root config for Ruff, Black, isort, Flake8, or mypy.

Agent expectations:

- Match existing style in touched files.
- Avoid broad reformat-only changes.
- Keep imports tidy and remove unused imports you introduce.
- Keep typing patterns consistent with nearby code.

Safe local sanity check:

```bash
python -m compileall services tests
```

## Test Commands

### Pytest (All / Single)

```bash
python -m pytest tests -q
python -m pytest tests/security/test_verification.py -q
python -m pytest tests/security/test_verification.py::test_generate_token -q
```

### Script-Style Flows Used in This Repo

```bash
python tests/security/test_verification.py
python tests/security/integration_test.py
python tests/security/test_server.py
python tests/security/hosts_manager.py check
```

Notes:

- Some tests require API + DB + Redis running.
- Some flows depend on local hosts/domain setup.
- `integration_test.py` includes interactive/manual steps.

### Playwright (WebUI)

Run from `webui/`:

```bash
npx playwright test
npx playwright test path/to/spec-file.spec.ts
npx playwright test -g "name fragment"
```

## Code Style Guidelines

### Imports

- Group imports: standard library, third-party, local modules.
- Separate groups with one blank line.
- Prefer explicit imports over wildcard imports.

### Formatting

- Match existing formatting in each file.
- Keep functions focused and readable.
- Avoid non-functional whitespace churn.

### Types and Schemas

- Add type hints for new/changed function signatures.
- Use `str | None` unions where consistent.
- Use Pydantic models for FastAPI request/response contracts.
- Use `Field(...)` validation for constrained inputs.

### Naming Conventions

- `snake_case`: variables, functions, modules.
- `PascalCase`: classes, ORM models, Pydantic models.
- `UPPER_SNAKE_CASE`: constants.
- Prefer clear route handler names (`create_project`, `list_tasks`, `start_scan`).

### Async and Database Usage

- Preserve async handlers for IO paths.
- Use `get_db` dependency with `AsyncSession`.
- Commit/refresh intentionally on write flows.
- Roll back session after integrity/database write errors.

### Error Handling and Security

- Use `HTTPException` with explicit status codes.
- Return structured error payloads for client-facing failures.
- Do not swallow exceptions silently.
- Avoid leaking secrets/tokens in error text.
- Treat verification and scan authorization logic as security-critical.
- Preserve ownership/legal-agreement checks and blacklist logic.

## Architecture and Boundaries

- API routes: `services/api_gateway/src/app/routes/`.
- Shared auth/config/db/models: `services/shared/`.
- Worker tasks: `services/orchestrator/src/app/tasks.py`.
- Compose services: Postgres, Redis, API, Celery worker, Flower.

Cross-service change expectations:

- Keep schema/model contracts synchronized.
- Keep diffs minimal and clearly scoped.
- Verify startup and health behavior after edits.

## Agent Change Hygiene

- Do not revert unrelated local/user changes.
- Avoid renaming/moving files unless task requires it.
- Keep changes focused and atomic.
- Note assumptions when full integration testing is not possible.
- Update this file when commands/tooling conventions change.