feat(client): DEBUG-only harness to pilot the client (socket + screenshots) #123

Merged

marco merged 1 commit from feat/debug-harness into main

2026-07-22 06:00:56 +02:00

marco commented

2026-07-21 23:39:45 +02:00

Owner

Summary

A DEBUG-only control channel so a shell or script (and the assistant) can pilot the running client and capture screenshots to attach to PRs — closes #122. A loopback TCP server (127.0.0.1:5199, newline-delimited, request→response) compiled only under #if DEBUG, so a Release build has no socket and no debug types. It injects the same intents a human sends (MoveRequest, Say, …) or synthetic input the real UI reacts to (click / drag / keys) — never fabricating server state, so the server validates everything as usual. Built on a ClientApi facade (query visible state + issue intents), the seam a future in-game scripting host (Lua) will reuse.

Commands: login, goto, move, say, open <admin|bag|doll>, click, rightclick, drag, type, key, screenshot, status, help. See docs/debug-harness.md.

Screenshots / recording

Captured by the harness itself, piloting the client — the deliverable dogfooding its own job:
login debug → open admin → screenshot, then click 130 135 (first command card) → screenshot:

Admin panel opened + captured via the harness:

Clicking the first card prefills /clearbag into the chat (synthetic click):

How it was tested

DebugCommand parser unit-tested (Client.Core, 7 cases).
Drove it end-to-end against just dev: login debug (reaches in-world), open admin (panel opens), click 130 135 (prefills /clearbag into chat), screenshot (writes a valid 1280×720 PNG) — all OK.
Verified a Release build contains no Automation types / no socket.

Checklist

just lint passes (CSharpier + analyzers, zero warnings)
just test is green
The whole solution builds (client and tools included)
Multi-platform preserved (pure .NET / MonoGame, loopback socket; no OS-specific APIs)
Tests added/updated for this change (DebugCommandTests)
Linked the related issue (#122) and its Definition of Done is met

## Summary A **DEBUG-only** control channel so a shell or script (and the assistant) can pilot the running client and capture screenshots to attach to PRs — closes #122. A loopback TCP server (`127.0.0.1:5199`, newline-delimited, request→response) compiled only under `#if DEBUG`, so a Release build has no socket and no debug types. It injects the *same intents a human sends* (`MoveRequest`, `Say`, …) or synthetic input the real UI reacts to (click / drag / keys) — never fabricating server state, so the server validates everything as usual. Built on a `ClientApi` facade (query visible state + issue intents), the seam a future in-game scripting host (Lua) will reuse. Commands: `login`, `goto`, `move`, `say`, `open <admin|bag|doll>`, `click`, `rightclick`, `drag`, `type`, `key`, `screenshot`, `status`, `help`. See `docs/debug-harness.md`. ## Screenshots / recording _Captured by the harness itself, piloting the client — the deliverable dogfooding its own job:_ `login debug` → `open admin` → `screenshot`, then `click 130 135` (first command card) → `screenshot`: **Admin panel opened + captured via the harness:** ![admin panel](https://git.homelab.devncode.it/attachments/1c36789a-ca8d-44e7-a1d1-8302ae649db2) **Clicking the first card prefills `/clearbag ` into the chat (synthetic click):** ![prefill](https://git.homelab.devncode.it/attachments/68c3b94f-e912-4053-b61c-d73da077735b) ## How it was tested - `DebugCommand` parser unit-tested (Client.Core, 7 cases). - Drove it end-to-end against `just dev`: `login debug` (reaches in-world), `open admin` (panel opens), `click 130 135` (prefills `/clearbag ` into chat), `screenshot` (writes a valid 1280×720 PNG) — all `OK`. - Verified a **Release** build contains no `Automation` types / no socket. ## Checklist - [x] `just lint` passes (CSharpier + analyzers, zero warnings) - [x] `just test` is green - [x] The whole solution builds (client and tools included) - [x] Multi-platform preserved (pure .NET / MonoGame, loopback socket; no OS-specific APIs) - [x] Tests added/updated for this change (`DebugCommandTests`) - [x] Linked the related issue (#122) and its Definition of Done is met

hz_admin.png

1 MiB

hz_prefill.png

1 MiB

marco added 1 commit

2026-07-21 23:39:45 +02:00

feat(client): DEBUG-only harness to pilot the client (#122 )

ci / Lint & Test (pull_request) Successful in 1m43s

Details

cbbfd965ce

A loopback TCP control channel (127.0.0.1:5199, newline request->response) compiled
only under #if DEBUG, so a shell or script can drive the running client and capture
screenshots to attach to PRs. Never in a Release build (verified: no Automation
types compiled in).

- Server-authoritative: commands inject the same intents a human sends (MoveRequest,
  Say, ...) or synthetic input the real UI reacts to (click/rightclick/drag/type/key);
  never fabricates server state.
- Built on a ClientApi facade (query visible state + issue intents) — the seam a future
  in-game scripting host (Lua/MoonSharp) will reuse.
- Commands: login, goto, move, say, open <admin|bag|doll>, click, rightclick, drag,
  type, key, screenshot, status, help. Queued off the socket thread, executed on the
  game loop (gestures span frames); screenshots captured after Draw.
- Command parsing is unit-tested (Client.Core). Dev admin allow-list adds 'debug'.
- Docs: docs/debug-harness.md; PR template + CLAUDE.md state the assistant-piloted
  screenshot process.

marco merged commit a21270f74b into main

2026-07-22 06:00:56 +02:00

marco deleted branch feat/debug-harness

2026-07-22 06:00:56 +02:00

marco referenced this pull request from a commit

2026-07-22 06:00:57 +02:00

feat(client): DEBUG-only harness to pilot the client (socket + screenshots) (#123)