hsmod/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• hearthmod/ contains orchestration scripts (host_ctl_ubuntu.sh, docker_ctl.sh) and legacy Docker setup.
• Core C services live in hm_gameserver/, hm_lobbyserver/, and shared code in hm_base/.
• Web UI is in hm_web/ (Python web.py, templates, and static assets).
• Card rendering and assets are in hm_sunwell/ (Node-based renderer).
• TLS proxy and web server components live in hm_stud/ and hm_nginx/.
• Database snapshot and seed data are in hm_database/.

Long-term maintainability should focus on repeatable local environments and centralized configuration. See README-dev.md for the current plan.

Build, Test, and Development Commands

• make -C hm_base target=game builds the shared base library for the gameserver.
• make -C hm_gameserver builds the gameserver binary.
• make -C hm_lobbyserver builds the lobbyserver binary.
• bash hearthmod/host_ctl_ubuntu.sh start <ip> starts the stack (legacy flow).
• bash hearthmod/host_ctl_ubuntu.sh build runs the full build, including client/web assets.

Current priority is a stable dev environment. Prefer adding a unified dev script or docker-compose workflow over expanding the legacy scripts.

Coding Style & Naming Conventions

• C code uses 4-space indentation and snake_case for functions and variables.
• Python uses 4-space indentation; prefer explicit names over abbreviations.
• Avoid one-letter variable names unless used as simple loop counters.
• Keep config constants centralized; avoid embedding ports/paths inline.
• New config values should be documented in README-dev.md and .env.example.

Testing Guidelines

• There is no dedicated test suite currently.
• If you introduce tests, keep them close to the component (e.g., hm_web/tests/).
• Prefer simple smoke tests (service port checks, Couchbase connectivity) that validate the dev environment.

Commit & Pull Request Guidelines

• Git history is not available in this workspace, so no commit convention is enforced.
• For new work, use concise imperative messages (e.g., “Add dev config loader”).
• Pull requests should include a short summary, testing notes, and any config changes.
• If the change impacts the dev environment, update README-dev.md in the same PR.

Security & Configuration Tips

• Couchbase credentials and ports are hard-coded in places; prefer .env or config files.
• hm_stud is abandonware; avoid deploying it to production without replacement.
• When adding config, document defaults and provide an .env.example.