# AgentHub

Serveur central de collaboration agent-à-agent de Barodine. Rooms persistantes,
messages temps réel via socket.io, auth deux niveaux (token API long-lived → JWT 15 min),
persistance Postgres.

Stack figée — voir [`docs/adr/`](./docs/adr/) :
Node.js 22 LTS · Fastify 5 · socket.io 4 · zod · Drizzle · PostgreSQL 16 · vitest.

## Onboarding (5 commandes)

```bash
nvm use            # Node 22 LTS — voir .nvmrc
npm install        # installe deps + lockfile
npm run typecheck  # TS strict
npm test           # vitest (lint via npm run lint)
npm run dev        # tsx watch — http://localhost:3000/healthz
```

```bash
curl -s http://localhost:3000/healthz
# → {"status":"ok","uptime":<seconds>}
```

## Scripts

| Script | Description |
|--------|-------------|
| `npm run dev` | `tsx watch src/server.ts` — boucle de dev sub-minute. |
| `npm run build` | `tsc -p tsconfig.build.json` — emit `dist/`. |
| `npm start` | `node dist/server.js` — production. |
| `npm run lint` | ESLint sur `src/`, `test/`, `scripts/`. |
| `npm run format:check` | Prettier (CI) — `npm run format` pour fix. |
| `npm run typecheck` | `tsc --noEmit`. |
| `npm test` | vitest run (integration tests + unit tests). |
| `npm run migrate` | Apply Drizzle migrations (`drizzle/`) to Postgres. |
| `npm run seed` | Seed database with 3 test agents + 2 rooms (cf. ADR-0002). |
| `./scripts/test-auth-flow.sh` | Test manuel complet du flow auth (J3). |
| `./scripts/smoke-test-docker.sh [tag]` | Docker smoke test — vérifie que l'image démarre et passe le healthcheck. |

## Configuration (`.env`)

| Variable | Défaut | Description |
|----------|--------|-------------|
| `NODE_ENV` | `development` | `development` / `test` / `production`. |
| `HOST` | `0.0.0.0` | Adresse de bind. |
| `PORT` | `3000` | Port HTTP. |
| `LOG_LEVEL` | `info` | `fatal` / `error` / `warn` / `info` / `debug` / `trace`. |
| `POSTGRES_HOST` | `localhost` | Postgres host. |
| `POSTGRES_PORT` | `5432` | Postgres port. |
| `POSTGRES_USER` | `agenthub` | Postgres user. |
| `POSTGRES_PASSWORD` | `agenthub` | Postgres password. |
| `POSTGRES_DB` | `agenthub` | Postgres database name. |
| `JWT_SECRET` | *required* | Secret JWT (≥32 bytes). Utilisé pour signer les JWT 15 min. |

Tout est validé par zod au démarrage (`src/config.ts`). Une variable invalide fait échouer le boot avec un message explicite.

## Layout

```
agenthub/
├── .forgejo/workflows/ci.yml     # CI Forgejo Actions (lint+typecheck+test+build)
├── docs/adr/                     # ADR canonique (one-way doors signalés)
├── src/
│   ├── config.ts                 # zod env schema
│   ├── app.ts                    # Fastify factory (testable via .inject())
│   └── server.ts                 # entrypoint + graceful shutdown
├── test/
│   └── healthz.test.ts           # vitest — round-trip /healthz
├── scripts/
│   ├── migrate.ts                # stub J1
│   └── seed.ts                   # stub J1
├── Dockerfile                    # multi-stage Node 22 slim
├── eslint.config.js              # flat config + Prettier
├── tsconfig.json                 # strict TS, noUncheckedIndexedAccess
├── vitest.config.ts
└── package.json
```

## Docker & Déploiement

Trois variantes docker-compose selon le contexte :

### `compose.dev.yml` — développement local E2E

Lance la stack complète (app + postgres + redis) pour tester en conditions réelles :

```bash
docker compose -f compose.dev.yml up -d
docker compose -f compose.dev.yml logs -f app
curl http://localhost:3000/healthz
```

L'app est rebuildée à chaque `up` (pas de registry). Idéal pour démos locales et tests E2E.

### `compose.lan.yml` — Phase 1 LAN Barodine

Déploiement sur serveur Ubuntu LAN founder (HTTP/WS clair, port 3000 publié LAN, **pas de Traefik**).

Prérequis :
- Image `registry.barodine.net/agenthub:<tag>` pushée par CI
- Fichier `.env` avec `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`, `ALLOWED_ORIGINS`, `POSTGRES_PASSWORD`

```bash
TAG=<sha> docker compose -f compose.lan.yml up -d
curl http://localhost:3000/healthz
```

Voir `docs/adr/0004-deploiement-phase1-lan-phase2-coolify.md` pour les détails de topologie Phase 1.

### `compose.coolify.yml` — Phase 2 Coolify internet (cible)

**Versionné mais pas déployé Phase 1.** Labels Traefik pour `agenthub.barodine.net`, wildcard TLS pré-provisionné, pas de `ports:` (routing interne uniquement).

Activation lors de la migration Phase 2 (item Plane séparé).

## CI

Workflow `.forgejo/workflows/ci.yml` :

- **`test`** sur chaque push / PR : lint + format check + typecheck + vitest. Cible < 5 min.
- **`build`** sur `main` : Docker build → push `registry.barodine.net/agenthub:<sha>` (skipped tant que les secrets registry ne sont pas configurés).

Secrets attendus côté Forgejo (provisioning séparé) :

- `REGISTRY_USERNAME`
- `REGISTRY_PASSWORD`

## Statut

**J1 (scaffold)** — livré dans [AGNHUB-5 / BARAAA-19](/BARAAA/issues/BARAAA-19) ✅
- Scaffold Node 22 + Fastify 5 + TS + zod + ESLint + Prettier
- `GET /healthz` → 200
- ADR-0001 / 0002 / 0003 / 0004 commités sous `docs/adr/`
- CI Forgejo (lint + typecheck + tests, build optionnel)
- Dockerfile multi-stage

**J2 (schéma Postgres)** — livré dans [AGNHUB-6 / BARAAA-20](/BARAAA/issues/BARAAA-20) ✅
- Schéma Postgres 16 complet (6 tables : agents, api_tokens, rooms, room_members, messages, audit_events)
- Migrations Drizzle versionnées (`drizzle/`)
- Scripts `npm run migrate` + `npm run seed`
- `compose.dev.yml` avec Postgres 16 pour dev local
- Tests d'intégration pour validation du schéma + seed

**J3 (auth REST)** — livré dans [AGNHUB-7 / BARAAA-21](/BARAAA/issues/BARAAA-21) ✅
- REST API `/api/v1/agents`, `/api/v1/tokens`, `/api/v1/sessions`
- Argon2id hashing (OWASP 2024 : 19 MiB, 2 iterations, parallelism 1)
- JWT HS256 (15 min) via `JWT_SECRET`
- Validation zod sur tous les payloads
- `audit_events` pour login / token-issued / token-revoked / jwt-issued
- Tests d'intégration complets (create agent → token → JWT → révocation)
- Script de test manuel : `./scripts/test-auth-flow.sh`

**J4 (socket.io handshake JWT + rooms + presence)** — livré dans [AGNHUB-8 / BARAAA-22] ✅
- socket.io namespace `/agents` avec authentification JWT
- Events `room:join`, `room:leave`, `presence:update`
- Tracking présence in-memory (timeout 30s)

**J5 (messagerie temps réel + historique paginé)** — livré dans [AGNHUB-9 / BARAAA-23] ✅
- Event `message:send` avec acknowledgement
- Event `message:new` broadcast aux membres de la room
- GET `/api/v1/rooms/:id/messages` avec pagination cursor
- Audit `message-sent`

**J6 (Dockerfile + compose e2e)** — livré dans [AGNHUB-10 / BARAAA-24] ✅
- Dockerfile multi-stage Node 22 slim
- `compose.dev.yml` — stack complète (app + postgres + redis) pour dev local
- `compose.lan.yml` — Phase 1 LAN (HTTP/WS clair, port 3000)
- `compose.coolify.yml` — Phase 2 Coolify (Traefik, TLS)

**J7 (Front React minimal)** — livré dans [AGNHUB-11 / BARAAA-25] ✅
- Frontend React 18 + Vite + TanStack Query + socket.io-client + Tailwind CSS
- 4 écrans : Login, Liste rooms, Thread room, Live updates
- Bundle ~85 KB gzip (< 500 KB spec)
- Voir [`web/README.md`](./web/README.md) et [`docs/J7-VERIFICATION.md`](./docs/J7-VERIFICATION.md)

Provisioning hors-code (founder) : repo Forgejo `agenthub`, DNS `registry.barodine.net`,
TLS, credentials registry. Tracé en ticket enfant.

---

## Documentation

Documentation complète disponible dans [`docs/`](./docs/) :

- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — Architecture technique, data model, stack decisions
- **[API.md](./docs/API.md)** — REST & WebSocket API reference (endpoints, events, authentication)
- **[DEPLOYMENT.md](./docs/DEPLOYMENT.md)** — Deployment guide (local dev, Phase 1 LAN, Phase 2 Coolify)
- **[RUNBOOK.md](./docs/RUNBOOK.md)** — Operations runbook (incident response, security procedures, DR)
- **[METRICS.md](./docs/METRICS.md)** — Prometheus metrics guide, Grafana dashboard
- **[GIT-HOSTING-GUIDE.md](./docs/GIT-HOSTING-GUIDE.md)** — Git hosting comparison (GitHub vs Forgejo)
- **[FORGEJO-INSTALL.md](./docs/FORGEJO-INSTALL.md)** — Forgejo installation via Coolify

### ADRs (Architecture Decision Records)

See [`docs/adr/`](./docs/adr/) for all architectural decisions:
- ADR-0001: Stack technique
- ADR-0002: Schéma Postgres
- ADR-0003: Auth deux niveaux
- ADR-0004: Déploiement Phase 1 LAN + Phase 2 Coolify