Rework core integration: validated capability layer, docs, and session state

2026-09-11 14:09:04 +02:00
parent 2a15f057df
commit e62d3007d8
33 changed files with 1897 additions and 612 deletions
@@ -0,0 +1,101 @@
+# Testing
+
+This document describes the test setup, the run commands, and the known gaps.
+
+## Unit tests
+
+The pure daemon logic has unit tests. The tests cover the ring buffers, the mention helpers, the
+command parser, the trust check, and the pacing range.
+
+```sh
+cd poc
+pnpm test:comm
+```
+
+The file is `poc/src/test-communication.ts`. The tests do not need Discord or Vesktop.
+
+## Type checks
+
+```sh
+cd poc && pnpm check          # daemon and spike code
+cd .. && pnpm testTypes       # Vesktop core
+```
+
+Both commands must pass before a change is complete.
+
+## Build
+
+```sh
+pnpm build
+```
+
+The build writes the application to `dist/`.
+
+## CDP probe
+
+The probe checks the current CDP transport. Start the client with
+`--remote-debugging-port=9222` first.
+
+```sh
+cd poc
+pnpm cdp:probe
+```
+
+A good result shows the Vencord global, the Flux dispatcher, the current user, and one binding
+event.
+
+## Live test setup
+
+The container has no display and no PipeWire. Use a virtual display.
+
+```sh
+# 1. Start a virtual display. On Linux, install Xvfb or extract it locally.
+Xvfb :99 -screen 0 1280x720x24 &
+
+# 2. Start the stock client with a pinned profile and remote debugging.
+DISPLAY=:99 \
+VENCORD_USER_DATA_DIR=~/.config/veskslop \
+electron . --no-sandbox --disable-gpu --disable-dev-shm-usage --remote-debugging-port=9222
+
+# 3. Start the daemon.
+cd poc && pnpm control:bridge
+
+# 4. Check the health endpoint.
+curl http://127.0.0.1:8788/health
+```
+
+Notes:
+
+- `VENCORD_USER_DATA_DIR` pins the Electron profile. The profile holds the client session.
+- Write `{"firstLaunch": false}` to `<DATA_DIR>/state.json` before the first start. This step skips
+  the first-launch window. The `VESKSLOP_HEADLESS=1` flag does the same job when it is in the tree.
+- The container needs `libasound.so.2` for Electron. Extract the library locally when the system
+  package is not available.
+
+## Sanctioned live target
+
+The only permitted live-send target is user **zzib** (`177117296140091393`). Send a test message
+with this command:
+
+```sh
+cd poc
+pnpm poc:dm
+```
+
+## CDP live results
+
+The CDP transport was verified on 2026-09-11:
+
+- `get_state` returned the real account and 7 guilds.
+- `send_dm` delivered a real DM to zzib.
+- The client ran headless under Xvfb.
+- The token was seeded from the token file.
+
+## Known gaps
+
+| Gap | Effect |
+| --- | --- |
+| Mock core is not in the tree. | The daemon tests need the real client. |
+| The trigger event path needs an incoming message. | Use zzib's account for a live test. |
+| `message.read` is cache-only. | A channel that the client never opened returns zero messages. |
+| Voice, audio, and video are not started. | No test coverage. |