commit ee49b82f291455426df9b21f90785633310bf112 Author: mohammad Date: Tue Mar 10 00:02:57 2026 +0300 first commit diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c6321df --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# 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 ` 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`. diff --git a/README-dev.md b/README-dev.md new file mode 100644 index 0000000..bcbbde1 --- /dev/null +++ b/README-dev.md @@ -0,0 +1,61 @@ +## Development Environment Recommendations + +This stack is most maintainable when the dev environment is repeatable and +configuration is centralized. The current scripts assume Ubuntu 16.04 and +hard-coded dependencies. The goal here is to make the environment predictable +without touching the protocol or rewriting core services. + +Key recommendations: + +- Standardize the dev workflow with containers (prefer `docker-compose`). +- Centralize ports, credentials, and paths into a single `.env` file. +- Provide a single entrypoint script to build/start/stop/log services. +- Keep database and service initialization scripted and idempotent. + +## Focused Plan (Maintainability Only) + +Phase 1: Audit and Baseline (1–3 days) + +- Inventory the current scripts and dependencies in `hearthmod/`. +- Confirm service ports and startup order (gameserver → lobbyserver → web). +- Capture required Couchbase buckets and data seed steps. + +Phase 2: Repeatable Local Environment (1–2 weeks) + +- Add `docker-compose.yml` to orchestrate Couchbase, gameserver, lobbyserver, + and web services. +- Add `.env.example` for all required configuration values. +- Create a single `./dev` or `./scripts/dev.sh` entrypoint: + - `dev build` (build C services and web assets) + - `dev up` (start all services) + - `dev down` (stop services) + - `dev logs` (tail logs) + +Phase 3: Configuration Cleanup (1–2 weeks) + +- Replace hard-coded ports and credentials with env-configured values. +- Add a minimal config loader in `hm_web` and in C servers (config file or env). +- Update nginx config to use env-substituted paths. + +Phase 4: Minimal Tests + Docs (1 week) + +- Add a simple smoke test script that validates service ports and Couchbase + connectivity. +- Document the workflow in `README-dev.md` and update top-level README with a + pointer. + +## Deliverables Checklist + +- `docker-compose.yml` with defined services and volumes +- `.env.example` with required config variables +- A single dev entrypoint script +- Updated docs (this file) and a quick-start section + +## Non-Goals (Intentionally Deferred) + +- Updating Hearthstone protocol compatibility +- Rewriting the database or switching away from Couchbase +- Migrating C services to a different language + +If you want, I can start by drafting the `docker-compose.yml` and a `dev` script +tailored to the current repo layout. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..843f965 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,88 @@ +version: "3.8" + +services: + couchbase: + image: ${COUCHBASE_IMAGE:-couchbase:community-6.6.0} + env_file: .env + ports: + - "8091-8096:8091-8096" + - "11210:11210" + volumes: + - couchbase_data:/opt/couchbase/var + + gameserver: + build: + context: . + dockerfile: docker/Dockerfile.gameserver + env_file: .env + depends_on: + - couchbase + ports: + - "3724:3724" + volumes: + - ./hm_gameserver:/workspace/hm_gameserver + - ./hm_base:/workspace/hm_base + - ./hm_database:/workspace/hm_database + - ./hm_log:/workspace/hm_log + working_dir: /workspace + command: ["./hm_gameserver/hm_gameserver", "--log=/workspace/hm_log/hm_gameserver.log"] + + lobbyserver: + build: + context: . + dockerfile: docker/Dockerfile.lobbyserver + env_file: .env + depends_on: + - couchbase + - gameserver + ports: + - "45678:45678" + volumes: + - ./hm_lobbyserver:/workspace/hm_lobbyserver + - ./hm_base:/workspace/hm_base + - ./hm_database:/workspace/hm_database + - ./hm_log:/workspace/hm_log + working_dir: /workspace + command: + - "./hm_lobbyserver/hm_lobbyserver" + - "--gameserver=gameserver" + - "--log=/workspace/hm_log/hm_lobbyserver.log" + + sunwell: + build: + context: ./hm_sunwell + dockerfile: docker/Dockerfile.sunwell + env_file: .env + ports: + - "3000:3000" + + web: + build: + context: ./hm_web + dockerfile: docker/Dockerfile.web + env_file: .env + depends_on: + - couchbase + - sunwell + ports: + - "9002:9002" + volumes: + - ./hm_web:/workspace/hm_web + - ./hm_sunwell:/workspace/hm_sunwell + working_dir: /workspace/hm_web + command: ["python", "app.py"] + + nginx: + build: + context: ./hm_nginx + dockerfile: docker/Dockerfile.nginx + env_file: .env + depends_on: + - web + ports: + - "8080:80" + volumes: + - ./hm_web/static:/usr/local/web/static:ro + +volumes: + couchbase_data: diff --git a/hearthmod b/hearthmod new file mode 160000 index 0000000..a15949d --- /dev/null +++ b/hearthmod @@ -0,0 +1 @@ +Subproject commit a15949d603c9aaa1b4c9e9786c91faadc7fc4367 diff --git a/hm_base b/hm_base new file mode 160000 index 0000000..48079d6 --- /dev/null +++ b/hm_base @@ -0,0 +1 @@ +Subproject commit 48079d6c7454f0051e9de8acff02aefa6d09ebfa diff --git a/hm_client b/hm_client new file mode 160000 index 0000000..e4a2c8b --- /dev/null +++ b/hm_client @@ -0,0 +1 @@ +Subproject commit e4a2c8baac7c25e6911ac42d199b17f8d7e59279 diff --git a/hm_database b/hm_database new file mode 160000 index 0000000..8f07d16 --- /dev/null +++ b/hm_database @@ -0,0 +1 @@ +Subproject commit 8f07d16612ded7787f1a2646525cc304c4bf5425 diff --git a/hm_gameserver b/hm_gameserver new file mode 160000 index 0000000..4bf34a2 --- /dev/null +++ b/hm_gameserver @@ -0,0 +1 @@ +Subproject commit 4bf34a228b85dc369091f073f72572a50133d0d9 diff --git a/hm_lobbyserver b/hm_lobbyserver new file mode 160000 index 0000000..6537d99 --- /dev/null +++ b/hm_lobbyserver @@ -0,0 +1 @@ +Subproject commit 6537d9989a76a02f7270006f14279ceb89244219 diff --git a/hm_nginx b/hm_nginx new file mode 160000 index 0000000..8fac308 --- /dev/null +++ b/hm_nginx @@ -0,0 +1 @@ +Subproject commit 8fac3084e2acfb21d8c7974236f6190f7325a3e9 diff --git a/hm_stud b/hm_stud new file mode 160000 index 0000000..5ef075e --- /dev/null +++ b/hm_stud @@ -0,0 +1 @@ +Subproject commit 5ef075eda22d712c7fbf910593cab1d6c835efa6 diff --git a/hm_sunwell b/hm_sunwell new file mode 160000 index 0000000..8d9f22c --- /dev/null +++ b/hm_sunwell @@ -0,0 +1 @@ +Subproject commit 8d9f22cdb28df16380cc50021cf6af3468757d59 diff --git a/hm_web b/hm_web new file mode 160000 index 0000000..a198222 --- /dev/null +++ b/hm_web @@ -0,0 +1 @@ +Subproject commit a198222e7ca24cccca18942744f24038fae2a107