gatus Agent Skills & AI Rules

# AGENTS.md

Guidance for AI coding agents working in this repository.

## Commands

- `make install` — Build the `gatus` binary
- `make run` — Run in dev mode (uses `./config.yaml`)
- `make test` — Run all Go tests with coverage
- `make clean` — Remove built binary
- `make frontend-install` — Install frontend npm dependencies
- `make frontend-build` — Build the Vue.js frontend (**must run after any `web/` changes**)
- `make frontend-dev` — Start the Vue dev server

## Key Rules

- **Vendored dependencies**: After adding/updating a Go dependency, run `go mod tidy && go mod vendor`
- **Frontend build artifacts**: `web/static/` is generated by `make frontend-build` and embedded into the Go binary at compile time via `//go:embed`. Never edit files in `web/static/` directly
- **Config validation order**: In `config/config.go` `parseAndValidateConfigBytes`, `ValidateAlertingConfig` **must** run before `ValidateEndpointsConfig` because provider default alerts must be parsed before endpoint defaults are set
- **Invalid configs panic at startup** — validation errors are fatal, not graceful
- **Hot-reload**: `main.go` watches the config file and re-runs the full stop → save → load → init → start cycle. New startup logic must account for this

## Environment Variables

- `GATUS_CONFIG_PATH` — Config file path (default: `config/config.yaml`); can be a directory of YAML files (deep-merged)
- `GATUS_LOG_LEVEL` — `DEBUG`, `INFO`, `WARN`, `ERROR`
- `ENVIRONMENT=dev` — Enables CORS for frontend dev on `localhost:8081`

## Project Structure

- `main.go` — Entry point; loads config, initializes storage, starts watchdog + API server
- `config/` — Central config struct (`config.go`) and sub-packages per config section (each with `ValidateAndSetDefaults()`)
- `alerting/` — Alerting config (`config.go`), alert types (`alert/type.go`), and one sub-package per provider under `provider/`
- `api/` — Fiber-based HTTP API routes and SPA serving
- `watchdog/` — Monitoring loop; spawns a goroutine per endpoint with semaphore-based concurrency control
- `client/` — HTTP/gRPC client used for health checks
- `storage/store/` — Storage abstraction with `memory/`, `sql/` (SQLite + PostgreSQL) implementations
- `security/` — Authentication (basic + OIDC) and security middleware
- `web/app/` — Vue 3 frontend source; builds to `web/static/` (embedded into the Go binary)
- `vendor/` — Vendored Go dependencies (committed to repo)

## Common Changes

### Adding an Alerting Provider

Use `alerting/provider/slack/` as the reference implementation. Every new provider touches **6 locations**:

1. **Create provider package** — `alerting/provider/{name}/{name}.go` + `{name}_test.go`
   - `Config` struct with `Validate()` and `Merge(*Config)` methods
   - `AlertProvider` struct with `DefaultConfig` (yaml inline), `DefaultAlert *alert.Alert`, `Overrides []Override`
   - Use `client.GetHTTPClient(nil)` (not `http.DefaultClient`), always `defer response.Body.Close()`
2. **Register type** — Add `Type{Name} Type = "{name}"` in `alerting/alert/type.go`
3. **Add to config struct** — Add field to `alerting.Config` in `alerting/config.go`; the **YAML tag must exactly match** the `alert.Type` string (reflection-based lookup via `GetAlertingProviderByAlertType`)
4. **Add compile-time checks** — Both `_ AlertProvider = (*pkg.AlertProvider)(nil)` **and** `_ Config[pkg.Config] = (*pkg.Config)(nil)` in `alerting/provider/provider.go`
5. **Register in validation** — Add the type to the `alertTypes` slice in `config/config.go` `ValidateAlertingConfig`
6. **Document** — Add to README.md in alphabetical order

### Adding a Config Section

1. Create package in `config/` with struct + `ValidateAndSetDefaults()` method
2. Add field to `Config` struct in `config/config.go`
3. Add `Validate*` call in `parseAndValidateConfigBytes` — **respect ordering constraints** (see comments in that function)

## Frontend

- Vue 3 Composition API (`<script setup>`) + Tailwind CSS
- Props-based data flow — **do not use provide/inject**
- All components must include `dark:` prefixed Tailwind classes for dark mode
- `window.config` contains server-injected UI settings (Go template placeholders)

## API Routes (`api/api.go`)

- Unprotected routes are registered **before** `ApplySecurityMiddleware`
- Protected routes are registered **after** — placement order matters

## Testing

- Config structs should have `*_test.go` files
- Use `t.Parallel()` where appropriate
- API tests spin up test servers (see existing `*_test.go` in `api/`)

## Commits & PRs

When creating a commit or PR as an agent, state that it was made by an agent and include your model name and version.