Supervisor/README.md

Supervisor Prototype

Supervisor je prvý funkčný prototyp ako jedna Go aplikácia s embednutým Vue frontendom.

Čo projekt robí

• spúšťa paralelné externé konzolové procesy v PTY session
• session bežia ďalej nezávisle od pripojeného browsera
• streamuje live terminál výstup cez WebSocket
• prijíma input z klávesnice (xterm.js) aj programový input cez HTTP API
• drží metadata a scrollback output v in-memory store
• podporuje odstránenie ukončených session (status stopped, exited, error)

Architektúra

• cmd/supervisor/main.go: entrypoint
• internal/app: zostavenie aplikácie, wiring komponentov
• internal/httpserver: čistý net/http router, middleware, API + WS handlery
• internal/session: PTY procesy, lifecycle session, output buffer, subscribe mechanizmus
• internal/store/memory: in-memory persistencia metadata session
• internal/supervisor: skeleton orchestration vrstvy pre budúce supervisor/worker rozšírenie
• web/: samostatný Vue 3 + Vite frontend
• internal/static: embedded statické assets servované zo zabudovaného FS

API endpointy

• GET /healthz
• GET /api/sessions
• POST /api/sessions
• GET /api/sessions/{id}
• POST /api/sessions/{id}/input
• POST /api/sessions/{id}/stop
• DELETE /api/sessions/{id}
• GET /ws/sessions/{id}

Poznámka k mazaniu:

• bežiacu session (running) nie je možné odstrániť (409 Conflict)
• neexistujúca session vracia 404
• úspešné odstránenie vracia 204 No Content

Session model

Každá session obsahuje:

• id
• name
• agentId
• command
• status
• createdAt
• startedAt
• exitedAt
• exitCode

WebSocket protokol

JSON envelope:

{
  "type": "terminal.input | terminal.output | terminal.resize | session.status | error",
  "session": "session-id",
  "payload": {}
}

Použité payloady:

• terminal.input: { "data": "..." }
• terminal.output: { "data": "..." }
• terminal.resize: { "cols": 120, "rows": 30 }
• session.status: { "status": "running", "exitCode": null }
• error: { "message": "..." }

Frontend poznámky

• layout má globálny reset okrajov (body { margin: 0; })
• v sidebare je pri ukončených session tlačidlo Remove
• pri odstránení aktuálne otvorenej session UI presmeruje na dashboard

Build

Predpoklady:

• Go (1.23+)
• Node.js + npm

Frontend build do web/dist a následne sa skopíruje do internal/static/dist pre go:embed.

make frontend-build
make backend-build
make build

Spustenie

make run

alebo:

./bin/supervisor

Default adresa: :8080.

Konfigurácia:

• SUPERVISOR_ADDR (napr. :9090)

Budúce rozšírenie

Štruktúra je pripravená na doplnenie:

• supervisor orchestration manager
• worker agents
• workflow runs
• audit log
• persistent store (DB)