# forgebot

K8s operator + API for AI agent dispatch from git forges.

## Architecture

- **API server** (`cmd/api`) — REST API backed by PostgreSQL. Receives webhooks from Gitea, manages task lifecycle, and orchestrates the review workflow.
- **Operator** (`cmd/operator`) — Kubernetes controller that watches for pending tasks, creates Jobs via AgentPool/AgentTask CRDs, and reports completion back to the API.
- **TUI** (`cmd/tui`) — Terminal kanban board for viewing and managing tasks.

## Task Lifecycle

Tasks follow a kanban workflow with automated review:

```
                    +-----------+
                    |   Todo    |
                    +-----+-----+
                          |
                   agent picks up
                          |
                    +-----v-------+
                    | In Progress |
                    +-----+-------+
                          |
                   agent completes
                          |
              +-----------+-----------+
              |                       |
        auto-create               error?
        review task            back to Todo
              |
        +-----v------+
        |  In Review  |<-----+
        +-----+------+      |
              |              |
       human decision    reviewer
              |          suggests
         +----+----+    changes
         |         |        |
    +----v--+  +---v----+   |
    | Done  |  | Wontdo |   |
    +-------+  +--------+   |
                             |
              (new fix task in Todo)
```

Only humans can move tasks from In Review to Done/Wontdo.

## Quick Start

### API Server

```bash
export DBHOST=localhost DBUSER=forgebot DBPASS=secret DBNAME=forgebot
export GITEA_URL=https://git.unkin.net GITEA_TOKEN=<token>
make build
./bin/forgebot-api
```

### Operator

```bash
./bin/forgebot-operator --api-url http://forgebot-api:8000
# or
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-operator
```

### TUI

```bash
./bin/forgebot-tui -api http://localhost:8000
# or
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-tui
```

#### TUI Key Bindings

| Key | Action |
|-----|--------|
| `h`/`l` or arrows | Move between columns |
| `j`/`k` or arrows | Move within column |
| `Enter` | Task detail view |
| `e` | Edit task in $EDITOR |
| `n` | Create new task |
| `d` | Mark done (in review only) |
| `w` | Mark wontdo (in review only) |
| `r` | Refresh |
| `/` | Filter by repository |
| `?` | Toggle help |
| `q` | Quit |

## API

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check |
| `GET` | `/api/v1/tasks` | List tasks (`?status=`, `?repository=`) |
| `POST` | `/api/v1/tasks` | Create task |
| `GET` | `/api/v1/tasks/{id}` | Get task |
| `PATCH` | `/api/v1/tasks/{id}` | Update task status |
| `POST` | `/api/v1/tasks/{id}/complete` | Agent completion callback (triggers review workflow) |
| `POST` | `/api/v1/tasks/{id}/comment` | Post comment to forge |
| `POST` | `/api/v1/webhook/gitea` | Gitea webhook receiver |

## CRDs

- **AgentPool** — Configuration for a pool of AI agents (model, concurrency, image, resources)
- **AgentTask** — A task dispatched to a pool for execution
- **ProviderQueue** — Polls the API for pending tasks and creates AgentTask CRs
- **RepositoryBinding** — Links a repository to a queue and pool with access controls

## Building

```bash
make build          # all binaries to bin/
make test           # run tests
make lint           # go vet
make fmt            # gofmt
make generate       # regenerate CRDs and RBAC
make docker-api     # build API container image
make docker-operator # build operator container image
```