first commit

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 <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`.

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.

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: