49 lines
2.9 KiB
Markdown
49 lines
2.9 KiB
Markdown
# 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).
|