38 lines
2.8 KiB
Markdown
38 lines
2.8 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
`cmd/webterm/` contains the CLI entrypoint. Core server, session, Docker, replay, screenshot, and static-serving code lives in `webterm/`. Shared internal helpers live in `internal/`. Frontend terminal code is in `webterm/static/js/terminal.ts`, which bundles to generated output at `webterm/static/js/terminal.js`. Static assets such as fonts, icons, and WASM files live under `webterm/static/`. Documentation and reference media live in `docs/`.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `make install-dev`: install Go and frontend dependencies.
|
|
- `make build`: typecheck and bundle frontend assets.
|
|
- `make build-fast`: rebuild frontend without TypeScript checking.
|
|
- `make build-go`: compile `bin/webterm`.
|
|
- `go run ./cmd/webterm`: start the server locally on `http://localhost:8080`.
|
|
- `make test`: run all Go tests.
|
|
- `make race`: run Go tests with the race detector.
|
|
- `make check`: run lint, tests, and coverage.
|
|
- `./update.sh`: rebuild, install, and restart the user service.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use `gofmt` for Go formatting; run `make format` before submitting Go-heavy changes. Follow existing Go naming: exported identifiers use `CamelCase`, internal helpers use `camelCase`, and tests live beside source files. TypeScript in `webterm/static/js/` uses strict mode, 2-space indentation, and direct DOM-oriented code rather than framework abstractions. Rebuild generated bundles when frontend source changes.
|
|
|
|
## Testing Guidelines
|
|
|
|
Go tests use the standard `testing` package. Name tests `TestXxx` and fuzz tests `FuzzXxx`; keep them next to the code they validate. Prefer focused unit tests for `webterm/` and `internal/` changes. Run `make test` for normal work and `make check` before opening a PR. Frontend changes should at minimum pass `bun run typecheck` via `make build`.
|
|
|
|
## Debugging Rule
|
|
|
|
Before making a second patch for the same bug, identify the exact callsite that causes the side effect. Trace the real owner of the behavior end-to-end, including library or dependency code when needed, instead of only patching app-level symptoms.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Recent history uses short imperative subjects, sometimes with prefixes such as `feat:`, `fix:`, and `deps:`. Keep commits focused, e.g. `fix: restore websocket reconnect on hidden-tab resume`. PRs should explain user-visible behavior, note test coverage, and include screenshots or recordings for terminal/UI changes. Link related issues when applicable.
|
|
|
|
## Security & Configuration Tips
|
|
|
|
By default, the service binds to port `8080`; review `~/.config/systemd/user/webterm.service` before exposing it remotely. Use HTTPS for browser microphone features. Static assets are embedded by default, but `WEBTERM_STATIC_PATH` can override them in development.
|