2.5 KiB
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, with the bundled output committed as 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: compilebin/webterm.go run ./cmd/webterm: start the server locally onhttp://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. Keep generated bundles in sync with 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.
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.