# 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).

## Build, Test, and Development Commands
- `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`.

## Coding Style & Naming Conventions
- 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).

## Testing Guidelines
- 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__`.

## Commit & Pull Request Guidelines
- 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.

## Security & Configuration Tips
- 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).