Repository Guidelines

Project Structure & Module Organization

cmd/supervisor/: Go entrypoint (main.go) for the single executable.
internal/: backend application code.
internal/httpserver/: HTTP routes, middleware, REST and WebSocket handlers.
internal/session/: PTY process runtime, session lifecycle, buffering, and manager logic.
internal/static/: embedded frontend assets (go:embed serves internal/static/dist).
web/: Vue 3 + TypeScript frontend (Vite, Pinia, Vue Router, xterm).
scripts/: build helpers for frontend and full build pipeline.
bin/: compiled artifacts (generated).

make frontend-build: installs web dependencies, runs Vite production build, copies web/dist to internal/static/dist.
make backend-build: builds Go binary at bin/supervisor.
make build: full build (frontend + backend).
make run: builds everything and starts the app.
cd web && npm run dev: frontend dev server with proxy to backend (:8080).
go test ./...: run backend unit tests (when tests are present).

Do not edit internal/static/dist by hand; it is generated from web/dist by make frontend-build.

Go: format with gofmt; package names lowercase; exported symbols in CamelCase; errors as err with wrapped context.
Vue/TS: components in PascalCase.vue, stores and API modules in camelCase.ts.
Keep handlers thin: validation + transport only; put lifecycle/process logic in internal/session.
Prefer explicit JSON DTOs over ad-hoc maps except small error responses.
Keep session state rules centralized in internal/session/manager.go (example: only non-running sessions can be deleted).

Backend tests use Go’s standard testing package.
Place tests alongside code as *_test.go (example: internal/session/manager_test.go).
Prioritize tests for session lifecycle (create/start/input/resize/stop) and WebSocket message handling.
Frontend automated tests are not configured yet; if added, keep them under web/src/**/__tests__.

Existing history uses short, direct commit messages (often imperative). Keep subject concise, one logical change per commit.
Recommended pattern: area: action (example: session: handle resize messages).
PRs should include a summary of behavior changes.
List impacted paths and manual verification commands.
Add screenshots/GIFs for UI changes.
Link the related issue/task when available.

Default bind is :8080; override with SUPERVISOR_ADDR.
Do not commit secrets or environment-specific credentials.
PTY commands are user-supplied; keep future changes mindful of command execution risk.
Session deletion endpoint is DELETE /api/sessions/{id}; preserve current API semantics (409 for running sessions, 204 on success).